@checkstack/auth-backend 0.4.33 → 0.5.0

package/src/oauth-branch.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import type { RealUser } from "@checkstack/backend-api";
+import { narrowedPrincipalFromSession } from "./oauth-branch";
+
+const CATALOG = [
+  "incident.incident.read",
+  "incident.incident.manage",
+  "anomaly.anomaly.read",
+];
+
+function liveUser(accessRules: string[]): RealUser {
+  return {
+    type: "user",
+    id: "u1",
+    email: "u1@example.com",
+    name: "User One",
+    roles: ["users"],
+    accessRules,
+    teamIds: ["team-a", "team-b"],
+  };
+}
+
+describe("narrowedPrincipalFromSession (§6.3)", () => {
+  test("accessRules = granted ∩ liveRules (NOT the full live rules)", () => {
+    const principal = narrowedPrincipalFromSession({
+      session: {
+        userId: "u1",
+        scopes: "incident.incident.read incident.incident.manage",
+      },
+      principal: {
+        base: liveUser(["incident.incident.read", "anomaly.anomaly.read"]),
+        catalog: CATALOG,
+      },
+    });
+    // manage granted but not held -> dropped; anomaly held but not granted -> absent.
+    expect(principal?.accessRules).toEqual(["incident.incident.read"]);
+  });
+
+  test("teamIds are inherited verbatim from the live enrichment", () => {
+    const principal = narrowedPrincipalFromSession({
+      session: { userId: "u1", scopes: "incident.incident.read" },
+      principal: {
+        base: liveUser(["incident.incident.read"]),
+        catalog: CATALOG,
+      },
+    });
+    expect(principal?.teamIds).toEqual(["team-a", "team-b"]);
+    expect(principal?.type).toBe("user");
+  });
+
+  test("a rule the principal has since LOST is dropped (live narrowing)", () => {
+    const principal = narrowedPrincipalFromSession({
+      session: { userId: "u1", scopes: "incident.incident.manage" },
+      principal: {
+        // The live user no longer has manage.
+        base: liveUser(["incident.incident.read"]),
+        catalog: CATALOG,
+      },
+    });
+    expect(principal?.accessRules).toEqual([]);
+  });
+
+  test("a token with no granted scopes is treated as unauthenticated", () => {
+    const principal = narrowedPrincipalFromSession({
+      session: { userId: "u1", scopes: "" },
+      principal: { base: liveUser(["incident.incident.read"]), catalog: CATALOG },
+    });
+    expect(principal).toBeUndefined();
+  });
+
+  test("admin token carries the concrete granted set, never the bare wildcard", () => {
+    const principal = narrowedPrincipalFromSession({
+      session: { userId: "u1", scopes: "checkstack:write" },
+      principal: { base: liveUser(["*"]), catalog: CATALOG },
+    });
+    expect(principal?.accessRules?.sort()).toEqual([...CATALOG].sort());
+    expect(principal?.accessRules).not.toContain("*");
+  });
+});

package/src/oauth-branch.ts

