@awsmbiz/create-inbis-app 0.0.0-stage → 0.1.0

package/template/modules/auth/wiring/worker.deps.ts

@@ -0,0 +1,2 @@
+/** Sign-in (auth module): the auth config and the email/SMS senders. Required. */
+auth?: AuthDeps;

package/template/modules/auth/wiring/worker.imports.ts

@@ -0,0 +1 @@
+import { mountAppAuth, type AuthDeps } from "./auth.js";

package/template/modules/auth/wiring/worker.routes.ts

@@ -0,0 +1,2 @@
+// Sign-in (auth module): sessions, /api/auth/*, GET /api/me and the local outboxes.
+mountAppAuth(app, deps.auth);

package/template/modules/example/files/e2e/example-notes.spec.ts

@@ -0,0 +1,39 @@
+import { expect, test } from "@playwright/test";
+import { expectNoPageScroll, expectNoViolations, THEMES, VIEWPORTS } from "./axe.js";
+// inbis:wire example.e2e.imports
+
+// EXAMPLE CODE (example module): the notes screen (web/src/example-notes.tsx), as someone
+// allowed to read and add notes. Delete it with the example.
+
+// inbis:wire example.e2e.setup
+
+test("someone adds a note and finds it at the top of the latest notes", async ({ page }) => {
+  const title = `Note ${String(Date.now())}`;
+  await page.goto("/notes");
+  await expect(page.getByRole("heading", { name: "Notes", level: 1 })).toBeVisible();
+  await page.getByLabel("Title").fill(title);
+  await page.getByLabel("Note", { exact: true }).fill("Written by the end-to-end test.");
+  await page.getByRole("button", { name: "Add note" }).click();
+  await expect(page.getByRole("status")).toHaveText(`Added “${title}”.`);
+  await expect(page.getByLabel("Title")).toHaveValue("");
+  const latest = page.getByRole("list", { name: "Latest notes" }).getByRole("listitem").first();
+  await expect(latest).toContainText(title);
+
+  await page.reload();
+  await expect(page.getByRole("list", { name: "Latest notes" }).getByRole("listitem").first()).toContainText(title);
+});
+
+for (const theme of THEMES) {
+  for (const [viewport, size] of Object.entries(VIEWPORTS)) {
+    test(`Notes (${theme}, ${viewport}) has no accessibility violations`, async ({ page }) => {
+      await page.emulateMedia({ colorScheme: theme });
+      await page.setViewportSize(size);
+      await page.goto("/notes");
+      await expect(page.getByRole("heading", { name: "Notes", level: 1 })).toBeVisible();
+      await expect(page.getByText("Loading notes…")).toBeHidden();
+      await expect(page.getByRole("alert")).toHaveCount(0);
+      await expectNoPageScroll(page);
+      await expectNoViolations(page);
+    });
+  }
+}

package/template/modules/example/files/migrations/0002_example_notes.sql

@@ -0,0 +1,12 @@
+-- EXAMPLE CODE (example module): the notes table. To remove the example from an app that
+-- has applied this migration, add a new migration that drops the table; never edit or
+-- delete an applied one.
+CREATE TABLE `example_note` (
+	`id` text PRIMARY KEY NOT NULL,
+	`title` text NOT NULL,
+	`body` text NOT NULL,
+	`author_id` text,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL
+);
+CREATE INDEX `example_note_created_at_idx` ON `example_note` (`created_at`);

package/template/modules/example/files/src/example-audit-actions.ts

@@ -0,0 +1,12 @@
+// EXAMPLE CODE (example module): delete it with the rest of the notes example.
+
+/**
+ * The audit actions the notes example records (src/example-notes.ts). With the audit module
+ * they are registered with the app's audit trail (src/audit-catalogues.ts); without it
+ * nothing is recorded. Kept in a file of its own, with no imports, so the audit trail can
+ * register it without an import cycle.
+ */
+export const EXAMPLE_AUDIT_ACTIONS = {
+  noteCreated: "example.note.created",
+  noteDeleted: "example.note.deleted",
+} as const;

package/template/modules/example/files/src/example-notes.ts

