@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/dist/runtime/request-hooks.js

@@ -0,0 +1,102 @@
+export function resolveRequestHooks(options) {
+    const definitions = new Map();
+    for (const definition of options.manifestDefinitions ?? []) {
+        if (!definition?.id) {
+            continue;
+        }
+        definitions.set(definition.id, definition);
+    }
+    const registrations = new Map();
+    for (const registration of options.registrations ?? []) {
+        if (!registration?.id || typeof registration.handler !== 'function') {
+            continue;
+        }
+        registrations.set(registration.id, registration.handler);
+    }
+    const hooks = [];
+    const warnings = [];
+    const seen = new Set();
+    for (const reference of options.routeReferences ?? []) {
+        const hookId = reference?.id?.trim();
+        if (!hookId || seen.has(hookId)) {
+            continue;
+        }
+        seen.add(hookId);
+        const definition = definitions.get(hookId);
+        if (!definition?.phase) {
+            warnings.push(`Route "${options.routeName}" references request hook "${hookId}" without manifest metadata.`);
+            continue;
+        }
+        const handler = registrations.get(hookId);
+        if (!handler) {
+            warnings.push(`Route "${options.routeName}" references request hook "${hookId}" without an implementation.`);
+            continue;
+        }
+        hooks.push({
+            id: hookId,
+            phase: definition.phase,
+            order: Number.isInteger(definition.order) ? Number(definition.order) : 0,
+            handler,
+        });
+    }
+    hooks.sort((left, right) => {
+        const phaseDelta = compareRequestHookPhase(left.phase, right.phase);
+        if (phaseDelta !== 0) {
+            return phaseDelta;
+        }
+        if (left.order !== right.order) {
+            return left.order - right.order;
+        }
+        return left.id.localeCompare(right.id);
+    });
+    return { hooks, warnings };
+}
+export async function executeRequestHookPhase(options) {
+    let currentResult = options.result;
+    for (const hook of options.hooks) {
+        if (hook.phase !== options.phase) {
+            continue;
+        }
+        try {
+            const hookResult = await hook.handler(options.context, {
+                phase: options.phase,
+                route: options.route,
+                result: currentResult,
+            });
+            if (options.phase === 'afterHandler') {
+                if (hookResult !== undefined) {
+                    currentResult = hookResult;
+                }
+                continue;
+            }
+            if (hookResult !== undefined) {
+                options.logger?.info?.('request hook produced early response', {
+                    hookId: hook.id,
+                    phase: hook.phase,
+                });
+                return { result: hookResult, shortCircuited: true };
+            }
+        }
+        catch (error) {
+            options.logger?.error?.('request hook failed', {
+                err: error,
+                hookId: hook.id,
+                phase: hook.phase,
+            });
+            throw error;
+        }
+    }
+    return { result: currentResult, shortCircuited: false };
+}
+function compareRequestHookPhase(left, right) {
+    return requestHookPhaseWeight(left) - requestHookPhaseWeight(right);
+}
+function requestHookPhaseWeight(phase) {
+    if (phase === 'beforeAuth') {
+        return 0;
+    }
+    if (phase === 'beforeHandler') {
+        return 1;
+    }
+    return 2;
+}

package/dist/runtime/session-metadata.d.ts

@@ -0,0 +1,13 @@
+export interface SessionMetadata {
+    id: string;
+    createdAt: string;
+    expiresAt: string;
+}
+export interface SessionMetadataInput {
+    id?: string;
+    createdAt?: string;
+    expiresAt?: string;
+}
+export declare function attachSessionMetadata<TSession extends Record<string, unknown>>(session: TSession, metadata: SessionMetadata | undefined): TSession;
+export declare function readSessionMetadata(session: Record<string, unknown> | null | undefined): SessionMetadataInput | undefined;
+export declare function stripSessionMetadataFields(session: Record<string, unknown>): void;

package/dist/runtime/session-metadata.js

