kavachos 0.0.6 → 0.1.1

package/dist/auth/index.d.ts

@@ -1,9 +1,10 @@
 import { z } from 'zod';
-import { a2 as AuthAdapter, o as ResolvedUser, L as KavachPlugin, D as Database, X as AdminConfig, p as SessionManager, $ as ApiKeyManagerConfig, a7 as EmailOtpConfig, P as Permission, ab as MagicLinkConfig, ag as OrgConfig, al as PasskeyConfig, I as PluginEndpoint, aF as TotpConfig } from '../types-W8X0PXE7.js';
-export { u as AdminModule, Y as AdminUser, _ as ApiKey, v as ApiKeyManagerModule, a3 as CaptchaConfig, G as CaptchaModule, a4 as CaptchaVerifyResult, a5 as CreateTokenInput, E as EmailOtpModule, a8 as EmailVerificationConfig, y as EmailVerificationModule, r as MagicLinkModule, ad as OidcProvider, ae as OneTimeTokenConfig, z as OneTimeTokenModule, af as OneTimeTokenPurpose, ah as OrgInvitation, ai as OrgMember, O as OrgModule, aj as OrgRole, ak as Organization, am as PasskeyCredential, s as PasskeyModule, an as PasswordResetConfig, x as PasswordResetModule, ap as PhoneAuthConfig, F as PhoneAuthModule, av as RevokeTokensResult, aw as SSO_ERROR, ax as SamlProvider, aA as SsoAuditEvent, aB as SsoConfig, aC as SsoConnection, aD as SsoError, t as SsoModule, T as TotpModule, aG as TotpSetup, aH as UsernameAuthConfig, w as UsernameAuthModule, aI as ValidateTokenResult, bv as WebhookConfig, bw as WebhookEvent, W as WebhookModule, aS as createAdminModule, aT as createApiKeyManagerModule, aV as createCaptchaModule, aY as createEmailOtpModule, aZ as createEmailVerificationModule, a_ as createMagicLinkModule, a$ as createOneTimeTokenModule, b0 as createOrgModule, b1 as createPasskeyModule, b2 as createPasswordResetModule, b3 as createPhoneAuthModule, b7 as createSsoModule, b8 as createTotpModule, b9 as createUsernameAuthModule, bx as createWebhookModule } from '../types-W8X0PXE7.js';
+import { a1 as AuthAdapter, o as ResolvedUser, J as KavachPlugin, D as Database, Q as AdminConfig, p as SessionManager, _ as ApiKeyManagerConfig, a6 as EmailOtpConfig, P as Permission, aa as MagicLinkConfig, af as OrgConfig, ak as PasskeyConfig, H as PluginEndpoint, aB as TotpConfig } from '../types-5Ua5KlPc.js';
+export { u as AdminModule, X as AdminUser, Z as ApiKey, v as ApiKeyManagerModule, a2 as CaptchaConfig, G as CaptchaModule, a3 as CaptchaVerifyResult, a4 as CreateTokenInput, E as EmailOtpModule, a7 as EmailVerificationConfig, y as EmailVerificationModule, r as MagicLinkModule, ac as OidcProvider, ad as OneTimeTokenConfig, z as OneTimeTokenModule, ae as OneTimeTokenPurpose, ag as OrgInvitation, ah as OrgMember, O as OrgModule, ai as OrgRole, aj as Organization, al as PasskeyCredential, s as PasskeyModule, am as PasswordResetConfig, x as PasswordResetModule, ao as PhoneAuthConfig, F as PhoneAuthModule, ar as RevokeTokensResult, as as SSO_ERROR, at as SamlProvider, aw as SsoAuditEvent, ax as SsoConfig, ay as SsoConnection, az as SsoError, t as SsoModule, T as TotpModule, aC as TotpSetup, aD as UsernameAuthConfig, w as UsernameAuthModule, aE as ValidateTokenResult, bq as WebhookConfig, br as WebhookEvent, W as WebhookModule, aO as createAdminModule, aP as createApiKeyManagerModule, aR as createCaptchaModule, aU as createEmailOtpModule, aV as createEmailVerificationModule, aW as createMagicLinkModule, aX as createOneTimeTokenModule, aY as createOrgModule, aZ as createPasskeyModule, a_ as createPasswordResetModule, a$ as createPhoneAuthModule, b2 as createSsoModule, b3 as createTotpModule, b4 as createUsernameAuthModule, bs as createWebhookModule } from '../types-5Ua5KlPc.js';
 import { R as Result } from '../types-BuHrZcjE.js';
 import * as jose from 'jose';
 import 'drizzle-orm/sqlite-core';
