@bevel-software/platform-mcp-core 0.24.0 → 0.25.2

package/dist/google-service-account/google-auth-http.protocol.d.ts

@@ -0,0 +1,24 @@
+import { type CallTemplate, type IUtcpClient } from '@utcp/sdk';
+import { HttpCommunicationProtocol } from '@utcp/http';
+import type { IServiceAccountTokenSource } from './service-account-token.contract.js';
+/**
+ * The stock UTCP `http` protocol, taught one more auth type. A call whose
+ * template names `google_service_account` is handed to the stock protocol with
+ * that auth swapped for the bearer token it resolves to (as `oauth2_user`,
+ * which the stock protocol sends as `Authorization: Bearer <token>` and strips
+ * on a cross-origin redirect). Every other call passes through untouched.
+ */
+export declare class GoogleAuthHttpProtocol extends HttpCommunicationProtocol {
+    private readonly tokens;
+    constructor(tokens: IServiceAccountTokenSource);
+    callTool(caller: IUtcpClient, toolName: string, toolArgs: Record<string, unknown>, toolCallTemplate: CallTemplate): Promise<unknown>;
+    callToolStreaming(caller: IUtcpClient, toolName: string, toolArgs: Record<string, unknown>, toolCallTemplate: CallTemplate): AsyncGenerator<unknown, void, unknown>;
+    private withBearerToken;
+}
+/**
+ * Put the service-account-aware protocol in place of the stock `http` one,
+ * minting tokens from `tokens`. Exported so a suite can answer for Google;
+ * a process never needs to call it, since loading this module already has.
+ */
+export declare function installGoogleServiceAccountAuth(tokens?: IServiceAccountTokenSource): void;
+//# sourceMappingURL=google-auth-http.protocol.d.ts.map

package/dist/google-service-account/google-auth-http.protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-auth-http.protocol.d.ts","sourceRoot":"","sources":["../../src/google-service-account/google-auth-http.protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACvF,OAAO,EAAE,yBAAyB,EAAyB,MAAM,YAAY,CAAC;AAG9E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AAEtF;;;;;;GAMG;AACH,qBAAa,sBAAuB,SAAQ,yBAAyB;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,0BAA0B;IAIhD,QAAQ,CACrB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,gBAAgB,EAAE,YAAY,GAC7B,OAAO,CAAC,OAAO,CAAC;IAIH,iBAAiB,CAC/B,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,gBAAgB,EAAE,YAAY,GAC7B,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC;YAI3B,eAAe;CAM9B;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,GAAE,0BAAkE,GACzE,IAAI,CAEN"}

package/dist/google-service-account/google-auth-http.protocol.js

@@ -0,0 +1,47 @@
+import { CommunicationProtocol } from '@utcp/sdk';
+import { HttpCommunicationProtocol } from '@utcp/http';
+import { isGoogleServiceAccountAuth } from './google-service-account.auth.js';
+import { GoogleServiceAccountTokenSource } from './google-service-account.token-source.js';
+/**
+ * The stock UTCP `http` protocol, taught one more auth type. A call whose
+ * template names `google_service_account` is handed to the stock protocol with
+ * that auth swapped for the bearer token it resolves to (as `oauth2_user`,
+ * which the stock protocol sends as `Authorization: Bearer <token>` and strips
+ * on a cross-origin redirect). Every other call passes through untouched.
+ */
+export class GoogleAuthHttpProtocol extends HttpCommunicationProtocol {
+    tokens;
+    constructor(tokens) {
+        super();
+        this.tokens = tokens;
+    }
+    async callTool(caller, toolName, toolArgs, toolCallTemplate) {
+        return super.callTool(caller, toolName, toolArgs, await this.withBearerToken(toolCallTemplate));
+    }
+    async *callToolStreaming(caller, toolName, toolArgs, toolCallTemplate) {
+        yield* super.callToolStreaming(caller, toolName, toolArgs, await this.withBearerToken(toolCallTemplate));
+    }
+    async withBearerToken(template) {
+        const auth = template.auth;
+        if (!isGoogleServiceAccountAuth(auth))
+            return template;
+        const accessToken = await this.tokens.accessToken(auth);
+        return { ...template, auth: { auth_type: 'oauth2_user', access_token: accessToken } };
+    }
+}
+/**
+ * Put the service-account-aware protocol in place of the stock `http` one,
+ * minting tokens from `tokens`. Exported so a suite can answer for Google;
+ * a process never needs to call it, since loading this module already has.
+ */
+export function installGoogleServiceAccountAuth(tokens = new GoogleServiceAccountTokenSource()) {
+    CommunicationProtocol.communicationProtocols['http'] = new GoogleAuthHttpProtocol(tokens);
+}
+// Installed on module load, the way `@utcp/http` installs the protocol this
+// one replaces: once per process, before any client exists (a client copies
+// the registry when it is built). The import of `@utcp/http` above has already
+// run its own registration by the time this line does, whatever order the
+// importing module lists the two in. One token cache then serves the process;
+// its entries are keyed by the key itself, so knowledge bases never share one.
+installGoogleServiceAccountAuth();
+//# sourceMappingURL=google-auth-http.protocol.js.map

package/dist/google-service-account/google-auth-http.protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-auth-http.protocol.js","sourceRoot":"","sources":["../../src/google-service-account/google-auth-http.protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAuC,MAAM,WAAW,CAAC;AACvF,OAAO,EAAE,yBAAyB,EAAyB,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAE,+BAA+B,EAAE,MAAM,0CAA0C,CAAC;AAG3F;;;;;;GAMG;AACH,MAAM,OAAO,sBAAuB,SAAQ,yBAAyB;IACtC;IAA7B,YAA6B,MAAkC;QAC7D,KAAK,EAAE,CAAC;QADmB,WAAM,GAAN,MAAM,CAA4B;IAE/D,CAAC;IAEQ,KAAK,CAAC,QAAQ,CACrB,MAAmB,EACnB,QAAgB,EAChB,QAAiC,EACjC,gBAA8B;QAE9B,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAClG,CAAC;IAEQ,KAAK,CAAC,CAAC,iBAAiB,CAC/B,MAAmB,EACnB,QAAgB,EAChB,QAAiC,EACjC,gBAA8B;QAE9B,KAAK,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC3G,CAAC;IAEO,KAAK,CAAC,eAAe,CAAC,QAAsB;QAClD,MAAM,IAAI,GAAI,QAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC;YAAE,OAAO,QAAQ,CAAC;QACvD,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACxD,OAAO,EAAE,GAAG,QAAQ,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,EAAkB,CAAC;IACxG,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,+BAA+B,CAC7C,SAAqC,IAAI,+BAA+B,EAAE;IAE1E,qBAAqB,CAAC,sBAAsB,CAAC,MAAM,CAAC,GAAG,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC5F,CAAC;AAED,4EAA4E;AAC5E,4EAA4E;AAC5E,+EAA+E;AAC/E,0EAA0E;AAC1E,8EAA8E;AAC9E,+EAA+E;AAC/E,+BAA+B,EAAE,CAAC"}

package/dist/google-service-account/google-service-account.auth.d.ts

