@starci/auth 0.5.0 → 0.6.0

package/dist/oidc/client.js

@@ -0,0 +1,119 @@
+import { OIDC_CLAIMS, OIDC_ERROR_CODES, OIDC_SUBJECT_MAX_LENGTH } from "../contracts/oidc.js";
+import { OidcError } from "./errors.js";
+import { isRecord, revealed, sameValue } from "./primitives.js";
+import { refreshOf } from "./refresh.js";
+import { rolesOf } from "./roles.js";
+const rejected = (cause) => new OidcError(OIDC_ERROR_CODES.Rejected, cause === undefined ? {} : { cause });
+/**
+ * The authorization code flow of one registered client: it builds the authorization address (S256 PKCE, nonce, state), exchanges a
+ * code once at the token endpoint and verifies the ID token (signature, issuer, audience = the client, expiry, nonce) before it answers
+ * an identity, and builds the RP-initiated logout address. It never logs a provider token; the refresh token a code exchange answers is for the
+ * server's own store, never for a browser.
+ */
+export class OidcClient {
+    #options;
+    #discovery;
+    #tokens;
+    constructor(options, discovery, tokens) {
+        this.#options = options;
+        this.#discovery = discovery;
+        this.#tokens = tokens;
+    }
+    /** The address the browser goes to for the registered code flow. */
+    async authorization(input) {
+        const client = this.#registration();
+        const metadata = await this.#discovery.get();
+        const url = new URL(metadata.authorizationEndpoint);
+        url.search = new URLSearchParams({
+            response_type: "code",
+            client_id: client.clientId,
+            redirect_uri: client.callbackUri,
+            scope: client.scope ?? "openid",
+            state: input.state,
+            nonce: input.nonce,
+            code_challenge: input.challenge,
+            code_challenge_method: "S256",
+            ...(input.prompt === undefined ? {} : { prompt: input.prompt }),
+            ...(input.idpHint === undefined ? {} : { kc_idp_hint: input.idpHint }),
+        }).toString();
+        return url.toString();
+    }
+    /** Exchanges a claimed code once, then verifies the ID token and answers the identity it asserts. */
+    async exchange(input) {
+        const client = this.#registration();
+        if (input.issuer !== undefined && input.issuer !== this.#options.issuer)
+            throw rejected();
+        const metadata = await this.#discovery.get();
+        const response = await this.#options.http
+            .request({
+            method: "POST",
+            url: metadata.tokenEndpoint,
+            timeoutMs: this.#options.timeoutMs,
+            form: {
+                grant_type: "authorization_code",
+                client_id: client.clientId,
+                ...(client.clientSecret === undefined ? {} : { client_secret: revealed(client.clientSecret) }),
+                redirect_uri: client.callbackUri,
+                code: input.code,
+                code_verifier: input.verifier,
+            },
+        })
+            .catch((cause) => {
+            throw new OidcError(OIDC_ERROR_CODES.Unavailable, { cause });
+        });
+        if (response.status >= 500)
+            throw new OidcError(OIDC_ERROR_CODES.Unavailable);
+        if (response.status !== 200 || !isRecord(response.body) || typeof response.body.id_token !== "string")
+            throw rejected();
+        const identity = await this.#identityOf(response.body.id_token, input.nonce);
+        const refresh = refreshOf(response.body, this.#options.clock.now());
+        return refresh === undefined ? identity : { ...identity, ...refresh };
+    }
+    /** The RP-initiated logout address of the registered client. */
+    async logout(input = {}) {
+        const client = this.#registration();
+        const { endSessionEndpoint } = await this.#discovery.get();
+        if (endSessionEndpoint === undefined)
+            throw rejected();
+        const url = new URL(endSessionEndpoint);
+        url.search = new URLSearchParams({
+            client_id: client.clientId,
+            post_logout_redirect_uri: client.postLogoutUri,
+            ...(input.idTokenHint === undefined ? {} : { id_token_hint: input.idTokenHint }),
+            ...(input.state === undefined ? {} : { state: input.state }),
+        }).toString();
+        return url.toString();
+    }
+    #registration() {
+        const client = this.#options.client;
+        if (client === undefined)
+            throw new OidcError(OIDC_ERROR_CODES.ConfigurationInvalid, { params: { key: "client" } });
+        return client;
+    }
+    async #identityOf(idToken, nonce) {
+        const client = this.#registration();
+        const verified = await this.#tokens.verify(idToken, { audience: [client.clientId], requiredClaims: [OIDC_CLAIMS.nonce] });
+        if (verified.kind === "refused")
+            throw rejected();
+        const claims = verified.value;
+        const received = claims[OIDC_CLAIMS.nonce];
+        if (typeof received !== "string" || !sameValue(received, nonce))
+            throw rejected();
+        const { sub, exp } = claims;
+        if (typeof sub !== "string" || sub === "" || sub.length > OIDC_SUBJECT_MAX_LENGTH || typeof exp !== "number" || !Number.isSafeInteger(exp))
+            throw rejected();
+        const roles = rolesOf(claims, { realm: this.#options.realmRoles, clients: this.#options.roleClients, claims: this.#options.roleClaims });
+        if (roles === undefined)
+            throw rejected();
+        const email = claims[OIDC_CLAIMS.email];
+        const sessionId = claims[OIDC_CLAIMS.sessionId];
+        return {
+            issuer: this.#options.issuer,
+            subject: sub,
+            roles,
+            ...(typeof email === "string" && email !== "" ? { email } : {}),
+            ...(typeof sessionId === "string" && sessionId !== "" ? { sessionId } : {}),
+            expiresAt: new Date(exp * 1000),
+        };
+    }
+}

package/dist/oidc/discovery.d.ts

@@ -0,0 +1,23 @@
+import type { ResolvedOidcOptions } from "./options.js";
+/** The endpoints of the discovery document the package uses, each validated against the issuer. */
+export interface OidcMetadata {
+    readonly issuer: string;
+    readonly authorizationEndpoint: string;
+    readonly tokenEndpoint: string;
+    readonly jwksUri: string;
+    /** Absent when the provider offers no RP-initiated logout. */
+    readonly endSessionEndpoint: string | undefined;
+    /** The RFC 7009 token revocation endpoint; absent when the provider advertises none. */
+    readonly revocationEndpoint: string | undefined;
+}
+/** The discovery address of an issuer. */
+export declare const discoveryUrl: (issuer: string) => string;
+/** Narrows a discovery document: its `issuer` is the configured issuer exactly, and every endpoint passes `endpointOf`. */
+export declare const readMetadata: (value: unknown, options: ResolvedOidcOptions) => OidcMetadata;
+/** Fetches and caches the discovery document of the issuer; concurrent callers share one request. */
+export declare class OidcDiscovery {
+    #private;
+    constructor(options: ResolvedOidcOptions);
+    /** The metadata: the cached document while it is fresh, else a new one. A provider that cannot be asked throws `Unavailable`; the cached document is never used past its life, so an outage never keeps stale endpoints. */
+    get(): Promise<OidcMetadata>;
+}

package/dist/oidc/discovery.js

@@ -0,0 +1,64 @@
+import { OIDC_ERROR_CODES } from "../contracts/oidc.js";
+import { OidcError } from "./errors.js";
+import { isAdmissibleUrl } from "./options.js";
+import { isRecord } from "./primitives.js";
+const DISCOVERY_PATH = "/.well-known/openid-configuration";
+/** The discovery address of an issuer. */
+export const discoveryUrl = (issuer) => `${issuer.replace(/\/$/u, "")}${DISCOVERY_PATH}`;
+const rejected = () => new OidcError(OIDC_ERROR_CODES.Rejected);
+/**
+ * An endpoint the provider advertises is trusted only on the issuer's own origin, over the admitted scheme, without credentials or a
+ * fragment: a discovery document cannot send the client secret or the browser to another host.
+ */
+const endpointOf = (value, options) => {
+    if (typeof value !== "string" || !isAdmissibleUrl(value, options.allowInsecureHttp))
+        throw rejected();
+    if (new URL(value).origin !== new URL(options.issuer).origin)
+        throw rejected();
+    return value;
+};
+/** Narrows a discovery document: its `issuer` is the configured issuer exactly, and every endpoint passes `endpointOf`. */
+export const readMetadata = (value, options) => {
+    if (!isRecord(value) || value.issuer !== options.issuer)
+        throw rejected();
+    return {
+        issuer: options.issuer,
+        authorizationEndpoint: endpointOf(value.authorization_endpoint, options),
+        tokenEndpoint: endpointOf(value.token_endpoint, options),
+        jwksUri: endpointOf(value.jwks_uri, options),
+        endSessionEndpoint: value.end_session_endpoint === undefined ? undefined : endpointOf(value.end_session_endpoint, options),
+        revocationEndpoint: value.revocation_endpoint === undefined ? undefined : endpointOf(value.revocation_endpoint, options),
+    };
+};
+/** Fetches and caches the discovery document of the issuer; concurrent callers share one request. */
+export class OidcDiscovery {
+    #options;
+    #held;
+    #pending;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** The metadata: the cached document while it is fresh, else a new one. A provider that cannot be asked throws `Unavailable`; the cached document is never used past its life, so an outage never keeps stale endpoints. */
+    async get() {
+        const now = this.#options.clock.now().getTime();
+        if (this.#held !== undefined && now - this.#held.at < this.#options.discoveryTtlMs)
+            return this.#held.metadata;
+        this.#pending ??= this.#fetch().finally(() => {
+            this.#pending = undefined;
+        });
+        return this.#pending;
+    }
+    async #fetch() {
+        const options = this.#options;
+        const response = await options.http
+            .request({ method: "GET", url: discoveryUrl(options.issuer), timeoutMs: options.timeoutMs })
+            .catch((cause) => {
+            throw new OidcError(OIDC_ERROR_CODES.Unavailable, { cause });
+        });
+        if (response.status !== 200)
+            throw new OidcError(OIDC_ERROR_CODES.Unavailable);
+        const metadata = readMetadata(response.body, options);
+        this.#held = { metadata, at: options.clock.now().getTime() };
+        return metadata;
+    }
+}

