@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/media-storage-path.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * `storagePath` is CLIENT DATA, and it addresses the shared bucket (AGL-1881).
+ *
+ * ## The hole this closes
+ *
+ * A media document records the object key its bytes live at, and seven code
+ * paths read that field and hand it straight to `bucket.file(...)` on the
+ * ADMIN SDK — which bypasses `cloud/firebase-storage.rules` entirely, because
+ * Admin credentials are not subject to them. The field was writable by any org
+ * editor or host editor:
+ *
+ * - `orgs/{orgId}/media/{id}` — the dedicated rule freezes only `visibleTo`.
+ * - `hosts/{hostId}/media/{id}` — `media` appears in NEITHER the create nor the
+ *   update exclusion list of the host catch-all, so `canWriteHostContent` is
+ *   the whole gate.
+ *
+ * So a legitimate editor could point their own media document at any object
+ * key in the bucket and then reach it through the paths that trust the field:
+ * `serveMediaCdn` streams it to an anonymous caller behind an edge-cached URL,
+ * `/api/media/replace` overwrites it, and the folder delete removes it. Read,
+ * overwrite and destroy, all cross-tenant, all from a document the attacker is
+ * supposed to own.
+ *
+ * The bucket is shared and holds more than customer media: `orgs/{orgId}/`,
+ * the legacy `hosts/{hostId}/media/`, `users/{uid}/` avatars, and — the part
+ * that makes this worse than "read another tenant's images" — the
+ * `adminAudit-archive/` and `erasures/` retention prefixes, which are FIXED and
+ * guessable rather than needing a stolen object key.
+ *
+ * ## Why the fix lives here and not only in the rules
+ *
+ * Freezing the field in the rules is right and is being done alongside this,
+ * but it is the second layer, not the first. Rules are deployed separately
+ * from code, staff writes bypass them, and a future writer could reintroduce
+ * the field legitimately. The durable invariant is at the SINK: an object key
+ * derived from a document must address that document's own scope, and that is
+ * checkable without trusting anything.
+ *
+ * ## The invariant
+ *
+ * Every writer in the repo — `media/upload`, `media/upload-url`, the v1 media
+ * create, and the folder relocation — builds the key as
+ * `` `${base}/media/` + optional folder path + mediaId ``, where `base` is
+ * `orgs/{orgId}` or `hosts/{hostId}`. There is no legitimate key outside
+ * `${base}/media/`, so that is the prefix required here rather than the looser
+ * `${base}/`.
+ */
+/**
+ * True when `candidate` is an object key that genuinely lives under this
+ * scope's media prefix.
+ *
+ * Traversal is rejected rather than normalized. GCS object keys are literal
+ * strings — `a/../b` is a key containing dots, not a path that resolves — so
+ * `..` cannot escape a prefix in the bucket itself. It is refused anyway
+ * because these keys are also handed to `File.copy`, tooling and log lines
+ * that may not share that property, and because a `..` in a key this repo
+ * writes is by construction not one this repo wrote.
+ */
+export declare function isMediaStoragePathInScope(candidate: unknown, base: string): boolean;
+/**
+ * The object key for a media document: the recorded `storagePath` when it is
+ * genuinely in scope, otherwise the legacy flat layout.
+ *
+ * Falling back rather than throwing is deliberate. The fallback names the
+ * document's OWN object, so a tampered record addresses nothing but itself —
+ * a read 404s, a delete removes a key that does not exist, and a replace
+ * writes where the asset should have been. Throwing would turn a tampered
+ * document into a 500 on a route that other, innocent assets share, which
+ * trades a contained failure for a noisy one.
+ *
+ * `onRefused` exists because a refusal here is not a normal condition: every
+ * writer in the repo produces an in-scope key, so a refused one means the
+ * document was written by something else. Callers that can log should.
+ */
+export declare function mediaStoragePathInScope(options: {
+    storagePath: unknown;
+    base: string;
+    mediaId: string;
+    onRefused?: (candidate: unknown) => void;
+}): string;

package/src/lib/server/media-storage-path.js

