railiance-platform/layer.yaml

# railiance-platform — DERIVED form of the NetKingdom security layer declaration
#
# THIS FILE DOES NOT GOVERN. The declaration is the `layer:` key in INTENT.md's
# frontmatter; this file is a derived artifact under §11's derived-artifact rule
# and must agree with it (GH-DEC-2026-017 §1, amendment A11). Comparison of the
# §3 vocabulary is ASCII case-insensitive (GH-DEC-2026-017 §2): INTENT.md's
# `Staff` and this file's `staff` are the same value and neither is re-spelled.
# A disagreement that survives the fold is a finding, reported, not resolved
# away by precedence.
#
# Framework: net-kingdom/canon/standards/security-layer-model_v0.7.md
# Companion: net-kingdom/SECURITY-COMPANION.md
# Declared:  INTENT.md frontmatter and body prose (§2 — own voice, own repo)
# Form:      adapted from ops-warden's reference layer.yaml, offered estate-wide.
#            layer.yaml is a convention, not a schema; gate-house confirmed on
#            2026-09-09 that v0.7 defines no shape for this file. Following the
#            practice because §5.3 requires gap records to be machine-readable.
#
# 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

# §11 derived-artifact marking (GH-DEC-2026-017 §1 / A11).
derived: true
derived_from: INTENT.md

# No `standard_version` key: a layer declaration MUST NOT carry a standard
# version (GH-DEC-2026-017, amendment A12). Version-scoped state belongs in the
# derived conformance record, which this repository does not yet produce (see
# gaps.conformance-check-script).
repository: railiance-platform
layer: staff
role: null
declared_by: INTENT.md
declared_at: "2026-09-09"

# §8 self-assessed state. Declared gaps below; nothing here is claimed as
# conforming, and no contact is omitted to improve the label.
conformance_state: declared-gap

# §5 / §6.4 — railiance-platform IS PEP-shaped. Applying an OpenBao policy,
# seeding or rotating a workload credential, and activating a delivery lane are
# protected side effects caused on this side. Being PEP-shaped does not change
# the Staff layer (§5 preamble).
pep_shaped: true
pep_stance: null          # NOT YET PUBLISHED — see gaps.pep-stance-map below.

# Every direct contact with a Tooling-layer system (§4: key-cape, OpenBao),
# grouped by capability rather than by file. 28 files in this repository invoke
# `bao`; they exercise the five capabilities below.
tooling_contacts:

  - id: openbao-attended-operator-login
    shape: "5.2"                      # conduit
    module: scripts/openbao-attended-exec.py
    tooling: OpenBao
    operation: "exec into `warden access openbao-platform-admin-login --exec -- <cmd>`"
    write: false
    capability: "Run a reviewed owner command under the founder's own attended OIDC identity"
    supplied_authority: none
    note: >-
      The §5.2 test holds: this repository presents no credential of its own,
      cannot widen what the founder could already do, and every action
      reconstructs as the founder. It supplies only a WSL browser launcher when
      the host lacks one. ops-warden owns the envelope and self-revokes the
      temporary token helper.

  - id: openbao-policy-and-auth-apply
    shape: "5.3"                      # declared engine gap
    module: scripts/openbao-apply-workload-kv-lanes.sh, scripts/openbao-apply-token-grants.py, scripts/credential-change.py
    tooling: OpenBao
    operation: "policy write; write auth/<mount>/role/<name>"
    write: true
    capability: "Apply the exact-path read policy and bound auth role for a reviewed credential lane"
    intended_owner: secrets-engine
    blocked_on: >-
      secrets-engine owns credential abstraction, custody and lifecycle, and is
      the layer this belongs in, but exposes no policy/role application surface.
      SECRETS-WP-0006 is cutting the first native lanes; until a lane is served
      there, application stays here behind an attended founder session.
    review: "2026-12-09"

  - id: openbao-kv-custody-write
    shape: "5.3"
    module: scripts/keycape_approval_custody.py, scripts/state_hub_preflight_lane.py, scripts/provision-policy-nexus-forgejo-source.py
    tooling: OpenBao
    operation: "kv put / kv patch with compare-and-set, value on stdin, never argv"
    write: true
    capability: "Seed or rotate a workload credential under attended founder custody"
    intended_owner: secrets-engine
    blocked_on: >-
      Same gap as above. No engine exposes an attended provisioning or rotation
      surface for a value the founder holds. Every write here is CAS-guarded,
      attended, and emits a mode-0600 metadata receipt with no value.
    review: "2026-12-09"

  - id: openbao-read-diagnostic
    shape: "5.1"                      # read-only diagnostic
    module: scripts/keycape-approval-custody-preflight.py, scripts/openbao_open_questions_session.py, scripts/openbao-verify-token-grants.py
    tooling: OpenBao
    operation: "token capabilities; policy read; kv metadata get; kv get (field names only)"
    write: false
    capability: "Produce acceptance and drift evidence for a lane without mutating it"
    note: >-
      No engine exposes these reads. Values never reach argv, disk, stdout or a
      receipt; where a data read is unavoidable to enumerate field names, only
      sorted key names leave the process. This is a gap to close, not a licence.
    review: "2026-12-09"

  - id: openbao-service-operation
    shape: "5.3"
    module: Makefile (openbao-deploy, openbao-overlay-apply), helm/openbao-values.yaml
    tooling: OpenBao
    operation: "helm upgrade of the OpenBao release; unseal and snapshot procedures"
    write: true
    capability: "Operate the OpenBao instance itself — deployment, listener, unseal, snapshot"
    intended_owner: unassigned
    blocked_on: >-
      §4 is explicit that there is no operator-of-third-party-Tooling shape:
      someone must run OpenBao and that stays a declared gap whose review keeps
      returning. Recorded here so the absence is visible rather than assumed
      benign. No engine is expected to take this; the review is the point.
    review: "2026-12-09"

  - id: keycape-client-secret-custody
    shape: "5.3"
    module: scripts/keycape_approval_custody.py
    tooling: key-cape
    operation: "read/patch Secret sso/keycape-config and the client-secret Secrets it references"
    write: true
    capability: "Deliver a KeyCape client secret into the KeyCape runtime and verify the delivery matches custody"
    intended_owner: secrets-engine
    blocked_on: >-
      KeyCape owns registration, issuance and disablement and deliberately ships
      no command for custody writes (their position, which we accept). No engine
      fronts the delivery half. Exercised once, attended, on 2026-09-09 under
      CCR-2026-0017/0018.
    review: "2026-12-09"

