@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/data/documents/shared/projectionContentKeys.js

@@ -0,0 +1,262 @@
+import { ContentKeyEnvelopeError, computeDocumentContentKeyTargetHash, DOCUMENT_CONTENT_KEY_WRAP_SUITE, decodeContentKeyEnvelope, unwrapContentKey, wrapContentKey, } from "../../../internal/crypto/index.js";
+import { bytesToBase64 } from "../../../internal/encoding/index.js";
+import { documentContainerProjections } from "../../keyingProjectionVerification/documentContainerProjections.js";
+import { throwKeyingVerificationErrorWithContext } from "../../keyingProjectionVerification/error.js";
+import { assertContainerKekPathCurrent, assertDocumentKekPathsCurrent, } from "./containerKekCurrency.js";
+import { unwrapContainerKekPath, unwrapContainerKekPathWithHistoryFailures, } from "./containerKekPath.js";
+import { ContainerKekHistoryUnavailableError } from "./containerKekPathHistory.js";
+import { deriveDocumentCreateTargets, describeProjectionTargetKek, readLinkedContainerIdsFromDocumentManifest, verifiedDocumentWrapTargets, } from "./projectionTargets.js";
+import { assertEqualBytes, describeDocumentTargetKek, normalizeDocumentKekTargetResponse, sortDocumentTargets, targetEnvelopeReference, } from "./readers.js";
+import { projectionVerificationOptions } from "./types.js";
+function getOnlyDocumentCreateTarget(projection) {
+    const target = deriveDocumentCreateTargets(projection)[0];
+    if (!target) {
+        throw new Error("Document create target is unavailable");
+    }
+    return target;
+}
+export async function wrapDocumentContentKeyForCreate(input) {
+    assertContainerKekPathCurrent(input.projection.containerKeks);
+    const keksByEpochId = await unwrapContainerKekPath({
+        execSql: input.execSql,
+        knownContainerKeks: input.knownContainerKeks,
+        persistVerificationCheckpoints: input.persistVerificationCheckpoints,
+        projection: input.projection,
+        secretKey: input.secretKey,
+        ...projectionVerificationOptions(input),
+    });
+    const target = getOnlyDocumentCreateTarget(input.projection);
+    const targetKek = keksByEpochId.get(target.containerKeyEpochId);
+    if (!targetKek) {
+        throw new Error("Document create target KEK could not be unwrapped");
+    }
+    const wrapped = await wrapContentKey(input.contentKey, targetKek, {
+        kind: "Document",
+        objectId: input.documentId,
+        contentKeyEpoch: input.contentKeyEpoch,
+        containerId: target.containerId,
+        containerKeyEpochId: target.containerKeyEpochId,
+    });
+    return [
+        {
+            ...target,
+            wrappedKey: bytesToBase64(wrapped.ciphertext),
+            wrappingMetadata: {
+                suite: DOCUMENT_CONTENT_KEY_WRAP_SUITE,
+                iv: bytesToBase64(wrapped.iv),
+            },
+        },
+    ];
+}
+export async function unwrapContentKeyTargetForKind(input) {
+    // Reading, not submitting: the suite still binds the envelope to its object
+    // kind, but an unrecognized extra metadata key is ignored rather than making
+    // an otherwise decryptable envelope permanently unreadable. The AEAD tag is
+    // what authenticates the recovered key, bound to the object, content-key
+    // epoch and target it was sealed for. The KEK stays out of the decoder.
+    try {
+        return await unwrapContentKey(decodeContentKeyEnvelope({
+            envelope: input.envelope,
+            kind: input.kind,
+            origin: "stored",
+        }), input.containerKek, {
+            kind: input.kind,
+            objectId: input.objectId,
+            contentKeyEpoch: input.contentKeyEpoch,
+            containerId: input.envelope.containerId,
+            containerKeyEpochId: input.envelope.containerKeyEpochId,
+        });
+    }
+    catch (error) {
+        if (!input.decryptErrorMessage)
+            throw error;
+        // Keep the structural diagnostic; the wrapper only adds which target it
+        // was, which the decoder cannot know.
+        const detail = error instanceof ContentKeyEnvelopeError ? `: ${error.message}` : "";
+        throw new Error(`${input.decryptErrorMessage}${detail}`, { cause: error });
+    }
+}
+export async function unwrapDocumentContentKeyTarget(input) {
+    return unwrapContentKeyTargetForKind({
+        containerKek: input.containerKek,
+        contentKeyEpoch: input.contentKeyEpoch,
+        decryptErrorMessage: `Document content-key target for container ${input.envelope.containerId} at epoch ${input.envelope.containerKeyEpochId} could not be unwrapped`,
+        envelope: input.envelope,
+        kind: "Document",
+        objectId: input.documentId,
+    });
+}
+export class DocumentHistoryUnavailableError extends Error {
+    historyCause;
+    constructor(historyCause) {
+        super(historyCause instanceof Error
+            ? historyCause.message
+            : "Document history key is unavailable");
+        this.historyCause = historyCause;
+        this.name = "DocumentHistoryUnavailableError";
+    }
+}
+/** No verified target or predecessor path can supply this content key. */
+export class DocumentContentKeyUnavailableError extends Error {
+    constructor() {
+        super("Document content key could not be unwrapped");
+        this.name = "DocumentContentKeyUnavailableError";
+    }
+}
+function preferredPredecessorFailure(failures) {
+    return (failures.find((failure) => !(failure instanceof ContainerKekHistoryUnavailableError)) ?? failures[0]);
+}
+function recordPreferredPredecessorFailure(failures, key, failure) {
+    const existing = failures.get(key);
+    const preferred = preferredPredecessorFailure(existing ? [existing, failure] : [failure]);
+    if (preferred)
+        failures.set(key, preferred);
+}
+export async function collectContainerKeksForDocumentSync(input) {
+    const keksByEpochId = new Map();
+    const predecessorFailuresByEpochId = new Map();
+    const unattributedPredecessorFailuresByContainerId = new Map();
+    for (const projection of documentContainerProjections(input.writerProjection)) {
+        let projectionKeks;
+        try {
+            projectionKeks = await unwrapContainerKekPathWithHistoryFailures({
+                execSql: input.execSql,
+                knownContainerKeks: keksByEpochId,
+                persistVerificationCheckpoints: input.persistVerificationCheckpoints,
+                principalPolicyCache: input.principalPolicyCache,
+                projection,
+                secretKey: input.secretKey,
+                verifiedByHash: input.verifiedByHash,
+                ...projectionVerificationOptions(input),
+            });
+        }
+        catch (error) {
+            throwKeyingVerificationErrorWithContext(error, `Document authorizing container KEK path could not be unwrapped for ${describeProjectionTargetKek(projection)}`);
+        }
+        for (const [containerKeyEpochId, failure,] of projectionKeks.predecessorFailuresByEpochId) {
+            recordPreferredPredecessorFailure(predecessorFailuresByEpochId, containerKeyEpochId, failure);
+        }
+        for (const [containerId, failure,] of projectionKeks.unattributedPredecessorFailuresByContainerId) {
+            recordPreferredPredecessorFailure(unattributedPredecessorFailuresByContainerId, containerId, failure);
+        }
+        for (const [containerKeyEpochId, keyMaterial,] of projectionKeks.keksByEpochId) {
+            const existing = keksByEpochId.get(containerKeyEpochId);
+            if (existing) {
+                assertEqualBytes(existing, keyMaterial, "Document writer projection contains conflicting container KEKs");
+                continue;
+            }
+            keksByEpochId.set(containerKeyEpochId, keyMaterial);
+        }
+    }
+    return {
+        keksByEpochId,
+        predecessorFailuresByEpochId,
+        unattributedPredecessorFailuresByContainerId,
+    };
+}
+export async function unwrapDocumentContentKeyFromBundle(bundle, 
+/** The document being read; its wraps must be sealed to it. */
+documentId, containerKeksByEpochId, predecessorFailuresByEpochId = new Map(), unattributedPredecessorFailuresByContainerId = new Map()) {
+    const canonicalTargetHash = await computeDocumentContentKeyTargetHash(sortDocumentTargets(bundle.targets.map(targetEnvelopeReference)));
+    if (canonicalTargetHash !== bundle.targetHash) {
+        throw new Error("Document content-key bundle target hash is not canonical");
+    }
+    if (bundle.documentId !== documentId) {
+        throw new Error("Document content-key bundle names another document");
+    }
+    let contentKey = null;
+    const predecessorFailures = [];
+    for (const envelope of bundle.targets) {
+        const containerKek = containerKeksByEpochId.get(envelope.containerKeyEpochId);
+        if (!containerKek) {
+            const predecessorFailure = predecessorFailuresByEpochId.get(envelope.containerKeyEpochId) ??
+                unattributedPredecessorFailuresByContainerId.get(envelope.containerId);
+            if (predecessorFailure)
+                predecessorFailures.push(predecessorFailure);
+            continue;
+        }
+        const unwrapped = await unwrapDocumentContentKeyTarget({
+            containerKek,
+            contentKeyEpoch: bundle.contentKeyEpoch,
+            documentId,
+            envelope,
+        });
+        if (contentKey) {
+            assertEqualBytes(contentKey, unwrapped, "Document content-key targets unwrap to conflicting keys");
+            continue;
+        }
+        contentKey = unwrapped;
+    }
+    if (!contentKey) {
+        const predecessorFailure = preferredPredecessorFailure(predecessorFailures);
+        if (predecessorFailure !== undefined) {
+            throw new DocumentHistoryUnavailableError(predecessorFailure);
+        }
+        throw new DocumentContentKeyUnavailableError();
+    }
+    if (contentKey.byteLength !== 32) {
+        throw new Error("Document content key must be 32 bytes");
+    }
+    return contentKey;
+}
+export async function unwrapDocumentContentKeyFromWriterProjection(input) {
+    const collectedKeks = await collectContainerKeksForDocumentSync(input);
+    return unwrapDocumentContentKeyFromBundle(input.writerProjection.contentKeyBundle, input.writerProjection.documentId, collectedKeks.keksByEpochId, collectedKeks.predecessorFailuresByEpochId, collectedKeks.unattributedPredecessorFailuresByContainerId);
+}
+/**
+ * Builds the healing bundle for a stale content-key bundle: wraps a FRESH
+ * content key to the projection's CURRENT KEK targets at the next
+ * content-key epoch. A current reader can recover the stale bundle through
+ * the container predecessor chain; the fresh key is still required so a
+ * holder revoked by the container rotation cannot decrypt future updates.
+ * Recovery re-encrypts a full-history snapshot under that fresh key.
+ *
+ * Like every content-key rotation (unlink included), this requires the KEK
+ * of EVERY linked-container target: all envelopes in a bundle must wrap the
+ * same key, so an inaccessible target's envelope can neither be carried
+ * forward (it wraps the old key) nor fabricated. A writer authorized through
+ * only a subset of a multi-container link set fails here with a named target
+ * and leaves the heal to a member who spans all of them.
+ */
+export async function buildRotatedDocumentContentKeyBundle(input) {
+    assertDocumentKekPathsCurrent(input.writerProjection);
+    const { contentKeyBundle, documentKekTargets } = input.writerProjection;
+    // The server list names the linked containers; each envelope's epoch comes
+    // from the verified authorizing-path leaf for that container.
+    const targets = verifiedDocumentWrapTargets({
+        linkedContainerIds: readLinkedContainerIdsFromDocumentManifest(input.writerProjection),
+        serverTargets: normalizeDocumentKekTargetResponse(documentKekTargets),
+        writerProjection: input.writerProjection,
+    });
+    const envelopes = [];
+    const contentKeyEpoch = contentKeyBundle.contentKeyEpoch + 1;
+    for (const target of targets) {
+        const containerKek = input.containerKeksByEpochId.get(target.containerKeyEpochId);
+        if (!containerKek) {
+            throw new Error(`Document content-key re-wrap KEK is unavailable for ${describeDocumentTargetKek(target)}`);
+        }
+        const wrapped = await wrapContentKey(input.contentKey, containerKek, {
+            kind: "Document",
+            objectId: contentKeyBundle.documentId,
+            contentKeyEpoch,
+            containerId: target.containerId,
+            containerKeyEpochId: target.containerKeyEpochId,
+        });
+        envelopes.push({
+            ...target,
+            wrappedKey: bytesToBase64(wrapped.ciphertext),
+            wrappingMetadata: {
+                suite: DOCUMENT_CONTENT_KEY_WRAP_SUITE,
+                iv: bytesToBase64(wrapped.iv),
+            },
+        });
+    }
+    return {
+        contentKeyEpoch,
+        documentId: contentKeyBundle.documentId,
+        linkSetManifestHash: documentKekTargets.linkSetManifestHash,
+        targetHash: documentKekTargets.documentKeyTargetHash,
+        targets: envelopes,
+    };
+}
+//# sourceMappingURL=projectionContentKeys.js.map

