@ontrails/core 1.0.0-beta.32 → 1.0.0-beta.39

package/src/webhook.ts

@@ -4,7 +4,9 @@ import type {
   ActivationSourceParse,
 } from './activation-source.js';
 import { InternalError, ValidationError } from './errors.js';
+import type { AnyResource } from './resource.js';
 import { Result } from './result.js';
+import type { TrailContext } from './types.js';
 
 export const webhookMethods = Object.freeze([
   'DELETE',
@@ -28,16 +30,46 @@ export interface WebhookVerifyRequest {
   readonly path: string;
 }
 
+/**
+ * Verification callback for inbound webhook requests.
+ *
+ * When the source declares `resources`, surfaces call `verify` with a
+ * resource-capable context so signature checks can reach declared
+ * resources (e.g. a store holding per-endpoint secrets). Verifiers that
+ * only need the request may ignore the second parameter.
+ */
 export type WebhookVerify = (
-  request: WebhookVerifyRequest
+  request: WebhookVerifyRequest,
+  ctx?: TrailContext
 ) => Promise<Result<void, Error>> | Result<void, Error>;
 
 export interface WebhookSpec<TOutput = unknown> {
+  /**
+   * Allowlist of header names delivered to the consumer trail. When set,
+   * the webhook envelope includes a `headers` map with the matching
+   * headers, lowercased. Headers outside the allowlist never reach the
+   * trail boundary.
+   */
+  readonly headers?: readonly string[] | undefined;
   readonly meta?: ActivationSourceMeta | undefined;
   readonly method?: WebhookMethodInput | undefined;
   readonly parse: ActivationSourceParse<TOutput>;
+  /**
+   * Absolute path, optionally with dynamic segments (`/hooks/:endpoint`).
+   * Segment values are delivered as fields of the webhook envelope under
+   * their segment names.
+   */
   readonly path: string;
   readonly payload?: ActivationSource['payload'] | undefined;
+  /**
+   * Deliver the raw request body text to the consumer trail as a
+   * `rawBody` envelope field. With `rawBody`, a non-JSON body no longer
+   * fails at the surface — the trail owns payload interpretation (e.g.
+   * HMAC verification over exact bytes).
+   */
+  readonly rawBody?: boolean | undefined;
+  /** Resources the `verify` callback may access through its context. */
+  readonly resources?: readonly AnyResource[] | undefined;
   readonly verify?: WebhookVerify | undefined;
   /** Reserved for future webhook-specific design; trail versioning is trail-only. */
   readonly version?: never;
@@ -45,11 +77,16 @@ export interface WebhookSpec<TOutput = unknown> {
 
 export interface WebhookSource<TOutput = unknown> extends ActivationSource {
   readonly kind: 'webhook';
+  readonly headers?: readonly string[] | undefined;
   readonly meta?: ActivationSourceMeta | undefined;
   readonly method: WebhookMethod;
   readonly parse: ActivationSourceParse<TOutput>;
   readonly path: string;
+  /** Dynamic segment names parsed from `path`, in order. Empty for static paths. */
+  readonly pathParams: readonly string[];
   readonly payload?: ActivationSource['payload'] | undefined;
+  readonly rawBody?: boolean | undefined;
+  readonly resources?: readonly AnyResource[] | undefined;
   readonly verify?: WebhookVerify | undefined;
 }
 
@@ -66,6 +103,111 @@ const normalizeMethod = (
 
 const normalizePath = (path: string): string => path.trim();
 
+const WEBHOOK_PATH_PARAM_PATTERN = /^:[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Envelope field names a path segment must not shadow. */
+const RESERVED_ENVELOPE_FIELDS = new Set(['body', 'headers', 'rawBody']);
+
+const pathSegments = (path: string): readonly string[] =>
+  normalizePath(path).split('/').slice(1);
+
+const isParamSegment = (segment: string): boolean => segment.startsWith(':');
+
+/** Decode a path segment, keeping the raw text when the encoding is malformed. */
+const decodeSegment = (segment: string): string => {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+};
+
+/**
+ * Parse the dynamic segment names out of a webhook path pattern.
+ *
+ * @example
+ * ```ts
+ * parseWebhookPathParams('/hooks/:endpoint'); // ['endpoint']
+ * parseWebhookPathParams('/webhooks/payment'); // []
+ * ```
+ */
+export const parseWebhookPathParams = (path: string): readonly string[] =>
+  pathSegments(path)
+    .filter((segment) => isParamSegment(segment))
+    .map((segment) => segment.slice(1));
+
+/**
+ * Match a concrete request path against a webhook path pattern.
+ *
+ * Returns the captured segment values keyed by segment name, or
+ * `undefined` when the path does not match. Static patterns match only
+ * themselves and capture nothing.
+ *
+ * @example
+ * ```ts
+ * matchWebhookPath('/hooks/:endpoint', '/hooks/github');
+ * // { endpoint: 'github' }
+ * ```
+ */
+export const matchWebhookPath = (
+  pattern: string,
+  path: string
+): Readonly<Record<string, string>> | undefined => {
+  const patternSegments = pathSegments(pattern);
+  const actualSegments = path.split('/').slice(1);
+  if (patternSegments.length !== actualSegments.length) {
+    return undefined;
+  }
+
+  const params: Record<string, string> = {};
+  for (const [index, patternSegment] of patternSegments.entries()) {
+    const actual = actualSegments[index] ?? '';
+    if (isParamSegment(patternSegment)) {
+      if (actual.length === 0) {
+        return undefined;
+      }
+      params[patternSegment.slice(1)] = decodeSegment(actual);
+      continue;
+    }
+    if (patternSegment !== actual) {
+      return undefined;
+    }
+  }
+  return params;
+};
+
+/**
+ * True when two webhook path patterns can both match one concrete path.
+ *
+ * Segment-wise: two literals overlap only when equal; a dynamic segment
+ * overlaps anything. Used by governance to extend route-collision
+ * detection past exact-path equality.
+ *
+ * @example
+ * ```ts
+ * webhookPathPatternsOverlap('/hooks/:a', '/hooks/github'); // true
+ * webhookPathPatternsOverlap('/hooks/:a', '/api/:b'); // false
+ * ```
+ */
+export const webhookPathPatternsOverlap = (
+  left: string,
+  right: string
+): boolean => {
+  const leftSegments = pathSegments(left);
+  const rightSegments = pathSegments(right);
+  if (leftSegments.length !== rightSegments.length) {
+    return false;
+  }
+  return leftSegments.every((leftSegment, index) => {
+    const rightSegment = rightSegments[index] ?? '';
+    return (
+      isParamSegment(leftSegment) ||
+      isParamSegment(rightSegment) ||
+      leftSegment === rightSegment
+    );
+  });
+};
+
 const isWebhookMethod = (method: string): method is WebhookMethod =>
   (webhookMethods as readonly string[]).includes(method);
 
@@ -100,14 +242,42 @@ const validatePath = (path: unknown): WebhookValidationIssue[] => {
   }
 
   const normalized = normalizePath(path);
-  return normalized.startsWith('/')
-    ? []
-    : [
-        {
-          field: 'path',
-          message: 'Webhook path must start with "/"',
-        },
-      ];
+  if (!normalized.startsWith('/')) {
+    return [
+      {
+        field: 'path',
+        message: 'Webhook path must start with "/"',
+      },
+    ];
+  }
+
+  const issues: WebhookValidationIssue[] = [];
+  for (const segment of pathSegments(normalized)) {
+    if (isParamSegment(segment) && !WEBHOOK_PATH_PARAM_PATTERN.test(segment)) {
+      issues.push({
+        field: 'path',
+        message: `Webhook path segment "${segment}" must match :name with a letter or underscore first`,
+      });
+    }
+  }
+
+  const params = parseWebhookPathParams(normalized);
+  if (new Set(params).size !== params.length) {
+    issues.push({
+      field: 'path',
+      message: 'Webhook path segments must use unique names',
+    });
+  }
+  for (const param of params) {
+    if (RESERVED_ENVELOPE_FIELDS.has(param)) {
+      issues.push({
+        field: 'path',
+        message: `Webhook path segment ":${param}" collides with the reserved envelope field "${param}"`,
+      });
+    }
+  }
+
+  return issues;
 };
 
 const validateRequiredParse = (parse: unknown): WebhookValidationIssue[] =>
@@ -229,14 +399,15 @@ export const getWebhookHeader = (
 
 export const verifyWebhookRequest = async (
   source: Pick<WebhookSource, 'id' | 'verify'>,
-  request: WebhookVerifyRequest
+  request: WebhookVerifyRequest,
+  ctx?: TrailContext
 ): Promise<Result<void, Error>> => {
   if (source.verify === undefined) {
     return Result.ok();
   }
 
   try {
-    return await source.verify(request);
+    return await source.verify(request, ctx);
   } catch (error) {
     const cause = errorFromUnknown(error);
     return Result.err(
@@ -269,10 +440,22 @@ export function webhook<TOutput>(
     method: normalized.method,
     parse: spec.parse,
     path: normalized.path,
+    pathParams: Object.freeze([...parseWebhookPathParams(normalized.path)]),
+    ...(spec.headers === undefined
+      ? {}
+      : {
+          headers: Object.freeze(
+            spec.headers.map((name) => name.toLowerCase())
+          ),
+        }),
     ...(spec.meta === undefined
       ? {}
       : { meta: Object.freeze({ ...spec.meta }) }),
     ...(spec.payload === undefined ? {} : { payload: spec.payload }),
+    ...(spec.rawBody === undefined ? {} : { rawBody: spec.rawBody }),
+    ...(spec.resources === undefined
+      ? {}
+      : { resources: Object.freeze([...spec.resources]) }),
     ...(spec.verify === undefined ? {} : { verify: spec.verify }),
   });
 }

package/src/workspace.ts

@@ -5,11 +5,15 @@
  * helpers for working with paths relative to a workspace.
  */
 
-import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
-import { resolve, relative, dirname, join, isAbsolute } from 'node:path';
-
 import { NotFoundError } from './errors.js';
 import { Result } from './result.js';
+// Workspace discovery is a tooling path: the node builtins load 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 fs = () => loadRuntimeBuiltin('node:fs');
+const nodePath = () => loadRuntimeBuiltin('node:path');
 
 export interface WorkspaceRootManifest {
   readonly workspaces?: unknown;
@@ -31,33 +35,24 @@ const normalizePath = (path: string): string => path.replaceAll('\\', '/');
 
 const normalizeRealPath = (path: string): string => {
   try {
-    return normalizePath(realpathSync(path));
+    return normalizePath(fs().realpathSync(path));
   } catch {
-    return normalizePath(resolve(path));
+    return normalizePath(nodePath().resolve(path));
   }
 };
 
 const readJsonSync = <T>(path: string): T | undefined => {
   try {
-    return JSON.parse(readFileSync(path, 'utf8')) as T;
+    return JSON.parse(fs().readFileSync(path, 'utf8')) as T;
   } catch {
     return undefined;
   }
 };
 
 /** Check if a directory has a package.json with a `workspaces` field. */
-const hasWorkspacesField = async (dir: string): Promise<boolean> => {
-  const pkgPath = join(dir, 'package.json');
-  const file = Bun.file(pkgPath);
-  if (!(await file.exists())) {
-    return false;
-  }
-  try {
-    const pkg: unknown = await file.json();
-    return typeof pkg === 'object' && pkg !== null && 'workspaces' in pkg;
-  } catch {
-    return false;
-  }
+const hasWorkspacesField = (dir: string): boolean => {
+  const pkg = readJsonSync<unknown>(nodePath().join(dir, 'package.json'));
+  return typeof pkg === 'object' && pkg !== null && 'workspaces' in pkg;
 };
 
 /**
@@ -93,19 +88,24 @@ const workspaceDirsForPattern = (
   pattern: string
 ): readonly string[] => {
   if (!pattern.endsWith('/*')) {
-    const workspaceDir = join(rootDir, pattern);
-    return existsSync(join(workspaceDir, 'package.json')) ? [workspaceDir] : [];
+    const workspaceDir = nodePath().join(rootDir, pattern);
+    return fs().existsSync(nodePath().join(workspaceDir, 'package.json'))
+      ? [workspaceDir]
+      : [];
   }
 
-  const groupDir = join(rootDir, pattern.slice(0, -2));
-  if (!existsSync(groupDir)) {
+  const groupDir = nodePath().join(rootDir, pattern.slice(0, -2));
+  if (!fs().existsSync(groupDir)) {
     return [];
   }
 
-  return readdirSync(groupDir, { withFileTypes: true })
+  return fs()
+    .readdirSync(groupDir, { withFileTypes: true })
     .filter((entry) => entry.isDirectory())
-    .map((entry) => join(groupDir, entry.name))
-    .filter((workspaceDir) => existsSync(join(workspaceDir, 'package.json')))
+    .map((entry) => nodePath().join(groupDir, entry.name))
+    .filter((workspaceDir) =>
+      fs().existsSync(nodePath().join(workspaceDir, 'package.json'))
+    )
     .toSorted();
 };
 
@@ -140,7 +140,7 @@ export const listWorkspacePackages = <
 ): readonly WorkspacePackage<Manifest>[] => {
   const normalizedRoot = normalizeRealPath(rootDir);
   const rootManifest = readJsonSync<WorkspaceRootManifest>(
-    join(normalizedRoot, 'package.json')
+    nodePath().join(normalizedRoot, 'package.json')
   );
   const packages: WorkspacePackage<Manifest>[] = [];
 
@@ -148,18 +148,20 @@ export const listWorkspacePackages = <
     normalizedRoot,
     listWorkspacePatterns(rootManifest)
   )) {
-    const packageJsonPath = join(workspaceDir, 'package.json');
+    const packageJsonPath = nodePath().join(workspaceDir, 'package.json');
     const manifest = readJsonSync<Manifest>(packageJsonPath);
     if (!manifest || typeof manifest.name !== 'string') {
       continue;
     }
 
-    const packageRoot = normalizeRealPath(dirname(packageJsonPath));
+    const packageRoot = normalizeRealPath(nodePath().dirname(packageJsonPath));
     packages.push({
       manifest,
       packageJsonPath: normalizeRealPath(packageJsonPath),
       packageRoot,
-      workspacePath: normalizePath(relative(normalizedRoot, packageRoot)),
+      workspacePath: normalizePath(
+        nodePath().relative(normalizedRoot, packageRoot)
+      ),
     });
   }
 
@@ -196,15 +198,15 @@ export const findWorkspacePackage = <
 export const findWorkspaceRoot = async (
   startDir?: string
 ): Promise<Result<string, NotFoundError>> => {
-  let current = resolve(startDir ?? process.cwd());
+  let current = nodePath().resolve(startDir ?? process.cwd());
 
   // eslint-disable-next-line no-constant-condition
   while (true) {
-    if (await hasWorkspacesField(current)) {
+    if (hasWorkspacesField(current)) {
       return Result.ok(current);
     }
 
-    const parent = dirname(current);
+    const parent = nodePath().dirname(current);
 
     if (parent === current) {
       return Result.err(
@@ -225,6 +227,7 @@ export const isInsideWorkspace = (
   filePath: string,
   workspaceRoot: string
 ): boolean => {
+  const { isAbsolute, relative, resolve } = nodePath();
   const rel = relative(resolve(workspaceRoot), resolve(filePath));
   return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
 };
@@ -235,4 +238,7 @@ export const isInsideWorkspace = (
 export const deriveRelativePath = (
   filePath: string,
   workspaceRoot: string
-): string => relative(resolve(workspaceRoot), resolve(filePath));
+): string => {
+  const { relative, resolve } = nodePath();
+  return relative(resolve(workspaceRoot), resolve(filePath));
+};