Vibe passkey

2026-07-03 14:31:40 -04:00
parent e98e7bf29d
commit 678e20d402
26 changed files with 1006 additions and 15 deletions
@@ -0,0 +1,88 @@
+# 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 |