audit

func AppendBootstrapAuthFail ¶

func AppendBootstrapAuthFail(
	ctx context.Context, store *BootstrapLedgerStore, clk clock.Clock,
	eventID, reason, clientIPHash string,
) error

AppendBootstrapAuthFail constructs a bootstrap.auth.fail ledger entry and persists it via the sealed *BootstrapLedgerStore. clientIPHash is the keyed, non-reversible hash of the client IP (#1488); it is empty when no IP was available (e.g. health probes, or the request did not flow through middleware that sets ctxkeys.RealIP).

clientIPHash is typed string (not redaction.IPHash) by design: this is the CONSUMER side — the sealed type that blocks plaintext lives on the producer (cells/accesscore setup.Service). This function still validates the untrusted wire value at the trust boundary with redaction.IsIPHashString before writing the ledger. Callers are responsible for passing an already-hashed value; the only producer is the bootstrap observer, which hashes via redaction.HashIP.

eventID is the stable source-event identity (the consuming slice passes outbox.Entry.ID()). It becomes the ledger EventID, which is the SOLE idempotency key (ledger.IdempotencyContentFingerprint hashes EventID only, see runtime/audit/ledger/mem_store.go). Using the stable entry ID — rather than a freshly minted uuid.NewString() — is what makes at-least-once redelivery idempotent: a redelivered event carries the same outbox UUID, so the second Append collapses to ErrAuditLedgerAlreadyExists instead of appending a duplicate ledger row. This mirrors the relay-chain appender (cells/auditcore/internal/appender) which also keys on entry.ID(). Callers must treat ErrAuditLedgerAlreadyExists (KindConflict) as an idempotent SUCCESS and Ack — see auditappendbootstrap.Service.HandleEvent.

Consistency level: L1 LocalTx — store.Append runs in a single PG transaction with the advisory-lock-fenced chain tail read; no outbox emit follows, so L2 atomicity coverage does not apply. The bootstrap chain is physically distinct from the auditcore relay chain via BootstrapNamespace(): the *BootstrapLedgerStore typed handle makes accidental injection of the auditcore-namespace store a compile error rather than a runtime fork (issue #1121 / ADR 202605270230 — Vault per-device-salt + Trillian per-tree partition patterns).

Payload JSON shape (camelCase, additive evolution):

{"reason": "<one of: missing_header | wrong_credentials | rate_limited>",
 "clientIpHash": "<keyed HMAC hex hash of the client IP, or empty>"}

Errors:

• ErrValidationFailed when store / clock is nil, eventID is empty, or reason is not in {missing_header, wrong_credentials, rate_limited}.
• The wrapped Append error otherwise — most commonly ErrAuditLedgerAlreadyExists (idempotent replay; callers Ack) or a chain-write failure (transient; callers Requeue). The wrap preserves the inner *errcode.Error code so callers can classify via errors.As.

func BootstrapNamespace ¶

func BootstrapNamespace() ledger.NamespaceID

BootstrapNamespace returns the canonical ledger.NamespaceID used by every bootstrap auth-fail audit chain. It is the only sanctioned way to obtain this NamespaceID at composition root; archtest AUDIT-NS-DISJOINT-01 locks the composition site to call this function rather than passing the literal string.

func VerifyBootstrapTailOnStartup ¶

func VerifyBootstrapTailOnStartup(ctx context.Context, store *BootstrapLedgerStore, logger *slog.Logger) error

VerifyBootstrapTailOnStartup runs the strict tail-verify protocol against the bootstrap audit chain: reads the tail snapshot, then re-computes the HMAC for every entry [1, tail.SeqNo] and checks chain linkage.

Called by cmd/corebundle.AuditCoreModule.Provide immediately after the bootstrap store is constructed. The bootstrap chain lives outside the auditcore cell (it is the only audit chain owned directly by the composition root), so its tail-verify cannot reuse cells/auditcore's strictTailVerifyOnStartup helper. The two helpers share the same fail- closed posture: a corrupted or tampered bootstrap chain surfaces at process startup rather than at the first 401/429, blocking k8s readiness instead of silently appending to a forked chain.

Empty chain (tail.SeqNo == 0) returns nil — no entries to verify.

ref: cells/auditcore/cell.go:strictTailVerifyOnStartup — auditcore-side counterpart for the relay-driven chain. ref: google/trillian log/sequencer.go IntegrateBatch — tree integrity must be verified before accepting new leaves (same fail-fast invariant).