@learncard/didkit-plugin 1.10.9 → 1.10.11
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/README.md +14 -114
- package/dist/didWebDocumentCache.d.ts +80 -0
- package/dist/didWebDocumentCache.d.ts.map +1 -0
- package/dist/didWebDocumentCache.test.d.ts +2 -0
- package/dist/didWebDocumentCache.test.d.ts.map +1 -0
- package/dist/didkit-plugin.cjs.development.cjs +369 -9
- package/dist/didkit-plugin.cjs.development.cjs.map +4 -4
- package/dist/didkit-plugin.cjs.production.min.cjs +2 -2
- package/dist/didkit-plugin.cjs.production.min.cjs.map +4 -4
- package/dist/didkit-plugin.esm.js +369 -9
- package/dist/didkit-plugin.esm.js.map +4 -4
- package/dist/helpers.d.ts +10 -1
- package/dist/helpers.d.ts.map +1 -1
- package/dist/index.d.cts +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/plugin.d.ts.map +1 -1
- package/package.json +4 -4
- package/src/didWebDocumentCache.test.ts +732 -0
- package/src/didWebDocumentCache.ts +573 -0
- package/src/helpers.ts +16 -8
- package/src/index.ts +12 -0
- package/src/plugin.ts +22 -4
package/README.md
CHANGED
|
@@ -1,12 +1,11 @@
|
|
|
1
1
|
[<img src="https://user-images.githubusercontent.com/2185016/190510561-294db809-09fd-4771-9749-6c0e0f4144fd.png" width="215"/>](https://learncard.com)
|
|
2
2
|
|
|
3
|
-
# @learncard/
|
|
3
|
+
# @learncard/didkit-plugin
|
|
4
4
|
|
|
5
|
-
[](https://www.npmjs.com/package/@learncard/core)
|
|
5
|
+
[](https://www.npmjs.com/package/@learncard/didkit-plugin)
|
|
6
|
+
[](https://www.npmjs.com/package/@learncard/didkit-plugin)
|
|
8
7
|
|
|
9
|
-
|
|
8
|
+
Wraps the [DIDKit](https://github.com/spruceid/didkit) WASM build to sign and verify credentials and presentations and resolve DIDs.
|
|
10
9
|
|
|
11
10
|
## Documentation
|
|
12
11
|
|
|
@@ -16,63 +15,26 @@ https://docs.learncard.com
|
|
|
16
15
|
## Install
|
|
17
16
|
|
|
18
17
|
```bash
|
|
19
|
-
bun add @learncard/
|
|
18
|
+
bun add @learncard/init @learncard/didkit-plugin
|
|
20
19
|
```
|
|
21
20
|
|
|
22
21
|
## Usage
|
|
23
22
|
|
|
24
|
-
|
|
23
|
+
This package exports `getDidKitPlugin`.
|
|
25
24
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
25
|
+
```ts
|
|
26
|
+
import { initLearnCard } from '@learncard/init';
|
|
27
|
+
import { getDidKitPlugin } from '@learncard/didkit-plugin';
|
|
29
28
|
|
|
30
|
-
|
|
31
|
-
import { initLearnCard } from '@learncard/core';
|
|
29
|
+
const learnCard = await initLearnCard({ custom: true });
|
|
32
30
|
|
|
33
|
-
|
|
31
|
+
// Optional args: a custom WASM URL/module, and allowRemoteContexts (default false)
|
|
32
|
+
const didkitLearnCard = await learnCard.addPlugin(await getDidKitPlugin());
|
|
34
33
|
```
|
|
35
34
|
|
|
36
|
-
|
|
35
|
+
On Node, prefer [`@learncard/didkit-plugin-node`](../didkit-plugin-node) (or `initLearnCard({ seed, didkit: 'node' })`). Seed-based `initLearnCard` wallets already include a DIDKit plugin.
|
|
37
36
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
```js
|
|
41
|
-
// Grab a test VC, or create your own!
|
|
42
|
-
const unsignedVc = await wallet.invoke.getTestVc();
|
|
43
|
-
|
|
44
|
-
const vc = await wallet.invoke.issueCredential(unsignedVc);
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
#### Verify a credential
|
|
48
|
-
|
|
49
|
-
```js
|
|
50
|
-
const result = await wallet.invoke.verifyCredential(vc, {}, true);
|
|
51
|
-
|
|
52
|
-
if (result.warnings.length > 0) console.error('Verification warnings:', result.warnings);
|
|
53
|
-
|
|
54
|
-
if (result.errors.length > 0) console.error('This credential is not valid!', result.errors);
|
|
55
|
-
else console.log('This credential is valid!');
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
#### Issue a presentation
|
|
59
|
-
|
|
60
|
-
```js
|
|
61
|
-
const vp = await wallet.invoke.issuePresentation(vc);
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
#### Verify a presentation
|
|
65
|
-
|
|
66
|
-
```js
|
|
67
|
-
const result = await wallet.invoke.verifyPresentation(vp);
|
|
68
|
-
|
|
69
|
-
if (result.warnings.length > 0) console.error('Verification warnings:', result.warnings);
|
|
70
|
-
|
|
71
|
-
if (result.errors.length > 0) console.error('This presentation is not valid!', result.errors);
|
|
72
|
-
else console.log('This presentation is valid!');
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
#### Final P-256 Data Integrity proofs
|
|
37
|
+
### Final P-256 Data Integrity proofs
|
|
76
38
|
|
|
77
39
|
The native and WASM engines support explicit `ecdsa-rdfc-2019` proofs with P-256/ES256
|
|
78
40
|
keys. Verification accepts equivalent P-256 JWKs and validated compressed P-256
|
|
@@ -95,64 +57,6 @@ document. Signing-only P-256 `did:key` holders can use generic claim links, but
|
|
|
95
57
|
claims; an unsupported delivery key leaves the pending credential and challenge available
|
|
96
58
|
for retry.
|
|
97
59
|
|
|
98
|
-
### Storing/Retrieving/Sending Credentials
|
|
99
|
-
|
|
100
|
-
#### Ceramic/IDX
|
|
101
|
-
|
|
102
|
-
To maintain co-ownership of credentials, it is best to store credentials in a public place, and then
|
|
103
|
-
store references to that public place. While this is not the only way to store credentials (and is
|
|
104
|
-
also definitely not a silver bullet! E.g. credentials containing private data), it is the opinion of
|
|
105
|
-
this library that it should be used by default. As a result, instantiating a wallet, will
|
|
106
|
-
automatically connect you to WeLibrary's ceramic node, and allow you to publish and retrieve
|
|
107
|
-
credentials there using IDX.
|
|
108
|
-
|
|
109
|
-
#### Publish Credential
|
|
110
|
-
|
|
111
|
-
After signing a VC, you may choose to publish that credential to Ceramic. Doing so will return a
|
|
112
|
-
stream ID, which you may share to the recipient. That stream ID can then be used to resolve the
|
|
113
|
-
issued credential. This means both the issuer and recipient may store the _stream ID_ instead of the
|
|
114
|
-
credential itself.
|
|
115
|
-
|
|
116
|
-
```js
|
|
117
|
-
const uri = await wallet.store.Ceramic.upload(vc);
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
#### Reading From Ceramic
|
|
121
|
-
|
|
122
|
-
To resolve a VC from a stream ID, simply call the `readFromCeramic` method:
|
|
123
|
-
|
|
124
|
-
```js
|
|
125
|
-
const vcFromCeramic = await wallet.read.get(uri);
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
#### Adding a Credential to a Wallet
|
|
129
|
-
|
|
130
|
-
After receiving a streamID, you can _persist_ that streamID by calling `addCredential`, and giving
|
|
131
|
-
the credential a bespoke title
|
|
132
|
-
|
|
133
|
-
```js
|
|
134
|
-
await wallet.index.IDX.add({ uri, id: 'Test VC' });
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
This will add the streamId, which can be used to resolve the verifiable credential to IDX using the
|
|
138
|
-
wallet's secret key. You can think of this as acting like the wallet's personal storage.
|
|
139
|
-
|
|
140
|
-
#### Getting a credential from the Wallet
|
|
141
|
-
|
|
142
|
-
After calling `addCredential`, you can use the bespoke title to retrieve that credential at any time
|
|
143
|
-
|
|
144
|
-
```js
|
|
145
|
-
const record = (await wallet.index.all.get()).find(record => record.id === 'Test VC');
|
|
146
|
-
const vcFromIdx = await wallet.read.get(record.uri);
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
Alternatively, you can get an array of _all_ credentials you have added using `getCredentials`
|
|
150
|
-
|
|
151
|
-
```js
|
|
152
|
-
const uris = (await wallet.index.all.get()).map(record => record.uri);
|
|
153
|
-
const vcs = await Promise.all(uris.map(async uri => wallet.read.get(uri)));
|
|
154
|
-
```
|
|
155
|
-
|
|
156
60
|
## Contributing
|
|
157
61
|
|
|
158
62
|
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
|
|
@@ -171,10 +75,6 @@ separate WASM graph. The committed WASM/glue pair and hosted URL are retained un
|
|
|
171
75
|
the normal source-update workflow builds, tests, and publishes a matching artifact
|
|
172
76
|
pair and updates the URL and bridge integrity pin.
|
|
173
77
|
|
|
174
|
-
## Who is Learning Economy Foundation?
|
|
175
|
-
|
|
176
|
-
**[Learning Economy Foundation (LEF)](https://www.learningeconomy.io)** is a 501(c)(3) non-profit organization leveraging global standards and web3 protocols to bring quality skills and equal opportunity to every human on earth, and address the persistent inequities that exist around the globe in education and employment. We help you build the future of education and work with:
|
|
177
|
-
|
|
178
78
|
## License
|
|
179
79
|
|
|
180
80
|
MIT © [Learning Economy Foundation](https://github.com/Learning-Economy-Foundation)
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Browser/Node fetch cache for did:web documents (`…/did.json`).
|
|
3
|
+
*
|
|
4
|
+
* DIDKit WASM resolves and verifies through `globalThis.fetch` with no in-flight
|
|
5
|
+
* dedupe (ssi did-web drops its TimedCache lock before the HTTP GET). Opening one
|
|
6
|
+
* credential can therefore stampede the same issuer document dozens of times.
|
|
7
|
+
*
|
|
8
|
+
* This module wraps `fetch` once so callers with *equivalent* resolver requests share:
|
|
9
|
+
* - in-flight promise dedupe keyed by normalized request semantics
|
|
10
|
+
* - a short TTL success cache (failures are never stored; Cache-Control honored)
|
|
11
|
+
*
|
|
12
|
+
* Equivalence follows platform `new Request(input, init)` rules (init.headers
|
|
13
|
+
* *replaces* Request headers, it does not merge). Semantics include method, URL,
|
|
14
|
+
* headers (so WASM's `Accept: application/json` is keyed, not bypassed), credentials,
|
|
15
|
+
* mode, cache, redirect, and referrer policy. Non-cacheable traffic (non-GET,
|
|
16
|
+
* non-did.json, integrity, no-store, etc.) is decided with cheap peeks and the
|
|
17
|
+
* original input/init are forwarded untouched — never `new Request` first, so
|
|
18
|
+
* body-bearing POSTs are not consumed. Only GET did.json paths normalize.
|
|
19
|
+
* Rebuilt Responses keep `url` (DIDKit parses it). Clear/invalidate bump a
|
|
20
|
+
* generation so stale in-flight work cannot join or repopulate after the body
|
|
21
|
+
* finishes streaming.
|
|
22
|
+
*/
|
|
23
|
+
export declare const DEFAULT_DID_WEB_DOCUMENT_TTL_MS = 10000;
|
|
24
|
+
/**
|
|
25
|
+
* LearnCard App wallet-boot TTL for did:web document GETs. Longer than
|
|
26
|
+
* {@link DEFAULT_DID_WEB_DOCUMENT_TTL_MS} so a credential detail modal that keeps
|
|
27
|
+
* re-resolving does not refetch every 10s (LC-2384: 4 identical demo-boi GETs at
|
|
28
|
+
* ~10s gaps). Apply only via {@link installWalletDidWebDocumentFetchCache} at app
|
|
29
|
+
* boot — never from {@link getDidKitPlugin}. Change this one constant to tune
|
|
30
|
+
* wallet lifetime; the public SDK factory keeps {@link DEFAULT_DID_WEB_DOCUMENT_TTL_MS}.
|
|
31
|
+
*/
|
|
32
|
+
export declare const WALLET_DID_WEB_DOCUMENT_TTL_MS = 60000;
|
|
33
|
+
export declare const DEFAULT_DID_WEB_DOCUMENT_CACHE_MAX_ENTRIES = 64;
|
|
34
|
+
export type DidWebDocumentCacheStats = {
|
|
35
|
+
installed: boolean;
|
|
36
|
+
ttlMs: number;
|
|
37
|
+
maxEntries: number;
|
|
38
|
+
successEntries: number;
|
|
39
|
+
inflightEntries: number;
|
|
40
|
+
cacheGeneration: number;
|
|
41
|
+
};
|
|
42
|
+
export type InstallDidWebDocumentFetchCacheOptions = {
|
|
43
|
+
/** Success-entry lifetime in ms. Defaults to {@link DEFAULT_DID_WEB_DOCUMENT_TTL_MS}. */
|
|
44
|
+
ttlMs?: number;
|
|
45
|
+
/** Max success entries (LRU). Defaults to {@link DEFAULT_DID_WEB_DOCUMENT_CACHE_MAX_ENTRIES}. */
|
|
46
|
+
maxEntries?: number;
|
|
47
|
+
/** Replace a previous install (tests). */
|
|
48
|
+
force?: boolean;
|
|
49
|
+
};
|
|
50
|
+
/** True for did:web document URLs (`/did.json`), including `.well-known/did.json`. */
|
|
51
|
+
export declare const isDidWebDocumentUrl: (url: string) => boolean;
|
|
52
|
+
/**
|
|
53
|
+
* Mirrors ssi `did_web_url`, then normalizes via the URL constructor (host case,
|
|
54
|
+
* default ports) so invalidate keys match fetch keys.
|
|
55
|
+
*/
|
|
56
|
+
export declare const didWebToDocumentUrl: (did: string) => string | undefined;
|
|
57
|
+
/**
|
|
58
|
+
* Install (or no-op if already installed) the process-wide did:web document fetch cache.
|
|
59
|
+
*
|
|
60
|
+
* TTL / maxEntries semantics:
|
|
61
|
+
* - Omitting `ttlMs` / `maxEntries` never clobbers a value already configured (so a
|
|
62
|
+
* generic {@link getDidKitPlugin} install cannot raise a shorter preinstalled TTL).
|
|
63
|
+
* - Passing `ttlMs` / `maxEntries` is an intentional opt-in and updates the module
|
|
64
|
+
* globals even when the wrapper is already installed (no `force` required).
|
|
65
|
+
* - First install with no options uses {@link DEFAULT_DID_WEB_DOCUMENT_TTL_MS}.
|
|
66
|
+
*/
|
|
67
|
+
export declare const installDidWebDocumentFetchCache: (options?: InstallDidWebDocumentFetchCacheOptions) => void;
|
|
68
|
+
/**
|
|
69
|
+
* LearnCard App / wallet boot opt-in: set did:web document TTL to
|
|
70
|
+
* {@link WALLET_DID_WEB_DOCUMENT_TTL_MS} (60s). Call before `initLearnCard` so the
|
|
71
|
+
* subsequent generic getDidKitPlugin install cannot clobber it. Not for generic
|
|
72
|
+
* SDK consumers (emptyLearnCard, scripts, etc.).
|
|
73
|
+
*/
|
|
74
|
+
export declare const installWalletDidWebDocumentFetchCache: () => void;
|
|
75
|
+
export declare const clearDidWebDocumentFetchCache: () => void;
|
|
76
|
+
export declare const invalidateDidWebDocument: (didOrUrl: string) => void;
|
|
77
|
+
export declare const getDidWebDocumentFetchCacheStats: () => DidWebDocumentCacheStats;
|
|
78
|
+
/** Test helper: restore `fetch` and empty caches. */
|
|
79
|
+
export declare const resetDidWebDocumentFetchCacheForTests: () => void;
|
|
80
|
+
//# sourceMappingURL=didWebDocumentCache.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"didWebDocumentCache.d.ts","sourceRoot":"","sources":["../src/didWebDocumentCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,eAAO,MAAM,+BAA+B,QAAS,CAAC;AACtD;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,QAAS,CAAC;AACrD,eAAO,MAAM,0CAA0C,KAAK,CAAC;AA+C7D,MAAM,MAAM,wBAAwB,GAAG;IACnC,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,sCAAsC,GAAG;IACjD,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAsFF,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,KAAG,OAOjD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAgB1D,CAAC;AAgQF;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,GACxC,UAAS,sCAA2C,KACrD,IAuBF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC,QAAO,IAExD,CAAC;AAEF,eAAO,MAAM,6BAA6B,QAAO,IAKhD,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAI,UAAU,MAAM,KAAG,IA0B3D,CAAC;AAEF,eAAO,MAAM,gCAAgC,QAAO,wBAOlD,CAAC;AAEH,qDAAqD;AACrD,eAAO,MAAM,qCAAqC,QAAO,IAYxD,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"didWebDocumentCache.test.d.ts","sourceRoot":"","sources":["../src/didWebDocumentCache.test.ts"],"names":[],"mappings":""}
|