toiljs 0.0.56 → 0.0.57

package/src/cli/diagnostics.ts

@@ -503,6 +503,54 @@ export function checkRestDispatch(f: RestFacts): Check {
     };
 }
 
+/**
+ * Whether the server's tsconfig wires the toilscript language-service plugin. The compiler turns
+ * each `@collection` field into a STATIC handle (`GuestbookDb.totals`) and injects the `@data`
+ * codec / `@user` members, none of which stock TypeScript can see, so without the plugin the editor
+ * false-flags them as TS2339. The plugin (editor-only; never runs under `tsc`) clears them.
+ */
+export function checkServerTsPlugin(present: boolean): Check {
+    return present
+        ? { id: 'server-ts-plugin', label: 'toilscript editor plugin', status: 'pass' }
+        : {
+              id: 'server-ts-plugin',
+              label: 'toilscript editor plugin',
+              status: 'warn',
+              detail: 'server tsconfig is missing the toilscript LS plugin, so the editor wrongly flags @database static collections (e.g. GuestbookDb.totals) and @data members as TS2339',
+              fix: 'Run `toiljs doctor --fix` to add { "plugins": [{ "name": "toilscript/std/ts-plugin.cjs" }] } to your server tsconfig, then pick the workspace TypeScript version and restart the TS server.',
+          };
+}
+
+// --- Security -------------------------------------------------------------------------------------
+
+/** Whether the project uses the auth primitive, and whether its session secret is configured. */
+export interface AuthFacts {
+    /** A server source references the auth primitive (`AuthService` / `@user` / `@auth`). */
+    readonly usesAuth: boolean;
+    /** `AUTH_SESSION_SECRET` is assigned a non-empty value in the local secrets source. */
+    readonly sessionSecretSet: boolean;
+}
+
+/**
+ * Flags the silent insecure default behind the auth primitive. When a project uses sessions but
+ * never sets `AUTH_SESSION_SECRET`, the server falls back to a PUBLISHED dev key (see
+ * `server/globals/auth.ts`), so anyone can forge a session cookie and skip login. doctor can only
+ * see the local secrets source, so it WARNS (the real secret may live on the deploy target) rather
+ * than failing CI on a false positive.
+ */
+export function checkAuthSecrets(f: AuthFacts): Check {
+    if (!f.usesAuth || f.sessionSecretSet) {
+        return { id: 'auth-secrets', label: 'Session secret', status: 'pass' };
+    }
+    return {
+        id: 'auth-secrets',
+        label: 'Session secret',
+        status: 'warn',
+        detail: 'auth is used but AUTH_SESSION_SECRET is unset: sessions fall back to a PUBLISHED key, so anyone can forge a session cookie and skip login',
+        fix: 'Set AUTH_SESSION_SECRET to a long random value in .env.secrets (local) and on your deploy target (also AUTH_OPRF_SEED / AUTH_KEM_SK if you use password login). Generate one: node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'hex\'))".',
+    };
+}
+
 // --- Summary --------------------------------------------------------------------------------------
 
 export function summarize(groups: readonly CheckGroup[]): DoctorSummary {

package/src/cli/doctor.ts

@@ -18,7 +18,9 @@ import {
 } from 'toiljs/compiler';
 
 import {
+    type AuthFacts,
     type Check,
+    checkAuthSecrets,
     checkBasePath,
     checkConfigLoads,
     checkDevScripts,
@@ -37,6 +39,7 @@ import {
     checkRpcWiring,
     checkSeoUrl,
     checkServerEntry,
+    checkServerTsPlugin,
     type CheckStatus,
     checkStyling,
     checkToilconfig,
@@ -231,6 +234,61 @@ function gatherRestFacts(root: string, toilconfig: Record<string, unknown> | nul
     return { hasControllers, dispatched };
 }
 
+/** Whether `.env.secrets` assigns `key` a non-empty value (a bare `KEY=` counts as unset). */
+function secretDefined(root: string, key: string): boolean {
+    const raw = readFile(path.join(root, '.env.secrets'));
+    if (raw === null) return false;
+    return new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=\\s*\\S`, 'm').test(raw);
+}
+
+/**
+ * Whether the server uses the auth primitive (so a missing session secret matters) and whether
+ * `AUTH_SESSION_SECRET` is set locally. `getSecure` reads ONLY the `.env.secrets` bucket, so that
+ * is the source we check; on a deploy target the secret lives on the dashboard instead.
+ */
+function gatherAuthFacts(root: string, toilconfig: Record<string, unknown> | null): AuthFacts {
+    let usesAuth = false;
+    for (const src of serverSources(root, toilconfig)) {
+        if (/\bAuthService\b/.test(src) || /@user\b/.test(src) || /@auth\b/.test(src)) {
+            usesAuth = true;
+            break;
+        }
+    }
+    return { usesAuth, sessionSecretSet: secretDefined(root, 'AUTH_SESSION_SECRET') };
+}
+
+/** The toilscript language-service plugin id wired into a server tsconfig. */
+const TS_PLUGIN_NAME = 'toilscript/std/ts-plugin.cjs';
+
+/**
+ * The server's tsconfig.json (the one beside a toilconfig entry, conventionally
+ * `server/tsconfig.json`), or null if none exists. That is the project the editor uses for server
+ * files, so it is where the toilscript LS plugin must live.
+ */
+function serverTsconfigPath(root: string, toilconfig: Record<string, unknown> | null): string | null {
+    const dirs = new Set<string>();
+    const entries = Array.isArray(toilconfig?.entries)
+        ? (toilconfig.entries as unknown[]).filter((e): e is string => typeof e === 'string')
+        : [];
+    for (const e of entries) dirs.add(path.dirname(path.resolve(root, e)));
+    if (dirs.size === 0) dirs.add(path.join(root, 'server'));
+    for (const dir of dirs) {
+        const p = path.join(dir, 'tsconfig.json');
+        if (fs.existsSync(p)) return p;
+    }
+    return null;
+}
+
+/** Whether a parsed tsconfig's `compilerOptions.plugins` references the toilscript LS plugin. */
+function tsconfigHasToilPlugin(tsconfig: Record<string, unknown> | null): boolean {
+    const plugins = asRecord(tsconfig?.compilerOptions)?.plugins;
+    if (!Array.isArray(plugins)) return false;
+    return plugins.some((p) => {
+        const name = asRecord(p)?.name;
+        return typeof name === 'string' && name.includes('ts-plugin');
+    });
+}
+
 interface RpcFixResult {
     /** Files written. */
     readonly changed: string[];
@@ -471,6 +529,64 @@ function applyPrettierFix(root: string, pkg: Record<string, unknown> | null): Rp
     return { changed, skipped };
 }
 
+/**
+ * Wires the editor side of the toilscript server: adds the LS plugin to the server tsconfig (so the
+ * editor stops false-flagging `@database` static collections / `@data` members), and points VS Code
+ * at the workspace TypeScript (so it actually loads that plugin). Idempotent; only writes real
+ * changes, and skips (with a note) configs it can't safely edit (a tsconfig with comments).
+ */
+function applyServerEditorFix(root: string, toilconfig: Record<string, unknown> | null): RpcFixResult {
+    const changed: string[] = [];
+    const skipped: string[] = [];
+
+    // 1. The LS plugin in the server tsconfig.
+    const tsPath = serverTsconfigPath(root, toilconfig);
+    if (tsPath === null) {
+        skipped.push('server/tsconfig.json (not found; add the toilscript ts-plugin by hand)');
+    } else {
+        const rel = path.relative(root, tsPath);
+        const raw = readFile(tsPath);
+        const parsed = raw !== null ? readJsonObject(tsPath) : null;
+        if (parsed === null) {
+            skipped.push(`${rel} (JSON with comments; add the "${TS_PLUGIN_NAME}" plugin by hand)`);
+        } else if (!tsconfigHasToilPlugin(parsed)) {
+            const co = asRecord(parsed.compilerOptions) ?? {};
+            const existingPlugins: unknown[] = Array.isArray(co.plugins)
+                ? (co.plugins as unknown[])
+                : [];
+            co.plugins = [...existingPlugins, { name: TS_PLUGIN_NAME }];
+            parsed.compilerOptions = co;
+            writeFile(tsPath, JSON.stringify(parsed, null, 4) + '\n');
+            changed.push(rel);
+        }
+    }
+
+    // 2. Make VS Code use the workspace TypeScript, so it loads the plugin above.
+    const vsPath = path.join(root, '.vscode', 'settings.json');
+    const vsRaw = readFile(vsPath);
+    const vs = vsRaw !== null ? readJsonObject(vsPath) : {};
+    if (vs === null) {
+        skipped.push('.vscode/settings.json (unparseable; set typescript.tsdk by hand)');
+    } else {
+        let touched = false;
+        if (vs['typescript.tsdk'] !== 'node_modules/typescript/lib') {
+            vs['typescript.tsdk'] = 'node_modules/typescript/lib';
+            touched = true;
+        }
+        if (vs['typescript.enablePromptUseWorkspaceTsdk'] !== true) {
+            vs['typescript.enablePromptUseWorkspaceTsdk'] = true;
+            touched = true;
+        }
+        if (touched) {
+            fs.mkdirSync(path.dirname(vsPath), { recursive: true });
+            writeFile(vsPath, JSON.stringify(vs, null, 4) + '\n');
+            changed.push('.vscode/settings.json');
+        }
+    }
+
+    return { changed, skipped };
+}
+
 /** Reads the framework's own package.json (engines + peerDependencies) for the requirements. */
 function frameworkMeta(): { node: string; peers: Record<string, string> } {
     const pkgPath = path.resolve(
@@ -631,20 +747,37 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
     const peerName = (n: string): Check => checkPeer(n, deps[n] ?? null, meta.peers[n] ?? '*');
     const peerChecks = Object.keys(meta.peers).map(peerName);
 
-    // Server tooling (RPC wiring + the prettier plugin): optionally fix in place, then re-read.
+    // Server tooling (RPC wiring + the prettier plugin + the editor LS plugin): optionally fix in
+    // place, then re-read.
     const rpcFix = serverPresent && opts.fix ? applyRpcFix(root) : null;
     const prettierFix = serverPresent && opts.fix ? applyPrettierFix(root, projectPkg) : null;
+    const editorFix = serverPresent && opts.fix ? applyServerEditorFix(root, toilconfig) : null;
     const rpcFacts = gatherRpcFacts(root);
     const restFacts = gatherRestFacts(root, toilconfig);
+    const authFacts = gatherAuthFacts(root, toilconfig);
     const prettierPresent = prettierPluginPresent(
         root,
         readJsonObject(path.join(root, 'package.json')),
     );
+    // Only assess the LS plugin when a server tsconfig exists and parses; an absent or
+    // commented one is left to the user rather than warned on.
+    const serverTsPath = serverPresent ? serverTsconfigPath(root, toilconfig) : null;
+    const serverTsParsed = serverTsPath ? readJsonObject(serverTsPath) : null;
+    const serverTsPluginPresent =
+        serverTsPath === null || serverTsParsed === null ? true : tsconfigHasToilPlugin(serverTsParsed);
     const serverFix =
-        rpcFix || prettierFix
+        rpcFix || prettierFix || editorFix
             ? {
-                  changed: [...(rpcFix?.changed ?? []), ...(prettierFix?.changed ?? [])],
-                  skipped: [...(rpcFix?.skipped ?? []), ...(prettierFix?.skipped ?? [])],
+                  changed: [
+                      ...(rpcFix?.changed ?? []),
+                      ...(prettierFix?.changed ?? []),
+                      ...(editorFix?.changed ?? []),
+                  ],
+                  skipped: [
+                      ...(rpcFix?.skipped ?? []),
+                      ...(prettierFix?.skipped ?? []),
+                      ...(editorFix?.skipped ?? []),
+                  ],
               }
             : null;
 
@@ -706,11 +839,17 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
                       checkRpcWiring(rpcFacts),
                       checkRestDispatch(restFacts),
                       checkPrettierPlugin(prettierPresent),
+                      checkServerTsPlugin(serverTsPluginPresent),
                   ]
                 : [checkToilconfig(false)],
         },
     ];
 
+    // Security checks only apply to a server (no server, no sessions to forge).
+    if (serverPresent) {
+        groups.push({ title: 'Security', checks: [checkAuthSecrets(authFacts)] });
+    }
+
     const summary = summarize(groups);
     if (opts.json) {
         process.stdout.write(JSON.stringify({ groups, summary, fixed: serverFix }, null, 2) + '\n');
@@ -731,14 +870,14 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
 function renderRpcFix(result: RpcFixResult): void {
     const out: string[] = [];
     if (result.changed.length > 0) {
-        out.push('  ' + success('fixed RPC wiring') + dim(`  ${result.changed.join(', ')}`));
+        out.push('  ' + success('fixed server wiring') + dim(`  ${result.changed.join(', ')}`));
         if (result.changed.includes('package.json')) {
             out.push(
                 '  ' + dim('run your installer (npm/pnpm/yarn) if the toilscript version changed.'),
             );
         }
     } else {
-        out.push('  ' + dim('RPC wiring already in place, nothing to fix.'));
+        out.push('  ' + dim('server wiring already in place, nothing to fix.'));
     }
     for (const item of result.skipped) out.push('  ' + warn('skipped') + dim(`  ${item}`));
     process.stdout.write(out.join('\n') + '\n\n');

package/src/client/dev/devtools.tsx

@@ -171,7 +171,11 @@ function loadPrefs(): Prefs {
     }
 }
 
-let prefs: Prefs = typeof localStorage !== 'undefined' ? loadPrefs() : defaultPrefs;
+// Gate on `window`, not `localStorage`: the devtools are browser-only, and merely
+// touching the bare `localStorage` global under SSR/Node trips its experimental-API
+// warning ("localStorage is not available because --localstorage-file ..."). In the
+// browser `loadPrefs()` reads it; under SSR we keep the defaults and never touch it.
+let prefs: Prefs = typeof window !== 'undefined' ? loadPrefs() : defaultPrefs;
 const prefListeners = new Set<() => void>();
 function setPrefs(next: Partial<Prefs>): void {
     prefs = { ...prefs, ...next };

package/src/client/routing/hooks.ts

@@ -101,10 +101,12 @@ function useLocationSubscription(): void {
     );
 }
 
-/** Subscribes to and returns the current `location.pathname`. */
+/** Subscribes to and returns the current `location.pathname`. SSR-safe: during a
+ *  server render (build-time template extraction / edge SSR) there is no `window`,
+ *  so it reports `/`; the client recomputes on hydration. */
 export function useLocation(): string {
     useLocationSubscription();
-    return window.location.pathname;
+    return typeof window === 'undefined' ? '/' : window.location.pathname;
 }
 
 /** Alias of {@link useLocation}: the current `location.pathname`. */
@@ -115,7 +117,7 @@ export function usePathname(): string {
 /** The current query string as a `URLSearchParams`, re-read on every navigation. */
 export function useSearchParams(): URLSearchParams {
     useLocationSubscription();
-    const search = window.location.search;
+    const search = typeof window === 'undefined' ? '' : window.location.search;
     return useMemo(() => new URLSearchParams(search), [search]);
 }
 

package/src/compiler/template-build.ts

@@ -17,6 +17,7 @@
  */
 
 import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 
 import { type ComponentType, type Context, createElement, type ReactNode } from 'react';
@@ -55,6 +56,14 @@ export interface RouteRenderInput {
     setSsrBuild: (on: boolean) => void;
     /** The built HTML shell (with hashed script tags) to splice into. */
     shell: string;
+    /** React's `createElement` from the SAME instance the page imports (the Vite
+     * SSR graph), so element creation and the components' hooks share one React.
+     * Defaults to the compiler's own React when omitted (unit tests). Mixing two
+     * React copies leaves the hook dispatcher null ("Cannot read properties of
+     * null (reading 'useRef')"). */
+    createElement?: typeof createElement;
+    /** `renderToStaticMarkup` paired with {@link createElement}'s React. */
+    renderToStaticMarkup?: typeof renderToStaticMarkup;
 }
 
 export interface TemplateArtifacts {
@@ -76,13 +85,14 @@ export function assembleRouteElement(
     layouts: ComponentType<{ children?: ReactNode }>[],
     loaderData: unknown,
     loaderContext: Context<unknown> | null,
+    h: typeof createElement = createElement,
 ): ReactNode {
-    let node: ReactNode = createElement(Page);
+    let node: ReactNode = h(Page);
     if (loaderContext) {
-        node = createElement(loaderContext.Provider, { value: loaderData }, node);
+        node = h(loaderContext.Provider, { value: loaderData }, node);
     }
     for (let i = layouts.length - 1; i >= 0; i--) {
-        node = createElement(layouts[i], null, node);
+        node = h(layouts[i], null, node);
     }
     return node;
 }
@@ -98,16 +108,19 @@ export function injectIntoShell(shell: string, routeHtml: string): string {
 
 /** Render one route to its template artifacts (pure given its inputs). */
 export function extractRouteTemplate(input: RouteRenderInput): TemplateArtifacts {
+    const h = input.createElement ?? createElement;
+    const render = input.renderToStaticMarkup ?? renderToStaticMarkup;
     const element = assembleRouteElement(
         input.Page,
         input.layouts,
         input.loaderData,
         input.loaderContext,
+        h,
     );
     input.setSsrBuild(true);
     let routeHtml: string;
     try {
-        routeHtml = renderToStaticMarkup(element);
+        routeHtml = render(element);
     } finally {
         input.setSsrBuild(false);
     }
@@ -188,6 +201,28 @@ export async function extractTemplates(
         LoaderDataContext: Context<unknown>;
     };
 
+    // Install the ambient `Toil` global (+ registered pages / transitions) exactly
+    // as the client entry does, by evaluating the generated globals module. Without
+    // it, any layout or component using `Toil` (e.g. `<Toil.Head>`, `<Toil.Link>`)
+    // throws "Toil is not defined" during extraction, so the route is silently
+    // skipped and falls back to client rendering.
+    const globalsModule = path.join(cfg.toilDir, 'globals.ts');
+    if (fs.existsSync(globalsModule)) {
+        await server.ssrLoadModule(globalsModule);
+    }
+
+    // Render with the SAME React the components import. Vite externalizes react
+    // (CommonJS) for SSR and resolves it from the app root, so resolve it the same
+    // way (from cfg.root) rather than using the compiler's own copy. Two React
+    // copies leave the hook dispatcher null, so a layout/component hook
+    // (`useLocation` -> `useRef`) throws. (`ssrLoadModule('react')` can't be used:
+    // Vite's SSR runner cannot evaluate the CJS module -> "module is not defined".)
+    const appRequire = createRequire(path.join(cfg.root, 'package.json'));
+    const react = appRequire('react') as { createElement: typeof createElement };
+    const reactDomServer = appRequire('react-dom/server') as {
+        renderToStaticMarkup: typeof renderToStaticMarkup;
+    };
+
     const ssrDir = path.join(outDir, '_ssr');
     const hostsTmplDir = path.join(cfg.root, 'hosts', hostName, '_tmpl');
     const generated: string[] = [];
@@ -232,6 +267,8 @@ export async function extractTemplates(
                     loaderContext: client.LoaderDataContext,
                     setSsrBuild: client.__setSsrBuild,
                     shell,
+                    createElement: react.createElement,
+                    renderToStaticMarkup: reactDomServer.renderToStaticMarkup,
                 });
                 writeTemplateArtifacts(ssrDir, art);
                 fs.mkdirSync(hostsTmplDir, { recursive: true });

package/src/devserver/database.ts

@@ -110,7 +110,7 @@ function collOf(db: DbDevState, handle: number): string | null {
 export function buildDatabaseImports(
     ref: MemoryRef,
     db: DbDevState,
-): Record<string, (...args: number[]) => number> {
+): Record<string, (...args: number[]) => number | bigint> {
     return {
         'data.resolve_collection': (
             namePtr: number,
@@ -586,6 +586,24 @@ export function buildDatabaseImports(
             db.lastResult = null;
             return v.length;
         },
+
+        // `data.result_schema_version() -> i64`: the schema version the last
+        // value-returning read's row was written under, so the guest decoder can
+        // default new fields / reject an unknown layout. The production edge
+        // surfaces the real per-row version; this single-process, single-version
+        // dev store has no historical versions (data is always the current
+        // layout), so it returns -1 ("no version tracked"), which the decoder
+        // treats as "decode with the current layout". An i64 result returns a
+        // BigInt in Node's WASM ABI. (Per-row versions in dev would need catalog
+        // decoding; a follow-up if dev must exercise cross-version decode.)
+        'data.result_schema_version': (): bigint => -1n,
+
+        // `data.write_allowed() -> i32`: 1 if the current call may write. Used by
+        // the rewrite-on-read convergence after a lazy migration. The dev store is
+        // single-version, so result_schema_version always returns -1 and no
+        // migration dispatch ever fires - the convergence write is never reached
+        // here regardless. Returns 1 (the dev store permits writes) for parity.
+        'data.write_allowed': (): number => 1,
     };
 }
 

package/src/devserver/host.ts

@@ -112,6 +112,34 @@ function readGuestString(ref: MemoryRef, ptr: number): string {
     return m.toString('utf16le', ptr, ptr + byteLen);
 }
 
+/**
+ * Framework auth secrets that, when unset, SILENTLY fall back to a published,
+ * well-known dev default inside the guest (see `server/globals/auth.ts`). Reading
+ * one that is absent means the wasm is about to sign sessions / derive keys under
+ * a value anyone can read off npm, so we surface it. Harmless for local dev; a
+ * deployed node MUST set these out of band (`.env.secrets` / the dashboard).
+ */
+const INSECURE_DEFAULT_SECRETS: Record<string, string> = {
+    AUTH_SESSION_SECRET:
+        'session cookies will be signed with a PUBLISHED key, so anyone can forge one and skip login',
+    AUTH_OPRF_SEED: 'the password OPRF seed will be the published dev value',
+    AUTH_KEM_SK: 'the server ML-KEM secret key will be the published dev value',
+};
+
+/** Warned-once set, keyed by secret name, so a hot path cannot spam the log. */
+const warnedInsecureSecrets = new Set<string>();
+
+/** Warn (once per process) that an absent framework secret falls back to a public default. */
+function warnInsecureSecretFallback(key: string): void {
+    if (warnedInsecureSecrets.has(key)) return;
+    warnedInsecureSecrets.add(key);
+    process.stdout.write(
+        `  ⚠ ${key} is not set: ${INSECURE_DEFAULT_SECRETS[key]}. ` +
+            `Fine for local dev, but a deployed node MUST set it in .env.secrets (or on your deploy target). ` +
+            `Generate one: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"\n`,
+    );
+}
+
 /**
  * Resolve one `Environment.get`/`getSecure` lookup against the dev env source
  * and write it into the guest buffer, with the edge's return protocol: the value
@@ -128,7 +156,10 @@ function envLookup(
 ): number {
     const key = readBytes(ref, keyPtr, keyLen).toString('utf8');
     const val = secure ? devEnvGetSecure(key) : devEnvGet(key);
-    if (val === null) return -2; // ABSENT
+    if (val === null) {
+        if (secure && key in INSECURE_DEFAULT_SECRETS) warnInsecureSecretFallback(key);
+        return -2; // ABSENT
+    }
     const bytes = Buffer.from(val, 'utf8');
     if (bytes.length > outCap) return -1; // TOO_SMALL
     const m = mem(ref);

package/test/devserver-secrets.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { buildHostImports, freshDispatchState, type MemoryRef } from '../src/devserver/host.js';
+
+/**
+ * The dev host warns (once) when the guest reads a framework auth secret that is unset, since the
+ * wasm then falls back to a PUBLISHED dev key (see `server/globals/auth.ts`). This is the visible
+ * counterpart to the silent fallback: without it, a server running on the dev host would sign
+ * sessions under a forgeable key with no signal. The repo root has no `.env.secrets`, so every
+ * lookup below is absent.
+ */
+function setup() {
+    const memory = new WebAssembly.Memory({ initial: 1 });
+    const ref: MemoryRef = { memory };
+    const env = buildHostImports(ref, freshDispatchState()).env as Record<
+        string,
+        (...a: number[]) => number
+    >;
+    const buf = Buffer.from(memory.buffer);
+    return { env, buf };
+}
+
+/** Writes `key` at offset 0 and runs `env_get_secure`, returning its status code. */
+function getSecure(env: Record<string, (...a: number[]) => number>, buf: Buffer, key: string): number {
+    const b = Buffer.from(key, 'utf8');
+    b.copy(buf, 0);
+    return env.env_get_secure(0, b.length, 256, 256);
+}
+
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+
+describe('dev host secret fallback warning', () => {
+    it('warns once that an unset AUTH_SESSION_SECRET falls back to a published key', () => {
+        const write = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+        const { env, buf } = setup();
+
+        expect(getSecure(env, buf, 'AUTH_SESSION_SECRET')).toBe(-2); // ABSENT
+        // Repeated reads (a fresh wasm instance per request hits this every time) warn only once.
+        expect(getSecure(env, buf, 'AUTH_SESSION_SECRET')).toBe(-2);
+
+        const warnings = write.mock.calls
+            .map((c) => String(c[0]))
+            .filter((s) => s.includes('AUTH_SESSION_SECRET'));
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]).toContain('forge');
+        expect(warnings[0]).toContain('deployed node');
+    });
+
+    it('does not warn for an ordinary (non-framework) absent secret', () => {
+        const write = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+        const { env, buf } = setup();
+
+        expect(getSecure(env, buf, 'STRIPE_KEY')).toBe(-2); // ABSENT, no published default
+        const warned = write.mock.calls.some((c) => String(c[0]).includes('STRIPE_KEY'));
+        expect(warned).toBe(false);
+    });
+});

