@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
@@ -1,20 +1,29 @@
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_LOGOUT_SCOPE, AUTH_USERS_READ_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
- import { AdminDeviceRevokeResponse, AdminDevicesResponse, AdminRevokeResponse, AdminUserResponse, AdminUsersResponse } from "./responses.js";
11
- import { ListDevicesQuery, ListUsersQuery, RevokeDeviceBody, RevokeSessionBody, UserIdParam } from "./schemas.js";
12
- import { deviceView, sessionView, userView } from "./views.js";
10
+ import { lifecycleDeps } from "../lifecycle/request.js";
11
+ import "../lifecycle/reason.js";
12
+ import { deleteUser, purgeAddress, reinstateUser, requirePresent, restoreUser, suspendUser } from "../lifecycle/transitions.js";
13
+ import { listVerificationOutcomes, resolveVerificationWindow, verificationCounts } from "../ledger/read.js";
14
+ import { auditedLifecycleCall, recordLifecycleRefusal } from "../lifecycle/audited.js";
15
+ import { AUTH_PURGE_BINDING } from "../purge/specs.js";
16
+ import { startPurgeInstance } from "../purge/start.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";
20
+ import { purgeExports } from "@pithy-sh/core/src/capability/purge";
13
21
  import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
14
22
  import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
15
23
  import { validate } from "@pithy-sh/core/src/http/validation";
16
- import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
17
24
  import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
25
+ import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
26
+ import { workflowBindingFor } from "@pithy-sh/core/src/workflow/dispatch";
18
27
  //#region src/http/adminRoutes.ts