package/data/documents/shared/projectionContentKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectionContentKeys.js","sourceRoot":"","sources":["projectionContentKeys.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  ContentKeyEnvelopeError,\n  type ContentKeyEnvelopeKind,\n  computeDocumentContentKeyTargetHash,\n  DOCUMENT_CONTENT_KEY_WRAP_SUITE,\n  decodeContentKeyEnvelope,\n  unwrapContentKey,\n  type VerifiedContainerAccessManifest,\n  wrapContentKey,\n} from \"@tearleads/crypto\";\nimport { bytesToBase64 } from \"@tearleads/encoding\";\nimport type { DocumentContentKeyTargetEnvelope } from \"@tearleads/validators/request\";\nimport type {\n  ContainerWriterProjectionResponse,\n  DocumentContentKeyBundleResponse,\n  DocumentWriterProjectionResponse,\n} from \"@tearleads/validators/response\";\nimport type { PrincipalPolicyCache } from \"../../keyingProjectionVerification\";\nimport { documentContainerProjections } from \"../../keyingProjectionVerification/documentContainerProjections\";\nimport { throwKeyingVerificationErrorWithContext } from \"../../keyingProjectionVerification/error\";\nimport type { ExecSql } from \"../../sqlite/sqlSchema\";\nimport {\n  assertContainerKekPathCurrent,\n  assertDocumentKekPathsCurrent,\n} from \"./containerKekCurrency\";\nimport {\n  unwrapContainerKekPath,\n  unwrapContainerKekPathWithHistoryFailures,\n} from \"./containerKekPath\";\nimport { ContainerKekHistoryUnavailableError } from \"./containerKekPathHistory\";\nimport {\n  deriveDocumentCreateTargets,\n  describeProjectionTargetKek,\n  readLinkedContainerIdsFromDocumentManifest,\n  verifiedDocumentWrapTargets,\n} from \"./projectionTargets\";\nimport {\n  assertEqualBytes,\n  describeDocumentTargetKek,\n  normalizeDocumentKekTargetResponse,\n  sortDocumentTargets,\n  targetEnvelopeReference,\n} from \"./readers\";\nimport type { ProjectionVerificationOptions } from \"./types\";\nimport { projectionVerificationOptions } from \"./types\";\n\nfunction getOnlyDocumentCreateTarget(\n  projection: ContainerWriterProjectionResponse,\n) {\n  const target = deriveDocumentCreateTargets(projection)[0];\n  if (!target) {\n    throw new Error(\"Document create target is unavailable\");\n  }\n  return target;\n}\n\nexport async function wrapDocumentContentKeyForCreate(\n  input: {\n    contentKey: Uint8Array;\n    contentKeyEpoch: number;\n    documentId: string;\n    execSql?: ExecSql | undefined;\n    knownContainerKeks?: ReadonlyMap<string, Uint8Array> | undefined;\n    persistVerificationCheckpoints?: boolean | undefined;\n    projection: ContainerWriterProjectionResponse;\n    secretKey: Uint8Array;\n  } & ProjectionVerificationOptions,\n): Promise<DocumentContentKeyTargetEnvelope[]> {\n  assertContainerKekPathCurrent(input.projection.containerKeks);\n  const keksByEpochId = await unwrapContainerKekPath({\n    execSql: input.execSql,\n    knownContainerKeks: input.knownContainerKeks,\n    persistVerificationCheckpoints: input.persistVerificationCheckpoints,\n    projection: input.projection,\n    secretKey: input.secretKey,\n    ...projectionVerificationOptions(input),\n  });\n  const target = getOnlyDocumentCreateTarget(input.projection);\n  const targetKek = keksByEpochId.get(target.containerKeyEpochId);\n  if (!targetKek) {\n    throw new Error(\"Document create target KEK could not be unwrapped\");\n  }\n\n  const wrapped = await wrapContentKey(input.contentKey, targetKek, {\n    kind: \"Document\",\n    objectId: input.documentId,\n    contentKeyEpoch: input.contentKeyEpoch,\n    containerId: target.containerId,\n    containerKeyEpochId: target.containerKeyEpochId,\n  });\n\n  return [\n    {\n      ...target,\n      wrappedKey: bytesToBase64(wrapped.ciphertext),\n      wrappingMetadata: {\n        suite: DOCUMENT_CONTENT_KEY_WRAP_SUITE,\n        iv: bytesToBase64(wrapped.iv),\n      },\n    },\n  ];\n}\n\nexport async function unwrapContentKeyTargetForKind(input: {\n  containerKek: Uint8Array;\n  /** The content-key epoch of the bundle the envelope was served in. */\n  contentKeyEpoch: number;\n  /** Wraps a decode or decrypt failure with this message. */\n  decryptErrorMessage?: string | undefined;\n  envelope: {\n    containerId: string;\n    containerKeyEpochId: string;\n    wrappedKey: string;\n    wrappingMetadata?: unknown;\n  };\n  kind: ContentKeyEnvelopeKind;\n  /** The document or blob the caller is reading, never read from the bundle. */\n  objectId: string;\n}): Promise<Uint8Array> {\n  // Reading, not submitting: the suite still binds the envelope to its object\n  // kind, but an unrecognized extra metadata key is ignored rather than making\n  // an otherwise decryptable envelope permanently unreadable. The AEAD tag is\n  // what authenticates the recovered key, bound to the object, content-key\n  // epoch and target it was sealed for. The KEK stays out of the decoder.\n  try {\n    return await unwrapContentKey(\n      decodeContentKeyEnvelope({\n        envelope: input.envelope,\n        kind: input.kind,\n        origin: \"stored\",\n      }),\n      input.containerKek,\n      {\n        kind: input.kind,\n        objectId: input.objectId,\n        contentKeyEpoch: input.contentKeyEpoch,\n        containerId: input.envelope.containerId,\n        containerKeyEpochId: input.envelope.containerKeyEpochId,\n      },\n    );\n  } catch (error) {\n    if (!input.decryptErrorMessage) throw error;\n    // Keep the structural diagnostic; the wrapper only adds which target it\n    // was, which the decoder cannot know.\n    const detail =\n      error instanceof ContentKeyEnvelopeError ? `: ${error.message}` : \"\";\n    throw new Error(`${input.decryptErrorMessage}${detail}`, { cause: error });\n  }\n}\n\nexport async function unwrapDocumentContentKeyTarget(input: {\n  containerKek: Uint8Array;\n  contentKeyEpoch: number;\n  documentId: string;\n  envelope: DocumentContentKeyTargetEnvelope;\n}): Promise<Uint8Array> {\n  return unwrapContentKeyTargetForKind({\n    containerKek: input.containerKek,\n    contentKeyEpoch: input.contentKeyEpoch,\n    decryptErrorMessage: `Document content-key target for container ${input.envelope.containerId} at epoch ${input.envelope.containerKeyEpochId} could not be unwrapped`,\n    envelope: input.envelope,\n    kind: \"Document\",\n    objectId: input.documentId,\n  });\n}\n\ninterface CollectedContainerKeks {\n  readonly keksByEpochId: ReadonlyMap<string, Uint8Array>;\n  readonly predecessorFailuresByEpochId: ReadonlyMap<string, Error>;\n  readonly unattributedPredecessorFailuresByContainerId: ReadonlyMap<\n    string,\n    Error\n  >;\n}\n\nexport class DocumentHistoryUnavailableError extends Error {\n  constructor(readonly historyCause: unknown) {\n    super(\n      historyCause instanceof Error\n        ? historyCause.message\n        : \"Document history key is unavailable\",\n    );\n    this.name = \"DocumentHistoryUnavailableError\";\n  }\n}\n\n/** No verified target or predecessor path can supply this content key. */\nexport class DocumentContentKeyUnavailableError extends Error {\n  constructor() {\n    super(\"Document content key could not be unwrapped\");\n    this.name = \"DocumentContentKeyUnavailableError\";\n  }\n}\n\nfunction preferredPredecessorFailure(\n  failures: readonly Error[],\n): Error | undefined {\n  return (\n    failures.find(\n      (failure) => !(failure instanceof ContainerKekHistoryUnavailableError),\n    ) ?? failures[0]\n  );\n}\n\nfunction recordPreferredPredecessorFailure(\n  failures: Map<string, Error>,\n  key: string,\n  failure: Error,\n): void {\n  const existing = failures.get(key);\n  const preferred = preferredPredecessorFailure(\n    existing ? [existing, failure] : [failure],\n  );\n  if (preferred) failures.set(key, preferred);\n}\n\nexport async function collectContainerKeksForDocumentSync(\n  input: {\n    execSql?: ExecSql | undefined;\n    persistVerificationCheckpoints?: boolean | undefined;\n    principalPolicyCache?: PrincipalPolicyCache | undefined;\n    secretKey: Uint8Array;\n    verifiedByHash?: Map<string, VerifiedContainerAccessManifest> | undefined;\n    writerProjection: DocumentWriterProjectionResponse;\n  } & ProjectionVerificationOptions,\n): Promise<CollectedContainerKeks> {\n  const keksByEpochId = new Map<string, Uint8Array>();\n  const predecessorFailuresByEpochId = new Map<string, Error>();\n  const unattributedPredecessorFailuresByContainerId = new Map<string, Error>();\n\n  for (const projection of documentContainerProjections(\n    input.writerProjection,\n  )) {\n    let projectionKeks: Awaited<\n      ReturnType<typeof unwrapContainerKekPathWithHistoryFailures>\n    >;\n    try {\n      projectionKeks = await unwrapContainerKekPathWithHistoryFailures({\n        execSql: input.execSql,\n        knownContainerKeks: keksByEpochId,\n        persistVerificationCheckpoints: input.persistVerificationCheckpoints,\n        principalPolicyCache: input.principalPolicyCache,\n        projection,\n        secretKey: input.secretKey,\n        verifiedByHash: input.verifiedByHash,\n        ...projectionVerificationOptions(input),\n      });\n    } catch (error) {\n      throwKeyingVerificationErrorWithContext(\n        error,\n        `Document authorizing container KEK path could not be unwrapped for ${describeProjectionTargetKek(projection)}`,\n      );\n    }\n    for (const [\n      containerKeyEpochId,\n      failure,\n    ] of projectionKeks.predecessorFailuresByEpochId) {\n      recordPreferredPredecessorFailure(\n        predecessorFailuresByEpochId,\n        containerKeyEpochId,\n        failure,\n      );\n    }\n    for (const [\n      containerId,\n      failure,\n    ] of projectionKeks.unattributedPredecessorFailuresByContainerId) {\n      recordPreferredPredecessorFailure(\n        unattributedPredecessorFailuresByContainerId,\n        containerId,\n        failure,\n      );\n    }\n    for (const [\n      containerKeyEpochId,\n      keyMaterial,\n    ] of projectionKeks.keksByEpochId) {\n      const existing = keksByEpochId.get(containerKeyEpochId);\n      if (existing) {\n        assertEqualBytes(\n          existing,\n          keyMaterial,\n          \"Document writer projection contains conflicting container KEKs\",\n        );\n        continue;\n      }\n      keksByEpochId.set(containerKeyEpochId, keyMaterial);\n    }\n  }\n\n  return {\n    keksByEpochId,\n    predecessorFailuresByEpochId,\n    unattributedPredecessorFailuresByContainerId,\n  };\n}\n\nexport async function unwrapDocumentContentKeyFromBundle(\n  bundle: DocumentContentKeyBundleResponse,\n  /** The document being read; its wraps must be sealed to it. */\n  documentId: string,\n  containerKeksByEpochId: ReadonlyMap<string, Uint8Array>,\n  predecessorFailuresByEpochId: ReadonlyMap<string, Error> = new Map(),\n  unattributedPredecessorFailuresByContainerId: ReadonlyMap<\n    string,\n    Error\n  > = new Map(),\n): Promise<Uint8Array> {\n  const canonicalTargetHash = await computeDocumentContentKeyTargetHash(\n    sortDocumentTargets(bundle.targets.map(targetEnvelopeReference)),\n  );\n  if (canonicalTargetHash !== bundle.targetHash) {\n    throw new Error(\"Document content-key bundle target hash is not canonical\");\n  }\n  if (bundle.documentId !== documentId) {\n    throw new Error(\"Document content-key bundle names another document\");\n  }\n  let contentKey: Uint8Array | null = null;\n  const predecessorFailures: Error[] = [];\n\n  for (const envelope of bundle.targets) {\n    const containerKek = containerKeksByEpochId.get(\n      envelope.containerKeyEpochId,\n    );\n    if (!containerKek) {\n      const predecessorFailure =\n        predecessorFailuresByEpochId.get(envelope.containerKeyEpochId) ??\n        unattributedPredecessorFailuresByContainerId.get(envelope.containerId);\n      if (predecessorFailure) predecessorFailures.push(predecessorFailure);\n      continue;\n    }\n    const unwrapped = await unwrapDocumentContentKeyTarget({\n      containerKek,\n      contentKeyEpoch: bundle.contentKeyEpoch,\n      documentId,\n      envelope,\n    });\n    if (contentKey) {\n      assertEqualBytes(\n        contentKey,\n        unwrapped,\n        \"Document content-key targets unwrap to conflicting keys\",\n      );\n      continue;\n    }\n    contentKey = unwrapped;\n  }\n\n  if (!contentKey) {\n    const predecessorFailure = preferredPredecessorFailure(predecessorFailures);\n    if (predecessorFailure !== undefined) {\n      throw new DocumentHistoryUnavailableError(predecessorFailure);\n    }\n    throw new DocumentContentKeyUnavailableError();\n  }\n  if (contentKey.byteLength !== 32) {\n    throw new Error(\"Document content key must be 32 bytes\");\n  }\n\n  return contentKey;\n}\n\nexport async function unwrapDocumentContentKeyFromWriterProjection(\n  input: {\n    execSql?: ExecSql | undefined;\n    principalPolicyCache?: PrincipalPolicyCache | undefined;\n    secretKey: Uint8Array;\n    verifiedByHash?: Map<string, VerifiedContainerAccessManifest> | undefined;\n    writerProjection: DocumentWriterProjectionResponse;\n  } & ProjectionVerificationOptions,\n): Promise<Uint8Array> {\n  const collectedKeks = await collectContainerKeksForDocumentSync(input);\n\n  return unwrapDocumentContentKeyFromBundle(\n    input.writerProjection.contentKeyBundle,\n    input.writerProjection.documentId,\n    collectedKeks.keksByEpochId,\n    collectedKeks.predecessorFailuresByEpochId,\n    collectedKeks.unattributedPredecessorFailuresByContainerId,\n  );\n}\n\n/**\n * Builds the healing bundle for a stale content-key bundle: wraps a FRESH\n * content key to the projection's CURRENT KEK targets at the next\n * content-key epoch. A current reader can recover the stale bundle through\n * the container predecessor chain; the fresh key is still required so a\n * holder revoked by the container rotation cannot decrypt future updates.\n * Recovery re-encrypts a full-history snapshot under that fresh key.\n *\n * Like every content-key rotation (unlink included), this requires the KEK\n * of EVERY linked-container target: all envelopes in a bundle must wrap the\n * same key, so an inaccessible target's envelope can neither be carried\n * forward (it wraps the old key) nor fabricated. A writer authorized through\n * only a subset of a multi-container link set fails here with a named target\n * and leaves the heal to a member who spans all of them.\n */\nexport async function buildRotatedDocumentContentKeyBundle(input: {\n  containerKeksByEpochId: ReadonlyMap<string, Uint8Array>;\n  contentKey: Uint8Array;\n  writerProjection: DocumentWriterProjectionResponse;\n}): Promise<DocumentContentKeyBundleResponse> {\n  assertDocumentKekPathsCurrent(input.writerProjection);\n  const { contentKeyBundle, documentKekTargets } = input.writerProjection;\n  // The server list names the linked containers; each envelope's epoch comes\n  // from the verified authorizing-path leaf for that container.\n  const targets = verifiedDocumentWrapTargets({\n    linkedContainerIds: readLinkedContainerIdsFromDocumentManifest(\n      input.writerProjection,\n    ),\n    serverTargets: normalizeDocumentKekTargetResponse(documentKekTargets),\n    writerProjection: input.writerProjection,\n  });\n  const envelopes: DocumentContentKeyBundleResponse[\"targets\"] = [];\n  const contentKeyEpoch = contentKeyBundle.contentKeyEpoch + 1;\n\n  for (const target of targets) {\n    const containerKek = input.containerKeksByEpochId.get(\n      target.containerKeyEpochId,\n    );\n    if (!containerKek) {\n      throw new Error(\n        `Document content-key re-wrap KEK is unavailable for ${describeDocumentTargetKek(target)}`,\n      );\n    }\n    const wrapped = await wrapContentKey(input.contentKey, containerKek, {\n      kind: \"Document\",\n      objectId: contentKeyBundle.documentId,\n      contentKeyEpoch,\n      containerId: target.containerId,\n      containerKeyEpochId: target.containerKeyEpochId,\n    });\n    envelopes.push({\n      ...target,\n      wrappedKey: bytesToBase64(wrapped.ciphertext),\n      wrappingMetadata: {\n        suite: DOCUMENT_CONTENT_KEY_WRAP_SUITE,\n        iv: bytesToBase64(wrapped.iv),\n      },\n    });\n  }\n\n  return {\n    contentKeyEpoch,\n    documentId: contentKeyBundle.documentId,\n    linkSetManifestHash: documentKekTargets.linkSetManifestHash,\n    targetHash: documentKekTargets.documentKeyTargetHash,\n    targets: envelopes,\n  };\n}\n"]}

