@aglyn/tenant-data-admin 1.0.0-beta.249 → 1.0.0-beta.252

package/src/lib/server/payment-fraud-hold.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @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.
+ */
+/** One document per workspace. Admin SDK only; no client rule opens it. */
+export declare const PAYMENT_FRAUD_HOLD_COLLECTION = "paymentFraudHolds";
+/** The actor every automatic payment-fraud lock's audit rows name. */
+export declare const PAYMENT_FRAUD_HOLD_ACTOR_UID = "system:payment-fraud";
+/** The lock reason the hold places. Never `abuse`: see the module header. */
+export declare const PAYMENT_FRAUD_HOLD_LOCK_REASON = "security";
+export declare const PAYMENT_FRAUD_HOLD: {
+    /** Distinct card fingerprints failing on one workspace… */
+    readonly cyclingMinCards: 3;
+    /** …within this window. */
+    readonly cyclingWindowMs: number;
+    /** A workspace this many days old or older gets an alert, not a lock. */
+    readonly youngDays: 14;
+    /** How long a failed charge is kept on the workspace's document. */
+    readonly retainMs: number;
+    /** And at most this many of them. */
+    readonly maxFailures: 30;
+    /** After an alert-only decision, how long before another may be raised. */
+    readonly alertWindowMs: number;
+    /** How long one run may hold a claim before another may take it over. */
+    readonly claimLeaseMs: number;
+};
+/** Why a hold was asked for. */
+export type PaymentFraudHoldTrigger = 'radar-blocked' | 'stripe-reported-fraud' | 'card-cycling' | 'early-fraud-warning' | 'radar-review';
+export declare const PAYMENT_FRAUD_HOLD_TRIGGER_LABELS: Record<PaymentFraudHoldTrigger, string>;
+/** What one charge says about the card, kept as evidence. */
+export interface PaymentFraudChargeEvidence {
+    chargeId: string;
+    paymentIntentId: string | null;
+    invoiceId: string | null;
+    /** The card's fingerprint: the same card number always has the same one. */
+    fingerprint: string | null;
+    cardCountry: string | null;
+    cardBrand: string | null;
+    last4: string | null;
+    /** `outcome.type`: `blocked`, `issuer_declined`, `authorized`… */
+    outcomeType: string | null;
+    /** `outcome.reason`: `highest_risk_level`, `rule`… */
+    outcomeReason: string | null;
+    riskLevel: string | null;
+    riskScore: number | null;
+    /** `fraud_details.stripe_report`. */
+    stripeReport: string | null;
+    failureCode: string | null;
+    declineCode: string | null;
+    postalCheck: string | null;
+    cvcCheck: string | null;
+    amountCents: number | null;
+    currency: string;
+    atMs: number;
+}
+/** A Stripe Charge object → the evidence kept about it. Pure. */
+export declare function chargeEvidence(charge: any, atMs: number): PaymentFraudChargeEvidence;
+/**
+ * Does this ONE charge ask for a hold? Stripe's own fraud report first —
+ * it is the stronger statement — then a Radar block at `highest` risk. A
+ * block at `elevated` risk, or by a custom rule, is not enough on its own:
+ * those catch real customers too, and card cycling is what catches the
+ * tester behind them.
+ */
+export declare function chargeFraudTrigger(evidence: Pick<PaymentFraudChargeEvidence, 'stripeReport' | 'outcomeType' | 'riskLevel'>): PaymentFraudHoldTrigger | null;
+/** Whether the failures show card cycling at `nowMs`. Pure. */
+export declare function cardCyclingPattern(failures: readonly PaymentFraudChargeEvidence[], nowMs: number): {
+    matched: boolean;
+    fingerprints: string[];
+};
+/**
+ * The guards (AGL-3767): a workspace 14+ days old, or one that has paid an
+ * invoice other than with the flagged charges, is alerted about and never
+ * locked automatically. An unreadable creation date is an existing customer,
+ * as everywhere else on the platform (`isYoungWorkspaceAge`). Pure.
+ */
+export declare function paymentFraudHoldGuard(input: {
+    ageDays: number | null;
+    hasPaidInvoice: boolean;
+}): {
+    lock: boolean;
+    reason: string | null;
+};
+/**
+ * Has this workspace paid an invoice with any charge OTHER than the flagged
+ * ones? Read off `platformRevenue`, which holds a row for every paid
+ * subscription invoice (AGL-1811). The flagged charges are excluded because
+ * a stolen card that went through has "paid" too — an early fraud warning
+ * only ever arrives on a charge that succeeded.
+ */
+export declare function hasPaidOtherInvoice(firestore: FirebaseFirestore.Firestore, orgId: string, flagged: {
+    chargeIds: readonly string[];
+    paymentIntentIds: readonly string[];
+}): Promise<boolean>;
+/**
+ * - `watching` — failures recorded, nothing asked for.
+ * - `placing` — a run claimed the hold.
+ * - `held` — locks placed. Never placed again automatically.
+ * - `alerted` — a guard made it an alert only; another alert waits out the window.
+ * - `skipped` — never held: the house, a staff-owned workspace, one that is gone.
+ */
+export type PaymentFraudHoldState = 'watching' | 'placing' | 'held' | 'alerted' | 'skipped';
+export interface PaymentFraudHoldRecord {
+    orgId: string;
+    state: PaymentFraudHoldState;
+    failures: PaymentFraudChargeEvidence[];
+    claimedAtMs?: number | null;
+    heldAtMs?: number | null;
+    alertedAtMs?: number | null;
+    trigger?: PaymentFraudHoldTrigger | null;
+    reviewId?: string | null;
+    outcome?: Record<string, unknown> | null;
+    updatedAtMs?: number;
+}
+/**
+ * Keep one failed charge on its workspace's document and say whether the
+ * failures now show card cycling. Idempotent on the charge id: a redelivery
+ * adds nothing and reports `added: false`.
+ */
+export declare function recordWorkspaceChargeFailure(firestore: FirebaseFirestore.Firestore, orgId: string, evidence: PaymentFraudChargeEvidence, nowMs?: number): Promise<{
+    added: boolean;
+    cycling: {
+        matched: boolean;
+        fingerprints: string[];
+    };
+    /** The failures inside the cycling window, oldest first, this one included. */
+    recent: PaymentFraudChargeEvidence[];
+    state: PaymentFraudHoldState;
+}>;
+/**
+ * Claim the workspace's hold for this run. Answers `claimed: false` with the
+ * reason when the hold is already placed, another run is placing it inside
+ * its lease, or a guard already alerted inside the alert window — which is
+ * what makes a redelivery, or the next card in a burst, a no-op.
+ */
+export declare function claimPaymentFraudHold(firestore: FirebaseFirestore.Firestore, orgId: string, trigger: PaymentFraudHoldTrigger, nowMs?: number): Promise<{
+    claimed: boolean;
+    /** Why not, when `claimed` is false. */
+    reason: 'held' | 'placing' | 'alerted' | 'skipped' | null;
+}>;
+/** Record what the run did with a claimed hold. */
+export declare function settlePaymentFraudHold(firestore: FirebaseFirestore.Firestore, orgId: string, state: 'held' | 'alerted' | 'skipped' | 'watching', fields: {
+    reviewId?: string | null;
+    outcome?: Record<string, unknown> | null;
+}, nowMs?: number): Promise<void>;
+/**
+ * Is this workspace on an automatic payment-fraud hold? What collapses the
+ * per-attempt `staff.paymentFailed` pings: once a workspace is held, the
+ * hold's one alert is the news, and each further declined card is not.
+ */
+export declare function isPaymentFraudHeld(firestore: FirebaseFirestore.Firestore, orgId: string): Promise<boolean>;

