@bounded-sh/observe 0.1.0

package/dist/manifest.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Escort (enforce) config for a route (SPEC §4.2 Mode A, T9). Present only on
+ * routes a promoted policy has escorted. When set, the interceptor makes ONE
+ * verdict round-trip BEFORE the call fires; the call still fires from the
+ * customer's own process (payload never transits Bounded).
+ */
+export interface EscortConfig {
+    /** Full URL the interceptor POSTs the candidate intent to for a verdict,
+     * e.g. "https://acme-dev.bounded.sh/api/verdict". Sensor-key authed. */
+    verdictUrl: string;
+    /** Full URL for the fire-and-forget settle report. Defaults to verdictUrl's
+     * sibling "/settle". */
+    settleUrl?: string;
+    /** Enforcement collection (execcfg key), e.g. "stripe_refunds". */
+    collection: string;
+    /** Rail request-body field -> intent field, e.g. {charge:"chargeId",
+     * amount:"amountCents"}. Extracted from the request the app ALREADY built. */
+    fieldMap: Record<string, string>;
+    /** Local behavior when the verdict endpoint is unreachable (U18). Default
+     * "closed" (immediate clean local error); "open" = proceed + flag. */
+    failMode: "closed" | "open";
+    /** Informational only — the server owns the real approval routing decision. */
+    approvalAbove?: {
+        field: string;
+        limit: number;
+    };
+    /** Verdict round-trip timeout, ms (default 3000). */
+    timeoutMs?: number;
+}
+/**
+ * Wanted-identity attribution for a route: an org may WANT a field like
+ * customer_email for per-user limits (per-actor enforcement + rollups). The
+ * value flows through the ATTRIBUTION channel (event.onBehalfOf) — NEVER the
+ * telemetry capture lists. Hashed by default IN-PROCESS (the raw value never
+ * leaves); raw values ride only on an explicit owner opt-in (hash:false).
+ */
+export interface IdentityFieldConfig {
+    /** Request-body field (dot path) holding the per-user principal, e.g. "customer_email". */
+    source: string;
+    /** The only supported target: the envelope's onBehalfOf attribution slot. */
+    as: "onBehalfOf";
+    /** true (DEFAULT) ⇒ onBehalfOf = "sha256:<hex(sha256(value))>", computed
+     * in-process. false = EXPLICIT owner opt-in to raw values. */
+    hash: boolean;
+}
+export interface RecognizerEntry {
+    /** Exact destination host (post-alias), e.g. "api.stripe.com". */
+    host: string;
+    /** Uppercase method. */
+    method: string;
+    /** Templated path this entry matches exactly, e.g. "/v1/charges/{id}/refunds". */
+    path: string;
+    /**
+     * JSON-RPC operation this entry matches (crypto rails). When set, the entry
+     * matches host + POST + the request body's JSON-RPC `method === rpcMethod`
+     * INSTEAD of the exact path — every RPC call POSTs to one path ("/") with the
+     * operation in the body, so path alone cannot tell `sendTransaction` from
+     * `getBalance`. Keyed separately (`${host}|rpc|${rpcMethod}`); entries WITHOUT
+     * rpcMethod keep matching by host+method+path exactly as before. */
+    rpcMethod?: string;
+    rail: string;
+    action: string;
+    /** SAFE request-body fields to recognize (dot paths). L2 denylist still applies. */
+    requestFields?: string[];
+    /** SAFE response-JSON fields to recognize (dot paths). L2 denylist still applies. */
+    responseFields?: string[];
+    /** Wanted identity → onBehalfOf. Exempt from the capture denylist ONLY in
+     * this slot; it can never appear in requestFields/responseFields (entries
+     * that try are rejected by validateManifest — belt and braces). */
+    identityField?: IdentityFieldConfig;
+    /** Escort (enforce) config — set only on promoted/escorted routes. */
+    escort?: EscortConfig;
+}
+/** A compiled, resolved escort (settleUrl + rail + action filled in). */
+export interface CompiledEscort extends EscortConfig {
+    settleUrl: string;
+    rail: string;
+    action: string;
+}
+export interface RouteMatcher {
+    host: string;
+    method?: string;
+    /** Matches when the templated path starts with this prefix. */
+    pathPrefix?: string;
+}
+export interface ObserveManifest {
+    /** Registry version stamped into rec.registryVersion. */
+    version: string;
+    /** Content-hashed policy version (stamped on events when present). */
+    policyVersion?: string;
+    recognizers: RecognizerEntry[];
+    /** Routes forced into exact per-minute counter aggregation. */
+    counters: RouteMatcher[];
+    /** Routes never reported at all (capture policy `mute`). */
+    mutes?: RouteMatcher[];
+    /** TODO: signed-manifest verification (see header comment). Ignored for now. */
+    signature?: string;
+}
+/** Built-in default manifest: metadata-only + curated safe-field recognizers.
+ * SAFE fields only: amounts (cents), opaque IDs, model names, token counts. */
+export declare const BUILTIN_MANIFEST: ObserveManifest;
+/** Env-derived escort pin parameters (register preload, BOUNDED_* env). Kept
+ * on ObserveConfig so the pin is re-applied over EVERY manifest swap — a
+ * fetched manifest can never silently drop the pinned enforcement. */
+export interface EscortPin {
+    verdictUrl: string;
+    collection: string;
+    failMode: "closed" | "open";
+    timeoutMs?: number;
+}
+/**
+ * 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.
+ */
+export declare function escortedManifest(base: ObserveManifest, verdictUrl: string, collection: string, failMode: "closed" | "open", timeoutMs?: number): ObserveManifest;
+/** Apply an (optional) env escort pin over a manifest. No pin = passthrough. */
+export declare function withEscortPin(base: ObserveManifest, pin: EscortPin | undefined): ObserveManifest;
+/** Compiled manifest index for O(1)-ish hot-path decisions. */
+export declare class CompiledManifest {
+    readonly manifest: ObserveManifest;
+    readonly source: "builtin" | "override" | "fetched";
+    /** host|METHOD|templatedPath -> entry (non-rpc entries only). */
+    private readonly exact;
+    /** host|rpc|rpcMethod -> entry (crypto JSON-RPC entries; matched on the
+     * request body's `method`, never the path). */
+    private readonly rpc;
+    /** Hosts carrying any rpcMethod recognizer (gates the JSON-RPC body parse). */
+    private readonly rpcHosts;
+    /** Hosts with any recognizer (request-body capture allowed). */
+    readonly captureHosts: Set<string>;
+    /** host|METHOD|templatedPath entries whose responseFields need a body read. */
+    private readonly respCapture;
+    /** host|METHOD|templatedPath -> compiled escort (non-GET/HEAD routes only). */
+    private readonly escorts;
+    /** 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. */
+    readonly hasEscorts: boolean;
+    constructor(manifest: ObserveManifest, source: "builtin" | "override" | "fetched");
+    get version(): string;
+    recognize(host: string, method: string, pathTemplate: string): RecognizerEntry | undefined;
+    /** 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: string): boolean;
+    /** Recognize a crypto JSON-RPC call by host + the body's `method`. */
+    recognizeRpc(host: string, rpcMethod: string): RecognizerEntry | undefined;
+    wantsResponseBody(host: string, method: string, pathTemplate: string): boolean;
+    /** Compiled escort for a route, or undefined. Reads are never escorted. */
+    escort(host: string, method: string, pathTemplate: string): CompiledEscort | undefined;
+    private matchList;
+    isCounterRoute(host: string, method: string, pathTemplate: string): boolean;
+    isMuted(host: string, method: string, pathTemplate: string): boolean;
+}
+/**
+ * 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.
+ */
+export declare function validateManifest(raw: unknown): ObserveManifest | null;