@@ -0,0 +1,98 @@
+const SESSION_METADATA_KEY = Symbol.for('webstir.webstir-backend.session-metadata');
+const SESSION_METADATA_FIELDS = ['id', 'createdAt', 'expiresAt'];
+export function attachSessionMetadata(session, metadata) {
+    const normalized = cloneSessionMetadata(metadata);
+    if (!normalized) {
+        return session;
+    }
+    Object.defineProperty(session, SESSION_METADATA_KEY, {
+        configurable: true,
+        enumerable: false,
+        value: normalized,
+        writable: true,
+    });
+    for (const field of SESSION_METADATA_FIELDS) {
+        Object.defineProperty(session, field, {
+            configurable: true,
+            enumerable: false,
+            value: normalized[field],
+            writable: true,
+        });
+    }
+    return session;
+}
+export function readSessionMetadata(session) {
+    if (!session || !isRecord(session)) {
+        return undefined;
+    }
+    const attached = readAttachedSessionMetadata(session);
+    const metadata = cloneSessionMetadataInput({
+        id: normalizeText(session.id) ?? attached?.id,
+        createdAt: normalizeDate(session.createdAt) ?? attached?.createdAt,
+        expiresAt: normalizeDate(session.expiresAt) ?? attached?.expiresAt,
+    });
+    return metadata && Object.keys(metadata).length > 0 ? metadata : undefined;
+}
+export function stripSessionMetadataFields(session) {
+    for (const field of SESSION_METADATA_FIELDS) {
+        Reflect.deleteProperty(session, field);
+    }
+}
+function readAttachedSessionMetadata(session) {
+    const attached = session[SESSION_METADATA_KEY];
+    return cloneSessionMetadata(attached);
+}
+function cloneSessionMetadata(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const metadata = cloneSessionMetadataInput(value);
+    const id = metadata?.id;
+    const createdAt = metadata?.createdAt;
+    const expiresAt = metadata?.expiresAt;
+    if (!id || !createdAt || !expiresAt) {
+        return undefined;
+    }
+    return {
+        id,
+        createdAt,
+        expiresAt,
+    };
+}
+function cloneSessionMetadataInput(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const metadata = {};
+    const id = normalizeText(value.id);
+    const createdAt = normalizeDate(value.createdAt);
+    const expiresAt = normalizeDate(value.expiresAt);
+    if (id) {
+        metadata.id = id;
+    }
+    if (createdAt) {
+        metadata.createdAt = createdAt;
+    }
+    if (expiresAt) {
+        metadata.expiresAt = expiresAt;
+    }
+    return metadata;
+}
+function normalizeText(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+function normalizeDate(value) {
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        return value.toISOString();
+    }
+    if (typeof value === 'string') {
+        const timestamp = Date.parse(value);
+        if (!Number.isNaN(timestamp)) {
+            return new Date(timestamp).toISOString();
+        }
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}

package/dist/runtime/session-runtime.d.ts

@@ -0,0 +1,28 @@
+export type SessionRuntimeFormIssueCode = 'validation' | 'auth' | 'csrf';
+export type SessionRuntimeFormValue = string | string[];
+export type SessionRuntimeFormValues = Record<string, SessionRuntimeFormValue>;
+export interface SessionRuntimeFormIssue {
+    code?: SessionRuntimeFormIssueCode;
+    field?: string;
+    message: string;
+}
+export interface SessionRuntimeStoredFormState {
+    values: SessionRuntimeFormValues;
+    issues: SessionRuntimeFormIssue[];
+    createdAt: string;
+}
+export interface SessionRuntimeFormState {
+    csrf: Record<string, string>;
+    states: Record<string, SessionRuntimeStoredFormState>;
+}
+export interface SessionRuntimeState {
+    form?: SessionRuntimeFormState;
+}
+export declare function attachSessionRuntimeState<TSession extends Record<string, unknown>>(session: TSession, runtime: SessionRuntimeState | undefined): TSession;
+export declare function cloneSessionRuntimeState(runtime: SessionRuntimeState | undefined): SessionRuntimeState | undefined;
+export declare function coerceSessionRuntimeFormState(value: unknown): SessionRuntimeFormState | undefined;
+export declare function getFormSessionRuntimeState(session: Record<string, unknown>): SessionRuntimeFormState;
+export declare function hasSessionRuntimeState(runtime: SessionRuntimeState | undefined): boolean;
+export declare function mergeSessionRuntimeState(left: SessionRuntimeState | undefined, right: SessionRuntimeState | undefined): SessionRuntimeState | undefined;
+export declare function pruneSessionRuntimeState(session: Record<string, unknown>): void;
+export declare function readSessionRuntimeState(session: Record<string, unknown> | null | undefined): SessionRuntimeState | undefined;

package/dist/runtime/session-runtime.js

@@ -0,0 +1,180 @@
+const SESSION_RUNTIME_KEY = Symbol.for('webstir.webstir-backend.session-runtime');
+const EPOCH_ISO = '1970-01-01T00:00:00.000Z';
+export function attachSessionRuntimeState(session, runtime) {
+    const normalized = cloneSessionRuntimeState(runtime);
+    if (!hasSessionRuntimeState(normalized)) {
+        Reflect.deleteProperty(session, SESSION_RUNTIME_KEY);
+        return session;
+    }
+    Object.defineProperty(session, SESSION_RUNTIME_KEY, {
+        configurable: true,
+        enumerable: false,
+        value: normalized,
+        writable: true,
+    });
+    return session;
+}
+export function cloneSessionRuntimeState(runtime) {
+    if (!runtime || !isRecord(runtime)) {
+        return undefined;
+    }
+    const form = cloneSessionRuntimeFormState(runtime.form);
+    if (!form) {
+        return undefined;
+    }
+    return { form };
+}
+export function coerceSessionRuntimeFormState(value) {
+    return cloneSessionRuntimeFormState(value);
+}
+export function getFormSessionRuntimeState(session) {
+    const existing = readAttachedSessionRuntimeState(session);
+    if (existing?.form) {
+        existing.form.csrf ??= {};
+        existing.form.states ??= {};
+        return existing.form;
+    }
+    const created = {
+        csrf: {},
+        states: {},
+    };
+    const runtime = {
+        ...(existing ?? {}),
+        form: created,
+    };
+    Object.defineProperty(session, SESSION_RUNTIME_KEY, {
+        configurable: true,
+        enumerable: false,
+        value: runtime,
+        writable: true,
+    });
+    return created;
+}
+export function hasSessionRuntimeState(runtime) {
+    if (!runtime?.form) {
+        return false;
+    }
+    return (Object.keys(runtime.form.csrf ?? {}).length > 0 ||
+        Object.keys(runtime.form.states ?? {}).length > 0);
+}
+export function mergeSessionRuntimeState(left, right) {
+    const leftClone = cloneSessionRuntimeState(left);
+    const rightClone = cloneSessionRuntimeState(right);
+    if (!leftClone) {
+        return rightClone;
+    }
+    if (!rightClone) {
+        return leftClone;
+    }
+    return {
+        form: leftClone.form || rightClone.form
+            ? {
+                csrf: {
+                    ...(leftClone.form?.csrf ?? {}),
+                    ...(rightClone.form?.csrf ?? {}),
+                },
+                states: {
+                    ...(leftClone.form?.states ?? {}),
+                    ...(rightClone.form?.states ?? {}),
+                },
+            }
+            : undefined,
+    };
+}
+export function pruneSessionRuntimeState(session) {
+    const runtime = readAttachedSessionRuntimeState(session);
+    if (!runtime) {
+        return;
+    }
+    if (runtime.form &&
+        Object.keys(runtime.form.csrf ?? {}).length === 0 &&
+        Object.keys(runtime.form.states ?? {}).length === 0) {
+        delete runtime.form;
+    }
+    if (!hasSessionRuntimeState(runtime)) {
+        Reflect.deleteProperty(session, SESSION_RUNTIME_KEY);
+    }
+}
+export function readSessionRuntimeState(session) {
+    if (!session || !isRecord(session)) {
+        return undefined;
+    }
+    return cloneSessionRuntimeState(readAttachedSessionRuntimeState(session));
+}
+function readAttachedSessionRuntimeState(session) {
+    const runtime = session[SESSION_RUNTIME_KEY];
+    return isRecord(runtime) ? runtime : undefined;
+}
+function cloneSessionRuntimeFormState(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    return {
+        csrf: cloneSessionRuntimeCsrfState(value.csrf),
+        states: cloneSessionRuntimeStoredStateMap(value.states),
+    };
+}
+function cloneSessionRuntimeCsrfState(value) {
+    if (!isRecord(value)) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(value).flatMap(([key, candidate]) => typeof candidate === 'string' ? [[key, candidate]] : []));
+}
+function cloneSessionRuntimeStoredStateMap(value) {
+    if (!isRecord(value)) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(value).flatMap(([key, candidate]) => {
+        const state = cloneSessionRuntimeStoredFormState(candidate);
+        return state ? [[key, state]] : [];
+    }));
+}
+function cloneSessionRuntimeStoredFormState(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    return {
+        values: cloneSessionRuntimeFormValues(value.values),
+        issues: cloneSessionRuntimeIssues(value.issues),
+        createdAt: typeof value.createdAt === 'string' ? value.createdAt : EPOCH_ISO,
+    };
+}
+function cloneSessionRuntimeFormValues(value) {
+    if (!isRecord(value)) {
+        return {};
+    }
+    const values = {};
+    for (const [key, candidate] of Object.entries(value)) {
+        if (typeof candidate === 'string') {
+            values[key] = candidate;
+            continue;
+        }
+        if (Array.isArray(candidate) && candidate.every((item) => typeof item === 'string')) {
+            values[key] = [...candidate];
+        }
+    }
+    return values;
+}
+function cloneSessionRuntimeIssues(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.flatMap((candidate) => {
+        if (!isRecord(candidate) || typeof candidate.message !== 'string') {
+            return [];
+        }
+        return [
+            {
+                code: normalizeIssueCode(candidate.code),
+                field: typeof candidate.field === 'string' ? candidate.field : undefined,
+                message: candidate.message,
+            },
+        ];
+    });
+}
+function normalizeIssueCode(value) {
+    return value === 'validation' || value === 'auth' || value === 'csrf' ? value : undefined;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}

