@uploadista/server 0.0.18-beta.7 → 0.0.18-beta.9

package/src/permissions/errors.ts

@@ -0,0 +1,105 @@
+/**
+ * Authorization Error Types
+ *
+ * Error classes for permission and authorization failures.
+ */
+
+import { AdapterError } from "../error-types";
+
+/**
+ * Authorization error - indicates the user lacks required permissions.
+ * Returns HTTP 403 Forbidden status.
+ *
+ * @example
+ * ```typescript
+ * if (!hasPermission(permissions, "engine:metrics")) {
+ *   throw new AuthorizationError("engine:metrics");
+ * }
+ * ```
+ */
+export class AuthorizationError extends AdapterError {
+  /**
+   * The permission that was required but not granted.
+   */
+  public readonly requiredPermission: string;
+
+  constructor(requiredPermission: string, message?: string) {
+    super(
+      message ?? `Permission denied: ${requiredPermission} required`,
+      403,
+      "PERMISSION_DENIED",
+    );
+    this.name = "AuthorizationError";
+    this.requiredPermission = requiredPermission;
+  }
+}
+
+/**
+ * Authentication required error - indicates no authentication context.
+ * Returns HTTP 401 Unauthorized status.
+ *
+ * @example
+ * ```typescript
+ * if (!authContext) {
+ *   throw new AuthenticationRequiredError();
+ * }
+ * ```
+ */
+export class AuthenticationRequiredError extends AdapterError {
+  constructor(message = "Authentication required") {
+    super(message, 401, "AUTHENTICATION_REQUIRED");
+    this.name = "AuthenticationRequiredError";
+  }
+}
+
+/**
+ * Organization mismatch error - indicates accessing a resource from another organization.
+ * Returns HTTP 403 Forbidden status.
+ *
+ * @example
+ * ```typescript
+ * if (resource.organizationId !== clientId) {
+ *   throw new OrganizationMismatchError();
+ * }
+ * ```
+ */
+export class OrganizationMismatchError extends AdapterError {
+  constructor(message = "Access denied: resource belongs to another organization") {
+    super(message, 403, "ORGANIZATION_MISMATCH");
+    this.name = "OrganizationMismatchError";
+  }
+}
+
+/**
+ * Quota exceeded error - indicates usage quota has been exceeded.
+ * Returns HTTP 402 Payment Required status.
+ *
+ * @example
+ * ```typescript
+ * if (usage > quota) {
+ *   throw new QuotaExceededError("Storage quota exceeded");
+ * }
+ * ```
+ */
+export class QuotaExceededError extends AdapterError {
+  constructor(message = "Quota exceeded", code = "QUOTA_EXCEEDED") {
+    super(message, 402, code);
+    this.name = "QuotaExceededError";
+  }
+}
+
+/**
+ * Creates a standardized error response body for AuthorizationError.
+ * Includes the required permission in the response.
+ *
+ * @param error - The AuthorizationError to format
+ * @returns Standardized error response body
+ */
+export const createAuthorizationErrorResponseBody = (
+  error: AuthorizationError,
+) => ({
+  error: error.message,
+  code: error.errorCode,
+  requiredPermission: error.requiredPermission,
+  timestamp: new Date().toISOString(),
+});

package/src/permissions/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Permissions Module
+ *
+ * Exports all permission-related types, constants, and utilities.
+ */
+
+export * from "./types";
+export * from "./matcher";
+export * from "./errors";

package/src/permissions/matcher.ts

