@pithy-sh/auth 0.11.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 (246) hide show
  1. package/README.md +30 -2
  2. package/dist/audit/actions.d.ts +39 -0
  3. package/dist/audit/actions.d.ts.map +1 -1
  4. package/dist/audit/actions.js +40 -1
  5. package/dist/audit/emit.d.ts +34 -0
  6. package/dist/audit/emit.d.ts.map +1 -1
  7. package/dist/audit/emit.js +47 -1
  8. package/dist/audit/evidence.d.ts +8 -2
  9. package/dist/audit/evidence.d.ts.map +1 -1
  10. package/dist/capability.d.ts +31 -11
  11. package/dist/capability.d.ts.map +1 -1
  12. package/dist/capability.js +38 -5
  13. package/dist/client/api.d.ts +55 -12
  14. package/dist/client/api.d.ts.map +1 -1
  15. package/dist/client/api.js +57 -18
  16. package/dist/client/bearer.d.ts +110 -0
  17. package/dist/client/bearer.d.ts.map +1 -0
  18. package/dist/client/bearer.js +265 -0
  19. package/dist/client/handoff.d.ts +77 -0
  20. package/dist/client/handoff.d.ts.map +1 -0
  21. package/dist/client/handoff.js +119 -0
  22. package/dist/client/mcp.d.ts +70 -0
  23. package/dist/client/mcp.d.ts.map +1 -0
  24. package/dist/client/mcp.js +65 -0
  25. package/dist/data/betterAuth.d.ts +3 -2
  26. package/dist/data/betterAuth.d.ts.map +1 -1
  27. package/dist/data/betterAuth.js +5 -3
  28. package/dist/data/kitFields.d.ts +5 -0
  29. package/dist/data/kitFields.d.ts.map +1 -1
  30. package/dist/data/kitFields.js +5 -0
  31. package/dist/data/tables.d.ts +25 -4
  32. package/dist/data/tables.d.ts.map +1 -1
  33. package/dist/data/tables.js +5 -3
  34. package/dist/data/userLifecycle.d.ts +9 -0
  35. package/dist/data/userLifecycle.d.ts.map +1 -1
  36. package/dist/data/userLifecycle.js +6 -2
  37. package/dist/data/verificationOutcome.d.ts +53 -0
  38. package/dist/data/verificationOutcome.d.ts.map +1 -0
  39. package/dist/data/verificationOutcome.js +50 -0
  40. package/dist/email/send.js +6 -2
  41. package/dist/http/adminRoutes.d.ts.map +1 -1
  42. package/dist/http/adminRoutes.js +56 -10
  43. package/dist/http/csrf.d.ts.map +1 -1
  44. package/dist/http/csrf.js +2 -1
  45. package/dist/http/guards.d.ts +15 -11
  46. package/dist/http/guards.d.ts.map +1 -1
  47. package/dist/http/guards.js +46 -11
  48. package/dist/http/handoff.d.ts +76 -0
  49. package/dist/http/handoff.d.ts.map +1 -0
  50. package/dist/http/handoff.js +316 -0
  51. package/dist/http/middleware.d.ts +12 -0
  52. package/dist/http/middleware.d.ts.map +1 -1
  53. package/dist/http/middleware.js +25 -4
  54. package/dist/http/resolve.d.ts.map +1 -1
  55. package/dist/http/resolve.js +9 -3
  56. package/dist/http/responses.d.ts +142 -0
  57. package/dist/http/responses.d.ts.map +1 -1
  58. package/dist/http/responses.js +66 -10
  59. package/dist/http/routes.d.ts +2 -0
  60. package/dist/http/routes.d.ts.map +1 -1
  61. package/dist/http/routes.js +35 -4
  62. package/dist/http/schemas.d.ts +57 -0
  63. package/dist/http/schemas.d.ts.map +1 -1
  64. package/dist/http/schemas.js +44 -1
  65. package/dist/http/views.d.ts +22 -2
  66. package/dist/http/views.d.ts.map +1 -1
  67. package/dist/http/views.js +40 -4
  68. package/dist/index.d.ts +2 -0
  69. package/dist/index.d.ts.map +1 -1
  70. package/dist/index.js +4 -2
  71. package/dist/instance/auth.d.ts +148 -10
  72. package/dist/instance/auth.d.ts.map +1 -1
  73. package/dist/instance/auth.js +86 -41
  74. package/dist/instance/plugins.d.ts +6 -0
  75. package/dist/instance/plugins.d.ts.map +1 -1
  76. package/dist/instance/plugins.js +14 -1
  77. package/dist/ledger/read.d.ts +53 -0
  78. package/dist/ledger/read.d.ts.map +1 -0
  79. package/dist/ledger/read.js +85 -0
  80. package/dist/ledger/record.d.ts +35 -0
  81. package/dist/ledger/record.d.ts.map +1 -0
  82. package/dist/ledger/record.js +98 -0
  83. package/dist/lifecycle/erasure.d.ts +9 -0
  84. package/dist/lifecycle/erasure.d.ts.map +1 -0
  85. package/dist/lifecycle/erasure.js +96 -0
  86. package/dist/lifecycle/inactivity.d.ts +19 -0
  87. package/dist/lifecycle/inactivity.d.ts.map +1 -0
  88. package/dist/lifecycle/inactivity.js +28 -0
  89. package/dist/lifecycle/transitions.d.ts +22 -1
  90. package/dist/lifecycle/transitions.d.ts.map +1 -1
  91. package/dist/lifecycle/transitions.js +51 -4
  92. package/dist/mcp/argumentClass.d.ts +51 -0
  93. package/dist/mcp/argumentClass.d.ts.map +1 -0
  94. package/dist/mcp/argumentClass.js +69 -0
  95. package/dist/mcp/capability.d.ts +50 -0
  96. package/dist/mcp/capability.d.ts.map +1 -0
  97. package/dist/mcp/capability.js +140 -0
  98. package/dist/mcp/clientMetadata.d.ts +40 -0
  99. package/dist/mcp/clientMetadata.d.ts.map +1 -0
  100. package/dist/mcp/clientMetadata.js +68 -0
  101. package/dist/mcp/consent.d.ts +49 -0
  102. package/dist/mcp/consent.d.ts.map +1 -0
  103. package/dist/mcp/consent.js +69 -0
  104. package/dist/mcp/dispatch.d.ts +35 -0
  105. package/dist/mcp/dispatch.d.ts.map +1 -0
  106. package/dist/mcp/dispatch.js +135 -0
  107. package/dist/mcp/floor.d.ts +37 -0
  108. package/dist/mcp/floor.d.ts.map +1 -0
  109. package/dist/mcp/floor.js +41 -0
  110. package/dist/mcp/host.d.ts +34 -0
  111. package/dist/mcp/host.d.ts.map +1 -0
  112. package/dist/mcp/host.js +2 -0
  113. package/dist/mcp/http/redirectList.d.ts +9 -0
  114. package/dist/mcp/http/redirectList.d.ts.map +1 -0
  115. package/dist/mcp/http/redirectList.js +24 -0
  116. package/dist/mcp/http/responses.d.ts +143 -0
  117. package/dist/mcp/http/responses.d.ts.map +1 -0
  118. package/dist/mcp/http/responses.js +83 -0
  119. package/dist/mcp/http/routes.d.ts +28 -0
  120. package/dist/mcp/http/routes.d.ts.map +1 -0
  121. package/dist/mcp/http/routes.js +517 -0
  122. package/dist/mcp/http/schemas.d.ts +24 -0
  123. package/dist/mcp/http/schemas.d.ts.map +1 -0
  124. package/dist/mcp/http/schemas.js +18 -0
  125. package/dist/mcp/marker.d.ts +15 -0
  126. package/dist/mcp/marker.d.ts.map +1 -0
  127. package/dist/mcp/marker.js +15 -0
  128. package/dist/mcp/provider.d.ts +78 -0
  129. package/dist/mcp/provider.d.ts.map +1 -0
  130. package/dist/mcp/provider.js +108 -0
  131. package/dist/mcp/purge.d.ts +15 -0
  132. package/dist/mcp/purge.d.ts.map +1 -0
  133. package/dist/mcp/purge.js +31 -0
  134. package/dist/mcp/rpc.d.ts +79 -0
  135. package/dist/mcp/rpc.d.ts.map +1 -0
  136. package/dist/mcp/rpc.js +103 -0
  137. package/dist/mcp/toolAudit.d.ts +76 -0
  138. package/dist/mcp/toolAudit.d.ts.map +1 -0
  139. package/dist/mcp/toolAudit.js +86 -0
  140. package/dist/migrations/0006_verification_outcomes.d.ts +15 -0
  141. package/dist/migrations/0006_verification_outcomes.d.ts.map +1 -0
  142. package/dist/migrations/0006_verification_outcomes.js +35 -0
  143. package/dist/migrations/0007_erasure_record.d.ts +17 -0
  144. package/dist/migrations/0007_erasure_record.d.ts.map +1 -0
  145. package/dist/migrations/0007_erasure_record.js +36 -0
  146. package/dist/migrations/0008_last_active.d.ts +15 -0
  147. package/dist/migrations/0008_last_active.d.ts.map +1 -0
  148. package/dist/migrations/0008_last_active.js +29 -0
  149. package/dist/migrations/set.d.ts +4 -1
  150. package/dist/migrations/set.d.ts.map +1 -1
  151. package/dist/migrations/set.js +8 -2
  152. package/dist/peer.d.ts +3 -2
  153. package/dist/peer.d.ts.map +1 -1
  154. package/dist/processing/activities.d.ts +6 -0
  155. package/dist/processing/activities.d.ts.map +1 -0
  156. package/dist/processing/activities.js +12 -0
  157. package/dist/purge/contribution.d.ts +20 -5
  158. package/dist/purge/contribution.d.ts.map +1 -1
  159. package/dist/purge/contribution.js +20 -6
  160. package/dist/purge/run.d.ts +75 -5
  161. package/dist/purge/run.d.ts.map +1 -1
  162. package/dist/purge/run.js +117 -14
  163. package/dist/purge/workflow.d.ts +15 -2
  164. package/dist/purge/workflow.d.ts.map +1 -1
  165. package/dist/purge/workflow.js +51 -7
  166. package/dist/test-utils/accountFootprint.d.ts +5 -2
  167. package/dist/test-utils/accountFootprint.d.ts.map +1 -1
  168. package/dist/test-utils/accountFootprint.js +7 -2
  169. package/dist/test-utils/liveApp.d.ts +6 -0
  170. package/dist/test-utils/liveApp.d.ts.map +1 -1
  171. package/dist/test-utils/liveApp.js +7 -2
  172. package/dist/token/handoff.d.ts +80 -0
  173. package/dist/token/handoff.d.ts.map +1 -0
  174. package/dist/token/handoff.js +136 -0
  175. package/dist/version.generated.d.ts +1 -1
  176. package/dist/version.generated.js +1 -1
  177. package/docs/account-lifecycle.md +59 -7
  178. package/docs/apple-signin.md +32 -4
  179. package/docs/facebook-oauth.md +2 -2
  180. package/docs/github-oauth.md +2 -2
  181. package/docs/google-oauth.md +9 -7
  182. package/docs/microsoft-oauth.md +2 -2
  183. package/package.json +11 -5
  184. package/pithy.manifest.json +2 -2
  185. package/pithy.mcp.manifest.json +36 -0
  186. package/src/audit/actions.ts +39 -0
  187. package/src/audit/emit.ts +63 -0
  188. package/src/audit/evidence.ts +8 -4
  189. package/src/capability.ts +80 -23
  190. package/src/client/api.ts +69 -19
  191. package/src/client/bearer.ts +388 -0
  192. package/src/client/handoff.ts +172 -0
  193. package/src/client/mcp.ts +140 -0
  194. package/src/data/betterAuth.ts +8 -4
  195. package/src/data/kitFields.ts +2 -0
  196. package/src/data/tables.ts +4 -2
  197. package/src/data/userLifecycle.ts +15 -3
  198. package/src/data/verificationOutcome.ts +86 -0
  199. package/src/email/send.ts +2 -2
  200. package/src/http/adminRoutes.ts +68 -3
  201. package/src/http/csrf.ts +4 -1
  202. package/src/http/guards.ts +48 -11
  203. package/src/http/handoff.ts +350 -0
  204. package/src/http/middleware.ts +29 -3
  205. package/src/http/resolve.ts +25 -25
  206. package/src/http/responses.ts +134 -8
  207. package/src/http/routes.ts +63 -4
  208. package/src/http/schemas.ts +85 -0
  209. package/src/http/views.ts +46 -2
  210. package/src/index.ts +2 -0
  211. package/src/instance/auth.ts +51 -1
  212. package/src/instance/plugins.ts +20 -2
  213. package/src/ledger/read.ts +133 -0
  214. package/src/ledger/record.ts +198 -0
  215. package/src/lifecycle/erasure.ts +118 -0
  216. package/src/lifecycle/inactivity.ts +56 -0
  217. package/src/lifecycle/transitions.ts +75 -5
  218. package/src/mcp/argumentClass.ts +112 -0
  219. package/src/mcp/capability.ts +194 -0
  220. package/src/mcp/clientMetadata.ts +81 -0
  221. package/src/mcp/consent.ts +95 -0
  222. package/src/mcp/dispatch.ts +154 -0
  223. package/src/mcp/floor.ts +62 -0
  224. package/src/mcp/host.ts +36 -0
  225. package/src/mcp/http/redirectList.ts +26 -0
  226. package/src/mcp/http/responses.ts +157 -0
  227. package/src/mcp/http/routes.ts +635 -0
  228. package/src/mcp/http/schemas.ts +37 -0
  229. package/src/mcp/marker.ts +18 -0
  230. package/src/mcp/provider.ts +151 -0
  231. package/src/mcp/purge.ts +39 -0
  232. package/src/mcp/rpc.ts +135 -0
  233. package/src/mcp/toolAudit.ts +132 -0
  234. package/src/migrations/0006_verification_outcomes.ts +51 -0
  235. package/src/migrations/0007_erasure_record.ts +43 -0
  236. package/src/migrations/0008_last_active.ts +30 -0
  237. package/src/migrations/set.ts +7 -1
  238. package/src/processing/activities.ts +14 -0
  239. package/src/purge/contribution.ts +37 -10
  240. package/src/purge/run.ts +179 -16
  241. package/src/purge/workflow.ts +65 -7
  242. package/src/seeds/example.ts +2 -2
  243. package/src/test-utils/accountFootprint.ts +10 -1
  244. package/src/test-utils/liveApp.ts +10 -1
  245. package/src/token/handoff.ts +180 -0
  246. package/src/version.generated.ts +1 -1
