@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 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/core
3
+ # @learncard/didkit-plugin
4
4
 
5
- [![npm version](https://img.shields.io/npm/v/@learncard/core)](https://www.npmjs.com/package/@learncard/core)
6
- [![npm downloads](https://img.shields.io/npm/dw/@learncard/core)](https://www.npmjs.com/package/@learncard/core)
7
- [![vulnerabilities](https://img.shields.io/snyk/vulnerabilities/npm/@learncard/core)](https://www.npmjs.com/package/@learncard/core)
5
+ [![npm version](https://img.shields.io/npm/v/@learncard/didkit-plugin)](https://www.npmjs.com/package/@learncard/didkit-plugin)
6
+ [![npm downloads](https://img.shields.io/npm/dw/@learncard/didkit-plugin)](https://www.npmjs.com/package/@learncard/didkit-plugin)
8
7
 
9
- The LearnCard Core is a pluggable, open-source, universal digital wallet to enable any individual or organization to seamlessly **issue, earn, store, share, and spend currency and credentials** built for the future of education and work.
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/core
18
+ bun add @learncard/init @learncard/didkit-plugin
20
19
  ```
21
20
 
22
21
  ## Usage
23
22
 
24
- ### Instantiation
23
+ This package exports `getDidKitPlugin`.
25
24
 
26
- Instantiate a wallet using `initLearnCard`. This method accepts a unique identifier string that is
27
- up to 64 characters long. If it is less than 64 characters, `initLearnCard` will pad the start of
28
- the string with 0's until it is 64 characters long.
25
+ ```ts
26
+ import { initLearnCard } from '@learncard/init';
27
+ import { getDidKitPlugin } from '@learncard/didkit-plugin';
29
28
 
30
- ```js
31
- import { initLearnCard } from '@learncard/core';
29
+ const learnCard = await initLearnCard({ custom: true });
32
30
 
33
- const wallet = await initLearnCard({ seed: 'a'.repeat(64) });
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
- ### Issuing/Verifying Credentials and Presentations
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
- #### Issue a credential
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,2 @@
1
+ export {};
2
+ //# sourceMappingURL=didWebDocumentCache.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"didWebDocumentCache.test.d.ts","sourceRoot":"","sources":["../src/didWebDocumentCache.test.ts"],"names":[],"mappings":""}