@zackbart/connecta 0.28.1 → 0.30.0

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

@@ -0,0 +1,276 @@
+/**
+ * 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. 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`.
+ */
+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";
+/**
+ * Whose Workspace account a call acts as.
+ *
+ * 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`.
+ */
+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. */
+export interface GoogleSubjectContext {
+    /** The call's cancellation, for an async directory lookup to honor. */
+    readonly signal?: AbortSignal;
+}
+/** Options every Workspace product provider shares. */
+export interface GoogleWorkspaceOptions {
+    /** What this connection is for, appended to the maintained guide. */
+    purpose: string;
+    /**
+     * The delegated service account: `{ clientEmail, privateKey }` from its
+     * JSON key, or the key file's whole JSON text. From deployment secrets,
+     * never a literal in source. One key serves every Workspace connector.
+     */
+    serviceAccount: GoogleServiceAccount | string;
+    /** Whose account each call acts as; see {@link GoogleWorkspaceSubject}. */
+    subject: GoogleWorkspaceSubject;
+    /** Human-readable display name. */
+    title?: string;
+    /** Organization-specific conventions appended to the maintained guide. */
+    instructions?: string;
+    /**
+     * Optional per-runtime call-admission policy. Google meters Workspace APIs
+     * per user and per project, so none is declared by default.
+     */
+    callAdmission?: ConnectorCallAdmissionPolicy;
+    /** Connector-specific inline result limit; omit to inherit the deployment. */
+    maxResultBytes?: number;
+    /** API base override for a proxy or test double. */
+    baseUrl?: string;
+}
+/** The closed options every Workspace provider accepts; see `assertKnownOptions`. */
+export declare const GOOGLE_WORKSPACE_OPTIONS: import("../../../config-schema.js").Field<unknown, unknown, true> & {
+    readonly shape: {
+        serviceAccount: import("../../../config-schema.js").Field<unknown, unknown, true> & {
+            readonly shape: {
+                readonly clientId: import("../../../config-schema.js").Field<unknown, unknown, true>;
+                readonly clientEmail: import("../../../config-schema.js").Field<unknown, unknown, true>;
+                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>;
+            };
+        };
+        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>;
+    };
+};
+/** The checked, construction-time half of {@link GoogleWorkspaceOptions}. */
+export interface WorkspaceConnection {
+    purpose: string;
+    account: ServiceAccountKey;
+    subject: GoogleWorkspaceSubject;
+}
+/** Validate the shared options at construction; throws on a structural mistake. */
+export declare function workspaceConnection(factory: string, options: GoogleWorkspaceOptions): WorkspaceConnection;
+/** 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;