package/dist/oidc/errors.d.ts

@@ -0,0 +1,10 @@
+import { DomainError } from "@starci/common";
+import type { OidcErrorCode, OidcErrorKind } from "../contracts/oidc.js";
+/** The one error class the package throws: a stable code, the kind it travels as, the key a configuration error names and the cause, never provider prose or a token. */
+export declare class OidcError extends DomainError<OidcErrorCode> {
+    readonly kind: OidcErrorKind;
+    constructor(code: OidcErrorCode, options?: {
+        readonly cause?: unknown;
+        readonly params?: Readonly<Record<string, string>>;
+    });
+}

package/dist/oidc/errors.js

@@ -0,0 +1,10 @@
+import { DomainError } from "@starci/common";
+import { OIDC_ERROR_KINDS } from "../contracts/oidc.js";
+/** The one error class the package throws: a stable code, the kind it travels as, the key a configuration error names and the cause, never provider prose or a token. */
+export class OidcError extends DomainError {
+    kind;
+    constructor(code, options = {}) {
+        super({ code, params: options.params ?? {}, ...(options.cause === undefined ? {} : { cause: options.cause }) });
+        this.kind = OIDC_ERROR_KINDS[code];
+    }
+}

package/dist/oidc/grants.d.ts

@@ -0,0 +1,41 @@
+import type { OidcPrincipal } from "../contracts/oidc.js";
+import type { OidcDiscovery } from "./discovery.js";
+import type { ResolvedOidcOptions } from "./options.js";
+import type { OidcPrincipalVerifier } from "./verifier.js";
+/** What a grant at the token endpoint established: the verified principal and the refresh token of the provider session. The access token is verified here and dropped. */
+export interface OidcGrant {
+    /** The principal the access token stands for (subject, mapped roles, email, session). */
+    readonly principal: OidcPrincipal;
+    /** The account: the `sub` of the access token. */
+    readonly subject: string;
+    /** The roles the issuer granted, mapped by the registration. */
+    readonly roles: readonly string[];
+    /** The verified email, or null when the token has none. */
+    readonly email: string | null;
+    /** The refresh token of the provider session. It stays on the server. */
+    readonly refreshToken: string;
+    /** When the refresh token stops being accepted. */
+    readonly refreshExpiresAt: Date;
+}
+/**
+ * The server-side grants of the registered client at the provider's token endpoint: the resource owner password grant, the refresh
+ * token grant and the revocation of a refresh token. Every answer is checked by the registration's `PrincipalVerifier`, so the result
+ * carries the same verified principal a bearer token would, plus the refresh token and its expiry; the access token is never returned,
+ * so it can never reach a browser. Nothing here logs a password or a token.
+ */
+export declare class OidcTokenClient {
+    #private;
+    constructor(options: ResolvedOidcOptions, discovery: OidcDiscovery, verifier: OidcPrincipalVerifier);
+    /**
+     * Signs a person in with a username (or the email the realm accepts) and a password. A refusal of the credentials (`invalid_grant`: bad
+     * password, unknown or disabled account) throws `CredentialsRejected`; an outage throws `Unavailable`.
+     */
+    passwordGrant(username: string, password: string): Promise<OidcGrant>;
+    /** Trades a refresh token for a new session grant (the provider rotates the refresh token). A dead refresh token (`invalid_grant`) throws `CredentialsRejected`. */
+    refresh(refreshToken: string): Promise<OidcGrant>;
+    /**
+     * Ends the provider session of a refresh token. It asks the discovered `revocation_endpoint` (RFC 7009); a provider that advertises none
+     * is asked at its end-session endpoint with the refresh token. A token the provider no longer knows is already ended and is no error.
+     */
+    revoke(refreshToken: string): Promise<void>;
+}

