@harperfast/harper 5.2.9 → 5.3.0-alpha.1

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';
+	},
+};

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

@@ -0,0 +1,137 @@
+/**
+ * GitHub Actions provider profile (#2171).
+ *
+ * The only module that should know anything about GitHub. Its rules are deliberately stricter than
+ * npm's trusted-publishing model, and scoping them here means that strictness never constrains
+ * another issuer.
+ */
+
+import { ClientError } from '../../../../utility/errors/hdbError.ts';
+import type { ClaimConstraint, TokenClaims } from '../types.ts';
+import type { IdentityProviderProfile } from './index.ts';
+
+/**
+ * Workflow references are `<owner>/<repo>/<path>@<ref>` and the ref is always a full `refs/...` name.
+ * Splitting on `@refs/` rather than the first or last `@` is exact, because a path segment cannot
+ * contain `/` — so this cannot occur inside the path, and a branch named `release@2` cannot fool it.
+ */
+const REF_QUALIFIER = '@refs/';
+
+/**
+ * GitHub's default audience is the repository owner's URL, shared by every repository under that
+ * owner, so accepting it would make a token minted by any repo in the org valid here — the one
+ * mistake the audience field exists to prevent.
+ */
+const SHARED_DEFAULT_AUDIENCE = /^https:\/\/github\.com\/[^/]+\/?$/i;
+
+/**
+ * Structural requirements on a policy's claim set, each guarding a distinct way a policy can be
+ * accidentally broad. Satisfying none of a row's claims admits, in order: any repository, any
+ * workflow in that repository, any branch that can be pushed to it.
+ *
+ * `repository_owner` is absent from the first row on purpose — it identifies an org, not a
+ * repository, so it would admit every repo in the org. `ref_type` is absent from the third for the
+ * same shape of reason: `ref_type: tag` still admits any tag, and anyone with push access can create
+ * one. A tag-triggered release pins `environment` and leans on GitHub's environment protection.
+ *
+ * `job_workflow_ref` pins the workflow (second row) but deliberately does NOT gate the ref (third).
+ * For a reusable workflow it names the workflow that RAN, not the caller that invoked it — the
+ * caller's ref lives in `workflow_ref`/`ref`. Its `@ref` suffix therefore describes the reusable
+ * workflow's own branch, which is constant however it is called, so accepting it as a ref gate would
+ * admit any branch of any caller repository that references that reusable workflow: precisely the
+ * hole the third row exists to close.
+ *
+ * `sub` is deliberately not accepted as a pin: it varies by trigger, and its format changed for
+ * repositories created after 2026-07-15 (immutable subjects embed owner and repo ids).
+ */
+const STRUCTURAL_REQUIREMENTS = [
+	{
+		requirement: 'pin the repository',
+		claims: ['repository_id', 'repository'],
+		because: ' (repository_id is immutable and survives renames)',
+	},
+	{
+		requirement: 'pin the workflow',
+		claims: ['workflow_ref', 'workflow_path', 'job_workflow_ref', 'job_workflow_path'],
+		because: '',
+	},
+	{
+		requirement: 'gate the ref',
+		claims: ['workflow_ref', 'ref', 'environment'],
+		because: ' — otherwise any branch that can be pushed to the repository can run the workflow and mint a token',
+	},
+];
+
+/** Returns undefined rather than guessing when the value is not a ref-qualified reference. */
+export function splitWorkflowPath(workflowRef: unknown): string | undefined {
+	if (typeof workflowRef !== 'string') return undefined;
+	const qualifierIndex = workflowRef.indexOf(REF_QUALIFIER);
+	return qualifierIndex === -1 ? undefined : workflowRef.slice(0, qualifierIndex);
+}
+
+export const githubActionsProfile: IdentityProviderProfile = {
+	name: 'GitHub Actions',
+
+	assertPolicyIsSpecific(policyClaims: Record<string, ClaimConstraint>): void {
+		const constrained = new Set(Object.keys(policyClaims));
+		for (const { requirement, claims, because } of STRUCTURAL_REQUIREMENTS) {
+			if (!claims.some((claimName) => constrained.has(claimName))) {
+				throw new ClientError(`claims must ${requirement} with one of: ${claims.join(', ')}${because}`);
+			}
+		}
+	},
+
+	assertAudienceIsSpecific(audience: string): void {
+		if (SHARED_DEFAULT_AUDIENCE.test(audience)) {
+			throw new ClientError(
+				`'audience' must identify this instance, not '${audience}' — GitHub's default audience is shared ` +
+					`by every repository under an owner, so a token minted for any of them would be accepted here. ` +
+					`Use the instance URL the CI client targets.`
+			);
+		}
+	},
+
+	/**
+	 * Adds `workflow_path` / `job_workflow_path` — the workflow reference with the ref removed — so a
+	 * policy can pin the workflow *file* while gating the ref some other way. A tag-triggered release
+	 * cannot pin `workflow_ref`, because the tag is unknown when the policy is written.
+	 *
+	 * A claim the token actually carries is never displaced by one we synthesized.
+	 */
+	normalizeClaims(payload: TokenClaims): TokenClaims {
+		const claims: TokenClaims = { ...payload };
+		for (const [source, derived] of [
+			['workflow_ref', 'workflow_path'],
+			['job_workflow_ref', 'job_workflow_path'],
+		]) {
+			const path = splitWorkflowPath(payload[source]);
+			if (path !== undefined && claims[derived] === undefined) claims[derived] = path;
+		}
+		return claims;
+	},
+
+	/**
+	 * A `pull_request_target` run executes the base repository's workflow with its secrets while a
+	 * fork controls the checked-out code. A plain `pull_request` run from a fork gets no
+	 * `id-token: write` and so cannot mint at all, but `pull_request_target` can — so it is denied
+	 * unless a policy constrains `event_name`, which is the explicit opt-in.
+	 */
+	vetoClaims(claims: TokenClaims, policyClaims: Record<string, ClaimConstraint>): string | undefined {
+		if (claims.event_name === 'pull_request_target' && policyClaims.event_name === undefined) {
+			return 'pull_request_target is denied unless the policy constrains event_name';
+		}
+		return undefined;
+	},
+
+	describePrincipal(claims: TokenClaims): string {
+		return [
+			claims.repository,
+			claims.workflow_ref ?? claims.workflow_path,
+			claims.environment && `environment=${claims.environment}`,
+			claims.run_id && `run=${claims.run_id}`,
+			claims.actor && `actor=${claims.actor}`,
+		]
+			.filter(Boolean)
+			.join(' ');
+	},
+};