passcontrol 0.5.3 → 0.6.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/sdk/verify.js ADDED
@@ -0,0 +1,238 @@
1
+ // Verifying what PassControl signs — from outside PassControl.
2
+ //
3
+ // This is the half of the system that runs on someone ELSE'S machine. A party
4
+ // handed a signed call receipt fetches the issuer's JWK Set once and verifies
5
+ // offline: no account here, no callback, and it keeps working after the issuing
6
+ // deployment is gone.
7
+ //
8
+ // Dependencies: only @noble/curves + the platform `fetch`. Runs on Node 18+,
9
+ // edge runtimes, and the browser.
10
+ import { ed25519 } from "@noble/curves/ed25519";
11
+ export const RECEIPT_TYP = "passcontrol-receipt+jwt";
12
+ export const AGENT_TOKEN_TYP = "passcontrol-agent+jwt";
13
+ /** The newest artifact version this verifier understands. */
14
+ export const SUPPORTED_VER = 2;
15
+ const b64urlToBytes = (value) => {
16
+ const b64 = value.replace(/-/g, "+").replace(/_/g, "/");
17
+ const pad = b64.length % 4 === 0 ? "" : "=".repeat(4 - (b64.length % 4));
18
+ const bin = atob(b64 + pad);
19
+ const out = new Uint8Array(bin.length);
20
+ for (let i = 0; i < bin.length; i++)
21
+ out[i] = bin.charCodeAt(i);
22
+ return out;
23
+ };
24
+ const utf8 = (s) => new TextEncoder().encode(s);
25
+ /**
26
+ * Exact string match, deliberately. Prefix or substring matching here is the
27
+ * classic issuer-confusion bug: `https://good.com.evil.com` starts with nothing
28
+ * useful but ends the way a naive `endsWith` would like, and
29
+ * `https://evil.com/?x=https://good.com` contains a trusted origin outright.
30
+ * A trailing slash is the one normalisation worth allowing.
31
+ */
32
+ export function matchesIssuer(iss, trusted) {
33
+ const strip = (v) => v.replace(/\/+$/, "");
34
+ return trusted.some((candidate) => strip(candidate) === strip(iss));
35
+ }
36
+ async function loadJwks(issuer, options, revalidate = false) {
37
+ if (!revalidate) {
38
+ const cached = options.jwksCache?.get(issuer);
39
+ if (cached)
40
+ return cached;
41
+ }
42
+ const fetchImpl = options.fetch ?? fetch;
43
+ try {
44
+ // `no-cache` means "revalidate with the origin", not "do not cache" — an
45
+ // unchanged key set still answers 304, so the retry below is cheap.
46
+ const res = await fetchImpl(new URL("/.well-known/jwks.json", issuer).toString(), revalidate ? { cache: "no-cache" } : undefined);
47
+ if (!res.ok)
48
+ return null;
49
+ const body = (await res.json());
50
+ const keys = Array.isArray(body?.keys) ? body.keys : [];
51
+ options.jwksCache?.set(issuer, keys);
52
+ return keys;
53
+ }
54
+ catch {
55
+ return null;
56
+ }
57
+ }
58
+ const selectCandidates = (keys, kid) => keys.filter((key) => key?.kty === "OKP" &&
59
+ key?.crv === "Ed25519" &&
60
+ typeof key.x === "string" &&
61
+ (!kid || !key.kid || key.kid === kid));
62
+ /** Monotonic where available; wall clock is an acceptable fallback for a UI timer. */
63
+ const nowMs = () => typeof performance !== "undefined" && typeof performance.now === "function"
64
+ ? performance.now()
65
+ : Date.now();
66
+ /**
67
+ * Emits one VerifyStep per gate, timing each from the end of the previous one.
68
+ * Returns a no-op when no consumer asked for a trace, so the untraced path pays
69
+ * nothing — not even a clock read.
70
+ */
71
+ function tracer(onStep) {
72
+ if (!onStep)
73
+ return () => { };
74
+ let previous = nowMs();
75
+ return (step, ok, reason) => {
76
+ const at = nowMs();
77
+ const ms = at - previous;
78
+ previous = at;
79
+ try {
80
+ onStep(reason === undefined ? { step, ok, ms } : { step, ok, reason, ms });
81
+ }
82
+ catch {
83
+ // Deliberately swallowed. See onStep's contract.
84
+ }
85
+ };
86
+ }
87
+ async function verifySigned(token, typ, options) {
88
+ const trace = tracer(options.onStep);
89
+ // Each gate below reports through `fail`, so the emitted reason and the
90
+ // returned reason cannot drift apart.
91
+ const fail = (step, reason) => {
92
+ trace(step, false, reason);
93
+ return { ok: false, reason };
94
+ };
95
+ const parts = token.split(".");
96
+ if (parts.length !== 3)
97
+ return fail("parse", "malformed");
98
+ const [headerPart, payloadPart, signaturePart] = parts;
99
+ if (!headerPart || !payloadPart || !signaturePart)
100
+ return fail("parse", "malformed");
101
+ let header;
102
+ let claims;
103
+ try {
104
+ header = JSON.parse(new TextDecoder().decode(b64urlToBytes(headerPart)));
105
+ claims = JSON.parse(new TextDecoder().decode(b64urlToBytes(payloadPart)));
106
+ }
107
+ catch {
108
+ return fail("parse", "malformed");
109
+ }
110
+ trace("parse", true);
111
+ // EdDSA is pinned, never read from the token. A verifier that dispatches on
112
+ // the token's own `alg` accepts alg:"none", and accepts an HS256 MAC computed
113
+ // over the public key it just fetched from the JWKS — the key material is
114
+ // public, so the "secret" is known to the attacker. That single mistake turns
115
+ // this whole mechanism into decoration.
116
+ if (header.alg !== "EdDSA")
117
+ return fail("algorithm", "bad_signature");
118
+ trace("algorithm", true);
119
+ // RFC 8725 explicit typing: a historical receipt must never satisfy a live
120
+ // authentication decision, and both are signed by the same key.
121
+ if (header.typ !== typ)
122
+ return fail("type", "wrong_type");
123
+ trace("type", true);
124
+ const iss = typeof claims.iss === "string" ? claims.iss : "";
125
+ if (!iss || !matchesIssuer(iss, options.trustedIssuers)) {
126
+ return fail("issuer", "untrusted_issuer");
127
+ }
128
+ trace("issuer", true);
129
+ // Additive-only versioning: a NEWER artifact than we understand is refused
130
+ // (it may rely on a claim we would ignore), but unknown claims within a
131
+ // supported version are fine — that is what lets the issuer add a field
132
+ // without invalidating verifiers already in the field.
133
+ const ver = typeof claims.ver === "number" ? claims.ver : 0;
134
+ if (ver > SUPPORTED_VER)
135
+ return fail("version", "unsupported_version");
136
+ trace("version", true);
137
+ const keys = await loadJwks(iss, options);
138
+ if (!keys)
139
+ return fail("jwks", "jwks_unreachable");
140
+ trace("jwks", true);
141
+ let candidates = selectCandidates(keys, header.kid);
142
+ if (candidates.length === 0) {
143
+ // Before saying an issuer does not publish this key — which is presented as
144
+ // a forgery — go back to the origin once, bypassing any HTTP cache. The
145
+ // JWKS ships `max-age=300, stale-while-revalidate=86400`, so a browser can
146
+ // hold a key list a day old; across a key rotation that list is missing the
147
+ // NEW key, and a genuine receipt signed minutes ago resolves to unknown_key.
148
+ // (INSTANCE_SIGNING_KEY_PREV keeps OLD keys published for the reverse case.)
149
+ // The retry is the price of an accusation, not of verification: it only runs
150
+ // on the path that was about to make one, and an unchanged key set answers
151
+ // 304. If it fails we keep `unknown_key` — we did reach the issuer and did
152
+ // read a key list, so "could not reach" would misdescribe what happened.
153
+ const fresh = await loadJwks(iss, options, true);
154
+ if (fresh)
155
+ candidates = selectCandidates(fresh, header.kid);
156
+ }
157
+ if (candidates.length === 0)
158
+ return fail("key", "unknown_key");
159
+ trace("key", true);
160
+ const signature = b64urlToBytes(signaturePart);
161
+ const signed = utf8(`${headerPart}.${payloadPart}`);
162
+ for (const key of candidates) {
163
+ try {
164
+ if (ed25519.verify(signature, signed, b64urlToBytes(key.x))) {
165
+ trace("signature", true);
166
+ return { ok: true, claims };
167
+ }
168
+ }
169
+ catch {
170
+ // Try the next key; a malformed JWK entry must not abort verification.
171
+ }
172
+ }
173
+ return fail("signature", "bad_signature");
174
+ }
175
+ /**
176
+ * Verify a signed call receipt.
177
+ *
178
+ * What a valid receipt proves: this issuer attests that the named passport or
179
+ * Direct Agent Key authenticated this call, with this verdict and this cost.
180
+ * A direct receipt proves bearer possession, not a passport signature. It does
181
+ * NOT prove:
182
+ * anything about the response, and nothing at all by its absence — see
183
+ * lib/receipt.ts for the limits, which are deliberate and documented.
184
+ */
185
+ export function verifyReceipt(jws, options) {
186
+ return verifySigned(jws, RECEIPT_TYP, options);
187
+ }
188
+ /**
189
+ * Verify an agent-to-agent token.
190
+ *
191
+ * ── Replay is YOUR problem, deliberately ────────────────────────────────────
192
+ *
193
+ * There is no server-side jti denylist, because there is no server in this
194
+ * path: verification is offline by design. A token is a bearer credential for
195
+ * its (short) lifetime, so if replay matters to you, dedupe on `claims.jti` —
196
+ * which is why it is returned. The short TTL bounds the window; it does not
197
+ * close it.
198
+ */
199
+ export async function verifyAgentToken(token, options) {
200
+ if (!options.audience)
201
+ return { ok: false, reason: "wrong_audience" };
202
+ const result = await verifySigned(token, AGENT_TOKEN_TYP, options);
203
+ if (!result.ok)
204
+ return result;
205
+ const claims = result.claims;
206
+ // Exact match. A token minted for `aud: "billing"` must not satisfy a
207
+ // verifier that is `payments`, however similar the names look.
208
+ if (claims.aud !== options.audience)
209
+ return { ok: false, reason: "wrong_audience" };
210
+ const now = Math.floor((options.now?.() ?? Date.now()) / 1000);
211
+ if (typeof claims.exp !== "number" || claims.exp <= now)
212
+ return { ok: false, reason: "expired" };
213
+ if (options.requireOnline) {
214
+ const live = await passportStatus(claims.iss, claims.sub, options);
215
+ // An unreachable issuer is NOT a revocation. Report it distinctly so the
216
+ // caller decides whether their situation tolerates an unknown, rather than
217
+ // having an outage silently read as "this agent was revoked".
218
+ if (live === null)
219
+ return { ok: false, reason: "status_unavailable" };
220
+ if (live !== "active")
221
+ return { ok: false, reason: "revoked" };
222
+ }
223
+ return { ok: true, claims };
224
+ }
225
+ async function passportStatus(issuer, passportId, options) {
226
+ const fetchImpl = options.fetch ?? fetch;
227
+ try {
228
+ const url = new URL(`/api/verify/${encodeURIComponent(passportId)}`, issuer).toString();
229
+ const res = await fetchImpl(url);
230
+ if (!res.ok)
231
+ return null;
232
+ const body = (await res.json());
233
+ return typeof body?.data?.status === "string" ? body.data.status : null;
234
+ }
235
+ catch {
236
+ return null;
237
+ }
238
+ }