@intentius/chant 0.124.62 → 0.124.64

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 (262) hide show
  1. package/dist/cli/handlers/approve.d.ts +26 -0
  2. package/dist/cli/handlers/approve.d.ts.map +1 -1
  3. package/dist/cli/handlers/approve.js +167 -18
  4. package/dist/cli/handlers/plan.d.ts +10 -0
  5. package/dist/cli/handlers/plan.d.ts.map +1 -0
  6. package/dist/cli/handlers/plan.js +71 -0
  7. package/dist/cli/handlers/pr.d.ts.map +1 -1
  8. package/dist/cli/handlers/pr.js +2 -1
  9. package/dist/cli/handlers/release.d.ts +11 -7
  10. package/dist/cli/handlers/release.d.ts.map +1 -1
  11. package/dist/cli/handlers/release.js +93 -20
  12. package/dist/cli/main.d.ts.map +1 -1
  13. package/dist/cli/main.js +48 -7
  14. package/dist/cli/mcp/workspace-tools.d.ts.map +1 -1
  15. package/dist/cli/mcp/workspace-tools.js +2 -1
  16. package/dist/cli/parse-args.d.ts.map +1 -1
  17. package/dist/cli/parse-args.js +43 -0
  18. package/dist/cli/registry.d.ts +18 -2
  19. package/dist/cli/registry.d.ts.map +1 -1
  20. package/dist/config.d.ts +50 -0
  21. package/dist/config.d.ts.map +1 -1
  22. package/dist/config.js +1 -0
  23. package/dist/gate-decision.d.ts +1 -1
  24. package/dist/gate-decision.d.ts.map +1 -1
  25. package/dist/gate-decision.js +4 -2
  26. package/dist/gate-statement.schema.json +46 -0
  27. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts +20 -0
  28. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts.map +1 -1
  29. package/dist/lifecycle/__fixtures__/publish-fakes.js +119 -3
  30. package/dist/lifecycle/gate-ledger.d.ts +28 -5
  31. package/dist/lifecycle/gate-ledger.d.ts.map +1 -1
  32. package/dist/lifecycle/gate-ledger.js +6 -0
  33. package/dist/lifecycle/gate-seal.d.ts +59 -7
  34. package/dist/lifecycle/gate-seal.d.ts.map +1 -1
  35. package/dist/lifecycle/gate-seal.js +68 -15
  36. package/dist/lifecycle/gate-statement.d.ts +95 -0
  37. package/dist/lifecycle/gate-statement.d.ts.map +1 -0
  38. package/dist/lifecycle/gate-statement.js +110 -0
  39. package/dist/lifecycle/gate-webauthn.d.ts +79 -0
  40. package/dist/lifecycle/gate-webauthn.d.ts.map +1 -0
  41. package/dist/lifecycle/gate-webauthn.js +105 -0
  42. package/dist/lifecycle/git.d.ts +1 -1
  43. package/dist/lifecycle/git.d.ts.map +1 -1
  44. package/dist/lifecycle/git.js +24 -19
  45. package/dist/lifecycle/ledger-remote.d.ts +37 -0
  46. package/dist/lifecycle/ledger-remote.d.ts.map +1 -0
  47. package/dist/lifecycle/ledger-remote.js +42 -0
  48. package/dist/lifecycle/plan-stale.d.ts +76 -0
  49. package/dist/lifecycle/plan-stale.d.ts.map +1 -0
  50. package/dist/lifecycle/plan-stale.js +120 -0
  51. package/dist/lifecycle/publish-credentials.d.ts +1 -1
  52. package/dist/lifecycle/publish-credentials.d.ts.map +1 -1
  53. package/dist/lifecycle/publish-credentials.js +2 -0
  54. package/dist/lifecycle/publish-declaration.d.ts +107 -0
  55. package/dist/lifecycle/publish-declaration.d.ts.map +1 -1
  56. package/dist/lifecycle/publish-declaration.js +110 -1
  57. package/dist/lifecycle/publish-forge.d.ts +5 -1
  58. package/dist/lifecycle/publish-forge.d.ts.map +1 -1
  59. package/dist/lifecycle/publish-forge.js +13 -4
  60. package/dist/lifecycle/publish-git-ssh.d.ts +82 -0
  61. package/dist/lifecycle/publish-git-ssh.d.ts.map +1 -0
  62. package/dist/lifecycle/publish-git-ssh.js +180 -0
  63. package/dist/lifecycle/publish-github.d.ts +69 -0
  64. package/dist/lifecycle/publish-github.d.ts.map +1 -0
  65. package/dist/lifecycle/publish-github.js +153 -0
  66. package/dist/lifecycle/publish-homebrew.d.ts +77 -0
  67. package/dist/lifecycle/publish-homebrew.d.ts.map +1 -0
  68. package/dist/lifecycle/publish-homebrew.js +265 -0
  69. package/dist/lifecycle/publish-marketplace.d.ts +85 -0
  70. package/dist/lifecycle/publish-marketplace.d.ts.map +1 -0
  71. package/dist/lifecycle/publish-marketplace.js +398 -0
  72. package/dist/lifecycle/publish-targets.d.ts +6 -0
  73. package/dist/lifecycle/publish-targets.d.ts.map +1 -1
  74. package/dist/lifecycle/publish-targets.js +15 -0
  75. package/dist/lifecycle/publish-tauri.d.ts +61 -0
  76. package/dist/lifecycle/publish-tauri.d.ts.map +1 -0
  77. package/dist/lifecycle/publish-tauri.js +181 -0
  78. package/dist/lifecycle/release-cut.d.ts +51 -5
  79. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  80. package/dist/lifecycle/release-cut.js +165 -16
  81. package/dist/lifecycle/release-publish.d.ts +18 -2
  82. package/dist/lifecycle/release-publish.d.ts.map +1 -1
  83. package/dist/lifecycle/release-publish.js +5 -0
  84. package/dist/lifecycle/release-revocation.d.ts +4 -3
  85. package/dist/lifecycle/release-revocation.d.ts.map +1 -1
  86. package/dist/lifecycle/release-revocation.js +5 -4
  87. package/dist/lifecycle/release-store.d.ts +32 -0
  88. package/dist/lifecycle/release-store.d.ts.map +1 -1
  89. package/dist/lifecycle/release-store.js +11 -0
  90. package/dist/lifecycle/snapshot-store.d.ts.map +1 -1
  91. package/dist/lifecycle/snapshot-store.js +17 -9
  92. package/dist/lifecycle/test-passkey.d.ts +25 -0
  93. package/dist/lifecycle/test-passkey.d.ts.map +1 -0
  94. package/dist/lifecycle/test-passkey.js +39 -0
  95. package/dist/notify.d.ts +23 -3
  96. package/dist/notify.d.ts.map +1 -1
  97. package/dist/notify.js +8 -2
  98. package/dist/notify.schema.json +12 -3
  99. package/dist/op/gate.d.ts +1 -1
  100. package/dist/op/gate.d.ts.map +1 -1
  101. package/dist/op/gate.js +2 -1
  102. package/dist/pr-forge.d.ts +20 -0
  103. package/dist/pr-forge.d.ts.map +1 -1
  104. package/dist/pr-forge.js +87 -8
  105. package/dist/release-floors.d.ts +1 -1
  106. package/dist/release-floors.js +1 -1
  107. package/dist/wave-runtime.mjs +333 -331
  108. package/dist/workspace/ci-builds.d.ts +21 -0
  109. package/dist/workspace/ci-builds.d.ts.map +1 -1
  110. package/dist/workspace/ci-builds.js +14 -0
  111. package/dist/workspace/ci-green.d.ts +45 -2
  112. package/dist/workspace/ci-green.d.ts.map +1 -1
  113. package/dist/workspace/ci-green.js +123 -5
  114. package/dist/workspace/ci-quarantine-report.d.ts +80 -0
  115. package/dist/workspace/ci-quarantine-report.d.ts.map +1 -0
  116. package/dist/workspace/ci-quarantine-report.js +204 -0
  117. package/dist/workspace/ci-quarantine.d.ts +73 -0
  118. package/dist/workspace/ci-quarantine.d.ts.map +1 -0
  119. package/dist/workspace/ci-quarantine.js +170 -0
  120. package/dist/workspace/ci-serve.d.ts.map +1 -1
  121. package/dist/workspace/ci-serve.js +7 -4
  122. package/dist/workspace/class-data.d.ts +3 -1
  123. package/dist/workspace/class-data.d.ts.map +1 -1
  124. package/dist/workspace/class-data.js +4 -1
  125. package/dist/workspace/declaration.d.ts +45 -2
  126. package/dist/workspace/declaration.d.ts.map +1 -1
  127. package/dist/workspace/declaration.js +45 -2
  128. package/dist/workspace/declaration.schema.json +51 -3
  129. package/dist/workspace/forge-work.d.ts +76 -0
  130. package/dist/workspace/forge-work.d.ts.map +1 -0
  131. package/dist/workspace/forge-work.js +160 -0
  132. package/dist/workspace/identity-gate-rule.d.ts +3 -2
  133. package/dist/workspace/identity-gate-rule.d.ts.map +1 -1
  134. package/dist/workspace/identity-gate-rule.js +5 -7
  135. package/dist/workspace/identity.d.ts +3 -2
  136. package/dist/workspace/identity.d.ts.map +1 -1
  137. package/dist/workspace/identity.js +6 -3
  138. package/dist/workspace/intent-cli.d.ts +3 -2
  139. package/dist/workspace/intent-cli.d.ts.map +1 -1
  140. package/dist/workspace/intent-cli.js +26 -5
  141. package/dist/workspace/intent-record.d.ts +3 -0
  142. package/dist/workspace/intent-record.d.ts.map +1 -1
  143. package/dist/workspace/intent-record.schema.json +32 -0
  144. package/dist/workspace/intent.d.ts +9 -0
  145. package/dist/workspace/intent.d.ts.map +1 -1
  146. package/dist/workspace/intent.js +2 -0
  147. package/dist/workspace/intent.schema.json +32 -0
  148. package/dist/workspace/kind-readers.d.ts.map +1 -1
  149. package/dist/workspace/kind-readers.js +2 -1
  150. package/dist/workspace/kinds.d.ts +6 -1
  151. package/dist/workspace/kinds.d.ts.map +1 -1
  152. package/dist/workspace/kinds.js +8 -3
  153. package/dist/workspace/plan-stale.schema.json +286 -0
  154. package/dist/workspace/release-candidates.d.ts +42 -7
  155. package/dist/workspace/release-candidates.d.ts.map +1 -1
  156. package/dist/workspace/release-candidates.js +64 -23
  157. package/dist/workspace/release-candidates.schema.json +55 -2
  158. package/dist/workspace/releases.schema.json +47 -0
  159. package/dist/workspace/trust/policy.d.ts +10 -0
  160. package/dist/workspace/trust/policy.d.ts.map +1 -1
  161. package/dist/workspace/trust/policy.js +19 -1
  162. package/dist/workspace/trust/run-commits.d.ts.map +1 -1
  163. package/dist/workspace/trust/run-commits.js +2 -1
  164. package/dist/workspace/trust/seal.d.ts.map +1 -1
  165. package/dist/workspace/trust/seal.js +34 -3
  166. package/dist/workspace/trust/trust-files.d.ts.map +1 -1
  167. package/dist/workspace/trust/trust-files.js +6 -1
  168. package/package.json +2 -1
  169. package/src/cli/handlers/approve-external-signature.test.ts +328 -0
  170. package/src/cli/handlers/approve.ts +206 -18
  171. package/src/cli/handlers/plan.ts +74 -0
  172. package/src/cli/handlers/pr.ts +2 -1
  173. package/src/cli/handlers/release.ts +84 -20
  174. package/src/cli/main.ts +48 -7
  175. package/src/cli/mcp/workspace-tools.ts +2 -1
  176. package/src/cli/parse-args.ts +33 -0
  177. package/src/cli/registry.ts +18 -2
  178. package/src/config.ts +8 -0
  179. package/src/gate-decision-bundle.test.ts +4 -2
  180. package/src/gate-decision.ts +11 -2
  181. package/src/gate-statement.schema.json +46 -0
  182. package/src/lifecycle/__fixtures__/publish-fakes.ts +125 -5
  183. package/src/lifecycle/gate-ledger.ts +34 -5
  184. package/src/lifecycle/gate-seal.ts +86 -15
  185. package/src/lifecycle/gate-statement.ts +144 -0
  186. package/src/lifecycle/gate-webauthn.test.ts +77 -0
  187. package/src/lifecycle/gate-webauthn.ts +133 -0
  188. package/src/lifecycle/git.ts +23 -19
  189. package/src/lifecycle/ledger-remote.test.ts +183 -0
  190. package/src/lifecycle/ledger-remote.ts +46 -0
  191. package/src/lifecycle/plan-stale.test.ts +149 -0
  192. package/src/lifecycle/plan-stale.ts +172 -0
  193. package/src/lifecycle/publish-credentials.ts +2 -0
  194. package/src/lifecycle/publish-declaration.ts +116 -1
  195. package/src/lifecycle/publish-forge.ts +14 -4
  196. package/src/lifecycle/publish-git-ssh.ts +202 -0
  197. package/src/lifecycle/publish-github.ts +174 -0
  198. package/src/lifecycle/publish-homebrew.test.ts +358 -0
  199. package/src/lifecycle/publish-homebrew.ts +283 -0
  200. package/src/lifecycle/publish-marketplace.test.ts +406 -0
  201. package/src/lifecycle/publish-marketplace.ts +421 -0
  202. package/src/lifecycle/publish-resume.test.ts +40 -0
  203. package/src/lifecycle/publish-target-context.test.ts +2 -2
  204. package/src/lifecycle/publish-targets.test.ts +23 -0
  205. package/src/lifecycle/publish-targets.ts +15 -0
  206. package/src/lifecycle/publish-tauri.test.ts +163 -0
  207. package/src/lifecycle/publish-tauri.ts +198 -0
  208. package/src/lifecycle/release-cut-lane.test.ts +177 -0
  209. package/src/lifecycle/release-cut-override.test.ts +213 -0
  210. package/src/lifecycle/release-cut.ts +198 -17
  211. package/src/lifecycle/release-publish.ts +23 -3
  212. package/src/lifecycle/release-revocation.ts +5 -4
  213. package/src/lifecycle/release-store.ts +44 -0
  214. package/src/lifecycle/snapshot-store.ts +16 -9
  215. package/src/lifecycle/test-passkey.ts +55 -0
  216. package/src/notify-bundle.test.ts +3 -1
  217. package/src/notify.schema.json +12 -3
  218. package/src/notify.ts +20 -3
  219. package/src/op/gate.ts +2 -1
  220. package/src/override-gate-bundle.test.ts +2 -0
  221. package/src/pr-forge-bundle.test.ts +2 -2
  222. package/src/pr-forge.test.ts +38 -0
  223. package/src/pr-forge.ts +93 -11
  224. package/src/pr-requires.test.ts +9 -0
  225. package/src/release-floors.ts +1 -1
  226. package/src/stage-hooks-bundle.test.ts +2 -0
  227. package/src/wave-runtime-bundle.test.ts +3 -2
  228. package/src/workspace/ci-builds.ts +27 -0
  229. package/src/workspace/ci-green-stale.test.ts +193 -0
  230. package/src/workspace/ci-green.ts +137 -6
  231. package/src/workspace/ci-quarantine-report.test.ts +145 -0
  232. package/src/workspace/ci-quarantine-report.ts +234 -0
  233. package/src/workspace/ci-quarantine.test.ts +160 -0
  234. package/src/workspace/ci-quarantine.ts +188 -0
  235. package/src/workspace/ci-serve.ts +7 -4
  236. package/src/workspace/class-data.ts +5 -1
  237. package/src/workspace/declaration.schema.json +51 -3
  238. package/src/workspace/declaration.test.ts +1 -0
  239. package/src/workspace/declaration.ts +88 -5
  240. package/src/workspace/forge-work.test.ts +143 -0
  241. package/src/workspace/forge-work.ts +195 -0
  242. package/src/workspace/identity-gate-rule.ts +6 -8
  243. package/src/workspace/identity.ts +6 -3
  244. package/src/workspace/intent-cli.ts +24 -5
  245. package/src/workspace/intent-record.schema.json +32 -0
  246. package/src/workspace/intent-record.ts +3 -0
  247. package/src/workspace/intent.schema.json +32 -0
  248. package/src/workspace/intent.ts +9 -0
  249. package/src/workspace/kind-readers.ts +2 -1
  250. package/src/workspace/kinds.test.ts +13 -0
  251. package/src/workspace/kinds.ts +12 -3
  252. package/src/workspace/plan-stale.schema.json +286 -0
  253. package/src/workspace/release-candidates.schema.json +55 -2
  254. package/src/workspace/release-candidates.test.ts +77 -4
  255. package/src/workspace/release-candidates.ts +80 -23
  256. package/src/workspace/releases.schema.json +47 -0
  257. package/src/workspace/trust/gate-seal.test.ts +44 -0
  258. package/src/workspace/trust/policy.ts +24 -1
  259. package/src/workspace/trust/run-commits.ts +2 -1
  260. package/src/workspace/trust/seal.ts +35 -3
  261. package/src/workspace/trust/trust-files.test.ts +5 -0
  262. package/src/workspace/trust/trust-files.ts +15 -1