package/dist/oidc/grants.js

@@ -0,0 +1,82 @@
+import { OIDC_ERROR_CODES } from "../contracts/oidc.js";
+import { OidcError } from "./errors.js";
+import { isRecord, revealed } from "./primitives.js";
+import { refreshOf } from "./refresh.js";
+import { errorCodeOf, send } from "./transport.js";
+const rejected = (cause) => new OidcError(OIDC_ERROR_CODES.Rejected, cause === undefined ? {} : { cause });
+/**
+ * The server-side grants of the registered client at the provider's token endpoint: the resource owner password grant, the refresh
+ * token grant and the revocation of a refresh token. Every answer is checked by the registration's `PrincipalVerifier`, so the result
+ * carries the same verified principal a bearer token would, plus the refresh token and its expiry; the access token is never returned,
+ * so it can never reach a browser. Nothing here logs a password or a token.
+ */
+export class OidcTokenClient {
+    #options;
+    #discovery;
+    #verifier;
+    constructor(options, discovery, verifier) {
+        this.#options = options;
+        this.#discovery = discovery;
+        this.#verifier = verifier;
+    }
+    /**
+     * Signs a person in with a username (or the email the realm accepts) and a password. A refusal of the credentials (`invalid_grant`: bad
+     * password, unknown or disabled account) throws `CredentialsRejected`; an outage throws `Unavailable`.
+     */
+    async passwordGrant(username, password) {
+        const client = this.#registration();
+        return this.#grant({ grant_type: "password", username, password, scope: client.scope ?? "openid" });
+    }
+    /** Trades a refresh token for a new session grant (the provider rotates the refresh token). A dead refresh token (`invalid_grant`) throws `CredentialsRejected`. */
+    async refresh(refreshToken) {
+        this.#registration();
+        return this.#grant({ grant_type: "refresh_token", refresh_token: refreshToken });
+    }
+    /**
+     * Ends the provider session of a refresh token. It asks the discovered `revocation_endpoint` (RFC 7009); a provider that advertises none
+     * is asked at its end-session endpoint with the refresh token. A token the provider no longer knows is already ended and is no error.
+     */
+    async revoke(refreshToken) {
+        const client = this.#registration();
+        const metadata = await this.#discovery.get();
+        const url = metadata.revocationEndpoint ?? metadata.endSessionEndpoint;
+        if (url === undefined)
+            throw rejected();
+        const credentials = { client_id: client.clientId, ...(client.clientSecret === undefined ? {} : { client_secret: revealed(client.clientSecret) }) };
+        const form = metadata.revocationEndpoint === undefined ? { ...credentials, refresh_token: refreshToken } : { ...credentials, token: refreshToken, token_type_hint: "refresh_token" };
+        const response = await send(this.#options, { method: "POST", url, form });
+        if (response.status >= 200 && response.status < 300)
+            return;
+        if (response.status === 400 && errorCodeOf(response.body) === "invalid_grant")
+            return;
+        throw rejected();
+    }
+    #registration() {
+        const client = this.#options.client;
+        if (client === undefined)
+            throw new OidcError(OIDC_ERROR_CODES.ConfigurationInvalid, { params: { key: "client" } });
+        return client;
+    }
+    async #grant(params) {
+        const client = this.#registration();
+        const { tokenEndpoint } = await this.#discovery.get();
+        const response = await send(this.#options, {
+            method: "POST",
+            url: tokenEndpoint,
+            form: { client_id: client.clientId, ...(client.clientSecret === undefined ? {} : { client_secret: revealed(client.clientSecret) }), ...params },
+        });
+        if (response.status !== 200)
+            throw errorCodeOf(response.body) === "invalid_grant" ? new OidcError(OIDC_ERROR_CODES.CredentialsRejected) : rejected();
+        const body = response.body;
+        if (!isRecord(body) || typeof body.access_token !== "string")
+            throw rejected();
+        const refresh = refreshOf(body, this.#options.clock.now());
+        if (refresh === undefined)
+            throw rejected();
+        const verified = await this.#verifier.verify(body.access_token);
+        if (verified.kind === "refused")
+            throw rejected();
+        const principal = verified.value;
+        return { principal, subject: principal.id, roles: principal.roles, email: principal.email ?? null, ...refresh };
+    }
+}

