@pithy-sh/auth 0.16.0 → 0.17.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 (59) hide show
  1. package/dist/capability.d.ts +9 -6
  2. package/dist/capability.d.ts.map +1 -1
  3. package/dist/capability.js +4 -2
  4. package/dist/data/tables.d.ts +1 -0
  5. package/dist/data/tables.d.ts.map +1 -1
  6. package/dist/data/userLifecycle.d.ts +1 -0
  7. package/dist/data/userLifecycle.d.ts.map +1 -1
  8. package/dist/data/userLifecycle.js +3 -2
  9. package/dist/hooks/runtime.d.ts +32 -0
  10. package/dist/hooks/runtime.d.ts.map +1 -0
  11. package/dist/hooks/runtime.js +25 -0
  12. package/dist/http/adminRoutes.d.ts.map +1 -1
  13. package/dist/http/adminRoutes.js +4 -2
  14. package/dist/http/resolve.d.ts.map +1 -1
  15. package/dist/http/resolve.js +2 -1
  16. package/dist/http/responses.d.ts +3 -0
  17. package/dist/http/responses.d.ts.map +1 -1
  18. package/dist/http/responses.js +2 -1
  19. package/dist/lifecycle/erasure.d.ts.map +1 -1
  20. package/dist/lifecycle/erasure.js +2 -1
  21. package/dist/lifecycle/hooks.d.ts +18 -10
  22. package/dist/lifecycle/hooks.d.ts.map +1 -1
  23. package/dist/lifecycle/request.d.ts +2 -1
  24. package/dist/lifecycle/request.d.ts.map +1 -1
  25. package/dist/lifecycle/request.js +4 -1
  26. package/dist/lifecycle/transitions.d.ts +24 -16
  27. package/dist/lifecycle/transitions.d.ts.map +1 -1
  28. package/dist/lifecycle/transitions.js +27 -16
  29. package/dist/migrations/0011_retained_basis_key.d.ts +10 -0
  30. package/dist/migrations/0011_retained_basis_key.d.ts.map +1 -0
  31. package/dist/migrations/0011_retained_basis_key.js +18 -0
  32. package/dist/migrations/set.d.ts +1 -0
  33. package/dist/migrations/set.d.ts.map +1 -1
  34. package/dist/migrations/set.js +3 -1
  35. package/dist/purge/run.d.ts +11 -11
  36. package/dist/purge/run.d.ts.map +1 -1
  37. package/dist/purge/run.js +9 -8
  38. package/dist/purge/workflow.d.ts +7 -1
  39. package/dist/purge/workflow.d.ts.map +1 -1
  40. package/dist/purge/workflow.js +6 -2
  41. package/dist/version.generated.d.ts +1 -1
  42. package/dist/version.generated.js +1 -1
  43. package/docs/account-lifecycle.md +46 -10
  44. package/package.json +5 -5
  45. package/src/capability.ts +21 -8
  46. package/src/data/userLifecycle.ts +9 -2
  47. package/src/hooks/runtime.ts +41 -0
  48. package/src/http/adminRoutes.ts +14 -7
  49. package/src/http/resolve.ts +8 -4
  50. package/src/http/responses.ts +7 -1
  51. package/src/lifecycle/erasure.ts +2 -1
  52. package/src/lifecycle/hooks.ts +22 -10
  53. package/src/lifecycle/request.ts +4 -1
  54. package/src/lifecycle/transitions.ts +47 -28
  55. package/src/migrations/0011_retained_basis_key.ts +19 -0
  56. package/src/migrations/set.ts +2 -0
  57. package/src/purge/run.ts +29 -17
  58. package/src/purge/workflow.ts +7 -3
  59. package/src/version.generated.ts +1 -1
package/src/purge/run.ts CHANGED
@@ -1,7 +1,12 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
- import { isRetained, type PurgeContext, type PurgeStep } from "@pithy-sh/core/src/capability/purge";
4
+ import {
5
+ isRetained,
6
+ type PurgeContext,
7
+ type PurgeStep,
8
+ type RetainingPurgeContribution,
9
+ } from "@pithy-sh/core/src/capability/purge";
5
10
  import type { LegalHolds } from "@pithy-sh/core/src/retention/holds";
