cloudflare-access 1.0.0

package/examples/custom-handlers.ts

@@ -0,0 +1,85 @@
+/**
+ * Custom Error Handlers Example
+ *
+ * Customize the response when authentication fails or access is denied.
+ */
+
+import { Hono } from "hono";
+import {
+  createCloudflareAccessAuth,
+  getCloudflareAccessConfigFromBindings,
+  type CloudflareAccessUser,
+} from "cloudflare-access/hono";
+
+interface Bindings {
+  CF_ACCESS_TEAM_DOMAIN: string;
+  CF_ACCESS_AUD: string;
+  ENVIRONMENT: string;
+}
+
+interface Variables {
+  user?: CloudflareAccessUser;
+}
+
+const app = new Hono<{ Bindings: Bindings; Variables: Variables }>();
+
+app.use(
+  createCloudflareAccessAuth({
+    accessConfig: getCloudflareAccessConfigFromBindings,
+    allowedEmails: ["admin@example.com"],
+
+    // Custom unauthorized response
+    onUnauthorized: (c, reason) => {
+      return c.json(
+        {
+          error: "Authentication Required",
+          message: "You must sign in to access this resource",
+          reason,
+          documentation: "https://docs.example.com/auth",
+          support: "support@example.com",
+        },
+        401,
+      );
+    },
+
+    // Custom forbidden response
+    onForbidden: (c, email) => {
+      return c.json(
+        {
+          error: "Access Denied",
+          message: `Sorry ${email}, you don't have permission to access this resource`,
+          requiredRole: "admin",
+          currentUser: email,
+          upgradeRequestUrl: "https://example.com/request-access",
+        },
+        403,
+      );
+    },
+
+    // Skip auth for these paths
+    excludePaths: ["/api/public", "/health", "/docs"],
+  }),
+);
+
+// Public routes (no auth required)
+app.get("/api/public", (c) => {
+  return c.json({
+    message: "This is public data",
+    timestamp: new Date().toISOString(),
+  });
+});
+
+app.get("/health", (c) => {
+  return c.json({ status: "healthy" });
+});
+
+// Protected routes
+app.get("/api/private", (c) => {
+  const user = c.get("user");
+  return c.json({
+    message: "Private data",
+    accessedBy: user?.email,
+  });
+});
+
+export default app;

package/examples/effect/http-server.ts

@@ -0,0 +1,205 @@
+import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup } from "@effect/platform";
+import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
+import { Effect, Layer, Schema } from "effect";
+import { createServer } from "node:http";
+import {
+  CloudflareAccessAuth,
+  makeCloudflareAccessLive,
+  CurrentUser,
+  Unauthorized,
+  Forbidden,
+} from "cloudflare-access/effect";
+
+// ============================================================================
+// 1. SCHEMAS
+// ============================================================================
+
+/**
+ * Schema for authenticated user
+ */
+const User = Schema.Struct({
+  email: Schema.String,
+  userId: Schema.optional(Schema.String),
+  country: Schema.optional(Schema.String),
+});
+
+/**
+ * Schema for user profile response
+ */
+const UserProfile = Schema.Struct({
+  email: Schema.String,
+  userId: Schema.optional(Schema.String),
+  country: Schema.optional(Schema.String),
+  preferences: Schema.Struct({
+    theme: Schema.String,
+    notifications: Schema.Boolean,
+  }),
+  lastLogin: Schema.String,
+});
+
+/**
+ * Schema for admin dashboard response
+ */
+const AdminStats = Schema.Struct({
+  totalUsers: Schema.Number,
+  activeSessions: Schema.Number,
+  apiRequests: Schema.Number,
+  recentActivity: Schema.Array(Schema.String),
+});
+
+// ============================================================================
+// 2. API DEFINITION
+// ============================================================================
+
+/**
+ * Users API Group - Protected endpoints
+ */
+const UsersGroup = HttpApiGroup.make("users")
+  .add(
+    HttpApiEndpoint.get("getProfile", "/users/me")
+      .addSuccess(UserProfile)
+      .addError(Unauthorized, { status: 401 })
+      .addError(Forbidden, { status: 403 }),
+  )
+  .middleware(CloudflareAccessAuth);
+
+/**
+ * Admin API Group - Admin-only endpoints
+ */
+const AdminGroup = HttpApiGroup.make("admin")
+  .add(
+    HttpApiEndpoint.get("getStats", "/admin/stats")
+      .addSuccess(AdminStats)
+      .addError(Unauthorized, { status: 401 })
+      .addError(Forbidden, { status: 403 }),
+  )
+  .add(
+    HttpApiEndpoint.get("getUsers", "/admin/users")
+      .addSuccess(Schema.Array(User))
+      .addError(Unauthorized, { status: 401 })
+      .addError(Forbidden, { status: 403 }),
+  )
+  .middleware(CloudflareAccessAuth);
+
+/**
+ * Public API Group - No authentication required
+ */
+const PublicGroup = HttpApiGroup.make("public").add(
+  HttpApiEndpoint.get("health", "/health").addSuccess(Schema.Struct({ status: Schema.String })),
+);
+
+/**
+ * Main API definition
+ */
+const Api = HttpApi.make("CloudflareAccessApi").add(PublicGroup).add(UsersGroup).add(AdminGroup);
+
+// ============================================================================
+// 3. IMPLEMENTATION
+// ============================================================================
+
+/**
+ * Authentication layer - provides the middleware implementation
+ */
+const CloudflareAccessLive = makeCloudflareAccessLive({
+  accessConfig: {
+    teamDomain: "https://yourteam.cloudflareaccess.com",
+    audTag: "your-audience-tag",
+  },
+  allowedEmails: ["admin@example.com", "user@example.com"],
+  skipInDev: true,
+  environment: "dev",
+});
+
+/**
+ * Implement the Users group
+ */
+const UsersLive = HttpApiBuilder.group(Api, "users", (handlers) =>
+  handlers.handle("getProfile", () =>
+    Effect.gen(function* () {
+      const user = yield* CurrentUser;
+      return {
+        email: user.email,
+        userId: user.userId,
+        country: user.country,
+        preferences: {
+          theme: "dark",
+          notifications: true,
+        },
+        lastLogin: new Date().toISOString(),
+      };
+    }),
+  ),
+).pipe(Layer.provide(CloudflareAccessLive));
+
+/**
+ * Implement the Admin group with admin-only access
+ */
+const AdminLive = HttpApiBuilder.group(Api, "admin", (handlers) =>
+  handlers
+    .handle("getStats", () =>
+      Effect.gen(function* () {
+        const user = yield* CurrentUser;
+        const allowedAdmins = ["admin@example.com"];
+
+        if (!allowedAdmins.includes(user.email)) {
+          return yield* Effect.fail(
+            new Forbidden({
+              message: "Admin access required",
+              email: user.email,
+            }),
+          );
+        }
+
+        return {
+          totalUsers: 1500,
+          activeSessions: 342,
+          apiRequests: 125000,
+          recentActivity: ["User login", "Config update"],
+        };
+      }),
+    )
+    .handle("getUsers", () =>
+      Effect.gen(function* () {
+        const user = yield* CurrentUser;
+        const allowedAdmins = ["admin@example.com"];
+
+        if (!allowedAdmins.includes(user.email)) {
+          return yield* Effect.fail(
+            new Forbidden({
+              message: "Admin access required",
+              email: user.email,
+            }),
+          );
+        }
+
+        return [
+          { email: "user1@example.com", userId: "1" },
+          { email: "user2@example.com", userId: "2" },
+        ];
+      }),
+    ),
+).pipe(Layer.provide(CloudflareAccessLive));
+
+/**
+ * Implement the Public group (no auth required)
+ */
+const PublicLive = HttpApiBuilder.group(Api, "public", (handlers) =>
+  handlers.handle("health", () => Effect.succeed({ status: "healthy" })),
+);
+
+// ============================================================================
+// 4. SERVER SETUP
+// ============================================================================
+
+const ApiLive = HttpApiBuilder.api(Api).pipe(
+  Layer.provide(UsersLive),
+  Layer.provide(AdminLive),
+  Layer.provide(PublicLive),
+);
+
+HttpApiBuilder.serve().pipe(
+  Layer.provide(ApiLive),
+  Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })),
+  Layer.launch,
+  NodeRuntime.runMain,
+);

package/examples/email-allowlist.ts

