@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/guardrails/quota.js

@@ -0,0 +1,80 @@
+import { resolveGuardrailPolicy } from './policy.js';
+import { TheoremError } from './theorem-error.js';
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost']);
+const slots = new Map();
+function utcDay(now) {
+    return new Date(now).toISOString().slice(0, 10);
+}
+function isLoopback(peer) {
+    return LOOPBACK.has(peer);
+}
+function cfConnectingIp(req) {
+    return req.headers.get('cf-connecting-ip')?.trim() ?? '';
+}
+function slotKey(profileId, ip) {
+    return `${profileId}:${ip}`;
+}
+/** Returns whether a local request lacks the proxy header needed for quota identity. */
+function skipQuota(peer, req) {
+    return isLoopback(peer) && !cfConnectingIp(req);
+}
+/** Resolves the client identity, preferring Cloudflare's header for local peers. */
+function clientIp(peer, req) {
+    if (isLoopback(peer)) {
+        const cf = cfConnectingIp(req);
+        if (cf) {
+            return cf;
+        }
+    }
+    if (peer) {
+        return peer;
+    }
+    return 'unknown';
+}
+/**
+ * Reserves one profile-and-client daily quota slot. The reservation stays busy
+ * until `releaseSlot` is called, preventing concurrent turns from overspending.
+ */
+function takeSlot(profile, ip, now) {
+    const quota = resolveGuardrailPolicy(profile.guardrails).quota;
+    if (!quota) {
+        return 'not_configured';
+    }
+    const day = utcDay(now);
+    const key = slotKey(profile.id, ip);
+    let slot = slots.get(key);
+    if (!slot || slot.day !== day) {
+        slot = { day, count: 0, busy: false };
+        slots.set(key, slot);
+    }
+    if (slot.busy) {
+        return 'busy';
+    }
+    if (slot.count >= quota.perDay) {
+        return 'quota';
+    }
+    slot.busy = true;
+    slot.count += 1;
+    return 'ok';
+}
+/** Releases an active quota reservation without decrementing its daily count. */
+function releaseSlot(profile, ip) {
+    const slot = slots.get(slotKey(profile.id, ip));
+    if (slot) {
+        slot.busy = false;
+    }
+}
+/** `undefined` when the profile has no quota configured. */
+function quotaExhausted(profile) {
+    const quota = resolveGuardrailPolicy(profile.guardrails).quota;
+    if (!quota) {
+        return undefined;
+    }
+    return new TheoremError('rate_limit', `${profile.id} used its daily quota of ${quota.perDay} turns`, // labels-exempt: internal diagnostic; the user reads the copy key
+    { copy: { key: 'quota.exhausted', params: { perDay: quota.perDay } } });
+}
+/** Clears all process-local quota counters; intended for tests or host resets. */
+function resetSlots() {
+    slots.clear();
+}
+export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot };

package/esm/src/guardrails/rules.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Every rule id Theorem's own guardrails report, in one place. The trace
+ * catalog describes each one, and its description map is keyed by
+ * {@link GuardrailRule}, so a new id fails typecheck until it is described.
+ * A host's egress `enforce` hook may report ids of its own; those are not here.
+ *
+ * @module
+ */
+/** What a detector found, the same id at every boundary; the event names the boundary. */
+export declare const DETECT_RULES: {
+    readonly ids: "detect.ids";
+    readonly financial: "detect.financial";
+    readonly network: "detect.network";
+    readonly credentials: "detect.credentials";
+    readonly injection: "detect.injection";
+    readonly tool_instructions: "detect.tool_instructions";
+    readonly canary_leak: "detect.canary_leak";
+    readonly prompt_leak: "detect.prompt_leak";
+    readonly marker_leak: "detect.marker_leak";
+    readonly ungiven_images: "detect.ungiven_images";
+    readonly ungiven_links: "detect.ungiven_links";
+    readonly tool_leak: "detect.tool_leak";
+};
+/** The rule a match of `key` reports: a detector of Theorem's, or the id of one of the host's own (`detect.acme.record`). */
+export declare function detectRule(key: string): string;
+/** What stops a reply besides a detector's match. */
+export declare const EGRESS_RULES: {
+    /**
+     * A provider-side built-in tool carried the canary or the system prompt. It
+     * ran before Theorem saw it: the data already left, so this is an incident.
+     */
+    readonly providerToolLeak: "egress.provider-tool-leak";
+    /** Payload could not be rendered for inspection — released output is unverified. */
+    readonly unscannable: "egress.unscannable";
+};
+/** A tool call refused for what the turn read before it. */
+export declare const TOOL_RULES: {
+    readonly taintedTurn: "tool_call.tainted-turn";
+    readonly steeredTurn: "tool_call.steered-turn";
+    readonly remoteDestination: "tool_call.remote-destination";
+};
+/** A tool's network target refused before any request was made. */
+export declare const NETWORK_RULES: {
+    readonly blocked: "network.blocked";
+};
+/** A rule id Theorem's own guardrails report. */
+export type GuardrailRule = (typeof DETECT_RULES)[keyof typeof DETECT_RULES] | (typeof EGRESS_RULES)[keyof typeof EGRESS_RULES] | (typeof TOOL_RULES)[keyof typeof TOOL_RULES] | (typeof NETWORK_RULES)[keyof typeof NETWORK_RULES];

