@interop/wallet-core 0.69.0 → 0.71.0

package/dist/request/appKey.d.ts

@@ -1,295 +0,0 @@
-import type { IDocumentLoader, IVerifiableCredential } from '@interop/data-integrity-core';
-import { CONTEXT_URL_V1 as APP_CONNECT_CONTEXT_URL } from 'byoe-context';
-import type { IAppConnectApp } from './types.js';
-/**
- * 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 declare const APP_KEY_KEY_NAME = "app-key";
-/**
- * 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 declare 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 declare const APP_KEY_TYPE_ARRAY: readonly string[];
-/**
- * The hosted App Connect context URL every app-key credential carries as the
- * second entry of its `@context` array (after the VC 1.1 context URL). The
- * context document defines the profile's BYOE terms; document loaders resolve
- * it from the bundled `byoe-context` document, so no fetch happens at sign or
- * verification time.
- */
-export { APP_CONNECT_CONTEXT_URL };
-/**
- * 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 declare function presentsAsAppKey(credential: IVerifiableCredential): boolean;
-/**
- * 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 declare class AppKeyRefusedError extends Error {
-    constructor();
-}
-/**
- * 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 declare function assertStorableAppKey(credential: IVerifiableCredential): void;
-/**
- * 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 declare function appKeySeedBindsSubject(credential: IVerifiableCredential): Promise<boolean>;
-/**
- * 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 declare class AppKeyMintInvariantError extends Error {
-    constructor();
-}
-/**
- * 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 declare function assertMintedAppKey(credential: IVerifiableCredential): Promise<void>;
-/**
- * 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.
- *
- * The legacy path ({@link findLegacyAppKeyCredential}) is the same chain
- * with `appUrl` undefined: it selects the credentials carrying no
- * `credentialSubject.appUrl` claim, so one predicate set and one sort serve
- * both paths and a hardening applied here reaches the legacy path too.
- *
- * @param options {object}
- * @param options.credentials {IVerifiableCredential[]}
- * @param [options.appUrl] {string} - The request's `app.appUrl` in
- *   serialized form; undefined selects the legacy credentials that carry no
- *   `appUrl` claim.
- * @param options.origin {string} - The attested requesting origin.
- * @returns {IVerifiableCredential[]}
- */
-export declare function appKeyCandidates({ credentials, appUrl, origin }: {
-    credentials: IVerifiableCredential[];
-    appUrl: string | undefined;
-    origin: string;
-}): IVerifiableCredential[];
-/**
- * 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 declare function findAppKeyCredential({ credentials, appUrl, origin }: {
-    credentials: IVerifiableCredential[];
-    appUrl: string;
-    origin: string;
-}): Promise<IVerifiableCredential | undefined>;
-/**
- * Assembles and signs an app-key credential for a seed the caller supplies:
- * the fixed two-entry type array, the hosted App Connect context URL, 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, and
- * exported for an application's own self-issue path (dev-grant provisioning,
- * tests), so the credential's shape is maintained in one place.
- *
- * @param options {object}
- * @param options.seedBytes {Uint8Array} - The 32-byte master seed; the
- *   derived did:key is both issuer and subject.
- * @param options.appName {string} - Shown on the credential (`name`, and the
- *   default `description`).
- * @param options.appUrl {string} - The app's canonical URL, already in
- *   serialized form.
- * @param options.origin {string} - The attested requesting origin.
- * @param [options.description] {string} - Overrides the default consent
- *   sentence (the legacy re-issue carries the old credential's forward).
- * @param [options.documentLoader] {IDocumentLoader} - JSON-LD loader; defaults
- *   to the shared security loader.
- * @returns {Promise<{ credential: IVerifiableCredential; subjectDid: string }>}
- */
-export declare function issueAppKeyCredential({ seedBytes, appName, appUrl, origin, description, documentLoader: loader }: {
-    seedBytes: Uint8Array;
-    appName: string;
-    appUrl: string;
-    origin: string;
-    description?: string;
-    documentLoader?: IDocumentLoader;
-}): Promise<{
-    credential: IVerifiableCredential;
-    subjectDid: string;
-}>;
-/**
- * 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 declare function mintAppKeyCredential({ app, origin }: {
-    app: IAppConnectApp;
-    origin: string;
-}): Promise<{
-    credential: IVerifiableCredential;
-    subjectDid: string;
-}>;
-/**
- * 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 declare function findLegacyAppKeyCredential({ credentials, origin }: {
-    credentials: IVerifiableCredential[];
-    origin: string;
-}): Promise<IVerifiableCredential | undefined>;
-/**
- * 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
- * hosted App Connect context URL, 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 declare function reissueAppKeyCredential({ credential, app, origin }: {
-    credential: IVerifiableCredential;
-    app: IAppConnectApp;
-    origin: string;
-}): Promise<{
-    credential: IVerifiableCredential;
-    subjectDid: string;
-}>;
-/**
- * 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 declare function appKeySubjectDid(credential: IVerifiableCredential): string | undefined;
-/**
- * The origin (`credentialSubject.origin`) an app-key credential is bound to,
- * when present.
- *
- * @param credential {IVerifiableCredential}
- * @returns {string | undefined}
- */
-export declare function appKeyOrigin(credential: IVerifiableCredential): string | 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 declare function appKeyAppUrl(credential: IVerifiableCredential): string | undefined;
-//# sourceMappingURL=appKey.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"appKey.d.ts","sourceRoot":"","sources":["../../src/request/appKey.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EACV,eAAe,EACf,qBAAqB,EACtB,MAAM,8BAA8B,CAAA;AAMrC,OAAO,EAAE,cAAc,IAAI,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAExE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAShD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAA;AAIzC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,qBAAqB,CAAA;AAEzD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAG9C,CAAA;AAEF;;;;;;GAMG;AACH,OAAO,EAAE,uBAAuB,EAAE,CAAA;AAOlC;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAE3E;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;;CAQ5C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAI5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAED;;;;;;GAMG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;;CAQlD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,IAAI,CAAC,CAOf;AAgDD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,WAAW,EACX,MAAM,EACN,MAAM,EACP,EAAE;IACD,WAAW,EAAE,qBAAqB,EAAE,CAAA;IACpC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,qBAAqB,EAAE,CAU1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,WAAW,EACX,MAAM,EACN,MAAM,EACP,EAAE;IACD,WAAW,EAAE,qBAAqB,EAAE,CAAA;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAU7C;AAaD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,SAAS,EACT,OAAO,EACP,MAAM,EACN,MAAM,EACN,WAA+C,EAC/C,cAAc,EAAE,MAAuB,EACxC,EAAE;IACD,SAAS,EAAE,UAAU,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,eAAe,CAAA;CACjC,GAAG,OAAO,CAAC;IAAE,UAAU,EAAE,qBAAqB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CA4BrE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,GAAG,EACH,MAAM,EACP,EAAE;IACD,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC;IAAE,UAAU,EAAE,qBAAqB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAQrE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,0BAA0B,CAAC,EAC/C,WAAW,EACX,MAAM,EACP,EAAE;IACD,WAAW,EAAE,qBAAqB,EAAE,CAAA;IACpC,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAoB7C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,uBAAuB,CAAC,EAC5C,UAAU,EACV,GAAG,EACH,MAAM,EACP,EAAE;IACD,UAAU,EAAE,qBAAqB,CAAA;IACjC,GAAG,EAAE,cAAc,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC;IAAE,UAAU,EAAE,qBAAqB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAqBrE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,qBAAqB,GAChC,MAAM,GAAG,SAAS,CAEpB;AA4BD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,qBAAqB,GAChC,MAAM,GAAG,SAAS,CAMpB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,qBAAqB,GAChC,MAAM,GAAG,SAAS,CAMpB"}