@lunora/cli 1.0.0-alpha.46 → 1.0.0-alpha.461

package/skills/lunora-setup-auth/SKILL.md

@@ -1,110 +1,195 @@
 ---
 name: lunora-setup-auth
-description: Adds authentication to a Lunora app. Use for sign-up/sign-in, email/password,
-    OAuth (Clerk, Auth0), magic link, or email OTP via `lunora registry add auth`,
-    wiring the auth handler into the Worker, and gating functions on the session.
+description: Adds authentication to a Lunora app with the `auth` registry item (better-auth via `@lunora/auth`, users and sessions in D1). Covers email/password sign-up and sign-in, Clerk or Auth0 OAuth, magic link, email OTP, copy-in auth screens (`lunora add auth-ui`), wiring `/api/auth/*` and `resolveIdentity` into the Worker, and gating functions on `ctx.auth.userId`. Use when the user asks to "add auth", "add login/sign-in/sign-up", "protect this query", or "add Clerk/Auth0/magic link/OTP", wants to keep an external identity provider (Clerk, WorkOS, Auth0, Supabase, any OIDC JWT) as the session owner, runs `lunora add auth` or `lunora registry add auth`, edits `lunora/auth/index.ts`, or `ctx.auth.userId` is unexpectedly `null`.
 ---
 
 # Lunora Setup Auth
 
