@tearleads/client-sdk 0.1.61 → 0.1.63

package/workflows/blobs/hydration/decrypt.js

@@ -0,0 +1,246 @@
+import { blobContentMetadataHash, bytesToHex, CONTENT_RECORD_ENCRYPTION_SUITE, computeBlobAccessManifestHash, computeBlobContentKeyTargetHash, computeContentRecordNonceDomainHash, makeVerifiedBlobKekTargets, verifyWriteHeader, } from "../../../internal/crypto/index.js";
+import { deriveBlobContentRecordKey } from "../../../data/documents/blob/shared/crypto.js";
+import { unwrapBlobContentKey } from "../../../data/documents/blob/shared/projection.js";
+import { parseBlobEncryptedBytes, readBlobKekTarget, readDocumentManifestIdentity, sortBlobTargets, } from "../../../data/documents/blob/shared/readers.js";
+import { assertBlobContentKeyBundleTargetHash } from "../../../data/documents/blob/shared/responses.js";
+import { importContentKeyMaterial } from "../../../data/documents/shared/contentRecordKeys.js";
+import { assertDocumentWriterProjectionConsistent } from "../../../data/documents/shared/projection.js";
+import { asWebCryptoBytes, readWriteHeader, uniqueSortedStrings, } from "../../../data/documents/shared/readers.js";
+import { projectionVerificationOptions } from "../../../data/documents/shared/types.js";
+import { readCanonicalRecord } from "../../../data/keying/canonicalJson.js";
+import { readRecordString, requireProjectionUserKeyResolver, } from "../../../data/keyingProjectionVerification/index.js";
+import { resolveEventContainerPaths } from "../../../data/keyingProjectionVerification/documentDependencyPaths.js";
+import { assertAttachmentBindingVerified } from "../verification/attachmentBindingVerification.js";
+import { assertBlobWrapScopeVerified } from "../verification/verifiedWrapScope.js";
+import { decryptBlobChunks } from "./blobChunkDecryption.js";
+async function assertBlobEncryptionMetadata(input) {
+    const { contentKeyBundle, encrypted, expectedBlobId, organizationId } = input;
+    if (encrypted.blobId !== expectedBlobId ||
+        encrypted.contentRecordId !== expectedBlobId) {
+        throw new Error("Blob encrypted bytes blob id mismatch");
+    }
+    if (encrypted.contentKeyEpoch !== contentKeyBundle.contentKeyEpoch ||
+        contentKeyBundle.blobId !== expectedBlobId) {
+        throw new Error("Blob encrypted bytes content-key bundle mismatch");
+    }
+    await assertBlobContentKeyBundleTargetHash(contentKeyBundle);
+    const expectedNonceDomainHash = await computeContentRecordNonceDomainHash({
+        version: 1,
+        organizationId,
+        objectKind: "blob",
+        objectId: expectedBlobId,
+        contentKeyEpoch: encrypted.contentKeyEpoch,
+        encryptionSuite: CONTENT_RECORD_ENCRYPTION_SUITE,
+        contentRecordId: encrypted.contentRecordId,
+    });
+    if (encrypted.nonceDomainHash !== expectedNonceDomainHash) {
+        throw new Error("Blob encrypted bytes nonce domain mismatch");
+    }
+    const expectedMetadataHash = await blobContentMetadataHash({
+        blobId: expectedBlobId,
+        byteLength: encrypted.byteLength,
+        chunkCount: encrypted.chunkCount,
+        chunkSize: encrypted.chunkSize,
+        contentKeyEpoch: encrypted.contentKeyEpoch,
+    });
+    if (encrypted.metadataHash !== expectedMetadataHash) {
+        throw new Error("Blob encrypted bytes metadata hash mismatch");
+    }
+}
+/** Verifies metadata and authority; the caller must still authenticate ciphertext. */
+export async function prepareDocumentAttachmentBlobDecryption({ binding, encrypted, expectedDocumentId, expectedSlotId, execSql, resolveProjectionUserKey, targetSecretKey, stillCurrent, warmReferencedPrincipalPolicies, writerProjection, }) {
+    const requiredResolveProjectionUserKey = requireProjectionUserKeyResolver(resolveProjectionUserKey, "Document attachment blob decrypt");
+    const verificationOptions = projectionVerificationOptions({
+        execSql,
+        stillCurrent,
+        warmReferencedPrincipalPolicies,
+        resolveProjectionUserKey: requiredResolveProjectionUserKey,
+    });
+    let documentAuthorization;
+    await assertDocumentWriterProjectionConsistent(writerProjection, {
+        allowStaleContentKeyBundle: true,
+        execSql,
+        onVerifiedAuthorization: (authorization) => {
+            documentAuthorization = authorization;
+        },
+        ...verificationOptions,
+    });
+    const { documentId, organizationId } = readDocumentManifestIdentity(writerProjection);
+    await assertBlobEncryptionMetadata({
+        contentKeyBundle: binding.contentKeyBundle,
+        encrypted,
+        expectedBlobId: binding.blobId,
+        organizationId,
+    });
+    await assertAttachmentBindingVerified({
+        authorization: documentAuthorization,
+        binding,
+        expectedDocumentId,
+        expectedSlotId,
+        resolveProjectionUserKey: requiredResolveProjectionUserKey,
+    });
+    await assertBlobWriteHeaderVerified({
+        authorization: documentAuthorization,
+        binding,
+        encrypted,
+        organizationId,
+        resolveProjectionUserKey: requiredResolveProjectionUserKey,
+    });
+    if (!documentAuthorization)
+        throw new Error("Blob document authorization is unavailable");
+    assertBlobWrapScopeVerified({
+        authorization: documentAuthorization,
+        binding,
+        documentId,
+    });
+    const contentKey = await unwrapBlobContentKey({
+        blobId: binding.blobId,
+        contentKeyBundle: binding.contentKeyBundle,
+        documentId,
+        encrypted,
+        execSql,
+        expectedBindingId: binding.bindingId,
+        secretKey: targetSecretKey,
+        ...verificationOptions,
+        writerProjection,
+    });
+    const contentKeyMaterial = await importContentKeyMaterial(contentKey);
+    const recordKey = await deriveBlobContentRecordKey({
+        blobId: binding.blobId,
+        contentKeyEpoch: encrypted.contentKeyEpoch,
+        contentKeyMaterial,
+        contentRecordId: encrypted.contentRecordId,
+        organizationId,
+        usage: "decrypt",
+    });
+    return { contentKey, recordKey, organizationId };
+}
+async function decryptDocumentAttachmentBlobWithKey(input) {
+    const encrypted = parseBlobEncryptedBytes(input.encryptedBytes);
+    const context = await prepareDocumentAttachmentBlobDecryption({
+        ...input,
+        encrypted,
+    });
+    const header = readWriteHeader(input.binding.writeHeader, "Attachment blob write header");
+    const ciphertextHash = bytesToHex(new Uint8Array(await crypto.subtle.digest("SHA-256", asWebCryptoBytes(input.encryptedBytes))));
+    if (header.ciphertextHash !== ciphertextHash)
+        throw new Error("Attachment blob write header does not match ciphertext");
+    const bytes = await decryptBlobChunks({
+        ...context,
+        encrypted,
+        expectedBlobId: input.binding.blobId,
+    });
+    return { bytes, contentKey: context.contentKey };
+}
+export async function decryptDocumentAttachmentBlob(input) {
+    return (await decryptDocumentAttachmentBlobWithKey(input)).bytes;
+}
+function assertStringSetEquals(input) {
+    const actual = uniqueSortedStrings(input.actual);
+    const expected = uniqueSortedStrings(input.expected);
+    if (actual.length !== expected.length ||
+        actual.some((value, index) => value !== expected[index])) {
+        throw new Error(`${input.label} is inconsistent`);
+    }
+}
+async function verifiedBlobKekTargetsForBinding(input) {
+    const { binding, projection } = input;
+    if (!projection) {
+        throw new Error("Attachment binding lacks blob KEK verification material");
+    }
+    const targets = sortBlobTargets(projection.targets.map((target, index) => readBlobKekTarget(target, `Attachment blob KEK target[${index}]`)));
+    const targetHash = await computeBlobContentKeyTargetHash(targets);
+    if (targetHash !== projection.blobKeyTargetHash ||
+        projection.blobId !== binding.blobId) {
+        throw new Error("Attachment blob KEK target hash is inconsistent");
+    }
+    if (input.requireBindingMembership &&
+        (!projection.activeBindingIds.includes(binding.bindingId) ||
+            !targets.some((target) => target.bindingId === binding.bindingId &&
+                target.documentId === attachmentBindingDocumentId(binding)))) {
+        throw new Error("Attachment binding is absent from blob KEK targets");
+    }
+    assertStringSetEquals({
+        actual: projection.linkedContainerManifestHashes,
+        expected: targets.map((target) => target.containerManifestHash),
+        label: "Attachment blob container manifests",
+    });
+    assertStringSetEquals({
+        actual: projection.linkedContainerKeyEpochIds,
+        expected: targets.map((target) => target.containerKeyEpochId),
+        label: "Attachment blob container KEKs",
+    });
+    const accessManifestHash = await computeBlobAccessManifestHash({
+        version: 1,
+        blobId: projection.blobId,
+        organizationId: projection.organizationId,
+        activeBindingIds: projection.activeBindingIds,
+        documentManifestHashes: projection.documentManifestHashes,
+        linkedContainerManifestHashes: projection.linkedContainerManifestHashes,
+        linkedContainerKeyEpochIds: projection.linkedContainerKeyEpochIds,
+        blobKeyTargetHash: projection.blobKeyTargetHash,
+    });
+    if (accessManifestHash !== projection.blobAccessManifestHash) {
+        throw new Error("Attachment blob access manifest hash is inconsistent");
+    }
+    return makeVerifiedBlobKekTargets({ ...projection, targets });
+}
+function attachmentBindingDocumentId(binding) {
+    if (!binding.bindingEvent) {
+        throw new Error("Attachment binding lacks a signed event");
+    }
+    return readRecordString(readCanonicalRecord(binding.bindingEvent.body, "Attachment binding event body"), "documentId", "Attachment binding event body");
+}
+async function assertBlobWriteHeaderVerified(input) {
+    if (!input.authorization || !input.binding.writeHeader) {
+        throw new Error("Attachment blob lacks verified write authority");
+    }
+    const header = readWriteHeader(input.binding.writeHeader, "Attachment blob write header");
+    const writer = await input.resolveProjectionUserKey(header.writerUserId);
+    if (!writer) {
+        throw new Error("Attachment blob writer identity is unavailable");
+    }
+    await verifiedBlobKekTargetsForBinding({
+        binding: input.binding,
+        projection: input.binding.blobKekTargets,
+        requireBindingMembership: true,
+    });
+    const blobKekTargets = await verifiedBlobKekTargetsForBinding({
+        binding: input.binding,
+        projection: input.binding.writeAuthorization,
+        // The signed binding proves which slot exposes the blob now. Writer
+        // authorization describes the older target set committed when the bytes
+        // were written, so a later valid binding need not appear in that set.
+        requireBindingMembership: false,
+    });
+    if (header.metadataHash !== input.encrypted.metadataHash ||
+        header.contentKeyEpoch !== input.encrypted.contentKeyEpoch ||
+        header.contentRecordId !== input.encrypted.contentRecordId ||
+        header.nonceDomainHash !== input.encrypted.nonceDomainHash) {
+        throw new Error("Attachment blob write header does not match ciphertext");
+    }
+    const verified = await verifyWriteHeader({
+        authorizationMembership: "referenced",
+        blobAuthorization: {
+            authorizingContainerPaths: resolveEventContainerPaths({
+                containerPathByManifestHash: input.authorization.containerPathByManifestHash,
+                dependencyManifestHashes: header.dependencyManifestHashes,
+            }).dependencyContainerPaths,
+            blobKekTargets,
+            principalPolicies: input.authorization.principalPolicies,
+        },
+        expectedAccessManifestHash: blobKekTargets.blobAccessManifestHash,
+        expectedObject: {
+            objectKind: "blob",
+            objectId: input.binding.blobId,
+            organizationId: input.organizationId,
+        },
+        expectedTargetHash: blobKekTargets.blobKeyTargetHash,
+        header,
+        writerPublicKey: writer.signingPublicKey,
+    });
+    if (!verified.ok) {
+        throw verified.error;
+    }
+}
+//# sourceMappingURL=decrypt.js.map

