@nerdsystem/sdk 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nerdsystem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @nerdsystem/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runtime for apps deployed on [nerdsystem](https://nerdsystem.com): sign-in, roles, and platform bindings, so your code reads the signed-in user and never handles passwords or tokens.
+
+```ts
+import { createNerdApp, requireAuth, requireRole } from "@nerdsystem/sdk";
+
+const app = createNerdApp();
+app.get("/api/me", requireAuth(), (c) => c.json({ user: c.var.user }));
+app.get("/api/admin", requireRole("admin"), (c) => c.json({ ok: true }));
+export default app;
+```
+
+`createNerdApp()` mounts session routes at `/api/auth` (signup, login, logout, me, forgot, reset), sets security headers on every response, and populates `c.var.user` from the httpOnly session cookie. Tokens are verified offline against the platform's JWKS.
+
+Start from the template with `npx nerdsystem init my-app`. Documentation lives in the template's `AGENTS.md` and `.claude/skills/nerdsystem/SKILL.md`.

package/dist/app.d.ts

@@ -0,0 +1,15 @@
+import { Hono } from "hono";
+import { type NerdHonoEnv } from "./auth/middleware";
+import type { NerdEnv } from "./env";
+import { type SecurityHeadersOptions } from "./security";
+export interface CreateNerdAppOptions {
+    /** Where session routes mount. Default "/api/auth". */
+    authPath?: string;
+    /** Security headers on every response. Pass false to disable, or options to tune the CSP. */
+    securityHeaders?: SecurityHeadersOptions | false;
+}
+/**
+ * A Hono app with nerdsystem auth wired in: session routes at /api/auth and `c.var.user`
+ * populated on every request. Add your API routes to it; static assets are served by the platform.
+ */
+export declare function createNerdApp<E extends NerdEnv = NerdEnv>(options?: CreateNerdAppOptions): Hono<NerdHonoEnv<E>>;

package/dist/app.js

@@ -0,0 +1,21 @@
+import { Hono } from "hono";
+import { attachUser } from "./auth/middleware";
+import { authRoutes } from "./auth/routes";
+import { securityHeaders } from "./security";
+/**
+ * A Hono app with nerdsystem auth wired in: session routes at /api/auth and `c.var.user`
+ * populated on every request. Add your API routes to it; static assets are served by the platform.
+ */
+export function createNerdApp(options = {}) {
+    const app = new Hono();
+    if (options.securityHeaders !== false)
+        app.use("*", securityHeaders(options.securityHeaders ?? {}));
+    app.use("*", attachUser());
+    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) => {
+        console.error("unhandled error", err);
+        return c.json({ error: { code: "internal", message: "Internal error" } }, 500);
+    });
+    return app;
+}

package/dist/auth/client.d.ts

@@ -0,0 +1,81 @@
+import type { NerdEnv, NerdUser } from "../env";
+export interface Session {
+    user: EndUser;
+    accessToken: string;
+    expiresIn: number;
+    refreshToken: string;
+}
+export interface EndUser extends NerdUser {
+    emailVerifiedAt: string | null;
+    disabledAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare class AuthServiceError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    constructor(status: number, code: string, message: string, details?: unknown | undefined);
+}
+/** Thin typed client for the platform auth service, scoped to this app's tenant. */
+export declare class AuthServiceClient {
+    private readonly env;
+    private readonly fetchImpl;
+    private readonly base;
+    constructor(env: Pick<NerdEnv, "NERD_AUTH_URL" | "NERD_PROJECT_ID" | "NERD_AUTH_SECRET">, fetchImpl?: typeof fetch);
+    get jwksUrl(): string;
+    private call;
+    signup(input: {
+        email: string;
+        password: string;
+        name: string;
+    }): Promise<Session>;
+    login(input: {
+        email: string;
+        password: string;
+    }): Promise<Session>;
+    refresh(refreshToken: string): Promise<Session>;
+    logout(refreshToken: string): Promise<{
+        ok: true;
+    }>;
+    me(accessToken: string): Promise<{
+        user: EndUser;
+    }>;
+    forgotPassword(input: {
+        email: string;
+        resetUrl: string;
+        appName?: string;
+    }): Promise<{
+        ok: true;
+    }>;
+    resetPassword(input: {
+        token: string;
+        password: string;
+    }): Promise<Session>;
+    /** Platform email relay. Server-side only. */
+    sendEmail(input: {
+        to: string;
+        subject: string;
+        text: string;
+        html?: string;
+        fromName?: string;
+    }): Promise<{
+        sent: true;
+        remainingToday: number;
+    }>;
+    /** Admin operations, authenticated with the tenant secret. Server-side only. */
+    readonly users: {
+        list: (limit?: number) => Promise<{
+            users: EndUser[];
+        }>;
+        setRoles: (userId: string, roles: string[]) => Promise<{
+            user: EndUser;
+        }>;
+        setDisabled: (userId: string, disabled: boolean) => Promise<{
+            user: EndUser;
+        }>;
+        delete: (userId: string) => Promise<{
+            deleted: true;
+        }>;
+    };
+}

