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

# Native CLI signer and consumer admission preparation

## Current release preparation — 2026-10-16 R2

Published canonical Secrets `4dd004a2250104ba56293b2d7b0d96f4e076ea99` was
built twice from an isolated clean checkout. Artifacts and deterministic bundle
manifest match exactly: manifest SHA256
`sha256:105dcebe6f03e9799f91ea75175e20500df2aa7f08b5e32d39c1c367593ca47e`,
fixed helper SHA256
`sha256:ed922b62533e4d33ae2d5f11175111f6f28e684a19e63ac704d43b63f0e0e12e`.
Disposable installation/help and empty native trust refusal pass; no native
prefix, trust/key, caller credential, protected effect or rollout was admitted.
Artifact integrity is not independent package admission. Full receipts and a
concrete probe/placement proposal are in Custodian `decision-native-preparation/r2/`.

Initial native scope remains the existing lifecycle pin and **0/11 protected
sites across10 handlers**. Runtime UID/release/config/catalog/stance/trust/evidence
and scoped caller/Approval delivery paths remain owner-unselected. A concrete
workstation candidate uses a new release prefix ending
`4dd004a22501-105dcebe6f03`; it is a proposal, not an installed/admitted path.
Only its exact future `bin/secrets-engine` wrapper is the effect entrypoint.
The current repo editable invocation and ambient demo/preflight fallbacks do not
constitute release admission. A local CLI does not automatically hold the named
ServiceAccount identity: existing docs describe separately authorized per-session
TokenRequest delivery, not a standing credential or pod identity grant.

Access's single offline signer-receipt tool is published at
`2b064eee510640224274ccdc7cefceb1ae13162e`; verified API/sign source matches this
consumer. Native producer rollout still awaits independent public kid/key/custody
and immutable candidate image/log/storage returns, including the Access owner's
separate durable-log hardening review. Published source alone is not that image.
The lifecycle pin stays v2/bd11c5fe...; task v2 is a separate unadmitted pin.

Source task correspondence is now implemented and cross-owner source-server
proved: fixed typed service mapping before issue, retained-registry signed-DENY
preapproval, original claim/context preservation, independent fresh source facts,
precise Approval CAS and independent confirmation/journal/native disposable proof.
This supersedes the historical source gaps below; it neither adds an execute-ccr
CLI command nor selects a real CCR/catalogue/Plan/grant/backend/journal runtime.
All native effect, caller/key/config and task-entitlement gates remain open under
existing WP14/WP13/WP8 records. `service-jwt` still refuses protected CLI work.

## Historical ff1a13d preparation (preserved)

The following draft records the earlier source/admission observations. References
to absent B2/B3/request/source-fact implementation are superseded by R2 above;
missing native keys, runtime placement and actual task inputs remain unresolved.


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.