@uploadista/server 0.0.3

package/src/service.test.ts

@@ -0,0 +1,275 @@
+import { Effect } from "effect";
+import { describe, expect, it } from "vitest";
+import {
+  AuthContextService,
+  AuthContextServiceLive,
+  NoAuthContextServiceLive,
+} from "./service";
+import type { AuthContext } from "./types";
+
+describe("AuthContextService", () => {
+  describe("AuthContextServiceLive", () => {
+    it("should return userId when auth context is provided", async () => {
+      const authContext: AuthContext = {
+        clientId: "user-123",
+        metadata: { role: "admin" },
+        permissions: ["upload:create", "flow:execute"],
+      };
+
+      const layer = AuthContextServiceLive(authContext);
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.getClientId();
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+      expect(result).toBe("user-123");
+    });
+
+    it("should return null when auth context is null", async () => {
+      const layer = AuthContextServiceLive(null);
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.getClientId();
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+      expect(result).toBeNull();
+    });
+
+    it("should return metadata when auth context is provided", async () => {
+      const authContext: AuthContext = {
+        clientId: "user-123",
+        metadata: { role: "admin", tier: "premium" },
+        permissions: [],
+      };
+
+      const layer = AuthContextServiceLive(authContext);
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.getMetadata();
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+      expect(result).toEqual({ role: "admin", tier: "premium" });
+    });
+
+    it("should return empty object when auth context has no metadata", async () => {
+      const authContext: AuthContext = {
+        clientId: "user-123",
+      };
+
+      const layer = AuthContextServiceLive(authContext);
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.getMetadata();
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+      expect(result).toEqual({});
+    });
+
+    it("should return empty object when auth context is null", async () => {
+      const layer = AuthContextServiceLive(null);
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.getMetadata();
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+      expect(result).toEqual({});
+    });
+
+    it("should return true for existing permission", async () => {
+      const authContext: AuthContext = {
+        clientId: "user-123",
+        permissions: ["upload:create", "flow:execute", "admin:read"],
+      };
+
+      const layer = AuthContextServiceLive(authContext);
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.hasPermission("flow:execute");
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+      expect(result).toBe(true);
+    });
+
+    it("should return false for non-existing permission", async () => {
+      const authContext: AuthContext = {
+        clientId: "user-123",
+        permissions: ["upload:create", "flow:execute"],
+      };
+
+      const layer = AuthContextServiceLive(authContext);
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.hasPermission("admin:write");
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+      expect(result).toBe(false);
+    });
+
+    it("should return false for permission check when no permissions array", async () => {
+      const authContext: AuthContext = {
+        clientId: "user-123",
+      };
+
+      const layer = AuthContextServiceLive(authContext);
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.hasPermission("upload:create");
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+      expect(result).toBe(false);
+    });
+
+    it("should return false for permission check when auth context is null", async () => {
+      const layer = AuthContextServiceLive(null);
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.hasPermission("upload:create");
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+      expect(result).toBe(false);
+    });
+
+    it("should return full auth context when provided", async () => {
+      const authContext: AuthContext = {
+        clientId: "user-123",
+        metadata: { role: "admin" },
+        permissions: ["upload:create"],
+      };
+
+      const layer = AuthContextServiceLive(authContext);
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.getAuthContext();
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+      expect(result).toEqual(authContext);
+    });
+
+    it("should return null auth context when not provided", async () => {
+      const layer = AuthContextServiceLive(null);
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.getAuthContext();
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("NoAuthContextServiceLive", () => {
+    it("should return null for getUserId", async () => {
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.getClientId();
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(NoAuthContextServiceLive)),
+      );
+      expect(result).toBeNull();
+    });
+
+    it("should return empty object for getMetadata", async () => {
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.getMetadata();
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(NoAuthContextServiceLive)),
+      );
+      expect(result).toEqual({});
+    });
+
+    it("should return false for any permission check", async () => {
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        const result1 = yield* service.hasPermission("upload:create");
+        const result2 = yield* service.hasPermission("admin:write");
+        return { result1, result2 };
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(NoAuthContextServiceLive)),
+      );
+      expect(result.result1).toBe(false);
+      expect(result.result2).toBe(false);
+    });
+
+    it("should return null for getAuthContext", async () => {
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        return yield* service.getAuthContext();
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(NoAuthContextServiceLive)),
+      );
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("Effect Layer composition", () => {
+    it("should work in composed effect programs", async () => {
+      const authContext: AuthContext = {
+        clientId: "user-456",
+        metadata: { department: "engineering" },
+        permissions: ["flow:execute"],
+      };
+
+      const layer = AuthContextServiceLive(authContext);
+
+      const program = Effect.gen(function* () {
+        const service = yield* AuthContextService;
+        const clientId = yield* service.getClientId();
+        const metadata = yield* service.getMetadata();
+        const hasPermission = yield* service.hasPermission("flow:execute");
+
+        return { clientId, metadata, hasPermission };
+      });
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      );
+
+      expect(result).toEqual({
+        clientId: "user-456",
+        metadata: { department: "engineering" },
+        hasPermission: true,
+      });
+    });
+  });
+});

