convex-cms 0.0.1

package/dist/component/authorization.d.ts

@@ -0,0 +1,323 @@
+/**
+ * Authorization Module
+ *
+ * Core permission checking logic that evaluates user roles against requested
+ * actions and resources. This module is called internally by all CMS operations
+ * to enforce access control.
+ *
+ * Key concepts:
+ * - Users are mapped to roles via the getUserRole hook (configured in ComponentConfig)
+ * - Roles have permissions that define what actions can be performed on resources
+ * - Permissions can be scoped to "all" (any resource) or "own" (resources created by the user)
+ *
+ * @example
+ * ```typescript
+ * import { requirePermission, checkPermission, UnauthorizedError } from './authorization';
+ *
+ * // In a mutation handler:
+ * const userRole = await getUserRole(userId);
+ * await requirePermission({
+ *   userId,
+ *   role: userRole,
+ *   resource: 'contentEntries',
+ *   action: 'update',
+ *   resourceOwnerId: entry.createdBy,
+ * });
+ *
+ * // Throws UnauthorizedError if permission denied
+ * ```
+ */
+import { type Resource, type Action, type OwnershipScope, type RoleDefinition } from "./roles.js";
+/**
+ * Error codes for authorization failures.
+ * These provide machine-readable error classification.
+ */
+export type AuthorizationErrorCode = "NO_ROLE" | "UNKNOWN_ROLE" | "PERMISSION_DENIED" | "OWNERSHIP_REQUIRED" | "INVALID_RESOURCE" | "INVALID_ACTION";
+/**
+ * Error thrown when a user lacks permission to perform an action.
+ *
+ * Includes detailed context about the failed authorization check,
+ * making it easy to understand why access was denied.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await requirePermission({ ... });
+ * } catch (error) {
+ *   if (error instanceof UnauthorizedError) {
+ *     console.log(error.code);      // 'PERMISSION_DENIED'
+ *     console.log(error.resource);  // 'contentEntries'
+ *     console.log(error.action);    // 'delete'
+ *     console.log(error.message);   // Human-readable message
+ *   }
+ * }
+ * ```
+ */
+export declare class UnauthorizedError extends Error {
+    /** Machine-readable error code for classification */
+    readonly code: AuthorizationErrorCode;
+    /** The resource being accessed (if applicable) */
+    readonly resource?: Resource;
+    /** The action being attempted (if applicable) */
+    readonly action?: Action;
+    /** The user's role (if known) */
+    readonly role?: string;
+    /** The user ID (if provided) */
+    readonly userId?: string;
+    /** The scope that was required but not granted */
+    readonly requiredScope?: OwnershipScope;
+    constructor(message: string, options: {
+        code: AuthorizationErrorCode;
+        resource?: Resource;
+        action?: Action;
+        role?: string;
+        userId?: string;
+        requiredScope?: OwnershipScope;
+    });
+    /**
+     * Create a JSON-serializable representation of the error.
+     * Useful for logging or API responses.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Options for checking a user's permission to perform an action.
+ */
+export interface PermissionCheckOptions {
+    /** The user ID performing the action (for error messages and ownership checks) */
+    userId?: string;
+    /** The role name to check permissions for (null means no role assigned) */
+    role: string | null;
+    /** The resource type being accessed */
+    resource: Resource;
+    /** The action being performed on the resource */
+    action: Action;
+    /**
+     * The ID of the user who owns the resource.
+     * Required when the user's role only has "own" scope permission.
+     * If not provided and "own" scope is needed, the check will fail.
+     */
+    resourceOwnerId?: string;
+    /**
+     * Custom roles to check in addition to default roles.
+     * Use this to support organization-specific role definitions.
+     */
+    customRoles?: Record<string, RoleDefinition>;
+}
+/**
+ * Result of a permission check that passed.
+ */
+export interface PermissionGranted {
+    allowed: true;
+    /** The scope that was granted (how the permission was satisfied) */
+    grantedScope: OwnershipScope;
+    /** Whether ownership was verified (true if resourceOwnerId matched userId) */
+    ownershipVerified: boolean;
+}
+/**
+ * Result of a permission check that failed.
+ */
+export interface PermissionDenied {
+    allowed: false;
+    /** The reason the permission was denied */
+    reason: string;
+    /** Machine-readable error code */
+    code: AuthorizationErrorCode;
+}
+/**
+ * Result of a permission check.
+ */
+export type PermissionCheckResult = PermissionGranted | PermissionDenied;
+/**
+ * Check if a user has permission to perform an action on a resource.
+ *
+ * This is the core permission evaluation function. It returns a result object
+ * indicating whether the permission was granted or denied, with details about
+ * why.
+ *
+ * The function checks permissions in the following order:
+ * 1. Validates that the user has a role assigned
+ * 2. Validates that the role exists (in default or custom roles)
+ * 3. Checks if the role has the required permission
+ * 4. For "own" scope permissions, validates ownership if resourceOwnerId is provided
+ *
+ * @param options - The permission check configuration
+ * @returns Result indicating whether permission was granted or denied
+ *
+ * @example
+ * ```typescript
+ * // Check if an editor can update any content entry
+ * const result = checkPermission({
+ *   role: 'editor',
+ *   resource: 'contentEntries',
+ *   action: 'update',
+ * });
+ * if (result.allowed) {
+ *   console.log('Permission granted with scope:', result.grantedScope);
+ * }
+ *
+ * // Check if an author can update their own content entry
+ * const result = checkPermission({
+ *   userId: 'user123',
+ *   role: 'author',
+ *   resource: 'contentEntries',
+ *   action: 'update',
+ *   resourceOwnerId: 'user123', // Same as userId - ownership verified
+ * });
+ * ```
+ */
+export declare function checkPermission(options: PermissionCheckOptions): PermissionCheckResult;
+/**
+ * Require that a user has permission to perform an action.
+ *
+ * This is the throwing version of `checkPermission`. It's designed to be used
+ * at the start of mutation/query handlers to enforce access control. If the
+ * permission check fails, it throws an UnauthorizedError with a descriptive
+ * message.
+ *
+ * @param options - The permission check configuration
+ * @returns The granted permission details (if allowed)
+ * @throws UnauthorizedError if the permission is denied
+ *
+ * @example
+ * ```typescript
+ * // In a content entry update mutation:
+ * export const updateEntry = mutation({
+ *   args: { id: v.id("contentEntries"), data: v.any() },
+ *   handler: async (ctx, { id, data }) => {
+ *     const entry = await ctx.db.get(id);
+ *     if (!entry) throw new Error("Entry not found");
+ *
+ *     // Check authorization before proceeding
+ *     const userRole = await getUserRole(ctx.auth.userId);
+ *     await requirePermission({
+ *       userId: ctx.auth.userId,
+ *       role: userRole,
+ *       resource: 'contentEntries',
+ *       action: 'update',
+ *       resourceOwnerId: entry.createdBy,
+ *     });
+ *
+ *     // If we get here, the user is authorized
+ *     await ctx.db.patch(id, data);
+ *   },
+ * });
+ * ```
+ */
+export declare function requirePermission(options: PermissionCheckOptions): PermissionGranted;
+/**
+ * Check if a user owns a resource.
+ *
+ * This is a simple helper for ownership checks without full permission validation.
+ * Use this when you've already verified the permission and just need to check
+ * ownership for scope enforcement.
+ *
+ * @param userId - The ID of the user performing the action
+ * @param resourceOwnerId - The ID of the user who created/owns the resource
+ * @returns True if the user owns the resource
+ *
+ * @example
+ * ```typescript
+ * // Check ownership before allowing a delete
+ * if (!isResourceOwner(currentUserId, entry.createdBy)) {
+ *   throw new UnauthorizedError(
+ *     'You can only delete your own content entries',
+ *     { code: 'OWNERSHIP_REQUIRED', resource: 'contentEntries', action: 'delete' }
+ *   );
+ * }
+ * ```
+ */
+export declare function isResourceOwner(userId: string | undefined, resourceOwnerId: string | undefined): boolean;
+/**
+ * Require that a user owns a resource.
+ *
+ * Throws an UnauthorizedError if the user doesn't own the resource.
+ * Use this when you need to enforce "own" scope on a resource.
+ *
+ * @param userId - The ID of the user performing the action
+ * @param resourceOwnerId - The ID of the user who created/owns the resource
+ * @param options - Additional context for the error message
+ * @throws UnauthorizedError if the user doesn't own the resource
+ *
+ * @example
+ * ```typescript
+ * // Require ownership before allowing update
+ * requireResourceOwnership(currentUserId, entry.createdBy, {
+ *   resource: 'contentEntries',
+ *   action: 'update',
+ *   role: userRole,
+ * });
+ * ```
+ */
+export declare function requireResourceOwnership(userId: string | undefined, resourceOwnerId: string | undefined, options: {
+    resource: Resource;
+    action: Action;
+    role?: string;
+}): void;
+/**
+ * Context for performing authorization checks within a request.
+ * This can be built up at the start of a handler and reused for multiple checks.
+ */
+export interface AuthorizationContext {
+    /** The user's ID */
+    userId: string;
+    /** The user's CMS role */
+    role: string;
+    /** Optional custom roles to check */
+    customRoles?: Record<string, RoleDefinition>;
+}
+/**
+ * Create an authorization context for a user.
+ *
+ * This is a convenience function for building the context object used by
+ * authorization functions. It validates that the user has a role assigned.
+ *
+ * @param userId - The user's ID
+ * @param role - The user's role (from getUserRole hook)
+ * @param customRoles - Optional custom role definitions
+ * @returns Authorization context for permission checks
+ * @throws UnauthorizedError if the user has no role assigned
+ *
+ * @example
+ * ```typescript
+ * // At the start of a mutation handler:
+ * const userRole = await getUserRole({ userId });
+ * const authCtx = createAuthContext(userId, userRole);
+ *
+ * // Later, check permissions with the context:
+ * requirePermission({
+ *   ...authCtx,
+ *   resource: 'contentEntries',
+ *   action: 'create',
+ * });
+ * ```
+ */
+export declare function createAuthContext(userId: string, role: string | null, customRoles?: Record<string, RoleDefinition>): AuthorizationContext;
+/**
+ * Check if a user can perform an action using an authorization context.
+ *
+ * This is a convenience wrapper around checkPermission that uses a pre-built
+ * authorization context.
+ *
+ * @param authCtx - The authorization context
+ * @param resource - The resource type being accessed
+ * @param action - The action being performed
+ * @param resourceOwnerId - Optional owner ID for ownership validation
+ * @returns Permission check result
+ */
+export declare function canPerform(authCtx: AuthorizationContext, resource: Resource, action: Action, resourceOwnerId?: string): PermissionCheckResult;
+/**
+ * Require that a user can perform an action using an authorization context.
+ *
+ * This is a convenience wrapper around requirePermission that uses a pre-built
+ * authorization context.
+ *
+ * @param authCtx - The authorization context
+ * @param resource - The resource type being accessed
+ * @param action - The action being performed
+ * @param resourceOwnerId - Optional owner ID for ownership validation
+ * @returns The granted permission details
+ * @throws UnauthorizedError if permission is denied
+ */
+export declare function mustPerform(authCtx: AuthorizationContext, resource: Resource, action: Action, resourceOwnerId?: string): PermissionGranted;
+//# sourceMappingURL=authorization.d.ts.map

package/dist/component/authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../../src/component/authorization.ts"],"names":[],"mappings":"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"}