create-windy 0.8.2 → 0.9.1

package/template/apps/server/src/observability/diagnostic-failure-recorder.ts

@@ -0,0 +1,94 @@
+import { responseStatus } from "./http-observability.js";
+import {
+  diagnosticRecord,
+  newDiagnosticId,
+  safeDiagnosticCode,
+  type DiagnosticIndex,
+} from "./diagnostic-index.js";
+
+export interface DiagnosticFailureInput {
+  readonly request: Request;
+  /** 必须来自路由注册表，禁止传入请求 URL 或包含真实参数的 pathname。 */
+  readonly route?: string;
+  readonly requestId: string;
+  readonly responseValue: unknown;
+  readonly status?: number | string;
+  readonly errorCode?: unknown;
+}
+
+export interface DiagnosticFailureReceipt {
+  readonly diagnosticId: string;
+  readonly errorCode: string;
+  readonly persisted: boolean;
+}
+
+export function createDiagnosticFailureRecorder(index: DiagnosticIndex) {
+  const captured = new WeakMap<
+    Request,
+    Promise<DiagnosticFailureReceipt | undefined>
+  >();
+  let nextPurge = 0;
+  return {
+    capture(
+      input: DiagnosticFailureInput,
+    ): Promise<DiagnosticFailureReceipt | undefined> {
+      const previous = captured.get(input.request);
+      if (previous) return previous;
+      const pending = record(input);
+      captured.set(input.request, pending);
+      return pending;
+    },
+  };
+
+  async function record(
+    input: DiagnosticFailureInput,
+  ): Promise<DiagnosticFailureReceipt | undefined> {
+    const statusCode = responseStatus(input.responseValue, input.status);
+    if (statusCode < 400) return;
+    const diagnosticId = newDiagnosticId();
+    const suppliedCode = input.errorCode ?? objectError(input.responseValue);
+    const errorCode = safeDiagnosticCode(suppliedCode, statusCode);
+    const record = diagnosticRecord({
+      diagnosticId,
+      requestId: /^[A-Za-z0-9._:-]{1,160}$/.test(input.requestId)
+        ? input.requestId
+        : "(unavailable)",
+      service: "server",
+      stage: "http",
+      method: /^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)$/.test(
+        input.request.method,
+      )
+        ? input.request.method
+        : "OTHER",
+      route: safeDiagnosticRoute(input.route),
+      statusCode,
+      errorCode,
+    });
+    try {
+      await index.record(record);
+      if (Date.now() >= nextPurge) {
+        nextPurge = Date.now() + 60_000;
+        // 有界批量清理不影响失败响应和原始错误处理。
+        void index.purgeExpired().catch(() => {});
+      }
+      return { diagnosticId, errorCode, persisted: true };
+    } catch {
+      return { diagnosticId, errorCode, persisted: false };
+    }
+  }
+}
+
+export function safeDiagnosticRoute(route: unknown): string {
+  return typeof route === "string" && /^\/[A-Za-z0-9_./:*-]{0,255}$/.test(route)
+    ? route
+    : "(unmatched)";
+}
+
+function objectError(value: unknown): unknown {
+  return value &&
+    typeof value === "object" &&
+    !(value instanceof Response) &&
+    "error" in value
+    ? value.error
+    : undefined;
+}

package/template/apps/server/src/observability/diagnostic-http-contract.test.ts

@@ -0,0 +1,42 @@
+import { expect, test } from "bun:test";
+import { createPlatformHttpApp } from "../http-app.js";
+import { createServerRuntime } from "../runtime.js";
+import { createPlatformObservability } from "./bootstrap.js";
+
+test("实际 HTTP 失败响应带诊断编号并只持久化模板与脱敏摘要", async () => {
+  const observability = createPlatformObservability({
+    databaseRequired: false,
+    auditStatus: () => ({
+      queued: 0,
+      dropped: 0,
+      state: "healthy",
+      attempted: 0,
+      persisted: 0,
+      failedAttempts: 0,
+      retries: 0,
+    }),
+    logger: { info() {} },
+  });
+  const app = createPlatformHttpApp(createServerRuntime(), observability).get(
+    "/synthetic/:privateId",
+    () =>
+      Response.json(
+        { error: "SAFE_FAILURE", privateBody: "private-note" },
+        { status: 503 },
+      ),
+  );
+  const response = await app.handle(
+    new Request("http://localhost/api/synthetic/secret-id?secret=query"),
+  );
+  expect(response.status).toBe(503);
+  const id = response.headers.get("x-diagnostic-id");
+  expect(id).toMatch(/^diag-/);
+  const record = await observability.diagnostics.find(id!);
+  expect(record).toMatchObject({
+    route: "/api/synthetic/:privateId",
+    statusCode: 503,
+  });
+  const serialized = JSON.stringify(record);
+  for (const secret of ["secret-id", "private-note", "secret=query"])
+    expect(serialized).not.toContain(secret);
+});

