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

package/dist/lib/server/handles/user-context-schema.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The part of the account context that kit's handles read.
+ *
+ * `locals.userContext` is app-defined (`unknown` in the locals contract); the
+ * account service fills it. Kit reads only organizations, team memberships and
+ * the superuser flag, and parses exactly those at the boundary. Unknown extra
+ * fields pass through untouched. A context that does not fit is treated as
+ * not loaded, which every reader already handles (fail closed).
+ */
+import * as z from 'zod/v4';
+declare const OrgContextMemberSchema: z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    membership: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export declare const UserContextSchema: z.ZodObject<{
+    user: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        isSuperuser: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>>;
+    organizations: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        slug: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        membership: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>>>;
+    teamMemberships: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        teamId: z.ZodString;
+    }, z.core.$loose>>>>;
+}, z.core.$loose>;
+export type UserContext = z.infer<typeof UserContextSchema>;
+export type OrgContextMember = z.infer<typeof OrgContextMemberSchema>;
+/** The loaded context, or `null` when none is loaded or it does not fit the schema. */
+export declare function readUserContext(locals: {
+    userContext?: unknown;
+}): UserContext | null;
+/**
+ * Org ids named by the verified session JWT's `orgs` claim, or `null` when the
+ * token carries no `orgs` array (a legacy token). Entries without a string id
+ * are ignored, as they can never match an org.
+ */
+export declare function readJwtOrgIds(user: {
+    orgs?: unknown;
+} | null | undefined): string[] | null;
+export {};

package/dist/lib/server/handles/user-context-schema.js

@@ -0,0 +1,39 @@
+/**
+ * The part of the account context that kit's handles read.
+ *
+ * `locals.userContext` is app-defined (`unknown` in the locals contract); the
+ * account service fills it. Kit reads only organizations, team memberships and
+ * the superuser flag, and parses exactly those at the boundary. Unknown extra
+ * fields pass through untouched. A context that does not fit is treated as
+ * not loaded, which every reader already handles (fail closed).
+ */
+import * as z from 'zod/v4';
+const OrgContextMemberSchema = z.looseObject({
+    id: z.string(),
+    slug: z.string().nullish(),
+    role: z.string().nullish(),
+    membership: z.looseObject({ role: z.string().nullish() }).nullish()
+});
+const TeamContextMemberSchema = z.looseObject({ teamId: z.string() });
+export const UserContextSchema = z.looseObject({
+    user: z.looseObject({ isSuperuser: z.boolean().optional() }).nullish(),
+    organizations: z.array(OrgContextMemberSchema).nullish(),
+    teamMemberships: z.array(TeamContextMemberSchema).nullish()
+});
+/** The loaded context, or `null` when none is loaded or it does not fit the schema. */
+export function readUserContext(locals) {
+    const parsed = UserContextSchema.safeParse(locals.userContext);
+    return parsed.success ? parsed.data : null;
+}
+const JwtOrgsSchema = z.array(z.looseObject({ id: z.string().optional() }).nullable());
+/**
+ * Org ids named by the verified session JWT's `orgs` claim, or `null` when the
+ * token carries no `orgs` array (a legacy token). Entries without a string id
+ * are ignored, as they can never match an org.
+ */
+export function readJwtOrgIds(user) {
+    const parsed = JwtOrgsSchema.safeParse(user?.orgs);
+    if (!parsed.success)
+        return null;
+    return parsed.data.flatMap((org) => (org?.id ? [org.id] : []));
+}

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