package/esm/src/guardrails/rules.js

@@ -0,0 +1,47 @@
+/**
+ * Every rule id Theorem's own guardrails report, in one place. The trace
+ * catalog describes each one, and its description map is keyed by
+ * {@link GuardrailRule}, so a new id fails typecheck until it is described.
+ * A host's egress `enforce` hook may report ids of its own; those are not here.
+ *
+ * @module
+ */
+/** What a detector found, the same id at every boundary; the event names the boundary. */
+export const DETECT_RULES = {
+    ids: 'detect.ids',
+    financial: 'detect.financial',
+    network: 'detect.network',
+    credentials: 'detect.credentials',
+    injection: 'detect.injection',
+    tool_instructions: 'detect.tool_instructions',
+    canary_leak: 'detect.canary_leak',
+    prompt_leak: 'detect.prompt_leak',
+    marker_leak: 'detect.marker_leak',
+    ungiven_images: 'detect.ungiven_images',
+    ungiven_links: 'detect.ungiven_links',
+    tool_leak: 'detect.tool_leak',
+};
+/** The rule a match of `key` reports: a detector of Theorem's, or the id of one of the host's own (`detect.acme.record`). */
+export function detectRule(key) {
+    return `detect.${key}`;
+}
+/** What stops a reply besides a detector's match. */
+export const EGRESS_RULES = {
+    /**
+     * A provider-side built-in tool carried the canary or the system prompt. It
+     * ran before Theorem saw it: the data already left, so this is an incident.
+     */
+    providerToolLeak: 'egress.provider-tool-leak', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    /** Payload could not be rendered for inspection — released output is unverified. */
+    unscannable: 'egress.unscannable', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+};
+/** A tool call refused for what the turn read before it. */
+export const TOOL_RULES = {
+    taintedTurn: 'tool_call.tainted-turn',
+    steeredTurn: 'tool_call.steered-turn',
+    remoteDestination: 'tool_call.remote-destination',
+};
+/** A tool's network target refused before any request was made. */
+export const NETWORK_RULES = {
+    blocked: 'network.blocked',
+};

package/esm/src/guardrails/sanitize.d.ts

