@vidos-id/openid4vc-wallet 0.0.0-test1

package/README.md

@@ -0,0 +1,153 @@
+# @vidos-id/openid4vc-wallet
+
+Minimal demo wallet library for importing, storing, and presenting `dc+sd-jwt` credentials.
+
+For the CLI wrapper, see [`@vidos-id/openid4vc-wallet-cli`](../wallet-cli/). For the installed CLI flow, see the [root README](../../). For development, the CLI bin can be run with `bun packages/wallet-cli/src/index.ts`.
+
+## Install
+
+Configure GitHub Packages in the consuming repo:
+
+```ini
+@vidos-id:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
+```
+
+Install with your preferred package manager:
+
+```bash
+# bun
+bun add @vidos-id/openid4vc-wallet
+
+# npm
+npm install @vidos-id/openid4vc-wallet
+
+# pnpm
+pnpm add @vidos-id/openid4vc-wallet
+
+# yarn
+yarn add @vidos-id/openid4vc-wallet
+```
+
+This package is currently published as raw TypeScript and is intended for Bun-based consumers.
+
+## Features
+
+- holder-key generation (ES256, ES384, EdDSA)
+- holder-key import from JWK
+- pluggable storage interface
+- issuer JWK/JWKS credential verification (optional)
+- direct OID4VCI receipt from credential offers
+- on-demand credential status resolution via Token Status List JWTs
+- DCQL matching with `dcql`
+- `openid4vp://` authorization URL parsing for by-value DCQL requests
+- selective disclosure presentation building
+- KB-JWT holder binding
+- `direct_post` and `direct_post.jwt` authorization response submission
+
+## Example
+
+```ts
+import {
+  InMemoryWalletStorage,
+  Wallet,
+  receiveCredentialFromOffer,
+} from "@vidos-id/openid4vc-wallet";
+
+const wallet = new Wallet(new InMemoryWalletStorage());
+
+// Default holder key algorithm is ES256; pass "ES384" or "EdDSA" for alternatives
+await wallet.getOrCreateHolderKey("ES256");
+
+// Import a credential (after issuing with the issuer library)
+await wallet.importCredential({
+  credential: "eyJ...",
+});
+
+// Optionally verify against issuer JWKS on import
+await wallet.importCredential({
+  credential: "eyJ...",
+  issuer: { issuer: "https://issuer.example", jwks: { keys: [/* ... */] } },
+});
+
+// Receive directly from a minimal OID4VCI credential offer
+await receiveCredentialFromOffer(
+  wallet,
+  'openid-credential-offer://?credential_offer=...'
+);
+
+// Or start from a by-reference offer URI
+await receiveCredentialFromOffer(
+  wallet,
+  'openid-credential-offer://?credential_offer_uri=https%3A%2F%2Fissuer.example%2Foffers%2Fperson-1'
+);
+
+// Endpoint resolution is metadata-driven:
+// 1. parse the offer or fetch credential_offer_uri first
+// 2. read credential_issuer from the resolved offer
+// 3. fetch /.well-known/openid-credential-issuer[issuer-path]
+// 4. use token_endpoint / credential_endpoint / optional nonce_endpoint from metadata
+
+// Resolve credential status only when needed
+const status = await wallet.getCredentialStatus("credential-id");
+
+// Create a presentation from a DCQL request
+const presentation = await wallet.createPresentation({
+  client_id: "https://verifier.example",
+  nonce: "nonce-123",
+  dcql_query: {
+    credentials: [
+      {
+        id: "person",
+        format: "dc+sd-jwt",
+        meta: { vct_values: ["https://example.com/PersonCredential"] },
+      },
+    ],
+  },
+});
+
+// Parse an openid4vp:// authorization URL
+const request = Wallet.parseAuthorizationRequestUrl("openid4vp://authorize?...");
+```
+
+Supported `openid4vp://` subset:
+- by-value only
+- requires `client_id`, `nonce`, and `dcql_query`
+- rejects `request`, `request_uri`, `scope`, and Presentation Exchange input
+
+Supported OID4VCI subset:
+- by-value credential offers and by-reference `credential_offer_uri`
+- pre-authorized-code flow only
+- JWT proof only
+- single `dc+sd-jwt` credential request + import
+
+OID4VCI endpoint resolution:
+- `receiveCredentialFromOffer` parses the offer input or fetches `credential_offer_uri`, then reads `credential_issuer`
+- issuer metadata is fetched from `/.well-known/openid-credential-issuer` relative to that issuer
+- if `credential_issuer` contains a path, that path is appended to the well-known URL
+- the fetched metadata must repeat the same `credential_issuer`
+- `token_endpoint` and `credential_endpoint` are taken from metadata, not hardcoded in the wallet
+- `nonce_endpoint` is used only if the token response does not already include `c_nonce`
+- there is no API to manually override discovered endpoints
+
+Examples:
+- `https://issuer.example` -> `https://issuer.example/.well-known/openid-credential-issuer`
+- `https://issuer.example/tenant-a` -> `https://issuer.example/.well-known/openid-credential-issuer/tenant-a`
+
+This allows issuers to use non-standard endpoint paths such as `/token` or `/credential`, as long as those exact URLs are returned in issuer metadata.
+
+Current limitations:
+- `credential_offer_uri` must return a supported by-value offer document
+- issuer metadata must contain `token_endpoint`, `credential_endpoint`, `jwks`, and the requested credential configuration
+- if the token response omits `c_nonce`, issuer metadata must provide `nonce_endpoint`
+
+## See also
+
+- [`@vidos-id/openid4vc-issuer`](../issuer/) - issuer library for credential issuance
+- [`scripts/demo-e2e.ts`](../../scripts/demo-e2e.ts) - full programmatic flow using both libraries
+
+## Test
+
+```bash
+bun test packages/wallet/src/wallet.test.ts
+```