@@ -161,6 +161,14 @@ export interface GateResolutionRecord {
161
161
  * resumes (`resume: true`) whose run stored a checkpoint. A seal covers it.
162
162
  */
163
163
  checkpointDigest?: string;
164
+ /**
165
+ * The line the relay set for the approver's signature to bind as well
166
+ * (#4697, `chant approve --binding`), such as a platform's deploy id and
167
+ * an expiry. Printable text on one line; chant reads nothing in it. Set
168
+ * only on an approval signed with --sign or --signature, whose seal (version
169
+ * 3) signs it.
170
+ */
171
+ binding?: string;
164
172
  /**
165
173
  * The environment this approval is for (#2574), copied off the pending fact
166
174
  * it answers. Set for a component gate, whose ledger is keyed by component
@@ -242,8 +250,10 @@ export interface GateResolutionRecord {
242
250
  /**
243
251
  * An ssh signature over this approval by `resolvedBy` (#3163, ws-080):
244
252
  * `chant approve --sign`, in the `chant-gate` namespace over the op, gate,
245
- * environment, plan digest, approver and timestamp. It attests the approver
246
- * only when the signers file at base lists a key for them. A gate the
253
+ * environment, plan digest, approver and timestamp. Or the same made
254
+ * elsewhere, by an ssh key or a passkey, and brought with `chant approve
255
+ * --signature` (#4646). It attests the approver only when the signers file
256
+ * at base lists a key for them, or `.chant/trust.json` a passkey. A gate the
247
257
  * declaration's `identity.gates` names counts only approvals whose seal
248
258
  * verifies. Absent on an unsigned approval.
249
259
  */
@@ -291,17 +301,30 @@ export function isGateCarriedFrom(raw: unknown): raw is GateCarriedFrom {
291
301
  );
292
302
  }
