@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/workflows/blobs/hydrate.js

@@ -0,0 +1,174 @@
+import { bytesToHex } from "../../internal/crypto/index.js";
+import { attachmentContentSha256 } from "../../data/documents/attachmentContentIdentity.js";
+import { errorMessage } from "../../data/errorMessage.js";
+import { createAttachmentDecryptor } from "./attachmentDecryptor.js";
+import { collectHydrationResults } from "./hydrationResults.js";
+function servedBindingRejectionKey(attachment, binding) {
+    return JSON.stringify([
+        attachment.slotId,
+        binding.bindingId,
+        attachment.contentSha256,
+    ]);
+}
+async function readBlobStreamBytes(blob) {
+    return new Uint8Array(await new Response(blob.encryptedBytes).arrayBuffer());
+}
+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";
+    const blob = await apiClient.getBlobBytes(binding.blobId);
+    if (!blob) {
+        return null;
+    }
+    let encryptedBytes;
+    try {
+        encryptedBytes = await readBlobStreamBytes(blob);
+    }
+    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;
+    }
+    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: () => loadDocumentAttachmentBlob({ ...input, binding: target.binding }),
+        })),
+    });
+    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,
+        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) {
+        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,
+            }),
+        })),
+    });
+    return hydrated.filter((item) => item !== null);
+}
+//# sourceMappingURL=hydrate.js.map

package/workflows/blobs/hydrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate.js","sourceRoot":"","sources":["hydrate.ts"],"names":[],"mappings":"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","sourcesContent":["import type { BlobBytesResponse } 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/blobContracts\";\nimport { attachmentContentSha256 } from \"../../data/documents/attachmentContentIdentity\";\nimport type { DocumentAttachment } from \"../../data/documents/documentContent\";\nimport { errorMessage } from \"../../data/errorMessage\";\nimport type { ProjectionUserKeyResolver } from \"../../data/keyingProjectionVerification\";\nimport type { SecurityIncidentReporter } from \"../../data/securityIncidents\";\nimport type { ExecSql } from \"../../data/sqlite/sqlSchema\";\nimport { createAttachmentDecryptor } from \"./attachmentDecryptor\";\nimport { collectHydrationResults } from \"./hydrationResults\";\n\ninterface DocumentAttachmentHydrationApi {\n  evictDocumentWriterProjection?(documentId: string): void;\n  getBlobBytes(blobId: string): 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}\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 readBlobStreamBytes(\n  blob: BlobBytesResponse,\n): Promise<Uint8Array<ArrayBuffer>> {\n  return new Uint8Array(await new Response(blob.encryptedBytes).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  },\n): Promise<LoadedDocumentAttachmentBlobBytes | null> {\n  const { apiClient, binding, log } = input;\n  const logPrefix = input.logPrefix ?? \"Documents\";\n  const blob = await apiClient.getBlobBytes(binding.blobId);\n  if (!blob) {\n    return null;\n  }\n\n  let encryptedBytes: Uint8Array<ArrayBuffer>;\n  try {\n    encryptedBytes = await readBlobStreamBytes(blob);\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  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        loadDocumentAttachmentBlob({ ...input, binding: target.binding }),\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    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  },\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    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  return hydrated.filter(\n    (item): item is HydratedDocumentAttachmentBlob => item !== null,\n  );\n}\n"]}

package/workflows/blobs/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/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,+CAA+C,CAAC;AACvD,OAAO,EAAE,sCAAsC,EAAE,MAAM,+CAA+C,CAAC;AAGvG,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/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

@@ -0,0 +1,11 @@
+export type { BlobByteSource, BlobByteSourceInput, BlobStore, } from "../../data/blobContracts.js";
+export { blobByteSourceInputLength, createBlobByteSource, readBlobByteSource, } from "../../data/blobContracts.js";
+export { createBlobStore } from "../../data/blobs/createBlobStore.js";
+export type { EncryptedBlobStoreCipher, EncryptedBlobStoreKey, EncryptedBlobStoreOptions, WrapEncryptedBlobStoreOptions, } from "../../data/blobs/encryptedBlobStore.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 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";