@@ -0,0 +1,99 @@
+import { eq } from "drizzle-orm";
+import type { RealUser, SafeDatabase } from "@checkstack/backend-api";
+import { narrowScopes } from "./scope-narrowing";
+import * as schema from "./schema";
+
+// Re-export the shared opaque-bearer extractor so existing import sites in this
+// plugin (index.ts) keep working without changing their import path.
+export { opaqueBearerToken } from "@checkstack/backend-api";
+
+/**
+ * The introspected OAuth session — the subset of better-auth's
+ * `OAuthAccessToken` row this branch needs. Tokens are OPAQUE (decision §11):
+ * this is the result of a DB introspection, not a decoded JWT.
+ */
+export interface IntrospectedOAuthSession {
+  /** The bound principal's user id (`OAuthAccessToken.userId`). */
+  userId: string;
+  /** Space-delimited granted scopes (`OAuthAccessToken.scopes`). */
+  scopes: string;
+}
+
+/**
+ * Introspect an OPAQUE OAuth access token against the oidcProvider-owned
+ * `oauthAccessToken` table (decision §11 — tokens are not JWTs, so this is a DB
+ * lookup, the same `findOne` the mcp plugin's `getMcpSession` performs, plus an
+ * explicit expiry check which `getMcpSession` does NOT do). Returns the session
+ * subset, or `undefined` when the token is unknown or expired.
+ */
+export async function introspectOpaqueToken({
+  db,
+  token,
+  now = new Date(),
+}: {
+  db: SafeDatabase<typeof schema>;
+  token: string;
+  now?: Date;
+}): Promise<IntrospectedOAuthSession | undefined> {
+  const rows = await db
+    .select({
+      userId: schema.oauthAccessToken.userId,
+      scopes: schema.oauthAccessToken.scopes,
+      expiresAt: schema.oauthAccessToken.accessTokenExpiresAt,
+    })
+    .from(schema.oauthAccessToken)
+    .where(eq(schema.oauthAccessToken.accessToken, token))
+    .limit(1);
+
+  const row = rows[0];
+  if (!row || !row.userId || !row.scopes) return undefined;
+  if (row.expiresAt && new Date(row.expiresAt).getTime() <= now.getTime()) {
+    return undefined; // expired
+  }
+  return { userId: row.userId, scopes: row.scopes };
+}
+
+/**
+ * The principal's LIVE rules + teams, resolved by the same machinery the UI
+ * uses (`enrichUser`). Passed in so this module stays pure and DB-agnostic.
+ */
+export interface LivePrincipal {
+  base: RealUser;
+  /** All currently-registered qualified access-rule IDs (for bundle/admin expansion). */
+  catalog: string[];
+}
+
+/**
+ * Build a NARROWED principal from an introspected opaque OAuth token.
+ *
+ * The crux (decision 4, §6.3): enrich the bound user to their CURRENT full
+ * access rules, then intersect with the token's granted scopes. Narrowing runs
+ * live on every call, so a rule the principal has since lost is dropped on the
+ * next call — strictly stronger than freezing claims into a JWT at mint.
+ *
+ * Returns `undefined` when the token has no granted scopes (it can do nothing,
+ * so it is treated as unauthenticated rather than as a zero-rule principal).
+ */
+export function narrowedPrincipalFromSession({
+  session,
+  principal,
+}: {
+  session: IntrospectedOAuthSession;
+  principal: LivePrincipal;
+}): RealUser | undefined {
+  const granted = session.scopes.split(" ").filter(Boolean);
+  if (granted.length === 0) return undefined;
+
+  const narrowedRules = narrowScopes({
+    requested: granted,
+    principalRules: principal.base.accessRules ?? [],
+    catalog: principal.catalog,
+  });
+
+  // Narrow-only: accessRules is replaced by the (subset) narrowed set; teamIds
+  // are inherited verbatim from the live enrichment.
+  return {
+    ...principal.base,
+    accessRules: narrowedRules,
+  };
+}

package/src/rate-limit.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { windowStartFor } from "./rate-limit";
+
+describe("windowStartFor", () => {
+  test("floors a timestamp to the start of its fixed window", () => {
+    const now = new Date("2026-06-02T10:17:42.000Z");
+    const start = windowStartFor({ now, windowSeconds: 3600 });
+    expect(start.toISOString()).toBe("2026-06-02T10:00:00.000Z");
+  });
+
+  test("two timestamps in the same window share a window start (one counter)", () => {
+    const a = windowStartFor({
+      now: new Date("2026-06-02T10:00:01.000Z"),
+      windowSeconds: 3600,
+    });
+    const b = windowStartFor({
+      now: new Date("2026-06-02T10:59:59.000Z"),
+      windowSeconds: 3600,
+    });
+    expect(a.getTime()).toBe(b.getTime());
+  });
+
+  test("the next window gets a distinct start (counter resets)", () => {
+    const a = windowStartFor({
+      now: new Date("2026-06-02T10:59:59.000Z"),
+      windowSeconds: 3600,
+    });
+    const b = windowStartFor({
+      now: new Date("2026-06-02T11:00:00.000Z"),
+      windowSeconds: 3600,
+    });
+    expect(b.getTime()).toBeGreaterThan(a.getTime());
+  });
+});

package/src/rate-limit.ts

