@harperfast/harper 5.2.9 → 5.3.0-alpha.1

package/security/authn/oidc/trustPolicyOperations.ts

@@ -0,0 +1,343 @@
+'use strict';
+
+// Operations against system.hdb_oidc_trust — the trust policies for OIDC trusted publishing (#2171).
+//
+// A policy lets an external CI run authenticate as a Harper user without holding any Harper
+// credential, so these are super_user only. Following components/secretOperations.ts, super_user is
+// enforced in-handler as well as via requiredPermissions: a role's `operations` allowlist can
+// otherwise delegate an SU-only operation (see the gate-2 bypass in utility/operation_authorization.ts).
+//
+// Rows reach peers through normal system-table replication; these operations deliberately do not
+// call replicateOperation, which would double-apply on top of it.
+
+import Joi from 'joi';
+import { databases } from '../../../resources/databases.ts';
+import * as terms from '../../../utility/hdbTerms.ts';
+import { ClientError, hdbErrors } from '../../../utility/errors/hdbError.ts';
+import { validateBySchema } from '../../../validation/validationWrapper.ts';
+import { loggerWithTag } from '../../../utility/logging/logger.ts';
+import { getUsersWithRolesCache } from '../../user.ts';
+import { validateClaimConstraintShape } from './claims.ts';
+import { normalizeIssuer } from './jwks.ts';
+import { profileForIssuer } from './providers/index.ts';
+import { validateOperations } from '../../../utility/operationPermissions.ts';
+import type { OidcTrustPolicy } from './types.ts';
+
+const { HTTP_STATUS_CODES } = hdbErrors;
+const OIDC_TRUST_TABLE = terms.SYSTEM_TABLE_NAMES.OIDC_TRUST_TABLE_NAME;
+// Same tag as tokenExchange: an ignored row and the exchange that ignored it belong in one stream.
+const logger = loggerWithTag('oidc-trust');
+
+const POLICY_ID = Joi.string()
+	.min(1)
+	.max(128)
+	.pattern(/^[\w.-]+$/)
+	.required()
+	.messages({ 'string.pattern.base': "'id' may contain only letters, numbers, '_', '-', and '.'" });
+
+function requireSuperUser(req: any): void {
+	if (!req?.hdb_user?.role?.permission?.super_user) {
+		throw new ClientError(
+			`Operation '${req?.operation}' is restricted to super_user roles`,
+			HTTP_STATUS_CODES.FORBIDDEN
+		);
+	}
+}
+
+function validate(validation: any): void {
+	if (validation) throw new ClientError(validation.message);
+}
+
+/**
+ * A typo would otherwise fail closed at request time, in CI, with nothing to point at — so it is
+ * caught here, where the reader is the administrator who wrote it. Delegates to the same helper
+ * add_role/alter_role use, so group names resolve identically rather than through a second
+ * definition that could drift.
+ */
+function assertOperationsAreKnown(operations: string[]): void {
+	const invalidOperation = validateOperations(operations);
+	if (invalidOperation != null) {
+		throw new ClientError(`operations contains '${invalidOperation}', which is not a Harper operation`);
+	}
+}
+
+/**
+ * The audience is matched by exact string equality at verification time (`jwt.verify`), and the CLI
+ * asks its provider for a token whose audience is `normalizeTarget(target)` — which supplies `:9925`
+ * when no port was written, and a trailing slash. So `audience=https://my-instance.example.com`, the
+ * natural reading of "the instance URL the CI client targets", stores a policy that can never match
+ * anything; the exchange then refuses with the same opaque message it gives every other failure,
+ * leaving the operator nothing to look at, in CI. Caught here instead, where the reader is the
+ * administrator who wrote it — the same bargain assertOperationsAreKnown makes.
+ *
+ * Rejected rather than rewritten: silently canonicalizing a value whose whole job is to be compared
+ * byte-for-byte is worse than refusing it, and it would also have to run after the profile's
+ * shared-audience guard to avoid disarming it. Stating the requirement keeps this independent of
+ * normalizeTarget's exact spelling rules, which live in the CLI; a unit test pins the two together.
+ *
+ * Only http(s) URLs are shaped this way. An issuer-specific audience (an `api://` identifier, a bare
+ * GUID) is not ours to constrain, so anything that is not an http(s) URL passes untouched.
+ */
+function assertAudienceIsCanonical(audience: string): void {
+	let url: URL;
+	try {
+		url = new URL(audience);
+	} catch {
+		return;
+	}
+	if (url.protocol !== 'http:' && url.protocol !== 'https:') return;
+
+	// `url.port` is empty for a default port, so consult the raw authority — with any userinfo
+	// removed first, since that colon is not a port.
+	const authority = audience.slice(audience.indexOf('://') + 3).split(/[/?#]/)[0];
+	const hasExplicitPort = !!url.port || authority.slice(authority.lastIndexOf('@') + 1).includes(':');
+	if (hasExplicitPort && audience.endsWith('/')) return;
+
+	throw new ClientError(
+		`'audience' must be the exact string the CI client requests its token for, which includes an ` +
+			`explicit port and a trailing slash (for example 'https://my-instance.example.com:9925/'). ` +
+			`'${audience}' is missing ${!hasExplicitPort ? 'a port' : 'a trailing slash'}, and the match is ` +
+			`byte-for-byte, so the policy could never authenticate.`
+	);
+}
+
+function trustTable() {
+	const table = (databases as any).system?.[OIDC_TRUST_TABLE];
+	if (!table) {
+		throw new ClientError(
+			`OIDC trust policies are not initialized on this node (system.${OIDC_TRUST_TABLE} missing). ` +
+				`Run upgrade or restart the server to provision the table.`
+		);
+	}
+	return table;
+}
+
+/**
+ * Rebuild a plain record from a stored row's known attributes. Never spread rows — RecordObject
+ * prototype fields don't survive a spread reliably (see DESIGN.md).
+ */
+function toRecord(row: any, problem?: string): OidcTrustPolicy & Record<string, unknown> {
+	return {
+		id: row.id,
+		issuer: row.issuer,
+		audience: row.audience,
+		claims: row.claims ?? {},
+		user: row.user,
+		operations: row.operations ?? null,
+		// Reported as stored rather than coerced. `row.enabled !== false` would render the string
+		// 'false' — one of the shapes the exchange refuses — as `enabled: true`, telling the operator
+		// a dead trust is live. Absent still means enabled, which is the documented default.
+		enabled: row.enabled === undefined ? true : row.enabled,
+		// Present only on a row the exchange will refuse, so a listing says why the trust is dead
+		// instead of leaving a per-attempt log line as the only signal. Shape problems are set here;
+		// listOidcTrust adds the ones that depend on state outside the row (a missing or inactive user).
+		...(problem ? { invalid_reason: problem } : {}),
+		description: row.description ?? null,
+		updated_by: row.updated_by ?? null,
+		__createdtime__: row.__createdtime__,
+		__updatedtime__: row.__updatedtime__,
+	} as any;
+}
+
+/**
+ * The policy set is small and administrator-managed, so a scan beats maintaining an index — and
+ * sorting by id keeps both the listing and the exchange's match order deterministic rather than
+ * dependent on an index's iteration order.
+ */
+async function readPolicies(
+	includeDisabled: boolean,
+	issuer?: string,
+	forExchange = false
+): Promise<OidcTrustPolicy[]> {
+	const table = trustTable();
+	const policies: OidcTrustPolicy[] = [];
+	for await (const row of table.search([])) {
+		if (!includeDisabled && row.enabled === false) continue;
+		if (issuer !== undefined && row.issuer !== issuer) continue;
+		// Validated on BOTH paths, always against the RAW row — normalizing first is precisely what
+		// hides the shapes that fail open (see storedPolicyProblem). The two paths then differ in what
+		// they do with the answer: the exchange refuses the row, while a listing reports it. A listing
+		// that silently skipped a refused policy, or that showed it as healthy, would leave the
+		// operator's belief that the trust works corroborated by the very command they ran to check.
+		const problem = storedPolicyProblem(row);
+		if (forExchange) {
+			if (problem) {
+				logger.warn?.(`Ignoring trust policy '${row.id}': ${problem}`);
+				continue;
+			}
+		}
+		policies.push(toRecord(row, problem));
+	}
+	return policies.sort((a, b) => String(a.id).localeCompare(String(b.id)));
+}
+
+/**
+ * Why a stored row must not be honored, or undefined if it is usable.
+ *
+ * add_oidc_trust enforces all of this at write time, but a row can reach the table another way —
+ * replication from a node predating a check, a restored backup, a direct write to the system table —
+ * so the exchange re-runs the same validators rather than trusting that every row was validated when
+ * written. Two shapes in particular fail OPEN if merely normalized instead of rejected:
+ *
+ *   operations: 'deploy_component'  — a scalar rather than an array. hasOperationScope tests
+ *     Array.isArray, so the scope is silently dropped and the token is minted UNSCOPED, carrying the
+ *     policy user's entire role. A malformed narrowing must never widen.
+ *   enabled: 'false'                — a string. `row.enabled !== false` is true for it, so a policy
+ *     an operator meant to disable keeps minting tokens.
+ *
+ * Shares validateOperations and validateClaimConstraintShape with the add path deliberately: two
+ * implementations of "is this row valid" is how the write path and the read path drift apart.
+ */
+export function storedPolicyProblem(row: any): string | undefined {
+	if (row.enabled !== undefined && typeof row.enabled !== 'boolean') {
+		return `'enabled' is a ${typeof row.enabled}, not a boolean`;
+	}
+	if (row.operations != null) {
+		if (!Array.isArray(row.operations)) return `'operations' is a ${typeof row.operations}, not an array`;
+		const invalidOperation = validateOperations(row.operations);
+		if (invalidOperation != null) return `operations contains '${invalidOperation}', which is not a Harper operation`;
+	}
+	try {
+		validateClaimConstraintShape(row.claims);
+	} catch (error) {
+		return (error as Error).message;
+	}
+	return undefined;
+}
+
+/**
+ * The policies the exchange will consider, narrowed to one issuer.
+ *
+ * Filtered inside the scan rather than by the caller: the exchange is unauthenticated and reaches
+ * here having done nothing but `jwt.decode`, so an anonymous caller presenting any syntactically
+ * valid JWT would otherwise drive a `toRecord()` allocation for every stored policy before anything
+ * has been verified. The scan itself stays — the table is administrator-sized, and an index here
+ * would buy little (see readPolicies) — but non-matching rows now cost nothing beyond the compare.
+ *
+ * A missing table yields no policies rather than throwing. On a node where the upgrade directive has
+ * not run, trustTable()'s descriptive ClientError would surface to an anonymous caller as a 400 with
+ * a body unlike the uniform 401 every other rejection returns, which both leaks node state and
+ * breaks the single-message property. The SU-only add/list/drop handlers still get that error, where
+ * it is the useful thing to say.
+ */
+export function loadEnabledPolicies(issuer: string): Promise<OidcTrustPolicy[]> {
+	if (!(databases as any).system?.[OIDC_TRUST_TABLE]) return Promise.resolve([]);
+	return readPolicies(false, issuer, true);
+}
+
+/**
+ * Creates or replaces a trust policy.
+ *
+ * Replace rather than merge: a partial update to a claim set is how an over-broad policy gets
+ * created by accident, and the whole point of `claims` is that every constraint in it was written
+ * deliberately.
+ */
+export async function addOidcTrust(req: any) {
+	requireSuperUser(req);
+	validate(
+		validateBySchema(
+			req,
+			Joi.object({
+				id: POLICY_ID,
+				issuer: Joi.string().min(1).max(512).required(),
+				audience: Joi.string().min(1).max(512).required(),
+				claims: Joi.object().min(1).required(),
+				user: Joi.string().min(1).max(512).required(),
+				operations: Joi.array().items(Joi.string().min(1)).min(1).max(100).unique(),
+				// `.strict()` — Joi coerces by default, but validateBySchema keeps only `result.error`
+				// and discards the converted value, so `"false"` would validate cleanly and then be
+				// stored as the string it arrived as. `req.enabled !== false` is true for that string,
+				// which silently leaves a policy an operator meant to disable still minting tokens.
+				// A revocation control has to fail closed, so reject the string outright.
+				enabled: Joi.boolean().strict(),
+				description: Joi.string().allow('').max(1024),
+			}).unknown(true)
+		)
+	);
+
+	const issuer = normalizeIssuer(req.issuer);
+	// Issuer-specific rules live in the provider profile; an unregistered issuer gets the strict
+	// generic profile rather than a permissive default. Each throws ClientError naming the problem.
+	const profile = profileForIssuer(issuer);
+	// On the RAW audience, before the canonical-form check below. GitHub's shared-audience guard
+	// matches `https://github.com/<owner>`, and a canonicalized form of that would no longer match
+	// the regex — checking the other way round would silently disarm it.
+	profile.assertAudienceIsSpecific(req.audience);
+	assertAudienceIsCanonical(req.audience);
+	if (req.operations) assertOperationsAreKnown(req.operations);
+	validateClaimConstraintShape(req.claims);
+	profile.assertPolicyIsSpecific(req.claims);
+
+	// Resolve the target user now: a policy pointing at a user that does not exist would fail only at
+	// exchange time, in CI, with nothing to point at. Read the users cache directly rather than
+	// findAndValidateUser — with validatePassword false, that returns a bare `{ username }` for an
+	// unknown user instead of failing, so it cannot answer "does this user exist".
+	const users = await getUsersWithRolesCache();
+	const targetUser = users?.get(req.user);
+	if (!targetUser) {
+		throw new ClientError(`No such user '${req.user}'; create the user before granting it to a workflow`);
+	}
+	if (targetUser.active === false) {
+		throw new ClientError(`User '${req.user}' is inactive; a policy naming it could never authenticate`);
+	}
+
+	const table = trustTable();
+	await table.put({
+		id: req.id,
+		issuer,
+		audience: req.audience,
+		claims: req.claims,
+		user: req.user,
+		operations: req.operations ?? null,
+		enabled: req.enabled !== false,
+		description: req.description ?? null,
+		updated_by: req.hdb_user?.username ?? null,
+	});
+
+	const result: Record<string, unknown> = { message: `Successfully set OIDC trust policy '${req.id}'` };
+	// Not an error — an admin may genuinely want this — but a policy that hands super_user to a
+	// workflow deserves to be said out loud rather than discovered later.
+	if (targetUser.role?.permission?.super_user) {
+		result.warning =
+			`Policy '${req.id}' authenticates as '${req.user}', which is a super_user. Any run matching this ` +
+			`policy gains full administrative access; consider a user whose role grants only the operations CI needs.`;
+	}
+	return result;
+}
+
+export async function listOidcTrust(req: any) {
+	requireSuperUser(req);
+	const policies = await readPolicies(true);
+
+	// The exchange also refuses a well-formed row whose user has since been deleted or deactivated
+	// (tokenExchange resolves it before spending the token), with the same opaque 401 — so without
+	// this the listing would still say the trust is fine for the most mundane arrival of all: someone
+	// deletes or deactivates the CI user and every deploy starts failing.
+	//
+	// Annotated here rather than in readPolicies, and deliberately: this is one cache read for the
+	// whole listing on an SU-only path, where doing it per row in readPolicies would put a user lookup
+	// on the unauthenticated exchange path, which already resolves the user itself at the right moment.
+	// A shape problem already reported wins, since it is the more fundamental complaint.
+	const users = await getUsersWithRolesCache();
+	for (const policy of policies as any[]) {
+		if (policy.invalid_reason) continue;
+		const user = users?.get(policy.user);
+		if (!user) policy.invalid_reason = `names user '${policy.user}', which does not exist`;
+		else if (user.active === false) policy.invalid_reason = `names inactive user '${policy.user}'`;
+	}
+
+	return { policies };
+}
+
+export async function dropOidcTrust(req: any) {
+	requireSuperUser(req);
+	validate(validateBySchema(req, Joi.object({ id: POLICY_ID }).unknown(true)));
+
+	const table = trustTable();
+	const row = await table.get(req.id);
+	if (!row) {
+		throw new ClientError(`No OIDC trust policy found with id '${req.id}'`, HTTP_STATUS_CODES.NOT_FOUND);
+	}
+	await table.delete(req.id);
+	return { message: `Successfully dropped OIDC trust policy '${req.id}'` };
+}

package/security/authn/oidc/types.ts

@@ -0,0 +1,41 @@
+/**
+ * Types for OIDC trusted publishing (#2171).
+ */
+
+/** One accepted value, or a set of them. */
+export type ClaimConstraint = string | string[];
+
+/**
+ * A stored trust policy. Matching one lets an external CI run act as `user` without holding any
+ * Harper credential, so `claims` is validated at write time rather than trusted as written — see
+ * validateClaimConstraintShape (claims.ts) and the profile's assertPolicyIsSpecific for the
+ * structural requirements, and addOidcTrust for the rest.
+ */
+export interface OidcTrustPolicy {
+	id: string;
+	/** Expected `iss`, and the base for OIDC discovery. */
+	issuer: string;
+	/** Expected `aud`. Must identify this instance — see SHARED_DEFAULT_AUDIENCE. */
+	audience: string;
+	claims: Record<string, ClaimConstraint>;
+	/** The exchanged token authenticates as this user, whose role is the least-privilege boundary. */
+	user: string;
+	/**
+	 * Optional narrowing of that boundary, enforced on the **operations API and SQL** paths (the
+	 * verifyPerms / verifyPermsAST gate): the minted token may invoke only these operations, even
+	 * where the role allows more. Never widens — an operation the role forbids stays forbidden.
+	 *
+	 * NOT enforced on the application REST/GraphQL resource path, which authorizes through the
+	 * table-level checkPermission and does not consult this scope — so a scoped operation token still
+	 * carries the role's full CRUD there. Extending the scope to the resource path is a follow-up on
+	 * the same surface as the GraphQL-bypasses-ops-allowlist gap (CORE-3061); until then, scope a
+	 * policy's `user` to a role that is itself least-privilege for the data the token can reach.
+	 */
+	operations?: string[];
+	/** Defaults to true; false keeps the policy for reference without honoring it. */
+	enabled?: boolean;
+	description?: string;
+}
+
+/** A verified token's payload, plus the entries the profile's normalizeClaims derives. */
+export type TokenClaims = Record<string, unknown>;

package/security/certificateVerification/index.ts

@@ -27,10 +27,14 @@ import { extractCertificateChain, extractRevocationUrls, bufferToPem } from './v
 import { getCachedCertificateVerificationConfig } from './verificationConfig.ts';
 import { verifyOCSP } from './ocspVerification.ts';
 import { verifyCRL } from './crlVerification.ts';
-import type { PeerCertificate, CertificateVerificationResult } from './types.ts';
+import { resolveTrustedIssuer } from './trustedIssuers.ts';
+import type { PeerCertificate, CertificateVerificationResult, FailureMode } from './types.ts';
 
 const logger = loggerWithTag('cert-verification');
 
+const warnedUnresolvedLeaves = new Set<string>();
+const MAX_WARNED_LEAVES = 10_000;
+
 /**
  * Verify certificate revocation status using OCSP and/or CRL
  * @param peerCertificate - Peer certificate object from TLS connection
@@ -52,14 +56,32 @@ export async function verifyCertificate(
 		return { valid: true, status: 'disabled', method: 'disabled' };
 	}
 
+	// ahead of the chain check so an explicitly disabled control can never reject
+	if (config.crl.enabled === false && config.ocsp.enabled === false) {
+		logger.debug?.('Both CRL and OCSP disabled - verification disabled');
+		return { valid: true, status: 'disabled', method: 'disabled' };
+	}
+
 	// Extract certificate chain
 	const certChain = extractCertificateChain(peerCertificate);
 	logger.trace?.(`Certificate chain length: ${certChain.length}`);
 
-	// Check if we have sufficient chain for verification (need certificate and issuer)
-	if (certChain.length < 2 || !certChain[0].issuer) {
-		logger.debug?.('Certificate chain insufficient for revocation checking - need certificate and issuer');
-		return { valid: true, status: 'no-issuer-cert', method: 'disabled' };
+	if (certChain.length === 0) {
+		return unresolvedIssuerResult(config.failureMode, peerCertificate, 'no certificate data');
+	}
+	// Revocation checking needs the issuer. The socket omits it on every resumed TLS session and on
+	// Node 26.8.0/26.8.1 (nodejs/node#65579); recover it from the CA set that authorized the client.
+	if (!certChain[0].issuer) {
+		const issuer = resolveTrustedIssuer(certChain[0].cert, peerCertificate.fingerprint256);
+		if (!issuer) {
+			return unresolvedIssuerResult(
+				config.failureMode,
+				peerCertificate,
+				'issuer is neither in the presented chain nor among the configured certificate authorities'
+			);
+		}
+		logger.debug?.('Issuer certificate resolved from the configured certificate authorities');
+		certChain[0].issuer = issuer;
 	}
 
 	// Extract certificate revocation URLs in single parse operation
@@ -117,17 +139,36 @@ export async function verifyCertificate(
 		logger.debug?.('Skipping OCSP - no responder URLs in certificate');
 	}
 
-	// All methods tried or skipped - determine failure handling
-	// If both methods are explicitly disabled (not just unavailable), treat as disabled
-	if (config.crl.enabled === false && config.ocsp.enabled === false) {
-		logger.debug?.('Both CRL and OCSP disabled - verification disabled');
-		return { valid: true, status: 'disabled', method: 'disabled' };
-	}
-
-	// Methods are enabled but unavailable - apply failure mode
+	// All methods tried or skipped - apply failure mode
 	if (config.failureMode === 'fail-closed') {
 		return { valid: false, status: 'no-verification-available', method: 'disabled' };
 	}
 
 	return { valid: true, status: 'verification-unavailable-allowed', method: 'disabled' };
 }
+
+/**
+ * Revocation status cannot be established without the issuer, so the configured failure mode
+ * decides: refuse under fail-closed, allow under fail-open. Either way this is a security control
+ * not running, so it is logged at warn (once per certificate) rather than debug.
+ */
+function unresolvedIssuerResult(
+	failureMode: FailureMode | undefined,
+	peerCertificate: PeerCertificate,
+	reason: string
+): CertificateVerificationResult {
+	const valid = failureMode !== 'fail-closed';
+	const leafKey = peerCertificate.fingerprint256 ?? peerCertificate.subject?.CN ?? '';
+	if (!warnedUnresolvedLeaves.has(leafKey)) {
+		if (warnedUnresolvedLeaves.size >= MAX_WARNED_LEAVES) warnedUnresolvedLeaves.clear();
+		warnedUnresolvedLeaves.add(leafKey);
+		logger.warn?.(
+			`Cannot check revocation status for client certificate ${peerCertificate.subject?.CN ?? 'unknown'}: ${reason}; ${
+				valid ? 'allowing connection (fail-open)' : 'rejecting connection (fail-closed)'
+			}`
+		);
+	} else {
+		logger.debug?.(`Cannot check revocation status for ${peerCertificate.subject?.CN ?? 'unknown'}: ${reason}`);
+	}
+	return { valid, status: 'no-issuer-cert', method: 'disabled' };
+}

package/security/certificateVerification/trustedIssuers.ts

@@ -0,0 +1,76 @@
+/**
+ * Resolves a client certificate's issuer from Harper's own trusted certificate authorities.
+ *
+ * Node completes a peer chain from the trust store only through the listener's default TLS
+ * context; Harper's client CAs live on the SNI contexts built by createTLSSelector, so whenever the
+ * client-sent chain is unavailable (every resumed TLS session; Node 26.8.0/26.8.1 on every
+ * connection, nodejs/node#65579) getPeerCertificate(true) exposes the leaf alone. The CA set that
+ * authorized the connection is the same set published here, so the issuer is recoverable from it
+ * unless it is an intermediate the client sent but Harper does not trust directly.
+ */
+
+import { X509Certificate, createHash } from 'node:crypto';
+
+const PEM_CERTIFICATE_PATTERN =
+	/-----BEGIN (?:TRUSTED |X509 )?CERTIFICATE-----[\s\S]*?-----END (?:TRUSTED |X509 )?CERTIFICATE-----/g;
+const MAX_RESOLVED_LEAVES = 10_000;
+
+let trustedAuthorities: X509Certificate[] = [];
+let publishedAuthorityPems = '';
+let resolvedIssuers = new Map<string, Buffer | null>();
+
+/**
+ * Publish the current trusted authority set (PEM strings, each possibly a bundle of several
+ * certificates). Replaces the previous generation atomically and drops its resolution cache,
+ * unless the set is unchanged. Unparseable certificates are skipped so one bad record cannot
+ * disable resolution for the rest; this never throws, because it runs inside the TLS selector's
+ * publication step.
+ */
+export function publishTrustedAuthorities(authorityPems: Iterable<unknown>): void {
+	const pems = Array.from(authorityPems).filter((pem): pem is string => typeof pem === 'string');
+	const joined = pems.join('\n');
+	if (joined === publishedAuthorityPems) return;
+	publishedAuthorityPems = joined;
+	const parsed: X509Certificate[] = [];
+	for (const pem of pems) {
+		for (const block of pem.match(PEM_CERTIFICATE_PATTERN) ?? []) {
+			try {
+				parsed.push(new X509Certificate(block));
+			} catch {}
+		}
+	}
+	trustedAuthorities = parsed;
+	resolvedIssuers = new Map();
+}
+
+/**
+ * Find the trusted authority that issued `leafDer`: subject/AKI match plus a signature check, so a
+ * same-named authority with a different key never counts, and a certificate is never its own
+ * issuer. Returns the issuer's DER, or undefined.
+ */
+export function resolveTrustedIssuer(leafDer: Buffer, fingerprint256?: string): Buffer | undefined {
+	if (trustedAuthorities.length === 0) return undefined;
+	const key = fingerprint256 ?? createHash('sha256').update(leafDer).digest('hex');
+	const cached = resolvedIssuers.get(key);
+	if (cached !== undefined) return cached ?? undefined;
+
+	let issuer: Buffer | null = null;
+	try {
+		const leaf = new X509Certificate(leafDer);
+		for (const authority of trustedAuthorities) {
+			try {
+				if (
+					authority.fingerprint256 !== leaf.fingerprint256 &&
+					leaf.checkIssued(authority) &&
+					leaf.verify(authority.publicKey)
+				) {
+					issuer = authority.raw;
+					break;
+				}
+			} catch {}
+		}
+	} catch {}
+	if (resolvedIssuers.size >= MAX_RESOLVED_LEAVES) resolvedIssuers.clear();
+	resolvedIssuers.set(key, issuer);
+	return issuer ?? undefined;
+}

package/security/certificateVerification/types.ts

@@ -17,6 +17,7 @@ export interface PeerCertificate {
 		[key: string]: any;
 	};
 	raw?: Buffer;
+	fingerprint256?: string;
 	issuerCertificate?: PeerCertificate;
 }
 

package/security/credentialProvenance.ts

@@ -0,0 +1,47 @@
+/**
+ * Provenance for a credential minted from a workload identity exchange (#2171) rather than from a
+ * password.
+ *
+ * The exchange's whole guarantee is that CI holds nothing durable: a one-hour operation token, no
+ * refresh token, nothing on disk to leak. That guarantee is only as strong as the paths that turn
+ * one credential into another. `create_authentication_tokens` is such a path and does not look like
+ * one: it is in `NO_AUTH_OPERATIONS`, but `serverHandlers.js` special-cases it so a call with no
+ * username/password authenticates by Bearer token instead — so an exchanged token is accepted there
+ * as if it were a password, honors a caller-supplied `expires_in` verbatim, and returns a 30-day
+ * refresh token. That converts a minutes-long leak into a month-long one, which is the exact
+ * exposure this feature exists to remove.
+ *
+ * A scope (operationScope.ts) cannot carry this weight. A trust policy names `operations` only when
+ * the operator opts in, so the ordinary exchanged token is UNSCOPED and a scope check finds nothing
+ * to deny — the common case would sail through a scope-only guard. Provenance is therefore recorded
+ * independently of scope, on every exchanged token.
+ *
+ * Like the scope, it lives under two names depending on the carrier: the claim `workload_identity`
+ * on a JWT payload, and `fromWorkloadIdentity` on an in-memory principal (validateToken lifts the
+ * claim across). And like the scope, every path that produces a credential or a principal has to
+ * carry it forward — impersonation included, or a workload token launders its provenance by
+ * impersonating and then mints freely.
+ */
+
+/** The JWT claim name. Signed with the rest of the payload, so it cannot be stripped in transit. */
+export const WORKLOAD_IDENTITY_CLAIM = 'workload_identity';
+
+/** Stamps a token payload as workload-identity provenance. Returns the payload. */
+export function markTokenAsWorkloadIdentity<T extends object>(payload: T): T {
+	(payload as any)[WORKLOAD_IDENTITY_CLAIM] = true;
+	return payload;
+}
+
+/** Lifts the claim from a verified token onto a user principal. Returns the user. */
+export function attachWorkloadIdentityToUser<T extends object>(user: T, claim: unknown): T {
+	if (claim === true) (user as any).fromWorkloadIdentity = true;
+	return user;
+}
+
+/**
+ * True when this principal authenticated with a workload-identity token. Checked strictly against
+ * `true` so a forged string or object on a user record cannot widen it.
+ */
+export function isWorkloadIdentityPrincipal(user: unknown): boolean {
+	return (user as any)?.fromWorkloadIdentity === true;
+}

package/security/credentialRejection.ts

@@ -0,0 +1,22 @@
+import { ClientError } from '../utility/errors/hdbError.ts';
+
+// Explicit provenance prevents internal faults with a 4xx status from being deferred as rejected credentials.
+const CREDENTIAL_REJECTION = Symbol('harper.credentialRejection');
+
+export function markCredentialRejection<E extends object>(error: E): E {
+	Object.defineProperty(error, CREDENTIAL_REJECTION, {
+		value: true,
+		enumerable: false,
+		configurable: true,
+		writable: false,
+	});
+	return error;
+}
+
+export function credentialRejectionError(message: string, statusCode: number): ClientError {
+	return markCredentialRejection(new ClientError(message, statusCode));
+}
+
+export function isCredentialRejection(error: unknown): boolean {
+	return (error as Record<symbol, unknown> | null | undefined)?.[CREDENTIAL_REJECTION] === true;
+}