run402 2.22.0 → 2.23.0

package/lib/assets.mjs

@@ -52,7 +52,9 @@ Options:
   --meta <k=v>        v1.50: attach caller-supplied metadata to the upload (repeatable). Number
                       coercion on pure digits; comma-split into string[]; "true"/"false" → boolean.
   --exif-policy keep|strip  v1.50: EXIF retention policy for image uploads (default keep).
-  --json              NDJSON progress events (for agent consumption)
+  --stream            NDJSON per-file progress events (for agent consumption).
+                      Without --stream, only the final results array is
+                      printed. --json is a deprecated alias for --stream.
   --prefix <p>        Prefix filter (ls only)
   --limit <n>         Max results (ls only; default 100, max 1000)
   --sort <key>        v1.50 ls only: key:asc | createdAt:asc | createdAt:desc (default key:asc).
@@ -99,7 +101,10 @@ Options:
                       Examples: --meta uploaded_by=agent_abc --meta version=3 --meta tags=hero,banner
   --exif-policy keep|strip  v1.50: EXIF retention policy. Default 'keep'. 'strip' discards EXIF
                       from the stored bytes and the image_exif response field.
-  --json              Emit NDJSON progress events on stdout (for agent consumption)
+  --stream            Emit NDJSON per-file progress events on stdout (for
+                      agent consumption). Default: emit only the final
+                      results array (also JSON). --json is a deprecated
+                      alias for --stream.
 
 Examples:
   run402 assets put ./artifact.tgz --project prj_abc123
@@ -223,6 +228,7 @@ function parseArgs(rawArgs) {
     "--immutable",
     "--concurrency",
     "--no-resume",
+    "--stream",
     "--json",
     "--prefix",
     "--limit",
@@ -237,7 +243,7 @@ function parseArgs(rawArgs) {
     "-h",
   ], valueFlags);
   const out = { positional: [], project: null, key: null, private: false, immutable: false,
-                 concurrency: 4, resume: true, json: false, prefix: null, limit: null,
+                 concurrency: 4, resume: true, stream: false, prefix: null, limit: null,
                  output: null, ttl: null, contentType: null,
                  metadata: null, exifPolicy: null, sort: null, filter: null };
   for (let i = 0; i < args.length; i++) {
@@ -249,7 +255,13 @@ function parseArgs(rawArgs) {
     else if (a === "--immutable") out.immutable = true;
     else if (a === "--concurrency") out.concurrency = parseIntegerFlag("--concurrency", args[++i], { min: 1 });
     else if (a === "--no-resume") out.resume = false;
-    else if (a === "--json") out.json = true;
+    else if (a === "--stream") out.stream = true;
+    else if (a === "--json") {
+      out.stream = true;
+      process.stderr.write(
+        "# warning: `--json` on `assets put` is deprecated and will be removed in a future release. Use `--stream` (alias means the same thing — NDJSON progress events on stdout).\n",
+      );
+    }
     else if (a === "--prefix") out.prefix = args[++i];
     else if (a === "--limit") out.limit = parseIntegerFlag("--limit", args[++i], { min: 1, max: 1000 });
     else if (a === "--output" || a === "-o") out.output = args[++i];
@@ -478,7 +490,7 @@ async function put(projectId, argv) {
       reportSdkError(err);
     }
   }
-  if (!opts.json) console.log(JSON.stringify(results, null, 2));
+  if (!opts.stream) console.log(JSON.stringify(results, null, 2));
 }
 
 // ---------------------------------------------------------------------------
@@ -622,7 +634,7 @@ function guessContentType(key) {
 }
 
 function log(opts, event) {
-  if (opts.json) console.log(JSON.stringify(event));
+  if (opts.stream) console.log(JSON.stringify(event));
 }
 
 // ---------------------------------------------------------------------------

package/lib/deploy-v2.mjs