@@ -0,0 +1,139 @@
+/**
+ * Permission Matching Logic
+ *
+ * Implements permission matching with support for:
+ * - Exact match: `engine:health` matches `engine:health`
+ * - Wildcard match: `engine:*` matches `engine:health`, `engine:metrics`, etc.
+ * - Hierarchical match: `engine:dlq` implies `engine:dlq:read` and `engine:dlq:write`
+ */
+
+import { PERMISSION_HIERARCHY } from "./types";
+
+/**
+ * Checks if a granted permission matches a required permission.
+ *
+ * @param granted - The permission that has been granted to the user
+ * @param required - The permission that is required for the operation
+ * @returns true if the granted permission satisfies the required permission
+ *
+ * @example
+ * ```typescript
+ * matchesPermission("engine:*", "engine:health") // true (wildcard)
+ * matchesPermission("engine:health", "engine:health") // true (exact)
+ * matchesPermission("engine:dlq", "engine:dlq:read") // true (hierarchical)
+ * matchesPermission("flow:execute", "engine:health") // false
+ * ```
+ */
+export const matchesPermission = (
+  granted: string,
+  required: string,
+): boolean => {
+  // Exact match
+  if (granted === required) {
+    return true;
+  }
+
+  // Wildcard match: `engine:*` matches `engine:health`
+  if (granted.endsWith(":*")) {
+    const prefix = granted.slice(0, -1); // Remove the `*`, keep the `:`
+    if (required.startsWith(prefix)) {
+      return true;
+    }
+  }
+
+  // Hierarchical match: `engine:dlq` implies `engine:dlq:read`
+  const impliedPermissions = PERMISSION_HIERARCHY[granted];
+  if (impliedPermissions?.includes(required)) {
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * Checks if any of the granted permissions satisfy the required permission.
+ *
+ * @param grantedPermissions - Array of permissions granted to the user
+ * @param required - The permission that is required for the operation
+ * @returns true if any granted permission satisfies the required permission
+ *
+ * @example
+ * ```typescript
+ * hasPermission(["flow:*", "upload:create"], "flow:execute") // true
+ * hasPermission(["upload:create"], "flow:execute") // false
+ * ```
+ */
+export const hasPermission = (
+  grantedPermissions: readonly string[],
+  required: string,
+): boolean => {
+  return grantedPermissions.some((granted) =>
+    matchesPermission(granted, required),
+  );
+};
+
+/**
+ * Checks if any of the granted permissions satisfy any of the required permissions.
+ *
+ * @param grantedPermissions - Array of permissions granted to the user
+ * @param requiredPermissions - Array of permissions, any of which would be sufficient
+ * @returns true if any granted permission satisfies any required permission
+ *
+ * @example
+ * ```typescript
+ * hasAnyPermission(["upload:create"], ["flow:execute", "upload:create"]) // true
+ * hasAnyPermission(["upload:read"], ["flow:execute", "upload:create"]) // false
+ * ```
+ */
+export const hasAnyPermission = (
+  grantedPermissions: readonly string[],
+  requiredPermissions: readonly string[],
+): boolean => {
+  return requiredPermissions.some((required) =>
+    hasPermission(grantedPermissions, required),
+  );
+};
+
+/**
+ * Checks if all of the required permissions are satisfied.
+ *
+ * @param grantedPermissions - Array of permissions granted to the user
+ * @param requiredPermissions - Array of permissions, all of which must be satisfied
+ * @returns true if all required permissions are satisfied
+ *
+ * @example
+ * ```typescript
+ * hasAllPermissions(["flow:*", "upload:*"], ["flow:execute", "upload:create"]) // true
+ * hasAllPermissions(["flow:execute"], ["flow:execute", "upload:create"]) // false
+ * ```
+ */
+export const hasAllPermissions = (
+  grantedPermissions: readonly string[],
+  requiredPermissions: readonly string[],
+): boolean => {
+  return requiredPermissions.every((required) =>
+    hasPermission(grantedPermissions, required),
+  );
+};
+
+/**
+ * Expands a permission to include all implied permissions.
+ * Useful for display or audit purposes.
+ *
+ * @param permission - The permission to expand
+ * @returns Array of the permission and all implied permissions
+ *
+ * @example
+ * ```typescript
+ * expandPermission("engine:dlq") // ["engine:dlq", "engine:dlq:read", "engine:dlq:write"]
+ * expandPermission("engine:health") // ["engine:health"]
+ * ```
+ */
+export const expandPermission = (permission: string): string[] => {
+  const result = [permission];
+  const implied = PERMISSION_HIERARCHY[permission];
+  if (implied) {
+    result.push(...implied);
+  }
+  return result;
+};

package/src/permissions/types.ts

@@ -0,0 +1,151 @@
+/**
+ * Permission Types and Constants
+ *
+ * Defines the permission model for fine-grained access control in the uploadista engine.
+ * Permissions follow a hierarchical format: `resource:action` with support for wildcards.
+ */
+
+// ============================================================================
+// Engine Permissions - Admin operations
+// ============================================================================
+
+/**
+ * Engine permissions for administrative operations.
+ * These control access to health, readiness, metrics, and DLQ endpoints.
+ */
+export const ENGINE_PERMISSIONS = {
+  /** Full admin access to all engine operations */
+  ALL: "engine:*",
+  /** Access health endpoint */
+  HEALTH: "engine:health",
+  /** Access readiness endpoint */
+  READINESS: "engine:readiness",
+  /** Access metrics endpoint */
+  METRICS: "engine:metrics",
+  /** Full DLQ access (implies read and write) */
+  DLQ: "engine:dlq",
+  /** Read DLQ entries */
+  DLQ_READ: "engine:dlq:read",
+  /** Retry/delete DLQ entries */
+  DLQ_WRITE: "engine:dlq:write",
+} as const;
+
+// ============================================================================
+// Flow Permissions - Flow execution operations
+// ============================================================================
+
+/**
+ * Flow permissions for flow execution operations.
+ */
+export const FLOW_PERMISSIONS = {
+  /** Full access to all flow operations */
+  ALL: "flow:*",
+  /** Execute flows */
+  EXECUTE: "flow:execute",
+  /** Cancel running flows */
+  CANCEL: "flow:cancel",
+  /** Check flow status */
+  STATUS: "flow:status",
+} as const;
+
+// ============================================================================
+// Upload Permissions - File upload operations
+// ============================================================================
+
+/**
+ * Upload permissions for file upload operations.
+ */
+export const UPLOAD_PERMISSIONS = {
+  /** Full access to all upload operations */
+  ALL: "upload:*",
+  /** Create uploads */
+  CREATE: "upload:create",
+  /** Read upload status */
+  READ: "upload:read",
+  /** Cancel uploads */
+  CANCEL: "upload:cancel",
+} as const;
+
+// ============================================================================
+// Combined Permissions Object
+// ============================================================================
+
+/**
+ * All available permissions organized by category.
+ *
+ * @example
+ * ```typescript
+ * import { PERMISSIONS } from "@uploadista/server";
+ *
+ * const adminPermissions = [PERMISSIONS.ENGINE.ALL];
+ * const userPermissions = [PERMISSIONS.FLOW.ALL, PERMISSIONS.UPLOAD.ALL];
+ * ```
+ */
+export const PERMISSIONS = {
+  ENGINE: ENGINE_PERMISSIONS,
+  FLOW: FLOW_PERMISSIONS,
+  UPLOAD: UPLOAD_PERMISSIONS,
+} as const;
+
+// ============================================================================
+// Permission Type Definitions
+// ============================================================================
+
+/** All engine permission strings */
+export type EnginePermission =
+  (typeof ENGINE_PERMISSIONS)[keyof typeof ENGINE_PERMISSIONS];
+
+/** All flow permission strings */
+export type FlowPermission =
+  (typeof FLOW_PERMISSIONS)[keyof typeof FLOW_PERMISSIONS];
+
+/** All upload permission strings */
+export type UploadPermission =
+  (typeof UPLOAD_PERMISSIONS)[keyof typeof UPLOAD_PERMISSIONS];
+
+/**
+ * Union type of all valid permission strings.
+ * Includes standard permissions and allows custom permissions via string.
+ */
+export type Permission =
+  | EnginePermission
+  | FlowPermission
+  | UploadPermission
+  | (string & {}); // Allow custom permissions while maintaining autocomplete
+
+/**
+ * Predefined permission sets for common use cases.
+ */
+export const PERMISSION_SETS = {
+  /** Full admin access - all engine, flow, and upload permissions */
+  ADMIN: [ENGINE_PERMISSIONS.ALL] as const,
+
+  /** Organization owner - all flow and upload permissions */
+  ORGANIZATION_OWNER: [
+    FLOW_PERMISSIONS.ALL,
+    UPLOAD_PERMISSIONS.ALL,
+  ] as const,
+
+  /** Organization member - same as owner for now */
+  ORGANIZATION_MEMBER: [
+    FLOW_PERMISSIONS.ALL,
+    UPLOAD_PERMISSIONS.ALL,
+  ] as const,
+
+  /** API key - limited to execute flows and create uploads */
+  API_KEY: [
+    FLOW_PERMISSIONS.EXECUTE,
+    UPLOAD_PERMISSIONS.CREATE,
+  ] as const,
+} as const;
+
+/**
+ * Hierarchical permission relationships.
+ * When a parent permission is granted, all child permissions are implied.
+ */
+export const PERMISSION_HIERARCHY: Record<string, readonly string[]> = {
+  [ENGINE_PERMISSIONS.DLQ]: [
+    ENGINE_PERMISSIONS.DLQ_READ,
+    ENGINE_PERMISSIONS.DLQ_WRITE,
+  ],
+} as const;

package/src/service.ts

@@ -1,5 +1,10 @@
 import { Context, Effect, Layer } from "effect";
 import type { AuthContext } from "./types";
+import {
+  hasPermission as matchHasPermission,
+  hasAnyPermission as matchHasAnyPermission,
+} from "./permissions/matcher";
+import { AuthorizationError, AuthenticationRequiredError } from "./permissions/errors";
 
 /**
  * Authentication Context Service
@@ -39,10 +44,68 @@ export class AuthContextService extends Context.Tag("AuthContextService")<
 
     /**
      * Check if the current client has a specific permission.
+     * Supports exact match, wildcard match, and hierarchical match.
      * Returns false if no authentication context or permission not found.
+     *
+     * @example
+     * ```typescript
+     * // Exact match
+     * yield* authService.hasPermission("engine:health")
+     *
+     * // Wildcard: user with "engine:*" will match "engine:health"
+     * yield* authService.hasPermission("engine:health")
+     *
+     * // Hierarchical: user with "engine:dlq" will match "engine:dlq:read"
+     * yield* authService.hasPermission("engine:dlq:read")
+     * ```
      */
     readonly hasPermission: (permission: string) => Effect.Effect<boolean>;
 
+    /**
+     * Check if the current client has any of the specified permissions.
+     * Returns true if at least one permission is granted.
+     */
+    readonly hasAnyPermission: (
+      permissions: readonly string[],
+    ) => Effect.Effect<boolean>;
+
+    /**
+     * Require a specific permission, failing with AuthorizationError if not granted.
+     * Use this when you want to fail fast on missing permissions.
+     *
+     * @throws AuthorizationError if permission is not granted
+     * @throws AuthenticationRequiredError if no auth context
+     *
+     * @example
+     * ```typescript
+     * const protectedHandler = Effect.gen(function* () {
+     *   const authService = yield* AuthContextService;
+     *   yield* authService.requirePermission("engine:metrics");
+     *   // Only reaches here if permission is granted
+     *   return yield* getMetrics();
+     * });
+     * ```
+     */
+    readonly requirePermission: (
+      permission: string,
+    ) => Effect.Effect<void, AuthorizationError | AuthenticationRequiredError>;
+
+    /**
+     * Require authentication, failing with AuthenticationRequiredError if not authenticated.
+     *
+     * @throws AuthenticationRequiredError if no auth context
+     */
+    readonly requireAuthentication: () => Effect.Effect<
+      AuthContext,
+      AuthenticationRequiredError
+    >;
+
+    /**
+     * Get all permissions granted to the current client.
+     * Returns empty array if no authentication context or no permissions.
+     */
+    readonly getPermissions: () => Effect.Effect<readonly string[]>;
+
     /**
      * Get the full authentication context if available.
      * Returns null if no authentication context is available.
@@ -60,14 +123,49 @@ export class AuthContextService extends Context.Tag("AuthContextService")<
  */
 export const AuthContextServiceLive = (
   authContext: AuthContext | null,
-): Layer.Layer<AuthContextService> =>
-  Layer.succeed(AuthContextService, {
+): Layer.Layer<AuthContextService> => {
+  const permissions = authContext?.permissions ?? [];
+
+  return Layer.succeed(AuthContextService, {
     getClientId: () => Effect.succeed(authContext?.clientId ?? null),
+
     getMetadata: () => Effect.succeed(authContext?.metadata ?? {}),
+
     hasPermission: (permission: string) =>
-      Effect.succeed(authContext?.permissions?.includes(permission) ?? false),
+      Effect.succeed(matchHasPermission(permissions, permission)),
+
+    hasAnyPermission: (requiredPermissions: readonly string[]) =>
+      Effect.succeed(matchHasAnyPermission(permissions, requiredPermissions)),
+
+    requirePermission: (permission: string) =>
+      Effect.gen(function* () {
+        if (!authContext) {
+          yield* Effect.logDebug(
+            `[Auth] Permission check failed: authentication required for '${permission}'`,
+          );
+          return yield* Effect.fail(new AuthenticationRequiredError());
+        }
+        if (!matchHasPermission(permissions, permission)) {
+          yield* Effect.logDebug(
+            `[Auth] Permission denied: '${permission}' for client '${authContext.clientId}'`,
+          );
+          return yield* Effect.fail(new AuthorizationError(permission));
+        }
+        yield* Effect.logDebug(
+          `[Auth] Permission granted: '${permission}' for client '${authContext.clientId}'`,
+        );
+      }),
+
+    requireAuthentication: () =>
+      authContext
+        ? Effect.succeed(authContext)
+        : Effect.fail(new AuthenticationRequiredError()),
+
+    getPermissions: () => Effect.succeed(permissions),
+
     getAuthContext: () => Effect.succeed(authContext),
   });
+};
 
 /**
  * No-auth implementation of AuthContextService.

package/src/usage-hooks/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Usage Hooks Module
+ *
+ * Exports all usage hook types and services.
+ */
+
+export * from "./types";
+export * from "./service";