19
28
  /**
20
29
  * The control-plane admin surface: the reads a management dashboard's user panes resolve to, and the
@@ -23,9 +32,15 @@ import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
23
32
  * GET {base}/admin/users auth:users:read query: ListUsersQuery
24
33
  * GET {base}/admin/users/:userId auth:users:read param: UserIdParam
25
34
  * GET {base}/admin/devices auth:devices:read query: ListDevicesQuery
35
+ * GET {base}/admin/verifications auth:verifications:read query: ListVerificationsQuery
26
36
  * POST {base}/admin/sessions/revoke auth:sessions:revoke json: RevokeSessionBody
27
37
  * POST {base}/admin/users/:userId/sessions/revoke auth:users:logout param: UserIdParam
28
38
  * POST {base}/admin/users/:userId/devices/revoke auth:devices:revoke param + json
39
+ * POST {base}/admin/users/:userId/suspend auth:users:suspend param + json: SuspendUserBody
40
+ * POST {base}/admin/users/:userId/reinstate auth:users:suspend param + json: ReinstateUserBody
41
+ * DELETE {base}/admin/users/:userId auth:users:delete param + json: DeleteUserBody
42
+ * POST {base}/admin/users/:userId/restore auth:users:delete param + json: RestoreUserBody
43
+ * GET {base}/admin/users/:userId/export auth:users:export param + query: ExportUserQuery
29
44
  *
30
45
  * ## Registered before the catch-all, or dead
31
46
  *
@@ -132,6 +147,116 @@ async function revokeTokens(c, wiring, tokens) {
132
147
  return tokens.length;
133
148
  }
134
149
  /**
150
+ * What a lifecycle route hands `../lifecycle/`: the transitions' dependencies, with the request's correlation
151
+ * and the connection on every audit event they write, and the operator as the actor.
152
+ *
153
+ * The actor is the token's verified `sub` — which person at the dashboard — the same id every other admin
154
+ * event records, so the trail and the history table name the same somebody.
155
+ */
156
+ function lifecycleCall(c, wiring, caller, userId, reason) {
157
+ const correlated = context(c);
158
+ return {
159
+ deps: lifecycleDeps(c, wiring, {
160
+ ...correlated,
161
+ metadata: { connectionId: caller.connectionId }
162
+ }),
163
+ actor: {
164
+ type: "control-plane",
165
+ id: caller.subject
166
+ },
167
+ restoreRoute: `POST ${wiring.config.basePath}/admin/users/${userId}/restore`,
168
+ audit: {
169
+ subject: caller.subject,
170
+ connectionId: caller.connectionId,
171
+ userId,
172
+ reason,
173
+ ...correlated
174
+ }
175
+ };
176
+ }
177
+ /**
178
+ * A lifecycle route's body validator, which audits the bodies it refuses (#621). Every call is on the trail,
179
+ * a refusal included, and a body the validator turns away never reaches `auditedLifecycleCall`. So it is
180
+ * recorded here, as `denied` under the route's own action, with whatever reason the body carried — cut to the
181
+ * reason's own limit, so a refused essay is not stored whole — and the 400 is thrown as before.
182
+ */
183
+ function lifecycleBody(schema, action) {
184
+ return validate("json", schema, async (raw, error, body) => {
185
+ const c = raw;
186
+ const caller = controlPlaneCaller(c);
187
+ const reason = body && typeof body === "object" ? body.reason : void 0;
188
+ await recordLifecycleRefusal(c.var.emit, {
189
+ action: typeof action === "string" ? action : action(body),
190
+ subject: caller.subject,
191
+ connectionId: caller.connectionId,
192
+ userId: c.req.valid("param").userId,
193
+ reason: typeof reason === "string" ? reason.slice(0, 500) : null,
194
+ ...context(c)
195
+ }, error, {
196
+ code: "validation/invalid_input",
197
+ outcome: "denied"
198
+ });
199
+ });
200
+ }
201
+ /**
202
+ * End every session an account holds, after its columns are written — never before, for the reason the suspend
203
+ * route gives: enforcement refuses the account the moment the columns land, and revoking first would leave a
204
+ * window for a sign-in the revocation never saw. Through Better Auth's adapter, so `onSessionRevoked` hears
205
+ * each, and recorded under `auth/admin_user_sessions_revoked` with the cause.
206
+ */
207
+ async function endSessions(c, wiring, caller, userId, cause) {
208
+ const revoked = await revokeTokens(c, wiring, await userSessionTokens(db(c, wiring), userId));
209
+ await emitControlPlaneAction(c.var.emit, {
210
+ action: AuthAuditActions.adminUserSessionsRevoked,
211
+ subject: caller.subject,
212
+ connectionId: caller.connectionId,
213
+ resourceType: "user",
214
+ resourceId: userId,
215
+ ...context(c),
216
+ metadata: {
217
+ revoked,
218
+ cause
219
+ }
220
+ });
221
+ return revoked;
222
+ }
223
+ /**
224
+ * Start the purge of one account now (#622): `started` when this Worker binds the purge Workflow and it took the
225
+ * instance — or already held it — and `pending` when it binds none or the start failed; the account is due
226
+ * either way, and the daily pass starts it. A failed start is not this call's failure: the deletion is already
227
+ * written, and a 500 over it would invite a retry that finds the account deleted and says nothing new.
228
+ *
229
+ * Under the instance id the deletion names (`../purge/start.ts`), so a hard deletion repeated, or one the daily
230
+ * pass also finds due, is the one purge and never a second.
231
+ */
232
+ async function startPurge(c, result, userId, notify) {
233
+ const log = c.var.log.child("auth");
234
+ const binding = workflowBindingFor(c.env, AUTH_PURGE_BINDING);
235
+ if (!binding) {
236
+ log.warn("a deletion found no purge Workflow bound; the purge is pending", { userId });
237
+ return "pending";
238
+ }
239
+ try {
240
+ await startPurgeInstance(binding, {
241
+ userId,
242
+ deletedAt: result.deletedAt.getTime(),
243
+ ...notify === void 0 ? {} : { notify },
244
+ at: /* @__PURE__ */ new Date()
245
+ });
246
+ return "started";
247
+ } catch (error) {
248
+ log.warn("the purge could not be started; the daily pass will start it", {
249
+ userId,
250
+ reason: error instanceof Error ? error.message : String(error)
251
+ });
252
+ return "pending";
253
+ }
254
+ }
255
+ /** What becomes of a soft deletion's purge: due later, or — when its window has already closed — due now. */
256
+ function scheduledOrDue(result) {
257
+ return result.purgeAfter.getTime() > Date.now() ? "scheduled" : "due";
258
+ }
259
+ /**
135
260
  * Register the control-plane admin routes. Called by `createAuthRoutes` **before** the Better Auth
136
261
  * catch-all; see the file header for why that ordering is load-bearing.
137
262
  */
@@ -158,8 +283,9 @@ function registerAuthAdminRoutes(wiring) {
158
283
  returned: page.items.length
159
284
  }
