# ops-warden — NetKingdom security layer declaration
#
# Framework: net-kingdom/canon/standards/security-layer-model_v0.4.md
# Assent:    docs/adr/ADR-0010 (ops-warden's own voice, per §11 "who must declare")
# Validate:  python3 scripts/check_layer_conformance.py
#
# §11 makes one check mechanical: "every direct Tooling client in a Staff
# repository maps to a declared §5.1, §5.2, or §5.3 entry". This file is that
# map. It is machine-readable because §5.3 requires it to be — ops-warden
# proposed that shape and is implementing it rather than declaring in prose.
#
# Conformance rule inherited from tenancy.yaml: accuracy, not altitude. A
# declared gap is TRACKED NON-CONFORMANCE (§11), never a claim of conformance.

schema_version: "0.1"
framework: netkingdom-security-layer-model
standard_version: "0.4"
repository: ops-warden
layer: staff
declared_by: docs/adr/ADR-0010
declared_at: "2026-08-29"

# §6.4 — ops-warden is PEP-shaped (it causes a protected side effect: issuing a
# certificate). Its unreachable-engine stance map is published separately, and
# asserted equal to shipped behaviour by tests/test_layer_conformance.py.
pep_stance: pep-stance.yaml

# Every direct contact with a Tooling-layer system (§4), one entry each.
tooling_contacts:

  - id: ssh-ca-signing-write
    shape: "5.3"                      # declared engine gap
    module: src/warden/vault.py
    symbol: VaultCA.sign
    tooling: OpenBao
    operation: "HTTP POST <addr>/v1/<mount>/sign/<role> with X-Vault-Token"
    write: true
    capability: "Sign a short-lived SSH certificate for an adm/agt/atm actor"
    intended_owner: secrets-engine
    blocked_on: >-
      No engine exposes an SSH certificate signing surface. secrets-engine owns
      credential abstraction, custody and lifecycle, which is the layer this
      belongs in, but fronts no SSH-CA API today.
    review: "2026-11-28"
    note: >-
      Production-verified and in daily use. This is the one lane ops-warden owns
      permanently (§4). Signing continues while the gap is open: refusing would
      remove production host access to close a documentation gap.

  - id: desk-paste-once-provision
    shape: "5.3"
    module: src/warden/desk.py
    symbol: _provision_to_openbao
    tooling: OpenBao
    operation: "bao kv put <path> <field>=- (value on stdin, never argv)"
    write: true
    capability: "Founder paste-once provisioning of a secret straight into OpenBao"
    intended_owner: secrets-engine
    blocked_on: >-
      No engine exposes an attended provisioning surface for a value the founder
      holds and no automated path can produce.
    review: "2026-11-28"
    note: >-
      Attended and founder-operated (WP-0029). The value reaches OpenBao without
      passing through a terminal, an argv, or the audit log.

  - id: taint-metadata-read
    shape: "5.1"                      # read-only diagnostic observation
    module: src/warden/taint.py
    symbol: fetch_taint_status
    tooling: OpenBao
    operation: "bao kv metadata get -format=json <path>"
    write: false
    capability: "Report EXPOSED taint (custom_metadata) without reading secret data"
    intended_owner: secrets-engine
    blocked_on: >-
      No engine exposes a disclosure-taint query. Metadata-only by construction —
      reading the data would be the 2026-07-16 vector this exists to avoid.
    review: "2026-11-28"

  - id: access-proxy-conduit
    shape: "5.2"                      # conduit
    module: src/warden/proxy.py
    symbol: proxy_fetch, proxy_attended_login_exec
    tooling: OpenBao, key-cape
    operation: "Runs the catalog-declared owner fetch_command as a child process"
    write: false
    capability: "warden access --fetch/--exec/--out/--wrap for exec_capable lanes"
    supplied_authority: none
    evidence:
      no_own_credential: src/warden/proxy.py::_caller_env
      test: tests/test_proxy.py::test_conduit_supplies_no_authority_of_its_own
      audit: "audit.jsonl records the caller, the lane, and the outcome; never a value"
    note: >-
      The §5.2 test is the supplied-authority property: ops-warden presents no
      credential of its own, cannot widen what the caller could already do, and
      the action reconstructs as the caller's. Governed by ADR-0002.

  - id: caller-identity-token
    shape: "5.2"
    module: src/warden/caller_identity.py
    symbol: resolve_caller_token
    tooling: OpenBao
    operation: "Runs the operator-configured caller_auth command, or reads token env"
    write: false
    capability: "Establish the caller's own identity for the pre-sign policy gate"
    supplied_authority: none
    detection: voluntary   # runs an operator-configured command, so no fixed
                           # argv shape to scan for; declared rather than omitted
    note: >-
      Obtains the CALLER's credential by the operator's configured means; adds no
      authority. Never mints, and never persists what it resolves.

# Contacts that are deliberately NOT Tooling contacts, recorded so the check is
# total rather than silently selective.
non_tooling_clients:

  - module: src/warden/policy.py
    target: access-engine (flex-auth)
    rationale: "Engine API — §5 permits it; this is the shape §5 prescribes."

  - module: src/warden/worker.py
    target: state-hub, llm-connect
    rationale: >-
      Not catalogued in §4. The layer catalog scopes the security estate, and
      neither the State Hub nor llm-connect appears in it, so no §5 shape applies
      on the standard's own terms. Raised with gate-house 2026-08-29 as a scope
      question rather than resolved unilaterally — see the assessment note.