@pithy-sh/audit 0.8.0 → 0.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/http/guards.d.ts +3 -3
- package/dist/http/guards.js +4 -4
- package/dist/http/responses.d.ts +76 -0
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +21 -1
- package/dist/http/routes.d.ts +1 -1
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +23 -13
- package/dist/http/schemas.d.ts +7 -5
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +9 -7
- package/dist/http/views.d.ts +6 -1
- package/dist/http/views.d.ts.map +1 -1
- package/dist/http/views.js +17 -1
- package/dist/query.d.ts +2 -0
- package/dist/query.d.ts.map +1 -1
- package/dist/query.js +1 -0
- package/dist/usage.d.ts +29 -12
- package/dist/usage.d.ts.map +1 -1
- package/dist/usage.js +23 -9
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/package.json +3 -3
- package/src/http/guards.ts +4 -4
- package/src/http/responses.ts +45 -0
- package/src/http/routes.ts +39 -15
- package/src/http/schemas.ts +21 -8
- package/src/http/views.ts +17 -0
- package/src/query.ts +7 -0
- package/src/usage.ts +37 -16
- package/src/version.generated.ts +1 -1
package/dist/http/guards.d.ts
CHANGED
|
@@ -37,9 +37,9 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
|
|
|
37
37
|
* the other.
|
|
38
38
|
*
|
|
39
39
|
* **Usage rides the listing scope.** `GET {base}/control-plane/usage` counts one connection's calls by scope
|
|
40
|
-
* and key. Its answer is the scope, the key id, and the method and path of the
|
|
41
|
-
* client's own footprint, which the listing already discloses in shape through
|
|
42
|
-
* — and never an IP, a user-agent, or any other metadata key. So it needs no detail scope, and an access review does
|
|
40
|
+
* and key, or every connection's. Its answer is the connection, the scope, the key id, and the method and path of the
|
|
41
|
+
* last allowed call — the management client's own footprint, which the listing already discloses in shape through
|
|
42
|
+
* `action`, `actorId` and `resourceId` — and never an IP, a user-agent, or any other metadata key. So it needs no detail scope, and an access review does
|
|
43
43
|
* not have to hold the most dangerous grant audit defines to ask which grants are used.
|
|
44
44
|
*
|
|
45
45
|
* **The access history rides the listing scope.** `GET {base}/control-plane/access-history` answers every
|
package/dist/http/guards.js
CHANGED
|
@@ -36,9 +36,9 @@
|
|
|
36
36
|
* the other.
|
|
37
37
|
*
|
|
38
38
|
* **Usage rides the listing scope.** `GET {base}/control-plane/usage` counts one connection's calls by scope
|
|
39
|
-
* and key. Its answer is the scope, the key id, and the method and path of the
|
|
40
|
-
* client's own footprint, which the listing already discloses in shape through
|
|
41
|
-
* — and never an IP, a user-agent, or any other metadata key. So it needs no detail scope, and an access review does
|
|
39
|
+
* and key, or every connection's. Its answer is the connection, the scope, the key id, and the method and path of the
|
|
40
|
+
* last allowed call — the management client's own footprint, which the listing already discloses in shape through
|
|
41
|
+
* `action`, `actorId` and `resourceId` — and never an IP, a user-agent, or any other metadata key. So it needs no detail scope, and an access review does
|
|
42
42
|
* not have to hold the most dangerous grant audit defines to ask which grants are used.
|
|
43
43
|
*
|
|
44
44
|
* **The access history rides the listing scope.** `GET {base}/control-plane/access-history` answers every
|
|
@@ -138,7 +138,7 @@ function auditAdminRoutes(basePath) {
|
|
|
138
138
|
path: `${basePath}/control-plane/usage`,
|
|
139
139
|
scope: AUDIT_TRAIL_READ_SCOPE,
|
|
140
140
|
kind: "reads",
|
|
141
|
-
summary: "Count which scopes one control-plane connection exercised and was refused, by key, over a window. Counts only — no event is read in full."
|
|
141
|
+
summary: "Count which scopes one control-plane connection, or every one, exercised and was refused, by key, over a window. Counts only — no event is read in full."
|
|
142
142
|
},
|
|
143
143
|
{
|
|
144
144
|
method: "GET",
|
package/dist/http/responses.d.ts
CHANGED
|
@@ -576,6 +576,82 @@ export declare const ControlPlaneUsageResponse: z.ZodObject<{
|
|
|
576
576
|
oldestEventAt: z.ZodNullable<z.ZodISODateTime>;
|
|
577
577
|
}, z.core.$strip>;
|
|
578
578
|
export type ControlPlaneUsageResponse = z.output<typeof ControlPlaneUsageResponse>;
|
|
579
|
+
/** One connection's scopes and keys, in the every-connection usage answer. */
|
|
580
|
+
export declare const ControlPlaneConnectionUsageView: z.ZodObject<{
|
|
581
|
+
connectionId: z.ZodString;
|
|
582
|
+
usage: z.ZodArray<z.ZodObject<{
|
|
583
|
+
scope: z.ZodString;
|
|
584
|
+
keyId: z.ZodNullable<z.ZodString>;
|
|
585
|
+
allowed: z.ZodNumber;
|
|
586
|
+
denied: z.ZodNumber;
|
|
587
|
+
lastAllowedAt: z.ZodNullable<z.ZodISODateTime>;
|
|
588
|
+
lastAllowedMethod: z.ZodNullable<z.ZodString>;
|
|
589
|
+
lastAllowedPath: z.ZodNullable<z.ZodString>;
|
|
590
|
+
lastDeniedAt: z.ZodNullable<z.ZodISODateTime>;
|
|
591
|
+
}, z.core.$strip>>;
|
|
592
|
+
}, z.core.$strip>;
|
|
593
|
+
export type ControlPlaneConnectionUsageView = z.output<typeof ControlPlaneConnectionUsageView>;
|
|
594
|
+
/**
|
|
595
|
+
* `GET {base}/control-plane/usage` with no `connectionId`: every connection that called in the window.
|
|
596
|
+
*
|
|
597
|
+
* A shape of its own, beside {@link ControlPlaneUsageResponse}, so the answer to a named connection is unchanged and
|
|
598
|
+
* a client that names one parses what it always did. Told apart by its keys: `connections` here, `connectionId` and
|
|
599
|
+
* `usage` there.
|
|
600
|
+
*/
|
|
601
|
+
export declare const ControlPlaneUsageAllResponse: z.ZodObject<{
|
|
602
|
+
since: z.ZodISODateTime;
|
|
603
|
+
until: z.ZodISODateTime;
|
|
604
|
+
connections: z.ZodArray<z.ZodObject<{
|
|
605
|
+
connectionId: z.ZodString;
|
|
606
|
+
usage: z.ZodArray<z.ZodObject<{
|
|
607
|
+
scope: z.ZodString;
|
|
608
|
+
keyId: z.ZodNullable<z.ZodString>;
|
|
609
|
+
allowed: z.ZodNumber;
|
|
610
|
+
denied: z.ZodNumber;
|
|
611
|
+
lastAllowedAt: z.ZodNullable<z.ZodISODateTime>;
|
|
612
|
+
lastAllowedMethod: z.ZodNullable<z.ZodString>;
|
|
613
|
+
lastAllowedPath: z.ZodNullable<z.ZodString>;
|
|
614
|
+
lastDeniedAt: z.ZodNullable<z.ZodISODateTime>;
|
|
615
|
+
}, z.core.$strip>>;
|
|
616
|
+
}, z.core.$strip>>;
|
|
617
|
+
oldestEventAt: z.ZodNullable<z.ZodISODateTime>;
|
|
618
|
+
}, z.core.$strip>;
|
|
619
|
+
export type ControlPlaneUsageAllResponse = z.output<typeof ControlPlaneUsageAllResponse>;
|
|
620
|
+
/** What the usage route answers: one connection's usage when the query names one, every connection's when not. */
|
|
621
|
+
export declare const ControlPlaneUsageReadResponse: z.ZodUnion<readonly [z.ZodObject<{
|
|
622
|
+
connectionId: z.ZodString;
|
|
623
|
+
since: z.ZodISODateTime;
|
|
624
|
+
until: z.ZodISODateTime;
|
|
625
|
+
usage: z.ZodArray<z.ZodObject<{
|
|
626
|
+
scope: z.ZodString;
|
|
627
|
+
keyId: z.ZodNullable<z.ZodString>;
|
|
628
|
+
allowed: z.ZodNumber;
|
|
629
|
+
denied: z.ZodNumber;
|
|
630
|
+
lastAllowedAt: z.ZodNullable<z.ZodISODateTime>;
|
|
631
|
+
lastAllowedMethod: z.ZodNullable<z.ZodString>;
|
|
632
|
+
lastAllowedPath: z.ZodNullable<z.ZodString>;
|
|
633
|
+
lastDeniedAt: z.ZodNullable<z.ZodISODateTime>;
|
|
634
|
+
}, z.core.$strip>>;
|
|
635
|
+
oldestEventAt: z.ZodNullable<z.ZodISODateTime>;
|
|
636
|
+
}, z.core.$strip>, z.ZodObject<{
|
|
637
|
+
since: z.ZodISODateTime;
|
|
638
|
+
until: z.ZodISODateTime;
|
|
639
|
+
connections: z.ZodArray<z.ZodObject<{
|
|
640
|
+
connectionId: z.ZodString;
|
|
641
|
+
usage: z.ZodArray<z.ZodObject<{
|
|
642
|
+
scope: z.ZodString;
|
|
643
|
+
keyId: z.ZodNullable<z.ZodString>;
|
|
644
|
+
allowed: z.ZodNumber;
|
|
645
|
+
denied: z.ZodNumber;
|
|
646
|
+
lastAllowedAt: z.ZodNullable<z.ZodISODateTime>;
|
|
647
|
+
lastAllowedMethod: z.ZodNullable<z.ZodString>;
|
|
648
|
+
lastAllowedPath: z.ZodNullable<z.ZodString>;
|
|
649
|
+
lastDeniedAt: z.ZodNullable<z.ZodISODateTime>;
|
|
650
|
+
}, z.core.$strip>>;
|
|
651
|
+
}, z.core.$strip>>;
|
|
652
|
+
oldestEventAt: z.ZodNullable<z.ZodISODateTime>;
|
|
653
|
+
}, z.core.$strip>]>;
|
|
654
|
+
export type ControlPlaneUsageReadResponse = z.output<typeof ControlPlaneUsageReadResponse>;
|
|
579
655
|
/** `GET {base}/control-plane/verify`. */
|
|
580
656
|
export declare const ChainVerifyResponse: z.ZodObject<{
|
|
581
657
|
tenant: z.ZodNullable<z.ZodString>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"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"}
|
package/dist/http/responses.js
CHANGED
|
@@ -205,6 +205,26 @@ const ControlPlaneUsageResponse = z.object({
|
|
|
205
205
|
usage: z.array(ControlPlaneUsageView).describe("One row per scope and key exercised, ordered by scope then key."),
|
|
206
206
|
oldestEventAt: z.iso.datetime().nullable().describe("The oldest event the trail holds, for any connection, or null on an empty trail. A window starting before it was not fully covered: retention removed what came before.")
|
|
207
207
|
}).describe("Which scopes one control-plane connection exercised and was refused, by key, over a window.");
|
|
208
|
+
/** One connection's scopes and keys, in the every-connection usage answer. */
|
|
209
|
+
const ControlPlaneConnectionUsageView = z.object({
|
|
210
|
+
connectionId: z.string().describe("The connection that made the calls."),
|
|
211
|
+
usage: z.array(ControlPlaneUsageView).describe("One row per scope and key this connection exercised, ordered by scope then key. Never empty.")
|
|
212
|
+
}).describe("One control-plane connection's usage, by scope and key.");
|
|
213
|
+
/**
|
|
214
|
+
* `GET {base}/control-plane/usage` with no `connectionId`: every connection that called in the window.
|
|
215
|
+
*
|
|
216
|
+
* A shape of its own, beside {@link ControlPlaneUsageResponse}, so the answer to a named connection is unchanged and
|
|
217
|
+
* a client that names one parses what it always did. Told apart by its keys: `connections` here, `connectionId` and
|
|
218
|
+
* `usage` there.
|
|
219
|
+
*/
|
|
220
|
+
const ControlPlaneUsageAllResponse = z.object({
|
|
221
|
+
since: z.iso.datetime().describe("The window's inclusive start, ISO-8601."),
|
|
222
|
+
until: z.iso.datetime().describe("The window's inclusive end, ISO-8601 — now, when the query named none."),
|
|
223
|
+
connections: z.array(ControlPlaneConnectionUsageView).describe("One entry per connection that made a call in the window, ordered by connection id. A connection that made none is absent: join against the connection listing for it."),
|
|
224
|
+
oldestEventAt: z.iso.datetime().nullable().describe("The oldest event the trail holds, for any connection, or null on an empty trail. A window starting before it was not fully covered: retention removed what came before.")
|
|
225
|
+
}).describe("Which scopes every control-plane connection exercised and was refused, by key, over a window.");
|
|
226
|
+
/** What the usage route answers: one connection's usage when the query names one, every connection's when not. */
|
|
227
|
+
const ControlPlaneUsageReadResponse = z.union([ControlPlaneUsageResponse, ControlPlaneUsageAllResponse]).describe("One connection's usage when `connectionId` is named, as `ControlPlaneUsageResponse`; every connection's when it is not, as `ControlPlaneUsageAllResponse`.");
|
|
208
228
|
/** `GET {base}/control-plane/verify`. */
|
|
209
229
|
const ChainVerifyResponse = z.object({
|
|
210
230
|
tenant: z.string().nullable().describe("The tenant whose chain was walked, or null for the untenanted chain."),
|
|
@@ -241,4 +261,4 @@ const AuditSinkView = z.object({
|
|
|
241
261
|
/** `GET {base}/control-plane/sinks`. */
|
|
242
262
|
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.");
|
|
243
263
|
//#endregion
|
|
244
|
-
export { AccessChangeView, AccessHistoryResponse, AuditEventDetailView, AuditEventResponse, AuditEventView, AuditEventsResponse, AuditSinkView, AuditSinksResponse, ChainExportResponse, ChainVerifyResponse, ConnectionAccessChange, ControlPlaneReachResponse, ControlPlaneReachSubjectView, ControlPlaneReachView, ControlPlaneUsageResponse, ControlPlaneUsageView, KeyAccessChange, MemberAccessChange };
|
|
264
|
+
export { AccessChangeView, AccessHistoryResponse, AuditEventDetailView, AuditEventResponse, AuditEventView, AuditEventsResponse, AuditSinkView, AuditSinksResponse, ChainExportResponse, ChainVerifyResponse, ConnectionAccessChange, ControlPlaneConnectionUsageView, ControlPlaneReachResponse, ControlPlaneReachSubjectView, ControlPlaneReachView, ControlPlaneUsageAllResponse, ControlPlaneUsageReadResponse, ControlPlaneUsageResponse, ControlPlaneUsageView, KeyAccessChange, MemberAccessChange };
|
package/dist/http/routes.d.ts
CHANGED
|
@@ -17,7 +17,7 @@ import type { AuditSinks } from "../ship/sinks";
|
|
|
17
17
|
* (control-plane: audit:events:read) query: AccessHistoryQuery
|
|
18
18
|
* GET /audit/control-plane/reach → what one credential reached, by tenant, route and outcome
|
|
19
19
|
* (control-plane: audit:events:read) query: ControlPlaneReachQuery
|
|
20
|
-
* GET /audit/control-plane/usage → one connection's calls, counted by scope and key
|
|
20
|
+
* GET /audit/control-plane/usage → one connection's calls, or every connection's, counted by scope and key
|
|
21
21
|
* (control-plane: audit:events:read) query: ControlPlaneUsageQuery
|
|
22
22
|
* GET /audit/control-plane/verify → whether one tenant's hash chain is whole, or where it breaks
|
|
23
23
|
* (control-plane: audit:events:export) query: ChainVerifyQuery
|
|
@@ -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;AAIpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,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;AAoChD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,CAwclG"}
|
package/dist/http/routes.js
CHANGED
|
@@ -9,9 +9,9 @@ import { reachPatterns } from "../routePattern.js";
|
|
|
9
9
|
import { controlPlaneReach, controlPlaneReachSubjects } from "../reach.js";
|
|
10
10
|
import { readSinkStates } from "../ship/state.js";
|
|
11
11
|
import { controlPlaneUsage } from "../usage.js";
|
|
12
|
-
import { AccessHistoryResponse, AuditEventResponse, AuditEventsResponse, AuditSinksResponse, ChainExportResponse, ChainVerifyResponse, ControlPlaneReachResponse,
|
|
12
|
+
import { AccessHistoryResponse, AuditEventResponse, AuditEventsResponse, AuditSinksResponse, ChainExportResponse, ChainVerifyResponse, ControlPlaneReachResponse, ControlPlaneUsageReadResponse } from "./responses.js";
|
|
13
13
|
import { AccessHistoryQuery, AuditEventIdParam, ChainExportQuery, ChainVerifyQuery, ControlPlaneReachQuery, ControlPlaneUsageQuery, ListAuditEventsQuery } from "./schemas.js";
|
|
14
|
-
import { accessChangeView, auditEventDetailView, auditEventView, auditSinkViews, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView } from "./views.js";
|
|
14
|
+
import { accessChangeView, auditEventDetailView, auditEventView, auditSinkViews, controlPlaneConnectionUsageViews, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView } from "./views.js";
|
|
15
15
|
import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
|
|
16
16
|
import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
|
|
17
17
|
import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
|
|
@@ -293,15 +293,16 @@ function registerAuditRoutes(options) {
|
|
|
293
293
|
});
|
|
294
294
|
/**
|
|
295
295
|
* CONTROL-PLANE READ. Which scopes one connection exercised and was refused, by key, over a window —
|
|
296
|
-
* counted in one SQL statement, never by paging events here.
|
|
297
|
-
*
|
|
298
|
-
*
|
|
296
|
+
* counted in one SQL statement, never by paging events here. With no `connectionId`, every connection that called
|
|
297
|
+
* in the window, each with its own scopes and keys, from the same one statement. Behind the listing
|
|
298
|
+
* scope, not the detail one: the answer is the connection, the scope, the key, and the last allowed call's method
|
|
299
|
+
* and path, and never an IP, a user-agent or any other metadata key.
|
|
299
300
|
*/
|
|
300
301
|
app.get(`${base}/control-plane/usage`, describeRoute({
|
|
301
|
-
summary: "Count which scopes one control-plane connection exercised and was refused, by key, over a window.",
|
|
302
|
+
summary: "Count which scopes one control-plane connection, or every one, exercised and was refused, by key, over a window.",
|
|
302
303
|
verification: "control-plane",
|
|
303
304
|
scopes: [AUDIT_TRAIL_READ_SCOPE],
|
|
304
|
-
responses: { 200:
|
|
305
|
+
responses: { 200: ControlPlaneUsageReadResponse }
|
|
305
306
|
}), requireControlPlane(AUDIT_TRAIL_READ_SCOPE), validate("query", ControlPlaneUsageQuery), async (c) => {
|
|
306
307
|
const operator = caller(c);
|
|
307
308
|
const query = c.req.valid("query");
|
|
@@ -309,32 +310,41 @@ function registerAuditRoutes(options) {
|
|
|
309
310
|
since: query.since,
|
|
310
311
|
until: query.until ?? /* @__PURE__ */ new Date()
|
|
311
312
|
};
|
|
313
|
+
const named = query.connectionId;
|
|
312
314
|
const result = await controlPlaneUsage(database(c), {
|
|
313
|
-
connectionId:
|
|
315
|
+
...named !== void 0 ? { connectionId: named } : {},
|
|
314
316
|
...window
|
|
315
317
|
});
|
|
318
|
+
const connections = named === void 0 ? controlPlaneConnectionUsageViews(result.usage) : void 0;
|
|
316
319
|
await c.var.emit({
|
|
317
320
|
action: AuditTrailActions.usageRead,
|
|
318
321
|
outcome: "success",
|
|
319
322
|
actorType: "control-plane",
|
|
320
323
|
actorId: operator.subject,
|
|
321
324
|
resourceType: "controlplane_connection",
|
|
322
|
-
resourceId:
|
|
325
|
+
...named !== void 0 ? { resourceId: named } : {},
|
|
323
326
|
requestId: c.req.header("cf-ray"),
|
|
324
327
|
ip: c.req.header("cf-connecting-ip"),
|
|
325
328
|
userAgent: c.req.header("user-agent"),
|
|
326
329
|
metadata: {
|
|
327
330
|
connectionId: operator.connectionId,
|
|
328
331
|
query: {
|
|
329
|
-
connectionId:
|
|
332
|
+
connectionId: named ?? null,
|
|
330
333
|
since: window.since.toISOString(),
|
|
331
334
|
until: window.until.toISOString()
|
|
332
335
|
},
|
|
336
|
+
...connections !== void 0 ? { connections: connections.map((entry) => entry.connectionId) } : {},
|
|
333
337
|
returned: result.usage.length
|
|
334
338
|
}
|
|
335
339
|
});
|
|
340
|
+
if (named === void 0) return c.json({
|
|
341
|
+
since: window.since.toISOString(),
|
|
342
|
+
until: window.until.toISOString(),
|
|
343
|
+
connections: connections ?? [],
|
|
344
|
+
oldestEventAt: result.oldestEventAt?.toISOString() ?? null
|
|
345
|
+
}, 200);
|
|
336
346
|
return c.json({
|
|
337
|
-
connectionId:
|
|
347
|
+
connectionId: named,
|
|
338
348
|
since: window.since.toISOString(),
|
|
339
349
|
until: window.until.toISOString(),
|
|
340
350
|
usage: result.usage.map(controlPlaneUsageView),
|
|
@@ -448,8 +458,8 @@ function registerAuditRoutes(options) {
|
|
|
448
458
|
});
|
|
449
459
|
/**
|
|
450
460
|
* CONTROL-PLANE READ. Every declared sink beside its own delivery row: one primary-key lookup per sink, bounded
|
|
451
|
-
* by the config.
|
|
452
|
-
*
|
|
461
|
+
* by the config. Records no audit action of its own, unlike the trail's reads: it reads delivery state, never
|
|
462
|
+
* the trail, so the gate's `controlplane/call_allowed` row is its only record.
|
|
453
463
|
*/
|
|
454
464
|
app.get(`${base}/control-plane/sinks`, describeRoute({
|
|
455
465
|
summary: "List every sink the trail ships to, each with its backlog, last delivery and dead letters.",
|
package/dist/http/schemas.d.ts
CHANGED
|
@@ -27,6 +27,7 @@ export declare const ListAuditEventsQuery: z.ZodObject<{
|
|
|
27
27
|
script: "script";
|
|
28
28
|
}>>;
|
|
29
29
|
action: z.ZodOptional<z.ZodString>;
|
|
30
|
+
actionPrefix: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
|
|
30
31
|
outcome: z.ZodOptional<z.ZodEnum<{
|
|
31
32
|
denied: "denied";
|
|
32
33
|
failure: "failure";
|
|
@@ -87,13 +88,14 @@ export type ControlPlaneReachQuery = z.infer<typeof ControlPlaneReachQuery>;
|
|
|
87
88
|
/**
|
|
88
89
|
* The usage query: whose calls to count, and over what window.
|
|
89
90
|
*
|
|
90
|
-
* `
|
|
91
|
-
*
|
|
92
|
-
*
|
|
93
|
-
*
|
|
91
|
+
* `since` is required, so a missing one is a 400 before any query runs — an unbounded window is not a question this
|
|
92
|
+
* route answers. `connectionId` is optional: named, the route counts that connection's calls; left out, it counts every
|
|
93
|
+
* connection's, which is the over-grant question across a Worker in one read. `until` defaults to now in the
|
|
94
|
+
* handler, which is the one value a schema cannot compute for a request. A window that ends before it starts is
|
|
95
|
+
* refused rather than answered with nothing, because nothing would read as an idle connection.
|
|
94
96
|
*/
|
|
95
97
|
export declare const ControlPlaneUsageQuery: z.ZodObject<{
|
|
96
|
-
connectionId: z.ZodString
|
|
98
|
+
connectionId: z.ZodOptional<z.ZodString>;
|
|
97
99
|
since: z.ZodPipe<z.ZodString, z.ZodTransform<Date, string>>;
|
|
98
100
|
until: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<Date, string>>>;
|
|
99
101
|
}, z.core.$strip>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA+CxB,kCAAkC;AAClC,eAAO,MAAM,iBAAiB;;iBAS+B,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB
|
|
1
|
+
{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA+CxB,kCAAkC;AAClC,eAAO,MAAM,iBAAiB;;iBAS+B,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqDiE,CAAC;AACnG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;;;;;iBAqBiE,CAAC;AACjG,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAKpE;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;iBA4B2E,CAAC;AAC/G,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;iBAY6D,CAAC;AACjG,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAU5E,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;iBAc4C,CAAC;AAC1E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,+CAA+C;AAC/C,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,kFAAkF;AAClF,eAAO,MAAM,gBAAgB;;;;;;iBA0B8D,CAAC;AAC5F,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
|
package/dist/http/schemas.js
CHANGED
|
@@ -54,7 +54,8 @@ const ListAuditEventsQuery = z.object({
|
|
|
54
54
|
actorType: AuditActorType.optional().describe("Filter to one kind of principal. `control-plane` is the one that separates a management client's own actions from the adopter's users'."),
|
|
55
55
|
actorId: FilterValue.optional().describe("Filter to one principal — a user id, a service name, a token subject."),
|
|
56
56
|
actorKind: ControlPlaneActorKind.optional().describe("Filter to one kind of client: `agent`, `dashboard` or `script`. `agent` finds a management agent's rows and every row a user's MCP client wrote, on both paths."),
|
|
57
|
-
action: AuditAction.max(MAX_FILTER_LENGTH).optional().describe("Filter to one exact `domain/reason` action code. Exact
|
|
57
|
+
action: AuditAction.max(MAX_FILTER_LENGTH).optional().describe("Filter to one exact `domain/reason` action code. Exact; `actionPrefix` is the domain-wide filter."),
|
|
58
|
+
actionPrefix: z.string().regex(/^[a-z][a-z0-9]*\/?$/, "An action prefix is one domain, lowercase, with or without its trailing `/` (e.g. `auth` or `auth/`).").max(MAX_FILTER_LENGTH).transform((value) => value.replace(/\/$/, "")).optional().describe("Filter to every action under one domain — `auth` or `auth/` matches `auth/login` and `auth/logout`, never `authority/granted`. The domain is the only prefix: a reason is never matched by its start."),
|
|
58
59
|
outcome: AuditOutcome.optional().describe("Filter to one outcome. `denied` is the one worth watching: a run of denials is what a credential being probed looks like."),
|
|
59
60
|
severity: AuditSeverity.optional().describe("Filter to one severity."),
|
|
60
61
|
resourceType: FilterValue.optional().describe("Filter to the kind of thing acted on (`user`, `secret`)."),
|
|
@@ -112,19 +113,20 @@ const ControlPlaneReachQuery = z.object({
|
|
|
112
113
|
/**
|
|
113
114
|
* The usage query: whose calls to count, and over what window.
|
|
114
115
|
*
|
|
115
|
-
* `
|
|
116
|
-
*
|
|
117
|
-
*
|
|
118
|
-
*
|
|
116
|
+
* `since` is required, so a missing one is a 400 before any query runs — an unbounded window is not a question this
|
|
117
|
+
* route answers. `connectionId` is optional: named, the route counts that connection's calls; left out, it counts every
|
|
118
|
+
* connection's, which is the over-grant question across a Worker in one read. `until` defaults to now in the
|
|
119
|
+
* handler, which is the one value a schema cannot compute for a request. A window that ends before it starts is
|
|
120
|
+
* refused rather than answered with nothing, because nothing would read as an idle connection.
|
|
119
121
|
*/
|
|
120
122
|
const ControlPlaneUsageQuery = z.object({
|
|
121
|
-
connectionId: FilterValue.describe("The control-plane connection whose calls to count — the `resourceId` its call rows carry.
|
|
123
|
+
connectionId: FilterValue.optional().describe("The control-plane connection whose calls to count — the `resourceId` its call rows carry. Omit it to count every connection's."),
|
|
122
124
|
since: TimeBound.describe("Inclusive lower bound on when a call landed, ISO-8601. Required."),
|
|
123
125
|
until: TimeBound.optional().describe("Inclusive upper bound on when a call landed, ISO-8601. Defaults to now.")
|
|
124
126
|
}).refine((query) => query.until === void 0 || query.until.getTime() >= query.since.getTime(), {
|
|
125
127
|
message: "`until` must not be before `since`.",
|
|
126
128
|
path: ["until"]
|
|
127
|
-
}).describe("The control-plane usage query: one connection, over a window.");
|
|
129
|
+
}).describe("The control-plane usage query: one connection or every connection, over a window.");
|
|
128
130
|
/**
|
|
129
131
|
* The tenant whose chain to read. **Required**, because there is no "every chain": a chain is one tenant's.
|
|
130
132
|
* Send it empty (`?tenant=`) for the untenanted chain — the same encoding the listing's filter uses.
|
package/dist/http/views.d.ts
CHANGED
|
@@ -6,7 +6,7 @@ import type { AuditSinkStateRow } from "../data/sinkState";
|
|
|
6
6
|
import type { ControlPlaneReachRow, ControlPlaneReachSubjectRow } from "../reach";
|
|
7
7
|
import type { AuditSinks } from "../ship/sinks";
|
|
8
8
|
import type { ControlPlaneUsageRow } from "../usage";
|
|
9
|
-
import type { AccessChangeView, AuditEventDetailView, AuditEventView, AuditSinkView, ControlPlaneReachSubjectView, ControlPlaneReachView, ControlPlaneUsageView } from "./responses";
|
|
9
|
+
import type { AccessChangeView, AuditEventDetailView, AuditEventView, AuditSinkView, ControlPlaneConnectionUsageView, ControlPlaneReachSubjectView, ControlPlaneReachView, ControlPlaneUsageView } from "./responses";
|
|
10
10
|
/**
|
|
11
11
|
* What a management client is shown of an audit event — decided here, once, rather than by whichever
|
|
12
12
|
* columns a query happened to select.
|
|
@@ -78,6 +78,11 @@ export declare function controlPlaneReachSubjectView(row: ControlPlaneReachSubje
|
|
|
78
78
|
* the scope, the key, and the last allowed call's method and path out of `metadata`, so there is nothing here to drop.
|
|
79
79
|
*/
|
|
80
80
|
export declare function controlPlaneUsageView(row: ControlPlaneUsageRow): ControlPlaneUsageView;
|
|
81
|
+
/**
|
|
82
|
+
* Fold every connection's usage rows into one entry per connection, in the order the aggregate returned them —
|
|
83
|
+
* by connection, then scope, then key — so each connection's rows keep the order a named read gives them.
|
|
84
|
+
*/
|
|
85
|
+
export declare function controlPlaneConnectionUsageViews(rows: readonly ControlPlaneUsageRow[]): ControlPlaneConnectionUsageView[];
|
|
81
86
|
/**
|
|
82
87
|
* Project the declared sinks, in declaration order, each beside its own state row. A sink with no row has never been
|
|
83
88
|
* attempted and answers null times, zero counts and `idle`; a row whose sink is no longer declared is not answered.
|
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,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"}
|
|
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,+BAA+B,EAC/B,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;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,SAAS,oBAAoB,EAAE,GACpC,+BAA+B,EAAE,CAQnC;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
|
@@ -185,6 +185,22 @@ function controlPlaneUsageView(row) {
|
|
|
185
185
|
};
|
|
186
186
|
}
|
|
187
187
|
/**
|
|
188
|
+
* Fold every connection's usage rows into one entry per connection, in the order the aggregate returned them —
|
|
189
|
+
* by connection, then scope, then key — so each connection's rows keep the order a named read gives them.
|
|
190
|
+
*/
|
|
191
|
+
function controlPlaneConnectionUsageViews(rows) {
|
|
192
|
+
const byConnection = /* @__PURE__ */ new Map();
|
|
193
|
+
for (const row of rows) {
|
|
194
|
+
const usage = byConnection.get(row.connectionId) ?? [];
|
|
195
|
+
usage.push(controlPlaneUsageView(row));
|
|
196
|
+
byConnection.set(row.connectionId, usage);
|
|
197
|
+
}
|
|
198
|
+
return [...byConnection].map(([connectionId, usage]) => ({
|
|
199
|
+
connectionId,
|
|
200
|
+
usage
|
|
201
|
+
}));
|
|
202
|
+
}
|
|
203
|
+
/**
|
|
188
204
|
* Project the declared sinks, in declaration order, each beside its own state row. A sink with no row has never been
|
|
189
205
|
* attempted and answers null times, zero counts and `idle`; a row whose sink is no longer declared is not answered.
|
|
190
206
|
*
|
|
@@ -216,4 +232,4 @@ function auditSinkViews(sinks, states) {
|
|
|
216
232
|
});
|
|
217
233
|
}
|
|
218
234
|
//#endregion
|
|
219
|
-
export { accessChangeView, auditEventDetailView, auditEventView, auditSinkViews, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView };
|
|
235
|
+
export { accessChangeView, auditEventDetailView, auditEventView, auditSinkViews, controlPlaneConnectionUsageViews, controlPlaneReachSubjectView, controlPlaneReachView, controlPlaneUsageView };
|
package/dist/query.d.ts
CHANGED
|
@@ -26,6 +26,8 @@ export interface AuditQuery {
|
|
|
26
26
|
actorKind?: ControlPlaneActorKind;
|
|
27
27
|
/** Match an exact `domain/reason` action code. */
|
|
28
28
|
action?: string;
|
|
29
|
+
/** Match every action under one domain — `auth` matches `auth/login`, never `authority/granted`. */
|
|
30
|
+
actionPrefix?: string;
|
|
29
31
|
/** Match the outcome (`success` | `failure` | `denied`). */
|
|
30
32
|
outcome?: AuditOutcome;
|
|
31
33
|
/** Match the severity (`info` | `warning` | `critical`). */
|
package/dist/query.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACvG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iDAAiD,CAAC;AAG7F,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,6CAA6C;IAC7C,EAAE,CAAC,EAAE,IAAI,CAAC;IACV;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,mEAAmE;IACnE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;
|
|
1
|
+
{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACvG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iDAAiD,CAAC;AAG7F,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,6CAA6C;IAC7C,EAAE,CAAC,EAAE,IAAI,CAAC;IACV;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,mEAAmE;IACnE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AA8DD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,GAAE,UAAe,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAK3G;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,GAAE,UAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAuBzG;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAGtG"}
|
package/dist/query.js
CHANGED
|
@@ -18,6 +18,7 @@ function auditEventQuery(db, filter) {
|
|
|
18
18
|
if (filter.actorId !== void 0) query = query.where("actorId", "=", filter.actorId);
|
|
19
19
|
if (filter.actorKind !== void 0) query = query.where("actorKind", "=", filter.actorKind);
|
|
20
20
|
if (filter.action !== void 0) query = query.where("action", "=", filter.action);
|
|
21
|
+
if (filter.actionPrefix !== void 0) query = query.where("action", ">=", `${filter.actionPrefix}/`).where("action", "<", `${filter.actionPrefix}0`);
|
|
21
22
|
if (filter.outcome !== void 0) query = query.where("outcome", "=", filter.outcome);
|
|
22
23
|
if (filter.severity !== void 0) query = query.where("severity", "=", filter.severity);
|
|
23
24
|
if (filter.resourceType !== void 0) query = query.where("resourceType", "=", filter.resourceType);
|
package/dist/usage.d.ts
CHANGED
|
@@ -3,25 +3,31 @@
|
|
|
3
3
|
import { z } from "zod";
|
|
4
4
|
import type { AuditDatabase } from "./data/tables";
|
|
5
5
|
/**
|
|
6
|
-
* Which scopes a control-plane connection exercised, and which it was refused — `#812
|
|
6
|
+
* Which scopes a control-plane connection exercised, and which it was refused — `#812` — for one connection or every
|
|
7
|
+
* connection at once.
|
|
7
8
|
*
|
|
8
9
|
* Every admitted call writes `controlplane/call_allowed`, and every verified call refused a scope writes
|
|
9
10
|
* `controlplane/call_denied`, both against the connection as `resourceId` and both naming the scope and key in
|
|
10
11
|
* `metadata`. Answering "granted twelve, used three" from the listing would take one forensic read per event, behind
|
|
11
12
|
* the scope that also discloses the client IP; this reads the same rows in SQL and returns counts.
|
|
12
13
|
*
|
|
14
|
+
* **One connection, or every one.** Over-grant — scopes a credential holds and never used — is a question over every
|
|
15
|
+
* connection on the Worker, so leaving the connection out counts them all in the same statement, grouped by connection
|
|
16
|
+
* first. A connection that made no call in the window has no row: the caller joins against the connection listing.
|
|
17
|
+
*
|
|
13
18
|
* **One statement for the aggregate, never a page walk.** A dashboard connection makes thousands of calls a day, and a
|
|
14
19
|
* handler that paged them to count would be the largest read on the surface. The `GROUP BY` runs in D1, over rows
|
|
15
|
-
* `pithyAuditEventsCallIdx` (`audit_0003_call_index`) finds by action, connection and time
|
|
20
|
+
* `pithyAuditEventsCallIdx` (`audit_0003_call_index`) finds by action, connection and time — or, across every
|
|
21
|
+
* connection, rows `pithyAuditEventsOccurredAtIdx` finds by the window.
|
|
16
22
|
*
|
|
17
23
|
* **Nothing personal leaves this function.** It reads the scope, the key id, and the method and path of the last
|
|
18
24
|
* allowed call out of `metadata`, and no other key, and never the IP or the user-agent. Those four are the management
|
|
19
25
|
* client's own footprint.
|
|
20
26
|
*/
|
|
21
|
-
/** What to count: one connection, over an inclusive window. */
|
|
27
|
+
/** What to count: one connection, or every connection, over an inclusive window. */
|
|
22
28
|
export interface ControlPlaneUsageFilter {
|
|
23
|
-
/** The connection whose calls are counted — the rows' `resourceId`. */
|
|
24
|
-
connectionId
|
|
29
|
+
/** The connection whose calls are counted — the rows' `resourceId`. Absent, every connection's calls are. */
|
|
30
|
+
connectionId?: string;
|
|
25
31
|
/** Inclusive lower bound on `occurredAt`. */
|
|
26
32
|
since: Date;
|
|
27
33
|
/** Inclusive upper bound on `occurredAt`. */
|
|
@@ -33,6 +39,7 @@ export interface ControlPlaneUsageFilter {
|
|
|
33
39
|
* Internal: the wire shape is `ControlPlaneUsageView` in `http/responses.ts`, and `http/views.ts` projects this into it.
|
|
34
40
|
*/
|
|
35
41
|
export declare const ControlPlaneUsageRow: z.ZodObject<{
|
|
42
|
+
connectionId: z.ZodString;
|
|
36
43
|
scope: z.ZodString;
|
|
37
44
|
keyId: z.ZodNullable<z.ZodString>;
|
|
38
45
|
allowed: z.ZodNumber;
|
|
@@ -45,7 +52,7 @@ export declare const ControlPlaneUsageRow: z.ZodObject<{
|
|
|
45
52
|
export type ControlPlaneUsageRow = z.output<typeof ControlPlaneUsageRow>;
|
|
46
53
|
/** What {@link controlPlaneUsage} answers. */
|
|
47
54
|
export interface ControlPlaneUsage {
|
|
48
|
-
/** One row per `(scope, keyId)` exercised, ordered by scope then key. */
|
|
55
|
+
/** One row per `(connectionId, scope, keyId)` exercised, ordered by connection, then scope, then key. */
|
|
49
56
|
usage: ControlPlaneUsageRow[];
|
|
50
57
|
/** The oldest event the trail holds, or null on an empty trail. */
|
|
51
58
|
oldestEventAt: Date | null;
|
|
@@ -55,13 +62,19 @@ export interface ControlPlaneUsage {
|
|
|
55
62
|
*
|
|
56
63
|
* Three steps, in one statement:
|
|
57
64
|
*
|
|
58
|
-
* 1. **`calls`** — the connection's call rows in the window,
|
|
59
|
-
* `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
|
|
65
|
+
* 1. **`calls`** — the connection's call rows in the window, or every connection's when none is named, with the
|
|
66
|
+
* connection beside the scope, key, method and path lifted out of `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
|
|
60
67
|
* refusal names the scope it required as `required`, and a handler's refusal as `scope`, so a denied row reads
|
|
61
68
|
* `required` first. A row with no scope at all is nobody's usage and is dropped.
|
|
62
|
-
* 2. **`ranked`** — each row's recency within its `(scope, keyId, action)`, newest first, `id`
|
|
63
|
-
* of the allowed rows is the last allowed call, whose method and path the answer carries.
|
|
64
|
-
* 3. **The group** — counts and last instants per `(scope, keyId)`.
|
|
69
|
+
* 2. **`ranked`** — each row's recency within its `(connectionId, scope, keyId, action)`, newest first, `id`
|
|
70
|
+
* breaking a tie. Rank 1 of the allowed rows is the last allowed call, whose method and path the answer carries.
|
|
71
|
+
* 3. **The group** — counts and last instants per `(connectionId, scope, keyId)`.
|
|
72
|
+
*
|
|
73
|
+
* Named, it seeks `pithyAuditEventsCallIdx`: each action, then the connection, then the window as a range. Unnamed,
|
|
74
|
+
* nothing narrows it but the actions and the window, and the window is what is small: an access review reads days of
|
|
75
|
+
* a trail that keeps months. So the planner reads `pithyAuditEventsOccurredAtIdx` over the window and checks the
|
|
76
|
+
* action on each row it finds, and the cost follows the window rather than everything retention holds. A row with no
|
|
77
|
+
* connection — an unverified refusal — is nobody's usage in either.
|
|
65
78
|
*/
|
|
66
79
|
export declare function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPlaneUsageFilter): import("kysely").SelectQueryBuilder<import("@pithy-sh/core/src/data/db").DatabaseSchema<{
|
|
67
80
|
pithyAuditEvents: z.ZodObject<{
|
|
@@ -119,6 +132,7 @@ export declare function controlPlaneUsageStatement(db: AuditDatabase, filter: Co
|
|
|
119
132
|
}> & {
|
|
120
133
|
calls: {
|
|
121
134
|
action: string;
|
|
135
|
+
connectionId: string | null;
|
|
122
136
|
id: number;
|
|
123
137
|
keyId: string | null;
|
|
124
138
|
method: string | null;
|
|
@@ -129,6 +143,7 @@ export declare function controlPlaneUsageStatement(db: AuditDatabase, filter: Co
|
|
|
129
143
|
} & {
|
|
130
144
|
ranked: {
|
|
131
145
|
action: string;
|
|
146
|
+
connectionId: string | null;
|
|
132
147
|
id: number;
|
|
133
148
|
keyId: string | null;
|
|
134
149
|
method: string | null;
|
|
@@ -139,6 +154,7 @@ export declare function controlPlaneUsageStatement(db: AuditDatabase, filter: Co
|
|
|
139
154
|
};
|
|
140
155
|
}, "ranked", {
|
|
141
156
|
allowed: number;
|
|
157
|
+
connectionId: string | null;
|
|
142
158
|
denied: number;
|
|
143
159
|
keyId: string | null;
|
|
144
160
|
lastAllowedAt: number | null;
|
|
@@ -148,7 +164,8 @@ export declare function controlPlaneUsageStatement(db: AuditDatabase, filter: Co
|
|
|
148
164
|
scope: string | null;
|
|
149
165
|
}>;
|
|
150
166
|
/**
|
|
151
|
-
* Count one connection's calls by scope and key, over an
|
|
167
|
+
* Count one connection's calls by scope and key, or every connection's by connection, scope and key, over an
|
|
168
|
+
* inclusive window.
|
|
152
169
|
*
|
|
153
170
|
* `oldestEventAt` is the oldest event the trail holds at all, for any connection or none. Retention prunes the trail
|
|
154
171
|
* by time, never per connection, so this is how far back any connection's answer can reach: a window starting before
|
package/dist/usage.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD
|
|
1
|
+
{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,oFAAoF;AACpF,MAAM,WAAW,uBAAuB;IACtC,6GAA6G;IAC7G,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,KAAK,EAAE,IAAI,CAAC;IACZ,6CAA6C;IAC7C,KAAK,EAAE,IAAI,CAAC;CACb;AAQD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;iBAmBkE,CAAC;AACpG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AASzE,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,yGAAyG;IACzG,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,mEAAmE;IACnE,aAAa,EAAE,IAAI,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+D5F;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,aAAa,EACjB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,iBAAiB,CAAC,CAU5B"}
|
package/dist/usage.js
CHANGED
|
@@ -15,6 +15,7 @@ const CONNECTION_RESOURCE = "controlplane_connection";
|
|
|
15
15
|
* Internal: the wire shape is `ControlPlaneUsageView` in `http/responses.ts`, and `http/views.ts` projects this into it.
|
|
16
16
|
*/
|
|
17
17
|
const ControlPlaneUsageRow = z.object({
|
|
18
|
+
connectionId: z.string().describe("The connection that made the calls — the rows' `resourceId`."),
|
|
18
19
|
scope: z.string().describe("The scope exercised: what an allowed call's token carried, or what a refused call required — `metadata.required` from the gate, `metadata.scope` from a handler."),
|
|
19
20
|
keyId: z.string().nullable().describe("The registered key that signed the calls. Null for a row that recorded none."),
|
|
20
21
|
allowed: z.number().int().describe("How many `controlplane/call_allowed` events in the window."),
|
|
@@ -31,13 +32,19 @@ const OldestEvent = z.object({ oldest: SQLiteDate.nullable().describe("The small
|
|
|
31
32
|
*
|
|
32
33
|
* Three steps, in one statement:
|
|
33
34
|
*
|
|
34
|
-
* 1. **`calls`** — the connection's call rows in the window,
|
|
35
|
-
* `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
|
|
35
|
+
* 1. **`calls`** — the connection's call rows in the window, or every connection's when none is named, with the
|
|
36
|
+
* connection beside the scope, key, method and path lifted out of `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
|
|
36
37
|
* refusal names the scope it required as `required`, and a handler's refusal as `scope`, so a denied row reads
|
|
37
38
|
* `required` first. A row with no scope at all is nobody's usage and is dropped.
|
|
38
|
-
* 2. **`ranked`** — each row's recency within its `(scope, keyId, action)`, newest first, `id`
|
|
39
|
-
* of the allowed rows is the last allowed call, whose method and path the answer carries.
|
|
40
|
-
* 3. **The group** — counts and last instants per `(scope, keyId)`.
|
|
39
|
+
* 2. **`ranked`** — each row's recency within its `(connectionId, scope, keyId, action)`, newest first, `id`
|
|
40
|
+
* breaking a tie. Rank 1 of the allowed rows is the last allowed call, whose method and path the answer carries.
|
|
41
|
+
* 3. **The group** — counts and last instants per `(connectionId, scope, keyId)`.
|
|
42
|
+
*
|
|
43
|
+
* Named, it seeks `pithyAuditEventsCallIdx`: each action, then the connection, then the window as a range. Unnamed,
|
|
44
|
+
* nothing narrows it but the actions and the window, and the window is what is small: an access review reads days of
|
|
45
|
+
* a trail that keeps months. So the planner reads `pithyAuditEventsOccurredAtIdx` over the window and checks the
|
|
46
|
+
* action on each row it finds, and the cost follows the window rather than everything retention holds. A row with no
|
|
47
|
+
* connection — an unverified refusal — is nobody's usage in either.
|
|
41
48
|
*/
|
|
42
49
|
function controlPlaneUsageStatement(db, filter) {
|
|
43
50
|
const allowed = ControlPlaneAuditActions.callAllowed;
|
|
@@ -46,15 +53,17 @@ function controlPlaneUsageStatement(db, filter) {
|
|
|
46
53
|
"id",
|
|
47
54
|
"action",
|
|
48
55
|
"occurredAt",
|
|
56
|
+
eb.ref("resourceId").as("connectionId"),
|
|
49
57
|
sql`case when ${eb.ref("action")} = ${denied}
|
|
50
58
|
then coalesce(json_extract(${eb.ref("metadata")}, '$.required'), json_extract(${eb.ref("metadata")}, '$.scope'))
|
|
51
59
|
else json_extract(${eb.ref("metadata")}, '$.scope') end`.as("scope"),
|
|
52
60
|
sql`json_extract(${eb.ref("metadata")}, '$.keyId')`.as("keyId"),
|
|
53
61
|
sql`json_extract(${eb.ref("metadata")}, '$.method')`.as("method"),
|
|
54
62
|
sql`json_extract(${eb.ref("metadata")}, '$.path')`.as("path")
|
|
55
|
-
]).where("action", "in", CALL_ACTIONS).where("resourceId", "=", filter.connectionId).where("occurredAt", ">=", SQLiteDate.encode(filter.since)).where("occurredAt", "<=", SQLiteDate.encode(filter.until)).where("resourceType", "=", CONNECTION_RESOURCE)).with("ranked", (q) => q.selectFrom("calls").selectAll().select(sql`row_number() over (
|
|
56
|
-
partition by ${sql.ref("scope")}, ${sql.ref("keyId")}, ${sql.ref("action")}
|
|
63
|
+
]).where("action", "in", CALL_ACTIONS).where((eb) => filter.connectionId === void 0 ? eb("resourceId", "is not", null) : eb("resourceId", "=", filter.connectionId)).where("occurredAt", ">=", SQLiteDate.encode(filter.since)).where("occurredAt", "<=", SQLiteDate.encode(filter.until)).where("resourceType", "=", CONNECTION_RESOURCE)).with("ranked", (q) => q.selectFrom("calls").selectAll().select(sql`row_number() over (
|
|
64
|
+
partition by ${sql.ref("connectionId")}, ${sql.ref("scope")}, ${sql.ref("keyId")}, ${sql.ref("action")}
|
|
57
65
|
order by ${sql.ref("occurredAt")} desc, ${sql.ref("id")} desc)`.as("recency")).where("scope", "is not", null)).selectFrom("ranked").select((eb) => [
|
|
66
|
+
"connectionId",
|
|
58
67
|
"scope",
|
|
59
68
|
"keyId",
|
|
60
69
|
sql`sum(case when ${eb.ref("action")} = ${allowed} then 1 else 0 end)`.as("allowed"),
|
|
@@ -65,10 +74,15 @@ function controlPlaneUsageStatement(db, filter) {
|
|
|
65
74
|
sql`max(case when ${eb.ref("action")} = ${allowed} and ${eb.ref("recency")} = 1
|
|
66
75
|
then ${eb.ref("path")} end)`.as("lastAllowedPath"),
|
|
67
76
|
sql`max(case when ${eb.ref("action")} = ${denied} then ${eb.ref("occurredAt")} end)`.as("lastDeniedAt")
|
|
68
|
-
]).groupBy([
|
|
77
|
+
]).groupBy([
|
|
78
|
+
"connectionId",
|
|
79
|
+
"scope",
|
|
80
|
+
"keyId"
|
|
81
|
+
]).orderBy("connectionId").orderBy("scope").orderBy("keyId");
|
|
69
82
|
}
|
|
70
83
|
/**
|
|
71
|
-
* Count one connection's calls by scope and key, over an
|
|
84
|
+
* Count one connection's calls by scope and key, or every connection's by connection, scope and key, over an
|
|
85
|
+
* inclusive window.
|
|
72
86
|
*
|
|
73
87
|
* `oldestEventAt` is the oldest event the trail holds at all, for any connection or none. Retention prunes the trail
|
|
74
88
|
* by time, never per connection, so this is how far back any connection's answer can reach: a window starting before
|
|
@@ -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.9.1";
|
|
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.9.1";
|
|
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.9.1",
|
|
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.18.0",
|
|
42
|
+
"@pithy-sh/secrets": "^0.6.6",
|
|
43
43
|
"hono": "^4.13.2",
|
|
44
44
|
"kysely": "^0.29.0",
|
|
45
45
|
"zod": "^4.4.0"
|
package/src/http/guards.ts
CHANGED
|
@@ -39,9 +39,9 @@ import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/sc
|
|
|
39
39
|
* the other.
|
|
40
40
|
*
|
|
41
41
|
* **Usage rides the listing scope.** `GET {base}/control-plane/usage` counts one connection's calls by scope
|
|
42
|
-
* and key. Its answer is the scope, the key id, and the method and path of the
|
|
43
|
-
* client's own footprint, which the listing already discloses in shape through
|
|
44
|
-
* — and never an IP, a user-agent, or any other metadata key. So it needs no detail scope, and an access review does
|
|
42
|
+
* and key, or every connection's. Its answer is the connection, the scope, the key id, and the method and path of the
|
|
43
|
+
* last allowed call — the management client's own footprint, which the listing already discloses in shape through
|
|
44
|
+
* `action`, `actorId` and `resourceId` — and never an IP, a user-agent, or any other metadata key. So it needs no detail scope, and an access review does
|
|
45
45
|
* not have to hold the most dangerous grant audit defines to ask which grants are used.
|
|
46
46
|
*
|
|
47
47
|
* **The access history rides the listing scope.** `GET {base}/control-plane/access-history` answers every
|
|
@@ -150,7 +150,7 @@ export function auditAdminRoutes(basePath: string): AdminRouteDeclaration[] {
|
|
|
150
150
|
scope: AUDIT_TRAIL_READ_SCOPE,
|
|
151
151
|
kind: "reads",
|
|
152
152
|
summary:
|
|
153
|
-
"Count which scopes one control-plane connection exercised and was refused, by key, over a window. Counts only — no event is read in full.",
|
|
153
|
+
"Count which scopes one control-plane connection, or every one, exercised and was refused, by key, over a window. Counts only — no event is read in full.",
|
|
154
154
|
},
|
|
155
155
|
{
|
|
156
156
|
method: "GET",
|
package/src/http/responses.ts
CHANGED
|
@@ -368,6 +368,51 @@ export const ControlPlaneUsageResponse = z
|
|
|
368
368
|
.describe("Which scopes one control-plane connection exercised and was refused, by key, over a window.");
|
|
369
369
|
export type ControlPlaneUsageResponse = z.output<typeof ControlPlaneUsageResponse>;
|
|
370
370
|
|
|
371
|
+
/** One connection's scopes and keys, in the every-connection usage answer. */
|
|
372
|
+
export const ControlPlaneConnectionUsageView = z
|
|
373
|
+
.object({
|
|
374
|
+
connectionId: z.string().describe("The connection that made the calls."),
|
|
375
|
+
usage: z
|
|
376
|
+
.array(ControlPlaneUsageView)
|
|
377
|
+
.describe("One row per scope and key this connection exercised, ordered by scope then key. Never empty."),
|
|
378
|
+
})
|
|
379
|
+
.describe("One control-plane connection's usage, by scope and key.");
|
|
380
|
+
export type ControlPlaneConnectionUsageView = z.output<typeof ControlPlaneConnectionUsageView>;
|
|
381
|
+
|
|
382
|
+
/**
|
|
383
|
+
* `GET {base}/control-plane/usage` with no `connectionId`: every connection that called in the window.
|
|
384
|
+
*
|
|
385
|
+
* A shape of its own, beside {@link ControlPlaneUsageResponse}, so the answer to a named connection is unchanged and
|
|
386
|
+
* a client that names one parses what it always did. Told apart by its keys: `connections` here, `connectionId` and
|
|
387
|
+
* `usage` there.
|
|
388
|
+
*/
|
|
389
|
+
export const ControlPlaneUsageAllResponse = z
|
|
390
|
+
.object({
|
|
391
|
+
since: z.iso.datetime().describe("The window's inclusive start, ISO-8601."),
|
|
392
|
+
until: z.iso.datetime().describe("The window's inclusive end, ISO-8601 — now, when the query named none."),
|
|
393
|
+
connections: z
|
|
394
|
+
.array(ControlPlaneConnectionUsageView)
|
|
395
|
+
.describe(
|
|
396
|
+
"One entry per connection that made a call in the window, ordered by connection id. A connection that made none is absent: join against the connection listing for it.",
|
|
397
|
+
),
|
|
398
|
+
oldestEventAt: z.iso
|
|
399
|
+
.datetime()
|
|
400
|
+
.nullable()
|
|
401
|
+
.describe(
|
|
402
|
+
"The oldest event the trail holds, for any connection, or null on an empty trail. A window starting before it was not fully covered: retention removed what came before.",
|
|
403
|
+
),
|
|
404
|
+
})
|
|
405
|
+
.describe("Which scopes every control-plane connection exercised and was refused, by key, over a window.");
|
|
406
|
+
export type ControlPlaneUsageAllResponse = z.output<typeof ControlPlaneUsageAllResponse>;
|
|
407
|
+
|
|
408
|
+
/** What the usage route answers: one connection's usage when the query names one, every connection's when not. */
|
|
409
|
+
export const ControlPlaneUsageReadResponse = z
|
|
410
|
+
.union([ControlPlaneUsageResponse, ControlPlaneUsageAllResponse])
|
|
411
|
+
.describe(
|
|
412
|
+
"One connection's usage when `connectionId` is named, as `ControlPlaneUsageResponse`; every connection's when it is not, as `ControlPlaneUsageAllResponse`.",
|
|
413
|
+
);
|
|
414
|
+
export type ControlPlaneUsageReadResponse = z.output<typeof ControlPlaneUsageReadResponse>;
|
|
415
|
+
|
|
371
416
|
/** `GET {base}/control-plane/verify`. */
|
|
372
417
|
export const ChainVerifyResponse = z
|
|
373
418
|
.object({
|
package/src/http/routes.ts
CHANGED
|
@@ -31,7 +31,9 @@ import {
|
|
|
31
31
|
ChainExportResponse,
|
|
32
32
|
ChainVerifyResponse,
|
|
33
33
|
ControlPlaneReachResponse,
|
|
34
|
-
|
|
34
|
+
type ControlPlaneUsageAllResponse,
|
|
35
|
+
ControlPlaneUsageReadResponse,
|
|
36
|
+
type ControlPlaneUsageResponse,
|
|
35
37
|
} from "./responses";
|
|
36
38
|
import {
|
|
37
39
|
AccessHistoryQuery,
|
|
@@ -47,6 +49,7 @@ import {
|
|
|
47
49
|
auditEventDetailView,
|
|
48
50
|
auditEventView,
|
|
49
51
|
auditSinkViews,
|
|
52
|
+
controlPlaneConnectionUsageViews,
|
|
50
53
|
controlPlaneReachSubjectView,
|
|
51
54
|
controlPlaneReachView,
|
|
52
55
|
controlPlaneUsageView,
|
|
@@ -61,7 +64,7 @@ import {
|
|
|
61
64
|
* (control-plane: audit:events:read) query: AccessHistoryQuery
|
|
62
65
|
* GET /audit/control-plane/reach → what one credential reached, by tenant, route and outcome
|
|
63
66
|
* (control-plane: audit:events:read) query: ControlPlaneReachQuery
|
|
64
|
-
* GET /audit/control-plane/usage → one connection's calls, counted by scope and key
|
|
67
|
+
* GET /audit/control-plane/usage → one connection's calls, or every connection's, counted by scope and key
|
|
65
68
|
* (control-plane: audit:events:read) query: ControlPlaneUsageQuery
|
|
66
69
|
* GET /audit/control-plane/verify → whether one tenant's hash chain is whole, or where it breaks
|
|
67
70
|
* (control-plane: audit:events:export) query: ChainVerifyQuery
|
|
@@ -412,17 +415,19 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
412
415
|
|
|
413
416
|
/**
|
|
414
417
|
* CONTROL-PLANE READ. Which scopes one connection exercised and was refused, by key, over a window —
|
|
415
|
-
* counted in one SQL statement, never by paging events here.
|
|
416
|
-
*
|
|
417
|
-
*
|
|
418
|
+
* counted in one SQL statement, never by paging events here. With no `connectionId`, every connection that called
|
|
419
|
+
* in the window, each with its own scopes and keys, from the same one statement. Behind the listing
|
|
420
|
+
* scope, not the detail one: the answer is the connection, the scope, the key, and the last allowed call's method
|
|
421
|
+
* and path, and never an IP, a user-agent or any other metadata key.
|
|
418
422
|
*/
|
|
419
423
|
app.get(
|
|
420
424
|
`${base}/control-plane/usage`,
|
|
421
425
|
describeRoute({
|
|
422
|
-
summary:
|
|
426
|
+
summary:
|
|
427
|
+
"Count which scopes one control-plane connection, or every one, exercised and was refused, by key, over a window.",
|
|
423
428
|
verification: "control-plane",
|
|
424
429
|
scopes: [AUDIT_TRAIL_READ_SCOPE],
|
|
425
|
-
responses: { 200:
|
|
430
|
+
responses: { 200: ControlPlaneUsageReadResponse },
|
|
426
431
|
}),
|
|
427
432
|
requireControlPlane(AUDIT_TRAIL_READ_SCOPE),
|
|
428
433
|
validate("query", ControlPlaneUsageQuery),
|
|
@@ -430,32 +435,51 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
430
435
|
const operator = caller(c);
|
|
431
436
|
const query = c.req.valid("query");
|
|
432
437
|
const window = { since: query.since, until: query.until ?? new Date() };
|
|
433
|
-
const
|
|
434
|
-
|
|
435
|
-
|
|
438
|
+
const named = query.connectionId;
|
|
439
|
+
const result = await controlPlaneUsage(database(c), {
|
|
440
|
+
...(named !== undefined ? { connectionId: named } : {}),
|
|
441
|
+
...window,
|
|
442
|
+
});
|
|
443
|
+
const connections = named === undefined ? controlPlaneConnectionUsageViews(result.usage) : undefined;
|
|
444
|
+
// Audited like the listing, once. Named, against the connection whose usage was read: "who reviewed this
|
|
445
|
+
// connection's grants" is a question the trail should answer about that connection. Unnamed, against no
|
|
446
|
+
// one connection: `query.connectionId` is null, which is "every connection", and `connections` names each
|
|
447
|
+
// one the answer covered, so the same question still finds this read from any of them.
|
|
436
448
|
await c.var.emit({
|
|
437
449
|
action: AuditTrailActions.usageRead,
|
|
438
450
|
outcome: "success",
|
|
439
451
|
actorType: "control-plane",
|
|
440
452
|
actorId: operator.subject,
|
|
441
453
|
resourceType: "controlplane_connection",
|
|
442
|
-
resourceId:
|
|
454
|
+
...(named !== undefined ? { resourceId: named } : {}),
|
|
443
455
|
requestId: c.req.header("cf-ray"),
|
|
444
456
|
ip: c.req.header("cf-connecting-ip"),
|
|
445
457
|
userAgent: c.req.header("user-agent"),
|
|
446
458
|
metadata: {
|
|
447
459
|
connectionId: operator.connectionId,
|
|
448
460
|
query: {
|
|
449
|
-
connectionId:
|
|
461
|
+
connectionId: named ?? null,
|
|
450
462
|
since: window.since.toISOString(),
|
|
451
463
|
until: window.until.toISOString(),
|
|
452
464
|
},
|
|
465
|
+
...(connections !== undefined ? { connections: connections.map((entry) => entry.connectionId) } : {}),
|
|
453
466
|
returned: result.usage.length,
|
|
454
467
|
},
|
|
455
468
|
});
|
|
469
|
+
if (named === undefined) {
|
|
470
|
+
return c.json(
|
|
471
|
+
{
|
|
472
|
+
since: window.since.toISOString(),
|
|
473
|
+
until: window.until.toISOString(),
|
|
474
|
+
connections: connections ?? [],
|
|
475
|
+
oldestEventAt: result.oldestEventAt?.toISOString() ?? null,
|
|
476
|
+
} satisfies ControlPlaneUsageAllResponse,
|
|
477
|
+
200,
|
|
478
|
+
);
|
|
479
|
+
}
|
|
456
480
|
return c.json(
|
|
457
481
|
{
|
|
458
|
-
connectionId:
|
|
482
|
+
connectionId: named,
|
|
459
483
|
since: window.since.toISOString(),
|
|
460
484
|
until: window.until.toISOString(),
|
|
461
485
|
usage: result.usage.map(controlPlaneUsageView),
|
|
@@ -599,8 +623,8 @@ export function registerAuditRoutes(options: AuditRoutesOptions): (app: Hono<Pit
|
|
|
599
623
|
|
|
600
624
|
/**
|
|
601
625
|
* CONTROL-PLANE READ. Every declared sink beside its own delivery row: one primary-key lookup per sink, bounded
|
|
602
|
-
* by the config.
|
|
603
|
-
*
|
|
626
|
+
* by the config. Records no audit action of its own, unlike the trail's reads: it reads delivery state, never
|
|
627
|
+
* the trail, so the gate's `controlplane/call_allowed` row is its only record.
|
|
604
628
|
*/
|
|
605
629
|
app.get(
|
|
606
630
|
`${base}/control-plane/sinks`,
|
package/src/http/schemas.ts
CHANGED
|
@@ -81,7 +81,19 @@ export const ListAuditEventsQuery = z
|
|
|
81
81
|
),
|
|
82
82
|
action: AuditAction.max(MAX_FILTER_LENGTH)
|
|
83
83
|
.optional()
|
|
84
|
-
.describe("Filter to one exact `domain/reason` action code. Exact
|
|
84
|
+
.describe("Filter to one exact `domain/reason` action code. Exact; `actionPrefix` is the domain-wide filter."),
|
|
85
|
+
actionPrefix: z
|
|
86
|
+
.string()
|
|
87
|
+
.regex(
|
|
88
|
+
/^[a-z][a-z0-9]*\/?$/,
|
|
89
|
+
"An action prefix is one domain, lowercase, with or without its trailing `/` (e.g. `auth` or `auth/`).",
|
|
90
|
+
)
|
|
91
|
+
.max(MAX_FILTER_LENGTH)
|
|
92
|
+
.transform((value) => value.replace(/\/$/, ""))
|
|
93
|
+
.optional()
|
|
94
|
+
.describe(
|
|
95
|
+
"Filter to every action under one domain — `auth` or `auth/` matches `auth/login` and `auth/logout`, never `authority/granted`. The domain is the only prefix: a reason is never matched by its start.",
|
|
96
|
+
),
|
|
85
97
|
outcome: AuditOutcome.optional().describe(
|
|
86
98
|
"Filter to one outcome. `denied` is the one worth watching: a run of denials is what a credential being probed looks like.",
|
|
87
99
|
),
|
|
@@ -191,15 +203,16 @@ export type ControlPlaneReachQuery = z.infer<typeof ControlPlaneReachQuery>;
|
|
|
191
203
|
/**
|
|
192
204
|
* The usage query: whose calls to count, and over what window.
|
|
193
205
|
*
|
|
194
|
-
* `
|
|
195
|
-
*
|
|
196
|
-
*
|
|
197
|
-
*
|
|
206
|
+
* `since` is required, so a missing one is a 400 before any query runs — an unbounded window is not a question this
|
|
207
|
+
* route answers. `connectionId` is optional: named, the route counts that connection's calls; left out, it counts every
|
|
208
|
+
* connection's, which is the over-grant question across a Worker in one read. `until` defaults to now in the
|
|
209
|
+
* handler, which is the one value a schema cannot compute for a request. A window that ends before it starts is
|
|
210
|
+
* refused rather than answered with nothing, because nothing would read as an idle connection.
|
|
198
211
|
*/
|
|
199
212
|
export const ControlPlaneUsageQuery = z
|
|
200
213
|
.object({
|
|
201
|
-
connectionId: FilterValue.describe(
|
|
202
|
-
"The control-plane connection whose calls to count — the `resourceId` its call rows carry.
|
|
214
|
+
connectionId: FilterValue.optional().describe(
|
|
215
|
+
"The control-plane connection whose calls to count — the `resourceId` its call rows carry. Omit it to count every connection's.",
|
|
203
216
|
),
|
|
204
217
|
since: TimeBound.describe("Inclusive lower bound on when a call landed, ISO-8601. Required."),
|
|
205
218
|
until: TimeBound.optional().describe("Inclusive upper bound on when a call landed, ISO-8601. Defaults to now."),
|
|
@@ -208,7 +221,7 @@ export const ControlPlaneUsageQuery = z
|
|
|
208
221
|
message: "`until` must not be before `since`.",
|
|
209
222
|
path: ["until"],
|
|
210
223
|
})
|
|
211
|
-
.describe("The control-plane usage query: one connection, over a window.");
|
|
224
|
+
.describe("The control-plane usage query: one connection or every connection, over a window.");
|
|
212
225
|
export type ControlPlaneUsageQuery = z.infer<typeof ControlPlaneUsageQuery>;
|
|
213
226
|
|
|
214
227
|
/**
|
package/src/http/views.ts
CHANGED
|
@@ -14,6 +14,7 @@ import type {
|
|
|
14
14
|
AuditEventDetailView,
|
|
15
15
|
AuditEventView,
|
|
16
16
|
AuditSinkView,
|
|
17
|
+
ControlPlaneConnectionUsageView,
|
|
17
18
|
ControlPlaneReachSubjectView,
|
|
18
19
|
ControlPlaneReachView,
|
|
19
20
|
ControlPlaneUsageView,
|
|
@@ -212,6 +213,22 @@ export function controlPlaneUsageView(row: ControlPlaneUsageRow): ControlPlaneUs
|
|
|
212
213
|
};
|
|
213
214
|
}
|
|
214
215
|
|
|
216
|
+
/**
|
|
217
|
+
* Fold every connection's usage rows into one entry per connection, in the order the aggregate returned them —
|
|
218
|
+
* by connection, then scope, then key — so each connection's rows keep the order a named read gives them.
|
|
219
|
+
*/
|
|
220
|
+
export function controlPlaneConnectionUsageViews(
|
|
221
|
+
rows: readonly ControlPlaneUsageRow[],
|
|
222
|
+
): ControlPlaneConnectionUsageView[] {
|
|
223
|
+
const byConnection = new Map<string, ControlPlaneUsageView[]>();
|
|
224
|
+
for (const row of rows) {
|
|
225
|
+
const usage = byConnection.get(row.connectionId) ?? [];
|
|
226
|
+
usage.push(controlPlaneUsageView(row));
|
|
227
|
+
byConnection.set(row.connectionId, usage);
|
|
228
|
+
}
|
|
229
|
+
return [...byConnection].map(([connectionId, usage]) => ({ connectionId, usage }));
|
|
230
|
+
}
|
|
231
|
+
|
|
215
232
|
/**
|
|
216
233
|
* Project the declared sinks, in declaration order, each beside its own state row. A sink with no row has never been
|
|
217
234
|
* attempted and answers null times, zero counts and `idle`; a row whose sink is no longer declared is not answered.
|
package/src/query.ts
CHANGED
|
@@ -30,6 +30,8 @@ export interface AuditQuery {
|
|
|
30
30
|
actorKind?: ControlPlaneActorKind;
|
|
31
31
|
/** Match an exact `domain/reason` action code. */
|
|
32
32
|
action?: string;
|
|
33
|
+
/** Match every action under one domain — `auth` matches `auth/login`, never `authority/granted`. */
|
|
34
|
+
actionPrefix?: string;
|
|
33
35
|
/** Match the outcome (`success` | `failure` | `denied`). */
|
|
34
36
|
outcome?: AuditOutcome;
|
|
35
37
|
/** Match the severity (`info` | `warning` | `critical`). */
|
|
@@ -100,6 +102,11 @@ function auditEventQuery(db: AuditDatabase, filter: AuditQuery) {
|
|
|
100
102
|
if (filter.actorId !== undefined) query = query.where("actorId", "=", filter.actorId);
|
|
101
103
|
if (filter.actorKind !== undefined) query = query.where("actorKind", "=", filter.actorKind);
|
|
102
104
|
if (filter.action !== undefined) query = query.where("action", "=", filter.action);
|
|
105
|
+
// A range rather than `LIKE`, so `pithyAuditEventsActionIdx` serves it: every `domain/…` code sorts at or after
|
|
106
|
+
// `domain/` and before `domain0`, because `0` is the character after `/`.
|
|
107
|
+
if (filter.actionPrefix !== undefined) {
|
|
108
|
+
query = query.where("action", ">=", `${filter.actionPrefix}/`).where("action", "<", `${filter.actionPrefix}0`);
|
|
109
|
+
}
|
|
103
110
|
if (filter.outcome !== undefined) query = query.where("outcome", "=", filter.outcome);
|
|
104
111
|
if (filter.severity !== undefined) query = query.where("severity", "=", filter.severity);
|
|
105
112
|
if (filter.resourceType !== undefined) query = query.where("resourceType", "=", filter.resourceType);
|
package/src/usage.ts
CHANGED
|
@@ -8,26 +8,32 @@ import { z } from "zod";
|
|
|
8
8
|
import type { AuditDatabase } from "./data/tables";
|
|
9
9
|
|
|
10
10
|
/**
|
|
11
|
-
* Which scopes a control-plane connection exercised, and which it was refused — `#812
|
|
11
|
+
* Which scopes a control-plane connection exercised, and which it was refused — `#812` — for one connection or every
|
|
12
|
+
* connection at once.
|
|
12
13
|
*
|
|
13
14
|
* Every admitted call writes `controlplane/call_allowed`, and every verified call refused a scope writes
|
|
14
15
|
* `controlplane/call_denied`, both against the connection as `resourceId` and both naming the scope and key in
|
|
15
16
|
* `metadata`. Answering "granted twelve, used three" from the listing would take one forensic read per event, behind
|
|
16
17
|
* the scope that also discloses the client IP; this reads the same rows in SQL and returns counts.
|
|
17
18
|
*
|
|
19
|
+
* **One connection, or every one.** Over-grant — scopes a credential holds and never used — is a question over every
|
|
20
|
+
* connection on the Worker, so leaving the connection out counts them all in the same statement, grouped by connection
|
|
21
|
+
* first. A connection that made no call in the window has no row: the caller joins against the connection listing.
|
|
22
|
+
*
|
|
18
23
|
* **One statement for the aggregate, never a page walk.** A dashboard connection makes thousands of calls a day, and a
|
|
19
24
|
* handler that paged them to count would be the largest read on the surface. The `GROUP BY` runs in D1, over rows
|
|
20
|
-
* `pithyAuditEventsCallIdx` (`audit_0003_call_index`) finds by action, connection and time
|
|
25
|
+
* `pithyAuditEventsCallIdx` (`audit_0003_call_index`) finds by action, connection and time — or, across every
|
|
26
|
+
* connection, rows `pithyAuditEventsOccurredAtIdx` finds by the window.
|
|
21
27
|
*
|
|
22
28
|
* **Nothing personal leaves this function.** It reads the scope, the key id, and the method and path of the last
|
|
23
29
|
* allowed call out of `metadata`, and no other key, and never the IP or the user-agent. Those four are the management
|
|
24
30
|
* client's own footprint.
|
|
25
31
|
*/
|
|
26
32
|
|
|
27
|
-
/** What to count: one connection, over an inclusive window. */
|
|
33
|
+
/** What to count: one connection, or every connection, over an inclusive window. */
|
|
28
34
|
export interface ControlPlaneUsageFilter {
|
|
29
|
-
/** The connection whose calls are counted — the rows' `resourceId`. */
|
|
30
|
-
connectionId
|
|
35
|
+
/** The connection whose calls are counted — the rows' `resourceId`. Absent, every connection's calls are. */
|
|
36
|
+
connectionId?: string;
|
|
31
37
|
/** Inclusive lower bound on `occurredAt`. */
|
|
32
38
|
since: Date;
|
|
33
39
|
/** Inclusive upper bound on `occurredAt`. */
|
|
@@ -47,6 +53,7 @@ const CONNECTION_RESOURCE = "controlplane_connection";
|
|
|
47
53
|
*/
|
|
48
54
|
export const ControlPlaneUsageRow = z
|
|
49
55
|
.object({
|
|
56
|
+
connectionId: z.string().describe("The connection that made the calls — the rows' `resourceId`."),
|
|
50
57
|
scope: z
|
|
51
58
|
.string()
|
|
52
59
|
.describe(
|
|
@@ -75,7 +82,7 @@ const OldestEvent = z
|
|
|
75
82
|
|
|
76
83
|
/** What {@link controlPlaneUsage} answers. */
|
|
77
84
|
export interface ControlPlaneUsage {
|
|
78
|
-
/** One row per `(scope, keyId)` exercised, ordered by scope then key. */
|
|
85
|
+
/** One row per `(connectionId, scope, keyId)` exercised, ordered by connection, then scope, then key. */
|
|
79
86
|
usage: ControlPlaneUsageRow[];
|
|
80
87
|
/** The oldest event the trail holds, or null on an empty trail. */
|
|
81
88
|
oldestEventAt: Date | null;
|
|
@@ -86,13 +93,19 @@ export interface ControlPlaneUsage {
|
|
|
86
93
|
*
|
|
87
94
|
* Three steps, in one statement:
|
|
88
95
|
*
|
|
89
|
-
* 1. **`calls`** — the connection's call rows in the window,
|
|
90
|
-
* `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
|
|
96
|
+
* 1. **`calls`** — the connection's call rows in the window, or every connection's when none is named, with the
|
|
97
|
+
* connection beside the scope, key, method and path lifted out of `metadata`. The scope is read from where each writer puts it: an allowed row carries the token's `scope`; a gate
|
|
91
98
|
* refusal names the scope it required as `required`, and a handler's refusal as `scope`, so a denied row reads
|
|
92
99
|
* `required` first. A row with no scope at all is nobody's usage and is dropped.
|
|
93
|
-
* 2. **`ranked`** — each row's recency within its `(scope, keyId, action)`, newest first, `id`
|
|
94
|
-
* of the allowed rows is the last allowed call, whose method and path the answer carries.
|
|
95
|
-
* 3. **The group** — counts and last instants per `(scope, keyId)`.
|
|
100
|
+
* 2. **`ranked`** — each row's recency within its `(connectionId, scope, keyId, action)`, newest first, `id`
|
|
101
|
+
* breaking a tie. Rank 1 of the allowed rows is the last allowed call, whose method and path the answer carries.
|
|
102
|
+
* 3. **The group** — counts and last instants per `(connectionId, scope, keyId)`.
|
|
103
|
+
*
|
|
104
|
+
* Named, it seeks `pithyAuditEventsCallIdx`: each action, then the connection, then the window as a range. Unnamed,
|
|
105
|
+
* nothing narrows it but the actions and the window, and the window is what is small: an access review reads days of
|
|
106
|
+
* a trail that keeps months. So the planner reads `pithyAuditEventsOccurredAtIdx` over the window and checks the
|
|
107
|
+
* action on each row it finds, and the cost follows the window rather than everything retention holds. A row with no
|
|
108
|
+
* connection — an unverified refusal — is nobody's usage in either.
|
|
96
109
|
*/
|
|
97
110
|
export function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPlaneUsageFilter) {
|
|
98
111
|
const allowed = ControlPlaneAuditActions.callAllowed;
|
|
@@ -105,6 +118,7 @@ export function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPla
|
|
|
105
118
|
"id",
|
|
106
119
|
"action",
|
|
107
120
|
"occurredAt",
|
|
121
|
+
eb.ref("resourceId").as("connectionId"),
|
|
108
122
|
sql<string | null>`case when ${eb.ref("action")} = ${denied}
|
|
109
123
|
then coalesce(json_extract(${eb.ref("metadata")}, '$.required'), json_extract(${eb.ref("metadata")}, '$.scope'))
|
|
110
124
|
else json_extract(${eb.ref("metadata")}, '$.scope') end`.as("scope"),
|
|
@@ -112,9 +126,13 @@ export function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPla
|
|
|
112
126
|
sql<string | null>`json_extract(${eb.ref("metadata")}, '$.method')`.as("method"),
|
|
113
127
|
sql<string | null>`json_extract(${eb.ref("metadata")}, '$.path')`.as("path"),
|
|
114
128
|
])
|
|
115
|
-
// In `pithyAuditEventsCallIdx`'s column order: the actions, the connection,
|
|
129
|
+
// In `pithyAuditEventsCallIdx`'s column order, for the named read: the actions, the connection, the window.
|
|
116
130
|
.where("action", "in", CALL_ACTIONS)
|
|
117
|
-
.where(
|
|
131
|
+
.where((eb) =>
|
|
132
|
+
filter.connectionId === undefined
|
|
133
|
+
? eb("resourceId", "is not", null)
|
|
134
|
+
: eb("resourceId", "=", filter.connectionId),
|
|
135
|
+
)
|
|
118
136
|
.where("occurredAt", ">=", SQLiteDate.encode(filter.since))
|
|
119
137
|
.where("occurredAt", "<=", SQLiteDate.encode(filter.until))
|
|
120
138
|
.where("resourceType", "=", CONNECTION_RESOURCE),
|
|
@@ -125,13 +143,14 @@ export function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPla
|
|
|
125
143
|
.selectAll()
|
|
126
144
|
.select(
|
|
127
145
|
sql<number>`row_number() over (
|
|
128
|
-
partition by ${sql.ref("scope")}, ${sql.ref("keyId")}, ${sql.ref("action")}
|
|
146
|
+
partition by ${sql.ref("connectionId")}, ${sql.ref("scope")}, ${sql.ref("keyId")}, ${sql.ref("action")}
|
|
129
147
|
order by ${sql.ref("occurredAt")} desc, ${sql.ref("id")} desc)`.as("recency"),
|
|
130
148
|
)
|
|
131
149
|
.where("scope", "is not", null),
|
|
132
150
|
)
|
|
133
151
|
.selectFrom("ranked")
|
|
134
152
|
.select((eb) => [
|
|
153
|
+
"connectionId",
|
|
135
154
|
"scope",
|
|
136
155
|
"keyId",
|
|
137
156
|
sql<number>`sum(case when ${eb.ref("action")} = ${allowed} then 1 else 0 end)`.as("allowed"),
|
|
@@ -147,13 +166,15 @@ export function controlPlaneUsageStatement(db: AuditDatabase, filter: ControlPla
|
|
|
147
166
|
"lastDeniedAt",
|
|
148
167
|
),
|
|
149
168
|
])
|
|
150
|
-
.groupBy(["scope", "keyId"])
|
|
169
|
+
.groupBy(["connectionId", "scope", "keyId"])
|
|
170
|
+
.orderBy("connectionId")
|
|
151
171
|
.orderBy("scope")
|
|
152
172
|
.orderBy("keyId");
|
|
153
173
|
}
|
|
154
174
|
|
|
155
175
|
/**
|
|
156
|
-
* Count one connection's calls by scope and key, over an
|
|
176
|
+
* Count one connection's calls by scope and key, or every connection's by connection, scope and key, over an
|
|
177
|
+
* inclusive window.
|
|
157
178
|
*
|
|
158
179
|
* `oldestEventAt` is the oldest event the trail holds at all, for any connection or none. Retention prunes the trail
|
|
159
180
|
* by time, never per connection, so this is how far back any connection's answer can reach: a window starting before
|
package/src/version.generated.ts
CHANGED