@dnsid-ai/oidc 0.20.1

package/dist/index.d.cts

@@ -0,0 +1,386 @@
+import { JWTPayload } from 'jose';
+import { KeyProvider, DnsIdJWK, SigningIdentityManager, IdentityResolver, VerificationOptions, TLSCertificate, VerifiedDomain } from '@dnsid-ai/protocol';
+
+/** Tunable OIDC policy for an {@link OIDCProfile}. All members are optional; defaults noted per member. */
+interface OIDCProfileConfig {
+    /** Scope requested when a token exchange does not specify one. Defaults to 'openid'. */
+    defaultScope?: string;
+    /** Lifetime of minted client assertions, in seconds. Defaults to 300. */
+    assertionLifetime?: number;
+    /** Upper bound on any requested assertion lifetime, in seconds. Defaults to 900. */
+    maxAssertionLifetime?: number;
+    /** Clock skew tolerated when validating token timestamps, in seconds. Defaults to 30. */
+    clockSkew?: number;
+    /** Timeout for discovery, JWKS, and token-endpoint requests, in milliseconds. Defaults to 10000. */
+    fetchTimeoutMs?: number;
+    /** Exact issuer URLs `verifyOIDCToken()` accepts. When absent or empty, verification always fails. */
+    allowedIssuers?: string[];
+    /** JWS algorithms accepted on inbound OIDC tokens. Defaults to ['RS256']. */
+    allowedTokenAlgorithms?: string[];
+    /** Permit plain-HTTP loopback issuers (localhost, 127.x, ::1) for local testing. Defaults to false. */
+    allowHttpLoopbackIssuer?: boolean;
+}
+/** Constructor options for {@link OIDCProfile}. */
+interface OIDCProfileOptions {
+    /** Agent FQDN; becomes the iss/sub/fqdn claims of minted assertions. */
+    domain: string;
+    /** Provider used to sign client assertions. Omit for a verification-only profile. */
+    keyProvider?: KeyProvider;
+    /** Resolver used by `verifyOIDCToken()` to verify token subjects as DNSid identity records. */
+    identityResolver?: IdentityResolver;
+    /** Custom fetch replaces the SSRF-safe Node default; inject only trusted/test transports with equivalent DNS safety. */
+    fetch?: typeof globalThis.fetch;
+    /** OIDC policy overrides; see {@link OIDCProfileConfig}. */
+    oidc?: OIDCProfileConfig;
+}
+/** Options for minting a JWT bearer client assertion. */
+interface OIDCAssertionOptions {
+    /** OIDC issuer the assertion is addressed to; becomes the aud claim. */
+    issuer: string;
+    /** Assertion lifetime in seconds; overrides the configured default, capped by maxAssertionLifetime. */
+    expiry?: number;
+    /** Extra claims to embed. Must not override reserved claims (iss, sub, aud, iat, exp, jti, fqdn). */
+    additionalClaims?: Record<string, unknown>;
+}
+/**
+ * The subset of an OIDC discovery document (`.well-known/openid-configuration`)
+ * this package relies on. Additional members are preserved as-is.
+ */
+interface OIDCDiscoveryDocument {
+    issuer: string;
+    token_endpoint: string;
+    jwks_uri: string;
+    [key: string]: unknown;
+}
+/** Options for `OIDCProfile.exchangeOIDCToken()` and `getOIDCToken()`. */
+interface OIDCTokenExchangeOptions {
+    /** Exact OIDC issuer URL to exchange against. */
+    issuer: string;
+    /** Audience (aud) requested for the access token. */
+    audience: string;
+    /** Space-delimited scope; defaults to the configured defaultScope, then 'openid'. */
+    scope?: string;
+    /** Pre-minted client assertion to present; its aud must exactly match the issuer. Minted fresh when absent. */
+    assertion?: string;
+}
+/** A successful token-endpoint response, normalized to camelCase members. */
+interface OIDCTokenResponse {
+    /** The issued access token. */
+    accessToken: string;
+    /** ID token, when the issuer returned one. */
+    idToken?: string;
+    /** Token type as reported by the issuer; always Bearer (case preserved). */
+    tokenType: string;
+    /** Token lifetime in seconds, when the issuer provided one. */
+    expiresIn?: number;
+    /** Scope actually granted, when the issuer reported it. */
+    scope?: string;
+    /** Issuer the token was obtained from. */
+    issuer?: string;
+    /** Token endpoint the exchange was performed against. */
+    tokenEndpoint?: string;
+    /** Raw JSON body of the token response. */
+    raw: unknown;
+}
+/**
+ * A private JWK used to sign client assertions without a full key provider.
+ * Must carry the private `d` member; keep it server-side only.
+ */
+interface OIDCPrivateJWK extends Omit<DnsIdJWK, 'kid'> {
+    kty: string;
+    /** Private key material (base64url). */
+    d: string;
+    /** Key id published on the derived public key; defaults to the RFC 7638 thumbprint. */
+    kid?: string;
+}
+/**
+ * Selects how the token endpoint is located. Exactly one mode applies:
+ * `issuer` (discovery at the issuer root), `serverUrl` (discovery relative to a
+ * base URL, token endpoint at `serverUrl` + '/token'), or `tokenEndpoint`
+ * (explicit endpoint; requires `issuer`, must share its origin, skips discovery).
+ */
+interface OIDCTokenEndpointOptions {
+    /** Exact HTTPS issuer root URL — no path, query, fragment, or trailing slash. Mutually exclusive with serverUrl. */
+    issuer?: string;
+    /** Base server URL used to derive the discovery document and token endpoint. Mutually exclusive with issuer. */
+    serverUrl?: string;
+    /** Explicit discovery document URL; only valid alongside issuer or serverUrl. */
+    discoveryUrl?: string;
+    /** Explicit token endpoint URL; requires issuer, must share its origin, and bypasses discovery. */
+    tokenEndpoint?: string;
+}
+/** Constructor options for {@link OIDCTokenMinter}. */
+interface OIDCTokenMinterOptions extends OIDCTokenEndpointOptions {
+    /** Agent FQDN; becomes the iss/sub/fqdn claims of minted assertions. */
+    domain: string;
+    /** Provider of the agent's operational key, used to sign client assertions. */
+    keyProvider: KeyProvider;
+    /** Custom fetch replaces the SSRF-safe Node default; inject only trusted/test transports with equivalent DNS safety. */
+    fetch?: typeof globalThis.fetch;
+    /** Scope used when a mint call does not specify one. Defaults to 'openid'. */
+    defaultScope?: string;
+    /** Lifetime of minted client assertions, in seconds. Defaults to 300. */
+    assertionLifetime?: number;
+    /** Upper bound on any requested assertion lifetime, in seconds. Defaults to 900. */
+    maxAssertionLifetime?: number;
+    /** Timeout for discovery and token-endpoint requests, in milliseconds. Defaults to 10000. */
+    timeoutMs?: number;
+    /** Permit plain-HTTP loopback issuers (localhost, 127.x, ::1) for local testing. Defaults to false. */
+    allowHttpLoopbackIssuer?: boolean;
+}
+/** Options for {@link createOIDCTokenMinter}: provide exactly one of keyProvider or privateJwk. */
+interface CreateOIDCTokenMinterOptions extends Omit<OIDCTokenMinterOptions, 'keyProvider'> {
+    /** Provider of the agent's operational key. Mutually exclusive with privateJwk. */
+    keyProvider?: KeyProvider;
+    /** Raw private JWK to sign with, wrapped in an in-memory provider. Mutually exclusive with keyProvider. */
+    privateJwk?: OIDCPrivateJWK;
+}
+/** Per-call options for `OIDCTokenMinter.mintToken()`. Endpoint members override the minter's defaults. */
+interface OIDCTokenMintOptions extends OIDCTokenEndpointOptions {
+    /** Audience (aud) requested for the access token. */
+    audience: string;
+    /** Space-delimited scope string. Mutually exclusive with scopes. */
+    scope?: string;
+    /** Individual scope values, joined with spaces. Mutually exclusive with scope. */
+    scopes?: readonly string[];
+    /** Extra claims for the client assertion. Must not override reserved claims (iss, sub, aud, iat, exp, jti, fqdn). */
+    additionalAssertionClaims?: Record<string, unknown>;
+}
+/** Combined options for the one-shot {@link mintOIDCToken}. */
+type MintOIDCTokenOptions = CreateOIDCTokenMinterOptions & OIDCTokenMintOptions;
+/** Options for `OIDCProfile.verifyOIDCToken()`. */
+interface VerifyOIDCTokenOptions extends VerificationOptions {
+    /** Exact issuer URL the token must have been issued by; must appear in the profile's allowedIssuers. */
+    issuer: string;
+    /** Audience the token must be addressed to (exact match). */
+    audience: string;
+    /** Set false to skip verifying the token subject as a DNSid identity record. Defaults to true. */
+    verifyDnsidSubject?: boolean;
+    peerCert?: TLSCertificate;
+}
+/** Result of a successful `OIDCProfile.verifyOIDCToken()` call. */
+interface VerifiedOIDCSubject {
+    /** Issuer that signed the token. */
+    issuer: string;
+    /** Token subject — the agent FQDN for DNSid-federated tokens. */
+    subject: string;
+    /** Audience the token was verified against. */
+    audience: string;
+    /** DNSid verification result for the subject; absent when verifyDnsidSubject is false. */
+    verifiedDomain?: VerifiedDomain;
+    /** The signature-verified JWT claims. */
+    claims: JWTPayload;
+}
+/**
+ * OAuth 2.0 error returned by a token endpoint (e.g. invalid_grant), carrying
+ * the raw `error` and `error_description` members from the response body.
+ */
+declare class OAuthError extends Error {
+    /** The RFC 6749 error code, when the endpoint provided one. */
+    readonly error?: string;
+    /** Human-readable error description, when the endpoint provided one. */
+    readonly errorDescription?: string;
+    constructor(error?: string, errorDescription?: string);
+}
+/**
+ * Mints OIDC access tokens for a DNSid agent via the RFC 7523 JWT bearer
+ * grant: signs a client assertion with the agent's operational key, then
+ * exchanges it at the issuer's token endpoint.
+ *
+ * Server-side only — requires the agent's private operational key. Prefer a
+ * long-lived minter over repeated {@link mintOIDCToken} calls when minting
+ * more than once against the same issuer.
+ */
+declare class OIDCTokenMinter {
+    private readonly domain;
+    private readonly keyProvider;
+    private readonly fetch;
+    private readonly defaultEndpointOptions;
+    private readonly defaultScope?;
+    private readonly assertionLifetime?;
+    private readonly maxAssertionLifetime?;
+    private readonly timeoutMs;
+    private readonly allowHttpLoopbackIssuer;
+    /**
+     * @throws ArgumentError if domain is not a valid agent FQDN, the endpoint
+     *   options mix modes (see {@link OIDCTokenEndpointOptions}), or timeoutMs
+     *   is not a positive number.
+     */
+    constructor(opts: OIDCTokenMinterOptions);
+    /**
+     * Mints a signed JWT bearer client assertion for the given issuer
+     * (iss/sub/fqdn = agent domain, aud = issuer, fresh jti).
+     *
+     * @throws ArgumentError if the issuer URL is invalid, the expiry is not
+     *   positive or exceeds the maximum lifetime, or additionalClaims override
+     *   a reserved claim.
+     * @throws ValidationError if the operational signing key is unsupported for JWS.
+     * @throws VerificationError (SignatureInvalid) if the produced signature does
+     *   not verify against the active operational key.
+     */
+    createAssertion(opts: OIDCAssertionOptions): Promise<string>;
+    /**
+     * Resolves the token endpoint (per the configured or per-call endpoint mode),
+     * mints a fresh assertion, and performs the JWT bearer token exchange.
+     *
+     * @returns The normalized token response.
+     * @throws ArgumentError if audience is missing or the options are inconsistent.
+     * @throws VerificationError if discovery or transport fails, the target
+     *   resolves to an unsafe address, or the response is malformed.
+     * @throws OAuthError if the token endpoint returns an OAuth error response.
+     */
+    mintToken(opts: OIDCTokenMintOptions): Promise<OIDCTokenResponse>;
+}
+/**
+ * Creates an {@link OIDCTokenMinter}, resolving the signing key from either a
+ * KeyProvider or a raw private JWK.
+ *
+ * @throws ArgumentError if neither or both of keyProvider/privateJwk are
+ *   given, the private JWK is invalid, or the minter options are invalid.
+ */
+declare function createOIDCTokenMinter(opts: CreateOIDCTokenMinterOptions): Promise<OIDCTokenMinter>;
+/**
+ * One-shot convenience: creates a minter and mints a single OIDC access token
+ * via the JWT bearer grant. Server-side only — never mint tokens in
+ * browser/client code. See `OIDCTokenMinter.mintToken()` for thrown errors.
+ *
+ * @example
+ * ```ts
+ * import { LocalKeyProvider } from '@dnsid-ai/sdk/node';
+ * import { mintOIDCToken } from '@dnsid-ai/oidc';
+ *
+ * const keyProvider = await LocalKeyProvider.load('.dnsid/keys.json', true);
+ * const token = await mintOIDCToken({
+ *   domain: 'agent.example.com',
+ *   keyProvider,
+ *   issuer: 'https://issuer.example.com',
+ *   audience: 'https://api.example.com',
+ *   scopes: ['openid', 'dnsid'],
+ * });
+ * console.log(token.accessToken);
+ * ```
+ */
+declare function mintOIDCToken(opts: MintOIDCTokenOptions): Promise<OIDCTokenResponse>;
+/**
+ * Wraps a raw private JWK in an in-memory KeyProvider suitable for signing
+ * OIDC assertions. Derives the public key, kid (RFC 7638 thumbprint), and alg
+ * when absent. The provider is signing-only: key generation, activation, and
+ * supersession are not supported.
+ *
+ * @throws ArgumentError if the JWK is not an object with a non-empty d member.
+ * @throws ValidationError if the key type/curve is unsupported for signing.
+ */
+declare function createOIDCKeyProviderFromJWK(privateJwk: OIDCPrivateJWK): Promise<KeyProvider>;
+/**
+ * DNSid OIDC federation profile for a single agent: mints client assertions,
+ * exchanges them for access tokens, and verifies inbound OIDC tokens back to
+ * DNSid identity records.
+ *
+ * Token minting requires the agent's private operational key — keep it
+ * server-side; never construct a profile in browser/client code.
+ */
+declare class OIDCProfile {
+    /** Builds a profile sharing an identity manager's domain, operational key provider, and identity resolver. */
+    static fromIdentityManager(identityManager: SigningIdentityManager, oidc?: OIDCProfileConfig): OIDCProfile;
+    private readonly domain;
+    private readonly keyProvider;
+    private readonly identityResolver?;
+    private readonly fetch;
+    private readonly config;
+    /** @throws ArgumentError if domain is not a valid agent FQDN. */
+    constructor(opts: OIDCProfileOptions);
+    /**
+     * Mints a signed JWT bearer client assertion for the given issuer
+     * (iss/sub/fqdn = agent domain, aud = issuer, fresh jti).
+     *
+     * @throws ArgumentError if the issuer URL is invalid, the expiry is not
+     *   positive or exceeds the maximum lifetime, or additionalClaims override
+     *   a reserved claim.
+     * @throws ValidationError if the operational signing key is unsupported for JWS.
+     * @throws VerificationError (SignatureInvalid) if the produced signature does
+     *   not verify against the active operational key.
+     */
+    createOIDCAssertion(opts: OIDCAssertionOptions): Promise<string>;
+    /**
+     * Fetches and validates the issuer's discovery document. The document's
+     * issuer must match exactly, and token_endpoint/jwks_uri must share the
+     * issuer's origin.
+     *
+     * @throws ArgumentError if the issuer is not an exact HTTPS URL.
+     * @throws VerificationError if the fetch fails, redirects, or the document is invalid.
+     */
+    discoverOIDCIssuer(issuer: string, options?: VerificationOptions): Promise<OIDCDiscoveryDocument>;
+    /**
+     * Discovers the issuer and performs the RFC 7523 JWT bearer exchange. When
+     * `assertion` is supplied it is presented as-is (its aud must exactly match
+     * the discovered issuer); otherwise a fresh assertion is minted.
+     *
+     * @returns The normalized token response.
+     * @throws ArgumentError if audience is missing or a supplied assertion is
+     *   not a valid JWT addressed to the issuer.
+     * @throws VerificationError if discovery or transport fails, or the response is malformed.
+     * @throws OAuthError if the token endpoint returns an OAuth error response.
+     */
+    exchangeOIDCToken(opts: OIDCTokenExchangeOptions): Promise<OIDCTokenResponse>;
+    /** Like {@link OIDCProfile.exchangeOIDCToken} but always mints a fresh assertion, ignoring any supplied one. */
+    getOIDCToken(opts: OIDCTokenExchangeOptions): Promise<OIDCTokenResponse>;
+    /**
+     * Verifies an OIDC token end-to-end: issuer allow-list, exact audience
+     * match, header and claim hygiene, signature against the issuer's published
+     * JWKS (restricted to allowedTokenAlgorithms), and timestamp checks with the
+     * configured clock skew. Unless `verifyDnsidSubject` is false, the token
+     * subject is then verified as a DNSid identity record via the profile's
+     * identityResolver.
+     *
+     * @returns The verified subject, claims, and (unless skipped) the DNSid
+     *   verification result for the subject domain.
+     * @throws ArgumentError if the issuer URL is invalid or audience is missing.
+     * @throws VerificationError with a VerificationCode (RecordInvalid,
+     *   SignatureInvalid, or TLSError) identifying the first check that failed —
+     *   including when the issuer is not in allowedIssuers, or when subject
+     *   verification is requested without an identityResolver.
+     */
+    verifyOIDCToken(token: string, opts: VerifyOIDCTokenOptions): Promise<VerifiedOIDCSubject>;
+    private verifyTokenWithinBudget;
+}
+/**
+ * Creates an {@link OIDCProfile}.
+ *
+ * @throws ArgumentError if domain is not a valid agent FQDN.
+ * @example
+ * ```ts
+ * import { LocalKeyProvider } from '@dnsid-ai/sdk/node';
+ * import { createOIDCProfile } from '@dnsid-ai/oidc';
+ *
+ * const profile = createOIDCProfile({
+ *   domain: 'agent.example.com',
+ *   keyProvider: await LocalKeyProvider.load('.dnsid/keys.json', true),
+ *   oidc: { allowedIssuers: ['https://issuer.example.com'] },
+ * });
+ * const token = await profile.getOIDCToken({
+ *   issuer: 'https://issuer.example.com',
+ *   audience: 'https://api.example.com',
+ * });
+ * ```
+ */
+declare function createOIDCProfile(opts: OIDCProfileOptions): OIDCProfile;
+/**
+ * Validates that an issuer is an exact absolute URL — no query, fragment, or
+ * trailing slash — using HTTPS (or plain-HTTP loopback when explicitly allowed).
+ *
+ * @returns The validated issuer string, unchanged.
+ * @throws ArgumentError if the issuer does not meet these requirements.
+ */
+declare function validateExactOIDCIssuer(issuer: string, allowHttpLoopbackIssuer?: boolean): string;
+/**
+ * Decodes a JWT's claims WITHOUT verifying its signature. Use only for
+ * inspection or logging — never for authorization decisions; use
+ * `OIDCProfile.verifyOIDCToken()` for those.
+ *
+ * @returns The decoded claims object.
+ * @throws VerificationError (RecordInvalid) if the token is not a decodable
+ *   JWT whose payload is a JSON object.
+ */
+declare function decodeOIDCClaims(token: string): Record<string, unknown>;
+
+export { type CreateOIDCTokenMinterOptions, type MintOIDCTokenOptions, OAuthError, type OIDCAssertionOptions, type OIDCDiscoveryDocument, type OIDCPrivateJWK, OIDCProfile, type OIDCProfileConfig, type OIDCProfileOptions, type OIDCTokenEndpointOptions, type OIDCTokenExchangeOptions, type OIDCTokenMintOptions, OIDCTokenMinter, type OIDCTokenMinterOptions, type OIDCTokenResponse, type VerifiedOIDCSubject, type VerifyOIDCTokenOptions, createOIDCKeyProviderFromJWK, createOIDCProfile, createOIDCTokenMinter, decodeOIDCClaims, mintOIDCToken, validateExactOIDCIssuer };