@learncard/openid4vc-plugin 0.0.1

package/dist/vci/auth-code.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Slice 4 — **OID4VCI authorization_code flow**.
+ *
+ * The authorization code grant is the second issuance path in
+ * OID4VCI Draft 13 (§5 / §6.1). Unlike `pre-authorized_code`, it
+ * requires a user-agent redirect to the authorization server, where
+ * the user consents, and then a callback back to the wallet with a
+ * one-time `code`. PKCE (Slice 4's companion module
+ * {@link ./pkce.ts}) protects the exchange.
+ *
+ * Because the plugin runs headless — it cannot itself launch a
+ * browser — we split the flow into two halves:
+ *
+ *   1. **begin** — resolve issuer + AS metadata, generate PKCE, build
+ *      the authorization URL, return it along with the opaque
+ *      `flowHandle` the wallet persists until the redirect fires.
+ *   2. **complete** — take the `code` that arrived on the redirect
+ *      plus the stored `flowHandle`, exchange for an access token,
+ *      then run the normal `/credential` request + proof-of-possession
+ *      to get the actual VC.
+ *
+ * The plugin's public API (`beginCredentialOfferAuthCode` /
+ * `completeCredentialOfferAuthCode`) wraps these with LearnCard
+ * session plumbing.
+ */
+import { CredentialOffer } from '../offer/types';
+import { PkcePair } from './pkce';
+import { AcceptedCredentialResult, AuthorizationServerMetadata, CredentialIssuerMetadata, ProofJwtSigner, TokenResponse } from './types';
+/** Grant-type URN used for the authorization_code flow on /token. */
+export declare const AUTHORIZATION_CODE_GRANT = "authorization_code";
+export interface BeginAuthCodeFlowOptions {
+    offer: CredentialOffer;
+    /**
+     * URL the wallet wants the AS to redirect back to after user
+     * consent. Must match whatever the wallet registered with the
+     * AS out-of-band (or, for clients using an ephemeral redirect
+     * like `http://127.0.0.1:<random>/cb`, whatever the wallet spins
+     * up at runtime).
+     */
+    redirectUri: string;
+    /** OAuth 2.0 client identifier. Required for auth_code flows. */
+    clientId: string;
+    /**
+     * Subset of `credential_configuration_ids` from the offer to
+     * actually request. Defaults to all of them. Validated before
+     * the network hits the AS so typos don't cost a real `code` round
+     * trip.
+     */
+    configurationIds?: string[];
+    /**
+     * OAuth 2.0 `scope`. Optional — the plugin prefers
+     * `authorization_details` (Draft 13 §5.1.1) when it can. Pass
+     * `scope` if the AS mandates it.
+     */
+    scope?: string;
+    /** Override fetch — defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Result of `begin`. The wallet:
+ *   - Opens `authorizationUrl` in a user-agent.
+ *   - Persists `flowHandle` until the redirect delivers a `code`.
+ *   - Calls `complete` with the received `code` + the stored handle.
+ */
+export interface BeginAuthCodeFlowResult {
+    authorizationUrl: string;
+    /**
+     * Opaque handle — JSON-serializable so the wallet can round-trip
+     * it through storage / postMessage / deep-link state. Carries
+     * everything `complete` needs: PKCE verifier, AS token endpoint,
+     * issuer metadata pointers, expected state.
+     */
+    flowHandle: AuthCodeFlowHandle;
+}
+export interface AuthCodeFlowHandle {
+    version: 1;
+    issuer: string;
+    tokenEndpoint: string;
+    credentialEndpoint: string;
+    configurationIds: string[];
+    redirectUri: string;
+    clientId: string;
+    state: string;
+    pkceVerifier: string;
+    pkceMethod: 'S256';
+    credentialConfigurations: Record<string, unknown>;
+}
+export interface CompleteAuthCodeFlowOptions {
+    flowHandle: AuthCodeFlowHandle;
+    /** Code delivered on the redirect callback. */
+    code: string;
+    /** State delivered on the redirect callback — must match the handle. */
+    state?: string;
+    /**
+     * Holder signer for the proof-of-possession JWT. Plugin wires
+     * its Ed25519 default; HSM-backed hosts inject their own.
+     */
+    signer: ProofJwtSigner;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Phase 1 of the auth_code flow. Pure preparation — the only network
+ * hits are metadata lookups; no codes are exchanged yet.
+ */
+export declare const beginAuthCodeFlow: (options: BeginAuthCodeFlowOptions) => Promise<BeginAuthCodeFlowResult>;
+/**
+ * Phase 2 — wallet has the `code` back from the redirect. Exchange
+ * for an access token, fetch the VC(s), return them.
+ *
+ * Reuses `requestCredential` and `buildProofJwt` from the pre-auth
+ * pipeline — only the token exchange differs.
+ */
+export declare const completeAuthCodeFlow: (options: CompleteAuthCodeFlowOptions) => Promise<AcceptedCredentialResult>;
+/**
+ * Build the authorization-endpoint URL a wallet opens in a user-agent
+ * to kick off the OAuth dance.
+ *
+ * Includes PKCE (S256), per-config `authorization_details` scoped to
+ * `openid_credential` (Draft 13 §5.1.1), and optional issuer_state so
+ * the AS can correlate the request with the original offer.
+ */
+export declare const buildAuthorizationUrl: (args: {
+    authorizationEndpoint: string;
+    clientId: string;
+    redirectUri: string;
+    configurationIds: string[];
+    scope?: string;
+    pkce: PkcePair;
+    state: string;
+    issuerState?: string;
+}) => string;
+/**
+ * POST to the AS token endpoint with `grant_type=authorization_code`
+ * + PKCE verifier. Returns the canonical {@link TokenResponse}.
+ *
+ * Error handling mirrors {@link ./token.ts:exchangePreAuthorizedCode}
+ * so the plugin's error surface is consistent across grant types.
+ */
+export declare const exchangeAuthorizationCode: (args: {
+    tokenEndpoint: string;
+    code: string;
+    codeVerifier: string;
+    clientId: string;
+    redirectUri: string;
+    fetchImpl?: typeof fetch;
+}) => Promise<TokenResponse>;
+export type { CredentialIssuerMetadata, AuthorizationServerMetadata };
+//# sourceMappingURL=auth-code.d.ts.map

package/dist/vci/auth-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-code.d.ts","sourceRoot":"","sources":["../../src/vci/auth-code.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAMjD,OAAO,EAEH,QAAQ,EACX,MAAM,QAAQ,CAAC;AAGhB,OAAO,EACH,wBAAwB,EACxB,2BAA2B,EAC3B,wBAAwB,EAExB,cAAc,EACd,aAAa,EAChB,MAAM,SAAS,CAAC;AAOjB,qEAAqE;AACrE,eAAO,MAAM,wBAAwB,uBAAuB,CAAC;AAE7D,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,eAAe,CAAC;IAEvB;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,uDAAuD;IACvD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACpC,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,UAAU,EAAE,kBAAkB,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IAGnB,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,2BAA2B;IACxC,UAAU,EAAE,kBAAkB,CAAC;IAE/B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IAEb,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,EAAE,cAAc,CAAC;IAEvB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC5B;AAMD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,YACjB,wBAAwB,KAClC,OAAO,CAAC,uBAAuB,CA8EjC,CAAC;AAMF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,YACpB,2BAA2B,KACrC,OAAO,CAAC,wBAAwB,CAiClC,CAAC;AAMF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,SAAU;IACxC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB,KAAG,MAuBH,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,SAAgB;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC5B,KAAG,OAAO,CAAC,aAAa,CAoExB,CAAC;AA8LF,YAAY,EAAE,wBAAwB,EAAE,2BAA2B,EAAE,CAAC"}

package/dist/vci/decode.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Normalized representation of an issued credential, suitable for handing
+ * to the LearnCard store plane.
+ *
+ * Fields:
+ * - `vc` — W3C VC JSON-LD object (what the wallet UI renders / validates).
+ * - `rawFormat` — the format id the issuer returned it in (e.g. `jwt_vc_json`).
+ * - `jwt` — original compact JWS, preserved only for jwt-based formats so
+ *   downstream verification can re-check the signature without re-fetching.
+ */
+export interface NormalizedCredential {
+    vc: W3CVerifiableCredential;
+    rawFormat: string;
+    jwt?: string;
+}
+/**
+ * W3C VC Data Model shape. Only the fields we actually touch are typed —
+ * everything else passes through as `unknown` so issuer-specific extensions
+ * aren't clobbered.
+ */
+export interface W3CVerifiableCredential {
+    '@context': unknown;
+    type: string[] | string;
+    id?: string;
+    issuer?: string | {
+        id?: string;
+        [k: string]: unknown;
+    };
+    issuanceDate?: string;
+    expirationDate?: string;
+    validFrom?: string;
+    validUntil?: string;
+    credentialSubject?: {
+        id?: string;
+        [k: string]: unknown;
+    } | Array<{
+        id?: string;
+        [k: string]: unknown;
+    }>;
+    credentialStatus?: unknown;
+    credentialSchema?: unknown;
+    proof?: unknown;
+    [k: string]: unknown;
+}
+/**
+ * Decode a credential returned from the issuer into the wallet's native
+ * W3C VC shape.
+ *
+ * Supports:
+ * - `jwt_vc_json` (and the draft-11 alias `jwt_vc`): compact JWS per VCDM
+ *   §6.3.1. Mapped claims: `iss` → `issuer`, `sub` → `credentialSubject.id`,
+ *   `jti` → `id`, `nbf`/`iat` → `issuanceDate`, `exp` → `expirationDate`.
+ *   The raw JWT is preserved in `jwt` so the store can re-verify later.
+ * - `ldp_vc`: the credential is already a JSON-LD VC object — pass through.
+ *
+ * Unknown formats throw `unsupported_format` so callers can decide whether
+ * to fail the batch or skip the entry.
+ *
+ * NOTE: This function deliberately does NOT verify the JWT signature. The
+ * issuer is trusted to return a valid credential for the pre-authorized
+ * code flow; downstream verification (via `learnCard.invoke.verifyCredential`)
+ * will re-check against the proof when the user views the credential.
+ */
+export declare const normalizeIssuedCredential: (credential: unknown, format: string) => NormalizedCredential;
+//# sourceMappingURL=decode.d.ts.map

package/dist/vci/decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../../src/vci/decode.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACjC,EAAE,EAAE,uBAAuB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACpC,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAAG,KAAK,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IACzG,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,yBAAyB,eACtB,OAAO,UACX,MAAM,KACf,oBAsBF,CAAC"}

package/dist/vci/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Stable, machine-readable error codes for the VCI (Verifiable Credential
+ * Issuance) flow. UI can map `code` → friendly copy without string-matching
+ * on the `message`.
+ */
+export type VciErrorCode = 'metadata_fetch_failed' | 'metadata_invalid' | 'metadata_issuer_mismatch' | 'token_request_failed' | 'token_response_invalid' | 'proof_signing_failed' | 'credential_request_failed' | 'credential_response_invalid' | 'unsupported_grant' | 'unsupported_format' | 'tx_code_required' | 'nonce_required' | 'store_failed' | 'index_failed' | 'store_plane_missing' | 'index_plane_missing';
+/**
+ * Thrown by any VCI helper when a flow step fails. Carries the originating
+ * HTTP status (when available) and the raw server body, so higher-level
+ * code can surface it for logs without re-parsing.
+ */
+export declare class VciError extends Error {
+    readonly code: VciErrorCode;
+    readonly status?: number;
+    readonly body?: unknown;
+    constructor(code: VciErrorCode, message: string, opts?: {
+        status?: number;
+        body?: unknown;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/vci/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/vci/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAClB,uBAAuB,GACvB,kBAAkB,GAClB,0BAA0B,GAC1B,sBAAsB,GACtB,wBAAwB,GACxB,sBAAsB,GACtB,2BAA2B,GAC3B,6BAA6B,GAC7B,mBAAmB,GACnB,oBAAoB,GACpB,kBAAkB,GAClB,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,qBAAqB,GACrB,qBAAqB,CAAC;AAE5B;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;gBAGpB,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CActE"}

package/dist/vci/index.d.ts

@@ -0,0 +1,12 @@
+export * from './types';
+export * from './errors';
+export * from './metadata';
+export * from './token';
+export * from './proof';
+export * from './request';
+export * from './accept';
+export * from './decode';
+export * from './store';
+export * from './pkce';
+export * from './auth-code';
+//# sourceMappingURL=index.d.ts.map

package/dist/vci/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vci/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC"}

package/dist/vci/metadata.d.ts

@@ -0,0 +1,25 @@
+import { AuthorizationServerMetadata, CredentialIssuerMetadata } from './types';
+/**
+ * Fetch and validate the Credential Issuer Metadata for a given issuer URL.
+ *
+ * @throws {VciError} with code `metadata_fetch_failed` for network / HTTP
+ *   errors, `metadata_invalid` for shape issues, and `metadata_issuer_mismatch`
+ *   when the returned `credential_issuer` doesn't match the requested one.
+ */
+export declare const fetchCredentialIssuerMetadata: (credentialIssuer: string, fetchImpl?: typeof fetch) => Promise<CredentialIssuerMetadata>;
+/**
+ * Fetch and validate Authorization Server metadata. Tries the
+ * OAuth 2.0 well-known path first and falls back to the OpenID Connect one.
+ */
+export declare const fetchAuthorizationServerMetadata: (authServer: string, fetchImpl?: typeof fetch) => Promise<AuthorizationServerMetadata>;
+/**
+ * Resolve the authorization server metadata that should be used for a given
+ * credential offer / issuer metadata pair.
+ *
+ * Preference order:
+ * 1. `authorization_server` explicitly named on the pre-authorized grant.
+ * 2. First entry of `issuerMetadata.authorization_servers`.
+ * 3. The issuer itself (many small deployments are their own AS).
+ */
+export declare const resolveAuthorizationServer: (issuerMetadata: CredentialIssuerMetadata, grantAuthServer?: string) => string;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/vci/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/vci/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,2BAA2B,EAC3B,wBAAwB,EAC3B,MAAM,SAAS,CAAC;AAOjB;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,qBACpB,MAAM,cACb,OAAO,KAAK,KACxB,OAAO,CAAC,wBAAwB,CA2ClC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gCAAgC,eAC7B,MAAM,cACP,OAAO,KAAK,KACxB,OAAO,CAAC,2BAA2B,CA2DrC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,mBACnB,wBAAwB,oBACtB,MAAM,KACzB,MAYF,CAAC"}

package/dist/vci/pkce.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Slice 4 — **PKCE (Proof Key for Code Exchange, RFC 7636)**.
+ *
+ * The authorization-code flow in OID4VCI is vulnerable to authorization
+ * code interception attacks unless the wallet proves possession of a
+ * secret at token-exchange time. PKCE is the standard mitigation:
+ *
+ *   1. Wallet generates a high-entropy `code_verifier`.
+ *   2. Wallet derives `code_challenge = BASE64URL(SHA-256(verifier))`.
+ *   3. Wallet sends `code_challenge` + `code_challenge_method=S256`
+ *      on the authorization request.
+ *   4. Wallet sends the original `code_verifier` on the token request.
+ *   5. AS compares the hashed verifier with the stored challenge.
+ *
+ * We only implement the `S256` method \u2014 `plain` is spec-allowed but
+ * provides no security benefit, and OpenID4VCI \u00a76.2 mandates `S256`
+ * when PKCE is used.
+ *
+ * Cross-platform: uses the Web Crypto API (`crypto.getRandomValues` +
+ * `crypto.subtle.digest`) which is available natively in browsers and
+ * in Node \u2265 18. Async because `subtle.digest` is async by spec.
+ */
+/**
+ * PKCE code challenge method. OID4VCI permits only `S256`; we pin the
+ * literal type so callers get compile-time noise if they try `plain`.
+ */
+export type PkceCodeChallengeMethod = 'S256';
+export interface PkcePair {
+    /**
+     * High-entropy secret kept by the wallet. Sent verbatim on the
+     * token request to prove possession of the original challenge.
+     */
+    verifier: string;
+    /**
+     * `BASE64URL(SHA-256(verifier))`. Sent on the authorization
+     * request (along with `code_challenge_method`) so the AS can
+     * later check the verifier matches.
+     */
+    challenge: string;
+    method: PkceCodeChallengeMethod;
+}
+export interface GeneratePkceOptions {
+    /**
+     * Byte length of the random verifier source. The spec allows
+     * 43–128 *characters* of base64url-encoded entropy; our default
+     * of 32 bytes encodes to ~43 base64url chars, matching the
+     * minimum. Bump this if your threat model demands more.
+     */
+    byteLength?: number;
+}
+export type PkceErrorCode = 'invalid_verifier' | 'unsupported_method';
+export declare class PkceError extends Error {
+    readonly code: PkceErrorCode;
+    constructor(code: PkceErrorCode, message: string);
+}
+/**
+ * Generate a fresh PKCE verifier + S256 challenge.
+ *
+ * The verifier is produced by base64url-encoding `byteLength` bytes of
+ * Web Crypto random output — which satisfies RFC 7636 §4.1's
+ * "unreserved characters only" requirement without extra normalization.
+ */
+export declare const generatePkcePair: (options?: GeneratePkceOptions) => Promise<PkcePair>;
+/**
+ * Derive the S256 challenge for a given verifier. Separated from
+ * {@link generatePkcePair} so callers that round-trip a verifier
+ * through a redirect (the common case — wallet stores verifier,
+ * extracts it later at token-exchange time) can re-derive the
+ * challenge for assertions and logs.
+ *
+ * Async because Web Crypto's `subtle.digest` is async by spec.
+ */
+export declare const computeS256Challenge: (verifier: string) => Promise<string>;
+/**
+ * Verify a challenge matches a given verifier. Used by the
+ * authorization server, not the wallet — but we expose it so the
+ * in-process test server can validate challenges the same way real
+ * ASes do.
+ */
+export declare const verifyPkce: (args: {
+    verifier: string;
+    challenge: string;
+    method?: PkceCodeChallengeMethod;
+}) => Promise<boolean>;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/vci/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/vci/pkce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,QAAQ;IACrB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB,MAAM,EAAE,uBAAuB,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAChC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD,MAAM,MAAM,aAAa,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;AAEtE,qBAAa,SAAU,SAAQ,KAAK;IAChC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBACjB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM;CAKnD;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,aAChB,mBAAmB,KAC7B,OAAO,CAAC,QAAQ,CAalB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,aAAoB,MAAM,KAAG,OAAO,CAAC,MAAM,CAW3E,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,SAAgB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,uBAAuB,CAAC;CACpC,KAAG,OAAO,CAAC,OAAO,CAOlB,CAAC"}

package/dist/vci/proof.d.ts

@@ -0,0 +1,43 @@
+import { JWKWithPrivateKey } from '@learncard/types';
+import { ProofJwtSigner } from './types';
+/**
+ * The `typ` value required by OID4VCI Draft 13 §7.2.1.1 for JWT
+ * proof-of-possession signatures.
+ */
+export declare const OID4VCI_PROOF_TYP = "openid4vci-proof+jwt";
+/**
+ * Build an OID4VCI proof-of-possession JWT per Draft 13 §7.2.1.1.
+ *
+ * Header fields set by this function:
+ * - `alg` — from signer
+ * - `kid` — from signer (MUST point to a verification method the issuer can resolve)
+ * - `typ` — `openid4vci-proof+jwt` (per spec)
+ *
+ * Payload fields set by this function:
+ * - `aud` — the credential issuer identifier
+ * - `iat` — current unix time
+ * - `nonce` — the `c_nonce` returned by the token endpoint (REQUIRED when the issuer supplied one)
+ * - `iss` — only when `clientId` is provided (pre-auth anonymous flows omit it)
+ *
+ * The signer contract is deliberately narrow so tests can exercise this
+ * function without any real crypto.
+ */
+export declare const buildProofJwt: (args: {
+    signer: ProofJwtSigner;
+    audience: string;
+    nonce?: string;
+    clientId?: string;
+    /** Override `iat` for deterministic tests. */
+    now?: () => number;
+}) => Promise<string>;
+/**
+ * Default {@link ProofJwtSigner} implementation backed by a LearnCard
+ * Ed25519 keypair and `jose`. Host plugins that use a different key type
+ * or an HSM should construct their own signer.
+ */
+export declare const createJoseEd25519Signer: (args: {
+    keypair: JWKWithPrivateKey;
+    /** Verification method URL, e.g. `did:key:z6M...#z6M...`. */
+    kid: string;
+}) => Promise<ProofJwtSigner>;
+//# sourceMappingURL=proof.d.ts.map

package/dist/vci/proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof.d.ts","sourceRoot":"","sources":["../../src/vci/proof.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGzC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,yBAAyB,CAAC;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,SAAgB;IACtC,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB,KAAG,OAAO,CAAC,MAAM,CA+BjB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,SAAgB;IAChD,OAAO,EAAE,iBAAiB,CAAC;IAC3B,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAC;CACf,KAAG,OAAO,CAAC,cAAc,CAqBzB,CAAC"}

package/dist/vci/request.d.ts

@@ -0,0 +1,48 @@
+import { CredentialResponseBody } from './types';
+/**
+ * POST a credential request to the issuer's credential endpoint and
+ * validate the response. Synchronous issuance only — deferred
+ * (`transaction_id`) and batch (`credentials` array) responses are passed
+ * through for higher-level handling.
+ *
+ * Draft 13 §7.2 distinguishes two mutually-exclusive ways to identify the
+ * credential being requested:
+ *
+ * 1. `credential_identifier` — supplied by the issuer in the token
+ *    response's `authorization_details[].credential_identifiers`. Only
+ *    use this when the token endpoint explicitly returned one.
+ * 2. `format` + format-specific fields (e.g. `credential_definition`
+ *    for `jwt_vc_json` / `ldp_vc`). The default path for pre-authorized
+ *    flows where the offer carries `credential_configuration_ids` but
+ *    the token response carries no `authorization_details`.
+ *
+ * Callers pick the path by setting either `credentialIdentifier` OR
+ * `format` (+ relevant `extra` fields).
+ */
+export declare const requestCredential: (args: {
+    credentialEndpoint: string;
+    accessToken: string;
+    tokenType?: string;
+    /**
+     * Opaque identifier from the token response's `authorization_details`.
+     * When set, `format` and any format-specific `extra` fields MUST NOT
+     * be sent (spec §7.2).
+     */
+    credentialIdentifier?: string;
+    /**
+     * Credential format id (`jwt_vc_json`, `ldp_vc`, …). Required unless
+     * `credentialIdentifier` is supplied.
+     */
+    format?: string;
+    /** Proof-of-possession JWT built by {@link buildProofJwt}. */
+    proofJwt: string;
+    /**
+     * Format-specific body fields. For `jwt_vc_json` this is typically
+     * `{ credential_definition: { type: [...] } }` copied from the issuer
+     * metadata's advertised configuration. Ignored when
+     * `credentialIdentifier` is set.
+     */
+    extra?: Record<string, unknown>;
+    fetchImpl?: typeof fetch;
+}) => Promise<CredentialResponseBody>;
+//# sourceMappingURL=request.d.ts.map

package/dist/vci/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/vci/request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAkB,MAAM,SAAS,CAAC;AAGjE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,SAAgB;IAC1C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC5B,KAAG,OAAO,CAAC,sBAAsB,CAkGjC,CAAC"}

package/dist/vci/store.d.ts

@@ -0,0 +1,89 @@
+import { LearnCard } from '@learncard/core';
+import { W3CVerifiableCredential } from './decode';
+import { AcceptedCredentialResult } from './types';
+import { VciError } from './errors';
+/**
+ * Name of the plugin we look for on the `store` and `index` planes by
+ * default. Matches the LearnCloud plugin's declared `name`.
+ */
+export declare const DEFAULT_STORE_PLUGIN = "LearnCloud";
+/** Shape of the record passed to `learnCard.index.<plugin>.add(record)`. */
+export interface IndexRecord {
+    id: string;
+    uri: string;
+    category: string;
+    title?: string;
+    imgUrl?: string;
+    boostUri?: string;
+    /** Index record schema version, matches existing wallet writes. */
+    __v: 1;
+}
+export interface StoreAcceptedCredentialsOptions {
+    /**
+     * Name of the plugin implementing the `store` + `index` planes. Defaults
+     * to `LearnCloud`. Overridable for future `SQLite` / local-only backends.
+     */
+    storage?: string;
+    /**
+     * When true (default), uploads the credential with `uploadEncrypted` so
+     * only the holder can read it back. When false or when the chosen store
+     * plugin doesn't implement `uploadEncrypted`, falls back to `upload`.
+     */
+    encrypt?: boolean;
+    /**
+     * Override or compute the category placed on the index record. Defaults
+     * to a simple VC-type heuristic.
+     */
+    category?: string | ((vc: W3CVerifiableCredential, index: number) => string);
+    /** Optional title (display name) on the index record. */
+    title?: string | ((vc: W3CVerifiableCredential, index: number) => string | undefined);
+    /** Optional image URL on the index record. */
+    imgUrl?: string | ((vc: W3CVerifiableCredential, index: number) => string | undefined);
+    /**
+     * Low-level escape hatches so consumers can swap the underlying backend
+     * (e.g. tests, SQLite, a custom in-memory mock). If supplied these take
+     * precedence over the `storage` / `encrypt` defaults.
+     */
+    upload?: (credential: W3CVerifiableCredential) => Promise<string>;
+    addToIndex?: (record: IndexRecord) => Promise<unknown>;
+    /** Custom id generator. Defaults to crypto.randomUUID() with a fallback. */
+    makeId?: () => string;
+}
+/** Per-credential outcome of `storeAcceptedCredentials`. */
+export interface StoredCredentialEntry {
+    /** URI returned by the store plane, e.g. `lc:network:...`. */
+    uri: string;
+    /** Id used in the index record. */
+    recordId: string;
+    /** Normalized W3C VC — what the store actually saw. */
+    vc: W3CVerifiableCredential;
+    /** Credential configuration id from the offer that produced this credential. */
+    configurationId: string;
+    /** Format id the issuer used (`jwt_vc_json`, `ldp_vc`, …). */
+    format: string;
+}
+export interface StoreAcceptedCredentialsResult {
+    stored: StoredCredentialEntry[];
+    /**
+     * Per-credential failures — storage of one credential failing should not
+     * abort the batch, so we surface partial success.
+     */
+    failures: Array<{
+        configurationId: string;
+        format: string;
+        error: VciError;
+    }>;
+}
+/**
+ * Persist a batch of credentials returned by {@link acceptCredentialOffer}
+ * into the host LearnCard's store + index planes.
+ *
+ * Each credential is normalized (JWT → W3C VC), uploaded to the store plane
+ * to get a URI, then indexed so it appears in the wallet UI.
+ *
+ * Errors are caught per-credential so a single failure doesn't abort the
+ * rest of the batch. Callers should inspect `failures` to decide whether
+ * to surface a partial-success toast or retry.
+ */
+export declare const storeAcceptedCredentials: (learnCard: LearnCard<any, any, any>, accepted: AcceptedCredentialResult, options?: StoreAcceptedCredentialsOptions) => Promise<StoreAcceptedCredentialsResult>;
+//# sourceMappingURL=store.d.ts.map

package/dist/vci/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/vci/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAEH,uBAAuB,EAE1B,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEpC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,GAAG,EAAE,CAAC,CAAC;CACV;AAED,MAAM,WAAW,+BAA+B;IAC5C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,uBAAuB,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IAC7E,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,uBAAuB,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;IACtF,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,uBAAuB,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;IACvF;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,uBAAuB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClE,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACzB;AAED,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IAClC,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,EAAE,EAAE,uBAAuB,CAAC;IAC5B,gFAAgF;IAChF,eAAe,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,8BAA8B;IAC3C,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC;;;OAGG;IACH,QAAQ,EAAE,KAAK,CAAC;QACZ,eAAe,EAAE,MAAM,CAAC;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,QAAQ,CAAC;KACnB,CAAC,CAAC;CACN;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,cACtB,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,YACzB,wBAAwB,YACzB,+BAA+B,KACzC,OAAO,CAAC,8BAA8B,CA+DxC,CAAC"}

package/dist/vci/token.d.ts

@@ -0,0 +1,16 @@
+import { TokenResponse } from './types';
+/**
+ * Exchange a pre-authorized code for an access token.
+ *
+ * Per OID4VCI Draft 13 §6.1, the request is a standard OAuth 2.0 token
+ * request with `grant_type = urn:ietf:params:oauth:grant-type:pre-authorized_code`
+ * and optional `tx_code` when the offer required one.
+ */
+export declare const exchangePreAuthorizedCode: (args: {
+    tokenEndpoint: string;
+    preAuthorizedCode: string;
+    txCode?: string;
+    clientId?: string;
+    fetchImpl?: typeof fetch;
+}) => Promise<TokenResponse>;
+//# sourceMappingURL=token.d.ts.map

package/dist/vci/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/vci/token.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,SAAgB;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC5B,KAAG,OAAO,CAAC,aAAa,CAmExB,CAAC"}