package/data/documents/shared/projectionTargets.d.ts

@@ -0,0 +1,38 @@
+import { type DocumentContentKeyTarget } from "../../../internal/crypto/index.js";
+import type { ContainerManifestRef, DocumentContentKeyTargetEnvelope } from "../../../internal/validators/request/index.js";
+import type { ContainerKeyingPathResponse, DocumentWriterProjectionResponse } from "../../../internal/validators/response/index.js";
+import type { DocumentLinkSetMutationOperation } from "./types.js";
+export declare function deriveDocumentCreateTargets(projection: ContainerKeyingPathResponse): DocumentContentKeyTarget[];
+export declare function mergeTargetEnvelopes(targets: readonly DocumentContentKeyTarget[], envelopes: readonly DocumentContentKeyTargetEnvelope[]): DocumentContentKeyTargetEnvelope[];
+export declare function describeProjectionTargetKek(projection: ContainerKeyingPathResponse): string;
+export declare function deriveDocumentTargetFromProjection(projection: ContainerKeyingPathResponse): DocumentContentKeyTarget;
+export declare function readLinkedContainerIdsFromDocumentManifest(writerProjection: DocumentWriterProjectionResponse): string[];
+/**
+ * The targets a content-key (re)wrap may address. The server's KEK target list
+ * only says which linked containers the bundle must cover; the epoch each
+ * envelope lands on comes from that container's verified authorizing-path
+ * leaf, never from the server row. A listed epoch that is not the linked
+ * container's verified current head — a predecessor a revoked member still
+ * holds, or another container's epoch — therefore fails before any wrap, as
+ * does a container listed twice. A linked container with no authorizing path
+ * is an availability gap, not tampering: its KEK is simply unavailable here.
+ */
+export declare function verifiedDocumentWrapTargets(input: {
+    linkedContainerIds: readonly string[];
+    serverTargets: readonly DocumentContentKeyTarget[];
+    writerProjection: DocumentWriterProjectionResponse;
+}): DocumentContentKeyTarget[];
+export declare function currentDocumentTargets(writerProjection: DocumentWriterProjectionResponse): DocumentContentKeyTarget[];
+/**
+ * Reduce a single container path (root→leaf chain) to {containerId,
+ * manifestHash} references. The server already stores each manifest and resolves
+ * it from its own store, so a write echoes only the hashes instead of
+ * re-embedding the full signed bundles it received in the writer projection.
+ */
+export declare function containerPathRefs(path: ContainerKeyingPathResponse["path"]): ContainerManifestRef[];
+export declare function authorizingContainerPathRefs(writerProjection: DocumentWriterProjectionResponse): ContainerManifestRef[][];
+export declare function authorizingContainerPathRefsForLinkSet(input: {
+    operation: DocumentLinkSetMutationOperation;
+    targetContainerId: string;
+    writerProjection: DocumentWriterProjectionResponse;
+}): ContainerManifestRef[][];