package/dist/oidc/index.d.ts

@@ -0,0 +1,35 @@
+export { OidcAdminClient, adminBaseOf } from "./admin.js";
+export type { OidcCreatedUser, OidcFoundUser, OidcNewUser } from "./admin.js";
+export { OidcBroker } from "./broker.js";
+export type { OidcBrokerSession, OidcSocialCallback, OidcSocialRequest } from "./broker.js";
+export { OidcClient } from "./client.js";
+export type { OidcAuthorization, OidcExchange, OidcExchangeResult, OidcLogout } from "./client.js";
+export { OidcDiscovery, discoveryUrl, readMetadata } from "./discovery.js";
+export type { OidcMetadata } from "./discovery.js";
+export { OidcError } from "./errors.js";
+export { OidcTokenClient } from "./grants.js";
+export type { OidcGrant } from "./grants.js";
+export { OidcKeys, readKeySet } from "./jwks.js";
+export type { OidcKeySet } from "./jwks.js";
+export { OidcModule, MODULE_OPTIONS_TOKEN as OIDC_OPTIONS } from "./oidc.module.js";
+export type { OidcModuleExtras, OidcRegisterAsyncOptions, OidcRegisterOptions } from "./oidc.module.js";
+export { createOidc } from "./oidc.js";
+export type { Oidc } from "./oidc.js";
+export { OIDC_ADMIN_CLIENT, OIDC_BROKER, OIDC_CLIENT, OIDC_DISCOVERY, OIDC_KEYS, OIDC_PRINCIPAL_VERIFIER, OIDC_REGISTRATION, OIDC_TOKEN_CLIENT, OIDC_TOKEN_VERIFIER } from "./oidc.tokens.js";
+export { fetchHttp, isAdmissibleUrl, resolveOptions } from "./options.js";
+export type { OidcClientRegistration, OidcHttp, OidcHttpRequest, OidcHttpResponse, OidcJwksOptions, OidcOptions, OidcRoleMapping, ResolvedOidcOptions, } from "./options.js";
+export { isRecord, pkceChallenge, randomReference, sameValue, systemClock } from "./primitives.js";
+export type { OidcClock, Revealable, SecretInput } from "./primitives.js";
+export { refreshOf } from "./refresh.js";
+export type { OidcRefresh } from "./refresh.js";
+export { rolesOf } from "./roles.js";
+export type { RoleSources } from "./roles.js";
+export { OidcTokenVerifier } from "./tokens.js";
+export type { TokenExpectations } from "./tokens.js";
+export { OidcPrincipalVerifier, principalOf, refuseSessions } from "./verifier.js";
+export type { PrincipalRules } from "./verifier.js";
+export type { OidcKeySource } from "./jwks.js";
+export { GITHUB_ACTIONS_CLAIMS, GITHUB_ACTIONS_ISSUER, GITHUB_ACTIONS_JWKS_URI, GOOGLE_ISSUER, GOOGLE_ISSUER_ALIAS, GOOGLE_JWKS_URI, createIssuerVerifier, githubActionsIssuer, googleIssuer, keycloakIssuer, keycloakIssuerUrl, keycloakOptions, mapped, unmapped, } from "./issuers/index.js";
+export type { GitHubActionsIssuerOptions, GitHubActionsRun, GoogleIdentity, GoogleIssuerOptions, IssuerEndpoints, IssuerKeys, IssuerMapping, IssuerPreset, IssuerVerifier, IssuerVerifierOptions, KeycloakIssuerOptions, } from "./issuers/index.js";
+export { OIDC_ACCESS_TOKEN_INVALID, OIDC_ALGORITHMS, OIDC_CLAIMS, OIDC_CLIENT_CODES, OIDC_DEFAULT_ALGORITHMS, OIDC_ERROR_CODES, OIDC_ERROR_KINDS, OIDC_ROLE, OIDC_ROLE_BOUNDS, OIDC_SUBJECT_MAX_LENGTH, } from "../contracts/oidc.js";
+export type { OidcAlgorithm, OidcClientOutcome, OidcErrorCode, OidcErrorKind, OidcFailureKind, OidcIdentity, OidcOutcome, OidcPrincipal, OidcRefusal, OidcRefusalReason, OidcSessionUser, PrincipalVerifier, } from "../contracts/oidc.js";

