@checkstack/backend-api 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @checkstack/backend-api
 
+## 0.5.0
+
+### Minor Changes
+
+- 66a3963: Add `SafeDatabase` type to prevent Drizzle relational query API usage at compile-time
+
+  - Added `SafeDatabase<S>` type that omits the `query` field from Drizzle's `NodePgDatabase`
+  - Updated `DatabaseDeps` to use `SafeDatabase` for all plugin database injection
+  - Updated `RpcContext.db` and `coreServices.database` to use the safe type
+  - Updated test utilities to use `SafeDatabase`
+
+  This change prevents accidental usage of the relational query API (`db.query`) which is blocked at runtime by the scoped database proxy.
+
+### Patch Changes
+
+- Updated dependencies [2c0822d]
+  - @checkstack/queue-api@0.2.0
+
+## 0.4.1
+
+### Patch Changes
+
+- 8a87cd4: Fixed anonymous user access to public endpoints with instance-level access rules
+
+  The RPC middleware now correctly checks if anonymous users have global access via the anonymous role before denying access to single-resource public endpoints. Also added support for contract-level `instanceAccess` override allowing bulk endpoints to share the same access rule as single endpoints.
+
+- Updated dependencies [8a87cd4]
+  - @checkstack/common@0.5.0
+  - @checkstack/queue-api@0.1.3
+  - @checkstack/signal-common@0.1.3
+
 ## 0.4.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend-api",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "./src/index.ts",
   "scripts": {

package/src/core-services.ts

@@ -5,7 +5,7 @@ import type { CollectorRegistry } from "./collector-registry";
 import type { QueuePluginRegistry, QueueManager } from "@checkstack/queue-api";
 import type { ConfigService } from "./config-service";
 import type { SignalService } from "@checkstack/signal-common";
-import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { SafeDatabase } from "./plugin-system";
 import {
   Logger,
   Fetch,
@@ -18,26 +18,26 @@ import type { EventBus } from "./event-bus-types";
 export * from "./types";
 
 export const authenticationStrategyServiceRef = createServiceRef<unknown>(
-  "internal.authenticationStrategy"
+  "internal.authenticationStrategy",
 );
 
 export const coreServices = {
   database:
-    createServiceRef<NodePgDatabase<Record<string, unknown>>>("core.database"),
+    createServiceRef<SafeDatabase<Record<string, unknown>>>("core.database"),
   logger: createServiceRef<Logger>("core.logger"),
   fetch: createServiceRef<Fetch>("core.fetch"),
   auth: createServiceRef<AuthService>("core.auth"),
   healthCheckRegistry: createServiceRef<HealthCheckRegistry>(
-    "core.healthCheckRegistry"
+    "core.healthCheckRegistry",
   ),
   collectorRegistry: createServiceRef<CollectorRegistry>(
-    "core.collectorRegistry"
+    "core.collectorRegistry",
   ),
   pluginInstaller: createServiceRef<PluginInstaller>("core.pluginInstaller"),
   rpc: createServiceRef<RpcService>("core.rpc"),
   rpcClient: createServiceRef<RpcClient>("core.rpcClient"),
   queuePluginRegistry: createServiceRef<QueuePluginRegistry>(
-    "core.queuePluginRegistry"
+    "core.queuePluginRegistry",
   ),
   queueManager: createServiceRef<QueueManager>("core.queueManager"),
   config: createServiceRef<ConfigService>("core.config"),

package/src/plugin-system.ts

@@ -14,12 +14,24 @@ export type ResolvedDeps<T extends Deps> = {
   [K in keyof T]: T[K]["T"];
 };
 
+/**
+ * Safe database type that omits Drizzle's relational query API.
+ * The relational query API bypasses schema isolation and is blocked
+ * at runtime by the scoped database proxy. This type prevents
+ * accidental usage at compile-time.
+ */
+export type SafeDatabase<S extends Record<string, unknown>> = Omit<
+  NodePgDatabase<S>,
+  "query"
+>;
+
 /**
  * Helper type for database dependency injection.
  * If schema S is provided, adds typed database; otherwise adds nothing.
+ * Uses SafeDatabase to prevent relational query API usage.
  */
 export type DatabaseDeps<S extends Record<string, unknown> | undefined> =
-  S extends undefined ? unknown : { database: NodePgDatabase<NonNullable<S>> };
+  S extends undefined ? unknown : { database: SafeDatabase<NonNullable<S>> };
 
 export type PluginContext = {
   pluginId: string;
@@ -37,7 +49,7 @@ export type AfterPluginsReadyContext = {
   onHook: <T>(
     hook: Hook<T>,
     listener: (payload: T) => Promise<void>,
-    options?: HookSubscribeOptions
+    options?: HookSubscribeOptions,
   ) => HookUnsubscribe;
   /**
    * Emit a hook event. Only available in afterPluginsReady phase.
@@ -48,7 +60,7 @@ export type AfterPluginsReadyContext = {
 export type BackendPluginRegistry = {
   registerInit: <
     D extends Deps,
-    S extends Record<string, unknown> | undefined = undefined
+    S extends Record<string, unknown> | undefined = undefined,
   >(args: {
     deps: D;
     schema?: S;
@@ -64,7 +76,7 @@ export type BackendPluginRegistry = {
      * Receives the same deps as init, plus onHook and emitHook.
      */
     afterPluginsReady?: (
-      deps: ResolvedDeps<D> & DatabaseDeps<S> & AfterPluginsReadyContext
+      deps: ResolvedDeps<D> & DatabaseDeps<S> & AfterPluginsReadyContext,
     ) => Promise<void>;
   }) => void;
   registerService: <S>(ref: ServiceRef<S>, impl: S) => void;
@@ -80,7 +92,7 @@ export type BackendPluginRegistry = {
    */
   registerRouter: <C extends AnyContractRouter>(
     router: Router<C, RpcContext>,
-    contract: C
+    contract: C,
   ) => void;
   /**
    * Register cleanup logic to be called when the plugin is deregistered.

package/src/rpc.test.ts

@@ -35,14 +35,17 @@ const testContracts = {
     access: [
       accessPair(
         "system",
-        { read: "View systems", manage: "Manage systems" },
-        { listKey: "systems", readIsPublic: true }
+        {
+          read: { description: "View systems", isPublic: true },
+          manage: { description: "Manage systems" },
+        },
+        { listKey: "systems" },
       ).read,
     ],
   }).output(
     z.object({
       systems: z.array(z.object({ id: z.string(), name: z.string() })),
-    })
+    }),
   ),
 
   // Authenticated endpoint
@@ -73,8 +76,11 @@ const testContracts = {
     access: [
       accessPair(
         "system",
-        { read: "View systems", manage: "Manage systems" },
-        { idParam: "systemId", readIsPublic: true }
+        {
+          read: { description: "View systems", isPublic: true },
+          manage: { description: "Manage systems" },
+        },
+        { idParam: "systemId" },
       ).read,
     ],
   })
@@ -96,7 +102,7 @@ const testContracts = {
     .output(
       z.object({
         statuses: z.record(z.string(), z.object({ status: z.string() })),
-      })
+      }),
     ),
 
   // Mutation endpoint
@@ -107,6 +113,33 @@ const testContracts = {
   })
     .input(z.object({ name: z.string() }))
     .output(z.object({ id: z.string() })),
+
+  // Bulk record endpoint using instanceAccess OVERRIDE at contract level
+  // This tests the pattern where bulk endpoints share the same access rule
+  // as single endpoints but use recordKey instead of idParam
+  bulkRecordWithOverride: proc({
+    userType: "public",
+    operationType: "query",
+    // Uses same access rule as singleResourceEndpoint (has idParam)
+    // but overrides instanceAccess to use recordKey
+    access: [
+      accessPair(
+        "system",
+        {
+          read: { description: "View systems", isPublic: true },
+          manage: { description: "Manage systems" },
+        },
+        { idParam: "systemId" },
+      ).read,
+    ],
+    instanceAccess: { recordKey: "statuses" },
+  })
+    .input(z.object({ systemIds: z.array(z.string()) }))
+    .output(
+      z.object({
+        statuses: z.record(z.string(), z.object({ status: z.string() })),
+      }),
+    ),
 };
 
 // =============================================================================
@@ -121,7 +154,7 @@ const testImplementations = {
   publicGlobalEndpoint: implement(testContracts.publicGlobalEndpoint).handler(
     () => ({
       message: "Hello from public global",
-    })
+    }),
   ),
 
   publicListEndpoint: implement(testContracts.publicListEndpoint).handler(
@@ -131,13 +164,13 @@ const testImplementations = {
         { id: "system-2", name: "System 2" },
         { id: "system-3", name: "System 3" },
       ],
-    })
+    }),
   ),
 
   authenticatedEndpoint: implement(testContracts.authenticatedEndpoint).handler(
     () => ({
       message: "Hello from authenticated",
-    })
+    }),
   ),
 
   userOnlyEndpoint: implement(testContracts.userOnlyEndpoint).handler(() => ({
@@ -147,11 +180,11 @@ const testImplementations = {
   serviceOnlyEndpoint: implement(testContracts.serviceOnlyEndpoint).handler(
     () => ({
       message: "Hello from service",
-    })
+    }),
   ),
 
   singleResourceEndpoint: implement(
-    testContracts.singleResourceEndpoint
+    testContracts.singleResourceEndpoint,
   ).handler(({ input }) => ({
     system: { id: input.systemId },
   })),
@@ -159,14 +192,22 @@ const testImplementations = {
   recordEndpoint: implement(testContracts.recordEndpoint).handler(
     ({ input }) => ({
       statuses: Object.fromEntries(
-        input.systemIds.map((id) => [id, { status: "ok" }])
+        input.systemIds.map((id) => [id, { status: "ok" }]),
       ),
-    })
+    }),
   ),
 
   mutationEndpoint: implement(testContracts.mutationEndpoint).handler(() => ({
     id: "new-id",
   })),
+
+  bulkRecordWithOverride: implement(
+    testContracts.bulkRecordWithOverride,
+  ).handler(({ input }) => ({
+    statuses: Object.fromEntries(
+      input.systemIds.map((id) => [id, { status: "ok" }]),
+    ),
+  })),
 };
 
 // =============================================================================
@@ -229,7 +270,7 @@ describe("autoAuthMiddleware", () => {
         .handler(() => ({ message: "success" }));
 
       expect(
-        call(procedure, undefined, { context: contextWithNoAccess })
+        call(procedure, undefined, { context: contextWithNoAccess }),
       ).rejects.toThrow();
     });
 
@@ -283,7 +324,7 @@ describe("autoAuthMiddleware", () => {
       expect(
         call(procedure, undefined, {
           context: { ...mockContext, user: undefined },
-        })
+        }),
       ).rejects.toThrow("Authentication required");
     });
   });
@@ -316,7 +357,7 @@ describe("autoAuthMiddleware", () => {
             ...mockContext,
             user: { type: "service" as const, pluginId: "test-service" },
           },
-        })
+        }),
       ).rejects.toThrow("This endpoint is for users only");
     });
   });
@@ -349,7 +390,7 @@ describe("autoAuthMiddleware", () => {
         .handler(() => ({ message: "success" }));
 
       expect(
-        call(procedure, undefined, { context: mockContext })
+        call(procedure, undefined, { context: mockContext }),
       ).rejects.toThrow("This endpoint is for services only");
     });
   });
@@ -368,7 +409,7 @@ describe("autoAuthMiddleware", () => {
       const result = await call(
         procedure,
         { systemId: "test-123" },
-        { context: mockContext }
+        { context: mockContext },
       );
 
       expect(result).toEqual({ system: { id: "test-123" } });
@@ -394,10 +435,62 @@ describe("autoAuthMiddleware", () => {
         call(
           procedure,
           { systemId: "forbidden-id" },
-          { context: contextWithNoAccess }
-        )
+          { context: contextWithNoAccess },
+        ),
       ).rejects.toThrow();
     });
+
+    // Regression tests for anonymous user access to single resources (issue: 403 for public endpoints)
+    it("should allow anonymous users with global access to single resource endpoints", async () => {
+      // Mock anonymous access rules to include the required access
+      const contextWithAnonymousAccess = {
+        ...mockContext,
+        user: undefined,
+        auth: {
+          ...mockContext.auth,
+          getAnonymousAccessRules: () =>
+            Promise.resolve(["test-plugin.system.read"]),
+        },
+      };
+
+      const procedure = implement(testContracts.singleResourceEndpoint)
+        .$context<RpcContext>()
+        .use(autoAuthMiddleware)
+        .handler(({ input }) => ({ system: { id: input.systemId } }));
+
+      const result = await call(
+        procedure,
+        { systemId: "system-123" },
+        { context: contextWithAnonymousAccess },
+      );
+
+      expect(result).toEqual({ system: { id: "system-123" } });
+    });
+
+    it("should deny anonymous users without global access to single resource endpoints", async () => {
+      // Mock anonymous access rules to NOT include the required access
+      const contextWithoutAnonymousAccess = {
+        ...mockContext,
+        user: undefined,
+        auth: {
+          ...mockContext.auth,
+          getAnonymousAccessRules: () => Promise.resolve([]),
+        },
+      };
+
+      const procedure = implement(testContracts.singleResourceEndpoint)
+        .$context<RpcContext>()
+        .use(autoAuthMiddleware)
+        .handler(({ input }) => ({ system: { id: input.systemId } }));
+
+      expect(
+        call(
+          procedure,
+          { systemId: "system-123" },
+          { context: contextWithoutAnonymousAccess },
+        ),
+      ).rejects.toThrow("Authentication required to access");
+    });
   });
 
   // ---------------------------------------------------------------------------
@@ -433,17 +526,85 @@ describe("autoAuthMiddleware", () => {
         .use(autoAuthMiddleware)
         .handler(({ input }) => ({
           statuses: Object.fromEntries(
-            input.systemIds.map((id) => [id, { status: "ok" }])
+            input.systemIds.map((id) => [id, { status: "ok" }]),
           ),
         }));
 
       const result = await call(
         procedure,
         { systemIds: ["sys-1", "sys-2"] },
-        { context: mockContext }
+        { context: mockContext },
       );
 
       expect(Object.keys(result.statuses)).toHaveLength(2);
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // Contract-level instanceAccess Override
+  // ---------------------------------------------------------------------------
+
+  describe("instanceAccess override at contract level", () => {
+    it("should use contract-level instanceAccess instead of access rule instanceAccess", async () => {
+      // This test verifies that bulk endpoints can share the same access rule
+      // as single endpoints, using instanceAccess override at contract level
+      const contextWithAnonymousAccess = {
+        ...mockContext,
+        user: undefined,
+        auth: {
+          ...mockContext.auth,
+          getAnonymousAccessRules: () =>
+            Promise.resolve(["test-plugin.system.read"]),
+        },
+      };
+
+      const procedure = implement(testContracts.bulkRecordWithOverride)
+        .$context<RpcContext>()
+        .use(autoAuthMiddleware)
+        .handler(({ input }) => ({
+          statuses: Object.fromEntries(
+            input.systemIds.map((id) => [id, { status: "ok" }]),
+          ),
+        }));
+
+      // Should use recordKey filtering (from contract override),
+      // not idParam check (from access rule)
+      const result = await call(
+        procedure,
+        { systemIds: ["sys-1", "sys-2"] },
+        { context: contextWithAnonymousAccess },
+      );
+
+      expect(Object.keys(result.statuses)).toHaveLength(2);
+    });
+
+    it("should deny anonymous users without access on override endpoints", async () => {
+      const contextWithoutAccess = {
+        ...mockContext,
+        user: undefined,
+        auth: {
+          ...mockContext.auth,
+          getAnonymousAccessRules: () => Promise.resolve([]),
+        },
+      };
+
+      const procedure = implement(testContracts.bulkRecordWithOverride)
+        .$context<RpcContext>()
+        .use(autoAuthMiddleware)
+        .handler(({ input }) => ({
+          statuses: Object.fromEntries(
+            input.systemIds.map((id) => [id, { status: "ok" }]),
+          ),
+        }));
+
+      // Without access, should return empty record (filtered out)
+      const result = await call(
+        procedure,
+        { systemIds: ["sys-1", "sys-2"] },
+        { context: contextWithoutAccess },
+      );
+
+      expect(Object.keys(result.statuses)).toHaveLength(0);
+    });
+  });
 });

package/src/rpc.ts

@@ -8,7 +8,7 @@ import {
   qualifyAccessRuleId,
   qualifyResourceType,
 } from "@checkstack/common";
-import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { SafeDatabase } from "./plugin-system";
 import {
   Logger,
   Fetch,
@@ -36,7 +36,7 @@ export interface RpcContext {
    */
   pluginMetadata: PluginMetadata;
 
-  db: NodePgDatabase<Record<string, unknown>>;
+  db: SafeDatabase<Record<string, unknown>>;
   logger: Logger;
   fetch: Fetch;
   auth: AuthService;
@@ -97,14 +97,19 @@ export const autoAuthMiddleware = os.middleware(
     const meta = procedure["~orpc"]?.meta as ProcedureMetadata | undefined;
     const requiredUserType = meta?.userType || "authenticated";
     const accessRules = meta?.access || [];
+    // Contract-level instanceAccess override (used for bulk endpoints)
+    const instanceAccessOverride = meta?.instanceAccess;
 
     // Build qualified access rule IDs for each access rule
+    // If contract has instanceAccess override, apply it to ALL rules
     const qualifiedRules = accessRules.map((rule) => ({
       ...rule,
+      // Use contract-level override if provided, otherwise use rule's config
+      instanceAccess: instanceAccessOverride ?? rule.instanceAccess,
       qualifiedId: qualifyAccessRuleId(context.pluginMetadata, rule),
       qualifiedResourceType: qualifyResourceType(
         context.pluginMetadata.pluginId,
-        rule.resource
+        rule.resource,
       ),
     }));
 
@@ -115,13 +120,13 @@ export const autoAuthMiddleware = os.middleware(
       (r) =>
         r.instanceAccess?.idParam &&
         !r.instanceAccess?.listKey &&
-        !r.instanceAccess?.recordKey
+        !r.instanceAccess?.recordKey,
     );
     const listResourceRules = instanceRules.filter(
-      (r) => r.instanceAccess?.listKey
+      (r) => r.instanceAccess?.listKey,
     );
     const recordResourceRules = instanceRules.filter(
-      (r) => r.instanceAccess?.recordKey
+      (r) => r.instanceAccess?.recordKey,
     );
 
     // 1. Handle anonymous endpoints - no auth required, no access checks
@@ -229,9 +234,20 @@ export const autoAuthMiddleware = os.middleware(
       const resourceId = getNestedValue(input, rule.instanceAccess!.idParam!);
       if (!resourceId) continue;
 
-      // If no user (anonymous on public endpoint), deny access to single resources
-      // (they can't have team grants)
+      // If no user (anonymous on public endpoint), check if anonymous role has global access
       if (!userId || !userType) {
+        const anonymousAccessRules =
+          await context.auth.getAnonymousAccessRules();
+        const hasGlobalAccess =
+          anonymousAccessRules.includes("*") ||
+          anonymousAccessRules.includes(rule.qualifiedId);
+
+        if (hasGlobalAccess) {
+          // Anonymous user has global access - allow access to this resource
+          continue;
+        }
+
+        // No global access and can't have team grants - deny access
         throw new ORPCError("FORBIDDEN", {
           message: `Authentication required to access ${rule.resource}:${resourceId}`,
         });
@@ -276,7 +292,7 @@ export const autoAuthMiddleware = os.middleware(
 
         if (items === undefined) {
           context.logger.error(
-            `resourceAccess: expected "${outputKey}" in response but not found`
+            `resourceAccess: expected "${outputKey}" in response but not found`,
           );
           throw new ORPCError("INTERNAL_SERVER_ERROR", {
             message: "Invalid response shape for filtered endpoint",
@@ -285,7 +301,7 @@ export const autoAuthMiddleware = os.middleware(
 
         if (!Array.isArray(items)) {
           context.logger.error(
-            `resourceAccess: "${outputKey}" must be an array`
+            `resourceAccess: "${outputKey}" must be an array`,
           );
           throw new ORPCError("INTERNAL_SERVER_ERROR", {
             message: "Invalid response shape for filtered endpoint",
@@ -352,7 +368,7 @@ export const autoAuthMiddleware = os.middleware(
 
         if (record === undefined) {
           context.logger.error(
-            `resourceAccess: expected "${outputKey}" in response but not found`
+            `resourceAccess: expected "${outputKey}" in response but not found`,
           );
           throw new ORPCError("INTERNAL_SERVER_ERROR", {
             message: "Invalid response shape for filtered endpoint",
@@ -365,7 +381,7 @@ export const autoAuthMiddleware = os.middleware(
           Array.isArray(record)
         ) {
           context.logger.error(
-            `resourceAccess: "${outputKey}" must be an object (record)`
+            `resourceAccess: "${outputKey}" must be an object (record)`,
           );
           throw new ORPCError("INTERNAL_SERVER_ERROR", {
             message: "Invalid response shape for filtered endpoint",
@@ -419,7 +435,7 @@ export const autoAuthMiddleware = os.middleware(
     }
 
     return result;
-  }
+  },
 );
 
 /**
@@ -562,7 +578,7 @@ export interface RpcService {
    */
   registerRouter<C extends AnyContractRouter>(
     router: Router<C, RpcContext>,
-    contract: C
+    contract: C,
   ): void;
 
   /**
@@ -574,7 +590,7 @@ export interface RpcService {
    */
   registerHttpHandler(
     handler: (req: Request) => Promise<Response>,
-    path?: string
+    path?: string,
   ): void;
 }
 

package/src/test-utils.ts

@@ -1,6 +1,6 @@
 import { mock } from "bun:test";
 import { RpcContext, EmitHookFn } from "./rpc";
-import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { SafeDatabase } from "./plugin-system";
 import { HealthCheckRegistry } from "./health-check";
 import { CollectorRegistry } from "./collector-registry";
 import { QueuePluginRegistry, QueueManager } from "@checkstack/queue-api";
@@ -10,11 +10,11 @@ import { QueuePluginRegistry, QueueManager } from "@checkstack/queue-api";
  * By default provides an authenticated user with wildcard access.
  */
 export function createMockRpcContext(
-  overrides: Partial<RpcContext> = {}
+  overrides: Partial<RpcContext> = {},
 ): RpcContext {
   return {
     pluginMetadata: { pluginId: "test-plugin" },
-    db: mock() as unknown as NodePgDatabase<Record<string, unknown>>,
+    db: mock() as unknown as SafeDatabase<Record<string, unknown>>,
     logger: {
       info: mock(),
       error: mock(),
@@ -39,7 +39,7 @@ export function createMockRpcContext(
       checkResourceTeamAccess: mock().mockResolvedValue({ hasAccess: true }),
       getAccessibleResourceIds: mock().mockImplementation(
         (params: { resourceIds: string[] }) =>
-          Promise.resolve(params.resourceIds)
+          Promise.resolve(params.resourceIds),
       ),
     },
     healthCheckRegistry: {