package/test/doctor.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
 import {
+    checkAuthSecrets,
     checkBasePath,
     checkDevScripts,
     checkDuplicatePatterns,
@@ -14,6 +15,7 @@ import {
     checkRootElement,
     checkRpcWiring,
     checkSeoUrl,
+    checkServerTsPlugin,
     checkStyling,
     findRelativeAssets,
     satisfiesMin,
@@ -189,6 +191,34 @@ describe('checkPrettierPlugin', () => {
     });
 });
 
+describe('checkServerTsPlugin', () => {
+    it('passes when the toilscript LS plugin is wired', () => {
+        expect(checkServerTsPlugin(true).status).toBe('pass');
+    });
+    it('warns (not fails) when missing, naming the TS2339 false positive and --fix', () => {
+        const c = checkServerTsPlugin(false);
+        expect(c.status).toBe('warn');
+        expect(c.detail).toContain('TS2339');
+        expect(c.fix).toContain('--fix');
+    });
+});
+
+describe('checkAuthSecrets', () => {
+    it('passes when auth is not used', () => {
+        expect(checkAuthSecrets({ usesAuth: false, sessionSecretSet: false }).status).toBe('pass');
+    });
+    it('passes when auth is used and the session secret is set', () => {
+        expect(checkAuthSecrets({ usesAuth: true, sessionSecretSet: true }).status).toBe('pass');
+    });
+    it('warns about session forgery when auth is used but the secret is unset', () => {
+        const c = checkAuthSecrets({ usesAuth: true, sessionSecretSet: false });
+        expect(c.status).toBe('warn');
+        expect(c.detail).toContain('AUTH_SESSION_SECRET');
+        expect(c.detail).toContain('forge');
+        expect(c.fix).toContain('.env.secrets');
+    });
+});
+
 describe('summarize', () => {
     it('tallies pass/warn/fail across groups', () => {
         const groups: CheckGroup[] = [