package/template/apps/server/src/observability/diagnostic-index.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { createDiagnosticFailureRecorder } from "./diagnostic-failure-recorder.js";
+import {
+  InMemoryDiagnosticIndex,
+  newDiagnosticId,
+  validDiagnosticId,
+} from "./diagnostic-index.js";
+
+describe("受控失败索引", () => {
+  test("同一请求只记录一次，不持久化 URL 查询、正文或错误内容", async () => {
+    const index = new InMemoryDiagnosticIndex();
+    const recorder = createDiagnosticFailureRecorder(index);
+    const request = new Request(
+      "https://example.test/api/people/private-id?token=secret",
+      { method: "POST", body: "private material" },
+    );
+    const input = {
+      request,
+      route: "/api/people/:id",
+      requestId: "safe-request",
+      status: 500,
+      responseValue: { error: "Provider returned secret body" },
+    };
+    const [first, second] = await Promise.all([
+      recorder.capture(input),
+      recorder.capture(input),
+    ]);
+    expect(first).toEqual(second);
+    expect(validDiagnosticId(first!.diagnosticId)).toBe(true);
+    const stored = await index.find(first!.diagnosticId);
+    expect(stored).toMatchObject({
+      route: "/api/people/:id",
+      errorCode: "UNEXPECTED_FAILURE",
+      requestId: "safe-request",
+      statusCode: 500,
+    });
+    const serialized = JSON.stringify(stored);
+    for (const secret of [
+      "private-id",
+      "token",
+      "secret",
+      "private material",
+      "Provider",
+    ])
+      expect(serialized).not.toContain(secret);
+  });
+
+  test("成功请求不产生索引，失效清理使用相同30天边界", async () => {
+    const index = new InMemoryDiagnosticIndex();
+    const recorder = createDiagnosticFailureRecorder(index);
+    expect(
+      await recorder.capture({
+        request: new Request("https://test.invalid/"),
+        requestId: "ok",
+        responseValue: new Response(null, { status: 200 }),
+      }),
+    ).toBeUndefined();
+    const receipt = await recorder.capture({
+      request: new Request("https://test.invalid/"),
+      requestId: "failed",
+      responseValue: new Response(null, { status: 503 }),
+    });
+    const stored = await index.find(receipt!.diagnosticId);
+    const expiry = new Date(stored!.expiresAt);
+    expect(
+      await index.find(receipt!.diagnosticId, new Date(expiry.getTime() - 1)),
+    ).toBeDefined();
+    expect(await index.find(receipt!.diagnosticId, expiry)).toBeUndefined();
+    expect(await index.purgeExpired(expiry)).toBe(1);
+  });
+
+  test("索引失败不掩盖原请求失败，返回受控关联回执", async () => {
+    const index = new InMemoryDiagnosticIndex();
+    index.record = async () => {
+      throw new Error("storage secret");
+    };
+    const receipt = await createDiagnosticFailureRecorder(index).capture({
+      request: new Request("https://test.invalid/"),
+      requestId: "failed",
+      responseValue: { error: "OPERATION_DENIED" },
+      status: 403,
+    });
+    expect(receipt).toMatchObject({
+      errorCode: "OPERATION_DENIED",
+      persisted: false,
+    });
+    expect(validDiagnosticId(newDiagnosticId())).toBe(true);
+  });
+});

package/template/apps/server/src/observability/diagnostic-index.ts

