@ixo/credentials-kit 0.0.0-stage → 0.1.0

package/dist/oid4vci.d.ts

@@ -0,0 +1,428 @@
+import { DidResolver } from './did.js';
+import { CredentialsKitError } from './index.js';
+import { FetchLike, HostPolicy } from './did.js';
+import { Signer, Ed25519PublicJwk, Ed25519JwsAlg } from './jose.js';
+import { PRE_AUTHORIZED_CODE_GRANT } from './profile.js';
+import { VerifyIssuedCredentialOptions, VerifiedPresentation } from './verify.js';
+import './util-DOTEZgTt.js';
+import './display.js';
+
+/**
+ * `@ixo/credentials-kit/oid4vci` — OpenID for Verifiable Credential Issuance 1.0, pre-authorized
+ * code flow only, `dc+sd-jwt` only, `jwt` key proofs (EdDSA, key named by a DID URL `kid`).
+ *
+ * Wallet flow (`redeemOffer`):
+ *   1. issuer metadata  GET <host>/.well-known/openid-credential-issuer[<path>]      (§12.2.2)
+ *   2. AS metadata      GET <host>/.well-known/oauth-authorization-server[<path>]    (RFC 8414 §3;
+ *      the AS is the credential issuer unless `authorization_servers` says otherwise, §12.2.4)
+ *   3. token            POST token_endpoint, form: grant_type=urn:ietf:params:oauth:grant-type:
+ *                       pre-authorized_code & pre-authorized_code=… [& tx_code=…]   (§6.1)
+ *   4. nonce            POST nonce_endpoint → { c_nonce }                             (§7)
+ *   5. credential       POST credential_endpoint, Bearer, JSON { credential_configuration_id
+ *                       (or credential_identifier), proofs: { jwt: [ proof ] } }      (§8.2)
+ *                       → 200 { credentials: [{ credential }], notification_id? }
+ *                       | 202 { transaction_id, interval }                           (§8.3)
+ *   6. deferred         POST deferred_credential_endpoint { transaction_id }          (§9)
+ *   7. notification     POST notification_endpoint { notification_id, event }        (§11)
+ *
+ * Proof JWT (Appendix F.1): header { typ: 'openid4vci-proof+jwt', alg: 'EdDSA' (or 'Ed25519'
+ * when that is the only one the issuer lists), kid: <DID URL> } (never `jwk` or `x5c`), payload
+ * { aud: <credential issuer identifier>, iat, nonce: c_nonce } (no `iss`: anonymous
+ * pre-authorized access). The wallet refuses an offer whose configuration does not list
+ * `did:<method of the holder DID>` in `cryptographic_binding_methods_supported` (when present).
+ *
+ * The wallet checks every credential it receives with `verifyIssuedCredential` before returning
+ * it (RFC 9901 §7.2; opt out with `verify: false`).
+ */
+
+interface Display {
+    name: string;
+    locale?: string;
+    description?: string;
+    logo?: {
+        uri: string;
+        alt_text?: string;
+    };
+    background_color?: string;
+    text_color?: string;
+}
+interface ClaimDescription {
+    path: (string | number | null)[];
+    mandatory?: boolean;
+    display?: {
+        name?: string;
+        locale?: string;
+    }[];
+}
+interface CredentialConfiguration {
+    format: 'dc+sd-jwt';
+    vct: string;
+    scope?: string;
+    cryptographic_binding_methods_supported?: string[];
+    credential_signing_alg_values_supported?: string[];
+    proof_types_supported?: Record<string, {
+        proof_signing_alg_values_supported: string[];
+    }>;
+    credential_metadata?: {
+        display?: Display[];
+        claims?: ClaimDescription[];
+    };
+    [name: string]: unknown;
+}
+interface CredentialIssuerMetadata {
+    credential_issuer: string;
+    authorization_servers?: string[];
+    credential_endpoint: string;
+    nonce_endpoint?: string;
+    deferred_credential_endpoint?: string;
+    notification_endpoint?: string;
+    display?: Display[];
+    credential_configurations_supported: Record<string, CredentialConfiguration>;
+    [name: string]: unknown;
+}
+/** RFC 8414 metadata, as much of it as the pre-authorized code flow needs. */
+interface AuthorizationServerMetadata {
+    issuer: string;
+    token_endpoint: string;
+    grant_types_supported?: string[];
+    token_endpoint_auth_methods_supported?: string[];
+    'pre-authorized_grant_anonymous_access_supported'?: boolean;
+    [name: string]: unknown;
+}
+interface TxCode {
+    input_mode?: 'numeric' | 'text';
+    length?: number;
+    description?: string;
+}
+interface PreAuthorizedCodeGrant {
+    'pre-authorized_code': string;
+    tx_code?: TxCode;
+    authorization_server?: string;
+}
+interface CredentialOffer {
+    credential_issuer: string;
+    credential_configuration_ids: string[];
+    grants: {
+        'urn:ietf:params:oauth:grant-type:pre-authorized_code': PreAuthorizedCodeGrant;
+        [grant: string]: unknown;
+    };
+}
+/** Form parameters of the token request (§6.1). */
+interface TokenRequest {
+    grant_type: typeof PRE_AUTHORIZED_CODE_GRANT;
+    'pre-authorized_code': string;
+    tx_code?: string;
+}
+interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    authorization_details?: {
+        type: 'openid_credential';
+        credential_configuration_id: string;
+        credential_identifiers: string[];
+    }[];
+}
+interface NonceResponse {
+    c_nonce: string;
+}
+type CredentialRequest = {
+    credential_configuration_id: string;
+    proofs: {
+        jwt: string[];
+    };
+} | {
+    credential_identifier: string;
+    proofs: {
+        jwt: string[];
+    };
+};
+interface CredentialResponse {
+    credentials: {
+        credential: string;
+    }[];
+    notification_id?: string;
+}
+interface DeferredCredentialResponse {
+    transaction_id: string;
+    interval: number;
+}
+interface DeferredCredentialRequest {
+    transaction_id: string;
+}
+type NotificationEvent = 'credential_accepted' | 'credential_failure' | 'credential_deleted';
+interface NotificationRequest {
+    notification_id: string;
+    event: NotificationEvent;
+    event_description?: string;
+}
+/** Error response of the token, credential, deferred and notification endpoints. */
+interface OAuthErrorResponse {
+    error: string;
+    error_description?: string;
+}
+type Oid4vciErrorCode = 'invalid_offer' | 'unsupported_offer' | 'invalid_metadata' | 'issuer_unavailable' | 'tx_code_unsupported' | 'token_error' | 'issuer_error' | 'invalid_response' | 'invalid_proof' | 'invalid_nonce' | 'invalid_credential';
+declare class Oid4vciError extends CredentialsKitError {
+    readonly code: Oid4vciErrorCode;
+    /** The OAuth / OpenID4VCI error code the server answered (sanitised), when there was one. */
+    readonly oauthError?: string;
+    /**
+     * For `invalid_proof` / `invalid_nonce`: a constant cause for logs. For `invalid_credential`:
+     * the `verifyIssuedCredential` failure code (`bad_signature`, `wrong_subject`, …).
+     */
+    readonly reason?: string;
+    constructor(code: Oid4vciErrorCode, extra?: {
+        oauthError?: string;
+        reason?: string;
+    });
+}
+/**
+ * The Credential Issuer Metadata URL (§12.2.2): `/.well-known/openid-credential-issuer` inserted
+ * between the host and the identifier's path (`https://h/identity` →
+ * `https://h/.well-known/openid-credential-issuer/identity`).
+ */
+declare function issuerMetadataUrl(credentialIssuer: string): string;
+/** The RFC 8414 Authorization Server Metadata URL, built the same way. */
+declare function authorizationServerMetadataUrl(issuer: string): string;
+interface IssuerConfigurationInput {
+    vct: string;
+    display?: Display[];
+    claims?: ClaimDescription[];
+}
+interface BuildIssuerMetadataInput {
+    /** The Credential Issuer Identifier (https URL, no query or fragment). */
+    credentialIssuer: string;
+    /** Keyed by credential configuration id. */
+    configurations: Record<string, IssuerConfigurationInput>;
+    display?: Display[];
+    /** Omit when the issuer is its own Authorization Server (the usual case). */
+    authorizationServers?: string[];
+    /**
+     * Publish each configuration's id as its `scope` (§12.2.4). Default false: `scope` is for the
+     * authorization code flow, which the pre-authorized-only profile does not offer.
+     */
+    includeScope?: boolean;
+    /**
+     * Endpoint URLs. Default: `<credentialIssuer>/oid4vci/{credential,nonce,notification}` (the
+     * layout Self uses). The deferred endpoint is published only when given.
+     */
+    endpoints?: {
+        credential?: string;
+        nonce?: string;
+        deferred?: string;
+        notification?: string;
+    };
+}
+/**
+ * Credential Issuer Metadata (§12.2.4) for `dc+sd-jwt` configurations with Ed25519 DID-bound
+ * proofs. Signing algorithms are listed as `["EdDSA", "Ed25519"]` (the JWS name the kit signs
+ * with, and the fully-specified RFC 9864 name it also accepts).
+ */
+declare function buildIssuerMetadata(input: BuildIssuerMetadataInput): CredentialIssuerMetadata;
+/**
+ * RFC 8414 metadata for an issuer that is its own Authorization Server and supports only the
+ * pre-authorized code grant, anonymously (OpenID4VCI §12.3). Serve it at
+ * `authorizationServerMetadataUrl(credentialIssuer)`. Default token endpoint:
+ * `<credentialIssuer>/oid4vci/token`.
+ */
+declare function buildAuthorizationServerMetadata(input: {
+    issuer: string;
+    tokenEndpoint?: string;
+}): AuthorizationServerMetadata;
+/** A pre-authorized code credential offer (§4.1.1). */
+declare function buildCredentialOffer(input: {
+    credentialIssuer: string;
+    configurationIds: string[];
+    preAuthorizedCode: string;
+    txCode?: TxCode;
+}): CredentialOffer;
+/**
+ * Validate a credential offer object: https `credential_issuer` on a public host (http only on a
+ * loopback host with `allowHttp` + `allowLocal`), no query or fragment, non-empty unique
+ * `credential_configuration_ids`, and a pre-authorized code grant with a non-empty code. Returns
+ * it normalised (only known members); throws `Oid4vciError('invalid_offer')`, or
+ * `unsupported_offer` for a well-formed offer with no pre-authorized code grant (e.g. only
+ * `authorization_code`).
+ */
+declare function validateCredentialOffer(v: unknown, opts?: HostPolicy): CredentialOffer;
+interface VerifiedProof {
+    /** The holder DID the proof key belongs to (`kid` without its fragment). */
+    did: string;
+    kid: string;
+    publicKey: Uint8Array;
+    jwk: Ed25519PublicJwk;
+    /** The proof's `nonce`, when it has one. */
+    nonce?: string;
+}
+interface VerifyProofJwtOptions {
+    /** The Credential Issuer Identifier: the proof's `aud` must equal it. */
+    audience: string;
+    /**
+     * The expected c_nonce, or a check for it (e.g. a stateless signed nonce). Omit only when the
+     * issuer has no nonce endpoint.
+     */
+    nonce?: string | ((nonce: string) => boolean | Promise<boolean>);
+    resolver: DidResolver;
+    /** ms since the epoch; default `Date.now()`. */
+    now?: number;
+    /** Oldest acceptable `iat`, in seconds before now (default 300). */
+    maxAgeSeconds?: number;
+}
+/**
+ * Verify an OpenID4VCI `jwt` key proof (Appendix F.1). The key must be an Ed25519 key listed
+ * under `authentication` on the DID document the `kid` names, controlled by that DID. The
+ * signature is checked before `opts.nonce` is called, so a single-use nonce store is consulted
+ * (and consumed) only for a proof the holder really signed. Returns
+ * the DID and key; the CALLER then enforces subject binding (the DID is the offer's subject) and
+ * binds `cnf` to exactly `jwk`. Throws `Oid4vciError` with code `invalid_proof` or
+ * `invalid_nonce` (the spec's error codes, ready for the error response) and a `reason`;
+ * `ResolverUnavailable` propagates.
+ */
+declare function verifyProofJwt(jwt: string, opts: VerifyProofJwtOptions): Promise<VerifiedProof>;
+/** A `jwt` key proof for `audience` (the Credential Issuer Identifier) with the issuer's c_nonce. */
+declare function createProofJwt(input: {
+    signer: Signer;
+    audience: string;
+    nonce?: string;
+    /** ms since the epoch; default `Date.now()`. */
+    now?: number;
+    /** Default `EdDSA`. */
+    alg?: Ed25519JwsAlg;
+}): Promise<string>;
+/** Fetch and check Credential Issuer Metadata (`credential_issuer` must match exactly, §12.2.4). */
+declare function fetchIssuerMetadata(credentialIssuer: string, opts: {
+    fetch: FetchLike;
+    timeoutMs?: number;
+} & HostPolicy): Promise<CredentialIssuerMetadata>;
+/**
+ * GET a credential offer by reference (§4.1.3): https only (http on loopback with `allowHttp`),
+ * no redirects, timeout, 64 KiB cap, `application/json`; never cached. Returns the validated
+ * offer; throws `Oid4vciError` (`invalid_offer`, `issuer_unavailable`, `issuer_error`).
+ */
+declare function fetchCredentialOffer(credentialOfferUri: string, opts: {
+    fetch: FetchLike;
+    timeoutMs?: number;
+} & HostPolicy): Promise<CredentialOffer>;
+interface IssuedResult {
+    status: 'issued';
+    /** The SD-JWT VC as issued (`<jwt>~<disclosures>~`). */
+    credential: string;
+    notificationId?: string;
+    /** Needed for `sendNotification`. */
+    accessToken: string;
+    notificationEndpoint?: string;
+    /** What `verifyIssuedCredential` found (absent only with `verify: false`). */
+    verified?: VerifiedPresentation;
+}
+interface DeferredResult {
+    status: 'deferred';
+    transactionId: string;
+    /** Seconds to wait before polling. */
+    interval: number;
+    accessToken: string;
+    deferredEndpoint: string;
+    notificationEndpoint?: string;
+    /**
+     * What to check the credential against when it arrives: pass it to `pollDeferred` as
+     * `verification` (null with `verify: false`).
+     */
+    verification: Omit<VerifyIssuedCredentialOptions, 'now'> | null;
+}
+interface RedeemOfferInput {
+    /** The offer by value (validated here; a `CredentialOffer` or the raw JSON). */
+    offer?: unknown;
+    /**
+     * The offer by reference (§4.1.3): fetched here on every call, never cached (each fetch mints a
+     * fresh, single-use pre-authorized code). Give exactly one of `offer` / `credentialOfferUri`.
+     */
+    credentialOfferUri?: string;
+    /**
+     * The holder key (its `kid` is a DID URL of the holder; the issuer binds `cnf` to it). When it
+     * carries `publicKey` (an `Ed25519Signer`) that key is the expected `cnf`; otherwise the key
+     * `kid` names under `authentication` on the holder's DID document is.
+     */
+    signer: Signer & {
+        publicKey?: Uint8Array;
+    };
+    fetch: FetchLike;
+    /**
+     * Resolves the issuer's DID (and the holder's, when the signer has no `publicKey`) to check the
+     * credential. Required unless `verify: false`.
+     */
+    resolver?: DidResolver;
+    /**
+     * The DID the credential's `iss` must be (e.g. the DID that deposited the offer). REQUIRED
+     * unless `verify: false` (`TypeError` otherwise). `false` accepts ANY issuer whose own DID
+     * document signs the credential: UNSAFE, since anyone can then mint a credential of your types
+     * (an offer link the person opened is enough). Use it only when you judge `out.verified.issuer`
+     * yourself before storing or showing anything.
+     */
+    expectedIssuer?: string | false;
+    /**
+     * Default true: check the credential with `verifyIssuedCredential` (signature, `iss`, `sub` =
+     * the holder DID, `cnf` = the holder key, `vct` = the offered configuration's, validity,
+     * disclosures). A credential that fails is NOT returned: `Oid4vciError('invalid_credential')`
+     * (and a best-effort `credential_failure` notification to the issuer).
+     */
+    verify?: boolean;
+    /** Allow http on loopback hosts (local development only; needs `allowLocal`). */
+    allowHttp?: boolean;
+    /** Allow loopback / private / local-name hosts (local development only). */
+    allowLocal?: boolean;
+    /** ms since the epoch (proof `iat`, validity); default `Date.now()`. */
+    now?: number;
+    timeoutMs?: number;
+}
+/**
+ * Redeem a pre-authorized code offer (by value, or fetched from `credentialOfferUri`) for ONE
+ * credential configuration (the offer must name exactly one; one that needs a `tx_code` is
+ * refused with `tx_code_unsupported`): issuer metadata → OAuth server metadata (token endpoint)
+ * → token (anonymous: no `client_id`) → nonce → credential (one retry with a fresh nonce on
+ * `invalid_nonce`) → `verifyIssuedCredential` (unless `verify: false`). Returns the checked
+ * credential, or the deferred transaction. Throws `Oid4vciError` (`invalid_credential` for a
+ * credential that does not check out), `VerificationUnavailable` / `ResolverUnavailable` when a
+ * DID document needed for the check cannot be read, and `TypeError` without `resolver` or
+ * `expectedIssuer` (unless `verify: false`). Store only what this returns, with
+ * `credentialRecordFromSdJwt`.
+ */
+declare function redeemOffer(input: RedeemOfferInput): Promise<IssuedResult | DeferredResult>;
+/**
+ * Poll the Deferred Credential Endpoint once (§9). `verification` is the `DeferredResult`'s:
+ * an issued credential is checked with `verifyIssuedCredential` and refused with
+ * `Oid4vciError('invalid_credential')` when it fails; pass `false` only to opt out explicitly.
+ */
+declare function pollDeferred(input: {
+    deferredEndpoint: string;
+    accessToken: string;
+    transactionId: string;
+    verification: Omit<VerifyIssuedCredentialOptions, 'now'> | false;
+    fetch: FetchLike;
+    timeoutMs?: number;
+    /** ms since the epoch (validity); default `Date.now()`. */
+    now?: number;
+} & HostPolicy): Promise<{
+    status: 'issued';
+    credential: string;
+    notificationId?: string;
+    verified?: VerifiedPresentation;
+} | {
+    status: 'deferred';
+    transactionId: string;
+    interval: number;
+}>;
+/** Tell the issuer what happened to the credential (§11). Throws `Oid4vciError` on refusal. */
+declare function sendNotification(input: {
+    notificationEndpoint: string;
+    accessToken: string;
+    notificationId: string;
+    event: NotificationEvent;
+    /** ASCII without `"` and `\` (§11.1). */
+    eventDescription?: string;
+    fetch: FetchLike;
+    allowHttp?: boolean;
+    allowLocal?: boolean;
+    timeoutMs?: number;
+}): Promise<void>;
+
+export { Oid4vciError, authorizationServerMetadataUrl, buildAuthorizationServerMetadata, buildCredentialOffer, buildIssuerMetadata, createProofJwt, fetchCredentialOffer, fetchIssuerMetadata, issuerMetadataUrl, pollDeferred, redeemOffer, sendNotification, validateCredentialOffer, verifyProofJwt };
+export type { AuthorizationServerMetadata, BuildIssuerMetadataInput, ClaimDescription, CredentialConfiguration, CredentialIssuerMetadata, CredentialOffer, CredentialRequest, CredentialResponse, DeferredCredentialRequest, DeferredCredentialResponse, DeferredResult, Display, IssuedResult, IssuerConfigurationInput, NonceResponse, NotificationEvent, NotificationRequest, OAuthErrorResponse, Oid4vciErrorCode, PreAuthorizedCodeGrant, RedeemOfferInput, TokenRequest, TokenResponse, TxCode, VerifiedProof, VerifyProofJwtOptions };

package/dist/oid4vci.js

@@ -0,0 +1,11 @@
+export { Oid4vciError, authorizationServerMetadataUrl, buildAuthorizationServerMetadata, buildCredentialOffer, buildIssuerMetadata, createProofJwt, fetchCredentialOffer, fetchIssuerMetadata, issuerMetadataUrl, pollDeferred, redeemOffer, sendNotification, validateCredentialOffer, verifyProofJwt } from './chunk-FSKCDHZ7.js';
+import './chunk-I6GBYFIJ.js';
+import './chunk-STMMFNVW.js';
+import './chunk-XREZY53L.js';
+import './chunk-JBUX6V2Q.js';
+import './chunk-WIEGZFUO.js';
+import './chunk-Q3MZNMCK.js';
+import './chunk-VXKONZK4.js';
+import './chunk-AQ3IINHC.js';
+//# sourceMappingURL=oid4vci.js.map
+//# sourceMappingURL=oid4vci.js.map

package/dist/oid4vci.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"oid4vci.js"}