package/dist/auth/client.js

@@ -0,0 +1,76 @@
+export class AuthServiceError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+/** Thin typed client for the platform auth service, scoped to this app's tenant. */
+export class AuthServiceClient {
+    env;
+    fetchImpl;
+    base;
+    constructor(env, 
+    // Wrapped, not bare: calling a stored `fetch` as a method breaks in workerd (illegal invocation).
+    fetchImpl = (input, init) => fetch(input, init)) {
+        this.env = env;
+        this.fetchImpl = fetchImpl;
+        this.base = `${env.NERD_AUTH_URL.replace(/\/$/, "")}/t/${env.NERD_PROJECT_ID}`;
+    }
+    get jwksUrl() {
+        return `${this.env.NERD_AUTH_URL.replace(/\/$/, "")}/.well-known/jwks.json`;
+    }
+    async call(method, path, body, auth) {
+        const res = await this.fetchImpl(`${this.base}${path}`, {
+            method,
+            headers: {
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
+                ...(auth ? { authorization: `Bearer ${auth}` } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : null,
+        });
+        const text = await res.text();
+        const json = text ? JSON.parse(text) : {};
+        if (!res.ok) {
+            const err = json.error;
+            throw new AuthServiceError(res.status, err?.code ?? "auth_error", err?.message ?? `Auth service returned ${res.status}`, err?.details);
+        }
+        return json;
+    }
+    signup(input) {
+        return this.call("POST", "/signup", input);
+    }
+    login(input) {
+        return this.call("POST", "/login", input);
+    }
+    refresh(refreshToken) {
+        return this.call("POST", "/refresh", { refreshToken });
+    }
+    logout(refreshToken) {
+        return this.call("POST", "/logout", { refreshToken });
+    }
+    me(accessToken) {
+        return this.call("GET", "/me", undefined, accessToken);
+    }
+    forgotPassword(input) {
+        return this.call("POST", "/password/forgot", input);
+    }
+    resetPassword(input) {
+        return this.call("POST", "/password/reset", input);
+    }
+    /** Platform email relay. Server-side only. */
+    sendEmail(input) {
+        return this.call("POST", "/email", input, this.env.NERD_AUTH_SECRET);
+    }
+    /** Admin operations, authenticated with the tenant secret. Server-side only. */
+    users = {
+        list: (limit = 50) => this.call("GET", `/users?limit=${limit}`, undefined, this.env.NERD_AUTH_SECRET),
+        setRoles: (userId, roles) => this.call("PATCH", `/users/${userId}`, { roles }, this.env.NERD_AUTH_SECRET),
+        setDisabled: (userId, disabled) => this.call("PATCH", `/users/${userId}`, { disabled }, this.env.NERD_AUTH_SECRET),
+        delete: (userId) => this.call("DELETE", `/users/${userId}`, undefined, this.env.NERD_AUTH_SECRET),
+    };
+}

package/dist/auth/cookies.d.ts

@@ -0,0 +1,8 @@
+import type { Context } from "hono";
+import type { Session } from "./client";
+export declare function accessCookieName(c: Context): string;
+export declare function refreshCookieName(c: Context): string;
+export declare function setSessionCookies(c: Context, session: Session): void;
+export declare function clearSessionCookies(c: Context): void;
+export declare function readAccessCookie(c: Context): string | undefined;
+export declare function readRefreshCookie(c: Context): string | undefined;

package/dist/auth/cookies.js

@@ -0,0 +1,35 @@
+import { deleteCookie, getCookie, setCookie } from "hono/cookie";
+/**
+ * Session cookies are host-only: no Domain attribute, and over https the `__Host-` prefix, which
+ * browsers only accept with Secure and Path=/ and never with a Domain. One app's cookies therefore
+ * cannot be read or overwritten by a sibling app on the shared app domain, nor by the platform.
+ */
+const ACCESS_BASE = "nerd_access";
+const REFRESH_BASE = "nerd_refresh";
+const REFRESH_MAX_AGE = 30 * 24 * 60 * 60;
+function isSecure(c) {
+    const proto = c.req.header("x-forwarded-proto") ?? new URL(c.req.url).protocol.replace(":", "");
+    return proto === "https";
+}
+export function accessCookieName(c) {
+    return isSecure(c) ? `__Host-${ACCESS_BASE}` : ACCESS_BASE;
+}
+export function refreshCookieName(c) {
+    return isSecure(c) ? `__Host-${REFRESH_BASE}` : REFRESH_BASE;
+}
+export function setSessionCookies(c, session) {
+    const secure = isSecure(c);
+    setCookie(c, accessCookieName(c), session.accessToken, { httpOnly: true, secure, sameSite: "Lax", path: "/", maxAge: session.expiresIn });
+    setCookie(c, refreshCookieName(c), session.refreshToken, { httpOnly: true, secure, sameSite: "Lax", path: "/", maxAge: REFRESH_MAX_AGE });
+}
+export function clearSessionCookies(c) {
+    const secure = isSecure(c);
+    deleteCookie(c, accessCookieName(c), { path: "/", secure });
+    deleteCookie(c, refreshCookieName(c), { path: "/", secure });
+}
+export function readAccessCookie(c) {
+    return getCookie(c, accessCookieName(c));
+}
+export function readRefreshCookie(c) {
+    return getCookie(c, refreshCookieName(c));
+}

package/dist/auth/jwks.d.ts

@@ -0,0 +1,10 @@
+import type { NerdUser } from "../env";
+export interface VerifiedToken extends NerdUser {
+    exp: number;
+}
+/** Verifies an access token offline against the platform JWKS (cached per isolate). Returns null if invalid. */
+export declare function verifyAccessToken(token: string, opts: {
+    jwksUrl: string;
+    projectId: string;
+    fetchImpl?: typeof fetch;
+}): Promise<VerifiedToken | null>;

package/dist/auth/jwks.js

@@ -0,0 +1,44 @@
+import { decode, verifyWithJwks } from "hono/jwt";
+const CACHE_TTL_MS = 10 * 60 * 1000;
+const cache = new Map();
+async function fetchKeys(jwksUrl, fetchImpl) {
+    const res = await fetchImpl(jwksUrl);
+    if (!res.ok)
+        throw new Error(`JWKS fetch failed: ${res.status}`);
+    const { keys } = (await res.json());
+    cache.set(jwksUrl, { keys, fetchedAt: Date.now() });
+    return keys;
+}
+async function keysFor(jwksUrl, kid, fetchImpl) {
+    const hit = cache.get(jwksUrl);
+    const fresh = hit && Date.now() - hit.fetchedAt < CACHE_TTL_MS;
+    if (hit && fresh && (!kid || hit.keys.some((k) => k.kid === kid)))
+        return hit.keys;
+    // Stale, or an unknown kid (key rotation): refetch.
+    return fetchKeys(jwksUrl, fetchImpl);
+}
+/** 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;
+    let kid;
+    try {
+        kid = decode(token).header.kid;
+    }
+    catch {
+        return null;
+    }
+    try {
+        const keys = await keysFor(opts.jwksUrl, kid, fetchImpl);
+        const claims = await verifyWithJwks(token, { keys, allowedAlgorithms: ["ES256"], verification: { aud: opts.projectId } });
+        return {
+            id: String(claims.sub),
+            email: String(claims.email),
+            name: String(claims.name),
+            roles: Array.isArray(claims.roles) ? claims.roles : [],
+            exp: Number(claims.exp),
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/auth/middleware.d.ts

@@ -0,0 +1,16 @@
+import type { Context, MiddlewareHandler } from "hono";
+import type { NerdEnv, NerdUser, NerdVariables } from "../env";
+export type NerdHonoEnv<E extends NerdEnv = NerdEnv> = {
+    Bindings: E;
+    Variables: NerdVariables;
+};
+/**
+ * Resolves the current user from the access cookie or a bearer token and sets `c.var.user`.
+ * Never rejects: routes decide with `requireAuth` / `requireRole`.
+ */
+export declare function attachUser<E extends NerdEnv>(): MiddlewareHandler<NerdHonoEnv<E>>;
+export declare function resolveUser<E extends NerdEnv>(c: Context<NerdHonoEnv<E>>): Promise<NerdUser | null>;
+/** 401 unless a user is signed in. */
+export declare function requireAuth<E extends NerdEnv>(): MiddlewareHandler<NerdHonoEnv<E>>;
+/** 401 if signed out, 403 unless the user has at least one of the given roles. */
+export declare function requireRole<E extends NerdEnv>(...roles: string[]): MiddlewareHandler<NerdHonoEnv<E>>;

package/dist/auth/middleware.js

@@ -0,0 +1,45 @@
+import { AuthServiceClient } from "./client";
+import { readAccessCookie } from "./cookies";
+import { verifyAccessToken } from "./jwks";
+/**
+ * Resolves the current user from the access cookie or a bearer token and sets `c.var.user`.
+ * Never rejects: routes decide with `requireAuth` / `requireRole`.
+ */
+export function attachUser() {
+    return async (c, next) => {
+        c.set("user", await resolveUser(c));
+        await next();
+    };
+}
+export async function resolveUser(c) {
+    const bearer = c.req.header("authorization");
+    const token = bearer?.toLowerCase().startsWith("bearer ") ? bearer.slice(7) : readAccessCookie(c);
+    if (!token)
+        return null;
+    const client = new AuthServiceClient(c.env);
+    const verified = await verifyAccessToken(token, { jwksUrl: client.jwksUrl, projectId: c.env.NERD_PROJECT_ID });
+    if (!verified)
+        return null;
+    const { exp: _exp, ...user } = verified;
+    return user;
+}
+/** 401 unless a user is signed in. */
+export function requireAuth() {
+    return async (c, next) => {
+        if (!c.get("user"))
+            return c.json({ error: { code: "unauthorized", message: "Sign in required" } }, 401);
+        await next();
+    };
+}
+/** 401 if signed out, 403 unless the user has at least one of the given roles. */
+export function requireRole(...roles) {
+    return async (c, next) => {
+        const user = c.get("user");
+        if (!user)
+            return c.json({ error: { code: "unauthorized", message: "Sign in required" } }, 401);
+        if (!roles.some((r) => user.roles.includes(r))) {
+            return c.json({ error: { code: "forbidden", message: `Requires role: ${roles.join(" or ")}` } }, 403);
+        }
+        await next();
+    };
+}

package/dist/auth/routes.d.ts

@@ -0,0 +1,8 @@
+import { Hono } from "hono";
+import type { NerdEnv } from "../env";
+import type { NerdHonoEnv } from "./middleware";
+/**
+ * Session routes the SDK mounts at /api/auth. Tokens live in httpOnly cookies on the app's own
+ * origin, so the browser never sees them. The frontend only ever calls these endpoints.
+ */
+export declare function authRoutes<E extends NerdEnv>(): Hono<NerdHonoEnv<E>>;

package/dist/auth/routes.js

@@ -0,0 +1,119 @@
+import { Hono } from "hono";
+import { AuthServiceClient, AuthServiceError } from "./client";
+import { clearSessionCookies, readAccessCookie, readRefreshCookie, setSessionCookies } from "./cookies";
+/** Verifies a Turnstile token with Cloudflare. Only enforced when the app has a secret configured. */
+async function verifyTurnstile(secret, token, ip) {
+    if (!token)
+        return false;
+    const res = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ secret, response: token, ...(ip ? { remoteip: ip } : {}) }),
+    });
+    const json = (await res.json().catch(() => ({})));
+    return json.success === true;
+}
+function str(v) {
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+/**
+ * Session routes the SDK mounts at /api/auth. Tokens live in httpOnly cookies on the app's own
+ * origin, so the browser never sees them. The frontend only ever calls these endpoints.
+ */
+export function authRoutes() {
+    const r = new Hono();
+    r.onError((err, c) => {
+        if (err instanceof AuthServiceError) {
+            return c.json({ error: { code: err.code, message: err.message, details: err.details } }, err.status);
+        }
+        console.error("auth route error", err);
+        return c.json({ error: { code: "internal", message: "Internal error" } }, 500);
+    });
+    r.post("/signup", async (c) => {
+        const body = (await c.req.json().catch(() => ({})));
+        const email = str(body.email);
+        const password = str(body.password);
+        const name = str(body.name);
+        if (!email || !password || !name)
+            return c.json({ error: { code: "bad_request", message: "email, password, and name are required" } }, 400);
+        if (c.env.NERD_TURNSTILE_SECRET && !(await verifyTurnstile(c.env.NERD_TURNSTILE_SECRET, str(body.turnstileToken), c.req.header("cf-connecting-ip")))) {
+            return c.json({ error: { code: "bad_request", message: "Please complete the verification challenge" } }, 400);
+        }
+        const session = await new AuthServiceClient(c.env).signup({ email, password, name });
+        setSessionCookies(c, session);
+        return c.json({ user: session.user }, 201);
+    });
+    r.post("/login", async (c) => {
+        const body = (await c.req.json().catch(() => ({})));
+        const email = str(body.email);
+        const password = str(body.password);
+        if (!email || !password)
+            return c.json({ error: { code: "bad_request", message: "email and password are required" } }, 400);
+        const session = await new AuthServiceClient(c.env).login({ email, password });
+        setSessionCookies(c, session);
+        return c.json({ user: session.user }, 200);
+    });
+    r.post("/refresh", async (c) => {
+        const refreshToken = readRefreshCookie(c);
+        if (!refreshToken)
+            return c.json({ error: { code: "unauthorized", message: "No session" } }, 401);
+        try {
+            const session = await new AuthServiceClient(c.env).refresh(refreshToken);
+            setSessionCookies(c, session);
+            return c.json({ user: session.user }, 200);
+        }
+        catch (err) {
+            if (err instanceof AuthServiceError && err.status === 401) {
+                clearSessionCookies(c);
+                return c.json({ error: { code: "unauthorized", message: "Session expired" } }, 401);
+            }
+            throw err;
+        }
+    });
+    r.post("/logout", async (c) => {
+        const refreshToken = readRefreshCookie(c);
+        if (refreshToken)
+            await new AuthServiceClient(c.env).logout(refreshToken).catch(() => { });
+        clearSessionCookies(c);
+        return c.json({ ok: true }, 200);
+    });
+    // Password reset. The email links to <app origin>/reset-password?token=..., a page the client renders.
+    r.post("/forgot", async (c) => {
+        const body = (await c.req.json().catch(() => ({})));
+        const email = str(body.email);
+        if (!email)
+            return c.json({ error: { code: "bad_request", message: "email is required" } }, 400);
+        const origin = new URL(c.req.url).origin;
+        await new AuthServiceClient(c.env).forgotPassword({ email, resetUrl: `${origin}/reset-password`, ...(c.env.NERD_APP_NAME ? { appName: c.env.NERD_APP_NAME } : {}) });
+        return c.json({ ok: true }, 200);
+    });
+    r.post("/reset", async (c) => {
+        const body = (await c.req.json().catch(() => ({})));
+        const token = str(body.token);
+        const password = str(body.password);
+        if (!token || !password)
+            return c.json({ error: { code: "bad_request", message: "token and password are required" } }, 400);
+        const session = await new AuthServiceClient(c.env).resetPassword({ token, password });
+        setSessionCookies(c, session);
+        return c.json({ user: session.user }, 200);
+    });
+    r.get("/me", async (c) => {
+        const user = c.get("user");
+        if (user)
+            return c.json({ user }, 200);
+        // Access cookie missing or expired. Try the refresh cookie once so page loads stay signed in.
+        const refreshToken = readRefreshCookie(c);
+        if (!refreshToken || readAccessCookie(c))
+            return c.json({ user: null }, 200);
+        try {
+            const session = await new AuthServiceClient(c.env).refresh(refreshToken);
+            setSessionCookies(c, session);
+            return c.json({ user: { id: session.user.id, email: session.user.email, name: session.user.name, roles: session.user.roles } }, 200);
+        }
+        catch {
+            clearSessionCookies(c);
+            return c.json({ user: null }, 200);
+        }
+    });
+    return r;
+}

package/dist/env.d.ts

@@ -0,0 +1,28 @@
+/** Bindings every nerdsystem app receives. Extend with your own via `createNerdApp<MyEnv>()`. */
+export interface NerdEnv {
+    /** The app's own D1 database. */
+    DB: D1Database;
+    /** The app's own R2 bucket. */
+    STORAGE: R2Bucket;
+    /** Static assets built by Vite. Present in production and under `vite dev`. */
+    ASSETS: Fetcher;
+    NERD_PROJECT_ID: string;
+    /** Base URL of the auth service, e.g. https://api.nerdsystem.com/auth/v1 */
+    NERD_AUTH_URL: string;
+    /** Tenant secret for admin calls. Rotated by the platform on every deploy. */
+    NERD_AUTH_SECRET: string;
+    /** Display name used in emails to end users. Optional. */
+    NERD_APP_NAME?: string;
+    /** Cloudflare Turnstile secret. When set, signup requires a valid widget token. */
+    NERD_TURNSTILE_SECRET?: string;
+}
+export interface NerdUser {
+    id: string;
+    email: string;
+    name: string;
+    roles: string[];
+}
+export type NerdVariables = {
+    /** The signed-in user, or null. Set by the SDK on every request. */
+    user: NerdUser | null;
+};

package/dist/env.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createNerdApp, type CreateNerdAppOptions } from "./app";
+export type { NerdEnv, NerdUser, NerdVariables } from "./env";
+export { attachUser, requireAuth, requireRole, resolveUser, type NerdHonoEnv } from "./auth/middleware";
+export { AuthServiceClient, AuthServiceError, type EndUser, type Session } from "./auth/client";
+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";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { createNerdApp } from "./app";
+export { attachUser, requireAuth, requireRole, resolveUser } from "./auth/middleware";
+export { AuthServiceClient, AuthServiceError } from "./auth/client";
+export { verifyAccessToken } from "./auth/jwks";
+export { authRoutes } from "./auth/routes";
+export { securityHeaders, DEFAULT_CSP } from "./security";
+export { sendEmail, verifyCron, cronEvent } from "./platform";