-Wire authentication into a Lunora app using the `auth` registry item, which is
-built on `@lunora/auth` (a thin wrapper over
-[better-auth](https://www.better-auth.com)) with sessions persisted in
-`SessionDO` and identity tables in D1.
+The `auth` registry item is built on `@lunora/auth`, a thin wrapper over
+[better-auth](https://www.better-auth.com). Users and sessions are stored in D1.
+Lunora's `SessionDO` is a separate TTL'd token store that `@lunora/auth` never
+calls, so don't wire it for auth. If you need auth state in a Durable Object
+instead of D1, use `LunoraAuthDO` / `.auth({ namespace, internalSecret })`.
 
-## When to Use
+If the project has no Lunora backend yet, start with `lunora-quickstart`.
 
-- Adding sign-up / sign-in to a Lunora app.
-- Adding an OAuth/OIDC provider (Clerk, Auth0), magic link, or email OTP.
-- Gating queries/mutations on the signed-in user.
+## Already have an identity provider? Skip better-auth
 
-## When Not to Use
+If the app's users sign in through Clerk, WorkOS AuthKit, Auth0, Supabase or any
+OIDC issuer, and that provider should keep owning the session, don't add the
+`auth` item. Verify the provider's JWT instead with `@lunora/jwt-auth`:
 
-- The project has no Lunora backend yet — use `lunora-quickstart` first.
-- You only need to read `ctx.auth.userId` in a function and auth is already
-  installed — just use it.
+```bash
+lunora init --auth=clerk             # new project: or workos | auth0 (wires everything below)
+lunora registry add auth-clerk-jwt   # existing project: or auth-workos-jwt | auth-auth0-jwt
+```
+
+```ts
+import { clerk } from "@lunora/jwt-auth"; // workos, auth0, supabase, jwtIdentityResolver
+import { memoizeIdentity } from "lunorash/runtime";
+
+defineApp<Env>()
+    .shard((env) => env.SHARD)
+    .extend((env) => ({
+        resolveIdentity: memoizeIdentity(clerk({ publishableKey: env.CLERK_PUBLISHABLE_KEY ?? "", authorizedParties: env.CLERK_AUTHORIZED_PARTIES ?? "" })),
+    }))
+    .build();
+```
+
+On the client, create the `LunoraClient` with `authTokenOnUpgrade: true` and,
+once signed in, call `setAuthTokenProvider(client, getToken, { subject: userId })`
+from `lunorash/client`. It refreshes before `exp` and on `onTokenExpired`; map
+the provider's "signed out" error (WorkOS `LoginRequiredError`, Auth0
+`login_required`) to `null`. `authTokenOnUpgrade` is what authenticates
+live-query sockets: the browser offers the bearer as a `Sec-WebSocket-Protocol`
+entry. Without it, a WorkOS or Auth0 socket, or a cross-origin Clerk one, is
+anonymous.
 
-## Workflow
+Org claims arrive as `orgId` with the org role (`orgRole` for Clerk, `role` /
+`orgRoles` for WorkOS); no preset sets the app-wide `roles` RLS reads, since
+any Clerk user can create an organization and be its admin. Check the org role
+together with `orgId` in a policy. `CLERK_AUTHORIZED_PARTIES` is required.
+Full guide:
+`/docs/concepts/external-auth`, with runnable apps in `examples/clerk-auth` and
+`examples/workos-auth`.
 
-1. Add the base `auth` item.
-2. Mount the auth request handler in the Worker entry.
-3. Configure env vars and the D1 database.
-4. (Optional) Layer a provider item (Clerk / Auth0 / magic link / OTP) on top.
-5. Gate functions on `ctx.auth.userId`; gate UI with the auth gates/hooks.
+The rest of this skill covers the better-auth path.
 
-## Step 1: Add the base item
+## Step 1: Add the item
 
 ```bash
-lunora registry add auth
+lunora add auth                      # asks for the provider and D1 database name
+lunora add auth --provider clerk --db my-app-db   # non-interactive (auth | clerk | auth0)
+lunora registry add auth             # low-level: writes placeholder names
 ```
 
-This:
+Then run `pnpm install`. The item does the following:
 
-1. Adds `@lunora/auth`, `@lunora/mail`, and `@lunora/server` to `package.json`
-   (run `pnpm install` afterwards).
-2. Copies `lunora/auth/index.ts` — the auth instance (`buildAuth` / `getAuth`)
-   and the `/api/auth/*` request handler (`mountAuth`) — into your project. It is
-   **yours** to edit.
-3. Adds a D1 `DB` binding to `wrangler.jsonc` (better-auth persists
-   users/sessions there).
-4. Scaffolds `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, and `MAIL_FROM` into
-   `.dev.vars`.
+1. Adds `@lunora/auth`, `@lunora/mail` and `@lunora/server` to `package.json`.
+2. Copies `lunora/auth/index.ts` into the project. The project owns this file and can edit it. It exports `buildAuth(env)`, `getAuth(env)` (memoized per isolate) and `mountAuth(env, request)`, which routes `/api/auth/*` and returns `undefined` for any other path. The scaffold turns on email/password with `requireEmailVerification: true` and sends verification and reset mail through `@lunora/mail`. It also adds the `uiConfig()` plugin.
+3. Adds a D1 `DB` binding to `wrangler.jsonc`. The `database_id` is a placeholder.
+4. Writes `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL` and `MAIL_FROM` to `.dev.vars`.
 
-## Step 2: Mount the handler
+## Step 2: Database and env vars
 
-In your Worker entry, route `/api/auth/*` to the scaffolded handler (see the
-generated `lunora/auth/index.ts` README block). `createWorker` handles the rest
-of the RPC surface; the auth handler owns the better-auth endpoints.
+| Var                  | Secret | Notes                                                                             |
+| -------------------- | ------ | --------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET` | yes    | At least 32 chars (`openssl rand -base64 32`). Production: `wrangler secret put`. |
+| `BETTER_AUTH_URL`    | no     | Public base URL. better-auth uses it for callbacks and cookies.                   |
+| `MAIL_FROM`          | no     | Sender for verification and reset mail.                                           |
 
-## Step 3: Env vars and the D1 database
+```bash
+wrangler d1 create my-app-db   # paste the returned id into the DB binding
+lunora doctor                  # flags a placeholder database_id
+```
 
-| Var                  | Secret | Notes                                                               |
-| -------------------- | ------ | ------------------------------------------------------------------- |
-| `BETTER_AUTH_SECRET` | yes    | Encryption secret, min 32 chars. `openssl rand -base64 32`.         |
-| `BETTER_AUTH_URL`    | no     | Public base URL, e.g. `http://localhost:8787` in dev, your domain.  |
-| `MAIL_FROM`          | no     | Sender for verification / reset mail. Captured in the dev Mail tab. |
+Don't declare the better-auth tables (`user`, `session`, `account`,
+`verification`) in `lunora/schema.ts`. better-auth owns them in D1. In dev the
+schema is auto-applied on the first `/api/auth/*` request. For production,
+pre-apply it with `compileMigrationsSql(auth.options)` piped to
+`wrangler d1 execute <db> --remote --file -`. The item README has the script.
+Re-run that migration after adding a plugin that brings its own tables, such as
+`organization` or `twoFactor`.
 
-Create the D1 database and paste its id into the `DB` binding in
-`wrangler.jsonc`:
+## Step 3: Wire the Worker
 
-```bash
-wrangler d1 create my-app-db
+There are two parts. `/api/auth/*` has to reach better-auth. `resolveIdentity`
+has to turn the session cookie into `ctx.auth`. If `resolveIdentity` is missing,
+sign-in still works but `ctx.auth.userId` stays `null` in every function.
+
+**Through the generated `defineApp` builder.** This is the default for
+templates. `.auth()` does both parts: it builds the instance lazily, runs
+`ensureMigrated`, dispatches `/api/auth/*` and sets `resolveIdentity`. A
+Vite-first app (`"main": "virtual:lunora/worker"`) has no entry file, so chain
+the call in the `lunora.config.ts` `app` hook. A hand-written entry
+(`src/server.ts`) chains it on `defineApp()` directly:
+
+```ts
+// lunora.config.ts
+import type { AppBuilder, LunoraConfig } from "./lunora/_generated/app";
+// Move the object `buildAuth` passes to `createAuth` (minus `database`; the
+// builder supplies the D1 adapter) into an exported `authOptions(env)` in
+// lunora/auth/index.ts, and have `buildAuth` spread it too.
+import { authOptions } from "./lunora/auth/index.js";
+
+interface Env {
+    BETTER_AUTH_SECRET: string;
+    BETTER_AUTH_URL: string;
+    DB: D1Database;
+}
+
+export default {
+    target: "cloudflare",
+    app: (app: AppBuilder<Env>): AppBuilder<Env> =>
+        app.auth({
+            d1: (env) => env.DB,
+            options: (env) => authOptions(env),
+        }),
+} satisfies LunoraConfig<Env>;
 ```
 
-The better-auth schema (user/session/account/verification tables) is **not**
-declared in `lunora/schema.ts` — it is managed by better-auth in D1. In dev,
-`ensureMigrated(auth)` auto-applies it; in production prefer
-`compileMigrationsSql(auth.options)` piped to `wrangler d1 execute`. Run
-`lunora doctor` to confirm the `DB` binding has a real `database_id` (not a
-placeholder).
+Reuse the scaffold's options rather than retyping a subset: a hand-written
+`{ emailAndPassword: { enabled: true } }` drops `requireEmailVerification`,
+`sendResetPassword` and `sendVerificationEmail`, so users sign in unverified and
+no verification or reset mail goes out.
+
+`.auth()` appears on the builder only after codegen sees `@lunora/auth`
+installed, so run `lunora codegen` first.
 
-Verification and password-reset emails are **captured into the Lunora Studio
-Mail tab** in dev with zero email setup. For real delivery, `lunora registry add
-mail` (adds the `SEND_EMAIL` binding) or set `RESEND_API_KEY`.
+**Hand-rolled `createWorker` entry.** Call the scaffolded `mountAuth` first in
+`fetch`, then hand every other request to the Lunora worker, which resolves the
+identity:
 
-## Step 4: Add a provider (optional)
+```ts
+import type { AuthEnv } from "../../lunora/auth/index.js";
+import { getAuth, mountAuth } from "../../lunora/auth/index.js";
+
+const worker = createWorker({
+    resolveIdentity: async (req, env) => {
+        const session = await getAuth(env as AuthEnv).api.getSession({ headers: req.headers });
+        return session?.user ? { userId: session.user.id } : null;
+    },
+    // …
+});
+
+export default {
+    async fetch(request: Request, env: AuthEnv, ctx: ExecutionContext): Promise<Response> {
+        const authResponse = await mountAuth(env, request);
+        if (authResponse) return authResponse;
+        return worker.fetch(request, env, ctx); // RPC, WebSocket, everything else
+    },
+};
+```
 
-Each provider item builds on the base `auth` item (`requires: ["auth"]`):
+## Step 4: Providers and add-ons (optional)
+
+Each of these items requires the base `auth` item and installs it if it is
+missing:
 
 ```bash
-lunora registry add auth-clerk        # Clerk via better-auth genericOAuth
-lunora registry add auth-auth0        # Auth0 via better-auth genericOAuth
-lunora registry add auth-magic-link   # passwordless magic-link (mail)
-lunora registry add auth-otp          # passwordless email one-time-password
+lunora add auth-clerk        # Clerk OIDC (genericOAuth): CLERK_CLIENT_ID / _SECRET / CLERK_ISSUER_URL
+lunora add auth-auth0        # Auth0 OIDC: AUTH0_CLIENT_ID / _SECRET / AUTH0_DOMAIN
+lunora add auth-magic-link   # passwordless link, sent via @lunora/mail
+lunora add auth-otp          # email one-time code, sent via @lunora/mail
+lunora add auth-emails       # styled React templates for the auth mails (renderEmail)
+lunora add auth-ui           # copy-in screens; framework auto-detected (no React Native port)
 ```
 
-Add the base `auth` item first (or let the registry resolve the `requires`
-dependency). OAuth items need the provider's client id/secret added to
-`.dev.vars`.
+The provider items copy a file into `lunora/auth/` but don't register it
+anywhere. Add the plugin to the `plugins` array yourself, in `buildAuth` or in
+`.auth({ options })`. For example, `plugins: [uiConfig(), clerk(env)]` with
+`import { clerk } from "./clerk.js"`. The other exports are `auth0`,
+`magicLinkPlugin` and `emailOtpPlugin`. The OAuth callback URL is
+`<BETTER_AUTH_URL>/api/auth/oauth2/callback/<clerk|auth0>`.
 
 ## Step 5: Use the session
 
 ### In functions
 
-The runtime resolves the session and exposes the user on every context:
-
 ```ts
-import { LunoraError, mutation, v } from "@lunora/server";
+import { LunoraError } from "lunorash/server";
+
+import { mutation, v } from "#lunora/_generated/server.js";
 
 export const createDocument = mutation.input({ title: v.string() }).mutation(async ({ ctx, args: { title } }) => {
     if (!ctx.auth.userId) {
@@ -114,27 +199,41 @@ export const createDocument = mutation.input({ title: v.string() }).mutation(asy
 });
 ```
 
-For richer checks (org membership, roles), compose `withAuthPlugins(auth)` and
-call the better-auth server API — see the scaffolded `lunora/auth/index.ts`.
+`ctx.auth.getIdentity()` returns the full session claims, such as email and
+name. For org or role checks, compose `withAuthPlugins(auth)` and call the
+better-auth server API.
+
+### In the client
 
-### In the UI (React)
+The default is a better-auth **cookie session**. `LunoraClient` needs no token,
+so don't call `setToken` / `setAuthToken` for it. Sign in with the better-auth
+client. Build that client with `createLunoraAuthClient`, which installs
+`lunoraSessionSync()`. That plugin tells every open `LunoraClient`, including
+ones in other tabs, to re-resolve the session after sign-in or sign-out. Without
+it, live queries keep serving the previous user's rows. If you call
+`createAuthClient` yourself, add `lunoraSessionSync()` to its plugins.
 
 ```tsx
-import { Authenticated, Unauthenticated, useAuth } from "@lunora/react";
+import { createLunoraAuthClient } from "@lunora/auth/plugins/client";
+import { Authenticated, AuthLoading, Unauthenticated, useAuth } from "@lunora/react";
+import { createAuthClient } from "better-auth/react";
 
-function Account() {
-    const { user, signIn, signOut } = useAuth();
+export const authClient = createLunoraAuthClient(createAuthClient);
+
+function Account({ email, password }: { email: string; password: string }) {
+    const { user } = useAuth(); // { setToken, status, token, user }
 
     return (
         <>
+            <AuthLoading>…</AuthLoading>
             <Authenticated>
                 <span>Signed in as {user?.email}</span>
-                <button type="button" onClick={() => signOut()}>
+                <button type="button" onClick={() => authClient.signOut()}>
                     Sign out
                 </button>
             </Authenticated>
             <Unauthenticated>
-                <button type="button" onClick={() => signIn()}>
+                <button type="button" onClick={() => authClient.signIn.email({ email, password })}>
                     Sign in
                 </button>
             </Unauthenticated>
@@ -143,28 +242,31 @@ function Account() {
 }
 ```
 
-`@lunora/react` also exports `AuthLoading` and `useAuthState` for the loading
-window before the session resolves.
-
-## Common Pitfalls
-
-1. **Declaring better-auth tables in `lunora/schema.ts`.** They live in D1 and
-   are managed by better-auth — do not add them to `defineSchema`.
-2. **Placeholder `database_id`.** The `DB` binding ships with a placeholder;
-   `wrangler d1 create` + paste the id, then `lunora doctor` to confirm.
-3. **Missing/short `BETTER_AUTH_SECRET`.** better-auth needs ≥32 chars;
-   `@lunora/auth` surfaces a clear error when it is absent.
-4. **Expecting prod email to "just work".** Dev captures mail into the Studio;
-   production needs `mail` (the `SEND_EMAIL` binding) or `RESEND_API_KEY` and a
-   verified sender domain.
-
-## Checklist
-
-- [ ] `lunora registry add auth` run, `pnpm install` done.
-- [ ] Auth handler mounted in the Worker entry.
-- [ ] `BETTER_AUTH_SECRET` / `BETTER_AUTH_URL` / `MAIL_FROM` set in `.dev.vars`.
-- [ ] D1 database created and its id pasted into the `DB` binding (`lunora
-doctor` clean).
-- [ ] Provider item added if needed (Clerk / Auth0 / magic link / OTP).
-- [ ] Functions gate on `ctx.auth.userId`; UI uses the auth gates/`useAuth`.
-- [ ] Verified sign-in → session → an authenticated query round-trip.
+A client plugin toggle such as `{ plugins: { twoFactor: true } }` only adds
+the client half. Register the matching server plugin (`twoFactor()` from
+`@lunora/auth/plugins`) in `buildAuth`'s `plugins` too, or its endpoints don't
+exist.
+
+`setToken` is only for bearer-token setups, such as React Native or a JWT from
+an external IdP.
+
+Branch on `status`, not on `user === null`. `status` takes one of four values:
+`"unauthenticated"`, `"loading"`, `"authenticated"` or `"unreachable"`. The gates
+in `@lunora/vue`, `@lunora/solid`, `@lunora/svelte` and `@lunora/angular` use the
+same four. `"unreachable"` means a credential is held but the session endpoint
+failed, for example on an offline reload. The gates treat it as authenticated,
+yet `user` can still be `null` at that point. A UI that reads that `null` as
+"signed out" shows a signed-in user the signed-out screen. The full contract is
+documented on `AuthStatus` in `@lunora/client/auth`.
+
+## Pitfalls
+
+- **Sign-in rejected right after sign-up.** The scaffold sets `requireEmailVerification: true`, so the user has to open the verification link first. In dev, that link is in the Studio Mail tab.
+- **Mail in production.** Dev captures mail into the Studio. In production with no `MAIL_FROM`, the scaffold throws rather than logging the link. Auth links are bearer credentials, so this is intentional. Production needs `lunora add email` (the `SEND_EMAIL` binding) or `RESEND_API_KEY`, plus a verified sender domain. See `lunora-setup-mail`.
+- **Unauthenticated storage or other items.** Items that call `requireOwner` throw `UNAUTHORIZED` until `resolveIdentity` is wired (Step 3).
+
+## Verify
+
+1. Run `lunora doctor`. It should report no placeholder `database_id`.
+2. Run `lunora dev`. Sign up, open the verification link from the Studio Mail tab, then sign in.
+3. Call a query that returns `ctx.auth.userId`. It should return the user's id, not `null`.