@checkstack/backend-api 0.1.0 → 0.3.0

package/src/rpc.ts

@@ -3,7 +3,11 @@ import { AnyContractRouter } from "@orpc/contract";
 import { HealthCheckRegistry } from "./health-check";
 import { CollectorRegistry } from "./collector-registry";
 import { QueuePluginRegistry, QueueManager } from "@checkstack/queue-api";
-import { ProcedureMetadata, qualifyPermissionId } from "@checkstack/common";
+import {
+  ProcedureMetadata,
+  qualifyAccessRuleId,
+  qualifyResourceType,
+} from "@checkstack/common";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import {
   Logger,
@@ -73,98 +77,101 @@ export type { ProcedureMetadata } from "@checkstack/common";
  *
  * Automatically enforces based on contract metadata:
  * 1. User type (from meta.userType):
- *    - "anonymous": No authentication required, no permission checks
- *    - "public": Anyone can attempt, but permissions are checked (anonymous role for guests)
+ *    - "anonymous": No authentication required, no access checks
+ *    - "public": Anyone can attempt, access checked based on user type
  *    - "user": Only real users (frontend authenticated)
  *    - "service": Only services (backend-to-backend)
  *    - "authenticated": Either users or services, but must be authenticated (default)
- * 2. Permissions (from meta.permissions, only for real users or public anonymous)
+ * 2. Access rules (from meta.access): unified access rules + resource-level access control
+ *
+ * Access Control Logic:
+ * - Rules WITHOUT instanceAccess: require global access
+ * - Rules WITH instanceAccess: S2S call to auth-backend decides based on:
+ *   - Global access OR team grants (when resource is NOT teamOnly)
+ *   - Team grants only (when resource IS teamOnly)
  *
  * Use this in backend routers: `implement(contract).$context<RpcContext>().use(autoAuthMiddleware)`
  */
 export const autoAuthMiddleware = os.middleware(
-  async ({ next, context, procedure }) => {
+  async ({ next, context, procedure }, input: unknown) => {
     const meta = procedure["~orpc"]?.meta as ProcedureMetadata | undefined;
     const requiredUserType = meta?.userType || "authenticated";
-    const contractPermissions = meta?.permissions || [];
+    const accessRules = meta?.access || [];
 
-    // Prefix contract permissions with pluginId to get fully-qualified permission IDs
-    // Contract defines: "catalog.read" -> Stored in DB as: "catalog.catalog.read"
-    const requiredPermissions = contractPermissions.map((p: string) =>
-      qualifyPermissionId(context.pluginMetadata, { id: p })
-    );
+    // Build qualified access rule IDs for each access rule
+    const qualifiedRules = accessRules.map((rule) => ({
+      ...rule,
+      qualifiedId: qualifyAccessRuleId(context.pluginMetadata, rule),
+      qualifiedResourceType: qualifyResourceType(
+        context.pluginMetadata.pluginId,
+        rule.resource
+      ),
+    }));
 
-    // Helper to wrap next() with error logging
-    const nextWithErrorLogging = async () => {
-      try {
-        return await next({});
-      } catch (error) {
-        // Log the full error before oRPC sanitizes it to a generic 500
-        if (error instanceof ORPCError) {
-          // ORPCError is intentional - log at debug level
-          context.logger.debug("RPC error response:", {
-            code: error.code,
-            message: error.message,
-            data: error.data,
-          });
-        } else {
-          // Unexpected error - log at error level with full stack trace
-          context.logger.error("Unexpected RPC error:", error);
-        }
-        throw error;
-      }
-    };
+    // Separate rules by type
+    const globalOnlyRules = qualifiedRules.filter((r) => !r.instanceAccess);
+    const instanceRules = qualifiedRules.filter((r) => r.instanceAccess);
+    const singleResourceRules = instanceRules.filter(
+      (r) => r.instanceAccess?.idParam
+    );
+    const listResourceRules = instanceRules.filter(
+      (r) => r.instanceAccess?.listKey
+    );
 
-    // 1. Handle anonymous endpoints - no auth required, no permission checks
+    // 1. Handle anonymous endpoints - no auth required, no access checks
     if (requiredUserType === "anonymous") {
-      return nextWithErrorLogging();
+      return next({});
     }
 
-    // 2. Handle public endpoints - anyone can attempt, but permissions are checked
+    // 2. Handle public endpoints - anyone can attempt
     if (requiredUserType === "public") {
-      if (context.user) {
-        // Authenticated user or application - check their permissions
-        if (
-          (context.user.type === "user" ||
-            context.user.type === "application") &&
-          requiredPermissions.length > 0
-        ) {
-          const userPermissions = context.user.permissions || [];
-          const hasPermission = requiredPermissions.some(
-            (p: string) =>
-              userPermissions.includes("*") || userPermissions.includes(p)
-          );
+      const user = context.user;
 
-          if (!hasPermission) {
-            throw new ORPCError("FORBIDDEN", {
-              message: `Missing permission: ${requiredPermissions.join(
-                " or "
-              )}`,
-            });
+      // Check global-only rules based on user status
+      if (globalOnlyRules.length > 0) {
+        if (user && (user.type === "user" || user.type === "application")) {
+          // Authenticated user - check their global accesss
+          const userAccessRules = user.accessRules || [];
+          for (const rule of globalOnlyRules) {
+            const hasAccess =
+              userAccessRules.includes("*") ||
+              userAccessRules.includes(rule.qualifiedId);
+            if (!hasAccess) {
+              throw new ORPCError("FORBIDDEN", {
+                message: `Missing access: ${rule.qualifiedId}`,
+              });
+            }
           }
-        }
-        // Services are trusted with all permissions
-      } else {
-        // Anonymous user - check anonymous role permissions
-        if (requiredPermissions.length > 0) {
-          const anonymousPermissions =
-            await context.auth.getAnonymousPermissions();
-          const hasPermission = requiredPermissions.some((p: string) =>
-            anonymousPermissions.includes(p)
-          );
-
-          if (!hasPermission) {
-            throw new ORPCError("FORBIDDEN", {
-              message: `Anonymous access not permitted for this resource`,
-            });
+        } else if (user && user.type === "service") {
+          // Services are trusted
+        } else {
+          // Anonymous - check anonymous role
+          const anonymousAccessRules =
+            await context.auth.getAnonymousAccessRules();
+          for (const rule of globalOnlyRules) {
+            if (!anonymousAccessRules.includes(rule.qualifiedId)) {
+              throw new ORPCError("FORBIDDEN", {
+                message: `Anonymous access not permitted for this resource`,
+              });
+            }
           }
         }
       }
-      return nextWithErrorLogging();
+
+      // For rules WITH instanceAccess on public endpoints:
+      // - If user is authenticated, check via S2S (step 6)
+      // - If anonymous, they get empty results from list filtering
+      //   (since they have no team grants - S2S will filter everything)
+
+      // If there are no instance rules, we can return early for public endpoints
+      if (instanceRules.length === 0) {
+        return next({});
+      }
+      // Otherwise, fall through to step 6 for instance-level checks
     }
 
     // 3. Enforce authentication for user/service/authenticated types
-    if (!context.user) {
+    if (requiredUserType !== "public" && !context.user) {
       throw new ORPCError("UNAUTHORIZED", {
         message: "Authentication required",
       });
@@ -173,40 +180,248 @@ export const autoAuthMiddleware = os.middleware(
     const user = context.user;
 
     // 4. Enforce user type
-    if (requiredUserType === "user" && user.type !== "user") {
-      throw new ORPCError("FORBIDDEN", {
-        message: "This endpoint is for users only",
-      });
+    if (user) {
+      if (requiredUserType === "user" && user.type !== "user") {
+        throw new ORPCError("FORBIDDEN", {
+          message: "This endpoint is for users only",
+        });
+      }
+      if (requiredUserType === "service" && user.type !== "service") {
+        throw new ORPCError("FORBIDDEN", {
+          message: "This endpoint is for services only",
+        });
+      }
+    }
+
+    // 5. Skip remaining checks for services - they are trusted
+    if (user?.type === "service") {
+      return next({});
+    }
+
+    // 6. Check access rules (for real users, applications, and anonymous on public endpoints)
+    const userId = user?.id;
+    const userType = user?.type as "user" | "application" | undefined;
+    const userAccessRules = user?.accessRules || [];
+
+    // Check global-only rules (for non-public endpoints - public already handled above)
+    if (requiredUserType !== "public") {
+      for (const rule of globalOnlyRules) {
+        const hasAccess =
+          userAccessRules.includes("*") ||
+          userAccessRules.includes(rule.qualifiedId);
+        if (!hasAccess) {
+          throw new ORPCError("FORBIDDEN", {
+            message: `Missing access: ${rule.qualifiedId}`,
+          });
+        }
+      }
     }
-    if (requiredUserType === "service" && user.type !== "service") {
-      throw new ORPCError("FORBIDDEN", {
-        message: "This endpoint is for services only",
+
+    // Pre-check: Single resource access rules
+    // For these, user MUST have either global access OR team grant
+    for (const rule of singleResourceRules) {
+      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 (!userId || !userType) {
+        throw new ORPCError("FORBIDDEN", {
+          message: `Authentication required to access ${rule.resource}:${resourceId}`,
+        });
+      }
+
+      const hasGlobalAccess =
+        userAccessRules.includes("*") ||
+        userAccessRules.includes(rule.qualifiedId);
+
+      const hasAccess = await checkResourceAccessViaS2S({
+        auth: context.auth,
+        userId,
+        userType,
+        resourceType: rule.qualifiedResourceType,
+        resourceId,
+        action: rule.level,
+        hasGlobalAccess,
       });
+
+      if (!hasAccess) {
+        throw new ORPCError("FORBIDDEN", {
+          message: `Access denied to resource ${rule.resource}:${resourceId}`,
+        });
+      }
     }
 
-    // 5. Enforce permissions (for real users and applications)
+    // Execute handler
+    const result = await next({});
+
+    // Post-filter: List endpoints
+    // For these, return only resources user has access to (via global perm OR team grant)
     if (
-      (user.type === "user" || user.type === "application") &&
-      requiredPermissions.length > 0
+      listResourceRules.length > 0 &&
+      result.output &&
+      typeof result.output === "object"
     ) {
-      const userPermissions = user.permissions || [];
-      const hasPermission = requiredPermissions.some(
-        (p: string) =>
-          userPermissions.includes("*") || userPermissions.includes(p)
-      );
+      const mutableOutput = result.output as Record<string, unknown>;
 
-      if (!hasPermission) {
-        throw new ORPCError("FORBIDDEN", {
-          message: `Missing permission: ${requiredPermissions.join(" or ")}`,
+      for (const rule of listResourceRules) {
+        const outputKey = rule.instanceAccess!.listKey!;
+        const items = mutableOutput[outputKey];
+
+        if (items === undefined) {
+          context.logger.error(
+            `resourceAccess: expected "${outputKey}" in response but not found`
+          );
+          throw new ORPCError("INTERNAL_SERVER_ERROR", {
+            message: "Invalid response shape for filtered endpoint",
+          });
+        }
+
+        if (!Array.isArray(items)) {
+          context.logger.error(
+            `resourceAccess: "${outputKey}" must be an array`
+          );
+          throw new ORPCError("INTERNAL_SERVER_ERROR", {
+            message: "Invalid response shape for filtered endpoint",
+          });
+        }
+
+        // If no user (anonymous), check if they have global access via anonymous role
+        if (!userId || !userType) {
+          // Anonymous users can't have team grants, but may have global access
+          const anonymousAccessRules =
+            await context.auth.getAnonymousAccessRules();
+          const hasGlobalAccess =
+            anonymousAccessRules.includes("*") ||
+            anonymousAccessRules.includes(rule.qualifiedId);
+
+          if (hasGlobalAccess) {
+            // Anonymous user has global access - return all items
+            continue;
+          } else {
+            // No global access and can't have team grants - return empty
+            mutableOutput[outputKey] = [];
+            continue;
+          }
+        }
+
+        const resourceIds = items
+          .map((item) => (item as { id?: string }).id)
+          .filter((id): id is string => typeof id === "string");
+
+        const hasGlobalAccess =
+          userAccessRules.includes("*") ||
+          userAccessRules.includes(rule.qualifiedId);
+
+        const accessibleIds = await getAccessibleResourceIdsViaS2S({
+          auth: context.auth,
+          userId,
+          userType,
+          resourceType: rule.qualifiedResourceType,
+          resourceIds,
+          action: rule.level,
+          hasGlobalAccess,
+        });
+
+        const accessibleSet = new Set(accessibleIds);
+        mutableOutput[outputKey] = items.filter((item) => {
+          const id = (item as { id?: string }).id;
+          return id && accessibleSet.has(id);
         });
       }
     }
 
-    // Pass through - services are trusted with all permissions
-    return nextWithErrorLogging();
+    return result;
   }
 );
 
+/**
+ * Extract a nested value from an object using dot notation.
+ * E.g., getNestedValue({ params: { id: "123" } }, "params.id") => "123"
+ */
+function getNestedValue(obj: unknown, path: string): string | undefined {
+  const parts = path.split(".");
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return typeof current === "string" ? current : undefined;
+}
+
+/**
+ * Check resource access via auth service S2S endpoint.
+ */
+async function checkResourceAccessViaS2S({
+  auth,
+  userId,
+  userType,
+  resourceType,
+  resourceId,
+  action,
+  hasGlobalAccess,
+}: {
+  auth: AuthService;
+  userId: string;
+  userType: "user" | "application";
+  resourceType: string;
+  resourceId: string;
+  action: "read" | "manage";
+  hasGlobalAccess: boolean;
+}): Promise<boolean> {
+  try {
+    const result = await auth.checkResourceTeamAccess({
+      userId,
+      userType,
+      resourceType,
+      resourceId,
+      action,
+      hasGlobalAccess,
+    });
+    return result.hasAccess;
+  } catch {
+    // If team access check fails (e.g., service not available), fall back to global access
+    return hasGlobalAccess;
+  }
+}
+
+/**
+ * Get accessible resource IDs via auth service S2S endpoint.
+ */
+async function getAccessibleResourceIdsViaS2S({
+  auth,
+  userId,
+  userType,
+  resourceType,
+  resourceIds,
+  action,
+  hasGlobalAccess,
+}: {
+  auth: AuthService;
+  userId: string;
+  userType: "user" | "application";
+  resourceType: string;
+  resourceIds: string[];
+  action: "read" | "manage";
+  hasGlobalAccess: boolean;
+}): Promise<string[]> {
+  if (resourceIds.length === 0) return [];
+
+  try {
+    return await auth.getAccessibleResourceIds({
+      userId,
+      userType,
+      resourceType,
+      resourceIds,
+      action,
+      hasGlobalAccess,
+    });
+  } catch {
+    // If team access check fails, fall back to global access behavior
+    return hasGlobalAccess ? resourceIds : [];
+  }
+}
+
 // =============================================================================
 // CONTRACT BUILDER
 // =============================================================================
@@ -217,16 +432,16 @@ export const autoAuthMiddleware = os.middleware(
  * All plugin contracts should use this builder. It ensures that:
  * 1. All procedures are authenticated by default
  * 2. User type is enforced based on meta.userType
- * 3. Permissions are enforced based on meta.permissions
+ * 3. Access rules are enforced based on meta.access
  *
  * @example
  * import { baseContractBuilder } from "@checkstack/backend-api";
- * import { permissions } from "./permissions";
+ * import { access } from "./access";
  *
  * const myContract = {
- *   // User-only endpoint with specific permission
+ *   // User-only endpoint with specific access rule
  *   getItems: baseContractBuilder
- *     .meta({ userType: "user", permissions: [permissions.myPluginRead.id] })
+ *     .meta({ userType: "user", accessRules: [access.myPluginRead.id] })
  *     .output(z.array(ItemSchema)),
  *
  *   // Service-only endpoint (backend-to-backend)

package/src/test-utils.ts

@@ -34,7 +34,12 @@ export function createMockRpcContext(
     auth: {
       authenticate: mock(),
       getCredentials: mock().mockResolvedValue({ headers: {} }),
-      getAnonymousPermissions: mock().mockResolvedValue([]),
+      getAnonymousAccessRules: mock().mockResolvedValue([]),
+      checkResourceTeamAccess: mock().mockResolvedValue({ hasAccess: true }),
+      getAccessibleResourceIds: mock().mockImplementation(
+        (params: { resourceIds: string[] }) =>
+          Promise.resolve(params.resourceIds)
+      ),
     },
     healthCheckRegistry: {
       register: mock(),

package/src/types.ts

@@ -22,21 +22,22 @@ export interface Fetch {
 
 /**
  * Real user authenticated via session/token (human users).
- * Has permissions and roles from the RBAC system.
+ * Has access rules and roles from the RBAC system.
  */
 export interface RealUser {
   type: "user";
   id: string;
   email?: string;
   name?: string;
-  permissions?: string[];
+  accessRules?: string[];
   roles?: string[];
+  teamIds?: string[];
   [key: string]: unknown;
 }
 
 /**
  * Service user for backend-to-backend calls.
- * Trusted implicitly - no permissions/roles needed.
+ * Trusted implicitly - no accesss/roles needed.
  */
 export interface ServiceUser {
   type: "service";
@@ -45,14 +46,15 @@ export interface ServiceUser {
 
 /**
  * External application authenticated via API key.
- * Has permissions and roles from the RBAC system like RealUser.
+ * Has access rules and roles from the RBAC system like RealUser.
  */
 export interface ApplicationUser {
   type: "application";
   id: string;
   name: string;
-  permissions?: string[];
+  accessRules?: string[];
   roles?: string[];
+  teamIds?: string[];
 }
 
 /**
@@ -65,11 +67,34 @@ export interface AuthService {
   authenticate(request: Request): Promise<AuthUser | undefined>;
   getCredentials(): Promise<{ headers: Record<string, string> }>;
   /**
-   * Get permissions assigned to the anonymous role.
-   * Used by autoAuthMiddleware to check permissions for unauthenticated
+   * Get access rules assigned to the anonymous role.
+   * Used by autoAuthMiddleware to check accesss for unauthenticated
    * users on "public" userType endpoints.
    */
-  getAnonymousPermissions(): Promise<string[]>;
+  getAnonymousAccessRules(): Promise<string[]>;
+  /**
+   * Check if a user has access to a specific resource via team grants.
+   */
+  checkResourceTeamAccess(params: {
+    userId: string;
+    userType: "user" | "application";
+    resourceType: string;
+    resourceId: string;
+    action: "read" | "manage";
+    hasGlobalAccess: boolean;
+  }): Promise<{ hasAccess: boolean }>;
+  /**
+   * Get IDs of resources the user can access from a given list.
+   * Used for bulk filtering of list endpoints.
+   */
+  getAccessibleResourceIds(params: {
+    userId: string;
+    userType: "user" | "application";
+    resourceType: string;
+    resourceIds: string[];
+    action: "read" | "manage";
+    hasGlobalAccess: boolean;
+  }): Promise<string[]>;
 }
 
 /**
@@ -88,7 +113,7 @@ export interface PluginInstaller {
  * Options for declarative route definitions (Deprecated, will be replaced by oRPC procedures).
  */
 export interface RouteOptions {
-  permission?: string | string[];
+  accessRule?: string | string[];
   schema?: ZodSchema;
 }