Authentication
What the web app does (verified in server/access.ts)
- People are listed in the server's
ACCESS_USERS. There is no password and no self-service account. - A device is enrolled with a single-use setup link (
npm run access:invite invite <person>on the node), which registers a WebAuthn passkey (discoverable, user verification required, relying partyvquant.spboucher.ai). - Sign-in is a passkey assertion. The session is a cookie
vq_access = <id>.<HMAC(ACCESS_KEY, id)>, 400 days, identical for every device of a person: it cannot be listed or revoked per device. - The passkey routes require
Origin: https://vquant.spboucher.ai.
Why the cookie is not reused
A native app has no page origin, and the cookie is a bearer value that is the same on every device and cannot be
revoked individually. Reusing it would have meant forging the Origin header and giving up device revocation.
The native bridge (server/native.ts, backend v5.8.0)
Same people, same passkeys, same relying party — nothing new to create for a person who already uses the web app.
GET /.well-known/apple-app-site-association→{"webcredentials":{"apps":["3YM54G49SN.ai.spboucher.vquant"]}}. With the app'swebcredentials:vquant.spboucher.aiassociated domain, macOS lets the app use the domain's passkeys (including those created in Safari and synced by iCloud Keychain).POST /api/native/login/options→ challenge.ASAuthorizationPlatformPublicKeyCredentialProviderperforms the assertion (Touch ID).POST /api/native/login/verifyverifies it exactly as the web gate does (@simplewebauthn/server, expected originhttps://vquant.spboucher.ai, user verification required, counter updated) and answers with a device tokenvqn_…(256 random bits).- The server stores only the SHA-256 of the token (
vq_devices: person, label, platform, passkey used, created, last used, last fresh check, revoked). Unused for 90 days it expires; revocation is immediate. - Enrolment of a Mac that has no passkey:
POST /api/native/register/options|verifywith a setup-link token — the web app's own invitations, claimed atomically with the passkey insert. - Sensitive operations (revoking another device, deleting a passkey) need a fresh passkey check
(
/api/native/reauth/*, valid 5 minutes); the client performs it once and retries. The last passkey of an account cannot be deleted. - Native routes require
X-VQ-Client: vquant-macos/<version>and refuse any request carrying anOriginheader; they are rate-limited per address.
The web gate accepts either the cookie or a valid device token, so every existing route enforces the same per-person authorisation for the Mac as for the browser.
On the Mac
- The token is the only credential stored: Keychain generic password,
WhenUnlockedThisDeviceOnly, not synced. Passkey private keys stay in the system authenticator; biometric data never reaches the app or the server. - Touch ID app lock (Settings › Touch ID & Passkeys): the token item is stored behind
SecAccessControl(.userPresence); at launch or after ⌃⌘L it is released only afterLAContextsucceeds. Touch ID unlocks the credential; the server still authenticates every request. - Sign-out revokes the session on the server, then clears the Keychain and the cache. A 401 from the server (revoked elsewhere, expired) signs the Mac out and erases the cache. A network failure never signs out.
- A different person signing in erases the previous person's cache first.
- Release builds only: the Associated Domains entitlement needs the Developer ID provisioning profile, and macOS resolves the association per application identifier, so Debug builds use another bundle id and cannot use system passkeys. Development and tests use a software authenticator against the backend test copy.
Verified
- Integration tests (real server, software authenticator): locked without a session; unknown passkey refused; assertion bound to another origin refused; enrolment with a setup link, link then spent; second device signs in; revoke it → it is locked out at its next request; own session cannot be revoked through the other-device route; sign-out kills the token server-side; the passkey signs in again.
- Production, 2026-11-18: the owner signed in on the notarized app with his existing passkey and Touch ID
(server log:
[native] signed in user=simon device="… · VQuant macOS 1.0.0"). Apple's CDN serves the association file (nscurl https://app-site-association.cdn-apple.com/a/v1/vquant.spboucher.ai→ 200). - Not verified: native enrolment with Touch ID (setup link), the Touch ID app lock, passkey deletion.
2.0.0
The protocol is unchanged. What changed around it:
- The client header is
vquant-macos/2.0.0; device labels read "… · VQuant macOS 2.0.0". - The shared package VQuantKit never sees the token: its requests are built by the app's
APIClient(MacVQTransport), so every/api/v2call carries the same Bearer device token and noOrigin. A 401 on any of them runs the same sign-out path. - Sign-out and a session ended by the server also erase the sync replica, its write queue and conflict records; lock stops the sync stream and leaves the sealed replica on disk.
- Verified for 2.0.0 (integration suite against the backend 6 test copy on 5058, software authenticator): locked without a session; unknown passkey refused; wrong origin refused; enrolment with a setup link, link then spent; second device signs in; reauth-gated revocation of that device; own session cannot be revoked through the other-device route; sign-out kills the token; the passkey signs in again.
- Still not verified: every Touch ID ceremony (sign-in on the signed 2.0.0 build, native enrolment, the app lock, revocation and passkey deletion from the Settings panes).