@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
@@ -0,0 +1,158 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { type PurgeStep } from "@pithy-sh/core/src/capability/purge";
4
+ import type { LegalHolds } from "@pithy-sh/core/src/retention/holds";
5
+ import { type TerminalErrorConstructor, type WorkflowStepLike } from "@pithy-sh/core/src/workflow/faults";
6
+ import { type DuePurge, type LifecycleDeps } from "../lifecycle/transitions";
7
+ import { type AuthPurgeDueParams, type AuthPurgeParams } from "./specs";
8
+ /**
9
+ * The purge, as steps (#622) — the bodies `./workflow.ts` hands a Workflow's step runner to.
10
+ *
11
+ * ## One step per contribution, and the order they run in
12
+ *
13
+ * 1. **`due`** — is the account deleted, and has its window closed? A restored account, one inside its window,
14
+ * and one already erased all end the run here, having erased nothing. This is the one check a cron-started
15
+ * purge and a hard deletion's both pass through, so re-running a purge for the same subject exits cleanly.
16
+ * 2. **`erase <capability>`** — one step per composed contribution, in composition order, each recording that it
17
+ * ran in `pithy_auth_user_lifecycle`. A contribution that **retains** its rows (#814) is a `retain <capability>`
18
+ * step instead: it erases nothing, and records `purge_retained` with the basis it gave. Handed to the platform's retry unclassified: an `erase` is idempotent by
19
+ * contract and runs code the kit did not write, so any fault in it is worth another attempt (`./retryPolicy.ts`).
20
+ * A failing contribution retries alone, and the ones that finished are served from the journal.
21
+ * 3. **`mail`** — the deletion-complete mail, **before the address is erased**: every other capability's rows are
22
+ * gone, and auth's, which hold the address, are not yet. The address is read in the step, never carried out of
23
+ * one, so it is in no Workflow's journal.
24
+ * 4. **`erase auth`** — auth's own contribution, last for that reason.
25
+ * 5. **`complete`** — the `purged` record, the audit event, `onUserPurged`. Once.
26
+ *
27
+ * Every step from 2 on records an audit event as well as its row (#823), which the erasure attestation cites.
28
+ *
29
+ * ## A legal hold stops it
30
+ *
31
+ * Before `due` hands over, and again before every step after it, the purge asks whether a legal hold stands on the
32
+ * account — each ask its own step, `hold <next>`, so a replay serves the answer it got. A hold found ends the run as
33
+ * `held`, having erased nothing more: the steps that finished stay finished, the rest wait. Released, the account is
34
+ * still deleted and still due, so the next daily pass starts a fresh purge, whose idempotent steps find nothing to
35
+ * erase where the first one did and carry on from there. A hold that cannot be read fails its step, which retries:
36
+ * a purge never erases past a hold it could not see.
37
+ *
38
+ * ## A purge that gives up says where (#823)
39
+ *
40
+ * A step that exhausts its retries fails the instance, and the daily pass starts a fresh one tomorrow. Until then the
41
+ * record would read as a purge still running. So the failure is caught once, recorded in its own `fail` step —
42
+ * the step it stopped at, in the history and the trail — and thrown on unchanged, so the instance still fails
43
+ * exactly as it did. A `fail` step that cannot write either is swallowed: the original failure is the one to report.
44
+ */
45
+ /** What a purge does with the account's own records — the transitions, over one set of dependencies. */
46
+ export interface PurgeOps {
47
+ /** Whether the account is due: deleted, with its window closed. `gone` when there is no account. */
48
+ due(userId: string): Promise<"due" | "not_due" | "gone">;
49
+ /** Record that one capability's step erased its rows. */
50
+ recordStep(userId: string, step: string, summary: string): Promise<void>;
51
+ /** Record that one capability's step kept its rows, and why (#814). */
52
+ recordRetained(userId: string, step: string, basis: string): Promise<void>;
53
+ /**
54
+ * The account's address, read now, or `null` once it is gone (#814). Handed to each step as
55
+ * `PurgeContext.address`, so a capability holding rows by address reads it inside its own step.
56
+ */
57
+ address(userId: string): Promise<string | null>;
58
+ /**
59
+ * Send the deletion-complete mail to the account's address, if it is still there to read, unless this purge's
60
+ * `notify` or the deletion's own saved choice is false. Says whether.
61
+ */
62
+ mailComplete(userId: string, notify: boolean | undefined): Promise<boolean>;
63
+ /** Write the `purged` record, the audit event and the hook. Says whether this call wrote them. */
64
+ complete(userId: string): Promise<boolean>;
65
+ /** Record that the purge gave up at `step`, in the history and the trail (#823). */
66
+ fail(userId: string, step: string): Promise<void>;
67
+ /** Whether a legal hold stands on the account. Throws when it cannot say. */
68
+ held(userId: string): Promise<boolean>;
69
+ }
70
+ /** The operations, over the lifecycle transitions. */
71
+ export declare function purgeOps(deps: LifecycleDeps, holds: LegalHolds): PurgeOps;
72
+ /** What one purge did: the account, how it ended, and the capabilities whose rows it erased. */
73
+ export interface PurgeOutcome {
74
+ /** The account. */
75
+ readonly userId: string;
76
+ /**
77
+ * `purged`; or why nothing was erased: `not_due` (restored, or inside its window) and `gone` (no account); or
78
+ * `held`, a legal hold stopped it before the step it would have run next.
79
+ */
80
+ readonly state: "purged" | "not_due" | "gone" | "held";
81
+ /** Every step that erased its rows, in the order it ran. Empty when nothing was erased. */
82
+ readonly erased: readonly string[];
83
+ /** Every step that kept its rows under a stated basis (#814), in the order it ran. */
84
+ readonly retained: readonly string[];
85
+ /** Whether the deletion-complete mail was enqueued. */
86
+ readonly mailed: boolean;
87
+ }
88
+ /** What one purge reads its plan from: the composed contributions, this run's env, and its operations. */
89
+ export interface PurgeRun {
90
+ /** Every composed purge step for `user`, auth's own among them. */
91
+ readonly steps: readonly PurgeStep[];
92
+ /** This run's bindings, handed to each contribution. */
93
+ readonly env: Record<string, unknown>;
94
+ /** The account's own records. */
95
+ readonly ops: PurgeOps;
96
+ }
97
+ /** Run one account's purge, one step per contribution, auth's last. See the file header for the order. */
98
+ export declare function purgeUser(run: PurgeRun, step: WorkflowStepLike, terminalError: TerminalErrorConstructor, params: AuthPurgeParams): Promise<PurgeOutcome>;
99
+ /** How many purges one `start` step dispatches — a page, so one pass over a backlog is a bounded number of steps. */
100
+ export declare const PURGE_START_PAGE = 50;
101
+ /** The default size of one daily pass. */
102
+ export declare const PURGE_DUE_DEFAULT_LIMIT = 500;
103
+ /** What the daily pass reads and starts through. */
104
+ export interface PurgeDueRun {
105
+ /** Every account whose purge is due, oldest first, at most `limit`, with the deletion it is due under. */
106
+ due(limit: number): Promise<DuePurge[]>;
107
+ /**
108
+ * Start one account's purge — under the instance id its deletion names, so a start repeated is the same one.
109
+ * Says whether the purge is running: started now, or found already started. `false` when it could not be
110
+ * started, and the pass does not count it.
111
+ */
112
+ start(due: DuePurge): Promise<boolean>;
113
+ /**
114
+ * Whether a legal hold stands on the account. A held account is not started; absent, every due account is,
115
+ * and each purge's own hold check stops it before its first step.
116
+ */
117
+ held?(userId: string): Promise<boolean>;
118
+ }
119
+ /**
120
+ * The daily pass (#622): list every account past its window, and start a purge for each — in pages, one step
121
+ * each, so a pass that dies part-way resumes after the page it finished rather than starting every purge
122
+ * again. An account still inside its window is not listed, so it is not started.
123
+ */
124
+ export declare function startDuePurges(run: PurgeDueRun, step: WorkflowStepLike, terminalError: TerminalErrorConstructor, params: AuthPurgeDueParams): Promise<{
125
+ started: number;
126
+ }>;
127
+ /** The daily pass's reads, over the lifecycle transitions. */
128
+ export declare function duePurgesOf(deps: LifecycleDeps): PurgeDueRun["due"];
129
+ /** How many inactive accounts one pass soft-deletes, at most: a backlog drains over nights, never in one. */
130
+ export declare const INACTIVE_DEFAULT_LIMIT = 200;
131
+ /** What the inactivity pass reads and deletes through. */
132
+ export interface InactivityRun {
133
+ /**
134
+ * The longest an account may sit inactive, in days — the strictest class age it holds — or null for no limit.
135
+ * Asked inside a step, so a replay serves the answer it got.
136
+ */
137
+ days(): Promise<number | null>;
138
+ /** Every account inactive since `cutoff`, oldest first, at most `limit`. */
139
+ inactive(cutoff: Date, limit: number): Promise<string[]>;
140
+ /** Whether a legal hold stands on the account. */
141
+ held(userId: string): Promise<boolean>;
142
+ /** Soft-delete one account through the lifecycle, with its notice mail and window. Says whether it was deleted. */
143
+ remove(userId: string, days: number): Promise<boolean>;
144
+ /** Now. */
145
+ now(): Date;
146
+ }
147
+ /**
148
+ * The inactivity pass: every account untouched for longer than the strictest class age it holds is
149
+ * soft-deleted through the lifecycle — its deletion-scheduled mail, its window, then the purge the daily pass starts
150
+ * once that window closes. A held account is skipped. With no class age that applies, the pass does nothing.
151
+ *
152
+ * Listed in one step, deleted in pages of steps, so a pass that dies part-way resumes after the page it finished.
153
+ * A deletion is no transition on an account already deleted, so a repeated page deletes nobody twice.
154
+ */
155
+ export declare function deleteInactiveAccounts(run: InactivityRun, step: WorkflowStepLike, terminalError: TerminalErrorConstructor, limit?: number): Promise<{
156
+ deleted: number;
157
+ }>;
158
+ //# sourceMappingURL=run.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/purge/run.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,205 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { completePurge, duePurges, mailPurgeComplete, purgeAddress, purgeSubject, recordPurgeFailure, recordPurgeStep } from "../lifecycle/transitions.js";
4
+ import { AUTH_CAPABILITY } from "./specs.js";
5
+ import { authWorkflowRetry } from "./retryPolicy.js";
6
+ import { isRetained } from "@pithy-sh/core/src/capability/purge";
7
+ import { classifiedSteps } from "@pithy-sh/core/src/workflow/faults";
8
+ //#region src/purge/run.ts
9
+ /** The operations, over the lifecycle transitions. */
10
+ function purgeOps(deps, holds) {
11
+ return {
12
+ due: async (userId) => (await purgeSubject(deps, userId)).state,
13
+ recordStep: (userId, step, summary) => recordPurgeStep(deps, {
14
+ userId,
15
+ step,
16
+ summary
17
+ }),
18
+ recordRetained: (userId, step, basis) => recordPurgeStep(deps, {
19
+ userId,
20
+ step,
21
+ summary: basis,
22
+ retained: true
23
+ }),
24
+ address: (userId) => purgeAddress(deps.db, userId),
25
+ mailComplete: async (userId, notify) => {
26
+ const subject = await purgeSubject(deps, userId);
27
+ if (subject.state !== "due") return false;
28
+ const silenced = notify === false || subject.notify === false;
29
+ return (await mailPurgeComplete(deps, {
30
+ recipient: subject.recipient,
31
+ ...silenced ? { notify: false } : {}
32
+ })).mailed;
33
+ },
34
+ complete: async (userId) => (await completePurge(deps, { userId })).changed,
35
+ fail: (userId, step) => recordPurgeFailure(deps, {
36
+ userId,
37
+ step
38
+ }),
39
+ held: (userId) => holds.held("user", userId)
40
+ };
41
+ }
42
+ /** Run one account's purge, one step per contribution, auth's last. See the file header for the order. */
43
+ async function purgeUser(run, step, terminalError, params) {
44
+ const own = classifiedSteps(step, authWorkflowRetry, terminalError);
45
+ const userId = params.userId;
46
+ const state = await own.do("due", () => run.ops.due(userId));
47
+ if (state !== "due") return {
48
+ userId,
49
+ state,
50
+ erased: [],
51
+ retained: [],
52
+ mailed: false
53
+ };
54
+ const stopped = (next) => own.do(`hold ${next}`, () => run.ops.held(userId));
55
+ const context = {
56
+ subject: {
57
+ type: "user",
58
+ id: userId
59
+ },
60
+ env: run.env,
61
+ address: () => run.ops.address(userId)
62
+ };
63
+ const auth = run.steps.filter((each) => each.step === AUTH_CAPABILITY);
64
+ const others = run.steps.filter((each) => each.step !== AUTH_CAPABILITY);
65
+ const erased = [];
66
+ const retained = [];
67
+ let current = "due";
68
+ const held = {
69
+ userId,
70
+ state: "held",
71
+ erased,
72
+ retained,
73
+ mailed: false
74
+ };
75
+ const runStep = async (each) => {
76
+ const { contribution } = each;
77
+ current = each.step;
78
+ if (isRetained(contribution)) retained.push(await retainStep(step, run.ops, each.step, contribution.retain.basis, userId));
79
+ else erased.push(await eraseStep(step, run.ops, each, context));
80
+ };
81
+ try {
82
+ for (const each of others) {
83
+ if (await stopped(each.step)) return held;
84
+ await runStep(each);
85
+ }
86
+ current = "mail";
87
+ if (await stopped("mail")) return held;
88
+ const mailed = await own.do("mail", () => run.ops.mailComplete(userId, params.notify));
89
+ for (const each of auth) {
90
+ if (await stopped(each.step)) return {
91
+ ...held,
92
+ mailed
93
+ };
94
+ await runStep(each);
95
+ }
96
+ current = "complete";
97
+ await own.do("complete", () => run.ops.complete(userId));
98
+ return {
99
+ userId,
100
+ state: "purged",
101
+ erased,
102
+ retained,
103
+ mailed
104
+ };
105
+ } catch (error) {
106
+ await recordFailure(step, run.ops, userId, current);
107
+ throw error;
108
+ }
109
+ }
110
+ /**
111
+ * Record where a purge gave up, in its own step, and never mask the failure that stopped it: a `fail` step that
112
+ * cannot write is swallowed. See the file header.
113
+ */
114
+ async function recordFailure(step, ops, userId, at) {
115
+ try {
116
+ await step.do("fail", async () => {
117
+ await ops.fail(userId, at);
118
+ return at;
119
+ });
120
+ } catch {}
121
+ }
122
+ /**
123
+ * One capability's step: erase, then record that it ran. On the platform's own retry, unclassified — see the
124
+ * file header. Recorded inside the same step, so a step that erased and failed to record is retried whole, and
125
+ * the second erase finds nothing.
126
+ */
127
+ function eraseStep(step, ops, each, context) {
128
+ return step.do(`erase ${each.step}`, async () => {
129
+ await each.contribution.erase?.(context);
130
+ await ops.recordStep(context.subject.id, each.step, each.contribution.summary);
131
+ return each.step;
132
+ });
133
+ }
134
+ /**
135
+ * One capability's retained step (#814): nothing is erased, and the record says the rows were kept and why. Its own
136
+ * step, so the trail names it in the order it would have run, and a replay serves it from the journal.
137
+ */
138
+ function retainStep(step, ops, name, basis, userId) {
139
+ return step.do(`retain ${name}`, async () => {
140
+ await ops.recordRetained(userId, name, basis);
141
+ return name;
142
+ });
143
+ }
144
+ /** How many purges one `start` step dispatches — a page, so one pass over a backlog is a bounded number of steps. */
145
+ const PURGE_START_PAGE = 50;
146
+ /** The default size of one daily pass. */
147
+ const PURGE_DUE_DEFAULT_LIMIT = 500;
148
+ /**
149
+ * The daily pass (#622): list every account past its window, and start a purge for each — in pages, one step
150
+ * each, so a pass that dies part-way resumes after the page it finished rather than starting every purge
151
+ * again. An account still inside its window is not listed, so it is not started.
152
+ */
153
+ async function startDuePurges(run, step, terminalError, params) {
154
+ const own = classifiedSteps(step, authWorkflowRetry, terminalError);
155
+ const limit = params.limit ?? 500;
156
+ const due = await own.do("due", () => run.due(limit));
157
+ let started = 0;
158
+ for (let page = 0; page * 50 < due.length; page += 1) {
159
+ const ids = due.slice(page * 50, (page + 1) * 50);
160
+ started += await own.do(`start ${page + 1}`, async () => {
161
+ let running = 0;
162
+ for (const each of ids) {
163
+ if (run.held && await run.held(each.userId)) continue;
164
+ if (await run.start(each)) running += 1;
165
+ }
166
+ return running;
167
+ });
168
+ }
169
+ return { started };
170
+ }
171
+ /** The daily pass's reads, over the lifecycle transitions. */
172
+ function duePurgesOf(deps) {
173
+ return (limit) => duePurges(deps, limit);
174
+ }
175
+ /** How many inactive accounts one pass soft-deletes, at most: a backlog drains over nights, never in one. */
176
+ const INACTIVE_DEFAULT_LIMIT = 200;
177
+ /**
178
+ * The inactivity pass: every account untouched for longer than the strictest class age it holds is
179
+ * soft-deleted through the lifecycle — its deletion-scheduled mail, its window, then the purge the daily pass starts
180
+ * once that window closes. A held account is skipped. With no class age that applies, the pass does nothing.
181
+ *
182
+ * Listed in one step, deleted in pages of steps, so a pass that dies part-way resumes after the page it finished.
183
+ * A deletion is no transition on an account already deleted, so a repeated page deletes nobody twice.
184
+ */
185
+ async function deleteInactiveAccounts(run, step, terminalError, limit = 200) {
186
+ const own = classifiedSteps(step, authWorkflowRetry, terminalError);
187
+ const days = await own.do("class age", () => run.days());
188
+ if (days === null) return { deleted: 0 };
189
+ const ids = await own.do("inactive", () => run.inactive(/* @__PURE__ */ new Date(run.now().getTime() - days * 864e5), limit));
190
+ let deleted = 0;
191
+ for (let page = 0; page * 50 < ids.length; page += 1) {
192
+ const slice = ids.slice(page * 50, (page + 1) * 50);
193
+ deleted += await own.do(`inactive ${page + 1}`, async () => {
194
+ let count = 0;
195
+ for (const userId of slice) {
196
+ if (await run.held(userId)) continue;
197
+ if (await run.remove(userId, days)) count += 1;
198
+ }
199
+ return count;
200
+ });
201
+ }
202
+ return { deleted };
203
+ }
204
+ //#endregion
205
+ export { INACTIVE_DEFAULT_LIMIT, PURGE_DUE_DEFAULT_LIMIT, PURGE_START_PAGE, deleteInactiveAccounts, duePurgesOf, purgeOps, purgeUser, startDuePurges };
@@ -0,0 +1,71 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { WorkflowRegistry } from "@pithy-sh/core/src/workflow/spec";
4
+ import { z } from "zod";
5
+ /** This capability's name, and the first segment of its workflow dispatch keys. */
6
+ export declare const AUTH_CAPABILITY = "auth";
7
+ /** The binding the purge of one account is started on. */
8
+ export declare const AUTH_PURGE_BINDING = "AUTH_PURGE";
9
+ /** The binding the daily pass that starts every due purge runs on. */
10
+ export declare const AUTH_PURGE_DUE_BINDING = "AUTH_PURGE_DUE";
11
+ /** The dispatch key of the purge of one account. */
12
+ export declare const AUTH_PURGE_KEY: string;
13
+ /** One account's purge: which, and whether its last mail is sent. */
14
+ export declare const AuthPurgeParams: z.ZodObject<{
15
+ userId: z.ZodString;
16
+ notify: z.ZodOptional<z.ZodBoolean>;
17
+ }, z.core.$strip>;
18
+ export type AuthPurgeParams = z.infer<typeof AuthPurgeParams>;
19
+ /**
20
+ * The daily pass's parameters. Every field optional, because a cron passes none — `createEntrypoint` starts a
21
+ * scheduled job with `{}`.
22
+ */
23
+ export declare const AuthPurgeDueParams: z.ZodObject<{
24
+ limit: z.ZodOptional<z.ZodNumber>;
25
+ }, z.core.$strip>;
26
+ export type AuthPurgeDueParams = z.infer<typeof AuthPurgeDueParams>;
27
+ /**
28
+ * The two durable jobs auth owns (#622) — **both hosted by the adopter's own Worker**, the one that composes
29
+ * auth, never a prebuilt host.
30
+ *
31
+ * **Why not a host.** A purge runs every composed capability's contribution, the adopter's own `app` among
32
+ * them, and those exist only in the Worker whose `pithy.config.ts` composed them. A prebuilt host composes
33
+ * nothing. So each class is five lines in the adopter's entry, calling `runAuthPurge` and `runAuthPurgeDue` in
34
+ * `./workflow.ts`, exactly as `@pithy-sh/payments`' usage pass is: Cloudflare resolves a `class_name` in the
35
+ * script that binds it, and the body finds the composition the way a Workflow that sends mail finds email.
36
+ * No `className` here, deliberately: the class is the adopter's, and so is its `workflows` entry. The docs
37
+ * give both (`docs/account-lifecycle.md`).
38
+ *
39
+ * **`purge-due` is daily at 02:00 UTC**, ahead of storage's and the secrets rotation at 03:00, payments' 04:00
40
+ * and testers' 05:00. Daily because the window is counted in days: an hourly pass would start the same purge
41
+ * twenty-four times and erase nothing sooner. Both stay dispatchable on demand — a hard deletion starts
42
+ * `purge` directly.
43
+ *
44
+ * `optional: true` for both, so a Worker composing auth still boots before the adopter has bound them. A
45
+ * deletion then reports its purge as `pending`, and nothing is erased until they are.
46
+ */
47
+ export declare const authWorkflows: {
48
+ readonly purge: {
49
+ readonly binding: "AUTH_PURGE";
50
+ readonly params: z.ZodObject<{
51
+ userId: z.ZodString;
52
+ notify: z.ZodOptional<z.ZodBoolean>;
53
+ }, z.core.$strip>;
54
+ readonly optional: true;
55
+ };
56
+ readonly "purge-due": {
57
+ readonly binding: "AUTH_PURGE_DUE";
58
+ readonly params: z.ZodObject<{
59
+ limit: z.ZodOptional<z.ZodNumber>;
60
+ }, z.core.$strip>;
61
+ readonly schedule: "0 2 * * *";
62
+ readonly optional: true;
63
+ };
64
+ };
65
+ /**
66
+ * The jobs as a dispatch registry, keyed `auth/<job>`, built here for the reason testers builds its own: the key
67
+ * format is core's either way. The daily pass starts each purge on the binding directly, not through this, because
68
+ * it names the instance (`./start.ts`) and dispatch does not.
69
+ */
70
+ export declare const authWorkflowRegistry: WorkflowRegistry;
71
+ //# sourceMappingURL=specs.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"specs.d.ts","sourceRoot":"","sources":["../../src/purge/specs.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAmB,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,mFAAmF;AACnF,eAAO,MAAM,eAAe,SAAS,CAAC;AAEtC,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAE/C,sEAAsE;AACtE,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAEvD,oDAAoD;AACpD,eAAO,MAAM,cAAc,QAAwC,CAAC;AAEpE,qEAAqE;AACrE,eAAO,MAAM,eAAe;;;iBAUkF,CAAC;AAC/G,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;iBAUuE,CAAC;AACvG,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa;;iBAEtB,OAAO;iBACP,MAAM;;;;iBACN,QAAQ;;;iBAGR,OAAO;iBACP,MAAM;;;iBACN,QAAQ,EAAE,WAAW;iBACrB,QAAQ;;CAEwB,CAAC;AAErC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,gBAKlC,CAAC"}
@@ -0,0 +1,72 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { z } from "zod";
4
+ import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
5
+ //#region src/purge/specs.ts
6
+ /** This capability's name, and the first segment of its workflow dispatch keys. */
7
+ const AUTH_CAPABILITY = "auth";
8
+ /** The binding the purge of one account is started on. */
9
+ const AUTH_PURGE_BINDING = "AUTH_PURGE";
10
+ /** The binding the daily pass that starts every due purge runs on. */
11
+ const AUTH_PURGE_DUE_BINDING = "AUTH_PURGE_DUE";
12
+ /** The dispatch key of the purge of one account. */
13
+ const AUTH_PURGE_KEY = workflowKey(AUTH_CAPABILITY, "purge");
14
+ /** One account's purge: which, and whether its last mail is sent. */
15
+ const AuthPurgeParams = z.object({
16
+ userId: z.string().min(1).max(255).describe("The account to erase, as `pithy_auth_users.id` stores it."),
17
+ notify: z.boolean().optional().describe("Whether the deletion-complete mail is sent. Absent is true; the config can still turn it off. A hard deletion with `notify: false` passes false.")
18
+ }).describe("One account's purge. It erases nothing unless the account is deleted and its window has closed.");
19
+ /**
20
+ * The daily pass's parameters. Every field optional, because a cron passes none — `createEntrypoint` starts a
21
+ * scheduled job with `{}`.
22
+ */
23
+ const AuthPurgeDueParams = z.object({ limit: z.number().int().min(1).max(1e3).optional().describe("How many due accounts to start a purge for in this pass, oldest first. Defaults to 500.") }).describe("One pass that starts a purge for every account past its window. A cron passes no field.");
24
+ /**
25
+ * The two durable jobs auth owns (#622) — **both hosted by the adopter's own Worker**, the one that composes
26
+ * auth, never a prebuilt host.
27
+ *
28
+ * **Why not a host.** A purge runs every composed capability's contribution, the adopter's own `app` among
29
+ * them, and those exist only in the Worker whose `pithy.config.ts` composed them. A prebuilt host composes
30
+ * nothing. So each class is five lines in the adopter's entry, calling `runAuthPurge` and `runAuthPurgeDue` in
31
+ * `./workflow.ts`, exactly as `@pithy-sh/payments`' usage pass is: Cloudflare resolves a `class_name` in the
32
+ * script that binds it, and the body finds the composition the way a Workflow that sends mail finds email.
33
+ * No `className` here, deliberately: the class is the adopter's, and so is its `workflows` entry. The docs
34
+ * give both (`docs/account-lifecycle.md`).
35
+ *
36
+ * **`purge-due` is daily at 02:00 UTC**, ahead of storage's and the secrets rotation at 03:00, payments' 04:00
37
+ * and testers' 05:00. Daily because the window is counted in days: an hourly pass would start the same purge
38
+ * twenty-four times and erase nothing sooner. Both stay dispatchable on demand — a hard deletion starts
39
+ * `purge` directly.
40
+ *
41
+ * `optional: true` for both, so a Worker composing auth still boots before the adopter has bound them. A
42
+ * deletion then reports its purge as `pending`, and nothing is erased until they are.
43
+ */
44
+ const authWorkflows = {
45
+ purge: {
46
+ binding: AUTH_PURGE_BINDING,
47
+ params: AuthPurgeParams,
48
+ optional: true
49
+ },
50
+ "purge-due": {
51
+ binding: AUTH_PURGE_DUE_BINDING,
52
+ params: AuthPurgeDueParams,
53
+ schedule: "0 2 * * *",
54
+ optional: true
55
+ }
56
+ };
57
+ /**
58
+ * The jobs as a dispatch registry, keyed `auth/<job>`, built here for the reason testers builds its own: the key
59
+ * format is core's either way. The daily pass starts each purge on the binding directly, not through this, because
60
+ * it names the instance (`./start.ts`) and dispatch does not.
61
+ */
62
+ const authWorkflowRegistry = Object.fromEntries(Object.entries(authWorkflows).map(([job, spec]) => {
63
+ const key = workflowKey(AUTH_CAPABILITY, job);
64
+ return [key, {
65
+ key,
66
+ capability: AUTH_CAPABILITY,
67
+ job,
68
+ spec
69
+ }];
70
+ }));
71
+ //#endregion
72
+ export { AUTH_CAPABILITY, AUTH_PURGE_BINDING, AUTH_PURGE_DUE_BINDING, AUTH_PURGE_KEY, AuthPurgeDueParams, AuthPurgeParams, authWorkflowRegistry, authWorkflows };
@@ -0,0 +1,42 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import type { WorkflowBinding } from "@pithy-sh/core/src/workflow/spec";
4
+ /**
5
+ * Starting one account's purge, from either door (#622) — a hard deletion's route and the daily pass.
6
+ *
7
+ * **Under an id the deletion names, so two starts of one purge are one instance.** A hard deletion repeated, a
8
+ * hard deletion the daily pass also finds due, a `start` step the pass retries: each asks for the same
9
+ * instance, and Cloudflare holds one instance per id, so the second `create` is refused and nothing runs
10
+ * twice. Two purges of one account running at once would both pass `due` and both reach the mail.
11
+ *
12
+ * **The id is the account, the deletion's start, and the UTC day of the start.** The account and the deletion,
13
+ * so a restored and re-deleted account is a different purge. The day, because the daily pass is the outer
14
+ * retry (`./retryPolicy.ts`): an instance that failed keeps its id, and a purge started under the same id
15
+ * forever could never be started again. So tomorrow's pass gets a fresh instance for an account still due,
16
+ * and every start within one day is the same one. Two instances of one purge can overlap only across a day
17
+ * boundary, while the first is still retrying; `complete` then records, audits and fires once whatever
18
+ * overlaps (`../lifecycle/transitions.ts`).
19
+ *
20
+ * **Hashed.** An instance id is at most 100 characters of `[A-Za-z0-9_-]`, and a user id is up to 255 of
21
+ * anything. A SHA-256 of the pair keeps the id inside the rule and says nothing about the account.
22
+ */
23
+ /** What starting a purge needs to know. */
24
+ export interface PurgeStart {
25
+ /** The account. */
26
+ readonly userId: string;
27
+ /** The deletion it is purged under — its start, ms-epoch. */
28
+ readonly deletedAt: number;
29
+ /** A hard deletion's `notify`, when it named one. The deletion's row carries it too. */
30
+ readonly notify?: boolean;
31
+ /** Now, for the day the id is named for. */
32
+ readonly at: Date;
33
+ }
34
+ /** The instance id of one purge, on one day. Deterministic: the same start always names the same instance. */
35
+ export declare function purgeInstanceId(start: Pick<PurgeStart, "userId" | "deletedAt" | "at">): Promise<string>;
36
+ /**
37
+ * Start one purge, or find it started. A `create` refused because the id is taken is a purge already started,
38
+ * so this asks the binding for the instance and succeeds when it is there. Any other failure is thrown, for the
39
+ * caller to report as `pending`. The parameters are the job's own schema, parsed.
40
+ */
41
+ export declare function startPurgeInstance(binding: WorkflowBinding, start: PurgeStart): Promise<void>;
42
+ //# sourceMappingURL=start.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../../src/purge/start.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAGxE;;;;;;;;;;;;;;;;;;GAkBG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,mBAAmB;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;CACnB;AAED,8GAA8G;AAC9G,wBAAsB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,GAAG,WAAW,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAK7G;AAWD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBnG"}
@@ -0,0 +1,37 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { AuthPurgeParams } from "./specs.js";
4
+ //#region src/purge/start.ts
5
+ /** The instance id of one purge, on one day. Deterministic: the same start always names the same instance. */
6
+ async function purgeInstanceId(start) {
7
+ const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`${start.userId}\n${start.deletedAt}`));
8
+ return `auth-purge-${Array.from(new Uint8Array(digest).slice(0, 20), (byte) => byte.toString(16).padStart(2, "0")).join("")}-${start.at.toISOString().slice(0, 10).replaceAll("-", "")}`;
9
+ }
10
+ function canLookUp(binding) {
11
+ return typeof binding.get === "function";
12
+ }
13
+ /**
14
+ * Start one purge, or find it started. A `create` refused because the id is taken is a purge already started,
15
+ * so this asks the binding for the instance and succeeds when it is there. Any other failure is thrown, for the
16
+ * caller to report as `pending`. The parameters are the job's own schema, parsed.
17
+ */
18
+ async function startPurgeInstance(binding, start) {
19
+ const id = await purgeInstanceId(start);
20
+ const params = AuthPurgeParams.parse({
21
+ userId: start.userId,
22
+ ...start.notify === void 0 ? {} : { notify: start.notify }
23
+ });
24
+ try {
25
+ await binding.create({
26
+ id,
27
+ params
28
+ });
29
+ } catch (error) {
30
+ if (canLookUp(binding)) {
31
+ if (await binding.get(id).then(() => true, () => false)) return;
32
+ }
33
+ throw error;
34
+ }
35
+ }
36
+ //#endregion
37
+ export { purgeInstanceId, startPurgeInstance };