package/dist/platform.d.ts

@@ -0,0 +1,24 @@
+import type { Context, MiddlewareHandler } from "hono";
+import type { NerdEnv } from "./env";
+/** Send a transactional email from the app through the platform relay (plan-limited per day). */
+export declare function sendEmail(env: NerdEnv, message: {
+    to: string;
+    subject: string;
+    text: string;
+    html?: string;
+}): Promise<{
+    remainingToday: number;
+}>;
+/**
+ * Verifies that a POST /api/cron came from the platform scheduler. The signature is an HMAC over
+ * "<timestamp>.<project id>" keyed by the SHA-256 of the app's tenant secret, valid for five minutes.
+ */
+export declare function verifyCron(): MiddlewareHandler<{
+    Bindings: NerdEnv;
+}>;
+/** Shape of the body the scheduler posts to /api/cron. */
+export interface CronEvent {
+    schedule: "hourly" | "daily";
+    at: string;
+}
+export declare function cronEvent(c: Context): Promise<CronEvent>;

package/dist/platform.js

@@ -0,0 +1,40 @@
+import { AuthServiceClient } from "./auth/client";
+/** Send a transactional email from the app through the platform relay (plan-limited per day). */
+export async function sendEmail(env, message) {
+    const client = new AuthServiceClient(env);
+    const r = await client.sendEmail({ ...message, ...(env.NERD_APP_NAME ? { fromName: env.NERD_APP_NAME } : {}) });
+    return { remainingToday: r.remainingToday };
+}
+async function hmacHex(secret, data) {
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return Array.from(new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data))), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function sha256Hex(input) {
+    const d = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+    return Array.from(new Uint8Array(d), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Verifies that a POST /api/cron came from the platform scheduler. The signature is an HMAC over
+ * "<timestamp>.<project id>" keyed by the SHA-256 of the app's tenant secret, valid for five minutes.
+ */
+export function verifyCron() {
+    return async (c, next) => {
+        const ts = c.req.header("x-nerd-cron-timestamp") ?? "";
+        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))
+            return c.json({ error: { code: "unauthorized", message: "Bad cron signature" } }, 401);
+        await next();
+    };
+}
+function timingSafeEqual(a, b) {
+    let d = 0;
+    for (let i = 0; i < a.length; i++)
+        d |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return d === 0;
+}
+export async function cronEvent(c) {
+    return (await c.req.json().catch(() => ({ schedule: "hourly", at: new Date().toISOString() })));
+}

