diff --git a/README.md b/README.md index d562575..74227b2 100644 --- a/README.md +++ b/README.md @@ -62,17 +62,22 @@ The IdP notifies `POST /internal/events` when access changes; the backend also p `common_audit_events` records who used which permission to change what through the backend. The tRPC audit middleware (`src/audit`) writes one event per mutation: the action (the procedure path), the caller from the token, the target, the outcome (`success`, `failure` when an error is thrown or returned, `denied` when the policy refuses the caller), the -request id shared by the calls of one HTTP request, and when. Handlers add the target and the state before and after -with `ctx.audit.set(...)`, or `ctx.audit.skip()` when a call changed nothing. Inputs and states are stored without -secrets (`password`, `token`, `ticket`, `code`, `*Key`, `*Secret` fields) or file contents, and are cut when too large. -Denied calls keep no input. Calls without a valid token are not recorded. - -Areas with their own history keep the details there, readable with their own permissions: - -- People: events name the actor, the action, the person and the outcome, without the input or the states; what changed - is in the person's activity history. -- Telegram moderation: kept in `tg_audit_log` under its own retention rules and not copied here, like the bot's - ingestion (`tg.messages.add`, `tg.users.add`). +request id shared by the calls of one HTTP request, and when. Calls without a valid token are not recorded. + +Every mutation declares how it is recorded in its procedure meta, and a test walks the router so that none ships +without one, like its policy: + +- `.meta(audit.full())`: also the input, the reason and the states before and after that the handler adds with + `ctx.audit.set(...)`. `fields` keeps only those fields of the input, for inputs that carry personal data or free + text not worth keeping. +- `.meta(audit.minimal({ target }))`: only the actor, the action, the target and the outcome, for areas that keep their + own history behind their own permissions. People records each change in the person's activity history. +- `.meta(audit.none(why))`: not recorded, e.g. the bot's ingestion, or Telegram moderation, which `tg_audit_log` keeps + under its own retention rules. + +Handlers call `ctx.audit.skip()` when a call changed nothing. Inputs and states are stored without secrets +(`password`, `token`, `ticket`, `code`, `*Key`, `*Secret` fields) or file contents, and are cut when too large. Denied +calls keep no input. Events are deleted 24 months after they were written (`AUDIT_EVENTS_RETENTION_MONTHS`). Dashboard users with the IdP permission `audit:read` read the log with `audit.list`, newest first, paged by `cursor` and filtered by area, outcome, diff --git a/src/audit/index.ts b/src/audit/index.ts index 300f024..4b8bc75 100644 --- a/src/audit/index.ts +++ b/src/audit/index.ts @@ -9,15 +9,10 @@ import { type TAuditOutcome, } from "@/db/schema/common/audit-events" import type { RequestAuth } from "@/idp/auth" -import { personIdSchema } from "@/people/contract" +import type { AuditOption, AuditTarget } from "./option" export type AuditEvent = typeof auditEvents.$inferInsert - -/** - * What a change was made to; `label` is a readable name, kept as it was at the time. `id` is null when the call acts - * on several records, which are then named in the input. - */ -export type AuditTarget = { type: string; id: string | number | null; label?: string | null } +export { type AuditOption, type AuditTarget, type AuditTargetOf, audit } from "./option" export type AuditActor = { kind: TAuditActorKind; sub?: string | null; tgId?: number | null; client?: string | null } @@ -37,19 +32,8 @@ export type AuditRecorder = { skip: () => void } -/** - * Mutations that are not changes made by someone: the bot's high-volume ingestion and per-visit syncs. Moderation the - * bot reports is kept in `tg_audit_log`, under its own retention rules, and not copied here. - */ -export const UNAUDITED = new Set(["tg.messages.add", "tg.users.add", "tg.auditLog.record", "esign.profile.sync"]) - -/** - * Areas that keep their own history, readable with their own permissions: their events name the actor, the action, - * the target and the outcome, without the input or the state before and after. - * - * Temporary: a per-procedure `audit` option in the procedure meta replaces this list. - */ -const MINIMAL_AREAS = [{ prefix: "people.", targetType: "people.person" }] +/** For a mutation without an option, which the router test keeps from shipping: the option that stores the least. */ +export const UNDECLARED: AuditOption = { capture: "minimal" } /** Handed to queries, which change nothing. */ export const noAudit: AuditRecorder = { set: () => {}, skip: () => {} } @@ -175,14 +159,10 @@ function outcomeOf(result: Result): { outcome: TAuditOutcome; error: string | nu return error === null ? { outcome: AUDIT_OUTCOME.SUCCESS, error: null } : { outcome: AUDIT_OUTCOME.FAILURE, error } } -/** The first of `keys` that `value` holds as a valid People id: raw inputs are not validated yet. */ -function personIdIn(value: unknown, keys: string[]): string | null { - if (value === null || typeof value !== "object") return null - for (const key of keys) { - const id = personIdSchema.safeParse((value as Record)[key]) - if (id.success) return id.data - } - return null +/** Only `fields` of a copied input, when it is an object. */ +function onlyFields(copy: AuditJson, fields: readonly string[] | undefined): AuditJson { + if (!fields || copy === null || typeof copy !== "object" || Array.isArray(copy)) return copy + return Object.fromEntries(fields.flatMap((field) => (field in copy ? [[field, copy[field] ?? null]] : []))) } /** @@ -191,49 +171,49 @@ function personIdIn(value: unknown, keys: string[]): string | null { */ export function auditEvent(options: { path: string + option?: AuditOption auth: RequestAuth | undefined requestId?: string | null rawInput: unknown note: AuditNote result: Result }): AuditEvent | null { - const { path, auth, note, result } = options - const actor = actorOf(auth) + const { path, note, result } = options + const option = options.option ?? UNDECLARED + if (option.capture === "none") return null + const actor = actorOf(options.auth) if (!actor) return null const { outcome, error } = outcomeOf(result) - const targetId = note.target?.id == null ? null : String(note.target.id) + // What the handler names wins over the option's target, which only sees the raw input and the result. + const target = + note.target ?? option.target?.({ input: options.rawInput, data: result.ok ? result.data : undefined }) ?? undefined + const targetId = target?.id == null ? null : String(target.id) const event: AuditEvent = { - action: note.action ?? path, + action: note.action ?? option.action ?? path, requestId: options.requestId ?? null, actorKind: actor.kind, actorSub: actor.sub ?? null, actorTgId: actor.tgId ?? null, actorClient: actor.client ?? null, - targetType: note.target?.type ?? null, + targetType: target?.type ?? null, targetId: cut(targetId), - targetLabel: cut(note.target?.label ?? null), - reason: cut(note.reason ?? null), + targetLabel: cut(target?.label ?? null), + reason: null, outcome, error, - // A refused call changed nothing, and its input is whatever the caller chose to send. - input: outcome === AUDIT_OUTCOME.DENIED ? null : auditJson(options.rawInput), - before: note.before === undefined ? null : auditJson(note.before), - after: note.after === undefined ? null : auditJson(note.after), + input: null, + before: null, + after: null, } + if (option.capture === "minimal") return event - const minimal = MINIMAL_AREAS.find((area) => path.startsWith(area.prefix)) - if (!minimal) return event - const id = - personIdIn(options.rawInput, ["personId", "id"]) ?? (result.ok ? personIdIn(result.data, ["personId", "id"]) : null) return { ...event, - targetType: minimal.targetType, - targetId: id, - targetLabel: null, - reason: null, - input: null, - before: null, - after: null, + reason: cut(note.reason ?? null), + // A refused call changed nothing, and its input is whatever the caller chose to send. + input: outcome === AUDIT_OUTCOME.DENIED ? null : onlyFields(auditJson(options.rawInput), option.fields), + before: note.before === undefined ? null : auditJson(note.before), + after: note.after === undefined ? null : auditJson(note.after), } } diff --git a/src/audit/option.ts b/src/audit/option.ts new file mode 100644 index 0000000..1d996f8 --- /dev/null +++ b/src/audit/option.ts @@ -0,0 +1,42 @@ +// No imports: routers declare their audit options with this module without loading the database schema. + +/** + * What a change was made to; `label` is a readable name, kept as it was at the time. `id` is null when the call acts + * on several records, which are then named in the input. + */ +export type AuditTarget = { type: string; id: string | number | null; label?: string | null } + +/** + * The target of a call, from its input and, once it succeeded, its result. The input is the raw one, not yet validated + * (and undefined for denied calls, whose body is not read), so a target function checks what it takes from it. + */ +export type AuditTargetOf = (call: { input: unknown; data: unknown }) => AuditTarget | null + +/** + * How a mutation is recorded, declared in its procedure meta with `.meta(audit.full())` and the like. A test walks the + * router so that every mutation declares one. + */ +export type AuditOption = + /** Not recorded; `why` says why, e.g. the bot's ingestion or an area that keeps its own log. */ + | { capture: "none"; why: string } + /** + * The actor, the action, the target and the outcome, without the input, the states or the reason: for areas that + * keep their own history, readable with their own permissions. + */ + | { capture: "minimal"; target?: AuditTargetOf; action?: string } + /** + * Also the input, the states the handler adds and the reason. `fields` keeps only those fields of the input, for + * inputs that carry personal data or free text not worth keeping. + */ + | { capture: "full"; fields?: readonly string[]; target?: AuditTargetOf; action?: string } + +/** Procedure meta for each way of recording a mutation. */ +export const audit = { + full: (options: Omit, "capture"> = {}) => ({ + audit: { capture: "full", ...options } satisfies AuditOption, + }), + minimal: (options: Omit, "capture"> = {}) => ({ + audit: { capture: "minimal", ...options } satisfies AuditOption, + }), + none: (why: string) => ({ audit: { capture: "none", why } satisfies AuditOption }), +} diff --git a/src/people/router.ts b/src/people/router.ts index 8f09c70..31864df 100644 --- a/src/people/router.ts +++ b/src/people/router.ts @@ -1,5 +1,6 @@ import { TRPCError } from "@trpc/server" import { z } from "zod" +import { type AuditTargetOf, audit } from "@/audit/option" import { SCOPE } from "@/idp/policies" import { createTRPCRouter, policy } from "@/trpc" import * as C from "./contract" @@ -7,6 +8,21 @@ import { requireGeneral } from "./model" import type { PeopleService } from "./service" import type { Viewer } from "./types" +/** + * The person a People call is about: the input's `personId` or `id`, else the created record's. The raw input is not + * validated yet, so only a valid People id is taken from it. + */ +const personTarget: AuditTargetOf = ({ input, data }) => { + for (const value of [input, data]) { + if (value === null || typeof value !== "object") continue + for (const key of ["personId", "id"]) { + const id = C.personIdSchema.safeParse((value as Record)[key]) + if (id.success) return { type: "people.person", id: id.data } + } + } + return { type: "people.person", id: null } +} + /** * Factory keeps policy and shape tests independent of databases and external services. * @@ -14,20 +30,24 @@ import type { Viewer } from "./types" * are open to every dashboard user here, since a team's Lead may add and remove its members. */ export function createPeopleRouter(people: PeopleService) { - const user = policy({ user: { scope: SCOPE.admin } }).use(async ({ ctx, next }) => { - if (ctx.actor.kind !== "user") throw new TRPCError({ code: "FORBIDDEN" }) - const sub = ctx.actor.sub - const viewer: Viewer = { - sub, - telegramId: ctx.actor.telegramId, - can: ctx.can, - holdsRole: (role) => { - const index = ctx.access?.current() - return !!index && index.hasRole(index.bySub(sub), role) - }, - } - return next({ ctx: { viewer } }) - }) + // People keeps each record's history in `people_activity`, behind its own permissions: the audit log only says who + // changed which record, and whether it worked. + const user = policy({ user: { scope: SCOPE.admin } }) + .meta(audit.minimal({ target: personTarget })) + .use(async ({ ctx, next }) => { + if (ctx.actor.kind !== "user") throw new TRPCError({ code: "FORBIDDEN" }) + const sub = ctx.actor.sub + const viewer: Viewer = { + sub, + telegramId: ctx.actor.telegramId, + can: ctx.can, + holdsRole: (role) => { + const index = ctx.access?.current() + return !!index && index.hasRole(index.bySub(sub), role) + }, + } + return next({ ctx: { viewer } }) + }) const admin = (permission: string) => user.use(({ ctx, next }) => { requireGeneral(ctx.viewer, permission) diff --git a/src/routers/azure/members.ts b/src/routers/azure/members.ts index 33b7b21..c12874a 100644 --- a/src/routers/azure/members.ts +++ b/src/routers/azure/members.ts @@ -1,5 +1,6 @@ import type { Actor } from "@polinetwork/auth-kit" import z from "zod" +import { audit } from "@/audit/option" import { azureDirectory } from "@/azure/directory" import { IncompleteMemberError, safeErrorDetail } from "@/azure/errors" import { MAIL_DOMAIN, mailboxLocalPart, mailboxSchema } from "@/azure/mailbox" @@ -40,6 +41,7 @@ export default createTRPCRouter({ * optionally email the new number. Token callers only: it can send mail to a caller-supplied address. */ setAssocNumber: policy(dashboard("azure:members:write")) + .meta(audit.full({ fields: ["userId", "assocNumber"] })) .input( z.object({ userId: z.string().min(1), @@ -121,6 +123,7 @@ export default createTRPCRouter({ * caller-supplied group or existing user. The address is `firstname.lastname` unless a custom one is chosen. */ create: policy(dashboard("azure:members:create")) + .meta(audit.full({ fields: ["assocNumber", "mailbox"] })) .input( z.object({ firstName: personName, @@ -187,7 +190,7 @@ export default createTRPCRouter({ logger.info({ by, memberId: member.id, assocNumber: input.assocNumber }, "[AZURE] member created") ctx.audit.set({ target: { type: "azure.member", id: member.id, label: name }, - after: { id: member.id, email: member.mail, assocNumber: input.assocNumber }, + after: { id: member.id, assocNumber: input.assocNumber }, }) let mailOk = false diff --git a/src/routers/esign.ts b/src/routers/esign.ts index 95cc562..0fb0276 100644 --- a/src/routers/esign.ts +++ b/src/routers/esign.ts @@ -2,6 +2,7 @@ import type { Actor } from "@polinetwork/auth-kit" import { TRPCError } from "@trpc/server" import { z } from "zod" import type { AuditRecorder } from "@/audit" +import { audit } from "@/audit/option" import { esign } from "@/esign" import { MAX_PDF_BYTES } from "@/esign/drive/types" import { EsignError, type EsignErrorCode } from "@/esign/errors" @@ -90,6 +91,7 @@ export const esignRouter = createTRPCRouter({ profile: createTRPCRouter({ /** The BFF passes the signed-in user's name and email from the ID token. */ sync: user + .meta(audit.none("Copies the signed-in user's name and email on each visit, not a change made by someone")) .input(z.object({ name: z.string().min(1).max(200), email: z.email().nullable() })) .mutation(({ ctx, input }) => run(() => esign.syncProfile(callerOf(ctx), input))), }), @@ -100,11 +102,14 @@ export const esignRouter = createTRPCRouter({ return run(() => esign.listProfiles()) }), /** Forgets the CIE bound to a person, e.g. after they renewed their card. */ - resetIdentity: user.input(z.object({ sub: z.string().min(1) })).mutation(({ ctx, input }) => { - requireManage(callerOf(ctx)) - ctx.audit.set({ target: { type: "esign.signer", id: input.sub } }) - return run(() => esign.resetIdentity(input.sub)) - }), + resetIdentity: user + .meta(audit.full()) + .input(z.object({ sub: z.string().min(1) })) + .mutation(({ ctx, input }) => { + requireManage(callerOf(ctx)) + ctx.audit.set({ target: { type: "esign.signer", id: input.sub } }) + return run(() => esign.resetIdentity(input.sub)) + }), }), drive: createTRPCRouter({ @@ -121,6 +126,7 @@ export const esignRouter = createTRPCRouter({ .input(z.object({ driveId: z.string().min(1), sign: driveRule })) .query(({ ctx, input }) => run(() => esign.driveAccessImpact(callerOf(ctx), input.driveId, input.sign))), setAccess: user + .meta(audit.full()) .input(z.object({ driveId: z.string().min(1), request: driveRule, sign: driveRule })) .mutation(async ({ ctx, input }) => { const caller = callerOf(ctx) @@ -138,6 +144,7 @@ export const esignRouter = createTRPCRouter({ documents: createTRPCRouter({ upload: user + .meta(audit.full()) .input( z .instanceof(FormData) @@ -157,6 +164,7 @@ export const esignRouter = createTRPCRouter({ return { document, pdf: publicPdf(pdf) } }), fromDrive: user + .meta(audit.full()) .input(z.object({ driveId: z.string().min(1), itemId: z.string().min(1) })) .mutation(async ({ ctx, input }) => { const caller = callerOf(ctx) @@ -182,6 +190,7 @@ export const esignRouter = createTRPCRouter({ requests: createTRPCRouter({ create: user + .meta(audit.full({ fields: ["title", "documentId", "ordered", "signers", "output"] })) .input( z.object({ title: z.string().trim().min(1).max(200), @@ -213,7 +222,22 @@ export const esignRouter = createTRPCRouter({ .mutation(async ({ ctx, input }) => { ctx.audit.set({ target: { type: "esign.document", id: input.documentId, label: input.title } }) const request = await run(() => esign.createRequest(callerOf(ctx), input)) - ctx.audit.set({ target: { type: "esign.request", id: request.id, label: request.title }, after: request }) + // Who signs, in which order: not their fiscal codes, certificates or the email recipients. + ctx.audit.set({ + target: { type: "esign.request", id: request.id, label: request.title }, + after: { + id: request.id, + title: request.title, + status: request.status, + ordered: request.ordered, + drives: request.drives, + signers: request.signers.map((signer) => ({ + sub: signer.sub, + role: signer.role, + position: signer.position, + })), + }, + }) return request }), list: user @@ -222,15 +246,22 @@ export const esignRouter = createTRPCRouter({ get: user .input(z.object({ id: z.uuid() })) .query(({ ctx, input }) => run(() => esign.getRequest(callerOf(ctx), input.id))), - cancel: user.input(z.object({ id: z.uuid() })).mutation(async ({ ctx, input }) => { - await auditRequest(ctx, input.id) - return run(() => esign.cancelRequest(callerOf(ctx), input.id)) - }), - delete: user.input(z.object({ id: z.uuid() })).mutation(async ({ ctx, input }) => { - await auditRequest(ctx, input.id) - return run(() => esign.deleteRequest(callerOf(ctx), input.id)) - }), + cancel: user + .meta(audit.full()) + .input(z.object({ id: z.uuid() })) + .mutation(async ({ ctx, input }) => { + await auditRequest(ctx, input.id) + return run(() => esign.cancelRequest(callerOf(ctx), input.id)) + }), + delete: user + .meta(audit.full()) + .input(z.object({ id: z.uuid() })) + .mutation(async ({ ctx, input }) => { + await auditRequest(ctx, input.id) + return run(() => esign.deleteRequest(callerOf(ctx), input.id)) + }), decline: user + .meta(audit.full({ fields: ["id"] })) .input(z.object({ id: z.uuid(), reason: z.string().max(500).nullable() })) .mutation(async ({ ctx, input }) => { await auditRequest(ctx, input.id) @@ -242,6 +273,7 @@ export const esignRouter = createTRPCRouter({ * once no deployed dashboard calls it, this and the service's `uploadSigned` can be removed. */ uploadSigned: user + .meta(audit.full()) .input( z .instanceof(FormData) @@ -259,10 +291,13 @@ export const esignRouter = createTRPCRouter({ esign.uploadSigned(callerOf(ctx), input.requestId, new Uint8Array(await input.file.arrayBuffer())) ) }), - retryDelivery: user.input(z.object({ id: z.uuid() })).mutation(async ({ ctx, input }) => { - await auditRequest(ctx, input.id) - return run(() => esign.retryDelivery(callerOf(ctx), input.id)) - }), + retryDelivery: user + .meta(audit.full()) + .input(z.object({ id: z.uuid() })) + .mutation(async ({ ctx, input }) => { + await auditRequest(ctx, input.id) + return run(() => esign.retryDelivery(callerOf(ctx), input.id)) + }), }), jobs: createTRPCRouter({ @@ -271,6 +306,7 @@ export const esignRouter = createTRPCRouter({ * ticket, so one PIN signs them all. `places` moves the caller's boxes before signing, one per place, in order. */ create: user + .meta(audit.full()) .input( z.object({ items: z @@ -293,10 +329,13 @@ export const esignRouter = createTRPCRouter({ statuses: user .input(z.object({ jobIds: z.array(z.uuid()).min(1).max(10) })) .query(({ ctx, input }) => run(() => esign.jobStatuses(callerOf(ctx), input.jobIds))), - cancel: user.input(z.object({ jobIds: z.array(z.uuid()).min(1).max(10) })).mutation(({ ctx, input }) => - run(async () => { - for (const jobId of input.jobIds) await esign.cancelJob(callerOf(ctx), jobId) - }) - ), + cancel: user + .meta(audit.full()) + .input(z.object({ jobIds: z.array(z.uuid()).min(1).max(10) })) + .mutation(({ ctx, input }) => + run(async () => { + for (const jobId of input.jobIds) await esign.cancelJob(callerOf(ctx), jobId) + }) + ), }), }) diff --git a/src/routers/groups/labels.ts b/src/routers/groups/labels.ts index 0308792..b5260ff 100644 --- a/src/routers/groups/labels.ts +++ b/src/routers/groups/labels.ts @@ -1,5 +1,6 @@ import { and, eq, sql } from "drizzle-orm" import { z } from "zod" +import { audit } from "@/audit/option" import { DB, SCHEMA } from "@/db" import { authorOf } from "@/idp/author" import { dashboard } from "@/idp/policies" @@ -32,6 +33,7 @@ export default createTRPCRouter({ }), create: policy(dashboard("groups:labels:write")) + .meta(audit.full()) .input( z.object({ label, @@ -57,6 +59,7 @@ export default createTRPCRouter({ }), delete: policy(dashboard("groups:labels:write")) + .meta(audit.full()) .input( z.object({ label, @@ -93,6 +96,7 @@ export default createTRPCRouter({ }), modify: policy(dashboard("groups:labels:write")) + .meta(audit.full()) .input( z.object({ label, @@ -132,6 +136,7 @@ export default createTRPCRouter({ }), tagGroup: policy(dashboard("groups:labels:write")) + .meta(audit.full()) .input( z.object({ groupId: z.number(), @@ -160,6 +165,7 @@ export default createTRPCRouter({ }), untagGroup: policy(dashboard("groups:labels:write")) + .meta(audit.full()) .input( z.object({ groupId: z.number(), diff --git a/src/routers/tg/audit-log.ts b/src/routers/tg/audit-log.ts index 7251a08..558a268 100644 --- a/src/routers/tg/audit-log.ts +++ b/src/routers/tg/audit-log.ts @@ -2,6 +2,7 @@ import { TRPCError } from "@trpc/server" import { desc, eq } from "drizzle-orm" import { alias } from "drizzle-orm/pg-core" import { z } from "zod" +import { audit } from "@/audit/option" import { DB, SCHEMA } from "@/db" import { ARRAY_AUDIT_TYPE, @@ -44,6 +45,7 @@ export default createTRPCRouter({ * `idempotencyKey` records nothing and returns the first record. */ record: policy({ service: { scope: SCOPE.tgAudit } }) + .meta(audit.none("Moderation is kept in tg_audit_log, under its own retention rules")) .input( z .object({ diff --git a/src/routers/tg/grants.ts b/src/routers/tg/grants.ts index 5316b27..d11f149 100644 --- a/src/routers/tg/grants.ts +++ b/src/routers/tg/grants.ts @@ -1,6 +1,7 @@ import { TRPCError } from "@trpc/server" import { and, eq, gt, inArray, isNull } from "drizzle-orm" import { z } from "zod" +import { audit } from "@/audit/option" import { DB, SCHEMA } from "@/db" import { describeActor } from "@/idp/actor-info" import { ACT_AS_SCOPE } from "@/idp/auth" @@ -53,6 +54,7 @@ export default createTRPCRouter({ * grantor is the token's user. */ create: policy(dashboard("tg:grants:manage")) + .meta(audit.full()) .input( z.object({ userId: z.number(), @@ -121,6 +123,7 @@ export default createTRPCRouter({ telegram: { scope: ACT_AS_SCOPE, permission: "tg:grants:manage" }, ...dashboard("tg:grants:manage"), }) + .meta(audit.full()) .input( z.object({ userId: z.number(), diff --git a/src/routers/tg/groups.ts b/src/routers/tg/groups.ts index f65fe29..7ee1ec9 100644 --- a/src/routers/tg/groups.ts +++ b/src/routers/tg/groups.ts @@ -1,5 +1,6 @@ import { and, eq, exists, ilike, inArray, ne, not, notExists, or, type SQL, sql } from "drizzle-orm" import { z } from "zod" +import { audit } from "@/audit/option" import { DB, SCHEMA } from "@/db" import { describeActor } from "@/idp/actor-info" import { botReadOrDashboard, dashboard, SCOPE, seesHiddenGroups } from "@/idp/policies" @@ -153,6 +154,7 @@ export default createTRPCRouter({ }), create: policy({ service: { scope: SCOPE.tgGroupsSync } }) + .meta(audit.full()) .input( z.array( z.object({ @@ -224,6 +226,7 @@ export default createTRPCRouter({ }), delete: policy({ service: { scope: SCOPE.tgGroupsSync } }) + .meta(audit.full()) .input( z.object({ telegramId: z.number(), @@ -237,6 +240,7 @@ export default createTRPCRouter({ }), setHide: policy(dashboard("tg:groups:manage")) + .meta(audit.full()) .input( z.object({ telegramId: z.number(), @@ -263,6 +267,7 @@ export default createTRPCRouter({ /** The performer is the token's user. */ leaveChat: policy(dashboard("tg:groups:manage")) + .meta(audit.full()) .input( z.object({ chatId: z.number(), diff --git a/src/routers/tg/messages.ts b/src/routers/tg/messages.ts index 13fb7e7..7198c27 100644 --- a/src/routers/tg/messages.ts +++ b/src/routers/tg/messages.ts @@ -1,5 +1,6 @@ import { and, desc, eq } from "drizzle-orm" import { z } from "zod" +import { audit } from "@/audit/option" import { DB, SCHEMA } from "@/db" import { botReadOrDashboard, SCOPE } from "@/idp/policies" import { logger } from "@/logger" @@ -78,6 +79,7 @@ export default createTRPCRouter({ }), add: policy({ service: { scope: SCOPE.tgIngest } }) + .meta(audit.none("The bot's ingestion of group messages, not changes made by someone")) .input(z.object({ messages: z.array(message) })) .output(z.object({ error: z.union([z.null(), z.enum(["ENCRYPT_ERROR"])]) })) .mutation(async ({ input }) => { diff --git a/src/routers/tg/users.ts b/src/routers/tg/users.ts index a458289..8fbbb15 100644 --- a/src/routers/tg/users.ts +++ b/src/routers/tg/users.ts @@ -1,5 +1,6 @@ import { count, eq, sql } from "drizzle-orm" import { z } from "zod" +import { audit } from "@/audit/option" import { DB, SCHEMA } from "@/db" import { botReadOrDashboard, dashboard, SCOPE } from "@/idp/policies" import { logger } from "@/logger" @@ -138,6 +139,7 @@ export default createTRPCRouter({ }), add: policy({ service: { scope: SCOPE.tgIngest } }) + .meta(audit.none("The bot's ingestion of the users it sees, not changes made by someone")) .input(z.object({ users: z.array(TgUserSchema) })) .output( z.union([ diff --git a/src/routers/wa/groups.ts b/src/routers/wa/groups.ts index a93b53f..9aa14d6 100644 --- a/src/routers/wa/groups.ts +++ b/src/routers/wa/groups.ts @@ -1,5 +1,6 @@ import { eq } from "drizzle-orm" import { z } from "zod" +import { audit } from "@/audit/option" import { DB, SCHEMA } from "@/db" import { dashboard } from "@/idp/policies" import { createTRPCRouter, policy } from "@/trpc" @@ -45,6 +46,7 @@ export default createTRPCRouter({ }), add: policy(dashboard("wa:groups:manage")) + .meta(audit.full()) .input( z.object({ title: z.string(), @@ -59,6 +61,7 @@ export default createTRPCRouter({ }), modify: policy(dashboard("wa:groups:manage")) + .meta(audit.full()) .input( z.object({ id: z.number(), @@ -81,6 +84,7 @@ export default createTRPCRouter({ }), delete: policy(dashboard("wa:groups:manage")) + .meta(audit.full()) .input( z.object({ id: z.number(), @@ -94,6 +98,7 @@ export default createTRPCRouter({ }), setHide: policy(dashboard("wa:groups:manage")) + .meta(audit.full()) .input( z.object({ id: z.number(), diff --git a/src/routers/web/associations.ts b/src/routers/web/associations.ts index 992ffd8..8726f53 100644 --- a/src/routers/web/associations.ts +++ b/src/routers/web/associations.ts @@ -1,5 +1,6 @@ import { asc, eq } from "drizzle-orm" import z from "zod" +import { audit } from "@/audit/option" import { uploadBlob } from "@/azure/blob" import { DB, SCHEMA } from "@/db" import { authorOf, createdByColumns, modifiedByColumns } from "@/idp/author" @@ -76,6 +77,7 @@ export default createTRPCRouter({ }), addAssociation: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z .instanceof(FormData) @@ -104,6 +106,7 @@ export default createTRPCRouter({ }), editAssociation: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z .instanceof(FormData) @@ -143,6 +146,7 @@ export default createTRPCRouter({ }), editAssociationLinks: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z.object({ id: z.number(), @@ -181,6 +185,7 @@ export default createTRPCRouter({ }), deleteAssociation: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z.object({ id: z.number(), diff --git a/src/routers/web/faqs.ts b/src/routers/web/faqs.ts index ca44be9..efc0dd6 100644 --- a/src/routers/web/faqs.ts +++ b/src/routers/web/faqs.ts @@ -1,5 +1,6 @@ import { asc, eq, sql } from "drizzle-orm" import z from "zod" +import { audit } from "@/audit/option" import { DB, SCHEMA } from "@/db" import { authorOf, createdByColumns, modifiedByColumns } from "@/idp/author" import { dashboard, publicData } from "@/idp/policies" @@ -55,6 +56,7 @@ export default createTRPCRouter({ }), addFaqs: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z.object({ titleIt: z.string(), @@ -83,6 +85,7 @@ export default createTRPCRouter({ }), addFaqsCategory: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z.object({ titleIt: z.string(), @@ -107,6 +110,7 @@ export default createTRPCRouter({ }), editFaqs: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z.object({ id: z.number(), @@ -139,6 +143,7 @@ export default createTRPCRouter({ }), editFaqsCategory: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z.object({ id: z.number(), @@ -171,6 +176,7 @@ export default createTRPCRouter({ }), deleteFaqs: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z.object({ id: z.number(), @@ -196,6 +202,7 @@ export default createTRPCRouter({ }), deleteFaqsCategory: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z.object({ id: z.number(), diff --git a/src/routers/web/freshman.ts b/src/routers/web/freshman.ts index d611e20..b69e5a5 100644 --- a/src/routers/web/freshman.ts +++ b/src/routers/web/freshman.ts @@ -1,5 +1,6 @@ import { TRPCError } from "@trpc/server" import { asc, eq, inArray, sql } from "drizzle-orm" +import { audit } from "@/audit/option" import { DB, SCHEMA } from "@/db" import { authorOf, modifiedByColumns } from "@/idp/author" import { dashboard, publicData } from "@/idp/policies" @@ -58,6 +59,7 @@ export default createTRPCRouter({ }), updateCard: policy(dashboard("web:content:write")) + .meta(audit.full()) .input(updateFreshmanCardInput) .mutation(async ({ input, ctx }) => { const { id, ...fields } = input @@ -70,6 +72,7 @@ export default createTRPCRouter({ }), moveCard: policy(dashboard("web:content:write")) + .meta(audit.full()) .input(moveFreshmanCardInput) .mutation(async ({ input, ctx }) => { const index = freshmanSlots.findIndex((slot) => slot.id === input.id) @@ -103,6 +106,7 @@ export default createTRPCRouter({ }), selectFaq: policy(dashboard("web:content:write")) + .meta(audit.full()) .input(selectFreshmanFaqInput) .mutation(async ({ input, ctx }) => { const author = modifiedByColumns(authorOf(ctx.actor)) diff --git a/src/routers/web/guides_matricole.ts b/src/routers/web/guides_matricole.ts index d909b45..95820f6 100644 --- a/src/routers/web/guides_matricole.ts +++ b/src/routers/web/guides_matricole.ts @@ -1,5 +1,6 @@ import { desc, eq } from "drizzle-orm" import z from "zod" +import { audit } from "@/audit/option" import { deleteBlob, uploadBlob } from "@/azure/blob" import { DB, SCHEMA } from "@/db" import { authorOf, createdByColumns } from "@/idp/author" @@ -42,6 +43,7 @@ export default createTRPCRouter({ }), addGuide: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z .instanceof(FormData) @@ -76,6 +78,7 @@ export default createTRPCRouter({ }), deleteGuide: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z.object({ id: z.number(), diff --git a/src/routers/web/projects.ts b/src/routers/web/projects.ts index 0c8e9dc..e77db91 100644 --- a/src/routers/web/projects.ts +++ b/src/routers/web/projects.ts @@ -1,5 +1,6 @@ import { asc, eq } from "drizzle-orm" import z from "zod" +import { audit } from "@/audit/option" import { uploadBlob } from "@/azure/blob" import { DB, SCHEMA } from "@/db" import { projectsCategories } from "@/db/schema/web/projects" @@ -43,6 +44,7 @@ export default createTRPCRouter({ }), addProject: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z .instanceof(FormData) @@ -73,6 +75,7 @@ export default createTRPCRouter({ }), editProject: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z .instanceof(FormData) @@ -113,6 +116,7 @@ export default createTRPCRouter({ }), reorderProjects: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z.object({ projectIds: z @@ -138,6 +142,7 @@ export default createTRPCRouter({ }), deleteProject: policy(dashboard("web:content:write")) + .meta(audit.full()) .input( z.object({ id: z.number(), diff --git a/src/routers/web/reports.ts b/src/routers/web/reports.ts index 9aef763..1f0e228 100644 --- a/src/routers/web/reports.ts +++ b/src/routers/web/reports.ts @@ -1,5 +1,6 @@ import { and, eq, inArray, sql } from "drizzle-orm" import z from "zod" +import { audit } from "@/audit/option" import { DB, SCHEMA, VIEWS } from "@/db" import { dashboard, SCOPE } from "@/idp/policies" import { createTRPCRouter, policy } from "@/trpc" @@ -29,6 +30,7 @@ function reportsTarget(ids: number[]) { export const reports = createTRPCRouter({ create: policy({ service: { scope: SCOPE.publicRead } }) + .meta(audit.full()) .input( z.discriminatedUnion("reportType", [ z.object({ @@ -84,6 +86,7 @@ export const reports = createTRPCRouter({ }), resolve: policy(dashboard("web:reports:manage")) + .meta(audit.full()) .input(z.object({ ids: z.array(z.number().int()).min(1) })) .mutation(async ({ input, ctx }) => { const before = await DB.select().from(REPORTS).where(inArray(REPORTS.id, input.ids)) @@ -96,6 +99,7 @@ export const reports = createTRPCRouter({ }), dismiss: policy(dashboard("web:reports:manage")) + .meta(audit.full()) .input(z.object({ ids: z.array(z.number().int()).min(1) })) .mutation(async ({ input, ctx }) => { const before = await DB.select().from(REPORTS).where(inArray(REPORTS.id, input.ids)) diff --git a/src/trpc.ts b/src/trpc.ts index 10736ca..2ee5d9d 100644 --- a/src/trpc.ts +++ b/src/trpc.ts @@ -2,7 +2,8 @@ import type { AccessSnapshotClient, Actor } from "@polinetwork/auth-kit" import { initTRPC, TRPCError } from "@trpc/server" import superjson from "superjson" import { ZodError, z } from "zod/v4" -import { auditEvent, auditRecorder, isDenied, noAudit, UNAUDITED } from "./audit" +import { auditEvent, auditRecorder, isDenied, noAudit } from "./audit" +import type { AuditOption } from "./audit/option" import { env } from "./env" import type { RequestAuth } from "./idp/auth" import { logger } from "./logger" @@ -25,7 +26,11 @@ export type PolicyRule = { scope: string | readonly string[]; permission?: strin /** Actor kinds a procedure accepts. A kind that is not listed is denied. */ export type Policy = { service?: PolicyRule; telegram?: PolicyRule; user?: PolicyRule } -type Meta = { policy?: Policy } +type Meta = { + policy?: Policy + /** How a mutation is recorded in the audit log; see `audit` in `src/audit`. */ + audit?: AuditOption +} const t = initTRPC .context() @@ -70,14 +75,17 @@ const timingMiddleware = t.middleware(async ({ next, path }) => { }) /** - * Records every mutation in `common_audit_events` (see `src/audit`): who called it, with what input, and whether it - * succeeded, failed or was denied. It runs before the policy so that denied calls are kept too, without their input. - * Handlers add the target and the state before and after through `ctx.audit`. A failed write is logged and does not - * fail the call, whose change has already happened. + * Records every mutation in `common_audit_events` (see `src/audit`) as its `audit` meta option says: who called it, + * on what, and whether it succeeded, failed or was denied, with the input and the states for `full`. It runs before + * the policy so that denied calls are kept too, without their input. Handlers add the target and the state before and + * after through `ctx.audit`. A failed write is logged and does not fail the call, whose change has already happened. */ -const auditMiddleware = t.middleware(async ({ ctx, path, type, getRawInput, next }) => { +const auditMiddleware = t.middleware(async ({ ctx, meta, path, type, getRawInput, next }) => { + const option = meta?.audit + if (type === "mutation" && !option) logger.error({ procedure: path }, "[AUDIT] mutation without an audit option") // Calls without a valid token are not recorded, so their bodies are never read for the log. - if (type !== "mutation" || UNAUDITED.has(path) || ctx.auth?.kind !== "token") return next({ ctx: { audit: noAudit } }) + if (type !== "mutation" || option?.capture === "none" || ctx.auth?.kind !== "token") + return next({ ctx: { audit: noAudit } }) const { recorder, note, skipped } = auditRecorder() const result = await next({ ctx: { audit: recorder } }) @@ -86,7 +94,7 @@ const auditMiddleware = t.middleware(async ({ ctx, path, type, getRawInput, next try { // A denied call's body may never have been read, and the event keeps none of it. const rawInput = isDenied(result) ? undefined : await getRawInput().catch(() => undefined) - const event = auditEvent({ path, auth: ctx.auth, requestId: ctx.requestId, rawInput, note, result }) + const event = auditEvent({ path, option, auth: ctx.auth, requestId: ctx.requestId, rawInput, note, result }) if (event) { // Imported here so that loading the router does not open the database. const { writeAuditEvent } = await import("./audit/store") diff --git a/tests/audit-json.test.ts b/tests/audit-json.test.ts index f91a83d..27011e7 100644 --- a/tests/audit-json.test.ts +++ b/tests/audit-json.test.ts @@ -64,6 +64,8 @@ describe("auditEvent", () => { const auth = { kind: "token", actor: admin, scopes: new Set(["backend:admin"]) } as const const ok = (data: unknown = undefined) => ({ ok: true as const, data }) + const full = { capture: "full" } as const + it("records nothing for calls without a valid token", () => { const rejected = { kind: "rejected", status: 401, reason: "Missing bearer token" } as const for (const caller of [undefined, rejected]) @@ -91,6 +93,7 @@ describe("auditEvent", () => { path: "esign.signers.resetIdentity", auth, rawInput: {}, + option: full, note: { target: { type: "esign.signer", id: "s".repeat(5000), label: "l".repeat(5000) }, reason: "r".repeat(5000), @@ -100,17 +103,6 @@ describe("auditEvent", () => { for (const value of [event?.targetId, event?.targetLabel, event?.reason]) expect(value?.length).toBeLessThan(2100) }) - it("names a person only by a valid People id", () => { - const event = auditEvent({ - path: "people.persons.setNote", - auth, - rawInput: { id: "ada@example.org", note: "" }, - note: {}, - result: { ok: false, error: new TRPCError({ code: "BAD_REQUEST", message: "Invalid input" }) }, - }) - expect(event).toMatchObject({ targetType: "people.person", targetId: null, input: null }) - }) - it("lists the issues of an invalid input rather than their JSON", () => { const invalid = z.object({ id: z.number(), title: z.string() }).safeParse({ id: "x" }) const event = auditEvent({ @@ -135,41 +127,84 @@ describe("auditEvent", () => { expect(event).toMatchObject({ targetType: "web.report", targetId: null, targetLabel: "2 reports" }) }) - it("keeps only the actor, the action, the person and the outcome for People", () => { - const note = auditEvent({ + it("records nothing for a mutation declared not to be", () => { + const option = { capture: "none", why: "ingestion" } as const + expect(auditEvent({ path: "tg.messages.add", option, auth, rawInput: {}, note: {}, result: ok() })).toBeNull() + }) + + it("keeps only the actor, the action, the target and the outcome when minimal", () => { + const event = auditEvent({ path: "people.persons.setNote", + option: { + capture: "minimal", + target: ({ input }) => ({ type: "people.person", id: (input as { id: string }).id }), + }, auth, rawInput: { id: "P-0001", note: "private HR note" }, - note: {}, + note: { before: { note: "old" }, after: { note: "new" }, reason: "why" }, result: ok(), }) - expect(note).toMatchObject({ + expect(event).toMatchObject({ action: "people.persons.setNote", actorSub: "usr_admin", targetType: "people.person", targetId: "P-0001", outcome: "success", + reason: null, input: null, before: null, after: null, }) + }) - const created = auditEvent({ - path: "people.persons.create", + it("stores as little as minimal for a mutation without an option", () => { + const event = auditEvent({ + path: "web.faqs.editFaqs", + auth, + rawInput: { id: 1 }, + note: { after: {} }, + result: ok(), + }) + expect(event).toMatchObject({ input: null, after: null }) + }) + + it("keeps only the declared fields of the input", () => { + const event = auditEvent({ + path: "azure.members.setAssocNumber", + option: { capture: "full", fields: ["userId", "assocNumber"] }, auth, - rawInput: { name: "Ada", contactEmail: "ada@example.org", phone: "+39 000" }, + rawInput: { userId: "u1", assocNumber: 7, notifyEmail: "ada@example.org" }, note: {}, - result: ok({ id: "P-0002" }), + result: ok({ error: null }), }) - expect(created).toMatchObject({ targetId: "P-0002", input: null }) + expect(event?.input).toEqual({ userId: "u1", assocNumber: 7 }) + }) - const ended = auditEvent({ - path: "people.admins.end", + it("prefers the target the handler names, and gives the option's the result", () => { + const option = { + capture: "full", + target: ({ data }: { data: unknown }) => ({ + type: "web.faq", + id: (data as { id: number } | undefined)?.id ?? null, + }), + } as const + const named = auditEvent({ + path: "web.faqs.addFaqs", + option, auth, - rawInput: { personId: "P-0003", reason: "stepped down" }, + rawInput: {}, + note: { target: { type: "web.faq", id: 9, label: "Exams" } }, + result: ok({ id: 1 }), + }) + expect(named).toMatchObject({ targetId: "9", targetLabel: "Exams" }) + const derived = auditEvent({ + path: "web.faqs.addFaqs", + option, + auth, + rawInput: {}, note: {}, - result: ok(), + result: ok({ id: 1 }), }) - expect(ended).toMatchObject({ targetId: "P-0003", reason: null, input: null }) + expect(derived).toMatchObject({ targetType: "web.faq", targetId: "1" }) }) }) diff --git a/tests/azure-router.test.ts b/tests/azure-router.test.ts index 384a97a..2062d10 100644 --- a/tests/azure-router.test.ts +++ b/tests/azure-router.test.ts @@ -133,7 +133,7 @@ describe("Azure tRPC routes without credentials", () => { targetType: "azure.member", targetId: result.id, targetLabel: "Katherine Johnson", - after: { id: result.id, email: "katherine.johnson@polinetwork.org", assocNumber: 2043 }, + after: { id: result.id, assocNumber: 2043 }, }) }) diff --git a/tests/group-label-platform-isolation.test.ts b/tests/group-label-platform-isolation.test.ts index 21654fd..730b7c0 100644 --- a/tests/group-label-platform-isolation.test.ts +++ b/tests/group-label-platform-isolation.test.ts @@ -64,6 +64,7 @@ vi.mock("@/db", () => ({ vi.mock("@/trpc", () => { const publicProcedure = { + meta: () => publicProcedure, input: (schema: { parse: (input: unknown) => unknown }) => ({ mutation: (handler: (args: { input: unknown; ctx: unknown }) => unknown) => ({ execute: (input: unknown) => diff --git a/tests/guides-latest.test.ts b/tests/guides-latest.test.ts index 13a4932..634e4f6 100644 --- a/tests/guides-latest.test.ts +++ b/tests/guides-latest.test.ts @@ -16,6 +16,7 @@ vi.mock("@/azure/blob", () => ({ deleteBlob: vi.fn(), uploadBlob: vi.fn() })) vi.mock("@/db", () => ({ DB: { select: state.select }, SCHEMA: { WEB: { guidesMatricole: state.guides } } })) vi.mock("@/trpc", () => { const procedure = { + meta: () => procedure, input: () => ({ mutation: (handler: unknown) => ({ handler }) }), output: () => ({ query: (handler: () => unknown) => ({ handler }) }), } diff --git a/tests/idp-router.test.ts b/tests/idp-router.test.ts index 3399dab..d7cb922 100644 --- a/tests/idp-router.test.ts +++ b/tests/idp-router.test.ts @@ -84,7 +84,9 @@ beforeAll(async () => { ;({ appRouter } = await import("@/routers")) }) -type ProcedureDef = { _def: { meta?: { policy?: unknown } } } +type ProcedureDef = { + _def: { type: string; meta?: { policy?: unknown; audit?: { capture: string; why?: string } } } +} function procedures(): Array<[string, ProcedureDef]> { return Object.entries( @@ -93,6 +95,36 @@ function procedures(): Array<[string, ProcedureDef]> { } describe("app router", () => { + it("records People changes without their details, naming a person only by a valid People id", () => { + const people = procedures().filter( + ([path, procedure]) => path.startsWith("people.") && procedure._def.type === "mutation" + ) + expect(people.length).toBeGreaterThan(10) + for (const [, procedure] of people) expect(procedure._def.meta?.audit?.capture).toBe("minimal") + const target = ( + procedures().find(([path]) => path === "people.persons.setNote")?.[1]._def.meta?.audit as unknown as { + target: (call: { input: unknown; data: unknown }) => unknown + } + ).target + expect(target({ input: { id: "P-0001", note: "" }, data: undefined })).toEqual({ + type: "people.person", + id: "P-0001", + }) + expect(target({ input: { personId: "P-0002" }, data: undefined })).toEqual({ type: "people.person", id: "P-0002" }) + expect(target({ input: { name: "Ada" }, data: { id: "P-0003" } })).toEqual({ type: "people.person", id: "P-0003" }) + expect(target({ input: { id: "ada@example.org" }, data: undefined })).toEqual({ type: "people.person", id: null }) + }) + + it("gives every mutation an audit option, and says why one is not recorded", () => { + const mutations = procedures().filter(([, procedure]) => procedure._def.type === "mutation") + expect(mutations.length).toBeGreaterThan(60) + expect(mutations.filter(([, procedure]) => !procedure._def.meta?.audit).map(([path]) => path)).toEqual([]) + const unexplained = mutations.filter( + ([, procedure]) => procedure._def.meta?.audit?.capture === "none" && !procedure._def.meta.audit.why?.trim() + ) + expect(unexplained.map(([path]) => path)).toEqual([]) + }) + it("gives every procedure a policy", () => { const missing = procedures() .filter(([, procedure]) => !procedure._def.meta?.policy) diff --git a/tests/tg-users-creation-history.test.ts b/tests/tg-users-creation-history.test.ts index a09db02..1b5628d 100644 --- a/tests/tg-users-creation-history.test.ts +++ b/tests/tg-users-creation-history.test.ts @@ -32,6 +32,7 @@ vi.mock("@/idp/policies", () => ({ })) vi.mock("@/trpc", () => { const procedure = { + meta: () => procedure, input: () => procedure, output: () => procedure, query: (handler: unknown) => ({ handler }),