docs: document passkey sign-in and ermite web passkey
- commit
- 72337111b3ca325e82ffba20704debe48d11e761
- author
- brice · · 2026-10-12 15:16 UTC
- parent
- 21bc4dd
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
2 files · +13 -1
M README.md +9 -1
| @@ -44,6 +44,7 @@ ermite mr comment <repo> <n> -m … [--path … --line … --side old|new] | res | |||
| 44 | 44 | ermite mr merge <repo> <n> --head <id> [--squash] [--delete-branch] | close <repo> <n> | |
| 45 | 45 | ermite web login # prints a one-time sign-in link (60 s) | |
| 46 | 46 | ermite web logout --all # signs every browser out | |
| 47 | + | ermite web passkey list | remove <id> # the owner's passkeys; removing one signs every browser out | |
| 47 | 48 | ermite signing-key show # public key and allowed_signers line of squash commits | |
| 48 | 49 | ermite version # client and server, warns about missing server features | |
| 49 | 50 | ermite watch [repo] [--json] # follows events, reconnects and resumes | |
| @@ -68,7 +69,14 @@ A merge request proposes a branch for its target (the default branch unless set) | |||
| 68 | 69 | ||
| 69 | 70 | ## Web sign-in | |
| 70 | 71 | ||
| 71 | - | `ermite web login`, run with the admin token or a token with every scope, prints a link that works once within 60 seconds. Opening it and confirming sets a session cookie for 12 hours (never longer than the token that asked for the link). It needs `https` in `ERMITE_PUBLIC_URL` (except on localhost). Browser writes require the session and an `Origin` equal to `ERMITE_PUBLIC_URL`. `ermite web logout --all`, or revoking a token with every scope, ends every session. | |
| 72 | + | Two ways in, both for the owner, both giving the same session cookie for 12 hours. Neither works over plain `http` except on localhost: the cookie is `Secure`. | |
| 73 | + | ||
| 74 | + | - **Passkey** (a phone, a laptop, a security key): open `/-/login` and press "Sign in with a passkey". Nothing to type, no terminal. A passkey is added once from `/-/passkeys` while signed in. | |
| 75 | + | - **Link**: `ermite web login`, run with the admin token or a token with every scope, prints a link that works once within 60 seconds. Opening it and confirming signs the browser in (never longer than the token that asked for the link). It is also how to sign in the first time, before any passkey exists. | |
| 76 | + | ||
| 77 | + | Passkeys need `ERMITE_PUBLIC_URL` to be `https` (or `http://localhost`) with a **host name, not an IP address**: WebAuthn ties a passkey to that name, and a passkey registered for one name does not work on another. On `http://127.0.0.1:…` the server starts without passkeys (the log says `passkeys disabled`, the routes and links are absent, `ermite version` does not list `passkeys`). Up to 20 passkeys can be registered; each asks for user verification (a fingerprint, a face or a PIN), and the server stores only the public key. A security key that reports a signature counter is checked for cloning; synced passkeys (iCloud, Google, a password manager) report none, so they are not. | |
| 78 | + | ||
| 79 | + | `ermite web passkey list` shows them, `ermite web passkey remove <id>` removes one. Removing a passkey, `ermite web logout --all`, or revoking a token with every scope ends every session, on every device. Browser writes require the session and an `Origin` equal to `ERMITE_PUBLIC_URL`. If you lose every device, `ermite web login` still works from a terminal. | |
| 72 | 80 | ||
| 73 | 81 | The server keeps its runtime files in `$ERMITE_DATA_DIR/run/` (the hook socket and scripts that git calls on each push); the hook socket path must stay under about 100 bytes. | |
| 74 | 82 | ||
| @@ -44,6 +44,7 @@ ermite mr comment <repo> <n> -m … [--path … --line … --side old|new] | res | |||||
| 44 | ermite mr merge <repo> <n> --head <id> [--squash] [--delete-branch] | close <repo> <n> | 44 | ermite mr merge <repo> <n> --head <id> [--squash] [--delete-branch] | close <repo> <n> | ||
| 45 | ermite web login # prints a one-time sign-in link (60 s) | 45 | ermite web login # prints a one-time sign-in link (60 s) | ||
| 46 | ermite web logout --all # signs every browser out | 46 | ermite web logout --all # signs every browser out | ||
| 47 | + | ermite web passkey list | remove <id> # the owner's passkeys; removing one signs every browser out | |||
| 47 | ermite signing-key show # public key and allowed_signers line of squash commits | 48 | ermite signing-key show # public key and allowed_signers line of squash commits | ||
| 48 | ermite version # client and server, warns about missing server features | 49 | ermite version # client and server, warns about missing server features | ||
| 49 | ermite watch [repo] [--json] # follows events, reconnects and resumes | 50 | ermite watch [repo] [--json] # follows events, reconnects and resumes | ||
| @@ -68,7 +69,14 @@ A merge request proposes a branch for its target (the default branch unless set) | |||||
| 68 | 69 | ||||
| 69 | ## Web sign-in | 70 | ## Web sign-in | ||
| 70 | 71 | ||||
| 71 | - | `ermite web login`, run with the admin token or a token with every scope, prints a link that works once within 60 seconds. Opening it and confirming sets a session cookie for 12 hours (never longer than the token that asked for the link). It needs `https` in `ERMITE_PUBLIC_URL` (except on localhost). Browser writes require the session and an `Origin` equal to `ERMITE_PUBLIC_URL`. `ermite web logout --all`, or revoking a token with every scope, ends every session. | 72 | + | Two ways in, both for the owner, both giving the same session cookie for 12 hours. Neither works over plain `http` except on localhost: the cookie is `Secure`. |
| 73 | + | ||||
| 74 | + | - **Passkey** (a phone, a laptop, a security key): open `/-/login` and press "Sign in with a passkey". Nothing to type, no terminal. A passkey is added once from `/-/passkeys` while signed in. | |||
| 75 | + | - **Link**: `ermite web login`, run with the admin token or a token with every scope, prints a link that works once within 60 seconds. Opening it and confirming signs the browser in (never longer than the token that asked for the link). It is also how to sign in the first time, before any passkey exists. | |||
| 76 | + | ||||
| 77 | + | Passkeys need `ERMITE_PUBLIC_URL` to be `https` (or `http://localhost`) with a **host name, not an IP address**: WebAuthn ties a passkey to that name, and a passkey registered for one name does not work on another. On `http://127.0.0.1:…` the server starts without passkeys (the log says `passkeys disabled`, the routes and links are absent, `ermite version` does not list `passkeys`). Up to 20 passkeys can be registered; each asks for user verification (a fingerprint, a face or a PIN), and the server stores only the public key. A security key that reports a signature counter is checked for cloning; synced passkeys (iCloud, Google, a password manager) report none, so they are not. | |||
| 78 | + | ||||
| 79 | + | `ermite web passkey list` shows them, `ermite web passkey remove <id>` removes one. Removing a passkey, `ermite web logout --all`, or revoking a token with every scope ends every session, on every device. Browser writes require the session and an `Origin` equal to `ERMITE_PUBLIC_URL`. If you lose every device, `ermite web login` still works from a terminal. | |||
| 72 | 80 | ||||
| 73 | The server keeps its runtime files in `$ERMITE_DATA_DIR/run/` (the hook socket and scripts that git calls on each push); the hook socket path must stay under about 100 bytes. | 81 | The server keeps its runtime files in `$ERMITE_DATA_DIR/run/` (the hook socket and scripts that git calls on each push); the hook socket path must stay under about 100 bytes. | ||
| 74 | 82 | ||||
M skills/ermite/CLI.md +4 -0
| @@ -81,3 +81,7 @@ Merge request JSON: `repo`, `number`, `title`, `description`, `source_branch`, ` | |||
| 81 | 81 | | `signing-key show` | public key and `allowed_signers` line to check squash commits with `git verify-commit` | | |
| 82 | 82 | | `web login [--json]` | one-time sign-in link (about 60 s); needs the admin token or a token with every scope and no repository list; the link is a secret | | |
| 83 | 83 | | `web logout --all` | signs every browser out | | |
| 84 | + | | `web passkey list [--json]` | the owner's passkeys (`id`, `name`, `created_at`, `last_used_at`, `synced`); same rights as `web login`; fails with "passkeys are not available on this server" when the public URL is not https with a host name | | |
| 85 | + | | `web passkey remove <id>` | removes a passkey and signs every browser out; the id comes from `list` | | |
| 86 | + | ||
| 87 | + | Adding a passkey is a browser action (`/-/passkeys` once signed in); agents do not use passkeys. | |
| @@ -81,3 +81,7 @@ Merge request JSON: `repo`, `number`, `title`, `description`, `source_branch`, ` | |||||
| 81 | | `signing-key show` | public key and `allowed_signers` line to check squash commits with `git verify-commit` | | 81 | | `signing-key show` | public key and `allowed_signers` line to check squash commits with `git verify-commit` | | ||
| 82 | | `web login [--json]` | one-time sign-in link (about 60 s); needs the admin token or a token with every scope and no repository list; the link is a secret | | 82 | | `web login [--json]` | one-time sign-in link (about 60 s); needs the admin token or a token with every scope and no repository list; the link is a secret | | ||
| 83 | | `web logout --all` | signs every browser out | | 83 | | `web logout --all` | signs every browser out | | ||
| 84 | + | | `web passkey list [--json]` | the owner's passkeys (`id`, `name`, `created_at`, `last_used_at`, `synced`); same rights as `web login`; fails with "passkeys are not available on this server" when the public URL is not https with a host name | | |||
| 85 | + | | `web passkey remove <id>` | removes a passkey and signs every browser out; the id comes from `list` | | |||
| 86 | + | ||||
| 87 | + | Adding a passkey is a browser action (`/-/passkeys` once signed in); agents do not use passkeys. | |||