@sirosfoundation/dc-api 0.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, SIROS Foundation
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,128 @@
+# @sirosfoundation/dc-api
+
+W3C Digital Credentials API utilities for OpenID4VP.
+
+Zero-dependency, backend-agnostic library providing:
+
+- **Protocol constants** — versioned OpenID4VP protocol identifiers per the W3C DC API spec
+- **Feature detection** — check DC API availability and protocol support
+- **Native DC API invocation** — call `navigator.credentials.get()` with proper parameters
+- **Error helpers** — classify errors and generate user-friendly messages
+
+## Install
+
+```sh
+npm install @sirosfoundation/dc-api
+```
+
+A pre-built ESM bundle is also available at `dist/dc-api.bundle.js` for use in
+importmaps or environments without a bundler.
+
+## Usage
+
+### Requesting credentials
+
+```ts
+import {
+  isDCAPIAvailable,
+  getBestProtocol,
+  requestCredential,
+  isUserCancel,
+} from '@sirosfoundation/dc-api';
+
+// 1. Check if DC API + openid4vp is available
+const protocol = getBestProtocol();
+
+if (protocol) {
+  try {
+    // 2. Call the native DC API
+    const result = await requestCredential(protocol, {
+      request: signedJWT, // JAR for "openid4vp-v1-signed"
+    });
+
+    // 3. Submit result.data to your backend
+    await submitToBackend(result.data);
+  } catch (err) {
+    if (isUserCancel(err)) {
+      // User cancelled — show alternative flow
+    } else {
+      throw err;
+    }
+  }
+} else {
+  // No DC API support — use QR code / redirect fallback
+  showQRCode();
+}
+```
+
+### Protocol constants
+
+```ts
+import { OID4VP_PROTOCOLS, isOID4VPProtocol } from '@sirosfoundation/dc-api';
+
+// Use shared constants instead of hardcoding protocol strings
+const supportedProtocols = [
+  OID4VP_PROTOCOLS.UNSIGNED,
+  OID4VP_PROTOCOLS.SIGNED,
+  OID4VP_PROTOCOLS.MULTISIGNED,
+];
+
+// Type guard for filtering
+const known = requests.filter(r => isOID4VPProtocol(r.protocol));
+```
+
+## API
+
+### Protocol Constants
+
+```ts
+OID4VP_PROTOCOLS.UNSIGNED     // "openid4vp-v1-unsigned"
+OID4VP_PROTOCOLS.SIGNED       // "openid4vp-v1-signed"
+OID4VP_PROTOCOLS.MULTISIGNED  // "openid4vp-v1-multisigned"
+OID4VP_PROTOCOLS.LEGACY       // "openid4vp"
+
+OID4VP_SPEC_PROTOCOLS         // [UNSIGNED, SIGNED, MULTISIGNED]
+OID4VP_ALL_PROTOCOLS          // [UNSIGNED, SIGNED, MULTISIGNED, LEGACY]
+isOID4VPProtocol(value)       // Type guard — true for any known protocol
+```
+
+### Detection
+
+| Function | Description |
+|---|---|
+| `isDCAPIAvailable()` | `true` when `typeof DigitalCredential !== "undefined"` |
+| `isProtocolAllowed(protocol)` | Delegates to `DigitalCredential.userAgentAllowsProtocol()` |
+| `getBestProtocol(preference?)` | Returns the first allowed protocol from a preference-ordered list (default: signed > multisigned > unsigned) |
+
+### Request
+
+| Function | Description |
+|---|---|
+| `requestCredential(protocol, data, options?)` | Calls `navigator.credentials.get({digital: {requests: [{protocol, data}]}})`, returns `{ protocol, data }` |
+
+`options.signal` accepts an `AbortSignal` for cancellation.
+
+### Error Helpers
+
+| Function | Description |
+|---|---|
+| `getUserFriendlyErrorMessage(error)` | Returns a human-readable message for DC API errors |
+| `isUserCancel(error)` | `true` for `NotAllowedError` or `AbortError` |
+| `isProtocolUnsupported(error)` | `true` for `NotSupportedError` |
+| `ERROR_MESSAGES` | Map of DOMException names to user-facing strings |
+
+## Design Principles
+
+- **Zero dependencies** — no runtime dependencies
+- **Backend-agnostic** — no knowledge of specific verifier or wallet endpoints
+- **Transport-agnostic** — no QR codes, redirects, or SSE; those belong in the consumer
+- **Spec-aligned** — uses the W3C DC API spec's detection and invocation patterns exactly
+
+## References
+
+- [W3C Digital Credentials API](https://w3c-fedid.github.io/digital-credentials/)
+- [OpenID4VP (DC API profile)](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html)
+
+## License
+
+BSD-2-Clause

package/dist/dc-api.bundle.js

@@ -0,0 +1,106 @@
+// src/protocols.ts
+const OID4VP_PROTOCOLS = {
+  /** Unsigned request — client_id derived from web-origin */
+  UNSIGNED: "openid4vp-v1-unsigned",
+  /** Signed request — JAR with single JWS compact serialization */
+  SIGNED: "openid4vp-v1-signed",
+  /** Multi-signed request — JWS JSON serialization */
+  MULTISIGNED: "openid4vp-v1-multisigned",
+  /** Legacy protocol string (pre-spec, used by some implementations) */
+  LEGACY: "openid4vp"
+};
+const OID4VP_SPEC_PROTOCOLS = [
+  OID4VP_PROTOCOLS.UNSIGNED,
+  OID4VP_PROTOCOLS.SIGNED,
+  OID4VP_PROTOCOLS.MULTISIGNED
+];
+const OID4VP_ALL_PROTOCOLS = [
+  ...OID4VP_SPEC_PROTOCOLS,
+  OID4VP_PROTOCOLS.LEGACY
+];
+
+// src/detect.ts
+function isDCAPIAvailable() {
+  return typeof DigitalCredential !== "undefined";
+}
+function isProtocolAllowed(protocol) {
+  if (typeof DigitalCredential === "undefined") return false;
+  if (typeof DigitalCredential.userAgentAllowsProtocol !== "function") return false;
+  return DigitalCredential.userAgentAllowsProtocol(protocol);
+}
+const DEFAULT_PREFERENCE = [
+  OID4VP_PROTOCOLS.SIGNED,
+  OID4VP_PROTOCOLS.MULTISIGNED,
+  OID4VP_PROTOCOLS.UNSIGNED
+];
+function getBestProtocol(preference) {
+  const candidates = preference ?? DEFAULT_PREFERENCE;
+  for (const proto of candidates) {
+    if (isProtocolAllowed(proto)) return proto;
+  }
+  return null;
+}
+
+// src/request.ts
+async function requestCredential(protocol, data, options) {
+  const dcOptions = {
+    digital: {
+      requests: [{
+        protocol,
+        data
+      }]
+    }
+  };
+  if (options?.signal) {
+    dcOptions.signal = options.signal;
+  }
+  const credential = await navigator.credentials.get(dcOptions);
+  if (!credential) {
+    throw new DOMException("No credential received", "NotAllowedError");
+  }
+  return normalizeCredential(credential, protocol);
+}
+function normalizeCredential(credential, fallbackProtocol) {
+  const dc = credential;
+  return {
+    protocol: dc.protocol ?? fallbackProtocol,
+    data: dc.data ?? credential
+  };
+}
+
+// src/errors.ts
+const ERROR_MESSAGES = {
+  NotAllowedError: "You denied the credential request or no wallet is available.",
+  NotSupportedError: "Your browser or wallet does not support this credential type.",
+  SecurityError: "Security error \u2014 ensure you are on HTTPS.",
+  AbortError: "The request was cancelled or timed out.",
+  InvalidStateError: "A credential request is already in progress.",
+  TypeError: "The credential request data is malformed."
+};
+const DEFAULT_MESSAGE = "An unexpected error occurred. Please try again.";
+function getUserFriendlyErrorMessage(error) {
+  if (error instanceof DOMException) {
+    return ERROR_MESSAGES[error.name] ?? DEFAULT_MESSAGE;
+  }
+  if (error instanceof Error) {
+    return ERROR_MESSAGES[error.name] ?? DEFAULT_MESSAGE;
+  }
+  return DEFAULT_MESSAGE;
+}
+function isUserCancel(error) {
+  return error instanceof DOMException && (error.name === "NotAllowedError" || error.name === "AbortError");
+}
+function isProtocolUnsupported(error) {
+  return error instanceof DOMException && error.name === "NotSupportedError";
+}
+export {
+  ERROR_MESSAGES,
+  OID4VP_PROTOCOLS,
+  getBestProtocol,
+  getUserFriendlyErrorMessage,
+  isDCAPIAvailable,
+  isProtocolAllowed,
+  isProtocolUnsupported,
+  isUserCancel,
+  requestCredential
+};

package/dist/detect.d.ts

@@ -0,0 +1,57 @@
+/**
+ * DC API feature detection.
+ *
+ * (a) isDCAPIAvailable() — checks typeof DigitalCredential !== "undefined"
+ *     Per spec §2.1.
+ *
+ * (b) isProtocolAllowed(protocol) — calls DigitalCredential.userAgentAllowsProtocol()
+ *     Per spec §2.2, §7.7.3. Returns false safely for unknown protocols.
+ *
+ * (c) getBestProtocol(preference?) — finds the best supported protocol
+ *     from a preference-ordered list.
+ */
+import { type OID4VPProtocol } from './protocols.js';
+/**
+ * Check if the W3C Digital Credentials API is available in this browser.
+ *
+ * Returns true when:
+ *   - Chrome 141+ (native)
+ *   - Safari/iOS 26+ (native, but may only support org-iso-mdoc)
+ *   - Any browser with wallet-companion installed (shims DigitalCredential)
+ */
+export declare function isDCAPIAvailable(): boolean;
+/**
+ * Check if the browser allows a specific protocol for digital credentials.
+ *
+ * Uses the static method DigitalCredential.userAgentAllowsProtocol()
+ * defined in the DC API spec §7.7.3.
+ *
+ * Returns false safely when:
+ *   - DigitalCredential is not defined
+ *   - userAgentAllowsProtocol is not implemented
+ *   - The protocol is unknown to the browser
+ *
+ * NOTE: This method reflects browser capability, NOT wallet availability.
+ * A true result means the browser will accept the protocol in a
+ * navigator.credentials.get() call, but a wallet must still be present
+ * to fulfill the request.
+ */
+export declare function isProtocolAllowed(protocol: string): boolean;
+/**
+ * Find the best OpenID4VP protocol supported by this browser.
+ *
+ * @param preference  Ordered list of protocols to try (most preferred first).
+ *                    Defaults to [SIGNED, MULTISIGNED, UNSIGNED].
+ * @returns The first allowed protocol, or null if none are supported.
+ *
+ * @example
+ * ```ts
+ * const protocol = getBestProtocol();
+ * if (protocol) {
+ *   const result = await requestCredential(protocol, requestData);
+ * } else {
+ *   // No DC API support for OpenID4VP — use QR/redirect fallback
+ * }
+ * ```
+ */
+export declare function getBestProtocol(preference?: readonly string[]): OID4VPProtocol | null;

package/dist/detect.js

@@ -0,0 +1,81 @@
+/**
+ * DC API feature detection.
+ *
+ * (a) isDCAPIAvailable() — checks typeof DigitalCredential !== "undefined"
+ *     Per spec §2.1.
+ *
+ * (b) isProtocolAllowed(protocol) — calls DigitalCredential.userAgentAllowsProtocol()
+ *     Per spec §2.2, §7.7.3. Returns false safely for unknown protocols.
+ *
+ * (c) getBestProtocol(preference?) — finds the best supported protocol
+ *     from a preference-ordered list.
+ */
+import { OID4VP_PROTOCOLS } from './protocols.js';
+/**
+ * Check if the W3C Digital Credentials API is available in this browser.
+ *
+ * Returns true when:
+ *   - Chrome 141+ (native)
+ *   - Safari/iOS 26+ (native, but may only support org-iso-mdoc)
+ *   - Any browser with wallet-companion installed (shims DigitalCredential)
+ */
+export function isDCAPIAvailable() {
+    return typeof DigitalCredential !== 'undefined';
+}
+/**
+ * Check if the browser allows a specific protocol for digital credentials.
+ *
+ * Uses the static method DigitalCredential.userAgentAllowsProtocol()
+ * defined in the DC API spec §7.7.3.
+ *
+ * Returns false safely when:
+ *   - DigitalCredential is not defined
+ *   - userAgentAllowsProtocol is not implemented
+ *   - The protocol is unknown to the browser
+ *
+ * NOTE: This method reflects browser capability, NOT wallet availability.
+ * A true result means the browser will accept the protocol in a
+ * navigator.credentials.get() call, but a wallet must still be present
+ * to fulfill the request.
+ */
+export function isProtocolAllowed(protocol) {
+    if (typeof DigitalCredential === 'undefined')
+        return false;
+    if (typeof DigitalCredential.userAgentAllowsProtocol !== 'function')
+        return false;
+    return DigitalCredential.userAgentAllowsProtocol(protocol);
+}
+/**
+ * Default protocol preference order.
+ * Signed first (most verifiers use JAR), then multisigned, then unsigned.
+ */
+const DEFAULT_PREFERENCE = [
+    OID4VP_PROTOCOLS.SIGNED,
+    OID4VP_PROTOCOLS.MULTISIGNED,
+    OID4VP_PROTOCOLS.UNSIGNED,
+];
+/**
+ * Find the best OpenID4VP protocol supported by this browser.
+ *
+ * @param preference  Ordered list of protocols to try (most preferred first).
+ *                    Defaults to [SIGNED, MULTISIGNED, UNSIGNED].
+ * @returns The first allowed protocol, or null if none are supported.
+ *
+ * @example
+ * ```ts
+ * const protocol = getBestProtocol();
+ * if (protocol) {
+ *   const result = await requestCredential(protocol, requestData);
+ * } else {
+ *   // No DC API support for OpenID4VP — use QR/redirect fallback
+ * }
+ * ```
+ */
+export function getBestProtocol(preference) {
+    const candidates = preference ?? DEFAULT_PREFERENCE;
+    for (const proto of candidates) {
+        if (isProtocolAllowed(proto))
+            return proto;
+    }
+    return null;
+}

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Error classification and user-friendly messages for DC API errors.
+ */
+/**
+ * User-friendly error messages keyed by DOMException name.
+ */
+export declare const ERROR_MESSAGES: Record<string, string>;
+/**
+ * Get a user-friendly message for a DC API error.
+ */
+export declare function getUserFriendlyErrorMessage(error: unknown): string;
+/**
+ * Check if the error represents a user cancellation (not a failure).
+ */
+export declare function isUserCancel(error: unknown): boolean;
+/**
+ * Check if the error means the protocol is not supported by this browser.
+ */
+export declare function isProtocolUnsupported(error: unknown): boolean;

package/dist/errors.js

@@ -0,0 +1,40 @@
+/**
+ * Error classification and user-friendly messages for DC API errors.
+ */
+/**
+ * User-friendly error messages keyed by DOMException name.
+ */
+export const ERROR_MESSAGES = {
+    NotAllowedError: 'You denied the credential request or no wallet is available.',
+    NotSupportedError: 'Your browser or wallet does not support this credential type.',
+    SecurityError: 'Security error — ensure you are on HTTPS.',
+    AbortError: 'The request was cancelled or timed out.',
+    InvalidStateError: 'A credential request is already in progress.',
+    TypeError: 'The credential request data is malformed.',
+};
+const DEFAULT_MESSAGE = 'An unexpected error occurred. Please try again.';
+/**
+ * Get a user-friendly message for a DC API error.
+ */
+export function getUserFriendlyErrorMessage(error) {
+    if (error instanceof DOMException) {
+        return ERROR_MESSAGES[error.name] ?? DEFAULT_MESSAGE;
+    }
+    if (error instanceof Error) {
+        return ERROR_MESSAGES[error.name] ?? DEFAULT_MESSAGE;
+    }
+    return DEFAULT_MESSAGE;
+}
+/**
+ * Check if the error represents a user cancellation (not a failure).
+ */
+export function isUserCancel(error) {
+    return (error instanceof DOMException &&
+        (error.name === 'NotAllowedError' || error.name === 'AbortError'));
+}
+/**
+ * Check if the error means the protocol is not supported by this browser.
+ */
+export function isProtocolUnsupported(error) {
+    return error instanceof DOMException && error.name === 'NotSupportedError';
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @sirosfoundation/dc-api
+ *
+ * W3C Digital Credentials API utilities for OpenID4VP.
+ *
+ * Backend-agnostic library providing:
+ *   - Protocol constants (versioned OpenID4VP protocol identifiers)
+ *   - DC API feature detection (API availability + protocol support)
+ *   - Native DC API invocation with response normalization
+ *   - Error classification helpers
+ *
+ * Does NOT include:
+ *   - Fallback transports (QR, redirect, SSE, polling) — those are verifier-specific
+ *   - Wallet popup management — that's the wallet-companion's job
+ *   - Backend endpoint URLs — pass your own
+ *
+ * References:
+ *   - W3C Digital Credentials API: https://w3c-fedid.github.io/digital-credentials/
+ *   - OpenID4VP (DC API profile): https://openid.net/specs/openid-4-verifiable-presentations-1_0.html
+ */
+export { OID4VP_PROTOCOLS, type OID4VPProtocol } from './protocols.js';
+export { isDCAPIAvailable, isProtocolAllowed, getBestProtocol, } from './detect.js';
+export { requestCredential, type DigitalCredentialResponse, type RequestCredentialOptions, } from './request.js';
+export { getUserFriendlyErrorMessage, isUserCancel, isProtocolUnsupported, ERROR_MESSAGES, } from './errors.js';

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * @sirosfoundation/dc-api
+ *
+ * W3C Digital Credentials API utilities for OpenID4VP.
+ *
+ * Backend-agnostic library providing:
+ *   - Protocol constants (versioned OpenID4VP protocol identifiers)
+ *   - DC API feature detection (API availability + protocol support)
+ *   - Native DC API invocation with response normalization
+ *   - Error classification helpers
+ *
+ * Does NOT include:
+ *   - Fallback transports (QR, redirect, SSE, polling) — those are verifier-specific
+ *   - Wallet popup management — that's the wallet-companion's job
+ *   - Backend endpoint URLs — pass your own
+ *
+ * References:
+ *   - W3C Digital Credentials API: https://w3c-fedid.github.io/digital-credentials/
+ *   - OpenID4VP (DC API profile): https://openid.net/specs/openid-4-verifiable-presentations-1_0.html
+ */
+export { OID4VP_PROTOCOLS } from './protocols.js';
+export { isDCAPIAvailable, isProtocolAllowed, getBestProtocol, } from './detect.js';
+export { requestCredential, } from './request.js';
+export { getUserFriendlyErrorMessage, isUserCancel, isProtocolUnsupported, ERROR_MESSAGES, } from './errors.js';

package/dist/protocols.d.ts

@@ -0,0 +1,34 @@
+/**
+ * W3C DigitalCredentialPresentationProtocol enum values for OpenID4VP.
+ *
+ * Per the DC API spec (§5, §7.8.2), protocol strings are versioned:
+ *   "openid4vp-v1-unsigned"    — unsigned request (client_id from origin)
+ *   "openid4vp-v1-signed"     — signed request (JAR with single signature)
+ *   "openid4vp-v1-multisigned" — multi-signed request (JWS JSON Serialization)
+ *
+ * The legacy "openid4vp" string is NOT a valid DC API protocol identifier
+ * but is included for compatibility with older implementations.
+ */
+export declare const OID4VP_PROTOCOLS: {
+    /** Unsigned request — client_id derived from web-origin */
+    readonly UNSIGNED: "openid4vp-v1-unsigned";
+    /** Signed request — JAR with single JWS compact serialization */
+    readonly SIGNED: "openid4vp-v1-signed";
+    /** Multi-signed request — JWS JSON serialization */
+    readonly MULTISIGNED: "openid4vp-v1-multisigned";
+    /** Legacy protocol string (pre-spec, used by some implementations) */
+    readonly LEGACY: "openid4vp";
+};
+export type OID4VPProtocol = (typeof OID4VP_PROTOCOLS)[keyof typeof OID4VP_PROTOCOLS];
+/**
+ * All spec-defined OpenID4VP protocol identifiers (excludes legacy).
+ */
+export declare const OID4VP_SPEC_PROTOCOLS: readonly OID4VPProtocol[];
+/**
+ * All protocol identifiers including legacy.
+ */
+export declare const OID4VP_ALL_PROTOCOLS: readonly OID4VPProtocol[];
+/**
+ * Check if a string is a known OpenID4VP protocol identifier.
+ */
+export declare function isOID4VPProtocol(value: unknown): value is OID4VPProtocol;

package/dist/protocols.js

@@ -0,0 +1,42 @@
+/**
+ * W3C DigitalCredentialPresentationProtocol enum values for OpenID4VP.
+ *
+ * Per the DC API spec (§5, §7.8.2), protocol strings are versioned:
+ *   "openid4vp-v1-unsigned"    — unsigned request (client_id from origin)
+ *   "openid4vp-v1-signed"     — signed request (JAR with single signature)
+ *   "openid4vp-v1-multisigned" — multi-signed request (JWS JSON Serialization)
+ *
+ * The legacy "openid4vp" string is NOT a valid DC API protocol identifier
+ * but is included for compatibility with older implementations.
+ */
+export const OID4VP_PROTOCOLS = {
+    /** Unsigned request — client_id derived from web-origin */
+    UNSIGNED: 'openid4vp-v1-unsigned',
+    /** Signed request — JAR with single JWS compact serialization */
+    SIGNED: 'openid4vp-v1-signed',
+    /** Multi-signed request — JWS JSON serialization */
+    MULTISIGNED: 'openid4vp-v1-multisigned',
+    /** Legacy protocol string (pre-spec, used by some implementations) */
+    LEGACY: 'openid4vp',
+};
+/**
+ * All spec-defined OpenID4VP protocol identifiers (excludes legacy).
+ */
+export const OID4VP_SPEC_PROTOCOLS = [
+    OID4VP_PROTOCOLS.UNSIGNED,
+    OID4VP_PROTOCOLS.SIGNED,
+    OID4VP_PROTOCOLS.MULTISIGNED,
+];
+/**
+ * All protocol identifiers including legacy.
+ */
+export const OID4VP_ALL_PROTOCOLS = [
+    ...OID4VP_SPEC_PROTOCOLS,
+    OID4VP_PROTOCOLS.LEGACY,
+];
+/**
+ * Check if a string is a known OpenID4VP protocol identifier.
+ */
+export function isOID4VPProtocol(value) {
+    return OID4VP_ALL_PROTOCOLS.includes(value);
+}

package/dist/request.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Native DC API credential request.
+ *
+ * Calls navigator.credentials.get() with the DC API options:
+ *   { digital: { requests: [{ protocol, data }] } }
+ *
+ * This module is backend-agnostic — it only handles the browser API call
+ * and response normalization. Fallback transports (QR, redirect, SSE)
+ * are the consumer's responsibility.
+ */
+import type { OID4VPProtocol } from './protocols.js';
+/**
+ * Normalized response from a DC API credential request.
+ */
+export interface DigitalCredentialResponse {
+    /** The protocol used for this credential exchange */
+    protocol: string;
+    /** The credential response data (opaque to this library) */
+    data: unknown;
+}
+/**
+ * Options for requestCredential().
+ */
+export interface RequestCredentialOptions {
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Request a credential via the native DC API.
+ *
+ * @param protocol  The protocol identifier (e.g. "openid4vp-v1-signed")
+ * @param data      The request data object. For JAR: { request: "<JWT>" }.
+ *                  For unsigned: the individual OID4VP parameters as an object.
+ * @param options   Optional AbortSignal for cancellation.
+ * @returns A normalized { protocol, data } response.
+ * @throws DOMException with name "NotAllowedError" if user cancels
+ * @throws DOMException with name "NotSupportedError" if protocol unsupported
+ *
+ * @example
+ * ```ts
+ * // Signed request (JAR)
+ * const result = await requestCredential("openid4vp-v1-signed", {
+ *   request: signedJWT,
+ * });
+ *
+ * // Unsigned request
+ * const result = await requestCredential("openid4vp-v1-unsigned", {
+ *   response_type: "vp_token",
+ *   nonce: "abc123",
+ *   dcql_query: { credentials: [...] },
+ * });
+ * ```
+ */
+export declare function requestCredential(protocol: OID4VPProtocol | string, data: object, options?: RequestCredentialOptions): Promise<DigitalCredentialResponse>;

package/dist/request.js

@@ -0,0 +1,65 @@
+/**
+ * Native DC API credential request.
+ *
+ * Calls navigator.credentials.get() with the DC API options:
+ *   { digital: { requests: [{ protocol, data }] } }
+ *
+ * This module is backend-agnostic — it only handles the browser API call
+ * and response normalization. Fallback transports (QR, redirect, SSE)
+ * are the consumer's responsibility.
+ */
+/**
+ * Request a credential via the native DC API.
+ *
+ * @param protocol  The protocol identifier (e.g. "openid4vp-v1-signed")
+ * @param data      The request data object. For JAR: { request: "<JWT>" }.
+ *                  For unsigned: the individual OID4VP parameters as an object.
+ * @param options   Optional AbortSignal for cancellation.
+ * @returns A normalized { protocol, data } response.
+ * @throws DOMException with name "NotAllowedError" if user cancels
+ * @throws DOMException with name "NotSupportedError" if protocol unsupported
+ *
+ * @example
+ * ```ts
+ * // Signed request (JAR)
+ * const result = await requestCredential("openid4vp-v1-signed", {
+ *   request: signedJWT,
+ * });
+ *
+ * // Unsigned request
+ * const result = await requestCredential("openid4vp-v1-unsigned", {
+ *   response_type: "vp_token",
+ *   nonce: "abc123",
+ *   dcql_query: { credentials: [...] },
+ * });
+ * ```
+ */
+export async function requestCredential(protocol, data, options) {
+    const dcOptions = {
+        digital: {
+            requests: [{
+                    protocol,
+                    data,
+                }],
+        },
+    };
+    if (options?.signal) {
+        dcOptions.signal = options.signal;
+    }
+    const credential = await navigator.credentials.get(dcOptions);
+    if (!credential) {
+        throw new DOMException('No credential received', 'NotAllowedError');
+    }
+    return normalizeCredential(credential, protocol);
+}
+/**
+ * Normalize a Credential into our standard response shape.
+ */
+function normalizeCredential(credential, fallbackProtocol) {
+    // The DC API returns a DigitalCredential with .protocol and .data
+    const dc = credential;
+    return {
+        protocol: dc.protocol ?? fallbackProtocol,
+        data: dc.data ?? credential,
+    };
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@sirosfoundation/dc-api",
+  "version": "0.1.0",
+  "description": "W3C Digital Credentials API utilities for OpenID4VP — detection, protocol constants, and native DC API invocation",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./bundle": {
+      "import": "./dist/dc-api.bundle.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && npm run bundle",
+    "bundle": "esbuild src/index.ts --bundle --format=esm --target=es2022 --outfile=dist/dc-api.bundle.js && sed -i 's/^var /const /g' dist/dc-api.bundle.js",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.1",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.0"
+  },
+  "license": "BSD-2-Clause",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sirosfoundation/dc-api.git"
+  },
+  "keywords": [
+    "digital-credentials",
+    "dc-api",
+    "openid4vp",
+    "verifiable-credentials",
+    "w3c"
+  ]
+}