# Contacts recorded so the check is total rather than selectively silent. §4
# asks for uncatalogued infrastructure to be listed anyway.
non_tooling_clients:

  - target: Kubernetes / CloudNative-PG / External Secrets (railiance01)
    module: Makefile (db-*, apps-pg-*), argocd/platform-addons/
    rationale: >-
      Not catalogued as Tooling in §4. This is the substrate axis under §9
      (reef-*), and §9 states the axis-to-layer mapping is unsettled (statute
      §20.3). Listed rather than mapped; we are not assuming a mapping.
    note: >-
      This is the largest single contact by volume and the one most likely to be
      recatalogued. If §4 grows to cover the cluster, these become §5.3 entries
      and this file changes shape, not just content.

  - target: State Hub
    module: session protocol in .claude/rules/, scripts/*state_hub*
    rationale: "Not catalogued in §4; the companion names it explicitly as outside the rule."
    note: "Read model. The only sanctioned write is resolving a decision; progress events reflect work already done."

  - target: Forgejo, Scaleway object storage, Nextcloud
    module: scripts/forgejo_package_prune.py, lib/railiance-backup-common.sh
    rationale: "Not catalogued in §4. Backup destinations and the forge are consumed, not operated as security Tooling."

  - target: flex-auth / access-engine, approval-engine
    module: docs/credential-lane-designs/, CCR review flow
    rationale: "Engine APIs — §5 permits it; this is the shape §5 prescribes. Decisions and approvals are consumed as claims, never rendered or cached here."

# §5 obligations this repository owes and has not met. Declared rather than
# omitted; the standard ranks a declared gap above silence (§8).
gaps:

  - id: pep-stance-map
    obligation: "§5 obligation 3 — publish a total unreachable-engine stance map"
    state: not-published
    intended_path: pep-stance.yaml
    blocked_on: >-
      The map must be total over its axis with no implicit default, and this
      repository does not own the zone axis it would enumerate. Every protected
      side effect here is currently attended and founder-gated, so no unattended
      branch has yet had to decide without a reachable engine — that is the
      reason the gap has not bitten, not a substitute for the map.
    build_to: "0.8"
    note: >-
      gate-house advised on 2026-09-09 to build to v0.8's tightened obligation 3
      rather than v0.7's and skip a migration: unknown must resolve to
      fail_closed, the map must enumerate its axis rather than lean on a
      catch-all, and the published-equals-shipped test is being promoted from
      SHOULD to MUST.
    review: "2026-10-09"

  - id: statute-13-1-registration
    obligation: "§5 obligation 3 — register the stance map in statute §13.1"
    state: not-registered
    blocked_on: "Depends on pep-stance-map. A map only we can read is not published."
    review: "2026-10-09"

  - id: conformance-check-script
    obligation: "Mechanical check that this declaration matches the repository"
    state: not-implemented
    blocked_on: >-
      ops-warden's scripts/check_layer_conformance.py and
      tests/test_layer_conformance.py are the part that makes this file more
      than a claim. Until an equivalent runs here, every row above is an
      assertion and is marked as such by this gap rather than by silence.
    review: "2026-10-09"