package/workflows/blobs/index.js

@@ -0,0 +1,9 @@
+export { blobByteSourceInputLength, createBlobByteSource, readBlobByteSource, } from "../../data/blobContracts.js";
+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";
+//# sourceMappingURL=index.js.map

package/workflows/blobs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAOnE,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAMpE,OAAO,EAAE,6BAA6B,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,8BAA8B,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC","sourcesContent":["export type {\n  BlobByteSource,\n  BlobByteSourceInput,\n  BlobStore,\n} from \"../../data/blobContracts\";\nexport {\n  blobByteSourceInputLength,\n  createBlobByteSource,\n  readBlobByteSource,\n} from \"../../data/blobContracts\";\nexport { createBlobStore } from \"../../data/blobs/createBlobStore\";\nexport type {\n  EncryptedBlobStoreCipher,\n  EncryptedBlobStoreKey,\n  EncryptedBlobStoreOptions,\n  WrapEncryptedBlobStoreOptions,\n} from \"../../data/blobs/encryptedBlobStore\";\nexport {\n  createEncryptedBlobStore,\n  createLazyEncryptedBlobStore,\n  wrapEncryptedBlobStore,\n} from \"../../data/blobs/encryptedBlobStore\";\nexport { createMemoryBlobStore } from \"../../data/blobs/memoryBlobStore\";\nexport { purgeOpfsBlobStore } from \"../../data/blobs/opfsBlobStore\";\nexport type {\n  MultipartStageResolvedListener,\n  MultipartUploadProgress,\n  MultipartUploadProgressListener,\n} from \"../../data/documents/blob/shared/types\";\nexport { decryptDocumentAttachmentBlob } from \"./decrypt\";\nexport { hydrateDocumentAttachmentBlobs } from \"./hydrate\";\nexport { uploadDocumentAttachment } from \"./upload\";\n"]}

package/workflows/blobs/multipartStageFailures.js

@@ -0,0 +1,36 @@
+import { MULTIPART_BLOB_STAGE_ERROR_CODES } from "../../internal/validators/response/index.js";
+export function multipartStagePath(stageId) {
+    return `/blobs/stages/multipart/${encodeURIComponent(stageId)}`;
+}
+export function multipartApiFailureMessage(input) {
+    const failure = input.apiClient.getRequestFailure?.(input.request)?.message;
+    return failure
+        ? `${input.fallback} Last API failure: ${failure}`
+        : input.fallback;
+}
+function provesMultipartStageReplacement(failure) {
+    return (failure?.kind === "http" &&
+        ((failure.status === 404 &&
+            failure.code === MULTIPART_BLOB_STAGE_ERROR_CODES.notFound) ||
+            (failure.status === 409 &&
+                failure.code === MULTIPART_BLOB_STAGE_ERROR_CODES.expired)));
+}
+export async function assertMultipartStageReplaceable(input) {
+    const request = {
+        method: "GET",
+        path: multipartStagePath(input.stageId),
+    };
+    const failure = input.apiClient.getRequestFailure?.(request);
+    if (!provesMultipartStageReplacement(failure)) {
+        throw new Error(multipartApiFailureMessage({
+            apiClient: input.apiClient,
+            fallback: `Multipart blob resume stage lookup failed for stage ${input.stageId}.`,
+            request,
+        }));
+    }
+    if (input.onStageUnavailable) {
+        await input.onStageUnavailable(input.stageId);
+        throw new Error("Multipart stage is unavailable; upload attempt stopped for recovery.");
+    }
+}
+//# sourceMappingURL=multipartStageFailures.js.map