package/data/documents/shared/projectionTargets.js

@@ -0,0 +1,164 @@
+import { KeyingVerificationError, } from "../../../internal/crypto/index.js";
+import { isPlainObject as isPlainRecord } from "../../../internal/validators/isPlainObject.js";
+import { describeDocumentTargetKek, normalizeDocumentKekTargetResponse, readManifestContainerId, serializeCanonical, sortDocumentTargets, targetEnvelopeReference, targetKey, uniqueSortedStrings, } from "./readers.js";
+export function deriveDocumentCreateTargets(projection) {
+    const targetIndex = projection.path.length - 1;
+    const targetManifest = projection.path[targetIndex];
+    if (!targetManifest) {
+        throw new Error("Container writer projection path is empty");
+    }
+    if (readManifestContainerId(targetManifest) !== projection.containerId) {
+        throw new Error("Container writer projection target path is inconsistent");
+    }
+    const targetKek = projection.containerKeks[targetIndex];
+    if (!targetKek) {
+        throw new Error("Container writer projection target KEK is unavailable");
+    }
+    if (targetKek.containerId !== projection.containerId) {
+        throw new Error("Container writer projection target KEK is inconsistent");
+    }
+    if (targetKek.accessManifestHash !== targetManifest.manifestHash) {
+        throw new Error("Container writer projection target KEK is stale");
+    }
+    return [
+        {
+            containerId: targetKek.containerId,
+            containerManifestHash: targetKek.accessManifestHash,
+            containerKeyEpochId: targetKek.containerKeyEpochId,
+            containerKeyEpoch: targetKek.containerKeyEpoch,
+        },
+    ];
+}
+export function mergeTargetEnvelopes(targets, envelopes) {
+    const expectedByKey = new Map(targets.map((target) => [targetKey(target), target]));
+    const envelopeByKey = new Map();
+    for (const envelope of envelopes) {
+        const key = targetKey(envelope);
+        if (!expectedByKey.has(key)) {
+            throw new Error("Document content-key target envelope is unexpected");
+        }
+        if (envelopeByKey.has(key)) {
+            throw new Error("Document content-key target envelope is duplicated");
+        }
+        if (envelope.wrappedKey.length === 0) {
+            throw new Error("Document content-key target envelope is empty");
+        }
+        if (!isPlainRecord(envelope.wrappingMetadata)) {
+            throw new Error("Document content-key target wrapping metadata must be an object");
+        }
+        envelopeByKey.set(key, envelope);
+    }
+    return sortDocumentTargets(targets).map((target) => {
+        const envelope = envelopeByKey.get(targetKey(target));
+        if (!envelope) {
+            throw new Error("Document content-key target envelope is missing");
+        }
+        return envelope;
+    });
+}
+function projectionLeafContainerId(projection) {
+    const leafBundle = projection.path.at(-1);
+    return leafBundle ? readManifestContainerId(leafBundle) : null;
+}
+export function describeProjectionTargetKek(projection) {
+    const targetKek = projection.containerKeks.at(-1);
+    const containerId = projectionLeafContainerId(projection) ??
+        targetKek?.containerId ??
+        projection.containerId;
+    return targetKek
+        ? `container ${containerId} epoch ${targetKek.containerKeyEpochId}`
+        : `container ${containerId}`;
+}
+export function deriveDocumentTargetFromProjection(projection) {
+    const target = deriveDocumentCreateTargets(projection)[0];
+    if (!target) {
+        throw new Error("Document target projection is unavailable");
+    }
+    return target;
+}
+export function readLinkedContainerIdsFromDocumentManifest(writerProjection) {
+    const state = writerProjection.documentManifest.state;
+    const linkedContainerIds = isPlainRecord(state)
+        ? Reflect.get(state, "linkedContainerIds")
+        : undefined;
+    if (!Array.isArray(linkedContainerIds) ||
+        linkedContainerIds.some((containerId) => typeof containerId !== "string" || containerId.length === 0)) {
+        throw new Error("Document link-set state is invalid");
+    }
+    return uniqueSortedStrings(linkedContainerIds);
+}
+/**
+ * The targets a content-key (re)wrap may address. The server's KEK target list
+ * only says which linked containers the bundle must cover; the epoch each
+ * envelope lands on comes from that container's verified authorizing-path
+ * leaf, never from the server row. A listed epoch that is not the linked
+ * container's verified current head — a predecessor a revoked member still
+ * holds, or another container's epoch — therefore fails before any wrap, as
+ * does a container listed twice. A linked container with no authorizing path
+ * is an availability gap, not tampering: its KEK is simply unavailable here.
+ */
+export function verifiedDocumentWrapTargets(input) {
+    const verifiedByKey = new Map();
+    const verifiedContainerIds = new Set();
+    for (const projection of input.writerProjection.authorizingContainerPaths) {
+        const target = deriveDocumentTargetFromProjection(projection);
+        verifiedByKey.set(targetKey(target), target);
+        verifiedContainerIds.add(target.containerId);
+    }
+    const containerIds = input.serverTargets.map((target) => target.containerId);
+    if (new Set(containerIds).size !== containerIds.length) {
+        throw new KeyingVerificationError("duplicate_entry", "Document content-key targets name a linked container more than once");
+    }
+    const linkedContainerIds = uniqueSortedStrings(input.linkedContainerIds);
+    const sortedContainerIds = uniqueSortedStrings(containerIds);
+    if (sortedContainerIds.length !== linkedContainerIds.length ||
+        sortedContainerIds.some((id, index) => id !== linkedContainerIds[index])) {
+        throw new KeyingVerificationError("object_mismatch", "Document content-key targets do not match the linked containers");
+    }
+    return sortDocumentTargets(input.serverTargets.map((target) => {
+        const verified = verifiedByKey.get(targetKey(target));
+        if (verified) {
+            return verified;
+        }
+        if (!verifiedContainerIds.has(target.containerId)) {
+            throw new Error(`Document content-key re-wrap KEK is unavailable for ${describeDocumentTargetKek(target)}`);
+        }
+        throw new KeyingVerificationError("object_mismatch", `Document content-key target is not the verified head of ${describeDocumentTargetKek(target)}`);
+    }));
+}
+export function currentDocumentTargets(writerProjection) {
+    const targets = normalizeDocumentKekTargetResponse(writerProjection.documentKekTargets);
+    const bundleTargets = sortDocumentTargets(writerProjection.contentKeyBundle.targets.map(targetEnvelopeReference));
+    if (serializeCanonical(targets, "KEK targets") !==
+        serializeCanonical(bundleTargets, "content-key targets")) {
+        throw new Error("Document link-set content-key targets mismatch");
+    }
+    return targets;
+}
+/**
+ * Reduce a single container path (root→leaf chain) to {containerId,
+ * manifestHash} references. The server already stores each manifest and resolves
+ * it from its own store, so a write echoes only the hashes instead of
+ * re-embedding the full signed bundles it received in the writer projection.
+ */
+export function containerPathRefs(path) {
+    return path.map((bundle) => {
+        const containerId = readManifestContainerId(bundle);
+        if (!containerId) {
+            throw new Error("Container path manifest is missing a container id");
+        }
+        return { containerId, manifestHash: bundle.manifestHash };
+    });
+}
+export function authorizingContainerPathRefs(writerProjection) {
+    return writerProjection.authorizingContainerPaths.map((projection) => containerPathRefs(projection.path));
+}
+export function authorizingContainerPathRefsForLinkSet(input) {
+    const paths = input.writerProjection.authorizingContainerPaths.filter((projection) => input.operation === "link" ||
+        projectionLeafContainerId(projection) !== input.targetContainerId);
+    if (paths.length === 0) {
+        throw new Error("Document link-set authorizing paths are missing");
+    }
+    return paths.map((projection) => containerPathRefs(projection.path));
+}
+//# sourceMappingURL=projectionTargets.js.map

