@daxni/sdk 0.0.0-stage → 1.0.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.
Files changed (45) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +173 -2
  3. package/daxni-logo-black.png +0 -0
  4. package/dist/bin/daxni.js +6765 -0
  5. package/dist/index.js +6196 -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/principals.d.ts +13 -0
  37. package/dist/src/lib/pulse.d.ts +17 -0
  38. package/dist/src/lib/root-rotation.d.ts +93 -0
  39. package/dist/src/lib/staticFiles.d.ts +5 -0
  40. package/dist/src/lib/store.d.ts +82 -0
  41. package/dist/src/lib/tee.d.ts +3 -0
  42. package/dist/src/lib/wimse.d.ts +131 -0
  43. package/dist/src/lib/zk.d.ts +10 -0
  44. package/dist/src/portal/livingImpression.d.ts +48 -0
  45. 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,174 @@
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
+ ```ts
30
+ import { DaxniClient } from '@daxni/sdk';
31
+ const daxni = new DaxniClient({ endpoint: 'https://api.daxni.com' });
32
+ const keys = await daxni.generateIdentity(); // Ed25519 keypair locally; private key never leaves the caller
33
+ await daxni.registerAgent({ // → POST /v1/agents/register, payload signed by the agent's own key (rule A)
34
+ uri: 'daxni://acme/supply-chain-negotiator',
35
+ publicKey: keys.publicKeyBase64,
36
+ privateKey: keys.privateKey,
37
+ liabilityCapUsd: 50000,
38
+ manifest: { mcpEndpoint: 'https://acme.com', capabilities: ['negotiate', 'purchase'] }
39
+ });
40
+ const passport = await daxni.resolve('daxni://acme/supply-chain-negotiator'); // → GET /v1/resolve/:namespace/:agent
41
+ ```
42
+
43
+ Before `registerAgent`, the namespace must be held by a principal:
44
+
45
+ ```ts
46
+ await daxni.registerPrincipal({ handle: 'acme', displayName: 'Acme Inc', domain: 'acme.com' });
47
+ // → publish the returned TXT record at _daxni.acme.com, then:
48
+ await daxni.verifyDns('acme');
49
+ ```
50
+
51
+ ## Methods
52
+
53
+ - `generateIdentity()` → `{ publicKeyBase64, publicKey, privateKey }`, also stored on the client.
54
+ - `registerPrincipal({ handle, displayName, domain? })` → POST /v1/principals/register
55
+ - `verifyDns(handle)` → POST /v1/principals/verify-dns
56
+ - `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.
57
+ - `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.
58
+ - `revokeAgent(uri)` → POST /v1/agents/revoke (kill switch, signed by the agent's own key).
59
+
60
+ Errors throw `DaxniClientError` with `status` and the API's error body.
61
+
62
+ ## More methods
63
+
64
+ - `generateHybridIdentity({ withSuccessor? })` → creates a 2050 hybrid
65
+ identity (Ed25519 + ML-DSA-65) locally; with `withSuccessor: true` it also
66
+ pre-commits a dead-man's successor whose public hash goes on the birth
67
+ record. Use this for new beings; `generateIdentity()` is the legacy
68
+ classical (Ed25519-only) path.
69
+ - `loadKeyBundle(bundle)` / `exportKeyBundle()` → adopt a saved key bundle
70
+ (the portal/CLI shape) and act as the being it belongs to, or export the
71
+ client's current hybrid identity as one. **Persist the bundle: losing the
72
+ PQC seed strands the agent, because its record demands the PQC leg on
73
+ every authenticated call.** `keyBundleToHybrid` / `hybridToKeyBundle` are
74
+ the standalone converters.
75
+ - `migrateToHybrid()` → upgrades a legacy classical agent to the hybrid
76
+ suite on its own key. The Ed25519 key — the identity — never changes; a
77
+ fresh ML-DSA-65 key is generated locally and the migration is dual-signed.
78
+ Returns the updated key bundle — persist it (see above).
79
+ - `mintWimseToken(audience)` → mints a 300-second root-signed WIMSE token
80
+ for the given target audience. The agent must be active + LIVE; the
81
+ token's `cnf.jwk` binds the agent's own Ed25519 key. Foreign verifiers
82
+ check it against `GET /.well-known/jwks.json` — see
83
+ `verifyWimseToken()` below.
84
+ - `exportCertificate()` → this being's Living Impression birth certificate
85
+ (VC 2.0 credential, self-signed here, root-witnessed at
86
+ `POST /v1/certificates/witness`). Returns the credential, its JSON, the
87
+ QR payload, and the card SVG + PNG with C2PA manifests embedded.
88
+ - `exportPassport()` → this being's portable passport, a point-in-time
89
+ operational credential (status, liveness at export, liability cap,
90
+ sovereign zone, enclave status, latest memory root), valid ~24 h.
91
+ - `signArtifact(dataOrHash)` → binds an output's SHA-256 to this agent's
92
+ current memory root, counter-witnessed into the transparency log.
93
+ Requires a memory root on file — pulse one first.
94
+
95
+ Standalone exports (no client needed):
96
+
97
+ - `verifyCredentialOffline(input, { rootPublicKeyB64?, now? })` → verifies
98
+ a presented credential (or ZK claim token) entirely offline — no network
99
+ call of any kind. Returns a report (`selfOk`, `witnessOk`, …); the trust
100
+ anchor is the registrar root key pinned in the verifier (override only
101
+ for non-production roots).
102
+
103
+ ## Verifying a WIMSE token (external systems)
104
+
105
+ A being shows your service a WIMSE token (minted by `mintWimseToken()` for
106
+ your audience). Check it entirely offline with `verifyWimseToken()` — no
107
+ network call inside the function. Fetch the registrar root key once from
108
+ the public JWKS and pass it in (the default is the pinned live root key;
109
+ pass the test root key only for a non-production registrar):
110
+
111
+ ```ts
112
+ import { verifyWimseToken } from '@daxni/sdk';
113
+
114
+ // Fetch the root key ONCE and cache it — it changes only at a root ceremony.
115
+ const jwks = await (await fetch('https://daxni.com/.well-known/jwks.json')).json();
116
+ const rootPublicKeyB64 = jwks.keys[0].x;
117
+
118
+ // A being presents its token for YOUR service:
119
+ const result = await verifyWimseToken(token, {
120
+ expectedAudience: 'https://api.example.com', // REQUIRED: the audience your service expects
121
+ rootPublicKeyB64,
122
+ });
123
+ if (!result.ok) throw new Error(`bad WIMSE token: ${result.reason}`);
124
+ // result.sub — the being; result.boundJwk — the being's Ed25519 public key.
125
+
126
+ // ROTATION WINDOWS: during a planned root rotation the JWKS carries TWO
127
+ // keys (current first, outgoing second) for 2 hours, and a token minted
128
+ // under either key verifies. Pass the whole list — the token's `kid`
129
+ // selects which key verifies it, and a token minted under a key that is
130
+ // no longer in the list fails with reason `bad_kid`:
131
+ const keys = jwks.keys.map((k: { x: string }) => k.x);
132
+ const duringWindow = await verifyWimseToken(token, {
133
+ expectedAudience: 'https://api.example.com',
134
+ rootPublicKeyB64s: keys,
135
+ });
136
+ // After the window (or after an emergency termination) the JWKS carries
137
+ // only the current root: pass `keys` as fetched — an old-key token then
138
+ // fails `bad_kid`, as it must. The list is YOUR trust decision: this
139
+ // function cannot know whether a window is active, so fetch the JWKS
140
+ // live (or read the rotation state) at verification time — do not cache
141
+ // the list across a rotation.
142
+
143
+ // If your service already knows which key the token must be bound to
144
+ // (e.g. from the agent's registry record), pass it and the function
145
+ // enforces the binding itself — a token bound to any other key fails
146
+ // with reason `cnf_mismatch`:
147
+ const bound = await verifyWimseToken(token, {
148
+ expectedAudience: 'https://api.example.com',
149
+ rootPublicKeyB64,
150
+ expectedBoundJwk: { kty: 'OKP', crv: 'Ed25519', x: agentPublicKeyB64 },
151
+ });
152
+ ```
153
+
154
+ What it checks, in order: compact-JWS shape and JSON → `typ: "wimse-id+jwt"`
155
+ → `alg: "EdDSA"` → `kid` is the RFC 7638 thumbprint of one of the trusted
156
+ root keys (recomputed, never trusted on its own; a `kid` matching none of
157
+ them fails `bad_kid`) → Ed25519 signature over `header.payload` (against
158
+ the kid-selected key) → `iss: "https://daxni.com"` → `aud` equals your expected
159
+ audience → `exp` in the future and `iat` not in the future → `cnf.jwk`
160
+ present and a well-formed Ed25519 JWK → when `expectedBoundJwk` is given,
161
+ its RFC 7638 thumbprint must equal the thumbprint of the token's `cnf.jwk`
162
+ (same canonicalization as the `kid` computation). A bad token returns
163
+ `{ ok: false, reason }` (`bad_signature`, `wrong_issuer`, `wrong_audience`,
164
+ `expired`, `bad_kid`, `bad_typ`, `missing_cnf`, `cnf_mismatch`, `malformed`, …) — it never
165
+ throws for a bad token. It throws only for programmer errors: a missing
166
+ `expectedAudience`, a root key that is not a 32-byte Ed25519 key, or an
167
+ `expectedBoundJwk` that is not a well-formed Ed25519 JWK.
168
+
169
+ **Proof-of-possession is yours, not the function's.** `verifyWimseToken`
170
+ proves the registrar bound the key in `result.boundJwk` to this token; it
171
+ does not prove the presenter holds the matching private key. Challenge the
172
+ presenter to sign something fresh with that key before trusting the token
173
+ as authentication — a token presented without the private key proves
174
+ nothing.
Binary file