yaxa-svelte 2.1.0 → 2.3.0

package/README.md

@@ -241,22 +241,81 @@ export const POST = createPolarWebhookHandler();
 
 ---
 
+## ⚡ Type-Safe Endpoint Pipeline (`yaxaEndpoint` & Declarative Guards)
+
+Eliminate endpoint boilerplate in `+server.ts` with declarative auth guards, sliding-window rate limiting, multi-engine validation (Zod, Valibot, Standard Schema), and RFC 7807 Problem Details:
+
+```ts
+// src/routes/api/projects/+server.ts
+import { yaxaEndpoint, requireAuth, requireRole, rateLimit } from 'yaxa-svelte/server';
+import { z } from 'zod';
+
+const CreateProjectSchema = z.object({
+	name: z.string().min(3),
+	description: z.string().optional()
+});
+
+export const POST = yaxaEndpoint({
+	status: 201,
+	guards: [
+		requireAuth(),
+		requireRole(['admin', 'owner']),
+		rateLimit({ points: 20, windowSeconds: 60 })
+	],
+	schema: {
+		body: CreateProjectSchema
+	},
+	handle: async ({ body, user, orgId }) => {
+		// Guaranteed type-safe body, authenticated user, and active orgId
+		return { id: 'proj_123', name: body.name, orgId };
+	}
+});
+```
+
+---
+
+## 📜 Auto-Generated OpenAPI 3.1 & Interactive Docs (`/api/docs`)
+
+Instantly generate an OpenAPI 3.1 specification and host interactive documentation ([Scalar](https://scalar.com/), Swagger UI, or Redoc) directly from your `yaxaEndpoint` routes:
+
+```ts
+// src/routes/api/docs/+server.ts
+import { createApiDocsHandler } from 'yaxa-svelte/server';
+import { POST as createProject } from '../projects/+server';
+
+export const GET = createApiDocsHandler({
+	title: 'Acme SaaS API',
+	version: '1.0.0',
+	theme: 'scalar', // 'scalar' (default) | 'swagger' | 'redoc'
+	endpoints: {
+		'/api/projects': {
+			POST: createProject
+		}
+	}
+});
+```
+
+- **Interactive Reference UI:** Open `/api/docs` in your browser.
+- **Raw OpenAPI 3.1 JSON:** Request `/api/docs?format=json` or send `Accept: application/json` for SDK generation.
+
+---
+
 ## 📦 Subpath Exports Architecture
 
-| Subpath                 | Description                                                                                                                               |
-| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
-| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Theme System & Composables (`useGate`, `useUpload`, `useToast`, `useClipboard`, etc.)     |
-| `yaxa-svelte/admin`     | Drizzle ORM Schema Introspection, `<AdminDashboard />`, `createYaxaAdminHook`, `createDrizzleAdmin`, `<DevSandbox />`, `<RecordDrawer />` |
-| `yaxa-svelte/server`    | Universal Server Hooks, SEO endpoints, Drizzle DB drivers, Cloud Storage handlers, and Email dispatch                                     |
-| `yaxa-svelte/auth`      | Better-Auth client & server integration (`useAuth`, `<AuthCard />`, `<PasskeyUI />`, `<TwoFactorModal />`, `createYaxaAuth`)              |
-| `yaxa-svelte/db`        | Multi-dialect Drizzle ORM clients & schemas for Neon (PostgreSQL) and Turso (SQLite/LibSQL)                                               |
-| `yaxa-svelte/polar`     | Polar.sh billing, customer portal sessions, and webhook synchronization                                                                   |
-| `yaxa-svelte/email`     | Resend transactional email templates with automatic development console fallback                                                          |
-| `yaxa-svelte/storage`   | AWS S3 and Cloudflare R2 presigned upload URL generators                                                                                  |
-| `yaxa-svelte/testing`   | Test mocks & utilities (`createMockSiteConfig`, `createMockUser`, `createTestWrapperProps`)                                               |
-| `yaxa-svelte/vite`      | Turnkey Vite plugin (`yaxa()`)                                                                                                            |
-| `yaxa-svelte/yaxa.css`  | Standalone turnkey Tailwind CSS v4 stylesheet with base styling, `@theme`, and scrollbars                                                 |
-| `yaxa-svelte/theme.css` | Pure Tailwind CSS v4 design tokens, `:root` variables, and harmonic radius scale without `@import 'tailwindcss'`                          |
+| Subpath                 | Description                                                                                                                                                  |
+| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Theme System & Composables (`useGate`, `useUpload`, `useToast`, `useClipboard`, etc.)                        |
+| `yaxa-svelte/admin`     | Drizzle ORM Schema Introspection, `<AdminDashboard />`, `createYaxaAdminHook`, `createDrizzleAdmin`, `<DevSandbox />`, `<RecordDrawer />`                    |
+| `yaxa-svelte/server`    | `yaxaEndpoint` Pipeline, Declarative Guards, OpenAPI 3.1 & Scalar/Swagger Docs, RFC 7807, Universal Server Hooks, SEO endpoints, Drizzle DB, Storage & Email |
+| `yaxa-svelte/auth`      | Better-Auth client & server integration (`useAuth`, `<AuthCard />`, `<PasskeyUI />`, `<TwoFactorModal />`, `createYaxaAuth`)                                 |
+| `yaxa-svelte/db`        | Multi-dialect Drizzle ORM clients & schemas for Neon (PostgreSQL) and Turso (SQLite/LibSQL)                                                                  |
+| `yaxa-svelte/polar`     | Polar.sh billing, customer portal sessions, and webhook synchronization                                                                                      |
+| `yaxa-svelte/email`     | Resend transactional email templates with automatic development console fallback                                                                             |
+| `yaxa-svelte/storage`   | AWS S3 and Cloudflare R2 presigned upload URL generators                                                                                                     |
+| `yaxa-svelte/testing`   | Test mocks & utilities (`createMockSiteConfig`, `createMockUser`, `createTestWrapperProps`)                                                                  |
+| `yaxa-svelte/vite`      | Turnkey Vite plugin (`yaxa()`)                                                                                                                               |
+| `yaxa-svelte/yaxa.css`  | Standalone turnkey Tailwind CSS v4 stylesheet with base styling, `@theme`, and scrollbars                                                                    |
+| `yaxa-svelte/theme.css` | Pure Tailwind CSS v4 design tokens, `:root` variables, and harmonic radius scale without `@import 'tailwindcss'`                                             |
 
 ---
 

package/dist/server/endpoint/endpoint.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/endpoint/endpoint.test.js

@@ -0,0 +1,364 @@
+import { describe, it, expect, vi } from 'vitest';
+import { z } from 'zod';
+import { createMockRequestEvent } from '../../testing/index.js';
+import { yaxaEndpoint, createProblemDetails, problemResponse, isProblemDetails, requireAuth, requireRole, rateLimit, composeGuards, validateData } from './index.js';
+describe('RFC 7807 Problem Details', () => {
+    it('creates structured problem details object with standard defaults', () => {
+        const problem = createProblemDetails({
+            status: 404,
+            detail: 'Project proj_999 does not exist.'
+        });
+        expect(problem.status).toBe(404);
+        expect(problem.title).toBe('Not Found');
+        expect(problem.type).toBe('https://httpstatuses.com/404');
+        expect(problem.detail).toBe('Project proj_999 does not exist.');
+        expect(isProblemDetails(problem)).toBe(true);
+    });
+    it('returns Response with application/problem+json content-type and custom fields', async () => {
+        const response = problemResponse({
+            status: 422,
+            title: 'Unprocessable Entity',
+            detail: 'Validation error',
+            invalidParams: [{ name: 'email', reason: 'Must be a valid email' }],
+            traceId: 'trace_abc123'
+        });
+        expect(response.status).toBe(422);
+        expect(response.headers.get('content-type')).toContain('application/problem+json');
+        const json = await response.json();
+        expect(json.status).toBe(422);
+        expect(json.invalidParams).toHaveLength(1);
+        expect(json.invalidParams[0].name).toBe('email');
+        expect(json.traceId).toBe('trace_abc123');
+    });
+});
+describe('Declarative Guards', () => {
+    describe('requireAuth', () => {
+        it('returns 401 Problem Details when user is unauthenticated', async () => {
+            const guard = requireAuth();
+            const event = createMockRequestEvent({ locals: { user: null } });
+            const result = await guard(event);
+            expect(result).toBeInstanceOf(Response);
+            if (result instanceof Response) {
+                expect(result.status).toBe(401);
+                const json = await result.json();
+                expect(json.title).toBe('Unauthorized');
+            }
+        });
+        it('throws 303 redirect when redirect option is set', async () => {
+            const guard = requireAuth({ redirect: '/login' });
+            const event = createMockRequestEvent({
+                url: 'http://localhost:5173/dashboard?tab=billing',
+                locals: { user: null }
+            });
+            try {
+                await guard(event);
+                expect.fail('Expected redirect to be thrown');
+            }
+            catch (err) {
+                expect(err.status).toBe(303);
+                expect(err.location).toContain('/login?returnTo=');
+                expect(err.location).toContain(encodeURIComponent('/dashboard?tab=billing'));
+            }
+        });
+        it('passes cleanly when user exists in locals', async () => {
+            const guard = requireAuth();
+            const event = createMockRequestEvent({
+                locals: { user: { id: 'usr_1', role: 'admin' } }
+            });
+            const result = await guard(event);
+            expect(result).toBeUndefined();
+        });
+    });
+    describe('requireRole', () => {
+        it('returns 401 if user is not logged in', async () => {
+            const guard = requireRole(['admin']);
+            const event = createMockRequestEvent({ locals: { user: null } });
+            const result = (await guard(event));
+            expect(result.status).toBe(401);
+        });
+        it('returns 403 Forbidden when user role is not allowed', async () => {
+            const guard = requireRole(['admin', 'owner']);
+            const event = createMockRequestEvent({
+                locals: { user: { id: 'usr_1', role: 'member' } }
+            });
+            const result = (await guard(event));
+            expect(result.status).toBe(403);
+            const json = await result.json();
+            expect(json.title).toBe('Forbidden');
+            expect(json.requiredRoles).toEqual(['admin', 'owner']);
+        });
+        it('passes when user has one of the allowed roles', async () => {
+            const guard = requireRole(['admin', 'owner']);
+            const event = createMockRequestEvent({
+                locals: { user: { id: 'usr_1', role: 'owner' } }
+            });
+            const result = await guard(event);
+            expect(result).toBeUndefined();
+        });
+        it('passes when member role matches org role in multi-tenant setup', async () => {
+            const guard = requireRole(['billing_admin']);
+            const event = createMockRequestEvent({
+                locals: {
+                    user: { id: 'usr_1', role: 'member' },
+                    member: { role: 'billing_admin' }
+                }
+            });
+            const result = await guard(event);
+            expect(result).toBeUndefined();
+        });
+    });
+    describe('rateLimit', () => {
+        it('allows requests up to points threshold then returns 429', async () => {
+            const guard = rateLimit({
+                points: 3,
+                windowSeconds: 10,
+                keyGenerator: () => 'test_client_key'
+            });
+            const event = createMockRequestEvent();
+            // First 3 calls succeed
+            expect(await guard(event)).toBeUndefined();
+            expect(await guard(event)).toBeUndefined();
+            expect(await guard(event)).toBeUndefined();
+            // 4th call is rate-limited
+            const result = (await guard(event));
+            expect(result.status).toBe(429);
+            expect(result.headers.get('Retry-After')).toBeDefined();
+            expect(result.headers.get('X-RateLimit-Remaining')).toBe('0');
+            const json = await result.json();
+            expect(json.title).toBe('Too Many Requests');
+        });
+    });
+    describe('composeGuards', () => {
+        it('executes guards sequentially and halts on first failure', async () => {
+            const guard = composeGuards(requireAuth(), requireRole(['admin']));
+            // Unauthenticated -> fails on requireAuth with 401
+            const eventUnauth = createMockRequestEvent({ locals: { user: null } });
+            const res1 = (await guard(eventUnauth));
+            expect(res1.status).toBe(401);
+            // Authenticated but wrong role -> fails on requireRole with 403
+            const eventForbidden = createMockRequestEvent({
+                locals: { user: { id: 'usr_1', role: 'viewer' } }
+            });
+            const res2 = (await guard(eventForbidden));
+            expect(res2.status).toBe(403);
+            // Both pass
+            const eventOk = createMockRequestEvent({
+                locals: { user: { id: 'usr_1', role: 'admin' } }
+            });
+            const res3 = await guard(eventOk);
+            expect(res3).toBeUndefined();
+        });
+    });
+});
+describe('Multi-Engine Validation Engine', () => {
+    it('validates with Zod schema and extracts parsed data', async () => {
+        const schema = z.object({
+            email: z.string().email(),
+            age: z.number().min(18)
+        });
+        const valid = await validateData(schema, { email: 'test@example.com', age: 25 });
+        expect(valid.success).toBe(true);
+        if (valid.success) {
+            expect(valid.data.email).toBe('test@example.com');
+            expect(valid.data.age).toBe(25);
+        }
+        const invalid = await validateData(schema, { email: 'bad-email', age: 16 }, 'body');
+        expect(invalid.success).toBe(false);
+        if (!invalid.success) {
+            expect(invalid.invalidParams.length).toBeGreaterThanOrEqual(2);
+            expect(invalid.invalidParams[0].name).toContain('body.');
+        }
+    });
+    it('validates with Standard Schema v1 (~standard)', async () => {
+        // Mock Standard Schema specification
+        const mockStandardSchema = {
+            '~standard': {
+                version: 1,
+                vendor: 'custom',
+                validate: (val) => {
+                    if (typeof val === 'string' && val.length > 3) {
+                        return { value: val.toUpperCase() };
+                    }
+                    return {
+                        issues: [{ path: ['name'], message: 'Name must exceed 3 characters' }]
+                    };
+                }
+            }
+        };
+        const ok = await validateData(mockStandardSchema, 'alice');
+        expect(ok.success).toBe(true);
+        if (ok.success)
+            expect(ok.data).toBe('ALICE');
+        const bad = await validateData(mockStandardSchema, 'al', 'body');
+        expect(bad.success).toBe(false);
+        if (!bad.success) {
+            expect(bad.invalidParams[0].name).toBe('body.name');
+            expect(bad.invalidParams[0].reason).toContain('exceed 3 characters');
+        }
+    });
+    it('validates with custom function validator', async () => {
+        const validator = (val) => {
+            if (!val || val.length === 0) {
+                return { success: false, error: 'Cannot be empty' };
+            }
+            return { success: true, data: val };
+        };
+        const ok = await validateData(validator, 'hello');
+        expect(ok.success).toBe(true);
+        const bad = await validateData(validator, '');
+        expect(bad.success).toBe(false);
+    });
+});
+describe('yaxaEndpoint Higher-Order Pipeline', () => {
+    const ItemSchema = z.object({
+        title: z.string().min(2),
+        price: z.number().positive()
+    });
+    const QuerySchema = z.object({
+        search: z.string().optional()
+    });
+    it('enforces guards before executing handler', async () => {
+        const endpoint = yaxaEndpoint({
+            guards: [requireAuth()],
+            handle: () => ({ success: true })
+        });
+        const eventUnauth = createMockRequestEvent({ locals: { user: null } });
+        const response = await endpoint(eventUnauth);
+        expect(response.status).toBe(401);
+        const json = await response.json();
+        expect(json.title).toBe('Unauthorized');
+    });
+    it('returns 422 Problem Details on invalid request body', async () => {
+        const endpoint = yaxaEndpoint({
+            schema: { body: ItemSchema },
+            handle: ({ body }) => body
+        });
+        const event = createMockRequestEvent({
+            method: 'POST',
+            body: { title: 'a', price: -5 }
+        });
+        const response = await endpoint(event);
+        expect(response.status).toBe(422);
+        expect(response.headers.get('content-type')).toContain('application/problem+json');
+        const json = await response.json();
+        expect(json.status).toBe(422);
+        expect(json.title).toBe('Unprocessable Entity');
+        expect(json.invalidParams.length).toBeGreaterThanOrEqual(2);
+    });
+    it('handles malformed JSON body gracefully with 400 Bad Request', async () => {
+        const endpoint = yaxaEndpoint({
+            handle: ({ body }) => body
+        });
+        const event = createMockRequestEvent({
+            method: 'POST',
+            body: '{ broken json: ',
+            headers: { 'content-type': 'application/json' }
+        });
+        const response = await endpoint(event);
+        expect(response.status).toBe(400);
+        const json = await response.json();
+        expect(json.title).toBe('Bad Request');
+    });
+    it('executes handler and auto-serializes JSON with typed body, query, and params', async () => {
+        const endpoint = yaxaEndpoint({
+            status: 201,
+            schema: {
+                body: ItemSchema,
+                query: QuerySchema
+            },
+            handle: ({ body, query, params, user }) => {
+                return {
+                    created: true,
+                    item: body,
+                    q: query.search,
+                    id: params.id,
+                    userId: user?.id
+                };
+            }
+        });
+        const event = createMockRequestEvent({
+            method: 'POST',
+            url: 'http://localhost:5173/api/items/item_42?search=svelte',
+            params: { id: 'item_42' },
+            body: { title: 'Keyboard', price: 99 },
+            locals: { user: { id: 'usr_77', role: 'admin' } }
+        });
+        const response = await endpoint(event);
+        expect(response.status).toBe(201);
+        expect(response.headers.get('content-type')).toContain('application/json');
+        const json = await response.json();
+        expect(json.created).toBe(true);
+        expect(json.item.title).toBe('Keyboard');
+        expect(json.item.price).toBe(99);
+        expect(json.q).toBe('svelte');
+        expect(json.id).toBe('item_42');
+        expect(json.userId).toBe('usr_77');
+    });
+    it('supports string returns as text/plain and null/void as 204 No Content', async () => {
+        const stringEndpoint = yaxaEndpoint({
+            handle: () => 'PONG'
+        });
+        const res1 = await stringEndpoint(createMockRequestEvent());
+        expect(res1.status).toBe(200);
+        expect(await res1.text()).toBe('PONG');
+        expect(res1.headers.get('content-type')).toContain('text/plain');
+        const voidEndpoint = yaxaEndpoint({
+            handle: () => undefined
+        });
+        const res2 = await voidEndpoint(createMockRequestEvent());
+        expect(res2.status).toBe(204);
+    });
+    it('passes through custom Response instances without modification', async () => {
+        const customEndpoint = yaxaEndpoint({
+            handle: () => new Response('Custom CSV Content', {
+                status: 200,
+                headers: { 'content-type': 'text/csv' }
+            })
+        });
+        const response = await customEndpoint(createMockRequestEvent());
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toBe('text/csv');
+        expect(await response.text()).toBe('Custom CSV Content');
+    });
+    it('supports interceptors for request timing and header enrichment', async () => {
+        const endpoint = yaxaEndpoint({
+            interceptors: [
+                async (_ctx, next) => {
+                    const res = await next();
+                    res.headers.set('x-yaxa-intercepted', 'true');
+                    return res;
+                }
+            ],
+            handle: () => ({ ok: true })
+        });
+        const response = await endpoint(createMockRequestEvent());
+        expect(response.headers.get('x-yaxa-intercepted')).toBe('true');
+    });
+    it('sanitizes unexpected internal 500 errors without leaking stack traces or sensitive strings', async () => {
+        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const failingEndpoint = yaxaEndpoint({
+            handle: () => {
+                throw new Error('Database password leak: secret123456');
+            }
+        });
+        const response = await failingEndpoint(createMockRequestEvent());
+        expect(response.status).toBe(500);
+        expect(response.headers.get('content-type')).toContain('application/problem+json');
+        const json = await response.json();
+        expect(json.title).toBe('Internal Server Error');
+        expect(json.detail).not.toContain('secret123456');
+        errorSpy.mockRestore();
+    });
+    it('attaches _yaxaConfig metadata for runtime reflection and OpenAPI discovery', () => {
+        const config = {
+            summary: 'Create Project',
+            description: 'Creates a new user project',
+            tags: ['Projects'],
+            handle: () => ({})
+        };
+        const endpoint = yaxaEndpoint(config);
+        expect(endpoint._yaxaConfig).toBeDefined();
+        expect(endpoint._yaxaConfig.summary).toBe('Create Project');
+        expect(endpoint._yaxaConfig.tags).toEqual(['Projects']);
+    });
+});

package/dist/server/endpoint/guards.d.ts

@@ -0,0 +1,57 @@
+import type { RequestEvent } from '@sveltejs/kit';
+import type { Guard } from './types';
+export interface RequireAuthOptions {
+    /**
+     * If provided, unauthorized users are redirected with 303 instead of receiving 401 JSON.
+     * (Useful for dashboard/form routes).
+     */
+    redirect?: string;
+    /**
+     * Custom error message for the RFC 7807 detail.
+     */
+    detail?: string;
+}
+export interface YaxaGuardMetadata {
+    type: 'auth' | 'role' | 'rateLimit' | string;
+    roles?: string[];
+    options?: any;
+}
+/**
+ * Declarative Guard: Enforces that the request has an active authenticated user in `event.locals.user`.
+ */
+export declare function requireAuth(options?: RequireAuthOptions): Guard;
+export interface RequireRoleOptions {
+    detail?: string;
+}
+/**
+ * Declarative Guard: Enforces that the active user/member possesses one of the allowed roles.
+ * Checks `event.locals.user.role`, `event.locals.member.role`, and `event.locals.orgRole`.
+ */
+export declare function requireRole(roles: string | string[], options?: RequireRoleOptions): Guard;
+export interface RateLimitOptions {
+    /**
+     * Maximum allowed requests within the time window. Default: 60.
+     */
+    points?: number;
+    /**
+     * Window duration in seconds. Default: 60.
+     */
+    windowSeconds?: number;
+    /**
+     * Custom cache key generator. Defaults to IP address or authenticated user ID.
+     */
+    keyGenerator?: (event: RequestEvent) => string;
+    /**
+     * Custom error message.
+     */
+    detail?: string;
+}
+/**
+ * Declarative Guard: In-memory sliding-window rate limiter.
+ * Returns 429 Too Many Requests with a `Retry-After` header when exceeded.
+ */
+export declare function rateLimit(options?: RateLimitOptions): Guard;
+/**
+ * Combines multiple guards into a single composite guard.
+ */
+export declare function composeGuards(...guards: Guard[]): Guard;

package/dist/server/endpoint/guards.js

@@ -0,0 +1,153 @@
+import { redirect } from '@sveltejs/kit';
+import { problemResponse } from './problem';
+/**
+ * Declarative Guard: Enforces that the request has an active authenticated user in `event.locals.user`.
+ */
+export function requireAuth(options = {}) {
+    const guard = (event) => {
+        const user = event.locals?.user;
+        if (!user) {
+            if (options.redirect) {
+                const returnTo = encodeURIComponent(event.url.pathname + event.url.search);
+                const target = options.redirect.includes('?')
+                    ? `${options.redirect}&returnTo=${returnTo}`
+                    : `${options.redirect}?returnTo=${returnTo}`;
+                throw redirect(303, target);
+            }
+            return problemResponse({
+                status: 401,
+                title: 'Unauthorized',
+                detail: options.detail || 'Authentication required to access this endpoint.',
+                type: 'https://yaxa.dev/errors/unauthorized'
+            });
+        }
+    };
+    guard._yaxaGuard = {
+        type: 'auth',
+        options
+    };
+    return guard;
+}
+/**
+ * Declarative Guard: Enforces that the active user/member possesses one of the allowed roles.
+ * Checks `event.locals.user.role`, `event.locals.member.role`, and `event.locals.orgRole`.
+ */
+export function requireRole(roles, options = {}) {
+    const allowedRoles = Array.isArray(roles) ? roles : [roles];
+    const guard = (event) => {
+        const locals = event.locals;
+        const user = locals?.user;
+        if (!user) {
+            return problemResponse({
+                status: 401,
+                title: 'Unauthorized',
+                detail: 'Authentication required before role verification.'
+            });
+        }
+        const userRole = user.role;
+        const memberRole = locals.member?.role || locals.orgRole;
+        const hasRole = (userRole && allowedRoles.includes(userRole)) ||
+            (memberRole && allowedRoles.includes(memberRole));
+        if (!hasRole) {
+            return problemResponse({
+                status: 403,
+                title: 'Forbidden',
+                detail: options.detail ||
+                    `Insufficient permissions. Requires one of: [${allowedRoles.join(', ')}].`,
+                type: 'https://yaxa.dev/errors/forbidden',
+                requiredRoles: allowedRoles
+            });
+        }
+    };
+    guard._yaxaGuard = {
+        type: 'role',
+        roles: allowedRoles,
+        options
+    };
+    return guard;
+}
+const rateLimitStore = new Map();
+// Periodic cleanup of stale rate-limit buckets (every 5 minutes)
+if (typeof setInterval !== 'undefined') {
+    const timer = setInterval(() => {
+        const now = Date.now();
+        for (const [key, bucket] of rateLimitStore.entries()) {
+            if (bucket.resetAt <= now) {
+                rateLimitStore.delete(key);
+            }
+        }
+    }, 5 * 60 * 1000);
+    if (timer && typeof timer === 'object' && 'unref' in timer) {
+        timer.unref();
+    }
+}
+/**
+ * Declarative Guard: In-memory sliding-window rate limiter.
+ * Returns 429 Too Many Requests with a `Retry-After` header when exceeded.
+ */
+export function rateLimit(options = {}) {
+    const points = options.points ?? 60;
+    const windowMs = (options.windowSeconds ?? 60) * 1000;
+    const guard = (event) => {
+        let key;
+        if (options.keyGenerator) {
+            key = options.keyGenerator(event);
+        }
+        else {
+            const userId = event.locals?.user?.id;
+            let clientIp = '127.0.0.1';
+            try {
+                if (typeof event.getClientAddress === 'function') {
+                    clientIp = event.getClientAddress();
+                }
+            }
+            catch {
+                // Fallback when running in environments without getClientAddress
+            }
+            const headerIp = event.request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ||
+                event.request.headers.get('x-real-ip');
+            const ip = headerIp || clientIp;
+            key = userId ? `user:${userId}` : `ip:${ip}`;
+        }
+        const now = Date.now();
+        let bucket = rateLimitStore.get(key);
+        if (!bucket || bucket.resetAt <= now) {
+            bucket = { tokens: points - 1, resetAt: now + windowMs };
+            rateLimitStore.set(key, bucket);
+            return;
+        }
+        if (bucket.tokens <= 0) {
+            const retryAfterSeconds = Math.max(1, Math.ceil((bucket.resetAt - now) / 1000));
+            return problemResponse({
+                status: 429,
+                title: 'Too Many Requests',
+                detail: options.detail || `Rate limit exceeded. Try again in ${retryAfterSeconds} seconds.`,
+                type: 'https://yaxa.dev/errors/rate-limit-exceeded',
+                headers: {
+                    'Retry-After': String(retryAfterSeconds),
+                    'X-RateLimit-Limit': String(points),
+                    'X-RateLimit-Remaining': '0',
+                    'X-RateLimit-Reset': String(Math.ceil(bucket.resetAt / 1000))
+                }
+            });
+        }
+        bucket.tokens -= 1;
+    };
+    guard._yaxaGuard = {
+        type: 'rateLimit',
+        options: { points, windowSeconds: options.windowSeconds ?? 60 }
+    };
+    return guard;
+}
+/**
+ * Combines multiple guards into a single composite guard.
+ */
+export function composeGuards(...guards) {
+    return async (event) => {
+        for (const guard of guards) {
+            const result = await guard(event);
+            if (result)
+                return result;
+        }
+    };
+}