@@ -0,0 +1,88 @@
+import { randomUUIDv7 } from "bun";
+import type { DiagnosticRecord } from "@southwind-ai/shared";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { DrizzleDiagnosticIndex } from "./diagnostic-repository.js";
+
+export type { DiagnosticRecord } from "@southwind-ai/shared";
+export const DIAGNOSTIC_RETENTION_DAYS = 30;
+const RETENTION_MS = DIAGNOSTIC_RETENTION_DAYS * 86_400_000;
+const ID_PATTERN =
+  /^diag-([0-9a-f]{8})-([0-9a-f]{4})-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+
+export interface DiagnosticIndex {
+  record(record: DiagnosticRecord): Promise<void>;
+  find(id: string, now?: Date): Promise<DiagnosticRecord | undefined>;
+  purgeExpired(now?: Date): Promise<number>;
+}
+
+export function createDiagnosticIndex(db?: NodePgDatabase): DiagnosticIndex {
+  return db ? new DrizzleDiagnosticIndex(db) : new InMemoryDiagnosticIndex();
+}
+
+export function newDiagnosticId(): string {
+  return `diag-${randomUUIDv7()}`;
+}
+
+export function validDiagnosticId(id: string): boolean {
+  return ID_PATTERN.test(id);
+}
+
+export function expiredDiagnosticId(id: string, now = new Date()): boolean {
+  const match = ID_PATTERN.exec(id);
+  return Boolean(
+    match &&
+    Number.parseInt(`${match[1]}${match[2]}`, 16) + RETENTION_MS <=
+      now.getTime(),
+  );
+}
+
+export function safeDiagnosticCode(value: unknown, statusCode: number): string {
+  return typeof value === "string" && /^[A-Z][A-Z0-9_]{1,79}$/.test(value)
+    ? value
+    : statusCode >= 500
+      ? "UNEXPECTED_FAILURE"
+      : `HTTP_${statusCode}`;
+}
+
+export function diagnosticRecord(
+  input: Omit<DiagnosticRecord, "occurredAt" | "expiresAt">,
+  now = new Date(),
+): DiagnosticRecord {
+  return {
+    ...input,
+    occurredAt: now.toISOString(),
+    expiresAt: new Date(now.getTime() + RETENTION_MS).toISOString(),
+  };
+}
+
+/** 无数据库开发模式有界保存；正式部署使用相同接口的 Drizzle Repository。 */
+export class InMemoryDiagnosticIndex implements DiagnosticIndex {
+  private readonly items = new Map<string, DiagnosticRecord>();
+  constructor(private readonly maxItems = 10_000) {}
+
+  async record(record: DiagnosticRecord): Promise<void> {
+    this.items.set(record.diagnosticId, structuredClone(record));
+    if (this.items.size > this.maxItems)
+      this.items.delete(this.items.keys().next().value!);
+  }
+
+  async find(
+    id: string,
+    now = new Date(),
+  ): Promise<DiagnosticRecord | undefined> {
+    const item = validDiagnosticId(id) ? this.items.get(id) : undefined;
+    return item && new Date(item.expiresAt) > now
+      ? structuredClone(item)
+      : undefined;
+  }
+
+  async purgeExpired(now = new Date()): Promise<number> {
+    let count = 0;
+    for (const [id, item] of this.items) {
+      if (new Date(item.expiresAt) > now) continue;
+      this.items.delete(id);
+      count++;
+    }
+    return count;
+  }
+}

package/template/apps/server/src/observability/diagnostic-repository.ts

