@venturekit/auth 0.0.0-dev.20260701100017 → 0.0.0-dev.20260704225856

package/dist/server/handoff-routes.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Session handoff route factory — the SSO flow that moves a session
+ * between hosts that cannot share cookies (different registrable
+ * domains, e.g. a platform subdomain and a white-label custom domain).
+ *
+ * Emits two Lambda handlers:
+ *
+ *   - `start`    — `POST /auth/handoff/start` on the host WITH a session.
+ *                  Body `{ target: "https://tenant.io/dashboard" }`.
+ *                  Verifies the session cookies, runs the app's
+ *                  `authorize` hook (membership check — THE gate that
+ *                  keeps foreign domains out), stashes a single-use
+ *                  code via the app's `HandoffStore`, and returns
+ *                  `{ url }` for the SPA to navigate to.
+ *   - `complete` — `GET /auth/handoff?code=…&next=…` on the TARGET
+ *                  host (a top-level browser navigation, typically
+ *                  through the app's same-origin API proxy). Redeems
+ *                  the code, mints fresh tokens from the stashed
+ *                  refresh token, sets first-party session cookies for
+ *                  THIS host, and 302-redirects to `next`. Every
+ *                  failure redirects to `failurePath` — the user is
+ *                  mid-navigation, JSON errors would dead-end them.
+ *
+ * The refresh token moves server→store→server; only the opaque
+ * single-use code (256-bit, 60s TTL, host-bound, hashed at rest)
+ * transits the browser. See `handoff.ts` for the security model.
+ */
+import { type APIGatewayProxyEventV2, type APIGatewayProxyResultV2, type Context as LambdaContext } from 'aws-lambda';
+import { type RequestContext } from '@venturekit/runtime';
+import { type CookieOptions } from './cookies.js';
+import { type AuthServerConfig } from './config.js';
+import { type HandoffStore } from './handoff.js';
+/** Body shape for the `start` route. */
+export interface HandoffStartBody {
+    /**
+     * Absolute URL the user wants to land on, on the other host —
+     * `https://tenant.io/dashboard`. The host is what `authorize` gets
+     * to approve; path + query become the post-handoff redirect.
+     */
+    target: string;
+}
+/** Argument bag for the app's `authorize` hook. */
+export interface HandoffAuthorizeArgs {
+    /** Cognito `sub` from the verified id token. */
+    userSub: string;
+    /** All claims of the verified id token. */
+    claims: Record<string, unknown>;
+    /** Host (lowercased, port included) the user wants a session on. */
+    targetHost: string;
+    /** Live request context (tenancy middleware output, headers, …). */
+    ctx: RequestContext;
+}
+export interface SessionHandoffRoutesOptions {
+    /** App-provided single-use code storage. See {@link HandoffStore}. */
+    store: HandoffStore;
+    /**
+     * THE authorization gate: may this user get a session on
+     * `targetHost`? Apps typically map the host to a tenant and check
+     * membership. Return `false` to refuse (403). Unknown hosts MUST
+     * return `false` — this hook is the only thing standing between a
+     * session and an arbitrary domain.
+     */
+    authorize: (args: HandoffAuthorizeArgs) => Promise<boolean>;
+    /**
+     * Builds the absolute URL of the `complete` endpoint on a target
+     * host, WITHOUT query string. Defaults to
+     * `https://<targetHost><completePath>`. Override in dev (http, ports)
+     * or when the browser-visible API prefix differs per host.
+     */
+    completeUrl?: (targetHost: string, ctx: RequestContext) => string;
+    /**
+     * Browser-visible path of the `complete` route used by the default
+     * `completeUrl`. Include the app's proxy prefix if there is one
+     * (mycohort: `/api/auth/handoff`). Default `/auth/handoff`.
+     */
+    completePath?: string;
+    /**
+     * Where `complete` redirects when redemption fails (missing /
+     * expired / wrong-host code). Relative path on the target host.
+     * Default `/login`.
+     */
+    failurePath?: string;
+    /**
+     * Cookie attributes for the session cookies minted on the target
+     * host — same semantics as the federated factory: pass a function
+     * to resolve per request (Domain depends on the host being landed
+     * on). Defaults to VK's host-only defaults.
+     */
+    cookieOptions?: CookieOptions | ((ctx: RequestContext) => CookieOptions);
+    /**
+     * Resolve the current (browser-facing) host on the `complete` leg.
+     *
+     * NOTE: `complete` is a top-level GET navigation — there is no
+     * `origin` header and `referer` still points at the ISSUING host,
+     * so the general-purpose `getRequestHost()` chain would pick the
+     * wrong host. The default here reads `x-forwarded-host` (set by
+     * same-origin proxies) then `host`. Override when your proxy uses
+     * a different header.
+     */
+    resolveRequestHost?: (ctx: RequestContext) => string;
+    /** Code lifetime in seconds. Default {@link DEFAULT_HANDOFF_TTL_SECONDS}. */
+    ttlSeconds?: number;
+    /** Explicit Cognito config; defaults to env-var loading per request. */
+    config?: AuthServerConfig;
+    /** Extra middleware for both routes (tenancy, rate limiting, …). */
+    middleware?: import('@venturekit/runtime').Middleware<RequestContext>[];
+}
+/** Route bundle returned by {@link createSessionHandoffRoutes}. */
+export interface SessionHandoffRoutes {
+    start: (event: APIGatewayProxyEventV2, context: LambdaContext) => Promise<APIGatewayProxyResultV2>;
+    complete: (event: APIGatewayProxyEventV2, context: LambdaContext) => Promise<APIGatewayProxyResultV2>;
+}
+/** Default browser-facing path of the `complete` route. */
+export declare const DEFAULT_HANDOFF_COMPLETE_PATH = "/auth/handoff";
+/**
+ * Build the session-handoff route pair. See module docs for the flow.
+ *
+ * @example
+ * ```typescript
+ * export const handoffRoutes = createSessionHandoffRoutes({
+ *   store: postgresHandoffStore,
+ *   authorize: async ({ userSub, targetHost }) =>
+ *     isApprovedMemberOfTenantOwning(targetHost, userSub),
+ *   completeUrl: (host) => `https://${host}/api/auth/handoff`,
+ *   cookieOptions: (ctx) => sessionCookieOptions(getRequestHost(ctx)),
+ * });
+ * ```
+ */
+export declare function createSessionHandoffRoutes(options: SessionHandoffRoutesOptions): SessionHandoffRoutes;
+//# sourceMappingURL=handoff-routes.d.ts.map

package/dist/server/handoff-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-routes.d.ts","sourceRoot":"","sources":["../../src/server/handoff-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,OAAO,IAAI,aAAa,EAC9B,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,KAAK,cAAc,EAQpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,KAAK,aAAa,EAKnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EACL,KAAK,YAAY,EAIlB,MAAM,cAAc,CAAC;AAItB,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mDAAmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,GAAG,EAAE,cAAc,CAAC;CACrB;AAED,MAAM,WAAW,2BAA2B;IAC1C,sEAAsE;IACtE,KAAK,EAAE,YAAY,CAAC;IACpB;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,IAAI,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5D;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,KAAK,MAAM,CAAC;IAClE;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,aAAa,GAAG,CAAC,CAAC,GAAG,EAAE,cAAc,KAAK,aAAa,CAAC,CAAC;IACzE;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,CAAC;IACrD,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,oEAAoE;IACpE,UAAU,CAAC,EAAE,OAAO,qBAAqB,EAAE,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;CACzE;AAED,mEAAmE;AACnE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,CACL,KAAK,EAAE,sBAAsB,EAC7B,OAAO,EAAE,aAAa,KACnB,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACtC,QAAQ,EAAE,CACR,KAAK,EAAE,sBAAsB,EAC7B,OAAO,EAAE,aAAa,KACnB,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACvC;AAED,2DAA2D;AAC3D,eAAO,MAAM,6BAA6B,kBAAkB,CAAC;AA6D7D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,oBAAoB,CAgJtB"}

package/dist/server/handoff-routes.js

@@ -0,0 +1,178 @@
+import { BadRequestError, ForbiddenError, UnauthorizedError, handler, setCookie, rawResult, redirect, } from '@venturekit/runtime';
+import { buildSessionCookies, readCookieFromHeader, ID_TOKEN_COOKIE, REFRESH_TOKEN_COOKIE, } from './cookies.js';
+import { loadAuthServerConfig } from './config.js';
+import { DEFAULT_HANDOFF_TTL_SECONDS, issueHandoffCode, redeemHandoffCode, } from './handoff.js';
+import { refreshSession } from './refresh.js';
+import { verifyAndDecode } from './verify.js';
+/** Default browser-facing path of the `complete` route. */
+export const DEFAULT_HANDOFF_COMPLETE_PATH = '/auth/handoff';
+function headersOf(ctx) {
+    return (ctx.rawEvent
+        ?.headers ?? {});
+}
+function headerValue(headers, name) {
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name && value)
+            return value;
+    }
+    return undefined;
+}
+/** Default current-host resolution for the `complete` navigation leg. */
+function defaultResolveRequestHost(ctx) {
+    const headers = headersOf(ctx);
+    return (headerValue(headers, 'x-forwarded-host') ??
+        headerValue(headers, 'host') ??
+        '');
+}
+/**
+ * `next` must be a same-host path: absolute (`/dashboard`), not
+ * protocol-relative (`//evil.io`), not an absolute URL, and not a
+ * backslash variant (`/\evil.io` — browsers normalize `\` to `/` in
+ * URLs, turning it protocol-relative). Otherwise `complete` would be
+ * an open redirector.
+ */
+function sanitizeNextPath(next, fallback) {
+    if (!next)
+        return fallback;
+    if (!/^\/(?![/\\])/.test(next))
+        return fallback;
+    return next;
+}
+/**
+ * Redirect for the browser-navigation legs, with cache/referrer
+ * hygiene: the request URL carries the one-time code, so the response
+ * must never be cached by shared caches (`no-store`) and the landing
+ * page must not leak the code onward via `Referer`.
+ */
+function navRedirect(location) {
+    const base = redirect(location);
+    const result = typeof base === 'string' ? { statusCode: 302, body: '' } : base;
+    return rawResult({
+        ...result,
+        headers: {
+            ...(typeof base === 'string' ? {} : base.headers),
+            'Cache-Control': 'no-store',
+            'Referrer-Policy': 'no-referrer',
+        },
+    });
+}
+/**
+ * Build the session-handoff route pair. See module docs for the flow.
+ *
+ * @example
+ * ```typescript
+ * export const handoffRoutes = createSessionHandoffRoutes({
+ *   store: postgresHandoffStore,
+ *   authorize: async ({ userSub, targetHost }) =>
+ *     isApprovedMemberOfTenantOwning(targetHost, userSub),
+ *   completeUrl: (host) => `https://${host}/api/auth/handoff`,
+ *   cookieOptions: (ctx) => sessionCookieOptions(getRequestHost(ctx)),
+ * });
+ * ```
+ */
+export function createSessionHandoffRoutes(options) {
+    const { store, authorize, completePath = DEFAULT_HANDOFF_COMPLETE_PATH, failurePath = '/login', ttlSeconds = DEFAULT_HANDOFF_TTL_SECONDS, resolveRequestHost = defaultResolveRequestHost, middleware: extraMiddleware = [], } = options;
+    const cookieOptionsFor = (ctx) => {
+        if (!options.cookieOptions)
+            return {};
+        return typeof options.cookieOptions === 'function'
+            ? options.cookieOptions(ctx)
+            : options.cookieOptions;
+    };
+    const buildCompleteUrl = (targetHost, ctx) => options.completeUrl
+        ? options.completeUrl(targetHost, ctx)
+        : `https://${targetHost}${completePath}`;
+    // ─── start ──────────────────────────────────────────────
+    const start = handler(async (body, ctx) => {
+        if (!body?.target) {
+            throw new BadRequestError('target is required');
+        }
+        let target;
+        try {
+            target = new URL(body.target);
+        }
+        catch {
+            throw new BadRequestError('target must be an absolute URL');
+        }
+        if (target.protocol !== 'https:' && target.protocol !== 'http:') {
+            throw new BadRequestError('target must be http(s)');
+        }
+        const targetHost = target.host.toLowerCase();
+        const nextPath = sanitizeNextPath(`${target.pathname}${target.search}`, '/');
+        // The session being handed off — both cookies are required: the
+        // id token proves WHO is asking, the refresh token is what the
+        // target host will mint its session from.
+        const cookieHeader = ctx.rawEvent.headers?.['cookie'] ?? ctx.rawEvent.headers?.['Cookie'] ?? null;
+        const idToken = readCookieFromHeader(cookieHeader, ID_TOKEN_COOKIE);
+        const refreshToken = readCookieFromHeader(cookieHeader, REFRESH_TOKEN_COOKIE);
+        if (!idToken || !refreshToken) {
+            throw new UnauthorizedError('No session to hand off');
+        }
+        const config = options.config ?? loadAuthServerConfig();
+        const claims = await verifyAndDecode(idToken, {
+            userPoolId: config.userPoolId,
+            clientId: config.appClientId,
+            tokenUse: 'id',
+            endpoint: config.endpoint,
+        });
+        const userSub = claims && typeof claims['sub'] === 'string' ? claims['sub'] : null;
+        if (!userSub) {
+            throw new UnauthorizedError('Invalid session');
+        }
+        const allowed = await authorize({
+            userSub,
+            claims: claims,
+            targetHost,
+            ctx,
+        });
+        if (!allowed) {
+            throw new ForbiddenError('Not authorized for this destination');
+        }
+        const code = await issueHandoffCode(store, { sub: userSub, refreshToken, targetHost }, ttlSeconds);
+        const url = `${buildCompleteUrl(targetHost, ctx)}?code=${encodeURIComponent(code)}` +
+            `&next=${encodeURIComponent(nextPath)}`;
+        return { url };
+    }, {
+        status: 200,
+        middleware: extraMiddleware,
+    });
+    // ─── complete ───────────────────────────────────────────
+    const complete = handler(async (_body, ctx) => {
+        const code = ctx.queryParams?.['code'] ?? '';
+        const next = sanitizeNextPath(ctx.queryParams?.['next'], '/');
+        const currentHost = resolveRequestHost(ctx);
+        const payload = await redeemHandoffCode(store, code, currentHost);
+        if (!payload) {
+            // Missing / expired / wrong-host code. The user is mid-
+            // navigation on the target host: land them on the login page,
+            // never on a JSON error.
+            return navRedirect(failurePath);
+        }
+        const config = options.config ?? loadAuthServerConfig();
+        let tokens;
+        try {
+            tokens = await refreshSession(payload.refreshToken, config);
+        }
+        catch {
+            return navRedirect(failurePath);
+        }
+        // `refreshSession` never returns a refresh token (Cognito does
+        // not rotate it) — carry the original over so the target host
+        // can refresh on its own later.
+        const cookieOptions = cookieOptionsFor(ctx);
+        const sessionCookies = buildSessionCookies({
+            idToken: tokens.idToken,
+            accessToken: tokens.accessToken,
+            refreshToken: payload.refreshToken,
+            expiresIn: tokens.expiresIn,
+        }, cookieOptions);
+        for (const cookie of sessionCookies) {
+            setCookie(ctx, cookie);
+        }
+        return navRedirect(next);
+    }, {
+        middleware: extraMiddleware,
+    });
+    return { start, complete };
+}
+//# sourceMappingURL=handoff-routes.js.map

