@checkstack/backend 0.14.0 → 0.16.0

package/src/plugin-manager/pg-http-errors.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import { ORPCError } from "@orpc/server";
+import { mapPgErrorToHttp } from "./pg-http-errors";
+
+/**
+ * Guards the regression where a client-caused Postgres fault (bad uuid,
+ * out-of-range int, over-long string, FK/unique violation) surfaced as a 500
+ * instead of a 4xx. The fuzzing pass found that `where id = $1` with a non-uuid
+ * `$1` reaches the driver and throws `22P02`, which oRPC reported as 500.
+ */
+describe("mapPgErrorToHttp", () => {
+  test("maps invalid_text_representation (bad uuid/int) to 400", () => {
+    const mapped = mapPgErrorToHttp({ code: "22P02" });
+    expect(mapped).toBeInstanceOf(ORPCError);
+    expect(mapped?.code).toBe("BAD_REQUEST");
+  });
+
+  test("maps numeric_value_out_of_range to 400", () => {
+    expect(mapPgErrorToHttp({ code: "22003" })?.code).toBe("BAD_REQUEST");
+  });
+
+  test("maps string_data_right_truncation to 400", () => {
+    expect(mapPgErrorToHttp({ code: "22001" })?.code).toBe("BAD_REQUEST");
+  });
+
+  test("maps foreign_key_violation to 400", () => {
+    expect(mapPgErrorToHttp({ code: "23503" })?.code).toBe("BAD_REQUEST");
+  });
+
+  test("maps unique_violation to 409 CONFLICT", () => {
+    expect(mapPgErrorToHttp({ code: "23505" })?.code).toBe("CONFLICT");
+  });
+
+  test("unwraps a Drizzle-wrapped driver error via cause", () => {
+    const mapped = mapPgErrorToHttp({
+      message: "wrapped",
+      cause: { code: "22P02" },
+    });
+    expect(mapped?.code).toBe("BAD_REQUEST");
+  });
+
+  test("returns undefined for an unknown SQLSTATE (genuine 500 stays a 500)", () => {
+    // 40001 = serialization_failure: a real server fault, not client input.
+    expect(mapPgErrorToHttp({ code: "40001" })).toBeUndefined();
+  });
+
+  test("returns undefined for a non-Postgres error", () => {
+    expect(mapPgErrorToHttp(new Error("boom"))).toBeUndefined();
+    expect(mapPgErrorToHttp("nope")).toBeUndefined();
+    expect(mapPgErrorToHttp(undefined)).toBeUndefined();
+  });
+
+  test("passes an already-mapped ORPCError through untouched (no double-map)", () => {
+    const original = new ORPCError("CONFLICT", { message: "dup" });
+    expect(mapPgErrorToHttp(original)).toBeUndefined();
+  });
+
+  test("does not leak the raw driver message to the client", () => {
+    const mapped = mapPgErrorToHttp({
+      code: "22001",
+      message: 'value too long for column "secret_token"',
+    });
+    expect(mapped?.message).not.toContain("secret_token");
+  });
+});

