@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/internal/api-client/sessionRefresh.js

@@ -0,0 +1,39 @@
+import { KeyingVerificationError } from "../crypto/index.js";
+import { errorMessage, isRefreshableSessionError, isReplayableRequestBody, } from "./requestInternals.js";
+/**
+ * Decides whether a failed request can be replayed after session renewal.
+ * Identity-integrity failures are terminal and must retain their typed error.
+ */
+export async function shouldRetryAfterSessionExpired(input) {
+    if (input.options.retryOnSessionExpired === false ||
+        !input.authToken ||
+        !isReplayableRequestBody(input.body) ||
+        !isRefreshableSessionError(input.responseStatus, input.code)) {
+        return false;
+    }
+    const currentAuthToken = input.getCurrentAuthToken();
+    if (currentAuthToken && currentAuthToken !== input.authToken) {
+        if (input.isKnownSessionRenewal(input.authToken, currentAuthToken))
+            input.options.onSessionRenewed?.();
+        return true;
+    }
+    let refreshed = false;
+    try {
+        refreshed = await input.refreshSession();
+    }
+    catch (error) {
+        if (error instanceof KeyingVerificationError) {
+            throw error;
+        }
+        if (input.options.reportErrors ?? true) {
+            input.reportError(`Session refresh failed: ${errorMessage(error)}`);
+        }
+    }
+    const renewed = Boolean(refreshed &&
+        input.getCurrentAuthToken() &&
+        input.getCurrentAuthToken() !== input.authToken);
+    if (renewed)
+        input.options.onSessionRenewed?.();
+    return renewed;
+}
+//# sourceMappingURL=sessionRefresh.js.map

package/internal/api-client/sessionRefresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionRefresh.js","sourceRoot":"","sources":["sessionRefresh.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EACL,YAAY,EACZ,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAe5B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,KAA0B;IAE1B,IACE,KAAK,CAAC,OAAO,CAAC,qBAAqB,KAAK,KAAK;QAC7C,CAAC,KAAK,CAAC,SAAS;QAChB,CAAC,uBAAuB,CAAC,KAAK,CAAC,IAAI,CAAC;QACpC,CAAC,yBAAyB,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,EAC5D,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,gBAAgB,GAAG,KAAK,CAAC,mBAAmB,EAAE,CAAC;IACrD,IAAI,gBAAgB,IAAI,gBAAgB,KAAK,KAAK,CAAC,SAAS,EAAE,CAAC;QAC7D,IAAI,KAAK,CAAC,qBAAqB,CAAC,KAAK,CAAC,SAAS,EAAE,gBAAgB,CAAC;YAChE,KAAK,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,CAAC;QACH,SAAS,GAAG,MAAM,KAAK,CAAC,cAAc,EAAE,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,KAAK,YAAY,uBAAuB,EAAE,CAAC;YAC7C,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,IAAI,IAAI,EAAE,CAAC;YACvC,KAAK,CAAC,WAAW,CAAC,2BAA2B,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CACrB,SAAS;QACP,KAAK,CAAC,mBAAmB,EAAE;QAC3B,KAAK,CAAC,mBAAmB,EAAE,KAAK,KAAK,CAAC,SAAS,CAClD,CAAC;IACF,IAAI,OAAO;QAAE,KAAK,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;IAChD,OAAO,OAAO,CAAC;AACjB,CAAC","sourcesContent":["import { KeyingVerificationError } from \"@tearleads/crypto\";\nimport {\n  errorMessage,\n  isRefreshableSessionError,\n  isReplayableRequestBody,\n} from \"./requestInternals\";\nimport type { RequestBody, RequestResultOptions } from \"./types\";\n\ninterface SessionRefreshInput {\n  readonly authToken: string | null;\n  readonly body: RequestBody | undefined;\n  readonly code: string | null;\n  readonly getCurrentAuthToken: () => string | null;\n  readonly isKnownSessionRenewal: (from: string, to: string) => boolean;\n  readonly options: RequestResultOptions;\n  readonly refreshSession: () => boolean | Promise<boolean>;\n  readonly reportError: (message: string) => void;\n  readonly responseStatus: number;\n}\n\n/**\n * Decides whether a failed request can be replayed after session renewal.\n * Identity-integrity failures are terminal and must retain their typed error.\n */\nexport async function shouldRetryAfterSessionExpired(\n  input: SessionRefreshInput,\n): Promise<boolean> {\n  if (\n    input.options.retryOnSessionExpired === false ||\n    !input.authToken ||\n    !isReplayableRequestBody(input.body) ||\n    !isRefreshableSessionError(input.responseStatus, input.code)\n  ) {\n    return false;\n  }\n\n  const currentAuthToken = input.getCurrentAuthToken();\n  if (currentAuthToken && currentAuthToken !== input.authToken) {\n    if (input.isKnownSessionRenewal(input.authToken, currentAuthToken))\n      input.options.onSessionRenewed?.();\n    return true;\n  }\n\n  let refreshed = false;\n  try {\n    refreshed = await input.refreshSession();\n  } catch (error: unknown) {\n    if (error instanceof KeyingVerificationError) {\n      throw error;\n    }\n    if (input.options.reportErrors ?? true) {\n      input.reportError(`Session refresh failed: ${errorMessage(error)}`);\n    }\n  }\n\n  const renewed = Boolean(\n    refreshed &&\n      input.getCurrentAuthToken() &&\n      input.getCurrentAuthToken() !== input.authToken,\n  );\n  if (renewed) input.options.onSessionRenewed?.();\n  return renewed;\n}\n"]}

package/internal/api-client/types.d.ts

