@bounded-sh/observe 0.1.0

package/dist/manifest.js

@@ -0,0 +1,941 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// manifest.ts -- the living capture policy, shim side (SPEC §3.1g / T1).
+//
+// v0: a built-in default manifest (metadata-only capture + built-in
+// recognizers for Stripe money movement, OpenAI/Anthropic spend, and
+// email/SMS/chat/GitHub egress) plus a
+// fetcher stub that polls <ingestBase>/v1/manifest?org=... every 60s. The
+// endpoint does not exist yet — 404/invalid responses keep the built-in
+// (fail-safe: no/invalid manifest => metadata-only, never over-capture).
+//
+// TODO(signed manifests, SPEC §3.1a): verify `signature` (Ed25519 over the
+// canonical manifest JSON, key pinned at init) before accepting a fetched
+// manifest. Until verification lands, fetched manifests are accepted only
+// structurally; the built-in remains the trust anchor.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompiledManifest = exports.BUILTIN_MANIFEST = void 0;
+exports.escortedManifest = escortedManifest;
+exports.withEscortPin = withEscortPin;
+exports.validateManifest = validateManifest;
+const denylist_1 = require("./denylist");
+// ---------------------------------------------------------------------------
+// Crypto RPC recognizers (rails: solana, evm). Crypto JSON-RPC POSTs EVERY
+// call to one path ("/") with the operation in the request body's `method`
+// field, so these entries match on `rpcMethod` (see RecognizerEntry.rpcMethod)
+// instead of the path. OBSERVE-ONLY: no escort blocks (onchain enforcement is
+// a separate track). The params VALUES — raw signed transactions, calldata,
+// signatures, private material — are NEVER captured; only the rpc method name
+// and a few clearly-PUBLIC scalars (an EVM `to` address, hex `value`, chainId)
+// ride rec.fields. Host coverage is EXACT (the matcher does not do suffix
+// wildcards): the common public endpoints are listed below; per-tenant provider
+// subdomains (*.helius-rpc.com, *.quiknode.pro, *.infura.io, *.g.alchemy.com)
+// are reached via tenant manifest overlays (compileOrgManifest), not the
+// built-in. Fee-payer / signer extraction from a Solana tx is intentionally
+// NOT attempted in the shim hot path (it would require decoding the blob) —
+// left to the onchain-enforcement design.
+const SOLANA_RPC_HOSTS = [
+    "api.mainnet-beta.solana.com",
+    "api.devnet.solana.com",
+    "mainnet.helius-rpc.com",
+    "solana-mainnet.g.alchemy.com",
+];
+const EVM_RPC_HOSTS = [
+    "mainnet.base.org",
+    "base-mainnet.g.alchemy.com",
+    "eth-mainnet.g.alchemy.com",
+    "mainnet.infura.io",
+];
+const SOLANA_RPC_METHODS = [
+    // params are [base64Tx, opts]. The tx blob (params[0]) is NEVER decoded on
+    // the hot path — capture only the method name + the encoding opt (an enum).
+    { rpcMethod: "sendTransaction", action: "solana.tx.send", requestFields: ["method", "params.1.encoding"] },
+    // wallet-adapter style signAndSend: the tx is opaque bytes — method name only.
+    { rpcMethod: "signAndSendTransaction", action: "solana.tx.signsend", requestFields: ["method"] },
+    { rpcMethod: "simulateTransaction", action: "solana.tx.simulate", requestFields: ["method", "params.1.encoding"] },
+    { rpcMethod: "requestAirdrop", action: "solana.airdrop", requestFields: ["method"] },
+];
+const EVM_RPC_METHODS = [
+    // Already-signed raw tx blob — method name only; never the blob (params[0]).
+    { rpcMethod: "eth_sendRawTransaction", action: "evm.tx.send", requestFields: ["method"] },
+    {
+        // params[0] is a tx object: `to` (public address), `value` (hex amount) and
+        // `chainId` are safe PUBLIC scalars. `data`/`input` (calldata) is NEVER
+        // listed. `from` is the sender wallet — a PUBLIC identifier routed to the
+        // attribution channel (onBehalfOf), raw by default (hash:false) since a
+        // wallet address is public (unlike an email); still owner-configurable.
+        rpcMethod: "eth_sendTransaction",
+        action: "evm.tx.send",
+        requestFields: ["method", "params.0.to", "params.0.value", "params.0.chainId"],
+        identityField: { source: "params.0.from", as: "onBehalfOf", hash: false },
+    },
+    { rpcMethod: "eth_call", action: "evm.call", requestFields: ["method"] },
+];
+/** Cross-product hosts × rpc methods into rpcMethod-keyed recognizer entries. */
+function rpcRecognizers(rail, hosts, methods) {
+    const out = [];
+    for (const host of hosts) {
+        for (const m of methods) {
+            out.push({
+                host,
+                method: "POST",
+                path: "/",
+                rpcMethod: m.rpcMethod,
+                rail,
+                action: m.action,
+                ...(m.requestFields ? { requestFields: m.requestFields } : {}),
+                ...(m.identityField ? { identityField: m.identityField } : {}),
+            });
+        }
+    }
+    return out;
+}
+const CRYPTO_RECOGNIZERS = [
+    ...rpcRecognizers("solana", SOLANA_RPC_HOSTS, SOLANA_RPC_METHODS),
+    ...rpcRecognizers("evm", EVM_RPC_HOSTS, EVM_RPC_METHODS),
+];
+/** Built-in default manifest: metadata-only + curated safe-field recognizers.
+ * SAFE fields only: amounts (cents), opaque IDs, model names, token counts. */
+exports.BUILTIN_MANIFEST = {
+    version: "builtin-0.3.0",
+    recognizers: [
+        // --- Stripe (rail: stripe). Amounts are already in cents. -------------
+        {
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/refunds",
+            rail: "stripe",
+            action: "stripe.refund.create",
+            requestFields: ["charge", "payment_intent", "amount", "currency"],
+            responseFields: ["id", "amount", "currency", "status"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/charges/{id}/refunds",
+            rail: "stripe",
+            action: "stripe.refund.create",
+            requestFields: ["amount"],
+            responseFields: ["id", "amount", "currency", "status"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "GET",
+            path: "/v1/refunds/{id}",
+            rail: "stripe",
+            action: "stripe.refund.get",
+            responseFields: ["id", "amount", "currency", "status"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/charges",
+            rail: "stripe",
+            action: "stripe.charge.create",
+            requestFields: ["amount", "currency", "customer"],
+            responseFields: ["id", "amount", "currency", "status"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "GET",
+            path: "/v1/charges/{id}",
+            rail: "stripe",
+            action: "stripe.charge.get",
+            responseFields: ["id", "amount", "currency", "status"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/payment_intents",
+            rail: "stripe",
+            action: "stripe.payment_intent.create",
+            requestFields: ["amount", "currency", "customer"],
+            responseFields: ["id", "amount", "currency", "status"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "GET",
+            path: "/v1/payment_intents/{id}",
+            rail: "stripe",
+            action: "stripe.payment_intent.get",
+            responseFields: ["id", "amount", "currency", "status"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/payment_intents/{id}/confirm",
+            rail: "stripe",
+            action: "stripe.payment_intent.confirm",
+            responseFields: ["id", "amount", "currency", "status"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/payment_intents/{id}/capture",
+            rail: "stripe",
+            action: "stripe.payment_intent.capture",
+            requestFields: ["amount_to_capture"],
+            responseFields: ["id", "amount", "amount_received", "currency", "status"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/payment_intents/{id}/cancel",
+            rail: "stripe",
+            action: "stripe.payment_intent.cancel",
+            responseFields: ["id", "status"],
+        },
+        // --- Stripe money-OUT (payouts/transfers leave the account). ----------
+        {
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/payouts",
+            rail: "stripe",
+            action: "stripe.payout.create",
+            // destination is an opaque external-account id (ba_…/card ids are
+            // opaque tokens, never PANs).
+            requestFields: ["amount", "currency", "destination"],
+            responseFields: ["id", "amount", "currency", "status"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/transfers",
+            rail: "stripe",
+            action: "stripe.transfer.create",
+            // destination is an opaque connected-account id (acct_…).
+            requestFields: ["amount", "currency", "destination"],
+            responseFields: ["id", "amount", "currency"],
+        },
+        // --- Stripe billing / checkout / setup. -------------------------------
+        {
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/subscriptions",
+            rail: "stripe",
+            action: "stripe.subscription.create",
+            requestFields: ["customer"],
+            responseFields: ["id", "status", "currency"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "DELETE",
+            path: "/v1/subscriptions/{id}",
+            rail: "stripe",
+            action: "stripe.subscription.cancel",
+            responseFields: ["id", "status"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/invoices/{id}/pay",
+            rail: "stripe",
+            action: "stripe.invoice.pay",
+            responseFields: ["id", "amount_paid", "amount_due", "currency", "status"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/checkout/sessions",
+            rail: "stripe",
+            action: "stripe.checkout.session.create",
+            requestFields: ["mode", "customer"],
+            responseFields: ["id", "amount_total", "currency", "status"],
+        },
+        {
+            // Customer bodies are PII-dense (name/email/address — all L2-denied
+            // anyway). id-only ON PURPOSE: the entry recognizes the ACTION, never
+            // the person.
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/customers",
+            rail: "stripe",
+            action: "stripe.customer.create",
+            responseFields: ["id"],
+        },
+        {
+            host: "api.stripe.com",
+            method: "POST",
+            path: "/v1/setup_intents",
+            rail: "stripe",
+            action: "stripe.setup_intent.create",
+            requestFields: ["customer"],
+            responseFields: ["id", "status"],
+        },
+        // --- OpenAI spend (rail: llm-gateway): model names + token counts. ----
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/chat/completions",
+            rail: "llm-gateway",
+            action: "openai.chat.completions.create",
+            // Output cap is optional + inconsistently named on OpenAI: capture both
+            // the current (max_completion_tokens) and legacy (max_tokens) forms so a
+            // request-time spend upper bound exists whenever the caller sets one.
+            requestFields: ["model", "max_tokens", "max_completion_tokens"],
+            responseFields: [
+                "model",
+                "usage.prompt_tokens",
+                "usage.completion_tokens",
+                "usage.total_tokens",
+                // cached-input discount (present on cached prompts) — settle-time actuals.
+                "usage.prompt_tokens_details.cached_tokens",
+            ],
+        },
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/responses",
+            rail: "llm-gateway",
+            action: "openai.responses.create",
+            requestFields: ["model", "max_output_tokens"],
+            responseFields: [
+                "model",
+                "usage.input_tokens",
+                "usage.output_tokens",
+                "usage.total_tokens",
+                "usage.input_tokens_details.cached_tokens",
+            ],
+        },
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/completions",
+            rail: "llm-gateway",
+            action: "openai.completions.create",
+            requestFields: ["model", "max_tokens"],
+            responseFields: [
+                "model",
+                "usage.prompt_tokens",
+                "usage.completion_tokens",
+                "usage.total_tokens",
+            ],
+        },
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/embeddings",
+            rail: "llm-gateway",
+            action: "openai.embeddings.create",
+            requestFields: ["model"],
+            responseFields: ["model", "usage.prompt_tokens", "usage.total_tokens"],
+        },
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/images/generations",
+            rail: "llm-gateway",
+            action: "openai.images.generations.create",
+            // Prompt text NEVER — model + count/size/quality knobs only. usage.*
+            // token counts appear on gpt-image-1 responses.
+            requestFields: ["model", "n", "size", "quality"],
+            responseFields: ["created", "usage.input_tokens", "usage.output_tokens", "usage.total_tokens"],
+        },
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/audio/speech",
+            rail: "llm-gateway",
+            action: "openai.audio.speech.create",
+            // Response is binary audio (no JSON); the input text NEVER — knobs only.
+            requestFields: ["model", "voice", "speed"],
+        },
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/audio/transcriptions",
+            rail: "llm-gateway",
+            action: "openai.audio.transcriptions.create",
+            // Request is multipart (file upload — not parsed today); transcript
+            // text NEVER. duration (seconds) + usage token counts are billed actuals.
+            requestFields: ["model"],
+            responseFields: ["duration", "usage.input_tokens", "usage.output_tokens", "usage.total_tokens"],
+        },
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/moderations",
+            rail: "llm-gateway",
+            action: "openai.moderations.create",
+            // The moderated input NEVER; results ride an array (never extracted).
+            requestFields: ["model"],
+            responseFields: ["id", "model"],
+        },
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/batches",
+            rail: "llm-gateway",
+            action: "openai.batches.create",
+            // input_file_id is an opaque file id; endpoint/completion_window are enums.
+            requestFields: ["input_file_id", "endpoint", "completion_window"],
+            responseFields: ["id", "status", "request_counts.total", "request_counts.completed", "request_counts.failed"],
+        },
+        {
+            host: "api.openai.com",
+            method: "GET",
+            path: "/v1/batches/{id}",
+            rail: "llm-gateway",
+            action: "openai.batches.get",
+            responseFields: ["id", "status", "request_counts.total", "request_counts.completed", "request_counts.failed"],
+        },
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/batches/{id}/cancel",
+            rail: "llm-gateway",
+            action: "openai.batches.cancel",
+            responseFields: ["id", "status"],
+        },
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/fine_tuning/jobs",
+            rail: "llm-gateway",
+            action: "openai.fine_tuning.jobs.create",
+            // training_file is an opaque file id; user-supplied `suffix` is skipped
+            // (free-text). NOTE: hyperparameters ride nested objects — not captured.
+            requestFields: ["model", "training_file"],
+            responseFields: ["id", "model", "status"],
+        },
+        {
+            host: "api.openai.com",
+            method: "GET",
+            path: "/v1/fine_tuning/jobs/{id}",
+            rail: "llm-gateway",
+            action: "openai.fine_tuning.jobs.get",
+            responseFields: ["id", "model", "status", "trained_tokens"],
+        },
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/fine_tuning/jobs/{id}/cancel",
+            rail: "llm-gateway",
+            action: "openai.fine_tuning.jobs.cancel",
+            responseFields: ["id", "status"],
+        },
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/assistants",
+            rail: "llm-gateway",
+            action: "openai.assistants.create",
+            // `name` is L2-denied and instructions are content — sampling knobs only.
+            requestFields: ["model", "temperature", "top_p"],
+            responseFields: ["id", "model"],
+        },
+        {
+            host: "api.openai.com",
+            method: "POST",
+            path: "/v1/threads/{id}/runs",
+            rail: "llm-gateway",
+            action: "openai.threads.runs.create",
+            requestFields: ["assistant_id", "model", "max_prompt_tokens", "max_completion_tokens"],
+            // usage is null until the run completes; token counts extract when present.
+            responseFields: ["id", "status", "model", "usage.prompt_tokens", "usage.completion_tokens", "usage.total_tokens"],
+        },
+        // --- Anthropic spend (rail: llm-gateway). -----------------------------
+        {
+            host: "api.anthropic.com",
+            method: "POST",
+            path: "/v1/messages",
+            rail: "llm-gateway",
+            action: "anthropic.messages.create",
+            requestFields: ["model", "max_tokens"],
+            // Cache write (~1.25× input) / read (~0.1× input) tokens are billed and
+            // must be captured or settle-time actual cost skews on cached traffic.
+            responseFields: [
+                "model",
+                "usage.input_tokens",
+                "usage.output_tokens",
+                "usage.cache_creation_input_tokens",
+                "usage.cache_read_input_tokens",
+            ],
+        },
+        {
+            host: "api.anthropic.com",
+            method: "POST",
+            path: "/v1/messages/batches",
+            rail: "llm-gateway",
+            action: "anthropic.messages.batches.create",
+            // The request is an array of message params (content — never captured);
+            // the batch id + per-state counts are the whole safe surface.
+            responseFields: [
+                "id",
+                "processing_status",
+                "request_counts.processing",
+                "request_counts.succeeded",
+                "request_counts.errored",
+                "request_counts.canceled",
+                "request_counts.expired",
+            ],
+        },
+        {
+            host: "api.anthropic.com",
+            method: "GET",
+            path: "/v1/messages/batches/{id}",
+            rail: "llm-gateway",
+            action: "anthropic.messages.batches.get",
+            responseFields: [
+                "id",
+                "processing_status",
+                "request_counts.processing",
+                "request_counts.succeeded",
+                "request_counts.errored",
+                "request_counts.canceled",
+                "request_counts.expired",
+            ],
+        },
+        {
+            host: "api.anthropic.com",
+            method: "POST",
+            path: "/v1/messages/batches/{id}/cancel",
+            rail: "llm-gateway",
+            action: "anthropic.messages.batches.cancel",
+            responseFields: ["id", "processing_status"],
+        },
+        {
+            // List response rides a `data` array (never extracted) — pagination
+            // cursors are the only safe scalars. Recognized > unknown shape.
+            host: "api.anthropic.com",
+            method: "GET",
+            path: "/v1/models",
+            rail: "llm-gateway",
+            action: "anthropic.models.list",
+            responseFields: ["first_id", "last_id"],
+        },
+        // --- Email egress (observe-only; metadata + opaque ids). --------------
+        {
+            // SendGrid bodies are ALL recipients + content (L2 territory) and the
+            // 202 response carries no JSON — a deliberately field-LESS entry. The
+            // recognized action (email.send, storied + risk-classed) is the value.
+            host: "api.sendgrid.com",
+            method: "POST",
+            path: "/v3/mail/send",
+            rail: "email",
+            action: "email.send",
+        },
+        {
+            // Resend: from/to/subject/html are content — response id only.
+            host: "api.resend.com",
+            method: "POST",
+            path: "/emails",
+            rail: "email",
+            action: "email.send",
+            responseFields: ["id"],
+        },
+        // --- SMS egress (observe-only). ----------------------------------------
+        {
+            // Twilio: To/From are phone numbers, Body is content — none captured.
+            // sid is the opaque message id; status is an enum (queued/sent/…).
+            host: "api.twilio.com",
+            method: "POST",
+            path: "/2010-04-01/Accounts/{id}/Messages.json",
+            rail: "sms",
+            action: "sms.send",
+            responseFields: ["sid", "status"],
+        },
+        // --- Chat egress (observe-only). ---------------------------------------
+        {
+            // Slack: text/blocks are content — channel id + delivery ack only.
+            host: "slack.com",
+            method: "POST",
+            path: "/api/chat.postMessage",
+            rail: "chat",
+            action: "chat.message.send",
+            requestFields: ["channel"],
+            responseFields: ["ok", "ts", "channel"],
+        },
+        // --- GitHub (rail: github; observe-only). {id} covers the owner/repo
+        // segments AS TEMPLATED BY THE SHIM — see templatePath (slug-looking
+        // owner/repo names may not template; id-looking ones do). ----------------
+        {
+            // title/body are content — response numbers/state only.
+            host: "api.github.com",
+            method: "POST",
+            path: "/repos/{id}/{id}/issues",
+            rail: "github",
+            action: "github.issues.create",
+            responseFields: ["id", "number", "state"],
+        },
+        {
+            // 204 No Content on success — the recognized action (destructive
+            // riskClass downstream) is the whole value.
+            host: "api.github.com",
+            method: "DELETE",
+            path: "/repos/{id}/{id}",
+            rail: "github",
+            action: "github.repo.delete",
+        },
+        {
+            // title/body/head/base are content-ish free text — draft flag only.
+            host: "api.github.com",
+            method: "POST",
+            path: "/repos/{id}/{id}/pulls",
+            rail: "github",
+            action: "github.pulls.create",
+            requestFields: ["draft"],
+            responseFields: ["id", "number", "state"],
+        },
+        {
+            // message/content are commit text + file bytes — shas only (opaque).
+            host: "api.github.com",
+            method: "PUT",
+            path: "/repos/{id}/{id}/contents/{id}",
+            rail: "github",
+            action: "github.contents.put",
+            requestFields: ["sha"],
+            responseFields: ["commit.sha", "content.sha"],
+        },
+        // --- Crypto RPC (rails: solana, evm) — rpcMethod-matched, observe-only. --
+        ...CRYPTO_RECOGNIZERS,
+    ],
+    counters: [],
+    mutes: [],
+};
+/** The single route the env escort pin targets (SPEC §3.1e, T9). */
+const PIN_ROUTE = { host: "api.stripe.com", method: "POST", path: "/v1/refunds" };
+/**
+ * Pin an escort block onto the Stripe-refund recognizer (api.stripe.com POST
+ * /v1/refunds). Everything else stays OBSERVE. Applied over the built-in at
+ * boot (register preload) AND re-applied over every fetched manifest swap.
+ * Idempotent, fetched-wins:
+ *   - If the entry ALREADY carries an escort block (server-side promotion in a
+ *     fetched manifest), that block wins and the env pin is skipped.
+ *   - If the entry is MISSING (a fetched manifest dropped the route), it is
+ *     restored from the built-in recognizer WITH the pin — enforcement armed
+ *     via BOUNDED_VERDICT_URL can never be silently switched off by a swap.
+ * The "+escort" version suffix is appended only when the pin was applied, and
+ * never doubled. counters/mutes/policyVersion of the base are preserved.
+ */
+function escortedManifest(base, verdictUrl, collection, failMode, timeoutMs) {
+    const escort = {
+        verdictUrl,
+        collection,
+        fieldMap: { charge: "chargeId", amount: "amountCents" },
+        failMode,
+        ...(timeoutMs ? { timeoutMs } : {}),
+    };
+    let found = false;
+    let pinned = false;
+    const recognizers = (base.recognizers || []).map((r) => {
+        if (r.host === PIN_ROUTE.host && r.method === PIN_ROUTE.method && r.path === PIN_ROUTE.path) {
+            found = true;
+            if (r.escort)
+                return r; // fetched/existing escort WINS; env pin skipped
+            pinned = true;
+            return { ...r, escort };
+        }
+        return r;
+    });
+    if (!found) {
+        const template = exports.BUILTIN_MANIFEST.recognizers.find((r) => r.host === PIN_ROUTE.host && r.method === PIN_ROUTE.method && r.path === PIN_ROUTE.path);
+        if (template) {
+            recognizers.push({ ...template, escort });
+            pinned = true;
+        }
+    }
+    if (!pinned)
+        return base;
+    const version = base.version.endsWith("+escort") ? base.version : `${base.version}+escort`;
+    return { ...base, version, recognizers };
+}
+/** Apply an (optional) env escort pin over a manifest. No pin = passthrough. */
+function withEscortPin(base, pin) {
+    if (!pin)
+        return base;
+    return escortedManifest(base, pin.verdictUrl, pin.collection, pin.failMode, pin.timeoutMs);
+}
+/** Compiled manifest index for O(1)-ish hot-path decisions. */
+class CompiledManifest {
+    manifest;
+    source;
+    /** host|METHOD|templatedPath -> entry (non-rpc entries only). */
+    exact = new Map();
+    /** host|rpc|rpcMethod -> entry (crypto JSON-RPC entries; matched on the
+     * request body's `method`, never the path). */
+    rpc = new Map();
+    /** Hosts carrying any rpcMethod recognizer (gates the JSON-RPC body parse). */
+    rpcHosts = new Set();
+    /** Hosts with any recognizer (request-body capture allowed). */
+    captureHosts = new Set();
+    /** host|METHOD|templatedPath entries whose responseFields need a body read. */
+    respCapture = new Set();
+    /** host|METHOD|templatedPath -> compiled escort (non-GET/HEAD routes only). */
+    escorts = new Map();
+    /** True if ANY route is escorted — the hot-path gate for escort mode. When
+     * false (the observe-only case) the interceptor does zero extra work. */
+    hasEscorts;
+    constructor(manifest, source) {
+        this.manifest = manifest;
+        this.source = source;
+        for (const r of manifest.recognizers) {
+            const method = r.method.toUpperCase();
+            // Crypto JSON-RPC entry: keyed by the body's rpc method, NOT the path
+            // (all RPC calls collapse onto one path). The request body must be
+            // captured to read the method, so the host still counts as a capture
+            // host. rpc entries are observe-only — escort/responseFields are ignored
+            // here (they cannot be path-keyed without collision on "/").
+            if (r.rpcMethod) {
+                this.rpc.set(`${r.host}|rpc|${r.rpcMethod}`, r);
+                this.rpcHosts.add(r.host);
+                this.captureHosts.add(r.host);
+                continue;
+            }
+            const key = `${r.host}|${method}|${r.path}`;
+            this.exact.set(key, r);
+            this.captureHosts.add(r.host);
+            if (r.responseFields && r.responseFields.length > 0)
+                this.respCapture.add(key);
+            // Reads are NEVER escorted (SPEC U16); ignore escort on GET/HEAD routes.
+            if (r.escort && method !== "GET" && method !== "HEAD") {
+                this.escorts.set(key, compileEscort(r.escort, r.rail, r.action));
+            }
+        }
+        this.hasEscorts = this.escorts.size > 0;
+    }
+    get version() {
+        return this.manifest.version;
+    }
+    recognize(host, method, pathTemplate) {
+        return this.exact.get(`${host}|${method}|${pathTemplate}`);
+    }
+    /** True if the host carries any crypto JSON-RPC recognizer — the cheap Set
+     * check that decides whether to parse the request body for its `method`. */
+    hasRpcHost(host) {
+        return this.rpcHosts.has(host);
+    }
+    /** Recognize a crypto JSON-RPC call by host + the body's `method`. */
+    recognizeRpc(host, rpcMethod) {
+        return this.rpc.get(`${host}|rpc|${rpcMethod}`);
+    }
+    wantsResponseBody(host, method, pathTemplate) {
+        return this.respCapture.has(`${host}|${method}|${pathTemplate}`);
+    }
+    /** Compiled escort for a route, or undefined. Reads are never escorted. */
+    escort(host, method, pathTemplate) {
+        if (method === "GET" || method === "HEAD")
+            return undefined;
+        return this.escorts.get(`${host}|${method}|${pathTemplate}`);
+    }
+    matchList(list, host, method, pathTemplate) {
+        if (!list)
+            return false;
+        for (const m of list) {
+            if (m.host !== host)
+                continue;
+            if (m.method && m.method.toUpperCase() !== method)
+                continue;
+            if (m.pathPrefix && !pathTemplate.startsWith(m.pathPrefix))
+                continue;
+            return true;
+        }
+        return false;
+    }
+    isCounterRoute(host, method, pathTemplate) {
+        return this.matchList(this.manifest.counters, host, method, pathTemplate);
+    }
+    isMuted(host, method, pathTemplate) {
+        return this.matchList(this.manifest.mutes, host, method, pathTemplate);
+    }
+}
+exports.CompiledManifest = CompiledManifest;
+/** Resolve verdictUrl's sibling path (…/verdict -> …/name); best-effort. */
+function siblingUrl(u, name) {
+    try {
+        const url = new URL(u);
+        url.pathname = url.pathname.replace(/\/[^/]*$/, `/${name}`);
+        return url.toString();
+    }
+    catch {
+        return u;
+    }
+}
+/** Fill in a raw EscortConfig into a compiled, resolved escort. */
+function compileEscort(e, rail, action) {
+    return {
+        verdictUrl: e.verdictUrl,
+        settleUrl: e.settleUrl ?? siblingUrl(e.verdictUrl, "settle"),
+        collection: e.collection,
+        fieldMap: e.fieldMap,
+        failMode: e.failMode === "open" ? "open" : "closed",
+        approvalAbove: e.approvalAbove,
+        timeoutMs: e.timeoutMs,
+        rail,
+        action,
+    };
+}
+/**
+ * Sanitize an untrusted escort block. Returns undefined on any problem
+ * (=> the route stays observe-only; fail-safe). L2/L11: fieldMap entries whose
+ * rail or intent field name is PII-shaped are dropped — a bad manifest can
+ * never pull PII into an intent.
+ */
+function cleanEscort(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return undefined;
+    const o = v;
+    if (typeof o.verdictUrl !== "string")
+        return undefined;
+    try {
+        const u = new URL(o.verdictUrl);
+        if (u.protocol !== "https:" && u.protocol !== "http:")
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof o.collection !== "string" || o.collection.length === 0 || o.collection.length > 64) {
+        return undefined;
+    }
+    const fieldMap = {};
+    if (typeof o.fieldMap === "object" && o.fieldMap !== null && !Array.isArray(o.fieldMap)) {
+        for (const [k, val] of Object.entries(o.fieldMap)) {
+            if (typeof val !== "string")
+                continue;
+            if (k.length === 0 || k.length > 64 || val.length === 0 || val.length > 64)
+                continue;
+            if ((0, denylist_1.isDeniedFieldPath)(k) || (0, denylist_1.isDeniedFieldPath)(val))
+                continue; // L2/L11 hard deny
+            fieldMap[k] = val;
+        }
+    }
+    if (Object.keys(fieldMap).length === 0)
+        return undefined;
+    const out = {
+        verdictUrl: o.verdictUrl,
+        collection: o.collection,
+        fieldMap,
+        failMode: o.failMode === "open" ? "open" : "closed",
+    };
+    if (typeof o.settleUrl === "string") {
+        try {
+            new URL(o.settleUrl);
+            out.settleUrl = o.settleUrl;
+        }
+        catch {
+            /* ignore bad settleUrl; sibling default applies */
+        }
+    }
+    if (typeof o.approvalAbove === "object" && o.approvalAbove !== null) {
+        const a = o.approvalAbove;
+        if (typeof a.field === "string" && typeof a.limit === "number" && Number.isFinite(a.limit)) {
+            out.approvalAbove = { field: a.field, limit: a.limit };
+        }
+    }
+    if (typeof o.timeoutMs === "number" && Number.isFinite(o.timeoutMs) && o.timeoutMs > 0 && o.timeoutMs <= 30_000) {
+        out.timeoutMs = o.timeoutMs;
+    }
+    return out;
+}
+/**
+ * Sanitize an untrusted identityField block. Returns undefined on any problem
+ * (=> the route attributes nothing extra; fail-safe). The source is EXEMPT
+ * from the capture denylist here — it targets the attribution channel
+ * (onBehalfOf), never a capture list. hash is true unless EXPLICITLY false
+ * (hashed-by-default is non-negotiable; raw is an owner opt-in boolean).
+ */
+function cleanIdentityField(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return undefined;
+    const o = v;
+    if (typeof o.source !== "string" || o.source.length === 0 || o.source.length > 128)
+        return undefined;
+    if (o.as !== "onBehalfOf")
+        return undefined; // the only supported target
+    return { source: o.source, as: "onBehalfOf", hash: o.hash === false ? false : true };
+}
+/**
+ * Structurally validate an untrusted manifest object. Returns a sanitized
+ * ObserveManifest or null (=> caller keeps the current manifest; fail-safe).
+ * L2: recognizer field lists are filtered through the hard PII denylist —
+ * a bad manifest cannot widen capture into PII-named fields.
+ */
+function validateManifest(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return null;
+    const m = raw;
+    if (typeof m.version !== "string" || m.version.length === 0 || m.version.length > 32)
+        return null;
+    if (!Array.isArray(m.recognizers))
+        return null;
+    const cleanFieldList = (v) => {
+        if (!Array.isArray(v))
+            return undefined;
+        const out = [];
+        for (const f of v) {
+            if (typeof f !== "string" || f.length === 0 || f.length > 128)
+                continue;
+            if ((0, denylist_1.isDeniedFieldPath)(f))
+                continue; // L2 HARD DENY — silently excluded
+            out.push(f);
+        }
+        return out.length > 0 ? out : undefined;
+    };
+    const recognizers = [];
+    for (const r of m.recognizers) {
+        if (typeof r !== "object" || r === null)
+            return null;
+        const e = r;
+        if (typeof e.host !== "string" ||
+            typeof e.method !== "string" ||
+            typeof e.path !== "string" ||
+            typeof e.rail !== "string" ||
+            typeof e.action !== "string") {
+            return null;
+        }
+        const identityField = cleanIdentityField(e.identityField);
+        if (identityField) {
+            // Belt and braces: the identity source is denylist-exempt ONLY in the
+            // identityField slot. An entry that ALSO lists it for capture is
+            // rejected outright — checked against the RAW lists (before the L2
+            // filter, which would silently hide PII-shaped sources).
+            const listsSource = (v) => Array.isArray(v) && v.some((f) => f === identityField.source);
+            if (listsSource(e.requestFields) || listsSource(e.responseFields))
+                return null;
+        }
+        // Crypto JSON-RPC method (optional): a short, denylist-safe operation name.
+        const rpcMethod = typeof e.rpcMethod === "string" && e.rpcMethod.length > 0 && e.rpcMethod.length <= 64
+            ? e.rpcMethod
+            : undefined;
+        recognizers.push({
+            host: e.host,
+            method: e.method.toUpperCase(),
+            path: e.path,
+            ...(rpcMethod ? { rpcMethod } : {}),
+            rail: e.rail,
+            action: e.action,
+            requestFields: cleanFieldList(e.requestFields),
+            responseFields: cleanFieldList(e.responseFields),
+            identityField,
+            escort: cleanEscort(e.escort),
+        });
+    }
+    const cleanMatchers = (v) => {
+        if (!Array.isArray(v))
+            return [];
+        const out = [];
+        for (const r of v) {
+            if (typeof r !== "object" || r === null)
+                continue;
+            const e = r;
+            if (typeof e.host !== "string")
+                continue;
+            out.push({
+                host: e.host,
+                method: typeof e.method === "string" ? e.method : undefined,
+                pathPrefix: typeof e.pathPrefix === "string" ? e.pathPrefix : undefined,
+            });
+        }
+        return out;
+    };
+    return {
+        version: m.version,
+        policyVersion: typeof m.policyVersion === "string" ? m.policyVersion : undefined,
+        recognizers,
+        counters: cleanMatchers(m.counters),
+        mutes: cleanMatchers(m.mutes),
+        // signature intentionally dropped until verification is implemented.
+    };
+}