@interop/wallet-core 0.23.1 → 0.24.0

package/dist/request/appKey.js

@@ -0,0 +1,498 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The App Connect app-key credential: a self-issued VC that carries a 32-byte
+ * seed an app keeps in the user's wallet so it can open its encrypted data on
+ * this and other devices. Unlike an ordinary credential, the issuer and
+ * subject are NOT the wallet user's DID -- they are a did:key derived from the
+ * seed itself (self-issued by the app key), so the credential validates
+ * standalone and the same seed reconstitutes the same identity on every
+ * client. The credential is bound to the attested requesting origin
+ * (`credentialSubject.origin`) and to the application's canonical URL
+ * (`credentialSubject.appUrl`), and matched wallet-side against both, so a
+ * phishing origin can neither recover an existing app key nor be handed one
+ * minted for another origin, and applications sharing an origin are kept
+ * apart by their `appUrl`s.
+ *
+ * Ported from Freewallet's `src/lib/appKey.ts`, migrated from the
+ * `credentialType` / `vocabBase` model to the App Connect spec's `appUrl`
+ * model: the type array is a fixed two-entry list, the inline `@context` is
+ * one static object identical for every application, and which application a
+ * credential belongs to is a claim (`credentialSubject.appUrl`), not a type.
+ * See the App Connect spec's App Key Credential section for the normative
+ * shape, matching, and minting rules this module implements.
+ */
+import * as vc from '@interop/vc';
+import { base64urlnopad } from '@scure/base';
+import { CapabilityAgent } from '@interop/webkms-client';
+import { Ed25519Signature2020 } from '@interop/ed25519-signature';
+import { issuerId, subjectId, typeArray } from '@interop/data-integrity-core/guards';
+import { documentLoader } from './composeVp.js';
+/**
+ * The semantic `handle` mixed into seed derivation. It identifies the agent
+ * but does not affect the derived key (only the seed bytes and the key name
+ * enter the HMAC), so it is cosmetic; kept for legibility.
+ */
+const APP_KEY_HANDLE = 'freewallet-app-key';
+/**
+ * The key name mixed into seed derivation. Unlike the handle this is
+ * load-bearing: it is the HMAC message in `CapabilityAgent` derivation, so the
+ * exact string is a pinned input of the App Connect key-derivation rule --
+ * every existing app-key credential's identity depends on it.
+ */
+export const APP_KEY_KEY_NAME = 'app-key';
+const VC_1_CONTEXT_URL = 'https://www.w3.org/2018/credentials/v1';
+/**
+ * The marker type every app-key credential carries, mapped to one stable IRI
+ * for every application. It makes "presents as an app key" a term check rather
+ * than a shape heuristic, which is what the store-time refusal
+ * ({@link assertStorableAppKey}) and the match path key off.
+ *
+ * It is a self-declaration, not evidence: the `type` array of a planted
+ * credential is attacker-controlled like the rest of it. The seed-to-subject
+ * binding ({@link appKeySeedBindsSubject}) authenticates only a credential's
+ * internal consistency, never its provenance (a fully attacker-generated
+ * credential binds perfectly). That is exactly why external ingest refuses on
+ * the marker alone, binding or not ({@link assertStorableAppKey}): app keys
+ * are wallet-minted, never imported.
+ */
+export const APP_KEY_CREDENTIAL_TYPE = 'AppKeyCredential';
+/**
+ * The fixed `type` array of every app-key credential: exactly two entries, in
+ * this order, identical for every application. Which application a credential
+ * belongs to is the `credentialSubject.appUrl` claim, not a type.
+ */
+export const APP_KEY_TYPE_ARRAY = Object.freeze([
+    'VerifiableCredential',
+    APP_KEY_CREDENTIAL_TYPE
+]);
+/**
+ * The static inline `@context` object every app-key credential carries as the
+ * second entry of its `@context` array (after the VC 1.1 context URL). The
+ * shape is normative and byte-identical for every application and every
+ * credential: carrying the terms inline keeps the credential verifiable with
+ * no remote vocabulary fetch on either side.
+ */
+export const APP_KEY_CONTEXT = Object.freeze({
+    '@protected': true,
+    AppKeyCredential: 'https://w3id.org/byoe#AppKeyCredential',
+    appUrl: 'https://w3id.org/byoe#appUrl',
+    seed: 'https://w3id.org/byoe#seed',
+    origin: 'https://w3id.org/byoe#origin',
+    name: 'https://schema.org/name',
+    description: 'https://schema.org/description'
+});
+/**
+ * The number of random bytes in an app-key seed.
+ */
+const SEED_BYTE_LENGTH = 32;
+/**
+ * Whether a credential presents as an app key -- that is, carries the
+ * {@link APP_KEY_CREDENTIAL_TYPE} marker in its `type` array. Says nothing
+ * about whether it IS one; that is the seed-to-subject binding's job.
+ *
+ * @param credential {IVerifiableCredential}
+ * @returns {boolean}
+ */
+export function presentsAsAppKey(credential) {
+    return typeArray(credential.type).includes(APP_KEY_CREDENTIAL_TYPE);
+}
+/**
+ * The refusal a store path raises for a credential that presents as an app key
+ * but arrived from outside the wallet's own mint path. A distinct class so the
+ * UI can show its own translated wording rather than this message.
+ */
+export class AppKeyRefusedError extends Error {
+    constructor() {
+        super('This credential claims to be an app key. App keys are created by the ' +
+            'wallet itself and cannot be added from outside, so it was not stored.');
+        this.name = 'AppKeyRefusedError';
+    }
+}
+/**
+ * Refuses any credential that presents as an app key, unconditionally --
+ * whether or not it binds to its own seed. Called on every path that puts a
+ * credential in the store from outside the wallet (a CHAPI store offer, a
+ * URL / QR / manual-paste import), so an externally arriving app key never
+ * reaches the store, the credential list, or the user's Space.
+ *
+ * The seed-to-subject binding ({@link appKeySeedBindsSubject}) authenticates
+ * only the credential's internal consistency, not its provenance: a fully
+ * attacker-generated credential binds perfectly (a fresh seed, the victim
+ * app's `origin` and `appUrl`, self-issued), and storing it would make its
+ * DID the controller the wallet delegates the user's storage to. So there is
+ * no "binds, so it stores" carve-out here: app-key credentials are
+ * wallet-minted, never imported, and only the wallet's own mint path may
+ * store one.
+ *
+ * A credential with no marker is left alone, so an ordinary credential that
+ * merely happens to carry a `seed` or `origin` claim is never caught.
+ *
+ * @param credential {IVerifiableCredential}
+ * @returns {void}   throws the refusal reason
+ */
+export function assertStorableAppKey(credential) {
+    if (presentsAsAppKey(credential)) {
+        throw new AppKeyRefusedError();
+    }
+}
+/**
+ * Whether an app-key credential's subject DID is the one its own seed derives
+ * -- the binding that makes the credential an app key rather than merely a
+ * self-issued claim to be one. Self-issuance is a weak signal (anyone can
+ * self-issue); this is the strong one, and it is fully local: the credential
+ * carries the seed, so re-derive with the same call `mintAppKeyCredential`
+ * uses and compare. Fails closed on an absent, non-base64url, or otherwise
+ * unusable seed rather than throwing out of the match path.
+ *
+ * @param credential {IVerifiableCredential}
+ * @returns {Promise<boolean>}
+ */
+export async function appKeySeedBindsSubject(credential) {
+    const subjectDid = subjectId(credential);
+    const seed = appKeySeedBytes(credential);
+    if (!subjectDid || !seed || seed.length !== SEED_BYTE_LENGTH) {
+        return false;
+    }
+    try {
+        const agent = await CapabilityAgent.fromSeed({
+            seed,
+            handle: APP_KEY_HANDLE,
+            keyName: APP_KEY_KEY_NAME
+        });
+        return agent.id === subjectDid;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Raised by {@link assertMintedAppKey} when a credential offered to the mint
+ * path's store door does not carry the mint invariants. Reaching it means a
+ * caller tried to route a foreign credential through the wallet's own mint
+ * door -- a programming error, not a user-facing refusal, so it is not
+ * translated like {@link AppKeyRefusedError}.
+ */
+export class AppKeyMintInvariantError extends Error {
+    constructor() {
+        super('Only a wallet-minted app-key credential (marker type present, subject ' +
+            'DID derived from its own seed) can be stored through the mint path.');
+        this.name = 'AppKeyMintInvariantError';
+    }
+}
+/**
+ * Asserts the mint invariants on a credential the wallet claims to have just
+ * minted: it presents as an app key (the marker type) and its subject DID
+ * re-derives from the seed it carries. The mirror image of
+ * {@link assertStorableAppKey} -- external ingest refuses every marker
+ * credential, the mint door stores only credentials that carry the full mint
+ * shape -- kept beside it so the two halves of the app-key store policy live
+ * in one module.
+ *
+ * @param credential {IVerifiableCredential}
+ * @returns {Promise<void>}   throws {@link AppKeyMintInvariantError}
+ */
+export async function assertMintedAppKey(credential) {
+    if (!presentsAsAppKey(credential) ||
+        !(await appKeySeedBindsSubject(credential))) {
+        throw new AppKeyMintInvariantError();
+    }
+}
+/**
+ * Whether a credential is self-issued: it names an issuer, and that issuer is
+ * its own subject. The shape every app-key credential has and every planted
+ * one must not be allowed to fake alone.
+ */
+function isSelfIssued(credential) {
+    const issuer = issuerId(credential.issuer);
+    return !!issuer && issuer === subjectId(credential);
+}
+/**
+ * The instant a credential's `issuanceDate` denotes, or NaN when it is
+ * absent, not a string, or does not parse. Ranking is over instants, not raw
+ * strings: the ranking decides which DID the wallet delegates to, so a
+ * comparison manipulable by the *spelling* of a date (a numeric offset,
+ * differing fractional-second precision) would reopen the planted-credential
+ * path in a narrower form.
+ */
+function issuanceInstant(credential) {
+    const raw = credential.issuanceDate;
+    if (typeof raw !== 'string') {
+        return NaN;
+    }
+    return Date.parse(raw);
+}
+/**
+ * Sort comparator ordering credentials latest-first by the instant their
+ * `issuanceDate` denotes; a credential whose date is absent or unparseable
+ * sorts last.
+ */
+function byIssuanceInstantDesc(first, second) {
+    const firstInstant = issuanceInstant(first);
+    const secondInstant = issuanceInstant(second);
+    if (Number.isNaN(firstInstant)) {
+        return Number.isNaN(secondInstant) ? 0 : 1;
+    }
+    if (Number.isNaN(secondInstant)) {
+        return -1;
+    }
+    return secondInstant - firstInstant;
+}
+/**
+ * The app-key candidates for an app + origin, latest-first: everything the
+ * cheap, synchronous predicates accept, so only plausible candidates pay for
+ * a key derivation. A candidate must carry the marker (required, not merely
+ * tolerated: a credential can then only reach the delegation path by carrying
+ * it, which is exactly what the store-time refusal screens), name the
+ * request's `appUrl` in `credentialSubject.appUrl` (both sides in serialized
+ * form -- the wallet mints the claim serialized, so the comparison is an
+ * exact string match), be self-issued, and be bound to the attested
+ * requesting origin. Sorting here (rather than after the binding check) lets
+ * {@link findAppKeyCredential} stop at the newest credential that binds.
+ *
+ * @param options {object}
+ * @param options.credentials {IVerifiableCredential[]}
+ * @param options.appUrl {string} - The request's `app.appUrl` in serialized
+ *   form.
+ * @param options.origin {string} - The attested requesting origin.
+ * @returns {IVerifiableCredential[]}
+ */
+export function appKeyCandidates({ credentials, appUrl, origin }) {
+    return credentials
+        .filter(credential => presentsAsAppKey(credential) &&
+        appKeyAppUrl(credential) === appUrl &&
+        isSelfIssued(credential) &&
+        appKeyOrigin(credential) === origin)
+        .sort(byIssuanceInstantDesc);
+}
+/**
+ * The current (latest) app-key credential for an app + origin, or undefined
+ * when the user has none -- which signals first run for that (origin,
+ * `appUrl`) pair.
+ *
+ * @param options {object}
+ * @param options.credentials {IVerifiableCredential[]}
+ * @param options.appUrl {string} - The request's `app.appUrl` in serialized
+ *   form.
+ * @param options.origin {string} - The attested requesting origin.
+ * @returns {Promise<IVerifiableCredential | undefined>}
+ */
+export async function findAppKeyCredential({ credentials, appUrl, origin }) {
+    // Newest-first, returning at the first credential that binds: a non-binding
+    // one ranked above it is discarded on the way, and the credentials below it
+    // never pay for a key derivation.
+    for (const candidate of appKeyCandidates({ credentials, appUrl, origin })) {
+        if (await appKeySeedBindsSubject(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Assembles and signs an app-key credential for a seed the caller supplies:
+ * the fixed two-entry type array, the static inline context, issuer and
+ * subject both the seed-derived DID, and the `seed` / `appUrl` / `origin`
+ * claims. `vc.issue` auto-fills `issuanceDate` in the canonical UTC form the
+ * ranking expects. Shared by the fresh mint and the legacy re-issue.
+ */
+async function issueAppKeyCredential({ seedBytes, appName, appUrl, origin, description }) {
+    const agent = await CapabilityAgent.fromSeed({
+        seed: seedBytes,
+        handle: APP_KEY_HANDLE,
+        keyName: APP_KEY_KEY_NAME
+    });
+    const controllerDid = agent.id;
+    const credential = {
+        '@context': [VC_1_CONTEXT_URL, { ...APP_KEY_CONTEXT }],
+        id: `urn:uuid:${crypto.randomUUID()}`,
+        type: [...APP_KEY_TYPE_ARRAY],
+        name: `${appName} app key`,
+        description,
+        issuer: controllerDid,
+        credentialSubject: {
+            id: controllerDid,
+            seed: base64urlnopad.encode(seedBytes),
+            appUrl,
+            origin
+        }
+    };
+    const suite = new Ed25519Signature2020({ signer: agent.getSigner() });
+    const signed = (await vc.issue({
+        credential,
+        suite,
+        documentLoader
+    }));
+    return { credential: signed, subjectDid: controllerDid };
+}
+/**
+ * Mints a fresh app-key credential for an app + origin: generates a 32-byte
+ * seed, derives the seed's did:key, and self-issues the credential (issuer ==
+ * subject == the seed-derived DID) with the `credentialSubject.appUrl` claim
+ * set from the validated request value. Does NOT store the result -- the
+ * caller stores it before delegating, so a failed delegation is found as
+ * "returning" on the next attempt rather than minting a second identity.
+ *
+ * @param options {object}
+ * @param options.app {IAppConnectApp} - The validated app identity; its
+ *   `appUrl` must already be in serialized form (`appConnectRequestOf`
+ *   guarantees this).
+ * @param options.origin {string} - The attested requesting origin, never a
+ *   value taken from the request body.
+ * @returns {Promise<{ credential: IVerifiableCredential; subjectDid: string }>}
+ */
+export async function mintAppKeyCredential({ app, origin }) {
+    const seedBytes = crypto.getRandomValues(new Uint8Array(SEED_BYTE_LENGTH));
+    return issueAppKeyCredential({
+        seedBytes,
+        appName: app.name,
+        appUrl: app.appUrl,
+        origin,
+        description: `The ${app.name} app keeps this key in your wallet so it can open ` +
+            'your encrypted data on this and other devices.'
+    });
+}
+/**
+ * The latest legacy app-key credential for an origin, or undefined. A legacy
+ * credential predates the `appUrl` model: it carries the marker and a
+ * per-app third type entry, but no `credentialSubject.appUrl` claim. Its
+ * identity was scoped to (origin, `credentialType`), and the request no
+ * longer carries a `credentialType` to select on, so the mapping is
+ * recoverable only when it is unambiguous: when the binding legacy candidates
+ * for the origin all name one subject DID. Two distinct legacy identities on
+ * one origin yield undefined rather than a guess -- re-issuing the wrong one
+ * would hand one application another's identity, which is worse than the
+ * caller treating the connect as a first run.
+ *
+ * @param options {object}
+ * @param options.credentials {IVerifiableCredential[]}
+ * @param options.origin {string} - The attested requesting origin.
+ * @returns {Promise<IVerifiableCredential | undefined>}
+ */
+export async function findLegacyAppKeyCredential({ credentials, origin }) {
+    const candidates = credentials
+        .filter(credential => presentsAsAppKey(credential) &&
+        appKeyAppUrl(credential) === undefined &&
+        isSelfIssued(credential) &&
+        appKeyOrigin(credential) === origin)
+        .sort(byIssuanceInstantDesc);
+    const bound = [];
+    for (const candidate of candidates) {
+        if (await appKeySeedBindsSubject(candidate)) {
+            bound.push(candidate);
+        }
+    }
+    if (bound.length === 0) {
+        return undefined;
+    }
+    const subjects = new Set(bound.map(credential => subjectId(credential)));
+    if (subjects.size > 1) {
+        return undefined;
+    }
+    return bound[0];
+}
+/**
+ * Re-issues a legacy app-key credential in place under the `appUrl` model:
+ * the same seed (so the same derived DID -- the app's identity and its
+ * encrypted-data access are preserved), the fixed two-entry type array, the
+ * static inline context, and the `credentialSubject.appUrl` claim set from
+ * the validated request value. A fresh mint would roll the seed and orphan
+ * the identity, and must never be the migration path. The fresh
+ * `issuanceDate` ranks the re-issued credential ahead of the legacy one, so
+ * subsequent connects match it directly.
+ *
+ * Does NOT store the result; the caller stores it through the mint door
+ * (it satisfies {@link assertMintedAppKey}) and may retire the legacy record.
+ *
+ * @param options {object}
+ * @param options.credential {IVerifiableCredential} - The legacy credential;
+ *   it must bind per {@link appKeySeedBindsSubject} and be bound to `origin`,
+ *   else this throws {@link AppKeyMintInvariantError}.
+ * @param options.app {IAppConnectApp} - The validated app identity; its
+ *   `appUrl` must already be in serialized form.
+ * @param options.origin {string} - The attested requesting origin.
+ * @returns {Promise<{ credential: IVerifiableCredential; subjectDid: string }>}
+ */
+export async function reissueAppKeyCredential({ credential, app, origin }) {
+    if (!(await appKeySeedBindsSubject(credential)) ||
+        appKeyOrigin(credential) !== origin) {
+        throw new AppKeyMintInvariantError();
+    }
+    const seedBytes = appKeySeedBytes(credential);
+    if (!seedBytes) {
+        throw new AppKeyMintInvariantError();
+    }
+    const legacyDescription = credential
+        .description;
+    return issueAppKeyCredential({
+        seedBytes,
+        appName: app.name,
+        appUrl: app.appUrl,
+        origin,
+        description: typeof legacyDescription === 'string'
+            ? legacyDescription
+            : `The ${app.name} app keeps this key in your wallet so it can ` +
+                'open your encrypted data on this and other devices.'
+    });
+}
+/**
+ * The subject DID (`credentialSubject.id`) of an app-key credential, or
+ * undefined. For a valid app-key credential this equals the issuer.
+ *
+ * @param credential {IVerifiableCredential}
+ * @returns {string | undefined}
+ */
+export function appKeySubjectDid(credential) {
+    return subjectId(credential);
+}
+/**
+ * The 32-byte seed an app-key credential carries
+ * (`credentialSubject.seed`, base64url-no-pad), or undefined when it is absent
+ * or malformed. This is the app's client secret, the root of its identity and
+ * of the keys it encrypts its own data with. The wallet reads it only to
+ * re-derive the credential's subject DID ({@link appKeySeedBindsSubject}) and
+ * to re-issue a legacy credential under the same identity; nothing downstream
+ * of the match takes the seed, so it never reaches the grant path.
+ *
+ * @param credential {IVerifiableCredential}
+ * @returns {Uint8Array | undefined}
+ */
+function appKeySeedBytes(credential) {
+    const subject = credential.credentialSubject;
+    if (!subject || typeof subject.seed !== 'string') {
+        return undefined;
+    }
+    try {
+        return base64urlnopad.decode(subject.seed);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The origin (`credentialSubject.origin`) an app-key credential is bound to,
+ * when present.
+ *
+ * @param credential {IVerifiableCredential}
+ * @returns {string | undefined}
+ */
+export function appKeyOrigin(credential) {
+    const subject = credential.credentialSubject;
+    return subject && typeof subject.origin === 'string'
+        ? subject.origin
+        : undefined;
+}
+/**
+ * The application URL (`credentialSubject.appUrl`) an app-key credential is
+ * scoped to, when present. Absent on a legacy (pre-`appUrl`) credential.
+ *
+ * @param credential {IVerifiableCredential}
+ * @returns {string | undefined}
+ */
+export function appKeyAppUrl(credential) {
+    const subject = credential.credentialSubject;
+    return subject && typeof subject.appUrl === 'string'
+        ? subject.appUrl
+        : undefined;
+}
+//# sourceMappingURL=appKey.js.map

package/dist/request/appKey.js.map

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

package/dist/request/classify.d.ts

@@ -9,10 +9,11 @@
  *
  * Ported from Freewallet's `src/lib/walletRequest/classify.ts` (the superset of
  * DCW's `app/lib/exchanges.ts` / `walletRequestApi.ts` dispatch helpers). The
- * App Connect query kind is a Freewallet-only extension and stays app-side; the
- * shared classifier covers the three VPR-spec query types.
+ * shared classifier covers the three VPR-spec query types plus the App Connect
+ * `AppConnectQuery` extension (`appConnectRequestOf`), whose `app` block is
+ * validated here against the attested requesting origin.
  */
-import type { CHAPIStoreEvent, ICapabilityQueryDetail, ICredentialQuery, IQueryByExample, IVPOffer, IVPRequest, IVPRDetails, IVPRQuery, IVerifiableCredential, IVerifiablePresentation, WalletRequestProfile } from './types.js';
+import type { CHAPIStoreEvent, IAppConnectRequest, ICapabilityQueryDetail, ICredentialQuery, IQueryByExample, IVPOffer, IVPRequest, IVPRDetails, IVPRQuery, IVerifiableCredential, IVerifiablePresentation, WalletRequestProfile } from './types.js';
 import type { CHAPIGetEvent } from './types.js';
 /**
  * The VC data model version a presentation carrying the given credentials must
@@ -90,6 +91,56 @@ export declare function credentialQueriesOf(query: IQueryByExample): ICredential
  * @returns {ICapabilityQueryDetail[]}
  */
 export declare function zcapQueriesOf(queries: IVPRQuery[]): ICapabilityQueryDetail[];
+/**
+ * Validates an App Connect `app.appUrl` against the attested requesting origin
+ * and returns its serialized form. The value must parse as an absolute URL,
+ * must not carry a fragment, and its origin must equal the attested origin;
+ * any violation throws (the query is malformed). All storage and comparison
+ * downstream uses the returned serialization, so spellings differing only in
+ * a default port, percent-encoding case, or dot-segments do not name distinct
+ * applications.
+ *
+ * The fragment check reads the serialized URL rather than `url.hash`: a bare
+ * trailing `#` sets an empty (non-null) fragment that `hash` reports as `''`,
+ * and a percent-encoded `%23` never appears as `#` in the serialization.
+ *
+ * @param options {object}
+ * @param options.appUrl {string} - The request's `app.appUrl`.
+ * @param options.origin {string} - The attested requesting origin.
+ * @returns {string} The parsed URL's serialization.
+ */
+export declare function serializedAppUrl({ appUrl, origin }: {
+    appUrl: string;
+    origin: string;
+}): string;
+/**
+ * Extracts the App Connect request from a query set, when one is present. An
+ * `AppConnectQuery` is one mental model per popup: the request must not also
+ * carry `QueryByExample` or standalone zcap queries, at most one
+ * `AppConnectQuery` is allowed, and its `app` block must carry the display
+ * `name` and the `appUrl` the wallet needs to match or mint the app-key
+ * credential -- with the `appUrl` validated against the attested requesting
+ * origin and rewritten to its serialized form ({@link serializedAppUrl}).
+ * Violations throw; classification-time callers surface the throw as a
+ * malformed-request state. The capability queries are normalized to an array
+ * (absent means "no grants requested" -- a connect that only recovers the app
+ * key is legal), and each entry is rebuilt from an allowlist of the declared
+ * fields (`referenceId`, `allowedAction`, `invocationTarget`): the type-level
+ * Omit does not bind an actual request body, so any other wire-level field --
+ * a smuggled `reason`, an attacker-chosen `controller`, a future
+ * display-bearing addition -- is made unrepresentable here, before the entries
+ * reach the profile the consent screen and the delegation path read.
+ *
+ * @param options {object}
+ * @param options.queries {IVPRQuery[]}
+ * @param options.origin {string} - The attested requesting origin the
+ *   `appUrl` is validated against.
+ * @returns {IAppConnectRequest | null}
+ */
+export declare function appConnectRequestOf({ queries, origin }: {
+    queries: IVPRQuery[];
+    origin: string;
+}): IAppConnectRequest | null;
 /**
  * Classifies a VPR body onto the independent axes the consent screen and
  * response assembly work from: whether DID Authentication is requested, and

package/dist/request/classify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../src/request/classify.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAEhB,eAAe,EACf,QAAQ,EACR,UAAU,EACV,WAAW,EACX,SAAS,EACT,qBAAqB,EACrB,uBAAuB,EAEvB,oBAAoB,EACrB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAO/C;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,qBAAqB,EAAE,GACnC,MAAM,CAOR;AA0DD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,uBAAuB,GACpC,qBAAqB,EAAE,CAQzB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAYtE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,QAAQ,CAKxE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,OAAO,EACR,EAAE;IACD,OAAO,EAAE,SAAS,EAAE,CAAA;CACrB,GAAG,OAAO,CAQV;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,EAAE,CAS3D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,GACrB,gBAAgB,EAAE,CAMpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,sBAAsB,EAAE,CAoB5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,oBAAoB,CAS1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAMpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,OAAO,CAQpE"}
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../src/request/classify.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EACV,eAAe,EAGf,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAEhB,eAAe,EACf,QAAQ,EACR,UAAU,EACV,WAAW,EACX,SAAS,EACT,qBAAqB,EACrB,uBAAuB,EAEvB,oBAAoB,EACrB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAO/C;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,qBAAqB,EAAE,GACnC,MAAM,CAOR;AA0DD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,uBAAuB,GACpC,qBAAqB,EAAE,CAQzB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAYtE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,QAAQ,CAKxE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,OAAO,EACR,EAAE;IACD,OAAO,EAAE,SAAS,EAAE,CAAA;CACrB,GAAG,OAAO,CAQV;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,EAAE,CAS3D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,GACrB,gBAAgB,EAAE,CAMpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,sBAAsB,EAAE,CAoB5E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,MAAM,EACP,EAAE;IACD,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,MAAM,CA4BT;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,OAAO,EACP,MAAM,EACP,EAAE;IACD,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,kBAAkB,GAAG,IAAI,CAmD5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,oBAAoB,CAS1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAMpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,OAAO,CAQpE"}