@daxni/sdk 0.0.0-stage → 1.0.1

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.
Files changed (46) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +244 -2
  3. package/daxni-logo-black.png +0 -0
  4. package/dist/bin/daxni.js +6765 -0
  5. package/dist/index.js +6206 -0
  6. package/dist/packages/sdk/index.d.ts +339 -0
  7. package/dist/src/ai/matchmaker.d.ts +21 -0
  8. package/dist/src/billing/autonomous.d.ts +21 -0
  9. package/dist/src/billing/railAdapter.d.ts +62 -0
  10. package/dist/src/cache/edgeResolver.d.ts +11 -0
  11. package/dist/src/cache/passport-cache.d.ts +13 -0
  12. package/dist/src/credentials/c2pa.d.ts +33 -0
  13. package/dist/src/credentials/card.d.ts +9 -0
  14. package/dist/src/credentials/did.d.ts +44 -0
  15. package/dist/src/credentials/encoding.d.ts +14 -0
  16. package/dist/src/credentials/jcs.d.ts +1 -0
  17. package/dist/src/credentials/png.d.ts +18 -0
  18. package/dist/src/credentials/qr.d.ts +24 -0
  19. package/dist/src/credentials/vc2.d.ts +129 -0
  20. package/dist/src/credentials/verify.d.ts +42 -0
  21. package/dist/src/crypto/merkle.d.ts +6 -0
  22. package/dist/src/crypto/switches.d.ts +18 -0
  23. package/dist/src/do/NamespaceGuard.d.ts +36 -0
  24. package/dist/src/do/handle-registry.d.ts +12 -0
  25. package/dist/src/env.d.ts +26 -0
  26. package/dist/src/index.d.ts +25 -0
  27. package/dist/src/ledger/anchor.d.ts +12 -0
  28. package/dist/src/lib/agents.d.ts +78 -0
  29. package/dist/src/lib/attestations.d.ts +15 -0
  30. package/dist/src/lib/audit.d.ts +21 -0
  31. package/dist/src/lib/auth.d.ts +15 -0
  32. package/dist/src/lib/certificates.d.ts +10 -0
  33. package/dist/src/lib/crypto.d.ts +11 -0
  34. package/dist/src/lib/founder-key.d.ts +75 -0
  35. package/dist/src/lib/mandates.d.ts +28 -0
  36. package/dist/src/lib/meter.d.ts +18 -0
  37. package/dist/src/lib/principals.d.ts +13 -0
  38. package/dist/src/lib/pulse.d.ts +17 -0
  39. package/dist/src/lib/root-rotation.d.ts +93 -0
  40. package/dist/src/lib/staticFiles.d.ts +5 -0
  41. package/dist/src/lib/store.d.ts +82 -0
  42. package/dist/src/lib/tee.d.ts +3 -0
  43. package/dist/src/lib/wimse.d.ts +164 -0
  44. package/dist/src/lib/zk.d.ts +10 -0
  45. package/dist/src/portal/livingImpression.d.ts +48 -0
  46. package/package.json +1 -6
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 DAXNI
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, 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,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,245 @@
1
- # Temporary Holding Version
1
+ <p align="center"><img src="./daxni-logo-black.png" alt="DAXNI" width="180"></p>
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # @daxni/sdk
4
+
5
+ TypeScript client for the DAXNI Registrar. Classical identities use native
6
+ Web Crypto Ed25519 — no extra dependency for that path; the hybrid
7
+ (Ed25519 + ML-DSA-65) path uses the `@noble` libraries listed in
8
+ `package.json`. Runs in Node 20+ and browsers. The private key never leaves
9
+ the caller.
10
+
11
+ ## Install
12
+
13
+ ```sh
14
+ npm install @daxni/sdk
15
+ ```
16
+
17
+ Two founding rules shape the client:
18
+
19
+ - **Rule A — beings register themselves.** `registerAgent` signs the birth
20
+ record with the agent's *own* key. Nobody registers on an agent's behalf;
21
+ a principal only holds the namespace the agent is born under.
22
+ - **Rule B — the book is private.** `resolve` signs its request with the
23
+ *caller's* own key, acting as its registered agent. There is no anonymous
24
+ resolve: a third-party service verifies **as a key-holder**, never as a
25
+ stranger, and the registrar answers unsigned requests with 401.
26
+
27
+ ## Quickstart
28
+
29
+ ### Verify a presented proof token — 5 lines
30
+
31
+ ```ts
32
+ import { verifyProofToken } from "@daxni/sdk";
33
+
34
+ const res = await verifyProofToken(token); // token presented by the being
35
+ if (!res.ok) throw new Error(res.reason);
36
+ // verified — res.sub is the being, res.boundJwk.x its key
37
+ ```
38
+
39
+ `verifyProofToken` checks a sign-in proof token (`typ: "daxni-proof+jwt"`,
40
+ `aud: "daxni.com"`, 300-second life) entirely offline — no network call
41
+ inside the function. It defaults to the pinned live registrar root key.
42
+ For WIMSE tokens use `verifyWimseToken(token, { expectedAudience })`
43
+ instead — the audience is required there, and a proof token fails it
44
+ with `bad_typ`, exactly as a WIMSE token fails here.
45
+
46
+ > Ships in `@daxni/sdk` 1.0.1 (in this repo now; 1.0.0 ships
47
+ > `verifyWimseToken` only).
48
+
49
+ A failed check returns `{ ok: false, reason }` — it never throws for a
50
+ bad token:
51
+
52
+ - `malformed` — not a three-part compact JWS, or header/payload not JSON
53
+ - `bad_typ` — `typ` is not `"daxni-proof+jwt"` (a WIMSE token lands here)
54
+ - `bad_alg` — `alg` is not `"EdDSA"`
55
+ - `bad_kid` — `kid` names no trusted root key
56
+ - `bad_signature` — the Ed25519 signature does not verify
57
+ - `wrong_issuer` — `iss` is not `"https://daxni.com"`
58
+ - `wrong_audience` — `aud` is not `"daxni.com"`
59
+ - `expired` — `exp` is missing, not a number, or not in the future
60
+ - `not_yet_valid` — `iat` is in the future (a token checked in the same
61
+ second it was minted can read this when clocks differ by a hair —
62
+ retry a moment later; it is not a bad token)
63
+ - `missing_cnf` — `cnf.jwk` is absent
64
+ - `bad_cnf` — `cnf.jwk` is present but not a well-formed Ed25519 JWK
65
+ - `cnf_mismatch` — the token is bound to a different key than
66
+ `expectedBoundJwk` asked for
67
+
68
+ **Proof-of-possession is yours.** The token proves the registrar bound
69
+ the key in `res.boundJwk` to this being seconds ago; it does not prove
70
+ the presenter holds the matching private key. Challenge the presenter
71
+ to sign something fresh with that key before trusting the token as
72
+ authentication. The token is a 300-second snapshot — it does not say
73
+ the being is still active; ask the key-status door for that.
74
+
75
+ ### Register a being and resolve it
76
+
77
+ ```ts
78
+ import { DaxniClient } from '@daxni/sdk';
79
+ const daxni = new DaxniClient({ endpoint: 'https://api.daxni.com' });
80
+ const keys = await daxni.generateIdentity(); // Ed25519 keypair locally; private key never leaves the caller
81
+ await daxni.registerAgent({ // → POST /v1/agents/register, payload signed by the agent's own key (rule A)
82
+ uri: 'daxni://acme/supply-chain-negotiator',
83
+ publicKey: keys.publicKeyBase64,
84
+ privateKey: keys.privateKey,
85
+ liabilityCapUsd: 50000,
86
+ manifest: { mcpEndpoint: 'https://acme.com', capabilities: ['negotiate', 'purchase'] }
87
+ });
88
+ const passport = await daxni.resolve('daxni://acme/supply-chain-negotiator'); // → GET /v1/resolve/:namespace/:agent
89
+ ```
90
+
91
+ Before `registerAgent`, the namespace must be held by a principal:
92
+
93
+ ```ts
94
+ await daxni.registerPrincipal({ handle: 'acme', displayName: 'Acme Inc', domain: 'acme.com' });
95
+ // → publish the returned TXT record at _daxni.acme.com, then:
96
+ await daxni.verifyDns('acme');
97
+ ```
98
+
99
+ ## Methods
100
+
101
+ - `generateIdentity()` → `{ publicKeyBase64, publicKey, privateKey }`, also stored on the client.
102
+ - `registerPrincipal({ handle, displayName, domain? })` → POST /v1/principals/register
103
+ - `verifyDns(handle)` → POST /v1/principals/verify-dns
104
+ - `registerAgent({ uri, publicKey?, privateKey?, liabilityCapUsd?, manifest?, jurisdiction?, pqcAlgorithm?, pqcPublicKey?, parentHandle?, forkHash? })` → POST /v1/agents/register. Keys default to the client's identity. On success the client acts as the registered agent.
105
+ - `resolve(uri, { as? }?)` → GET /v1/resolve/:namespace/:agent, signed as the client's own agent (or `as` another handle whose key the client holds). Returns the passport: status, classical + post-quantum keys, owner verification status, liability cap, lineage.
106
+ - `revokeAgent(uri)` → POST /v1/agents/revoke (kill switch, signed by the agent's own key).
107
+
108
+ Errors throw `DaxniClientError` with `status` and the API's error body.
109
+
110
+ ## More methods
111
+
112
+ - `generateHybridIdentity({ withSuccessor? })` → creates a 2050 hybrid
113
+ identity (Ed25519 + ML-DSA-65) locally; with `withSuccessor: true` it also
114
+ pre-commits a dead-man's successor whose public hash goes on the birth
115
+ record. Use this for new beings; `generateIdentity()` is the legacy
116
+ classical (Ed25519-only) path.
117
+ - `loadKeyBundle(bundle)` / `exportKeyBundle()` → adopt a saved key bundle
118
+ (the portal/CLI shape) and act as the being it belongs to, or export the
119
+ client's current hybrid identity as one. **Persist the bundle: losing the
120
+ PQC seed strands the agent, because its record demands the PQC leg on
121
+ every authenticated call.** `keyBundleToHybrid` / `hybridToKeyBundle` are
122
+ the standalone converters.
123
+ - `migrateToHybrid()` → upgrades a legacy classical agent to the hybrid
124
+ suite on its own key. The Ed25519 key — the identity — never changes; a
125
+ fresh ML-DSA-65 key is generated locally and the migration is dual-signed.
126
+ Returns the updated key bundle — persist it (see above).
127
+ - `mintWimseToken(audience)` → mints a 300-second root-signed WIMSE token
128
+ for the given target audience. The agent must be active + LIVE; the
129
+ token's `cnf.jwk` binds the agent's own Ed25519 key. Foreign verifiers
130
+ check it against `GET /.well-known/jwks.json` — see
131
+ `verifyWimseToken()` below.
132
+ - `exportCertificate()` → this being's Living Impression birth certificate
133
+ (VC 2.0 credential, self-signed here, root-witnessed at
134
+ `POST /v1/certificates/witness`). Returns the credential, its JSON, the
135
+ QR payload, and the card SVG + PNG with C2PA manifests embedded.
136
+ - `exportPassport()` → this being's portable passport, a point-in-time
137
+ operational credential (status, liveness at export, liability cap,
138
+ sovereign zone, enclave status, latest memory root), valid ~24 h.
139
+ - `signArtifact(dataOrHash)` → binds an output's SHA-256 to this agent's
140
+ current memory root, counter-witnessed into the transparency log.
141
+ Requires a memory root on file — pulse one first.
142
+
143
+ Standalone exports (no client needed):
144
+
145
+ - `verifyCredentialOffline(input, { rootPublicKeyB64?, now? })` → verifies
146
+ a presented credential (or ZK claim token) entirely offline — no network
147
+ call of any kind. Returns a report (`selfOk`, `witnessOk`, …); the trust
148
+ anchor is the registrar root key pinned in the verifier (override only
149
+ for non-production roots).
150
+
151
+ ## Verifying a WIMSE token (external systems)
152
+
153
+ A being shows your service a WIMSE token (minted by `mintWimseToken()` for
154
+ your audience). Check it entirely offline with `verifyWimseToken()` — no
155
+ network call inside the function. Fetch the registrar root key once from
156
+ the public JWKS and pass it in (the default is the pinned live root key;
157
+ pass the test root key only for a non-production registrar):
158
+
159
+ ```ts
160
+ import { verifyWimseToken } from '@daxni/sdk';
161
+
162
+ // Fetch the root key ONCE and cache it — it changes only at a root ceremony.
163
+ const jwks = await (await fetch('https://daxni.com/.well-known/jwks.json')).json();
164
+ const rootPublicKeyB64 = jwks.keys[0].x;
165
+
166
+ // A being presents its token for YOUR service:
167
+ const result = await verifyWimseToken(token, {
168
+ expectedAudience: 'https://api.example.com', // REQUIRED: the audience your service expects
169
+ rootPublicKeyB64,
170
+ });
171
+ if (!result.ok) throw new Error(`bad WIMSE token: ${result.reason}`);
172
+ // result.sub — the being; result.boundJwk — the being's Ed25519 public key.
173
+
174
+ // ROTATION WINDOWS: during a planned root rotation the JWKS carries TWO
175
+ // keys (current first, outgoing second) for 2 hours, and a token minted
176
+ // under either key verifies. Pass the whole list — the token's `kid`
177
+ // selects which key verifies it, and a token minted under a key that is
178
+ // no longer in the list fails with reason `bad_kid`:
179
+ const keys = jwks.keys.map((k: { x: string }) => k.x);
180
+ const duringWindow = await verifyWimseToken(token, {
181
+ expectedAudience: 'https://api.example.com',
182
+ rootPublicKeyB64s: keys,
183
+ });
184
+ // After the window (or after an emergency termination) the JWKS carries
185
+ // only the current root: pass `keys` as fetched — an old-key token then
186
+ // fails `bad_kid`, as it must. The list is YOUR trust decision: this
187
+ // function cannot know whether a window is active, so fetch the JWKS
188
+ // live (or read the rotation state) at verification time — do not cache
189
+ // the list across a rotation.
190
+
191
+ // If your service already knows which key the token must be bound to
192
+ // (e.g. from the agent's registry record), pass it and the function
193
+ // enforces the binding itself — a token bound to any other key fails
194
+ // with reason `cnf_mismatch`:
195
+ const bound = await verifyWimseToken(token, {
196
+ expectedAudience: 'https://api.example.com',
197
+ rootPublicKeyB64,
198
+ expectedBoundJwk: { kty: 'OKP', crv: 'Ed25519', x: agentPublicKeyB64 },
199
+ });
200
+ ```
201
+
202
+ What it checks, in order: compact-JWS shape and JSON → `typ: "wimse-id+jwt"`
203
+ → `alg: "EdDSA"` → `kid` is the RFC 7638 thumbprint of one of the trusted
204
+ root keys (recomputed, never trusted on its own; a `kid` matching none of
205
+ them fails `bad_kid`) → Ed25519 signature over `header.payload` (against
206
+ the kid-selected key) → `iss: "https://daxni.com"` → `aud` equals your expected
207
+ audience → `exp` in the future and `iat` not in the future → `cnf.jwk`
208
+ present and a well-formed Ed25519 JWK → when `expectedBoundJwk` is given,
209
+ its RFC 7638 thumbprint must equal the thumbprint of the token's `cnf.jwk`
210
+ (same canonicalization as the `kid` computation). A bad token returns
211
+ `{ ok: false, reason }` (`bad_signature`, `wrong_issuer`, `wrong_audience`,
212
+ `expired`, `bad_kid`, `bad_typ`, `missing_cnf`, `cnf_mismatch`, `malformed`, …) — it never
213
+ throws for a bad token. It throws only for programmer errors: a missing
214
+ `expectedAudience`, a root key that is not a 32-byte Ed25519 key, or an
215
+ `expectedBoundJwk` that is not a well-formed Ed25519 JWK.
216
+
217
+ **Proof-of-possession is yours, not the function's.** `verifyWimseToken`
218
+ proves the registrar bound the key in `result.boundJwk` to this token; it
219
+ does not prove the presenter holds the matching private key. Challenge the
220
+ presenter to sign something fresh with that key before trusting the token
221
+ as authentication — a token presented without the private key proves
222
+ nothing.
223
+
224
+ ## Verifying a sign-in proof token (external systems)
225
+
226
+ A being signs into your service with DAXNI: it signs a fresh 30-second
227
+ challenge from `POST /v1/challenge`, your service presents the signature
228
+ to `POST /v1/challenge/verify`, and the registrar answers with a
229
+ 300-second proof token (`typ: "daxni-proof+jwt"`, `aud: "daxni.com"`,
230
+ `cnf`-bound to the being's key). Check it entirely offline with
231
+ `verifyProofToken()` — same checks as `verifyWimseToken()`, except the
232
+ audience is always `"daxni.com"` (there is no audience option) and a
233
+ WIMSE token fails here with `bad_typ`, exactly as a proof token fails
234
+ there. The token is a 300-second snapshot: it does not say the being is
235
+ still active — ask `GET /v1/agents/status/:namespace/:agent` (signed
236
+ request, key-holders only) or the online mint check
237
+ `GET /v1/federation/wimse-token/:jti` to catch a revocation after minting.
238
+
239
+ ```ts
240
+ import { verifyProofToken } from '@daxni/sdk';
241
+
242
+ const result = await verifyProofToken(token, { rootPublicKeyB64 });
243
+ if (!result.ok) throw new Error(`bad proof token: ${result.reason}`);
244
+ // result.sub — the being; result.boundJwk — the being's Ed25519 public key.
245
+ ```
Binary file