@@ -753,6 +753,44 @@ async function applyCmd(args) {
   const releaseSpec = normalizedManifest.spec;
   const idempotencyKey = normalizedManifest.idempotencyKey;
 
+  // Pre-flight source scan (auth-aware-ssr Section 9). Bypass via
+  // RUN402_DEPLOY_SKIP_SCAN=1 — useful for forcing a deploy when
+  // the scanner has a false positive that the operator has confirmed
+  // is fine. Hits with severity `error` fail the deploy.
+  if (process.env.RUN402_DEPLOY_SKIP_SCAN !== "1") {
+    try {
+      const { resolveScanRoot, scanSourceTree, SCAN_SEVERITY } = await import(
+        "./doctor-source-scan.mjs"
+      );
+      const scanRoot = opts.dir
+        ? (isAbsolute(opts.dir) ? opts.dir : resolve(process.cwd(), opts.dir))
+        : resolveScanRoot(process.cwd());
+      const findings = scanSourceTree(scanRoot, { cwd: process.cwd() });
+      const errorFindings = findings.filter((f) => f.severity === SCAN_SEVERITY.ERROR);
+      if (errorFindings.length > 0) {
+        const summary = errorFindings.slice(0, 10).map((f) => {
+          const loc = f.line ? `${f.file}:${f.line}` : f.file;
+          return `  ${f.code} ${loc}\n    ${f.message}${f.canonical_name ? `\n    fix: ${f.canonical_name}` : ""}`;
+        }).join("\n");
+        const more = errorFindings.length > 10 ? `\n  ...and ${errorFindings.length - 10} more` : "";
+        fail({
+          code: "R402_AUTH_PREFLIGHT_FAILED",
+          message: `Source scan blocked deploy: ${errorFindings.length} R402_AUTH_* finding(s). Run \`run402 doctor\` for the full list. Bypass with RUN402_DEPLOY_SKIP_SCAN=1 if you're sure.`,
+          details: { findings: errorFindings, summary: `${summary}${more}` },
+        });
+      }
+    } catch (err) {
+      if (err && typeof err === "object" && err.code === "R402_AUTH_PREFLIGHT_FAILED") {
+        throw err;
+      }
+      // Scanner crashed — warn but don't block. The scanner is a safety
+      // net; the deploy should proceed if it can't read the source tree.
+      console.warn(
+        `[deploy] source scan skipped: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
   let sdkOpts;
   if (useGithubActionsOidc) {
     sdkOpts = {

package/lib/doctor-source-scan.mjs

@@ -0,0 +1,424 @@
+/**
+ * `run402 doctor` source-scan module (auth-aware-ssr Section 9).
+ *
+ * Walks the project's `src/` directory and reports patterns the
+ * auth-aware-ssr design specifies as deploy-failing OR runtime warnings:
+ *
+ *   - **Hallucinated SDK names.** `getUser`, `getSession`, `currentUser`,
+ *     `getCurrentUser`, `getServerSession`, `auth.protect`, `auth.signIn`,
+ *     `auth.logout`, `auth.middleware`, etc. Each hit emits
+ *     `R402_AUTH_UNKNOWN_EXPORT` with a structured fix-it (attempted name,
+ *     canonical replacement, import line, docs URL).
+ *
+ *   - **State-changing GET handlers.** Astro pages that export a GET
+ *     handler containing DB-mutation patterns (`db().insert`, `db().update`,
+ *     `db().delete`, `adminDb().sql("UPDATE"`, etc.). Emit
+ *     `R402_AUTH_STATE_CHANGING_GET`.
+ *
+ *   - **`auth.*` calls in prerendered pages.** Astro pages declaring
+ *     `export const prerender = true` that also call `auth.*` helpers.
+ *     Emit `R402_AUTH_PRERENDERED`.
+ *
+ *   - **Direct `internal.sessions.authz_version` mutation.** Consumer
+ *     migrations that try to `UPDATE internal.sessions SET authz_version`
+ *     manually. Emit `R402_AUTH_AUTHZ_VERSION_PROHIBITED`.
+ *
+ * The scanner is regex-based — fast, dependency-free, and good enough
+ * for the canonical patterns. The `run402 doctor --json` mode emits the
+ * structured envelope; the default mode prints a readable per-finding
+ * summary. Wired into `run402 deploy` pre-flight as a deploy-failing
+ * gate for the error severities; non-blocking for warning severities.
+ *
+ * @see openspec/changes/auth-aware-ssr/specs/functions-sdk-auth-model
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join, relative } from "node:path";
+
+/** Severity ladder for scanner findings. `error` blocks deploy; `warn`
+ *  reports but doesn't block. The `run402 doctor` exit code is non-zero
+ *  whenever any `error`-severity finding is present. */
+export const SCAN_SEVERITY = Object.freeze({
+  ERROR: "error",
+  WARN: "warn",
+});
+
+/** File extensions scanned. Astro frontmatter + TS/JS are the primary
+ *  surface; the regex matchers fire equally on all of them. `.astro`
+ *  matters because consumers write SSR pages there. */
+const SCANNED_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".astro"]);
+
+/** Directories the scanner refuses to descend into. We never report
+ *  on platform-generated code or vendored dependencies. */
+const SKIPPED_DIRECTORIES = new Set([
+  "node_modules",
+  ".git",
+  ".vscode",
+  ".idea",
+  "dist",
+  "build",
+  "out",
+  ".astro",
+  ".next",
+  ".vercel",
+  ".netlify",
+  "coverage",
+]);
+
+/** Hallucinated-name registry from the auth-aware-ssr spec. Each entry
+ *  carries the canonical replacement so the fix-it is actionable. The
+ *  list is intentionally exhaustive — every name flagged here came up
+ *  in pre-launch LLM hallucination samples. */
+const HALLUCINATED_NAMES = [
+  // ESM named imports — caught by regex on import lines AND by call-site
+  // matching when consumers paste from training-data examples.
+  { name: "getUser", canonical: "auth.user() / auth.requireUser()", origin: "supabase / clerk / nextauth legacy" },
+  { name: "getUserId", canonical: "(await auth.user())?.id", origin: "run402 v0.x" },
+  { name: "getRole", canonical: "auth.requireRole(role)", origin: "run402 v0.x" },
+  { name: "getSession", canonical: "auth.user()", origin: "next-auth / nextauth" },
+  { name: "currentUser", canonical: "auth.user()", origin: "clerk" },
+  { name: "currentSession", canonical: "auth.user()", origin: "clerk" },
+  { name: "getCurrentUser", canonical: "auth.user()", origin: "generic" },
+  { name: "getCurrentSession", canonical: "auth.user()", origin: "generic" },
+  { name: "getServerSession", canonical: "auth.user()", origin: "next-auth" },
+  { name: "getAuth", canonical: "auth.user() / auth.requireUser()", origin: "clerk" },
+  { name: "requireAuth", canonical: "auth.requireUser()", origin: "generic" },
+  { name: "withAuth", canonical: "auth.requireUser() inside the handler", origin: "next-auth-style HOC" },
+  { name: "protectRoute", canonical: "auth.requireUser() inside the handler", origin: "generic" },
+  { name: "useUser", canonical: "auth.user() (note: server-only; not a React hook)", origin: "clerk / supabase" },
+  { name: "useSession", canonical: "auth.user() (note: server-only)", origin: "next-auth / clerk" },
+  { name: "createServerClient", canonical: "db() (use the bundled SDK; no client setup needed)", origin: "supabase" },
+  { name: "clerkClient", canonical: "auth.user() + db()", origin: "clerk" },
+];
+
+/** Property-access hallucinations on the `auth` object. The SDK's
+ *  Proxy catches these at runtime, but the source scanner fires
+ *  earlier so the deploy fails before the bundle ships. */
+const HALLUCINATED_AUTH_PROPERTIES = [
+  { name: "auth.session", canonical: "auth.user() then read .sessionId" },
+  { name: "auth.getSession", canonical: "auth.user()" },
+  { name: "auth.currentUser", canonical: "auth.user()" },
+  { name: "auth.currentSession", canonical: "auth.user()" },
+  { name: "auth.requireAuth", canonical: "auth.requireUser()" },
+  { name: "auth.middleware", canonical: "auth.csrfField() / @run402/astro middleware" },
+  { name: "auth.signIn", canonical: "POST /auth/sign-in or auth.sessions.createResponseFromIdentity({...})" },
+  { name: "auth.signOut", canonical: "auth.sessions.endResponse()" },
+  { name: "auth.signout", canonical: "auth.sessions.endResponse()" },
+  { name: "auth.logout", canonical: "auth.sessions.endResponse()" },
+  { name: "auth.login", canonical: "auth.sessions.createResponseFromIdentity({...})" },
+  { name: "auth.redirectToSignIn", canonical: "auth.requireUser() — platform handles redirect" },
+  { name: "auth.getUser", canonical: "auth.user()" },
+  { name: "auth.getToken", canonical: "auth.requireUser() then read .sessionId (tokens not exposed)" },
+  { name: "auth.protect", canonical: "auth.requireUser() / auth.requireRole(...)" },
+];
+
+/** Browser-only patterns that should NEVER appear in SSR / Lambda code.
+ *  These are caught at scan time because the SDK doesn't ship a
+ *  shim — the line just fails to execute. */
+const BROWSER_ONLY_PATTERNS = [
+  {
+    pattern: /localStorage\.getItem\(\s*['"]wl_session['"]\s*\)/g,
+    name: "localStorage.wl_session",
+    canonical: "auth.user() (browser sessions are HttpOnly cookies; no localStorage)",
+  },
+  {
+    // Matches: `Authorization: "Bearer ..."` (bare key + string value)
+    //          `"Authorization": "Bearer ..."` (string key + string value)
+    //          `'Authorization': 'Bearer ...'` (single quotes)
+    pattern: /['"]?Authorization['"]?\s*[:,]\s*['"]Bearer\s/g,
+    name: "Authorization: Bearer (in browser code)",
+    canonical: "Browser code doesn't carry JWTs. Use auth.fetch() for same-origin SSR fetches.",
+    severity: SCAN_SEVERITY.WARN, // Bearer is fine in server-side machine code; gated by file path.
+  },
+];
+
+/** Scan a single file's content. Returns the array of findings (zero
+ *  or more). Pure / no I/O — tests pass strings directly. */
+export function scanFileContent(content, opts = {}) {
+  const filePath = opts.filePath ?? "<inline>";
+  const findings = [];
+
+  // 1) Hallucinated bare names — import { getSession } from ... OR
+  //    bare call sites `await getSession(...)`.
+  for (const entry of HALLUCINATED_NAMES) {
+    // Match in an `import { … }` statement OR a bare function-call site.
+    // Negative-lookahead: don't fire on `auth.getSession` etc. (caught
+    // separately by the auth-property scanner below).
+    const importRegex = new RegExp(
+      `import\\s*\\{[^}]*\\b${escapeRegex(entry.name)}\\b[^}]*\\}\\s*from\\s*['"]@run402/functions['"]`,
+      "g",
+    );
+    const callRegex = new RegExp(
+      `(?<![.\\w])${escapeRegex(entry.name)}\\s*\\(`,
+      "g",
+    );
+    let match;
+    while ((match = importRegex.exec(content)) !== null) {
+      findings.push({
+        code: "R402_AUTH_UNKNOWN_EXPORT",
+        severity: SCAN_SEVERITY.ERROR,
+        file: filePath,
+        line: lineNumberFor(content, match.index),
+        attempted_name: entry.name,
+        canonical_name: entry.canonical,
+        import_line: 'import { auth } from "@run402/functions"',
+        docs: "https://docs.run402.com/auth/sdk",
+        message: `Import '${entry.name}' from @run402/functions is not a working export (origin: ${entry.origin}). Use ${entry.canonical}.`,
+      });
+    }
+    while ((match = callRegex.exec(content)) !== null) {
+      findings.push({
+        code: "R402_AUTH_UNKNOWN_EXPORT",
+        severity: SCAN_SEVERITY.ERROR,
+        file: filePath,
+        line: lineNumberFor(content, match.index),
+        attempted_name: entry.name,
+        canonical_name: entry.canonical,
+        import_line: 'import { auth } from "@run402/functions"',
+        docs: "https://docs.run402.com/auth/sdk",
+        message: `Call to '${entry.name}()' will throw R402_AUTH_UNKNOWN_EXPORT at runtime. Use ${entry.canonical}.`,
+      });
+    }
+  }
+
+  // 2) Hallucinated property access on `auth.*`. The SDK Proxy catches
+  //    these at runtime; we catch earlier at deploy.
+  for (const entry of HALLUCINATED_AUTH_PROPERTIES) {
+    const regex = new RegExp(`(?<![\\w.])${escapeRegex(entry.name)}\\b`, "g");
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      findings.push({
+        code: "R402_AUTH_UNKNOWN_EXPORT",
+        severity: SCAN_SEVERITY.ERROR,
+        file: filePath,
+        line: lineNumberFor(content, match.index),
+        attempted_name: entry.name,
+        canonical_name: entry.canonical,
+        import_line: 'import { auth } from "@run402/functions"',
+        docs: "https://docs.run402.com/auth/sdk",
+        message: `'${entry.name}' is not a valid auth.* helper. Use ${entry.canonical}.`,
+      });
+    }
+  }
+
+  // 3) Browser-only / wrong-environment patterns.
+  for (const entry of BROWSER_ONLY_PATTERNS) {
+    let match;
+    while ((match = entry.pattern.exec(content)) !== null) {
+      findings.push({
+        code: "R402_AUTH_UNKNOWN_EXPORT",
+        severity: entry.severity ?? SCAN_SEVERITY.ERROR,
+        file: filePath,
+        line: lineNumberFor(content, match.index),
+        attempted_name: entry.name,
+        canonical_name: entry.canonical,
+        message: `'${entry.name}' is not supported. ${entry.canonical}.`,
+      });
+    }
+  }
+
+  // 4) Prerendered pages calling auth.*. The Astro adapter throws
+  //    R402_AUTH_PRERENDERED at build time; this catches earlier.
+  if (filePath.endsWith(".astro") || filePath.endsWith(".ts") || filePath.endsWith(".tsx")) {
+    const declaresPrerender = /export\s+const\s+prerender\s*=\s*true/.test(content);
+    if (declaresPrerender) {
+      const authCallRegex = /\bauth\.(user|requireUser|requireRole|requireMembership|requireFresh|fetch|csrfToken|csrfField|sessions|identities)\b/g;
+      let match;
+      while ((match = authCallRegex.exec(content)) !== null) {
+        findings.push({
+          code: "R402_AUTH_PRERENDERED",
+          severity: SCAN_SEVERITY.ERROR,
+          file: filePath,
+          line: lineNumberFor(content, match.index),
+          message: `auth.${match[1]} called from a prerendered page. Convert to SSR (\`export const prerender = false\`) or use a server island.`,
+          docs: "https://docs.run402.com/auth/rendering-modes",
+        });
+      }
+    }
+  }
+
+  // 5) State-changing GET handlers. Heuristic: an Astro `export const GET`
+  //    or a `GET` Web-handler containing db-mutation patterns.
+  const getHandlerRegex = /export\s+(?:async\s+)?(?:const\s+|function\s+)GET\s*[=(]/g;
+  const mutationInGetRegex = /\b(?:db|adminDb)\s*\(\s*\)?[^)]*\)?\s*\.(?:insert|update|delete)\s*\(/g;
+  const sqlMutationRegex = /\.sql\s*\(\s*['"`]\s*(?:UPDATE|INSERT|DELETE)\b/gi;
+  if (getHandlerRegex.test(content)) {
+    let match;
+    while ((match = mutationInGetRegex.exec(content)) !== null) {
+      findings.push({
+        code: "R402_AUTH_STATE_CHANGING_GET",
+        severity: SCAN_SEVERITY.ERROR,
+        file: filePath,
+        line: lineNumberFor(content, match.index),
+        message: "GET handler mutates state. Move the mutation to POST.",
+        docs: "https://docs.run402.com/auth/hosted-ui#post-only",
+      });
+    }
+    while ((match = sqlMutationRegex.exec(content)) !== null) {
+      findings.push({
+        code: "R402_AUTH_STATE_CHANGING_GET",
+        severity: SCAN_SEVERITY.ERROR,
+        file: filePath,
+        line: lineNumberFor(content, match.index),
+        message: "GET handler runs UPDATE/INSERT/DELETE SQL. Move the mutation to POST.",
+        docs: "https://docs.run402.com/auth/hosted-ui#post-only",
+      });
+    }
+  }
+
+  // 6) Direct mutation of internal.sessions.authz_version in consumer
+  //    migrations or SQL strings. The platform is the sole writer.
+  const authzVersionRegex = /UPDATE\s+internal\.sessions\s+SET\s+authz_version\b/gi;
+  let m;
+  while ((m = authzVersionRegex.exec(content)) !== null) {
+    findings.push({
+      code: "R402_AUTH_AUTHZ_VERSION_PROHIBITED",
+      severity: SCAN_SEVERITY.ERROR,
+      file: filePath,
+      line: lineNumberFor(content, m.index),
+      message: "Consumer code may not mutate internal.sessions.authz_version directly. Register your grants table in the authz manifest so the platform installs the bump trigger.",
+      docs: "https://docs.run402.com/auth/db-actor-context#authz-version",
+    });
+  }
+
+  // 7) Redundant `.eq("user_id", user.id)` against RLS-bound tables.
+  //    db() propagates the actor via the run402.actor.* settings — PostgREST
+  //    enforces ownership in RLS. Filtering on user_id again is at best a
+  //    no-op and at worst a code smell that suggests the developer doesn't
+  //    trust RLS. Catch the most common shapes:
+  //
+  //      .eq("user_id", user.id)
+  //      .eq('user_id', actor.id)
+  //      .eq("user_id", await auth.user()).id   (rare; covered by the suffix)
+  //
+  //    Opt-out via inline annotation comment on the preceding or same line:
+  //      // run402-allow-user-filter: <reason>
+  //      .eq("user_id", joinedRowOwner)
+  //
+  //    Pattern is intentionally narrow (`user_id` literal column name + a
+  //    value expression matching `<ident>.id`) to keep the false-positive
+  //    rate low. Heuristic — RLS-binding is unknown at scan time; the rule
+  //    fires on the shape, and the operator either annotates or fixes.
+  const redundantFilterRegex =
+    /\.eq\s*\(\s*['"]user_id['"]\s*,\s*([a-zA-Z_$][\w$]*)\.id\s*\)/g;
+  const lines = content.split(/\r?\n/);
+  const cumulativeOffsets = (() => {
+    const offsets = [0];
+    for (let i = 0; i < lines.length; i++) {
+      // +1 for the trailing newline we split on
+      offsets.push(offsets[i] + lines[i].length + 1);
+    }
+    return offsets;
+  })();
+  function lineIndexFor(charIndex) {
+    // Binary search would be faster; lines are typically <2k.
+    for (let i = 0; i < cumulativeOffsets.length - 1; i++) {
+      if (charIndex < cumulativeOffsets[i + 1]) return i;
+    }
+    return cumulativeOffsets.length - 2;
+  }
+  let f;
+  while ((f = redundantFilterRegex.exec(content)) !== null) {
+    const lineIdx = lineIndexFor(f.index);
+    const thisLine = lines[lineIdx] ?? "";
+    const prevLine = lineIdx > 0 ? (lines[lineIdx - 1] ?? "") : "";
+    const annotated =
+      /\/\/\s*run402-allow-user-filter/i.test(thisLine) ||
+      /\/\/\s*run402-allow-user-filter/i.test(prevLine);
+    if (annotated) continue;
+    findings.push({
+      code: "R402_AUTH_REDUNDANT_USER_FILTER",
+      severity: SCAN_SEVERITY.WARN,
+      file: filePath,
+      line: lineIdx + 1,
+      message:
+        `Redundant '.eq(\"user_id\", ${f[1]}.id)'. db() propagates the actor — PostgREST RLS enforces ownership server-side. ` +
+        `If this is intentional (e.g., the table's RLS scopes on something else and you want to filter additionally), ` +
+        `silence with: // run402-allow-user-filter: <reason>`,
+      docs: "https://run402.com/errors/#R402_AUTH_REDUNDANT_USER_FILTER",
+    });
+  }
+
+  return findings;
+}
+
+/** Recursively walk `srcDir` and scan every file with a relevant
+ *  extension. Returns the combined findings list, sorted by file +
+ *  line for stable output. */
+export function scanSourceTree(srcDir, opts = {}) {
+  const findings = [];
+  walk(srcDir, (filePath) => {
+    if (!SCANNED_EXTENSIONS.has(extname(filePath))) return;
+    let content;
+    try {
+      content = readFileSync(filePath, "utf8");
+    } catch (err) {
+      findings.push({
+        code: "R402_AUTH_SOURCE_SCAN_ERROR",
+        severity: SCAN_SEVERITY.WARN,
+        file: relative(opts.cwd ?? srcDir, filePath),
+        message: `failed to read file: ${err instanceof Error ? err.message : String(err)}`,
+      });
+      return;
+    }
+    findings.push(
+      ...scanFileContent(content, { filePath: relative(opts.cwd ?? srcDir, filePath) }),
+    );
+  });
+  findings.sort((a, b) => {
+    if (a.file !== b.file) return a.file < b.file ? -1 : 1;
+    return (a.line ?? 0) - (b.line ?? 0);
+  });
+  return findings;
+}
+
+function walk(dir, visitor) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIPPED_DIRECTORIES.has(entry.name)) continue;
+      walk(join(dir, entry.name), visitor);
+    } else if (entry.isFile()) {
+      visitor(join(dir, entry.name));
+    }
+  }
+}
+
+function lineNumberFor(content, index) {
+  let line = 1;
+  for (let i = 0; i < index; i++) {
+    if (content.charCodeAt(i) === 10) line++;
+  }
+  return line;
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Convenience for tests: synchronous, no FS access. */
+export function _testOnly_hallucinatedNames() {
+  return HALLUCINATED_NAMES.slice();
+}
+
+export function _testOnly_authProperties() {
+  return HALLUCINATED_AUTH_PROPERTIES.slice();
+}
+
+/** Resolve the project's src/ directory. Astro convention is `<root>/src`;
+ *  bare Node projects use `<root>/src` or `<root>`. We prefer `src/` if
+ *  it exists. */
+export function resolveScanRoot(cwd = process.cwd()) {
+  const srcDir = join(cwd, "src");
+  try {
+    if (statSync(srcDir).isDirectory()) return srcDir;
+  } catch {
+    // Fall through.
+  }
+  return cwd;
+}

package/lib/doctor-source-scan.test.mjs

@@ -0,0 +1,318 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  scanFileContent,
+  SCAN_SEVERITY,
+  _testOnly_hallucinatedNames,
+  _testOnly_authProperties,
+} from "./doctor-source-scan.mjs";
+
+describe("scanFileContent — hallucinated bare names", () => {
+  it("flags `import { getUser } from \"@run402/functions\"` as an error", () => {
+    const findings = scanFileContent(
+      `import { getUser } from "@run402/functions";\n`,
+      { filePath: "src/pages/index.astro" },
+    );
+    assert.ok(findings.length >= 1);
+    const f = findings.find((x) => x.attempted_name === "getUser" && x.line === 1);
+    assert.ok(f, "found getUser finding");
+    assert.equal(f.code, "R402_AUTH_UNKNOWN_EXPORT");
+    assert.equal(f.severity, SCAN_SEVERITY.ERROR);
+    assert.match(f.canonical_name, /auth\.user/);
+    assert.equal(f.file, "src/pages/index.astro");
+  });
+
+  it("flags `import { getSession, currentUser } from \"@run402/functions\"`", () => {
+    const findings = scanFileContent(
+      `import { getSession, currentUser } from "@run402/functions";`,
+    );
+    const names = new Set(findings.map((f) => f.attempted_name));
+    assert.ok(names.has("getSession"));
+    assert.ok(names.has("currentUser"));
+  });
+
+  it("flags bare `await getSession()` call sites", () => {
+    const findings = scanFileContent(`
+      const session = await getSession();
+    `);
+    assert.ok(findings.some((f) => f.attempted_name === "getSession"));
+  });
+
+  it("does not double-fire on `auth.getSession()` — that's the property scanner's job", () => {
+    const findings = scanFileContent(`
+      const session = await auth.getSession();
+    `);
+    // The bare-name scanner should NOT fire on `auth.getSession`; only
+    // the property scanner should. So exactly one finding for getSession.
+    const bareGetSession = findings.filter((f) => f.attempted_name === "getSession");
+    assert.equal(bareGetSession.length, 0, "bare getSession() must not fire on auth.getSession()");
+    const authGetSession = findings.filter((f) => f.attempted_name === "auth.getSession");
+    assert.equal(authGetSession.length, 1);
+  });
+
+  it("includes the canonical replacement and docs URL in the finding", () => {
+    const findings = scanFileContent(
+      `import { getUser } from "@run402/functions";`,
+    );
+    const f = findings[0];
+    assert.match(f.canonical_name, /auth\.user/);
+    assert.match(f.import_line, /@run402\/functions/);
+    assert.match(f.docs, /docs\.run402\.com\/auth\/sdk/);
+  });
+
+  it("covers every hallucinated name in the spec registry", () => {
+    const names = _testOnly_hallucinatedNames();
+    for (const entry of names) {
+      const findings = scanFileContent(`const x = ${entry.name}();`);
+      assert.ok(
+        findings.some((f) => f.attempted_name === entry.name),
+        `expected scanner to flag bare ${entry.name}()`,
+      );
+    }
+  });
+
+  it("does NOT fire on `auth.user()` (the canonical helper)", () => {
+    const findings = scanFileContent(`
+      const user = await auth.user();
+      const required = await auth.requireUser();
+    `);
+    // Should be zero R402_AUTH_UNKNOWN_EXPORT findings.
+    assert.equal(findings.length, 0, `unexpected findings: ${JSON.stringify(findings)}`);
+  });
+});
+
+describe("scanFileContent — auth.* property hallucinations", () => {
+  it("flags `auth.protect(...)` as an error pointing at auth.requireUser / auth.requireRole", () => {
+    const findings = scanFileContent(`const r = auth.protect({ role: "admin" });`);
+    const f = findings.find((x) => x.attempted_name === "auth.protect");
+    assert.ok(f);
+    assert.match(f.canonical_name, /requireUser|requireRole/);
+  });
+
+  it("flags `auth.signIn(...)` pointing at createResponseFromIdentity", () => {
+    const findings = scanFileContent(`return auth.signIn({ provider: "google" });`);
+    const f = findings.find((x) => x.attempted_name === "auth.signIn");
+    assert.ok(f);
+    assert.match(f.canonical_name, /createResponseFromIdentity|POST \/auth\/sign-in/);
+  });
+
+  it("covers every auth.* property in the registry", () => {
+    const props = _testOnly_authProperties();
+    for (const entry of props) {
+      const findings = scanFileContent(`const r = ${entry.name}();`);
+      assert.ok(
+        findings.some((f) => f.attempted_name === entry.name),
+        `expected scanner to flag ${entry.name}`,
+      );
+    }
+  });
+});
+
+describe("scanFileContent — browser-only patterns", () => {
+  it("flags `localStorage.getItem(\"wl_session\")`", () => {
+    const findings = scanFileContent(`
+      const token = localStorage.getItem("wl_session");
+    `);
+    assert.ok(findings.some((f) => f.attempted_name === "localStorage.wl_session"));
+  });
+
+  it("warns on Authorization: Bearer in browser-context code", () => {
+    const findings = scanFileContent(`
+      fetch("/api", { headers: { "Authorization": "Bearer " + token } });
+    `);
+    const f = findings.find((x) => x.attempted_name?.startsWith("Authorization"));
+    assert.ok(f);
+    assert.equal(f.severity, SCAN_SEVERITY.WARN, "Bearer is a warn, not an error");
+  });
+});
+
+describe("scanFileContent — prerendered pages calling auth.*", () => {
+  it("flags `export const prerender = true` + `auth.user()`", () => {
+    const findings = scanFileContent(
+      `---
+export const prerender = true;
+const user = await auth.user();
+---
+<html><body>{user?.email}</body></html>`,
+      { filePath: "src/pages/me.astro" },
+    );
+    const f = findings.find((x) => x.code === "R402_AUTH_PRERENDERED");
+    assert.ok(f, "expected R402_AUTH_PRERENDERED");
+    assert.equal(f.severity, SCAN_SEVERITY.ERROR);
+    assert.match(f.docs, /rendering-modes/);
+  });
+
+  it("does NOT fire when `prerender = true` page never calls auth.*", () => {
+    const findings = scanFileContent(
+      `---
+export const prerender = true;
+const title = "static page";
+---
+<html><body>{title}</body></html>`,
+      { filePath: "src/pages/static.astro" },
+    );
+    const f = findings.find((x) => x.code === "R402_AUTH_PRERENDERED");
+    assert.equal(f, undefined);
+  });
+
+  it("does NOT fire when the file lacks the prerender export", () => {
+    const findings = scanFileContent(
+      `const user = await auth.user();`,
+      { filePath: "src/pages/dynamic.astro" },
+    );
+    const f = findings.find((x) => x.code === "R402_AUTH_PRERENDERED");
+    assert.equal(f, undefined);
+  });
+});
+
+describe("scanFileContent — state-changing GET handlers", () => {
+  it("flags `export async function GET` with `db().insert(...)`", () => {
+    const findings = scanFileContent(`
+      import { db } from "@run402/functions";
+      export async function GET(req) {
+        await db().from("posts").insert({ title: "x" });
+        return new Response("ok");
+      }
+    `);
+    const f = findings.find((x) => x.code === "R402_AUTH_STATE_CHANGING_GET");
+    assert.ok(f);
+    assert.equal(f.severity, SCAN_SEVERITY.ERROR);
+  });
+
+  it("flags `export const GET` with `adminDb().sql(\"UPDATE ...\")`", () => {
+    const findings = scanFileContent(`
+      import { adminDb } from "@run402/functions";
+      export const GET = async () => {
+        await adminDb().sql("UPDATE foo SET x = 1");
+        return new Response("ok");
+      };
+    `);
+    const f = findings.find((x) => x.code === "R402_AUTH_STATE_CHANGING_GET");
+    assert.ok(f);
+  });
+
+  it("does NOT fire on read-only GET handlers", () => {
+    const findings = scanFileContent(`
+      import { db } from "@run402/functions";
+      export async function GET() {
+        const rows = await db().from("posts").select();
+        return Response.json(rows);
+      }
+    `);
+    const f = findings.find((x) => x.code === "R402_AUTH_STATE_CHANGING_GET");
+    assert.equal(f, undefined);
+  });
+});
+
+describe("scanFileContent — direct authz_version mutation", () => {
+  it("flags `UPDATE internal.sessions SET authz_version`", () => {
+    const findings = scanFileContent(`
+      adminDb().sql(\`UPDATE internal.sessions SET authz_version = authz_version + 1\`);
+    `);
+    const f = findings.find((x) => x.code === "R402_AUTH_AUTHZ_VERSION_PROHIBITED");
+    assert.ok(f);
+    assert.equal(f.severity, SCAN_SEVERITY.ERROR);
+    assert.match(f.docs, /authz-version/);
+  });
+
+  it("is case-insensitive (UPDATE / update / Update)", () => {
+    const variants = [
+      "update internal.sessions set authz_version = 5;",
+      "Update Internal.Sessions Set Authz_Version = 5;",
+    ];
+    for (const sql of variants) {
+      const findings = scanFileContent(sql);
+      assert.ok(
+        findings.some((f) => f.code === "R402_AUTH_AUTHZ_VERSION_PROHIBITED"),
+        `case variant failed: ${sql}`,
+      );
+    }
+  });
+});
+
+describe("scanFileContent — redundant user_id filter (R402_AUTH_REDUNDANT_USER_FILTER)", () => {
+  it("flags `.eq(\"user_id\", user.id)`", () => {
+    const content = [
+      'import { db, auth } from "@run402/functions";',
+      "const user = await auth.requireUser();",
+      'const rows = await db().from("posts").select("*").eq("user_id", user.id);',
+    ].join("\n");
+    const findings = scanFileContent(content);
+    const f = findings.find((x) => x.code === "R402_AUTH_REDUNDANT_USER_FILTER");
+    assert.ok(f, "expected a R402_AUTH_REDUNDANT_USER_FILTER finding");
+    assert.equal(f.severity, SCAN_SEVERITY.WARN);
+    assert.match(f.docs, /R402_AUTH_REDUNDANT_USER_FILTER/);
+    assert.equal(f.line, 3);
+  });
+
+  it("flags `.eq('user_id', actor.id)` with single quotes + different identifier", () => {
+    const content = "const r = q.eq('user_id', actor.id);";
+    const findings = scanFileContent(content);
+    assert.ok(findings.some((f) => f.code === "R402_AUTH_REDUNDANT_USER_FILTER"));
+  });
+
+  it("is silenced by `// run402-allow-user-filter:` on the same line", () => {
+    const content = [
+      'import { db, auth } from "@run402/functions";',
+      "const user = await auth.requireUser();",
+      'const rows = await db().from("posts").select("*").eq("user_id", user.id); // run402-allow-user-filter: explicit filter for analytics export',
+    ].join("\n");
+    const findings = scanFileContent(content);
+    assert.ok(
+      !findings.some((f) => f.code === "R402_AUTH_REDUNDANT_USER_FILTER"),
+      "annotated line should not produce a finding",
+    );
+  });
+
+  it("is silenced by `// run402-allow-user-filter:` on the preceding line", () => {
+    const content = [
+      'import { db, auth } from "@run402/functions";',
+      "const user = await auth.requireUser();",
+      "// run402-allow-user-filter: this table's RLS scopes on org_id, not user_id",
+      'const rows = await db().from("posts").select("*").eq("user_id", user.id);',
+    ].join("\n");
+    const findings = scanFileContent(content);
+    assert.ok(
+      !findings.some((f) => f.code === "R402_AUTH_REDUNDANT_USER_FILTER"),
+      "preceding annotation should silence",
+    );
+  });
+
+  it("does NOT flag `.eq(\"org_id\", user.org_id)` or `.eq(\"team_id\", ...)`", () => {
+    const content = [
+      'const rows1 = q.eq("org_id", user.id);', // non-user_id column
+      "const rows2 = q.eq(\"team_id\", actor.team_id);",
+      'const rows3 = q.eq("user_id", "fixed-uuid-literal");', // literal string, not <ident>.id
+    ].join("\n");
+    const findings = scanFileContent(content);
+    assert.ok(
+      !findings.some((f) => f.code === "R402_AUTH_REDUNDANT_USER_FILTER"),
+      "non-matching patterns should not fire",
+    );
+  });
+});
+
+describe("scanFileContent — line numbers + file paths", () => {
+  it("reports the line of the violation, not always line 1", () => {
+    const content = [
+      "// line 1: comment",
+      "// line 2: comment",
+      'import { auth } from "@run402/functions";',
+      "// line 4: comment",
+      'const u = await getSession(); // line 5',
+      "",
+    ].join("\n");
+    const findings = scanFileContent(content);
+    const f = findings.find((x) => x.attempted_name === "getSession");
+    assert.ok(f);
+    assert.equal(f.line, 5);
+  });
+
+  it("propagates filePath from the caller", () => {
+    const findings = scanFileContent(`const u = await getSession();`, {
+      filePath: "src/pages/account.astro",
+    });
+    assert.equal(findings[0].file, "src/pages/account.astro");
+  });
+});