package/data/documents/shared/projectionTargets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectionTargets.js","sourceRoot":"","sources":["projectionTargets.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type DocumentContentKeyTarget,\n  KeyingVerificationError,\n} from \"@tearleads/crypto\";\nimport { isPlainObject as isPlainRecord } from \"@tearleads/validators/isPlainObject\";\nimport type {\n  ContainerManifestRef,\n  DocumentContentKeyTargetEnvelope,\n} from \"@tearleads/validators/request\";\nimport type {\n  ContainerKeyingPathResponse,\n  DocumentWriterProjectionResponse,\n} from \"@tearleads/validators/response\";\nimport {\n  describeDocumentTargetKek,\n  normalizeDocumentKekTargetResponse,\n  readManifestContainerId,\n  serializeCanonical,\n  sortDocumentTargets,\n  targetEnvelopeReference,\n  targetKey,\n  uniqueSortedStrings,\n} from \"./readers\";\nimport type { DocumentLinkSetMutationOperation } from \"./types\";\n\nexport function deriveDocumentCreateTargets(\n  projection: ContainerKeyingPathResponse,\n): DocumentContentKeyTarget[] {\n  const targetIndex = projection.path.length - 1;\n  const targetManifest = projection.path[targetIndex];\n  if (!targetManifest) {\n    throw new Error(\"Container writer projection path is empty\");\n  }\n\n  if (readManifestContainerId(targetManifest) !== projection.containerId) {\n    throw new Error(\"Container writer projection target path is inconsistent\");\n  }\n\n  const targetKek = projection.containerKeks[targetIndex];\n  if (!targetKek) {\n    throw new Error(\"Container writer projection target KEK is unavailable\");\n  }\n  if (targetKek.containerId !== projection.containerId) {\n    throw new Error(\"Container writer projection target KEK is inconsistent\");\n  }\n  if (targetKek.accessManifestHash !== targetManifest.manifestHash) {\n    throw new Error(\"Container writer projection target KEK is stale\");\n  }\n\n  return [\n    {\n      containerId: targetKek.containerId,\n      containerManifestHash: targetKek.accessManifestHash,\n      containerKeyEpochId: targetKek.containerKeyEpochId,\n      containerKeyEpoch: targetKek.containerKeyEpoch,\n    },\n  ];\n}\n\nexport function mergeTargetEnvelopes(\n  targets: readonly DocumentContentKeyTarget[],\n  envelopes: readonly DocumentContentKeyTargetEnvelope[],\n): DocumentContentKeyTargetEnvelope[] {\n  const expectedByKey = new Map(\n    targets.map((target) => [targetKey(target), target]),\n  );\n  const envelopeByKey = new Map<string, DocumentContentKeyTargetEnvelope>();\n\n  for (const envelope of envelopes) {\n    const key = targetKey(envelope);\n    if (!expectedByKey.has(key)) {\n      throw new Error(\"Document content-key target envelope is unexpected\");\n    }\n    if (envelopeByKey.has(key)) {\n      throw new Error(\"Document content-key target envelope is duplicated\");\n    }\n    if (envelope.wrappedKey.length === 0) {\n      throw new Error(\"Document content-key target envelope is empty\");\n    }\n    if (!isPlainRecord(envelope.wrappingMetadata)) {\n      throw new Error(\n        \"Document content-key target wrapping metadata must be an object\",\n      );\n    }\n    envelopeByKey.set(key, envelope);\n  }\n\n  return sortDocumentTargets(targets).map((target) => {\n    const envelope = envelopeByKey.get(targetKey(target));\n    if (!envelope) {\n      throw new Error(\"Document content-key target envelope is missing\");\n    }\n    return envelope;\n  });\n}\n\nfunction projectionLeafContainerId(\n  projection: ContainerKeyingPathResponse,\n): string | null {\n  const leafBundle = projection.path.at(-1);\n  return leafBundle ? readManifestContainerId(leafBundle) : null;\n}\n\nexport function describeProjectionTargetKek(\n  projection: ContainerKeyingPathResponse,\n): string {\n  const targetKek = projection.containerKeks.at(-1);\n  const containerId =\n    projectionLeafContainerId(projection) ??\n    targetKek?.containerId ??\n    projection.containerId;\n  return targetKek\n    ? `container ${containerId} epoch ${targetKek.containerKeyEpochId}`\n    : `container ${containerId}`;\n}\n\nexport function deriveDocumentTargetFromProjection(\n  projection: ContainerKeyingPathResponse,\n): DocumentContentKeyTarget {\n  const target = deriveDocumentCreateTargets(projection)[0];\n  if (!target) {\n    throw new Error(\"Document target projection is unavailable\");\n  }\n  return target;\n}\n\nexport function readLinkedContainerIdsFromDocumentManifest(\n  writerProjection: DocumentWriterProjectionResponse,\n): string[] {\n  const state = writerProjection.documentManifest.state;\n  const linkedContainerIds = isPlainRecord(state)\n    ? Reflect.get(state, \"linkedContainerIds\")\n    : undefined;\n  if (\n    !Array.isArray(linkedContainerIds) ||\n    linkedContainerIds.some(\n      (containerId) =>\n        typeof containerId !== \"string\" || containerId.length === 0,\n    )\n  ) {\n    throw new Error(\"Document link-set state is invalid\");\n  }\n\n  return uniqueSortedStrings(linkedContainerIds);\n}\n\n/**\n * The targets a content-key (re)wrap may address. The server's KEK target list\n * only says which linked containers the bundle must cover; the epoch each\n * envelope lands on comes from that container's verified authorizing-path\n * leaf, never from the server row. A listed epoch that is not the linked\n * container's verified current head — a predecessor a revoked member still\n * holds, or another container's epoch — therefore fails before any wrap, as\n * does a container listed twice. A linked container with no authorizing path\n * is an availability gap, not tampering: its KEK is simply unavailable here.\n */\nexport function verifiedDocumentWrapTargets(input: {\n  linkedContainerIds: readonly string[];\n  serverTargets: readonly DocumentContentKeyTarget[];\n  writerProjection: DocumentWriterProjectionResponse;\n}): DocumentContentKeyTarget[] {\n  const verifiedByKey = new Map<string, DocumentContentKeyTarget>();\n  const verifiedContainerIds = new Set<string>();\n  for (const projection of input.writerProjection.authorizingContainerPaths) {\n    const target = deriveDocumentTargetFromProjection(projection);\n    verifiedByKey.set(targetKey(target), target);\n    verifiedContainerIds.add(target.containerId);\n  }\n\n  const containerIds = input.serverTargets.map((target) => target.containerId);\n  if (new Set(containerIds).size !== containerIds.length) {\n    throw new KeyingVerificationError(\n      \"duplicate_entry\",\n      \"Document content-key targets name a linked container more than once\",\n    );\n  }\n  const linkedContainerIds = uniqueSortedStrings(input.linkedContainerIds);\n  const sortedContainerIds = uniqueSortedStrings(containerIds);\n  if (\n    sortedContainerIds.length !== linkedContainerIds.length ||\n    sortedContainerIds.some((id, index) => id !== linkedContainerIds[index])\n  ) {\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Document content-key targets do not match the linked containers\",\n    );\n  }\n\n  return sortDocumentTargets(\n    input.serverTargets.map((target) => {\n      const verified = verifiedByKey.get(targetKey(target));\n      if (verified) {\n        return verified;\n      }\n      if (!verifiedContainerIds.has(target.containerId)) {\n        throw new Error(\n          `Document content-key re-wrap KEK is unavailable for ${describeDocumentTargetKek(target)}`,\n        );\n      }\n      throw new KeyingVerificationError(\n        \"object_mismatch\",\n        `Document content-key target is not the verified head of ${describeDocumentTargetKek(target)}`,\n      );\n    }),\n  );\n}\n\nexport function currentDocumentTargets(\n  writerProjection: DocumentWriterProjectionResponse,\n): DocumentContentKeyTarget[] {\n  const targets = normalizeDocumentKekTargetResponse(\n    writerProjection.documentKekTargets,\n  );\n  const bundleTargets = sortDocumentTargets(\n    writerProjection.contentKeyBundle.targets.map(targetEnvelopeReference),\n  );\n\n  if (\n    serializeCanonical(targets, \"KEK targets\") !==\n    serializeCanonical(bundleTargets, \"content-key targets\")\n  ) {\n    throw new Error(\"Document link-set content-key targets mismatch\");\n  }\n\n  return targets;\n}\n\n/**\n * Reduce a single container path (root→leaf chain) to {containerId,\n * manifestHash} references. The server already stores each manifest and resolves\n * it from its own store, so a write echoes only the hashes instead of\n * re-embedding the full signed bundles it received in the writer projection.\n */\nexport function containerPathRefs(\n  path: ContainerKeyingPathResponse[\"path\"],\n): ContainerManifestRef[] {\n  return path.map((bundle) => {\n    const containerId = readManifestContainerId(bundle);\n    if (!containerId) {\n      throw new Error(\"Container path manifest is missing a container id\");\n    }\n    return { containerId, manifestHash: bundle.manifestHash };\n  });\n}\n\nexport function authorizingContainerPathRefs(\n  writerProjection: DocumentWriterProjectionResponse,\n): ContainerManifestRef[][] {\n  return writerProjection.authorizingContainerPaths.map((projection) =>\n    containerPathRefs(projection.path),\n  );\n}\n\nexport function authorizingContainerPathRefsForLinkSet(input: {\n  operation: DocumentLinkSetMutationOperation;\n  targetContainerId: string;\n  writerProjection: DocumentWriterProjectionResponse;\n}): ContainerManifestRef[][] {\n  const paths = input.writerProjection.authorizingContainerPaths.filter(\n    (projection) =>\n      input.operation === \"link\" ||\n      projectionLeafContainerId(projection) !== input.targetContainerId,\n  );\n  if (paths.length === 0) {\n    throw new Error(\"Document link-set authorizing paths are missing\");\n  }\n\n  return paths.map((projection) => containerPathRefs(projection.path));\n}\n"]}

