secrets-engine/docs/proposals/native-cli-admission

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.