package/lib/doctor.mjs

@@ -14,6 +14,11 @@
 import { existsSync, statSync } from "node:fs";
 import { CONFIG_DIR, readAllowance, loadKeyStore } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
+import {
+  resolveScanRoot,
+  scanSourceTree,
+  SCAN_SEVERITY,
+} from "./doctor-source-scan.mjs";
 
 const HELP = `run402 doctor — Health and config diagnostics
 
@@ -21,8 +26,10 @@ Usage:
   run402 doctor [--json] [--verbose]
 
 Options:
-  --json       Emit a structured JSON report on stdout
-  --verbose    Include extra detail (timing, error messages)
+  --json         Emit a structured JSON report on stdout
+  --verbose      Include extra detail (timing, error messages)
+  --no-scan      Skip the source-tree scan (config / health checks only)
+  --scan-dir D   Scan a custom directory instead of \`<cwd>/src\`
 
 Checks performed:
   - Config directory exists and is writable
@@ -30,6 +37,11 @@ Checks performed:
   - Keystore has at least one wallet
   - API_BASE is reachable (network check via /health)
   - Active tier resolves and is not 'past_due' / 'frozen'
+  - Source scan: hallucinated SDK auth names (R402_AUTH_UNKNOWN_EXPORT),
+    state-changing GET handlers (R402_AUTH_STATE_CHANGING_GET),
+    auth.* calls in prerendered pages (R402_AUTH_PRERENDERED),
+    direct mutation of internal.sessions.authz_version
+    (R402_AUTH_AUTHZ_VERSION_PROHIBITED).
 
 Exit codes:
   0  — all checks pass
@@ -44,6 +56,9 @@ export async function run(sub, args = []) {
   }
   const json = all.includes("--json");
   const verbose = all.includes("--verbose");
+  const skipScan = all.includes("--no-scan");
+  const scanDirArgIdx = all.indexOf("--scan-dir");
+  const scanDirOverride = scanDirArgIdx >= 0 ? all[scanDirArgIdx + 1] : null;
 
   const checks = [];
 
@@ -222,6 +237,44 @@ export async function run(sub, args = []) {
     });
   }
 
+  // 7. Source-tree scan (auth-aware-ssr Section 9). Detects hallucinated
+  // SDK names, state-changing GETs, auth.* in prerendered pages, and
+  // direct mutation of internal.sessions.authz_version. Hits with severity
+  // `error` block deploy (`run402 deploy` wraps doctor and respects exit
+  // code). Skipped via --no-scan when the user wants config-only checks.
+  if (!skipScan) {
+    try {
+      const scanRoot = scanDirOverride ?? resolveScanRoot(process.cwd());
+      const findings = scanSourceTree(scanRoot, { cwd: process.cwd() });
+      const errorFindings = findings.filter((f) => f.severity === SCAN_SEVERITY.ERROR);
+      const warnFindings = findings.filter((f) => f.severity === SCAN_SEVERITY.WARN);
+      if (findings.length === 0) {
+        checks.push({ name: "source_scan", status: "ok", value: { scan_root: scanRoot, file_count_with_findings: 0 } });
+      } else {
+        checks.push({
+          name: "source_scan",
+          status: errorFindings.length > 0 ? "error" : "warning",
+          value: {
+            scan_root: scanRoot,
+            findings: errorFindings.length + warnFindings.length,
+            errors: errorFindings.length,
+            warnings: warnFindings.length,
+            details: findings,
+          },
+          hint: errorFindings.length > 0
+            ? "Fix the R402_AUTH_* findings above. `run402 deploy` will refuse to ship until these are resolved."
+            : "Source scan emitted warnings (non-blocking). Review and address when convenient.",
+        });
+      }
+    } catch (err) {
+      checks.push({
+        name: "source_scan",
+        status: "skipped",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
   // 'warning' counts as ok for exit-code purposes — gaps are surfaced in
   // output but don't fail the doctor. Only hard 'error' / 'missing' /
   // 'empty' fail.
@@ -246,6 +299,17 @@ export async function run(sub, args = []) {
       if (c.value && c.value.gaps && Array.isArray(c.value.gaps)) {
         for (const gap of c.value.gaps) console.log(`     • ${gap}`);
       }
+      // Source-scan details — print every finding with file:line + canonical fix-it.
+      if (c.name === "source_scan" && c.value && Array.isArray(c.value.details)) {
+        for (const f of c.value.details) {
+          const sev = f.severity === "error" ? "✗" : "⚠";
+          const location = f.line ? `${f.file}:${f.line}` : f.file;
+          console.log(`     ${sev} ${f.code} ${location}`);
+          console.log(`         ${f.message}`);
+          if (f.canonical_name) console.log(`         fix: ${f.canonical_name}`);
+          if (f.docs) console.log(`         docs: ${f.docs}`);
+        }
+      }
     }
   }
 

package/lib/email.mjs

@@ -16,8 +16,11 @@ Subcommands:
   list   [--limit <n>] [--after <cursor>] [--project <id>]
                                       List sent/received messages (paginated)
   get    <message_id> [--project <id>]  Get a message with replies
-  get-raw <message_id> [--project <id>] [--output <file>]
-                                      Fetch raw RFC-822 bytes (inbound only)
+  get-raw <message_id> --output <file> [--project <id>]
+                                      Fetch raw RFC-822 bytes (inbound only).
+                                      --output is required: bytes are written
+                                      to the file; stdout receives a JSON
+                                      envelope { message_id, bytes, output }.
   reply  <message_id> --html "..." [--text "..."] [--subject "..."] [--from-name "..."] [--project <id>]
                                       Reply to an inbound message (threads via In-Reply-To)
   delete [<slug|mailbox_id>] --confirm [--project <id>]
@@ -123,7 +126,19 @@ compatibility; new code should use 'info'.
   "get-raw": `run402 email get-raw — Fetch raw RFC-822 bytes for an inbound message
 
 Usage:
