@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/upload-cors.d.ts

@@ -0,0 +1,155 @@
+/**
+ * @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.
+ */
+/**
+ * Which origins may complete a signed direct-to-GCS upload (AGL-1452).
+ *
+ * ## The fact this module exists for
+ *
+ * **GCS matches the CORS `origin` list as an exact string.** There is no
+ * subtree form and no wildcard form short of `*`. Measured against the live
+ * bucket on 2026-08-20 by driving real preflights: `https://app.aglyn.com`
+ * answers with `Access-Control-Allow-Origin`, while `https://console.aglyn.com`,
+ * `https://app.aglyn.io`, `https://zgover.aglyn.com`, `http://app.aglyn.com`
+ * and `https://app.aglyn.com.evil.example` all answer 200 with **no CORS
+ * headers at all** — which is how the browser refuses the `PUT`.
+ *
+ * This is the OPPOSITE of the App Check reCAPTCHA allowlist, which matches a
+ * listed name and everything beneath it. Both are "allowed domains for the
+ * platform", so reasoning across from one to the other is the natural move and
+ * gives exactly the wrong answer.
+ *
+ * ## Why it bites, and only sometimes
+ *
+ * The signed direct-to-GCS path carries video, PDF and ZIP above
+ * `SIGNED_UPLOAD_MAX_BYTES`; ordinary images take the base64 route and are
+ * unaffected. So a missing origin fails **only on large files**, behind a
+ * generic "try again" snackbar with no diagnosable cause — the same silence
+ * that let AGL-1408 ship with no CORS rule at all.
+ *
+ * A console origin appears whenever a name is attached to the project WITHOUT
+ * a redirect. Attached WITH one, the browser never holds that origin — it is
+ * already at the redirect target when it uploads — which is why
+ * `console.aglyn.com` needs no entry and `zgover.aglyn.com` does.
+ *
+ * ## Why `*` is not on the table
+ *
+ * The signed URL carries the authorization. A wildcard would let any site on
+ * the internet spend one that leaks. {@link permitsUploadOrigin} still reports
+ * a wildcard as permitting, because its job is to describe the bucket
+ * truthfully — a check that called `*` "missing" would report a failure while
+ * the uploads it watches were in fact wide open. {@link mergeUploadOrigins} is
+ * where we refuse to ever write one.
+ *
+ * ## Why a MERGE
+ *
+ * `gcloud storage buckets update --cors-file` **replaces** the configuration
+ * rather than merging it. Automation that builds a fresh document from the
+ * origins it happens to know about silently drops every other customer's
+ * origin, and the symptom lands on them, days later, as a failed large upload
+ * nobody can attribute. Everything here is read-modify-write.
+ */
+export interface CorsRule {
+    origin?: string[];
+    method?: string[];
+    responseHeader?: string[];
+    maxAgeSeconds?: number;
+}
+/** The method the DAM uploader issues. Parsed out of it by `storage-cors.spec.ts`. */
+export declare const UPLOAD_CORS_METHOD = "PUT";
+/** The headers that `PUT` sets, which the preflight answers from. */
+export declare const UPLOAD_CORS_RESPONSE_HEADERS: string[];
+/** One hour, matching `cloud/storage-cors.json`. */
+export declare const UPLOAD_CORS_MAX_AGE_SECONDS = 3600;
+/**
+ * The origin a browser on `host` will actually put in the `Origin` header.
+ *
+ * Accepts a bare hostname or a URL, because callers hold both shapes: a
+ * console-domain claim stores a hostname and `NEXT_PUBLIC_CONSOLE_URL` carries
+ * a scheme. Null for anything that is not a hostname — including `*`, which is
+ * never a thing this function will hand onward.
+ */
+export declare function uploadOriginFor(host: string): string | null;
+/**
+ * Would this bucket configuration let a browser at `origin` complete the
+ * signed `PUT`?
+ *
+ * Exact comparison, deliberately: matching loosely here would make this agree
+ * with the intuition and disagree with GCS, which is the whole failure being
+ * guarded against.
+ */
+export declare function permitsUploadOrigin(rules: CorsRule[] | null | undefined, origin: string): boolean;
+/**
+ * The origins this configuration would refuse, in the order asked.
+ *
+ * A null configuration — the read failed, the bucket is unreachable — covers
+ * NOTHING. Reporting calm because we could not look is the shape of alarm that
+ * has already cost this repo three outages.
+ */
+export declare function missingUploadOrigins(rules: CorsRule[] | null | undefined, origins: string[]): string[];
+/**
+ * The configuration to WRITE so `origins` can upload, preserving everything
+ * already permitted.
+ *
+ * Adds to the existing upload rule where there is one, so the policy does not
+ * grow a rule per customer. Throws on a wildcard rather than returning an
+ * error, because there is no caller for whom emitting one is the right
+ * outcome and a returned error is a thing a caller can ignore.
+ */
+export declare function mergeUploadOrigins(rules: CorsRule[], origins: string[]): {
+    rules: CorsRule[];
+    added: string[];
+};
+/**
+ * The configuration to WRITE so `origins` are no longer permitted, keeping
+ * everything else (AGL-1452).
+ *
+ * ## Why a detach has to do this
+ *
+ * An origin outlives the name unless something removes it. For an
+ * `*.aglyn.com` subdomain that is untidy. For a **white-label console domain**
+ * it is a standing permission on a bucket that accepts signed writes, granted
+ * to a host the customer keeps and we no longer serve — and the signed URL
+ * carries its own authorization, so that host can spend one that leaks. A
+ * stale CORS origin is therefore worse than a stale reCAPTCHA entry, not
+ * merely equivalent to one.
+ *
+ * ## `keep` is not optional in practice
+ *
+ * The platform origin is configured, not provisioned. Removing it would break
+ * large uploads for every customer at once — the platform-wide outage the
+ * read-modify-write warning is about, reached from the other direction. Every
+ * caller passes it.
+ *
+ * A rule left with no origins is DROPPED rather than written as `origin: []`.
+ * GCS accepts the empty form, and it reads to the next person like a rule that
+ * permits something.
+ */
+export declare function revokeUploadOrigins(rules: CorsRule[], origins: string[], { keep }?: {
+    keep?: string[];
+}): {
+    rules: CorsRule[];
+    removed: string[];
+    refused: string[];
+};
+/**
+ * What a human must run when the automation could not.
+ *
+ * Carries the warning as well as the command: the obvious one-liner is the
+ * destructive one, and an instruction that omits that is how the read-modify-
+ * write rule gets skipped by the person following it in a hurry.
+ */
+export declare function uploadCorsRemedy(bucket: string, missing: string[]): string;

