@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.3

package/dist/lib/server/handles/admin-scope.d.ts

@@ -0,0 +1,75 @@
+/**
+ * AdminScope — the typed gate result for admin surfaces.
+ *
+ * Admin surfaces (the system app today; potentially others in future) serve
+ * two audiences: Vibes staff (cross-tenant) and org admins (scoped to a
+ * single org). `requireAdminScope` resolves which tier the caller is in and
+ * returns a typed scope that every downstream query must filter by.
+ *
+ * Pair with `scopeFromLocals` / `actingScopeFromLocals`:
+ *  - admin-scope answers "what admin perimeter is this request inside"
+ *  - scope-from-locals answers "what data does this user see"
+ *
+ * Anonymous → 401. Authorization failure → 403. Staff bit always resolves
+ * to `{ tier: 'staff' }`, ignoring `opts.organizationIdFromUrl`.
+ */
+export type AdminScope = {
+    tier: 'staff';
+    user: AdminScopeUser;
+} | {
+    tier: 'org';
+    user: AdminScopeUser;
+    organizationId: string;
+};
+export interface AdminScopeUser {
+    id: string;
+    email: string;
+    staff: boolean;
+    isSuperuser: boolean;
+}
+export interface RequireAdminScopeOptions {
+    /**
+     * If true, only staff resolve. Org admins → 403 even if otherwise
+     * authorized. Use for cross-tenant admin pages (deployments, AI spend,
+     * cross-tenant feature flags, the infra provider catalog).
+     */
+    staffOnly?: boolean;
+    /**
+     * Org id from a URL path param. When provided and the user is an org
+     * admin of that organization, returns `{ tier: 'org', organizationId: organizationIdFromUrl }`.
+     * When the user is staff, this is ignored (staff resolves to `{ tier: 'staff' }`
+     * regardless of URL).
+     */
+    organizationIdFromUrl?: string | null;
+    /**
+     * Async predicate for "is this user an org admin of this org". Caller
+     * provides this so the handle stays adapter-free — the actual check
+     * goes through whatever permission adapter the consuming app has wired
+     * (e.g. `auth-system/require-admin`'s `isOrgAdmin`). Receives the resolved
+     * user object (already verified by the handle to be non-null with an id),
+     * not a userId, so callers can use closed-over context without a dummy
+     * unused parameter.
+     */
+    isOrgAdmin?: (user: AdminScopeUser, organizationId: string) => Promise<boolean>;
+}
+/**
+ * Resolve the admin scope for a request.
+ *
+ * Lookup order:
+ *  1. No user → 401.
+ *  2. `user.staff === true` → `{ tier: 'staff' }`, regardless of organizationIdFromUrl.
+ *  3. `opts.staffOnly === true` and user not staff → 403.
+ *  4. `opts.organizationIdFromUrl` provided and `opts.isOrgAdmin` resolves true → `{ tier: 'org' }`.
+ *  5. Otherwise → 403.
+ *
+ * The handle is intentionally adapter-free: consumers pass `isOrgAdmin` from
+ * whichever permission backend they use. This keeps vibeskit out of the
+ * auth-system dependency direction.
+ */
+export declare function requireAdminScope(locals: App.Locals, options?: RequireAdminScopeOptions): Promise<AdminScope>;
+/**
+ * Same as `requireAdminScope`, but returns null on 401/403 instead of
+ * throwing. Useful for page loaders that conditionally render an admin
+ * affordance without redirecting unauthenticated visitors.
+ */
+export declare function tryAdminScope(locals: App.Locals, options?: RequireAdminScopeOptions): Promise<AdminScope | null>;

package/dist/lib/server/handles/admin-scope.js

