@pithy-sh/audit 0.7.0 → 0.8.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 +1 -1
- package/dist/capability.d.ts +1 -1
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +4 -3
- package/dist/http/guards.d.ts +4 -0
- package/dist/http/guards.d.ts.map +1 -1
- package/dist/http/guards.js +12 -0
- package/dist/http/responses.d.ts +46 -0
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +18 -1
- package/dist/http/routes.d.ts +7 -2
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +29 -7
- package/dist/http/views.d.ts +15 -5
- package/dist/http/views.d.ts.map +1 -1
- package/dist/http/views.js +37 -5
- package/dist/ship/consumer.js +1 -1
- package/dist/ship/delivery.d.ts +13 -0
- package/dist/ship/delivery.d.ts.map +1 -0
- package/dist/ship/delivery.js +21 -0
- package/dist/ship/health.d.ts +2 -11
- package/dist/ship/health.d.ts.map +1 -1
- package/dist/ship/health.js +4 -18
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/package.json +3 -3
- package/src/capability.ts +19 -20
- package/src/http/guards.ts +13 -0
- package/src/http/responses.ts +64 -0
- package/src/http/routes.ts +37 -7
- package/src/http/views.ts +41 -5
- package/src/ship/delivery.ts +23 -0
- package/src/ship/health.ts +3 -21
- package/src/version.generated.ts +1 -1
package/README.md
CHANGED
|
@@ -82,7 +82,7 @@ Set the token with `pithy secrets create splunk-hec-token --env prod`, then run
|
|
|
82
82
|
|
|
83
83
|
**Declared, not toggled.** A sink is reviewed and deployed like code. No control-plane route adds, changes or removes one, so no management credential can point the trail somewhere new.
|
|
84
84
|
|
|
85
|
-
**Delivered at least once, and never in the way.** Each event a Worker writes goes on the `AUDIT_SHIP` queue once per sink that takes it, naming the event and the sink and nothing else; the Worker's own consumer reads the row back and posts each sink's share of a batch in one request. Enqueueing happens after the write and never fails it. A redirect is never followed, so the token and the batch go only to the URL you declared; a sink answering 3xx counts as a refusal. A sink that refuses or cannot be reached retries after 30 seconds, doubling to an hour, and fails alone: the other sinks still deliver. After ten retries a message goes to `AUDIT_SHIP_DLQ` and waits there for a person. Audit's manifest entry reports `auditShipBacklog`, `auditShipDeadLettered` and `auditShipDelivery` (`delivering`, `failing`, `idle`), behind `audit:events:read`, and `pithy doctor` lists every sink and whether each environment holds its token.
|
|
85
|
+
**Delivered at least once, and never in the way.** Each event a Worker writes goes on the `AUDIT_SHIP` queue once per sink that takes it, naming the event and the sink and nothing else; the Worker's own consumer reads the row back and posts each sink's share of a batch in one request. Enqueueing happens after the write and never fails it. A redirect is never followed, so the token and the batch go only to the URL you declared; a sink answering 3xx counts as a refusal. A sink that refuses or cannot be reached retries after 30 seconds, doubling to an hour, and fails alone: the other sinks still deliver. After ten retries a message goes to `AUDIT_SHIP_DLQ` and waits there for a person. Audit's manifest entry reports `auditShipBacklog`, `auditShipDeadLettered` and `auditShipDelivery` (`delivering`, `failing`, `idle`), behind `audit:events:read`, each across every sink: the two counts summed, and the state `failing` when any sink is. `GET /audit/control-plane/sinks`, behind the same scope, answers each sink on its own, in declaration order: its name, profile, host, `detail` flag and `actions` filter, its `lastDeliveredAt` and `lastFailedAt`, its `retrying` backlog, its `deadLettered` count and its own `delivery` state. Never its token, its URL path or query, or an event. `pithy doctor` lists every sink and whether each environment holds its token.
|
|
86
86
|
|
|
87
87
|
**Redacted by default.** Without `detail: true`, no IP, user-agent or metadata value leaves the Worker. The sink receives their salted commitments instead — the same ones the chain hashes — which verify and disclose nothing. With `detail: true` the values and their salt travel, so the receiver can check the commitments too.
|
|
88
88
|
|
package/dist/capability.d.ts
CHANGED
|
@@ -41,7 +41,7 @@ export type AuditConfigInput = z.input<typeof AuditConfig>;
|
|
|
41
41
|
export interface AuditCapability extends Capability {
|
|
42
42
|
/** The D1 binding the audit table lives in (the resolved `database` config). */
|
|
43
43
|
auditDatabase: string;
|
|
44
|
-
/** The sinks the trail ships to
|
|
44
|
+
/** The sinks the trail ships to, as declared — what `pithy doctor` lists. */
|
|
45
45
|
auditSinks: AuditSinks;
|
|
46
46
|
}
|
|
47
47
|
/**
|
package/dist/capability.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
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,
|
|
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,6EAA6E;IAC7E,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,MAAM,GAAE,gBAAqB,GAAG,eAAe,CAgLpE;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,eAAe,CAEvF"}
|
package/dist/capability.js
CHANGED
|
@@ -6,6 +6,7 @@ import { checkpointLockCheck } from "./chain/lockCheck.js";
|
|
|
6
6
|
import { auditDatabase, auditTables } from "./data/tables.js";
|
|
7
7
|
import { auditCitationsFor } from "./citations.js";
|
|
8
8
|
import { auditAdminRoutes } from "./http/guards.js";
|
|
9
|
+
import { AuditSinks } from "./ship/sinks.js";
|
|
9
10
|
import { registerAuditRoutes } from "./http/routes.js";
|
|
10
11
|
import { audit_0001_init } from "./migrations/0001_init.js";
|
|
11
12
|
import { audit_0002_actor_kind } from "./migrations/0002_actor_kind.js";
|
|
@@ -16,7 +17,6 @@ import { audit_0006_sinks } from "./migrations/0006_sinks.js";
|
|
|
16
17
|
import { auditUserPurge } from "./purge/contribution.js";
|
|
17
18
|
import { recordAuditEvent } from "./recorder.js";
|
|
18
19
|
import { auditExampleSeed } from "./seeds/example.js";
|
|
19
|
-
import { AuditSinks } from "./ship/sinks.js";
|
|
20
20
|
import { shipBindings } from "./ship/queue.js";
|
|
21
21
|
import { auditShipConsumer } from "./ship/consumer.js";
|
|
22
22
|
import { shipHealth } from "./ship/health.js";
|
|
@@ -42,7 +42,7 @@ const AUDIT_MIGRATION_ORDER = 250;
|
|
|
42
42
|
* database (`app`, the `DB` binding) by default — so the audit migration tracks alongside the app's
|
|
43
43
|
* in one `pithy_migrations` table rather than fighting it on a second provider over the same binding.
|
|
44
44
|
* The physical binding is config-selectable; this registry key is the coordination point capabilities
|
|
45
|
-
* use to share one database (CLAUDE.md §Data layer
|
|
45
|
+
* use to share one database (CLAUDE.md §Data layer).
|
|
46
46
|
*/
|
|
47
47
|
const AUDIT_DATABASE_NAME = "app";
|
|
48
48
|
/**
|
|
@@ -166,7 +166,8 @@ function audit(config = {}) {
|
|
|
166
166
|
checkpoints: (c) => {
|
|
167
167
|
const bucket = c.env?.[AUDIT_CHECKPOINT_BINDING];
|
|
168
168
|
return typeof bucket === "object" && bucket !== null ? bucket : null;
|
|
169
|
-
}
|
|
169
|
+
},
|
|
170
|
+
sinks
|
|
170
171
|
}),
|
|
171
172
|
middleware: [(app) => {
|
|
172
173
|
app.use("*", async (c, next) => {
|
package/dist/http/guards.d.ts
CHANGED
|
@@ -53,6 +53,10 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
|
|
|
53
53
|
* already names in `resourceId`, and the tenant is what it shows as `tenant`; the answer never carries an IP, a user-agent, or a metadata key beyond the key id, scope, method and
|
|
54
54
|
* path. So a breach review does not need the detail scope to draw a breach scope.
|
|
55
55
|
*
|
|
56
|
+
* **The sinks ride the listing scope.** `GET {base}/control-plane/sinks` answers each declared sink's name, profile,
|
|
57
|
+
* host, filter and delivery state — what the manifest's health keys already total behind the same scope. It never
|
|
58
|
+
* carries a token, a secret name, a URL path or query, an event, or anything a receiver answered.
|
|
59
|
+
*
|
|
56
60
|
* **The chain has a scope of its own.** `GET {base}/control-plane/verify` walks one tenant's chain, and
|
|
57
61
|
* `GET {base}/control-plane/export` takes it out in canonical form with its checkpoints. An export is the trail in
|
|
58
62
|
* bulk, meant to leave the building, so neither read rides the listing scope: both need `audit:events:export`. The
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF
|
|
1
|
+
{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAAuC,CAAC;AAE7E;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA8C,CAAC;AAE3F;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAAyC,CAAC;AAEjF;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,iBAAiB,EAIlE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,EAAE,CA0E1E"}
|
package/dist/http/guards.js
CHANGED
|
@@ -52,6 +52,10 @@
|
|
|
52
52
|
* already names in `resourceId`, and the tenant is what it shows as `tenant`; the answer never carries an IP, a user-agent, or a metadata key beyond the key id, scope, method and
|
|
53
53
|
* path. So a breach review does not need the detail scope to draw a breach scope.
|
|
54
54
|
*
|
|
55
|
+
* **The sinks ride the listing scope.** `GET {base}/control-plane/sinks` answers each declared sink's name, profile,
|
|
56
|
+
* host, filter and delivery state — what the manifest's health keys already total behind the same scope. It never
|
|
57
|
+
* carries a token, a secret name, a URL path or query, an event, or anything a receiver answered.
|
|
58
|
+
*
|
|
55
59
|
* **The chain has a scope of its own.** `GET {base}/control-plane/verify` walks one tenant's chain, and
|
|
56
60
|
* `GET {base}/control-plane/export` takes it out in canonical form with its checkpoints. An export is the trail in
|
|
57
61
|
* bulk, meant to leave the building, so neither read rides the listing scope: both need `audit:events:export`. The
|
|
@@ -152,6 +156,14 @@ function auditAdminRoutes(basePath) {
|
|
|
152
156
|
kind: "reads",
|
|
153
157
|
summary: "Export one tenant's hash chain in canonical form with its checkpoints, to verify offline. Personal values only with the detail scope."
|
|
154
158
|
},
|
|
159
|
+
{
|
|
160
|
+
method: "GET",
|
|
161
|
+
operation: "sinks.list",
|
|
162
|
+
path: `${basePath}/control-plane/sinks`,
|
|
163
|
+
scope: AUDIT_TRAIL_READ_SCOPE,
|
|
164
|
+
kind: "reads",
|
|
165
|
+
summary: "List every sink the trail ships to, with its profile, host and filter, and its backlog, last delivery and dead letters. No event is read."
|
|
166
|
+
},
|
|
155
167
|
{
|
|
156
168
|
method: "GET",
|
|
157
169
|
operation: "events.read",
|
package/dist/http/responses.d.ts
CHANGED
|
@@ -680,4 +680,50 @@ export declare const ChainExportResponse: z.ZodObject<{
|
|
|
680
680
|
nextCursor: z.ZodNullable<z.ZodString>;
|
|
681
681
|
}, z.core.$strip>;
|
|
682
682
|
export type ChainExportResponse = z.output<typeof ChainExportResponse>;
|
|
683
|
+
/** One declared sink, as `GET {base}/control-plane/sinks` shows it. Never its URL path, its query or its token. */
|
|
684
|
+
export declare const AuditSinkView: z.ZodObject<{
|
|
685
|
+
name: z.ZodString;
|
|
686
|
+
profile: z.ZodEnum<{
|
|
687
|
+
"datadog-logs": "datadog-logs";
|
|
688
|
+
"splunk-hec": "splunk-hec";
|
|
689
|
+
webhook: "webhook";
|
|
690
|
+
}>;
|
|
691
|
+
host: z.ZodString;
|
|
692
|
+
detail: z.ZodBoolean;
|
|
693
|
+
actions: z.ZodNullable<z.ZodArray<z.ZodString>>;
|
|
694
|
+
lastDeliveredAt: z.ZodNullable<z.ZodISODateTime>;
|
|
695
|
+
lastFailedAt: z.ZodNullable<z.ZodISODateTime>;
|
|
696
|
+
retrying: z.ZodNumber;
|
|
697
|
+
deadLettered: z.ZodNumber;
|
|
698
|
+
delivery: z.ZodEnum<{
|
|
699
|
+
delivering: "delivering";
|
|
700
|
+
failing: "failing";
|
|
701
|
+
idle: "idle";
|
|
702
|
+
}>;
|
|
703
|
+
}, z.core.$strip>;
|
|
704
|
+
export type AuditSinkView = z.output<typeof AuditSinkView>;
|
|
705
|
+
/** `GET {base}/control-plane/sinks`. */
|
|
706
|
+
export declare const AuditSinksResponse: z.ZodObject<{
|
|
707
|
+
sinks: z.ZodArray<z.ZodObject<{
|
|
708
|
+
name: z.ZodString;
|
|
709
|
+
profile: z.ZodEnum<{
|
|
710
|
+
"datadog-logs": "datadog-logs";
|
|
711
|
+
"splunk-hec": "splunk-hec";
|
|
712
|
+
webhook: "webhook";
|
|
713
|
+
}>;
|
|
714
|
+
host: z.ZodString;
|
|
715
|
+
detail: z.ZodBoolean;
|
|
716
|
+
actions: z.ZodNullable<z.ZodArray<z.ZodString>>;
|
|
717
|
+
lastDeliveredAt: z.ZodNullable<z.ZodISODateTime>;
|
|
718
|
+
lastFailedAt: z.ZodNullable<z.ZodISODateTime>;
|
|
719
|
+
retrying: z.ZodNumber;
|
|
720
|
+
deadLettered: z.ZodNumber;
|
|
721
|
+
delivery: z.ZodEnum<{
|
|
722
|
+
delivering: "delivering";
|
|
723
|
+
failing: "failing";
|
|
724
|
+
idle: "idle";
|
|
725
|
+
}>;
|
|
726
|
+
}, z.core.$strip>>;
|
|
727
|
+
}, z.core.$strip>;
|
|
728
|
+
export type AuditSinksResponse = z.output<typeof AuditSinksResponse>;
|
|
683
729
|
//# sourceMappingURL=responses.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;
|
|
1
|
+
{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkCxB;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmC0E,CAAC;AACtG,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAY0E,CAAC;AAC5G,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEzE,2BAA2B;AAC3B,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK6B,CAAC;AAC9D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,oCAAoC;AACpC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAEQ,CAAC;AACxC,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AA4BrE,mDAAmD;AACnD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAa4B,CAAC;AAC5D,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAErE,sEAAsE;AACtE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyB2C,CAAC;AAC/E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E,iEAAiE;AACjE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAO2D,CAAC;AACxF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D,wDAAwD;AACxD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BAEiE,CAAC;AAC/F,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE,iDAAiD;AACjD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAO8E,CAAC;AACjH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;iBAwC4E,CAAC;AAC/G,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E,sEAAsE;AACtE,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;iBA0BqE,CAAC;AAC/G,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAEzF,wCAAwC;AACxC,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgBqE,CAAC;AAC5G,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAEnF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;iBA0BgD,CAAC;AACnF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E,wCAAwC;AACxC,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;iBAaoE,CAAC;AAC3G,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAEnF,yCAAyC;AACzC,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2CiE,CAAC;AAClG,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAE/B,CAAC;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,mHAAmH;AACnH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;iBAgDsE,CAAC;AACjG,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D,wCAAwC;AACxC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;iBAMqE,CAAC;AACrG,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
|
package/dist/http/responses.js
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
import { SHIP_DELIVERY_STATES } from "../ship/delivery.js";
|
|
4
|
+
import { AuditSinkProfile } from "../ship/sinks.js";
|
|
3
5
|
import { AuditActorType, AuditMetadata, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
|
|
4
6
|
import { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
|
|
5
7
|
import { z } from "zod";
|
|
@@ -223,5 +225,20 @@ const ChainVerifyResponse = z.object({
|
|
|
223
225
|
* one schema, so what the Worker writes and what the verifier accepts cannot drift.
|
|
224
226
|
*/
|
|
225
227
|
const ChainExportResponse = AuditChainExport.describe("One page of one tenant's audit chain: canonical events, their hashes, the link before them and the checkpoints covering them.");
|
|
228
|
+
/** One declared sink, as `GET {base}/control-plane/sinks` shows it. Never its URL path, its query or its token. */
|
|
229
|
+
const AuditSinkView = z.object({
|
|
230
|
+
name: z.string().describe("The sink's name, as `audit({ sinks })` declares it."),
|
|
231
|
+
profile: AuditSinkProfile.describe("The format the sink is delivered in: `splunk-hec`, `datadog-logs` or `webhook`."),
|
|
232
|
+
host: z.string().describe("The host the sink posts to, with its port when the URL names one. Never the path or query, which may carry a key."),
|
|
233
|
+
detail: z.boolean().describe("Whether the sink receives each event's IP, user-agent and metadata values, rather than their salted hashes."),
|
|
234
|
+
actions: z.array(z.string().describe("An action prefix the sink takes, e.g. `auth/`.")).nullable().describe("The action prefixes the sink takes, or null when it takes every action the trail records."),
|
|
235
|
+
lastDeliveredAt: z.iso.datetime().nullable().describe("When the sink last accepted a delivery, ISO-8601, or null when it never has."),
|
|
236
|
+
lastFailedAt: z.iso.datetime().nullable().describe("When the sink last refused a delivery or could not be reached, ISO-8601, or null when it never has."),
|
|
237
|
+
retrying: z.number().int().nonnegative().describe("How many events are waiting on a retry to this sink: its backlog. The manifest's `auditShipBacklog` is the sum over every sink."),
|
|
238
|
+
deadLettered: z.number().int().nonnegative().describe("How many events this sink never took: their retries ran out and they went to the dead-letter queue. The manifest's `auditShipDeadLettered` is the sum."),
|
|
239
|
+
delivery: z.enum(SHIP_DELIVERY_STATES).describe("How delivery to this sink stands: `failing` when its last attempt failed, `delivering` when it last took one, `idle` when it has never been attempted.")
|
|
240
|
+
}).describe("One sink the trail ships to: where, what it takes, and how delivery to it stands.");
|
|
241
|
+
/** `GET {base}/control-plane/sinks`. */
|
|
242
|
+
const AuditSinksResponse = z.object({ sinks: z.array(AuditSinkView).describe("Every declared sink, in declaration order. Empty when the Worker ships nothing.") }).describe("Every sink the trail ships to, each with its backlog, last delivery and dead letters.");
|
|
226
243
|
//#endregion
|
|
227
|
-
export { AccessChangeView, AccessHistoryResponse, AuditEventDetailView, AuditEventResponse, AuditEventView, AuditEventsResponse, ChainExportResponse, ChainVerifyResponse, ConnectionAccessChange, ControlPlaneReachResponse, ControlPlaneReachSubjectView, ControlPlaneReachView, ControlPlaneUsageResponse, ControlPlaneUsageView, KeyAccessChange, MemberAccessChange };
|
|
244
|
+
export { AccessChangeView, AccessHistoryResponse, AuditEventDetailView, AuditEventResponse, AuditEventView, AuditEventsResponse, AuditSinkView, AuditSinksResponse, ChainExportResponse, ChainVerifyResponse, ConnectionAccessChange, ControlPlaneReachResponse, ControlPlaneReachSubjectView, ControlPlaneReachView, ControlPlaneUsageResponse, ControlPlaneUsageView, KeyAccessChange, MemberAccessChange };
|
package/dist/http/routes.d.ts
CHANGED
|
@@ -7,6 +7,7 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
|
|
|
7
7
|
import type { VerificationStrategy } from "@pithy-sh/core/src/http/verification";
|
|
8
8
|
import type { Context, Hono } from "hono";
|
|
9
9
|
import type { AuditDatabase } from "../data/tables";
|
|
10
|
+
import type { AuditSinks } from "../ship/sinks";
|
|
10
11
|
/**
|
|
11
12
|
* The audit routes, their verification strategies, and what each accepts:
|
|
12
13
|
*
|
|
@@ -22,9 +23,11 @@ import type { AuditDatabase } from "../data/tables";
|
|
|
22
23
|
* (control-plane: audit:events:export) query: ChainVerifyQuery
|
|
23
24
|
* GET /audit/control-plane/export → one tenant's chain in canonical form, with its checkpoints
|
|
24
25
|
* (control-plane: audit:events:export) query: ChainExportQuery
|
|
26
|
+
* GET /audit/control-plane/sinks → every declared sink and how delivery to it stands
|
|
27
|
+
* (control-plane: audit:events:read) no input
|
|
25
28
|
*
|
|
26
29
|
* **All are reads, and there is nothing else.** The trail is append-only: no route here deletes,
|
|
27
|
-
* edits, or prunes, because a management credential that could erase an audit row could erase the
|
|
30
|
+
* edits, or prunes, and no route adds, changes or removes a sink, because a management credential that could erase an audit row could erase the
|
|
28
31
|
* evidence of its own use. Retention is a lifecycle concern for a Workflow, not a button on a
|
|
29
32
|
* dashboard.
|
|
30
33
|
*
|
|
@@ -73,10 +76,12 @@ export interface AuditRoutesOptions {
|
|
|
73
76
|
*/
|
|
74
77
|
adminRoutes: () => readonly AdminRoute[];
|
|
75
78
|
/**
|
|
76
|
-
* The checkpoint bucket for this request, or null when the Worker binds none
|
|
79
|
+
* The checkpoint bucket for this request, or null when the Worker binds none. Absent, verify checks links
|
|
77
80
|
* alone and says so, and an export carries no checkpoints.
|
|
78
81
|
*/
|
|
79
82
|
checkpoints?: (c: Context<PithyHonoEnv>) => R2Bucket | null;
|
|
83
|
+
/** The sinks the trail ships to, as declared. Absent, the sinks read answers an empty list. */
|
|
84
|
+
sinks?: AuditSinks;
|
|
80
85
|
}
|
|
81
86
|
/** Register the audit sub-router. Returned as the capability's `routes` hook. */
|
|
82
87
|
export declare function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<PithyHonoEnv>) => void;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAE7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sDAAsD,CAAC;AAEvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAIrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;
|
|
1
|
+
{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/http/routes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAE7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sDAAsD,CAAC;AAEvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAIrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAiChD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAED,wCAAwC;AACxC,eAAO,MAAM,YAAY,EAAE,SAAS,qBAAqB,EASxD,CAAC;AAEF,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,QAAQ,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,aAAa,CAAC;IACtD;;;OAGG;IACH,WAAW,EAAE,MAAM,SAAS,UAAU,EAAE,CAAC;IACzC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,QAAQ,GAAG,IAAI,CAAC;IAC5D,+FAA+F;IAC/F,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AA2CD,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAmblG"}
|
package/dist/http/routes.js
CHANGED
|
@@ -7,10 +7,11 @@ import { exportChainRange, verifyChainRange } from "../chain/verify.js";
|
|
|
7
7
|
import { pageAuditEvents, readAuditEvent } from "../query.js";
|
|
8
8
|
import { reachPatterns } from "../routePattern.js";
|
|
9
9
|
import { controlPlaneReach, controlPlaneReachSubjects } from "../reach.js";
|
|
10
|
+
import { readSinkStates } from "../ship/state.js";
|
|
10
11
|
import { controlPlaneUsage } from "../usage.js";
|
|
11
|
-
import { AccessHistoryResponse, AuditEventResponse, AuditEventsResponse, ChainExportResponse, ChainVerifyResponse, ControlPlaneReachResponse, ControlPlaneUsageResponse } from "./responses.js";
|
|
12
|
+
import { AccessHistoryResponse, AuditEventResponse, AuditEventsResponse, AuditSinksResponse, ChainExportResponse, ChainVerifyResponse, ControlPlaneReachResponse, ControlPlaneUsageResponse } from "./responses.js";
|
|
12
13
|
import { AccessHistoryQuery, AuditEventIdParam, ChainExportQuery, ChainVerifyQuery, ControlPlaneReachQuery, ControlPlaneUsageQuery, ListAuditEventsQuery } from "./schemas.js";
|
|
13
|
-
import { accessChangeView, auditEventDetailView, auditEventView, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView } from "./views.js";
|
|
14
|
+
import { accessChangeView, auditEventDetailView, auditEventView, auditSinkViews, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView } from "./views.js";
|
|
14
15
|
import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
|
|
15
16
|
import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
|
|
16
17
|
import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
|
|
@@ -59,6 +60,12 @@ const AUDIT_ROUTES = [
|
|
|
59
60
|
path: "/control-plane/export",
|
|
60
61
|
strategy: "control-plane",
|
|
61
62
|
scope: AUDIT_CHAIN_EXPORT_SCOPE
|
|
63
|
+
},
|
|
64
|
+
{
|
|
65
|
+
method: "GET",
|
|
66
|
+
path: "/control-plane/sinks",
|
|
67
|
+
strategy: "control-plane",
|
|
68
|
+
scope: AUDIT_TRAIL_READ_SCOPE
|
|
62
69
|
}
|
|
63
70
|
];
|
|
64
71
|
/**
|
|
@@ -103,6 +110,7 @@ function registerAuditRoutes(options) {
|
|
|
103
110
|
const database = options.database;
|
|
104
111
|
const adminRoutes = options.adminRoutes;
|
|
105
112
|
const checkpoints = options.checkpoints ?? (() => null);
|
|
113
|
+
const sinks = options.sinks ?? {};
|
|
106
114
|
return (app) => {
|
|
107
115
|
/**
|
|
108
116
|
* CONTROL-PLANE READ. A filtered, resumable page of the trail — keyset, never offset, because the
|
|
@@ -173,7 +181,7 @@ function registerAuditRoutes(options) {
|
|
|
173
181
|
return c.json({ event: auditEventDetailView(row) }, 200);
|
|
174
182
|
});
|
|
175
183
|
/**
|
|
176
|
-
* CONTROL-PLANE READ
|
|
184
|
+
* CONTROL-PLANE READ. Who could do what, over time: every membership, connection and key change in a
|
|
177
185
|
* window, oldest first, with its before and after — one SQL statement per page, never a walk of events here.
|
|
178
186
|
* Behind the listing scope, not the detail one: it lifts named metadata keys and never an IP or a user-agent.
|
|
179
187
|
*/
|
|
@@ -222,7 +230,7 @@ function registerAuditRoutes(options) {
|
|
|
222
230
|
}, 200);
|
|
223
231
|
});
|
|
224
232
|
/**
|
|
225
|
-
* CONTROL-PLANE READ
|
|
233
|
+
* CONTROL-PLANE READ. What one credential reached — by tenant, action, method, route and outcome — over a
|
|
226
234
|
* window, in one SQL statement, never by paging events here. `subjects=true` expands one route into the subject
|
|
227
235
|
* ids its called paths name. Behind the listing scope, not the detail one: the answer is the tenant, the route,
|
|
228
236
|
* the scope and ids the listing already shows, and never an IP, a user-agent or any other metadata key.
|
|
@@ -284,7 +292,7 @@ function registerAuditRoutes(options) {
|
|
|
284
292
|
}, 200);
|
|
285
293
|
});
|
|
286
294
|
/**
|
|
287
|
-
* CONTROL-PLANE READ
|
|
295
|
+
* CONTROL-PLANE READ. Which scopes one connection exercised and was refused, by key, over a window —
|
|
288
296
|
* counted in one SQL statement, never by paging events here. Behind the listing scope, not the detail one: the
|
|
289
297
|
* answer is the scope, the key, and the last allowed call's method and path, and never an IP, a user-agent or any
|
|
290
298
|
* other metadata key.
|
|
@@ -334,7 +342,7 @@ function registerAuditRoutes(options) {
|
|
|
334
342
|
}, 200);
|
|
335
343
|
});
|
|
336
344
|
/**
|
|
337
|
-
* CONTROL-PLANE READ
|
|
345
|
+
* CONTROL-PLANE READ. Walk one tenant's hash chain over a window — every link, every hash, the
|
|
338
346
|
* checkpoints covering it — and answer intact or the first break. Reads only: it proves the trail whole and
|
|
339
347
|
* changes nothing.
|
|
340
348
|
*/
|
|
@@ -391,7 +399,7 @@ function registerAuditRoutes(options) {
|
|
|
391
399
|
}, 200);
|
|
392
400
|
});
|
|
393
401
|
/**
|
|
394
|
-
* CONTROL-PLANE READ
|
|
402
|
+
* CONTROL-PLANE READ. One page of one tenant's chain in canonical form, each event with its hash, the
|
|
395
403
|
* link before the page and the checkpoints covering it — what `pithy audit verify` checks offline. The IP,
|
|
396
404
|
* user-agent and metadata values ride along only when the connection also holds the detail scope.
|
|
397
405
|
*/
|
|
@@ -438,6 +446,20 @@ function registerAuditRoutes(options) {
|
|
|
438
446
|
});
|
|
439
447
|
return c.json(page, 200);
|
|
440
448
|
});
|
|
449
|
+
/**
|
|
450
|
+
* CONTROL-PLANE READ. Every declared sink beside its own delivery row: one primary-key lookup per sink, bounded
|
|
451
|
+
* by the config. Not audited, unlike the trail's reads: it reads delivery state, never the trail, and a pane
|
|
452
|
+
* polling it would otherwise append to the trail, and ship to every sink, on each poll.
|
|
453
|
+
*/
|
|
454
|
+
app.get(`${base}/control-plane/sinks`, describeRoute({
|
|
455
|
+
summary: "List every sink the trail ships to, each with its backlog, last delivery and dead letters.",
|
|
456
|
+
verification: "control-plane",
|
|
457
|
+
scopes: [AUDIT_TRAIL_READ_SCOPE],
|
|
458
|
+
responses: { 200: AuditSinksResponse }
|
|
459
|
+
}), requireControlPlane(AUDIT_TRAIL_READ_SCOPE), async (c) => {
|
|
460
|
+
const states = await readSinkStates(database(c), Object.keys(sinks));
|
|
461
|
+
return c.json({ sinks: auditSinkViews(sinks, states) }, 200);
|
|
462
|
+
});
|
|
441
463
|
};
|
|
442
464
|
}
|
|
443
465
|
//#endregion
|
package/dist/http/views.d.ts
CHANGED
|
@@ -2,9 +2,11 @@
|
|
|
2
2
|
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
3
|
import type { AccessHistoryRow } from "../accessHistory";
|
|
4
4
|
import type { AuditEventRow } from "../data/auditEvent";
|
|
5
|
+
import type { AuditSinkStateRow } from "../data/sinkState";
|
|
5
6
|
import type { ControlPlaneReachRow, ControlPlaneReachSubjectRow } from "../reach";
|
|
7
|
+
import type { AuditSinks } from "../ship/sinks";
|
|
6
8
|
import type { ControlPlaneUsageRow } from "../usage";
|
|
7
|
-
import type { AccessChangeView, AuditEventDetailView, AuditEventView, ControlPlaneReachSubjectView, ControlPlaneReachView, ControlPlaneUsageView } from "./responses";
|
|
9
|
+
import type { AccessChangeView, AuditEventDetailView, AuditEventView, AuditSinkView, ControlPlaneReachSubjectView, ControlPlaneReachView, ControlPlaneUsageView } from "./responses";
|
|
8
10
|
/**
|
|
9
11
|
* What a management client is shown of an audit event — decided here, once, rather than by whichever
|
|
10
12
|
* columns a query happened to select.
|
|
@@ -56,7 +58,7 @@ export declare function auditEventView(row: AuditEventRow): AuditEventView;
|
|
|
56
58
|
/** Project one row for the single-event read, network identifiers and metadata included. */
|
|
57
59
|
export declare function auditEventDetailView(row: AuditEventRow): AuditEventDetailView;
|
|
58
60
|
/**
|
|
59
|
-
* Project one access change
|
|
61
|
+
* Project one access change into the wire union, by what changed.
|
|
60
62
|
*
|
|
61
63
|
* The statement already read nothing but the named metadata keys, so this drops nothing personal; what it does is
|
|
62
64
|
* keep each subject's fields to that subject, so a member change never carries a null `scopesBefore` a client could
|
|
@@ -64,16 +66,24 @@ export declare function auditEventDetailView(row: AuditEventRow): AuditEventDeta
|
|
|
64
66
|
*/
|
|
65
67
|
export declare function accessChangeView(row: AccessHistoryRow): AccessChangeView;
|
|
66
68
|
/**
|
|
67
|
-
* Project one reach row
|
|
69
|
+
* Project one reach row. Field for field, with the instants as ISO-8601: the statement already read nothing
|
|
68
70
|
* but the scope, the key, the method and the path out of `metadata`, and the tenant out of the handler's events, so
|
|
69
71
|
* there is nothing here to drop.
|
|
70
72
|
*/
|
|
71
73
|
export declare function controlPlaneReachView(row: ControlPlaneReachRow): ControlPlaneReachView;
|
|
72
|
-
/** Project one subject row
|
|
74
|
+
/** Project one subject row, field for field, the same way — never a spread a new field would ride out on. */
|
|
73
75
|
export declare function controlPlaneReachSubjectView(row: ControlPlaneReachSubjectRow): ControlPlaneReachSubjectView;
|
|
74
76
|
/**
|
|
75
|
-
* Project one usage row
|
|
77
|
+
* Project one usage row. Field for field, with the instants as ISO-8601: the aggregate already read nothing but
|
|
76
78
|
* the scope, the key, and the last allowed call's method and path out of `metadata`, so there is nothing here to drop.
|
|
77
79
|
*/
|
|
78
80
|
export declare function controlPlaneUsageView(row: ControlPlaneUsageRow): ControlPlaneUsageView;
|
|
81
|
+
/**
|
|
82
|
+
* Project the declared sinks, in declaration order, each beside its own state row. A sink with no row has never been
|
|
83
|
+
* attempted and answers null times, zero counts and `idle`; a row whose sink is no longer declared is not answered.
|
|
84
|
+
*
|
|
85
|
+
* Named fields, never a spread of the config: a sink's URL path and query may carry a key, and its secret name says
|
|
86
|
+
* where its token lives, so neither leaves. The host is the URL's host and port, as `pithy doctor` prints it.
|
|
87
|
+
*/
|
|
88
|
+
export declare function auditSinkViews(sinks: AuditSinks, states: readonly AuditSinkStateRow[]): AuditSinkView[];
|
|
79
89
|
//# sourceMappingURL=views.d.ts.map
|
package/dist/http/views.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../src/http/views.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;
|
|
1
|
+
{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../src/http/views.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAElF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,aAAa,EACb,4BAA4B,EAC5B,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,cAAc,CA6BjE;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,oBAAoB,CAE7E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CA2CxE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,oBAAoB,GAAG,qBAAqB,CActF;AAED,6GAA6G;AAC7G,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,2BAA2B,GAAG,4BAA4B,CAgB3G;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,oBAAoB,GAAG,qBAAqB,CAWtF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,iBAAiB,EAAE,GAAG,aAAa,EAAE,CAuBvG"}
|
package/dist/http/views.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
import { shipDelivery } from "../ship/delivery.js";
|
|
3
4
|
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
4
5
|
//#region src/http/views.ts
|
|
5
6
|
/**
|
|
@@ -81,7 +82,7 @@ function auditEventDetailView(row) {
|
|
|
81
82
|
};
|
|
82
83
|
}
|
|
83
84
|
/**
|
|
84
|
-
* Project one access change
|
|
85
|
+
* Project one access change into the wire union, by what changed.
|
|
85
86
|
*
|
|
86
87
|
* The statement already read nothing but the named metadata keys, so this drops nothing personal; what it does is
|
|
87
88
|
* keep each subject's fields to that subject, so a member change never carries a null `scopesBefore` a client could
|
|
@@ -130,7 +131,7 @@ function accessChangeView(row) {
|
|
|
130
131
|
};
|
|
131
132
|
}
|
|
132
133
|
/**
|
|
133
|
-
* Project one reach row
|
|
134
|
+
* Project one reach row. Field for field, with the instants as ISO-8601: the statement already read nothing
|
|
134
135
|
* but the scope, the key, the method and the path out of `metadata`, and the tenant out of the handler's events, so
|
|
135
136
|
* there is nothing here to drop.
|
|
136
137
|
*/
|
|
@@ -149,7 +150,7 @@ function controlPlaneReachView(row) {
|
|
|
149
150
|
lastAt: row.lastAt.toISOString()
|
|
150
151
|
};
|
|
151
152
|
}
|
|
152
|
-
/** Project one subject row
|
|
153
|
+
/** Project one subject row, field for field, the same way — never a spread a new field would ride out on. */
|
|
153
154
|
function controlPlaneReachSubjectView(row) {
|
|
154
155
|
return {
|
|
155
156
|
tenant: row.tenant,
|
|
@@ -168,7 +169,7 @@ function controlPlaneReachSubjectView(row) {
|
|
|
168
169
|
};
|
|
169
170
|
}
|
|
170
171
|
/**
|
|
171
|
-
* Project one usage row
|
|
172
|
+
* Project one usage row. Field for field, with the instants as ISO-8601: the aggregate already read nothing but
|
|
172
173
|
* the scope, the key, and the last allowed call's method and path out of `metadata`, so there is nothing here to drop.
|
|
173
174
|
*/
|
|
174
175
|
function controlPlaneUsageView(row) {
|
|
@@ -183,5 +184,36 @@ function controlPlaneUsageView(row) {
|
|
|
183
184
|
lastDeniedAt: row.lastDeniedAt?.toISOString() ?? null
|
|
184
185
|
};
|
|
185
186
|
}
|
|
187
|
+
/**
|
|
188
|
+
* Project the declared sinks, in declaration order, each beside its own state row. A sink with no row has never been
|
|
189
|
+
* attempted and answers null times, zero counts and `idle`; a row whose sink is no longer declared is not answered.
|
|
190
|
+
*
|
|
191
|
+
* Named fields, never a spread of the config: a sink's URL path and query may carry a key, and its secret name says
|
|
192
|
+
* where its token lives, so neither leaves. The host is the URL's host and port, as `pithy doctor` prints it.
|
|
193
|
+
*/
|
|
194
|
+
function auditSinkViews(sinks, states) {
|
|
195
|
+
const byName = new Map(states.map((state) => [state.sink, state]));
|
|
196
|
+
return Object.entries(sinks).map(([name, sink]) => {
|
|
197
|
+
const state = byName.get(name) ?? {
|
|
198
|
+
sink: name,
|
|
199
|
+
lastDeliveredAt: null,
|
|
200
|
+
lastFailedAt: null,
|
|
201
|
+
retrying: 0,
|
|
202
|
+
deadLettered: 0
|
|
203
|
+
};
|
|
204
|
+
return {
|
|
205
|
+
name,
|
|
206
|
+
profile: sink.profile,
|
|
207
|
+
host: new URL(sink.url).host,
|
|
208
|
+
detail: sink.detail,
|
|
209
|
+
actions: sink.actions === void 0 ? null : [...sink.actions],
|
|
210
|
+
lastDeliveredAt: state.lastDeliveredAt?.toISOString() ?? null,
|
|
211
|
+
lastFailedAt: state.lastFailedAt?.toISOString() ?? null,
|
|
212
|
+
retrying: state.retrying,
|
|
213
|
+
deadLettered: state.deadLettered,
|
|
214
|
+
delivery: shipDelivery([state])
|
|
215
|
+
};
|
|
216
|
+
});
|
|
217
|
+
}
|
|
186
218
|
//#endregion
|
|
187
|
-
export { accessChangeView, auditEventDetailView, auditEventView, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView };
|
|
219
|
+
export { accessChangeView, auditEventDetailView, auditEventView, auditSinkViews, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView };
|
package/dist/ship/consumer.js
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
2
|
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
3
|
import { readRowsByEventId } from "../chain/rows.js";
|
|
4
|
+
import { recordSinkOutcome } from "./state.js";
|
|
4
5
|
import { shippedEventOf } from "./event.js";
|
|
5
6
|
import { sinkDelivery } from "./profiles.js";
|
|
6
7
|
import { ShipMessage, isFinalAttempt, retryDelaySeconds } from "./queue.js";
|
|
7
|
-
import { recordSinkOutcome } from "./state.js";
|
|
8
8
|
//#region src/ship/consumer.ts
|
|
9
9
|
/**
|
|
10
10
|
* **The shipping consumer (#824): one request per sink per batch, at least once.**
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
import type { AuditSinkStateRow } from "../data/sinkState";
|
|
4
|
+
/**
|
|
5
|
+
* The values a delivery state takes: per sink on the sinks read, and across every sink on the manifest's
|
|
6
|
+
* `auditShipDelivery`. `failing` when any sink's last attempt failed; `delivering` when every sink that has been
|
|
7
|
+
* attempted last took a delivery; `idle` when no sink has been attempted yet.
|
|
8
|
+
*/
|
|
9
|
+
export declare const SHIP_DELIVERY_STATES: readonly ["delivering", "failing", "idle"];
|
|
10
|
+
export type ShipDeliveryState = (typeof SHIP_DELIVERY_STATES)[number];
|
|
11
|
+
/** How delivery stands, from the given sinks' rows: one sink's for its own state, every declared sink's for the total. */
|
|
12
|
+
export declare function shipDelivery(states: readonly AuditSinkStateRow[]): ShipDeliveryState;
|
|
13
|
+
//# sourceMappingURL=delivery.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../../src/ship/delivery.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,YAAI,YAAY,EAAE,SAAS,EAAE,MAAM,CAAU,CAAC;AAC/E,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,0HAA0H;AAC1H,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,GAAG,iBAAiB,CAQpF"}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
//#region src/ship/delivery.ts
|
|
4
|
+
/**
|
|
5
|
+
* The values a delivery state takes: per sink on the sinks read, and across every sink on the manifest's
|
|
6
|
+
* `auditShipDelivery`. `failing` when any sink's last attempt failed; `delivering` when every sink that has been
|
|
7
|
+
* attempted last took a delivery; `idle` when no sink has been attempted yet.
|
|
8
|
+
*/
|
|
9
|
+
const SHIP_DELIVERY_STATES = [
|
|
10
|
+
"delivering",
|
|
11
|
+
"failing",
|
|
12
|
+
"idle"
|
|
13
|
+
];
|
|
14
|
+
/** How delivery stands, from the given sinks' rows: one sink's for its own state, every declared sink's for the total. */
|
|
15
|
+
function shipDelivery(states) {
|
|
16
|
+
const attempted = states.filter((state) => state.lastDeliveredAt !== null || state.lastFailedAt !== null);
|
|
17
|
+
if (attempted.length === 0) return "idle";
|
|
18
|
+
return attempted.some((state) => state.lastFailedAt !== null && (state.lastDeliveredAt === null || state.lastFailedAt > state.lastDeliveredAt)) ? "failing" : "delivering";
|
|
19
|
+
}
|
|
20
|
+
//#endregion
|
|
21
|
+
export { SHIP_DELIVERY_STATES, shipDelivery };
|
package/dist/ship/health.d.ts
CHANGED
|
@@ -3,11 +3,10 @@
|
|
|
3
3
|
import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
|
|
4
4
|
import { type CapabilityHealth } from "@pithy-sh/core/src/controlPlane/discovery/health";
|
|
5
5
|
import type { Context } from "hono";
|
|
6
|
-
import type { AuditSinkStateRow } from "../data/sinkState";
|
|
7
6
|
import type { AuditDatabase } from "../data/tables";
|
|
8
7
|
import type { AuditSinks } from "./sinks";
|
|
9
8
|
/**
|
|
10
|
-
* **Shipping's health, on audit's manifest entry
|
|
9
|
+
* **Shipping's health, on audit's manifest entry** — whether the trail is reaching its sinks.
|
|
11
10
|
*
|
|
12
11
|
* Three keys, all behind `audit:events:read`, the scope the listing already requires: a backlog, a dead-letter
|
|
13
12
|
* count, and a state. Each is read off `pithy_audit_sinks` by primary key, one row per declared sink, so the bound
|
|
@@ -18,16 +17,8 @@ import type { AuditSinks } from "./sinks";
|
|
|
18
17
|
export declare const AUDIT_SHIP_BACKLOG = "auditShipBacklog";
|
|
19
18
|
/** Events given up on, across every sink: their last retry failed and they went to the dead-letter queue. */
|
|
20
19
|
export declare const AUDIT_SHIP_DEAD_LETTERED = "auditShipDeadLettered";
|
|
21
|
-
/** How delivery stands, across every sink. */
|
|
20
|
+
/** How delivery stands, across every sink: {@link shipDelivery} over every declared sink's row. */
|
|
22
21
|
export declare const AUDIT_SHIP_DELIVERY = "auditShipDelivery";
|
|
23
|
-
/**
|
|
24
|
-
* The values {@link AUDIT_SHIP_DELIVERY} takes. `failing` when any sink's last attempt failed; `delivering` when
|
|
25
|
-
* every sink that has been attempted last took a delivery; `idle` when no sink has been attempted yet.
|
|
26
|
-
*/
|
|
27
|
-
export declare const SHIP_DELIVERY_STATES: readonly ["delivering", "failing", "idle"];
|
|
28
|
-
export type ShipDeliveryState = (typeof SHIP_DELIVERY_STATES)[number];
|
|
29
|
-
/** How delivery stands, from the declared sinks' rows. */
|
|
30
|
-
export declare function shipDelivery(states: readonly AuditSinkStateRow[]): ShipDeliveryState;
|
|
31
22
|
/** Declare shipping's health keys over the declared sinks. */
|
|
32
23
|
export declare function shipHealth(sinks: AuditSinks, database: (c: Context<PithyHonoEnv>) => AuditDatabase): CapabilityHealth;
|
|
33
24
|
//# sourceMappingURL=health.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/ship/health.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAC7E,OAAO,EAAE,KAAK,gBAAgB,EAA0B,MAAM,kDAAkD,CAAC;AACjH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,
|
|
1
|
+
{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/ship/health.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAC7E,OAAO,EAAE,KAAK,gBAAgB,EAA0B,MAAM,kDAAkD,CAAC;AACjH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAG1C;;;;;;;GAOG;AAEH,oDAAoD;AACpD,eAAO,MAAM,kBAAkB,qBAAqB,CAAC;AAErD,6GAA6G;AAC7G,eAAO,MAAM,wBAAwB,0BAA0B,CAAC;AAEhE,mGAAmG;AACnG,eAAO,MAAM,mBAAmB,sBAAsB,CAAC;AAEvD,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,aAAa,GAAG,gBAAgB,CA0CrH"}
|
package/dist/ship/health.js
CHANGED
|
@@ -2,10 +2,11 @@
|
|
|
2
2
|
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
3
|
import { AUDIT_TRAIL_READ_SCOPE } from "../http/guards.js";
|
|
4
4
|
import { readSinkStates } from "./state.js";
|
|
5
|
+
import { SHIP_DELIVERY_STATES, shipDelivery } from "./delivery.js";
|
|
5
6
|
import { defineCapabilityHealth } from "@pithy-sh/core/src/controlPlane/discovery/health";
|
|
6
7
|
//#region src/ship/health.ts
|
|
7
8
|
/**
|
|
8
|
-
* **Shipping's health, on audit's manifest entry
|
|
9
|
+
* **Shipping's health, on audit's manifest entry** — whether the trail is reaching its sinks.
|
|
9
10
|
*
|
|
10
11
|
* Three keys, all behind `audit:events:read`, the scope the listing already requires: a backlog, a dead-letter
|
|
11
12
|
* count, and a state. Each is read off `pithy_audit_sinks` by primary key, one row per declared sink, so the bound
|
|
@@ -16,23 +17,8 @@ import { defineCapabilityHealth } from "@pithy-sh/core/src/controlPlane/discover
|
|
|
16
17
|
const AUDIT_SHIP_BACKLOG = "auditShipBacklog";
|
|
17
18
|
/** Events given up on, across every sink: their last retry failed and they went to the dead-letter queue. */
|
|
18
19
|
const AUDIT_SHIP_DEAD_LETTERED = "auditShipDeadLettered";
|
|
19
|
-
/** How delivery stands, across every sink. */
|
|
20
|
+
/** How delivery stands, across every sink: {@link shipDelivery} over every declared sink's row. */
|
|
20
21
|
const AUDIT_SHIP_DELIVERY = "auditShipDelivery";
|
|
21
|
-
/**
|
|
22
|
-
* The values {@link AUDIT_SHIP_DELIVERY} takes. `failing` when any sink's last attempt failed; `delivering` when
|
|
23
|
-
* every sink that has been attempted last took a delivery; `idle` when no sink has been attempted yet.
|
|
24
|
-
*/
|
|
25
|
-
const SHIP_DELIVERY_STATES = [
|
|
26
|
-
"delivering",
|
|
27
|
-
"failing",
|
|
28
|
-
"idle"
|
|
29
|
-
];
|
|
30
|
-
/** How delivery stands, from the declared sinks' rows. */
|
|
31
|
-
function shipDelivery(states) {
|
|
32
|
-
const attempted = states.filter((state) => state.lastDeliveredAt !== null || state.lastFailedAt !== null);
|
|
33
|
-
if (attempted.length === 0) return "idle";
|
|
34
|
-
return attempted.some((state) => state.lastFailedAt !== null && (state.lastDeliveredAt === null || state.lastFailedAt > state.lastDeliveredAt)) ? "failing" : "delivering";
|
|
35
|
-
}
|
|
36
22
|
/** Declare shipping's health keys over the declared sinks. */
|
|
37
23
|
function shipHealth(sinks, database) {
|
|
38
24
|
const names = Object.keys(sinks);
|
|
@@ -77,4 +63,4 @@ function shipHealth(sinks, database) {
|
|
|
77
63
|
});
|
|
78
64
|
}
|
|
79
65
|
//#endregion
|
|
80
|
-
export { AUDIT_SHIP_BACKLOG, AUDIT_SHIP_DEAD_LETTERED, AUDIT_SHIP_DELIVERY,
|
|
66
|
+
export { AUDIT_SHIP_BACKLOG, AUDIT_SHIP_DEAD_LETTERED, AUDIT_SHIP_DELIVERY, shipHealth };
|
|
@@ -3,5 +3,5 @@
|
|
|
3
3
|
/** This package's npm name — the join key against a release feed. */
|
|
4
4
|
export declare const PACKAGE_NAME = "@pithy-sh/audit";
|
|
5
5
|
/** This package's version, stamped from its own package.json at generation time. */
|
|
6
|
-
export declare const PACKAGE_VERSION = "0.
|
|
6
|
+
export declare const PACKAGE_VERSION = "0.8.0";
|
|
7
7
|
//# sourceMappingURL=version.generated.d.ts.map
|
|
@@ -4,6 +4,6 @@
|
|
|
4
4
|
/** This package's npm name — the join key against a release feed. */
|
|
5
5
|
const PACKAGE_NAME = "@pithy-sh/audit";
|
|
6
6
|
/** This package's version, stamped from its own package.json at generation time. */
|
|
7
|
-
const PACKAGE_VERSION = "0.
|
|
7
|
+
const PACKAGE_VERSION = "0.8.0";
|
|
8
8
|
//#endregion
|
|
9
9
|
export { PACKAGE_NAME, PACKAGE_VERSION };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pithy-sh/audit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.0",
|
|
4
4
|
"license": "FSL-1.1-MIT",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -38,8 +38,8 @@
|
|
|
38
38
|
"@hono/zod-validator": "^0.9.0"
|
|
39
39
|
},
|
|
40
40
|
"peerDependencies": {
|
|
41
|
-
"@pithy-sh/core": "^0.
|
|
42
|
-
"@pithy-sh/secrets": "^0.6.
|
|
41
|
+
"@pithy-sh/core": "^0.16.0",
|
|
42
|
+
"@pithy-sh/secrets": "^0.6.4",
|
|
43
43
|
"hono": "^4.13.2",
|
|
44
44
|
"kysely": "^0.29.0",
|
|
45
45
|
"zod": "^4.4.0"
|
package/src/capability.ts
CHANGED
|
@@ -49,7 +49,7 @@ export const AUDIT_MIGRATION_ORDER = 250;
|
|
|
49
49
|
* database (`app`, the `DB` binding) by default — so the audit migration tracks alongside the app's
|
|
50
50
|
* in one `pithy_migrations` table rather than fighting it on a second provider over the same binding.
|
|
51
51
|
* The physical binding is config-selectable; this registry key is the coordination point capabilities
|
|
52
|
-
* use to share one database (CLAUDE.md §Data layer
|
|
52
|
+
* use to share one database (CLAUDE.md §Data layer).
|
|
53
53
|
*/
|
|
54
54
|
const AUDIT_DATABASE_NAME = "app" as const;
|
|
55
55
|
|
|
@@ -89,7 +89,7 @@ export type AuditConfigInput = z.input<typeof AuditConfig>;
|
|
|
89
89
|
export interface AuditCapability extends Capability {
|
|
90
90
|
/** The D1 binding the audit table lives in (the resolved `database` config). */
|
|
91
91
|
auditDatabase: string;
|
|
92
|
-
/** The sinks the trail ships to
|
|
92
|
+
/** The sinks the trail ships to, as declared — what `pithy doctor` lists. */
|
|
93
93
|
auditSinks: AuditSinks;
|
|
94
94
|
}
|
|
95
95
|
|
|
@@ -103,7 +103,7 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
103
103
|
const resolved = AuditConfig.parse(config);
|
|
104
104
|
const sinks = resolved.sinks;
|
|
105
105
|
const ships = Object.keys(sinks).length > 0;
|
|
106
|
-
// The tokens each sink reads, declared on audit's own slice
|
|
106
|
+
// The tokens each sink reads, declared on audit's own slice; empty, and not declared, when nothing ships.
|
|
107
107
|
const sinkSecrets = sinkSecretsRegistry(sinks);
|
|
108
108
|
const databaseOf = (c: { var: { db: unknown } }) =>
|
|
109
109
|
(c.var.db as Record<typeof AUDIT_DATABASE_NAME, AuditDatabase>)[AUDIT_DATABASE_NAME];
|
|
@@ -112,16 +112,14 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
112
112
|
let adminRoutes: readonly AdminRoute[] = auditAdminRoutes(resolved.basePath);
|
|
113
113
|
const capability = defineCapability({
|
|
114
114
|
name: "audit",
|
|
115
|
-
//
|
|
116
|
-
//
|
|
117
|
-
// the control-plane manifest, and reported together: a release feed is keyed by package name, so the
|
|
118
|
-
// version alone leaves a client guessing the key (#626).
|
|
115
|
+
// Stamped by `scripts/stampVersions.ts`: a Worker cannot read its own package.json. Reported together, because a
|
|
116
|
+
// release feed is keyed by package name and the version alone leaves a client guessing the key.
|
|
119
117
|
version: PACKAGE_VERSION,
|
|
120
118
|
package: PACKAGE_NAME,
|
|
121
119
|
config: AuditConfig,
|
|
122
120
|
requiredBindings: [
|
|
123
121
|
{ type: "d1", name: resolved.database },
|
|
124
|
-
// The checkpoint bucket
|
|
122
|
+
// The checkpoint bucket: each tenant chain's head and count, written on a schedule by the checkpoint
|
|
125
123
|
// host and read back by the verify and export routes. Optional, so a Worker not yet provisioned still records
|
|
126
124
|
// every event and still verifies links — it says so, as `checkpointStore: "absent"`.
|
|
127
125
|
{ type: "r2", name: AUDIT_CHECKPOINT_BINDING, optional: true },
|
|
@@ -130,12 +128,12 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
130
128
|
...workflowBindings(auditWorkflows),
|
|
131
129
|
// The retention prune's binding: optional, and bound by the adopter to the class their own Worker exports.
|
|
132
130
|
...workflowBindings(auditAppWorkflows),
|
|
133
|
-
// The shipping queue and its dead-letter queue
|
|
131
|
+
// The shipping queue and its dead-letter queue, only when a sink is declared: Cloudflare Queues needs
|
|
134
132
|
// the Workers Paid plan, so a project that ships nothing binds neither. Required when declared — a sink that
|
|
135
133
|
// could never be enqueued to is a config that does not do what it says.
|
|
136
134
|
...shipBindings(sinks),
|
|
137
135
|
],
|
|
138
|
-
// A sink's token is read through `@pithy-sh/secrets`, so a Worker that ships needs it composed
|
|
136
|
+
// A sink's token is read through `@pithy-sh/secrets`, so a Worker that ships needs it composed.
|
|
139
137
|
...(ships
|
|
140
138
|
? {
|
|
141
139
|
dependsOn: ["secrets"],
|
|
@@ -162,10 +160,10 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
162
160
|
}),
|
|
163
161
|
}
|
|
164
162
|
: {}),
|
|
165
|
-
// The checkpoint job
|
|
163
|
+
// The checkpoint job, hosted by the prebuilt audit worker and fired hourly from its cron.
|
|
166
164
|
// And the retention prune, hosted by the adopter's own Worker and fired daily from its cron.
|
|
167
165
|
workflows: { ...auditWorkflows, ...auditAppWorkflows },
|
|
168
|
-
// `pithy doctor` says whether object lock is in force on each deployed environment's checkpoint bucket
|
|
166
|
+
// `pithy doctor` says whether object lock is in force on each deployed environment's checkpoint bucket.
|
|
169
167
|
settings: checkpointLockCheck(),
|
|
170
168
|
databases: {
|
|
171
169
|
[AUDIT_DATABASE_NAME]: {
|
|
@@ -184,9 +182,9 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
184
182
|
},
|
|
185
183
|
seeds: [auditExampleSeed],
|
|
186
184
|
// Every event where a person is the actor is kept through their purge, as the record of who acted, and exported
|
|
187
|
-
// on an access request with the basis that keeps it
|
|
185
|
+
// on an access request with the basis that keeps it.
|
|
188
186
|
purge: [auditUserPurge(resolved.database)],
|
|
189
|
-
// The same recorder for code with no request — a Workflow step, which has `env` and nothing else
|
|
187
|
+
// The same recorder for code with no request — a Workflow step, which has `env` and nothing else.
|
|
190
188
|
// Built over the binding this config names, stamped with the env's own origin, and non-fatal on the same
|
|
191
189
|
// terms as the middleware's: a missing binding or a failed insert drops the event and logs it, and the
|
|
192
190
|
// step it records stands. Found by core's `composedAuditEmit`, so the step imports nothing from here.
|
|
@@ -206,14 +204,14 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
206
204
|
});
|
|
207
205
|
};
|
|
208
206
|
},
|
|
209
|
-
// Where a resource's events sit in their chains, for the control plane's erasure attestation
|
|
207
|
+
// Where a resource's events sit in their chains, for the control plane's erasure attestation. Found by
|
|
210
208
|
// core's `composedAuditCitations`, so the attestation imports nothing from here.
|
|
211
209
|
auditCitations: auditCitationsFor(resolved.database),
|
|
212
210
|
// Built from the resolved `basePath`, never the default: an adopter who mounts this at `/trail`
|
|
213
211
|
// gets a manifest naming their paths, where a client assuming the default would 404.
|
|
214
212
|
adminRoutes: auditAdminRoutes(resolved.basePath),
|
|
215
213
|
// The manifest's routes, gathered once at startup: a credential's reach groups the paths it called by the routes
|
|
216
|
-
// this Worker declares
|
|
214
|
+
// this Worker declares, and only `compose` sees every capability.
|
|
217
215
|
compose: ({ capabilities }) => {
|
|
218
216
|
adminRoutes = capabilities.flatMap((capability) => capability.adminRoutes ?? []);
|
|
219
217
|
},
|
|
@@ -228,13 +226,14 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
228
226
|
const bucket = (c.env as Record<string, unknown> | undefined)?.[AUDIT_CHECKPOINT_BINDING];
|
|
229
227
|
return typeof bucket === "object" && bucket !== null ? (bucket as R2Bucket) : null;
|
|
230
228
|
},
|
|
229
|
+
sinks,
|
|
231
230
|
}),
|
|
232
231
|
// Replace the no-op `emit` seam with a recorder over this request's audit database. The database
|
|
233
232
|
// is resolved lazily inside the closure — only when a route actually emits — so a request that
|
|
234
233
|
// never audits never triggers the lazy Kysely build. Runs after createBackend's default-setter
|
|
235
234
|
// (which seeds `db`, `log`, and the no-op `emit`), so `c.var.db` and `c.var.log` are ready by the
|
|
236
|
-
// time emit is called. A non-fatal write failure routes through the logger seam
|
|
237
|
-
//
|
|
235
|
+
// time emit is called. A non-fatal write failure routes through the logger seam as a namespaced
|
|
236
|
+
// `audit/*` record on the `audit` sub-logger.
|
|
238
237
|
middleware: [
|
|
239
238
|
(app) => {
|
|
240
239
|
app.use("*", async (c, next) => {
|
|
@@ -244,7 +243,7 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
244
243
|
// context. `workerIdentity` never throws and returns nulls for whatever is unstamped, so a
|
|
245
244
|
// Worker predating these vars still records its events — just without an origin.
|
|
246
245
|
// The parameter is annotated: `AuditEmit` is generic over `metadata` so a call site carrying a
|
|
247
|
-
// privacy-marked value fails to compile
|
|
246
|
+
// privacy-marked value fails to compile, and the recorder is the one place every event lands.
|
|
248
247
|
const ship = shipperFor(c.env as Record<string, unknown> | undefined, sinks);
|
|
249
248
|
const onShipError = (error: unknown) =>
|
|
250
249
|
c.var.log.child("audit").error("audit shipment not enqueued", { error });
|
|
@@ -252,7 +251,7 @@ export function audit(config: AuditConfigInput = {}): AuditCapability {
|
|
|
252
251
|
recordAuditEvent(databaseOf(c), event, {
|
|
253
252
|
origin: workerIdentity(c.env),
|
|
254
253
|
onError: (error) => c.var.log.child("audit").error("audit event dropped", { error }),
|
|
255
|
-
// Enqueued after the response where the runtime allows it
|
|
254
|
+
// Enqueued after the response where the runtime allows it, so shipping never holds the
|
|
256
255
|
// request it records; awaited only where there is no execution context to hand it to.
|
|
257
256
|
...(ship
|
|
258
257
|
? {
|
package/src/http/guards.ts
CHANGED
|
@@ -55,6 +55,10 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
|
|
|
55
55
|
* already names in `resourceId`, and the tenant is what it shows as `tenant`; the answer never carries an IP, a user-agent, or a metadata key beyond the key id, scope, method and
|
|
56
56
|
* path. So a breach review does not need the detail scope to draw a breach scope.
|
|
57
57
|
*
|
|
58
|
+
* **The sinks ride the listing scope.** `GET {base}/control-plane/sinks` answers each declared sink's name, profile,
|
|
59
|
+
* host, filter and delivery state — what the manifest's health keys already total behind the same scope. It never
|
|
60
|
+
* carries a token, a secret name, a URL path or query, an event, or anything a receiver answered.
|
|
61
|
+
*
|
|
58
62
|
* **The chain has a scope of its own.** `GET {base}/control-plane/verify` walks one tenant's chain, and
|
|
59
63
|
* `GET {base}/control-plane/export` takes it out in canonical form with its checkpoints. An export is the trail in
|
|
60
64
|
* bulk, meant to leave the building, so neither read rides the listing scope: both need `audit:events:export`. The
|
|
@@ -166,6 +170,15 @@ export function auditAdminRoutes(basePath: string): AdminRouteDeclaration[] {
|
|
|
166
170
|
summary:
|
|
167
171
|
"Export one tenant's hash chain in canonical form with its checkpoints, to verify offline. Personal values only with the detail scope.",
|
|
168
172
|
},
|
|
173
|
+
{
|
|
174
|
+
method: "GET",
|
|
175
|
+
operation: "sinks.list",
|
|
176
|
+
path: `${basePath}/control-plane/sinks`,
|
|
177
|
+
scope: AUDIT_TRAIL_READ_SCOPE,
|
|
178
|
+
kind: "reads",
|
|
179
|
+
summary:
|
|
180
|
+
"List every sink the trail ships to, with its profile, host and filter, and its backlog, last delivery and dead letters. No event is read.",
|
|
181
|
+
},
|
|
169
182
|
{
|
|
170
183
|
method: "GET",
|
|
171
184
|
operation: "events.read",
|
package/src/http/responses.ts
CHANGED
|
@@ -5,6 +5,8 @@ import { AuditActorType, AuditMetadata, AuditOutcome, AuditSeverity } from "@pit
|
|
|
5
5
|
import { AuditChainExport, ChainBreak, ChainLink } from "@pithy-sh/core/src/audit/chain";
|
|
6
6
|
import { ControlPlaneActorKind } from "@pithy-sh/core/src/controlPlane/data/connection";
|
|
7
7
|
import { z } from "zod";
|
|
8
|
+
import { SHIP_DELIVERY_STATES } from "../ship/delivery";
|
|
9
|
+
import { AuditSinkProfile } from "../ship/sinks";
|
|
8
10
|
|
|
9
11
|
/**
|
|
10
12
|
* What the audit routes return, as Zod objects a management client can validate against.
|
|
@@ -421,3 +423,65 @@ export const ChainExportResponse = AuditChainExport.describe(
|
|
|
421
423
|
"One page of one tenant's audit chain: canonical events, their hashes, the link before them and the checkpoints covering them.",
|
|
422
424
|
);
|
|
423
425
|
export type ChainExportResponse = z.output<typeof ChainExportResponse>;
|
|
426
|
+
|
|
427
|
+
/** One declared sink, as `GET {base}/control-plane/sinks` shows it. Never its URL path, its query or its token. */
|
|
428
|
+
export const AuditSinkView = z
|
|
429
|
+
.object({
|
|
430
|
+
name: z.string().describe("The sink's name, as `audit({ sinks })` declares it."),
|
|
431
|
+
profile: AuditSinkProfile.describe(
|
|
432
|
+
"The format the sink is delivered in: `splunk-hec`, `datadog-logs` or `webhook`.",
|
|
433
|
+
),
|
|
434
|
+
host: z
|
|
435
|
+
.string()
|
|
436
|
+
.describe(
|
|
437
|
+
"The host the sink posts to, with its port when the URL names one. Never the path or query, which may carry a key.",
|
|
438
|
+
),
|
|
439
|
+
detail: z
|
|
440
|
+
.boolean()
|
|
441
|
+
.describe(
|
|
442
|
+
"Whether the sink receives each event's IP, user-agent and metadata values, rather than their salted hashes.",
|
|
443
|
+
),
|
|
444
|
+
actions: z
|
|
445
|
+
.array(z.string().describe("An action prefix the sink takes, e.g. `auth/`."))
|
|
446
|
+
.nullable()
|
|
447
|
+
.describe("The action prefixes the sink takes, or null when it takes every action the trail records."),
|
|
448
|
+
lastDeliveredAt: z.iso
|
|
449
|
+
.datetime()
|
|
450
|
+
.nullable()
|
|
451
|
+
.describe("When the sink last accepted a delivery, ISO-8601, or null when it never has."),
|
|
452
|
+
lastFailedAt: z.iso
|
|
453
|
+
.datetime()
|
|
454
|
+
.nullable()
|
|
455
|
+
.describe("When the sink last refused a delivery or could not be reached, ISO-8601, or null when it never has."),
|
|
456
|
+
retrying: z
|
|
457
|
+
.number()
|
|
458
|
+
.int()
|
|
459
|
+
.nonnegative()
|
|
460
|
+
.describe(
|
|
461
|
+
"How many events are waiting on a retry to this sink: its backlog. The manifest's `auditShipBacklog` is the sum over every sink.",
|
|
462
|
+
),
|
|
463
|
+
deadLettered: z
|
|
464
|
+
.number()
|
|
465
|
+
.int()
|
|
466
|
+
.nonnegative()
|
|
467
|
+
.describe(
|
|
468
|
+
"How many events this sink never took: their retries ran out and they went to the dead-letter queue. The manifest's `auditShipDeadLettered` is the sum.",
|
|
469
|
+
),
|
|
470
|
+
delivery: z
|
|
471
|
+
.enum(SHIP_DELIVERY_STATES)
|
|
472
|
+
.describe(
|
|
473
|
+
"How delivery to this sink stands: `failing` when its last attempt failed, `delivering` when it last took one, `idle` when it has never been attempted.",
|
|
474
|
+
),
|
|
475
|
+
})
|
|
476
|
+
.describe("One sink the trail ships to: where, what it takes, and how delivery to it stands.");
|
|
477
|
+
export type AuditSinkView = z.output<typeof AuditSinkView>;
|
|
478
|
+
|
|
479
|
+
/** `GET {base}/control-plane/sinks`. */
|
|
480
|
+
export const AuditSinksResponse = z
|
|
481
|
+
.object({
|
|
482
|
+
sinks: z
|
|
483
|
+
.array(AuditSinkView)
|
|
484
|
+
.describe("Every declared sink, in declaration order. Empty when the Worker ships nothing."),
|
|
485
|
+
})
|
|
486
|
+
.describe("Every sink the trail ships to, each with its backlog, last delivery and dead letters.");
|
|
487
|
+
export type AuditSinksResponse = z.output<typeof AuditSinksResponse>;
|
package/src/http/routes.ts
CHANGED
|
@@ -19,12 +19,15 @@ import type { AuditDatabase } from "../data/tables";
|
|
|
19
19
|
import { pageAuditEvents, readAuditEvent } from "../query";
|
|
20
20
|
import { controlPlaneReach, controlPlaneReachSubjects } from "../reach";
|
|
21
21
|
import { reachPatterns } from "../routePattern";
|
|
22
|
+
import type { AuditSinks } from "../ship/sinks";
|
|
23
|
+
import { readSinkStates } from "../ship/state";
|
|
22
24
|
import { controlPlaneUsage } from "../usage";
|
|
23
25
|
import { AUDIT_CHAIN_EXPORT_SCOPE, AUDIT_EVENT_DETAIL_READ_SCOPE, AUDIT_TRAIL_READ_SCOPE } from "./guards";
|
|
24
26
|
import {
|
|
25
27
|
AccessHistoryResponse,
|
|
26
28
|
AuditEventResponse,
|
|
27
29
|
AuditEventsResponse,
|
|
30
|
+
AuditSinksResponse,
|
|
28
31
|
ChainExportResponse,
|
|
29
32
|
ChainVerifyResponse,
|
|
30
33
|
ControlPlaneReachResponse,
|
|
@@ -43,6 +46,7 @@ import {
|
|
|
43
46
|
accessChangeView,
|
|
44
47
|
auditEventDetailView,
|
|
45
48
|
auditEventView,
|
|
49
|
+
auditSinkViews,
|
|
46
50
|
controlPlaneReachSubjectView,
|
|
47
51
|
controlPlaneReachView,
|
|
48
52
|
controlPlaneUsageView,
|
|
@@ -63,9 +67,11 @@ import {
|
|
|
63
67
|
* (control-plane: audit:events:export) query: ChainVerifyQuery
|
|
64
68
|
* GET /audit/control-plane/export → one tenant's chain in canonical form, with its checkpoints
|
|
65
69
|
* (control-plane: audit:events:export) query: ChainExportQuery
|
|
70
|
+
* GET /audit/control-plane/sinks → every declared sink and how delivery to it stands
|
|
71
|
+
* (control-plane: audit:events:read) no input
|
|
66
72
|
*
|
|
67
73
|
* **All are reads, and there is nothing else.** The trail is append-only: no route here deletes,
|
|
68
|
-
* edits, or prunes, because a management credential that could erase an audit row could erase the
|
|
74
|
+
* edits, or prunes, and no route adds, changes or removes a sink, because a management credential that could erase an audit row could erase the
|
|
69
75
|
* evidence of its own use. Retention is a lifecycle concern for a Workflow, not a button on a
|
|
70
76
|
* dashboard.
|
|
71
77
|
*
|
|
@@ -106,6 +112,7 @@ export const AUDIT_ROUTES: readonly AuditRouteDeclaration[] = [
|
|
|
106
112
|
{ method: "GET", path: "/control-plane/usage", strategy: "control-plane", scope: AUDIT_TRAIL_READ_SCOPE },
|
|
107
113
|
{ method: "GET", path: "/control-plane/verify", strategy: "control-plane", scope: AUDIT_CHAIN_EXPORT_SCOPE },
|
|
108
114
|
{ method: "GET", path: "/control-plane/export", strategy: "control-plane", scope: AUDIT_CHAIN_EXPORT_SCOPE },
|
|
115
|
+
{ method: "GET", path: "/control-plane/sinks", strategy: "control-plane", scope: AUDIT_TRAIL_READ_SCOPE },
|
|
109
116
|
];
|
|
110
117
|
|
|
111
118
|
/** How the audit sub-router is built. */
|
|
@@ -125,10 +132,12 @@ export interface AuditRoutesOptions {
|
|
|
125
132
|
*/
|
|
126
133
|
adminRoutes: () => readonly AdminRoute[];
|
|
127
134
|
/**
|
|
128
|
-
* The checkpoint bucket for this request, or null when the Worker binds none
|
|
135
|
+
* The checkpoint bucket for this request, or null when the Worker binds none. Absent, verify checks links
|
|
129
136
|
* alone and says so, and an export carries no checkpoints.
|
|
130
137
|
*/
|
|
131
138
|
checkpoints?: (c: Context<PithyHonoEnv>) => R2Bucket | null;
|
|
139
|
+
/** The sinks the trail ships to, as declared. Absent, the sinks read answers an empty list. */
|
|
140
|
+
sinks?: AuditSinks;
|
|
132
141
|
}
|
|
133
142
|
|
|
134
143
|
/**
|
|
@@ -178,6 +187,7 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
178
187
|
const database = options.database;
|
|
179
188
|
const adminRoutes = options.adminRoutes;
|
|
180
189
|
const checkpoints = options.checkpoints ?? (() => null);
|
|
190
|
+
const sinks = options.sinks ?? {};
|
|
181
191
|
|
|
182
192
|
return (app) => {
|
|
183
193
|
/**
|
|
@@ -273,7 +283,7 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
273
283
|
);
|
|
274
284
|
|
|
275
285
|
/**
|
|
276
|
-
* CONTROL-PLANE READ
|
|
286
|
+
* CONTROL-PLANE READ. Who could do what, over time: every membership, connection and key change in a
|
|
277
287
|
* window, oldest first, with its before and after — one SQL statement per page, never a walk of events here.
|
|
278
288
|
* Behind the listing scope, not the detail one: it lifts named metadata keys and never an IP or a user-agent.
|
|
279
289
|
*/
|
|
@@ -328,7 +338,7 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
328
338
|
);
|
|
329
339
|
|
|
330
340
|
/**
|
|
331
|
-
* CONTROL-PLANE READ
|
|
341
|
+
* CONTROL-PLANE READ. What one credential reached — by tenant, action, method, route and outcome — over a
|
|
332
342
|
* window, in one SQL statement, never by paging events here. `subjects=true` expands one route into the subject
|
|
333
343
|
* ids its called paths name. Behind the listing scope, not the detail one: the answer is the tenant, the route,
|
|
334
344
|
* the scope and ids the listing already shows, and never an IP, a user-agent or any other metadata key.
|
|
@@ -401,7 +411,7 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
401
411
|
);
|
|
402
412
|
|
|
403
413
|
/**
|
|
404
|
-
* CONTROL-PLANE READ
|
|
414
|
+
* CONTROL-PLANE READ. Which scopes one connection exercised and was refused, by key, over a window —
|
|
405
415
|
* counted in one SQL statement, never by paging events here. Behind the listing scope, not the detail one: the
|
|
406
416
|
* answer is the scope, the key, and the last allowed call's method and path, and never an IP, a user-agent or any
|
|
407
417
|
* other metadata key.
|
|
@@ -457,7 +467,7 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
457
467
|
);
|
|
458
468
|
|
|
459
469
|
/**
|
|
460
|
-
* CONTROL-PLANE READ
|
|
470
|
+
* CONTROL-PLANE READ. Walk one tenant's hash chain over a window — every link, every hash, the
|
|
461
471
|
* checkpoints covering it — and answer intact or the first break. Reads only: it proves the trail whole and
|
|
462
472
|
* changes nothing.
|
|
463
473
|
*/
|
|
@@ -526,7 +536,7 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
526
536
|
);
|
|
527
537
|
|
|
528
538
|
/**
|
|
529
|
-
* CONTROL-PLANE READ
|
|
539
|
+
* CONTROL-PLANE READ. One page of one tenant's chain in canonical form, each event with its hash, the
|
|
530
540
|
* link before the page and the checkpoints covering it — what `pithy audit verify` checks offline. The IP,
|
|
531
541
|
* user-agent and metadata values ride along only when the connection also holds the detail scope.
|
|
532
542
|
*/
|
|
@@ -586,5 +596,25 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
586
596
|
return c.json(page satisfies ChainExportResponse, 200);
|
|
587
597
|
},
|
|
588
598
|
);
|
|
599
|
+
|
|
600
|
+
/**
|
|
601
|
+
* CONTROL-PLANE READ. Every declared sink beside its own delivery row: one primary-key lookup per sink, bounded
|
|
602
|
+
* by the config. Not audited, unlike the trail's reads: it reads delivery state, never the trail, and a pane
|
|
603
|
+
* polling it would otherwise append to the trail, and ship to every sink, on each poll.
|
|
604
|
+
*/
|
|
605
|
+
app.get(
|
|
606
|
+
`${base}/control-plane/sinks`,
|
|
607
|
+
describeRoute({
|
|
608
|
+
summary: "List every sink the trail ships to, each with its backlog, last delivery and dead letters.",
|
|
609
|
+
verification: "control-plane",
|
|
610
|
+
scopes: [AUDIT_TRAIL_READ_SCOPE],
|
|
611
|
+
responses: { 200: AuditSinksResponse },
|
|
612
|
+
}),
|
|
613
|
+
requireControlPlane(AUDIT_TRAIL_READ_SCOPE),
|
|
614
|
+
async (c) => {
|
|
615
|
+
const states = await readSinkStates(database(c), Object.keys(sinks));
|
|
616
|
+
return c.json({ sinks: auditSinkViews(sinks, states) } satisfies AuditSinksResponse, 200);
|
|
617
|
+
},
|
|
618
|
+
);
|
|
589
619
|
};
|
|
590
620
|
}
|
package/src/http/views.ts
CHANGED
|
@@ -4,12 +4,16 @@
|
|
|
4
4
|
import { InternalError } from "@pithy-sh/core/src/error/pithyError";
|
|
5
5
|
import type { AccessHistoryRow } from "../accessHistory";
|
|
6
6
|
import type { AuditEventRow } from "../data/auditEvent";
|
|
7
|
+
import type { AuditSinkStateRow } from "../data/sinkState";
|
|
7
8
|
import type { ControlPlaneReachRow, ControlPlaneReachSubjectRow } from "../reach";
|
|
9
|
+
import { shipDelivery } from "../ship/delivery";
|
|
10
|
+
import type { AuditSinks } from "../ship/sinks";
|
|
8
11
|
import type { ControlPlaneUsageRow } from "../usage";
|
|
9
12
|
import type {
|
|
10
13
|
AccessChangeView,
|
|
11
14
|
AuditEventDetailView,
|
|
12
15
|
AuditEventView,
|
|
16
|
+
AuditSinkView,
|
|
13
17
|
ControlPlaneReachSubjectView,
|
|
14
18
|
ControlPlaneReachView,
|
|
15
19
|
ControlPlaneUsageView,
|
|
@@ -89,7 +93,7 @@ export function auditEventView(row: AuditEventRow): AuditEventView {
|
|
|
89
93
|
// not personal data — and a client that can filter by tenant but cannot see which tenant a row
|
|
90
94
|
// carries has to take the filter on trust, which is how a row ends up drawn under the wrong heading.
|
|
91
95
|
tenant: row.tenant,
|
|
92
|
-
// Its position in its tenant's chain, or null: written before the chain began
|
|
96
|
+
// Its position in its tenant's chain, or null: written before the chain began. The mark, on the listing.
|
|
93
97
|
chainSeq: row.chainSeq,
|
|
94
98
|
};
|
|
95
99
|
}
|
|
@@ -100,7 +104,7 @@ export function auditEventDetailView(row: AuditEventRow): AuditEventDetailView {
|
|
|
100
104
|
}
|
|
101
105
|
|
|
102
106
|
/**
|
|
103
|
-
* Project one access change
|
|
107
|
+
* Project one access change into the wire union, by what changed.
|
|
104
108
|
*
|
|
105
109
|
* The statement already read nothing but the named metadata keys, so this drops nothing personal; what it does is
|
|
106
110
|
* keep each subject's fields to that subject, so a member change never carries a null `scopesBefore` a client could
|
|
@@ -152,7 +156,7 @@ export function accessChangeView(row: AccessHistoryRow): AccessChangeView {
|
|
|
152
156
|
}
|
|
153
157
|
|
|
154
158
|
/**
|
|
155
|
-
* Project one reach row
|
|
159
|
+
* Project one reach row. Field for field, with the instants as ISO-8601: the statement already read nothing
|
|
156
160
|
* but the scope, the key, the method and the path out of `metadata`, and the tenant out of the handler's events, so
|
|
157
161
|
* there is nothing here to drop.
|
|
158
162
|
*/
|
|
@@ -172,7 +176,7 @@ export function controlPlaneReachView(row: ControlPlaneReachRow): ControlPlaneRe
|
|
|
172
176
|
};
|
|
173
177
|
}
|
|
174
178
|
|
|
175
|
-
/** Project one subject row
|
|
179
|
+
/** Project one subject row, field for field, the same way — never a spread a new field would ride out on. */
|
|
176
180
|
export function controlPlaneReachSubjectView(row: ControlPlaneReachSubjectRow): ControlPlaneReachSubjectView {
|
|
177
181
|
return {
|
|
178
182
|
tenant: row.tenant,
|
|
@@ -192,7 +196,7 @@ export function controlPlaneReachSubjectView(row: ControlPlaneReachSubjectRow):
|
|
|
192
196
|
}
|
|
193
197
|
|
|
194
198
|
/**
|
|
195
|
-
* Project one usage row
|
|
199
|
+
* Project one usage row. Field for field, with the instants as ISO-8601: the aggregate already read nothing but
|
|
196
200
|
* the scope, the key, and the last allowed call's method and path out of `metadata`, so there is nothing here to drop.
|
|
197
201
|
*/
|
|
198
202
|
export function controlPlaneUsageView(row: ControlPlaneUsageRow): ControlPlaneUsageView {
|
|
@@ -207,3 +211,35 @@ export function controlPlaneUsageView(row: ControlPlaneUsageRow): ControlPlaneUs
|
|
|
207
211
|
lastDeniedAt: row.lastDeniedAt?.toISOString() ?? null,
|
|
208
212
|
};
|
|
209
213
|
}
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* Project the declared sinks, in declaration order, each beside its own state row. A sink with no row has never been
|
|
217
|
+
* attempted and answers null times, zero counts and `idle`; a row whose sink is no longer declared is not answered.
|
|
218
|
+
*
|
|
219
|
+
* Named fields, never a spread of the config: a sink's URL path and query may carry a key, and its secret name says
|
|
220
|
+
* where its token lives, so neither leaves. The host is the URL's host and port, as `pithy doctor` prints it.
|
|
221
|
+
*/
|
|
222
|
+
export function auditSinkViews(sinks: AuditSinks, states: readonly AuditSinkStateRow[]): AuditSinkView[] {
|
|
223
|
+
const byName = new Map(states.map((state) => [state.sink, state]));
|
|
224
|
+
return Object.entries(sinks).map(([name, sink]) => {
|
|
225
|
+
const state = byName.get(name) ?? {
|
|
226
|
+
sink: name,
|
|
227
|
+
lastDeliveredAt: null,
|
|
228
|
+
lastFailedAt: null,
|
|
229
|
+
retrying: 0,
|
|
230
|
+
deadLettered: 0,
|
|
231
|
+
};
|
|
232
|
+
return {
|
|
233
|
+
name,
|
|
234
|
+
profile: sink.profile,
|
|
235
|
+
host: new URL(sink.url).host,
|
|
236
|
+
detail: sink.detail,
|
|
237
|
+
actions: sink.actions === undefined ? null : [...sink.actions],
|
|
238
|
+
lastDeliveredAt: state.lastDeliveredAt?.toISOString() ?? null,
|
|
239
|
+
lastFailedAt: state.lastFailedAt?.toISOString() ?? null,
|
|
240
|
+
retrying: state.retrying,
|
|
241
|
+
deadLettered: state.deadLettered,
|
|
242
|
+
delivery: shipDelivery([state]),
|
|
243
|
+
};
|
|
244
|
+
});
|
|
245
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: FSL-1.1-MIT
|
|
3
|
+
|
|
4
|
+
import type { AuditSinkStateRow } from "../data/sinkState";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The values a delivery state takes: per sink on the sinks read, and across every sink on the manifest's
|
|
8
|
+
* `auditShipDelivery`. `failing` when any sink's last attempt failed; `delivering` when every sink that has been
|
|
9
|
+
* attempted last took a delivery; `idle` when no sink has been attempted yet.
|
|
10
|
+
*/
|
|
11
|
+
export const SHIP_DELIVERY_STATES = ["delivering", "failing", "idle"] as const;
|
|
12
|
+
export type ShipDeliveryState = (typeof SHIP_DELIVERY_STATES)[number];
|
|
13
|
+
|
|
14
|
+
/** How delivery stands, from the given sinks' rows: one sink's for its own state, every declared sink's for the total. */
|
|
15
|
+
export function shipDelivery(states: readonly AuditSinkStateRow[]): ShipDeliveryState {
|
|
16
|
+
const attempted = states.filter((state) => state.lastDeliveredAt !== null || state.lastFailedAt !== null);
|
|
17
|
+
if (attempted.length === 0) return "idle";
|
|
18
|
+
const failing = attempted.some(
|
|
19
|
+
(state) =>
|
|
20
|
+
state.lastFailedAt !== null && (state.lastDeliveredAt === null || state.lastFailedAt > state.lastDeliveredAt),
|
|
21
|
+
);
|
|
22
|
+
return failing ? "failing" : "delivering";
|
|
23
|
+
}
|
package/src/ship/health.ts
CHANGED
|
@@ -4,14 +4,14 @@
|
|
|
4
4
|
import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
|
|
5
5
|
import { type CapabilityHealth, defineCapabilityHealth } from "@pithy-sh/core/src/controlPlane/discovery/health";
|
|
6
6
|
import type { Context } from "hono";
|
|
7
|
-
import type { AuditSinkStateRow } from "../data/sinkState";
|
|
8
7
|
import type { AuditDatabase } from "../data/tables";
|
|
9
8
|
import { AUDIT_TRAIL_READ_SCOPE } from "../http/guards";
|
|
9
|
+
import { SHIP_DELIVERY_STATES, shipDelivery } from "./delivery";
|
|
10
10
|
import type { AuditSinks } from "./sinks";
|
|
11
11
|
import { readSinkStates } from "./state";
|
|
12
12
|
|
|
13
13
|
/**
|
|
14
|
-
* **Shipping's health, on audit's manifest entry
|
|
14
|
+
* **Shipping's health, on audit's manifest entry** — whether the trail is reaching its sinks.
|
|
15
15
|
*
|
|
16
16
|
* Three keys, all behind `audit:events:read`, the scope the listing already requires: a backlog, a dead-letter
|
|
17
17
|
* count, and a state. Each is read off `pithy_audit_sinks` by primary key, one row per declared sink, so the bound
|
|
@@ -25,27 +25,9 @@ export const AUDIT_SHIP_BACKLOG = "auditShipBacklog";
|
|
|
25
25
|
/** Events given up on, across every sink: their last retry failed and they went to the dead-letter queue. */
|
|
26
26
|
export const AUDIT_SHIP_DEAD_LETTERED = "auditShipDeadLettered";
|
|
27
27
|
|
|
28
|
-
/** How delivery stands, across every sink. */
|
|
28
|
+
/** How delivery stands, across every sink: {@link shipDelivery} over every declared sink's row. */
|
|
29
29
|
export const AUDIT_SHIP_DELIVERY = "auditShipDelivery";
|
|
30
30
|
|
|
31
|
-
/**
|
|
32
|
-
* The values {@link AUDIT_SHIP_DELIVERY} takes. `failing` when any sink's last attempt failed; `delivering` when
|
|
33
|
-
* every sink that has been attempted last took a delivery; `idle` when no sink has been attempted yet.
|
|
34
|
-
*/
|
|
35
|
-
export const SHIP_DELIVERY_STATES = ["delivering", "failing", "idle"] as const;
|
|
36
|
-
export type ShipDeliveryState = (typeof SHIP_DELIVERY_STATES)[number];
|
|
37
|
-
|
|
38
|
-
/** How delivery stands, from the declared sinks' rows. */
|
|
39
|
-
export function shipDelivery(states: readonly AuditSinkStateRow[]): ShipDeliveryState {
|
|
40
|
-
const attempted = states.filter((state) => state.lastDeliveredAt !== null || state.lastFailedAt !== null);
|
|
41
|
-
if (attempted.length === 0) return "idle";
|
|
42
|
-
const failing = attempted.some(
|
|
43
|
-
(state) =>
|
|
44
|
-
state.lastFailedAt !== null && (state.lastDeliveredAt === null || state.lastFailedAt > state.lastDeliveredAt),
|
|
45
|
-
);
|
|
46
|
-
return failing ? "failing" : "delivering";
|
|
47
|
-
}
|
|
48
|
-
|
|
49
31
|
/** Declare shipping's health keys over the declared sinks. */
|
|
50
32
|
export function shipHealth(sinks: AuditSinks, database: (c: Context<PithyHonoEnv>) => AuditDatabase): CapabilityHealth {
|
|
51
33
|
const names = Object.keys(sinks);
|
package/src/version.generated.ts
CHANGED