@zackbart/connecta 0.34.1 → 0.36.0

package/dist/redaction-identity.js

@@ -0,0 +1,47 @@
+const stores = [];
+/** Keep `store`'s entry for a value on every redacted copy of that value. */
+export function followRedactedCopies(store) {
+    stores.push(store);
+    return store;
+}
+/** `to`, a redacted copy of `from`, takes every registered fact about `from`. */
+export function redactedCopyOf(from, to) {
+    for (const store of stores) {
+        if (!store.has(from))
+            continue;
+        if (store instanceof WeakMap)
+            store.set(to, store.get(from));
+        else
+            store.add(to);
+    }
+    return to;
+}
+// Error classes whose instances' `name` redaction keeps whatever was sent, by identity: the
+// built-in errors, DOMException, and connecta's and the pinned MCP SDK's own classes, each
+// registered with literals beside its class. Any other name an error carries, including one a
+// custom class gives itself, is checked like other text.
+const errorNames = new Map();
+/** Keep `names` as the `name` of `ctor`'s instances and its subclasses'. */
+export function keepErrorName(ctor, ...names) {
+    errorNames.set(ctor.prototype, new Set(names));
+}
+/** Whether a registered class on `prototype`'s chain gives its instances `name`. */
+export function keptErrorName(prototype, name) {
+    for (let at = prototype; at; at = Object.getPrototypeOf(at))
+        if (errorNames.get(at)?.has(name))
+            return true;
+    return false;
+}
+for (const [ctor, name] of [
+    [Error, "Error"],
+    [TypeError, "TypeError"],
+    [RangeError, "RangeError"],
+    [SyntaxError, "SyntaxError"],
+    [ReferenceError, "ReferenceError"],
+    [EvalError, "EvalError"],
+    [URIError, "URIError"],
+    [AggregateError, "AggregateError"],
+])
+    keepErrorName(ctor, name);
+if (typeof DOMException === "function")
+    keepErrorName(DOMException, "DOMException", "AbortError", "TimeoutError");

package/dist/redaction-marker.js

