284 lines
11 KiB
TypeScript
284 lines
11 KiB
TypeScript
/**
|
|
* `0pt/auth/zitadel.ts` -- self-contained Zitadel (OIDC) Bearer JWT
|
|
* verification for 0pt.
|
|
*
|
|
* ==========================================================================
|
|
* Wave 2 foundational hardening: REAL cryptographic verification that closes
|
|
* the "no signature verification at all" hole (0pt's API layer historically
|
|
* trusted an X-Tenant-Id header and NEVER verified the Bearer token). This
|
|
* mirrors the canonical implementation already shipped on the n0d/aud0/api0/
|
|
* inf0 hardening branches. It is intentionally self-contained (no dependency
|
|
* on @siax/capability-registry, which is not consumable cross-repo) and
|
|
* depends only on `jose` + the platform's global `fetch`.
|
|
*
|
|
* ISSUER / JWKS DISCOVERY
|
|
* ----------------------
|
|
* The fleet IdP is Zitadel at ZITADEL_ISSUER (default
|
|
* https://id-customers.siax.io). Signing keys are resolved by:
|
|
* 1. Fetching `<issuer>/.well-known/openid-configuration` and reading its
|
|
* `jwks_uri` (the spec-correct OIDC discovery path).
|
|
* 2. Falling back to `<issuer>/oauth/v2/keys` (Zitadel's well-known JWKS
|
|
* endpoint) if discovery is unavailable.
|
|
* The resolved JWKS is wrapped in jose's `createRemoteJWKSet`, which caches
|
|
* keys and refreshes on an unknown `kid`; the resolver is additionally cached
|
|
* per-issuer for the process lifetime.
|
|
*
|
|
* TENANT CLAIM DERIVATION (documented precedence)
|
|
* -----------------------------------------------
|
|
* `deriveTenantId` maps a verified token to a SIAX tenant id with this
|
|
* precedence (overridable via ZITADEL_TENANT_CLAIM, which -- when set and
|
|
* present on the token -- wins outright):
|
|
* 1. `urn:zitadel:iam:org:id` -- Zitadel's standard
|
|
* organization-id claim;
|
|
* 0pt's tenant boundary
|
|
* maps 1:1 to a Zitadel org.
|
|
* 2. `urn:zitadel:iam:user:resourceowner:id` -- the user's resource-owner
|
|
* org id (present on some
|
|
* token profiles).
|
|
* 3. `tenant_id` -- an explicit custom claim,
|
|
* if a Zitadel action/mapper
|
|
* injects the SIAX tenant
|
|
* slug directly.
|
|
* 4. `tenant` -- a looser custom fallback.
|
|
* A signed-but-tenantless token is not usable here and fails verification.
|
|
*/
|
|
|
|
import {
|
|
createRemoteJWKSet,
|
|
decodeJwt,
|
|
jwtVerify,
|
|
type JWTPayload,
|
|
type JWTVerifyGetKey,
|
|
} from 'jose';
|
|
import { normalizeZitadelClaims, ZitadelClaimError } from '@siax/auth-zitadel';
|
|
|
|
/** Default fleet Zitadel issuer (OIDC). Overridable via ZITADEL_ISSUER. */
|
|
export const DEFAULT_ZITADEL_ISSUER = 'https://id-customers.siax.io';
|
|
|
|
/** Central Keycloak (SIAX Portal) trust; additive, unset keeps legacy behaviour. */
|
|
export function keycloakIssuer(): string | undefined {
|
|
const raw = process.env.KEYCLOAK_ISSUER?.trim().replace(/\/+$/, '');
|
|
return raw && raw.length > 0 ? raw : undefined;
|
|
}
|
|
|
|
export function keycloakAudiences(): string[] {
|
|
const raw = process.env.KEYCLOAK_EXPECTED_AUDIENCE?.trim();
|
|
if (!raw) return ['account'];
|
|
const list = raw.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
|
|
return list.length > 0 ? list : ['account'];
|
|
}
|
|
|
|
export function keycloakAuthorizedParty(): string | undefined {
|
|
const raw = process.env.KEYCLOAK_AUTHORIZED_PARTY?.trim();
|
|
return raw && raw.length > 0 ? raw : undefined;
|
|
}
|
|
|
|
function tokenIssuerUnsafe(token: string): string | undefined {
|
|
try {
|
|
const iss = decodeJwt(token).iss;
|
|
return typeof iss === 'string' ? iss : undefined;
|
|
} catch {
|
|
return undefined;
|
|
}
|
|
}
|
|
|
|
/** Standard + custom claim paths tenant derivation reads, in precedence order. */
|
|
export const ZITADEL_ORG_ID_CLAIM = 'urn:zitadel:iam:org:id';
|
|
export const ZITADEL_RESOURCEOWNER_CLAIM = 'urn:zitadel:iam:user:resourceowner:id';
|
|
export const TENANT_ID_CLAIM = 'tenant_id';
|
|
export const TENANT_CLAIM = 'tenant';
|
|
|
|
/** Ordered claim keys checked by {@link deriveTenantId} (after any override). */
|
|
export const TENANT_CLAIM_PRECEDENCE = [
|
|
ZITADEL_ORG_ID_CLAIM,
|
|
ZITADEL_RESOURCEOWNER_CLAIM,
|
|
TENANT_ID_CLAIM,
|
|
TENANT_CLAIM,
|
|
] as const;
|
|
|
|
/** Resolve the configured issuer, trimming and falling back to the default. */
|
|
export function zitadelIssuer(): string {
|
|
const fromEnv = process.env.ZITADEL_ISSUER?.trim();
|
|
return fromEnv && fromEnv.length > 0 ? fromEnv : DEFAULT_ZITADEL_ISSUER;
|
|
}
|
|
|
|
/** The env-configured tenant-claim override, if any (ZITADEL_TENANT_CLAIM). */
|
|
export function tenantClaimOverride(): string | undefined {
|
|
const v = process.env.ZITADEL_TENANT_CLAIM?.trim();
|
|
return v && v.length > 0 ? v : undefined;
|
|
}
|
|
|
|
/** A verified caller principal derived from a valid Zitadel access/ID token. */
|
|
export interface VerifiedPrincipal {
|
|
/** The token subject (`sub`) -- the authenticated actor id. */
|
|
sub: string;
|
|
/** The SIAX tenant id derived from the token (see deriveTenantId). */
|
|
tenantId: string;
|
|
/** The full verified JWT payload, for any additional downstream claims. */
|
|
claims: JWTPayload;
|
|
}
|
|
|
|
/** Thrown by {@link verifyBearer} on any verification/derivation failure. */
|
|
export class BearerVerificationError extends Error {
|
|
readonly reason: string;
|
|
readonly cause?: unknown;
|
|
constructor(reason: string, cause?: unknown) {
|
|
super(reason);
|
|
this.name = 'BearerVerificationError';
|
|
this.reason = reason;
|
|
this.cause = cause;
|
|
}
|
|
}
|
|
|
|
function claimAsString(claims: JWTPayload, key: string): string | undefined {
|
|
const v = claims[key];
|
|
return typeof v === 'string' && v.length > 0 ? v : undefined;
|
|
}
|
|
|
|
/**
|
|
* Map a verified JWT payload to a SIAX tenant id (documented precedence above).
|
|
* @param override an explicit claim key to try first (ZITADEL_TENANT_CLAIM).
|
|
*/
|
|
export function deriveTenantId(claims: JWTPayload, override = tenantClaimOverride()): string | undefined {
|
|
if (override) {
|
|
const fromOverride = claimAsString(claims, override);
|
|
if (fromOverride) return fromOverride;
|
|
}
|
|
for (const key of TENANT_CLAIM_PRECEDENCE) {
|
|
const v = claimAsString(claims, key);
|
|
if (v) return v;
|
|
}
|
|
return undefined;
|
|
}
|
|
|
|
// --- JWKS resolution --------------------------------------------------------
|
|
const jwksCache = new Map<string, JWTVerifyGetKey>();
|
|
// Test seam: an injected resolver bypasses remote discovery entirely.
|
|
let keyResolverOverride: JWTVerifyGetKey | undefined;
|
|
|
|
/**
|
|
* TEST SEAM: inject a JWKS resolver (e.g. jose `createLocalJWKSet`) so unit
|
|
* tests can verify locally-signed tokens without any network access. Pass
|
|
* `undefined` to clear.
|
|
*/
|
|
export function __setKeyResolverForTests(resolver: JWTVerifyGetKey | undefined): void {
|
|
keyResolverOverride = resolver;
|
|
}
|
|
|
|
/** TEST SEAM: clear the per-issuer remote-JWKS cache. */
|
|
export function __resetJwksCache(): void {
|
|
jwksCache.clear();
|
|
}
|
|
|
|
function stripTrailingSlash(url: string): string {
|
|
return url.replace(/\/+$/, '');
|
|
}
|
|
|
|
async function resolveJwksUri(issuer: string): Promise<string> {
|
|
const base = stripTrailingSlash(issuer);
|
|
const wellKnown = `${base}/.well-known/openid-configuration`;
|
|
try {
|
|
const res = await fetch(wellKnown);
|
|
if (res.ok) {
|
|
const cfg = (await res.json()) as { jwks_uri?: unknown };
|
|
if (typeof cfg.jwks_uri === 'string' && cfg.jwks_uri.length > 0) {
|
|
return cfg.jwks_uri;
|
|
}
|
|
}
|
|
} catch {
|
|
// fall through to the Zitadel default keys endpoint
|
|
}
|
|
return `${base}/oauth/v2/keys`;
|
|
}
|
|
|
|
async function getRemoteJwks(issuer: string): Promise<JWTVerifyGetKey> {
|
|
const cached = jwksCache.get(issuer);
|
|
if (cached) return cached;
|
|
const uri = await resolveJwksUri(issuer);
|
|
const resolver = createRemoteJWKSet(new URL(uri));
|
|
jwksCache.set(issuer, resolver);
|
|
return resolver;
|
|
}
|
|
|
|
export interface VerifyBearerOptions {
|
|
/** Override the issuer (default: {@link zitadelIssuer}). */
|
|
issuer?: string;
|
|
/** Override the key resolver (test seam; default: remote JWKS for issuer). */
|
|
keyResolver?: JWTVerifyGetKey;
|
|
/** Override the tenant-claim key (default: {@link tenantClaimOverride}). */
|
|
tenantClaim?: string;
|
|
}
|
|
|
|
/**
|
|
* Verify a raw Bearer token string against Zitadel: checks the RS/ES
|
|
* signature (via JWKS), the `iss` claim, and `exp`/`nbf` (jose enforces
|
|
* expiry automatically), then derives the tenant id. Returns a
|
|
* {@link VerifiedPrincipal} or throws {@link BearerVerificationError}.
|
|
*/
|
|
export async function verifyBearer(
|
|
token: string,
|
|
opts: VerifyBearerOptions = {},
|
|
): Promise<VerifiedPrincipal> {
|
|
// Central Keycloak (SIAX Portal) user tokens, routed by issuer.
|
|
const kcIssuer = keycloakIssuer();
|
|
if (kcIssuer !== undefined && tokenIssuerUnsafe(token) === kcIssuer) {
|
|
const resolver = opts.keyResolver ?? keyResolverOverride ?? (await getRemoteJwks(kcIssuer));
|
|
let payload: JWTPayload;
|
|
try {
|
|
({ payload } = await jwtVerify(token, resolver, {
|
|
issuer: kcIssuer,
|
|
audience: keycloakAudiences(),
|
|
}));
|
|
} catch (err) {
|
|
throw new BearerVerificationError('keycloak_token_verification_failed', err);
|
|
}
|
|
const azp = typeof payload.azp === 'string' ? payload.azp : '';
|
|
const expectedAzp = keycloakAuthorizedParty();
|
|
if (expectedAzp !== undefined && azp !== expectedAzp) {
|
|
throw new BearerVerificationError('keycloak_azp_mismatch');
|
|
}
|
|
const sub = typeof payload.sub === 'string' ? payload.sub : undefined;
|
|
if (!sub) throw new BearerVerificationError('token_missing_sub');
|
|
const tenantId = deriveTenantId(payload, opts.tenantClaim ?? tenantClaimOverride());
|
|
if (!tenantId) throw new BearerVerificationError('token_missing_tenant_claim');
|
|
return { sub, tenantId, claims: payload };
|
|
}
|
|
|
|
const issuer = opts.issuer ?? zitadelIssuer();
|
|
const resolver = opts.keyResolver ?? keyResolverOverride ?? (await getRemoteJwks(issuer));
|
|
|
|
let payload: JWTPayload;
|
|
try {
|
|
const result = await jwtVerify(token, resolver, { issuer });
|
|
payload = result.payload;
|
|
} catch (err) {
|
|
throw new BearerVerificationError('token_verification_failed', err);
|
|
}
|
|
|
|
try {
|
|
const identity = normalizeZitadelClaims(payload, {
|
|
source: 'jwt',
|
|
tenantClaim: opts.tenantClaim ?? tenantClaimOverride(),
|
|
});
|
|
return {
|
|
sub: identity.principal.subject,
|
|
tenantId: identity.tenant.tenantId,
|
|
claims: payload,
|
|
};
|
|
} catch (err) {
|
|
if (err instanceof ZitadelClaimError) {
|
|
if (/sub/i.test(err.reason)) {
|
|
throw new BearerVerificationError('token_missing_sub');
|
|
}
|
|
if (/tenant/i.test(err.reason)) {
|
|
throw new BearerVerificationError('token_missing_tenant_claim');
|
|
}
|
|
if (/aud/i.test(err.reason)) {
|
|
throw new BearerVerificationError('token_invalid_audience');
|
|
}
|
|
throw new BearerVerificationError('token_verification_failed', err);
|
|
}
|
|
throw err;
|
|
}
|
|
}
|