160
285
  });
286
+ const now = /* @__PURE__ */ new Date();
161
287
  return c.json({
162
- users: page.items.map(userView),
288
+ users: page.items.map((user) => userView(user, now)),
163
289
  nextCursor: page.nextCursor
164
290
  });
165
291
  });
@@ -195,7 +321,7 @@ function registerAuthAdminRoutes(wiring) {
195
321
  }
196
322
  });
197
323
  return c.json({
198
- user: userView(user),
324
+ user: userView(user, /* @__PURE__ */ new Date()),
199
325
  providers,
200
326
  sessions,
201
327
  devices
@@ -227,6 +353,47 @@ function registerAuthAdminRoutes(wiring) {
227
353
  nextCursor: page.nextCursor
228
354
  });
229
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
+ });
230
397
  app.post(`${base}/admin/sessions/revoke`, describeRoute({
231
398
  summary: "Revoke one session by its id.",
232
399
  verification: "control-plane",
@@ -301,6 +468,150 @@ function registerAuthAdminRoutes(wiring) {
301
468
  removed
302
469
  });
303
470
  });
471
+ app.post(`${base}/admin/users/:userId/suspend`, describeRoute({
472
+ summary: "Suspend one user, with a reason: their sessions end and every sign-in is refused.",
473
+ verification: "control-plane",
474
+ scopes: [AUTH_USERS_SUSPEND_SCOPE],
475
+ responses: { 200: AdminUserSuspendResponse }
476
+ }), requireControlPlane(AUTH_USERS_SUSPEND_SCOPE), validate("param", UserIdParam), lifecycleBody(SuspendUserBody, AuthAuditActions.adminUserSuspended), async (c) => {
477
+ const { userId } = c.req.valid("param");
478
+ const { reason, until, notify } = c.req.valid("json");
479
+ const caller = controlPlaneCaller(c);
480
+ const call = lifecycleCall(c, wiring, caller, userId, reason);
481
+ const result = await auditedLifecycleCall(c.var.emit, {
482
+ action: AuthAuditActions.adminUserSuspended,
483
+ ...call.audit
484
+ }, () => suspendUser(call.deps, {
485
+ userId,
486
+ actor: call.actor,
487
+ reason,
488
+ until: until ?? null,
489
+ ...notify === void 0 ? {} : { notify },
490
+ restoreRoute: call.restoreRoute
491
+ }), () => false);
492
+ const revoked = await revokeTokens(c, wiring, await userSessionTokens(db(c, wiring), userId));
493
+ await emitControlPlaneAction(c.var.emit, {
494
+ action: AuthAuditActions.adminUserSessionsRevoked,
495
+ subject: caller.subject,
496
+ connectionId: caller.connectionId,
497
+ resourceType: "user",
498
+ resourceId: userId,
499
+ ...context(c),
500
+ metadata: {
501
+ revoked,
502
+ cause: "suspended"
503
+ }
504
+ });
505
+ return c.json(suspensionView(userId, result, revoked));
506
+ });
507
+ app.post(`${base}/admin/users/:userId/reinstate`, describeRoute({
508
+ summary: "Lift one user's suspension, with a reason. They sign in again; no session is restored.",
509
+ verification: "control-plane",
510
+ scopes: [AUTH_USERS_SUSPEND_SCOPE],
511
+ responses: { 200: AdminUserReinstateResponse }
512
+ }), requireControlPlane(AUTH_USERS_SUSPEND_SCOPE), validate("param", UserIdParam), lifecycleBody(ReinstateUserBody, AuthAuditActions.adminUserReinstated), async (c) => {
513
+ const { userId } = c.req.valid("param");
514
+ const { reason, notify } = c.req.valid("json");
515
+ const call = lifecycleCall(c, wiring, controlPlaneCaller(c), userId, reason);
516
+ const result = await auditedLifecycleCall(c.var.emit, {
517
+ action: AuthAuditActions.adminUserReinstated,
518
+ ...call.audit
519
+ }, () => reinstateUser(call.deps, {
520
+ userId,
521
+ actor: call.actor,
522
+ reason,
523
+ ...notify === void 0 ? {} : { notify },
524
+ restoreRoute: call.restoreRoute
525
+ }), (outcome) => !outcome.changed);
526
+ return c.json(reinstatementView(userId, result));
527
+ });
528
+ app.delete(`${base}/admin/users/:userId`, describeRoute({
529
+ summary: "Delete one user, with a reason: soft by default, restorable until the purge window closes; hard when named, purged now.",
530
+ verification: "control-plane",
531
+ scopes: [AUTH_USERS_DELETE_SCOPE],
532
+ responses: { 200: AdminUserDeleteResponse }
533
+ }), requireControlPlane(AUTH_USERS_DELETE_SCOPE), validate("param", UserIdParam), lifecycleBody(DeleteUserBody, (body) => body?.mode === "hard" ? AuthAuditActions.adminUserHardDeleted : AuthAuditActions.adminUserSoftDeleted), async (c) => {
534
+ const { userId } = c.req.valid("param");
535
+ const { mode, reason, notify } = c.req.valid("json");
536
+ const caller = controlPlaneCaller(c);
537
+ const call = lifecycleCall(c, wiring, caller, userId, reason);
538
+ const action = mode === "hard" ? AuthAuditActions.adminUserHardDeleted : AuthAuditActions.adminUserSoftDeleted;
539
+ const result = await auditedLifecycleCall(c.var.emit, {
540
+ action,
541
+ ...call.audit
542
+ }, () => deleteUser(call.deps, {
543
+ userId,
544
+ actor: call.actor,
545
+ reason,
546
+ mode,
547
+ ...notify === void 0 ? {} : { notify }
548
+ }), (outcome) => outcome.outcome === "unchanged");
549
+ const sessionsRevoked = await endSessions(c, wiring, caller, userId, "deleted");
550
+ const disposition = mode === "hard" ? "due" : scheduledOrDue(result);
551
+ const purge = disposition === "due" ? await startPurge(c, result, userId, mode === "hard" ? notify : void 0) : disposition;
552
+ return c.json(deletionView(userId, mode, result, purge, sessionsRevoked));
553
+ });
554
+ app.post(`${base}/admin/users/:userId/restore`, describeRoute({
555
+ summary: "Restore one deleted user inside the purge window, with a reason. They sign in again; no session is restored.",
556
+ verification: "control-plane",
557
+ scopes: [AUTH_USERS_DELETE_SCOPE],
558
+ responses: { 200: AdminUserRestoreResponse }
559
+ }), requireControlPlane(AUTH_USERS_DELETE_SCOPE), validate("param", UserIdParam), lifecycleBody(RestoreUserBody, AuthAuditActions.adminUserRestored), async (c) => {
560
+ const { userId } = c.req.valid("param");
561
+ const { reason } = c.req.valid("json");
562
+ const call = lifecycleCall(c, wiring, controlPlaneCaller(c), userId, reason);
563
+ const result = await auditedLifecycleCall(c.var.emit, {
564
+ action: AuthAuditActions.adminUserRestored,
565
+ ...call.audit
566
+ }, () => restoreUser(call.deps, {
567
+ userId,
568
+ actor: call.actor,
569
+ reason
570
+ }), (outcome) => !outcome.changed);
571
+ return c.json(restorationView(userId, result));
572
+ });
573
+ app.get(`${base}/admin/users/:userId/export`, describeRoute({
574
+ summary: "Export everything the kit holds about one user, from every composed capability, as one document.",
575
+ description: "The answer to an access request. One entry per composed capability that declares a purge contribution, in the order the purge erases them. Audited as a disclosure, with the reason.",
576
+ verification: "control-plane",
577
+ scopes: [AUTH_USERS_EXPORT_SCOPE],
578
+ responses: { 200: AdminUserExportResponse }
579
+ }), requireControlPlane(AUTH_USERS_EXPORT_SCOPE), validate("param", UserIdParam), validate("query", ExportUserQuery), async (c) => {
580
+ const { userId } = c.req.valid("param");
581
+ const { reason } = c.req.valid("query");
582
+ const caller = controlPlaneCaller(c);
583
+ const call = lifecycleCall(c, wiring, caller, userId, reason);
584
+ const exportedAt = /* @__PURE__ */ new Date();
585
+ const entries = await auditedLifecycleCall(c.var.emit, {
586
+ action: AuthAuditActions.adminUserExported,
587
+ ...call.audit
588
+ }, async () => {
589
+ const database = db(c, wiring);
590
+ await requirePresent(database, userId);
591
+ return purgeExports(wiring.purgeSteps ?? [], {
592
+ subject: {
593
+ type: "user",
594
+ id: userId
595
+ },
596
+ env: c.env,
597
+ address: () => purgeAddress(database, userId)
598
+ });
599
+ }, () => false);
600
+ await emitControlPlaneAction(c.var.emit, {
601
+ action: AuthAuditActions.adminUserExported,
602
+ subject: caller.subject,
603
+ connectionId: caller.connectionId,
604
+ resourceType: "user",
605
+ resourceId: userId,
606
+ ...context(c),
607
+ metadata: {
608
+ reason,
609
+ disclosure: true,
610
+ capabilities: entries.map((entry) => `${entry.capability}:${entry.state}`)
611
+ }
612
+ });
613
+ return c.json(exportView(userId, exportedAt, entries));
614
+ });
304
615
  };
