@pithy-sh/auth 0.10.0 → 0.12.0

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 (283) hide show
  1. package/README.md +30 -2
  2. package/dist/admin/users.js +1 -1
  3. package/dist/audit/actions.d.ts +58 -0
  4. package/dist/audit/actions.d.ts.map +1 -1
  5. package/dist/audit/actions.js +59 -1
  6. package/dist/audit/emit.d.ts +36 -0
  7. package/dist/audit/emit.d.ts.map +1 -1
  8. package/dist/audit/emit.js +48 -2
  9. package/dist/audit/evidence.d.ts +8 -2
  10. package/dist/audit/evidence.d.ts.map +1 -1
  11. package/dist/capability.d.ts +47 -8
  12. package/dist/capability.d.ts.map +1 -1
  13. package/dist/capability.js +56 -6
  14. package/dist/client/api.d.ts +55 -12
  15. package/dist/client/api.d.ts.map +1 -1
  16. package/dist/client/api.js +57 -18
  17. package/dist/client/bearer.d.ts +110 -0
  18. package/dist/client/bearer.d.ts.map +1 -0
  19. package/dist/client/bearer.js +265 -0
  20. package/dist/client/handoff.d.ts +77 -0
  21. package/dist/client/handoff.d.ts.map +1 -0
  22. package/dist/client/handoff.js +119 -0
  23. package/dist/client/mcp.d.ts +70 -0
  24. package/dist/client/mcp.d.ts.map +1 -0
  25. package/dist/client/mcp.js +65 -0
  26. package/dist/data/betterAuth.d.ts +3 -2
  27. package/dist/data/betterAuth.d.ts.map +1 -1
  28. package/dist/data/betterAuth.js +5 -3
  29. package/dist/data/kitFields.d.ts +5 -0
  30. package/dist/data/kitFields.d.ts.map +1 -1
  31. package/dist/data/kitFields.js +5 -0
  32. package/dist/data/tables.d.ts +26 -4
  33. package/dist/data/tables.d.ts.map +1 -1
  34. package/dist/data/tables.js +5 -3
  35. package/dist/data/userLifecycle.d.ts +10 -0
  36. package/dist/data/userLifecycle.d.ts.map +1 -1
  37. package/dist/data/userLifecycle.js +8 -3
  38. package/dist/data/verificationOutcome.d.ts +53 -0
  39. package/dist/data/verificationOutcome.d.ts.map +1 -0
  40. package/dist/data/verificationOutcome.js +50 -0
  41. package/dist/email/send.js +6 -2
  42. package/dist/http/adminRoutes.d.ts.map +1 -1
  43. package/dist/http/adminRoutes.js +319 -8
  44. package/dist/http/csrf.d.ts.map +1 -1
  45. package/dist/http/csrf.js +2 -1
  46. package/dist/http/guards.d.ts +15 -10
  47. package/dist/http/guards.d.ts.map +1 -1
  48. package/dist/http/guards.js +76 -10
  49. package/dist/http/handoff.d.ts +76 -0
  50. package/dist/http/handoff.d.ts.map +1 -0
  51. package/dist/http/handoff.js +316 -0
  52. package/dist/http/middleware.d.ts +37 -1
  53. package/dist/http/middleware.d.ts.map +1 -1
  54. package/dist/http/middleware.js +68 -6
  55. package/dist/http/resolve.d.ts.map +1 -1
  56. package/dist/http/resolve.js +9 -3
  57. package/dist/http/responses.d.ts +322 -0
  58. package/dist/http/responses.d.ts.map +1 -1
  59. package/dist/http/responses.js +202 -5
  60. package/dist/http/routes.d.ts +3 -0
  61. package/dist/http/routes.d.ts.map +1 -1
  62. package/dist/http/routes.js +78 -5
  63. package/dist/http/schemas.d.ts +114 -0
  64. package/dist/http/schemas.d.ts.map +1 -1
  65. package/dist/http/schemas.js +94 -1
  66. package/dist/http/views.d.ts +60 -3
  67. package/dist/http/views.d.ts.map +1 -1
  68. package/dist/http/views.js +143 -3
  69. package/dist/index.d.ts +2 -0
  70. package/dist/index.d.ts.map +1 -1
  71. package/dist/index.js +4 -2
  72. package/dist/instance/auth.d.ts +148 -10
  73. package/dist/instance/auth.d.ts.map +1 -1
  74. package/dist/instance/auth.js +87 -42
  75. package/dist/instance/plugins.d.ts +6 -0
  76. package/dist/instance/plugins.d.ts.map +1 -1
  77. package/dist/instance/plugins.js +14 -1
  78. package/dist/ledger/read.d.ts +53 -0
  79. package/dist/ledger/read.d.ts.map +1 -0
  80. package/dist/ledger/read.js +85 -0
  81. package/dist/ledger/record.d.ts +35 -0
  82. package/dist/ledger/record.d.ts.map +1 -0
  83. package/dist/ledger/record.js +98 -0
  84. package/dist/lifecycle/audited.d.ts +48 -0
  85. package/dist/lifecycle/audited.d.ts.map +1 -0
  86. package/dist/lifecycle/audited.js +65 -0
  87. package/dist/lifecycle/enforce.d.ts +37 -2
  88. package/dist/lifecycle/enforce.d.ts.map +1 -1
  89. package/dist/lifecycle/enforce.js +46 -5
  90. package/dist/lifecycle/erasure.d.ts +9 -0
  91. package/dist/lifecycle/erasure.d.ts.map +1 -0
  92. package/dist/lifecycle/erasure.js +96 -0
  93. package/dist/lifecycle/inactivity.d.ts +19 -0
  94. package/dist/lifecycle/inactivity.d.ts.map +1 -0
  95. package/dist/lifecycle/inactivity.js +28 -0
  96. package/dist/lifecycle/reason.d.ts +11 -0
  97. package/dist/lifecycle/reason.d.ts.map +1 -0
  98. package/dist/lifecycle/reason.js +13 -0
  99. package/dist/lifecycle/request.d.ts +5 -2
  100. package/dist/lifecycle/request.d.ts.map +1 -1
  101. package/dist/lifecycle/request.js +6 -2
  102. package/dist/lifecycle/transitions.d.ts +179 -18
  103. package/dist/lifecycle/transitions.d.ts.map +1 -1
  104. package/dist/lifecycle/transitions.js +391 -70
  105. package/dist/mcp/argumentClass.d.ts +51 -0
  106. package/dist/mcp/argumentClass.d.ts.map +1 -0
  107. package/dist/mcp/argumentClass.js +69 -0
  108. package/dist/mcp/capability.d.ts +50 -0
  109. package/dist/mcp/capability.d.ts.map +1 -0
  110. package/dist/mcp/capability.js +140 -0
  111. package/dist/mcp/clientMetadata.d.ts +40 -0
  112. package/dist/mcp/clientMetadata.d.ts.map +1 -0
  113. package/dist/mcp/clientMetadata.js +68 -0
  114. package/dist/mcp/consent.d.ts +49 -0
  115. package/dist/mcp/consent.d.ts.map +1 -0
  116. package/dist/mcp/consent.js +69 -0
  117. package/dist/mcp/dispatch.d.ts +35 -0
  118. package/dist/mcp/dispatch.d.ts.map +1 -0
  119. package/dist/mcp/dispatch.js +135 -0
  120. package/dist/mcp/floor.d.ts +37 -0
  121. package/dist/mcp/floor.d.ts.map +1 -0
  122. package/dist/mcp/floor.js +41 -0
  123. package/dist/mcp/host.d.ts +34 -0
  124. package/dist/mcp/host.d.ts.map +1 -0
  125. package/dist/mcp/host.js +2 -0
  126. package/dist/mcp/http/redirectList.d.ts +9 -0
  127. package/dist/mcp/http/redirectList.d.ts.map +1 -0
  128. package/dist/mcp/http/redirectList.js +24 -0
  129. package/dist/mcp/http/responses.d.ts +143 -0
  130. package/dist/mcp/http/responses.d.ts.map +1 -0
  131. package/dist/mcp/http/responses.js +83 -0
  132. package/dist/mcp/http/routes.d.ts +28 -0
  133. package/dist/mcp/http/routes.d.ts.map +1 -0
  134. package/dist/mcp/http/routes.js +517 -0
  135. package/dist/mcp/http/schemas.d.ts +24 -0
  136. package/dist/mcp/http/schemas.d.ts.map +1 -0
  137. package/dist/mcp/http/schemas.js +18 -0
  138. package/dist/mcp/marker.d.ts +15 -0
  139. package/dist/mcp/marker.d.ts.map +1 -0
  140. package/dist/mcp/marker.js +15 -0
  141. package/dist/mcp/provider.d.ts +78 -0
  142. package/dist/mcp/provider.d.ts.map +1 -0
  143. package/dist/mcp/provider.js +108 -0
  144. package/dist/mcp/purge.d.ts +15 -0
  145. package/dist/mcp/purge.d.ts.map +1 -0
  146. package/dist/mcp/purge.js +31 -0
  147. package/dist/mcp/rpc.d.ts +79 -0
  148. package/dist/mcp/rpc.d.ts.map +1 -0
  149. package/dist/mcp/rpc.js +103 -0
  150. package/dist/mcp/toolAudit.d.ts +76 -0
  151. package/dist/mcp/toolAudit.d.ts.map +1 -0
  152. package/dist/mcp/toolAudit.js +86 -0
  153. package/dist/migrations/0005_purge_once.d.ts +22 -0
  154. package/dist/migrations/0005_purge_once.d.ts.map +1 -0
  155. package/dist/migrations/0005_purge_once.js +35 -0
  156. package/dist/migrations/0006_verification_outcomes.d.ts +15 -0
  157. package/dist/migrations/0006_verification_outcomes.d.ts.map +1 -0
  158. package/dist/migrations/0006_verification_outcomes.js +35 -0
  159. package/dist/migrations/0007_erasure_record.d.ts +17 -0
  160. package/dist/migrations/0007_erasure_record.d.ts.map +1 -0
  161. package/dist/migrations/0007_erasure_record.js +36 -0
  162. package/dist/migrations/0008_last_active.d.ts +15 -0
  163. package/dist/migrations/0008_last_active.d.ts.map +1 -0
  164. package/dist/migrations/0008_last_active.js +29 -0
  165. package/dist/migrations/pluginTables.d.ts +8 -0
  166. package/dist/migrations/pluginTables.d.ts.map +1 -1
  167. package/dist/migrations/pluginTables.js +8 -1
  168. package/dist/migrations/set.d.ts +5 -1
  169. package/dist/migrations/set.d.ts.map +1 -1
  170. package/dist/migrations/set.js +10 -2
  171. package/dist/peer.d.ts +3 -2
  172. package/dist/peer.d.ts.map +1 -1
  173. package/dist/processing/activities.d.ts +6 -0
  174. package/dist/processing/activities.d.ts.map +1 -0
  175. package/dist/processing/activities.js +12 -0
  176. package/dist/purge/contribution.d.ts +62 -0
  177. package/dist/purge/contribution.d.ts.map +1 -0
  178. package/dist/purge/contribution.js +155 -0
  179. package/dist/purge/retryPolicy.d.ts +22 -0
  180. package/dist/purge/retryPolicy.d.ts.map +1 -0
  181. package/dist/purge/retryPolicy.js +26 -0
  182. package/dist/purge/run.d.ts +158 -0
  183. package/dist/purge/run.d.ts.map +1 -0
  184. package/dist/purge/run.js +205 -0
  185. package/dist/purge/specs.d.ts +71 -0
  186. package/dist/purge/specs.d.ts.map +1 -0
  187. package/dist/purge/specs.js +72 -0
  188. package/dist/purge/start.d.ts +42 -0
  189. package/dist/purge/start.d.ts.map +1 -0
  190. package/dist/purge/start.js +37 -0
  191. package/dist/purge/workflow.d.ts +71 -0
  192. package/dist/purge/workflow.d.ts.map +1 -0
  193. package/dist/purge/workflow.js +140 -0
  194. package/dist/test-utils/accountFootprint.d.ts +13 -0
  195. package/dist/test-utils/accountFootprint.d.ts.map +1 -0
  196. package/dist/test-utils/accountFootprint.js +49 -0
  197. package/dist/test-utils/liveApp.d.ts +6 -0
  198. package/dist/test-utils/liveApp.d.ts.map +1 -1
  199. package/dist/test-utils/liveApp.js +7 -2
  200. package/dist/token/handoff.d.ts +80 -0
  201. package/dist/token/handoff.d.ts.map +1 -0
  202. package/dist/token/handoff.js +136 -0
  203. package/dist/version.generated.d.ts +1 -1
  204. package/dist/version.generated.js +1 -1
  205. package/docs/account-lifecycle.md +176 -12
  206. package/docs/apple-signin.md +32 -4
  207. package/docs/facebook-oauth.md +2 -2
  208. package/docs/github-oauth.md +2 -2
  209. package/docs/google-oauth.md +9 -7
  210. package/docs/microsoft-oauth.md +2 -2
  211. package/package.json +11 -5
  212. package/pithy.manifest.json +2 -2
  213. package/pithy.mcp.manifest.json +36 -0
  214. package/src/audit/actions.ts +58 -0
  215. package/src/audit/emit.ts +66 -1
  216. package/src/audit/evidence.ts +8 -4
  217. package/src/capability.ts +122 -18
  218. package/src/client/api.ts +69 -19
  219. package/src/client/bearer.ts +388 -0
  220. package/src/client/handoff.ts +172 -0
  221. package/src/client/mcp.ts +140 -0
  222. package/src/data/betterAuth.ts +8 -4
  223. package/src/data/kitFields.ts +2 -0
  224. package/src/data/tables.ts +4 -2
  225. package/src/data/userLifecycle.ts +19 -4
  226. package/src/data/verificationOutcome.ts +86 -0
  227. package/src/email/send.ts +2 -2
  228. package/src/http/adminRoutes.ts +465 -4
  229. package/src/http/csrf.ts +4 -1
  230. package/src/http/guards.ts +79 -10
  231. package/src/http/handoff.ts +350 -0
  232. package/src/http/middleware.ts +74 -5
  233. package/src/http/resolve.ts +25 -25
  234. package/src/http/responses.ts +374 -3
  235. package/src/http/routes.ts +116 -5
  236. package/src/http/schemas.ts +195 -0
  237. package/src/http/views.ts +192 -3
  238. package/src/index.ts +2 -0
  239. package/src/instance/auth.ts +58 -3
  240. package/src/instance/plugins.ts +20 -2
  241. package/src/ledger/read.ts +133 -0
  242. package/src/ledger/record.ts +198 -0
  243. package/src/lifecycle/audited.ts +104 -0
  244. package/src/lifecycle/enforce.ts +55 -5
  245. package/src/lifecycle/erasure.ts +118 -0
  246. package/src/lifecycle/inactivity.ts +56 -0
  247. package/src/lifecycle/reason.ts +11 -0
  248. package/src/lifecycle/request.ts +10 -2
  249. package/src/lifecycle/transitions.ts +552 -93
  250. package/src/mcp/argumentClass.ts +112 -0
  251. package/src/mcp/capability.ts +194 -0
  252. package/src/mcp/clientMetadata.ts +81 -0
  253. package/src/mcp/consent.ts +95 -0
  254. package/src/mcp/dispatch.ts +154 -0
  255. package/src/mcp/floor.ts +62 -0
  256. package/src/mcp/host.ts +36 -0
  257. package/src/mcp/http/redirectList.ts +26 -0
  258. package/src/mcp/http/responses.ts +157 -0
  259. package/src/mcp/http/routes.ts +635 -0
  260. package/src/mcp/http/schemas.ts +37 -0
  261. package/src/mcp/marker.ts +18 -0
  262. package/src/mcp/provider.ts +151 -0
  263. package/src/mcp/purge.ts +39 -0
  264. package/src/mcp/rpc.ts +135 -0
  265. package/src/mcp/toolAudit.ts +132 -0
  266. package/src/migrations/0005_purge_once.ts +42 -0
  267. package/src/migrations/0006_verification_outcomes.ts +51 -0
  268. package/src/migrations/0007_erasure_record.ts +43 -0
  269. package/src/migrations/0008_last_active.ts +30 -0
  270. package/src/migrations/pluginTables.ts +19 -1
  271. package/src/migrations/set.ts +9 -1
  272. package/src/processing/activities.ts +14 -0
  273. package/src/purge/contribution.ts +218 -0
  274. package/src/purge/retryPolicy.ts +26 -0
  275. package/src/purge/run.ts +348 -0
  276. package/src/purge/specs.ts +95 -0
  277. package/src/purge/start.ts +79 -0
  278. package/src/purge/workflow.ts +202 -0
  279. package/src/seeds/example.ts +2 -2
  280. package/src/test-utils/accountFootprint.ts +104 -0
  281. package/src/test-utils/liveApp.ts +10 -1
  282. package/src/token/handoff.ts +180 -0
  283. package/src/version.generated.ts +1 -1
