@aglyn/aglyn 1.0.0-beta.230 → 1.0.0-beta.231

package/src/lib/app-utils/site-wide-outbox.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @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.
+ */
+import { type DocumentReference, type Firestore } from 'firebase/firestore';
+/**
+ * A SITE-WIDE CHANGE, SAVED FROM THE BROWSER, AND THE CACHE DROP IT OWES
+ * (AGL-3386).
+ *
+ * A site's settings, and the plugin data its pages render — the theme, the
+ * announcement bar, a product, a site variable — are client Firestore writes
+ * with no publish step. The live site is ISR-cached for an hour, so each of
+ * those writes has to tell the tenant to drop the site's cached pages, or the
+ * change waits out the hour while the console says it is saved.
+ *
+ * Telling it from the tab is the fast path, and a tab is not durable: close
+ * it, sleep the laptop or lose the network between the write and the fetch,
+ * and the write has landed while the drop has landed nowhere. So the drop is
+ * also WRITTEN DOWN, as a publish outbox entry in the same batch as the
+ * write — either both land or neither does — and the console's scheduled
+ * drain fires any entry the tab did not get to release. This is the same
+ * mechanism a screen publish uses (AGL-2575); the entry carries
+ * `entireHost: true`, because a site-wide setting has no address of its own.
+ *
+ * This is the outbox half for the native app (AGL-3621), which saves the
+ * same documents and owes the same drop. The browser's copy is
+ * `@aglyn/tenant-feature-instance/hooks/helpers/site-wide-change`, left as it
+ * was because a web bundle may not grow by a byte for the app; this one takes
+ * the entry id from its caller, since the id helper's barrel is not free of
+ * React. `site-wide-outbox.spec.ts` beside that file holds the two to the
+ * same collection, the same entry and the same retry.
+ */
+/**
+ * The publish outbox. The console's `PUBLISH_OUTBOX_COLLECTION` is the same
+ * collection, and `host-document-writes-sweep.spec.ts` holds the two names
+ * and the entry's keys to the console's constants and to the rule.
+ */
+export declare const SITE_WIDE_OUTBOX_COLLECTION = "publishOutbox";
+/**
+ * What a site-wide entry names. The rule insists every entry names at least
+ * one address; the drain reads `entireHost` and drops every routed page of
+ * the site instead, which is what a site-wide change needs.
+ */
+export declare const SITE_WIDE_OUTBOX_PATHS: readonly string[];
+/**
+ * What an entry can be staged into: a batch, or a transaction — anything
+ * whose `set` lands in the same commit as the write beside it.
+ */
+export interface SiteWideEntryWriter {
+    set(ref: DocumentReference, data: Record<string, unknown>): unknown;
+}
+/**
+ * Stages one site-wide outbox entry into the caller's batch, under `entryId`:
+ * the id every console resource carries, never an SDK auto-id.
+ */
+export declare function stageSiteWideOutboxEntryAs(batch: SiteWideEntryWriter, firestore: Firestore, hostId: string, entryId: string): DocumentReference;
+/** Adds a site-wide outbox entry to a batch that is about to commit. */
+export type StageSiteWideEntry = (batch: SiteWideEntryWriter, firestore: Firestore) => void;
+/**
+ * Commits a write with its site-wide outbox entry beside it, and answers the
+ * entry — or `null` when the write had to land without one.
+ *
+ * `commit` performs the write. It is handed the stager on the first attempt
+ * and must put the entry in the SAME batch as the write; it is called again
+ * without one if that batch is refused.
+ *
+ * The retry is what keeps the entry from ever costing a save. The entry is
+ * the durable copy of a cache drop, and the write is the user's work: a rule
+ * that refuses the entry — the window between a code release and the rules
+ * deploy that admits it, or a role the outbox rule does not cover — must
+ * leave the save exactly as it was without it, with the tab's own drop still
+ * behind it. A write the rules refuse on its own merits is refused again,
+ * and that second refusal is the one the caller sees.
+ */
+export declare function commitWithSiteWideEntryAs(hostId: string, commit: (stage: StageSiteWideEntry | undefined) => Promise<void>, newEntryId: () => string): Promise<DocumentReference | null>;
+/**
+ * Releases an entry once its drop is KNOWN to have landed — a plain `ok` from
+ * the console route and nothing else. Any other answer leaves it for the
+ * drain, because the entry is the only record that the site may still be
+ * stale; the cost of keeping one needlessly is a duplicate drop, which is a
+ * no-op.
+ */
+export declare function releaseSiteWideOutboxEntry(entry: DocumentReference | null, reason: string | null | undefined): Promise<void>;

package/src/lib/app-utils/site-wide-outbox.js

@@ -0,0 +1,117 @@
+/**
+ * @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.
+ */ import { deleteDoc, doc, serverTimestamp } from "firebase/firestore";
+/**
+ * A SITE-WIDE CHANGE, SAVED FROM THE BROWSER, AND THE CACHE DROP IT OWES
+ * (AGL-3386).
+ *
+ * A site's settings, and the plugin data its pages render — the theme, the
+ * announcement bar, a product, a site variable — are client Firestore writes
+ * with no publish step. The live site is ISR-cached for an hour, so each of
+ * those writes has to tell the tenant to drop the site's cached pages, or the
+ * change waits out the hour while the console says it is saved.
+ *
+ * Telling it from the tab is the fast path, and a tab is not durable: close
+ * it, sleep the laptop or lose the network between the write and the fetch,
+ * and the write has landed while the drop has landed nowhere. So the drop is
+ * also WRITTEN DOWN, as a publish outbox entry in the same batch as the
+ * write — either both land or neither does — and the console's scheduled
+ * drain fires any entry the tab did not get to release. This is the same
+ * mechanism a screen publish uses (AGL-2575); the entry carries
+ * `entireHost: true`, because a site-wide setting has no address of its own.
+ *
+ * This is the outbox half for the native app (AGL-3621), which saves the
+ * same documents and owes the same drop. The browser's copy is
+ * `@aglyn/tenant-feature-instance/hooks/helpers/site-wide-change`, left as it
+ * was because a web bundle may not grow by a byte for the app; this one takes
+ * the entry id from its caller, since the id helper's barrel is not free of
+ * React. `site-wide-outbox.spec.ts` beside that file holds the two to the
+ * same collection, the same entry and the same retry.
+ */ /**
+ * The publish outbox. The console's `PUBLISH_OUTBOX_COLLECTION` is the same
+ * collection, and `host-document-writes-sweep.spec.ts` holds the two names
+ * and the entry's keys to the console's constants and to the rule.
+ */ export const SITE_WIDE_OUTBOX_COLLECTION = 'publishOutbox';
+/**
+ * What a site-wide entry names. The rule insists every entry names at least
+ * one address; the drain reads `entireHost` and drops every routed page of
+ * the site instead, which is what a site-wide change needs.
+ */ export const SITE_WIDE_OUTBOX_PATHS = [
+    '/'
+];
+/**
+ * Stages one site-wide outbox entry into the caller's batch, under `entryId`:
+ * the id every console resource carries, never an SDK auto-id.
+ */ export function stageSiteWideOutboxEntryAs(batch, firestore, hostId, entryId) {
+    const ref = doc(firestore, SITE_WIDE_OUTBOX_COLLECTION, entryId);
+    batch.set(ref, {
+        hostId,
+        paths: [
+            ...SITE_WIDE_OUTBOX_PATHS
+        ],
+        // A server timestamp: the rules pin it to `request.time`, and the drain
+        // ages entries by it.
+        createdAt: serverTimestamp(),
+        attempts: 0,
+        entireHost: true
+    });
+    return ref;
+}
+const isPermissionDenied = (error)=>(error == null ? void 0 : error.code) === 'permission-denied';
+/**
+ * Commits a write with its site-wide outbox entry beside it, and answers the
+ * entry — or `null` when the write had to land without one.
+ *
+ * `commit` performs the write. It is handed the stager on the first attempt
+ * and must put the entry in the SAME batch as the write; it is called again
+ * without one if that batch is refused.
+ *
+ * The retry is what keeps the entry from ever costing a save. The entry is
+ * the durable copy of a cache drop, and the write is the user's work: a rule
+ * that refuses the entry — the window between a code release and the rules
+ * deploy that admits it, or a role the outbox rule does not cover — must
+ * leave the save exactly as it was without it, with the tab's own drop still
+ * behind it. A write the rules refuse on its own merits is refused again,
+ * and that second refusal is the one the caller sees.
+ */ export async function commitWithSiteWideEntryAs(hostId, commit, newEntryId) {
+    // A holder rather than a `let`: the stager assigns it inside a callback,
+    // which control-flow narrowing cannot see.
+    const staged = {
+        entry: null
+    };
+    try {
+        await commit((batch, firestore)=>{
+            staged.entry = stageSiteWideOutboxEntryAs(batch, firestore, hostId, newEntryId());
+        });
+        return staged.entry;
+    } catch (error) {
+        if (!staged.entry || !isPermissionDenied(error)) throw error;
+        await commit(undefined);
+        return null;
+    }
+}
+/**
+ * Releases an entry once its drop is KNOWN to have landed — a plain `ok` from
+ * the console route and nothing else. Any other answer leaves it for the
+ * drain, because the entry is the only record that the site may still be
+ * stale; the cost of keeping one needlessly is a duplicate drop, which is a
+ * no-op.
+ */ export async function releaseSiteWideOutboxEntry(entry, reason) {
+    if (!entry || reason !== 'ok') return;
+    await deleteDoc(entry).catch(()=>undefined);
+}
+
+//# sourceMappingURL=site-wide-outbox.js.map

