@nerdsystem/sdk 0.0.13 → 0.0.14

package/README.md

@@ -15,6 +15,28 @@ export default app;
 
 Start from the template with `npx nerdsystem init my-app`. Documentation lives in the template's `AGENTS.md` and `.claude/skills/nerdsystem/SKILL.md`.
 
+## Testing who can reach what
+
+`@nerdsystem/sdk/testing` runs your app's real routes in-process, as a signed-out visitor and as made-up signed-in users. It is for tests only; never import it from server code.
+
+```ts
+import { testApp } from "@nerdsystem/sdk/testing";
+
+const t = await testApp(app, { env }); // env needs DB and STORAGE, e.g. from wrangler's getPlatformProxy()
+
+// Every route the app declares must refuse a signed-out visitor, except the ones named here.
+await t.expectEveryRouteLocked({ public: ["GET /api/health"] });
+
+// One person's data is out of reach for another.
+const alice = await t.as("alice");
+const bob = await t.as("bob");
+const { todo } = await (await alice.post("/api/todos", { title: "mine" })).json();
+await t.expectHiddenFrom(bob, "DELETE", `/api/todos/${todo.id}`);
+await t.expectNotListed(bob, "/api/todos", "mine");
+```
+
+Apps created with `nerd init` ship with these tests in `test/`, and `nerd check` runs them before every deploy.
+
 ## Adding the SDK to an existing Vite + Hono app
 
 `nerd init` is the only scaffold and it refuses a folder that is not empty. A Vite client with a Hono server can be brought into the same shape by hand; `nerd check` refuses anything else; steps 1, 2, 4, 6, and 7 are its checks, and steps 3 and 5 are what the deploy relies on.

package/dist/auth/jwks.d.ts

@@ -1,4 +1,11 @@
+import type { HonoJsonWebKey } from "hono/utils/jwt/jws";
 import type { NerdUser } from "../env";
+/**
+ * Puts keys in the cache as if they had been fetched. Only `@nerdsystem/sdk/testing` calls this, so an app's
+ * tests can sign in made-up users without the network; `nerd check` refuses an app whose server code imports
+ * the testing module.
+ */
+export declare function seedJwks(jwksUrl: string, keys: HonoJsonWebKey[]): void;
 export interface VerifiedToken extends NerdUser {
     exp: number;
 }

package/dist/auth/jwks.js

@@ -17,6 +17,14 @@ async function keysFor(jwksUrl, kid, fetchImpl) {
     // Stale, or an unknown kid (key rotation): refetch.
     return fetchKeys(jwksUrl, fetchImpl);
 }
