secrets-engine/docs/secret-use-evidence-contract.md

Secret-use evidence engine contract

Status: shipped as secrets-engine secret-use snapshot. Observation-input admission remains proposed until kings-guard consumes it. layer.yaml owner_status stays proposed until that admission. Completeness is not claimed.

Standard: NetKingdom Security Layer Model v0.7 §9.6. Companion: net-kingdom/SECURITY-COMPANION.md §6.

What this is

A read-only Lifecycle engine surface of non-secret lease, revocation, mount, rotation, and delivery-session metadata, so kings-guard can evaluate secret-abuse posture without a vault client.

secrets-engine route and secrets-engine audit are operator summaries over local JSONL. They are not this surface. The shipped command is secrets-engine secret-use snapshot [--catalog-id ID] [--json]. It reads the catalog and local evidence only. It never contacts OpenBao.

Bound (normative)

The archive proves the records it holds were not altered or truncated after arrival. It does not prove a record was sent. Absence of a record is not evidence of non-occurrence. Completeness is not claimed.

This surface cannot close adversarial omission at a compromised source. Cadence for load-bearing classes is a heartbeat (secrets-engine evidence heartbeat), not rate monitoring.

Fields (non-secret)

Field	Meaning	Freshness
as_of	UTC timestamp of the snapshot	Snapshot time
catalog_id	Lane id	Catalog load
stage	build | test | prod	Catalog load
kind	kv | auth-capability	Catalog load
mount	OpenBao mount name	Catalog load
path	KV path or allowlisted auth path, never a value	Catalog load
field_names	Declared field names, never values	Catalog load
ready	All declared fields present (boolean)	Last route/verify
session_handle	Accessor fingerprint only	Last exec/verify
revocation_attempted	Boolean	Last session
revocation_succeeded	Boolean	Last session
lifecycle_operation	suspend | deactivate | destroy | revoke if one ran	Last lifecycle
decision_id	Present only where a decision was rendered	Last privileged action
stance_stage / stance_failure_mode	Named PEP residue	Last privileged action
evidence_kind	load-bearing | attributive | heartbeat	Per record

Forbidden in this surface: secret values, tokens, passwords, AppRole secret_id, raw accessors, certificate private keys, subprocess argv, and exception prose.

Freshness

Every row carries as_of. There is no cached authorization verdict. A consumer must not treat a stale snapshot as a standing allow. Cadence for load-bearing classes is the heartbeat declared in evidence-classification.yaml:

form: heartbeat
interval: 1d
command: secrets-engine evidence heartbeat

The snapshot envelope repeats that cadence. Evidence-derived fields (ready, session, stance, decision id) appear only when a local record exists. Omission is not non-occurrence.

Destination

Intended owner of custody is audit-core. Today the engine queues load-bearing records in evidence_dir/outbox/ and writes attributive records to local JSONL. Drain to audit-core is best-effort and is never on the mutation path.

kings-guard reads this engine surface, not OpenBao.

Non-responsibilities

This surface does not decide whether an action is permitted, does not expose an approval-validity query, does not prove omission at source, and does not observe production events kings-guard has not received. Companion §10 still holds: nothing is observed in production until kings-guard reports otherwise.

Assent

A coordination message to kings-guard records this contract. Assent or contest belongs in kings-guard's own voice.

2026-09-01: kings-guard assented, in its own voice (State Hub message 75ebd2cc-a166-4676-94aa-deef2791c0c9), to this document as a proposed Engine / Lifecycle read-only non-secret surface. Assent covers: no secret values; destination audit-core; completeness not claimed; heartbeat rather than rate monitoring for load-bearing classes; kings-guard reads this engine surface, never OpenBao. kings-guard will not consume it as an observation input until the surface ships and publishes its cadence declaration. layer.yaml owner_status remains proposed until that surface exists.