@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.
- package/dist/capability.d.ts +9 -6
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +4 -2
- package/dist/data/tables.d.ts +1 -0
- package/dist/data/tables.d.ts.map +1 -1
- package/dist/data/userLifecycle.d.ts +1 -0
- package/dist/data/userLifecycle.d.ts.map +1 -1
- package/dist/data/userLifecycle.js +3 -2
- package/dist/hooks/runtime.d.ts +32 -0
- package/dist/hooks/runtime.d.ts.map +1 -0
- package/dist/hooks/runtime.js +25 -0
- package/dist/http/adminRoutes.d.ts.map +1 -1
- package/dist/http/adminRoutes.js +4 -2
- package/dist/http/resolve.d.ts.map +1 -1
- package/dist/http/resolve.js +2 -1
- package/dist/http/responses.d.ts +3 -0
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +2 -1
- package/dist/lifecycle/erasure.d.ts.map +1 -1
- package/dist/lifecycle/erasure.js +2 -1
- package/dist/lifecycle/hooks.d.ts +18 -10
- package/dist/lifecycle/hooks.d.ts.map +1 -1
- package/dist/lifecycle/request.d.ts +2 -1
- package/dist/lifecycle/request.d.ts.map +1 -1
- package/dist/lifecycle/request.js +4 -1
- package/dist/lifecycle/transitions.d.ts +24 -16
- package/dist/lifecycle/transitions.d.ts.map +1 -1
- package/dist/lifecycle/transitions.js +27 -16
- package/dist/migrations/0011_retained_basis_key.d.ts +10 -0
- package/dist/migrations/0011_retained_basis_key.d.ts.map +1 -0
- package/dist/migrations/0011_retained_basis_key.js +18 -0
- package/dist/migrations/set.d.ts +1 -0
- package/dist/migrations/set.d.ts.map +1 -1
- package/dist/migrations/set.js +3 -1
- package/dist/purge/run.d.ts +11 -11
- package/dist/purge/run.d.ts.map +1 -1
- package/dist/purge/run.js +9 -8
- package/dist/purge/workflow.d.ts +7 -1
- package/dist/purge/workflow.d.ts.map +1 -1
- package/dist/purge/workflow.js +6 -2
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/docs/account-lifecycle.md +46 -10
- package/package.json +5 -5
- package/src/capability.ts +21 -8
- package/src/data/userLifecycle.ts +9 -2
- package/src/hooks/runtime.ts +41 -0
- package/src/http/adminRoutes.ts +14 -7
- package/src/http/resolve.ts +8 -4
- package/src/http/responses.ts +7 -1
- package/src/lifecycle/erasure.ts +2 -1
- package/src/lifecycle/hooks.ts +22 -10
- package/src/lifecycle/request.ts +4 -1
- package/src/lifecycle/transitions.ts +47 -28
- package/src/migrations/0011_retained_basis_key.ts +19 -0
- package/src/migrations/set.ts +2 -0
- package/src/purge/run.ts +29 -17
- package/src/purge/workflow.ts +7 -3
- 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 {
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
70
|
-
recordRetained(userId: string, step: string,
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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,
|
|
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
|
|
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
|
*/
|
package/src/purge/workflow.ts
CHANGED
|
@@ -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
|
|
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
|
-
/**
|
|
71
|
-
|
|
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
|
};
|
package/src/version.generated.ts
CHANGED