Initial Commit
This commit is contained in:
46
openspec/archive/2026-05-26-api-audit-file/proposal.md
Normal file
46
openspec/archive/2026-05-26-api-audit-file/proposal.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# `@suaveplan/api-audit-file` — file-rotating audit sink
|
||||
|
||||
**Package**: `@suaveplan/api-audit-file`
|
||||
**Status**: PROPOSED
|
||||
**Type**: new-package
|
||||
**Stage**: 8 — see umbrella `openspec/changes/api-plugin-foundation/`
|
||||
|
||||
## Why
|
||||
|
||||
Per design doc §12.5, some operators (single-host deployments, on-prem environments without a log shipper) need an audit sink that writes to a local file with rotation. This package is that sink. It mirrors the `api-audit-stdout` contract (`audit` capability, JSON-per-line, HMAC-signed records) and adds size + time rotation.
|
||||
|
||||
## What changes
|
||||
|
||||
- ADDED: `createFileAuditSink({ path, hmacKey, clock, rotation })` — returns an `AuditSink`. Writes JSON-per-line with HMAC signature to `path`. Rotation policy: size-based (`maxSizeBytes`, default 100 MB) AND time-based (`maxAgeMs`, default 1 day). Rotated files are renamed to `<path>.<utc-ISO>.log` and optionally gzipped if `compress: true`.
|
||||
- ADDED: Retention policy — `maxFiles` (default 30) keeps the most recent N rotated files; older files are deleted with a `api.audit.rotation_evicted_total{sink="file"}` increment.
|
||||
- ADDED: Atomic-write strategy — writes go through a temp file path then `fsync` + rename for crash safety, OR an append-on-open `fd` model gated by `host.audit.file.appendMode` (`"strict-sync" | "append"`).
|
||||
- ADDED: Same backpressure model as `api-audit-stdout`: bounded queue, observable drops via `api.audit.dropped_total{sink="file"}`.
|
||||
- ADDED: Error codes (`AUDIT_FILE_*`): `INVALID_RECORD`, `WRITER_FAILED`, `QUEUE_FULL`, `ROTATION_FAILED`, `RETENTION_FAILED`, `PATH_NOT_WRITEABLE`.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Cross-host audit aggregation — separate package.
|
||||
- Encryption at rest — caller handles (the sink writes plaintext + HMAC; disk-encryption is outside scope).
|
||||
- Centralised log shipping (`fluentd`, `vector`, …) — operators wire the rotated files into those tools.
|
||||
|
||||
## Source mapping
|
||||
|
||||
Genesis-original. Source of design intent: `docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md`.
|
||||
|
||||
| Requirement | Design doc section |
|
||||
|---|---|
|
||||
| File-rotating audit sink (`api-audit-file`) | §12.5 |
|
||||
| HMAC-signed records | §12.5 |
|
||||
| Same `audit` capability contract | §12.5 |
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/sink/sink.test.ts` — write 1000 records, assert all are present, JSON-parseable, HMAC-valid.
|
||||
- `src/rotation/rotation.test.ts` — exercise size rotation (write enough bytes to exceed `maxSizeBytes`) and time rotation (advance `FakeClock` past `maxAgeMs`); assert rotated file exists with the expected timestamp suffix.
|
||||
- `src/retention/retention.test.ts` — create N+1 rotated files (with `FakeClock`), assert oldest is evicted and `api.audit.rotation_evicted_total` increments.
|
||||
- `src/sink/sink.spec-conformance.test.ts` — drop policy mirrors `api-audit-stdout`; observability assertions.
|
||||
- `tests/dep-graph.test.ts` — runtime deps (`api-types`, `crypto-hash`, `error`, `logger`, `zod`).
|
||||
|
||||
## Migration impact
|
||||
|
||||
None — additive only. `api-host` registers this when `host.audit.sink = "file"`.
|
||||
@@ -0,0 +1,99 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: api-audit-file (api-audit-file)
|
||||
|
||||
**Package**: `@suaveplan/api-audit-file`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement below carries a `**Verified by:**` line at authoring time.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: JSON-per-line file writes with HMAC signature
|
||||
|
||||
The package SHALL write each audit record as a single JSON line to the configured file `path` with an HMAC-SHA-256 signature computed over the canonical record bytes.
|
||||
|
||||
#### Scenario: 1000 records write as 1000 JSON lines
|
||||
|
||||
- WHEN 1000 valid records are written
|
||||
- THEN the file contains 1000 lines, each parses as JSON AND each line's HMAC verifies
|
||||
|
||||
**Verified by:** `src/sink/sink.test.ts::"writes 1000 records as 1000 verified JSON lines"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Size-based rotation
|
||||
|
||||
The package SHALL rotate the file when its size reaches `rotation.maxSizeBytes` (default 100 MB). The rotated file is renamed to `<path>.<utc-ISO>.log` and a new empty file is opened. Subsequent writes go to the new file.
|
||||
|
||||
#### Scenario: write past maxSizeBytes triggers rotation
|
||||
|
||||
- WHEN `maxSizeBytes` is 1024 AND 2048 bytes of records are written
|
||||
- THEN a rotated file with an ISO-timestamp suffix exists AND subsequent writes go to a fresh file
|
||||
|
||||
**Verified by:** `src/rotation/rotation.test.ts::"size rotation produces timestamp-suffixed file"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Time-based rotation
|
||||
|
||||
The package SHALL rotate when the current file's age (against the supplied `Clock`) reaches `rotation.maxAgeMs` (default 24h). Time rotation uses `FakeClock` in tests for determinism.
|
||||
|
||||
#### Scenario: clock advance past maxAgeMs triggers rotation
|
||||
|
||||
- WHEN `maxAgeMs` is 60_000ms AND the clock advances by 61_000ms
|
||||
- THEN the next write rotates first AND lands in the new file
|
||||
|
||||
**Verified by:** `src/rotation/rotation.test.ts::"time rotation triggers on clock advance"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Retention enforces maxFiles
|
||||
|
||||
The package SHALL retain at most `rotation.maxFiles` (default 30) rotated files. Older files are deleted with `api.audit.rotation_evicted_total{sink="file"}` increment.
|
||||
|
||||
#### Scenario: N+1 rotated files evicts the oldest
|
||||
|
||||
- WHEN `maxFiles` is 3 AND a 4th rotation occurs
|
||||
- THEN the oldest rotated file is deleted AND `api.audit.rotation_evicted_total` increments by 1
|
||||
|
||||
**Verified by:** `src/retention/retention.test.ts::"evicts oldest beyond maxFiles and increments counter"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Path-not-writeable surfaces at boot
|
||||
|
||||
The package SHALL fail fast at sink construction if `path`'s directory is not writeable, raising `AUDIT_FILE_PATH_NOT_WRITEABLE`.
|
||||
|
||||
#### Scenario: unwriteable path raises at boot
|
||||
|
||||
- WHEN `path` resolves to a directory the process cannot write
|
||||
- THEN `createFileAuditSink` throws `AUDIT_FILE_PATH_NOT_WRITEABLE`
|
||||
|
||||
**Verified by:** `src/sink/sink.test.ts::"unwriteable path raises AUDIT_FILE_PATH_NOT_WRITEABLE"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Drops are observable
|
||||
|
||||
The package SHALL drop records that exceed `maxQueueMs` and increment `api.audit.dropped_total{sink="file"}`. Drops MUST NEVER be silent.
|
||||
|
||||
#### Scenario: drop increments dropped_total
|
||||
|
||||
- WHEN the file writer is stalled long enough for the queue to overflow
|
||||
- THEN the record is dropped AND `api.audit.dropped_total{sink="file"}` increments by 1
|
||||
|
||||
**Verified by:** `src/sink/sink.spec-conformance.test.ts::"drop increments dropped_total with sink label file"`
|
||||
|
||||
---
|
||||
|
||||
### Requirement: HMAC verification detects tampering
|
||||
|
||||
The package SHALL produce HMACs such that any byte change in the record invalidates verification with the same key.
|
||||
|
||||
#### Scenario: tampering invalidates HMAC
|
||||
|
||||
- WHEN one byte in a written line is flipped
|
||||
- THEN HMAC verification fails
|
||||
|
||||
**Verified by:** `src/hmac/hmac.test.ts::"tampering invalidates HMAC"`
|
||||
68
openspec/archive/2026-05-26-api-audit-file/tasks.md
Normal file
68
openspec/archive/2026-05-26-api-audit-file/tasks.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# Tasks — `@suaveplan/api-audit-file`
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Spec authoring
|
||||
|
||||
- [x] 1.1 Read design doc (§12.5)
|
||||
- [x] 1.2 Read `openspec/AGENTS.md` Sections 13 and 14
|
||||
- [x] 1.3 Draft `proposal.md`
|
||||
- [x] 1.4 Draft `specs/api-audit-file/spec.md`
|
||||
- [x] 1.5 Every requirement carries `**Verified by:**`
|
||||
|
||||
## 2. Implementation
|
||||
|
||||
- [ ] 2.1 Scaffold `packages/api/api-audit-file/`
|
||||
- [ ] 2.2 `src/sink/` — `createFileAuditSink`, append/strict-sync writer
|
||||
- [ ] 2.3 `src/rotation/` — size + time rotation
|
||||
- [ ] 2.4 `src/retention/` — `maxFiles` eviction
|
||||
- [ ] 2.5 `src/schema/` — `AuditRecord` Zod schema (shared shape with `api-audit-stdout`)
|
||||
- [ ] 2.6 `src/hmac/` — HMAC-SHA-256 over canonical bytes
|
||||
- [ ] 2.7 `src/error-codes.ts`
|
||||
- [ ] 2.8 `src/instruments/` — records_total, dropped_total, rotation_evicted_total
|
||||
- [ ] 2.9 `src/index.ts` — explicit named re-exports
|
||||
|
||||
## 3. Tests
|
||||
|
||||
- [ ] 3.1 `src/sink/sink.test.ts`
|
||||
- [ ] 3.2 `src/sink/sink.spec-conformance.test.ts`
|
||||
- [ ] 3.3 `src/rotation/rotation.test.ts`
|
||||
- [ ] 3.4 `src/retention/retention.test.ts`
|
||||
- [ ] 3.5 `src/hmac/hmac.test.ts`
|
||||
- [ ] 3.6 `tests/dep-graph.test.ts`
|
||||
- [ ] 3.7 Every `it(...)` carries `{ timeout: 5000 }` (30000 for write-heavy tests)
|
||||
|
||||
## 4. Documentation
|
||||
|
||||
- [ ] 4.1 Sibling `.md` per implementation `.ts`
|
||||
- [ ] 4.2 `README.md` `## Modules`
|
||||
- [ ] 4.3 Update `CLAUDE.md` package listing
|
||||
|
||||
## 5. Pre-archive verification (the 5-gate triple)
|
||||
|
||||
- [ ] 5.1 `bun run check`
|
||||
- [ ] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/api-audit-file`
|
||||
- [ ] 5.3 `bunx turbo test:coverage --filter=@suaveplan/api-audit-file` — 100/100/100/100
|
||||
- [ ] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/api-audit-file`
|
||||
- [ ] 5.5 `bunx turbo build --filter=@suaveplan/api-audit-file`
|
||||
|
||||
## 6. Pre-archive 7-row checklist
|
||||
|
||||
- [ ] 6.1 Generics threaded; shared `AuditSink` typing parity with stdout
|
||||
- [ ] 6.2 Zod schemas wired at record-write boundary
|
||||
- [ ] 6.3 Every `AUDIT_FILE_*` code thrown by a production path
|
||||
- [ ] 6.4 Strict-mode: rotation under load is correct; drops observable
|
||||
- [ ] 6.5 OTel counters asserted with real `MeterProvider`
|
||||
- [ ] 6.6 Lifecycle dedup — `dispose()` flushes and is idempotent
|
||||
- [ ] 6.7 No retroactive tick
|
||||
|
||||
## 7. Archive
|
||||
|
||||
- [ ] 7.1 Fold spec delta into `openspec/specs/api-audit-file/spec.md`
|
||||
- [ ] 7.2 Move folder to archive
|
||||
- [ ] 7.3 Tick `8.11` in umbrella tasks
|
||||
- [ ] 7.4 Refresh `MANIFEST.md`
|
||||
Reference in New Issue
Block a user