@ontrails/core 0.2.0

package/src/path-scope.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+
+import { matchesAnyGlob, matchesGlob } from './glob.js';
+
+declare const pathGlobBrand: unique symbol;
+
+export type PathGlob = string & {
+  readonly [pathGlobBrand]: 'PathGlob';
+};
+
+export const normalizePathScopePath = (value: string): string =>
+  value.replaceAll('\\', '/').replace(/^\.\//, '');
+
+export const matchesPathGlob = (path: string, pattern: string): boolean =>
+  matchesGlob(normalizePathScopePath(path), normalizePathScopePath(pattern), {
+    separator: '/',
+  });
+
+export const matchesAnyPathGlob = (
+  path: string,
+  patterns: readonly string[] | undefined
+): boolean =>
+  matchesAnyGlob(
+    normalizePathScopePath(path),
+    patterns?.map(normalizePathScopePath),
+    { separator: '/' }
+  );
+
+const pathGlobArraySchema = z.array(z.string()).readonly();
+
+export const pathScopeSchema = z
+  .object({
+    exclude: pathGlobArraySchema.optional(),
+    extensions: z.array(z.string()).readonly().optional(),
+    include: pathGlobArraySchema.optional(),
+  })
+  .strict();
+
+export type PathScope = z.output<typeof pathScopeSchema>;
+
+export type ScanTargets = Pick<PathScope, 'exclude' | 'extensions'>;
+
+const extensionOf = (path: string): string => {
+  const normalized = normalizePathScopePath(path);
+  const name = normalized.slice(normalized.lastIndexOf('/') + 1);
+  const dot = name.lastIndexOf('.');
+  return dot <= 0 ? '' : name.slice(dot);
+};
+
+const normalizeExtension = (extension: string): string =>
+  extension === '' || extension.startsWith('.') ? extension : `.${extension}`;
+
+const includedByExtension = (
+  path: string,
+  extensions: readonly string[] | undefined
+): boolean =>
+  extensions === undefined ||
+  extensions.length === 0 ||
+  extensions.map(normalizeExtension).includes(extensionOf(path));
+
+export const includedByPathScope = (path: string, scope?: PathScope): boolean =>
+  (scope?.include === undefined ||
+    scope.include.length === 0 ||
+    matchesAnyPathGlob(path, scope.include)) &&
+  !matchesAnyPathGlob(path, scope?.exclude) &&
+  includedByExtension(path, scope?.extensions);

package/src/path-security.ts

@@ -0,0 +1,98 @@
+/**
+ * Path security utilities for preventing path traversal attacks.
+ *
+ * All functions are runtime-agnostic (Node / Bun compatible).
+ */
+
+import { PermissionError } from './errors.js';
+import { Result } from './result.js';
+// Path security guards filesystem access on tooling paths: node:path
+// loads lazily at first use so the core barrel's module graph stays
+// execution-portable on runtimes without node: builtins (TRL-1198).
+import { loadRuntimeBuiltin } from './runtime-builtins.js';
+
+const nodePath = () => loadRuntimeBuiltin('node:path');
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+/** Returns true when `target` is equal to or a descendant of `base`. */
+const isWithin = (base: string, target: string): boolean => {
+  const { isAbsolute, relative } = nodePath();
+  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 { resolve } = nodePath();
+  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 { resolve } = nodePath();
+  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 deriveSafePath = (
+  basePath: string,
+  ...segments: string[]
+): Result<string, PermissionError> => {
+  const { normalize, resolve } = nodePath();
+  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/permits.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+/** Minimal permit shape available on TrailContext. */
+export interface BasePermit {
+  readonly id: string;
+  readonly scopes: readonly string[];
+}
+
+export const basePermitSchema: z.ZodType<BasePermit> = z.object({
+  id: z.string(),
+  scopes: z.array(z.string()).readonly(),
+});

package/src/queue.ts

@@ -0,0 +1,163 @@
+import type {
+  ActivationSource,
+  ActivationSourceMeta,
+  ActivationSourceParse,
+} from './activation-source.js';
+import { ValidationError } from './errors.js';
+
+export interface QueueSpec<TOutput = unknown> {
+  readonly meta?: ActivationSourceMeta | undefined;
+  readonly parse: ActivationSourceParse<TOutput>;
+  readonly payload?: ActivationSource['payload'] | undefined;
+  /**
+   * Runtime queue name. Defaults to the source id, so authored queue
+   * contracts can stay stable while host bindings choose their own names.
+   */
+  readonly queue?: string | undefined;
+  /** Reserved for future queue-specific design; trail versioning is trail-only. */
+  readonly version?: never;
+}
+
+export interface QueueSource<TOutput = unknown> extends ActivationSource {
+  readonly kind: 'queue';
+  readonly meta?: ActivationSourceMeta | undefined;
+  readonly parse: ActivationSourceParse<TOutput>;
+  readonly payload?: ActivationSource['payload'] | undefined;
+  readonly queue: string;
+}
+
+export interface QueueValidationIssue {
+  readonly field: 'parse' | 'queue';
+  readonly message: string;
+}
+
+const normalizeQueueName = (queueName: string): string => queueName.trim();
+
+const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isZodSchema = (value: unknown): boolean =>
+  isObjectRecord(value) && typeof value['safeParse'] === 'function';
+
+const validateQueueName = (queueName: unknown): QueueValidationIssue[] =>
+  typeof queueName === 'string' && queueName.trim().length > 0
+    ? []
+    : [
+        {
+          field: 'queue',
+          message: 'Queue source must define a non-empty queue name',
+        },
+      ];
+
+const validateRequiredParse = (parse: unknown): QueueValidationIssue[] =>
+  parse === undefined
+    ? [
+        {
+          field: 'parse',
+          message: 'Queue sources must define parse',
+        },
+      ]
+    : [];
+
+const validateParseShape = (parse: unknown): QueueValidationIssue[] => {
+  if (parse === undefined || isZodSchema(parse)) {
+    return [];
+  }
+  if (isObjectRecord(parse) && isZodSchema(parse['output'])) {
+    return [];
+  }
+  return [
+    {
+      field: 'parse',
+      message: 'Queue parse must be a Zod schema or define parse.output',
+    },
+  ];
+};
+
+const queueIssuesMessage = (
+  id: string,
+  issues: readonly QueueValidationIssue[]
+): string =>
+  `queue("${id}") is invalid: ${issues.map((issue) => `${issue.field}: ${issue.message}`).join('; ')}`;
+
+const assertQueueSpec = <TOutput>(
+  id: string,
+  spec: QueueSpec<TOutput>
+): {
+  readonly queue: string;
+} => {
+  const queueName = spec.queue === undefined ? id : spec.queue;
+  const issues = [
+    ...validateQueueName(queueName),
+    ...validateRequiredParse(spec.parse),
+    ...validateParseShape(spec.parse),
+  ];
+
+  if (issues.length > 0) {
+    throw new ValidationError(queueIssuesMessage(id, issues), {
+      context: { issues },
+    });
+  }
+
+  return { queue: normalizeQueueName(queueName) };
+};
+
+export const validateQueueSource = (
+  source: ActivationSource
+): readonly QueueValidationIssue[] => {
+  if (source.kind !== 'queue') {
+    return [];
+  }
+
+  return [
+    ...validateQueueName(source.queue),
+    ...validateRequiredParse(source.parse),
+    ...validateParseShape(source.parse),
+  ];
+};
+
+/**
+ * Define a queue activation source.
+ *
+ * Queue sources are inert contract data: they describe which runtime queue
+ * wakes a trail and how the message body becomes trail input. A host adapter
+ * such as `@ontrails/cloudflare/workers` owns delivery.
+ *
+ * @example
+ * ```ts
+ * import { queue } from '@ontrails/core';
+ * import { z } from 'zod';
+ *
+ * const source = queue('queue.email.outbox', {
+ *   queue: 'email-outbox',
+ *   parse: z.object({ messageId: z.string() }),
+ * });
+ * ```
+ */
+export function queue<TOutput>(
+  id: string,
+  spec: QueueSpec<TOutput>
+): QueueSource<TOutput>;
+export function queue<TOutput>(
+  spec: QueueSpec<TOutput> & { readonly id: string }
+): QueueSource<TOutput>;
+export function queue<TOutput>(
+  idOrSpec: string | (QueueSpec<TOutput> & { readonly id: string }),
+  maybeSpec?: QueueSpec<TOutput>
+): QueueSource<TOutput> {
+  const id = typeof idOrSpec === 'string' ? idOrSpec : idOrSpec.id;
+  // oxlint-disable-next-line no-non-null-assertion -- overload guarantees maybeSpec when idOrSpec is string
+  const spec = typeof idOrSpec === 'string' ? maybeSpec! : idOrSpec;
+  const normalized = assertQueueSpec(id, spec);
+
+  return Object.freeze({
+    id,
+    kind: 'queue' as const,
+    parse: spec.parse,
+    queue: normalized.queue,
+    ...(spec.meta === undefined
+      ? {}
+      : { meta: Object.freeze({ ...spec.meta }) }),
+    ...(spec.payload === undefined ? {} : { payload: spec.payload }),
+  });
+}

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,50 @@
+/**
+ * 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. Keep the threshold above short prose like "Bearer token".
+  /Bearer\s+[A-Za-z0-9\-._~+/=]{6,}/g,
+
+  // Basic auth
+  /Basic\s+[A-Za-z0-9+/=]{8,}/g,
+
+  // Common key/value secrets embedded in strings
+  /\b(?:password|secret|token|api[_-]?key|cookie)\s*[:=]\s*[^\s,;]+/gi,
+
+  // 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',
+];