@cosmicdrift/kumiko-framework 0.299.0 → 0.304.0

package/src/engine/boot-validator/__tests__/access-declarations.test.ts

@@ -578,3 +578,130 @@ describe("validateAccessDeclarations — self-bound personal-data fields", () =>
     expect(() => validateAccessDeclarations(feature)).toThrow(/"displayName"/);
   });
 });
+
+describe("validateAccessDeclarations — anonymous (roles-form) personal-data intake", () => {
+  test("an anonymous write handler accepting a personal-data field without personalData throws", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:signup",
+        z.object({ email: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        { access: { roles: ["anonymous"] } },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/Feature notes/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:signup"/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"email"/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/personalData: "public-intake"/);
+  });
+
+  test('the same handler WITH personalData: "public-intake" boots fine', () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:signup",
+        z.object({ email: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        { access: { roles: ["anonymous"], personalData: "public-intake" } },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).not.toThrow();
+  });
+
+  test('an owner-bound personal-data field is not exempted for an anonymous handler — anonymous callers share one user.id, so from("user:id", ...) binds no one', () => {
+    const ownedByCaller: OwnershipMap = { Member: from("user:id", "ownerUserId") };
+    const entity = createEntity({
+      table: "fw2885_guard_anon_owned",
+      fields: {
+        name: createTextField({ personal: { of: "ownerUserId" }, find: "none" }),
+        ownerUserId: createTextField({ required: false, personal: "ref" }),
+      },
+      access: { write: ownedByCaller },
+    });
+    const schema = z.object({ name: z.string() });
+    const anonymousFeature = defineFeature("notes", (r) => {
+      r.entity("note", entity);
+      r.writeHandler("note:signup", schema, async () => ({ isSuccess: true as const, data: {} }), {
+        access: { roles: ["anonymous"] },
+      });
+    });
+    expect(anonymousFeature.handlerEntityMappings["note:signup"]).toBe("note");
+    expect(() => validateAccessDeclarations(anonymousFeature)).toThrow(/"name"/);
+
+    // Control: the same owner-bound entity/schema via openToAll IS exempted, so the throw above is override-specific.
+    const openToAllFeature = defineFeature("notes", (r) => {
+      r.entity("note", entity);
+      r.writeHandler("note:signup", schema, async () => ({ isSuccess: true as const, data: {} }), {
+        access: { openToAll: { reason: "members share contacts" } },
+      });
+    });
+    expect(() => validateAccessDeclarations(openToAllFeature)).not.toThrow();
+  });
+
+  test('personalData: "public-intake" on roles without "anonymous" throws', () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        { access: { roles: ["Admin"], personalData: "public-intake" } },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:create"/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/anonymous/);
+  });
+
+  test('personalData: "tenant-members" on the roles form throws', () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        {
+          // @cast-boundary test — simulates JSON/Designer input that doesn't match the static union
+          access: { roles: ["anonymous"], personalData: "tenant-members" } as unknown as AccessRule,
+        },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"tenant-members"/);
+  });
+
+  test("personalData on the roles form of a query handler throws", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.queryHandler("note:list", z.object({}), async () => [], {
+        access: { roles: ["anonymous"], personalData: "public-intake" },
+      });
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:list"/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/access\.personalData/);
+  });
+
+  test("a non-anonymous roles handler accepting a personal-data field does not throw", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:create",
+        z.object({ email: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        { access: { roles: ["Admin"] } },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).not.toThrow();
+  });
+
+  test('personalData: "tenant-members" no longer type-checks on the roles form', () => {
+    // @ts-expect-error "tenant-members" is only valid on openToAll, not the roles form
+    const access: AccessRule = { roles: ["anonymous"], personalData: "tenant-members" };
+    expect(access).toBeDefined();
+  });
+
+  test("an unrecognised personalData string does not type-check on the roles form", () => {
+    // @ts-expect-error only "public-intake" is a valid roles-form personalData value
+    const access: AccessRule = { roles: ["anonymous"], personalData: "whatever" };
+    expect(access).toBeDefined();
+  });
+});

