Document exact native signer and CLI admission requirements

Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a140c4-354a-7823-8f0d-8f717397f786

docs/proposals/native-cli-admission/README.md

@@ -0,0 +1,158 @@
+# Native CLI signer and consumer admission preparation
+
+This proposal covers the existing lifecycle CLI authentication path under
+SECRETS-WP-0014. It grants no installation, key retrieval, caller mint, approval
+consume, OpenBao effect or task-policy activation. All native acceptance counts
+below are zero. Exact missing owner inputs are in `proposal.json`.
+
+## Current consumer and initial scope
+
+At source `ff1a13d`, the workstation has the repository's editable v0.1.0 CLI
+entrypoint at `/home/worsch/secrets-engine/.venv/bin/secrets-engine`, importing
+`secrets_engine.cli:main`. There is no global `~/.local/bin/secrets-engine` or uv
+managed Secrets tool. Presence-only inspection of this session found none of the
+PDP/trust/approval/policy/configuration variables set. This says nothing about
+other sessions, private owner configuration or a remote installation. No credential
+file, private configuration or process environment was inspected.
+
+Use a separately reviewed immutable wheel-plus-verifier bundle for proposed
+adoption. The canonical source for the candidate build is **ff1a13d**, containing
+both CLI packaging and strict R2 handoff; earlier c80-based proof bundles are
+intermediate source evidence. Custodian `decision-native-preparation/` retains the
+exact canonical bundle manifest and hashes. Nothing was installed by this step.
+
+Initial stage is signer-only existing lifecycle-pin admission plus offline
+verification of captured native signed allow and deny records. Capturing those
+records later needs its own admitted caller and exact source operation; this
+proposal does not grant that capture. Use Access's one receipt verifier,
+`tools/verify_native_signer_receipt.py`, with its reviewed admission file rather
+than creating another consumer verifier or canonicalization implementation.
+That tool is separate Access source preparation; its exact integrated revision
+and reviewed admission file remain owner inputs, not part of this CLI install.
+
+The producer-owned offline pin is `secrets-engine.catalog-lane.lifecycle` v2,
+`sha256:bd11c5fe77ce6439c65fea225ad6b71d2110efc5e7b5bc9b499c59cd0a53b8b4`,
+evaluator `flex-auth/local`, mode `standalone`. A source digest is not proof of the
+live image's source or policy. Access's live metadata records the current pin has
+no signer arguments/mounts; no production kid/public key/fingerprint/custody
+receipt or candidate signed-runtime OCI digest is admitted. The proposed signer
+custody route is draft/nonresolvable. Do not fill those gaps from fixture keys or
+from the same responder's keys endpoint. The independent receipt must bind signer
+purpose/custody to this exact consumer pin and declare any sharing. A shared key
+plus the generic evaluator name cannot prove an individual pod's identity; the
+owner-bound tunnel and rollout identity still require separate verification.
+
+`lifecycle-trust.template.json` uses the existing runtime trust schema and the
+producer-owned source pin, but deliberately has an empty key map. It **must
+refuse** before caller credential access. It is not a deployable trust file. A
+future owner-admitted copy must contain the independently authenticated actual
+kid/key and exact pin, with its public-key fingerprint/custody provenance retained
+outside this unadmitted template. The task-policy coordinate is not admitted here.
+
+## Exact PEP denominator
+
+The initial shared authentication implementation is one Check client reached
+through `authorize_action` and `_require_lane_approval`. Native protected-effect
+coverage remains **0 of 11 serving CLI call sites across 10 handlers**, not one
+PEP per catalog row. The current lifecycle policy's action vocabulary has twelve
+values; that is a separate count from handler/call-site coverage.
+
+| CLI path | Handler / delegated authorization site | PDP action |
+| --- | --- | --- |
+| apply, live only | `cmd_apply` | apply |
+| provision | `cmd_provision` | provision |
+| rotate, live only | `cmd_rotate` | rotate |
+| verify | `cmd_verify` | verify |
+| handoff | `cmd_handoff` | handoff |
+| wrap | `cmd_wrap` | wrap |
+| exec primary | `cmd_exec`, primary gate | exec |
+| exec companion | `cmd_exec`, delegated companion gate | exec for each companion; separate claim/CAS, same call site |
+| revoke, live only | `cmd_revoke` | deactivate |
+| lifecycle compromise/reactivate, live only | `_cmd_lifecycle_state` | selected compromise/reactivate; local state mutation |
+| lifecycle suspend/deactivate/destroy, live only | `cmd_lifecycle` | selected operation |
+
+`session revoke` is a separate stance/readiness-controlled backend path without
+this served Check/CAS chain; it is excluded from this signer acceptance and still
+refuses production under its stance. `service-auth probe-openbao` is an explicit
+identity/login-self probe, not protected task adoption. `route` performs existing
+backend readiness metadata probes through its ambient backend resolver; it is not
+closed by this signer proposal. Dry-run/plan/catalog/audit/source evidence commands
+are not protected-effect proof. These exclusions must remain visible in any claim
+about the whole repository's PEP coverage.
+
+The existing CLI handlers still use the generic `require_production_consume`
+response contract. Strict R2 task consumption is a separate owner API, not a
+retrofit of all eleven CLI sites. Native effect acceptance must review the actual
+selected handler/consume contract and caller scope rather than borrow the task
+fixture proof.
+
+No production effect is authorized merely because a handler shares the signed
+client. In particular, configured `service-jwt` still refuses protected CLI work
+before approval/CAS/backend because CCR38 is identity-only. Do not select
+bootstrap/env, alter the stance or enable unsafe-demo to manufacture acceptance.
+
+## Owner-controlled placement and minimum configuration
+
+The deploying owner must select the runtime UID, fresh release prefix, configuration
+parent and exact runtime paths; none is agreed by this proposal. The future
+admitted executable is `<prefix>/bin/secrets-engine`, whose wrapper fixes the
+bundle helper and checks its digest before CLI import. The helper's source/binary
+hash is artifact integrity, not independent package or key admission. Do not use
+the editable checkout, a rolling alias, a synthetic test prefix or an internal
+venv entrypoint as if it were that admission.
+
+Explicit absolute owner-admitted catalog, policy, `SECRETS_ENGINE_PEP_STANCE`,
+trust and evidence/outbox locations are needed. Installed-package defaults fall
+back to working-directory metadata and are not an admitted native configuration.
+The total existing stance remains prod fail_closed. Config needs the exact
+producer policy/version, service subject, loopback owner-bound PDP tunnel and
+separately admitted bounded audience `flex-auth` caller-file lifetime. Approval
+endpoint and its existing separately scoped credential delivery must be admitted
+independently. Both approval credential providers may not be configured together.
+The bundle helper is not selected by an ambient override. Runtime credentials and
+keys are not placed in this proposal or release bundle.
+
+Acceptance order is: admit exact package/source/install/config; obtain independent
+signer/key/pin custody return and exact signed producer rollout candidate; under
+that separately reviewed rollout capture bounded native records; run Access's
+single offline receipt verifier against the fixed installed helper and admitted
+trust; prove forged/altered/unknown/unsigned/wrong-pin/expired refusal and exact
+old/new-key overlap then removed-key refusal. Also close the producer's missing
+native durable log/outbox/audit path under its owner. No install or rollout is
+performed here, and shared-source tests do not fill native effect coverage.
+
+Rollback retains the reviewed signed producer and admitted overlap or stops the
+consumer. Rolling back to an unsigned image is an outage, not permission to turn
+off verification. Removing keys, changing policy pins or restoring removed keys
+needs exact owner review; no discovery/cached-key fallback or blind consume retry.
+
+## Separate task-execution gap
+
+Strict `task_execution_handoff` exists and Platform's independently confirmed
+journal/native fixture path has actual source-server proof. Neither creates an
+existing `execute-ccr` CLI command: the current parser has none. Proposed task
+caller mapping/request join, policy admission, production source/Plan/grant and
+installation/journal/cleanup placement remain separate owner decisions. Both
+Access task-policy runtime false gates remain unchanged; lifecycle apply is not
+a substitute for execute-ccr. Platform has selected no fresh approved real
+CCR/catalogue/descriptor/grant. CCR42 is in_flight and lacks a matching Secrets
+catalog; synthetic CCR2/issue-core fixture bytes and temporary paths are not native
+inputs. Actual before/after bytes for the exact metadata targets and independent
+readback/cleanup receipts must come from Platform's eventual owner-selected plan.
+
+For future server-owned Approval facts, strict R2 deliberately requires the
+returned binding context to equal the originally submitted context. B1 caller
+join remains signed-DENY and must preserve that context. Replacing the carried
+claim with a freshly observed blob would refuse because its freshness fields
+change; no generic equality relaxation is proposed. Access's current review
+preference is to validate fresh authoritative facts out of band while retaining
+the submitted context, with reviewed producer-owned signed source/receipt evidence.
+Exact stable fact/freshness and provenance correspondence requires Approval and
+Access review before B2/B3; no new fields or behavior are implemented here.
+
+The Approval owner's pending `approval-fact-contract/consumer-contract.md` and
+`golden-vectors.json` in the Custodian target evidence name this correspondence.
+They require both original/fresh windows and exact nonfreshness authority facts.
+Their Python native numeric canonical vectors still need producer conformance;
+no silent digest translation or new target numeric restriction is admitted.
+The proposal pins those owner artifacts for review, not as B2 implementation.