@steve31415/baselib 3.26.0 → 3.28.0

package/README.md

@@ -5,7 +5,7 @@ What it provides and why: `docs/SPEC.md`. How it's put together:
 `docs/IMPL.md`. Full design rationale with alternatives:
 `~/migration/research/base-services-design.md`.
 
-Server subpath exports: `config`, `log`, `auth`, `s2s`, `db`, `http`, `sync`,
+Server subpath exports: `config`, `log`, `auth`, `oauth-resource`, `s2s`, `db`, `http`, `sync`,
 `app-update`, `llm`, `email`, and `twitter`. Browser exports: `log-browser`, `rum`,
 `slow-fetch`, `sync-browser`, and `app-update-browser`.
 

package/dist/http.d.ts

@@ -5,6 +5,16 @@ import type { Logger } from './log-core.js';
  *  identity); /health excluded. Entry-point detail beyond this (key
  *  parameters, outcomes) is the handler's job per OPERATIONS.md. */
 export declare function requestLogging(logger: Logger): import("hono").MiddlewareHandler<any, string, {}, Response>;
+/** The address of the client that connected to Google's edge, read from
+ *  X-Forwarded-For — for per-source rate limits, never for authorization.
+ *  Google appends to whatever the client sent, so only the tail can be
+ *  trusted: through the fleet load balancer the header ends
+ *  `<client>,<load balancer>` (Google's Application Load Balancer docs: it
+ *  "does not verify any IP addresses that precede" those two), and a request
+ *  made straight to the service's run.app URL ends `<client>`. `canonicalHost`
+ *  is the app's public host: a request for any other host did not come
+ *  through the load balancer. */
+export declare function forwardedClientIp(c: Context, canonicalHost: string): string;
 export declare function addHealth(app: Hono): void;
 /** app.onError handler: log with full context, return a plain 500. */
 export declare function errorHandler(logger: Logger): (err: Error, c: Context) => (Response & import("hono").TypedResponse<{

package/dist/http.js

@@ -25,6 +25,23 @@ export function requestLogging(logger) {
         });
     });
 }
