Merge pull request #149 from drudge/codex/native-passkeys

Add native passkeys and optional password sign-in

Author: drudge

CHANGELOG.md

@@ -8,6 +8,40 @@ Create a passphrase-sealed application backup before upgrading and keep
 mixed-version cluster windows short. Cross-version restore and downgrade
 compatibility are not yet a published contract.
 
+## [1.3.0]
+
+Sable 1.3.0 adds native passkeys for standalone servers and clusters, making
+passwords optional while retaining OpenID Connect and password sign-in.
+
+### Passkeys and account access
+
+- Register and manage passkeys in **Profile → Account**, below Account details.
+  Sign in without a username using your device's fingerprint, face, PIN, or a
+  security key. Passkeys require an HTTPS DNS hostname; localhost is supported
+  for development. Unsupported browsers and ordinary HTTP connections hide
+  passkey sign-in and registration controls.
+- Disable password sign-in after adding a passkey, then re-enable the existing
+  password without resetting it. Accounts without a password can set one.
+  Credential removal and password controls use Sable's confirmation dialogs.
+- Passkey public credentials replicate and are included in authorization
+  backups. Existing HTTPS identities and cluster membership determine trusted
+  origins, with a stable RP ID derived from the registrable domain. Nodes under
+  the same domain can accept the same credential after replication.
+- **Settings → Web → Enable passkeys** controls availability and defaults on.
+  Disabling preserves saved credentials and blocks passkey authentication and
+  enrollment. The settings form checks that active accounts have an enabled
+  password or a link to the enabled OIDC provider before allowing the change.
+- The [passkey guide](docs/guides/passkeys.md) covers enrollment, password
+  recovery, standalone HTTPS, reverse proxies, cluster failover, and backups.
+  Initial administrator setup still starts with a password.
+
+### Update preferences
+
+- Software Updates in Settings now includes **Include pre-releases** alongside
+  **Check for updates on sign-in**. Both wait for **Save Settings**.
+- The About page retains its release-channel control and shares the same saved,
+  node-local preference with Settings.
+
 ## [1.2.0]
 
 Sable 1.2.0 makes it easier to migrate authoritative zones from Technitium and

README.md

@@ -62,6 +62,8 @@ without shipping a Node.js runtime or a separate frontend bundle.
   console navigation
 - Database-backed users, built-in/custom RBAC, separate Web/API permissions,
   per-zone grants, revocable API tokens, and an AES-256-GCM secret vault
+- Native WebAuthn passkeys, passwordless sign-in, and per-account optional
+  passwords with [passkey management in Profile](docs/guides/passkeys.md)
 - OpenID Connect single sign-on with guided setup, PKCE, group-to-role mapping,
   just-in-time provisioning, verified-email linking, and replicated federated
   identities

config.example.toml

@@ -208,6 +208,10 @@ tls_insecure = false
 # enabled = true
 
 [security]
+# Hide passkey sign-in and enrollment, keeping saved credentials.
+# Applies locally on standalone servers and replicates in clusters.
+# Ensure every account has another sign-in method before setting true.
+passkeys_disabled = false
 enabled = true
 secure_cookies = false
 session_ttl = "12h"
@@ -222,7 +226,7 @@ secret_key_file = "data/sable.key"
 # Enabling this adds a button to the sign-in page and takes nobody's password
 # away. Moving an account to single sign-on only is a per-account switch on the
 # Administration page, and Sable keeps one administrator able to sign in with a
-# password so a problem at the provider cannot lock everyone out.
+# password or passkey so a problem at the provider cannot lock everyone out.
 [oidc]
 enabled = false
 # display_name = "Pocket ID"

docs/clustering.md

@@ -73,7 +73,8 @@ Replicated state includes:
 - Dynamic DNS settings and external provider credentials;
 - UniFi settings and controller credentials;
 - OpenID Connect settings, client secret, linked identities, and role mappings;
-- users, roles, permission grants, password hashes, API-token hashes, and token
+- passkey availability (`security.passkeys_disabled`);
+- users, roles, permission grants, password hashes, passkey public credentials, API-token hashes, and token
   revocations.
 
 Node-local state includes:
@@ -89,6 +90,11 @@ Replicas validate and activate a complete candidate before recording the new
 generation. A rejected candidate leaves the previous runtime and manifest
 active.
 