@@ -0,0 +1,40 @@
+import type { NormalizedTurnRequest, Profile, TurnContext, TurnEvent, TurnHistoryMessage, TurnRequest } from '../kernel/types.js';
+import { type Boundary } from './boundaries.js';
+import { type BoundaryReader } from './detect-at.js';
+import { TheoremError } from './theorem-error.js';
+import type { GuardrailEvent } from './types.js';
+/** A context package as the model reads it: text as written, anything else as JSON. */
+declare function contextText(value: unknown): string;
+/** Each sender's package read at the `context` boundary, with what was found there. */
+declare function sanitizeContext(context: TurnContext | undefined, readerFor: () => BoundaryReader): {
+    context: TurnContext | undefined;
+    events: GuardrailEvent[];
+    blocked: boolean;
+};
+/** The project id trimmed, or `undefined` when it is empty or has illegal characters. */
+declare function sanitizeProjectId(id: string | undefined): string | undefined;
+/**
+ * Exported because every path that injects messages into a turn needs it — turn
+ * history, and host steer injects mid-turn. A second copy would drift.
+ */
+declare function sanitizeHistory(history: TurnHistoryMessage[], reader: BoundaryReader): TurnHistoryMessage[];
+/** The error a turn ends on when a detector set to `block` matched at `boundary`. */
+declare function requestRefused(boundary: Boundary): TheoremError;
+/** A turn request read at each boundary it crosses. */
+interface SanitizedTurnRequest {
+    request: NormalizedTurnRequest;
+    /** One guardrail event for each boundary where something matched. */
+    events: TurnEvent[];
+    /** Set when a match blocks: the request does not reach the model, and the turn ends on this. */
+    refusal?: TheoremError;
+}
+/**
+ * `req.system` is host-assembled per turn — it interpolates retrieval and user
+ * data, so it is read at its own boundary. `identity.system` never reaches this
+ * path and stays verbatim.
+ */
+declare function sanitizeTurnRequestWithEvents(req: TurnRequest, profile: Profile): SanitizedTurnRequest;
+/** The turn request with its input cleaned under the profile's guardrails. Throws when a match blocks it. */
+declare function sanitizeTurnRequest(req: TurnRequest, profile: Profile): NormalizedTurnRequest;
+export type { SanitizedTurnRequest };
+export { contextText, requestRefused, sanitizeContext, sanitizeHistory, sanitizeProjectId, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, };

package/esm/src/guardrails/sanitize.js

