Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBrain OAuth 2.1 Provider — implements MCP SDK's OAuthServerProvider.
*
* Backed by raw SQL (PGLite or Postgres), not the BrainEngine interface.
* OAuth is infrastructure, not brain operations.
*
* Supports:
* - Client registration (manual via CLI or Dynamic Client Registration)
* - Authorization code flow with PKCE (for ChatGPT, browser-based clients)
* - Client credentials flow (for machine-to-machine: Perplexity, Claude)
* - Token refresh with rotation
* - Token revocation
* - Legacy access_tokens fallback for backward compat
*/
import { OAuthGrants, type OAuthTransaction } from './oauth-grants.ts';
import { safeHexEqual } from './timing-safe.ts';
import { AsyncLocalStorage } from 'node:async_hooks';
import type { Response } from 'express';
import type {
OAuthClientInformationFull,
OAuthTokens,
OAuthTokenRevocationRequest,
} from '@modelcontextprotocol/sdk/shared/auth.js';
import type { OAuthServerProvider, AuthorizationParams } from '@modelcontextprotocol/sdk/server/auth/provider.js';
import type { OAuthRegisteredClientsStore } from '@modelcontextprotocol/sdk/server/auth/clients.js';
import type { AuthInfo as SdkAuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
import { InvalidTokenError, InvalidClientMetadataError, InvalidClientError, InvalidGrantError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
import { hashToken, generateToken, isUndefinedColumnError } from './utils.ts';
import {
hasScope,
assertAllowedScopes,
filterAllowedScopes,
parseScopeString,
InvalidScopeError,
ALLOWED_SCOPES_LIST,
dcrScopeViolation,
} from './scope.ts';
import type { AuthInfo as CoreAuthInfo } from './operations.ts';
import { TOKEN_TTL_MAX_SECONDS, authSourcesFromGrant, grantFromClient, grantFromRow, normalizeGrantBrain, intersectGrantedScopes, privatePagesAuth, type GrantPatch } from './grants/model.ts';
import { assertValidSlugPrefixes, pgArray } from './grants/encoding.ts';
import { rescopeOAuthClient, type RescopeClientOptions, type RescopeClientResult } from './grants/rescope.ts';
import { grantValidationContext, validateClientGrant, insertClientGrant, assertGrantPatch } from './grants/service.ts';
import { resolveTokenGrant, touchTokenLastUsed } from './grants/legacy-token.ts';
import { NO_SOURCES } from './source-id.ts';
/**
* A slug-prefix write binding is only meaningful if every entry actually
* constrains something. `''` (or whitespace) matches every slug under
* `startsWith`, so one unset variable in a provisioning template would turn
* a binding into a silent wildcard while still displaying as "fenced".
* Reject at every write surface: registration, rescope, admin API.
*/
export { assertValidSlugPrefixes } from './grants/encoding.ts';
import type { SqlQuery, SqlValue } from './sql-query.ts';
import { storedMinTrust } from './trust/tier.ts';
import { tokenMemberBinding } from './access/token-binding.ts';
import { withAttestRight } from './access/actor-model.ts';
export type { SqlQuery, SqlValue };
export interface AgentClientBindings {
boundTools?: string[];
boundSourceId?: string;
boundBrainId?: string;
boundSlugPrefixes?: string[];
boundMaxConcurrent?: number;
budgetUsdPerDay?: string | null;
delegatedSlugPrefixes?: string[] | null;
delegatedNamespace?: 'prefixes' | 'job';
allowedOperations?: string[] | null;
}
// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------
/**
* Allow-list of RFC 7591 §2 `token_endpoint_auth_method` values gbrain
* accepts at registration. Three values, chosen because the SDK's
* `mcpAuthRouter` advertises exactly these three in
* `token_endpoint_auth_methods_supported`:
*
* - `client_secret_post` — confidential client; secret in body (default)
* - `client_secret_basic` — confidential client; secret in Authorization header
* - `none` — public PKCE-only client (Claude Code, Cursor, ChatGPT custom connector)
*
* Three call sites enforce this set:
* 1. CLI `gbrain auth register-client` (src/commands/auth.ts)
* 2. Admin `POST /admin/api/register-client` (src/commands/serve-http.ts)
* 3. DCR `POST /register` (this file, GBrainClientsStore.registerClient)
*
* **Read-tolerant by design.** `getClient` returns whatever is stored
* verbatim — legacy rows with non-allowlist values (e.g. pre-v0.41.3
* direct UPDATEs) continue to function. The validator gates new writes
* ONLY; we don't break operators with hand-edited rows on upgrade.
*/
export type TokenEndpointAuthMethod = 'client_secret_post' | 'client_secret_basic' | 'none';
export const ALLOWED_TOKEN_ENDPOINT_AUTH_METHODS = new Set<TokenEndpointAuthMethod>([
'client_secret_post',
'client_secret_basic',
'none',
]);
export class InvalidTokenEndpointAuthMethodError extends Error {
readonly code = 'invalid_token_endpoint_auth_method';
constructor(value: unknown) {
super(
`Invalid token_endpoint_auth_method: ${JSON.stringify(value)}. ` +
`Expected one of: ${Array.from(ALLOWED_TOKEN_ENDPOINT_AUTH_METHODS).join(', ')}. ` +
`RFC 7591 §2 — see https://datatracker.ietf.org/doc/html/rfc7591#section-2.`,
);
this.name = 'InvalidTokenEndpointAuthMethodError';
}
}
/**
* Validate a token_endpoint_auth_method value at the registration boundary.
* Throws `InvalidTokenEndpointAuthMethodError` on rejection; returns the
* typed value on success. Returns `'client_secret_post'` for undefined input
* (RFC 7591 default).
*
* Apply at every registration entry point (CLI, admin endpoint, DCR). Do
* NOT apply on read — legacy oauth_clients rows with non-allowlist values
* must continue to function unchanged.
*/
export function validateTokenEndpointAuthMethod(value: unknown): TokenEndpointAuthMethod {
if (value === undefined || value === null || value === '') return 'client_secret_post';
if (typeof value !== 'string') throw new InvalidTokenEndpointAuthMethodError(value);
if (!ALLOWED_TOKEN_ENDPOINT_AUTH_METHODS.has(value as TokenEndpointAuthMethod)) {
throw new InvalidTokenEndpointAuthMethodError(value);
}
return value as TokenEndpointAuthMethod;
}
/**
* Re-throw non-OAuth registration errors as `InvalidClientMetadataError` so
* the MCP SDK register handler returns HTTP 400 `invalid_client_metadata`
* instead of a generic 500 `server_error`. Already-OAuth errors pass through.
*/
function asClientMetadataError(err: unknown): never {
if (err instanceof InvalidClientMetadataError) throw err;
// Duck-type OAuthError from the SDK (has .errorCode) without importing the
// base class — keeps the dependency surface stable across SDK versions.
if (err && typeof err === 'object' && 'errorCode' in err) throw err;
const message = err instanceof Error ? err.message : String(err);
console.warn(`[gbrain dcr] rejected registration: ${message}`);
throw new InvalidClientMetadataError(message);
}
/**
* Validate a redirect_uri for the DCR path.
*
* Allowed:
* - `https://` (production web clients)
* - loopback `http://` (127.0.0.1 / ::1 / localhost) — RFC 8252 §7.3
* - custom URI schemes (`warp://`, `myapp://`, …) — RFC 8252 §7.1 native apps
*
* Rejected:
* - non-loopback plaintext `http://` (auth-code exfiltration over the network)
* - unparseable strings
*
* Throws `InvalidClientMetadataError` (OAuthError → SDK maps to HTTP 400
* `invalid_client_metadata`) so DCR validation failures never surface as
* opaque 500s. CLI registration bypasses this gate (operator-trusted).
*/
export function validateRedirectUri(uri: string): void {
let parsed: URL;
try {
parsed = new URL(uri);
} catch {
throw new InvalidClientMetadataError(`Invalid redirect_uri: not a parseable URL: ${uri}`);
}
const isLoopback = parsed.hostname === 'localhost'
|| parsed.hostname === '127.0.0.1'
|| parsed.hostname === '[::1]'
|| parsed.hostname === '::1';
if (parsed.protocol === 'https:') return;
if (parsed.protocol === 'http:' && isLoopback) return;
// Native-app custom schemes (anything other than http/https). Require a
// non-empty scheme name so bare strings like "://x" can't sneak through,
// and reject browser-executable pseudo-schemes: a javascript:/data:/
// vbscript:/blob: "redirect" is script injection, not a native-app callback.
if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
const scheme = parsed.protocol.replace(/:$/, '');
const pseudoSchemes = new Set(['javascript', 'data', 'vbscript', 'blob']);
if (pseudoSchemes.has(scheme.toLowerCase())) {
throw new InvalidClientMetadataError(
`redirect_uri scheme '${scheme}:' is a browser pseudo-scheme, not a native-app scheme: ${uri}`,
);
}
if (scheme.length > 0) return;
}
throw new InvalidClientMetadataError(
`redirect_uri must use https://, a native-app custom scheme, or http:// loopback: ${uri}`,
);
}
/**
* Coerce an OAuth timestamp column (Unix epoch seconds, BIGINT) into a JS
* number, or undefined for SQL NULL.
*
* Why this exists: postgres.js with `prepare: false` (the auto-detected setting
* on Supabase PgBouncer / port 6543; see src/core/db.ts:resolvePrepare) returns
* BIGINT columns as strings. Two surfaces break on that: (1) the MCP SDK's
* bearerAuth middleware checks `typeof authInfo.expiresAt === 'number'` and
* rejects strings; (2) RFC 7591 §3.2.1 requires `client_id_issued_at` and
* `client_secret_expires_at` to be JSON numbers in DCR responses, not strings.
*
* Throws on non-finite (NaN/Infinity) so corrupt rows fail loud at the boundary
* instead of letting `expiresAt: NaN` flow through to the SDK as a fake-valid
* token. Returns undefined for SQL NULL so callers decide NULL semantics
* explicitly. For OAuth, the comparison sites treat NULL as "expired"
* (fail-closed); the DCR response sites preserve undefined per RFC 7591
* (the `client_secret_expires_at` field is optional, undefined means
* "did not expire").
*/
export function coerceTimestamp(value: unknown): number | undefined {
if (value === null || value === undefined) return undefined;
const n = Number(value);
if (!Number.isFinite(n)) {
throw new Error(`coerceTimestamp: non-finite timestamp value ${JSON.stringify(value)}`);
}
return n;
}
interface GBrainOAuthProviderOptions {
sql: SqlQuery;
/** Required for grant issuance/rotation/revocation; registration and verification need only sql. */
transaction?: OAuthTransaction;
/** Default token TTL in seconds (default: 3600 = 1 hour) */
tokenTtl?: number;
/** Default refresh token TTL in seconds (default: 30 days) */
refreshTtl?: number;
/**
* Disable Dynamic Client Registration (RFC 7591) while keeping the rest of
* the OAuth surface intact. When true, `clientsStore.registerClient` is not
* surfaced to the SDK router, so POST `/register` returns 404 even though
* the underlying provider can still register clients programmatically via
* `registerClientManual`. Replaces the previous monkey-patching pattern in
* serve-http.ts (cleanup, not a security fix — DCR was never reachable
* before mcpAuthRouter ran).
*/
dcrDisabled?: boolean;
/** #5222: the canonical /mcp resource from the configured public URL; grants canonicalize `resource` against it. */
resourceUrl?: URL;
/**
* Allow the consent-bypassing `client_credentials` grant on the unauthenticated
* Dynamic Client Registration path. Default false (#1353): a self-registered
* DCR client defaults to `authorization_code` (owner approval on /authorize),
* and an explicit `client_credentials` request is rejected. Operators who opt
* in via `--enable-dcr-insecure` get anonymous READ-ONLY machine clients: the
* DCR scope ceiling (`dcrScopeViolation` in scope.ts) caps them at `read`.
* Manual CLI / admin registration is unaffected (operator-trusted).
*/
allowClientCredentialsDcr?: boolean;
/**
* #2179: lower bound (seconds) for DCR-requested per-client token TTLs.
* Requests below it clamp up. Default DEFAULT_DCR_TTL_MIN_SECONDS (300).
*/
dcrTtlMinSeconds?: number;
/**
* #2179: upper bound (seconds) for DCR-requested per-client token TTLs.
* Requests above it clamp down. Unset defaults FAIL-CLOSED to
* max(tokenTtl, dcrTtlMinSeconds): an anonymous DCR registrant can never
* elect a longer-lived token than the operator's own --token-ttl unless
* the admin explicitly widened the window.
*/
dcrTtlMaxSeconds?: number;
}
// ---------------------------------------------------------------------------
// DCR token TTL (#2179)
// ---------------------------------------------------------------------------
/**
* Default lower clamp bound for DCR-requested token TTLs (#2179). Admins
* override via the `oauth.dcr_ttl_min_seconds` / `oauth.dcr_ttl_max_seconds`
* config keys, read once by `gbrain serve --http` at startup. There is
* deliberately NO fixed default max: an unset max derives fail-closed from
* the operator's --token-ttl (`max(tokenTtl, min)`), so a self-registering
* client can never out-live the server default without explicit admin opt-in.
*/
export const DEFAULT_DCR_TTL_MIN_SECONDS = 300; // 5 minutes
/**
* Clamp a DCR-requested token TTL into the admin-configured [min, max]
* window. Bounds are REQUIRED — callers resolve them (fail-closed) first.
* Never rejects (#2179): out-of-range values clamp to the nearest bound.
* Non-integer requests floor; an inverted window collapses to the min bound.
*/
export function clampDcrTokenTtl(
requested: number,
min: number,
max: number,
): number {
const lo = Math.max(1, Math.floor(min));
const hi = Math.max(lo, Math.floor(max));
return Math.min(hi, Math.max(lo, Math.floor(requested)));
}
/**
* Request-scoped carrier for the `token_ttl_seconds` DCR extension field
* (#2179). The MCP SDK's /register handler validates the request body against
* a strict schema and STRIPS unknown members before they reach
* `clientsStore.registerClient`, so serve-http's /register middleware parses
* the raw body and runs the SDK chain inside this AsyncLocalStorage context;
* the store reads it back out at registration time. No context (CLI, admin
* API, programmatic registration) means "no TTL request" — default behavior.
*/
export const dcrRegistrationContext = new AsyncLocalStorage<{ tokenTtlSeconds?: number }>();
// ---------------------------------------------------------------------------
// Clients Store
// ---------------------------------------------------------------------------
class GBrainClientsStore implements OAuthRegisteredClientsStore {
// #2179: DCR TTL bounds are required — the provider resolves fail-closed
// defaults (max bounded by tokenTtl); no permissive fallback lives here.
constructor(
private sql: SqlQuery,
private allowClientCredentialsDcr: boolean,
private dcrTtlMin: number,
private dcrTtlMax: number,
) {}
async getClient(clientId: string): Promise<OAuthClientInformationFull | undefined> {
const rows = await this.sql`
SELECT client_id, client_secret_hash, client_name, redirect_uris,
grant_types, scope, token_endpoint_auth_method,
client_id_issued_at, client_secret_expires_at
FROM oauth_clients WHERE client_id = ${clientId}
AND (to_jsonb(oauth_clients)->>'deleted_at') IS NULL
`;
if (rows.length === 0) return undefined;
const r = rows[0];
// v0.34.1 (#909): public clients (token_endpoint_auth_method='none')
// have client_secret_hash = NULL. Normalize SQL NULL to JS undefined
// so SDK middleware that checks `client.client_secret === undefined`
// (not `=== null`) correctly identifies the client as public and
// skips the secret-comparison branch on /token.
const rawSecret = r.client_secret_hash;
return {
client_id: r.client_id as string,
client_secret: rawSecret == null ? undefined : (rawSecret as string),
client_name: r.client_name as string,
redirect_uris: (r.redirect_uris as string[]) || [],
grant_types: (r.grant_types as string[]) || ['client_credentials'],
scope: r.scope as string | undefined,
token_endpoint_auth_method: r.token_endpoint_auth_method as string | undefined,
client_id_issued_at: coerceTimestamp(r.client_id_issued_at),
client_secret_expires_at: coerceTimestamp(r.client_secret_expires_at),
};
}
async registerClient(
client: Omit<OAuthClientInformationFull, 'client_id' | 'client_id_issued_at'>,
): Promise<OAuthClientInformationFull> {
// DCR is unauthenticated network input. Every validation failure here
// MUST become InvalidClientMetadataError (HTTP 400) — plain Errors are
// converted to opaque 500 server_error by the MCP SDK register handler,
// which is what broke Warp/rmcp clients against gbrain.
let authMethod: TokenEndpointAuthMethod;
let registeredScope: string;
let grantTypes: string[];
try {
// redirect_uri: https / loopback http / native custom schemes only.
// Non-loopback plaintext http is still rejected (auth-code exfil).
// CLI registrations bypass this gate (operator-trusted).
for (const uri of client.redirect_uris || []) {
validateRedirectUri(String(uri));
}
// v0.42 (#1353): the DCR path is the unauthenticated network entry point.
// `client_credentials` skips /authorize owner approval entirely, so a
// self-registered DCR client must NOT get it unless the operator opted in
// via `--enable-dcr-insecure`. Gated BEFORE the scope ceiling: when the
// grant is not on offer at all the reply must say so, not "limited to
// read" (which implies it is available narrower). CLI/admin paths bypass this.
grantTypes = client.grant_types?.length ? client.grant_types : ['authorization_code'];
if (!this.allowClientCredentialsDcr && grantTypes.includes('client_credentials')) {
throw new InvalidClientMetadataError(
'client_credentials grant is not permitted via dynamic client registration; ' +
'restart the server with --enable-dcr-insecure to allow it, or register the ' +
'client via the gbrain CLI / admin API.',
);
}
// Scope policy for DCR: (1) ceiling — anonymous registration may hold
// at most `read write` (`read` for an allowed client_credentials
// registration); privileged scopes are REJECTED as 400, never silently
// dropped (scope.ts). The ceiling depends on the grant default above.
// (2) filter unknowns (RFC 7591 value replacement) instead of
// hard-rejecting: OIDC-flavored stacks append `offline_access` /
// `openid`. Empty-after-filter with a non-empty request is a hard 400.
const requestedScopes = parseScopeString(client.scope);
const ceilingViolation = dcrScopeViolation(requestedScopes, grantTypes);
if (ceilingViolation) throw new InvalidClientMetadataError(ceilingViolation);
const { allowed, dropped } = filterAllowedScopes(requestedScopes);
if (dropped.length > 0) {
console.warn(
`[gbrain dcr] dropping unknown scopes from registration ` +
`(client_name=${client.client_name || 'unnamed'}): ${dropped.join(' ')}`,
);
}
if (requestedScopes.length > 0 && allowed.length === 0) {
throw new InvalidClientMetadataError(
`No recognized scopes in request (${requestedScopes.join(' ')}). ` +
`Allowed: ${ALLOWED_SCOPES_LIST.join(', ')}.`,
);
}
registeredScope = allowed.join(' ');
// v0.41.3 (T5): validate token_endpoint_auth_method on the DCR path so
// `--enable-dcr` is not the looser entry point. CLI and admin paths gate
// through the same `validateTokenEndpointAuthMethod` helper — all three
// registration entry points share one allow-list.
authMethod = validateTokenEndpointAuthMethod(client.token_endpoint_auth_method);
} catch (err) {
asClientMetadataError(err);
}
const clientId = generateToken('gbrain_cl_');
// v0.34.1 (#909): RFC 7591 §2 — clients that authenticate at the token
// endpoint via PKCE alone declare `token_endpoint_auth_method: "none"`.
// For those clients the authorization server MUST NOT issue a client
// secret. Pre-fix, unconditional secret generation made the MCP SDK's
// clientAuth middleware check `client.client_secret` on every request,
// rejecting valid public-client (Claude Code, Cursor) flows.
//
// We persist secret_hash = NULL for public clients so `getClient` and
// the SDK's clientAuth path can detect them via `client_secret_hash IS
// NULL` and skip the secret comparison. Confidential clients (default
// `client_secret_post` and explicit `client_secret_basic`) still mint
// a secret as before.
const isPublicClient = authMethod === 'none';
const clientSecret = isPublicClient ? undefined : generateToken('gbrain_cs_');
const secretHash = clientSecret ? hashToken(clientSecret) : null;
const now = Math.floor(Date.now() / 1000);
// v0.34.1 (#861, D2 + D13 + #876): DCR clients get source_id='default'
// (matches legacy fallback) and federated_read=['default'] (read scope
// == write scope). Operators who need narrower / wider scope rescope
// via the CLI later. Pre-v60/v61 brain falls through to the legacy
// projection (no source_id / federated_read column yet).
// #6202: registered_via='dcr' marks the client as self-registered, so its
// owner picks its source at the first consent (OAuthGrants.begin). A brain
// without the column yet (new server before the migration) falls through to
// the unmarked ladder: the client keeps today's read-only consent.
const insertUnmarked = async (): Promise<void> => {
try {
await this.sql`
INSERT INTO oauth_clients (client_id, client_secret_hash, client_name, redirect_uris,
grant_types, scope, token_endpoint_auth_method,
client_id_issued_at, source_id, federated_read)
VALUES (${clientId}, ${secretHash}, ${client.client_name || 'unnamed'},
${pgArray((client.redirect_uris || []).map(String))},
${pgArray(grantTypes)},
${registeredScope}, ${authMethod},
${now}, ${'default'}, ${pgArray(['default'])})
`;
} catch (err) {
if (isUndefinedColumnError(err, 'federated_read')) {
try {
await this.sql`
INSERT INTO oauth_clients (client_id, client_secret_hash, client_name, redirect_uris,
grant_types, scope, token_endpoint_auth_method,
client_id_issued_at, source_id)
VALUES (${clientId}, ${secretHash}, ${client.client_name || 'unnamed'},
${pgArray((client.redirect_uris || []).map(String))},
${pgArray(grantTypes)},
${registeredScope}, ${authMethod},
${now}, ${'default'})
`;
} catch (err2) {
if (isUndefinedColumnError(err2, 'source_id')) {
await this.sql`
INSERT INTO oauth_clients (client_id, client_secret_hash, client_name, redirect_uris,
grant_types, scope, token_endpoint_auth_method,
client_id_issued_at)
VALUES (${clientId}, ${secretHash}, ${client.client_name || 'unnamed'},
${pgArray((client.redirect_uris || []).map(String))},
${pgArray(grantTypes)},
${registeredScope}, ${authMethod},
${now})
`;
} else {
throw err2;
}
}
} else if (isUndefinedColumnError(err, 'source_id')) {
await this.sql`
INSERT INTO oauth_clients (client_id, client_secret_hash, client_name, redirect_uris,
grant_types, scope, token_endpoint_auth_method,
client_id_issued_at)
VALUES (${clientId}, ${secretHash}, ${client.client_name || 'unnamed'},
${pgArray((client.redirect_uris || []).map(String))},
${pgArray(grantTypes)},
${registeredScope}, ${authMethod},
${now})
`;
} else {
throw err;
}
}
};
try {
await this.sql`
INSERT INTO oauth_clients (client_id, client_secret_hash, client_name, redirect_uris,
grant_types, scope, token_endpoint_auth_method,
client_id_issued_at, source_id, federated_read, registered_via)
VALUES (${clientId}, ${secretHash}, ${client.client_name || 'unnamed'},
${pgArray((client.redirect_uris || []).map(String))},
${pgArray(grantTypes)},
${registeredScope}, ${authMethod},
${now}, ${'default'}, ${pgArray(['default'])}, ${'dcr'})
`;
} catch (err) {
if (!isUndefinedColumnError(err, 'registered_via')) throw err;
await insertUnmarked();
}
// #2179: optional `token_ttl_seconds` hint from the DCR request body,
// carried via dcrRegistrationContext (the SDK strips unknown body
// members). Fail-safe posture: absent or malformed → server default TTL;
// out-of-range → clamped into [dcrTtlMin, dcrTtlMax]; never rejected.
// Persist into oauth_clients.token_ttl (the same per-client override the
// admin API writes) and echo the EFFECTIVE value in the registration
// response so the caller can show the user what it actually got.
let effectiveTtl: number | undefined;
const requestedTtl = dcrRegistrationContext.getStore()?.tokenTtlSeconds;
if (typeof requestedTtl === 'number' && Number.isFinite(requestedTtl)) {
const clamped = clampDcrTokenTtl(requestedTtl, this.dcrTtlMin, this.dcrTtlMax);
try {
await this.sql`UPDATE oauth_clients SET token_ttl = ${clamped} WHERE client_id = ${clientId}`;
effectiveTtl = clamped;
} catch (e) {
// Pre-migration schema without the token_ttl column: keep the
// registration, but do NOT echo a TTL that wasn't persisted.
if (!isUndefinedColumnError(e, 'token_ttl')) throw e;
}
}
// Public clients: omit `client_secret` entirely from the response so
// the wire payload matches RFC 7591 §3.2.1 ("if the client is a
// public client, the authorization server MUST NOT issue a client
// secret"). Confidential clients return the freshly-generated secret
// exactly once — same shape as before.
// Override scope with the filtered grant so the client sees what was
// actually registered (RFC 7591 §3.2.1 returned metadata).
const response: OAuthClientInformationFull = {
...client,
scope: registeredScope,
client_id: clientId,
client_id_issued_at: now,
};
if (clientSecret) response.client_secret = clientSecret;
if (effectiveTtl !== undefined) {
(response as Record<string, unknown>).token_ttl_seconds = effectiveTtl;
}
return response;
}
}
// ---------------------------------------------------------------------------
// OAuth Provider
// ---------------------------------------------------------------------------
export class GBrainOAuthProvider implements OAuthServerProvider {
// The SDK otherwise consumes the verifier and calls our exchange with
// undefined. This provider validates S256 itself before consuming the code,
// for both the SDK's public-client route and our confidential-client route.
readonly skipLocalPkceValidation = true;
private sql: SqlQuery;
private transaction?: OAuthTransaction;
private _clientsStore: GBrainClientsStore;
private readonly dcrDisabled: boolean;
private tokenTtl: number;
private refreshTtl: number;
readonly grants: OAuthGrants;
constructor(options: GBrainOAuthProviderOptions) {
this.sql = options.sql;
this.transaction = options.transaction;
this.dcrDisabled = options.dcrDisabled === true;
this.tokenTtl = options.tokenTtl || 3600;
this.refreshTtl = options.refreshTtl || 30 * 24 * 3600;
this.grants = new OAuthGrants({ sql: this.sql, transaction: options.transaction, tokenTtl: this.tokenTtl, refreshTtl: this.refreshTtl, resourceUrl: options.resourceUrl });
// #2179 fail-closed: an unset DCR max is bounded by the operator's own
// token TTL — never a fixed permissive ceiling — so a self-registering
// client cannot elect a longer-lived token than the server default
// unless the admin explicitly configured a wider window.
const dcrTtlMin = Math.min(options.dcrTtlMinSeconds ?? DEFAULT_DCR_TTL_MIN_SECONDS, TOKEN_TTL_MAX_SECONDS);
const dcrTtlMax = Math.min(options.dcrTtlMaxSeconds ?? Math.max(this.tokenTtl, dcrTtlMin), TOKEN_TTL_MAX_SECONDS);
this._clientsStore = new GBrainClientsStore(
this.sql,
options.allowClientCredentialsDcr === true,
dcrTtlMin,
dcrTtlMax,
);
}
get clientsStore(): OAuthRegisteredClientsStore {
if (this.dcrDisabled) {
// Surface getClient only — without registerClient the SDK's mcpAuthRouter
// does not wire up the /register DCR endpoint. Replaces the prior
// monkey-patch in serve-http.ts; the outcome is identical (DCR off-by-
// default), but the API expresses intent on the constructor instead of
// requiring callers to mutate `_clientsStore` after construction.
return {
getClient: this._clientsStore.getClient.bind(this._clientsStore),
} as OAuthRegisteredClientsStore;
}
return this._clientsStore;
}
// -------------------------------------------------------------------------
// Authorization Code Flow
// -------------------------------------------------------------------------
async authorize(
client: OAuthClientInformationFull,
params: AuthorizationParams,
res: Response,
): Promise<void> {
const id = await this.grants.begin(client.client_id, params);
res.redirect(`/admin/?oauth_request=${id}#oauth-consent`);
}
async challengeForAuthorizationCode(
client: OAuthClientInformationFull,
authorizationCode: string,
): Promise<string> {
const codeHash = hashToken(authorizationCode);
// F1 hardening: bind client_id atomically so a wrong client cannot read
// another client's PKCE challenge. Pre-fix the SELECT didn't filter on
// client_id at all.
const rows = await this.sql`
SELECT code_challenge FROM oauth_codes
JOIN oauth_clients ON oauth_clients.client_id = oauth_codes.client_id
WHERE (to_jsonb(oauth_clients)->>'deleted_at') IS NULL
AND code_hash = ${codeHash}
AND oauth_codes.client_id = ${client.client_id}
AND oauth_codes.expires_at > ${Math.floor(Date.now() / 1000)}
`;
if (rows.length === 0) throw new InvalidGrantError('Authorization code not found or expired');
return rows[0].code_challenge as string;
}
async exchangeAuthorizationCode(
client: OAuthClientInformationFull,
authorizationCode: string,
codeVerifier?: string,
redirectUri?: string,
resource?: URL,
): Promise<OAuthTokens> {
return this.grants.exchangeCode(client.client_id, authorizationCode, codeVerifier, redirectUri, resource, client.client_secret);
}
// -------------------------------------------------------------------------
// Refresh Token
// -------------------------------------------------------------------------
async exchangeRefreshToken(
client: OAuthClientInformationFull,
refreshToken: string,
scopes?: string[],
resource?: URL,
): Promise<OAuthTokens> {
return this.grants.refresh(client.client_id, refreshToken, scopes, resource, client.client_secret);
}
// -------------------------------------------------------------------------
// Token Verification
// -------------------------------------------------------------------------
async verifyAccessToken(token: string): Promise<SdkAuthInfo> {
const tokenHash = hashToken(token);
const now = Math.floor(Date.now() / 1000);
// Try OAuth tokens first. JOIN oauth_clients in the same query so
// verifyAccessToken returns client_name AND source_id in AuthInfo —
// eliminates the separate per-request lookup at serve-http.ts that
// was the N+1 hot path (see PR #586 review D14=B; v0.34.1 #861 D2
// adds the source_id thread on the same JOIN).
//
// v0.34.1 (#861): the JOIN guards on a c.source_id column that
// migration v60 adds. Pre-v60 brains throw a "column does not exist"
// error here — caught at the boundary via isUndefinedColumnError so
// unmigrated brains degrade to "no source scope" rather than refusing
// every token verification.
let oauthRows: Record<string, unknown>[];
try {
oauthRows = await this.sql`
SELECT t.client_id, t.scopes, t.expires_at, t.resource, c.client_name, c.scope AS current_scopes, to_jsonb(t)->>'grant_type' AS token_grant,
(to_jsonb(c) - 'client_secret_hash') AS current_grant,
EXISTS(SELECT 1 FROM sources s WHERE s.id = to_jsonb(c)->>'source_id'
AND NOT COALESCE((to_jsonb(s)->>'archived')::boolean, false)) AS source_active,
ARRAY(SELECT s.id FROM sources s WHERE NOT COALESCE((to_jsonb(s)->>'archived')::boolean, false)
AND s.id IN (SELECT jsonb_array_elements_text(COALESCE(NULLIF(to_jsonb(c)->'federated_read', 'null'::jsonb), jsonb_build_array(to_jsonb(c)->>'source_id'))))) AS active_read_sources,
c.source_id, c.federated_read, c.bound_slug_prefixes,
c.surface, c.surface_set_by
FROM oauth_tokens t
LEFT JOIN oauth_clients c ON c.client_id = t.client_id
WHERE t.token_hash = ${tokenHash} AND t.token_type = 'access'
AND c.client_id IS NOT NULL AND (to_jsonb(c)->>'deleted_at') IS NULL
`;
} catch (err) {
// Degrade ladder for brains that haven't run apply-migrations yet:
// surface/surface_set_by (v127) → bound_slug_prefixes (v85) →
// federated_read (v61) → source_id (v60) → pre-v0.34 base projection.
// Auth must keep working the whole way down.
//
// `isUndefinedColumnError(err, name)` canNOT actually tell us WHICH
// column was missing — with SQLSTATE 42703 present it returns true for
// any undefined column, and the name is only consulted in the message
// fallback. So the ladder must not branch on the reported name; it
// walks every narrower projection in turn, each guarded, and only
// rethrows once the narrowest one still fails. (Branching on the name
// is what made the first cut of this hard-fail every token
// verification on a pre-v61 brain.)
// Any of the optional columns may be the missing one, and on the
// message-fallback path (drivers that don't surface SQLSTATE) the name
// is what identifies it — so probe all five at every rung (ENG-9:
// surface + surface_set_by ship in one migration and go missing
// together, so BOTH names are probed).
const missingOAuthColumn = (e: unknown): boolean =>
isUndefinedColumnError(e, 'surface') ||
isUndefinedColumnError(e, 'surface_set_by') ||
isUndefinedColumnError(e, 'bound_slug_prefixes') ||
isUndefinedColumnError(e, 'federated_read') ||
isUndefinedColumnError(e, 'source_id');
if (!missingOAuthColumn(err)) throw err;
try {
// v127 missing: drop the surface columns first, keep the fence
// column (WP4 amendment 17 — the NEW top rung). Surface degrade is
// fail-OPEN by design: the serve-http ceiling still bounds every
// request, so a missing per-client surface only means "server
// surface applies", never a widened catalog.
oauthRows = await this.sql`
SELECT t.client_id, t.scopes, t.expires_at, t.resource, c.client_name, c.scope AS current_scopes,
(to_jsonb(c) - 'client_secret_hash') AS current_grant,
EXISTS(SELECT 1 FROM sources s WHERE s.id = to_jsonb(c)->>'source_id'
AND NOT COALESCE((to_jsonb(s)->>'archived')::boolean, false)) AS source_active,
ARRAY(SELECT s.id FROM sources s WHERE NOT COALESCE((to_jsonb(s)->>'archived')::boolean, false)
AND s.id IN (SELECT jsonb_array_elements_text(COALESCE(NULLIF(to_jsonb(c)->'federated_read', 'null'::jsonb), jsonb_build_array(to_jsonb(c)->>'source_id'))))) AS active_read_sources,
c.source_id, c.federated_read, c.bound_slug_prefixes
FROM oauth_tokens t
LEFT JOIN oauth_clients c ON c.client_id = t.client_id
WHERE t.token_hash = ${tokenHash} AND t.token_type = 'access'
AND c.client_id IS NOT NULL AND (to_jsonb(c)->>'deleted_at') IS NULL
`;
} catch (errS) {
if (!missingOAuthColumn(errS)) throw errS;
try {
// v85 missing: keep source_id + federated_read, drop the fence column.
oauthRows = await this.sql`
SELECT t.client_id, t.scopes, t.expires_at, t.resource, c.client_name, c.scope AS current_scopes,
(to_jsonb(c) - 'client_secret_hash') AS current_grant,
EXISTS(SELECT 1 FROM sources s WHERE s.id = to_jsonb(c)->>'source_id'
AND NOT COALESCE((to_jsonb(s)->>'archived')::boolean, false)) AS source_active,
ARRAY(SELECT s.id FROM sources s WHERE NOT COALESCE((to_jsonb(s)->>'archived')::boolean, false)
AND s.id IN (SELECT jsonb_array_elements_text(COALESCE(NULLIF(to_jsonb(c)->'federated_read', 'null'::jsonb), jsonb_build_array(to_jsonb(c)->>'source_id'))))) AS active_read_sources,
c.source_id, c.federated_read
FROM oauth_tokens t
LEFT JOIN oauth_clients c ON c.client_id = t.client_id
WHERE t.token_hash = ${tokenHash} AND t.token_type = 'access'
AND c.client_id IS NOT NULL AND (to_jsonb(c)->>'deleted_at') IS NULL
`;
} catch (err2) {
if (!missingOAuthColumn(err2)) throw err2;
try {
// v61 missing: source_id only.
oauthRows = await this.sql`
SELECT t.client_id, t.scopes, t.expires_at, t.resource, c.client_name, c.scope AS current_scopes,
(to_jsonb(c) - 'client_secret_hash') AS current_grant,
EXISTS(SELECT 1 FROM sources s WHERE s.id = to_jsonb(c)->>'source_id'
AND NOT COALESCE((to_jsonb(s)->>'archived')::boolean, false)) AS source_active,
ARRAY(SELECT s.id FROM sources s WHERE NOT COALESCE((to_jsonb(s)->>'archived')::boolean, false)
AND s.id IN (SELECT jsonb_array_elements_text(COALESCE(NULLIF(to_jsonb(c)->'federated_read', 'null'::jsonb), jsonb_build_array(to_jsonb(c)->>'source_id'))))) AS active_read_sources, c.source_id
FROM oauth_tokens t
LEFT JOIN oauth_clients c ON c.client_id = t.client_id
WHERE t.token_hash = ${tokenHash} AND t.token_type = 'access'
AND c.client_id IS NOT NULL AND (to_jsonb(c)->>'deleted_at') IS NULL
`;
} catch (err3) {
if (!missingOAuthColumn(err3)) throw err3;
// Truly pre-v60: pre-v0.34 projection.
oauthRows = await this.sql`
SELECT t.client_id, t.scopes, t.expires_at, t.resource, c.client_name, c.scope AS current_scopes,
(to_jsonb(c) - 'client_secret_hash') AS current_grant,
EXISTS(SELECT 1 FROM sources s WHERE s.id = to_jsonb(c)->>'source_id'
AND NOT COALESCE((to_jsonb(s)->>'archived')::boolean, false)) AS source_active,
ARRAY(SELECT s.id FROM sources s WHERE NOT COALESCE((to_jsonb(s)->>'archived')::boolean, false)
AND s.id IN (SELECT jsonb_array_elements_text(COALESCE(NULLIF(to_jsonb(c)->'federated_read', 'null'::jsonb), jsonb_build_array(to_jsonb(c)->>'source_id'))))) AS active_read_sources
FROM oauth_tokens t
LEFT JOIN oauth_clients c ON c.client_id = t.client_id
WHERE t.token_hash = ${tokenHash} AND t.token_type = 'access'
AND c.client_id IS NOT NULL AND (to_jsonb(c)->>'deleted_at') IS NULL
`;
}
}
}
}
if (oauthRows.length > 0) {
const row = oauthRows[0];
const currentGrant = row.current_grant && typeof row.current_grant === 'object' ? row.current_grant as Record<string, unknown> : {};
for (const field of ['allowed_operations', 'grant_revision', 'grant_profile', 'grant_repair_reasons', 'bound_tools', 'bound_source_id', 'bound_brain_id', 'delegated_slug_prefixes', 'delegated_namespace', 'bound_max_concurrent', 'budget_usd_per_day']) row[field] = currentGrant[field];
row.client_deleted_at = currentGrant.deleted_at;
row.grant_projection_present = 'allowed_operations' in currentGrant;
if (row.client_deleted_at != null || row.current_scopes == null) throw new InvalidTokenError('Client revoked or missing');
const issuedScopes = Array.isArray(row.scopes) ? row.scopes as string[] : [];
const effectiveScopes = intersectGrantedScopes(issuedScopes, parseScopeString(String(row.current_scopes)));
const grantProjectionDegraded = row.grant_profile != null && (row.grant_projection_present !== true || !Array.isArray(row.allowed_operations));
if (grantProjectionDegraded) throw new InvalidTokenError('Client grant schema incomplete; run gbrain apply-migrations --yes');
// NULL expires_at is treated as expired (fail-closed). Schema permits NULL,
// and the SDK's bearerAuth requires `typeof expiresAt === 'number'` — we
// throw here rather than return an undefined-bearing AuthInfo.
const expiresAt = coerceTimestamp(row.expires_at);
if (expiresAt === undefined || expiresAt < now) {
throw new InvalidTokenError('Token expired');
}
// v0.34.1 (#876): federated_read normalization. SELECT returns
// either a JS array (Postgres / PGLite text[] driver mapping) or
// undefined when the legacy projection ran (pre-v61 brain). Empty
// array vs undefined matters: empty array = explicit no-federated-
// read; undefined = column missing on this brain.
const federatedRaw = row.federated_read;
const rowSourceId = (row.source_id as string | null) ?? undefined;
let allowedSources = Array.isArray(federatedRaw)
? (federatedRaw as string[])
: undefined;
// Degraded-projection safety: `resolveRequestedScope` only authorizes an
// explicitly requested `source_id` when `allowedSources` is a NON-EMPTY
// array — with it undefined, a remote caller naming any source is
// accepted. On a brain missing `federated_read` the ladder above returns
// exactly that undefined, so a client scoped to one source could read
// every other source by passing `source_id`. Synthesize the client's own
// source as its grant so the authorization check stays armed. (Legacy
// `access_tokens` keep their historical scope handling below — this only
// covers the OAuth rows whose column we just dropped.)
if (allowedSources === undefined && rowSourceId !== undefined) {
allowedSources = [rowSourceId];
}
// Grant membership is live: archiving a previously granted source must
// not leave its old snapshot readable. A wholly inactive grant exposes
// no operations; authenticated capability metadata can explain why.
if (rowSourceId !== undefined && row.source_active === false) effectiveScopes.length = 0;
if (allowedSources?.length && Array.isArray(row.active_read_sources)) {
allowedSources = allowedSources.filter(id => (row.active_read_sources as string[]).includes(id));
if (allowedSources.length === 0) effectiveScopes.length = 0;
}
// v0.42.72.0: slug-prefix write binding. Array (even empty — the
// fence treats [] as deny-all, matching submit_agent's fail-closed
// posture) when the client carries a binding; undefined when the
// column is NULL, the projection degraded, or the brain predates
// the column.
const boundRaw = row.bound_slug_prefixes;
const boundSlugPrefixes = Array.isArray(boundRaw)
? (boundRaw as string[])
: undefined;
// Fail CLOSED on the fence axis. If the projection degraded, we do not
// know whether this client carries a binding, and "column absent" is
// indistinguishable from "no binding" downstream. On a genuinely
// pre-v85 brain no binding can exist and this is harmless; the case
// that matters is a partially broken schema (interrupted migration,
// restored dump missing one column) where bindings DO exist and every
// bound client would otherwise be silently unfenced.
const fenceProjectionDegraded = !('bound_slug_prefixes' in row);
// WP4 (D2): per-client tool surface. Raw TEXT threaded as-is — the
// value space is OPEN (amendment 18; future tiers write tier names into
// this column), so parsing/warning happens at the serve-http resolution
// site, not here. Undefined when the column is NULL, the projection
// degraded (v127 rung), or the brain predates v127. Surface degrade is
// fail-open by design: the server ceiling still bounds every request.
const rowSurface = typeof row.surface === 'string' ? row.surface : undefined;
const rowSurfaceSetBy = typeof row.surface_set_by === 'string' ? row.surface_set_by : undefined;
// The explicit no-source grant: every read and write refuses
// (NO_SOURCES, the same sentinel a `--sources none` token carries).
const sourcesNone = currentGrant.source_grant === 'none';
const clientHolders = Array.isArray(currentGrant.takes_holders)
? (currentGrant.takes_holders as unknown[]).filter((h): h is string => typeof h === 'string') : undefined;
return {
token,
clientId: row.client_id as string,
principal: { kind: 'oauth_client', id: row.client_id as string },
...withAttestRight(await tokenMemberBinding(this.sql, currentGrant, currentGrant.client_id_issued_at), currentGrant, row.token_grant),
clientName: (row.client_name as string | null) ?? undefined,
scopes: effectiveScopes,
issuedScopes,
sourceActive: rowSourceId === undefined ? undefined : row.source_active === true,
allowedOperations: Array.isArray(row.allowed_operations) ? row.allowed_operations as string[] : null,
grantRevision: Number(row.grant_revision ?? 0),
grantProfile: typeof row.grant_profile === 'string' ? row.grant_profile : null,
grantRepairReasons: Array.isArray(row.grant_repair_reasons) ? row.grant_repair_reasons as string[] : [],
tokenTtlSeconds: currentGrant.token_ttl == null ? null : Number(currentGrant.token_ttl),
boundTools: Array.isArray(row.bound_tools) ? row.bound_tools as string[] : null,
boundSourceId: typeof row.bound_source_id === 'string' ? row.bound_source_id : null,
boundBrainId: typeof row.bound_brain_id === 'string' ? row.bound_brain_id : null,
delegatedSlugPrefixes: Array.isArray(row.delegated_slug_prefixes) ? row.delegated_slug_prefixes as string[] : null,
delegatedNamespace: row.delegated_namespace === 'job' ? 'job' : 'prefixes',
boundMaxConcurrent: Number(row.bound_max_concurrent ?? 1),
budgetUsdPerDay: row.budget_usd_per_day == null ? null : String(row.budget_usd_per_day),
expiresAt,
resource: row.resource ? new URL(row.resource as string) : undefined,
// v0.34.1 (#861, D2): source-isolation scope from oauth_clients.
// Undefined when the row predates v60 or when the brain itself
// predates v60 (fell through to the legacy projection above).
sourceId: sourcesNone ? NO_SOURCES : rowSourceId,
// v0.34.1 (#876): federated read scope. sourceScopeOpts in
// operations.ts prefers this array over scalar sourceId when set
// and non-empty.
allowedSources: sourcesNone ? [] : allowedSources,
...(sourcesNone ? { hasSourceGrant: true } : {}),
// Per-client takes holders; undefined → the /mcp dispatch site's fail-closed ['world'].
...(clientHolders ? { takesHoldersAllowList: clientHolders } : {}),
// v0.42.72.0: write fence — consumed by enforceClientSlugFence in
// operations.ts on every direct slug-mutating write op.
boundSlugPrefixes,
...(fenceProjectionDegraded ? { fenceProjectionDegraded: true } : {}),
// WP4: per-client surface + operator-lock marker (amendment 19).
...(rowSurface !== undefined ? { surface: rowSurface } : {}),
...(rowSurfaceSetBy !== undefined ? { surfaceSetBy: rowSurfaceSetBy } : {}),
// #5575 (CEO-18): the client's read floor; current_grant is the whole row, so no projection rung needs it.
...(storedMinTrust(currentGrant.min_trust) ? { minTrust: storedMinTrust(currentGrant.min_trust) } : {}),
// GBRA-156 / GBRA-575: private pages and private facts in the sources the client's grant names (source_id + federated_read), never its bound source.
...(sourcesNone || rowSourceId === undefined ? {} : privatePagesAuth(grantFromClient(grantFromRow({ ...currentGrant, source_id: rowSourceId, federated_read: allowedSources ?? [] })))),
} as CoreAuthInfo as SdkAuthInfo;
}
// Fallback: legacy access_tokens table (backward compat). SELECT * keeps
// every schema generation readable: pre-v38 rows have no permissions,
// pre-F3 rows no grant columns, and `scopes` (original schema) must never
// drop out of the projection, or normalizeTokenScopes(undefined) would
// grandfather a scoped token to full admin (ship-review P1).
const legacyRows: Record<string, unknown>[] = await this.sql`
SELECT * FROM access_tokens
WHERE token_hash = ${tokenHash} AND revoked_at IS NULL
`;
if (legacyRows.length > 0) {
// For legacy tokens, name = clientId = clientName (single identifier).
// #2833: debounced fire-and-forget last_used_at update that never blocks
// or fails verification; shared with src/mcp/http-transport.ts.
void touchTokenLastUsed(this.sql, legacyRows[0]);
const name = legacyRows[0].name as string;
// One grant shape (grants/model.ts), shared with the legacy HTTP
// transport so the two cannot drift. Unified rows read the columns,
// fail-closed on drift; a row still on the legacy shape is converted on
// this read (resolveTokenGrant). Scopes: NULL (every token minted before
// #4043) is grandfathered full access; an array is honored as-is,
// including [] as deny. Takes holders null → the /mcp dispatch site
// defaults to the fail-closed ['world'].
const grant = await resolveTokenGrant(this.sql, legacyRows[0]);
return {
token,
clientId: name,
principal: { kind: 'legacy_token', id: String(legacyRows[0].id) },
...withAttestRight(await tokenMemberBinding(this.sql, legacyRows[0], legacyRows[0].created_at), legacyRows[0], 'legacy'),
clientName: name,
scopes: grant.scopes,
...(grant.allowedOperations === null ? {} : { allowedOperations: grant.allowedOperations }),
expiresAt: Math.floor(Date.now() / 1000) + 365 * 24 * 3600, // Legacy tokens never expire — set 1yr future
// #3242 parity: hasSourceGrant=false only on the historical no-grant
// floor, the one case that may widen unqualified reads.
...authSourcesFromGrant(grant),
takesHoldersAllowList: grant.takesHolders ?? undefined,
...(storedMinTrust(legacyRows[0].min_trust) ? { minTrust: storedMinTrust(legacyRows[0].min_trust) } : {}),
...privatePagesAuth(grant),
} as CoreAuthInfo as SdkAuthInfo;
}
throw new InvalidTokenError('Invalid token');
}
// -------------------------------------------------------------------------
// Token Revocation
// -------------------------------------------------------------------------
async revokeToken(
client: OAuthClientInformationFull,
request: OAuthTokenRevocationRequest,
): Promise<void> {
await this.grants.revokeToken(client.client_id, request.token, client.client_secret);
}
/** Owner-triggered revocation serializes with every grant path. */
async revokeClient(clientId: string): Promise<void> {
await this.grants.revokeClient(clientId);
}
// -------------------------------------------------------------------------
// Client Credentials (called by custom handler, not SDK)
// -------------------------------------------------------------------------
/**
* v0.37.7.0 #1166 — verify a confidential client's secret without
* spending it. Returns the validated client info on success, throws
* with an opaque "Invalid client" message on failure (mirrors RFC 6749
* §5.2 invalid_client semantics). Used by the serve-http custom
* /token handler for `authorization_code` + `refresh_token` grants on
* confidential clients, since the SDK's plaintext compare in
* clientAuth.js can't see our hash-only storage.
*
* Public clients (token_endpoint_auth_method === 'none') return
* `client_secret_hash = NULL` from getClient; this method refuses
* them so the SDK's PKCE path stays the canonical surface.
*/
async verifyConfidentialClientSecret(
clientId: string,
presentedSecret: string,
): Promise<OAuthClientInformationFull> {
const client = await this._clientsStore.getClient(clientId);
if (!client || typeof client.client_secret !== 'string' || !/^[a-f0-9]{64}$/i.test(client.client_secret) || !safeHexEqual(client.client_secret, hashToken(presentedSecret))) {
throw new InvalidClientError('Invalid client or client has been revoked');
}
return client;
}
async exchangeClientCredentials(
clientId: string,
clientSecret: string,
requestedScope?: string,
): Promise<OAuthTokens> {
return this.grants.clientCredentials(clientId, clientSecret, requestedScope);
}
// -------------------------------------------------------------------------
// Maintenance
// -------------------------------------------------------------------------
async sweepExpiredTokens(): Promise<number> {
const now = Math.floor(Date.now() / 1000);
// F6 hardening: postgres.js and PGLite expose deleted-row count on
// different shapes; `(result as any).count` returned 0 on at least one
// engine even when rows were deleted, and codes were never counted at
// all. RETURNING 1 + array length is portable across both engines.
const result = await this.sql`
DELETE FROM oauth_tokens WHERE expires_at < ${now} RETURNING 1
`;
const deletedCodes = await this.sql`
DELETE FROM oauth_codes WHERE expires_at < ${now} RETURNING 1
`;
return result.length + deletedCodes.length;
}
// -------------------------------------------------------------------------
// CLI Registration Helper
// -------------------------------------------------------------------------
async registerClientManual(
name: string,
grantTypes: string[],
scopes: string,
redirectUris: string[] = [],
sourceId: string = 'default',
federatedRead?: string[],
tokenEndpointAuthMethod?: string,
agentBindings?: AgentClientBindings,
grantPatch?: GrantPatch,
): Promise<{ clientId: string; clientSecret?: string }> {
// v0.28: ALLOWED_SCOPES allowlist. Reject `--scopes "read flying-unicorn"`
// at registration so meaningless scope strings can't pile up in the DB.
// Pre-allowlist clients keep working (allowlist is registration-time;
// existing rows aren't re-validated).
assertAllowedScopes(parseScopeString(scopes));
// A bound_slug_prefixes entry that is empty or whitespace-only makes
// `startsWith` true for every slug — a binding that looks set in
// `auth list` and the admin UI while fencing nothing. Reject at
// registration, the same way source ids are validated.
if (agentBindings?.boundTools && (agentBindings.boundTools.length === 0 || agentBindings.boundTools.some(tool => typeof tool !== 'string' || !tool.trim()))) {
throw new Error('--bound-tools requires at least one non-empty tool name');
}
if (agentBindings?.boundSlugPrefixes) {
// Same rule as rescopeClient: an empty list is ambiguous. It registers
// as deny-all for every direct write while printing an empty binding
// line, so an operator cannot tell it from an unbound client.
if (agentBindings.boundSlugPrefixes.length === 0) {
throw new Error('--bound-slug-prefixes cannot be an empty list (pass prefixes, or omit the flag for full-source write authority)');
}
assertValidSlugPrefixes(agentBindings.boundSlugPrefixes);
}
// v0.41.3 (T1+T2): validate token_endpoint_auth_method at the registration
// boundary. Throws InvalidTokenEndpointAuthMethodError on bad input.
// Default is `client_secret_post` (RFC 7591 §2).
const authMethod = validateTokenEndpointAuthMethod(tokenEndpointAuthMethod);
const clientId = generateToken('gbrain_cl_');
// v0.41.3 (T2): atomic public-client INSERT. When the caller declares
// `tokenEndpointAuthMethod: 'none'` we mint NO secret and INSERT with
// client_secret_hash = NULL in a single statement. Pre-fix, the admin
// endpoint did INSERT-then-UPDATE which left a confidential row stranded
// if the UPDATE failed mid-flight (codex F4). Confidential clients
// (`client_secret_post` / `client_secret_basic`) get the secret minted
// and hashed as before.
const isPublicClient = authMethod === 'none';
const clientSecret = isPublicClient ? undefined : generateToken('gbrain_cs_');
const secretHash = clientSecret ? hashToken(clientSecret) : null;
const now = Math.floor(Date.now() / 1000);
// v0.34.1 (#861 + #876): persist source_id AND federated_read so
// verifyAccessToken can populate both AuthInfo fields. Defaults:
// source_id = 'default' (matches v60 backfill)
// federated_read = [source_id] when omitted (a non-federated client
// has read scope == write scope, the v0.33 default)
const federated = federatedRead && federatedRead.length > 0 ? federatedRead : [sourceId];
const schema = await this.sql`SELECT column_name FROM information_schema.columns
WHERE table_schema = current_schema() AND table_name = 'oauth_clients'
AND column_name IN ('grant_revision', 'allowed_operations', 'delegated_slug_prefixes', 'delegated_namespace', 'grant_profile', 'grant_repair_reasons', 'surface', 'surface_set_by', 'token_ttl', 'source_id', 'federated_read', 'bound_slug_prefixes', 'bound_tools', 'bound_source_id', 'bound_brain_id', 'bound_max_concurrent', 'budget_usd_per_day')`;
if (schema.length === 17) {
const initial = grantFromRow({
client_id: clientId, client_name: name, scope: scopes, source_id: sourceId,
federated_read: federated, bound_slug_prefixes: agentBindings?.boundSlugPrefixes ?? null,
allowed_operations: agentBindings?.allowedOperations ?? null,
bound_tools: agentBindings?.boundTools ?? null,
bound_source_id: agentBindings?.boundSourceId ?? null, bound_brain_id: agentBindings?.boundBrainId ?? null,
delegated_slug_prefixes: agentBindings?.delegatedSlugPrefixes ?? agentBindings?.boundSlugPrefixes ?? null,
delegated_namespace: agentBindings?.delegatedNamespace ?? (agentBindings?.boundSlugPrefixes || agentBindings?.delegatedSlugPrefixes ? 'prefixes' : 'job'),
bound_max_concurrent: agentBindings?.boundMaxConcurrent ?? 1,
budget_usd_per_day: agentBindings?.budgetUsdPerDay ?? null,
});
if (grantPatch) assertGrantPatch(grantPatch);
const changes = Object.fromEntries(Object.entries(grantPatch ?? {}).filter(([, value]) => value !== undefined)) as GrantPatch;
const grant = { ...initial, ...changes, revision: 1 };
grant.boundBrainId = normalizeGrantBrain(grant.boundBrainId);
validateClientGrant(grant, await grantValidationContext(this.sql));
// GST-1113: with a transaction, the scope-source check and the insert commit together under the source row locks.
const metadata = { secretHash, redirectUris, grantTypes, authMethod, issuedAt: now };
await (this.transaction ? this.transaction(sql => insertClientGrant(sql, grant, metadata)) : insertClientGrant(this.sql, grant, metadata));
return { clientId, clientSecret };
}
if (grantPatch || hasScope(parseScopeString(scopes), 'agent')) {
throw new Error('Client grants require an up-to-date OAuth schema; run gbrain apply-migrations --yes');
}
try {
if (agentBindings) {
await this.sql`
INSERT INTO oauth_clients (client_id, client_secret_hash, client_name, redirect_uris,
grant_types, scope, token_endpoint_auth_method,
client_id_issued_at,
source_id, federated_read,
bound_tools, bound_source_id, bound_brain_id,
bound_slug_prefixes, bound_max_concurrent, budget_usd_per_day)
VALUES (${clientId}, ${secretHash}, ${name},
${pgArray(redirectUris)}, ${pgArray(grantTypes)}, ${scopes}, ${authMethod}, ${now},
${sourceId}, ${pgArray(federated)},
${agentBindings.boundTools ? pgArray(agentBindings.boundTools) : null},
${agentBindings.boundSourceId ?? null}, ${agentBindings.boundBrainId ?? null},
${agentBindings.boundSlugPrefixes ? pgArray(agentBindings.boundSlugPrefixes) : null},
${agentBindings.boundMaxConcurrent ?? 1}, ${agentBindings.budgetUsdPerDay ?? null})
`;
} else {
await this.sql`
INSERT INTO oauth_clients (client_id, client_secret_hash, client_name, redirect_uris,
grant_types, scope, token_endpoint_auth_method,
client_id_issued_at,
source_id, federated_read)
VALUES (${clientId}, ${secretHash}, ${name},
${pgArray(redirectUris)}, ${pgArray(grantTypes)}, ${scopes}, ${authMethod}, ${now},
${sourceId}, ${pgArray(federated)})
`;
}
} catch (err) {
if (agentBindings && (
isUndefinedColumnError(err, 'bound_tools') ||
isUndefinedColumnError(err, 'bound_source_id') ||
isUndefinedColumnError(err, 'bound_brain_id') ||
isUndefinedColumnError(err, 'bound_slug_prefixes') ||
isUndefinedColumnError(err, 'bound_max_concurrent') ||
isUndefinedColumnError(err, 'budget_usd_per_day')
)) {
throw new Error('register-client --bound-* flags require an up-to-date OAuth schema; run `gbrain apply-migrations --yes` and retry.');
}
// Pre-v60 / pre-v61 brain: column missing. Fall back through both
// projections so registration still works until apply-migrations.
if (isUndefinedColumnError(err, 'federated_read')) {
// v60-only brain: source_id but no federated_read.
try {
await this.sql`
INSERT INTO oauth_clients (client_id, client_secret_hash, client_name, redirect_uris,
grant_types, scope, token_endpoint_auth_method,
client_id_issued_at, source_id)
VALUES (${clientId}, ${secretHash}, ${name},
${pgArray(redirectUris)}, ${pgArray(grantTypes)}, ${scopes}, ${authMethod}, ${now}, ${sourceId})
`;
} catch (err2) {
if (isUndefinedColumnError(err2, 'source_id')) {
await this.sql`
INSERT INTO oauth_clients (client_id, client_secret_hash, client_name, redirect_uris,
grant_types, scope, token_endpoint_auth_method,
client_id_issued_at)
VALUES (${clientId}, ${secretHash}, ${name},
${pgArray(redirectUris)}, ${pgArray(grantTypes)}, ${scopes}, ${authMethod}, ${now})
`;
} else {
throw err2;
}
}
} else if (isUndefinedColumnError(err, 'source_id')) {
await this.sql`
INSERT INTO oauth_clients (client_id, client_secret_hash, client_name, redirect_uris,
grant_types, scope, token_endpoint_auth_method,
client_id_issued_at)
VALUES (${clientId}, ${secretHash}, ${name},
${pgArray(redirectUris)}, ${pgArray(grantTypes)}, ${scopes}, ${authMethod}, ${now})
`;
} else {
throw err;
}
}
return { clientId, clientSecret };
}
/**
* v0.42.x (#1914): admin-gated rescope for an existing OAuth client.
*
* DCR clients self-register with source_id='default' +
* federated_read=['default'] and MUST NOT be able to widen their own
* scope (fail-closed trust). This is the trusted-operator surface that
* changes it afterward: `gbrain auth rescope-client` (local CLI) and
* POST /admin/api/rescope-client (requireAdmin) both route here.
*
* Omitted fields are left untouched (COALESCE). Takes effect on the
* client's NEXT request even for already-issued tokens, because
* verifyAccessToken re-reads oauth_clients on every verification.
*/
async rescopeClient(clientId: string, opts: RescopeClientOptions): Promise<RescopeClientResult> {
return rescopeOAuthClient(this.sql, clientId, opts);
}
}