package/workflows/blobs/multipartStageFailures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipartStageFailures.js","sourceRoot":"","sources":["multipartStageFailures.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,MAAM,gCAAgC,CAAC;AAUlF,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,OAAO,2BAA2B,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,KAI1C;IACC,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,iBAAiB,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC5E,OAAO,OAAO;QACZ,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,sBAAsB,OAAO,EAAE;QAClD,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;AACrB,CAAC;AAED,SAAS,+BAA+B,CACtC,OAAmC;IAEnC,OAAO,CACL,OAAO,EAAE,IAAI,KAAK,MAAM;QACxB,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,GAAG;YACtB,OAAO,CAAC,IAAI,KAAK,gCAAgC,CAAC,QAAQ,CAAC;YAC3D,CAAC,OAAO,CAAC,MAAM,KAAK,GAAG;gBACrB,OAAO,CAAC,IAAI,KAAK,gCAAgC,CAAC,OAAO,CAAC,CAAC,CAChE,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,+BAA+B,CAAC,KAMrD;IACC,MAAM,OAAO,GAAG;QACd,MAAM,EAAE,KAAc;QACtB,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC;KACxC,CAAC;IACF,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,iBAAiB,EAAE,CAAC,OAAO,CAAC,CAAC;IAC7D,IAAI,CAAC,+BAA+B,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CACb,0BAA0B,CAAC;YACzB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,QAAQ,EAAE,uDAAuD,KAAK,CAAC,OAAO,GAAG;YACjF,OAAO;SACR,CAAC,CACH,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,kBAAkB,EAAE,CAAC;QAC7B,MAAM,KAAK,CAAC,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9C,MAAM,IAAI,KAAK,CACb,sEAAsE,CACvE,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["import { MULTIPART_BLOB_STAGE_ERROR_CODES } from \"@tearleads/validators/response\";\nimport type { BlobAttachmentApi } from \"../../data/documents/blob/shared/types\";\n\ntype RequestFailureInput = Parameters<\n  NonNullable<BlobAttachmentApi[\"getRequestFailure\"]>\n>[0];\ntype RequestFailure = ReturnType<\n  NonNullable<BlobAttachmentApi[\"getRequestFailure\"]>\n>;\n\nexport function multipartStagePath(stageId: string): string {\n  return `/blobs/stages/multipart/${encodeURIComponent(stageId)}`;\n}\n\nexport function multipartApiFailureMessage(input: {\n  readonly apiClient: BlobAttachmentApi;\n  readonly fallback: string;\n  readonly request: RequestFailureInput;\n}): string {\n  const failure = input.apiClient.getRequestFailure?.(input.request)?.message;\n  return failure\n    ? `${input.fallback} Last API failure: ${failure}`\n    : input.fallback;\n}\n\nfunction provesMultipartStageReplacement(\n  failure: RequestFailure | undefined,\n): boolean {\n  return (\n    failure?.kind === \"http\" &&\n    ((failure.status === 404 &&\n      failure.code === MULTIPART_BLOB_STAGE_ERROR_CODES.notFound) ||\n      (failure.status === 409 &&\n        failure.code === MULTIPART_BLOB_STAGE_ERROR_CODES.expired))\n  );\n}\n\nexport async function assertMultipartStageReplaceable(input: {\n  readonly apiClient: BlobAttachmentApi;\n  readonly onStageUnavailable?:\n    | ((stageId: string) => Promise<void>)\n    | undefined;\n  readonly stageId: string;\n}): Promise<void> {\n  const request = {\n    method: \"GET\" as const,\n    path: multipartStagePath(input.stageId),\n  };\n  const failure = input.apiClient.getRequestFailure?.(request);\n  if (!provesMultipartStageReplacement(failure)) {\n    throw new Error(\n      multipartApiFailureMessage({\n        apiClient: input.apiClient,\n        fallback: `Multipart blob resume stage lookup failed for stage ${input.stageId}.`,\n        request,\n      }),\n    );\n  }\n  if (input.onStageUnavailable) {\n    await input.onStageUnavailable(input.stageId);\n    throw new Error(\n      \"Multipart stage is unavailable; upload attempt stopped for recovery.\",\n    );\n  }\n}\n"]}

package/workflows/blobs/multipartUpload.js