package/data/documents/shared/pullContinuation.d.ts

@@ -0,0 +1,17 @@
+export type DocumentSyncCommitLsnMode = "tracked" | "untracked";
+export interface DocumentSyncPullContinuation {
+    readonly commitLsn: string;
+    readonly commitLsnMode: DocumentSyncCommitLsnMode;
+    readonly cursor: string;
+}
+export declare function documentSyncPullContinuationsEqual(left: DocumentSyncPullContinuation | null | undefined, right: DocumentSyncPullContinuation | null | undefined): boolean;
+/**
+ * Non-null durable value used after the server rejects a cursor. Readers treat
+ * it like any other undecodable continuation and force page-one recovery, but
+ * ordinary saves preserve it until a successful sync settlement explicitly
+ * replaces or clears the continuation.
+ */
+export declare const DOCUMENT_SYNC_PULL_RECOVERY_REQUIRED = "[0,\"recovery-required\"]";
+/** Decode untrusted local state; malformed progress restarts from page one. */
+export declare function deserializeDocumentSyncPullContinuation(value: string | null): DocumentSyncPullContinuation | null;
+export declare function serializeDocumentSyncPullContinuation(continuation: DocumentSyncPullContinuation | null): string | null;

package/data/documents/shared/pullContinuation.js

@@ -0,0 +1,53 @@
+import { isWalLsnString, MAX_DOCUMENT_SYNC_PULL_CURSOR_LENGTH, } from "../../../internal/validators/util/index.js";
+export function documentSyncPullContinuationsEqual(left, right) {
+    if (!left || !right)
+        return left == null && right == null;
+    return (left.commitLsn === right.commitLsn &&
+        left.commitLsnMode === right.commitLsnMode &&
+        left.cursor === right.cursor);
+}
+/**
+ * Non-null durable value used after the server rejects a cursor. Readers treat
+ * it like any other undecodable continuation and force page-one recovery, but
+ * ordinary saves preserve it until a successful sync settlement explicitly
+ * replaces or clears the continuation.
+ */
+export const DOCUMENT_SYNC_PULL_RECOVERY_REQUIRED = '[0,"recovery-required"]';
+function isValidCheckpoint(mode, commitLsn) {
+    return ((mode === "tracked" && commitLsn !== "0/0" && isWalLsnString(commitLsn)) ||
+        (mode === "untracked" && commitLsn === "0/0"));
+}
+/** Decode untrusted local state; malformed progress restarts from page one. */
+export function deserializeDocumentSyncPullContinuation(value) {
+    if (value === null)
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed) || parsed.length !== 4)
+            return null;
+        const [version, commitLsnMode, commitLsn, cursor] = parsed;
+        if (version !== 1 ||
+            !isValidCheckpoint(commitLsnMode, commitLsn) ||
+            typeof commitLsn !== "string" ||
+            typeof cursor !== "string" ||
+            cursor.length === 0 ||
+            cursor.length > MAX_DOCUMENT_SYNC_PULL_CURSOR_LENGTH) {
+            return null;
+        }
+        return { commitLsn, commitLsnMode, cursor };
+    }
+    catch {
+        return null;
+    }
+}
+export function serializeDocumentSyncPullContinuation(continuation) {
+    if (continuation === null)
+        return null;
+    return JSON.stringify([
+        1,
+        continuation.commitLsnMode,
+        continuation.commitLsn,
+        continuation.cursor,
+    ]);
+}
+//# sourceMappingURL=pullContinuation.js.map