@@ -0,0 +1,73 @@
+import { sql } from "drizzle-orm";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import * as schema from "./schema";
+
+/**
+ * Shared-Postgres fixed-window rate limiter (state-and-scale §14.5).
+ *
+ * The counter lives in the `ai_rate_limit` table, so the cap holds across ALL
+ * pods — an in-memory per-pod limiter would let N pods each allow the cap, i.e.
+ * N x the intended limit, which a single-process test would never catch. This
+ * is LOCKED: the limiter MUST be Postgres-backed, never in-memory.
+ *
+ * Each call atomically bumps the counter for `(key, windowStart)` and returns
+ * the post-increment count, so the increment + read is a single round-trip with
+ * no read-modify-write race between pods.
+ */
+
+/** Floor a timestamp to the start of its fixed window. */
+export function windowStartFor({
+  now,
+  windowSeconds,
+}: {
+  now: Date;
+  windowSeconds: number;
+}): Date {
+  const windowMs = windowSeconds * 1000;
+  return new Date(Math.floor(now.getTime() / windowMs) * windowMs);
+}
+
+export interface RateLimitResult {
+  /** Count AFTER this call's increment. */
+  count: number;
+  /** Whether this call is within the limit (`count <= max`). */
+  allowed: boolean;
+  /** The window this call was counted against. */
+  windowStart: Date;
+}
+
+/**
+ * Atomically increment and check a fixed-window counter.
+ *
+ * Returns `{ allowed: false }` when the post-increment count exceeds `max`.
+ * Callers decide the response (e.g. 429 for the DCR endpoint).
+ */
+export async function checkRateLimit({
+  db,
+  key,
+  max,
+  windowSeconds,
+  now = new Date(),
+}: {
+  db: SafeDatabase<typeof schema>;
+  key: string;
+  max: number;
+  windowSeconds: number;
+  now?: Date;
+}): Promise<RateLimitResult> {
+  const windowStart = windowStartFor({ now, windowSeconds });
+
+  // INSERT ... ON CONFLICT (key, window_start) DO UPDATE SET count = count + 1
+  // RETURNING count. Single atomic statement: no read-modify-write race.
+  const rows = await db
+    .insert(schema.aiRateLimit)
+    .values({ key, windowStart, count: 1 })
+    .onConflictDoUpdate({
+      target: [schema.aiRateLimit.key, schema.aiRateLimit.windowStart],
+      set: { count: sql`${schema.aiRateLimit.count} + 1` },
+    })
+    .returning({ count: schema.aiRateLimit.count });
+
+  const count = rows[0]?.count ?? 1;
+  return { count, allowed: count <= max, windowStart };
+}

package/src/router.ts

@@ -14,6 +14,7 @@ import {
   passwordSchema,
   authAccess,
   pluginMetadata,
+  isApplicationBindable,
 } from "@checkstack/auth-common";
 import { qualifyAccessRuleId } from "@checkstack/common";
 import { hashPassword } from "better-auth/crypto";
@@ -21,6 +22,7 @@ import * as schema from "./schema";
 import { eq, inArray, and } from "drizzle-orm";
 import type { SafeDatabase } from "@checkstack/backend-api";
 import { authHooks } from "./hooks";