@@ -0,0 +1,53 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { z } from "zod";
4
+ /**
5
+ * `pithy_auth_verification_outcomes` — the verification ledger (#829): one row per sign-in link or code auth
6
+ * issued, and whether it was used.
7
+ *
8
+ * **Why a ledger, and not a read of `pithy_auth_verifications`.** Better Auth consumes a verification row on its
9
+ * first use and deletes it, so a used link leaves nothing behind, and an unused one looks exactly like one still
10
+ * waiting until the cleanup on some later read takes it. "How many sign-ins failed because mail did not land"
11
+ * needs both halves, so auth writes its own record: when it issues, and again when the link or code is used.
12
+ *
13
+ * **Never the token, never the address.** The row names the verification by its row id, the person by their user
14
+ * id where one exists, and the mail by its `pithy_email_jobs` id — which is where the address already lives,
15
+ * under email's own retention. A sign-up has no user when its link is sent, so its row joins to its mail by the
16
+ * job id alone and gains the user id when the link is used and the account exists.
17
+ *
18
+ * **No foreign key, to the user or to the job.** The two live in different capabilities' tables, and a purge of
19
+ * the account erases its rows here by user id (`../purge/contribution.ts`).
20
+ *
21
+ * Written by the kit through its own Kysely, so its dates take the house ms-epoch `SQLiteDate`.
22
+ */
23
+ /** What was issued. */
24
+ export declare const VerificationType: z.ZodEnum<{
25
+ magic_link: "magic_link";
26
+ otp: "otp";
27
+ }>;
28
+ export type VerificationType = z.output<typeof VerificationType>;
29
+ /** One issued link or code, as stored. */
30
+ export declare const VerificationOutcome: z.ZodObject<{
31
+ id: z.ZodNumber;
32
+ verificationId: z.ZodString;
33
+ type: z.ZodEnum<{
34
+ magic_link: "magic_link";
35
+ otp: "otp";
36
+ }>;
37
+ userId: z.ZodNullable<z.ZodString>;
38
+ emailJobId: z.ZodNullable<z.ZodString>;
39
+ issuedAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
40
+ expiresAt: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
41
+ usedAt: z.ZodNullable<z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>>;
42
+ }, z.core.$strip>;
43
+ export type VerificationOutcome = z.output<typeof VerificationOutcome>;
44
+ /** Where an issued link or code stands at a moment: used, expired unused, or still pending. */
45
+ export declare const VerificationState: z.ZodEnum<{
46
+ expired: "expired";
47
+ pending: "pending";
48
+ used: "used";
49
+ }>;
50
+ export type VerificationState = z.output<typeof VerificationState>;
51
+ /** Where one row stands at `now`. Used wins over expiry: a link used a second before it ran out was used. */
52
+ export declare function verificationStateAt(row: Pick<VerificationOutcome, "expiresAt" | "usedAt">, now: Date): VerificationState;
53
+ //# sourceMappingURL=verificationOutcome.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"verificationOutcome.d.ts","sourceRoot":"","sources":["../../src/data/verificationOutcome.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,uBAAuB;AACvB,eAAO,MAAM,gBAAgB;;;EAI1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE,0CAA0C;AAC1C,eAAO,MAAM,mBAAmB;;;;;;;;;;;;iBAgC7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB;;;;EAI3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE,6GAA6G;AAC7G,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,GAAG,QAAQ,CAAC,EACtD,GAAG,EAAE,IAAI,GACR,iBAAiB,CAGnB"}
@@ -0,0 +1,50 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { z } from "zod";
4
+ import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
5
+ //#region src/data/verificationOutcome.ts
6
+ /**
7
+ * `pithy_auth_verification_outcomes` — the verification ledger (#829): one row per sign-in link or code auth
8
+ * issued, and whether it was used.
9
+ *
10
+ * **Why a ledger, and not a read of `pithy_auth_verifications`.** Better Auth consumes a verification row on its
11
+ * first use and deletes it, so a used link leaves nothing behind, and an unused one looks exactly like one still
12
+ * waiting until the cleanup on some later read takes it. "How many sign-ins failed because mail did not land"
13
+ * needs both halves, so auth writes its own record: when it issues, and again when the link or code is used.
14
+ *
15
+ * **Never the token, never the address.** The row names the verification by its row id, the person by their user
16
+ * id where one exists, and the mail by its `pithy_email_jobs` id — which is where the address already lives,
17
+ * under email's own retention. A sign-up has no user when its link is sent, so its row joins to its mail by the
18
+ * job id alone and gains the user id when the link is used and the account exists.
19
+ *
20
+ * **No foreign key, to the user or to the job.** The two live in different capabilities' tables, and a purge of
21
+ * the account erases its rows here by user id (`../purge/contribution.ts`).
22
+ *
23
+ * Written by the kit through its own Kysely, so its dates take the house ms-epoch `SQLiteDate`.
24
+ */
25
+ /** What was issued. */
26
+ const VerificationType = z.enum(["magic_link", "otp"]).describe("What was issued: `magic_link`, a sign-in link; `otp`, a one-time sign-in code. The only two auth sends — it composes no password, so no reset, and no separate email-verification mail.");
27
+ /** One issued link or code, as stored. */
28
+ const VerificationOutcome = z.object({
29
+ id: z.number().int().describe("Primary key. Auto-incrementing, so two rows issued in the same millisecond keep their order."),
30
+ verificationId: z.string().describe("The `pithy_auth_verifications` row that carries this link or code. A wrong code is re-issued under a new row with the same expiry, and this follows it. Indexed."),
31
+ type: VerificationType.describe("What was issued."),
32
+ userId: z.string().nullable().describe("The account it signs in to, when one existed at issue or was created by its use. Null for a sign-up nobody completed. Indexed, so a purge finds the account's rows."),
33
+ emailJobId: z.string().nullable().describe("The `pithy_email_jobs` row that carried it — how a reader joins it to a bounce, a deferral or a suppression. Null when the email seam failed and nothing was queued."),
34
+ issuedAt: SQLiteDate.describe("When it was issued. Ms-epoch in SQLite; a `Date` in app code."),
35
+ expiresAt: SQLiteDate.describe("When it stops working, used or not. Ms-epoch in SQLite."),
36
+ usedAt: SQLiteDate.nullable().describe("When it was used to sign in, or null while it has not been. Ms-epoch in SQLite.")
37
+ }).describe("One sign-in link or code in `pithy_auth_verification_outcomes`: what it was, whose, the mail that carried it, and when it was issued, expires and was used. Never the token or the address.");
38
+ /** Where an issued link or code stands at a moment: used, expired unused, or still pending. */
39
+ const VerificationState = z.enum([
40
+ "used",
41
+ "expired",
42
+ "pending"
43
+ ]).describe("Where it stands: `used`, it signed somebody in; `expired`, it ran out unused; `pending`, it is unused and still works.");
44
+ /** Where one row stands at `now`. Used wins over expiry: a link used a second before it ran out was used. */
45
+ function verificationStateAt(row, now) {
46
+ if (row.usedAt !== null) return "used";
47
+ return row.expiresAt.getTime() <= now.getTime() ? "expired" : "pending";
48
+ }
49
+ //#endregion
50
+ export { VerificationOutcome, VerificationState, VerificationType, verificationStateAt };
@@ -64,9 +64,13 @@ function makeSendAuthEmail(enqueue, expiresMinutes, localeFor) {
64
64
  function deliveryOf(result) {
65
65
  if (result.status === "suppressed") return {
66
66
  delivery: "withheld",
67
- reason: result.suppressionReason ?? result.status
67
+ reason: result.suppressionReason ?? result.status,
68
+ jobId: result.jobId
69
+ };
70
+ return {
71
+ delivery: "queued",
72
+ jobId: result.jobId
68
73
  };
69
- return { delivery: "queued" };
70
74
  }
71
75
  //#endregion
72
76
  export { makeSendAuthEmail };
@@ -1 +1 @@
1
- {"version":3,"file":"adminRoutes.d.ts","sourceRoot":"","sources":["../../src/http/adminRoutes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAS7E,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAe1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAuThD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAyc7F"}
1
+ {"version":3,"file":"adminRoutes.d.ts","sourceRoot":"","sources":["../../src/http/adminRoutes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAS7E,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAe1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AA8ThD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAmgB7F"}
@@ -1,21 +1,22 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
- import { authDatabase } from "../data/tables.js";
4
3
  import { AuthAuditActions } from "../audit/actions.js";
4
+ import { authDatabase } from "../data/tables.js";
5
5
  import { correlation, emitControlPlaneAction } from "../audit/emit.js";
6
6
  import { deleteDevice, deviceSessionTokens } from "../device/registry.js";
7
7
  import { getAuthInstance, resolveDb } from "./resolve.js";
8
- import { AUTH_DEVICES_READ_SCOPE, AUTH_DEVICES_REVOKE_SCOPE, AUTH_SESSIONS_REVOKE_SCOPE, AUTH_USERS_DELETE_SCOPE, AUTH_USERS_EXPORT_SCOPE, AUTH_USERS_LOGOUT_SCOPE, AUTH_USERS_READ_SCOPE, AUTH_USERS_SUSPEND_SCOPE } from "./guards.js";
8
+ import { AUTH_DEVICES_READ_SCOPE, AUTH_DEVICES_REVOKE_SCOPE, AUTH_SESSIONS_REVOKE_SCOPE, AUTH_USERS_DELETE_SCOPE, AUTH_USERS_EXPORT_SCOPE, AUTH_USERS_LOGOUT_SCOPE, AUTH_USERS_READ_SCOPE, AUTH_USERS_SUSPEND_SCOPE, AUTH_VERIFICATIONS_READ_SCOPE } from "./guards.js";
9
9
  import { findSessionById, getUser, listDeviceRegistry, listUserDevices, listUserSessions, listUsers, userProviders, userSessionTokens } from "../admin/users.js";
10
10
  import { lifecycleDeps } from "../lifecycle/request.js";
11
11
  import "../lifecycle/reason.js";
12
- import { deleteUser, reinstateUser, requirePresent, restoreUser, suspendUser } from "../lifecycle/transitions.js";
12
+ import { deleteUser, purgeAddress, reinstateUser, requirePresent, restoreUser, suspendUser } from "../lifecycle/transitions.js";
13
+ import { listVerificationOutcomes, resolveVerificationWindow, verificationCounts } from "../ledger/read.js";
13
14
  import { auditedLifecycleCall, recordLifecycleRefusal } from "../lifecycle/audited.js";
14
15
  import { AUTH_PURGE_BINDING } from "../purge/specs.js";
15
16
  import { startPurgeInstance } from "../purge/start.js";
16
- import { AdminDeviceRevokeResponse, AdminDevicesResponse, AdminRevokeResponse, AdminUserDeleteResponse, AdminUserExportResponse, AdminUserReinstateResponse, AdminUserResponse, AdminUserRestoreResponse, AdminUserSuspendResponse, AdminUsersResponse } from "./responses.js";
17
- import { DeleteUserBody, ExportUserQuery, ListDevicesQuery, ListUsersQuery, ReinstateUserBody, RestoreUserBody, RevokeDeviceBody, RevokeSessionBody, SuspendUserBody, UserIdParam } from "./schemas.js";
18
- import { deletionView, deviceView, exportView, reinstatementView, restorationView, sessionView, suspensionView, userView } from "./views.js";
17
+ import { AdminDeviceRevokeResponse, AdminDevicesResponse, AdminRevokeResponse, AdminUserDeleteResponse, AdminUserExportResponse, AdminUserReinstateResponse, AdminUserResponse, AdminUserRestoreResponse, AdminUserSuspendResponse, AdminUsersResponse, AdminVerificationsResponse } from "./responses.js";
18
+ import { DeleteUserBody, ExportUserQuery, ListDevicesQuery, ListUsersQuery, ListVerificationsQuery, ReinstateUserBody, RestoreUserBody, RevokeDeviceBody, RevokeSessionBody, SuspendUserBody, UserIdParam } from "./schemas.js";
19
+ import { deletionView, deviceView, exportView, reinstatementView, restorationView, sessionView, suspensionView, userView, verificationView } from "./views.js";
19
20
  import { purgeExports } from "@pithy-sh/core/src/capability/purge";
20
21
  import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
21
22
  import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
@@ -31,6 +32,7 @@ import { workflowBindingFor } from "@pithy-sh/core/src/workflow/dispatch";
31
32
  * GET {base}/admin/users auth:users:read query: ListUsersQuery
32
33
  * GET {base}/admin/users/:userId auth:users:read param: UserIdParam
33
34
  * GET {base}/admin/devices auth:devices:read query: ListDevicesQuery
35
+ * GET {base}/admin/verifications auth:verifications:read query: ListVerificationsQuery
34
36
  * POST {base}/admin/sessions/revoke auth:sessions:revoke json: RevokeSessionBody
35
37
  * POST {base}/admin/users/:userId/sessions/revoke auth:users:logout param: UserIdParam
36
38
  * POST {base}/admin/users/:userId/devices/revoke auth:devices:revoke param + json
@@ -281,8 +283,9 @@ function registerAuthAdminRoutes(wiring) {
281
283
  returned: page.items.length
282
284
  }
283
285
  });
286
+ const now = /* @__PURE__ */ new Date();
284
287
  return c.json({
285
- users: page.items.map(userView),
288
+ users: page.items.map((user) => userView(user, now)),
286
289
  nextCursor: page.nextCursor
287
290
  });
288
291
  });
