@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/security/auth.ts

@@ -7,13 +7,21 @@ import { v4 as uuid } from 'uuid';
 import * as env from '../utility/environment/environmentManager.ts';
 import { CONFIG_PARAMS, AUTH_AUDIT_STATUS, AUTH_AUDIT_TYPES } from '../utility/hdbTerms.ts';
 import harperLogger from '../utility/logging/harper_logger.ts';
-const { forComponent, AuthAuditLog } = harperLogger;
+const { forComponent, AuthAuditLog, errorForLog } = harperLogger;
 import serverHandlers from '../server/itc/serverHandlers.js';
 const { user } = serverHandlers;
-import { Headers, addVaryHeader } from '../server/serverHelpers/Headers.ts';
+import { Headers, addVaryHeader, SHARED_CACHE_OPTIN, PRIVATE_SCOPE } from '../server/serverHelpers/Headers.ts';
 import { convertToMS } from '../utility/common_utils.ts';
 import { verifyCertificate } from './certificateVerification/index.ts';
+import {
+	credentialRejectionError,
+	deferCredentialRejection,
+	getDeferredCredentialRejection,
+	isCredentialRejection,
+} from './deferredAuthentication.ts';
 import { serializeMessage } from '../server/serverHelpers/contentTypes.ts';
+import { hdbErrors } from '../utility/errors/hdbError.ts';
+const { AUTHENTICATION_ERROR_MSGS, HTTP_STATUS_CODES } = hdbErrors;
 const authLogger = forComponent('authentication');
 const { debug } = authLogger;
 const authEventLog = authLogger.withTag('auth-event');
@@ -50,10 +58,6 @@ const LOG_AUTH_FAILED = env.get(CONFIG_PARAMS.LOGGING_AUDITAUTHEVENTS_LOGFAILED)
 
 const DEFAULT_COOKIE_EXPIRES = 'Tue, 01 Oct 8307 19:33:20 GMT';
 
