@soulcraft/sdk 2.8.0 → 3.0.1

package/dist/modules/auth/backchannel.js

@@ -1,171 +0,0 @@
-/**
- * @module modules/auth/backchannel
- * @description OIDC back-channel logout handler factory for Soulcraft product backends.
- *
- * 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 (Hono)
- *
- * ```typescript
- * import { createBackchannelLogoutHandler } from '@soulcraft/sdk/server'
- *
- * app.post('/api/auth/backchannel-logout', createBackchannelLogoutHandler({
- *   auth,
- *   clientSecret: process.env.SOULCRAFT_OIDC_CLIENT_SECRET!,
- *   idpUrl: process.env.SOULCRAFT_IDP_URL!,
- *   clientId: process.env.SOULCRAFT_OIDC_CLIENT_ID!,
- * }))
- * ```
- */
-// 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)
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * 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;
-    }
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// createBackchannelLogoutHandler
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * @description Creates a Hono route handler for the OIDC back-channel logout endpoint.
- *
- * Mount at `POST /api/auth/backchannel-logout`. The handler:
- * 1. Parses the `logout_token` from the form-encoded 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 A Hono-compatible request handler function.
- *
- * @deprecated Use `createRequestBackchannelLogoutHandler` from `request-backchannel.ts` instead.
- * The Hono-specific handler will be removed in a future major version.
- *
- * @example
- * ```typescript
- * app.post('/api/auth/backchannel-logout', createBackchannelLogoutHandler({
- *   auth,
- *   clientSecret: process.env.SOULCRAFT_OIDC_CLIENT_SECRET!,
- *   idpUrl: process.env.SOULCRAFT_IDP_URL!,
- *   clientId: process.env.SOULCRAFT_OIDC_CLIENT_ID!,
- * }))
- * ```
- */
-export function createBackchannelLogoutHandler(config) {
-    const idpOrigin = config.idpUrl.replace(/\/$/, '');
-    return async function backchannelLogoutHandler(c) {
-        // Parse the logout_token from the form-encoded body
-        let logoutToken = null;
-        try {
-            const contentType = c.req.header('content-type') ?? '';
-            if (contentType.includes('application/x-www-form-urlencoded')) {
-                const body = await c.req.parseBody();
-                logoutToken = body['logout_token'] ?? null;
-            }
-            else {
-                // Also accept JSON body for easier testing
-                const body = await c.req.json();
-                logoutToken = body['logout_token'] ?? null;
-            }
-        }
-        catch {
-            return c.json({ error: 'Failed to parse request body' }, 400);
-        }
-        if (!logoutToken || typeof logoutToken !== 'string') {
-            return c.json({ error: 'Missing logout_token' }, 400);
-        }
-        // Verify the JWT
-        const payload = await verifyHS256JWT(logoutToken, config.clientSecret);
-        if (!payload) {
-            return c.json({ error: 'Invalid logout_token signature' }, 401);
-        }
-        // Validate issuer
-        if (payload['iss'] !== idpOrigin) {
-            return c.json({ error: 'Invalid issuer' }, 401);
-        }
-        // 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 c.json({ error: 'Invalid audience' }, 401);
-        }
-        // Validate events claim
-        const events = payload['events'];
-        if (!events || !(BACKCHANNEL_LOGOUT_EVENT in events)) {
-            return c.json({ error: 'Missing backchannel logout event' }, 400);
-        }
-        // Extract the subject user ID
-        const sub = payload['sub'];
-        if (!sub || typeof sub !== 'string') {
-            return c.json({ error: 'Missing sub claim' }, 400);
-        }
-        // 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 c.json({ error: 'Failed to revoke sessions' }, 500);
-        }
-        return c.json({ ok: true }, 200);
-    };
-}
-//# sourceMappingURL=backchannel.js.map

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

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

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

