feat(PR27/PR28): on-chain policy anchoring — anchorRef, XRPL NFT revocation, HCS policy anchoring, encrypted mode

PR27: anchorRef + read-only adapters
- Add anchorRef?: string to PolicyGrantLike, CreatePolicyGrantInput, policyGrantForVerificationSchema
- New AnchorRail "xrpl-nft", PolicyAnchorResult, PolicyAnchorSubmitMode types
- resolveXrplDid: did:xrpl DID resolution via account_objects JSON-RPC
- checkXrplNftRevocation: XRPL nft_info RPC — non-existence = revoked
- hederaHcsPolicyAnchor: submit policy document to HCS topic (hash-only default)

PR28: encrypted anchoring + privacy model
- encryptPolicyDocument / decryptPolicyDocument: AES-256-GCM via Web Crypto API
- hederaHcsPolicyAnchor: three submitMode values (hash-only/full-document/encrypted)
- xrplEncryptAndStorePolicyDocument: encrypt + IPFS upload for NFT-backed grants
- InMemoryPolicyCustody: PolicyDocumentCustody for hash-only off-chain storage
- 40 new tests across 5 test files (243 total, 27 files, all passing)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 2 people

src/anchor/custody.ts

@@ -0,0 +1,38 @@
+/**
+ * Policy document custody — in-memory implementation.
+ *
+ * The Service layer (mpcp-policy-authority) is the custodian of full policy documents
+ * when submitMode="hash-only". Auditors retrieve the document from the Service and
+ * verify it against the on-chain policyHash.
+ *
+ * InMemoryPolicyCustody is for development and testing. Production deployments
+ * (mpcp-policy-authority) back this interface with a real database.
+ */
+
+import type { PolicyDocumentCustody } from "./types.js";
+
+/**
+ * In-memory policy document custody store.
+ * Documents are lost when the process exits. Use only for development and testing.
+ */
+export class InMemoryPolicyCustody implements PolicyDocumentCustody {
+  private readonly _docs = new Map<string, object>();
+
+  async store(policyHash: string, document: object): Promise<void> {
+    this._docs.set(policyHash, document);
+  }
+
+  async retrieve(policyHash: string): Promise<object | null> {
+    return this._docs.get(policyHash) ?? null;
+  }
+
+  /** Number of documents currently held. Useful for testing. */
+  get size(): number {
+    return this._docs.size;
+  }
+
+  /** Remove all documents. Useful for test teardown. */
+  clear(): void {
+    this._docs.clear();
+  }
+}

src/anchor/encrypt.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared AES-256-GCM encryption helper for policy document anchoring.
+ * Uses globalThis.crypto.subtle (Node.js 19+ / all modern browsers).
+ * No external dependencies.
+ */
+
+import type { EncryptedPolicyDocument, PolicyAnchorEncryptionOptions } from "./types.js";
+
+/**
+ * Copy a Uint8Array into a fresh ArrayBuffer so Web Crypto types are satisfied.
+ * @types/node types Uint8Array.buffer as ArrayBufferLike (SharedArrayBuffer | ArrayBuffer),
+ * but SubtleCrypto methods require a concrete ArrayBuffer.
+ */
+function toArrayBuffer(src: Uint8Array): ArrayBuffer {
+  return src.buffer.slice(src.byteOffset, src.byteOffset + src.byteLength) as ArrayBuffer;
+}
+
+/**
+ * Encrypt a policy document with AES-256-GCM.
+ *
+ * @param policyDocument - The policy document object to encrypt
+ * @param options - Encryption key (Uint8Array or CryptoKey) and optional IV
+ * @returns EncryptedPolicyDocument with algorithm, base64 IV, and base64 ciphertext
+ */
+export async function encryptPolicyDocument(
+  policyDocument: object,
+  options: PolicyAnchorEncryptionOptions,
+): Promise<EncryptedPolicyDocument> {
+  // Import key if raw bytes provided
+  let cryptoKey: CryptoKey;
+  if (options.key instanceof Uint8Array) {
+    if (options.key.length !== 32) {
+      throw new Error("AES-256 key must be exactly 32 bytes");
+    }
+    cryptoKey = await globalThis.crypto.subtle.importKey(
+      "raw",
+      toArrayBuffer(options.key),
+      { name: "AES-GCM" },
+      false,
+      ["encrypt"],
+    );
+  } else {
+    cryptoKey = options.key;
+  }
+
+  const ivRaw = options.iv ?? globalThis.crypto.getRandomValues(new Uint8Array(12));
+  const iv = toArrayBuffer(ivRaw);
+  if (ivRaw.length !== 12) {
+    throw new Error("AES-GCM IV must be exactly 12 bytes");
+  }
+
+  const plaintext = new TextEncoder().encode(JSON.stringify(policyDocument));
+
+  // AES-GCM encrypt — ciphertext includes the 16-byte authentication tag appended
+  const ciphertextBuffer = await globalThis.crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    cryptoKey,
+    plaintext,
+  );
+
+  return {
+    algorithm: "AES-256-GCM",
+    iv: Buffer.from(ivRaw).toString("base64"),
+    ciphertext: Buffer.from(ciphertextBuffer).toString("base64"),
+  };
+}
+
+/**
+ * Decrypt an EncryptedPolicyDocument produced by encryptPolicyDocument.
+ *
+ * @param encrypted - The encrypted document envelope
+ * @param options - Decryption key (Uint8Array or CryptoKey)
+ * @returns The original policy document object
+ */
+export async function decryptPolicyDocument(
+  encrypted: EncryptedPolicyDocument,
+  options: Pick<PolicyAnchorEncryptionOptions, "key">,
+): Promise<object> {
+  let cryptoKey: CryptoKey;
+  if (options.key instanceof Uint8Array) {
+    if (options.key.length !== 32) {
+      throw new Error("AES-256 key must be exactly 32 bytes");
+    }
+    cryptoKey = await globalThis.crypto.subtle.importKey(
+      "raw",
+      toArrayBuffer(options.key),
+      { name: "AES-GCM" },
+      false,
+      ["decrypt"],
+    );
+  } else {
+    cryptoKey = options.key;
+  }
+
+  const iv = toArrayBuffer(Buffer.from(encrypted.iv, "base64"));
+  const ciphertext = toArrayBuffer(Buffer.from(encrypted.ciphertext, "base64"));
+
+  let plaintext: ArrayBuffer;
+  try {
+    plaintext = await globalThis.crypto.subtle.decrypt(
+      { name: "AES-GCM", iv },
+      cryptoKey,
+      ciphertext,
+    );
+  } catch {
+    throw new Error("decryption_failed: wrong key or corrupted ciphertext");
+  }
+
+  const json = new TextDecoder().decode(plaintext);
+  return JSON.parse(json) as object;
+}