@@ -0,0 +1,61 @@
+import type { DocumentAttributionRangesQuery, HttpOperation, HttpOperationMethod } from "../validators/operation/index.js";
+import type { PrincipalPolicyBundleResponse, SyncWatermark } from "../validators/response/index.js";
+export type HttpMethod = HttpOperationMethod;
+export type RequestBody = BodyInit;
+export interface ListContainerDocumentsOptions {
+    limit?: number;
+    watermark?: SyncWatermark | null;
+}
+export type ListDocumentEditAttributionRangesOptions = Omit<DocumentAttributionRangesQuery, "cursor"> & {
+    cursor?: DocumentAttributionRangesQuery["cursor"] | null;
+};
+export interface RequestResultOptions {
+    readonly signal?: AbortSignal | undefined;
+    /** Expected target for a declared 402; mismatched response identities fail closed. */
+    readonly expectedPaymentRequiredOrganizationId?: string | undefined;
+    readonly headers?: Record<string, string> | undefined;
+    readonly reportErrors?: boolean | undefined;
+    /** Called after this request or a concurrent request renews the same session. */
+    readonly onSessionRenewed?: (() => void) | undefined;
+    readonly retryOnSessionExpired?: boolean | "renew-only" | undefined;
+}
+export type OperationRequestFn = <T>(path: string, validator: (value: unknown) => value is T, method: HttpMethod, body: RequestBody | undefined, options: RequestResultOptions | undefined, failureOperation: HttpOperation) => Promise<T | null>;
+export type OperationRequestResultFn = <T>(path: string, validator: (value: unknown) => value is T, method: HttpMethod, body: RequestBody | undefined, options: RequestResultOptions | undefined, failureOperation: HttpOperation) => Promise<RequestResult<T>>;
+export type RequestFailureKind = "http" | "network" | "json" | "shape" | "cancelled" | "outcome-unknown";
+export interface RequestFailure {
+    readonly code?: string | undefined;
+    readonly kind: RequestFailureKind;
+    readonly message: string;
+    readonly method: HttpMethod;
+    readonly ok: false;
+    readonly path: string;
+    readonly report: () => void;
+    readonly status: number | null;
+    readonly statusText: string;
+    readonly stalePrincipalPolicies?: PrincipalPolicyBundleResponse[] | undefined;
+    /**
+     * With `container_descendant_rekeys_required`, the full owed set, parent-first;
+     * with `container_descendant_rekeys_inaccessible`, its unwritable subset.
+     * A hint, never authority; verify each container before signing for it.
+     */
+    readonly requiredContainerIds?: readonly string[] | undefined;
+}
+export interface RequestSuccess<T> {
+    readonly data: T;
+    readonly ok: true;
+}
+export type RequestResult<T> = RequestFailure | RequestSuccess<T>;
+export interface ResponseRequestValidationFailureInput {
+    readonly code?: string | undefined;
+    readonly kind: RequestFailureKind;
+    readonly message: string;
+    readonly method: HttpMethod;
+    readonly options?: RequestResultOptions | undefined;
+    readonly path: string;
+    readonly status: number | null;
+    readonly statusText: string;
+}
+export interface OperationResponseRequestFn {
+    (path: string, method: HttpMethod, body: RequestBody | undefined, options: RequestResultOptions | undefined, additionalSuccessStatuses: readonly number[], failureOperation: HttpOperation): Promise<RequestResult<Response>>;
+    readonly reportFailure: (input: ResponseRequestValidationFailureInput) => RequestFailure;
+}

package/internal/api-client/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/internal/api-client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  DocumentAttributionRangesQuery,\n  HttpOperation,\n  HttpOperationMethod,\n} from \"@tearleads/validators/operation\";\nimport type {\n  PrincipalPolicyBundleResponse,\n  SyncWatermark,\n} from \"@tearleads/validators/response\";\n\nexport type HttpMethod = HttpOperationMethod;\nexport type RequestBody = BodyInit;\n\nexport interface ListContainerDocumentsOptions {\n  limit?: number;\n  watermark?: SyncWatermark | null;\n}\n\nexport type ListDocumentEditAttributionRangesOptions = Omit<\n  DocumentAttributionRangesQuery,\n  \"cursor\"\n> & {\n  cursor?: DocumentAttributionRangesQuery[\"cursor\"] | null;\n};\n\nexport interface RequestResultOptions {\n  readonly signal?: AbortSignal | undefined;\n  /** Expected target for a declared 402; mismatched response identities fail closed. */\n  readonly expectedPaymentRequiredOrganizationId?: string | undefined;\n  readonly headers?: Record<string, string> | undefined;\n  readonly reportErrors?: boolean | undefined;\n  /** Called after this request or a concurrent request renews the same session. */\n  readonly onSessionRenewed?: (() => void) | undefined;\n  readonly retryOnSessionExpired?: boolean | \"renew-only\" | undefined;\n}\n\nexport type OperationRequestFn = <T>(\n  path: string,\n  validator: (value: unknown) => value is T,\n  method: HttpMethod,\n  body: RequestBody | undefined,\n  options: RequestResultOptions | undefined,\n  failureOperation: HttpOperation,\n) => Promise<T | null>;\n\nexport type OperationRequestResultFn = <T>(\n  path: string,\n  validator: (value: unknown) => value is T,\n  method: HttpMethod,\n  body: RequestBody | undefined,\n  options: RequestResultOptions | undefined,\n  failureOperation: HttpOperation,\n) => Promise<RequestResult<T>>;\n\nexport type RequestFailureKind =\n  | \"http\"\n  | \"network\"\n  | \"json\"\n  | \"shape\"\n  | \"cancelled\"\n  | \"outcome-unknown\";\n\nexport interface RequestFailure {\n  readonly code?: string | undefined;\n  readonly kind: RequestFailureKind;\n  readonly message: string;\n  readonly method: HttpMethod;\n  readonly ok: false;\n  readonly path: string;\n  readonly report: () => void;\n  readonly status: number | null;\n  readonly statusText: string;\n  readonly stalePrincipalPolicies?: PrincipalPolicyBundleResponse[] | undefined;\n  /**\n   * With `container_descendant_rekeys_required`, the full owed set, parent-first;\n   * with `container_descendant_rekeys_inaccessible`, its unwritable subset.\n   * A hint, never authority; verify each container before signing for it.\n   */\n  readonly requiredContainerIds?: readonly string[] | undefined;\n}\n\nexport interface RequestSuccess<T> {\n  readonly data: T;\n  readonly ok: true;\n}\n\nexport type RequestResult<T> = RequestFailure | RequestSuccess<T>;\n\nexport interface ResponseRequestValidationFailureInput {\n  readonly code?: string | undefined;\n  readonly kind: RequestFailureKind;\n  readonly message: string;\n  readonly method: HttpMethod;\n  readonly options?: RequestResultOptions | undefined;\n  readonly path: string;\n  readonly status: number | null;\n  readonly statusText: string;\n}\n\nexport interface OperationResponseRequestFn {\n  (\n    path: string,\n    method: HttpMethod,\n    body: RequestBody | undefined,\n    options: RequestResultOptions | undefined,\n    additionalSuccessStatuses: readonly number[],\n    failureOperation: HttpOperation,\n  ): Promise<RequestResult<Response>>;\n  readonly reportFailure: (\n    input: ResponseRequestValidationFailureInput,\n  ) => RequestFailure;\n}\n"]}

package/internal/api-client/verifiedProjectionHistory.d.ts

@@ -0,0 +1,4 @@
+/** Transport registers immutable candidates; only successful SDK verification admits one. */
+export declare function registerProjectionHistoryAdmission(projection: object, admit: () => void): void;
+/** Does not grant access or advance a security checkpoint. */
+export declare function retainVerifiedProjectionHistory(projection: object): void;

package/internal/api-client/verifiedProjectionHistory.js

@@ -0,0 +1,12 @@
+const admissions = new WeakMap();
+/** Transport registers immutable candidates; only successful SDK verification admits one. */
+export function registerProjectionHistoryAdmission(projection, admit) {
+    admissions.set(projection, admit);
+}
+/** Does not grant access or advance a security checkpoint. */
+export function retainVerifiedProjectionHistory(projection) {
+    const admit = admissions.get(projection);
+    admissions.delete(projection);
+    admit?.();
+}
+//# sourceMappingURL=verifiedProjectionHistory.js.map