package/src/lib/app-utils/site-wide-outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/site-wide-outbox.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\nimport {\n  deleteDoc,\n  doc,\n  serverTimestamp,\n  type DocumentReference,\n  type Firestore,\n} from 'firebase/firestore'\n\n/**\n * A SITE-WIDE CHANGE, SAVED FROM THE BROWSER, AND THE CACHE DROP IT OWES\n * (AGL-3386).\n *\n * A site's settings, and the plugin data its pages render — the theme, the\n * announcement bar, a product, a site variable — are client Firestore writes\n * with no publish step. The live site is ISR-cached for an hour, so each of\n * those writes has to tell the tenant to drop the site's cached pages, or the\n * change waits out the hour while the console says it is saved.\n *\n * Telling it from the tab is the fast path, and a tab is not durable: close\n * it, sleep the laptop or lose the network between the write and the fetch,\n * and the write has landed while the drop has landed nowhere. So the drop is\n * also WRITTEN DOWN, as a publish outbox entry in the same batch as the\n * write — either both land or neither does — and the console's scheduled\n * drain fires any entry the tab did not get to release. This is the same\n * mechanism a screen publish uses (AGL-2575); the entry carries\n * `entireHost: true`, because a site-wide setting has no address of its own.\n *\n * This is the outbox half for the native app (AGL-3621), which saves the\n * same documents and owes the same drop. The browser's copy is\n * `@aglyn/tenant-feature-instance/hooks/helpers/site-wide-change`, left as it\n * was because a web bundle may not grow by a byte for the app; this one takes\n * the entry id from its caller, since the id helper's barrel is not free of\n * React. `site-wide-outbox.spec.ts` beside that file holds the two to the\n * same collection, the same entry and the same retry.\n */\n\n/**\n * The publish outbox. The console's `PUBLISH_OUTBOX_COLLECTION` is the same\n * collection, and `host-document-writes-sweep.spec.ts` holds the two names\n * and the entry's keys to the console's constants and to the rule.\n */\nexport const SITE_WIDE_OUTBOX_COLLECTION = 'publishOutbox'\n\n/**\n * What a site-wide entry names. The rule insists every entry names at least\n * one address; the drain reads `entireHost` and drops every routed page of\n * the site instead, which is what a site-wide change needs.\n */\nexport const SITE_WIDE_OUTBOX_PATHS: readonly string[] = ['/']\n\n/**\n * What an entry can be staged into: a batch, or a transaction — anything\n * whose `set` lands in the same commit as the write beside it.\n */\nexport interface SiteWideEntryWriter {\n  set(ref: DocumentReference, data: Record<string, unknown>): unknown\n}\n\n/**\n * Stages one site-wide outbox entry into the caller's batch, under `entryId`:\n * the id every console resource carries, never an SDK auto-id.\n */\nexport function stageSiteWideOutboxEntryAs(\n  batch: SiteWideEntryWriter,\n  firestore: Firestore,\n  hostId: string,\n  entryId: string,\n): DocumentReference {\n  const ref = doc(firestore, SITE_WIDE_OUTBOX_COLLECTION, entryId)\n  batch.set(ref, {\n    hostId,\n    paths: [...SITE_WIDE_OUTBOX_PATHS],\n    // A server timestamp: the rules pin it to `request.time`, and the drain\n    // ages entries by it.\n    createdAt: serverTimestamp(),\n    attempts: 0,\n    entireHost: true,\n  })\n  return ref\n}\n\n/** Adds a site-wide outbox entry to a batch that is about to commit. */\nexport type StageSiteWideEntry = (\n  batch: SiteWideEntryWriter,\n  firestore: Firestore,\n) => void\n\nconst isPermissionDenied = (error: unknown): boolean =>\n  (error as { code?: unknown } | null)?.code === 'permission-denied'\n\n/**\n * Commits a write with its site-wide outbox entry beside it, and answers the\n * entry — or `null` when the write had to land without one.\n *\n * `commit` performs the write. It is handed the stager on the first attempt\n * and must put the entry in the SAME batch as the write; it is called again\n * without one if that batch is refused.\n *\n * The retry is what keeps the entry from ever costing a save. The entry is\n * the durable copy of a cache drop, and the write is the user's work: a rule\n * that refuses the entry — the window between a code release and the rules\n * deploy that admits it, or a role the outbox rule does not cover — must\n * leave the save exactly as it was without it, with the tab's own drop still\n * behind it. A write the rules refuse on its own merits is refused again,\n * and that second refusal is the one the caller sees.\n */\nexport async function commitWithSiteWideEntryAs(\n  hostId: string,\n  commit: (stage: StageSiteWideEntry | undefined) => Promise<void>,\n  newEntryId: () => string,\n): Promise<DocumentReference | null> {\n  // A holder rather than a `let`: the stager assigns it inside a callback,\n  // which control-flow narrowing cannot see.\n  const staged: { entry: DocumentReference | null } = { entry: null }\n  try {\n    await commit((batch, firestore) => {\n      staged.entry = stageSiteWideOutboxEntryAs(batch, firestore, hostId, newEntryId())\n    })\n    return staged.entry\n  } catch (error) {\n    if (!staged.entry || !isPermissionDenied(error)) throw error\n    await commit(undefined)\n    return null\n  }\n}\n\n/**\n * Releases an entry once its drop is KNOWN to have landed — a plain `ok` from\n * the console route and nothing else. Any other answer leaves it for the\n * drain, because the entry is the only record that the site may still be\n * stale; the cost of keeping one needlessly is a duplicate drop, which is a\n * no-op.\n */\nexport async function releaseSiteWideOutboxEntry(\n  entry: DocumentReference | null,\n  reason: string | null | undefined,\n): Promise<void> {\n  if (!entry || reason !== 'ok') return\n  await deleteDoc(entry).catch((): void => undefined)\n}\n"],"names":["deleteDoc","doc","serverTimestamp","SITE_WIDE_OUTBOX_COLLECTION","SITE_WIDE_OUTBOX_PATHS","stageSiteWideOutboxEntryAs","batch","firestore","hostId","entryId","ref","set","paths","createdAt","attempts","entireHost","isPermissionDenied","error","code","commitWithSiteWideEntryAs","commit","newEntryId","staged","entry","undefined","releaseSiteWideOutboxEntry","reason","catch"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,SAAS,EACTC,GAAG,EACHC,eAAe,QAGV,qBAAoB;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BC,GAED;;;;CAIC,GACD,OAAO,MAAMC,8BAA8B,gBAAe;AAE1D;;;;CAIC,GACD,OAAO,MAAMC,yBAA4C;IAAC;CAAI,CAAA;AAU9D;;;CAGC,GACD,OAAO,SAASC,2BACdC,KAA0B,EAC1BC,SAAoB,EACpBC,MAAc,EACdC,OAAe;IAEf,MAAMC,MAAMT,IAAIM,WAAWJ,6BAA6BM;IACxDH,MAAMK,GAAG,CAACD,KAAK;QACbF;QACAI,OAAO;eAAIR;SAAuB;QAClC,wEAAwE;QACxE,sBAAsB;QACtBS,WAAWX;QACXY,UAAU;QACVC,YAAY;IACd;IACA,OAAOL;AACT;AAQA,MAAMM,qBAAqB,CAACC,QAC1B,CAACA,yBAAD,AAACA,MAAqCC,IAAI,MAAK;AAEjD;;;;;;;;;;;;;;;CAeC,GACD,OAAO,eAAeC,0BACpBX,MAAc,EACdY,MAAgE,EAChEC,UAAwB;IAExB,yEAAyE;IACzE,2CAA2C;IAC3C,MAAMC,SAA8C;QAAEC,OAAO;IAAK;IAClE,IAAI;QACF,MAAMH,OAAO,CAACd,OAAOC;YACnBe,OAAOC,KAAK,GAAGlB,2BAA2BC,OAAOC,WAAWC,QAAQa;QACtE;QACA,OAAOC,OAAOC,KAAK;IACrB,EAAE,OAAON,OAAO;QACd,IAAI,CAACK,OAAOC,KAAK,IAAI,CAACP,mBAAmBC,QAAQ,MAAMA;QACvD,MAAMG,OAAOI;QACb,OAAO;IACT;AACF;AAEA;;;;;;CAMC,GACD,OAAO,eAAeC,2BACpBF,KAA+B,EAC/BG,MAAiC;IAEjC,IAAI,CAACH,SAASG,WAAW,MAAM;IAC/B,MAAM1B,UAAUuB,OAAOI,KAAK,CAAC,IAAYH;AAC3C"}

package/src/lib/app-utils/transfer-launcher-context.d.ts

@@ -82,6 +82,12 @@ export interface TransferExportLaunch {
         label: string;
         value: unknown;
     };
+    /**
+     * One of the resource's own presets to open on (`TransferResourcePreset.id`)
+     * — a list's "Export for Pirate Ship" — instead of the person's last
+     * choice. An id the resource does not offer is ignored.
+     */
+    preset?: string;
 }
 /** What a person may do with a resource's records. */
 export type TransferAction = 'import' | 'export';

package/src/lib/app-utils/transfer-launcher-context.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/transfer-launcher-context.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\nimport { createContext, useContext } from 'react'\nimport type { TransferUnfinishedImportSummary } from '../data-transfer/transfer-api'\n\n/**\n * The console shell's import wizard and export dialog, for a plugin to open.\n *\n * The wizard and the dialog are the console's private UI kit, which a\n * published plugin cannot depend on. So the shell hands down a launcher\n * through this context, and a plugin's list or hub opens the wizard for its\n * own resource — the key it declared in `transferResources` — with\n * `useTransferLauncher()?.openImport({ resource, scope })`.\n *\n * Outside the console shell — a spec, a tenant page, a surface mounted by\n * something else — the context holds `null`, and a plugin hides its Import\n * and Export actions: with no shell there is no workspace to move data into.\n *\n * Inside it, `can('import' | 'export', target)` says which of the two this\n * person may use (AGL-3546): a plugin shows Import only when `can('import')`\n * and Export only when `can('export')`. The transfer routes stay the\n * enforcement; `can` answers what they would.\n *\n * Only types and a context: it names no resource, imports nothing from the\n * transfer core, and so costs the barrel nothing past React.\n *\n * A client-only context like the others in `contexts.ts`: it calls\n * `createContext` at module scope, so it is reachable from the full\n * `@aglyn/aglyn` barrel (and this subpath) and never from\n * `@aglyn/aglyn/server` (AGL-405).\n */\n\n/** Where the records live: the workspace, or one of its sites. */\nexport type TransferLaunchScope = 'org' | 'host'\n\n/** Opens the import wizard on one resource. */\nexport interface TransferImportLaunch {\n  /**\n   * The resource key the plugin declared in `transferResources` — for one\n   * declared with `instances`, the key naming the instance\n   * (`data.dataset:<datasetId>`).\n   */\n  resource: string\n  scope: TransferLaunchScope\n  /** The wizard's title, naming the instance (\"Import into Products\"); \"Import <resource label>\" when absent. */\n  title?: string\n  /** The site, for a `host` resource. */\n  hostId?: string | null\n  /** Resume this import instead of starting a new one. */\n  jobId?: string | null\n  /**\n   * What the file is imported as, as the `importMapping` zone's widgets know\n   * it (`contacts`); omitted, the mapping step shows no zone.\n   */\n  mappingZone?: string\n  /** Called when the person leaves the wizard from its results with Done. */\n  onFinished?(): void\n}\n\n/** Opens the export dialog on one resource. */\nexport interface TransferExportLaunch {\n  /** The resource key the plugin declared in `transferResources`, naming the instance for one declared with `instances`. */\n  resource: string\n  scope: TransferLaunchScope\n  /** The dialog's title, naming the instance (\"Export Products\"); \"Export <resource label>\" when absent. */\n  title?: string\n  /** The site, for a `host` resource. */\n  hostId?: string | null\n  /** The record ids the person selected in the list, when there is a selection. */\n  selection?: readonly string[]\n  /** The list's current filter: a name for it, and the value the resource's `readPage` reads. */\n  filter?: { label: string; value: unknown }\n}\n\n/** What a person may do with a resource's records. */\nexport type TransferAction = 'import' | 'export'\n\n/** The resource a list asks {@link TransferLauncher.can} about. */\nexport interface TransferAccessTarget {\n  /** The resource key, naming the instance for one declared with `instances`. */\n  resource: string\n  scope: TransferLaunchScope\n  /** The site, for a `host` resource or a workspace resource read through one site. */\n  hostId?: string | null\n}\n\n/**\n * An import the person started and left before it wrote anything\n * (AGL-3549) — a tab closed mid-wizard — which `openImport({ jobId })`\n * reopens on the step it was left at.\n */\nexport type TransferUnfinishedImport = TransferUnfinishedImportSummary\n\n/** What the shell offers: open the wizard or the dialog, or close whichever is open. */\nexport interface TransferLauncher {\n  openImport(launch: TransferImportLaunch): void\n  openExport(launch: TransferExportLaunch): void\n  close(): void\n  /**\n   * Whether the person may `action` the target's records (AGL-3546) — the\n   * answer the transfer routes give, from the permissions the shell already\n   * holds: synchronous, with no request per button, and `false` until those\n   * permissions have answered. Importing needs \"Manage data\" (on the named\n   * site, for a site's records); exporting needs only access to the\n   * records — membership, and reaching the named site — unless the resource\n   * declares a `readPermission`. The routes stay the enforcement.\n   */\n  can(action: TransferAction, target: TransferAccessTarget): boolean\n  /**\n   * The person's own unfinished imports (AGL-3549), newest first: of the\n   * target's resource — the exact key, so one dataset's are not another's —\n   * on the target's site when it names one, when a target is given; every\n   * one otherwise. Empty\n   * until the shell has read them; the first ask starts the read, and the\n   * list is read again whenever the wizard closes. Only for a person who may\n   * import into the workspace.\n   */\n  unfinished?(target?: TransferAccessTarget): readonly TransferUnfinishedImport[]\n  /**\n   * Throws an unfinished import away now — its job, its file and its saved\n   * choices — instead of leaving it to expire. Refused for an import that\n   * has written anything, which is undone instead.\n   */\n  discard?(jobId: string): Promise<void>\n}\n\nexport const TransferLauncherContext = createContext<TransferLauncher | null>(null)\nTransferLauncherContext.displayName = 'TransferLauncherContext'\n\n/** The shell's launcher, or `null` outside the console shell. */\nexport function useTransferLauncher(): TransferLauncher | null {\n  return useContext(TransferLauncherContext)\n}\n\n"],"names":["createContext","useContext","TransferLauncherContext","displayName","useTransferLauncher"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,aAAa,EAAEC,UAAU,QAAQ,QAAO;AA4HjD,OAAO,MAAMC,0BAA0BF,cAAuC,MAAK;AACnFE,wBAAwBC,WAAW,GAAG;AAEtC,+DAA+D,GAC/D,OAAO,SAASC;IACd,OAAOH,WAAWC;AACpB"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/transfer-launcher-context.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\nimport { createContext, useContext } from 'react'\nimport type { TransferUnfinishedImportSummary } from '../data-transfer/transfer-api'\n\n/**\n * The console shell's import wizard and export dialog, for a plugin to open.\n *\n * The wizard and the dialog are the console's private UI kit, which a\n * published plugin cannot depend on. So the shell hands down a launcher\n * through this context, and a plugin's list or hub opens the wizard for its\n * own resource — the key it declared in `transferResources` — with\n * `useTransferLauncher()?.openImport({ resource, scope })`.\n *\n * Outside the console shell — a spec, a tenant page, a surface mounted by\n * something else — the context holds `null`, and a plugin hides its Import\n * and Export actions: with no shell there is no workspace to move data into.\n *\n * Inside it, `can('import' | 'export', target)` says which of the two this\n * person may use (AGL-3546): a plugin shows Import only when `can('import')`\n * and Export only when `can('export')`. The transfer routes stay the\n * enforcement; `can` answers what they would.\n *\n * Only types and a context: it names no resource, imports nothing from the\n * transfer core, and so costs the barrel nothing past React.\n *\n * A client-only context like the others in `contexts.ts`: it calls\n * `createContext` at module scope, so it is reachable from the full\n * `@aglyn/aglyn` barrel (and this subpath) and never from\n * `@aglyn/aglyn/server` (AGL-405).\n */\n\n/** Where the records live: the workspace, or one of its sites. */\nexport type TransferLaunchScope = 'org' | 'host'\n\n/** Opens the import wizard on one resource. */\nexport interface TransferImportLaunch {\n  /**\n   * The resource key the plugin declared in `transferResources` — for one\n   * declared with `instances`, the key naming the instance\n   * (`data.dataset:<datasetId>`).\n   */\n  resource: string\n  scope: TransferLaunchScope\n  /** The wizard's title, naming the instance (\"Import into Products\"); \"Import <resource label>\" when absent. */\n  title?: string\n  /** The site, for a `host` resource. */\n  hostId?: string | null\n  /** Resume this import instead of starting a new one. */\n  jobId?: string | null\n  /**\n   * What the file is imported as, as the `importMapping` zone's widgets know\n   * it (`contacts`); omitted, the mapping step shows no zone.\n   */\n  mappingZone?: string\n  /** Called when the person leaves the wizard from its results with Done. */\n  onFinished?(): void\n}\n\n/** Opens the export dialog on one resource. */\nexport interface TransferExportLaunch {\n  /** The resource key the plugin declared in `transferResources`, naming the instance for one declared with `instances`. */\n  resource: string\n  scope: TransferLaunchScope\n  /** The dialog's title, naming the instance (\"Export Products\"); \"Export <resource label>\" when absent. */\n  title?: string\n  /** The site, for a `host` resource. */\n  hostId?: string | null\n  /** The record ids the person selected in the list, when there is a selection. */\n  selection?: readonly string[]\n  /** The list's current filter: a name for it, and the value the resource's `readPage` reads. */\n  filter?: { label: string; value: unknown }\n  /**\n   * One of the resource's own presets to open on (`TransferResourcePreset.id`)\n   * — a list's \"Export for Pirate Ship\" — instead of the person's last\n   * choice. An id the resource does not offer is ignored.\n   */\n  preset?: string\n}\n\n/** What a person may do with a resource's records. */\nexport type TransferAction = 'import' | 'export'\n\n/** The resource a list asks {@link TransferLauncher.can} about. */\nexport interface TransferAccessTarget {\n  /** The resource key, naming the instance for one declared with `instances`. */\n  resource: string\n  scope: TransferLaunchScope\n  /** The site, for a `host` resource or a workspace resource read through one site. */\n  hostId?: string | null\n}\n\n/**\n * An import the person started and left before it wrote anything\n * (AGL-3549) — a tab closed mid-wizard — which `openImport({ jobId })`\n * reopens on the step it was left at.\n */\nexport type TransferUnfinishedImport = TransferUnfinishedImportSummary\n\n/** What the shell offers: open the wizard or the dialog, or close whichever is open. */\nexport interface TransferLauncher {\n  openImport(launch: TransferImportLaunch): void\n  openExport(launch: TransferExportLaunch): void\n  close(): void\n  /**\n   * Whether the person may `action` the target's records (AGL-3546) — the\n   * answer the transfer routes give, from the permissions the shell already\n   * holds: synchronous, with no request per button, and `false` until those\n   * permissions have answered. Importing needs \"Manage data\" (on the named\n   * site, for a site's records); exporting needs only access to the\n   * records — membership, and reaching the named site — unless the resource\n   * declares a `readPermission`. The routes stay the enforcement.\n   */\n  can(action: TransferAction, target: TransferAccessTarget): boolean\n  /**\n   * The person's own unfinished imports (AGL-3549), newest first: of the\n   * target's resource — the exact key, so one dataset's are not another's —\n   * on the target's site when it names one, when a target is given; every\n   * one otherwise. Empty\n   * until the shell has read them; the first ask starts the read, and the\n   * list is read again whenever the wizard closes. Only for a person who may\n   * import into the workspace.\n   */\n  unfinished?(target?: TransferAccessTarget): readonly TransferUnfinishedImport[]\n  /**\n   * Throws an unfinished import away now — its job, its file and its saved\n   * choices — instead of leaving it to expire. Refused for an import that\n   * has written anything, which is undone instead.\n   */\n  discard?(jobId: string): Promise<void>\n}\n\nexport const TransferLauncherContext = createContext<TransferLauncher | null>(null)\nTransferLauncherContext.displayName = 'TransferLauncherContext'\n\n/** The shell's launcher, or `null` outside the console shell. */\nexport function useTransferLauncher(): TransferLauncher | null {\n  return useContext(TransferLauncherContext)\n}\n\n"],"names":["createContext","useContext","TransferLauncherContext","displayName","useTransferLauncher"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,aAAa,EAAEC,UAAU,QAAQ,QAAO;AAkIjD,OAAO,MAAMC,0BAA0BF,cAAuC,MAAK;AACnFE,wBAAwBC,WAAW,GAAG;AAEtC,+DAA+D,GAC/D,OAAO,SAASC;IACd,OAAOH,WAAWC;AACpB"}

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

@@ -417,6 +417,13 @@ const ascii = (text)=>Array.from(text, (character)=>character.charCodeAt(0));
             ],
             label: 'Matroska/WebM'
         }
