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

package/dist/lib/server/handles/org-membership.js

@@ -0,0 +1,194 @@
+/**
+ * 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 { json, redirect } from '@sveltejs/kit';
+import { minimatch } from 'minimatch';
+import { asVibesKitLocals } from '../locals.js';
+import { readUserContext } from './user-context-schema.js';
+function hasFileExtension(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);
+}
+function isPublicRoute(pathname, publicRoutes) {
+    return publicRoutes.some((route) => {
+        if (pathname === route)
+            return true;
+        if (route.includes('*'))
+            return minimatch(pathname, route);
+        return pathname.startsWith(`${route}/`);
+    });
+}
+/** First org in `members` matching the configured slug/id requirement, else null. */
+function matchRequiredOrg(members, requireSlug, requireOrgId) {
+    return (members.find((member) => (requireSlug !== undefined && member.slug === requireSlug) ||
+        (requireOrgId !== undefined && member.id === requireOrgId)) ?? null);
+}
+function forbid(pathname, message, redirectTo) {
+    if (pathname.startsWith('/api/')) {
+        return json({ error: { message } }, { status: 403 });
+    }
+    if (redirectTo) {
+        return new Response(null, { status: 302, headers: { Location: redirectTo } });
+    }
+    return new Response(message, {
+        status: 403,
+        headers: { 'Content-Type': 'text/plain' }
+    });
+}
+/**
+ * 503 for "we could not determine your membership".
+ *
+ * Deliberately NOT routed through `forbiddenRedirect`: sending a member to an
+ * access-denied page tells them they were denied, which is exactly the false
+ * statement this branch exists to stop making. Says retryable so a caller
+ * (agent tool, client fetch) treats it as the transient upstream failure it is.
+ */
+function membershipUndetermined(pathname) {
+    const message = 'Membership could not be verified right now. This is an upstream failure, not a denial — retry shortly.';
+    if (pathname.startsWith('/api/')) {
+        return json({ error: { message, retryable: true } }, { status: 503 });
+    }
+    return new Response(message, {
+        status: 503,
+        headers: { 'Content-Type': 'text/plain', 'Retry-After': '5' }
+    });
+}
+/**
+ * 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 function createOrgMembershipHandle(options) {
+    const { requireSlug, requireOrgId, allowAdminBypass = true, resolveOrgIdForBypass, publicRoutes = [], forbiddenRedirect } = options;
+    if (!requireSlug && !requireOrgId) {
+        throw new Error('createOrgMembershipHandle: must specify requireSlug or requireOrgId');
+    }
+    return async ({ event, resolve }) => {
+        const locals = asVibesKitLocals(event.locals);
+        const pathname = event.url.pathname;
+        if (hasFileExtension(pathname) || isPublicRoute(pathname, publicRoutes)) {
+            return resolve(event);
+        }
+        // Unauthenticated: authEnforcementHandle should have caught this.
+        // Don't double-gate; just pass through with null.
+        if (!locals.user) {
+            locals.activeOrgId = null;
+            return resolve(event);
+        }
+        // 1. The VERIFIED JWT claim — signed, already in hand, zero subrequests.
+        //    This is the seam auth-web's definePayload designates for membership.
+        const claimedOrgs = locals.user.orgs ?? [];
+        const fromClaim = matchRequiredOrg(claimedOrgs, requireSlug, requireOrgId);
+        if (fromClaim) {
+            locals.activeOrgId = fromClaim.id;
+            return resolve(event);
+        }
+        // 2. Fallback: the account context. Still needed for tokens minted before
+        //    the `orgs` claim existed — they carry `orgs: []` and would otherwise
+        //    lock out a real member until their next ≤15m refresh.
+        const context = readUserContext(locals);
+        const contextOrgs = context?.organizations ?? [];
+        const fromContext = matchRequiredOrg(contextOrgs, requireSlug, requireOrgId);
+        if (fromContext) {
+            locals.activeOrgId = fromContext.id;
+            return resolve(event);
+        }
+        // Superuser bypass reads the JWT flag FIRST for the same reason as
+        // membership: `context.user.isSuperuser` is only as available as
+        // account-web, so a degraded context hop used to lock out superusers too.
+        const isSuperuser = locals.user.isSuperuser === true || context?.user?.isSuperuser === true;
+        if (allowAdminBypass && isSuperuser) {
+            if (requireOrgId) {
+                locals.activeOrgId = requireOrgId;
+            }
+            else if (resolveOrgIdForBypass) {
+                locals.activeOrgId = await resolveOrgIdForBypass(event);
+            }
+            else {
+                locals.activeOrgId = null;
+            }
+            return resolve(event);
+        }
+        // Neither source granted access. Before calling that a DENIAL, confirm we
+        // actually hold a complete membership list. A non-empty claim is complete
+        // by construction (definePayload emits every membership). A context fetch
+        // that SUCCEEDED is complete. With neither, we simply never got to ask —
+        // say so, and say it with a status that means "try again", not "you are
+        // not a member".
+        const membershipsKnown = claimedOrgs.length > 0 || (context != null && !locals.userContextError);
+        if (!membershipsKnown) {
+            return membershipUndetermined(pathname);
+        }
+        const label = requireSlug ?? requireOrgId;
+        return forbid(pathname, `Forbidden: membership in "${label}" is required to access this app.`, forbiddenRedirect);
+    };
+}
+// Avoid "unused" warning if consumers only use the default redirect form.
+export { redirect };

package/dist/lib/server/handles/permission-fetch.d.ts

@@ -0,0 +1,71 @@
+/**
+ * createPermissionFetchHandle — fetches user permissions from the auth app
+ *
+ * Calls the auth app's /api/auth/permissions endpoint and populates
+ * event.locals.permissions and event.locals.roles.
+ *
+ * Runs AFTER sessionHandle (requires event.locals.user to be set).
+ * Provides per-userId caching with TTL.
+ *
+ * On failure, permissions default to an empty array (deny-by-default).
+ */
+import type { Handle, RequestEvent } from '@sveltejs/kit';
+import { type VibesKitRuntimePort } from '../locals.js';
+export interface PermissionFetchHandleOptions {
+    /**
+     * Base URL of the auth app (e.g., 'http://auth.vibes.local:8419').
+     * The /api/auth/permissions endpoint will be appended automatically.
+     */
+    authOrigin: string | ((event: RequestEvent) => string | Promise<string>);
+    /**
+     * Optional project ID to scope permissions.
+     * If not set, permissions are fetched without project scope.
+     */
+    projectId?: string;
+    /**
+     * Cache TTL in milliseconds. Defaults to 60 seconds.
+     */
+    cacheTtlMs?: number;
+    /**
+     * Optional fetch options passed to each permissions call.
+     */
+    fetchOptions?: RequestInit;
+}
+export interface PermissionEntry {
+    id: string;
+    name: string;
+    resource: string;
+    action: string;
+    description?: string;
+}
+export interface RoleEntry {
+    id: string;
+    name: string;
+    description?: string;
+    projectId?: string | null;
+    permissions: PermissionEntry[];
+}
+export interface PermissionsPayload {
+    permissions: PermissionEntry[];
+    roles: RoleEntry[];
+}
+/**
+ * Invalidate the cached permissions for a given userId.
+ */
+export declare function invalidatePermissionCache(runtime: VibesKitRuntimePort, userId: string): void;
+/**
+ * Create a handle that fetches and caches user permissions from the auth app.
+ *
+ * @example
+ * ```typescript
+ * import { sequence } from '@sveltejs/kit/hooks';
+ * import { createSessionFetchHandle } from '@vibesdotdev/auth/system/session-handle';
+ * import { createPermissionFetchHandle } from '../../index.ts/server/handles';
+ *
+ * export const handle = sequence(
+ *   createSessionFetchHandle({ sessionUrl: authLinks.session }),
+ *   createPermissionFetchHandle({ authOrigin: 'http://auth.vibes.local:8419' })
+ * );
+ * ```
+ */
+export declare function createPermissionFetchHandle(options: PermissionFetchHandleOptions): Handle;