package/dist/runtime/session.d.ts

@@ -0,0 +1,83 @@
+import { type SessionRuntimeState } from './session-runtime.js';
+export type FlashLevel = 'info' | 'success' | 'warning' | 'error';
+export type FlashPublishCondition = 'always' | 'success' | 'error';
+export interface SessionCookieConfig {
+    secret: string;
+    cookieName: string;
+    secure: boolean;
+    maxAgeSeconds: number;
+    path?: string;
+    sameSite?: 'Lax' | 'Strict' | 'None';
+}
+export interface SessionFlashMessage {
+    key: string;
+    level: FlashLevel;
+    createdAt: string;
+}
+export interface RouteSessionDefinitionLike {
+    mode?: 'optional' | 'required';
+    write?: boolean;
+}
+export interface RouteFlashMessageDefinitionLike {
+    key?: string;
+    level?: FlashLevel;
+    when?: FlashPublishCondition;
+}
+export interface RouteFlashDefinitionLike {
+    consume?: readonly string[];
+    publish?: readonly RouteFlashMessageDefinitionLike[];
+}
+export interface RouteFormDefinitionLike {
+    session?: RouteSessionDefinitionLike;
+    flash?: RouteFlashDefinitionLike;
+}
+export interface SessionAwareRouteDefinitionLike {
+    session?: RouteSessionDefinitionLike;
+    flash?: RouteFlashDefinitionLike;
+    form?: RouteFormDefinitionLike;
+}
+export interface SessionCommitResult<TSession> {
+    session: TSession | null;
+    setCookie?: string;
+}
+export interface PreparedSessionState<TSession, TResult> {
+    session: TSession | null;
+    flash: SessionFlashMessage[];
+    commit(options: {
+        session: TSession | null;
+        route?: SessionAwareRouteDefinitionLike;
+        result?: TResult;
+    }): SessionCommitResult<TSession>;
+}
+export interface SessionStoreRuntimeState extends SessionRuntimeState {
+    flash?: SessionFlashMessage[];
+}
+export interface SessionStoreRecord<TSession extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    value: TSession;
+    flash?: SessionFlashMessage[];
+    runtime?: SessionStoreRuntimeState;
+    createdAt: string;
+    expiresAt: string;
+}
+export interface SessionStore<TSession extends Record<string, unknown> = Record<string, unknown>> {
+    get(sessionId: string): SessionStoreRecord<TSession> | undefined;
+    set(record: SessionStoreRecord<TSession>): void;
+    delete(sessionId: string): void;
+}
+export interface InMemorySessionStore<TSession extends Record<string, unknown> = Record<string, unknown>> extends SessionStore<TSession> {
+    clear(): void;
+}
+export declare function prepareSessionState<TSession extends Record<string, unknown>, TResult extends {
+    status?: number;
+    errors?: unknown;
+}>(options: {
+    cookies?: Record<string, string> | string | string[];
+    route?: SessionAwareRouteDefinitionLike;
+    config: SessionCookieConfig;
+    store?: SessionStore<TSession>;
+    now?: () => Date;
+}): PreparedSessionState<TSession, TResult>;
+export declare function parseCookieHeader(header: string | string[] | undefined): Record<string, string>;
+export declare function createInMemorySessionStore<TSession extends Record<string, unknown> = Record<string, unknown>>(): InMemorySessionStore<TSession>;
+export declare function resetInMemorySessionStore(store?: InMemorySessionStore<Record<string, unknown>>): void;