@zackbart/connecta 0.34.0 → 0.35.0

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

@@ -1,57 +1,3 @@
-/**
- * Google Workspace access as the person calling, with no per-user consent:
- * a service account with domain-wide delegation mints a token *as* the user
- * the deployment maps the admitted caller to. The foundation each Workspace
- * product provider (`gmail()` first) builds on; never its own export.
- *
- * Whose account. `ConnectorContext` carries no identity, and a deployment's
- * own connector never learns its caller (`src/connector-caller.ts`). A
- * maintained Workspace provider is the second sanctioned reader of that
- * 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. 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
- * host. Catalogs need no subject: tools are static.
- *
- * A product builds on three calls: `workspaceConnection(factory, options)` at
- * construction, `googleWorkspaceClient({...})` once, and the client's `json`,
- * `bytes`, or `text` per request — plus `googleReasonsOf(error)` where a
- * product must decide on a Google reason the shared mapping leaves generic.
- * Nothing else here is the products' to touch.
- *
- * Setup, once per Workspace, shared by every product:
- *
- * 1. In a Google Cloud project, enable each product's API (Gmail API, Google
- *    Drive API, …).
- * 2. Create a service account. It needs no IAM role: delegation, not project
- *    permission, is what reaches user data.
- * 3. Create a JSON key for it. An organization policy
- *    (`iam.disableServiceAccountKeyCreation`, on by default for newer
- *    organizations) may refuse; an org policy administrator can override it
- *    for this project alone.
- * 4. Copy the service account's numeric client ID (Details → Advanced
- *    settings, or the key's `client_id`).
- * 5. As a Workspace super admin: Admin console → Security → Access and data
- *    control → API controls → Manage Domain Wide Delegation → Add new, with
- *    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`. 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";
 import { type GoogleServiceAccount, type ServiceAccountKey } from "./service-account.js";
 export type { GoogleServiceAccount } from "./service-account.js";
@@ -100,6 +46,8 @@ export interface GoogleWorkspaceOptions {
     callAdmission?: ConnectorCallAdmissionPolicy;
     /** Connector-specific inline result limit; omit to inherit the deployment. */
     maxResultBytes?: number;
+    /** Serve only read-classified tools on every endpoint. Defaults to false. */
+    readOnly?: boolean;
     /** API base override for a proxy or test double. */
     baseUrl?: string;
 }
@@ -144,10 +92,11 @@ export declare const GOOGLE_WORKSPACE_OPTIONS: import("../../../config-schema.js
         };
         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>;
         purpose: import("../../../config-schema.js").Field<unknown, unknown, true>;
-        subject: import("../../../config-schema.js").Field<unknown, unknown, true>;
+        maxResultBytes: import("../../../config-schema.js").Field<unknown, unknown, true>;
+        readOnly: 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>;
     };
 };
 /** The checked, construction-time half of {@link GoogleWorkspaceOptions}. */
@@ -159,157 +108,7 @@ 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.
+ * The Workspace address this call acts as, resolved from config and the
+ * admitted caller only. Throws before any network call when there is none.
  */