package/dist/oidc/index.js

@@ -0,0 +1,18 @@
+export { OidcAdminClient, adminBaseOf } from "./admin.js";
+export { OidcBroker } from "./broker.js";
+export { OidcClient } from "./client.js";
+export { OidcDiscovery, discoveryUrl, readMetadata } from "./discovery.js";
+export { OidcError } from "./errors.js";
+export { OidcTokenClient } from "./grants.js";
+export { OidcKeys, readKeySet } from "./jwks.js";
+export { OidcModule, MODULE_OPTIONS_TOKEN as OIDC_OPTIONS } from "./oidc.module.js";
+export { createOidc } from "./oidc.js";
+export { OIDC_ADMIN_CLIENT, OIDC_BROKER, OIDC_CLIENT, OIDC_DISCOVERY, OIDC_KEYS, OIDC_PRINCIPAL_VERIFIER, OIDC_REGISTRATION, OIDC_TOKEN_CLIENT, OIDC_TOKEN_VERIFIER } from "./oidc.tokens.js";
+export { fetchHttp, isAdmissibleUrl, resolveOptions } from "./options.js";
+export { isRecord, pkceChallenge, randomReference, sameValue, systemClock } from "./primitives.js";
+export { refreshOf } from "./refresh.js";
+export { rolesOf } from "./roles.js";
+export { OidcTokenVerifier } from "./tokens.js";
+export { OidcPrincipalVerifier, principalOf, refuseSessions } from "./verifier.js";
+export { GITHUB_ACTIONS_CLAIMS, GITHUB_ACTIONS_ISSUER, GITHUB_ACTIONS_JWKS_URI, GOOGLE_ISSUER, GOOGLE_ISSUER_ALIAS, GOOGLE_JWKS_URI, createIssuerVerifier, githubActionsIssuer, googleIssuer, keycloakIssuer, keycloakIssuerUrl, keycloakOptions, mapped, unmapped, } from "./issuers/index.js";
+export { OIDC_ACCESS_TOKEN_INVALID, OIDC_ALGORITHMS, OIDC_CLAIMS, OIDC_CLIENT_CODES, OIDC_DEFAULT_ALGORITHMS, OIDC_ERROR_CODES, OIDC_ERROR_KINDS, OIDC_ROLE, OIDC_ROLE_BOUNDS, OIDC_SUBJECT_MAX_LENGTH, } from "../contracts/oidc.js";

