@pithy-sh/auth 0.10.0 → 0.11.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 (116) hide show
  1. package/README.md +1 -1
  2. package/dist/admin/users.js +1 -1
  3. package/dist/audit/actions.d.ts +19 -0
  4. package/dist/audit/actions.d.ts.map +1 -1
  5. package/dist/audit/actions.js +20 -1
  6. package/dist/audit/emit.d.ts +2 -0
  7. package/dist/audit/emit.d.ts.map +1 -1
  8. package/dist/audit/emit.js +1 -1
  9. package/dist/capability.d.ts +19 -0
  10. package/dist/capability.d.ts.map +1 -1
  11. package/dist/capability.js +20 -3
  12. package/dist/data/tables.d.ts +1 -0
  13. package/dist/data/tables.d.ts.map +1 -1
  14. package/dist/data/userLifecycle.d.ts +1 -0
  15. package/dist/data/userLifecycle.d.ts.map +1 -1
  16. package/dist/data/userLifecycle.js +2 -1
  17. package/dist/http/adminRoutes.d.ts.map +1 -1
  18. package/dist/http/adminRoutes.js +270 -5
  19. package/dist/http/guards.d.ts +8 -7
  20. package/dist/http/guards.d.ts.map +1 -1
  21. package/dist/http/guards.js +38 -7
  22. package/dist/http/middleware.d.ts +25 -1
  23. package/dist/http/middleware.d.ts.map +1 -1
  24. package/dist/http/middleware.js +44 -3
  25. package/dist/http/responses.d.ts +180 -0
  26. package/dist/http/responses.d.ts.map +1 -1
  27. package/dist/http/responses.js +142 -1
  28. package/dist/http/routes.d.ts +1 -0
  29. package/dist/http/routes.d.ts.map +1 -1
  30. package/dist/http/routes.js +45 -3
  31. package/dist/http/schemas.d.ts +57 -0
  32. package/dist/http/schemas.d.ts.map +1 -1
  33. package/dist/http/schemas.js +51 -1
  34. package/dist/http/views.d.ts +39 -2
  35. package/dist/http/views.d.ts.map +1 -1
  36. package/dist/http/views.js +105 -1
  37. package/dist/instance/auth.d.ts.map +1 -1
  38. package/dist/instance/auth.js +2 -2
  39. package/dist/lifecycle/audited.d.ts +48 -0
  40. package/dist/lifecycle/audited.d.ts.map +1 -0
  41. package/dist/lifecycle/audited.js +65 -0
  42. package/dist/lifecycle/enforce.d.ts +37 -2
  43. package/dist/lifecycle/enforce.d.ts.map +1 -1
  44. package/dist/lifecycle/enforce.js +46 -5
  45. package/dist/lifecycle/reason.d.ts +11 -0
  46. package/dist/lifecycle/reason.d.ts.map +1 -0
  47. package/dist/lifecycle/reason.js +13 -0
  48. package/dist/lifecycle/request.d.ts +5 -2
  49. package/dist/lifecycle/request.d.ts.map +1 -1
  50. package/dist/lifecycle/request.js +6 -2
  51. package/dist/lifecycle/transitions.d.ts +158 -18
  52. package/dist/lifecycle/transitions.d.ts.map +1 -1
  53. package/dist/lifecycle/transitions.js +344 -70
  54. package/dist/migrations/0005_purge_once.d.ts +22 -0
  55. package/dist/migrations/0005_purge_once.d.ts.map +1 -0
  56. package/dist/migrations/0005_purge_once.js +35 -0
  57. package/dist/migrations/pluginTables.d.ts +8 -0
  58. package/dist/migrations/pluginTables.d.ts.map +1 -1
  59. package/dist/migrations/pluginTables.js +8 -1
  60. package/dist/migrations/set.d.ts +2 -1
  61. package/dist/migrations/set.d.ts.map +1 -1
  62. package/dist/migrations/set.js +4 -2
  63. package/dist/purge/contribution.d.ts +47 -0
  64. package/dist/purge/contribution.d.ts.map +1 -0
  65. package/dist/purge/contribution.js +141 -0
  66. package/dist/purge/retryPolicy.d.ts +22 -0
  67. package/dist/purge/retryPolicy.d.ts.map +1 -0
  68. package/dist/purge/retryPolicy.js +26 -0
  69. package/dist/purge/run.d.ts +88 -0
  70. package/dist/purge/run.d.ts.map +1 -0
  71. package/dist/purge/run.js +102 -0
  72. package/dist/purge/specs.d.ts +71 -0
  73. package/dist/purge/specs.d.ts.map +1 -0
  74. package/dist/purge/specs.js +72 -0
  75. package/dist/purge/start.d.ts +42 -0
  76. package/dist/purge/start.d.ts.map +1 -0
  77. package/dist/purge/start.js +37 -0
  78. package/dist/purge/workflow.d.ts +58 -0
  79. package/dist/purge/workflow.d.ts.map +1 -0
  80. package/dist/purge/workflow.js +96 -0
  81. package/dist/test-utils/accountFootprint.d.ts +10 -0
  82. package/dist/test-utils/accountFootprint.d.ts.map +1 -0
  83. package/dist/test-utils/accountFootprint.js +44 -0
  84. package/dist/version.generated.d.ts +1 -1
  85. package/dist/version.generated.js +1 -1
  86. package/docs/account-lifecycle.md +123 -11
  87. package/package.json +5 -5
  88. package/pithy.manifest.json +1 -1
  89. package/src/audit/actions.ts +19 -0
  90. package/src/audit/emit.ts +3 -1
  91. package/src/capability.ts +48 -1
  92. package/src/data/userLifecycle.ts +4 -1
  93. package/src/http/adminRoutes.ts +398 -2
  94. package/src/http/guards.ts +39 -7
  95. package/src/http/middleware.ts +45 -2
  96. package/src/http/responses.ts +245 -0
  97. package/src/http/routes.ts +55 -3
  98. package/src/http/schemas.ts +110 -0
  99. package/src/http/views.ts +147 -2
  100. package/src/instance/auth.ts +7 -2
  101. package/src/lifecycle/audited.ts +104 -0
  102. package/src/lifecycle/enforce.ts +55 -5
  103. package/src/lifecycle/reason.ts +11 -0
  104. package/src/lifecycle/request.ts +10 -2
  105. package/src/lifecycle/transitions.ts +482 -93
  106. package/src/migrations/0005_purge_once.ts +42 -0
  107. package/src/migrations/pluginTables.ts +19 -1
  108. package/src/migrations/set.ts +3 -1
  109. package/src/purge/contribution.ts +191 -0
  110. package/src/purge/retryPolicy.ts +26 -0
  111. package/src/purge/run.ts +185 -0
  112. package/src/purge/specs.ts +95 -0
  113. package/src/purge/start.ts +79 -0
  114. package/src/purge/workflow.ts +144 -0
  115. package/src/test-utils/accountFootprint.ts +95 -0
  116. package/src/version.generated.ts +1 -1