package/src/engine/boot-validator/__tests__/no-all-role-in-handler-access.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../../define-feature";
+import { validateHandlerAccess } from "../entity-handler";
+
+describe('validateHandlerAccess — roles: ["all"] is rejected', () => {
+  test("a write handler with roles: ['all'] throws, naming the handler", () => {
+    const feature = defineFeature("no-all-write", (r) => {
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { roles: ["all"] },
+        },
+      );
+    });
+
+    expect(() => validateHandlerAccess(feature)).toThrow(/no-all-write:write:note:create/);
+    expect(() => validateHandlerAccess(feature)).toThrow(/no session ever carries the role "all"/);
+  });
+
+  test("a query handler with roles: ['all'] throws, naming the handler", () => {
+    const feature = defineFeature("no-all-query", (r) => {
+      r.queryHandler(
+        "note:list",
+        z.object({}),
+        async () => ({ isSuccess: true as const, data: {} }),
+        {
+          access: { roles: ["all"] },
+        },
+      );
+    });
+
+    expect(() => validateHandlerAccess(feature)).toThrow(/no-all-query:query:note:list/);
+  });
+
+  test("openToAll access is unaffected", () => {
+    const feature = defineFeature("open-to-all-ok", (r) => {
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { openToAll: { reason: "any signed-in user" } },
+        },
+      );
+    });
+
+    expect(() => validateHandlerAccess(feature)).not.toThrow();
+  });
+
+  test("roles: ['anonymous'] with a rateLimit boots fine", () => {
+    const feature = defineFeature("anon-ok", (r) => {
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        {
+          access: { roles: ["anonymous"] },
+          rateLimit: { per: "ip", limit: 10, windowSeconds: 60 },
+        },
+      );
+    });
+
+    expect(() => validateHandlerAccess(feature)).not.toThrow();
+  });
+});

package/src/engine/boot-validator/access-declarations.ts

