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

package/dist/lib/server/middleware/versioning.js

@@ -0,0 +1,98 @@
+import { error } from '@sveltejs/kit';
+export const API_VERSIONS = {
+    v1: '1.0.0',
+    v2: '2.0.0' // Future version
+};
+export const DEFAULT_VERSION = 'v1';
+/**
+ * A declared version. Own keys only: an inherited name such as `constructor`
+ * in a client-supplied header is not a version.
+ */
+function isApiVersion(value) {
+    return Object.hasOwn(API_VERSIONS, value);
+}
+/**
+ * Extract API version from request
+ * Supports both URL path versioning (/api/v1/...) and header versioning (X-API-Version: v1)
+ */
+export function getApiVersion(request) {
+    // Check URL path for version
+    const urlPath = new URL(request.url).pathname;
+    const pathVersion = urlPath.match(/\/api\/(v\d+)\//)?.[1];
+    if (pathVersion !== undefined && isApiVersion(pathVersion)) {
+        return pathVersion;
+    }
+    // Check header for version
+    const headerVersion = request.headers.get('X-API-Version');
+    if (headerVersion !== null && isApiVersion(headerVersion)) {
+        return headerVersion;
+    }
+    // Default to v1
+    return DEFAULT_VERSION;
+}
+/**
+ * Middleware to handle API versioning
+ */
+export function withApiVersion(handlers, defaultHandler) {
+    return async (event) => {
+        const version = getApiVersion(event.request);
+        const handler = handlers[version] || defaultHandler;
+        if (!handler) {
+            throw error(404, `API version ${version} not supported for this endpoint`);
+        }
+        // Add version to response headers
+        const response = await handler(event);
+        if (response instanceof Response) {
+            response.headers.set('X-API-Version', version);
+            response.headers.set('X-Supported-Versions', Object.keys(API_VERSIONS).join(', '));
+        }
+        return response;
+    };
+}
+/**
+ * Mark an endpoint as deprecated
+ */
+export function withDeprecation(handler, deprecationInfo) {
+    return async (event) => {
+        const response = await handler(event);
+        if (response instanceof Response) {
+            response.headers.set('Deprecation', 'true');
+            response.headers.set('X-Deprecation-Since', deprecationInfo.since);
+            if (deprecationInfo.sunset) {
+                response.headers.set('Sunset', deprecationInfo.sunset);
+            }
+            if (deprecationInfo.alternative) {
+                response.headers.set('Link', `<${deprecationInfo.alternative}>; rel="successor-version"`);
+            }
+            // Add deprecation warning header
+            const warning = `299 - "This endpoint is deprecated${deprecationInfo.sunset ? ` and will be removed on ${deprecationInfo.sunset}` : ''}${deprecationInfo.alternative ? `. Use ${deprecationInfo.alternative} instead` : ''}"`;
+            response.headers.set('Warning', warning);
+        }
+        return response;
+    };
+}
+/**
+ * Example usage:
+ *
+ * // Version-specific handlers
+ * export const GET = withApiVersion({
+ *   v1: withValidation(async (event) => {
+ *     // v1 implementation
+ *   }),
+ *   v2: withValidation(async (event) => {
+ *     // v2 implementation with new features
+ *   })
+ * });
+ *
+ * // Deprecated endpoint
+ * export const POST = withDeprecation(
+ *   withValidation(async (event) => {
+ *     // Implementation
+ *   }),
+ *   {
+ *     since: '2024-01-01',
+ *     sunset: '2024-06-01',
+ *     alternative: '/api/v2/new-endpoint'
+ *   }
+ * );
+ */

package/dist/lib/server/outbound.d.ts

@@ -0,0 +1,37 @@
+import type { RequestEvent } from '@sveltejs/kit';
+export interface VibesServerFetchOptions {
+    /**
+     * Cookie header to send. Default forwards the inbound Cookie. Pass `''`
+     * to send none, or a pin/transform (for example active-org).
+     */
+    cookie?: string | ((inboundCookie: string) => string);
+    /** Additional fixed headers. Cookie/authorization remain owned by this helper. */
+    headers?: HeadersInit;
+    /**
+     * Acting-org assertion (`x-vibes-active-org`). Default pins
+     * `locals.activeOrgId` only for destinations on an origin the request
+     * runtime's declared platform or app service names (those hosts load
+     * userContext before the org handle). account-web
+     * treats the header as fail-closed against JWT `orgs` only — pass
+     * `false` to send none, `true` to pin on every call, or a string to
+     * pin an explicit id.
+     */
+    activeOrg?: boolean | string;
+    /** Request URL used to decide the default pin. `createVibesServerFetch` sets this. */
+    destination?: string;
+}
+/** Minimal, runtime-neutral HTTP request capability used by server bridges. */
+export type VibesServerFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Build the authenticated headers for a Vibes server-to-server call.
+ * Default forwards the inbound Cookie and, when `locals.sessionToken` is
+ * present, adds `Authorization: Bearer <locals.sessionToken>`. A token
+ * refreshed by the session handle always wins over stale inbound credentials.
+ * `x-vibes-active-org` is pinned from `locals.activeOrgId` for platform/app
+ * destinations (those handles can verify membership). account-web cannot;
+ * pass `activeOrg: false` to suppress, `true` to pin on every call.
+ * Callers that need no cookie pass `cookie: ''`.
+ */
+export declare function vibesServerRequestHeaders(event: Pick<RequestEvent, 'request' | 'locals'>, initHeaders?: HeadersInit, options?: VibesServerFetchOptions): Headers;
+/** Request-scoped fetch that forwards current Vibes identity without ambient globals. */
+export declare function createVibesServerFetch(event: Pick<RequestEvent, 'request' | 'locals' | 'fetch'>, options?: VibesServerFetchOptions): VibesServerFetch;

package/dist/lib/server/outbound.js

@@ -0,0 +1,105 @@
+import { canonicalOrigin } from '@vibesdotdev/infra-core/service';
+import { kitLogger } from '../kit-logger';
+import { ACTIVE_ORG_HEADER_NAME } from "./handles/active-org.js";
+import { asVibesKitLocals } from "./locals.js";
+import { declaredServiceOrigins } from "./services/service-transport.js";
+const logger = kitLogger('outbound');
+/**
+ * Declared services whose request handles verify an asserted acting org (they
+ * load the user context before the org handle). Every origin they declare on
+ * the request runtime, their loopback dev transports included, gets the
+ * default pin; Kit names none of those origins itself.
+ */
+const ACTIVE_ORG_PIN_SERVICE_IDS = new Set(['platform', 'app']);
+function hrefOf(input) {
+    // A URL and a string stringify to their href; only a Request carries it as `.url`.
+    return input instanceof Request ? input.url : String(input);
+}
+function isCookieTransform(cookie) {
+    return typeof cookie === 'function';
+}
+function isExplicitActingOrg(activeOrg) {
+    return typeof activeOrg === 'string';
+}
+/**
+ * Whether `destination` is an origin a pin service declares on the request
+ * runtime, compared canonically (case and trailing root dots never matter;
+ * a lookalike never matches). A path-relative destination stays on the
+ * calling app and gets no default pin.
+ */
+function destinationAcceptsActiveOrgHeader(runtime, requestUrl, destination) {
+    if (!destination)
+        return false;
+    if (!URL.canParse(destination, requestUrl)) {
+        logger.warn('outbound: destination URL unparseable; skipping active-org pin', {
+            destination
+        });
+        return false;
+    }
+    const resolved = new URL(destination, requestUrl);
+    if (!URL.canParse(destination) && resolved.origin === new URL(requestUrl).origin)
+        return false;
+    const origin = canonicalOrigin(resolved);
+    return (origin !== undefined && declaredServiceOrigins(runtime, ACTIVE_ORG_PIN_SERVICE_IDS).has(origin));
+}
+function resolveActingOrgId(localsActiveOrgId, options, acceptsPin) {
+    if (options.activeOrg === false || options.activeOrg === '')
+        return undefined;
+    if (isExplicitActingOrg(options.activeOrg)) {
+        const pinned = options.activeOrg.trim();
+        return pinned.length > 0 ? pinned : undefined;
+    }
+    const fromLocals = localsActiveOrgId?.trim();
+    if (!fromLocals)
+        return undefined;
+    if (options.activeOrg === true)
+        return fromLocals;
+    if (acceptsPin(options.destination))
+        return fromLocals;
+    return undefined;
+}
+/**
+ * Build the authenticated headers for a Vibes server-to-server call.
+ * Default forwards the inbound Cookie and, when `locals.sessionToken` is
+ * present, adds `Authorization: Bearer <locals.sessionToken>`. A token
+ * refreshed by the session handle always wins over stale inbound credentials.
+ * `x-vibes-active-org` is pinned from `locals.activeOrgId` for platform/app
+ * destinations (those handles can verify membership). account-web cannot;
+ * pass `activeOrg: false` to suppress, `true` to pin on every call.
+ * Callers that need no cookie pass `cookie: ''`.
+ */
+export function vibesServerRequestHeaders(event, initHeaders, options = {}) {
+    const headers = new Headers(options.headers);
+    new Headers(initHeaders).forEach((value, key) => headers.set(key, value));
+    const inboundCookie = event.request.headers.get('cookie') ?? '';
+    const cookie = isCookieTransform(options.cookie)
+        ? options.cookie(inboundCookie)
+        : (options.cookie ?? inboundCookie);
+    if (cookie)
+        headers.set('cookie', cookie);
+    else
+        headers.delete('cookie');
+    const locals = asVibesKitLocals(event.locals);
+    const refreshed = locals.sessionToken?.trim();
+    const inboundAuthorization = event.request.headers.get('authorization')?.trim();
+    const authorization = refreshed ? `Bearer ${refreshed}` : inboundAuthorization;
+    if (authorization)
+        headers.set('authorization', authorization);
+    else
+        headers.delete('authorization');
+    const actingOrg = resolveActingOrgId(locals.activeOrgId, options, (destination) => destinationAcceptsActiveOrgHeader(locals.runtime, event.request.url, destination));
+    if (actingOrg && !headers.has(ACTIVE_ORG_HEADER_NAME)) {
+        headers.set(ACTIVE_ORG_HEADER_NAME, actingOrg);
+    }
+    return headers;
+}
+/** Request-scoped fetch that forwards current Vibes identity without ambient globals. */
+export function createVibesServerFetch(event, options = {}) {
+    return (input, init) => event.fetch(input, {
+        ...init,
+        headers: vibesServerRequestHeaders(event, init?.headers, {
+            ...options,
+            destination: options.destination ?? hrefOf(input)
+        })
+    });
+}

package/dist/lib/server/page/load.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Server-side load function wrappers for SvelteKit
+ *
+ * Provides consistent permission checking, validation, and middleware
+ * for +page.server.ts and +layout.server.ts load functions
+ */
+import type { RequestEvent } from '@sveltejs/kit';
+import type { AuthConfig } from '../../types';
+import type { VibesKitUser } from '../locals.js';
+/** Minimal user shape passed to load/action handlers */
+type LoadUser = VibesKitUser;
+/**
+ * SvelteKit's generated `RequestEvent` default is scoped to the routes of the
+ * package currently being checked. A reusable wrapper cannot use that default:
+ * it would erase a consuming app's dynamic params. Keep the event contract and
+ * expose route params as the runtime truth (present string values), while
+ * allowing consumers to supply a narrower param map when useful.
+ */
+export type VibesRequestEvent<Params extends Record<string, string> = Record<string, string>> = Omit<RequestEvent, 'params'> & {
+    params: Params;
+};
+export interface LoadConfig {
+    /** Authentication and permission requirements */
+    auth?: AuthConfig;
+    /** Logging configuration */
+    logging?: boolean;
+    /** Load function metadata */
+    metadata?: {
+        name?: string;
+        description?: string;
+    };
+}
+export type LoadHandler<T = unknown, Params extends Record<string, string> = Record<string, string>> = (event: VibesRequestEvent<Params>, context: {
+    user?: LoadUser;
+}) => T | Promise<T>;
+export type ActionHandler<T = unknown, Params extends Record<string, string> = Record<string, string>> = (event: VibesRequestEvent<Params>, context: {
+    user?: LoadUser;
+}) => T | Promise<T>;
+/**
+ * Wrapper for SvelteKit page load functions
+ */
+export declare function vibesPageLoad<T = unknown, Params extends Record<string, string> = Record<string, string>>(config: LoadConfig, handler: LoadHandler<T, Params>): (event: VibesRequestEvent<Params>) => Promise<T>;
+/**
+ * Wrapper for SvelteKit layout load functions
+ */
+export declare function vibesLayoutLoad<T = unknown, Params extends Record<string, string> = Record<string, string>>(config: LoadConfig, handler: LoadHandler<T, Params>): (event: VibesRequestEvent<Params>) => Promise<T>;
+/**
+ * Wrapper for SvelteKit form actions
+ */
+export declare function vibesAction<T = unknown, Params extends Record<string, string> = Record<string, string>>(config: LoadConfig, handler: ActionHandler<T, Params>): (event: VibesRequestEvent<Params>) => Promise<T>;
+export {};

package/dist/lib/server/page/load.js

@@ -0,0 +1,112 @@
+/**
+ * Server-side load function wrappers for SvelteKit
+ *
+ * Provides consistent permission checking, validation, and middleware
+ * for +page.server.ts and +layout.server.ts load functions
+ */
+import { applyPermissionCheck, AuthenticationError, PermissionError } from '../middleware/permission-checker';
+import { getVibesKit } from '../../instance';
+const PAGE_LOAD_LOGGING = {
+    category: 'page-load',
+    completed: 'Page load completed',
+    authenticationFailed: 'Page load authentication failed',
+    permissionDenied: 'Page load permission denied',
+    failed: 'Page load failed',
+    includeMethod: false
+};
+const LAYOUT_LOAD_LOGGING = {
+    category: 'layout-load',
+    completed: 'Layout load completed',
+    authenticationFailed: 'Layout load authentication failed',
+    permissionDenied: 'Layout load permission denied',
+    failed: 'Layout load failed',
+    includeMethod: false
+};
+const ACTION_LOGGING = {
+    category: 'action',
+    completed: 'Action completed',
+    authenticationFailed: 'Action authentication failed',
+    permissionDenied: 'Action permission denied',
+    failed: 'Action failed',
+    includeMethod: true
+};
+/**
+ * Run `handler` for `event` behind `config.auth`. The event reaches the
+ * handler unchanged, so its route `params` keep the caller's declared type.
+ * A refusal (`AuthenticationError`, `PermissionError`) or handler failure is
+ * logged once and rethrown untouched; the handler never runs after a refusal.
+ */
+async function runWrapped(logging, config, handler, event) {
+    const kit = getVibesKit();
+    const logger = kit.config.services?.logger;
+    const startTime = performance.now();
+    const pathname = event.url.pathname;
+    const where = logging.includeMethod
+        ? { path: pathname, method: event.request.method }
+        : { path: pathname };
+    try {
+        // 1. Authentication and permissions
+        let user = undefined;
+        if (config.auth) {
+            const authResult = await applyPermissionCheck(event, config.auth);
+            user = authResult.user;
+        }
+        // 2. Execute handler
+        const result = await handler(event, { user });
+        // 3. Logging
+        if (config.logging) {
+            logger?.info(logging.completed, {
+                ...where,
+                duration: Math.round(performance.now() - startTime),
+                hasUser: !!user,
+                category: logging.category
+            });
+        }
+        return result;
+    }
+    catch (error) {
+        const duration = Math.round(performance.now() - startTime);
+        if (error instanceof AuthenticationError) {
+            logger?.warn(logging.authenticationFailed, {
+                ...where,
+                duration,
+                error: error.message,
+                category: logging.category
+            });
+            throw error;
+        }
+        if (error instanceof PermissionError) {
+            logger?.warn(logging.permissionDenied, {
+                ...where,
+                duration,
+                error: error.message,
+                category: logging.category
+            });
+            throw error;
+        }
+        logger?.error(logging.failed, error instanceof Error ? error : new Error(String(error)), {
+            ...where,
+            duration,
+            category: logging.category
+        });
+        throw error;
+    }
+}
+/**
+ * Wrapper for SvelteKit page load functions
+ */
+export function vibesPageLoad(config, handler) {
+    return (event) => runWrapped(PAGE_LOAD_LOGGING, config, handler, event);
+}
+/**
+ * Wrapper for SvelteKit layout load functions
+ */
+export function vibesLayoutLoad(config, handler) {
+    return (event) => runWrapped(LAYOUT_LOAD_LOGGING, config, handler, event);
+}
+/**
+ * Wrapper for SvelteKit form actions
+ */
+export function vibesAction(config, handler) {
+    return (event) => runWrapped(ACTION_LOGGING, config, handler, event);
+}

package/dist/lib/server/runtime-bound-logger.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A kit logger bound to a runtime the host hands the kit.
+ *
+ * Kit modules read one `services.logger` and call it with no runtime, but a
+ * logger that belongs to a runtime (`getLogger(id, runtime)`) cannot exist
+ * before a runtime does. An app declares a factory instead of a logger; the
+ * kit resolves it on the first runtime it is handed (`bind`), once per runtime,
+ * and logs through that logger from then on. Before the first runtime there is
+ * nothing to log on, so an entry is dropped.
+ */
+import type { Logger } from '../types/kit';
+import type { VibesKitRuntimePort } from './locals';
+/** Builds the kit's logger on one handed runtime. */
+export type KitLoggerFactory<Runtime extends VibesKitRuntimePort = VibesKitRuntimePort> = (runtime: Runtime) => Logger;
+export interface RuntimeBoundLogger extends Logger {
+    /** Resolve the factory on `runtime` (once per runtime) and log through its logger from now on. */
+    bind(runtime: VibesKitRuntimePort): void;
+}
+export declare function createRuntimeBoundLogger<Runtime extends VibesKitRuntimePort>(factory: KitLoggerFactory<Runtime>): RuntimeBoundLogger;
+export declare function isRuntimeBoundLogger(logger: Logger | undefined): logger is RuntimeBoundLogger;
+/**
+ * Hand the initialized kit's logger the runtime a seam was given. A kit whose
+ * logger was injected as a plain `Logger` is unaffected.
+ */
+export declare function bindKitLogger(runtime: VibesKitRuntimePort): void;

package/dist/lib/server/runtime-bound-logger.js

@@ -0,0 +1,46 @@
+/**
+ * A kit logger bound to a runtime the host hands the kit.
+ *
+ * Kit modules read one `services.logger` and call it with no runtime, but a
+ * logger that belongs to a runtime (`getLogger(id, runtime)`) cannot exist
+ * before a runtime does. An app declares a factory instead of a logger; the
+ * kit resolves it on the first runtime it is handed (`bind`), once per runtime,
+ * and logs through that logger from then on. Before the first runtime there is
+ * nothing to log on, so an entry is dropped.
+ */
+import { kitSlot } from '../kit-slot';
+const BOUND = Symbol.for('vibesdotdev.kit.runtimeBoundLogger');
+export function createRuntimeBoundLogger(factory) {
+    const resolved = new WeakMap();
+    let current;
+    const logger = {
+        [BOUND]: true,
+        bind(runtime) {
+            let bound = resolved.get(runtime);
+            if (!bound) {
+                // SAFETY: the host hands the kit the runtime the app's factory declared
+                // (`event.locals.runtime`); the kit only knows it structurally.
+                bound = factory(runtime);
+                resolved.set(runtime, bound);
+            }
+            current = bound;
+        },
+        debug: (message, meta) => current?.debug(message, meta),
+        info: (message, meta) => current?.info(message, meta),
+        warn: (message, meta) => current?.warn(message, meta),
+        error: (message, error, meta) => current?.error(message, error, meta)
+    };
+    return logger;
+}
+export function isRuntimeBoundLogger(logger) {
+    return logger !== undefined && BOUND in logger;
+}
+/**
+ * Hand the initialized kit's logger the runtime a seam was given. A kit whose
+ * logger was injected as a plain `Logger` is unaffected.
+ */
+export function bindKitLogger(runtime) {
+    const logger = kitSlot().kit?.config.services?.logger;
+    if (isRuntimeBoundLogger(logger))
+        logger.bind(runtime);
+}

package/dist/lib/server/services/account-billing-adapter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Account Billing HTTP Adapter
+ *
+ * Implements the BillingService interface by calling account-web's
+ * internal billing endpoints. Authenticates with the shared
+ * `VIBES_INTERNAL_SERVICE_TOKEN` bearer and supplies `X-Vibes-User-Id`
+ * as the billing subject.
+ *
+ * Routes through a Cloudflare Service Binding to `vibes-account` when one
+ * is handed by the runtime. Without one it uses global `fetch` against the
+ * transport the request runtime's declared account service names for
+ * `accountOrigin` (its local dev server's loopback origin in the local tier);
+ * an `accountOrigin` no declared service serves refuses `service-undeclared`.
+ */
+import type { BillingService } from '../../types/kit';
+import type { VibesKitRuntimePort } from '../locals.js';
+type FetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Minimal duck type for a Cloudflare Service Binding fetcher. Equivalent to
+ * `Fetcher` from `@cloudflare/workers-types`, but typed locally so vibeskit
+ * doesn't take a CF-types dependency.
+ */
+export interface AccountServiceBinding {
+    fetch: FetchFn;
+}
+export declare function setBillingRequestCookie(_cookie: string): void;
+export interface AccountBillingAdapterOptions {
+    /**
+     * Origin of the account service, as its declaration names it (e.g.
+     * 'https://account.vibes.dev'); the adapter calls the transport that
+     * declaration names for it. Pass a thunk when the URL depends on a declared host value: it receives
+     * the request's runtime port and may be async (the adapter resolves it per
+     * call — apps have no runtime at module load).
+     */
+    accountOrigin: string | ((runtime: VibesKitRuntimePort) => string | Promise<string>);
+    /**
+     * Internal service token. Must match account-web's
+     * `VIBES_INTERNAL_SERVICE_TOKEN`. Pass a function to resolve the credential
+     * through the request's runtime port (`runtime.resolveCredential`). When omitted,
+     * `VIBES_INTERNAL_SERVICE_TOKEN` is resolved through `runtime.resolveCredential`
+     * (a resolution failure throws).
+     */
+    serviceToken?: string | ((runtime: VibesKitRuntimePort) => string | Promise<string>);
+    /**
+     * Optional Cloudflare Service Binding to `vibes-account`. When provided,
+     * every internal billing call goes through Worker-to-Worker RPC. A function
+     * receives the request's runtime port.
+     */
+    accountBinding?: AccountServiceBinding | ((runtime: VibesKitRuntimePort) => AccountServiceBinding | undefined);
+}
+export declare function createAccountBillingAdapter(options: AccountBillingAdapterOptions): BillingService;
+export {};