Skip to content

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.

engrt auth status
engrt auth login <provider>
engrt auth logout <provider>

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):

github     ✗ auth_unavailable: github authentication: no ENGRT session; use explicit auth login github

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.

engrt auth status

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.

engrt auth login github
engrt auth login gcp
engrt auth login kubernetes
engrt auth login openshift

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:

gcloud auth login
oc login --token=<token> --server=<url>
kubectl config use-context <name>

Per provider

export ENGRT_GITHUB_TOKEN=ghp_your_personal_access_token
engrt auth login github

Validated against GET <base_url>/user.

gcloud auth login
engrt auth login gcp

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.

kubectl config use-context <name>
engrt auth login kubernetes

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.

oc login --token=<token> --server=<server>
engrt auth login openshift

Validated via oc whoami.


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:

authentication:
  gcp:
    enabled: true
    binary: gcloud

Or from the environment:

export ENGRT_AUTHENTICATION_GCP_ENABLED=true

See config.yaml and GCP, Kubernetes, OpenShift.


Checking without side effects

engrt resolve auth login github

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.