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

package/dist/lib/server/hooks/cors.d.ts

@@ -0,0 +1,47 @@
+import type { Handle, RequestEvent } from '@sveltejs/kit';
+/**
+ * Decide whether `origin` is trusted for this request, from a registry (for
+ * example Auth's registered-app resolver), never a static list. Called at most
+ * once per request, only when an `Origin` header is present. A throw refuses.
+ */
+export type CorsOriginResolver = (origin: string, event: RequestEvent) => Promise<boolean>;
+export interface CorsHandleOptions {
+    /**
+     * Static origin patterns. Kept for existing callers while they migrate to
+     * `resolveOrigin`; when both are given an origin is admitted if either
+     * admits it.
+     */
+    allowedOrigins?: readonly string[];
+    /** Registry-backed trust: the preferred way to admit origins. */
+    resolveOrigin?: CorsOriginResolver;
+    allowedMethods?: readonly string[];
+    allowedHeaders?: readonly string[];
+    allowCredentials?: boolean;
+    maxAge?: number;
+    /**
+     * Marks this handle as running in a development build. Mirrors the
+     * `isDev` option `createVibesHandle` and `applySecurityHeaders` already
+     * take, so pass the same value: `isDev: DEV` from `esm-env` in
+     * `hooks.server.ts`.
+     *
+     * Defaults to `false` (fail closed). When `false`, loopback-origin
+     * entries in `allowedOrigins` (`localhost`, `127.0.0.1`, `[::1]`,
+     * `*.localhost`, and any `http://localhost:*`-style entry) are ignored
+     * for matching purposes, so a page served from a loopback origin cannot
+     * make credentialed cross-origin requests against a production
+     * deployment. Non-loopback entries (e.g. `*.vibes.dev`) are unaffected
+     * by this flag.
+     */
+    isDev?: boolean;
+    /**
+     * Security escape hatch: honor loopback-origin entries in
+     * `allowedOrigins` even when `isDev` is not set. This intentionally
+     * re-opens the credentialed-loopback-origin surface that `isDev`
+     * defaulting to `false` closes — only set this to `true` if the
+     * production deployment must accept credentialed requests from a
+     * loopback origin (e.g. a local companion app talking to a hosted
+     * backend). Defaults to `false`.
+     */
+    allowLoopbackInProduction?: boolean;
+}
+export declare function createCorsHandle(options: CorsHandleOptions): Handle;

package/dist/lib/server/hooks/cors.js