package/internal/api-client/verifiedProjectionHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifiedProjectionHistory.js","sourceRoot":"","sources":["verifiedProjectionHistory.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG,IAAI,OAAO,EAAsB,CAAC;AAErD,6FAA6F;AAC7F,MAAM,UAAU,kCAAkC,CAChD,UAAkB,EAClB,KAAiB;IAEjB,UAAU,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;AACpC,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,+BAA+B,CAAC,UAAkB;IAChE,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACzC,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC9B,KAAK,EAAE,EAAE,CAAC;AACZ,CAAC","sourcesContent":["const admissions = new WeakMap<object, () => void>();\n\n/** Transport registers immutable candidates; only successful SDK verification admits one. */\nexport function registerProjectionHistoryAdmission(\n  projection: object,\n  admit: () => void,\n): void {\n  admissions.set(projection, admit);\n}\n\n/** Does not grant access or advance a security checkpoint. */\nexport function retainVerifiedProjectionHistory(projection: object): void {\n  const admit = admissions.get(projection);\n  admissions.delete(projection);\n  admit?.();\n}\n"]}

package/internal/api-client/writerProjectionCitations.js

@@ -0,0 +1,95 @@
+import { BoundedCache } from "./ApiCache.js";
+function collectCitedContainerIds(value, key, cited) {
+    if (typeof value === "string") {
+        if (/containerid$/iu.test(key))
+            cited.add(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        const listsIds = /containerids$/iu.test(key);
+        for (const item of value) {
+            if (listsIds && typeof item === "string")
+                cited.add(item);
+            else
+                collectCitedContainerIds(item, key, cited);
+        }
+        return;
+    }
+    if (value === null || typeof value !== "object")
+        return;
+    const entries = Object.entries(value);
+    // An access event names its container as `objectId` beside `objectKind`.
+    if (Reflect.get(value, "objectKind") === "container") {
+        const objectId = Reflect.get(value, "objectId");
+        if (typeof objectId === "string")
+            cited.add(objectId);
+    }
+    for (const [childKey, child] of entries) {
+        collectCitedContainerIds(child, childKey, cited);
+    }
+}
+/**
+ * Every container a writer projection cites: any `…containerId` field, any
+ * `…containerIds` list, and the object id of a container access event,
+ * wherever they appear. Reading every such field rather than a fixed set errs
+ * toward citing too much, which costs only a refetch.
+ */
+export function writerProjectionCitedContainerIds(projection) {
+    const cited = new Set();
+    collectCitedContainerIds(projection, "", cited);
+    return cited;
+}
+function citesAny(cited, containerIds) {
+    for (const id of containerIds)
+        if (cited.has(id))
+            return true;
+    return false;
+}
+/**
+ * A writer projection cache that records which containers each resolved entry
+ * cites, so a manifest change to some containers can evict exactly the
+ * entries citing them. An entry that has not resolved to a projection has no
+ * record and is always evicted.
+ */
+export class CitingProjectionCache extends BoundedCache {
+    citations = new WeakMap();
+    set(key, value) {
+        void value.then((projection) => {
+            if (projection !== null) {
+                this.citations.set(value, writerProjectionCitedContainerIds(projection));
+            }
+        }, () => undefined);
+        return super.set(key, value);
+    }
+    /** Evicts the entries that cite any of the containers or are unresolved. */
+    evictCiting(containerIds) {
+        for (const key of [...this.keys()]) {
+            const entry = this.get(key);
+            const cited = entry && this.citations.get(entry);
+            if (cited && !citesAny(cited, containerIds))
+                continue;
+            this.delete(key);
+        }
+    }
+}
+/**
+ * Evicts what a manifest change to these containers makes stale: every
+ * container or document writer projection citing one of them or not yet
+ * resolved, and every fetch still in flight (it may predate the change), which
+ * the raised stamp floor keeps from publishing even when no cache slot tracks
+ * it. Attachment envelopes wrap to the same KEK targets, so an attachment list
+ * stays only while its document's projection does; a list whose document has
+ * no cached projection is evicted too.
+ */
+export function evictWriterProjectionsCiting(containerIds, caches) {
+    for (const { cache, inFlight } of [caches.containers, caches.documents]) {
+        cache.evictCiting(containerIds);
+        cache.invalidateInFlight();
+        inFlight.clear();
+    }
+    for (const key of [...caches.attachmentLists.keys()]) {
+        if (!caches.documents.cache.has(key))
+            caches.attachmentLists.delete(key);
+    }
+}
+//# sourceMappingURL=writerProjectionCitations.js.map

package/internal/api-client/writerProjectionCitations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writerProjectionCitations.js","sourceRoot":"","sources":["writerProjectionCitations.ts"],"names":[],"mappings":"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","sourcesContent":["import { BoundedCache } from \"./ApiCache\";\n\nfunction collectCitedContainerIds(\n  value: unknown,\n  key: string,\n  cited: Set<string>,\n): void {\n  if (typeof value === \"string\") {\n    if (/containerid$/iu.test(key)) cited.add(value);\n    return;\n  }\n  if (Array.isArray(value)) {\n    const listsIds = /containerids$/iu.test(key);\n    for (const item of value) {\n      if (listsIds && typeof item === \"string\") cited.add(item);\n      else collectCitedContainerIds(item, key, cited);\n    }\n    return;\n  }\n  if (value === null || typeof value !== \"object\") return;\n  const entries = Object.entries(value);\n  // An access event names its container as `objectId` beside `objectKind`.\n  if (Reflect.get(value, \"objectKind\") === \"container\") {\n    const objectId = Reflect.get(value, \"objectId\");\n    if (typeof objectId === \"string\") cited.add(objectId);\n  }\n  for (const [childKey, child] of entries) {\n    collectCitedContainerIds(child, childKey, cited);\n  }\n}\n\n/**\n * Every container a writer projection cites: any `…containerId` field, any\n * `…containerIds` list, and the object id of a container access event,\n * wherever they appear. Reading every such field rather than a fixed set errs\n * toward citing too much, which costs only a refetch.\n */\nexport function writerProjectionCitedContainerIds(\n  projection: unknown,\n): ReadonlySet<string> {\n  const cited = new Set<string>();\n  collectCitedContainerIds(projection, \"\", cited);\n  return cited;\n}\n\nfunction citesAny(\n  cited: ReadonlySet<string>,\n  containerIds: ReadonlySet<string>,\n): boolean {\n  for (const id of containerIds) if (cited.has(id)) return true;\n  return false;\n}\n\n/**\n * A writer projection cache that records which containers each resolved entry\n * cites, so a manifest change to some containers can evict exactly the\n * entries citing them. An entry that has not resolved to a projection has no\n * record and is always evicted.\n */\nexport class CitingProjectionCache<V> extends BoundedCache<Promise<V | null>> {\n  private readonly citations = new WeakMap<\n    Promise<V | null>,\n    ReadonlySet<string>\n  >();\n\n  override set(key: string, value: Promise<V | null>): this {\n    void value.then(\n      (projection) => {\n        if (projection !== null) {\n          this.citations.set(\n            value,\n            writerProjectionCitedContainerIds(projection),\n          );\n        }\n      },\n      () => undefined,\n    );\n    return super.set(key, value);\n  }\n\n  /** Evicts the entries that cite any of the containers or are unresolved. */\n  evictCiting(containerIds: ReadonlySet<string>): void {\n    for (const key of [...this.keys()]) {\n      const entry = this.get(key);\n      const cited = entry && this.citations.get(entry);\n      if (cited && !citesAny(cited, containerIds)) continue;\n      this.delete(key);\n    }\n  }\n}\n\ninterface CitingProjectionCacheWithFetches<V> {\n  readonly cache: CitingProjectionCache<V>;\n  /** Shared result fetches still in flight, keyed like the cache. */\n  readonly inFlight: Map<string, unknown>;\n}\n\n/**\n * Evicts what a manifest change to these containers makes stale: every\n * container or document writer projection citing one of them or not yet\n * resolved, and every fetch still in flight (it may predate the change), which\n * the raised stamp floor keeps from publishing even when no cache slot tracks\n * it. Attachment envelopes wrap to the same KEK targets, so an attachment list\n * stays only while its document's projection does; a list whose document has\n * no cached projection is evicted too.\n */\nexport function evictWriterProjectionsCiting(\n  containerIds: ReadonlySet<string>,\n  caches: {\n    readonly attachmentLists: BoundedCache<unknown>;\n    readonly containers: CitingProjectionCacheWithFetches<unknown>;\n    readonly documents: CitingProjectionCacheWithFetches<unknown>;\n  },\n): void {\n  for (const { cache, inFlight } of [caches.containers, caches.documents]) {\n    cache.evictCiting(containerIds);\n    cache.invalidateInFlight();\n    inFlight.clear();\n  }\n  for (const key of [...caches.attachmentLists.keys()]) {\n    if (!caches.documents.cache.has(key)) caches.attachmentLists.delete(key);\n  }\n}\n"]}