package/src/service.ts

@@ -0,0 +1,78 @@
+import { Context, Effect, Layer } from "effect";
+import type { AuthContext } from "./types";
+
+/**
+ * Authentication Context Service
+ *
+ * Provides access to the current authentication context throughout
+ * the upload and flow processing pipeline. The service is provided
+ * via Effect Layer and can be accessed using Effect.service().
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { AuthContextService } from "@uploadista/server";
+ *
+ * const uploadHandler = Effect.gen(function* () {
+ *   const authService = yield* AuthContextService;
+ *   const clientId = yield* authService.getClientId();
+ *   if (clientId) {
+ *     console.log(`Processing upload for client: ${clientId}`);
+ *   }
+ * });
+ * ```
+ */
+export class AuthContextService extends Context.Tag("AuthContextService")<
+  AuthContextService,
+  {
+    /**
+     * Get the current client ID from auth context.
+     * Returns null if no authentication context is available.
+     */
+    readonly getClientId: () => Effect.Effect<string | null>;
+
+    /**
+     * Get the current auth metadata.
+     * Returns empty object if no authentication context or no metadata.
+     */
+    readonly getMetadata: () => Effect.Effect<Record<string, unknown>>;
+
+    /**
+     * Check if the current client has a specific permission.
+     * Returns false if no authentication context or permission not found.
+     */
+    readonly hasPermission: (permission: string) => Effect.Effect<boolean>;
+
+    /**
+     * Get the full authentication context if available.
+     * Returns null if no authentication context is available.
+     */
+    readonly getAuthContext: () => Effect.Effect<AuthContext | null>;
+  }
+>() {}
+
+/**
+ * Creates an AuthContextService Layer from an AuthContext.
+ * This is typically called by adapters after successful authentication.
+ *
+ * @param authContext - The authentication context from middleware
+ * @returns Effect Layer providing AuthContextService
+ */
+export const AuthContextServiceLive = (
+  authContext: AuthContext | null,
+): Layer.Layer<AuthContextService> =>
+  Layer.succeed(AuthContextService, {
+    getClientId: () => Effect.succeed(authContext?.clientId ?? null),
+    getMetadata: () => Effect.succeed(authContext?.metadata ?? {}),
+    hasPermission: (permission: string) =>
+      Effect.succeed(authContext?.permissions?.includes(permission) ?? false),
+    getAuthContext: () => Effect.succeed(authContext),
+  });
+
+/**
+ * No-auth implementation of AuthContextService.
+ * Returns null/empty values for all operations.
+ * Used when no authentication middleware is configured (backward compatibility).
+ */
+export const NoAuthContextServiceLive: Layer.Layer<AuthContextService> =
+  AuthContextServiceLive(null);

package/src/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Authentication context containing user identity and authorization metadata.
+ * This context is extracted from authentication middleware and made available
+ * throughout the upload and flow processing pipeline via Effect Layer.
+ */
+export type AuthContext = {
+  /**
+   * Unique identifier for the authenticated user.
+   * This is typically extracted from JWT claims (sub), session data, or API key metadata.
+   */
+  clientId: string;
+
+  /**
+   * Optional metadata for authorization and tracking purposes.
+   * Can include rate limits, quotas, permissions, or custom application data.
+   *
+   * @example
+   * ```typescript
+   * {
+   *   permissions: ['upload:create', 'flow:execute'],
+   *   rateLimit: { requests: 1000, period: 3600 },
+   *   quota: { storage: 10737418240, used: 5368709120 }
+   * }
+   * ```
+   */
+  metadata?: Record<string, unknown>;
+
+  /**
+   * Optional list of permissions granted to the user.
+   * These can be used for fine-grained access control in the future.
+   */
+  permissions?: string[];
+};
+
+/**
+ * Result type for authentication middleware.
+ * - AuthContext: Successful authentication with user identity
+ * - null: Authentication failed or not authenticated
+ */
+export type AuthResult = AuthContext | null;

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "@uploadista/typescript-config/base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["@cloudflare/workers-types"],
+    "composite": true,
+    "incremental": true,
+    "moduleResolution": "bundler"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}