Authentication & Session Management

Authentication & Session Management

Status: Available Pattern

Authentication in Swoff is identity plumbing — how the client proves to your backend who the user is. We don't care how you sign in (JWT, cookies, OAuth, biometric). We care about the browser-native infrastructure for storing, attaching, and invalidating that proof.

Two Worlds of Auth

Auth mechanisms fall into two categories at the transmission level:

Cookie / Session Auth (Automatic)

The server sets an http-only cookie on login. The browser automatically sends it on subsequent same-origin requests. No client header setup needed.

Examples: Better-Auth (default), Auth.js / NextAuth.js, Clerk (same-origin), Laravel Sanctum (SPA), Passport.js (session), Django SessionAuth, Supabase SSR, Logto (web).

Bearer / Custom Header Auth (Manual)

The server returns a token on login. The client stores it and manually attaches it to every request via Authorization or a custom header.

Examples: Auth0, Firebase Auth, Better-Auth (bearer plugin), Supabase (raw fetch), Laravel Sanctum (API), DRF JWT, Passport.js (JWT), Clerk (cross-origin), Logto (SPA).

Setup with CLI

Configure auth in swoff.config.json and regenerate:

{
  "features": {
    "auth": {
      "enabled": true,
      "type": "bearer",
      "refreshPath": "/api/refresh",
      "userEndpoint": "/api/me"
    }
  }
}

The CLI generates four files:

• swoff/auth-store.js — memory-only token, persists { user, expiresAt } to IndexedDB
• swoff/auth-fetch.js — authenticatedFetch() + config-driven withAuthHeaders()
• swoff/auth-user.js — user fetch + separate IndexedDB cache
• swoff/auth-state.js — four-state detection (online/offline × authenticated/unauthenticated)

Prerequisites

1. API Integration — fetchWithCache base wrapper
2. Client Registration — SW registered and active

Next Steps

• Auth Store — how token storage works
• Auth Libraries Reference — identify your auth type