@@ -0,0 +1,136 @@
+import { createRoute, z, type OpenAPIHono } from "@hono/zod-openapi";
+import type { ApiEnv } from "@awsmbiz/inbis-api";
+import { requireBinding } from "@awsmbiz/inbis-cloudflare";
+import { createDatabase, idColumn, timestampColumns } from "@awsmbiz/inbis-db";
+import { desc } from "drizzle-orm";
+import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+import type { Context, MiddlewareHandler } from "hono";
+import type { AppDeps } from "./app.js";
+import { auditSinkFor } from "./audit-sink.js";
+import { EXAMPLE_AUDIT_ACTIONS } from "./example-audit-actions.js";
+// inbis:wire example.imports
+
+// EXAMPLE CODE (example module). A small business feature, notes, showing the pattern for
+// your own: a table in the app's migrations (migrations/0002_example_notes.sql), validated
+// routes documented in /openapi.json, a screen (web/src/example-notes.tsx), and, when the
+// app has them, a permission check, audit events and an admin page. Copy it for a feature
+// of your own, or delete it: these files, the `mountExampleNotes` call in src/app.ts, the
+// `/notes` route in web/src/routes.tsx and the `notes.*` messages (plus a migration that
+// drops the table if one was applied).
+
+/** The notes table (migrations/0002_example_notes.sql). */
+export const exampleNote = sqliteTable("example_note", {
+  id: idColumn(),
+  title: text("title").notNull(),
+  body: text("body").notNull(),
+  /** Who added it: the signed-in user's ID, or null where the routes do not need sign-in. */
+  authorId: text("author_id"),
+  ...timestampColumns(),
+});
+
+export const NoteSchema = z
+  .object({
+    id: z.string(),
+    title: z.string(),
+    body: z.string(),
+    authorId: z.string().nullable(),
+    createdAt: z.string().openapi({ format: "date-time" }),
+  })
+  .openapi("ExampleNote");
+
+const NewNoteSchema = z
+  .object({
+    title: z.string().trim().min(1).max(120),
+    body: z.string().trim().max(2000).default(""),
+  })
+  .openapi("NewExampleNote");
+
+const NoteListSchema = z.object({ items: z.array(NoteSchema) }).openapi("ExampleNoteList");
+
+/** The newest notes a list returns. A real feature would paginate (`parsePageRequest` in @awsmbiz/inbis-db). */
+const LIST_LIMIT = 50;
+
+type AppContext = Context<ApiEnv<Env>>;
+
+/** A row as the API returns it. */
+export function toNote(row: typeof exampleNote.$inferSelect): z.infer<typeof NoteSchema> {
+  return { id: row.id, title: row.title, body: row.body, authorId: row.authorId, createdAt: row.createdAt.toISOString() };
+}
+
+/** The app's database (binding DB). */
+export const notesDatabase = (c: AppContext) => createDatabase(requireBinding(c.env, "DB"));
+
+/**
+ * Records an event in the app's audit trail when it has one (the audit module); without
+ * one, `auditSinkFor` is `undefined` and nothing is recorded.
+ */
+export async function recordNoteEvent(c: AppContext, action: string, actorId: string | null, noteId: string): Promise<void> {
+  await auditSinkFor(c.env, { logger: c.var.logger })?.record({
+    action,
+    actorId,
+    subjectId: `example_note:${noteId}`,
+    occurredAt: new Date(),
+    requestId: c.var.requestId,
+  });
+}
+
+/** Who may call the notes routes: middleware before reading and before adding, and who the caller is. */
+interface NotesPolicy {
+  read: MiddlewareHandler[];
+  write: MiddlewareHandler[];
+  /** The signed-in user's ID, recorded as the note's author and the audit event's actor. */
+  actorOf: (c: AppContext) => string | null;
+}
+
+/** Rules that tighten the policy, in module order (each may use the app's deps, e.g. `deps.auth`). */
+const policyRules: ((policy: NotesPolicy, deps: AppDeps) => void)[] = [
+  // inbis:wire example.policy
+];
+
+/**
+ * Mounts `GET /v1/example/notes` (the newest notes) and `POST /v1/example/notes` (add one;
+ * `422 VALIDATION_FAILED` on an invalid body). Without access control anyone may call
+ * them; with it, the caller must be signed in and hold `example.notes.read` /
+ * `example.notes.write` (src/access-control.ts).
+ */
+export function mountExampleNotes(app: OpenAPIHono<ApiEnv<Env>>, deps: AppDeps): void {
+  const policy: NotesPolicy = { read: [], write: [], actorOf: () => null };
+  for (const rule of policyRules) rule(policy, deps);
+
+  const list = createRoute({
+    method: "get",
+    path: "/v1/example/notes",
+    tags: ["example"],
+    summary: "The newest example notes (example code: replace it with your own)",
+    middleware: policy.read,
+    responses: {
+      200: { description: "Up to 50 notes, newest first", content: { "application/json": { schema: NoteListSchema } } },
+    },
+  });
+
+  const add = createRoute({
+    method: "post",
+    path: "/v1/example/notes",
+    tags: ["example"],
+    summary: "Add an example note (example code: replace it with your own)",
+    middleware: policy.write,
+    request: { body: { required: true, content: { "application/json": { schema: NewNoteSchema } } } },
+    responses: {
+      201: { description: "The note added", content: { "application/json": { schema: NoteSchema } } },
+    },
+  });
+
+  app.openapi(list, async (c) => {
+    const rows = await notesDatabase(c).select().from(exampleNote).orderBy(desc(exampleNote.createdAt), desc(exampleNote.id)).limit(LIST_LIMIT);
+    return c.json({ items: rows.map(toNote) }, 200);
+  });
+
+  app.openapi(add, async (c) => {
+    const { title, body } = c.req.valid("json");
+    const authorId = policy.actorOf(c);
+    const [row] = await notesDatabase(c).insert(exampleNote).values({ title, body, authorId }).returning();
+    if (row === undefined) throw new Error("The note was not stored.");
+    await recordNoteEvent(c, EXAMPLE_AUDIT_ACTIONS.noteCreated, authorId, row.id);
+    return c.json(toNote(row), 201);
+  });
+}

