@interop/wallet-request 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +20 -0
- package/README.md +160 -0
- package/dist/appKey.d.ts +295 -0
- package/dist/appKey.d.ts.map +1 -0
- package/dist/appKey.js +516 -0
- package/dist/appKey.js.map +1 -0
- package/dist/capabilityRequest.d.ts +41 -0
- package/dist/capabilityRequest.d.ts.map +1 -0
- package/dist/capabilityRequest.js +46 -0
- package/dist/capabilityRequest.js.map +1 -0
- package/dist/classify.d.ts +233 -0
- package/dist/classify.d.ts.map +1 -0
- package/dist/classify.js +419 -0
- package/dist/classify.js.map +1 -0
- package/dist/composeVp.d.ts +52 -0
- package/dist/composeVp.d.ts.map +1 -0
- package/dist/composeVp.js +176 -0
- package/dist/composeVp.js.map +1 -0
- package/dist/ephemeralExchange.d.ts +100 -0
- package/dist/ephemeralExchange.d.ts.map +1 -0
- package/dist/ephemeralExchange.js +230 -0
- package/dist/ephemeralExchange.js.map +1 -0
- package/dist/exchangeClient.d.ts +142 -0
- package/dist/exchangeClient.d.ts.map +1 -0
- package/dist/exchangeClient.js +241 -0
- package/dist/exchangeClient.js.map +1 -0
- package/dist/index.d.ts +63 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +62 -0
- package/dist/index.js.map +1 -0
- package/dist/interactionRequest.d.ts +23 -0
- package/dist/interactionRequest.d.ts.map +1 -0
- package/dist/interactionRequest.js +46 -0
- package/dist/interactionRequest.js.map +1 -0
- package/dist/interactionUrl.d.ts +42 -0
- package/dist/interactionUrl.d.ts.map +1 -0
- package/dist/interactionUrl.js +104 -0
- package/dist/interactionUrl.js.map +1 -0
- package/dist/log.d.ts +49 -0
- package/dist/log.d.ts.map +1 -0
- package/dist/log.js +53 -0
- package/dist/log.js.map +1 -0
- package/dist/matching.d.ts +95 -0
- package/dist/matching.d.ts.map +1 -0
- package/dist/matching.js +205 -0
- package/dist/matching.js.map +1 -0
- package/dist/onboarding.d.ts +96 -0
- package/dist/onboarding.d.ts.map +1 -0
- package/dist/onboarding.js +174 -0
- package/dist/onboarding.js.map +1 -0
- package/dist/parse.d.ts +63 -0
- package/dist/parse.d.ts.map +1 -0
- package/dist/parse.js +153 -0
- package/dist/parse.js.map +1 -0
- package/dist/presentationSuite.d.ts +71 -0
- package/dist/presentationSuite.d.ts.map +1 -0
- package/dist/presentationSuite.js +143 -0
- package/dist/presentationSuite.js.map +1 -0
- package/dist/processRequest.d.ts +45 -0
- package/dist/processRequest.d.ts.map +1 -0
- package/dist/processRequest.js +146 -0
- package/dist/processRequest.js.map +1 -0
- package/dist/queryPredicates.d.ts +112 -0
- package/dist/queryPredicates.d.ts.map +1 -0
- package/dist/queryPredicates.js +157 -0
- package/dist/queryPredicates.js.map +1 -0
- package/dist/types.d.ts +257 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -0
- package/dist/walletInput.d.ts +118 -0
- package/dist/walletInput.d.ts.map +1 -0
- package/dist/walletInput.js +169 -0
- package/dist/walletInput.js.map +1 -0
- package/package.json +98 -0
package/LICENSE.md
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Interop Alliance
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
|
6
|
+
this software and associated documentation files (the "Software"), to deal in
|
|
7
|
+
the Software without restriction, including without limitation the rights to
|
|
8
|
+
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
|
9
|
+
the Software, and to permit persons to whom the Software is furnished to do so,
|
|
10
|
+
subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
|
17
|
+
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
|
18
|
+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
|
19
|
+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
20
|
+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# Wallet Request _(@interop/wallet-request)_
|
|
2
|
+
|
|
3
|
+
[](https://github.com/interop-alliance/wallet-request/actions?query=workflow%3A%22CI%22)
|
|
4
|
+
[](https://npm.im/@interop/wallet-request)
|
|
5
|
+
|
|
6
|
+
> Wallet-request / exchange-protocol handling for the browser, Node.js, and
|
|
7
|
+
> React Native: input classification, VPR parsing, QueryByExample matching,
|
|
8
|
+
> cryptosuite negotiation, VP composition, and the VC-API / ephemeral-exchange
|
|
9
|
+
> clients.
|
|
10
|
+
|
|
11
|
+
## Table of Contents
|
|
12
|
+
|
|
13
|
+
- [Background](#background)
|
|
14
|
+
- [Security](#security)
|
|
15
|
+
- [Install](#install)
|
|
16
|
+
- [Usage](#usage)
|
|
17
|
+
- [Contribute](#contribute)
|
|
18
|
+
- [License](#license)
|
|
19
|
+
|
|
20
|
+
## Background
|
|
21
|
+
|
|
22
|
+
`@interop/wallet-request` is the wallet side of a Verifiable Presentation
|
|
23
|
+
Request exchange: everything between "the user scanned or pasted something" and
|
|
24
|
+
"here is the signed response". It covers:
|
|
25
|
+
|
|
26
|
+
- **Input classification** -- `classifyWalletInput` / `handleWalletInput`, one
|
|
27
|
+
ordered discrimination for every place a wallet accepts arbitrary text (a QR
|
|
28
|
+
scan, a paste box, a file drop, an opened deep link): a wallet-connection
|
|
29
|
+
payload, a client-enrollment connect code, a legacy credential-request link, a
|
|
30
|
+
VCALM interaction URL, a registered deep link, a wallet API message, or raw
|
|
31
|
+
credential JSON. Classification does no fetch, navigation, or storage.
|
|
32
|
+
- **Parsing and classification of exchange messages** -- `parse.ts` turns deep
|
|
33
|
+
links and JSON into typed messages, `classify.ts` turns CHAPI events and VPRs
|
|
34
|
+
into typed requests, including the App Connect `AppConnectQuery` extension.
|
|
35
|
+
- **Matching** -- `matching.ts` filters stored credentials against a
|
|
36
|
+
QueryByExample, with both wallets' matchers shipped side by side.
|
|
37
|
+
- **VP composition and cryptosuite negotiation** -- `composeVp.ts` builds the
|
|
38
|
+
response presentation, embedding any grants before signing so the DIDAuth
|
|
39
|
+
proof covers them; `presentationSuite.ts` negotiates the cryptosuite.
|
|
40
|
+
- **The App Connect app-key credential** -- `appKey.ts`: matching, minting, the
|
|
41
|
+
store-time refusal policy, and the legacy re-issue path.
|
|
42
|
+
- **The `WalletOnboardingQuery` transport vocabulary** -- `onboarding.ts`: the
|
|
43
|
+
inviter's compose helper and the enrollee's classification, over a query
|
|
44
|
+
carrying the account pointer and controller.
|
|
45
|
+
- **Exchange clients** -- `exchangeClient.ts` (VC-API, fetch-injectable),
|
|
46
|
+
`interactionUrl.ts` / `interactionRequest.ts` (VCALM interaction URLs),
|
|
47
|
+
`ephemeralExchange.ts` (the requester's side of a WAS server's ephemeral
|
|
48
|
+
exchange), and `capabilityRequest.ts` (the zcap-only VPR a requester stores on
|
|
49
|
+
one).
|
|
50
|
+
- **`processRequest.ts`** -- the pure request-to-response pipeline; consent and
|
|
51
|
+
the response channel stay with the caller.
|
|
52
|
+
|
|
53
|
+
The package was extracted verbatim from `@interop/wallet-core`'s `request`
|
|
54
|
+
subpath. The Verifiable Presentation Request vocabulary is owned by
|
|
55
|
+
[`@interop/data-integrity-core`](https://npm.im/@interop/data-integrity-core)
|
|
56
|
+
and re-exported from the root here, so a consumer imports one package.
|
|
57
|
+
|
|
58
|
+
Two grammars this package classifies belong to a wallet's account convention
|
|
59
|
+
rather than to this package: the `was-link` wallet-connection payload and the
|
|
60
|
+
connect-code prefix are defined in `@interop/wallet-core` (`space` and
|
|
61
|
+
`enrollment`), beside the ceremonies that consume them. `classifyWalletInput`
|
|
62
|
+
and `handleWalletInput` take each as an injected `recognizers` predicate instead
|
|
63
|
+
of importing the convention. A wallet on a WAS account wires `isWasLinkPayload`
|
|
64
|
+
(from `@interop/wallet-core/space`) and `isConnectCode` (from
|
|
65
|
+
`@interop/wallet-core/enrollment`); a wallet holding no WAS account passes
|
|
66
|
+
neither, and those branches never match. This package depends on nothing in
|
|
67
|
+
`@interop/wallet-core`, and `@interop/wallet-core` imports nothing from here.
|
|
68
|
+
|
|
69
|
+
## Security
|
|
70
|
+
|
|
71
|
+
- **Classification does no I/O.** `classifyWalletInput`, `handleWalletInput`,
|
|
72
|
+
`parse.ts`, and `classify.ts` never fetch, navigate, or write to storage. The
|
|
73
|
+
one network seam in the package is the injected `FetchLike` the exchange
|
|
74
|
+
clients take.
|
|
75
|
+
- **`processRequest` is pure.** Consent and the response channel stay with the
|
|
76
|
+
caller; zcap and App Connect processing arrive as injected
|
|
77
|
+
`RequestProcessors`.
|
|
78
|
+
- **The App Connect `appUrl` origin rule.** An `AppConnectQuery`'s `app.appUrl`
|
|
79
|
+
must parse as an absolute URL, carry no fragment, and be same-origin with the
|
|
80
|
+
attested requesting origin. An opaque origin serializes as `"null"` and is
|
|
81
|
+
refused rather than compared as same-origin with itself.
|
|
82
|
+
- **Grants are signed inside the VP.** `composeVp.ts` embeds grants in the
|
|
83
|
+
presentation before signing, so the DIDAuth proof covers them.
|
|
84
|
+
- **App keys are wallet-minted.** `appKey.ts`'s store-time refusal policy
|
|
85
|
+
rejects an imported app-key credential; only a credential this package minted
|
|
86
|
+
may be stored.
|
|
87
|
+
- **Every field is untrusted input.** VPRs, CHAPI events, and pasted or scanned
|
|
88
|
+
text all come from outside the wallet. Helpers here validate shape and refuse
|
|
89
|
+
malformed input rather than silently guessing at it.
|
|
90
|
+
|
|
91
|
+
## Install
|
|
92
|
+
|
|
93
|
+
- Node.js 24+ is recommended.
|
|
94
|
+
|
|
95
|
+
### PNPM
|
|
96
|
+
|
|
97
|
+
To install via PNPM:
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
pnpm install @interop/wallet-request
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Development
|
|
104
|
+
|
|
105
|
+
To install locally (for development):
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
git clone https://github.com/interop-alliance/wallet-request.git
|
|
109
|
+
cd wallet-request
|
|
110
|
+
pnpm install
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## Usage
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
import {
|
|
117
|
+
classifyWalletInput,
|
|
118
|
+
handleWalletInput,
|
|
119
|
+
classifyRequest,
|
|
120
|
+
composeVp,
|
|
121
|
+
processRequest
|
|
122
|
+
} from '@interop/wallet-request'
|
|
123
|
+
import { deepMatch } from '@interop/wallet-request/matching'
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
A wallet on a WAS account wires the two account-convention recognizers from
|
|
127
|
+
`@interop/wallet-core`:
|
|
128
|
+
|
|
129
|
+
```ts
|
|
130
|
+
import { handleWalletInput } from '@interop/wallet-request'
|
|
131
|
+
import { isWasLinkPayload } from '@interop/wallet-core/space'
|
|
132
|
+
import { isConnectCode } from '@interop/wallet-core/enrollment'
|
|
133
|
+
|
|
134
|
+
await handleWalletInput({
|
|
135
|
+
text: scannedText,
|
|
136
|
+
recognizers: { isWasLink: isWasLinkPayload, isConnectCode },
|
|
137
|
+
handlers: {
|
|
138
|
+
wasLink: input => joinWasAccount(input.text),
|
|
139
|
+
connectCode: input => approveEnrollment(input.text),
|
|
140
|
+
credentials: input => resolveCredentialsInput(input.text)
|
|
141
|
+
// ... the remaining kinds an app implements
|
|
142
|
+
}
|
|
143
|
+
})
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
The root exports every module. `./matching` is a separate leaf export: the
|
|
147
|
+
QueryByExample matchers alone, so a wallet's matching tests load without the
|
|
148
|
+
VP-signing and document-loader graph.
|
|
149
|
+
|
|
150
|
+
## Contribute
|
|
151
|
+
|
|
152
|
+
PRs accepted. See [CONTRIBUTING.md](CONTRIBUTING.md) for editor setup (Prettier,
|
|
153
|
+
ESLint, and EditorConfig) and how it maps to CI.
|
|
154
|
+
|
|
155
|
+
If editing the Readme, please conform to the
|
|
156
|
+
[standard-readme](https://github.com/RichardLitt/standard-readme) specification.
|
|
157
|
+
|
|
158
|
+
## License
|
|
159
|
+
|
|
160
|
+
[MIT License](LICENSE.md) © 2026 Interop Alliance.
|
package/dist/appKey.d.ts
ADDED
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
import type { IDocumentLoader, IVerifiableCredential } from '@interop/data-integrity-core';
|
|
2
|
+
import { CONTEXT_URL_V1 as APP_CONNECT_CONTEXT_URL } from 'byoe-context';
|
|
3
|
+
import type { IAppConnectApp } from './types.js';
|
|
4
|
+
/**
|
|
5
|
+
* The key name mixed into seed derivation. Unlike the handle this is
|
|
6
|
+
* load-bearing: it is the HMAC message in `CapabilityAgent` derivation, so the
|
|
7
|
+
* exact string is a pinned input of the App Connect key-derivation rule --
|
|
8
|
+
* every existing app-key credential's identity depends on it.
|
|
9
|
+
*/
|
|
10
|
+
export declare const APP_KEY_KEY_NAME = "app-key";
|
|
11
|
+
/**
|
|
12
|
+
* The marker type every app-key credential carries, mapped to one stable IRI
|
|
13
|
+
* for every application. It makes "presents as an app key" a term check rather
|
|
14
|
+
* than a shape heuristic, which is what the store-time refusal
|
|
15
|
+
* ({@link assertStorableAppKey}) and the match path key off.
|
|
16
|
+
*
|
|
17
|
+
* It is a self-declaration, not evidence: the `type` array of a planted
|
|
18
|
+
* credential is attacker-controlled like the rest of it. The seed-to-subject
|
|
19
|
+
* binding ({@link appKeySeedBindsSubject}) authenticates only a credential's
|
|
20
|
+
* internal consistency, never its provenance (a fully attacker-generated
|
|
21
|
+
* credential binds perfectly). That is exactly why external ingest refuses on
|
|
22
|
+
* the marker alone, binding or not ({@link assertStorableAppKey}): app keys
|
|
23
|
+
* are wallet-minted, never imported.
|
|
24
|
+
*/
|
|
25
|
+
export declare const APP_KEY_CREDENTIAL_TYPE = "AppKeyCredential";
|
|
26
|
+
/**
|
|
27
|
+
* The fixed `type` array of every app-key credential: exactly two entries, in
|
|
28
|
+
* this order, identical for every application. Which application a credential
|
|
29
|
+
* belongs to is the `credentialSubject.appUrl` claim, not a type.
|
|
30
|
+
*/
|
|
31
|
+
export declare const APP_KEY_TYPE_ARRAY: readonly string[];
|
|
32
|
+
/**
|
|
33
|
+
* The hosted App Connect context URL every app-key credential carries as the
|
|
34
|
+
* second entry of its `@context` array (after the VC 1.1 context URL). The
|
|
35
|
+
* context document defines the profile's BYOE terms; document loaders resolve
|
|
36
|
+
* it from the bundled `byoe-context` document, so no fetch happens at sign or
|
|
37
|
+
* verification time.
|
|
38
|
+
*/
|
|
39
|
+
export { APP_CONNECT_CONTEXT_URL };
|
|
40
|
+
/**
|
|
41
|
+
* Whether a credential presents as an app key -- that is, carries the
|
|
42
|
+
* {@link APP_KEY_CREDENTIAL_TYPE} marker in its `type` array. Says nothing
|
|
43
|
+
* about whether it IS one; that is the seed-to-subject binding's job.
|
|
44
|
+
*
|
|
45
|
+
* @param credential {IVerifiableCredential}
|
|
46
|
+
* @returns {boolean}
|
|
47
|
+
*/
|
|
48
|
+
export declare function presentsAsAppKey(credential: IVerifiableCredential): boolean;
|
|
49
|
+
/**
|
|
50
|
+
* The refusal a store path raises for a credential that presents as an app key
|
|
51
|
+
* but arrived from outside the wallet's own mint path. A distinct class so the
|
|
52
|
+
* UI can show its own translated wording rather than this message.
|
|
53
|
+
*/
|
|
54
|
+
export declare class AppKeyRefusedError extends Error {
|
|
55
|
+
constructor();
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Refuses any credential that presents as an app key, unconditionally --
|
|
59
|
+
* whether or not it binds to its own seed. Called on every path that puts a
|
|
60
|
+
* credential in the store from outside the wallet (a CHAPI store offer, a
|
|
61
|
+
* URL / QR / manual-paste import), so an externally arriving app key never
|
|
62
|
+
* reaches the store, the credential list, or the user's Space.
|
|
63
|
+
*
|
|
64
|
+
* The seed-to-subject binding ({@link appKeySeedBindsSubject}) authenticates
|
|
65
|
+
* only the credential's internal consistency, not its provenance: a fully
|
|
66
|
+
* attacker-generated credential binds perfectly (a fresh seed, the victim
|
|
67
|
+
* app's `origin` and `appUrl`, self-issued), and storing it would make its
|
|
68
|
+
* DID the controller the wallet delegates the user's storage to. So there is
|
|
69
|
+
* no "binds, so it stores" carve-out here: app-key credentials are
|
|
70
|
+
* wallet-minted, never imported, and only the wallet's own mint path may
|
|
71
|
+
* store one.
|
|
72
|
+
*
|
|
73
|
+
* A credential with no marker is left alone, so an ordinary credential that
|
|
74
|
+
* merely happens to carry a `seed` or `origin` claim is never caught.
|
|
75
|
+
*
|
|
76
|
+
* @param credential {IVerifiableCredential}
|
|
77
|
+
* @returns {void} throws the refusal reason
|
|
78
|
+
*/
|
|
79
|
+
export declare function assertStorableAppKey(credential: IVerifiableCredential): void;
|
|
80
|
+
/**
|
|
81
|
+
* Whether an app-key credential's subject DID is the one its own seed derives
|
|
82
|
+
* -- the binding that makes the credential an app key rather than merely a
|
|
83
|
+
* self-issued claim to be one. Self-issuance is a weak signal (anyone can
|
|
84
|
+
* self-issue); this is the strong one, and it is fully local: the credential
|
|
85
|
+
* carries the seed, so re-derive with the same call `mintAppKeyCredential`
|
|
86
|
+
* uses and compare. Fails closed on an absent, non-base64url, or otherwise
|
|
87
|
+
* unusable seed rather than throwing out of the match path.
|
|
88
|
+
*
|
|
89
|
+
* @param credential {IVerifiableCredential}
|
|
90
|
+
* @returns {Promise<boolean>}
|
|
91
|
+
*/
|
|
92
|
+
export declare function appKeySeedBindsSubject(credential: IVerifiableCredential): Promise<boolean>;
|
|
93
|
+
/**
|
|
94
|
+
* Raised by {@link assertMintedAppKey} when a credential offered to the mint
|
|
95
|
+
* path's store door does not carry the mint invariants. Reaching it means a
|
|
96
|
+
* caller tried to route a foreign credential through the wallet's own mint
|
|
97
|
+
* door -- a programming error, not a user-facing refusal, so it is not
|
|
98
|
+
* translated like {@link AppKeyRefusedError}.
|
|
99
|
+
*/
|
|
100
|
+
export declare class AppKeyMintInvariantError extends Error {
|
|
101
|
+
constructor();
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Asserts the mint invariants on a credential the wallet claims to have just
|
|
105
|
+
* minted: it presents as an app key (the marker type) and its subject DID
|
|
106
|
+
* re-derives from the seed it carries. The mirror image of
|
|
107
|
+
* {@link assertStorableAppKey} -- external ingest refuses every marker
|
|
108
|
+
* credential, the mint door stores only credentials that carry the full mint
|
|
109
|
+
* shape -- kept beside it so the two halves of the app-key store policy live
|
|
110
|
+
* in one module.
|
|
111
|
+
*
|
|
112
|
+
* @param credential {IVerifiableCredential}
|
|
113
|
+
* @returns {Promise<void>} throws {@link AppKeyMintInvariantError}
|
|
114
|
+
*/
|
|
115
|
+
export declare function assertMintedAppKey(credential: IVerifiableCredential): Promise<void>;
|
|
116
|
+
/**
|
|
117
|
+
* The app-key candidates for an app + origin, latest-first: everything the
|
|
118
|
+
* cheap, synchronous predicates accept, so only plausible candidates pay for
|
|
119
|
+
* a key derivation. A candidate must carry the marker (required, not merely
|
|
120
|
+
* tolerated: a credential can then only reach the delegation path by carrying
|
|
121
|
+
* it, which is exactly what the store-time refusal screens), name the
|
|
122
|
+
* request's `appUrl` in `credentialSubject.appUrl` (both sides in serialized
|
|
123
|
+
* form -- the wallet mints the claim serialized, so the comparison is an
|
|
124
|
+
* exact string match), be self-issued, and be bound to the attested
|
|
125
|
+
* requesting origin. Sorting here (rather than after the binding check) lets
|
|
126
|
+
* {@link findAppKeyCredential} stop at the newest credential that binds.
|
|
127
|
+
*
|
|
128
|
+
* The legacy path ({@link findLegacyAppKeyCredential}) is the same chain
|
|
129
|
+
* with `appUrl` undefined: it selects the credentials carrying no
|
|
130
|
+
* `credentialSubject.appUrl` claim, so one predicate set and one sort serve
|
|
131
|
+
* both paths and a hardening applied here reaches the legacy path too.
|
|
132
|
+
*
|
|
133
|
+
* @param options {object}
|
|
134
|
+
* @param options.credentials {IVerifiableCredential[]}
|
|
135
|
+
* @param [options.appUrl] {string} - The request's `app.appUrl` in
|
|
136
|
+
* serialized form; undefined selects the legacy credentials that carry no
|
|
137
|
+
* `appUrl` claim.
|
|
138
|
+
* @param options.origin {string} - The attested requesting origin.
|
|
139
|
+
* @returns {IVerifiableCredential[]}
|
|
140
|
+
*/
|
|
141
|
+
export declare function appKeyCandidates({ credentials, appUrl, origin }: {
|
|
142
|
+
credentials: IVerifiableCredential[];
|
|
143
|
+
appUrl: string | undefined;
|
|
144
|
+
origin: string;
|
|
145
|
+
}): IVerifiableCredential[];
|
|
146
|
+
/**
|
|
147
|
+
* The current (latest) app-key credential for an app + origin, or undefined
|
|
148
|
+
* when the user has none -- which signals first run for that (origin,
|
|
149
|
+
* `appUrl`) pair.
|
|
150
|
+
*
|
|
151
|
+
* @param options {object}
|
|
152
|
+
* @param options.credentials {IVerifiableCredential[]}
|
|
153
|
+
* @param options.appUrl {string} - The request's `app.appUrl` in serialized
|
|
154
|
+
* form.
|
|
155
|
+
* @param options.origin {string} - The attested requesting origin.
|
|
156
|
+
* @returns {Promise<IVerifiableCredential | undefined>}
|
|
157
|
+
*/
|
|
158
|
+
export declare function findAppKeyCredential({ credentials, appUrl, origin }: {
|
|
159
|
+
credentials: IVerifiableCredential[];
|
|
160
|
+
appUrl: string;
|
|
161
|
+
origin: string;
|
|
162
|
+
}): Promise<IVerifiableCredential | undefined>;
|
|
163
|
+
/**
|
|
164
|
+
* Assembles and signs an app-key credential for a seed the caller supplies:
|
|
165
|
+
* the fixed two-entry type array, the hosted App Connect context URL, issuer
|
|
166
|
+
* and subject both the seed-derived DID, and the `seed` / `appUrl` / `origin`
|
|
167
|
+
* claims. `vc.issue` auto-fills `issuanceDate` in the canonical UTC form the
|
|
168
|
+
* ranking expects. Shared by the fresh mint and the legacy re-issue, and
|
|
169
|
+
* exported for an application's own self-issue path (dev-grant provisioning,
|
|
170
|
+
* tests), so the credential's shape is maintained in one place.
|
|
171
|
+
*
|
|
172
|
+
* @param options {object}
|
|
173
|
+
* @param options.seedBytes {Uint8Array} - The 32-byte master seed; the
|
|
174
|
+
* derived did:key is both issuer and subject.
|
|
175
|
+
* @param options.appName {string} - Shown on the credential (`name`, and the
|
|
176
|
+
* default `description`).
|
|
177
|
+
* @param options.appUrl {string} - The app's canonical URL, already in
|
|
178
|
+
* serialized form.
|
|
179
|
+
* @param options.origin {string} - The attested requesting origin.
|
|
180
|
+
* @param [options.description] {string} - Overrides the default consent
|
|
181
|
+
* sentence (the legacy re-issue carries the old credential's forward).
|
|
182
|
+
* @param [options.documentLoader] {IDocumentLoader} - JSON-LD loader; defaults
|
|
183
|
+
* to the shared security loader.
|
|
184
|
+
* @returns {Promise<{ credential: IVerifiableCredential; subjectDid: string }>}
|
|
185
|
+
*/
|
|
186
|
+
export declare function issueAppKeyCredential({ seedBytes, appName, appUrl, origin, description, documentLoader: loader }: {
|
|
187
|
+
seedBytes: Uint8Array;
|
|
188
|
+
appName: string;
|
|
189
|
+
appUrl: string;
|
|
190
|
+
origin: string;
|
|
191
|
+
description?: string;
|
|
192
|
+
documentLoader?: IDocumentLoader;
|
|
193
|
+
}): Promise<{
|
|
194
|
+
credential: IVerifiableCredential;
|
|
195
|
+
subjectDid: string;
|
|
196
|
+
}>;
|
|
197
|
+
/**
|
|
198
|
+
* Mints a fresh app-key credential for an app + origin: generates a 32-byte
|
|
199
|
+
* seed, derives the seed's did:key, and self-issues the credential (issuer ==
|
|
200
|
+
* subject == the seed-derived DID) with the `credentialSubject.appUrl` claim
|
|
201
|
+
* set from the validated request value. Does NOT store the result -- the
|
|
202
|
+
* caller stores it before delegating, so a failed delegation is found as
|
|
203
|
+
* "returning" on the next attempt rather than minting a second identity.
|
|
204
|
+
*
|
|
205
|
+
* @param options {object}
|
|
206
|
+
* @param options.app {IAppConnectApp} - The validated app identity; its
|
|
207
|
+
* `appUrl` must already be in serialized form (`appConnectRequestOf`
|
|
208
|
+
* guarantees this).
|
|
209
|
+
* @param options.origin {string} - The attested requesting origin, never a
|
|
210
|
+
* value taken from the request body.
|
|
211
|
+
* @returns {Promise<{ credential: IVerifiableCredential; subjectDid: string }>}
|
|
212
|
+
*/
|
|
213
|
+
export declare function mintAppKeyCredential({ app, origin }: {
|
|
214
|
+
app: IAppConnectApp;
|
|
215
|
+
origin: string;
|
|
216
|
+
}): Promise<{
|
|
217
|
+
credential: IVerifiableCredential;
|
|
218
|
+
subjectDid: string;
|
|
219
|
+
}>;
|
|
220
|
+
/**
|
|
221
|
+
* The latest legacy app-key credential for an origin, or undefined. A legacy
|
|
222
|
+
* credential predates the `appUrl` model: it carries the marker and a
|
|
223
|
+
* per-app third type entry, but no `credentialSubject.appUrl` claim. Its
|
|
224
|
+
* identity was scoped to (origin, `credentialType`), and the request no
|
|
225
|
+
* longer carries a `credentialType` to select on, so the mapping is
|
|
226
|
+
* recoverable only when it is unambiguous: when the binding legacy candidates
|
|
227
|
+
* for the origin all name one subject DID. Two distinct legacy identities on
|
|
228
|
+
* one origin yield undefined rather than a guess -- re-issuing the wrong one
|
|
229
|
+
* would hand one application another's identity, which is worse than the
|
|
230
|
+
* caller treating the connect as a first run.
|
|
231
|
+
*
|
|
232
|
+
* @param options {object}
|
|
233
|
+
* @param options.credentials {IVerifiableCredential[]}
|
|
234
|
+
* @param options.origin {string} - The attested requesting origin.
|
|
235
|
+
* @returns {Promise<IVerifiableCredential | undefined>}
|
|
236
|
+
*/
|
|
237
|
+
export declare function findLegacyAppKeyCredential({ credentials, origin }: {
|
|
238
|
+
credentials: IVerifiableCredential[];
|
|
239
|
+
origin: string;
|
|
240
|
+
}): Promise<IVerifiableCredential | undefined>;
|
|
241
|
+
/**
|
|
242
|
+
* Re-issues a legacy app-key credential in place under the `appUrl` model:
|
|
243
|
+
* the same seed (so the same derived DID -- the app's identity and its
|
|
244
|
+
* encrypted-data access are preserved), the fixed two-entry type array, the
|
|
245
|
+
* hosted App Connect context URL, and the `credentialSubject.appUrl` claim set
|
|
246
|
+
* from the validated request value. A fresh mint would roll the seed and orphan
|
|
247
|
+
* the identity, and must never be the migration path. The fresh
|
|
248
|
+
* `issuanceDate` ranks the re-issued credential ahead of the legacy one, so
|
|
249
|
+
* subsequent connects match it directly.
|
|
250
|
+
*
|
|
251
|
+
* Does NOT store the result; the caller stores it through the mint door
|
|
252
|
+
* (it satisfies {@link assertMintedAppKey}) and may retire the legacy record.
|
|
253
|
+
*
|
|
254
|
+
* @param options {object}
|
|
255
|
+
* @param options.credential {IVerifiableCredential} - The legacy credential;
|
|
256
|
+
* it must bind per {@link appKeySeedBindsSubject} and be bound to `origin`,
|
|
257
|
+
* else this throws {@link AppKeyMintInvariantError}.
|
|
258
|
+
* @param options.app {IAppConnectApp} - The validated app identity; its
|
|
259
|
+
* `appUrl` must already be in serialized form.
|
|
260
|
+
* @param options.origin {string} - The attested requesting origin.
|
|
261
|
+
* @returns {Promise<{ credential: IVerifiableCredential; subjectDid: string }>}
|
|
262
|
+
*/
|
|
263
|
+
export declare function reissueAppKeyCredential({ credential, app, origin }: {
|
|
264
|
+
credential: IVerifiableCredential;
|
|
265
|
+
app: IAppConnectApp;
|
|
266
|
+
origin: string;
|
|
267
|
+
}): Promise<{
|
|
268
|
+
credential: IVerifiableCredential;
|
|
269
|
+
subjectDid: string;
|
|
270
|
+
}>;
|
|
271
|
+
/**
|
|
272
|
+
* The subject DID (`credentialSubject.id`) of an app-key credential, or
|
|
273
|
+
* undefined. For a valid app-key credential this equals the issuer.
|
|
274
|
+
*
|
|
275
|
+
* @param credential {IVerifiableCredential}
|
|
276
|
+
* @returns {string | undefined}
|
|
277
|
+
*/
|
|
278
|
+
export declare function appKeySubjectDid(credential: IVerifiableCredential): string | undefined;
|
|
279
|
+
/**
|
|
280
|
+
* The origin (`credentialSubject.origin`) an app-key credential is bound to,
|
|
281
|
+
* when present.
|
|
282
|
+
*
|
|
283
|
+
* @param credential {IVerifiableCredential}
|
|
284
|
+
* @returns {string | undefined}
|
|
285
|
+
*/
|
|
286
|
+
export declare function appKeyOrigin(credential: IVerifiableCredential): string | undefined;
|
|
287
|
+
/**
|
|
288
|
+
* The application URL (`credentialSubject.appUrl`) an app-key credential is
|
|
289
|
+
* scoped to, when present. Absent on a legacy (pre-`appUrl`) credential.
|
|
290
|
+
*
|
|
291
|
+
* @param credential {IVerifiableCredential}
|
|
292
|
+
* @returns {string | undefined}
|
|
293
|
+
*/
|
|
294
|
+
export declare function appKeyAppUrl(credential: IVerifiableCredential): string | undefined;
|
|
295
|
+
//# sourceMappingURL=appKey.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"appKey.d.ts","sourceRoot":"","sources":["../src/appKey.ts"],"names":[],"mappings":"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"}
|