package/dist/oidc/issuers/github-actions.d.ts

@@ -0,0 +1,54 @@
+import type { IssuerEndpoints, IssuerPreset } from "./issuer.js";
+/** The issuer of GitHub Actions OIDC tokens. */
+export declare const GITHUB_ACTIONS_ISSUER = "https://token.actions.githubusercontent.com";
+/** Its signing keys. */
+export declare const GITHUB_ACTIONS_JWKS_URI = "https://token.actions.githubusercontent.com/.well-known/jwks";
+/** The claims a CI run token must carry beyond `sub` and `exp`. */
+export declare const GITHUB_ACTIONS_CLAIMS: readonly ["repository", "repository_id", "workflow", "workflow_ref", "ref", "run_id", "sha"];
+/** Which runs the app trusts: always one repository, optionally pinned further. */
+export interface GitHubActionsIssuerOptions {
+    /** The audience the workflow asked for (`core.getIDToken(audience)`): required, so a token minted for another service never passes. */
+    readonly audience: string | readonly string[];
+    /** The repository the run belongs to (`owner/name`), compared without case as GitHub names are. */
+    readonly repository: string;
+    /** The numeric repository id: pins the repository across a rename or a deleted-and-recreated name. */
+    readonly repositoryId?: string | undefined;
+    /** The workflow files admitted (`.github/workflows/ci.yml`), matched against the path of `workflow_ref`; any when absent. */
+    readonly workflows?: readonly string[] | undefined;
+    /** The refs admitted (`refs/heads/main`, `refs/tags/v1.0.0`); any when absent. */
+    readonly refs?: readonly string[] | undefined;
+    /** A test double's addresses. */
+    readonly endpoints?: IssuerEndpoints | undefined;
+}
+/** What a verified CI run token attests. */
+export interface GitHubActionsRun {
+    /** The `sub` claim (`repo:owner/name:ref:refs/heads/main`). */
+    readonly subject: string;
+    readonly repository: string;
+    readonly repositoryId: string;
+    /** The owner part of `repository`. */
+    readonly repositoryOwner: string;
+    /** The workflow name. */
+    readonly workflow: string;
+    /** `owner/name/.github/workflows/<file>@<ref>`. */
+    readonly workflowRef: string;
+    /** The workflow file path of `workflowRef` (`.github/workflows/ci.yml`). */
+    readonly workflowPath: string;
+    readonly ref: string;
+    readonly sha: string;
+    readonly runId: string;
+    /** The attempt of the run (`1`), when the token names one. */
+    readonly runAttempt: string | null;
+    /** Who started the run, when the token names them. */
+    readonly actor: string | null;
+    /** What started it (`push`, `pull_request`), when the token names it. */
+    readonly eventName: string | null;
+    /** The deployment environment, when the job has one. */
+    readonly environment: string | null;
+}
+/**
+ * The GitHub Actions preset: the OIDC token a workflow run mints (`permissions: id-token: write`), RS256 against GitHub's pinned key set,
+ * for an audience the app names, from one repository, optionally pinned to its id, its workflow files and its refs. A CI attestation port
+ * (a run proving which repository, workflow, ref and commit it is) composes this inside `integrations/keycloak`.
+ */
+export declare const githubActionsIssuer: (options: GitHubActionsIssuerOptions) => IssuerPreset<GitHubActionsRun>;

package/dist/oidc/issuers/github-actions.js