@@ -0,0 +1,96 @@
+/**
+ * AdminScope — the typed gate result for admin surfaces.
+ *
+ * Admin surfaces (the system app today; potentially others in future) serve
+ * two audiences: Vibes staff (cross-tenant) and org admins (scoped to a
+ * single org). `requireAdminScope` resolves which tier the caller is in and
+ * returns a typed scope that every downstream query must filter by.
+ *
+ * Pair with `scopeFromLocals` / `actingScopeFromLocals`:
+ *  - admin-scope answers "what admin perimeter is this request inside"
+ *  - scope-from-locals answers "what data does this user see"
+ *
+ * Anonymous → 401. Authorization failure → 403. Staff bit always resolves
+ * to `{ tier: 'staff' }`, ignoring `opts.organizationIdFromUrl`.
+ */
+import { error } from '@sveltejs/kit';
+import * as z from 'zod/v4';
+import { kitLogger } from '../../kit-logger';
+import { settle } from '../../attempt.js';
+import { failureClass } from '../../failure-class.js';
+const logger = kitLogger('admin-scope');
+/**
+ * The verified session user as this gate reads it. Only a string id is
+ * required (anonymous or id-less is 401); the other fields are read as the
+ * flags the session JWT carries. The parsed user keeps every other field the
+ * session published, so callers' `isOrgAdmin` still sees the whole user.
+ */
+const SessionUserSchema = z.looseObject({
+    id: z.string(),
+    email: z
+        .string()
+        .nullish()
+        .transform((email) => email ?? ''),
+    staff: z.boolean().catch(false),
+    isSuperuser: z.boolean().catch(false)
+});
+/**
+ * Resolve the admin scope for a request.
+ *
+ * Lookup order:
+ *  1. No user → 401.
+ *  2. `user.staff === true` → `{ tier: 'staff' }`, regardless of organizationIdFromUrl.
+ *  3. `opts.staffOnly === true` and user not staff → 403.
+ *  4. `opts.organizationIdFromUrl` provided and `opts.isOrgAdmin` resolves true → `{ tier: 'org' }`.
+ *  5. Otherwise → 403.
+ *
+ * The handle is intentionally adapter-free: consumers pass `isOrgAdmin` from
+ * whichever permission backend they use. This keeps vibeskit out of the
+ * auth-system dependency direction.
+ */
+export async function requireAdminScope(locals, options = {}) {
+    const verdict = await adminScopeVerdict(locals, options);
+    if (verdict.kind === 'refused') {
+        throw error(verdict.status, verdict.message);
+    }
+    return verdict.scope;
+}
+async function adminScopeVerdict(locals, options) {
+    const parsedUser = SessionUserSchema.safeParse(locals.user);
+    if (!parsedUser.success) {
+        return { kind: 'refused', status: 401, message: 'Authentication required' };
+    }
+    const user = parsedUser.data;
+    if (user.staff === true || user.isSuperuser === true) {
+        return { kind: 'granted', scope: { tier: 'staff', user } };
+    }
+    if (options.staffOnly === true) {
+        return { kind: 'refused', status: 403, message: 'Staff access required' };
+    }
+    const organizationId = options.organizationIdFromUrl ?? null;
+    const isOrgAdmin = options.isOrgAdmin;
+    if (organizationId && isOrgAdmin) {
+        const answer = await settle(() => isOrgAdmin(user, organizationId));
+        if (answer.ok) {
+            if (answer.value) {
+                return { kind: 'granted', scope: { tier: 'org', user, organizationId } };
+            }
+        }
+        else {
+            // Deny by default, reporting only the failure class.
+            logger.warn('Organization admin check failed; denying admin scope', {
+                reason: failureClass(answer.error)
+            });
+        }
+    }
+    return { kind: 'refused', status: 403, message: 'Admin access required' };
+}
+/**
+ * Same as `requireAdminScope`, but returns null on 401/403 instead of
+ * throwing. Useful for page loaders that conditionally render an admin
+ * affordance without redirecting unauthenticated visitors.
+ */
+export async function tryAdminScope(locals, options = {}) {
+    const verdict = await adminScopeVerdict(locals, options);
+    return verdict.kind === 'granted' ? verdict.scope : null;
+}