package/src/plugin-manager/pg-http-errors.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { ORPCError } from "@orpc/server";
+
+/**
+ * Postgres SQLSTATE codes for the error classes a *client* can trigger with bad
+ * input. These must surface as 4xx, not 500 - a malformed uuid, an out-of-range
+ * integer, an over-long string, or a constraint violation is the caller's
+ * mistake, not an internal server error.
+ *
+ * Without this mapping a `where id = $1` with `$1 = "not-a-uuid"` reaches the
+ * driver and throws `22P02`, which oRPC reports as a 500 - making routine
+ * fuzzing/probing look like the server is broken and burying genuine 500s.
+ *
+ * @see https://www.postgresql.org/docs/current/errcodes-appendix.html
+ */
+const PG_CLIENT_ERROR_CODES: Record<string, { code: "BAD_REQUEST" | "CONFLICT"; message: string }> = {
+  // Class 22 — data exception (the caller sent a value the type can't hold).
+  "22P02": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a value was malformed (e.g. not a valid id).",
+  },
+  "22003": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a numeric value is out of the allowed range.",
+  },
+  "22001": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a text value exceeds the allowed length.",
+  },
+  "22007": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a date/time value is malformed.",
+  },
+  // Class 23 — integrity-constraint violation.
+  "23502": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a required value is missing.",
+  },
+  "23503": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a referenced record does not exist.",
+  },
+  "23505": {
+    code: "CONFLICT",
+    message: "That record already exists.",
+  },
+  "23514": {
+    code: "BAD_REQUEST",
+    message: "Invalid input: a value failed a validation constraint.",
+  },
+};
+
+// A Postgres driver error carries a SQLSTATE string in `code`. Drizzle may
+// rethrow it wrapped, exposing the original on `cause`, so we check both shapes
+// (mirrors the catalog-backend `pg-errors` matcher).
+const pgErrorSchema = z.object({ code: z.string() });
+const wrappedPgErrorSchema = z.object({ cause: pgErrorSchema });
+
+function extractSqlState(error: unknown): string | undefined {
+  const direct = pgErrorSchema.safeParse(error);
+  if (direct.success) return direct.data.code;
+  const wrapped = wrappedPgErrorSchema.safeParse(error);
+  if (wrapped.success) return wrapped.data.cause.code;
+  return undefined;
+}
+
+/**
+ * Maps a caught Postgres driver error to an `ORPCError` with the right 4xx
+ * status when the SQLSTATE indicates a client-caused fault. Returns `undefined`
+ * for anything else (genuine 500s, application errors), so callers fall through
+ * to their existing error-logging + rethrow path.
+ *
+ * The original error is preserved as `cause` for diagnostics; the client-facing
+ * message is deliberately generic so we never leak column/constraint names.
+ */
+export function mapPgErrorToHttp(error: unknown): ORPCError<string, unknown> | undefined {
+  // An already-mapped oRPC error (e.g. a handler's own CONFLICT/NOT_FOUND) must
+  // pass through untouched.
+  if (error instanceof ORPCError) return undefined;
+  const sqlState = extractSqlState(error);
+  if (!sqlState) return undefined;
+  const mapping = PG_CLIENT_ERROR_CODES[sqlState];
+  if (!mapping) return undefined;
+  return new ORPCError(mapping.code, { message: mapping.message, cause: error });
+}

package/src/plugin-manager/plugin-loader.getservice.test.ts

@@ -63,6 +63,44 @@ function captureEnv(deps: PluginLoaderDeps): BackendPluginRegistry {
   return captured;
 }
 
