@soulcraft/sdk 2.6.1 → 3.0.0

package/dist/modules/auth/request-backchannel.js

@@ -0,0 +1,206 @@
+/**
+ * @module modules/auth/request-backchannel
+ * @description Framework-agnostic OIDC back-channel logout handler using Web Standard
+ * Request/Response.
+ *
+ * Implements the OpenID Connect Back-Channel Logout 1.0 specification. When a user
+ * signs out of the central IdP (`auth.soulcraft.com`), the IdP POSTs a signed
+ * `logout_token` (HS256 JWT) to every registered product's back-channel logout
+ * endpoint. This handler verifies the token and deletes all active sessions for
+ * the identified user, ensuring immediate logout across all products.
+ *
+ * ## Protocol
+ *
+ * 1. IdP POSTs `application/x-www-form-urlencoded` body with `logout_token` field
+ * 2. Handler verifies HS256 JWT signature using the OIDC client secret
+ * 3. Handler validates standard claims: `iss`, `aud`, `events` (must contain
+ *    `http://schemas.openid.net/event/backchannel-logout`)
+ * 4. Handler deletes all better-auth sessions for the `sub` (user ID) claim
+ * 5. Returns 200 on success, 400 for malformed tokens, 401 for bad signatures
+ *
+ * ## Mounting
+ *
+ * ```typescript
+ * import { createRequestBackchannelLogoutHandler } from '@soulcraft/sdk/server'
+ *
+ * const handleLogout = createRequestBackchannelLogoutHandler({
+ *   auth,
+ *   clientSecret: process.env.SOULCRAFT_OIDC_CLIENT_SECRET!,
+ *   idpUrl: process.env.SOULCRAFT_IDP_URL!,
+ *   clientId: process.env.SOULCRAFT_OIDC_CLIENT_ID!,
+ * })
+ *
+ * // SvelteKit: export const POST = ({ request }) => handleLogout(request)
+ * // Bun:       if (url.pathname === '/api/auth/backchannel-logout') return handleLogout(req)
+ * ```
+ */
+// The OIDC back-channel logout events claim URI.
+const BACKCHANNEL_LOGOUT_EVENT = 'http://schemas.openid.net/event/backchannel-logout';
+// ─────────────────────────────────────────────────────────────────────────────
+// JWT verification helpers (Web Crypto API — no external deps)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * @description Verify an HS256 JWT using the Web Crypto API.
+ *
+ * @param token - Raw JWT string (`header.payload.signature`).
+ * @param secret - HMAC secret for signature verification.
+ * @returns The decoded payload if the signature is valid, or null.
+ */
+async function verifyHS256JWT(token, secret) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return null;
+    const [headerB64, payloadB64, sigB64] = parts;
+    // Import the HMAC key
+    let key;
+    try {
+        key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    }
+    catch {
+        return null;
+    }
+    // Verify signature over `header.payload`
+    const signingInput = `${headerB64}.${payloadB64}`;
+    let sigBytes;
+    try {
+        sigBytes = Uint8Array.from(atob(sigB64.replace(/-/g, '+').replace(/_/g, '/')), (c) => c.charCodeAt(0));
+    }
+    catch {
+        return null;
+    }
+    const valid = await crypto.subtle.verify('HMAC', key, sigBytes.buffer, new TextEncoder().encode(signingInput));
+    if (!valid)
+        return null;
+    // Decode payload
+    try {
+        const padded = payloadB64.replace(/-/g, '+').replace(/_/g, '/') +
+            '=='.slice(0, (4 - (payloadB64.length % 4)) % 4);
+        return JSON.parse(atob(padded));
+    }
+    catch {
+        return null;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// createRequestBackchannelLogoutHandler
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * @description Creates a framework-agnostic request handler for the OIDC back-channel
+ * logout endpoint.
+ *
+ * The handler:
+ * 1. Parses the `logout_token` from the form-encoded or JSON body
+ * 2. Verifies the HS256 JWT signature using the OIDC client secret
+ * 3. Validates `iss` (must match idpUrl), `aud` (must match clientId),
+ *    and `events` (must contain the back-channel logout event URI)
+ * 4. Calls `auth.api.revokeUserSessions({ body: { userId: sub } })` to
+ *    immediately invalidate all sessions for the identified user
+ * 5. Returns 200 on success, 400 for malformed/missing token, 401 for
+ *    invalid signature or failed claims validation
+ *
+ * @param config - Auth instance, client secret, IdP URL, and client ID.
+ * @returns An async request handler function `(req: Request) => Promise<Response>`.
+ *
+ * @example
+ * ```typescript
+ * import { createRequestBackchannelLogoutHandler } from '@soulcraft/sdk/server'
+ *
+ * const handleLogout = createRequestBackchannelLogoutHandler({
+ *   auth,
+ *   clientSecret: process.env.SOULCRAFT_OIDC_CLIENT_SECRET!,
+ *   idpUrl: process.env.SOULCRAFT_IDP_URL!,
+ *   clientId: process.env.SOULCRAFT_OIDC_CLIENT_ID!,
+ * })
+ *
+ * // SvelteKit +server.ts:
+ * export const POST = ({ request }) => handleLogout(request)
+ * ```
+ */
+export function createRequestBackchannelLogoutHandler(config) {
+    const idpOrigin = config.idpUrl.replace(/\/$/, '');
+    return async function requestBackchannelLogoutHandler(req) {
+        // Parse the logout_token from the body
+        let logoutToken = null;
+        try {
+            const contentType = req.headers.get('content-type') ?? '';
+            if (contentType.includes('application/x-www-form-urlencoded')) {
+                const text = await req.text();
+                const params = new URLSearchParams(text);
+                logoutToken = params.get('logout_token');
+            }
+            else {
+                // Also accept JSON body for easier testing
+                const body = await req.json();
+                logoutToken = body['logout_token'] ?? null;
+            }
+        }
+        catch {
+            return new Response(JSON.stringify({ error: 'Failed to parse request body' }), {
+                status: 400,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        if (!logoutToken || typeof logoutToken !== 'string') {
+            return new Response(JSON.stringify({ error: 'Missing logout_token' }), {
+                status: 400,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        // Verify the JWT
+        const payload = await verifyHS256JWT(logoutToken, config.clientSecret);
+        if (!payload) {
+            return new Response(JSON.stringify({ error: 'Invalid logout_token signature' }), {
+                status: 401,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        // Validate issuer
+        if (payload['iss'] !== idpOrigin) {
+            return new Response(JSON.stringify({ error: 'Invalid issuer' }), {
+                status: 401,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        // Validate audience — may be a string or array of strings
+        const aud = payload['aud'];
+        const audList = Array.isArray(aud) ? aud : [String(aud ?? '')];
+        if (!audList.includes(config.clientId)) {
+            return new Response(JSON.stringify({ error: 'Invalid audience' }), {
+                status: 401,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        // Validate events claim
+        const events = payload['events'];
+        if (!events || !(BACKCHANNEL_LOGOUT_EVENT in events)) {
+            return new Response(JSON.stringify({ error: 'Missing backchannel logout event' }), {
+                status: 400,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        // Extract the subject user ID
+        const sub = payload['sub'];
+        if (!sub || typeof sub !== 'string') {
+            return new Response(JSON.stringify({ error: 'Missing sub claim' }), {
+                status: 400,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        // Revoke all sessions for this user
+        try {
+            await config.auth.api.revokeUserSessions({ body: { userId: sub } });
+        }
+        catch (err) {
+            console.error(`[SDK/backchannel] Failed to revoke sessions for user ${sub}:`, err);
+            return new Response(JSON.stringify({ error: 'Failed to revoke sessions' }), {
+                status: 500,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        return new Response(JSON.stringify({ ok: true }), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+        });
+    };
+}
+//# sourceMappingURL=request-backchannel.js.map

package/dist/modules/auth/request-backchannel.js.map

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

package/dist/modules/auth/request-middleware.d.ts

@@ -0,0 +1,438 @@
+/**
+ * @module modules/auth/request-middleware
+ * @description Framework-agnostic auth middleware, session verification, and dev/guest
+ * utilities for Soulcraft product backends.
+ *
+ * All middleware uses Web Standard `Request`/`Response` — no framework dependency.
+ * Compatible with SvelteKit, Bun.serve, Deno, Cloudflare Workers, and any server
+ * that speaks the Web Standard APIs.
+ *
+ * ## Session verification strategies
+ *
+ * Products select the right session verifier for their deployment context:
+ *
+ * ```
+ * Production (all products):
+ *   createRemoteSessionVerifier({ idpUrl: 'https://auth.soulcraft.com' })
+ *
+ * Development (all products):
+ *   createDevSessionVerifier({ role: 'owner' })   // auto-login, no OAuth needed
+ * ```
+ *
+ * ## Middleware signature
+ *
+ * All middleware follows the universal pattern:
+ * ```
+ * (req: Request, next: () => Promise<Response>) => Promise<Response>
+ * ```
+ *
+ * ## User retrieval
+ *
+ * After middleware runs, retrieve the resolved user with `getUser(req)`:
+ * ```typescript
+ * const user = getUser(req) // SoulcraftSessionUser | null
+ * ```
+ *
+ * ## Dev and guest cookie verifiers
+ *
+ * - `createDevCookieVerifier` — reads the dev session cookie issued by
+ *   `createRequestDevLoginHandler`.
+ * - `createGuestCookieVerifier` — reads the guest session cookie issued by
+ *   `createRequestGuestSessionHandler`.
+ *
+ * @example SvelteKit hooks
+ * ```typescript
+ * import {
+ *   createRequestAuthMiddleware,
+ *   createRemoteSessionVerifier,
+ *   getUser,
+ * } from '@soulcraft/sdk/server'
+ *
+ * const verifySession = createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL! })
+ * const { requireAuth } = createRequestAuthMiddleware(verifySession)
+ *
+ * export const handle = async ({ event, resolve }) => {
+ *   const response = await requireAuth(event.request, () => resolve(event))
+ *   event.locals.user = getUser(event.request)
+ *   return response
+ * }
+ * ```
+ *
+ * @example Bun.serve
+ * ```typescript
+ * import {
+ *   createRequestAuthMiddleware,
+ *   createRemoteSessionVerifier,
+ *   getUser,
+ * } from '@soulcraft/sdk/server'
+ *
+ * const verifier = createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL! })
+ * const { optionalAuth } = createRequestAuthMiddleware(verifier)
+ *
+ * Bun.serve({
+ *   fetch: (req) => optionalAuth(req, async () => {
+ *     const user = getUser(req)
+ *     return new Response(JSON.stringify({ user: user?.email ?? 'anonymous' }))
+ *   }),
+ * })
+ * ```
+ */
+import type { SoulcraftSessionUser, SoulcraftSession } from './types.js';
+/** Minimal better-auth API surface the middleware depends on. */
+export interface BetterAuthLike {
+    api: {
+        getSession(opts: {
+            headers: Headers;
+        }): Promise<{
+            user: Record<string, unknown>;
+            session: {
+                id: string;
+                expiresAt: Date | string | number;
+            };
+        } | null>;
+    };
+}
+/**
+ * A session verifier function — the common abstraction for session resolution
+ * across all products.
+ *
+ * Returned by `createRemoteSessionVerifier` and `createDevSessionVerifier`.
+ * Pass to `createRequestAuthMiddleware` for the framework-agnostic middleware.
+ */
+export type SessionVerifier = (cookieHeader: string) => Promise<SoulcraftSession | null>;
+/**
+ * Options for `createRequestAuthMiddleware()`.
+ */
+export interface AuthMiddlewareOptions {
+    /**
+     * If true, a synthetic dev user is injected in non-production environments
+     * when a `BetterAuthLike` auth instance is provided and session lookup fails.
+     * Not used when a `SessionVerifier` function is provided — use
+     * `createDevSessionVerifier` instead for full dev auto-login in that mode.
+     * @default true
+     */
+    devAutoLogin?: boolean;
+}
+/**
+ * Options for `createRemoteSessionVerifier()`.
+ */
+export interface RemoteSessionVerifierOptions {
+    /** The central IdP base URL, e.g. `"https://auth.soulcraft.com"`. */
+    idpUrl: string;
+    /** Session cache TTL in milliseconds. Default: 30 000 (30 seconds). */
+    cacheTtlMs?: number;
+    /** Maximum cached sessions. Default: 500. */
+    cacheMax?: number;
+}
+/**
+ * Options for `createDevSessionVerifier()`.
+ */
+export interface DevSessionVerifierOptions {
+    /**
+     * The platform role to assign to the synthetic dev session.
+     * @default 'owner'
+     */
+    role?: SoulcraftSessionUser['platformRole'];
+    /**
+     * Email address for the synthetic dev user.
+     * @default 'dev@soulcraft.com'
+     */
+    email?: string;
+    /**
+     * Display name for the synthetic dev user.
+     * @default 'Dev User'
+     */
+    name?: string;
+}
+/**
+ * Options for `createRequestDevLoginHandler()`.
+ */
+export interface DevLoginHandlerOptions {
+    /**
+     * Allowed platform roles. The role must be in this list for the handler to
+     * issue a session cookie. Defaults to all non-guest platform roles.
+     * @default ['creator','viewer','customer','staff','manager','owner','learner','instructor']
+     */
+    allowedRoles?: SoulcraftSessionUser['platformRole'][];
+    /**
+     * Cookie name for the issued dev session.
+     * @default 'soulcraft_dev_session'
+     */
+    cookieName?: string;
+    /**
+     * Session cookie max-age in seconds.
+     * @default 86400 (24 hours)
+     */
+    maxAgeSeconds?: number;
+}
+/**
+ * Options for `createRequestGuestSessionHandler()`.
+ */
+export interface GuestSessionHandlerOptions {
+    /**
+     * Cookie name for the issued guest session.
+     * @default 'soulcraft_guest_session'
+     */
+    cookieName?: string;
+    /**
+     * Guest session max-age in seconds.
+     * @default 3600 (1 hour)
+     */
+    maxAgeSeconds?: number;
+    /**
+     * An optional callback invoked when a new guest session is created.
+     * Receives the generated guest ID. Useful for analytics or initializing
+     * a guest cart/basket in the product's store.
+     *
+     * @param guestId - The newly generated unique guest ID.
+     */
+    onGuestCreated?: (guestId: string) => Promise<void> | void;
+}
+/**
+ * @description A framework-agnostic middleware function that processes a Web Standard
+ * Request and either calls the next handler or short-circuits with its own Response.
+ */
+export type RequestMiddleware = (req: Request, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * @description The object returned by `createRequestAuthMiddleware()`.
+ * Provides `requireAuth` and `optionalAuth` middleware using pure Request/Response.
+ */
+export interface RequestAuthMiddleware {
+    /**
+     * Require authentication. Resolves the session from request cookies. If the
+     * session is valid, attaches the typed user to the request via WeakMap and
+     * calls `next()`. Returns HTTP 401 JSON response if unauthenticated.
+     */
+    requireAuth: RequestMiddleware;
+    /**
+     * Optional authentication. Resolves the session if one exists, but does not
+     * reject unauthenticated requests. User will be `null` for anonymous requests.
+     */
+    optionalAuth: RequestMiddleware;
+}
+/**
+ * @description Retrieves the resolved Soulcraft user attached to a Request by
+ * the request auth middleware.
+ *
+ * Returns the `SoulcraftSessionUser` if the request was authenticated, `null` if
+ * the request passed through `optionalAuth` without a session, or `null` if no
+ * middleware has processed this request.
+ *
+ * @param req - The Web Standard Request that was processed by middleware.
+ * @returns The resolved user, or null if unauthenticated or not yet processed.
+ *
+ * @example
+ * ```typescript
+ * const response = await requireAuth(request, async () => {
+ *   const user = getUser(request)!
+ *   return new Response(`Hello ${user.name}`)
+ * })
+ * ```
+ */
+export declare function getUser(req: Request): SoulcraftSessionUser | null;
+/**
+ * Creates a cached remote session verifier that proxies session lookups to
+ * the central IdP at `auth.soulcraft.com`.
+ *
+ * Used by products that operate as OIDC clients (Venue, Academy, and Workshop
+ * in production). Caches successful lookups in an LRU cache to avoid per-request
+ * HTTP round-trips to the IdP.
+ *
+ * The verifier sends the cookie header to the IdP's `/api/auth/get-session` endpoint
+ * and returns the resolved `SoulcraftSession` or `null` if the session is invalid.
+ *
+ * Pass the returned function to `createRequestAuthMiddleware`:
+ * ```typescript
+ * const verifySession = createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL! })
+ * const { requireAuth } = createRequestAuthMiddleware(verifySession)
+ * ```
+ *
+ * @param options - IdP URL, cache TTL, and max cache size.
+ * @returns A `SessionVerifier` — async function that accepts a cookie header string.
+ *
+ * @example
+ * ```typescript
+ * const verifySession = createRemoteSessionVerifier({
+ *   idpUrl: 'https://auth.soulcraft.com',
+ *   cacheTtlMs: 30_000,
+ * })
+ *
+ * const session = await verifySession(request.headers.get('cookie') ?? '')
+ * if (!session) return new Response('Unauthorized', { status: 401 })
+ * ```
+ */
+export declare function createRemoteSessionVerifier(options: RemoteSessionVerifierOptions): SessionVerifier;
+/**
+ * Creates a session verifier that always resolves to a synthetic dev session.
+ *
+ * Intended for products that run as OIDC clients but need local development auth
+ * without OAuth, network calls, SQLite, or real cookies. The returned verifier always
+ * succeeds — any request resolves to the configured synthetic user.
+ *
+ * Designed as a drop-in replacement for `createRemoteSessionVerifier` in local dev:
+ *
+ * ```typescript
+ * const verifySession = process.env.SOULCRAFT_IDP_URL
+ *   ? createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL })
+ *   : createDevSessionVerifier({ role: 'owner' })
+ *
+ * const { requireAuth } = createRequestAuthMiddleware(verifySession)
+ * ```
+ *
+ * **Never use in production.** The verifier performs no validation whatsoever.
+ *
+ * @param options - Optional synthetic user configuration.
+ * @returns A `SessionVerifier` with the same signature as `createRemoteSessionVerifier`.
+ *
+ * @example
+ * ```typescript
+ * const verifySession = process.env.SOULCRAFT_IDP_URL
+ *   ? createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL })
+ *   : createDevSessionVerifier({ role: 'owner' })
+ *
+ * export const handle = async ({ event, resolve }) => {
+ *   const session = await verifySession(event.request.headers.get('cookie') ?? '')
+ *   event.locals.session = session
+ *   return resolve(event)
+ * }
+ * ```
+ */
+export declare function createDevSessionVerifier(options?: DevSessionVerifierOptions): SessionVerifier;
+/**
+ * Creates a session verifier that reads the cookie issued by `createRequestDevLoginHandler`.
+ *
+ * Use this together with `createRequestDevLoginHandler` when you want dev role-switching
+ * (e.g. clicking "Login as Staff" in a dev UI) rather than a fixed synthetic user.
+ *
+ * The verifier decodes the base64url cookie value and returns the embedded session.
+ * Falls back to `null` (unauthenticated) if the cookie is absent or expired.
+ *
+ * ```typescript
+ * // Only one of these in dev — pick what fits your workflow:
+ *
+ * // Option A: Fixed dev user, no login UI needed
+ * const verifySession = createDevSessionVerifier({ role: 'owner' })
+ *
+ * // Option B: Role-switching dev login UI
+ * const loginHandler = createRequestDevLoginHandler({ allowedRoles: ['owner', 'staff', 'customer'] })
+ * const verifySession = createDevCookieVerifier()
+ * ```
+ *
+ * @param cookieName - Must match the `cookieName` passed to `createRequestDevLoginHandler`. Default: `'soulcraft_dev_session'`.
+ * @returns A `SessionVerifier` compatible with `createRequestAuthMiddleware`.
+ */
+export declare function createDevCookieVerifier(cookieName?: string): SessionVerifier;
+/**
+ * Creates a session verifier that reads the cookie issued by `createRequestGuestSessionHandler`.
+ *
+ * Returns the guest `SoulcraftSession` or `null` if no valid guest cookie is present.
+ * Compose with `createRemoteSessionVerifier` to allow both authenticated and guest access:
+ *
+ * ```typescript
+ * const verifyReal = createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL! })
+ * const verifyGuest = createGuestCookieVerifier()
+ *
+ * const { optionalAuth } = createRequestAuthMiddleware(async (cookie) =>
+ *   await verifyReal(cookie) ?? await verifyGuest(cookie)
+ * )
+ * ```
+ *
+ * @param cookieName - Must match the `cookieName` passed to `createRequestGuestSessionHandler`. Default: `'soulcraft_guest_session'`.
+ * @returns A `SessionVerifier` compatible with `createRequestAuthMiddleware`.
+ */
+export declare function createGuestCookieVerifier(cookieName?: string): SessionVerifier;
+/**
+ * @description Creates framework-agnostic auth middleware from a `SessionVerifier`
+ * function or a `BetterAuthLike` instance.
+ *
+ * Uses `WeakMap<Request, User>` to attach the resolved user to the request.
+ * Retrieve the resolved user after middleware with `getUser(req)`.
+ *
+ * **Preferred form (all products in OIDC-client mode):**
+ * Pass a `SessionVerifier` returned by `createRemoteSessionVerifier` or
+ * `createDevSessionVerifier`. The middleware reads the request cookie header and
+ * passes it to the verifier.
+ *
+ * **Legacy form (Workshop standalone mode):**
+ * Pass a `better-auth` instance directly. The middleware calls `auth.api.getSession`.
+ * In non-production environments and when `devAutoLogin` is enabled, a synthetic dev
+ * user is injected on failed lookups so local dev works without OAuth.
+ *
+ * @param authOrVerifier - A `better-auth` instance or a `SessionVerifier` function.
+ * @param options - Optional middleware configuration (only applies to `BetterAuthLike` form).
+ * @returns Middleware pair: `{ requireAuth, optionalAuth }`.
+ *
+ * @example Verifier form (Venue / Academy / Workshop in OIDC mode)
+ * ```typescript
+ * const verifySession = createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL! })
+ * const { requireAuth } = createRequestAuthMiddleware(verifySession)
+ *
+ * // Use in any server:
+ * const response = await requireAuth(request, () => handler(request))
+ * const user = getUser(request)!
+ * ```
+ *
+ * @example BetterAuth form (Workshop dev standalone)
+ * ```typescript
+ * import { auth } from './better-auth.js'
+ * const { requireAuth } = createRequestAuthMiddleware(auth)
+ * ```
+ */
+export declare function createRequestAuthMiddleware(authOrVerifier: BetterAuthLike | SessionVerifier, options?: AuthMiddlewareOptions): RequestAuthMiddleware;
+/**
+ * @description Creates a framework-agnostic request handler for a dev login endpoint.
+ *
+ * Mount at `/api/dev/login` to get a role-switching endpoint for local development.
+ * Accepts `?role=<platformRole>` and optional `?email=` / `?name=` / `?redirect=`
+ * query params. Issues a base64url session cookie and returns an HTTP 302 redirect.
+ *
+ * **Guards against production use:** the handler returns HTTP 404 when
+ * `NODE_ENV === 'production'` — safe to leave mounted in all environments.
+ *
+ * @param options - Allowed roles, cookie name, and max-age.
+ * @returns A request handler function `(req: Request) => Response`.
+ *
+ * @example
+ * ```typescript
+ * import { createRequestDevLoginHandler } from '@soulcraft/sdk/server'
+ *
+ * const devLogin = createRequestDevLoginHandler({ allowedRoles: ['owner', 'staff', 'customer'] })
+ *
+ * // SvelteKit: export const GET = ({ request }) => devLogin(request)
+ * // Bun:       if (url.pathname === '/api/dev/login') return devLogin(req)
+ *
+ * // Usage: GET /api/dev/login?role=staff → sets cookie + redirects to /
+ * ```
+ */
+export declare function createRequestDevLoginHandler(options?: DevLoginHandlerOptions): (req: Request) => Response;
+/**
+ * @description Creates a framework-agnostic request handler that issues a guest
+ * session cookie.
+ *
+ * Venue visitors can browse and initiate bookings without creating an account.
+ * Mount at e.g. `/api/guest/session` to issue a session cookie with
+ * `platformRole: 'guest'` and a unique guest ID on each call (if no valid guest
+ * session already exists).
+ *
+ * The guest session cookie can be verified using `createGuestCookieVerifier`,
+ * which returns a `SessionVerifier` compatible with `createRequestAuthMiddleware`.
+ *
+ * @param options - Cookie name, max-age, and optional `onGuestCreated` callback.
+ * @returns An async request handler function `(req: Request) => Promise<Response>`.
+ *
+ * @example
+ * ```typescript
+ * import { createRequestGuestSessionHandler, createGuestCookieVerifier } from '@soulcraft/sdk/server'
+ *
+ * const guestSession = createRequestGuestSessionHandler({
+ *   onGuestCreated: async (guestId) => {
+ *     await db.guests.insert({ id: guestId, createdAt: new Date() })
+ *   },
+ * })
+ *
+ * // SvelteKit: export const POST = ({ request }) => guestSession(request)
+ * // Bun:       if (url.pathname === '/api/guest/session') return guestSession(req)
+ * ```
+ */
+export declare function createRequestGuestSessionHandler(options?: GuestSessionHandlerOptions): (req: Request) => Promise<Response>;
+//# sourceMappingURL=request-middleware.d.ts.map

package/dist/modules/auth/request-middleware.d.ts.map

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