@@ -0,0 +1,84 @@
+import { OIDC_ERROR_CODES } from "../../contracts/oidc.js";
+import { OidcError } from "../errors.js";
+import { mapped, unmapped } from "./issuer.js";
+/** The issuer of GitHub Actions OIDC tokens. */
+export const GITHUB_ACTIONS_ISSUER = "https://token.actions.githubusercontent.com";
+/** Its signing keys. */
+export const GITHUB_ACTIONS_JWKS_URI = "https://token.actions.githubusercontent.com/.well-known/jwks";
+/** The claims a CI run token must carry beyond `sub` and `exp`. */
+export const GITHUB_ACTIONS_CLAIMS = ["repository", "repository_id", "workflow", "workflow_ref", "ref", "run_id", "sha"];
+const text = (value) => (typeof value === "string" && value !== "" ? value : null);
+/** `owner/name/.github/workflows/ci.yml@refs/heads/main` -> `.github/workflows/ci.yml` for the given repository, else null. */
+const workflowPathOf = (workflowRef, repository) => {
+    const at = workflowRef.lastIndexOf("@");
+    const path = at < 0 ? workflowRef : workflowRef.slice(0, at);
+    const prefix = `${repository}/`;
+    return path.toLowerCase().startsWith(prefix.toLowerCase()) && path.length > prefix.length ? path.slice(prefix.length) : null;
+};
+const RUN_ID = /^\d{1,20}$/u;
+/** The run a verified token's claims attest, or a refusal: a claim of the wrong shape is `claims`, one the policy does not admit is `policy`. */
+const runOf = (claims, options) => {
+    const subject = text(claims.sub);
+    const repository = text(claims.repository);
+    const repositoryId = text(claims.repository_id);
+    const workflow = text(claims.workflow);
+    const workflowRef = text(claims.workflow_ref);
+    const ref = text(claims.ref);
+    const sha = text(claims.sha);
+    const runId = text(claims.run_id);
+    if (subject === null || repository === null || repositoryId === null || workflow === null || workflowRef === null || ref === null || sha === null || runId === null || !RUN_ID.test(runId))
+        return unmapped("claims");
+    const wanted = options.repository.toLowerCase();
+    if (repository.toLowerCase() !== wanted)
+        return unmapped("policy", "repository");
+    if (!subject.toLowerCase().startsWith(`repo:${wanted}:`))
+        return unmapped("policy", "sub");
+    if (options.repositoryId !== undefined && repositoryId !== options.repositoryId)
+        return unmapped("policy", "repository_id");
+    const workflowPath = workflowPathOf(workflowRef, repository);
+    if (workflowPath === null)
+        return unmapped("policy", "workflow_ref");
+    if (options.workflows !== undefined && !options.workflows.includes(workflowPath))
+        return unmapped("policy", "workflow_ref");
+    if (options.refs !== undefined && !options.refs.includes(ref))
+        return unmapped("policy", "ref");
+    return mapped({
+        subject,
+        repository,
+        repositoryId,
+        repositoryOwner: repository.slice(0, repository.indexOf("/")),
+        workflow,
+        workflowRef,
+        workflowPath,
+        ref,
+        sha,
+        runId,
+        runAttempt: text(claims.run_attempt),
+        actor: text(claims.actor),
+        eventName: text(claims.event_name),
+        environment: text(claims.environment),
+    });
+};
+const REPOSITORY = /^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/u;
+/**
+ * The GitHub Actions preset: the OIDC token a workflow run mints (`permissions: id-token: write`), RS256 against GitHub's pinned key set,
+ * for an audience the app names, from one repository, optionally pinned to its id, its workflow files and its refs. A CI attestation port
+ * (a run proving which repository, workflow, ref and commit it is) composes this inside `integrations/keycloak`.
+ */
+export const githubActionsIssuer = (options) => {
+    const audience = typeof options.audience === "string" ? [options.audience] : options.audience;
+    if (audience.length === 0 || audience.some((entry) => entry === ""))
+        throw new OidcError(OIDC_ERROR_CODES.ConfigurationInvalid, { params: { key: "audience" } });
+    if (!REPOSITORY.test(options.repository))
+        throw new OidcError(OIDC_ERROR_CODES.ConfigurationInvalid, { params: { key: "repository" } });
+    return {
+        name: "github-actions",
+        issuer: options.endpoints?.issuer ?? GITHUB_ACTIONS_ISSUER,
+        issuerAliases: [],
+        keys: { kind: "jwks", uri: options.endpoints?.jwksUri ?? GITHUB_ACTIONS_JWKS_URI },
+        algorithms: ["RS256"],
+        audience,
+        requiredClaims: [...GITHUB_ACTIONS_CLAIMS],
+        identityOf: (claims) => runOf(claims, options),
+    };
+};

package/dist/oidc/issuers/google.d.ts

@@ -0,0 +1,30 @@
+import type { GoogleProfile } from "../../server/ports.js";
+import type { IssuerEndpoints, IssuerPreset } from "./issuer.js";
+/** Google's issuer, as its discovery document names it. */
+export declare const GOOGLE_ISSUER = "https://accounts.google.com";
+/** The other spelling Google puts in `iss`. */
+export declare const GOOGLE_ISSUER_ALIAS = "accounts.google.com";
+/** Google's signing keys. */
+export declare const GOOGLE_JWKS_URI = "https://www.googleapis.com/oauth2/v3/certs";
+/** What a Google ID token must say. */
+export interface GoogleIssuerOptions {
+    /** The app's OAuth client id(s): the `aud` of its ID tokens. */
+    readonly clientId: string | readonly string[];
+    /** When set, the Workspace domain the account must belong to (the `hd` claim). */
+    readonly hostedDomain?: string | undefined;
+    /** Refuse a token whose address Google has not verified (true). */
+    readonly requireVerifiedEmail?: boolean | undefined;
+    /** A test double's addresses. */
+    readonly endpoints?: IssuerEndpoints | undefined;
+}
+/** The person a Google ID token stands for: the profile the passport flow gives, with the Workspace domain. */
+export interface GoogleIdentity extends GoogleProfile {
+    /** The Workspace domain (`hd`), or null for a consumer account. */
+    readonly hostedDomain: string | null;
+}
+/**
+ * The Google preset: ID tokens of Google sign-in (One Tap, the Identity Services button, a mobile client), RS256 against Google's pinned key
+ * set, issued for the app's client id. It maps to the same profile the lite Google flow gives the authenticator, so one `signInWithGoogle`
+ * serves both.
+ */
+export declare const googleIssuer: (options: GoogleIssuerOptions) => IssuerPreset<GoogleIdentity>;