@@ -0,0 +1,45 @@
+import { type GoogleServiceAccountAuth } from './service-account-token.contract.js';
+/** Whether a call template's `auth` asks for a Google service-account token. */
+export declare function isGoogleServiceAccountAuth(auth: unknown): auth is GoogleServiceAccountAuth;
+/**
+ * Where in `doc` a `google_service_account` auth block sits that nothing will
+ * act on, as a phrase for a refusal, or null when every block is the `auth` of
+ * one of `toolCallTemplates` and that template is an `http` one.
+ *
+ * `toolCallTemplates` are the templates tools are really called through, which
+ * only the caller knows: the document's shape is its business. A block
+ * anywhere else is read by nothing, whatever the object around it looks like:
+ * a template the document never registers, an `auth_tools`, a block at the
+ * root of a file that discovers its tools from a url.
+ *
+ * UTCP validates an auth type on any call template that takes an `auth`, but
+ * only the `http` protocol mints the token. Every other protocol sends an auth
+ * type it does not know as no credentials at all, so such a tool would save
+ * cleanly and then call Google unauthenticated.
+ *
+ * Every block in the document is found, at any depth (see
+ * `googleServiceAccountBlocks`), and the first one in document order that
+ * nothing will act on is the one named.
+ */
+export declare function findUnservedGoogleServiceAccountAuth(doc: unknown, toolCallTemplates: readonly unknown[]): string | null;
+/**
+ * Whether any `google_service_account` block in `doc` has its key WRITTEN IN
+ * THE DOCUMENT: a `credentials` that is anything but one variable reference.
+ *
+ * The document is a `.tool`, which is knowledge-base content: it is committed
+ * to the repository, and read by everyone and every agent that can read the
+ * knowledge base. A key written into it is a key all of them hold, for as
+ * long as the history keeps it. So the place for the key is the vault, and
+ * `credentials` only ever names the variable.
+ *
+ * Asked of the document as its author wrote it, wherever the block sits: a
+ * key in a block nothing will act on is just as readable. It cannot be asked
+ * where the auth type itself is validated, because that also runs on the
+ * template AFTER its variables were substituted, where `credentials` is the
+ * key and has to be.
+ *
+ * Says only that one was found. It never returns, quotes or measures the
+ * value: what it would be describing is the secret.
+ */
+export declare function holdsLiteralGoogleServiceAccountKey(doc: unknown): boolean;
+//# sourceMappingURL=google-service-account.auth.d.ts.map

package/dist/google-service-account/google-service-account.auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-service-account.auth.d.ts","sourceRoot":"","sources":["../../src/google-service-account/google-service-account.auth.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoC,KAAK,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AA0BtH,gFAAgF;AAChF,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,wBAAwB,CAM1F;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oCAAoC,CAAC,GAAG,EAAE,OAAO,EAAE,iBAAiB,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,GAAG,IAAI,CASvH;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOzE"}

package/dist/google-service-account/google-service-account.auth.js

@@ -0,0 +1,153 @@
+import { AuthSerializer, Serializer } from '@utcp/sdk';
+import { z } from 'zod';
+import { GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE } from './service-account-token.contract.js';
+const GoogleServiceAccountAuthSchema = z.object({
+    auth_type: z.literal(GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE),
+    credentials: z
+        .string()
+        .min(1)
+        .describe('The service-account key JSON. Recommended to use a vault variable like "${GOOGLE_SA_KEY}".'),
+    // Trimmed before the length check, so a blank scope is refused here rather
+    // than reaching Google as an empty one.
+    scopes: z
+        .union([z.string().trim().min(1), z.array(z.string().trim().min(1)).min(1)])
+        .describe('OAuth scopes for the token, e.g. "https://www.googleapis.com/auth/adwords".'),
+    subject: z.string().trim().min(1).optional().describe('User to impersonate under domain-wide delegation.'),
+});
+class GoogleServiceAccountAuthSerializer extends Serializer {
+    toDict(obj) {
+        return { ...obj };
+    }
+    validateDict(obj) {
+        return GoogleServiceAccountAuthSchema.parse(obj);
+    }
+}
+/** Whether a call template's `auth` asks for a Google service-account token. */
+export function isGoogleServiceAccountAuth(auth) {
+    return (typeof auth === 'object' &&
+        auth !== null &&
+        auth.auth_type === GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE);
+}
+/** The one call template type whose protocol turns the key into a token. */
+const SERVED_CALL_TEMPLATE_TYPE = 'http';
+/**
+ * The other call template types an author is likely to have reached for, which
+ * the answer below may name. A type outside this list is the file's own text,
+ * and is described rather than quoted back.
+ */
+const NAMEABLE_CALL_TEMPLATE_TYPES = ['sse', 'streamable_http', 'mcp', 'cli'];
+/**
+ * Where in `doc` a `google_service_account` auth block sits that nothing will
+ * act on, as a phrase for a refusal, or null when every block is the `auth` of
+ * one of `toolCallTemplates` and that template is an `http` one.
+ *
+ * `toolCallTemplates` are the templates tools are really called through, which
+ * only the caller knows: the document's shape is its business. A block
+ * anywhere else is read by nothing, whatever the object around it looks like:
+ * a template the document never registers, an `auth_tools`, a block at the
+ * root of a file that discovers its tools from a url.
+ *
+ * UTCP validates an auth type on any call template that takes an `auth`, but
+ * only the `http` protocol mints the token. Every other protocol sends an auth
+ * type it does not know as no credentials at all, so such a tool would save
+ * cleanly and then call Google unauthenticated.
+ *
+ * Every block in the document is found, at any depth (see
+ * `googleServiceAccountBlocks`), and the first one in document order that
+ * nothing will act on is the one named.
+ */
+export function findUnservedGoogleServiceAccountAuth(doc, toolCallTemplates) {
+    const served = new Set(toolCallTemplates);
+    for (const { parent, key } of googleServiceAccountBlocks(doc)) {
+        // Judged by where it sits, so once per place it appears: an aliased
+        // block can be served in one place and ignored in another.
+        const where = unservedPlacement(parent, key, served);
+        if (where)
+            return where;
+    }
+    return null;
+}
+/** `${NAME}` or `$NAME`, as UTCP spells a variable, and nothing else around it. */
+const ONE_VARIABLE_REFERENCE = /^\s*(?:\$\{[a-zA-Z0-9_]+\}|\$[a-zA-Z0-9_]+)\s*$/;
+/**
+ * Whether any `google_service_account` block in `doc` has its key WRITTEN IN
+ * THE DOCUMENT: a `credentials` that is anything but one variable reference.
+ *
+ * The document is a `.tool`, which is knowledge-base content: it is committed
+ * to the repository, and read by everyone and every agent that can read the
+ * knowledge base. A key written into it is a key all of them hold, for as
+ * long as the history keeps it. So the place for the key is the vault, and
+ * `credentials` only ever names the variable.
+ *
+ * Asked of the document as its author wrote it, wherever the block sits: a
+ * key in a block nothing will act on is just as readable. It cannot be asked
+ * where the auth type itself is validated, because that also runs on the
+ * template AFTER its variables were substituted, where `credentials` is the
+ * key and has to be.
+ *
+ * Says only that one was found. It never returns, quotes or measures the
+ * value: what it would be describing is the secret.
+ */
+export function holdsLiteralGoogleServiceAccountKey(doc) {
+    for (const { block } of googleServiceAccountBlocks(doc)) {
+        const { credentials } = block;
+        // Not a string is not a key either; the auth type's own schema refuses it.
+        if (typeof credentials === 'string' && !ONE_VARIABLE_REFERENCE.test(credentials))
+            return true;
+    }
+    return false;
+}
+/**
+ * Every `google_service_account` auth block in `doc`, at any depth, with the
+ * object it sits in and the key it sits under, in document order.
+ *
+ * The walk keeps its own stack, so a deeply nested document cannot overflow
+ * the call stack, and it does not re-enter an object it has seen: a YAML
+ * anchor aliased inside itself parses to a cyclic object. A block is yielded
+ * once per place it appears, since an aliased one sits in several.
+ */
+function* googleServiceAccountBlocks(doc) {
+    const seen = new WeakSet();
+    const pending = [{ node: doc }];
+    for (let next = pending.pop(); next; next = pending.pop()) {
+        const { node, parent, key } = next;
+        if (!node || typeof node !== 'object')
+            continue;
+        if (isGoogleServiceAccountAuth(node)) {
+            yield { block: node, parent, key };
+            continue;
+        }
+        if (seen.has(node))
+            continue;
+        seen.add(node);
+        // Pushed in reverse, so blocks come out in document order.
+        if (Array.isArray(node)) {
+            for (let i = node.length - 1; i >= 0; i--)
+                pending.push({ node: node[i] });
+        }
+        else {
+            const obj = node;
+            const keys = Object.keys(obj);
+            for (let i = keys.length - 1; i >= 0; i--)
+                pending.push({ node: obj[keys[i]], parent: obj, key: keys[i] });
+        }
+    }
+}
+/** Why a block under `parent[key]` is acted on by nothing, or null when it is. */
+function unservedPlacement(parent, key, served) {
+    if (!parent || key !== 'auth' || typeof parent.call_template_type !== 'string') {
+        return "somewhere that is not a call template's `auth`";
+    }
+    const type = parent.call_template_type.toLowerCase().trim();
+    if (type !== SERVED_CALL_TEMPLATE_TYPE) {
+        return NAMEABLE_CALL_TEMPLATE_TYPES.includes(type) ? `a \`${type}\` call template` : 'a call template that is not an `http` one';
+    }
+    return served.has(parent) ? null : 'an `http` call template that no tool is called through';
+}
+// Register the auth type on module load, so a `.tool` naming it validates
+// wherever UTCP parses a call template: the inline manual route, the preview,
+// and the client re-validating a template after substituting its variables.
+// UTCP's registry is process-wide and the type carries no state, so one
+// registration serves every knowledge base. Idempotent (safe under hot-reload).
+AuthSerializer.registerAuth(GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE, new GoogleServiceAccountAuthSerializer(), true);
+//# sourceMappingURL=google-service-account.auth.js.map