@@ -0,0 +1,288 @@
+import { bytesToHex, MAX_BLOB_CHUNK_COUNT } from "../../internal/crypto/index.js";
+import { assertMultipartStageReplaceable, multipartApiFailureMessage, multipartStagePath, } from "./multipartStageFailures.js";
+const DEFAULT_MULTIPART_UPLOAD_CONCURRENCY = 4;
+const MAX_MULTIPART_UPLOAD_CONCURRENCY = 4;
+const MAX_MULTIPART_PART_BYTES = 5 * 1024 * 1024 * 1024;
+function pathSegment(value) {
+    return encodeURIComponent(String(value));
+}
+function multipartPartPath(input) {
+    const basePath = `${multipartStagePath(input.stageId)}/parts/${pathSegment(input.partNumber)}`;
+    return `${basePath}/bytes`;
+}
+async function sha256BytesHex(bytes) {
+    return bytesToHex(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)));
+}
+function normalizeMultipartUploadConcurrency(value) {
+    if (value === undefined) {
+        return DEFAULT_MULTIPART_UPLOAD_CONCURRENCY;
+    }
+    if (!Number.isInteger(value) ||
+        value <= 0 ||
+        value > MAX_MULTIPART_UPLOAD_CONCURRENCY) {
+        throw new Error(`Multipart blob upload concurrency must be between 1 and ${MAX_MULTIPART_UPLOAD_CONCURRENCY}`);
+    }
+    return value;
+}
+function isMultipartPartCommit(part) {
+    return part !== undefined;
+}
+async function uploadMultipartPartTasks(input) {
+    let failed = false;
+    let firstFailure;
+    let nextTaskIndex = 0;
+    async function worker() {
+        while (!failed) {
+            const task = input.tasks[nextTaskIndex];
+            nextTaskIndex += 1;
+            if (!task) {
+                return;
+            }
+            try {
+                const uploaded = await uploadMultipartPartBytes({
+                    apiClient: input.apiClient,
+                    encryption: input.encryption,
+                    stageId: input.stageId,
+                    task,
+                    uploadId: input.uploadId,
+                });
+                if (!uploaded) {
+                    failed = true;
+                    throw new Error(multipartApiFailureMessage({
+                        apiClient: input.apiClient,
+                        fallback: `Multipart blob part ${task.partNumber} upload failed for stage ${input.stageId}.`,
+                        request: {
+                            method: "PUT",
+                            path: multipartPartPath({
+                                partNumber: task.partNumber,
+                                stageId: input.stageId,
+                            }),
+                        },
+                    }));
+                }
+                input.completeParts[task.partIndex] = {
+                    etag: uploaded.part.etag,
+                    partNumber: task.partNumber,
+                };
+                input.onPartUploaded?.(task);
+            }
+            catch (error) {
+                // Stop sibling workers from pulling new tasks and firing more uploads
+                // once any part rejects. Keep this worker alive long enough for the
+                // shared join below to drain uploads siblings already started.
+                failed = true;
+                firstFailure ??= { error };
+                return;
+            }
+        }
+    }
+    const workerCount = Math.min(input.concurrency, input.tasks.length);
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    if (firstFailure) {
+        throw firstFailure.error;
+    }
+}
+async function uploadMultipartPartBytes(input) {
+    const encryptedPartBytes = await input.encryption.encryptPart(input.task.partIndex);
+    if (encryptedPartBytes.byteLength !== input.task.byteLength) {
+        throw new Error(`Encrypted blob part ${input.task.partNumber} byte length mismatch: expected ${input.task.byteLength.toLocaleString()}, received ${encryptedPartBytes.byteLength.toLocaleString()}.`);
+    }
+    const uploaded = await input.apiClient.uploadMultipartBlobPartBytes(input.stageId, input.task.partNumber, {
+        byteLength: encryptedPartBytes.byteLength,
+        encryptedBytes: encryptedPartBytes,
+        sha256: await sha256BytesHex(encryptedPartBytes),
+        uploadId: input.uploadId,
+    });
+    if (uploaded &&
+        (uploaded.stageId !== input.stageId ||
+            uploaded.uploadId !== input.uploadId ||
+            uploaded.part.partNumber !== input.task.partNumber ||
+            uploaded.part.byteLength !== input.task.byteLength)) {
+        throw new Error(`Multipart blob part ${input.task.partNumber} response does not match its request.`);
+    }
+    return uploaded;
+}
+function uploadedPartsByPartNumber(parts) {
+    return new Map(parts.map((part) => [part.partNumber, part]));
+}
+function isMultipartStageStatus(stage) {
+    return "completed" in stage && typeof stage.completed === "boolean";
+}
+/**
+ * Plans encrypted part indices without materializing their bytes, reusing any
+ * already-staged parts and seeding cumulative progress for resumed uploads.
+ */
+function planMultipartParts(input) {
+    const { encryption, uploadedParts } = input;
+    const completeParts = new Array(encryption.partCount);
+    const uploadTasks = [];
+    const progress = {
+        bytesTotal: 0,
+        bytesUploaded: 0,
+        partsCompleted: 0,
+        partsTotal: encryption.partCount,
+    };
+    for (let partIndex = 0; partIndex < encryption.partCount; partIndex += 1) {
+        const partNumber = partIndex + 1;
+        const byteLength = encryption.getPartByteLength(partIndex);
+        progress.bytesTotal += byteLength;
+        const uploadedPart = uploadedParts.get(partNumber);
+        if (uploadedPart?.byteLength === byteLength) {
+            completeParts[partIndex] = {
+                etag: uploadedPart.etag,
+                partNumber,
+            };
+            progress.partsCompleted += 1;
+            progress.bytesUploaded += byteLength;
+            continue;
+        }
+        uploadTasks.push({
+            byteLength,
+            partIndex,
+            partNumber,
+        });
+    }
+    return { completeParts, progress, uploadTasks };
+}
+async function resolveMultipartStageStatus(input) {
+    const resumeStageId = input.multipart.resumeStageId;
+    if (resumeStageId) {
+        const resumed = await input.apiClient.getMultipartBlobStage(resumeStageId);
+        if (!resumed) {
+            await assertMultipartStageReplaceable({
+                apiClient: input.apiClient,
+                onStageUnavailable: input.onStageUnavailable,
+                stageId: resumeStageId,
+            });
+        }
+        if (resumed && resumed.stageId !== resumeStageId) {
+            throw new Error(`Multipart blob resume response does not match stage ${resumeStageId}.`);
+        }
+        if (resumed) {
+            // A successful lookup is authoritative: a metadata mismatch indicates
+            // inconsistent persisted state or a bad server response, not proof that
+            // the existing stage is safe to abandon.
+            if (resumed.organizationId !== input.organizationId ||
+                resumed.byteLength !== input.byteLength ||
+                resumed.sha256 !== input.sha256) {
+                throw new Error(`Multipart blob resume stage ${resumeStageId} does not match the requested organization or bytes.`);
+            }
+            return resumed;
+        }
+    }
+    const stage = await input.apiClient.initiateMultipartBlobStage({
+        organizationId: input.organizationId,
+        byteLength: input.byteLength,
+        sha256: input.sha256,
+    });
+    if (!stage) {
+        throw new Error(multipartApiFailureMessage({
+            apiClient: input.apiClient,
+            fallback: `Multipart blob stage initiation failed for ${input.byteLength.toLocaleString()} bytes.`,
+            request: { method: "POST", path: "/blobs/stages/multipart" },
+        }));
+    }
+    if (stage.organizationId !== input.organizationId ||
+        stage.byteLength !== input.byteLength ||
+        stage.sha256 !== input.sha256) {
+        throw new Error("Multipart blob stage initiation response does not match its request.");
+    }
+    return isMultipartStageStatus(stage)
+        ? stage
+        : {
+            ...stage,
+            completed: false,
+        };
+}
+function assertMultipartPlanLimits(encryption) {
+    if (encryption.partCount > MAX_BLOB_CHUNK_COUNT) {
+        throw new Error(`Multipart blob upload would require ${encryption.partCount.toLocaleString()} parts; the maximum is ${MAX_BLOB_CHUNK_COUNT.toLocaleString()} fixed 5 MiB chunks.`);
+    }
+    for (let index = 0; index < encryption.partCount; index += 1) {
+        if (encryption.getPartByteLength(index) > MAX_MULTIPART_PART_BYTES) {
+            throw new Error(`Encrypted blob part ${index + 1} exceeds the 5 GiB multipart part limit.`);
+        }
+    }
+}
+export async function stageMultipartBlobAttachment(input) {
+    if (input.multipart.partSize !== input.encryption.chunkSize) {
+        throw new Error("Multipart part size must match the encryption chunk size exactly.");
+    }
+    assertMultipartPlanLimits(input.encryption);
+    const status = await resolveMultipartStageStatus({
+        apiClient: input.apiClient,
+        byteLength: input.encryption.byteLength,
+        multipart: input.multipart,
+        organizationId: input.organizationId,
+        onStageUnavailable: input.onStageUnavailable,
+        sha256: input.encryption.sha256,
+    });
+    // Surface the stage id before any parts upload so the caller can persist it;
+    // an upload interrupted mid-flight can then resume this same stage.
+    await input.onStageResolved?.({
+        partSize: input.encryption.chunkSize,
+        stageId: status.stageId,
+    });
+    if (status.completed) {
+        input.onMultipartProgress?.({
+            bytesTotal: input.encryption.byteLength,
+            bytesUploaded: input.encryption.byteLength,
+            partsCompleted: input.encryption.partCount,
+            partsTotal: input.encryption.partCount,
+        });
+        return status.stageId;
+    }
+    const { completeParts, progress, uploadTasks } = planMultipartParts({
+        encryption: input.encryption,
+        uploadedParts: uploadedPartsByPartNumber(status.uploadedParts),
+    });
+    const reportMultipartProgress = () => {
+        input.onMultipartProgress?.({
+            bytesTotal: progress.bytesTotal,
+            bytesUploaded: progress.bytesUploaded,
+            partsCompleted: progress.partsCompleted,
+            partsTotal: progress.partsTotal,
+        });
+    };
+    reportMultipartProgress();
+    await uploadMultipartPartTasks({
+        apiClient: input.apiClient,
+        completeParts,
+        concurrency: normalizeMultipartUploadConcurrency(input.multipart.uploadConcurrency),
+        encryption: input.encryption,
+        onPartUploaded: (task) => {
+            progress.partsCompleted += 1;
+            progress.bytesUploaded += task.byteLength;
+            reportMultipartProgress();
+        },
+        stageId: status.stageId,
+        tasks: uploadTasks,
+        uploadId: status.uploadId,
+    });
+    const committedParts = completeParts.filter(isMultipartPartCommit);
+    if (committedParts.length !== input.encryption.partCount) {
+        throw new Error(`Multipart blob upload incomplete for stage ${status.stageId}: committed ${committedParts.length.toLocaleString()} of ${input.encryption.partCount.toLocaleString()} parts.`);
+    }
+    const completed = await input.apiClient.completeMultipartBlobStage(status.stageId, {
+        parts: committedParts,
+        uploadId: status.uploadId,
+    });
+    if (!completed) {
+        throw new Error(multipartApiFailureMessage({
+            apiClient: input.apiClient,
+            fallback: `Multipart blob stage completion failed for stage ${status.stageId} with ${committedParts.length.toLocaleString()} committed parts.`,
+            request: {
+                method: "POST",
+                path: `${multipartStagePath(status.stageId)}/complete`,
+            },
+        }));
+    }
+    if (completed.organizationId !== input.organizationId ||
+        completed.stageId !== status.stageId ||
+        completed.byteLength !== input.encryption.byteLength ||
+        completed.sha256 !== input.encryption.sha256) {
+        throw new Error(`Multipart blob stage ${status.stageId} completion response does not match its request.`);
+    }
+    return completed.stageId;
+}
+//# sourceMappingURL=multipartUpload.js.map