@@ -0,0 +1,111 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * `storagePath` is CLIENT DATA, and it addresses the shared bucket (AGL-1881).
+ *
+ * ## The hole this closes
+ *
+ * A media document records the object key its bytes live at, and seven code
+ * paths read that field and hand it straight to `bucket.file(...)` on the
+ * ADMIN SDK — which bypasses `cloud/firebase-storage.rules` entirely, because
+ * Admin credentials are not subject to them. The field was writable by any org
+ * editor or host editor:
+ *
+ * - `orgs/{orgId}/media/{id}` — the dedicated rule freezes only `visibleTo`.
+ * - `hosts/{hostId}/media/{id}` — `media` appears in NEITHER the create nor the
+ *   update exclusion list of the host catch-all, so `canWriteHostContent` is
+ *   the whole gate.
+ *
+ * So a legitimate editor could point their own media document at any object
+ * key in the bucket and then reach it through the paths that trust the field:
+ * `serveMediaCdn` streams it to an anonymous caller behind an edge-cached URL,
+ * `/api/media/replace` overwrites it, and the folder delete removes it. Read,
+ * overwrite and destroy, all cross-tenant, all from a document the attacker is
+ * supposed to own.
+ *
+ * The bucket is shared and holds more than customer media: `orgs/{orgId}/`,
+ * the legacy `hosts/{hostId}/media/`, `users/{uid}/` avatars, and — the part
+ * that makes this worse than "read another tenant's images" — the
+ * `adminAudit-archive/` and `erasures/` retention prefixes, which are FIXED and
+ * guessable rather than needing a stolen object key.
+ *
+ * ## Why the fix lives here and not only in the rules
+ *
+ * Freezing the field in the rules is right and is being done alongside this,
+ * but it is the second layer, not the first. Rules are deployed separately
+ * from code, staff writes bypass them, and a future writer could reintroduce
+ * the field legitimately. The durable invariant is at the SINK: an object key
+ * derived from a document must address that document's own scope, and that is
+ * checkable without trusting anything.
+ *
+ * ## The invariant
+ *
+ * Every writer in the repo — `media/upload`, `media/upload-url`, the v1 media
+ * create, and the folder relocation — builds the key as
+ * `` `${base}/media/` + optional folder path + mediaId ``, where `base` is
+ * `orgs/{orgId}` or `hosts/{hostId}`. There is no legitimate key outside
+ * `${base}/media/`, so that is the prefix required here rather than the looser
+ * `${base}/`.
+ */ /**
+ * True when `candidate` is an object key that genuinely lives under this
+ * scope's media prefix.
+ *
+ * Traversal is rejected rather than normalized. GCS object keys are literal
+ * strings — `a/../b` is a key containing dots, not a path that resolves — so
+ * `..` cannot escape a prefix in the bucket itself. It is refused anyway
+ * because these keys are also handed to `File.copy`, tooling and log lines
+ * that may not share that property, and because a `..` in a key this repo
+ * writes is by construction not one this repo wrote.
+ */ export function isMediaStoragePathInScope(candidate, base) {
+    if (typeof candidate !== 'string') return false;
+    const value = candidate.trim();
+    if (!value || value !== candidate) return false;
+    if (!base) return false;
+    const prefix = `${base}/media/`;
+    if (!value.startsWith(prefix)) return false;
+    // Something has to follow the prefix; the prefix alone is a folder.
+    if (value.length === prefix.length) return false;
+    if (value.includes('//')) return false;
+    return !value.split('/').includes('..');
+}
+/**
+ * The object key for a media document: the recorded `storagePath` when it is
+ * genuinely in scope, otherwise the legacy flat layout.
+ *
+ * Falling back rather than throwing is deliberate. The fallback names the
+ * document's OWN object, so a tampered record addresses nothing but itself —
+ * a read 404s, a delete removes a key that does not exist, and a replace
+ * writes where the asset should have been. Throwing would turn a tampered
+ * document into a 500 on a route that other, innocent assets share, which
+ * trades a contained failure for a noisy one.
+ *
+ * `onRefused` exists because a refusal here is not a normal condition: every
+ * writer in the repo produces an in-scope key, so a refused one means the
+ * document was written by something else. Callers that can log should.
+ */ export function mediaStoragePathInScope(options) {
+    const { storagePath, base, mediaId } = options;
+    const fallback = `${base}/media/${mediaId}`;
+    if (storagePath === undefined || storagePath === null || storagePath === '') {
+        // The ordinary legacy case — the field predates real folders. Not a
+        // refusal, and must not be reported as one.
+        return fallback;
+    }
+    if (isMediaStoragePathInScope(storagePath, base)) return storagePath;
+    options.onRefused == null ? void 0 : options.onRefused.call(options, storagePath);
+    return fallback;
+}
+
+//# sourceMappingURL=media-storage-path.js.map