@@ -1,412 +0,0 @@
-/**
- * @module modules/auth/middleware
- * @description Hono auth middleware factories, remote session verification, and
- * dev/guest session utilities for Soulcraft product backends.
- *
- * ## Session verification strategies
- *
- * All products share the same `createAuthMiddleware` factory, but each product
- * selects the right session verifier for its deployment context:
- *
- * ```
- * Production (all products):
- *   createRemoteSessionVerifier({ idpUrl: 'https://auth.soulcraft.com' })
- *
- * Development (all products):
- *   createDevSessionVerifier({ role: 'owner' })   // auto-login, no OAuth needed
- *
- * Workshop standalone (legacy / local OAuth):
- *   createAuthMiddleware(betterAuthInstance)       // BetterAuthLike overload
- * ```
- *
- * ## Dev and guest endpoint factories
- *
- * - `createDevLoginHandler` — mounts a `/api/dev/login` endpoint for role-switching
- *   during development. Issues a signed dev session cookie. No-ops in production.
- * - `createGuestSessionHandler` — mounts a `/api/guest/session` endpoint so Venue
- *   visitors can obtain a guest session (platformRole `'guest'`) for anonymous
- *   browse and booking flows, before they create an account.
- *
- * @example Production setup (Venue / Academy)
- * ```typescript
- * import { createAuthMiddleware, createRemoteSessionVerifier } from '@soulcraft/sdk/server'
- *
- * const verifySession = createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL! })
- * const { requireAuth, optionalAuth } = createAuthMiddleware(verifySession)
- *
- * app.get('/api/bookings', requireAuth, async (c) => {
- *   const user = c.get('user')! // SoulcraftSessionUser
- * })
- * ```
- */
-import type { SoulcraftSessionUser, SoulcraftSession } from './types.js';
-/** Minimal Hono-compatible context shape used by the auth middleware. */
-interface HonoContext<T extends {
-    Variables: Record<string, unknown>;
-} = {
-    Variables: Record<string, unknown>;
-}> {
-    req: {
-        raw: Request;
-        header(name: string): string | undefined;
-        query(name: string): string | undefined;
-    };
-    get<K extends keyof T['Variables']>(key: K): T['Variables'][K];
-    set<K extends keyof T['Variables']>(key: K, value: T['Variables'][K]): void;
-    json(data: unknown, status?: number): Response;
-    redirect(url: string, status?: number): Response;
-    header(name: string, value: string): void;
-}
-/** Hono-compatible Next function. */
-type HonoNext = () => Promise<void>;
-/** The Hono context variable key where the resolved user is stored. */
-export declare const AUTH_USER_KEY: "user";
-/** Hono-compatible context type with the resolved Soulcraft user variable. */
-export type AuthContext = HonoContext<{
-    Variables: {
-        [AUTH_USER_KEY]: SoulcraftSessionUser | null;
-    };
-}>;
-/** 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 in non-standalone auth mode.
- *
- * Returned by `createRemoteSessionVerifier` and `createDevSessionVerifier`.
- * `createAuthMiddleware` accepts either a `BetterAuthLike` instance (Workshop
- * standalone mode) or a `SessionVerifier` function (all other products and modes).
- */
-export type SessionVerifier = (cookieHeader: string) => Promise<SoulcraftSession | null>;
-/**
- * Options for `createAuthMiddleware()`.
- */
-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;
-}
-/**
- * The object returned by `createAuthMiddleware()`.
- */
-export interface AuthMiddleware {
-    /**
-     * Require authentication. Resolves the session from request cookies. If the
-     * session is valid, attaches the typed user to the Hono context under the
-     * `'user'` key and calls `next()`. Returns HTTP 401 if unauthenticated.
-     */
-    requireAuth: (c: AuthContext, next: HonoNext) => Promise<void | Response>;
-    /**
-     * Optional authentication. Resolves the session if one exists, but does not
-     * reject unauthenticated requests. User will be `null` for anonymous requests.
-     */
-    optionalAuth: (c: AuthContext, next: HonoNext) => Promise<void | Response>;
-}
-/**
- * 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 `createDevLoginHandler()`.
- */
-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 `createGuestSessionHandler()`.
- */
-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;
-}
-/**
- * Creates Hono auth middleware from a `SessionVerifier` function or a `BetterAuthLike`
- * instance.
- *
- * **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.
- *
- * Both forms return identical `{ requireAuth, optionalAuth }` middleware.
- *
- * @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 } = createAuthMiddleware(verifySession)
- * ```
- *
- * @deprecated Use `createRequestAuthMiddleware` from `request-middleware.ts` instead.
- * The Hono-specific middleware will be removed in a future major version.
- *
- * @example BetterAuth form (Workshop dev standalone)
- * ```typescript
- * import { auth } from './better-auth.js'
- * const { requireAuth } = createAuthMiddleware(auth)
- * ```
- */
-export declare function createAuthMiddleware(authOrVerifier: BetterAuthLike | SessionVerifier, options?: AuthMiddlewareOptions): AuthMiddleware;
-/**
- * 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 directly to `createAuthMiddleware`:
- * ```typescript
- * const verifySession = createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL! })
- * const { requireAuth } = createAuthMiddleware(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(c.req.header('cookie') ?? '')
- * if (!session) return c.json({ error: 'Unauthorized' }, 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 } = createAuthMiddleware(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 Hono 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=`
- * query params. Issues a signed base64url session cookie that `createAuthMiddleware`
- * (when used with a `SessionVerifier` that reads dev cookies) can resolve.
- *
- * **Guards against production use:** the handler returns HTTP 404 when
- * `NODE_ENV === 'production'` — it is safe to leave mounted in all environments.
- *
- * @param options - Allowed roles, cookie name, and max-age.
- * @returns A Hono-compatible request handler `(c: HonoContext) => Response`.
- *
- * @deprecated Use `createRequestDevLoginHandler` from `request-middleware.ts` instead.
- * The Hono-specific handler will be removed in a future major version.
- *
- * @example
- * ```typescript
- * import { createDevLoginHandler } from '@soulcraft/sdk/server'
- *
- * // In your Hono server setup:
- * app.get('/api/dev/login', createDevLoginHandler({ allowedRoles: ['owner', 'staff', 'customer'] }))
- *
- * // Usage: GET /api/dev/login?role=staff → sets cookie + redirects to /
- * ```
- */
-export declare function createDevLoginHandler(options?: DevLoginHandlerOptions): (c: HonoContext) => Response | Promise<Response>;
-/**
- * Creates a session verifier that reads the cookie issued by `createDevLoginHandler`.
- *
- * Use this together with `createDevLoginHandler` 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
- * app.get('/api/dev/login', createDevLoginHandler({ allowedRoles: ['owner', 'staff', 'customer'] }))
- * const verifySession = createDevCookieVerifier()
- * ```
- *
- * @param cookieName - Must match the `cookieName` passed to `createDevLoginHandler`. Default: `'soulcraft_dev_session'`.
- * @returns A `SessionVerifier` compatible with `createAuthMiddleware`.
- */
-export declare function createDevCookieVerifier(cookieName?: string): SessionVerifier;
-/**
- * Creates a Hono request handler that issues a guest session cookie.
- *
- * Venue visitors can browse and initiate bookings without creating an account.
- * This handler mounts at e.g. `/api/guest/session` and issues 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 `createAuthMiddleware`.
- *
- * @param options - Cookie name, max-age, and optional `onGuestCreated` callback.
- * @returns A Hono-compatible request handler.
- *
- * @deprecated Use `createRequestGuestSessionHandler` from `request-middleware.ts` instead.
- * The Hono-specific handler will be removed in a future major version.
- *
- * @example
- * ```typescript
- * import { createGuestSessionHandler, createGuestCookieVerifier, createAuthMiddleware } from '@soulcraft/sdk/server'
- *
- * // Issue guest sessions
- * app.post('/api/guest/session', createGuestSessionHandler({
- *   onGuestCreated: async (guestId) => {
- *     await db.guests.insert({ id: guestId, createdAt: new Date() })
- *   },
- * }))
- *
- * // Verify guest sessions in optional auth (guests can browse)
- * const verifyGuest = createGuestCookieVerifier()
- * const verifySession = createRemoteSessionVerifier({ idpUrl: process.env.SOULCRAFT_IDP_URL! })
- *
- * // Compose: check real session first, fall back to guest
- * const { optionalAuth } = createAuthMiddleware(async (cookie) =>
- *   await verifySession(cookie) ?? await verifyGuest(cookie)
- * )
- * ```
- */
-export declare function createGuestSessionHandler(options?: GuestSessionHandlerOptions): (c: HonoContext) => Promise<Response>;
-/**
- * Creates a session verifier that reads the cookie issued by `createGuestSessionHandler`.
- *
- * 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 } = createAuthMiddleware(async (cookie) =>
- *   await verifyReal(cookie) ?? await verifyGuest(cookie)
- * )
- * ```
- *
- * @param cookieName - Must match the `cookieName` passed to `createGuestSessionHandler`. Default: `'soulcraft_guest_session'`.
- * @returns A `SessionVerifier` compatible with `createAuthMiddleware`.
- */
-export declare function createGuestCookieVerifier(cookieName?: string): SessionVerifier;
-export {};
-//# sourceMappingURL=middleware.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../src/modules/auth/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAOxE,yEAAyE;AACzE,UAAU,WAAW,CAAC,CAAC,SAAS;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE;IAC7G,GAAG,EAAE;QAAE,GAAG,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;QAAC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAA;IACxG,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,WAAW,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9D,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,WAAW,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IAC3E,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAChD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1C;AAED,qCAAqC;AACrC,KAAK,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;AAMnC,uEAAuE;AACvE,eAAO,MAAM,aAAa,EAAG,MAAe,CAAA;AAE5C,8EAA8E;AAC9E,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC;IAAE,SAAS,EAAE;QAAE,CAAC,aAAa,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAA;KAAE,CAAA;CAAE,CAAC,CAAA;AAEtG,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE;QACH,UAAU,CAAC,IAAI,EAAE;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,GAAG,OAAO,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAAC,OAAO,EAAE;gBAAE,EAAE,EAAE,MAAM,CAAC;gBAAC,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAA;aAAE,CAAA;SAAE,GAAG,IAAI,CAAC,CAAA;KACtJ,CAAA;CACF;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;AAExF;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC,CAAA;IAEzE;;;OAGG;IACH,YAAY,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC,CAAA;CAC3E;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAA;IACd,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,IAAI,CAAC,EAAE,oBAAoB,CAAC,cAAc,CAAC,CAAA;IAC3C;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAC,cAAc,CAAC,EAAE,CAAA;IACrD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC3D;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,cAAc,GAAG,eAAe,EAChD,OAAO,GAAE,qBAA0B,GAClC,cAAc,CA0EhB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,4BAA4B,GACpC,eAAe,CAkEjB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,yBAA8B,GACtC,eAAe,CAsBjB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,sBAA2B,GACnC,CAAC,CAAC,EAAE,WAAW,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CA2DlD;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,SAA0B,GACnC,eAAe,CAMjB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,0BAA+B,GACvC,CAAC,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAkDvC;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,SAA4B,GACrC,eAAe,CAMjB"}