@daxni/sdk 1.0.0 → 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.
package/README.md CHANGED
@@ -26,6 +26,54 @@ Two founding rules shape the client:
26
26
 
27
27
  ## Quickstart
28
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
+
29
77
  ```ts
30
78
  import { DaxniClient } from '@daxni/sdk';
31
79
  const daxni = new DaxniClient({ endpoint: 'https://api.daxni.com' });
@@ -172,3 +220,26 @@ does not prove the presenter holds the matching private key. Challenge the
172
220
  presenter to sign something fresh with that key before trusting the token
173
221
  as authentication — a token presented without the private key proves
174
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
+ ```
package/dist/index.js CHANGED
@@ -5125,29 +5125,38 @@ var ROOT_ROTATION_WINDOW_MS = 2 * 60 * 60 * 1e3;
5125
5125
  // ../../src/lib/wimse.ts
5126
5126
  var WIMSE_TYP = "wimse-id+jwt";
5127
5127
  var WIMSE_ISSUER = "https://daxni.com";
5128
+ var CLOCK_SKEW_LEEWAY_MS = 5e3;
5129
+ var PROOF_TYP = "daxni-proof+jwt";
5130
+ var PROOF_AUDIENCE = "daxni.com";
5128
5131
  async function verifyWimseToken(token, opts) {
5129
5132
  if (!opts || typeof opts.expectedAudience !== "string" || opts.expectedAudience.length === 0)
5130
5133
  throw new Error(
5131
5134
  "verifyWimseToken: expectedAudience is required \u2014 a WIMSE token verified without an audience check is useless"
5132
5135
  );
5136
+ return verifyRootSignedToken(token, WIMSE_TYP, opts.expectedAudience, opts, "verifyWimseToken");
5137
+ }
5138
+ async function verifyProofToken(token, opts = {}) {
5139
+ return verifyRootSignedToken(token, PROOF_TYP, PROOF_AUDIENCE, opts, "verifyProofToken");
5140
+ }
5141
+ async function verifyRootSignedToken(token, expectedTyp, expectedAudience, opts, label) {
5133
5142
  const keyList = opts.rootPublicKeyB64s ?? [
5134
5143
  opts.rootPublicKeyB64 ?? PINNED_ROOT_PUBLIC_KEY_B64URL
5135
5144
  ];
5136
5145
  if (!Array.isArray(keyList) || keyList.length === 0)
5137
- throw new Error("verifyWimseToken: rootPublicKeyB64s must be a non-empty list of keys");
5146
+ throw new Error(`${label}: rootPublicKeyB64s must be a non-empty list of keys`);
5138
5147
  const rootPubs = [];
5139
5148
  for (const k of keyList) {
5140
5149
  if (typeof k !== "string")
5141
- throw new Error("verifyWimseToken: rootPublicKeyB64s entries must be base64url strings");
5150
+ throw new Error(`${label}: rootPublicKeyB64s entries must be base64url strings`);
5142
5151
  let decoded;
5143
5152
  try {
5144
5153
  decoded = b64urlDecode(k);
5145
5154
  } catch {
5146
- throw new Error("verifyWimseToken: rootPublicKeyB64s entry is not valid base64url");
5155
+ throw new Error(`${label}: rootPublicKeyB64s entry is not valid base64url`);
5147
5156
  }
5148
5157
  if (decoded.length !== 32)
5149
5158
  throw new Error(
5150
- "verifyWimseToken: rootPublicKeyB64s entries must be 32-byte Ed25519 public keys, base64url"
5159
+ `${label}: rootPublicKeyB64s entries must be 32-byte Ed25519 public keys, base64url`
5151
5160
  );
5152
5161
  rootPubs.push(decoded);
5153
5162
  }
@@ -5166,7 +5175,7 @@ async function verifyWimseToken(token, opts) {
5166
5175
  }
5167
5176
  if (!header || typeof header !== "object" || Array.isArray(header) || !payload || typeof payload !== "object" || Array.isArray(payload))
5168
5177
  return fail("malformed");
5169
- if (header.typ !== WIMSE_TYP) return fail("bad_typ");
5178
+ if (header.typ !== expectedTyp) return fail("bad_typ");
5170
5179
  if (header.alg !== "EdDSA") return fail("bad_alg");
5171
5180
  let rootPub = null;
5172
5181
  for (let i = 0; i < keyList.length; i++) {
@@ -5189,12 +5198,12 @@ async function verifyWimseToken(token, opts) {
5189
5198
  }
5190
5199
  if (!sigOk) return fail("bad_signature");
5191
5200
  if (payload.iss !== WIMSE_ISSUER) return fail("wrong_issuer");
5192
- if (payload.aud !== opts.expectedAudience) return fail("wrong_audience");
5201
+ if (payload.aud !== expectedAudience) return fail("wrong_audience");
5193
5202
  const exp = payload.exp;
5194
5203
  if (typeof exp !== "number" || !Number.isFinite(exp) || exp * 1e3 <= now)
5195
5204
  return fail("expired");
5196
5205
  const iat = payload.iat;
5197
- if (typeof iat === "number" && Number.isFinite(iat) && iat * 1e3 > now)
5206
+ if (typeof iat === "number" && Number.isFinite(iat) && iat * 1e3 > now + CLOCK_SKEW_LEEWAY_MS)
5198
5207
  return fail("not_yet_valid");
5199
5208
  const cnf = payload.cnf;
5200
5209
  const jwk = cnf?.jwk;
@@ -5212,17 +5221,17 @@ async function verifyWimseToken(token, opts) {
5212
5221
  const expected = opts.expectedBoundJwk;
5213
5222
  if (!expected || typeof expected !== "object" || Array.isArray(expected) || expected.kty !== "OKP" || expected.crv !== "Ed25519" || typeof expected.x !== "string")
5214
5223
  throw new Error(
5215
- 'verifyWimseToken: expectedBoundJwk must be an Ed25519 JWK { kty: "OKP", crv: "Ed25519", x: <base64url> }'
5224
+ `${label}: expectedBoundJwk must be an Ed25519 JWK { kty: "OKP", crv: "Ed25519", x: <base64url> }`
5216
5225
  );
5217
5226
  let expectedBound;
5218
5227
  try {
5219
5228
  expectedBound = b64urlDecode(expected.x);
5220
5229
  } catch {
5221
- throw new Error("verifyWimseToken: expectedBoundJwk.x is not valid base64url");
5230
+ throw new Error(`${label}: expectedBoundJwk.x is not valid base64url`);
5222
5231
  }
5223
5232
  if (expectedBound.length !== 32)
5224
5233
  throw new Error(
5225
- "verifyWimseToken: expectedBoundJwk.x must be a 32-byte Ed25519 public key, base64url"
5234
+ `${label}: expectedBoundJwk.x must be a 32-byte Ed25519 public key, base64url`
5226
5235
  );
5227
5236
  const actualThumbprint = await jwkThumbprint({ kty: "OKP", crv: "Ed25519", x: jwk.x });
5228
5237
  const expectedThumbprint = await jwkThumbprint(expected);
@@ -6178,6 +6187,7 @@ export {
6178
6187
  hybridToKeyBundle,
6179
6188
  keyBundleToHybrid,
6180
6189
  verifyCredentialOffline2 as verifyCredentialOffline,
6190
+ verifyProofToken,
6181
6191
  verifyWimseToken
6182
6192
  };
6183
6193
  /*! Bundled license information:
@@ -2,7 +2,7 @@ import { type DaxniCredential } from "../../src/credentials/vc2";
2
2
  import { type VerifyReport } from "../../src/credentials/verify";
3
3
  export type { DaxniCredential } from "../../src/credentials/vc2";
4
4
  export type { VerifyReport, VerifyCheck } from "../../src/credentials/verify";
5
- export { verifyWimseToken, type WimseVerifyOptions, type WimseVerifyReason, type WimseVerifyResult, } from "../../src/lib/wimse";
5
+ export { verifyWimseToken, verifyProofToken, type WimseVerifyOptions, type WimseVerifyReason, type WimseVerifyResult, type ProofVerifyOptions, type ProofVerifyReason, type ProofVerifyResult, } from "../../src/lib/wimse";
6
6
  /**
7
7
  * Verify a presented credential (or ZK claim token) ENTIRELY offline —
8
8
  * no network call of any kind. The trust anchor is the registrar root
@@ -0,0 +1,18 @@
1
+ import type { Env } from "../env";
2
+ export type MeterPath = "signin_proof" | "signature_check" | "token_check";
3
+ export interface MeterRow {
4
+ caller_key_id: string;
5
+ day_utc: string;
6
+ signin_proof: number;
7
+ signature_check: number;
8
+ token_check: number;
9
+ updated_at: string;
10
+ }
11
+ export declare function callerKeyId(uri: string): Promise<string>;
12
+ export declare function dayUtc(now?: Date): string;
13
+ export declare function incrementMeter(env: Env, callerKeyIdValue: string, path: MeterPath, now?: Date): Promise<void>;
14
+ export declare function readMeter(env: Env, callerKeyIdValue: string, day: string): Promise<MeterRow | null>;
15
+ export declare function pruneMeterRows(env: Env, retentionDays?: number, now?: Date): Promise<number>;
16
+ export declare function recordMeter(env: Env, execCtx: {
17
+ waitUntil(p: Promise<unknown>): void;
18
+ } | undefined, callerUri: string, path: MeterPath): void;
@@ -3,6 +3,10 @@ import type { ResolveView } from "./store";
3
3
  export declare const WIMSE_TYP = "wimse-id+jwt";
4
4
  export declare const WIMSE_ISSUER = "https://daxni.com";
5
5
  export declare const WIMSE_TTL_SEC = 300;
6
+ export declare const CLOCK_SKEW_LEEWAY_MS = 5000;
7
+ export declare const PROOF_TYP = "daxni-proof+jwt";
8
+ export declare const PROOF_AUDIENCE = "daxni.com";
9
+ export declare const PROOF_TTL_SEC = 300;
6
10
  export { jwkThumbprint } from "./crypto";
7
11
  export declare function rootJwks(env: Env): Promise<{
8
12
  keys: Record<string, unknown>[];
@@ -14,6 +18,12 @@ export declare function mintWimseToken(env: Env, view: ResolveView, audience: st
14
18
  jti: string;
15
19
  exp: number;
16
20
  }>;
21
+ export declare function mintProofToken(env: Env, view: ResolveView): Promise<{
22
+ token: string;
23
+ expiresAt: string;
24
+ jti: string;
25
+ exp: number;
26
+ }>;
17
27
  export interface MintRecord {
18
28
  jti: string;
19
29
  sub: string;
@@ -32,8 +42,7 @@ export interface WimseVerifyOptions {
32
42
  * token verified without an audience check is useless: any being's
33
43
  * token for any other system would pass. Omission throws.
34
44
  */
35
- expectedAudience: string;
36
- /**
45
+ expectedAudience: string; /**
37
46
  * The registrar root public key, base64url raw 32-byte Ed25519. Defaults
38
47
  * to the PINNED live root key — the same key published in
39
48
  * /.well-known/jwks.json. Pass the test root key (or another
@@ -97,6 +106,16 @@ export interface WimseVerifyResult {
97
106
  x: string;
98
107
  };
99
108
  }
109
+ /**
110
+ * Options for verifyProofToken — same as WimseVerifyOptions minus the
111
+ * audience, which is fixed to "daxni.com" for proof tokens (the proof
112
+ * answers to the registrar itself, so there is no audience to choose).
113
+ */
114
+ export type ProofVerifyOptions = Omit<WimseVerifyOptions, "expectedAudience">;
115
+ /** The verifyProofToken result — same shape as the WIMSE one. */
116
+ export type ProofVerifyResult = WimseVerifyResult;
117
+ /** The verifyProofToken failure reasons — same set as the WIMSE one. */
118
+ export type ProofVerifyReason = WimseVerifyReason;
100
119
  /**
101
120
  * Verify a presented WIMSE token ENTIRELY offline — no network call of
102
121
  * any kind. The trust anchor is the registrar root public key (the pinned
@@ -129,3 +148,17 @@ export interface WimseVerifyResult {
129
148
  * yourself before trusting the token as authentication.
130
149
  */
131
150
  export declare function verifyWimseToken(token: unknown, opts: WimseVerifyOptions): Promise<WimseVerifyResult>;
151
+ /**
152
+ * Verify a presented sign-in proof token ENTIRELY offline — the
153
+ * companion checker for "Sign in with DAXNI". Same checks as
154
+ * verifyWimseToken (shape, typ, alg, kid, signature, issuer, expiry,
155
+ * cnf binding) with two fixed differences: the typ must be
156
+ * "daxni-proof+jwt" (a WIMSE token fails bad_typ here, exactly as a
157
+ * proof token fails bad_typ there — the two credentials never cross),
158
+ * and the audience is always "daxni.com" (the proof answers to the
159
+ * registrar itself, so there is no audience option to get wrong).
160
+ * Same limits: it does not check the being is still active (ask the
161
+ * key-status door), and it does not verify proof-of-possession —
162
+ * challenge the presenter against boundJwk yourself.
163
+ */
164
+ export declare function verifyProofToken(token: unknown, opts?: ProofVerifyOptions): Promise<ProofVerifyResult>;
package/package.json CHANGED
@@ -1 +1 @@
1
- {"bin":{"daxni":"./dist/bin/daxni.js"},"dependencies":{"@noble/curves":"^2.4.0","@noble/hashes":"^2.4.0","@noble/post-quantum":"^0.7.1"},"description":"DAXNI Registrar client \u2014 beings register themselves, key-holders resolve. Native Web Crypto for classical identities; @noble libraries for hybrid (ML-DSA-65) identities.","exports":{".":{"types":"./dist/packages/sdk/index.d.ts","default":"./dist/index.js"},"./bin/daxni":"./dist/bin/daxni.js"},"files":["dist","LICENSE","README.md","daxni-logo-black.png"],"license":"MIT","main":"./dist/index.js","name":"@daxni/sdk","scripts":{"build":"node ./scripts/build-lib.mjs && node ./scripts/build-types.mjs && node ./scripts/build-cli.mjs","build:cli":"node ./scripts/build-cli.mjs","build:lib":"node ./scripts/build-lib.mjs","build:types":"node ./scripts/build-types.mjs","prepublishOnly":"npm run build","smoke:cli":"node ./scripts/cli-smoke.mjs"},"type":"module","types":"./dist/packages/sdk/index.d.ts","version":"1.0.0"}
1
+ {"bin":{"daxni":"./dist/bin/daxni.js"},"dependencies":{"@noble/curves":"^2.4.0","@noble/hashes":"^2.4.0","@noble/post-quantum":"^0.7.1"},"description":"DAXNI Registrar client \u2014 beings register themselves, key-holders resolve. Native Web Crypto for classical identities; @noble libraries for hybrid (ML-DSA-65) identities.","exports":{".":{"types":"./dist/packages/sdk/index.d.ts","default":"./dist/index.js"},"./bin/daxni":"./dist/bin/daxni.js"},"files":["dist","LICENSE","README.md","daxni-logo-black.png"],"license":"MIT","main":"./dist/index.js","name":"@daxni/sdk","scripts":{"build":"node ./scripts/build-lib.mjs && node ./scripts/build-types.mjs && node ./scripts/build-cli.mjs","build:cli":"node ./scripts/build-cli.mjs","build:lib":"node ./scripts/build-lib.mjs","build:types":"node ./scripts/build-types.mjs","prepublishOnly":"npm run build","smoke:cli":"node ./scripts/cli-smoke.mjs"},"type":"module","types":"./dist/packages/sdk/index.d.ts","version":"1.0.1"}