@zackbart/connecta 0.34.1 → 0.35.0

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

@@ -0,0 +1,537 @@
+// Google Workspace on the provider kit (decision 0010; C.7 step 1 under 0011).
+// Shared by every Workspace product; never its own export. `workspace.ts`
+// keeps shared options, connection parsing and subject resolution;
+// `service-account.ts` keeps the private token exchange and cache.
+// This module adds what every product needs: the Google error
+// table, the delegated machine grant, a value-safety resolver over the
+// product's own operations, a request adapter that keeps the legacy request
+// bytes and write wording, and the step-1 catalog bridge.
+import { Effect, Option, Schema } from "effect";
+import { callClassification } from "../../../call-classification.js";
+import { deriveContext } from "../../../derived-context.js";
+import { ConnectorCallError } from "../../../errors.js";
+import { attachFailureFacts } from "../../../operator-record.js";
+import { Refusal, StatusFailure, toConnectorCallError, } from "../../../http/errors.js";
+import { Classification, Dispatches, Signal } from "../../../http/services.js";
+import { read, write } from "../../../http/tools.js";
+import { callMemo, Operation } from "../../../runtime/call.js";
+import { providerFailureMessage, unsentAfterUnauthorized } from "../../../write-outcome.js";
+import { delegatedToken, forgetDelegatedToken } from "./service-account.js";
+import { subjectFor, workspaceConnection } from "./workspace.js";
+import { tagWorkspaceSubject } from "../../../workspace-subject.js";
+import { googleNamedOperation, requireGoogleIndex } from "./hatch.js";
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function reasonsOf(tokens) {
+    const error = asRecord(asRecord(tokens)["error"]);
+    const reasons = new Set();
+    for (const entry of [...asArray(error["errors"]), ...asArray(error["details"])]) {
+        const reason = asRecord(entry)["reason"];
+        if (typeof reason === "string")
+            reasons.add(reason);
+    }
+    if (typeof error["status"] === "string")
+        reasons.add(error["status"]);
+    return [...reasons];
+}
+/** Public reason spellings shared by classification and the pre-redaction vocabulary. */
+const REASONS = {
+    disabled: ["accessNotConfigured", "SERVICE_DISABLED"],
+    rateLimited: ["rateLimitExceeded", "userRateLimitExceeded", "RATE_LIMIT_EXCEEDED"],
+    insufficientScope: ["insufficientPermissions", "ACCESS_TOKEN_SCOPE_INSUFFICIENT"],
+    exportSize: ["exportSizeLimitExceeded"],
+    domainPolicy: ["domainPolicy"],
+    filePermission: ["insufficientFilePermissions", "forbidden"],
+    precondition: ["FAILED_PRECONDITION", "failedPrecondition"],
+    aborted: ["ABORTED", "aborted"],
+};
+/**
+ * Google's failure table, in the legacy client's order: Google's own
+ * specific reasons decide first, whatever the status; only a refused
+ * precondition or an abort with nothing more specific to say is left for
+ * the revision guard (the `revisionGuarded` request flag), then the status.
+ * Each verdict's words are the legacy client's, so the messages stay.
+ */
+export function googleErrors(product, options = {}) {
+    const { provider, api, scopes, notFound } = product;
+    const has = (facts, names) => names.some((name) => facts.reasons.includes(name));
+    return {
+        provider,
+        facts: (tokens) => ({ reasons: reasonsOf(tokens) }),
+        factVocabulary: { reasons: Object.values(REASONS).flat() },
+        numericFacts: {
+            retryAfterMs: {
+                header: "retry-after",
+                format: "retry-after",
+                review: "HTTP Retry-After delay for failure recovery.",
+            },
+        },
+        detail: ({ status, body }) => {
+            const message = asRecord(asRecord(body)["error"])["message"];
+            // The body arrives redacted whole, before anything here cuts it.
+            const said = typeof message === "string" ? message.trim().slice(0, 500) : "";
+            return said ? `${provider}: ${said}${/[.!?]$/.test(said) ? "" : "."}` : `${provider} returned HTTP ${status}.`;
+        },
+        classify: [
+            // Every 3xx the transport lets through (300, 304, 305, 306) is a redirect first.
+            ({ status }) => status >= 300 && status < 400
+                ? {
+                    code: "connector_call_failed",
+                    retryable: false,
+                    words: () => `${provider} answered HTTP ${status} with a redirect; this connection talks to exactly one origin and never forwards its credential to another.`,
+                }
+                : undefined,
+            ({ status }) => status === 401
+                ? {
+                    code: "auth_required",
+                    words: (detail) => `${detail} Google rejected a freshly minted delegated token. The domain-wide delegation grant or the service account may have been revoked.`,
+                }
+                : undefined,
+            ({ facts }) => has(facts, REASONS.disabled)
+                ? {
+                    code: "connector_call_failed",
+                    retryable: false,
+                    words: (detail) => `${detail} The ${api} is not enabled in the service account's Google Cloud project; an operator enables it there.`,
+                }
+                : undefined,
+            ({ status, facts, retryAfterMs }) => (status === 429 && !options.standard) || has(facts, REASONS.rateLimited)
+                ? {
+                    code: "rate_limited",
+                    retryAfterMs,
+                    words: (detail) => `${detail} Google meters this API per user and per project.`,
+                    advice: "; wait before retrying",
+                }
+                : undefined,
+            ({ facts }) => has(facts, REASONS.insufficientScope)
+                ? {
+                    code: "provider_permission_denied",
+                    words: (detail) => `${detail} The delegated token lacks a scope this call needs. The Admin console's domain-wide delegation entry must list exactly: ${scopes.join(",")}.`,
+                }
+                : undefined,
+            ({ facts }) => has(facts, REASONS.exportSize)
+                ? {
+                    code: "connector_call_failed",
+                    retryable: false,
+                    words: (detail) => `${detail} The item is larger than Google will export in this format. Download the original file instead, or export a smaller part.`,
+                }
+                : undefined,
+            ({ facts }) => has(facts, REASONS.domainPolicy)
+                ? {
+                    code: "provider_permission_denied",
+                    retryable: false,
+                    words: (detail) => `${detail} A Workspace domain policy forbids this action for this account; only a Workspace administrator can change that.`,
+                }
+                : undefined,
+            ({ facts }) => has(facts, REASONS.filePermission)
+                ? {
+                    code: "provider_permission_denied",
+                    retryable: false,
+                    words: (detail) => `${detail} This account does not have the permission on this item that the action needs — it may be shared view-only, or not shared with this user. Its owner can grant more.`,
+                }
+                : undefined,
+            // A write that named the revision it was made against hears "the item
+            // moved on" as a refused precondition or an abort. Fixed words, so no
+            // provider ever matches on Google's prose.
+            ({ status, facts, operation }) => operation.flags?.["revisionGuarded"] === true &&
+                (status === 400 || status === 409) &&
+                has(facts, [...REASONS.precondition, ...REASONS.aborted])
+                ? {
+                    code: "conflict",
+                    words: () => `${provider} refused the write because the item changed after the revision it named.`,
+                    advice: " Re-read it for the current revision, reapply the change, and retry.",
+                }
+                : undefined,
+            // Google uses the same reason for a product switched off for this user
+            // and for a stale write, so the classification asserts neither.
+            ({ status, facts }) => status === 400 && has(facts, REASONS.precondition)
+                ? {
+                    code: "connector_call_failed",
+                    retryable: false,
+                    words: (detail) => `${detail} Google refused the request's precondition; its message says which.`,
+                }
+                : undefined,
+        ],
+        statuses: {
+            401: () => ({ code: "auth_required" }),
+            403: () => ({
+                code: "provider_permission_denied",
+                retryable: false,
+                words: (detail) => `${detail} Google refused the request; the account may lack access to this item, or a Workspace policy may block it. Google does not say which. Ask the item owner to grant access or a Workspace administrator to review the policy.`,
+            }),
+            404: () => notFound === "absent"
+                ? { code: "not_found", words: (detail) => `${detail} Re-read the id from a list or search tool.` }
+                : {
+                    code: "connector_call_failed",
+                    retryable: false,
+                    words: (detail) => `${detail} The id is unknown or not visible to this account; Google does not distinguish them.`,
+                },
+            400: () => ({ code: "invalid_args" }),
+            422: () => ({ code: "invalid_args" }),
+            serverError: ({ retryAfterMs }) => ({
+                code: "unavailable",
+                retryAfterMs,
+                words: (detail) => `${detail} Google is failing upstream.`,
+            }),
+            otherwise: () => ({ code: "connector_call_failed", retryable: false }),
+        },
+        unreadable: `${provider} returned a successful response that is not JSON.`,
+        ...(options.standard
+            ? {
+                meanings: {
+                    unknownId: notFound === "absent" ? "not_found" : "connector_call_failed",
+                    provesAbsence: notFound === "absent",
+                    conflicts: options.revisionConflicts
+                        ? ["A revision-guarded batch update returned ABORTED or FAILED_PRECONDITION with HTTP 400 or 409"]
+                        : [],
+                },
+                bodyFailures: {
+                    review: "An incomplete Google response cannot establish the requested result, including named binary reads.",
+                    statusOnly: [],
+                    readFailed: `${provider}'s response could not be read completely.`,
+                },
+                statuses: {
+                    401: () => ({ code: "auth_required" }),
+                    403: () => ({
+                        code: "provider_permission_denied",
+                        retryable: false,
+                        words: (detail) => `${detail} The account may lack access, or a Workspace policy may block this request.`,
+                    }),
+                    404: () => notFound === "absent"
+                        ? { code: "not_found" }
+                        : {
+                            code: "connector_call_failed",
+                            retryable: false,
+                            words: (detail) => `${detail} The id is unknown or not visible to this account; Google does not distinguish them.`,
+                        },
+                },
+            }
+            : {}),
+    };
+}
+// --- Value safety ------------------------------------------------------------------
+/** One declared operation as a matcher over actual paths: `:name` matches one encoded segment. */
+function templateMatcher(template) {
+    const segments = template.split("/").map((segment) => {
+        const parameter = /^:([A-Za-z0-9_]+)(.*)$/.exec(segment);
+        const literal = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        return parameter ? `[^/]+${literal(parameter[2])}` : literal(segment);
+    });
+    return new RegExp(`^${segments.join("/")}$`);
+}
+/**
+ * Google's value safety. Workspace answers are the user's own documents and
+ * mail, returned to the user who can open them; no response carries a
+ * credential or a stored secret, and the token a request sent is redacted by
+ * the kit's sent-secret pass before anything reads a body. So no field is
+ * rewritten and failures keep Google's (redacted) message, as they did on the
+ * legacy client. Every request resolves to one of the product's declared
+ * operations, so a path no tool declares never reaches the network.
+ */
+export function googleSafety(provider, operations) {
+    const declared = operations.map((operation) => {
+        const { method, path } = operation;
+        return { method, template: path, matcher: templateMatcher(path) };
+    });
+    return {
+        reviewed: {
+            resolve: (method, path) => {
+                const found = declared.find((entry) => entry.method === method && entry.matcher.test(path));
+                if (!found)
+                    throw new ConnectorCallError("invalid_args", `This ${provider} operation is not one the connection declares.`);
+                return { method: found.method, template: found.template };
+            },
+            redact: (data) => data,
+            withholdsErrors: () => false,
+        },
+        sensitiveFields: { names: [], choice: "drop" },
+    };
+}
+// --- The delegated grant -----------------------------------------------------------
+const connections = new WeakMap();
+/**
+ * The checked shared options, parsed once per construction: every definition
+ * callback receives the same validated options object, and the key is
+ * decoded and checked only the first time.
+ */
+export function workspaceOf(factory, options) {
+    let connection = connections.get(options);
+    if (!connection) {
+        connection = workspaceConnection(factory, options);
+        connections.set(options, connection);
+    }
+    return connection;
+}
+/**
+ * A machine grant over the service account's delegated tokens. Built at
+ * construction, outside every caller context (INV-7); each send evaluates it
+ * with that call's services. The subject resolves once per call, from
+ * deployment config and the admitted caller only, before any token is
+ * minted. Tokens are the shared in-memory cache's: only token strings and
+ * expiries cross requests.
+ */
+export function googleGrant(product, connection) {
+    const { provider, scopes } = product;
+    const errors = googleErrors(product);
+    const subjectKey = {};
+    return Effect.gen(function* () {
+        const operation = yield* Effect.serviceOption(Operation);
+        const ctx = Option.isSome(operation) ? operation.value : undefined;
+        if (!ctx)
+            return yield* Effect.die(new Error(`${provider} needs the call's connector context to resolve its subject.`));
+        const callSignal = yield* Signal;
+        // One resolution per call: a tool that sends several requests acts as one account throughout.
+        const tokenRequest = async () => ({
+            account: connection.account,
+            subject: await callMemo(ctx, subjectKey, () => subjectFor(provider, connection.subject, ctx)),
+            scopes,
+        });
+        const use = (work) => Effect.tryPromise({
+            try: (interrupted) => work(deriveContext(ctx, { signal: callSignal ? AbortSignal.any([callSignal, interrupted]) : interrupted })),
+            catch: (error) => error,
+        }).pipe(Effect.catch((error) => error instanceof ConnectorCallError ? Effect.fail(new Refusal({ error })) : Effect.die(error)));
+        return {
+            token: use(async (view) => delegatedToken(await tokenRequest(), view)),
+            // The token a 401 refused is forgotten, never a newer one, then minted anew.
+            refresh: (stale) => use(async (view) => {
+                const request = await tokenRequest();
+                await forgetDelegatedToken(request, stale);
+                return delegatedToken(request, view);
+            }),
+            // Unreachable with GOOGLE_GRANT_RENEWAL, which answers a replay's 401 from its body.
+            rejected: Effect.suspend(() => Effect.fail(new Refusal({
+                error: toConnectorCallError(new StatusFailure({
+                    status: 401,
+                    headers: new Headers(),
+                    body: undefined,
+                    operation: { method: "GET", template: "" },
+                }), errors, { classification: "read", dispatches: [] }),
+            }))),
+            discard: (rejected) => use(async () => forgetDelegatedToken(await tokenRequest(), rejected)).pipe(Effect.ignore),
+        };
+    });
+}
+/**
+ * Renewal as the legacy client did it: a read's 401 earns one fresh token
+ * and one replay, and a second 401 is answered from its own body; a write's
+ * 401 forgets its token and is never sent again, and the next call mints.
+ */
+export const GOOGLE_GRANT_RENEWAL = { replayRejection: "answer", writeRenewal: "discard" };
+/** Tag the built connector with whose account it acts as (#837, decisions/0006). */
+export function tagWorkspace(factory) {
+    return (connector, options) => {
+        tagWorkspaceSubject(connector, workspaceOf(factory, options).subject);
+    };
+}
+const outcomes = new WeakMap();
+/** The phase of a failure a Google request returned; undefined for anything else. */
+export function googleOutcomeOf(failure) {
+    return failure !== null && typeof failure === "object" ? outcomes.get(failure) : undefined;
+}
+function noted(failure, outcome) {
+    outcomes.set(failure, Object.freeze({ ...outcome }));
+    return failure;
+}
+/** Query pairs as the legacy transport encoded them: undefined dropped, arrays repeated, values stringified. */
+function queryPairs(query) {
+    const pairs = [];
+    for (const [key, value] of Object.entries(query ?? {})) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value))
+            for (const item of value)
+                pairs.push([key, String(item)]);
+        else
+            pairs.push([key, String(value)]);
+    }
+    return pairs;
+}
+/**
+ * Words the legacy client gave a served write whose answer proves nothing:
+ * no answer, a 5xx, a redirect, or a 2xx whose reply could not be read. Only
+ * the message and retry flag are its; the core still decides the outcome,
+ * which for each of these is unknown.
+ */
+function unknownWrite(message, status) {
+    return new Refusal({
+        error: attachFailureFacts(new ConnectorCallError("connector_call_failed", message, { retryable: false }), status === undefined ? {} : { httpStatus: status }),
+    });
+}
+export function googleClient(connection, provider, configuration = {}) {
+    if (configuration.standard || configuration.index)
+        requireGoogleIndex(configuration.index);
+    const send = (request, accept, options, binary = false) => Effect.gen(function* () {
+        if (configuration.index) {
+            yield* Effect.try({
+                try: () => {
+                    if (!request.template)
+                        throw new ConnectorCallError("invalid_args", "This indexed Google named request needs its declared operation template.");
+                    googleNamedOperation(configuration.index, request.method, request.path, request.template);
+                },
+                catch: (error) => new Refusal({ error: error }),
+            });
+        }
+        const active = yield* Effect.serviceOption(Operation);
+        const callWrite = (yield* Classification) === "write";
+        const dispatches = yield* Dispatches;
+        const signal = yield* Signal;
+        // Match the legacy wording rule even for direct calls: their GET
+        // lookups have no served verdict. Physical write accounting stays the
+        // core's Classification; only these Google-specific words use this.
+        const served = Option.isSome(active) && active.value ? callClassification(active.value) : undefined;
+        const write = (served ?? (request.method === "GET" ? "read" : "write")) === "write";
+        const operation = yield* connection.safety.resolve(request.method, request.path);
+        return yield* connection
+            .sendPath({
+            method: request.method,
+            path: request.path,
+            template: operation.template,
+            query: queryPairs(request.query),
+            headers: { accept, ...request.headers },
+            ...(request.body !== undefined ? { json: JSON.stringify(request.body) } : {}),
+            ...(request.rawBody !== undefined ? { rawBody: request.rawBody } : {}),
+        }, {
+            ...(options?.revisionGuarded || binary
+                ? {
+                    flags: {
+                        ...(options?.revisionGuarded ? { revisionGuarded: true } : {}),
+                        ...(binary ? { googleBytes: true } : {}),
+                    },
+                }
+                : {}),
+            ...(binary && options?.maxBytes !== undefined ? { prefix: { maxBytes: options.maxBytes } } : {}),
+            ...(options?.effect ? { effect: options.effect } : {}),
+            ...(options?.step ? { step: options.step } : {}),
+        })
+            .pipe(Effect.catch((failure) => Effect.fail(settled(failure, dispatches.find((entry) => entry.failure === failure), write, callWrite, signal))));
+    });
+    function settled(failure, own, write, callWrite, signal) {
+        // A lookup inside a write call has not sent the write. Keep the lookup's
+        // own verdict; only a call-owned request gets uncertain-write wording.
+        write = write && own?.request?.auxiliary !== true;
+        const status = own?.status;
+        const dispatched = own?.request?.dispatched === true;
+        const at = (phase, code = status) => ({ dispatched, phase, ...(code === undefined ? {} : { status: code }) });
+        if (!dispatched)
+            return noted(failure, { dispatched: false, phase: "before-send" });
+        if (configuration.standard) {
+            // Preserve phase evidence for partial-create recovery; settlement and
+            // reconciliation wording belong to the kit in standard mode.
+            const phase = failure._tag === "TransportFailure"
+                ? "awaiting-response"
+                : failure._tag === "UnreadableBody" || failure._tag === "ResponseTooLarge"
+                    ? "reading-body"
+                    : failure._tag === "RedirectRefused" || (status !== undefined && status >= 300 && status < 400)
+                        ? "redirected"
+                        : status === 401
+                            ? "unauthorized"
+                            : status !== undefined && status >= 500
+                                ? "server-error"
+                                : "refused";
+            return noted(failure, at(phase));
+        }
+        switch (failure._tag) {
+            case "StatusFailure": {
+                const code = failure.status;
+                if (code >= 300 && code < 400)
+                    return noted(write
+                        ? unknownWrite(`${provider} answered HTTP ${code} with a redirect, which this connection does not follow, so whether the request was applied is unknown. Re-read its target before repeating it.`, status)
+                        : failure, at("redirected", code));
+                if (write && code >= 500)
+                    return noted(unknownWrite(`${provider} answered HTTP ${code} after receiving the request, so its outcome is unknown — it may have been applied. Re-read its target before repeating it.`, status), at("server-error", code));
+                if (callWrite && own?.request?.auxiliary !== true && code === 401) {
+                    // Never sent again (INV-9); the next call mints a fresh token.
+                    const refusal = toConnectorCallError(failure, connection.errors, {
+                        classification: "write",
+                        dispatches: [own],
+                        withholds: connection.safety.withholdsErrors,
+                        signal,
+                    });
+                    return noted(new Refusal({ error: unsentAfterUnauthorized(provider, refusal) }), at("unauthorized", 401));
+                }
+                return noted(failure, at("refused", code));
+            }
+            case "RedirectRefused":
+                return noted(write
+                    ? unknownWrite(`${provider} answered HTTP ${failure.status} with a redirect, which this connection does not follow, so whether the request was applied is unknown. Re-read its target before repeating it.`, status)
+                    : failure, at("redirected", failure.status));
+            case "TransportFailure":
+                return noted(write
+                    ? unknownWrite(`${provider} was sent the request but no answer came back, so it may or may not have been applied. Re-read its target before repeating it.`, status)
+                    : failure, at("awaiting-response", undefined));
+            case "ResponseTooLarge":
+            case "UnreadableBody":
+                // An error status keeps its meaning whatever went wrong reading it.
+                if (status !== undefined && status >= 400)
+                    return noted(failure, at(write && status >= 500 ? "server-error" : "refused"));
+                return noted(write
+                    ? unknownWrite(`${provider} accepted the request but its reply could not be read; the change probably applied. Re-read before repeating it.`, status)
+                    : failure, at("reading-body"));
+            default:
+                return noted(failure, at("refused"));
+        }
+    }
+    return {
+        json: (request, options) => Effect.map(send(request, "application/json", options), (answer) => answer.data),
+        bytes: (request, accept = "*/*", options) => send(request, accept, options, true),
+    };
+}
+/**
+ * Reword a failure a Google request returned, keeping its verdict, its
+ * provenance and its phase: what a product adds after an uncertain create.
+ */
+export function googleFailureMessage(connection, failure, message) {
+    return Effect.gen(function* () {
+        const error = toConnectorCallError(failure, connection.errors, {
+            classification: yield* Classification,
+            dispatches: yield* Dispatches,
+            withholds: connection.safety.withholdsErrors,
+            signal: yield* Signal,
+        });
+        const reworded = new Refusal({ error: providerFailureMessage(error, message(error.message)) });
+        const outcome = googleOutcomeOf(failure);
+        return yield* Effect.fail(outcome ? noted(reworded, outcome) : reworded);
+    });
+}
+/** Arguments arrive validated against the exact legacy `inputSchema` by `api()` before any handler runs. */
+const ARGUMENTS = Schema.Record(Schema.String, Schema.Unknown);
+/**
+ * The step-1 catalog bridge. The tool is a kit `read` or `write` (its
+ * lease, write capacity, transport, failure mapping and result safety are
+ * the kit's), but its catalog keeps the legacy declaration's bytes:
+ * annotations, input and output schemas. `api()` validates every call, from
+ * every entry path, against that exact input schema before the handler runs
+ * (`callTool` in `src/connectors/api-connector.ts`, fail-closed), so the
+ * decoder accepts whatever reaches it and keeps the caller's key order. Step
+ * 2 replaces these schemas with Effect declarations (0011).
+ */
+export function googleTool(connection, declaration) {
+    const { annotations } = declaration;
+    const spec = {
+        name: declaration.name,
+        description: declaration.description,
+        input: ARGUMENTS,
+        output: Schema.Unknown,
+        ...(declaration.writeSteps ? { writeSteps: declaration.writeSteps } : {}),
+        run: (args) => Effect.gen(function* () {
+            const operation = yield* Effect.serviceOption(Operation);
+            const ctx = Option.isSome(operation) ? operation.value : undefined;
+            if (!ctx)
+                return yield* Effect.die(new Error(`${declaration.name} needs the call's connector context.`));
+            return yield* declaration.run(args, ctx);
+        }).pipe(
+        // A product's own refusals are thrown ConnectorCallErrors, as on the legacy client.
+        Effect.catchDefect((defect) => defect instanceof ConnectorCallError ? Effect.fail(new Refusal({ error: defect })) : Effect.die(defect))),
+    };
+    const built = annotations.readOnlyHint === true && annotations.destructiveHint !== true
+        ? read(connection, spec)
+        : write(connection, { ...spec, destructive: annotations.destructiveHint === true });
+    return Object.assign(built, {
+        annotations: declaration.annotations,
+        inputSchema: declaration.inputSchema,
+        outputSchema: declaration.outputSchema,
+    });
+}