@@ -7,6 +7,7 @@ import { emailOTP } from "better-auth/plugins/email-otp";
7
7
  import { jwt } from "better-auth/plugins/jwt";
8
8
  import { magicLink } from "better-auth/plugins/magic-link";
9
9
  import { z } from "zod";
10
+ import type { VerificationLedger } from "../ledger/record";
10
11
  import type { SendAuthEmail } from "./auth";
11
12
  /**
12
13
  * The Better Auth plugins the kit composes for itself, and the reason they are fixed.
@@ -57,6 +58,11 @@ export interface KitPluginDeps {
57
58
  * built the instance — the schema baseline, a seed, a unit test. See `./providerSignInGate`.
58
59
  */
59
60
  requestHeaders?: Headers;
61
+ /**
62
+ * The verification ledger (#829) — told what each send was and which mail carries it, once the email seam
63
+ * has answered. Absent where no instance will ever send: the schema baseline in `../migrations/pluginTables.ts`.
64
+ */
65
+ ledger?: VerificationLedger;
60
66
  }
61
67
  /**
62
68
  * The kit's own, as a **tuple** rather than an array. Better Auth infers a composed instance's whole
@@ -1 +1 @@
1
- {"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../src/instance/plugins.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACzD,OAAO,EAAE,GAAG,EAAE,MAAM,yBAAyB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAoB,aAAa,EAAE,MAAM,QAAQ,CAAC;AAI9D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,YAAI,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,gCAAoC,CAAC;AAEtH,qGAAqG;AACrG,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,aAAa,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,SAAS,EAAE,aAAa,CAAC;IACzB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;;OAKG;IACH,IAAI,EAAE,SAAS,CAAC;IAChB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IAKvB,gBAAgB;IAChB,UAAU,CAAC,OAAO,MAAM,CAAC;IACzB,UAAU,CAAC,OAAO,GAAG,CAAC;IACtB,UAAU,CAAC,OAAO,SAAS,CAAC;IAC5B,UAAU,CAAC,OAAO,QAAQ,CAAC;IAI3B,gBAAgB;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAkE1D;AAuCD;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,iDAMpB,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,CA4BhF"}
1
+ {"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../src/instance/plugins.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACzD,OAAO,EAAE,GAAG,EAAE,MAAM,yBAAyB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAoB,aAAa,EAAE,MAAM,QAAQ,CAAC;AAI9D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,YAAI,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,gCAAoC,CAAC;AAEtH,qGAAqG;AACrG,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,aAAa,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,SAAS,EAAE,aAAa,CAAC;IACzB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;;OAKG;IACH,IAAI,EAAE,SAAS,CAAC;IAChB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,kBAAkB,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IAKvB,gBAAgB;IAChB,UAAU,CAAC,OAAO,MAAM,CAAC;IACzB,UAAU,CAAC,OAAO,GAAG,CAAC;IACtB,UAAU,CAAC,OAAO,SAAS,CAAC;IAC5B,UAAU,CAAC,OAAO,QAAQ,CAAC;IAI3B,gBAAgB;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAkE1D;AAmDD;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,iDAMpB,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,CA4BhF"}
@@ -118,15 +118,28 @@ function kitPlugins(deps) {
118
118
  */