package/src/lib/server/media-storage-path.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/media-storage-path.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * `storagePath` is CLIENT DATA, and it addresses the shared bucket (AGL-1881).\n *\n * ## The hole this closes\n *\n * A media document records the object key its bytes live at, and seven code\n * paths read that field and hand it straight to `bucket.file(...)` on the\n * ADMIN SDK — which bypasses `cloud/firebase-storage.rules` entirely, because\n * Admin credentials are not subject to them. The field was writable by any org\n * editor or host editor:\n *\n * - `orgs/{orgId}/media/{id}` — the dedicated rule freezes only `visibleTo`.\n * - `hosts/{hostId}/media/{id}` — `media` appears in NEITHER the create nor the\n *   update exclusion list of the host catch-all, so `canWriteHostContent` is\n *   the whole gate.\n *\n * So a legitimate editor could point their own media document at any object\n * key in the bucket and then reach it through the paths that trust the field:\n * `serveMediaCdn` streams it to an anonymous caller behind an edge-cached URL,\n * `/api/media/replace` overwrites it, and the folder delete removes it. Read,\n * overwrite and destroy, all cross-tenant, all from a document the attacker is\n * supposed to own.\n *\n * The bucket is shared and holds more than customer media: `orgs/{orgId}/`,\n * the legacy `hosts/{hostId}/media/`, `users/{uid}/` avatars, and — the part\n * that makes this worse than \"read another tenant's images\" — the\n * `adminAudit-archive/` and `erasures/` retention prefixes, which are FIXED and\n * guessable rather than needing a stolen object key.\n *\n * ## Why the fix lives here and not only in the rules\n *\n * Freezing the field in the rules is right and is being done alongside this,\n * but it is the second layer, not the first. Rules are deployed separately\n * from code, staff writes bypass them, and a future writer could reintroduce\n * the field legitimately. The durable invariant is at the SINK: an object key\n * derived from a document must address that document's own scope, and that is\n * checkable without trusting anything.\n *\n * ## The invariant\n *\n * Every writer in the repo — `media/upload`, `media/upload-url`, the v1 media\n * create, and the folder relocation — builds the key as\n * `` `${base}/media/` + optional folder path + mediaId ``, where `base` is\n * `orgs/{orgId}` or `hosts/{hostId}`. There is no legitimate key outside\n * `${base}/media/`, so that is the prefix required here rather than the looser\n * `${base}/`.\n */\n\n/**\n * True when `candidate` is an object key that genuinely lives under this\n * scope's media prefix.\n *\n * Traversal is rejected rather than normalized. GCS object keys are literal\n * strings — `a/../b` is a key containing dots, not a path that resolves — so\n * `..` cannot escape a prefix in the bucket itself. It is refused anyway\n * because these keys are also handed to `File.copy`, tooling and log lines\n * that may not share that property, and because a `..` in a key this repo\n * writes is by construction not one this repo wrote.\n */\nexport function isMediaStoragePathInScope(\n  candidate: unknown,\n  base: string,\n): boolean {\n  if (typeof candidate !== 'string') return false\n  const value = candidate.trim()\n  if (!value || value !== candidate) return false\n  if (!base) return false\n  const prefix = `${base}/media/`\n  if (!value.startsWith(prefix)) return false\n  // Something has to follow the prefix; the prefix alone is a folder.\n  if (value.length === prefix.length) return false\n  if (value.includes('//')) return false\n  return !value.split('/').includes('..')\n}\n\n/**\n * The object key for a media document: the recorded `storagePath` when it is\n * genuinely in scope, otherwise the legacy flat layout.\n *\n * Falling back rather than throwing is deliberate. The fallback names the\n * document's OWN object, so a tampered record addresses nothing but itself —\n * a read 404s, a delete removes a key that does not exist, and a replace\n * writes where the asset should have been. Throwing would turn a tampered\n * document into a 500 on a route that other, innocent assets share, which\n * trades a contained failure for a noisy one.\n *\n * `onRefused` exists because a refusal here is not a normal condition: every\n * writer in the repo produces an in-scope key, so a refused one means the\n * document was written by something else. Callers that can log should.\n */\nexport function mediaStoragePathInScope(options: {\n  storagePath: unknown\n  base: string\n  mediaId: string\n  onRefused?: (candidate: unknown) => void\n}): string {\n  const { storagePath, base, mediaId } = options\n  const fallback = `${base}/media/${mediaId}`\n  if (storagePath === undefined || storagePath === null || storagePath === '') {\n    // The ordinary legacy case — the field predates real folders. Not a\n    // refusal, and must not be reported as one.\n    return fallback\n  }\n  if (isMediaStoragePathInScope(storagePath, base)) return storagePath as string\n  options.onRefused?.(storagePath)\n  return fallback\n}\n"],"names":["isMediaStoragePathInScope","candidate","base","value","trim","prefix","startsWith","length","includes","split","mediaStoragePathInScope","options","storagePath","mediaId","fallback","undefined","onRefused"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CC,GAED;;;;;;;;;;CAUC,GACD,OAAO,SAASA,0BACdC,SAAkB,EAClBC,IAAY;IAEZ,IAAI,OAAOD,cAAc,UAAU,OAAO;IAC1C,MAAME,QAAQF,UAAUG,IAAI;IAC5B,IAAI,CAACD,SAASA,UAAUF,WAAW,OAAO;IAC1C,IAAI,CAACC,MAAM,OAAO;IAClB,MAAMG,SAAS,GAAGH,KAAK,OAAO,CAAC;IAC/B,IAAI,CAACC,MAAMG,UAAU,CAACD,SAAS,OAAO;IACtC,oEAAoE;IACpE,IAAIF,MAAMI,MAAM,KAAKF,OAAOE,MAAM,EAAE,OAAO;IAC3C,IAAIJ,MAAMK,QAAQ,CAAC,OAAO,OAAO;IACjC,OAAO,CAACL,MAAMM,KAAK,CAAC,KAAKD,QAAQ,CAAC;AACpC;AAEA;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASE,wBAAwBC,OAKvC;IACC,MAAM,EAAEC,WAAW,EAAEV,IAAI,EAAEW,OAAO,EAAE,GAAGF;IACvC,MAAMG,WAAW,GAAGZ,KAAK,OAAO,EAAEW,SAAS;IAC3C,IAAID,gBAAgBG,aAAaH,gBAAgB,QAAQA,gBAAgB,IAAI;QAC3E,oEAAoE;QACpE,4CAA4C;QAC5C,OAAOE;IACT;IACA,IAAId,0BAA0BY,aAAaV,OAAO,OAAOU;IACzDD,QAAQK,SAAS,oBAAjBL,QAAQK,SAAS,MAAjBL,SAAoBC;IACpB,OAAOE;AACT"}

