@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/api-idempotency.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The atomic attempt claim (AGL-1691, promoted here by AGL-1697).
+ *
+ * Nine call sites in this repo create a Stripe Checkout session and eight of
+ * them sent no `Idempotency-Key`, so a retry, a double-click or a client
+ * timeout minted a second session on a live account. Closing them one at a time
+ * with one local copy each is how a codebase ends up with nine subtly different
+ * answers to the same question, so the POS implementation moves here whole
+ * rather than being reimplemented per caller.
+ *
+ * Exported ONLY from `@aglyn/aglyn/server` (never the client barrel): it needs
+ * `node:crypto`, which is the same reason `realm-server` lives behind that
+ * entry point.
+ */
+/**
+ * The minimum Firestore surface the claim needs, declared structurally.
+ *
+ * A `FirebaseFirestore.Firestore` satisfies it, but stating it this way keeps
+ * `@aglyn/aglyn` free of a firebase-admin dependency — and it is the reason a
+ * spec can hand this an in-memory map and count what actually landed.
+ */
+export interface IdempotencyDocRef {
+    create(data: Record<string, unknown>): Promise<unknown>;
+    get(): Promise<{
+        get(field: string): unknown;
+    }>;
+    set(data: Record<string, unknown>, options: {
+        merge: boolean;
+    }): Promise<unknown>;
+    delete(): Promise<unknown>;
+}
+export interface IdempotencyStore {
+    collection(name: string): {
+        doc(id: string): IdempotencyDocRef;
+    };
+}
+/** A claim on one attempt. */
+export interface AttemptClaim {
+    /**
+     * The digest to hand Stripe as `Idempotency-Key`, or null when the client
+     * sent no key.
+     */
+    stripeKey: string | null;
+    /** Record the response so a repeat of this attempt replays it. */
+    record: (status: number, body: unknown) => Promise<void>;
+    /** Give the key back, so a failed attempt can be retried with it. */
+    release: () => Promise<void>;
+}
+export type AttemptClaimResult = {
+    claim: AttemptClaim;
+} | {
+    replay: {
+        status: number;
+        body: unknown;
+    };
+};
+export interface AttemptScope {
+    /**
+     * What kind of attempt this is (`pos`, `marketplace-checkout`, …). Part of
+     * the digest, so two features cannot collide on one client-minted key.
+     */
+    kind: string;
+    /**
+     * What the attempt is scoped to — a host id, or a `listingId:buyerUid` pair.
+     * Also part of the digest.
+     */
+    scopeId: string;
+    /**
+     * The org whose data this is, so `eraseOrgIdempotencyKeys` sweeps the claim
+     * on org erasure (AGL-1448). Empty is written as explicit `null` — Firestore
+     * rejects `undefined`.
+     */
+    orgId: string;
+    /** The client-minted attempt key. Empty means "the client sent none". */
+    key: string;
+    /** What to answer a caller whose identical attempt is still in flight. */
+    busyMessage: string;
+}
+/**
+ * How long a replay key is remembered (AGL-1978).
+ *
+ * This was unbounded, and the reason that matters is not document count. A
+ * settled claim stores the ORIGINAL RESPONSE BODY, and for the REST API that
+ * body is the created record's `values` — the customer's own data. So the
+ * collection was a second, permanent copy of every record ever created
+ * through the API, and `conventions.md` advertises the consequence in terms:
+ * a replay "keeps working after the record has been edited or deleted". A
+ * customer who deleted a record left our copy of it behind, forever, in a
+ * collection nobody thought of as content.
+ *
+ * 30 days, chosen against real retry behaviour rather than against the
+ * feeling that shorter is safer:
+ *
+ * - Stripe's own idempotency window is 24 hours, and it serves the whole
+ *   payments industry. 30 days is thirty times that.
+ * - It covers every retry pattern an integration actually has: the immediate
+ *   retry, the retry after a timeout, and the nightly job that fails and
+ *   re-runs the next morning. A human re-importing last quarter's data is
+ *   not retrying — that is a new operation, and it should mint a new key.
+ * - It turns an unbounded archive into a working set without touching the
+ *   in-flight semantics the `409` protects.
+ *
+ * ⚠️ This CHANGES a documented promise. `apps/docs/api/conventions.md` said
+ * keys "never expire — a key really is single-use forever"; it now states
+ * the window. The doc moved in the same commit, because a retention change
+ * that leaves the published contract behind is the AGL-1496 shape.
+ */
+export declare const API_IDEMPOTENCY_RETENTION_DAYS = 30;
+/**
+ * When a claim taken at `now` expires. A `Date`, never an epoch number: a
+ * TTL policy keys on a Firestore Timestamp and silently governs nothing when
+ * the field is a number. Note the existing `createdAtMs`/`settledAtMs`
+ * fields are numbers and could not have been used — which is why AGL-1978
+ * called for a new field rather than a policy on an existing one.
+ */
+export declare function apiIdempotencyExpiry(now?: Date): Date;
+/**
+ * One Stripe idempotency key per OBJECT an attempt creates (AGL-1714).
+ *
+ * Stripe's idempotency layer is account-scoped, not endpoint-scoped: it
+ * "compares incoming parameters to those of the original request and errors if
+ * they're not the same". Sending one claim digest unchanged to two endpoints —
+ * a coupon and then the session, a price and then the subscription — therefore
+ * makes the SECOND call fail outright. An attempt that creates more than one
+ * Stripe object derives a key per object from the one digest instead.
+ *
+ * Null-propagating so a keyless attempt (older cached client bundle) sends no
+ * header at all rather than the string `"null:session"`.
+ */
+export declare function deriveStripeObjectKey(digest: string | null, object: string): string | null;
+/**
+ * Take an exclusive claim on one attempt, so a retry cannot mint a second
+ * order, a second purchase or a second Checkout session.
+ *
+ * The key is supplied by the CLIENT, once per attempt, and is deliberately NOT
+ * derived from the content. A cashier ringing the same coffee twice in a minute
+ * is a real second sale, and a buyer re-buying a component after a refund is a
+ * real second purchase; a content hash would silently swallow both, which is a
+ * worse bug than the one this closes. So the client mints a key when something
+ * first becomes an attempt and retires it when that attempt is over — stable
+ * across a retry of THAT attempt, distinct for a legitimately identical next
+ * one. Callers that need "you cannot have two of these at all" want a business
+ * rule as well, not a longer-lived key.
+ *
+ * The claim is `create()`. Firestore rejects a create on an existing document,
+ * and that rejection is the whole dedupe primitive — a read-then-write would
+ * race exactly the double-submit it exists to stop.
+ *
+ * Storage reuses the REST API's collection and its `orgId` field rather than
+ * inventing a second replay store, so `eraseOrgIdempotencyKeys` already sweeps
+ * these on org erasure (AGL-1448) with no change there.
+ */
+export declare function claimAttempt(store: IdempotencyStore, scope: AttemptScope): Promise<AttemptClaimResult>;

