@xemahq/kernel-contracts 0.2.0 → 0.2.2

package/src/mail-source/lib/mail-event.ts

@@ -0,0 +1,106 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Canonical mail-event contract ──
+//
+// Domain biomes subscribe to these `type`s to add email workflows WITHOUT
+// importing MailOps. A domain biome (editorial, finance, support, …) listens
+// for `mail.message.received` / `mail.message.classified` / `mail.thread.updated`
+// on the event bus and dispatches its OWN workflows — exactly the way the
+// search-source registry (`@xemahq/kernel-contracts/search-source`) lets
+// search-api index any biome without importing a single source client.
+//
+// These contracts live in the KERNEL so a subscriber depends on the kernel
+// package, never on `mailops-api`. MailOps is the single producer: its
+// publisher imports this contract and emits the events; subscribers import the
+// same contract and match on it. Producer and consumers share one source of
+// truth, with zero service-to-service code coupling.
+//
+// The payloads are deliberately domain-AGNOSTIC: stable identity + addressing
+// fields that fit any mailbox. `classification` and `labels` are optional
+// passthrough — a domain that runs a classifier upstream can carry its verdict
+// here, but the contract itself never invents domain semantics.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+/**
+ * Closed set of canonical mail-event `type`s. These are the wire identifiers
+ * domain biomes subscribe to — never a free-form string at a call site.
+ */
+export enum MailEventType {
+  /** A mail message was received + persisted. */
+  MessageReceived = 'mail.message.received',
+  /** A received message carries (or was given) a classification verdict. */
+  MessageClassified = 'mail.message.classified',
+  /** A thread's roll-up (membership / latest activity) changed. */
+  ThreadUpdated = 'mail.thread.updated',
+}
+
+/**
+ * The stable identity + addressing fields every mail event shares. Domain
+ * biomes match/route on exactly these — nothing producer-internal leaks here.
+ */
+export const MailEventBaseSchema = z.object({
+  orgId: z.string().min(1),
+  projectId: z.string().min(1).optional(),
+  /** Mailbox the message belongs to (provider-native key or address). */
+  mailboxRef: z.string().min(1),
+  /** Provider message id of the inbound email. */
+  messageId: z.string().min(1),
+  /** Opaque per-conversation thread reference, when the message threads. */
+  threadRef: z.string().min(1).optional(),
+  from: z.string().min(1),
+  subject: z.string().optional(),
+  /** ISO-8601 timestamp the provider stamped on the message. */
+  receivedAt: z.string().min(1),
+  /** Optional provider/domain labels carried verbatim. */
+  labels: z.array(z.string()).optional(),
+});
+
+/** `mail.message.received` payload. */
+export const MailMessageReceivedSchema = MailEventBaseSchema.extend({
+  /**
+   * Optional classification passthrough. Present when an upstream classifier
+   * already tagged the message at ingest; absent otherwise.
+   */
+  classification: z.string().min(1).optional(),
+});
+
+/**
+ * `mail.message.classified` payload. Same identity as received, with the
+ * classification required (the event exists BECAUSE a verdict was produced).
+ */
+export const MailMessageClassifiedSchema = MailEventBaseSchema.extend({
+  classification: z.string().min(1),
+});
+
+/** `mail.thread.updated` payload — a thread roll-up changed. */
+export const MailThreadUpdatedSchema = z.object({
+  orgId: z.string().min(1),
+  projectId: z.string().min(1).optional(),
+  mailboxRef: z.string().min(1),
+  threadRef: z.string().min(1),
+  subject: z.string().optional(),
+  /** Distinct participant addresses in the thread. */
+  participants: z.array(z.string()),
+  /** Number of messages in the thread at the time of the event. */
+  messageCount: z.number().int().nonnegative(),
+  /** ISO-8601 timestamp of the most recent message in the thread. */
+  lastReceivedAt: z.string().min(1),
+});
+
+export type MailMessageReceivedPayload = z.infer<
+  typeof MailMessageReceivedSchema
+>;
+export type MailMessageClassifiedPayload = z.infer<
+  typeof MailMessageClassifiedSchema
+>;
+export type MailThreadUpdatedPayload = z.infer<typeof MailThreadUpdatedSchema>;
+
+/** Schema version stamped on every canonical mail event. */
+export const MAIL_EVENT_SCHEMA_VERSION = '1.0.0' as const;
+
+/** Producer URI for every canonical mail event. */
+export const MAIL_EVENT_SOURCE = '/xema/services/mailops-api' as const;
+
+/** `ehdatatype` discriminator for the mail-event family. */
+export const MAIL_EVENT_DATA_TYPE = 'mailops' as const;

