@bevel-software/platform-mcp-core 0.23.0 → 0.25.0

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

@@ -36,6 +36,7 @@ export {
 
 export {
   describeToolFailure,
+  withTransportDetail,
   toCallToolResult,
   renderProgress,
   toolError,
@@ -48,13 +49,40 @@ export {
 } from './results.js';
 
 export {
-  CODE_MODE_META_TOOLS,
+  codeModeMetaTools,
+  chainNamespaceExample,
   META_TOOL_NAMES,
   CALL_TOOL_CHAIN_MAX_OUTPUT,
+  CALL_TOOL_CHAIN_NAME,
+  CHAIN_FAILURES_RULE,
+  CHAIN_LARGE_RESULTS_RULE,
+  type CodeModeMetaToolsOptions,
   type SpillPort,
   dispatchMetaTool,
 } from './meta-tools.js';
 
+export {
+  CHAIN_RUNTIME_PRELUDE,
+  CHAIN_TIMEOUT_DEFAULT_MS,
+  CHAIN_TIMEOUT_MAX_MS,
+  CHAIN_TIMEOUT_MIN_MS,
+  type ChainNamespaces,
+  type ToolChainOutcome,
+  chainNamespaces,
+  chainOutOfMemoryMessage,
+  chainTimeoutMessage,
+  describeChainFailure,
+  runToolChain,
+  unknownNamespaceMessage,
+  withChainRuntime,
+} from './chain-runtime.js';
+
+export {
+  type ChainExample,
+  type ChainExampleTool,
+  chainExample,
+} from './chain-example.js';
+
 export { registerManual, dispatchToolCall } from './dispatch.js';
 
 export {
@@ -62,7 +90,6 @@ export {
   RETIRED_TOOL_NAMES,
   retiredToolMessage,
   retiredToolInFailure,
-  retiredToolChainFailure,
 } from './retired-tools.js';
 
 export {
@@ -93,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';