Credentials

A credential is a named value ZShot types for the navigator. The navigator sees the name; the value never enters the model’s context.

Wherever page text shows a typed value, as a text field or a greeting does, the navigator reads credential:NAME in its place. A screenshot shows the page as it is, so a navigator shown one after VISION sees any credential the page displays.

A credential is typed exactly as given, trailing spaces included, and must not be empty. Omit a credential to leave its field blank.

An environment variable is read before the environment is cleared for Chromium, so no helper process inherits it.

Scope

A credential is offered only on pages within the start URL’s registrable domain. --navigator-credential-origin replaces that scope, as for a login that hands off to another domain. A credential selected by several entries may be typed wherever any of them allows.

Server

A server takes navigator_credential from each request, and refuses --navigator-credential at startup. Its own credentials come from --navigator-credential-env or --navigator-credential-helper, are offered to every request, and a request cannot reuse their names.

A request’s navigator_credential_origin maps a name or name pattern to a list of globs, and scopes only the request’s own navigator_credential entries. Credentials configured at startup keep their startup origins.

Helpers

A helper’s SPEC is a command line or an https:// URL; http:// is accepted for loopback hosts. In real use the helper reads a secret store, as op read op://Vault/Site/password or security find-generic-password -w -s zshot-cli.com do.

--navigator-credential-secret sends every helper a shared secret, so a helper can confirm the request came from a ZShot you configured. Its ZSHOT_NAVIGATOR_CREDENTIAL_SECRET form is read at startup and removed from ZShot’s environment before the browser starts.

Executable Helpers

A command line is split with shell quoting rules and run without a shell. The program is a path, or a bare name found on PATH at startup. It receives the environment ZShot passes to Chromium’s own helpers: time zone, locale, HOME, PATH, TMPDIR, proxy and certificate variables, LC_* and XDG_*, minus LD_LIBRARY_PATH and DYLD_*. It also receives the names given with --navigator-credential-helper-env, and:

A --navigator-credential-secret arrives as one line on stdin; without one, stdin is /dev/null. The secret never enters a helper’s environment or the request document.

The helper prints the value on stdout as one line of at most 64 KiB; a trailing newline is dropped. A non-zero exit, empty output, or a value with a line break fails the fill. stderr is kept for the error message, so a helper must not print secrets there.

At startup ZShot checks that each program exists, is a regular file this user can execute, and is not setuid, then records its identity. A failed check exits with code 5. A program that changes on disk afterwards is not run.

HTTP Helpers

An HTTP helper receives a POST with Content-Type: application/json, and a --navigator-credential-secret as Authorization: Bearer <secret>:

{"credential": {"name": "password", "url": "https://zshot-cli.com/example_assets/zrm/"}}

and answers 200 with:

{"credential": {"value": "hunter2"}}

Any other status, a redirect, a body over 64 KiB, or a body without credential.value fails the fill. Redirects are not followed and no proxy is used.

Failures

A call is bounded by --navigator-credential-helper-timeout and never retried. An executable past the limit is killed with its process group. A failure during navigation exits with code 14 and Credential helper 'NAME' failed: <reason>; under --server the response is 502 with the failure class.

ZShot logs each call at debug before it starts, each answer at info with the helper and its duration, and each failure at error with the reason. The value never appears in a log.