+import { enrichApplicationPrincipal as resolveApplicationPrincipal } from "./utils/user";
 
 /**
  * Type guard to check if user is a RealUser (not a service).
@@ -37,6 +39,11 @@ import {
   PLATFORM_REGISTRATION_CONFIG_VERSION,
   PLATFORM_REGISTRATION_CONFIG_ID,
 } from "./platform-registration-config";
+import {
+  mcpOAuthConfigV1,
+  MCP_OAUTH_CONFIG_VERSION,
+  MCP_OAUTH_CONFIG_ID,
+} from "./mcp-oauth-config";
 
 export const ADMIN_ROLE_ID = "admin";
 export const USERS_ROLE_ID = "users";
@@ -663,6 +670,41 @@ export const createAuthRouter = (
     },
   );
 
+  const getMcpOAuthSettings = os.getMcpOAuthSettings.handler(async () => {
+    const cfg = await configService.get(
+      MCP_OAUTH_CONFIG_ID,
+      mcpOAuthConfigV1,
+      MCP_OAUTH_CONFIG_VERSION,
+    );
+    // Defaults mirror the schema (off by default).
+    return {
+      enabled: cfg?.enabled ?? false,
+      allowDynamicClientRegistration:
+        cfg?.allowDynamicClientRegistration ?? false,
+      dcrRateLimitMax: cfg?.dcrRateLimitMax ?? 5,
+      dcrRateLimitWindowSeconds: cfg?.dcrRateLimitWindowSeconds ?? 3600,
+    };
+  });
+
+  const setMcpOAuthSettings = os.setMcpOAuthSettings.handler(
+    async ({ input }) => {
+      await configService.set(
+        MCP_OAUTH_CONFIG_ID,
+        mcpOAuthConfigV1,
+        MCP_OAUTH_CONFIG_VERSION,
+        {
+          enabled: input.enabled,
+          allowDynamicClientRegistration: input.allowDynamicClientRegistration,
+          dcrRateLimitMax: input.dcrRateLimitMax,
+          dcrRateLimitWindowSeconds: input.dcrRateLimitWindowSeconds,
+        },
+      );
+      // Enabling/disabling the plugins requires re-initializing better-auth.
+      await reloadAuthFn();
+      return { success: true };
+    },
+  );
+
   // ==========================================================================
   // ONBOARDING ENDPOINTS
   // ==========================================================================
@@ -1441,6 +1483,62 @@ export const createAuthRouter = (
     },
   );
 
+  // S2S: resolve an application principal live for the app-principal token path.
+  const enrichApplicationPrincipal =
+    os.enrichApplicationPrincipal.handler(async ({ input }) => {
+      const enriched = await resolveApplicationPrincipal(
+        input.applicationId,
+        internalDb,
+      );
+      return enriched ?? null;
+    });
+
+  // List applications the caller may bind as an automation's service account.
+  // An app is bindable only when its access rules are a subset of the caller's
+  // (no privilege escalation); `*`-holders may bind anything.
+  const getBindableApplications = os.getBindableApplications.handler(
+    async ({ context }) => {
+      const callerRules = isRealUser(context.user)
+        ? (context.user.accessRules ?? [])
+        : [];
+
+      const apps = await internalDb.select().from(schema.application);
+      const bindable: {
+        id: string;
+        name: string;
+        description: string | null;
+      }[] = [];
+
+      const callerIsAdmin = callerRules.includes("*");
+      for (const app of apps) {
+        // Admins bind anything without resolving rules; others need the
+        // per-app subset check.
+        if (!callerIsAdmin) {
+          const enriched = await resolveApplicationPrincipal(
+            app.id,
+            internalDb,
+          );
+          if (!enriched) continue;
+          if (
+            !isApplicationBindable({
+              appAccessRules: enriched.accessRules,
+              callerAccessRules: callerRules,
+            })
+          ) {
+            continue;
+          }
+        }
+        bindable.push({
+          id: app.id,
+          name: app.name,
+          description: app.description,
+        });
+      }
+
+      return bindable;
+    },
+  );
+
   // ==========================================================================
   // TEAM MANAGEMENT HANDLERS
   // ==========================================================================
@@ -1962,6 +2060,8 @@ export const createAuthRouter = (
     getRegistrationSchema,
     getRegistrationStatus,
     setRegistrationStatus,
+    getMcpOAuthSettings,
+    setMcpOAuthSettings,
     getOnboardingStatus,
     completeOnboarding,
     validateResetToken,
@@ -1979,6 +2079,8 @@ export const createAuthRouter = (
     updateApplication,
     deleteApplication,
     regenerateApplicationSecret,
+    enrichApplicationPrincipal,
+    getBindableApplications,
     getOwnStrategyConfig,
     // Teams
     getTeams,

package/src/schema.ts

@@ -4,6 +4,8 @@ import {
   boolean,
   timestamp,
   primaryKey,
+  integer,
+  index,
 } from "drizzle-orm/pg-core";
 
 // --- Better Auth Schema ---
@@ -278,3 +280,73 @@ export const resourceTeamAccess = pgTable(
     pk: primaryKey({ columns: [t.resourceType, t.resourceId, t.teamId] }),
   })
 );
+
+// --- AI platform: OAuth Authorization Server (better-auth oidcProvider/mcp) ---
+//
+// These three tables are OWNED by the better-auth `oidcProvider` + `mcp`
+// plugins (Phase 2). The plugins' Drizzle adapter resolves them by the camelCase
+// model keys below (`oauthApplication`, `oauthAccessToken`, `oauthConsent`) and
+// the camelCase field keys; column names are snake_case to match repo
+// convention. Field shapes mirror the plugin schema exactly (see
+// SPIKE-findings.md). Access tokens are OPAQUE random strings persisted here —
+// validation is an introspection lookup, not a JWKS verify (decision §11).
+
+/** Registered OAuth clients (incl. dynamically-registered MCP clients). */
+export const oauthApplication = pgTable("oauth_application", {
+  id: text("id").primaryKey(),
+  name: text("name"),
+  icon: text("icon"),
+  metadata: text("metadata"),
+  clientId: text("client_id").unique(),
+  clientSecret: text("client_secret"),
+  redirectUrls: text("redirect_urls"),
+  type: text("type"),
+  disabled: boolean("disabled").default(false),
+  userId: text("user_id"),
+  createdAt: timestamp("created_at"),
+  updatedAt: timestamp("updated_at"),
+});
+
+/** Issued opaque access/refresh tokens + their granted scopes. */
+export const oauthAccessToken = pgTable("oauth_access_token", {
+  id: text("id").primaryKey(),
+  accessToken: text("access_token").unique(),
+  refreshToken: text("refresh_token").unique(),
+  accessTokenExpiresAt: timestamp("access_token_expires_at"),
+  refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
+  clientId: text("client_id"),
+  userId: text("user_id"),
+  scopes: text("scopes"),
+  createdAt: timestamp("created_at"),
+  updatedAt: timestamp("updated_at"),
+});
+
+/** Per-(client,user) consent record for the consent screen. */
+export const oauthConsent = pgTable("oauth_consent", {
+  id: text("id").primaryKey(),
+  clientId: text("client_id"),
+  userId: text("user_id"),
+  scopes: text("scopes"),
+  createdAt: timestamp("created_at"),
+  updatedAt: timestamp("updated_at"),
+  consentGiven: boolean("consent_given"),
+});
+
+// --- AI platform: shared-Postgres rate-limit counter (state-and-scale §14.5) ---
+//
+// Fixed-window counter so a limit holds across ALL pods (an in-memory per-pod
+// limiter would let N pods each allow the cap = N x the intended limit). Used
+// today for the DCR endpoint throttle (`dcr:<ip>`); per-principal tool budgets
+// (Phase 3) reuse the same table with a different key.
+export const aiRateLimit = pgTable(
+  "ai_rate_limit",
+  {
+    key: text("key").notNull(),
+    windowStart: timestamp("window_start").notNull(),
+    count: integer("count").notNull().default(0),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.key, t.windowStart] }),
+    keyIdx: index("ai_rate_limit_key_idx").on(t.key, t.windowStart),
+  }),
+);