package/internal/api-client/writerProjectionPrime.js

@@ -0,0 +1,25 @@
+/**
+ * Seed a writer-projection cache slot from a projection the client just
+ * authored, so the next read resolves locally instead of a cold GET. The seed
+ * must describe the id it is primed under — checked with the same binding a
+ * fetched response must satisfy, since a seed is built from mutation-response
+ * material and a projection for another object would make that next read, and
+ * the wrap it feeds, land on the wrong container or document. It never
+ * clobbers an existing entry (a fetch in flight or an earlier prime). The
+ * just-authored seed supersedes any GET already in flight: dropping the shared
+ * result entry makes a post-prime result caller read the seed instead of
+ * coalescing onto the older fetch. Callers already holding that fetch keep
+ * their result, and its settle cannot clobber the seed because the slot no
+ * longer matches its snapshot.
+ */
+export function primeWriterProjectionSlot(input) {
+    if (!input.describes(input.projection)) {
+        throw new Error(`${input.label} writer projection prime does not describe ${input.id}`);
+    }
+    if (input.cache.has(input.id)) {
+        return;
+    }
+    input.cache.set(input.id, Promise.resolve(input.projection));
+    input.inFlightResults.delete(input.id);
+}
+//# sourceMappingURL=writerProjectionPrime.js.map

package/internal/api-client/writerProjectionPrime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writerProjectionPrime.js","sourceRoot":"","sources":["writerProjectionPrime.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,yBAAyB,CAAI,KAO5C;IACC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,CAAC,KAAK,8CAA8C,KAAK,CAAC,EAAE,EAAE,CACvE,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;QAC9B,OAAO;IACT,CAAC;IACD,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;IAC7D,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC","sourcesContent":["import type { BoundedCache } from \"./ApiCache\";\n\n/**\n * Seed a writer-projection cache slot from a projection the client just\n * authored, so the next read resolves locally instead of a cold GET. The seed\n * must describe the id it is primed under — checked with the same binding a\n * fetched response must satisfy, since a seed is built from mutation-response\n * material and a projection for another object would make that next read, and\n * the wrap it feeds, land on the wrong container or document. It never\n * clobbers an existing entry (a fetch in flight or an earlier prime). The\n * just-authored seed supersedes any GET already in flight: dropping the shared\n * result entry makes a post-prime result caller read the seed instead of\n * coalescing onto the older fetch. Callers already holding that fetch keep\n * their result, and its settle cannot clobber the seed because the slot no\n * longer matches its snapshot.\n */\nexport function primeWriterProjectionSlot<T>(input: {\n  readonly cache: BoundedCache<Promise<T | null>>;\n  readonly describes: (value: unknown) => value is T;\n  readonly id: string;\n  readonly inFlightResults: { delete(key: string): boolean };\n  readonly label: string;\n  readonly projection: T;\n}): void {\n  if (!input.describes(input.projection)) {\n    throw new Error(\n      `${input.label} writer projection prime does not describe ${input.id}`,\n    );\n  }\n  if (input.cache.has(input.id)) {\n    return;\n  }\n  input.cache.set(input.id, Promise.resolve(input.projection));\n  input.inFlightResults.delete(input.id);\n}\n"]}

package/internal/crypto/blobEnvelopeError.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A blob envelope failed structural validation. Distinct from other errors so
+ * a caller can report a malformed envelope as the submitter's fault without
+ * also reporting its own faults that way.
+ */
+export declare class BlobEnvelopeError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}

package/internal/crypto/blobEnvelopeError.js

@@ -0,0 +1,12 @@
+/**
+ * A blob envelope failed structural validation. Distinct from other errors so
+ * a caller can report a malformed envelope as the submitter's fault without
+ * also reporting its own faults that way.
+ */
+export class BlobEnvelopeError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "BlobEnvelopeError";
+    }
+}
+//# sourceMappingURL=blobEnvelopeError.js.map

package/internal/crypto/blobEnvelopeError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blobEnvelopeError.js","sourceRoot":"","sources":["blobEnvelopeError.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe,EAAE,OAAsB;QACjD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF","sourcesContent":["/**\n * A blob envelope failed structural validation. Distinct from other errors so\n * a caller can report a malformed envelope as the submitter's fault without\n * also reporting its own faults that way.\n */\nexport class BlobEnvelopeError extends Error {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"BlobEnvelopeError\";\n  }\n}\n"]}

package/internal/crypto/blobEnvelopeFields.js

@@ -0,0 +1,34 @@
+import { BlobEnvelopeError } from "./blobEnvelopeError.js";
+export function readRecordString(record, key, label) {
+    const value = record[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new BlobEnvelopeError(`${label}.${key} must be a non-empty string`);
+    }
+    return value;
+}
+export function readRecordPositiveInteger(record, key, label) {
+    const value = record[key];
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+        throw new BlobEnvelopeError(`${label}.${key} must be a positive integer`);
+    }
+    return value;
+}
+const REPORTED_UNEXPECTED_KEYS = 3;
+const REPORTED_KEY_LENGTH = 32;
+/**
+ * Names at most a few offending keys, each truncated. The record is parsed
+ * from untrusted bytes bounded only by the header limit, so echoing every key
+ * back would put kilobytes of caller-chosen text into an error and its logs.
+ */
+export function assertOnlyRecordKeys(record, allowedKeys, label) {
+    const unexpectedKeys = Object.keys(record).filter((key) => !allowedKeys.has(key));
+    if (unexpectedKeys.length === 0)
+        return;
+    const named = unexpectedKeys
+        .slice(0, REPORTED_UNEXPECTED_KEYS)
+        .map((key) => JSON.stringify(key.slice(0, REPORTED_KEY_LENGTH)))
+        .join(",");
+    const remaining = unexpectedKeys.length - REPORTED_UNEXPECTED_KEYS;
+    throw new BlobEnvelopeError(`${label} has unexpected keys: ${named}${remaining > 0 ? ` and ${remaining} more` : ""}`);
+}
+//# sourceMappingURL=blobEnvelopeFields.js.map