+import '../redirect/index.js';
 
 /**
  * JWT bearer-token auth adapter.
@@ -1188,6 +1189,29 @@ declare function createLastLoginModule(config: LastLoginConfig, db: Database): L
 
 declare function magicLink(config: MagicLinkConfig): KavachPlugin;
 
+/**
+ * Types for the OAuth 2.0 / OIDC provider system.
+ *
+ * KavachOS uses PKCE (S256) for all provider flows regardless of whether
+ * the provider strictly requires it. This prevents authorization code
+ * interception attacks on both public and confidential clients.
+ */
+interface OAuthProviderConfig {
+    /** OAuth application client ID. */
+    clientId: string;
+    /** OAuth application client secret. */
+    clientSecret: string;
+    /**
+     * Additional scopes to request on top of the provider defaults.
+     * The provider's default scopes are always included.
+     */
+    scopes?: string[];
+    /**
+     * Override the redirect URI registered with the provider.
+     * When omitted the module uses the `redirectUri` passed at call time.
+     */
+    redirectUri?: string;
+}
 interface OAuthProvider {
     /** Machine-readable provider ID, e.g. `'google'`, `'github'`. */
     id: string;
@@ -1252,6 +1276,446 @@ interface OAuthUserInfo {
     /** Full raw response from the provider's user info endpoint. */
     raw: Record<string, unknown>;
 }
+interface OAuthModuleConfig {
+    /**
+     * Map of provider ID to provider instance.
+     *
+     * @example
+     * ```typescript
+     * import { createGoogleProvider } from 'kavachos/auth/oauth/providers/google';
+     * import { createGithubProvider } from 'kavachos/auth/oauth/providers/github';
+     *
+     * providers: {
+     *   google: createGoogleProvider({ clientId: '...', clientSecret: '...' }),
+     *   github: createGithubProvider({ clientId: '...', clientSecret: '...' }),
+     * }
+     * ```
+     */
+    providers: Record<string, OAuthProvider>;
+    /**
+     * How long an OAuth state entry lives before it is considered expired.
+     * Defaults to 600 seconds (10 minutes).
+     */
+    stateTtlSeconds?: number;
+}
+interface OAuthModule {
+    /**
+     * Generate a PKCE-protected authorization URL and persist the state.
+     *
+     * Call this on your `/auth/:provider` route and redirect the user to the
+     * returned URL.
+     *
+     * @returns `{ url, state }` — redirect to `url`; `state` is stored in the DB.
+     */
+    getAuthorizationUrl(providerId: string, redirectUri: string): Promise<{
+        url: string;
+        state: string;
+    }>;
+    /**
+     * Handle the provider callback and resolve (or create) a linked account.
+     *
+     * Call this on your `/auth/:provider/callback` route.
+     *
+     * @param providerId  The provider that issued the callback.
+     * @param code        The authorization code from the query string.
+     * @param state       The state value from the query string (validated against DB).
+     * @param redirectUri Must match the URI used in `getAuthorizationUrl`.
+     * @returns The linked account row and normalized user info.
+     */
+    handleCallback(providerId: string, code: string, state: string, redirectUri: string): Promise<OAuthCallbackResult>;
+    /**
+     * Manually link an OAuth provider account to an existing KavachOS user.
+     *
+     * Useful when you want to add a second provider to a user who already
+     * authenticated via a different method.
+     */
+    linkAccount(userId: string, providerId: string, userInfo: OAuthUserInfo, tokens: OAuthTokens): Promise<OAuthAccount>;
+    /**
+     * Look up the KavachOS user linked to a given provider account.
+     *
+     * Returns `null` when no link exists yet.
+     */
+    findLinkedUser(providerId: string, providerAccountId: string): Promise<{
+        userId: string;
+    } | null>;
+}
+interface OAuthCallbackResult {
+    /** Whether this callback created a new linked account (vs. found an existing one). */
+    isNewAccount: boolean;
+    account: OAuthAccount;
+    userInfo: OAuthUserInfo;
+    tokens: OAuthTokens;
+}
+interface OAuthAccount {
+    id: string;
+    userId: string;
+    provider: string;
+    providerAccountId: string;
+    accessToken: string;
+    refreshToken: string | null;
+    expiresAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+/**
+ * OAuth module factory.
+ *
+ * Provides three operations on top of any configured set of providers:
+ *
+ * 1. `getAuthorizationUrl` — generate a PKCE-protected authorization URL and
+ *    persist the state + code verifier to the database.
+ * 2. `handleCallback` — validate state, exchange the code, fetch user info,
+ *    and create or return an existing linked account.
+ * 3. `linkAccount` — manually link provider tokens to an existing user.
+ * 4. `findLinkedUser` — look up which user owns a provider account.
+ *
+ * All state operations use the `kavach_oauth_states` table; all account links
+ * use the `kavach_oauth_accounts` table — both defined in `./schema.ts`.
+ */
+
+/**
+ * Create an OAuth module bound to a database instance.
+ *
+ * @example
+ * ```typescript
+ * import { createOAuthModule } from 'kavachos/auth/oauth';
+ * import { createGoogleProvider } from 'kavachos/auth/oauth/providers/google';
+ *
+ * const oauth = createOAuthModule(db, {
+ *   providers: {
+ *     google: createGoogleProvider({ clientId: '...', clientSecret: '...' }),
+ *   },
+ * });
+ *
+ * // On /auth/google
+ * const { url } = await oauth.getAuthorizationUrl('google', 'https://my.app/callback');
+ * return redirect(url);
+ *
+ * // On /auth/google/callback
+ * const { account, userInfo } = await oauth.handleCallback(
+ *   'google', req.query.code, req.query.state, 'https://my.app/callback',
+ * );
+ * ```
+ */
+declare function createOAuthModule(db: Database, config: OAuthModuleConfig): OAuthModule;
+
+interface OAuthPluginConfig extends OAuthModuleConfig {
+    /**
+     * Build the redirect URI for a given provider.
+     *
+     * When omitted the plugin constructs the URI from `ctx.config.baseUrl`
+     * using the pattern `{baseUrl}/auth/oauth/callback/{provider}`.
+     */
+    buildRedirectUri?: (provider: string, baseUrl: string) => string;
+}
+declare function oauth(config: OAuthPluginConfig): KavachPlugin;
+
+/**
+ * Apple Sign In provider (OAuth 2.0 / OIDC).
+ *
+ * Endpoints:
+ * - Authorization: https://appleid.apple.com/auth/authorize
+ * - Token:         https://appleid.apple.com/auth/token
+ *
+ * Notes:
+ * - Apple does not expose a dedicated UserInfo endpoint. Instead, it embeds
+ *   user claims (email, name) in the `id_token` JWT on first authorization.
+ *   On subsequent authorizations the `user` form-post field is absent — only
+ *   the `id_token` carries the `sub` and `email` claims.
+ * - PKCE S256 is supported and recommended.
+ * - `response_mode` must be `form_post` when requesting the `name` scope,
+ *   because Apple POSTs back a `user` JSON field alongside the code.
+ * - The `name` scope only delivers user data on the *first* authorization.
+ *   Store it immediately; subsequent logins will not include it.
+ *
+ * Docs: https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/incorporating_sign_in_with_apple_into_other_platforms
+ */
+
+/**
+ * Create an Apple Sign In provider instance.
+ *
+ * Apple requires a JWT client secret (signed with your private key) rather
+ * than a static secret. Generate the client secret JWT before passing it in
+ * as `clientSecret`.
+ *
+ * @example
+ * ```typescript
+ * const apple = createAppleProvider({
+ *   clientId: process.env.APPLE_CLIENT_ID,       // Services ID, e.g. com.example.app
+ *   clientSecret: appleClientSecretJwt,           // ES256 JWT generated from private key
+ * });
+ * ```
+ */
+declare function createAppleProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Discord OAuth 2.0 provider.
+ *
+ * Endpoints:
+ * - Authorization: https://discord.com/api/oauth2/authorize
+ * - Token:         https://discord.com/api/oauth2/token
+ * - UserInfo:      https://discord.com/api/users/@me
+ *
+ * Notes:
+ * - PKCE S256 is supported as of the Discord OAuth 2.0 implementation.
+ * - The `identify` scope grants access to the user object (ID, username,
+ *   avatar). The `email` scope is required separately to receive the email.
+ * - Avatar URLs are constructed from the user ID and avatar hash. When the
+ *   user has no custom avatar, `avatar` is null and Discord serves a default
+ *   based on the discriminator (or username for the new username system).
+ * - Discord user IDs are Snowflakes (64-bit integers serialized as strings).
+ *
+ * Docs: https://discord.com/developers/docs/topics/oauth2
+ */
+
+/**
+ * Create a Discord OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const discord = createDiscordProvider({
+ *   clientId: process.env.DISCORD_CLIENT_ID,
+ *   clientSecret: process.env.DISCORD_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createDiscordProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * GitHub OAuth 2.0 provider.
+ *
+ * Endpoints:
+ * - Authorization: https://github.com/login/oauth/authorize
+ * - Token:         https://github.com/login/oauth/access_token
+ * - UserInfo:      https://api.github.com/user
+ * - Emails:        https://api.github.com/user/emails (for primary verified email)
+ *
+ * Notes:
+ * - GitHub does not natively support PKCE in its OAuth flow, but we send the
+ *   `code_challenge` parameter anyway — it is silently ignored, which is safe.
+ *   The code verifier is still validated server-side within KavachOS state
+ *   storage so the CSRF protection guarantee holds.
+ * - The `user:email` scope is required to read the primary email when it is
+ *   set to private on the GitHub profile.
+ * - GitHub tokens do not carry an `expires_in` field for classic tokens.
+ *
+ * Docs: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps
+ */
+
+/**
+ * Create a GitHub OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const github = createGithubProvider({
+ *   clientId: process.env.GITHUB_CLIENT_ID,
+ *   clientSecret: process.env.GITHUB_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createGithubProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * GitLab OAuth 2.0 provider.
+ *
+ * Endpoints (gitlab.com — self-managed instances replace the base URL):
+ * - Authorization: https://gitlab.com/oauth/authorize
+ * - Token:         https://gitlab.com/oauth/token
+ * - UserInfo:      https://gitlab.com/api/v4/user
+ *
+ * Notes:
+ * - PKCE S256 is supported.
+ * - The `read_user` scope grants access to the `/api/v4/user` endpoint which
+ *   returns the authenticated user's profile including email.
+ * - GitLab user IDs are integers; they are converted to strings for the
+ *   KavachOS normalized format.
+ * - For self-managed GitLab instances, override the URLs by providing a
+ *   custom base URL and constructing the provider accordingly.
+ *
+ * Docs: https://docs.gitlab.com/ee/api/oauth2.html
+ */
+
+/**
+ * Create a GitLab OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const gitlab = createGitlabProvider({
+ *   clientId: process.env.GITLAB_CLIENT_ID,
+ *   clientSecret: process.env.GITLAB_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createGitlabProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Google OAuth 2.0 / OIDC provider.
+ *
+ * Endpoints:
+ * - Authorization: https://accounts.google.com/o/oauth2/v2/auth
+ * - Token:         https://oauth2.googleapis.com/token
+ * - UserInfo:      https://www.googleapis.com/oauth2/v3/userinfo
+ *
+ * PKCE S256 is always enforced. Google supports it for all client types
+ * and the spec mandates it for public clients.
+ *
+ * Docs: https://developers.google.com/identity/protocols/oauth2
+ */
+
+/**
+ * Create a Google OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const google = createGoogleProvider({
+ *   clientId: process.env.GOOGLE_CLIENT_ID,
+ *   clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createGoogleProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * LinkedIn OAuth 2.0 / OIDC provider.
+ *
+ * Endpoints:
+ * - Authorization: https://www.linkedin.com/oauth/v2/authorization
+ * - Token:         https://www.linkedin.com/oauth/v2/accessToken
+ * - UserInfo:      https://api.linkedin.com/v2/userinfo (OIDC endpoint)
+ *
+ * Notes:
+ * - LinkedIn's OIDC userinfo endpoint (`/v2/userinfo`) is available when the
+ *   `openid` scope is requested. It returns standard OIDC claims including
+ *   `sub`, `name`, `email`, and `picture`.
+ * - PKCE is not supported by LinkedIn's OAuth server. The code challenge is
+ *   sent for symmetry but silently ignored. CSRF protection via `state` still
+ *   applies within KavachOS.
+ * - The `sub` claim is the LinkedIn member ID and is stable across sessions.
+ *
+ * Docs: https://learn.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/sign-in-with-linkedin-v2
+ */
+
+/**
+ * Create a LinkedIn OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const linkedin = createLinkedInProvider({
+ *   clientId: process.env.LINKEDIN_CLIENT_ID,
+ *   clientSecret: process.env.LINKEDIN_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createLinkedInProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Microsoft identity platform (Entra ID / Azure AD) OAuth 2.0 / OIDC provider.
+ *
+ * Endpoints (common tenant — works for personal accounts and work/school):
+ * - Authorization: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
+ * - Token:         https://login.microsoftonline.com/common/oauth2/v2.0/token
+ * - UserInfo:      https://graph.microsoft.com/v1.0/me
+ *
+ * Notes:
+ * - PKCE S256 is supported and required for public clients.
+ * - `User.Read` is a Microsoft Graph permission, not a standard OIDC scope.
+ *   It grants access to the `/me` endpoint.
+ * - The `id` field on the Graph `/me` response is the Entra object ID, which
+ *   is stable across tenant changes and is safe to use as a primary key.
+ * - For single-tenant apps, replace `common` with the tenant ID or domain.
+ *
+ * Docs: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow
+ */
+
+/**
+ * Create a Microsoft identity platform OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const microsoft = createMicrosoftProvider({
+ *   clientId: process.env.MICROSOFT_CLIENT_ID,
+ *   clientSecret: process.env.MICROSOFT_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createMicrosoftProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Slack OAuth 2.0 / OIDC provider.
+ *
+ * Endpoints:
+ * - Authorization: https://slack.com/oauth/v2/authorize
+ * - Token:         https://slack.com/api/oauth.v2.access
+ * - UserInfo:      https://slack.com/api/openid.connect.userInfo
+ *
+ * Notes:
+ * - Slack's v2 OAuth uses OpenID Connect for user sign-in. The
+ *   `openid.connect.userInfo` endpoint returns OIDC-standard claims.
+ * - The token exchange response has a nested structure: `authed_user.access_token`
+ *   for the user token and a bot token at the top level when bot scopes are
+ *   included. For sign-in we want the user token.
+ * - PKCE is not natively supported by Slack's OAuth v2 server. The code
+ *   challenge is sent but silently ignored — CSRF protection via `state` still
+ *   applies within KavachOS.
+ * - Slack user IDs are workspace-scoped, not global. The `sub` claim from the
+ *   OIDC userinfo endpoint is the globally unique identifier across workspaces.
+ *
+ * Docs: https://api.slack.com/authentication/sign-in-with-slack
+ */
+
+/**
+ * Create a Slack OAuth provider instance.
+ *
+ * @example
+ * ```typescript
+ * const slack = createSlackProvider({
+ *   clientId: process.env.SLACK_CLIENT_ID,
+ *   clientSecret: process.env.SLACK_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createSlackProvider(config: OAuthProviderConfig): OAuthProvider;
+
+/**
+ * Twitter / X OAuth 2.0 provider.
+ *
+ * Endpoints:
+ * - Authorization: https://twitter.com/i/oauth2/authorize
+ * - Token:         https://api.twitter.com/2/oauth2/token
+ * - UserInfo:      https://api.twitter.com/2/users/me
+ *
+ * Notes:
+ * - Twitter OAuth 2.0 (the v2 API) mandates PKCE S256 for all public clients.
+ *   Confidential clients may omit PKCE but it is always safer to include it.
+ * - The token exchange requires HTTP Basic auth (`client_id:client_secret`)
+ *   rather than including credentials in the request body.
+ * - The `/2/users/me` endpoint returns a minimal set of fields by default.
+ *   Additional fields (profile_image_url, name) must be requested via the
+ *   `user.fields` query parameter.
+ * - Twitter does not return an email address through the standard OAuth 2.0
+ *   flow. Email access requires a separate elevated API access application
+ *   and the `tweet.read` scope alone does not grant it.
+ * - User IDs are numeric strings and stable across username changes.
+ *
+ * Docs: https://developer.twitter.com/en/docs/authentication/oauth-2-0/authorization-code
+ */
+
+/**
+ * Create a Twitter / X OAuth provider instance.
+ *
+ * Twitter requires PKCE for all flows. The `clientSecret` is still needed for
+ * the token exchange (sent as HTTP Basic auth).
+ *
+ * @example
+ * ```typescript
+ * const twitter = createTwitterProvider({
+ *   clientId: process.env.TWITTER_CLIENT_ID,
+ *   clientSecret: process.env.TWITTER_CLIENT_SECRET,
+ * });
+ * ```
+ */
+declare function createTwitterProvider(config: OAuthProviderConfig): OAuthProvider;
 
 /**
  * OAuth proxy module for mobile apps.
@@ -1812,6 +2276,90 @@ declare function createPolarModule(config: PolarConfig, db: Database): PolarModu
 
 declare function polar(config: PolarConfig): KavachPlugin;
 
+/**
+ * Shared store interface for the rateLimit() plugin.
+ * Kept in a separate file to avoid circular imports between
+ * rate-limit.ts and the individual store implementations.
+ */
+/** Store backend interface for the rateLimit() plugin. */
+interface RateLimitStore {
+    /**
+     * Increment the hit count for `key` within a `windowMs`-millisecond window.
+     * Returns the updated count and the unix timestamp (ms) when the window resets.
+     */
+    increment(key: string, windowMs: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    /** Clear all recorded hits for a key. */
+    reset(key: string): Promise<void>;
+}
+
+/**
+ * rateLimit() plugin for KavachOS.
+ *
+ * Wraps auth endpoints with configurable per-IP (and per-agent) throttling.
+ * Intercepts requests via the onRequest lifecycle hook before any handler
+ * runs, keeping the limiting logic decoupled from individual endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { createKavach } from 'kavachos';
+ * import { rateLimit } from 'kavachos/auth';
+ * import { kvStore } from 'kavachos/auth/stores/kv';
+ *
+ * const kavach = createKavach({
+ *   plugins: [
+ *     rateLimit({
+ *       signIn:        { window: '15m', max: 10 },
+ *       signUp:        { window: '1h',  max: 5  },
+ *       passwordReset: { window: '1h',  max: 3  },
+ *       agentAuthorize:{ window: '1m',  max: 100 },
+ *       default:       { window: '1m',  max: 60  },
+ *       store: kvStore(env.CACHE_KV),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+
+/** Per-endpoint rate limit configuration */
+interface EndpointLimit {
+    /** Duration string: "15m", "1h", "30s", "1d" */
+    window: string;
+    /** Maximum number of requests allowed within the window */
+    max: number;
+}
+interface RateLimitConfig$1 {
+    /** Limit for POST /auth/sign-in */
+    signIn?: EndpointLimit;
+    /** Limit for POST /auth/sign-up */
+    signUp?: EndpointLimit;
+    /** Limit for POST /auth/password-reset */
+    passwordReset?: EndpointLimit;
+    /** Limit for POST /auth/agent/authorize */
+    agentAuthorize?: EndpointLimit;
+    /** Fallback limit applied to all other /auth/* paths */
+    default?: EndpointLimit;
+    /**
+     * Storage backend.
+     * Pass "memory" or omit to use the built-in in-memory store.
+     * Pass a KVStore (or any RateLimitStore) for edge deployments.
+     */
+    store?: "memory" | RateLimitStore;
+    /**
+     * Extract a rate-limit key from the request.
+     * Defaults to reading x-forwarded-for → x-real-ip → "unknown".
+     */
+    keyExtractor?: (request: Request) => string;
+    /**
+     * Custom response factory called when a limit is exceeded.
+     * Defaults to a JSON 429 response with Retry-After header.
+     */
+    onLimit?: (request: Request, retryAfter: number) => Response;
+}
+declare function rateLimit(config?: RateLimitConfig$1): KavachPlugin;
+
 /**
  * In-memory sliding window rate limiter for auth endpoints.
  *
@@ -2118,6 +2666,55 @@ declare function createSiweModule(config: SiweConfig): SiweModule;
 
 declare function siwe(config: SiweConfig): KavachPlugin;
 
+/**
+ * Cloudflare KV rate limit store.
+ *
+ * Each key stores a JSON object { count, resetAt } with a TTL so Cloudflare
+ * automatically evicts expired windows without any extra cleanup logic.
+ *
+ * The KV namespace is passed in at construction time so this module remains
+ * free of any Cloudflare-specific imports (it only uses the KV interface that
+ * Workers expose at runtime).
+ */
+
+/** Minimal KV namespace interface — compatible with Cloudflare Workers KVNamespace */
+interface KVNamespace {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+declare class KVStore implements RateLimitStore {
+    private readonly kv;
+    constructor(kv: KVNamespace);
+    increment(key: string, windowMs: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    reset(key: string): Promise<void>;
+}
+/** Factory function to create a KVStore from a KV namespace binding */
+declare function kvStore(kv: KVNamespace): KVStore;
+
+/**
+ * In-memory rate limit store.
+ *
+ * Uses a Map keyed by a caller-supplied string. Each entry tracks the current
+ * hit count and the unix timestamp (ms) at which the window resets. Expired
+ * windows are reset on the next increment so memory stays bounded without
+ * needing a background sweep.
+ */
+
+declare class MemoryStore implements RateLimitStore {
+    private readonly entries;
+    increment(key: string, windowMs: number): Promise<{
+        count: number;
+        resetAt: number;
+    }>;
+    reset(key: string): Promise<void>;
+}
+
 /**
  * Stripe payment integration for KavachOS.
  *
@@ -2254,4 +2851,4 @@ declare function createTrustedDeviceModule(config: TrustedDeviceConfig, db: Data
  */
 declare function deviceLabelFromRequest(request: Request): string;
 
-export { type AccessTokenClaims, type AdditionalFieldsConfig, type AdditionalFieldsModule, AdminConfig, type AnonymousAuthConfig, type AnonymousAuthModule, ApiKeyManagerConfig, AuthAdapter, type AuthorizeParams, type BearerAuthOptions, type BudgetCheckResult, type CheckParams, type CheckResult, type CheckoutOptions, type CostAlert, type CostAttributionConfig, type CostAttributionModule, type CostReport, type CreateEphemeralSessionInput, type CustomSessionConfig, type CustomSessionModule, type DeleteOptions, type DeleteResult, type DeviceAuthConfig, type DeviceAuthModule, type DeviceAuthStatus, type DeviceCodeResponse, EVENT_TYPES, EmailOtpConfig, type EndpointGroup, type EphemeralSession, type EphemeralSessionConfig, type EphemeralSessionModule, type EphemeralSessionValidateResult, type EventStreamConfig, type EventStreamModule, type EventType, type ExpandParams, type FederatedAgent, type FederationConfig, type FederationModule, type FederationToken, type FederationWellKnown, type FieldDefinition, type GdprModule, type GetUserClaimsFn, type GoogleUser, type HeaderAuthOptions, HibpApiError, HibpBreachedError, type HibpConfig, type HibpModule, type InstanceIdentity, type IssueFederationTokenInput, type JsonWebKeySet, type JwtSessionConfig, type JwtSessionModule, type LastLoginConfig, type LastLoginModule, type ListObjectsParams, type ListSubjectsParams, type LoginEvent, type LoginMethod, MagicLinkConfig, type OAuthProxyConfig, OAuthProxyError, type OAuthProxyModule, type OAuthProxyPluginConfig, type OidcClient, type OidcDiscoveryDocument, type OidcProviderConfig, type OidcProviderModule, type OneTapConfig, type OneTapModule, OneTapVerifyError, type OpenApiComponents, type OpenApiConfig, type OpenApiDocument, type OpenApiInfo, type OpenApiMediaType, type OpenApiModule, type OpenApiOperation, type OpenApiParameter, type OpenApiPathItem, type OpenApiRequestBody, type OpenApiResponse, type OpenApiSchema, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServer, OrgConfig, PasskeyConfig, type PermissionRuleSet, type PolarConfig, type PolarModule, type PolarSubscription, type ProxyTokens, type RateLimitConfig, type RateLimitMiddlewareOptions, type RateLimitResult, type RateLimiter, type ReBACConfig, type ReBACModule, type RecordCostInput, type RecordLoginInput, type RegisterClientInput, type Relationship, ResolvedUser, type ResourceNode, type ScimConfig, type ScimGroup, type ScimModule, type ScimUser, type SessionTokens, type SessionUser, type SiweConfig, type SiweModule, type SiweVerifyResult, type StreamEvent, type StripeConfig, type StripeModule, type SubscriptionInfo, type TokenParams, type TokenResponse, TotpConfig, type TrustLevel, type TrustedDevice, type TrustedDeviceConfig, type TrustedDeviceModule, type TrustedInstance, type TwoFactorConfig, type UserDataExport, type UserInfoClaims, type ValidationResult, type VerifiedSession, additionalFields, admin, anonymousAuth, apiKeys, bearerAuth, createAdditionalFieldsModule, createAnonymousAuthModule, createCostAttributionModule, createCustomSessionModule, createDeviceAuthModule, createEphemeralSessionModule, createEventStreamModule, createFederationModule, createGdprModule, createHibpModule, createJwtSessionModule, createLastLoginModule, createOAuthProxyModule, createOidcProviderModule, createOneTapModule, createOpenApiModule, createPolarModule, createRateLimiter, createReBACModule, createScimModule, createSiweModule, createStripeModule, createTrustedDeviceModule, customAuth, customSession, deviceAuth, deviceLabelFromRequest, emailOtp, gdpr, headerAuth, magicLink, oauthProxy, oneTap, organization, passkey, polar, scim, siwe, stripe, twoFactor, withRateLimit };
+export { type AccessTokenClaims, type AdditionalFieldsConfig, type AdditionalFieldsModule, AdminConfig, type AnonymousAuthConfig, type AnonymousAuthModule, ApiKeyManagerConfig, AuthAdapter, type AuthorizeParams, type BearerAuthOptions, type BudgetCheckResult, type CheckParams, type CheckResult, type CheckoutOptions, type CostAlert, type CostAttributionConfig, type CostAttributionModule, type CostReport, type CreateEphemeralSessionInput, type CustomSessionConfig, type CustomSessionModule, type DeleteOptions, type DeleteResult, type DeviceAuthConfig, type DeviceAuthModule, type DeviceAuthStatus, type DeviceCodeResponse, EVENT_TYPES, EmailOtpConfig, type EndpointGroup, type EndpointLimit, type EphemeralSession, type EphemeralSessionConfig, type EphemeralSessionModule, type EphemeralSessionValidateResult, type EventStreamConfig, type EventStreamModule, type EventType, type ExpandParams, type FederatedAgent, type FederationConfig, type FederationModule, type FederationToken, type FederationWellKnown, type FieldDefinition, type GdprModule, type GetUserClaimsFn, type GoogleUser, type HeaderAuthOptions, HibpApiError, HibpBreachedError, type HibpConfig, type HibpModule, type InstanceIdentity, type IssueFederationTokenInput, type JsonWebKeySet, type JwtSessionConfig, type JwtSessionModule, type KVNamespace, KVStore, type LastLoginConfig, type LastLoginModule, type ListObjectsParams, type ListSubjectsParams, type LoginEvent, type LoginMethod, MagicLinkConfig, MemoryStore, type OAuthAccount, type OAuthCallbackResult, type OAuthModule, type OAuthModuleConfig, type OAuthPluginConfig, type OAuthProvider, type OAuthProviderConfig, type OAuthProxyConfig, OAuthProxyError, type OAuthProxyModule, type OAuthProxyPluginConfig, type OAuthTokens, type OAuthUserInfo, type OidcClient, type OidcDiscoveryDocument, type OidcProviderConfig, type OidcProviderModule, type OneTapConfig, type OneTapModule, OneTapVerifyError, type OpenApiComponents, type OpenApiConfig, type OpenApiDocument, type OpenApiInfo, type OpenApiMediaType, type OpenApiModule, type OpenApiOperation, type OpenApiParameter, type OpenApiPathItem, type OpenApiRequestBody, type OpenApiResponse, type OpenApiSchema, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServer, OrgConfig, PasskeyConfig, type PermissionRuleSet, type PolarConfig, type PolarModule, type PolarSubscription, type ProxyTokens, type RateLimitConfig, type RateLimitMiddlewareOptions, type RateLimitConfig$1 as RateLimitPluginConfig, type RateLimitResult, type RateLimitStore, type RateLimiter, type ReBACConfig, type ReBACModule, type RecordCostInput, type RecordLoginInput, type RegisterClientInput, type Relationship, ResolvedUser, type ResourceNode, type ScimConfig, type ScimGroup, type ScimModule, type ScimUser, type SessionTokens, type SessionUser, type SiweConfig, type SiweModule, type SiweVerifyResult, type StreamEvent, type StripeConfig, type StripeModule, type SubscriptionInfo, type TokenParams, type TokenResponse, TotpConfig, type TrustLevel, type TrustedDevice, type TrustedDeviceConfig, type TrustedDeviceModule, type TrustedInstance, type TwoFactorConfig, type UserDataExport, type UserInfoClaims, type ValidationResult, type VerifiedSession, additionalFields, admin, anonymousAuth, apiKeys, bearerAuth, createAdditionalFieldsModule, createAnonymousAuthModule, createAppleProvider, createCostAttributionModule, createCustomSessionModule, createDeviceAuthModule, createDiscordProvider, createEphemeralSessionModule, createEventStreamModule, createFederationModule, createGdprModule, createGithubProvider, createGitlabProvider, createGoogleProvider, createHibpModule, createJwtSessionModule, createLastLoginModule, createLinkedInProvider, createMicrosoftProvider, createOAuthModule, createOAuthProxyModule, createOidcProviderModule, createOneTapModule, createOpenApiModule, createPolarModule, createRateLimiter, createReBACModule, createScimModule, createSiweModule, createSlackProvider, createStripeModule, createTrustedDeviceModule, createTwitterProvider, customAuth, customSession, deviceAuth, deviceLabelFromRequest, emailOtp, gdpr, headerAuth, kvStore, magicLink, oauth, oauthProxy, oneTap, organization, passkey, polar, rateLimit, scim, siwe, stripe, twoFactor, withRateLimit };