package/dist/security.d.ts

@@ -0,0 +1,15 @@
+import type { MiddlewareHandler } from "hono";
+export interface SecurityHeadersOptions {
+    /** Content-Security-Policy. Pass a string to override, or false to omit. */
+    contentSecurityPolicy?: string | false;
+    /** Add HSTS on https responses. Default true. */
+    hsts?: boolean;
+}
+/**
+ * A conservative default: same-origin scripts, styles may be inline (Vite and most UI libraries
+ * emit some), images from anywhere over https, API calls to the app's own origin, no framing.
+ * Apps that load third-party scripts override `contentSecurityPolicy`.
+ */
+export declare const DEFAULT_CSP: string;
+/** Security headers on every response the Worker produces (static assets are served by the platform). */
+export declare function securityHeaders(opts?: SecurityHeadersOptions): MiddlewareHandler;

package/dist/security.js

@@ -0,0 +1,38 @@
+/**
+ * A conservative default: same-origin scripts, styles may be inline (Vite and most UI libraries
+ * emit some), images from anywhere over https, API calls to the app's own origin, no framing.
+ * Apps that load third-party scripts override `contentSecurityPolicy`.
+ */
+export const DEFAULT_CSP = [
+    "default-src 'self'",
+    "script-src 'self' https://challenges.cloudflare.com",
+    "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
+    "font-src 'self' https://fonts.gstatic.com data:",
+    "img-src 'self' data: blob: https:",
+    "connect-src 'self'",
+    "frame-src https://challenges.cloudflare.com",
+    "frame-ancestors 'none'",
+    "base-uri 'self'",
+    "form-action 'self'",
+].join("; ");
+/** Security headers on every response the Worker produces (static assets are served by the platform). */
+export function securityHeaders(opts = {}) {
+    const csp = opts.contentSecurityPolicy === undefined ? DEFAULT_CSP : opts.contentSecurityPolicy;
+    return async (c, next) => {
+        await next();
+        const h = c.res.headers;
+        if (!h.has("x-content-type-options"))
+            h.set("x-content-type-options", "nosniff");
+        if (!h.has("referrer-policy"))
+            h.set("referrer-policy", "strict-origin-when-cross-origin");
+        if (!h.has("permissions-policy"))
+            h.set("permissions-policy", "camera=(), microphone=(), geolocation=(), payment=()");
+        if (!h.has("x-frame-options"))
+            h.set("x-frame-options", "DENY");
+        if (csp && !h.has("content-security-policy"))
+            h.set("content-security-policy", csp);
+        if (opts.hsts !== false && c.req.url.startsWith("https://") && !h.has("strict-transport-security")) {
+            h.set("strict-transport-security", "max-age=31536000; includeSubDomains");
+        }
+    };
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@nerdsystem/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "description": "Runtime for apps deployed on nerdsystem: auth, authorization, and platform bindings.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "hono": "^4.13.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20261102.1",
+    "hono": "^4.13.16",
+    "typescript": "^5.9.3"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/doobe01/nerdsystem-cloudflare",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://nerdsystem.com",
+  "keywords": [
+    "cloudflare",
+    "workers",
+    "hono",
+    "auth",
+    "deploy",
+    "claude-code"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
 }