@zackbart/connecta 0.32.0 → 0.34.0

package/dist/provider.js

@@ -3,17 +3,53 @@
 // acquire the MCP client, OAuth, or Effect graph by using it, and a hosted
 // provider does not acquire `api()`. Its runtime imports validate plain
 // options and reviewed classification, with no I/O.
-import { array, assertKnownOptions, keys, optionsOf } from "./config-schema.js";
+import { array, assertKnownOptions, ConfigError, fn, keys, object, opaque, required, whole, } from "./config-schema.js";
 import { reviewedClassification } from "./catalog-drift.js";
-const budget = optionsOf()(keys("kind", "maxCalls", "windowMs"));
-const admissionRule = optionsOf()({
-    ...keys("maxConcurrency", "maxQueueSize", "queueTimeoutMs", "retryAfterMs", "partitionKey"),
+const budget = {
+    ...object({
+        kind: required(opaque({
+            check(value, path) {
+                if (value !== "rolling-window")
+                    throw new ConfigError(`${path} must be "rolling-window".`);
+            },
+        })),
+        maxCalls: required(whole({ min: 1 })),
+        windowMs: required(whole({ min: 1 })),
+    }),
+    absent: () => undefined,
+};
+const admissionRule = object({
+    maxConcurrency: whole({ min: 1 }),
+    maxQueueSize: whole({ min: 0 }),
+    queueTimeoutMs: whole({ min: 1 }),
+    retryAfterMs: whole({ min: 0 }),
+    partitionKey: fn(),
     budget,
 });
-export const CALL_ADMISSION = optionsOf()({
-    ...keys("maxPartitions"),
-    rules: array(admissionRule),
+const admissionPolicy = object({
+    maxPartitions: whole({ min: 1 }),
+    rules: required(array(admissionRule)),
 });
+export const CALL_ADMISSION = {
+    ...admissionPolicy,
+    absent: () => undefined,
+    parse(value, path) {
+        const policy = admissionPolicy.parse(assertKnownOptions(value, path, admissionPolicy), path);
+        if (policy.rules.length !== 1) {
+            throw new ConfigError(`${path}.rules must contain exactly one rule in this release.`);
+        }
+        const rule = policy.rules[0];
+        if (rule.maxConcurrency === undefined && rule.budget === undefined) {
+            throw new ConfigError(`${path} rule must declare maxConcurrency or budget.`);
+        }
+        if (rule.maxConcurrency === undefined &&
+            (rule.maxQueueSize !== undefined || rule.queueTimeoutMs !== undefined || rule.retryAfterMs !== undefined)) {
+            throw new ConfigError(`${path} queue settings require maxConcurrency.`);
+        }
+        // object() omits undefined children; its resolved type lists every key.
+        return policy;
+    },
+};
 /** Options every maintained provider shares. */
 export const PROVIDER_COMMON = {
     ...keys("title", "authScope", "purpose", "instructions", "maxResultBytes"),
@@ -142,6 +178,9 @@ function asProvider(provider, shape, id, options, build) {
     let connector;
     try {
         options = assertKnownOptions(options, `${factory}(${JSON.stringify(id)})`, shape);
+        const admission = options == null ? undefined : options.callAdmission;
+        if (admission !== undefined)
+            CALL_ADMISSION.parse(admission, `${factory}(${JSON.stringify(id)}).callAdmission`);
         connector = build(id, options);
     }
     catch (error) {

package/dist/providers/_shared/google/workspace.d.ts

@@ -10,9 +10,16 @@
  * channel (PRINCIPLES.md INV-3, #678): deployment config supplies
  * `subject`, a function from the admitted `AuthenticatedIdentity` to a
  * Workspace address, and the provider reads the identity core attached beside
- * the context. No tool argument, header, or program can name the subject —
- * every product's base URL is confined beneath `users/me`, or its product's
- * equivalent, so the token's subject is the only account a request reaches.
+ * the context. An agent, which has no Workspace account, acts instead as the
+ * `owner` of the pool it came through, which core copies from that pool's
+ * config beside the identity; the mapping never sees an agent. In a pool
+ * without an owner the connector is absent for agents (core's scoped
+ * registry view hides it), and this provider still fails `auth_required` if
+ * one reaches it anyway (decisions/0006). A fixed
+ * `subject` address is every caller's, owners aside. No tool argument,
+ * header, or program can name the subject — every product's base URL is
+ * confined beneath `users/me`, or its product's equivalent, so the token's
+ * subject is the only account a request reaches.
  * A call with no admitted caller, one an open deployment admitted without
  * authentication (the mapping is never asked about it), or one the mapping
  * answers `undefined` for, fails `auth_required` before anything leaves the
@@ -41,7 +48,8 @@
  *    that client ID and *exactly* the scopes each product provider lists, comma
  *    separated. A grant can take up to 24 hours to apply.
  * 6. Pass the key to the provider from the deployment's secrets, and map the
- *    admitted identity to a Workspace address in `subject`.
+ *    admitted identity to a Workspace address in `subject`. Give each pool
+ *    agents use an `owner`, the address they act as there.
  */
 import { type GuardedRequest } from "../../../connectors/guarded-fetch.js";
 import type { AuthenticatedIdentity, ConnectorCallAdmissionPolicy, ConnectorContext } from "../../../types.js";
@@ -53,13 +61,15 @@ export type { GoogleServiceAccount } from "./service-account.js";
  * A function receives the identity an inbound auth provider authenticated for
  * this request and returns that person's Workspace address, or `undefined`
  * for a caller who has none — that call then fails closed. It is never called
- * for an open deployment's anonymous requests, nor for a call no request
- * admitted. It may be async, for a directory lookup (a Clerk user id to an
- * email, say), and receives the call's cancellation signal for that; it runs
- * once per tool call and should cache what it fetches. A string is one fixed
- * account for every caller who can reach the connector, for a shared mailbox
- * or scheduled work with no caller; limit who reaches it with
- * `identity.connectorAccess`.
+ * for an open deployment's anonymous requests, for a call no request
+ * admitted, or for an agent: an agent acts as the `owner` of the pool it
+ * came through, and never sees the connector in a pool without one. It may be async, for
+ * a directory lookup (a Clerk user id to an email, say), and receives the
+ * call's cancellation signal for that; it runs once per tool call and should
+ * cache what it fetches. A string is one fixed account for every caller who
+ * can reach the connector, agents included and pool owners aside, for a
+ * shared mailbox or scheduled work with no caller; limit who reaches it with
+ * `maintainers` and the `members` of the pools that list it.
  */
 export type GoogleWorkspaceSubject = string | ((identity: Readonly<AuthenticatedIdentity>, context: GoogleSubjectContext) => string | undefined | Promise<string | undefined>);
 /** What a subject mapping is told about the call it resolves for. */
@@ -103,18 +113,41 @@ export declare const GOOGLE_WORKSPACE_OPTIONS: import("../../../config-schema.js
                 readonly privateKey: import("../../../config-schema.js").Field<unknown, unknown, true>;
             };
         };
-        callAdmission: import("../../../config-schema.js").Field<unknown, unknown, true> & {
-            readonly shape: {
-                rules: import("../../../config-schema.js").Field<unknown[], readonly unknown[] | undefined, true>;
-                maxPartitions: import("../../../config-schema.js").Field<unknown, unknown, true>;
+        callAdmission: Omit<import("../../../config-schema.js").Field<unknown, ConnectorCallAdmissionPolicy | undefined, true>, "parse"> & {
+            parse(value: unknown, path: string): ConnectorCallAdmissionPolicy;
+            readonly shape: import("../../../config-schema.js").Shape & {
+                maxPartitions: import("../../../config-schema.js").Field<number, number | undefined, true>;
+                rules: import("../../../config-schema.js").Field<{
+                    maxConcurrency?: number | undefined;
+                    maxQueueSize?: number | undefined;
+                    queueTimeoutMs?: number | undefined;
+                    retryAfterMs?: number | undefined;
+                    partitionKey?: ((input: Readonly<import("../../../types.js").ConnectorCallAdmissionInput>) => string) | undefined;
+                    budget?: {
+                        kind: "rolling-window";
+                        maxCalls: number;
+                        windowMs: number;
+                    } | undefined;
+                }[], readonly {
+                    readonly maxConcurrency: number | undefined;
+                    readonly maxQueueSize: number | undefined;
+                    readonly queueTimeoutMs: number | undefined;
+                    readonly retryAfterMs: number | undefined;
+                    readonly partitionKey: ((input: Readonly<import("../../../types.js").ConnectorCallAdmissionInput>) => string) | undefined;
+                    readonly budget: {
+                        readonly kind: "rolling-window";
+                        readonly maxCalls: number;
+                        readonly windowMs: number;
+                    } | undefined;
+                }[], false>;
             };
         };
         instructions: import("../../../config-schema.js").Field<unknown, unknown, true>;
         title: import("../../../config-schema.js").Field<unknown, unknown, true>;
         maxResultBytes: import("../../../config-schema.js").Field<unknown, unknown, true>;
-        baseUrl: import("../../../config-schema.js").Field<unknown, unknown, true>;
-        subject: import("../../../config-schema.js").Field<unknown, unknown, true>;
         purpose: import("../../../config-schema.js").Field<unknown, unknown, true>;
+        subject: import("../../../config-schema.js").Field<unknown, unknown, true>;
+        baseUrl: import("../../../config-schema.js").Field<unknown, unknown, true>;
     };
 };
 /** The checked, construction-time half of {@link GoogleWorkspaceOptions}. */
@@ -125,6 +158,12 @@ export interface WorkspaceConnection {
 }
 /** Validate the shared options at construction; throws on a structural mistake. */
 export declare function workspaceConnection(factory: string, options: GoogleWorkspaceOptions): WorkspaceConnection;
+/**
+ * Tag a built Workspace connector with whose account it acts as, so the
+ * operator matrix can say "humans act as themselves, agents as the pool
+ * owner" for a mapping, or name a fixed subject (#837). Returns it unchanged.
+ */
+export declare function workspaceConnector<C extends object>(connection: WorkspaceConnection, connector: C): C;
 /** How a product reads an HTTP 404 — see H11. */
 type NotFoundMeaning = "absent" | "ambiguous";
 /**

package/dist/providers/_shared/google/workspace.js

@@ -10,9 +10,16 @@
  * channel (PRINCIPLES.md INV-3, #678): deployment config supplies
  * `subject`, a function from the admitted `AuthenticatedIdentity` to a
  * Workspace address, and the provider reads the identity core attached beside
- * the context. No tool argument, header, or program can name the subject —
- * every product's base URL is confined beneath `users/me`, or its product's
- * equivalent, so the token's subject is the only account a request reaches.
+ * the context. An agent, which has no Workspace account, acts instead as the
+ * `owner` of the pool it came through, which core copies from that pool's
+ * config beside the identity; the mapping never sees an agent. In a pool
+ * without an owner the connector is absent for agents (core's scoped
+ * registry view hides it), and this provider still fails `auth_required` if
+ * one reaches it anyway (decisions/0006). A fixed
+ * `subject` address is every caller's, owners aside. No tool argument,
+ * header, or program can name the subject — every product's base URL is
+ * confined beneath `users/me`, or its product's equivalent, so the token's
+ * subject is the only account a request reaches.
  * A call with no admitted caller, one an open deployment admitted without
  * authentication (the mapping is never asked about it), or one the mapping
  * answers `undefined` for, fails `auth_required` before anything leaves the
@@ -41,13 +48,16 @@
  *    that client ID and *exactly* the scopes each product provider lists, comma
  *    separated. A grant can take up to 24 hours to apply.
  * 6. Pass the key to the provider from the deployment's secrets, and map the
- *    admitted identity to a Workspace address in `subject`.
+ *    admitted identity to a Workspace address in `subject`. Give each pool
+ *    agents use an `owner`, the address they act as there.
  */
 import { guardedFetch, retryAfterMs } from "../../../connectors/guarded-fetch.js";
 import { keys, optionsOf } from "../../../config-schema.js";
 import { callerOf } from "../../../connector-caller.js";
 import { CALL_ADMISSION } from "../../../connectors/option-shapes.js";
 import { ConnectorCallError } from "../../../errors.js";
+import { isWorkspaceAddress } from "../../../workspace-address.js";
+import { tagWorkspaceSubject } from "../../../workspace-subject.js";
 import { delegatedToken, forgetDelegatedToken, parseServiceAccount, } from "./service-account.js";
 /** The closed options every Workspace provider accepts; see `assertKnownOptions`. */
 export const GOOGLE_WORKSPACE_OPTIONS = optionsOf()({
@@ -56,8 +66,6 @@ export const GOOGLE_WORKSPACE_OPTIONS = optionsOf()({
     serviceAccount: optionsOf()(keys("clientEmail", "privateKey", "clientId")),
     callAdmission: CALL_ADMISSION,
 });
-/** A plausible mailbox: one `@`, no whitespace or control characters. */
-const ADDRESS = /^[^\s@<>()",;:\\[\]]+@[^\s@<>()",;:\\[\]]+\.[^\s@<>()",;:\\[\]]+$/;
 /** Validate the shared options at construction; throws on a structural mistake. */
 export function workspaceConnection(factory, options) {
     const purpose = options?.purpose?.trim();
@@ -66,7 +74,7 @@ export function workspaceConnection(factory, options) {
     const account = parseServiceAccount(`${factory}()`, options.serviceAccount);
     const subject = options.subject;
     if (typeof subject === "string") {
-        if (!ADDRESS.test(subject.trim())) {
+        if (!isWorkspaceAddress(subject.trim())) {
             throw new Error(`${factory}() subject must be a Workspace email address or a function of the caller.`);
         }
         return { purpose, account, subject: subject.trim() };
@@ -76,6 +84,14 @@ export function workspaceConnection(factory, options) {
     }
     return { purpose, account, subject };
 }
+/**
+ * Tag a built Workspace connector with whose account it acts as, so the
+ * operator matrix can say "humans act as themselves, agents as the pool
+ * owner" for a mapping, or name a fixed subject (#837). Returns it unchanged.
+ */
+export function workspaceConnector(connection, connector) {
+    return tagWorkspaceSubject(connector, connection.subject);
+}
 /**
  * The Workspace address this call acts as, resolved from config and the
  * admitted caller only. Throws before any network call when there is none.
@@ -92,6 +108,16 @@ async function subjectFor(provider, subject, ctx) {
     if (!caller.authenticated) {
         throw new ConnectorCallError("auth_required", `${provider} acts as the signed-in Workspace user, and this deployment admitted the call without authentication. Configure inbound auth, or a fixed subject for shared use.`);
     }
+    // An agent has no Workspace account of its own. It acts as the owner of the
+    // pool it came through, which core copied from that pool's config, and the
+    // mapping, which answers for people, is never asked about it (decisions/0006).
+    // Core's scoped view already hides the connector from an agent without an
+    // owner; this refusal is the fallback for any context built without it.
+    if (caller.identity.agent !== undefined) {
+        if (caller.pool !== undefined && isWorkspaceAddress(caller.poolOwner))
+            return caller.poolOwner;
+        throw new ConnectorCallError("auth_required", `${provider} acts as a pool's owner for agents, and the pool this agent reached it through has no owner. An operator sets owner on the pool in the deployment's config; nothing a call sends can choose one.`);
+    }
     let mapped;
     try {
         mapped = await subject(caller.identity, ctx.signal ? { signal: ctx.signal } : {});
@@ -104,7 +130,7 @@ async function subjectFor(provider, subject, ctx) {
     if (mapped === undefined) {
         throw new ConnectorCallError("auth_required", `This caller has no Google Workspace account mapped for ${provider}. An operator maps signed-in identities to Workspace addresses in the deployment's subject config; nothing a call sends can choose one.`);
     }
-    if (typeof mapped !== "string" || !ADDRESS.test(mapped.trim())) {
+    if (typeof mapped !== "string" || !isWorkspaceAddress(mapped.trim())) {
         throw new ConnectorCallError("connector_call_failed", `The deployment's ${provider} subject mapping returned something that is not an email address.`, { retryable: false });
     }
     return mapped.trim();

package/dist/providers/_shared/rest/tools.js

@@ -1,5 +1,5 @@
 import { guardedFetch, } from "../../../connectors/guarded-fetch.js";
-import { recordRecovery } from "../../../call-recovery.js";
+import { IDEMPOTENCY_KEY_MAX_LENGTH, recordRecovery } from "../../../call-recovery.js";
 import { ConnectorCallError, unavailableCallError } from "../../../errors.js";
 const READ = { readOnlyHint: true };
 const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true };
@@ -506,7 +506,7 @@ export function restTools(vendor) {
                         idempotencyKey: {
                             type: "string",
                             minLength: 1,
-                            maxLength: 255,
+                            maxLength: IDEMPOTENCY_KEY_MAX_LENGTH,
                             description: "Reuse to retry this exact write; one is generated and returned when omitted.",
                         },
                     }

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

@@ -99,6 +99,16 @@ interface ResourceRules {
 export interface ValueSafetyTable {
     /** Display name in refusals. */
     readonly title: string;
+    /** Global signing names plus generic credential names only on these reviewed response paths. */
+    readonly embeddedUrls?: {
+        readonly operations?: Readonly<Record<string, readonly string[]>>;
+        /** Discriminated resources, wherever lists, expansions, or events embed them. */
+        readonly resources?: {
+            readonly key: string;
+            readonly partials?: readonly string[];
+            readonly paths: Readonly<Record<string, readonly string[]>>;
+        };
+    };
     /** The reviewed verdict for every flagged operation, keyed `METHOD /path template`. */
     readonly operations: Readonly<Record<string, ValueSafetyVerdict>>;
     /**
@@ -127,6 +137,46 @@ export declare function under(prefixes: readonly string[], paths: readonly strin
  * (Cloudflare's).
  */
 export declare function credentialName(name: string): boolean;
+/** Where a vendor stores the files it signs. */
+export interface FileHosts {
+    /** Hosts matched whole or as a parent domain: `file.notion.so` covers `img.file.notion.so`. */
+    readonly domains: readonly string[];
+    /** S3 buckets, virtual-hosted or as the first path segment on an S3 endpoint. Never all of S3. */
+    readonly buckets: readonly string[];
+}
+/**
+ * `text` with every pre-signed link withheld: at one of `hosts` (Notion's
+ * file storage, say), its whole query and fragment; anywhere, a signing
+ * parameter's value. Everything else comes back byte for byte.
+ */
+export declare function withholdSignedLinks(text: string, hosts: FileHosts): string;
+/**
+ * Reviewed REST text policy: only credential-bearing URL queries/fragments
+ * change. Ordinary links, including external proxies, retain their bytes.
+ * Literal AWS/Google signing names are withheld anywhere, as in #818.
+ */
+export declare function withholdEmbeddedUrls(text: string): string;
+/** Every string inside a JSON value through `withholdSignedLinks`; unchanged values keep their identity. */
+export declare function withholdSignedLinksIn(value: unknown, hosts: FileHosts, depth?: number): unknown;
+/** Apply the reviewed text policy to a selected value or vendor error body. */
+export declare function withholdEmbeddedUrlsIn(value: unknown): unknown;
+/**
+ * Whether a request value carries a link whose query or
+ * fragment holds the exact `[redacted]` placeholder, plain or encoded: a
+ * withheld read copied into a write, which would store the placeholder.
+ * Only the link's own destination is read: a Markdown link ends at its
+ * closing `)`, so `[f](…?a=1)[redacted]` is ordinary text after it.
+ * The word alone (`unredacted`) or the placeholder away from a file link is
+ * a person's text. When `hosts` is supplied, require its actual authority
+ * to match that policy, preserving Notion's external-proxy boundary.
+ */
+export declare function carriesWithheldLink(value: unknown, hosts?: FileHosts): boolean;
+/** Refuse a withheld destination copied into customer data, before any dispatch. */
+export declare function refuseWithheldLinks(value: unknown, title: string): void;
+/** Upload admission inspects actual bytes, including base64-decoded files and multipart blobs. */
+export declare function refuseWithheldUpload(body: BodyInit, title: string): Promise<void>;
+/** Only for documented JSON fields the vendor decodes as base64, never arbitrary strings. */
+export declare function refuseWithheldBase64(value: unknown, title: string, maxDecodedBytes?: number): Promise<void>;
 /** 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. */