+/**
+ * Puts keys in the cache as if they had been fetched. Only `@nerdsystem/sdk/testing` calls this, so an app's
+ * tests can sign in made-up users without the network; `nerd check` refuses an app whose server code imports
+ * the testing module.
+ */
+export function seedJwks(jwksUrl, keys) {
+    cache.set(jwksUrl, { keys, fetchedAt: Date.now() });
+}
 /** Verifies an access token offline against the platform JWKS (cached per isolate). Returns null if invalid. */
 export async function verifyAccessToken(token, opts) {
     const fetchImpl = opts.fetchImpl ?? fetch;

package/dist/testing.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Test harness for apps on nerdsystem: `import { testApp } from "@nerdsystem/sdk/testing"`.
+ *
+ * It answers the two questions that matter most and that nobody looking at the screen can see:
+ * can a stranger reach this route, and can one user reach another user's data? It calls the app's own
+ * routes in-process (no server, no network) as a signed-out visitor and as made-up signed-in users, and
+ * writes what it checked to `.nerd/access-report.json`, which `nerd check` reads before every deploy.
+ *
+ * Never import this from server code. It can sign in anyone; it exists for tests only.
+ */
+import type { Hono } from "hono";
+type AnyApp = Pick<Hono, "request" | "routes">;
+type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** A route as the report and the `public` list name it, e.g. "GET /api/todos/:id". */
+export type RouteName = `${Method} ${string}`;
+export interface TestClient {
+    /** Who this client is signed in as, or null for the signed-out visitor. */
+    readonly user: {
+        id: string;
+        email: string;
+        name: string;
+        roles: string[];
+    } | null;
+    request(method: Method, path: string, body?: unknown): Promise<Response>;
+    get(path: string): Promise<Response>;
+    post(path: string, body?: unknown): Promise<Response>;
+    put(path: string, body?: unknown): Promise<Response>;
+    patch(path: string, body?: unknown): Promise<Response>;
+    delete(path: string, body?: unknown): Promise<Response>;
+}
+export interface AccessReport {
+    version: 1;
+    /** Every route the app declares outside the SDK's own sign-in routes. */
+    routes: RouteName[];
+    /** Routes a signed-out visitor was refused on (401 or 403). */
+    locked: RouteName[];
+    /** Routes the test declared open to everyone, on purpose. */
+    public: RouteName[];
+    /** Routes with an id in the path that a second signed-in user was refused on (403 or 404). */
+    ownerChecked: RouteName[];
+    /** Routes with an id in the path that the test declared shared between users, on purpose. */
+    shared: RouteName[];
+    /** True once `expectEveryRouteLocked` has run to the end. */
+    everyRouteChecked: boolean;
+}
+export interface TestAppOptions<E> {
+    /** The bindings the app runs with: at least `DB` and `STORAGE`, e.g. from wrangler's `getPlatformProxy()`. */
+    env: E;
+    /** Where the sign-in routes are mounted. Default "/api/auth". */
+    authPath?: string;
+    /** Called with the finished report after every change; the starter app writes it to `.nerd/access-report.json`. */
+    onReport?: (report: AccessReport) => void | Promise<void>;
+}
+export interface TestHarness {
+    /** A signed-out visitor. */
+    readonly anonymous: TestClient;
+    /** A signed-in user. The same name is the same person every time; a different name is a different person. */
+    as(name: string, opts?: {
+        roles?: string[];
+    }): Promise<TestClient>;
+    /** Every route the app declares, as "METHOD /path". */
+    routes(): RouteName[];
+    /**
+     * Calls every route as a signed-out visitor and throws unless each one answers 401 or 403. Routes that
+     * are meant to be open to everyone are named in `public`; a route named there that is in fact locked,
+     * or that does not exist, also throws, so the list cannot go stale. A new route is covered the moment
+     * it exists, without touching the test.
+     */
+    expectEveryRouteLocked(opts?: {
+        public?: RouteName[];
+    }): Promise<void>;
+    /**
+     * Throws unless `other` is refused (403 or 404) on a route that belongs to someone else, e.g.
+     * `await t.expectHiddenFrom(bob, "PATCH", `/api/todos/${id}`, { done: true })`.
+     */
+    expectHiddenFrom(other: TestClient, method: Method, path: string, body?: unknown): Promise<void>;
+    /** Throws if the response `other` gets from `path` contains `needle`, e.g. the title of someone else's row in a list. */
+    expectNotListed(other: TestClient, path: string, needle: string): Promise<void>;
+    /** Declares that a route with an id in its path is meant to be readable by every signed-in user. Say why. */
+    shared(route: RouteName, reason: string): void;
+    /** What has been checked so far. */
+    report(): AccessReport;
+}
+/**
+ * Wraps the app for tests. `env` is merged with the three NERD_ values the SDK needs, pointed at a
+ * made-up auth service whose keys this harness holds, so signed-in test users are real to the app's
+ * `requireAuth()` and `requireRole()` and nothing leaves the machine.
+ */
+export declare function testApp<E extends object>(app: AnyApp, options: TestAppOptions<E>): Promise<TestHarness>;
+/** The routes with an id in the path, which `nerd check` expects an owner test (or a `shared` declaration) for. */
+export declare function routesWithId(report: AccessReport): RouteName[];
+export {};

package/dist/testing.js

@@ -0,0 +1,164 @@
+import { sign } from "hono/jwt";
+import { seedJwks } from "./auth/jwks";
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+const TEST_AUTH_URL = "https://auth.test.invalid/auth/v1/t/prj_test";
+const TEST_PROJECT_ID = "prj_test";
+function pattern(path) {
+    const src = path
+        .split("/")
+        .map((seg) => (seg.startsWith(":") ? "[^/]+" : seg === "*" ? ".*" : seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")))
+        .join("/");
+    return new RegExp(`^${src}/?$`);
+}
+/** A concrete path for a declared one: every `:param` becomes "1", which no fresh test database has a row for. */
+function sample(path) {
+    return path
+        .split("/")
+        .map((seg) => (seg.startsWith(":") ? "1" : seg === "*" ? "x" : seg))
+        .join("/");
+}
+function hasId(path) {
+    return path.split("/").some((seg) => seg.startsWith(":"));
+}
+/**
+ * Wraps the app for tests. `env` is merged with the three NERD_ values the SDK needs, pointed at a
+ * made-up auth service whose keys this harness holds, so signed-in test users are real to the app's
+ * `requireAuth()` and `requireRole()` and nothing leaves the machine.
+ */
+export async function testApp(app, options) {
+    const authPath = (options.authPath ?? "/api/auth").replace(/\/$/, "");
+    const pair = (await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]));
+    const kid = `test-${crypto.randomUUID()}`;
+    const priv = { ...(await crypto.subtle.exportKey("jwk", pair.privateKey)), kid, alg: "ES256" };
+    const pub = { ...(await crypto.subtle.exportKey("jwk", pair.publicKey)), kid, alg: "ES256", use: "sig" };
+    seedJwks(`${TEST_AUTH_URL}/.well-known/jwks.json`, [pub]);
+    const env = { ...options.env, NERD_PROJECT_ID: TEST_PROJECT_ID, NERD_AUTH_URL: TEST_AUTH_URL, NERD_AUTH_SECRET: "nas_test_only" };
+    const declared = () => {
+        const seen = new Map();
+        for (const r of app.routes) {
+            const method = r.method.toUpperCase();
+            // Middleware registers as ALL; a handler registered with app.all() on a real path counts for every method.
+            const isHandlerPath = !r.path.endsWith("*");
+            if (r.path === authPath || r.path.startsWith(`${authPath}/`))
+                continue;
+            const methods = method === "ALL" ? (isHandlerPath ? METHODS : []) : METHODS.includes(method) ? [method] : [];
+            for (const m of methods) {
+                const name = `${m} ${r.path}`;
+                if (!seen.has(name))
+                    seen.set(name, { method: m, path: r.path, name });
+            }
+        }
+        // app.use("/x/*") also lands in app.routes with a concrete method when written as app.get("/x/*", mw); those end in * and are skipped above.
+        return [...seen.values()];
+    };
+    const nameFor = (method, path) => {
+        const clean = path.split("?")[0] ?? path;
+        // Prefer the most literal match: "/api/todos/archive" over "/api/todos/:id".
+        const hits = declared().filter((r) => r.method === method && pattern(r.path).test(clean));
+        hits.sort((a, b) => a.path.split(":").length - b.path.split(":").length);
+        return hits[0]?.name ?? null;
+    };
+    const state = { locked: new Set(), public: new Set(), ownerChecked: new Set(), shared: new Set(), everyRouteChecked: false };
+    const report = () => ({
+        version: 1,
+        routes: declared().map((r) => r.name).sort(),
+        locked: [...state.locked].sort(),
+        public: [...state.public].sort(),
+        ownerChecked: [...state.ownerChecked].sort(),
+        shared: [...state.shared].sort(),
+        everyRouteChecked: state.everyRouteChecked,
+    });
+    const publish = async () => {
+        if (options.onReport)
+            await options.onReport(report());
+    };
+    const client = (user, token) => {
+        const request = async (method, path, body) => {
+            const headers = {};
+            if (token)
+                headers.authorization = `Bearer ${token}`;
+            if (body !== undefined)
+                headers["content-type"] = "application/json";
+            return app.request(path, { method, headers, body: body === undefined ? null : JSON.stringify(body) }, env);
+        };
+        return {
+            user,
+            request,
+            get: (p) => request("GET", p),
+            post: (p, b) => request("POST", p, b),
+            put: (p, b) => request("PUT", p, b),
+            patch: (p, b) => request("PATCH", p, b),
+            delete: (p, b) => request("DELETE", p, b),
+        };
+    };
+    const anonymous = client(null, null);
+    return {
+        anonymous,
+        async as(name, opts = {}) {
+            const user = { id: `usr_test_${name}`, email: `${name}@example.test`, name, roles: opts.roles ?? [] };
+            const now = Math.floor(Date.now() / 1000);
+            const token = await sign({ sub: user.id, email: user.email, name: user.name, roles: user.roles, aud: TEST_PROJECT_ID, iat: now, exp: now + 3600 }, priv, "ES256");
+            return client(user, token);
+        },
+        routes: () => declared().map((r) => r.name).sort(),
+        async expectEveryRouteLocked(opts = {}) {
+            const open = new Set(opts.public ?? []);
+            const routes = declared();
+            const problems = [];
+            for (const name of open)
+                if (!routes.some((r) => r.name === name))
+                    problems.push(`"${name}" is listed as public but the app has no such route. Remove it from the list.`);
+            for (const r of routes) {
+                const res = await anonymous.request(r.method, sample(r.path), r.method === "GET" || r.method === "DELETE" ? undefined : {});
+                const refused = res.status === 401 || res.status === 403;
+                if (open.has(r.name)) {
+                    if (refused)
+                        problems.push(`"${r.name}" is listed as public but refuses a signed-out visitor (${res.status}). Remove it from the list.`);
+                    else
+                        state.public.add(r.name);
+                }
+                else if (refused)
+                    state.locked.add(r.name);
+                else
+                    problems.push(`${r.name} answered ${res.status} to a signed-out visitor. Put requireAuth() (or requireRole) in front of it, before anything else runs. If everyone is meant to reach it, add "${r.name}" to the public list.`);
+            }
+            if (problems.length) {
+                await publish();
+                throw new Error(`Routes a stranger can reach:\n- ${problems.join("\n- ")}`);
+            }
+            state.everyRouteChecked = true;
+            await publish();
+        },
+        async expectHiddenFrom(other, method, path, body) {
+            if (!other.user)
+                throw new Error("expectHiddenFrom needs a signed-in user: the question is whether one person can reach another person's data. Use `await t.as(\"bob\")`.");
+            const res = await other.request(method, path, body);
+            if (res.status !== 403 && res.status !== 404) {
+                throw new Error(`${method} ${path} answered ${res.status} to ${other.user.name}, who does not own it. Filter the query by the signed-in user (where userId = c.var.user.id) so someone else's row is not found.`);
+            }
+            const name = nameFor(method, path);
+            if (name)
+                state.ownerChecked.add(name);
+            await publish();
+        },
+        async expectNotListed(other, path, needle) {
+            const res = await other.get(path);
+            const text = await res.text();
+            if (text.includes(needle))
+                throw new Error(`GET ${path} showed ${other.user?.name ?? "a signed-out visitor"} something that belongs to someone else. Filter the query by the signed-in user.`);
+        },
+        shared(route, reason) {
+            if (!reason.trim())
+                throw new Error("Say why the route is shared between users.");
+            if (!declared().some((r) => r.name === route))
+                throw new Error(`"${route}" is not a route of this app.`);
+            state.shared.add(route);
+            void publish();
+        },
+        report,
+    };
+}
+/** The routes with an id in the path, which `nerd check` expects an owner test (or a `shared` declaration) for. */
+export function routesWithId(report) {
+    return report.routes.filter((r) => hasId(r.slice(r.indexOf(" ") + 1)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerdsystem/sdk",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "Runtime for apps deployed on nerdsystem: auth, authorization, and platform bindings.",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
     }
   },
   "files": [