@@ -0,0 +1,50 @@
+/**
+ * Email Allowlist Example
+ *
+ * Restrict access to specific email addresses. This provides an additional
+ * layer of security beyond Cloudflare Access policies.
+ */
+
+import { Hono } from "hono";
+import {
+  createCloudflareAccessAuth,
+  getCloudflareAccessConfigFromBindings,
+  type CloudflareAccessUser,
+} from "cloudflare-access/hono";
+
+interface Bindings {
+  CF_ACCESS_TEAM_DOMAIN: string;
+  CF_ACCESS_AUD: string;
+}
+
+interface Variables {
+  user?: CloudflareAccessUser;
+}
+
+const app = new Hono<{ Bindings: Bindings; Variables: Variables }>();
+
+// Only allow specific emails
+const ALLOWED_EMAILS = ["admin@company.com", "ceo@company.com", "cto@company.com"];
+
+app.use(
+  createCloudflareAccessAuth({
+    accessConfig: getCloudflareAccessConfigFromBindings,
+    allowedEmails: ALLOWED_EMAILS,
+  }),
+);
+
+// Only accessible to allowed emails
+app.get("/api/sensitive-data", (c) => {
+  const user = c.get("user");
+
+  return c.json({
+    message: "Access granted to sensitive data",
+    user: user?.email,
+    data: {
+      revenue: 1000000,
+      projections: "classified",
+    },
+  });
+});
+
+export default app;

package/examples/express/basic.ts

@@ -0,0 +1,26 @@
+import express from "express";
+import { cloudflareAccessAuth } from "cloudflare-access/express";
+
+const app = express();
+
+// Use Cloudflare Access middleware
+app.use(
+  cloudflareAccessAuth({
+    accessConfig: {
+      teamDomain: "https://yourteam.cloudflareaccess.com",
+      audTag: "your-audience-tag",
+    },
+  }),
+);
+
+app.get("/protected", (req, res) => {
+  res.json({
+    message: `Hello ${req.user?.email}`,
+    userId: req.user?.userId,
+    country: req.user?.country,
+  });
+});
+
+app.listen(3000, () => {
+  console.log("Server running on http://localhost:3000");
+});

package/examples/fastify/basic.ts

@@ -0,0 +1,24 @@
+import fastify from "fastify";
+import { cloudflareAccessPlugin } from "cloudflare-access/fastify";
+
+const app = fastify();
+
+// Register Cloudflare Access plugin
+app.register(cloudflareAccessPlugin, {
+  accessConfig: {
+    teamDomain: "https://yourteam.cloudflareaccess.com",
+    audTag: "your-audience-tag",
+  },
+});
+
+app.get("/protected", async (request, _reply) => {
+  return {
+    message: `Hello ${request.user?.email}`,
+    userId: request.user?.userId,
+    country: request.user?.country,
+  };
+});
+
+app.listen({ port: 3000 }, () => {
+  console.log("Server running on http://localhost:3000");
+});

package/examples/hono/basic.ts

@@ -0,0 +1,26 @@
+import { Hono } from "hono";
+import {
+  createCloudflareAccessAuth,
+  getCloudflareAccessConfigFromBindings,
+  type CloudflareAccessVariables,
+} from "cloudflare-access/hono";
+
+const app = new Hono<{ Variables: CloudflareAccessVariables }>();
+
+// Use with Cloudflare Access bindings
+app.use(
+  createCloudflareAccessAuth({
+    accessConfig: getCloudflareAccessConfigFromBindings,
+  }),
+);
+
+app.get("/protected", (c) => {
+  const user = c.get("user");
+  return c.json({
+    message: `Hello ${user?.email}`,
+    userId: user?.userId,
+    country: user?.country,
+  });
+});
+
+export default app;

package/examples/hono-router.ts

@@ -0,0 +1,74 @@
+/**
+ * Hono Router Example
+ *
+ * Using the middleware with Hono's router pattern for modular APIs.
+ */
+
+import { Hono } from "hono";
+import {
+  createCloudflareAccessAuth,
+  getCloudflareAccessConfigFromBindings,
+  type CloudflareAccessUser,
+} from "cloudflare-access/hono";
+
+interface Bindings {
+  CF_ACCESS_TEAM_DOMAIN: string;
+  CF_ACCESS_AUD: string;
+}
+
+// Extend Hono's variables type
+interface Variables {
+  user?: CloudflareAccessUser;
+}
+
+// Create typed Hono app
+const app = new Hono<{ Bindings: Bindings; Variables: Variables }>();
+
+// API v1 routes
+const apiV1 = new Hono<{ Bindings: Bindings; Variables: Variables }>();
+
+apiV1.use(
+  createCloudflareAccessAuth({
+    accessConfig: getCloudflareAccessConfigFromBindings,
+  }),
+);
+
+apiV1.get("/users/me", (c) => {
+  const user = c.get("user");
+  return c.json({
+    id: user?.userId,
+    email: user?.email,
+    country: user?.country,
+  });
+});
+
+apiV1.get("/dashboard", (c) => {
+  const user = c.get("user");
+  return c.json({
+    welcome: `Hello ${user?.email}`,
+    lastLogin: new Date().toISOString(),
+  });
+});
+
+// Public routes
+const publicRouter = new Hono();
+
+publicRouter.get("/status", (c) => {
+  return c.json({
+    status: "operational",
+    version: "1.0.0",
+  });
+});
+
+// Mount routers
+app.route("/api/v1", apiV1);
+app.route("/public", publicRouter);
+
+export default app;
+
+/*
+Route structure:
+- GET /api/v1/users/me     -> Protected (requires auth)
+- GET /api/v1/dashboard    -> Protected (requires auth)
+- GET /public/status       -> Public (no auth)
+*/