package/src/lib/server/media-strong-digest.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The largest object this path will digest.
+ *
+ * Deliberately equal to the largest non-video `signedMaxBytes` in
+ * `apps/console/utils/media-upload-limits.ts` (ZIP, `.pptx`). Raising it
+ * only ever adds video; lowering it silently strips the strong key off a
+ * document type that has one today, which is why the spec asserts the
+ * number instead of trusting it.
+ */
+export declare const MEDIA_STRONG_DIGEST_MAX_BYTES: number;
+/** Why no digest was taken. Absent when one was. */
+export type StrongDigestSkip = 'over-ceiling' | 'unreadable';
+export interface StoredObjectDigest {
+    /** Lower-case hex sha256 of the whole object, or absent. */
+    sha256?: string;
+    /** Set when — and only when — `sha256` is absent. */
+    skipped?: StrongDigestSkip;
+    /** Bytes actually pulled out of the bucket. Zero when the bound bit. */
+    bytesRead: number;
+    /**
+     * The largest single buffer held while hashing.
+     *
+     * Exported because it is the only externally checkable evidence that this
+     * function streams rather than buffers — a caller, a log line or a spec
+     * can distinguish the two without reading the implementation. It is also
+     * the number that would move first if someone "simplified" this back to
+     * `file.download()`.
+     */
+    peakChunkBytes: number;
+}
+/**
+ * May an object of this size be digested?
+ *
+ * A pure predicate so the route and the spec (AGL-1630) apply ONE rule
+ * rather than copies that drift.
+ *
+ * An unknown, zero or non-finite size answers `false`, never `true`. GCS
+ * reports no size for a composite object, and guessing "small" there means
+ * starting an unbounded read on the exact shape that cannot be bounded.
+ */
+export declare function strongDigestWithinCeiling(sizeBytes: number, maxBytes?: number): boolean;
+/** The minimal Storage surface this needs; injectable for tests. */
+export interface DigestibleStorageFile {
+    createReadStream: (options?: unknown) => NodeJS.ReadableStream;
+}
+/**
+ * Stream one stored object through sha256.
+ *
+ * FAILS SOFT, in both directions, and that is the whole safety argument:
+ *
+ * * An unreadable object returns `unreadable`, not a throw. The callers are
+ *   an upload finalize and a backfill; a Storage blip must not start
+ *   refusing uploads, matching the fail-open posture of the ranged
+ *   inspection above it and the deny-list read below it.
+ * * A stream that ends SHORT — a truncated range, a proxy cutting the body,
+ *   a mid-flight reset — returns `unreadable` rather than the digest of
+ *   what did arrive. A partial digest is worse than none: it is a
+ *   well-formed 64-hex value that matches nothing, and because
+ *   `mediaQuarantineKeys` PREFERS the strong digest, writing one would
+ *   shadow the legacy hash that would otherwise have matched. That is a
+ *   takedown quietly lifting itself, which is the one failure this whole
+ *   subsystem may not have.
+ */
+export declare function storedObjectSha256(options: {
+    file: DigestibleStorageFile;
+    /** The object's real size, as Storage reports it. */
+    sizeBytes: number;
+    maxBytes?: number;
+}): Promise<StoredObjectDigest>;

package/src/lib/server/media-strong-digest.js