package/internal/crypto/blobEnvelopeFields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blobEnvelopeFields.js","sourceRoot":"","sources":["blobEnvelopeFields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,UAAU,gBAAgB,CAC9B,MAA+B,EAC/B,GAAW,EACX,KAAa;IAEb,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,iBAAiB,CAAC,GAAG,KAAK,IAAI,GAAG,6BAA6B,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,MAA+B,EAC/B,GAAW,EACX,KAAa;IAEb,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC5E,MAAM,IAAI,iBAAiB,CAAC,GAAG,KAAK,IAAI,GAAG,6BAA6B,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,wBAAwB,GAAG,CAAC,CAAC;AACnC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAA+B,EAC/B,WAAgC,EAChC,KAAa;IAEb,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAC/C,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAC/B,CAAC;IACF,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACxC,MAAM,KAAK,GAAG,cAAc;SACzB,KAAK,CAAC,CAAC,EAAE,wBAAwB,CAAC;SAClC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC;SAC/D,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,MAAM,SAAS,GAAG,cAAc,CAAC,MAAM,GAAG,wBAAwB,CAAC;IACnE,MAAM,IAAI,iBAAiB,CACzB,GAAG,KAAK,yBAAyB,KAAK,GACpC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,SAAS,OAAO,CAAC,CAAC,CAAC,EAC7C,EAAE,CACH,CAAC;AACJ,CAAC","sourcesContent":["import { BlobEnvelopeError } from \"./blobEnvelopeError\";\n\nexport function readRecordString(\n  record: Record<string, unknown>,\n  key: string,\n  label: string,\n): string {\n  const value = record[key];\n  if (typeof value !== \"string\" || value.length === 0) {\n    throw new BlobEnvelopeError(`${label}.${key} must be a non-empty string`);\n  }\n  return value;\n}\n\nexport function readRecordPositiveInteger(\n  record: Record<string, unknown>,\n  key: string,\n  label: string,\n): number {\n  const value = record[key];\n  if (typeof value !== \"number\" || !Number.isSafeInteger(value) || value <= 0) {\n    throw new BlobEnvelopeError(`${label}.${key} must be a positive integer`);\n  }\n  return value;\n}\n\nconst REPORTED_UNEXPECTED_KEYS = 3;\nconst REPORTED_KEY_LENGTH = 32;\n\n/**\n * Names at most a few offending keys, each truncated. The record is parsed\n * from untrusted bytes bounded only by the header limit, so echoing every key\n * back would put kilobytes of caller-chosen text into an error and its logs.\n */\nexport function assertOnlyRecordKeys(\n  record: Record<string, unknown>,\n  allowedKeys: ReadonlySet<string>,\n  label: string,\n): void {\n  const unexpectedKeys = Object.keys(record).filter(\n    (key) => !allowedKeys.has(key),\n  );\n  if (unexpectedKeys.length === 0) return;\n  const named = unexpectedKeys\n    .slice(0, REPORTED_UNEXPECTED_KEYS)\n    .map((key) => JSON.stringify(key.slice(0, REPORTED_KEY_LENGTH)))\n    .join(\",\");\n  const remaining = unexpectedKeys.length - REPORTED_UNEXPECTED_KEYS;\n  throw new BlobEnvelopeError(\n    `${label} has unexpected keys: ${named}${\n      remaining > 0 ? ` and ${remaining} more` : \"\"\n    }`,\n  );\n}\n"]}

package/internal/crypto/blobEnvelopeReader.d.ts

@@ -0,0 +1,30 @@
+export interface BlobEnvelopeRecord {
+    blobId: string;
+    byteLength: number;
+    chunkCount: number;
+    chunks: BlobEnvelopeChunk[];
+    chunkSize: number;
+    contentKeyEpoch: number;
+    contentRecordId: string;
+    encryptedByteLength: number;
+    headerByteLength: number;
+    iv: Uint8Array;
+    metadataHash: string;
+    nonceDomainHash: string;
+}
+/**
+ * What the header alone establishes. It deliberately has no `chunks`: a
+ * header-only parse has not read the ciphertext, and an empty array there
+ * would read as an empty object rather than an unread one.
+ */
+export type BlobEnvelopeHeaderRecord = Omit<BlobEnvelopeRecord, "chunks">;
+interface BlobEnvelopeChunk {
+    ciphertext: Uint8Array<ArrayBuffer>;
+    index: number;
+    plaintextByteLength: number;
+}
+export declare const MAX_BLOB_ENVELOPE_HEADER_BYTES: number;
+export declare function readBlobEnvelopeHeaderByteLength(encryptedBytes: Uint8Array<ArrayBuffer>): number;
+export declare function parseBlobEnvelopeV2Header(encryptedBytes: Uint8Array<ArrayBuffer>): BlobEnvelopeHeaderRecord;
+export declare function parseBlobEnvelopeV2(encryptedBytes: Uint8Array<ArrayBuffer>): BlobEnvelopeRecord;
+export {};

package/internal/crypto/blobEnvelopeReader.js