@@ -0,0 +1,69 @@
+/**
+ * createUserContextHandle — fetches user context from the account app
+ *
+ * Calls the account app's /api/account/context endpoint (or equivalent)
+ * and populates event.locals.userContext with the result.
+ *
+ * Runs AFTER sessionHandle (requires event.locals.user to be set).
+ * Provides aggressive per-userId caching with TTL.
+ */
+import type { Handle, RequestEvent } from '@sveltejs/kit';
+import { type VibesKitRuntimePort } from '../locals.js';
+import { type UserContext } from './user-context-schema.js';
+/** Minimal fetcher shape; matches both `globalThis.fetch` and CF service-binding fetchers. */
+export type UserContextFetcher = (input: URL | string | Request, init?: RequestInit) => Promise<Response>;
+export interface UserContextHandleOptions {
+    /**
+     * Base URL of the account app (e.g., 'http://127.0.0.1:8419').
+     * The /api/account/context endpoint will be appended automatically.
+     */
+    accountOrigin: string | ((event: RequestEvent) => string | Promise<string>);
+    /**
+     * Cache TTL in milliseconds. Defaults to 60 seconds.
+     * Set lower for more responsive context updates; higher for better performance.
+     */
+    cacheTtlMs?: number;
+    /**
+     * Optional fetch options passed to each context call.
+     * Use this to add custom headers, credentials, etc.
+     */
+    fetchOptions?: RequestInit;
+    /**
+     * Optional fetcher used to call the account context endpoint. When
+     * omitted, the handle looks for a Cloudflare service-binding registered
+     * under `serviceBindingName` (default `'ACCOUNT_SERVICE'`) and uses its
+     * `.fetch` if found; otherwise it falls back to global `fetch`. Pass an
+     * explicit fetcher (or a getter that returns one) to override; pass
+     * `null` to force the global-fetch path even when a binding is
+     * available.
+     */
+    fetcher?: UserContextFetcher | (() => UserContextFetcher | undefined) | null;
+    /**
+     * Name of the runtime binding the handle should prefer for context
+     * calls. Defaults to `'ACCOUNT_SERVICE'`, matching the convention used
+     * by each consumer app's `wrangler.jsonc`. Set to `null` to disable the
+     * binding lookup entirely.
+     */
+    serviceBindingName?: string | null;
+}
+/**
+ * Invalidate the cached user context for a given userId.
+ * Call this when user context mutations occur (profile update, org change, etc.).
+ */
+export declare function invalidateUserContext(runtime: VibesKitRuntimePort, userId: string): void;
+/**
+ * Create a handle that fetches and caches user context from the account app.
+ *
+ * @example
+ * ```typescript
+ * import { sequence } from '@sveltejs/kit/hooks';
+ * import { createSessionFetchHandle } from '@vibesdotdev/auth/system/session-handle';
+ *
+ * export const handle = sequence(
+ *   createSessionFetchHandle({ sessionUrl: accountLinks.session }),
+ *   createUserContextHandle({ accountOrigin: 'http://127.0.0.1:8419' })
+ * );
+ * ```
+ */
+export declare function createUserContextHandle(options: UserContextHandleOptions): Handle;
+export declare function fetchUserContext(event: Pick<RequestEvent, 'request' | 'locals'>, url: string, fetchOptions: RequestInit, fetcher: UserContextFetcher): Promise<UserContext>;

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