package/template/modules/example/files/test/example-notes-fixtures.ts

@@ -0,0 +1,30 @@
+import { exports } from "cloudflare:workers";
+// inbis:wire example.test.imports
+
+// EXAMPLE CODE (example module): delete it with the rest of the notes example, or copy it.
+
+/** The app's origin in tests (also sent as `Origin` on a signed-in caller's changes). */
+const ORIGIN = "https://app.example.test";
+
+/** Calls the app over HTTP. */
+export type Call = (path: string, init?: RequestInit) => Promise<Response>;
+
+/**
+ * Steps that turn the anonymous caller into one allowed to read and add notes, in order
+ * (with access control: a signed-in user holding the `notes-editor` role).
+ */
+const steps: ((caller: { call: Call }) => Promise<void>)[] = [
+  // inbis:wire example.test.caller
+];
+
+/** A caller allowed to read and add notes. Without access control anyone may. */
+export async function notesCaller(): Promise<Call> {
+  const caller: { call: Call } = { call: (path, init) => exports.default.fetch(new Request(`${ORIGIN}${path}`, init)) };
+  for (const step of steps) await step(caller);
+  return caller.call;
+}
+
+/** A JSON POST body. */
+export function postJson(body: unknown): RequestInit {
+  return { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) };
+}

package/template/modules/example/files/test/example-notes.test.ts

@@ -0,0 +1,52 @@
+import { env } from "cloudflare:workers";
+import { beforeEach, describe, expect, it } from "vitest";
+import { notesCaller, postJson } from "./example-notes-fixtures.js";
+import { migrate } from "./migrate.js";
+
+// EXAMPLE CODE (example module): the notes API over HTTP. Delete it with the example.
+
+const NOTES = "/v1/example/notes";
+
+interface Note {
+  id: string;
+  title: string;
+  body: string;
+  authorId: string | null;
+  createdAt: string;
+}
+
+beforeEach(async () => {
+  await migrate();
+  await env.DB.prepare("DELETE FROM example_note").run();
+});
+
+describe("the example notes API", () => {
+  it("adds a note and lists it, newest first", async () => {
+    const call = await notesCaller();
+    const first = await call(NOTES, postJson({ title: "First", body: "One" }));
+    expect(first.status).toBe(201);
+    const created = await first.json<Note>();
+    expect(created).toMatchObject({ title: "First", body: "One" });
+    expect(Number.isNaN(Date.parse(created.createdAt))).toBe(false);
+    await call(NOTES, postJson({ title: "Second" }));
+
+    const list = await call(NOTES);
+    expect(list.status).toBe(200);
+    const { items } = await list.json<{ items: Note[] }>();
+    expect(items.map((note) => note.title)).toEqual(["Second", "First"]);
+    expect(items[0]?.body).toBe("");
+  });
+
+  it("refuses a note without a title", async () => {
+    const call = await notesCaller();
+    const response = await call(NOTES, postJson({ title: "  ", body: "No title" }));
+    expect(response.status).toBe(422);
+    expect(await response.json()).toMatchObject({ error: { code: "VALIDATION_FAILED" } });
+  });
+
+  it("is documented in the OpenAPI description", async () => {
+    const call = await notesCaller();
+    const document = await (await call("/openapi.json")).json<{ paths: Record<string, Record<string, unknown>> }>();
+    expect(Object.keys(document.paths[NOTES] ?? {}).sort()).toEqual(["get", "post"]);
+  });
+});

