@playstack/audit

@playstack/audit records security- and administration-relevant activity in append-only, per-scope tamper-evident chains for Node and Workers.

Install

npm install @playstack/audit @playstack/core @playstack/events

Compose event-driven audit

import {
  bindAuditRegistry,
  createAuditService,
  Sha256AuditHash,
} from '@playstack/audit'

const audit = createAuditService({
  persistence,
  hash: new Sha256AuditHash(applicationCrypto),
  clock,
  ids,
  mapper: {
    map: (event, payload) => ({
      scopeType: event.context.scope?.type ?? 'system',
      scopeId: event.context.scope?.id ?? 'global',
      actorType: event.context.actor?.type ?? 'system',
      actorId: event.context.actor?.id,
      resourceType: payload.resourceType as string,
      resourceId: payload.resourceId as string,
    }),
  },
  retention: {
    months: 84,
    policyReference: 'docs/policies/audit-retention.md',
  },
})

const dispose = bindAuditRegistry(events, registry, audit)
events.assertReady()

The event definition chooses the audit tier and projected fields. The application mapper supplies scope, actor, resource, and impersonation facts because those cannot be inferred safely from arbitrary payload names. The recorded action defaults to the event name without its first (package) segment, so accounts.member.joined is audited as member.joined; a mapper may return action to override that, for example to keep the full event name when two packages share a suffix.

Configuration reference

The validated retention policy is exposed as audit.retention so storage, scheduled partition maintenance, and framework adapters use the same decision.

Audit entry properties

Queries always require scopeType and scopeId, with optional actor, resource, action, time range, cursor, and limit filters.

Built-in actor types are user, apiKey, staff, and system. The string contract is intentionally extensible, so applications can record actors such as partner, service, or another authenticated principal without converting them into a user. Actor identifiers remain optional only for system activity.

Persistence bridge

AuditPersistence must lock the scopeType/scopeId chain while reading its tail and appending the next record—even when the chain is empty. Transactional event handlers receive the emitting transaction and fail the mutation if audit storage fails. Queued handlers open their own transaction after outbox delivery.

@playstack/audit/prisma provides PostgreSQL advisory locking, append-only inserts, and stable time/ID cursor pagination. The managed Prisma fragment is composed by the CLI; the application owns migrations plus monthly partition creation and removal.

Direct application routes

Package events are the authoritative audit path for security-critical domain operations. Use @playstack/nest-audit for explicitly declared application routes whose successful responses should be recorded on a best-effort basis.

Boundary

Audit is not the general event store and does not record every event. The application owns retention policy, storage access control, operator workflows, partition operations, and the decision about which application-specific events are auditable.

API entry points and requirements

Reference snapshot: @playstack/audit@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.