package/dist/index.d.mts

@@ -0,0 +1,330 @@
+import { JWK, JWTHeaderParameters, importJWK } from "jose";
+import { z } from "zod";
+import { DcqlQuery } from "dcql";
+
+//#region src/schemas.d.ts
+declare const JwkSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+declare const HolderKeyRecordSchema: z.ZodObject<{
+  id: z.ZodString;
+  algorithm: z.ZodEnum<{
+    ES256: "ES256";
+    ES384: "ES384";
+    EdDSA: "EdDSA";
+  }>;
+  publicJwk: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  privateJwk: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  createdAt: z.ZodString;
+}, z.core.$strip>;
+declare const CredentialStatusListReferenceSchema: z.ZodObject<{
+  idx: z.ZodNumber;
+  uri: z.ZodString;
+}, z.core.$strip>;
+declare const CredentialStatusSchema: z.ZodObject<{
+  status_list: z.ZodObject<{
+    idx: z.ZodNumber;
+    uri: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+declare const StoredCredentialRecordSchema: z.ZodObject<{
+  id: z.ZodString;
+  format: z.ZodLiteral<"dc+sd-jwt">;
+  compactSdJwt: z.ZodString;
+  issuer: z.ZodString;
+  vct: z.ZodString;
+  holderKeyId: z.ZodString;
+  claims: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  status: z.ZodOptional<z.ZodObject<{
+    status_list: z.ZodObject<{
+      idx: z.ZodNumber;
+      uri: z.ZodString;
+    }, z.core.$strip>;
+  }, z.core.$strip>>;
+  issuerKeyMaterial: z.ZodOptional<z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
+    issuer: z.ZodString;
+    jwks: z.ZodObject<{
+      keys: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+  }, z.core.$strip>, z.ZodObject<{
+    issuer: z.ZodString;
+    jwk: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  }, z.core.$strip>]>>>;
+  importedAt: z.ZodString;
+}, z.core.$strip>;
+declare const IssuerJwksSchema: z.ZodObject<{
+  issuer: z.ZodString;
+  jwks: z.ZodObject<{
+    keys: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+declare const IssuerJwkSchema: z.ZodObject<{
+  issuer: z.ZodString;
+  jwk: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+declare const IssuerKeyMaterialSchema: z.ZodUnion<readonly [z.ZodObject<{
+  issuer: z.ZodString;
+  jwks: z.ZodObject<{
+    keys: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+  issuer: z.ZodString;
+  jwk: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>]>;
+declare const ImportCredentialInputSchema: z.ZodObject<{
+  credential: z.ZodString;
+  issuer: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+    issuer: z.ZodString;
+    jwks: z.ZodObject<{
+      keys: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+  }, z.core.$strip>, z.ZodObject<{
+    issuer: z.ZodString;
+    jwk: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  }, z.core.$strip>]>>;
+}, z.core.$strip>;
+declare const ResponseModeSchema: z.ZodEnum<{
+  direct_post: "direct_post";
+  "direct_post.jwt": "direct_post.jwt";
+}>;
+declare const VerifierClientMetadataSchema: z.ZodObject<{
+  jwks: z.ZodOptional<z.ZodObject<{
+    keys: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>>;
+  encrypted_response_enc_values_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  vp_formats_supported: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+declare const OpenId4VpRequestSchema: z.ZodObject<{
+  client_id: z.ZodString;
+  nonce: z.ZodString;
+  dcql_query: z.ZodUnknown;
+  state: z.ZodOptional<z.ZodString>;
+  response_type: z.ZodOptional<z.ZodLiteral<"vp_token">>;
+  response_mode: z.ZodOptional<z.ZodEnum<{
+    direct_post: "direct_post";
+    "direct_post.jwt": "direct_post.jwt";
+  }>>;
+  response_uri: z.ZodOptional<z.ZodString>;
+  client_metadata: z.ZodOptional<z.ZodObject<{
+    jwks: z.ZodOptional<z.ZodObject<{
+      keys: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    encrypted_response_enc_values_supported: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    vp_formats_supported: z.ZodOptional<z.ZodUnknown>;
+  }, z.core.$loose>>;
+  scope: z.ZodOptional<z.ZodUnknown>;
+  presentation_definition: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+declare const WalletConfigSchema: z.ZodObject<{
+  storage: z.ZodCustom<unknown, unknown>;
+}, z.core.$strip>;
+type HolderKeyRecord = z.infer<typeof HolderKeyRecordSchema>;
+type CredentialStatus = z.infer<typeof CredentialStatusSchema>;
+type CredentialStatusListReference = z.infer<typeof CredentialStatusListReferenceSchema>;
+type StoredCredentialRecord = z.infer<typeof StoredCredentialRecordSchema>;
+type IssuerKeyMaterial = z.infer<typeof IssuerKeyMaterialSchema>;
+type ImportCredentialInput = z.infer<typeof ImportCredentialInputSchema>;
+type OpenId4VpRequestInput = z.infer<typeof OpenId4VpRequestSchema>;
+type VerifierClientMetadata = z.infer<typeof VerifierClientMetadataSchema>;
+type ParsedDcqlQuery = ReturnType<typeof DcqlQuery.parse>;
+//#endregion
+//#region src/crypto.d.ts
+declare const HOLDER_KEY_ALG = "ES256";
+declare const SD_JWT_HASH_ALG = "sha-256";
+type ImportedJwkKey = Awaited<ReturnType<typeof importJWK>>;
+declare function sha256Base64Url(input: string): Promise<string>;
+declare function sdJwtHasher(data: string | ArrayBuffer, alg: string): Promise<Uint8Array>;
+declare function createHolderKeyRecord(alg?: HolderKeyRecord["algorithm"]): Promise<HolderKeyRecord>;
+declare function getJwkThumbprint(jwk: JWK): Promise<string>;
+declare function importPrivateKey(jwk: JWK, alg?: string): Promise<ImportedJwkKey>;
+declare function importPublicKey(jwk: JWK, alg: string): Promise<ImportedJwkKey>;
+declare function createKbJwt(input: {
+  holderPrivateJwk: JWK;
+  aud: string;
+  nonce: string;
+  sdJwtPresentation: string;
+  alg?: string;
+}): Promise<string>;
+declare function createOpenId4VciProofJwt(input: {
+  holderPrivateJwk: JWK;
+  holderPublicJwk: JWK;
+  aud: string;
+  nonce: string;
+  alg?: string;
+}): Promise<string>;
+declare function issueDemoCredential(input: {
+  issuer: string;
+  issuerPrivateJwk: JWK;
+  issuerAlg?: string;
+  issuerKid?: string;
+  holderPublicJwk: JWK;
+  vct: string;
+  claims: Record<string, unknown>;
+  disclosureFrame?: Record<string, unknown>;
+  headers?: JWTHeaderParameters;
+  issuedAt?: number;
+  saltGenerator?: (length: number) => Promise<string>;
+}): Promise<string>;
+//#endregion
+//#region src/storage.d.ts
+interface WalletStorage {
+  getHolderKey(): Promise<HolderKeyRecord | null>;
+  setHolderKey(record: HolderKeyRecord): Promise<void>;
+  listCredentials(): Promise<StoredCredentialRecord[]>;
+  getCredential(id: string): Promise<StoredCredentialRecord | null>;
+  setCredential(record: StoredCredentialRecord): Promise<void>;
+}
+declare class InMemoryWalletStorage implements WalletStorage {
+  private holderKey;
+  private readonly credentials;
+  getHolderKey(): Promise<HolderKeyRecord | null>;
+  setHolderKey(record: HolderKeyRecord): Promise<void>;
+  listCredentials(): Promise<StoredCredentialRecord[]>;
+  getCredential(id: string): Promise<StoredCredentialRecord | null>;
+  setCredential(record: StoredCredentialRecord): Promise<void>;
+}
+//#endregion
+//#region src/wallet.d.ts
+declare class WalletError extends Error {
+  constructor(message: string);
+}
+type MatchedCredential = {
+  queryId: string;
+  credentialId: string;
+  issuer: string;
+  vct: string;
+  claims: Record<string, unknown>;
+  claimPaths: Array<Array<string | number | null>>;
+};
+type QueryCredentialMatches = {
+  queryId: string;
+  credentials: MatchedCredential[];
+};
+type MatchDcqlQueryResult = {
+  query: ParsedDcqlQuery;
+  credentials: MatchedCredential[];
+};
+type InspectDcqlQueryResult = {
+  query: ParsedDcqlQuery;
+  queries: QueryCredentialMatches[];
+};
+type CreatePresentationResult = {
+  query: ParsedDcqlQuery;
+  vpToken: string;
+  dcqlPresentation: Record<string, string[]>;
+  matchedCredentials: MatchedCredential[];
+};
+type TokenStatusLabel = "VALID" | "INVALID" | "SUSPENDED" | "APPLICATION_SPECIFIC" | "UNASSIGNED";
+type ResolvedCredentialStatus = {
+  credentialId: string;
+  statusReference: CredentialStatus["status_list"];
+  status: {
+    value: number;
+    label: TokenStatusLabel;
+    isValid: boolean;
+  };
+  statusList: {
+    uri: string;
+    bits: 1 | 2 | 4 | 8;
+    iat: number;
+    exp?: number;
+    ttl?: number;
+    aggregationUri?: string;
+    jwt: string;
+  };
+};
+declare class Wallet {
+  private readonly storage;
+  constructor(storage: WalletStorage);
+  getOrCreateHolderKey(alg?: HolderKeyRecord["algorithm"]): Promise<HolderKeyRecord>;
+  importHolderKey(input: {
+    privateJwk: Record<string, unknown>;
+    publicJwk: Record<string, unknown>;
+    algorithm: string;
+  }): Promise<HolderKeyRecord>;
+  listCredentials(): Promise<StoredCredentialRecord[]>;
+  getCredentialStatus(credentialId: string, options?: {
+    fetch?: typeof fetch;
+  }): Promise<ResolvedCredentialStatus | null>;
+  getVpFormatsSupported(): {
+    "dc+sd-jwt": {
+      kb_jwt_alg_values: string[];
+      sd_jwt_alg_values: string[];
+    };
+  };
+  importCredential(input: ImportCredentialInput): Promise<StoredCredentialRecord>;
+  matchDcqlQuery(input: OpenId4VpRequestInput): Promise<MatchDcqlQueryResult>;
+  inspectDcqlQuery(input: OpenId4VpRequestInput): Promise<InspectDcqlQueryResult>;
+  createPresentation(input: OpenId4VpRequestInput, options?: {
+    selectedCredentials?: Record<string, string>;
+  }): Promise<CreatePresentationResult>;
+}
+//#endregion
+//#region src/openid4vci.d.ts
+declare const credentialOfferSchema: z.ZodObject<{
+  credential_issuer: z.ZodString;
+  credential_configuration_ids: z.ZodArray<z.ZodString>;
+  grants: z.ZodObject<{
+    "urn:ietf:params:oauth:grant-type:pre-authorized_code": z.ZodObject<{
+      "pre-authorized_code": z.ZodString;
+      tx_code: z.ZodOptional<z.ZodNever>;
+    }, z.core.$strip>;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+declare const issuerMetadataSchema: z.ZodObject<{
+  credential_issuer: z.ZodString;
+  token_endpoint: z.ZodString;
+  credential_endpoint: z.ZodString;
+  nonce_endpoint: z.ZodOptional<z.ZodString>;
+  jwks: z.ZodObject<{
+    keys: z.ZodArray<z.ZodObject<{
+      kty: z.ZodString;
+      kid: z.ZodOptional<z.ZodString>;
+      alg: z.ZodOptional<z.ZodString>;
+      crv: z.ZodOptional<z.ZodString>;
+      x: z.ZodOptional<z.ZodString>;
+      y: z.ZodOptional<z.ZodString>;
+      d: z.ZodOptional<z.ZodString>;
+      n: z.ZodOptional<z.ZodString>;
+      e: z.ZodOptional<z.ZodString>;
+      x5c: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$catchall<z.ZodUnknown>>>;
+  }, z.core.$strip>;
+  credential_configurations_supported: z.ZodRecord<z.ZodString, z.ZodObject<{
+    format: z.ZodLiteral<"dc+sd-jwt">;
+    vct: z.ZodString;
+    scope: z.ZodString;
+    proof_types_supported: z.ZodObject<{
+      jwt: z.ZodObject<{
+        proof_signing_alg_values_supported: z.ZodArray<z.ZodString>;
+      }, z.core.$strip>;
+    }, z.core.$strip>;
+    credential_signing_alg_values_supported: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type OpenId4VciCredentialOffer = z.infer<typeof credentialOfferSchema>;
+type OpenId4VciIssuerMetadata = z.infer<typeof issuerMetadataSchema>;
+declare function parseCredentialOffer(input: unknown): OpenId4VciCredentialOffer;
+declare function fetchIssuerMetadata(credentialIssuer: string, options?: {
+  fetch?: typeof fetch;
+}): Promise<OpenId4VciIssuerMetadata>;
+declare function receiveCredentialFromOffer(wallet: Wallet, offerInput: unknown, options?: {
+  fetch?: typeof fetch;
+}): Promise<StoredCredentialRecord>;
+//#endregion
+//#region src/openid4vp.d.ts
+type OpenId4VpAuthorizationResponse = {
+  vp_token: string;
+  state?: string;
+};
+type OpenId4VpResponseSubmissionResult = {
+  responseMode: "direct_post" | "direct_post.jwt";
+  responseUri: string;
+  status: number;
+  body?: unknown;
+  redirectUri?: string;
+};
+declare function parseOpenid4VpAuthorizationUrl(input: string): Promise<OpenId4VpRequestInput>;
+declare function resolveOpenId4VpRequest(input: unknown): Promise<OpenId4VpRequestInput>;
+declare function createOpenId4VpAuthorizationResponse(request: OpenId4VpRequestInput, presentation: CreatePresentationResult): OpenId4VpAuthorizationResponse;
+declare function submitOpenId4VpAuthorizationResponse(request: OpenId4VpRequestInput, response: OpenId4VpAuthorizationResponse): Promise<OpenId4VpResponseSubmissionResult>;
+//#endregion
+export { CreatePresentationResult, CredentialStatus, CredentialStatusListReference, CredentialStatusListReferenceSchema, CredentialStatusSchema, HOLDER_KEY_ALG, HolderKeyRecord, HolderKeyRecordSchema, ImportCredentialInput, ImportCredentialInputSchema, InMemoryWalletStorage, InspectDcqlQueryResult, IssuerJwkSchema, IssuerJwksSchema, IssuerKeyMaterial, IssuerKeyMaterialSchema, JwkSchema, MatchDcqlQueryResult, MatchedCredential, OpenId4VciCredentialOffer, OpenId4VciIssuerMetadata, OpenId4VpAuthorizationResponse, OpenId4VpRequestInput, OpenId4VpRequestSchema, OpenId4VpResponseSubmissionResult, ParsedDcqlQuery, QueryCredentialMatches, ResolvedCredentialStatus, ResponseModeSchema, SD_JWT_HASH_ALG, StoredCredentialRecord, StoredCredentialRecordSchema, TokenStatusLabel, VerifierClientMetadata, VerifierClientMetadataSchema, Wallet, WalletConfigSchema, WalletError, WalletStorage, createHolderKeyRecord, createKbJwt, createOpenId4VciProofJwt, createOpenId4VpAuthorizationResponse, fetchIssuerMetadata, getJwkThumbprint, importPrivateKey, importPublicKey, issueDemoCredential, parseCredentialOffer, parseOpenid4VpAuthorizationUrl, receiveCredentialFromOffer, resolveOpenId4VpRequest, sdJwtHasher, sha256Base64Url, submitOpenId4VpAuthorizationResponse };