@learncard/openid4vc-plugin 0.0.1

package/dist/vp/pex.d.ts

@@ -0,0 +1,83 @@
+import { Field, InputDescriptor } from './types';
+/**
+ * Presentation Exchange v2 matcher — tests whether a single candidate VC
+ * satisfies an input_descriptor's constraints.
+ *
+ * Scope (what PEX expressions we support in Slice 6):
+ *
+ * **JSONPath subset (field.path[])**
+ * - `$`                       root
+ * - `$.foo`, `$.foo.bar`      dotted properties
+ * - `$['foo']`, `$["foo bar"]` bracketed property names (quoted literals)
+ * - `$.foo[0]`                numeric index
+ * - `$.foo[*]`                array wildcard
+ * - `$..foo`                  recursive descent
+ * - `$.foo[?(@.bar=='x')]`    filter predicates — NOT yet supported, and
+ *                              they're rare in real-world PD docs. Paths
+ *                              that need predicates throw a descriptive
+ *                              error rather than silently evaluating to
+ *                              nothing.
+ *
+ * **JSON Schema filter subset (field.filter)**
+ * - `type`, `const`, `enum`, `pattern`
+ * - `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`
+ * - `minLength`, `maxLength`
+ * - `contains` (on arrays)
+ * - `items` (on arrays — applied to every element)
+ * - Anything else is treated as "unknown constraint" and passes by
+ *   default. Verifiers relying on more exotic keywords will want the
+ *   full-ajv upgrade path noted in the README.
+ *
+ * Format / holder-binding checks live in the higher-level select.ts
+ * layer (Slice 6d) since they depend on knowing the candidate's format
+ * and the PD's `format` designation together.
+ */
+/** Per-field evaluation result. */
+export interface FieldMatch {
+    matched: boolean;
+    /** First JSONPath from `field.path[]` that yielded a matching value. */
+    matchedPath?: string;
+    /** The value at `matchedPath`. */
+    value?: unknown;
+    /** Diagnostic reason when `matched === false`. */
+    reason?: string;
+}
+/** Per-descriptor evaluation result. */
+export interface DescriptorMatch {
+    matched: boolean;
+    descriptorId: string;
+    /** One entry per declared field, in order. */
+    fields: FieldMatch[];
+    /** Diagnostic reason summarizing the first failure, when `matched === false`. */
+    reason?: string;
+}
+/**
+ * Evaluate a single PEX field against a candidate credential.
+ *
+ * Walks `field.path[]` in declared order, returning the first path that
+ * resolves AND — if `field.filter` is present — whose value satisfies
+ * the filter. Optional fields that find no value still succeed.
+ */
+export declare const evaluateField: (candidate: unknown, field: Field) => FieldMatch;
+/**
+ * Evaluate a full input_descriptor against a candidate credential.
+ *
+ * Short-circuits on the first required-field failure so a single bad
+ * field produces a useful reason instead of a wall of mismatches.
+ */
+export declare const matchInputDescriptor: (candidate: unknown, descriptor: InputDescriptor) => DescriptorMatch;
+/**
+ * Evaluate a supported JSONPath expression against `root` and return all
+ * matching values. Throws if the expression uses unsupported features
+ * (filter predicates, slicing, unions, scripting) so callers surface an
+ * actionable error rather than silently returning nothing.
+ */
+export declare const queryJsonPath: (root: unknown, path: string) => unknown[];
+/**
+ * Return whether `value` satisfies the PEX-sanctioned subset of JSON
+ * Schema. Unknown keywords are ignored (lenient mode) — wallets that
+ * reject on unknown keywords force verifier upgrades in lockstep, which
+ * is incompatible with the "meet them where they are" design goal.
+ */
+export declare const satisfiesFilter: (value: unknown, filter: Record<string, unknown>) => boolean;
+//# sourceMappingURL=pex.d.ts.map

