@absolutejs/auth 0.54.9 → 0.55.1

package/dist/utils.d.ts

@@ -21,7 +21,7 @@ export declare const resolveCookieSecure: (override?: boolean) => boolean;
 export declare const resolveOAuthAuthorization: ({ authProvider, providerConfiguration, providerInstance, tokenResponse, now }: {
     authProvider: string;
     providerConfiguration?: ProviderConfig;
-    providerInstance: OAuth2Client<ProviderOption>;
+    providerInstance: Pick<OAuth2Client<ProviderOption>, "fetchUserProfile">;
     tokenResponse: OAuth2TokenResponse;
     now?: number;
 }) => Promise<ResolvedOAuthAuthorization>;

package/docs/AGENT-AUTH.md

@@ -0,0 +1,54 @@
+# Agent authentication and registration
+
+Absolute Auth implements agent registration inside `@absolutejs/auth`. There is
+no separate `auth-md` package and no WorkOS service dependency. `/auth.md` is a
+wire-compatible, generated companion document; OAuth metadata remains the
+authoritative machine-readable contract.
+
+## Interoperability contract
+
+The implementation composes existing standards wherever they already define the
+behavior:
+
+- RFC 9728 protected-resource discovery
+- RFC 8414 authorization-server discovery
+- RFC 7523 JWT bearer grants
+- RFC 8628-style user-code polling semantics
+- RFC 9396-compatible authorization details in agent delegations
+- the auth.md v0.6 registration projection and ID-JAG assertion type
+
+The auth.md claim grant currently has a WorkOS-namespaced URN because that is the
+identifier in the open v0.6 wire profile. It is isolated behind
+`AGENT_CLAIM_GRANT_TYPE`; it does not indicate a WorkOS backend dependency. A
+future neutral identifier can be accepted alongside it without changing the
+internal store, verifier, or client contracts.
+
+Protocol inputs are normalized into provider-neutral Absolute types. Identity
+verification, user resolution, stores, key management, and token revocation are
+injected interfaces. Provider adapters can therefore be added without changing
+routes or application authorization logic.
+
+## Security invariants
+
+- The service owns the account-linking page. Agents never receive passwords,
+  MFA codes, or service session cookies.
+- ID-JAG assertions are signature-, issuer-, audience-, client-, freshness-,
+  verification-, and replay-checked before identity resolution.
+- A durable identity key includes issuer, subject, and client id. Different
+  agents acting for the same user cannot collapse into one registration.
+- Claim and attempt tokens are stored only as hashes. User codes have bounded
+  attempts, short expirations, constant-time comparison, and atomic updates.
+- Polling is rate-enforced and returns `slow_down` when the advertised interval
+  is ignored.
+- Access tokens are opaque, scoped, short-lived, and looked up in a revocable
+  store. Anonymous pre-claim credentials must be revoked before ownership is
+  committed.
+- Structured discovery never advertises an optional capability, such as
+  security-event delivery, unless the deployment actually implements it.
+
+## Deployment checklist
+
+Use the Postgres identity-registration store in production, run the `agents`
+migrations, keep signing keys in managed key storage, make anonymous-token
+revocation idempotent, pin trusted assertion issuers and client ids, and apply
+normal edge rate limits to identity, claim, completion, and token routes.

package/docs/MIGRATE-FROM-LUCIA.md