@@ -0,0 +1,67 @@
+import { and, eq, gt, inArray, lte } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { diagnosticEvents } from "@southwind-ai/database";
+import type { DiagnosticRecord } from "@southwind-ai/shared";
+import type { DiagnosticIndex } from "./diagnostic-index.js";
+
+export class DrizzleDiagnosticIndex implements DiagnosticIndex {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async record(record: DiagnosticRecord): Promise<void> {
+    await this.db
+      .insert(diagnosticEvents)
+      .values({
+        ...record,
+        occurredAt: new Date(record.occurredAt),
+        expiresAt: new Date(record.expiresAt),
+      })
+      .onConflictDoNothing();
+  }
+
+  async find(
+    id: string,
+    now = new Date(),
+  ): Promise<DiagnosticRecord | undefined> {
+    const [row] = await this.db
+      .select()
+      .from(diagnosticEvents)
+      .where(
+        and(
+          eq(diagnosticEvents.diagnosticId, id),
+          gt(diagnosticEvents.expiresAt, now),
+        ),
+      )
+      .limit(1);
+    return row
+      ? {
+          ...row,
+          service: "server",
+          stage: "http",
+          occurredAt: row.occurredAt.toISOString(),
+          expiresAt: row.expiresAt.toISOString(),
+        }
+      : undefined;
+  }
+
+  async purgeExpired(now = new Date()): Promise<number> {
+    const expired = await this.db
+      .select({ id: diagnosticEvents.diagnosticId })
+      .from(diagnosticEvents)
+      .where(lte(diagnosticEvents.expiresAt, now))
+      .limit(5_000);
+    if (!expired.length) return 0;
+    const removed = await this.db
+      .delete(diagnosticEvents)
+      .where(
+        and(
+          inArray(
+            diagnosticEvents.diagnosticId,
+            expired.map(({ id }) => id),
+          ),
+          lte(diagnosticEvents.expiresAt, now),
+        ),
+      )
+      .returning({ id: diagnosticEvents.diagnosticId });
+    return removed.length;
+  }
+}

package/template/apps/server/src/platform-app-bootstrap.ts

@@ -1,3 +1,11 @@
+// @windy-module system.agent begin
+import { prepareAgentGovernance } from "./agent/governance-runtime.js";
+import { registerAgentSkillRoutes } from "./agent-skills/bootstrap.js";
+import { registerDshWorkbenchRoutes } from "./app/dsh-workbench.js";
+// @windy-module system.agent end
+// @windy-module system.audit begin
+import { registerDiagnosticRoutes } from "./system/diagnostic-routes.js";
+// @windy-module system.audit end
 import type { ModuleManifest } from "@southwind-ai/modules";
 import type { FeatureFlagDefinition } from "@southwind-ai/shared";
 import type { AuthRepository } from "./auth/repository.js";
@@ -35,6 +43,15 @@ interface PlatformAppBootstrapInput extends Omit<
 
 export async function bootstrapPlatformApp(input: PlatformAppBootstrapInput) {
   const app = await createPlatformServerApp(input);
+  // @windy-module system.audit begin
+  if (input.modules.some((module) => module.name === "system.audit"))
+    registerDiagnosticRoutes(
+      app,
+      input.runtime,
+      input.features,
+      input.observability.diagnostics,
+    );
+  // @windy-module system.audit end
   const authorizer = createStaticRouteAuthorizer(input.runtime, input.modules);
   // @windy-module system.license begin
   registerPlatformLicenseRoutes(app, input.licenseRuntime, authorizer);
@@ -46,5 +63,30 @@ export async function bootstrapPlatformApp(input: PlatformAppBootstrapInput) {
     input.runtime,
     input.features,
   );
+  // @windy-module system.agent begin
+  if (input.modules.some((module) => module.name === "system.agent")) {
+    const governance = await prepareAgentGovernance({
+      runtime: input.runtime,
+      modules: input.modules,
+      db: input.persistence?.db,
+    });
+    registerAgentSkillRoutes(
+      createManifestAuthorizedRouteApp(app, authorizer),
+      governance.skills,
+    );
+    registerDshWorkbenchRoutes({
+      app,
+      runtime: input.runtime,
+      modules: input.modules,
+      authRepository: input.authRepository,
+      sessionCookieName: input.platformConfig.security.sessionCookieName,
+      enabled: input.platformConfig.enableAI,
+      options: {
+        publishedSkills: (context) =>
+          governance.skills.publishedBundles(context),
+      },
+    });
+  }
+  // @windy-module system.agent end
   return app;
 }

package/template/apps/server/src/platform-http-runtime.ts

@@ -1,3 +1,6 @@
+// @windy-module system.audit begin
+import { createDiagnosticIndex } from "./observability/diagnostic-index.js";
+// @windy-module system.audit end
 import type { PlatformConfig } from "@southwind-ai/config";
 import type { FeatureFlagDefinition } from "@southwind-ai/shared";
 import type { AuthRepository } from "./auth/repository.js";
@@ -52,6 +55,9 @@ export function createHttpObservability(
     databaseRequired: process.env.NODE_ENV === "production",
     auditStatus: () => runtime.auditSink.status(),
     logger,
+    // @windy-module system.audit begin
+    diagnosticIndex: createDiagnosticIndex(persistence?.db),
+    // @windy-module system.audit end
   });
 }
 

