@agilesyndrome/cf-genai-base 0.1.0

package/CONTRACT.md

@@ -0,0 +1,44 @@
+# Shared site contract
+
+Every site built from this foundation follows the same edge contract.
+
+## Worker entrypoint
+
+`createWorker({ fetch, auth?, scheduled?, security? })` owns the Worker lifecycle.
+The site router owns pages, APIs, D1 queries, and R2 object keys. `scheduled`
+is optional and must use `ctx.waitUntil` for background work.
+
+## Routes
+
+- `GET /health` returns `{ ok, version, build_number }` and is cache-disabled.
+- `GET /api/me` returns `{ user: null | { sub, email, name, ...roles } }`.
+- `/auth/login`, `/auth/callback`, and `/auth/logout` are reserved for auth.
+- Public APIs must be explicitly listed in auth configuration.
+- Mutating `/api/*` requests require a same-origin `Origin` header.
+
+## Environment and bindings
+
+Required OIDC secrets for the standard auth plugin:
+
+- `OIDC_ISSUER`
+- `OIDC_CLIENT_ID`
+- `OIDC_CLIENT_SECRET`
+- `AUTH_SESSION_SECRET`
+
+Standard bindings:
+
+- `DB`: primary D1 database for durable application records.
+- `ASSETS`: static asset binding when the site has a frontend bundle.
+- `R2_*`: optional R2 buckets for files or photos; use a descriptive suffix.
+
+Build metadata is optional: `BUILD_SHA` and `BUILD_NUMBER`.
+
+D1 migrations are committed with the site, applied by Wrangler, and are the
+source of truth for schema changes. R2 stores binary data; metadata and access
+control remain in D1.
+
+## User and role contract
+
+Auth returns a stable `sub`, normalized lowercase `email`, and display `name`.
+Applications may add roles or an internal D1 user id in `onLogin`; authorization
+must remain in the application router rather than in the shared auth package.

package/LICENSE

@@ -0,0 +1,7 @@
+MIT License
+
+Copyright (c) 2026 Agile Syndrome
+
+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 SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.

package/README.md

@@ -0,0 +1,21 @@
+# `@easleyowl/cf-genai-base`
+
+Opinionated startup boilerplate for small Cloudflare Workers.
+
+The base is deliberately small: a site still owns its router, HTML, D1
+queries, R2 keys, and scheduled jobs. `createWorker` composes an optional auth
+handler, normalizes uncaught failures, and applies baseline response headers.
+Use D1 bindings for durable application data and R2 bindings for binary assets;
+do not put either into module-level state.
+
+```js
+import { createWorker, healthResponse } from "@easleyowl/cf-genai-base";
+
+export default createWorker({
+  auth: (request, env) => auth.handle(request, env),
+  fetch: async (request, env) => {
+    if (new URL(request.url).pathname === "/health") return healthResponse(env);
+    return router(request, env);
+  },
+});
+```

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@agilesyndrome/cf-genai-base",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "description": "Lean Worker lifecycle and security helpers for Cloudflare sites.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CONTRACT.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agilesyndrome/cf-genai-base.git"
+  },
+  "homepage": "https://github.com/agilesyndrome/cf-genai-base#readme"
+}

package/src/index.js

@@ -0,0 +1,43 @@
+/**
+ * Small, opinionated Worker composition layer shared by the Easley Owl sites.
+ * Site code owns routing and data access; this owns lifecycle and the edges.
+ */
+export function createWorker({ fetch, scheduled, auth, security = true }) {
+  return {
+    async fetch(request, env, ctx) {
+      try {
+        const authResponse = auth ? await auth(request, env, ctx) : null;
+        const response = authResponse || await fetch(request, env, ctx);
+        return security ? secureResponse(response) : response;
+      } catch (error) {
+        console.error("[worker] request failed", error);
+        return secureResponse(Response.json({ error: "Internal server error" }, { status: 500 }));
+      }
+    },
+    ...(scheduled ? { scheduled } : {}),
+  };
+}
+
+export function secureResponse(response) {
+  const headers = new Headers(response.headers);
+  headers.set("X-Content-Type-Options", "nosniff");
+  headers.set("X-Frame-Options", "DENY");
+  headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
+  headers.set("Permissions-Policy", "camera=(), microphone=(), geolocation=(), payment=(), usb=()");
+  headers.set("Cross-Origin-Opener-Policy", "same-origin");
+  headers.set("Strict-Transport-Security", "max-age=31536000");
+  return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}
+
+export function methodNotAllowed(allow = "GET") {
+  return new Response("Method Not Allowed", { status: 405, headers: { Allow: allow } });
+}
+
+export function healthResponse(env, details = {}) {
+  return Response.json({
+    ok: true,
+    version: String(env.BUILD_SHA || "unknown").slice(0, 7),
+    build_number: env.BUILD_NUMBER ? String(env.BUILD_NUMBER) : null,
+    ...details,
+  }, { headers: { "Cache-Control": "no-store" } });
+}