package/dist/google-service-account/google-service-account.auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-service-account.auth.js","sourceRoot":"","sources":["../../src/google-service-account/google-service-account.auth.ts"],"names":[],"mappings":"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"}

package/dist/google-service-account/google-service-account.token-source.d.ts

@@ -0,0 +1,28 @@
+import { type GoogleServiceAccountAuth, type IServiceAccountTokenSource } from './service-account-token.contract.js';
+/**
+ * Google's token endpoint. Fixed rather than read from the key's own
+ * `token_uri`, so a key cannot point the server at another host with a signed
+ * assertion in hand.
+ */
+export declare const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+/**
+ * Mints and caches access tokens for Google service accounts: signs an RS256
+ * assertion with the key's private key, exchanges it at Google's token
+ * endpoint, and keeps the token until shortly before it expires. Concurrent
+ * calls for the same token share one exchange, and a failed exchange is
+ * answered from memory for a few seconds (or for Google's `Retry-After`), so
+ * an outage or a rate limit is not met with a fresh exchange on every call.
+ * Injected with `fetch` and a clock so suites answer for Google.
+ */
+export declare class GoogleServiceAccountTokenSource implements IServiceAccountTokenSource {
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly timeoutMs;
+    private readonly tokens;
+    private readonly failures;
+    private readonly inFlight;
+    constructor(fetchImpl?: typeof fetch, now?: () => number, timeoutMs?: number);
+    accessToken(auth: GoogleServiceAccountAuth): Promise<string>;
+    private exchange;
+}
+//# sourceMappingURL=google-service-account.token-source.d.ts.map

package/dist/google-service-account/google-service-account.token-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-service-account.token-source.d.ts","sourceRoot":"","sources":["../../src/google-service-account/google-service-account.token-source.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAChC,MAAM,qCAAqC,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,wCAAwC,CAAC;AA8BtE;;;;;;;;GAQG;AACH,qBAAa,+BAAgC,YAAW,0BAA0B;IAM9E,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAP5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;gBAG5C,SAAS,GAAE,OAAO,KAAa,EAC/B,GAAG,GAAE,MAAM,MAAiB,EAC5B,SAAS,GAAE,MAA2B;IAGnD,WAAW,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC;YA4BpD,QAAQ;CA+CvB"}

package/dist/google-service-account/google-service-account.token-source.js