@@ -0,0 +1,180 @@
+/**
+ * createUserContextHandle — fetches user context from the account app
+ *
+ * Calls the account app's /api/account/context endpoint (or equivalent)
+ * and populates event.locals.userContext with the result.
+ *
+ * Runs AFTER sessionHandle (requires event.locals.user to be set).
+ * Provides aggressive per-userId caching with TTL.
+ */
+import { kitLogger } from '../../kit-logger';
+import { asVibesKitLocals, requireKitRuntime } from '../locals.js';
+import { vibesServerRequestHeaders } from "../outbound.js";
+import { serviceBindingFetch } from '../services/service-binding-runtime.js';
+import { resolveOption } from '../helpers/resolve-option.js';
+import { settle } from '../../attempt.js';
+import { failureClass } from '../../failure-class.js';
+import { UserContextSchema } from './user-context-schema.js';
+import { CapabilityError } from '@vibesdotdev/kernel';
+const logger = kitLogger('user-context-handle');
+class UserContextUnavailableError extends CapabilityError {
+    constructor(reason, status) {
+        super('User context could not be loaded', 'UNAVAILABLE', {
+            reason,
+            details: status === undefined ? undefined : { status }
+        });
+        this.name = 'UserContextUnavailableError';
+    }
+}
+function createUserContextCache() {
+    const cache = new Map();
+    function get(key) {
+        const entry = cache.get(key);
+        if (!entry)
+            return null;
+        if (Date.now() > entry.expiresAt) {
+            cache.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    function set(key, value, ttlMs) {
+        cache.set(key, { value, expiresAt: Date.now() + ttlMs });
+    }
+    function invalidate(key) {
+        for (const entry of cache.keys()) {
+            if (JSON.parse(entry)[0] === key)
+                cache.delete(entry);
+        }
+    }
+    function clear() {
+        cache.clear();
+    }
+    return { get, set, invalidate, clear };
+}
+const contextCaches = new WeakMap();
+function contextCache(runtime) {
+    let cache = contextCaches.get(runtime);
+    if (!cache) {
+        cache = createUserContextCache();
+        contextCaches.set(runtime, cache);
+    }
+    return cache;
+}
+/**
+ * Invalidate the cached user context for a given userId.
+ * Call this when user context mutations occur (profile update, org change, etc.).
+ */
+export function invalidateUserContext(runtime, userId) {
+    contextCaches.get(runtime)?.invalidate(userId);
+}
+/** The option's calling convention: a zero-argument function is a getter, anything else a fetcher. */
+function isFetcherGetter(option) {
+    return option.length === 0;
+}
+function resolveFetcher(runtime, option, serviceBindingName) {
+    if (option === null) {
+        return globalFetch;
+    }
+    if (option !== undefined) {
+        if (isFetcherGetter(option)) {
+            const got = option();
+            if (got)
+                return got;
+        }
+        else {
+            return option;
+        }
+    }
+    const fromBinding = serviceBindingFetch(runtime, serviceBindingName);
+    return fromBinding ?? globalFetch;
+}
+/** The runtime's global `fetch`, looked up at call time. */
+const globalFetch = (input, init) => globalThis.fetch(input, init);
+/**
+ * Create a handle that fetches and caches user context from the account app.
+ *
+ * @example
+ * ```typescript
+ * import { sequence } from '@sveltejs/kit/hooks';
+ * import { createSessionFetchHandle } from '@vibesdotdev/auth/system/session-handle';
+ *
+ * export const handle = sequence(
+ *   createSessionFetchHandle({ sessionUrl: accountLinks.session }),
+ *   createUserContextHandle({ accountOrigin: 'http://127.0.0.1:8419' })
+ * );
+ * ```
+ */
+export function createUserContextHandle(options) {
+    const { accountOrigin, cacheTtlMs = 60_000, // 60 seconds default
+    fetchOptions = {} } = options;
+    return async ({ event, resolve }) => {
+        const locals = asVibesKitLocals(event.locals);
+        // Only fetch context for authenticated users
+        if (!locals.user) {
+            locals.userContext = null;
+            locals.userContextError = null;
+            return resolve(event);
+        }
+        const userId = locals.user.id;
+        const lookup = await settle(async () => {
+            const runtime = requireKitRuntime(locals);
+            const resolvedAccountOrigin = await resolveOption(accountOrigin, event);
+            const cacheKey = JSON.stringify([userId, resolvedAccountOrigin]);
+            const cache = contextCache(runtime);
+            const cached = cache.get(cacheKey);
+            if (cached !== null)
+                return cached;
+            const contextUrl = `${resolvedAccountOrigin.replace(/\/$/, '')}/api/account/context`;
+            const serviceBindingName = options.serviceBindingName === undefined ? 'ACCOUNT_SERVICE' : options.serviceBindingName;
+            const fetcher = resolveFetcher(runtime, options.fetcher, serviceBindingName);
+            const context = await fetchUserContext(event, contextUrl, fetchOptions, fetcher);
+            cache.set(cacheKey, context, cacheTtlMs);
+            return context;
+        });
+        if (lookup.ok) {
+            locals.userContext = lookup.value;
+            locals.userContextError = null;
+        }
+        else {
+            const reason = failureClass(lookup.error);
+            logger.warn('Failed to fetch user context', { reason });
+            // Don't throw — context is non-fatal, continue without it. But RECORD
+            // why it is missing: a downstream gate that reads `organizations` off a
+            // null context cannot otherwise distinguish "this user has no orgs" from
+            // "we never got to ask", and denying on the second is a false negative
+            // dressed as an authorization decision.
+            locals.userContext = null;
+            locals.userContextError = reason;
+        }
+        return resolve(event);
+    };
+}
+export async function fetchUserContext(event, url, fetchOptions, fetcher) {
+    const inboundCookie = event.request.headers.get('cookie') ?? '';
+    const response = await fetcher(url, {
+        ...fetchOptions,
+        headers: vibesServerRequestHeaders(event, {
+            'Content-Type': 'application/json',
+            ...fetchOptions.headers
+        }, {
+            // account-web accepts the session bearer for this route, then
+            // forwards the inbound cookie to auth `/api/auth/permissions`
+            // and reads `activeProject` in createActiveProjectHandle.
+            // It has no userContext handle, so an acting-org header 403s.
+            cookie: inboundCookie,
+            activeOrg: false
+        })
+    });
+    if (!response.ok) {
+        throw new UserContextUnavailableError('user-context-upstream-failed', response.status);
+    }
+    // The context is parsed at this boundary: a body that is not an object (or
+    // whose org/team lists do not fit) is a failed lookup, recorded by the handle
+    // as `userContextError`, never published into locals.
+    const context = UserContextSchema.safeParse(await response.json());
+    if (!context.success) {
+        throw new UserContextUnavailableError('user-context-invalid-payload');
+    }
+    return context.data;
+}

package/dist/lib/server/helpers/auth.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Authentication and authorization helper functions
+ */
+import type { AuthConfig, AuthHelper } from '../../types';
+/**
+ * Authentication helper functions for common patterns
+ */
+export declare const auth: AuthHelper;
+/**
+ * Common permission patterns
+ */
+export declare const permissions: {
+    chatRead: () => AuthConfig;
+    chatWrite: () => AuthConfig;
+    chatReadOwn: () => AuthConfig;
+    chatWriteOwn: () => AuthConfig;
+    projectRead: () => AuthConfig;
+    projectWrite: () => AuthConfig;
+    projectAdmin: () => AuthConfig;
+    knowledgeRead: () => AuthConfig;
+    knowledgeWrite: () => AuthConfig;
+    knowledgeAdmin: () => AuthConfig;
+    aiGenerate: () => AuthConfig;
+    aiModels: () => AuthConfig;
+    aiProviders: () => AuthConfig;
+    userRead: () => AuthConfig;
+    userWrite: () => AuthConfig;
+    userAdmin: () => AuthConfig;
+    adminRead: () => AuthConfig;
+    adminWrite: () => AuthConfig;
+    adminAll: () => AuthConfig;
+    billingRead: () => AuthConfig;
+    billingWrite: () => AuthConfig;
+    billingAdmin: () => AuthConfig;
+};
+/**
+ * Common role patterns
+ */
+export declare const roles: {
+    admin: () => AuthConfig;
+    moderator: () => AuthConfig;
+    user: () => AuthConfig;
+    adminOrModerator: () => AuthConfig;
+    staffMember: () => AuthConfig;
+};

package/dist/lib/server/helpers/auth.js

@@ -0,0 +1,98 @@
+/**
+ * Authentication and authorization helper functions
+ */
+/**
+ * Authentication helper functions for common patterns
+ */
+export const auth = {
+    /**
+     * Public endpoint (no authentication required)
+     */
+    public() {
+        return {
+            required: false
+        };
+    },
+    /**
+     * Require authentication for this endpoint
+     */
+    required() {
+        return {
+            required: true
+        };
+    },
+    /**
+     * Require specific permissions
+     * @param perms Array of permissions in format "resource:action" or "resource:action:own"
+     */
+    permissions(perms) {
+        return {
+            required: true,
+            permissions: perms
+        };
+    },
+    /**
+     * Require specific roles
+     * @param roles Array of role names
+     */
+    roles(roles) {
+        return {
+            required: true,
+            roles
+        };
+    },
+    /**
+     * Require admin access
+     */
+    adminOnly() {
+        return {
+            required: true,
+            adminOnly: true
+        };
+    }
+};
+/**
+ * Common permission patterns
+ */
+export const permissions = {
+    // Chat permissions
+    chatRead: () => auth.permissions(['chat:read']),
+    chatWrite: () => auth.permissions(['chat:write']),
+    chatReadOwn: () => auth.permissions(['chat:read:own']),
+    chatWriteOwn: () => auth.permissions(['chat:write:own']),
+    // Project permissions
+    projectRead: () => auth.permissions(['project:read']),
+    projectWrite: () => auth.permissions(['project:write']),
+    projectAdmin: () => auth.permissions(['project:admin']),
+    // Knowledge permissions
+    knowledgeRead: () => auth.permissions(['knowledge:read']),
+    knowledgeWrite: () => auth.permissions(['knowledge:write']),
+    knowledgeAdmin: () => auth.permissions(['knowledge:admin']),
+    // AI permissions
+    aiGenerate: () => auth.permissions(['ai:generate']),
+    aiModels: () => auth.permissions(['ai:models']),
+    aiProviders: () => auth.permissions(['ai:providers']),
+    // User permissions
+    userRead: () => auth.permissions(['user:read']),
+    userWrite: () => auth.permissions(['user:write']),
+    userAdmin: () => auth.permissions(['user:admin']),
+    // Admin permissions
+    adminRead: () => auth.permissions(['admin:read']),
+    adminWrite: () => auth.permissions(['admin:write']),
+    adminAll: () => auth.permissions(['admin:all']),
+    // Billing permissions
+    billingRead: () => auth.permissions(['billing:read']),
+    billingWrite: () => auth.permissions(['billing:write']),
+    billingAdmin: () => auth.permissions(['billing:admin'])
+};
+/**
+ * Common role patterns
+ */
+export const roles = {
+    admin: () => auth.roles(['admin']),
+    moderator: () => auth.roles(['moderator']),
+    user: () => auth.roles(['user']),
+    // Multiple role options
+    adminOrModerator: () => auth.roles(['admin', 'moderator']),
+    staffMember: () => auth.roles(['admin', 'moderator', 'staff'])
+};

package/dist/lib/server/helpers/billing.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Billing and subscription helper functions
+ */
+import type { BillingConfigEnhanced, BillingHelper } from '../../types';
+export { planNormalizer } from '../../billing/plan-normalizer.js';
+export declare const comparePlanPriority: (a: string, b: string) => number;
+export declare const isPlanAtLeast: (current: string, minimum: string) => boolean;
+export declare const isPlanOneOf: (current: string, plans: string[]) => boolean;
+export declare const planPriorityOrder: readonly string[];
+export declare const normalizeTierSlug: (slug: string | null | undefined) => string | null;
+export declare const normalizePlanSlug: (slug: string | null | undefined) => string | null;
+export declare const normalizePlanComparisonValue: (slug: string | null | undefined) => string | null;
+export declare const canonicalTierPriority: () => readonly string[];
+/** A billing configuration that could not be built safely (fixed message, no values). */
+export declare class BillingConfigError extends RangeError {
+    constructor(message: string);
+}
+/**
+ * A billing configuration whose credits depend on the request: `credits` is
+ * the reservation made before the size is known; `creditsFor` computes (and
+ * validates) the credits for a request of the given size or volume.
+ */
+export interface DynamicBillingConfig<TRequestSize> extends BillingConfigEnhanced<TRequestSize> {
+    creditsFor: (requestSize: TRequestSize) => number;
+}
+/**
+ * Common billing patterns for different endpoint types
+ */
+export declare const billingPatterns: {
+    /**
+     * AI text generation billing pattern
+     */
+    aiTextGeneration: () => BillingConfigEnhanced;
+    /**
+     * AI image generation billing pattern
+     */
+    aiImageGeneration: () => BillingConfigEnhanced;
+    /**
+     * Knowledge extraction billing pattern
+     */
+    knowledgeExtraction: () => BillingConfigEnhanced;
+    /**
+     * Web crawling billing pattern
+     */
+    webCrawl: () => BillingConfigEnhanced;
+    /**
+     * Benchmark execution billing pattern
+     */
+    benchmarkExecution: () => BillingConfigEnhanced;
+    /**
+     * Workbench execution billing pattern
+     */
+    workbench: () => BillingConfigEnhanced;
+    /**
+     * Free tier - no billing required
+     */
+    free: () => BillingConfigEnhanced;
+};
+/**
+ * Billing helper functions for common patterns
+ */
+export declare const billing: BillingHelper;
+/**
+ * Create billing configuration with multiple features
+ */
+export declare function requireFeatures(features: string[]): BillingConfigEnhanced;
+/**
+ * Create billing configuration with custom settings
+ */
+export declare function customBilling<TSize = number>(config: Partial<BillingConfigEnhanced<TSize>>): BillingConfigEnhanced<TSize>;
+/**
+ * Billing configuration for free tier endpoints
+ */
+export declare function freeTier(): BillingConfigEnhanced;
+/**
+ * Billing configuration for premium only endpoints
+ */
+export declare function premiumOnly(upgradeUrl?: string): BillingConfigEnhanced;
+/**
+ * Dynamic credit calculation based on request
+ */
+export declare function dynamicCredits<TRequestSize>(quotaFeature: string, calculator: (requestSize: TRequestSize) => number): DynamicBillingConfig<TRequestSize>;
+/**
+ * Rate-based billing (e.g., per minute of usage)
+ */
+export declare function rateBased(quotaFeature: string, ratePerUnit: number, _unit?: 'second' | 'minute' | 'hour'): BillingConfigEnhanced;
+/**
+ * Tiered billing based on usage volume. Every tier is honoured: `creditsFor(volume)`
+ * is the rate of the highest tier whose threshold the volume reaches (volumes below
+ * every threshold pay the lowest tier). `credits` is the first tier's rate, the
+ * reservation until the volume is known. No tiers is a typed refusal.
+ */
+export declare function tieredBilling(quotaFeature: string, tiers: Array<{
+    threshold: number;
+    rate: number;
+}>): DynamicBillingConfig<number>;
+/**
+ * Billing for experimental features
+ */
+export declare function experimental(feature: string): BillingConfigEnhanced;
+/**
+ * Billing for beta features
+ */
+export declare function beta(feature: string): BillingConfigEnhanced;