package/workflows/blobs/hydration/decrypt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decrypt.js","sourceRoot":"","sources":["decrypt.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  blobContentMetadataHash,\n  bytesToHex,\n  CONTENT_RECORD_ENCRYPTION_SUITE,\n  computeBlobAccessManifestHash,\n  computeBlobContentKeyTargetHash,\n  computeContentRecordNonceDomainHash,\n  makeVerifiedBlobKekTargets,\n  verifyWriteHeader,\n} from \"@tearleads/crypto\";\nimport type { BlobKekTargetsResponse } from \"@tearleads/validators/response\";\nimport type { BlobBytes } from \"../../../data/blobs/blobContracts\";\nimport { deriveBlobContentRecordKey } from \"../../../data/documents/blob/shared/crypto\";\nimport { unwrapBlobContentKey } from \"../../../data/documents/blob/shared/projection\";\nimport {\n  parseBlobEncryptedBytes,\n  readBlobKekTarget,\n  readDocumentManifestIdentity,\n  sortBlobTargets,\n} from \"../../../data/documents/blob/shared/readers\";\nimport { assertBlobContentKeyBundleTargetHash } from \"../../../data/documents/blob/shared/responses\";\nimport type {\n  BlobEncryptedBytesHeader,\n  DecryptDocumentAttachmentBlobInput,\n} from \"../../../data/documents/blob/shared/types\";\nimport { importContentKeyMaterial } from \"../../../data/documents/shared/contentRecordKeys\";\nimport { assertDocumentWriterProjectionConsistent } from \"../../../data/documents/shared/projection\";\nimport {\n  asWebCryptoBytes,\n  readWriteHeader,\n  uniqueSortedStrings,\n} from \"../../../data/documents/shared/readers\";\nimport { projectionVerificationOptions } from \"../../../data/documents/shared/types\";\nimport { readCanonicalRecord } from \"../../../data/keying/canonicalJson\";\nimport type { DocumentWriterProjectionAuthorization } from \"../../../data/keyingProjectionVerification\";\nimport {\n  readRecordString,\n  requireProjectionUserKeyResolver,\n} from \"../../../data/keyingProjectionVerification\";\nimport { resolveEventContainerPaths } from \"../../../data/keyingProjectionVerification/documentDependencyPaths\";\n\nimport { assertAttachmentBindingVerified } from \"../verification/attachmentBindingVerification\";\nimport { assertBlobWrapScopeVerified } from \"../verification/verifiedWrapScope\";\nimport { decryptBlobChunks } from \"./blobChunkDecryption\";\n\nasync function assertBlobEncryptionMetadata(input: {\n  readonly contentKeyBundle: DecryptDocumentAttachmentBlobInput[\"binding\"][\"contentKeyBundle\"];\n  readonly encrypted: BlobEncryptedBytesHeader;\n  readonly expectedBlobId: string;\n  readonly organizationId: string;\n}): Promise<void> {\n  const { contentKeyBundle, encrypted, expectedBlobId, organizationId } = input;\n  if (\n    encrypted.blobId !== expectedBlobId ||\n    encrypted.contentRecordId !== expectedBlobId\n  ) {\n    throw new Error(\"Blob encrypted bytes blob id mismatch\");\n  }\n  if (\n    encrypted.contentKeyEpoch !== contentKeyBundle.contentKeyEpoch ||\n    contentKeyBundle.blobId !== expectedBlobId\n  ) {\n    throw new Error(\"Blob encrypted bytes content-key bundle mismatch\");\n  }\n  await assertBlobContentKeyBundleTargetHash(contentKeyBundle);\n\n  const expectedNonceDomainHash = await computeContentRecordNonceDomainHash({\n    version: 1,\n    organizationId,\n    objectKind: \"blob\",\n    objectId: expectedBlobId,\n    contentKeyEpoch: encrypted.contentKeyEpoch,\n    encryptionSuite: CONTENT_RECORD_ENCRYPTION_SUITE,\n    contentRecordId: encrypted.contentRecordId,\n  });\n  if (encrypted.nonceDomainHash !== expectedNonceDomainHash) {\n    throw new Error(\"Blob encrypted bytes nonce domain mismatch\");\n  }\n  const expectedMetadataHash = await blobContentMetadataHash({\n    blobId: expectedBlobId,\n    byteLength: encrypted.byteLength,\n    chunkCount: encrypted.chunkCount,\n    chunkSize: encrypted.chunkSize,\n    contentKeyEpoch: encrypted.contentKeyEpoch,\n  });\n  if (encrypted.metadataHash !== expectedMetadataHash) {\n    throw new Error(\"Blob encrypted bytes metadata hash mismatch\");\n  }\n}\n\nexport type AttachmentBlobDecryptionInput = Omit<\n  DecryptDocumentAttachmentBlobInput,\n  \"encryptedBytes\"\n> & {\n  encrypted: BlobEncryptedBytesHeader;\n};\n\n/** Verifies metadata and authority; the caller must still authenticate ciphertext. */\nexport async function prepareDocumentAttachmentBlobDecryption({\n  binding,\n  encrypted,\n  expectedDocumentId,\n  expectedSlotId,\n  execSql,\n  resolveProjectionUserKey,\n  targetSecretKey,\n  stillCurrent,\n  warmReferencedPrincipalPolicies,\n  writerProjection,\n}: AttachmentBlobDecryptionInput): Promise<{\n  contentKey: Uint8Array;\n  recordKey: CryptoKey;\n  organizationId: string;\n}> {\n  const requiredResolveProjectionUserKey = requireProjectionUserKeyResolver(\n    resolveProjectionUserKey,\n    \"Document attachment blob decrypt\",\n  );\n  const verificationOptions = projectionVerificationOptions({\n    execSql,\n    stillCurrent,\n    warmReferencedPrincipalPolicies,\n    resolveProjectionUserKey: requiredResolveProjectionUserKey,\n  });\n  let documentAuthorization: DocumentWriterProjectionAuthorization | undefined;\n  await assertDocumentWriterProjectionConsistent(writerProjection, {\n    allowStaleContentKeyBundle: true,\n    execSql,\n    onVerifiedAuthorization: (authorization) => {\n      documentAuthorization = authorization;\n    },\n    ...verificationOptions,\n  });\n  const { documentId, organizationId } =\n    readDocumentManifestIdentity(writerProjection);\n  await assertBlobEncryptionMetadata({\n    contentKeyBundle: binding.contentKeyBundle,\n    encrypted,\n    expectedBlobId: binding.blobId,\n    organizationId,\n  });\n  await assertAttachmentBindingVerified({\n    authorization: documentAuthorization,\n    binding,\n    expectedDocumentId,\n    expectedSlotId,\n    resolveProjectionUserKey: requiredResolveProjectionUserKey,\n  });\n  await assertBlobWriteHeaderVerified({\n    authorization: documentAuthorization,\n    binding,\n    encrypted,\n    organizationId,\n    resolveProjectionUserKey: requiredResolveProjectionUserKey,\n  });\n\n  if (!documentAuthorization)\n    throw new Error(\"Blob document authorization is unavailable\");\n  assertBlobWrapScopeVerified({\n    authorization: documentAuthorization,\n    binding,\n    documentId,\n  });\n  const contentKey = await unwrapBlobContentKey({\n    blobId: binding.blobId,\n    contentKeyBundle: binding.contentKeyBundle,\n    documentId,\n    encrypted,\n    execSql,\n    expectedBindingId: binding.bindingId,\n    secretKey: targetSecretKey,\n    ...verificationOptions,\n    writerProjection,\n  });\n  const contentKeyMaterial = await importContentKeyMaterial(contentKey);\n  const recordKey = await deriveBlobContentRecordKey({\n    blobId: binding.blobId,\n    contentKeyEpoch: encrypted.contentKeyEpoch,\n    contentKeyMaterial,\n    contentRecordId: encrypted.contentRecordId,\n    organizationId,\n    usage: \"decrypt\",\n  });\n  return { contentKey, recordKey, organizationId };\n}\n\nasync function decryptDocumentAttachmentBlobWithKey(\n  input: DecryptDocumentAttachmentBlobInput,\n): Promise<{ bytes: BlobBytes; contentKey: Uint8Array }> {\n  const encrypted = parseBlobEncryptedBytes(input.encryptedBytes);\n  const context = await prepareDocumentAttachmentBlobDecryption({\n    ...input,\n    encrypted,\n  });\n  const header = readWriteHeader(\n    input.binding.writeHeader,\n    \"Attachment blob write header\",\n  );\n  const ciphertextHash = bytesToHex(\n    new Uint8Array(\n      await crypto.subtle.digest(\n        \"SHA-256\",\n        asWebCryptoBytes(input.encryptedBytes),\n      ),\n    ),\n  );\n  if (header.ciphertextHash !== ciphertextHash)\n    throw new Error(\"Attachment blob write header does not match ciphertext\");\n  const bytes = await decryptBlobChunks({\n    ...context,\n    encrypted,\n    expectedBlobId: input.binding.blobId,\n  });\n  return { bytes, contentKey: context.contentKey };\n}\n\nexport async function decryptDocumentAttachmentBlob(\n  input: DecryptDocumentAttachmentBlobInput,\n): Promise<BlobBytes> {\n  return (await decryptDocumentAttachmentBlobWithKey(input)).bytes;\n}\n\nfunction assertStringSetEquals(input: {\n  readonly actual: readonly string[];\n  readonly expected: readonly string[];\n  readonly label: string;\n}): void {\n  const actual = uniqueSortedStrings(input.actual);\n  const expected = uniqueSortedStrings(input.expected);\n  if (\n    actual.length !== expected.length ||\n    actual.some((value, index) => value !== expected[index])\n  ) {\n    throw new Error(`${input.label} is inconsistent`);\n  }\n}\n\nasync function verifiedBlobKekTargetsForBinding(input: {\n  readonly binding: DecryptDocumentAttachmentBlobInput[\"binding\"];\n  readonly requireBindingMembership: boolean;\n  readonly projection: BlobKekTargetsResponse | undefined;\n}) {\n  const { binding, projection } = input;\n  if (!projection) {\n    throw new Error(\"Attachment binding lacks blob KEK verification material\");\n  }\n  const targets = sortBlobTargets(\n    projection.targets.map((target, index) =>\n      readBlobKekTarget(target, `Attachment blob KEK target[${index}]`),\n    ),\n  );\n  const targetHash = await computeBlobContentKeyTargetHash(targets);\n  if (\n    targetHash !== projection.blobKeyTargetHash ||\n    projection.blobId !== binding.blobId\n  ) {\n    throw new Error(\"Attachment blob KEK target hash is inconsistent\");\n  }\n  if (\n    input.requireBindingMembership &&\n    (!projection.activeBindingIds.includes(binding.bindingId) ||\n      !targets.some(\n        (target) =>\n          target.bindingId === binding.bindingId &&\n          target.documentId === attachmentBindingDocumentId(binding),\n      ))\n  ) {\n    throw new Error(\"Attachment binding is absent from blob KEK targets\");\n  }\n  assertStringSetEquals({\n    actual: projection.linkedContainerManifestHashes,\n    expected: targets.map((target) => target.containerManifestHash),\n    label: \"Attachment blob container manifests\",\n  });\n  assertStringSetEquals({\n    actual: projection.linkedContainerKeyEpochIds,\n    expected: targets.map((target) => target.containerKeyEpochId),\n    label: \"Attachment blob container KEKs\",\n  });\n  const accessManifestHash = await computeBlobAccessManifestHash({\n    version: 1,\n    blobId: projection.blobId,\n    organizationId: projection.organizationId,\n    activeBindingIds: projection.activeBindingIds,\n    documentManifestHashes: projection.documentManifestHashes,\n    linkedContainerManifestHashes: projection.linkedContainerManifestHashes,\n    linkedContainerKeyEpochIds: projection.linkedContainerKeyEpochIds,\n    blobKeyTargetHash: projection.blobKeyTargetHash,\n  });\n  if (accessManifestHash !== projection.blobAccessManifestHash) {\n    throw new Error(\"Attachment blob access manifest hash is inconsistent\");\n  }\n  return makeVerifiedBlobKekTargets({ ...projection, targets });\n}\n\nfunction attachmentBindingDocumentId(\n  binding: DecryptDocumentAttachmentBlobInput[\"binding\"],\n): string {\n  if (!binding.bindingEvent) {\n    throw new Error(\"Attachment binding lacks a signed event\");\n  }\n  return readRecordString(\n    readCanonicalRecord(\n      binding.bindingEvent.body,\n      \"Attachment binding event body\",\n    ),\n    \"documentId\",\n    \"Attachment binding event body\",\n  );\n}\n\nasync function assertBlobWriteHeaderVerified(input: {\n  readonly authorization: DocumentWriterProjectionAuthorization | undefined;\n  readonly binding: DecryptDocumentAttachmentBlobInput[\"binding\"];\n  readonly encrypted: BlobEncryptedBytesHeader;\n  readonly organizationId: string;\n  readonly resolveProjectionUserKey: ReturnType<\n    typeof requireProjectionUserKeyResolver\n  >;\n}): Promise<void> {\n  if (!input.authorization || !input.binding.writeHeader) {\n    throw new Error(\"Attachment blob lacks verified write authority\");\n  }\n  const header = readWriteHeader(\n    input.binding.writeHeader,\n    \"Attachment blob write header\",\n  );\n  const writer = await input.resolveProjectionUserKey(header.writerUserId);\n  if (!writer) {\n    throw new Error(\"Attachment blob writer identity is unavailable\");\n  }\n  await verifiedBlobKekTargetsForBinding({\n    binding: input.binding,\n    projection: input.binding.blobKekTargets,\n    requireBindingMembership: true,\n  });\n  const blobKekTargets = await verifiedBlobKekTargetsForBinding({\n    binding: input.binding,\n    projection: input.binding.writeAuthorization,\n    // The signed binding proves which slot exposes the blob now. Writer\n    // authorization describes the older target set committed when the bytes\n    // were written, so a later valid binding need not appear in that set.\n    requireBindingMembership: false,\n  });\n  if (\n    header.metadataHash !== input.encrypted.metadataHash ||\n    header.contentKeyEpoch !== input.encrypted.contentKeyEpoch ||\n    header.contentRecordId !== input.encrypted.contentRecordId ||\n    header.nonceDomainHash !== input.encrypted.nonceDomainHash\n  ) {\n    throw new Error(\"Attachment blob write header does not match ciphertext\");\n  }\n  const verified = await verifyWriteHeader({\n    authorizationMembership: \"referenced\",\n    blobAuthorization: {\n      authorizingContainerPaths: resolveEventContainerPaths({\n        containerPathByManifestHash:\n          input.authorization.containerPathByManifestHash,\n        dependencyManifestHashes: header.dependencyManifestHashes,\n      }).dependencyContainerPaths,\n      blobKekTargets,\n      principalPolicies: input.authorization.principalPolicies,\n    },\n    expectedAccessManifestHash: blobKekTargets.blobAccessManifestHash,\n    expectedObject: {\n      objectKind: \"blob\",\n      objectId: input.binding.blobId,\n      organizationId: input.organizationId,\n    },\n    expectedTargetHash: blobKekTargets.blobKeyTargetHash,\n    header,\n    writerPublicKey: writer.signingPublicKey,\n  });\n  if (!verified.ok) {\n    throw verified.error;\n  }\n}\n"]}