+Passkeys work across trusted node addresses under the same registrable domain.
+Credentials replicate, but browser sessions and in-progress sign-in challenges
+remain node-local. See [Sign in with passkeys](guides/passkeys.md#hostnames-and-cluster-failover)
+for naming and failover examples.
+
 ## Monitoring and node queries
 
 The Cluster page refreshes role, connectivity, applied/current generation,

docs/configuration.md

@@ -771,12 +771,33 @@ source compiler statistics, cache entries, and configuration revision.
 ```toml
 [security]
 enabled = true
+passkeys_disabled = false
 secure_cookies = false
 session_ttl = "12h"
 api_token_ttl = "3mo"
 secret_key_file = "data/sable.key"
 ```
 
+Native passkeys work on standalone servers and clusters without a separate RP ID
+or origin list. Enroll them in **Profile → Account → Passkeys** and use **Sign in
+with a passkey** on the login page. HTTPS with a DNS hostname is required;
+`http://localhost` is supported for development. Enrollment and sign-in controls
+are hidden when the browser lacks secure-context or WebAuthn support.
+
+Passwords, OIDC, and passkeys can coexist. In Profile's Password header, disable
+password sign-in after enrollment or re-enable the saved password without a
+reset. Setting a new password is a separate action that revokes browser sessions.
+
+**Settings → Web → Enable passkeys** controls availability. Click **Save
+Settings** to apply it. It defaults on, takes effect without restarting, and
+replicates across a cluster. Disabling preserves saved keys and blocks passkey
+sign-in and enrollment. The settings form requires an alternate sign-in method
+for every active account. Direct TOML edits use `security.passkeys_disabled`;
+verify alternate account access before disabling it that way.
+
+See [Sign in with passkeys](guides/passkeys.md) for hostname derivation, proxy
+configuration, failover, and recovery.
+
 Security is enabled by default. On the first start, all console routes redirect
 to `/setup` until the initial administrator is created. Passwords use Argon2id
 with a unique random salt and the OWASP minimum 19 MiB, two-pass profile. Sable
@@ -908,7 +929,7 @@ and ACME provider credentials are handled.
 sign-in page; it takes nothing away. Moving an account to SSO only is a
 per-account switch under **Administration → the user → Sign-In**, so people opt
 in one at a time. Sable refuses to leave the deployment without at least one
-administrator who can still sign in with a password, because single sign-on
+administrator who can still sign in with a password or passkey, because single sign-on
 depends on a service Sable does not run: if the provider is unreachable, its
 certificate expires, or a group claim changes shape, that administrator is how
 you get in and fix it.

docs/guides/passkeys.md

@@ -0,0 +1,167 @@
+# Sign in with passkeys
+
+Passkeys let you sign in to Sable using your device's fingerprint reader, face
+recognition, PIN, or a FIDO2 security key, without entering a username or password.
+They are enabled by default and work on **standalone servers and clusters**.
+Passwords, OpenID Connect (OIDC), and passkeys can all be available together.
+
+Sable stores the credential's public key. The private key stays with your device
+or passkey provider. Passkeys use normal Sable browser sessions and account
+permissions; they do not replace API tokens.
+
+## Before you begin
+
+- Enable console authentication and complete initial administrator setup with a
+  password. You can make that password optional after adding a passkey.
+- Access Sable through a stable HTTPS DNS hostname with a certificate trusted by
+  your browser. A standalone server uses its configured HTTPS identities; no
+  cluster or separate passkey configuration is required.
+- Use a browser and authenticator that support passkeys and device verification.
+  Sable requires a discoverable credential and verification with a fingerprint,
+  face, device PIN, or security-key PIN.
+
+Ordinary HTTP connections cannot register or use passkeys. The sign-in button,
+registration name field, and Add passkey button stay hidden when the browser
+lacks a secure context or the WebAuthn API. `http://localhost` is supported for
+local development. Access by IP address is not supported for passkey enrollment
+or sign-in, even when HTTPS is available.
+
+## Add and use a passkey
+
+1. Sign in with your password or OIDC provider.
+2. Open **Profile → Account**. The **Passkeys** card is below Account details and
+   above Password.
+3. Enter a descriptive name, such as “Personal phone,” and select **Add passkey**.
+4. Complete your browser's prompt to save the passkey.
+5. Sign out and select **Sign in with a passkey** to test it.
+
+Each account can have up to 20 passkeys. The list shows the name, domain,
+creation time, and last use. Select **Remove** and confirm in Sable's dialog to
+remove a saved credential. Removing it from Sable prevents it from being used
+for that account; it does not delete the entry from your device's passkey manager.
+
+On a standalone server, manage passkeys directly on that server. In a cluster,
+register and remove them on the primary. Replicas can accept passkey sign-ins
+after receiving the credential through replication.
+
+## Disable or re-enable password sign-in
+
+After adding and testing a passkey, select **Disable password sign-in** on the
+right side of the **Password** card header and confirm. Your existing password
+is retained but cannot be used to sign in. Linked OIDC accounts remain available.
+
+To restore the same password, sign in with a passkey or OIDC and select
+**Enable password sign-in** in the Password header. Confirm the change; no
+password reset is required.
+
+You can instead fill in New Password and Confirm New Password and select
+**Set new password and enable sign-in**. Setting a new password enables password
+sign-in and signs out existing browser sessions. An account that never had a
+password must set one before it can use password sign-in.
+
+First-run administrator setup and locally created accounts start with a
+password. Accounts provisioned through OIDC can add passkeys without ever
+setting a password.
+
+Keep a backup passkey or a tested recovery administrator before disabling your
+password. Sable refuses to remove your final passkey while password sign-in is
+disabled. When disabling a password, it also requires an active administrator
+with password or passkey access so recovery does not depend entirely on an
+external identity provider. If you lose access to your authenticators, another
+administrator can reset your password and enable password sign-in through
+Administration.
+
+## Administrator setting
+
+Open **Settings → Web → Passkeys**, change **Enable passkeys**, then select
+**Save Settings**. Changing the switch alone does not save it.
+
+Turning it off hides passkey sign-in and enrollment and rejects both new and
+in-progress passkey ceremonies. Saved credentials remain in place for later
+re-enabling, and they can still be removed from Profile. Password and OIDC
+sign-in continue to work when enabled for the account.
+
+The settings form refuses to disable passkeys if an active account has neither
+an enabled password nor a link to the currently enabled OIDC issuer. A link to
+a different or disabled provider does not count as an alternative.
+
+The setting takes effect without restarting. On a standalone server it applies
+to that server; in a cluster it replicates to the other nodes. The configuration
+is:
+
+```toml
+[security]
+enabled = true
+passkeys_disabled = false
+```
+
+Set `passkeys_disabled = true` to disable the feature. Before editing TOML
+directly, ensure every active account has another enabled sign-in method; the
+account check described above is performed by the settings form.
+
+## Hostnames and cluster failover
+
+Sable derives the relying party ID (RP ID) from the registrable parent domain of
+the hostname you access, using the Public Suffix List. No manual RP ID or
+separate allowed-origins list is needed.
+
+| Console address | RP ID |
+| --- | --- |
+| `https://dns.example.com` | `example.com` |
+| `https://ns1.penree.net` | `penree.net` |
+| `https://ns2.penree.net` | `penree.net` |
+| `http://localhost:5391` | `localhost` |
+
+For a cluster named `ns.penree.net` with nodes `ns1.penree.net` and
+`ns2.penree.net`, the RP ID is `penree.net`. The cluster domain itself does not
+set the RP ID. Sable handles public suffixes such as `co.uk` and private hosting
+suffixes when deriving the registrable domain.
+
+Trusted origins come from existing configuration:
+
+- Advertised HTTPS URLs in the cluster registry and the local advertised URL.
+- The HTTPS console's listener hostname and explicit certificate DNS names.
+- `encrypted_dns.acme.domains` for ACME, or the explicit names in a manually
+  installed or generated certificate.
+
+Sable recognizes the configured HTTPS listener port and standard HTTPS port
+443. Wildcard certificate names do not authorize arbitrary sibling websites.
+Adding or removing a configured identity changes the trusted origins without
+maintaining another passkey-specific list.
+
+After replication, a credential registered on `ns1.penree.net` can sign in on
+`ns2.penree.net` when both addresses are trusted. Joining a cluster, promoting a
+replica, or removing the old primary does not change the RP ID. Browser sessions
+and in-progress authentication challenges are node-local: begin a new sign-in
+on the replacement node if failover interrupts a login.
+
+Nodes under unrelated registrable domains cannot share a passkey with this
+default. Use names under the same domain or retain password/OIDC access. A
+credential's RP ID cannot be changed after enrollment; moving to a different
+domain requires a new passkey.
+
+## Reverse proxies and backups
+
+A reverse proxy must preserve the original Host and send
+`X-Forwarded-Proto: https` to Sable. The browser's origin must match that address.
+When no explicit HTTPS identities are configured, such as an HTTP-only backend
+behind a proxy, sign-in falls back to the exact verified enrollment origin.
+
+Authorization backups and cluster snapshots include public credentials and user
+handles. Restoring them preserves ownership but cannot change their domain
+binding or recover a lost private key. The restored server must be reachable at
+an authorized HTTPS address under the same domain. Replication preserves newer
+local signature counters when applying older credential state.
+
+## Troubleshooting
+
+- **No passkey button:** check the administrator setting, browser support, and
+  whether you opened an HTTPS hostname or localhost.
+- **Hostname rejected:** use a DNS name present in the existing HTTPS identities.
+  Check the exact hostname and port, certificate names, and proxy headers.
+- **Passkey missing on another node:** confirm replication has caught up and the
+  node uses a trusted address under the same registrable domain.
+- **Canceled or timed-out prompt:** retry the sign-in or registration action.
+- **Demo passkeys do not work:** the demo's MacBook and iPhone entries are display
+  fixtures. Their private keys are discarded; keep the demo password enabled or
+  register your own passkey using localhost.

docs/guides/sso.md

@@ -1,10 +1,12 @@
 # Connect single sign-on
 
 Let operators use an existing OpenID Connect identity provider while keeping a local recovery account. Enabling SSO adds a sign-in choice; it does not automatically remove local passwords.
+[Native Sable passkeys](passkeys.md) can be used alongside OIDC and passwords,
+including by OIDC-provisioned accounts that have never set a local password.
 
 ## Before you begin
 
-Prepare an OIDC client at your provider, a stable HTTPS console URL, and an administrator who can still sign in with a password. Decide whether unknown users may be provisioned and what, if anything, they receive by default.
+Prepare an OIDC client at your provider, a stable HTTPS console URL, and an administrator who can still sign in with a password or passkey. Decide whether unknown users may be provisioned and what, if anything, they receive by default.
 
 Managing the provider, account provisioning, and role mappings requires both `settings.write` and `users.write`. Use an administrator or a role with both permissions.
 
@@ -30,7 +32,7 @@ Turn verified-email linking off if your provider cannot reliably verify addresse
 
 Use a second browser session to test a non-administrator user and an intended administrator. Confirm their effective permissions, group mapping, and logout behavior. Keep the local administrator session open until these checks pass.
 
-Switch an account to SSO-only under its **Sign-In** settings only after testing. Sable preserves a password-capable administrator because it cannot repair an unavailable identity provider for you.
+Switch an account to SSO-only under its **Sign-In** settings only after testing. Sable requires an administrator with password or passkey sign-in because it cannot repair an unavailable identity provider for you.
 
 ## Troubleshoot safely
 

docs/index.md

@@ -31,7 +31,7 @@ These guides cover Sable 1.0.0. [Download the release](https://github.com/drudge
 ## Secure it and keep it running
 
 - [Enable encrypted DNS](guides/encrypted-dns.md) and [manage certificates](guides/certificates.md).
-- [Grant people the right permissions](guides/access-control.md) or [connect single sign-on](guides/sso.md).
+- [Grant people the right permissions](guides/access-control.md), [use passkeys](guides/passkeys.md), or [connect single sign-on](guides/sso.md).
 - [Back up and rehearse recovery](backup.md) before your first production upgrade.
 - [Build a resilient cluster](clustering.md) and [update nodes safely](guides/updates.md).
 - [Keep a public name pointed at your connection](guides/dynamic-dns.md), [sync UniFi device names](guides/unifi.md), or [add a Glance widget](guides/glance.md).

go.mod

@@ -7,6 +7,8 @@ toolchain go1.27.1
 require (
 	github.com/a-h/templ v0.3.1020
 	github.com/fsnotify/fsnotify v1.10.1
+	github.com/fxamacker/cbor/v2 v2.9.3
+	github.com/go-webauthn/webauthn v0.18.1
 	github.com/jackc/pgx/v5 v5.11.0
 	github.com/miekg/dns v1.1.73
 	github.com/pelletier/go-toml/v2 v2.4.3
@@ -27,6 +29,10 @@ require (
 	github.com/cli/browser v1.3.0 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/fatih/color v1.19.0 // indirect
+	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
+	github.com/go-webauthn/x v0.3.1 // indirect
+	github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
+	github.com/google/go-tpm v0.9.8 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
@@ -36,7 +42,10 @@ require (
 	github.com/mattn/go-isatty v0.0.24 // indirect
 	github.com/natefinch/atomic v1.0.1 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/philhofer/fwd v1.2.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/tinylib/msgp v1.6.4 // indirect
+	github.com/x448/float16 v0.8.4 // indirect
 	golang.org/x/sync v0.23.0 // indirect
 	golang.org/x/telemetry v0.0.0-20260908163034-4bcc4b2ee518 // indirect
 	golang.org/x/text v0.42.0 // indirect