@beignet/core 0.0.14 → 0.0.15

package/dist/webhooks/index.js

@@ -0,0 +1,313 @@
+/**
+ * @beignet/core/webhooks
+ *
+ * Provider-neutral inbound webhook primitives for Beignet applications.
+ */
+/**
+ * Error thrown for invalid webhook definitions and inputs.
+ */
+export class WebhookOptionsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WebhookOptionsError";
+    }
+}
+/**
+ * Error thrown when verification fails.
+ */
+export class WebhookVerificationError extends Error {
+    webhookName;
+    provider;
+    code;
+    cause;
+    constructor(args) {
+        super(args.message);
+        this.name = "WebhookVerificationError";
+        this.webhookName = args.webhookName;
+        this.provider = args.provider;
+        this.code = args.code;
+        this.cause = args.cause;
+    }
+}
+/**
+ * Error thrown when a verified event fails payload validation.
+ */
+export class WebhookValidationError extends Error {
+    webhookName;
+    eventType;
+    issues;
+    constructor(args) {
+        super(`Webhook "${args.webhookName}" event "${args.eventType}" payload validation failed: ${formatIssues(args.issues)}`);
+        this.name = "WebhookValidationError";
+        this.webhookName = args.webhookName;
+        this.eventType = args.eventType;
+        this.issues = args.issues;
+    }
+}
+/**
+ * Define a typed inbound webhook surface.
+ */
+export function defineWebhook(name, options = {}) {
+    if (!name)
+        throw new WebhookOptionsError("Webhook name is required.");
+    return {
+        name,
+        provider: options.provider,
+        events: (options.events ?? {}),
+        verifier: options.verifier,
+        metadata: options.metadata,
+    };
+}
+/**
+ * Verify a raw webhook request and validate the matching event payload schema.
+ */
+export async function verifyWebhook(webhook, input, options = {}) {
+    validateWebhook(webhook);
+    const verifier = options.verifier ?? webhook.verifier;
+    if (!verifier) {
+        throw new WebhookOptionsError(`Webhook "${webhook.name}" does not have a verifier.`);
+    }
+    let event;
+    try {
+        event = await verifier.verify(input);
+    }
+    catch (error) {
+        if (error instanceof WebhookVerificationError)
+            throw error;
+        throw new WebhookVerificationError({
+            message: `Webhook "${webhook.name}" verification failed.`,
+            webhookName: webhook.name,
+            provider: webhook.provider,
+            code: "verification_failed",
+            cause: error,
+        });
+    }
+    return parseWebhookEvent(webhook, event, options);
+}
+/**
+ * Validate a verified webhook event against its catalog entry.
+ */
+export async function parseWebhookEvent(webhook, event, options = {}) {
+    validateWebhook(webhook);
+    validateEvent(webhook, event);
+    const schema = webhook.events[event.type];
+    if (!schema) {
+        if (options.allowUnknownEvents ?? true)
+            return event;
+        throw new WebhookVerificationError({
+            message: `Webhook "${webhook.name}" received unknown event type "${event.type}".`,
+            webhookName: webhook.name,
+            provider: webhook.provider,
+            code: "unknown_event_type",
+        });
+    }
+    const result = await schema["~standard"].validate(event.payload);
+    if (result.issues?.length) {
+        throw new WebhookValidationError({
+            webhookName: webhook.name,
+            eventType: event.type,
+            issues: result.issues,
+        });
+    }
+    if (!("value" in result)) {
+        throw new Error("Invalid Standard Schema result: missing value");
+    }
+    return {
+        ...event,
+        payload: result.value,
+    };
+}
+/**
+ * Create an in-memory verifier for tests.
+ */
+export function createMemoryWebhookVerifier(options = {}) {
+    const queuedEvents = [...(options.events ?? [])];
+    const verifiedEvents = [];
+    return {
+        get verifiedEvents() {
+            return verifiedEvents;
+        },
+        async verify() {
+            const event = queuedEvents.shift();
+            if (!event) {
+                throw new WebhookVerificationError({
+                    message: "No memory webhook event is queued.",
+                    code: "missing_memory_event",
+                });
+            }
+            verifiedEvents.push(event);
+            return event;
+        },
+        queue(event) {
+            queuedEvents.push(event);
+        },
+        reset() {
+            queuedEvents.length = 0;
+            verifiedEvents.length = 0;
+        },
+    };
+}
+/**
+ * Create a generic JSON + HMAC verifier.
+ */
+export function createHmacWebhookVerifier(options) {
+    if (!options.secret) {
+        throw new WebhookOptionsError("Webhook HMAC secret is required.");
+    }
+    const signatureHeader = normalizeHeaderName(options.signatureHeader ?? "x-webhook-signature");
+    const algorithm = options.algorithm ?? "SHA-256";
+    const eventIdPath = options.eventIdPath ?? "id";
+    const eventTypePath = options.eventTypePath ?? "type";
+    return {
+        async verify(input) {
+            const signature = input.signature ?? input.headers?.[signatureHeader];
+            if (!signature) {
+                throw new WebhookVerificationError({
+                    message: `Missing ${signatureHeader} header.`,
+                    provider: options.provider,
+                    code: "missing_signature",
+                });
+            }
+            const expected = await hmacHex(algorithm, options.secret, input.rawBody);
+            const actual = normalizeSignature(signature, options.signaturePrefix);
+            if (!(await timingSafeStringEqual(actual, expected))) {
+                throw new WebhookVerificationError({
+                    message: "Webhook signature is invalid.",
+                    provider: options.provider,
+                    code: "invalid_signature",
+                });
+            }
+            const payload = parseJsonBody(input.rawBody);
+            const id = readStringPath(payload, eventIdPath);
+            const type = readStringPath(payload, eventTypePath);
+            if (!id) {
+                throw new WebhookVerificationError({
+                    message: `Webhook payload is missing string event ID at "${eventIdPath}".`,
+                    provider: options.provider,
+                    code: "missing_event_id",
+                });
+            }
+            if (!type) {
+                throw new WebhookVerificationError({
+                    message: `Webhook payload is missing string event type at "${eventTypePath}".`,
+                    provider: options.provider,
+                    code: "missing_event_type",
+                });
+            }
+            return {
+                id,
+                type,
+                provider: options.provider,
+                payload,
+                raw: payload,
+            };
+        },
+    };
+}
+function validateWebhook(webhook) {
+    if (!webhook.name)
+        throw new WebhookOptionsError("Webhook name is required.");
+}
+function validateEvent(webhook, event) {
+    if (!event.id) {
+        throw new WebhookVerificationError({
+            message: `Webhook "${webhook.name}" event is missing an ID.`,
+            webhookName: webhook.name,
+            provider: webhook.provider,
+            code: "missing_event_id",
+        });
+    }
+    if (!event.type) {
+        throw new WebhookVerificationError({
+            message: `Webhook "${webhook.name}" event is missing a type.`,
+            webhookName: webhook.name,
+            provider: webhook.provider,
+            code: "missing_event_type",
+        });
+    }
+}
+function formatPath(path) {
+    if (!path?.length)
+        return "";
+    return path
+        .map((segment) => typeof segment === "object" && segment !== null && "key" in segment
+        ? String(segment.key)
+        : String(segment))
+        .join(".");
+}
+function formatIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = formatPath(issue.path);
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join("; ");
+}
+function normalizeHeaderName(name) {
+    return name.toLowerCase();
+}
+function normalizeSignature(signature, prefix) {
+    const trimmed = signature.trim();
+    if (!prefix)
+        return trimmed;
+    return trimmed.startsWith(prefix) ? trimmed.slice(prefix.length) : trimmed;
+}
+function rawBodyBytes(rawBody) {
+    if (typeof rawBody === "string")
+        return new TextEncoder().encode(rawBody);
+    if (rawBody instanceof Uint8Array)
+        return rawBody;
+    return new Uint8Array(rawBody);
+}
+function rawBodyText(rawBody) {
+    if (typeof rawBody === "string")
+        return rawBody;
+    return new TextDecoder().decode(rawBodyBytes(rawBody));
+}
+function parseJsonBody(rawBody) {
+    try {
+        return JSON.parse(rawBodyText(rawBody));
+    }
+    catch (error) {
+        throw new WebhookVerificationError({
+            message: "Webhook payload must be valid JSON.",
+            code: "invalid_json",
+            cause: error,
+        });
+    }
+}
+function readStringPath(input, path) {
+    let value = input;
+    for (const segment of path.split(".")) {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return undefined;
+        }
+        value = value[segment];
+    }
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+async function hmacHex(algorithm, secret, rawBody) {
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: algorithm ?? "SHA-256" }, false, ["sign"]);
+    const bytes = rawBodyBytes(rawBody);
+    const data = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    const signature = await crypto.subtle.sign("HMAC", key, data);
+    return bytesToHex(new Uint8Array(signature));
+}
+function bytesToHex(bytes) {
+    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function timingSafeStringEqual(a, b) {
+    const encoder = new TextEncoder();
+    const [digestA, digestB] = await Promise.all([
+        crypto.subtle.digest("SHA-256", encoder.encode(a)),
+        crypto.subtle.digest("SHA-256", encoder.encode(b)),
+    ]);
+    const bytesA = new Uint8Array(digestA);
+    const bytesB = new Uint8Array(digestB);
+    let mismatch = 0;
+    for (let index = 0; index < bytesA.length; index++) {
+        mismatch |= (bytesA[index] ?? 0) ^ (bytesB[index] ?? 0);
+    }
+    return mismatch === 0;
+}
+//# sourceMappingURL=index.js.map

package/dist/webhooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/webhooks/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/core",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "type": "module",
   "description": "Core framework primitives for Beignet",
   "exports": {
@@ -130,6 +130,10 @@
       "types": "./dist/uploads/client.d.ts",
       "default": "./dist/uploads/client.js"
     },
+    "./webhooks": {
+      "types": "./dist/webhooks/index.d.ts",
+      "default": "./dist/webhooks/index.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "default": "./dist/server/index.js"

package/src/ports/index.ts

@@ -37,6 +37,7 @@
  * - `@beignet/core/outbox` owns durable outbox helpers and test adapters
  * - `@beignet/core/payments` owns `PaymentsPort` and payment test adapters
  * - `@beignet/core/schedules` owns schedule definitions and runners
+ * - `@beignet/core/webhooks` owns inbound webhook definitions and verifiers
  */
 
 import { createUnboundPort } from "./unbound.js";
@@ -358,6 +359,42 @@ export {
   SearchOptionsError,
   searchDocuments,
 } from "../search/index.js";
+/**
+ * Webhook exports.
+ *
+ * Webhooks have a dedicated subpath. Re-export the common app-facing
+ * definitions and helpers here so production concerns can be imported from one
+ * shared port toolbox when useful.
+ */
+export type {
+  CreateHmacWebhookVerifierOptions,
+  CreateMemoryWebhookVerifierOptions,
+  DefineWebhookOptions,
+  InferSchemaOutput,
+  InferWebhookEvent,
+  MemoryWebhookVerifier,
+  VerifyWebhookInput,
+  VerifyWebhookOptions,
+  WebhookDef,
+  WebhookEvent,
+  WebhookEventSchemas,
+  WebhookHeaders,
+  WebhookRawBody,
+  WebhookVerifier,
+} from "../webhooks/index.js";
+/**
+ * Webhook helper exports.
+ */
+export {
+  createHmacWebhookVerifier,
+  createMemoryWebhookVerifier,
+  defineWebhook,
+  parseWebhookEvent,
+  verifyWebhook,
+  WebhookOptionsError,
+  WebhookValidationError,
+  WebhookVerificationError,
+} from "../webhooks/index.js";
 /**
  * Audit log port exports.
  */

package/src/server/hooks/error-reporting.ts

@@ -0,0 +1,249 @@
+/**
+ * Error reporting hook utilities for @beignet/core/server
+ */
+
+import type { HttpContractConfig } from "../../contracts/index.js";
+import type {
+  ErrorReporterPort,
+  ErrorReportOptions,
+} from "../../error-reporting/index.js";
+import { isAppError, SchemaValidationError } from "../../errors/index.js";
+import {
+  IdempotencyConflictError,
+  IdempotencyInProgressError,
+} from "../../idempotency/index.js";
+import {
+  AuthUnauthorizedError,
+  EntitlementRequiredError,
+  GateAuthorizationError,
+  TenantRequiredError,
+} from "../../ports/index.js";
+import type {
+  HttpRequestLike,
+  ServerCaughtErrorHook,
+  ServerHook,
+} from "../types.js";
+
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Minimal context shape used by `createErrorReportingHooks(...)`.
+ */
+export type ErrorReportingContext = {
+  ports?: {
+    errorReporter?: ErrorReporterPort;
+  };
+  requestId?: string;
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  traceparent?: string;
+  actor?: {
+    type?: string;
+    id?: string;
+  };
+  tenant?: {
+    id?: string;
+  };
+};
+
+/**
+ * Arguments passed to error reporting hook callbacks.
+ */
+export type ErrorReportingHookArgs<Ctx> = Parameters<
+  ServerCaughtErrorHook<Ctx>
+>[0];
+
+/**
+ * Error reporter resolver accepted by `createErrorReportingHooks(...)`.
+ */
+export type ErrorReporterResolver<Ctx> = (
+  args: ErrorReportingHookArgs<Ctx>,
+) => MaybePromise<ErrorReporterPort | undefined>;
+
+/**
+ * Options accepted by `createErrorReportingHooks(...)`.
+ */
+export interface ErrorReportingHooksOptions<Ctx> {
+  /**
+   * Reporter to use instead of `ctx.ports.errorReporter`.
+   */
+  reporter?: ErrorReporterPort | ErrorReporterResolver<Ctx>;
+  /**
+   * Decide whether a caught error should be captured. The default reports
+   * unexpected failures and skips expected catalog/auth/validation outcomes.
+   */
+  shouldReport?: (args: ErrorReportingHookArgs<Ctx>) => MaybePromise<boolean>;
+  /**
+   * Additional capture options. These are merged over Beignet's request,
+   * actor, tenant, contract, and trace metadata.
+   */
+  reportOptions?:
+    | ErrorReportOptions
+    | ((args: ErrorReportingHookArgs<Ctx>) => MaybePromise<ErrorReportOptions>);
+  /**
+   * Observer for reporter failures. Reporter failures are otherwise ignored so
+   * error reporting cannot change the HTTP response.
+   */
+  onReporterError?: (args: {
+    error: unknown;
+    reportingError: unknown;
+    ctx?: Ctx;
+    req: HttpRequestLike;
+    contract: HttpContractConfig;
+  }) => MaybePromise<void>;
+}
+
+/**
+ * Create server hooks that capture unexpected HTTP request failures through
+ * `ctx.ports.errorReporter`.
+ *
+ * The hook observes `onCaughtError`, never maps responses, and ignores capture
+ * failures by default so reporting cannot affect request handling.
+ */
+export function createErrorReportingHooks<
+  Ctx extends ErrorReportingContext = ErrorReportingContext,
+>(config: ErrorReportingHooksOptions<Ctx> = {}): ServerHook<Ctx> {
+  return {
+    name: "error-reporting",
+    async onCaughtError(args) {
+      const shouldReport = config.shouldReport
+        ? await config.shouldReport(args)
+        : shouldReportServerError(args.err);
+      if (!shouldReport) return;
+
+      const reporter = await resolveReporter(config.reporter, args);
+      if (!reporter) return;
+
+      const baseOptions = createDefaultReportOptions(args);
+      const customOptions =
+        typeof config.reportOptions === "function"
+          ? await config.reportOptions(args)
+          : config.reportOptions;
+
+      try {
+        await reporter.captureException(
+          args.err,
+          mergeReportOptions(baseOptions, customOptions),
+        );
+      } catch (reportingError) {
+        try {
+          await config.onReporterError?.({
+            error: args.err,
+            reportingError,
+            ctx: args.ctx,
+            req: args.req,
+            contract: args.contract,
+          });
+        } catch {
+          // Reporter failure observers must not affect request handling.
+        }
+      }
+    },
+  };
+}
+
+/**
+ * Default filter for HTTP error reporting.
+ */
+export function shouldReportServerError(error: unknown): boolean {
+  if (isAppError(error)) return false;
+  if (error instanceof AuthUnauthorizedError) return false;
+  if (error instanceof TenantRequiredError) return false;
+  if (error instanceof IdempotencyConflictError) return false;
+  if (error instanceof IdempotencyInProgressError) return false;
+  if (error instanceof GateAuthorizationError) return false;
+  if (error instanceof EntitlementRequiredError) return false;
+  if (error instanceof SchemaValidationError) return false;
+  return true;
+}
+
+async function resolveReporter<Ctx extends ErrorReportingContext>(
+  reporter: ErrorReportingHooksOptions<Ctx>["reporter"],
+  args: ErrorReportingHookArgs<Ctx>,
+): Promise<ErrorReporterPort | undefined> {
+  if (typeof reporter === "function") {
+    return reporter(args);
+  }
+
+  if (reporter) {
+    return reporter;
+  }
+
+  return args.ctx?.ports?.errorReporter;
+}
+
+function createDefaultReportOptions<Ctx extends ErrorReportingContext>(
+  args: ErrorReportingHookArgs<Ctx>,
+): ErrorReportOptions {
+  const ctx = args.ctx;
+  const url = safeUrl(args.req.url);
+  const actor = ctx?.actor;
+  const tenant = ctx?.tenant;
+
+  return {
+    level: "error",
+    mechanism: "beignet.server",
+    handled: false,
+    requestId: ctx?.requestId,
+    traceId: ctx?.traceId,
+    spanId: ctx?.spanId,
+    parentSpanId: ctx?.parentSpanId,
+    traceparent: ctx?.traceparent,
+    user: actor?.type === "user" && actor.id ? { id: actor.id } : undefined,
+    tags: {
+      "beignet.kind": "http",
+      "http.method": args.req.method,
+      "http.route": args.contract.path,
+      "http.contract": args.contract.name,
+    },
+    contexts: {
+      request: {
+        method: args.req.method,
+        path: url?.pathname ?? args.contract.path,
+        route: args.contract.path,
+        contract: args.contract.name,
+      },
+      actor:
+        actor?.type || actor?.id
+          ? {
+              type: actor.type,
+              id: actor.id,
+            }
+          : undefined,
+      tenant: tenant?.id ? { id: tenant.id } : undefined,
+    },
+  };
+}
+
+function mergeReportOptions(
+  base: ErrorReportOptions,
+  custom: ErrorReportOptions | undefined,
+): ErrorReportOptions {
+  if (!custom) return base;
+
+  return {
+    ...base,
+    ...custom,
+    tags: {
+      ...base.tags,
+      ...custom.tags,
+    },
+    contexts: {
+      ...base.contexts,
+      ...custom.contexts,
+    },
+    extra: {
+      ...base.extra,
+      ...custom.extra,
+    },
+  };
+}
+
+function safeUrl(value: string): URL | undefined {
+  try {
+    return new URL(value);
+  } catch {
+    return undefined;
+  }
+}

package/src/server/hooks/index.ts

@@ -16,6 +16,14 @@ export {
   type CorsConfig,
   createCorsHooks,
 } from "./cors.js";
+export {
+  createErrorReportingHooks,
+  type ErrorReporterResolver,
+  type ErrorReportingContext,
+  type ErrorReportingHookArgs,
+  type ErrorReportingHooksOptions,
+  shouldReportServerError,
+} from "./error-reporting.js";
 export {
   defaultMapErrorToResponse,
   type ErrorMappingConfig,

package/src/server/server.ts

@@ -2396,6 +2396,11 @@ export function contractsFromRoutes<
  * ```
  */
 export function defineRouteGroup<Ctx>(): RouteGroupBuilder<Ctx>;
+/**
+ * @deprecated Prefer `defineRouteGroup<Ctx>()({ ... })`. TypeScript cannot
+ * infer the route tuple generic when callers provide only `Ctx`, so the direct
+ * form preserves context checking but erases per-route contract output checks.
+ */
 export function defineRouteGroup<
   Ctx,
   // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level

package/src/server/use-case-route.ts

@@ -223,8 +223,8 @@ export type UseCaseRouteDef<
 /**
  * Structural check that a use case accepts the context this route provides.
  *
- * Enforced through `run` parameter contravariance so it applies even where
- * contract types are erased, such as `defineRouteGroup<Ctx>({ ... })`.
+ * Enforced through `run` parameter contravariance so it applies even at loose
+ * collection boundaries where contract types are erased.
  */
 export type UseCaseAcceptsCtx<Ctx> = {
   run: (args: { ctx: Ctx; input: never }) => Promise<unknown>;