package/workflows/blobs/hydration/hydrate.d.ts

@@ -0,0 +1,56 @@
+import type { BlobBytesResponse, RequestResultOptions } from "../../../internal/api-client/index.js";
+import type { BlobAttachmentSummary, DocumentWriterProjectionResponse, ListDocumentAttachmentsResponse } from "../../../internal/validators/response/index.js";
+import type { BlobBytes } from "../../../data/blobs/blobContracts.js";
+import type { DocumentAttachment } from "../../../data/documents/documentContent.js";
+import type { ProjectionUserKeyResolver, ReferencedPrincipalPolicyWarmer } from "../../../data/keyingProjectionVerification/index.js";
+import type { SecurityIncidentReporter } from "../../../data/shared/securityIncidents.js";
+import type { ExecSql } from "../../../data/sqlite/sqlSchema.js";
+interface DocumentAttachmentHydrationApi {
+    evictDocumentWriterProjection?(documentId: string): void;
+    getBlobBytes(blobId: string, options?: RequestResultOptions): Promise<BlobBytesResponse | null>;
+    getDocumentWriterProjection(documentId: string): Promise<DocumentWriterProjectionResponse | null>;
+    listDocumentAttachments(documentId: string): Promise<ListDocumentAttachmentsResponse | null>;
+}
+interface HydratedDocumentAttachmentBlob {
+    attachment: DocumentAttachment;
+    binding: BlobAttachmentSummary;
+    bytes: BlobBytes;
+    /** Plaintext digest of `bytes`. */
+    contentSha256: string;
+    /**
+     * The served binding is validly signed but its plaintext digest differs
+     * from the digest the document content records for the slot. Set only when
+     * the slot held no local bytes: the bind and the content update carrying
+     * its digest are two server writes, and an uploader lost between them must
+     * not leave the attachment permanently invisible. Never a security incident;
+     * an honest crash window is indistinguishable from a served rollback.
+     */
+    intentMismatch: boolean;
+    storageKey: string;
+}
+interface DocumentAttachmentHydrationContext {
+    apiClient: DocumentAttachmentHydrationApi;
+    documentId: string;
+    execSql: ExecSql;
+    localBlobIdBySlotId?: Readonly<Record<string, string | null | undefined>> | undefined;
+    localStorageKeyBySlotId?: Readonly<Record<string, string | undefined>>;
+    log?: ((message: string) => void) | undefined;
+    logPrefix?: string | undefined;
+    /**
+     * Served bindings already downloaded and refused for a held copy, keyed per
+     * (slot, binding, intent). Populated here; a later pass skips the download
+     * until the binding or the document intent changes.
+     */
+    rejectedServedBindings?: Set<string> | undefined;
+    resolveProjectionUserKey: ProjectionUserKeyResolver;
+    reportSecurityIncident?: SecurityIncidentReporter | undefined;
+    targetSecretKey: Uint8Array;
+    stillCurrent?: (() => boolean) | undefined;
+    warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;
+}
+export declare function hydrateDocumentAttachmentBlobs(input: DocumentAttachmentHydrationContext & {
+    attachments: ReadonlyArray<DocumentAttachment>;
+    /** No binding target remains unchecked or unavailable in this pass. */
+    onBindingsChecked?: () => void;
+}): Promise<HydratedDocumentAttachmentBlob[] | null>;
+export {};