-  run402 email get-raw <message_id> [--output <file>] [--project <id>]
+  run402 email get-raw <message_id> --output <file> [--project <id>]
+
+Arguments:
+  <message_id>        Inbound message ID
+
+Options:
+  --output <file>     Required: destination file for the raw RFC-822 bytes.
+                      stdout receives a JSON envelope
+                      { message_id, bytes, output } — the MIME body is never
+                      written to stdout, so the CLI stays pipeable.
+  --project <id>      Project ID (defaults to the active project)
+  --mailbox <slug|id> Target a specific mailbox (required when the project
+                      has more than one)
 `,
   create: `run402 email create — Create a project mailbox
 
@@ -321,21 +336,24 @@ async function getRaw(args) {
     fail({
       code: "BAD_USAGE",
       message: "Missing message_id.",
-      hint: "run402 email get-raw <message_id> [--output <file>]",
+      hint: "run402 email get-raw <message_id> --output <file>",
+    });
+  }
+  if (!outputFile) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --output <file>. Raw MIME bytes must be written to a file, not stdout.",
+      hint: "run402 email get-raw <message_id> --output <file>",
+      details: { flag: "--output" },
     });
   }
 
   try {
     const result = await getSdk().email.getRaw(projectId, messageId, { mailbox: mailbox ?? undefined });
     const buf = Buffer.from(result.bytes);
-
-    if (outputFile) {
-      const { writeFileSync } = await import("node:fs");
-      writeFileSync(outputFile, buf);
-      console.log(JSON.stringify({ message_id: messageId, bytes: buf.length, output: outputFile }));
-    } else {
-      process.stdout.write(buf);
-    }
+    const { writeFileSync } = await import("node:fs");
+    writeFileSync(outputFile, buf);
+    console.log(JSON.stringify({ message_id: messageId, bytes: buf.length, output: outputFile }));
   } catch (err) {
     reportSdkError(err);
   }