@@ -5,16 +5,24 @@ import { AuthAuditActions } from "../audit/actions.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 } 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, reinstateUser, requirePresent, restoreUser, suspendUser } from "../lifecycle/transitions.js";
13
+ import { auditedLifecycleCall, recordLifecycleRefusal } from "../lifecycle/audited.js";
14
+ import { AUTH_PURGE_BINDING } from "../purge/specs.js";
15
+ 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";
19
+ import { purgeExports } from "@pithy-sh/core/src/capability/purge";
13
20
  import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
14
21
  import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
15
22
  import { validate } from "@pithy-sh/core/src/http/validation";
16
- import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
17
23
  import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
24
+ import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
25
+ import { workflowBindingFor } from "@pithy-sh/core/src/workflow/dispatch";
18
26
  //#region src/http/adminRoutes.ts
19
27
  /**
20
28
  * The control-plane admin surface: the reads a management dashboard's user panes resolve to, and the
@@ -26,6 +34,11 @@ import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
26
34
  * POST {base}/admin/sessions/revoke auth:sessions:revoke json: RevokeSessionBody
27
35
  * POST {base}/admin/users/:userId/sessions/revoke auth:users:logout param: UserIdParam
28
36
  * POST {base}/admin/users/:userId/devices/revoke auth:devices:revoke param + json
37
+ * POST {base}/admin/users/:userId/suspend auth:users:suspend param + json: SuspendUserBody
38
+ * POST {base}/admin/users/:userId/reinstate auth:users:suspend param + json: ReinstateUserBody
39
+ * DELETE {base}/admin/users/:userId auth:users:delete param + json: DeleteUserBody
40
+ * POST {base}/admin/users/:userId/restore auth:users:delete param + json: RestoreUserBody
41
+ * GET {base}/admin/users/:userId/export auth:users:export param + query: ExportUserQuery
29
42
  *
30
43
  * ## Registered before the catch-all, or dead
31
44
  *
@@ -132,6 +145,116 @@ async function revokeTokens(c, wiring, tokens) {
132
145
  return tokens.length;
133
146
  }
134
147
  /**
148
+ * What a lifecycle route hands `../lifecycle/`: the transitions' dependencies, with the request's correlation
149
+ * and the connection on every audit event they write, and the operator as the actor.
150
+ *
151
+ * The actor is the token's verified `sub` — which person at the dashboard — the same id every other admin
152
+ * event records, so the trail and the history table name the same somebody.
153
+ */
154
+ function lifecycleCall(c, wiring, caller, userId, reason) {
155
+ const correlated = context(c);
156
+ return {
157
+ deps: lifecycleDeps(c, wiring, {
158
+ ...correlated,
159
+ metadata: { connectionId: caller.connectionId }
160
+ }),
161
+ actor: {
162
+ type: "control-plane",
163
+ id: caller.subject
164
+ },
165
+ restoreRoute: `POST ${wiring.config.basePath}/admin/users/${userId}/restore`,
166
+ audit: {
167
+ subject: caller.subject,
168
+ connectionId: caller.connectionId,
169
+ userId,
170
+ reason,
171
+ ...correlated
172
+ }
173
+ };
174
+ }
175
+ /**
176
+ * A lifecycle route's body validator, which audits the bodies it refuses (#621). Every call is on the trail,
177
+ * a refusal included, and a body the validator turns away never reaches `auditedLifecycleCall`. So it is
178
+ * recorded here, as `denied` under the route's own action, with whatever reason the body carried — cut to the
179
+ * reason's own limit, so a refused essay is not stored whole — and the 400 is thrown as before.
180
+ */
181
+ function lifecycleBody(schema, action) {
182
+ return validate("json", schema, async (raw, error, body) => {
183
+ const c = raw;
184
+ const caller = controlPlaneCaller(c);
185
+ const reason = body && typeof body === "object" ? body.reason : void 0;
186
+ await recordLifecycleRefusal(c.var.emit, {
187
+ action: typeof action === "string" ? action : action(body),
188
+ subject: caller.subject,
189
+ connectionId: caller.connectionId,
190
+ userId: c.req.valid("param").userId,
191
+ reason: typeof reason === "string" ? reason.slice(0, 500) : null,
192
+ ...context(c)
193
+ }, error, {
194
+ code: "validation/invalid_input",
195
+ outcome: "denied"
196
+ });
197
+ });
198
+ }
199
+ /**
200
+ * End every session an account holds, after its columns are written — never before, for the reason the suspend
201
+ * route gives: enforcement refuses the account the moment the columns land, and revoking first would leave a
202
+ * window for a sign-in the revocation never saw. Through Better Auth's adapter, so `onSessionRevoked` hears
203
+ * each, and recorded under `auth/admin_user_sessions_revoked` with the cause.
204
+ */
205
+ async function endSessions(c, wiring, caller, userId, cause) {
206
+ const revoked = await revokeTokens(c, wiring, await userSessionTokens(db(c, wiring), userId));
207
+ await emitControlPlaneAction(c.var.emit, {
208
+ action: AuthAuditActions.adminUserSessionsRevoked,
209
+ subject: caller.subject,
210
+ connectionId: caller.connectionId,
211
+ resourceType: "user",
212
+ resourceId: userId,
213
+ ...context(c),
214
+ metadata: {
215
+ revoked,
216
+ cause
217
+ }
218
+ });
219
+ return revoked;
220
+ }
221
+ /**
222
+ * Start the purge of one account now (#622): `started` when this Worker binds the purge Workflow and it took the
223
+ * instance — or already held it — and `pending` when it binds none or the start failed; the account is due
224
+ * either way, and the daily pass starts it. A failed start is not this call's failure: the deletion is already
225
+ * written, and a 500 over it would invite a retry that finds the account deleted and says nothing new.
226
+ *
227
+ * Under the instance id the deletion names (`../purge/start.ts`), so a hard deletion repeated, or one the daily
228
+ * pass also finds due, is the one purge and never a second.
229
+ */
230
+ async function startPurge(c, result, userId, notify) {
231
+ const log = c.var.log.child("auth");
232
+ const binding = workflowBindingFor(c.env, AUTH_PURGE_BINDING);
233
+ if (!binding) {
234
+ log.warn("a deletion found no purge Workflow bound; the purge is pending", { userId });
235
+ return "pending";
236
+ }
237
+ try {
238
+ await startPurgeInstance(binding, {
239
+ userId,
240
+ deletedAt: result.deletedAt.getTime(),
241
+ ...notify === void 0 ? {} : { notify },
242
+ at: /* @__PURE__ */ new Date()
243
+ });
244
+ return "started";
245
+ } catch (error) {
246
+ log.warn("the purge could not be started; the daily pass will start it", {
247
+ userId,
248
+ reason: error instanceof Error ? error.message : String(error)
249
+ });
250
+ return "pending";
251
+ }
252
+ }
253
+ /** What becomes of a soft deletion's purge: due later, or — when its window has already closed — due now. */
254
+ function scheduledOrDue(result) {
255
+ return result.purgeAfter.getTime() > Date.now() ? "scheduled" : "due";
256
+ }
257
+ /**
135
258
  * Register the control-plane admin routes. Called by `createAuthRoutes` **before** the Better Auth
136
259
  * catch-all; see the file header for why that ordering is load-bearing.
137
260
  */