@@ -0,0 +1,203 @@
+import { DEV } from 'esm-env';
+import { isHttpError, isRedirect } from '@sveltejs/kit';
+import * as z from 'zod/v4';
+import { settle } from '../../attempt.js';
+import { failureClass } from '../../failure-class.js';
+import { kitLogger } from '../../kit-logger';
+const logger = kitLogger('vibeskit-cors');
+// `PUT` is first-class because apps use `vibesPUT`; origin allowlists remain the gate.
+const DEFAULT_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'];
+const DEFAULT_HEADERS = ['Content-Type', 'Authorization'];
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+// Classifies an `allowedOrigins` entry (not a request Origin) as loopback-only
+// so `createCorsHandle` can gate it behind `isDev` / `allowLoopbackInProduction`.
+function isLoopbackPattern(pattern) {
+    let host = pattern.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '');
+    if (host.endsWith(':*'))
+        host = host.slice(0, -2);
+    host = host.replace(/:\d+$/, '');
+    if (host.startsWith('*.'))
+        return host.slice(2) === 'localhost';
+    return LOOPBACK_HOSTS.has(host);
+}
+/** A request Origin served from a loopback host, on any port. */
+function isLoopbackOrigin(origin) {
+    if (!URL.canParse(origin))
+        return false;
+    const url = new URL(origin);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return false;
+    const host = url.hostname;
+    return LOOPBACK_HOSTS.has(host) || host.endsWith('.localhost');
+}
+function matchesAllowedOrigin(origin, patterns) {
+    // An Origin that fails URL parsing still matches allowlist patterns as a raw string.
+    const parsedOrigin = URL.canParse(origin) ? new URL(origin) : null;
+    for (const pattern of patterns) {
+        if (pattern.startsWith('*.')) {
+            const suffix = pattern.slice(1);
+            const apex = pattern.slice(2);
+            if (parsedOrigin?.hostname.endsWith(suffix))
+                return true;
+            if (parsedOrigin?.hostname === apex)
+                return true;
+            if (origin.endsWith(suffix))
+                return true;
+            if (origin === apex)
+                return true;
+        }
+        else if (pattern.endsWith(':*')) {
+            const prefix = pattern.slice(0, -2);
+            if (origin === prefix || origin.startsWith(`${prefix}:`))
+                return true;
+        }
+        else if (parsedOrigin?.hostname === pattern) {
+            return true;
+        }
+        else if (origin === pattern) {
+            return true;
+        }
+    }
+    return false;
+}
+export function createCorsHandle(options) {
+    const { allowedOrigins = [], resolveOrigin, allowedMethods = DEFAULT_METHODS, allowedHeaders = DEFAULT_HEADERS, allowCredentials = true, maxAge = 86400, isDev = DEV, allowLoopbackInProduction = false } = options;
+    // Computed once at handle-creation time (not per request): non-loopback
+    // entries pass through unchanged; loopback entries are dropped unless
+    // this is a dev build or the escape hatch is set.
+    if (!resolveOrigin && options.allowedOrigins === undefined) {
+        throw new TypeError('createCorsHandle needs resolveOrigin or allowedOrigins');
+    }
+    const honorLoopback = isDev || allowLoopbackInProduction;
+    const effectiveOrigins = honorLoopback
+        ? allowedOrigins
+        : allowedOrigins.filter((pattern) => !isLoopbackPattern(pattern));
+    async function admitOrigin(origin, event) {
+        if (matchesAllowedOrigin(origin, effectiveOrigins))
+            return true;
+        if (!resolveOrigin)
+            return false;
+        if (isDev && isLoopbackOrigin(origin))
+            return true;
+        const verdict = await settle(() => resolveOrigin(origin, event));
+        if (!verdict.ok) {
+            // Fail closed: an unanswerable registry admits nothing.
+            logger.warn('CORS origin resolver failed; refusing the origin', {
+                reason: failureClass(verdict.error)
+            });
+            return false;
+        }
+        return verdict.value === true;
+    }
+    return async ({ event, resolve }) => {
+        const origin = event.request.headers.get('Origin');
+        const isAllowed = origin ? await admitOrigin(origin, event) : false;
+        if (event.request.method === 'OPTIONS') {
+            if (!isAllowed || !origin) {
+                return new Response(null, { status: 403 });
+            }
+            return new Response(null, {
+                status: 204,
+                headers: {
+                    'Access-Control-Allow-Origin': origin,
+                    'Access-Control-Allow-Methods': allowedMethods.join(', '),
+                    'Access-Control-Allow-Headers': allowedHeaders.join(', '),
+                    'Access-Control-Allow-Credentials': allowCredentials ? 'true' : 'false',
+                    'Access-Control-Max-Age': maxAge.toString(),
+                    Vary: 'Origin'
+                }
+            });
+        }
+        const resolved = await settle(() => resolve(event));
+        let response;
+        if (resolved.ok) {
+            response = resolved.value;
+        }
+        else {
+            const err = resolved.error;
+            const isRedirectAnyGraph = isRedirect(err) || OtherGraphRedirectSchema.safeParse(err).success;
+            if (!isAllowed || !origin || isRedirectAnyGraph)
+                throw err;
+            const otherGraphError = OtherGraphHttpErrorSchema.safeParse(err);
+            const httpError = isHttpError(err)
+                ? err
+                : otherGraphError.success
+                    ? otherGraphError.data
+                    : null;
+            if (httpError === null) {
+                // The browser is told a fixed 500; what failed goes to the log.
+                logger.warn('CORS request handling failed; answering with a fixed 500', {
+                    reason: failureClass(err)
+                });
+            }
+            response = corsErrorResponse(httpError);
+        }
+        if (isAllowed && origin) {
+            applyCorsHeaders(response.headers, {
+                origin,
+                allowedMethods,
+                allowedHeaders,
+                allowCredentials
+            });
+        }
+        return response;
+    };
+}
+function applyCorsHeaders(headers, input) {
+    headers.set('Access-Control-Allow-Origin', input.origin);
+    headers.set('Access-Control-Allow-Methods', input.allowedMethods.join(', '));
+    headers.set('Access-Control-Allow-Headers', input.allowedHeaders.join(', '));
+    if (input.allowCredentials) {
+        headers.set('Access-Control-Allow-Credentials', 'true');
+    }
+    appendVary(headers, 'Origin');
+}
+function appendVary(headers, value) {
+    const current = headers.get('Vary');
+    if (!current) {
+        headers.set('Vary', value);
+        return;
+    }
+    const parts = current.split(',').map((part) => part.trim().toLowerCase());
+    if (!parts.includes(value.toLowerCase())) {
+        headers.set('Vary', `${current}, ${value}`);
+    }
+}
+/**
+ * Linked workspaces can load the app and Kit through different SvelteKit module
+ * instances. SvelteKit's helpers use `instanceof`, so a legitimate HttpError or
+ * Redirect from the app graph otherwise becomes an opaque 500 in Kit's graph.
+ * These shapes recognise the other graph's copies by their fields.
+ */
+const OtherGraphHttpErrorSchema = z.object({
+    status: z.number().int().min(400).max(599),
+    body: z.unknown()
+});
+const OtherGraphRedirectSchema = z.object({
+    status: z.number().int().min(300).max(399),
+    location: z.string()
+});
+/** An HttpError body is either the message itself or an object carrying one. */
+const HttpErrorMessageSchema = z.union([
+    z.string().min(1),
+    z.object({ message: z.string().min(1) }).transform((body) => body.message)
+]);
+function corsErrorResponse(httpError) {
+    const status = httpError?.status ?? 500;
+    const message = httpError ? extractHttpErrorMessage(httpError) : 'Internal Server Error';
+    return new Response(JSON.stringify({
+        error: {
+            message,
+            status
+        }
+    }), {
+        status,
+        headers: {
+            'content-type': 'application/json'
+        }
+    });
+}
+function extractHttpErrorMessage(httpError) {
+    const message = HttpErrorMessageSchema.safeParse(httpError.body);
+    return message.success ? message.data : 'Request failed';
+}