@@ -0,0 +1,190 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * A BOUNDED strong content digest for objects the server never held
+ * (AGL-1629) — the decision AGL-1614 deferred, taken now that AGL-1475
+ * changed what it costs.
+ *
+ * ## What changed since the question was asked
+ *
+ * AGL-1614 wrote `contentSha256` only where the bytes were already in hand,
+ * and argued — correctly, at the time — that the signed-upload route could
+ * not have one: the browser PUTs straight to GCS, GCS computes md5 and
+ * crc32c but never sha256, and `file.download()` on a 200 MB video is the
+ * exact cost the route exists to avoid. The conclusion was "needs a
+ * product call on cost".
+ *
+ * AGL-1475 (`c607678ee`) then made finalize read bytes anyway — a 4 KB head
+ * and, for document archives, a 64 KB tail — to inspect structure. The
+ * route is no longer byte-blind, and the honest question is no longer
+ * "download or not" but "how much".
+ *
+ * ## The measurement the decision rests on
+ *
+ * Production media bucket, `gs://aglyn-main.appspot.com`, read-only listing
+ * on 2026-08-20: **182 source objects, 44,774,216 bytes (42.70 MiB)** —
+ * plus 269 derived `__wNNN.webp` variants, which carry no media document
+ * and need no digest. Largest single object **7,742,225 B (7.38 MiB)**;
+ * mean 246 KB; 177 of 182 under 1 MB; **nothing above 10 MiB and no video
+ * at all**. Hashing the entire back catalogue is ~$0.005 of egress.
+ *
+ * So the "200 MB video" that made this expensive is a CEILING, not a
+ * population. It still has to be handled — a ceiling is what an attacker
+ * aims at — but it must not be allowed to price the other 99%.
+ *
+ * ## The decision
+ *
+ * Digest every signed upload up to {@link MEDIA_STRONG_DIGEST_MAX_BYTES},
+ * by STREAMING; above it, write nothing and degrade exactly as before.
+ *
+ * **Why 50 MiB and not a rounder number.** It is precisely the largest
+ * NON-VIDEO ceiling on the signed route: ZIP is 50 MB and `.pptx` is 50 MB,
+ * PDF and the Office types are 25 MB, images are 15 MB. At 50 MiB every
+ * type except video is covered *at its own maximum* — there is no size at
+ * which a PDF or a brand-kit zip silently loses its strong digest. Only
+ * video (200 MB) can exceed it, and only past 50 MB.
+ *
+ * **What the bound costs, precisely.** One additional full read of the
+ * object, capped at 50 MiB. GCS internet egress is ~$0.12/GiB, so the
+ * worst case is **$0.0057 per upload** and the measured mean case is
+ * **$0.00003**. sha256 in Node runs at roughly 500 MB/s, so the CPU is
+ * ~0.1 s at the ceiling. The route already declares `maxDuration = 60` and
+ * already budgets a 15 MB download plus three `sharp` encodes inside it.
+ *
+ * **What the bound buys.**
+ *
+ *  1. **Cross-route matching, which was previously impossible.** The
+ *     in-process routes key on sha256 of the bytes; this route keyed on a
+ *     16-hex truncation of GCS's md5. The same file through the two paths
+ *     produced two unrelated keys, so "re-uploading the same bytes stays
+ *     quarantined" held within an ingestion path and not across them. Under
+ *     the ceiling it now holds across them. That is the headline.
+ *  2. **The md5 collision target goes away** for everything under the
+ *     ceiling. A chosen-prefix md5 collision is hours of ordinary compute
+ *     and yields two files sharing the 64-bit truncation — a cross-tenant
+ *     availability attack an outsider could mount. The preferred key stops
+ *     being md5-derived.
+ *  3. **Ingestion refusal actually works** on the signed route for known
+ *     bytes, rather than only at delivery via the per-asset fallback.
+ *
+ * **What it does not buy, stated rather than implied.** Video above 50 MB
+ * carries no `contentSha256` and never will on this path. That is the
+ * bounded alternative, not a pretence of completeness: such an object
+ * matches on the legacy truncated hash and on its per-asset key, exactly as
+ * every signed upload did before this module existed. Video is also the
+ * type least plausibly a chosen-prefix collision target or a
+ * shared-bytes malware carrier, which is why it is the class the bound
+ * sacrifices.
+ *
+ * ## Why streaming rather than `download()`
+ *
+ * `file.download()` resolves a single Buffer. At the ceiling that is 50 MiB
+ * of function heap on a path that is concurrently holding a `sharp`
+ * pipeline. Streaming through the hash keeps the resident set at one chunk
+ * regardless of object size, which is what makes a 50 MiB bound safe to
+ * state at all. The spec asserts the peak rather than only the hex, because
+ * a hex-only assertion passes just as happily against a buffering
+ * implementation.
+ */ import { createHash } from "node:crypto";
+/**
+ * The largest object this path will digest.
+ *
+ * Deliberately equal to the largest non-video `signedMaxBytes` in
+ * `apps/console/utils/media-upload-limits.ts` (ZIP, `.pptx`). Raising it
+ * only ever adds video; lowering it silently strips the strong key off a
+ * document type that has one today, which is why the spec asserts the
+ * number instead of trusting it.
+ */ export const MEDIA_STRONG_DIGEST_MAX_BYTES = 50 * 1024 * 1024;
+/**
+ * May an object of this size be digested?
+ *
+ * A pure predicate so the route and the spec (AGL-1630) apply ONE rule
+ * rather than copies that drift.
+ *
+ * An unknown, zero or non-finite size answers `false`, never `true`. GCS
+ * reports no size for a composite object, and guessing "small" there means
+ * starting an unbounded read on the exact shape that cannot be bounded.
+ */ export function strongDigestWithinCeiling(sizeBytes, maxBytes = MEDIA_STRONG_DIGEST_MAX_BYTES) {
+    if (typeof sizeBytes !== 'number' || !Number.isFinite(sizeBytes)) return false;
+    if (sizeBytes <= 0) return false;
+    return sizeBytes <= maxBytes;
+}
+/**
+ * Stream one stored object through sha256.
+ *
+ * FAILS SOFT, in both directions, and that is the whole safety argument:
+ *
+ * * An unreadable object returns `unreadable`, not a throw. The callers are
+ *   an upload finalize and a backfill; a Storage blip must not start
+ *   refusing uploads, matching the fail-open posture of the ranged
+ *   inspection above it and the deny-list read below it.
+ * * A stream that ends SHORT — a truncated range, a proxy cutting the body,
+ *   a mid-flight reset — returns `unreadable` rather than the digest of
+ *   what did arrive. A partial digest is worse than none: it is a
+ *   well-formed 64-hex value that matches nothing, and because
+ *   `mediaQuarantineKeys` PREFERS the strong digest, writing one would
+ *   shadow the legacy hash that would otherwise have matched. That is a
+ *   takedown quietly lifting itself, which is the one failure this whole
+ *   subsystem may not have.
+ */ export async function storedObjectSha256(options) {
+    var _options_maxBytes;
+    const { file, sizeBytes } = options;
+    const maxBytes = (_options_maxBytes = options.maxBytes) != null ? _options_maxBytes : MEDIA_STRONG_DIGEST_MAX_BYTES;
+    // Before any egress, not after — a bound that reads and discards costs
+    // exactly what it exists to save.
+    if (!strongDigestWithinCeiling(sizeBytes, maxBytes)) {
+        return {
+            skipped: 'over-ceiling',
+            bytesRead: 0,
+            peakChunkBytes: 0
+        };
+    }
+    const hash = createHash('sha256');
+    let bytesRead = 0;
+    let peakChunkBytes = 0;
+    try {
+        const stream = file.createReadStream();
+        for await (const chunk of stream){
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            if (buffer.length > peakChunkBytes) peakChunkBytes = buffer.length;
+            bytesRead += buffer.length;
+            hash.update(new Uint8Array(buffer));
+        }
+    } catch (error) {
+        console.error('[media] strong digest read failed', error);
+        return {
+            skipped: 'unreadable',
+            bytesRead,
+            peakChunkBytes
+        };
+    }
+    if (bytesRead !== sizeBytes) {
+        // See the fail-soft note above: a short read is not a small file.
+        console.error('[media] strong digest read short', `expected ${sizeBytes} bytes, read ${bytesRead}`);
+        return {
+            skipped: 'unreadable',
+            bytesRead,
+            peakChunkBytes
+        };
+    }
+    return {
+        sha256: hash.digest('hex'),
+        bytesRead,
+        peakChunkBytes
+    };
+}
+
+//# sourceMappingURL=media-strong-digest.js.map