package/template/modules/example/files/web/src/example-notes.tsx

@@ -0,0 +1,176 @@
+import { Alert, AlertDescription, AlertTitle, Button, Card, CardContent, CardHeader, CardTitle, Input, Label } from "@awsmbiz/inbis-ui";
+import { useEffect, useId, useState, type SyntheticEvent } from "react";
+import { t } from "./messages.js";
+
+// EXAMPLE CODE (example module): the notes screen, on GET|POST /v1/example/notes
+// (src/example-notes.ts). Copy it for a screen of your own, or delete it with the example.
+
+/** A note as the API returns it. */
+interface Note {
+  id: string;
+  title: string;
+  body: string;
+  createdAt: string;
+}
+
+type ListState = { kind: "loading" } | { kind: "error" } | { kind: "forbidden" } | { kind: "ready"; notes: Note[] };
+
+/** 401 (not signed in) and 403 (no permission): only with access control. */
+const refused = (status: number) => status === 401 || status === 403;
+
+const dateFormat = new Intl.DateTimeFormat(undefined, { dateStyle: "medium", timeStyle: "short" });
+
+const textareaClass =
+  "min-h-24 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-2 text-base transition-colors outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 md:text-sm dark:bg-input/30";
+
+/** The notes page: a form to add a note, then the newest notes. */
+export function ExampleNotes() {
+  const [list, setList] = useState<ListState>({ kind: "loading" });
+  const [attempt, setAttempt] = useState(0);
+  const [title, setTitle] = useState("");
+  const [body, setBody] = useState("");
+  const [saving, setSaving] = useState(false);
+  const [saveError, setSaveError] = useState<"failed" | "forbidden" | null>(null);
+  const [saved, setSaved] = useState("");
+  const titleId = useId();
+  const bodyId = useId();
+
+  useEffect(() => {
+    let active = true;
+    fetch("/v1/example/notes", { credentials: "include" })
+      .then(async (response) => {
+        if (!active) return;
+        if (refused(response.status)) setList({ kind: "forbidden" });
+        else if (!response.ok) setList({ kind: "error" });
+        else setList({ kind: "ready", notes: ((await response.json()) as { items: Note[] }).items });
+      })
+      .catch(() => {
+        if (active) setList({ kind: "error" });
+      });
+    return () => {
+      active = false;
+    };
+  }, [attempt]);
+
+  const submit = async (event: SyntheticEvent) => {
+    event.preventDefault();
+    setSaving(true);
+    setSaveError(null);
+    setSaved("");
+    const response = await fetch("/v1/example/notes", {
+      method: "POST",
+      credentials: "include",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ title, body }),
+    }).catch(() => null);
+    setSaving(false);
+    if (response?.ok !== true) {
+      setSaveError(response !== null && refused(response.status) ? "forbidden" : "failed");
+      return;
+    }
+    const note = (await response.json()) as Note;
+    setTitle("");
+    setBody("");
+    setSaved(t("notes.saved", { title: note.title }));
+    setList((current) => (current.kind === "ready" ? { kind: "ready", notes: [note, ...current.notes] } : current));
+  };
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <h1 className="text-2xl font-semibold tracking-tight">{t("notes.title")}</h1>
+        <p className="text-muted-foreground">{t("notes.description")}</p>
+      </div>
+      <Card>
+        <CardHeader>
+          <CardTitle>
+            <h2>{t("notes.add")}</h2>
+          </CardTitle>
+        </CardHeader>
+        <CardContent>
+          <form onSubmit={(event) => void submit(event)} className="flex flex-col gap-4">
+            <div className="flex flex-col gap-2">
+              <Label htmlFor={titleId}>{t("notes.noteTitle")}</Label>
+              <Input
+                id={titleId}
+                required
+                maxLength={120}
+                value={title}
+                onChange={(event) => {
+                  setTitle(event.target.value);
+                }}
+              />
+            </div>
+            <div className="flex flex-col gap-2">
+              <Label htmlFor={bodyId}>{t("notes.noteBody")}</Label>
+              <textarea
+                id={bodyId}
+                maxLength={2000}
+                className={textareaClass}
+                value={body}
+                onChange={(event) => {
+                  setBody(event.target.value);
+                }}
+              />
+            </div>
+            {saveError !== null ? (
+              <Alert variant="destructive" role="alert">
+                <AlertDescription>{t(saveError === "forbidden" ? "notes.saveForbidden" : "notes.saveFailed")}</AlertDescription>
+              </Alert>
+            ) : null}
+            <Button type="submit" className="self-start" disabled={saving}>
+              {saving ? t("notes.saving") : t("notes.save")}
+            </Button>
+            {/* Always in the page, so screen readers announce the note added. */}
+            <p role="status" className="text-sm text-muted-foreground">
+              {saved}
+            </p>
+          </form>
+        </CardContent>
+      </Card>
+      <section aria-labelledby="notes-list-heading" className="flex flex-col gap-3">
+        <h2 id="notes-list-heading" className="text-lg font-semibold">
+          {t("notes.listHeading")}
+        </h2>
+        {list.kind === "loading" ? <p className="text-sm text-muted-foreground">{t("notes.loading")}</p> : null}
+        {list.kind === "forbidden" ? (
+          <Alert role="alert">
+            <AlertTitle>{t("notes.forbidden")}</AlertTitle>
+            <AlertDescription>{t("notes.forbiddenHint")}</AlertDescription>
+          </Alert>
+        ) : null}
+        {list.kind === "error" ? (
+          <>
+            <Alert variant="destructive" role="alert">
+              <AlertTitle>{t("notes.failed")}</AlertTitle>
+              <AlertDescription>{t("notes.failedHint")}</AlertDescription>
+            </Alert>
+            <Button
+              className="self-start"
+              onClick={() => {
+                setList({ kind: "loading" });
+                setAttempt((n) => n + 1);
+              }}
+            >
+              {t("notes.tryAgain")}
+            </Button>
+          </>
+        ) : null}
+        {list.kind === "ready" && list.notes.length === 0 ? <p>{t("notes.empty")}</p> : null}
+        {list.kind === "ready" && list.notes.length > 0 ? (
+          <ul aria-labelledby="notes-list-heading" className="flex flex-col divide-y">
+            {list.notes.map((note) => (
+              <li key={note.id} className="flex flex-col gap-1 py-3 first:pt-0">
+                <span className="font-medium break-words">{note.title}</span>
+                {note.body === "" ? null : <span className="text-sm break-words whitespace-pre-line">{note.body}</span>}
+                <time dateTime={note.createdAt} className="text-sm text-muted-foreground">
+                  {dateFormat.format(new Date(note.createdAt))}
+                </time>
+              </li>
+            ))}
+          </ul>
+        ) : null}
+      </section>
+    </div>
+  );
+}