src/anchor/hederaHcsPolicyAnchor.ts

@@ -0,0 +1,163 @@
+/**
+ * Hedera HCS policy document anchor.
+ * Publishes a PolicyGrant's policy document (or its hash) to a Hedera HCS topic
+ * for tamper-evident, third-party-auditable policy trails.
+ *
+ * Default submitMode is "hash-only" — only the policyHash is published.
+ * This is GDPR-safe and sufficient for most audit use cases.
+ *
+ * Environment variables:
+ *   MPCP_HCS_POLICY_TOPIC_ID   — Target HCS topic for policy anchoring
+ *   MPCP_HCS_OPERATOR_ID       — Hedera operator account ID
+ *   MPCP_HCS_OPERATOR_KEY      — Hedera operator private key
+ *   HEDERA_NETWORK             — testnet | mainnet (default: testnet)
+ */
+
+import { createHash } from "node:crypto";
+import type {
+  PolicyAnchorResult,
+  PolicyAnchorSubmitMode,
+  PolicyAnchorEncryptionOptions,
+} from "./types.js";
+import { encryptPolicyDocument } from "./encrypt.js";
+
+// ---------------------------------------------------------------------------
+// HCS message shapes
+// ---------------------------------------------------------------------------
+
+interface HcsPolicyAnchorMessageBase {
+  type: "MPCP:PolicyAnchor:1.0";
+  policyHash: string;
+  anchoredAt: string;
+}
+
+interface HcsHashOnlyMessage extends HcsPolicyAnchorMessageBase {
+  submitMode: "hash-only";
+}
+
+interface HcsFullDocumentMessage extends HcsPolicyAnchorMessageBase {
+  submitMode: "full-document";
+  policyDocument: object;
+}
+
+interface HcsEncryptedMessage extends HcsPolicyAnchorMessageBase {
+  submitMode: "encrypted";
+  encryptedDocument: {
+    algorithm: "AES-256-GCM";
+    iv: string;
+    ciphertext: string;
+  };
+}
+
+type HcsPolicyAnchorMessage =
+  | HcsHashOnlyMessage
+  | HcsFullDocumentMessage
+  | HcsEncryptedMessage;
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Anchor a policy document to Hedera HCS.
+ *
+ * @param policyDocument - The policy document object to anchor
+ * @param options - submitMode (default "hash-only"), encryption, and HCS credentials
+ * @returns PolicyAnchorResult with anchorRef "hcs:{topicId}:{sequenceNumber}"
+ */
+export async function hederaHcsAnchorPolicyDocument(
+  policyDocument: object,
+  options?: {
+    topicId?: string;
+    operatorId?: string;
+    operatorKey?: string;
+    submitMode?: PolicyAnchorSubmitMode;
+    encryption?: PolicyAnchorEncryptionOptions;
+  },
+): Promise<PolicyAnchorResult> {
+  const submitMode: PolicyAnchorSubmitMode = options?.submitMode ?? "hash-only";
+
+  if (submitMode === "encrypted" && !options?.encryption) {
+    throw new Error(
+      "hederaHcsAnchorPolicyDocument: encryption options required when submitMode is 'encrypted'",
+    );
+  }
+
+  const accountId = options?.operatorId ?? process.env.MPCP_HCS_OPERATOR_ID;
+  const privateKeyStr = options?.operatorKey ?? process.env.MPCP_HCS_OPERATOR_KEY;
+  const topicIdStr = options?.topicId ?? process.env.MPCP_HCS_POLICY_TOPIC_ID;
+
+  if (!accountId || !privateKeyStr || !topicIdStr) {
+    throw new Error(
+      "HCS policy anchor requires MPCP_HCS_OPERATOR_ID, MPCP_HCS_OPERATOR_KEY, MPCP_HCS_POLICY_TOPIC_ID",
+    );
+  }
+
+  let sdk: typeof import("@hashgraph/sdk");
+  try {
+    sdk = await import("@hashgraph/sdk");
+  } catch {
+    throw new Error(
+      "Hedera HCS requires @hashgraph/sdk. Install with: npm install @hashgraph/sdk",
+    );
+  }
+  const { Client, TopicMessageSubmitTransaction, PrivateKey, AccountId, TopicId } = sdk;
+
+  // Compute SHA-256 of canonical policy document
+  const canonicalPolicy = JSON.stringify(policyDocument, Object.keys(policyDocument).sort());
+  const policyHash = createHash("sha256").update(canonicalPolicy).digest("hex");
+
+  const anchoredAt = new Date().toISOString();
+
+  // Build message body based on submitMode
+  let message: HcsPolicyAnchorMessage;
+
+  if (submitMode === "hash-only") {
+    message = { type: "MPCP:PolicyAnchor:1.0", policyHash, anchoredAt, submitMode };
+  } else if (submitMode === "full-document") {
+    message = {
+      type: "MPCP:PolicyAnchor:1.0",
+      policyHash,
+      anchoredAt,
+      submitMode,
+      policyDocument,
+    };
+  } else {
+    // encrypted
+    const encryptedDocument = await encryptPolicyDocument(policyDocument, options!.encryption!);
+    message = {
+      type: "MPCP:PolicyAnchor:1.0",
+      policyHash,
+      anchoredAt,
+      submitMode,
+      encryptedDocument,
+    };
+  }
+
+  const messageBytes = new TextEncoder().encode(JSON.stringify(message));
+
+  const network = process.env.HEDERA_NETWORK ?? "testnet";
+  const client = Client.forName(network);
+  client.setOperator(AccountId.fromString(accountId), PrivateKey.fromString(privateKeyStr));
+
+  const tx = new TopicMessageSubmitTransaction()
+    .setTopicId(TopicId.fromString(topicIdStr))
+    .setMessage(messageBytes);
+
+  const txResponse = await tx.execute(client);
+  const receipt = await txResponse.getReceipt(client);
+
+  const sequenceNumber = receipt.topicSequenceNumber?.toString();
+  const consensusTs = receipt.consensusTimestamp;
+  const anchoredAtIso = consensusTs ? new Date(consensusTs.toDate()).toISOString() : anchoredAt;
+
+  client.close();
+
+  return {
+    rail: "hedera-hcs",
+    reference: `hcs:${topicIdStr}:${sequenceNumber ?? "unknown"}`,
+    anchoredAt: anchoredAtIso,
+    policyHash,
+    submitMode,
+  };
+}