293
303
 
294
- /** A gate approval's seal (#3163): who signed, the key's fingerprint (reported, never trusted), and the armored signature. */
304
+ /**
305
+ * A gate approval's seal (#3163): who signed, the key's fingerprint (reported,
306
+ * never trusted), and the armored signature. A passkey's seal (#4646) has
307
+ * `kind: "webauthn"`, the credential id as `key`, the assertion's signature
308
+ * (base64url) as `signature`, and its client data and authenticator data, so
309
+ * it can be checked again against the passkey `.chant/trust.json` lists.
310
+ */
295
311
  export interface GateApprovalSeal {
312
+ /** `webauthn` for a passkey's assertion (#4646). Absent on an ssh signature. */
313
+ kind?: "webauthn";
296
314
  signer: string;
297
315
  key: string;
298
316
  signature: string;
317
+ /** A passkey's clientDataJSON, base64url (#4646). */
318
+ clientDataJSON?: string;
319
+ /** A passkey's authenticatorData, base64url (#4646). */
320
+ authenticatorData?: string;
299
321
  /**
300
322
  * The seal's version (#3947). `2` on a seal over an approval that carries a
301
323
  * `checkpointDigest`, whose payload signs the digest as one more line.
302
- * Absent on every other seal, which is version 1.
324
+ * `3` on a seal over an approval with a `binding` (#4697), which signs one
325
+ * more line after that. Absent on every other seal, which is version 1.
303
326
  */
304
- version?: 2;
327
+ version?: 2 | 3;
305
328
  }
306
329
 
307
330
  export type GateResolutionInput = Omit<GateResolutionRecord, "version" | "kind">;
@@ -624,6 +647,12 @@ export function parseGateLedger(
624
647
  malformed++;
625
648
  continue;
626
649
  }
