SPB Git

Repository Public

AUTHENTICATION.md 5.9 KB

# 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 party vquant.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.

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.

  1. GET /.well-known/apple-app-site-association → {"webcredentials":{"apps":["3YM54G49SN.ai.spboucher.vquant"]}}. With the app's webcredentials:vquant.spboucher.ai associated domain, macOS lets the app use the domain's passkeys (including those created in Safari and synced by iCloud Keychain).
  2. POST /api/native/login/options → challenge. ASAuthorizationPlatformPublicKeyCredentialProvider performs the assertion (Touch ID). POST /api/native/login/verify verifies it exactly as the web gate does (@simplewebauthn/server, expected origin https://vquant.spboucher.ai, user verification required, counter updated) and answers with a device token vqn_… (256 random bits).
  3. 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.
  4. Enrolment of a Mac that has no passkey: POST /api/native/register/options|verify with a setup-link token — the web app's own invitations, claimed atomically with the passkey insert.
  5. 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.
  6. Native routes require X-VQ-Client: vquant-macos/<version> and refuse any request carrying an Origin header; 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 after LAContext succeeds. 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/v2 call carries the same Bearer device token and no Origin. 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).
Files main
Menu

Theme