@@ -0,0 +1,206 @@
+import { createHash, createSign } from 'node:crypto';
+import { ServiceAccountAuthError, } from './service-account-token.contract.js';
+/**
+ * Google's token endpoint. Fixed rather than read from the key's own
+ * `token_uri`, so a key cannot point the server at another host with a signed
+ * assertion in hand.
+ */
+export const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const JWT_BEARER_GRANT = 'urn:ietf:params:oauth:grant-type:jwt-bearer';
+/** The longest assertion lifetime Google accepts. */
+const ASSERTION_LIFETIME_S = 3600;
+/** A token this close to expiry is replaced, so a call never leaves with one that dies on the way. */
+const REFRESH_SKEW_MS = 60_000;
+const REQUEST_TIMEOUT_MS = 10_000;
+/** Tokens (and failures) kept at once. Each distinct key, scope set and subject is one entry. */
+const MAX_CACHED_TOKENS = 256;
+/** How long a failed exchange is answered from memory when Google names no `Retry-After`. */
+const FAILURE_BACKOFF_MS = 5_000;
+/** The longest a `Retry-After` from Google holds calls back, so a far-off value cannot park a tool for good. */
+const MAX_FAILURE_BACKOFF_MS = 60_000;
+/**
+ * Mints and caches access tokens for Google service accounts: signs an RS256
+ * assertion with the key's private key, exchanges it at Google's token
+ * endpoint, and keeps the token until shortly before it expires. Concurrent
+ * calls for the same token share one exchange, and a failed exchange is
+ * answered from memory for a few seconds (or for Google's `Retry-After`), so
+ * an outage or a rate limit is not met with a fresh exchange on every call.
+ * Injected with `fetch` and a clock so suites answer for Google.
+ */
+export class GoogleServiceAccountTokenSource {
+    fetchImpl;
+    now;
+    timeoutMs;
+    tokens = new Map();
+    failures = new Map();
+    inFlight = new Map();
+    constructor(fetchImpl = fetch, now = Date.now, timeoutMs = REQUEST_TIMEOUT_MS) {
+        this.fetchImpl = fetchImpl;
+        this.now = now;
+        this.timeoutMs = timeoutMs;
+    }
+    async accessToken(auth) {
+        const key = parseServiceAccountKey(auth.credentials);
+        const scope = scopeString(auth.scopes);
+        const cacheKey = tokenCacheKey(key, scope, auth.subject);
+        const cached = this.tokens.get(cacheKey);
+        if (cached && cached.expiresAt - REFRESH_SKEW_MS > this.now())
+            return cached.accessToken;
+        const failed = this.failures.get(cacheKey);
+        if (failed && failed.retryAt > this.now())
+            throw failed.error;
+        const pending = this.inFlight.get(cacheKey);
+        if (pending)
+            return pending;
+        const exchange = this.exchange(key, scope, auth.subject, cacheKey)
+            .catch((err) => {
+            // Remembered per key, scope set and subject: a corrected key hashes to
+            // another entry, so fixing it is never held back by this.
+            if (err instanceof ServiceAccountAuthError) {
+                remember(this.failures, cacheKey, { error: err, retryAt: this.now() + err.retryAfterMs });
+            }
+            throw err;
+        })
+            .finally(() => this.inFlight.delete(cacheKey));
+        this.inFlight.set(cacheKey, exchange);
+        return exchange;
+    }
+    async exchange(key, scope, subject, cacheKey) {
+        const assertion = signAssertion(key, scope, subject, this.now());
+        let res;
+        try {
+            res = await this.fetchImpl(GOOGLE_TOKEN_URL, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+                body: new URLSearchParams({ grant_type: JWT_BEARER_GRANT, assertion }).toString(),
+                // Don't follow redirects: the assertion goes to Google's endpoint and nowhere else.
+                redirect: 'error',
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (err) {
+            const reason = err instanceof Error && err.name === 'TimeoutError'
+                ? `timed out after ${this.timeoutMs}ms`
+                : err instanceof Error
+                    ? err.message
+                    : String(err);
+            throw new ServiceAccountAuthError(`Google's token endpoint could not be reached: ${reason}`);
+        }
+        // Whatever came back is read as an object of fields or as none. A body
+        // that is not JSON, and one that is JSON but no object (`null`, a number,
+        // a list), both carry no field to read: reading one off `null` would
+        // throw a TypeError instead of the refusal below, past the code that
+        // remembers a failure and says who was refused.
+        const parsed = await res.json().catch(() => null);
+        const body = (parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {});
+        if (!res.ok) {
+            // Google says why in `error` and `error_description` (a revoked key, a
+            // scope the account may not have, a subject without delegation); neither
+            // carries the key, so both are passed on.
+            const detail = [body.error, body.error_description].filter((v) => typeof v === 'string').join(': ');
+            throw new ServiceAccountAuthError(`Google refused the service account ${key.clientEmail} (HTTP ${res.status})${detail ? `: ${detail}` : ''}`, retryAfterMs(res.headers.get('retry-after'), this.now()));
+        }
+        const accessToken = typeof body.access_token === 'string' ? body.access_token : '';
+        if (!accessToken)
+            throw new ServiceAccountAuthError("Google's token response had no access_token");
+        const expiresIn = typeof body.expires_in === 'number' ? body.expires_in : ASSERTION_LIFETIME_S;
+        this.failures.delete(cacheKey);
+        remember(this.tokens, cacheKey, { accessToken, expiresAt: this.now() + expiresIn * 1000 });
+        return accessToken;
+    }
+}
+/**
+ * Keep `value` under `cacheKey`, dropping the oldest entry first when the map
+ * is full: a Map iterates in insertion order, and re-inserting moves an entry
+ * to the back.
+ */
+function remember(map, cacheKey, value) {
+    map.delete(cacheKey);
+    if (map.size >= MAX_CACHED_TOKENS) {
+        const oldest = map.keys().next().value;
+        if (oldest !== undefined)
+            map.delete(oldest);
+    }
+    map.set(cacheKey, value);
+}
+/**
+ * How long to hold calls back after a refusal: Google's `Retry-After` (seconds
+ * or an HTTP date) when it sent one, capped, else the default backoff.
+ */
+function retryAfterMs(header, now) {
+    if (!header)
+        return FAILURE_BACKOFF_MS;
+    const seconds = Number(header);
+    const ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(header) - now;
+    if (!Number.isFinite(ms) || ms <= 0)
+        return FAILURE_BACKOFF_MS;
+    return Math.min(ms, MAX_FAILURE_BACKOFF_MS);
+}
+/**
+ * The key as an admin is likely to have stored it: the JSON file Google
+ * issued, or that JSON in base64. Only the fields the assertion needs are
+ * kept, and no error quotes what was stored.
+ */
+function parseServiceAccountKey(raw) {
+    const value = raw.trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(value.startsWith('{') ? value : Buffer.from(value, 'base64').toString('utf8'));
+    }
+    catch {
+        throw new ServiceAccountAuthError('The service-account credentials are not a key JSON. Store the JSON file Google issued for the service account.');
+    }
+    const obj = (parsed ?? {});
+    const clientEmail = typeof obj.client_email === 'string' ? obj.client_email : '';
+    const privateKey = typeof obj.private_key === 'string' ? obj.private_key : '';
+    if (!clientEmail || !privateKey) {
+        throw new ServiceAccountAuthError('The service-account key JSON has no client_email or private_key. Store the JSON file Google issued for the service account.');
+    }
+    return {
+        clientEmail,
+        privateKey,
+        privateKeyId: typeof obj.private_key_id === 'string' ? obj.private_key_id : undefined,
+    };
+}
+/**
+ * The scopes as Google wants them: space-separated, each trimmed. UTCP keeps
+ * the template as written once it validates, so stray whitespace is cleaned
+ * here, whether it sits in a list entry or in a space-separated string.
+ */
+function scopeString(scopes) {
+    const list = Array.isArray(scopes) ? scopes : [scopes];
+    return list
+        .flatMap((s) => s.split(/\s+/))
+        .filter(Boolean)
+        .join(' ');
+}
+/** One entry per key, scope set and subject. The private key is hashed so the cache holds no copy of it. */
+function tokenCacheKey(key, scope, subject) {
+    const keyHash = createHash('sha256').update(key.privateKey).digest('hex');
+    return JSON.stringify([key.clientEmail, key.privateKeyId ?? '', keyHash, scope.split(' ').sort().join(' '), subject ?? '']);
+}
+/** The RS256 assertion Google exchanges for an access token. */
+function signAssertion(key, scope, subject, now) {
+    const seconds = Math.floor(now / 1000);
+    const part = (value) => Buffer.from(JSON.stringify(value), 'utf8').toString('base64url');
+    const header = { alg: 'RS256', typ: 'JWT', ...(key.privateKeyId ? { kid: key.privateKeyId } : {}) };
+    const claims = {
+        iss: key.clientEmail,
+        scope,
+        aud: GOOGLE_TOKEN_URL,
+        iat: seconds,
+        exp: seconds + ASSERTION_LIFETIME_S,
+        ...(subject ? { sub: subject } : {}),
+    };
+    const body = `${part(header)}.${part(claims)}`;
+    let signature;
+    try {
+        signature = createSign('RSA-SHA256').update(body).end().sign(key.privateKey, 'base64url');
+    }
+    catch {
+        // What the key was is never quoted.
+        throw new ServiceAccountAuthError(`The private key of service account ${key.clientEmail} could not be read. It must be the PEM in the key JSON Google issued.`);
+    }
+    return `${body}.${signature}`;
+}
+//# sourceMappingURL=google-service-account.token-source.js.map

package/dist/google-service-account/google-service-account.token-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-service-account.token-source.js","sourceRoot":"","sources":["../../src/google-service-account/google-service-account.token-source.ts"],"names":[],"mappings":"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"}

package/dist/google-service-account/index.d.ts

@@ -0,0 +1,5 @@
+export { isGoogleServiceAccountAuth, findUnservedGoogleServiceAccountAuth, holdsLiteralGoogleServiceAccountKey, } from './google-service-account.auth.js';
+export { GoogleAuthHttpProtocol, installGoogleServiceAccountAuth } from './google-auth-http.protocol.js';
+export { GoogleServiceAccountTokenSource, GOOGLE_TOKEN_URL } from './google-service-account.token-source.js';
+export { GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE, ServiceAccountAuthError, type GoogleServiceAccountAuth, type IServiceAccountTokenSource, } from './service-account-token.contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/google-service-account/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/google-service-account/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,0BAA0B,EAC1B,oCAAoC,EACpC,mCAAmC,GACpC,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,+BAA+B,EAAE,MAAM,gCAAgC,CAAC;AACzG,OAAO,EAAE,+BAA+B,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC7G,OAAO,EACL,gCAAgC,EAChC,uBAAuB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,GAChC,MAAM,qCAAqC,CAAC"}

package/dist/google-service-account/index.js

@@ -0,0 +1,7 @@
+// Importing this module registers the `google_service_account` auth type with
+// UTCP and puts the `http` protocol that acts on it in place of the stock one.
+export { isGoogleServiceAccountAuth, findUnservedGoogleServiceAccountAuth, holdsLiteralGoogleServiceAccountKey, } from './google-service-account.auth.js';
+export { GoogleAuthHttpProtocol, installGoogleServiceAccountAuth } from './google-auth-http.protocol.js';
+export { GoogleServiceAccountTokenSource, GOOGLE_TOKEN_URL } from './google-service-account.token-source.js';
+export { GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE, ServiceAccountAuthError, } from './service-account-token.contract.js';
+//# sourceMappingURL=index.js.map

package/dist/google-service-account/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/google-service-account/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,+EAA+E;AAC/E,OAAO,EACL,0BAA0B,EAC1B,oCAAoC,EACpC,mCAAmC,GACpC,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,+BAA+B,EAAE,MAAM,gCAAgC,CAAC;AACzG,OAAO,EAAE,+BAA+B,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC7G,OAAO,EACL,gCAAgC,EAChC,uBAAuB,GAGxB,MAAM,qCAAqC,CAAC"}

package/dist/google-service-account/service-account-token.contract.d.ts

@@ -0,0 +1,33 @@
+/** The `auth_type` a `.tool` call template names to call a Google API as a service account. */
+export declare const GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE = "google_service_account";
+/**
+ * A call template's `auth` block for a Google service account, as it reaches
+ * the protocol: variables already substituted, so `credentials` holds the key
+ * itself rather than the `${VAR}` that named it.
+ */
+export interface GoogleServiceAccountAuth {
+    auth_type: typeof GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE;
+    /** The service-account key JSON Google issued, or that JSON in base64. Normally `${VAR}`, filled from the Secrets Vault. */
+    credentials: string;
+    /** The OAuth scopes the token is for: one scope, a space-separated list, or an array. */
+    scopes: string | string[];
+    /** The user to act as under domain-wide delegation. Absent, the token is the service account's own. */
+    subject?: string;
+}
+/**
+ * Answers the one question a tool call has of a service account: which bearer
+ * token to send right now. How the token is minted and how long it is kept is
+ * the implementation's business.
+ */
+export interface IServiceAccountTokenSource {
+    accessToken(auth: GoogleServiceAccountAuth): Promise<string>;
+}
+/** A service-account token could not be had. The message never carries the key. */
+export declare class ServiceAccountAuthError extends Error {
+    /** How long the same token should not be asked for again. */
+    readonly retryAfterMs: number;
+    constructor(message: string, 
+    /** How long the same token should not be asked for again. */
+    retryAfterMs?: number);
+}
+//# sourceMappingURL=service-account-token.contract.d.ts.map

package/dist/google-service-account/service-account-token.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-account-token.contract.d.ts","sourceRoot":"","sources":["../../src/google-service-account/service-account-token.contract.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,eAAO,MAAM,gCAAgC,2BAA2B,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,OAAO,gCAAgC,CAAC;IACnD,4HAA4H;IAC5H,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,uGAAuG;IACvG,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,WAAW,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9D;AAED,mFAAmF;AACnF,qBAAa,uBAAwB,SAAQ,KAAK;IAG9C,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,EAAE,MAAM;gBAF7B,OAAO,EAAE,MAAM;IACf,6DAA6D;IACpD,YAAY,GAAE,MAAc;CAKxC"}

package/dist/google-service-account/service-account-token.contract.js

@@ -0,0 +1,14 @@
+/** The `auth_type` a `.tool` call template names to call a Google API as a service account. */
+export const GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE = 'google_service_account';
+/** A service-account token could not be had. The message never carries the key. */
+export class ServiceAccountAuthError extends Error {
+    retryAfterMs;
+    constructor(message, 
+    /** How long the same token should not be asked for again. */
+    retryAfterMs = 5_000) {
+        super(message);
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'ServiceAccountAuthError';
+    }
+}
+//# sourceMappingURL=service-account-token.contract.js.map

package/dist/google-service-account/service-account-token.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-account-token.contract.js","sourceRoot":"","sources":["../../src/google-service-account/service-account-token.contract.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,MAAM,CAAC,MAAM,gCAAgC,GAAG,wBAAwB,CAAC;AA0BzE,mFAAmF;AACnF,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAIrC;IAHX,YACE,OAAe;IACf,6DAA6D;IACpD,eAAuB,KAAK;QAErC,KAAK,CAAC,OAAO,CAAC,CAAC;QAFN,iBAAY,GAAZ,YAAY,CAAgB;QAGrC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF"}

package/dist/index.d.ts

@@ -37,4 +37,5 @@ export { type SkillSummary, type LoadedSkill, skillPromptText, } from './skills.
 export { utcpNamespacePrefix, utcpNamespacedKey, seedBevelHostedManualVars, } from './utcp-namespace.js';
 export { sanitizeIdentifier, utcpNameToTsInterfaceName, findToolByName, findToolsByNames, AmbiguousToolNameError, } from './code-mode-names.js';
 export { printable } from './printable.js';
+export { GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE, GOOGLE_TOKEN_URL, GoogleAuthHttpProtocol, GoogleServiceAccountTokenSource, ServiceAccountAuthError, findUnservedGoogleServiceAccountAuth, holdsLiteralGoogleServiceAccountKey, installGoogleServiceAccountAuth, isGoogleServiceAccountAuth, type GoogleServiceAccountAuth, type IServiceAccountTokenSource, } from './google-service-account/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,KAAK,WAAW,EAChB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,cAAc,EACnB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,SAAS,EACd,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,KAAK,WAAW,EAChB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,cAAc,EACnB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,SAAS,EACd,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAM3C,OAAO,EACL,gCAAgC,EAChC,gBAAgB,EAChB,sBAAsB,EACtB,+BAA+B,EAC/B,uBAAuB,EACvB,oCAAoC,EACpC,mCAAmC,EACnC,+BAA+B,EAC/B,0BAA0B,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,GAChC,MAAM,mCAAmC,CAAC"}

package/dist/index.js

@@ -37,4 +37,9 @@ export { skillPromptText, } from './skills.js';
 export { utcpNamespacePrefix, utcpNamespacedKey, seedBevelHostedManualVars, } from './utcp-namespace.js';
 export { sanitizeIdentifier, utcpNameToTsInterfaceName, findToolByName, findToolsByNames, AmbiguousToolNameError, } from './code-mode-names.js';
 export { printable } from './printable.js';
+// Loading this package teaches UTCP `auth_type: google_service_account`, on
+// both surfaces alike: the auth type validates and the `http` protocol mints
+// the token. A side effect of the import, like the `@utcp/http` registration
+// it builds on, so neither surface has a step to forget.
+export { GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE, GOOGLE_TOKEN_URL, GoogleAuthHttpProtocol, GoogleServiceAccountTokenSource, ServiceAccountAuthError, findUnservedGoogleServiceAccountAuth, holdsLiteralGoogleServiceAccountKey, installGoogleServiceAccountAuth, isGoogleServiceAccountAuth, } from './google-service-account/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EAErB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EAGxB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EAGpB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAGL,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,GAEvB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAGL,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EAErB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EAGxB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EAGpB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAGL,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,GAEvB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAGL,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,4EAA4E;AAC5E,6EAA6E;AAC7E,6EAA6E;AAC7E,yDAAyD;AACzD,OAAO,EACL,gCAAgC,EAChC,gBAAgB,EAChB,sBAAsB,EACtB,+BAA+B,EAC/B,uBAAuB,EACvB,oCAAoC,EACpC,mCAAmC,EACnC,+BAA+B,EAC/B,0BAA0B,GAG3B,MAAM,mCAAmC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-mcp-core",
-  "version": "0.24.0",
+  "version": "0.25.2",
   "description": "The transport-agnostic half of Bevel's MCP surface: UTCP manual registration, tool discovery, MCP listing/dispatch and the code-mode meta-tools. Shared by the hosted proxy and the local stdio server.",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,7 +27,8 @@
     "@utcp/code-mode": "^1.2.13",
     "@utcp/http": "^1.1.12",
     "@utcp/mcp": "^1.2.0",
-    "@utcp/sdk": "^1.2.0"
+    "@utcp/sdk": "^1.2.0",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",

package/src/google-service-account/google-auth-http.protocol.ts

@@ -0,0 +1,62 @@
+import { CommunicationProtocol, type CallTemplate, type IUtcpClient } from '@utcp/sdk';
+import { HttpCommunicationProtocol, type HttpCallTemplate } from '@utcp/http';
+import { isGoogleServiceAccountAuth } from './google-service-account.auth.js';
+import { GoogleServiceAccountTokenSource } from './google-service-account.token-source.js';
+import type { IServiceAccountTokenSource } from './service-account-token.contract.js';
+
+/**
+ * The stock UTCP `http` protocol, taught one more auth type. A call whose
+ * template names `google_service_account` is handed to the stock protocol with
+ * that auth swapped for the bearer token it resolves to (as `oauth2_user`,
+ * which the stock protocol sends as `Authorization: Bearer <token>` and strips
+ * on a cross-origin redirect). Every other call passes through untouched.
+ */
+export class GoogleAuthHttpProtocol extends HttpCommunicationProtocol {
+  constructor(private readonly tokens: IServiceAccountTokenSource) {
+    super();
+  }
+
+  override async callTool(
+    caller: IUtcpClient,
+    toolName: string,
+    toolArgs: Record<string, unknown>,
+    toolCallTemplate: CallTemplate,
+  ): Promise<unknown> {
+    return super.callTool(caller, toolName, toolArgs, await this.withBearerToken(toolCallTemplate));
+  }
+
+  override async *callToolStreaming(
+    caller: IUtcpClient,
+    toolName: string,
+    toolArgs: Record<string, unknown>,
+    toolCallTemplate: CallTemplate,
+  ): AsyncGenerator<unknown, void, unknown> {
+    yield* super.callToolStreaming(caller, toolName, toolArgs, await this.withBearerToken(toolCallTemplate));
+  }
+
+  private async withBearerToken(template: CallTemplate): Promise<CallTemplate> {
+    const auth = (template as HttpCallTemplate).auth;
+    if (!isGoogleServiceAccountAuth(auth)) return template;
+    const accessToken = await this.tokens.accessToken(auth);
+    return { ...template, auth: { auth_type: 'oauth2_user', access_token: accessToken } } as CallTemplate;
+  }
+}
+
+/**
+ * Put the service-account-aware protocol in place of the stock `http` one,
+ * minting tokens from `tokens`. Exported so a suite can answer for Google;
+ * a process never needs to call it, since loading this module already has.
+ */
+export function installGoogleServiceAccountAuth(
+  tokens: IServiceAccountTokenSource = new GoogleServiceAccountTokenSource(),
+): void {
+  CommunicationProtocol.communicationProtocols['http'] = new GoogleAuthHttpProtocol(tokens);
+}
+
+// Installed on module load, the way `@utcp/http` installs the protocol this
+// one replaces: once per process, before any client exists (a client copies
+// the registry when it is built). The import of `@utcp/http` above has already
+// run its own registration by the time this line does, whatever order the
+// importing module lists the two in. One token cache then serves the process;
+// its entries are keyed by the key itself, so knowledge bases never share one.
+installGoogleServiceAccountAuth();

package/src/google-service-account/google-service-account.auth.ts

@@ -0,0 +1,161 @@
+import { AuthSerializer, Serializer, type Auth } from '@utcp/sdk';
+import { z } from 'zod';
+import { GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE, type GoogleServiceAccountAuth } from './service-account-token.contract.js';
+
+const GoogleServiceAccountAuthSchema = z.object({
+  auth_type: z.literal(GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE),
+  credentials: z
+    .string()
+    .min(1)
+    .describe('The service-account key JSON. Recommended to use a vault variable like "${GOOGLE_SA_KEY}".'),
+  // Trimmed before the length check, so a blank scope is refused here rather
+  // than reaching Google as an empty one.
+  scopes: z
+    .union([z.string().trim().min(1), z.array(z.string().trim().min(1)).min(1)])
+    .describe('OAuth scopes for the token, e.g. "https://www.googleapis.com/auth/adwords".'),
+  subject: z.string().trim().min(1).optional().describe('User to impersonate under domain-wide delegation.'),
+});
+
+class GoogleServiceAccountAuthSerializer extends Serializer<Auth> {
+  toDict(obj: Auth): Record<string, unknown> {
+    return { ...obj };
+  }
+
+  validateDict(obj: Record<string, unknown>): Auth {
+    return GoogleServiceAccountAuthSchema.parse(obj) as Auth;
+  }
+}
+
+/** Whether a call template's `auth` asks for a Google service-account token. */
+export function isGoogleServiceAccountAuth(auth: unknown): auth is GoogleServiceAccountAuth {
+  return (
+    typeof auth === 'object' &&
+    auth !== null &&
+    (auth as { auth_type?: unknown }).auth_type === GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE
+  );
+}
+
+/** The one call template type whose protocol turns the key into a token. */
+const SERVED_CALL_TEMPLATE_TYPE = 'http';
+
+/**
+ * The other call template types an author is likely to have reached for, which
+ * the answer below may name. A type outside this list is the file's own text,
+ * and is described rather than quoted back.
+ */
+const NAMEABLE_CALL_TEMPLATE_TYPES = ['sse', 'streamable_http', 'mcp', 'cli'];
+
+/**
+ * Where in `doc` a `google_service_account` auth block sits that nothing will
+ * act on, as a phrase for a refusal, or null when every block is the `auth` of
+ * one of `toolCallTemplates` and that template is an `http` one.
+ *
+ * `toolCallTemplates` are the templates tools are really called through, which
+ * only the caller knows: the document's shape is its business. A block
+ * anywhere else is read by nothing, whatever the object around it looks like:
+ * a template the document never registers, an `auth_tools`, a block at the
+ * root of a file that discovers its tools from a url.
+ *
+ * UTCP validates an auth type on any call template that takes an `auth`, but
+ * only the `http` protocol mints the token. Every other protocol sends an auth
+ * type it does not know as no credentials at all, so such a tool would save
+ * cleanly and then call Google unauthenticated.
+ *
+ * Every block in the document is found, at any depth (see
+ * `googleServiceAccountBlocks`), and the first one in document order that
+ * nothing will act on is the one named.
+ */
+export function findUnservedGoogleServiceAccountAuth(doc: unknown, toolCallTemplates: readonly unknown[]): string | null {
+  const served = new Set<unknown>(toolCallTemplates);
+  for (const { parent, key } of googleServiceAccountBlocks(doc)) {
+    // Judged by where it sits, so once per place it appears: an aliased
+    // block can be served in one place and ignored in another.
+    const where = unservedPlacement(parent, key, served);
+    if (where) return where;
+  }
+  return null;
+}
+
+/** `${NAME}` or `$NAME`, as UTCP spells a variable, and nothing else around it. */
+const ONE_VARIABLE_REFERENCE = /^\s*(?:\$\{[a-zA-Z0-9_]+\}|\$[a-zA-Z0-9_]+)\s*$/;
+
+/**
+ * Whether any `google_service_account` block in `doc` has its key WRITTEN IN
+ * THE DOCUMENT: a `credentials` that is anything but one variable reference.
+ *
+ * The document is a `.tool`, which is knowledge-base content: it is committed
+ * to the repository, and read by everyone and every agent that can read the
+ * knowledge base. A key written into it is a key all of them hold, for as
+ * long as the history keeps it. So the place for the key is the vault, and
+ * `credentials` only ever names the variable.
+ *
+ * Asked of the document as its author wrote it, wherever the block sits: a
+ * key in a block nothing will act on is just as readable. It cannot be asked
+ * where the auth type itself is validated, because that also runs on the
+ * template AFTER its variables were substituted, where `credentials` is the
+ * key and has to be.
+ *
+ * Says only that one was found. It never returns, quotes or measures the
+ * value: what it would be describing is the secret.
+ */
+export function holdsLiteralGoogleServiceAccountKey(doc: unknown): boolean {
+  for (const { block } of googleServiceAccountBlocks(doc)) {
+    const { credentials } = block as { credentials?: unknown };
+    // Not a string is not a key either; the auth type's own schema refuses it.
+    if (typeof credentials === 'string' && !ONE_VARIABLE_REFERENCE.test(credentials)) return true;
+  }
+  return false;
+}
+
+/**
+ * Every `google_service_account` auth block in `doc`, at any depth, with the
+ * object it sits in and the key it sits under, in document order.
+ *
+ * The walk keeps its own stack, so a deeply nested document cannot overflow
+ * the call stack, and it does not re-enter an object it has seen: a YAML
+ * anchor aliased inside itself parses to a cyclic object. A block is yielded
+ * once per place it appears, since an aliased one sits in several.
+ */
+function* googleServiceAccountBlocks(
+  doc: unknown,
+): Generator<{ block: GoogleServiceAccountAuth; parent?: Record<string, unknown>; key?: string }> {
+  const seen = new WeakSet<object>();
+  const pending: { node: unknown; parent?: Record<string, unknown>; key?: string }[] = [{ node: doc }];
+  for (let next = pending.pop(); next; next = pending.pop()) {
+    const { node, parent, key } = next;
+    if (!node || typeof node !== 'object') continue;
+    if (isGoogleServiceAccountAuth(node)) {
+      yield { block: node, parent, key };
+      continue;
+    }
+    if (seen.has(node)) continue;
+    seen.add(node);
+    // Pushed in reverse, so blocks come out in document order.
+    if (Array.isArray(node)) {
+      for (let i = node.length - 1; i >= 0; i--) pending.push({ node: node[i] });
+    } else {
+      const obj = node as Record<string, unknown>;
+      const keys = Object.keys(obj);
+      for (let i = keys.length - 1; i >= 0; i--) pending.push({ node: obj[keys[i]!], parent: obj, key: keys[i] });
+    }
+  }
+}
+
+/** Why a block under `parent[key]` is acted on by nothing, or null when it is. */
+function unservedPlacement(parent: Record<string, unknown> | undefined, key: string | undefined, served: Set<unknown>): string | null {
+  if (!parent || key !== 'auth' || typeof parent.call_template_type !== 'string') {
+    return "somewhere that is not a call template's `auth`";
+  }
+  const type = parent.call_template_type.toLowerCase().trim();
+  if (type !== SERVED_CALL_TEMPLATE_TYPE) {
+    return NAMEABLE_CALL_TEMPLATE_TYPES.includes(type) ? `a \`${type}\` call template` : 'a call template that is not an `http` one';
+  }
+  return served.has(parent) ? null : 'an `http` call template that no tool is called through';
+}
+
+// Register the auth type on module load, so a `.tool` naming it validates
+// wherever UTCP parses a call template: the inline manual route, the preview,
+// and the client re-validating a template after substituting its variables.
+// UTCP's registry is process-wide and the type carries no state, so one
+// registration serves every knowledge base. Idempotent (safe under hot-reload).
+AuthSerializer.registerAuth(GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE, new GoogleServiceAccountAuthSerializer(), true);

package/src/google-service-account/google-service-account.token-source.ts

@@ -0,0 +1,239 @@
+import { createHash, createSign } from 'node:crypto';
+import {
+  ServiceAccountAuthError,
+  type GoogleServiceAccountAuth,
+  type IServiceAccountTokenSource,
+} from './service-account-token.contract.js';
+
+/**
+ * Google's token endpoint. Fixed rather than read from the key's own
+ * `token_uri`, so a key cannot point the server at another host with a signed
+ * assertion in hand.
+ */
+export const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const JWT_BEARER_GRANT = 'urn:ietf:params:oauth:grant-type:jwt-bearer';
+/** The longest assertion lifetime Google accepts. */
+const ASSERTION_LIFETIME_S = 3600;
+/** A token this close to expiry is replaced, so a call never leaves with one that dies on the way. */
+const REFRESH_SKEW_MS = 60_000;
+const REQUEST_TIMEOUT_MS = 10_000;
+/** Tokens (and failures) kept at once. Each distinct key, scope set and subject is one entry. */
+const MAX_CACHED_TOKENS = 256;
+/** How long a failed exchange is answered from memory when Google names no `Retry-After`. */
+const FAILURE_BACKOFF_MS = 5_000;
+/** The longest a `Retry-After` from Google holds calls back, so a far-off value cannot park a tool for good. */
+const MAX_FAILURE_BACKOFF_MS = 60_000;
+
+interface ServiceAccountKey {
+  clientEmail: string;
+  privateKey: string;
+  privateKeyId?: string;
+}
+
+interface CachedToken {
+  accessToken: string;
+  expiresAt: number;
+}
+
+interface CachedFailure {
+  error: ServiceAccountAuthError;
+  retryAt: number;
+}
+
+/**
+ * Mints and caches access tokens for Google service accounts: signs an RS256
+ * assertion with the key's private key, exchanges it at Google's token
+ * endpoint, and keeps the token until shortly before it expires. Concurrent
+ * calls for the same token share one exchange, and a failed exchange is
+ * answered from memory for a few seconds (or for Google's `Retry-After`), so
+ * an outage or a rate limit is not met with a fresh exchange on every call.
+ * Injected with `fetch` and a clock so suites answer for Google.
+ */
+export class GoogleServiceAccountTokenSource implements IServiceAccountTokenSource {
+  private readonly tokens = new Map<string, CachedToken>();
+  private readonly failures = new Map<string, CachedFailure>();
+  private readonly inFlight = new Map<string, Promise<string>>();
+
+  constructor(
+    private readonly fetchImpl: typeof fetch = fetch,
+    private readonly now: () => number = Date.now,
+    private readonly timeoutMs: number = REQUEST_TIMEOUT_MS,
+  ) {}
+
+  async accessToken(auth: GoogleServiceAccountAuth): Promise<string> {
+    const key = parseServiceAccountKey(auth.credentials);
+    const scope = scopeString(auth.scopes);
+    const cacheKey = tokenCacheKey(key, scope, auth.subject);
+
+    const cached = this.tokens.get(cacheKey);
+    if (cached && cached.expiresAt - REFRESH_SKEW_MS > this.now()) return cached.accessToken;
+
+    const failed = this.failures.get(cacheKey);
+    if (failed && failed.retryAt > this.now()) throw failed.error;
+
+    const pending = this.inFlight.get(cacheKey);
+    if (pending) return pending;
+
+    const exchange = this.exchange(key, scope, auth.subject, cacheKey)
+      .catch((err: unknown) => {
+        // Remembered per key, scope set and subject: a corrected key hashes to
+        // another entry, so fixing it is never held back by this.
+        if (err instanceof ServiceAccountAuthError) {
+          remember(this.failures, cacheKey, { error: err, retryAt: this.now() + err.retryAfterMs });
+        }
+        throw err;
+      })
+      .finally(() => this.inFlight.delete(cacheKey));
+    this.inFlight.set(cacheKey, exchange);
+    return exchange;
+  }
+
+  private async exchange(key: ServiceAccountKey, scope: string, subject: string | undefined, cacheKey: string): Promise<string> {
+    const assertion = signAssertion(key, scope, subject, this.now());
+    let res: Response;
+    try {
+      res = await this.fetchImpl(GOOGLE_TOKEN_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+        body: new URLSearchParams({ grant_type: JWT_BEARER_GRANT, assertion }).toString(),
+        // Don't follow redirects: the assertion goes to Google's endpoint and nowhere else.
+        redirect: 'error',
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (err) {
+      const reason =
+        err instanceof Error && err.name === 'TimeoutError'
+          ? `timed out after ${this.timeoutMs}ms`
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      throw new ServiceAccountAuthError(`Google's token endpoint could not be reached: ${reason}`);
+    }
+
+    // Whatever came back is read as an object of fields or as none. A body
+    // that is not JSON, and one that is JSON but no object (`null`, a number,
+    // a list), both carry no field to read: reading one off `null` would
+    // throw a TypeError instead of the refusal below, past the code that
+    // remembers a failure and says who was refused.
+    const parsed: unknown = await res.json().catch(() => null);
+    const body = (parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}) as Record<string, unknown>;
+    if (!res.ok) {
+      // Google says why in `error` and `error_description` (a revoked key, a
+      // scope the account may not have, a subject without delegation); neither
+      // carries the key, so both are passed on.
+      const detail = [body.error, body.error_description].filter((v) => typeof v === 'string').join(': ');
+      throw new ServiceAccountAuthError(
+        `Google refused the service account ${key.clientEmail} (HTTP ${res.status})${detail ? `: ${detail}` : ''}`,
+        retryAfterMs(res.headers.get('retry-after'), this.now()),
+      );
+    }
+    const accessToken = typeof body.access_token === 'string' ? body.access_token : '';
+    if (!accessToken) throw new ServiceAccountAuthError("Google's token response had no access_token");
+    const expiresIn = typeof body.expires_in === 'number' ? body.expires_in : ASSERTION_LIFETIME_S;
+
+    this.failures.delete(cacheKey);
+    remember(this.tokens, cacheKey, { accessToken, expiresAt: this.now() + expiresIn * 1000 });
+    return accessToken;
+  }
+}
+
+/**
+ * Keep `value` under `cacheKey`, dropping the oldest entry first when the map
+ * is full: a Map iterates in insertion order, and re-inserting moves an entry
+ * to the back.
+ */
+function remember<T>(map: Map<string, T>, cacheKey: string, value: T): void {
+  map.delete(cacheKey);
+  if (map.size >= MAX_CACHED_TOKENS) {
+    const oldest = map.keys().next().value;
+    if (oldest !== undefined) map.delete(oldest);
+  }
+  map.set(cacheKey, value);
+}
+
+/**
+ * How long to hold calls back after a refusal: Google's `Retry-After` (seconds
+ * or an HTTP date) when it sent one, capped, else the default backoff.
+ */
+function retryAfterMs(header: string | null, now: number): number {
+  if (!header) return FAILURE_BACKOFF_MS;
+  const seconds = Number(header);
+  const ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(header) - now;
+  if (!Number.isFinite(ms) || ms <= 0) return FAILURE_BACKOFF_MS;
+  return Math.min(ms, MAX_FAILURE_BACKOFF_MS);
+}
+
+/**
+ * The key as an admin is likely to have stored it: the JSON file Google
+ * issued, or that JSON in base64. Only the fields the assertion needs are
+ * kept, and no error quotes what was stored.
+ */
+function parseServiceAccountKey(raw: string): ServiceAccountKey {
+  const value = raw.trim();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value.startsWith('{') ? value : Buffer.from(value, 'base64').toString('utf8'));
+  } catch {
+    throw new ServiceAccountAuthError(
+      'The service-account credentials are not a key JSON. Store the JSON file Google issued for the service account.',
+    );
+  }
+  const obj = (parsed ?? {}) as Record<string, unknown>;
+  const clientEmail = typeof obj.client_email === 'string' ? obj.client_email : '';
+  const privateKey = typeof obj.private_key === 'string' ? obj.private_key : '';
+  if (!clientEmail || !privateKey) {
+    throw new ServiceAccountAuthError(
+      'The service-account key JSON has no client_email or private_key. Store the JSON file Google issued for the service account.',
+    );
+  }
+  return {
+    clientEmail,
+    privateKey,
+    privateKeyId: typeof obj.private_key_id === 'string' ? obj.private_key_id : undefined,
+  };
+}
+
+/**
+ * The scopes as Google wants them: space-separated, each trimmed. UTCP keeps
+ * the template as written once it validates, so stray whitespace is cleaned
+ * here, whether it sits in a list entry or in a space-separated string.
+ */
+function scopeString(scopes: string | string[]): string {
+  const list = Array.isArray(scopes) ? scopes : [scopes];
+  return list
+    .flatMap((s) => s.split(/\s+/))
+    .filter(Boolean)
+    .join(' ');
+}
+
+/** One entry per key, scope set and subject. The private key is hashed so the cache holds no copy of it. */
+function tokenCacheKey(key: ServiceAccountKey, scope: string, subject: string | undefined): string {
+  const keyHash = createHash('sha256').update(key.privateKey).digest('hex');
+  return JSON.stringify([key.clientEmail, key.privateKeyId ?? '', keyHash, scope.split(' ').sort().join(' '), subject ?? '']);
+}
+
+/** The RS256 assertion Google exchanges for an access token. */
+function signAssertion(key: ServiceAccountKey, scope: string, subject: string | undefined, now: number): string {
+  const seconds = Math.floor(now / 1000);
+  const part = (value: unknown) => Buffer.from(JSON.stringify(value), 'utf8').toString('base64url');
+  const header = { alg: 'RS256', typ: 'JWT', ...(key.privateKeyId ? { kid: key.privateKeyId } : {}) };
+  const claims = {
+    iss: key.clientEmail,
+    scope,
+    aud: GOOGLE_TOKEN_URL,
+    iat: seconds,
+    exp: seconds + ASSERTION_LIFETIME_S,
+    ...(subject ? { sub: subject } : {}),
+  };
+  const body = `${part(header)}.${part(claims)}`;
+  let signature: string;
+  try {
+    signature = createSign('RSA-SHA256').update(body).end().sign(key.privateKey, 'base64url');
+  } catch {
+    // What the key was is never quoted.
+    throw new ServiceAccountAuthError(
+      `The private key of service account ${key.clientEmail} could not be read. It must be the PEM in the key JSON Google issued.`,
+    );
+  }
+  return `${body}.${signature}`;
+}

