@interop/wallet-core 0.23.1 → 0.25.0

package/dist/request/appKey.d.ts

@@ -0,0 +1,255 @@
+import type { 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.
+ *
+ * @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 declare function appKeyCandidates({ credentials, appUrl, origin }: {
+    credentials: IVerifiableCredential[];
+    appUrl: string;
+    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>;
+/**
+ * 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

@@ -0,0 +1 @@
+{"version":3,"file":"appKey.d.ts","sourceRoot":"","sources":["../../src/request/appKey.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AAMzE,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;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,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,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;AAmDD;;;;;;;;;;;;;;;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,CAWrE;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,CAwB7C;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,CAwBrE;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"}