@exposify/next 0.0.2 → 0.0.4

package/README.md

@@ -6,7 +6,7 @@ your own app.
 
 ```sh
 npm install @exposify/next
-npx exposify-next setup   # pick the endpoints, get the route file to create
+npx @exposify/next setup   # pick the endpoints, get the route file to create
 ```
 
 Or by hand, in two files:
@@ -32,7 +32,7 @@ export { handler as GET, handler as POST, handler as DELETE };
 build` starts, and keeps it current in dev as route files change. It holds
 the route table, your Server Actions, your docs (`README.md`, `docs/**/*.md`) for `search_docs`,
 and `exposify.descriptions.json`'s texts, so nothing is read from disk at
-runtime. Commit it or ignore it; `npx exposify-next generate` writes it too.
+runtime. Commit it or ignore it; `npx @exposify/next generate` writes it too.
 
 ## Which routes become tools
 
@@ -79,6 +79,22 @@ it. The MCP client's address and host are forwarded as
 - **Vercel Deployment Protection** blocks those requests on protected
   previews: set `VERCEL_AUTOMATION_BYPASS_SECRET` (Vercel's "Protection
   Bypass for Automation") and it's sent as `x-vercel-protection-bypass`.
+  Without it, a tool call fails with an error that says so. An MCP client
+  outside Vercel reaches a protected preview with
+  `?x-vercel-protection-bypass=<secret>` on the MCP URL.
+- **The agent's address:** some hosts (Vercel) replace `x-forwarded-for` on
+  these requests with their own. Where a route rate-limits or logs by IP,
+  use `agentIp()`: the agent's address on a tool call (signed with
+  `EXPOSIFY_KEY`, so it can't be forged), the usual `x-forwarded-for`
+  otherwise.
+
+  ```ts
+  import { agentIp } from "@exposify/next";
+
+  export async function POST(req: Request) {
+    const ip = await agentIp(req);
+  }
+  ```
 - `basePath` and `trailingSlash` from `next.config` are applied.
 - `rateLimit` / `rateWindowMs`: MCP requests per client address per window
   (default 60 per 60 s), in memory and per instance.
@@ -136,6 +152,42 @@ was found. Name another one with `aiReady(exposify, { login: "signIn" })`
 (an action's export name) or `{ login: { path: "/api/login", fields:
 ["email", "password"] } }`, or turn it off with `login: false`.
 
+**Logins in two steps.** If your login asks for a code next (two-factor:
+it sets a pending cookie and redirects to a code page, or answers
+`{ mfaRequired: true }`), the form asks for the code too and runs your second
+step (a Server Action or route named like `verify`, `2fa` or `otp` that takes
+one code and sets the session) with the cookies the first step set. The
+password isn't kept between the two forms. Passwordless logins work the same
+way: an email or phone number, then a code, with "Send a new code". Name the
+second step with `loginVerify: "verifyCode"` (or `{ path, fields }`), or turn
+it off with `loginVerify: false`. Magic links aren't supported; an email that
+also carries a code is.
+
+**Supabase Auth (`@supabase/ssr`).** The generator looks for Supabase, not
+for a login form: it finds your `signInWithPassword`, `signInWithOtp`,
+`signInWithOAuth` and `<Auth />` calls and whether each runs in the browser
+or on your server.
+
+- Signed in from the browser (as in Supabase's own starter), or nowhere it
+  could find: AI assistants sign in to your Supabase project directly. A
+  password goes on the form at `/mcp/login`, from your app's server straight
+  to Supabase; social logins and email codes go through Supabase on
+  Exposify's page; a user with an authenticator app enters its code too.
+- Signed in from a Server Action or route handler: that's your login, and
+  the form runs it, since it may check more than Supabase does. Social
+  logins still go to Supabase directly.
+
+Either way, tool calls carry the `sb-<ref>-auth-token` cookie your server
+reads, and Exposify refreshes the session before supabase-js would. The
+route reads `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`
+(or `_ANON_KEY`); pass `aiReady(exposify, { supabase: { url, key } })` to
+name them, or `supabase: false` to turn it off. The dashboard shows what was
+found and has the switch for passwords. `inspect` says which way it went and
+why; `npx @exposify/next test-sign-in` signs in on your running app and checks
+a protected page accepts the cookie. `@supabase/auth-helpers-nextjs` (an
+older cookie format) isn't supported, and apps on `@supabase/supabase-js`
+alone keep their session in the browser, where the server never sees it.
+
 **No login found, and no sign-in method in the dashboard?** Then agents use
 your app signed out: `/mcp` doesn't ask them to sign in, and your own checks
 decide what they can do. The startup log says which it is
@@ -286,8 +338,8 @@ errors; the thrown message stays in your server log.
 
 ## CLI
 
-`npx exposify-next setup | inspect | describe | generate`. The first three
-are the same as `exposify-express`'s; the scan reads your route files
+`npx @exposify/next setup | inspect | describe | generate`. The first three
+are the same as `@exposify/express`'s; the scan reads your route files
 instead of booting the app.
 
 Server Actions get their own rows: