cloudflare-access 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,452 @@
+# cloudflare-access
+
+Multi-framework authentication for Cloudflare Access with JWT validation.
+
+Supports: **Hono**, **Express**, **Fastify**, **NestJS**, and **Effect-TS**.
+
+## Installation
+
+```bash
+# npm
+npm install cloudflare-access
+
+# yarn
+yarn add cloudflare-access
+
+# bun
+bun add cloudflare-access
+```
+
+## Framework-Specific Installation
+
+### Hono
+
+```bash
+bun add cloudflare-access hono
+```
+
+### Express
+
+```bash
+bun add cloudflare-access express
+```
+
+### Fastify
+
+```bash
+bun add cloudflare-access fastify
+```
+
+### NestJS
+
+```bash
+bun add cloudflare-access @nestjs/common @nestjs/core
+```
+
+### Effect-TS
+
+```bash
+bun add cloudflare-access effect
+```
+
+## Quick Start
+
+### Hono
+
+```typescript
+import { Hono } from "hono";
+import { createCloudflareAccessAuth } from "cloudflare-access/hono";
+
+const app = new Hono();
+
+// Using static configuration (works with any deployment target)
+app.use(
+  createCloudflareAccessAuth({
+    accessConfig: {
+      teamDomain: process.env.CF_ACCESS_TEAM_DOMAIN!,
+      audTag: process.env.CF_ACCESS_AUD!,
+    },
+  }),
+);
+
+// Or with Cloudflare Workers bindings
+// import { getCloudflareAccessConfigFromBindings } from "cloudflare-access/hono";
+// app.use(createCloudflareAccessAuth({
+//   accessConfig: getCloudflareAccessConfigFromBindings,
+// }));
+
+app.get("/protected", (c) => {
+  const user = c.get("user");
+  return c.json({ email: user?.email });
+});
+```
+
+### Express
+
+```typescript
+import express from "express";
+import { cloudflareAccessAuth } from "cloudflare-access/express";
+
+const app = express();
+
+app.use(
+  cloudflareAccessAuth({
+    accessConfig: {
+      teamDomain: "https://yourteam.cloudflareaccess.com",
+      audTag: "your-audience-tag",
+    },
+  }),
+);
+
+app.get("/protected", (req, res) => {
+  res.json({ email: req.user?.email });
+});
+```
+
+### Fastify
+
+```typescript
+import fastify from "fastify";
+import { cloudflareAccessPlugin } from "cloudflare-access/fastify";
+
+const app = fastify();
+
+app.register(cloudflareAccessPlugin, {
+  accessConfig: {
+    teamDomain: "https://yourteam.cloudflareaccess.com",
+    audTag: "your-audience-tag",
+  },
+});
+
+app.get("/protected", async (request, reply) => {
+  return { email: request.user?.email };
+});
+```
+
+### NestJS
+
+```typescript
+import { Controller, Get, Req, Module } from "@nestjs/common";
+import { CloudflareAccessGuard, Public } from "cloudflare-access/nestjs";
+import { APP_GUARD } from "@nestjs/core";
+import type { Request } from "express";
+
+@Controller("api")
+export class ApiController {
+  @Get("protected")
+  getProtected(@Req() req: Request) {
+    return { email: req.user?.email };
+  }
+
+  @Public()
+  @Get("public")
+  getPublic() {
+    return { message: "This is public" };
+  }
+}
+
+@Module({
+  controllers: [ApiController],
+  providers: [
+    {
+      provide: APP_GUARD,
+      useFactory: () =>
+        new CloudflareAccessGuard({
+          accessConfig: {
+            teamDomain: "https://yourteam.cloudflareaccess.com",
+            audTag: "your-audience-tag",
+          },
+        }),
+    },
+  ],
+})
+export class AppModule {}
+```
+
+### Effect-TS
+
+```typescript
+import { Effect, Either } from "effect";
+import { HttpServerRequest } from "@effect/platform";
+import { authenticateRequest } from "cloudflare-access/effect";
+
+const request: HttpServerRequest.HttpServerRequest = {
+  url: "https://example.com/api/protected",
+  headers: {
+    "cf-access-jwt-assertion": "jwt-token-here",
+  },
+  method: "GET",
+};
+
+const program = Effect.gen(function* () {
+  const result = yield* Effect.either(
+    authenticateRequest(request, {
+      accessConfig: {
+        teamDomain: "https://yourteam.cloudflareaccess.com",
+        audTag: "your-audience-tag",
+      },
+    }),
+  );
+
+  return Either.match(result, {
+    onLeft: (error) => {
+      console.error(`Auth failed: ${error.message}`);
+      return null;
+    },
+    onRight: (user) => {
+      console.log(`Authenticated user: ${user.email}`);
+      return user;
+    },
+  });
+});
+
+Effect.runPromise(program);
+```
+
+## Configuration
+
+### Environment Variables
+
+Configure your Cloudflare Access credentials via environment variables:
+
+```bash
+# .env
+CF_ACCESS_TEAM_DOMAIN=https://yourteam.cloudflareaccess.com
+CF_ACCESS_AUD=your-audience-tag
+ENVIRONMENT=dev
+```
+
+Or set them directly in your environment:
+
+```bash
+export CF_ACCESS_TEAM_DOMAIN="https://yourteam.cloudflareaccess.com"
+export CF_ACCESS_AUD="your-audience-tag"
+```
+
+For **Cloudflare Workers**, use `wrangler.toml`:
+
+```toml
+[vars]
+CF_ACCESS_TEAM_DOMAIN = "https://yourteam.cloudflareaccess.com"
+CF_ACCESS_AUD = "your-audience-tag"
+```
+
+Or with Wrangler secrets:
+
+```bash
+wrangler secret put CF_ACCESS_AUD
+```
+
+### Common Options
+
+All framework adapters support these options:
+
+```typescript
+interface CloudflareAccessAuthOptions {
+  /** Cloudflare Access configuration */
+  accessConfig: CloudflareAccessConfig;
+
+  /** Optional email allowlist */
+  allowedEmails?: string[];
+
+  /** Custom unauthorized handler */
+  onUnauthorized?: (reason: string) => Response | void | Promise<void>;
+
+  /** Custom forbidden handler */
+  onForbidden?: (email: string) => Response | void | Promise<void>;
+
+  /** Paths to exclude from authentication */
+  excludePaths?: string[];
+
+  /** Skip JWT validation in development (localhost requests) */
+  skipInDev?: boolean;
+
+  /** Environment indicator */
+  environment?: string;
+}
+```
+
+## User Information
+
+After successful authentication, user information is available:
+
+```typescript
+interface CloudflareAccessUser {
+  email: string;
+  userId?: string;
+  country?: string;
+}
+```
+
+## Rich Error Handling
+
+The library provides rich, actionable errors with detailed context:
+
+### Error Classes
+
+```typescript
+import {
+  CloudflareAccessError,
+  AuthRequiredError,
+  InvalidTokenError,
+  AccessDeniedError,
+  ConfigurationError,
+  // Type guards
+  isAuthRequiredError,
+  isInvalidTokenError,
+  isAccessDeniedError,
+} from "cloudflare-access/core";
+
+// All errors extend CloudflareAccessError
+try {
+  await validateCloudflareAccessToken(token, options, url);
+} catch (error) {
+  if (isAuthRequiredError(error)) {
+    console.log("Auth required:", error.message);
+    console.log("Fix:", error.context?.fix);
+  }
+
+  if (isInvalidTokenError(error)) {
+    console.log("Invalid token:", error.reason);
+    console.log("Token info:", error.context?.tokenInfo);
+  }
+
+  if (isAccessDeniedError(error)) {
+    console.log("Access denied for:", error.email);
+  }
+
+  // All errors are serializable
+  console.log("Full error:", error.toJSON());
+}
+```
+
+### Error Codes
+
+```typescript
+import { CloudflareAccessErrorCode } from "cloudflare-access/core";
+
+// Available error codes:
+// - AUTH_REQUIRED: Missing or invalid authentication token
+// - INVALID_TOKEN: Token validation failed (expired, wrong signature, etc.)
+// - ACCESS_DENIED: User email not in allowlist
+// - INVALID_TEAM_DOMAIN: Invalid team domain configuration
+// - MISSING_AUDIENCE_TAG: Missing audience tag
+// - MISSING_CONFIG: Missing environment configuration
+```
+
+### Effect-TS Error Handling
+
+```typescript
+import { Effect, Either } from "effect";
+import {
+  authenticateRequest,
+  AuthRequiredError,
+  InvalidTokenError,
+  AccessDeniedError,
+} from "cloudflare-access/effect";
+import { HttpServerRequest } from "@effect/platform";
+
+const request: HttpServerRequest.HttpServerRequest = {
+  url: "https://example.com/api/protected",
+  headers: { "cf-access-jwt-assertion": "token" },
+  method: "GET",
+};
+
+const program = Effect.gen(function* () {
+  const result = yield* Effect.either(
+    authenticateRequest(request, {
+      accessConfig: {
+        teamDomain: "https://yourteam.cloudflareaccess.com",
+        audTag: "your-audience-tag",
+      },
+    }),
+  );
+
+  return Either.match(result, {
+    onLeft: (error) => {
+      if (error instanceof AuthRequiredError) {
+        console.log("Auth required:", error.message);
+        return null;
+      }
+      if (error instanceof AccessDeniedError) {
+        console.log("Access denied for:", error.email);
+        return null;
+      }
+      throw error;
+    },
+    onRight: (user) => user,
+  });
+});
+```
+
+## Using the Core Module Directly
+
+If you need lower-level access to the authentication logic:
+
+```typescript
+import {
+  validateCloudflareAccessToken,
+  getCloudflareAccessConfigFromEnv,
+  type CloudflareAccessConfig,
+} from "cloudflare-access/core";
+
+const result = await validateCloudflareAccessToken(
+  token,
+  { accessConfig: { teamDomain, audTag } },
+  requestUrl,
+);
+
+if (result.success) {
+  console.log("User:", result.user);
+} else {
+  console.log("Auth failed:", result.error);
+}
+```
+
+## Package Imports
+
+The package uses subpath exports for each framework:
+
+```typescript
+// Core authentication logic
+import { validateCloudflareAccessToken } from "cloudflare-access/core";
+
+// Framework adapters
+import { createCloudflareAccessAuth } from "cloudflare-access/hono";
+import { cloudflareAccessAuth } from "cloudflare-access/express";
+import { cloudflareAccessPlugin } from "cloudflare-access/fastify";
+import { CloudflareAccessGuard } from "cloudflare-access/nestjs";
+import { authenticateRequest } from "cloudflare-access/effect";
+
+// Hono exports (from root)
+import {
+  createCloudflareAccessAuth,
+  getCloudflareAccessConfigFromBindings,
+} from "cloudflare-access";
+```
+
+## Examples
+
+See the `/examples` directory for detailed examples:
+
+- `examples/hono/` - Hono framework examples
+- `examples/express/` - Express framework examples
+- `examples/fastify/` - Fastify framework examples
+- `examples/nestjs/` - NestJS framework examples
+- `examples/effect/` - Effect-TS framework examples
+
+## Testing
+
+The library includes comprehensive test coverage for all adapters:
+
+```bash
+# Run all tests
+bun test
+
+# Run with coverage
+bun test --coverage
+```
+
+## License
+
+MIT

