key-cape/docs/audit-core-sender-package.md

KeyCape audit-core intake package

Status: proposed, 2026-10-27. Answers audit-core AUDIT-WP-0017-T04 ("common intake package for every new sender") for KeyCape, and NetKingdom NK-WP-0055-T11. Implementation work: workplans/KEY-WP-0044-audit-correlation-and-intake.md. Unknowns are marked UNKNOWN. Authelia, LLDAP and privacyIDEA get their own packages and source names; this one covers KeyCape only.

1. What KeyCape emits today (from source, 2026-10-27)

All events go through telemetry.Emitter (src/internal/server/telemetry/). In production cmd/keycape/main.go wires a LogEmitter: one zerolog JSON line on stdout per event. There is no webhook, receipt store or audit-core sender.

Fields per line: event_type, client_id, endpoint, result, environment, trace_id, timestamp, and optionally feature, error_type, scopes, uid, assurance, grant_type. Events never carry tokens, codes, email or OTPs (comment in events.go).

event_type	Emitted at
auth_start	/authorize request accepted
auth_success	/authorize completes (with uid, assurance aal1/aal2); also /userinfo
auth_failure	/authorize: auth_failed, stale_upstream_authentication, mfa_check_error, mfa_failed
token_issued	/token authorization_code/refresh and client_credentials success
unsupported_feature	profile enforcement middleware
migration_event	migration tools only (not the server)

Gaps against audit needs:

• trace_id is never set (always empty) — fixed by KEY-WP-0044-T01.
• No event on /token failures, client authentication failure, revoke or introspection; no explicit event for denied scope/tenant/principal-type preconditions — KEY-WP-0044-T02.
• token_issued lacks subject and tenant; environment is unset on several emissions; no stable event id — KEY-WP-0044-T02.

2. Source registration

Item	Value
source	netkingdom.keycape (proposed)
Owning repo	key-cape (runtime package owner: UNKNOWN, the Railiance/rapp package that deploys KeyCape)
Namespace / pod selector	UNKNOWN — to be taken from the deploying package; KeyCape does not own its manifests
Emitting identity	a dedicated KeyCape audit sender credential (section 6); not a KeyCape OIDC client
Tenant policy	per-tenant: the event's tenant is the principal's tenant; platform-scoped events (client auth failure before a tenant is known, service clients without a tenant) use a platform tenant value — UNKNOWN, audit-core to name it

3. Envelope mapping (audit-core docs/event-envelope.md)

Envelope field	KeyCape value
id (= Idempotency-Key)	event_id: UUIDv7 minted once when the event is created and reused on every retry (KEY-WP-0044-T02). Not derived from request content, so two identical logins stay distinct
type	keycape.<action> from section 4
source	netkingdom.keycape
subject	the principal (sub/uid) for user events; client:<client_id> for client-only events
tenant	principal tenant, else the platform tenant value
correlation_id	W3C trace-id from inbound traceparent, or a generated one (contract AC-1, AC-4)
occurred_at	event timestamp, RFC 3339 with offset (UTC Z)
data	client_id, endpoint, result, error_type, grant_type, scopes, assurance, principal_type, environment, correlation_origin (propagated/generated), optional parent_event_id

Never in data: access/ID/refresh tokens, authorization codes, client secrets, passwords, OTPs, email. actor is null at ingest per the envelope; the authenticated subject lives in subject/data.

4. Scope rows (action vocabulary)

type	Today	Meaning
keycape.auth.start	yes	authorize request accepted
keycape.login.success	yes (auth_success)	user authenticated, with assurance
keycape.login.failure	yes (auth_failure)	upstream auth failed or stale
keycape.mfa.success	partly (aal2 on auth_success)	MFA/step-up satisfied
keycape.mfa.failure	yes (mfa_failed, mfa_check_error)	MFA challenge failed or errored
keycape.token.issued	yes	token issued (any grant)
keycape.token.denied	no	/token refused: invalid_grant, invalid_scope, unauthorized_client
keycape.client.auth_failure	no	client authentication failed at /token, revoke or introspect
keycape.scope.denied	no	requested scope, tenant or principal-type precondition refused
keycape.token.revoked	no	revocation accepted
keycape.token.introspected	no	introspection served (volume to be judged; may be excluded)
keycape.userinfo.served	yes (auth_success on /userinfo)	userinfo served
keycape.profile.unsupported_feature	yes	request used a feature the profile refuses
keycape.heartbeat	no	liveness, section 5

migration_event is excluded: it comes from offline tools, not the server.

5. Volume, heartbeat, retention

• Volume: UNKNOWN — no production measurement exists. Estimate for the current one-node estate with a handful of users and six flex-auth consumers: low hundreds to a few thousand events/day, peak under 5/s, dominated by token.issued (client_credentials) and userinfo.served. To be replaced by a measured count from the stdout stream before overlay sizing.
• emission_cadence: event-driven plus keycape.heartbeat every 5 minutes; proposed silence threshold 15 minutes.
• Retention: audit-core default 30-day query window plus archive. Proposed archive for login/MFA/token/denial records: 1 year (security-relevant identity evidence). Final class is a NetKingdom/audit-core decision — UNKNOWN.

6. Credential path

The sender secret is minted through the attended OpenBao path that warden route find "audit-core sender credential" points to (railiance-platform OpenBao), delivered to the KeyCape pod as a Kubernetes Secret reference, and never in Git, State Hub, logs or this document. audit-core never holds or prints it; may_read stays false; may_write is limited to source netkingdom.keycape. The exact OpenBao path and delivery mechanism are UNKNOWN until railiance-platform names them.

7. Export mechanism

Open choice, recorded in KEY-WP-0044-T03: (a) a collector tailing KeyCape's stdout JSON lines and posting envelopes, or (b) a KeyCape AuditEmitter posting directly with retry on the stable event_id. Preference: (b), because event_id and correlation_origin are known only inside KeyCape and a log tail cannot guarantee idempotent retry. UNKNOWN until audit-core states its preferred intake for application senders.