package/template/modules/example/module.json

@@ -0,0 +1,61 @@
+{
+  "name": "example",
+  "description": "Example code to copy or delete: a small business feature (notes) with an app migration, validated /v1 routes in the OpenAPI description and a screen; with access-control, permissions and a role on the routes; with audit, audit events; with admin, an admin page.",
+  "order": 50,
+  "requires": [],
+  "points": {
+    "example.imports": { "file": "src/example-notes.ts", "description": "Imports for the notes routes' policy rules." },
+    "example.policy": { "file": "src/example-notes.ts", "description": "Policy rules `(policy, deps) => { ... }` (comma-terminated): add middleware to `policy.read` / `policy.write`, set `policy.actorOf`." },
+    "example.test.imports": { "file": "test/example-notes-fixtures.ts", "description": "Imports for the notes test caller." },
+    "example.test.caller": { "file": "test/example-notes-fixtures.ts", "description": "Steps `async (caller) => { ... }` (comma-terminated) that replace `caller.call` with one allowed to read and add notes; `ORIGIN` in scope." },
+    "example.e2e.imports": { "file": "e2e/example-notes.spec.ts", "description": "Imports for the notes e2e spec." },
+    "example.e2e.setup": { "file": "e2e/example-notes.spec.ts", "description": "Top-level setup of the notes e2e spec: sign in as someone allowed to read and add notes." }
+  },
+  "wiring": {
+    "worker.imports": "wiring/worker.imports.ts",
+    "worker.routes": "wiring/worker.routes.ts",
+    "web.routes.imports": "wiring/web.routes.imports.tsx",
+    "web.routes": "wiring/web.routes.tsx",
+    "web.messages": "wiring/web.messages.ts",
+    "readme.modules": "wiring/readme.modules.md"
+  },
+  "when": [
+    {
+      "modules": ["access-control"],
+      "files": "with-access-control",
+      "wiring": {
+        "access.permissions": "wiring/access-control/access.permissions.ts",
+        "access.roles": "wiring/access-control/access.roles.ts",
+        "example.imports": "wiring/access-control/example.imports.ts",
+        "example.policy": "wiring/access-control/example.policy.ts",
+        "example.test.imports": "wiring/access-control/example.test.imports.ts",
+        "example.test.caller": "wiring/access-control/example.test.caller.ts",
+        "example.e2e.imports": "wiring/access-control/example.e2e.imports.ts",
+        "example.e2e.setup": "wiring/access-control/example.e2e.setup.ts",
+        "readme.modules": "wiring/access-control/readme.modules.md"
+      }
+    },
+    {
+      "modules": ["audit"],
+      "files": "with-audit",
+      "wiring": {
+        "audit.catalogues.imports": "wiring/audit/audit.catalogues.imports.ts",
+        "audit.catalogues": "wiring/audit/audit.catalogues.ts",
+        "readme.modules": "wiring/audit/readme.modules.md"
+      }
+    },
+    {
+      "modules": ["admin"],
+      "files": "with-admin",
+      "wiring": {
+        "worker.imports": "wiring/admin/worker.imports.ts",
+        "worker.routes": "wiring/admin/worker.routes.ts",
+        "admin.imports": "wiring/admin/admin.imports.tsx",
+        "admin.pages": "wiring/admin/admin.pages.tsx",
+        "admin.nav": "wiring/admin/admin.nav.tsx",
+        "web.messages": "wiring/admin/web.messages.ts",
+        "readme.modules": "wiring/admin/readme.modules.md"
+      }
+    }
+  ]
+}