package/dist/lib/server/handles/auth-enforcement.d.ts

@@ -0,0 +1,50 @@
+/**
+ * createAuthEnforcementHandle — redirect/401 for unauthenticated requests
+ *
+ * A standalone auth enforcement handle for use AFTER sessionHandle.
+ * Checks event.locals.user and enforces authentication on protected routes.
+ *
+ * Does NOT fetch sessions — that is the job of sessionHandle.
+ * Does NOT load user context — that is the job of userContextHandle.
+ *
+ * Configurable public routes (glob patterns) and redirect URL builder.
+ */
+import { type Handle, type RequestEvent } from '@sveltejs/kit';
+export interface AuthEnforcementOptions {
+    /**
+     * Public route patterns that bypass auth enforcement (supports globs).
+     * Examples: ['/', '/auth/**', '/api/health/**']
+     */
+    publicRoutes?: string[];
+    /**
+     * Where to redirect unauthenticated page requests.
+     * Defaults to '/auth'. A function is resolved per request (for origins that
+     * depend on declared host values).
+     */
+    redirectTo?: string | ((event: RequestEvent) => string | Promise<string>);
+    /**
+     * Whether to enforce auth on /api/** routes (return 401 vs redirect).
+     * Defaults to true.
+     */
+    enforceOnApiRoutes?: boolean;
+}
+/**
+ * Create an auth enforcement handle.
+ *
+ * @example
+ * ```typescript
+ * import { sequence } from '@sveltejs/kit/hooks';
+ * import { createSessionFetchHandle } from '@vibesdotdev/auth/system/session-handle';
+ * import { createAuthEnforcementHandle } from '../../index.ts/server';
+ *
+ * export const handle = sequence(
+ *   createSessionFetchHandle({ sessionUrl: accountLinks.session }),
+ *   createAuthEnforcementHandle({
+ *     publicRoutes: ['/', '/auth/**', '/api/health/**'],
+ *     redirectTo: '/auth',
+ *     enforceOnApiRoutes: true
+ *   })
+ * );
+ * ```
+ */
+export declare function createAuthEnforcementHandle(options?: AuthEnforcementOptions): Handle;

package/dist/lib/server/handles/auth-enforcement.js