package/dist/lib/server/handles/permission-fetch.js

@@ -0,0 +1,160 @@
+/**
+ * createPermissionFetchHandle — fetches user permissions from the auth app
+ *
+ * Calls the auth app's /api/auth/permissions endpoint and populates
+ * event.locals.permissions and event.locals.roles.
+ *
+ * Runs AFTER sessionHandle (requires event.locals.user to be set).
+ * Provides per-userId caching with TTL.
+ *
+ * On failure, permissions default to an empty array (deny-by-default).
+ */
+import * as z from 'zod/v4';
+import { resolveOption } from '../helpers/resolve-option.js';
+import { settle } from '../../attempt.js';
+import { failureClass } from '../../failure-class.js';
+import { kitLogger } from '../../kit-logger';
+import { asVibesKitLocals, requireKitRuntime } from '../locals.js';
+import { CapabilityError } from '@vibesdotdev/kernel';
+const logger = kitLogger('permission-fetch-handle');
+class PermissionFetchUnavailableError extends CapabilityError {
+    constructor(reason, status) {
+        super('Permissions could not be loaded', 'UNAVAILABLE', {
+            reason,
+            details: status === undefined ? undefined : { status }
+        });
+        this.name = 'PermissionFetchUnavailableError';
+    }
+}
+const PermissionEntrySchema = z.looseObject({
+    id: z.string(),
+    name: z.string(),
+    resource: z.string(),
+    action: z.string(),
+    description: z.string().optional()
+});
+const RoleEntrySchema = z.looseObject({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().optional(),
+    projectId: z.string().nullish(),
+    permissions: z.array(PermissionEntrySchema)
+});
+const PermissionsPayloadSchema = z.looseObject({
+    permissions: z.array(PermissionEntrySchema),
+    roles: z.array(RoleEntrySchema)
+});
+const permissionCaches = new WeakMap();
+function permissionCache(runtime) {
+    let cache = permissionCaches.get(runtime);
+    if (!cache) {
+        cache = new Map();
+        permissionCaches.set(runtime, cache);
+    }
+    return cache;
+}
+function getCached(cache, key) {
+    const entry = cache.get(key);
+    if (!entry)
+        return null;
+    if (Date.now() > entry.expiresAt) {
+        cache.delete(key);
+        return null;
+    }
+    return entry.value;
+}
+function setCache(cache, key, value, ttlMs) {
+    cache.set(key, { value, expiresAt: Date.now() + ttlMs });
+}
+/**
+ * Invalidate the cached permissions for a given userId.
+ */
+export function invalidatePermissionCache(runtime, userId) {
+    const cache = permissionCaches.get(runtime);
+    if (!cache)
+        return;
+    for (const key of cache.keys())
+        if (JSON.parse(key)[0] === userId)
+            cache.delete(key);
+}
+// Handle
+/**
+ * Create a handle that fetches and caches user permissions from the auth app.
+ *
+ * @example
+ * ```typescript
+ * import { sequence } from '@sveltejs/kit/hooks';
+ * import { createSessionFetchHandle } from '@vibesdotdev/auth/system/session-handle';
+ * import { createPermissionFetchHandle } from '../../index.ts/server/handles';
+ *
+ * export const handle = sequence(
+ *   createSessionFetchHandle({ sessionUrl: authLinks.session }),
+ *   createPermissionFetchHandle({ authOrigin: 'http://auth.vibes.local:8419' })
+ * );
+ * ```
+ */
+export function createPermissionFetchHandle(options) {
+    const { authOrigin, projectId, cacheTtlMs = 60_000, fetchOptions = {} } = options;
+    return async ({ event, resolve }) => {
+        const locals = asVibesKitLocals(event.locals);
+        // Only fetch permissions for authenticated users
+        if (!locals.user) {
+            locals.permissions = [];
+            locals.roles = [];
+            return resolve(event);
+        }
+        const userId = locals.user.id;
+        const lookup = await settle(async () => {
+            const runtime = requireKitRuntime(locals);
+            const resolvedAuthOrigin = await resolveOption(authOrigin, event);
+            const cache = permissionCache(runtime);
+            const cacheKey = JSON.stringify([userId, projectId ?? null, resolvedAuthOrigin]);
+            const cached = getCached(cache, cacheKey);
+            if (cached !== null)
+                return cached;
+            const permUrl = `${resolvedAuthOrigin.replace(/\/$/, '')}/api/auth/permissions`;
+            const url = projectId ? `${permUrl}?projectId=${encodeURIComponent(projectId)}` : permUrl;
+            const payload = await fetchPermissions(event, url, fetchOptions);
+            setCache(cache, cacheKey, payload, cacheTtlMs);
+            return payload;
+        });
+        if (lookup.ok) {
+            locals.permissions = lookup.value.permissions;
+            locals.roles = lookup.value.roles;
+        }
+        else {
+            logger.warn('Failed to fetch user permissions — defaulting to empty', {
+                reason: failureClass(lookup.error)
+            });
+            // Deny-by-default: empty permissions means nothing is allowed
+            locals.permissions = [];
+            locals.roles = [];
+        }
+        return resolve(event);
+    };
+}
+async function fetchPermissions(event, url, fetchOptions) {
+    // auth-web `/api/auth/permissions` fills locals.user from Better Auth
+    // getSession on the `vibes.session` cookie. A JWT Authorization bearer
+    // fails HMAC, is treated as an API key, and clears locals.user. Keep the
+    // inbound cookie until that receiver accepts the session bearer.
+    const inboundCookie = event.request.headers.get('cookie') || '';
+    const response = await fetch(url, {
+        ...fetchOptions,
+        headers: {
+            cookie: inboundCookie,
+            'Content-Type': 'application/json',
+            ...fetchOptions.headers
+        }
+    });
+    if (!response.ok) {
+        throw new PermissionFetchUnavailableError('permission-fetch-upstream-failed', response.status);
+    }
+    // Parsed at the boundary: a body that is not a permissions payload is a failed
+    // lookup (the handle then denies by default), never published into locals.
+    const payload = PermissionsPayloadSchema.safeParse(await response.json());
+    if (!payload.success) {
+        throw new PermissionFetchUnavailableError('permission-fetch-invalid-payload');
+    }
+    return payload.data;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * createScopeHandle — populates `event.locals.scope` with the canonical actor
+ * `Scope` for the request.
+ *
+ * Composition is owned by the host's scope resolver (the `scope` package's
+ * `resolveCloudScope`), handed in as `resolveScope` — kit imports no scope
+ * package. The resolver reads the outputs of earlier handles in the chain
+ * (no new fetches): `locals.user`, `locals.userContext` (organizations +
+ * teamMemberships), the active org/team/project ids, `locals.billing` for the
+ * tier and `locals.roles` for the free-form project role.
+ *
+ * Insertion point in the canonical chain (per `handles/index.ts` ordering):
+ *   1. persistenceHandle
+ *   2. sessionHandle
+ *   3. activeUserGateHandle
+ *   4. authEnforcementHandle
+ *   5. userContextHandle
+ *   6. activeProjectHandle
+ *   7. activeOrgHandle
+ *   8. permissionFetchHandle
+ *   9. **scopeHandle**       ← runs LAST so it can read every prior local
+ *  10. demo banner / rate limit / cache / security / cors
+ *
+ * Deny by default: when the request state cannot form a valid `Scope` (for
+ * example, a user without an email) the handle logs a warning and leaves
+ * `locals.scope` undefined, so scope-gated routes refuse rather than run on
+ * an invented identity. Unknown org/team roles omit that level.
+ */
+import type { Handle } from '@sveltejs/kit';
+import type { KitScope } from '../locals.js';
+export interface ScopeHandleOptions {
+    /**
+     * Resolve the actor scope from earlier-handle locals. Return `null` /
+     * `undefined` when the request state cannot form a valid scope (deny by
+     * default). A throw propagates — kit does not swallow resolver failures.
+     */
+    resolveScope(locals: App.Locals): {
+        scope: KitScope;
+    } | null | undefined;
+}
+/**
+ * Create a handle that resolves the actor `Scope` from earlier-handle outputs
+ * and populates `event.locals.scope`.
+ *
+ * Skips unauthenticated requests (`locals.user` falsy) — no scope is set,
+ * downstream loaders should not rely on `locals.scope` on public routes.
+ */
+export declare function createScopeHandle(options: ScopeHandleOptions): Handle;

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