package/template/modules/example/wiring/access-control/access.permissions.ts

@@ -0,0 +1,3 @@
+// Notes (example module: example code, copy or delete).
+"example.notes.read": "Read the example notes (GET /v1/example/notes)",
+"example.notes.write": "Add example notes (POST /v1/example/notes)",

package/template/modules/example/wiring/access-control/access.roles.ts

@@ -0,0 +1,2 @@
+// Notes (example module: example code, copy or delete).
+"notes-editor": { name: "Notes editor", description: "Reads and adds example notes.", permissions: ["example.notes.read", "example.notes.write"] },

package/template/modules/example/wiring/access-control/example.e2e.imports.ts

@@ -0,0 +1,2 @@
+import { adminApi } from "./auth-helpers.js";
+import { adminsCanSignIn } from "./auth-seeded.js";

package/template/modules/example/wiring/access-control/example.e2e.setup.ts

@@ -0,0 +1,18 @@
+// Access control (access-control module): the notes need sign-in and the notes permissions.
+// The seeded administrator grants itself notes-editor through the role admin API (signed in
+// once, through the API: one authenticator code for the whole file), then browses with that session.
+test.skip(!adminsCanSignIn, "the spec signs in as the seeded administrator: email + password and 2FA (src/auth-choices.ts)");
+
+let session: Awaited<ReturnType<Awaited<ReturnType<typeof adminApi>>["storageState"]>>;
+
+test.beforeAll(async ({ playwright, baseURL }) => {
+  const admin = await adminApi(playwright, baseURL);
+  const { user } = (await (await admin.get("/api/me")).json()) as { user: { id: string } };
+  expect((await admin.put(`/api/admin/users/${user.id}/roles/notes-editor`)).status()).toBe(200);
+  session = await admin.storageState();
+  await admin.dispose();
+});
+
+test.beforeEach(async ({ context }) => {
+  await context.addCookies(session.cookies);
+});

package/template/modules/example/wiring/access-control/example.imports.ts

@@ -0,0 +1,3 @@
+import { requireAuth, sessionMiddleware, type AuthEnv } from "@awsmbiz/inbis-auth/hono";
+import { requirePermission } from "./access-control.js";
+import { authResolver } from "./auth.js";

package/template/modules/example/wiring/access-control/example.policy.ts