+describe("registerPlugin pluginPath threading (migrations)", () => {
+  // Regression guard (#251): a manually-loaded plugin (e.g. the dev server's
+  // plugin-under-dev) must carry its on-disk path through to `pendingInits`,
+  // because the loader builds the Drizzle migrations folder as
+  // `<pluginPath>/drizzle`. Manual plugins historically got `pluginPath: ""`,
+  // so their migrations were silently skipped and a scaffolded plugin booted
+  // with no tables. The dev path now supplies the plugin's dir via
+  // `manualPluginPaths`; this asserts the value reaches `pendingInits`.
+  function registerWithPath(pluginPath: string): PendingInit[] {
+    const pendingInits: PendingInit[] = [];
+    const plugin = createBackendPlugin({
+      metadata: { pluginId: "widget" },
+      register: (env) => {
+        env.registerInit({ deps: {}, init: async () => {} });
+      },
+    });
+    registerPlugin({
+      backendPlugin: plugin,
+      pluginPath,
+      pendingInits,
+      providedBy: new Map<string, string>(),
+      deps: makeDeps(new ServiceRegistry()),
+    });
+    return pendingInits;
+  }
+
+  it("threads a supplied pluginPath into the pending init (so migrations run)", () => {
+    const pending = registerWithPath("/repo/packages/widget-backend");
+    expect(pending).toHaveLength(1);
+    expect(pending[0]?.pluginPath).toBe("/repo/packages/widget-backend");
+  });
+
+  it("keeps an empty pluginPath when none is supplied (migrations skipped)", () => {
+    const pending = registerWithPath("");
+    expect(pending[0]?.pluginPath).toBe("");
+  });
+});
+
 describe("plugin env.getService", () => {
   it("resolves a service registered by another plugin through the real ServiceRegistry", async () => {
     const registry = new ServiceRegistry();

package/src/plugin-manager/plugin-loader.skip-naming.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach, afterEach, spyOn } from "bun:test";
+import { createBackendPlugin } from "@checkstack/backend-api";
+import type { AccessRule, PluginMetadata } from "@checkstack/common";
+import { ServiceRegistry } from "../services/service-registry";
+import { createExtensionPointManager } from "./extension-points";
+import { registerPlugin, type PluginLoaderDeps } from "./plugin-loader";
+import type { PendingInit } from "./types";
+import type { AnyContractRouter } from "@orpc/contract";
+import { rootLogger } from "../logger";
+
+/**
+ * Regression coverage for the "no register() export" skip diagnostic.
+ *
+ * A package declared `checkstack.type: "backend"` is inserted into the
+ * `plugins` table and loaded in Phase 1 via `pluginModule.default`. If that
+ * default export is missing (a host-consumed library mis-typed as a backend
+ * plugin, e.g. `@checkstack/signal-backend` before it was reclassified to
+ * `tooling`), `backendPlugin` is `undefined` and the loader skips it.
+ *
+ * Previously the skip warning rendered the opaque literal "unknown" because
+ * the only identifier source was `backendPlugin?.metadata?.pluginId`. These
+ * tests assert the package name / path from the database row is used as a
+ * fallback so the offending package is always identifiable, and that a valid
+ * plugin loads without any warning.
+ */
+
+function makeDeps(registry: ServiceRegistry): PluginLoaderDeps {
+  return {
+    registry,
+    pluginRpcRouters: new Map<string, unknown>(),
+    pluginHttpHandlers: new Map<string, (req: Request) => Promise<Response>>(),
+    extensionPointManager: createExtensionPointManager(),
+    registeredAccessRules: [] as (AccessRule & { pluginId: string })[],
+    getAllAccessRules: () => [],
+    db: {} as PluginLoaderDeps["db"],
+    pluginMetadataRegistry: new Map<string, PluginMetadata>(),
+    cleanupHandlers: new Map<string, Array<() => Promise<void>>>(),
+    pluginContractRegistry: new Map<string, AnyContractRouter>(),
+  };
+}
+
+// A module whose `default` export is missing models a package mis-typed as a
+// backend plugin. `registerPlugin` accepts `BackendPlugin | undefined` precisely
+// because `pluginModule.default` can be `undefined` at runtime, so no cast is
+// needed to exercise the guard.
+const missingDefaultExport = undefined;
+
+describe("registerPlugin skip diagnostic", () => {
+  let warnSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    warnSpy = spyOn(rootLogger, "warn").mockImplementation(() => rootLogger);
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  it("names the package by its database-row name (never 'unknown') when the default export is missing", () => {
+    const pendingInits: PendingInit[] = [];
+
+    registerPlugin({
+      backendPlugin: missingDefaultExport,
+      pluginPath: "/workspace/core/signal-backend",
+      pluginName: "@checkstack/signal-backend",
+      pendingInits,
+      providedBy: new Map<string, string>(),
+      deps: makeDeps(new ServiceRegistry()),
+    });
+
+    expect(pendingInits).toHaveLength(0);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const message = String(warnSpy.mock.calls[0]?.[0]);
+    expect(message).toContain("@checkstack/signal-backend");
+    expect(message).not.toContain("unknown");
+  });
+
+  it("falls back to the plugin path when no name is available", () => {
+    const pendingInits: PendingInit[] = [];
+
+    registerPlugin({
+      backendPlugin: missingDefaultExport,
+      pluginPath: "/workspace/core/mystery-backend",
+      pendingInits,
+      providedBy: new Map<string, string>(),
+      deps: makeDeps(new ServiceRegistry()),
+    });
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const message = String(warnSpy.mock.calls[0]?.[0]);
+    expect(message).toContain("/workspace/core/mystery-backend");
+    expect(message).not.toContain("unknown");
+  });
+
+  it("does not warn when a valid plugin with register() is registered", () => {
+    const pendingInits: PendingInit[] = [];
+    const plugin = createBackendPlugin({
+      metadata: { pluginId: "valid-plugin" },
+      register: () => {
+        // no-op: a valid plugin must not trigger the skip diagnostic.
+      },
+    });
+
+    registerPlugin({
+      backendPlugin: plugin,
+      pluginPath: "/workspace/core/valid-backend",
+      pluginName: "@checkstack/valid-backend",
+      pendingInits,
+      providedBy: new Map<string, string>(),
+      deps: makeDeps(new ServiceRegistry()),
+    });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});

package/src/plugin-manager/plugin-loader.ts

@@ -71,27 +71,72 @@ export interface PluginLoaderDeps {
   onApiRouteRegistered?: () => void;
 }
 
+/**
+ * Resolves a human-identifiable name for a plugin module so diagnostics never
+ * render the opaque literal "unknown". Prefers the declared `pluginId`, then
+ * the package name from the database/discovery row, then the on-disk path.
+ */
+function resolvePluginIdentifier({
+  backendPlugin,
+  pluginName,
+  pluginPath,
+}: {
+  backendPlugin: BackendPlugin | undefined;
+  pluginName?: string;
+  pluginPath: string;
+}): string {
+  const pluginId = backendPlugin?.metadata?.pluginId;
+  if (pluginId) {
+    return pluginId;
+  }
+  if (pluginName) {
+    return pluginName;
+  }
+  if (pluginPath) {
+    return pluginPath;
+  }
+  return "unknown";
+}
+
 /**
  * Registers a single plugin - called during Phase 1.
  */
 export function registerPlugin({
   backendPlugin,
   pluginPath,
+  pluginName,
   pendingInits,
   providedBy,
   deps,
 }: {
-  backendPlugin: BackendPlugin;
+  /**
+   * The plugin module's default export. Typed as possibly `undefined` because
+   * a package mis-typed as `checkstack.type: "backend"` may have no default
+   * export at all (`pluginModule.default` is `undefined` at runtime); the guard
+   * below handles that case explicitly.
+   */
+  backendPlugin: BackendPlugin | undefined;
   pluginPath: string;
+  /**
+   * Package name of the plugin from its database/discovery row. Used so the
+   * "no register() export" diagnostic can name the offending package even when
+   * its module has no default export carrying `metadata.pluginId`.
+   */
+  pluginName?: string;
   pendingInits: PendingInit[];
   providedBy: Map<string, string>;
   deps: PluginLoaderDeps;
 }) {
   if (!backendPlugin || typeof backendPlugin.register !== "function") {
+    const identifier = resolvePluginIdentifier({
+      backendPlugin,
+      pluginName,
+      pluginPath,
+    });
     rootLogger.warn(
-      `Plugin ${
-        backendPlugin?.metadata?.pluginId || "unknown"
-      } is not using new API. Skipping.`,
+      `Plugin '${identifier}' has no backend register() export and was skipped. ` +
+        `If this package is a host-consumed library rather than a runtime plugin, ` +
+        `set its package.json "checkstack.type" to "tooling" so it is not discovered as a backend plugin.`,
     );
     return;
   }
@@ -201,11 +246,21 @@ export function registerPlugin({
 export async function loadPlugins({
   rootRouter,
   manualPlugins = [],
+  manualPluginPaths,
   skipDiscovery = false,
   deps,
 }: {
   rootRouter: Hono;
   manualPlugins?: BackendPlugin[];
+  /**
+   * Optional `pluginId -> on-disk plugin dir` map for manually-loaded
+   * plugins. When a manual plugin has an entry here, its Drizzle migrations
+   * (in `<dir>/drizzle`) are applied just like a discovered plugin's. The
+   * dev server passes the plugin's `CHECKSTACK_DEV_PLUGIN_PATH` here so a
+   * scaffolded plugin's tables exist on first boot; without it, manual
+   * plugins keep their historical `pluginPath: ""` (migrations skipped).
+   */
+  manualPluginPaths?: Map<string, string>;
   /** When true, skip filesystem plugin discovery (for testing) */
   skipDiscovery?: boolean;
   deps: PluginLoaderDeps;
@@ -286,6 +341,7 @@ export async function loadPlugins({
       registerPlugin({
         backendPlugin,
         pluginPath: plugin.path,
+        pluginName: plugin.name,
         pendingInits,
         providedBy,
         deps,
@@ -301,7 +357,10 @@ export async function loadPlugins({
   for (const backendPlugin of manualPlugins) {
     registerPlugin({
       backendPlugin,
-      pluginPath: "",
+      // Use the supplied dir (dev server passes the plugin's path so its
+      // migrations run); fall back to "" for manual plugins without one.
+      pluginPath:
+        manualPluginPaths?.get(backendPlugin.metadata.pluginId) ?? "",
       pendingInits,
       providedBy,
       deps,

package/src/plugin-manager.ts

@@ -197,11 +197,15 @@ export class PluginManager {
   async loadPlugins(
     rootRouter: Hono,
     manualPlugins: BackendPlugin[] = [],
-    options: { skipDiscovery?: boolean } = {}
+    options: {
+      skipDiscovery?: boolean;
+      manualPluginPaths?: Map<string, string>;
+    } = {}
   ) {
     await loadPluginsImpl({
       rootRouter,
       manualPlugins,
+      manualPluginPaths: options.manualPluginPaths,
       skipDiscovery: options.skipDiscovery,
       deps: {
         registry: this.registry,

package/src/services/collector-registry.ts

@@ -4,6 +4,7 @@ import type {
   TransportClient,
   RegisteredCollector,
 } from "@checkstack/backend-api";
+import { assertNoSecretTemplatableConflict } from "@checkstack/backend-api";
 import { rootLogger } from "../logger";
 
 /**
@@ -19,6 +20,14 @@ export class CoreCollectorRegistry {
   ): void {
     // Use fully-qualified ID: ownerPluginId.collectorId
     const qualifiedId = `${ownerPlugin.pluginId}.${collector.id}`;
+    // Load-time guard: a config field must not be both a secret and
+    // templatable (they resolve in separate ordered passes). Fail fast on a
+    // misconfigured collector rather than silently skipping one pass at run
+    // time.
+    assertNoSecretTemplatableConflict({
+      schema: collector.config.schema,
+      schemaName: `collector:${qualifiedId}`,
+    });
     if (this.collectors.has(qualifiedId)) {
       rootLogger.warn(
         `CollectorStrategy '${qualifiedId}' is already registered. Overwriting.`

package/src/services/dev-auth.test.ts

@@ -1,9 +1,26 @@
-import { describe, it, expect } from "bun:test";
-import { createDevAuthService } from "./dev-auth";
+import { describe, it, expect, mock } from "bun:test";
+
+// dev-auth signs/verifies S2S tokens via jwtService, which is backed by the
+// DB-bound KeyStore. Mock it so these stay pure unit tests (no DB): tokens are
+// modeled as `svc:<pluginId>` strings so we can assert the wiring without real
+// crypto.
+mock.module("./jwt", () => ({
+  jwtService: {
+    sign: async (payload: Record<string, unknown>) =>
+      `svc:${String(payload.service)}`,
+    verify: async (token: string) =>
+      token.startsWith("svc:") ? { service: token.slice(4) } : undefined,
+  },
+}));
+
+const { createDevAuthService } = await import("./dev-auth");
 
 describe("createDevAuthService", () => {
   it("authenticate() returns a stable RealUser identity", async () => {
-    const svc = createDevAuthService({ getAllAccessRules: () => [] });
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [],
+      pluginId: "dev",
+    });
     const user = await svc.authenticate(new Request("http://x"));
     expect(user).toBeDefined();
     if (!user || user.type !== "user") {
@@ -22,6 +39,7 @@ describe("createDevAuthService", () => {
         { id: "catalog.system.read" },
         { id: "catalog.system.manage" },
       ],
+      pluginId: "dev",
     });
     const user = await svc.authenticate(new Request("http://x"));
     if (!user || user.type !== "user") throw new Error("expected RealUser");
@@ -33,7 +51,10 @@ describe("createDevAuthService", () => {
 
   it("re-reads access rules on each authenticate (rules registered later still apply)", async () => {
     const rules = [{ id: "first.rule" }];
-    const svc = createDevAuthService({ getAllAccessRules: () => rules });
+    const svc = createDevAuthService({
+      getAllAccessRules: () => rules,
+      pluginId: "dev",
+    });
 
     const before = await svc.authenticate(new Request("http://x"));
     if (!before || before.type !== "user") throw new Error("expected RealUser");
@@ -45,20 +66,58 @@ describe("createDevAuthService", () => {
     expect(after.accessRules).toEqual(["first.rule", "second.rule"]);
   });
 
+  it("authenticate() honors real SERVICE tokens (S2S calls stay services, not the dev user)", async () => {
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [],
+      pluginId: "dev",
+    });
+    // A backend-to-backend caller presents a token minted as `{ service: <id> }`.
+    const principal = await svc.authenticate(
+      new Request("http://x", {
+        headers: { Authorization: "Bearer svc:incident" },
+      }),
+    );
+    expect(principal).toEqual({ type: "service", pluginId: "incident" });
+  });
+
+  it("authenticate() falls back to the dev user for non-service tokens", async () => {
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [{ id: "x" }],
+      pluginId: "dev",
+    });
+    const principal = await svc.authenticate(
+      new Request("http://x", {
+        headers: { Authorization: "Bearer not-a-real-token" },
+      }),
+    );
+    if (!principal || principal.type !== "user") {
+      throw new Error("expected RealUser");
+    }
+    expect(principal.id).toBe("dev-user");
+  });
+
   it("getAnonymousAccessRules returns an empty list (anonymous gets nothing in dev)", async () => {
     const svc = createDevAuthService({
       getAllAccessRules: () => [{ id: "x" }, { id: "y" }],
+      pluginId: "dev",
     });
     expect(await svc.getAnonymousAccessRules()).toEqual([]);
   });
 
-  it("getCredentials returns an empty headers object", async () => {
-    const svc = createDevAuthService({ getAllAccessRules: () => [] });
-    expect(await svc.getCredentials()).toEqual({ headers: {} });
+  it("getCredentials mints a service token scoped to this plugin", async () => {
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [],
+      pluginId: "notification",
+    });
+    const creds = await svc.getCredentials();
+    expect(creds.headers.Authorization).toBe("Bearer svc:notification");
   });
 
   it("checkResourceTeamAccess always grants", async () => {
-    const svc = createDevAuthService({ getAllAccessRules: () => [] });
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [],
+      pluginId: "dev",
+    });
     expect(
       await svc.checkResourceTeamAccess({
         userId: "x",
@@ -72,7 +131,10 @@ describe("createDevAuthService", () => {
   });
 
   it("getAccessibleResourceIds returns the input list unfiltered", async () => {
-    const svc = createDevAuthService({ getAllAccessRules: () => [] });
+    const svc = createDevAuthService({
+      getAllAccessRules: () => [],
+      pluginId: "dev",
+    });
     expect(
       await svc.getAccessibleResourceIds({
         userId: "x",

package/src/services/dev-auth.ts

@@ -1,4 +1,5 @@
 import type { AuthService, RealUser } from "@checkstack/backend-api";
+import { jwtService } from "./jwt";
 
 /**
  * Dev-only auth service.
@@ -8,17 +9,37 @@ import type { AuthService, RealUser } from "@checkstack/backend-api";
  * synthetic user that has every registered access rule, so any procedure
  * (regardless of the access guards on it) authorizes.
  *
+ * IMPORTANT: real SERVICE tokens still resolve to a `ServiceUser`. dev-auth
+ * REPLACES the core auth factory, so without this passthrough every
+ * backend-to-backend call (and the service-only endpoints they hit, e.g.
+ * `notification.registerSubscriptionSpec` from a plugin's `afterPluginsReady`)
+ * would be authenticated as the synthetic USER and 403 with "for services
+ * only" - which fatally breaks app boot. Only non-service requests get the
+ * synthetic dev admin.
+ *
  * NEVER register this in production. The runtime gates installation
  * behind a `CHECKSTACK_DEV_AUTH=true` env var that we set explicitly in
  * the dev server entry point.
  *
  * The user identity is stable (`dev-user`) so plugin code that derives
  * UI / data from `user.id` behaves consistently across reloads.
+ *
+ * Note: app-principal tokens (automation `runAs`) are NOT specially handled
+ * here - in dev they fall through to the dev admin. That's a dev convenience;
+ * the bounded-principal enforcement is covered by unit/integration tests.
  */
 export function createDevAuthService({
   getAllAccessRules,
+  pluginId,
 }: {
   getAllAccessRules: () => Array<{ id: string }>;
+  /**
+   * The plugin this auth instance is scoped to (from the service-factory
+   * metadata). Used to mint S2S credentials as `{ service: pluginId }`, so
+   * service-only endpoints that check the caller's plugin (e.g. subscription
+   * spec ownership) accept the call - exactly like the production auth factory.
+   */
+  pluginId: string;
 }): AuthService {
   const devUser: RealUser = {
     type: "user",
@@ -31,15 +52,31 @@ export function createDevAuthService({
   };
 
   return {
-    async authenticate(_request) {
-      // Always grant every access rule the platform currently knows about.
-      // We resolve this lazily so rules registered by plugins after auth
-      // construction (the normal flow) still apply.
+    async authenticate(request) {
+      // Honor real service tokens so backend-to-backend calls (and the
+      // service-only endpoints they hit during boot) keep working.
+      const token = request.headers.get("Authorization")?.replace("Bearer ", "");
+      if (token) {
+        const payload = await jwtService.verify(token);
+        if (payload && payload.service) {
+          return { type: "service" as const, pluginId: payload.service as string };
+        }
+      }
+      // Otherwise authenticate as the synthetic dev admin. Grant every access
+      // rule the platform currently knows about, resolved lazily so rules
+      // registered by plugins after auth construction still apply.
       devUser.accessRules = getAllAccessRules().map((r) => r.id);
       return devUser;
     },
     async getCredentials() {
-      return { headers: {} };
+      // Mint a real service token (as THIS plugin) so backend-to-backend calls
+      // authenticate as a SERVICE and pass service-only endpoints - including
+      // those that check the caller's plugin id (e.g. subscription-spec
+      // ownership) - matching production. Without this, S2S calls would carry
+      // no auth, be treated as the synthetic user, and 403 on service-only
+      // procedures (breaking boot).
+      const token = await jwtService.sign({ service: pluginId }, "5m");
+      return { headers: { Authorization: `Bearer ${token}` } };
     },
     async getAnonymousAccessRules() {
       // Anonymous users get nothing; the dev user is the only authenticated