@@ -0,0 +1,82 @@
+/**
+ * createAuthEnforcementHandle — redirect/401 for unauthenticated requests
+ *
+ * A standalone auth enforcement handle for use AFTER sessionHandle.
+ * Checks event.locals.user and enforces authentication on protected routes.
+ *
+ * Does NOT fetch sessions — that is the job of sessionHandle.
+ * Does NOT load user context — that is the job of userContextHandle.
+ *
+ * Configurable public routes (glob patterns) and redirect URL builder.
+ */
+import { json } from '@sveltejs/kit';
+import { minimatch } from 'minimatch';
+import { resolveOption } from '../helpers/resolve-option.js';
+/**
+ * Check if a pathname matches any public route pattern.
+ */
+function isPublicRoute(pathname, publicRoutes) {
+    return publicRoutes.some((route) => {
+        if (pathname === route)
+            return true;
+        if (route.includes('*'))
+            return minimatch(pathname, route);
+        return pathname.startsWith(`${route}/`);
+    });
+}
+/**
+ * Check if a pathname looks like a static asset.
+ * Assets don't need auth enforcement (they're handled by the server differently).
+ */
+function isAssetRequest(pathname) {
+    // Never under `/api/`: an API route named `x.json` is an endpoint, not an asset.
+    return !pathname.startsWith('/api/') && /\.[a-zA-Z0-9]+$/.test(pathname);
+}
+/**
+ * Create an auth enforcement handle.
+ *
+ * @example
+ * ```typescript
+ * import { sequence } from '@sveltejs/kit/hooks';
+ * import { createSessionFetchHandle } from '@vibesdotdev/auth/system/session-handle';
+ * import { createAuthEnforcementHandle } from '../../index.ts/server';
+ *
+ * export const handle = sequence(
+ *   createSessionFetchHandle({ sessionUrl: accountLinks.session }),
+ *   createAuthEnforcementHandle({
+ *     publicRoutes: ['/', '/auth/**', '/api/health/**'],
+ *     redirectTo: '/auth',
+ *     enforceOnApiRoutes: true
+ *   })
+ * );
+ * ```
+ */
+export function createAuthEnforcementHandle(options = {}) {
+    const { publicRoutes = [], redirectTo: redirectOption = '/auth', enforceOnApiRoutes = true } = options;
+    return async ({ event, resolve }) => {
+        const pathname = event.url.pathname;
+        // Assets and public routes bypass enforcement entirely
+        if (isAssetRequest(pathname) || isPublicRoute(pathname, publicRoutes)) {
+            return resolve(event);
+        }
+        const redirectTo = await resolveOption(redirectOption, event);
+        // Auth redirect target is always allowed
+        if (pathname === redirectTo || pathname === `${redirectTo}/`) {
+            return resolve(event);
+        }
+        // Check authentication BEFORE running the endpoint
+        if (!event.locals.user) {
+            if (event.url.pathname.startsWith('/api/') && enforceOnApiRoutes) {
+                return json({ error: { message: 'Authentication required' } }, { status: 401 });
+            }
+            // Page routes → redirect to login
+            const redirectUrl = `${redirectTo}?redirect=${encodeURIComponent(event.url.pathname + event.url.search)}`;
+            return new Response(null, {
+                status: 302,
+                headers: { Location: redirectUrl }
+            });
+        }
+        // User is authenticated, proceed with the request
+        return resolve(event);
+    };
+}

package/dist/lib/server/handles/demo-banner.d.ts

@@ -0,0 +1,15 @@
+/**
+ * createDemoBannerHandle — exposes demo mode to templates + manages demo cookie lifecycle
+ *
+ * Sets `locals.demoMode = true` so layouts can render a DemoBanner.
+ *
+ * Cookie lifecycle:
+ * - SET: when demo mode active (from ?demo=1, header, or existing cookie) AND no real user.
+ *        Persists for 1 hour so cross-surface navigation works.
+ * - CLEAR: when a real authenticated user is detected. Signing in kills demo mode.
+ *
+ * MUST run after sessionHandle (so locals.user is populated) and after
+ * auth enforcement / user gate handles.
+ */
+import type { Handle } from '@sveltejs/kit';
+export declare function createDemoBannerHandle(): Handle;

package/dist/lib/server/handles/demo-banner.js

@@ -0,0 +1,33 @@
+/**
+ * createDemoBannerHandle — exposes demo mode to templates + manages demo cookie lifecycle
+ *
+ * Sets `locals.demoMode = true` so layouts can render a DemoBanner.
+ *
+ * Cookie lifecycle:
+ * - SET: when demo mode active (from ?demo=1, header, or existing cookie) AND no real user.
+ *        Persists for 1 hour so cross-surface navigation works.
+ * - CLEAR: when a real authenticated user is detected. Signing in kills demo mode.
+ *
+ * MUST run after sessionHandle (so locals.user is populated) and after
+ * auth enforcement / user gate handles.
+ */
+import { DEMO_COOKIE_NAME, checkDemoMode, createDemoSessionCookie, clearDemoSessionCookie } from '../helpers/is-demo-mode';
+export function createDemoBannerHandle() {
+    return async ({ event, resolve }) => {
+        const isDemo = checkDemoMode(event);
+        const hasRealUser = !!event.locals.user;
+        const hasDemoCookie = event.cookies.get(DEMO_COOKIE_NAME) === '1';
+        if (isDemo && !hasRealUser) {
+            Object.assign(event.locals, { demoMode: true });
+        }
+        const response = await resolve(event);
+        if (hasRealUser && hasDemoCookie) {
+            // Append: `set` would erase every other Set-Cookie the app wrote on this response.
+            response.headers.append('set-cookie', clearDemoSessionCookie());
+        }
+        else if (isDemo) {
+            response.headers.append('set-cookie', createDemoSessionCookie());
+        }
+        return response;
+    };
+}