package/src/scope-narrowing.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, test } from "bun:test";
+import {
+  SCOPE_BUNDLE,
+  expandBundles,
+  narrowScopes,
+} from "./scope-narrowing";
+
+const CATALOG = [
+  "incident.incident.read",
+  "incident.incident.manage",
+  "healthcheck.config.read",
+  "healthcheck.config.manage",
+  "anomaly.anomaly.read",
+  "ai.tools.manage",
+];
+
+describe("expandBundles", () => {
+  test("checkstack:read expands to every *.read rule", () => {
+    expect(
+      expandBundles({ requested: [SCOPE_BUNDLE.read], catalog: CATALOG }).sort(),
+    ).toEqual(
+      [
+        "incident.incident.read",
+        "healthcheck.config.read",
+        "anomaly.anomaly.read",
+      ].sort(),
+    );
+  });
+
+  test("checkstack:write expands to every *.read + *.manage rule", () => {
+    expect(
+      expandBundles({
+        requested: [SCOPE_BUNDLE.write],
+        catalog: CATALOG,
+      }).sort(),
+    ).toEqual([...CATALOG].sort());
+  });
+
+  test("raw rule IDs pass through unchanged", () => {
+    expect(
+      expandBundles({
+        requested: ["incident.incident.read"],
+        catalog: CATALOG,
+      }),
+    ).toEqual(["incident.incident.read"]);
+  });
+
+  test("unknown bundle-like strings are kept verbatim (intersection drops them)", () => {
+    // Not a known bundle: kept as a raw id, then dropped by narrowScopes.
+    expect(
+      expandBundles({ requested: ["checkstack:everything"], catalog: CATALOG }),
+    ).toEqual(["checkstack:everything"]);
+  });
+});
+
+describe("narrowScopes", () => {
+  test("intersects granted scopes with the principal's live rules", () => {
+    const narrowed = narrowScopes({
+      requested: ["incident.incident.read", "incident.incident.manage"],
+      principalRules: ["incident.incident.read", "anomaly.anomaly.read"],
+      catalog: CATALOG,
+    });
+    // manage was granted but the principal lacks it -> dropped.
+    expect(narrowed).toEqual(["incident.incident.read"]);
+  });
+
+  test("checkstack:write narrows to only what the principal actually has", () => {
+    const narrowed = narrowScopes({
+      requested: [SCOPE_BUNDLE.write],
+      principalRules: ["incident.incident.read"],
+      catalog: CATALOG,
+    });
+    expect(narrowed).toEqual(["incident.incident.read"]);
+  });
+
+  test("admin (*) can carry any granted rule but NEVER the bare wildcard", () => {
+    const narrowed = narrowScopes({
+      requested: [SCOPE_BUNDLE.write],
+      principalRules: ["*"],
+      catalog: CATALOG,
+    });
+    expect(narrowed.sort()).toEqual([...CATALOG].sort());
+    expect(narrowed).not.toContain("*");
+  });
+
+  test("a rule the principal has since LOST is dropped (live narrowing)", () => {
+    // Token granted incident.manage, but the principal no longer holds it.
+    const narrowed = narrowScopes({
+      requested: ["incident.incident.manage"],
+      principalRules: ["incident.incident.read"],
+      catalog: CATALOG,
+    });
+    expect(narrowed).toEqual([]);
+  });
+
+  // Matrix #5 (Phase 5 hardening, named): the narrow-only invariant is the
+  // single most important OAuth property — a token can only ever narrow, never
+  // widen, what its bound principal could already do. We restate it as an
+  // explicit, named hardening assertion (the fuzz below is the exhaustive
+  // backstop) so the security suite carries it as a first-class regression
+  // guard, not buried in a generic property test.
+  test("HARDENING: scope narrowing can NEVER widen a principal", () => {
+    // A token that requests MORE than the principal holds gains nothing extra.
+    const escalation = narrowScopes({
+      requested: [
+        "incident.incident.read",
+        "incident.incident.manage", // not held
+        "healthcheck.config.manage", // not held
+        SCOPE_BUNDLE.write, // a bundle that would expand to manage rules
+      ],
+      principalRules: ["incident.incident.read"],
+      catalog: CATALOG,
+    });
+    expect(escalation).toEqual(["incident.incident.read"]);
+    // A leaked admin token is NOT a god-token: it carries only the granted set,
+    // never the bare wildcard.
+    const adminGranted = narrowScopes({
+      requested: ["incident.incident.read"],
+      principalRules: ["*"],
+      catalog: CATALOG,
+    });
+    expect(adminGranted).toEqual(["incident.incident.read"]);
+    expect(adminGranted).not.toContain("*");
+  });
+
+  // Matrix #5: property/fuzz — narrowing can NEVER widen.
+  test("PROPERTY: narrowed is always a subset of the principal's effective rules", () => {
+    const universe = [...CATALOG, "*", SCOPE_BUNDLE.read, SCOPE_BUNDLE.write];
+    const rand = (n: number) => Math.floor(Math.random() * n);
+    const pick = (pool: string[]) =>
+      pool.filter(() => Math.random() < 0.5);
+
+    for (let i = 0; i < 1000; i++) {
+      const requested = pick(universe);
+      const principalRules = pick(universe).filter(
+        (r) => r !== SCOPE_BUNDLE.read && r !== SCOPE_BUNDLE.write,
+      );
+      // Occasionally include the admin wildcard.
+      if (rand(5) === 0) principalRules.push("*");
+
+      const narrowed = narrowScopes({
+        requested,
+        principalRules,
+        catalog: CATALOG,
+      });
+
+      const isAdmin = principalRules.includes("*");
+      const effective = new Set(isAdmin ? CATALOG : principalRules);
+      for (const rule of narrowed) {
+        // Never widens: every narrowed rule is within the effective ceiling.
+        expect(effective.has(rule)).toBe(true);
+        // Never the bare god-scope.
+        expect(rule).not.toBe("*");
+      }
+    }
+  });
+});