package/lib/functions.mjs

@@ -15,8 +15,12 @@ Usage:
 Subcommands:
   deploy <id> <name> --file <file> [--timeout <s>] [--memory <mb>] [--deps <pkg,...>] [--schedule <cron>]
                                        Deploy a function to a project
-  invoke <id> <name> [--method <M>] [--body <json>]
-                                       Invoke a deployed function
+  invoke <id> <name> [--method <M>] [--body <json>] [--raw]
+                                       Invoke a deployed function. Default
+                                       wraps the SDK result as JSON on stdout.
+                                       --raw prints the response body verbatim
+                                       (string body → text + newline, JSON
+                                       body → pretty-printed JSON).
   logs   <id> <name> [--tail <n>] [--since <ts>] [--request-id <req_...>] [--follow]
                                        Get function logs
   update <id> <name> [--schedule <cron>] [--schedule-remove] [--timeout <s>] [--memory <mb>]
@@ -99,10 +103,22 @@ Arguments:
 Options:
   --method <M>        HTTP method (default POST)
   --body <json>       Request body (ignored for GET/HEAD)
+  --raw               Skip JSON wrapping. Prints the response body verbatim:
+                      string body → text + trailing newline; JSON body →
+                      pretty-printed JSON. Useful when piping a text/plain
+                      function response to another tool.
+
+Output (default — without --raw):
+  Stdout is a single JSON envelope { http_status, body, duration_ms }.
+  Safe to pipe to jq even when the function returns a plain string.
+  The HTTP status is exposed as http_status (not status) so the payload
+  stays clean of the reserved top-level "status" field used in error
+  envelopes on stderr.
 
 Examples:
   run402 functions invoke prj_abc123 stripe-webhook --body '{"event":"test"}'
   run402 functions invoke prj_abc123 ping --method GET