package/src/policy/index.ts

@@ -1,3 +1,4 @@
 export * from './lib/obligations';
+export * from './lib/egress-allowlist';
 export * from './lib/route-hints';
 export * from './lib/policy';

package/src/policy/lib/egress-allowlist.ts

@@ -0,0 +1,239 @@
+import {
+  EgressAllowlistObligationSchema,
+  type EgressAllowlistObligation,
+} from './obligations';
+
+/**
+ * Shared, deterministic egress-decision matcher for the
+ * `PolicyObligationKind.EgressAllowlist` obligation.
+ *
+ * This is the SINGLE implementation every outbound-fetch caller reuses —
+ * do not copy the wildcard semantics into a fetch activity. It is a pure
+ * function with zero IO and zero RegExp backtracking surface (patterns are
+ * tokenised and compared label-by-label / segment-by-segment), so it is
+ * safe to call on every outbound request.
+ *
+ * Layered control, NOT a replacement: the IP-level SSRF block (private /
+ * loopback / link-local / metadata ranges) lives in the fetch activity and
+ * is ALWAYS applied. This matcher adds a SEPARATE domain-level (hostname /
+ * URL-prefix wildcard) gate on top, driven by org policy.
+ */
+
+/** Result of an egress evaluation. `allowed=false` carries a typed reason. */
+export type EgressDecision =
+  | { readonly allowed: true }
+  | { readonly allowed: false; readonly reason: EgressDenyReason };
+
+/** Closed set of egress-deny reasons — never a free-form string. */
+export enum EgressDenyReason {
+  /** Target URL did not parse, or used a non-http(s) scheme. */
+  InvalidTarget = 'invalid-target',
+  /** Target matched a `deny` pattern. */
+  Blocklisted = 'blocklisted',
+  /** Target matched no `allow` pattern. */
+  NotAllowlisted = 'not-allowlisted',
+}
+
+/**
+ * Thrown when the obligation payload itself is malformed (a bad pattern,
+ * empty allowlist, …). This is a HARD error at evaluation time — a
+ * misconfigured policy must never silently allow egress.
+ */
+export class MalformedEgressObligationError extends Error {
+  constructor(detail: string) {
+    super(`Malformed egress-allowlist obligation: ${detail}`);
+    this.name = 'MalformedEgressObligationError';
+  }
+}
+
+/**
+ * Evaluate whether `targetUrl` is permitted by the egress obligation.
+ *
+ * Fail-fast: a malformed `obligation` payload throws
+ * `MalformedEgressObligationError` — it is NOT treated as "allow". A
+ * target that does not parse, or uses a non-http(s) scheme, is denied with
+ * `EgressDenyReason.InvalidTarget` (the IP-level SSRF guard also rejects
+ * those, but this matcher is defensive in isolation).
+ *
+ * Decision: a target is allowed iff it matches at least one `allow`
+ * pattern AND no `deny` pattern. `deny` always wins over `allow`.
+ */
+export function evaluateEgress(
+  targetUrl: string,
+  obligation: EgressAllowlistObligation,
+): EgressDecision {
+  // Re-validate the payload at the evaluation boundary. A producer that
+  // bypassed the wire schema (e.g. a hand-built obligation) cannot smuggle
+  // a malformed pattern past the matcher.
+  const parsed = EgressAllowlistObligationSchema.safeParse(obligation);
+  if (!parsed.success) {
+    throw new MalformedEgressObligationError(parsed.error.issues[0]?.message ?? 'invalid payload');
+  }
+  const { allow, deny } = parsed.data;
+
+  const target = parseTarget(targetUrl);
+  if (target === null) {
+    return { allowed: false, reason: EgressDenyReason.InvalidTarget };
+  }
+
+  if (deny !== undefined) {
+    for (const pattern of deny) {
+      if (matchPattern(pattern, target)) {
+        return { allowed: false, reason: EgressDenyReason.Blocklisted };
+      }
+    }
+  }
+
+  for (const pattern of allow) {
+    if (matchPattern(pattern, target)) {
+      return { allowed: true };
+    }
+  }
+  return { allowed: false, reason: EgressDenyReason.NotAllowlisted };
+}
+
+/**
+ * Boolean convenience wrapper. Returns `true` iff `evaluateEgress`
+ * allows the target. Re-throws `MalformedEgressObligationError` — a bad
+ * obligation is never silently coerced to a boolean.
+ */
+export function isEgressAllowed(
+  targetUrl: string,
+  obligation: EgressAllowlistObligation,
+): boolean {
+  return evaluateEgress(targetUrl, obligation).allowed;
+}
+
+// ── internals ───────────────────────────────────────────────────────────
+
+interface ParsedTarget {
+  /** Lower-cased host with no port, no trailing dot. */
+  readonly host: string;
+  /** `http:` or `https:` (lower-cased, includes the colon, matches URL API). */
+  readonly scheme: string;
+  /** Path with a single normalised form: leading `/`, no trailing slash (except root `/`). */
+  readonly path: string;
+}
+
+/**
+ * Parse the target into the canonical `(scheme, host, path)` shape the
+ * matcher compares against. Returns `null` for an unparseable URL or a
+ * non-http(s) scheme — the WHATWG `URL` parser collapses
+ * credential/fragment/IP-literal bypass attempts (e.g.
+ * `https://evil.com#@good.com`, `https://user:pass@evil.com`) into their
+ * real host, so a crafted pattern-looking authority cannot smuggle past
+ * the host comparison.
+ */
+function parseTarget(rawUrl: string): ParsedTarget | null {
+  let u: URL;
+  try {
+    u = new URL(rawUrl);
+  } catch {
+    return null;
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    return null;
+  }
+  const host = u.hostname.toLowerCase().replace(/\.$/, '');
+  if (host.length === 0) {
+    return null;
+  }
+  return { host, scheme: u.protocol, path: normalisePath(u.pathname) };
+}
+
+/** Collapse `//` and strip a trailing slash (keep root `/`). */
+function normalisePath(pathname: string): string {
+  const collapsed = pathname.replace(/\/{2,}/g, '/');
+  if (collapsed.length > 1 && collapsed.endsWith('/')) {
+    return collapsed.slice(0, -1);
+  }
+  return collapsed.length === 0 ? '/' : collapsed;
+}
+
+/**
+ * Match a single pattern against the parsed target. A pattern with a
+ * scheme is a URL pattern (scheme + host + path-prefix); otherwise it is a
+ * host-only pattern. Deterministic, bounded, no RegExp.
+ */
+function matchPattern(pattern: string, target: ParsedTarget): boolean {
+  const schemeSep = pattern.indexOf('://');
+  if (schemeSep === -1) {
+    // Host-only pattern — must contain no path separator.
+    if (pattern.includes('/')) {
+      // A pattern like `example.com/api` with no scheme is ambiguous;
+      // treat it as a non-match rather than guessing. The wire schema
+      // already steers authors toward an explicit `https://` URL pattern.
+      return false;
+    }
+    return matchHost(pattern.toLowerCase(), target.host);
+  }
+
+  const scheme = pattern.slice(0, schemeSep + 1).toLowerCase(); // includes trailing `:`
+  if (scheme !== target.scheme) {
+    return false;
+  }
+  const rest = pattern.slice(schemeSep + 3); // after `://`
+  const slash = rest.indexOf('/');
+  const hostPart = (slash === -1 ? rest : rest.slice(0, slash)).toLowerCase();
+  const pathPart = slash === -1 ? '' : rest.slice(slash);
+  if (!matchHost(hostPart, target.host)) {
+    return false;
+  }
+  return matchPath(pathPart, target.path);
+}
+
+/**
+ * Host match: label-by-label, `*` matches exactly one label. Both sides
+ * are tokenised on `.`; label counts must match exactly so `*.a.com`
+ * never matches `a.com` or `x.y.a.com`.
+ */
+function matchHost(pattern: string, host: string): boolean {
+  if (pattern.length === 0) {
+    return false;
+  }
+  const pLabels = pattern.split('.');
+  const hLabels = host.split('.');
+  if (pLabels.length !== hLabels.length) {
+    return false;
+  }
+  for (let i = 0; i < pLabels.length; i++) {
+    const pl = pLabels[i];
+    const hl = hLabels[i];
+    if (pl === '*') {
+      // `*` matches exactly one non-empty label; reject an empty host label.
+      if (hl === undefined || hl.length === 0) {
+        return false;
+      }
+      continue;
+    }
+    if (pl !== hl) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Path-prefix match for a URL pattern. Semantics:
+ *   • `''` or `/`        → matches any path (host-level rule).
+ *   • `/api`             → exact path `/api` only.
+ *   • `/api/*`           → `/api` and any sub-path `/api/...`.
+ * Compared segment-by-segment after normalising the pattern path the same
+ * way as the target.
+ */
+function matchPath(patternPath: string, targetPath: string): boolean {
+  if (patternPath === '' || patternPath === '/') {
+    return true;
+  }
+  const wildcard = patternPath.endsWith('/*');
+  const base = normalisePath(wildcard ? patternPath.slice(0, -2) : patternPath);
+  if (!wildcard) {
+    return targetPath === base;
+  }
+  // `/api/*` matches `/api` exactly and any `/api/<seg>...`. Compare on a
+  // segment boundary so `/api/*` does NOT match `/apix`.
+  if (targetPath === base) {
+    return true;
+  }
+  return targetPath.startsWith(base === '/' ? '/' : `${base}/`);
+}

package/src/policy/lib/obligations.ts

@@ -18,6 +18,15 @@ export enum PolicyObligationKind {
   MaxCostUsd = 'max-cost-usd',
   RestrictOutputClassification = 'restrict-output-classification',
   DataResidency = 'data-residency',
+  /**
+   * Org-level egress allowlist (SSRF / exfiltration control). Carries a
+   * set of wildcard host/URL patterns the executing party MAY reach on an
+   * outbound fetch; an optional blocklist subtracts from it. Generic — it
+   * is NOT mail-specific; every biome's outbound-fetch path consults it.
+   * Evaluated by the shared `isEgressAllowed` matcher (this module) — never
+   * by an ad-hoc string compare. See `EgressAllowlistObligation`.
+   */
+  EgressAllowlist = 'egress-allowlist',
 }
 
 export const PolicyObligationKindSchema = z.nativeEnum(PolicyObligationKind);
@@ -134,6 +143,57 @@ export type DataResidencyObligation = z.infer<
   typeof DataResidencyObligationSchema
 >;
 
+// ── Egress allowlist payload ────────────────────────────────────────────
+//
+// A pattern is matched against the target URL by `isEgressAllowed` below.
+// Two pattern shapes are supported, distinguished structurally at match
+// time (NOT by a free-form flag):
+//
+//   • Host pattern   — no scheme, no path. Matched against the URL host
+//     ONLY. `*` matches exactly ONE dns label; `**` is NOT supported (a
+//     single `*` already spans one label, and multi-label wildcards invite
+//     over-broad rules). Examples: `outlook.office365.com`,
+//     `*.office365.com` (matches `a.office365.com`, NOT `office365.com`
+//     and NOT `a.b.office365.com`).
+//   • URL pattern    — has a scheme (`https://…`). Scheme + host are
+//     matched exactly (host may itself use the `*`-per-label wildcard) and
+//     the path prefix is matched with a single trailing `/*` meaning "this
+//     path or any sub-path". Examples: `https://example.com/api/*`
+//     (matches `https://example.com/api`, `https://example.com/api/v1`,
+//     NOT `https://example.com/apix`).
+//
+// Matching is deterministic and bounded — patterns are tokenised on `.`
+// (host) / `/` (path) and compared label-by-label / segment-by-segment.
+// No pattern is ever compiled to a backtracking RegExp, so there is no
+// catastrophic-regex surface.
+const EGRESS_PATTERN = z
+  .string()
+  .min(1)
+  // Disallow whitespace, embedded credentials (`@`), fragments (`#`) and
+  // query (`?`) in a PATTERN — those belong to the *target*, not the rule,
+  // and accepting them would let a rule author write an ambiguous pattern.
+  .refine((p) => !/[\s@#?]/.test(p), {
+    message:
+      'egress pattern must not contain whitespace, "@", "#" or "?" (those belong to the target URL, not the rule)',
+  });
+
+export const EgressAllowlistObligationSchema = z.object({
+  kind: z.literal(PolicyObligationKind.EgressAllowlist),
+  /**
+   * Non-empty allowlist. An outbound target is permitted only if it
+   * matches at least one `allow` pattern AND no `deny` pattern. An empty
+   * `allow` array is rejected — an egress obligation with nothing allowed
+   * would deny ALL egress, which is expressed by simply NOT shipping the
+   * obligation (opt-in semantics) rather than an empty allowlist.
+   */
+  allow: z.array(EGRESS_PATTERN).min(1),
+  /** Optional blocklist; a match here denies even if `allow` matched. */
+  deny: z.array(EGRESS_PATTERN).optional(),
+});
+export type EgressAllowlistObligation = z.infer<
+  typeof EgressAllowlistObligationSchema
+>;
+
 /**
  * `PolicyObligation` — closed discriminated union (plan v4.3 §A.4).
  *
@@ -150,6 +210,7 @@ export const PolicyObligationSchema = z.discriminatedUnion('kind', [
   MaxCostUsdObligationSchema,
   RestrictOutputClassificationObligationSchema,
   DataResidencyObligationSchema,
+  EgressAllowlistObligationSchema,
 ]);
 
 export type PolicyObligation = z.infer<typeof PolicyObligationSchema>;