package/src/lib/server/media-strong-digest.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/media-strong-digest.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A BOUNDED strong content digest for objects the server never held\n * (AGL-1629) — the decision AGL-1614 deferred, taken now that AGL-1475\n * changed what it costs.\n *\n * ## What changed since the question was asked\n *\n * AGL-1614 wrote `contentSha256` only where the bytes were already in hand,\n * and argued — correctly, at the time — that the signed-upload route could\n * not have one: the browser PUTs straight to GCS, GCS computes md5 and\n * crc32c but never sha256, and `file.download()` on a 200 MB video is the\n * exact cost the route exists to avoid. The conclusion was \"needs a\n * product call on cost\".\n *\n * AGL-1475 (`c607678ee`) then made finalize read bytes anyway — a 4 KB head\n * and, for document archives, a 64 KB tail — to inspect structure. The\n * route is no longer byte-blind, and the honest question is no longer\n * \"download or not\" but \"how much\".\n *\n * ## The measurement the decision rests on\n *\n * Production media bucket, `gs://aglyn-main.appspot.com`, read-only listing\n * on 2026-08-20: **182 source objects, 44,774,216 bytes (42.70 MiB)** —\n * plus 269 derived `__wNNN.webp` variants, which carry no media document\n * and need no digest. Largest single object **7,742,225 B (7.38 MiB)**;\n * mean 246 KB; 177 of 182 under 1 MB; **nothing above 10 MiB and no video\n * at all**. Hashing the entire back catalogue is ~$0.005 of egress.\n *\n * So the \"200 MB video\" that made this expensive is a CEILING, not a\n * population. It still has to be handled — a ceiling is what an attacker\n * aims at — but it must not be allowed to price the other 99%.\n *\n * ## The decision\n *\n * Digest every signed upload up to {@link MEDIA_STRONG_DIGEST_MAX_BYTES},\n * by STREAMING; above it, write nothing and degrade exactly as before.\n *\n * **Why 50 MiB and not a rounder number.** It is precisely the largest\n * NON-VIDEO ceiling on the signed route: ZIP is 50 MB and `.pptx` is 50 MB,\n * PDF and the Office types are 25 MB, images are 15 MB. At 50 MiB every\n * type except video is covered *at its own maximum* — there is no size at\n * which a PDF or a brand-kit zip silently loses its strong digest. Only\n * video (200 MB) can exceed it, and only past 50 MB.\n *\n * **What the bound costs, precisely.** One additional full read of the\n * object, capped at 50 MiB. GCS internet egress is ~$0.12/GiB, so the\n * worst case is **$0.0057 per upload** and the measured mean case is\n * **$0.00003**. sha256 in Node runs at roughly 500 MB/s, so the CPU is\n * ~0.1 s at the ceiling. The route already declares `maxDuration = 60` and\n * already budgets a 15 MB download plus three `sharp` encodes inside it.\n *\n * **What the bound buys.**\n *\n *  1. **Cross-route matching, which was previously impossible.** The\n *     in-process routes key on sha256 of the bytes; this route keyed on a\n *     16-hex truncation of GCS's md5. The same file through the two paths\n *     produced two unrelated keys, so \"re-uploading the same bytes stays\n *     quarantined\" held within an ingestion path and not across them. Under\n *     the ceiling it now holds across them. That is the headline.\n *  2. **The md5 collision target goes away** for everything under the\n *     ceiling. A chosen-prefix md5 collision is hours of ordinary compute\n *     and yields two files sharing the 64-bit truncation — a cross-tenant\n *     availability attack an outsider could mount. The preferred key stops\n *     being md5-derived.\n *  3. **Ingestion refusal actually works** on the signed route for known\n *     bytes, rather than only at delivery via the per-asset fallback.\n *\n * **What it does not buy, stated rather than implied.** Video above 50 MB\n * carries no `contentSha256` and never will on this path. That is the\n * bounded alternative, not a pretence of completeness: such an object\n * matches on the legacy truncated hash and on its per-asset key, exactly as\n * every signed upload did before this module existed. Video is also the\n * type least plausibly a chosen-prefix collision target or a\n * shared-bytes malware carrier, which is why it is the class the bound\n * sacrifices.\n *\n * ## Why streaming rather than `download()`\n *\n * `file.download()` resolves a single Buffer. At the ceiling that is 50 MiB\n * of function heap on a path that is concurrently holding a `sharp`\n * pipeline. Streaming through the hash keeps the resident set at one chunk\n * regardless of object size, which is what makes a 50 MiB bound safe to\n * state at all. The spec asserts the peak rather than only the hex, because\n * a hex-only assertion passes just as happily against a buffering\n * implementation.\n */\n\nimport { createHash } from 'node:crypto'\n\n/**\n * The largest object this path will digest.\n *\n * Deliberately equal to the largest non-video `signedMaxBytes` in\n * `apps/console/utils/media-upload-limits.ts` (ZIP, `.pptx`). Raising it\n * only ever adds video; lowering it silently strips the strong key off a\n * document type that has one today, which is why the spec asserts the\n * number instead of trusting it.\n */\nexport const MEDIA_STRONG_DIGEST_MAX_BYTES = 50 * 1024 * 1024\n\n/** Why no digest was taken. Absent when one was. */\nexport type StrongDigestSkip = 'over-ceiling' | 'unreadable'\n\nexport interface StoredObjectDigest {\n  /** Lower-case hex sha256 of the whole object, or absent. */\n  sha256?: string\n  /** Set when — and only when — `sha256` is absent. */\n  skipped?: StrongDigestSkip\n  /** Bytes actually pulled out of the bucket. Zero when the bound bit. */\n  bytesRead: number\n  /**\n   * The largest single buffer held while hashing.\n   *\n   * Exported because it is the only externally checkable evidence that this\n   * function streams rather than buffers — a caller, a log line or a spec\n   * can distinguish the two without reading the implementation. It is also\n   * the number that would move first if someone \"simplified\" this back to\n   * `file.download()`.\n   */\n  peakChunkBytes: number\n}\n\n/**\n * May an object of this size be digested?\n *\n * A pure predicate so the route and the spec (AGL-1630) apply ONE rule\n * rather than copies that drift.\n *\n * An unknown, zero or non-finite size answers `false`, never `true`. GCS\n * reports no size for a composite object, and guessing \"small\" there means\n * starting an unbounded read on the exact shape that cannot be bounded.\n */\nexport function strongDigestWithinCeiling(\n  sizeBytes: number,\n  maxBytes: number = MEDIA_STRONG_DIGEST_MAX_BYTES,\n): boolean {\n  if (typeof sizeBytes !== 'number' || !Number.isFinite(sizeBytes)) return false\n  if (sizeBytes <= 0) return false\n  return sizeBytes <= maxBytes\n}\n\n/** The minimal Storage surface this needs; injectable for tests. */\nexport interface DigestibleStorageFile {\n  createReadStream: (options?: unknown) => NodeJS.ReadableStream\n}\n\n/**\n * Stream one stored object through sha256.\n *\n * FAILS SOFT, in both directions, and that is the whole safety argument:\n *\n * * An unreadable object returns `unreadable`, not a throw. The callers are\n *   an upload finalize and a backfill; a Storage blip must not start\n *   refusing uploads, matching the fail-open posture of the ranged\n *   inspection above it and the deny-list read below it.\n * * A stream that ends SHORT — a truncated range, a proxy cutting the body,\n *   a mid-flight reset — returns `unreadable` rather than the digest of\n *   what did arrive. A partial digest is worse than none: it is a\n *   well-formed 64-hex value that matches nothing, and because\n *   `mediaQuarantineKeys` PREFERS the strong digest, writing one would\n *   shadow the legacy hash that would otherwise have matched. That is a\n *   takedown quietly lifting itself, which is the one failure this whole\n *   subsystem may not have.\n */\nexport async function storedObjectSha256(options: {\n  file: DigestibleStorageFile\n  /** The object's real size, as Storage reports it. */\n  sizeBytes: number\n  maxBytes?: number\n}): Promise<StoredObjectDigest> {\n  const { file, sizeBytes } = options\n  const maxBytes = options.maxBytes ?? MEDIA_STRONG_DIGEST_MAX_BYTES\n\n  // Before any egress, not after — a bound that reads and discards costs\n  // exactly what it exists to save.\n  if (!strongDigestWithinCeiling(sizeBytes, maxBytes)) {\n    return { skipped: 'over-ceiling', bytesRead: 0, peakChunkBytes: 0 }\n  }\n\n  const hash = createHash('sha256')\n  let bytesRead = 0\n  let peakChunkBytes = 0\n  try {\n    const stream = file.createReadStream()\n    for await (const chunk of stream as AsyncIterable<Buffer | string>) {\n      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))\n      if (buffer.length > peakChunkBytes) peakChunkBytes = buffer.length\n      bytesRead += buffer.length\n      hash.update(new Uint8Array(buffer))\n    }\n  } catch (error) {\n    console.error('[media] strong digest read failed', error)\n    return { skipped: 'unreadable', bytesRead, peakChunkBytes }\n  }\n\n  if (bytesRead !== sizeBytes) {\n    // See the fail-soft note above: a short read is not a small file.\n    console.error(\n      '[media] strong digest read short',\n      `expected ${sizeBytes} bytes, read ${bytesRead}`,\n    )\n    return { skipped: 'unreadable', bytesRead, peakChunkBytes }\n  }\n\n  return { sha256: hash.digest('hex'), bytesRead, peakChunkBytes }\n}\n"],"names":["createHash","MEDIA_STRONG_DIGEST_MAX_BYTES","strongDigestWithinCeiling","sizeBytes","maxBytes","Number","isFinite","storedObjectSha256","options","file","skipped","bytesRead","peakChunkBytes","hash","stream","createReadStream","chunk","buffer","Buffer","isBuffer","from","String","length","update","Uint8Array","error","console","sha256","digest"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqFC,GAED,SAASA,UAAU,QAAQ,cAAa;AAExC;;;;;;;;CAQC,GACD,OAAO,MAAMC,gCAAgC,KAAK,OAAO,KAAI;AAwB7D;;;;;;;;;CASC,GACD,OAAO,SAASC,0BACdC,SAAiB,EACjBC,WAAmBH,6BAA6B;IAEhD,IAAI,OAAOE,cAAc,YAAY,CAACE,OAAOC,QAAQ,CAACH,YAAY,OAAO;IACzE,IAAIA,aAAa,GAAG,OAAO;IAC3B,OAAOA,aAAaC;AACtB;AAOA;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,eAAeG,mBAAmBC,OAKxC;QAEkBA;IADjB,MAAM,EAAEC,IAAI,EAAEN,SAAS,EAAE,GAAGK;IAC5B,MAAMJ,YAAWI,oBAAAA,QAAQJ,QAAQ,YAAhBI,oBAAoBP;IAErC,uEAAuE;IACvE,kCAAkC;IAClC,IAAI,CAACC,0BAA0BC,WAAWC,WAAW;QACnD,OAAO;YAAEM,SAAS;YAAgBC,WAAW;YAAGC,gBAAgB;QAAE;IACpE;IAEA,MAAMC,OAAOb,WAAW;IACxB,IAAIW,YAAY;IAChB,IAAIC,iBAAiB;IACrB,IAAI;QACF,MAAME,SAASL,KAAKM,gBAAgB;QACpC,WAAW,MAAMC,SAASF,OAA0C;YAClE,MAAMG,SAASC,OAAOC,QAAQ,CAACH,SAASA,QAAQE,OAAOE,IAAI,CAACC,OAAOL;YACnE,IAAIC,OAAOK,MAAM,GAAGV,gBAAgBA,iBAAiBK,OAAOK,MAAM;YAClEX,aAAaM,OAAOK,MAAM;YAC1BT,KAAKU,MAAM,CAAC,IAAIC,WAAWP;QAC7B;IACF,EAAE,OAAOQ,OAAO;QACdC,QAAQD,KAAK,CAAC,qCAAqCA;QACnD,OAAO;YAAEf,SAAS;YAAcC;YAAWC;QAAe;IAC5D;IAEA,IAAID,cAAcR,WAAW;QAC3B,kEAAkE;QAClEuB,QAAQD,KAAK,CACX,oCACA,CAAC,SAAS,EAAEtB,UAAU,aAAa,EAAEQ,WAAW;QAElD,OAAO;YAAED,SAAS;YAAcC;YAAWC;QAAe;IAC5D;IAEA,OAAO;QAAEe,QAAQd,KAAKe,MAAM,CAAC;QAAQjB;QAAWC;IAAe;AACjE"}