@@ -0,0 +1,54 @@
+/**
+ * createScopeHandle — populates `event.locals.scope` with the canonical actor
+ * `Scope` for the request.
+ *
+ * Composition is owned by the host's scope resolver (the `scope` package's
+ * `resolveCloudScope`), handed in as `resolveScope` — kit imports no scope
+ * package. The resolver reads the outputs of earlier handles in the chain
+ * (no new fetches): `locals.user`, `locals.userContext` (organizations +
+ * teamMemberships), the active org/team/project ids, `locals.billing` for the
+ * tier and `locals.roles` for the free-form project role.
+ *
+ * Insertion point in the canonical chain (per `handles/index.ts` ordering):
+ *   1. persistenceHandle
+ *   2. sessionHandle
+ *   3. activeUserGateHandle
+ *   4. authEnforcementHandle
+ *   5. userContextHandle
+ *   6. activeProjectHandle
+ *   7. activeOrgHandle
+ *   8. permissionFetchHandle
+ *   9. **scopeHandle**       ← runs LAST so it can read every prior local
+ *  10. demo banner / rate limit / cache / security / cors
+ *
+ * Deny by default: when the request state cannot form a valid `Scope` (for
+ * example, a user without an email) the handle logs a warning and leaves
+ * `locals.scope` undefined, so scope-gated routes refuse rather than run on
+ * an invented identity. Unknown org/team roles omit that level.
+ */
+import { kitLogger } from '../../kit-logger';
+const logger = kitLogger('scope-handle');
+/**
+ * Create a handle that resolves the actor `Scope` from earlier-handle outputs
+ * and populates `event.locals.scope`.
+ *
+ * Skips unauthenticated requests (`locals.user` falsy) — no scope is set,
+ * downstream loaders should not rely on `locals.scope` on public routes.
+ */
+export function createScopeHandle(options) {
+    return async ({ event, resolve }) => {
+        const user = event.locals.user;
+        if (!user) {
+            event.locals.scope = undefined;
+            return resolve(event);
+        }
+        const resolved = options.resolveScope(event.locals);
+        event.locals.scope = resolved?.scope;
+        if (!resolved) {
+            logger.warn('Scope could not be resolved from request locals — leaving locals.scope unset', {
+                userId: user.id
+            });
+        }
+        return resolve(event);
+    };
+}

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

