@ontrails/core 1.0.0-beta.4 → 1.0.0-beta.41

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

@@ -4,10 +4,14 @@
  * 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';
+// 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
@@ -15,6 +19,7 @@ import { Result } from './result.js';
 
 /** 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.
@@ -39,6 +44,7 @@ export const securePath = (
   basePath: string,
   userPath: string
 ): Result<string, PermissionError> => {
+  const { resolve } = nodePath();
   const base = resolve(basePath);
   const resolved = resolve(base, userPath);
 
@@ -61,6 +67,7 @@ export const securePath = (
  * `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);
@@ -70,10 +77,11 @@ export const isPathSafe = (basePath: string, userPath: string): boolean => {
  * Joins multiple path segments, resolves them against `basePath`, and
  * validates the result stays within the base directory.
  */
-export const resolveSafePath = (
+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)));
 

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/patterns.ts

@@ -16,11 +16,14 @@ export const DEFAULT_PATTERNS: RegExp[] = [
   // SSN: XXX-XX-XXXX
   /\b\d{3}-\d{2}-\d{4}\b/g,
 
-  // Bearer tokens
-  /Bearer\s+[A-Za-z0-9\-._~+/]+=*/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+/]+=*/g,
+  /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,

package/src/resilience.ts

@@ -61,11 +61,11 @@ const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
 export const shouldRetry = (error: Error): boolean => isRetryable(error);
 
 // ---------------------------------------------------------------------------
-// getBackoffDelay
+// deriveBackoffDelay
 // ---------------------------------------------------------------------------
 
 /** Compute exponential backoff delay with full jitter. */
-export const getBackoffDelay = (
+export const deriveBackoffDelay = (
   attempt: number,
   options?: Pick<RetryOptions, 'baseDelay' | 'maxDelay' | 'backoffFactor'>
 ): number => {
@@ -108,7 +108,7 @@ const tryAttempt = async <T>(
   if (isLast || !retryPredicate(result.error)) {
     return { done: true, result };
   }
-  const delay = getBackoffDelay(attempt, options);
+  const delay = deriveBackoffDelay(attempt, options);
   if (delay > 0) {
     await sleep(delay, options?.signal);
   }
@@ -203,10 +203,9 @@ export const withTimeout = <T>(
       );
     }, ms);
 
-    // oxlint-disable-next-line prefer-await-to-then, no-void -- .then() needed inside Promise constructor; void discards unhandled rejection
-    void fn().then(
-      // oxlint-disable-next-line prefer-await-to-callbacks -- callback required inside .then()
-      (result) => {
+    const run = async () => {
+      try {
+        const result = await fn();
         if (settled) {
           return;
         }
@@ -215,9 +214,7 @@ export const withTimeout = <T>(
         signal?.removeEventListener('abort', onAbort);
         // oxlint-disable-next-line promise/no-multiple-resolved -- settled guard ensures single resolution
         resolve(result);
-      },
-      // oxlint-disable-next-line prefer-await-to-callbacks -- rejection handler required inside .then()
-      (error: unknown) => {
+      } catch (error: unknown) {
         if (settled) {
           return;
         }
@@ -229,6 +226,9 @@ export const withTimeout = <T>(
           Result.err(error instanceof Error ? error : new Error(String(error)))
         );
       }
-    );
+    };
+
+    // oxlint-disable-next-line no-void -- fire-and-settle inside Promise constructor
+    void run();
   });
 };