javascript-solid-server 0.0.188 → 0.0.190

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.
@@ -0,0 +1,259 @@
1
+ /**
2
+ * Unit tests for owner-key provisioning (Phase 1 of #437).
3
+ */
4
+
5
+ import { describe, it } from 'node:test';
6
+ import assert from 'node:assert';
7
+ import { schnorr, secp256k1 } from '@noble/curves/secp256k1';
8
+ import {
9
+ generateOwnerKeypair,
10
+ publicKeyMultibase,
11
+ secretKeyMultibase,
12
+ buildOwnerKeyDocument,
13
+ provisionOwnerKey,
14
+ assertProvisionKeysCompatible
15
+ } from '../src/keys/provision.js';
16
+ import { decodeFFormSecp256k1 } from '../src/auth/nostr-keys.js';
17
+
18
+ describe('generateOwnerKeypair', () => {
19
+ it('produces a 32-byte x-only pubkey and a 32-byte secret', () => {
20
+ const { publicHex, secretHex } = generateOwnerKeypair();
21
+ assert.match(publicHex, /^[0-9a-f]{64}$/);
22
+ assert.match(secretHex, /^[0-9a-f]{64}$/);
23
+ });
24
+
25
+ it('produces a working Schnorr keypair (sign + verify)', () => {
26
+ const { publicHex, secretHex } = generateOwnerKeypair();
27
+ const message = new TextEncoder().encode('jss provision-keys roundtrip');
28
+ const sig = schnorr.sign(message, hexToBytes(secretHex));
29
+ assert.strictEqual(
30
+ schnorr.verify(sig, message, hexToBytes(publicHex)),
31
+ true,
32
+ 'signature must verify under the generated pubkey'
33
+ );
34
+ });
35
+
36
+ it('produces a different keypair on every call', () => {
37
+ const a = generateOwnerKeypair();
38
+ const b = generateOwnerKeypair();
39
+ assert.notStrictEqual(a.publicHex, b.publicHex);
40
+ assert.notStrictEqual(a.secretHex, b.secretHex);
41
+ });
42
+
43
+ it('always normalizes the secret so G*secret has even y (BIP-340)', () => {
44
+ // Without normalization, ECDSA signatures made with the raw secret
45
+ // would verify against the natural y of G*secret — even/odd ~50/50
46
+ // — while the JWK we publish in the WebID profile is derived from
47
+ // the even-y x-only Schnorr pubkey. Phase 2's LWS-CID round-trip
48
+ // would flake non-deterministically. Generate many keypairs and
49
+ // assert every secret's natural public point is even-y.
50
+ for (let i = 0; i < 64; i++) {
51
+ const { secretHex } = generateOwnerKeypair();
52
+ const compressed = secp256k1.getPublicKey(hexToBytes(secretHex), /*compressed=*/true);
53
+ assert.strictEqual(compressed[0], 0x02,
54
+ `secret #${i} produced odd-y point; normalization is broken`);
55
+ }
56
+ });
57
+ });
58
+
59
+ describe('publicKeyMultibase / secretKeyMultibase', () => {
60
+ // Fixed test vectors so the encoding format is pinned (any change to
61
+ // multicodec/multibase would shift these values and fail the assertion).
62
+ const publicHex = '87a1c6f0e9b3d2456789abcdef0123456789abcdef0123456789abcdef012345';
63
+ const secretHex = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
64
+
65
+ it('encodes a public key as f + e701 + 02 + 64-hex-pubkey', () => {
66
+ const mb = publicKeyMultibase(publicHex);
67
+ // f (multibase) + e701 (multicodec varint for secp256k1-pub) +
68
+ // 02 (BIP-340 even-y parity) + 64-char pubkey hex
69
+ assert.strictEqual(mb, 'fe70102' + publicHex);
70
+ });
71
+
72
+ it('encodes a secret key as f + 8126 + 64-hex-secret', () => {
73
+ const mb = secretKeyMultibase(secretHex);
74
+ // f (multibase) + 8126 (multicodec varint for secp256k1-priv) +
75
+ // 64-char secret hex (no parity byte — secret IS the scalar)
76
+ assert.strictEqual(mb, 'f8126' + secretHex);
77
+ });
78
+
79
+ it('round-trips through src/auth/nostr-keys decoder for the public side', () => {
80
+ // The Multikey value we write must be readable by jss's existing
81
+ // f-form decoder (used by the did:nostr verifier). This pins the
82
+ // shape so a future change to either side fails loud.
83
+ const mb = publicKeyMultibase(publicHex);
84
+ const decoded = decodeFFormSecp256k1(mb);
85
+ assert.strictEqual(decoded, publicHex);
86
+ });
87
+
88
+ it('rejects non-hex / wrong-length inputs', () => {
89
+ assert.throws(() => publicKeyMultibase('not-hex'), /64-char lower-hex/);
90
+ assert.throws(() => publicKeyMultibase(publicHex.slice(0, 63)), /64-char/);
91
+ assert.throws(() => secretKeyMultibase(''), /64-char/);
92
+ assert.throws(() => secretKeyMultibase(publicHex.toUpperCase()), /64-char lower-hex/);
93
+ });
94
+ });
95
+
96
+ describe('buildOwnerKeyDocument', () => {
97
+ const args = {
98
+ controllerWebId: 'https://alice.example/profile/card.jsonld#me',
99
+ publicHex: '87a1c6f0e9b3d2456789abcdef0123456789abcdef0123456789abcdef012345',
100
+ secretHex: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
101
+ };
102
+
103
+ it('emits a W3C CID v1.0 Multikey JSON-LD document', () => {
104
+ const doc = buildOwnerKeyDocument(args);
105
+ assert.strictEqual(doc['@context'], 'https://www.w3.org/ns/cid/v1');
106
+ assert.strictEqual(doc.type, 'Multikey');
107
+ });
108
+
109
+ it('defaults the controller to did:nostr:<hex> in Phase 2', () => {
110
+ // Phase 2 of #437 (#443) flipped the default controller to
111
+ // `did:nostr:<publicHex>` now that jss's resolver round-trips
112
+ // it. Phase 1 had used the WebID; the swap was anticipated in
113
+ // the Phase 1 design log and ships here.
114
+ const doc = buildOwnerKeyDocument({
115
+ publicHex: args.publicHex,
116
+ secretHex: args.secretHex
117
+ });
118
+ assert.strictEqual(doc.controller, `did:nostr:${args.publicHex}`);
119
+ });
120
+
121
+ it('accepts an explicit controller override (e.g. WebID, urn:, custom DID method)', () => {
122
+ // The forward-looking knob — operators or future callers that
123
+ // want to pin the document's controller to something other than
124
+ // did:nostr (a WebID, a urn:, a custom DID method) pass
125
+ // `controller` explicitly. Defaults still fire when omitted.
126
+ const doc = buildOwnerKeyDocument({
127
+ publicHex: args.publicHex,
128
+ secretHex: args.secretHex,
129
+ controller: args.controllerWebId
130
+ });
131
+ assert.strictEqual(doc.controller, args.controllerWebId);
132
+ assert.doesNotMatch(doc.controller, /^did:nostr:/);
133
+ });
134
+
135
+ it('embeds both the public and secret Multikey values', () => {
136
+ const doc = buildOwnerKeyDocument(args);
137
+ assert.strictEqual(doc.publicKeyMultibase, publicKeyMultibase(args.publicHex));
138
+ assert.strictEqual(doc.secretKeyMultibase, secretKeyMultibase(args.secretHex));
139
+ });
140
+
141
+ it('does NOT include a `nostr` extension block (npub etc.)', () => {
142
+ // Resolution #2 of #437: bech32 npub is derivable from the public
143
+ // multibase value in any Nostr-aware tool. Including it would
144
+ // double the secret-on-disk surface for log/error/dump leaks
145
+ // (the symmetric `nsec` field was originally proposed alongside).
146
+ const doc = buildOwnerKeyDocument(args);
147
+ assert.strictEqual(doc.nostr, undefined);
148
+ });
149
+
150
+ it('rejects an explicit empty controller override', () => {
151
+ // The default did:nostr controller is computed from publicHex, so
152
+ // missing inputs are caught upstream (see publicKeyMultibase
153
+ // validation tests). When a caller *explicitly* passes an empty
154
+ // string, that's a misconfiguration we surface loudly.
155
+ assert.throws(
156
+ () => buildOwnerKeyDocument({
157
+ publicHex: args.publicHex,
158
+ secretHex: args.secretHex,
159
+ controller: ''
160
+ }),
161
+ /controller required/
162
+ );
163
+ });
164
+ });
165
+
166
+ describe('provisionOwnerKey', () => {
167
+ const webId = 'https://alice.example/profile/card.jsonld#me';
168
+
169
+ it('returns the document together with raw key material for CLI display', () => {
170
+ const out = provisionOwnerKey({ webId });
171
+ assert.match(out.publicHex, /^[0-9a-f]{64}$/);
172
+ assert.match(out.secretHex, /^[0-9a-f]{64}$/);
173
+ assert.strictEqual(out.publicMultibase, out.document.publicKeyMultibase);
174
+ assert.strictEqual(out.document.type, 'Multikey');
175
+ // Phase 2 of #437 (#443): controller defaults to did:nostr:<hex>.
176
+ assert.strictEqual(out.document.controller, `did:nostr:${out.publicHex}`);
177
+ assert.strictEqual(out.didNostr, `did:nostr:${out.publicHex}`);
178
+ });
179
+
180
+ it('returns a verificationMethod entry suitable for the WebID profile', () => {
181
+ // Phase 2 wires the public side into the profile's
182
+ // verificationMethod array so the existing LWS-CID verifier
183
+ // (src/auth/lws-cid.js) can authenticate JWTs signed with the
184
+ // matching secret. Both Multikey and JWK forms ship — Multikey
185
+ // for CID v1.0 conformance, JWK for LWS-CID compat.
186
+ const out = provisionOwnerKey({ webId });
187
+ assert.strictEqual(out.vm['@type'], 'Multikey');
188
+ assert.strictEqual(out.vm.controller, webId);
189
+ assert.strictEqual(out.vm['@id'], 'https://alice.example/profile/card.jsonld#owner-key');
190
+ assert.strictEqual(out.vm.publicKeyMultibase, out.publicMultibase);
191
+ assert.strictEqual(out.vm.publicKeyJwk.kty, 'EC');
192
+ assert.strictEqual(out.vm.publicKeyJwk.crv, 'secp256k1');
193
+ assert.match(out.vm.publicKeyJwk.x, /^[A-Za-z0-9_-]+$/);
194
+ assert.match(out.vm.publicKeyJwk.y, /^[A-Za-z0-9_-]+$/);
195
+ });
196
+
197
+ it('honours an explicit documentController override', () => {
198
+ // The legacy controllerWebId alias was removed in #443 review —
199
+ // the canonical way to pin the document controller is
200
+ // documentController.
201
+ const out = provisionOwnerKey({ webId, documentController: webId });
202
+ assert.strictEqual(out.document.controller, webId);
203
+ assert.strictEqual(out.vm.controller, webId,
204
+ 'VM controller still uses webId regardless of documentController');
205
+ });
206
+
207
+ it('keeps document.controller and vm.controller decoupled by design', () => {
208
+ // Asymmetric on purpose: vm.controller lives inside the WebID
209
+ // profile and identifies who in WebID-land can present this VM
210
+ // (always the pod owner = webId). document.controller lives in
211
+ // /private/privkey.jsonld and identifies the key in its own right
212
+ // (defaults to did:nostr, can be overridden to any custom DID
213
+ // method or URI). The two are distinct semantically; the JSDoc
214
+ // on provisionOwnerKey spells this out.
215
+ const out = provisionOwnerKey({ webId, documentController: 'urn:example:custom' });
216
+ assert.strictEqual(out.document.controller, 'urn:example:custom');
217
+ assert.strictEqual(out.vm.controller, webId,
218
+ 'vm.controller intentionally tracks webId, not documentController');
219
+ });
220
+ });
221
+
222
+ describe('assertProvisionKeysCompatible', () => {
223
+ // Refuse the provisionKeys + --public combination — public mode
224
+ // bypasses WAC, which would expose the freshly-written secret on
225
+ // /private/privkey.jsonld to anyone over HTTP.
226
+ it('throws when both provisionKeys and isPublic are true', () => {
227
+ assert.throws(
228
+ () => assertProvisionKeysCompatible({ provisionKeys: true, isPublic: true }),
229
+ /cannot be combined with --public/
230
+ );
231
+ });
232
+
233
+ it('does NOT throw for provisionKeys alone (the supported case)', () => {
234
+ assert.doesNotThrow(() =>
235
+ assertProvisionKeysCompatible({ provisionKeys: true, isPublic: false })
236
+ );
237
+ });
238
+
239
+ it('does NOT throw for --public alone (no secrets being written)', () => {
240
+ assert.doesNotThrow(() =>
241
+ assertProvisionKeysCompatible({ provisionKeys: false, isPublic: true })
242
+ );
243
+ });
244
+
245
+ it('does NOT throw when neither flag is set', () => {
246
+ assert.doesNotThrow(() =>
247
+ assertProvisionKeysCompatible({ provisionKeys: false, isPublic: false })
248
+ );
249
+ });
250
+ });
251
+
252
+ function hexToBytes(hex) {
253
+ if (hex.length % 2 !== 0) throw new Error('hex length must be even');
254
+ const out = new Uint8Array(hex.length / 2);
255
+ for (let i = 0; i < out.length; i++) {
256
+ out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
257
+ }
258
+ return out;
259
+ }
@@ -132,12 +132,12 @@ describe('renderServerRoot', () => {
132
132
  assert.doesNotMatch(html, /class="info"/);
133
133
  });
134
134
 
135
- it('always emits the Get started button pointing at the docs introduction', () => {
135
+ it('always emits the Get started button pointing at the docs First Run page', () => {
136
136
  const html = renderServerRoot({ version: '1.0.0' });
137
- // The canonical URL is the introduction page, not the category.
138
- // Docusaurus 3 doesn't auto-generate a category index page, so
139
- // /docs/getting-started/ would 404. Link to the real document.
140
- assert.match(html, /href="https:\/\/jss\.live\/docs\/getting-started\/introduction"/);
137
+ // First Run is the friendly "you just installed it, now what?"
138
+ // walkthrough — better destination for a first-time installer than
139
+ // the encyclopedic Introduction page. See #440.
140
+ assert.match(html, /href="https:\/\/jss\.live\/docs\/getting-started\/first-run"/);
141
141
  assert.match(html, /Get started/);
142
142
  });
143
143