# WebAuthn / Passkeys (v0.13)

## Overview

The bundled Dex uses a custom WebAuthn connector (`orca-webauthn-connector`,
REQ-148) for password-free authentication. Passkeys are public-key
credentials — the private key never leaves the authenticator (TPM /
security key / phone Secure Enclave). This directly satisfies R-021
(no Orca-issued credentials): the authenticator proves possession of
the private key without ever exposing it.

The WebAuthn connector ships as part of the v0.12 milestone (P05) and
is operationally wired in v0.13 (P04: registration requires auth; P06:
real Dex deployment).

## Registration

```bash
orca auth register [--no-browser]
```

Opens the browser to the Dex WebAuthn registration page at
`https://<cluster>/orca/webauthn/register`. The operator authenticates
via an existing session or admin bootstrap token, then performs the
WebAuthn ceremony (biometric or security key). After the ceremony,
Dex maps the credential ID to an OIDC `sub`.

- **`--no-browser`**: print the registration URL instead of opening a
  browser (useful for headless operators or remote SSH sessions — copy
  the URL into a local browser).

Credentials are stored at `ClusterDir()/webauthn-credentials.db`
(mode 0600, public keys only — private keys never leave the
authenticator and are never stored by orca).

**Example**:
```bash
# Interactive (opens browser)
orca auth register

# Headless / remote SSH (print URL)
orca auth register --no-browser
# → https://orca.local/orca/webauthn/register
```

## RP ID

The relying-party ID is the cluster's Traefik-served domain, set via
`--rp-id` on `orca auth init-idp` (C-38). The RP ID **must** match the
cluster's Traefik domain — WebAuthn enforces that the RP ID is a
registrable domain suffix of the current origin.

HTTPS secure context is provided by Traefik (step-ca cert, R-017).
WebAuthn requires a secure context (HTTPS or localhost); the step-ca
cert behind Traefik satisfies this.

## Bootstrap Sequence

1. `orca init` bootstraps the cluster CA (step-ca, mTLS-only).
2. `orca auth init-idp --rp-id <cluster-domain>` deploys Dex behind
   Traefik (step-ca cert) with the WebAuthn connector configured.
3. First operator authenticates via an existing session or admin
   bootstrap token, then registers a passkey:

   ```bash
   orca auth register
   ```

4. Subsequent operators use WebAuthn login (`orca auth login` opens
   the browser to the Dex login page; the WebAuthn ceremony is one of
   the available upstreams).

## Health Check

```bash
orca doctor oidc
```

Verifies the bundled Dex OIDC provider is running and the
`/.well-known/openid-configuration` endpoint responds. Run after
`orca auth init-idp` or after a Dex config change.

## Security properties

- **No passwords**: WebAuthn is password-free. No password is ever
  sent to or stored by orca (R-021).
- **Phishing-resistant**: the WebAuthn protocol cryptographically binds
  the ceremony to the RP ID, defeating credential phishing.
- **Private key never leaves the authenticator**: orca stores only
  public keys.
- **Secure context required**: HTTPS via step-ca / Traefik (C-38).

## See also

- [docs/oidc.md](oidc.md) — OIDC configuration (Dex quickstart, BYO IdP)
- [docs/security-runbook.md](security-runbook.md) — security runbook
- [docs/cli.md](cli.md#orca-auth) — `orca auth` CLI reference