@@ -301,6 +424,148 @@ function registerAuthAdminRoutes(wiring) {
301
424
  removed
302
425
  });
303
426
  });
427
+ app.post(`${base}/admin/users/:userId/suspend`, describeRoute({
428
+ summary: "Suspend one user, with a reason: their sessions end and every sign-in is refused.",
429
+ verification: "control-plane",
430
+ scopes: [AUTH_USERS_SUSPEND_SCOPE],
431
+ responses: { 200: AdminUserSuspendResponse }
432
+ }), requireControlPlane(AUTH_USERS_SUSPEND_SCOPE), validate("param", UserIdParam), lifecycleBody(SuspendUserBody, AuthAuditActions.adminUserSuspended), async (c) => {
433
+ const { userId } = c.req.valid("param");
434
+ const { reason, until, notify } = c.req.valid("json");
435
+ const caller = controlPlaneCaller(c);
436
+ const call = lifecycleCall(c, wiring, caller, userId, reason);
437
+ const result = await auditedLifecycleCall(c.var.emit, {
438
+ action: AuthAuditActions.adminUserSuspended,
439
+ ...call.audit
440
+ }, () => suspendUser(call.deps, {
441
+ userId,
442
+ actor: call.actor,
443
+ reason,
444
+ until: until ?? null,
445
+ ...notify === void 0 ? {} : { notify },
446
+ restoreRoute: call.restoreRoute
447
+ }), () => false);
448
+ const revoked = await revokeTokens(c, wiring, await userSessionTokens(db(c, wiring), userId));
449
+ await emitControlPlaneAction(c.var.emit, {
450
+ action: AuthAuditActions.adminUserSessionsRevoked,
451
+ subject: caller.subject,
452
+ connectionId: caller.connectionId,
453
+ resourceType: "user",
454
+ resourceId: userId,
455
+ ...context(c),
456
+ metadata: {
457
+ revoked,
458
+ cause: "suspended"
459
+ }
460
+ });
461
+ return c.json(suspensionView(userId, result, revoked));
462
+ });
463
+ app.post(`${base}/admin/users/:userId/reinstate`, describeRoute({
464
+ summary: "Lift one user's suspension, with a reason. They sign in again; no session is restored.",
465
+ verification: "control-plane",
466
+ scopes: [AUTH_USERS_SUSPEND_SCOPE],
467
+ responses: { 200: AdminUserReinstateResponse }
468
+ }), requireControlPlane(AUTH_USERS_SUSPEND_SCOPE), validate("param", UserIdParam), lifecycleBody(ReinstateUserBody, AuthAuditActions.adminUserReinstated), async (c) => {
469
+ const { userId } = c.req.valid("param");
470
+ const { reason, notify } = c.req.valid("json");
471
+ const call = lifecycleCall(c, wiring, controlPlaneCaller(c), userId, reason);
472
+ const result = await auditedLifecycleCall(c.var.emit, {
473
+ action: AuthAuditActions.adminUserReinstated,
474
+ ...call.audit
475
+ }, () => reinstateUser(call.deps, {
476
+ userId,
477
+ actor: call.actor,
478
+ reason,
479
+ ...notify === void 0 ? {} : { notify },
480
+ restoreRoute: call.restoreRoute
481
+ }), (outcome) => !outcome.changed);
482
+ return c.json(reinstatementView(userId, result));
483
+ });
484
+ app.delete(`${base}/admin/users/:userId`, describeRoute({
485
+ summary: "Delete one user, with a reason: soft by default, restorable until the purge window closes; hard when named, purged now.",
486
+ verification: "control-plane",
487
+ scopes: [AUTH_USERS_DELETE_SCOPE],
488
+ responses: { 200: AdminUserDeleteResponse }
489
+ }), requireControlPlane(AUTH_USERS_DELETE_SCOPE), validate("param", UserIdParam), lifecycleBody(DeleteUserBody, (body) => body?.mode === "hard" ? AuthAuditActions.adminUserHardDeleted : AuthAuditActions.adminUserSoftDeleted), async (c) => {
490
+ const { userId } = c.req.valid("param");
491
+ const { mode, reason, notify } = c.req.valid("json");
492
+ const caller = controlPlaneCaller(c);
493
+ const call = lifecycleCall(c, wiring, caller, userId, reason);
494
+ const action = mode === "hard" ? AuthAuditActions.adminUserHardDeleted : AuthAuditActions.adminUserSoftDeleted;
495
+ const result = await auditedLifecycleCall(c.var.emit, {
496
+ action,
497
+ ...call.audit
498
+ }, () => deleteUser(call.deps, {
499
+ userId,
500
+ actor: call.actor,
501
+ reason,
502
+ mode,
503
+ ...notify === void 0 ? {} : { notify }
504
+ }), (outcome) => outcome.outcome === "unchanged");
505
+ const sessionsRevoked = await endSessions(c, wiring, caller, userId, "deleted");
506
+ const disposition = mode === "hard" ? "due" : scheduledOrDue(result);
507
+ const purge = disposition === "due" ? await startPurge(c, result, userId, mode === "hard" ? notify : void 0) : disposition;
508
+ return c.json(deletionView(userId, mode, result, purge, sessionsRevoked));
509
+ });
510
+ app.post(`${base}/admin/users/:userId/restore`, describeRoute({
511
+ summary: "Restore one deleted user inside the purge window, with a reason. They sign in again; no session is restored.",
512
+ verification: "control-plane",
513
+ scopes: [AUTH_USERS_DELETE_SCOPE],
514
+ responses: { 200: AdminUserRestoreResponse }
515
+ }), requireControlPlane(AUTH_USERS_DELETE_SCOPE), validate("param", UserIdParam), lifecycleBody(RestoreUserBody, AuthAuditActions.adminUserRestored), async (c) => {
516
+ const { userId } = c.req.valid("param");
517
+ const { reason } = c.req.valid("json");
518
+ const call = lifecycleCall(c, wiring, controlPlaneCaller(c), userId, reason);
519
+ const result = await auditedLifecycleCall(c.var.emit, {
520
+ action: AuthAuditActions.adminUserRestored,
521
+ ...call.audit
522
+ }, () => restoreUser(call.deps, {
523
+ userId,
524
+ actor: call.actor,
525
+ reason
526
+ }), (outcome) => !outcome.changed);
527
+ return c.json(restorationView(userId, result));
528
+ });
529
+ app.get(`${base}/admin/users/:userId/export`, describeRoute({
530
+ summary: "Export everything the kit holds about one user, from every composed capability, as one document.",
531
+ 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.",
532
+ verification: "control-plane",
533
+ scopes: [AUTH_USERS_EXPORT_SCOPE],
534
+ responses: { 200: AdminUserExportResponse }
535
+ }), requireControlPlane(AUTH_USERS_EXPORT_SCOPE), validate("param", UserIdParam), validate("query", ExportUserQuery), async (c) => {
536
+ const { userId } = c.req.valid("param");
537
+ const { reason } = c.req.valid("query");
538
+ const caller = controlPlaneCaller(c);
539
+ const call = lifecycleCall(c, wiring, caller, userId, reason);
540
+ const exportedAt = /* @__PURE__ */ new Date();
541
+ const entries = await auditedLifecycleCall(c.var.emit, {
542
+ action: AuthAuditActions.adminUserExported,
543
+ ...call.audit
544
+ }, async () => {
545
+ await requirePresent(db(c, wiring), userId);
546
+ return purgeExports(wiring.purgeSteps ?? [], {
547
+ subject: {
548
+ type: "user",
549
+ id: userId
550
+ },
551
+ env: c.env
552
+ });
553
+ }, () => false);
554
+ await emitControlPlaneAction(c.var.emit, {
555
+ action: AuthAuditActions.adminUserExported,
556
+ subject: caller.subject,
557
+ connectionId: caller.connectionId,
558
+ resourceType: "user",
559
+ resourceId: userId,
560
+ ...context(c),
561
+ metadata: {
562
+ reason,
563
+ disclosure: true,
564
+ capabilities: entries.map((entry) => `${entry.capability}:${entry.state}`)
565
+ }
566
+ });
567
+ return c.json(exportView(userId, exportedAt, entries));
568
+ });
304
569
  };
