@ontrails/core 1.0.0-beta.0

package/src/job.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+
+import { progressFields } from './patterns/progress.js';
+import { statusFields } from './patterns/status.js';
+
+/**
+ * Proof: job-style output schema composes from existing pattern helpers.
+ * No dedicated `kind: "job"` needed — regular trails with status+progress output work.
+ */
+export const jobOutputSchema = z.object({
+  ...progressFields().shape,
+  ...statusFields().shape,
+  completedAt: z.string().optional(),
+  error: z.string().optional(),
+  jobId: z.string(),
+  result: z.unknown().optional(),
+  startedAt: z.string().optional(),
+});
+
+export type JobOutput = z.infer<typeof jobOutputSchema>;

package/src/layer.ts

@@ -0,0 +1,44 @@
+import type { Trail } from './trail.js';
+import type { Implementation } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Layer interface
+// ---------------------------------------------------------------------------
+
+/** A composable middleware that wraps trail implementations */
+export interface Layer {
+  readonly name: string;
+  readonly description?: string | undefined;
+
+  /** Wrap a trail's implementation, returning a new implementation */
+  wrap<I, O>(
+    trail: Trail<I, O>,
+    implementation: Implementation<I, O>
+  ): Implementation<I, O>;
+}
+
+// ---------------------------------------------------------------------------
+// Composition
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply layers outermost-first: layers[0] wraps layers[1] wraps ... wraps
+ * the base implementation.
+ *
+ * An empty layers array returns the implementation unchanged.
+ */
+export const composeLayers = <I, O>(
+  layers: readonly Layer[],
+  trail: Trail<I, O>,
+  implementation: Implementation<I, O>
+): Implementation<I, O> => {
+  // Fold right so layers[0] is the outermost wrapper
+  let result = implementation;
+  for (let i = layers.length - 1; i >= 0; i -= 1) {
+    const layer = layers[i];
+    if (layer) {
+      result = layer.wrap(trail, result);
+    }
+  }
+  return result;
+};

package/src/path-security.ts