+    ],
+    // A web font (AGL-3656): the theme's font installer stores WOFF2 only.
+    'font/woff2': [
+        {
+            magic: ascii('wOF2'),
+            label: 'WOFF2'
+        }
     ]
 };
 /** The OOXML document types whose archive is scanned for a macro project. */ const OOXML_DOCUMENT_TYPES = new Set([

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/upload-inspection.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 * STRUCTURAL upload inspection (AGL-1475).\n *\n * ## What this is, and what it is emphatically not\n *\n * This is **not** an antivirus scanner and no code in this module should ever\n * be described as one. It does not have malware signatures, it does not\n * emulate, unpack or detonate anything, and a novel trojan with a correct PDF\n * header passes it without a murmur. It is *structural validation*: it reads\n * the first few kilobytes of an upload and answers three questions the\n * platform previously could not ask at all.\n *\n * 1. **Are these bytes an executable?** A Windows PE, an ELF binary, a Mach-O\n *    binary or an installer package is refused whatever it claims to be. This\n *    is the single highest-value check here: the Sept-1 risk is a customer's\n *    domain re-serving a trojan to a visitor's browser, and the overwhelming\n *    majority of that population is a plain executable with a lying name.\n * 2. **Do the bytes match the declared type?** Media ingress trusted the\n *    caller's content type completely — AGL-2463 wrote that gap down. The\n *    allowlist bounded what a file *claimed* to be and nothing bounded what it\n *    *was*, so `Content-Type: application/pdf` over a `.exe` was stored,\n *    hashed, given a CDN path and served. It now has to be a PDF.\n * 3. **Does an Office document carry a macro project?** AGL-1465 kept\n *    `.docm`/`.xlsm`/`.pptm` out **by content type**, which is a gate on a\n *    string the uploader chooses. Renaming a macro-enabled document to\n *    `.docx` walked straight past it. The archive is now checked for a\n *    `vbaProject.bin` entry, which is the thing that made those extensions\n *    worth excluding in the first place.\n *\n * Plus one signature, EICAR — see {@link EICAR_TEST_SIGNATURE}.\n *\n * ## What it therefore does not catch\n *\n * A malicious PDF that is a real PDF. A macro-free document that exploits a\n * reader. Anything inside a plain `application/zip`, which is a brand kit and\n * may legitimately contain a build tool. An obfuscated dropper in a JSON\n * file. Real malware detection needs signatures and an engine, which needs a\n * ClamAV service, which does not fit the budget this platform runs on — the\n * cost work is in the issue. Nothing here should be allowed to read as though\n * that decision went the other way.\n *\n * ## Why it is pure, and takes a window rather than a file\n *\n * Three of the four media chokepoints hold the whole file in memory and can\n * pass it straight in. The fourth — signed direct-to-storage upload — never\n * sees the bytes, because that is the entire reason it exists: a 200 MB video\n * goes browser → bucket and downloading it back into the function to look at\n * it would cost more than the feature. So that caller does two RANGED reads\n * instead, a few KB from each end, and passes them as {@link\n * InspectUploadInput.bytes} and {@link InspectUploadInput.tail}. Every\n * signature this module knows lives in one of those two windows, so the\n * signed route gets the same verdict for the price of a rounding error.\n */\n\n/**\n * The EICAR standard antivirus test string.\n *\n * A 68-byte printable string, defined by the European Institute for Computer\n * Antivirus Research, that every antivirus product agrees to flag and that is\n * completely inert. It exists so that a pipeline can be tested end to end\n * without anyone handling a live sample.\n *\n * It is matched here for exactly two reasons, and neither is malware\n * detection. First, it makes this module's own tests honest without checking\n * a real sample into the repository. Second, it is the probe a security\n * reviewer or a customer will actually try, and answering it with silence\n * would be a worse lie than answering it with a refusal — a refusal that says\n * \"structural check\" is true, where a silent accept invites the reader to\n * conclude nothing is checked at all.\n *\n * **This is a signature list of one. It is not an engine.** Do not add a\n * second entry here and start calling the result malware scanning; if real\n * signatures are wanted, they belong in a scanner service, not in a string\n * constant.\n */\nexport const EICAR_TEST_SIGNATURE =\n  'X5O!P%@AP[4\\\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*'\n\n/**\n * How many leading bytes an inspection needs.\n *\n * Every magic number checked here sits in the first 16 bytes; the window is\n * far larger so that the EICAR match and the small-file macro scan have room,\n * and because the signed route's ranged GET costs the same for 4 KB as for\n * 64 bytes.\n */\nexport const UPLOAD_INSPECTION_HEAD_BYTES = 4096\n\n/**\n * How many trailing bytes an inspection wants for an Office document.\n *\n * A ZIP's central directory — the authoritative list of what is inside it —\n * lives at the end of the file. 64 KB covers the directory of any document\n * archive this platform accepts (the largest ceiling is a 50 MB `.pptx`, and\n * its directory is a few KB even with hundreds of embedded images). A\n * document whose directory is somehow larger than this window degrades to\n * \"macro not found\", which is the pre-existing behaviour, not a regression.\n */\nexport const UPLOAD_INSPECTION_TAIL_BYTES = 65536\n\nexport type UploadInspectionCode =\n  | 'signature_match'\n  | 'executable_bytes'\n  | 'type_mismatch'\n  | 'macro_payload'\n  | 'empty_file'\n\nexport interface UploadInspectionRefusal {\n  /** Stable machine code — for the API error body, logs and tests. */\n  code: UploadInspectionCode\n  /** What the bytes turned out to be, in words rather than hex. */\n  detected: string\n  /**\n   * The sentence the uploader sees. Names the file and what was found, so\n   * that a merchant who did nothing wrong can tell which of fifty dropped\n   * files was the problem and why.\n   */\n  message: string\n}\n\nexport interface InspectUploadInput {\n  /**\n   * The whole file, or its leading {@link UPLOAD_INSPECTION_HEAD_BYTES}.\n   * Callers holding the whole file pass it and omit `tail`.\n   */\n  bytes: Uint8Array\n  /**\n   * The file's trailing bytes, supplied ONLY by a caller that passed a head\n   * window rather than the whole file. When absent, `bytes` is searched for\n   * the trailing structures too — which is correct precisely because a caller\n   * that omits it is one that handed over the entire file.\n   */\n  tail?: Uint8Array | null\n  /** The type the upload claims to be, already normalized by the caller. */\n  contentType: string\n  /** For the message only. Never used to decide anything. */\n  fileName?: string | null\n}\n\ninterface Signature {\n  /** Bytes to match. */\n  magic: readonly number[]\n  /** Where they start. */\n  offset?: number\n  /** Human name for the refusal message. */\n  label: string\n}\n\nconst at = (bytes: Uint8Array, signature: Signature): boolean => {\n  const offset = signature.offset ?? 0\n  if (bytes.length < offset + signature.magic.length) return false\n  for (let i = 0; i < signature.magic.length; i++) {\n    if (bytes[offset + i] !== signature.magic[i]) return false\n  }\n  return true\n}\n\nconst ascii = (text: string): number[] =>\n  Array.from(text, (character) => character.charCodeAt(0))\n\n/**\n * Executable and installer containers, refused whatever the upload claims to\n * be. This list is deliberately about CONTAINERS, not content: each entry is\n * a format whose entire purpose is to be run, and none of them has any\n * business in a media library under any content type.\n *\n * `#!` is NOT here on purpose. A shebang is two characters that a legitimate\n * `text/plain` upload can genuinely open with, it is not executable in a\n * browser, and the type-mismatch check below already refuses it under every\n * binary type. Refusing it outright would buy nothing and cost real uploads.\n */\nconst EXECUTABLE_SIGNATURES: readonly Signature[] = [\n  { magic: ascii('MZ'), label: 'a Windows executable' },\n  { magic: [0x7f, 0x45, 0x4c, 0x46], label: 'a Linux executable (ELF)' },\n  { magic: [0xfe, 0xed, 0xfa, 0xce], label: 'a macOS executable (Mach-O)' },\n  { magic: [0xfe, 0xed, 0xfa, 0xcf], label: 'a macOS executable (Mach-O)' },\n  { magic: [0xce, 0xfa, 0xed, 0xfe], label: 'a macOS executable (Mach-O)' },\n  { magic: [0xcf, 0xfa, 0xed, 0xfe], label: 'a macOS executable (Mach-O)' },\n  // 0xCAFEBABE is both a Java class file and a multi-architecture Mach-O\n  // binary. Both are code; the label names the likelier one for a DAM.\n  { magic: [0xca, 0xfe, 0xba, 0xbe], label: 'a compiled program' },\n  { magic: ascii('!<arch>'), label: 'an installer package' },\n  { magic: [0xed, 0xab, 0xee, 0xdb], label: 'an installer package (RPM)' },\n  // Windows shortcut — a .lnk is a launcher, and a classic phishing payload.\n  { magic: [0x4c, 0x00, 0x00, 0x00, 0x01, 0x14, 0x02, 0x00], label: 'a Windows shortcut' },\n]\n\n/** ZIP, in its three legal opening forms. Every OOXML document is one. */\nconst ZIP_SIGNATURES: readonly Signature[] = [\n  { magic: [0x50, 0x4b, 0x03, 0x04], label: 'ZIP' },\n  { magic: [0x50, 0x4b, 0x05, 0x06], label: 'ZIP' },\n  { magic: [0x50, 0x4b, 0x07, 0x08], label: 'ZIP' },\n]\n\n/** Microsoft's pre-2007 container: legacy `.doc`, `.xls`, `.ppt` and `.msi`. */\nconst OLE_SIGNATURE: Signature = {\n  magic: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1],\n  label: 'a legacy Office document',\n}\n\n/** ISO base media (`....ftyp`) — mp4, QuickTime, and the modern image codecs. */\nconst ISO_BMFF: Signature = { magic: ascii('ftyp'), offset: 4, label: 'ISO media' }\n\n/**\n * Accepted content type → the signatures its bytes may legally start with.\n *\n * A type ABSENT from this table is not checked for a match, and that is a\n * deliberate, load-bearing property rather than a gap to be filled with\n * guesses. `text/plain`, `text/csv`, `text/markdown`, `application/json` and\n * `image/svg+xml` are text: they have no magic number, any leading bytes are\n * legal, and inventing a heuristic for them would refuse real files. They are\n * still covered by the executable check above, which is the check that\n * matters for them — an `.exe` renamed `notes.txt` is refused; a CSV that is\n * merely unusual is not.\n */\nconst TYPE_SIGNATURES: Readonly<Record<string, readonly Signature[]>> = {\n  'application/pdf': [{ magic: ascii('%PDF-'), label: 'PDF' }],\n  'application/zip': ZIP_SIGNATURES,\n  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': ZIP_SIGNATURES,\n  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': ZIP_SIGNATURES,\n  'application/vnd.openxmlformats-officedocument.presentationml.presentation': ZIP_SIGNATURES,\n  // Word writes RTF under a `.doc` name often enough that refusing it would\n  // be a real false positive, so both containers are legal for this type.\n  'application/msword': [OLE_SIGNATURE, { magic: ascii('{\\\\rtf'), label: 'RTF' }],\n  'application/vnd.ms-excel': [OLE_SIGNATURE],\n  'application/vnd.ms-powerpoint': [OLE_SIGNATURE],\n  'application/rtf': [{ magic: ascii('{\\\\rtf'), label: 'RTF' }],\n\n  'image/png': [{ magic: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], label: 'PNG' }],\n  'image/jpeg': [{ magic: [0xff, 0xd8, 0xff], label: 'JPEG' }],\n  'image/gif': [\n    { magic: ascii('GIF87a'), label: 'GIF' },\n    { magic: ascii('GIF89a'), label: 'GIF' },\n  ],\n  'image/webp': [{ magic: ascii('RIFF'), label: 'WebP' }],\n  'image/bmp': [{ magic: ascii('BM'), label: 'BMP' }],\n  'image/tiff': [\n    { magic: [0x49, 0x49, 0x2a, 0x00], label: 'TIFF' },\n    { magic: [0x4d, 0x4d, 0x00, 0x2a], label: 'TIFF' },\n  ],\n  'image/x-icon': [{ magic: [0x00, 0x00, 0x01, 0x00], label: 'icon' }],\n  'image/vnd.microsoft.icon': [{ magic: [0x00, 0x00, 0x01, 0x00], label: 'icon' }],\n  'image/avif': [ISO_BMFF],\n  'image/heic': [ISO_BMFF],\n  'image/heif': [ISO_BMFF],\n\n  'video/mp4': [ISO_BMFF],\n  'video/quicktime': [ISO_BMFF],\n  'video/webm': [{ magic: [0x1a, 0x45, 0xdf, 0xa3], label: 'Matroska/WebM' }],\n}\n\n/** The OOXML document types whose archive is scanned for a macro project. */\nconst OOXML_DOCUMENT_TYPES = new Set([\n  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',\n  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',\n  'application/vnd.openxmlformats-officedocument.presentationml.presentation',\n])\n\n/** The pre-2007 Office types whose OLE directory is scanned for the same. */\nconst LEGACY_OFFICE_TYPES = new Set([\n  'application/msword',\n  'application/vnd.ms-excel',\n  'application/vnd.ms-powerpoint',\n])\n\n/**\n * Does a caller holding only a head window need to fetch the tail as well?\n *\n * Only the macro scan reads the end of a file, and only for document\n * archives, so this is what lets the signed-upload route skip a second ranged\n * GET for the 200 MB videos that route exists to carry — which is every\n * object on it bar a handful of documents.\n */\nexport function uploadInspectionNeedsTail(contentType: string): boolean {\n  return (\n    OOXML_DOCUMENT_TYPES.has(contentType) || LEGACY_OFFICE_TYPES.has(contentType)\n  )\n}\n\nconst indexOfBytes = (haystack: Uint8Array, needle: Uint8Array): number => {\n  if (!needle.length || haystack.length < needle.length) return -1\n  const last = haystack.length - needle.length\n  outer: for (let i = 0; i <= last; i++) {\n    for (let j = 0; j < needle.length; j++) {\n      if (haystack[i + j] !== needle[j]) continue outer\n    }\n    return i\n  }\n  return -1\n}\n\nconst contains = (haystack: Uint8Array, needle: Uint8Array): boolean =>\n  indexOfBytes(haystack, needle) >= 0\n\nconst EICAR_BYTES = new Uint8Array(ascii(EICAR_TEST_SIGNATURE))\n\n/** `vbaProject.bin` as an OOXML archive entry name. */\nconst VBA_ENTRY = new Uint8Array(ascii('vbaProject.bin'))\n\n/**\n * `_VBA_PROJECT` as it appears in an OLE directory, which stores stream names\n * as UTF-16LE. Matching the encoded form rather than the ASCII one is what\n * keeps this from firing on a document that merely contains the words.\n */\nconst OLE_VBA_STREAM = new Uint8Array(\n  ascii('_VBA_PROJECT').flatMap((code) => [code, 0x00]),\n)\n\nconst describeFile = (fileName?: string | null): string => {\n  const name = String(fileName ?? '').trim()\n  return name ? `\"${name}\"` : 'This file'\n}\n\n/**\n * Inspect an upload's bytes against the type it claims to be.\n *\n * Returns `null` when nothing structural is wrong — which, to be explicit, is\n * NOT a statement that the file is safe. See the module header.\n */\nexport function inspectUploadBytes(\n  input: InspectUploadInput,\n): UploadInspectionRefusal | null {\n  const { bytes, contentType, fileName } = input\n  const head = bytes ?? new Uint8Array(0)\n  // A caller that passed the whole file gets the whole file searched for the\n  // trailing structures too; only a ranged caller supplies a separate tail.\n  const tail = input.tail ?? head\n  const subject = describeFile(fileName)\n\n  if (!head.length) {\n    return {\n      code: 'empty_file',\n      detected: 'an empty file',\n      message: `${subject} is empty, so there is nothing to store.`,\n    }\n  }\n\n  // 1. The signature list of one. Checked first so that a probe gets the\n  //    answer it is actually asking for, whatever else is also wrong.\n  if (contains(head, EICAR_BYTES) || contains(tail, EICAR_BYTES)) {\n    return {\n      code: 'signature_match',\n      detected: 'the EICAR antivirus test file',\n      message:\n        `${subject} matches the EICAR test signature and was refused by the ` +\n        `upload structure check.`,\n    }\n  }\n\n  // 2. Executable containers, refused under every declared type.\n  for (const signature of EXECUTABLE_SIGNATURES) {\n    if (at(head, signature)) {\n      return {\n        code: 'executable_bytes',\n        detected: signature.label,\n        message:\n          `${subject} contains ${signature.label}, which cannot be uploaded ` +\n          `whatever it is named or labeled.`,\n      }\n    }\n  }\n\n  // 3. The declared type against what the bytes actually are.\n  const expected = TYPE_SIGNATURES[contentType]\n  if (expected && !expected.some((signature) => at(head, signature))) {\n    return {\n      code: 'type_mismatch',\n      detected: `something other than ${expected[0].label}`,\n      message:\n        `${subject} is labeled ${contentType} but its contents are not ` +\n        `${expected[0].label}. Re-save it in the format it claims to be, or ` +\n        `upload it under its real type.`,\n    }\n  }\n\n  // 4. A macro project inside a document whose type is not supposed to have\n  //    one. This is the check the content-type allowlist could never make.\n  if (OOXML_DOCUMENT_TYPES.has(contentType)) {\n    if (contains(head, VBA_ENTRY) || contains(tail, VBA_ENTRY)) {\n      return {\n        code: 'macro_payload',\n        detected: 'an embedded macro project',\n        message:\n          `${subject} contains an embedded macro project. Macro-enabled ` +\n          `documents are not accepted — save it without macros and upload ` +\n          `it again.`,\n      }\n    }\n  } else if (LEGACY_OFFICE_TYPES.has(contentType)) {\n    if (contains(head, OLE_VBA_STREAM) || contains(tail, OLE_VBA_STREAM)) {\n      return {\n        code: 'macro_payload',\n        detected: 'an embedded macro project',\n        message:\n          `${subject} contains an embedded macro project. Macro-enabled ` +\n          `documents are not accepted — save it without macros and upload ` +\n          `it again.`,\n      }\n    }\n  }\n\n  return null\n}\n\nexport default inspectUploadBytes\n"],"names":["EICAR_TEST_SIGNATURE","UPLOAD_INSPECTION_HEAD_BYTES","UPLOAD_INSPECTION_TAIL_BYTES","at","bytes","signature","offset","length","magic","i","ascii","text","Array","from","character","charCodeAt","EXECUTABLE_SIGNATURES","label","ZIP_SIGNATURES","OLE_SIGNATURE","ISO_BMFF","TYPE_SIGNATURES","OOXML_DOCUMENT_TYPES","Set","LEGACY_OFFICE_TYPES","uploadInspectionNeedsTail","contentType","has","indexOfBytes","haystack","needle","last","outer","j","contains","EICAR_BYTES","Uint8Array","VBA_ENTRY","OLE_VBA_STREAM","flatMap","code","describeFile","fileName","name","String","trim","inspectUploadBytes","input","head","tail","subject","detected","message","expected","some"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/upload-inspection.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 * STRUCTURAL upload inspection (AGL-1475).\n *\n * ## What this is, and what it is emphatically not\n *\n * This is **not** an antivirus scanner and no code in this module should ever\n * be described as one. It does not have malware signatures, it does not\n * emulate, unpack or detonate anything, and a novel trojan with a correct PDF\n * header passes it without a murmur. It is *structural validation*: it reads\n * the first few kilobytes of an upload and answers three questions the\n * platform previously could not ask at all.\n *\n * 1. **Are these bytes an executable?** A Windows PE, an ELF binary, a Mach-O\n *    binary or an installer package is refused whatever it claims to be. This\n *    is the single highest-value check here: the Sept-1 risk is a customer's\n *    domain re-serving a trojan to a visitor's browser, and the overwhelming\n *    majority of that population is a plain executable with a lying name.\n * 2. **Do the bytes match the declared type?** Media ingress trusted the\n *    caller's content type completely — AGL-2463 wrote that gap down. The\n *    allowlist bounded what a file *claimed* to be and nothing bounded what it\n *    *was*, so `Content-Type: application/pdf` over a `.exe` was stored,\n *    hashed, given a CDN path and served. It now has to be a PDF.\n * 3. **Does an Office document carry a macro project?** AGL-1465 kept\n *    `.docm`/`.xlsm`/`.pptm` out **by content type**, which is a gate on a\n *    string the uploader chooses. Renaming a macro-enabled document to\n *    `.docx` walked straight past it. The archive is now checked for a\n *    `vbaProject.bin` entry, which is the thing that made those extensions\n *    worth excluding in the first place.\n *\n * Plus one signature, EICAR — see {@link EICAR_TEST_SIGNATURE}.\n *\n * ## What it therefore does not catch\n *\n * A malicious PDF that is a real PDF. A macro-free document that exploits a\n * reader. Anything inside a plain `application/zip`, which is a brand kit and\n * may legitimately contain a build tool. An obfuscated dropper in a JSON\n * file. Real malware detection needs signatures and an engine, which needs a\n * ClamAV service, which does not fit the budget this platform runs on — the\n * cost work is in the issue. Nothing here should be allowed to read as though\n * that decision went the other way.\n *\n * ## Why it is pure, and takes a window rather than a file\n *\n * Three of the four media chokepoints hold the whole file in memory and can\n * pass it straight in. The fourth — signed direct-to-storage upload — never\n * sees the bytes, because that is the entire reason it exists: a 200 MB video\n * goes browser → bucket and downloading it back into the function to look at\n * it would cost more than the feature. So that caller does two RANGED reads\n * instead, a few KB from each end, and passes them as {@link\n * InspectUploadInput.bytes} and {@link InspectUploadInput.tail}. Every\n * signature this module knows lives in one of those two windows, so the\n * signed route gets the same verdict for the price of a rounding error.\n */\n\n/**\n * The EICAR standard antivirus test string.\n *\n * A 68-byte printable string, defined by the European Institute for Computer\n * Antivirus Research, that every antivirus product agrees to flag and that is\n * completely inert. It exists so that a pipeline can be tested end to end\n * without anyone handling a live sample.\n *\n * It is matched here for exactly two reasons, and neither is malware\n * detection. First, it makes this module's own tests honest without checking\n * a real sample into the repository. Second, it is the probe a security\n * reviewer or a customer will actually try, and answering it with silence\n * would be a worse lie than answering it with a refusal — a refusal that says\n * \"structural check\" is true, where a silent accept invites the reader to\n * conclude nothing is checked at all.\n *\n * **This is a signature list of one. It is not an engine.** Do not add a\n * second entry here and start calling the result malware scanning; if real\n * signatures are wanted, they belong in a scanner service, not in a string\n * constant.\n */\nexport const EICAR_TEST_SIGNATURE =\n  'X5O!P%@AP[4\\\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*'\n\n/**\n * How many leading bytes an inspection needs.\n *\n * Every magic number checked here sits in the first 16 bytes; the window is\n * far larger so that the EICAR match and the small-file macro scan have room,\n * and because the signed route's ranged GET costs the same for 4 KB as for\n * 64 bytes.\n */\nexport const UPLOAD_INSPECTION_HEAD_BYTES = 4096\n\n/**\n * How many trailing bytes an inspection wants for an Office document.\n *\n * A ZIP's central directory — the authoritative list of what is inside it —\n * lives at the end of the file. 64 KB covers the directory of any document\n * archive this platform accepts (the largest ceiling is a 50 MB `.pptx`, and\n * its directory is a few KB even with hundreds of embedded images). A\n * document whose directory is somehow larger than this window degrades to\n * \"macro not found\", which is the pre-existing behaviour, not a regression.\n */\nexport const UPLOAD_INSPECTION_TAIL_BYTES = 65536\n\nexport type UploadInspectionCode =\n  | 'signature_match'\n  | 'executable_bytes'\n  | 'type_mismatch'\n  | 'macro_payload'\n  | 'empty_file'\n\nexport interface UploadInspectionRefusal {\n  /** Stable machine code — for the API error body, logs and tests. */\n  code: UploadInspectionCode\n  /** What the bytes turned out to be, in words rather than hex. */\n  detected: string\n  /**\n   * The sentence the uploader sees. Names the file and what was found, so\n   * that a merchant who did nothing wrong can tell which of fifty dropped\n   * files was the problem and why.\n   */\n  message: string\n}\n\nexport interface InspectUploadInput {\n  /**\n   * The whole file, or its leading {@link UPLOAD_INSPECTION_HEAD_BYTES}.\n   * Callers holding the whole file pass it and omit `tail`.\n   */\n  bytes: Uint8Array\n  /**\n   * The file's trailing bytes, supplied ONLY by a caller that passed a head\n   * window rather than the whole file. When absent, `bytes` is searched for\n   * the trailing structures too — which is correct precisely because a caller\n   * that omits it is one that handed over the entire file.\n   */\n  tail?: Uint8Array | null\n  /** The type the upload claims to be, already normalized by the caller. */\n  contentType: string\n  /** For the message only. Never used to decide anything. */\n  fileName?: string | null\n}\n\ninterface Signature {\n  /** Bytes to match. */\n  magic: readonly number[]\n  /** Where they start. */\n  offset?: number\n  /** Human name for the refusal message. */\n  label: string\n}\n\nconst at = (bytes: Uint8Array, signature: Signature): boolean => {\n  const offset = signature.offset ?? 0\n  if (bytes.length < offset + signature.magic.length) return false\n  for (let i = 0; i < signature.magic.length; i++) {\n    if (bytes[offset + i] !== signature.magic[i]) return false\n  }\n  return true\n}\n\nconst ascii = (text: string): number[] =>\n  Array.from(text, (character) => character.charCodeAt(0))\n\n/**\n * Executable and installer containers, refused whatever the upload claims to\n * be. This list is deliberately about CONTAINERS, not content: each entry is\n * a format whose entire purpose is to be run, and none of them has any\n * business in a media library under any content type.\n *\n * `#!` is NOT here on purpose. A shebang is two characters that a legitimate\n * `text/plain` upload can genuinely open with, it is not executable in a\n * browser, and the type-mismatch check below already refuses it under every\n * binary type. Refusing it outright would buy nothing and cost real uploads.\n */\nconst EXECUTABLE_SIGNATURES: readonly Signature[] = [\n  { magic: ascii('MZ'), label: 'a Windows executable' },\n  { magic: [0x7f, 0x45, 0x4c, 0x46], label: 'a Linux executable (ELF)' },\n  { magic: [0xfe, 0xed, 0xfa, 0xce], label: 'a macOS executable (Mach-O)' },\n  { magic: [0xfe, 0xed, 0xfa, 0xcf], label: 'a macOS executable (Mach-O)' },\n  { magic: [0xce, 0xfa, 0xed, 0xfe], label: 'a macOS executable (Mach-O)' },\n  { magic: [0xcf, 0xfa, 0xed, 0xfe], label: 'a macOS executable (Mach-O)' },\n  // 0xCAFEBABE is both a Java class file and a multi-architecture Mach-O\n  // binary. Both are code; the label names the likelier one for a DAM.\n  { magic: [0xca, 0xfe, 0xba, 0xbe], label: 'a compiled program' },\n  { magic: ascii('!<arch>'), label: 'an installer package' },\n  { magic: [0xed, 0xab, 0xee, 0xdb], label: 'an installer package (RPM)' },\n  // Windows shortcut — a .lnk is a launcher, and a classic phishing payload.\n  { magic: [0x4c, 0x00, 0x00, 0x00, 0x01, 0x14, 0x02, 0x00], label: 'a Windows shortcut' },\n]\n\n/** ZIP, in its three legal opening forms. Every OOXML document is one. */\nconst ZIP_SIGNATURES: readonly Signature[] = [\n  { magic: [0x50, 0x4b, 0x03, 0x04], label: 'ZIP' },\n  { magic: [0x50, 0x4b, 0x05, 0x06], label: 'ZIP' },\n  { magic: [0x50, 0x4b, 0x07, 0x08], label: 'ZIP' },\n]\n\n/** Microsoft's pre-2007 container: legacy `.doc`, `.xls`, `.ppt` and `.msi`. */\nconst OLE_SIGNATURE: Signature = {\n  magic: [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1],\n  label: 'a legacy Office document',\n}\n\n/** ISO base media (`....ftyp`) — mp4, QuickTime, and the modern image codecs. */\nconst ISO_BMFF: Signature = { magic: ascii('ftyp'), offset: 4, label: 'ISO media' }\n\n/**\n * Accepted content type → the signatures its bytes may legally start with.\n *\n * A type ABSENT from this table is not checked for a match, and that is a\n * deliberate, load-bearing property rather than a gap to be filled with\n * guesses. `text/plain`, `text/csv`, `text/markdown`, `application/json` and\n * `image/svg+xml` are text: they have no magic number, any leading bytes are\n * legal, and inventing a heuristic for them would refuse real files. They are\n * still covered by the executable check above, which is the check that\n * matters for them — an `.exe` renamed `notes.txt` is refused; a CSV that is\n * merely unusual is not.\n */\nconst TYPE_SIGNATURES: Readonly<Record<string, readonly Signature[]>> = {\n  'application/pdf': [{ magic: ascii('%PDF-'), label: 'PDF' }],\n  'application/zip': ZIP_SIGNATURES,\n  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': ZIP_SIGNATURES,\n  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': ZIP_SIGNATURES,\n  'application/vnd.openxmlformats-officedocument.presentationml.presentation': ZIP_SIGNATURES,\n  // Word writes RTF under a `.doc` name often enough that refusing it would\n  // be a real false positive, so both containers are legal for this type.\n  'application/msword': [OLE_SIGNATURE, { magic: ascii('{\\\\rtf'), label: 'RTF' }],\n  'application/vnd.ms-excel': [OLE_SIGNATURE],\n  'application/vnd.ms-powerpoint': [OLE_SIGNATURE],\n  'application/rtf': [{ magic: ascii('{\\\\rtf'), label: 'RTF' }],\n\n  'image/png': [{ magic: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], label: 'PNG' }],\n  'image/jpeg': [{ magic: [0xff, 0xd8, 0xff], label: 'JPEG' }],\n  'image/gif': [\n    { magic: ascii('GIF87a'), label: 'GIF' },\n    { magic: ascii('GIF89a'), label: 'GIF' },\n  ],\n  'image/webp': [{ magic: ascii('RIFF'), label: 'WebP' }],\n  'image/bmp': [{ magic: ascii('BM'), label: 'BMP' }],\n  'image/tiff': [\n    { magic: [0x49, 0x49, 0x2a, 0x00], label: 'TIFF' },\n    { magic: [0x4d, 0x4d, 0x00, 0x2a], label: 'TIFF' },\n  ],\n  'image/x-icon': [{ magic: [0x00, 0x00, 0x01, 0x00], label: 'icon' }],\n  'image/vnd.microsoft.icon': [{ magic: [0x00, 0x00, 0x01, 0x00], label: 'icon' }],\n  'image/avif': [ISO_BMFF],\n  'image/heic': [ISO_BMFF],\n  'image/heif': [ISO_BMFF],\n\n  'video/mp4': [ISO_BMFF],\n  'video/quicktime': [ISO_BMFF],\n  'video/webm': [{ magic: [0x1a, 0x45, 0xdf, 0xa3], label: 'Matroska/WebM' }],\n\n  // A web font (AGL-3656): the theme's font installer stores WOFF2 only.\n  'font/woff2': [{ magic: ascii('wOF2'), label: 'WOFF2' }],\n}\n\n/** The OOXML document types whose archive is scanned for a macro project. */\nconst OOXML_DOCUMENT_TYPES = new Set([\n  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',\n  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',\n  'application/vnd.openxmlformats-officedocument.presentationml.presentation',\n])\n\n/** The pre-2007 Office types whose OLE directory is scanned for the same. */\nconst LEGACY_OFFICE_TYPES = new Set([\n  'application/msword',\n  'application/vnd.ms-excel',\n  'application/vnd.ms-powerpoint',\n])\n\n/**\n * Does a caller holding only a head window need to fetch the tail as well?\n *\n * Only the macro scan reads the end of a file, and only for document\n * archives, so this is what lets the signed-upload route skip a second ranged\n * GET for the 200 MB videos that route exists to carry — which is every\n * object on it bar a handful of documents.\n */\nexport function uploadInspectionNeedsTail(contentType: string): boolean {\n  return (\n    OOXML_DOCUMENT_TYPES.has(contentType) || LEGACY_OFFICE_TYPES.has(contentType)\n  )\n}\n\nconst indexOfBytes = (haystack: Uint8Array, needle: Uint8Array): number => {\n  if (!needle.length || haystack.length < needle.length) return -1\n  const last = haystack.length - needle.length\n  outer: for (let i = 0; i <= last; i++) {\n    for (let j = 0; j < needle.length; j++) {\n      if (haystack[i + j] !== needle[j]) continue outer\n    }\n    return i\n  }\n  return -1\n}\n\nconst contains = (haystack: Uint8Array, needle: Uint8Array): boolean =>\n  indexOfBytes(haystack, needle) >= 0\n\nconst EICAR_BYTES = new Uint8Array(ascii(EICAR_TEST_SIGNATURE))\n\n/** `vbaProject.bin` as an OOXML archive entry name. */\nconst VBA_ENTRY = new Uint8Array(ascii('vbaProject.bin'))\n\n/**\n * `_VBA_PROJECT` as it appears in an OLE directory, which stores stream names\n * as UTF-16LE. Matching the encoded form rather than the ASCII one is what\n * keeps this from firing on a document that merely contains the words.\n */\nconst OLE_VBA_STREAM = new Uint8Array(\n  ascii('_VBA_PROJECT').flatMap((code) => [code, 0x00]),\n)\n\nconst describeFile = (fileName?: string | null): string => {\n  const name = String(fileName ?? '').trim()\n  return name ? `\"${name}\"` : 'This file'\n}\n\n/**\n * Inspect an upload's bytes against the type it claims to be.\n *\n * Returns `null` when nothing structural is wrong — which, to be explicit, is\n * NOT a statement that the file is safe. See the module header.\n */\nexport function inspectUploadBytes(\n  input: InspectUploadInput,\n): UploadInspectionRefusal | null {\n  const { bytes, contentType, fileName } = input\n  const head = bytes ?? new Uint8Array(0)\n  // A caller that passed the whole file gets the whole file searched for the\n  // trailing structures too; only a ranged caller supplies a separate tail.\n  const tail = input.tail ?? head\n  const subject = describeFile(fileName)\n\n  if (!head.length) {\n    return {\n      code: 'empty_file',\n      detected: 'an empty file',\n      message: `${subject} is empty, so there is nothing to store.`,\n    }\n  }\n\n  // 1. The signature list of one. Checked first so that a probe gets the\n  //    answer it is actually asking for, whatever else is also wrong.\n  if (contains(head, EICAR_BYTES) || contains(tail, EICAR_BYTES)) {\n    return {\n      code: 'signature_match',\n      detected: 'the EICAR antivirus test file',\n      message:\n        `${subject} matches the EICAR test signature and was refused by the ` +\n        `upload structure check.`,\n    }\n  }\n\n  // 2. Executable containers, refused under every declared type.\n  for (const signature of EXECUTABLE_SIGNATURES) {\n    if (at(head, signature)) {\n      return {\n        code: 'executable_bytes',\n        detected: signature.label,\n        message:\n          `${subject} contains ${signature.label}, which cannot be uploaded ` +\n          `whatever it is named or labeled.`,\n      }\n    }\n  }\n\n  // 3. The declared type against what the bytes actually are.\n  const expected = TYPE_SIGNATURES[contentType]\n  if (expected && !expected.some((signature) => at(head, signature))) {\n    return {\n      code: 'type_mismatch',\n      detected: `something other than ${expected[0].label}`,\n      message:\n        `${subject} is labeled ${contentType} but its contents are not ` +\n        `${expected[0].label}. Re-save it in the format it claims to be, or ` +\n        `upload it under its real type.`,\n    }\n  }\n\n  // 4. A macro project inside a document whose type is not supposed to have\n  //    one. This is the check the content-type allowlist could never make.\n  if (OOXML_DOCUMENT_TYPES.has(contentType)) {\n    if (contains(head, VBA_ENTRY) || contains(tail, VBA_ENTRY)) {\n      return {\n        code: 'macro_payload',\n        detected: 'an embedded macro project',\n        message:\n          `${subject} contains an embedded macro project. Macro-enabled ` +\n          `documents are not accepted — save it without macros and upload ` +\n          `it again.`,\n      }\n    }\n  } else if (LEGACY_OFFICE_TYPES.has(contentType)) {\n    if (contains(head, OLE_VBA_STREAM) || contains(tail, OLE_VBA_STREAM)) {\n      return {\n        code: 'macro_payload',\n        detected: 'an embedded macro project',\n        message:\n          `${subject} contains an embedded macro project. Macro-enabled ` +\n          `documents are not accepted — save it without macros and upload ` +\n          `it again.`,\n      }\n    }\n  }\n\n  return null\n}\n\nexport default inspectUploadBytes\n"],"names":["EICAR_TEST_SIGNATURE","UPLOAD_INSPECTION_HEAD_BYTES","UPLOAD_INSPECTION_TAIL_BYTES","at","bytes","signature","offset","length","magic","i","ascii","text","Array","from","character","charCodeAt","EXECUTABLE_SIGNATURES","label","ZIP_SIGNATURES","OLE_SIGNATURE","ISO_BMFF","TYPE_SIGNATURES","OOXML_DOCUMENT_TYPES","Set","LEGACY_OFFICE_TYPES","uploadInspectionNeedsTail","contentType","has","indexOfBytes","haystack","needle","last","outer","j","contains","EICAR_BYTES","Uint8Array","VBA_ENTRY","OLE_VBA_STREAM","flatMap","code","describeFile","fileName","name","String","trim","inspectUploadBytes","input","head","tail","subject","detected","message","expected","some"],"mappings":"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"}

package/src/lib/app-utils/webhook-delivery.js

@@ -109,7 +109,10 @@
     'payment_method.detached',
     // Fraud signals to staff (AGL-3356).
     'radar.early_fraud_warning.created',
-    'review.opened'
+    'review.opened',
+    // Register card readers (AGL-3607).
+    'terminal.reader.action_succeeded',
+    'terminal.reader.action_failed'
 ];
 /**
  * How the CONNECT destination identifies itself (AGL-1948), mirroring

package/src/lib/app-utils/webhook-delivery.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/webhook-delivery.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 * DID THE WEBHOOK ACTUALLY DO ANYTHING? (AGL-1954)\n *\n * Every signal we have about the billing webhook is a signal about the\n * REQUEST. Stripe records `delivery_success` off the status code. The\n * idempotency claim in `stripeEvents` records that the signature verified and\n * the handler was entered. `/api/health/billing` (AGL-1924) counts what\n * Stripe attempted and failed to deliver. All three read green for the one\n * failure this module exists to catch: **a handler that answers 200 and moves\n * nothing.**\n *\n * That is not hypothetical here. AGL-1798 is exactly it — `charge.refunded`\n * was never subscribed on the live destination, so AGL-1546's entitlement\n * revocation had no trigger, and every other indicator looked fine for as\n * long as it lasted. AGL-1551 is the same class from the other side: a week\n * of 100% rejected deliveries behind a green \"Active\" badge.\n *\n * ## The honest signal is an EFFECT, not a return code\n *\n * A check that asserts \"the handler ran\" is nearly as blind as the 200 —\n * the handler DID run in the AGL-1798 shape, it just had no work registered\n * for the event. So the route reports what it COMMITTED: an org's plan\n * mirrored, a `platformRevenue` row written, a refund stamped, an orphan\n * recorded, an audit row appended, a plugin claiming the event. Those are the\n * things whose absence is the bug.\n *\n * ## Three outcomes, and conflating the middle two is its own failure\n *\n * A binary \"did it write something\" would fire on every legitimately\n * irrelevant delivery — a tenant shopper's subscription carries no\n * `metadata.orgId` and correctly moves nothing on OUR side; a marketplace\n * refund resolves to no workspace customer and is correctly left to the\n * plugins; a `won` dispute nobody claimed reversed no money and correctly\n * wakes nobody. Alerting on those is alert fatigue, which ends with the alarm\n * muted and the real one lost inside it.\n *\n * So a branch that decides an event is not its business must SAY SO, by\n * name, through {@link WebhookEffectLedger.skip}. That is what separates:\n *\n * | outcome   | meaning                                            | alarm |\n * |-----------|----------------------------------------------------|-------|\n * | `acted`   | something durable committed, or a plugin claimed it | no    |\n * | `ignored` | a branch named a reason, or we never asked for this event type | no |\n * | `inert`   | an event we deliberately subscribe to produced NEITHER | YES  |\n *\n * `inert` is the whole point. Falling off the end of the dispatch with no\n * effect and no stated reason is precisely what a deleted write, an\n * unregistered plugin handler, or a renamed event type looks like from\n * inside the process — and it is the only one of the three that nothing else\n * in this system can see.\n *\n * ## Why the \"did we ask for it\" test is the required-events list\n *\n * Stripe delivers what the destination is subscribed to, and the destination\n * is created by `tools/scripts/setup-stripe.mjs` from `WEBHOOK_EVENTS`. An\n * event type outside that list reaching us is either a hand-added\n * subscription or a Connect delivery arriving at the platform destination —\n * unremarkable, and never our silent-drop bug, because we never claimed to\n * handle it. An event type INSIDE it is one we went out of our way to ask\n * Stripe for, so producing nothing from it is a contradiction by\n * construction.\n *\n * `REQUIRED_WEBHOOK_EVENTS` below is a copy of that list, and a copy is a\n * drift hazard — so `webhook-delivery.spec.ts` reads the `.mjs` and fails on\n * any divergence, in either direction. The alternative (moving the list\n * across the nx boundary out of `tools/`) is a wider change than this\n * warrants and is tracked on AGL-1948.\n *\n * Pure: no clock, no I/O, no Firestore. The route records, this decides, the\n * spec exercises every branch without a network.\n */\n\n/** What a single delivery turned out to be. */\nexport type WebhookDeliveryOutcome = 'acted' | 'ignored' | 'inert'\n\n/**\n * The event types the platform destination is subscribed to, mirroring\n * `WEBHOOK_EVENTS` in `tools/scripts/lib/stripe-webhook-health.mjs`.\n *\n * The list is the definition of \"we asked for this\", which is what makes a\n * no-op delivery of one of them a defect rather than a non-event. Kept in\n * the same order as the source so a diff between the two reads cleanly.\n */\nexport const REQUIRED_WEBHOOK_EVENTS: readonly string[] = [\n  'customer.subscription.created',\n  'customer.subscription.updated',\n  'customer.subscription.deleted',\n  'checkout.session.completed',\n  'invoice.finalized',\n  'invoice.paid',\n  'invoice.payment_failed',\n  'charge.refunded',\n  'charge.dispute.created',\n  'charge.dispute.closed',\n  // AI overage charged as it accrues (AGL-3011), in the source list's order.\n  'invoice.voided',\n  'invoice.marked_uncollectible',\n  'customer.updated',\n  'payment_method.attached',\n  'payment_method.detached',\n  // Fraud signals to staff (AGL-3356).\n  'radar.early_fraud_warning.created',\n  'review.opened',\n]\n\n/**\n * How the CONNECT destination identifies itself (AGL-1948), mirroring\n * `CONNECT_SCOPE_METADATA_KEY` / `CONNECT_SCOPE_METADATA_VALUE` in\n * `tools/scripts/lib/stripe-webhook-health.mjs`.\n *\n * Connected-account events are delivered only to a destination created with\n * `connect: true`, and Stripe's API does not report that flag back on the\n * endpoint object — so the destination is identified by metadata we set at\n * creation instead. Same copy-and-guard arrangement as the list above.\n */\nexport const CONNECT_SCOPE_METADATA_KEY = 'aglyn_scope'\nexport const CONNECT_SCOPE_METADATA_VALUE = 'connect'\n\n/**\n * What the Connect destination must carry, mirroring\n * `CONNECT_WEBHOOK_EVENTS` in the same script lib.\n *\n * `account.updated` is the whole point of it: AGL-1997's `syncConnectAccountStatus`\n * is what stops a merchant whose Stripe account was later restricted from\n * going on selling against a stale `stripeChargesEnabled`, with the SHOPPER\n * meeting the failure at payment time. Without this event the handler cannot\n * run — which is exactly the state AGL-2122 found and fixed.\n */\nexport const REQUIRED_CONNECT_WEBHOOK_EVENTS: readonly string[] = [\n  'account.updated',\n  'payout.failed',\n  'payout.paid',\n]\n\n/**\n * Does this Stripe endpoint object carry our Connect scope marker?\n *\n * Coverage for it reuses `unsubscribedRequiredEvents` with\n * `REQUIRED_CONNECT_WEBHOOK_EVENTS` as the `required` argument — the wildcard\n * and null handling are identical questions, and a second copy of that logic\n * is a second place for it to drift.\n */\nexport function isConnectWebhookEndpoint(endpoint: unknown): boolean {\n  const metadata = (endpoint as { metadata?: Record<string, unknown> })?.metadata\n  return metadata?.[CONNECT_SCOPE_METADATA_KEY] === CONNECT_SCOPE_METADATA_VALUE\n}\n\n/**\n * A per-delivery record of what actually committed.\n *\n * Deliberately append-only and stringly-typed: the reasons are read by a\n * human in a log line and by a spec, never switched on. Keeping it dumb is\n * what stops it growing into a second dispatch table that can disagree with\n * the real one.\n */\nexport interface WebhookEffectLedger {\n  /** Durable things this delivery committed, in the order they landed. */\n  readonly effects: readonly string[]\n  /** Reasons a branch decided the event was none of its business. */\n  readonly skips: readonly string[]\n  /**\n   * Record a committed effect. Call this AFTER the write it names, so a\n   * throw between the two cannot claim an effect that never landed.\n   */\n  effect(name: string): void\n  /**\n   * Record a deliberate no-op and why. This is the difference between \"not\n   * ours\" and \"broken\", and it is the half that prevents alert fatigue.\n   */\n  skip(reason: string): void\n}\n\nexport function createWebhookEffectLedger(): WebhookEffectLedger {\n  const effects: string[] = []\n  const skips: string[] = []\n  return {\n    effects,\n    skips,\n    effect(name: string) {\n      effects.push(name)\n    },\n    skip(reason: string) {\n      skips.push(reason)\n    },\n  }\n}\n\n/** Firestore methods that MUTATE. Everything else is a read or a builder. */\nconst WRITE_METHODS = new Set(['set', 'update', 'create', 'delete', 'add'])\n\n/**\n * Wrap a Firestore handle so every write it commits lands in the ledger.\n *\n * ## Why this exists rather than a `ledger.effect()` beside each write\n *\n * A hand-placed note next to a write is a check that CANNOT FAIL in the one\n * way that matters. Delete the write and leave the note, and the ledger\n * cheerfully reports an effect that never happened — which is the same\n * \"asserts its own literals\" defect the health probes are written to avoid.\n * The note has to be caused by the write, not merely adjacent to it.\n *\n * So the effect is recorded from INSIDE the call, after it resolves. A write\n * that throws records nothing (it did not commit); a write that is deleted\n * from the source records nothing (it is not called). There is no edit to\n * the handler that removes the work and keeps the signal.\n *\n * ## What it deliberately does not see\n *\n * Writes issued through a DIFFERENT Firestore handle — the shared\n * `tenant-data-admin` writers (`writeOrgBilling`, `notifyOrgAdmins`,\n * `notifyStaff`), which each open their own — and anything a plugin does\n * inside its own handler. Those are noted explicitly by the caller where\n * they are the only consequence of a branch, and the comments at those call\n * sites say so. The boundary is stated rather than hidden: this covers the\n * route's own writes, which is where the route's own bugs live.\n *\n * A Proxy rather than a hand-written facade because the wrapped object is\n * passed on to `updateExisting` and friends, which call methods this module\n * has never heard of. A facade would have to enumerate them and would\n * silently drop the ones it forgot.\n */\nexport function observeWrites<T extends object>(\n  handle: T,\n  ledger: WebhookEffectLedger,\n  label = 'firestore',\n): T {\n  return new Proxy(handle, {\n    get(target, property, receiver) {\n      const value = Reflect.get(target, property, receiver)\n      if (typeof value !== 'function' || typeof property !== 'string') {\n        return value\n      }\n      const method = property\n      return (...args: unknown[]) => {\n        const result = (value as (...a: unknown[]) => unknown).apply(\n          target,\n          args,\n        )\n        // `collection('orgs')` names the thing being written, so the ledger\n        // reads `orgs.update` rather than `firestore.update`. Everything\n        // else inherits the label it was reached through.\n        const nextLabel =\n          method === 'collection' && typeof args[0] === 'string'\n            ? (args[0] as string)\n            : label\n        if (WRITE_METHODS.has(method)) {\n          // Recorded on RESOLUTION. A rejected write committed nothing and\n          // must not read as an effect.\n          return Promise.resolve(result).then((settled) => {\n            ledger.effect(`${nextLabel}.${method}`)\n            return settled\n          })\n        }\n        // Builders (`collection`, `doc`, `where`, `limit`) return objects\n        // that can themselves be written through, so the wrapper follows\n        // them. Thenables are returned bare: wrapping a promise would make\n        // `then` look like a builder and recurse forever.\n        if (\n          result &&\n          typeof result === 'object' &&\n          typeof (result as { then?: unknown }).then !== 'function'\n        ) {\n          return observeWrites(result as object, ledger, nextLabel)\n        }\n        return result\n      }\n    },\n  })\n}\n\nexport interface WebhookDeliveryVerdict {\n  outcome: WebhookDeliveryOutcome\n  /** One short phrase naming WHY, for the log line and the spec. */\n  reason: string\n}\n\n/**\n * Classify one delivery.\n *\n * Order is the argument:\n *\n * 1. **Any effect, or any plugin claim, wins.** A delivery that both wrote\n *    something and skipped something else did work; a partially-skipped\n *    handler is not an idle one.\n * 2. **A named skip is an answer.** Reaching a branch that consciously\n *    decided \"not ours\" is a handled event, not a dropped one.\n * 3. **An event type we never subscribed to is not our problem.** Nothing\n *    promised to handle it.\n * 4. **Everything else is inert** — and by elimination that means: we asked\n *    Stripe for this event, we received it, no handler claimed it, no branch\n *    wrote anything, and no branch could say why.\n */\nexport function classifyWebhookDelivery(input: {\n  type: string\n  effects: readonly string[]\n  skips: readonly string[]\n  claimed: boolean\n  /** Overridable so the spec can prove the rule rather than the list. */\n  required?: readonly string[]\n}): WebhookDeliveryVerdict {\n  const { type, effects, skips, claimed } = input\n  const required = input.required ?? REQUIRED_WEBHOOK_EVENTS\n  if (effects.length > 0) return { outcome: 'acted', reason: effects[0] }\n  if (claimed) return { outcome: 'acted', reason: 'plugin-claimed' }\n  if (skips.length > 0) return { outcome: 'ignored', reason: skips[0] }\n  if (!required.includes(type)) {\n    return { outcome: 'ignored', reason: 'not-subscribed' }\n  }\n  return { outcome: 'inert', reason: 'no-effect' }\n}\n\n/**\n * How long after Stripe CREATES an event its first delivery attempt may\n * plausibly take to reach us, in seconds. Mirrors `RETRY_LAG_SECONDS` in\n * `tools/scripts/lib/stripe-webhook-health.mjs`, under the same\n * read-the-`.mjs`-as-text drift guard as the lists above.\n *\n * Calibrated against the live account on 2026-08-18: the five deliveries that\n * succeeded first time landed in 1.0–3.7s; the one that did not —\n * `evt_1U49XtDYHP4psn7hA9VHPnZz`, whose three 400s ARE the three failures the\n * Stripe Dashboard was showing — landed 16,665s (4h 37m) late. Two minutes\n * sits three orders of magnitude clear of the healthy band and still inside\n * Stripe's first automatic retry interval, so it separates the two without\n * straddling either.\n */\nexport const RETRY_LAG_SECONDS = 120\n\n/**\n * What a delivery's lag says about the attempts BEFORE it.\n *\n * `unknown` is a first-class outcome, not a synonym for either answer. See\n * {@link classifyDeliveryLag} for why that matters more here than usual.\n */\nexport type WebhookDeliveryAttempt = 'first-attempt' | 'retried' | 'unknown'\n\n/** Why {@link classifyDeliveryLag} answered as it did. */\nexport type WebhookDeliveryLagReason =\n  | 'measured'\n  | 'created-absent'\n  | 'created-not-a-number'\n  | 'created-non-positive'\n  | 'received-unusable'\n  | 'clock-skew'\n\nexport interface WebhookDeliveryLagVerdict {\n  attempt: WebhookDeliveryAttempt\n  /** Seconds between `event.created` and our claim. Null unless `measured`. */\n  lagSeconds: number | null\n  reason: WebhookDeliveryLagReason\n}\n\n/**\n * DID THIS DELIVERY ONLY LAND ON A RETRY? (AGL-2039, the last arm of AGL-1948)\n *\n * ## The reconciliation this exists to close\n *\n * `/api/health/billing` scores EVENTS and `GET /v1/events?delivery_success=false`\n * is a TERMINAL-state filter: it selects events that are still pending or\n * failed EVERY attempt. An event that 400s three times and then succeeds on\n * the fourth reads back `delivery_success: true` and is, to that filter,\n * indistinguishable from one that succeeded immediately. The Stripe Dashboard\n * scores delivery ATTEMPTS, so the same hour reads 0% here and 30% there —\n * and both numbers are right. The three real failures were visible only in\n * the second reading, and each was a mirror that did not run when it should\n * have.\n *\n * The recoverable half of the attempt history is in our own data. The route\n * claims `stripeEvents/{id}` AFTER signature verification and DELETES the\n * claim when a handler throws, so the stamp always records the attempt that\n * actually got through. The distance from `event.created` to that stamp is\n * the delivery lag, and a lag of minutes means an earlier attempt failed.\n *\n * ## Why this is decided at WRITE time, not at read time\n *\n * The obvious implementation reads `receivedAt` off every claim document in\n * the window and subtracts. That turns a `.count()` aggregation — one\n * integer, zero documents read — into a document scan on a PUBLIC,\n * unauthenticated health endpoint polled every five minutes. Deciding here,\n * once, at the moment of the claim, lets the probe stay an aggregation over a\n * marker field, exactly like AGL-1954's `inertAtMs`.\n *\n * ## Absent, zero and unknown are THREE different things\n *\n * `strictNullChecks` is off repo-wide, so an absent `created` folds to falsy\n * and a naive `Number(event?.created ?? 0)` yields 0 — which subtracts to a\n * lag of ~1.7 BILLION seconds and reports every such delivery as a retry,\n * forever, on a perfectly healthy webhook. A monitoring signal that reds on\n * its own missing input is worse than no signal, because it is the thing that\n * gets muted. So each of those inputs is rejected by name:\n *\n * | input                       | attempt    | reason                  |\n * |-----------------------------|------------|-------------------------|\n * | field absent / null         | `unknown`  | `created-absent`        |\n * | a string, NaN, Infinity     | `unknown`  | `created-not-a-number`  |\n * | `0` or negative             | `unknown`  | `created-non-positive`  |\n * | our own stamp unusable      | `unknown`  | `received-unusable`     |\n * | created in the FUTURE by more than the bar | `unknown` | `clock-skew` |\n *\n * A lag between `-threshold` and `+threshold` is `first-attempt`: sub-second\n * clock skew between Stripe's clock and ours is ordinary and is not evidence\n * of anything.\n *\n * Pure: no clock, no I/O. The caller supplies both timestamps.\n */\nexport function classifyDeliveryLag(input: {\n  /** `event.created`, in unix SECONDS, exactly as Stripe sent it. */\n  eventCreatedSeconds: unknown\n  /** When we claimed the event, in unix MILLISECONDS. */\n  receivedAtMs: unknown\n  /** Overridable so the spec can prove the rule rather than the constant. */\n  thresholdSeconds?: number\n}): WebhookDeliveryLagVerdict {\n  const threshold = input.thresholdSeconds ?? RETRY_LAG_SECONDS\n  const created = input.eventCreatedSeconds\n  if (created === undefined || created === null) {\n    return { attempt: 'unknown', lagSeconds: null, reason: 'created-absent' }\n  }\n  if (typeof created !== 'number' || !Number.isFinite(created)) {\n    return {\n      attempt: 'unknown',\n      lagSeconds: null,\n      reason: 'created-not-a-number',\n    }\n  }\n  // Zero is the value an absent field folds to under the repo's null rules,\n  // and no Stripe event was created at the epoch. Rejected by name so it can\n  // never be mistaken for a measurement.\n  if (created <= 0) {\n    return {\n      attempt: 'unknown',\n      lagSeconds: null,\n      reason: 'created-non-positive',\n    }\n  }\n  const received = input.receivedAtMs\n  if (typeof received !== 'number' || !Number.isFinite(received) || received <= 0) {\n    return { attempt: 'unknown', lagSeconds: null, reason: 'received-unusable' }\n  }\n  const lagSeconds = received / 1000 - created\n  // An event stamped in OUR future by more than the threshold is a clock\n  // disagreement, not a fast delivery, and reporting it as a healthy first\n  // attempt would be an answer we cannot support.\n  if (lagSeconds < -threshold) {\n    return { attempt: 'unknown', lagSeconds: null, reason: 'clock-skew' }\n  }\n  return {\n    attempt: lagSeconds > threshold ? 'retried' : 'first-attempt',\n    lagSeconds,\n    reason: 'measured',\n  }\n}\n\n/**\n * Which required events is a destination NOT subscribed to? (AGL-1948)\n *\n * The same blind spot from the configuration side, and the cheaper half of\n * it: a subscription removed by hand in the Stripe dashboard produces no\n * failed delivery, no rejected request and no inert one either — Stripe\n * simply stops sending, and every count on the health probe reads a\n * perfectly healthy zero. `charge.refunded` was missing from the live\n * endpoint for exactly this reason (AGL-1798) and the only thing that ever\n * noticed was a script nobody ran.\n *\n * `['*']` is Stripe's wildcard subscription and covers everything.\n *\n * Returns the names, sorted, so the probe body is stable and a diff between\n * two readings is meaningful.\n */\nexport function unsubscribedRequiredEvents(\n  enabledEvents: readonly string[] | null | undefined,\n  required: readonly string[] = REQUIRED_WEBHOOK_EVENTS,\n): string[] {\n  if (!enabledEvents) return []\n  if (enabledEvents.includes('*')) return []\n  const enabled = new Set(enabledEvents)\n  return required.filter((event) => !enabled.has(event)).sort()\n}\n"],"names":["REQUIRED_WEBHOOK_EVENTS","CONNECT_SCOPE_METADATA_KEY","CONNECT_SCOPE_METADATA_VALUE","REQUIRED_CONNECT_WEBHOOK_EVENTS","isConnectWebhookEndpoint","endpoint","metadata","createWebhookEffectLedger","effects","skips","effect","name","push","skip","reason","WRITE_METHODS","Set","observeWrites","handle","ledger","label","Proxy","get","target","property","receiver","value","Reflect","method","args","result","apply","nextLabel","has","Promise","resolve","then","settled","classifyWebhookDelivery","input","type","claimed","required","length","outcome","includes","RETRY_LAG_SECONDS","classifyDeliveryLag","threshold","thresholdSeconds","created","eventCreatedSeconds","undefined","attempt","lagSeconds","Number","isFinite","received","receivedAtMs","unsubscribedRequiredEvents","enabledEvents","enabled","filter","event","sort"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/webhook-delivery.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 * DID THE WEBHOOK ACTUALLY DO ANYTHING? (AGL-1954)\n *\n * Every signal we have about the billing webhook is a signal about the\n * REQUEST. Stripe records `delivery_success` off the status code. The\n * idempotency claim in `stripeEvents` records that the signature verified and\n * the handler was entered. `/api/health/billing` (AGL-1924) counts what\n * Stripe attempted and failed to deliver. All three read green for the one\n * failure this module exists to catch: **a handler that answers 200 and moves\n * nothing.**\n *\n * That is not hypothetical here. AGL-1798 is exactly it — `charge.refunded`\n * was never subscribed on the live destination, so AGL-1546's entitlement\n * revocation had no trigger, and every other indicator looked fine for as\n * long as it lasted. AGL-1551 is the same class from the other side: a week\n * of 100% rejected deliveries behind a green \"Active\" badge.\n *\n * ## The honest signal is an EFFECT, not a return code\n *\n * A check that asserts \"the handler ran\" is nearly as blind as the 200 —\n * the handler DID run in the AGL-1798 shape, it just had no work registered\n * for the event. So the route reports what it COMMITTED: an org's plan\n * mirrored, a `platformRevenue` row written, a refund stamped, an orphan\n * recorded, an audit row appended, a plugin claiming the event. Those are the\n * things whose absence is the bug.\n *\n * ## Three outcomes, and conflating the middle two is its own failure\n *\n * A binary \"did it write something\" would fire on every legitimately\n * irrelevant delivery — a tenant shopper's subscription carries no\n * `metadata.orgId` and correctly moves nothing on OUR side; a marketplace\n * refund resolves to no workspace customer and is correctly left to the\n * plugins; a `won` dispute nobody claimed reversed no money and correctly\n * wakes nobody. Alerting on those is alert fatigue, which ends with the alarm\n * muted and the real one lost inside it.\n *\n * So a branch that decides an event is not its business must SAY SO, by\n * name, through {@link WebhookEffectLedger.skip}. That is what separates:\n *\n * | outcome   | meaning                                            | alarm |\n * |-----------|----------------------------------------------------|-------|\n * | `acted`   | something durable committed, or a plugin claimed it | no    |\n * | `ignored` | a branch named a reason, or we never asked for this event type | no |\n * | `inert`   | an event we deliberately subscribe to produced NEITHER | YES  |\n *\n * `inert` is the whole point. Falling off the end of the dispatch with no\n * effect and no stated reason is precisely what a deleted write, an\n * unregistered plugin handler, or a renamed event type looks like from\n * inside the process — and it is the only one of the three that nothing else\n * in this system can see.\n *\n * ## Why the \"did we ask for it\" test is the required-events list\n *\n * Stripe delivers what the destination is subscribed to, and the destination\n * is created by `tools/scripts/setup-stripe.mjs` from `WEBHOOK_EVENTS`. An\n * event type outside that list reaching us is either a hand-added\n * subscription or a Connect delivery arriving at the platform destination —\n * unremarkable, and never our silent-drop bug, because we never claimed to\n * handle it. An event type INSIDE it is one we went out of our way to ask\n * Stripe for, so producing nothing from it is a contradiction by\n * construction.\n *\n * `REQUIRED_WEBHOOK_EVENTS` below is a copy of that list, and a copy is a\n * drift hazard — so `webhook-delivery.spec.ts` reads the `.mjs` and fails on\n * any divergence, in either direction. The alternative (moving the list\n * across the nx boundary out of `tools/`) is a wider change than this\n * warrants and is tracked on AGL-1948.\n *\n * Pure: no clock, no I/O, no Firestore. The route records, this decides, the\n * spec exercises every branch without a network.\n */\n\n/** What a single delivery turned out to be. */\nexport type WebhookDeliveryOutcome = 'acted' | 'ignored' | 'inert'\n\n/**\n * The event types the platform destination is subscribed to, mirroring\n * `WEBHOOK_EVENTS` in `tools/scripts/lib/stripe-webhook-health.mjs`.\n *\n * The list is the definition of \"we asked for this\", which is what makes a\n * no-op delivery of one of them a defect rather than a non-event. Kept in\n * the same order as the source so a diff between the two reads cleanly.\n */\nexport const REQUIRED_WEBHOOK_EVENTS: readonly string[] = [\n  'customer.subscription.created',\n  'customer.subscription.updated',\n  'customer.subscription.deleted',\n  'checkout.session.completed',\n  'invoice.finalized',\n  'invoice.paid',\n  'invoice.payment_failed',\n  'charge.refunded',\n  'charge.dispute.created',\n  'charge.dispute.closed',\n  // AI overage charged as it accrues (AGL-3011), in the source list's order.\n  'invoice.voided',\n  'invoice.marked_uncollectible',\n  'customer.updated',\n  'payment_method.attached',\n  'payment_method.detached',\n  // Fraud signals to staff (AGL-3356).\n  'radar.early_fraud_warning.created',\n  'review.opened',\n  // Register card readers (AGL-3607).\n  'terminal.reader.action_succeeded',\n  'terminal.reader.action_failed',\n]\n\n/**\n * How the CONNECT destination identifies itself (AGL-1948), mirroring\n * `CONNECT_SCOPE_METADATA_KEY` / `CONNECT_SCOPE_METADATA_VALUE` in\n * `tools/scripts/lib/stripe-webhook-health.mjs`.\n *\n * Connected-account events are delivered only to a destination created with\n * `connect: true`, and Stripe's API does not report that flag back on the\n * endpoint object — so the destination is identified by metadata we set at\n * creation instead. Same copy-and-guard arrangement as the list above.\n */\nexport const CONNECT_SCOPE_METADATA_KEY = 'aglyn_scope'\nexport const CONNECT_SCOPE_METADATA_VALUE = 'connect'\n\n/**\n * What the Connect destination must carry, mirroring\n * `CONNECT_WEBHOOK_EVENTS` in the same script lib.\n *\n * `account.updated` is the whole point of it: AGL-1997's `syncConnectAccountStatus`\n * is what stops a merchant whose Stripe account was later restricted from\n * going on selling against a stale `stripeChargesEnabled`, with the SHOPPER\n * meeting the failure at payment time. Without this event the handler cannot\n * run — which is exactly the state AGL-2122 found and fixed.\n */\nexport const REQUIRED_CONNECT_WEBHOOK_EVENTS: readonly string[] = [\n  'account.updated',\n  'payout.failed',\n  'payout.paid',\n]\n\n/**\n * Does this Stripe endpoint object carry our Connect scope marker?\n *\n * Coverage for it reuses `unsubscribedRequiredEvents` with\n * `REQUIRED_CONNECT_WEBHOOK_EVENTS` as the `required` argument — the wildcard\n * and null handling are identical questions, and a second copy of that logic\n * is a second place for it to drift.\n */\nexport function isConnectWebhookEndpoint(endpoint: unknown): boolean {\n  const metadata = (endpoint as { metadata?: Record<string, unknown> })?.metadata\n  return metadata?.[CONNECT_SCOPE_METADATA_KEY] === CONNECT_SCOPE_METADATA_VALUE\n}\n\n/**\n * A per-delivery record of what actually committed.\n *\n * Deliberately append-only and stringly-typed: the reasons are read by a\n * human in a log line and by a spec, never switched on. Keeping it dumb is\n * what stops it growing into a second dispatch table that can disagree with\n * the real one.\n */\nexport interface WebhookEffectLedger {\n  /** Durable things this delivery committed, in the order they landed. */\n  readonly effects: readonly string[]\n  /** Reasons a branch decided the event was none of its business. */\n  readonly skips: readonly string[]\n  /**\n   * Record a committed effect. Call this AFTER the write it names, so a\n   * throw between the two cannot claim an effect that never landed.\n   */\n  effect(name: string): void\n  /**\n   * Record a deliberate no-op and why. This is the difference between \"not\n   * ours\" and \"broken\", and it is the half that prevents alert fatigue.\n   */\n  skip(reason: string): void\n}\n\nexport function createWebhookEffectLedger(): WebhookEffectLedger {\n  const effects: string[] = []\n  const skips: string[] = []\n  return {\n    effects,\n    skips,\n    effect(name: string) {\n      effects.push(name)\n    },\n    skip(reason: string) {\n      skips.push(reason)\n    },\n  }\n}\n\n/** Firestore methods that MUTATE. Everything else is a read or a builder. */\nconst WRITE_METHODS = new Set(['set', 'update', 'create', 'delete', 'add'])\n\n/**\n * Wrap a Firestore handle so every write it commits lands in the ledger.\n *\n * ## Why this exists rather than a `ledger.effect()` beside each write\n *\n * A hand-placed note next to a write is a check that CANNOT FAIL in the one\n * way that matters. Delete the write and leave the note, and the ledger\n * cheerfully reports an effect that never happened — which is the same\n * \"asserts its own literals\" defect the health probes are written to avoid.\n * The note has to be caused by the write, not merely adjacent to it.\n *\n * So the effect is recorded from INSIDE the call, after it resolves. A write\n * that throws records nothing (it did not commit); a write that is deleted\n * from the source records nothing (it is not called). There is no edit to\n * the handler that removes the work and keeps the signal.\n *\n * ## What it deliberately does not see\n *\n * Writes issued through a DIFFERENT Firestore handle — the shared\n * `tenant-data-admin` writers (`writeOrgBilling`, `notifyOrgAdmins`,\n * `notifyStaff`), which each open their own — and anything a plugin does\n * inside its own handler. Those are noted explicitly by the caller where\n * they are the only consequence of a branch, and the comments at those call\n * sites say so. The boundary is stated rather than hidden: this covers the\n * route's own writes, which is where the route's own bugs live.\n *\n * A Proxy rather than a hand-written facade because the wrapped object is\n * passed on to `updateExisting` and friends, which call methods this module\n * has never heard of. A facade would have to enumerate them and would\n * silently drop the ones it forgot.\n */\nexport function observeWrites<T extends object>(\n  handle: T,\n  ledger: WebhookEffectLedger,\n  label = 'firestore',\n): T {\n  return new Proxy(handle, {\n    get(target, property, receiver) {\n      const value = Reflect.get(target, property, receiver)\n      if (typeof value !== 'function' || typeof property !== 'string') {\n        return value\n      }\n      const method = property\n      return (...args: unknown[]) => {\n        const result = (value as (...a: unknown[]) => unknown).apply(\n          target,\n          args,\n        )\n        // `collection('orgs')` names the thing being written, so the ledger\n        // reads `orgs.update` rather than `firestore.update`. Everything\n        // else inherits the label it was reached through.\n        const nextLabel =\n          method === 'collection' && typeof args[0] === 'string'\n            ? (args[0] as string)\n            : label\n        if (WRITE_METHODS.has(method)) {\n          // Recorded on RESOLUTION. A rejected write committed nothing and\n          // must not read as an effect.\n          return Promise.resolve(result).then((settled) => {\n            ledger.effect(`${nextLabel}.${method}`)\n            return settled\n          })\n        }\n        // Builders (`collection`, `doc`, `where`, `limit`) return objects\n        // that can themselves be written through, so the wrapper follows\n        // them. Thenables are returned bare: wrapping a promise would make\n        // `then` look like a builder and recurse forever.\n        if (\n          result &&\n          typeof result === 'object' &&\n          typeof (result as { then?: unknown }).then !== 'function'\n        ) {\n          return observeWrites(result as object, ledger, nextLabel)\n        }\n        return result\n      }\n    },\n  })\n}\n\nexport interface WebhookDeliveryVerdict {\n  outcome: WebhookDeliveryOutcome\n  /** One short phrase naming WHY, for the log line and the spec. */\n  reason: string\n}\n\n/**\n * Classify one delivery.\n *\n * Order is the argument:\n *\n * 1. **Any effect, or any plugin claim, wins.** A delivery that both wrote\n *    something and skipped something else did work; a partially-skipped\n *    handler is not an idle one.\n * 2. **A named skip is an answer.** Reaching a branch that consciously\n *    decided \"not ours\" is a handled event, not a dropped one.\n * 3. **An event type we never subscribed to is not our problem.** Nothing\n *    promised to handle it.\n * 4. **Everything else is inert** — and by elimination that means: we asked\n *    Stripe for this event, we received it, no handler claimed it, no branch\n *    wrote anything, and no branch could say why.\n */\nexport function classifyWebhookDelivery(input: {\n  type: string\n  effects: readonly string[]\n  skips: readonly string[]\n  claimed: boolean\n  /** Overridable so the spec can prove the rule rather than the list. */\n  required?: readonly string[]\n}): WebhookDeliveryVerdict {\n  const { type, effects, skips, claimed } = input\n  const required = input.required ?? REQUIRED_WEBHOOK_EVENTS\n  if (effects.length > 0) return { outcome: 'acted', reason: effects[0] }\n  if (claimed) return { outcome: 'acted', reason: 'plugin-claimed' }\n  if (skips.length > 0) return { outcome: 'ignored', reason: skips[0] }\n  if (!required.includes(type)) {\n    return { outcome: 'ignored', reason: 'not-subscribed' }\n  }\n  return { outcome: 'inert', reason: 'no-effect' }\n}\n\n/**\n * How long after Stripe CREATES an event its first delivery attempt may\n * plausibly take to reach us, in seconds. Mirrors `RETRY_LAG_SECONDS` in\n * `tools/scripts/lib/stripe-webhook-health.mjs`, under the same\n * read-the-`.mjs`-as-text drift guard as the lists above.\n *\n * Calibrated against the live account on 2026-08-18: the five deliveries that\n * succeeded first time landed in 1.0–3.7s; the one that did not —\n * `evt_1U49XtDYHP4psn7hA9VHPnZz`, whose three 400s ARE the three failures the\n * Stripe Dashboard was showing — landed 16,665s (4h 37m) late. Two minutes\n * sits three orders of magnitude clear of the healthy band and still inside\n * Stripe's first automatic retry interval, so it separates the two without\n * straddling either.\n */\nexport const RETRY_LAG_SECONDS = 120\n\n/**\n * What a delivery's lag says about the attempts BEFORE it.\n *\n * `unknown` is a first-class outcome, not a synonym for either answer. See\n * {@link classifyDeliveryLag} for why that matters more here than usual.\n */\nexport type WebhookDeliveryAttempt = 'first-attempt' | 'retried' | 'unknown'\n\n/** Why {@link classifyDeliveryLag} answered as it did. */\nexport type WebhookDeliveryLagReason =\n  | 'measured'\n  | 'created-absent'\n  | 'created-not-a-number'\n  | 'created-non-positive'\n  | 'received-unusable'\n  | 'clock-skew'\n\nexport interface WebhookDeliveryLagVerdict {\n  attempt: WebhookDeliveryAttempt\n  /** Seconds between `event.created` and our claim. Null unless `measured`. */\n  lagSeconds: number | null\n  reason: WebhookDeliveryLagReason\n}\n\n/**\n * DID THIS DELIVERY ONLY LAND ON A RETRY? (AGL-2039, the last arm of AGL-1948)\n *\n * ## The reconciliation this exists to close\n *\n * `/api/health/billing` scores EVENTS and `GET /v1/events?delivery_success=false`\n * is a TERMINAL-state filter: it selects events that are still pending or\n * failed EVERY attempt. An event that 400s three times and then succeeds on\n * the fourth reads back `delivery_success: true` and is, to that filter,\n * indistinguishable from one that succeeded immediately. The Stripe Dashboard\n * scores delivery ATTEMPTS, so the same hour reads 0% here and 30% there —\n * and both numbers are right. The three real failures were visible only in\n * the second reading, and each was a mirror that did not run when it should\n * have.\n *\n * The recoverable half of the attempt history is in our own data. The route\n * claims `stripeEvents/{id}` AFTER signature verification and DELETES the\n * claim when a handler throws, so the stamp always records the attempt that\n * actually got through. The distance from `event.created` to that stamp is\n * the delivery lag, and a lag of minutes means an earlier attempt failed.\n *\n * ## Why this is decided at WRITE time, not at read time\n *\n * The obvious implementation reads `receivedAt` off every claim document in\n * the window and subtracts. That turns a `.count()` aggregation — one\n * integer, zero documents read — into a document scan on a PUBLIC,\n * unauthenticated health endpoint polled every five minutes. Deciding here,\n * once, at the moment of the claim, lets the probe stay an aggregation over a\n * marker field, exactly like AGL-1954's `inertAtMs`.\n *\n * ## Absent, zero and unknown are THREE different things\n *\n * `strictNullChecks` is off repo-wide, so an absent `created` folds to falsy\n * and a naive `Number(event?.created ?? 0)` yields 0 — which subtracts to a\n * lag of ~1.7 BILLION seconds and reports every such delivery as a retry,\n * forever, on a perfectly healthy webhook. A monitoring signal that reds on\n * its own missing input is worse than no signal, because it is the thing that\n * gets muted. So each of those inputs is rejected by name:\n *\n * | input                       | attempt    | reason                  |\n * |-----------------------------|------------|-------------------------|\n * | field absent / null         | `unknown`  | `created-absent`        |\n * | a string, NaN, Infinity     | `unknown`  | `created-not-a-number`  |\n * | `0` or negative             | `unknown`  | `created-non-positive`  |\n * | our own stamp unusable      | `unknown`  | `received-unusable`     |\n * | created in the FUTURE by more than the bar | `unknown` | `clock-skew` |\n *\n * A lag between `-threshold` and `+threshold` is `first-attempt`: sub-second\n * clock skew between Stripe's clock and ours is ordinary and is not evidence\n * of anything.\n *\n * Pure: no clock, no I/O. The caller supplies both timestamps.\n */\nexport function classifyDeliveryLag(input: {\n  /** `event.created`, in unix SECONDS, exactly as Stripe sent it. */\n  eventCreatedSeconds: unknown\n  /** When we claimed the event, in unix MILLISECONDS. */\n  receivedAtMs: unknown\n  /** Overridable so the spec can prove the rule rather than the constant. */\n  thresholdSeconds?: number\n}): WebhookDeliveryLagVerdict {\n  const threshold = input.thresholdSeconds ?? RETRY_LAG_SECONDS\n  const created = input.eventCreatedSeconds\n  if (created === undefined || created === null) {\n    return { attempt: 'unknown', lagSeconds: null, reason: 'created-absent' }\n  }\n  if (typeof created !== 'number' || !Number.isFinite(created)) {\n    return {\n      attempt: 'unknown',\n      lagSeconds: null,\n      reason: 'created-not-a-number',\n    }\n  }\n  // Zero is the value an absent field folds to under the repo's null rules,\n  // and no Stripe event was created at the epoch. Rejected by name so it can\n  // never be mistaken for a measurement.\n  if (created <= 0) {\n    return {\n      attempt: 'unknown',\n      lagSeconds: null,\n      reason: 'created-non-positive',\n    }\n  }\n  const received = input.receivedAtMs\n  if (typeof received !== 'number' || !Number.isFinite(received) || received <= 0) {\n    return { attempt: 'unknown', lagSeconds: null, reason: 'received-unusable' }\n  }\n  const lagSeconds = received / 1000 - created\n  // An event stamped in OUR future by more than the threshold is a clock\n  // disagreement, not a fast delivery, and reporting it as a healthy first\n  // attempt would be an answer we cannot support.\n  if (lagSeconds < -threshold) {\n    return { attempt: 'unknown', lagSeconds: null, reason: 'clock-skew' }\n  }\n  return {\n    attempt: lagSeconds > threshold ? 'retried' : 'first-attempt',\n    lagSeconds,\n    reason: 'measured',\n  }\n}\n\n/**\n * Which required events is a destination NOT subscribed to? (AGL-1948)\n *\n * The same blind spot from the configuration side, and the cheaper half of\n * it: a subscription removed by hand in the Stripe dashboard produces no\n * failed delivery, no rejected request and no inert one either — Stripe\n * simply stops sending, and every count on the health probe reads a\n * perfectly healthy zero. `charge.refunded` was missing from the live\n * endpoint for exactly this reason (AGL-1798) and the only thing that ever\n * noticed was a script nobody ran.\n *\n * `['*']` is Stripe's wildcard subscription and covers everything.\n *\n * Returns the names, sorted, so the probe body is stable and a diff between\n * two readings is meaningful.\n */\nexport function unsubscribedRequiredEvents(\n  enabledEvents: readonly string[] | null | undefined,\n  required: readonly string[] = REQUIRED_WEBHOOK_EVENTS,\n): string[] {\n  if (!enabledEvents) return []\n  if (enabledEvents.includes('*')) return []\n  const enabled = new Set(enabledEvents)\n  return required.filter((event) => !enabled.has(event)).sort()\n}\n"],"names":["REQUIRED_WEBHOOK_EVENTS","CONNECT_SCOPE_METADATA_KEY","CONNECT_SCOPE_METADATA_VALUE","REQUIRED_CONNECT_WEBHOOK_EVENTS","isConnectWebhookEndpoint","endpoint","metadata","createWebhookEffectLedger","effects","skips","effect","name","push","skip","reason","WRITE_METHODS","Set","observeWrites","handle","ledger","label","Proxy","get","target","property","receiver","value","Reflect","method","args","result","apply","nextLabel","has","Promise","resolve","then","settled","classifyWebhookDelivery","input","type","claimed","required","length","outcome","includes","RETRY_LAG_SECONDS","classifyDeliveryLag","threshold","thresholdSeconds","created","eventCreatedSeconds","undefined","attempt","lagSeconds","Number","isFinite","received","receivedAtMs","unsubscribedRequiredEvents","enabledEvents","enabled","filter","event","sort"],"mappings":"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"}

package/src/lib/foundation/definitions/org-billing.types.d.ts

@@ -1259,6 +1259,14 @@ export interface OrgCrmSettings {
      * nobody asked for. Public mailbox domains never qualify either way.
      */
     autoCreateCompanies?: boolean;
+    /**
+     * What a new contact, company, deal or task starts shared with
+     * (AGL-3662), set apart from datasets and media. `'org'`: every site.
+     * `'host'`: the site it came in on and its consent group. Unset reads the
+     * org's `defaultResourceScope` — see `crmDefaultScopeOf` — and then
+     * `'host'`.
+     */
+    defaultRecordScope?: 'org' | 'host';
     /**
      * Per-site settings, keyed by host id (AGL-2618). On the ORG document
      * rather than on each host document because the reader is the org-level