@@ -0,0 +1,32 @@
+/**
+ * VibesScope — the shared query-scope shape for every app.
+ *
+ * Apps that own data (casework/app/chat/ai/tools/knowledge) hit their DB
+ * with a scope extracted from the request. When `organizationId` is non-null, queries
+ * filter by organization (data is shared across org members). When null,
+ * they fall back to per-user isolation (admin bypass, personal workspace,
+ * pre-org-lockdown).
+ *
+ * The scope is extracted via `scopeFromLocals(locals)` — it throws 401 if
+ * the caller is not authenticated.
+ */
+export interface VibesScope {
+    userId: string;
+    organizationId: string | null;
+}
+/**
+ * Extract the query scope from a request's locals.
+ *
+ * Throws 401 if the caller is not authenticated. Reads:
+ *  - locals.user.id → scope.userId
+ *  - locals.activeOrgId → scope.organizationId
+ *
+ * Requires `createActiveOrgHandle` (or a membership-gate handle that forces
+ * activeOrgId) to have run earlier in the handle chain.
+ */
+export declare function scopeFromLocals(locals: App.Locals): VibesScope;
+/**
+ * Same as scopeFromLocals, but returns null if unauthenticated instead of
+ * throwing. Useful for page loaders that render an unauthenticated view.
+ */
+export declare function tryScopeFromLocals(locals: App.Locals): VibesScope | null;

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