package/workflows/blobs/hydration/hydrate.js

@@ -0,0 +1,190 @@
+import { bytesToHex } from "../../../internal/crypto/index.js";
+import { runBlobTransfer } from "../../../data/blobs/transferPool.js";
+import { attachmentContentSha256 } from "../../../data/documents/attachmentContentIdentity.js";
+import { errorMessage } from "../../../data/shared/errorMessage.js";
+import { createAttachmentDecryptor } from "../verification/attachmentDecryptor.js";
+import { collectHydrationResults } from "./hydrationResults.js";
+import { readAttachmentTransfer } from "./readAttachmentTransfer.js";
+function servedBindingRejectionKey(attachment, binding) {
+    return JSON.stringify([
+        attachment.slotId,
+        binding.bindingId,
+        attachment.contentSha256,
+    ]);
+}
+async function hasExpectedBlobSha256(blob, encryptedBytes) {
+    const blobDigest = new Uint8Array(await crypto.subtle.digest("SHA-256", encryptedBytes));
+    return bytesToHex(blobDigest) === blob.sha256;
+}
+function shouldHydrateAttachment(input) {
+    const slotId = input.attachment.slotId;
+    const localStorageKey = input.localStorageKeyBySlotId?.[slotId];
+    // An empty slot always hydrates: a rejection only ever protected a held
+    // copy, so once that copy is gone the served binding is shown (flagged).
+    if (!localStorageKey) {
+        return true;
+    }
+    if (input.rejectedServedBindings?.has(servedBindingRejectionKey(input.attachment, input.binding))) {
+        return false;
+    }
+    const localBlobId = input.localBlobIdBySlotId?.[slotId];
+    return localBlobId !== null && localBlobId !== input.binding.blobId;
+}
+async function loadDocumentAttachmentBlob(input) {
+    const { apiClient, binding, log } = input;
+    const logPrefix = input.logPrefix ?? "Documents";
+    if (input.stillCurrent?.() === false)
+        return null;
+    input.signal.throwIfAborted();
+    const blob = await apiClient.getBlobBytes(binding.blobId, {
+        signal: input.signal,
+    });
+    if (!blob) {
+        return null;
+    }
+    let encryptedBytes;
+    try {
+        encryptedBytes = await readAttachmentTransfer(blob, input.signal, input.progress);
+    }
+    catch (error) {
+        log?.(`${logPrefix}: blob ${binding.blobId} failed to stream during hydration: ${errorMessage(error)}`);
+        return null;
+    }
+    if (encryptedBytes.byteLength !== blob.byteLength) {
+        log?.(`${logPrefix}: blob ${binding.blobId} byte length mismatch during hydration.`);
+        return null;
+    }
+    if (!(await hasExpectedBlobSha256(blob, encryptedBytes))) {
+        log?.(`${logPrefix}: blob ${binding.blobId} sha256 mismatch during hydration.`);
+        return null;
+    }
+    input.signal.throwIfAborted();
+    return {
+        blobId: binding.blobId,
+        encryptedBytes,
+    };
+}
+async function loadUniqueDocumentAttachmentBlobs(input) {
+    const targetsByBlobId = new Map();
+    for (const target of input.hydrationTargets) {
+        if (!targetsByBlobId.has(target.binding.blobId)) {
+            targetsByBlobId.set(target.binding.blobId, target);
+        }
+    }
+    const loadedBlobs = await collectHydrationResults({
+        ...input,
+        tasks: Array.from(targetsByBlobId.values()).map((target) => ({
+            blobId: target.binding.blobId,
+            run: () => runBlobTransfer(input.apiClient, (signal, progress) => loadDocumentAttachmentBlob({
+                ...input,
+                binding: target.binding,
+                signal,
+                progress,
+            })),
+        })),
+    });
+    return new Map(loadedBlobs.flatMap((loaded) => loaded ? [[loaded.blobId, loaded]] : []));
+}
+function applyLoadedBlobBytesToHydrationTargets(hydrationTargets, loadedBlobsByBlobId) {
+    return hydrationTargets.flatMap((target) => {
+        const loaded = loadedBlobsByBlobId.get(target.binding.blobId);
+        return loaded
+            ? [
+                {
+                    ...target,
+                    encryptedBytes: loaded.encryptedBytes,
+                },
+            ]
+            : [];
+    });
+}
+async function decryptLoadedDocumentAttachmentBlob(input) {
+    const bytes = await input.decryptAttachment({
+        binding: input.loaded.binding,
+        encryptedBytes: input.loaded.encryptedBytes,
+        expectedDocumentId: input.documentId,
+        expectedSlotId: input.loaded.attachment.slotId,
+        execSql: input.execSql,
+        resolveProjectionUserKey: input.resolveProjectionUserKey,
+        targetSecretKey: input.targetSecretKey,
+        stillCurrent: input.stillCurrent,
+        warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,
+        writerProjection: input.writerProjection,
+    });
+    const { attachment, binding } = input.loaded;
+    const contentSha256 = await attachmentContentSha256(bytes);
+    const intentMismatch = contentSha256 !== attachment.contentSha256;
+    const logPrefix = input.logPrefix ?? "Documents";
+    if (intentMismatch && input.localStorageKeyBySlotId?.[attachment.slotId]) {
+        // Never replace a held copy with bytes the document does not record.
+        input.rejectedServedBindings?.add(servedBindingRejectionKey(attachment, binding));
+        input.log?.(`${logPrefix}: served attachment bytes differ from the current document content; keeping the held copy.`);
+        return null;
+    }
+    if (intentMismatch) {
+        input.log?.(`${logPrefix}: served attachment bytes differ from the current document content; showing them flagged.`);
+    }
+    return {
+        attachment,
+        binding,
+        bytes,
+        contentSha256,
+        intentMismatch,
+        storageKey: `blob-${binding.blobId}`,
+    };
+}
+export async function hydrateDocumentAttachmentBlobs(input) {
+    const attachmentBindings = await input.apiClient.listDocumentAttachments(input.documentId);
+    if (!attachmentBindings) {
+        return null;
+    }
+    const bindingBySlotId = new Map(attachmentBindings.map((binding) => [binding.slotId, binding]));
+    const hydrationTargets = input.attachments.flatMap((attachment) => {
+        const binding = bindingBySlotId.get(attachment.slotId);
+        return binding &&
+            shouldHydrateAttachment({
+                attachment,
+                binding,
+                localBlobIdBySlotId: input.localBlobIdBySlotId,
+                localStorageKeyBySlotId: input.localStorageKeyBySlotId,
+                rejectedServedBindings: input.rejectedServedBindings,
+            })
+            ? [{ attachment, binding }]
+            : [];
+    });
+    if (hydrationTargets.length === 0) {
+        input.onBindingsChecked?.();
+        return [];
+    }
+    const loadedBlobs = applyLoadedBlobBytesToHydrationTargets(hydrationTargets, await loadUniqueDocumentAttachmentBlobs({
+        ...input,
+        hydrationTargets,
+    }));
+    if (loadedBlobs.length === 0) {
+        return [];
+    }
+    const writerProjection = await input.apiClient.getDocumentWriterProjection(input.documentId);
+    if (!writerProjection) {
+        const logPrefix = input.logPrefix ?? "Documents";
+        input.log?.(`${logPrefix}: cannot hydrate attachments for document ${input.documentId} without a writer projection.`);
+        return [];
+    }
+    const decryptAttachment = createAttachmentDecryptor(input.apiClient, input.documentId);
+    const hydrated = await collectHydrationResults({
+        ...input,
+        tasks: loadedBlobs.map((loaded) => ({
+            blobId: loaded.binding.blobId,
+            run: () => decryptLoadedDocumentAttachmentBlob({
+                ...input,
+                decryptAttachment,
+                loaded,
+                writerProjection,
+            }),
+        })),
+    });
+    const complete = hydrated.filter((item) => item !== null);
+    if (complete.length === hydrationTargets.length)
+        input.onBindingsChecked?.();
+    return complete;
+}
+//# sourceMappingURL=hydrate.js.map