+  run402 functions invoke prj_abc123 csv --raw > export.csv
 `,
   logs: `run402 functions logs — Fetch or tail function logs
 
@@ -117,7 +133,10 @@ Options:
   --tail <n>          Number of most-recent entries (default 50, max 1000)
   --since <ts>        ISO timestamp or epoch ms; only entries after this
   --request-id <id>   Only entries correlated to this req_... request id
-  --follow            Poll every 3s and stream new entries (Ctrl-C to stop)
+  --follow            Poll every 3s and stream new entries (Ctrl-C to stop).
+                      Emits NDJSON: one JSON log entry per line, no wrapping
+                      "logs:" envelope (the wrapping object is only used in
+                      the non-follow batch mode).
 
 Examples:
   run402 functions logs prj_abc123 stripe-webhook --tail 100
@@ -208,12 +227,13 @@ async function deploy(projectId, name, args) {
 }
 
 async function invoke(projectId, name, args) {
-  assertRequiredProjectAndName(projectId, name, "run402 functions invoke <project_id> <name> [--method <M>] [--body <json>]");
-  assertKnownFlags(args, ["--method", "--body", "--help", "-h"], ["--method", "--body"]);
-  const opts = { method: "POST", body: undefined };
+  assertRequiredProjectAndName(projectId, name, "run402 functions invoke <project_id> <name> [--method <M>] [--body <json>] [--raw]");
+  assertKnownFlags(args, ["--method", "--body", "--raw", "--help", "-h"], ["--method", "--body"]);
+  const opts = { method: "POST", body: undefined, raw: false };
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--method" && args[i + 1]) opts.method = args[++i];
     if (args[i] === "--body" && args[i + 1]) opts.body = args[++i];
+    if (args[i] === "--raw") opts.raw = true;
   }
   const invokeOpts = { method: opts.method };
   if (opts.body !== undefined && opts.method !== "GET" && opts.method !== "HEAD") {
@@ -221,12 +241,17 @@ async function invoke(projectId, name, args) {
   }
   try {
     const result = await getSdk().functions.invoke(projectId, name, invokeOpts);
-    const body = result.body;
-    if (typeof body === "string") {
-      process.stdout.write(body + "\n");
-    } else {
-      console.log(JSON.stringify(body, null, 2));
+    if (opts.raw) {
+      const body = result.body;
+      if (typeof body === "string") {
+        process.stdout.write(body + "\n");
+      } else {
+        console.log(JSON.stringify(body, null, 2));
+      }
+      return;
     }
+    const { status, ...rest } = result;
+    console.log(JSON.stringify({ http_status: status, ...rest }, null, 2));
   } catch (err) {
     reportSdkError(err);
   }
@@ -310,7 +335,7 @@ async function logs(projectId, name, args) {
     }
 
     for (const { entry } of fresh) {
-      console.log(`[${entry.timestamp}] ${entry.message}`);
+      console.log(JSON.stringify(entry));
     }
     if (fresh.length === 0 || !Number.isFinite(nextHighWaterMs)) return;
 

package/lib/init-astro.mjs

@@ -215,11 +215,10 @@ const { title, ogImage, canonical } = Astro.props;
 //   2. DB update.
 //   3. cache.invalidate() so the public URL re-renders fresh on next visit.
 import type { APIRoute } from "astro";
-import { db, getUser, cache } from "@run402/functions";
+import { db, auth, cache } from "@run402/functions";
 
 export const POST: APIRoute = async ({ request }) => {
-  const user = await getUser();
-  if (!user) return new Response("Unauthorized", { status: 401 });
+  const user = await auth.requireUser();
 
   const body = (await request.json()) as { slug: string; title: string; html: string };
   if (!body?.slug) return new Response("Missing slug", { status: 400 });
@@ -236,6 +235,96 @@ export const POST: APIRoute = async ({ request }) => {
     headers: { "content-type": "application/json" },
   });
 };
+`,
+    },
+    {
+      path: "AGENTS.md",
+      content: `# AGENTS.md
+
+This file documents the brutally-small Run402 surface this Astro project
+uses. Coding agents: read this first. The platform is intentionally small —
+there are no other auth helpers, no other client surfaces, and no other
+hidden APIs.
+
+## The auth surface
+
+\`auth\` is the entire user-auth surface. Import from \`@run402/functions\`:
+
+\`\`\`ts
+import { auth } from "@run402/functions";
+
+// In SSR pages and API routes:
+const user = await auth.user();             // Actor | null
+const user = await auth.requireUser();      // Actor; throws R402_AUTH_REQUIRED
+const { user, role } = await auth.requireRole("admin");
+const { user, membership } = await auth.requireMembership("member");
+await auth.requireFresh({ maxAge: "10m", amr: ["passkey"] });
+
+// CSRF for hosted forms (server-side, in <form> rendering):
+const field = auth.csrfField();
+// → <input type="hidden" name="_csrf" value="..." />
+
+// Cross-origin-safe fetch (auto-forwards actor context to same-origin):
+const res = await auth.fetch("/api/internal");  // relative URLs only
+\`\`\`
+
+## The four Never rules
+
+1. **Never \`try\`/\`catch\` auth errors.** Let them bubble. The platform turns
+   \`R402_AUTH_REQUIRED\` into a 303 to \`/auth/sign-in?return_to=…\` and
+   \`R402_AUTH_INSUFFICIENT_ROLE\` into 403 with a fix-it response. Catching
+   them creates silent-null bugs.
+
+2. **Never \`.eq("user_id", user.id)\`.** \`db()\` propagates the actor to
+   PostgREST so RLS enforces ownership server-side. The redundant filter is
+   a code smell that \`run402 doctor\` flags as
+   \`R402_AUTH_REDUNDANT_USER_FILTER\`.
+
+3. **Never set client-supplied actor headers.** \`x-run402-actor-*\`,
+   \`run402.actor.*\`, \`x-r402-actor-*\` are platform-owned channel headers.
+   The gateway strips inbound spoofing attempts and emits
+   \`R402_AUTH_ACTOR_HEADER_SPOOF\` in strict mode.
+
+4. **Never mint a session from a raw \`userId\`.** Use
+   \`auth.sessions.createResponseFromIdentity({ provider, subject, proof, amr })\`
+   with a verified identity proof. No \`createSessionForUserId(uuid)\` API exists.
+
+## Hosted UI components
+
+For sign-in, sign-up, and sign-out chrome, use the platform's
+\`@run402/astro\` components — they emit forms posting to platform hosted
+routes (\`/auth/v1/sign-in\` etc.) with the CSRF token already wired:
+
+\`\`\`astro
+---
+import { SignIn, SignUp, UserButton, SignedIn, SignedOut } from "@run402/astro";
+---
+
+<SignedIn>
+  <UserButton />
+</SignedIn>
+<SignedOut>
+  <SignIn returnTo="/dashboard" />
+</SignedOut>
+\`\`\`
+
+Do NOT roll your own sign-in form. The hosted routes handle CSRF, returnTo
+validation, OAuth provider bridges, and passkey ceremonies.
+
+## Rendering-mode quick map
+
+\`auth.*\` calls run at request time, so the page must be SSR or a
+server-island. Calling \`auth.user()\` from a prerendered page throws
+\`R402_AUTH_PRERENDERED\`.
+
+| Mode                          | When                                | Auth-aware              |
+| ----------------------------- | ----------------------------------- | ----------------------- |
+| SSR (default)                 | Personalized pages                  | \`auth.user()\` works   |
+| Prerendered                   | Marketing pages, never sees actor   | \`auth.*\` throws       |
+| Server island                 | Prerendered page + personalized slot| \`auth.*\` in the island|
+| Client hydrate                | Visibility-only, no SSR pass        | Component hits session  |
+
+For error-code reference: https://run402.com/errors/#R402_AUTH_REQUIRED
 `,
     },
   ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "2.22.0",
+  "version": "2.23.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {