Ansible/scripts/addons/webgui/docs/CREDENTIALS.md

> The behaviors below are retained from2.1.0rc2. Current candidate2.1.0rc9 targets Core3.3.0rc8/schema5 and adds reports/journal described in REPORTS.md and JOURNAL.md. Credential, read-only inventory and OS-permission boundaries here remain unchanged; old version/no-migration statements describe the earlier slice.

# One-run credentials through core API 1.0

Core 3.3.0rc8 is authoritative. WebGUI 2.1 does not decrypt Vault or read/export/copy keys.
Use native inventory or explicit customer-key loading in New run. Existing usernames,
Vault variables and host/group precedence are core/Ansible behavior.

Custom forced username/password override is NOT exposed by core and was removed
from this adapter. A supplied connection_password, when the catalog requests it, is
a native default and may be overridden by inventory. It is not password-only testing.
Become-password UI, key uploads, cross-job password caching and raw task output are
not implemented. Terminal features are not automatically API features.

## Where to enter a password

Submit the reviewed job first. With approval disabled it queues directly; otherwise
an independent enabled administrator approves it. The running queue worker reserves
a slot after local core readiness. Job detail then offers Unlock this run. With JavaScript and native dialog support this opens an in-page modal; its link remains an authenticated full-page fallback. Overview and Jobs also surface your eligible reservations in Needs your attention.
Only the requesting account may use this form. All requested fields derive from
PreparedRun. A present customer Vault is conservatively required even when the
catalog's require_vault flag is false. An encrypted customer key can use an explicit
key passphrase or Core's literal vault_linux_ssh_key_passphrase lookup. The grouped Use customer Vault / Enter separately choice appears only for that alternative requirement with a Vault source. A separately required key passphrase is never made optional.

A reservation without secrets lasts5minutes. After submission, hand-off/preparation/
start must fit60seconds; execution has the separate bounded job timeout. An expired
or failed attempt does not retain credentials for the next attempt. Scheduled jobs
collect secrets only when their time/window/approval and worker are ready.

## Transport and processing

Existing verified HTTPS to NPM/backend and loopback final hop are assumed configured
by the operator. Dedicated POST bodies, CSRF/origin/session authorization and8KiB
body limit remain. Passwords are literal, max2048 UTF8 bytes each, no CR/LF/NUL. No
client-side hash substitution. Browser fields clear on navigation and never enter
HTMX history/localStorage. Raw body/error logging remains prohibited.

The web identity sends private bounded local frames to its worker, then to the
executor. The executor starts aimctl with a separate inherited secret pipe FD, not
stdin request JSON, argv, environment or a password file. Core owns its provider,
key agent and native credential helpers. WebGUI does not reinterpret Vault values.

Python release of references is not guaranteed RAM erasure. Review swap/dumps,
proxy request buffering and access to the service accounts. A compromised authorized
web process may exercise the local core client authority; this is not tenant isolation.
No automatic data/file-permission repair or credential fallback is performed.

## Qualification

`aim-web credential-check` now means public capability/authorized metadata checking.
It does not test decryption or remote auth and requires no pytest in production.
`core-check --customer ... --playbook ... --host ... --key-mode customer` additionally
runs documented local readiness. Real SSH/WinRM acceptance remains an operator gate.
Use the included disposable test instructions for API integration; fake native
fixtures do not certify real Ansible or controller systemd permissions.


## Dialog lifecycle and recovery

The dialog loads only after an explicit user action. Its form lives outside status/attention polling so typing is not discarded by an HTMX replacement. It shows the frozen customer/playbook/mode and target count. Show/Hide never changes what is submitted, and pasting is not blocked. Escape/Close/Not now clear fields, including visible-password inputs, and return focus without canceling the job. Backdrop taps do not dismiss it. A small visual viewport constrains the dialog's internal scroll area rather than growing the page.

Only required/supported Core fields are rendered. For the Vault/key alternative, the default sends just the Vault password; Enter separately adds a required key-passphrase field. Switching back clears that field. No source-radio name or extra scope/identity field is sent to the API. A plain HTML form with JavaScript unavailable exposes the optional separate field with its explanation and does not submit disabled source controls.

The countdown uses the server deadline, not a new five-minute timer on each opening. Polling does not renew it. Submission clears live form values and disables repeat clicks. A 202 accepted response means only that the existing worker claimed the handoff. Core validation and remote authentication happen later. A lost acknowledgement must not cause automatic POST retry: the client locks the form and polls owner-only status. Worker single-claim/session/scope checks remain authoritative across tabs.

The canonical POST route is `/api/v2/runs/{id}/credentials`; the existing `/api/v2/jobs/{id}/credentials` is kept as an alias. Both use the same five-attempts-per-minute requester throttle and existing private worker socket. `GET /api/v2/runs/{id}/credential-status` is non-secret status only. It never reports a password as correct, requests new work or extends the reservation.