package/dist/lib/server/handles/demo-mode.d.ts

@@ -0,0 +1,16 @@
+/**
+ * createDemoAwareAuthEnforcementHandle — wraps auth enforcement to allow demo sessions
+ *
+ * When demo mode is active AND no real user is signed in, this handle passes
+ * requests through that would normally be redirected/401'd, setting
+ * `locals.user = null` and `locals.session = null` so downstream
+ * code sees an unauthenticated (but not redirected) request.
+ *
+ * If a real user IS authenticated, this behaves exactly like the normal
+ * auth enforcement handle — signing in always kills demo mode.
+ */
+import type { Handle } from '@sveltejs/kit';
+import type { AuthEnforcementOptions } from './auth-enforcement';
+export declare function createDemoAwareAuthEnforcementHandle(options?: AuthEnforcementOptions): Handle;
+import type { ActiveUserGateOptions } from './active-user-gate';
+export declare function createDemoAwareActiveUserGateHandle(options?: ActiveUserGateOptions): Handle;

package/dist/lib/server/handles/demo-mode.js

@@ -0,0 +1,41 @@
+/**
+ * createDemoAwareAuthEnforcementHandle — wraps auth enforcement to allow demo sessions
+ *
+ * When demo mode is active AND no real user is signed in, this handle passes
+ * requests through that would normally be redirected/401'd, setting
+ * `locals.user = null` and `locals.session = null` so downstream
+ * code sees an unauthenticated (but not redirected) request.
+ *
+ * If a real user IS authenticated, this behaves exactly like the normal
+ * auth enforcement handle — signing in always kills demo mode.
+ */
+import { checkDemoMode } from '../helpers/is-demo-mode';
+import { asVibesKitLocals } from '../locals.js';
+import { createAuthEnforcementHandle } from './auth-enforcement';
+export function createDemoAwareAuthEnforcementHandle(options) {
+    const inner = createAuthEnforcementHandle(options ?? {});
+    return async ({ event, resolve }) => {
+        if (!checkDemoMode(event)) {
+            return inner({ event, resolve });
+        }
+        const locals = asVibesKitLocals(event.locals);
+        locals.user = null;
+        locals.session = null;
+        return resolve(event);
+    };
+}
+/**
+ * createDemoAwareActiveUserGateHandle — wraps active-user gate to allow demo sessions
+ *
+ * Skips status checks when in demo mode (no real user).
+ */
+import { createActiveUserGateHandle } from './active-user-gate';
+export function createDemoAwareActiveUserGateHandle(options) {
+    const inner = createActiveUserGateHandle(options ?? {});
+    return async ({ event, resolve }) => {
+        if (!checkDemoMode(event)) {
+            return inner({ event, resolve });
+        }
+        return resolve(event);
+    };
+}

