@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/src/runtime/forms.ts

@@ -0,0 +1,364 @@
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+
+import {
+  getFormSessionRuntimeState,
+  pruneSessionRuntimeState,
+  type SessionRuntimeFormState,
+} from './session-runtime.js';
+
+export type FormIssueCode = 'validation' | 'auth' | 'csrf';
+export type FormValue = string | string[];
+export type FormValues = Record<string, FormValue>;
+
+export interface FormIssue {
+  code?: FormIssueCode;
+  field?: string;
+  message: string;
+}
+
+export interface FormRouteDefinitionLike {
+  path?: string;
+  form?: {
+    csrf?: boolean;
+  };
+}
+
+export interface PreparedFormState<TSession extends Record<string, unknown>> {
+  session: TSession;
+  csrfToken?: string;
+  values: FormValues;
+  issues: FormIssue[];
+}
+
+type FormRuntimeStore = SessionRuntimeFormState;
+
+interface RouteHandlerResultLike {
+  status?: number;
+  headers?: Record<string, string>;
+  body?: unknown;
+  redirect?: {
+    location: string;
+  };
+  errors?: { code: string; message: string; details?: unknown }[];
+}
+
+export type FormSubmissionResult<TSession extends Record<string, unknown>, TAuth> =
+  | {
+      ok: true;
+      session: TSession;
+      values: FormValues;
+      auth: TAuth | undefined;
+    }
+  | {
+      ok: false;
+      session: TSession;
+      values: FormValues;
+      issues: FormIssue[];
+      result: RouteHandlerResultLike;
+    };
+
+const DEFAULT_CSRF_FIELD_NAME = '_csrf';
+
+export function prepareFormState<TSession extends Record<string, unknown>>(options: {
+  session: TSession | null;
+  formId: string;
+  route?: FormRouteDefinitionLike;
+  csrf?: boolean;
+  now?: () => Date;
+}): PreparedFormState<TSession> {
+  const session = ensureSession(options.session);
+  const store = getFormRuntimeStore(session);
+  const stored = store.states[options.formId];
+  if (stored) {
+    delete store.states[options.formId];
+  }
+
+  let csrfToken: string | undefined;
+  if (isCsrfEnabled(options)) {
+    csrfToken = ensureCsrfToken(store, options.formId);
+  }
+
+  cleanupFormRuntimeStore(session);
+  return {
+    session,
+    csrfToken,
+    values: cloneFormValues(stored?.values),
+    issues: cloneIssues(stored?.issues),
+  };
+}
+
+export function processFormSubmission<TSession extends Record<string, unknown>, TAuth>(options: {
+  session: TSession | null;
+  body: unknown;
+  auth?: TAuth;
+  formId: string;
+  route?: FormRouteDefinitionLike;
+  csrf?: boolean;
+  csrfFieldName?: string;
+  redirectTo?: string;
+  requireAuth?:
+    | boolean
+    | {
+        redirectTo?: string;
+        message?: string;
+      };
+  validate?: (values: FormValues) => readonly FormIssue[] | FormIssue[] | undefined;
+  now?: () => Date;
+}): FormSubmissionResult<TSession, TAuth> {
+  const now = options.now ?? (() => new Date());
+  const session = ensureSession(options.session);
+  const store = getFormRuntimeStore(session);
+  const csrfFieldName = options.csrfFieldName ?? DEFAULT_CSRF_FIELD_NAME;
+  const values = normalizeFormValues(options.body, csrfFieldName);
+  const redirectTo = options.redirectTo;
+
+  if (isCsrfEnabled(options)) {
+    const expectedToken = ensureCsrfToken(store, options.formId);
+    const providedToken = readCsrfToken(options.body, csrfFieldName);
+    if (!providedToken || !tokensMatch(providedToken, expectedToken)) {
+      return failSubmission({
+        session,
+        store,
+        formId: options.formId,
+        values,
+        redirectTo,
+        now,
+        issues: [
+          {
+            code: 'csrf',
+            message: 'Form session expired. Reload the page and try again.',
+          },
+        ],
+      });
+    }
+    delete store.csrf[options.formId];
+  }
+
+  if (requiresAuth(options.requireAuth) && options.auth === undefined) {
+    return failSubmission({
+      session,
+      store,
+      formId: options.formId,
+      values,
+      redirectTo: resolveAuthRedirect(options.requireAuth, redirectTo),
+      now,
+      issues: [
+        {
+          code: 'auth',
+          message:
+            typeof options.requireAuth === 'object' && options.requireAuth.message
+              ? options.requireAuth.message
+              : 'Sign-in required to submit this form.',
+        },
+      ],
+    });
+  }
+
+  const validationResult = options.validate?.(values);
+  const validationIssues = cloneIssues(
+    Array.isArray(validationResult) ? validationResult : undefined,
+  );
+  if (validationIssues.length > 0) {
+    return failSubmission({
+      session,
+      store,
+      formId: options.formId,
+      values,
+      redirectTo,
+      now,
+      issues: validationIssues.map((issue) => ({
+        ...issue,
+        code: issue.code ?? 'validation',
+      })),
+    });
+  }
+
+  delete store.states[options.formId];
+  cleanupFormRuntimeStore(session);
+  return {
+    ok: true,
+    session,
+    values,
+    auth: options.auth,
+  };
+}
+
+export function groupFormIssuesByField(issues: readonly FormIssue[] | undefined): {
+  form: string[];
+  fields: Record<string, string[]>;
+} {
+  const grouped = {
+    form: [] as string[],
+    fields: {} as Record<string, string[]>,
+  };
+  for (const issue of issues ?? []) {
+    if (!issue?.message) {
+      continue;
+    }
+    if (!issue.field) {
+      grouped.form.push(issue.message);
+      continue;
+    }
+    grouped.fields[issue.field] ??= [];
+    grouped.fields[issue.field].push(issue.message);
+  }
+  return grouped;
+}
+
+function failSubmission<TSession extends Record<string, unknown>>(options: {
+  session: TSession;
+  store: FormRuntimeStore;
+  formId: string;
+  values: FormValues;
+  redirectTo?: string;
+  issues: FormIssue[];
+  now: () => Date;
+}): FormSubmissionResult<TSession, never> {
+  options.store.states[options.formId] = {
+    values: cloneFormValues(options.values),
+    issues: cloneIssues(options.issues),
+    createdAt: options.now().toISOString(),
+  };
+  cleanupFormRuntimeStore(options.session);
+
+  if (options.redirectTo) {
+    return {
+      ok: false,
+      session: options.session,
+      values: options.values,
+      issues: options.issues,
+      result: {
+        status: 303,
+        redirect: {
+          location: options.redirectTo,
+        },
+      },
+    };
+  }
+
+  const status = options.issues.some((issue) => issue.code === 'auth')
+    ? 401
+    : options.issues.some((issue) => issue.code === 'csrf')
+      ? 403
+      : 422;
+
+  return {
+    ok: false,
+    session: options.session,
+    values: options.values,
+    issues: options.issues,
+    result: {
+      status,
+      errors: options.issues.map((issue) => ({
+        code: issue.code === 'auth' ? 'auth' : 'validation',
+        message: issue.message,
+        details: issue.field
+          ? { field: issue.field, reason: issue.code ?? 'validation' }
+          : { reason: issue.code ?? 'validation' },
+      })),
+    },
+  };
+}
+
+function ensureSession<TSession extends Record<string, unknown>>(
+  session: TSession | null,
+): TSession {
+  if (session && typeof session === 'object' && !Array.isArray(session)) {
+    return session;
+  }
+  return {} as TSession;
+}
+
+function getFormRuntimeStore(session: Record<string, unknown>): FormRuntimeStore {
+  return getFormSessionRuntimeState(session);
+}
+
+function cleanupFormRuntimeStore(session: Record<string, unknown>): void {
+  pruneSessionRuntimeState(session);
+}
+
+function ensureCsrfToken(store: FormRuntimeStore, formId: string): string {
+  const existing = store.csrf[formId];
+  if (existing) {
+    return existing;
+  }
+  const generated = randomUUID();
+  store.csrf[formId] = generated;
+  return generated;
+}
+
+function readCsrfToken(body: unknown, fieldName: string): string | undefined {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return undefined;
+  }
+  const value = (body as Record<string, unknown>)[fieldName];
+  if (typeof value === 'string' && value.length > 0) {
+    return value;
+  }
+  if (Array.isArray(value) && typeof value[0] === 'string' && value[0].length > 0) {
+    return value[0];
+  }
+  return undefined;
+}
+
+function normalizeFormValues(body: unknown, csrfFieldName: string): FormValues {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return {};
+  }
+  const values: FormValues = {};
+  for (const [key, raw] of Object.entries(body as Record<string, unknown>)) {
+    if (key === csrfFieldName) {
+      continue;
+    }
+    if (typeof raw === 'string') {
+      values[key] = raw;
+      continue;
+    }
+    if (Array.isArray(raw) && raw.every((value) => typeof value === 'string')) {
+      values[key] = [...raw];
+    }
+  }
+  return values;
+}
+
+function cloneFormValues(values: FormValues | undefined): FormValues {
+  if (!values) {
+    return {};
+  }
+  return Object.fromEntries(
+    Object.entries(values).map(([key, value]) => [key, Array.isArray(value) ? [...value] : value]),
+  );
+}
+
+function cloneIssues(issues: readonly FormIssue[] | undefined): FormIssue[] {
+  return (issues ?? []).map((issue) => ({ ...issue }));
+}
+
+function tokensMatch(left: string, right: string): boolean {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  if (leftBuffer.length !== rightBuffer.length) {
+    return false;
+  }
+  return timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+function isCsrfEnabled(options: { route?: FormRouteDefinitionLike; csrf?: boolean }): boolean {
+  return options.csrf ?? options.route?.form?.csrf ?? false;
+}
+
+function requiresAuth(
+  option: { redirectTo?: string; message?: string } | boolean | undefined,
+): boolean {
+  return option === true || typeof option === 'object';
+}
+
+function resolveAuthRedirect(
+  option: { redirectTo?: string; message?: string } | boolean | undefined,
+  fallback: string | undefined,
+): string | undefined {
+  if (typeof option === 'object' && option.redirectTo) {
+    return option.redirectTo;
+  }
+  return fallback;
+}

package/src/runtime/request-hooks.ts

@@ -0,0 +1,165 @@
+export type RequestHookPhase = 'beforeAuth' | 'beforeHandler' | 'afterHandler';
+
+export interface RequestHookDefinitionLike {
+  id?: string;
+  phase?: RequestHookPhase;
+  order?: number;
+}
+
+export interface RequestHookReferenceLike {
+  id?: string;
+}
+
+export type RequestHookHandler<TContext, TResult, TRoute> = (
+  context: TContext,
+  input: { phase: RequestHookPhase; route: TRoute; result?: TResult },
+) => Promise<TResult | undefined> | TResult | undefined;
+
+export interface RegisteredRequestHook<TContext, TResult, TRoute> {
+  id?: string;
+  handler?: RequestHookHandler<TContext, TResult, TRoute>;
+}
+
+export interface CompiledRequestHook<TContext, TResult, TRoute> {
+  id: string;
+  phase: RequestHookPhase;
+  order: number;
+  handler: RequestHookHandler<TContext, TResult, TRoute>;
+}
+
+export function resolveRequestHooks<TContext, TResult, TRoute>(options: {
+  routeName: string;
+  routeReferences?: readonly RequestHookReferenceLike[];
+  manifestDefinitions?: readonly RequestHookDefinitionLike[];
+  registrations?: readonly RegisteredRequestHook<TContext, TResult, TRoute>[];
+}): { hooks: CompiledRequestHook<TContext, TResult, TRoute>[]; warnings: string[] } {
+  const definitions = new Map<string, RequestHookDefinitionLike>();
+  for (const definition of options.manifestDefinitions ?? []) {
+    if (!definition?.id) {
+      continue;
+    }
+    definitions.set(definition.id, definition);
+  }
+
+  const registrations = new Map<string, RequestHookHandler<TContext, TResult, TRoute>>();
+  for (const registration of options.registrations ?? []) {
+    if (!registration?.id || typeof registration.handler !== 'function') {
+      continue;
+    }
+    registrations.set(registration.id, registration.handler);
+  }
+
+  const hooks: CompiledRequestHook<TContext, TResult, TRoute>[] = [];
+  const warnings: string[] = [];
+  const seen = new Set<string>();
+
+  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<TContext, TResult, TRoute>(options: {
+  hooks: readonly CompiledRequestHook<TContext, TResult, TRoute>[];
+  phase: RequestHookPhase;
+  context: TContext;
+  route: TRoute;
+  logger?: {
+    info?(message: string, metadata?: Record<string, unknown>): void;
+    error?(message: string, metadata?: Record<string, unknown>): void;
+  };
+  result?: TResult;
+}): Promise<{ result?: TResult; shortCircuited: boolean }> {
+  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: RequestHookPhase, right: RequestHookPhase): number {
+  return requestHookPhaseWeight(left) - requestHookPhaseWeight(right);
+}
+
+function requestHookPhaseWeight(phase: RequestHookPhase): number {
+  if (phase === 'beforeAuth') {
+    return 0;
+  }
+  if (phase === 'beforeHandler') {
+    return 1;
+  }
+  return 2;
+}

package/src/runtime/session-metadata.ts

@@ -0,0 +1,135 @@
+export interface SessionMetadata {
+  id: string;
+  createdAt: string;
+  expiresAt: string;
+}
+
+export interface SessionMetadataInput {
+  id?: string;
+  createdAt?: string;
+  expiresAt?: string;
+}
+
+const SESSION_METADATA_KEY = Symbol.for('webstir.webstir-backend.session-metadata');
+const SESSION_METADATA_FIELDS = ['id', 'createdAt', 'expiresAt'] as const;
+
+export function attachSessionMetadata<TSession extends Record<string, unknown>>(
+  session: TSession,
+  metadata: SessionMetadata | undefined,
+): TSession {
+  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: Record<string, unknown> | null | undefined,
+): SessionMetadataInput | undefined {
+  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: Record<string, unknown>): void {
+  for (const field of SESSION_METADATA_FIELDS) {
+    Reflect.deleteProperty(session, field);
+  }
+}
+
+function readAttachedSessionMetadata(
+  session: Record<string, unknown>,
+): SessionMetadata | undefined {
+  const attached = (session as Record<PropertyKey, unknown>)[SESSION_METADATA_KEY];
+  return cloneSessionMetadata(attached);
+}
+
+function cloneSessionMetadata(value: unknown): SessionMetadata | undefined {
+  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: unknown): SessionMetadataInput | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const metadata: SessionMetadataInput = {};
+  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: unknown): string | undefined {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function normalizeDate(value: unknown): string | undefined {
+  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: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}