@@ -0,0 +1,10 @@
+// Access control (access-control module): signed in, holding example.notes.read to read and
+// example.notes.write to add (src/access-control.ts). /v1 has no session of its own, so the
+// rule adds auth's session middleware first.
+(policy, deps) => {
+  if (deps.auth === undefined) throw new Error("createApp needs deps.auth (see src/index.ts).");
+  const session = sessionMiddleware(authResolver(deps.auth));
+  policy.read.push(session, requireAuth(), requirePermission("example.notes.read"));
+  policy.write.push(session, requireAuth(), requirePermission("example.notes.write"));
+  policy.actorOf = (c) => (c as unknown as Context<AuthEnv>).var.user?.id ?? null;
+},

package/template/modules/example/wiring/access-control/example.test.caller.ts

@@ -0,0 +1,17 @@
+// Access control (access-control module): a signed-in user an administrator granted notes-editor.
+async (caller) => {
+  const app = testApp(choicesWith("invite-only"));
+  const user = newUser();
+  await seedUser(user);
+  const cookie = await signIn(app, user);
+  const { id } = (await (await app.call("/api/me", { headers: { cookie } })).json<{ user: { id: string } }>()).user;
+  const admin = await seedAdmin();
+  const granted = await app.call(`/api/admin/users/${id}/roles/notes-editor`, { ...json({}, { cookie: admin }), method: "PUT" });
+  if (granted.status !== 200) throw new Error(`Granting notes-editor failed: ${String(granted.status)}`);
+  caller.call = (path, init = {}) => {
+    const headers = new Headers(init.headers);
+    headers.set("cookie", cookie);
+    headers.set("origin", ORIGIN);
+    return app.call(path, { ...init, headers });
+  };
+},

package/template/modules/example/wiring/access-control/example.test.imports.ts

@@ -0,0 +1 @@
+import { choicesWith, json, newUser, seedAdmin, seedUser, signIn, testApp } from "./auth-fixtures.js";

package/template/modules/example/wiring/access-control/readme.modules.md

@@ -0,0 +1,5 @@
+With access control (the `access-control` module), the notes routes need a signed-in user
+holding `example.notes.read` (to read) or `example.notes.write` (to add), declared in
+`src/access-control.ts` with the `notes-editor` system role that grants both: an
+administrator assigns it to people from the role admin API (or the admin area's Roles pages).
+The rule lives in `policyRules` in `src/example-notes.ts`.

package/template/modules/example/wiring/admin/admin.imports.tsx

@@ -0,0 +1 @@
+import { NotesAdminPage, NotesIcon } from "./admin-notes.js";

package/template/modules/example/wiring/admin/admin.nav.tsx

@@ -0,0 +1,2 @@
+// Notes (example module: example code, copy or delete).
+{ to: "notes", label: t("admin.notes.title"), icon: NotesIcon },

package/template/modules/example/wiring/admin/admin.pages.tsx

@@ -0,0 +1,2 @@
+// Notes (example module: example code, copy or delete).
+{ path: "notes", title: t("admin.notes.title"), component: NotesAdminPage },

package/template/modules/example/wiring/admin/readme.modules.md

@@ -0,0 +1,4 @@
+With the admin area (the `admin` module), administrators get a **Notes** page at
+`/admin/notes` (`web/src/admin-notes.tsx`) to delete notes, on `GET /api/admin/example/notes`
+and `DELETE /api/admin/example/notes/:noteId` (`src/example-notes-admin.ts`, guarded by
+`requireAdmin()` and, for the deletion, `requireRecentAdminSignIn()`).

package/template/modules/example/wiring/admin/web.messages.ts

@@ -0,0 +1,11 @@
+// Notes admin page (example module: example code, copy or delete).
+"admin.notes.title": "Notes",
+"admin.notes.description": "The newest notes people added. Delete one that should not be there.",
+"admin.notes.loading": "Loading notes…",
+"admin.notes.failed": "Notes could not be loaded.",
+"admin.notes.empty": "No notes yet.",
+"admin.notes.listLabel": "Notes",
+"admin.notes.delete": "Delete",
+"admin.notes.deleteNote": "Delete “{title}”",
+"admin.notes.confirmTitle": "Delete this note?",
+"admin.notes.confirmDescription": "“{title}” will be deleted for everyone. This can't be undone.",

package/template/modules/example/wiring/admin/worker.imports.ts

@@ -0,0 +1 @@
+import { mountExampleNotesAdmin } from "./example-notes-admin.js";