package/dist/vp/pex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pex.d.ts","sourceRoot":"","sources":["../../src/vp/pex.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAW9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,cAAe,OAAO,SAAS,KAAK,KAAG,UA6DhE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,cAClB,OAAO,cACN,eAAe,KAC5B,eAyBF,CAAC;AAYF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAAU,OAAO,QAAQ,MAAM,KAAG,OAAO,EA0DlE,CAAC;AAmIF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,UAAW,OAAO,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,OA6GjF,CAAC"}

package/dist/vp/present.d.ts

@@ -0,0 +1,126 @@
+import { UnsignedVP } from '@learncard/types';
+import type { CandidateCredential, PresentationSubmission } from './select';
+import { PresentationDefinition } from './types';
+/**
+ * Slice 7a — **Verifiable Presentation construction**.
+ *
+ * Given a user's per-descriptor credential picks and the verifier's
+ * Presentation Definition, produce:
+ *
+ * 1. An unsigned W3C `VerifiablePresentation` object ready to be
+ *    signed (via `learnCard.invoke.issuePresentation` for `ldp_vp`, or
+ *    via the Slice 7b JWT signer for `jwt_vp_json`).
+ * 2. A DIF PEX v2 `PresentationSubmission` whose `descriptor_map`
+ *    paths correctly target each credential inside the final
+ *    `vp_token` for the chosen envelope format.
+ * 3. The envelope format id (`ldp_vp` | `jwt_vp_json`) so the caller
+ *    knows which signing path to invoke.
+ *
+ * **Pure and synchronous.** This layer never signs, never POSTs, and
+ * never touches the holder's private keys. All transport /
+ * cryptographic work happens in Slices 7b and 7c.
+ *
+ * ## Descriptor map semantics
+ *
+ * The DIF PEX spec (§6 "Presentation Submission") evaluates
+ * `descriptor_map[n].path` as a JSONPath over the vp_token **after
+ * decoding** when the outer token is a JWT. We emit paths that match
+ * what every mainstream verifier (walt.id, Sphereon, EUDI, Animo)
+ * actually resolves:
+ *
+ * - Outer `ldp_vp` envelope → `path: "$.verifiableCredential[N]"`
+ * - Outer `jwt_vp_json` envelope → `path: "$.vp.verifiableCredential[N]"`
+ *
+ * For mixed inner formats (e.g. a `jwt_vc_json` VC embedded alongside
+ * an `ldp_vc` inside an `ldp_vp`), the per-credential `format` field
+ * discriminates without needing `path_nested` — the path still
+ * resolves directly to the credential value at that index.
+ */
+/**
+ * Envelope format for the outer Verifiable Presentation.
+ *
+ * - `ldp_vp` — plain JSON-LD VP, signed with a Linked-Data / Data
+ *   Integrity proof (Slice 7b routes this through
+ *   `learnCard.invoke.issuePresentation`).
+ * - `jwt_vp_json` — compact JWS whose payload wraps the VP under a
+ *   top-level `vp` claim (VCDM §6.3.1).
+ */
+export type VpFormat = 'ldp_vp' | 'jwt_vp_json';
+/**
+ * A single user pick: "this candidate satisfies this input_descriptor".
+ * Wallets typically build this list from the SelectionResult by showing
+ * the per-descriptor candidate lists and letting the user tap once per
+ * row.
+ */
+export interface ChosenCredential {
+    descriptorId: string;
+    candidate: CandidateCredential;
+}
+export interface BuildPresentationOptions {
+    /** The verifier's Presentation Definition (used for `definition_id` + format hints). */
+    pd: PresentationDefinition;
+    /**
+     * The holder's picks, in presentation order. The resulting VP's
+     * `verifiableCredential` array mirrors this order, and every
+     * `descriptor_map` entry points at the matching index.
+     */
+    chosen: ChosenCredential[];
+    /** Holder DID, emitted as `unsignedVp.holder`. Required for VCDM §4.1.1 compliance. */
+    holder: string;
+    /**
+     * Override the envelope format. By default we infer from
+     * `pd.format` (if the verifier declared preference) and fall back
+     * to matching the chosen credentials' inner format.
+     */
+    envelopeFormat?: VpFormat;
+    /** Override the submission id. Defaults to a short random hex id. */
+    submissionId?: string;
+    /** Override the VP id. Defaults to `urn:uuid:<v4>`. */
+    presentationId?: string;
+    /** Seam for deterministic tests. Defaults to a `crypto.getRandomValues`-backed id. */
+    makeId?: () => string;
+}
+export interface PreparedPresentation {
+    /**
+     * Unsigned W3C Verifiable Presentation. Shape is the same for both
+     * envelope formats; the signing step differs.
+     *
+     * - For `ldp_vp`: pass this straight to
+     *   `learnCard.invoke.issuePresentation(unsignedVp, signingOptions)`.
+     * - For `jwt_vp_json`: wrap as the `vp` claim of a JWT and sign
+     *   (Slice 7b).
+     */
+    unsignedVp: UnsignedVP;
+    /** Ready-to-submit DIF PEX v2 Presentation Submission. */
+    submission: PresentationSubmission;
+    /** Outer envelope format id. */
+    vpFormat: VpFormat;
+    /**
+     * Per-credential format id, in the same order as
+     * `unsignedVp.verifiableCredential`. Slice 7b / 7c use this to
+     * decide serialization (compact JWS string vs. JSON object).
+     */
+    innerFormats: string[];
+}
+export type BuildPresentationErrorCode = 'no_selections' | 'unknown_descriptor' | 'unknown_credential_format' | 'invalid_jwt_vc';
+export declare class BuildPresentationError extends Error {
+    readonly code: BuildPresentationErrorCode;
+    constructor(code: BuildPresentationErrorCode, message: string);
+}
+/**
+ * Build a VerifiablePresentation + PresentationSubmission from a
+ * user's credential picks. See module doc for behavior.
+ *
+ * Validates input eagerly so callers get actionable errors instead of
+ * a malformed VP that the verifier silently rejects:
+ *
+ * - `no_selections` — `chosen` is empty.
+ * - `unknown_descriptor` — a pick references an id that doesn't exist
+ *   in the PD's input_descriptors.
+ * - `unknown_credential_format` — a candidate's format can't be
+ *   inferred AND wasn't explicitly declared.
+ * - `invalid_jwt_vc` — a candidate tagged `jwt_vc_json` has neither a
+ *   compact JWS string nor a `proof.jwt` we can extract.
+ */
+export declare const buildPresentation: (options: BuildPresentationOptions) => PreparedPresentation;
+//# sourceMappingURL=present.d.ts.map

