@helloleo/plugins 0.2.0-beta.7 → 0.2.0

package/dist/index.js

@@ -24964,7 +24964,7 @@ function authLibTs(providers) {
   const oauth = providers.filter((p) => p !== "password");
   const envFields = [
     "BETTER_AUTH_SECRET?: string",
-    "BETTER_AUTH_URL?: string",
+    "HELLOLEO_URL?: string",
     ...oauth.flatMap((p) => {
       const prefix = p.toUpperCase();
       return [
@@ -25011,7 +25011,7 @@ function buildAuth() {
 
   return betterAuth({
     secret: e.BETTER_AUTH_SECRET,
-    baseURL: e.BETTER_AUTH_URL,
+    baseURL: e.HELLOLEO_URL || 'http://localhost:3000',
     database: drizzleAdapter(db, { provider: 'sqlite', schema }),
     emailAndPassword: {
       enabled: ${hasPassword},
@@ -25438,8 +25438,9 @@ var setupAuthentication = tool({
     const schemaAppended = await appendAuthTables(dir);
     const depsAdded = await addAuthDependencies(dir);
     const envLines = [
-      "  - dev (.env): BETTER_AUTH_SECRET=<random>, BETTER_AUTH_URL=http://localhost:3000",
-      "  - prod: `wrangler secret put BETTER_AUTH_SECRET`, and BETTER_AUTH_URL as a var in wrangler.jsonc"
+      "  - dev (.env): BETTER_AUTH_SECRET=<random>",
+      "  - prod: `wrangler secret put BETTER_AUTH_SECRET`",
+      "  - HELLOLEO_URL is auto-injected by the platform (preview + production) -- nothing to set for baseURL"
     ];
     for (const p of oauth) {
       const prefix = p.toUpperCase();
@@ -25477,247 +25478,619 @@ var SetupAuthenticationPlugin = async () => {
   };
 };
 // src/tools/setup-netsuite.ts
-import { mkdir as mkdir2 } from "fs/promises";
+import { mkdir as mkdir2, readFile as readFile3 } from "fs/promises";
 import path7 from "path";
-function netsuiteTs() {
+function schemaAppend() {
+  return `
+// --- NetSuite OAuth (added by setup_netsuite) ---
+// Short-lived PKCE + return-to state between /auth/netsuite/start and its
+// callback. Single-use: the callback deletes the row after reading it.
+export const netsuiteFlows = sqliteTable('netsuite_flows', {
+  flowId: text('flow_id').primaryKey(),
+  codeVerifier: text('code_verifier').notNull(),
+  returnTo: text('return_to').notNull(),
+  createdAt: integer('created_at')
+    .notNull()
+    .default(sql\`(unixepoch())\`),
+})
+
+// Opaque session id -> NetSuite tokens. Tokens stay server-side; the browser
+// only ever holds the sid (sent as a bearer).
+export const netsuiteSessions = sqliteTable('netsuite_sessions', {
+  sid: text('sid').primaryKey(),
+  accountId: text('account_id').notNull(),
+  accessToken: text('access_token').notNull(),
+  refreshToken: text('refresh_token'),
+  expiresAt: integer('expires_at'),
+  userId: text('user_id'),
+  email: text('email'),
+  createdAt: integer('created_at')
+    .notNull()
+    .default(sql\`(unixepoch())\`),
+})
+`;
+}
+function netsuiteServerTs() {
   return `/*
- * NetSuite OAuth client helper (bearer-token-in-fragment).
+ * NetSuite runtime OAuth -- server side (TanStack Start server routes).
  *
- * Two NetSuite Integration Records back this:
- *   1. MCP (scope: mcp)            -- used by HelloLeo at build time.
- *   2. Runtime (scope: rest_webservices) -- used here at sign-in time.
- * Runtime credentials live as HelloLeo Cloud secrets on the project's Worker
- * (env.NETSUITE_ACCOUNT_ID / _CLIENT_ID / _CLIENT_SECRET). They never reach
- * the browser. Cookies are NOT used -- frontend \u2194 Worker are cross-site
- * (e.g. *.helloleo.dev <-> *.workers.dev) and Chrome partitions / drops
- * third-party cookies in the HelloLeo preview iframe.
+ * Runs wherever the app runs: \`vite dev\` (workerd) in the Fly preview machine
+ * in dev, and the published Cloudflare Worker in prod. There is no separate
+ * backend Worker -- these helpers back the /auth/netsuite/* + /api/me routes.
  *
- * Flow:
- *   1. User clicks "Sign in with NetSuite".
- *   2. Browser navigates to the Worker /auth/netsuite/start.
- *   3. Worker redirects to NetSuite's OAuth UI with PKCE.
- *   4. NetSuite redirects back to the Worker /auth/netsuite/callback.
- *   5. Worker exchanges the code, mints a session id, then redirects to
- *      <return_to>#nssid=<sid>. URL fragments stay in the browser only.
- *   6. This module reads the fragment on load, stashes the sid in
- *      sessionStorage, and sends it as Authorization: Bearer on every
- *      Worker call.
- *
- * NEVER use a hardcoded password gate. NEVER use sessionStorage as the
- * authoritative auth state -- the only acceptable check is /api/me on the
- * Worker. sessionStorage here is just a cache of the bearer token.
+ * Config is read from the Cloudflare env binding via @helloleo/runtime.
+ * Set NETSUITE_ACCOUNT_ID / _CLIENT_ID / _CLIENT_SECRET (secret optional for a
+ * PKCE public client) and optional PUBLIC_APP_URL as HelloLeo Cloud secrets
+ * (prod) or dev vars (preview). They never reach the browser.
  */
+import { eq } from 'drizzle-orm'
+import { env as runtimeEnv } from '@helloleo/runtime'
+import { db } from '#/db'
+import { netsuiteSessions } from '#/db/schema'
 
-export const WORKER_URL = import.meta.env.VITE_WORKER_URL ?? '';
-const TOKEN_KEY = 'nssid';
+interface NsEnv {
+  NETSUITE_ACCOUNT_ID?: string
+  NETSUITE_CLIENT_ID?: string
+  NETSUITE_CLIENT_SECRET?: string
+  PUBLIC_APP_URL?: string
+  HELLOLEO_URL?: string
+}
+const nsEnv = runtimeEnv as unknown as NsEnv
 
-// Capture-and-strip the #nssid=... fragment as early as possible so URLs
-// shown to the user stay clean. Runs once at module load.
-(function bootstrapTokenFromHash() {
-  if (typeof window === 'undefined') return;
-  const hash = window.location.hash.replace(/^#/, '');
-  if (!hash) return;
-  const params = new URLSearchParams(hash);
-  const sid = params.get(TOKEN_KEY);
-  if (sid) {
-    try { sessionStorage.setItem(TOKEN_KEY, sid); } catch {}
-    params.delete(TOKEN_KEY);
-    const remaining = params.toString();
-    const newHash = remaining ? '#' + remaining : '';
-    window.history.replaceState(null, '', window.location.pathname + window.location.search + newHash);
+// Runtime record scope. The app signs end-users in for REST/SuiteQL.
+export const SCOPE = 'rest_webservices'
+const REFRESH_LEEWAY_SECONDS = 60
+
+export function requireConfig() {
+  const accountId = nsEnv.NETSUITE_ACCOUNT_ID
+  const clientId = nsEnv.NETSUITE_CLIENT_ID
+  if (!accountId || !clientId) {
+    throw new Error(
+      'NetSuite not configured: set NETSUITE_ACCOUNT_ID and NETSUITE_CLIENT_ID (and NETSUITE_CLIENT_SECRET for a confidential client) as HelloLeo Cloud secrets / dev vars.',
+    )
+  }
+  return { accountId, clientId, clientSecret: nsEnv.NETSUITE_CLIENT_SECRET || '' }
+}
+
+// Account id -> DNS host form: lowercase, underscores to hyphens.
+function host(accountId: string) {
+  return accountId.trim().toLowerCase().replace(/_/g, '-')
+}
+export function authorizeUrl(accountId: string) {
+  return \`https://\${host(accountId)}.app.netsuite.com/app/login/oauth2/authorize.nl\`
+}
+export function tokenUrl(accountId: string) {
+  return \`https://\${host(accountId)}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token\`
+}
+export function restBase(accountId: string) {
+  return \`https://\${host(accountId)}.suitetalk.api.netsuite.com\`
+}
+
+function stripTrailingSlash(s: string) {
+  return s.endsWith('/') ? s.slice(0, -1) : s
+}
+
+// Public origin of THIS app, used to build the redirect URI. Prefer an explicit
+// PUBLIC_APP_URL; else derive from the request (honouring the preview proxy's
+// forwarded headers). Must match a redirect URI registered on the NetSuite
+// Integration Record exactly.
+export function appOrigin(request: Request) {
+  // 1) Explicit override wins (set by the platform per environment).
+  if (nsEnv.PUBLIC_APP_URL) return stripTrailingSlash(nsEnv.PUBLIC_APP_URL)
+  // 2) HELLOLEO_URL is injected on every deploy (the app's canonical origin), so
+  //    it's set even when the NetSuite wizard's PUBLIC_APP_URL pin wasn't.
+  if (nsEnv.HELLOLEO_URL) return stripTrailingSlash(nsEnv.HELLOLEO_URL)
+  // 3) Preview/prod proxies rewrite Host, so trust the forwarded/original host
+  //    they set (HelloLeo's nginx sends X-Original-Host) \u2014 that's the public URL
+  //    the browser loaded, not an internal upstream host.
+  const url = new URL(request.url)
+  const proto = request.headers.get('x-forwarded-proto') || url.protocol.replace(':', '')
+  const hostHeader =
+    request.headers.get('x-forwarded-host') ||
+    request.headers.get('x-original-host') ||
+    url.host
+  return \`\${proto}://\${hostHeader}\`
+}
+export function redirectUri(request: Request) {
+  return \`\${appOrigin(request)}/auth/netsuite/callback\`
+}
+
+// Coerce ?return_to= to our OWN origin. The callback appends the session bearer
+// as a #nssid=... fragment; an off-origin return_to would leak that live
+// credential to an attacker-controlled page (open-redirect -> token theft).
+export function safeReturnTo(request: Request, raw: string | null): string {
+  const origin = appOrigin(request)
+  if (!raw) return origin
+  try {
+    const u = new URL(raw, origin)
+    return u.origin === origin ? u.toString() : origin
+  } catch {
+    return origin
   }
-})();
+}
+
+// --- PKCE (Web Crypto: works on workerd and Node) ---
+function b64url(bytes: Uint8Array) {
+  let s = ''
+  for (const b of bytes) s += String.fromCharCode(b)
+  return btoa(s).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '')
+}
+export async function pkce() {
+  const verifier = b64url(crypto.getRandomValues(new Uint8Array(48)))
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
+  const challenge = b64url(new Uint8Array(digest))
+  return { verifier, challenge }
+}
+
+interface TokenResponse {
+  access_token?: string
+  refresh_token?: string
+  expires_in?: number
+  error?: string
+  error_description?: string
+}
+
+// Confidential client -> HTTP Basic. Public (PKCE-only) -> client_id in body.
+function authHeaders(clientId: string, clientSecret: string, params: Record<string, string>) {
+  const headers: Record<string, string> = { 'Content-Type': 'application/x-www-form-urlencoded' }
+  if (clientSecret) headers.Authorization = 'Basic ' + btoa(\`\${clientId}:\${clientSecret}\`)
+  else params.client_id = clientId
+  return headers
+}
+
+// POST the token endpoint and parse tolerantly. NetSuite returns JSON for both
+// success and OAuth errors, but a gateway (502/504) can return HTML -- never let
+// res.json() throw into the route handler (that would surface as an opaque 500
+// instead of a clean "token exchange failed").
+async function postToken(
+  accountId: string,
+  params: Record<string, string>,
+  headers: Record<string, string>,
+): Promise<TokenResponse> {
+  let res: Response
+  try {
+    res = await fetch(tokenUrl(accountId), { method: 'POST', headers, body: new URLSearchParams(params) })
+  } catch (e) {
+    return { error: 'network_error', error_description: String(e) }
+  }
+  const text = await res.text()
+  let data: TokenResponse = {}
+  try {
+    data = JSON.parse(text) as TokenResponse
+  } catch {
+    // non-JSON body (e.g. gateway HTML) -- leave data empty, fall through
+  }
+  if (!res.ok && !data.error) {
+    data = { error: 'token_request_failed', error_description: 'HTTP ' + res.status }
+  }
+  return data
+}
+
+export async function exchangeCode(request: Request, code: string, verifier: string) {
+  const { accountId, clientId, clientSecret } = requireConfig()
+  const params: Record<string, string> = {
+    grant_type: 'authorization_code',
+    code,
+    redirect_uri: redirectUri(request),
+    code_verifier: verifier,
+  }
+  return postToken(accountId, params, authHeaders(clientId, clientSecret, params))
+}
+
+async function refreshToken(refresh: string) {
+  const { accountId, clientId, clientSecret } = requireConfig()
+  const params: Record<string, string> = { grant_type: 'refresh_token', refresh_token: refresh }
+  return postToken(accountId, params, authHeaders(clientId, clientSecret, params))
+}
+
+export interface NsSession {
+  sid: string
+  accountId: string
+  accessToken: string
+  refreshToken: string | null
+  expiresAt: number | null
+  userId: string | null
+  email: string | null
+}
+
+// Load a session by sid, transparently refreshing the access token when it's
+// within the leeway of expiry. Returns null if unknown or unrefreshable.
+export async function getSession(sid: string): Promise<NsSession | null> {
+  if (!sid) return null
+  const rows = await db.select().from(netsuiteSessions).where(eq(netsuiteSessions.sid, sid)).limit(1)
+  const s = rows[0]
+  if (!s) return null
+  const now = Math.floor(Date.now() / 1000)
+  // A missing expiry is treated as EXPIRED (force a refresh) rather than trusting
+  // the token forever -- NetSuite normally sends expires_in, so this is defensive.
+  const expired = s.expiresAt == null ? true : now + REFRESH_LEEWAY_SECONDS >= s.expiresAt
+  if (expired) {
+    // Token expired (or about to). It MUST refresh; if it can't, the session is
+    // dead \u2014 delete it and return null so /api/me reports signed-out and the user
+    // re-auths, rather than a "logged in" app whose every NetSuite call 401s.
+    if (!s.refreshToken) { await deleteSession(sid); return null }
+    const tok = await refreshToken(s.refreshToken)
+    if (!tok.access_token) { await deleteSession(sid); return null }
+    const expiresAt = now + (tok.expires_in || 3600)
+    const refreshTok = tok.refresh_token ?? s.refreshToken
+    await db
+      .update(netsuiteSessions)
+      .set({ accessToken: tok.access_token, refreshToken: refreshTok, expiresAt })
+      .where(eq(netsuiteSessions.sid, sid))
+    return { ...s, accessToken: tok.access_token, refreshToken: refreshTok, expiresAt }
+  }
+  return s
+}
+
+export async function deleteSession(sid: string) {
+  if (sid) await db.delete(netsuiteSessions).where(eq(netsuiteSessions.sid, sid))
+}
+
+export function bearer(request: Request) {
+  const h = request.headers.get('authorization') || ''
+  return h.startsWith('Bearer ') ? h.slice(7) : ''
+}
+
+/**
+ * Call NetSuite REST / SuiteQL for the signed-in session. Use this from your
+ * data routes (src/routes/api/*). \`path\` is relative to the account's
+ * suitetalk host, e.g. '/services/rest/query/v1/suiteql'. Returns the raw
+ * fetch Response (401 if the sid is unknown). Access token is auto-refreshed.
+ */
+export async function netsuiteFetch(sid: string, path: string, init: RequestInit = {}): Promise<Response> {
+  const session = await getSession(sid)
+  if (!session) return new Response(JSON.stringify({ error: 'unauthorized' }), { status: 401 })
+  const url = path.startsWith('http') ? path : \`\${restBase(session.accountId)}\${path}\`
+  const headers = new Headers(init.headers)
+  headers.set('Authorization', \`Bearer \${session.accessToken}\`)
+  if (init.body && !headers.has('Content-Type')) headers.set('Content-Type', 'application/json')
+  return fetch(url, { ...init, headers })
+}
+`;
+}
+function startRouteTs() {
+  return `import { createFileRoute } from '@tanstack/react-router'
+import { db } from '#/db'
+import { netsuiteFlows } from '#/db/schema'
+import {
+  authorizeUrl,
+  pkce,
+  redirectUri,
+  requireConfig,
+  safeReturnTo,
+  SCOPE,
+} from '#/lib/netsuite-server'
+
+// GET /auth/netsuite/start -- begin the NetSuite OAuth (PKCE) flow.
+export const Route = createFileRoute('/auth/netsuite/start')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const { accountId, clientId } = requireConfig()
+        const url = new URL(request.url)
+        // Same-origin only: the callback returns the bearer in a URL fragment.
+        const returnTo = safeReturnTo(request, url.searchParams.get('return_to'))
+
+        const { verifier, challenge } = await pkce()
+        const flowId = crypto.randomUUID()
+        await db.insert(netsuiteFlows).values({ flowId, codeVerifier: verifier, returnTo })
+
+        const authorize = new URL(authorizeUrl(accountId))
+        authorize.searchParams.set('response_type', 'code')
+        authorize.searchParams.set('client_id', clientId)
+        authorize.searchParams.set('redirect_uri', redirectUri(request))
+        authorize.searchParams.set('scope', SCOPE)
+        authorize.searchParams.set('state', flowId)
+        authorize.searchParams.set('code_challenge', challenge)
+        authorize.searchParams.set('code_challenge_method', 'S256')
+
+        return new Response(null, { status: 302, headers: { Location: authorize.toString() } })
+      },
+    },
+  },
+})
+`;
+}
+function callbackRouteTs() {
+  return `import { createFileRoute } from '@tanstack/react-router'
+import { eq } from 'drizzle-orm'
+import { db } from '#/db'
+import { netsuiteFlows, netsuiteSessions } from '#/db/schema'
+import { exchangeCode, requireConfig } from '#/lib/netsuite-server'
+
+// GET /auth/netsuite/callback -- exchange the code, mint a session, hand the
+// bearer back to the SPA via the URL fragment (#nssid=...). The fragment
+// survives the HelloLeo preview iframe, where third-party cookies are dropped.
+export const Route = createFileRoute('/auth/netsuite/callback')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const url = new URL(request.url)
+        const err = url.searchParams.get('error')
+        if (err) return new Response(\`NetSuite authorization failed: \${err}\`, { status: 400 })
+
+        const code = url.searchParams.get('code')
+        const state = url.searchParams.get('state')
+        if (!code || !state) return new Response('Missing code or state', { status: 400 })
+
+        const rows = await db
+          .select()
+          .from(netsuiteFlows)
+          .where(eq(netsuiteFlows.flowId, state))
+          .limit(1)
+        const flow = rows[0]
+        if (!flow) return new Response('Unknown or expired flow -- start again', { status: 400 })
+        // Single-use: burn the flow row immediately.
+        await db.delete(netsuiteFlows).where(eq(netsuiteFlows.flowId, state))
+        // Reject stale flows: the PKCE verifier must not stay valid indefinitely
+        // for an abandoned or leaked authorize URL (createdAt is unixepoch seconds).
+        const nowSec = Math.floor(Date.now() / 1000)
+        if (flow.createdAt && nowSec - flow.createdAt > 600) {
+          return new Response('Flow expired -- start again', { status: 400 })
+        }
+
+        const tok = await exchangeCode(request, code, flow.codeVerifier)
+        if (!tok.access_token) {
+          return new Response(
+            \`Token exchange failed: \${tok.error_description || tok.error || 'unknown error'}\`,
+            { status: 400 },
+          )
+        }
+
+        const sid = crypto.randomUUID()
+        const now = Math.floor(Date.now() / 1000)
+        await db.insert(netsuiteSessions).values({
+          sid,
+          accountId: requireConfig().accountId,
+          accessToken: tok.access_token,
+          refreshToken: tok.refresh_token ?? null,
+          expiresAt: now + (tok.expires_in || 3600),
+        })
+
+        const dest = new URL(flow.returnTo)
+        dest.hash = \`nssid=\${sid}\`
+        return new Response(null, { status: 302, headers: { Location: dest.toString() } })
+      },
+    },
+  },
+})
+`;
+}
+function logoutRouteTs() {
+  return `import { createFileRoute } from '@tanstack/react-router'
+import { bearer, deleteSession } from '#/lib/netsuite-server'
+
+// POST /auth/netsuite/logout -- destroy the current session.
+export const Route = createFileRoute('/auth/netsuite/logout')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        await deleteSession(bearer(request))
+        return Response.json({ ok: true })
+      },
+    },
+  },
+})
+`;
+}
+function meRouteTs() {
+  return `import { createFileRoute } from '@tanstack/react-router'
+import { bearer, getSession } from '#/lib/netsuite-server'
+
+// GET /api/me -- resolve the bearer sid to a session. The ONLY authoritative
+// auth check; the client must never trust sessionStorage on its own.
+export const Route = createFileRoute('/api/me')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const session = await getSession(bearer(request))
+        if (!session) return Response.json({ authenticated: false })
+        return Response.json({
+          authenticated: true,
+          account_id: session.accountId,
+        })
+      },
+    },
+  },
+})
+`;
+}
+function configRouteTs() {
+  return `import { createFileRoute } from '@tanstack/react-router'
+import { env as runtimeEnv } from '@helloleo/runtime'
+import { appOrigin, redirectUri } from '#/lib/netsuite-server'
+
+// GET /auth/netsuite/config -- single source of truth for the redirect URI.
+// Whatever this returns is EXACTLY what /auth/netsuite/start sends NetSuite, so
+// show the user THIS value to register on their Integration Record. Never
+// hardcode or guess a callback URL.
+export const Route = createFileRoute('/auth/netsuite/config')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const e = runtimeEnv as unknown as {
+          NETSUITE_ACCOUNT_ID?: string
+          NETSUITE_CLIENT_ID?: string
+        }
+        return Response.json({
+          redirect_uri: redirectUri(request),
+          origin: appOrigin(request),
+          configured: Boolean(e.NETSUITE_ACCOUNT_ID && e.NETSUITE_CLIENT_ID),
+        })
+      },
+    },
+  },
+})
+`;
+}
+function netsuiteClientTs() {
+  return `/*
+ * NetSuite auth -- client (same-origin). The OAuth backend is THIS app's own
+ * server routes (src/routes/auth/netsuite/* + src/routes/api/me.ts), so every
+ * call is relative -- no separate Worker, no VITE_WORKER_URL.
+ *
+ * The browser only ever holds an opaque session id (sid), handed back in the
+ * callback's URL fragment (#nssid=...) so it survives the HelloLeo preview
+ * iframe (third-party cookies are partitioned/dropped there). The sid rides as
+ * Authorization: Bearer on every call; NetSuite tokens stay server-side. The
+ * only authoritative auth check is GET /api/me.
+ *
+ * NEVER use a password gate. NEVER trust sessionStorage as the auth state --
+ * it's just a cache of the bearer.
+ */
+const TOKEN_KEY = 'nssid'
+
+// Capture-and-strip #nssid=... as early as possible so URLs stay clean.
+;(function bootstrapTokenFromHash() {
+  if (typeof window === 'undefined') return
+  const hash = window.location.hash.replace(/^#/, '')
+  if (!hash) return
+  const params = new URLSearchParams(hash)
+  const sid = params.get(TOKEN_KEY)
+  if (sid) {
+    try {
+      sessionStorage.setItem(TOKEN_KEY, sid)
+    } catch {}
+    params.delete(TOKEN_KEY)
+    const rest = params.toString()
+    window.history.replaceState(
+      null,
+      '',
+      window.location.pathname + window.location.search + (rest ? '#' + rest : ''),
+    )
+  }
+})()
 
 export function getSessionToken(): string | null {
-  try { return sessionStorage.getItem(TOKEN_KEY); } catch { return null; }
+  try {
+    return sessionStorage.getItem(TOKEN_KEY)
+  } catch {
+    return null
+  }
 }
 
 export function signInWithNetSuite(returnTo: string = window.location.href) {
-  if (!WORKER_URL) {
-    throw new Error(
-      'VITE_WORKER_URL is not set. HelloLeo Cloud must be provisioned before sign-in works.',
-    );
-  }
-  const url = new URL(\`\${WORKER_URL.replace(/\\/$/, '')}/auth/netsuite/start\`);
-  url.searchParams.set('return_to', returnTo);
-  // The app usually renders inside the HelloLeo preview iframe. NetSuite's
-  // OAuth page sets X-Frame-Options: DENY, so navigating the iframe to the
-  // Worker (which 302s to NetSuite) ends up loading a page the browser
-  // refuses to render -- looks like "nothing happens" to the user. Navigate
-  // the top frame instead so the OAuth flow runs at the top level and the
-  // callback redirect lands on the same top frame, which then reads the
-  // #nssid= fragment. Use \`location.href =\` (NOT \`location.assign()\`):
-  // reading the \`.assign\` method off a cross-origin \`window.top.location\`
-  // throws a SecurityError, which would drop us into the same-frame fallback
-  // and load NetSuite inside the iframe (X-Frame-Options: DENY -> "refused to
-  // connect"). Assigning \`.href\` is a navigation, allowed cross-origin.
+  const url = new URL('/auth/netsuite/start', window.location.origin)
+  url.searchParams.set('return_to', returnTo)
+  // The app renders inside the HelloLeo preview iframe; /start 302s to
+  // NetSuite, whose OAuth page sends X-Frame-Options: DENY. Navigate the TOP
+  // frame so the flow runs at top level and the callback lands there to read
+  // #nssid=. Assign .href (NOT .assign(): reading .assign off a cross-origin
+  // window.top.location throws, dropping us into the iframe fallback ->
+  // "refused to connect").
   try {
     if (window.top && window.top !== window) {
-      window.top.location.href = url.toString();
-      return;
+      window.top.location.href = url.toString()
+      return
     }
   } catch {
-    /* top window not accessible \u2014 fall through to same-frame navigation */
+    /* top window unreachable -- fall through to same-frame navigation */
   }
-  window.location.href = url.toString();
+  window.location.href = url.toString()
 }
 
 export interface NetSuiteSession {
-  authenticated: boolean;
-  account_id?: string;
-  user_id?: string;
-  email?: string;
+  authenticated: boolean
+  account_id?: string
 }
 
 export async function getNetSuiteSession(): Promise<NetSuiteSession> {
-  if (!WORKER_URL) return { authenticated: false };
-  const sid = getSessionToken();
-  if (!sid) return { authenticated: false };
-  const res = await fetch(\`\${WORKER_URL.replace(/\\/$/, '')}/api/me\`, {
-    headers: { Authorization: 'Bearer ' + sid },
-  });
-  if (!res.ok) return { authenticated: false };
-  const data = await res.json();
-  return { authenticated: Boolean(data?.account_id), ...data };
+  const sid = getSessionToken()
+  if (!sid) return { authenticated: false }
+  const res = await fetch('/api/me', { headers: { Authorization: 'Bearer ' + sid } })
+  if (!res.ok) return { authenticated: false }
+  const data = await res.json()
+  return { authenticated: Boolean(data?.authenticated), ...data }
 }
 
 export async function signOutNetSuite(): Promise<void> {
-  if (!WORKER_URL) return;
-  const sid = getSessionToken();
+  const sid = getSessionToken()
   if (sid) {
     try {
-      await fetch(\`\${WORKER_URL.replace(/\\/$/, '')}/auth/netsuite/logout\`, {
+      await fetch('/auth/netsuite/logout', {
         method: 'POST',
         headers: { Authorization: 'Bearer ' + sid },
-      });
+      })
     } catch {}
   }
-  try { sessionStorage.removeItem(TOKEN_KEY); } catch {}
-  window.location.reload();
+  try {
+    sessionStorage.removeItem(TOKEN_KEY)
+  } catch {}
+  window.location.reload()
 }
 
 /**
- * Helper for ALL other Worker calls (your dashboard endpoints, etc.).
- * Always go through this instead of bare fetch -- it injects the bearer
- * token and routes through the Worker so NetSuite tokens stay server-side.
+ * Fetch YOUR data routes (src/routes/api/*) with the bearer attached. Use this
+ * instead of bare fetch for authenticated calls.
  */
-export async function workerFetch(pathOrUrl: string, init: RequestInit = {}): Promise<Response> {
-  if (!WORKER_URL) throw new Error('VITE_WORKER_URL is not set');
-  const url = pathOrUrl.startsWith('http')
-    ? pathOrUrl
-    : \`\${WORKER_URL.replace(/\\/$/, '')}\${pathOrUrl.startsWith('/') ? '' : '/'}\${pathOrUrl}\`;
-  const sid = getSessionToken();
-  const headers = new Headers(init.headers ?? {});
-  if (sid) headers.set('Authorization', 'Bearer ' + sid);
-  return fetch(url, { ...init, headers });
-}
-`;
-}
-function signInButtonTsx() {
-  return `import { signInWithNetSuite } from '../../lib/netsuite';
-
-export function SignInWithNetSuite() {
-  return (
-    <button
-      onClick={() => signInWithNetSuite()}
-      className="inline-flex items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground shadow hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-    >
-      Sign in with NetSuite
-    </button>
-  );
-}
-`;
+export async function apiFetch(path: string, init: RequestInit = {}): Promise<Response> {
+  const sid = getSessionToken()
+  const headers = new Headers(init.headers)
+  if (sid) headers.set('Authorization', 'Bearer ' + sid)
+  return fetch(path, { ...init, headers })
 }
-function netsuiteLoginPageTsx() {
-  return `import { SignInWithNetSuite } from './SignInWithNetSuite';
 
 /**
- * Default unauthenticated landing page. Replaces any password gate.
- * Customise copy / imagery freely but keep <SignInWithNetSuite /> as the
- * only call-to-action -- it points to the Worker's /auth/netsuite/start.
+ * The exact redirect URI this app will send NetSuite, read from the server so
+ * it can never drift from what /auth/netsuite/start actually uses. Show it to
+ * whoever registers the Integration Record; never hardcode a callback URL.
  */
-export function LoginPage() {
-  return (
-    <div className="min-h-screen bg-background text-foreground flex">
-      <div className="hidden lg:flex lg:w-1/2 bg-primary text-primary-foreground p-12 flex-col justify-between">
-        <div className="text-xl font-semibold">NetSuite App</div>
-        <div>
-          <h1 className="text-4xl font-bold leading-tight">
-            Connect your NetSuite account
-          </h1>
-          <p className="mt-4 text-primary-foreground/80 max-w-md">
-            Sign in with your NetSuite credentials to access your data securely.
-            Tokens stay server-side on HelloLeo Cloud -- they never reach the
-            browser.
-          </p>
-        </div>
-        <div className="text-xs text-primary-foreground/60">
-          Powered by HelloLeo
-        </div>
-      </div>
-      <div className="flex-1 flex items-center justify-center px-6 py-12">
-        <div className="w-full max-w-sm space-y-6">
-          <div>
-            <h2 className="text-2xl font-semibold">Welcome</h2>
-            <p className="mt-2 text-sm text-muted-foreground">
-              Use the button below to sign in. You'll be redirected to NetSuite
-              to authorise access, then back here.
-            </p>
-          </div>
-          <SignInWithNetSuite />
-        </div>
-      </div>
-    </div>
-  );
+export async function getNetSuiteRedirectUri(): Promise<string | null> {
+  try {
+    const res = await fetch('/auth/netsuite/config')
+    if (!res.ok) return null
+    const data = await res.json()
+    return data?.redirect_uri ?? null
+  } catch {
+    return null
+  }
 }
 `;
 }
 function authTsx() {
-  return `import * as React from 'react';
+  return `import * as React from 'react'
 import {
   getNetSuiteSession,
   signInWithNetSuite,
   signOutNetSuite,
   type NetSuiteSession,
-} from './netsuite';
+} from './netsuite'
 
 /**
- * NetSuite auth context. Holds the current session (resolved from the Worker's
- * /api/me via getNetSuiteSession) and exposes sign-in / sign-out. The only
- * authoritative auth check is /api/me -- never trust sessionStorage directly.
+ * NetSuite auth context. Holds the session (resolved client-side from /api/me
+ * via getNetSuiteSession) and exposes sign-in / sign-out. /api/me is the only
+ * authoritative check -- never trust sessionStorage directly.
  */
 export interface NetSuiteAuthContextValue {
-  pending: boolean;
-  isAuthenticated: boolean;
-  session: NetSuiteSession | null;
-  signIn: () => void;
-  signOut: () => Promise<void>;
-  refresh: () => Promise<void>;
+  pending: boolean
+  isAuthenticated: boolean
+  session: NetSuiteSession | null
+  signIn: () => void
+  signOut: () => Promise<void>
+  refresh: () => Promise<void>
 }
 
-const NetSuiteAuthContext =
-  React.createContext<NetSuiteAuthContextValue | null>(null);
+const NetSuiteAuthContext = React.createContext<NetSuiteAuthContextValue | null>(null)
 
-export function NetSuiteAuthProvider({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  const [session, setSession] = React.useState<NetSuiteSession | null>(null);
-  const [pending, setPending] = React.useState(true);
+export function NetSuiteAuthProvider({ children }: { children: React.ReactNode }) {
+  const [session, setSession] = React.useState<NetSuiteSession | null>(null)
+  // Start pending on BOTH server and client render so SSR and first paint match
+  // (a spinner), avoiding a hydration mismatch. The effect (client-only)
+  // resolves it.
+  const [pending, setPending] = React.useState(true)
 
   const refresh = React.useCallback(async () => {
-    setPending(true);
+    setPending(true)
     try {
-      setSession(await getNetSuiteSession());
+      setSession(await getNetSuiteSession())
     } finally {
-      setPending(false);
+      setPending(false)
     }
-  }, []);
+  }, [])
 
   React.useEffect(() => {
-    refresh();
-  }, [refresh]);
+    refresh()
+  }, [refresh])
 
   const value: NetSuiteAuthContextValue = {
     pending,
@@ -25726,126 +26099,226 @@ export function NetSuiteAuthProvider({
     signIn: () => signInWithNetSuite(),
     signOut: signOutNetSuite,
     refresh,
-  };
+  }
 
-  return (
-    <NetSuiteAuthContext.Provider value={value}>
-      {children}
-    </NetSuiteAuthContext.Provider>
-  );
+  return <NetSuiteAuthContext.Provider value={value}>{children}</NetSuiteAuthContext.Provider>
 }
 
 export function useNetSuiteAuth(): NetSuiteAuthContextValue {
-  const ctx = React.useContext(NetSuiteAuthContext);
+  const ctx = React.useContext(NetSuiteAuthContext)
   if (!ctx) {
-    throw new Error('useNetSuiteAuth must be used within <NetSuiteAuthProvider>');
+    throw new Error('useNetSuiteAuth must be used within <NetSuiteAuthProvider>')
   }
-  return ctx;
+  return ctx
 }
 `;
 }
 function authLayoutTsx() {
-  return `import type { ReactNode } from 'react';
-import { NetSuiteAuthProvider, useNetSuiteAuth } from '../../lib/auth';
-import { LoginPage } from './LoginPage';
+  return `import type { ReactNode } from 'react'
+import { NetSuiteAuthProvider, useNetSuiteAuth } from '../../lib/auth'
+import { LoginPage } from './LoginPage'
 
 /**
- * NetSuite auth layout. This is the ONLY wiring you need to add by hand --
- * wrap the root route's <Outlet /> with it:
+ * NetSuite auth layout. The ONE manual wiring step: wrap the root route's
+ * <Outlet /> with it in src/routes/__root.tsx:
  *
- *   // src/routes/__root.tsx
- *   import { AuthLayout } from '../components/auth/AuthLayout';
+ *   import { AuthLayout } from '../components/auth/AuthLayout'
  *   ...
  *   function RootComponent() {
  *     return (
- *       <>
+ *       <RootDocument>
  *         <AuthLayout>
  *           <Outlet />
  *         </AuthLayout>
- *         { ...devtools... }
- *       </>
- *     );
+ *       </RootDocument>
+ *     )
  *   }
  *
- * It provides NetSuite auth context to the whole tree and gates rendering:
- * while the session resolves it shows a spinner, unauthenticated users see
- * <LoginPage />, authenticated users see your routes. Use useNetSuiteAuth()
- * anywhere below it to read the session or sign out. NEVER swap this for a
- * password gate -- real OAuth is the only supported login.
+ * It provides auth context and gates rendering: a spinner while the session
+ * resolves, <LoginPage /> for signed-out users, your routes once signed in.
+ * NEVER swap this for a password gate -- real OAuth is the only login.
  */
 export function AuthLayout({ children }: { children: ReactNode }) {
   return (
     <NetSuiteAuthProvider>
       <Gate>{children}</Gate>
     </NetSuiteAuthProvider>
-  );
+  )
 }
 
 function Gate({ children }: { children: ReactNode }) {
-  const { pending, isAuthenticated } = useNetSuiteAuth();
+  const { pending, isAuthenticated } = useNetSuiteAuth()
 
   if (pending) {
     return (
       <div className="min-h-screen flex items-center justify-center bg-background">
         <div className="h-8 w-8 rounded-full border-2 border-primary border-t-transparent animate-spin" />
       </div>
-    );
+    )
   }
 
-  if (!isAuthenticated) return <LoginPage />;
+  if (!isAuthenticated) return <LoginPage />
+
+  return <>{children}</>
+}
+`;
+}
+function loginPageTsx2() {
+  return `import { SignInWithNetSuite } from './SignInWithNetSuite'
 
-  return <>{children}</>;
+/**
+ * Default unauthenticated landing page. Replaces any password gate. Customise
+ * the copy / imagery freely but keep <SignInWithNetSuite /> as the only
+ * call-to-action -- it points to /auth/netsuite/start.
+ */
+export function LoginPage() {
+  return (
+    <div className="min-h-screen bg-background text-foreground flex">
+      <div className="hidden lg:flex lg:w-1/2 bg-primary text-primary-foreground p-12 flex-col justify-between">
+        <div className="text-xl font-semibold">NetSuite App</div>
+        <div>
+          <h1 className="text-4xl font-bold leading-tight">Connect your NetSuite account</h1>
+          <p className="mt-4 text-primary-foreground/80 max-w-md">
+            Sign in with your NetSuite credentials to access your data securely. Tokens stay
+            server-side -- they never reach the browser.
+          </p>
+        </div>
+        <div className="text-xs text-primary-foreground/60">Powered by HelloLeo</div>
+      </div>
+      <div className="flex-1 flex items-center justify-center px-6 py-12">
+        <div className="w-full max-w-sm space-y-6">
+          <div>
+            <h2 className="text-2xl font-semibold">Welcome</h2>
+            <p className="mt-2 text-sm text-muted-foreground">
+              Use the button below to sign in. You'll be redirected to NetSuite to authorise
+              access, then back here.
+            </p>
+          </div>
+          <SignInWithNetSuite />
+        </div>
+      </div>
+    </div>
+  )
+}
+`;
+}
+function signInButtonTsx() {
+  return `import { signInWithNetSuite } from '../../lib/netsuite'
+
+export function SignInWithNetSuite() {
+  return (
+    <button
+      onClick={() => signInWithNetSuite()}
+      className="inline-flex items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground shadow hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      Sign in with NetSuite
+    </button>
+  )
 }
 `;
 }
 var setupNetsuite = tool({
-  description: "Add NetSuite OAuth wiring to an existing project. Call scaffold first, " + "then this. Writes the OAuth client, auth provider and login components. " + "All files are additive, nothing is overwritten. Real OAuth is wired " + "from day one, never replace <AuthLayout> with a password placeholder.",
+  description: "Add NetSuite runtime OAuth (end-user LOGIN) to a TanStack Start project. " + "Call scaffold first, then this. This login uses NetSuite Integration " + "Record #2 (scope: rest_webservices) -- a SEPARATE record from the MCP one " + "(scope: mcp) that was used only to BUILD the app; do not confuse them. " + "Emits server routes (the OAuth backend lives IN the app -- no separate " + "Worker, no VITE_WORKER_URL), the netsuite_flows + netsuite_sessions " + "drizzle tables, and the same-origin client + auth components. Config " + "(NETSUITE_ACCOUNT_ID/_CLIENT_ID/_CLIENT_SECRET) comes from the project " + ".env in dev and HelloLeo Cloud secrets in prod -- same var names, never " + "in code. Real OAuth from day one -- never replace <AuthLayout> with a " + "password placeholder. Setup guide (link the user to it): " + "https://docs.helloleo.dev/integrations/netsuite",
   args: {},
   async execute(_args, context) {
     const dir = context.directory;
+    await mkdir2(path7.join(dir, "src", "lib"), { recursive: true });
     await mkdir2(path7.join(dir, "src", "components", "auth"), {
       recursive: true
     });
-    const nsFiles = [
-      [path7.join("src", "lib", "netsuite.ts"), netsuiteTs()],
+    await mkdir2(path7.join(dir, "src", "routes", "auth", "netsuite"), {
+      recursive: true
+    });
+    await mkdir2(path7.join(dir, "src", "routes", "api"), { recursive: true });
+    const schemaPath = path7.join(dir, "src", "db", "schema.ts");
+    let schemaAppended = false;
+    try {
+      const current = await readFile3(schemaPath, "utf8");
+      if (!current.includes("netsuite_flows")) {
+        await Bun.write(schemaPath, current + schemaAppend());
+        schemaAppended = true;
+      }
+    } catch {
+      await Bun.write(schemaPath, `import { sql } from 'drizzle-orm'
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+${schemaAppend()}`);
+      schemaAppended = true;
+    }
+    const files = [
+      [path7.join("src", "lib", "netsuite-server.ts"), netsuiteServerTs()],
+      [
+        path7.join("src", "routes", "auth", "netsuite", "start.ts"),
+        startRouteTs()
+      ],
+      [
+        path7.join("src", "routes", "auth", "netsuite", "callback.ts"),
+        callbackRouteTs()
+      ],
+      [
+        path7.join("src", "routes", "auth", "netsuite", "logout.ts"),
+        logoutRouteTs()
+      ],
+      [
+        path7.join("src", "routes", "auth", "netsuite", "config.ts"),
+        configRouteTs()
+      ],
+      [path7.join("src", "routes", "api", "me.ts"), meRouteTs()],
+      [path7.join("src", "lib", "netsuite.ts"), netsuiteClientTs()],
       [path7.join("src", "lib", "auth.tsx"), authTsx()],
       [
         path7.join("src", "components", "auth", "AuthLayout.tsx"),
         authLayoutTsx()
       ],
-      [
-        path7.join("src", "components", "auth", "LoginPage.tsx"),
-        netsuiteLoginPageTsx()
-      ],
+      [path7.join("src", "components", "auth", "LoginPage.tsx"), loginPageTsx2()],
       [
         path7.join("src", "components", "auth", "SignInWithNetSuite.tsx"),
         signInButtonTsx()
       ]
     ];
-    for (const [filePath, content] of nsFiles) {
+    for (const [filePath, content] of files) {
       await Bun.write(path7.join(dir, filePath), content);
     }
     return [
-      `Wrote ${nsFiles.length} NetSuite OAuth files (all additive, nothing overwritten):`,
-      "  - src/lib/netsuite.ts (OAuth client: signIn, session, workerFetch)",
-      "  - src/lib/auth.tsx (NetSuiteAuthProvider and useNetSuiteAuth)",
-      "  - src/components/auth/AuthLayout.tsx (provider and auth gate)",
-      "  - src/components/auth/LoginPage.tsx (unauthenticated view)",
-      "  - src/components/auth/SignInWithNetSuite.tsx (sign-in button)",
+      `Wrote ${files.length} NetSuite files${schemaAppended ? " + appended src/db/schema.ts" : ""}:`,
+      "DOCS -- the authoritative setup guide is https://docs.helloleo.dev/integrations/netsuite . When you tell the user what to do in NetSuite, follow and link these steps verbatim; do not invent steps.",
+      "  - Record #2 (runtime): https://docs.helloleo.dev/integrations/netsuite#step-4-%E2%80%94-create-integration-record-2-runtime",
+      "  - Send runtime creds to Leo: https://docs.helloleo.dev/integrations/netsuite#step-5-%E2%80%94-send-the-runtime-credentials-to-leo",
       "",
-      "Notes:",
-      "- AuthLayout shows LoginPage to signed-out users and renders the app's routes once they sign in with NetSuite.",
-      "- Read the session anywhere with useNetSuiteAuth() from src/lib/auth.tsx.",
-      "- Never replace AuthLayout with a password gate. Real OAuth is the only supported login.",
-      "- The auth worker (deployed via the cloudflare-backend MCP) serves /auth/netsuite/start, /auth/netsuite/callback, /api/me and /auth/netsuite/logout. It reads env.NETSUITE_ACCOUNT_ID, _CLIENT_ID and _CLIENT_SECRET. VITE_WORKER_URL must be set (HelloLeo Cloud seeds it).",
+      "  server (OAuth backend lives in the app -- no separate Worker):",
+      "  - src/lib/netsuite-server.ts (env, PKCE, token exchange, session refresh, netsuiteFetch)",
+      "  - src/routes/auth/netsuite/start.ts    GET  begin PKCE flow",
+      "  - src/routes/auth/netsuite/callback.ts GET  code -> tokens -> session",
+      "  - src/routes/auth/netsuite/logout.ts   POST destroy session",
+      "  - src/routes/auth/netsuite/config.ts   GET  the exact redirect URI to register",
+      "  - src/routes/api/me.ts                 GET  bearer -> session (auth check)",
+      "  - src/db/schema.ts += netsuite_flows + netsuite_sessions",
+      "  client:",
+      "  - src/lib/netsuite.ts (same-origin: signIn, session, apiFetch)",
+      "  - src/lib/auth.tsx (NetSuiteAuthProvider + useNetSuiteAuth)",
+      "  - src/components/auth/{AuthLayout,LoginPage,SignInWithNetSuite}.tsx",
       "",
-      "Next: in src/routes/__root.tsx, import AuthLayout and wrap <Outlet /> with it. Keep any existing providers.",
+      "WIRE IT UP (one manual step): in src/routes/__root.tsx, wrap <Outlet /> with <AuthLayout>:",
       "",
       "    import { AuthLayout } from '../components/auth/AuthLayout'",
       "",
       "    <AuthLayout>",
       "      <Outlet />",
-      "    </AuthLayout>"
+      "    </AuthLayout>",
+      "",
+      "Then:",
+      "- Build your dashboard inside <AuthLayout>. Read the session with useNetSuiteAuth().",
+      "- Data routes: add src/routes/api/*.ts and call netsuiteFetch(bearer(request), '/services/rest/query/v1/suiteql', {...}) from the handler.",
+      "",
+      "TWO INTEGRATION RECORDS -- do not confuse them:",
+      "- Record #1 (scope: mcp): already connected, used ONLY to build the app (schema discovery). This login does NOT use it.",
+      "- Record #2 (scope: rest_webservices): THIS login uses it -- the end user signs into NetSuite through it, and the redirect URI is registered on THIS record. If it doesn't exist yet, tell the user to create it (a second Integration Record, scope rest_webservices only).",
+      "",
+      "CONFIG -- NETSUITE_ACCOUNT_ID, NETSUITE_CLIENT_ID, NETSUITE_CLIENT_SECRET (secret optional for PKCE public clients). Never hardcode; never put in code. Same var names in every environment, different SOURCE:",
+      "- DEV (Fly preview): read from the project .env. HelloLeo writes them there (the setup wizard, or the env tooling). In dev the app uses .env -- do NOT tell the user to use HelloLeo Cloud here.",
+      "- PROD (published Worker): the SAME names live as HelloLeo Cloud secrets; the publish step promotes them from .env onto the Worker automatically. Same code path (@helloleo/runtime env), just a different source per environment.",
+      "- PUBLIC_APP_URL / HELLOLEO_URL are set by the platform per environment; don't hardcode them.",
+      "- REDIRECT URI -- never guess or hardcode it. It is derived server-side and auto-corrects behind the preview proxy. Read the exact value from GET /auth/netsuite/config (or getNetSuiteRedirectUri() on the client) and tell the user to register THAT on Integration Record #2 (scope: rest_webservices). Register both the preview and published URLs -- NetSuite allows multiple redirect URIs.",
+      "- Never replace <AuthLayout> with a password gate. Real OAuth is the only supported login."
     ].join(`
 `);
   }