package/src/lib/server/payment-fraud-hold.js

@@ -0,0 +1,283 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 PAYMENT-FRAUD HOLD: THE DURABLE HALF (AGL-3767).
+ *
+ * When Stripe says a workspace's OWN subscription payment is fraud, the
+ * workspace is put on an automatic `security` hold: the workspace and each
+ * of its sites locked as a takedown, its subscriptions canceled, staff
+ * alerted once. Never `abuse`: that is a permanent ban, and Stripe's verdict
+ * is a strong signal about a card, not a decision about a person. Staff
+ * re-place the hold as `abuse` on Staff → Lockdown, or lift it.
+ *
+ * Three triggers, all on charges that resolve to a workspace through the
+ * `stripeCustomers` index — never a site's sale on a connected account:
+ *
+ *  1. one failed charge Radar BLOCKED at `highest` risk, or that Stripe
+ *     itself reported as `fraudulent` ({@link chargeFraudTrigger});
+ *  2. CARD CYCLING: failed charges on {@link PAYMENT_FRAUD_HOLD}'s
+ *     `cyclingMinCards` or more distinct card fingerprints within its
+ *     `cyclingWindowMs` ({@link cardCyclingPattern}). A real customer whose
+ *     card is declined tries it again, or tries one other card; three
+ *     different cards inside half an hour on one invoice is a card tester
+ *     working through a list. The workspace that prompted this (2026-10-13)
+ *     put four cards on one $56 invoice in two minutes;
+ *  3. an issuer's early fraud warning or a Radar review on the workspace's
+ *     charge — filed by `payment-fraud-signal.ts`, which asks for the hold.
+ *
+ * Two guards turn the hold into an alert only: a workspace 14 or more days
+ * old, or one that has paid an invoice with any charge other than the
+ * flagged ones. Those are customers with a history, and a person decides.
+ *
+ * This module is the state: one `paymentFraudHolds/{orgId}` document holding
+ * the workspace's recent failed charges (what card cycling counts) and the
+ * hold's own state, claimed in a transaction so a Stripe redelivery, or two
+ * events about one attempt arriving together, place one hold and raise one
+ * alert. The locks themselves are the console's
+ * (`apps/console/utils/server/payment-fraud-hold.ts`), because only the
+ * console holds the lockdown cores.
+ *=========================================*/ /** One document per workspace. Admin SDK only; no client rule opens it. */ export const PAYMENT_FRAUD_HOLD_COLLECTION = 'paymentFraudHolds';
+/** The actor every automatic payment-fraud lock's audit rows name. */ export const PAYMENT_FRAUD_HOLD_ACTOR_UID = 'system:payment-fraud';
+/** The lock reason the hold places. Never `abuse`: see the module header. */ export const PAYMENT_FRAUD_HOLD_LOCK_REASON = 'security';
+export const PAYMENT_FRAUD_HOLD = {
+    /** Distinct card fingerprints failing on one workspace… */ cyclingMinCards: 3,
+    /** …within this window. */ cyclingWindowMs: 30 * 60000,
+    /** A workspace this many days old or older gets an alert, not a lock. */ youngDays: 14,
+    /** How long a failed charge is kept on the workspace's document. */ retainMs: 24 * 60 * 60000,
+    /** And at most this many of them. */ maxFailures: 30,
+    /** After an alert-only decision, how long before another may be raised. */ alertWindowMs: 24 * 60 * 60000,
+    /** How long one run may hold a claim before another may take it over. */ claimLeaseMs: 10 * 60000
+};
+export const PAYMENT_FRAUD_HOLD_TRIGGER_LABELS = {
+    'radar-blocked': 'Radar blocked a payment at highest risk',
+    'stripe-reported-fraud': 'Stripe reported a payment as fraudulent',
+    'card-cycling': `${PAYMENT_FRAUD_HOLD.cyclingMinCards} or more different cards failed within ${PAYMENT_FRAUD_HOLD.cyclingWindowMs / 60000} minutes`,
+    'early-fraud-warning': 'An issuer sent an early fraud warning',
+    'radar-review': 'Radar opened a review'
+};
+function text(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function refOf(value) {
+    if (typeof value === 'string') return value || null;
+    return text(value == null ? void 0 : value.id);
+}
+/** A Stripe Charge object → the evidence kept about it. Pure. */ export function chargeEvidence(charge, atMs) {
+    var _ref, _ref1, _ref2, _ref3;
+    var _charge_payment_method_details, _charge_fraud_details, _card_checks, _card_checks1;
+    const card = (_ref = charge == null ? void 0 : (_charge_payment_method_details = charge.payment_method_details) == null ? void 0 : _charge_payment_method_details.card) != null ? _ref : {};
+    const outcome = (_ref1 = charge == null ? void 0 : charge.outcome) != null ? _ref1 : {};
+    const amount = Number(charge == null ? void 0 : charge.amount);
+    const score = Number(outcome == null ? void 0 : outcome.risk_score);
+    return {
+        chargeId: String((_ref2 = charge == null ? void 0 : charge.id) != null ? _ref2 : ''),
+        paymentIntentId: refOf(charge == null ? void 0 : charge.payment_intent),
+        invoiceId: refOf(charge == null ? void 0 : charge.invoice),
+        fingerprint: text(card == null ? void 0 : card.fingerprint),
+        cardCountry: text(card == null ? void 0 : card.country),
+        cardBrand: text(card == null ? void 0 : card.brand),
+        last4: text(card == null ? void 0 : card.last4),
+        outcomeType: text(outcome == null ? void 0 : outcome.type),
+        outcomeReason: text(outcome == null ? void 0 : outcome.reason),
+        riskLevel: text(outcome == null ? void 0 : outcome.risk_level),
+        riskScore: (outcome == null ? void 0 : outcome.risk_score) == null || !Number.isFinite(score) ? null : score,
+        stripeReport: text(charge == null ? void 0 : (_charge_fraud_details = charge.fraud_details) == null ? void 0 : _charge_fraud_details.stripe_report),
+        failureCode: text(charge == null ? void 0 : charge.failure_code),
+        declineCode: text(outcome == null ? void 0 : outcome.network_decline_code),
+        postalCheck: text(card == null ? void 0 : (_card_checks = card.checks) == null ? void 0 : _card_checks.address_postal_code_check),
+        cvcCheck: text(card == null ? void 0 : (_card_checks1 = card.checks) == null ? void 0 : _card_checks1.cvc_check),
+        amountCents: Number.isFinite(amount) ? amount : null,
+        currency: String((_ref3 = charge == null ? void 0 : charge.currency) != null ? _ref3 : 'usd'),
+        atMs
+    };
+}
+/**
+ * Does this ONE charge ask for a hold? Stripe's own fraud report first —
+ * it is the stronger statement — then a Radar block at `highest` risk. A
+ * block at `elevated` risk, or by a custom rule, is not enough on its own:
+ * those catch real customers too, and card cycling is what catches the
+ * tester behind them.
+ */ export function chargeFraudTrigger(evidence) {
+    if (evidence.stripeReport === 'fraudulent') return 'stripe-reported-fraud';
+    if (evidence.outcomeType === 'blocked' && evidence.riskLevel === 'highest') return 'radar-blocked';
+    return null;
+}
+/** Whether the failures show card cycling at `nowMs`. Pure. */ export function cardCyclingPattern(failures, nowMs) {
+    const since = nowMs - PAYMENT_FRAUD_HOLD.cyclingWindowMs;
+    const fingerprints = [
+        ...new Set(failures.filter((entry)=>entry.atMs >= since && entry.atMs <= nowMs && entry.fingerprint).map((entry)=>entry.fingerprint))
+    ];
+    return {
+        matched: fingerprints.length >= PAYMENT_FRAUD_HOLD.cyclingMinCards,
+        fingerprints
+    };
+}
+/**
+ * The guards (AGL-3767): a workspace 14+ days old, or one that has paid an
+ * invoice other than with the flagged charges, is alerted about and never
+ * locked automatically. An unreadable creation date is an existing customer,
+ * as everywhere else on the platform (`isYoungWorkspaceAge`). Pure.
+ */ export function paymentFraudHoldGuard(input) {
+    if (input.hasPaidInvoice) {
+        return {
+            lock: false,
+            reason: 'The workspace has paid an invoice before, so a person decides.'
+        };
+    }
+    if (typeof input.ageDays !== 'number' || !Number.isFinite(input.ageDays) || input.ageDays >= PAYMENT_FRAUD_HOLD.youngDays) {
+        return {
+            lock: false,
+            reason: input.ageDays === null || !Number.isFinite(input.ageDays) ? 'The workspace has no readable creation date, so it is treated as an existing customer.' : `The workspace is ${Math.floor(input.ageDays)} days old (${PAYMENT_FRAUD_HOLD.youngDays} or more), so a person decides.`
+        };
+    }
+    return {
+        lock: true,
+        reason: null
+    };
+}
+/**
+ * Has this workspace paid an invoice with any charge OTHER than the flagged
+ * ones? Read off `platformRevenue`, which holds a row for every paid
+ * subscription invoice (AGL-1811). The flagged charges are excluded because
+ * a stolen card that went through has "paid" too — an early fraud warning
+ * only ever arrives on a charge that succeeded.
+ */ export async function hasPaidOtherInvoice(firestore, orgId, flagged) {
+    const rows = await firestore.collection('platformRevenue').where('orgId', '==', orgId).limit(25).get();
+    return rows.docs.some((row)=>{
+        if (!(Number(row.get('grossCents')) > 0)) return false;
+        const chargeId = text(row.get('chargeId'));
+        const paymentIntentId = text(row.get('paymentIntentId'));
+        if (chargeId && flagged.chargeIds.includes(chargeId)) return false;
+        if (paymentIntentId && flagged.paymentIntentIds.includes(paymentIntentId)) return false;
+        return true;
+    });
+}
+function holdRef(firestore, orgId) {
+    return firestore.collection(PAYMENT_FRAUD_HOLD_COLLECTION).doc(orgId);
+}
+/**
+ * Keep one failed charge on its workspace's document and say whether the
+ * failures now show card cycling. Idempotent on the charge id: a redelivery
+ * adds nothing and reports `added: false`.
+ */ export async function recordWorkspaceChargeFailure(firestore, orgId, evidence, nowMs = Date.now()) {
+    const ref = holdRef(firestore, orgId);
+    return firestore.runTransaction(async (transaction)=>{
+        var _snapshot_data, _stored_state;
+        const snapshot = await transaction.get(ref);
+        const stored = snapshot.exists ? (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {} : {};
+        const previous = Array.isArray(stored.failures) ? stored.failures : [];
+        const state = (_stored_state = stored.state) != null ? _stored_state : 'watching';
+        const added = !previous.some((entry)=>entry.chargeId === evidence.chargeId);
+        const failures = added ? [
+            ...previous.filter((entry)=>entry.atMs >= nowMs - PAYMENT_FRAUD_HOLD.retainMs),
+            evidence
+        ].slice(-PAYMENT_FRAUD_HOLD.maxFailures) : previous;
+        if (added) {
+            transaction.set(ref, _extends({
+                orgId,
+                failures
+            }, snapshot.exists ? {} : {
+                state: 'watching'
+            }, {
+                updatedAtMs: nowMs
+            }), {
+                merge: true
+            });
+        }
+        return {
+            added,
+            cycling: cardCyclingPattern(failures, nowMs),
+            recent: failures.filter((entry)=>entry.atMs >= nowMs - PAYMENT_FRAUD_HOLD.cyclingWindowMs),
+            state
+        };
+    });
+}
+/**
+ * Claim the workspace's hold for this run. Answers `claimed: false` with the
+ * reason when the hold is already placed, another run is placing it inside
+ * its lease, or a guard already alerted inside the alert window — which is
+ * what makes a redelivery, or the next card in a burst, a no-op.
+ */ export async function claimPaymentFraudHold(firestore, orgId, trigger, nowMs = Date.now()) {
+    const ref = holdRef(firestore, orgId);
+    return firestore.runTransaction(async (transaction)=>{
+        var _snapshot_data, _record_state;
+        const snapshot = await transaction.get(ref);
+        const record = snapshot.exists ? (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {} : {};
+        const state = (_record_state = record.state) != null ? _record_state : 'watching';
+        if (state === 'held') return {
+            claimed: false,
+            reason: 'held'
+        };
+        if (state === 'skipped') return {
+            claimed: false,
+            reason: 'skipped'
+        };
+        if (state === 'placing' && typeof record.claimedAtMs === 'number' && nowMs - record.claimedAtMs < PAYMENT_FRAUD_HOLD.claimLeaseMs) {
+            return {
+                claimed: false,
+                reason: 'placing'
+            };
+        }
+        if (state === 'alerted' && typeof record.alertedAtMs === 'number' && nowMs - record.alertedAtMs < PAYMENT_FRAUD_HOLD.alertWindowMs) {
+            return {
+                claimed: false,
+                reason: 'alerted'
+            };
+        }
+        transaction.set(ref, {
+            orgId,
+            state: 'placing',
+            claimedAtMs: nowMs,
+            trigger,
+            updatedAtMs: nowMs
+        }, {
+            merge: true
+        });
+        return {
+            claimed: true,
+            reason: null
+        };
+    });
+}
+/** Record what the run did with a claimed hold. */ export async function settlePaymentFraudHold(firestore, orgId, state, fields, nowMs = Date.now()) {
+    await holdRef(firestore, orgId).set(_extends({
+        state
+    }, state === 'held' ? {
+        heldAtMs: nowMs
+    } : {}, state === 'alerted' ? {
+        alertedAtMs: nowMs
+    } : {}, fields.reviewId !== undefined ? {
+        reviewId: fields.reviewId
+    } : {}, fields.outcome !== undefined ? {
+        outcome: fields.outcome
+    } : {}, {
+        claimedAtMs: null,
+        updatedAtMs: nowMs
+    }), {
+        merge: true
+    });
+}
+/**
+ * Is this workspace on an automatic payment-fraud hold? What collapses the
+ * per-attempt `staff.paymentFailed` pings: once a workspace is held, the
+ * hold's one alert is the news, and each further declined card is not.
+ */ export async function isPaymentFraudHeld(firestore, orgId) {
+    const snapshot = await holdRef(firestore, orgId).get();
+    return snapshot.exists && snapshot.get('state') === 'held';
+}
+
+//# sourceMappingURL=payment-fraud-hold.js.map

package/src/lib/server/payment-fraud-hold.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/payment-fraud-hold.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 * THE PAYMENT-FRAUD HOLD: THE DURABLE HALF (AGL-3767).\n *\n * When Stripe says a workspace's OWN subscription payment is fraud, the\n * workspace is put on an automatic `security` hold: the workspace and each\n * of its sites locked as a takedown, its subscriptions canceled, staff\n * alerted once. Never `abuse`: that is a permanent ban, and Stripe's verdict\n * is a strong signal about a card, not a decision about a person. Staff\n * re-place the hold as `abuse` on Staff → Lockdown, or lift it.\n *\n * Three triggers, all on charges that resolve to a workspace through the\n * `stripeCustomers` index — never a site's sale on a connected account:\n *\n *  1. one failed charge Radar BLOCKED at `highest` risk, or that Stripe\n *     itself reported as `fraudulent` ({@link chargeFraudTrigger});\n *  2. CARD CYCLING: failed charges on {@link PAYMENT_FRAUD_HOLD}'s\n *     `cyclingMinCards` or more distinct card fingerprints within its\n *     `cyclingWindowMs` ({@link cardCyclingPattern}). A real customer whose\n *     card is declined tries it again, or tries one other card; three\n *     different cards inside half an hour on one invoice is a card tester\n *     working through a list. The workspace that prompted this (2026-10-13)\n *     put four cards on one $56 invoice in two minutes;\n *  3. an issuer's early fraud warning or a Radar review on the workspace's\n *     charge — filed by `payment-fraud-signal.ts`, which asks for the hold.\n *\n * Two guards turn the hold into an alert only: a workspace 14 or more days\n * old, or one that has paid an invoice with any charge other than the\n * flagged ones. Those are customers with a history, and a person decides.\n *\n * This module is the state: one `paymentFraudHolds/{orgId}` document holding\n * the workspace's recent failed charges (what card cycling counts) and the\n * hold's own state, claimed in a transaction so a Stripe redelivery, or two\n * events about one attempt arriving together, place one hold and raise one\n * alert. The locks themselves are the console's\n * (`apps/console/utils/server/payment-fraud-hold.ts`), because only the\n * console holds the lockdown cores.\n *=========================================*/\n\n/** One document per workspace. Admin SDK only; no client rule opens it. */\nexport const PAYMENT_FRAUD_HOLD_COLLECTION = 'paymentFraudHolds'\n\n/** The actor every automatic payment-fraud lock's audit rows name. */\nexport const PAYMENT_FRAUD_HOLD_ACTOR_UID = 'system:payment-fraud'\n\n/** The lock reason the hold places. Never `abuse`: see the module header. */\nexport const PAYMENT_FRAUD_HOLD_LOCK_REASON = 'security'\n\nexport const PAYMENT_FRAUD_HOLD = {\n  /** Distinct card fingerprints failing on one workspace… */\n  cyclingMinCards: 3,\n  /** …within this window. */\n  cyclingWindowMs: 30 * 60_000,\n  /** A workspace this many days old or older gets an alert, not a lock. */\n  youngDays: 14,\n  /** How long a failed charge is kept on the workspace's document. */\n  retainMs: 24 * 60 * 60_000,\n  /** And at most this many of them. */\n  maxFailures: 30,\n  /** After an alert-only decision, how long before another may be raised. */\n  alertWindowMs: 24 * 60 * 60_000,\n  /** How long one run may hold a claim before another may take it over. */\n  claimLeaseMs: 10 * 60_000,\n} as const\n\n/** Why a hold was asked for. */\nexport type PaymentFraudHoldTrigger =\n  | 'radar-blocked'\n  | 'stripe-reported-fraud'\n  | 'card-cycling'\n  | 'early-fraud-warning'\n  | 'radar-review'\n\nexport const PAYMENT_FRAUD_HOLD_TRIGGER_LABELS: Record<PaymentFraudHoldTrigger, string> = {\n  'radar-blocked': 'Radar blocked a payment at highest risk',\n  'stripe-reported-fraud': 'Stripe reported a payment as fraudulent',\n  'card-cycling': `${PAYMENT_FRAUD_HOLD.cyclingMinCards} or more different cards failed within ${\n    PAYMENT_FRAUD_HOLD.cyclingWindowMs / 60_000\n  } minutes`,\n  'early-fraud-warning': 'An issuer sent an early fraud warning',\n  'radar-review': 'Radar opened a review',\n}\n\n/** What one charge says about the card, kept as evidence. */\nexport interface PaymentFraudChargeEvidence {\n  chargeId: string\n  paymentIntentId: string | null\n  invoiceId: string | null\n  /** The card's fingerprint: the same card number always has the same one. */\n  fingerprint: string | null\n  cardCountry: string | null\n  cardBrand: string | null\n  last4: string | null\n  /** `outcome.type`: `blocked`, `issuer_declined`, `authorized`… */\n  outcomeType: string | null\n  /** `outcome.reason`: `highest_risk_level`, `rule`… */\n  outcomeReason: string | null\n  riskLevel: string | null\n  riskScore: number | null\n  /** `fraud_details.stripe_report`. */\n  stripeReport: string | null\n  failureCode: string | null\n  declineCode: string | null\n  postalCheck: string | null\n  cvcCheck: string | null\n  amountCents: number | null\n  currency: string\n  atMs: number\n}\n\nfunction text(value: unknown): string | null {\n  return typeof value === 'string' && value.trim() ? value.trim() : null\n}\n\nfunction refOf(value: unknown): string | null {\n  if (typeof value === 'string') return value || null\n  return text((value as { id?: unknown } | null)?.id)\n}\n\n/** A Stripe Charge object → the evidence kept about it. Pure. */\nexport function chargeEvidence(charge: any, atMs: number): PaymentFraudChargeEvidence {\n  const card = charge?.payment_method_details?.card ?? {}\n  const outcome = charge?.outcome ?? {}\n  const amount = Number(charge?.amount)\n  const score = Number(outcome?.risk_score)\n  return {\n    chargeId: String(charge?.id ?? ''),\n    paymentIntentId: refOf(charge?.payment_intent),\n    invoiceId: refOf(charge?.invoice),\n    fingerprint: text(card?.fingerprint),\n    cardCountry: text(card?.country),\n    cardBrand: text(card?.brand),\n    last4: text(card?.last4),\n    outcomeType: text(outcome?.type),\n    outcomeReason: text(outcome?.reason),\n    riskLevel: text(outcome?.risk_level),\n    riskScore: outcome?.risk_score == null || !Number.isFinite(score) ? null : score,\n    stripeReport: text(charge?.fraud_details?.stripe_report),\n    failureCode: text(charge?.failure_code),\n    declineCode: text(outcome?.network_decline_code),\n    postalCheck: text(card?.checks?.address_postal_code_check),\n    cvcCheck: text(card?.checks?.cvc_check),\n    amountCents: Number.isFinite(amount) ? amount : null,\n    currency: String(charge?.currency ?? 'usd'),\n    atMs,\n  }\n}\n\n/**\n * Does this ONE charge ask for a hold? Stripe's own fraud report first —\n * it is the stronger statement — then a Radar block at `highest` risk. A\n * block at `elevated` risk, or by a custom rule, is not enough on its own:\n * those catch real customers too, and card cycling is what catches the\n * tester behind them.\n */\nexport function chargeFraudTrigger(\n  evidence: Pick<PaymentFraudChargeEvidence, 'stripeReport' | 'outcomeType' | 'riskLevel'>,\n): PaymentFraudHoldTrigger | null {\n  if (evidence.stripeReport === 'fraudulent') return 'stripe-reported-fraud'\n  if (evidence.outcomeType === 'blocked' && evidence.riskLevel === 'highest') return 'radar-blocked'\n  return null\n}\n\n/** Whether the failures show card cycling at `nowMs`. Pure. */\nexport function cardCyclingPattern(\n  failures: readonly PaymentFraudChargeEvidence[],\n  nowMs: number,\n): { matched: boolean; fingerprints: string[] } {\n  const since = nowMs - PAYMENT_FRAUD_HOLD.cyclingWindowMs\n  const fingerprints = [\n    ...new Set(\n      failures\n        .filter((entry) => entry.atMs >= since && entry.atMs <= nowMs && entry.fingerprint)\n        .map((entry) => entry.fingerprint as string),\n    ),\n  ]\n  return { matched: fingerprints.length >= PAYMENT_FRAUD_HOLD.cyclingMinCards, fingerprints }\n}\n\n/**\n * The guards (AGL-3767): a workspace 14+ days old, or one that has paid an\n * invoice other than with the flagged charges, is alerted about and never\n * locked automatically. An unreadable creation date is an existing customer,\n * as everywhere else on the platform (`isYoungWorkspaceAge`). Pure.\n */\nexport function paymentFraudHoldGuard(input: {\n  ageDays: number | null\n  hasPaidInvoice: boolean\n}): { lock: boolean; reason: string | null } {\n  if (input.hasPaidInvoice) {\n    return { lock: false, reason: 'The workspace has paid an invoice before, so a person decides.' }\n  }\n  if (\n    typeof input.ageDays !== 'number' ||\n    !Number.isFinite(input.ageDays) ||\n    input.ageDays >= PAYMENT_FRAUD_HOLD.youngDays\n  ) {\n    return {\n      lock: false,\n      reason:\n        input.ageDays === null || !Number.isFinite(input.ageDays)\n          ? 'The workspace has no readable creation date, so it is treated as an existing customer.'\n          : `The workspace is ${Math.floor(input.ageDays)} days old (${PAYMENT_FRAUD_HOLD.youngDays} or more), so a person decides.`,\n    }\n  }\n  return { lock: true, reason: null }\n}\n\n/**\n * Has this workspace paid an invoice with any charge OTHER than the flagged\n * ones? Read off `platformRevenue`, which holds a row for every paid\n * subscription invoice (AGL-1811). The flagged charges are excluded because\n * a stolen card that went through has \"paid\" too — an early fraud warning\n * only ever arrives on a charge that succeeded.\n */\nexport async function hasPaidOtherInvoice(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  flagged: { chargeIds: readonly string[]; paymentIntentIds: readonly string[] },\n): Promise<boolean> {\n  const rows = await firestore\n    .collection('platformRevenue')\n    .where('orgId', '==', orgId)\n    .limit(25)\n    .get()\n  return rows.docs.some((row) => {\n    if (!(Number(row.get('grossCents')) > 0)) return false\n    const chargeId = text(row.get('chargeId'))\n    const paymentIntentId = text(row.get('paymentIntentId'))\n    if (chargeId && flagged.chargeIds.includes(chargeId)) return false\n    if (paymentIntentId && flagged.paymentIntentIds.includes(paymentIntentId)) return false\n    return true\n  })\n}\n\n/**\n * - `watching` — failures recorded, nothing asked for.\n * - `placing` — a run claimed the hold.\n * - `held` — locks placed. Never placed again automatically.\n * - `alerted` — a guard made it an alert only; another alert waits out the window.\n * - `skipped` — never held: the house, a staff-owned workspace, one that is gone.\n */\nexport type PaymentFraudHoldState = 'watching' | 'placing' | 'held' | 'alerted' | 'skipped'\n\nexport interface PaymentFraudHoldRecord {\n  orgId: string\n  state: PaymentFraudHoldState\n  failures: PaymentFraudChargeEvidence[]\n  claimedAtMs?: number | null\n  heldAtMs?: number | null\n  alertedAtMs?: number | null\n  trigger?: PaymentFraudHoldTrigger | null\n  reviewId?: string | null\n  outcome?: Record<string, unknown> | null\n  updatedAtMs?: number\n}\n\nfunction holdRef(firestore: FirebaseFirestore.Firestore, orgId: string) {\n  return firestore.collection(PAYMENT_FRAUD_HOLD_COLLECTION).doc(orgId)\n}\n\n/**\n * Keep one failed charge on its workspace's document and say whether the\n * failures now show card cycling. Idempotent on the charge id: a redelivery\n * adds nothing and reports `added: false`.\n */\nexport async function recordWorkspaceChargeFailure(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  evidence: PaymentFraudChargeEvidence,\n  nowMs: number = Date.now(),\n): Promise<{\n  added: boolean\n  cycling: { matched: boolean; fingerprints: string[] }\n  /** The failures inside the cycling window, oldest first, this one included. */\n  recent: PaymentFraudChargeEvidence[]\n  state: PaymentFraudHoldState\n}> {\n  const ref = holdRef(firestore, orgId)\n  return firestore.runTransaction(async (transaction) => {\n    const snapshot = await transaction.get(ref)\n    const stored = (snapshot.exists ? (snapshot.data() ?? {}) : {}) as Partial<PaymentFraudHoldRecord>\n    const previous = Array.isArray(stored.failures) ? stored.failures : []\n    const state = (stored.state ?? 'watching') as PaymentFraudHoldState\n    const added = !previous.some((entry) => entry.chargeId === evidence.chargeId)\n    const failures = added\n      ? [...previous.filter((entry) => entry.atMs >= nowMs - PAYMENT_FRAUD_HOLD.retainMs), evidence].slice(\n          -PAYMENT_FRAUD_HOLD.maxFailures,\n        )\n      : previous\n    if (added) {\n      transaction.set(\n        ref,\n        {\n          orgId,\n          failures,\n          ...(snapshot.exists ? {} : { state: 'watching' }),\n          updatedAtMs: nowMs,\n        },\n        { merge: true },\n      )\n    }\n    return {\n      added,\n      cycling: cardCyclingPattern(failures, nowMs),\n      recent: failures.filter((entry) => entry.atMs >= nowMs - PAYMENT_FRAUD_HOLD.cyclingWindowMs),\n      state,\n    }\n  })\n}\n\n/**\n * Claim the workspace's hold for this run. Answers `claimed: false` with the\n * reason when the hold is already placed, another run is placing it inside\n * its lease, or a guard already alerted inside the alert window — which is\n * what makes a redelivery, or the next card in a burst, a no-op.\n */\nexport async function claimPaymentFraudHold(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  trigger: PaymentFraudHoldTrigger,\n  nowMs: number = Date.now(),\n): Promise<{\n  claimed: boolean\n  /** Why not, when `claimed` is false. */\n  reason: 'held' | 'placing' | 'alerted' | 'skipped' | null\n}> {\n  const ref = holdRef(firestore, orgId)\n  return firestore.runTransaction(async (transaction) => {\n    const snapshot = await transaction.get(ref)\n    const record = (snapshot.exists ? (snapshot.data() ?? {}) : {}) as Partial<PaymentFraudHoldRecord>\n    const state = (record.state ?? 'watching') as PaymentFraudHoldState\n    if (state === 'held') return { claimed: false as const, reason: 'held' as const }\n    if (state === 'skipped') return { claimed: false as const, reason: 'skipped' as const }\n    if (\n      state === 'placing' &&\n      typeof record.claimedAtMs === 'number' &&\n      nowMs - record.claimedAtMs < PAYMENT_FRAUD_HOLD.claimLeaseMs\n    ) {\n      return { claimed: false as const, reason: 'placing' as const }\n    }\n    if (\n      state === 'alerted' &&\n      typeof record.alertedAtMs === 'number' &&\n      nowMs - record.alertedAtMs < PAYMENT_FRAUD_HOLD.alertWindowMs\n    ) {\n      return { claimed: false as const, reason: 'alerted' as const }\n    }\n    transaction.set(\n      ref,\n      { orgId, state: 'placing', claimedAtMs: nowMs, trigger, updatedAtMs: nowMs },\n      { merge: true },\n    )\n    return { claimed: true, reason: null }\n  })\n}\n\n/** Record what the run did with a claimed hold. */\nexport async function settlePaymentFraudHold(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  state: 'held' | 'alerted' | 'skipped' | 'watching',\n  fields: { reviewId?: string | null; outcome?: Record<string, unknown> | null },\n  nowMs: number = Date.now(),\n): Promise<void> {\n  await holdRef(firestore, orgId).set(\n    {\n      state,\n      ...(state === 'held' ? { heldAtMs: nowMs } : {}),\n      ...(state === 'alerted' ? { alertedAtMs: nowMs } : {}),\n      ...(fields.reviewId !== undefined ? { reviewId: fields.reviewId } : {}),\n      ...(fields.outcome !== undefined ? { outcome: fields.outcome } : {}),\n      claimedAtMs: null,\n      updatedAtMs: nowMs,\n    },\n    { merge: true },\n  )\n}\n\n/**\n * Is this workspace on an automatic payment-fraud hold? What collapses the\n * per-attempt `staff.paymentFailed` pings: once a workspace is held, the\n * hold's one alert is the news, and each further declined card is not.\n */\nexport async function isPaymentFraudHeld(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n): Promise<boolean> {\n  const snapshot = await holdRef(firestore, orgId).get()\n  return snapshot.exists && snapshot.get('state') === 'held'\n}\n"],"names":["PAYMENT_FRAUD_HOLD_COLLECTION","PAYMENT_FRAUD_HOLD_ACTOR_UID","PAYMENT_FRAUD_HOLD_LOCK_REASON","PAYMENT_FRAUD_HOLD","cyclingMinCards","cyclingWindowMs","youngDays","retainMs","maxFailures","alertWindowMs","claimLeaseMs","PAYMENT_FRAUD_HOLD_TRIGGER_LABELS","text","value","trim","refOf","id","chargeEvidence","charge","atMs","card","payment_method_details","outcome","amount","Number","score","risk_score","chargeId","String","paymentIntentId","payment_intent","invoiceId","invoice","fingerprint","cardCountry","country","cardBrand","brand","last4","outcomeType","type","outcomeReason","reason","riskLevel","risk_level","riskScore","isFinite","stripeReport","fraud_details","stripe_report","failureCode","failure_code","declineCode","network_decline_code","postalCheck","checks","address_postal_code_check","cvcCheck","cvc_check","amountCents","currency","chargeFraudTrigger","evidence","cardCyclingPattern","failures","nowMs","since","fingerprints","Set","filter","entry","map","matched","length","paymentFraudHoldGuard","input","hasPaidInvoice","lock","ageDays","Math","floor","hasPaidOtherInvoice","firestore","orgId","flagged","rows","collection","where","limit","get","docs","some","row","chargeIds","includes","paymentIntentIds","holdRef","doc","recordWorkspaceChargeFailure","Date","now","ref","runTransaction","transaction","snapshot","stored","exists","data","previous","Array","isArray","state","added","slice","set","updatedAtMs","merge","cycling","recent","claimPaymentFraudHold","trigger","record","claimed","claimedAtMs","alertedAtMs","settlePaymentFraudHold","fields","heldAtMs","reviewId","undefined","isPaymentFraudHeld"],"mappings":"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"}

package/src/lib/server/payment-fraud-signal.d.ts

@@ -21,6 +21,21 @@ import type { RiskEventInput } from './risk-notice';
  * handle, so the webhook's spec substitutes it with the barrel.
  */
 export type RiskNotifier = (input: RiskEventInput) => Promise<unknown>;
+/**
+ * What the platform did, by itself, about a workspace's flagged payment
+ * (AGL-3767): `summary` is the line staff read on the row, `record` the
+ * structured half kept beside it.
+ */
+export interface WorkspaceSignalResponse {
+    summary: string;
+    record: Record<string, unknown>;
+}
+/** The console's answer to a new signal on a workspace's own charge. */
+export type WorkspaceSignalResponder = (input: {
+    signal: PaymentFraudSignal;
+    reviewId: string;
+    reference: string;
+}) => Promise<WorkspaceSignalResponse | null>;
 /** Which Stripe signal this is. */
 export type PaymentFraudSignalKind = 'early-fraud-warning' | 'radar-review' | 'dispute';
 /** The Stripe object type each signal arrives as, for the queue's text. */
@@ -144,11 +159,21 @@ export declare function recordPaymentFraudSignal(signal: PaymentFraudSignal, dep
     firestore: FirebaseFirestore.Firestore;
     notifyRisk: RiskNotifier;
     nowMs?: number;
+    /**
+     * What the platform does about a NEW early fraud warning or Radar review
+     * on a workspace's own charge (AGL-3767): the console's refund and
+     * automatic security hold. Called once per signal, never for a
+     * redelivery; whatever it answers is written onto the row as
+     * `automatedResponse`, with its `summary` appended to the row's text.
+     * Absent, the row is filed exactly as before.
+     */
+    respond?: WorkspaceSignalResponder;
 }): Promise<{
     reviewId: string;
     reference: string;
     first: boolean;
     reopened: boolean;
+    response: WorkspaceSignalResponse | null;
 }>;
 export declare const SELLER_FRAUD_PATTERN: {
     /** Distinct charges with an early fraud warning or a dispute. */