@@ -0,0 +1,125 @@
+// The placeholder redaction leaves where it removed a value. Sent-secret redaction (sent-secrets.ts)
+// and REST value safety (providers/_shared/rest/value-safety.ts) write the same text.
+/** What a removed value reads as. */
+export const REDACTED = "[redacted]";
+/**
+ * Whether redaction altered a value: it carries the placeholder. The provider kit redacts sent
+ * secrets from every value of a vendor body before result safety reads it, so a rule that decides
+ * on a value (a type discriminator, a record's label or type, a URL's scheme or parameter names,
+ * a Content-Type) can find the placeholder where the vendor wrote what the rule matches.
+ * Such a decision takes its most protective outcome (#703).
+ */
+export function redactionAltered(value) {
+    return typeof value === "string" && value.includes(REDACTED);
+}
+// Numeric references may omit `;`; named HTML references have at most 31 characters. Require
+// their `;` so a real query separator such as `&amp=value` remains a separator. Legacy `amp`
+// may omit its semicolon only before the `#` of a nested numeric reference.
+const CHARACTER_REFERENCE = /(?:#([0-9]+);?|#x([0-9a-f]+);?|([a-z][a-z0-9]{1,30});|(amp)(?=#))/iy;
+// Named references whose decoded characters all belong to a credential's alphabet (`fjlig` is `fj`).
+const CREDENTIAL_REFERENCE = /^(?:plus|sol|equals|percnt|lowbar|underbar|fjlig)$/;
+/**
+ * The end of a character reference at `at`, or `at` itself. A reference is value data, including
+ * one spelling a delimiter. Decode only to find nested-reference boundaries and, when
+ * `credentialOnly`, to require credential data or an ampersand. No decoded text is returned.
+ * Known signing values read possible named references fail-closed without a browser entity table.
+ * Each successful read advances over disjoint source characters.
+ */
+export function characterReferenceEnd(text, at, credentialOnly = false) {
+    if (text.charCodeAt(at) !== 0x26)
+        return at;
+    return referenceBodyEnd(text, at + 1, at, credentialOnly);
+}
+/** A numeric reference body whose leading characters redaction may have taken, including its `&`. */
+export function bareReferenceEnd(text, at, credentialOnly = false) {
+    if (text.charCodeAt(at) !== 0x23 || !/[0-9x]/i.test(text[at + 1] ?? ""))
+        return at;
+    return referenceBodyEnd(text, at, at, credentialOnly);
+}
+function referenceBodyEnd(text, from, at, credentialOnly) {
+    let end = at;
+    let readable = false;
+    while (from < text.length) {
+        CHARACTER_REFERENCE.lastIndex = from;
+        const reference = CHARACTER_REFERENCE.exec(text);
+        if (!reference)
+            break;
+        end = CHARACTER_REFERENCE.lastIndex;
+        const name = (reference[3] ?? reference[4])?.toLowerCase();
+        const code = reference[1] !== undefined
+            ? Number(reference[1])
+            : reference[2] !== undefined
+                ? Number.parseInt(reference[2], 16)
+                : name === "amp"
+                    ? 0x26
+                    : -1;
+        const ampersand = code === 0x26;
+        readable = ampersand || credentialUnit(code) || (name !== undefined && CREDENTIAL_REFERENCE.test(name));
+        if (!readable && name === undefined && text.charCodeAt(end - 1) !== 0x3b)
+            readable = prefixSpellsCredential(reference[1] ?? reference[2], reference[1] === undefined ? 16 : 10);
+        if (!ampersand)
+            break;
+        from = end;
+    }
+    return credentialOnly && !readable ? at : end;
+}
+// Without its `;`, a numeric reference's digits may run into the value's next characters (`&#47`
+// then `9` reads as `&#479`), so a short digit prefix spelling credential data counts.
+function prefixSpellsCredential(digits, radix) {
+    let at = 0;
+    while (digits.charCodeAt(at) === 0x30)
+        at++;
+    const limit = radix === 16 ? 2 : 3;
+    for (let length = 1; length <= limit && at + length <= digits.length; length++)
+        if (credentialUnit(Number.parseInt(digits.slice(at, at + length), radix)))
+            return true;
+    return false;
+}
+/**
+ * A credential's data: the base64 and base64url alphabets (letters, digits, `+`, `/`, `=`, `-`,
+ * `_`) and `%` escapes. A remainder of `+/` alone is still the end of a base64 value.
+ */
+function credentialUnit(code) {
+    return ((code >= 0x30 && code <= 0x39) ||
+        (code >= 0x41 && code <= 0x5a) ||
+        (code >= 0x61 && code <= 0x7a) ||
+        code === 0x2b ||
+        code === 0x2f ||
+        code === 0x3d ||
+        code === 0x2d ||
+        code === 0x5f ||
+        code === 0x25);
+}
+/**
+ * The text right after the placeholder at `at` that may be the rest of a credential whose public
+ * prefix redaction took (#703): up to the first unit `ends` accepts, reading later placeholders
+ * whole so none is split. Redaction can take `sk_live_`, `whsec_`, `Bearer `, or a signing
+ * parameter's name and `=`, leaving what follows; with that prefix known, any remainder rebuilds
+ * the credential, however short or encoded, so `readable` holds whenever it carries any base64 or
+ * base64url character, a `%` escape or a reference spelling credential data or an ampersand.
+ * Other references end the inferred remainder. Other punctuation alone (`.`, `,`, `;`, `!`) is no
+ * credential's data. References, including bare numeric bodies, are read before consulting `ends`.
+ * The run still ends where `ends` says a value does. One forward pass.
+ */
+export function splitRemainder(text, at, ends) {
+    if (!redactionAltered(text.slice(at, at + REDACTED.length)))
+        return { end: at, readable: false };
+    let end = at + REDACTED.length;
+    let readable = false;
+    while (end < text.length) {
+        const reference = Math.max(characterReferenceEnd(text, end, true), bareReferenceEnd(text, end, true));
+        if (text.startsWith(REDACTED, end))
+            end += REDACTED.length;
+        else if (reference > end) {
+            readable = true;
+            end = reference;
+        }
+        else if (ends(text, end))
+            break;
+        else {
+            readable ||= credentialUnit(text.charCodeAt(end));
+            end++;
+        }
+    }
+    return { end, readable };
+}

package/dist/registry.d.ts

@@ -1,8 +1,8 @@
 import type { CatalogDriftActivityContext } from "./activity.js";
-import type { CredentialVault } from "./credential-contract.js";
-import type { Connector, ConnectorContext, ConnectorStatus, KVStorage, Logger, ToolDef } from "./types.js";
 import { type CallAdmissionPermit, type ConnectorCallAdmissionSnapshot } from "./call-admission.js";
 import { type ConnectorCaller } from "./connector-caller.js";
+import type { CredentialVault } from "./credential-contract.js";
+import type { Connector, ConnectorContext, ConnectorStatus, KVStorage, Logger, ToolDef } from "./types.js";
 /**
  * Split `"<connectorId>.<toolName>"` on the first dot. Connector ids contain
  * no dots, so a downstream tool name may. Exported because an address that
@@ -45,8 +45,10 @@ export declare function resolveMaxResultBytes(value: number | undefined, inherit
 export interface RegistryOptions {
     publicUrl?: string | undefined;
     oauthClientName?: string | undefined;
-    classification?: Readonly<Record<string, Readonly<Record<string, "read" | "write">>>> | undefined;
+    classification?: Readonly<Record<string, Readonly<Record<string, "read" | "write" | "hidden">>>> | undefined;
     storage: KVStorage;
+    /** Internal deployment root, preserved when a personal registry partitions storage. */
+    rootStorage?: KVStorage;
     catalogStorage?: KVStorage;
     logger: Logger;
     credentialVault?: CredentialVault | undefined;
@@ -87,6 +89,13 @@ export interface ResultIdentity {
     endpoint: string;
     origin: string | null;
 }
+export interface ProgramResultDependency {
+    /** Catalog metadata needs visibility, not permission to invoke a write. */
+    access?: "catalog";
+    connector: string;
+    tool?: string;
+    classification: "read" | "write";
+}
 export interface RegistryView {
     credentialUiAvailable(): boolean;
     /** Deployment-wide result-size cap threaded to the meta-tools. */
@@ -111,8 +120,8 @@ export interface RegistryView {
     }): Promise<CallAdmissionPermit>;
     resultsStorage(): KVStorage;
     resultIdentity(): ResultIdentity;
-    /** Recheck live auth/grants and pool admission before exposing stored data. */
-    recheckResultAccess(address: string | undefined, classification: "read" | "write", signal?: AbortSignal, access?: "catalog"): Promise<boolean>;
+    /** One validation pass: admit once, then check every dependency under that scope. */
+    recheckResultAccess(dependencies: readonly ProgramResultDependency[], classification: "read" | "write", signal?: AbortSignal): Promise<boolean>;
     /** Reserve deployment-wide capacity before writing a paging envelope's chunks. */
     stashResult(id: string, chunks: readonly string[], ttlSeconds: number): Promise<boolean>;
     /** Local declared-vs-stored credential mismatch, with no downstream I/O. */
@@ -143,7 +152,7 @@ export interface RegistryScope {
     principalKey?: string;
     endpoint?: string;
     origin?: string | null;
-    currentResultAccess?: (address: string | undefined, classification: "read" | "write", signal?: AbortSignal, access?: "catalog") => Promise<boolean>;
+    currentResultAccess?: RegistryView["recheckResultAccess"];
     /** The admitted caller, readable only by built-in connectors; see connector-caller.ts. */
     caller?: ConnectorCaller;
 }
@@ -163,6 +172,7 @@ export declare class Registry implements RegistryView {
     private readonly catalogAccess;
     /** Bounded tokens isolating count-only observations by catalog identity. */
     private readonly catalogObservationPartitions;
+    private readonly overrideWarningCatalogs;
     private readonly observedOutputSchemas;
     /** Result-size guard cap threaded to the meta-tools. */
     readonly maxResultBytes: number;
@@ -221,7 +231,6 @@ export declare class Registry implements RegistryView {
     private catalogPartition;
     /** Bounded, in-memory tokens; no principal or catalog data is persisted. */
     private catalogObservationPartition;
-    private catalogDriftOf;
     /** Reject queued/future downstream admission; active permits release safely. */
     closeCallAdmission(): void;
     /**
@@ -248,7 +257,7 @@ export declare class Registry implements RegistryView {
      * connector's namespace. Backs connecta.result.
      */
     resultIdentity(): ResultIdentity;
-    recheckResultAccess(_address: string | undefined, _classification: "read" | "write", _signal?: AbortSignal, _access?: "catalog"): Promise<boolean>;
+    recheckResultAccess(_dependencies: readonly ProgramResultDependency[], _classification: "read" | "write", _signal?: AbortSignal): Promise<boolean>;
     resultsStorage(): KVStorage;
     credentialUiAvailable(): boolean;
     bindOAuthHandoff(id: string, authorizationUrl: string, principalKey?: string): Promise<void>;
@@ -266,14 +275,11 @@ export declare class Registry implements RegistryView {
     private acceptToolNames;
     /**
      * One connector's catalog as served: the cached downstream facts, classified
-     * on every read by the connector's `classification`, into fresh objects.
-     * Safety is derived here and nowhere else, so no cache layer can carry a
-     * stale verdict — from an older review, an older release, or a stale
-     * fallback — and nothing a caller or decorator does to a served tool reaches
-     * the next read.
+     * on every read by annotations and deployment overrides, into fresh objects.
+     * No cache or caller mutation can carry a stale verdict into the next read.
      */
     private loadTools;
-    private publishUnreviewedTool;
+    private publishTool;
     /** Construction-only view for the secret-free static config description. */
     describeStaticTools(id: string): ToolDef[] | undefined;
     private validateClassification;
@@ -282,7 +288,7 @@ export declare class Registry implements RegistryView {
     /** Age of a complete cache entry; reads never refresh it. */
     catalogAgeMs(id: string): number | null;
     /** Pure lookup shared by status probes and operator catalog refreshes. */
-    withCatalogObservations(id: string, baseUrl: string, status: ConnectorStatus, scope?: RegistryScope): ConnectorStatus;
+    withCatalogObservations(id: string, _baseUrl: string, status: ConnectorStatus, _scope?: RegistryScope): ConnectorStatus;
     /** Best-effort connector status for the operator UI. */
     statusFor(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions, scope?: RegistryScope): Promise<ConnectorStatus>;
     /** Rotate the storage generation; in-flight old readers cannot republish it. */