@interop/wallet-request 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,257 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Shared types for `@interop/wallet-request`. The Verifiable
+ * Presentation Request (VPR) vocabulary itself is owned by
+ * `@interop/data-integrity-core` (its `VPR` module) and re-exported here so a
+ * request consumer imports one package; this file adds only the request-local
+ * types the app sources carried alongside that vocabulary: the CHAPI event
+ * shapes, the VC-API exchange reply shape, the classified-request profile, and
+ * the injection-seam types (`PresentationSigner`, `FetchLike`,
+ * `RequestProcessors`) that keep this layer free of any single app's session /
+ * network / consent machinery.
+ *
+ * Ported from DCW's `app/lib/walletRequestApi.ts` and Freewallet's
+ * `src/lib/walletRequest/{types,classify}.ts`.
+ *
+ * The VPR vocabulary (and the loose-shape guards in `classify` / `matching`) is
+ * imported from the `@interop/data-integrity-core/vpr` and `/guards` subpaths
+ * rather than the package root: the vocabulary was added to data-integrity-core
+ * without a version bump, so the package root can dedup onto an older cached
+ * build that predates it, whereas the subpath entry points resolve only against
+ * the current build that defines them.
+ */
+import type { ISigner } from '@interop/data-integrity-core';
+import type { IVerifiableCredential, IVerifiablePresentation, IZcap } from '@interop/data-integrity-core';
+import type { ICapabilityQueryDetail, IQueryByExample, IVPRDetails as ISpecVPRDetails, WalletResponse } from '@interop/data-integrity-core/vpr';
+export type { IVPRequest, IVPOffer, IIssueRequest, IExchangeInvitation, IOid4VCIOffer, IVPRInteract, IVPRQuery, IQueryByExample, ICredentialQuery, IAcceptedCryptosuites, IDIDAuthenticationQuery, IZcapQuery, ICapabilityQueryDetail, IInvocationTarget, IAllowedAction, WalletApiMessage, WalletResponse, IVpRequest, IVpOffer, IVprDetails, IVprQuery, IDidAuthenticationQuery } from '@interop/data-integrity-core/vpr';
+export type { IVerifiableCredential, IVerifiablePresentation, IZcap } from '@interop/data-integrity-core';
+/**
+ * The protocol handles a verifier offers alongside a CHAPI request. Only
+ * `vcapi` (and the newer `interact` meta-protocol) are acted on; `OID4VP` /
+ * `OID4VCI` are recognized but unused.
+ */
+export interface CHAPIProtocols {
+    vcapi?: string;
+    interact?: string;
+    OID4VP?: string;
+    OID4VCI?: string;
+}
+/**
+ * The body of a Verifiable Presentation Request, widened from the spec
+ * vocabulary with the wallet-layer `agent` member: the requester's
+ * self-declared display name on a standalone capability request (an agent
+ * asking for grants through an interaction URL, where no attested origin
+ * names it). One member at the VPR root rather than one per query, since a
+ * single agent sends the whole request. Display only and attacker-controlled,
+ * like App Connect's `app.name`; `requestingAgentOf` validates it.
+ */
+export type IVPRDetails = ISpecVPRDetails & {
+    agent?: {
+        name: string;
+    };
+};
+/**
+ * Raw CHAPI credential-get event. The `VerifiablePresentation` object CHAPI
+ * hands us *is* the VPR body (`query` / `challenge` / `domain`); classification
+ * rewraps it as an `IVPRequest`. When the verifier names a `protocols` handle
+ * it sends that body empty instead, and the VPR must be fetched from the
+ * protocol exchange (see `exchangeClient.ts`).
+ */
+export interface CHAPIGetEvent {
+    credentialRequestOrigin: string;
+    credentialRequestOptions?: {
+        web?: {
+            VerifiablePresentation?: IVPRDetails;
+            protocols?: CHAPIProtocols;
+        };
+    };
+    respondWith(promise: Promise<{
+        dataType: string;
+        data: unknown;
+    } | null>): void;
+}
+/**
+ * Raw CHAPI credential-store event. `credential.data` is the offered payload,
+ * and `credential.dataType` names its shape: issuers may offer either a
+ * `VerifiablePresentation` wrapping the credential(s), or a bare
+ * `VerifiableCredential` (what vcplayground.org sends). An issuer that names a
+ * `protocols` handle in `credential.options` sends `data` empty instead, and
+ * the offered credentials must be fetched from the protocol exchange (see
+ * `exchangeClient.ts`).
+ */
+export interface CHAPIStoreEvent {
+    credentialRequestOrigin?: string;
+    credential: {
+        dataType?: string;
+        data: IVerifiablePresentation | IVerifiableCredential;
+        options?: {
+            protocols?: CHAPIProtocols;
+            recommendedHandlerOrigins?: string[];
+        };
+    };
+    respondWith(promise: Promise<{
+        dataType: string;
+        data: unknown;
+    } | null>): void;
+}
+/**
+ * The exchange's reply to either wallet call. A multi-step exchange answers a
+ * submitted presentation with another `verifiablePresentationRequest`; a
+ * finished one answers with nothing, or with credentials it issued, or with a
+ * `redirectUrl` for the user to land on.
+ */
+export interface VCAPIExchangeResponse {
+    verifiablePresentationRequest?: IVPRDetails;
+    verifiablePresentation?: IVerifiablePresentation;
+    redirectUrl?: string;
+}
+/**
+ * A VP Request classified on independent axes: whether DID Authentication is
+ * requested, what credentials are asked for (`vcQueries`), and what capability
+ * delegations are asked for (`zcapRequests`). Any combination is valid,
+ * including zcap-only. An app that layers additional query kinds on top (e.g.
+ * Freewallet's App Connect) extends this shape with its own field.
+ */
+export interface WalletRequestProfile {
+    didAuth: boolean;
+    vcQueries: IQueryByExample[];
+    zcapRequests: ICapabilityQueryDetail[];
+    /**
+     * The requester's self-declared display name (the VPR's `agent.name`,
+     * validated and trimmed), present only when the request carried one.
+     */
+    agent?: {
+        name: string;
+    };
+}
+/**
+ * A capability request entry as an `AppConnectQuery` carries it: the standard
+ * capability-query detail minus the members the wallet itself fills or refuses
+ * (`controller` is filled with the app-key subject DID at delegation time;
+ * `reason` is display-bearing and not accepted from an App Connect request).
+ */
+export type IAppConnectCapabilityQuery = Omit<ICapabilityQueryDetail, 'controller' | 'reason'>;
+/**
+ * The app identity an App Connect request presents: a display `name` for the
+ * consent surface (attacker-controlled free text, never evidence of identity)
+ * and the application's canonical `appUrl`, which scopes the app-key identity
+ * within the requesting origin. Validated by `appConnectRequestOf`: the
+ * `appUrl` must parse as an absolute URL, carry no fragment, and be
+ * same-origin with the attested requesting origin.
+ */
+export type IAppConnectApp = {
+    name: string;
+    appUrl: string;
+};
+/**
+ * "Connect this app to the user's wallet and Space" -- a single-round request
+ * that combines app-key recovery-or-minting with capability delegation. The
+ * wallet finds (or self-issues) the app-key credential for the requesting
+ * origin and `appUrl`, delegates the requested capabilities to its subject
+ * DID, and returns credential + grants in one signed presentation.
+ */
+export type IAppConnectQuery = {
+    type: 'AppConnectQuery';
+    app: IAppConnectApp;
+    capabilityQuery?: IAppConnectCapabilityQuery | IAppConnectCapabilityQuery[];
+};
+/**
+ * An App Connect request as classified and validated by
+ * `appConnectRequestOf`: the app identity (its `appUrl` already in serialized
+ * form) plus its capability queries normalized to an array.
+ */
+export type IAppConnectRequest = {
+    app: IAppConnectApp;
+    capabilityQueries: IAppConnectCapabilityQuery[];
+};
+/**
+ * "Connect a new wallet client to this account" -- the query an already-
+ * enrolled wallet client (the inviter) puts in the VPR of an ephemeral
+ * exchange for a fresh wallet (the enrollee) to answer. It carries everything
+ * the enrollee needs to find the account, so no secret is required of the
+ * person joining:
+ *
+ * - `did` -- the account's stable did:webvh id, whose log is world-readable
+ *   and is where the enrollee verifies its own approval.
+ * - `spaceId` and `host` -- where the account lives (the WAS server base URL
+ *   and the Space on it); together with `did` these are exactly the account
+ *   pointer a keyring record carries (keyring's `AccountPointer` shape), so
+ *   the inviter passes its session pointer straight in.
+ * - `controller` -- the account controller did:key, what the enrollee's own
+ *   profile link stores once it has joined.
+ *
+ * Discovery only: the query names the account but authorizes nothing. Every
+ * act on the Space still requires zcaps a holder of the QR or capability URL
+ * does not have, and nothing is authorized before the ceremony's
+ * confirmation-code comparison. The enrollee answers off-band of the VPR
+ * vocabulary, with the onboarding response envelope
+ * (`@interop/wallet-core`'s `enrollment` subpath), whose payload is an ordinary connect
+ * code.
+ */
+export type IWalletOnboardingQuery = {
+    type: 'WalletOnboardingQuery';
+    host: string;
+    did: string;
+    spaceId: string;
+    controller: string;
+};
+/**
+ * A wallet-onboarding request as classified and validated by
+ * `walletOnboardingRequestOf`: the account's did:webvh `did`, its `spaceId`,
+ * the `host` already in serialized URL form (the three together being the
+ * account pointer), and the account controller did:key.
+ */
+export type IWalletOnboardingRequest = {
+    host: string;
+    did: string;
+    spaceId: string;
+    controller: string;
+};
+/**
+ * The authentication signer plus the DID to name as the VP `holder`. Each app
+ * resolves this from its own key material (DCW from the selected profile's
+ * `authentication` signer + DID; Freewallet from the KMS did:web key or the
+ * passphrase-derived root key) before handing it to the shared compose path.
+ */
+export interface PresentationSigner {
+    signer: ISigner;
+    holder: string;
+}
+/**
+ * Injected network transport. Defaults to `globalThis.fetch`; DCW passes its
+ * `fetchWithTimeout`, Freewallet its CORS-proxy fetch.
+ */
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/**
+ * App-side processors injected into {@link processRequest}. Both are optional:
+ * a wallet that grants no capabilities omits `processZcaps`, and a wallet
+ * without an App Connect flow omits `processAppConnect` (the branch is then
+ * inert).
+ */
+export interface RequestProcessors {
+    /**
+     * Delegates the approved capabilities and returns the minted zcaps.
+     * Freewallet supplies `processZcaps(session)`; DCW supplies a no-op / `[]`.
+     */
+    processZcaps?: (args: {
+        zcapRequests: ICapabilityQueryDetail[];
+    }) => Promise<IZcap[]>;
+    /**
+     * Handles the App Connect single-round branch. Invoked when the request
+     * carries an `AppConnectQuery`; `appConnect` arrives already validated by
+     * `appConnectRequestOf` (its `app.appUrl` in serialized form), so the
+     * processor never sees a malformed app block.
+     */
+    processAppConnect?: (args: {
+        request: IVPRDetails;
+        appConnect: IAppConnectRequest;
+        origin: string;
+        challenge?: string;
+        domain?: string;
+        didAuthRequested: boolean;
+        cryptosuite?: string;
+    }) => Promise<WalletResponse>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/walletInput.d.ts

@@ -0,0 +1,118 @@
+import type { WalletApiMessage } from './types.js';
+/**
+ * What a piece of wallet input turned out to be. Every variant carries the
+ * trimmed `text` it was classified from, plus whatever the classification
+ * already parsed (a classifier that recognized a grammar has usually parsed
+ * enough of it that re-parsing in the handler would be waste and drift).
+ */
+export type WalletInput = {
+    kind: 'was-link';
+    text: string;
+} | {
+    kind: 'connect-code';
+    text: string;
+} | {
+    kind: 'legacy-request';
+    text: string;
+    params: Record<string, string>;
+} | {
+    kind: 'interaction-url';
+    text: string;
+} | {
+    kind: 'deep-link';
+    text: string;
+} | {
+    kind: 'wallet-api-message';
+    text: string;
+    message: WalletApiMessage;
+} | {
+    kind: 'credentials';
+    text: string;
+};
+/**
+ * The account-convention recognizers a caller injects, one per grammar the
+ * classifier recognizes but does not own. Each is a predicate over the
+ * trimmed input; an absent one means the branch never matches. A wallet on a
+ * WAS account passes `@interop/wallet-core`'s own predicates
+ * (`isWasLinkPayload` from `space`, `isConnectCode` from `enrollment`), so
+ * the grammar keeps its one spelling there.
+ */
+export interface WalletInputRecognizers {
+    /**
+     * Whether the text is a `was-link` wallet-connection payload.
+     */
+    isWasLink?: (text: string) => boolean;
+    /**
+     * Whether the text is a client-enrollment connect code.
+     */
+    isConnectCode?: (text: string) => boolean;
+}
+/**
+ * Classifies one piece of wallet input. See the module doc for the order and
+ * why each branch sits where it does.
+ *
+ * @param text {string}   the scanned, pasted, or opened text
+ * @param [options] {object}
+ * @param [options.deepLinkSchemes] {string[]}   the link prefixes this app has
+ *   registered (custom protocols and universal app links). Empty, the
+ *   deep-link and legacy-request branches never match -- a wallet with no
+ *   registered links has nothing to route them to
+ * @param [options.recognizers] {WalletInputRecognizers}   the account-
+ *   convention predicates for the `was-link` and `connect-code` branches.
+ *   Absent, neither branch ever matches
+ * @returns {WalletInput}
+ */
+export declare function classifyWalletInput(text: string, { deepLinkSchemes, recognizers }?: {
+    deepLinkSchemes?: string[];
+    recognizers?: WalletInputRecognizers;
+}): WalletInput;
+/**
+ * The handlers a caller injects, one per classified kind. Every handler is
+ * optional: an input whose kind has no handler throws, which is what keeps a
+ * wallet that does not implement a grammar from silently doing the wrong thing
+ * with it.
+ */
+export interface WalletInputHandlers<T> {
+    wasLink?: (input: {
+        text: string;
+    }) => T | Promise<T>;
+    connectCode?: (input: {
+        text: string;
+    }) => T | Promise<T>;
+    legacyRequest?: (input: {
+        text: string;
+        params: Record<string, string>;
+    }) => T | Promise<T>;
+    interactionUrl?: (input: {
+        text: string;
+    }) => T | Promise<T>;
+    deepLink?: (input: {
+        text: string;
+    }) => T | Promise<T>;
+    walletApiMessage?: (input: {
+        text: string;
+        message: WalletApiMessage;
+    }) => T | Promise<T>;
+    credentials?: (input: {
+        text: string;
+    }) => T | Promise<T>;
+}
+/**
+ * Classifies input and dispatches it to the matching handler.
+ *
+ * @param options {object}
+ * @param options.text {string}   the scanned, pasted, or opened text
+ * @param [options.deepLinkSchemes] {string[]}   this app's registered link
+ *   prefixes
+ * @param [options.recognizers] {WalletInputRecognizers}   the account-
+ *   convention predicates for the `was-link` and `connect-code` branches
+ * @param options.handlers {WalletInputHandlers}   the injected handlers
+ * @returns {Promise<*>}   whatever the matching handler resolves to
+ */
+export declare function handleWalletInput<T>({ text, deepLinkSchemes, recognizers, handlers }: {
+    text: string;
+    deepLinkSchemes?: string[];
+    recognizers?: WalletInputRecognizers;
+    handlers: WalletInputHandlers<T>;
+}): Promise<T>;
+//# sourceMappingURL=walletInput.d.ts.map

package/dist/walletInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walletInput.d.ts","sourceRoot":"","sources":["../src/walletInput.ts"],"names":[],"mappings":"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"}

package/dist/walletInput.js

@@ -0,0 +1,169 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The universal wallet-input classifier: one ordered discrimination for every
+ * place a wallet accepts arbitrary text -- a QR scan, a paste box, a file
+ * drop, an opened deep link. Each wallet had grown its own ladder, so a
+ * grammar one wallet routed the other silently mis-handled (a connect code
+ * read as a credential URL, a connection payload read as nothing at all).
+ *
+ * Classification only: nothing here fetches, navigates, or stores. The caller
+ * supplies the handlers ({@link handleWalletInput}) or switches on the
+ * discriminated result itself.
+ *
+ * The order is the whole design, because several grammars are subsets of
+ * others. Most specific first:
+ *
+ * 1. **`was-link`** -- the wallet-connection QR payload, a non-URL JSON blob
+ *    (deliberately not a link, so no OS handler ever routes it). Checked first
+ *    because it is JSON that would otherwise fall through to the credential
+ *    branch.
+ * 2. **`connect-code`** -- a client-enrollment connect code, recognized by
+ *    prefix.
+ * 3. **`legacy-request`** -- the legacy credential-request link: a registered
+ *    deep link carrying both `vc_request_url` and `issuer`. Necessarily ahead
+ *    of the generic deep-link branch, which it would otherwise be swallowed by.
+ * 4. **`interaction-url`** -- a VCALM interaction URL (`interaction:` scheme,
+ *    or `iuv=1`), the indirection that resolves to a protocols map.
+ * 5. **`deep-link`** -- any other link on one of the app's registered schemes,
+ *    routed by the app's own link handling.
+ * 6. **`wallet-api-message`** -- a wallet API message, either as raw JSON or
+ *    carried in a `request` query parameter of a link that is NOT on a
+ *    registered scheme (a plain `https:` QR from a site that has one). The
+ *    parameter form is checked before the raw-JSON form so the message is
+ *    handed back parsed either way.
+ * 7. **`credentials`** -- the fallback: raw VC/VP JSON, or a URL to fetch one
+ *    from. Deliberately last, since it is the only branch that cannot be
+ *    recognized positively.
+ *
+ * Nothing is classified as "unrecognized": the credential branch is where
+ * unrecognized text lands, and the resolver a caller runs there is what
+ * produces the honest error message.
+ *
+ * The first two grammars are account conventions this package does not own:
+ * the `was-link` payload shape and the connect-code prefix are defined by
+ * `@interop/wallet-core` (`space` and `enrollment`), beside the ceremonies
+ * that consume them. The classifier takes each as an injected recognizer
+ * ({@link WalletInputRecognizers}) rather than importing the convention, the
+ * same way it takes the app's registered link schemes: a wallet that holds no
+ * WAS account has no such grammar to route, and one that does passes the
+ * owning package's predicate. An absent recognizer means that branch never
+ * matches, so the ordering above is preserved whichever subset is wired.
+ */
+import { isInteractionUrl } from './interactionUrl.js';
+import { isWalletApiMessage, parseWalletApiMessage, parseWalletApiUrl } from './parse.js';
+/**
+ * The query parameters of a link, whatever its scheme. Uses the substring
+ * after the first `?` rather than `new URL`, so a custom-protocol link parses
+ * the same way an `https:` one does.
+ *
+ * @param text {string}
+ * @returns {URLSearchParams}
+ */
+function queryParamsOf(text) {
+    const start = text.indexOf('?');
+    return new URLSearchParams(start === -1 ? '' : text.slice(start + 1));
+}
+/**
+ * Classifies one piece of wallet input. See the module doc for the order and
+ * why each branch sits where it does.
+ *
+ * @param text {string}   the scanned, pasted, or opened text
+ * @param [options] {object}
+ * @param [options.deepLinkSchemes] {string[]}   the link prefixes this app has
+ *   registered (custom protocols and universal app links). Empty, the
+ *   deep-link and legacy-request branches never match -- a wallet with no
+ *   registered links has nothing to route them to
+ * @param [options.recognizers] {WalletInputRecognizers}   the account-
+ *   convention predicates for the `was-link` and `connect-code` branches.
+ *   Absent, neither branch ever matches
+ * @returns {WalletInput}
+ */
+export function classifyWalletInput(text, { deepLinkSchemes = [], recognizers = {} } = {}) {
+    const trimmed = text.trim();
+    if (recognizers.isWasLink?.(trimmed)) {
+        return { kind: 'was-link', text: trimmed };
+    }
+    if (recognizers.isConnectCode?.(trimmed)) {
+        return { kind: 'connect-code', text: trimmed };
+    }
+    const isDeepLink = deepLinkSchemes.some(scheme => trimmed.startsWith(scheme));
+    if (isDeepLink) {
+        const params = queryParamsOf(trimmed);
+        if (params.has('vc_request_url') && params.has('issuer')) {
+            return {
+                kind: 'legacy-request',
+                text: trimmed,
+                params: Object.fromEntries(params.entries())
+            };
+        }
+    }
+    if (isInteractionUrl(trimmed)) {
+        return { kind: 'interaction-url', text: trimmed };
+    }
+    if (isDeepLink) {
+        return { kind: 'deep-link', text: trimmed };
+    }
+    // A link on an unregistered scheme can still carry a wallet API message in
+    // its `request` parameter (a site's own QR code).
+    const carried = parseWalletApiUrl({ url: trimmed });
+    const message = carried
+        ? parseWalletApiMessage({ messageObject: carried })
+        : isWalletApiMessage(trimmed)
+            ? parseWalletApiMessage({
+                messageObject: JSON.parse(trimmed)
+            })
+            : undefined;
+    if (message) {
+        return { kind: 'wallet-api-message', text: trimmed, message };
+    }
+    return { kind: 'credentials', text: trimmed };
+}
+/**
+ * Classifies input and dispatches it to the matching handler.
+ *
+ * @param options {object}
+ * @param options.text {string}   the scanned, pasted, or opened text
+ * @param [options.deepLinkSchemes] {string[]}   this app's registered link
+ *   prefixes
+ * @param [options.recognizers] {WalletInputRecognizers}   the account-
+ *   convention predicates for the `was-link` and `connect-code` branches
+ * @param options.handlers {WalletInputHandlers}   the injected handlers
+ * @returns {Promise<*>}   whatever the matching handler resolves to
+ */
+export async function handleWalletInput({ text, deepLinkSchemes, recognizers, handlers }) {
+    const input = classifyWalletInput(text, { deepLinkSchemes, recognizers });
+    switch (input.kind) {
+        case 'was-link':
+            return dispatch({ handler: handlers.wasLink, input });
+        case 'connect-code':
+            return dispatch({ handler: handlers.connectCode, input });
+        case 'legacy-request':
+            return dispatch({ handler: handlers.legacyRequest, input });
+        case 'interaction-url':
+            return dispatch({ handler: handlers.interactionUrl, input });
+        case 'deep-link':
+            return dispatch({ handler: handlers.deepLink, input });
+        case 'wallet-api-message':
+            return dispatch({ handler: handlers.walletApiMessage, input });
+        default:
+            return dispatch({ handler: handlers.credentials, input });
+    }
+}
+/**
+ * Runs one handler, or refuses because this wallet does not implement the
+ * grammar the input turned out to be.
+ *
+ * @param options {object}
+ * @param [options.handler] {Function}
+ * @param options.input {WalletInput}
+ * @returns {Promise<*>}
+ */
+async function dispatch({ handler, input }) {
+    if (!handler) {
+        throw new Error(`Unhandled wallet input of kind "${input.kind}".`);
+    }
+    return handler(input);
+}
+//# sourceMappingURL=walletInput.js.map

package/dist/walletInput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walletInput.js","sourceRoot":"","sources":["../src/walletInput.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@interop/wallet-request",
+  "description": "Wallet-request and exchange protocol handling for Interop wallet apps: input classification, VPR parsing, QueryByExample matching, cryptosuite negotiation, VP composition, the App Connect app-key credential, and the VC-API / ephemeral-exchange clients.",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "build": "pnpm run clear && tsc",
+    "clear": "rimraf dist/*",
+    "dev": "vite",
+    "fix": "eslint --fix src test && pnpm run format",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\" \"*.md\"",
+    "lint": "eslint src test",
+    "prepare": "pnpm run build",
+    "rebuild": "pnpm run clear && pnpm run build",
+    "typecheck": "tsc -p tsconfig.dev.json",
+    "test": "pnpm run fix && pnpm run lint && pnpm run typecheck && pnpm run test:node && pnpm run test:dist",
+    "test:browser": "playwright test",
+    "test:node": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:dist": "pnpm run build && ! grep -rl @interop/logger dist"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./matching": {
+      "types": "./dist/matching.d.ts",
+      "react-native": "./dist/matching.js",
+      "import": "./dist/matching.js",
+      "default": "./dist/matching.js"
+    }
+  },
+  "module": "dist/index.js",
+  "browser": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "dependencies": {
+    "@interop/data-integrity-core": "^8.7.1",
+    "@interop/data-integrity-proof": "^3.4.5",
+    "@interop/ed25519-signature": "^7.2.1",
+    "@interop/security-document-loader": "^10.1.1",
+    "@interop/vc": "^11.0.8",
+    "@interop/webkms-client": "^14.7.5",
+    "@scure/base": "^2.3.0",
+    "byoe-context": "^0.5.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@interop/ed25519-verification-key": "^8.1.0",
+    "@interop/logger": "^0.2.0",
+    "@playwright/test": "^1.60.0",
+    "@types/node": "^26.0.1",
+    "@vitest/coverage-v8": "^4.1.7",
+    "eslint": "^10.4.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.6.0",
+    "prettier": "^3.8.3",
+    "rimraf": "^6.1.3",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.4",
+    "vite": "^8.0.14",
+    "vitest": "^4.1.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "wallet",
+    "verifiable-credentials",
+    "verifiable-presentation-request",
+    "vc-api",
+    "app-connect",
+    "isomorphic"
+  ],
+  "packageManager": "pnpm@12.3.4+sha512.961aa41fb077da3a04a441d9f8e15ebc0c96da8ef710b2eb67bf9ee7cb0610eabd48f1fd85f51cffe73846785fa0f87c56a3a872a1d893f8446741b5cce45457",
+  "engines": {
+    "node": ">=24.0"
+  },
+  "author": {
+    "name": "Interop Alliance",
+    "url": "https://github.com/interop-alliance/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/interop-alliance/wallet-request.git"
+  },
+  "homepage": "https://github.com/interop-alliance/wallet-request",
+  "bugs": "https://github.com/interop-alliance/wallet-request/issues"
+}