src/anchor/index.ts

@@ -4,9 +4,26 @@
  * for public auditability, dispute protection, and replay protection.
  */
 
-export type { AnchorOptions, AnchorResult, AnchorRail } from "./types.js";
+export type {
+  AnchorOptions,
+  AnchorResult,
+  AnchorRail,
+  PolicyAnchorResult,
+  PolicyAnchorSubmitMode,
+  PolicyAnchorEncryptionOptions,
+  EncryptedPolicyDocument,
+  PolicyDocumentIpfsStore,
+  PolicyDocumentCustody,
+} from "./types.js";
 export { mockAnchorIntentHash } from "./mockAnchor.js";
 export {
   hederaHcsAnchorIntentHash,
   verifyHederaHcsAnchor,
 } from "./hederaHcsAnchor.js";
+export { resolveXrplDid } from "./xrplDid.js";
+export { hederaHcsAnchorPolicyDocument } from "./hederaHcsPolicyAnchor.js";
+export { checkXrplNftRevocation } from "./xrplNftRevocation.js";
+export { xrplEncryptAndStorePolicyDocument } from "./xrplPolicyAnchor.js";
+export type { XrplPolicyAnchorPreparation } from "./xrplPolicyAnchor.js";
+export { InMemoryPolicyCustody } from "./custody.js";
+export { encryptPolicyDocument, decryptPolicyDocument } from "./encrypt.js";