audit-catalog.ts

audit-catalog.tspackages/shared/src/events/audit-catalog.tsraw ← events5,007 B← Back to the app
1/**
2 * @factory/shared — the MANDATORY AUDIT-EVENT catalog (TASK-0133).
3 *
4 * Single source of truth for the PRODUCT-SPEC §23 mandatory audit events
5 * (plus the phase-12/13 security-mandatory additions). Two consumers:
6 *
7 * 1. `tests/integration/audit-completeness/` — the completeness test imports
8 *    this table and, for EVERY entry, performs the `fire` operation in a
9 *    seeded workspace/org and asserts an `AuditLog` row with the `name`
10 *    action + every `metadata` field present. A missing emitter fails the
11 *    build (the phase exit criterion "audit log covers all mandatory events").
12 * 2. The audit viewer's action autocomplete (the org-admin API reads the same
13 *    list server-side via `@factory/shared`).
14 *
15 * `metadata` lists the REQUIRED metadata fields — the catalog is the
16 * contract, so an emitter that drops a listed field fails the completeness
17 * test. Fields the emitter carries that are NOT listed are fine.
18 */
19 
20export interface AuditCatalogEntry {
21  /** The exact `AuditLog.action` string. */
22  name: string;
23  /** One-line description (docs + UI autocomplete). */
24  description: string;
25  /**
26   * The operation that must fire it. The completeness test keys its dispatch
27   * table off this id, so it is part of the contract (renaming it is a
28   * breaking change for the test).
29   */
30  fire: string;
31  /** Required `AuditLog.metadata` fields. */
32  metadata: string[];
33}
34 
35export const AUDIT_CATALOG: AuditCatalogEntry[] = [
36  {
37    name: "user.login",
38    description: "Successful password sign-in.",
39    fire: "login",
40    metadata: ["email"]
41  },
42  {
43    name: "page.created",
44    description: "A page was created.",
45    fire: "page.create",
46    metadata: ["title", "parentId", "type"]
47  },
48  {
49    name: "page.updated",
50    description: "A page's title/content changed.",
51    fire: "page.update",
52    metadata: []
53  },
54  {
55    name: "page.deleted",
56    description: "A page was trashed (soft delete; descendants included).",
57    fire: "page.trash",
58    metadata: ["pageIds"]
59  },
60  {
61    name: "page.shared",
62    description: "A share (public or per-user) was created for a page/database.",
63    fire: "share.create",
64    metadata: ["targetType", "targetId", "scope"]
65  },
66  {
67    name: "permission.changed",
68    description: "A permission or membership role changed (workspace/team/file).",
69    fire: "permission.change",
70    metadata: ["change", "targetId"]
71  },
72  {
73    name: "database.created",
74    description: "A database was created (page with a database block).",
75    fire: "database.create",
76    metadata: ["title"]
77  },
78  {
79    name: "record.created",
80    description: "A record was inserted into a database.",
81    fire: "record.create",
82    metadata: ["databaseId"]
83  },
84  {
85    name: "record.updated",
86    description: "A record's properties changed.",
87    fire: "record.update",
88    metadata: ["databaseId"]
89  },
90  {
91    name: "file.uploaded",
92    description: "A file was uploaded (first version).",
93    fire: "file.upload",
94    metadata: ["name", "size"]
95  },
96  {
97    name: "automation.executed",
98    description: "An automation run reached a terminal state (worker).",
99    fire: "automation.run",
100    metadata: ["automationId", "runId", "status"]
101  },
102  {
103    name: "api_key.created",
104    description: "A workspace API key was created (the raw key is never audited).",
105    fire: "api_key.create",
106    metadata: ["name", "scopes"]
107  },
108  {
109    name: "ai.budget_exceeded",
110    description: "The AI monthly budget was exceeded (call denied).",
111    fire: "ai.budget",
112    metadata: ["used", "limit"]
113  },
114  {
115    name: "oauth.token_issued",
116    description: "An OAuth2 token was issued (authorization code or refresh).",
117    fire: "oauth.token",
118    metadata: ["clientId", "scopes"]
119  },
120  {
121    name: "oauth.token_revoked",
122    description: "An OAuth2 token (family) was revoked.",
123    fire: "oauth.revoke",
124    metadata: ["clientId"]
125  },
126  {
127    name: "sso.login.saml",
128    description: "A user signed in via SAML SSO.",
129    fire: "sso.saml",
130    metadata: ["orgId", "nameId"]
131  },
132  {
133    name: "sso.login.oidc",
134    description: "A user signed in via OIDC SSO.",
135    fire: "sso.oidc",
136    metadata: ["orgId", "nameId"]
137  },
138  {
139    name: "scim.user.created",
140    description: "SCIM provisioned a user into the organization.",
141    fire: "scim.create",
142    metadata: ["userId", "email", "role"]
143  },
144  {
145    name: "scim.user.deactivated",
146    description: "SCIM deprovisioned (suspended) a user.",
147    fire: "scim.deactivate",
148    metadata: ["userId", "via"]
149  },
150  {
151    name: "webhook.created",
152    description: "A workspace webhook was created.",
153    fire: "webhook.create",
154    metadata: ["url", "events"]
155  },
156  {
157    name: "webhook.revoked",
158    description: "A workspace webhook was revoked (soft delete).",
159    fire: "webhook.revoke",
160    metadata: ["url"]
161  }
162] as const;
163 
164/** The exact action strings (autocomplete + completeness assertions). */
165export const AUDIT_CATALOG_NAMES: readonly string[] = AUDIT_CATALOG.map((e) => e.name);
166