go-authcrunch: Skill for Codex

Authentication Client

Ownership

pkg/authclient is the importable consumer of pkg/apiauth JSON login types. It owns Config, Client, Options, PromptFunc, Credentials, and FileTokenStore. It sends only POST <base_url>/login; authentication does not require enable admin api. Keep server handlers in pkg/authn and management operations in cmd/authdbctl.

Read references/integration.md when embedding the client, choosing credential paths, or changing the CLI adapter. Public contracts also live beside the exported Go declarations and in pkg/authclient/doc.go.

The reusable package does not discover config, select application directories, read terminal input, log credentials, or dispatch CLI commands. Do not add urfave/cli, term, or application-name defaults to it. Applications own prompt presentation, config loading, user-agent identity, and credential persistence.

Protocol Invariants

• NewClient validates a copy of configuration. Authenticate(ctx) starts a fresh exchange, returns credentials, and has no token-file side effects.
• Keep each response newly decoded. Missing sandbox fields must not inherit previous response values. Continue only with a sandbox ID, sandbox secret, and next challenge; success requires a nonempty usable access token.
• Keep the ten-request bound, response-size limit, context propagation, and refusal to follow redirects, including with an injected HTTP client.
• Configured password/TOTP values avoid input prompts. PromptMFA returns totp or webauthn; the CLI translates numbered choices. Without a prompt, a configured TOTP secret can answer a combined MFA challenge directly.
• APIKey selects a separate, single-request login with Realm; reject mixed username/password/TOTP configuration. Send the key only in the JSON body, never in the URL. Do not fall back to challenges or prompt after key rejection. The portal derives the identity using its existing proxy API key verifier. Keys are independent credentials, including for accounts enrolled in MFA. They do not satisfy password/TOTP/WebAuthn checkpoints; configured challenge requirements or an explicit saved flow preference can therefore deny key login. Key login issues an access token only, sets no cookies, and cannot create a refresh family. refresh_transport: body is rejected for this mode.
• TOTP uses raw secret bytes and SHA-1, matching identity.MfaToken and existing authdbctl config. Do not silently interpret the secret as base32. Defaults are six digits and thirty seconds; accepted digits match the portal's four-to-eight range and the period must be positive.
• U2F/WebAuthn assertion handling remains unsupported. Return ErrUnsupportedChallenge without echoing server challenge payloads. Missing input uses ErrInputRequired; HTTP failures expose a status via HTTPError.
• Each login returns only its new credentials. Never merge an old refresh token into a fresh result. Token syntax checks are not JWT verification.