package/dist/server/handoff-routes.js.map

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

package/dist/server/handoff.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Cross-domain session handoff — core primitives.
+ *
+ * **Why this exists.** Browser cookies cannot span registrable domains:
+ * a session on `app.platform.com` can never be read by `tenant.io`, no
+ * matter what `Domain=` attribute it carries. Multi-tenant products
+ * with white-label custom domains therefore need an SSO-style handoff
+ * to "move" a session between hosts: the host WITH a session mints a
+ * short-lived, single-use **handoff code** bound to the target host;
+ * the target host redeems it server-side and mints its own first-party
+ * cookies. The user's refresh token travels server-to-server through
+ * the app's {@link HandoffStore} — only the opaque code ever appears
+ * in a URL.
+ *
+ * **Security properties**
+ *   - Codes are 256-bit `crypto.randomBytes` values — unguessable.
+ *   - The store is keyed by the **SHA-256 hash** of the code, so a
+ *     leaked store (DB dump, logs) cannot be replayed into sessions.
+ *   - Codes are single-use: {@link HandoffStore.take} must delete
+ *     atomically (e.g. SQL `DELETE … RETURNING`).
+ *   - Codes expire after {@link DEFAULT_HANDOFF_TTL_SECONDS}; expiry is
+ *     enforced BOTH by the store's TTL mechanism and re-checked here on
+ *     redeem, so a lagging store cleanup can't extend the window.
+ *   - Codes are bound to the target host at issue time; redeeming on
+ *     any other host fails — and a wrong-host attempt BURNS the code,
+ *     so it cannot be probed and then replayed on the right host.
+ *     Combined with the route factory's `authorize` hook this
+ *     guarantees a session can only ever materialize on hosts the app
+ *     explicitly approved for THIS user.
+ *   - The `complete` redirects carry `Cache-Control: no-store` and
+ *     `Referrer-Policy: no-referrer` so the code-bearing URL never
+ *     sits in a shared cache and never leaks via `Referer`.
+ *
+ * **Residual risks — know what this does NOT protect against**
+ *   - *Login CSRF*: like every URL-based SSO handoff (OAuth code flow
+ *     included), an attacker can mint a code for THEIR OWN session and
+ *     lure a victim into opening the complete URL, logging the victim
+ *     in as the attacker on that host. The 60s single-use window and
+ *     the membership-gated `authorize` hook narrow this to hosts the
+ *     ATTACKER belongs to; apps for which this matters should show the
+ *     signed-in identity prominently post-handoff.
+ *   - *Store contents*: payloads hold live refresh tokens. The hashed
+ *     key prevents lookup-by-code, rows die in ≤60s, but a hostile DBA
+ *     window exists — encrypt payloads at rest if that is in scope.
+ *
+ * The route-level flow lives in `handoff-routes.ts`
+ * ({@link createSessionHandoffRoutes}); apps supply the storage
+ * (Postgres / DynamoDB / Redis — anything with atomic take).
+ */
+/** Default lifetime of a handoff code: one browser redirect, not more. */
+export declare const DEFAULT_HANDOFF_TTL_SECONDS = 60;
+/**
+ * What the issuing host stashes for the target host to redeem.
+ *
+ * Contains the user's **refresh token** — treat stored payloads as
+ * secrets (the code-hash key already prevents lookup-by-code, and rows
+ * are deleted on redeem / expiry, but encrypt at rest if your store's
+ * threat model calls for it).
+ */
+export interface HandoffPayload {
+    /** Cognito subject of the user the session belongs to. */
+    sub: string;
+    /** The session's refresh token — used by the target host to mint fresh tokens. */
+    refreshToken: string;
+    /** Host (including port, lowercased) the code was issued FOR. */
+    targetHost: string;
+    /** Epoch millis after which the code is dead even if the store still has it. */
+    expiresAt: number;
+}
+/**
+ * Storage the app provides for in-flight handoff codes.
+ *
+ * Keys are code **hashes** (see module docs). Implementations must make
+ * `take` atomic — two concurrent redeems of the same code must never
+ * both succeed:
+ *
+ * ```sql
+ * -- Postgres example
+ * DELETE FROM auth_handoff_codes WHERE code_hash = $1 RETURNING payload;
+ * ```
+ */
+export interface HandoffStore {
+    /** Persist a payload under `codeHash`, expiring after `ttlSeconds`. */
+    put(codeHash: string, payload: HandoffPayload, ttlSeconds: number): Promise<void>;
+    /** Atomically fetch AND delete. Returns null when absent (or already taken). */
+    take(codeHash: string): Promise<HandoffPayload | null>;
+}
+/** Generate an unguessable handoff code (256-bit, base64url). */
+export declare function generateHandoffCode(): string;
+/** Hash a handoff code for use as a store key. */
+export declare function hashHandoffCode(code: string): string;
+/**
+ * Issue a handoff code for `targetHost`.
+ *
+ * @returns the RAW code — put it in the redirect URL. Only its hash
+ *          touches the store.
+ */
+export declare function issueHandoffCode(store: HandoffStore, input: {
+    sub: string;
+    refreshToken: string;
+    targetHost: string;
+}, ttlSeconds?: number): Promise<string>;
+/**
+ * Redeem a handoff code on `currentHost`.
+ *
+ * Returns the payload when the code exists, hasn't expired, and was
+ * issued for exactly this host — null otherwise. The code is consumed
+ * either way (single-use: a failed redeem must burn it too, so an
+ * attacker can't probe).
+ */
+export declare function redeemHandoffCode(store: HandoffStore, code: string, currentHost: string): Promise<HandoffPayload | null>;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/server/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../src/server/handoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH,0EAA0E;AAC1E,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,gFAAgF;IAChF,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CACxD;AAED,iEAAiE;AACjE,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,kDAAkD;AAClD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAOD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAChE,UAAU,GAAE,MAAoC,GAC/C,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAOhC"}

package/dist/server/handoff.js

@@ -0,0 +1,102 @@
+/**
+ * Cross-domain session handoff — core primitives.
+ *
+ * **Why this exists.** Browser cookies cannot span registrable domains:
+ * a session on `app.platform.com` can never be read by `tenant.io`, no
+ * matter what `Domain=` attribute it carries. Multi-tenant products
+ * with white-label custom domains therefore need an SSO-style handoff
+ * to "move" a session between hosts: the host WITH a session mints a
+ * short-lived, single-use **handoff code** bound to the target host;
+ * the target host redeems it server-side and mints its own first-party
+ * cookies. The user's refresh token travels server-to-server through
+ * the app's {@link HandoffStore} — only the opaque code ever appears
+ * in a URL.
+ *
+ * **Security properties**
+ *   - Codes are 256-bit `crypto.randomBytes` values — unguessable.
+ *   - The store is keyed by the **SHA-256 hash** of the code, so a
+ *     leaked store (DB dump, logs) cannot be replayed into sessions.
+ *   - Codes are single-use: {@link HandoffStore.take} must delete
+ *     atomically (e.g. SQL `DELETE … RETURNING`).
+ *   - Codes expire after {@link DEFAULT_HANDOFF_TTL_SECONDS}; expiry is
+ *     enforced BOTH by the store's TTL mechanism and re-checked here on
+ *     redeem, so a lagging store cleanup can't extend the window.
+ *   - Codes are bound to the target host at issue time; redeeming on
+ *     any other host fails — and a wrong-host attempt BURNS the code,
+ *     so it cannot be probed and then replayed on the right host.
+ *     Combined with the route factory's `authorize` hook this
+ *     guarantees a session can only ever materialize on hosts the app
+ *     explicitly approved for THIS user.
+ *   - The `complete` redirects carry `Cache-Control: no-store` and
+ *     `Referrer-Policy: no-referrer` so the code-bearing URL never
+ *     sits in a shared cache and never leaks via `Referer`.
+ *
+ * **Residual risks — know what this does NOT protect against**
+ *   - *Login CSRF*: like every URL-based SSO handoff (OAuth code flow
+ *     included), an attacker can mint a code for THEIR OWN session and
+ *     lure a victim into opening the complete URL, logging the victim
+ *     in as the attacker on that host. The 60s single-use window and
+ *     the membership-gated `authorize` hook narrow this to hosts the
+ *     ATTACKER belongs to; apps for which this matters should show the
+ *     signed-in identity prominently post-handoff.
+ *   - *Store contents*: payloads hold live refresh tokens. The hashed
+ *     key prevents lookup-by-code, rows die in ≤60s, but a hostile DBA
+ *     window exists — encrypt payloads at rest if that is in scope.
+ *
+ * The route-level flow lives in `handoff-routes.ts`
+ * ({@link createSessionHandoffRoutes}); apps supply the storage
+ * (Postgres / DynamoDB / Redis — anything with atomic take).
+ */
+import { createHash, randomBytes } from 'node:crypto';
+/** Default lifetime of a handoff code: one browser redirect, not more. */
+export const DEFAULT_HANDOFF_TTL_SECONDS = 60;
+/** Generate an unguessable handoff code (256-bit, base64url). */
+export function generateHandoffCode() {
+    return randomBytes(32).toString('base64url');
+}
+/** Hash a handoff code for use as a store key. */
+export function hashHandoffCode(code) {
+    return createHash('sha256').update(code).digest('base64url');
+}
+/** Lowercase a host for comparison. Ports are significant (dev hosts). */
+function normalizeHost(host) {
+    return host.trim().toLowerCase();
+}
+/**
+ * Issue a handoff code for `targetHost`.
+ *
+ * @returns the RAW code — put it in the redirect URL. Only its hash
+ *          touches the store.
+ */
+export async function issueHandoffCode(store, input, ttlSeconds = DEFAULT_HANDOFF_TTL_SECONDS) {
+    const code = generateHandoffCode();
+    const payload = {
+        sub: input.sub,
+        refreshToken: input.refreshToken,
+        targetHost: normalizeHost(input.targetHost),
+        expiresAt: Date.now() + ttlSeconds * 1000,
+    };
+    await store.put(hashHandoffCode(code), payload, ttlSeconds);
+    return code;
+}
+/**
+ * Redeem a handoff code on `currentHost`.
+ *
+ * Returns the payload when the code exists, hasn't expired, and was
+ * issued for exactly this host — null otherwise. The code is consumed
+ * either way (single-use: a failed redeem must burn it too, so an
+ * attacker can't probe).
+ */
+export async function redeemHandoffCode(store, code, currentHost) {
+    if (!code)
+        return null;
+    const payload = await store.take(hashHandoffCode(code));
+    if (!payload)
+        return null;
+    if (Date.now() > payload.expiresAt)
+        return null;
+    if (payload.targetHost !== normalizeHost(currentHost))
+        return null;
+    return payload;
+}
+//# sourceMappingURL=handoff.js.map