650
+ // #4697: and for the binding a seal signs. A line break would make the statement's lines ambiguous.
651
+ const rawBinding: unknown = (parsed as { binding?: unknown }).binding;
652
+ if (rawBinding !== undefined && (typeof rawBinding !== "string" || /[\r\n\u2028\u2029]/.test(rawBinding))) {
653
+ malformed++;
654
+ continue;
655
+ }
627
656
  // #4020: a commit or run id of the wrong type is dropped, so a reader can trust the type without losing the line.
628
657
  // #4551: and so is a `changeSet` that is not a digest.
629
658
  for (const key of ["gitSha", "runId", "changeSet"] as const) {
@@ -20,6 +20,9 @@
20
20
 
21
21
  import { createHash, createPublicKey, verify, type KeyObject } from "node:crypto";
22
22
  import type { Signer } from "../workspace/trust/trust-files";
23
+ import { verifyWebAuthnAssertion, type PasskeySigner } from "./gate-webauthn";
24
+
25
+ export { isWebAuthnAssertion, passkeyPublicKey, verifyWebAuthnAssertion, webAuthnChallenge, type PasskeySigner, type WebAuthnAssertion, type WebAuthnCheck } from "./gate-webauthn";
23
26
 
24
27
  /**
25
28
  * The ssh signature namespace of a gate approval's seal (#3163, ws-080), so a
@@ -39,6 +42,12 @@ export interface SealedGateApproval {
39
42
  timestamp: string;
40
43
  /** The checkpoint the approval lets a run resume from (#3947), when it carries one. */
41
44
  checkpointDigest?: string;
45
+ /**
46
+ * A line the relay set for the signature to bind as well (#4697), such as
47
+ * a platform's deploy id and an expiry. chant doesn't read it; the seal
48
+ * signs it. A carried approval keeps the original's.
49
+ */
50
+ binding?: string;
42
51
  /** The line a carried approval came from (#3949): the names and time its seal was made under. */
43
52
  carriedFrom?: { op: string; gate: string; timestamp: string; checkpointDigest?: string };
44
53
  seal?: unknown;
@@ -64,11 +73,14 @@ export function sealedFieldsOf(a: SealedGateApproval): SealedGateApproval {
64
73
  }
65
74
 
66
75
  /**
67
- * The version of a seal over `a` (#3947): 2 when the approval carries a
68
- * checkpoint digest, which the payload signs, and 1 otherwise. `chant approve
69
- * --sign` records 2 on the seal; a seal records no version for 1.
76
+ * The version of a seal over `a` (#3947): 3 when the approval carries a
77
+ * relay's binding (#4697), 2 when it carries a checkpoint digest and no
78
+ * binding, and 1 otherwise. Each signs the lines of the one before plus its
79
+ * own. `chant approve --sign` and `--signature` record 2 and 3 on the seal; a
80
+ * seal records no version for 1.
70
81
  */
71
- export function gateSealVersion(a: Pick<SealedGateApproval, "checkpointDigest" | "carriedFrom">): 1 | 2 {
82
+ export function gateSealVersion(a: Pick<SealedGateApproval, "checkpointDigest" | "carriedFrom" | "binding">): 1 | 2 | 3 {
83
+ if (a.binding !== undefined) return 3;
72
84
  const checkpoint = a.carriedFrom !== undefined ? a.carriedFrom.checkpointDigest : a.checkpointDigest;
73
85
  return checkpoint !== undefined ? 2 : 1;
74
86
  }
@@ -88,14 +100,23 @@ export function gateSealVersion(a: Pick<SealedGateApproval, "checkpointDigest" |
88
100
  * then covered by the seal too, and removing or swapping the digest stops it
89
101
  * verifying. An approval with none signs what a version 1 seal signed.
90
102
  *
103
+ * Seal version 3 (#4697) adds a binding line the relay set, `binding
104
+ * <text>`, after everything else, checkpoint included. A platform puts what
105
+ * it needs the person's signature to cover there too (a deploy id and an
106
+ * expiry); chant records and checks it and reads nothing in it. An approval
107
+ * with no binding signs what a version 1 or 2 seal signed, so those still
108
+ * verify, and an older chant, which leaves the line out, finds a version 3
109
+ * seal doesn't verify and counts nothing for it.
110
+ *
91
111
  * A carried approval (#3949) signs what the line it came from signed: see
92
112
  * {@link sealedFieldsOf}.
93
113
  */
94
114
  export function gateSealPayload(approval: SealedGateApproval): Buffer {
95
115
  const a = sealedFieldsOf(approval);
96
116
  const relay = a.relayedBy !== undefined ? `\nrelayed-by ${a.relayedBy}` : "";
97
- const checkpoint = gateSealVersion(a) === 2 ? `\ncheckpoint ${a.checkpointDigest}` : "";
98
- return Buffer.from(`${a.op}\n${a.gate}\n${a.environment ?? ""}\n${a.planDigest ?? ""}\n${a.resolvedBy}\n${a.timestamp}${relay}${checkpoint}`, "utf-8");
117
+ const checkpoint = a.checkpointDigest !== undefined ? `\ncheckpoint ${a.checkpointDigest}` : "";
118
+ const binding = a.binding !== undefined ? `\nbinding ${a.binding}` : "";
119
+ return Buffer.from(`${a.op}\n${a.gate}\n${a.environment ?? ""}\n${a.planDigest ?? ""}\n${a.resolvedBy}\n${a.timestamp}${relay}${checkpoint}${binding}`, "utf-8");
99
120
  }
100
121
 
101
122
  // ── SSHSIG ───────────────────────────────────────────────────────────────
@@ -248,6 +269,8 @@ export interface GateSigners {
248
269
  /** Whether a signers file exists at base. False: no seal verifies, so a sealed gate passes nothing. */
249
270
  active: boolean;
250
271
  signers: Signer[];
272
+ /** The passkeys `.chant/trust.json` lists at base (#4646). Absent: none. */
273
+ passkeys?: PasskeySigner[];
251
274
  /** Why the trust config could not be read, when it could not. `active` is false then. */
252
275
  problems: string[];
253
276
  }
@@ -269,12 +292,53 @@ export function namespaceAllowed(list: string | undefined, namespace: string): b
269
292
  return allowed;
270
293
  }
271
294
 
295
+ /** The seal kind of an approval signed with a passkey (#4646). A seal with no `kind` is an ssh signature. */
296
+ export const WEBAUTHN_SEAL_KIND = "webauthn";
297
+
298
+ /** What {@link checkGateSignature} reads: the ssh signers and the passkeys at base. */
299
+ export interface GateSignerKeys {
300
+ signers: readonly Signer[];
301
+ passkeys?: readonly PasskeySigner[];
302
+ }
303
+
304
+ /** What {@link checkGateSignature} found. `unlisted`: nothing at base is listed for the principal. */
305
+ export type GateSignatureCheck = { ok: true; key: string } | { ok: false; unlisted: boolean; reason: string };
306
+
307
+ /**
308
+ * Whether `seal`'s signature over `payload` verifies for `principal` with a
309
+ * key listed for them at base (#4646): an ssh signature in the `chant-gate`
310
+ * namespace against the signers file's keys, or, for a seal of kind
311
+ * `webauthn`, an assertion against the passkeys `.chant/trust.json` lists.
312
+ * The one check `chant approve`, the `identity.gates` rule, a sealed gate and
313
+ * `checkGateSeal` all make. Never throws.
314
+ */
315
+ export function checkGateSignature(keys: GateSignerKeys, principal: string, seal: { signature: string } & Record<string, unknown>, payload: Buffer): GateSignatureCheck {
316
+ const name = normalise(principal);
317
+ if (seal.kind === WEBAUTHN_SEAL_KIND) {
318
+ const passkeys = (keys.passkeys ?? []).filter((p) => normalise(p.principal) === name);
319
+ if (passkeys.length === 0) return { ok: false, unlisted: true, reason: `${principal} has no passkey in .chant/trust.json at base` };
320
+ const assertion = { id: seal.key, clientDataJSON: seal.clientDataJSON, authenticatorData: seal.authenticatorData, signature: seal.signature };
321
+ if (typeof assertion.id !== "string" || typeof assertion.clientDataJSON !== "string" || typeof assertion.authenticatorData !== "string") {
322
+ return { ok: false, unlisted: false, reason: "a webauthn seal needs key (the credential id), clientDataJSON and authenticatorData" };
323
+ }
324
+ const r = verifyWebAuthnAssertion(assertion as { id: string; clientDataJSON: string; authenticatorData: string; signature: string }, payload, passkeys);
325
+ return r.ok ? r : { ok: false, unlisted: false, reason: r.reason };
326
+ }
327
+ if (seal.kind !== undefined) return { ok: false, unlisted: false, reason: `a seal of kind ${JSON.stringify(seal.kind)} is not one this chant reads` };
328
+ const listed = keys.signers.filter((s) => normalise(s.principal) === name);
329
+ if (listed.length === 0) return { ok: false, unlisted: true, reason: `${principal} has no key in the signers file at base` };
330
+ const blobs = listed.filter((s) => namespaceAllowed(s.namespaces, GATE_SEAL_NAMESPACE)).map((s) => Buffer.from(s.key.split(" ")[1] ?? "", "base64"));
331
+ const r = verifySshSignatureWith(seal.signature, payload, GATE_SEAL_NAMESPACE, blobs);
332
+ return r.ok ? r : { ok: false, unlisted: false, reason: r.reason };
333
+ }
334
+
272
335
  /**
273
336
  * Why this approval does not count toward a sealed gate, or null when it
274
337
  * does: its seal verifies, for the approver it names, against a key `signers`
275
- * lists for that approver in the `chant-gate` namespace. With no signers file
276
- * at base, nothing counts. The same rule as `sealedApprovalRule` in
277
- * `../../op/gate-review.ts`, which checks with ssh-keygen.
338
+ * lists for that approver in the `chant-gate` namespace, or a passkey
339
+ * `.chant/trust.json` lists for them (#4646). With no signers file at base,
340
+ * nothing counts. The same rule as `sealedApprovalRule` in
341
+ * `../../op/gate-review.ts`.
278
342
  */
279
343
  export function gateSealRefusal(signers: GateSigners, a: SealedGateApproval): string | null {
280
344
  const where = `${signers.signersPath} at base`;
@@ -289,10 +353,17 @@ export function gateSealRefusal(signers: GateSigners, a: SealedGateApproval): st
289
353
  return `the seal on ${what} is malformed: it needs signer and signature`;
290
354
  }
291
355
  if (normalise(seal.signer) !== normalise(a.resolvedBy)) return `the seal on ${what} is by ${seal.signer}, and its approver is ${a.resolvedBy || "empty"}`;
292
- const keys = signers.signers
293
- .filter((s) => normalise(s.principal) === normalise(a.resolvedBy) && namespaceAllowed(s.namespaces, GATE_SEAL_NAMESPACE))
294
- .map((s) => Buffer.from(s.key.split(" ")[1] ?? "", "base64"));
295
- if (keys.length === 0) return `${a.resolvedBy} has no key in ${where}, so the seal can't count`;
296
- const r = verifySshSignatureWith(seal.signature, gateSealPayload(a), GATE_SEAL_NAMESPACE, keys);
297
- return r.ok ? null : `the seal does not verify for ${a.resolvedBy} against ${where}: ${r.reason}`;
356
+ const r = checkGateSignature(signers, a.resolvedBy, seal as { signature: string }, gateSealPayload(a));
357
+ if (r.ok) return null;
358
+ return r.unlisted ? `${a.resolvedBy} has no ${unlistedWhat(seal)} in ${unlistedWhere(seal, where)}, so the seal can't count` : `the seal does not verify for ${a.resolvedBy} against ${where}: ${r.reason}`;
359
+ }
360
+
361
+ /** "key" or "passkey", for a refusal that names what is missing for a seal's kind. */
362
+ export function unlistedWhat(seal: object): string {
363
+ return (seal as { kind?: unknown }).kind === WEBAUTHN_SEAL_KIND ? "passkey" : "key";
364
+ }
365
+
366
+ /** Where the missing key would be listed: the signers file, or `.chant/trust.json` for a passkey. */
367
+ export function unlistedWhere(seal: object, signersWhere: string): string {
368
+ return (seal as { kind?: unknown }).kind === WEBAUTHN_SEAL_KIND ? ".chant/trust.json at base" : signersWhere;
298
369
  }
@@ -0,0 +1,144 @@
1
+ /**
2
+ * A gate approval's statement, for a signature made outside chant (#4646).
3
+ *
4
+ * `chant approve --sign` signs `gateSealPayload`'s bytes with an ssh key on
5
+ * the machine running chant. A platform that collects the approval somewhere
6
+ * else (a phone with a passkey, a device key on another machine) needs the
7
+ * same bytes before anything is recorded: `chant approve <op> <gate>
8
+ * --statement` prints them as a `chant-gate-statement/v1` document
9
+ * (`../gate-statement.schema.json`), with the time fixed so the signature and
10
+ * the approval that records it cover the same line. The platform has the
11
+ * person sign them and hands the signature to `chant approve --signature`,
12
+ * with the same `--actor`, `--relayed-by` and `--at`.
13
+ *
14
+ * The relay can add a line of its own for the signature to bind, `--binding
15
+ * <text>` on both calls (#4697): a platform's deploy id and an expiry, say.
16
+ * It is signed last as `binding <text>` (seal version 3) and kept on the
17
+ * approval, and chant checks only that it is one line of printable text no
18
+ * longer than {@link GATE_BINDING_MAX_BYTES}.
19
+ */
20
+
21
+ import { createHash } from "node:crypto";
22
+ import { NEXT_RELEASE } from "../release-floors";
23
+ import { GATE_SEAL_NAMESPACE, gateSealPayload, gateSealVersion, isWebAuthnAssertion, webAuthnChallenge, type SealedGateApproval, type WebAuthnAssertion } from "./gate-seal";
24
+
25
+ /**
26
+ * The first chant that prints a gate's statement, records an approval
27
+ * signed elsewhere (`chant approve --signature`), reads `passkeys` in
28
+ * `.chant/trust.json` and verifies a seal of kind `webauthn` (#4646). An
29
+ * older chant reads a trust.json with `passkeys` as invalid, which turns
30
+ * attestation off, and counts no passkey seal toward a gate.
31
+ */
32
+ export const GATE_EXTERNAL_SIGNATURE_FLOOR = "0.124.63";
33
+
34
+ /**
35
+ * The first chant that takes `--binding` and signs and checks a binding line
36
+ * (seal version 3, #4697). An older chant leaves the line out of what it
37
+ * checks, so it finds a version 3 seal doesn't verify and counts nothing for
38
+ * it, whatever the gate.
39
+ */
40
+ export const GATE_BINDING_FLOOR = NEXT_RELEASE;
41
+
42
+ /** The longest binding `--binding` takes, in UTF-8 bytes (#4697). */
43
+ export const GATE_BINDING_MAX_BYTES = 512;
44
+
45
+ /**
46
+ * Why `text` can't be a gate statement's binding line (#4697), or null when
47
+ * it can: it must be non-empty, at most {@link GATE_BINDING_MAX_BYTES} UTF-8
48
+ * bytes, with no leading or trailing space, and printable on one line, so no
49
+ * control or format character (bidi overrides among them), line or paragraph
50
+ * separator, unassigned code point or lone surrogate.
51
+ */
52
+ export function gateBindingProblem(text: string): string | null {
53
+ if (text === "") return "it is empty";
54
+ const bytes = Buffer.byteLength(text, "utf-8");
55
+ if (bytes > GATE_BINDING_MAX_BYTES) return `it is ${bytes} bytes, and the most is ${GATE_BINDING_MAX_BYTES}`;
56
+ if (text.trim() !== text) return "it starts or ends with white space";
57
+ const bad = /[\p{C}\p{Zl}\p{Zp}]/u.exec(text);
58
+ if (bad) return `it holds U+${bad[0].codePointAt(0)!.toString(16).toUpperCase().padStart(4, "0")}, and it must be printable text on one line`;
59
+ return null;
60
+ }
61
+
62
+ export const GATE_STATEMENT_SCHEMA = "chant-gate-statement/v1";
63
+
64
+ /** The `$id` of `../gate-statement.schema.json`, which the package exports as `@intentius/chant/gate-statement.schema.json`. */
65
+ export const GATE_STATEMENT_SCHEMA_ID = "https://intentius.io/chant/schemas/gate-statement/v1/gate-statement.schema.json";
66
+
67
+ /** What `chant approve <op> <gate> --statement` prints. */
68
+ export interface GateStatement {
69
+ schema: typeof GATE_STATEMENT_SCHEMA;
70
+ chantVersion: string;
71
+ op: string;
72
+ gate: string;
73
+ environment: string | null;
74
+ planDigest: string | null;
75
+ resolvedBy: string;
76
+ relayedBy: string | null;
77
+ timestamp: string;
78
+ checkpointDigest: string | null;
79
+ /** The relay's binding line (#4697, `--binding`), or null. When set the statement ends with `binding <text>`. */
80
+ binding: string | null;
81
+ /** 3 when the statement signs a binding, else 2 when it signs a checkpoint digest, else 1. */
82
+ sealVersion: 1 | 2 | 3;
83
+ /** The ssh signature namespace an ssh key signs the statement in. */
84
+ namespace: typeof GATE_SEAL_NAMESPACE;
85
+ /** The statement's UTF-8 text, LF-joined with no final newline. */
86
+ text: string;
87
+ /** The same bytes, base64. */
88
+ statement: string;
89
+ /** `sha256:` and the bytes' SHA-256 in hex. */
90
+ digest: string;
91
+ /** The WebAuthn challenge: base64url of the bytes' SHA-256, no padding. */
92
+ challenge: string;
93
+ }
94
+
95
+ /** The statement of approval `a`, as `chant approve --statement` prints it. */
96
+ export function gateStatement(a: SealedGateApproval, chantVersion: string): GateStatement {
97
+ const bytes = gateSealPayload(a);
98
+ return {
99
+ schema: GATE_STATEMENT_SCHEMA,
100
+ chantVersion,
101
+ op: a.op,
102
+ gate: a.gate,
103
+ environment: a.environment ?? null,
104
+ planDigest: a.planDigest ?? null,
105
+ resolvedBy: a.resolvedBy,
106
+ relayedBy: a.relayedBy ?? null,
107
+ timestamp: a.timestamp,
108
+ checkpointDigest: a.checkpointDigest ?? null,
109
+ binding: a.binding ?? null,
110
+ sealVersion: gateSealVersion(a),
111
+ namespace: GATE_SEAL_NAMESPACE,
112
+ text: bytes.toString("utf-8"),
113
+ statement: bytes.toString("base64"),
114
+ digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
115
+ challenge: webAuthnChallenge(bytes),
116
+ };
117
+ }
118
+
119
+ /** A signature `chant approve --signature` was handed. */
120
+ export type ExternalSignature = { kind: "ssh"; signature: string } | { kind: "webauthn"; assertion: WebAuthnAssertion };
121
+
122
+ /**
123
+ * Read what `--signature` names: an armored ssh signature, or a WebAuthn
124
+ * assertion as JSON, either `{ id, clientDataJSON, authenticatorData,
125
+ * signature }` or a `PublicKeyCredential`'s `toJSON()` with those three
126
+ * under `response`. Returns a problem when it is neither.
127
+ */
128
+ export function readExternalSignature(text: string): ExternalSignature | { problem: string } {
129
+ const armored = /-----BEGIN SSH SIGNATURE-----[^-]*-----END SSH SIGNATURE-----/.exec(text);
130
+ if (armored) return { kind: "ssh", signature: `${armored[0]}\n` };
131
+ let raw: unknown;
132
+ try {
133
+ raw = JSON.parse(text);
134
+ } catch {
135
+ return { problem: "it is neither an armored ssh signature (-----BEGIN SSH SIGNATURE-----) nor a WebAuthn assertion in JSON" };
136
+ }
137
+ const o = raw as { id?: unknown; response?: Record<string, unknown> } | null;
138
+ const flat = o && typeof o === "object" && o.response && typeof o.response === "object" ? { id: o.id, ...o.response } : raw;
139
+ if (!isWebAuthnAssertion(flat)) {
140
+ return { problem: "a WebAuthn assertion needs id, clientDataJSON, authenticatorData and signature, each base64url" };
141
+ }
142
+ const { id, clientDataJSON, authenticatorData, signature } = flat;
143
+ return { kind: "webauthn", assertion: { id, clientDataJSON, authenticatorData, signature } };
144
+ }
@@ -0,0 +1,77 @@
1
+ /**
2
+ * #4646: a passkey's assertion over a gate's statement, checked with
3
+ * node:crypto. Each assertion is built by hand the way an authenticator
4
+ * builds one: client data, authenticator data, and a signature over
5
+ * authenticatorData || SHA-256(clientDataJSON).
6
+ */
7
+
8
+ import { describe, expect, test } from "vitest";
9
+ import { gateSealPayload, gateSealRefusal, type GateSigners, type SealedGateApproval } from "./gate-seal";
10
+ import { verifyWebAuthnAssertion, webAuthnChallenge, type WebAuthnAssertion } from "./gate-webauthn";
11
+ import { assert, passkey } from "./test-passkey";
12
+ import { readExternalSignature } from "./gate-statement";
13
+
14
+ const approval: SealedGateApproval = {
15
+ op: "deploy",
16
+ gate: "ship",
17
+ environment: "prod",
18
+ planDigest: `sha256:${"a".repeat(64)}`,
19
+ resolvedBy: "github:erin",
20
+ timestamp: "2026-11-01T10:00:00.000Z",
21
+ };
22
+ const statement = gateSealPayload(approval);
23
+
24
+ describe("a passkey's assertion over a gate statement (#4646)", () => {
25
+ test.each(["EdDSA", "ES256"] as const)("verifies with an %s passkey", (alg) => {
26
+ const pk = passkey("github:erin", "cred-erin", alg);
27
+ expect(verifyWebAuthnAssertion(assert(pk, statement), statement, [pk.signer])).toEqual({ ok: true, key: "cred-erin" });
28
+ });
29
+
30
+ test("refuses what WebAuthn level 2 refuses", () => {
31
+ const pk = passkey("github:erin", "cred-erin");
32
+ const why = (a: WebAuthnAssertion, over: Buffer = statement) => {
33
+ const r = verifyWebAuthnAssertion(a, over, [pk.signer]);
34
+ return r.ok ? null : r.reason;
35
+ };
36
+ expect(why(assert(pk, statement, { type: "webauthn.create" }))).toMatch(/not webauthn\.get/);
37
+ expect(why(assert(pk, statement, { challenge: webAuthnChallenge(Buffer.from("other")) }))).toMatch(/challenge/);
38
+ expect(why(assert(pk, statement, { origin: "https://evil.example" }))).toMatch(/origin "https:\/\/evil\.example"/);
39
+ expect(why(assert(pk, statement, { crossOrigin: true }))).toMatch(/cross-origin/);
40
+ expect(why(assert(pk, statement, { rpId: "evil.example" }))).toMatch(/rpIdHash/);
41
+ expect(why(assert(pk, statement, { flags: 0x01 }))).toMatch(/user-verified/);
42
+ expect(why(assert(pk, statement, { flags: 0x04 }))).toMatch(/user-present/);
43
+ // A different plan digest is a different statement.
44
+ expect(why(assert(pk, statement), gateSealPayload({ ...approval, planDigest: `sha256:${"b".repeat(64)}` }))).toMatch(/challenge/);
45
+ // Another key under the listed id.
46
+ const other = passkey("github:erin", "cred-erin");
47
+ expect(why(assert(other, statement))).toMatch(/does not match/);
48
+ // A credential nobody listed.
49
+ expect(why({ ...assert(pk, statement), id: "cred-unknown" })).toMatch(/does not list/);
50
+ // A signature over other bytes.
51
+ const a = assert(pk, statement);
52
+ expect(why({ ...a, authenticatorData: Buffer.concat([Buffer.from(a.authenticatorData, "base64url"), Buffer.from([1])]).toString("base64url") })).toMatch(/does not match/);
53
+ });
54
+
55
+ test("a sealed gate counts the passkey's seal for its approver only", () => {
56
+ const pk = passkey("github:erin", "cred-erin", "ES256");
57
+ const a = assert(pk, statement);
58
+ const seal = { kind: "webauthn", signer: "github:erin", key: a.id, signature: a.signature, clientDataJSON: a.clientDataJSON, authenticatorData: a.authenticatorData };
59
+ const signers: GateSigners = { base: null, signersPath: ".chant/allowed_signers", active: true, signers: [], passkeys: [pk.signer], problems: [] };
60
+ expect(gateSealRefusal(signers, { ...approval, seal })).toBeNull();
61
+ expect(gateSealRefusal({ ...signers, passkeys: [] }, { ...approval, seal })).toMatch(/has no passkey in \.chant\/trust\.json at base/);
62
+ expect(gateSealRefusal({ ...signers, passkeys: [{ ...pk.signer, principal: "github:frank" }] }, { ...approval, seal })).toMatch(/has no passkey/);
63
+ expect(gateSealRefusal(signers, { ...approval, planDigest: `sha256:${"c".repeat(64)}`, seal })).toMatch(/challenge/);
64
+ expect(gateSealRefusal(signers, { ...approval, seal: { ...seal, kind: "x509" } })).toMatch(/kind "x509"/);
65
+ });
66
+
67
+ test("--signature reads an ssh signature, an assertion, or a PublicKeyCredential's JSON", () => {
68
+ const pk = passkey("github:erin", "cred-erin");
69
+ const a = assert(pk, statement);
70
+ expect(readExternalSignature(JSON.stringify(a))).toEqual({ kind: "webauthn", assertion: a });
71
+ const { id, ...response } = a;
72
+ expect(readExternalSignature(JSON.stringify({ id, rawId: id, type: "public-key", response: { ...response, userHandle: null } }))).toEqual({ kind: "webauthn", assertion: a });
73
+ expect(readExternalSignature("-----BEGIN SSH SIGNATURE-----\nU1NIU0lH\n-----END SSH SIGNATURE-----\n")).toMatchObject({ kind: "ssh" });
74
+ expect(readExternalSignature("{}")).toHaveProperty("problem");
75
+ expect(readExternalSignature("nonsense")).toHaveProperty("problem");
76
+ });
77
+ });
@@ -0,0 +1,133 @@
1
+ /**
2
+ * A gate approval signed with a passkey (#4646): a WebAuthn assertion over
3
+ * the gate's statement, checked with node:crypto.
4
+ *
5
+ * A platform that collects an approval on a phone asks the browser for an
6
+ * assertion (`navigator.credentials.get`) whose challenge is the statement's
7
+ * digest, `base64url(SHA-256(statement))` with no padding, where the
8
+ * statement is `gateSealPayload`'s bytes (`chant approve --statement` prints
9
+ * them). The assertion is relayed to `chant approve --signature`, checked
10
+ * against a passkey `.chant/trust.json` lists at base for the approver, and
11
+ * kept on the approval's seal, so anyone can check it again offline.
12
+ *
13
+ * The check follows WebAuthn level 2, section 7.2, for what can be checked
14
+ * without the relying party's state: the client data's type is
15
+ * `webauthn.get`, its challenge is the statement's, its origin is one the
16
+ * passkey lists and it is not cross-origin; the authenticator data's rpIdHash
17
+ * is SHA-256 of the passkey's rpId and both the user-present and
18
+ * user-verified flags are set; and the signature over authenticatorData ||
19
+ * SHA-256(clientDataJSON) verifies with the passkey's public key. The
20
+ * signature counter is not checked: a ledger line can't know the
21
+ * authenticator's last count.
22
+ *
23
+ * Like `./gate-seal.ts`, this imports node:crypto and nothing else, so a
24
+ * bundled gate decision carries it.
25
+ */
26
+
27
+ import { createHash, createPublicKey, verify, type KeyObject } from "node:crypto";
28
+
29
+ /**
30
+ * A passkey `.chant/trust.json` lists for a person (#4646): the credential
31
+ * id, its public key, the relying party it was made for, and the origins an
32
+ * assertion may come from.
33
+ */
34
+ export interface PasskeySigner {
35
+ principal: string;
36
+ /** The credential id (`rawId`), base64url with no padding. */
37
+ id: string;
38
+ /**
39
+ * The credential's public key as DER SubjectPublicKeyInfo, base64url: what
40
+ * `AuthenticatorAttestationResponse.getPublicKey()` gives. Ed25519 (EdDSA),
41
+ * P-256 (ES256) and RSA (RS256) keys verify.
42
+ */
43
+ publicKey: string;
44
+ /** The relying party id the credential is scoped to, such as `example.com`. */
45
+ rpId: string;
46
+ /** Origins an assertion may come from, such as `https://control.example.com`. */
47
+ origins: string[];
48
+ }
49
+
50
+ /** A WebAuthn assertion as a browser returns it, each field base64url. */
51
+ export interface WebAuthnAssertion {
52
+ /** The credential id. */
53
+ id: string;
54
+ clientDataJSON: string;
55
+ authenticatorData: string;
56
+ signature: string;
57
+ }
58
+
59
+ /** What {@link verifyWebAuthnAssertion} found. On success, `key` is the credential id. */
60
+ export type WebAuthnCheck = { ok: true; key: string } | { ok: false; reason: string };
61
+
62
+ const B64URL = /^[A-Za-z0-9_-]+={0,2}$/;
63
+
64
+ /** Whether `raw` has the shape of a {@link WebAuthnAssertion}. */
65
+ export function isWebAuthnAssertion(raw: unknown): raw is WebAuthnAssertion {
66
+ const a = raw as Partial<Record<keyof WebAuthnAssertion, unknown>> | null;
67
+ return (
68
+ !!a && typeof a === "object" && !Array.isArray(a) &&
69
+ (["id", "clientDataJSON", "authenticatorData", "signature"] as const).every((k) => typeof a[k] === "string" && B64URL.test(a[k] as string))
70
+ );
71
+ }
72
+
73
+ /** The challenge a passkey signs for `statement`: base64url of its SHA-256, no padding. */
74
+ export function webAuthnChallenge(statement: Buffer): string {
75
+ return createHash("sha256").update(statement).digest("base64url");
76
+ }
77
+
78
+ /** The passkey's key and the algorithm its signature is checked with, or why it can't be read. */
79
+ export function passkeyPublicKey(publicKey: string): { key: KeyObject; alg: "EdDSA" | "ES256" | "RS256" } | { problem: string } {
80
+ let key: KeyObject;
81
+ try {
82
+ key = createPublicKey({ key: Buffer.from(publicKey, "base64url"), format: "der", type: "spki" });
83
+ } catch (err) {
84
+ return { problem: `the public key is not a DER SubjectPublicKeyInfo: ${err instanceof Error ? err.message : String(err)}` };
85
+ }
86
+ if (key.asymmetricKeyType === "ed25519") return { key, alg: "EdDSA" };
87
+ if (key.asymmetricKeyType === "ec" && key.asymmetricKeyDetails?.namedCurve === "prime256v1") return { key, alg: "ES256" };
88
+ if (key.asymmetricKeyType === "rsa") return { key, alg: "RS256" };
89
+ return { problem: `a ${key.asymmetricKeyType}${key.asymmetricKeyDetails?.namedCurve ? ` ${key.asymmetricKeyDetails.namedCurve}` : ""} key; a passkey is Ed25519, P-256 or RSA` };
90
+ }
91
+
92
+ const sameId = (a: string, b: string): boolean => a.replace(/=+$/, "") === b.replace(/=+$/, "");
93
+
94
+ /**
95
+ * Whether `assertion` signs `statement` with one of `passkeys`, chosen by
96
+ * credential id. Never throws.
97
+ */
98
+ export function verifyWebAuthnAssertion(assertion: WebAuthnAssertion, statement: Buffer, passkeys: readonly PasskeySigner[]): WebAuthnCheck {
99
+ try {
100
+ const pk = passkeys.find((p) => sameId(p.id, assertion.id));
101
+ if (!pk) return { ok: false, reason: `signed by passkey ${assertion.id}, which the policy at base does not list for the approver` };
102
+ const clientData = Buffer.from(assertion.clientDataJSON, "base64url");
103
+ let cd: { type?: unknown; challenge?: unknown; origin?: unknown; crossOrigin?: unknown };
104
+ try {
105
+ cd = JSON.parse(clientData.toString("utf-8"));
106
+ } catch {
107
+ return { ok: false, reason: "its clientDataJSON is not JSON" };
108
+ }
109
+ if (cd.type !== "webauthn.get") return { ok: false, reason: `its client data is a ${JSON.stringify(cd.type)} ceremony, not webauthn.get` };
110
+ if (cd.challenge !== webAuthnChallenge(statement)) return { ok: false, reason: "its challenge is not this approval's statement digest" };
111
+ if (typeof cd.origin !== "string" || !pk.origins.includes(cd.origin)) {
112
+ return { ok: false, reason: `it comes from origin ${JSON.stringify(cd.origin)}, and the passkey allows ${pk.origins.join(", ")}` };
113
+ }
114
+ if (cd.crossOrigin === true) return { ok: false, reason: "it was made in a cross-origin frame" };
115
+ const authData = Buffer.from(assertion.authenticatorData, "base64url");
116
+ if (authData.length < 37) return { ok: false, reason: "its authenticatorData is shorter than 37 bytes" };
117
+ if (!authData.subarray(0, 32).equals(createHash("sha256").update(pk.rpId, "utf-8").digest())) {
118
+ return { ok: false, reason: `its rpIdHash is not SHA-256 of ${pk.rpId}` };
119
+ }
120
+ const flags = authData[32]!;
121
+ if (!(flags & 0x01)) return { ok: false, reason: "the user-present flag is unset" };
122
+ if (!(flags & 0x04)) return { ok: false, reason: "the user-verified flag is unset" };
123
+ const key = passkeyPublicKey(pk.publicKey);
124
+ if ("problem" in key) return { ok: false, reason: `passkey ${pk.id}: ${key.problem}` };
125
+ const signed = Buffer.concat([authData, createHash("sha256").update(clientData).digest()]);
126
+ const signature = Buffer.from(assertion.signature, "base64url");
127
+ // ES256 signatures are ASN.1 DER, node's default for an EC key.
128
+ const ok = verify(key.alg === "EdDSA" ? null : "sha256", signed, key.key, signature);
129
+ return ok ? { ok: true, key: pk.id } : { ok: false, reason: "the signature does not match the signed fields" };
130
+ } catch (err) {
131
+ return { ok: false, reason: err instanceof Error ? err.message : String(err) };
132
+ }
133
+ }