cloudflare-access 1.0.0

package/dist/jwks-ChdyyS_L.d.mts

@@ -0,0 +1,173 @@
+import { JWTPayload, createRemoteJWKSet } from 'jose';
+
+/**
+ * Cloudflare Access JWT payload with additional claims
+ */
+interface CloudflareAccessPayload extends JWTPayload {
+    /** User's email address */
+    email?: string;
+    /** Token type */
+    type?: string;
+    /** Identity nonce for additional verification */
+    identity_nonce?: string;
+    /** User's country */
+    country?: string;
+}
+/**
+ * Cloudflare Access configuration
+ */
+interface CloudflareAccessConfig {
+    /** Exact Cloudflare Access issuer domain, e.g. https://myteam.cloudflareaccess.com */
+    teamDomain: string;
+    /** Exact Access application audience tag */
+    audTag: string;
+}
+/**
+ * User information extracted from Cloudflare Access token
+ */
+interface CloudflareAccessUser {
+    email: string;
+    userId?: string;
+    country?: string;
+}
+/**
+ * Expected environment bindings for Cloudflare Access
+ */
+interface CloudflareAccessMiddlewareEnv {
+    CF_ACCESS_TEAM_DOMAIN?: string;
+    CF_ACCESS_AUD?: string;
+    ENVIRONMENT?: string;
+}
+/**
+ * Error codes for Cloudflare Access authentication
+ */
+declare const CloudflareAccessErrorCode: {
+    /** Missing or invalid authentication token */
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+    /** Token validation failed (expired, wrong signature, etc.) */
+    readonly INVALID_TOKEN: "INVALID_TOKEN";
+    /** User email not in allowlist */
+    readonly ACCESS_DENIED: "ACCESS_DENIED";
+    /** Invalid team domain configuration */
+    readonly INVALID_TEAM_DOMAIN: "INVALID_TEAM_DOMAIN";
+    /** Missing audience tag configuration */
+    readonly MISSING_AUDIENCE_TAG: "MISSING_AUDIENCE_TAG";
+    /** Missing environment configuration */
+    readonly MISSING_CONFIG: "MISSING_CONFIG";
+    /** JWKS fetch failed */
+    readonly JWKS_FETCH_ERROR: "JWKS_FETCH_ERROR";
+};
+type CloudflareAccessErrorCode = (typeof CloudflareAccessErrorCode)[keyof typeof CloudflareAccessErrorCode];
+/**
+ * Rich authentication error with actionable information
+ */
+interface AuthError {
+    code: CloudflareAccessErrorCode;
+    message: string;
+    why: string;
+    fix: string;
+    context?: Record<string, unknown>;
+}
+/**
+ * Authentication result
+ */
+type AuthResult = {
+    success: true;
+    user: CloudflareAccessUser | null;
+    error?: never;
+} | {
+    success: false;
+    user?: CloudflareAccessUser | null;
+    error: AuthError;
+};
+
+/**
+ * Base error class for Cloudflare Access authentication errors
+ */
+declare class CloudflareAccessError extends Error {
+    readonly code: CloudflareAccessErrorCode;
+    readonly context?: Record<string, unknown>;
+    readonly requestUrl?: string;
+    readonly timestamp: string;
+    constructor(code: CloudflareAccessErrorCode, message: string, options?: {
+        cause?: Error;
+        context?: Record<string, unknown>;
+        requestUrl?: string;
+    });
+    /**
+     * Get a user-friendly error message with fix instructions
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Get fix instructions based on error code
+     */
+    private getFixInstructions;
+}
+/**
+ * Error thrown when authentication is required but missing/invalid
+ */
+declare class AuthRequiredError extends CloudflareAccessError {
+    constructor(options?: {
+        requestUrl?: string;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Error thrown when token validation fails
+ */
+declare class InvalidTokenError extends CloudflareAccessError {
+    readonly reason: string;
+    constructor(reason: string, options?: {
+        requestUrl?: string;
+    });
+}
+/**
+ * Error thrown when user is not in email allowlist
+ */
+declare class AccessDeniedError extends CloudflareAccessError {
+    readonly email: string;
+    constructor(email: string, options?: {
+        requestUrl?: string;
+        allowedEmails?: string[];
+    });
+}
+/**
+ * Error thrown when configuration is invalid or missing
+ */
+declare class ConfigurationError extends CloudflareAccessError {
+    constructor(message: string, options?: {
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Type guard to check if error is a CloudflareAccessError
+ */
+declare function isCloudflareAccessError(error: unknown): error is CloudflareAccessError;
+/**
+ * Type guard for specific error types
+ */
+declare function isAuthRequiredError(error: unknown): error is AuthRequiredError;
+declare function isInvalidTokenError(error: unknown): error is InvalidTokenError;
+declare function isAccessDeniedError(error: unknown): error is AccessDeniedError;
+declare function isConfigurationError(error: unknown): error is ConfigurationError;
+/**
+ * Convert unknown error to CloudflareAccessError
+ */
+declare function toAuthError(error: unknown): CloudflareAccessError;
+
+/**
+ * Clear the JWKS cache. Useful for testing.
+ * @internal
+ */
+declare function __clearJwksCache(): void;
+/**
+ * Get or create cached JWKS for a team domain
+ */
+declare function getRemoteJwks(teamDomain: string): ReturnType<typeof createRemoteJWKSet>;
+/**
+ * Check if request is from local development
+ */
+declare function isLocalDevelopmentRequest(url: string): boolean;
+
+export { AccessDeniedError as A, type CloudflareAccessConfig as C, InvalidTokenError as I, __clearJwksCache as _, AuthRequiredError as a, type AuthResult as b, CloudflareAccessError as c, CloudflareAccessErrorCode as d, type CloudflareAccessMiddlewareEnv as e, type CloudflareAccessPayload as f, type CloudflareAccessUser as g, ConfigurationError as h, isAccessDeniedError as i, isAuthRequiredError as j, isCloudflareAccessError as k, isConfigurationError as l, isInvalidTokenError as m, type AuthError as n, getRemoteJwks as o, isLocalDevelopmentRequest as p, toAuthError as t };

package/dist/jwks-ChdyyS_L.d.ts

@@ -0,0 +1,173 @@
+import { JWTPayload, createRemoteJWKSet } from 'jose';
+
+/**
+ * Cloudflare Access JWT payload with additional claims
+ */
+interface CloudflareAccessPayload extends JWTPayload {
+    /** User's email address */
+    email?: string;
+    /** Token type */
+    type?: string;
+    /** Identity nonce for additional verification */
+    identity_nonce?: string;
+    /** User's country */
+    country?: string;
+}
+/**
+ * Cloudflare Access configuration
+ */
+interface CloudflareAccessConfig {
+    /** Exact Cloudflare Access issuer domain, e.g. https://myteam.cloudflareaccess.com */
+    teamDomain: string;
+    /** Exact Access application audience tag */
+    audTag: string;
+}
+/**
+ * User information extracted from Cloudflare Access token
+ */
+interface CloudflareAccessUser {
+    email: string;
+    userId?: string;
+    country?: string;
+}
+/**
+ * Expected environment bindings for Cloudflare Access
+ */
+interface CloudflareAccessMiddlewareEnv {
+    CF_ACCESS_TEAM_DOMAIN?: string;
+    CF_ACCESS_AUD?: string;
+    ENVIRONMENT?: string;
+}
+/**
+ * Error codes for Cloudflare Access authentication
+ */
+declare const CloudflareAccessErrorCode: {
+    /** Missing or invalid authentication token */
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+    /** Token validation failed (expired, wrong signature, etc.) */
+    readonly INVALID_TOKEN: "INVALID_TOKEN";
+    /** User email not in allowlist */
+    readonly ACCESS_DENIED: "ACCESS_DENIED";
+    /** Invalid team domain configuration */
+    readonly INVALID_TEAM_DOMAIN: "INVALID_TEAM_DOMAIN";
+    /** Missing audience tag configuration */
+    readonly MISSING_AUDIENCE_TAG: "MISSING_AUDIENCE_TAG";
+    /** Missing environment configuration */
+    readonly MISSING_CONFIG: "MISSING_CONFIG";
+    /** JWKS fetch failed */
+    readonly JWKS_FETCH_ERROR: "JWKS_FETCH_ERROR";
+};
+type CloudflareAccessErrorCode = (typeof CloudflareAccessErrorCode)[keyof typeof CloudflareAccessErrorCode];
+/**
+ * Rich authentication error with actionable information
+ */
+interface AuthError {
+    code: CloudflareAccessErrorCode;
+    message: string;
+    why: string;
+    fix: string;
+    context?: Record<string, unknown>;
+}
+/**
+ * Authentication result
+ */
+type AuthResult = {
+    success: true;
+    user: CloudflareAccessUser | null;
+    error?: never;
+} | {
+    success: false;
+    user?: CloudflareAccessUser | null;
+    error: AuthError;
+};
+
+/**
+ * Base error class for Cloudflare Access authentication errors
+ */
+declare class CloudflareAccessError extends Error {
+    readonly code: CloudflareAccessErrorCode;
+    readonly context?: Record<string, unknown>;
+    readonly requestUrl?: string;
+    readonly timestamp: string;
+    constructor(code: CloudflareAccessErrorCode, message: string, options?: {
+        cause?: Error;
+        context?: Record<string, unknown>;
+        requestUrl?: string;
+    });
+    /**
+     * Get a user-friendly error message with fix instructions
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Get fix instructions based on error code
+     */
+    private getFixInstructions;
+}
+/**
+ * Error thrown when authentication is required but missing/invalid
+ */
+declare class AuthRequiredError extends CloudflareAccessError {
+    constructor(options?: {
+        requestUrl?: string;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Error thrown when token validation fails
+ */
+declare class InvalidTokenError extends CloudflareAccessError {
+    readonly reason: string;
+    constructor(reason: string, options?: {
+        requestUrl?: string;
+    });
+}
+/**
+ * Error thrown when user is not in email allowlist
+ */
+declare class AccessDeniedError extends CloudflareAccessError {
+    readonly email: string;
+    constructor(email: string, options?: {
+        requestUrl?: string;
+        allowedEmails?: string[];
+    });
+}
+/**
+ * Error thrown when configuration is invalid or missing
+ */
+declare class ConfigurationError extends CloudflareAccessError {
+    constructor(message: string, options?: {
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Type guard to check if error is a CloudflareAccessError
+ */
+declare function isCloudflareAccessError(error: unknown): error is CloudflareAccessError;
+/**
+ * Type guard for specific error types
+ */
+declare function isAuthRequiredError(error: unknown): error is AuthRequiredError;
+declare function isInvalidTokenError(error: unknown): error is InvalidTokenError;
+declare function isAccessDeniedError(error: unknown): error is AccessDeniedError;
+declare function isConfigurationError(error: unknown): error is ConfigurationError;
+/**
+ * Convert unknown error to CloudflareAccessError
+ */
+declare function toAuthError(error: unknown): CloudflareAccessError;
+
+/**
+ * Clear the JWKS cache. Useful for testing.
+ * @internal
+ */
+declare function __clearJwksCache(): void;
+/**
+ * Get or create cached JWKS for a team domain
+ */
+declare function getRemoteJwks(teamDomain: string): ReturnType<typeof createRemoteJWKSet>;
+/**
+ * Check if request is from local development
+ */
+declare function isLocalDevelopmentRequest(url: string): boolean;
+
+export { AccessDeniedError as A, type CloudflareAccessConfig as C, InvalidTokenError as I, __clearJwksCache as _, AuthRequiredError as a, type AuthResult as b, CloudflareAccessError as c, CloudflareAccessErrorCode as d, type CloudflareAccessMiddlewareEnv as e, type CloudflareAccessPayload as f, type CloudflareAccessUser as g, ConfigurationError as h, isAccessDeniedError as i, isAuthRequiredError as j, isCloudflareAccessError as k, isConfigurationError as l, isInvalidTokenError as m, type AuthError as n, getRemoteJwks as o, isLocalDevelopmentRequest as p, toAuthError as t };

package/dist/middleware-BDl6jUCu.d.mts

@@ -0,0 +1,83 @@
+import * as hono from 'hono';
+import { Context, MiddlewareHandler } from 'hono';
+import { C as CloudflareAccessConfig, g as CloudflareAccessUser, e as CloudflareAccessMiddlewareEnv } from './jwks-ChdyyS_L.mjs';
+
+/**
+ * Extended Hono variables type
+ */
+interface CloudflareAccessVariables {
+    /** Authenticated user from Cloudflare Access */
+    user?: CloudflareAccessUser;
+}
+/**
+ * Helper type to create a typed Hono app with Cloudflare Access variables
+ */
+type CloudflareAccessHono = hono.Hono<{
+    Variables: CloudflareAccessVariables;
+}>;
+/**
+ * Configuration resolver type - can be static config or a function
+ */
+type CloudflareAccessConfigResolver$1 = CloudflareAccessConfig | ((c: Context) => CloudflareAccessConfig);
+/**
+ * Options for creating Cloudflare Access authentication middleware for Hono
+ */
+interface CloudflareAccessAuthOptions {
+    /**
+     * Exact Cloudflare Access config or a resolver that reads it from bindings.
+     * Both `teamDomain` and `audTag` are required for secure validation.
+     */
+    accessConfig: CloudflareAccessConfigResolver$1;
+    /** Optional email allowlist. Access policy should still be configured at Cloudflare. */
+    allowedEmails?: string[];
+    /** Custom unauthorized handler */
+    onUnauthorized?: (c: Context, reason: string) => Response | Promise<Response>;
+    /** Custom forbidden handler */
+    onForbidden?: (c: Context, email: string) => Response | Promise<Response>;
+    /** Paths to exclude from auth check */
+    excludePaths?: string[];
+    /** Whether to skip JWT validation outside production */
+    skipInDev?: boolean;
+}
+
+/**
+ * Configuration resolver type - can be static config or a function
+ */
+type CloudflareAccessConfigResolver = CloudflareAccessConfig | ((c: Context) => CloudflareAccessConfig);
+/**
+ * Get Cloudflare Access configuration from Hono context bindings
+ */
+declare function getCloudflareAccessConfigFromBindings(c: Context<{
+    Bindings: CloudflareAccessMiddlewareEnv;
+}>): CloudflareAccessConfig;
+/**
+ * Get access configuration from resolver
+ */
+declare function resolveConfig(resolver: CloudflareAccessConfigResolver, c: Context): CloudflareAccessConfig;
+
+/**
+ * Creates secure Cloudflare Access authentication middleware for Hono.
+ *
+ * @param options - Configuration options
+ * @returns Hono middleware handler
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { createCloudflareAccessAuth, getCloudflareAccessConfigFromBindings } from 'cloudflare-access/adapters/hono';
+ *
+ * const app = new Hono();
+ *
+ * app.use(createCloudflareAccessAuth({
+ *   accessConfig: getCloudflareAccessConfigFromBindings,
+ * }));
+ *
+ * app.get('/protected', (c) => {
+ *   const user = c.get('user');
+ *   return c.json({ email: user?.email });
+ * });
+ * ```
+ */
+declare function createCloudflareAccessAuth(options: CloudflareAccessAuthOptions): MiddlewareHandler;
+
+export { type CloudflareAccessAuthOptions as C, type CloudflareAccessConfigResolver$1 as a, type CloudflareAccessHono as b, type CloudflareAccessVariables as c, createCloudflareAccessAuth as d, getCloudflareAccessConfigFromBindings as g, resolveConfig as r };

package/dist/middleware-CgFsjM20.d.ts

@@ -0,0 +1,83 @@
+import * as hono from 'hono';
+import { Context, MiddlewareHandler } from 'hono';
+import { C as CloudflareAccessConfig, g as CloudflareAccessUser, e as CloudflareAccessMiddlewareEnv } from './jwks-ChdyyS_L.js';
+
+/**
+ * Extended Hono variables type
+ */
+interface CloudflareAccessVariables {
+    /** Authenticated user from Cloudflare Access */
+    user?: CloudflareAccessUser;
+}
+/**
+ * Helper type to create a typed Hono app with Cloudflare Access variables
+ */
+type CloudflareAccessHono = hono.Hono<{
+    Variables: CloudflareAccessVariables;
+}>;
+/**
+ * Configuration resolver type - can be static config or a function
+ */
+type CloudflareAccessConfigResolver$1 = CloudflareAccessConfig | ((c: Context) => CloudflareAccessConfig);
+/**
+ * Options for creating Cloudflare Access authentication middleware for Hono
+ */
+interface CloudflareAccessAuthOptions {
+    /**
+     * Exact Cloudflare Access config or a resolver that reads it from bindings.
+     * Both `teamDomain` and `audTag` are required for secure validation.
+     */
+    accessConfig: CloudflareAccessConfigResolver$1;
+    /** Optional email allowlist. Access policy should still be configured at Cloudflare. */
+    allowedEmails?: string[];
+    /** Custom unauthorized handler */
+    onUnauthorized?: (c: Context, reason: string) => Response | Promise<Response>;
+    /** Custom forbidden handler */
+    onForbidden?: (c: Context, email: string) => Response | Promise<Response>;
+    /** Paths to exclude from auth check */
+    excludePaths?: string[];
+    /** Whether to skip JWT validation outside production */
+    skipInDev?: boolean;
+}
+
+/**
+ * Configuration resolver type - can be static config or a function
+ */
+type CloudflareAccessConfigResolver = CloudflareAccessConfig | ((c: Context) => CloudflareAccessConfig);
+/**
+ * Get Cloudflare Access configuration from Hono context bindings
+ */
+declare function getCloudflareAccessConfigFromBindings(c: Context<{
+    Bindings: CloudflareAccessMiddlewareEnv;
+}>): CloudflareAccessConfig;
+/**
+ * Get access configuration from resolver
+ */
+declare function resolveConfig(resolver: CloudflareAccessConfigResolver, c: Context): CloudflareAccessConfig;
+
+/**
+ * Creates secure Cloudflare Access authentication middleware for Hono.
+ *
+ * @param options - Configuration options
+ * @returns Hono middleware handler
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { createCloudflareAccessAuth, getCloudflareAccessConfigFromBindings } from 'cloudflare-access/adapters/hono';
+ *
+ * const app = new Hono();
+ *
+ * app.use(createCloudflareAccessAuth({
+ *   accessConfig: getCloudflareAccessConfigFromBindings,
+ * }));
+ *
+ * app.get('/protected', (c) => {
+ *   const user = c.get('user');
+ *   return c.json({ email: user?.email });
+ * });
+ * ```
+ */
+declare function createCloudflareAccessAuth(options: CloudflareAccessAuthOptions): MiddlewareHandler;
+
+export { type CloudflareAccessAuthOptions as C, type CloudflareAccessConfigResolver$1 as a, type CloudflareAccessHono as b, type CloudflareAccessVariables as c, createCloudflareAccessAuth as d, getCloudflareAccessConfigFromBindings as g, resolveConfig as r };

package/examples/basic.ts

@@ -0,0 +1,52 @@
+/**
+ * Basic Example - Static Configuration
+ *
+ * This example shows the simplest usage of the middleware with
+ * hardcoded configuration. Not recommended for production use.
+ */
+
+import { Hono } from "hono";
+import { createCloudflareAccessAuth, type CloudflareAccessHono } from "cloudflare-access/hono";
+
+// Use the helper type for proper typing
+const app: CloudflareAccessHono = new Hono();
+
+// Apply middleware with static configuration
+app.use(
+  createCloudflareAccessAuth({
+    accessConfig: {
+      teamDomain: "https://myteam.cloudflareaccess.com",
+      audTag: "my-application-audience-tag",
+    },
+  }),
+);
+
+// Protected route - user is properly typed
+app.get("/api/protected", (c) => {
+  const user = c.get("user");
+  return c.json({
+    message: "Hello from protected route",
+    user: {
+      email: user?.email,
+      userId: user?.userId,
+    },
+  });
+});
+
+// Health check (no auth required if excluded in config)
+app.get("/health", (c) => {
+  return c.json({ status: "ok" });
+});
+
+export default app;
+
+// For local testing with Bun
+if (import.meta.main) {
+  console.log("Basic example - Static configuration");
+  console.log("This example requires valid Cloudflare Access credentials.");
+  console.log("");
+  console.log("To test with a real token:");
+  console.log(
+    '  curl -H "CF-Access-JWT-Assertion: <your-token>" http://localhost:8787/api/protected',
+  );
+}

package/examples/cloudflare-workers.ts

@@ -0,0 +1,84 @@
+/**
+ * Cloudflare Workers Example - Environment Bindings
+ *
+ * This is the recommended approach for production. Configuration is read
+ * from environment bindings set in wrangler.toml or Cloudflare dashboard.
+ */
+
+import { Hono } from "hono";
+import {
+  createCloudflareAccessAuth,
+  getCloudflareAccessConfigFromBindings,
+  type CloudflareAccessUser,
+} from "cloudflare-access/hono";
+
+// Define your environment bindings type
+interface Bindings {
+  // Cloudflare Access configuration
+  CF_ACCESS_TEAM_DOMAIN: string;
+  CF_ACCESS_AUD: string;
+
+  // Your other bindings
+  ENVIRONMENT: string;
+  DB?: D1Database;
+  CACHE?: KVNamespace;
+}
+
+// Define variables type
+interface Variables {
+  user?: CloudflareAccessUser;
+}
+
+const app = new Hono<{ Bindings: Bindings; Variables: Variables }>();
+
+// Apply middleware using bindings
+app.use(
+  createCloudflareAccessAuth({
+    accessConfig: getCloudflareAccessConfigFromBindings,
+    skipInDev: true, // Skip auth on localhost in non-prod environments
+  }),
+);
+
+// Protected API routes
+app.get("/api/user", (c) => {
+  const user = c.get("user");
+
+  return c.json({
+    email: user?.email,
+    userId: user?.userId,
+    country: user?.country,
+  });
+});
+
+app.get("/api/admin", (c) => {
+  const user = c.get("user");
+
+  // You can access the authenticated user's email
+  console.log(`Admin access by: ${user?.email}`);
+
+  return c.json({
+    message: "Admin panel",
+    admin: user?.email,
+  });
+});
+
+// Export for Cloudflare Workers
+export default app;
+
+/*
+## wrangler.toml configuration:
+
+name = "my-app"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+
+[vars]
+ENVIRONMENT = "prod"
+CF_ACCESS_TEAM_DOMAIN = "https://myteam.cloudflareaccess.com"
+
+# Secrets (set via wrangler secret put)
+# CF_ACCESS_AUD = "your-audience-tag"
+
+## To set secrets:
+# wrangler secret put CF_ACCESS_AUD
+*/