package/dist/server/handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.js","sourceRoot":"","sources":["../../src/server/handoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEtD,0EAA0E;AAC1E,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAwC9C,iEAAiE;AACjE,MAAM,UAAU,mBAAmB;IACjC,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAC/C,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AAC/D,CAAC;AAED,0EAA0E;AAC1E,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAmB,EACnB,KAAgE,EAChE,aAAqB,2BAA2B;IAEhD,MAAM,IAAI,GAAG,mBAAmB,EAAE,CAAC;IACnC,MAAM,OAAO,GAAmB;QAC9B,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,UAAU,EAAE,aAAa,CAAC,KAAK,CAAC,UAAU,CAAC;QAC3C,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,GAAG,IAAI;KAC1C,CAAC;IACF,MAAM,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAmB,EACnB,IAAY,EACZ,WAAmB;IAEnB,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IACxD,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAChD,IAAI,OAAO,CAAC,UAAU,KAAK,aAAa,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IACnE,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/server/index.d.ts

@@ -34,19 +34,26 @@ export type { AdminInviteUserInput, AdminInviteUserResult, AdminUpdateAttributes
 export { adminInviteUser, adminUpdateUserAttributes, adminDisableUser, adminEnableUser, adminDeleteUser, } from './admin-users.js';
 export type { RefreshResult } from './refresh.js';
 export { refreshSession } from './refresh.js';
-export { revokeRefreshToken } from './revoke.js';
+export { revokeRefreshToken, globalSignOut } from './revoke.js';
+export type { EnsureUserForVerifiedEmailInput, EnsureUserForVerifiedEmailResult, } from './passwordless.js';
+export { ensureUserForVerifiedEmail, mintSessionForVerifiedEmail, } from './passwordless.js';
 export type { ChangePasswordInput } from './change-password.js';
 export { changePassword } from './change-password.js';
 export type { ForgotPasswordInput, ForgotPasswordResult, ConfirmForgotPasswordInput, CodeDeliveryDetails, } from './forgot-password.js';
 export { forgotPassword, confirmForgotPassword } from './forgot-password.js';
 export type { VerifyOptions } from './verify.js';
 export { verifyAndDecode } from './verify.js';
-export type { SessionTokens, CookieOptions, OAuthStateCookieOptions, } from './cookies.js';
-export { ID_TOKEN_COOKIE, ACCESS_TOKEN_COOKIE, REFRESH_TOKEN_COOKIE, buildSessionCookies, buildClearSessionCookies, readCookieFromHeader, buildOAuthStateCookie, clearOAuthStateCookie, oauthStateCookieName, } from './cookies.js';
+export { decodeJwtClaims } from './token-utils.js';
+export type { SessionTokens, CookieOptions, CookieDomainOptions, OAuthStateCookieOptions, } from './cookies.js';
+export { ID_TOKEN_COOKIE, ACCESS_TOKEN_COOKIE, REFRESH_TOKEN_COOKIE, buildSessionCookies, buildClearSessionCookies, readCookieFromHeader, buildOAuthStateCookie, clearOAuthStateCookie, oauthStateCookieName, resolveCookieDomain, } from './cookies.js';
 export type { CookieAuthMiddlewareOptions } from './middleware.js';
-export { cookieAuthMiddleware, extractToken } from './middleware.js';
+export { cookieAuthMiddleware, extractToken, defaultScopeMapper } from './middleware.js';
 export type { FederatedAuthRoutes, FederatedAuthRoutesOptions, FederatedCallbackBody, FederatedCallbackResult, FederatedOnSignInArgs, FederatedOnSignInResult, FederatedStartBody, } from './federated-routes.js';
 export { createFederatedAuthRoutes } from './federated-routes.js';
+export type { HandoffPayload, HandoffStore } from './handoff.js';
+export { DEFAULT_HANDOFF_TTL_SECONDS, generateHandoffCode, hashHandoffCode, issueHandoffCode, redeemHandoffCode, } from './handoff.js';
+export type { HandoffAuthorizeArgs, HandoffStartBody, SessionHandoffRoutes, SessionHandoffRoutesOptions, } from './handoff-routes.js';
+export { createSessionHandoffRoutes, DEFAULT_HANDOFF_COMPLETE_PATH, } from './handoff-routes.js';
 export type { FederatedProvider, FederatedProfile, FederatedProviderCredentials, SignInAsFederatedUserInput, BuildAuthorizeUrlInput, ExchangeAuthorizationCodeInput, } from './federated.js';
 export { loadFederatedProviderCredentials, generateOAuthState, verifyOAuthState, buildAuthorizeUrl, exchangeAuthorizationCode, signInAsFederatedUser, } from './federated.js';
 export type { VerificationChannel, VerificationCodeStore, VerificationCodeRecord, RequestVerificationCodeInput, RequestVerificationCodeResult, VerifyVerificationCodeInput, } from './verification.js';

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,YAAY,EACV,eAAe,EACf,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7E,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,YAAY,EACV,aAAa,EACb,aAAa,EACb,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAErE,YAAY,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAElE,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,4BAA4B,EAC5B,0BAA0B,EAC1B,sBAAsB,EACtB,8BAA8B,GAC/B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,gCAAgC,EAChC,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,EAC5B,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,mCAAmC,GACpC,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}