package/src/lib/app-utils/upload-cors.js

@@ -0,0 +1,254 @@
+/**
+ * @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.
+ */ /**
+ * Which origins may complete a signed direct-to-GCS upload (AGL-1452).
+ *
+ * ## The fact this module exists for
+ *
+ * **GCS matches the CORS `origin` list as an exact string.** There is no
+ * subtree form and no wildcard form short of `*`. Measured against the live
+ * bucket on 2026-08-20 by driving real preflights: `https://app.aglyn.com`
+ * answers with `Access-Control-Allow-Origin`, while `https://console.aglyn.com`,
+ * `https://app.aglyn.io`, `https://zgover.aglyn.com`, `http://app.aglyn.com`
+ * and `https://app.aglyn.com.evil.example` all answer 200 with **no CORS
+ * headers at all** — which is how the browser refuses the `PUT`.
+ *
+ * This is the OPPOSITE of the App Check reCAPTCHA allowlist, which matches a
+ * listed name and everything beneath it. Both are "allowed domains for the
+ * platform", so reasoning across from one to the other is the natural move and
+ * gives exactly the wrong answer.
+ *
+ * ## Why it bites, and only sometimes
+ *
+ * The signed direct-to-GCS path carries video, PDF and ZIP above
+ * `SIGNED_UPLOAD_MAX_BYTES`; ordinary images take the base64 route and are
+ * unaffected. So a missing origin fails **only on large files**, behind a
+ * generic "try again" snackbar with no diagnosable cause — the same silence
+ * that let AGL-1408 ship with no CORS rule at all.
+ *
+ * A console origin appears whenever a name is attached to the project WITHOUT
+ * a redirect. Attached WITH one, the browser never holds that origin — it is
+ * already at the redirect target when it uploads — which is why
+ * `console.aglyn.com` needs no entry and `zgover.aglyn.com` does.
+ *
+ * ## Why `*` is not on the table
+ *
+ * The signed URL carries the authorization. A wildcard would let any site on
+ * the internet spend one that leaks. {@link permitsUploadOrigin} still reports
+ * a wildcard as permitting, because its job is to describe the bucket
+ * truthfully — a check that called `*` "missing" would report a failure while
+ * the uploads it watches were in fact wide open. {@link mergeUploadOrigins} is
+ * where we refuse to ever write one.
+ *
+ * ## Why a MERGE
+ *
+ * `gcloud storage buckets update --cors-file` **replaces** the configuration
+ * rather than merging it. Automation that builds a fresh document from the
+ * origins it happens to know about silently drops every other customer's
+ * origin, and the symptom lands on them, days later, as a failed large upload
+ * nobody can attribute. Everything here is read-modify-write.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+/** The method the DAM uploader issues. Parsed out of it by `storage-cors.spec.ts`. */ export const UPLOAD_CORS_METHOD = 'PUT';
+/** The headers that `PUT` sets, which the preflight answers from. */ export const UPLOAD_CORS_RESPONSE_HEADERS = [
+    'Content-Type',
+    'x-goog-resumable'
+];
+/** One hour, matching `cloud/storage-cors.json`. */ export const UPLOAD_CORS_MAX_AGE_SECONDS = 3600;
+const HOSTNAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+/**
+ * The origin a browser on `host` will actually put in the `Origin` header.
+ *
+ * Accepts a bare hostname or a URL, because callers hold both shapes: a
+ * console-domain claim stores a hostname and `NEXT_PUBLIC_CONSOLE_URL` carries
+ * a scheme. Null for anything that is not a hostname — including `*`, which is
+ * never a thing this function will hand onward.
+ */ export function uploadOriginFor(host) {
+    const raw = String(host != null ? host : '').trim().toLowerCase();
+    if (!raw) return null;
+    const bare = raw.replace(/^[a-z][a-z0-9+.-]*:\/\//, '').split(/[/?#]/)[0].replace(/\.$/, '');
+    return HOSTNAME.test(bare) ? `https://${bare}` : null;
+}
+function uploadRules(rules) {
+    return rules.filter((rule)=>{
+        var _rule_method;
+        return ((_rule_method = rule.method) != null ? _rule_method : []).some((method)=>method.toUpperCase() === UPLOAD_CORS_METHOD);
+    });
+}
+/**
+ * Would this bucket configuration let a browser at `origin` complete the
+ * signed `PUT`?
+ *
+ * Exact comparison, deliberately: matching loosely here would make this agree
+ * with the intuition and disagree with GCS, which is the whole failure being
+ * guarded against.
+ */ export function permitsUploadOrigin(rules, origin) {
+    if (!rules) return false;
+    return uploadRules(rules).some((rule)=>{
+        var _rule_origin;
+        return ((_rule_origin = rule.origin) != null ? _rule_origin : []).some((listed)=>listed === '*' || listed === origin);
+    });
+}
+/**
+ * The origins this configuration would refuse, in the order asked.
+ *
+ * A null configuration — the read failed, the bucket is unreachable — covers
+ * NOTHING. Reporting calm because we could not look is the shape of alarm that
+ * has already cost this repo three outages.
+ */ export function missingUploadOrigins(rules, origins) {
+    return origins.filter((origin)=>!permitsUploadOrigin(rules, origin));
+}
+/**
+ * The configuration to WRITE so `origins` can upload, preserving everything
+ * already permitted.
+ *
+ * Adds to the existing upload rule where there is one, so the policy does not
+ * grow a rule per customer. Throws on a wildcard rather than returning an
+ * error, because there is no caller for whom emitting one is the right
+ * outcome and a returned error is a thing a caller can ignore.
+ */ export function mergeUploadOrigins(rules, origins) {
+    if (origins.some((origin)=>String(origin).includes('*'))) {
+        throw new Error('refusing to write a wildcard CORS origin: the signed URL carries the ' + 'authorization, so `*` lets any site spend one that leaks (AGL-1452)');
+    }
+    const wanted = [
+        ...new Set(origins)
+    ];
+    const missing = missingUploadOrigins(rules, wanted);
+    if (missing.length === 0) return {
+        rules,
+        added: []
+    };
+    const target = rules.findIndex((rule)=>uploadRules([
+            rule
+        ]).length === 1);
+    if (target < 0) {
+        return {
+            rules: [
+                ...rules,
+                {
+                    origin: missing,
+                    method: [
+                        UPLOAD_CORS_METHOD
+                    ],
+                    responseHeader: [
+                        ...UPLOAD_CORS_RESPONSE_HEADERS
+                    ],
+                    maxAgeSeconds: UPLOAD_CORS_MAX_AGE_SECONDS
+                }
+            ],
+            added: missing
+        };
+    }
+    const next = rules.map((rule, index)=>{
+        var _rule_origin;
+        return index === target ? _extends({}, rule, {
+            origin: [
+                ...new Set([
+                    ...(_rule_origin = rule.origin) != null ? _rule_origin : [],
+                    ...missing
+                ])
+            ]
+        }) : rule;
+    });
+    return {
+        rules: next,
+        added: missing
+    };
+}
+/**
+ * The configuration to WRITE so `origins` are no longer permitted, keeping
+ * everything else (AGL-1452).
+ *
+ * ## Why a detach has to do this
+ *
+ * An origin outlives the name unless something removes it. For an
+ * `*.aglyn.com` subdomain that is untidy. For a **white-label console domain**
+ * it is a standing permission on a bucket that accepts signed writes, granted
+ * to a host the customer keeps and we no longer serve — and the signed URL
+ * carries its own authorization, so that host can spend one that leaks. A
+ * stale CORS origin is therefore worse than a stale reCAPTCHA entry, not
+ * merely equivalent to one.
+ *
+ * ## `keep` is not optional in practice
+ *
+ * The platform origin is configured, not provisioned. Removing it would break
+ * large uploads for every customer at once — the platform-wide outage the
+ * read-modify-write warning is about, reached from the other direction. Every
+ * caller passes it.
+ *
+ * A rule left with no origins is DROPPED rather than written as `origin: []`.
+ * GCS accepts the empty form, and it reads to the next person like a rule that
+ * permits something.
+ */ export function revokeUploadOrigins(rules, origins, { keep = [] } = {}) {
+    const protectedSet = new Set(keep);
+    const asked = [
+        ...new Set(origins.map((origin)=>String(origin)))
+    ];
+    const refused = asked.filter((origin)=>origin === '*' || protectedSet.has(origin));
+    const doomed = new Set(asked.filter((origin)=>!refused.includes(origin)));
+    if (doomed.size === 0) return {
+        rules,
+        removed: [],
+        refused
+    };
+    const removed = [];
+    const next = [];
+    for (const rule of rules){
+        var _rule_origin;
+        if (uploadRules([
+            rule
+        ]).length !== 1) {
+            next.push(rule);
+            continue;
+        }
+        const kept = ((_rule_origin = rule.origin) != null ? _rule_origin : []).filter((origin)=>{
+            if (!doomed.has(String(origin))) return true;
+            removed.push(String(origin));
+            return false;
+        });
+        if (kept.length > 0) next.push(_extends({}, rule, {
+            origin: kept
+        }));
+    }
+    return {
+        rules: next,
+        removed,
+        refused
+    };
+}
+/**
+ * What a human must run when the automation could not.
+ *
+ * Carries the warning as well as the command: the obvious one-liner is the
+ * destructive one, and an instruction that omits that is how the read-modify-
+ * write rule gets skipped by the person following it in a hurry.
+ */ export function uploadCorsRemedy(bucket, missing) {
+    return [
+        `Large (resumable) uploads from ${missing.join(', ')} will fail until`,
+        `gs://${bucket} permits ${missing.length === 1 ? 'that origin' : 'those origins'}.`,
+        'GCS matches the CORS origin list EXACTLY — there is no subtree form, so',
+        'each origin needs its own entry.',
+        '',
+        '  gcloud storage buckets describe gs://' + bucket + ' --format=json\\(cors_config\\) > cors.json',
+        '  # edit cors.json: ADD the origins above to the rule whose method is PUT',
+        `  gcloud storage buckets update gs://${bucket} --cors-file=cors.json`,
+        '',
+        '⚠️ --cors-file REPLACES the configuration rather than merging it. Read the',
+        'live document, add to it, write it back — building a fresh one drops every',
+        'other origin, and that failure lands on someone else, days later.'
+    ].join('\n');
+}
+
+//# sourceMappingURL=upload-cors.js.map

package/src/lib/app-utils/upload-cors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/upload-cors.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 * Which origins may complete a signed direct-to-GCS upload (AGL-1452).\n *\n * ## The fact this module exists for\n *\n * **GCS matches the CORS `origin` list as an exact string.** There is no\n * subtree form and no wildcard form short of `*`. Measured against the live\n * bucket on 2026-08-20 by driving real preflights: `https://app.aglyn.com`\n * answers with `Access-Control-Allow-Origin`, while `https://console.aglyn.com`,\n * `https://app.aglyn.io`, `https://zgover.aglyn.com`, `http://app.aglyn.com`\n * and `https://app.aglyn.com.evil.example` all answer 200 with **no CORS\n * headers at all** — which is how the browser refuses the `PUT`.\n *\n * This is the OPPOSITE of the App Check reCAPTCHA allowlist, which matches a\n * listed name and everything beneath it. Both are \"allowed domains for the\n * platform\", so reasoning across from one to the other is the natural move and\n * gives exactly the wrong answer.\n *\n * ## Why it bites, and only sometimes\n *\n * The signed direct-to-GCS path carries video, PDF and ZIP above\n * `SIGNED_UPLOAD_MAX_BYTES`; ordinary images take the base64 route and are\n * unaffected. So a missing origin fails **only on large files**, behind a\n * generic \"try again\" snackbar with no diagnosable cause — the same silence\n * that let AGL-1408 ship with no CORS rule at all.\n *\n * A console origin appears whenever a name is attached to the project WITHOUT\n * a redirect. Attached WITH one, the browser never holds that origin — it is\n * already at the redirect target when it uploads — which is why\n * `console.aglyn.com` needs no entry and `zgover.aglyn.com` does.\n *\n * ## Why `*` is not on the table\n *\n * The signed URL carries the authorization. A wildcard would let any site on\n * the internet spend one that leaks. {@link permitsUploadOrigin} still reports\n * a wildcard as permitting, because its job is to describe the bucket\n * truthfully — a check that called `*` \"missing\" would report a failure while\n * the uploads it watches were in fact wide open. {@link mergeUploadOrigins} is\n * where we refuse to ever write one.\n *\n * ## Why a MERGE\n *\n * `gcloud storage buckets update --cors-file` **replaces** the configuration\n * rather than merging it. Automation that builds a fresh document from the\n * origins it happens to know about silently drops every other customer's\n * origin, and the symptom lands on them, days later, as a failed large upload\n * nobody can attribute. Everything here is read-modify-write.\n */\n\nexport interface CorsRule {\n  origin?: string[]\n  method?: string[]\n  responseHeader?: string[]\n  maxAgeSeconds?: number\n}\n\n/** The method the DAM uploader issues. Parsed out of it by `storage-cors.spec.ts`. */\nexport const UPLOAD_CORS_METHOD = 'PUT'\n\n/** The headers that `PUT` sets, which the preflight answers from. */\nexport const UPLOAD_CORS_RESPONSE_HEADERS = ['Content-Type', 'x-goog-resumable']\n\n/** One hour, matching `cloud/storage-cors.json`. */\nexport const UPLOAD_CORS_MAX_AGE_SECONDS = 3600\n\nconst HOSTNAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/\n\n/**\n * The origin a browser on `host` will actually put in the `Origin` header.\n *\n * Accepts a bare hostname or a URL, because callers hold both shapes: a\n * console-domain claim stores a hostname and `NEXT_PUBLIC_CONSOLE_URL` carries\n * a scheme. Null for anything that is not a hostname — including `*`, which is\n * never a thing this function will hand onward.\n */\nexport function uploadOriginFor(host: string): string | null {\n  const raw = String(host ?? '').trim().toLowerCase()\n  if (!raw) return null\n  const bare = raw\n    .replace(/^[a-z][a-z0-9+.-]*:\\/\\//, '')\n    .split(/[/?#]/)[0]\n    .replace(/\\.$/, '')\n  return HOSTNAME.test(bare) ? `https://${bare}` : null\n}\n\nfunction uploadRules(rules: CorsRule[]): CorsRule[] {\n  return rules.filter((rule) =>\n    (rule.method ?? []).some(\n      (method) => method.toUpperCase() === UPLOAD_CORS_METHOD,\n    ),\n  )\n}\n\n/**\n * Would this bucket configuration let a browser at `origin` complete the\n * signed `PUT`?\n *\n * Exact comparison, deliberately: matching loosely here would make this agree\n * with the intuition and disagree with GCS, which is the whole failure being\n * guarded against.\n */\nexport function permitsUploadOrigin(\n  rules: CorsRule[] | null | undefined,\n  origin: string,\n): boolean {\n  if (!rules) return false\n  return uploadRules(rules).some((rule) =>\n    (rule.origin ?? []).some((listed) => listed === '*' || listed === origin),\n  )\n}\n\n/**\n * The origins this configuration would refuse, in the order asked.\n *\n * A null configuration — the read failed, the bucket is unreachable — covers\n * NOTHING. Reporting calm because we could not look is the shape of alarm that\n * has already cost this repo three outages.\n */\nexport function missingUploadOrigins(\n  rules: CorsRule[] | null | undefined,\n  origins: string[],\n): string[] {\n  return origins.filter((origin) => !permitsUploadOrigin(rules, origin))\n}\n\n/**\n * The configuration to WRITE so `origins` can upload, preserving everything\n * already permitted.\n *\n * Adds to the existing upload rule where there is one, so the policy does not\n * grow a rule per customer. Throws on a wildcard rather than returning an\n * error, because there is no caller for whom emitting one is the right\n * outcome and a returned error is a thing a caller can ignore.\n */\nexport function mergeUploadOrigins(\n  rules: CorsRule[],\n  origins: string[],\n): { rules: CorsRule[]; added: string[] } {\n  if (origins.some((origin) => String(origin).includes('*'))) {\n    throw new Error(\n      'refusing to write a wildcard CORS origin: the signed URL carries the ' +\n        'authorization, so `*` lets any site spend one that leaks (AGL-1452)',\n    )\n  }\n  const wanted = [...new Set(origins)]\n  const missing = missingUploadOrigins(rules, wanted)\n  if (missing.length === 0) return { rules, added: [] }\n\n  const target = rules.findIndex((rule) => uploadRules([rule]).length === 1)\n  if (target < 0) {\n    return {\n      rules: [\n        ...rules,\n        {\n          origin: missing,\n          method: [UPLOAD_CORS_METHOD],\n          responseHeader: [...UPLOAD_CORS_RESPONSE_HEADERS],\n          maxAgeSeconds: UPLOAD_CORS_MAX_AGE_SECONDS,\n        },\n      ],\n      added: missing,\n    }\n  }\n  const next = rules.map((rule, index) =>\n    index === target\n      ? { ...rule, origin: [...new Set([...(rule.origin ?? []), ...missing])] }\n      : rule,\n  )\n  return { rules: next, added: missing }\n}\n\n/**\n * The configuration to WRITE so `origins` are no longer permitted, keeping\n * everything else (AGL-1452).\n *\n * ## Why a detach has to do this\n *\n * An origin outlives the name unless something removes it. For an\n * `*.aglyn.com` subdomain that is untidy. For a **white-label console domain**\n * it is a standing permission on a bucket that accepts signed writes, granted\n * to a host the customer keeps and we no longer serve — and the signed URL\n * carries its own authorization, so that host can spend one that leaks. A\n * stale CORS origin is therefore worse than a stale reCAPTCHA entry, not\n * merely equivalent to one.\n *\n * ## `keep` is not optional in practice\n *\n * The platform origin is configured, not provisioned. Removing it would break\n * large uploads for every customer at once — the platform-wide outage the\n * read-modify-write warning is about, reached from the other direction. Every\n * caller passes it.\n *\n * A rule left with no origins is DROPPED rather than written as `origin: []`.\n * GCS accepts the empty form, and it reads to the next person like a rule that\n * permits something.\n */\nexport function revokeUploadOrigins(\n  rules: CorsRule[],\n  origins: string[],\n  { keep = [] }: { keep?: string[] } = {},\n): { rules: CorsRule[]; removed: string[]; refused: string[] } {\n  const protectedSet = new Set(keep)\n  const asked = [...new Set(origins.map((origin) => String(origin)))]\n  const refused = asked.filter(\n    (origin) => origin === '*' || protectedSet.has(origin),\n  )\n  const doomed = new Set(asked.filter((origin) => !refused.includes(origin)))\n  if (doomed.size === 0) return { rules, removed: [], refused }\n\n  const removed: string[] = []\n  const next: CorsRule[] = []\n  for (const rule of rules) {\n    if (uploadRules([rule]).length !== 1) {\n      next.push(rule)\n      continue\n    }\n    const kept = (rule.origin ?? []).filter((origin) => {\n      if (!doomed.has(String(origin))) return true\n      removed.push(String(origin))\n      return false\n    })\n    if (kept.length > 0) next.push({ ...rule, origin: kept })\n  }\n  return { rules: next, removed, refused }\n}\n\n/**\n * What a human must run when the automation could not.\n *\n * Carries the warning as well as the command: the obvious one-liner is the\n * destructive one, and an instruction that omits that is how the read-modify-\n * write rule gets skipped by the person following it in a hurry.\n */\nexport function uploadCorsRemedy(bucket: string, missing: string[]): string {\n  return [\n    `Large (resumable) uploads from ${missing.join(', ')} will fail until`,\n    `gs://${bucket} permits ${missing.length === 1 ? 'that origin' : 'those origins'}.`,\n    'GCS matches the CORS origin list EXACTLY — there is no subtree form, so',\n    'each origin needs its own entry.',\n    '',\n    '  gcloud storage buckets describe gs://' + bucket + ' --format=json\\\\(cors_config\\\\) > cors.json',\n    '  # edit cors.json: ADD the origins above to the rule whose method is PUT',\n    `  gcloud storage buckets update gs://${bucket} --cors-file=cors.json`,\n    '',\n    '⚠️ --cors-file REPLACES the configuration rather than merging it. Read the',\n    'live document, add to it, write it back — building a fresh one drops every',\n    'other origin, and that failure lands on someone else, days later.',\n  ].join('\\n')\n}\n"],"names":["UPLOAD_CORS_METHOD","UPLOAD_CORS_RESPONSE_HEADERS","UPLOAD_CORS_MAX_AGE_SECONDS","HOSTNAME","uploadOriginFor","host","raw","String","trim","toLowerCase","bare","replace","split","test","uploadRules","rules","filter","rule","method","some","toUpperCase","permitsUploadOrigin","origin","listed","missingUploadOrigins","origins","mergeUploadOrigins","includes","Error","wanted","Set","missing","length","added","target","findIndex","responseHeader","maxAgeSeconds","next","map","index","revokeUploadOrigins","keep","protectedSet","asked","refused","has","doomed","size","removed","push","kept","uploadCorsRemedy","bucket","join"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+CC;AASD,oFAAoF,GACpF,OAAO,MAAMA,qBAAqB,MAAK;AAEvC,mEAAmE,GACnE,OAAO,MAAMC,+BAA+B;IAAC;IAAgB;CAAmB,CAAA;AAEhF,kDAAkD,GAClD,OAAO,MAAMC,8BAA8B,KAAI;AAE/C,MAAMC,WAAW;AAEjB;;;;;;;CAOC,GACD,OAAO,SAASC,gBAAgBC,IAAY;IAC1C,MAAMC,MAAMC,OAAOF,eAAAA,OAAQ,IAAIG,IAAI,GAAGC,WAAW;IACjD,IAAI,CAACH,KAAK,OAAO;IACjB,MAAMI,OAAOJ,IACVK,OAAO,CAAC,2BAA2B,IACnCC,KAAK,CAAC,QAAQ,CAAC,EAAE,CACjBD,OAAO,CAAC,OAAO;IAClB,OAAOR,SAASU,IAAI,CAACH,QAAQ,CAAC,QAAQ,EAAEA,MAAM,GAAG;AACnD;AAEA,SAASI,YAAYC,KAAiB;IACpC,OAAOA,MAAMC,MAAM,CAAC,CAACC;YAClBA;eAAD,EAACA,eAAAA,KAAKC,MAAM,YAAXD,eAAe,EAAE,EAAEE,IAAI,CACtB,CAACD,SAAWA,OAAOE,WAAW,OAAOpB;;AAG3C;AAEA;;;;;;;CAOC,GACD,OAAO,SAASqB,oBACdN,KAAoC,EACpCO,MAAc;IAEd,IAAI,CAACP,OAAO,OAAO;IACnB,OAAOD,YAAYC,OAAOI,IAAI,CAAC,CAACF;YAC7BA;eAAD,EAACA,eAAAA,KAAKK,MAAM,YAAXL,eAAe,EAAE,EAAEE,IAAI,CAAC,CAACI,SAAWA,WAAW,OAAOA,WAAWD;;AAEtE;AAEA;;;;;;CAMC,GACD,OAAO,SAASE,qBACdT,KAAoC,EACpCU,OAAiB;IAEjB,OAAOA,QAAQT,MAAM,CAAC,CAACM,SAAW,CAACD,oBAAoBN,OAAOO;AAChE;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASI,mBACdX,KAAiB,EACjBU,OAAiB;IAEjB,IAAIA,QAAQN,IAAI,CAAC,CAACG,SAAWf,OAAOe,QAAQK,QAAQ,CAAC,OAAO;QAC1D,MAAM,IAAIC,MACR,0EACE;IAEN;IACA,MAAMC,SAAS;WAAI,IAAIC,IAAIL;KAAS;IACpC,MAAMM,UAAUP,qBAAqBT,OAAOc;IAC5C,IAAIE,QAAQC,MAAM,KAAK,GAAG,OAAO;QAAEjB;QAAOkB,OAAO,EAAE;IAAC;IAEpD,MAAMC,SAASnB,MAAMoB,SAAS,CAAC,CAAClB,OAASH,YAAY;YAACG;SAAK,EAAEe,MAAM,KAAK;IACxE,IAAIE,SAAS,GAAG;QACd,OAAO;YACLnB,OAAO;mBACFA;gBACH;oBACEO,QAAQS;oBACRb,QAAQ;wBAAClB;qBAAmB;oBAC5BoC,gBAAgB;2BAAInC;qBAA6B;oBACjDoC,eAAenC;gBACjB;aACD;YACD+B,OAAOF;QACT;IACF;IACA,MAAMO,OAAOvB,MAAMwB,GAAG,CAAC,CAACtB,MAAMuB;YAEYvB;eADxCuB,UAAUN,SACN,aAAKjB;YAAMK,QAAQ;mBAAI,IAAIQ,IAAI;wBAAKb,eAAAA,KAAKK,MAAM,YAAXL,eAAe,EAAE;uBAAMc;iBAAQ;aAAE;aACrEd;;IAEN,OAAO;QAAEF,OAAOuB;QAAML,OAAOF;IAAQ;AACvC;AAEA;;;;;;;;;;;;;;;;;;;;;;;;CAwBC,GACD,OAAO,SAASU,oBACd1B,KAAiB,EACjBU,OAAiB,EACjB,EAAEiB,OAAO,EAAE,EAAuB,GAAG,CAAC,CAAC;IAEvC,MAAMC,eAAe,IAAIb,IAAIY;IAC7B,MAAME,QAAQ;WAAI,IAAId,IAAIL,QAAQc,GAAG,CAAC,CAACjB,SAAWf,OAAOe;KAAU;IACnE,MAAMuB,UAAUD,MAAM5B,MAAM,CAC1B,CAACM,SAAWA,WAAW,OAAOqB,aAAaG,GAAG,CAACxB;IAEjD,MAAMyB,SAAS,IAAIjB,IAAIc,MAAM5B,MAAM,CAAC,CAACM,SAAW,CAACuB,QAAQlB,QAAQ,CAACL;IAClE,IAAIyB,OAAOC,IAAI,KAAK,GAAG,OAAO;QAAEjC;QAAOkC,SAAS,EAAE;QAAEJ;IAAQ;IAE5D,MAAMI,UAAoB,EAAE;IAC5B,MAAMX,OAAmB,EAAE;IAC3B,KAAK,MAAMrB,QAAQF,MAAO;YAKVE;QAJd,IAAIH,YAAY;YAACG;SAAK,EAAEe,MAAM,KAAK,GAAG;YACpCM,KAAKY,IAAI,CAACjC;YACV;QACF;QACA,MAAMkC,OAAO,EAAClC,eAAAA,KAAKK,MAAM,YAAXL,eAAe,EAAE,EAAED,MAAM,CAAC,CAACM;YACvC,IAAI,CAACyB,OAAOD,GAAG,CAACvC,OAAOe,UAAU,OAAO;YACxC2B,QAAQC,IAAI,CAAC3C,OAAOe;YACpB,OAAO;QACT;QACA,IAAI6B,KAAKnB,MAAM,GAAG,GAAGM,KAAKY,IAAI,CAAC,aAAKjC;YAAMK,QAAQ6B;;IACpD;IACA,OAAO;QAAEpC,OAAOuB;QAAMW;QAASJ;IAAQ;AACzC;AAEA;;;;;;CAMC,GACD,OAAO,SAASO,iBAAiBC,MAAc,EAAEtB,OAAiB;IAChE,OAAO;QACL,CAAC,+BAA+B,EAAEA,QAAQuB,IAAI,CAAC,MAAM,gBAAgB,CAAC;QACtE,CAAC,KAAK,EAAED,OAAO,SAAS,EAAEtB,QAAQC,MAAM,KAAK,IAAI,gBAAgB,gBAAgB,CAAC,CAAC;QACnF;QACA;QACA;QACA,4CAA4CqB,SAAS;QACrD;QACA,CAAC,qCAAqC,EAAEA,OAAO,sBAAsB,CAAC;QACtE;QACA;QACA;QACA;KACD,CAACC,IAAI,CAAC;AACT"}

package/src/lib/app-utils/upload-inspection.d.ts

@@ -0,0 +1,159 @@
+/**
+ * @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.
+ */
+/**
+ * STRUCTURAL upload inspection (AGL-1475).
+ *
+ * ## What this is, and what it is emphatically not
+ *
+ * This is **not** an antivirus scanner and no code in this module should ever
+ * be described as one. It does not have malware signatures, it does not
+ * emulate, unpack or detonate anything, and a novel trojan with a correct PDF
+ * header passes it without a murmur. It is *structural validation*: it reads
+ * the first few kilobytes of an upload and answers three questions the
+ * platform previously could not ask at all.
+ *
+ * 1. **Are these bytes an executable?** A Windows PE, an ELF binary, a Mach-O
+ *    binary or an installer package is refused whatever it claims to be. This
+ *    is the single highest-value check here: the Sept-1 risk is a customer's
+ *    domain re-serving a trojan to a visitor's browser, and the overwhelming
+ *    majority of that population is a plain executable with a lying name.
+ * 2. **Do the bytes match the declared type?** Media ingress trusted the
+ *    caller's content type completely — AGL-2463 wrote that gap down. The
+ *    allowlist bounded what a file *claimed* to be and nothing bounded what it
+ *    *was*, so `Content-Type: application/pdf` over a `.exe` was stored,
+ *    hashed, given a CDN path and served. It now has to be a PDF.
+ * 3. **Does an Office document carry a macro project?** AGL-1465 kept
+ *    `.docm`/`.xlsm`/`.pptm` out **by content type**, which is a gate on a
+ *    string the uploader chooses. Renaming a macro-enabled document to
+ *    `.docx` walked straight past it. The archive is now checked for a
+ *    `vbaProject.bin` entry, which is the thing that made those extensions
+ *    worth excluding in the first place.
+ *
+ * Plus one signature, EICAR — see {@link EICAR_TEST_SIGNATURE}.
+ *
+ * ## What it therefore does not catch
+ *
+ * A malicious PDF that is a real PDF. A macro-free document that exploits a
+ * reader. Anything inside a plain `application/zip`, which is a brand kit and
+ * may legitimately contain a build tool. An obfuscated dropper in a JSON
+ * file. Real malware detection needs signatures and an engine, which needs a
+ * ClamAV service, which does not fit the budget this platform runs on — the
+ * cost work is in the issue. Nothing here should be allowed to read as though
+ * that decision went the other way.
+ *
+ * ## Why it is pure, and takes a window rather than a file
+ *
+ * Three of the four media chokepoints hold the whole file in memory and can
+ * pass it straight in. The fourth — signed direct-to-storage upload — never
+ * sees the bytes, because that is the entire reason it exists: a 200 MB video
+ * goes browser → bucket and downloading it back into the function to look at
+ * it would cost more than the feature. So that caller does two RANGED reads
+ * instead, a few KB from each end, and passes them as {@link
+ * InspectUploadInput.bytes} and {@link InspectUploadInput.tail}. Every
+ * signature this module knows lives in one of those two windows, so the
+ * signed route gets the same verdict for the price of a rounding error.
+ */
+/**
+ * The EICAR standard antivirus test string.
+ *
+ * A 68-byte printable string, defined by the European Institute for Computer
+ * Antivirus Research, that every antivirus product agrees to flag and that is
+ * completely inert. It exists so that a pipeline can be tested end to end
+ * without anyone handling a live sample.
+ *
+ * It is matched here for exactly two reasons, and neither is malware
+ * detection. First, it makes this module's own tests honest without checking
+ * a real sample into the repository. Second, it is the probe a security
+ * reviewer or a customer will actually try, and answering it with silence
+ * would be a worse lie than answering it with a refusal — a refusal that says
+ * "structural check" is true, where a silent accept invites the reader to
+ * conclude nothing is checked at all.
+ *
+ * **This is a signature list of one. It is not an engine.** Do not add a
+ * second entry here and start calling the result malware scanning; if real
+ * signatures are wanted, they belong in a scanner service, not in a string
+ * constant.
+ */
+export declare const EICAR_TEST_SIGNATURE = "X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*";
+/**
+ * How many leading bytes an inspection needs.
+ *
+ * Every magic number checked here sits in the first 16 bytes; the window is
+ * far larger so that the EICAR match and the small-file macro scan have room,
+ * and because the signed route's ranged GET costs the same for 4 KB as for
+ * 64 bytes.
+ */
+export declare const UPLOAD_INSPECTION_HEAD_BYTES = 4096;
+/**
+ * How many trailing bytes an inspection wants for an Office document.
+ *
+ * A ZIP's central directory — the authoritative list of what is inside it —
+ * lives at the end of the file. 64 KB covers the directory of any document
+ * archive this platform accepts (the largest ceiling is a 50 MB `.pptx`, and
+ * its directory is a few KB even with hundreds of embedded images). A
+ * document whose directory is somehow larger than this window degrades to
+ * "macro not found", which is the pre-existing behaviour, not a regression.
+ */
+export declare const UPLOAD_INSPECTION_TAIL_BYTES = 65536;
+export type UploadInspectionCode = 'signature_match' | 'executable_bytes' | 'type_mismatch' | 'macro_payload' | 'empty_file';
+export interface UploadInspectionRefusal {
+    /** Stable machine code — for the API error body, logs and tests. */
+    code: UploadInspectionCode;
+    /** What the bytes turned out to be, in words rather than hex. */
+    detected: string;
+    /**
+     * The sentence the uploader sees. Names the file and what was found, so
+     * that a merchant who did nothing wrong can tell which of fifty dropped
+     * files was the problem and why.
+     */
+    message: string;
+}
+export interface InspectUploadInput {
+    /**
+     * The whole file, or its leading {@link UPLOAD_INSPECTION_HEAD_BYTES}.
+     * Callers holding the whole file pass it and omit `tail`.
+     */
+    bytes: Uint8Array;
+    /**
+     * The file's trailing bytes, supplied ONLY by a caller that passed a head
+     * window rather than the whole file. When absent, `bytes` is searched for
+     * the trailing structures too — which is correct precisely because a caller
+     * that omits it is one that handed over the entire file.
+     */
+    tail?: Uint8Array | null;
+    /** The type the upload claims to be, already normalized by the caller. */
+    contentType: string;
+    /** For the message only. Never used to decide anything. */
+    fileName?: string | null;
+}
+/**
+ * Does a caller holding only a head window need to fetch the tail as well?
+ *
+ * Only the macro scan reads the end of a file, and only for document
+ * archives, so this is what lets the signed-upload route skip a second ranged
+ * GET for the 200 MB videos that route exists to carry — which is every
+ * object on it bar a handful of documents.
+ */
+export declare function uploadInspectionNeedsTail(contentType: string): boolean;
+/**
+ * Inspect an upload's bytes against the type it claims to be.
+ *
+ * Returns `null` when nothing structural is wrong — which, to be explicit, is
+ * NOT a statement that the file is safe. See the module header.
+ */
+export declare function inspectUploadBytes(input: InspectUploadInput): UploadInspectionRefusal | null;
+export default inspectUploadBytes;