package/workflows/blobs/hydration/hydrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate.js","sourceRoot":"","sources":["hydrate.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  BlobBytesResponse,\n  RequestResultOptions,\n} from \"@tearleads/api-client\";\nimport { bytesToHex } from \"@tearleads/crypto\";\nimport type {\n  BlobAttachmentSummary,\n  DocumentWriterProjectionResponse,\n  ListDocumentAttachmentsResponse,\n} from \"@tearleads/validators/response\";\nimport type { BlobBytes } from \"../../../data/blobs/blobContracts\";\nimport { runBlobTransfer } from \"../../../data/blobs/transferPool\";\nimport { attachmentContentSha256 } from \"../../../data/documents/attachmentContentIdentity\";\nimport type { DocumentAttachment } from \"../../../data/documents/documentContent\";\nimport type {\n  ProjectionUserKeyResolver,\n  ReferencedPrincipalPolicyWarmer,\n} from \"../../../data/keyingProjectionVerification\";\nimport { errorMessage } from \"../../../data/shared/errorMessage\";\nimport type { SecurityIncidentReporter } from \"../../../data/shared/securityIncidents\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\nimport { createAttachmentDecryptor } from \"../verification/attachmentDecryptor\";\nimport { collectHydrationResults } from \"./hydrationResults\";\nimport { readAttachmentTransfer } from \"./readAttachmentTransfer\";\n\ninterface DocumentAttachmentHydrationApi {\n  evictDocumentWriterProjection?(documentId: string): void;\n  getBlobBytes(\n    blobId: string,\n    options?: RequestResultOptions,\n  ): Promise<BlobBytesResponse | null>;\n  getDocumentWriterProjection(\n    documentId: string,\n  ): Promise<DocumentWriterProjectionResponse | null>;\n  listDocumentAttachments(\n    documentId: string,\n  ): Promise<ListDocumentAttachmentsResponse | null>;\n}\n\ninterface HydratedDocumentAttachmentBlob {\n  attachment: DocumentAttachment;\n  binding: BlobAttachmentSummary;\n  bytes: BlobBytes;\n  /** Plaintext digest of `bytes`. */\n  contentSha256: string;\n  /**\n   * The served binding is validly signed but its plaintext digest differs\n   * from the digest the document content records for the slot. Set only when\n   * the slot held no local bytes: the bind and the content update carrying\n   * its digest are two server writes, and an uploader lost between them must\n   * not leave the attachment permanently invisible. Never a security incident;\n   * an honest crash window is indistinguishable from a served rollback.\n   */\n  intentMismatch: boolean;\n  storageKey: string;\n}\n\ninterface DocumentAttachmentHydrationContext {\n  apiClient: DocumentAttachmentHydrationApi;\n  documentId: string;\n  execSql: ExecSql;\n  localBlobIdBySlotId?:\n    | Readonly<Record<string, string | null | undefined>>\n    | undefined;\n  localStorageKeyBySlotId?: Readonly<Record<string, string | undefined>>;\n  log?: ((message: string) => void) | undefined;\n  logPrefix?: string | undefined;\n  /**\n   * Served bindings already downloaded and refused for a held copy, keyed per\n   * (slot, binding, intent). Populated here; a later pass skips the download\n   * until the binding or the document intent changes.\n   */\n  rejectedServedBindings?: Set<string> | undefined;\n  resolveProjectionUserKey: ProjectionUserKeyResolver;\n  reportSecurityIncident?: SecurityIncidentReporter | undefined;\n  targetSecretKey: Uint8Array;\n  stillCurrent?: (() => boolean) | undefined;\n  warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;\n}\n\nfunction servedBindingRejectionKey(\n  attachment: DocumentAttachment,\n  binding: BlobAttachmentSummary,\n): string {\n  return JSON.stringify([\n    attachment.slotId,\n    binding.bindingId,\n    attachment.contentSha256,\n  ]);\n}\n\ninterface DocumentAttachmentHydrationTarget {\n  attachment: DocumentAttachment;\n  binding: BlobAttachmentSummary;\n}\n\ninterface LoadedDocumentAttachmentBlob\n  extends DocumentAttachmentHydrationTarget {\n  encryptedBytes: Uint8Array<ArrayBuffer>;\n}\n\ninterface LoadedDocumentAttachmentBlobBytes {\n  blobId: string;\n  encryptedBytes: Uint8Array<ArrayBuffer>;\n}\n\nasync function hasExpectedBlobSha256(\n  blob: BlobBytesResponse,\n  encryptedBytes: Uint8Array<ArrayBuffer>,\n): Promise<boolean> {\n  const blobDigest = new Uint8Array(\n    await crypto.subtle.digest(\"SHA-256\", encryptedBytes),\n  );\n\n  return bytesToHex(blobDigest) === blob.sha256;\n}\n\nfunction shouldHydrateAttachment(input: {\n  attachment: DocumentAttachment;\n  binding: BlobAttachmentSummary;\n  localBlobIdBySlotId:\n    | Readonly<Record<string, string | null | undefined>>\n    | undefined;\n  localStorageKeyBySlotId:\n    | Readonly<Record<string, string | undefined>>\n    | undefined;\n  rejectedServedBindings: ReadonlySet<string> | undefined;\n}): boolean {\n  const slotId = input.attachment.slotId;\n  const localStorageKey = input.localStorageKeyBySlotId?.[slotId];\n  // An empty slot always hydrates: a rejection only ever protected a held\n  // copy, so once that copy is gone the served binding is shown (flagged).\n  if (!localStorageKey) {\n    return true;\n  }\n  if (\n    input.rejectedServedBindings?.has(\n      servedBindingRejectionKey(input.attachment, input.binding),\n    )\n  ) {\n    return false;\n  }\n\n  const localBlobId = input.localBlobIdBySlotId?.[slotId];\n  return localBlobId !== null && localBlobId !== input.binding.blobId;\n}\n\nasync function loadDocumentAttachmentBlob(\n  input: DocumentAttachmentHydrationContext & {\n    binding: BlobAttachmentSummary;\n    signal: AbortSignal;\n    progress: () => void;\n  },\n): Promise<LoadedDocumentAttachmentBlobBytes | null> {\n  const { apiClient, binding, log } = input;\n  const logPrefix = input.logPrefix ?? \"Documents\";\n  if (input.stillCurrent?.() === false) return null;\n  input.signal.throwIfAborted();\n  const blob = await apiClient.getBlobBytes(binding.blobId, {\n    signal: input.signal,\n  });\n  if (!blob) {\n    return null;\n  }\n\n  let encryptedBytes: Uint8Array<ArrayBuffer>;\n  try {\n    encryptedBytes = await readAttachmentTransfer(\n      blob,\n      input.signal,\n      input.progress,\n    );\n  } catch (error) {\n    log?.(\n      `${logPrefix}: blob ${binding.blobId} failed to stream during hydration: ${errorMessage(\n        error,\n      )}`,\n    );\n    return null;\n  }\n\n  if (encryptedBytes.byteLength !== blob.byteLength) {\n    log?.(\n      `${logPrefix}: blob ${binding.blobId} byte length mismatch during hydration.`,\n    );\n    return null;\n  }\n\n  if (!(await hasExpectedBlobSha256(blob, encryptedBytes))) {\n    log?.(\n      `${logPrefix}: blob ${binding.blobId} sha256 mismatch during hydration.`,\n    );\n    return null;\n  }\n\n  input.signal.throwIfAborted();\n  return {\n    blobId: binding.blobId,\n    encryptedBytes,\n  };\n}\n\nasync function loadUniqueDocumentAttachmentBlobs(\n  input: DocumentAttachmentHydrationContext & {\n    hydrationTargets: ReadonlyArray<DocumentAttachmentHydrationTarget>;\n  },\n): Promise<ReadonlyMap<string, LoadedDocumentAttachmentBlobBytes>> {\n  const targetsByBlobId = new Map<string, DocumentAttachmentHydrationTarget>();\n  for (const target of input.hydrationTargets) {\n    if (!targetsByBlobId.has(target.binding.blobId)) {\n      targetsByBlobId.set(target.binding.blobId, target);\n    }\n  }\n\n  const loadedBlobs = await collectHydrationResults({\n    ...input,\n    tasks: Array.from(targetsByBlobId.values()).map((target) => ({\n      blobId: target.binding.blobId,\n      run: () =>\n        runBlobTransfer(input.apiClient, (signal, progress) =>\n          loadDocumentAttachmentBlob({\n            ...input,\n            binding: target.binding,\n            signal,\n            progress,\n          }),\n        ),\n    })),\n  });\n\n  return new Map(\n    loadedBlobs.flatMap((loaded) =>\n      loaded ? [[loaded.blobId, loaded] as const] : [],\n    ),\n  );\n}\n\nfunction applyLoadedBlobBytesToHydrationTargets(\n  hydrationTargets: ReadonlyArray<DocumentAttachmentHydrationTarget>,\n  loadedBlobsByBlobId: ReadonlyMap<string, LoadedDocumentAttachmentBlobBytes>,\n): LoadedDocumentAttachmentBlob[] {\n  return hydrationTargets.flatMap((target) => {\n    const loaded = loadedBlobsByBlobId.get(target.binding.blobId);\n    return loaded\n      ? [\n          {\n            ...target,\n            encryptedBytes: loaded.encryptedBytes,\n          },\n        ]\n      : [];\n  });\n}\n\nasync function decryptLoadedDocumentAttachmentBlob(\n  input: DocumentAttachmentHydrationContext & {\n    loaded: LoadedDocumentAttachmentBlob;\n    decryptAttachment: ReturnType<typeof createAttachmentDecryptor>;\n    writerProjection: DocumentWriterProjectionResponse;\n  },\n): Promise<HydratedDocumentAttachmentBlob | null> {\n  const bytes = await input.decryptAttachment({\n    binding: input.loaded.binding,\n    encryptedBytes: input.loaded.encryptedBytes,\n    expectedDocumentId: input.documentId,\n    expectedSlotId: input.loaded.attachment.slotId,\n    execSql: input.execSql,\n    resolveProjectionUserKey: input.resolveProjectionUserKey,\n    targetSecretKey: input.targetSecretKey,\n    stillCurrent: input.stillCurrent,\n    warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,\n    writerProjection: input.writerProjection,\n  });\n\n  const { attachment, binding } = input.loaded;\n  const contentSha256 = await attachmentContentSha256(bytes);\n  const intentMismatch = contentSha256 !== attachment.contentSha256;\n  const logPrefix = input.logPrefix ?? \"Documents\";\n  if (intentMismatch && input.localStorageKeyBySlotId?.[attachment.slotId]) {\n    // Never replace a held copy with bytes the document does not record.\n    input.rejectedServedBindings?.add(\n      servedBindingRejectionKey(attachment, binding),\n    );\n    input.log?.(\n      `${logPrefix}: served attachment bytes differ from the current document content; keeping the held copy.`,\n    );\n    return null;\n  }\n  if (intentMismatch) {\n    input.log?.(\n      `${logPrefix}: served attachment bytes differ from the current document content; showing them flagged.`,\n    );\n  }\n  return {\n    attachment,\n    binding,\n    bytes,\n    contentSha256,\n    intentMismatch,\n    storageKey: `blob-${binding.blobId}`,\n  };\n}\n\nexport async function hydrateDocumentAttachmentBlobs(\n  input: DocumentAttachmentHydrationContext & {\n    attachments: ReadonlyArray<DocumentAttachment>;\n    /** No binding target remains unchecked or unavailable in this pass. */\n    onBindingsChecked?: () => void;\n  },\n): Promise<HydratedDocumentAttachmentBlob[] | null> {\n  const attachmentBindings = await input.apiClient.listDocumentAttachments(\n    input.documentId,\n  );\n  if (!attachmentBindings) {\n    return null;\n  }\n\n  const bindingBySlotId = new Map(\n    attachmentBindings.map((binding) => [binding.slotId, binding]),\n  );\n  const hydrationTargets: DocumentAttachmentHydrationTarget[] =\n    input.attachments.flatMap((attachment) => {\n      const binding = bindingBySlotId.get(attachment.slotId);\n      return binding &&\n        shouldHydrateAttachment({\n          attachment,\n          binding,\n          localBlobIdBySlotId: input.localBlobIdBySlotId,\n          localStorageKeyBySlotId: input.localStorageKeyBySlotId,\n          rejectedServedBindings: input.rejectedServedBindings,\n        })\n        ? [{ attachment, binding }]\n        : [];\n    });\n  if (hydrationTargets.length === 0) {\n    input.onBindingsChecked?.();\n    return [];\n  }\n\n  const loadedBlobs = applyLoadedBlobBytesToHydrationTargets(\n    hydrationTargets,\n    await loadUniqueDocumentAttachmentBlobs({\n      ...input,\n      hydrationTargets,\n    }),\n  );\n  if (loadedBlobs.length === 0) {\n    return [];\n  }\n\n  const writerProjection = await input.apiClient.getDocumentWriterProjection(\n    input.documentId,\n  );\n  if (!writerProjection) {\n    const logPrefix = input.logPrefix ?? \"Documents\";\n    input.log?.(\n      `${logPrefix}: cannot hydrate attachments for document ${input.documentId} without a writer projection.`,\n    );\n    return [];\n  }\n\n  const decryptAttachment = createAttachmentDecryptor(\n    input.apiClient,\n    input.documentId,\n  );\n  const hydrated = await collectHydrationResults({\n    ...input,\n    tasks: loadedBlobs.map((loaded) => ({\n      blobId: loaded.binding.blobId,\n      run: () =>\n        decryptLoadedDocumentAttachmentBlob({\n          ...input,\n          decryptAttachment,\n          loaded,\n          writerProjection,\n        }),\n    })),\n  });\n  const complete = hydrated.filter(\n    (item): item is HydratedDocumentAttachmentBlob => item !== null,\n  );\n  if (complete.length === hydrationTargets.length) input.onBindingsChecked?.();\n  return complete;\n}\n"]}