package/dist/providers/_shared/google/result-size.js

@@ -12,6 +12,7 @@
  * around its rows — page objects, counts, ids — so a product sizes its rows
  * against this and its envelope never needs measuring.
  */
+import { redactBeforeCut } from "../../../sent-secrets.js";
 /** The size one Workspace result is built to stay under, in UTF-8 JSON bytes. */
 export const RESULT_BUDGET_BYTES = 192 * 1024;
 const encoder = new TextEncoder();
@@ -24,9 +25,21 @@ export function jsonBytes(value) {
  * `text` cut so that its JSON string encoding — quotes and escapes included —
  * takes at most `maxBytes` UTF-8 bytes, with `marker(dropped)` appended when
  * anything was cut. The cut never splits a surrogate pair, and the marker is
- * counted inside the bound, so the result always fits.
+ * counted inside the bound, so the result always fits. Text that must be cut
+ * has every secret the call's request sent replaced first: a cut through an
+ * echo would leave a fragment no later redaction can find.
  */
-export function clampText(text, maxBytes, marker) {
+export function clampText(ctx, original, maxBytes, marker) {
+    if (jsonBytes(original) <= maxBytes)
+        return original;
+    return clampRedactedText(redactBeforeCut(ctx, original), maxBytes, marker);
+}
+/**
+ * {@link clampText} for text whose sent secrets the caller already replaced,
+ * whole, before cutting any of it: a reader that pages one text from offsets
+ * must count every page in the same redacted text.
+ */
+export function clampRedactedText(text, maxBytes, marker) {
     if (jsonBytes(text) <= maxBytes)
         return text;
     const fits = (length) => {

package/dist/providers/_shared/google/service-account.d.ts

@@ -47,7 +47,8 @@ export interface DelegatedTokenRequest {
  * what happened inside its own request — a token, Google's refusal, or
  * `abandoned` for anything else — and a follower that hears `abandoned`, or
  * reaches the deadline first, mints for itself. A refusal is rebuilt for each
- * follower from its code and message, never handed over as the owner's object.
+ * follower from its code, message and resend advice, never handed over as the
+ * owner's object.
  */
 export declare function delegatedToken(request: DelegatedTokenRequest, ctx: ConnectorContext): Promise<string>;
 /**

package/dist/providers/_shared/google/service-account.js

@@ -23,7 +23,7 @@
  * and never the material that proves it.
  */
 import { guardedFetch, retryAfterMs } from "../../../connectors/guarded-fetch.js";
-import { ConnectorCallError } from "../../../errors.js";
+import { ConnectorCallError, resendAdvice, resendAdviceOf } from "../../../errors.js";
 /** Google's OAuth 2.0 token endpoint, and the JWT audience it requires. */
 const GOOGLE_TOKEN_ORIGIN = "https://oauth2.googleapis.com";
 const GOOGLE_TOKEN_URL = `${GOOGLE_TOKEN_ORIGIN}/token`;
@@ -259,6 +259,7 @@ async function signAssertion(account, subject, scopes, nowSeconds) {
 }
 // --- Token exchange --------------------------------------------------------------
 const tokenTransport = guardedFetch({
+    auxiliary: true,
     provider: "Google OAuth",
     baseUrl: GOOGLE_TOKEN_ORIGIN,
     headers: { Accept: "application/json" },
@@ -309,7 +310,7 @@ function tokenFailure(account, scopes, status, headers, payload) {
         return new ConnectorCallError("provider_permission_denied", `Google refused domain-wide delegation for ${account.clientEmail}.${said} A Workspace super admin must authorize ${client} in the Admin console (Security → Access and data control → API controls → Manage Domain Wide Delegation) with exactly these scopes: ${scopes.join(",")}. A new or changed grant can take up to 24 hours to apply.`);
     }
     if (code === "invalid_grant") {
-        return new ConnectorCallError("auth_required", `Google refused the delegated token.${said} The mapped Workspace user may not exist, may be suspended, or may be outside the domain that granted delegation; the service account key may have been deleted or disabled; or this host's clock may be minutes off. Check the deployment's subject mapping and the key before retrying.`);
+        return resendAdvice(new ConnectorCallError("auth_required", `Google refused the delegated token.${said} The mapped Workspace user may not exist, may be suspended, or may be outside the domain that granted delegation; the service account key may have been deleted or disabled; or this host's clock may be minutes off. Check the deployment's subject mapping and the key.`), " before retrying");
     }
     if (code === "invalid_client" || code === "disabled_client") {
         return new ConnectorCallError("auth_required", `Google rejected service account ${account.clientEmail} itself.${said} The account or its key may be disabled or deleted; create a new JSON key and redeploy.`);
@@ -436,7 +437,8 @@ function follow(flight, signal) {
  * what happened inside its own request — a token, Google's refusal, or
  * `abandoned` for anything else — and a follower that hears `abandoned`, or
  * reaches the deadline first, mints for itself. A refusal is rebuilt for each
- * follower from its code and message, never handed over as the owner's object.
+ * follower from its code, message and resend advice, never handed over as the
+ * owner's object.
  */
 export async function delegatedToken(request, ctx) {
     const key = await cacheKey(request);
@@ -451,7 +453,8 @@ export async function delegatedToken(request, ctx) {
             if (outcome.kind === "token")
                 return outcome.minted.accessToken;
             if (outcome.kind === "refused") {
-                throw new ConnectorCallError(outcome.code, outcome.message, outcome.retryAfterMs === undefined ? {} : { retryAfterMs: outcome.retryAfterMs });
+                const refused = new ConnectorCallError(outcome.code, outcome.message, outcome.retryAfterMs === undefined ? {} : { retryAfterMs: outcome.retryAfterMs });
+                throw outcome.advice === undefined ? refused : resendAdvice(refused, outcome.advice);
             }
             if (flights.get(key) === flight)
                 flights.delete(key);
@@ -478,6 +481,7 @@ export async function delegatedToken(request, ctx) {
                     code: error.code,
                     message: error.message,
                     retryAfterMs: error.retryAfterMs,
+                    advice: resendAdviceOf(error),
                 }
                 : { kind: "abandoned" });
             throw error;