package/dist/lib/server/handles/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * VibesKit Handle Primitives
+ *
+ * Individual, composable handles for the vibeskit handle chain.
+ *
+ * **Recommended approach**: Use `createVibesStandardAuth()` from `@vibesdotdev/kit/server`.
+ * It returns the correctly ordered handles below so you don't have to manually
+ * sequence 6-8 pieces in every app.
+ *
+ * The canonical chain for an authenticated, multi-tenant app is:
+ *   1. persistenceHandle       — app-specific (DB init, runtime bootstrap)
+ *   2. sessionHandle           — JWT (preferred) or fetch from auth (populates locals.user)
+ *   3. activeUserGateHandle    — demo-aware gate (usually before enforcement)
+ *   4. authEnforcementHandle   — redirect/401 (app-specific sign-in URL builder)
+ *   5. userContextHandle       — fetch aggregate from account (orgs, settings, perms)
+ *   6. activeProjectHandle     — read cookie → locals.activeProjectId
+ *   7. activeOrgHandle         — read/validate cookie → locals.activeOrgId
+ *   8. permissionFetchHandle   — optional, populates roles/permissions
+ *   9. demo banner / rate limit / cache / security / cors
+ *
+ * Route/page loaders then call `scopeFromLocals(locals)` (or
+ * `actingScopeFromLocals(locals)`) to get a query scope. `organizationId === null`
+ * is a first-class personal-workspace mode — never treat it as an error.
+ *
+ * `orgMembershipHandle` is opt-in and **single-tenant only**.
+ */
+export { createUserContextHandle, invalidateUserContext } from './user-context.js';
+export type { UserContextHandleOptions } from './user-context.js';
+export { checkProjectAccessViaProjectsApi, createActiveProjectHandle, invalidateActiveProjectAccess, readActiveProjectCookie, setActiveProjectCookie, ACTIVE_PROJECT_COOKIE_NAME } from './active-project.js';
+export type { ActiveProjectHandleOptions, ProjectAccessFetcher } from './active-project.js';
+export { createActiveOrgHandle, readActiveOrgCookie, setActiveOrgCookie, ACTIVE_ORG_COOKIE_NAME, ACTIVE_ORG_HEADER_NAME } from './active-org.js';
+export { createOrgMembershipHandle } from './org-membership.js';
+export { scopeFromLocals, tryScopeFromLocals } from './scope.js';
+export type { VibesScope } from './scope.js';
+export { actingScopeFromLocals, matchesActingOwner } from './acting-scope.js';
+export type { ActingScope } from './acting-scope.js';
+export { requireAdminScope, tryAdminScope } from './admin-scope.js';
+export type { AdminScope, AdminScopeUser, RequireAdminScopeOptions } from './admin-scope.js';
+export { createAuthEnforcementHandle } from './auth-enforcement.js';
+export type { AuthEnforcementOptions } from './auth-enforcement.js';
+export { createActiveUserGateHandle } from './active-user-gate.js';
+export type { ActiveUserGateOptions, ActiveUserStatus } from './active-user-gate.js';
+export { createDemoAwareAuthEnforcementHandle, createDemoAwareActiveUserGateHandle } from './demo-mode.js';
+export { createDemoBannerHandle } from './demo-banner.js';
+export { createPermissionFetchHandle, invalidatePermissionCache } from './permission-fetch.js';
+export type { PermissionFetchHandleOptions } from './permission-fetch.js';

package/dist/lib/server/handles/index.js