package/workflows/blobs/hydration/hydrationResults.js

@@ -0,0 +1,23 @@
+import { reportKeyingVerificationErrorInCauseChain, rethrowDatabaseUnavailableError, } from "../../../data/keyingProjectionVerification/error.js";
+import { rethrowProjectionVerificationCancelled } from "../../../data/keyingProjectionVerification/types.js";
+/** One unavailable or invalid attachment does not suppress independent successes. */
+export async function collectHydrationResults(input) {
+    const outcomes = await Promise.allSettled(input.tasks.map((task) => task.run()));
+    const values = [];
+    for (const [index, outcome] of outcomes.entries()) {
+        if (outcome.status === "fulfilled") {
+            values.push(outcome.value);
+            continue;
+        }
+        rethrowDatabaseUnavailableError(outcome.reason);
+        rethrowProjectionVerificationCancelled(outcome.reason);
+        await reportKeyingVerificationErrorInCauseChain(outcome.reason, input.reportSecurityIncident, {
+            operation: "hydrate_attachment",
+            objectKind: "blob",
+            objectId: input.tasks[index]?.blobId ?? null,
+        });
+        input.log?.("Documents: an attachment is unavailable during hydration.");
+    }
+    return values;
+}
+//# sourceMappingURL=hydrationResults.js.map

