@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 +71 -0
- package/dist/index.js +20 -10
- package/dist/packages/sdk/index.d.ts +1 -1
- package/dist/src/lib/meter.d.ts +18 -0
- package/dist/src/lib/wimse.d.ts +35 -2
- package/package.json +1 -1
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(
|
|
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(
|
|
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(
|
|
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
|
-
|
|
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 !==
|
|
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 !==
|
|
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
|
-
|
|
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(
|
|
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
|
-
|
|
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;
|
package/dist/src/lib/wimse.d.ts
CHANGED
|
@@ -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.
|
|
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"}
|