@@ -0,0 +1,38 @@
+/**
+ * VibesKit Handle Primitives
+ *
+ * Individual, composable handles for the vibeskit handle chain.
+ *
+ * **Recommended approach**: Use `createVibesStandardAuth()` from `@vibesdotdev/kit/server`.
+ * It returns the correctly ordered handles below so you don't have to manually
+ * sequence 6-8 pieces in every app.
+ *
+ * The canonical chain for an authenticated, multi-tenant app is:
+ *   1. persistenceHandle       — app-specific (DB init, runtime bootstrap)
+ *   2. sessionHandle           — JWT (preferred) or fetch from auth (populates locals.user)
+ *   3. activeUserGateHandle    — demo-aware gate (usually before enforcement)
+ *   4. authEnforcementHandle   — redirect/401 (app-specific sign-in URL builder)
+ *   5. userContextHandle       — fetch aggregate from account (orgs, settings, perms)
+ *   6. activeProjectHandle     — read cookie → locals.activeProjectId
+ *   7. activeOrgHandle         — read/validate cookie → locals.activeOrgId
+ *   8. permissionFetchHandle   — optional, populates roles/permissions
+ *   9. demo banner / rate limit / cache / security / cors
+ *
+ * Route/page loaders then call `scopeFromLocals(locals)` (or
+ * `actingScopeFromLocals(locals)`) to get a query scope. `organizationId === null`
+ * is a first-class personal-workspace mode — never treat it as an error.
+ *
+ * `orgMembershipHandle` is opt-in and **single-tenant only**.
+ */
+export { createUserContextHandle, invalidateUserContext } from './user-context.js';
+export { checkProjectAccessViaProjectsApi, createActiveProjectHandle, invalidateActiveProjectAccess, readActiveProjectCookie, setActiveProjectCookie, ACTIVE_PROJECT_COOKIE_NAME } from './active-project.js';
+export { createActiveOrgHandle, readActiveOrgCookie, setActiveOrgCookie, ACTIVE_ORG_COOKIE_NAME, ACTIVE_ORG_HEADER_NAME } from './active-org.js';
+export { createOrgMembershipHandle } from './org-membership.js';
+export { scopeFromLocals, tryScopeFromLocals } from './scope.js';
+export { actingScopeFromLocals, matchesActingOwner } from './acting-scope.js';
+export { requireAdminScope, tryAdminScope } from './admin-scope.js';
+export { createAuthEnforcementHandle } from './auth-enforcement.js';
+export { createActiveUserGateHandle } from './active-user-gate.js';
+export { createDemoAwareAuthEnforcementHandle, createDemoAwareActiveUserGateHandle } from './demo-mode.js';
+export { createDemoBannerHandle } from './demo-banner.js';
+export { createPermissionFetchHandle, invalidatePermissionCache } from './permission-fetch.js';

package/dist/lib/server/handles/org-membership.d.ts