305
570
  }
306
571
  //#endregion
@@ -85,20 +85,21 @@ 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 (#620): `POST {base}/admin/users/:userId/suspend` and `/reinstate` (#621). 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 (#620):
95
+ * `DELETE {base}/admin/users/:userId` and `POST …/restore` (#622). 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 (#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
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,9 +107,9 @@ export declare const AUTH_USERS_EXPORT_SCOPE: ControlPlaneScope;
106
107
  * Every control-plane scope auth defines — what `pithy dashboard connect` offers for this capability,
107
108
  * and the list a manifest or a doc quotes rather than re-typing.
108
109
  *
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.
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.
112
113
  */
113
114
  export declare const AUTH_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[];
114
115
  /**
@@ -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,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"}
@@ -84,20 +84,21 @@ 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 (#620): `POST {base}/admin/users/:userId/suspend` and `/reinstate` (#621). 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 (#620):
94
+ * `DELETE {base}/admin/users/:userId` and `POST …/restore` (#622). 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 (#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
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";
@@ -105,9 +106,9 @@ const AUTH_USERS_EXPORT_SCOPE = "auth:users:export";
105
106
  * Every control-plane scope auth defines — what `pithy dashboard connect` offers for this capability,
106
107
  * and the list a manifest or a doc quotes rather than re-typing.
107
108
  *
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.
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.
111
112
  */
112
113
  const AUTH_CONTROL_PLANE_SCOPES = [
113
114
  AUTH_USERS_READ_SCOPE,
@@ -168,6 +169,36 @@ function authAdminRoutes(basePath) {
168
169
  path: `${basePath}/admin/users/:userId/devices/revoke`,
169
170
  scope: AUTH_DEVICES_REVOKE_SCOPE,
170
171
  summary: "Sign one device out and forget it — for a phone reported lost."
172
+ },
173
+ {
174
+ method: "POST",
175
+ path: `${basePath}/admin/users/:userId/suspend`,
176
+ scope: AUTH_USERS_SUSPEND_SCOPE,
177
+ summary: "Suspend a user, with a reason. Their sessions end and every sign-in is refused."
178
+ },
179
+ {
180
+ method: "POST",
181
+ path: `${basePath}/admin/users/:userId/reinstate`,
182
+ scope: AUTH_USERS_SUSPEND_SCOPE,
183
+ summary: "Lift a suspension, with a reason. They sign in again; no session comes back."
184
+ },
185
+ {
186
+ method: "DELETE",
187
+ path: `${basePath}/admin/users/:userId`,
188
+ scope: AUTH_USERS_DELETE_SCOPE,
189
+ summary: "Delete a user, with a reason. Soft by default: restorable until the purge window closes. Hard, when named: erased now."
190
+ },
191
+ {
192
+ method: "POST",
193
+ path: `${basePath}/admin/users/:userId/restore`,
194
+ scope: AUTH_USERS_DELETE_SCOPE,
195
+ summary: "Restore a deleted user inside the purge window, with a reason. They sign in again."
196
+ },
197
+ {
198
+ method: "GET",
199
+ path: `${basePath}/admin/users/:userId/export`,
200
+ scope: AUTH_USERS_EXPORT_SCOPE,
201
+ summary: "Everything the kit holds about one user, from every capability — the answer to an access request."
171
202
  }
172
203
  ];
173
204
  }
@@ -1,7 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
  import type { PithyHonoEnv, PithyMiddleware } from "@pithy-sh/core/src/capability/capability";
4
- import type { MiddlewareHandler } from "hono";
4
+ import type { Context, MiddlewareHandler } from "hono";
5
5
  import type { AuthWiring } from "../capability";
6
6
  export declare function createSessionMiddleware(wiring: AuthWiring): PithyMiddleware;
7
7
  /**
@@ -14,4 +14,28 @@ export declare function createSessionMiddleware(wiring: AuthWiring): PithyMiddle
14
14
  * middleware's, remembered for this request; this guard only raises it.
15
15
  */
16
16
  export declare function requireAuth(): MiddlewareHandler<PithyHonoEnv>;
17
+ /** Whose account a request may act on as its own holder: the signed-in account, or a suspended one's. */
18
+ export interface AccountHolder {
19
+ /** The account. */
20
+ readonly userId: string;
21
+ /** The session the request presented. */
22
+ readonly sessionId: string;
23
+ /** Whether the account is suspended — every other route refuses it. */
24
+ readonly suspended: boolean;
25
+ }
26
+ /**
27
+ * The account this request's credential opens, for a route a **suspended** account may still use — and there is
28
+ * exactly one, deleting it (#622). The App Store and Google Play require that a person can delete their account
29
+ * from inside the app, and a suspension is no reason to keep somebody who wants to leave.
30
+ *
31
+ * A deleted account is not admitted: there is nothing left to delete. Neither is a request whose standing could
32
+ * not be checked.
33
+ */
34
+ export declare function accountHolder(c: Context<PithyHonoEnv>): AccountHolder | null;
35
+ /**
36
+ * The gate for that route: `requireAuth()`, with a suspended account's genuine credential admitted. Everything
37
+ * `requireAuth()` refuses otherwise, it refuses the same way — a deleted account with its code, anything else
38
+ * with `auth/invalid_token`.
39
+ */
40
+ export declare function requireAccountHolder(): MiddlewareHandler<PithyHonoEnv>;
17
41
  //# sourceMappingURL=middleware.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/http/middleware.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAI9F,OAAO,KAAK,EAAW,iBAAiB,EAAE,MAAM,MAAM,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAuC,MAAM,eAAe,CAAC;AA6DrF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,GAAG,eAAe,CAqB3E;AA4FD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CAAC,YAAY,CAAC,CAY7D"}
1
+ {"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/http/middleware.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAI9F,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAuC,MAAM,eAAe,CAAC;AA6DrF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,GAAG,eAAe,CAqB3E;AA4FD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CAAC,YAAY,CAAC,CAY7D;AAED,yGAAyG;AACzG,MAAM,WAAW,aAAa;IAC5B,mBAAmB;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,aAAa,GAAG,IAAI,CAI5E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,CAAC,YAAY,CAAC,CAYtE"}
@@ -2,7 +2,7 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
  import { authDatabase } from "../data/tables.js";
4
4
  import { LifecycleColumns } from "../lifecycle/state.js";
5
- import { lifecycleRefusalFor, noteRefusal, noticedRefusal } from "../lifecycle/enforce.js";
5
+ import { lifecycleRefusalFor, noteRefusal, noticedRefusal, suspendedHolder } from "../lifecycle/enforce.js";
6
6
  import { getAuthInstance, resolveDb } from "./resolve.js";
7
7
  import { withResignedCredentials } from "./credentialResign.js";
8
8
  import { InternalError, UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
@@ -79,7 +79,10 @@ async function resolveSession(c, wiring, instance) {
79
79
  if (session) {
80
80
  const refusal = await standingRefusal(c, wiring, session.user);
81
81
  if (refusal) {
82
- noteRefusal(c, refusal);
82
+ noteRefusal(c, refusal, {
83
+ userId: session.user.id,
84
+ sessionId: session.session.id
85
+ });
83
86
  return;
84
87
  }
85
88
  const scopes = await resolvedScopes(c, wiring.resolveScopes, {
@@ -143,5 +146,43 @@ function requireAuth() {
143
146
  await next();
144
147
  };
145
148
  }
149
+ /**
150
+ * The account this request's credential opens, for a route a **suspended** account may still use — and there is
151
+ * exactly one, deleting it (#622). The App Store and Google Play require that a person can delete their account
152
+ * from inside the app, and a suspension is no reason to keep somebody who wants to leave.
153
+ *
154
+ * A deleted account is not admitted: there is nothing left to delete. Neither is a request whose standing could
155
+ * not be checked.
156
+ */
157
+ function accountHolder(c) {
158
+ if (c.var.auth) return {
159
+ userId: c.var.auth.userId,
160
+ sessionId: c.var.auth.sessionId,
161
+ suspended: false
162
+ };
163
+ const held = suspendedHolder(c);
164
+ return held ? {
165
+ ...held,
166
+ suspended: true
167
+ } : null;
168
+ }
169
+ /**
170
+ * The gate for that route: `requireAuth()`, with a suspended account's genuine credential admitted. Everything
171
+ * `requireAuth()` refuses otherwise, it refuses the same way — a deleted account with its code, anything else
172
+ * with `auth/invalid_token`.
173
+ */
174
+ function requireAccountHolder() {
175
+ return async (c, next) => {
176
+ if (!accountHolder(c)) {
177
+ const refusal = noticedRefusal(c);
178
+ if (refusal) throw refusal;
179
+ throw new UnauthorizedError({
180
+ message: "Authentication required.",
181
+ action: "Sign in and retry with a valid session or bearer token."
182
+ });
183
+ }
184
+ await next();
185
+ };
186
+ }
146
187
  //#endregion
147
- export { createSessionMiddleware, requireAuth };
188
+ export { accountHolder, createSessionMiddleware, requireAccountHolder, requireAuth };