Study: Auth platform selection

⚠️ AUTH IS BURIED — 2026-05-18. The implementation work captured below was paused mid-spike. CV and JobCache currently run with no authentication enforcement on any endpoint that previously required a bearer token. This study stays here because the design will resume when we have the mindshare for it; right now it is historical research, not the current production state.

Thaw path: git checkout auth-stashed-v1 (formerly the auth-spike branch). SPIKE-LOG.md at the branch root has 6+ hours of journaled learnings with every gotcha as inline code comments.

Status: research complete, decision deferred Date: 2026-05-18

Goal

Pick an authentication architecture for CareerVector + JobCache that:

1. Secures every privileged endpoint (admin UIs, MCP tools that mutate, agent-callable APIs)
2. Supports three user types — public, admin (privileged paths), end users (jobcache)
3. Doesn't lock us into a vendor that monetizes the gateway between us and our users/money
4. Ships in a reasonable amount of time given that auth is not the main business
5. Survives our uncertainty about jobcache's eventual shape and customer mix

User types

CV's main app has no user accounts by design (CLAUDE.md §1) — workspace slug = identity. This study covers only the admin and end-user tiers + the service/agent tier.

Current state (May 2026)

Four different bearer-auth implementations exist today:

Workers with no auth gating that probably need it:

• careervector-mcp — agent-facing, currently public
• jobcache-interface UI host — needs human auth for jobcache users
• jobcache-interface MCP host — needs bearer auth at minimum

Options considered

Identity-provider SaaS

The recurring theme: SaaS providers monetize on the exact surface that hurts to migrate (users + payments). Migration tax = "every active user resets password / re-enrolls MFA / re-links OAuth."

Self-hosted IdP services

Auth libraries (no extra service)

Critical finding: the "Cloud ↔ self-hosted seamless switch" marketing claim

Multiple OSS-with-Cloud providers (Hanko, Logto) advertise "no vendor lock-in, move between Cloud and self-hosted anytime." Verified against their own docs:

Hanko Cloud → self-hosted (May 2026 reality):

• Export requires a paid plan (Admin API only)
• Export JSON schema documented contains: user_id, email, created_at, updated_at
• Export schema does NOT include: password hashes, MFA factors, passkey credentials, OAuth provider links
• Their own docs: "A dedicated export feature matching the import functionality will be added to Hanko Cloud in the near future"
• Their own docs: "Currently with our help, but full self-service import/export will soon be possible"

Logto Cloud → self-hosted:

• FAQ: "Safely migrate your critical data and resources to an alternative platform. Reach out to us for expert assistance during this process"
• i.e., sales conversation, not a button

So the "no vendor lock-in" claim is architecturally true (same Docker image, same schema) but operationally aspirational today. Today both Hanko Cloud and Logto Cloud have the same migration tax as a fully proprietary SaaS — forced password resets, MFA re-enrollment, OAuth re-link for every active user.

The only path with genuinely zero migration cost is starting self-hosted from day 1, OR owning the user table outright via a library.

Migration-pain principle

Migration pain has three sources:

1. Passwords: hashed with provider-specific algorithm/version — never portable
2. MFA factors / passkey credentials: bound to relying party ID and stored in provider DB — re-enrollment required
3. OAuth tokens: per-relying-party — re-link required

To eliminate migration pain:

• Own the user table (so the user records persist regardless of auth provider)
• Use stable provider subjects (Google's sub claim, Microsoft's oid claim) as foreign keys to provider identity
• Don't store passwords at all — eliminate (1)
• Don't enroll MFA in our system — eliminate (2) by federating to Google/Microsoft which do MFA at their layer
• Use OAuth-only flows — (3) becomes "user clicks Sign in with Google again," not real migration

This gives us the property: the auth library can be swapped at any time without any user-visible migration.

Decision (tentative, 2026-05-18)

A two-mode design:

Public surfaces (CV main UI, status pages, wiki) keep their current "no auth needed" model.

Schema sketch

users
├── id          UUID (we mint)
├── google_sub  TEXT NULLABLE  (Google OAuth sub claim, unique if present)
├── microsoft_sub TEXT NULLABLE (Microsoft OAuth oid claim, unique if present)
├── email       TEXT
├── role        TEXT  ('admin' | 'user')
├── plan        TEXT NULLABLE  (jobcache subscriber plan, later)
├── created_at  TIMESTAMP
└── …
sessions       (DB-backed, signed token in cookie)

Two DBs:

• careervector-auth worker → D1 (CV admin users)
• jobcache-interface → Cockroach (jobcache users)

Sessions are cookies scoped to .careervector.corbet.ch / .jobcache.corbet.ch so any worker under those zones can read them.

Migration optionality preserved

Footgun checklist for Better Auth

Defaults handle most of these correctly. The ones we must verify:

1. CF Rate Limiting on all auth endpoints (Better Auth doesn't ship this) — prevents enumeration/email-bombing
2. Cookie attributes — httpOnly: true, secure: true, sameSite: 'lax' in prod; verify env-aware config
3. Uniform login errors — opt in to "invalid credentials" instead of "user not found" / "wrong password" (low priority if we go OAuth-only since we never see passwords)
4. DB-backed sessions (default) — JWT-only sessions don't revoke until expiry
5. No password storage — confirmed by OAuth-only mode, no MFA enrolled in our system

What we explicitly DON'T build now

To preserve migration-zero property:

• ❌ Email/password authentication (creates a hash-format migration debt)
• ❌ Magic link via email (requires transactional email infra)
• ❌ MFA enrollment in our system (Google/Microsoft handle MFA at IdP layer)
• ❌ Passkeys at app level (passkey credentials are bound to relying party ID, complicated migration story)
• ❌ Cloud auth provider at any tier

If any of these are demanded later (an enterprise customer pushing for in-app MFA, say), we'll add them with migration debt as a conscious trade.

Open questions

• Microsoft OAuth for v1: do enough small-business customers use Microsoft 365 to warrant supporting it on day 1, or start Google-only and add Microsoft when asked?
• jobcache signup model: invite-only (we mint accounts) or open OAuth signup? Invite-only is safer until product-market fit is clear.
• SAML escape valve: if/when an enterprise customer demands SAML SSO, bolt on WorkOS Connections-as-a-Service ($125/mo per connection) plugged into Better Auth as an OIDC provider. Pay only when revenue justifies. Decision deferred until first ask.
• Payments timing: deferred until first jobcache subscriber lines up. Stripe direct, not Clerk Billing or WorkOS-wrapped.

Recommended execution order

1. Extract lib/auth-bearer/ from lib/qa-platform — non-blocking, applies regardless of human-auth choice (~1.5h)
2. Migrate ops/api, ops/mcp, jobcache-control, jobcache-ingest to use it; add bearer to careervector-mcp (~2h)
3. Provision Better Auth (OAuth-only, Google) in jobcache-interface — user table, session middleware, sign-in/sign-out (~3h)
4. New careervector-auth worker with Better Auth; gate qa/ops UIs via session cookie at .careervector.corbet.ch (~3h)
5. Stripe wiring for jobcache (deferred until needed)

Total ~9-10 hours of focused work. $0/mo forever. Migration cost forever bounded.

References

• Better Auth GitHub — MIT, 28.3k stars
• Auth.js docs — alternative to Better Auth
• Hanko import/export docs — verified the migration story today
• WorkOS pricing — verified per-connection costs
• Clerk pricing — verified Billing take-rate
• Logto pricing — verified Cloud feature pricing
• CLAUDE.md §1: CareerVector has no user accounts by design (link = identity)