@nerdsystem/sdk 0.0.14 → 0.0.15

package/README.md

@@ -15,6 +15,23 @@ 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`.
 
+## Locked by default, and checked input
+
+```ts
+import { createNerdApp, readBody } from "@nerdsystem/sdk";
+import { z } from "zod";
+
+// Every route needs a signed-in user except the ones named here. Leave `public` out and routes are
+// open unless each one says requireAuth(), which is how apps created before 0.0.15 behave.
+const app = createNerdApp({ public: ["GET /api/health"] });
+
+app.post("/api/notes", async (c) => {
+  // 400 in the usual error shape unless the body matches. Works with anything that has zod's safeParse.
+  const input = await readBody(c, z.object({ title: z.string().trim().min(1).max(200) }));
+  // ...
+});
+```
+
 ## 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.

package/dist/access.d.ts

@@ -0,0 +1,45 @@
+import type { Context, MiddlewareHandler } from "hono";
+import type { NerdEnv, NerdVariables } from "./env";
+type Env<E extends NerdEnv> = {
+    Bindings: E;
+    Variables: NerdVariables;
+};
+/**
+ * Sign-in required for everything, unless the route is named. With this in front, a route the agent
+ * forgot to protect answers 401 instead of answering everyone: forgetting fails closed.
+ *
+ * Let through without a user: the SDK's own sign-in routes, preflight requests, the routes named in
+ * `publicRoutes` ("GET /api/health", with `:param` and `*` allowed), and a scheduled call that carries
+ * the platform's valid signature. Everything else needs `c.var.user`; a route can still ask for more
+ * with `requireRole`.
+ */
+export declare function lockByDefault<E extends NerdEnv>(publicRoutes: readonly string[], authPath: string): MiddlewareHandler<Env<E>>;
+/** Thrown by `readBody` and `readQuery`; `createNerdApp` answers it with 400 and the usual error shape. */
+export declare class BadRequest extends Error {
+    readonly details?: unknown | undefined;
+    constructor(message: string, details?: unknown | undefined);
+}
+/** Anything with zod's `safeParse`: the SDK does not depend on a validation library, the app brings its own. */
+export interface Schema<T> {
+    safeParse(input: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues?: readonly {
+                path?: readonly (string | number | symbol)[];
+                message?: string;
+            }[];
+        };
+    };
+}
+/**
+ * The request's JSON body, checked against a schema, or a 400. Use it instead of `c.req.json()` so every
+ * field has a type, a length, and a range before the route touches it:
+ * `const input = await readBody(c, z.object({ title: z.string().trim().min(1).max(200) }))`.
+ */
+export declare function readBody<T>(c: Context, schema: Schema<T>): Promise<T>;
+/** The query string as an object, checked against a schema, or a 400. */
+export declare function readQuery<T>(c: Context, schema: Schema<T>): T;
+export {};

package/dist/access.js

@@ -0,0 +1,76 @@
+import { cronSignatureValid } from "./platform";
+function matcher(route) {
+    const space = route.indexOf(" ");
+    if (space < 1)
+        throw new Error(`createNerdApp: public route "${route}" must look like "GET /api/health".`);
+    const method = route.slice(0, space).toUpperCase();
+    const path = route.slice(space + 1).trim();
+    if (!path.startsWith("/"))
+        throw new Error(`createNerdApp: public route "${route}" must look like "GET /api/health".`);
+    const src = path
+        .split("/")
+        .map((seg) => (seg.startsWith(":") ? "[^/]+" : seg === "*" ? ".*" : seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")))
+        .join("/");
+    return { method, re: new RegExp(`^${src}/?$`) };
+}
+/**
+ * Sign-in required for everything, unless the route is named. With this in front, a route the agent
+ * forgot to protect answers 401 instead of answering everyone: forgetting fails closed.
+ *
+ * Let through without a user: the SDK's own sign-in routes, preflight requests, the routes named in
+ * `publicRoutes` ("GET /api/health", with `:param` and `*` allowed), and a scheduled call that carries
+ * the platform's valid signature. Everything else needs `c.var.user`; a route can still ask for more
+ * with `requireRole`.
+ */
+export function lockByDefault(publicRoutes, authPath) {
+    const open = publicRoutes.map(matcher);
+    const auth = authPath.replace(/\/$/, "");
+    return async (c, next) => {
+        if (c.get("user"))
+            return next();
+        const method = c.req.method === "HEAD" ? "GET" : c.req.method;
+        const path = c.req.path;
+        if (method === "OPTIONS" || path === auth || path.startsWith(`${auth}/`))
+            return next();
+        if (open.some((o) => o.method === method && o.re.test(path)))
+            return next();
+        if (await cronSignatureValid(c))
+            return next();
+        return c.json({ error: { code: "unauthorized", message: "Sign in required" } }, 401);
+    };
+}
+/** Thrown by `readBody` and `readQuery`; `createNerdApp` answers it with 400 and the usual error shape. */
+export class BadRequest extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+    }
+}
+function parse(schema, input, what) {
+    const r = schema.safeParse(input);
+    if (r.success)
+        return r.data;
+    const issues = (r.error.issues ?? []).slice(0, 10).map((i) => ({ field: (i.path ?? []).map(String).join("."), problem: String(i.message ?? "invalid") }));
+    const first = issues[0];
+    throw new BadRequest(first ? `${first.field || what}: ${first.problem}` : `The ${what} is not valid.`, { issues });
+}
+/**
+ * The request's JSON body, checked against a schema, or a 400. Use it instead of `c.req.json()` so every
+ * field has a type, a length, and a range before the route touches it:
+ * `const input = await readBody(c, z.object({ title: z.string().trim().min(1).max(200) }))`.
+ */
+export async function readBody(c, schema) {
+    let raw;
+    try {
+        raw = await c.req.json();
+    }
+    catch {
+        throw new BadRequest("The request body must be JSON.");
+    }
+    return parse(schema, raw, "body");
+}
+/** The query string as an object, checked against a schema, or a 400. */
+export function readQuery(c, schema) {
+    return parse(schema, c.req.query(), "query");
+}

package/dist/app.d.ts

@@ -9,6 +9,12 @@ export interface CreateNerdAppOptions {
     securityHeaders?: SecurityHeadersOptions | false;
     /** Reject cookie-authenticated writes that a browser sent from another site. Pass false only if you handle CSRF yourself. */
     crossSiteGuard?: false;
+    /**
+     * Turns on sign-in for every route: only the routes named here answer a signed-out visitor, e.g.
+     * `["GET /api/health"]` (`:param` and `*` work). Pass `[]` to lock everything. Leave it out and routes
+     * are open unless each one says `requireAuth()`, which is how apps created before this option behave.
+     */
+    public?: readonly string[];
 }
 /**
  * A Hono app with nerdsystem auth wired in: session routes at /api/auth and `c.var.user`

package/dist/app.js

@@ -2,6 +2,7 @@ import { Hono } from "hono";
 import { attachUser } from "./auth/middleware";
 import { crossSiteGuard } from "./auth/csrf";
 import { authRoutes } from "./auth/routes";
+import { BadRequest, lockByDefault } from "./access";
 import { securityHeaders } from "./security";
 /**
  * A Hono app with nerdsystem auth wired in: session routes at /api/auth and `c.var.user`
@@ -14,9 +15,13 @@ export function createNerdApp(options = {}) {
     if (options.crossSiteGuard !== false)
         app.use("*", crossSiteGuard());
     app.use("*", attachUser());
+    if (options.public)
+        app.use("*", lockByDefault(options.public, options.authPath ?? "/api/auth"));
     app.route(options.authPath ?? "/api/auth", authRoutes());
     app.notFound((c) => c.json({ error: { code: "not_found", message: `No route for ${c.req.method} ${c.req.path}` } }, 404));
     app.onError((err, c) => {
+        if (err instanceof BadRequest)
+            return c.json({ error: { code: "bad_request", message: err.message, ...(err.details !== undefined ? { details: err.details } : {}) } }, 400);
         console.error("unhandled error", err);
         return c.json({ error: { code: "internal", message: "Internal error" } }, 500);
     });

package/dist/index.d.ts

@@ -7,3 +7,4 @@ export { verifyAccessToken, type VerifiedToken } from "./auth/jwks";
 export { authRoutes } from "./auth/routes";
 export { securityHeaders, DEFAULT_CSP, type SecurityHeadersOptions } from "./security";
 export { sendEmail, verifyCron, cronEvent, type CronEvent } from "./platform";
+export { BadRequest, readBody, readQuery, type Schema } from "./access";

package/dist/index.js

@@ -6,3 +6,4 @@ export { verifyAccessToken } from "./auth/jwks";
 export { authRoutes } from "./auth/routes";
 export { securityHeaders, DEFAULT_CSP } from "./security";
 export { sendEmail, verifyCron, cronEvent } from "./platform";
+export { BadRequest, readBody, readQuery } from "./access";

package/dist/platform.d.ts

@@ -16,6 +16,13 @@ export declare function sendEmail(env: NerdEnv, message: {
 export declare function verifyCron(): MiddlewareHandler<{
     Bindings: NerdEnv;
 }>;
+/** True when the request carries the platform's fresh, valid scheduled-call signature. */
+export declare function cronSignatureValid(c: {
+    req: {
+        header(name: string): string | undefined;
+    };
+    env: Pick<NerdEnv, "NERD_AUTH_SECRET" | "NERD_PROJECT_ID">;
+}): Promise<boolean>;
 /** Shape of the body the scheduler posts to /api/cron. */
 export interface CronEvent {
     schedule: "hourly" | "daily";

package/dist/platform.js

@@ -23,12 +23,20 @@ export function verifyCron() {
         const sig = c.req.header("x-nerd-cron-signature") ?? "";
         if (!ts || !sig || Math.abs(Date.now() / 1000 - Number(ts)) > 300)
             return c.json({ error: { code: "unauthorized", message: "Not a scheduled call" } }, 401);
-        const expected = await hmacHex(await sha256Hex(c.env.NERD_AUTH_SECRET), `${ts}.${c.env.NERD_PROJECT_ID}`);
-        if (expected.length !== sig.length || !timingSafeEqual(expected, sig))
+        if (!(await cronSignatureValid(c)))
             return c.json({ error: { code: "unauthorized", message: "Bad cron signature" } }, 401);
         await next();
     };
 }
+/** True when the request carries the platform's fresh, valid scheduled-call signature. */
+export async function cronSignatureValid(c) {
+    const ts = c.req.header("x-nerd-cron-timestamp") ?? "";
+    const sig = c.req.header("x-nerd-cron-signature") ?? "";
+    if (!ts || !sig || !c.env.NERD_AUTH_SECRET || Math.abs(Date.now() / 1000 - Number(ts)) > 300)
+        return false;
+    const expected = await hmacHex(await sha256Hex(c.env.NERD_AUTH_SECRET), `${ts}.${c.env.NERD_PROJECT_ID}`);
+    return expected.length === sig.length && timingSafeEqual(expected, sig);
+}
 function timingSafeEqual(a, b) {
     let d = 0;
     for (let i = 0; i < a.length; i++)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerdsystem/sdk",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "Runtime for apps deployed on nerdsystem: auth, authorization, and platform bindings.",
   "type": "module",
   "main": "./dist/index.js",