package/dist/lib/server/hooks/errors.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Error handling for SvelteKit hooks
+ *
+ * Provides createVibesErrorHandler() for standardized error handling
+ * with logging, exception capture, and environment-aware error responses.
+ *
+ * A thrown value is untrusted: it may carry a getter that throws, sit behind a
+ * Proxy, be circular, or hold a huge payload. `serializeError` therefore reads
+ * only a fixed set of well-known fields through guarded parses, copies only
+ * plain data properties (never invoking a custom getter), bounds every text and
+ * payload it keeps, and redacts credential-named fields. It never throws.
+ */
+import type { HandleServerError } from '@sveltejs/kit';
+import * as z from 'zod/v4';
+import { type KitJsonValue } from '../locals.js';
+/**
+ * Serialized error structure
+ */
+export interface SerializedError {
+    message: string;
+    name: string;
+    stack?: string;
+    code?: string;
+    statusCode?: number;
+    /** Custom properties of the thrown value, copied as JSON (bounded, credentials redacted). */
+    [key: string]: KitJsonValue | undefined;
+}
+/**
+ * The fields of a thrown object that are read, each guarded. Any object may be
+ * thrown; these are the ones a response or a log line is built from.
+ */
+export interface ThrownObject {
+    message?: string;
+    name?: string;
+    stack?: string;
+    code?: string;
+    status?: number;
+    statusCode?: number;
+}
+/** Anything a `throw` can carry, as a closed set of kinds. */
+export type ThrownValue = ThrownObject | string | number | boolean | bigint | symbol | null | undefined;
+/**
+ * Every kind of value a `throw` can carry. The boundary parse for a caught
+ * value: a catch clause's value, or SvelteKit's `error`, goes through
+ * `thrownValueOf` before it is serialized.
+ */
+export declare const ThrownValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodBigInt, z.ZodSymbol, z.ZodNull, z.ZodUndefined, z.ZodCustom<ThrownObject, ThrownObject>]>;
+/** The caught value as a `ThrownValue` (the parse accepts every value a `throw` can carry). */
+export declare function thrownValueOf<Caught>(caught: Caught): ThrownValue;
+/** What a 5xx's system-error log receives about the request beside the error itself. */
+export interface SystemErrorContext {
+    url: string;
+    method: string;
+    status: number;
+    userId: string | null;
+    environment: string;
+    requestId: string;
+    routeId: string | null;
+    serializedError: SerializedError;
+}
+/**
+ * Error handler configuration
+ */
+export interface ErrorHandlerConfig {
+    /** Environment name (development, staging, production) */
+    environment?: 'development' | 'staging' | 'production';
+    /** Whether to show detailed errors (default: auto-detect from environment) */
+    showDetailedErrors?: boolean;
+    /** Whether to show stack traces (default: auto-detect from environment) */
+    showStackTraces?: boolean;
+    /** Custom exception capture function (e.g., Sentry, PostHog) */
+    captureException?: (error: Error) => Promise<void>;
+    /** Custom system error logger */
+    logSystemError?: (error: Error, context: SystemErrorContext) => Promise<void>;
+}
+/**
+ * Run `schema` against `input` where reading it may itself fail (a throwing
+ * getter, a Proxy trap). A value that cannot be read carries no such field:
+ * the failed attempt is not reported, because the response must still be
+ * produced and the hostile value is never repeated.
+ */
+export declare function parseGuarded<Parsed, Input>(schema: z.ZodType<Parsed>, input: Input): Parsed | undefined;
+/**
+ * `value instanceof type` for a value that may be hostile: a Proxy whose
+ * prototype trap throws is simply not an instance.
+ */
+export declare function guardedInstanceOf<Thrown, Instance>(value: Thrown, type: abstract new (...args: never[]) => Instance): value is Thrown & Instance;
+/** The thrown value when it is an Error (guarded), else nothing. */
+export declare function errorInstance<Thrown>(value: Thrown): Error | undefined;
+/**
+ * An Error for whatever was thrown: the value itself when it is one, else an
+ * Error carrying its bounded description.
+ */
+export declare function failureAsError<Thrown>(value: Thrown): Error;
+/**
+ * Serialize error objects safely for JSON responses. Never throws, whatever
+ * was thrown; the result is bounded and carries no credential-named values.
+ *
+ * @param error - Error object to serialize
+ * @returns Serializable error object
+ */
+export declare function serializeError(error: ThrownValue): SerializedError;
+/**
+ * The text of a serialized error's `cause` (a string, or an object carrying a
+ * message), bounded; undefined when it has none.
+ */
+export declare function serializedCauseMessage(serialized: SerializedError): string | undefined;
+/**
+ * Create a vibes error handler for SvelteKit
+ *
+ * Handles errors with logging, exception capture, and environment-aware responses.
+ *
+ * @param config - Error handler configuration
+ * @returns SvelteKit HandleServerError function
+ *
+ * @example
+ * ```typescript
+ * export const handleError = createVibesErrorHandler({
+ *   environment: 'production',
+ *   captureException: async (error) => {
+ *     await sentry.captureException(error);
+ *   },
+ *   logSystemError: async (error, context) => {
+ *     await ActivityLogger.logSystemEvent('system.error', null, context);
+ *   }
+ * });
+ * ```
+ */
+export declare function createVibesErrorHandler(config?: ErrorHandlerConfig): ({ error, event, status, message }: Parameters<HandleServerError>[0]) => Promise<{
+    message: string;
+    name: string;
+    statusCode: number;
+    environment: "development" | "staging" | "production";
+    requestId: string;
+    method: string;
+    path: string;
+    routeId: string | undefined;
+    diagnostic: {
+        status: number;
+        requestId: string;
+        method: string;
+        path: string;
+        routeId: string | undefined;
+    } | undefined;
+    showDetailedErrors: boolean;
+    originalStatus: number;
+    stack?: undefined;
+    code?: undefined;
+    causeMessage?: undefined;
+    originalMessage?: undefined;
+} | {
+    message: string;
+    name: string;
+    stack: string | undefined;
+    code: string | undefined;
+    statusCode: number;
+    environment: "development" | "staging" | "production";
+    requestId: string;
+    method: string;
+    path: string;
+    routeId: string | undefined;
+    causeMessage: string | undefined;
+    diagnostic: {
+        status: number;
+        requestId: string;
+        method: string;
+        path: string;
+        routeId: string | undefined;
+        message: string;
+        name: string;
+        stack?: string;
+        code?: string;
+        statusCode?: number;
+    };
+    showDetailedErrors: boolean;
+    originalStatus: number;
+    originalMessage: string;
+} | {
+    message: string;
+    requestId: string;
+    environment: "development" | "staging" | "production";
+    showDetailedErrors: boolean;
+    name?: undefined;
+    statusCode?: undefined;
+    method?: undefined;
+    path?: undefined;
+    routeId?: undefined;
+    diagnostic?: undefined;
+    originalStatus?: undefined;
+    stack?: undefined;
+    code?: undefined;
+    causeMessage?: undefined;
+    originalMessage?: undefined;
+}>;