package/dist/vp/present.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"present.d.ts","sourceRoot":"","sources":["../../src/vp/present.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,KAAK,EACR,mBAAmB,EACnB,sBAAsB,EAEzB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAMH;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,wBAAwB;IACrC,wFAAwF;IACxF,EAAE,EAAE,sBAAsB,CAAC;IAE3B;;;;OAIG;IACH,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAE3B,uFAAuF;IACvF,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,cAAc,CAAC,EAAE,QAAQ,CAAC;IAE1B,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACjC;;;;;;;;OAQG;IACH,UAAU,EAAE,UAAU,CAAC;IAEvB,0DAA0D;IAC1D,UAAU,EAAE,sBAAsB,CAAC;IAEnC,gCAAgC;IAChC,QAAQ,EAAE,QAAQ,CAAC;IAEnB;;;;OAIG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;CAC1B;AAMD,MAAM,MAAM,0BAA0B,GAChC,eAAe,GACf,oBAAoB,GACpB,2BAA2B,GAC3B,gBAAgB,CAAC;AAEvB,qBAAa,sBAAuB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;gBAE9B,IAAI,EAAE,0BAA0B,EAAE,OAAO,EAAE,MAAM;CAKhE;AAMD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,YACjB,wBAAwB,KAClC,oBAwDF,CAAC"}

package/dist/vp/request-object.d.ts