package/src/lib/app-utils/api-idempotency.js

@@ -0,0 +1,213 @@
+/**
+ * @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 { createHash } from "node:crypto";
+/** Where the REST API already keeps replay keys (AGL-618). */ const COLLECTION = 'apiIdempotency';
+/**
+ * How long a replay key is remembered (AGL-1978).
+ *
+ * This was unbounded, and the reason that matters is not document count. A
+ * settled claim stores the ORIGINAL RESPONSE BODY, and for the REST API that
+ * body is the created record's `values` — the customer's own data. So the
+ * collection was a second, permanent copy of every record ever created
+ * through the API, and `conventions.md` advertises the consequence in terms:
+ * a replay "keeps working after the record has been edited or deleted". A
+ * customer who deleted a record left our copy of it behind, forever, in a
+ * collection nobody thought of as content.
+ *
+ * 30 days, chosen against real retry behaviour rather than against the
+ * feeling that shorter is safer:
+ *
+ * - Stripe's own idempotency window is 24 hours, and it serves the whole
+ *   payments industry. 30 days is thirty times that.
+ * - It covers every retry pattern an integration actually has: the immediate
+ *   retry, the retry after a timeout, and the nightly job that fails and
+ *   re-runs the next morning. A human re-importing last quarter's data is
+ *   not retrying — that is a new operation, and it should mint a new key.
+ * - It turns an unbounded archive into a working set without touching the
+ *   in-flight semantics the `409` protects.
+ *
+ * ⚠️ This CHANGES a documented promise. `apps/docs/api/conventions.md` said
+ * keys "never expire — a key really is single-use forever"; it now states
+ * the window. The doc moved in the same commit, because a retention change
+ * that leaves the published contract behind is the AGL-1496 shape.
+ */ export const API_IDEMPOTENCY_RETENTION_DAYS = 30;
+/**
+ * When a claim taken at `now` expires. A `Date`, never an epoch number: a
+ * TTL policy keys on a Firestore Timestamp and silently governs nothing when
+ * the field is a number. Note the existing `createdAtMs`/`settledAtMs`
+ * fields are numbers and could not have been used — which is why AGL-1978
+ * called for a new field rather than a policy on an existing one.
+ */ export function apiIdempotencyExpiry(now = new Date()) {
+    return new Date(now.getTime() + API_IDEMPOTENCY_RETENTION_DAYS * 24 * 60 * 60 * 1000);
+}
+/**
+ * One Stripe idempotency key per OBJECT an attempt creates (AGL-1714).
+ *
+ * Stripe's idempotency layer is account-scoped, not endpoint-scoped: it
+ * "compares incoming parameters to those of the original request and errors if
+ * they're not the same". Sending one claim digest unchanged to two endpoints —
+ * a coupon and then the session, a price and then the subscription — therefore
+ * makes the SECOND call fail outright. An attempt that creates more than one
+ * Stripe object derives a key per object from the one digest instead.
+ *
+ * Null-propagating so a keyless attempt (older cached client bundle) sends no
+ * header at all rather than the string `"null:session"`.
+ */ export function deriveStripeObjectKey(digest, object) {
+    return digest ? `${digest}:${object}` : null;
+}
+/**
+ * Take an exclusive claim on one attempt, so a retry cannot mint a second
+ * order, a second purchase or a second Checkout session.
+ *
+ * The key is supplied by the CLIENT, once per attempt, and is deliberately NOT
+ * derived from the content. A cashier ringing the same coffee twice in a minute
+ * is a real second sale, and a buyer re-buying a component after a refund is a
+ * real second purchase; a content hash would silently swallow both, which is a
+ * worse bug than the one this closes. So the client mints a key when something
+ * first becomes an attempt and retires it when that attempt is over — stable
+ * across a retry of THAT attempt, distinct for a legitimately identical next
+ * one. Callers that need "you cannot have two of these at all" want a business
+ * rule as well, not a longer-lived key.
+ *
+ * The claim is `create()`. Firestore rejects a create on an existing document,
+ * and that rejection is the whole dedupe primitive — a read-then-write would
+ * race exactly the double-submit it exists to stop.
+ *
+ * Storage reuses the REST API's collection and its `orgId` field rather than
+ * inventing a second replay store, so `eraseOrgIdempotencyKeys` already sweeps
+ * these on org erasure (AGL-1448) with no change there.
+ */ export async function claimAttempt(store, scope) {
+    // No key: transact as before. These are public API routes and an older
+    // cached client bundle must keep working rather than start failing.
+    //
+    // ⚠️ THIS IS A NO-OP CLAIM, AND IT IS A REAL HOLE — deliberately left open,
+    // now made LOUD (AGL-2163). `stripeKey: null` propagates through
+    // `deriveStripeObjectKey` to the Stripe call (see
+    // `marketplace/checkout.ts`), so a caller that sends no Idempotency-Key
+    // header gets neither our claim nor Stripe's own 24-hour window: the
+    // concurrent-double-charge race this module exists to close is fully back
+    // for that request.
+    //
+    // THE POLICY IS NOT CHANGED HERE, ON PURPOSE. The obvious "fix" — synthesise
+    // a key from the request body — would redefine what "the same attempt"
+    // means: a cashier ringing the same coffee twice and a buyer re-purchasing
+    // the same listing after a refund would both read as replays and be
+    // silently swallowed, which is a worse bug than the one it closes (see the
+    // paragraph above on why the key is client-minted). Requiring the header
+    // instead would break every older cached client bundle mid-checkout.
+    // Choosing between those two is a product call, not a bug fix.
+    //
+    // What IS wrong is that it was SILENT. An unprotected money call left no
+    // trace anywhere, so nobody could tell whether this path was taken once a
+    // year or on a third of all checkouts — which is exactly the number the
+    // policy decision needs. `console.warn` rather than a counter because it
+    // rides the platform's existing log pipeline and this path is low-volume by
+    // construction (one line per money attempt, not per request).
+    if (!scope.key) {
+        var _scope_orgId;
+        console.warn('api-idempotency: UNPROTECTED money call — no Idempotency-Key header, ' + 'so neither the attempt claim nor Stripe idempotency applies', {
+            kind: scope.kind,
+            scopeId: scope.scopeId,
+            orgId: (_scope_orgId = scope.orgId) != null ? _scope_orgId : null
+        });
+        return {
+            claim: {
+                stripeKey: null,
+                record: async ()=>undefined,
+                release: async ()=>undefined
+            }
+        };
+    }
+    const digest = createHash('sha256').update(`${scope.kind}:${scope.scopeId}:${scope.key}`).digest('hex');
+    const ref = store.collection(COLLECTION).doc(digest);
+    try {
+        await ref.create({
+            orgId: scope.orgId || null,
+            scopeId: scope.scopeId,
+            kind: scope.kind,
+            status: 'pending',
+            createdAtMs: Date.now(),
+            // Stamped at CLAIM, not at settlement, so a claim stranded by a killed
+            // process is reaped on the same schedule as one that completed. Those
+            // are the documents that would otherwise sit forever holding a key
+            // hostage — the failure mode `release()` exists to avoid and cannot
+            // cover when the process is gone.
+            expiresAt: apiIdempotencyExpiry()
+        });
+    } catch (unused) {
+        // Already claimed: either the attempt finished and we replay its result,
+        // or it is still in flight.
+        const prior = await ref.get();
+        const priorResponse = prior.get('response');
+        if (priorResponse) {
+            var _prior_get;
+            return {
+                replay: {
+                    status: Number((_prior_get = prior.get('responseStatus')) != null ? _prior_get : 200),
+                    body: priorResponse
+                }
+            };
+        }
+        // In flight. Fail CLOSED — the money direction. Letting the second caller
+        // through IS the duplicate charge. A process killed between the claim and
+        // the record leaves a key stuck here; the customer starts a fresh attempt
+        // with a fresh key, which is the correct failure direction even though it
+        // is not a pleasant one.
+        return {
+            replay: {
+                status: 409,
+                body: {
+                    error: scope.busyMessage
+                }
+            }
+        };
+    }
+    return {
+        claim: {
+            // The same digest goes to Stripe, so even if our claim is lost after the
+            // call, Stripe replays its own session rather than opening a second one.
+            // Scoped by kind and attempt, so it cannot collide.
+            stripeKey: digest,
+            // Both swallow their own failure. A claim that cannot be recorded or
+            // released must not turn a completed purchase into a 500 — the money has
+            // already moved by then, and the worst case here is a key that replays
+            // nothing or one that goes unused.
+            record: async (status, body)=>{
+                try {
+                    await ref.set({
+                        status: 'done',
+                        responseStatus: status,
+                        response: body,
+                        settledAtMs: Date.now()
+                    }, {
+                        merge: true
+                    });
+                } catch (unused) {
+                /* best effort */ }
+            },
+            // A rejected or failed attempt must not burn the key: the customer fixes
+            // the cause and presses the same button.
+            release: async ()=>{
+                try {
+                    await ref.delete();
+                } catch (unused) {
+                /* best effort */ }
+            }
+        }
+    };
+}
+
+//# sourceMappingURL=api-idempotency.js.map