-// RFC 9111 cache-scope directives; boundaries on both sides so a token like `public-foo` doesn't match
-const SHARED_CACHE_OPTIN = /(^|[,\s])(public|s-maxage)($|[\s,;=])/i;
-const PRIVATE_SCOPE = /(^|[,\s])(private|no-store)($|[\s,;=])/i;
-
 let authorizationCache = new Map();
 server.onInvalidatedUser(() => {
 	// TODO: Eventually we probably want to be able to invalidate individual users
@@ -190,7 +194,13 @@ export async function authentication(request, nextHandler) {
 		if (request.user) {
 			// already authenticated
 		} else if (authorization) {
-			const cachedUser = authorizationCache.get(authorization);
+			let cachedUser = authorizationCache.get(authorization);
+			// A cached Bearer identity must not outlive its token: expiry is the only revocation
+			// mechanism for scoped tokens, so it has to be exact, not cache-TTL-fuzzy.
+			if (cachedUser?.authExpiresAt && cachedUser.authExpiresAt * 1000 <= Date.now()) {
+				authorizationCache.delete(authorization);
+				cachedUser = undefined;
+			}
 			if (cachedUser?.role) {
 				// Shallow-clone so verifyPerms's `role.permission = fullRolePerms` reassignment
 				// doesn't mutate the cache entry (defense-in-depth; operations and other
@@ -204,6 +214,7 @@ export async function authentication(request, nextHandler) {
 				const strategy = authorization.slice(0, spaceIndex);
 				const credentials = authorization.slice(spaceIndex + 1);
 				let username, password;
+				let credentialRejection;
 				try {
 					switch (strategy) {
 						case 'Basic':
@@ -231,12 +242,23 @@ export async function authentication(request, nextHandler) {
 											// API has its own logic for handling this
 											status: -1,
 										});
-									} catch {
+									} catch (refreshError) {
+										// Preserve refresh-validation faults; only a tagged rejection permits falling
+										// back to the original operation-token rejection.
+										if (!isCredentialRejection(refreshError)) throw refreshError;
 										throw error;
 									}
 								}
+								// A non-'invalid token' rejection (e.g. expired) must propagate, not fall
+								// through to caching an undefined user (which would read as anonymous).
+								throw error;
 							}
 							break;
+						default:
+							throw credentialRejectionError(
+								AUTHENTICATION_ERROR_MSGS.GENERIC_AUTH_FAIL,
+								HTTP_STATUS_CODES.UNAUTHORIZED
+							);
 					}
 				} catch (err) {
 					if (LOG_AUTH_FAILED) {
@@ -247,18 +269,31 @@ export async function authentication(request, nextHandler) {
 						}
 					}
 
-					return applyResponseHeaders({
-						status: 401,
-						body: serializeMessage({ error: err.message }, request),
-					});
+					const internalFault = !isCredentialRejection(err);
+					if (request.isOperationsServer || internalFault) {
+						if (internalFault) authLogger.error('Authentication failed internally', errorForLog(err));
+						return applyResponseHeaders({
+							status: 401,
+							body: serializeMessage(
+								{ error: internalFault ? AUTHENTICATION_ERROR_MSGS.GENERIC_AUTH_FAIL : err.message },
+								request
+							),
+						});
+					}
+					credentialRejection = err;
 				}
 
-				authorizationCache.set(authorization, newUser);
-				if (LOG_AUTH_SUCCESSFUL) authAuditLog(newUser.username, AUTH_AUDIT_STATUS.SUCCESS, strategy);
-				// Shallow-clone so verifyPerms's `role.permission = fullRolePerms` reassignment
-				// doesn't mutate the just-stored cache entry (defense-in-depth).
-				if (newUser?.role) {
-					newUser = { ...newUser, role: { ...newUser.role, permission: { ...newUser.role.permission } } };
+				if (credentialRejection) {
+					deferCredentialRejection(request, credentialRejection, strategy);
+				} else {
+					authorizationCache.set(authorization, newUser);
+					if (LOG_AUTH_SUCCESSFUL && newUser != null)
+						authAuditLog(newUser.username, AUTH_AUDIT_STATUS.SUCCESS, strategy);
+					// Shallow-clone so verifyPerms's `role.permission = fullRolePerms` reassignment
+					// doesn't mutate the just-stored cache entry (defense-in-depth).
+					if (newUser?.role) {
+						newUser = { ...newUser, role: { ...newUser.role, permission: { ...newUser.role.permission } } };
+					}
 				}
 			}
 
@@ -346,16 +381,19 @@ export async function authentication(request, nextHandler) {
 		if (!response) return response;
 		if (response.status === 401) {
 			wasUnauthorized = true;
-			if (
-				headers['user-agent']?.startsWith('Mozilla') &&
-				headers.accept?.startsWith('text/html') &&
-				resources.loginPath
-			) {
-				// on the web if we have a login page, default to redirecting to it
-				response.status = 302;
-				response.headers.set('Location', resources.loginPath(request));
-			} // the HTTP specified way of indicating HTTP authentication methods supported:
-			else response.headers.set('WWW-Authenticate', 'Basic');
+			// Downstream owns the challenge or redirect after Harper deferred the credential decision.
+			if (!getDeferredCredentialRejection(request)) {
+				if (
+					headers['user-agent']?.startsWith('Mozilla') &&
+					headers.accept?.startsWith('text/html') &&
+					resources.loginPath
+				) {
+					// on the web if we have a login page, default to redirecting to it
+					response.status = 302;
+					response.headers.set('Location', resources.loginPath(request));
+				} // the HTTP specified way of indicating HTTP authentication methods supported:
+				else response.headers.set('WWW-Authenticate', 'Basic');
+			}
 		}
 		return applyResponseHeaders(response);
 	} catch (error) {
@@ -367,7 +405,8 @@ export async function authentication(request, nextHandler) {
 		// if we are rejecting the credentials (401, possibly rewritten to a login redirect); such a
 		// response must never be stored by a shared cache and served to a different principal (#1565)
 		const rejectedAuth = response?.status === 401 || wasUnauthorized;
-		const identityDependent = !!request.user || rejectedAuth;
+		// A downstream response produced under the untouched credential remains identity-dependent (#1565).
+		const identityDependent = !!request.user || rejectedAuth || !!getDeferredCredentialRejection(request);
 		// with CORS enabled the response is origin-dependent — ACAO reflects the request Origin, and
 		// its absence when no Origin was sent is origin-dependent too — so a shared cache must
 		// partition on Origin either way (#1518)

package/security/authn/oidc/claims.ts

@@ -0,0 +1,72 @@
+/**
+ * Issuer-agnostic claim matching and constraint validation (#2171).
+ *
+ * Pure — no network, no storage, and nothing that knows which issuer a token came from. Rules that
+ * depend on the issuer live in providers/.
+ */
+
+import { ClientError } from '../../../utility/errors/hdbError.ts';
+import type { ClaimConstraint, TokenClaims } from './types.ts';
+
+/** Issuers may encode a numeric id as a JSON number; anything non-scalar is not comparable. */
+function claimToString(value: unknown): string | undefined {
+	if (typeof value === 'string') return value;
+	if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+	return undefined;
+}
+
+/**
+ * Returns undefined on a match, or the first failure's reason — for the log, never the caller.
+ *
+ * A constrained claim absent from the token fails rather than passes, so a policy cannot be weakened
+ * by an issuer that stops emitting a claim.
+ */
+export function matchTrustPolicyClaims(
+	claims: TokenClaims,
+	policyClaims: Record<string, ClaimConstraint>
+): string | undefined {
+	const constraints = Object.entries(policyClaims);
+	// validateClaimConstraintShape rejects this at write time; this backstops a row that reached the
+	// table another way, such as replication from a peer.
+	if (constraints.length === 0) return 'policy constrains no claims';
+
+	for (const [claimName, constraint] of constraints) {
+		const actual = claimToString(claims[claimName]);
+		if (actual === undefined || actual === '') return `token has no usable ${claimName} claim`;
+		const accepted = Array.isArray(constraint) ? constraint : [constraint];
+		// Exact membership, deliberately — never a prefix, wildcard, or regex. Relaxing this to
+		// something like `startsWith` is the classic trusted-publishing escalation: a policy pinning
+		// `HarperFast/my-app` would then also admit `HarperFast/my-app-evil`, a repository anyone can
+		// create. unitTests/security/authn/oidc/claims.test.js pins both argument orders.
+		if (!accepted.includes(actual)) return `${claimName} does not match the policy`;
+	}
+	return undefined;
+}
+
+/**
+ * Validates the *shape* of a policy's constraints — that each is a usable set of comparable values.
+ * Whether the set is specific enough to be safe depends on the issuer; that is the provider profile's
+ * assertPolicyIsSpecific.
+ *
+ * Throws ClientError naming the first problem; the reader is an administrator writing a policy.
+ */
+export function validateClaimConstraintShape(
+	policyClaims: unknown
+): asserts policyClaims is Record<string, ClaimConstraint> {
+	if (!policyClaims || typeof policyClaims !== 'object' || Array.isArray(policyClaims)) {
+		throw new ClientError('claims must be an object of claim constraints');
+	}
+
+	const entries = Object.entries(policyClaims as Record<string, unknown>);
+	if (entries.length === 0) throw new ClientError('claims must constrain at least one claim');
+
+	for (const [claimName, constraint] of entries) {
+		const values = Array.isArray(constraint) ? constraint : [constraint];
+		if (values.length === 0) throw new ClientError(`claims.${claimName} must accept at least one value`);
+		for (const value of values) {
+			if (typeof value !== 'string' || value === '') {
+				throw new ClientError(`claims.${claimName} must be a non-empty string or an array of non-empty strings`);
+			}
+		}
+	}
+}

package/security/authn/oidc/identityToken.ts

@@ -0,0 +1,129 @@
+/**
+ * Identity-token verification for OIDC trusted publishing (#2171).
+ *
+ * Verifies that a token was signed by the configured issuer and is addressed to this instance.
+ * Matching it against a policy's claim constraints is separate (claims.ts), because one verification
+ * serves every policy sharing an issuer and audience.
+ */
+
+import jwt, { type Algorithm, type JwtPayload } from 'jsonwebtoken';
+import type { KeyObject } from 'node:crypto';
+import { ClientError } from '../../../utility/errors/hdbError.ts';
+import { loggerWithTag } from '../../../utility/logging/logger.ts';
+import { getSigningKey as defaultGetSigningKey, normalizeIssuer } from './jwks.ts';
+import { profileForIssuer } from './providers/index.ts';
+import type { TokenClaims } from './types.ts';
+
+const logger = loggerWithTag('oidc-trust');
+
+/**
+ * Asymmetric signatures only. Passing this to jwt.verify is what prevents algorithm confusion: an
+ * `alg: none` token, or one HMAC-signed with a public key as the secret, is rejected before the
+ * signature is considered.
+ */
+const ALLOWED_ALGORITHMS: Algorithm[] = [
+	'RS256',
+	'RS384',
+	'RS512',
+	'ES256',
+	'ES384',
+	'ES512',
+	'PS256',
+	'PS384',
+	'PS512',
+];
+
+const CLOCK_TOLERANCE_SECONDS = 60;
+
+/** CI identity tokens are minted per job and live minutes; a far-future expiry is not one to honor. */
+const MAX_TOKEN_LIFETIME_SECONDS = 3_600;
+
+export interface VerifyTokenTarget {
+	issuer: string;
+	audience: string;
+}
+
+export interface VerifyTokenOptions {
+	/** Overridable for tests; defaults to the network-backed JWKS lookup. */
+	getSigningKey?: (issuer: string, kid: unknown) => Promise<KeyObject>;
+	/** Seconds since the epoch to evaluate expiry against; defaults to the real clock. */
+	clockTimestamp?: number;
+}
+
+/**
+ * Refuses a token. Shared with the exchange so both halves fail identically: the endpoint is
+ * unauthenticated, and a caller told exactly which check failed can probe a policy one claim at a
+ * time. The reason goes to the log instead.
+ */
+export function rejectToken(detail: string): never {
+	logger.warn?.(`Rejecting identity token: ${detail}`);
+	throw new ClientError('Identity token was rejected', 401);
+}
+
+/** Verifies a CI identity token against one issuer/audience pair and returns its normalized claims. */
+export async function verifyIdentityToken(
+	token: unknown,
+	target: VerifyTokenTarget,
+	options: VerifyTokenOptions = {}
+): Promise<TokenClaims> {
+	if (typeof token !== 'string' || token === '') throw new ClientError('token is required');
+	const issuer = normalizeIssuer(target.issuer);
+	if (typeof target.audience !== 'string' || target.audience === '') {
+		throw new ClientError('audience is required');
+	}
+
+	const decoded = jwt.decode(token, { complete: true });
+	if (!decoded) rejectToken('token is not a well-formed JWT');
+
+	// Checked before resolving a key so a garbage header costs no outbound request.
+	if (!ALLOWED_ALGORITHMS.includes(decoded.header.alg as Algorithm)) {
+		rejectToken(`unsupported algorithm ${decoded.header.alg}`);
+	}
+
+	const getSigningKey = options.getSigningKey ?? defaultGetSigningKey;
+	const key = await getSigningKey(issuer, decoded.header.kid);
+
+	let payload: JwtPayload;
+	try {
+		payload = jwt.verify(token, key, {
+			algorithms: ALLOWED_ALGORITHMS,
+			// Both spellings, because `issuer` here is normalized (trailing slash stripped) while
+			// jsonwebtoken compares it byte-for-byte against the raw `iss`. Azure AD v1 emits
+			// `https://sts.windows.net/<tenant>/`, which would otherwise never authenticate — and the
+			// generic profile exists precisely to serve issuers like it with no provider code. This
+			// cannot widen trust: normalizeIssuer already maps the two forms to one value, which is
+			// what keys the JWKS cache, the discovery check, and the policy lookup.
+			issuer: [issuer, `${issuer}/`],
+			audience: target.audience,
+			clockTolerance: CLOCK_TOLERANCE_SECONDS,
+			...(options.clockTimestamp === undefined ? {} : { clockTimestamp: options.clockTimestamp }),
+		}) as JwtPayload;
+	} catch (error) {
+		rejectToken((error as Error).message);
+	}
+
+	// jsonwebtoken only enforces `exp` when present, so a token without one never expires.
+	if (typeof payload.exp !== 'number') rejectToken('token has no exp claim');
+	// `iat` is REQUIRED by OIDC, and required here rather than treated as optional: skipping the
+	// ceiling when it is absent means a token carrying a distant `exp` and no `iat` is unbounded —
+	// the ceiling would silently not apply to exactly the token that most needs it.
+	if (typeof payload.iat !== 'number') rejectToken('token has no iat claim');
+
+	// Bounded against the verification clock, not only as `exp - iat`. jsonwebtoken validates `exp`
+	// and `nbf` but never rejects a future `iat`, so an issuer that shifts the whole pair forward
+	// keeps a small delta and still hands out a token valid far longer than the ceiling. Both the
+	// delta and the absolute distance to `exp` are checked; the tolerance mirrors the one given to
+	// jwt.verify so genuine clock skew is not treated as an attack.
+	const now = options.clockTimestamp ?? Math.floor(Date.now() / 1000);
+	if (payload.iat > now + CLOCK_TOLERANCE_SECONDS) rejectToken('token iat is in the future');
+	if (payload.exp - payload.iat > MAX_TOKEN_LIFETIME_SECONDS) {
+		rejectToken(`token lifetime exceeds ${MAX_TOKEN_LIFETIME_SECONDS}s`);
+	}
+	if (payload.exp - now > MAX_TOKEN_LIFETIME_SECONDS + CLOCK_TOLERANCE_SECONDS) {
+		rejectToken(`token expires more than ${MAX_TOKEN_LIFETIME_SECONDS}s from now`);
+	}
+	// No `jti` requirement: not every issuer emits one (Azure uses `uti`, others omit it), and the
+	// exchange keys replay on a hash of the token itself, which is universal.
+
+	return profileForIssuer(issuer).normalizeClaims(payload as TokenClaims);
+}

package/security/authn/oidc/jwks.ts

@@ -0,0 +1,260 @@
+/**
+ * OIDC discovery and JWKS retrieval for trusted publishing (#2171).
+ *
+ * The issuer's signing keys are the root of trust for an exchanged token, and the endpoint that
+ * reaches them is unauthenticated — hence HTTPS only, bounded body, bounded time, and a rate limit
+ * on the refetch an unrecognized `kid` triggers, without which forged `kid`s become one outbound
+ * fetch per request.
+ */
+
+import { createPublicKey, type KeyObject } from 'node:crypto';
+import { loggerWithTag } from '../../../utility/logging/logger.ts';
+import { ClientError, ServerError } from '../../../utility/errors/hdbError.ts';
+
+const logger = loggerWithTag('oidc-trust');
+
+const DISCOVERY_PATH = '/.well-known/openid-configuration';
+/** How long a fetched key set is served without revalidation. */
+const JWKS_CACHE_TTL_MS = 3_600_000;
+/** Floor between refetches triggered by an unrecognized `kid`. */
+const MIN_REFETCH_INTERVAL_MS = 60_000;
+/**
+ * How long a cached key set survives a failed refetch. Bounded, so a network blip does not break
+ * deploys but a pulled key does not stay honored forever.
+ */
+const STALE_KEY_GRACE_MS = 86_400_000;
+const FETCH_TIMEOUT_MS = 5_000;
+const MAX_RESPONSE_BYTES = 1_048_576;
+/** Asymmetric only: an `oct` key in a JWKS is the setup for algorithm confusion. */
+const SUPPORTED_KEY_TYPES = ['RSA', 'EC'];
+
+interface IssuerKeys {
+	keys: Map<string, KeyObject>;
+	fetchedAt: number;
+}
+
+const issuerKeyCache = new Map<string, IssuerKeys>();
+const inFlightLoads = new Map<string, Promise<IssuerKeys>>();
+/**
+ * When an unrecognized `kid` last drove a refetch, per issuer. Outside the cache entry on purpose:
+ * every successful fetch replaces that entry, and a rate limit that resets whenever it fires is not
+ * a rate limit. Separating them also lets a genuine key rotation be picked up on first use.
+ */
+const unknownKidRefetchAt = new Map<string, number>();
+
+/**
+ * When a refresh for an issuer last FAILED, per issuer. Tracked separately from `fetchedAt`, which a
+ * failed fetch does not advance — so without this, every request wave arriving after the cache went
+ * stale starts discovery again and rides the same timeout before falling back to the same stale key.
+ * The exchange is unauthenticated and picks its issuer from an unverified JWT, and issuer key ids are
+ * public, so an anonymous caller could keep that cycle running for the length of an issuer outage:
+ * exactly when the stale-key grace is supposed to be absorbing load, not generating it.
+ */
+const failedRefreshAt = new Map<string, number>();
+
+/** How long a failed refresh suppresses the next one, while a usable stale key is still on hand. */
+const FAILED_REFRESH_BACKOFF_MS = 30_000;
+
+/**
+ * Bumped by every clear. A fetch that was already in flight when the cache was cleared must not
+ * write its now-stale result back: clearing drops `inFlightLoads`, but the orphaned fetch still
+ * holds a reference and would repopulate the entry an operator just discarded — which for a clear
+ * issued precisely because the cached key is wrong means the re-read silently does nothing.
+ */
+let cacheGeneration = 0;
+
+/** Drops all cached key sets. Exported for tests and for an operator forcing a re-read. */
+export function clearJwksCache(): void {
+	cacheGeneration++;
+	issuerKeyCache.clear();
+	inFlightLoads.clear();
+	unknownKidRefetchAt.clear();
+	failedRefreshAt.clear();
+}
+
+/**
+ * Canonicalizes an issuer URL. The result is both the cache key and the discovery base, so a policy
+ * stored with a trailing slash and one without must not become two entries for the same issuer.
+ */
+export function normalizeIssuer(issuer: unknown): string {
+	if (typeof issuer !== 'string' || issuer === '') throw new ClientError('issuer is required');
+	let url: URL;
+	try {
+		url = new URL(issuer);
+	} catch {
+		throw new ClientError(`issuer is not a valid URL: ${issuer}`);
+	}
+	if (url.protocol !== 'https:') throw new ClientError('issuer must be an https URL');
+	if (url.search !== '' || url.hash !== '') throw new ClientError('issuer must not carry a query or fragment');
+	return url.origin + (url.pathname === '/' ? '' : url.pathname.replace(/\/$/, ''));
+}
+
+/**
+ * `content-length` is checked first as a cheap rejection, then the body is counted as it streams —
+ * the header is advisory, and a hostile endpoint can simply omit it.
+ */
+async function readBoundedJson(response: Response, url: string): Promise<any> {
+	const declaredLength = Number(response.headers.get('content-length'));
+	if (Number.isFinite(declaredLength) && declaredLength > MAX_RESPONSE_BYTES) {
+		throw new ServerError(`Response from ${url} exceeds ${MAX_RESPONSE_BYTES} bytes`);
+	}
+	const chunks: Buffer[] = [];
+	let total = 0;
+	if (response.body) {
+		for await (const chunk of response.body as unknown as AsyncIterable<Uint8Array>) {
+			total += chunk.length;
+			if (total > MAX_RESPONSE_BYTES) {
+				throw new ServerError(`Response from ${url} exceeds ${MAX_RESPONSE_BYTES} bytes`);
+			}
+			chunks.push(Buffer.from(chunk));
+		}
+	}
+	try {
+		return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+	} catch (error) {
+		throw new ServerError(`Response from ${url} is not valid JSON: ${(error as Error).message}`);
+	}
+}
+
+async function fetchJson(url: string): Promise<any> {
+	let response: Response;
+	try {
+		response = await fetch(url, {
+			signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+			headers: { accept: 'application/json' },
+			redirect: 'error',
+		});
+	} catch (error) {
+		throw new ServerError(`Could not reach ${url}: ${(error as Error).message}`);
+	}
+	if (!response.ok) throw new ServerError(`${url} responded ${response.status}`);
+	return readBoundedJson(response, url);
+}
+
+/**
+ * The discovery document's own `issuer` must equal the one we asked about — the spec requires it,
+ * and it stops a misdirected document from quietly re-pointing an issuer we trust.
+ */
+async function discoverJwksUri(issuer: string): Promise<string> {
+	const document = await fetchJson(issuer + DISCOVERY_PATH);
+	// Swallowed rather than propagated: normalizeIssuer raises ClientError, the wrong shape for a
+	// malformed *server* response.
+	let declaredIssuer: string | undefined;
+	try {
+		declaredIssuer = normalizeIssuer(document?.issuer);
+	} catch {
+		declaredIssuer = undefined;
+	}
+	if (declaredIssuer !== issuer) {
+		throw new ServerError(`Discovery document at ${issuer} declares a different issuer`);
+	}
+	const jwksUri = document?.jwks_uri;
+	if (typeof jwksUri !== 'string' || !jwksUri.startsWith('https://')) {
+		throw new ServerError(`Discovery document at ${issuer} has no https jwks_uri`);
+	}
+	return jwksUri;
+}
+
+/**
+ * Undefined for a key we will not honor. One unusable entry must not poison the set: issuers publish
+ * keys for other purposes, and an unknown future type should degrade rather than fail the fetch.
+ */
+function toSigningKey(jwk: any): KeyObject | undefined {
+	if (!jwk || typeof jwk !== 'object') return undefined;
+	if (typeof jwk.kid !== 'string' || jwk.kid === '') return undefined;
+	if (jwk.use !== undefined && jwk.use !== 'sig') return undefined;
+	if (!SUPPORTED_KEY_TYPES.includes(jwk.kty)) return undefined;
+	try {
+		return createPublicKey({ key: jwk, format: 'jwk' });
+	} catch (error) {
+		logger.warn?.(`Skipping unusable JWK ${jwk.kid}: ${(error as Error).message}`);
+		return undefined;
+	}
+}
+
+async function fetchIssuerKeys(issuer: string): Promise<IssuerKeys> {
+	// Sampled before the first await, so any clear during the fetch is detectable at the end.
+	const generation = cacheGeneration;
+	const jwksUri = await discoverJwksUri(issuer);
+	const jwks = await fetchJson(jwksUri);
+	if (!Array.isArray(jwks?.keys)) throw new ServerError(`JWKS at ${jwksUri} has no keys array`);
+
+	const keys = new Map<string, KeyObject>();
+	for (const jwk of jwks.keys) {
+		const key = toSigningKey(jwk);
+		if (key) keys.set(jwk.kid, key);
+	}
+	if (keys.size === 0) throw new ServerError(`JWKS at ${jwksUri} contains no usable signing keys`);
+
+	const entry: IssuerKeys = { keys, fetchedAt: Date.now() };
+	// Still returned to the caller that asked for it — it is freshly fetched and valid — but only
+	// cached if no clear happened while this was in flight.
+	if (generation === cacheGeneration) issuerKeyCache.set(issuer, entry);
+	logger.debug?.(`Loaded ${keys.size} signing key(s) for ${issuer}`);
+	return entry;
+}
+
+/** Loads an issuer's keys, collapsing concurrent callers onto one fetch. */
+function loadIssuerKeys(issuer: string): Promise<IssuerKeys> {
+	const existing = inFlightLoads.get(issuer);
+	if (existing) return existing;
+
+	const load = fetchIssuerKeys(issuer).finally(() => inFlightLoads.delete(issuer));
+	inFlightLoads.set(issuer, load);
+	return load;
+}
+
+/** Resolves the public key an issuer used to sign a token, by `kid`. */
+/**
+ * `now` exists so the two time-based bounds below can be tested — the cache TTL and, more
+ * importantly, the STALE_KEY_GRACE_MS ceiling that stops a pulled key being honored forever through
+ * a prolonged outage. Reaching either otherwise needs a cache aged past an hour, and this repo bars
+ * new fake timers. Mirrors the `clockTimestamp` seam verifyIdentityToken already takes, rather than
+ * inventing a second convention. Callers in production pass nothing.
+ */
+export async function getSigningKey(issuer: string, kid: unknown, now: number = Date.now()): Promise<KeyObject> {
+	if (typeof kid !== 'string' || kid === '') throw new ClientError('Token has no key id', 401);
+	const normalizedIssuer = normalizeIssuer(issuer);
+	const cached = issuerKeyCache.get(normalizedIssuer);
+
+	if (cached && now - cached.fetchedAt < JWKS_CACHE_TTL_MS) {
+		const key = cached.keys.get(kid);
+		if (key) return key;
+		// Unknown kid against a still-fresh set: refetch once, then hold the line for the window. The
+		// timestamp is recorded before the fetch so a failing issuer is rate-limited like a succeeding one.
+		if (now - (unknownKidRefetchAt.get(normalizedIssuer) ?? 0) < MIN_REFETCH_INTERVAL_MS) {
+			throw new ClientError('Token signing key is not recognized', 401);
+		}
+		unknownKidRefetchAt.set(normalizedIssuer, now);
+	}
+
+	// A usable stale key, if the cache is expired but still inside the grace window.
+	const staleKey = cached && now - cached.fetchedAt < STALE_KEY_GRACE_MS ? cached.keys.get(kid) : undefined;
+
+	// Skip the fetch entirely while a recent one is known to have failed. Not gated on having a stale
+	// key: the fetch is the expensive part, and the issuer we have NEVER cached is the worse case —
+	// there is nothing to fall back to, so without this every request rides the full discovery and
+	// timeout. Refusing for the backoff interval bounds what an anonymous caller can drive, at the
+	// cost of a legitimate first exchange waiting out that interval after a blip. Fails closed.
+	if (now - (failedRefreshAt.get(normalizedIssuer) ?? 0) < FAILED_REFRESH_BACKOFF_MS) {
+		if (staleKey) return staleKey;
+		throw new ServerError(`Signing keys for ${normalizedIssuer} are temporarily unavailable; a recent refresh failed`);
+	}
+
+	let refreshed: IssuerKeys;
+	try {
+		refreshed = await loadIssuerKeys(normalizedIssuer);
+	} catch (error) {
+		// Recorded whether or not a stale key rescues this request, so the backoff also covers the
+		// issuer whose keys we have never held.
+		failedRefreshAt.set(normalizedIssuer, now);
+		if (!staleKey) throw error;
+		logger.warn?.(`Using cached signing key for ${normalizedIssuer}; refresh failed: ${(error as Error).message}`);
+		return staleKey;
+	}
+	failedRefreshAt.delete(normalizedIssuer);
+
+	const key = refreshed.keys.get(kid);
+	if (!key) throw new ClientError('Token signing key is not recognized', 401);
+	return key;
+}

package/security/authn/oidc/providers/generic.ts

@@ -0,0 +1,40 @@
+/**
+ * Fallback profile for issuers with no registered provider profile (#2171).
+ *
+ * Strict rather than permissive: the policy must pin `sub`. That is what makes workload identity work
+ * with zero provider code — a Kubernetes service-account token
+ * (`system:serviceaccount:<namespace>:<name>`), a GCP service account, and a SPIFFE SVID all carry a
+ * stable canonical subject, so pinning it identifies exactly one principal.
+ *
+ * GitHub Actions needs its own profile precisely because its `sub` is the one claim you should not
+ * pin: it varies by trigger, and its format changed for repositories created after 2026-07-15.
+ */
+
+import { ClientError } from '../../../../utility/errors/hdbError.ts';
+import type { ClaimConstraint, TokenClaims } from '../types.ts';
+import type { IdentityProviderProfile } from './index.ts';
+
+export const genericProfile: IdentityProviderProfile = {
+	name: 'generic OIDC',
+
+	assertPolicyIsSpecific(policyClaims: Record<string, ClaimConstraint>): void {
+		if (policyClaims.sub === undefined) {
+			throw new ClientError(
+				'claims must pin `sub` for an issuer with no registered provider profile — it is the only ' +
+					'claim every OIDC issuer defines as identifying a single principal. Register a provider ' +
+					'profile if this issuer needs richer rules.'
+			);
+		}
+	},
+
+	// No known shared default audience; the required `sub` pin already binds the policy to one principal.
+	assertAudienceIsSpecific(): void {},
+
+	normalizeClaims(payload: TokenClaims): TokenClaims {
+		return { ...payload };
+	},
+
+	describePrincipal(claims: TokenClaims): string {
+		return typeof claims.sub === 'string' ? claims.sub : 'unknown principal';
+	},
+};