package/src/google-service-account/index.ts

@@ -0,0 +1,15 @@
+// Importing this module registers the `google_service_account` auth type with
+// UTCP and puts the `http` protocol that acts on it in place of the stock one.
+export {
+  isGoogleServiceAccountAuth,
+  findUnservedGoogleServiceAccountAuth,
+  holdsLiteralGoogleServiceAccountKey,
+} from './google-service-account.auth.js';
+export { GoogleAuthHttpProtocol, installGoogleServiceAccountAuth } from './google-auth-http.protocol.js';
+export { GoogleServiceAccountTokenSource, GOOGLE_TOKEN_URL } from './google-service-account.token-source.js';
+export {
+  GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE,
+  ServiceAccountAuthError,
+  type GoogleServiceAccountAuth,
+  type IServiceAccountTokenSource,
+} from './service-account-token.contract.js';

package/src/google-service-account/service-account-token.contract.ts

@@ -0,0 +1,38 @@
+/** The `auth_type` a `.tool` call template names to call a Google API as a service account. */
+export const GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE = 'google_service_account';
+
+/**
+ * A call template's `auth` block for a Google service account, as it reaches
+ * the protocol: variables already substituted, so `credentials` holds the key
+ * itself rather than the `${VAR}` that named it.
+ */
+export interface GoogleServiceAccountAuth {
+  auth_type: typeof GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE;
+  /** The service-account key JSON Google issued, or that JSON in base64. Normally `${VAR}`, filled from the Secrets Vault. */
+  credentials: string;
+  /** The OAuth scopes the token is for: one scope, a space-separated list, or an array. */
+  scopes: string | string[];
+  /** The user to act as under domain-wide delegation. Absent, the token is the service account's own. */
+  subject?: string;
+}
+
+/**
+ * Answers the one question a tool call has of a service account: which bearer
+ * token to send right now. How the token is minted and how long it is kept is
+ * the implementation's business.
+ */
+export interface IServiceAccountTokenSource {
+  accessToken(auth: GoogleServiceAccountAuth): Promise<string>;
+}
+
+/** A service-account token could not be had. The message never carries the key. */
+export class ServiceAccountAuthError extends Error {
+  constructor(
+    message: string,
+    /** How long the same token should not be asked for again. */
+    readonly retryAfterMs: number = 5_000,
+  ) {
+    super(message);
+    this.name = 'ServiceAccountAuthError';
+  }
+}

package/src/index.ts

@@ -120,3 +120,21 @@ export {
 } from './code-mode-names.js';
 
 export { printable } from './printable.js';
+
+// Loading this package teaches UTCP `auth_type: google_service_account`, on
+// both surfaces alike: the auth type validates and the `http` protocol mints
+// the token. A side effect of the import, like the `@utcp/http` registration
+// it builds on, so neither surface has a step to forget.
+export {
+  GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE,
+  GOOGLE_TOKEN_URL,
+  GoogleAuthHttpProtocol,
+  GoogleServiceAccountTokenSource,
+  ServiceAccountAuthError,
+  findUnservedGoogleServiceAccountAuth,
+  holdsLiteralGoogleServiceAccountKey,
+  installGoogleServiceAccountAuth,
+  isGoogleServiceAccountAuth,
+  type GoogleServiceAccountAuth,
+  type IServiceAccountTokenSource,
+} from './google-service-account/index.js';