@kaiz11/stack-client 0.0.14

package/dist/auth/server/middleware.d.ts

@@ -0,0 +1,305 @@
+import { VerifyError, type VerifyOptions, type JWKSKeyGetter } from "./verify.js";
+/**
+ * Auth middleware configuration
+ */
+export interface StackAuthMiddlewareConfig {
+    /** Base URL of the stack (e.g., "https://stack.zenku.app") */
+    baseUrl: string;
+    /** Tenant identifier (default: "_platform") */
+    tenantId?: string;
+    /** Verification options */
+    options?: VerifyOptions;
+    /** Paths to exclude from authentication (regex patterns) */
+    excludePaths?: RegExp[];
+    /** Custom error handler */
+    onError?: (error: VerifyError) => Response;
+}
+/**
+ * Advanced middleware configuration (with explicit keyGetter)
+ */
+export interface AuthMiddlewareConfig {
+    /** JWKS key getter (from createRemoteJWKS or createLocalJWKS) */
+    keyGetter: JWKSKeyGetter;
+    /** Verification options */
+    options?: VerifyOptions;
+    /** Paths to exclude from authentication (regex patterns) */
+    excludePaths?: RegExp[];
+    /** Custom error handler */
+    onError?: (error: VerifyError) => Response;
+}
+/**
+ * Hono context-like interface
+ */
+interface HonoContext {
+    req: {
+        raw: Request;
+        path: string;
+    };
+    set: (key: string, value: unknown) => void;
+    get: (key: string) => unknown;
+    json: (data: unknown, status?: number) => Response;
+}
+/**
+ * Hono next function
+ */
+type HonoNext = () => Promise<Response | void>;
+/**
+ * Create auth middleware for Hono
+ *
+ * Automatically constructs the JWKS URL from the base URL and optional tenant ID,
+ * and verifies JWT tokens signed by the GoTrue instance.
+ *
+ * ## Token Handling
+ *
+ * | Token Type    | Result                                          |
+ * |---------------|-------------------------------------------------|
+ * | No token      | 401 Unauthorized                                |
+ * | Invalid token | 401 Unauthorized                                |
+ * | Anon JWT      | ✅ Passes, `user.role = "anon"`                 |
+ * | Auth JWT      | ✅ Passes, `user.role = "authenticated"`        |
+ * | Service JWT   | ✅ Passes, `user.role = "service_role"`         |
+ *
+ * **Note:** This middleware requires a valid JWT. In Supabase's model, even
+ * "public" requests use the anon key. If you want to allow requests without
+ * any token, use `optionalStackAuthMiddleware` instead.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import { createStackAuthMiddleware } from "@kaiz11/stack-client/auth/server";
+ *
+ * const app = new Hono();
+ *
+ * // Platform (default)
+ * app.use("*", createStackAuthMiddleware({
+ *   baseUrl: "https://stack.zenku.app",
+ *   excludePaths: [/^\/health$/],
+ * }));
+ *
+ * // Tenant
+ * app.use("*", createStackAuthMiddleware({
+ *   baseUrl: "https://stack.zenku.app",
+ *   tenantId: "acme-corp",
+ *   excludePaths: [/^\/health$/],
+ * }));
+ *
+ * app.get("/api/me", (c) => {
+ *   const user = c.get("user") as AuthUser;
+ *   return c.json({ user });
+ * });
+ * ```
+ */
+export declare function createStackAuthMiddleware(config: StackAuthMiddlewareConfig): (c: HonoContext, next: HonoNext) => Promise<Response | void>;
+/**
+ * Create auth middleware for Hono (advanced)
+ *
+ * Use this when you need to provide a custom JWKS key getter.
+ * For most cases, prefer `createStackAuthMiddleware`.
+ *
+ * ## Token Handling
+ *
+ * | Token Type    | Result                                          |
+ * |---------------|-------------------------------------------------|
+ * | No token      | 401 Unauthorized                                |
+ * | Invalid token | 401 Unauthorized                                |
+ * | Anon JWT      | ✅ Passes, `user.role = "anon"`                 |
+ * | Auth JWT      | ✅ Passes, `user.role = "authenticated"`        |
+ * | Service JWT   | ✅ Passes, `user.role = "service_role"`         |
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from "hono";
+ * import { createAuthMiddleware, createLocalJWKS } from "@kaiz11/stack-client/auth/server";
+ *
+ * const app = new Hono();
+ *
+ * // For testing with local keys
+ * const keyGetter = createLocalJWKS(testJWKS);
+ *
+ * app.use("*", createAuthMiddleware({
+ *   keyGetter,
+ *   excludePaths: [/^\/health$/],
+ * }));
+ * ```
+ */
+export declare function createAuthMiddleware(config: AuthMiddlewareConfig): (c: HonoContext, next: HonoNext) => Promise<Response | void>;
+/**
+ * Create role guard middleware for Hono
+ *
+ * Use after `createStackAuthMiddleware` to require specific roles.
+ *
+ * ## Token Handling (assuming auth middleware already ran)
+ *
+ * | Token Type    | `requireRoleMiddleware("authenticated")` | `requireRoleMiddleware("service_role")` |
+ * |---------------|------------------------------------------|----------------------------------------|
+ * | Anon JWT      | 403 Forbidden                            | 403 Forbidden                          |
+ * | Auth JWT      | ✅ Passes                                | 403 Forbidden                          |
+ * | Service JWT   | 403 Forbidden                            | ✅ Passes                              |
+ *
+ * **Common patterns:**
+ * - `requireRoleMiddleware("authenticated")` — Reject anon, allow logged-in users
+ * - `requireRoleMiddleware("service_role")` — Admin/server-only endpoints
+ *
+ * @example
+ * ```typescript
+ * import { createStackAuthMiddleware, requireRoleMiddleware } from "@kaiz11/stack-client/auth/server";
+ *
+ * app.use("*", createStackAuthMiddleware({ baseUrl: "https://stack.zenku.app" }));
+ *
+ * // Reject anon tokens, require actual login
+ * app.use("/api/user/*", requireRoleMiddleware("authenticated"));
+ *
+ * // Admin routes require service_role
+ * app.use("/admin/*", requireRoleMiddleware("service_role"));
+ * ```
+ */
+export declare function requireRoleMiddleware(role: string): (c: HonoContext, next: HonoNext) => Promise<Response | void>;
+/**
+ * Create MFA guard middleware for Hono
+ *
+ * Requires AAL2 (two-factor authentication verified in current session).
+ *
+ * ## Token Handling (assuming auth middleware already ran)
+ *
+ * | Token Type       | AAL Level | Result                              |
+ * |------------------|-----------|-------------------------------------|
+ * | Anon JWT         | aal1      | 403 MFA required                    |
+ * | Auth JWT         | aal1      | 403 MFA required                    |
+ * | Auth JWT + MFA   | aal2      | ✅ Passes                           |
+ * | Service JWT      | aal1      | 403 MFA required                    |
+ *
+ * **Note:** Service role tokens typically have aal1. If you need service role
+ * access to MFA-protected routes, check the role explicitly instead.
+ *
+ * @example
+ * ```typescript
+ * // Sensitive routes require MFA
+ * app.use("/settings/security/*", requireMfaMiddleware());
+ *
+ * // Or combine with role check for admin bypass
+ * app.use("/settings/security/*", async (c, next) => {
+ *   const user = c.get("user") as AuthUser;
+ *   if (user.role === "service_role") return next(); // Admin bypass
+ *   return requireMfaMiddleware()(c, next);
+ * });
+ * ```
+ */
+export declare function requireMfaMiddleware(): (c: HonoContext, next: HonoNext) => Promise<Response | void>;
+/**
+ * Optional auth middleware configuration
+ */
+export interface OptionalStackAuthConfig {
+    /** Base URL of the stack (e.g., "https://stack.zenku.app") */
+    baseUrl: string;
+    /** Tenant identifier (default: "_platform") */
+    tenantId?: string;
+    /** Verification options */
+    options?: VerifyOptions;
+    /**
+     * Auto-fetch anon key when no token is provided.
+     *
+     * When enabled, if no Authorization header is present, the middleware
+     * will fetch the tenant's public anon key and use it. This ensures
+     * `user` is always set (with `role = "anon"`) rather than `undefined`.
+     *
+     * The anon key is cached in memory (1 hour TTL) to avoid repeated fetches.
+     *
+     * Default: true
+     */
+    autoFetchAnon?: boolean;
+}
+/**
+ * Optional auth configuration (advanced)
+ */
+export interface OptionalAuthConfig {
+    /** JWKS key getter (from createRemoteJWKS or createLocalJWKS) */
+    keyGetter: JWKSKeyGetter;
+    /** Verification options */
+    options?: VerifyOptions;
+}
+/**
+ * Optional auth middleware for Hono
+ *
+ * Attaches user info if token is present. When no token is provided,
+ * automatically fetches the tenant's anon key (default behavior).
+ *
+ * ## Token Handling (default, autoFetchAnon = true)
+ *
+ * | Token Type    | Result                                          |
+ * |---------------|-------------------------------------------------|
+ * | No token      | ✅ Auto-fetches anon key, `user.role = "anon"`  |
+ * | Invalid token | ✅ Falls back to anon key, `user.role = "anon"` |
+ * | Anon JWT      | ✅ Continues, `user.role = "anon"`              |
+ * | Auth JWT      | ✅ Continues, `user.role = "authenticated"`     |
+ * | Service JWT   | ✅ Continues, `user.role = "service_role"`      |
+ *
+ * ## Token Handling (autoFetchAnon = false)
+ *
+ * | Token Type    | Result                                          |
+ * |---------------|-------------------------------------------------|
+ * | No token      | ✅ Continues, `user = undefined`                |
+ * | Invalid token | ✅ Continues, `user = undefined`                |
+ * | Anon JWT      | ✅ Continues, `user.role = "anon"`              |
+ * | Auth JWT      | ✅ Continues, `user.role = "authenticated"`     |
+ * | Service JWT   | ✅ Continues, `user.role = "service_role"`      |
+ *
+ * **Note:** Unlike `createStackAuthMiddleware`, this never returns 401.
+ * Invalid tokens fall back to anon (default) or are silently ignored.
+ *
+ * @example
+ * ```typescript
+ * import { optionalStackAuthMiddleware } from "@kaiz11/stack-client/auth/server";
+ *
+ * // Default: user is always set (auto-fetches anon if no token)
+ * app.use("*", optionalStackAuthMiddleware({
+ *   baseUrl: "https://stack.zenku.app",
+ *   tenantId: "acme-corp",
+ * }));
+ *
+ * // Disable auto-fetch: user may be undefined if no token
+ * app.use("*", optionalStackAuthMiddleware({
+ *   baseUrl: "https://stack.zenku.app",
+ *   tenantId: "acme-corp",
+ *   autoFetchAnon: false,
+ * }));
+ *
+ * app.get("/api/feed", (c) => {
+ *   const user = c.get("user") as AuthUser;
+ *   if (user.role === "authenticated") {
+ *     // Logged in user
+ *   } else {
+ *     // Anonymous access (anon token or auto-fetched)
+ *   }
+ * });
+ * ```
+ */
+export declare function optionalStackAuthMiddleware(config: OptionalStackAuthConfig): (c: HonoContext, next: HonoNext) => Promise<Response | void>;
+/**
+ * Optional auth middleware for Hono (advanced)
+ *
+ * Attaches user info if token is present, but doesn't require it.
+ * Use this when you need a custom JWKS key getter.
+ *
+ * ## Token Handling
+ *
+ * | Token Type    | Result                                          |
+ * |---------------|-------------------------------------------------|
+ * | No token      | ✅ Continues, `user = undefined`                |
+ * | Invalid token | ✅ Continues, `user = undefined`                |
+ * | Anon JWT      | ✅ Continues, `user.role = "anon"`              |
+ * | Auth JWT      | ✅ Continues, `user.role = "authenticated"`     |
+ * | Service JWT   | ✅ Continues, `user.role = "service_role"`      |
+ *
+ * @example
+ * ```typescript
+ * import { optionalAuthMiddleware, createLocalJWKS } from "@kaiz11/stack-client/auth/server";
+ *
+ * // For testing with local keys
+ * const keyGetter = createLocalJWKS(testJWKS);
+ *
+ * app.use("*", optionalAuthMiddleware({ keyGetter }));
+ * ```
+ */
+export declare function optionalAuthMiddleware(config: OptionalAuthConfig): (c: HonoContext, next: HonoNext) => Promise<Response | void>;
+export {};
+//# sourceMappingURL=middleware.d.ts.map

package/dist/auth/server/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../src/auth/server/middleware.ts"],"names":[],"mappings":"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"}