@@ -1,3 +1,4 @@
+import { ANONYMOUS_ROLE } from "../system-user";
 import type {
   AccessRule,
   FeatureDefinition,
@@ -73,12 +74,14 @@ function candidatePersonalFieldNames(
   feature: FeatureDefinition,
   handlerName: string,
   handler: WriteHandlerDef,
+  honorOwnerBindingOverride?: boolean,
 ): ReadonlySet<string> {
   const mappedEntityName = feature.handlerEntityMappings?.[handlerName];
   const entities = feature.entities ?? {};
   if (mappedEntityName) {
     const entity = entities[mappedEntityName];
-    const honorOwnerBinding = !canWriteAroundExecutor(feature, handler);
+    const honorOwnerBinding =
+      honorOwnerBindingOverride ?? !canWriteAroundExecutor(feature, handler);
     return entity ? personalFieldNames(entity, honorOwnerBinding) : new Set();
   }
   const names = new Set<string>();
@@ -103,12 +106,17 @@ function hasOpenToAll(access: AccessRule): boolean {
 
 // Read via `unknown`: access can come from untyped sources (pattern JSON, Designer).
 function declaredPersonalData(access: AccessRule): unknown {
-  if (!("openToAll" in access)) return undefined;
+  if (!("openToAll" in access)) return access.personalData;
   const openToAll: unknown = access.openToAll;
   if (typeof openToAll !== "object" || openToAll === null) return undefined;
   return "personalData" in openToAll ? openToAll.personalData : undefined;
 }
 
+function accessAllowsAnonymous(access: AccessRule): boolean {
+  if ("openToAll" in access) return false;
+  return Array.isArray(access.roles) && access.roles.includes(ANONYMOUS_ROLE);
+}
+
 function declaresTenantMembersPersonalData(access: AccessRule): boolean {
   return declaredPersonalData(access) === "tenant-members";
 }
@@ -154,9 +162,10 @@ function validatePersonalDataOnlyOnWrite(
 ): void {
   // skip: write handlers may declare personalData, or it wasn't declared here
   if (kind === "write" || declaredPersonalData(access) === undefined) return;
+  const property = "openToAll" in access ? "openToAll.personalData" : "access.personalData";
   throw new Error(
     `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
-      "openToAll.personalData — it only applies to write handlers, whose input is " +
+      `${property} — it only applies to write handlers, whose input is ` +
       "checked for personal-data fields.",
   );
 }
@@ -167,11 +176,29 @@ function validatePersonalDataValue(
   access: AccessRule,
 ): void {
   const declared = declaredPersonalData(access);
-  // skip: nothing declared, or the one supported value
-  if (declared === undefined || declared === "tenant-members") return;
+  // skip: nothing declared
+  if (declared === undefined) return;
+  if ("openToAll" in access) {
+    // skip: the one supported value on openToAll
+    if (declared === "tenant-members") return;
+    throw new Error(
+      `[Feature ${feature.name}] write handler "${handlerName}" declares an unknown ` +
+        `openToAll.personalData ${JSON.stringify(declared)} — the only supported value is "tenant-members".`,
+    );
+  }
+  if (declared !== "public-intake") {
+    throw new Error(
+      `[Feature ${feature.name}] write handler "${handlerName}" declares an unknown ` +
+        `access.personalData ${JSON.stringify(declared)} — the only supported value is "public-intake".`,
+    );
+  }
+  // skip: roles include "anonymous", which personalData: "public-intake" requires
+  if (Array.isArray(access.roles) && access.roles.includes(ANONYMOUS_ROLE)) return;
   throw new Error(
-    `[Feature ${feature.name}] write handler "${handlerName}" declares an unknown ` +
-      `openToAll.personalData ${JSON.stringify(declared)} — the only supported value is "tenant-members".`,
+    `[Feature ${feature.name}] write handler "${handlerName}" declares ` +
+      'access.personalData: "public-intake" but its roles do not include ' +
+      `"${ANONYMOUS_ROLE}" — personalData: "public-intake" only applies to handlers ` +
+      "that allow anonymous callers.",
   );
 }
 
@@ -200,12 +227,37 @@ function validateOpenToAllPersonalData(
   );
 }
 
+// Anonymous callers all share one user.id, so honorOwnerBindingOverride is always false here.
+function validateAnonymousPersonalData(
+  feature: FeatureDefinition,
+  handlerName: string,
+  handler: WriteHandlerDef,
+): void {
+  const access = handler.access;
+  // skip: not reachable by an anonymous caller, or already declares public-intake
+  if (!accessAllowsAnonymous(access) || declaredPersonalData(access) === "public-intake") return;
+  const inputKeys = collectZodObjectKeys(handler.schema);
+  const personalNames = candidatePersonalFieldNames(feature, handlerName, handler, false);
+  const offending = [...inputKeys].filter((key) => personalNames.has(key));
+  // skip: no personal-data fields in the handler's input
+  if (offending.length === 0) return;
+  throw new Error(
+    `[Feature ${feature.name}] write handler "${handlerName}" allows anonymous callers ` +
+      `("${ANONYMOUS_ROLE}" in access.roles) and accepts personal-data field(s) ` +
+      `${offending.map((f) => `"${f}"`).join(", ")}. Declare ` +
+      'access: { roles: [..., "anonymous"], personalData: "public-intake" } — every anonymous ' +
+      'request shares one caller identity, so owner-binding via from("user:id", ...) does not ' +
+      "vouch for it; protection comes from the handler's required rateLimit (per ip).",
+  );
+}
+
 export function validateAccessDeclarations(feature: FeatureDefinition): void {
   for (const [handlerName, handler] of Object.entries(feature.writeHandlers)) {
     validateOpenToAllReason(feature, "write", handlerName, handler.access);
     validateEscapeHatchReason(feature, "write", handlerName, handler.escapeHatch);
     validatePersonalDataValue(feature, handlerName, handler.access);
     validateOpenToAllPersonalData(feature, handlerName, handler);
+    validateAnonymousPersonalData(feature, handlerName, handler);
   }
   for (const [handlerName, handler] of Object.entries(feature.queryHandlers)) {
     validateOpenToAllReason(feature, "query", handlerName, handler.access);

package/src/engine/boot-validator/entity-handler.ts

@@ -148,6 +148,7 @@ export function validateHandlerAccess(feature: FeatureDefinition): void {
             `Set { roles: [...] } for role-based access, or { openToAll: { reason: "..." } } for any authenticated user.`,
         );
       }
+      validateNoAllRoleInHandlerAccess(feature.name, kind, name, handler.access);
       validateAnonymousRateLimit(feature.name, kind, name, handler.access, handler.rateLimit);
       validateRateLimitDisabledReason(feature.name, kind, name, handler.rateLimit);
     }
@@ -171,6 +172,25 @@ export function validateRateLimitDisabledReason(
   }
 }
 
+// No session ever carries the role "all" — `roles: ["all"]` is unreachable dead config, not a wildcard.
+export function validateNoAllRoleInHandlerAccess(
+  featureName: string,
+  kind: "write" | "query" | "stream",
+  handlerName: string,
+  access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>,
+): void {
+  // skip: openToAll has no roles list to check
+  if (!("roles" in access)) return;
+  // skip: no "all" in the roles list, nothing unreachable to report
+  if (!access.roles.includes("all")) return;
+  throw new Error(
+    `${kind} handler "${featureName}:${kind}:${handlerName}" declares access: { roles: ["all"] } — ` +
+      `no session ever carries the role "all", so this handler is unreachable by any caller. ` +
+      `Use access: { roles: ["anonymous"] } plus rateLimit: { per: "ip", ... } (or "ip+handler") ` +
+      `for unauthenticated callers, or access: { openToAll: { reason: "..." } } for any signed-in user.`,
+  );
+}
+
 export function validateAnonymousRateLimit(
   featureName: string,
   kind: "write" | "query" | "stream",

package/src/engine/feature-ast/__tests__/patch.test.ts

@@ -239,6 +239,7 @@ describe("patch coverage for the remaining pattern-kinds", () => {
       method: "GET",
       path: "/health",
       handlerSource: "async (c) => c.json({ ok: true })",
+      anonymous: true,
     });
     expect(parseSourceFile(sf).patterns).toHaveLength(3);
     removePattern(sf, { kind: "httpRoute", method: "GET", path: "/health" });

package/src/engine/feature-ast/__tests__/patcher.test.ts

@@ -328,6 +328,7 @@ describe("FeaturePatcher — coverage for the remaining typed adds", () => {
       method: "GET",
       path: "/health",
       handlerSource: "async (c) => c.json({ ok: true })",
+      anonymous: true,
     });
     const result = parseSourceFile(sf);
     expect(result.errors).toEqual([]);

package/src/engine/feature-ast/__tests__/read-optional-access-rule.test.ts

@@ -26,3 +26,17 @@ describe("readOptionalAccessRule — openToAll.personalData", () => {
     ).toBeUndefined();
   });
 });
+
+describe("readOptionalAccessRule — roles.personalData", () => {
+  test("keeps personalData: public-intake on the roles form", () => {
+    expect(readOptionalAccessRule({ roles: ["anonymous"], personalData: "public-intake" })).toEqual(
+      { roles: ["anonymous"], personalData: "public-intake" },
+    );
+  });
+
+  test("drops an unknown personalData value on the roles form", () => {
+    expect(
+      readOptionalAccessRule({ roles: ["anonymous"], personalData: "tenant-members" }),
+    ).toEqual({ roles: ["anonymous"] });
+  });
+});

package/src/engine/feature-ast/extractors/hooks.ts

@@ -41,7 +41,9 @@ export function readOptionalPhase(node: Node | undefined): HookPhase | undefined
 export function readOptionalAccessRule(value: unknown): AccessRule | undefined {
   if (!isPlainObject(value)) return undefined;
   if (Array.isArray(value["roles"]) && value["roles"].every((r) => typeof r === "string")) {
-    return { roles: value["roles"] as readonly string[] };
+    const personalData =
+      value["personalData"] === "public-intake" ? { personalData: "public-intake" as const } : {};
+    return { roles: value["roles"] as readonly string[], ...personalData };
   }
   const openToAll = value["openToAll"];
   if (isPlainObject(openToAll) && typeof openToAll["reason"] === "string") {

package/src/engine/feature-ast/extractors/jobs-routes.ts

@@ -210,13 +210,16 @@ export function extractHttpRoute(
       "handler must be an inline arrow function or function expression",
     );
   }
-  const anonymous = readBooleanProperty(arg, "anonymous");
+  // Missing/non-boolean `anonymous` reads as false (the safe side — mounted
+  // behind the session auth chain, not public) so a source file that predates
+  // the required field still parses instead of erroring here.
+  const anonymous = readBooleanProperty(arg, "anonymous") === true;
   return ok({
     kind: "httpRoute",
     source: sourceLocationFromNode(call, sourceFile),
     method: methodValue,
     path: pathLiteral.getLiteralValue(),
     handlerBody: sourceLocationFromNode(fn, sourceFile),
-    ...(anonymous === true && { anonymous: true }),
+    anonymous,
   });
 }

package/src/engine/feature-ast/patcher.ts

@@ -149,7 +149,7 @@ export type AddHttpRouteArgs = {
   readonly method: HttpRouteMethod;
   readonly path: string;
   readonly handlerSource: string;
-  readonly anonymous?: boolean;
+  readonly anonymous: boolean;
 };
 
 export type AddDefineEventArgs = {
@@ -480,7 +480,7 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
         method,
         path,
         handlerBody: rawLoc(handlerSource),
-        ...(anonymous === true && { anonymous: true }),
+        anonymous,
       });
     },
 

package/src/engine/feature-ast/patterns.ts

@@ -508,7 +508,7 @@ export type HttpRoutePattern = {
   readonly source: SourceLocation;
   readonly method: HttpRouteMethod;
   readonly path: string;
-  readonly anonymous?: boolean;
+  readonly anonymous: boolean;
   readonly handlerBody: SourceLocation;
 };
 

package/src/engine/feature-ast/render.ts

@@ -558,7 +558,7 @@ function renderHttpRoute(p: HttpRoutePattern): string {
   const lines: string[] = ["r.httpRoute({"];
   lines.push(`  method: ${JSON.stringify(p.method)},`);
   lines.push(`  path: ${JSON.stringify(p.path)},`);
-  if (p.anonymous === true) lines.push("  anonymous: true,");
+  lines.push(`  anonymous: ${p.anonymous},`);
   lines.push(`  handler: ${p.handlerBody.raw},`);
   lines.push("});");
   return lines.join("\n");

package/src/engine/feature-ui-extensions.ts

@@ -498,6 +498,12 @@ export function buildUiExtensionsMethods<TName extends string>(
             `Pick a different path or use r.queryHandler / r.writeHandler.`,
         );
       }
+      if (typeof definition.anonymous !== "boolean") {
+        throw new Error(
+          `[Feature ${name}] httpRoute "${definition.method} ${definition.path}" must declare ` +
+            `anonymous: true | false — true mounts it public, false behind the session auth chain.`,
+        );
+      }
       const key = `${definition.method} ${definition.path}`;
       if (state.httpRoutes[key]) {
         throw new Error(

package/src/engine/index.ts

@@ -476,6 +476,8 @@ export type {
   RelationDefinition,
   ResolvedPiiFlags,
   RetentionDef,
+  RoleAccessPersonalData,
+  RoleAccessRule,
   RowAction,
   RowActionNavigate,
   RowActionNavigateBase,

package/src/engine/membership-roles.ts

@@ -6,8 +6,9 @@
 // survive a projection rebuild: replaying a stored membership event goes
 // through the apply path, not the handler. stripForbiddenMembershipRoles is
 // the read-time backstop — applied at every JWT mint that derives roles from
-// membership, it neutralises a resurrected role without touching globalRoles
-// (where SystemAdmin legitimately lives).
+// membership, it neutralises a resurrected role. buildSessionRoles applies a
+// matching strip (anonymous/all only) to globalRoles, where SystemAdmin
+// legitimately lives.
 
 import { access } from "./config-helpers";
 
@@ -26,11 +27,21 @@ export function findForbiddenMembershipRole(roles: readonly string[]): string |
 }
 
 // Filters reserved roles out of the membership portion only. Callers merge the
-// result with globalRoles, which is never filtered.
+// result with globalRoles, which buildSessionRoles filters separately below.
 export function stripForbiddenMembershipRoles(roles: readonly string[]): readonly string[] {
   return roles.filter((role) => !isForbiddenMembershipRole(role));
 }
 
+// "anonymous"/"all" are never legitimate global roles; system/SystemAdmin stay.
+const NON_MINTABLE_GLOBAL_ROLES: ReadonlySet<string> = new Set<string>([
+  ...access.all,
+  ...access.anonymous,
+]);
+
+function stripNonMintableGlobalRoles(roles: readonly string[]): readonly string[] {
+  return roles.filter((role) => !NON_MINTABLE_GLOBAL_ROLES.has(role));
+}
+
 // Single mint path for session roles: merges globalRoles with the stripped
 // membership portion and dedupes. Every place that builds a session's roles
 // from a membership should go through this instead of repeating
@@ -41,5 +52,10 @@ export function buildSessionRoles(
   globalRoles: readonly string[],
   membershipRoles: readonly string[],
 ): readonly string[] {
-  return Array.from(new Set([...globalRoles, ...stripForbiddenMembershipRoles(membershipRoles)]));
+  return Array.from(
+    new Set([
+      ...stripNonMintableGlobalRoles(globalRoles),
+      ...stripForbiddenMembershipRoles(membershipRoles),
+    ]),
+  );
 }

package/src/engine/pattern-library/__tests__/library.test.ts

@@ -315,6 +315,7 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
         source: PLACEHOLDER_LOC,
         method: "GET",
         path: "/x",
+        anonymous: true,
         handlerBody: PLACEHOLDER_BODY_LOC,
       };
     case "projection":

package/src/engine/pattern-library/mixed-schemas.ts

@@ -453,6 +453,7 @@ export const httpRouteSchema: PatternFormSchema = {
       path: "anonymous",
       label: { en: "Anonymous (no auth)", de: "Anonym (keine Auth)" },
       input: "boolean",
+      required: true,
     },
     {
       path: "handlerBody",

package/src/engine/types/index.ts

@@ -194,6 +194,8 @@ export type {
   RateLimitDisabled,
   RateLimitOption,
   RateLimitPer,
+  RoleAccessPersonalData,
+  RoleAccessRule,
   SessionUser,
   SessionUserOrigin,
   StreamHandlerDef,

package/src/observability/__tests__/metrics-wiring.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import { composeEnvSchema, readKumikoMeta } from "../../env";
+import { prometheusMetricsEnvSchema, resolveObservabilityWiring } from "../metrics-wiring";
+
+describe("resolveObservabilityWiring", () => {
+  it("returns {} without a token", () => {
+    expect(resolveObservabilityWiring(undefined)).toEqual({});
+  });
+
+  it("returns {} for an empty token", () => {
+    expect(resolveObservabilityWiring("")).toEqual({});
+  });
+
+  it("wires a prometheus provider and metrics route when a token is set", () => {
+    const token = "a".repeat(32);
+    const wiring = resolveObservabilityWiring(token);
+
+    expect("metrics" in wiring).toBe(true);
+    if (!("metrics" in wiring)) throw new Error("expected wiring to include metrics");
+
+    expect(wiring.metrics).toEqual({ path: "/metrics", token });
+    expect(wiring.observability.name).toBe("prometheus");
+    expect(wiring.observability.meter.snapshot()).toEqual(new Map());
+  });
+});
+
+describe("prometheusMetricsEnvSchema", () => {
+  it("rejects tokens shorter than 32 characters", () => {
+    const result = prometheusMetricsEnvSchema.safeParse({
+      PROMETHEUS_METRICS_TOKEN: "a".repeat(31),
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts a 32-character token", () => {
+    const result = prometheusMetricsEnvSchema.safeParse({
+      PROMETHEUS_METRICS_TOKEN: "a".repeat(32),
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a missing token", () => {
+    const result = prometheusMetricsEnvSchema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("exposes pulumi secret metadata for consumer env-schemas", () => {
+    const { schema } = composeEnvSchema({
+      features: [],
+      extend: z.object({ FOO: z.string() }).extend(prometheusMetricsEnvSchema.shape),
+    });
+
+    const field = schema.shape["PROMETHEUS_METRICS_TOKEN"];
+    if (!(field instanceof z.ZodType))
+      throw new Error("expected PROMETHEUS_METRICS_TOKEN in composed schema");
+    const meta = readKumikoMeta(field);
+    expect(meta.pulumi?.secret).toBe(true);
+    expect(meta.pulumi?.generator).toBe("openssl rand -base64 32");
+  });
+});

package/src/observability/index.ts

@@ -16,6 +16,11 @@ export {
   createSafeMetricsHandle,
   createUnboundMetricsHandle,
 } from "./metrics-handle";
+export {
+  type ObservabilityWiring,
+  prometheusMetricsEnvSchema,
+  resolveObservabilityWiring,
+} from "./metrics-wiring";
 export { createNoopProvider } from "./noop-provider";
 export {
   createPrometheusMeter,