2026-08-09 20:59:14 +02:00
|
|
|
# Work Records — audit-core
|
|
|
|
|
|
|
|
|
|
> Generated by `statehub fix-consistency` (CUST-WP-0061-T04, work-record
|
|
|
|
|
> stage 3). Do not edit by hand — edit the source file/block listed for
|
|
|
|
|
> each record and re-run fix-consistency to refresh this index. Archived
|
|
|
|
|
> workplans are omitted; closed decisions/intakes/engagements stay listed
|
|
|
|
|
> so recently-resolved work is still visible. [auto]
|
|
|
|
|
|
|
|
|
|
| Kind | ID | Status | Lane | Source |
|
|
|
|
|
| --- | --- | --- | --- | --- |
|
|
|
|
|
| workplan | AUDIT-WP-0001 | finished | — | workplans/AUDIT-WP-0001-statehub-bootstrap.md |
|
|
|
|
|
| workplan | AUDIT-WP-0002 | finished | — | workplans/AUDIT-WP-0002-pluggable-audit-backend.md |
|
Route ingestion through the backend contract; fix error semantics
AUDIT-WP-0004 T01, T02, T07.
T01 - ingestion wrote to SQLite directly and never called the AuditBackend
contract, so a 202 meant a row existed rather than that a backend with a
declared retention policy had accepted the event. Adds IdempotentAuditBackend
to the contract: duplicate detection lives inside the backend so custody and
idempotency state share a transaction and cannot diverge. SQLiteAuditBackend
implements it with WAL, synchronous=FULL and a busy timeout. Ingestion now
refuses any backend declaring durable=False, so the development file backend
cannot silently become the production sink.
The atomicity claim was tested rather than asserted, and the first attempt
failed: with a single shared connection, 16 racing submissions of one event
told two callers they were first. Storage was correct but the response was
not. Fixed with per-thread connections and BEGIN IMMEDIATE around the
insert/read pair, and locked in by a test.
T02 - storage errors previously escaped the handler with start_response never
called, and the auth check sat outside the try block so a non-ASCII
Authorization header crashed the request. Adds a catch-all, maps conflict to
409, backend unavailability to 503 and unexpected faults to 500, and
documents the full response contract with the retry semantics each status
implies, since senders key their behaviour off it.
T07 - ingestion tests 2 -> 23, suite 15 -> 36. accepted_at is now UTC rather
than local time, and naive timestamps are rejected instead of silently
assumed.
Remaining in WP-0004: T03 tenant/source binding, T04 redaction policy,
T05 operator read surface, T06 production serving layer.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 14:30:20 +02:00
|
|
|
| workplan | AUDIT-WP-0003 | finished | — | workplans/AUDIT-WP-0003-user-engine-event-ingestion-service.md |
|
|
|
|
|
| workplan | AUDIT-WP-0004 | proposed | — | workplans/AUDIT-WP-0004-receiver-correctness-and-hardening.md |
|
|
|
|
|
| workplan | AUDIT-WP-0005 | proposed | — | workplans/AUDIT-WP-0005-postgres-store-and-production-deployment.md |
|
2026-08-09 20:59:14 +02:00
|
|
|
| task | AUDIT-WP-0001-T01 | done | — | workplans/AUDIT-WP-0001-statehub-bootstrap.md |
|
|
|
|
|
| task | AUDIT-WP-0001-T02 | done | — | workplans/AUDIT-WP-0001-statehub-bootstrap.md |
|
|
|
|
|
| task | AUDIT-WP-0001-T03 | done | — | workplans/AUDIT-WP-0001-statehub-bootstrap.md |
|
|
|
|
|
| task | AUDIT-WP-0002-T01 | done | — | workplans/AUDIT-WP-0002-pluggable-audit-backend.md |
|
Rescope WP-0003 and open WP-0004/WP-0005 after pre-deploy review
A pre-deploy review found the receiver is not deployable as built. The
ingestion path never calls AuditBackend.emit(), so a 202 means a SQLite row
exists, not that a backend with a declared retention policy accepted the
event. Storage exceptions escape the handler with start_response never
called. Tenant isolation and source binding are recorded as done but are not
implemented. There is no read, replay, or correlation-lookup surface, so the
failure matrix cannot produce the evidence NK-WP-0024 needs.
WP-0003 closes as finished on its narrowed scope (contract + reference
implementation, T01/T02). T03 and T04 are cancelled with rationale.
WP-0004 covers receiver correctness and hardening, storage-agnostic so it
runs in parallel with the database platform work.
WP-0005 covers the Postgres backend, deployment, SQLite record migration,
and the live failure matrix. Production storage moves from SQLite-on-a-volume
to the Railiance PostgreSQL platform (RAPP-POSTGRES-WP-0002).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 12:44:23 +02:00
|
|
|
| task | AUDIT-WP-0003-T01 | done | — | workplans/AUDIT-WP-0003-user-engine-event-ingestion-service.md |
|
|
|
|
|
| task | AUDIT-WP-0003-T02 | done | — | workplans/AUDIT-WP-0003-user-engine-event-ingestion-service.md |
|
Route ingestion through the backend contract; fix error semantics
AUDIT-WP-0004 T01, T02, T07.
T01 - ingestion wrote to SQLite directly and never called the AuditBackend
contract, so a 202 meant a row existed rather than that a backend with a
declared retention policy had accepted the event. Adds IdempotentAuditBackend
to the contract: duplicate detection lives inside the backend so custody and
idempotency state share a transaction and cannot diverge. SQLiteAuditBackend
implements it with WAL, synchronous=FULL and a busy timeout. Ingestion now
refuses any backend declaring durable=False, so the development file backend
cannot silently become the production sink.
The atomicity claim was tested rather than asserted, and the first attempt
failed: with a single shared connection, 16 racing submissions of one event
told two callers they were first. Storage was correct but the response was
not. Fixed with per-thread connections and BEGIN IMMEDIATE around the
insert/read pair, and locked in by a test.
T02 - storage errors previously escaped the handler with start_response never
called, and the auth check sat outside the try block so a non-ASCII
Authorization header crashed the request. Adds a catch-all, maps conflict to
409, backend unavailability to 503 and unexpected faults to 500, and
documents the full response contract with the retry semantics each status
implies, since senders key their behaviour off it.
T07 - ingestion tests 2 -> 23, suite 15 -> 36. accepted_at is now UTC rather
than local time, and naive timestamps are rejected instead of silently
assumed.
Remaining in WP-0004: T03 tenant/source binding, T04 redaction policy,
T05 operator read surface, T06 production serving layer.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 14:30:20 +02:00
|
|
|
| task | AUDIT-WP-0003-T03 | cancel | — | workplans/AUDIT-WP-0003-user-engine-event-ingestion-service.md |
|
|
|
|
|
| task | AUDIT-WP-0003-T04 | cancel | — | workplans/AUDIT-WP-0003-user-engine-event-ingestion-service.md |
|
Bind sender identities, add operator read surface, real serving layer
AUDIT-WP-0004 T03, T05, T06.
T03 - the receiver accepted whatever tenant and source a caller sent as long
as it held the one shared token, despite WP-0003 recording tenant isolation as
delivered. audit_core.senders binds each credential to the sources and tenants
it may assert, driven by AUDIT_CORE_SENDERS rather than literals. Identities
hold a list of tokens so rotation publishes the replacement alongside the
incumbent and needs no delivery gap. Read is a separate privilege from write,
so a sender credential cannot read the audit trail back.
T05 - lookup by event id, lookup by correlation id, and a dead-letter view.
Rejections are recorded rather than silently dropped. An event rejected for
carrying secret-shaped material has its payload withheld: storing it would
write that material into the audit store, which is what the rejection exists
to prevent. Reason and payload hash are kept so it stays traceable.
Replay is deliberately not built here. Idempotent replay is a property of the
durable store and building it against SQLite would produce a second
implementation to throw away; it lands with the Postgres backend in
AUDIT-WP-0005-T01.
T06 - serving moves to waitress with configurable threads and channel timeout,
installed in the image via the serve extra. Without it the entrypoint falls
back to a threaded wsgiref server with a socket timeout and graceful shutdown
on SIGTERM, and logs a warning so a deployment cannot quietly land on the
fallback. Metric counters deferred to WP-0005-T03 to be designed against the
real scrape path.
Tests 36 -> 46, covering cross-tenant and cross-source refusal, token
rotation, read/write privilege separation, correlation lookup, and payload
withholding on secret rejection.
Remaining in WP-0004: T04 redaction policy, which needs a decision on whether
a secret-shaped field is a rejection or a redaction.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 14:50:02 +02:00
|
|
|
| task | AUDIT-WP-0004-T01 | done | — | workplans/AUDIT-WP-0004-receiver-correctness-and-hardening.md |
|
|
|
|
|
| task | AUDIT-WP-0004-T02 | done | — | workplans/AUDIT-WP-0004-receiver-correctness-and-hardening.md |
|
Redact secret-shaped fields by default, countable per field path
AUDIT-WP-0004-T04, closing the workplan.
Decision (Bernd): default to redaction, allow rejection per sender. Losing an
audit record over one field is worse than storing it masked, but a
higher-assurance channel must be able to refuse rather than mask. secret_policy
is set per sender identity in AUDIT_CORE_SENDERS and defaults to redact.
Detection now covers the whole payload at any depth, including lists, rather
than only the top level of data. Under redaction the value is masked and the
key is preserved: dropping the key would hide that the sender transmitted the
field at all, which is exactly what an operator needs in order to stop it. The
stored record carries details.redaction with policy and affected paths, so a
reader never has to infer whether what they see is what was sent.
Idempotency is unaffected - the payload hash is taken over the original request
body, so redaction is deterministic and a resubmission still reconciles as a
duplicate.
Both outcomes are counted durably by sender, source, action and field path,
exposed at GET /v1/secret-findings. Per-path aggregation is the point: the
actionable unit is "stop emitting data.auth.token on membership.added", not
"there were 47 redactions". Counters survive restart because the fix they drive
lives in another service.
Contract doc updated to match. Tests 46 -> 50. WP-0004 is finished.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 16:02:22 +02:00
|
|
|
| task | AUDIT-WP-0004-T03 | done | — | workplans/AUDIT-WP-0004-receiver-correctness-and-hardening.md |
|
Route ingestion through the backend contract; fix error semantics
AUDIT-WP-0004 T01, T02, T07.
T01 - ingestion wrote to SQLite directly and never called the AuditBackend
contract, so a 202 meant a row existed rather than that a backend with a
declared retention policy had accepted the event. Adds IdempotentAuditBackend
to the contract: duplicate detection lives inside the backend so custody and
idempotency state share a transaction and cannot diverge. SQLiteAuditBackend
implements it with WAL, synchronous=FULL and a busy timeout. Ingestion now
refuses any backend declaring durable=False, so the development file backend
cannot silently become the production sink.
The atomicity claim was tested rather than asserted, and the first attempt
failed: with a single shared connection, 16 racing submissions of one event
told two callers they were first. Storage was correct but the response was
not. Fixed with per-thread connections and BEGIN IMMEDIATE around the
insert/read pair, and locked in by a test.
T02 - storage errors previously escaped the handler with start_response never
called, and the auth check sat outside the try block so a non-ASCII
Authorization header crashed the request. Adds a catch-all, maps conflict to
409, backend unavailability to 503 and unexpected faults to 500, and
documents the full response contract with the retry semantics each status
implies, since senders key their behaviour off it.
T07 - ingestion tests 2 -> 23, suite 15 -> 36. accepted_at is now UTC rather
than local time, and naive timestamps are rejected instead of silently
assumed.
Remaining in WP-0004: T03 tenant/source binding, T04 redaction policy,
T05 operator read surface, T06 production serving layer.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 14:30:20 +02:00
|
|
|
| task | AUDIT-WP-0004-T04 | todo | — | workplans/AUDIT-WP-0004-receiver-correctness-and-hardening.md |
|
Redact secret-shaped fields by default, countable per field path
AUDIT-WP-0004-T04, closing the workplan.
Decision (Bernd): default to redaction, allow rejection per sender. Losing an
audit record over one field is worse than storing it masked, but a
higher-assurance channel must be able to refuse rather than mask. secret_policy
is set per sender identity in AUDIT_CORE_SENDERS and defaults to redact.
Detection now covers the whole payload at any depth, including lists, rather
than only the top level of data. Under redaction the value is masked and the
key is preserved: dropping the key would hide that the sender transmitted the
field at all, which is exactly what an operator needs in order to stop it. The
stored record carries details.redaction with policy and affected paths, so a
reader never has to infer whether what they see is what was sent.
Idempotency is unaffected - the payload hash is taken over the original request
body, so redaction is deterministic and a resubmission still reconciles as a
duplicate.
Both outcomes are counted durably by sender, source, action and field path,
exposed at GET /v1/secret-findings. Per-path aggregation is the point: the
actionable unit is "stop emitting data.auth.token on membership.added", not
"there were 47 redactions". Counters survive restart because the fix they drive
lives in another service.
Contract doc updated to match. Tests 46 -> 50. WP-0004 is finished.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 16:02:22 +02:00
|
|
|
| task | AUDIT-WP-0004-T05 | done | — | workplans/AUDIT-WP-0004-receiver-correctness-and-hardening.md |
|
|
|
|
|
| task | AUDIT-WP-0004-T06 | done | — | workplans/AUDIT-WP-0004-receiver-correctness-and-hardening.md |
|
Bind sender identities, add operator read surface, real serving layer
AUDIT-WP-0004 T03, T05, T06.
T03 - the receiver accepted whatever tenant and source a caller sent as long
as it held the one shared token, despite WP-0003 recording tenant isolation as
delivered. audit_core.senders binds each credential to the sources and tenants
it may assert, driven by AUDIT_CORE_SENDERS rather than literals. Identities
hold a list of tokens so rotation publishes the replacement alongside the
incumbent and needs no delivery gap. Read is a separate privilege from write,
so a sender credential cannot read the audit trail back.
T05 - lookup by event id, lookup by correlation id, and a dead-letter view.
Rejections are recorded rather than silently dropped. An event rejected for
carrying secret-shaped material has its payload withheld: storing it would
write that material into the audit store, which is what the rejection exists
to prevent. Reason and payload hash are kept so it stays traceable.
Replay is deliberately not built here. Idempotent replay is a property of the
durable store and building it against SQLite would produce a second
implementation to throw away; it lands with the Postgres backend in
AUDIT-WP-0005-T01.
T06 - serving moves to waitress with configurable threads and channel timeout,
installed in the image via the serve extra. Without it the entrypoint falls
back to a threaded wsgiref server with a socket timeout and graceful shutdown
on SIGTERM, and logs a warning so a deployment cannot quietly land on the
fallback. Metric counters deferred to WP-0005-T03 to be designed against the
real scrape path.
Tests 36 -> 46, covering cross-tenant and cross-source refusal, token
rotation, read/write privilege separation, correlation lookup, and payload
withholding on secret rejection.
Remaining in WP-0004: T04 redaction policy, which needs a decision on whether
a secret-shaped field is a rejection or a redaction.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 14:50:02 +02:00
|
|
|
| task | AUDIT-WP-0004-T07 | done | — | workplans/AUDIT-WP-0004-receiver-correctness-and-hardening.md |
|
Route ingestion through the backend contract; fix error semantics
AUDIT-WP-0004 T01, T02, T07.
T01 - ingestion wrote to SQLite directly and never called the AuditBackend
contract, so a 202 meant a row existed rather than that a backend with a
declared retention policy had accepted the event. Adds IdempotentAuditBackend
to the contract: duplicate detection lives inside the backend so custody and
idempotency state share a transaction and cannot diverge. SQLiteAuditBackend
implements it with WAL, synchronous=FULL and a busy timeout. Ingestion now
refuses any backend declaring durable=False, so the development file backend
cannot silently become the production sink.
The atomicity claim was tested rather than asserted, and the first attempt
failed: with a single shared connection, 16 racing submissions of one event
told two callers they were first. Storage was correct but the response was
not. Fixed with per-thread connections and BEGIN IMMEDIATE around the
insert/read pair, and locked in by a test.
T02 - storage errors previously escaped the handler with start_response never
called, and the auth check sat outside the try block so a non-ASCII
Authorization header crashed the request. Adds a catch-all, maps conflict to
409, backend unavailability to 503 and unexpected faults to 500, and
documents the full response contract with the retry semantics each status
implies, since senders key their behaviour off it.
T07 - ingestion tests 2 -> 23, suite 15 -> 36. accepted_at is now UTC rather
than local time, and naive timestamps are rejected instead of silently
assumed.
Remaining in WP-0004: T03 tenant/source binding, T04 redaction policy,
T05 operator read surface, T06 production serving layer.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 14:30:20 +02:00
|
|
|
| task | AUDIT-WP-0005-T01 | todo | — | workplans/AUDIT-WP-0005-postgres-store-and-production-deployment.md |
|
|
|
|
|
| task | AUDIT-WP-0005-T02 | todo | — | workplans/AUDIT-WP-0005-postgres-store-and-production-deployment.md |
|
|
|
|
|
| task | AUDIT-WP-0005-T03 | todo | — | workplans/AUDIT-WP-0005-postgres-store-and-production-deployment.md |
|
|
|
|
|
| task | AUDIT-WP-0005-T04 | todo | — | workplans/AUDIT-WP-0005-postgres-store-and-production-deployment.md |
|
|
|
|
|
| task | AUDIT-WP-0005-T05 | todo | — | workplans/AUDIT-WP-0005-postgres-store-and-production-deployment.md |
|
|
|
|
|
| task | AUDIT-WP-0005-T06 | todo | — | workplans/AUDIT-WP-0005-postgres-store-and-production-deployment.md |
|