package/dist/oidc/issuers/google.js

@@ -0,0 +1,39 @@
+import { mapped, unmapped } from "./issuer.js";
+/** Google's issuer, as its discovery document names it. */
+export const GOOGLE_ISSUER = "https://accounts.google.com";
+/** The other spelling Google puts in `iss`. */
+export const GOOGLE_ISSUER_ALIAS = "accounts.google.com";
+/** Google's signing keys. */
+export const GOOGLE_JWKS_URI = "https://www.googleapis.com/oauth2/v3/certs";
+const text = (value) => (typeof value === "string" && value !== "" ? value : null);
+/**
+ * The Google preset: ID tokens of Google sign-in (One Tap, the Identity Services button, a mobile client), RS256 against Google's pinned key
+ * set, issued for the app's client id. It maps to the same profile the lite Google flow gives the authenticator, so one `signInWithGoogle`
+ * serves both.
+ */
+export const googleIssuer = (options) => {
+    const audience = typeof options.clientId === "string" ? [options.clientId] : options.clientId;
+    const verifiedOnly = options.requireVerifiedEmail ?? true;
+    return {
+        name: "google",
+        issuer: options.endpoints?.issuer ?? GOOGLE_ISSUER,
+        issuerAliases: options.endpoints === undefined ? [GOOGLE_ISSUER_ALIAS] : [],
+        keys: { kind: "jwks", uri: options.endpoints?.jwksUri ?? GOOGLE_JWKS_URI },
+        algorithms: ["RS256"],
+        audience,
+        requiredClaims: ["iat"],
+        identityOf: (claims) => {
+            const subject = text(claims.sub);
+            if (subject === null)
+                return unmapped("claims", "sub");
+            const verified = claims.email_verified === true || claims.email_verified === "true";
+            const email = text(claims.email);
+            if (verifiedOnly && (email === null || !verified))
+                return unmapped("policy", "email_verified");
+            const hostedDomain = text(claims.hd);
+            if (options.hostedDomain !== undefined && hostedDomain !== options.hostedDomain)
+                return unmapped("policy", "hd");
+            return mapped({ subject, email, emailVerified: verified, name: text(claims.name), picture: text(claims.picture), hostedDomain });
+        },
+    };
+};

package/dist/oidc/issuers/index.d.ts

@@ -0,0 +1,8 @@
+export { createIssuerVerifier, mapped, unmapped } from "./issuer.js";
+export type { IssuerEndpoints, IssuerKeys, IssuerMapping, IssuerPreset, IssuerVerifier, IssuerVerifierOptions } from "./issuer.js";
+export { keycloakIssuer, keycloakIssuerUrl, keycloakOptions } from "./keycloak.js";
+export type { KeycloakIssuerOptions } from "./keycloak.js";
+export { GOOGLE_ISSUER, GOOGLE_ISSUER_ALIAS, GOOGLE_JWKS_URI, googleIssuer } from "./google.js";
+export type { GoogleIdentity, GoogleIssuerOptions } from "./google.js";
+export { GITHUB_ACTIONS_CLAIMS, GITHUB_ACTIONS_ISSUER, GITHUB_ACTIONS_JWKS_URI, githubActionsIssuer } from "./github-actions.js";
+export type { GitHubActionsIssuerOptions, GitHubActionsRun } from "./github-actions.js";

package/dist/oidc/issuers/index.js

@@ -0,0 +1,4 @@
+export { createIssuerVerifier, mapped, unmapped } from "./issuer.js";
+export { keycloakIssuer, keycloakIssuerUrl, keycloakOptions } from "./keycloak.js";
+export { GOOGLE_ISSUER, GOOGLE_ISSUER_ALIAS, GOOGLE_JWKS_URI, googleIssuer } from "./google.js";
+export { GITHUB_ACTIONS_CLAIMS, GITHUB_ACTIONS_ISSUER, GITHUB_ACTIONS_JWKS_URI, githubActionsIssuer } from "./github-actions.js";