@@ -0,0 +1,182 @@
+import { base64ToBytes, bytesToBase64 } from "../encoding/index.js";
+import { isPlainObject as isPlainRecord } from "../validators/isPlainObject.js";
+import { BlobEnvelopeError } from "./blobEnvelopeError.js";
+import { assertOnlyRecordKeys, readRecordPositiveInteger, readRecordString, } from "./blobEnvelopeFields.js";
+import { BLOB_ENCRYPTED_BYTES_FORMAT, BLOB_ENCRYPTED_BYTES_VERSION, BLOB_ENVELOPE_MAGIC_BYTES, BLOB_ENVELOPE_PREFIX_BYTES, blobChunkPlaintextByteLength, computeBlobChunkCount, computeBlobEncryptedByteLength, encodeBlobEnvelopeV2Header, } from "./blobEnvelopeV2.js";
+import { CONTENT_RECORD_ENCRYPTION_SUITE } from "./keying/types.js";
+import { AES_GCM_TAG_BYTES, assertAesGcmIv } from "./symmetric.js";
+const BLOB_ENCRYPTED_BYTES_KEYS = new Set([
+    "blobId",
+    "byteLength",
+    "chunkCount",
+    "chunkSize",
+    "contentKeyEpoch",
+    "contentRecordId",
+    "encryptionSuite",
+    "format",
+    "iv",
+    "metadataHash",
+    "nonceDomainHash",
+    "version",
+]);
+export const MAX_BLOB_ENVELOPE_HEADER_BYTES = 64 * 1024;
+const TEXT_DECODER = new TextDecoder("utf-8", { fatal: true });
+export function readBlobEnvelopeHeaderByteLength(encryptedBytes) {
+    if (encryptedBytes.byteLength < BLOB_ENVELOPE_PREFIX_BYTES) {
+        throw new BlobEnvelopeError("Blob encrypted bytes envelope is truncated");
+    }
+    for (let index = 0; index < BLOB_ENVELOPE_MAGIC_BYTES.byteLength; index += 1) {
+        if (encryptedBytes[index] !== BLOB_ENVELOPE_MAGIC_BYTES[index]) {
+            throw new BlobEnvelopeError("Blob encrypted bytes magic is invalid");
+        }
+    }
+    const headerPayloadByteLength = new DataView(encryptedBytes.buffer, encryptedBytes.byteOffset, encryptedBytes.byteLength).getUint32(BLOB_ENVELOPE_MAGIC_BYTES.byteLength);
+    if (headerPayloadByteLength === 0 ||
+        headerPayloadByteLength > MAX_BLOB_ENVELOPE_HEADER_BYTES) {
+        throw new BlobEnvelopeError("Blob encrypted bytes header length is invalid");
+    }
+    return BLOB_ENVELOPE_PREFIX_BYTES + headerPayloadByteLength;
+}
+function readHeaderValue(encryptedBytes) {
+    const headerByteLength = readBlobEnvelopeHeaderByteLength(encryptedBytes);
+    if (headerByteLength > encryptedBytes.byteLength) {
+        throw new BlobEnvelopeError("Blob encrypted bytes header is truncated");
+    }
+    let value;
+    try {
+        value = JSON.parse(TEXT_DECODER.decode(encryptedBytes.subarray(BLOB_ENVELOPE_PREFIX_BYTES, headerByteLength)));
+    }
+    catch {
+        throw new BlobEnvelopeError("Blob encrypted bytes are invalid JSON");
+    }
+    if (!isPlainRecord(value)) {
+        throw new BlobEnvelopeError("Blob encrypted bytes must be an object");
+    }
+    return { headerByteLength, value };
+}
+function readPlaintextByteLength(value) {
+    const byteLength = Reflect.get(value, "byteLength");
+    if (typeof byteLength !== "number" ||
+        !Number.isSafeInteger(byteLength) ||
+        byteLength < 0) {
+        throw new BlobEnvelopeError("Blob encrypted bytes.byteLength must be a non-negative safe integer");
+    }
+    return byteLength;
+}
+/**
+ * `base64ToBytes` and `assertAesGcmIv` belong to shared modules with their own
+ * error types, so both are wrapped: every structural rejection has to reach a
+ * caller as a BlobEnvelopeError to be reported as the submitter's fault.
+ */
+function readHeaderIv(value) {
+    const ivString = readRecordString(value, "iv", "Blob encrypted bytes");
+    let iv;
+    try {
+        iv = base64ToBytes(ivString);
+        assertAesGcmIv(iv, "Blob encrypted bytes IV is invalid");
+    }
+    catch (error) {
+        throw new BlobEnvelopeError("Blob encrypted bytes IV is invalid", {
+            cause: error,
+        });
+    }
+    if (bytesToBase64(iv) !== ivString) {
+        throw new BlobEnvelopeError("Blob encrypted bytes IV is not canonical base64");
+    }
+    return { iv, ivString };
+}
+function normalizeHeader(value) {
+    assertOnlyRecordKeys(value, BLOB_ENCRYPTED_BYTES_KEYS, "Blob encrypted bytes");
+    const format = readRecordString(value, "format", "Blob encrypted bytes");
+    if (format !== BLOB_ENCRYPTED_BYTES_FORMAT) {
+        throw new BlobEnvelopeError("Blob encrypted bytes format is invalid");
+    }
+    const version = readRecordPositiveInteger(value, "version", "Blob encrypted bytes");
+    if (version !== BLOB_ENCRYPTED_BYTES_VERSION) {
+        throw new BlobEnvelopeError(`Blob encrypted bytes version ${version} is invalid; expected ${BLOB_ENCRYPTED_BYTES_VERSION}`);
+    }
+    const encryptionSuite = readRecordString(value, "encryptionSuite", "Blob encrypted bytes");
+    if (encryptionSuite !== CONTENT_RECORD_ENCRYPTION_SUITE) {
+        throw new BlobEnvelopeError("Blob encrypted bytes suite is invalid");
+    }
+    const byteLength = readPlaintextByteLength(value);
+    const chunkCount = readRecordPositiveInteger(value, "chunkCount", "Blob encrypted bytes");
+    const chunkSize = readRecordPositiveInteger(value, "chunkSize", "Blob encrypted bytes");
+    if (chunkCount !== computeBlobChunkCount(byteLength, chunkSize)) {
+        throw new BlobEnvelopeError("Blob encrypted bytes chunk count is invalid");
+    }
+    const { iv, ivString } = readHeaderIv(value);
+    return {
+        header: {
+            blobId: readRecordString(value, "blobId", "Blob encrypted bytes"),
+            byteLength,
+            chunkCount,
+            chunkSize,
+            contentKeyEpoch: readRecordPositiveInteger(value, "contentKeyEpoch", "Blob encrypted bytes"),
+            contentRecordId: readRecordString(value, "contentRecordId", "Blob encrypted bytes"),
+            encryptionSuite,
+            format,
+            iv: ivString,
+            metadataHash: readRecordString(value, "metadataHash", "Blob encrypted bytes"),
+            nonceDomainHash: readRecordString(value, "nonceDomainHash", "Blob encrypted bytes"),
+            version,
+        },
+        iv,
+    };
+}
+function readEncryptedChunks(input) {
+    let chunkOffset = input.headerByteLength;
+    return Array.from({ length: input.header.chunkCount }, (_, index) => {
+        const plaintextByteLength = blobChunkPlaintextByteLength({
+            chunkCount: input.header.chunkCount,
+            chunkIndex: index,
+            chunkSize: input.header.chunkSize,
+            plaintextByteLength: input.header.byteLength,
+        });
+        const ciphertextByteLength = plaintextByteLength + AES_GCM_TAG_BYTES;
+        const ciphertext = new Uint8Array(input.encryptedBytes.buffer, input.encryptedBytes.byteOffset + chunkOffset, ciphertextByteLength);
+        chunkOffset += ciphertextByteLength;
+        return { ciphertext, index, plaintextByteLength };
+    });
+}
+export function parseBlobEnvelopeV2Header(encryptedBytes) {
+    const { headerByteLength, value } = readHeaderValue(encryptedBytes);
+    const { header, iv } = normalizeHeader(value);
+    const canonicalHeaderBytes = encodeBlobEnvelopeV2Header(header);
+    if (canonicalHeaderBytes.byteLength !== headerByteLength ||
+        canonicalHeaderBytes.some((byte, index) => byte !== encryptedBytes[index])) {
+        throw new BlobEnvelopeError("Blob encrypted bytes header is not canonical");
+    }
+    const expectedByteLength = computeBlobEncryptedByteLength({
+        chunkCount: header.chunkCount,
+        headerByteLength,
+        plaintextByteLength: header.byteLength,
+    });
+    return {
+        blobId: header.blobId,
+        byteLength: header.byteLength,
+        chunkCount: header.chunkCount,
+        chunkSize: header.chunkSize,
+        contentKeyEpoch: header.contentKeyEpoch,
+        contentRecordId: header.contentRecordId,
+        encryptedByteLength: expectedByteLength,
+        headerByteLength,
+        iv,
+        metadataHash: header.metadataHash,
+        nonceDomainHash: header.nonceDomainHash,
+    };
+}
+export function parseBlobEnvelopeV2(encryptedBytes) {
+    const encrypted = parseBlobEnvelopeV2Header(encryptedBytes);
+    if (encryptedBytes.byteLength !== encrypted.encryptedByteLength)
+        throw new BlobEnvelopeError("Blob encrypted bytes length is invalid");
+    return {
+        ...encrypted,
+        chunks: readEncryptedChunks({
+            encryptedBytes,
+            header: encrypted,
+            headerByteLength: encrypted.headerByteLength,
+        }),
+    };
+}
+//# sourceMappingURL=blobEnvelopeReader.js.map