119
119
  async function sendAndRecord(deps, message, ctx) {
120
120
  const requestContext = ctx?.context;
121
+ const type = message.template === "magicLink" ? "magic_link" : "otp";
122
+ let delivery;
121
123
  try {
122
- markMessageDelivery(requestContext, await deps.sendEmail(message));
124
+ delivery = await deps.sendEmail(message);
123
125
  } catch (error) {
124
126
  markMessageDelivery(requestContext, {
125
127
  delivery: "failed",
126
128
  reason: SEND_FAULT
127
129
  });
130
+ await deps.ledger?.issued(requestContext, {
131
+ type,
132
+ email: message.to,
133
+ emailJobId: null
134
+ });
128
135
  throw error;
129
136
  }
137
+ markMessageDelivery(requestContext, delivery);
138
+ await deps.ledger?.issued(requestContext, {
139
+ type,
140
+ email: message.to,
141
+ emailJobId: delivery.delivery === "failed" ? null : delivery.jobId ?? null
142
+ });
130
143
  }
131
144
  /** Is this value shaped like a Better Auth plugin — an object carrying a non-empty string `id`? */
132
145
  function isBetterAuthPlugin(value) {
@@ -0,0 +1,53 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { AdminPage } from "../admin/users";
4
+ import type { AuthDatabase } from "../data/tables";
5
+ import { VerificationOutcome, type VerificationState, VerificationType } from "../data/verificationOutcome";
6
+ import type { VerificationTypeCounts } from "../http/responses";
7
+ /**
8
+ * Reading the verification ledger (#829): what `GET {auth}/admin/verifications` answers.
9
+ *
10
+ * Two reads over one window of issue times: the counts by type and state, and the rows themselves, paged. The
11
+ * state is computed at read time — an unused row becomes expired the moment its expiry passes, with nothing
12
+ * written — so both reads take the same `now`, and a row counted as pending is listed as pending.
13
+ */
14
+ /** How far back a window reaches when the caller names no start. */
15
+ export declare const DEFAULT_WINDOW_DAYS = 30;
16
+ /** A window of issue times: `since` inclusive, `until` exclusive. */
17
+ export interface VerificationWindow {
18
+ since: Date;
19
+ until: Date;
20
+ }
21
+ /**
22
+ * The window a read covers. `until` defaults to now and `since` to 30 days before it; a window that ends where it
23
+ * starts, or before, is refused rather than answered with nothing, because an empty answer would read as "no
24
+ * sign-ins".
25
+ */
26
+ export declare function resolveVerificationWindow(input: {
27
+ since?: Date;
28
+ until?: Date;
29
+ }, now: Date): VerificationWindow;
30
+ /**
31
+ * The counts by type and state over a window: one aggregate, grouped by type, and every type answered — a type
32
+ * nothing was issued for reads as zeros rather than going missing, so a reader never has to tell "none" from
33
+ * "not reported".
34
+ */
35
+ export declare function verificationCounts(db: AuthDatabase, window: VerificationWindow, now: Date): Promise<VerificationTypeCounts[]>;
36
+ /** What the row listing filters on and where it resumes. */
37
+ export interface ListVerificationOutcomesOptions {
38
+ window: VerificationWindow;
39
+ /** Only this type. */
40
+ type?: VerificationType | undefined;
41
+ /** Only rows in this state at `now`. */
42
+ state?: VerificationState | undefined;
43
+ /** The moment `state` is judged at — the same `now` the counts took. */
44
+ now: Date;
45
+ cursor?: string | undefined;
46
+ limit?: number | undefined;
47
+ }
48
+ /**
49
+ * The window's rows, newest issue first, paged by keyset on `(issuedAt, id)` — the index the migration built for
50
+ * exactly this. A malformed cursor is a first page, as everywhere in the kit.
51
+ */
52
+ export declare function listVerificationOutcomes(db: AuthDatabase, options: ListVerificationOutcomesOptions): Promise<AdminPage<VerificationOutcome>>;
53
+ //# sourceMappingURL=read.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/ledger/read.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC5G,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE;;;;;;GAMG;AAEH,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,IAAI,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAAE,KAAK,CAAC,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,IAAI,CAAA;CAAE,EAAE,GAAG,EAAE,IAAI,GAAG,kBAAkB,CAU9G;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,kBAAkB,EAC1B,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAuBnC;AAED,4DAA4D;AAC5D,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,kBAAkB,CAAC;IAC3B,sBAAsB;IACtB,IAAI,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACpC,wCAAwC;IACxC,KAAK,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACtC,wEAAwE;IACxE,GAAG,EAAE,IAAI,CAAC;IACV,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC,CAgCzC"}
@@ -0,0 +1,85 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { VerificationOutcome, VerificationType } from "../data/verificationOutcome.js";
4
+ import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
5
+ import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
6
+ import { decodeCursor, pageLimit, toPage } from "@pithy-sh/core/src/data/cursor";
7
+ import { sql } from "kysely";
8
+ //#region src/ledger/read.ts
9
+ /**
10
+ * Reading the verification ledger (#829): what `GET {auth}/admin/verifications` answers.
11
+ *
12
+ * Two reads over one window of issue times: the counts by type and state, and the rows themselves, paged. The
13
+ * state is computed at read time — an unused row becomes expired the moment its expiry passes, with nothing
14
+ * written — so both reads take the same `now`, and a row counted as pending is listed as pending.
15
+ */
16
+ /** How far back a window reaches when the caller names no start. */
17
+ const DEFAULT_WINDOW_DAYS = 30;
18
+ /**
19
+ * The window a read covers. `until` defaults to now and `since` to 30 days before it; a window that ends where it
20
+ * starts, or before, is refused rather than answered with nothing, because an empty answer would read as "no
21
+ * sign-ins".
22
+ */
23
+ function resolveVerificationWindow(input, now) {
24
+ const until = input.until ?? now;
25
+ const since = input.since ?? /* @__PURE__ */ new Date(until.getTime() - 2592e6);
26
+ if (since.getTime() >= until.getTime()) throw new ValidationError({
27
+ message: "The window must start before it ends.",
28
+ detail: `since ${since.toISOString()} is not before until ${until.toISOString()}`
29
+ });
30
+ return {
31
+ since,
32
+ until
33
+ };
34
+ }
35
+ /**
36
+ * The counts by type and state over a window: one aggregate, grouped by type, and every type answered — a type
37
+ * nothing was issued for reads as zeros rather than going missing, so a reader never has to tell "none" from
38
+ * "not reported".
39
+ */
40
+ async function verificationCounts(db, window, now) {
41
+ const at = SQLiteDate.encode(now);
42
+ const rows = await db.selectFrom("pithyAuthVerificationOutcomes").select((eb) => [
43
+ "type",
44
+ eb.fn.countAll().as("issued"),
45
+ sql`sum(case when ${eb.ref("usedAt")} is not null then 1 else 0 end)`.as("used"),
46
+ sql`sum(case when ${eb.ref("usedAt")} is null and ${eb.ref("expiresAt")} <= ${at} then 1 else 0 end)`.as("expired")
47
+ ]).where("issuedAt", ">=", SQLiteDate.encode(window.since)).where("issuedAt", "<", SQLiteDate.encode(window.until)).groupBy("type").execute();
48
+ return VerificationType.options.map((type) => {
49
+ const row = rows.find((candidate) => candidate.type === type);
50
+ const issued = Number(row?.issued ?? 0);
51
+ const used = Number(row?.used ?? 0);
52
+ const expired = Number(row?.expired ?? 0);
53
+ return {
54
+ type,
55
+ issued,
56
+ used,
57
+ expired,
58
+ pending: issued - used - expired
59
+ };
60
+ });
61
+ }
62
+ /**
63
+ * The window's rows, newest issue first, paged by keyset on `(issuedAt, id)` — the index the migration built for
64
+ * exactly this. A malformed cursor is a first page, as everywhere in the kit.
65
+ */
66
+ async function listVerificationOutcomes(db, options) {
67
+ const limit = pageLimit(options.limit);
68
+ const at = SQLiteDate.encode(options.now);
69
+ let query = db.selectFrom("pithyAuthVerificationOutcomes").selectAll().where("issuedAt", ">=", SQLiteDate.encode(options.window.since)).where("issuedAt", "<", SQLiteDate.encode(options.window.until)).orderBy("issuedAt", "desc").orderBy("id", "desc").limit(limit + 1);
70
+ if (options.type) query = query.where("type", "=", options.type);
71
+ if (options.state === "used") query = query.where("usedAt", "is not", null);
72
+ if (options.state === "expired") query = query.where("usedAt", "is", null).where("expiresAt", "<=", at);
73
+ if (options.state === "pending") query = query.where("usedAt", "is", null).where("expiresAt", ">", at);
74
+ const cursor = decodeCursor(options.cursor);
75
+ const sort = cursor ? Number(cursor.sort) : NaN;
76
+ const id = cursor ? Number(cursor.id) : NaN;
77
+ if (Number.isFinite(sort) && Number.isFinite(id)) query = query.where((eb) => eb.or([eb("issuedAt", "<", sort), eb.and([eb("issuedAt", "=", sort), eb("id", "<", id)])]));
78
+ const rows = await query.execute();
79
+ return toPage(rows.map((row) => VerificationOutcome.parse(row)), limit, (row) => ({
80
+ sort: row.issuedAt.getTime(),
81
+ id: row.id
82
+ }));
83
+ }
84
+ //#endregion
85
+ export { DEFAULT_WINDOW_DAYS, listVerificationOutcomes, resolveVerificationWindow, verificationCounts };
@@ -0,0 +1,35 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { AuthDatabase } from "../data/tables";
4
+ import type { VerificationType } from "../data/verificationOutcome";
5
+ /** The verification ledger's four writers. */
6
+ export interface VerificationLedger {
7
+ /** `verification.create.after`: remember the row, and move a wrong code's ledger row onto its re-issue. */
8
+ created(row: unknown, requestContext: unknown): Promise<void>;
9
+ /** `verification.delete.before`: remember the live row about to be consumed. */
10
+ consuming(row: unknown, requestContext: unknown): void;
11
+ /** The send callback, once the email seam has answered: record the row created in this request. */
12
+ issued(requestContext: unknown, input: IssuedInput): Promise<void>;
13
+ /** `session.create.after`: stamp the row consumed in this request as used, by this user. */
14
+ signedIn(requestContext: unknown, userId: unknown): Promise<void>;
15
+ }
16
+ /** What the send callback knows. The address is read to find the account and is never stored. */
17
+ export interface IssuedInput {
18
+ /** What was issued. */
19
+ type: VerificationType;
20
+ /** Who it was sent to — looked up, never written. */
21
+ email: string;
22
+ /** The `pithy_email_jobs` row that carries it, or null when the seam queued nothing. */
23
+ emailJobId: string | null;
24
+ }
25
+ /** A date off a Better Auth row: a `Date` from the adapter, an ISO string or a number from anywhere else. */
26
+ export declare function dateOf(value: unknown): Date | null;
27
+ /** The id and dates off a verification row, or null for anything not shaped like one. */
28
+ export declare function verificationRowOf(row: unknown): {
29
+ id: string;
30
+ createdAt: Date | null;
31
+ expiresAt: Date;
32
+ } | null;
33
+ /** Build the ledger's writers over one database. `now` is injectable for the tests that pin a clock. */
34
+ export declare function verificationLedger(db: AuthDatabase, now?: () => Date): VerificationLedger;
35
+ //# sourceMappingURL=record.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/ledger/record.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAoDpE,8CAA8C;AAC9C,MAAM,WAAW,kBAAkB;IACjC,2GAA2G;IAC3G,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,gFAAgF;IAChF,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,GAAG,IAAI,CAAC;IACvD,mGAAmG;IACnG,MAAM,CAAC,cAAc,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,4FAA4F;IAC5F,QAAQ,CAAC,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;AAED,iGAAiG;AACjG,MAAM,WAAW,WAAW;IAC1B,uBAAuB;IACvB,IAAI,EAAE,gBAAgB,CAAC;IACvB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,6GAA6G;AAC7G,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,CAIlD;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAO9G;AAED,wGAAwG;AACxG,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,YAAY,EAAE,GAAG,GAAE,MAAM,IAAuB,GAAG,kBAAkB,CA2F3G"}
@@ -0,0 +1,98 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
4
+ //#region src/ledger/record.ts
5
+ /** A date off a Better Auth row: a `Date` from the adapter, an ISO string or a number from anywhere else. */
6
+ function dateOf(value) {
7
+ const date = value instanceof Date ? value : typeof value === "string" || typeof value === "number" ? new Date(value) : null;
8
+ return date && Number.isFinite(date.getTime()) ? date : null;
9
+ }
10
+ /** The id and dates off a verification row, or null for anything not shaped like one. */
11
+ function verificationRowOf(row) {
12
+ if (typeof row !== "object" || row === null) return null;
13
+ const { id, createdAt, expiresAt } = row;
14
+ if (typeof id !== "string" || id === "") return null;
15
+ const expires = dateOf(expiresAt);
16
+ if (!expires) return null;
17
+ return {
18
+ id,
19
+ createdAt: dateOf(createdAt),
20
+ expiresAt: expires
21
+ };
22
+ }
23
+ /** Build the ledger's writers over one database. `now` is injectable for the tests that pin a clock. */
24
+ function verificationLedger(db, now = () => /* @__PURE__ */ new Date()) {
25
+ const pending = /* @__PURE__ */ new WeakMap();
26
+ const stateOf = (requestContext) => {
27
+ if (typeof requestContext !== "object" || requestContext === null) return null;
28
+ let state = pending.get(requestContext);
29
+ if (!state) {
30
+ state = {};
31
+ pending.set(requestContext, state);
32
+ }
33
+ return state;
34
+ };
35
+ return {
36
+ async created(row, requestContext) {
37
+ const state = stateOf(requestContext);
38
+ const verification = verificationRowOf(row);
39
+ if (!state || !verification) return;
40
+ const consumed = state.consuming;
41
+ if (consumed && consumed.expiresAt.getTime() === verification.expiresAt.getTime()) {
42
+ state.consuming = void 0;
43
+ await swallow(() => db.updateTable("pithyAuthVerificationOutcomes").set({ verificationId: verification.id }).where("verificationId", "=", consumed.id).execute());
44
+ }
45
+ state.created = {
46
+ id: verification.id,
47
+ issuedAt: verification.createdAt ?? now(),
48
+ expiresAt: verification.expiresAt
49
+ };
50
+ },
51
+ consuming(row, requestContext) {
52
+ const state = stateOf(requestContext);
53
+ const verification = verificationRowOf(row);
54
+ if (!state || !verification) return;
55
+ if (verification.expiresAt.getTime() <= now().getTime()) return;
56
+ state.consuming = {
57
+ id: verification.id,
58
+ expiresAt: verification.expiresAt
59
+ };
60
+ },
61
+ async issued(requestContext, input) {
62
+ const state = stateOf(requestContext);
63
+ const created = state?.created;
64
+ if (!state || !created) return;
65
+ state.created = void 0;
66
+ await swallow(async () => {
67
+ const user = await db.selectFrom("pithyAuthUsers").select("id").where("email", "=", input.email.toLowerCase()).executeTakeFirst();
68
+ await db.insertInto("pithyAuthVerificationOutcomes").values({
69
+ verificationId: created.id,
70
+ type: input.type,
71
+ userId: user?.id ?? null,
72
+ emailJobId: input.emailJobId,
73
+ issuedAt: SQLiteDate.encode(created.issuedAt),
74
+ expiresAt: SQLiteDate.encode(created.expiresAt),
75
+ usedAt: null
76
+ }).execute();
77
+ });
78
+ },
79
+ async signedIn(requestContext, userId) {
80
+ const state = stateOf(requestContext);
81
+ const consumed = state?.consuming;
82
+ if (!state || !consumed || typeof userId !== "string" || userId === "") return;
83
+ state.consuming = void 0;
84
+ await swallow(() => db.updateTable("pithyAuthVerificationOutcomes").set((eb) => ({
85
+ usedAt: SQLiteDate.encode(now()),
86
+ userId: eb.fn.coalesce("userId", eb.val(userId))
87
+ })).where("verificationId", "=", consumed.id).where("usedAt", "is", null).execute());
88
+ }
89
+ };
90
+ }
91
+ /** Run a ledger write and drop its failure: the ledger reports on sign-in and is never the reason one fails. */
92
+ async function swallow(write) {
93
+ try {
94
+ await write();
95
+ } catch {}
96
+ }
97
+ //#endregion
98
+ export { dateOf, verificationLedger, verificationRowOf };
@@ -0,0 +1,48 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { AuditEmit } from "@pithy-sh/core/src/audit/recorder";
4
+ /**
5
+ * Every control-plane lifecycle call is audited, including the ones that changed nothing (#621).
6
+ *
7
+ * A transition that moves the account writes its own audit event, beside the history row, in
8
+ * `./transitions.ts`. That leaves two kinds of call with no event, and both matter to somebody reading the
9
+ * trail after an incident: **a refusal** — an unknown account, a deleted one, an end in the past — which says
10
+ * a credential was trying, and **a call that found the account already where it asked to put it**, which
11
+ * says somebody pressed the button. This records both, under the same action as the transition, so one
12
+ * filter finds every attempt: a refusal is `denied` (or `failure` for a fault) with the code, and a no-op is
13
+ * a `success` with `changed: false`. A refusal is still thrown, unchanged.
14
+ *
15
+ * A body the route's validator refuses never reaches the call, so the route records it with
16
+ * {@link recordLifecycleRefusal}, on the same event, before the 400 is thrown.
17
+ */
18
+ /** Who called, about whom, and why — what every lifecycle audit event carries. */
19
+ export interface LifecycleCall {
20
+ /** The audit action the transition writes when it moves the account. */
21
+ readonly action: string;
22
+ /** The management client's verified `sub`: which person acted. */
23
+ readonly subject: string;
24
+ /** The connection the call came through. */
25
+ readonly connectionId: string;
26
+ /** The account acted on. */
27
+ readonly userId: string;
28
+ /** The reason the caller gave — `null` for a refused body that carried none. */
29
+ readonly reason: string | null;
30
+ /** The request's correlation. */
31
+ readonly ip?: string | undefined;
32
+ readonly userAgent?: string | undefined;
33
+ readonly requestId?: string | undefined;
34
+ }
35
+ /**
36
+ * Record one refused lifecycle call — `denied` with its code, or `failure` for a fault. `code` names the
37
+ * refusal when the thrown error carries none of its own, as a body Hono could not parse does not.
38
+ */
39
+ export declare function recordLifecycleRefusal(emit: AuditEmit, call: LifecycleCall, error: unknown, fallback?: {
40
+ code: string;
41
+ outcome: "denied" | "failure";
42
+ }): Promise<void>;
43
+ /**
44
+ * Run one lifecycle call and audit whatever the transition did not. `unchanged` says whether a result is a
45
+ * call that changed nothing; the event for a call that did change something is the transition's own.
46
+ */
47
+ export declare function auditedLifecycleCall<T>(emit: AuditEmit, call: LifecycleCall, run: () => Promise<T>, unchanged: (result: T) => boolean): Promise<T>;
48
+ //# sourceMappingURL=audited.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"audited.d.ts","sourceRoot":"","sources":["../../src/lifecycle/audited.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAInE;;;;;;;;;;;;;GAaG;AAEH,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iCAAiC;IACjC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AA0BD;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,OAAO,EACd,QAAQ,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAA;CAAE,GACzD,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,aAAa,EACnB,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACrB,SAAS,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,GAChC,OAAO,CAAC,CAAC,CAAC,CAYZ"}
@@ -0,0 +1,65 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { emitControlPlaneAction } from "../audit/emit.js";
4
+ import { PithyError } from "@pithy-sh/core/src/error/pithyError";
5
+ //#region src/lifecycle/audited.ts
6
+ /** The public code of a thrown error, or `core/internal` for anything that is not a `PithyError`. */
7
+ function codeOf(error) {
8
+ return error instanceof PithyError ? error.payload.code : "core/internal";
9
+ }
10
+ /** A refusal this Worker made on purpose is `denied`; a fault, a 5xx or a throw that is not ours, `failure`. */
11
+ function outcomeOf(error) {
12
+ return error instanceof PithyError && error.payload.status < 500 ? "denied" : "failure";
13
+ }
14
+ /** The event every lifecycle audit record shares, before its outcome and metadata. */
15
+ function eventOf(call) {
16
+ return {
17
+ action: call.action,
18
+ subject: call.subject,
19
+ connectionId: call.connectionId,
20
+ resourceType: "user",
21
+ resourceId: call.userId,
22
+ ip: call.ip,
23
+ userAgent: call.userAgent,
24
+ requestId: call.requestId
25
+ };
26
+ }
27
+ /**
28
+ * Record one refused lifecycle call — `denied` with its code, or `failure` for a fault. `code` names the
29
+ * refusal when the thrown error carries none of its own, as a body Hono could not parse does not.
30
+ */
31
+ async function recordLifecycleRefusal(emit, call, error, fallback) {
32
+ const ours = error instanceof PithyError;
33
+ await emitControlPlaneAction(emit, {
34
+ ...eventOf(call),
35
+ outcome: ours || !fallback ? outcomeOf(error) : fallback.outcome,
36
+ metadata: {
37
+ reason: call.reason,
38
+ changed: false,
39
+ code: ours || !fallback ? codeOf(error) : fallback.code
40
+ }
41
+ });
42
+ }
43
+ /**
44
+ * Run one lifecycle call and audit whatever the transition did not. `unchanged` says whether a result is a
45
+ * call that changed nothing; the event for a call that did change something is the transition's own.
46
+ */
47
+ async function auditedLifecycleCall(emit, call, run, unchanged) {
48
+ let result;
49
+ try {
50
+ result = await run();
51
+ } catch (error) {
52
+ await recordLifecycleRefusal(emit, call, error);
53
+ throw error;
54
+ }
55
+ if (unchanged(result)) await emitControlPlaneAction(emit, {
56
+ ...eventOf(call),
57
+ metadata: {
58
+ reason: call.reason,
59
+ changed: false
60
+ }
61
+ });
62
+ return result;
63
+ }
64
+ //#endregion
65
+ export { auditedLifecycleCall, recordLifecycleRefusal };
@@ -33,8 +33,43 @@ export declare function readLifecycleColumns(db: AuthDatabase, userId: string):
33
33
  * read here, which is the sign-in path: a session about to be created has no user object yet.
34
34
  */
35
35
  export declare function lifecycleRefusalFor(db: AuthDatabase, userId: string, columns: Partial<LifecycleColumns> | null | undefined, now: Date): Promise<PithyError | null>;
36
- /** Remember that this request's credential belongs to an account that may not act. */
37
- export declare function noteRefusal(context: object, refusal: PithyError): void;
36
+ /** The holder of a refused credential: whose session it is. Known because the credential itself is genuine. */
37
+ export interface RefusedHolder {
38
+ /** The account the session belongs to. */
39
+ readonly userId: string;
40
+ /** The session the request presented. */
41
+ readonly sessionId: string;
42
+ }
43
+ /** Remember that this request's credential belongs to an account that may not act, and whose it is. */
44
+ export declare function noteRefusal(context: object, refusal: PithyError, holder?: RefusedHolder): void;
38
45
  /** The refusal the session middleware reached for this request, if it reached one. */
39
46
  export declare function noticedRefusal(context: object): PithyError | undefined;
47
+ /**
48
+ * The holder of a **suspended** account's credential on this request, or `undefined` (#622).
49
+ *
50
+ * Only a suspension: a deleted account has nothing left to delete, and a check that could not be made has
51
+ * established nobody. The one reader is the self-service deletion, through `../http/middleware.ts`.
52
+ */
53
+ export declare function suspendedHolder(context: object): RefusedHolder | undefined;
54
+ /**
55
+ * The header a sign-in carries to ask for a session that can do nothing but delete its account, and the one
56
+ * value it takes (#622).
57
+ *
58
+ * A suspension revokes every session the account holds and refuses every new one, so without this a suspended
59
+ * person would hold no credential and could get none — and the one route a suspension leaves open, deleting the
60
+ * account, would be one nobody could reach. With it, the sign-in completes: the person still proves who they are,
61
+ * by the code, the link or the provider, exactly as for any sign-in. **The session that results is still a
62
+ * suspended account's**, so the session middleware refuses it everywhere, Better Auth's own endpoints included,
63
+ * and only `DELETE /auth/account` admits it. Nothing about the header is trusted beyond that: it asks for a
64
+ * session no more capable than none, save for leaving.
65
+ */
66
+ export declare const ACCOUNT_DELETION_INTENT_HEADER = "x-pithy-intent";
67
+ /** The value of `ACCOUNT_DELETION_INTENT_HEADER` that asks for a deletion-only session. */
68
+ export declare const ACCOUNT_DELETION_INTENT = "delete-account";
69
+ /**
70
+ * Whether a sign-in refused with `refusal` may still create its session: only a **suspended** account's, and only
71
+ * when the request asks for nothing but deleting it. A deleted account has nothing left to delete, and a check
72
+ * that could not be made has established nobody, so neither is admitted.
73
+ */
74
+ export declare function admitsDeletionSignIn(refusal: PithyError, headers: Headers | null | undefined): boolean;
40
75
  //# sourceMappingURL=enforce.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"enforce.d.ts","sourceRoot":"","sources":["../../src/lifecycle/enforce.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAmB,gBAAgB,EAAoB,MAAM,SAAS,CAAC;AAE9E;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iHAAiH;AACjH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAW/F;AAED,kGAAkG;AAClG,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAO7G;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI,GAAG,SAAS,EACrD,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAM5B;AAYD,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAEtE;AAED,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAEtE"}
1
+ {"version":3,"file":"enforce.d.ts","sourceRoot":"","sources":["../../src/lifecycle/enforce.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAmB,gBAAgB,EAAoB,MAAM,SAAS,CAAC;AAE9E;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iHAAiH;AACjH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAW/F;AAED,kGAAkG;AAClG,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAO7G;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI,GAAG,SAAS,EACrD,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAM5B;AAED,+GAA+G;AAC/G,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAgBD,uGAAuG;AACvG,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,CAE9F;AAED,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAEtE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAG1E;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,8BAA8B,mBAAmB,CAAC;AAC/D,2FAA2F;AAC3F,eAAO,MAAM,uBAAuB,mBAAmB,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAItG"}
@@ -56,15 +56,56 @@ async function lifecycleRefusalFor(db, userId, columns, now) {
56
56
  * capability's own guards read — a refused account already has no `AuthContext`, which is the part every
57
57
  * other capability's guard needs. Keyed by the context the way `../http/resolve.ts` caches the instance, so
58
58
  * it dies with the request.
59
+ *
60
+ * **The holder rides with it (#622).** A suspended account may still delete itself — the app stores require
61
+ * that a person can always leave — and that one route has to know whose account the refused credential
62
+ * opens. Nothing else reads it: the holder is reachable only through `accountHolder`, and only that route uses it.
59
63
  */
60
64
  const refusals = /* @__PURE__ */ new WeakMap();
61
- /** Remember that this request's credential belongs to an account that may not act. */
62
- function noteRefusal(context, refusal) {
63
- refusals.set(context, refusal);
65
+ /** Remember that this request's credential belongs to an account that may not act, and whose it is. */
66
+ function noteRefusal(context, refusal, holder) {
67
+ refusals.set(context, {
68
+ refusal,
69
+ holder
70
+ });
64
71
  }
65
72
  /** The refusal the session middleware reached for this request, if it reached one. */
66
73
  function noticedRefusal(context) {
67
- return refusals.get(context);
74
+ return refusals.get(context)?.refusal;
75
+ }
76
+ /**
77
+ * The holder of a **suspended** account's credential on this request, or `undefined` (#622).
78
+ *
79
+ * Only a suspension: a deleted account has nothing left to delete, and a check that could not be made has
80
+ * established nobody. The one reader is the self-service deletion, through `../http/middleware.ts`.
81
+ */
82
+ function suspendedHolder(context) {
83
+ const noted = refusals.get(context);
84
+ return noted?.refusal.payload.code === "auth/account_suspended" ? noted.holder : void 0;
85
+ }
86
+ /**
87
+ * The header a sign-in carries to ask for a session that can do nothing but delete its account, and the one
88
+ * value it takes (#622).
89
+ *
90
+ * A suspension revokes every session the account holds and refuses every new one, so without this a suspended
91
+ * person would hold no credential and could get none — and the one route a suspension leaves open, deleting the
92
+ * account, would be one nobody could reach. With it, the sign-in completes: the person still proves who they are,
93
+ * by the code, the link or the provider, exactly as for any sign-in. **The session that results is still a
94
+ * suspended account's**, so the session middleware refuses it everywhere, Better Auth's own endpoints included,
95
+ * and only `DELETE /auth/account` admits it. Nothing about the header is trusted beyond that: it asks for a
96
+ * session no more capable than none, save for leaving.
97
+ */
98
+ const ACCOUNT_DELETION_INTENT_HEADER = "x-pithy-intent";
99
+ /** The value of `ACCOUNT_DELETION_INTENT_HEADER` that asks for a deletion-only session. */
100
+ const ACCOUNT_DELETION_INTENT = "delete-account";
101
+ /**
102
+ * Whether a sign-in refused with `refusal` may still create its session: only a **suspended** account's, and only
103
+ * when the request asks for nothing but deleting it. A deleted account has nothing left to delete, and a check
104
+ * that could not be made has established nobody, so neither is admitted.
105
+ */
106
+ function admitsDeletionSignIn(refusal, headers) {
107
+ if (refusal.payload.code !== "auth/account_suspended") return false;
108
+ return headers?.get(ACCOUNT_DELETION_INTENT_HEADER)?.trim().toLowerCase() === ACCOUNT_DELETION_INTENT;
68
109
  }
69
110
  //#endregion
70
- export { lifecycleRefusalFor, noteRefusal, noticedRefusal, readLifecycleColumns, suspensionReason };
111
+ export { ACCOUNT_DELETION_INTENT, ACCOUNT_DELETION_INTENT_HEADER, admitsDeletionSignIn, lifecycleRefusalFor, noteRefusal, noticedRefusal, readLifecycleColumns, suspendedHolder, suspensionReason };
@@ -0,0 +1,9 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { ErasureHistoryReader, ErasureRecords } from "@pithy-sh/core/src/capability/erasure";
4
+ import { type AuthDatabase } from "../data/tables";
5
+ /** The reader, over one auth database. */
6
+ export declare function userErasureReader(db: AuthDatabase): ErasureHistoryReader;
7
+ /** What auth declares: the `user` subject, the actions its purge records, and the reader over its database. */
8
+ export declare function authErasureRecords(database: string): ErasureRecords;
9
+ //# sourceMappingURL=erasure.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"erasure.d.ts","sourceRoot":"","sources":["../../src/lifecycle/erasure.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAqB,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAGrH,OAAO,EAAE,KAAK,YAAY,EAAgB,MAAM,gBAAgB,CAAC;AAqBjE,0CAA0C;AAC1C,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,YAAY,GAAG,oBAAoB,CAsExE;AAED,+GAA+G;AAC/G,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAgBnE"}