package/dist/server/index.js

@@ -28,13 +28,19 @@ export { signInWithPasswordOrChallenge, respondToNewPasswordChallenge, } from '.
 export { signUpUser } from './sign-up.js';
 export { adminInviteUser, adminUpdateUserAttributes, adminDisableUser, adminEnableUser, adminDeleteUser, } from './admin-users.js';
 export { refreshSession } from './refresh.js';
-export { revokeRefreshToken } from './revoke.js';
+export { revokeRefreshToken, globalSignOut } from './revoke.js';
+export { ensureUserForVerifiedEmail, mintSessionForVerifiedEmail, } from './passwordless.js';
 export { changePassword } from './change-password.js';
 export { forgotPassword, confirmForgotPassword } from './forgot-password.js';
 export { verifyAndDecode } from './verify.js';
-export { ID_TOKEN_COOKIE, ACCESS_TOKEN_COOKIE, REFRESH_TOKEN_COOKIE, buildSessionCookies, buildClearSessionCookies, readCookieFromHeader, buildOAuthStateCookie, clearOAuthStateCookie, oauthStateCookieName, } from './cookies.js';
-export { cookieAuthMiddleware, extractToken } from './middleware.js';
+// Unverified claim extraction — ONLY for tokens received directly
+// from the provider (e.g. reading profile claims right after sign-in).
+export { decodeJwtClaims } from './token-utils.js';
+export { ID_TOKEN_COOKIE, ACCESS_TOKEN_COOKIE, REFRESH_TOKEN_COOKIE, buildSessionCookies, buildClearSessionCookies, readCookieFromHeader, buildOAuthStateCookie, clearOAuthStateCookie, oauthStateCookieName, resolveCookieDomain, } from './cookies.js';
+export { cookieAuthMiddleware, extractToken, defaultScopeMapper } from './middleware.js';
 export { createFederatedAuthRoutes } from './federated-routes.js';