-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";
-/**
- * Google's machine-readable reasons for a failure the shared client mapped:
- * `errors[].reason`, `details[].reason`, and the canonical `status`, in that
- * order, deduplicated, at most eight, and only tokens of `[A-Za-z0-9_.]` up to
- * 64 characters — never a message or any other part of the payload. An empty
- * array for anything else, including a failure that never reached Google.
- *
- * For a product that needs a decision the shared mapping does not make, such
- * as Drive telling `cannotDownloadAbusiveFile` from another refusal. Classify
- * on these, never on the error's message.
- */
-export declare function googleReasonsOf(error: unknown): readonly string[];
-/**
- * How far a failed request got, for a product that must decide whether its
- * write may have landed:
- *
- * - `before-send`: nothing left connecta — no caller, no mapped account, a
- *   refused token, a local refusal. Nothing happened downstream.
- * - `awaiting-response`: the request was sent and no HTTP status came back.
- *   Google may or may not have applied it.
- * - `reading-body`: Google answered 2xx — it accepted the request — and the
- *   reply could not be used. A write probably applied.
- * - `redirected`: Google answered 3xx, which is never followed. It shows
- *   neither that a write applied nor that it did not: outcome unknown.
- * - `server-error`: Google answered a non-idempotent write with a 5xx,
- *   whatever reason it named. It may have committed before failing, so the
- *   outcome is unknown.
- * - `refused`: Google answered with a 4xx, or a read or idempotent write
- *   with a 5xx. Nothing to repeat blindly: a 4xx applied nothing, and a
- *   repeated read or idempotent write is harmless.
- */
-interface GoogleOutcome {
-    /** Whether the request left connecta for Google's API. */
-    readonly dispatched: boolean;
-    /** The HTTP status Google answered with, when one arrived. */
-    readonly status?: number;
-    readonly phase: "before-send" | "awaiting-response" | "reading-body" | "redirected" | "server-error" | "refused";
-}
-/**
- * How far the request behind a failure from `json`, `bytes`, or `text` got —
- * see {@link GoogleOutcome}. `undefined` for anything the client did not
- * throw. Read it beside the error, the way `googleReasonsOf` is read; the
- * error itself already carries the right retry verdict.
- */
-export declare function googleOutcomeOf(error: unknown): GoogleOutcome | undefined;
-/** What a Workspace product needs to reach its API as the calling user. */
-export interface GoogleWorkspaceClientOptions {
-    /** Product name in messages: "Gmail", "Google Drive". */
-    provider: string;
-    /** The API's console name, for an "enable the API" message: "Gmail API". */
-    api: string;
-    /**
-     * Absolute base URL, confined to the delegated user's own resources — for
-     * Gmail, `…/gmail/v1/users/me` — so no path can address another account.
-     */
-    baseUrl: string;
-    /** This product's scopes, and only these; the DWD grant must list them. */
-    scopes: readonly string[];
-    /** Response ceiling in bytes. */
-    maxResponseBytes: number;
-    /** H11: whether this API's 404 means absence or may hide a permission gap. */
-    notFound: NotFoundMeaning;
-    connection: WorkspaceConnection;
-}
-/** A non-JSON response body, read under the product's byte ceiling. */
-interface GoogleBytes {
-    bytes: Uint8Array;
-    /** The response's `Content-Type`, when it sent one. */
-    contentType: string | undefined;
-    /**
-     * Whether the body went on past what was kept. Only a request with
-     * `maxBytes` keeps less than the whole body, so without it this is false.
-     */
-    truncated: boolean;
-    /** The HTTP status: 200, 206 for an honored Range, 416 for an empty file. */
-    status: number;
-    /** The response's `Content-Range`, when it sent one. */
-    contentRange: string | undefined;
-}
-/** A text response body, decoded in the charset its `Content-Type` names. */
-interface GoogleText {
-    text: string;
-    contentType: string | undefined;
-    truncated: boolean;
-    status: number;
-    contentRange: string | undefined;
-}
-/** {@link GoogleRequestOptions}, plus a bound on how much of the body to read. */
-interface GoogleReadOptions extends GoogleRequestOptions {
-    /**
-     * Read at most this many bytes of the body: the result retains at most
-     * `maxBytes` (+1 to detect overflow, reported as `truncated`) and may
-     * consume at most one extra transport chunk from the stream; the rest is
-     * cancelled unread. A declared length past the client's ceiling is
-     * then no reason to refuse; the ceiling still bounds the read. With it set,
-     * a 416 carrying `Content-Range: bytes *\/0` — a Range request against an
-     * empty file — answers an empty result with that status, not a failure.
-     * A whole number of bytes, zero or more.
-     */
-    maxBytes?: number;
-}
-/**
- * A product's request path to its API, as the calling user. Every method
- * resolves the subject once per call context, sends the cached or a freshly
- * minted token, maps Google's failures by what the caller does next, and
- * answers a 401 with one fresh token and one replay — safe for a write too,
- * since a 401 is a refusal before the request did anything. Because of that
- * replay a `rawBody` must be sendable twice: a `ReadableStream` is refused
- * with a `TypeError` before any request; strings, bytes, Blobs, FormData, and
- * URLSearchParams are fine.
- */
-export interface GoogleWorkspaceClient {
-    /** One JSON request; the parsed body, `undefined` for an empty one. */
-    json(request: GuardedRequest, ctx: ConnectorContext, options?: GoogleRequestOptions): Promise<unknown>;
-    /**
-     * One request whose answer is not JSON — a download, an export — as bytes,
-     * bounded by `maxResponseBytes`. `accept` is sent as `Accept`.
-     */
-    bytes(request: GuardedRequest, ctx: ConnectorContext, accept?: string, options?: GoogleReadOptions): Promise<GoogleBytes>;
-    /**
-     * As {@link bytes}, decoded as text in the response's declared charset. A
-     * truncated prefix drops a code point the cut left incomplete.
-     */
-    text(request: GuardedRequest, ctx: ConnectorContext, accept?: string, options?: GoogleReadOptions): Promise<GoogleText>;
-}
-/** How one request's failures read, beyond the product's defaults. */
-interface GoogleRequestOptions {
-    /**
-     * The request is a write that names the revision it was made against —
-     * Docs, Slides, or Forms `writeControl.requiredRevisionId`. Google answers
-     * a stale one with HTTP 400 or 409 carrying FAILED_PRECONDITION or
-     * ABORTED, which then maps to `conflict` with fixed text telling the agent
-     * to re-read for the current revision and retry. Without it, such a refusal
-     * stays `connector_call_failed`, since the same reason also means things
-     * like a product switched off for the user.
-     */
-    revisionGuarded?: boolean;
-    /**
-     * Sending this write twice leaves the same state as sending it once — a
-     * PUT of a whole resource, a Sheets `values.update` of fixed cells. Only
-     * then does a 5xx on a write stay a retryable `unavailable`; otherwise its
-     * outcome is unknown and it is not retried. Reads are always idempotent.
-     */
-    idempotent?: boolean;
-}
-/** Build the delegated, confined, Google-error-mapped transport for one product. */
-export declare function googleWorkspaceClient(options: GoogleWorkspaceClientOptions): GoogleWorkspaceClient;
+export declare function subjectFor(provider: string, subject: GoogleWorkspaceSubject, ctx: ConnectorContext): Promise<string>;