package/examples/nestjs/basic.ts

@@ -0,0 +1,39 @@
+import { Controller, Get, Module, Req } from "@nestjs/common";
+import type { Request } from "express";
+import { CloudflareAccessGuard, Public } from "cloudflare-access/nestjs";
+import { APP_GUARD } from "@nestjs/core";
+
+@Controller("api")
+export class ApiController {
+  @Get("protected")
+  getProtected(@Req() req: Request) {
+    return {
+      message: `Hello ${req.user?.email}`,
+      userId: req.user?.userId,
+      country: req.user?.country,
+    };
+  }
+
+  @Public()
+  @Get("public")
+  getPublic() {
+    return { message: "This is a public endpoint" };
+  }
+}
+
+@Module({
+  controllers: [ApiController],
+  providers: [
+    {
+      provide: APP_GUARD,
+      useFactory: () =>
+        new CloudflareAccessGuard({
+          accessConfig: {
+            teamDomain: "https://yourteam.cloudflareaccess.com",
+            audTag: "your-audience-tag",
+          },
+        }),
+    },
+  ],
+})
+export class AppModule {}

package/examples/skip-dev-mode.ts

@@ -0,0 +1,89 @@
+/**
+ * Skip Dev Mode Example
+ *
+ * Skip authentication during local development while still
+ * requiring it in production.
+ */
+
+import { Hono } from "hono";
+import {
+  createCloudflareAccessAuth,
+  getCloudflareAccessConfigFromBindings,
+  type CloudflareAccessUser,
+} from "cloudflare-access/hono";
+
+interface Bindings {
+  CF_ACCESS_TEAM_DOMAIN: string;
+  CF_ACCESS_AUD: string;
+  ENVIRONMENT: "dev" | "staging" | "prod";
+}
+
+interface Variables {
+  user?: CloudflareAccessUser;
+}
+
+const app = new Hono<{ Bindings: Bindings; Variables: Variables }>();
+
+app.use(
+  createCloudflareAccessAuth({
+    accessConfig: getCloudflareAccessConfigFromBindings,
+
+    // When true, auth is skipped for localhost/127.0.0.1
+    // when ENVIRONMENT is not "prod"
+    skipInDev: true,
+
+    // Also exclude specific paths from auth
+    excludePaths: ["/api/public", "/health"],
+  }),
+);
+
+// This route:
+// - Requires auth in production
+// - Skips auth on localhost in dev/staging
+app.get("/api/private", (c) => {
+  const user = c.get("user");
+  const env = c.env.ENVIRONMENT;
+
+  // In dev mode, user might be undefined since auth is skipped
+  if (!user) {
+    return c.json({
+      message: "Development mode - auth skipped",
+      environment: env,
+      note: "In production, this would require authentication",
+    });
+  }
+
+  return c.json({
+    message: "Production mode - authenticated",
+    environment: env,
+    user: user?.email,
+  });
+});
+
+// Always public
+app.get("/health", (c) => {
+  return c.json({ status: "ok" });
+});
+
+export default app;
+
+/*
+## Development workflow:
+
+1. Local development (no auth required):
+   ```bash
+   ENVIRONMENT=dev bun run dev
+   curl http://localhost:8787/api/private
+   # Returns: { message: "Development mode..." }
+   ```
+
+2. Production (auth required):
+   ```bash
+   # Deployed to Cloudflare with ENVIRONMENT=prod
+   curl https://api.example.com/api/private
+   # Returns: 401 Unauthorized
+
+   curl -H "CF-Access-JWT-Assertion: <token>" https://api.example.com/api/private
+   # Returns: { message: "Production mode...", user: "..." }
+   ```
+*/