package/internal/crypto/blobEnvelopeReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blobEnvelopeReader.js","sourceRoot":"","sources":["blobEnvelopeReader.ts"],"names":[],"mappings":"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","sourcesContent":["import { base64ToBytes, bytesToBase64 } from \"@tearleads/encoding\";\nimport { isPlainObject as isPlainRecord } from \"@tearleads/validators/isPlainObject\";\nimport { BlobEnvelopeError } from \"./blobEnvelopeError\";\nimport {\n  assertOnlyRecordKeys,\n  readRecordPositiveInteger,\n  readRecordString,\n} from \"./blobEnvelopeFields\";\nimport {\n  BLOB_ENCRYPTED_BYTES_FORMAT,\n  BLOB_ENCRYPTED_BYTES_VERSION,\n  BLOB_ENVELOPE_MAGIC_BYTES,\n  BLOB_ENVELOPE_PREFIX_BYTES,\n  type BlobEnvelopeV2Header,\n  blobChunkPlaintextByteLength,\n  computeBlobChunkCount,\n  computeBlobEncryptedByteLength,\n  encodeBlobEnvelopeV2Header,\n} from \"./blobEnvelopeV2\";\nimport { CONTENT_RECORD_ENCRYPTION_SUITE } from \"./keying/types\";\nimport { AES_GCM_TAG_BYTES, assertAesGcmIv } from \"./symmetric\";\n\nexport interface BlobEnvelopeRecord {\n  blobId: string;\n  byteLength: number;\n  chunkCount: number;\n  chunks: BlobEnvelopeChunk[];\n  chunkSize: number;\n  contentKeyEpoch: number;\n  contentRecordId: string;\n  encryptedByteLength: number;\n  headerByteLength: number;\n  iv: Uint8Array;\n  metadataHash: string;\n  nonceDomainHash: string;\n}\n/**\n * What the header alone establishes. It deliberately has no `chunks`: a\n * header-only parse has not read the ciphertext, and an empty array there\n * would read as an empty object rather than an unread one.\n */\nexport type BlobEnvelopeHeaderRecord = Omit<BlobEnvelopeRecord, \"chunks\">;\ninterface BlobEnvelopeChunk {\n  ciphertext: Uint8Array<ArrayBuffer>;\n  index: number;\n  plaintextByteLength: number;\n}\nconst BLOB_ENCRYPTED_BYTES_KEYS = new Set([\n  \"blobId\",\n  \"byteLength\",\n  \"chunkCount\",\n  \"chunkSize\",\n  \"contentKeyEpoch\",\n  \"contentRecordId\",\n  \"encryptionSuite\",\n  \"format\",\n  \"iv\",\n  \"metadataHash\",\n  \"nonceDomainHash\",\n  \"version\",\n]);\n\nexport const MAX_BLOB_ENVELOPE_HEADER_BYTES = 64 * 1024;\nconst TEXT_DECODER = new TextDecoder(\"utf-8\", { fatal: true });\n\nexport function readBlobEnvelopeHeaderByteLength(\n  encryptedBytes: Uint8Array<ArrayBuffer>,\n): number {\n  if (encryptedBytes.byteLength < BLOB_ENVELOPE_PREFIX_BYTES) {\n    throw new BlobEnvelopeError(\"Blob encrypted bytes envelope is truncated\");\n  }\n  for (\n    let index = 0;\n    index < BLOB_ENVELOPE_MAGIC_BYTES.byteLength;\n    index += 1\n  ) {\n    if (encryptedBytes[index] !== BLOB_ENVELOPE_MAGIC_BYTES[index]) {\n      throw new BlobEnvelopeError(\"Blob encrypted bytes magic is invalid\");\n    }\n  }\n  const headerPayloadByteLength = new DataView(\n    encryptedBytes.buffer,\n    encryptedBytes.byteOffset,\n    encryptedBytes.byteLength,\n  ).getUint32(BLOB_ENVELOPE_MAGIC_BYTES.byteLength);\n  if (\n    headerPayloadByteLength === 0 ||\n    headerPayloadByteLength > MAX_BLOB_ENVELOPE_HEADER_BYTES\n  ) {\n    throw new BlobEnvelopeError(\n      \"Blob encrypted bytes header length is invalid\",\n    );\n  }\n  return BLOB_ENVELOPE_PREFIX_BYTES + headerPayloadByteLength;\n}\n\nfunction readHeaderValue(encryptedBytes: Uint8Array<ArrayBuffer>): {\n  readonly headerByteLength: number;\n  readonly value: Record<string, unknown>;\n} {\n  const headerByteLength = readBlobEnvelopeHeaderByteLength(encryptedBytes);\n  if (headerByteLength > encryptedBytes.byteLength) {\n    throw new BlobEnvelopeError(\"Blob encrypted bytes header is truncated\");\n  }\n\n  let value: unknown;\n  try {\n    value = JSON.parse(\n      TEXT_DECODER.decode(\n        encryptedBytes.subarray(BLOB_ENVELOPE_PREFIX_BYTES, headerByteLength),\n      ),\n    );\n  } catch {\n    throw new BlobEnvelopeError(\"Blob encrypted bytes are invalid JSON\");\n  }\n  if (!isPlainRecord(value)) {\n    throw new BlobEnvelopeError(\"Blob encrypted bytes must be an object\");\n  }\n  return { headerByteLength, value };\n}\n\nfunction readPlaintextByteLength(value: Record<string, unknown>): number {\n  const byteLength = Reflect.get(value, \"byteLength\");\n  if (\n    typeof byteLength !== \"number\" ||\n    !Number.isSafeInteger(byteLength) ||\n    byteLength < 0\n  ) {\n    throw new BlobEnvelopeError(\n      \"Blob encrypted bytes.byteLength must be a non-negative safe integer\",\n    );\n  }\n  return byteLength;\n}\n\n/**\n * `base64ToBytes` and `assertAesGcmIv` belong to shared modules with their own\n * error types, so both are wrapped: every structural rejection has to reach a\n * caller as a BlobEnvelopeError to be reported as the submitter's fault.\n */\nfunction readHeaderIv(value: Record<string, unknown>): {\n  readonly iv: Uint8Array;\n  readonly ivString: string;\n} {\n  const ivString = readRecordString(value, \"iv\", \"Blob encrypted bytes\");\n  let iv: Uint8Array;\n  try {\n    iv = base64ToBytes(ivString);\n    assertAesGcmIv(iv, \"Blob encrypted bytes IV is invalid\");\n  } catch (error) {\n    throw new BlobEnvelopeError(\"Blob encrypted bytes IV is invalid\", {\n      cause: error,\n    });\n  }\n  if (bytesToBase64(iv) !== ivString) {\n    throw new BlobEnvelopeError(\n      \"Blob encrypted bytes IV is not canonical base64\",\n    );\n  }\n  return { iv, ivString };\n}\n\nfunction normalizeHeader(value: Record<string, unknown>): {\n  readonly header: BlobEnvelopeV2Header;\n  readonly iv: Uint8Array;\n} {\n  assertOnlyRecordKeys(\n    value,\n    BLOB_ENCRYPTED_BYTES_KEYS,\n    \"Blob encrypted bytes\",\n  );\n  const format = readRecordString(value, \"format\", \"Blob encrypted bytes\");\n  if (format !== BLOB_ENCRYPTED_BYTES_FORMAT) {\n    throw new BlobEnvelopeError(\"Blob encrypted bytes format is invalid\");\n  }\n  const version = readRecordPositiveInteger(\n    value,\n    \"version\",\n    \"Blob encrypted bytes\",\n  );\n  if (version !== BLOB_ENCRYPTED_BYTES_VERSION) {\n    throw new BlobEnvelopeError(\n      `Blob encrypted bytes version ${version} is invalid; expected ${BLOB_ENCRYPTED_BYTES_VERSION}`,\n    );\n  }\n  const encryptionSuite = readRecordString(\n    value,\n    \"encryptionSuite\",\n    \"Blob encrypted bytes\",\n  );\n  if (encryptionSuite !== CONTENT_RECORD_ENCRYPTION_SUITE) {\n    throw new BlobEnvelopeError(\"Blob encrypted bytes suite is invalid\");\n  }\n  const byteLength = readPlaintextByteLength(value);\n  const chunkCount = readRecordPositiveInteger(\n    value,\n    \"chunkCount\",\n    \"Blob encrypted bytes\",\n  );\n  const chunkSize = readRecordPositiveInteger(\n    value,\n    \"chunkSize\",\n    \"Blob encrypted bytes\",\n  );\n  if (chunkCount !== computeBlobChunkCount(byteLength, chunkSize)) {\n    throw new BlobEnvelopeError(\"Blob encrypted bytes chunk count is invalid\");\n  }\n  const { iv, ivString } = readHeaderIv(value);\n  return {\n    header: {\n      blobId: readRecordString(value, \"blobId\", \"Blob encrypted bytes\"),\n      byteLength,\n      chunkCount,\n      chunkSize,\n      contentKeyEpoch: readRecordPositiveInteger(\n        value,\n        \"contentKeyEpoch\",\n        \"Blob encrypted bytes\",\n      ),\n      contentRecordId: readRecordString(\n        value,\n        \"contentRecordId\",\n        \"Blob encrypted bytes\",\n      ),\n      encryptionSuite,\n      format,\n      iv: ivString,\n      metadataHash: readRecordString(\n        value,\n        \"metadataHash\",\n        \"Blob encrypted bytes\",\n      ),\n      nonceDomainHash: readRecordString(\n        value,\n        \"nonceDomainHash\",\n        \"Blob encrypted bytes\",\n      ),\n      version,\n    },\n    iv,\n  };\n}\n\nfunction readEncryptedChunks(input: {\n  readonly encryptedBytes: Uint8Array<ArrayBuffer>;\n  readonly header: Pick<\n    BlobEnvelopeV2Header,\n    \"byteLength\" | \"chunkCount\" | \"chunkSize\"\n  >;\n  readonly headerByteLength: number;\n}): BlobEnvelopeChunk[] {\n  let chunkOffset = input.headerByteLength;\n  return Array.from({ length: input.header.chunkCount }, (_, index) => {\n    const plaintextByteLength = blobChunkPlaintextByteLength({\n      chunkCount: input.header.chunkCount,\n      chunkIndex: index,\n      chunkSize: input.header.chunkSize,\n      plaintextByteLength: input.header.byteLength,\n    });\n    const ciphertextByteLength = plaintextByteLength + AES_GCM_TAG_BYTES;\n    const ciphertext = new Uint8Array(\n      input.encryptedBytes.buffer,\n      input.encryptedBytes.byteOffset + chunkOffset,\n      ciphertextByteLength,\n    );\n    chunkOffset += ciphertextByteLength;\n    return { ciphertext, index, plaintextByteLength };\n  });\n}\n\nexport function parseBlobEnvelopeV2Header(\n  encryptedBytes: Uint8Array<ArrayBuffer>,\n): BlobEnvelopeHeaderRecord {\n  const { headerByteLength, value } = readHeaderValue(encryptedBytes);\n  const { header, iv } = normalizeHeader(value);\n  const canonicalHeaderBytes = encodeBlobEnvelopeV2Header(header);\n  if (\n    canonicalHeaderBytes.byteLength !== headerByteLength ||\n    canonicalHeaderBytes.some((byte, index) => byte !== encryptedBytes[index])\n  ) {\n    throw new BlobEnvelopeError(\"Blob encrypted bytes header is not canonical\");\n  }\n  const expectedByteLength = computeBlobEncryptedByteLength({\n    chunkCount: header.chunkCount,\n    headerByteLength,\n    plaintextByteLength: header.byteLength,\n  });\n  return {\n    blobId: header.blobId,\n    byteLength: header.byteLength,\n    chunkCount: header.chunkCount,\n    chunkSize: header.chunkSize,\n    contentKeyEpoch: header.contentKeyEpoch,\n    contentRecordId: header.contentRecordId,\n    encryptedByteLength: expectedByteLength,\n    headerByteLength,\n    iv,\n    metadataHash: header.metadataHash,\n    nonceDomainHash: header.nonceDomainHash,\n  };\n}\n\nexport function parseBlobEnvelopeV2(\n  encryptedBytes: Uint8Array<ArrayBuffer>,\n): BlobEnvelopeRecord {\n  const encrypted = parseBlobEnvelopeV2Header(encryptedBytes);\n  if (encryptedBytes.byteLength !== encrypted.encryptedByteLength)\n    throw new BlobEnvelopeError(\"Blob encrypted bytes length is invalid\");\n  return {\n    ...encrypted,\n    chunks: readEncryptedChunks({\n      encryptedBytes,\n      header: encrypted,\n      headerByteLength: encrypted.headerByteLength,\n    }),\n  };\n}\n"]}