package/workflows/blobs/hydration/hydrationResults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrationResults.js","sourceRoot":"","sources":["hydrationResults.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yCAAyC,EACzC,+BAA+B,GAChC,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAAE,sCAAsC,EAAE,MAAM,kDAAkD,CAAC;AAG1G,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAI,KAIhD;IACC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,UAAU,CACvC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CACtC,CAAC;IACF,MAAM,MAAM,GAAQ,EAAE,CAAC;IACvB,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QAClD,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YACnC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,+BAA+B,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAChD,sCAAsC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACvD,MAAM,yCAAyC,CAC7C,OAAO,CAAC,MAAM,EACd,KAAK,CAAC,sBAAsB,EAC5B;YACE,SAAS,EAAE,oBAAoB;YAC/B,UAAU,EAAE,MAAM;YAClB,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,IAAI;SAC7C,CACF,CAAC;QACF,KAAK,CAAC,GAAG,EAAE,CAAC,2DAA2D,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import {\n  reportKeyingVerificationErrorInCauseChain,\n  rethrowDatabaseUnavailableError,\n} from \"../../../data/keyingProjectionVerification/error\";\nimport { rethrowProjectionVerificationCancelled } from \"../../../data/keyingProjectionVerification/types\";\nimport type { SecurityIncidentReporter } from \"../../../data/shared/securityIncidents\";\n\n/** One unavailable or invalid attachment does not suppress independent successes. */\nexport async function collectHydrationResults<T>(input: {\n  tasks: readonly { blobId: string; run: () => Promise<T> }[];\n  reportSecurityIncident?: SecurityIncidentReporter | undefined;\n  log?: ((message: string) => void) | undefined;\n}): Promise<T[]> {\n  const outcomes = await Promise.allSettled(\n    input.tasks.map((task) => task.run()),\n  );\n  const values: T[] = [];\n  for (const [index, outcome] of outcomes.entries()) {\n    if (outcome.status === \"fulfilled\") {\n      values.push(outcome.value);\n      continue;\n    }\n    rethrowDatabaseUnavailableError(outcome.reason);\n    rethrowProjectionVerificationCancelled(outcome.reason);\n    await reportKeyingVerificationErrorInCauseChain(\n      outcome.reason,\n      input.reportSecurityIncident,\n      {\n        operation: \"hydrate_attachment\",\n        objectKind: \"blob\",\n        objectId: input.tasks[index]?.blobId ?? null,\n      },\n    );\n    input.log?.(\"Documents: an attachment is unavailable during hydration.\");\n  }\n  return values;\n}\n"]}

