tegwick
4b4d556d62
Every live privileged production handler CAS-consumes through approval-engine before OpenBao. Conflict, unavailability, or a missing binding fail closed. Live production remains disabled until the durable decision record is served. Record kings-guard assent on the secret-use evidence contract. Assistant: grok Assistant-Session: 01a05f07-ae72-7781-9fcb-19efd61add00
87 lines
3.9 KiB
Markdown
87 lines
3.9 KiB
Markdown
# Secret-use evidence engine contract (proposed)
|
|
|
|
Status: **proposed**. `layer.yaml` owner_status remains `proposed` until this
|
|
surface ships. kings-guard must assent or contest before it is treated as an
|
|
observation input.
|
|
|
|
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.
|
|
|
|
## 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. Recommended maximum age
|
|
for posture evaluation is the heartbeat interval declared in
|
|
`evidence-classification.yaml` (`1d`) until a tighter contract is assented.
|
|
|
|
## 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.
|