@ewqwe/digital-identity 1.1.1

package/LICENSE

@@ -0,0 +1,12 @@
+MIT License
+Copyright (c) 2026 NILIMI SAS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# @ewqwe/digital-identity
+
+npm-compatible JavaScript/TypeScript library for EU Digital Identity (OpenID4VP, DCQL, mDoc, SD-JWT VC).
+
+Part of the [ewQwe TypeScript workspace](../README.md). When used inside the workspace the
+library is resolved via pnpm's `workspace:*` protocol. Published to npm for external consumers.
+
+## Installation
+
+### As an npm dependency (external consumer)
+
+```bash
+npm install @ewqwe/digital-identity
+```
+
+### Inside the pnpm workspace
+
+```bash
+# From typescript/ root — build the library
+pnpm --filter @ewqwe/digital-identity build
+```
+
+The library is linked into consumers via `workspace:*` in the workspace root.
+
+## Usage
+
+### CommonJS
+
+```javascript
+const { buildAgeVerificationQuery, generateNonce } = require('@ewqwe/digital-identity');
+
+const query = buildAgeVerificationQuery(18);
+const nonce = generateNonce();
+```
+
+### ES Modules
+
+```javascript
+import { buildAgeVerificationQuery, generateNonce } from '@ewqwe/digital-identity';
+
+const query = buildAgeVerificationQuery(18);
+const nonce = generateNonce();
+```
+
+## Features
+
+- **DCQL Query Builders**: Build Digital Credentials Query Language queries for OpenID4VP.
+- **Credential Types**: Pre-configured credential types (mDL, PID, Proof of Age, etc.) with associated claims.
+- **Protocol Profiles**: HAIP and Annex A profile support.
+- **Attestation Verification**: JWT signature verification using the Web Crypto API in browsers and Node.js.
+- **Type Definitions**: Full TypeScript support with comprehensive type safety.
+
+## Quick Start
+
+### Generate an age verification query
+
+```javascript
+import { buildAgeVerificationQuery } from '@ewqwe/digital-identity';
+
+// Generate query for age 18+
+const query = buildAgeVerificationQuery(18);
+console.log(JSON.stringify(query, null, 2));
+
+// Generate query for age 21+
+const query21 = buildAgeVerificationQuery(21);
+```
+
+### Build an Init Transaction Request
+
+```javascript
+import { buildInitTransactionRequest } from '@ewqwe/digital-identity';
+
+const request = buildInitTransactionRequest(
+  'https://example.com',
+  'mdl',
+  ['given_name', 'family_name', 'birth_date']
+);
+```
+
+### Generate a Cryptographic Nonce
+
+```javascript
+import { generateNonce } from '@ewqwe/digital-identity';
+
+const nonce = generateNonce();
+// Returns a base64url-encoded 32-byte random value
+```
+
+### Validate a DCQL Query
+
+```javascript
+import { isValidDCQLQuery, buildAgeVerificationQuery } from '@ewqwe/digital-identity';
+
+const query = buildAgeVerificationQuery(18);
+const validation = isValidDCQLQuery(query);
+
+if (validation.valid) {
+  console.log('Valid DCQL query');
+} else {
+  console.error('Invalid:', validation.error);
+}
+```
+
+## API Reference
+
+### DCQL Query Functions
+
+| Function | Description |
+|----------|-------------|
+| `buildAgeVerificationQuery(ageThreshold)` | Build minimal age verification query |
+| `buildAgeVerificationQueryWithFallback(ageThreshold)` | Build query with mDL fallback |
+| `buildInitTransactionRequest(publicUrl, credentialType, claims)` | Build init transaction request |
+| `getDefaultAgeVerificationDCQL()` | Get default age verification query |
+| `determineProfile(credentialType, explicitProfile)` | Determine protocol profile |
+| `generateNonce()` | Generate cryptographic nonce |
+| `isValidDCQLQuery(query)` | Validate DCQL query structure |
+| `parseDCQLQuery(queryString)` | Parse DCQL from JSON string |
+| `extractAgeThreshold(query)` | Extract age threshold from query |
+
+### Credential Types
+
+```javascript
+import { CREDENTIAL_TYPES, getClaimsForType } from '@ewqwe/digital-identity';
+
+// Get all credential types
+const types = Object.keys(CREDENTIAL_TYPES);
+
+// Get claims for a specific type
+const mdlClaims = getClaimsForType('mdl');
+```
+
+### Protocol Profiles
+
+```javascript
+import { PROTOCOL_PROFILES, determineProfile } from '@ewqwe/digital-identity';
+
+// Get HAIP profile
+const haip = PROTOCOL_PROFILES.haip;
+
+// Determine profile for credential type
+const profile = determineProfile('mdl'); // 'haip'
+```
+
+### Attestation Verification
+
+```javascript
+import { parseAttestation, verifyAttestation } from '@ewqwe/digital-identity';
+
+// Parse and verify attestation from backend response
+const attestation = await parseAttestation(jwtToken, '/ewqwe_api/jwks');
+
+// Or verify with pre-imported public key
+const publicKey = await importVerifierPublicKey(pemOrSpki);
+const claims = await verifyAttestation(jwtToken, publicKey);
+```
+
+## API Client
+
+`@ewqwe/digital-identity` exports `EwqweApiClient` for server-side and browser client code, with a pluggable `fetch` implementation.
+
+```ts
+import { EwqweApiClient } from '@ewqwe/digital-identity';
+
+const apiClient = new EwqweApiClient({
+  baseUrl: 'https://localhost:5175',
+  fetch: window.fetch,
+});
+
+const tx = await apiClient.initOpenID4VPTransaction({
+  public_url: 'https://localhost:5174',
+  credential_type: 'proof-of-age',
+});
+
+const status = await apiClient.getOpenID4VPTransactionStatus(tx.transaction_id);
+const verify = await apiClient.verifyPresentation({
+  vp_token: '<vp_token>',
+  presentation_submission: null,
+});
+```
+
+### API client methods
+
+- `initOpenID4VPTransaction(request: InitTransactionRequest): Promise<InitTransactionResponse>`
+- `getOpenID4VPTransactionStatus(transactionId: string): Promise<TransactionStatusResult>`
+- `getOpenID4VPAuthorizationRequest(transactionId: string): Promise<OpenID4VPRequest>`
+- `postOpenID4VPAuthorizationRequest(transactionId: string, response: OpenID4VPResponse): Promise<void>`
+- `postOpenID4VPDirectPost(response: OpenID4VPResponse): Promise<void>`
+- `getOpenID4VPJwks(): Promise<{ keys: unknown[] }>`
+- `verifyPresentation(args): Promise<VerifyResponse>`
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,22 @@
+import type { InitTransactionRequest, InitTransactionResponse, OpenID4VPRequest, OpenID4VPResponse, TransactionStatusResult, VerifyRequest, VerifyResponse } from "./types.js";
+export type FetchFn = (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+export interface ApiClientOptions {
+    fetch?: FetchFn;
+    baseUrl?: string;
+}
+export declare class EwqweApiClient {
+    private fetchFn;
+    private baseUrl;
+    constructor(options?: ApiClientOptions);
+    private buildUrl;
+    private requestJson;
+    initOpenID4VPTransaction(request: InitTransactionRequest): Promise<InitTransactionResponse>;
+    getOpenID4VPTransactionStatus(transactionId: string): Promise<TransactionStatusResult>;
+    getOpenID4VPAuthorizationRequest(transactionId: string): Promise<OpenID4VPRequest>;
+    postOpenID4VPAuthorizationRequest(transactionId: string, authResponse: OpenID4VPResponse): Promise<void>;
+    postOpenID4VPDirectPost(response: OpenID4VPResponse): Promise<void>;
+    getOpenID4VPJwks(): Promise<{
+        keys: unknown[];
+    }>;
+    verifyPresentation(request: VerifyRequest): Promise<VerifyResponse>;
+}

package/dist/attestation.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Attestation JWT parsing and verification utilities.
+ *
+ * Browser- and Node-compatible — uses the Web Crypto API only (SubtleCrypto).
+ *
+ * @module
+ */
+/**
+ * Decoded payload of a credential verification attestation JWT.
+ *
+ * Standard JWT claims are typed; all credential-specific claims (e.g.
+ * `age_over_18`, `given_name`) are accessible via index signature because they
+ * are format-agnostic and defined by the credential schema, not this library.
+ */
+export interface Attestation {
+    /** Issuer — credential verifier identifier. */
+    iss: string;
+    /** Subject — transaction / attestation event ID. */
+    sub: string;
+    /** Audience — relying party identifier (client_id). */
+    aud: string;
+    /** Expiration time (Unix timestamp seconds). */
+    exp: number;
+    /** Issued at (Unix timestamp seconds). */
+    iat: number;
+    /** Not before (Unix timestamp seconds). */
+    nbf: number;
+    /** Unique attestation ID (UUID). */
+    jti: string;
+    /** Nonce from the OpenID4VP request (replay prevention). */
+    nonce?: string;
+    /** Credential doc_type (e.g. `"org.iso.18013.5.1.mDL"`). */
+    doc_type?: string;
+    /** Credential namespace (e.g. `"org.iso.18013.5.1"`). */
+    namespace?: string;
+    /** All credential-specific claims, keyed by claim name. */
+    [key: string]: unknown;
+}
+/**
+ * Base64url-decode a string to a Uint8Array.
+ * Handles the standard base64url alphabet (no padding required).
+ */
+export declare function base64urlDecode(input: string): Uint8Array;
+/**
+ * Import an ES256 (ECDSA P-256) public key for attestation signature verification.
+ *
+ * Accepts either:
+ * - A raw SPKI DER encoded as a base64 string (no headers), or
+ * - A PEM-encoded SubjectPublicKeyInfo certificate (`-----BEGIN PUBLIC KEY-----`), or
+ * - A PEM-encoded X.509 certificate (`-----BEGIN CERTIFICATE-----`): the Subject
+ *   Public Key Info is automatically extracted from the TBSCertificate.
+ */
+export declare function importVerifierPublicKey(pemOrSpki: string): Promise<CryptoKey>;
+/**
+ * Decode and verify an attestation JWT signed by the credential verifier.
+ *
+ * Steps:
+ * 1. Fetches the JWKS from `jwksUrl`.
+ * 2. Locates the verification key using the `kid` from the JWT header (falls back
+ *    to the first key carrying an `x5c` certificate chain).
+ * 3. Imports the public key from the DER certificate in `x5c[0]`.
+ * 4. Verifies the ES256 signature and checks `exp` / `nbf`.
+ * 5. Returns the verified {@link Attestation}.
+ *
+ * @param jwt     - Compact-serialized JWT from `VerifyResponse.attestation`.
+ * @param jwksUrl - URL of the JWK Set that contains the attestation signing key,
+ *                  e.g. `"/ewqwe_api/openid4vp/.well-known/jwks.json"`.
+ * @throws If the JWKS cannot be fetched, no matching key is found, or verification fails.
+ */
+export declare function decodeAttestation(jwt: string): Attestation;
+export declare function getAttestationExpiryStatus(attestation: Attestation): "valid" | "expired" | "not_yet_valid";
+export declare function parseAttestation(jwt: string, jwksUrl: string): Promise<Attestation>;
+/**
+ * Verify an ES256 attestation JWT signature and return the decoded claims.
+ *
+ * @param jwt - The compact-serialized JWT string.
+ * @param publicKey - The verifier's public key, obtained from `importVerifierPublicKey`.
+ * @throws If the signature is invalid, the JWT is malformed, or the claims are expired.
+ */
+export declare function verifyAttestation(jwt: string, publicKey: CryptoKey): Promise<Attestation>;

package/dist/config.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @ewqwe/digital-identity — Protocol & Credential Configuration
+ *
+ * Defines protocol profiles (HAIP, Annex A), credential type specifications
+ * (mDL, PID, Proof of Age), and helper functions for querying them.
+ *
+ * Node.js compatible — no platform-specific APIs.
+ *
+ * @see https://openid.net/specs/openid-4-verifiable-presentations-1_0.html
+ * @see https://ageverification.dev/Technical%20Specification/annexes/annex-A/annex-A-av-profile
+ * @see ISO/IEC 18013-5:2021 for mDL claims
+ */
+import type { ClaimDefinition, CredentialType, CredentialTypeConfig, ProfileId, ProtocolProfile } from "./types.js";
+/**
+ * Protocol Profile Configurations
+ *
+ * **HAIP (High Assurance Interoperability Profile):**
+ * - Used for: mDL, PID (National ID)
+ * - Client ID Scheme: x509_hash (X.509 certificate SHA-256 hash)
+ * - Request Format: JAR (JWT Authorization Request with x5c header)
+ * - Response Mode: direct_post.jwt (encrypted/signed response)
+ * - URL Schemes: eudi-openid4vp://, openid4vp://
+ * - Reference: OpenID4VP HAIP Draft
+ *
+ * **Annex A (EU Age Verification Profile):**
+ * - Used for: Proof of Age attestations
+ * - Client ID Scheme: redirect_uri (redirect URI as client identifier)
+ * - Request Format: Plain JSON (redirect_uri scheme forbids signed requests)
+ * - Response Mode: direct_post (plain VP token)
+ * - URL Schemes: av://
+ * - Reference: https://ageverification.dev/Technical%20Specification/annexes/annex-A/annex-A-av-profile
+ *
+ * Note: The key difference is client_id_scheme. HAIP uses x509_hash with signed JARs,
+ * while Annex A uses redirect_uri with plain JSON (signed requests are explicitly forbidden).
+ * The `x509_hash` scheme is preferred over `x509_san_dns` because it provides a direct
+ * cryptographic binding to the verifier's certificate, independent of DNS resolution.
+ */
+export declare const PROTOCOL_PROFILES: Record<ProfileId, ProtocolProfile>;
+/**
+ * Credential type configurations based on ISO 18013-5, EU ARF, and EU Age Verification Profile.
+ *
+ * References:
+ * - mDL: ISO/IEC 18013-5:2021
+ * - PID: EU ARF Annex 2.02 Topic 3 (PID_04, PID_05)
+ * - Proof of Age: EU Age Verification Profile (https://ageverification.dev)
+ * - EUDI Wallet document categories: WalletCoreConfig.kt `documentCategories`
+ *
+ * Credential format identifiers:
+ * - `"mso_mdoc"` — ISO/IEC 18013-5 Mobile Documents (CBOR-encoded, namespace-based claims)
+ * - `"dc+sd-jwt"` — IETF SD-JWT VC (JSON-encoded, flat or nested claim paths)
+ *
+ * SD-JWT VC credential types use `vct` (Verifiable Credential Type) as the type
+ * identifier instead of `docType`/`namespace`. Claims use JSON paths instead of
+ * namespace-based paths. See OpenID4VP 1.0 §B.3 and draft-ietf-oauth-sd-jwt-vc-08.
+ */
+export declare const CREDENTIAL_TYPES: Record<CredentialType, CredentialTypeConfig>;
+/**
+ * Get default selected claims for a credential type (first 5 claims).
+ */
+export declare function getDefaultClaims(credentialType: CredentialType): string[];
+/**
+ * Get claim definitions for a credential type.
+ */
+export declare function getClaimsForType(credentialType: CredentialType): ClaimDefinition[];
+/**
+ * Get the protocol profile for a credential type.
+ */
+export declare function getProfileForType(credentialType: CredentialType): ProtocolProfile | null;
+/**
+ * Get the profile ID for a credential type.
+ */
+export declare function getProfileIdForType(credentialType: CredentialType): ProfileId;

package/dist/dcql.d.ts

@@ -0,0 +1,266 @@
+/**
+ * @ewqwe/digital-identity — DCQL Query Utilities
+ *
+ * Functions to build, parse, and convert DCQL (Digital Credentials Query Language)
+ * queries for EU Age Verification and OpenID4VP presentations.
+ *
+ * Node.js compatible — uses Node.js crypto API.
+ *
+ * @see https://openid.net/specs/openid-4-verifiable-presentations-1_0.html §6–7
+ * @see https://ageverification.dev/Technical%20Specification/annexes/annex-A/annex-A-av-profile
+ */
+import type { CredentialType, InitTransactionRequest, ProfileId } from "./types.js";
+/** EU Age Verification namespace. */
+export declare const EU_AV_NAMESPACE = "eu.europa.ec.av.1";
+/** EU Age Verification mDoc document type. */
+export declare const EU_AV_DOCTYPE = "eu.europa.ec.av.1.mdoc";
+/** ISO 18013-5 mDL namespace. */
+export declare const ISO_MDL_NAMESPACE = "org.iso.18013.5.1";
+/** ISO 18013-5 mDL document type. */
+export declare const ISO_MDL_DOCTYPE = "org.iso.18013.5.1.mDL";
+/** EU PID namespace. */
+export declare const EU_PID_NAMESPACE = "eu.europa.ec.eudi.pid.1";
+/** EU PID document type. */
+export declare const EU_PID_DOCTYPE = "eu.europa.ec.eudi.pid.1";
+/**
+ * A single entry in `trusted_authorities` — identifies an authority or trust framework
+ * that certifies credential issuers the Verifier will accept.
+ *
+ * A Credential matches if it satisfies **at least one** entry in the array.
+ *
+ * Type identifiers defined by OpenID4VP 1.0 §6.1.1:
+ * - `"aki"` — X.509 Authority Key Identifier, base64url-encoded (§6.1.1.1)
+ * - `"etsi_tl"` — ETSI Trusted List identifier (§6.1.1.2)
+ * - `"openid_federation"` — OpenID Federation Entity Identifier (§6.1.1.3)
+ *
+ * @see https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#section-6.1.1
+ */
+export interface TrustedAuthoritiesQuery {
+    /** Type identifier for the trust framework. */
+    type: "aki" | "etsi_tl" | "openid_federation" | string;
+    /** Non-empty array of values interpreted according to `type`. */
+    values: string[];
+}
+/** A single claim constraint in a DCQL credential query. */
+export interface DCQLClaimsQuery {
+    /** Claim identifier (for referencing in claim_sets). */
+    id?: string;
+    /**
+     * Claims Path Pointer (OpenID4VP 1.0 §7).
+     *
+     * A **non-empty** array whose elements must be:
+     * - `string` — navigate into the named key of an object (§7.1)
+     * - `number` (non-negative integer) — select the element at this index in an array (§7.1)
+     * - `null` — select **all** elements of the currently selected array(s) (§7.1)
+     *
+     * For `mso_mdoc` credentials (§7.2) exactly two strings are required:
+     * `[namespace, dataElementIdentifier]`.
+     *
+     * Examples from §7.3:
+     * - `["address", "street_address"]` — nested object key
+     * - `["degrees", null, "type"]` — all `type` values across the `degrees` array
+     * - `["nationalities", 1]` — second element of the `nationalities` array
+     */
+    path: (string | number | null)[];
+    /** Expected values — if provided, claim must match one of these (§6.3). */
+    values?: (string | number | boolean)[];
+    /** Whether to retain this claim after verification (mso_mdoc only, §B.2.4). */
+    intent_to_retain?: boolean;
+}
+/**
+ * A single credential query in DCQL.
+ *
+ * Format identifiers per the OpenID4VP 1.0 spec (Appendix B):
+ * - `"mso_mdoc"` — ISO/IEC 18013-5 Mobile Documents (§B.2)
+ * - `"dc+sd-jwt"` — IETF SD-JWT VC (§B.3), canonical since Nov 2024
+ *   (was `"vc+sd-jwt"` before Nov 2024; both SHOULD be accepted per
+ *   draft-ietf-oauth-sd-jwt-vc-08 §3.2.1)
+ * - `"jwt_vc_json"` — W3C VC signed as JWT (§B.1.3.1)
+ * - `"ldp_vc"` — W3C VC with Linked Data Proofs (§B.1.3.2)
+ *
+ * @see https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#appendix-B
+ * @see https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-08.html#section-3.2.1
+ */
+export interface DCQLCredentialQuery {
+    /** Unique identifier for this credential query. */
+    id: string;
+    /**
+     * Credential format identifier.
+     *
+     * `"mso_mdoc"` is for ISO/IEC 18013-5 Mobile Documents (mDL/mDoc).
+     *
+     * `"sd-jwt"` formats are for IETF SD-JWT Verifiable Credentials.  The current
+     * IANA-registered identifier for SD-JWT VC is `"dc+sd-jwt"` (application/dc+sd-jwt),
+     * which is the canonical name to use going forward. The older `"vc+sd-jwt"`
+     * SHOULD also be accepted during the transitional period per draft-ietf-oauth-sd-jwt-vc-08 §3.2.1.
+     *
+     * `"jwt_vc_json"` is for W3C Verifiable Credentials signed as JWT without JSON-LD.
+     *
+     * `"ldp_vc"` is for W3C Verifiable Credentials with Linked Data Proofs.
+     */
+    format: "mso_mdoc" | "dc+sd-jwt" | "vc+sd-jwt" | "jwt_vc_json" | "ldp_vc";
+    /** Format-specific metadata. */
+    meta?: {
+        /** Document type for mso_mdoc (e.g. "org.iso.18013.5.1.mDL"). */
+        doctype_value?: string;
+        /** Verifiable Credential Type values for dc+sd-jwt / vc+sd-jwt. */
+        vct_values?: string[];
+        /** Type values for jwt_vc_json / ldp_vc. */
+        type_values?: string[][];
+    };
+    /** Claims to request from the credential. */
+    claims?: DCQLClaimsQuery[];
+    /** Named subsets of claims; the wallet picks one set. */
+    claim_sets?: string[][];
+    /** Allow the wallet to return multiple matching credentials. */
+    multiple?: boolean;
+    /**
+     * Expected authorities or trust frameworks that certify issuers the Verifier will accept.
+     *
+     * OPTIONAL non-empty array. Every Credential returned by the Wallet SHOULD match at least
+     * one of the conditions. The Verifier still bears its own responsibility to verify issuer
+     * trust; this field is a hint to the Wallet to avoid sending credentials likely to be
+     * rejected. See §6.1.1 for matching semantics per type.
+     *
+     * @see https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#section-6.1.1
+     */
+    trusted_authorities?: TrustedAuthoritiesQuery[];
+    /**
+     * Require cryptographic holder binding in the presentation.
+     *
+     * OPTIONAL. Default is `true` per §6.1 — a Verifiable Presentation with Cryptographic
+     * Holder Binding is required unless explicitly set to `false`.
+     */
+    require_cryptographic_holder_binding?: boolean;
+}
+/** A credential set defining alternatives (OR logic). */
+export interface DCQLCredentialSetQuery {
+    /** Which credential query options satisfy this set. */
+    options: string[][];
+    /** Whether this credential set is required (default: true). */
+    required?: boolean;
+    /** Human-readable purpose for this credential set. */
+    purpose?: string;
+}
+/** The complete DCQL query structure — OpenID4VP 1.0 §6. */
+export interface DCQLQuery {
+    /** Array of credential queries. */
+    credentials: DCQLCredentialQuery[];
+    /** Optional credential sets for defining alternatives. */
+    credential_sets?: DCQLCredentialSetQuery[];
+}
+/**
+ * Build a minimal age verification query using the EU AV profile.
+ *
+ * @param ageThreshold - The age threshold to verify (e.g. 18, 21)
+ * @returns DCQL query requesting age_over_N = true
+ */
+export declare function buildAgeVerificationQuery(ageThreshold?: number): DCQLQuery;
+/**
+ * Build an age verification query with mDL fallback.
+ *
+ * Uses credential_sets to allow either EU AV proof OR mDL.
+ *
+ * @param ageThreshold - The age threshold to verify (e.g., 18, 21)
+ * @returns DCQL query with EU AV primary and mDL fallback
+ */
+export declare function buildAgeVerificationQueryWithFallback(ageThreshold?: number): DCQLQuery;
+/**
+ * Default DCQL query requesting age_over_18 from EU PID.
+ */
+export declare function getDefaultAgeVerificationDCQL(): DCQLQuery;
+/**
+ * Build an `InitTransactionRequest` directly from a credential type and
+ * selected claims — the canonical way to initialize an OpenID4VP transaction.
+ *
+ * Builds a **DCQL query** directly (never a legacy `PresentationDefinition`),
+ * so no server-side conversion is required.
+ *
+ * @param publicUrl - The public URL the wallet is going to call back to
+ * @param credentialType - The type of credential to request
+ * @param selectedClaims - Array of claim IDs to include (e.g. `["age_over_18"]`)
+ * @returns `InitTransactionRequest` ready to POST to `/ewqwe_api/openid4vp/init`
+ */
+export declare function buildInitTransactionRequest(publicUrl: string, credentialType: CredentialType, selectedClaims: string[], profile?: ProfileId): InitTransactionRequest;
+/**
+ * Determine the protocol profile based on credential type or explicit selection.
+ *
+ * - mDL and PID → HAIP (x509_san_dns, JAR signing, eudi-openid4vp://)
+ * - Proof of Age → Annex A (redirect_uri, plain request, av://)
+ */
+export declare function determineProfile(credentialType?: string, explicitProfile?: "haip" | "annex-a"): "haip" | "annex-a";
+/**
+ * Generate a cryptographically secure nonce for OpenID4VP requests.
+ *
+ * @returns Base64URL-encoded random nonce
+ */
+export declare function generateNonce(): string;
+/**
+ * Validate the structural rules of a DCQL query per OpenID4VP 1.0 §6 and §6.4.1.
+ *
+ * Rules enforced:
+ *
+ * **§6 — Top level**
+ * - `credentials` MUST be non-empty.
+ * - Credential query `id` values MUST be unique across `credentials`.
+ * - `credential_sets`, if present, MUST be non-empty.
+ * - Each `credential_sets` option element MUST reference a valid credential query `id`.
+ *
+ * **§6.1 — Credential Query**
+ * - Each credential `id` MUST be a non-empty string of alphanumeric, `-`, or `_`.
+ * - `trusted_authorities`, if present, MUST be non-empty.
+ *
+ * **§6.3 & §6.4.1 — Claims / claim_sets**
+ * - `claim_sets` MUST NOT be present when `claims` is absent.
+ * - Claim `id` values MUST be unique within a single `claims` array.
+ * - When `claim_sets` is present, every claim MUST have a non-empty `id`.
+ * - Every identifier referenced in `claim_sets` MUST appear in `claims`.
+ *
+ * @param query - The DCQL query to validate.
+ * @returns An object `{ valid: true }` or `{ valid: false, error: string }`.
+ */
+export declare function isValidDCQLQuery(query: DCQLQuery): {
+    valid: true;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Parse a DCQL query from a string (typically from URL parameters).
+ *
+ * @param queryString - JSON string containing DCQL query
+ * @returns Parsed DCQL query or null if invalid
+ */
+export declare function parseDCQLQuery(queryString: string): DCQLQuery | null;
+/**
+ * Extract the age threshold from a DCQL query.
+ *
+ * @param query - DCQL query to analyze
+ * @returns Age threshold (e.g. 18, 21) or null if not an age verification query
+ */
+export declare function extractAgeThreshold(query: DCQLQuery): number | null;
+/**
+ * Build an OpenID4VP authorization request URL for same-device flow.
+ */
+export declare function buildAuthorizationRequest(params: {
+    rpDomain: string;
+    redirectUri: string;
+    ageThreshold?: number;
+    nonce?: string;
+    state?: string;
+}): Record<string, string>;
+/**
+ * Build an OpenID4VP authorization request for cross-device flow.
+ *
+ * Note: When using the HAIP profile with the EUDI Wallet, the client_id should be
+ * `x509_hash:<cert_hash>` instead of `x509_san_dns:<domain>` for a direct cryptographic
+ * binding to the verifier's certificate. The `x509_san_dns` form is maintained here for
+ * legacy compatibility and for deployments that still rely on DNS-based identification.
+ */
+export declare function buildCrossDeviceAuthorizationRequest(params: {
+    rpDomain: string;
+    responseUri: string;
+    ageThreshold?: number;
+    nonce?: string;
+    state?: string;
+}): Record<string, string>;