@@ -0,0 +1,160 @@
+import { sanitizeTurnBlobs } from '../kernel/registry/attachments.js';
+import { CONTEXT_SENDERS } from '../kernel/schema.js';
+import { mapSystemPrompt } from '../kernel/system-parts.js';
+import { recordOf } from './boundaries.js';
+import { boundaryReader, detectEvent } from './detect-at.js';
+import { guardrailTurnEvent } from './events.js';
+import { resolveGuardrailPolicy } from './policy.js';
+import { TheoremError } from './theorem-error.js';
+/** The boundaries one turn request crosses, in the order their events are reported. */
+const REQUEST_BOUNDARIES = [
+    'user',
+    'slots',
+    'repair',
+    'attachment',
+    'voice',
+    'history',
+    'system',
+];
+function sanitizeSlots(slots, reader) {
+    if (!slots) {
+        return slots;
+    }
+    return Object.fromEntries(Object.entries(slots).map(([key, value]) => [key, reader.read(value)]));
+}
+/** The browser's context is the visitor's to change; the host's is built by its own code, like turn system text. */
+const CONTEXT_TRUST = {
+    client: 'untrusted',
+    server: 'assembled',
+};
+/** A context package as the model reads it: text as written, anything else as JSON. */
+function contextText(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+/** Each sender's package read at the `context` boundary, with what was found there. */
+function sanitizeContext(context, readerFor) {
+    const events = [];
+    let blocked = false;
+    if (!context)
+        return { context, events, blocked };
+    const read = {};
+    for (const sender of CONTEXT_SENDERS) {
+        const value = context[sender];
+        if (value === undefined)
+            continue;
+        const reader = readerFor();
+        read[sender] = reader.read(contextText(value));
+        const found = reader.found();
+        const event = detectEvent('context', found);
+        if (event)
+            events.push({ ...event, trust: CONTEXT_TRUST[sender] });
+        blocked ||= found.action === 'block';
+    }
+    return { context: read, events, blocked };
+}
+const PROJECT_ID_OK = /^[A-Za-z0-9._-]+$/;
+/** The project id trimmed, or `undefined` when it is empty or has illegal characters. */
+function sanitizeProjectId(id) {
+    const trimmed = id?.trim();
+    return trimmed && PROJECT_ID_OK.test(trimmed) ? trimmed : undefined;
+}
+function sanitizeRepair(repair, reader) {
+    if (!repair) {
+        return repair;
+    }
+    const guidance = repair.guidance ? reader.read(repair.guidance) : undefined;
+    return {
+        previousOutput: reader.read(repair.previousOutput),
+        rejection: reader.read(repair.rejection),
+        ...(guidance ? { guidance } : {}),
+    };
+}
+/**
+ * Exported because every path that injects messages into a turn needs it — turn
+ * history, and host steer injects mid-turn. A second copy would drift.
+ */
+function sanitizeHistory(history, reader) {
+    return history.map((m) => {
+        const content = m.content === undefined ? undefined : reader.read(m.content);
+        const parts = m.parts?.map((p) => p.type === 'text' ? { ...p, text: reader.read(p.text) } : p);
+        return {
+            role: m.role,
+            ...(content !== undefined ? { content } : {}),
+            ...(parts ? { parts } : {}),
+            ...(m.tool_calls ? { tool_calls: m.tool_calls } : {}),
+            ...(m.tool_call_id ? { tool_call_id: m.tool_call_id } : {}),
+            ...(m.name ? { name: m.name } : {}),
+            ...(m.metadata ? { metadata: m.metadata } : {}),
+            // why: Google refuses a call from the current turn replayed without its thought signature, so a reply resumed after a gate needs it.
+            ...(m.reasoning ? { reasoning: m.reasoning } : {}),
+        };
+    });
+}
+/** The error a turn ends on when a detector set to `block` matched at `boundary`. */
+function requestRefused(boundary) {
+    // labels-exempt: developer contract / internal diagnostic — the user's wording is `detect.blocked`
+    return new TheoremError('input', `guardrails.detect blocked the request at ${boundary}`, {
+        copy: { key: 'detect.blocked' },
+    });
+}
+/**
+ * `req.system` is host-assembled per turn — it interpolates retrieval and user
+ * data, so it is read at its own boundary. `identity.system` never reaches this
+ * path and stays verbatim.
+ */
+function sanitizeTurnRequestWithEvents(req, profile) {
+    const { detect } = resolveGuardrailPolicy(profile.guardrails);
+    const at = recordOf(REQUEST_BOUNDARIES, (boundary) => boundaryReader(boundary, detect));
+    const input = req.input ?? {};
+    const text = input.text === undefined ? undefined : at.user.read(input.text);
+    const system = req.system === undefined
+        ? undefined
+        : mapSystemPrompt(req.system, 'TurnRequest.system', (part) => at.system.read(part));
+    const slots = sanitizeSlots(input.slots, at.slots);
+    const told = sanitizeContext(input.context, () => boundaryReader('context', detect));
+    const repair = sanitizeRepair(input.repair, at.repair);
+    const history = input.history ? sanitizeHistory(input.history, at.history) : undefined;
+    const { attachments, voice } = input.attachments?.length || input.voice?.length
+        ? sanitizeTurnBlobs(profile, input.attachments, input.voice, at)
+        : input;
+    const events = [];
+    let refusal;
+    for (const boundary of REQUEST_BOUNDARIES) {
+        const found = at[boundary].found();
+        const event = detectEvent(boundary, found);
+        if (event)
+            events.push(guardrailTurnEvent(event));
+        if (found.action === 'block')
+            refusal ??= requestRefused(boundary);
+    }
+    events.push(...told.events.map(guardrailTurnEvent));
+    if (told.blocked)
+        refusal ??= requestRefused('context');
+    return {
+        request: {
+            ...req,
+            system,
+            projectId: sanitizeProjectId(req.projectId),
+            input: {
+                ...input,
+                text,
+                slots,
+                ...(told.context ? { context: told.context } : {}),
+                repair,
+                history,
+                attachments,
+                voice,
+            },
+        },
+        events,
+        ...(refusal ? { refusal } : {}),
+    };
+}
+/** The turn request with its input cleaned under the profile's guardrails. Throws when a match blocks it. */
+function sanitizeTurnRequest(req, profile) {
+    const { request, refusal } = sanitizeTurnRequestWithEvents(req, profile);
+    if (refusal)
+        throw refusal;
+    return request;
+}
+export { contextText, requestRefused, sanitizeContext, sanitizeHistory, sanitizeProjectId, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, };

package/esm/src/guardrails/sensitive-groups.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The names of the sensitive-data groups and how a profile switches them, apart from the patterns
+ * that find them: what reads or shows a profile's settings has no need of the patterns.
+ *
+ * @module
+ */
+/**
+ * The families of sensitive data, each switched on its own: a profile can
+ * redact credentials and card numbers but leave network addresses alone.
+ */
+declare const SENSITIVE_GROUPS: readonly ["ids", "financial", "network", "credentials"];
+/** A group of sensitive-value checks: ids, financial, network, or credentials. */
+type SensitiveGroup = (typeof SENSITIVE_GROUPS)[number];
+/** Per group, whether it runs. A group left out keeps its default. */
+type SensitiveSwitches = Partial<Record<SensitiveGroup, boolean>>;
+/** `true` runs every group, `false` none; an object switches the groups it names. */
+type SensitiveSelection = boolean | SensitiveSwitches;
+/** Every group's switch, defaults applied. */
+type SensitiveGroups = Readonly<Record<SensitiveGroup, boolean>>;
+export type { SensitiveGroup, SensitiveGroups, SensitiveSelection, SensitiveSwitches };
+export { SENSITIVE_GROUPS };

package/esm/src/guardrails/sensitive-groups.js

@@ -0,0 +1,12 @@
+/**
+ * The names of the sensitive-data groups and how a profile switches them, apart from the patterns
+ * that find them: what reads or shows a profile's settings has no need of the patterns.
+ *
+ * @module
+ */
+/**
+ * The families of sensitive data, each switched on its own: a profile can
+ * redact credentials and card numbers but leave network addresses alone.
+ */
+const SENSITIVE_GROUPS = ['ids', 'financial', 'network', 'credentials'];
+export { SENSITIVE_GROUPS };

package/esm/src/guardrails/sensitive.d.ts

@@ -0,0 +1,22 @@
+import { type RedactSpan } from '../observability/spans.js';
+import type { SensitiveGroup, SensitiveSelection } from './sensitive-groups.js';
+declare const CARD_CANDIDATE: RegExp;
+interface SensitivePattern {
+    group: SensitiveGroup;
+    pattern: RegExp;
+    /** Whether a match at `at` of `text` counts. */
+    hit?: (match: string, text: string, at: number) => boolean;
+}
+/** Every pattern, with its group. */
+declare const SENSITIVE_PATTERNS: readonly SensitivePattern[];
+/**
+ * A card-number candidate at `at` of `text` that is a card: digits a card
+ * network issues, passing the Luhn check, outside a web address. A run of
+ * digits in an address is the address's own identifier: one random 19-digit
+ * identifier in a hundred passes the first two tests.
+ */
+declare function cardHit(blob: string, text: string, at: number): boolean;
+/** Sensitive-data spans in `text`, from the groups `selection` runs (every group by default). */
+declare function sensitiveSpans(text: string, selection?: SensitiveSelection): RedactSpan[];
+export type { SensitivePattern };
+export { CARD_CANDIDATE, cardHit, SENSITIVE_PATTERNS, sensitiveSpans };

package/esm/src/guardrails/sensitive.js

@@ -0,0 +1,234 @@
+import { blobAt, spansFromPatterns } from '../observability/spans.js';
+import { CREDENTIAL_RULES, GLOBAL_ALLOWLIST } from './credential-rules.js';
+import { credentialHit, credentialSpans } from './credential-scan.js';
+const SSN = /\b\d{3}-\d{2}-\d{4}\b/g;
+const SSN_CONTEXTUAL = /(?:SSN|social\s*security(?:\s*number)?)[:\s]+\d(?:[-\s]*\d){8}/gi;
+const ITIN = /\b9\d{2}-\d{2}-\d{4}\b/g;
+const EIN = /\b\d{2}-\d{7}\b/g;
+const IBAN = /\b[A-Z]{2}\d{2}[A-Z0-9]{13,30}\b/g;
+const IPV4 = /\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\b/g;
+const HEX_GROUP = '[0-9a-f]{1,4}';
+const DOTTED_QUAD = '(?:(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(?:25[0-5]|2[0-4]\\d|[01]?\\d\\d?)';
+/** Every RFC 4291 text form: full, `::`-compressed, and with a dotted IPv4 tail. */
+const IPV6_FORMS = [
+    `(?:${HEX_GROUP}:){6}${DOTTED_QUAD}`,
+    `(?:${HEX_GROUP}:){1,5}:${DOTTED_QUAD}`,
+    `::(?:${HEX_GROUP}:){0,5}${DOTTED_QUAD}`,
+    `(?:${HEX_GROUP}:){7}${HEX_GROUP}`,
+    `(?:${HEX_GROUP}:){1,6}(?::${HEX_GROUP}){1,6}`,
+    `(?:${HEX_GROUP}:){1,7}:`,
+    `:(?::${HEX_GROUP}){1,7}`,
+];
+const IPV6 = new RegExp(`(?<![\\w:.])(?:${IPV6_FORMS.join('|')})(?![\\w:])`, 'gi');
+/** Credentials gitleaks' rules miss: keys cut short or spaced out, a short private key, and a bare bearer token. */
+const OWN_CREDENTIAL_RULES = [
+    {
+        id: 'openai-api-key-any',
+        pattern: /\bsk-\s*[A-Za-z0-9]{20,}\b/,
+        keywords: ['sk-'],
+        allowlists: [],
+    },
+    {
+        id: 'anthropic-api-key-any',
+        pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/,
+        keywords: ['sk-ant-'],
+        allowlists: [],
+    },
+    {
+        id: 'openrouter-api-key',
+        pattern: /\bsk-or-[A-Za-z0-9_-]{20,}\b/,
+        keywords: ['sk-or-'],
+        allowlists: [],
+    },
+    {
+        id: 'github-fine-grained-pat-any',
+        pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/,
+        keywords: ['github_pat_'],
+        allowlists: [],
+    },
+    {
+        id: 'slack-token-any',
+        pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/,
+        keywords: ['xox'],
+        allowlists: [],
+    },
+    {
+        id: 'private-key-any',
+        pattern: /-----BEGIN (?:(?:RSA|DSA|EC|OPENSSH|ENCRYPTED|PGP) )?PRIVATE KEY(?: BLOCK)?-----[\s\S]{0,16384}?-----END (?:(?:RSA|DSA|EC|OPENSSH|ENCRYPTED|PGP) )?PRIVATE KEY(?: BLOCK)?-----/,
+        keywords: ['-----begin'],
+        allowlists: [],
+    },
+    {
+        id: 'bearer-token',
+        pattern: /\bBearer[ \t]+([A-Za-z0-9._~+/-]{16,}=*)/i,
+        entropy: 3,
+        keywords: ['bearer'],
+        allowlists: [],
+    },
+];
+/** Every credential rule: gitleaks', then Theorem's own. */
+const CREDENTIALS = [...CREDENTIAL_RULES, ...OWN_CREDENTIAL_RULES];
+const CARD_CANDIDATE = /\b(?:\d[\s.-]*?){13,19}\b/g;
+/** The patterns each group matches. Card numbers are financial too, found by `cardSpans`; credentials by `credentialSpans`. */
+const GROUP_PATTERNS = {
+    ids: [SSN, SSN_CONTEXTUAL, ITIN, EIN],
+    financial: [IBAN],
+    network: [IPV4, IPV6],
+};
+/** Every pattern, with its group. */
+const SENSITIVE_PATTERNS = [
+    ...['ids', 'financial', 'network'].flatMap((group) => GROUP_PATTERNS[group].map((pattern) => ({ group, pattern }))),
+    ...CREDENTIALS.map((rule) => ({
+        group: 'credentials',
+        pattern: new RegExp(rule.pattern.source, `${rule.pattern.flags}g`),
+        hit: (match, text, at) => credentialHit(rule, GLOBAL_ALLOWLIST, match, text, at),
+    })),
+];
+const ALL_GROUPS = {
+    ids: true,
+    financial: true,
+    network: true,
+    credentials: true,
+};
+/** `selection` with the groups it leaves out taken from `defaults`. */
+function resolveSensitive(selection, defaults = ALL_GROUPS) {
+    if (selection === undefined)
+        return defaults;
+    if (typeof selection === 'boolean') {
+        return { ids: selection, financial: selection, network: selection, credentials: selection };
+    }
+    return { ...defaults, ...selection };
+}
+const LUHN_DOUBLE = 2;
+const LUHN_NINE = 9;
+const LUHN_TEN = 10;
+function luhnOk(digits) {
+    let sum = 0;
+    let doubleIt = false;
+    for (let i = digits.length - 1; i >= 0; i -= 1) {
+        const ch = digits[i];
+        if (ch === undefined) {
+            return false;
+        }
+        let n = Number(ch);
+        if (doubleIt) {
+            n *= LUHN_DOUBLE;
+            if (n > LUHN_NINE) {
+                n -= LUHN_NINE;
+            }
+        }
+        sum += n;
+        doubleIt = !doubleIt;
+    }
+    return sum % LUHN_TEN === 0;
+}
+const LENGTHS_16_TO_19 = [16, 17, 18, 19];
+/** Visa, Mastercard, American Express, Diners Club, Discover, JCB, UnionPay, Maestro, Mir, and RuPay, in that order. */
+const CARD_NETWORKS = [
+    { leading: [['4', '4']], lengths: [13, 16, 19] },
+    {
+        leading: [
+            ['51', '55'],
+            ['2221', '2720'],
+        ],
+        lengths: [16],
+    },
+    {
+        leading: [
+            ['34', '34'],
+            ['37', '37'],
+        ],
+        lengths: [15],
+    },
+    {
+        leading: [
+            ['300', '305'],
+            ['3095', '3095'],
+            ['36', '36'],
+            ['38', '39'],
+        ],
+        lengths: [14, 15, ...LENGTHS_16_TO_19],
+    },
+    {
+        leading: [
+            ['6011', '6011'],
+            ['644', '649'],
+            ['65', '65'],
+        ],
+        lengths: LENGTHS_16_TO_19,
+    },
+    { leading: [['3528', '3589']], lengths: LENGTHS_16_TO_19 },
+    { leading: [['62', '62']], lengths: LENGTHS_16_TO_19 },
+    {
+        leading: [
+            ['5018', '5018'],
+            ['5020', '5020'],
+            ['5038', '5038'],
+            ['5893', '5893'],
+            ['6304', '6304'],
+            ['6759', '6759'],
+            ['6761', '6763'],
+        ],
+        lengths: [13, 14, 15, ...LENGTHS_16_TO_19],
+    },
+    { leading: [['2200', '2204']], lengths: LENGTHS_16_TO_19 },
+    {
+        leading: [
+            ['60', '60'],
+            ['81', '82'],
+            ['508', '508'],
+            ['353', '353'],
+            ['356', '356'],
+        ],
+        lengths: [16],
+    },
+];
+/** Whether some card network issues numbers that start and run as long as `digits`. */
+function isIssued(digits) {
+    return CARD_NETWORKS.some((network) => network.lengths.includes(digits.length) &&
+        network.leading.some(([low, high]) => {
+            const start = digits.slice(0, low.length);
+            return start >= low && start <= high;
+        }));
+}
+const URL_SCHEME = /https?:\/\//i;
+const URL_LOOKBACK = 2048;
+/** Whether `at` of `text` is inside a web address: the unbroken run of characters before it holds `http://` or `https://`. */
+function isInUrl(text, at) {
+    const floor = Math.max(0, at - URL_LOOKBACK);
+    let from = at;
+    while (from > floor && !/\s/.test(text[from - 1] ?? ' '))
+        from -= 1;
+    return URL_SCHEME.test(text.slice(from, at));
+}
+/**
+ * A card-number candidate at `at` of `text` that is a card: digits a card
+ * network issues, passing the Luhn check, outside a web address. A run of
+ * digits in an address is the address's own identifier: one random 19-digit
+ * identifier in a hundred passes the first two tests.
+ */
+function cardHit(blob, text, at) {
+    const digits = blob.replaceAll(/[^\d]/g, '');
+    return isIssued(digits) && luhnOk(digits) && !isInUrl(text, at);
+}
+function cardSpans(text) {
+    const spans = [];
+    for (const match of text.matchAll(CARD_CANDIDATE)) {
+        const found = blobAt(match);
+        if (found && cardHit(found.blob, text, found.index)) {
+            spans.push({ start: found.index, end: found.index + found.blob.length, kind: 'sensitive' });
+        }
+    }
+    return spans;
+}
+/** Sensitive-data spans in `text`, from the groups `selection` runs (every group by default). */
+function sensitiveSpans(text, selection = true) {
+    const groups = resolveSensitive(selection);
+    const patterns = ['ids', 'financial', 'network'].flatMap((group) => groups[group] ? GROUP_PATTERNS[group] : []);
+    return [
+        ...spansFromPatterns(text, patterns, 'sensitive'),
+        ...(groups.financial ? cardSpans(text) : []),
+        ...(groups.credentials ? credentialSpans(text, CREDENTIALS, GLOBAL_ALLOWLIST) : []),
+    ];
+}
+export { CARD_CANDIDATE, cardHit, SENSITIVE_PATTERNS, sensitiveSpans };