+export { DEFAULT_HANDOFF_TTL_SECONDS, generateHandoffCode, hashHandoffCode, issueHandoffCode, redeemHandoffCode, } from './handoff.js';
+export { createSessionHandoffRoutes, DEFAULT_HANDOFF_COMPLETE_PATH, } from './handoff-routes.js';
 export { loadFederatedProviderCredentials, generateOAuthState, verifyOAuthState, buildAuthorizeUrl, exchangeAuthorizationCode, signInAsFederatedUser, } from './federated.js';
 export { generateVerificationCode, hashVerificationCode, requestVerificationCode, verifyVerificationCode, createInMemoryVerificationCodeStore, } from './verification.js';
 //# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAOlD,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO1C,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAQtD,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAG7E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAO9C,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAWrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAUlE,OAAO,EACL,gCAAgC,EAChC,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAUxB,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,mCAAmC,GACpC,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAOlD,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO1C,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAQhE,OAAO,EACL,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAQtD,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAG7E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,kEAAkE;AAClE,uEAAuE;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAQnD,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAWzF,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAGlE,OAAO,EACL,2BAA2B,EAC3B,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAQtB,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAU7B,OAAO,EACL,gCAAgC,EAChC,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAUxB,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,mCAAmC,GACpC,MAAM,mBAAmB,CAAC"}