package/data/documents/shared/pullContinuation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pullContinuation.js","sourceRoot":"","sources":["pullContinuation.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,oCAAoC,GACrC,MAAM,4BAA4B,CAAC;AAUpC,MAAM,UAAU,kCAAkC,CAChD,IAAqD,EACrD,KAAsD;IAEtD,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC;IAC1D,OAAO,CACL,IAAI,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS;QAClC,IAAI,CAAC,aAAa,KAAK,KAAK,CAAC,aAAa;QAC1C,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,CAC7B,CAAC;AACJ,CAAC;AASD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,yBAAyB,CAAC;AAE9E,SAAS,iBAAiB,CACxB,IAAa,EACb,SAAkB;IAElB,OAAO,CACL,CAAC,IAAI,KAAK,SAAS,IAAI,SAAS,KAAK,KAAK,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC;QACxE,CAAC,IAAI,KAAK,WAAW,IAAI,SAAS,KAAK,KAAK,CAAC,CAC9C,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,uCAAuC,CACrD,KAAoB;IAEpB,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAEhC,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAC/D,MAAM,CAAC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC;QAC3D,IACE,OAAO,KAAK,CAAC;YACb,CAAC,iBAAiB,CAAC,aAAa,EAAE,SAAS,CAAC;YAC5C,OAAO,SAAS,KAAK,QAAQ;YAC7B,OAAO,MAAM,KAAK,QAAQ;YAC1B,MAAM,CAAC,MAAM,KAAK,CAAC;YACnB,MAAM,CAAC,MAAM,GAAG,oCAAoC,EACpD,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,qCAAqC,CACnD,YAAiD;IAEjD,IAAI,YAAY,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,CAAC;QACD,YAAY,CAAC,aAAa;QAC1B,YAAY,CAAC,SAAS;QACtB,YAAY,CAAC,MAAM;KAC4B,CAAC,CAAC;AACrD,CAAC","sourcesContent":["import {\n  isWalLsnString,\n  MAX_DOCUMENT_SYNC_PULL_CURSOR_LENGTH,\n} from \"@tearleads/validators/util\";\n\nexport type DocumentSyncCommitLsnMode = \"tracked\" | \"untracked\";\n\nexport interface DocumentSyncPullContinuation {\n  readonly commitLsn: string;\n  readonly commitLsnMode: DocumentSyncCommitLsnMode;\n  readonly cursor: string;\n}\n\nexport function documentSyncPullContinuationsEqual(\n  left: DocumentSyncPullContinuation | null | undefined,\n  right: DocumentSyncPullContinuation | null | undefined,\n): boolean {\n  if (!left || !right) return left == null && right == null;\n  return (\n    left.commitLsn === right.commitLsn &&\n    left.commitLsnMode === right.commitLsnMode &&\n    left.cursor === right.cursor\n  );\n}\n\ntype PersistedDocumentSyncPullContinuation = readonly [\n  version: 1,\n  commitLsnMode: DocumentSyncCommitLsnMode,\n  commitLsn: string,\n  cursor: string,\n];\n\n/**\n * Non-null durable value used after the server rejects a cursor. Readers treat\n * it like any other undecodable continuation and force page-one recovery, but\n * ordinary saves preserve it until a successful sync settlement explicitly\n * replaces or clears the continuation.\n */\nexport const DOCUMENT_SYNC_PULL_RECOVERY_REQUIRED = '[0,\"recovery-required\"]';\n\nfunction isValidCheckpoint(\n  mode: unknown,\n  commitLsn: unknown,\n): mode is DocumentSyncCommitLsnMode {\n  return (\n    (mode === \"tracked\" && commitLsn !== \"0/0\" && isWalLsnString(commitLsn)) ||\n    (mode === \"untracked\" && commitLsn === \"0/0\")\n  );\n}\n\n/** Decode untrusted local state; malformed progress restarts from page one. */\nexport function deserializeDocumentSyncPullContinuation(\n  value: string | null,\n): DocumentSyncPullContinuation | null {\n  if (value === null) return null;\n\n  try {\n    const parsed: unknown = JSON.parse(value);\n    if (!Array.isArray(parsed) || parsed.length !== 4) return null;\n    const [version, commitLsnMode, commitLsn, cursor] = parsed;\n    if (\n      version !== 1 ||\n      !isValidCheckpoint(commitLsnMode, commitLsn) ||\n      typeof commitLsn !== \"string\" ||\n      typeof cursor !== \"string\" ||\n      cursor.length === 0 ||\n      cursor.length > MAX_DOCUMENT_SYNC_PULL_CURSOR_LENGTH\n    ) {\n      return null;\n    }\n    return { commitLsn, commitLsnMode, cursor };\n  } catch {\n    return null;\n  }\n}\n\nexport function serializeDocumentSyncPullContinuation(\n  continuation: DocumentSyncPullContinuation | null,\n): string | null {\n  if (continuation === null) return null;\n  return JSON.stringify([\n    1,\n    continuation.commitLsnMode,\n    continuation.commitLsn,\n    continuation.cursor,\n  ] satisfies PersistedDocumentSyncPullContinuation);\n}\n"]}