305
616
  }
306
617
  //#endregion
@@ -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,30 +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, the routes in #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, the routes in #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
95
96
  * one scope on this surface whose worst case cannot be undone: once the window closes, the person's rows are
96
97
  * gone from every capability that held them.
97
98
  */
98
99
  export declare const AUTH_USERS_DELETE_SCOPE: ControlPlaneScope;
99
100
  /**
100
- * Export everything the kit holds about one account — the answer to an access request (#620, the route in
101
- * #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
102
103
  * them, so it is granted on its own and audited as one.
103
104
  */
104
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;
105
112
  /**
106
113
  * Every control-plane scope auth defines — what `pithy dashboard connect` offers for this capability,
107
114
  * and the list a manifest or a doc quotes rather than re-typing.
108
115
  *
109
- * **The three lifecycle scopes are declared before the routes that require them.** The suspend, delete and
110
- * export routes land in #621 and #622; declaring the vocabulary here, once, is what lets those issues build on
111
- * one name each rather than three issues each choosing their own.
116
+ * Declaring the vocabulary here, once, gives every route that requires one of these the same name.
112
117
  */
113
118
  export declare const AUTH_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[];
114
119
  /**
@@ -123,5 +128,5 @@ export declare const AUTH_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[];
123
128
  * The summaries say what the operation is *for*. A client renders these next to a button somebody is
124
129
  * about to press on a real person's account.
125
130
  */