package/workflows/blobs/index.d.ts

@@ -6,6 +6,6 @@ export { createEncryptedBlobStore, createLazyEncryptedBlobStore, wrapEncryptedBl
 export { createMemoryBlobStore } from "../../data/blobs/memoryBlobStore.js";
 export { purgeOpfsBlobStore } from "../../data/blobs/opfsBlobStore.js";
 export type { MultipartStageResolvedListener, MultipartUploadProgress, MultipartUploadProgressListener, } from "../../data/documents/blob/shared/types.js";
-export { decryptDocumentAttachmentBlob } from "./decrypt.js";
-export { hydrateDocumentAttachmentBlobs } from "./hydrate.js";
-export { uploadDocumentAttachment } from "./upload.js";
+export { decryptDocumentAttachmentBlob } from "./hydration/decrypt.js";
+export { hydrateDocumentAttachmentBlobs } from "./hydration/hydrate.js";
+export { uploadDocumentAttachment } from "./upload/index.js";

package/workflows/blobs/index.js

@@ -3,7 +3,7 @@ export { createBlobStore } from "../../data/blobs/createBlobStore.js";
 export { createEncryptedBlobStore, createLazyEncryptedBlobStore, wrapEncryptedBlobStore, } from "../../data/blobs/encryptedBlobStore.js";
 export { createMemoryBlobStore } from "../../data/blobs/memoryBlobStore.js";
 export { purgeOpfsBlobStore } from "../../data/blobs/opfsBlobStore.js";
-export { decryptDocumentAttachmentBlob } from "./decrypt.js";
-export { hydrateDocumentAttachmentBlobs } from "./hydrate.js";
-export { uploadDocumentAttachment } from "./upload.js";
+export { decryptDocumentAttachmentBlob } from "./hydration/decrypt.js";
+export { hydrateDocumentAttachmentBlobs } from "./hydration/hydrate.js";
+export { uploadDocumentAttachment } from "./upload/index.js";
 //# sourceMappingURL=index.js.map