@statewalker/webrun-biscuit 0.1.0 → 0.2.0

package/dist/parser.d.ts

@@ -6,6 +6,12 @@
 import { type Check, type Fact, type Op, type Predicate, type Rule, type Scope, type Term } from "./datalog.js";
 export declare class ParseError extends Error {
 }
+/**
+ * A value bound to a `{name}` parameter. It becomes a TERM, never source text,
+ * so no string can change the shape of the program it is bound into.
+ */
+export type ParamValue = string | number | bigint | boolean | null | Date | Uint8Array | readonly ParamValue[] | ReadonlySet<ParamValue>;
+export type Params = Readonly<Record<string, ParamValue>>;
 export type Statement = {
     k: "fact";
     fact: Fact;
@@ -25,9 +31,13 @@ export type Statement = {
 };
 export declare class Parser {
     private readonly src;
+    private readonly params;
     private i;
     private readonly vars;
-    constructor(src: string, vars?: Map<string, number>);
+    private readonly usedParams;
+    constructor(src: string, vars?: Map<string, number>, params?: Params);
+    /** names in `params` that the source never referred to */
+    unusedParameters(): string[];
     /** id -> name, for printing rules back out */
     variableNames(): Map<number, string>;
     varId(name: string): number;
@@ -45,6 +55,7 @@ export declare class Parser {
     private tryDate;
     /** a term that may be a variable (rule/check context) */
     term(allowVariables?: boolean): Term;
+    private parameter;
     private array;
     private setOrMap;
     private asMapKey;
@@ -76,5 +87,5 @@ export declare class Parser {
     statement(): Statement;
     parse(): Statement[];
 }
-export declare const parse: (src: string) => Statement[];
+export declare const parse: (src: string, params?: Params) => Statement[];
 //# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAEL,KAAK,KAAK,EAEV,KAAK,IAAI,EAGT,KAAK,EAAE,EACP,KAAK,SAAS,EACd,KAAK,IAAI,EACT,KAAK,KAAK,EACV,KAAK,IAAI,EAEV,MAAM,cAAc,CAAC;AAEtB,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC,MAAM,MAAM,SAAS,GACjB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GACzB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GACzB;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC5B;IAAE,CAAC,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,IAAI,EAAE,CAAA;CAAE,GACxD;IAAE,CAAC,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,KAAK,EAAE,CAAA;CAAE,CAAC;AAKzC,qBAAa,MAAM;IAIf,OAAO,CAAC,QAAQ,CAAC,GAAG;IAHtB,OAAO,CAAC,CAAC,CAAK;IACd,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsB;IAC3C,YACmB,GAAG,EAAE,MAAM,EAC5B,IAAI,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAG3B;IAED,8CAA8C;IAC9C,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAInC;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO1B;IAID,OAAO,CAAC,EAAE;IAgBV,OAAO,KAAK,GAAG,GAGd;IACD,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,GAAG;IAKX,OAAO,CAAC,MAAM;IAGd,gEAAgE;IAChE,OAAO,CAAC,OAAO;IAQf,0EAA0E;IAC1E,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,IAAI;IAYZ,OAAO,CAAC,MAAM;IA+Bd,OAAO,CAAC,OAAO;IAYf,yDAAyD;IACzD,IAAI,CAAC,cAAc,UAAO,GAAG,IAAI,CAkChC;IAED,OAAO,CAAC,KAAK;IAWb,OAAO,CAAC,QAAQ;IA4BhB,OAAO,CAAC,QAAQ;IAQhB,SAAS,CAAC,cAAc,UAAO,GAAG,SAAS,CAW1C;IAID,uEAAuE;IACvE,UAAU,IAAI,EAAE,EAAE,CAEjB;IAED,OAAO,CAAC,MAAM;IAcd,OAAO,CAAC,OAAO;IAcf,OAAO,CAAC,UAAU;IAsBlB,4DAA4D;IAC5D,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,QAAQ;IAYhB,0EAA0E;IAC1E,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,OAAO;IAWf,OAAO,CAAC,OAAO;IAiEf,OAAO,CAAC,OAAO;IAiBf,OAAO,CAAC,MAAM;IAsBd,yEAAyE;IACzE,OAAO,CAAC,QAAQ;IA0BhB,0EAA0E;IAC1E,OAAO,CAAC,YAAY;IAiBpB,OAAO,CAAC,OAAO;IASf,SAAS,IAAI,SAAS,CAgCrB;IAED,KAAK,IAAI,SAAS,EAAE,CAQnB;CACF;AAED,eAAO,MAAM,KAAK,QAAS,MAAM,KAAG,SAAS,EAA6B,CAAC"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-biscuit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "description": "Biscuit authorization tokens in pure TypeScript: proto2 codec, Ed25519 and secp256r1 signature chain, Datalog engine, parser, authorizer and builder. No WASM, no Node built-ins — runs in Node, browsers, Workers and Durable Objects.",

package/src/authorizer.ts

@@ -3,7 +3,7 @@
  * mirroring the evaluation order of the reference implementation.
  */
 
-import { revocationIds, verifyToken } from "./crypto.js";
+import { revocationIds, verifyToken, verifyTokenAsync } from "./crypto.js";
 import {
   AUTHORIZER,
   type Check,
@@ -24,9 +24,10 @@ import {
   trustedOriginsFromScopes,
   World,
 } from "./datalog.js";
-import { Parser, type Statement } from "./parser.js";
+import { type Params, ParseError, Parser, type Statement } from "./parser.js";
 import { printCheck, printPolicy, printPredicate, printRule } from "./print.js";
 import {
+  type BiscuitMsg,
   type BlockMsg,
   decodeBiscuit,
   decodeBlock,
@@ -258,7 +259,24 @@ export function loadToken(
 ): LoadedToken {
   const token = decodeBiscuit(bytes);
   verifyToken(token, rootPublicKey, rootAlgorithm);
+  return toLoadedToken(token);
+}
+
+/**
+ * `loadToken`, verifying signatures with the platform's WebCrypto Ed25519 where
+ * available — see `verifyTokenAsync`. Same result, same errors.
+ */
+export async function loadTokenAsync(
+  bytes: Uint8Array,
+  rootPublicKey: Uint8Array,
+  rootAlgorithm: 0 | 1 = 0,
+): Promise<LoadedToken> {
+  const token = decodeBiscuit(bytes);
+  await verifyTokenAsync(token, rootPublicKey, rootAlgorithm);
+  return toLoadedToken(token);
+}
 
+function toLoadedToken(token: BiscuitMsg): LoadedToken {
   const signed = [token.authority, ...token.blocks];
   const decoded = signed.map((sb) => decodeBlock(sb.block));
 
@@ -327,8 +345,8 @@ function headVariablesAreBound(rule: Rule): boolean {
 /* ------------------------------------------------------------- authorizer */
 
 export type FailedCheck =
-  | { source: "authorizer"; checkId: number }
-  | { source: "block"; blockId: number; checkId: number };
+  | { source: "authorizer"; checkId: number; rule: string }
+  | { source: "block"; blockId: number; checkId: number; rule: string };
 
 export type AuthorizationResult =
   | { kind: "ok"; policy: number }
@@ -360,7 +378,12 @@ interface AuthorizerCode {
   varNames: Map<number, string>;
 }
 
-export function parseAuthorizer(src: string): AuthorizerCode {
+/**
+ * Parse authorizer (or block) source. `{name}` parameters are bound from
+ * `params` as terms; an unbound or an unused parameter is a `ParseError`, as it
+ * is in the reference.
+ */
+export function parseAuthorizer(src: string, params?: Params): AuthorizerCode {
   const out: AuthorizerCode = {
     facts: [],
     rules: [],
@@ -369,8 +392,11 @@ export function parseAuthorizer(src: string): AuthorizerCode {
     scopes: [],
     varNames: new Map(),
   };
-  const parser = new Parser(src);
+  const parser = new Parser(src, undefined, params);
   const statements: Statement[] = parser.parse();
+  const unused = parser.unusedParameters();
+  if (unused.length > 0)
+    throw new ParseError(`unused parameter${unused.length > 1 ? "s" : ""} {${unused.join("}, {")}}`);
   out.varNames = parser.variableNames();
   for (const st of statements) {
     if (st.k === "fact") out.facts.push(st.fact);
@@ -386,14 +412,35 @@ export interface AuthorizeOptions {
   limits?: RunLimits;
   /** extern functions callable as `.extern::name(...)` */
   externs?: Map<string, ExternFn>;
+  /** values for `{name}` parameters in the authorizer code */
+  params?: Params;
+}
+
+export interface QueryOptions {
+  /** values for `{name}` parameters in the query rule */
+  params?: Params;
+}
+
+/** One authorizer run: its result, plus read access to the world it produced. */
+export interface Evaluation {
+  readonly result: AuthorizationResult;
+  /**
+   * Every distinct fact `rule` derives from the evaluated world — the
+   * reference's `Authorizer::query`. The rule sees what the authorizer sees
+   * (authority block and authorizer facts) unless it says `trusting ...`.
+   * Throws when the evaluation itself did not complete.
+   */
+  query(rule: string, options?: QueryOptions): Predicate[];
+  /** The post-run world, in the shape the official sample corpus records it. */
+  snapshot(): WorldSnapshot;
 }
 
 export function authorize(
-  token: LoadedToken,
+  token: LoadedToken | null,
   authorizerSrc: string,
   options: AuthorizeOptions = {},
 ): AuthorizationResult {
-  return authorizeDetailed(token, authorizerSrc, options).result;
+  return evaluate(token, authorizerSrc, options).result;
 }
 
 const EMPTY_WORLD: WorldSnapshot = { facts: [], rules: [], checks: [], policies: [] };
@@ -401,16 +448,32 @@ const EMPTY_WORLD: WorldSnapshot = { facts: [], rules: [], checks: [], policies:
 /** Same as `authorize`, and also returns the post-run world, in the shape the
  *  official sample corpus records it. */
 export function authorizeDetailed(
-  token: LoadedToken,
+  token: LoadedToken | null,
   authorizerSrc: string,
   options: AuthorizeOptions = {},
 ): AuthorizeDetails {
+  const evaluation = evaluate(token, authorizerSrc, options);
+  return { result: evaluation.result, world: evaluation.snapshot() };
+}
+
+const NO_TOKEN: LoadedToken = { blocks: [], publicKeyToBlockIds: new Map(), revocationIds: [] };
+
+/**
+ * Run the authorizer against a verified token — or against no token at all,
+ * for a decision made from the authorizer's own facts and rules.
+ */
+export function evaluate(
+  loadedToken: LoadedToken | null,
+  authorizerSrc: string,
+  options: AuthorizeOptions = {},
+): Evaluation {
+  const token = loadedToken ?? NO_TOKEN;
   const limits = options.limits ?? DEFAULT_LIMITS;
   let code: AuthorizerCode;
   try {
-    code = parseAuthorizer(authorizerSrc);
+    code = parseAuthorizer(authorizerSrc, options.params);
   } catch (e) {
-    return { result: { kind: "format", error: (e as Error).message }, world: EMPTY_WORLD };
+    return unusable({ kind: "format", error: (e as Error).message });
   }
 
   const world = new World();
@@ -426,14 +489,11 @@ export function authorizeDetailed(
     for (const f of block.facts) world.addFact(origin, f);
     for (const r of block.rules) {
       if (!headVariablesAreBound(r))
-        return {
-          result: {
-            kind: "invalidBlockRule",
-            blockId: 0, // the reference implementation always reports 0 here
-            rule: printRule(r, (v) => block.varNames.get(v) ?? String(v)),
-          },
-          world: EMPTY_WORLD,
-        };
+        return unusable({
+          kind: "invalidBlockRule",
+          blockId: 0, // the reference implementation always reports 0 here
+          rule: printRule(r, (v) => block.varNames.get(v) ?? String(v)),
+        });
       world.addRule(id, trustedOriginsFromScopes(r.scopes, trusted, id, keys), r);
     }
   }
@@ -501,11 +561,30 @@ export function authorizeDetailed(
     };
   };
 
+  let failure: ExecutionError | undefined;
+  const settled = (result: AuthorizationResult): Evaluation => ({
+    result,
+    snapshot,
+    query(src: string, queryOptions: QueryOptions = {}): Predicate[] {
+      if (failure) throw failure;
+      const parsed = parseAuthorizer(`${src};`, queryOptions.params);
+      const count =
+        parsed.facts.length + parsed.rules.length + parsed.checks.length + parsed.policies.length;
+      if (count !== 1 || parsed.rules.length !== 1)
+        throw new ParseError("a query must be exactly one rule");
+      const rule = parsed.rules[0];
+      const trusted = trustedOriginsFromScopes(rule.scopes, authorizerTrusted, AUTHORIZER, keys);
+      return world.query(rule, trusted);
+    },
+  });
+
   try {
     world.run(limits);
   } catch (e) {
-    if (e instanceof ExecutionError)
-      return { result: { kind: "execution", error: e.kind }, world: snapshot() };
+    if (e instanceof ExecutionError) {
+      failure = e;
+      return settled({ kind: "execution", error: e.kind });
+    }
     throw e;
   }
 
@@ -528,13 +607,17 @@ export function authorizeDetailed(
     // 1. authorizer checks
     code.checks.forEach((check, i) => {
       if (!runCheck(check, AUTHORIZER, authorizerTrusted))
-        errors.push({ source: "authorizer", checkId: i });
+        errors.push({
+          source: "authorizer",
+          checkId: i,
+          rule: printCheck(check, name(AUTHORIZER)),
+        });
     });
 
     // 2. authority block checks
     token.blocks[0]?.checks.forEach((check, j) => {
       if (!runCheck(check, 0, blockTrusted[0]))
-        errors.push({ source: "block", blockId: 0, checkId: j });
+        errors.push({ source: "block", blockId: 0, checkId: j, rule: printCheck(check, name(0)) });
     });
 
     // 3. policies (first match wins)
@@ -553,7 +636,7 @@ export function authorizeDetailed(
     for (let id = 1; id < token.blocks.length; id++) {
       token.blocks[id].checks.forEach((check, j) => {
         if (!runCheck(check, id, blockTrusted[id]))
-          errors.push({ source: "block", blockId: id, checkId: j });
+          errors.push({ source: "block", blockId: id, checkId: j, rule: printCheck(check, name(id)) });
       });
     }
 
@@ -563,14 +646,27 @@ export function authorizeDetailed(
         : "allow" in policyResult && errors.length === 0
           ? { kind: "ok", policy: policyResult.allow }
           : { kind: "unauthorized", policy: policyResult, checks: errors };
-    return { result, world: snapshot() };
+    return settled(result);
   } catch (e) {
-    if (e instanceof ExecutionError)
-      return { result: { kind: "execution", error: e.kind }, world: snapshot() };
+    if (e instanceof ExecutionError) {
+      failure = e;
+      return settled({ kind: "execution", error: e.kind });
+    }
     throw e;
   }
 }
 
+/** An evaluation that never produced a world: the result says why, and queries refuse. */
+function unusable(result: AuthorizationResult): Evaluation {
+  return {
+    result,
+    snapshot: () => EMPTY_WORLD,
+    query() {
+      throw new Error(`cannot query an evaluation that ended in ${result.kind}`);
+    },
+  };
+}
+
 function compareOrigins(a: (number | null)[], b: (number | null)[]): number {
   for (let i = 0; i < Math.max(a.length, b.length); i++) {
     const x = a[i] === undefined ? -Infinity : (a[i] ?? -1);

package/src/builder.ts

@@ -30,6 +30,7 @@ import {
   type ScopeMsg,
   type TermMsg,
 } from "./proto.js";
+import type { Params } from "./parser.js";
 import { DATALOG_3_2, requiredVersion } from "./version.js";
 
 const SIGNATURE_VERSION = 1;
@@ -52,8 +53,14 @@ class SymbolWriter {
   constructor(
     private readonly known: string[] = [],
     private readonly knownKeys: string[] = [],
+    private readonly varNames: ReadonlyMap<number, string> = new Map(),
   ) {}
 
+  /** A variable's wire id is the symbol index of its NAME, not the parser's local id. */
+  variable(id: number): number {
+    return this.insert(this.varNames.get(id) ?? String(id));
+  }
+
   insert(s: string): number {
     const d = DEFAULT_SYMBOLS.indexOf(s);
     if (d >= 0) return d;
@@ -85,7 +92,7 @@ const parseKeyString = (key: string): PublicKeyMsg => {
 function toTerm(t: Term, w: SymbolWriter): TermMsg {
   switch (t.t) {
     case "var":
-      return { kind: "variable", value: t.v };
+      return { kind: "variable", value: w.variable(t.v) };
     case "int":
       return { kind: "integer", value: t.v };
     case "str":
@@ -130,7 +137,11 @@ const toOps = (ops: Op[], w: SymbolWriter): OpMsg[] =>
       case "binary":
         return { kind: "binary", op: op.op, ffiName: op.ffi ? w.insert(op.ffi) : undefined };
       case "closure":
-        return { kind: "closure", params: op.params, ops: toOps(op.ops, w) };
+        return {
+          kind: "closure",
+          params: op.params.map((p) => w.variable(p)),
+          ops: toOps(op.ops, w),
+        };
       default:
         // unreachable for a well-typed Op; loud rather than `undefined`
         throw new Error(`unknown expression op kind ${(op as { kind: string }).kind}`);
@@ -158,6 +169,8 @@ export interface BlockContent {
   rules: Rule[];
   checks: Check[];
   scopes: Scope[];
+  /** variable id -> name; ids without a name are written as their decimal id */
+  varNames?: ReadonlyMap<number, string>;
 }
 
 export function buildBlockMsg(
@@ -166,7 +179,7 @@ export function buildBlockMsg(
   knownKeys: string[] = [],
   minVersion = 0,
 ): BlockMsg {
-  const w = new SymbolWriter(knownSymbols, knownKeys);
+  const w = new SymbolWriter(knownSymbols, knownKeys, content.varNames);
   const facts = content.facts.map((f) => toPredicate(f.predicate, w));
   const rules = content.rules.map((r) => toRule(r, w));
   const checks = content.checks.map((c) => ({
@@ -185,11 +198,17 @@ export function buildBlockMsg(
   };
 }
 
-const contentFromCode = (code: string): BlockContent => {
-  const parsed = parseAuthorizer(code);
+const contentFromCode = (code: string, params?: Params): BlockContent => {
+  const parsed = parseAuthorizer(code, params);
   if (parsed.policies.length)
     throw new BuilderError("allow/deny policies belong to the authorizer, not to a block");
-  return { facts: parsed.facts, rules: parsed.rules, checks: parsed.checks, scopes: parsed.scopes };
+  return {
+    facts: parsed.facts,
+    rules: parsed.rules,
+    checks: parsed.checks,
+    scopes: parsed.scopes,
+    varNames: parsed.varNames,
+  };
 };
 
 /* ---------------------------------------------------- accumulated tables */
@@ -216,6 +235,8 @@ export interface BuildOptions {
   /** supply a next keypair instead of generating one (tests, determinism) */
   nextKeypair?: Keypair;
   algorithm?: 0 | 1;
+  /** values for `{name}` parameters in the block code */
+  params?: Params;
 }
 
 /** Mint a new token whose authority block holds `code`. */
@@ -225,7 +246,7 @@ export function buildToken(
   options: BuildOptions = {},
 ): Uint8Array {
   const algorithm = options.algorithm ?? 0;
-  const content = typeof code === "string" ? contentFromCode(code) : code;
+  const content = typeof code === "string" ? contentFromCode(code, options.params) : code;
   const blockBytes = encodeBlock(buildBlockMsg(content));
   const next = options.nextKeypair ?? generateKeypair(algorithm);
   const nextKey: PublicKeyMsg = { algorithm, key: next.publicKey };
@@ -257,7 +278,7 @@ export function attenuate(
   const currentAlgorithm = previous.nextKey.algorithm;
 
   const tables = knownTables(token);
-  const content = typeof code === "string" ? contentFromCode(code) : code;
+  const content = typeof code === "string" ? contentFromCode(code, options.params) : code;
   const blockBytes = encodeBlock(buildBlockMsg(content, tables.symbols, tables.keys));
 
   const next = options.nextKeypair ?? generateKeypair(algorithm);
@@ -312,8 +333,9 @@ export function thirdPartyBlock(
   externalSecret: Uint8Array,
   code: string | BlockContent,
   algorithm: 0 | 1 = 0,
+  params?: Params,
 ): ThirdPartyResponse {
-  const content = typeof code === "string" ? contentFromCode(code) : code;
+  const content = typeof code === "string" ? contentFromCode(code, params) : code;
   // a third-party block carries its own symbol table, so it starts from empty,
   // and third-party blocks themselves require datalog v3.2+
   const blockBytes = encodeBlock(buildBlockMsg(content, [], [], DATALOG_3_2));

package/src/crypto.ts

@@ -4,6 +4,7 @@
  */
 import { ed25519 } from "@noble/curves/ed25519.js";
 import { p256 } from "@noble/curves/nist.js";
+import { fromBase64 } from "./base64.js";
 import type { BiscuitMsg, PublicKeyMsg, SignedBlock } from "./proto.js";
 
 export class SignatureError extends Error {}
@@ -144,9 +145,27 @@ export { bytesEqual };
 
 /* --------------------------------------------------------------- verifying */
 
-/** Verifies the full signature chain and the proof. Throws on failure. */
-export function verifyToken(token: BiscuitMsg, rootPublicKey: Uint8Array, rootAlgorithm = 0): void {
+interface SignatureCheck {
+  key: PublicKeyMsg;
+  payload: Uint8Array;
+  signature: Uint8Array;
+  error: string;
+}
+
+/**
+ * Everything verifying a token requires, as data: the signatures to check, in
+ * chain order, and — for an unsealed token — the proof secret whose public key
+ * must equal the last block's next key. Structural problems throw here, before
+ * any signature is looked at. `verifyToken` and `verifyTokenAsync` both consume
+ * this, so neither can skip a check the other makes.
+ */
+function chainChecks(
+  token: BiscuitMsg,
+  rootPublicKey: Uint8Array,
+  rootAlgorithm: number,
+): { checks: SignatureCheck[]; proof?: { secret: Uint8Array; key: PublicKeyMsg } } {
   const root: PublicKeyMsg = { algorithm: rootAlgorithm as 0 | 1, key: rootPublicKey };
+  const checks: SignatureCheck[] = [];
 
   if (token.authority.externalSignature)
     throw new SignatureError("the authority block must not carry an external signature");
@@ -160,8 +179,12 @@ export function verifyToken(token: BiscuitMsg, rootPublicKey: Uint8Array, rootAl
         : (() => {
             throw new SignatureError(`unsupported block version ${authVersion}`);
           })();
-  if (!verifySignature(root, authPayload, token.authority.signature))
-    throw new SignatureError("invalid authority block signature");
+  checks.push({
+    key: root,
+    payload: authPayload,
+    signature: token.authority.signature,
+    error: "invalid authority block signature",
+  });
 
   let currentKey = token.authority.nextKey;
   let previousSignature = token.authority.signature;
@@ -175,16 +198,21 @@ export function verifyToken(token: BiscuitMsg, rootPublicKey: Uint8Array, rootAl
       payload = blockPayloadV1(block.block, block.nextKey, externalSig, previousSignature, version);
     else throw new SignatureError(`unsupported block version ${version}`);
 
-    if (!verifySignature(currentKey, payload, block.signature))
-      throw new SignatureError("invalid block signature");
+    checks.push({
+      key: currentKey,
+      payload,
+      signature: block.signature,
+      error: "invalid block signature",
+    });
 
     if (block.externalSignature) {
       if (version !== 1) throw new SignatureError("unsupported third party block version");
-      const ext = externalPayloadV1(block.block, previousSignature, version);
-      if (
-        !verifySignature(block.externalSignature.publicKey, ext, block.externalSignature.signature)
-      )
-        throw new SignatureError("invalid external signature");
+      checks.push({
+        key: block.externalSignature.publicKey,
+        payload: externalPayloadV1(block.block, previousSignature, version),
+        signature: block.externalSignature.signature,
+        error: "invalid external signature",
+      });
     }
 
     currentKey = block.nextKey;
@@ -192,13 +220,131 @@ export function verifyToken(token: BiscuitMsg, rootPublicKey: Uint8Array, rootAl
   }
 
   if (token.proof.kind === "nextSecret") {
-    const derived = publicKeyFromSecret(token.proof.value, currentKey.algorithm);
-    if (!bytesEqual(derived, currentKey.key))
-      throw new SignatureError("the last public key does not match the private key");
-  } else {
-    const last = token.blocks.length ? token.blocks[token.blocks.length - 1] : token.authority;
-    if (!verifySignature(currentKey, sealPayloadV0(last), token.proof.value))
-      throw new SignatureError("invalid seal signature");
+    return { checks, proof: { secret: token.proof.value, key: currentKey } };
+  }
+  const last = token.blocks.length ? token.blocks[token.blocks.length - 1] : token.authority;
+  checks.push({
+    key: currentKey,
+    payload: sealPayloadV0(last),
+    signature: token.proof.value,
+    error: "invalid seal signature",
+  });
+  return { checks };
+}
+
+/** Verifies the full signature chain and the proof. Throws on failure. */
+export function verifyToken(token: BiscuitMsg, rootPublicKey: Uint8Array, rootAlgorithm = 0): void {
+  const { checks, proof } = chainChecks(token, rootPublicKey, rootAlgorithm);
+  for (const check of checks)
+    if (!verifySignature(check.key, check.payload, check.signature))
+      throw new SignatureError(check.error);
+  if (proof && !bytesEqual(publicKeyFromSecret(proof.secret, proof.key.algorithm), proof.key.key))
+    throw new SignatureError("the last public key does not match the private key");
+}
+
+/**
+ * `verifyToken`, using the platform's WebCrypto for Ed25519 where it offers it
+ * — about ten times faster than the pure-JS path in Node and current browsers.
+ * secp256r1, and any runtime without WebCrypto Ed25519, fall back to
+ * `@noble/curves`, so the result never depends on where it runs.
+ */
+export async function verifyTokenAsync(
+  token: BiscuitMsg,
+  rootPublicKey: Uint8Array,
+  rootAlgorithm = 0,
+): Promise<void> {
+  const { checks, proof } = chainChecks(token, rootPublicKey, rootAlgorithm);
+  const [verdicts, derived] = await Promise.all([
+    Promise.all(checks.map((c) => verifySignatureAsync(c.key, c.payload, c.signature))),
+    proof ? publicKeyFromSecretAsync(proof.secret, proof.key.algorithm) : undefined,
+  ]);
+  verdicts.forEach((ok, i) => {
+    if (!ok) throw new SignatureError(checks[i].error);
+  });
+  if (proof && !bytesEqual(derived as Uint8Array, proof.key.key))
+    throw new SignatureError("the last public key does not match the private key");
+}
+
+/* ------------------------------------------------------ WebCrypto Ed25519 */
+
+type Subtle = {
+  importKey(
+    format: string,
+    data: Uint8Array,
+    algorithm: { name: string },
+    extractable: boolean,
+    usages: string[],
+  ): Promise<unknown>;
+  verify(algorithm: string, key: unknown, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
+  exportKey(format: "jwk", key: unknown): Promise<{ x?: string }>;
+};
+
+const subtle = (globalThis as { crypto?: { subtle?: Subtle } }).crypto?.subtle;
+
+/** PKCS#8 wrapping of a raw 32-byte Ed25519 seed (RFC 8410) */
+const PKCS8_ED25519 = Uint8Array.from([
+  0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+]);
+
+let ed25519Native: Promise<boolean> | undefined;
+
+/** Whether this runtime's WebCrypto verifies Ed25519, and does so correctly. Probed once. */
+function nativeEd25519(): Promise<boolean> {
+  ed25519Native ??= (async () => {
+    if (!subtle) return false;
+    try {
+      const secret = new Uint8Array(32).fill(7);
+      const message = ascii("webrun-biscuit");
+      const signature = ed25519.sign(message, secret);
+      const key = await subtle.importKey(
+        "raw",
+        ed25519.getPublicKey(secret),
+        { name: "Ed25519" },
+        false,
+        ["verify"],
+      );
+      const forged = signature.slice();
+      forged[0] ^= 1;
+      return (
+        (await subtle.verify("Ed25519", key, signature, message)) &&
+        !(await subtle.verify("Ed25519", key, forged, message))
+      );
+    } catch {
+      return false;
+    }
+  })();
+  return ed25519Native;
+}
+
+async function verifySignatureAsync(
+  key: PublicKeyMsg,
+  payload: Uint8Array,
+  sig: Uint8Array,
+): Promise<boolean> {
+  if (key.algorithm !== ALG_ED25519 || !subtle || !(await nativeEd25519()))
+    return verifySignature(key, payload, sig);
+  if (key.key.length !== 32 || sig.length !== 64) return false;
+  try {
+    const imported = await subtle.importKey("raw", key.key, { name: "Ed25519" }, false, ["verify"]);
+    return await subtle.verify("Ed25519", imported, sig, payload);
+  } catch {
+    return false;
+  }
+}
+
+async function publicKeyFromSecretAsync(secret: Uint8Array, algorithm: number): Promise<Uint8Array> {
+  if (algorithm !== ALG_ED25519 || secret.length !== 32 || !subtle || !(await nativeEd25519()))
+    return publicKeyFromSecret(secret, algorithm);
+  try {
+    const pkcs8 = new Uint8Array(PKCS8_ED25519.length + 32);
+    pkcs8.set(PKCS8_ED25519);
+    pkcs8.set(secret, PKCS8_ED25519.length);
+    const key = await subtle.importKey("pkcs8", pkcs8, { name: "Ed25519" }, true, ["sign"]);
+    const { x } = await subtle.exportKey("jwk", key);
+    if (x === undefined) return publicKeyFromSecret(secret, algorithm);
+    return fromBase64(x);
+  } catch {
+    return publicKeyFromSecret(secret, algorithm);
   }
 }