@@ -0,0 +1,90 @@
+/**
+ * Path security utilities for preventing path traversal attacks.
+ *
+ * All functions are runtime-agnostic (Node / Bun compatible).
+ */
+
+import { resolve, relative, normalize, isAbsolute } from 'node:path';
+
+import { PermissionError } from './errors.js';
+import { Result } from './result.js';
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+/** Returns true when `target` is equal to or a descendant of `base`. */
+const isWithin = (base: string, target: string): boolean => {
+  const rel = relative(base, target);
+  // Empty string means they are the same directory.
+  // A relative path starting with ".." means it escapes.
+  // An absolute path means a completely different tree.
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolves `userPath` relative to `basePath` and ensures it stays within
+ * the base directory. Returns the resolved absolute path on success, or a
+ * `PermissionError` if the path escapes.
+ *
+ * Uses lexical path comparison (not `realpath`). Does not follow symlinks —
+ * if an attacker can create symlinks inside `basePath`, those could point
+ * outside the base. Use `realpath` before calling in symlink-sensitive environments.
+ */
+export const securePath = (
+  basePath: string,
+  userPath: string
+): Result<string, PermissionError> => {
+  const base = resolve(basePath);
+  const resolved = resolve(base, userPath);
+
+  if (!isWithin(base, resolved)) {
+    return Result.err(
+      new PermissionError(
+        `Path traversal detected: "${userPath}" escapes "${basePath}"`,
+        {
+          context: { basePath: base, resolved, userPath },
+        }
+      )
+    );
+  }
+
+  return Result.ok(resolved);
+};
+
+/**
+ * Returns `true` if `userPath` (resolved against `basePath`) stays within
+ * `basePath`.
+ */
+export const isPathSafe = (basePath: string, userPath: string): boolean => {
+  const base = resolve(basePath);
+  const resolved = resolve(base, userPath);
+  return isWithin(base, resolved);
+};
+
+/**
+ * Joins multiple path segments, resolves them against `basePath`, and
+ * validates the result stays within the base directory.
+ */
+export const resolveSafePath = (
+  basePath: string,
+  ...segments: string[]
+): Result<string, PermissionError> => {
+  const base = resolve(basePath);
+  const joined = resolve(base, ...segments.map((s) => normalize(s)));
+
+  if (!isWithin(base, joined)) {
+    return Result.err(
+      new PermissionError(
+        `Path traversal detected: segments escape "${basePath}"`,
+        { context: { basePath: base, resolved: joined, segments } }
+      )
+    );
+  }
+
+  return Result.ok(joined);
+};

package/src/patterns/bulk.ts

@@ -0,0 +1,16 @@
+/**
+ * Bulk operation schema helpers for @ontrails/core/patterns
+ */
+
+import { z } from 'zod';
+
+/** Bulk operation output wrapper for a given item schema. */
+export const bulkOutput = <T>(itemSchema: z.ZodType<T>) =>
+  z.object({
+    errors: z
+      .array(z.object({ index: z.number(), message: z.string() }))
+      .optional(),
+    failed: z.number(),
+    items: z.array(itemSchema),
+    succeeded: z.number(),
+  });

package/src/patterns/change.ts

@@ -0,0 +1,12 @@
+/**
+ * Change-tracking schema helpers for @ontrails/core/patterns
+ */
+
+import { z } from 'zod';
+
+/** Before/after change output for a given schema. */
+export const changeOutput = <T>(schema: z.ZodType<T>) =>
+  z.object({
+    after: schema,
+    before: schema.optional(),
+  });

package/src/patterns/date-range.ts

@@ -0,0 +1,12 @@
+/**
+ * Date-range schema helpers for @ontrails/core/patterns
+ */
+
+import { z } from 'zod';
+
+/** Optional since/until date-range fields. */
+export const dateRangeFields = () =>
+  z.object({
+    since: z.string().optional(),
+    until: z.string().optional(),
+  });

package/src/patterns/index.ts

@@ -0,0 +1,8 @@
+export { paginationFields, paginatedOutput } from './pagination.js';
+export { bulkOutput } from './bulk.js';
+export { timestampFields } from './timestamps.js';
+export { dateRangeFields } from './date-range.js';
+export { sortFields } from './sorting.js';
+export { statusFields } from './status.js';
+export { changeOutput } from './change.js';
+export { progressFields } from './progress.js';

package/src/patterns/pagination.ts

@@ -0,0 +1,22 @@
+/**
+ * Pagination schema helpers for @ontrails/core/patterns
+ */
+
+import { z } from 'zod';
+
+/** Common pagination input fields. */
+export const paginationFields = () =>
+  z.object({
+    cursor: z.string().optional(),
+    limit: z.number().optional().default(20),
+    offset: z.number().optional().default(0),
+  });
+
+/** Paginated output wrapper for a given item schema. */
+export const paginatedOutput = <T>(itemSchema: z.ZodType<T>) =>
+  z.object({
+    hasMore: z.boolean(),
+    items: z.array(itemSchema),
+    nextCursor: z.string().optional(),
+    total: z.number(),
+  });

package/src/patterns/progress.ts

@@ -0,0 +1,13 @@
+/**
+ * Progress schema helpers for @ontrails/core/patterns
+ */
+
+import { z } from 'zod';
+
+/** Progress tracking fields. */
+export const progressFields = () =>
+  z.object({
+    current: z.number(),
+    percentage: z.number().optional(),
+    total: z.number(),
+  });

package/src/patterns/sorting.ts

@@ -0,0 +1,14 @@
+/**
+ * Sorting schema helpers for @ontrails/core/patterns
+ */
+
+import { z } from 'zod';
+
+/** Sort fields constrained to a set of allowed column names. */
+export const sortFields = <const T extends string>(
+  allowedFields: [T, ...T[]]
+) =>
+  z.object({
+    sortBy: z.enum(allowedFields).optional(),
+    sortOrder: z.enum(['asc', 'desc']).optional().default('asc'),
+  });

package/src/patterns/status.ts

@@ -0,0 +1,11 @@
+/**
+ * Status schema helpers for @ontrails/core/patterns
+ */
+
+import { z } from 'zod';
+
+/** Standard workflow status field. */
+export const statusFields = () =>
+  z.object({
+    status: z.enum(['pending', 'running', 'completed', 'failed', 'cancelled']),
+  });

package/src/patterns/timestamps.ts

@@ -0,0 +1,12 @@
+/**
+ * Timestamp schema helpers for @ontrails/core/patterns
+ */
+
+import { z } from 'zod';
+
+/** Standard createdAt / updatedAt fields. */
+export const timestampFields = () =>
+  z.object({
+    createdAt: z.string(),
+    updatedAt: z.string(),
+  });

package/src/redaction/index.ts

@@ -0,0 +1,3 @@
+export { DEFAULT_PATTERNS, DEFAULT_SENSITIVE_KEYS } from './patterns.js';
+export { createRedactor } from './redactor.js';
+export type { Redactor, RedactorConfig } from './redactor.js';

package/src/redaction/patterns.ts

@@ -0,0 +1,47 @@
+/**
+ * Default redaction patterns and sensitive key lists.
+ *
+ * These are used by {@link createRedactor} to strip secrets from strings
+ * and object values before they reach logs, traces, or error payloads.
+ */
+
+// ---------------------------------------------------------------------------
+// Regex patterns that match sensitive values inside arbitrary strings
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_PATTERNS: RegExp[] = [
+  // Credit card numbers: 4 groups of 4 digits separated by spaces or dashes
+  /\b\d{4}[- ]\d{4}[- ]\d{4}[- ]\d{4}\b/g,
+
+  // SSN: XXX-XX-XXXX
+  /\b\d{3}-\d{2}-\d{4}\b/g,
+
+  // Bearer tokens
+  /Bearer\s+[A-Za-z0-9\-._~+/]+=*/g,
+
+  // Basic auth
+  /Basic\s+[A-Za-z0-9+/]+=*/g,
+
+  // API keys: sk-*, pk_*, sk_* prefixed tokens
+  /\b(?:sk-|pk_|sk_)[A-Za-z0-9_-]{8,}\b/g,
+
+  // JWT tokens: eyJ... (three base64url segments separated by dots)
+  /\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+];
+
+// ---------------------------------------------------------------------------
+// Object keys whose values should always be redacted
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_SENSITIVE_KEYS: string[] = [
+  'password',
+  'secret',
+  'token',
+  'apiKey',
+  'api_key',
+  'authorization',
+  'cookie',
+  'ssn',
+  'creditCard',
+  'credit_card',
+];

package/src/redaction/redactor.ts

@@ -0,0 +1,178 @@
+/**
+ * Redactor — strips sensitive data from strings and objects.
+ *
+ * @example
+ * ```ts
+ * const r = createRedactor();
+ * r.redact("token: Bearer abc123");         // "token: [REDACTED]"
+ * r.redactObject({ password: "s3cret" });   // { password: "[REDACTED]" }
+ * ```
+ */
+
+import { DEFAULT_PATTERNS, DEFAULT_SENSITIVE_KEYS } from './patterns.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface RedactorConfig {
+  readonly patterns?: RegExp[];
+  readonly sensitiveKeys?: string[];
+  readonly replacement?: string;
+}
+
+export interface Redactor {
+  /** Replace all pattern matches in a string with the replacement. */
+  redact(value: string): string;
+
+  /**
+   * Deep-clone `obj` and redact:
+   * 1. Values whose key matches a sensitive key (case-insensitive).
+   * 2. All remaining string values that match a pattern.
+   */
+  redactObject<T extends Record<string, unknown>>(obj: T): T;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const resetPatterns = (patterns: RegExp[]): void => {
+  for (const p of patterns) {
+    p.lastIndex = 0;
+  }
+};
+
+const applyPatterns = (
+  value: string,
+  patterns: RegExp[],
+  replacement: string
+): string => {
+  let result = value;
+  for (const pattern of patterns) {
+    // Reset in case the regex is stateful (global flag)
+    pattern.lastIndex = 0;
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+};
+
+const isSensitiveKey = (
+  key: string | undefined,
+  sensitiveKeysLower: ReadonlySet<string>
+): boolean => key !== undefined && sensitiveKeysLower.has(key.toLowerCase());
+
+type DeepRedact = (
+  value: unknown,
+  sensitiveKeysLower: ReadonlySet<string>,
+  patterns: RegExp[],
+  replacement: string,
+  currentKey?: string,
+  seen?: WeakSet<object>
+) => unknown;
+
+const mapObjectValues = (
+  value: object,
+  visit: (item: unknown, key: string) => unknown
+): Record<string, unknown> => {
+  const result: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value)) {
+    result[key] = visit(item, key);
+  }
+  return result;
+};
+
+/** Track and guard against circular references in object graphs. */
+const trackOrCircular = (
+  value: object,
+  seen: WeakSet<object>
+): '[Circular]' | null => {
+  if (seen.has(value)) {
+    return '[Circular]';
+  }
+  seen.add(value);
+  return null;
+};
+
+/* oxlint-disable no-use-before-define -- mutual recursion between redactCompound and deepRedact */
+
+/** Redact a compound value (array or object), delegating scalars back to deepRedact. */
+const redactCompound = (
+  value: unknown[] | object,
+  sensitiveKeysLower: ReadonlySet<string>,
+  patterns: RegExp[],
+  replacement: string,
+  seen: WeakSet<object>
+): unknown => {
+  const circular = trackOrCircular(value, seen);
+  if (circular) {
+    return circular;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) =>
+      deepRedact(
+        item,
+        sensitiveKeysLower,
+        patterns,
+        replacement,
+        undefined,
+        seen
+      )
+    );
+  }
+  return mapObjectValues(value, (item, key) =>
+    deepRedact(item, sensitiveKeysLower, patterns, replacement, key, seen)
+  );
+};
+
+const deepRedact: DeepRedact = (
+  value,
+  sensitiveKeysLower,
+  patterns,
+  replacement,
+  currentKey?,
+  seen = new WeakSet<object>()
+) => {
+  if (isSensitiveKey(currentKey, sensitiveKeysLower)) {
+    return replacement;
+  }
+  if (typeof value === 'string') {
+    return applyPatterns(value, patterns, replacement);
+  }
+  if (value !== null && typeof value === 'object') {
+    return redactCompound(
+      value,
+      sensitiveKeysLower,
+      patterns,
+      replacement,
+      seen
+    );
+  }
+  return value;
+};
+
+/* oxlint-enable no-use-before-define */
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export const createRedactor = (config?: RedactorConfig): Redactor => {
+  const patterns = config?.patterns ?? DEFAULT_PATTERNS;
+  const sensitiveKeys = config?.sensitiveKeys ?? DEFAULT_SENSITIVE_KEYS;
+  const replacement = config?.replacement ?? '[REDACTED]';
+
+  const sensitiveKeysLower = new Set(sensitiveKeys.map((k) => k.toLowerCase()));
+
+  return {
+    redact(value: string): string {
+      resetPatterns(patterns);
+      return applyPatterns(value, patterns, replacement);
+    },
+
+    redactObject<T extends Record<string, unknown>>(obj: T): T {
+      resetPatterns(patterns);
+      return deepRedact(obj, sensitiveKeysLower, patterns, replacement) as T;
+    },
+  };
+};