@@ -0,0 +1,235 @@
+# Migrating from Lucia (v3) to `@absolutejs/auth`
+
+Lucia was deprecated in 2024. The maintainer's note —
+*"database adapters have been a significant complexity tax"* — is exactly
+the problem `@absolutejs/auth` solves by **owning the schema** (via
+Drizzle migrations + the `bunx absolute-auth migrate` CLI) instead of
+abstracting around yours.
+
+If you're on Lucia v3, this guide walks you through the migration
+end-to-end. It assumes Postgres + Drizzle ORM; SQLite + better-sqlite3
+follow the same flow with the obvious column-type swaps.
+
+> Status: tested against Lucia v3.2.x. Open an issue with your Lucia
+> config snippet if you hit a shape this guide doesn't cover.
+
+## What you keep
+
+- **Your user table** — `@absolutejs/auth` doesn't rename `users.id`,
+  drop fields, or require you to give up your domain columns. The
+  migration adds `users.sub` (UUID) alongside whatever you already have.
+- **Session semantics** — server-side sessions with an httpOnly cookie,
+  same trust model as Lucia. We use Redis or in-memory; the cookie name
+  is `user_session_id` (configurable).
+- **Argon2id password hashes** — Lucia's default. We accept them
+  unchanged (`@absolutejs/auth` uses `Bun.password.hash` which also
+  defaults to argon2id).
+
+## What changes
+
+| Lucia | `@absolutejs/auth` |
+|---|---|
+| `lucia.createSession(userId, attributes)` | Implicit — `auth<UserType>()` creates the session on a successful OAuth callback or `signin.email({...})`. |
+| `lucia.validateSession(sessionId)` | Use the `protectRoutePlugin` decorator on routes that need an authenticated user. |
+| `lucia.invalidateSession(sessionId)` | `await authSessionStore.removeSession(sessionId)` or hit `/oauth2/signout`. |
+| `lucia.invalidateUserSessions(userId)` | `await authSessionStore.removeUserSessions(userId)`. |
+| `getUserAttributes` hook | Move logic into your route handler; the user is already in `context.user`. |
+| Custom `Adapter` (SQLite / Postgres / D1) | Not needed — schema is fixed via Drizzle migrations. |
+| `Lucia.Register` module-augmentation trick | Plain generic — `auth<MyUser>({...})`. |
+
+## Step-by-step
+
+### 1. Install + bootstrap
+
+```bash
+bun add @absolutejs/auth elysia citra
+bunx absolute-auth migrate
+```
+
+The CLI generates the Drizzle migrations for `users`, `auth_identities`,
+`auth_sessions`, `auth_login_history` (adaptive risk), and so on. Run
+them against your DB.
+
+### 2. Backfill from Lucia's tables
+
+The package ships an import CLI that handles this end-to-end:
+
+```bash
+# Export your Lucia tables to a single JSON file:
+psql $LUCIA_DB -c "\COPY (SELECT json_agg(row_to_json(u)) FROM \"user\" u) TO 'users.json'"
+psql $LUCIA_DB -c "\COPY (SELECT json_agg(row_to_json(k)) FROM \"key\" k) TO 'keys.json'"
+# Concatenate into one document:
+jq -s '{ users: .[0], keys: .[1] }' users.json keys.json > lucia-export.json
+
+# Dry-run (counts only, no inserts):
+bunx absolute-auth import lucia lucia-export.json --db $DATABASE_URL
+
+# Commit:
+bunx absolute-auth import lucia lucia-export.json --db $DATABASE_URL --commit
+```
+
+The CLI extracts `email:`/`username:` keys → `users.password` and
+treats the rest as OAuth identities → `auth_identities`. Re-running is
+idempotent (`ON CONFLICT DO NOTHING` on email + provider:subject).
+
+If you'd rather do the SQL yourself (e.g. you need custom column
+mapping):
+
+```ts
+// scripts/migrateFromLucia.ts
+import { neon } from '@neondatabase/serverless';
+
+const sql = neon(process.env.DATABASE_URL);
+
+// 1. Users — Lucia's `user` → @absolutejs/auth's `users`
+//    Generate fresh UUIDs for `sub`; keep your existing primary key
+//    aliased in `legacy_id` for downstream-FK rewrites if needed.
+await sql`
+  INSERT INTO users (sub, email, created_at, /* your fields */)
+  SELECT
+    gen_random_uuid()::text,
+    email,
+    COALESCE(created_at, NOW()),
+    /* your fields */
+  FROM lucia_user
+  ON CONFLICT (email) DO NOTHING
+`;
+
+// 2. OAuth identities — Lucia's `key` rows with `:` prefix
+//    (e.g. `google:1234567890`) → auth_identities
+await sql`
+  INSERT INTO auth_identities (id, auth_provider, provider_subject, user_sub)
+  SELECT
+    split_part(k.id, ':', 1) || ':' || split_part(k.id, ':', 2),
+    split_part(k.id, ':', 1),
+    split_part(k.id, ':', 2),
+    u.sub
+  FROM lucia_key k
+  JOIN lucia_user l ON l.id = k.user_id
+  JOIN users u ON u.email = l.email
+  WHERE k.id LIKE '%:%'
+  ON CONFLICT DO NOTHING
+`;
+
+// 3. Password hashes — Lucia's `key` with `hashed_password`
+//    Argon2id format carries over unchanged.
+await sql`
+  UPDATE users SET password = k.hashed_password
+  FROM lucia_key k
+  JOIN lucia_user l ON l.id = k.user_id
+  WHERE k.hashed_password IS NOT NULL
+    AND users.email = l.email
+`;
+
+// 4. Sessions — DON'T migrate. Lucia uses opaque IDs; we use a different
+//    cookie name + scheme. Force a re-login on cutover by NOT copying
+//    the session table.
+```
+
+### 3. Wire the new auth config
+
+```ts
+import { Elysia } from 'elysia';
+import { auth, createNeonAuthSessionStore } from '@absolutejs/auth';
+
+type MyUser = {
+  email: string;
+  sub: string;
+  // …whatever your domain user has
+};
+
+const authSessionStore = createNeonAuthSessionStore<MyUser>();
+
+const app = await auth<MyUser>({
+  authSessionStore,
+  // your existing OAuth provider config (Google, GitHub, …)
+  providersConfiguration: { google: { /* … */ } },
+  // The bridge from a decoded token → your user shape.
+  // Lucia's `getUserAttributes` lives here now.
+  getUser: (decoded) => ({
+    email: decoded.email,
+    sub: /* … */,
+  }),
+});
+```
+
+### 4. Replace `validateSession` call sites
+
+Before (Lucia):
+
+```ts
+app.get('/me', async (ctx) => {
+  const { session, user } = await lucia.validateSession(
+    ctx.cookies.get('auth_session') ?? ''
+  );
+  if (!session) return ctx.error(401);
+
+  return user;
+});
+```
+
+After (`@absolutejs/auth`):
+
+```ts
+import { protectRoutePlugin } from '@absolutejs/auth';
+
+app
+  .use(protectRoutePlugin<MyUser>())
+  .get('/me', ({ user }) => user); // typed as MyUser, throws 401 if unauthenticated
+```
+
+### 5. Switch the cookie name (optional)
+
+Lucia's default cookie is `auth_session`. `@absolutejs/auth` uses
+`user_session_id`. If you want zero re-logins after the cutover (you
+also can't — see Step 2 — but if you've decided to migrate sessions
+manually), the session cookie config is overridable. We recommend
+NOT migrating sessions; the cutover is the right moment to force
+re-auth.
+
+### 6. Drop the Lucia tables
+
+```sql
+DROP TABLE lucia_session, lucia_key, lucia_user;
+```
+
+(After the migration script verifies zero new user creation in Lucia.)
+
+## What you get post-migration that you didn't have before
+
+- **OIDC provider role** — your app can issue OAuth tokens to other apps
+  via `/.well-known/openid-configuration`. Lucia is an RP only.
+- **MFA (TOTP) + passkeys (WebAuthn) + magic links** — all first-party,
+  Lucia required third-party libraries.
+- **SCIM 2.0 + SAML 2.0 IdP role** for enterprise SSO.
+- **Tamper-evident audit log** with hash-chained events + SIEM streaming.
+- **Adaptive risk** + strong device fingerprinting on every login.
+- **Drop-in OAuth provider library** ([citra](https://www.npmjs.com/package/citra))
+  — every quirk Slack/LinkedIn/QuickBooks/Salesforce inflict on you,
+  centrally handled. See [OAUTH-PROVIDER-QUIRKS.md](./OAUTH-PROVIDER-QUIRKS.md).
+
+## Common questions
+
+**Q: My Lucia setup used SQLite. Does this work?**
+Yes — Drizzle supports SQLite, the migration SQL above swaps to the
+SQLite dialect. The argon2id verifiers, OAuth flows, and TS types are
+all SQL-dialect-agnostic.
+
+**Q: I have custom `DatabaseUserAttributes` from Lucia's module
+augmentation. How do I port that?**
+That's just your `UserType` now. Pass it as the generic to `auth<T>()`
+— compile-time enforced everywhere downstream, no module augmentation.
+
+**Q: I used Lucia's "key" abstraction for non-OAuth identities (Apple
+Sign In via custom claims, magic-link tokens, etc.). Where do those go?**
+Magic links: built-in via the `passwordless` block. Apple Sign In:
+treated as a standard OAuth provider via citra. Any other custom
+"identity" you owned: write a row into `auth_identities` with your
+chosen `auth_provider` value (e.g. `apple`).
+
+**Q: I want to keep Lucia's sessions live during the cutover.**
+The cleanest path is to NOT — force a re-login. If you must, write a
+session-bridge middleware that reads Lucia's `auth_session` cookie,
+calls Lucia's `validateSession`, mints a new `@absolutejs/auth` session
+in our store, and sets the new cookie. Single-PR rollback path:
+remove the bridge, Lucia's cookie expires naturally.

package/docs/OAUTH-PROVIDER-QUIRKS.md

@@ -0,0 +1,150 @@
+# OAuth Provider Quirks Reference
+
+Nango's 2026 post — *"the real-world OAuth experience is comparable to
+JavaScript browser APIs in 2008"* — is accurate. Every major OAuth
+provider implements the spec a little differently, and the gap between
+"works on Localhost with Google" and "works in production with eight
+providers" is where most auth libraries lose their developers.
+
+`@absolutejs/auth` delegates provider-specific knowledge to
+[citra](https://www.npmjs.com/package/citra), which means the quirks
+below are handled for you. This doc exists so you know *what* citra is
+handling — useful when debugging, when a provider rolls out a breaking
+change, or when you're picking which providers to support.
+
+## Quick reference
+
+| Provider | Standard? | Notable quirks |
+|---|---|---|
+| Google | ✓ Mostly | Email scope `openid email profile`; refresh tokens require `access_type=offline&prompt=consent`. |
+| GitHub | ✗ Not OIDC | Returns `access_token` directly (no `id_token`); the user email needs a second call to `/user/emails` because the primary OAuth payload omits it for users who hide their email. |
+| LinkedIn | ✗ | **Silently fails with PKCE.** citra disables PKCE for LinkedIn — passing it returns a confusing "Unauthorized" error from LinkedIn's `/oauth/v2/accessToken` with no body. |
+| Slack | ✗ | **Two scope types** — `scope` (workspace-installed bot scopes) and `user_scope` (Sign in with Slack). citra exposes both separately. |
+| Discord | ✓ Mostly | Email scope returns a different payload shape on `/users/@me` vs the OIDC `userinfo` endpoint; citra normalizes. |
+| Facebook | ✗ | Token exchange uses GET, not POST. App tokens have a different format from user tokens. citra picks the right one. |
+| Microsoft / Entra | ✓ | `tid` (tenant) claim is the multi-tenant routing key. Personal accounts vs work accounts return different `iss` claims; citra exposes both. |
+| Apple | ✗ | **`form_post` response mode by default** — the redirect comes back as a POST, not GET. citra registers a POST handler. ID token returns first-name/last-name on FIRST sign-in only; we cache it. |
+| QuickBooks | ✗ | Adds a `realmId` query param to the redirect — not in the spec, but essential (it's the QuickBooks company-file scope). citra exposes it as a top-level property. |
+| Salesforce | ✗ | Returns `instance_url` (which sandbox/region) outside the spec. citra exposes it. Refresh-token TTL is governed by org-level setting "Refresh Token Policy", not OAuth defaults. |
+| Notion | ✗ | The `bot_id` in the token response is the workspace integration — not the user. citra makes the distinction. |
+| Zoom | ✓ Mostly | Refresh tokens rotate on every use AND invalidate other refresh tokens for the same user — single-device limit by default. |
+| Atlassian (Jira / Confluence) | ✗ | Per-resource access tokens. citra fetches `/oauth/token/accessible-resources` after token exchange to expose the cloud IDs the token can access. |
+| Spotify | ✓ | Standard. |
+| Twitch | ✓ Mostly | The OAuth flow uses `id_token` but the `at_hash` calculation diverges from the spec — citra skips at_hash verification for Twitch. |
+| Yahoo | ✗ | Uses non-standard `userinfo` paths per region (US vs JP). citra handles per-region. |
+| Stack Overflow | ✗ | Token endpoint returns the access token URL-encoded in the body (e.g. `access_token=abc&expires=86400`), not JSON. citra parses it. |
+| Dropbox | ✗ | Refresh tokens not issued unless you pass `token_access_type=offline` — undocumented. citra adds it. |
+| Reddit | ✗ | Returns `error: 'unsupported_response_type'` if you DON'T also pass `duration=permanent` for refresh-capable flows. citra adds it. |
+| X (Twitter) v2 | ✓ Mostly | Required `code_challenge_method=plain` if you pass `state` containing a `+`. citra escapes. |
+
+## The hairy ones in detail
+
+### LinkedIn
+
+**Problem:** LinkedIn's IdP rejects PKCE proofs without a useful error.
+The `/oauth/v2/accessToken` call returns 401 Unauthorized with an HTML
+body (yes, HTML) explaining nothing.
+
+**citra's handling:** LinkedIn's provider config sets `pkce: false`.
+The redirect URL doesn't include `code_challenge`; the token exchange
+doesn't include `code_verifier`. State + nonce only.
+
+**Implication for security:** LinkedIn is a public OAuth client (no
+client-bound proof of possession). Combine with strict `redirect_uri`
+matching, short auth-code TTLs, and prefer `private_key_jwt` if you
+have an enterprise LinkedIn instance.
+
+### Apple Sign In
+
+**Problem 1:** Apple POSTs the callback (form-post response mode) by
+default. Most Express/Elysia setups only register the redirect handler
+on `GET /callback`.
+
+**citra's handling:** the redirect handler accepts both GET and POST
+methods. The package's `callback.ts` extracts the auth code from either
+query or form body.
+
+**Problem 2:** Apple includes the user's first/last name as a JSON
+payload in the `user` parameter on the **FIRST** sign-in only. Re-logins
+omit it. If you wait until the second sign-in to extract the name,
+you'll never see it.
+
+**citra's handling:** extracts on first call + persists. Subsequent
+sign-ins return the cached name from `auth_identities.metadata`.
+
+### Slack
+
+**Problem:** Slack has two distinct OAuth scope vocabularies — `scope`
+(bot/installer scopes) and `user_scope` (Sign in with Slack). Passing
+only `scope` works for app install but fails for Sign in with Slack;
+passing only `user_scope` works for Sign in with Slack but doesn't
+install the app.
+
+**citra's handling:** the Slack provider config exposes both as
+separate fields.
+
+### QuickBooks
+
+**Problem:** QuickBooks adds a non-spec `realmId` parameter to the
+redirect — it identifies which company file the user authorized. If
+you don't capture it, you've lost the only way to know which QuickBooks
+account this token operates on.
+
+**citra's handling:** parses `realmId` from the callback URL and
+exposes it on the decoded payload alongside `email` / `sub` / etc.
+
+### Salesforce
+
+**Problem 1:** The token response includes `instance_url` — the URL of
+the Salesforce org — which is where all subsequent API calls must go.
+The OAuth spec has no field for this, so most libraries drop it.
+
+**citra's handling:** `instance_url` exposed on the decoded payload.
+
+**Problem 2:** Refresh token TTL is governed by the Salesforce org's
+"Refresh Token Policy" setting, which can be configured to expire
+sooner than standard OAuth defaults. If you assume standard semantics,
+you'll get random 401s when the org admin tightens the policy.
+
+**citra's handling:** treats every refresh as potentially failing and
+returns an explicit error code; the consumer's `OnRefreshError` handler
+gets the chance to redirect the user back through the authorize flow.
+
+### Microsoft / Entra ID
+
+**Problem:** Personal accounts and work accounts return different
+`iss` (issuer) claims:
+
+```
+work:     https://login.microsoftonline.com/{tenant-id}/v2.0
+personal: https://login.microsoftonline.com/9188040d-...-bf63a3.../v2.0
+```
+
+A naive `iss` allowlist that only includes one breaks the other.
+
+**citra's handling:** issuer-check matches by prefix
+`https://login.microsoftonline.com/`. JWKS lookup goes via the `iss`
+claim's tenant.
+
+## When citra needs to evolve
+
+Providers change their OAuth behavior unilaterally. When you see:
+- A new error code in an `OnCallbackError` log,
+- A field you used to get from the decoded payload going missing,
+- A `401` from a refresh that used to work,
+
+…the fastest fix is usually to bump citra to its latest version
+(`bun add citra@latest`). citra ships a per-provider integration test
+suite + tracks upstream changes; typical lag between a provider
+breaking change and a citra patch is days, not months.
+
+If a fix isn't in citra yet, open an issue at
+[github.com/absolutejs/citra](https://github.com/absolutejs/citra) with
+the provider name + the specific request/response that failed. The
+provider config is one TypeScript file per provider; patches are usually
+5–30 lines.
+
+## Recommended reading
+
+- [Nango: Why is OAuth Still Hard in 2026?](https://nango.dev/blog/why-is-oauth-still-hard/)
+- [RFC 9700 (OAuth 2.0 Best Current Practice)](https://datatracker.ietf.org/doc/rfc9700/) — the FAPI 2.0 baseline; pair with `strictFapi: true`.

package/docs/UI-COMPONENTS.md

@@ -0,0 +1,226 @@
+# Drop-in UI Components
+
+The most common reason developers stay on Clerk / Auth0 isn't the auth
+itself — it's the polished `<UserButton />` and `<SignIn />` components
+that go with them. This page is the answer to *"but I'd lose Clerk's
+`<UserButton />`."*
+
+`@absolutejs/auth` ships three headless components (React) + the recipe
+to build the same in Vue / Svelte / Solid using the existing
+composables. Every component is restyleable via a `classNames` prop;
+every internal element carries a `data-abs-auth="…"` attribute the
+consumer can target from CSS without touching the source.
+
+## React
+
+The components are real React functional components in
+`@absolutejs/auth/react`:
+
+```tsx
+import { authClient } from './shared/authClient'; // your createAuthClient instance
+import { SignIn, SignUp, UserButton } from '@absolutejs/auth/react';
+
+// Sign-in page
+<SignIn
+  client={authClient}
+  providers={['google', 'github']}  // optional OAuth buttons above the form
+  onSuccess={(result) => {
+    if (result.status === 'mfa_required') router.push('/mfa');
+    else router.push('/dashboard');
+  }}
+  onError={(error) => console.error(error.message)}
+  classNames={{
+    container: 'flex flex-col gap-4 max-w-sm',
+    button: 'rounded-md bg-violet-600 text-white py-2',
+    input: 'border-slate-200 border rounded px-3 py-2',
+    // …all classNames are optional
+  }}
+/>
+
+// Sign-up page (always email/password; OAuth registration uses /authorize directly)
+<SignUp
+  client={authClient}
+  onSuccess={(result) => {
+    if (result.status === 'verification_required') router.push('/verify-email');
+    else router.push('/dashboard');
+  }}
+/>
+
+// Top navigation user button
+<UserButton
+  client={authClient}
+  user={user}  // your AuthUser-shaped record (you keep the session state)
+  items={[
+    { label: 'Settings', href: '/settings' },
+    { label: 'API keys', href: '/settings/api' },
+  ]}
+  onSignOut={() => router.push('/')}
+/>
+```
+
+### `data-abs-auth` attributes — restyle without classNames
+
+If you don't want to thread classNames through every render call, set
+your CSS based on the data attribute selector:
+
+```css
+[data-abs-auth='sign-in'] { display: flex; flex-direction: column; gap: 1rem; }
+[data-abs-auth='submit']:disabled { opacity: 0.5; cursor: not-allowed; }
+[data-abs-auth='oauth-grid'] { display: grid; grid-template-columns: 1fr 1fr; gap: 0.5rem; }
+[data-abs-auth='menu'] { position: absolute; right: 0; top: 100%; }
+```
+
+## Vue 3 — copy-paste recipes
+
+Vue SFCs have their own compile step that's outside this package's
+build scope, so we ship the composables (`useSignIn`, `useSignUp`,
+`useSignOut`) and you drop a ~30-line SFC into your project:
+
+```vue
+<!-- src/components/auth/SignIn.vue -->
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useSignIn } from '@absolutejs/auth/vue';
+import type { AuthClient } from '@absolutejs/auth/client';
+
+const props = defineProps<{ client: AuthClient }>();
+const emit = defineEmits<{ success: [unknown]; error: [Error] }>();
+
+const email = ref('');
+const password = ref('');
+const { error, isPending, mutate } = useSignIn(props.client);
+
+const onSubmit = async () => {
+  const result = await mutate({ email: email.value, password: password.value });
+  if (result.error !== null) emit('error', result.error);
+  else if (result.data !== null) emit('success', result.data);
+};
+</script>
+
+<template>
+  <form @submit.prevent="onSubmit" data-abs-auth="sign-in">
+    <label data-abs-auth="email-field">
+      <span>Email</span>
+      <input v-model="email" type="email" autocomplete="username webauthn" required />
+    </label>
+    <label data-abs-auth="password-field">
+      <span>Password</span>
+      <input v-model="password" type="password" autocomplete="current-password" minlength="12" required />
+    </label>
+    <p v-if="$error" role="alert" data-abs-auth="error">{{ $error.message }}</p>
+    <button type="submit" :disabled="isPending" data-abs-auth="submit">
+      {{ isPending ? 'Signing in…' : 'Sign in' }}
+    </button>
+  </form>
+</template>
+```
+
+`SignUp.vue` and `UserButton.vue` follow the same shape — swap
+`useSignIn` for `useSignUp` / `useSignOut`.
+
+## Svelte 5 (runes) — copy-paste recipe
+
+```svelte
+<!-- src/lib/components/SignIn.svelte -->
+<script lang="ts">
+  import { useSignIn } from '@absolutejs/auth/svelte';
+  import type { AuthClient } from '@absolutejs/auth/client';
+
+  let { client, onSuccess, onError }: {
+    client: AuthClient;
+    onSuccess?: (result: unknown) => void;
+    onError?: (error: Error) => void;
+  } = $props();
+
+  let email = $state('');
+  let password = $state('');
+  const { error, isPending, mutate } = useSignIn(client);
+
+  const onSubmit = async (event: SubmitEvent) => {
+    event.preventDefault();
+    const result = await mutate({ email, password });
+    if (result.error !== null) onError?.(result.error);
+    else if (result.data !== null) onSuccess?.(result.data);
+  };
+</script>
+
+<form onsubmit={onSubmit} data-abs-auth="sign-in">
+  <label data-abs-auth="email-field">
+    <span>Email</span>
+    <input bind:value={email} type="email" autocomplete="username webauthn" required />
+  </label>
+  <label data-abs-auth="password-field">
+    <span>Password</span>
+    <input bind:value={password} type="password" autocomplete="current-password" minlength="12" required />
+  </label>
+  {#if $error}
+    <p role="alert" data-abs-auth="error">{$error.message}</p>
+  {/if}
+  <button type="submit" disabled={$isPending} data-abs-auth="submit">
+    {$isPending ? 'Signing in…' : 'Sign in'}
+  </button>
+</form>
+```
+
+## Solid — copy-paste recipe
+
+```tsx
+// src/components/auth/SignIn.tsx
+import { createSignal, type Component } from 'solid-js';
+import { useSignIn } from '@absolutejs/auth/solid';
+import type { AuthClient } from '@absolutejs/auth/client';
+
+export const SignIn: Component<{
+  client: AuthClient;
+  onSuccess?: (result: unknown) => void;
+  onError?: (error: Error) => void;
+}> = (props) => {
+  const [email, setEmail] = createSignal('');
+  const [password, setPassword] = createSignal('');
+  const { error, isPending, mutate } = useSignIn(props.client);
+
+  const onSubmit = async (event: SubmitEvent) => {
+    event.preventDefault();
+    const result = await mutate({ email: email(), password: password() });
+    if (result.error !== null) props.onError?.(result.error);
+    else if (result.data !== null) props.onSuccess?.(result.data);
+  };
+
+  return (
+    <form onSubmit={onSubmit} data-abs-auth="sign-in">
+      <label data-abs-auth="email-field">
+        <span>Email</span>
+        <input value={email()} onInput={(e) => setEmail(e.currentTarget.value)}
+               type="email" autocomplete="username webauthn" required />
+      </label>
+      <label data-abs-auth="password-field">
+        <span>Password</span>
+        <input value={password()} onInput={(e) => setPassword(e.currentTarget.value)}
+               type="password" autocomplete="current-password" minlength={12} required />
+      </label>
+      {error() && (
+        <p role="alert" data-abs-auth="error">{error()!.message}</p>
+      )}
+      <button type="submit" disabled={isPending()} data-abs-auth="submit">
+        {isPending() ? 'Signing in…' : 'Sign in'}
+      </button>
+    </form>
+  );
+};
+```
+
+## Why we don't ship Vue/Svelte/Solid SFCs in the package
+
+Each non-React framework needs its own SFC compiler bundled into the
+build pipeline (`@vitejs/plugin-vue`, `@sveltejs/vite-plugin-svelte`,
+`solid-vite`). Adopting four parallel build paths in a single package
+inflates the install footprint by 30–60 MB and creates a maintenance
+matrix that the React-only approach doesn't have.
+
+The composables (`useSignIn`, `useSignUp`, etc.) are framework-native
+and shipped in `@absolutejs/auth/{vue,svelte,solid}`. Wiring a
+20-30-line SFC over them is faster than configuring our build to ship
+them precompiled — and gives you full control of the markup.
+
+If you'd like SFC-native components added to the package despite the
+build cost, open an issue.