@zackbart/connecta 0.30.0 → 0.31.0

package/dist/providers/_shared/rest/value-safety.d.ts

@@ -0,0 +1,151 @@
+import type { Operation, OperationIndex } from "./operation-index.js";
+/** What a removed secret reads as. */
+export declare const REDACTED = "[redacted]";
+/** Credential vocabulary over normalized names, matched anywhere; mirrors `scripts/value-safety.mjs`. */
+export declare const CREDENTIAL_WORDS: string[];
+/** Credential vocabulary matched at the end of a normalized name; mirrors the script. */
+export declare const CREDENTIAL_SUFFIX: RegExp;
+/** Suffixes of metadata about a credential (ids, prefixes, last four, counts, expiry, scopes); mirrors the script. */
+export declare const METADATA_SUFFIXES: string[];
+/** Exact metadata names that contain a credential word; mirrors the script. */
+export declare const METADATA_NAMES: string[];
+export type ValueSafetyVerdict = {
+    readonly verdict: "refuse";
+    readonly reason: string;
+} | {
+    readonly verdict: "redact";
+    readonly reason: string;
+    /**
+     * Reviewed field paths into the data a tool returns: `a.b` (a list on
+     * the way is traversed item by item), `[]` for list items, `{}` or `*`
+     * for every value of a map, `@keys` for a map keyed by secrets (keys
+     * become placeholders), `[?env]` for list items whose `type` names an
+     * environment variable, `[?credential]` for list items labelled with a
+     * credential name, `[?header]` for header, cookie, or query rules. A
+     * `url:` prefix sanitizes a URL; an `origin:` prefix (or `#url` suffix)
+     * keeps only its scheme and host. Every other value at a path becomes
+     * `[redacted]`.
+     */
+    readonly paths: readonly string[];
+    /** Reviewed metadata paths the key-name heuristic leaves (children are still checked). */
+    readonly keep?: readonly string[];
+    /** See the `safe` verdict. */
+    readonly errors?: "vendor";
+} | {
+    readonly verdict: "safe";
+    readonly reason: string;
+    /** Reviewed metadata paths the key-name heuristic leaves (children are still checked). */
+    readonly keep?: readonly string[];
+    /**
+     * The error policy. By default a reviewed operation's failures carry the
+     * vendor's codes and statuses but never its text, which may echo a
+     * stored secret. `vendor` is a reviewed exception for operations whose
+     * errors cannot: the vendor's text passes (and still meets the
+     * sent-secrets matcher).
+     */
+    readonly errors?: "vendor";
+};
+/** One field name reviewed for a whole vendor whose objects repeat across operations (Stripe's). */
+interface FieldReview {
+    readonly verdict: "redact" | "keep";
+    readonly reason: string;
+}
+/**
+ * A reviewed rule for one resource type, applied to every object whose
+ * discriminator names it wherever a response embeds it: the top level, a list,
+ * a search result, an expansion, an event's `data.object`. Operation verdicts
+ * review what an operation returns by shape; resource rules are the backstop
+ * for what expansions can put anywhere.
+ */
+/**
+ * When an object is provably unbound (a guest Checkout Session), stated as
+ * data so `providers:spec` can hold it to the pinned schema: every binding
+ * field the schema has must be listed, in `bindings` or, with a reason, in
+ * `unbound`.
+ */
+interface GuestCondition {
+    /**
+     * Fields that bind the object to an identity or its saved methods. Each
+     * must be absent, null, empty, or one of the listed values that bind
+     * nothing (`customer_creation: "if_required"`).
+     */
+    readonly bindings: Readonly<Record<string, readonly string[]>>;
+    /** Identity-named fields that bind nothing (guest prefill or collected details), with the reason. */
+    readonly unbound: Readonly<Record<string, string>>;
+    /** Fields whose value must be one of these (a Checkout Session's `mode: "payment"`). */
+    readonly requires?: Readonly<Record<string, readonly string[]>>;
+}
+interface ResourceRule {
+    readonly reason: string;
+    /** Reviewed paths relative to the object, in the operation path language. */
+    readonly paths?: readonly string[];
+    /**
+     * Fields whose string is a payer-facing URL the resource exists to hand out
+     * (a guest Checkout page), returned without URL sanitizing: its fragment is
+     * opaque state the page needs. With `guest`, only while the object is
+     * provably a guest's; otherwise its `withheld` paths go.
+     */
+    readonly verbatim?: readonly string[];
+    readonly guest?: GuestCondition;
+    readonly withheld?: readonly string[];
+}
+interface ResourceRules {
+    /** The field that names an object's type (Stripe's `object`). */
+    readonly key: string;
+    /** Sibling fields holding a partial copy of a discriminated object (an event's `previous_attributes`). */
+    readonly partials?: readonly string[];
+    readonly rules: Readonly<Record<string, ResourceRule>>;
+}
+export interface ValueSafetyTable {
+    /** Display name in refusals. */
+    readonly title: string;
+    /** The reviewed verdict for every flagged operation, keyed `METHOD /path template`. */
+    readonly operations: Readonly<Record<string, ValueSafetyVerdict>>;
+    /**
+     * Field names reviewed once for the vendor: `redact` wherever the name
+     * appears, `keep` as metadata the heuristic leaves wherever it appears
+     * (children are still checked). Keyed by the exact field name.
+     */
+    readonly fields?: Readonly<Record<string, FieldReview>>;
+    /** Operations whose whole body is environment variables: every value field goes, `key` or not. */
+    readonly envBodies?: RegExp;
+    /** Keys whose string-list values are permission scopes (action names under a resource), never secrets. */
+    readonly scopeMaps?: readonly string[];
+    /** Rules for resource types wherever they appear, for vendors whose objects carry a type discriminator. */
+    readonly resources?: ResourceRules;
+}
+export declare const refuse: (reason: string) => ValueSafetyVerdict;
+export declare const redact: (reason: string, paths: readonly string[], keep?: readonly string[]) => ValueSafetyVerdict;
+export declare const safe: (reason: string, keep?: readonly string[]) => ValueSafetyVerdict;
+/** A verdict whose failures keep the vendor's text: reviewed, for operations whose errors echo no stored secret. */
+export declare const vendorErrors: (verdict: ValueSafetyVerdict) => ValueSafetyVerdict;
+/** Paths under each prefix; a `url:` or `origin:` directive stays in front. */
+export declare function under(prefixes: readonly string[], paths: readonly string[]): string[];
+/**
+ * Whether a key names a credential: a credential word anywhere in a name
+ * that is not metadata (Vercel's former rule), or a credential suffix
+ * (Cloudflare's).
+ */
+export declare function credentialName(name: string): boolean;
+/** Whether every segment of a reviewed path is in the path language; the harness checks each table. */
+export declare function validPath(raw: string): boolean;
+/** What a vendor's tools ask of its reviewed table. */
+export interface ValueSafety {
+    readonly table: ValueSafetyTable;
+    /** The reviewed verdict for an operation, if it was flagged. */
+    verdict(method: string, template: string): ValueSafetyVerdict | undefined;
+    /** The refusal for a `refuse` verdict, before anything is sent. */
+    refusal(method: string, template: string): string | undefined;
+    /** One success body made value-safe: reviewed paths, environment bodies, resource rules, then the heuristic. */
+    redact(data: unknown, method: string, template: string): unknown;
+    /**
+     * Whether a failure's vendor text is withheld: any reviewed operation
+     * unless its verdict says `errors: "vendor"`, or an unreviewed one whose
+     * request accepts a credential-named field (an error may echo what was
+     * submitted). Codes and statuses still route.
+     */
+    withholdsErrors(op: Operation): boolean;
+}
+/** A vendor's value-safety mechanism over its reviewed table and pinned index. */
+export declare function valueSafety(table: ValueSafetyTable, index: () => OperationIndex): ValueSafety;
+export {};