126
- export declare function authAdminRoutes(basePath: string): AdminRoute[];
131
+ export declare function authAdminRoutes(basePath: string): AdminRouteDeclaration[];
127
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;;;;GAIG;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,CAuC9D"}
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,30 +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, the routes in #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, the routes in #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
94
95
  * one scope on this surface whose worst case cannot be undone: once the window closes, the person's rows are
95
96
  * gone from every capability that held them.
96
97
  */
97
98
  const AUTH_USERS_DELETE_SCOPE = "auth:users:delete";
98
99
  /**
99
- * Export everything the kit holds about one account — the answer to an access request (#620, the route in
100
- * #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
101
102
  * them, so it is granted on its own and audited as one.
102
103
  */
103
104
  const AUTH_USERS_EXPORT_SCOPE = "auth:users:export";
104
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
+ /**
105
112
  * Every control-plane scope auth defines — what `pithy dashboard connect` offers for this capability,
106
113
  * and the list a manifest or a doc quotes rather than re-typing.
107
114
  *
108
- * **The three lifecycle scopes are declared before the routes that require them.** The suspend, delete and
109
- * export routes land in #621 and #622; declaring the vocabulary here, once, is what lets those issues build on
110
- * one name each rather than three issues each choosing their own.
115
+ * Declaring the vocabulary here, once, gives every route that requires one of these the same name.
111
116
  */
