Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 16 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
80 changes: 30 additions & 50 deletions src/audit/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 }

Expand All @@ -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: () => {} }
Expand Down Expand Up @@ -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<string, unknown>)[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]] : [])))
}

/**
Expand All @@ -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),
}
}
42 changes: 42 additions & 0 deletions src/audit/option.ts
Original file line number Diff line number Diff line change
@@ -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<Extract<AuditOption, { capture: "full" }>, "capture"> = {}) => ({
audit: { capture: "full", ...options } satisfies AuditOption,
}),
minimal: (options: Omit<Extract<AuditOption, { capture: "minimal" }>, "capture"> = {}) => ({
audit: { capture: "minimal", ...options } satisfies AuditOption,
}),
none: (why: string) => ({ audit: { capture: "none", why } satisfies AuditOption }),
}
48 changes: 34 additions & 14 deletions src/people/router.ts
Original file line number Diff line number Diff line change
@@ -1,33 +1,53 @@
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"
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<string, unknown>)[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.
*
* The service checks every role change again with the same rules as PoliNetwork Auth (`rules.ts`). Team changes
* 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)
Expand Down
5 changes: 4 additions & 1 deletion src/routers/azure/members.ts
Original file line number Diff line number Diff line change
@@ -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"
Expand Down Expand Up @@ -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),
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down
Loading
Loading