package/src/lib/app-utils/api-idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/api-idempotency.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 { createHash } from 'node:crypto'\n\n/**\n * The atomic attempt claim (AGL-1691, promoted here by AGL-1697).\n *\n * Nine call sites in this repo create a Stripe Checkout session and eight of\n * them sent no `Idempotency-Key`, so a retry, a double-click or a client\n * timeout minted a second session on a live account. Closing them one at a time\n * with one local copy each is how a codebase ends up with nine subtly different\n * answers to the same question, so the POS implementation moves here whole\n * rather than being reimplemented per caller.\n *\n * Exported ONLY from `@aglyn/aglyn/server` (never the client barrel): it needs\n * `node:crypto`, which is the same reason `realm-server` lives behind that\n * entry point.\n */\n\n/**\n * The minimum Firestore surface the claim needs, declared structurally.\n *\n * A `FirebaseFirestore.Firestore` satisfies it, but stating it this way keeps\n * `@aglyn/aglyn` free of a firebase-admin dependency — and it is the reason a\n * spec can hand this an in-memory map and count what actually landed.\n */\nexport interface IdempotencyDocRef {\n  create(data: Record<string, unknown>): Promise<unknown>\n  get(): Promise<{ get(field: string): unknown }>\n  set(data: Record<string, unknown>, options: { merge: boolean }): Promise<unknown>\n  delete(): Promise<unknown>\n}\n\nexport interface IdempotencyStore {\n  collection(name: string): { doc(id: string): IdempotencyDocRef }\n}\n\n/** A claim on one attempt. */\nexport interface AttemptClaim {\n  /**\n   * The digest to hand Stripe as `Idempotency-Key`, or null when the client\n   * sent no key.\n   */\n  stripeKey: string | null\n  /** Record the response so a repeat of this attempt replays it. */\n  record: (status: number, body: unknown) => Promise<void>\n  /** Give the key back, so a failed attempt can be retried with it. */\n  release: () => Promise<void>\n}\n\nexport type AttemptClaimResult =\n  | { claim: AttemptClaim }\n  | { replay: { status: number; body: unknown } }\n\nexport interface AttemptScope {\n  /**\n   * What kind of attempt this is (`pos`, `marketplace-checkout`, …). Part of\n   * the digest, so two features cannot collide on one client-minted key.\n   */\n  kind: string\n  /**\n   * What the attempt is scoped to — a host id, or a `listingId:buyerUid` pair.\n   * Also part of the digest.\n   */\n  scopeId: string\n  /**\n   * The org whose data this is, so `eraseOrgIdempotencyKeys` sweeps the claim\n   * on org erasure (AGL-1448). Empty is written as explicit `null` — Firestore\n   * rejects `undefined`.\n   */\n  orgId: string\n  /** The client-minted attempt key. Empty means \"the client sent none\". */\n  key: string\n  /** What to answer a caller whose identical attempt is still in flight. */\n  busyMessage: string\n}\n\n/** Where the REST API already keeps replay keys (AGL-618). */\nconst COLLECTION = 'apiIdempotency'\n\n/**\n * How long a replay key is remembered (AGL-1978).\n *\n * This was unbounded, and the reason that matters is not document count. A\n * settled claim stores the ORIGINAL RESPONSE BODY, and for the REST API that\n * body is the created record's `values` — the customer's own data. So the\n * collection was a second, permanent copy of every record ever created\n * through the API, and `conventions.md` advertises the consequence in terms:\n * a replay \"keeps working after the record has been edited or deleted\". A\n * customer who deleted a record left our copy of it behind, forever, in a\n * collection nobody thought of as content.\n *\n * 30 days, chosen against real retry behaviour rather than against the\n * feeling that shorter is safer:\n *\n * - Stripe's own idempotency window is 24 hours, and it serves the whole\n *   payments industry. 30 days is thirty times that.\n * - It covers every retry pattern an integration actually has: the immediate\n *   retry, the retry after a timeout, and the nightly job that fails and\n *   re-runs the next morning. A human re-importing last quarter's data is\n *   not retrying — that is a new operation, and it should mint a new key.\n * - It turns an unbounded archive into a working set without touching the\n *   in-flight semantics the `409` protects.\n *\n * ⚠️ This CHANGES a documented promise. `apps/docs/api/conventions.md` said\n * keys \"never expire — a key really is single-use forever\"; it now states\n * the window. The doc moved in the same commit, because a retention change\n * that leaves the published contract behind is the AGL-1496 shape.\n */\nexport const API_IDEMPOTENCY_RETENTION_DAYS = 30\n\n/**\n * When a claim taken at `now` expires. A `Date`, never an epoch number: a\n * TTL policy keys on a Firestore Timestamp and silently governs nothing when\n * the field is a number. Note the existing `createdAtMs`/`settledAtMs`\n * fields are numbers and could not have been used — which is why AGL-1978\n * called for a new field rather than a policy on an existing one.\n */\nexport function apiIdempotencyExpiry(now = new Date()): Date {\n  return new Date(\n    now.getTime() + API_IDEMPOTENCY_RETENTION_DAYS * 24 * 60 * 60 * 1000,\n  )\n}\n\n/**\n * One Stripe idempotency key per OBJECT an attempt creates (AGL-1714).\n *\n * Stripe's idempotency layer is account-scoped, not endpoint-scoped: it\n * \"compares incoming parameters to those of the original request and errors if\n * they're not the same\". Sending one claim digest unchanged to two endpoints —\n * a coupon and then the session, a price and then the subscription — therefore\n * makes the SECOND call fail outright. An attempt that creates more than one\n * Stripe object derives a key per object from the one digest instead.\n *\n * Null-propagating so a keyless attempt (older cached client bundle) sends no\n * header at all rather than the string `\"null:session\"`.\n */\nexport function deriveStripeObjectKey(\n  digest: string | null,\n  object: string,\n): string | null {\n  return digest ? `${digest}:${object}` : null\n}\n\n/**\n * Take an exclusive claim on one attempt, so a retry cannot mint a second\n * order, a second purchase or a second Checkout session.\n *\n * The key is supplied by the CLIENT, once per attempt, and is deliberately NOT\n * derived from the content. A cashier ringing the same coffee twice in a minute\n * is a real second sale, and a buyer re-buying a component after a refund is a\n * real second purchase; a content hash would silently swallow both, which is a\n * worse bug than the one this closes. So the client mints a key when something\n * first becomes an attempt and retires it when that attempt is over — stable\n * across a retry of THAT attempt, distinct for a legitimately identical next\n * one. Callers that need \"you cannot have two of these at all\" want a business\n * rule as well, not a longer-lived key.\n *\n * The claim is `create()`. Firestore rejects a create on an existing document,\n * and that rejection is the whole dedupe primitive — a read-then-write would\n * race exactly the double-submit it exists to stop.\n *\n * Storage reuses the REST API's collection and its `orgId` field rather than\n * inventing a second replay store, so `eraseOrgIdempotencyKeys` already sweeps\n * these on org erasure (AGL-1448) with no change there.\n */\nexport async function claimAttempt(\n  store: IdempotencyStore,\n  scope: AttemptScope,\n): Promise<AttemptClaimResult> {\n  // No key: transact as before. These are public API routes and an older\n  // cached client bundle must keep working rather than start failing.\n  //\n  // ⚠️ THIS IS A NO-OP CLAIM, AND IT IS A REAL HOLE — deliberately left open,\n  // now made LOUD (AGL-2163). `stripeKey: null` propagates through\n  // `deriveStripeObjectKey` to the Stripe call (see\n  // `marketplace/checkout.ts`), so a caller that sends no Idempotency-Key\n  // header gets neither our claim nor Stripe's own 24-hour window: the\n  // concurrent-double-charge race this module exists to close is fully back\n  // for that request.\n  //\n  // THE POLICY IS NOT CHANGED HERE, ON PURPOSE. The obvious \"fix\" — synthesise\n  // a key from the request body — would redefine what \"the same attempt\"\n  // means: a cashier ringing the same coffee twice and a buyer re-purchasing\n  // the same listing after a refund would both read as replays and be\n  // silently swallowed, which is a worse bug than the one it closes (see the\n  // paragraph above on why the key is client-minted). Requiring the header\n  // instead would break every older cached client bundle mid-checkout.\n  // Choosing between those two is a product call, not a bug fix.\n  //\n  // What IS wrong is that it was SILENT. An unprotected money call left no\n  // trace anywhere, so nobody could tell whether this path was taken once a\n  // year or on a third of all checkouts — which is exactly the number the\n  // policy decision needs. `console.warn` rather than a counter because it\n  // rides the platform's existing log pipeline and this path is low-volume by\n  // construction (one line per money attempt, not per request).\n  if (!scope.key) {\n    console.warn(\n      'api-idempotency: UNPROTECTED money call — no Idempotency-Key header, ' +\n        'so neither the attempt claim nor Stripe idempotency applies',\n      { kind: scope.kind, scopeId: scope.scopeId, orgId: scope.orgId ?? null },\n    )\n    return {\n      claim: {\n        stripeKey: null,\n        record: async () => undefined,\n        release: async () => undefined,\n      },\n    }\n  }\n  const digest = createHash('sha256')\n    .update(`${scope.kind}:${scope.scopeId}:${scope.key}`)\n    .digest('hex')\n  const ref = store.collection(COLLECTION).doc(digest)\n  try {\n    await ref.create({\n      orgId: scope.orgId || null,\n      scopeId: scope.scopeId,\n      kind: scope.kind,\n      status: 'pending',\n      createdAtMs: Date.now(),\n      // Stamped at CLAIM, not at settlement, so a claim stranded by a killed\n      // process is reaped on the same schedule as one that completed. Those\n      // are the documents that would otherwise sit forever holding a key\n      // hostage — the failure mode `release()` exists to avoid and cannot\n      // cover when the process is gone.\n      expiresAt: apiIdempotencyExpiry(),\n    })\n  } catch {\n    // Already claimed: either the attempt finished and we replay its result,\n    // or it is still in flight.\n    const prior = await ref.get()\n    const priorResponse = prior.get('response')\n    if (priorResponse) {\n      return {\n        replay: {\n          status: Number(prior.get('responseStatus') ?? 200),\n          body: priorResponse,\n        },\n      }\n    }\n    // In flight. Fail CLOSED — the money direction. Letting the second caller\n    // through IS the duplicate charge. A process killed between the claim and\n    // the record leaves a key stuck here; the customer starts a fresh attempt\n    // with a fresh key, which is the correct failure direction even though it\n    // is not a pleasant one.\n    return { replay: { status: 409, body: { error: scope.busyMessage } } }\n  }\n  return {\n    claim: {\n      // The same digest goes to Stripe, so even if our claim is lost after the\n      // call, Stripe replays its own session rather than opening a second one.\n      // Scoped by kind and attempt, so it cannot collide.\n      stripeKey: digest,\n      // Both swallow their own failure. A claim that cannot be recorded or\n      // released must not turn a completed purchase into a 500 — the money has\n      // already moved by then, and the worst case here is a key that replays\n      // nothing or one that goes unused.\n      record: async (status: number, body: unknown): Promise<void> => {\n        try {\n          await ref.set(\n            {\n              status: 'done',\n              responseStatus: status,\n              response: body,\n              settledAtMs: Date.now(),\n            },\n            { merge: true },\n          )\n        } catch {\n          /* best effort */\n        }\n      },\n      // A rejected or failed attempt must not burn the key: the customer fixes\n      // the cause and presses the same button.\n      release: async (): Promise<void> => {\n        try {\n          await ref.delete()\n        } catch {\n          /* best effort */\n        }\n      },\n    },\n  }\n}\n"],"names":["createHash","COLLECTION","API_IDEMPOTENCY_RETENTION_DAYS","apiIdempotencyExpiry","now","Date","getTime","deriveStripeObjectKey","digest","object","claimAttempt","store","scope","key","console","warn","kind","scopeId","orgId","claim","stripeKey","record","undefined","release","update","ref","collection","doc","create","status","createdAtMs","expiresAt","prior","get","priorResponse","replay","Number","body","error","busyMessage","set","responseStatus","response","settledAtMs","merge","delete"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,UAAU,QAAQ,cAAa;AA2ExC,4DAA4D,GAC5D,MAAMC,aAAa;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GACD,OAAO,MAAMC,iCAAiC,GAAE;AAEhD;;;;;;CAMC,GACD,OAAO,SAASC,qBAAqBC,MAAM,IAAIC,MAAM;IACnD,OAAO,IAAIA,KACTD,IAAIE,OAAO,KAAKJ,iCAAiC,KAAK,KAAK,KAAK;AAEpE;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASK,sBACdC,MAAqB,EACrBC,MAAc;IAEd,OAAOD,SAAS,GAAGA,OAAO,CAAC,EAAEC,QAAQ,GAAG;AAC1C;AAEA;;;;;;;;;;;;;;;;;;;;;CAqBC,GACD,OAAO,eAAeC,aACpBC,KAAuB,EACvBC,KAAmB;IAEnB,uEAAuE;IACvE,oEAAoE;IACpE,EAAE;IACF,4EAA4E;IAC5E,iEAAiE;IACjE,kDAAkD;IAClD,wEAAwE;IACxE,qEAAqE;IACrE,0EAA0E;IAC1E,oBAAoB;IACpB,EAAE;IACF,6EAA6E;IAC7E,uEAAuE;IACvE,2EAA2E;IAC3E,oEAAoE;IACpE,2EAA2E;IAC3E,yEAAyE;IACzE,qEAAqE;IACrE,+DAA+D;IAC/D,EAAE;IACF,yEAAyE;IACzE,0EAA0E;IAC1E,wEAAwE;IACxE,yEAAyE;IACzE,4EAA4E;IAC5E,8DAA8D;IAC9D,IAAI,CAACA,MAAMC,GAAG,EAAE;YAIuCD;QAHrDE,QAAQC,IAAI,CACV,0EACE,+DACF;YAAEC,MAAMJ,MAAMI,IAAI;YAAEC,SAASL,MAAMK,OAAO;YAAEC,KAAK,GAAEN,eAAAA,MAAMM,KAAK,YAAXN,eAAe;QAAK;QAEzE,OAAO;YACLO,OAAO;gBACLC,WAAW;gBACXC,QAAQ,UAAYC;gBACpBC,SAAS,UAAYD;YACvB;QACF;IACF;IACA,MAAMd,SAASR,WAAW,UACvBwB,MAAM,CAAC,GAAGZ,MAAMI,IAAI,CAAC,CAAC,EAAEJ,MAAMK,OAAO,CAAC,CAAC,EAAEL,MAAMC,GAAG,EAAE,EACpDL,MAAM,CAAC;IACV,MAAMiB,MAAMd,MAAMe,UAAU,CAACzB,YAAY0B,GAAG,CAACnB;IAC7C,IAAI;QACF,MAAMiB,IAAIG,MAAM,CAAC;YACfV,OAAON,MAAMM,KAAK,IAAI;YACtBD,SAASL,MAAMK,OAAO;YACtBD,MAAMJ,MAAMI,IAAI;YAChBa,QAAQ;YACRC,aAAazB,KAAKD,GAAG;YACrB,uEAAuE;YACvE,sEAAsE;YACtE,mEAAmE;YACnE,oEAAoE;YACpE,kCAAkC;YAClC2B,WAAW5B;QACb;IACF,EAAE,eAAM;QACN,yEAAyE;QACzE,4BAA4B;QAC5B,MAAM6B,QAAQ,MAAMP,IAAIQ,GAAG;QAC3B,MAAMC,gBAAgBF,MAAMC,GAAG,CAAC;QAChC,IAAIC,eAAe;gBAGEF;YAFnB,OAAO;gBACLG,QAAQ;oBACNN,QAAQO,QAAOJ,aAAAA,MAAMC,GAAG,CAAC,6BAAVD,aAA+B;oBAC9CK,MAAMH;gBACR;YACF;QACF;QACA,0EAA0E;QAC1E,0EAA0E;QAC1E,0EAA0E;QAC1E,0EAA0E;QAC1E,yBAAyB;QACzB,OAAO;YAAEC,QAAQ;gBAAEN,QAAQ;gBAAKQ,MAAM;oBAAEC,OAAO1B,MAAM2B,WAAW;gBAAC;YAAE;QAAE;IACvE;IACA,OAAO;QACLpB,OAAO;YACL,yEAAyE;YACzE,yEAAyE;YACzE,oDAAoD;YACpDC,WAAWZ;YACX,qEAAqE;YACrE,yEAAyE;YACzE,uEAAuE;YACvE,mCAAmC;YACnCa,QAAQ,OAAOQ,QAAgBQ;gBAC7B,IAAI;oBACF,MAAMZ,IAAIe,GAAG,CACX;wBACEX,QAAQ;wBACRY,gBAAgBZ;wBAChBa,UAAUL;wBACVM,aAAatC,KAAKD,GAAG;oBACvB,GACA;wBAAEwC,OAAO;oBAAK;gBAElB,EAAE,eAAM;gBACN,eAAe,GACjB;YACF;YACA,yEAAyE;YACzE,yCAAyC;YACzCrB,SAAS;gBACP,IAAI;oBACF,MAAME,IAAIoB,MAAM;gBAClB,EAAE,eAAM;gBACN,eAAe,GACjB;YACF;QACF;IACF;AACF"}

package/src/lib/app-utils/api-plugins.d.ts

@@ -0,0 +1,210 @@
+/**
+ * @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.
+ */
+/**
+ * Server half of the plugin pattern (AGL-396): the API-route registry, the
+ * server counterpart to the ConsoleExtension registry. A feature plugin
+ * registers request handlers here from its `/server` entry point (never its
+ * client barrel, so firebase-admin and other server-only deps stay out of
+ * the browser bundle). The app ships one catch-all dispatcher route per
+ * Next app that resolves a request path to a registered handler — so moving
+ * a feature's API into its plugin needs no new app route and keeps the same
+ * URL. Reference implementation: events-calendar `events/list` (AGL-396).
+ *
+ * The request/response shapes are structural (not `next` types) so plugins
+ * stay framework-light; `NextApiRequest`/`NextApiResponse` satisfy them, so
+ * the dispatcher passes Next's objects straight through.
+ */
+export interface PluginApiRequest {
+    method?: string;
+    query: Partial<Record<string, string | string[]>>;
+    body: any;
+    /**
+     * The unparsed request text, for handlers that verify signatures over the
+     * exact payload (Stripe/Svix webhooks registered as plugin API paths).
+     * UTF-8 re-encoding of the text is byte-identical for valid UTF-8 JSON.
+     */
+    rawBody?: string;
+    headers: Partial<Record<string, string | string[]>>;
+    cookies: Partial<Record<string, string>>;
+    /**
+     * Node socket — the client-address fallback (`remoteAddress`).
+     *
+     * On the console's Pages Router this is the real transport peer. Behind the
+     * App Router adapter there is no socket, and `api-adapter.ts` fills it from
+     * the shared client-address reader so a handler falling back to it gets the
+     * same trusted hop rather than a caller-supplied one.
+     */
+    socket: {
+        remoteAddress?: string;
+    };
+}
+export interface PluginApiResponse {
+    status(code: number): PluginApiResponse;
+    json(body: unknown): void;
+    send(body: unknown): void;
+    setHeader(name: string, value: string | number | readonly string[]): void;
+    redirect(url: string): void;
+    redirect(status: number, url: string): void;
+    end(): void;
+}
+export type PluginApiHandler = (req: PluginApiRequest, res: PluginApiResponse) => void | Promise<void>;
+/**
+ * A handler in the Web shape (AGL-2939): the dispatcher's own `Request`
+ * in, a `Response` out — with a streamed body when the door streams, as
+ * the assistant's chat and a job's event feed do. `params` carries the
+ * dispatcher's path segments and any `:name` segment the registered path
+ * declared.
+ */
+export type PluginWebApiHandler = (request: Request, context: {
+    params: Record<string, string | string[]>;
+}) => Response | Promise<Response>;
+/** What a route registers: the (req, res) shape, or a Web handler. */
+export type PluginApiRoute = PluginApiHandler | {
+    web: PluginWebApiHandler;
+};
+/** A registered route matched to a request path, with its `:name` segments filled. */
+export interface PluginApiMatch {
+    route: PluginApiRoute;
+    params: Record<string, string>;
+}
+/**
+ * Who a request is FOR, as far as the dispatchers' release gate is concerned
+ * (AGL-2978).
+ *
+ * The gate buckets a rollout and reads per-org overrides on an org id, and a
+ * dispatcher learns that id from the site a request names (`hostId`). Two
+ * kinds of request name no site and still belong to one organization:
+ *
+ * - a request to an ORGANIZATION-level surface (`ConsoleExtension.orgNavItems`,
+ *   AGL-2974), which names its org rather than a site;
+ * - a request that arrives with no bearer token by design — a provider's
+ *   OAuth redirect back to the platform, which carries only what the platform
+ *   signed into it.
+ *
+ * Without a subject the gate treats both as anonymous, so a plugin released to
+ * one organization by override refused that organization's own requests, and
+ * a staff member previewing a dark plugin could not complete a redirect their
+ * own session had started.
+ */
+export interface PluginApiRequestSubject {
+    /** The organization: the rollout bucket and the override key. */
+    orgId: string | null;
+    /**
+     * The account the request acts for, read ONLY when the request carries no
+     * bearer token — a token speaks for itself. A route may name one only when
+     * it verified a signature binding the uid to the request, because the gate
+     * lets a staff account named here preview a released-off plugin.
+     */
+    uid?: string | null;
+}
+/** Reads a request's subject; answers `null` when the request names none. */
+export type PluginApiSubjectResolver = (request: Request) => PluginApiRequestSubject | null | Promise<PluginApiRequestSubject | null>;
+/** What a registration may say about its route beyond the handler. */
+export interface PluginApiRouteOptions {
+    /**
+     * How a request to this route names its subject when it names no site.
+     * Consulted by both dispatchers before their release gate, and only for a
+     * request with no `hostId`: a named site always decides the org.
+     */
+    subject?: PluginApiSubjectResolver;
+    /**
+     * The route answers a link the platform MAILED to somebody — an
+     * unsubscribe in a message's `List-Unsubscribe` header — rather than a door
+     * a member uses (AGL-2981).
+     *
+     * Such a link has to keep working whether or not its plugin is released,
+     * or switched on, for the workspace NOW. A recipient's way out does not
+     * close when a rollout is paused or a workspace turns the plugin off:
+     * CAN-SPAM holds an opt-out open for thirty days after the send, and an
+     * unsubscribe that 404s the day a kill switch is flipped is one nobody can
+     * use. So both dispatchers skip their per-site enablement and release
+     * gates for it — and nothing else: lockdown and the rate limit still
+     * apply. The flag says nothing about who may act, so the route
+     * authenticates the link itself, by a signature it verifies.
+     */
+    recipientLink?: boolean;
+}
+export { setRegisteringPluginId, getRegisteringPluginId, } from './registering-plugin';
+/**
+ * Registers a plugin API handler at a host-relative path (e.g.
+ * 'events/list'), served by the app dispatcher at `/api/events/list`.
+ *
+ * Idempotent by path FOR ITS OWNER — re-registration by the plugin that
+ * holds the path replaces the previous handler, which is what a hot reload,
+ * a second surface, and a repeated init all depend on.
+ *
+ * A different plugin is REFUSED (AGL-2484). This map is process-global and
+ * was last-writer-wins on the path alone, while Aglyn's own commission-taking
+ * handlers sit at `marketplace/checkout` and `commerce/checkout` — and the
+ * tenant dispatcher calls `ensureRemoteServerBundles()` after the first-party
+ * loader has run, so a remote bundle registering either path was simply the
+ * later writer. Getting there needs `PLUGIN_REMOTE_SERVER=enabled` (off by
+ * default), realm trust and a valid signature, so this is the last of several
+ * doors rather than the only one; it is also the one the registry could close
+ * by itself, because it already recorded who registered what.
+ *
+ * Anonymous registration — no loader marker — is an IDENTITY here, not a
+ * wildcard: it may replace itself and nothing else may take it.
+ */
+export declare function registerPluginApiRoute(path: string, handler: PluginApiRoute, options?: PluginApiRouteOptions): void;
+/** The plugin that registered a path, for per-org enablement gating. */
+export declare function pluginIdForRegisteredApiPath(path: string): string | undefined;
+export declare function unregisterPluginApiRoute(path: string): void;
+/**
+ * The route for a request path, or undefined when nothing is registered.
+ *
+ * An exact registration wins; otherwise a registration whose path carries
+ * `:name` segments matches segment for segment (`ai/jobs/:jobId/cancel`
+ * answers `ai/jobs/abc/cancel`), and the named segments come back as
+ * `params`. Patterns are tried in registration order and a static segment
+ * beats a named one only by being registered exactly.
+ */
+export declare function resolvePluginApiMatch(path: string): PluginApiMatch | undefined;
+/**
+ * Whether a request path resolves to a route registered as a
+ * {@link PluginApiRouteOptions.recipientLink} — what both dispatchers ask
+ * before their enablement and release gates (AGL-2981).
+ */
+export declare function isPluginRecipientLinkRoute(path: string): boolean;
+/**
+ * The subject a request to a registered route names, or `null` (AGL-2978).
+ *
+ * `null` when the route declared no resolver, when the resolver answered
+ * nothing, and when it THREW: a resolver that cannot read its request has
+ * named no subject, and the gate then treats the request as anonymous — the
+ * conservative direction. The resolver reads a clone, so the handler still
+ * receives the untouched body. Ids are held to a plain path segment, so a
+ * resolver cannot hand the gate a path to read overrides from.
+ */
+export declare function resolvePluginApiRequestSubject(path: string, request: Request): Promise<PluginApiRequestSubject | null>;
+/**
+ * The legacy (node-style) handler at a request path, or undefined when
+ * nothing is registered there or the route is a web handler — a web route
+ * is reached through `resolvePluginApiMatch` and `runPluginApiMatch`, since
+ * it takes the `Request` and the filled `:name` segments, not a `req`/`res`
+ * pair.
+ */
+export declare function resolvePluginApiRoute(path: string): PluginApiHandler | undefined;
+/**
+ * Runs a matched route against the dispatcher's request: a Web handler is
+ * called as it is, and a (req, res) handler goes through the adapter the
+ * caller supplies — the adapter lives on the `/server` entry, which this
+ * module may not import.
+ */
+export declare function runPluginApiMatch(match: PluginApiMatch, request: Request, params: Record<string, string | string[]>, runLegacy: (handler: PluginApiHandler, request: Request, params: Record<string, string | string[]>) => Promise<Response>): Promise<Response>;
+/** Registered paths, for diagnostics. */
+export declare function listPluginApiRoutes(): string[];