@pithy-sh/audit 0.5.0 → 0.7.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/README.md +93 -0
- package/dist/accessHistory.d.ts +315 -0
- package/dist/accessHistory.d.ts.map +1 -0
- package/dist/accessHistory.js +299 -0
- package/dist/actions.d.ts +15 -1
- package/dist/actions.d.ts.map +1 -1
- package/dist/actions.js +16 -2
- package/dist/capability.d.ts +14 -0
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +124 -12
- package/dist/chain/append.d.ts +43 -0
- package/dist/chain/append.d.ts.map +1 -0
- package/dist/chain/append.js +110 -0
- package/dist/chain/checkpoint.d.ts +70 -0
- package/dist/chain/checkpoint.d.ts.map +1 -0
- package/dist/chain/checkpoint.js +133 -0
- package/dist/chain/lockCheck.d.ts +15 -0
- package/dist/chain/lockCheck.d.ts.map +1 -0
- package/dist/chain/lockCheck.js +75 -0
- package/dist/chain/prune.d.ts +84 -0
- package/dist/chain/prune.d.ts.map +1 -0
- package/dist/chain/prune.js +231 -0
- package/dist/chain/rows.d.ts +74 -0
- package/dist/chain/rows.d.ts.map +1 -0
- package/dist/chain/rows.js +133 -0
- package/dist/chain/tombstone.d.ts +21 -0
- package/dist/chain/tombstone.d.ts.map +1 -0
- package/dist/chain/tombstone.js +98 -0
- package/dist/chain/verify.d.ts +63 -0
- package/dist/chain/verify.d.ts.map +1 -0
- package/dist/chain/verify.js +220 -0
- package/dist/citations.d.ts +17 -0
- package/dist/citations.d.ts.map +1 -0
- package/dist/citations.js +48 -0
- package/dist/cli/emitFromCLI.d.ts +5 -0
- package/dist/cli/emitFromCLI.d.ts.map +1 -1
- package/dist/cli/emitFromCLI.js +5 -0
- package/dist/data/auditEvent.d.ts +4 -0
- package/dist/data/auditEvent.d.ts.map +1 -1
- package/dist/data/auditEvent.js +7 -3
- package/dist/data/sinkState.d.ts +23 -0
- package/dist/data/sinkState.d.ts.map +1 -0
- package/dist/data/sinkState.js +25 -0
- package/dist/data/tables.d.ts +14 -1
- package/dist/data/tables.d.ts.map +1 -1
- package/dist/data/tables.js +5 -1
- package/dist/http/guards.d.ts +39 -6
- package/dist/http/guards.d.ts.map +1 -1
- package/dist/http/guards.js +101 -17
- package/dist/http/responses.d.ts +503 -0
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +157 -5
- package/dist/http/routes.d.ts +25 -3
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +321 -15
- package/dist/http/schemas.d.ts +67 -0
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +88 -4
- package/dist/http/views.d.ts +25 -1
- package/dist/http/views.d.ts.map +1 -1
- package/dist/http/views.js +107 -2
- package/dist/migrations/0003_call_index.d.ts +21 -0
- package/dist/migrations/0003_call_index.d.ts.map +1 -0
- package/dist/migrations/0003_call_index.js +33 -0
- package/dist/migrations/0004_request_index.d.ts +16 -0
- package/dist/migrations/0004_request_index.d.ts.map +1 -0
- package/dist/migrations/0004_request_index.js +24 -0
- package/dist/migrations/0005_chain.d.ts +24 -0
- package/dist/migrations/0005_chain.d.ts.map +1 -0
- package/dist/migrations/0005_chain.js +43 -0
- package/dist/migrations/0006_sinks.d.ts +11 -0
- package/dist/migrations/0006_sinks.d.ts.map +1 -0
- package/dist/migrations/0006_sinks.js +20 -0
- package/dist/provision/resolveAuditConfig.d.ts +31 -0
- package/dist/provision/resolveAuditConfig.d.ts.map +1 -0
- package/dist/provision/resolveAuditConfig.js +43 -0
- package/dist/purge/contribution.d.ts +21 -0
- package/dist/purge/contribution.d.ts.map +1 -0
- package/dist/purge/contribution.js +41 -0
- package/dist/reach.d.ts +250 -0
- package/dist/reach.d.ts.map +1 -0
- package/dist/reach.js +244 -0
- package/dist/recorder.d.ts +11 -0
- package/dist/recorder.d.ts.map +1 -1
- package/dist/recorder.js +23 -5
- package/dist/routePattern.d.ts +60 -0
- package/dist/routePattern.d.ts.map +1 -0
- package/dist/routePattern.js +130 -0
- package/dist/seeds/example.d.ts.map +1 -1
- package/dist/seeds/example.js +23 -6
- package/dist/ship/consumer.d.ts +45 -0
- package/dist/ship/consumer.d.ts.map +1 -0
- package/dist/ship/consumer.js +141 -0
- package/dist/ship/event.d.ts +59 -0
- package/dist/ship/event.d.ts.map +1 -0
- package/dist/ship/event.js +77 -0
- package/dist/ship/health.d.ts +33 -0
- package/dist/ship/health.d.ts.map +1 -0
- package/dist/ship/health.js +80 -0
- package/dist/ship/profiles.d.ts +34 -0
- package/dist/ship/profiles.d.ts.map +1 -0
- package/dist/ship/profiles.js +62 -0
- package/dist/ship/queue.d.ts +57 -0
- package/dist/ship/queue.d.ts.map +1 -0
- package/dist/ship/queue.js +70 -0
- package/dist/ship/secrets.d.ts +7 -0
- package/dist/ship/secrets.d.ts.map +1 -0
- package/dist/ship/secrets.js +40 -0
- package/dist/ship/shipper.d.ts +15 -0
- package/dist/ship/shipper.d.ts.map +1 -0
- package/dist/ship/shipper.js +27 -0
- package/dist/ship/sinks.d.ts +54 -0
- package/dist/ship/sinks.d.ts.map +1 -0
- package/dist/ship/sinks.js +45 -0
- package/dist/ship/state.d.ts +27 -0
- package/dist/ship/state.d.ts.map +1 -0
- package/dist/ship/state.js +29 -0
- package/dist/usage.d.ts +159 -0
- package/dist/usage.d.ts.map +1 -0
- package/dist/usage.js +87 -0
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/dist/workflows/prune.d.ts +73 -0
- package/dist/workflows/prune.d.ts.map +1 -0
- package/dist/workflows/prune.js +128 -0
- package/dist/workflows/retryPolicy.d.ts +10 -0
- package/dist/workflows/retryPolicy.d.ts.map +1 -0
- package/dist/workflows/retryPolicy.js +14 -0
- package/dist/workflows/specs.d.ts +70 -0
- package/dist/workflows/specs.d.ts.map +1 -0
- package/dist/workflows/specs.js +70 -0
- package/dist/workflows/worker.d.ts +32 -0
- package/dist/workflows/worker.d.ts.map +1 -0
- package/dist/workflows/worker.js +41 -0
- package/package.json +5 -2
- package/pithy.manifest.json +36 -4
- package/src/accessHistory.ts +360 -0
- package/src/actions.ts +15 -1
- package/src/capability.ts +154 -12
- package/src/chain/append.ts +161 -0
- package/src/chain/checkpoint.ts +172 -0
- package/src/chain/lockCheck.ts +72 -0
- package/src/chain/prune.ts +340 -0
- package/src/chain/rows.ts +211 -0
- package/src/chain/tombstone.ts +104 -0
- package/src/chain/verify.ts +366 -0
- package/src/citations.ts +62 -0
- package/src/cli/emitFromCLI.ts +5 -0
- package/src/cloudflare-test.d.ts +1 -0
- package/src/data/auditEvent.ts +31 -1
- package/src/data/sinkState.ts +41 -0
- package/src/data/tables.ts +7 -1
- package/src/http/guards.ts +90 -6
- package/src/http/responses.ts +318 -3
- package/src/http/routes.ts +379 -7
- package/src/http/schemas.ts +158 -2
- package/src/http/views.ts +123 -1
- package/src/migrations/0003_call_index.ts +35 -0
- package/src/migrations/0004_request_index.ts +26 -0
- package/src/migrations/0005_chain.ts +56 -0
- package/src/migrations/0006_sinks.ts +28 -0
- package/src/provision/resolveAuditConfig.ts +60 -0
- package/src/purge/contribution.ts +39 -0
- package/src/reach.ts +454 -0
- package/src/recorder.ts +64 -42
- package/src/routePattern.ts +141 -0
- package/src/seeds/example.ts +13 -0
- package/src/ship/consumer.ts +169 -0
- package/src/ship/event.ts +86 -0
- package/src/ship/health.ts +92 -0
- package/src/ship/profiles.ts +99 -0
- package/src/ship/queue.ts +108 -0
- package/src/ship/secrets.ts +42 -0
- package/src/ship/shipper.ts +32 -0
- package/src/ship/sinks.ts +82 -0
- package/src/ship/state.ts +61 -0
- package/src/usage.ts +176 -0
- package/src/version.generated.ts +1 -1
- package/src/workflows/prune.ts +196 -0
- package/src/workflows/retryPolicy.ts +14 -0
- package/src/workflows/specs.ts +92 -0
- package/src/workflows/worker.ts +65 -0
- package/src/workflows/wrangler.jsonc +40 -0
|
@@ -0,0 +1,299 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
import { AuditActorType } from "@pithy-sh/core/src/audit/auditEvent";
|
|
4
|
+
import { ControlPlaneAuditActions } from "@pithy-sh/core/src/controlPlane/audit/actions";
|
|
5
|
+
import { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
|
|
6
|
+
import { SQLiteBoolean, SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
|
|
7
|
+
import { decodeCursor, pageLimit, toPage } from "@pithy-sh/core/src/data/cursor";
|
|
8
|
+
import { sql } from "kysely";
|
|
9
|
+
import { z } from "zod";
|
|
10
|
+
//#region src/accessHistory.ts
|
|
11
|
+
/**
|
|
12
|
+
* Who could do what, over time — `#831`.
|
|
13
|
+
*
|
|
14
|
+
* Every change to who can reach an environment's data is already in the trail: a membership joining, changing role,
|
|
15
|
+
* leaving or being removed, and a control-plane connection being registered, updated or removed, or a key on it
|
|
16
|
+
* registered, expired or revoked. What each changed — the role before and after, the scopes before and after — is in
|
|
17
|
+
* the row's `metadata`, which only the forensic one-event read returns, beside the IP and the user-agent. This reads
|
|
18
|
+
* the same rows in SQL and answers the changes.
|
|
19
|
+
*
|
|
20
|
+
* **One statement per page, never a walk.** The events are filtered, their known metadata keys lifted out, and each
|
|
21
|
+
* classified and given its before and after, all in D1. The handler pages the *answer*, oldest first; it never pages
|
|
22
|
+
* events to compute it.
|
|
23
|
+
*
|
|
24
|
+
* **Nothing personal, and nothing else, leaves this function.** It reads {@link ACCESS_HISTORY_METADATA_KEYS} out of
|
|
25
|
+
* `metadata` and no other key, and never the IP or the user-agent columns. The principal is the one personal field,
|
|
26
|
+
* and it is what the question is: who sanctioned a connection is half of who could reach the data through it.
|
|
27
|
+
*
|
|
28
|
+
* **A change recorded before its emitter carried the detail reads as `not_recorded`**, never as a guess. A role
|
|
29
|
+
* change from before `previousRole` was written has no before, and an update that moved no scope, from before the
|
|
30
|
+
* grant was written on every update, has neither — so their values are null and `recorded` says why.
|
|
31
|
+
*/
|
|
32
|
+
/**
|
|
33
|
+
* The code an accepted invitation writes. It carries `joined: false` when the person was already a member: acceptance
|
|
34
|
+
* then changed nothing, and its `role` is the role the invitation offered, not the one the membership holds.
|
|
35
|
+
*/
|
|
36
|
+
const INVITATION_ACCEPTED_ACTION = "organization/member_joined";
|
|
37
|
+
/**
|
|
38
|
+
* The membership codes `@pithy-sh/organization` writes, as literals.
|
|
39
|
+
*
|
|
40
|
+
* Literals rather than an import: audit depends on core alone, and a capability never reaches into another's
|
|
41
|
+
* internals (principle 4). A code is stable forever once a row holds one, and `packages/cli/src/audit/accessHistoryCodes.test.ts`
|
|
42
|
+
* holds every literal here to the register that declares it, so a rename there fails the build here.
|
|
43
|
+
*/
|
|
44
|
+
const MEMBER_ACCESS_ACTIONS = {
|
|
45
|
+
/** A membership was created with nothing before it — save {@link INVITATION_ACCEPTED_ACTION} with `joined: false`. */
|
|
46
|
+
joins: [
|
|
47
|
+
"organization/created",
|
|
48
|
+
INVITATION_ACCEPTED_ACTION,
|
|
49
|
+
"organization/admin_member_added"
|
|
50
|
+
],
|
|
51
|
+
/** A membership's role changed, recorded with `previousRole` from #831 on. */
|
|
52
|
+
changes: ["organization/member_role_changed", "organization/admin_member_role_changed"],
|
|
53
|
+
/** Ownership reached a membership: its role became the conferred one. */
|
|
54
|
+
ownership: ["organization/ownership_accepted", "organization/admin_ownership_forced"],
|
|
55
|
+
/** A membership ended, recorded with the role it held. */
|
|
56
|
+
ends: [
|
|
57
|
+
"organization/member_removed",
|
|
58
|
+
"organization/member_left",
|
|
59
|
+
"organization/admin_member_removed"
|
|
60
|
+
]
|
|
61
|
+
};
|
|
62
|
+
/** The member codes whose actor is the member, so an older row without `subjectUserId` still names them. */
|
|
63
|
+
const SELF_ACTIONS = [
|
|
64
|
+
"organization/created",
|
|
65
|
+
"organization/member_joined",
|
|
66
|
+
"organization/member_left",
|
|
67
|
+
"organization/ownership_accepted"
|
|
68
|
+
];
|
|
69
|
+
/** The connection-lifecycle codes, written by the CLI's `connectionRegistry`. */
|
|
70
|
+
const CONNECTION_ACTIONS = [
|
|
71
|
+
ControlPlaneAuditActions.connectionRegistered,
|
|
72
|
+
ControlPlaneAuditActions.connectionUpdated,
|
|
73
|
+
ControlPlaneAuditActions.connectionRemoved
|
|
74
|
+
];
|
|
75
|
+
/** The key codes the seam's own routes write. */
|
|
76
|
+
const KEY_ACTIONS = [ControlPlaneAuditActions.keyRegistered, ControlPlaneAuditActions.keyExpired];
|
|
77
|
+
/** Every code an access change is read from. */
|
|
78
|
+
const ACCESS_ACTIONS = [
|
|
79
|
+
...MEMBER_ACCESS_ACTIONS.joins,
|
|
80
|
+
...MEMBER_ACCESS_ACTIONS.changes,
|
|
81
|
+
...MEMBER_ACCESS_ACTIONS.ownership,
|
|
82
|
+
...MEMBER_ACCESS_ACTIONS.ends,
|
|
83
|
+
...CONNECTION_ACTIONS,
|
|
84
|
+
...KEY_ACTIONS
|
|
85
|
+
];
|
|
86
|
+
/**
|
|
87
|
+
* Every `metadata` key this read lifts, and the only ones. `accessHistory.workers.test.ts` holds the compiled
|
|
88
|
+
* statement to this list, so a key added to the SQL and not here fails.
|
|
89
|
+
*/
|
|
90
|
+
const ACCESS_HISTORY_METADATA_KEYS = [
|
|
91
|
+
"role",
|
|
92
|
+
"previousRole",
|
|
93
|
+
"confers",
|
|
94
|
+
"subjectUserId",
|
|
95
|
+
"membershipId",
|
|
96
|
+
"scopes",
|
|
97
|
+
"scopesBefore",
|
|
98
|
+
"scopesAfter",
|
|
99
|
+
"actorKind",
|
|
100
|
+
"purpose",
|
|
101
|
+
"authorizedBy",
|
|
102
|
+
"registeredKeyId",
|
|
103
|
+
"expiredKeyId",
|
|
104
|
+
"revokedKeyId",
|
|
105
|
+
"joined",
|
|
106
|
+
"replacedConnectionId"
|
|
107
|
+
];
|
|
108
|
+
/** A list of scopes, as `json_extract` hands an array back: JSON text, decoded through the codec. */
|
|
109
|
+
const ScopeList = sqliteJson(z.array(z.string()).describe("A connection's granted scopes."));
|
|
110
|
+
/**
|
|
111
|
+
* One access change, decoded from the statement's row. Flat, because SQL is: `subject` says which fields mean
|
|
112
|
+
* something, and `http/views.ts` projects it into the wire union `AccessChangeView`.
|
|
113
|
+
*/
|
|
114
|
+
const AccessHistoryRow = z.object({
|
|
115
|
+
id: z.number().int().describe("The event's surrogate id. The keyset tiebreak; never on the wire."),
|
|
116
|
+
eventId: z.string().describe("The event's public UUID."),
|
|
117
|
+
occurredAt: SQLiteDate.describe("When the change happened."),
|
|
118
|
+
action: z.string().describe("The `domain/reason` code the change was read from."),
|
|
119
|
+
actorType: AuditActorType.describe("The kind of principal that made the change."),
|
|
120
|
+
actorId: z.string().nullable().describe("The principal that made the change, or null."),
|
|
121
|
+
actorKind: ControlPlaneActorKind.nullable().describe("For a `control-plane` actor, which kind of client, or null."),
|
|
122
|
+
subject: z.enum([
|
|
123
|
+
"member",
|
|
124
|
+
"connection",
|
|
125
|
+
"key"
|
|
126
|
+
]).describe("What changed: a membership, a connection, or a key."),
|
|
127
|
+
recorded: SQLiteBoolean.describe("Whether the event carried its before and after. False reads as not recorded."),
|
|
128
|
+
organizationId: z.string().nullable().describe("A member change's organization — the event's tenant."),
|
|
129
|
+
membershipId: z.string().nullable().describe("A member change's membership."),
|
|
130
|
+
userId: z.string().nullable().describe("A member change's member."),
|
|
131
|
+
roleBefore: z.string().nullable().describe("A member change's role before, or null for none or not recorded."),
|
|
132
|
+
roleAfter: z.string().nullable().describe("A member change's role after, or null for none or not recorded."),
|
|
133
|
+
connectionId: z.string().nullable().describe("A connection or key change's connection."),
|
|
134
|
+
connectionKind: ControlPlaneActorKind.nullable().describe("The connection's kind of client, or null."),
|
|
135
|
+
purpose: z.string().nullable().describe("The connection's purpose, or null."),
|
|
136
|
+
principal: z.string().nullable().describe("Who sanctioned the connection, or null."),
|
|
137
|
+
scopesBefore: ScopeList.nullable().describe("The connection's scopes before, or null for none or not recorded."),
|
|
138
|
+
scopesAfter: ScopeList.nullable().describe("The connection's scopes after, or null for none or not recorded."),
|
|
139
|
+
replacedConnectionId: z.string().nullable().describe("For a registration that started over, the connection it replaced, whose grant ended with it."),
|
|
140
|
+
keyId: z.string().nullable().describe("A key change's key id."),
|
|
141
|
+
keyChange: z.enum([
|
|
142
|
+
"registered",
|
|
143
|
+
"expired",
|
|
144
|
+
"revoked"
|
|
145
|
+
]).nullable().describe("What happened to the key.")
|
|
146
|
+
}).describe("One access change, as the access-history statement answers it.");
|
|
147
|
+
/** `json_extract(metadata, '<path>')`, the path a literal of ours and never a caller's. */
|
|
148
|
+
function meta(path) {
|
|
149
|
+
return sql`json_extract(${sql.ref("metadata")}, ${sql.lit(path)})`;
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* A key an update may write as the value it holds now, or as `{ from, to }` when the update moved it: the `to`, or
|
|
153
|
+
* the plain value. `json_type` is null for an absent key, which reads as the plain value — also null.
|
|
154
|
+
*/
|
|
155
|
+
function currentValue(key) {
|
|
156
|
+
return sql`case json_type(${sql.ref("metadata")}, ${sql.lit(`$.${key}`)})
|
|
157
|
+
when 'object' then ${meta(`$.${key}.to`)} else ${meta(`$.${key}`)} end`;
|
|
158
|
+
}
|
|
159
|
+
/** `<column> in (<codes>)`, the codes bound as parameters. */
|
|
160
|
+
function oneOf(column, codes) {
|
|
161
|
+
return sql`${sql.ref(column)} in (${sql.join(codes)})`;
|
|
162
|
+
}
|
|
163
|
+
/** A decoded cursor, narrowed to the `(occurredAt, id)` pair this ordering can use. Anything else is a first page. */
|
|
164
|
+
function keysetPosition(cursor) {
|
|
165
|
+
if (!cursor) return void 0;
|
|
166
|
+
if (typeof cursor.sort !== "number" || typeof cursor.id !== "number") return void 0;
|
|
167
|
+
return {
|
|
168
|
+
sort: cursor.sort,
|
|
169
|
+
id: cursor.id
|
|
170
|
+
};
|
|
171
|
+
}
|
|
172
|
+
/**
|
|
173
|
+
* The page, as one Kysely statement — exported so a test can read what it compiles to.
|
|
174
|
+
*
|
|
175
|
+
* Three steps, in one statement:
|
|
176
|
+
*
|
|
177
|
+
* 1. **`extracted`** — the window's successful access events, after the cursor, with each named metadata key lifted
|
|
178
|
+
* out. `scopes` is an array on a registration and a removal and `{ from, to }` on an update that moved it, so the
|
|
179
|
+
* two are read apart. Kind, purpose and principal are the update's `to` where it moved them. An invitation redeemed
|
|
180
|
+
* by someone already a member (`joined` false) is left out here: it changed nothing.
|
|
181
|
+
* 2. **`classified`** — what changed. A member code is a member change; a key code is a key change, and so is a CLI
|
|
182
|
+
* update that registered or revoked a key, because that is what it did; the rest of the connection codes are
|
|
183
|
+
* connection changes.
|
|
184
|
+
* 3. **The answer** — each change's before and after by its code, and whether the event recorded them.
|
|
185
|
+
*/
|
|
186
|
+
function accessHistoryStatement(db, filter, page) {
|
|
187
|
+
const { joins, changes, ownership, ends } = MEMBER_ACCESS_ACTIONS;
|
|
188
|
+
const memberActions = [
|
|
189
|
+
...joins,
|
|
190
|
+
...changes,
|
|
191
|
+
...ownership,
|
|
192
|
+
...ends
|
|
193
|
+
];
|
|
194
|
+
const position = page.position;
|
|
195
|
+
return db.with("extracted", (q) => q.selectFrom("pithyAuditEvents").select([
|
|
196
|
+
"id",
|
|
197
|
+
"eventId",
|
|
198
|
+
"occurredAt",
|
|
199
|
+
"action",
|
|
200
|
+
"actorType",
|
|
201
|
+
"actorId",
|
|
202
|
+
"actorKind",
|
|
203
|
+
"tenant",
|
|
204
|
+
"resourceId",
|
|
205
|
+
meta("$.role").as("role"),
|
|
206
|
+
meta("$.previousRole").as("previousRole"),
|
|
207
|
+
meta("$.confers").as("confers"),
|
|
208
|
+
meta("$.subjectUserId").as("subjectUserId"),
|
|
209
|
+
meta("$.membershipId").as("recordedMembershipId"),
|
|
210
|
+
sql`case json_type(${sql.ref("metadata")}, '$.scopes') when 'array' then ${meta("$.scopes")} end`.as("scopes"),
|
|
211
|
+
meta("$.scopes.from").as("scopesFrom"),
|
|
212
|
+
meta("$.scopes.to").as("scopesTo"),
|
|
213
|
+
meta("$.scopesBefore").as("scopesBeforeKey"),
|
|
214
|
+
meta("$.scopesAfter").as("scopesAfterKey"),
|
|
215
|
+
currentValue("actorKind").as("connectionKind"),
|
|
216
|
+
currentValue("purpose").as("purpose"),
|
|
217
|
+
currentValue("authorizedBy").as("principal"),
|
|
218
|
+
meta("$.registeredKeyId").as("registeredKeyId"),
|
|
219
|
+
meta("$.expiredKeyId").as("expiredKeyId"),
|
|
220
|
+
meta("$.revokedKeyId").as("revokedKeyId"),
|
|
221
|
+
meta("$.replacedConnectionId").as("replacedConnectionId")
|
|
222
|
+
]).where("action", "in", ACCESS_ACTIONS).where(sql`not (${sql.ref("action")} = ${INVITATION_ACCEPTED_ACTION} and coalesce(${meta("$.joined")}, 1) = 0)`).where("outcome", "=", "success").where("occurredAt", ">=", SQLiteDate.encode(filter.since)).where("occurredAt", "<=", SQLiteDate.encode(filter.until)).$if(position !== void 0, (query) => query.where((eb) => eb.or([eb("occurredAt", ">", position?.sort ?? 0), eb.and([eb("occurredAt", "=", position?.sort ?? 0), eb("id", ">", position?.id ?? 0)])])))).with("classified", (q) => q.selectFrom("extracted").selectAll().select(sql`case
|
|
223
|
+
when ${oneOf("action", memberActions)} then 'member'
|
|
224
|
+
when ${oneOf("action", KEY_ACTIONS)} then 'key'
|
|
225
|
+
when ${sql.ref("registeredKeyId")} is not null or ${sql.ref("revokedKeyId")} is not null then 'key'
|
|
226
|
+
else 'connection' end`.as("subject"))).with("answered", (q) => q.selectFrom("classified").select([
|
|
227
|
+
"id",
|
|
228
|
+
"eventId",
|
|
229
|
+
"occurredAt",
|
|
230
|
+
"action",
|
|
231
|
+
"actorType",
|
|
232
|
+
"actorId",
|
|
233
|
+
"actorKind",
|
|
234
|
+
"subject",
|
|
235
|
+
sql`case when ${sql.ref("subject")} = 'member' then ${sql.ref("tenant")} end`.as("organizationId"),
|
|
236
|
+
sql`case when ${sql.ref("subject")} = 'member' then
|
|
237
|
+
case when ${sql.ref("action")} = 'organization/created' then ${sql.ref("recordedMembershipId")}
|
|
238
|
+
else ${sql.ref("resourceId")} end end`.as("membershipId"),
|
|
239
|
+
sql`case when ${sql.ref("subject")} = 'member' then coalesce(${sql.ref("subjectUserId")},
|
|
240
|
+
case when ${oneOf("action", SELF_ACTIONS)} then ${sql.ref("actorId")} end) end`.as("userId"),
|
|
241
|
+
sql`case
|
|
242
|
+
when ${oneOf("action", changes)} or ${oneOf("action", ownership)} then ${sql.ref("previousRole")}
|
|
243
|
+
when ${oneOf("action", ends)} then ${sql.ref("role")} end`.as("roleBefore"),
|
|
244
|
+
sql`case
|
|
245
|
+
when ${oneOf("action", joins)} or ${oneOf("action", changes)} then ${sql.ref("role")}
|
|
246
|
+
when ${oneOf("action", ownership)} then coalesce(${sql.ref("role")}, ${sql.ref("confers")}) end`.as("roleAfter"),
|
|
247
|
+
sql`case when ${sql.ref("subject")} != 'member' then ${sql.ref("resourceId")} end`.as("connectionId"),
|
|
248
|
+
sql`case when ${sql.ref("subject")} = 'connection' then ${sql.ref("connectionKind")} end`.as("connectionKind"),
|
|
249
|
+
sql`case when ${sql.ref("subject")} = 'connection' then ${sql.ref("purpose")} end`.as("purpose"),
|
|
250
|
+
sql`case when ${sql.ref("subject")} = 'connection' then ${sql.ref("principal")} end`.as("principal"),
|
|
251
|
+
sql`case when ${sql.ref("subject")} = 'connection' then case ${sql.ref("action")}
|
|
252
|
+
when ${ControlPlaneAuditActions.connectionUpdated} then coalesce(${sql.ref("scopesBeforeKey")}, ${sql.ref("scopesFrom")})
|
|
253
|
+
when ${ControlPlaneAuditActions.connectionRemoved} then ${sql.ref("scopes")} end end`.as("scopesBefore"),
|
|
254
|
+
sql`case when ${sql.ref("subject")} = 'connection' then case ${sql.ref("action")}
|
|
255
|
+
when ${ControlPlaneAuditActions.connectionRegistered} then ${sql.ref("scopes")}
|
|
256
|
+
when ${ControlPlaneAuditActions.connectionUpdated} then coalesce(${sql.ref("scopesAfterKey")}, ${sql.ref("scopesTo")})
|
|
257
|
+
end end`.as("scopesAfter"),
|
|
258
|
+
sql`case when ${sql.ref("subject")} = 'connection' and ${sql.ref("action")} = ${ControlPlaneAuditActions.connectionRegistered}
|
|
259
|
+
then ${sql.ref("replacedConnectionId")} end`.as("replacedConnectionId"),
|
|
260
|
+
sql`case when ${sql.ref("subject")} = 'key' then
|
|
261
|
+
coalesce(${sql.ref("registeredKeyId")}, ${sql.ref("expiredKeyId")}, ${sql.ref("revokedKeyId")}) end`.as("keyId"),
|
|
262
|
+
sql`case when ${sql.ref("subject")} = 'key' then case
|
|
263
|
+
when ${sql.ref("action")} = ${ControlPlaneAuditActions.keyExpired} then 'expired'
|
|
264
|
+
when ${sql.ref("action")} = ${ControlPlaneAuditActions.keyRegistered} or ${sql.ref("registeredKeyId")} is not null then 'registered'
|
|
265
|
+
else 'revoked' end end`.as("keyChange")
|
|
266
|
+
])).selectFrom("answered").selectAll().select(sql`case ${sql.ref("subject")}
|
|
267
|
+
when 'member' then case
|
|
268
|
+
when ${oneOf("action", joins)} then ${sql.ref("roleAfter")} is not null
|
|
269
|
+
when ${oneOf("action", ends)} then ${sql.ref("roleBefore")} is not null
|
|
270
|
+
else ${sql.ref("roleBefore")} is not null and ${sql.ref("roleAfter")} is not null end
|
|
271
|
+
when 'connection' then case ${sql.ref("action")}
|
|
272
|
+
when ${ControlPlaneAuditActions.connectionRegistered} then ${sql.ref("scopesAfter")} is not null
|
|
273
|
+
when ${ControlPlaneAuditActions.connectionRemoved} then ${sql.ref("scopesBefore")} is not null
|
|
274
|
+
else ${sql.ref("scopesBefore")} is not null and ${sql.ref("scopesAfter")} is not null end
|
|
275
|
+
else ${sql.ref("keyId")} is not null end`.as("recorded")).orderBy("occurredAt", "asc").orderBy("id", "asc").limit(page.limit + 1);
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* Read one page of access changes in a window, oldest first.
|
|
279
|
+
*
|
|
280
|
+
* **Keyset, never offset**, ascending: the trail is appended to while it is read, and a change recorded mid-read
|
|
281
|
+
* lands after the window's last page rather than pushing a row from one page onto the next.
|
|
282
|
+
*/
|
|
283
|
+
async function accessHistory(db, filter) {
|
|
284
|
+
const limit = pageLimit(filter.limit);
|
|
285
|
+
const decoded = (await accessHistoryStatement(db, filter, {
|
|
286
|
+
position: keysetPosition(decodeCursor(filter.cursor)),
|
|
287
|
+
limit
|
|
288
|
+
}).execute()).map((row) => AccessHistoryRow.parse(row));
|
|
289
|
+
const page = toPage(decoded, limit, (row) => ({
|
|
290
|
+
sort: row.occurredAt.getTime(),
|
|
291
|
+
id: row.id
|
|
292
|
+
}));
|
|
293
|
+
return {
|
|
294
|
+
changes: page.items,
|
|
295
|
+
nextCursor: page.nextCursor
|
|
296
|
+
};
|
|
297
|
+
}
|
|
298
|
+
//#endregion
|
|
299
|
+
export { ACCESS_ACTIONS, ACCESS_HISTORY_METADATA_KEYS, AccessHistoryRow, INVITATION_ACCEPTED_ACTION, MEMBER_ACCESS_ACTIONS, accessHistory, accessHistoryStatement };
|
package/dist/actions.d.ts
CHANGED
|
@@ -25,10 +25,14 @@ export declare function defineAuditActions<const T extends Record<string, string
|
|
|
25
25
|
* every other capability, so a management client paging through it is doing something that has to be
|
|
26
26
|
* answerable later; a trail that records every write and no read cannot answer "who looked".
|
|
27
27
|
*
|
|
28
|
-
* They are separate codes rather than one, because the
|
|
28
|
+
* They are separate codes rather than one, because the reads disclose different things and a
|
|
29
29
|
* reviewer filtering the trail should not have to inspect metadata to tell them apart:
|
|
30
30
|
* `audit/trail_read` is a filtered page of structural fields, while `audit/event_read` is the full
|
|
31
31
|
* record of one event — the IP, the user-agent, and the capability metadata included.
|
|
32
|
+
* `audit/access_history_read` is the access changes in a window: who held what, and when it changed.
|
|
33
|
+
* `audit/reach_read` is one credential's reach: counts by tenant and route, and on request one route's subjects.
|
|
34
|
+
* `audit/usage_read` is counts: which scopes one connection exercised and was refused, by key, over a window.
|
|
35
|
+
* `audit/chain_verified` is a walk of one tenant's chain, and `audit/chain_exported` a page of it in canonical form (#822).
|
|
32
36
|
*
|
|
33
37
|
* Yes, this appends to the table it just read. That is a loop by design, not by accident: the row it
|
|
34
38
|
* writes is one row, it is the only durable evidence the read happened, and the alternative is a
|
|
@@ -39,5 +43,15 @@ export declare const AuditTrailActions: {
|
|
|
39
43
|
readonly trailRead: "audit/trail_read";
|
|
40
44
|
/** One event was read in full, network identifiers and metadata included. */
|
|
41
45
|
readonly eventRead: "audit/event_read";
|
|
46
|
+
/** The access changes in a window were read — before and after, never an event in full (#831). */
|
|
47
|
+
readonly accessHistoryRead: "audit/access_history_read";
|
|
48
|
+
/** One control-plane credential's reach was read — tenants, routes and subjects, never an event in full (#828). */
|
|
49
|
+
readonly reachRead: "audit/reach_read";
|
|
50
|
+
/** One control-plane connection's usage was counted — scopes and keys, never an event in full (#812). */
|
|
51
|
+
readonly usageRead: "audit/usage_read";
|
|
52
|
+
/** One tenant's chain was walked and checked against its checkpoints (#822). */
|
|
53
|
+
readonly chainVerified: "audit/chain_verified";
|
|
54
|
+
/** A page of one tenant's chain was exported in canonical form, its personal values only with the detail scope (#822). */
|
|
55
|
+
readonly chainExported: "audit/chain_exported";
|
|
42
56
|
};
|
|
43
57
|
//# sourceMappingURL=actions.d.ts.map
|
package/dist/actions.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAYxF;AAED
|
|
1
|
+
{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAYxF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB;IAC5B,6CAA6C;;IAE7C,6EAA6E;;IAE7E,kGAAkG;;IAElG,mHAAmH;;IAEnH,yGAAyG;;IAEzG,gFAAgF;;IAEhF,0HAA0H;;CAE1H,CAAC"}
|
package/dist/actions.js
CHANGED
|
@@ -38,10 +38,14 @@ function defineAuditActions(actions) {
|
|
|
38
38
|
* every other capability, so a management client paging through it is doing something that has to be
|
|
39
39
|
* answerable later; a trail that records every write and no read cannot answer "who looked".
|
|
40
40
|
*
|
|
41
|
-
* They are separate codes rather than one, because the
|
|
41
|
+
* They are separate codes rather than one, because the reads disclose different things and a
|
|
42
42
|
* reviewer filtering the trail should not have to inspect metadata to tell them apart:
|
|
43
43
|
* `audit/trail_read` is a filtered page of structural fields, while `audit/event_read` is the full
|
|
44
44
|
* record of one event — the IP, the user-agent, and the capability metadata included.
|
|
45
|
+
* `audit/access_history_read` is the access changes in a window: who held what, and when it changed.
|
|
46
|
+
* `audit/reach_read` is one credential's reach: counts by tenant and route, and on request one route's subjects.
|
|
47
|
+
* `audit/usage_read` is counts: which scopes one connection exercised and was refused, by key, over a window.
|
|
48
|
+
* `audit/chain_verified` is a walk of one tenant's chain, and `audit/chain_exported` a page of it in canonical form (#822).
|
|
45
49
|
*
|
|
46
50
|
* Yes, this appends to the table it just read. That is a loop by design, not by accident: the row it
|
|
47
51
|
* writes is one row, it is the only durable evidence the read happened, and the alternative is a
|
|
@@ -51,7 +55,17 @@ const AuditTrailActions = defineAuditActions({
|
|
|
51
55
|
/** A filtered page of the trail was read. */
|
|
52
56
|
trailRead: "audit/trail_read",
|
|
53
57
|
/** One event was read in full, network identifiers and metadata included. */
|
|
54
|
-
eventRead: "audit/event_read"
|
|
58
|
+
eventRead: "audit/event_read",
|
|
59
|
+
/** The access changes in a window were read — before and after, never an event in full (#831). */
|
|
60
|
+
accessHistoryRead: "audit/access_history_read",
|
|
61
|
+
/** One control-plane credential's reach was read — tenants, routes and subjects, never an event in full (#828). */
|
|
62
|
+
reachRead: "audit/reach_read",
|
|
63
|
+
/** One control-plane connection's usage was counted — scopes and keys, never an event in full (#812). */
|
|
64
|
+
usageRead: "audit/usage_read",
|
|
65
|
+
/** One tenant's chain was walked and checked against its checkpoints (#822). */
|
|
66
|
+
chainVerified: "audit/chain_verified",
|
|
67
|
+
/** A page of one tenant's chain was exported in canonical form, its personal values only with the detail scope (#822). */
|
|
68
|
+
chainExported: "audit/chain_exported"
|
|
55
69
|
});
|
|
56
70
|
//#endregion
|
|
57
71
|
export { AuditTrailActions, defineAuditActions };
|
package/dist/capability.d.ts
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
3
|
import { type Capability } from "@pithy-sh/core/src/capability/capability";
|
|
4
4
|
import { z } from "zod";
|
|
5
|
+
import { AuditSinks } from "./ship/sinks";
|
|
5
6
|
/**
|
|
6
7
|
* Sort order of the audit migration within the audit database, relative to other capabilities
|
|
7
8
|
* (core low, app high). Unique per database; the migration registry composes the key
|
|
@@ -22,6 +23,17 @@ export declare const AUDIT_MIGRATION_ORDER = 250;
|
|
|
22
23
|
export declare const AuditConfig: z.ZodObject<{
|
|
23
24
|
database: z.ZodDefault<z.ZodString>;
|
|
24
25
|
basePath: z.ZodDefault<z.ZodString>;
|
|
26
|
+
sinks: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
|
|
27
|
+
profile: z.ZodEnum<{
|
|
28
|
+
"datadog-logs": "datadog-logs";
|
|
29
|
+
"splunk-hec": "splunk-hec";
|
|
30
|
+
webhook: "webhook";
|
|
31
|
+
}>;
|
|
32
|
+
url: z.ZodURL;
|
|
33
|
+
secret: z.ZodString;
|
|
34
|
+
actions: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
|
|
35
|
+
detail: z.ZodDefault<z.ZodBoolean>;
|
|
36
|
+
}, z.core.$strict>>>;
|
|
25
37
|
}, z.core.$strip>;
|
|
26
38
|
export type AuditConfig = z.output<typeof AuditConfig>;
|
|
27
39
|
export type AuditConfigInput = z.input<typeof AuditConfig>;
|
|
@@ -29,6 +41,8 @@ export type AuditConfigInput = z.input<typeof AuditConfig>;
|
|
|
29
41
|
export interface AuditCapability extends Capability {
|
|
30
42
|
/** The D1 binding the audit table lives in (the resolved `database` config). */
|
|
31
43
|
auditDatabase: string;
|
|
44
|
+
/** The sinks the trail ships to (#824), as declared — what `pithy doctor` lists. */
|
|
45
|
+
auditSinks: AuditSinks;
|
|
32
46
|
}
|
|
33
47
|
/**
|
|
34
48
|
* The audit capability. It contributes the `pithy_audit_events` table to the configured D1 binding
|
package/dist/capability.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAQ7F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsBxB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI1C;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAWzC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;iBAiB8B,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,MAAM,GAAE,gBAAqB,GAAG,eAAe,CAiLpE;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
|
package/dist/capability.js
CHANGED
|
@@ -1,16 +1,35 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
-
import {
|
|
3
|
+
import { AUDIT_CHECKPOINT_BINDING } from "./chain/checkpoint.js";
|
|
4
|
+
import { auditAppWorkflows, auditWorkflows } from "./workflows/specs.js";
|
|
5
|
+
import { checkpointLockCheck } from "./chain/lockCheck.js";
|
|
6
|
+
import { auditDatabase, auditTables } from "./data/tables.js";
|
|
7
|
+
import { auditCitationsFor } from "./citations.js";
|
|
4
8
|
import { auditAdminRoutes } from "./http/guards.js";
|
|
5
9
|
import { registerAuditRoutes } from "./http/routes.js";
|
|
6
10
|
import { audit_0001_init } from "./migrations/0001_init.js";
|
|
7
11
|
import { audit_0002_actor_kind } from "./migrations/0002_actor_kind.js";
|
|
12
|
+
import { audit_0003_call_index } from "./migrations/0003_call_index.js";
|
|
13
|
+
import { audit_0004_request_index } from "./migrations/0004_request_index.js";
|
|
14
|
+
import { audit_0005_chain } from "./migrations/0005_chain.js";
|
|
15
|
+
import { audit_0006_sinks } from "./migrations/0006_sinks.js";
|
|
16
|
+
import { auditUserPurge } from "./purge/contribution.js";
|
|
8
17
|
import { recordAuditEvent } from "./recorder.js";
|
|
9
18
|
import { auditExampleSeed } from "./seeds/example.js";
|
|
19
|
+
import { AuditSinks } from "./ship/sinks.js";
|
|
20
|
+
import { shipBindings } from "./ship/queue.js";
|
|
21
|
+
import { auditShipConsumer } from "./ship/consumer.js";
|
|
22
|
+
import { shipHealth } from "./ship/health.js";
|
|
23
|
+
import { sinkSecretsRegistry } from "./ship/secrets.js";
|
|
24
|
+
import { shipperFor } from "./ship/shipper.js";
|
|
10
25
|
import { PACKAGE_NAME, PACKAGE_VERSION } from "./version.generated.js";
|
|
26
|
+
import { z } from "zod";
|
|
27
|
+
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
11
28
|
import { defineCapability } from "@pithy-sh/core/src/capability/capability";
|
|
29
|
+
import { createWorkerLogger } from "@pithy-sh/core/src/logger/worker";
|
|
12
30
|
import { workerIdentity } from "@pithy-sh/core/src/worker/identity";
|
|
13
|
-
import {
|
|
31
|
+
import { workflowBindings } from "@pithy-sh/core/src/workflow/bindings";
|
|
32
|
+
import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
|
|
14
33
|
//#region src/capability.ts
|
|
15
34
|
/**
|
|
16
35
|
* Sort order of the audit migration within the audit database, relative to other capabilities
|
|
@@ -39,7 +58,8 @@ const AUDIT_DATABASE_NAME = "app";
|
|
|
39
58
|
*/
|
|
40
59
|
const AuditConfig = z.object({
|
|
41
60
|
database: z.string().default("DB").describe("The D1 binding the audit table and its migrations target. Defaults to `DB`, the shared app database."),
|
|
42
|
-
basePath: z.string().startsWith("/").default("/audit").describe("Where the control-plane routes that read the trail mount. Reads only — the trail is append-only and this surface never writes.")
|
|
61
|
+
basePath: z.string().startsWith("/").default("/audit").describe("Where the control-plane routes that read the trail mount. Reads only — the trail is append-only and this surface never writes."),
|
|
62
|
+
sinks: AuditSinks.default({}).describe("Where the trail is shipped as it is written — Splunk HEC, Datadog Logs, or any HTTPS endpoint — by name. Declared here and nowhere else: no control-plane route adds, changes or removes one. Empty ships nothing and binds no queue.")
|
|
43
63
|
}).describe("Configuration for the audit capability.");
|
|
44
64
|
/**
|
|
45
65
|
* The audit capability. It contributes the `pithy_audit_events` table to the configured D1 binding
|
|
@@ -49,41 +69,133 @@ const AuditConfig = z.object({
|
|
|
49
69
|
*/
|
|
50
70
|
function audit(config = {}) {
|
|
51
71
|
const resolved = AuditConfig.parse(config);
|
|
72
|
+
const sinks = resolved.sinks;
|
|
73
|
+
const ships = Object.keys(sinks).length > 0;
|
|
74
|
+
const sinkSecrets = sinkSecretsRegistry(sinks);
|
|
75
|
+
const databaseOf = (c) => c.var.db[AUDIT_DATABASE_NAME];
|
|
76
|
+
let adminRoutes = auditAdminRoutes(resolved.basePath);
|
|
52
77
|
const capability = defineCapability({
|
|
53
78
|
name: "audit",
|
|
54
79
|
version: PACKAGE_VERSION,
|
|
55
80
|
package: PACKAGE_NAME,
|
|
56
81
|
config: AuditConfig,
|
|
57
|
-
requiredBindings: [
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
82
|
+
requiredBindings: [
|
|
83
|
+
{
|
|
84
|
+
type: "d1",
|
|
85
|
+
name: resolved.database
|
|
86
|
+
},
|
|
87
|
+
{
|
|
88
|
+
type: "r2",
|
|
89
|
+
name: AUDIT_CHECKPOINT_BINDING,
|
|
90
|
+
optional: true
|
|
91
|
+
},
|
|
92
|
+
...workflowBindings(auditWorkflows),
|
|
93
|
+
...workflowBindings(auditAppWorkflows),
|
|
94
|
+
...shipBindings(sinks)
|
|
95
|
+
],
|
|
96
|
+
...ships ? {
|
|
97
|
+
dependsOn: ["secrets"],
|
|
98
|
+
secretRegistry: sinkSecrets,
|
|
99
|
+
health: shipHealth(sinks, databaseOf),
|
|
100
|
+
queue: auditShipConsumer({
|
|
101
|
+
sinks,
|
|
102
|
+
database: (env) => {
|
|
103
|
+
const binding = env[resolved.database];
|
|
104
|
+
if (typeof binding !== "object" || binding === null) throw new InternalError({
|
|
105
|
+
message: "Audit shipping cannot read the trail.",
|
|
106
|
+
action: `Bind the ${resolved.database} D1 database to this Worker.`,
|
|
107
|
+
detail: `no ${resolved.database} binding on the queue invocation's env`
|
|
108
|
+
});
|
|
109
|
+
return auditDatabase(binding);
|
|
110
|
+
},
|
|
111
|
+
token: async (env, secret) => (await sharedSecretsStore(env, sinkSecrets)).get(secret),
|
|
112
|
+
log: createWorkerLogger({ name: "audit" })
|
|
113
|
+
})
|
|
114
|
+
} : {},
|
|
115
|
+
workflows: {
|
|
116
|
+
...auditWorkflows,
|
|
117
|
+
...auditAppWorkflows
|
|
118
|
+
},
|
|
119
|
+
settings: checkpointLockCheck(),
|
|
61
120
|
databases: { [AUDIT_DATABASE_NAME]: {
|
|
62
121
|
binding: resolved.database,
|
|
63
122
|
tables: auditTables,
|
|
64
123
|
migrationOrder: 250,
|
|
65
124
|
migrations: {
|
|
66
125
|
"0001_init": audit_0001_init,
|
|
67
|
-
"0002_actor_kind": audit_0002_actor_kind
|
|
126
|
+
"0002_actor_kind": audit_0002_actor_kind,
|
|
127
|
+
"0003_call_index": audit_0003_call_index,
|
|
128
|
+
"0004_request_index": audit_0004_request_index,
|
|
129
|
+
"0005_chain": audit_0005_chain,
|
|
130
|
+
"0006_sinks": audit_0006_sinks
|
|
68
131
|
}
|
|
69
132
|
} },
|
|
70
133
|
seeds: [auditExampleSeed],
|
|
134
|
+
purge: [auditUserPurge(resolved.database)],
|
|
135
|
+
auditRecorder: (env) => {
|
|
136
|
+
const log = createWorkerLogger({ name: "audit" });
|
|
137
|
+
const binding = env[resolved.database];
|
|
138
|
+
return async (event) => {
|
|
139
|
+
if (typeof binding !== "object" || binding === null) {
|
|
140
|
+
log.error("audit event dropped", {
|
|
141
|
+
reason: `no ${resolved.database} binding`,
|
|
142
|
+
action: event.action
|
|
143
|
+
});
|
|
144
|
+
return;
|
|
145
|
+
}
|
|
146
|
+
const ship = shipperFor(env, sinks);
|
|
147
|
+
await recordAuditEvent(auditDatabase(binding), event, {
|
|
148
|
+
origin: workerIdentity(env),
|
|
149
|
+
onError: (error) => log.error("audit event dropped", { error }),
|
|
150
|
+
...ship ? {
|
|
151
|
+
ship,
|
|
152
|
+
onShipError: (error) => log.error("audit shipment not enqueued", { error })
|
|
153
|
+
} : {}
|
|
154
|
+
});
|
|
155
|
+
};
|
|
156
|
+
},
|
|
157
|
+
auditCitations: auditCitationsFor(resolved.database),
|
|
71
158
|
adminRoutes: auditAdminRoutes(resolved.basePath),
|
|
159
|
+
compose: ({ capabilities }) => {
|
|
160
|
+
adminRoutes = capabilities.flatMap((capability) => capability.adminRoutes ?? []);
|
|
161
|
+
},
|
|
72
162
|
routes: registerAuditRoutes({
|
|
73
163
|
basePath: resolved.basePath,
|
|
74
|
-
database: (c) => c.var.db[AUDIT_DATABASE_NAME]
|
|
164
|
+
database: (c) => c.var.db[AUDIT_DATABASE_NAME],
|
|
165
|
+
adminRoutes: () => adminRoutes,
|
|
166
|
+
checkpoints: (c) => {
|
|
167
|
+
const bucket = c.env?.[AUDIT_CHECKPOINT_BINDING];
|
|
168
|
+
return typeof bucket === "object" && bucket !== null ? bucket : null;
|
|
169
|
+
}
|
|
75
170
|
}),
|
|
76
171
|
middleware: [(app) => {
|
|
77
172
|
app.use("*", async (c, next) => {
|
|
78
|
-
|
|
173
|
+
const ship = shipperFor(c.env, sinks);
|
|
174
|
+
const onShipError = (error) => c.var.log.child("audit").error("audit shipment not enqueued", { error });
|
|
175
|
+
c.set("emit", (event) => recordAuditEvent(databaseOf(c), event, {
|
|
79
176
|
origin: workerIdentity(c.env),
|
|
80
|
-
onError: (error) => c.var.log.child("audit").error("audit event dropped", { error })
|
|
177
|
+
onError: (error) => c.var.log.child("audit").error("audit event dropped", { error }),
|
|
178
|
+
...ship ? {
|
|
179
|
+
ship: (shipment) => {
|
|
180
|
+
const sent = ship(shipment);
|
|
181
|
+
try {
|
|
182
|
+
c.executionCtx.waitUntil(sent.catch(onShipError));
|
|
183
|
+
return Promise.resolve();
|
|
184
|
+
} catch {
|
|
185
|
+
return sent;
|
|
186
|
+
}
|
|
187
|
+
},
|
|
188
|
+
onShipError
|
|
189
|
+
} : {}
|
|
81
190
|
}));
|
|
82
191
|
await next();
|
|
83
192
|
});
|
|
84
193
|
}]
|
|
85
194
|
});
|
|
86
|
-
return Object.assign(capability, {
|
|
195
|
+
return Object.assign(capability, {
|
|
196
|
+
auditDatabase: resolved.database,
|
|
197
|
+
auditSinks: sinks
|
|
198
|
+
});
|
|
87
199
|
}
|
|
88
200
|
/** Whether a capability is the audit capability — carries its resolved binding. */
|
|
89
201
|
function isAuditCapability(capability) {
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
import { type D1RetryOptions } from "@pithy-sh/core/src/data/withD1Retry";
|
|
4
|
+
import type { AuditDatabase, AuditEventInsert } from "../data/tables";
|
|
5
|
+
/**
|
|
6
|
+
* How long one append keeps contending for its chain's next position before it gives up, in ms. Every lost race
|
|
7
|
+
* means another event landed, so a burst of appends to one tenant all land, one position at a time: the bound is on
|
|
8
|
+
* time, not on how many appends overtake this one, so no burst size drops an event. It exists only to end a request
|
|
9
|
+
* that a chain somebody is writing wrong would hold forever.
|
|
10
|
+
*/
|
|
11
|
+
export declare const CHAIN_APPEND_DEADLINE_MS = 30000;
|
|
12
|
+
/**
|
|
13
|
+
* How many lost races in a row may find the head where it was. A race is lost because an event took the position,
|
|
14
|
+
* so the head moves; one that does not move is a chain this append cannot join, and retrying it is spinning.
|
|
15
|
+
*/
|
|
16
|
+
export declare const CHAIN_APPEND_STALLS = 3;
|
|
17
|
+
/** How one append contends for its chain. Every field has a default; tests narrow them. */
|
|
18
|
+
export interface ChainAppendOptions {
|
|
19
|
+
/** How a transient D1 fault on the insert is retried. */
|
|
20
|
+
retry?: D1RetryOptions;
|
|
21
|
+
/** How long the append keeps contending, in ms. Defaults to {@link CHAIN_APPEND_DEADLINE_MS}. */
|
|
22
|
+
deadlineMs?: number;
|
|
23
|
+
/** The longest back-off between attempts, in ms. Defaults to 50; 0 retries at once. */
|
|
24
|
+
backoffCeilingMs?: number;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* **Append one event to its tenant's chain, without forking it (#822).**
|
|
28
|
+
*
|
|
29
|
+
* Read the head, compute this event's link and hash, then insert in **one statement that refuses when the head has
|
|
30
|
+
* moved**: `INSERT … SELECT … WHERE NOT EXISTS (an event at or past this position in this chain)`. D1 runs one
|
|
31
|
+
* statement at a time, so the check and the write cannot be split by another append. A loser inserts nothing,
|
|
32
|
+
* backs off a random moment, re-reads the head and tries again, so two concurrent appends never share a position
|
|
33
|
+
* and never name the same predecessor, and a burst of them all lands. The partial unique indexes from
|
|
34
|
+
* `audit_0005_chain` sit under it as a backstop.
|
|
35
|
+
*
|
|
36
|
+
* `withD1Retry` still rides out a transient fault on the insert. A retry after a write that landed inserts nothing
|
|
37
|
+
* here rather than tripping the unique index, so it is told apart from a lost race by asking whether the event's
|
|
38
|
+
* own id is already in the table.
|
|
39
|
+
*/
|
|
40
|
+
export declare function appendChained(db: AuditDatabase, record: AuditEventInsert, options?: ChainAppendOptions): Promise<void>;
|
|
41
|
+
/** Whether a failed write failed because the database has not taken `audit_0005_chain` yet. */
|
|
42
|
+
export declare function isUnmigratedChain(error: unknown): boolean;
|
|
43
|
+
//# sourceMappingURL=append.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"append.d.ts","sourceRoot":"","sources":["../../src/chain/append.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,cAAc,EAAe,MAAM,qCAAqC,CAAC;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAItE;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAKrC,2FAA2F;AAC3F,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AASD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CA0Ff;AAMD,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEzD"}
|