@@ -0,0 +1,49 @@
+/**
+ * VibesScope — the shared query-scope shape for every app.
+ *
+ * Apps that own data (casework/app/chat/ai/tools/knowledge) hit their DB
+ * with a scope extracted from the request. When `organizationId` is non-null, queries
+ * filter by organization (data is shared across org members). When null,
+ * they fall back to per-user isolation (admin bypass, personal workspace,
+ * pre-org-lockdown).
+ *
+ * The scope is extracted via `scopeFromLocals(locals)` — it throws 401 if
+ * the caller is not authenticated.
+ */
+import { error } from '@sveltejs/kit';
+import * as z from 'zod/v4';
+import { asVibesKitLocals } from "../locals.js";
+const UserIdSchema = z.string();
+/**
+ * Extract the query scope from a request's locals.
+ *
+ * Throws 401 if the caller is not authenticated. Reads:
+ *  - locals.user.id → scope.userId
+ *  - locals.activeOrgId → scope.organizationId
+ *
+ * Requires `createActiveOrgHandle` (or a membership-gate handle that forces
+ * activeOrgId) to have run earlier in the handle chain.
+ */
+export function scopeFromLocals(locals) {
+    const scope = tryScopeFromLocals(locals);
+    if (!scope) {
+        throw error(401, 'Authentication required');
+    }
+    return scope;
+}
+/**
+ * Same as scopeFromLocals, but returns null if unauthenticated instead of
+ * throwing. Useful for page loaders that render an unauthenticated view.
+ */
+export function tryScopeFromLocals(locals) {
+    const kitLocals = asVibesKitLocals(locals);
+    // A user without a string id is not an authenticated principal.
+    const userId = UserIdSchema.safeParse(kitLocals.user?.id);
+    if (!userId.success) {
+        return null;
+    }
+    return {
+        userId: userId.data,
+        organizationId: kitLocals.activeOrgId ?? null
+    };
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Tenant-admin context derivation for AppShell sidebars.
+ *
+ * Mirrors the role hierarchy in
+ * apps/account-web/src/server/server/organizations/membership.ts. When the
+ * signed-in user is owner/admin of the active org, the AppShell prepends a
+ * "Tenant Admin" group that deep-links to account.vibes.dev so org admins
+ * don't have to manually navigate to a different app.
+ *
+ * Pure helper, not a handle: call it from a layout load after the standard
+ * vibeskit chain has populated `locals.userContext` and `locals.activeOrgId`.
+ */
+interface OrgRoleRecord {
+    id: string;
+    slug?: string | null;
+    role?: string | null;
+    membership?: {
+        role?: string | null;
+    } | null;
+}
+interface TenantAdminUserContext {
+    organizations?: OrgRoleRecord[] | null;
+}
+interface TenantAdminLocals {
+    userContext?: TenantAdminUserContext | null;
+    activeOrgId?: string | null;
+}
+export interface TenantAdminContext {
+    activeOrgRole: string | null;
+    activeOrgIsAdmin: boolean;
+    activeOrgSlug: string | null;
+}
+export declare function deriveTenantAdminContext(locals: TenantAdminLocals): TenantAdminContext;
+export {};

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

@@ -0,0 +1,22 @@
+/**
+ * Tenant-admin context derivation for AppShell sidebars.
+ *
+ * Mirrors the role hierarchy in
+ * apps/account-web/src/server/server/organizations/membership.ts. When the
+ * signed-in user is owner/admin of the active org, the AppShell prepends a
+ * "Tenant Admin" group that deep-links to account.vibes.dev so org admins
+ * don't have to manually navigate to a different app.
+ *
+ * Pure helper, not a handle: call it from a layout load after the standard
+ * vibeskit chain has populated `locals.userContext` and `locals.activeOrgId`.
+ */
+const ORG_ADMIN_ROLES = new Set(['owner', 'admin']);
+export function deriveTenantAdminContext(locals) {
+    const activeOrgId = locals.activeOrgId ?? null;
+    const organizations = locals.userContext?.organizations ?? [];
+    const activeOrg = activeOrgId ? organizations.find((o) => o.id === activeOrgId) : null;
+    const activeOrgRole = activeOrg?.membership?.role ?? activeOrg?.role ?? null;
+    const activeOrgIsAdmin = activeOrgRole !== null && ORG_ADMIN_ROLES.has(activeOrgRole);
+    const activeOrgSlug = activeOrg?.slug ?? null;
+    return { activeOrgRole, activeOrgIsAdmin, activeOrgSlug };
+}