engrt auth¶
Goal: inspect a platform's verified identity or native readiness and request explicit native logout. Runtime never creates its own credential store — see Authentication for the model.
Providers: github, gcp, kubernetes, openshift.
This reference describes authentication as of v0.13.0; version-tagged notes mark when a behaviour was introduced.
v0.12.0
v0.12.0 adds an optional ENGRT GitHub session in the OS secure store
(engrt auth login github device flow, granted_scopes, host-bound logout). See
Governed authority.
No GitHub source available yet (engrt auth status, fresh Home with no token):
On a host with no OS secure store the code is auth_store_unavailable, and the
message names the store-free sources (ENGRT_GITHUB_TOKEN / source: env,
source: file, source: github_app). On a CI or pod surface an OS-store session is
refused with auth_surface_mismatch (local_session_unavailable_on_surface), and
the message says which sources work there.
engrt auth status¶
A diagnostic across every enabled provider, with durable auth intent and completion. Native tools may refresh their own caches while answering.
Only providers with enabled: true in
config.yaml are checked. A disabled
provider costs nothing — no code path for it runs.
JSON adds proof, credential_source and credential_class, and retains
specific auth_* failure categories in error_code. Only
principal_verified supplies a verified subject; credential_ready and
configuration_ready leave it empty. A completed status report still exits 0
when individual providers report credential errors. Configuration, cancellation,
scratch cleanup or evidence failures exit 1. Status is not authorization for the
next operation.
Verified principals require a valid keyed identity projection in local audit. If the privacy key cannot be loaded or created, v0.9.9 reports evidence failure instead of successful authentication with an empty identity digest. A native auth action may already have refreshed its own state; the failure does not mean no effects occurred and is never automatically retried. Configuration/ credential readiness has no verified-principal digest requirement.
On an evidence failure, JSON is one failure object with
error_code: evidence_finalization_failed and a result containing the observed
proof, provider, credential source/class and subject_resolved, not the raw
subject or token. For an interrupted auth status, result is the array of
provider observations collected before the failure; the command exits 1.
Successful auth output is unchanged. An observed proof is not evidence that its
audit completed, and repeating login/logout is not an evidence-repair operation.
The key is loaded through private no-follow descriptors with serialized creation and exact size checks. Empty/truncated, shared-permission or aliased key state refuses; it is never silently replaced. See privacy-key recovery limits before attempting a repair, since replacing the key changes historical correlation.
auth status is a diagnostic, not a prerequisite
There is no pre-flight auth check anywhere in the execution path.
Nothing you run invokes auth status internally. Each execution validates
the provider its operation needs, inline — so a capability's steps
re-validate once per step. No session is established or reused.
For a fuller picture, including installed-binary checks and policy warnings,
use engrt config validate.
Native auth scratch and cleanup¶
Standalone native auth uses private per-user scratch under the OS temporary root, with descriptor-bound ownership and active-operation leases. Prepared command probes borrow their command's environment/cwd and never remove its scratch. Native credential homes remain tool-owned; Runtime does not copy or cache their credentials. See scratch ownership and recovery.
Cleanup failure exits 1 with operation_cleanup_failed, preserving the action's
safe observed proof or logout completion in result. This failure does not
invalidate a principal already verified by the native tool or undo logout. A
separate native failure category remains in the observation's error_code;
raw native stdout/stderr, filesystem causes, subject and token are withheld.
If evidence also fails, outer evidence_finalization_failed takes precedence.
For auth status, failure result is the provider observations collected so far.
For config validate, they are under result.auth_statuses. A scratch cleanup
failure stops further auth probes instead of returning a completed status report.
Ordinary credential failures retain the diagnostic exit-0 behavior described above.
Do not repeat a completed login/logout just to clear scratch. Repair the underlying
storage/permissions problem after verifying native users are quiescent. A later
allocation can reclaim only recognized finished, inactive ownership; unknown,
legacy and unfinished directories are preserved. audit recover neither removes
scratch nor replays native actions. File Engine grants cannot edit the selected
auth scratch namespace or operation lease controls to bypass this protection.
engrt auth login <provider>¶
Validates one provider explicitly. Audited.
This is a validation, not an interactive login. The runtime never opens a browser and never starts a platform's login flow. If a session is missing or expired, the error names the command to run yourself:
Per provider¶
Validated against GET <base_url>/user.
Reports native CLI credential readiness using a selected account and bounded token probe. It does not claim the configured account as a verified API principal, and it does not validate ADC.
Validated by reading the kubeconfig's current-context directly — no
shell-out, no kubectl dependency for the check itself. This is configuration
readiness, not proof of live API authentication.
engrt auth logout <provider>¶
Audited. What it actually does depends on whether there is a session to end:
| Provider | Behaviour |
|---|---|
gcp |
gcloud auth revoke <selected-account> --quiet; refuses native override/impersonation modes; never ADC; revocation semantics depend on native credential type |
openshift |
Genuinely ends the session — oc logout |
github |
Prints guidance. A personal access token has no server-side session; revoke it in GitHub settings and unset the variable |
kubernetes |
Prints guidance. A kubeconfig is a file, not a session |
engrt auth logout gcp # selected stored CLI account, never ADC
engrt auth logout openshift # ends the oc session
engrt auth logout github # guidance only — still audited
The distinction is deliberate: the runtime will not pretend to revoke something it cannot revoke. Admitted actions require durable intent; audit/completion failures are returned, not ignored or retried. Invalid configuration or unknown provider names fail before native work. Login/logout failures exit 1.
Enabling a provider¶
All providers except github ship enabled: false. Enable one after
logging in with the platform's own tooling:
Or from the environment:
See config.yaml and
GCP, Kubernetes, OpenShift.
Checking without side effects¶
Confirms the command line resolves, without validating anything or writing an audit record.
Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.