@@ -0,0 +1,99 @@
+import { JWK } from 'jose';
+import { AuthorizationRequest } from './types';
+export type RequestObjectErrorCode = 'invalid_request_object' | 'request_fetch_failed' | 'missing_client_id_scheme' | 'unsupported_client_id_scheme' | 'client_id_mismatch' | 'request_signature_invalid' | 'request_signer_untrusted' | 'did_resolution_failed' | 'unsafe_mode_rejected';
+export declare class RequestObjectError extends Error {
+    readonly code: RequestObjectErrorCode;
+    constructor(code: RequestObjectErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Minimal DID Document shape the resolver surface consumes. We avoid
+ * re-modeling the full spec — consumers only need enough to pull a
+ * `publicKeyJwk` out.
+ */
+export interface VerificationMethod {
+    id: string;
+    type: string;
+    controller?: string;
+    publicKeyJwk?: JWK;
+    publicKeyMultibase?: string;
+}
+export interface DidDocument {
+    id: string;
+    verificationMethod?: VerificationMethod[];
+    authentication?: Array<string | VerificationMethod>;
+    assertionMethod?: Array<string | VerificationMethod>;
+}
+export type DidResolver = (did: string) => Promise<DidDocument>;
+export interface VerifyRequestObjectOptions {
+    /** The `request_uri` to fetch. Mutually exclusive with `inlineJwt`. */
+    requestUri?: string;
+    /** The inline `request=<jws>` parameter value. Mutually exclusive with `requestUri`. */
+    inlineJwt?: string;
+    /**
+     * `client_id` from the outer URL params. Some verifiers let the
+     * `client_id` live in the URL while the JWS payload just repeats
+     * it; we cross-check them. Optional — only used as a consistency
+     * check when provided.
+     */
+    urlClientId?: string;
+    /**
+     * `client_id_scheme` from the outer URL params. Same cross-check
+     * rationale as `urlClientId`.
+     */
+    urlClientIdScheme?: string;
+    fetchImpl?: typeof fetch;
+    /**
+     * DID resolver override. When omitted, a built-in resolver handles
+     * `did:jwk` (offline) and `did:web` (over `fetchImpl`). Host apps
+     * that ship `did:key`/`did:ion`/… wire their own resolver here.
+     */
+    didResolver?: DidResolver;
+    /**
+     * Trusted X.509 root certificates (PEM strings). When scheme is
+     * `x509_san_dns`, the chain presented in `x5c` MUST root to one of
+     * these. If this list is empty and `unsafeAllowSelfSigned` is
+     * false, we refuse to verify x509-signed Request Objects.
+     */
+    trustedX509Roots?: readonly string[];
+    /**
+     * **Dangerous.** Accept self-signed / untrusted x509 chains for
+     * local development. The harness flips this on when a user
+     * explicitly opts in; production wallets must leave it off.
+     */
+    unsafeAllowSelfSigned?: boolean;
+    /**
+     * **Maximally dangerous.** Skip JWS signature verification on the
+     * Request Object entirely — claims are decoded but their
+     * authenticity is not checked at all. Strictly an interop /
+     * test-harness escape hatch for verifiers whose signing keys
+     * are pre-shared out-of-band and not published in any in-band
+     * channel (e.g. EUDI's reference verifier in `pre-registered`
+     * mode, which embeds `kid: "access_certificate"` referencing a
+     * keystore inside the verifier container with no JWKS endpoint).
+     *
+     * Production wallets MUST leave this off. Tampered Request
+     * Objects bypass detection when this flag is set. The other
+     * binding checks (`urlClientId` ↔ signed `client_id`) still run
+     * because they're integrity checks against the host-supplied
+     * URL, not against the JWS signature.
+     */
+    unsafeSkipRequestObjectSignatureVerification?: boolean;
+}
+/**
+ * Fetch-and-verify a signed OpenID4VP Authorization Request Object.
+ *
+ * Returns the canonical {@link AuthorizationRequest} shape built from
+ * the verified JWS payload. On any failure — fetch, decode, signature,
+ * trust-anchor — throws {@link RequestObjectError} with a stable code.
+ */
+export declare const verifyAndDecodeRequestObject: (opts: VerifyRequestObjectOptions) => Promise<AuthorizationRequest>;
+/**
+ * Built-in DID resolver covering the two methods wallet-side holder
+ * traffic most often uses: `did:jwk` (keys inline in the identifier)
+ * and `did:web` (DID docs over HTTPS). Other methods should be handled
+ * via the caller's `didResolver` override.
+ */
+export declare const builtInDidResolver: (fetchImpl?: typeof fetch | undefined) => DidResolver;
+//# sourceMappingURL=request-object.d.ts.map

package/dist/vp/request-object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-object.d.ts","sourceRoot":"","sources":["../../src/vp/request-object.ts"],"names":[],"mappings":"AAwCA,OAAO,EAAoC,GAAG,EAAE,MAAM,MAAM,CAAC;AAE7D,OAAO,EACH,oBAAoB,EAGvB,MAAM,SAAS,CAAC;AAYjB,MAAM,MAAM,sBAAsB,GAC5B,wBAAwB,GACxB,sBAAsB,GACtB,0BAA0B,GAC1B,8BAA8B,GAC9B,oBAAoB,GACpB,2BAA2B,GAC3B,0BAA0B,GAC1B,uBAAuB,GACvB,sBAAsB,CAAC;AAE7B,qBAAa,kBAAmB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;gBAGlC,IAAI,EAAE,sBAAsB,EAC5B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CASpC;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,GAAG,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC1C,cAAc,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,kBAAkB,CAAC,CAAC;IACpD,eAAe,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,kBAAkB,CAAC,CAAC;CACxD;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AAEhE,MAAM,WAAW,0BAA0B;IACvC,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAEzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAErC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;;;;;;;;;;;;OAeG;IACH,4CAA4C,CAAC,EAAE,OAAO,CAAC;CAC1D;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,SAC/B,0BAA0B,KACjC,OAAO,CAAC,oBAAoB,CAwG9B,CAAC;AA0fF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,eAChB,OAAO,KAAK,GAAG,SAAS,KACpC,WAaF,CAAC"}

package/dist/vp/select.d.ts

@@ -0,0 +1,137 @@
+import { DescriptorMatch } from './pex';
+import { PresentationDefinition } from './types';
+/**
+ * Given the holder's full credential pool and a verifier's Presentation
+ * Definition, figure out which credentials are eligible to satisfy each
+ * `input_descriptor`, whether the overall submission is possible, and
+ * produce a ready-to-serialize PresentationSubmission skeleton.
+ *
+ * This is the "preview" half of the OID4VP flow: the UI shows the user
+ * the candidates returned here, they pick one per descriptor, and Slice
+ * 7 builds + signs the actual `vp_token` using those selections.
+ */
+/**
+ * A single credential paired with its inferred / declared format id.
+ * Callers always pass in strings they've indexed themselves; we never
+ * attempt to decrypt or verify the credential here.
+ */
+export interface CandidateCredential {
+    /** The raw credential value — a JSON-LD object for ldp_vc or a compact JWT string for jwt_vc_json. */
+    credential: unknown;
+    /** Credential format id. Inferred via {@link inferCredentialFormat} when omitted. */
+    format?: string;
+    /**
+     * Caller-provided identifier (URI, DB row id, etc.) used when
+     * building audit logs and when binding selections back to storage.
+     * Not part of the DIF PEX spec — ours alone.
+     */
+    id?: string;
+}
+export interface DescriptorCandidate {
+    descriptorId: string;
+    candidate: CandidateCredential;
+    match: DescriptorMatch;
+    /**
+     * Absolute position in the caller's original `candidates` array.
+     * Lets callers reconstruct their own state without string-matching.
+     */
+    candidateIndex: number;
+}
+export interface DescriptorSelection {
+    descriptorId: string;
+    /** Candidates that satisfied every required field + format constraint. */
+    candidates: DescriptorCandidate[];
+    /** Reason this descriptor has zero candidates (when applicable). */
+    reason?: string;
+}
+export interface SelectionResult {
+    /** One entry per input_descriptor, in the PD's declared order. */
+    descriptors: DescriptorSelection[];
+    /**
+     * `true` when the Presentation Definition's submission requirements
+     * (or, if none, all descriptors) can be satisfied by the candidate
+     * pool. UIs use this to disable the "Share" button up front.
+     */
+    canSatisfy: boolean;
+    /**
+     * Human-readable reason shown to the user when `canSatisfy` is
+     * false. Example: `"The verifier requires a UniversityDegree
+     * credential and you don't have one."`
+     */
+    reason?: string;
+}
+/**
+ * DIF PEX v2 Presentation Submission — what the wallet returns inside
+ * the vp_token to tell the verifier which VC answered which descriptor.
+ */
+export interface PresentationSubmission {
+    id: string;
+    definition_id: string;
+    descriptor_map: PresentationSubmissionDescriptor[];
+}
+export interface PresentationSubmissionDescriptor {
+    id: string;
+    format: string;
+    path: string;
+    path_nested?: PresentationSubmissionDescriptor;
+}
+/**
+ * Input to {@link buildPresentationSubmission}: the user's per-descriptor
+ * selection, along with the VP-internal path where the chosen VC will
+ * appear (typically `$.verifiableCredential[N]`).
+ */
+export interface SelectedDescriptor {
+    descriptorId: string;
+    format: string;
+    /**
+     * JSONPath inside the outer vp_token where the credential will sit.
+     * For a JSON-LD VP: `$.verifiableCredential[0]`.
+     * For a JWT VP wrapping JSON-LD VCs: `$.vp.verifiableCredential[0]`.
+     */
+    path: string;
+    /**
+     * JSONPath inside a nested envelope. For jwt_vc_json credentials
+     * embedded in a JSON-LD VP: `$` (the VC JWT is the whole value).
+     * Only set when the credential is itself a wrapped envelope (JWT).
+     */
+    pathNested?: string;
+}
+/**
+ * Run the holder's candidate pool against every input_descriptor in the
+ * PD. Each candidate must pass (a) any format constraint declared on
+ * the descriptor (or, if the descriptor has none, on the PD itself),
+ * and (b) every required field in `constraints.fields[]`.
+ *
+ * The result preserves the PD's declared descriptor order so UIs can
+ * render "one row per descriptor".
+ */
+export declare const selectCredentials: (candidates: CandidateCredential[], pd: PresentationDefinition) => SelectionResult;
+/**
+ * Build a DIF PEX v2 Presentation Submission descriptor map. The
+ * caller is responsible for ordering selections (and computing the
+ * `path` into their final vp_token shape) so this function is purely
+ * a well-typed assembler — it never rearranges, never substitutes, and
+ * never validates the selection against the PD.
+ *
+ * The `definition_id` must come from the original PD to satisfy
+ * verifiers that cross-check the submission.
+ */
+export declare const buildPresentationSubmission: (pd: PresentationDefinition, selections: SelectedDescriptor[], options?: {
+    submissionId?: string;
+    makeId?: () => string;
+}) => PresentationSubmission;
+/**
+ * Best-effort inference of the credential format id from the value's
+ * shape. Covers the two formats we've exercised end-to-end:
+ *
+ * - **`jwt_vc_json`** — compact JWS string (three base64url segments
+ *   separated by `.`), OR a decoded VC whose `proof.type ===
+ *   'JwtProof2020'` (the shape WaltID returns).
+ * - **`ldp_vc`** — a JSON-LD VC with a Data Integrity / JCS / legacy
+ *   `proof.type` (Ed25519Signature2020, DataIntegrityProof, etc.).
+ *
+ * Unknown shapes fall through to the caller-default `undefined`, which
+ * surfaces in the selection pipeline as "no format declared".
+ */
+export declare const inferCredentialFormat: (credential: unknown) => string | undefined;
+//# sourceMappingURL=select.d.ts.map

package/dist/vp/select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../src/vp/select.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,eAAe,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EAGH,sBAAsB,EAEzB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;GASG;AAMH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAChC,sGAAsG;IACtG,UAAU,EAAE,OAAO,CAAC;IACpB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,KAAK,EAAE,eAAe,CAAC;IACvB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC5B,kEAAkE;IAClE,WAAW,EAAE,mBAAmB,EAAE,CAAC;IAEnC;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,gCAAgC,EAAE,CAAC;CACtD;AAED,MAAM,WAAW,gCAAgC;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,gCAAgC,CAAC;CAClD;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,eACd,mBAAmB,EAAE,MAC7B,sBAAsB,KAC3B,eAwDF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,OAChC,sBAAsB,cACd,kBAAkB,EAAE,YACvB;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAA;CAAE,KAC1D,sBAwBF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,eAAgB,OAAO,KAAG,MAAM,GAAG,SAwBpE,CAAC"}

package/dist/vp/sign.d.ts

@@ -0,0 +1,125 @@
+import { UnsignedVP, VP } from '@learncard/types';
+import { ProofJwtSigner } from '../vci/types';
+import { VpFormat } from './present';
+/**
+ * Slice 7b — **Verifiable Presentation signing**.
+ *
+ * Takes the unsigned VP produced by {@link buildPresentation} and turns
+ * it into a signed `vp_token` ready for Slice 7c's `direct_post`
+ * transport. Two envelope formats are supported, matching
+ * {@link VpFormat}:
+ *
+ * - **`jwt_vp_json`** — wrap the VP as a JWT per VCDM §6.3.1:
+ *     - `iss` = holder DID
+ *     - `sub` = holder DID (VCDM §6.3.1.1 — "identifier of the
+ *       expected holder")
+ *     - `aud` = verifier's `client_id` (from the OID4VP Authorization
+ *       Request)
+ *     - `nonce` = verifier's nonce (replay-binding)
+ *     - `jti` = VP id
+ *     - `iat` = now (epoch seconds)
+ *     - `vp`  = the unsigned VP JSON
+ *   The JWS is signed with the holder's {@link ProofJwtSigner} — the
+ *   same interface the VCI proof-of-possession path uses.
+ *
+ * - **`ldp_vp`** — delegate to the host's Linked-Data proof pipeline.
+ *   The plugin wires this to `learnCard.invoke.issuePresentation` in
+ *   Slice 7c, passing `domain = audience` and `challenge = nonce` per
+ *   OID4VP §6.1 so the verifier can detect replay.
+ *
+ * Pure + dependency-injected: this module never talks to the network
+ * and never accesses LearnCard directly. Tests supply trivial mock
+ * signers; the plugin supplies real ones.
+ */
+/**
+ * The vp_token value ready for OID4VP `direct_post`:
+ *
+ * - `string` — compact JWS (used for `jwt_vp_json`).
+ * - `VP`     — signed JSON-LD VP object (used for `ldp_vp`).
+ *
+ * The transport layer (Slice 7c) serializes these two shapes
+ * uniformly: both go into `application/x-www-form-urlencoded` as the
+ * `vp_token` field, with JSON objects JSON-stringified first.
+ */
+/**
+ * Wire-shape of the OID4VP `vp_token` form field across BOTH query
+ * languages:
+ *
+ * - `string` — PEX `jwt_vp_json` compact JWS, OR a single DCQL entry
+ *   that's a `jwt_vc_json` presentation.
+ * - `VP`    — PEX `ldp_vp` signed VP object.
+ * - `Record<string, string | VP>` — DCQL response object keyed by
+ *   `credential_query_id` (OID4VP 1.0 §6.4); values are
+ *   per-query signed presentations.
+ *
+ * The submit layer JSON-encodes whichever non-string variant arrives
+ * before form-urlencoding it.
+ */
+export type VpToken = string | VP | Record<string, string | VP>;
+/**
+ * Linked-Data VP signer contract. The plugin binds this to
+ * `learnCard.invoke.issuePresentation`, passing through OID4VP's
+ * replay-binding via `domain`/`challenge`.
+ */
+export interface LdpVpSigner {
+    sign: (unsignedVp: UnsignedVP, options: {
+        domain: string;
+        challenge: string;
+    }) => Promise<VP>;
+}
+export interface SignPresentationOptions {
+    /** Unsigned VP from {@link buildPresentation}. */
+    unsignedVp: UnsignedVP;
+    /** Envelope format from {@link buildPresentation}. */
+    vpFormat: VpFormat;
+    /**
+     * Verifier's `client_id` (from the Authorization Request). For
+     * `jwt_vp_json` this becomes the JWT `aud`; for `ldp_vp` it
+     * becomes the LD-proof `domain`.
+     */
+    audience: string;
+    /**
+     * Verifier's `nonce` (from the Authorization Request). For
+     * `jwt_vp_json` this becomes the JWT `nonce`; for `ldp_vp` it
+     * becomes the LD-proof `challenge`.
+     */
+    nonce: string;
+    /**
+     * Holder DID. Must equal `unsignedVp.holder`; we re-validate to
+     * prevent the signer from silently signing a VP whose holder
+     * field was tampered with between construction and signing.
+     */
+    holder: string;
+    /** Override the JWT `jti`. Defaults to `unsignedVp.id`. */
+    jti?: string;
+    /** Override `iat` for deterministic tests. Defaults to `Math.floor(Date.now() / 1000)`. */
+    iat?: number;
+}
+export interface SignPresentationHelpers {
+    /** Required when `vpFormat === 'jwt_vp_json'`. */
+    jwtSigner?: ProofJwtSigner;
+    /** Required when `vpFormat === 'ldp_vp'`. */
+    ldpVpSigner?: LdpVpSigner;
+}
+export interface SignPresentationResult {
+    vpToken: VpToken;
+    vpFormat: VpFormat;
+}
+export type VpSignErrorCode = 'missing_jwt_signer' | 'missing_ldp_signer' | 'jwt_sign_failed' | 'ldp_sign_failed' | 'holder_mismatch' | 'invalid_input';
+export declare class VpSignError extends Error {
+    readonly code: VpSignErrorCode;
+    constructor(code: VpSignErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Sign a prepared Verifiable Presentation. See module doc for
+ * envelope semantics.
+ *
+ * All cryptographic work happens inside the injected signer(s) —
+ * unsupported combinations (e.g. `jwt_vp_json` with no `jwtSigner`)
+ * throw `VpSignError` with a typed code so callers can surface
+ * actionable UI instead of a generic "signing failed".
+ */
+export declare const signPresentation: (options: SignPresentationOptions, helpers: SignPresentationHelpers) => Promise<SignPresentationResult>;
+//# sourceMappingURL=sign.d.ts.map

package/dist/vp/sign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../../src/vp/sign.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH;;;;;;;;;GASG;AACH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,EAAE,CAAC,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,CACF,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,KAC7C,OAAO,CAAC,EAAE,CAAC,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACpC,kDAAkD;IAClD,UAAU,EAAE,UAAU,CAAC;IAEvB,sDAAsD;IACtD,QAAQ,EAAE,QAAQ,CAAC;IAEnB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,2FAA2F;IAC3F,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACpC,kDAAkD;IAClD,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,6CAA6C;IAC7C,WAAW,CAAC,EAAE,WAAW,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;CACtB;AAMD,MAAM,MAAM,eAAe,GACrB,oBAAoB,GACpB,oBAAoB,GACpB,iBAAiB,GACjB,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,CAAC;AAEtB,qBAAa,WAAY,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;gBAEnB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAQpF;AAMD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,YAChB,uBAAuB,WACvB,uBAAuB,KACjC,OAAO,CAAC,sBAAsB,CAQhC,CAAC"}