@zackbart/connecta 0.34.1 → 0.35.0

package/dist/sent-secrets.d.ts

@@ -4,68 +4,200 @@ export declare function shortSecretWarning(): (value: string | undefined, logger
 export declare class SentSecrets {
     /** Normalized form to its strongest kind. */
     private readonly forms;
+    /** A form's leading units that encode only public auth framing; absent is none. */
+    private readonly frames;
     private readonly recipients;
+    private readonly mintedStates;
+    /** Encoded content this set already found clean, and whether under payload rules, which
+     * cover envelope ones. Cleared whenever the set changes. */
+    private memo;
     private privateChars;
+    /** The longest form; whether any comes from a value shorter than K; whether any is not ASCII. */
+    private widestForm;
+    private smallForms;
+    private unicodeForms;
     /** The shortest form left unregistered; any string this long might contain it. */
     private unmatched;
-    private unicode;
     private views;
     private store;
     private unregistered;
+    /** Every form of `value`. Its first `frame` units are public auth framing, which no form's
+     * fragment index starts in: a base64 form's framing ends at its last unit encoding only it. */
     private register;
     /** The request receives existing and future secrets from every context. */
     include(source: SentSecrets): void;
-    add(value: string): void;
+    /** A credential, as sent and in the auth framings a vendor may echo it with. Its first
+     * `frame` units, such as a header's `Basic `, are framing too. */
+    add(value: string, frame?: number): void;
     /** Explicit secrets use the same floor as every other credential. */
     secret(value: string): void;
+    /** An identifier sent beside a credential, such as a confidential client's ID or a Basic
+     * username: matched whole only, since consent URLs and metadata carry its parts by design. */
+    identifier(value: string): void;
     /** Submitted writeOnly strings and numbers join this request's set, including property
      * names inside a private object. Empty strings, booleans, and null carry no text. */
     arguments(args: unknown, schema: JsonSchema | undefined): void;
-    /** Structural fields must be refused, never repaired into different URLs. */
+    /** Structural fields must be refused, never repaired into different URLs. A field the checker
+     * would change under the boundary's rules is refused: one holding a whole form or any K-unit
+     * run of one, in any view of the lattice. With `ignoreCase`, as for a host URL parsing
+     * lowercased, the lowercased field is also checked against lowercased forms. */
     contains(value: string, ignoreCase?: boolean): boolean;
     containsUrl(value: string): boolean;
     header(value: string): void;
     request(input: RequestInfo | URL, init?: RequestInit): void;
     /** Serialized wire text about to be returned, stored, or paged, under payload rules. */
     text(value: string): string;
-    /** Copy only what changes, including non-enumerable Error fields; never retain a raw cause.
-     * Payload rules apply where downstream or guest data enters; envelopes repeat literal
-     * replacement. */
-    redact<T>(value: T, mode?: "payload" | "prose" | "envelope"): T;
+    /** A plain-data snapshot of `value` with every match removed: own enumerable data properties
+     * (an error's own fields, non-enumerable ones included), read once each. Accessors are never
+     * invoked, except an error's stack and the accessors its class defines, read once into the
+     * copy. The original object is never returned, so nothing read later can differ from what was
+     * checked. Payload rules apply where downstream or guest data enters; the envelope pass at the
+     * agent boundary repeats every check except short private values, which would rewrite
+     * Connecta's own identifiers, counts and addresses. `values` applies payload rules to every
+     * value of a parsed vendor body but keeps its object keys, which result safety and projections
+     * match by name: a renamed key would hide a field from the rule that withholds it. JSON inside
+     * a string is a value, so its keys are still checked. The connector's result and failures are
+     * checked again under payload rules, keys included, at the `api()` boundary and the invocation. */
+    redact<T>(value: T, mode?: "payload" | "envelope" | "values"): T;
+    /** Whether payload redaction would change anything in `value`, for fields that must be
+     * refused rather than rewritten. */
+    changes(value: unknown): boolean;
+    /** Relay state and links Connecta minted and authenticates are framing, not payload: they
+     * hold sealed downstream state or Connecta's own facts, never downstream text or arguments,
+     * and a coincidental match must not corrupt them. Never admit downstream-authored state
+     * here. Exact value membership survives JSON serialization within this request. */
+    mintedState(value: string): string;
+    /** Base64, or base64url with `url`, of bytes Connecta returns to an agent. No later pass
+     * reads through an encoding the output does not declare, so the bytes are checked first: as
+     * byte-valued units, as UTF-8 text, and through any base64 they carry, then the encoding
+     * itself. Content holding a match encodes the placeholder instead. Downstream content takes
+     * payload rules. `claims` is JSON Connecta assembled, such as a page cursor: its own names,
+     * counts and fingerprints beside downstream values it already redacted under payload rules.
+     * Every string in it is checked under payload rules, since each downstream value a cursor
+     * holds is one, and the whole text and its encoding under the boundary's, so Connecta's keys
+     * and counts never meet a short private value. Checked so, it is remembered as clean for later
+     * passes over the same set. */
+    encode(bytes: Uint8Array, { url, claims }?: {
+        url?: boolean;
+        claims?: boolean;
+    }): string;
+    /** Text pieces a provider reads as one lane, such as rich-text runs with metadata between
+     * them: checked joined, each match replaced in every piece it touches. */
+    parts(parts: string[]): string[];
+    /** Complete and unfinished forms in bounded text, all found against its original bytes.
+     * Replacing a complete match first could hide a longer open match containing it. Even a
+     * one-unit shared prefix is withheld: a read boundary gives no evidence it is public text.
+     * Each decoded layer sets aside a trailing escape the read cut short, which is withheld. */
+    redactOpenTail(text: string): string;
     /** Credentials alone: later calls keep the private arguments they submit, and cached
      * catalogs never depend on one request's arguments. */
     redactCredentials<T>(value: T): T;
     private idle;
     private scan;
     private matcher;
+    /** Short private forms, matched as substrings of payload text. */
+    private shortMatcher;
+    /** Forms with no indexed fragment, such as identifiers, matched whole. */
+    private wholeMatcher;
+    private fragments;
     private credentials;
-    /** Strings at least this long might hold a form that was never matched. */
-    private floor;
-    /** Every raw and JSON-unescaped match, mapped to source spans before any replacement. Text
-     * decodes one more layer while the last one could still hold an escape, up to
-     * MAX_DECODE_LEVELS counting the JSON strings it came from. Work beyond the call's budget
-     * or that depth returns undefined, which withholds the string. */
-    private find;
-    /** A structured leaf, property name, or prose. A short private form withholds prose
-     * wherever it occurs, and a leaf only when the whole leaf is that form. */
-    private string;
-    /** A number, boolean, or null matching by its canonical text becomes a placeholder string. */
-    private scalar;
-    /** JSON objects, arrays, and string literals are parsed and walked, nested JSON strings
-     * included; their serialized bytes must then hold no literal the walk cannot see, such as
-     * one spanning tokens. Other text is prose or a structured leaf. */
-    private wire;
-    /** Iterative and copy-on-write: only containers on a changed path are copied. A container's
-     * entries are counted against the node budget before it is walked; a cycle or a container
-     * past MAX_WALK_DEPTH is withheld, and one past the node budget is checked as serialized text. */
-    private walk;
-    /** A container larger than the node budget is scanned as serialized text, Error fields
-     * included: kept unchanged when nothing registered appears, otherwise withheld whole. */
-    private serialized;
-    /** Skill supporting files may contain arbitrary bytes, including echoes. */
-    private blob;
-    /** Match across blocks before isError/JSON unwrapping concatenates them. */
-    private joinedContent;
+    /** Every form lowercased, for fields such as hosts that reach output lowercased. */
+    private folded;
+    /** The shortest text that might hold something this set cannot check, which is withheld: a
+     * K-unit run of a value too large to register (or a whole short one), or of a form past the
+     * fragment index's or a matcher's capacity. Envelope scans rely on the payload scans for
+     * unregistered values. */
+    private limit;
+    /** Whether an open tail could begin a form this set never registered or indexed. */
+    private uncheckedTail;
+    /** A form whole: a leaf, key, number, boolean or decoded view equal to one, as it stands or
+     * under JSON escapes. This is how a tiny private value is matched. */
+    private whole;
+    /** Every K-unit run of a registered form, every identifier form, and in payload text every
+     * short private form, in the raw text and each JSON-unescaped layer, mapped to source spans
+     * before any replacement. A layer decodes while the one above holds an escape; each is scanned
+     * only around the escapes it decoded, since any other match was found a layer up. Work beyond
+     * the call's budget returns undefined, which withholds the text. */
+    private spansOf;
+    /** Add the span of an unfinished form the text ends inside, at any decoded layer. */
+    private openSpans;
+    /** The one string checker. Every string that can reach an agent, an executor or storage is
+     * checked here, under the whole lattice: projection leaves and numbers, object keys, declared
+     * binary fields, the bytes of typed arrays and ArrayBuffers, cursor claims and every encoding
+     * Connecta produces, error fields, provider lanes, bounded reads and structural fields.
+     * `parts` is one lane: matched joined, raw and through its JSON layers, each match replaced in
+     * every part it touches, a tiny private value withholding a part it equals, and every part
+     * withheld that the set cannot fully check. Then every text and declared binary part is
+     * decoded in each of its text views (see textViews), its base64 and base64url runs and a
+     * declared field's whole content are decoded and checked as bytes, UTF-8 and nested base64,
+     * and so are byte parts; a part a decoded view matches is withheld whole. Each decode is
+     * charged to the call's budget, and a part it cannot pay for is withheld. A `bounded` lane is
+     * text cut short, which also loses an unfinished tail. Nothing else matches a string that is
+     * returned: the matching steps below are called only from here. */
+    private checked;
+    /** Cursor claims: the whole text and its encoding under the boundary's rules, then every
+     * string in the JSON under payload rules. Keys and numbers are Connecta's own names and
+     * counts: a downstream value enters a cursor only as a string. */
+    private claimsClean;
+    /** The shortest base64 run inside a view that is decoded: long enough to carry the smallest
+     * piece this scan matches (see SHORT_RUN_UNITS). */
+    private runUnits;
+    /** The text views base64 is found in: the text; one layer of its JSON escapes decoded; its
+     * percent escapes decoded; and its form decoding, a `+` read as a space with any percent
+     * escapes decoded, whether or not it holds one. Two decodes chained, such as percent escapes
+     * inside JSON escapes, are not a view. Undefined when the work budget cannot pay for them. */
+    private textViews;
+    /** Text and declared binary parts carrying base64 or base64url, in any text view, the whole
+     * view or a run inside it, and byte parts, whose decoded bytes or their UTF-8 text hold a
+     * match are withheld whole: no later pass reads through an encoding the output does not
+     * declare. A declared field is also decoded whole, as its reader decodes it. Every part's
+     * decoded views are matched together, as one lane between unmatched separators. Each decode
+     * is paid for from the call's work budget; a part the budget cannot check is withheld. */
+    private encodedLeaves;
+    /** The parts' joined text, matched once, with each part's replacement. A tiny or short
+     * private value equal to a whole part withholds it. A number or a serialized container that
+     * a match touches is withheld whole. A bounded lane also loses an unfinished tail, and is
+     * withheld whole when the set could not tell where one begins. */
+    private safeParts;
+    /** Leaves too large to match joined within the work budget: each is matched alone, in order,
+     * and one that does not fit is withheld without spending what a smaller one needs. A run
+     * crossing from one kept leaf into the next, through any short leaves between them, is then
+     * matched SEAM_UNITS deep on each side of the seam. */
+    private leafByLeaf;
+    /** Serialized JSON whose keys, syntax and leaves together hold a K-unit run of a form: one
+     * spanning tokens, which no leaf holds alone, withholds the whole text. A run inside one
+     * string or number is a leaf's, already matched in the projection. */
+    private spansTokens;
+    /** The output boundary. One walk reads every field once, from its descriptor, and projects
+     * every string and number leaf in serialization order, nested JSON strings parsed and errors'
+     * own fields included, declared binary fields and the bytes and numbers typed binary holds
+     * among them; the one checker matches the joined projection, so a form split across adjacent
+     * leaves is found, and only the affected piece of each leaf is written back. Keys and scalars
+     * go through the same checker alone. Fixed framing words and tags, outcome booleans, and on an
+     * error its classification code and a name its registered class gives it (redaction-identity's
+     * fixed allowlist) are kept: nothing downstream chooses them. Every other field is matched,
+     * whatever its name; an error's other name is projected like any field and withheld whole when
+     * anything changes any part of it.
+     *
+     * What returns is what was checked, and only JSON data: strings, numbers, booleans, null,
+     * plain objects and arrays, a fresh built-in Uint8Array, and error copies. A caller's container
+     * is returned as it stands only as verified plain data, so a later read returns the same
+     * values: its prototype is Object.prototype, Array.prototype or null, nothing on its chain is a
+     * toJSON, it holds no symbol field and an array no field but its indices (a hole checked
+     * through its prototypes), every field is a data property this walk read, and nothing in it
+     * changed. Anything else is a copy. An error always is, of its own class, with the accessors in
+     * ERROR_ACCESSORS and those its chain defines read once into fields and a toJSON shadowed, never
+     * read; an object of any other class is plain data, its chain's accessors unread; an array that
+     * is not plain is a plain array of its indices; a String, Number or Boolean wrapper is its
+     * primitive. A typed array, DataView or ArrayBuffer becomes a fresh Uint8Array of the bytes it
+     * held, which are checked as bytes, and as numbers with any other elements it held. A function
+     * or symbol is withheld. A container's own accessor is never invoked: its copy leaves it out,
+     * or holds the placeholder at an array index. A toJSON is called once, as serialization would,
+     * and replaced by its checked result. A change copies every container on its path on first
+     * write, so no caller's value is ever mutated, and a container past the node budget is
+     * withheld whole. Copies hold writable, configurable data properties and keep the identity
+     * facts registered in redaction-identity. */
+    private project;
 }
 export declare function sentSecretsFor(ctx: ConnectorContext): SentSecrets;
 /** One identity per upstream request, including all discovery and call work. */
@@ -73,16 +205,41 @@ export declare function sentSecretsForRequest(scope: object, secrets?: SentSecre
 /** The agent-facing choke point. Apply to values before bridge serialization
  * and to serialized wire text, so JSON escapes and structured strings share
  * the same rule. Payloads were redacted where they entered; this boundary
- * repeats credential and literal private-value replacement around Connecta's
- * own envelopes, whose identifiers and counts are never private data. */
+ * repeats every check but short private values around Connecta's own
+ * envelopes, whose identifiers and counts are never private data. */
 export declare function redactAgentOutput<T>(secrets: SentSecrets, value: T): T;
 /** Wrap the complete operation table, including rejections. Adding an operation
  * cannot add an unredacted exit. A direct invocation owns a fresh scope unless
  * its HTTP request supplied one. */
 export declare function agentOutputOperations<T extends Record<string, (...args: never[]) => Promise<unknown>>>(create: (scope: object) => T, requestScope?: object): T;
-/** Slot reads cover custom handlers too, including keys put in query strings. */
+/** Slot reads cover custom handlers too, including keys put in query strings. A field named
+ * as an identifier (an application or client ID, a username, a public key) is matched whole. */
+export declare function registerCredentialValues(secrets: SentSecrets, values: import("./types.js").ConnectorCredentialValues | null): void;
 export declare function trackCredentialReads(ctx: ConnectorContext): void;
+/** A connector's result or error as it enters: every connector's credentials and the
+ * request's private arguments, under payload rules. */
 export declare function redactSentSecrets<T>(ctx: ConnectorContext, value: T): T;
+/** Everything the context's request sent: every connector's credentials and the
+ * request's private arguments, which a context's own set does not hold. */
+export declare function requestSentSecrets(ctx: ConnectorContext): SentSecrets;
+/** Downstream text, or a parsed body, about to be cut short, trimmed, normalized or
+ * extracted from. Redact it whole first: a cut through an echoed form can leave a remnant
+ * shorter than any fragment the output boundary matches, and a normalized number or
+ * extracted substring may no longer hold the form at all. */
+export declare function redactBeforeCut<T>(ctx: ConnectorContext, value: T): T;
+/** Base64, or base64url with `url`, of bytes or UTF-8 text Connecta returns to an agent: a
+ * download, an attachment, a REST body, a page cursor. Every such encoding goes through here,
+ * since no later pass reads through an encoding the output does not declare: the content is
+ * checked first with the request's set, and content holding a match encodes the placeholder.
+ * A cursor passes `claims`: connecta's own counts and fingerprints beside downstream values it
+ * already redacted (`redactSentSecrets`), checked under the boundary's rules. */
+export declare function encodeForAgent(ctx: ConnectorContext, content: Uint8Array | string, options?: {
+    url?: boolean;
+    claims?: boolean;
+}): string;
+/** Downstream text read only up to a bound, as a field an agent reads: whole forms are
+ * replaced, and so is a tail that begins one the read stopped inside. */
+export declare function redactBoundedRead(ctx: ConnectorContext, text: string): string;
 /** Sanitize listing facts before any cache or consumer receives them. A name
  * cannot be rewritten without changing dispatch, and dropping one entry would
  * publish a partial catalog, so refuse the complete listing instead. */