@@ -0,0 +1,124 @@
+/**
+ * createOrgMembershipHandle — single-tenant org enforcement.
+ *
+ * Use this on top of `createActiveOrgHandle` when the entire app is locked
+ * to a specific organization (Casework → Northwind, etc.). The handle:
+ *
+ *   - Resolves the required org from the VERIFIED session JWT's `orgs` claim
+ *     (`locals.user.orgs`), falling back to `locals.userContext.organizations`.
+ *   - Force-sets `locals.activeOrgId` to that org's id for members.
+ *   - Optionally lets a superuser bypass with no active org.
+ *   - 403s anyone else (HTML for page requests, JSON for `/api/**`).
+ *   - 503s — never 403s — when membership could not be DETERMINED.
+ *
+ * ## Why the JWT claim comes first
+ *
+ * auth-web's `definePayload` mints `orgs` (`{id, role, slug}`) into every 15m
+ * session token and states plainly that consumer apps "MUST NOT fetch
+ * membership per-request". This gate used to read membership only off
+ * `locals.userContext`, which is a per-request subrequest to account-web — on
+ * a single-tenant app that is a blocking hop on EVERY page and API call, and
+ * it made authorization only as available as account-web.
+ *
+ * That cost was not theoretical. A forwarded agent credential authenticated
+ * fine here, then the context hop returned 401; `createUserContextHandle`
+ * swallowed it as "non-fatal" and left `userContext` null; this gate read zero
+ * organizations and answered `Forbidden: membership in "northwind" is
+ * required` — a membership denial for a user who is, and always was, a member.
+ * Reading the signed claim removes both the hop and the failure mode.
+ *
+ * ## What reading the claim costs
+ *
+ * Membership now reflects the token, so a REVOKED membership keeps working
+ * until the user's next token refresh — up to 15 minutes (JWT_MAX_AGE_SECONDS),
+ * against the ~5 minutes the account-context cache gave before. That widening
+ * is deliberate and platform-wide, not local to this gate: the 15m token IS the
+ * revocation window auth-web's `definePayload` designs for, and git-web's
+ * `getRepositoryPermission` already authorizes on the same terms. An app that
+ * genuinely needs sub-minute revocation must not use a claim-based gate at all.
+ *
+ * ## Empty is not the same as absent
+ *
+ * An empty `orgs` claim is ambiguous: a genuinely org-less user, a token
+ * minted before the claim existed, or `loadOrgMembershipClaim` degrading to
+ * `[]` on a DB hiccup. So the claim may only ever GRANT. Denial requires a
+ * source we trust to be COMPLETE — a non-empty claim, or a context fetch that
+ * actually succeeded. With neither, the honest answer is 503, not 403.
+ *
+ * Multi-tenant apps that scope per request via the activeOrg cookie do NOT
+ * need this handle — `createActiveOrgHandle` already reads + validates the
+ * cookie, and the `actingScopeFromLocals` helper handles personal-workspace
+ * (`orgId === null`) versus org-workspace (`orgId === ref`) on its own.
+ *
+ * Prerequisites in the handle chain (before this runs):
+ *   - sessionHandle → locals.user (incl. the verified `orgs` claim)
+ *   - authEnforcementHandle → unauthenticated requests already redirected
+ *   - userContextHandle → locals.userContext (fallback source) + userContextError
+ *   - activeOrgHandle → locals.activeOrgId set from cookie (will be overwritten)
+ *
+ * Locals read/written:
+ *   - reads  locals.user, locals.userContext, locals.userContextError
+ *   - writes locals.activeOrgId (force-set to required org's id)
+ */
+import { redirect, type Handle, type RequestEvent } from '@sveltejs/kit';
+export interface OrgMembershipOptions {
+    /**
+     * Require membership in the org with this slug. activeOrgId is
+     * force-set to that org's id.
+     */
+    requireSlug?: string;
+    /**
+     * Require membership in the org with this id. activeOrgId is
+     * force-set to this id.
+     */
+    requireOrgId?: string;
+    /**
+     * If true, allow `locals.userContext.user.isSuperuser` users to bypass
+     * membership checks. Default: true.
+     *
+     * When bypass fires, `activeOrgId` resolves in this order:
+     *   1. `requireOrgId` if set (use directly).
+     *   2. `resolveOrgIdForBypass(event)` if set (custom lookup — usually a
+     *      slug → id call against the account-web internal API).
+     *   3. `null` — superuser acts in personal scope.
+     *
+     * In a tenant-branded app the subdomain already declares the tenant, so
+     * leaving the superuser in personal scope (null) means they see *less*
+     * than the tenant's own members. Prefer (1) or (2) so superusers acting
+     * inside a branded app see the same data the tenant's members do.
+     */
+    allowAdminBypass?: boolean;
+    /**
+     * Resolver consulted on superuser admin-bypass when only `requireSlug`
+     * is configured. Should return the tenant's org id for the current
+     * request, or `null` if the slug can't be resolved. The handle awaits
+     * this on each bypassed request, so the implementation is expected to
+     * cache.
+     */
+    resolveOrgIdForBypass?: (event: RequestEvent) => Promise<string | null>;
+    /**
+     * Public route patterns that bypass this gate. Glob supported.
+     * Defaults to an empty list — set in tandem with authEnforcementHandle.
+     */
+    publicRoutes?: string[];
+    /**
+     * Redirect target for forbidden page requests. Default returns a 403 HTML.
+     * For API requests (/api/**), always returns 403 JSON.
+     */
+    forbiddenRedirect?: string;
+}
+/**
+ * Create a single-tenant org-membership enforcement handle.
+ *
+ * @example Single-tenant by slug:
+ * ```typescript
+ * createOrgMembershipHandle({ requireSlug: 'northwind' })
+ * ```
+ *
+ * @example Single-tenant by id:
+ * ```typescript
+ * createOrgMembershipHandle({ requireOrgId: 'org_01h...' })
+ * ```
+ */
+export declare function createOrgMembershipHandle(options: OrgMembershipOptions): Handle;
+export { redirect };