@uploadista/server 0.0.17 → 0.0.18-beta.10

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/plugins-typing.ts

@@ -15,7 +15,7 @@
  */
 
 import type { Flow, UploadServer } from "@uploadista/core";
-import type { ExtractLayerServices } from "@uploadista/core/flow/types";
+import type { ExtractLayerServices } from "@uploadista/core/flow";
 import type { Effect, Layer } from "effect";
 import type z from "zod";
 

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";

package/src/usage-hooks/service.ts

@@ -0,0 +1,162 @@
+/**
+ * Usage Hook Service
+ *
+ * Effect service for executing usage tracking hooks with timeout handling.
+ */
+
+import { Context, Effect, Layer } from "effect";
+import type {
+  UsageHookConfig,
+  UsageHookResult,
+  UploadUsageContext,
+  FlowUsageContext,
+} from "./types";
+import { DEFAULT_USAGE_HOOK_TIMEOUT, continueResult } from "./types";
+
+/**
+ * Usage Hook Service
+ *
+ * Provides methods to execute usage hooks during upload and flow processing.
+ * Handles timeout and error recovery gracefully.
+ */
+export class UsageHookService extends Context.Tag("UsageHookService")<
+  UsageHookService,
+  {
+    /**
+     * Execute onUploadStart hook if configured.
+     * Returns continue result if no hook is configured or on error/timeout.
+     */
+    readonly onUploadStart: (
+      ctx: UploadUsageContext,
+    ) => Effect.Effect<UsageHookResult>;
+
+    /**
+     * Execute onUploadComplete hook if configured.
+     * Errors are logged but swallowed (fire-and-forget).
+     */
+    readonly onUploadComplete: (ctx: UploadUsageContext) => Effect.Effect<void>;
+
+    /**
+     * Execute onFlowStart hook if configured.
+     * Returns continue result if no hook is configured or on error/timeout.
+     */
+    readonly onFlowStart: (
+      ctx: FlowUsageContext,
+    ) => Effect.Effect<UsageHookResult>;
+
+    /**
+     * Execute onFlowComplete hook if configured.
+     * Errors are logged but swallowed (fire-and-forget).
+     */
+    readonly onFlowComplete: (ctx: FlowUsageContext) => Effect.Effect<void>;
+  }
+>() {}
+
+/**
+ * Creates a UsageHookService Layer from configuration.
+ *
+ * @param config - Usage hook configuration with optional hooks and timeout
+ * @returns Effect Layer providing UsageHookService
+ */
+export const UsageHookServiceLive = (
+  config?: UsageHookConfig,
+): Layer.Layer<UsageHookService> => {
+  const hooks = config?.hooks;
+  const timeout = config?.timeout ?? DEFAULT_USAGE_HOOK_TIMEOUT;
+
+  return Layer.succeed(UsageHookService, {
+    onUploadStart: (ctx: UploadUsageContext) => {
+      if (!hooks?.onUploadStart) {
+        return Effect.succeed(continueResult());
+      }
+
+      return hooks
+        .onUploadStart(ctx)
+        .pipe(
+          // Add timeout - proceed on timeout (fail-open)
+          Effect.timeout(timeout),
+          Effect.map((result) => result ?? continueResult()),
+          // On any error, log and continue (fail-open for availability)
+          Effect.catchAll((error) =>
+            Effect.gen(function* () {
+              yield* Effect.logWarning(
+                `onUploadStart hook failed: ${error}. Proceeding with upload.`,
+              );
+              return continueResult();
+            }),
+          ),
+        );
+    },
+
+    onUploadComplete: (ctx: UploadUsageContext) => {
+      if (!hooks?.onUploadComplete) {
+        return Effect.void;
+      }
+
+      return hooks
+        .onUploadComplete(ctx)
+        .pipe(
+          // Add timeout
+          Effect.timeout(timeout),
+          Effect.asVoid,
+          // On any error, just log (fire-and-forget)
+          Effect.catchAll((error) =>
+            Effect.logWarning(
+              `onUploadComplete hook failed: ${error}. Upload already completed.`,
+            ),
+          ),
+        );
+    },
+
+    onFlowStart: (ctx: FlowUsageContext) => {
+      if (!hooks?.onFlowStart) {
+        return Effect.succeed(continueResult());
+      }
+
+      return hooks
+        .onFlowStart(ctx)
+        .pipe(
+          // Add timeout - proceed on timeout (fail-open)
+          Effect.timeout(timeout),
+          Effect.map((result) => result ?? continueResult()),
+          // On any error, log and continue (fail-open for availability)
+          Effect.catchAll((error) =>
+            Effect.gen(function* () {
+              yield* Effect.logWarning(
+                `onFlowStart hook failed: ${error}. Proceeding with flow.`,
+              );
+              return continueResult();
+            }),
+          ),
+        );
+    },
+
+    onFlowComplete: (ctx: FlowUsageContext) => {
+      if (!hooks?.onFlowComplete) {
+        return Effect.void;
+      }
+
+      return hooks
+        .onFlowComplete(ctx)
+        .pipe(
+          // Add timeout
+          Effect.timeout(timeout),
+          Effect.asVoid,
+          // On any error, just log (fire-and-forget)
+          Effect.catchAll((error) =>
+            Effect.logWarning(
+              `onFlowComplete hook failed: ${error}. Flow already completed.`,
+            ),
+          ),
+        );
+    },
+  });
+};
+
+/**
+ * No-op implementation of UsageHookService.
+ * All hooks are no-ops that return continue/void.
+ * Used when no usage hooks are configured (default backward compatibility).
+ */
+export const NoUsageHookServiceLive: Layer.Layer<UsageHookService> =
+  UsageHookServiceLive();