package/dist/adapters/effect/index.d.mts

@@ -0,0 +1,167 @@
+import { C as CloudflareAccessConfig, g as CloudflareAccessUser, c as CloudflareAccessError } from '../../jwks-ChdyyS_L.mjs';
+export { A as AccessDeniedError, a as AuthRequiredError, b as AuthResult, d as CloudflareAccessErrorCode, e as CloudflareAccessMiddlewareEnv, f as CloudflareAccessPayload, h as ConfigurationError, I as InvalidTokenError, _ as __clearJwksCache, i as isAccessDeniedError, j as isAuthRequiredError, k as isCloudflareAccessError, l as isConfigurationError, m as isInvalidTokenError, t as toAuthError } from '../../jwks-ChdyyS_L.mjs';
+export { g as getCloudflareAccessConfigFromEnv } from '../../config-D4O7DXNT.mjs';
+import { Schema, Context, Redacted, Effect, Layer, Option } from 'effect';
+import * as _effect_platform_HttpRouter from '@effect/platform/HttpRouter';
+import { HttpApiMiddleware, HttpApiSecurity, HttpServerRequest } from '@effect/platform';
+import * as effect_Either from 'effect/Either';
+import 'jose';
+
+/**
+ * Options for creating Cloudflare Access middleware
+ */
+interface CloudflareAccessMiddlewareOptions {
+    /** Cloudflare Access configuration */
+    accessConfig: CloudflareAccessConfig;
+    /** Optional email allowlist */
+    allowedEmails?: string[];
+    /** Skip validation in development */
+    skipInDev?: boolean;
+    /** Environment identifier */
+    environment?: string;
+}
+
+declare const Unauthorized_base: Schema.TaggedErrorClass<Unauthorized, "Unauthorized", {
+    readonly _tag: Schema.tag<"Unauthorized">;
+} & {
+    message: typeof Schema.String;
+    code: typeof Schema.String;
+}>;
+/**
+ * Unauthorized error schema for Effect Platform
+ */
+declare class Unauthorized extends Unauthorized_base {
+}
+declare const Forbidden_base: Schema.TaggedErrorClass<Forbidden, "Forbidden", {
+    readonly _tag: Schema.tag<"Forbidden">;
+} & {
+    message: typeof Schema.String;
+    email: typeof Schema.String;
+}>;
+/**
+ * Forbidden error schema for Effect Platform
+ */
+declare class Forbidden extends Forbidden_base {
+}
+
+declare const CurrentUser_base: Context.TagClass<CurrentUser, "cloudflare-access/CurrentUser", CloudflareAccessUser>;
+/**
+ * Context Tag for the authenticated user.
+ * Use this to access the current user in your handlers.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { CurrentUser } from "cloudflare-access/effect";
+ *
+ * const handler = Effect.gen(function* () {
+ *   const user = yield* CurrentUser;
+ *   console.log(`Hello ${user.email}`);
+ *   return user;
+ * });
+ * ```
+ */
+declare class CurrentUser extends CurrentUser_base {
+}
+
+declare const CloudflareAccessAuth_base: HttpApiMiddleware.TagClass.BaseSecurity<CloudflareAccessAuth, "CloudflareAccessAuth", {
+    readonly provides: typeof CurrentUser;
+    readonly failure: Schema.Union<[typeof Unauthorized, typeof Forbidden]>;
+    readonly security: {
+        readonly bearer: HttpApiSecurity.Bearer;
+    };
+}, {
+    readonly bearer: (_: Redacted.Redacted<string>) => Effect.Effect<CloudflareAccessUser, Unauthorized | Forbidden, _effect_platform_HttpRouter.HttpRouter.Provided>;
+}, {
+    readonly bearer: HttpApiSecurity.Bearer;
+}>;
+/**
+ * Cloudflare Access authentication middleware class.
+ *
+ * Use this class directly in your API middleware definitions.
+ *
+ * @example
+ * ```typescript
+ * import { HttpApi, HttpApiGroup, HttpApiEndpoint } from "@effect/platform";
+ * import { Schema, Effect, Layer } from "effect";
+ * import {
+ *   CloudflareAccessAuth,
+ *   CurrentUser,
+ *   makeCloudflareAccessLive,
+ *   Unauthorized,
+ *   Forbidden
+ * } from "cloudflare-access/effect";
+ *
+ * // Configure the middleware
+ * const CloudflareAccessLive = makeCloudflareAccessLive({
+ *   accessConfig: {
+ *     teamDomain: "https://yourteam.cloudflareaccess.com",
+ *     audTag: "your-audience-tag",
+ *   },
+ *   allowedEmails: ["admin@example.com"],
+ *   skipInDev: true,
+ *   environment: "dev",
+ * });
+ *
+ * // Define API with protected endpoints
+ * const User = Schema.Struct({ email: Schema.String });
+ *
+ * const api = HttpApi.make("api").add(
+ *   HttpApiGroup.make("users").add(
+ *     HttpApiEndpoint.get("profile", "/profile")
+ *       .addSuccess(User)
+ *       .middleware(CloudflareAccessAuth)
+ *   )
+ * );
+ *
+ * // Implement handlers with access to CurrentUser
+ * const UsersLive = HttpApiBuilder.group(api, "users", (handlers) =>
+ *   Effect.gen(function* () {
+ *     const user = yield* CurrentUser;
+ *     return handlers.handle("profile", () =>
+ *       Effect.succeed({ email: user.email })
+ *     );
+ *   })
+ * ).pipe(Layer.provide(CloudflareAccessLive));
+ * ```
+ */
+declare class CloudflareAccessAuth extends CloudflareAccessAuth_base {
+}
+/**
+ * Create a Layer that implements Cloudflare Access authentication.
+ *
+ * This layer validates the Cloudflare Access JWT token from the request
+ * and provides the authenticated user via the CurrentUser context.
+ *
+ * @param options Configuration for Cloudflare Access
+ * @returns Layer that provides authentication
+ */
+declare const makeCloudflareAccessLive: (options: CloudflareAccessMiddlewareOptions) => Layer.Layer<CloudflareAccessAuth, never, never>;
+
+/**
+ * Extract Cloudflare Access token from request headers.
+ * Looks for CF-Access-JWT-Assertion header.
+ *
+ * @param request HTTP server request
+ * @returns Option with token if present
+ */
+declare const extractToken: (request: HttpServerRequest.HttpServerRequest) => Option.Option<string>;
+/**
+ * Authenticate using the CF-Access-JWT-Assertion header directly.
+ * This bypasses the HttpApiSecurity bearer token pattern.
+ *
+ * @param request HTTP server request
+ * @param options Authentication options
+ * @returns Effect with authenticated user or error
+ */
+declare const authenticateRequest: (request: HttpServerRequest.HttpServerRequest, options: CloudflareAccessMiddlewareOptions) => Effect.Effect<CloudflareAccessUser, CloudflareAccessError, never>;
+/**
+ * Get user as Option (returns None on auth failure)
+ */
+declare const getUser: (request: HttpServerRequest.HttpServerRequest, options: CloudflareAccessMiddlewareOptions) => Effect.Effect<Option.Option<CloudflareAccessUser>, never, never>;
+/**
+ * Authenticate and return Either (for explicit error handling)
+ */
+declare const authenticateEither: (request: HttpServerRequest.HttpServerRequest, options: CloudflareAccessMiddlewareOptions) => Effect.Effect<effect_Either.Either<CloudflareAccessUser, CloudflareAccessError>, never, never>;
+
+export { CloudflareAccessAuth, CloudflareAccessConfig, CloudflareAccessError, type CloudflareAccessMiddlewareOptions, CloudflareAccessUser, CurrentUser, Forbidden, Unauthorized, authenticateEither, authenticateRequest, extractToken, getUser, makeCloudflareAccessLive };