+/** The address of the client that connected to Google's edge, read from
+ *  X-Forwarded-For — for per-source rate limits, never for authorization.
+ *  Google appends to whatever the client sent, so only the tail can be
+ *  trusted: through the fleet load balancer the header ends
+ *  `<client>,<load balancer>` (Google's Application Load Balancer docs: it
+ *  "does not verify any IP addresses that precede" those two), and a request
+ *  made straight to the service's run.app URL ends `<client>`. `canonicalHost`
+ *  is the app's public host: a request for any other host did not come
+ *  through the load balancer. */
+export function forwardedClientIp(c, canonicalHost) {
+    const hops = (c.req.header('x-forwarded-for') ?? '')
+        .split(',')
+        .map((hop) => hop.trim())
+        .filter(Boolean);
+    const viaLoadBalancer = (c.req.header('host') ?? '').toLowerCase() === canonicalHost.toLowerCase();
+    return hops.at(viaLoadBalancer ? -2 : -1) ?? 'unknown';
+}
 export function addHealth(app) {
     app.get('/health', (c) => c.json({
         ok: true,

package/dist/llm/complete.d.ts

@@ -1,4 +1,11 @@
-import type { LLMRequest, LLMResponse } from './types.js';
+import type { LLMRequest, LLMResponse, Effort } from './types.js';
+import type { ModelEntry } from './models.js';
+/**
+ * The effort level to send a model: none when the model has no effort
+ * control, otherwise the requested level clamped to the nearest one the
+ * model accepts (e.g. `minimal` → `low` on models without a `minimal`).
+ */
+export declare function resolveEffort(entry: ModelEntry, effort: Effort | undefined): Effort | undefined;
 /**
  * Call an LLM with automatic failover to alternative providers.
  *

package/dist/llm/complete.js

@@ -1,9 +1,25 @@
-import { LLMError } from './types.js';
+import { LLMError, EFFORT_LEVELS } from './types.js';
 import { MODEL_REGISTRY, THINKING_HEADROOM_WARN_TOKENS } from './models.js';
 import { providers } from './providers/index.js';
 const DEFAULT_MAX_TOKENS = 2048;
 const DEFAULT_TEMPERATURE = 0.3;
 const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_THINKING_LEVELS = ['low', 'medium', 'high'];
+/**
+ * The effort level to send a model: none when the model has no effort
+ * control, otherwise the requested level clamped to the nearest one the
+ * model accepts (e.g. `minimal` → `low` on models without a `minimal`).
+ */
+export function resolveEffort(entry, effort) {
+    if (!entry.supportsEffort || effort === undefined)
+        return undefined;
+    const levels = entry.thinkingLevels ?? DEFAULT_THINKING_LEVELS;
+    if (levels.includes(effort))
+        return effort;
+    const rank = (level) => EFFORT_LEVELS.indexOf(level);
+    const wanted = rank(effort);
+    return [...levels].sort((a, b) => Math.abs(rank(a) - wanted) - Math.abs(rank(b) - wanted))[0];
+}
 /**
  * Call an LLM with automatic failover to alternative providers.
  *
@@ -42,6 +58,16 @@ export async function llmComplete(request) {
             ...(request.callSite ? { callSite: request.callSite } : {}),
         });
     }
+    // Google is retiring the Gemini thinking budget in favor of levels (see
+    // LLMRequest.thinkingBudget). Flag every caller still passing one so the
+    // migration to `effort` is visible in the logs, not discovered by a 400.
+    if (request.thinkingBudget !== undefined) {
+        request.logger?.warn('llm.thinking_budget_deprecated', {
+            model: request.model,
+            thinkingBudget: request.thinkingBudget,
+            ...(request.callSite ? { callSite: request.callSite } : {}),
+        });
+    }
     // Build the ordered list of models to try: primary + fallbacks
     const modelsToTry = [request.model, ...entry.fallbacks];
     const failedAttempts = [];
@@ -67,7 +93,7 @@ export async function llmComplete(request) {
                 supportsTemperature: modelEntry.supportsTemperature ?? true,
                 supportsThinkingBudgetZero: modelEntry.supportsThinkingBudgetZero ?? true,
                 supportsForcedToolChoice: modelEntry.supportsForcedToolChoice ?? true,
-                effort: modelEntry.supportsEffort ? request.effort : undefined,
+                effort: resolveEffort(modelEntry, request.effort),
                 jsonSchema: request.jsonSchema,
                 apiKey,
                 logger: request.logger,

package/dist/llm/index.d.ts

@@ -1,4 +1,4 @@
 export { llmComplete } from './complete.js';
 export { MODEL_REGISTRY } from './models.js';
 export type { ModelEntry } from './models.js';
-export { LLMError, type LLMRequest, type LLMResponse, type FailedAttempt, type FinishCategory, type ProviderName, type ApiKeys, type JsonSchema, } from './types.js';
+export { LLMError, EFFORT_LEVELS, type Effort, type LLMRequest, type LLMResponse, type FailedAttempt, type FinishCategory, type ProviderName, type ApiKeys, type JsonSchema, } from './types.js';

package/dist/llm/index.js

@@ -7,4 +7,4 @@
 // Public API
 export { llmComplete } from './complete.js';
 export { MODEL_REGISTRY } from './models.js';
-export { LLMError, } from './types.js';
+export { LLMError, EFFORT_LEVELS, } from './types.js';

package/dist/llm/models.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderName } from './types.js';
+import type { ProviderName, Effort } from './types.js';
 export interface ModelEntry {
     /** Provider that serves this model. */
     provider: ProviderName;
@@ -22,12 +22,22 @@ export interface ModelEntry {
      */
     supportsThinkingBudgetZero?: boolean;
     /**
-     * Whether this model accepts Anthropic's `output_config.effort` parameter
-     * (verified on Sonnet 5 / Sonnet 4.6 2026-08-10; documented GA on Opus
-     * 4.6+/5). Defaults to `false`; the effort option is dropped for models
-     * without it.
+     * Whether this model accepts a reasoning-effort level: Anthropic's
+     * `output_config.effort` (verified on Sonnet 5 / Sonnet 4.6 2026-08-10;
+     * documented GA on Opus 4.6+/5) or Gemini's `thinkingConfig.thinkingLevel`
+     * (every Gemini 3.x model; verified live 2026-10-06). Defaults to `false`;
+     * the effort option is dropped for models without it.
      */
     supportsEffort?: boolean;
+    /**
+     * The effort levels this model accepts, for `supportsEffort` models whose
+     * set differs from the default `low | medium | high`. A requested level
+     * outside the set is clamped to the nearest one in it (`minimal` → `low`).
+     * Gemini 3.5 Flash-Lite, 3.6 Flash and 3 Flash preview also take `minimal`
+     * ("no hidden reasoning"); 3.1 Pro preview does not (Google's per-model
+     * table, 2026-10-06).
+     */
+    thinkingLevels?: readonly Effort[];
     /**
      * Whether this model performs hidden reasoning when the request omits any
      * thinking configuration (which this library always does). Defaults to

package/dist/llm/models.js

@@ -11,7 +11,12 @@ export const THINKING_HEADROOM_WARN_TOKENS = 4096;
 export const MODEL_REGISTRY = {
     // 2026-08 suite refresh: current models are claude-sonnet-5 / claude-opus-5
     // (Anthropic; claude-opus-5-5 succeeded claude-opus-5 on 2026-09-22), the gpt-5.6 sol/terra/luna family (OpenAI), and the Gemini
-    // 3.5/3.6 GA line plus gemini-3.1-pro-preview (Google). Older names stay
+    // 3.5/3.6 GA line plus gemini-3.1-pro-preview (Google). Google's 2026-10
+    // deprecation notice: `temperature`/`topP`/`topK` have had no effect since
+    // 3.6 Flash and, like `thinkingBudget`, will 400 on models after 3.8 Flash
+    // — hence `supportsTemperature: false` from 3.6 Flash on and `effort`
+    // (thinking level) as the reasoning control on every Gemini 3.x entry.
+    // Older names stay
     // registered so existing callers keep working, but no fallback chain routes
     // through a retiring model: gemini-2.5-pro and gemini-2.5-flash shut down
     // 2026-10-16, and the gpt-4o snapshots retire from 2026-10 onward.
@@ -30,6 +35,8 @@ export const MODEL_REGISTRY = {
         // so no `thinksByDefault` headroom warning.
         // Rejects thinkingBudget 0 (400, verified 2026-08-09).
         supportsThinkingBudgetZero: false,
+        supportsEffort: true,
+        thinkingLevels: ['minimal', 'low', 'medium', 'high'],
     },
     'gemini-3.6-flash': {
         provider: 'gemini',
@@ -40,6 +47,11 @@ export const MODEL_REGISTRY = {
         thinksByDefault: true,
         // Rejects thinkingBudget 0 (400, verified 2026-08-09).
         supportsThinkingBudgetZero: false,
+        supportsEffort: true,
+        thinkingLevels: ['minimal', 'low', 'medium', 'high'],
+        // Sampling parameters are fixed at their defaults from this model on
+        // (Google, 2026-10); still accepted today, so omitting changes nothing.
+        supportsTemperature: false,
     },
     'gpt-5.6-luna': {
         provider: 'openai',
@@ -63,11 +75,14 @@ export const MODEL_REGISTRY = {
         provider: 'gemini',
         apiModelId: 'gemini-3.1-flash-lite',
         fallbacks: ['claude-sonnet-4-6'],
+        supportsEffort: true,
     },
     'gemini-3-flash-preview': {
         provider: 'gemini',
         apiModelId: 'gemini-3-flash-preview',
         fallbacks: ['claude-haiku-4-5', 'gpt-5.6-luna'],
+        supportsEffort: true,
+        thinkingLevels: ['minimal', 'low', 'medium', 'high'],
     },
     'gpt-4o-mini': {
         provider: 'openai',
@@ -181,6 +196,8 @@ export const MODEL_REGISTRY = {
         thinksByDefault: true,
         // Rejects thinkingBudget 0 (400, verified 2026-08-09).
         supportsThinkingBudgetZero: false,
+        // Levels low|medium|high only (no `minimal`) — the default set.
+        supportsEffort: true,
     },
     // Retiring 2026-10-16 — migrate callers to gemini-3.1-pro-preview.
     'gemini-2.5-pro': {

package/dist/llm/providers/gemini.js

@@ -53,13 +53,18 @@ export const geminiProvider = {
             generationConfig.responseSchema = stripUnsupportedSchemaFields(request.jsonSchema.schema);
         }
         // Gemini thinking models reason before answering; the reasoning tokens
-        // count against maxOutputTokens. Capping the thinking budget reserves
-        // headroom for the visible response so a long reasoning pass can't
-        // truncate it. Models with a thinking floor (registry
+        // count against maxOutputTokens. `effort` (pre-gated and clamped in
+        // complete.ts) is the current control, sent as a thinking level — not a
+        // token cap, so callers size maxOutputTokens for it. The deprecated
+        // thinkingBudget is still forwarded when no level is set (the API rejects
+        // both together). Models with a thinking floor (registry
         // `supportsThinkingBudgetZero: false`) reject an explicit 0 budget with a
         // 400 — for those a 0 means "as little thinking as possible", which their
         // default already is, so the config is omitted entirely.
-        if (request.thinkingBudget !== undefined
+        if (request.effort) {
+            generationConfig.thinkingConfig = { thinkingLevel: request.effort };
+        }
+        else if (request.thinkingBudget !== undefined
             && (request.thinkingBudget !== 0 || request.supportsThinkingBudgetZero)) {
             generationConfig.thinkingConfig = { thinkingBudget: request.thinkingBudget };
         }

package/dist/llm/types.d.ts

@@ -35,21 +35,25 @@ export interface LLMRequest {
     /** Timeout per provider attempt, including response body download, in ms. Default: 60000. */
     timeoutMs?: number;
     /**
-     * Cap on reasoning/thinking tokens for models that support hidden reasoning
-     * (currently Gemini 2.5 family). Reasoning tokens are charged against the
-     * same budget as output tokens, so when thinking is unbounded it can starve
-     * the visible response and cause mid-string truncation. Setting this
-     * reserves headroom for the response. Ignored by providers that don't
-     * expose a thinking budget.
+     * @deprecated Use `effort`. Gemini's token cap on hidden reasoning. Gemini
+     * 3.x already remaps a budget to a thinking *level* (so it is no longer a
+     * cap), and Google has announced that models after 3.8 Flash reject it
+     * outright (400). Still forwarded to Gemini when `effort` is absent, with
+     * WARN `llm.thinking_budget_deprecated` per call; ignored by Anthropic and
+     * OpenAI, and ignored by Gemini when `effort` is also set.
      */
     thinkingBudget?: number;
     /**
-     * Output-effort level for models that support Anthropic's `output_config.
-     * effort` (registry `supportsEffort`). Lower effort trades thoroughness for
-     * latency/cost. Currently honored on Anthropic models only; when a call
-     * fails over to another provider the fallback runs at its own defaults.
+     * Reasoning-effort level for models that expose one (registry
+     * `supportsEffort`): Anthropic `output_config.effort`, Gemini
+     * `thinkingConfig.thinkingLevel`. Lower effort trades thoroughness for
+     * latency and cost. A level the target model lacks is clamped to its
+     * nearest supported level (registry `thinkingLevels`; `minimal` → `low` on
+     * Anthropic). Dropped for models without the control, so a failed-over
+     * call runs at the fallback's defaults. Levels are not token caps: size
+     * `maxTokens` for the reasoning the level will do.
      */
-    effort?: 'low' | 'medium' | 'high';
+    effort?: Effort;
     /**
      * Optional short identifier for the calling feature (e.g. 'video_classify',
      * 'message_prioritize', 'log_summary'). Included in llm.request and
@@ -80,6 +84,14 @@ export interface LLMRequest {
  * provider-specific vocabulary local to the adapter that owns it.
  */
 export type FinishCategory = 'complete' | 'truncated' | 'declined' | 'other';
+/**
+ * Reasoning-effort levels, ordered from least to most. Each provider adapter
+ * maps a level to its native control (Anthropic `output_config.effort`,
+ * Gemini `thinkingConfig.thinkingLevel`); `minimal` exists only on some
+ * Gemini models and means "no hidden reasoning".
+ */
+export declare const EFFORT_LEVELS: readonly ["minimal", "low", "medium", "high"];
+export type Effort = (typeof EFFORT_LEVELS)[number];
 /** Successful response from llmComplete(). */
 export interface LLMResponse {
     /** The text output (or JSON stringified if jsonSchema was used). */
@@ -188,8 +200,11 @@ export interface ProviderCallRequest {
     logger?: Logger;
     timeoutMs: number;
     thinkingBudget?: number;
-    /** Effort level, pre-gated by the registry's `supportsEffort` (absent when unsupported). */
-    effort?: 'low' | 'medium' | 'high';
+    /**
+     * Effort level, pre-gated by the registry's `supportsEffort` (absent when
+     * unsupported) and clamped to the model's `thinkingLevels`.
+     */
+    effort?: Effort;
     callSite?: string;
     cacheSystemPrompt?: boolean;
 }

package/dist/llm/types.js

@@ -1,3 +1,10 @@
+/**
+ * Reasoning-effort levels, ordered from least to most. Each provider adapter
+ * maps a level to its native control (Anthropic `output_config.effort`,
+ * Gemini `thinkingConfig.thinkingLevel`); `minimal` exists only on some
+ * Gemini models and means "no hidden reasoning".
+ */
+export const EFFORT_LEVELS = ['minimal', 'low', 'medium', 'high'];
 /** Error thrown when an LLM provider call fails. Its message may contain private input; do not log verbatim. */
 export class LLMError extends Error {
     provider;

package/dist/oauth-resource.d.ts

@@ -0,0 +1,85 @@
+import type { Context } from 'hono';
+import type { UserAccessPolicy, UserRole } from './auth.js';
+import type { Logger } from './log-core.js';
+import { serviceFetch } from './s2s.js';
+/** The exact shape of an access token: the prefix plus 32 random bytes in
+ *  base64url. Anything else is refused before any cache or network work. */
+export declare const ACCESS_TOKEN_PATTERN: RegExp;
+/** A user acting through a connector, limited to the scopes they approved. */
+export interface ConnectorUser {
+    type: 'connector';
+    email: string;
+    name?: string;
+    userId?: string;
+    role: UserRole;
+    scopes: ReadonlySet<string>;
+    /** The OAuth client the user approved (e.g. Claude's client ID URL). */
+    clientId: string;
+    /** The consent this token descends from; revoking it kills the token. */
+    grantId: string;
+}
+declare module 'hono' {
+    interface ContextVariableMap {
+        connector: ConnectorUser;
+    }
+}
+export interface ConnectorResourceOptions {
+    /** This endpoint's exact public URL, e.g. https://notes.apps.snewman.net/mcp
+     *  — the OAuth resource tokens must have been issued for. */
+    resource: string;
+    /** Every scope this resource defines (advertised in metadata and
+     *  challenges). */
+    scopes: readonly string[];
+    /** Base URL of the auth service (the authorization server). */
+    authUrl?: string;
+}
+export interface RequireConnectorUserOptions extends ConnectorResourceOptions {
+    /** Which users this app admits — the same policy as requireIdentity. */
+    userAccess?: UserAccessPolicy;
+    logger?: Logger;
+    /** Per-user request ceiling (default 600/min). */
+    rateLimitPerMin?: number;
+    /** Injectable for tests: performs the introspection call for one token. */
+    introspect?: (token: string) => Promise<Response>;
+    cache?: {
+        hitMs?: number;
+        missMs?: number;
+        maxEntries?: number;
+    };
+    /** Uncached tokens one source address may have introspected per minute
+     *  (default 60). A connector's own traffic needs one per token per cache
+     *  window, so this only ever binds on a stream of unknown tokens. */
+    introspectionsPerSourcePerMin?: number;
+    now?: () => number;
+}
+/** The introspection call itself: s2s OIDC to the auth service, bounded in
+ *  time including the ID-token mint. */
+export declare function introspectAtAuth(authUrl: string, token: string, fetcher?: typeof serviceFetch): Promise<Response>;
+/** Where the RFC 9728 document for `resource` is served: the well-known
+ *  prefix inserted before the resource's path. Built from configuration,
+ *  never from the request URL (which is http:// behind the load balancer). */
+export declare function resourceMetadataUrl(resource: string): string;
+/** The RFC 9728 protected-resource metadata document. */
+export declare function protectedResourceMetadata(opts: ConnectorResourceOptions): {
+    resource: string;
+    authorization_servers: string[];
+    scopes_supported: string[];
+    bearer_methods_supported: string[];
+};
+/** 403 that asks the client to re-run consent for more scope. The challenge
+ *  names every scope of the resource, because a client does not reliably
+ *  carry earlier scopes into a step-up. */
+export declare function insufficientScope(c: Context, opts: ConnectorResourceOptions): Response & import("hono").TypedResponse<{
+    error: string;
+}, 403, "json">;
+export declare function requireConnectorUser(opts: RequireConnectorUserOptions): import("hono").MiddlewareHandler<any, string, {}, (Response & import("hono").TypedResponse<{
+    error: string;
+}, 401, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+    code: string;
+    email: string;
+}, 403, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 429, "json">) | (Response & import("hono").TypedResponse<{
+    error: string;
+}, 503, "json">)>;

package/dist/oauth-resource.js

@@ -0,0 +1,257 @@
+// Resource-server side of the fleet's OAuth access tokens — the credential a
+// connector (claude.ai's MCP client) presents on a user's behalf.
+//
+// The auth service is the authorization server: it shows the consent page and
+// issues opaque `pwat_…` access tokens bound to exactly one resource (an
+// app's MCP endpoint URL) and a scope list. An app that serves such an
+// endpoint mounts requireConnectorUser() on that route ONLY. It is
+// deliberately separate from requireIdentity(): a connector token must never
+// be admitted on an app's ordinary user routes, so it produces its own
+// context variable (`connector`) and never sets `identity` or `user`.
+//
+// Resolution, in order:
+//   1. Test bypass (AUTH_MODE=test): X-Test-Connector-User (+ -Role, -Scope).
+//      Credential verification is bypassed; the access policy and the app's
+//      scope checks still run.
+//   2. Authorization: Bearer pwat_… → introspection at the auth service over
+//      s2s OIDC, cached in-instance (5 min hits, capped by the token's own
+//      expiry / 30 s misses, bounded LRU). Introspections are budgeted per
+//      source address, so a stream of junk tokens costs the auth service a
+//      bounded number of calls and costs other callers nothing.
+//
+// Failure mapping matters to the client. A 401 makes it discard its token and
+// re-run sign-in, so 401 is reserved for "this token is not valid here".
+// Anything that is OUR fault or the auth service's (unreachable, slow, any
+// non-200, a malformed answer) is 503 and is never cached.
+import { createHash } from 'node:crypto';
+import { createMiddleware } from 'hono/factory';
+import { ACCESS_DENIED_CODE, DEFAULT_AUTH_URL, userAllowed } from './auth.js';
+import { authMode } from './config.js';
+import { forwardedClientIp } from './http.js';
+import { RateLimiter, serviceFetch } from './s2s.js';
+/** The exact shape of an access token: the prefix plus 32 random bytes in
+ *  base64url. Anything else is refused before any cache or network work. */
+export const ACCESS_TOKEN_PATTERN = /^pwat_[A-Za-z0-9_-]{43}$/;
+const INTROSPECT_TIMEOUT_MS = 5_000;
+/** The introspection call itself: s2s OIDC to the auth service, bounded in
+ *  time including the ID-token mint. */
+export function introspectAtAuth(authUrl, token, fetcher = serviceFetch) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error('introspection timed out')), INTROSPECT_TIMEOUT_MS);
+    });
+    const call = fetcher(`${authUrl}/api/oauth/introspect`, {
+        audience: authUrl,
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ token }),
+        signal: AbortSignal.timeout(INTROSPECT_TIMEOUT_MS),
+    });
+    return Promise.race([call, timeout]).finally(() => clearTimeout(timer));
+}
+function authBase(opts) {
+    return (opts.authUrl ?? DEFAULT_AUTH_URL).replace(/\/$/, '');
+}
+/** Where the RFC 9728 document for `resource` is served: the well-known
+ *  prefix inserted before the resource's path. Built from configuration,
+ *  never from the request URL (which is http:// behind the load balancer). */
+export function resourceMetadataUrl(resource) {
+    const url = new URL(resource);
+    const path = url.pathname === '/' ? '' : url.pathname;
+    return `${url.origin}/.well-known/oauth-protected-resource${path}`;
+}
+/** The RFC 9728 protected-resource metadata document. */
+export function protectedResourceMetadata(opts) {
+    return {
+        resource: opts.resource,
+        authorization_servers: [authBase(opts)],
+        scopes_supported: [...opts.scopes],
+        bearer_methods_supported: ['header'],
+    };
+}
+function challenge(opts, error) {
+    return [
+        ...(error ? [`error="${error}"`] : []),
+        `resource_metadata="${resourceMetadataUrl(opts.resource)}"`,
+        `scope="${opts.scopes.join(' ')}"`,
+    ].join(', ');
+}
+function unauthorized(c, opts, error) {
+    c.header('www-authenticate', `Bearer ${challenge(opts, error)}`);
+    c.header('cache-control', 'no-store');
+    return c.json({ error: error ?? 'unauthorized' }, 401);
+}
+/** 403 that asks the client to re-run consent for more scope. The challenge
+ *  names every scope of the resource, because a client does not reliably
+ *  carry earlier scopes into a step-up. */
+export function insufficientScope(c, opts) {
+    c.header('www-authenticate', `Bearer ${challenge(opts, 'insufficient_scope')}`);
+    c.header('cache-control', 'no-store');
+    return c.json({ error: 'insufficient_scope' }, 403);
+}
+/** A Map in insertion order doubles as an LRU: a hit is re-inserted, and the
+ *  oldest key is dropped when full. Unauthenticated callers choose the keys,
+ *  so the bound is what keeps them from growing the process. */
+class LruCache {
+    maxEntries;
+    entries = new Map();
+    constructor(maxEntries) {
+        this.maxEntries = maxEntries;
+    }
+    get(key, now) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        this.entries.delete(key);
+        if (entry.expires <= now)
+            return undefined;
+        this.entries.set(key, entry);
+        return entry;
+    }
+    set(key, entry) {
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        if (this.entries.size > this.maxEntries) {
+            this.entries.delete(this.entries.keys().next().value);
+        }
+    }
+}
+function parseRole(value) {
+    return value === 'owner' || value === 'invited' ? value : undefined;
+}
+function parseScopes(value) {
+    return new Set(typeof value === 'string' ? value.split(' ').filter(Boolean) : []);
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+export function requireConnectorUser(opts) {
+    const policy = opts.userAccess ?? 'owner';
+    const hitMs = opts.cache?.hitMs ?? 300_000;
+    const missMs = opts.cache?.missMs ?? 30_000;
+    const cache = new LruCache(opts.cache?.maxEntries ?? 1_000);
+    const now = opts.now ?? Date.now;
+    const limiter = new RateLimiter(opts.rateLimitPerMin ?? 600);
+    const sourceBudget = new RateLimiter(opts.introspectionsPerSourcePerMin ?? 60);
+    const resourceHost = new URL(opts.resource).host;
+    const introspect = opts.introspect ?? ((token) => introspectAtAuth(authBase(opts), token));
+    const unavailable = (c) => {
+        c.header('cache-control', 'no-store');
+        return c.json({ error: 'auth service unavailable' }, 503);
+    };
+    const rateLimited = (c) => {
+        c.header('cache-control', 'no-store');
+        return c.json({ error: 'rate limit exceeded' }, 429);
+    };
+    return createMiddleware(async (c, next) => {
+        const admit = (user) => {
+            if (!userAllowed(policy, user)) {
+                opts.logger?.warn('connector user access denied', {
+                    email: user.email,
+                    policy,
+                    path: c.req.path,
+                });
+                c.header('cache-control', 'no-store');
+                return c.json({ error: 'not enabled for this account', code: ACCESS_DENIED_CODE, email: user.email }, 403);
+            }
+            if (!limiter.allow(user.email)) {
+                opts.logger?.warn('connector rate limit exceeded', { email: user.email, path: c.req.path });
+                return rateLimited(c);
+            }
+            // A copy per request: the cached identity is shared, and a Set typed
+            // read-only is still mutable at runtime.
+            c.set('connector', { ...user, scopes: new Set(user.scopes) });
+            return next();
+        };
+        if (authMode() === 'test') {
+            const email = c.req.header('x-test-connector-user');
+            if (!email)
+                return unauthorized(c, opts);
+            const scope = c.req.header('x-test-connector-scope');
+            return admit({
+                type: 'connector',
+                email,
+                role: parseRole(c.req.header('x-test-connector-role')) ?? 'invited',
+                scopes: scope === undefined ? new Set(opts.scopes) : parseScopes(scope),
+                clientId: 'test-client',
+                grantId: 'test-grant',
+            });
+        }
+        const header = c.req.header('authorization');
+        if (!header)
+            return unauthorized(c, opts);
+        const token = header.match(/^Bearer\s+(\S+)\s*$/i)?.[1];
+        // A bearer of any other shape — including a service's OIDC token — is not
+        // ours to verify and is never forwarded or logged.
+        if (!token || !ACCESS_TOKEN_PATTERN.test(token))
+            return unauthorized(c, opts, 'invalid_token');
+        const key = createHash('sha256').update(token).digest('hex');
+        const cached = cache.get(key, now());
+        if (cached)
+            return cached.user ? admit(cached.user) : unauthorized(c, opts, 'invalid_token');
+        const reject = () => {
+            cache.set(key, { expires: now() + missMs });
+            return unauthorized(c, opts, 'invalid_token');
+        };
+        // Spent before the call, on every uncached token whatever the answer, so
+        // concurrent junk cannot overshoot it. Over budget is a 429, never a 401:
+        // a client holding a good token must not be told to discard it.
+        if (!sourceBudget.allow(forwardedClientIp(c, resourceHost))) {
+            opts.logger?.warn('connector introspection budget exhausted', { path: c.req.path });
+            return rateLimited(c);
+        }
+        let res;
+        try {
+            res = await introspect(token);
+        }
+        catch (err) {
+            opts.logger?.error('auth service unreachable for introspection', { error: err });
+            return unavailable(c);
+        }
+        if (res.status !== 200) {
+            opts.logger?.error('connector token introspection failed', { meta_status: res.status });
+            return unavailable(c);
+        }
+        const data = (await res.json().catch(() => null));
+        // Only an explicit `active: false` means "not valid". Any other answer
+        // without `active: true` is a protocol fault: fail closed, loudly, and
+        // without caching, so a broken auth service cannot sign every user out.
+        if (data?.active === false)
+            return reject();
+        if (data?.active !== true || Array.isArray(data)) {
+            opts.logger?.error('connector introspection answer is malformed');
+            return unavailable(c);
+        }
+        if (data.resource !== opts.resource) {
+            // The auth service only answers `active` to the resource's own service
+            // account, so this is reachable only by the always-admitted agent
+            // identity in development. Not valid here either way.
+            opts.logger?.warn('connector token is for another resource', { resource: data.resource });
+            return reject();
+        }
+        const role = parseRole(data.role);
+        const expMs = typeof data.exp === 'number' ? data.exp * 1000 : NaN;
+        if (!role ||
+            !nonEmptyString(data.email) ||
+            !nonEmptyString(data.client_id) ||
+            !nonEmptyString(data.grant_id) ||
+            !Number.isFinite(expMs)) {
+            opts.logger?.error('connector introspection answer is malformed');
+            return unavailable(c);
+        }
+        if (expMs <= now())
+            return reject();
+        const user = {
+            type: 'connector',
+            email: data.email,
+            name: typeof data.name === 'string' ? data.name : undefined,
+            userId: typeof data.user_id === 'string' ? data.user_id : undefined,
+            role,
+            scopes: parseScopes(data.scope),
+            clientId: data.client_id,
+            grantId: data.grant_id,
+        };
+        cache.set(key, { expires: Math.min(now() + hitMs, expMs), user });
+        return admit(user);
+    });
+}

package/dist/s2s.d.ts

@@ -25,6 +25,7 @@ export declare class RateLimiter {
     private windows;
     constructor(perMinute: number);
     allow(key: string): boolean;
+    private evict;
 }
 export interface S2sOptions {
     /** This service's canonical URL, e.g. https://auth.apps.snewman.net — the

package/dist/s2s.js

@@ -47,6 +47,8 @@ export function grantAllows(grants, email, method, path) {
 // loops and mischief, not a precision tool (per-instance state only).
 export class RateLimiter {
     perMinute;
+    // Insertion order is window-start order (a restarted window is re-inserted),
+    // so the oldest window is always first.
     windows = new Map();
     constructor(perMinute) {
         this.perMinute = perMinute;
@@ -55,13 +57,31 @@ export class RateLimiter {
         const now = Date.now();
         const w = this.windows.get(key);
         if (!w || now - w.start >= 60_000) {
+            this.windows.delete(key);
+            this.evict(now);
             this.windows.set(key, { start: now, count: 1 });
-            return true;
+            return this.perMinute >= 1;
         }
         w.count++;
         return w.count <= this.perMinute;
     }
+    // Keys can be chosen by unauthenticated callers (a per-IP limiter on a
+    // public endpoint), so finished windows are dropped as new ones arrive and
+    // the map never exceeds RATE_LIMITER_MAX_KEYS: past that the oldest live
+    // window is forgotten, which only ever relaxes the limit for that key.
+    evict(now) {
+        for (const [key, w] of this.windows) {
+            if (now - w.start < 60_000 && this.windows.size < RATE_LIMITER_MAX_KEYS)
+                return;
+            this.windows.delete(key);
+        }
+    }
 }
+const RATE_LIMITER_MAX_KEYS = 10_000;
+/** The auth service's OAuth token families (access, refresh, authorization
+ *  code). They are opaque, never Google ID tokens, and are admitted only by
+ *  oauth-resource.ts's middleware on an app's connector route. */
+const CONNECTOR_TOKEN = /^pw(?:at|rt|ac)_/;
 /** `message` with every occurrence of `token` — and of each of its
  *  dot-separated segments of 8+ chars, since some verifier messages quote a
  *  single segment — replaced by `<token>`, then truncated. */
@@ -85,6 +105,12 @@ export async function resolveS2sCaller(opts, headers, method, path) {
         const m = headers.authorization?.match(/^Bearer (.+)$/i);
         if (!m)
             return { failure: { status: 401, error: 'missing bearer token' } };
+        if (CONNECTOR_TOKEN.test(m[1])) {
+            // A connector token on a route that takes service callers: refused here
+            // so it never reaches the verifier, whose errors quote the token.
+            opts.logger?.warn('connector token presented on a service route', { path });
+            return { failure: { status: 401, error: 'invalid token' } };
+        }
         try {
             const client = opts.verifyClient ?? defaultVerifyClient();
             const ticket = await client.verifyIdToken({ idToken: m[1], audience: opts.audience });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "3.26.0",
+  "version": "3.28.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,10 @@
       "types": "./dist/auth.d.ts",
       "default": "./dist/auth.js"
     },
+    "./oauth-resource": {
+      "types": "./dist/oauth-resource.d.ts",
+      "default": "./dist/oauth-resource.js"
+    },
     "./db": {
       "types": "./dist/db.d.ts",
       "default": "./dist/db.js"