package/template/apps/server/src/runtime-development.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { systemModuleManifests } from "@southwind-ai/modules";
+import { developmentAdminActor } from "./runtime-development.js";
+
+describe("开发Token默认权限", () => {
+  test("随Manifest补充标准能力，不自动授予敏感披露或治理导出", () => {
+    const actor = developmentAdminActor();
+    const permissions = systemModuleManifests().flatMap(
+      (module) => module.permissions,
+    );
+    const standard = permissions.filter(
+      ({ accessRisk }) => !accessRisk || accessRisk === "standard",
+    );
+    const restricted = permissions.filter(
+      ({ accessRisk }) => accessRisk && accessRisk !== "standard",
+    );
+    expect(standard.length).toBeGreaterThan(0);
+    for (const permission of standard)
+      expect(actor.permissionKeys).toContain(permission.key);
+    for (const permission of restricted)
+      expect(actor.permissionKeys).not.toContain(permission.key);
+    expect(actor.permissionKeys).not.toContain("system.user.reveal");
+    expect(actor.permissionKeys).not.toContain("system.user.export");
+  });
+});

package/template/apps/server/src/runtime-development.ts

@@ -1,3 +1,4 @@
+import { systemModuleManifests } from "@southwind-ai/modules";
 import type { RequestActor } from "./guards.js";
 // @windy-module work-order begin
 import { exampleDevelopmentPermissionKeys } from "./example-permissions.js";
@@ -21,50 +22,11 @@ export function developmentAdminActor(): RequestActor {
       },
     ]),
     permissionKeys: [
-      "system.admin.access",
-      "system.menu.read",
-      "system.profile.read",
-      "system.profile.manage",
-      "system.user.read",
-      "system.user.manage",
-      "system.user-directory.read",
-      "system.role.read",
-      "system.role.manage",
-      "system.department.read",
-      "system.department.create",
-      "system.department.manage",
-      "system.menu.manage",
-      "system.dict.read",
-      "system.dict.manage",
-      "system.feature.read",
-      "system.feature.manage",
-      "system.ui-components.read",
-      "system.search.read",
-      "system.search.manage",
-      "system.settings.read",
-      "system.settings.manage",
-      "system.watermark.read",
-      "system.watermark.manage",
-      // @windy-module system.license begin
-      "system.license.read",
-      "system.license.manage",
-      // @windy-module system.license end
-      "system.audit.read",
-      "system.agent.read",
-      "system.ops.read",
-      "system.scheduler.read",
-      "system.scheduler.manage",
-      "system.notification.read",
-      "system.notification.update",
-      "system.notification.manage",
-      "system.bulk-data.manage",
-      "system.storage.read",
-      "system.storage.create",
-      "system.storage.manage",
-      "system.workflow.read",
-      "system.workflow.create",
-      "system.workflow.approve",
-      "system.workflow.manage",
+      ...systemModuleManifests().flatMap((module) =>
+        module.permissions
+          .filter(({ accessRisk }) => !accessRisk || accessRisk === "standard")
+          .map((permission) => permission.key),
+      ),
       // @windy-module work-order begin
       ...exampleDevelopmentPermissionKeys,
       // @windy-module work-order end

package/template/apps/server/src/system/diagnostic-routes.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createServerRuntime } from "../runtime.js";
+import {
+  createDiagnosticIndex,
+  diagnosticRecord,
+  newDiagnosticId,
+} from "../observability/diagnostic-index.js";
+import { FakeRouteApp } from "./route-test-app.js";
+import { registerDiagnosticRoutes } from "./diagnostic-routes.js";
+
+describe("diagnostic lookup", () => {
+  test("只允许 diagnostics.read 查询，并为查询留下审计", async () => {
+    const runtime = createServerRuntime({
+      WINDY_DEV_ADMIN_TOKEN: "admin-token",
+    });
+    const index = createDiagnosticIndex();
+    const id = newDiagnosticId();
+    await index.record(
+      diagnosticRecord({
+        diagnosticId: id,
+        requestId: "internal-req",
+        service: "server",
+        stage: "http",
+        method: "GET",
+        route: "/api/resources/:id",
+        statusCode: 500,
+        errorCode: "UNEXPECTED_FAILURE",
+      }),
+    );
+    const app = new FakeRouteApp();
+    registerDiagnosticRoutes(
+      app,
+      runtime,
+      createFoundationSnapshot().features,
+      index,
+    );
+    const route = "/system/diagnostics/:diagnosticId";
+    const anonymous = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/diagnostics/" + id),
+    );
+    const denied = (await app.invoke("GET", route, {
+      guardContext: anonymous,
+      params: { diagnosticId: id },
+      query: {},
+    })) as Response;
+    expect(denied.status).toBe(403);
+    expect(JSON.stringify(await denied.json())).not.toContain("internal-req");
+
+    const admin = await runtime.createGuardContext(
+      new Request("http://localhost/api/system/diagnostics/" + id, {
+        headers: { authorization: "Bearer admin-token" },
+      }),
+    );
+    const found = (await app.invoke("GET", route, {
+      guardContext: admin,
+      params: { diagnosticId: id },
+      query: {},
+    })) as Response;
+    expect(found.status).toBe(200);
+    expect(found.headers.get("cache-control")).toBe("no-store");
+    expect(await found.json()).toMatchObject({
+      requestId: "internal-req",
+      errorCode: "UNEXPECTED_FAILURE",
+    });
+    expect(runtime.auditSink.list()).toContainEqual(
+      expect.objectContaining({ action: "diagnostic.read" }),
+    );
+
+    const expired = (await app.invoke("GET", route, {
+      guardContext: admin,
+      params: { diagnosticId: "diag-00000000-0000-7000-8000-000000000000" },
+      query: {},
+    })) as Response;
+    expect(expired.status).toBe(410);
+    expect(await expired.json()).toEqual({ error: "DIAGNOSTIC_EXPIRED" });
+  });
+});

