@sourceregistry/sveltekit-enhance 1.1.2 → 1.3.0

package/README.md

@@ -1,112 +1,396 @@
+<div align="center">
+
 # @sourceregistry/sveltekit-enhance
 
-[![npm version](https://img.shields.io/npm/v/@sourceregistry/sveltekit-enhance?logo=npm)](https://www.npmjs.com/package/@sourceregistry/sveltekit-enhance)
-[![License](https://img.shields.io/npm/l/@sourceregistry/sveltekit-enhance)](https://github.com/SourceRegistry/sveltekit-enhance/blob/main/LICENSE)
-[![CI](https://github.com/SourceRegistry/sveltekit-enhance/actions/workflows/ci.yml/badge.svg)](https://github.com/SourceRegistry/sveltekit-enhance/actions/workflows/ci.yml)
+**Composable middleware, guards, and form utilities for SvelteKit**
+
+[![npm version](https://img.shields.io/npm/v/@sourceregistry/sveltekit-enhance?style=flat-square&color=f96743)](https://www.npmjs.com/package/@sourceregistry/sveltekit-enhance)
+[![npm downloads](https://img.shields.io/npm/dm/@sourceregistry/sveltekit-enhance?style=flat-square)](https://www.npmjs.com/package/@sourceregistry/sveltekit-enhance)
+[![license](https://img.shields.io/npm/l/@sourceregistry/sveltekit-enhance?style=flat-square)](./LICENSE)
+[![SvelteKit](https://img.shields.io/badge/SvelteKit-%5E2.58-FF3E00?style=flat-square&logo=svelte&logoColor=white)](https://kit.svelte.dev)
+[![issues](https://img.shields.io/github/issues/SourceRegistry/sveltekit-enhance?style=flat-square)](https://github.com/SourceRegistry/sveltekit-enhance/issues)
+
+Wrap actions, loads, methods, and hooks with composable enhancers. Stack auth guards, feature flags, request tracing, and form parsing without touching SvelteKit's internals.
 
-Production-ready utilities for **SvelteKit server flows**.  
-Use `@sourceregistry/sveltekit-enhance` to build cleaner actions, loads, methods, and hooks with reusable guards for authentication, feature flags, request correlation, and form processing.
+[Docs](https://sourceregistry.github.io/sveltekit-enhance/) · [npm](https://www.npmjs.com/package/@sourceregistry/sveltekit-enhance) · [Issues](https://github.com/SourceRegistry/sveltekit-enhance/issues)
 
-## Why teams use this
+</div>
 
-- Standardize server-side context logic across routes.
-- Reduce repetitive request parsing and validation code.
-- Keep middleware-like behavior explicit and composable.
-- Improve observability with correlation IDs on every response.
+---
 
 ## Installation
 
-```bash
+```sh
 npm install @sourceregistry/sveltekit-enhance
 ```
 
-## Core concepts
+**Peer dependency:** `@sveltejs/kit ^2.58.0`
 
-The package provides an `enhance` wrapper for:
+---
 
-- `enhance.action(...)`
-- `enhance.load(...)`
-- `enhance.method(...)`
-- `enhance.handle(...)`
+## Overview
 
-Each wrapper accepts one or more context functions and merges their outputs into a typed `context` object.
+```ts
+import { enhance, Auth, RequestCorrelation, RequestMonitor, Form } from '@sourceregistry/sveltekit-enhance';
 
-## Quick start
+// hooks.server.ts
+export const handle = enhance.handle(
+    async ({ event, resolve }) => resolve(event),
+    RequestCorrelation.attach,
+    RequestMonitor.trace({ logger: myLogger, record: metrics.record }),
+);
 
-```ts
-// src/routes/account/+page.server.ts
-import {enhance} from '@sourceregistry/sveltekit-enhance';
-import {Auth, FeatureFlag, form} from '@sourceregistry/sveltekit-enhance';
+// +server.ts
+export const POST = enhance.method(
+    async (event) => new Response(JSON.stringify(event.context)),
+    Auth.Bearer,
+    FeatureFlag.all('PUBLIC_API_ENABLED'),
+);
 
+// +page.server.ts
 export const actions = {
-  save: enhance.action(
-    async ({request, context}) => {
-      const data = await request.formData();
-      const email = form.string$(data, 'email');
-
-      return {
-        ok: true,
-        token: context.token,
-        email
-      };
-    },
+    default: enhance.action(
+        async (event) => {
+            const name = event.context.form.string$('name');
+            return success({ name });
+        },
+        Form.schema(myValidator),
+    ),
+};
+```
+
+---
+
+## Core API
+
+Import from `@sourceregistry/sveltekit-enhance`.
+
+### `enhance.handle`
+
+Wraps SvelteKit's `handle` hook. Enhancers run left-to-right before the handler; their return values are merged into `context`.
+
+```ts
+import { enhance } from '@sourceregistry/sveltekit-enhance';
+
+// src/hooks.server.ts
+export const handle = enhance.handle(
+    async ({ event, resolve, context }) => resolve(event),
+    enhancerA,
+    enhancerB,
+);
+```
+
+### `enhance.load`
+
+Wraps server `load` functions.
+
+```ts
+// +page.server.ts
+export const load = enhance.load(
+    async (event) => ({ user: event.context.user }),
     Auth.Bearer,
-    FeatureFlag.all('PUBLIC_ACCOUNT_EDIT')
-  )
+);
+```
+
+### `enhance.action`
+
+Wraps form actions.
+
+```ts
+// +page.server.ts
+export const actions = {
+    submit: enhance.action(
+        async (event) => success(event.context),
+        Auth.Bearer,
+        Form.schema(myValidator),
+    ),
 };
 ```
 
-## Included helpers
+### `enhance.method`
 
-- `Auth.Bearer`  
-  Validates `Authorization: Bearer <token>` and returns `{ token }`.
+Wraps `+server.ts` endpoint handlers.
 
-- `FeatureFlag.all(...flags)` / `FeatureFlag.oneOf(...flags)`  
-  Enforces public environment-based feature flags.
+```ts
+// +server.ts
+export const GET = enhance.method(
+    async (event) => new Response(JSON.stringify(event.context)),
+    Auth.Bearer,
+);
+```
+
+### Utilities
+
+```ts
+import { fail, error, success, not_good } from '@sourceregistry/sveltekit-enhance';
+
+fail(400, { message: 'bad input' });   // throws ActionFailure — use inside actions
+error(404, { message: 'not found' });  // throws HttpError
+success({ id: 1 });                    // typed identity helper
+not_good(input, 403);                  // delegates to fail or error based on callType
+```
 
-- `RequestCorrelation.attach`  
-  Reuses incoming `x-correlation-id` / `x-request-id` or generates one, stores it in `locals`, and appends it to response headers.
+---
 
-- `Devtools.ignore`  
-  Ignores the Chrome DevTools app-specific probe route with a `204` response.
+## Helpers
 
-- `Form` utilities  
-  Typed helpers for strings, numbers, booleans, dates, files, arrays, JSON, selector helpers, and schema-style validation workflows.
+All helpers are available from `@sourceregistry/sveltekit-enhance` or `@sourceregistry/sveltekit-enhance/helpers`.
 
-## Example: handle hook with correlation ID
+---
+
+### `CSRF`
+
+Blocks cross-site form submissions on mutating methods (`POST`, `PUT`, `PATCH`, `DELETE`) with form content types. Checks the `Origin` header against the request origin. Absent `Origin` (server-side fetch, curl) is allowed through. Returns `403` — JSON body when `Accept: application/json`, SvelteKit `error()` otherwise.
 
 ```ts
-// src/hooks.server.ts
-import {enhance, RequestCorrelation} from '@sourceregistry/sveltekit-enhance';
+import { CSRF, CSRFChecker } from '@sourceregistry/sveltekit-enhance';
 
 export const handle = enhance.handle(
-  async ({event, resolve}) => resolve(event),
-  RequestCorrelation.attach
+    myHandler,
+    CSRF.inspect(
+        CSRFChecker.list('/api/webhooks/stripe'),  // bypass paths
+        myLogger,                                   // optional, defaults to console
+    ),
+);
+```
+
+Built-in bypass checkers:
+
+| Checker | Description |
+|---------|-------------|
+| `CSRFChecker.list(...paths)` | Exact pathname match |
+| `CSRFChecker.regex(...patterns)` | RegExp match against pathname |
+
+Custom checker — any `(input: EnhanceInput) => MaybePromise<boolean>`:
+```ts
+// true = bypass CSRF check
+CSRF.inspect((input) => input.url.pathname.startsWith('/api/public'))
+```
+
+Returns `{ csrf_valid: true }` on pass. Locals set: none.
+
+---
+
+### `Auth`
+
+Extracts and validates `Authorization: Bearer <token>` headers.
+
+```ts
+import { Auth } from '@sourceregistry/sveltekit-enhance';
+
+export const GET = enhance.method(
+    async (event) => new Response(event.context.token),
+    Auth.Bearer,
 );
 ```
 
-## API exports
+Returns `{ token: string }`. Throws `401` if the header is missing or malformed.
+
+---
+
+### `Devtools`
+
+Silences Chrome DevTools probe requests (`/.well-known/appspecific/com.chrome.devtools.json`) with a `204 No Content`. Logs in `dev` mode.
 
 ```ts
-import {
-  enhance,
-  action,
-  load,
-  method,
-  handle,
-  Auth,
-  FeatureFlag,
-  RequestCorrelation,
-  Devtools,
-  Form
-} from '@sourceregistry/sveltekit-enhance';
+import { Devtools } from '@sourceregistry/sveltekit-enhance';
+
+export const handle = enhance.handle(myHandler, Devtools.ignore);
 ```
 
-## Compatibility
+---
+
+### `FeatureFlag`
+
+Guards routes behind SvelteKit public env vars (`$env/dynamic/public`). Always passes in `dev` mode.
+
+```ts
+import { FeatureFlag } from '@sourceregistry/sveltekit-enhance';
+
+// All listed flags must be enabled
+FeatureFlag.all('PUBLIC_FEATURE_A', 'PUBLIC_FEATURE_B')
+
+// At least one flag must be enabled
+FeatureFlag.oneOf('PUBLIC_FEATURE_A', 'PUBLIC_FEATURE_B')
+```
+
+Truthy values: `true`, `TRUE`, `on`, `ON`, `1`. Returns `{ flags }` or throws `503 Feature not enabled`.
+
+---
+
+### `RequestCorrelation`
+
+Propagates a correlation ID across the request/response cycle.
+
+- Reads `x-correlation-id` or `x-request-id` from incoming headers
+- Validates: max 128 chars, pattern `[A-Za-z0-9._:-]+`
+- Generates a UUID v4 if absent
+- Echoes the ID back via `x-correlation-id` response header
+
+```ts
+import { RequestCorrelation } from '@sourceregistry/sveltekit-enhance';
+
+export const handle = enhance.handle(myHandler, RequestCorrelation.attach);
+```
+
+| Local | Type | Description |
+|-------|------|-------------|
+| `correlation_id` | `string` | Resolved correlation ID |
+| `request_started_at` | `number` | `Date.now()` at attach time |
+
+---
+
+### `RequestMonitor`
+
+Structured HTTP request logging and optional metrics collection. Instruments the full lifecycle: start, completion (log level by status), and unhandled errors — all with elapsed duration.
+
+```ts
+import { RequestMonitor } from '@sourceregistry/sveltekit-enhance';
+
+export const handle = enhance.handle(
+    myHandler,
+    RequestCorrelation.attach,
+    RequestMonitor.trace({
+        logger: myLogger,        // optional, defaults to console
+        record: metrics.record,  // optional
+    }),
+);
+```
+
+#### `TraceOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `logger` | `TraceLogger` | `console` | Must implement `debug`, `info`, `warn`, `error` |
+| `record` | `(entry: RecordTraceMetricEntry) => any` | — | Called after every request |
+
+#### Log events
+
+| Event | Level | Condition |
+|-------|-------|-----------|
+| `http.request.started` | `debug` | Before resolve |
+| `http.request.completed` | `info` | `status < 400` |
+| `http.request.completed` | `warn` | `status 4xx` |
+| `http.request.completed` | `error` | `status 5xx` |
+| `http.request.failed` | `error` | Unhandled throw |
+
+#### Types
+
+```ts
+type RecordTraceMetricEntry = { method: string; path: string; status: number; durationMs: number }
+type TraceLogger            = { debug(...args: any[]): any; info(...args: any[]): any; warn(...args: any[]): any; error(...args: any[]): any }
+```
+
+Locals set: `trace: { id: string; started_at: bigint }`.
+
+---
+
+### `Form`
+
+Typed, ergonomic FormData extraction. Works standalone or as an enhancer.
+
+#### As an enhancer — `Form.schema`
+
+Validates and deserializes form data via a `Validator<T>` before the handler runs.
+
+```ts
+import { Form, enhance, success } from '@sourceregistry/sveltekit-enhance';
+
+export const actions = {
+    default: enhance.action(
+        async (event) => success(event.context.form.result),
+        Form.schema(myValidator),
+    ),
+};
+```
+
+#### Standalone — `Form.handle`
+
+```ts
+import { Form } from '@sourceregistry/sveltekit-enhance';
+
+await Form.handle(request, ({ form }) => {
+    const name = form.string$('name');
+    const age  = form.number('age');
+    return { name, age };
+});
+```
+
+#### Field extractors
+
+Optional variants return `undefined` when the field is absent. Required variants (`$` suffix) throw `fail(400)`.
+
+| Method | Returns | Notes |
+|--------|---------|-------|
+| `string(name)` / `string$(name)` | `string \| null \| undefined` | |
+| `pattern$(name, pattern)` | `string` | `RegExp` or pattern string |
+| `number(name)` / `number$(name)` | `number \| undefined` | |
+| `boolean(name)` / `boolean$(name)` | `boolean \| undefined` | Accepts `true/false`, `1/0`, `on/off` |
+| `date(name, parser?)` / `date$(name, parser)` | `Date \| undefined` | Custom parser supported |
+| `json<T>(name, transformer?)` / `json$(name)` | `T \| undefined` | Optional transform fn |
+| `jsond(options)` | `any` | All FormData → nested object via dot-notation keys |
+| `file(name)` / `file$(name)` | `File \| null \| undefined` | |
+| `files(name)` | `File[]` | Non-empty, named files only |
+| `fileRecord(prefix, removePrefix?)` | `Record<string, File[]>` | Groups files by key prefix |
+| `array<T>(name, mapper?)` / `array$(name)` | `T[] \| undefined` | |
+| `enum(name, Enum)` / `enum$(name, Enum)` | `keyof E \| undefined` | |
+| `record(options?)` | `Record<string, any>` | All entries; optional `filter` / `transformer` |
+| `validate(schema, options?)` | `T` | Runs `Validator<T>`, throws `fail(400)` on failure |
+
+#### Conditional helpers
+
+```ts
+form.onlyIf(condition, trueVal, falseVal?)
+form.onlyIfPresent(key, (entry) => ..., fallback?)
+form.onlyIfArrayPresent(key, (entries) => ..., fallback)
+form.selector({ fieldName: (entry, key) => ..., $default?, $error? })
+form.selector$({ ... })    // throws fail(400) if no case matches
+form.basedOn(val, processor)
+form.process(name, parser, processor)
+```
+
+#### Standalone functions
+
+All `FormContext` methods are also exported as standalone functions taking `FormData` as the first argument, plus:
+
+```ts
+arrayString(formdata, name, delimiter, mapper?)
+hasOneOf(formdata, names)
+reviver(key, value)   // JSON.parse reviver — coerces strings to typed primitives
+```
+
+---
+
+## Type Reference
+
+```ts
+// Core
+EnhanceInput<CallType>     // event passed to all enhancers
+EnhanceFunction<CallType>  // (event: EnhanceInput) => MaybePromise<object | Response>
+EnhanceHandle              // final handle fn — ({ event, resolve, context }) => MaybePromise<Response>
+EnhanceLoad                // final load fn
+EnhanceAction              // final action fn
+EnhanceMethod              // final method fn
+MaybePromise<T>            // T | Promise<T>
+
+// Form
+Validator<T>               // (value: unknown, path?: ValidationPath) => ValidationResult<T>
+ValidationResult<T>        // { success: true; data: T } | { success: false; errors: ValidationIssue[] }
+ValidationIssue            // { path: string; message: string; code?: string }
+FormContext                // fluent API returned by Form.enhance / Form.handle
+InferValidator<V>          // infers T from Validator<T>
+
+// Helpers
+TraceLogger                // { debug, info, warn, error }
+TraceOptions               // { logger?: TraceLogger; record?: (entry) => any }
+RecordTraceMetricEntry     // { method: string; path: string; status: number; durationMs: number }
+RequestTraceLocals         // { trace?: { id: string; started_at: bigint } }
+RequestCorrelationLocals   // { correlation_id?: string; request_started_at?: number }
+CSRFChecker                // { regex(...patterns): checker; list(...paths): checker }
+```
 
-- SvelteKit 2+
-- Node.js runtime (matching your SvelteKit adapter/runtime support)
+---
 
 ## License
 
-Apache-2.0
+[Apache-2.0](./LICENSE) © [A.P.A. Slaa](https://github.com/SourceRegistry)

package/dist/helpers/CSRF.d.ts

@@ -0,0 +1,14 @@
+import { type EnhanceFunction, type EnhanceInput } from "../index.js";
+import type { MaybePromise } from "../index.js";
+import type { Logger } from "./logger.js";
+export declare const CSRF: {
+    inspect: (checker: (input: EnhanceInput) => MaybePromise<boolean>, logger?: Logger) => EnhanceFunction<"handle">;
+};
+export declare const CSRFChecker: {
+    regex: (...oneOf: RegExp[]) => (input: {
+        url: URL;
+    }) => boolean;
+    list: (...oneOf: string[]) => (input: {
+        url: URL;
+    }) => boolean;
+};

package/dist/helpers/CSRF.js

@@ -0,0 +1,38 @@
+import { json } from '@sveltejs/kit';
+import { error } from "../index.js";
+function isContentType(request, ...types) {
+    const type = request.headers.get('content-type')?.split(';', 1)[0].trim() ?? '';
+    return types.includes(type.toLowerCase());
+}
+function isFormContentType(request) {
+    return isContentType(request, 'application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain');
+}
+const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const SAFE_LOG_HEADERS = new Set(['content-type', 'origin', 'referer', 'user-agent', 'accept', 'host']);
+export const CSRF = {
+    inspect: (checker, logger = console) => async (input) => {
+        const { request, url } = input;
+        const origin = request.headers.get('origin');
+        const forbidden = isFormContentType(request) &&
+            MUTATING_METHODS.has(request.method) &&
+            origin !== null &&
+            origin !== url.origin &&
+            !(await checker(input));
+        if (forbidden) {
+            const message = `Cross-site ${request.method} form submissions are forbidden`;
+            logger.warn('CSRF Violation detected', {
+                url: url.toString(),
+                headers: Object.fromEntries([...request.headers.entries()].filter(([k]) => SAFE_LOG_HEADERS.has(k.toLowerCase())))
+            });
+            if (request.headers.get('accept') === 'application/json') {
+                return json({ message }, { status: 403 });
+            }
+            return error(403, { message });
+        }
+        return { csrf_valid: true };
+    }
+};
+export const CSRFChecker = {
+    regex: (...oneOf) => (input) => oneOf.some((exp) => exp[Symbol.match](input.url.pathname)),
+    list: (...oneOf) => (input) => oneOf.includes(input.url.pathname)
+};

package/dist/helpers/index.d.ts

@@ -3,3 +3,6 @@ export * from './devtools.js';
 export * from './featureflag.js';
 export * from './form.ts';
 export * from './request-correlation.ts';
+export * from './request-monitor.js';
+export * from './CSRF.js';
+export * from './logger.js';

package/dist/helpers/index.js

@@ -3,3 +3,6 @@ export * from './devtools.js';
 export * from './featureflag.js';
 export * from "./form.js";
 export * from "./request-correlation.js";
+export * from './request-monitor.js';
+export * from './CSRF.js';
+export * from './logger.js';

package/dist/helpers/logger.d.ts

@@ -0,0 +1,6 @@
+export type Logger = {
+    debug: (...args: any[]) => any;
+    info: (...args: any[]) => any;
+    warn: (...args: any[]) => any;
+    error: (...args: any[]) => any;
+};

package/dist/helpers/logger.js

@@ -0,0 +1 @@
+export {};

package/dist/helpers/request-monitor.d.ts

@@ -0,0 +1,21 @@
+import type { EnhanceFunction } from "../index.js";
+import type { Logger } from "./logger.js";
+export type RequestTraceLocals = {
+    trace?: {
+        id: string;
+        started_at: bigint;
+    };
+};
+export type RecordTraceMetricEntry = {
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+};
+export type TraceOptions = {
+    logger?: Logger;
+    record?: (entry: RecordTraceMetricEntry) => any;
+};
+export declare const RequestMonitor: {
+    trace: (options?: TraceOptions) => EnhanceFunction<"handle">;
+};

package/dist/helpers/request-monitor.js

@@ -0,0 +1,72 @@
+const durationMs = (startedAt) => Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+const resolveRoute = (event) => event.route.id ?? event.url.pathname;
+export const RequestMonitor = {
+    trace: (options = {}) => {
+        const { logger = console, record, } = options;
+        return async (event) => {
+            const locals = event.locals;
+            const requestId = locals.requestId ?? "unknown";
+            const route = resolveRoute(event);
+            locals.trace = {
+                id: requestId,
+                started_at: process.hrtime.bigint()
+            };
+            logger.debug("http.request.started", {
+                request_id: requestId,
+                method: event.request.method,
+                route,
+                client_ip: event?.getClientAddress?.()
+            });
+            try {
+                const response = await event.resolve(event.event);
+                if (!response)
+                    return response;
+                const elapsedMs = Number(durationMs(locals.trace.started_at).toFixed(2));
+                record?.({
+                    method: event.request.method,
+                    path: route,
+                    status: response.status,
+                    durationMs: elapsedMs,
+                });
+                const context = {
+                    request_id: requestId,
+                    method: event.request.method,
+                    route,
+                    status: response.status,
+                    duration_ms: elapsedMs,
+                    client_ip: event?.getClientAddress?.()
+                };
+                if (response.status >= 500) {
+                    logger.error("http.request.completed", context);
+                    return response;
+                }
+                if (response.status >= 400) {
+                    logger.warn("http.request.completed", context);
+                    return response;
+                }
+                logger.info("http.request.completed", context);
+                return response;
+            }
+            catch (error) {
+                const elapsedMs = Number(durationMs(locals.trace.started_at).toFixed(2));
+                record?.({
+                    method: event.request.method,
+                    path: route,
+                    status: 500,
+                    durationMs: elapsedMs,
+                });
+                logger.error("http.request.failed", {
+                    request_id: requestId,
+                    method: event.request.method,
+                    route,
+                    duration_ms: elapsedMs,
+                    client_ip: event?.getClientAddress?.(),
+                    error: error instanceof Error
+                        ? { name: error.name, message: error.message }
+                        : { value: String(error) }
+                });
+                throw error;
+            }
+        };
+    }
+};

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export type EnhanceInput<CallType extends EnhanceCallType = EnhanceCallType, Par
     request: Request;
     callType: CallType;
     fetch: typeof fetch;
+    getClientAddress?: () => string;
     get errorHandlers(): EnhanceErrorHandler[];
 } & (CallType extends 'handle' ? {
     get responseHandlers(): EnhanceResponseHandler[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sourceregistry/sveltekit-enhance",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Composable enhance and form utilities for SvelteKit actions, loads, methods, and hooks.",
   "author": "A.P.A. Slaa (a.p.a.slaa@projectsource.nl)",
   "scripts": {
@@ -31,6 +31,10 @@
       "types": "./dist/index.d.ts",
       "svelte": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./helpers": {
+      "types": "./dist/helpers/index.d.ts",
+      "default": "./dist/helpers/index.js"
     }
   },
   "repository": {