6
11
  import {
7
12
  classifiedSteps,
@@ -23,7 +28,7 @@ import { authWorkflowRetry } from "./retryPolicy";
23
28
  import { AUTH_CAPABILITY, type AuthPurgeDueParams, type AuthPurgeParams } from "./specs";
24
29
 
25
30
  /**
26
- * The purge, as steps (#622) — the bodies `./workflow.ts` hands a Workflow's step runner to.
31
+ * The purge, as steps — the bodies `./workflow.ts` hands a Workflow's step runner to.
27
32
  *
28
33
  * ## One step per contribution, and the order they run in
29
34
  *
@@ -31,7 +36,7 @@ import { AUTH_CAPABILITY, type AuthPurgeDueParams, type AuthPurgeParams } from "
31
36
  * and one already erased all end the run here, having erased nothing. This is the one check a cron-started
32
37
  * purge and a hard deletion's both pass through, so re-running a purge for the same subject exits cleanly.
33
38
  * 2. **`erase <capability>`** — one step per composed contribution, in composition order, each recording that it
34
- * ran in `pithy_auth_user_lifecycle`. A contribution that **retains** its rows (#814) is a `retain <capability>`
39
+ * ran in `pithy_auth_user_lifecycle`. A contribution that **retains** its rows is a `retain <capability>`
35
40
  * 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
36
41
  * contract and runs code the kit did not write, so any fault in it is worth another attempt (`./retryPolicy.ts`).
37
42
  * A failing contribution retries alone, and the ones that finished are served from the journal.
@@ -41,7 +46,7 @@ import { AUTH_CAPABILITY, type AuthPurgeDueParams, type AuthPurgeParams } from "
41
46
  * 4. **`erase auth`** — auth's own contribution, last for that reason.
42
47
  * 5. **`complete`** — the `purged` record, the audit event, `onUserPurged`. Once.
43
48
  *
44
- * Every step from 2 on records an audit event as well as its row (#823), which the erasure attestation cites.
49
+ * Every step from 2 on records an audit event as well as its row, which the erasure attestation cites.
45
50
  *
46
51
  * ## A legal hold stops it
47
52
  *
@@ -52,7 +57,7 @@ import { AUTH_CAPABILITY, type AuthPurgeDueParams, type AuthPurgeParams } from "
52
57
  * erase where the first one did and carry on from there. A hold that cannot be read fails its step, which retries:
53
58
  * a purge never erases past a hold it could not see.
54
59
  *
55
- * ## A purge that gives up says where (#823)
60
+ * ## A purge that gives up says where
56
61
  *
57
62
  * A step that exhausts its retries fails the instance, and the daily pass starts a fresh one tomorrow. Until then the
58
63
  * record would read as a purge still running. So the failure is caught once, recorded in its own `fail` step —
@@ -66,10 +71,10 @@ export interface PurgeOps {
66
71
  due(userId: string): Promise<"due" | "not_due" | "gone">;
67
72
  /** Record that one capability's step erased its rows. */
68
73
  recordStep(userId: string, step: string, summary: string): Promise<void>;
69
- /** Record that one capability's step kept its rows, and why (#814). */
70
- recordRetained(userId: string, step: string, basis: string): Promise<void>;
74
+ /** Record that one capability's step kept its rows, and why: its basis, and the catalog key that translates it. */
75
+ recordRetained(userId: string, step: string, retain: RetainingPurgeContribution["retain"]): Promise<void>;
71
76
  /**
72
- * The account's address, read now, or `null` once it is gone (#814). Handed to each step as
77
+ * The account's address, read now, or `null` once it is gone. Handed to each step as
73
78
  * `PurgeContext.address`, so a capability holding rows by address reads it inside its own step.
74
79
  */
75
80
  address(userId: string): Promise<string | null>;
@@ -80,7 +85,7 @@ export interface PurgeOps {
80
85
  mailComplete(userId: string, notify: boolean | undefined): Promise<boolean>;
81
86
  /** Write the `purged` record, the audit event and the hook. Says whether this call wrote them. */
82
87
  complete(userId: string): Promise<boolean>;
83
- /** Record that the purge gave up at `step`, in the history and the trail (#823). */
88
+ /** Record that the purge gave up at `step`, in the history and the trail. */
84
89
  fail(userId: string, step: string): Promise<void>;
85
90
  /** Whether a legal hold stands on the account. Throws when it cannot say. */
86
91
  held(userId: string): Promise<boolean>;
@@ -91,13 +96,20 @@ export function purgeOps(deps: LifecycleDeps, holds: LegalHolds): PurgeOps {
91
96
  return {
92
97
  due: async (userId) => (await purgeSubject(deps, userId)).state,
93
98
  recordStep: (userId, step, summary) => recordPurgeStep(deps, { userId, step, summary }),
94
- recordRetained: (userId, step, basis) => recordPurgeStep(deps, { userId, step, summary: basis, retained: true }),
99
+ recordRetained: (userId, step, retain) =>
100
+ recordPurgeStep(deps, {
101
+ userId,
102
+ step,
103
+ summary: retain.basis,
104
+ retained: true,
105
+ ...(retain.basisKey === undefined ? {} : { basisKey: retain.basisKey }),
106
+ }),
95
107
  address: (userId) => purgeAddress(deps.db, userId),
96
108
  mailComplete: async (userId, notify) => {
97
109
  const subject = await purgeSubject(deps, userId);
98
110
  if (subject.state !== "due") return false;
99
111
  // Either can silence it: the parameter a hard deletion started this purge with, or the choice that deletion
100
- // wrote on its history row — the one a purge the daily pass started still has (#622).
112
+ // wrote on its history row — the one a purge the daily pass started still has.
101
113
  const silenced = notify === false || subject.notify === false;
102
114
  return (await mailPurgeComplete(deps, { recipient: subject.recipient, ...(silenced ? { notify: false } : {}) }))
103
115
  .mailed;
@@ -119,7 +131,7 @@ export interface PurgeOutcome {
119
131
  readonly state: "purged" | "not_due" | "gone" | "held";
120
132
  /** Every step that erased its rows, in the order it ran. Empty when nothing was erased. */
121
133
  readonly erased: readonly string[];
122
- /** Every step that kept its rows under a stated basis (#814), in the order it ran. */
134
+ /** Every step that kept its rows under a stated basis, in the order it ran. */
123
135
  readonly retained: readonly string[];
124
136
  /** Whether the deletion-complete mail was enqueued. */
125
137
  readonly mailed: boolean;
@@ -165,7 +177,7 @@ export async function purgeUser(
165
177
  const { contribution } = each;
166
178
  current = each.step;
167
179
  if (isRetained(contribution))
168
- retained.push(await retainStep(step, run.ops, each.step, contribution.retain.basis, userId));
180
+ retained.push(await retainStep(step, run.ops, each.step, contribution.retain, userId));
169
181
  else erased.push(await eraseStep(step, run.ops, each, context));
170
182
  };
171
183
  try {
@@ -218,18 +230,18 @@ function eraseStep(step: WorkflowStepLike, ops: PurgeOps, each: PurgeStep, conte
218
230
  }
219
231
 
220
232
  /**
221
- * One capability's retained step (#814): nothing is erased, and the record says the rows were kept and why. Its own
233
+ * One capability's retained step: nothing is erased, and the record says the rows were kept and why. Its own
222
234
  * step, so the trail names it in the order it would have run, and a replay serves it from the journal.
223
235
  */
224
236
  function retainStep(
225
237
  step: WorkflowStepLike,
226
238
  ops: PurgeOps,
227
239
  name: string,
228
- basis: string,
240
+ retain: RetainingPurgeContribution["retain"],
229
241
  userId: string,
230
242
  ): Promise<string> {
231
243
  return step.do(`retain ${name}`, async () => {
232
- await ops.recordRetained(userId, name, basis);
244
+ await ops.recordRetained(userId, name, retain);
233
245
  return name;
234
246
  });
235
247
  }
@@ -258,7 +270,7 @@ export interface PurgeDueRun {
258
270
  }
259
271
 
260
272
  /**
261
- * The daily pass (#622): list every account past its window, and start a purge for each — in pages, one step
273
+ * The daily pass: list every account past its window, and start a purge for each — in pages, one step
262
274
  * each, so a pass that dies part-way resumes after the page it finished rather than starting every purge
263
275
  * again. An account still inside its window is not listed, so it is not started.
264
276
  */
@@ -31,7 +31,7 @@ import { AUTH_PURGE_BINDING, AUTH_PURGE_KEY, AuthPurgeDueParams, AuthPurgeParams
31
31
  import { startPurgeInstance } from "./start";
32
32
 
33
33
  /**
34
- * The purge's two Workflow bodies (#622) — run by classes **the adopter's own Worker** exports, beside the
34
+ * The purge's two Workflow bodies — run by classes **the adopter's own Worker** exports, beside the
35
35
  * `createEntrypoint` it already exports, because a purge runs every composed capability's contribution and
36
36
  * those exist nowhere else:
37
37
  *
@@ -67,8 +67,11 @@ interface PurgeEvent {
67
67
  readonly instanceId?: string;
68
68
  }
69
69
 
70
- /** The lifecycle transitions' dependencies, for a run with no request: this env, and the composition's seams. */
71
- function lifecycleFor(auth: AuthCapability, env: Record<string, unknown>, log: Logger): LifecycleDeps {
70
+ /**
71
+ * The lifecycle transitions' dependencies, for a run with no request: this env, and the composition's seams. The
72
+ * hooks run in this env with no `waitUntil`, since a Workflow has no `ExecutionContext`.
73
+ */
74
+ export function lifecycleFor(auth: AuthCapability, env: Record<string, unknown>, log: Logger): LifecycleDeps {
72
75
  const d1 = resolveDb(env, auth.authConfig.database);
73
76
  return {
74
77
  db: authDatabase(d1),
@@ -76,6 +79,7 @@ function lifecycleFor(auth: AuthCapability, env: Record<string, unknown>, log: L
76
79
  emit: auth.auditFor(env),
77
80
  config: auth.authConfig,
78
81
  hooks: auth.lifecycleHooks,
82
+ runtime: { env },
79
83
  enqueueEmail: (input) => enqueueFromEnv(env as unknown as EmailEnqueueEnv, input),
80
84
  log,
81
85
  };
@@ -13,4 +13,4 @@
13
13
  export const PACKAGE_NAME = "@pithy-sh/auth";
14
14
 
15
15
  /** This package's version, stamped from its own package.json at generation time. */
16
- export const PACKAGE_VERSION = "0.16.0";
16
+ export const PACKAGE_VERSION = "0.17.0";