package/template/apps/server/src/system/diagnostic-routes.ts

@@ -0,0 +1,66 @@
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import type { createServerRuntime } from "../runtime.js";
+import {
+  expiredDiagnosticId,
+  validDiagnosticId,
+  type DiagnosticIndex,
+} from "../observability/diagnostic-index.js";
+import { findFeature } from "../route-guards.js";
+import { resourceEvent, routeContext } from "./route-helpers.js";
+import { withPermission } from "./resource-route-support.js";
+import type { RouteApp } from "./route-types.js";
+
+export function registerDiagnosticRoutes(
+  app: Pick<RouteApp, "get">,
+  runtime: ReturnType<typeof createServerRuntime>,
+  features: FeatureFlagDefinition[],
+  index: DiagnosticIndex,
+) {
+  const feature = findFeature(features, "system.diagnostics");
+  if (!feature) throw new Error("错误诊断缺少 system.diagnostics Feature");
+  app.get("/system/diagnostics/:diagnosticId", (raw) => {
+    const { params, guardContext } = routeContext(raw);
+    return withPermission(
+      runtime,
+      guardContext,
+      "GET",
+      "diagnostics",
+      "read",
+      feature,
+      async () => {
+        const id = params.diagnosticId ?? "";
+        if (/^web-[0-9a-f-]{36}$/.test(id))
+          return failure("CLIENT_ONLY_DIAGNOSTIC", 422);
+        if (!validDiagnosticId(id))
+          return failure("INVALID_DIAGNOSTIC_ID", 400);
+        try {
+          await runtime.auditSink.recordCriticalEvent(
+            resourceEvent(
+              guardContext,
+              "diagnostic.read",
+              "diagnostic-events",
+              id,
+            ),
+          );
+          if (expiredDiagnosticId(id))
+            return failure("DIAGNOSTIC_EXPIRED", 410);
+          const record = await index.find(id);
+          return record
+            ? Response.json(record, {
+                headers: { "cache-control": "no-store" },
+              })
+            : failure("DIAGNOSTIC_NOT_FOUND", 404);
+        } catch {
+          return failure("DIAGNOSTIC_INDEX_UNAVAILABLE", 503);
+        }
+      },
+    );
+  });
+}
+
+function failure(error: string, status: number) {
+  return Response.json(
+    { error },
+    { status, headers: { "cache-control": "no-store" } },
+  );
+}