@@ -318,7 +321,7 @@ function registerAuthAdminRoutes(wiring) {
318
321
  }
319
322
  });
320
323
  return c.json({
321
- user: userView(user),
324
+ user: userView(user, /* @__PURE__ */ new Date()),
322
325
  providers,
323
326
  sessions,
324
327
  devices
@@ -350,6 +353,47 @@ function registerAuthAdminRoutes(wiring) {
350
353
  nextCursor: page.nextCursor
351
354
  });
352
355
  });
356
+ app.get(`${base}/admin/verifications`, describeRoute({
357
+ summary: "Count the sign-in links and codes sent over a window by type and state, and page through them, newest first.",
358
+ verification: "control-plane",
359
+ scopes: [AUTH_VERIFICATIONS_READ_SCOPE],
360
+ responses: { 200: AdminVerificationsResponse }
361
+ }), requireControlPlane(AUTH_VERIFICATIONS_READ_SCOPE), validate("query", ListVerificationsQuery), async (c) => {
362
+ const query = c.req.valid("query");
363
+ const caller = controlPlaneCaller(c);
364
+ const now = /* @__PURE__ */ new Date();
365
+ const window = resolveVerificationWindow(query, now);
366
+ const database = db(c, wiring);
367
+ const [counts, page] = await Promise.all([verificationCounts(database, window, now), listVerificationOutcomes(database, {
368
+ window,
369
+ now,
370
+ type: query.type,
371
+ state: query.state,
372
+ cursor: query.cursor,
373
+ limit: query.limit
374
+ })]);
375
+ await emitControlPlaneAction(c.var.emit, {
376
+ action: AuthAuditActions.adminVerificationsListed,
377
+ subject: caller.subject,
378
+ connectionId: caller.connectionId,
379
+ resourceType: "verification",
380
+ ...context(c),
381
+ metadata: {
382
+ since: window.since.toISOString(),
383
+ until: window.until.toISOString(),
384
+ returned: page.items.length
385
+ }
386
+ });
387
+ return c.json({
388
+ window: {
389
+ since: window.since.toISOString(),
390
+ until: window.until.toISOString()
391
+ },
392
+ counts,
393
+ verifications: page.items.map((row) => verificationView(row, now)),
394
+ nextCursor: page.nextCursor
395
+ });
396
+ });
353
397
  app.post(`${base}/admin/sessions/revoke`, describeRoute({
354
398
  summary: "Revoke one session by its id.",
355
399
  verification: "control-plane",
@@ -542,13 +586,15 @@ function registerAuthAdminRoutes(wiring) {
542
586
  action: AuthAuditActions.adminUserExported,
543
587
  ...call.audit
544
588
  }, async () => {
545
- await requirePresent(db(c, wiring), userId);
589
+ const database = db(c, wiring);
590
+ await requirePresent(database, userId);
546
591
  return purgeExports(wiring.purgeSteps ?? [], {
547
592
  subject: {
548
593
  type: "user",
549
594
  id: userId
550
595
  },
551
- env: c.env
596
+ env: c.env,
597
+ address: () => purgeAddress(database, userId)
552
598
  });
553
599
  }, () => false);
554
600
  await emitControlPlaneAction(c.var.emit, {
@@ -1 +1 @@
1
- {"version":3,"file":"csrf.d.ts","sourceRoot":"","sources":["../../src/http/csrf.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAChF,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,gCAAgC,CAAC;AAG7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAkEhD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,GAAE,UAAyB,GAAG,eAAe,CAWrG"}
1
+ {"version":3,"file":"csrf.d.ts","sourceRoot":"","sources":["../../src/http/csrf.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAChF,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,gCAAgC,CAAC;AAG7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAqEhD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,GAAE,UAAyB,GAAG,eAAe,CAWrG"}
package/dist/http/csrf.js CHANGED
@@ -1,6 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
  import { baseURLResolver } from "./baseUrl.js";
4
+ import { dispatchedAuth } from "../mcp/dispatch.js";
4
5
  import { ForbiddenError } from "@pithy-sh/core/src/error/pithyError";
5
6
  import { ambientEnv } from "@pithy-sh/core/src/env/ambient";
6
7
  //#region src/http/csrf.ts
@@ -43,7 +44,7 @@ function allowedOrigins(baseURL, trustedOrigins) {
43
44
  function sameOriginGate(allowedOrigins, resolveBaseURL) {
44
45
  const allowed = new Set(allowedOrigins);
45
46
  return async (c, next) => {
46
- if (c.req.raw.headers.has("authorization")) {
47
+ if (c.req.raw.headers.has("authorization") || dispatchedAuth(c.req.raw) !== void 0) {
47
48
  await next();
48
49
  return;
49
50
  }
@@ -1,6 +1,6 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
- import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
3
+ import type { AdminRouteDeclaration } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
4
4
  import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
5
5
  /**
6
6
  * Auth's control-plane scopes, and the admin surface a manifest advertises.
@@ -27,7 +27,7 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
27
27
  * every legitimate management call, permanently, and **no credential could fix it** — there is no user
28
28
  * to sign in as. `controlPlaneIsolation.workers.test.ts` pins both directions of that separation.
29
29
  *
30
- * ## Eight scopes, because these are eight different blast radii
30
+ * ## Nine scopes, because these are nine different blast radii
31
31
  *
32
32
  * The temptation is one `auth:admin` flag, and on this capability it is the most dangerous version of
33
33
  * that mistake. **Reading a user is a privacy operation; revoking their sessions is an availability
@@ -85,31 +85,35 @@ export declare const AUTH_USERS_LOGOUT_SCOPE: ControlPlaneScope;
85
85
  */
86
86
  export declare const AUTH_DEVICES_REVOKE_SCOPE: ControlPlaneScope;
87
87
  /**
88
- * Suspend an account and reinstate it (#620): `POST {base}/admin/users/:userId/suspend` and `/reinstate` (#621). Ending somebody's access is an availability
88
+ * Suspend an account and reinstate it: `POST {base}/admin/users/:userId/suspend` and `/reinstate`. Ending somebody's access is an availability
89
89
  * operation on one person, and reversible — which is what separates it from deleting them, and why it is
90
90
  * granted apart from both reading them and erasing them.
91
91
  */
92
92
  export declare const AUTH_USERS_SUSPEND_SCOPE: ControlPlaneScope;
93
93
  /**
94
- * Delete an account, restore one inside its purge window, and start a purge (#620):
95
- * `DELETE {base}/admin/users/:userId` and `POST …/restore` (#622). The
94
+ * Delete an account, restore one inside its purge window, and start a purge:
95
+ * `DELETE {base}/admin/users/:userId` and `POST …/restore`. The
96
96
  * one scope on this surface whose worst case cannot be undone: once the window closes, the person's rows are
97
97
  * gone from every capability that held them.
98
98
  */
99
99
  export declare const AUTH_USERS_DELETE_SCOPE: ControlPlaneScope;
100
100
  /**
101
- * Export everything the kit holds about one account — the answer to an access request (#620):
102
- * `GET {base}/admin/users/:userId/export` (#622). A disclosure, and a far larger one than reading the user: it carries every capability's rows about
101
+ * Export everything the kit holds about one account — the answer to an access request:
102
+ * `GET {base}/admin/users/:userId/export`. A disclosure, and a far larger one than reading the user: it carries every capability's rows about
103
103
  * them, so it is granted on its own and audited as one.
104
104
  */
105
105
  export declare const AUTH_USERS_EXPORT_SCOPE: ControlPlaneScope;
106
+ /**
107
+ * Read the verification ledger: every sign-in link and code issued over a window, whether it was used,
108
+ * expired or is still waiting, and the mail that carried it. A read, and apart from `auth:users:read` because the question is the fleet's deliverability rather than
109
+ * who one person is — the rows name accounts by id and never by address.
110
+ */
111
+ export declare const AUTH_VERIFICATIONS_READ_SCOPE: ControlPlaneScope;
106
112
  /**
107
113
  * Every control-plane scope auth defines — what `pithy dashboard connect` offers for this capability,
108
114
  * and the list a manifest or a doc quotes rather than re-typing.
109
115
  *
110
- * **The lifecycle scopes were declared before the routes that require them** (#620): suspend and reinstate
111
- * landed in #621, delete, restore and export in #622. Declaring the vocabulary here, once, is what let those
112
- * issues build on one name each rather than each choosing its own.
116
+ * Declaring the vocabulary here, once, gives every route that requires one of these the same name.
113
117
  */
114
118
  export declare const AUTH_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[];
115
119
  /**
@@ -124,5 +128,5 @@ export declare const AUTH_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[];
124
128
  * The summaries say what the operation is *for*. A client renders these next to a button somebody is
125
129
  * about to press on a real person's account.
126
130
  */
127
- export declare function authAdminRoutes(basePath: string): AdminRoute[];
131
+ export declare function authAdminRoutes(basePath: string): AdminRouteDeclaration[];
128
132
  //# sourceMappingURL=guards.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sDAAsD,CAAC;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAAqC,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,iBAA0C,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,iBAAyC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAAwC,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,iBAAiB,EASjE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CAsE9D"}
1
+ {"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAAqC,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,iBAA0C,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,iBAAyC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAAwC,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA6C,CAAC;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,iBAAiB,EAUjE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAqGzE"}
@@ -26,7 +26,7 @@
26
26
  * every legitimate management call, permanently, and **no credential could fix it** — there is no user
27
27
  * to sign in as. `controlPlaneIsolation.workers.test.ts` pins both directions of that separation.
28
28
  *
29
- * ## Eight scopes, because these are eight different blast radii
29
+ * ## Nine scopes, because these are nine different blast radii
30
30
  *
31
31
  * The temptation is one `auth:admin` flag, and on this capability it is the most dangerous version of
32
32
  * that mistake. **Reading a user is a privacy operation; revoking their sessions is an availability
@@ -84,31 +84,35 @@ const AUTH_USERS_LOGOUT_SCOPE = "auth:users:logout";
84
84
  */
85
85
  const AUTH_DEVICES_REVOKE_SCOPE = "auth:devices:revoke";
86
86
  /**
87
- * Suspend an account and reinstate it (#620): `POST {base}/admin/users/:userId/suspend` and `/reinstate` (#621). Ending somebody's access is an availability
87
+ * Suspend an account and reinstate it: `POST {base}/admin/users/:userId/suspend` and `/reinstate`. Ending somebody's access is an availability
88
88
  * operation on one person, and reversible — which is what separates it from deleting them, and why it is
89
89
  * granted apart from both reading them and erasing them.
90
90
  */
91
91
  const AUTH_USERS_SUSPEND_SCOPE = "auth:users:suspend";
92
92
  /**
93
- * Delete an account, restore one inside its purge window, and start a purge (#620):
94
- * `DELETE {base}/admin/users/:userId` and `POST …/restore` (#622). The
93
+ * Delete an account, restore one inside its purge window, and start a purge:
94
+ * `DELETE {base}/admin/users/:userId` and `POST …/restore`. The
95
95
  * one scope on this surface whose worst case cannot be undone: once the window closes, the person's rows are
96
96
  * gone from every capability that held them.
97
97
  */
98
98
  const AUTH_USERS_DELETE_SCOPE = "auth:users:delete";
99
99
  /**
100
- * Export everything the kit holds about one account — the answer to an access request (#620):
101
- * `GET {base}/admin/users/:userId/export` (#622). A disclosure, and a far larger one than reading the user: it carries every capability's rows about
100
+ * Export everything the kit holds about one account — the answer to an access request:
101
+ * `GET {base}/admin/users/:userId/export`. A disclosure, and a far larger one than reading the user: it carries every capability's rows about
102
102
  * them, so it is granted on its own and audited as one.
103
103
  */
104
104
  const AUTH_USERS_EXPORT_SCOPE = "auth:users:export";
105
105
  /**
106
+ * Read the verification ledger: every sign-in link and code issued over a window, whether it was used,
107
+ * expired or is still waiting, and the mail that carried it. A read, and apart from `auth:users:read` because the question is the fleet's deliverability rather than
108
+ * who one person is — the rows name accounts by id and never by address.
109
+ */
110
+ const AUTH_VERIFICATIONS_READ_SCOPE = "auth:verifications:read";
111
+ /**
106
112
  * Every control-plane scope auth defines — what `pithy dashboard connect` offers for this capability,
107
113
  * and the list a manifest or a doc quotes rather than re-typing.
108
114
  *
109
- * **The lifecycle scopes were declared before the routes that require them** (#620): suspend and reinstate
110
- * landed in #621, delete, restore and export in #622. Declaring the vocabulary here, once, is what let those
111
- * issues build on one name each rather than each choosing its own.
115
+ * Declaring the vocabulary here, once, gives every route that requires one of these the same name.
112
116
  */
113
117
  const AUTH_CONTROL_PLANE_SCOPES = [
114
118
  AUTH_USERS_READ_SCOPE,
@@ -118,7 +122,8 @@ const AUTH_CONTROL_PLANE_SCOPES = [
118
122
  AUTH_DEVICES_REVOKE_SCOPE,
119
123
  AUTH_USERS_SUSPEND_SCOPE,
120
124
  AUTH_USERS_DELETE_SCOPE,
121
- AUTH_USERS_EXPORT_SCOPE
125
+ AUTH_USERS_EXPORT_SCOPE,
126
+ AUTH_VERIFICATIONS_READ_SCOPE
122
127
  ];
123
128
  /**
124
129
  * Auth's management surface, as `GET /control-plane/manifest` reports it.
@@ -136,71 +141,101 @@ function authAdminRoutes(basePath) {
136
141
  return [
137
142
  {
138
143
  method: "GET",
144
+ operation: "users.list",
139
145
  path: `${basePath}/admin/users`,
140
146
  scope: AUTH_USERS_READ_SCOPE,
147
+ kind: "reads",
141
148
  summary: "Find a user. Lists everyone newest first, or searches email and display name."
142
149
  },
143
150
  {
144
151
  method: "GET",
152
+ operation: "users.read",
145
153
  path: `${basePath}/admin/users/:userId`,
146
154
  scope: AUTH_USERS_READ_SCOPE,
155
+ kind: "reads",
147
156
  summary: "One user, with where they are signed in and what they sign in with."
148
157
  },
149
158
  {
150
159
  method: "GET",
160
+ operation: "devices.list",
151
161
  path: `${basePath}/admin/devices`,
152
162
  scope: AUTH_DEVICES_READ_SCOPE,
163
+ kind: "reads",
153
164
  summary: "The device registry across users, most-recently-seen first."
154
165
  },
155
166
  {
156
167
  method: "POST",
168
+ operation: "sessions.revoke",
157
169
  path: `${basePath}/admin/sessions/revoke`,
158
170
  scope: AUTH_SESSIONS_REVOKE_SCOPE,
171
+ kind: "credentials",
159
172
  summary: "Kill one session. The rest of that person's sign-ins keep working."
160
173
  },
161
174
  {
162
175
  method: "POST",
176
+ operation: "users.sessions.revoke",
163
177
  path: `${basePath}/admin/users/:userId/sessions/revoke`,
164
178
  scope: AUTH_USERS_LOGOUT_SCOPE,
179
+ kind: "credentials",
165
180
  summary: "Sign a user out everywhere, on every device, immediately."
166
181
  },
167
182
  {
168
183
  method: "POST",
184
+ operation: "users.devices.revoke",
169
185
  path: `${basePath}/admin/users/:userId/devices/revoke`,
170
186
  scope: AUTH_DEVICES_REVOKE_SCOPE,
187
+ kind: "credentials",
171
188
  summary: "Sign one device out and forget it — for a phone reported lost."
172
189
  },
173
190
  {
174
191
  method: "POST",
192
+ operation: "users.suspend",
175
193
  path: `${basePath}/admin/users/:userId/suspend`,
176
194
  scope: AUTH_USERS_SUSPEND_SCOPE,
195
+ kind: "writes",
177
196
  summary: "Suspend a user, with a reason. Their sessions end and every sign-in is refused."
178
197
  },
179
198
  {
180
199
  method: "POST",
200
+ operation: "users.reinstate",
181
201
  path: `${basePath}/admin/users/:userId/reinstate`,
182
202
  scope: AUTH_USERS_SUSPEND_SCOPE,
203
+ kind: "writes",
183
204
  summary: "Lift a suspension, with a reason. They sign in again; no session comes back."
184
205
  },
185
206
  {
186
207
  method: "DELETE",
208
+ operation: "users.delete",
187
209
  path: `${basePath}/admin/users/:userId`,
188
210
  scope: AUTH_USERS_DELETE_SCOPE,
211
+ kind: "deletes",
189
212
  summary: "Delete a user, with a reason. Soft by default: restorable until the purge window closes. Hard, when named: erased now."
190
213
  },
191
214
  {
192
215
  method: "POST",
216
+ operation: "users.restore",
193
217
  path: `${basePath}/admin/users/:userId/restore`,
194
218
  scope: AUTH_USERS_DELETE_SCOPE,
219
+ kind: "deletes",
195
220
  summary: "Restore a deleted user inside the purge window, with a reason. They sign in again."
196
221
  },
197
222
  {
198
223
  method: "GET",
224
+ operation: "verifications.list",
225
+ path: `${basePath}/admin/verifications`,
226
+ scope: AUTH_VERIFICATIONS_READ_SCOPE,
227
+ kind: "reads",
228
+ summary: "Every sign-in link and code sent over a window: used, expired or still waiting, and the mail that carried it."
229
+ },
230
+ {
231
+ method: "GET",
232
+ operation: "users.export",
199
233
  path: `${basePath}/admin/users/:userId/export`,
200
234
  scope: AUTH_USERS_EXPORT_SCOPE,
235
+ kind: "reads",
201
236
  summary: "Everything the kit holds about one user, from every capability — the answer to an access request."
202
237
  }
203
238
  ];
204
239
  }
205
240
  //#endregion
206
- export { AUTH_CONTROL_PLANE_SCOPES, AUTH_DEVICES_READ_SCOPE, AUTH_DEVICES_REVOKE_SCOPE, AUTH_SESSIONS_REVOKE_SCOPE, AUTH_USERS_DELETE_SCOPE, AUTH_USERS_EXPORT_SCOPE, AUTH_USERS_LOGOUT_SCOPE, AUTH_USERS_READ_SCOPE, AUTH_USERS_SUSPEND_SCOPE, authAdminRoutes };
241
+ export { AUTH_CONTROL_PLANE_SCOPES, AUTH_DEVICES_READ_SCOPE, AUTH_DEVICES_REVOKE_SCOPE, AUTH_SESSIONS_REVOKE_SCOPE, AUTH_USERS_DELETE_SCOPE, AUTH_USERS_EXPORT_SCOPE, AUTH_USERS_LOGOUT_SCOPE, AUTH_USERS_READ_SCOPE, AUTH_USERS_SUSPEND_SCOPE, AUTH_VERIFICATIONS_READ_SCOPE, authAdminRoutes };
@@ -0,0 +1,76 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
4
+ import type { Context } from "hono";
5
+ import type { AuthWiring } from "../capability";
6
+ import type { AuthInstance } from "../instance/auth";
7
+ import type { HandoffExchangeBody, SocialSignInStartQuery } from "./schemas";
8
+ /**
9
+ * The redirect half of a native sign-in, and the trade that ends it.
10
+ *
11
+ * A native app starts a social sign-in with its own deep link as `callbackURL` (a scheme in `trustedOrigins`,
12
+ * such as `myapp://auth/callback`). Better Auth checks that URL when the sign-in starts and, at the provider's
13
+ * callback, answers with a redirect to it carrying the session as a cookie. A cookie set on a redirect to an app
14
+ * scheme lands in the system browser, which the app never reads. {@link handOffToApp} replaces that answer: the
15
+ * session cookies are dropped and the deep link carries a one-time code instead (`../token/handoff.ts`). The app
16
+ * posts the code to `POST {base}/handoff`, {@link exchangeHandoff}, and gets the raw session token back.
17
+ *
18
+ * The code is bound to the app that asked for it. The app puts the S256 challenge of a verifier only it holds on
19
+ * its `callbackURL` as `handoff_challenge`, Better Auth keeps that URL with the sign-in's state, and the challenge
20
+ * comes back here on the redirect. It is moved off the link and stored with the code, and the trade must present
21
+ * the verifier. A deep link with no challenge gets no code at all.
22
+ *
23
+ * Which redirects are handed off: any whose link carries `handoff_challenge`, whatever its scheme, and any to a
24
+ * non-http(s) scheme. So an app's https universal link (iOS) or app link (Android), which the operating system
25
+ * routes only to the app that proves it owns the domain, gets a code when the app asks for one with a challenge.
26
+ * An http(s) callback with no challenge is a web page, and a web page gets its cookie.
27
+ *
28
+ * A magic link is handed off only to an https link. Whoever asks for the link chooses the challenge, and the
29
+ * person who opens it is somebody else, so the code must reach only the app that owns the link's domain. Any app
30
+ * can claim a custom scheme; a magic link to one is refused, and a native app without a universal link signs in
31
+ * by email with a one-time code instead.
32
+ *
33
+ * A native app starts a redirect sign-in with {@link startNativeSignIn}, a GET the system browser's sign-in sheet
34
+ * opens, rather than by posting `/sign-in/social` itself. Better Auth binds the sign-in to a signed `state`
35
+ * cookie and checks it at the provider's callback; set on the app's own request, that cookie would never reach
36
+ * the sheet that completes the callback.
37
+ */
38
+ /** The deep-link query parameter the one-time code travels in. */
39
+ export declare const HANDOFF_CODE_PARAM = "code";
40
+ /** The `callbackURL` query parameter the app's S256 challenge travels in. */
41
+ export declare const HANDOFF_CHALLENGE_PARAM = "handoff_challenge";
42
+ /** The `error` a deep link gets back when it carried no challenge to bind a code to. */
43
+ export declare const HANDOFF_UNBOUND_ERROR = "handoff_challenge_required";
44
+ /** The `error` a magic link to a custom scheme gets back: only an https universal link or app link is handed one. */
45
+ export declare const HANDOFF_SCHEME_REFUSED_ERROR = "handoff_scheme_refused";
46
+ type Ctx = Context<PithyHonoEnv>;
47
+ /**
48
+ * Rewrite a sign-in that ends on an app link into a handoff, or answer null and leave the response as Better Auth
49
+ * wrote it: any answer that is not a redirect to an app link, and a redirect that sets no session (a refused
50
+ * sign-in returning its error to the app).
51
+ *
52
+ * An app link outside `trustedOrigins` is refused rather than followed. Better Auth checked the callback when the
53
+ * sign-in started, so reaching that branch means something else wrote the redirect, and a session must never be
54
+ * handed to a scheme this Worker does not trust.
55
+ */
56
+ export declare function handOffToApp(c: Ctx, wiring: AuthWiring, instance: AuthInstance, response: Response): Promise<Response | null>;
57
+ /**
58
+ * Start a native redirect sign-in inside the system browser's sign-in sheet: run the social sign-in here and
59
+ * answer a redirect to the provider that carries Better Auth's `Set-Cookie`, so the signed `state` cookie lands in
60
+ * the jar of the browser that will come back through the provider's callback.
61
+ *
62
+ * Only for the handoff: the callback must be a link `trustedOrigins` admits, carrying a well-formed
63
+ * `handoff_challenge`, and a navigation another page started (`Sec-Fetch-Site` other than `none`) is refused. A web page starts its sign-in with the JSON `POST /sign-in/social`, as it always has.
64
+ * The sign-in runs on a request of its own with the sheet's cookies, origin and fetch metadata left behind:
65
+ * nothing the sheet already holds takes part in it.
66
+ */
67
+ export declare function startNativeSignIn(c: Ctx, wiring: AuthWiring, query: SocialSignInStartQuery): Promise<Response>;
68
+ /**
69
+ * Trade a one-time code and its verifier for the session the code stands for. The code is spent by the attempt
70
+ * whatever the answer, so a wrong verifier gets one guess.
71
+ * Device headers sent with the trade register the device and bind it to the session, as they would on any other
72
+ * native sign-in; the browser that completed the redirect had none to send.
73
+ */
74
+ export declare function exchangeHandoff(c: Ctx, wiring: AuthWiring, body: HandoffExchangeBody): Promise<Response>;
75
+ export {};
76
+ //# sourceMappingURL=handoff.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../src/http/handoff.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAQ7E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAMrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,kEAAkE;AAClE,eAAO,MAAM,kBAAkB,SAAS,CAAC;AAEzC,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAE3D,wFAAwF;AACxF,eAAO,MAAM,qBAAqB,+BAA+B,CAAC;AAElE,qHAAqH;AACrH,eAAO,MAAM,4BAA4B,2BAA2B,CAAC;AAKrE,KAAK,GAAG,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;AA8CjC;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,CAAC,EAAE,GAAG,EACN,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA+E1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAgFpH;AAYD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6B9G"}