@checkstack/status-page-backend 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# @checkstack/status-page-backend
+
+## 0.1.0
+
+### Minor Changes
+
+- 5c6393f: Add operator-built public Status Pages (phase 1: secure, extensible core).
+
+  Operators compose a public status page from widgets (status banner, system
+  health, group status, 90-day uptime, incidents, scheduled maintenance) plus
+  content blocks (text/Markdown, heading, links, image, divider), each bound to the
+  resources they choose, then publish it.
+
+  Security model — "only published widgets reveal data":
+
+  - A single public endpoint, `getPublishedStatusPage(slug)`, returns the layout
+    plus each widget's already-resolved, field-ALLOW-LISTED DTO. The public surface
+    has no generic data API, so it can only ever show what was placed on the page.
+  - Three gates: edit-time (you can only bind resources you can access), publish-time
+    (an audited, deliberate exposure that re-checks the editor can read every bound
+    resource via a user-scoped client), and render-time (resolvers run as a trusted
+    service but emit only DTO fields — never internal config, ids, or `createdBy`;
+    the service re-validates each DTO against its schema, so a resolver bug fails
+    closed).
+  - The overall banner rolls up only the bound systems; private resources are never
+    exposed beyond their public-safe status; per-binding label overrides avoid
+    internal-name leaks.
+
+  Coherence + extensibility:
+
+  - Status pages are team-scopable resources (RLAC): created via the standard
+    owning-team picker + create-capability flow, resolvable by name in the Teams
+    admin.
+  - Widget types come from an extension-point registry, so any plugin can contribute
+    a widget (config schema + public DTO + `resolvePublic`); the public renderers
+    are pure, prop-only components with no data access, so third-party widgets can
+    never leak.
+  - Draft vs published layouts; per-page visibility (public / authenticated-only)
+    and theming (brand color, logo).
+
+  Dependency direction: the status-page platform owns the widget-type registry and
+  the content widgets, but the DOMAIN widgets are contributed by their owning
+  plugins via the `statusWidgetTypeExtensionPoint` — system health / uptime /
+  banner / group status by `healthcheck-backend`, incidents by `incident-backend`,
+  scheduled maintenance by `maintenance-backend`. So `status-page-backend` depends
+  only on `backend-api` / `common` / `status-page-common`; the owning plugins
+  depend on the platform, never the reverse. `catalog-common` gains
+  `assertCatalogResourcesReadable` for the publish-time access check.
+
+  Phase 1 scope: the secure core, the admin builder, and the public page (served as
+  a no-access-rule route). A fully separate public bundle, custom domains + TLS,
+  drag-reorder, live-data preview, and distribution (embeds/badges/RSS/subscriptions)
+  are the next phases.
+
+### Patch Changes
+
+- Updated dependencies [d2077bd]
+- Updated dependencies [9ab73c5]
+- Updated dependencies [5c6393f]
+  - @checkstack/backend-api@0.23.0
+  - @checkstack/common@0.16.0
+  - @checkstack/status-page-common@0.1.0

package/drizzle/0000_late_alex_wilder.sql

