# Passkey Authentication — Chrono CCG

## How it works

The app uses passkeys (WebAuthn/FIDO2) as the only sign-in method. There are no passwords, usernames, or email addresses. Your fingerprint (or device PIN) is the key.

Authentication has two phases:

1. **Enrollment** — register a passkey once on a device/authenticator
2. **Sign in** — use that passkey to authenticate on subsequent visits

---

## First-time setup (enrollment)

1. Navigate to `http://localhost:5256/login` (or whatever the server URL is)
2. You should see: **"No passkey enrolled yet. Register your device to get started."**
3. Click **Enroll Passkey**
4. Your browser or password manager (1Password, etc.) will prompt you to create a passkey
5. Authenticate with your fingerprint, Face ID, or device PIN
6. You'll be redirected to the app — you are now signed in

The credential is stored in the database. From this point on, only registered passkeys can authenticate.

---

## Signing in after enrollment

1. Navigate to the app — if not signed in, you'll be redirected to `/login`
2. You should see: **"Use your registered passkey to sign in."**
3. Click **Sign in with Passkey**
4. Authenticate with your fingerprint, Face ID, or device PIN
5. You'll be redirected to the app

---

## Using 1Password

1Password supports passkeys natively. When prompted by the browser:

1. Click **Enroll Passkey** or **Sign in with Passkey**
2. A browser dialog will appear asking how to create/use the passkey
3. Select **1Password** from the list of options
4. 1Password will prompt for your fingerprint (Touch ID / Windows Hello)
5. Done

**Important:** The site must be accessed from its configured origin (e.g., `http://localhost:5256`). 1Password associates passkeys with the domain/origin, so using a different address (e.g., a different port or IP) won't find the saved passkey.

---

## Enrolling additional passkeys

Once signed in, you can enroll another passkey (e.g., a hardware key, a second device) by navigating to `/login` while already authenticated. The Enroll Passkey button will appear and allow registration of additional credentials.

---

## Signing out

There is no sign-out UI yet. To sign out manually, clear your browser cookies for the site. The session cookie is named `.AspNetCore.Cookies`.

---

## Configuration

The Fido2 relying party settings live in `appsettings.Development.json`:

```json
"Fido2": {
  "ServerDomain": "localhost",
  "ServerName": "Chrono CCG",
  "Origins": [ "http://localhost:5256", "https://localhost:7266" ]
}
```

If the server moves to a different host or port, update `Origins` to match the full scheme+host+port the browser uses to access it. `ServerDomain` must be the effective domain (no port, no scheme).

---

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `Response.Transports field is required` | Old version of `passkey.js` | Redeploy — fixed in current version |
| `Relying party ID does not match` | Origin mismatch | Ensure the URL in the browser matches an entry in `Fido2:Origins` |
| `Session expired. Please retry enrollment` | Took too long between steps | Start over from the login page |
| `Credential not recognized` | Passkey was created on a different server/domain, or the DB was wiped | Re-enroll |
| Button does nothing | Blazor circuit not connected yet | Wait a moment after page load and try again |
| 1Password doesn't offer to save | Browser extension not active | Ensure 1Password browser extension is installed and enabled |