112
117
  const AUTH_CONTROL_PLANE_SCOPES = [
113
118
  AUTH_USERS_READ_SCOPE,
@@ -117,7 +122,8 @@ const AUTH_CONTROL_PLANE_SCOPES = [
117
122
  AUTH_DEVICES_REVOKE_SCOPE,
118
123
  AUTH_USERS_SUSPEND_SCOPE,
119
124
  AUTH_USERS_DELETE_SCOPE,
120
- AUTH_USERS_EXPORT_SCOPE
125
+ AUTH_USERS_EXPORT_SCOPE,
126
+ AUTH_VERIFICATIONS_READ_SCOPE
121
127
  ];
122
128
  /**
123
129
  * Auth's management surface, as `GET /control-plane/manifest` reports it.
@@ -135,41 +141,101 @@ function authAdminRoutes(basePath) {
135
141
  return [
136
142
  {
137
143
  method: "GET",
144
+ operation: "users.list",
138
145
  path: `${basePath}/admin/users`,
139
146
  scope: AUTH_USERS_READ_SCOPE,
147
+ kind: "reads",
140
148
  summary: "Find a user. Lists everyone newest first, or searches email and display name."
141
149
  },
142
150
  {
143
151
  method: "GET",
152
+ operation: "users.read",
144
153
  path: `${basePath}/admin/users/:userId`,
145
154
  scope: AUTH_USERS_READ_SCOPE,
155
+ kind: "reads",
146
156
  summary: "One user, with where they are signed in and what they sign in with."
147
157
  },
148
158
  {
149
159
  method: "GET",
160
+ operation: "devices.list",
150
161
  path: `${basePath}/admin/devices`,
151
162
  scope: AUTH_DEVICES_READ_SCOPE,
163
+ kind: "reads",
152
164
  summary: "The device registry across users, most-recently-seen first."
153
165
  },
154
166
  {
155
167
  method: "POST",
168
+ operation: "sessions.revoke",
156
169
  path: `${basePath}/admin/sessions/revoke`,
157
170
  scope: AUTH_SESSIONS_REVOKE_SCOPE,
171
+ kind: "credentials",
158
172
  summary: "Kill one session. The rest of that person's sign-ins keep working."
159
173
  },
160
174
  {
161
175
  method: "POST",
176
+ operation: "users.sessions.revoke",
162
177
  path: `${basePath}/admin/users/:userId/sessions/revoke`,
163
178
  scope: AUTH_USERS_LOGOUT_SCOPE,
179
+ kind: "credentials",
164
180
  summary: "Sign a user out everywhere, on every device, immediately."
165
181
  },
166
182
  {
167
183
  method: "POST",
184
+ operation: "users.devices.revoke",
168
185
  path: `${basePath}/admin/users/:userId/devices/revoke`,
169
186
  scope: AUTH_DEVICES_REVOKE_SCOPE,
187
+ kind: "credentials",
170
188
  summary: "Sign one device out and forget it — for a phone reported lost."
189
+ },
190
+ {
191
+ method: "POST",
192
+ operation: "users.suspend",
193
+ path: `${basePath}/admin/users/:userId/suspend`,
194
+ scope: AUTH_USERS_SUSPEND_SCOPE,
195
+ kind: "writes",
196
+ summary: "Suspend a user, with a reason. Their sessions end and every sign-in is refused."
197
+ },
198
+ {
199
+ method: "POST",
200
+ operation: "users.reinstate",
201
+ path: `${basePath}/admin/users/:userId/reinstate`,
202
+ scope: AUTH_USERS_SUSPEND_SCOPE,
203
+ kind: "writes",
204
+ summary: "Lift a suspension, with a reason. They sign in again; no session comes back."
205
+ },
206
+ {
207
+ method: "DELETE",
208
+ operation: "users.delete",
209
+ path: `${basePath}/admin/users/:userId`,
210
+ scope: AUTH_USERS_DELETE_SCOPE,
211
+ kind: "deletes",
212
+ summary: "Delete a user, with a reason. Soft by default: restorable until the purge window closes. Hard, when named: erased now."
213
+ },
214
+ {
215
+ method: "POST",
216
+ operation: "users.restore",
217
+ path: `${basePath}/admin/users/:userId/restore`,
218
+ scope: AUTH_USERS_DELETE_SCOPE,
219
+ kind: "deletes",
220
+ summary: "Restore a deleted user inside the purge window, with a reason. They sign in again."
221
+ },
222
+ {
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",
233
+ path: `${basePath}/admin/users/:userId/export`,
234
+ scope: AUTH_USERS_EXPORT_SCOPE,
235
+ kind: "reads",
236
+ summary: "Everything the kit holds about one user, from every capability — the answer to an access request."
171
237
  }
172
238
  ];
173
239
  }
174
240
  //#endregion
175
- 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 };