@@ -0,0 +1,14 @@
+CREATE TABLE "status_pages" (
+	"id" text PRIMARY KEY NOT NULL,
+	"slug" text NOT NULL,
+	"title" text NOT NULL,
+	"visibility" text DEFAULT 'public' NOT NULL,
+	"theme" jsonb DEFAULT '{"mode":"auto"}'::jsonb NOT NULL,
+	"draft_layout" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"published_layout" jsonb,
+	"published_at" timestamp,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "status_pages_slug_unique" ON "status_pages" USING btree ("slug");

package/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,113 @@
+{
+  "id": "ed199f30-548d-4957-9e63-87484bfc0d39",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.status_pages": {
+      "name": "status_pages",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "slug": {
+          "name": "slug",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "visibility": {
+          "name": "visibility",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'public'"
+        },
+        "theme": {
+          "name": "theme",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{\"mode\":\"auto\"}'::jsonb"
+        },
+        "draft_layout": {
+          "name": "draft_layout",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "published_layout": {
+          "name": "published_layout",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "published_at": {
+          "name": "published_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "status_pages_slug_unique": {
+          "name": "status_pages_slug_unique",
+          "columns": [
+            {
+              "expression": "slug",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1781129403698,
+      "tag": "0000_late_alex_wilder",
+      "breakpoints": true
+    }
+  ]
+}

package/drizzle.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  schema: "./src/schema.ts",
+  out: "./drizzle",
+  dialect: "postgresql",
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@checkstack/status-page-backend",
+  "version": "0.1.0",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "checkstack": {
+    "type": "backend"
+  },
+  "scripts": {
+    "typecheck": "tsgo -b",
+    "generate": "drizzle-kit generate",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "0.23.0",
+    "@checkstack/common": "0.16.0",
+    "@checkstack/status-page-common": "0.1.0",
+    "drizzle-orm": "^0.45.0",
+    "zod": "^4.2.1",
+    "@orpc/server": "^1.14.4",
+    "@orpc/client": "^1.14.4"
+  },
+  "devDependencies": {
+    "@checkstack/drizzle-helper": "0.0.5",
+    "@checkstack/scripts": "0.6.2",
+    "@checkstack/test-utils-backend": "0.1.43",
+    "@checkstack/tsconfig": "0.0.7",
+    "@types/bun": "^1.0.0",
+    "drizzle-kit": "^0.31.10",
+    "typescript": "^5.0.0"
+  }
+}

package/src/content-widgets.ts

@@ -0,0 +1,94 @@
+import {
+  pluginMetadata,
+  TextConfigSchema,
+  TextDtoSchema,
+  HeadingConfigSchema,
+  HeadingDtoSchema,
+  LinksConfigSchema,
+  LinksDtoSchema,
+  ImageConfigSchema,
+  ImageDtoSchema,
+  DividerConfigSchema,
+  DividerDtoSchema,
+} from "@checkstack/status-page-common";
+import type {
+  WidgetTypeDefinition,
+  WidgetTypeRegistry,
+} from "./widget-registry";
+
+/**
+ * The CONTENT widgets — the only built-ins the status-page platform owns,
+ * because they bind no domain resources (their config IS their public DTO).
+ * The domain widgets (system health, uptime, incidents, maintenance, ...) are
+ * contributed by their OWNING plugins via `statusWidgetTypeExtensionPoint`, so
+ * this package never depends on catalog/healthcheck/incident/maintenance.
+ */
+function staticWidget({
+  id,
+  displayName,
+  description,
+  configSchema,
+  dtoSchema,
+}: {
+  id: string;
+  displayName: string;
+  description: string;
+  configSchema: WidgetTypeDefinition["configSchema"];
+  dtoSchema: WidgetTypeDefinition["dtoSchema"];
+}): WidgetTypeDefinition {
+  return {
+    id,
+    displayName,
+    description,
+    category: "Content",
+    binding: "none",
+    configSchema,
+    dtoSchema,
+    boundResources: () => [],
+    async resolvePublic({ config }) {
+      return dtoSchema.parse(configSchema.parse(config));
+    },
+  };
+}
+
+/** Register the content widgets the platform owns directly. */
+export function registerContentWidgets(registry: WidgetTypeRegistry): void {
+  const widgets: WidgetTypeDefinition[] = [
+    staticWidget({
+      id: "text",
+      displayName: "Text",
+      description: "A Markdown text block (rendered sanitized).",
+      configSchema: TextConfigSchema,
+      dtoSchema: TextDtoSchema,
+    }),
+    staticWidget({
+      id: "heading",
+      displayName: "Heading",
+      description: "A section heading.",
+      configSchema: HeadingConfigSchema,
+      dtoSchema: HeadingDtoSchema,
+    }),
+    staticWidget({
+      id: "links",
+      displayName: "Links",
+      description: "A list of labelled links.",
+      configSchema: LinksConfigSchema,
+      dtoSchema: LinksDtoSchema,
+    }),
+    staticWidget({
+      id: "image",
+      displayName: "Image / logo",
+      description: "An image (e.g. your logo).",
+      configSchema: ImageConfigSchema,
+      dtoSchema: ImageDtoSchema,
+    }),
+    staticWidget({
+      id: "divider",
+      displayName: "Divider",
+      description: "A horizontal divider.",
+      configSchema: DividerConfigSchema,
+      dtoSchema: DividerDtoSchema,
+    }),
+  ];
+  for (const w of widgets) registry.register(w, pluginMetadata);
+}

package/src/hooks.ts

@@ -0,0 +1,17 @@
+import { createHook } from "@checkstack/backend-api";
+
+/**
+ * Status-page hooks for cross-plugin audit. Publishing a page is a deliberate
+ * PUBLIC-EXPOSURE action; an audit-log plugin can subscribe to record exactly
+ * which resources a page exposed, when, and by whom.
+ */
+export const statusPageHooks = {
+  published: createHook<{
+    pageId: string;
+    slug: string;
+    /** Qualified `type:id` of every resource the published widgets expose. */
+    exposedResources: string[];
+    publishedBy: string;
+    publishedAt: string;
+  }>("statuspage.page.published"),
+} as const;

package/src/index.ts

@@ -0,0 +1,98 @@
+import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import { inArray, ilike } from "drizzle-orm";
+import {
+  pluginMetadata,
+  statusPageContract,
+  statusPageAccessRules,
+} from "@checkstack/status-page-common";
+import * as schema from "./schema";
+import { statusPages } from "./schema";
+import { createStatusPageRouter } from "./router";
+import { StatusPageService } from "./service";
+import {
+  createWidgetTypeRegistry,
+  statusWidgetTypeExtensionPoint,
+} from "./widget-registry";
+import { registerContentWidgets } from "./content-widgets";
+
+const STATUS_PAGE_RESOURCE_TYPE = "statuspage.page";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    env.registerAccessRules(statusPageAccessRules);
+
+    // The widget-type registry is created here (register phase) and seeded with
+    // the built-ins, then exposed so ANY plugin can contribute widget types via
+    // the extension point during its own register/init.
+    const registry = createWidgetTypeRegistry();
+    registerContentWidgets(registry);
+    env.registerExtensionPoint(statusWidgetTypeExtensionPoint, {
+      registerWidgetType: (definition, meta) =>
+        registry.register(definition, meta),
+    });
+
+    env.registerInit({
+      schema,
+      deps: {
+        rpc: coreServices.rpc,
+        logger: coreServices.logger,
+        rpcClient: coreServices.rpcClient,
+        resourceResolverRegistry: coreServices.resourceResolverRegistry,
+      },
+      init: async ({
+        database,
+        rpc,
+        logger,
+        rpcClient,
+        resourceResolverRegistry,
+      }) => {
+        const db = database as SafeDatabase<typeof schema>;
+
+        const service = new StatusPageService({
+          db,
+          registry,
+          rpcClient,
+          logger,
+        });
+        const internalUrl =
+          process.env.INTERNAL_URL || "http://localhost:3000";
+        const router = createStatusPageRouter({ service, internalUrl });
+        rpc.registerRouter(router, statusPageContract);
+
+        // Let the Teams admin resolve `statuspage.page` grants by name + search.
+        resourceResolverRegistry.register(STATUS_PAGE_RESOURCE_TYPE, {
+          resolveNames: async (ids) => {
+            if (ids.length === 0) return new Map();
+            const rows = await db
+              .select({ id: statusPages.id, title: statusPages.title })
+              .from(statusPages)
+              .where(inArray(statusPages.id, ids));
+            return new Map(rows.map((r) => [r.id, r.title]));
+          },
+          search: async (query, limit) => {
+            const rows = await db
+              .select({ id: statusPages.id, name: statusPages.title })
+              .from(statusPages)
+              .where(ilike(statusPages.title, `%${query}%`))
+              .limit(limit);
+            return rows;
+          },
+        });
+
+        logger.debug("✅ Status Pages backend initialized.");
+      },
+    });
+  },
+});
+
+export {
+  statusWidgetTypeExtensionPoint,
+  type StatusWidgetTypeExtensionPoint,
+  type WidgetTypeDefinition,
+  type WidgetResolveContext,
+  type BoundResource,
+} from "./widget-registry";
+export { statusPageHooks } from "./hooks";

package/src/router.ts

@@ -0,0 +1,106 @@
+import { implement } from "@orpc/server";
+import {
+  autoAuthMiddleware,
+  correlationMiddleware,
+  type RpcContext,
+} from "@checkstack/backend-api";
+import { statusPageContract } from "@checkstack/status-page-common";
+import { statusPageHooks } from "./hooks";
+import {
+  createUserScopedRpcClient,
+  forwardableAuthHeadersFrom,
+} from "./user-client";
+import type { StatusPageService } from "./service";
+
+const os = implement(statusPageContract)
+  .$context<RpcContext>()
+  .use(correlationMiddleware)
+  .use(autoAuthMiddleware);
+
+export interface StatusPageRouterDeps {
+  service: StatusPageService;
+  /** Loopback base URL for the user-scoped publish gate. */
+  internalUrl: string;
+}
+
+export function createStatusPageRouter({
+  service,
+  internalUrl,
+}: StatusPageRouterDeps) {
+  const listStatusPages = os.listStatusPages.handler(async () => ({
+    pages: await service.list(),
+  }));
+
+  const getStatusPage = os.getStatusPage.handler(async ({ input }) =>
+    service.get(input.id),
+  );
+
+  const createStatusPage = os.createStatusPage.handler(async ({ input }) => {
+    // `teamId` is consumed by the create-mode middleware (it resolves + writes
+    // the owning-team grant); the table has no team column, so strip it here.
+    const { teamId: _teamId, ...rest } = input;
+    return service.create(rest);
+  });
+
+  const updateStatusPage = os.updateStatusPage.handler(async ({ input }) =>
+    service.update(input),
+  );
+
+  const publishStatusPage = os.publishStatusPage.handler(
+    async ({ input, context }) => {
+      const userClient = createUserScopedRpcClient({
+        internalUrl,
+        forwardHeaders: forwardableAuthHeadersFrom(context.requestHeaders),
+      });
+      const { page, exposed } = await service.publish({
+        id: input.id,
+        userClient,
+      });
+      const publishedBy = context.user
+        ? context.user.type === "service"
+          ? `service:${context.user.pluginId}`
+          : context.user.id
+        : "system";
+      await context.emitHook(statusPageHooks.published, {
+        pageId: page.id,
+        slug: page.slug,
+        exposedResources: exposed.map((b) => `${b.resourceType}:${b.resourceId}`),
+        publishedBy,
+        publishedAt: page.publishedAt ?? new Date().toISOString(),
+      });
+      return page;
+    },
+  );
+
+  const unpublishStatusPage = os.unpublishStatusPage.handler(
+    async ({ input }) => service.unpublish(input.id),
+  );
+
+  const deleteStatusPage = os.deleteStatusPage.handler(async ({ input }) => ({
+    deleted: await service.remove(input.id),
+  }));
+
+  const listWidgetTypes = os.listWidgetTypes.handler(async () => ({
+    widgetTypes: service.listWidgetTypes(),
+  }));
+
+  const getPublishedStatusPage = os.getPublishedStatusPage.handler(
+    async ({ input, context }) => {
+      const isAuthenticated =
+        context.user?.type === "user" || context.user?.type === "application";
+      return service.resolvePublished({ slug: input.slug, isAuthenticated });
+    },
+  );
+
+  return {
+    listStatusPages,
+    getStatusPage,
+    createStatusPage,
+    updateStatusPage,
+    publishStatusPage,
+    unpublishStatusPage,
+    deleteStatusPage,
+    listWidgetTypes,
+    getPublishedStatusPage,
+  };
+}

package/src/schema.ts

@@ -0,0 +1,48 @@
+import {
+  pgTable,
+  text,
+  timestamp,
+  jsonb,
+  uniqueIndex,
+} from "drizzle-orm/pg-core";
+import type { InferSelectModel } from "drizzle-orm";
+import type {
+  StatusPageLayout,
+  StatusPageTheme,
+} from "@checkstack/status-page-common";
+
+/**
+ * Status pages. Team ownership lives in the relation-tuple store keyed by
+ * `statuspage.page` / id (NOT a column here) — exactly like systems/automations.
+ *
+ * The DRAFT layout is the builder's working copy. PUBLISH snapshots it into
+ * `published_layout`; the public resolver reads ONLY `published_layout`, so a
+ * page being edited never changes under visitors until republished.
+ */
+export const statusPages = pgTable(
+  "status_pages",
+  {
+    id: text("id")
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    slug: text("slug").notNull(),
+    title: text("title").notNull(),
+    /** "public" | "authenticated" */
+    visibility: text("visibility").notNull().default("public"),
+    theme: jsonb("theme").$type<StatusPageTheme>().notNull().default({ mode: "auto" }),
+    draftLayout: jsonb("draft_layout")
+      .$type<StatusPageLayout>()
+      .notNull()
+      .default([]),
+    /** Null until the page is published; the public-facing snapshot. */
+    publishedLayout: jsonb("published_layout").$type<StatusPageLayout>(),
+    publishedAt: timestamp("published_at"),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    slugUnique: uniqueIndex("status_pages_slug_unique").on(t.slug),
+  }),
+);
+
+export type StatusPageRow = InferSelectModel<typeof statusPages>;