@forgezero/access 0.1.0

package/dist/conditions.js

@@ -0,0 +1,491 @@
+// src/index.ts
+var SCHEMA_VERSION = 1;
+function assertReadable(document, what) {
+  const version = document.version ?? 1;
+  if (version > SCHEMA_VERSION) {
+    throw new AccessError("ACCESS_VERSION_TOO_NEW", `${what} is version ${version}; this build reads ${SCHEMA_VERSION}. Upgrade @forgezero/access.`);
+  }
+}
+
+class AccessError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "AccessError";
+  }
+}
+
+class Refusal extends Error {
+  status;
+  code;
+  details;
+  retryable;
+  refusal = true;
+  constructor(status, code, message, details = {}, retryable = false) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.retryable = retryable;
+    this.name = "Refusal";
+  }
+}
+function isRefusal(error) {
+  return typeof error === "object" && error !== null && error.refusal === true;
+}
+
+class Settled extends Error {
+  value;
+  status;
+  headers;
+  settled = true;
+  constructor(value, status = 200, headers = {}) {
+    super("Already settled.");
+    this.value = value;
+    this.status = status;
+    this.headers = headers;
+    this.name = "Settled";
+  }
+}
+function isSettled(error) {
+  return typeof error === "object" && error !== null && error.settled === true;
+}
+function defineFactors(factors) {
+  for (const [id, factor] of Object.entries(factors)) {
+    if (factor.status === "shipped" && !(factor.tests?.length ?? 0)) {
+      throw new AccessError("FACTOR_UNTESTED", `Factor "${id}" is marked shipped with no tests. A method nobody exercises is a claim.`);
+    }
+  }
+  return factors;
+}
+function page(label, options = {}) {
+  return { kind: "page", label, ...options };
+}
+function action(label, method, options = {}) {
+  return { kind: "action", label, method, ...options };
+}
+function defineRoutes(routes) {
+  for (const [key, route] of Object.entries(routes)) {
+    const isApi = key.startsWith("api/");
+    if (isApi !== (route.kind === "action")) {
+      throw new AccessError("ROUTE_KIND_MISMATCH", `"${key}": routes under api/ must be actions, and actions must be under api/.`);
+    }
+    if (route.kind === "action" && route.page && !(route.page in routes)) {
+      throw new AccessError("ROUTE_DANGLING_PAGE", `"${key}" names page "${route.page}", which does not exist.`);
+    }
+    if (route.kind === "action" && route.response) {
+      for (const status of Object.keys(route.response)) {
+        if (!route.response[Number(status)]) {
+          throw new AccessError("ROUTE_EMPTY_RESPONSE", `"${key}" declares status ${status} with no schema.`);
+        }
+      }
+    }
+  }
+  return routes;
+}
+function codePolicy(config) {
+  return {
+    roles: async () => config.roles,
+    enabledFactors: async () => config.enabledFactors
+  };
+}
+function externalPolicy(reader) {
+  return {
+    async roles() {
+      const roles = await reader.roles();
+      for (const role of roles)
+        assertReadable(role, `role "${role.roleKey}"`);
+      return roles;
+    },
+    enabledFactors: () => reader.enabledFactors()
+  };
+}
+function stemOf(routeKey, strip) {
+  const withoutApi = routeKey.startsWith("api/") ? routeKey.slice(4) : routeKey;
+  return strip ? withoutApi.replace(strip, "") : withoutApi;
+}
+function grantsRoute(grants, routeKey, options = {}) {
+  const { mode = "inherit", sharesGrantWith, strip } = options;
+  const stem = stemOf(routeKey, strip);
+  const shared = sharesGrantWith ? stemOf(sharesGrantWith, strip) : undefined;
+  return grants.some((grant) => {
+    const granted = stemOf(grant, strip);
+    if (stem === granted || granted === routeKey)
+      return true;
+    if (shared !== undefined && (granted === shared || granted === sharesGrantWith))
+      return true;
+    return mode === "inherit" && stem.startsWith(granted + "/");
+  });
+}
+function fulfilledActionFactors() {
+  return [];
+}
+function defineAccessControl(config) {
+  assertReadable(config, "access control");
+  const routeKeys = new Set(Object.keys(config.routes));
+  const actionKeys = Object.entries(config.routes).filter(([, route]) => route.kind === "action").map(([key]) => key);
+  const checkKeys = (listName, name, keys) => {
+    if (keys.length === 0) {
+      throw new AccessError("POLICY_ORPHANED", `${listName} "${name}" binds no routes.`);
+    }
+    for (const key of keys) {
+      if (!routeKeys.has(key)) {
+        throw new AccessError("POLICY_UNKNOWN_ROUTE", `${listName} "${name}" names "${key}", which is not a route.`);
+      }
+    }
+  };
+  const sessionOf = new Map;
+  for (const [name, policy] of Object.entries(config.sessionPolicies)) {
+    checkKeys("Session policy", name, policy.routes);
+    for (const key of policy.routes) {
+      if (sessionOf.has(key)) {
+        throw new AccessError("SESSION_DUPLICATE", `"${key}" is in more than one session policy.`);
+      }
+      sessionOf.set(key, policy);
+    }
+    for (const factor of policy.factors) {
+      const spec = config.factors[factor];
+      if (!spec)
+        throw new AccessError("FACTOR_UNKNOWN", `Session policy "${name}" names unknown factor "${factor}".`);
+      if (spec.kind === "action") {
+        throw new AccessError("FACTOR_WRONG_KIND", `"${factor}" is action-only and cannot establish a session.`);
+      }
+    }
+  }
+  const unclassified = [...routeKeys].filter((key) => !sessionOf.has(key));
+  if (unclassified.length > 0) {
+    throw new AccessError("SESSION_INCOMPLETE", `No session policy covers: ${unclassified.join(", ")}. Every route needs exactly one.`);
+  }
+  const actionOf = new Map;
+  for (const [name, policy] of Object.entries(config.actionPolicies ?? {})) {
+    checkKeys("Action policy", name, policy.routes);
+    if (policy.required < 1 || policy.required > policy.factors.length) {
+      throw new AccessError("ACTION_UNSATISFIABLE", `Action policy "${name}" requires ${policy.required} of ${policy.factors.length} factors.`);
+    }
+    for (const factor of policy.factors) {
+      const spec = config.factors[factor];
+      if (!spec)
+        throw new AccessError("FACTOR_UNKNOWN", `Action policy "${name}" names unknown factor "${factor}".`);
+      if (spec.kind === "session") {
+        throw new AccessError("FACTOR_WRONG_KIND", `"${factor}" is session-only and cannot authorise an action.`);
+      }
+    }
+    for (const key of policy.routes) {
+      if (actionOf.has(key)) {
+        throw new AccessError("ACTION_DUPLICATE", `"${key}" is in more than one action policy.`);
+      }
+      actionOf.set(key, policy);
+    }
+  }
+  const rateOf = new Map;
+  const rateLists = Object.entries(config.ratePolicies ?? {});
+  for (const [name, policy] of rateLists) {
+    checkKeys("Rate policy", name, policy.routes);
+    for (const key of policy.routes) {
+      if (rateOf.has(key)) {
+        throw new AccessError("RATE_DUPLICATE", `"${key}" is in more than one rate policy.`);
+      }
+      rateOf.set(key, policy);
+    }
+  }
+  if (rateLists.length > 0) {
+    const unrated = actionKeys.filter((key) => !rateOf.has(key));
+    if (unrated.length > 0) {
+      throw new AccessError("RATE_INCOMPLETE", `No rate policy covers: ${unrated.join(", ")}. Declaring any means declaring all.`);
+    }
+  }
+  const beforeOf = new Map;
+  for (const [name, handler] of Object.entries(config.beforeHandlers ?? {})) {
+    checkKeys("Before handler", name, handler.routes);
+    for (const key of handler.routes) {
+      beforeOf.set(key, [...beforeOf.get(key) ?? [], handler]);
+    }
+  }
+  const afterOf = new Map;
+  for (const [name, handler] of Object.entries(config.afterHandlers ?? {})) {
+    checkKeys("After handler", name, handler.routes);
+    for (const key of handler.routes) {
+      afterOf.set(key, [...afterOf.get(key) ?? [], handler]);
+    }
+  }
+  const features = config.features ?? [];
+  return {
+    version: config.version ?? SCHEMA_VERSION,
+    routes: config.routes,
+    features,
+    source: config.source,
+    keys: () => Object.keys(config.routes),
+    get: (key) => config.routes[key],
+    exists(key, context) {
+      const route = config.routes[key];
+      if (!route)
+        return false;
+      if (route.feature && !features.includes(route.feature))
+        return false;
+      if (context?.stage && route.stages && !route.stages.includes(context.stage))
+        return false;
+      if (context?.realm && route.realms && !route.realms.includes(context.realm))
+        return false;
+      return true;
+    },
+    sessionPolicyFor: (key) => sessionOf.get(key),
+    actionPolicyFor: (key) => actionOf.get(key),
+    ratePolicyFor: (key) => rateOf.get(key),
+    beforeFor: (key) => beforeOf.get(key) ?? [],
+    afterFor: (key) => afterOf.get(key) ?? []
+  };
+}
+function authorise(args) {
+  const { access, routeKey, stage, realm, session, roles } = args;
+  if (!access.exists(routeKey, { stage, realm })) {
+    return { allow: false, status: 404, code: "NOT_FOUND" };
+  }
+  const policy = access.sessionPolicyFor(routeKey);
+  if (!policy || policy.factors.length === 0)
+    return { allow: true };
+  if (!session)
+    return { allow: false, status: 401, code: "AUTH_REQUIRED" };
+  const missing = policy.factors.filter((factor) => !session.factors.includes(factor));
+  if (missing.length > 0) {
+    return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
+  }
+  const grants = roles.filter((role) => session.roleKeys.includes(role.roleKey)).flatMap((role) => role.grants);
+  if (!grantsRoute(grants, routeKey)) {
+    return { allow: false, status: 403, code: "ACCESS_DENIED" };
+  }
+  return { allow: true };
+}
+function resolveActionFactors(policy, enabled) {
+  const available = policy.factors.filter((factor) => enabled.includes(factor));
+  return { available, required: policy.required, satisfiable: available.length >= policy.required };
+}
+function impactOfDisabling(access, enabledAfter) {
+  const broken = [];
+  for (const key of access.keys()) {
+    const policy = access.actionPolicyFor(key);
+    if (!policy)
+      continue;
+    const { available, required, satisfiable } = resolveActionFactors(policy, enabledAfter);
+    if (!satisfiable)
+      broken.push({ route: key, available: available.length, required });
+  }
+  return broken;
+}
+var VERSION = "0.1.0";
+
+// src/conditions.ts
+function define(condition, routes, refusals, run) {
+  return { condition, routes, refusals, run };
+}
+function required(state, name, condition) {
+  const value = state[name];
+  if (value === undefined) {
+    throw new Error(`${condition} needs state["${name}"], which is unset. Declare loadTarget before it in the before list.`);
+  }
+  return value;
+}
+function loadTarget(options) {
+  const as = options.as ?? "target";
+  const code = options.code ?? "NOT_FOUND";
+  const readId = options.id ?? ((context) => context.params.id);
+  return define("loadTarget", options.routes, [{ status: 404, code, when: "no record matches the identifier" }], async (context) => {
+    const id = readId(context);
+    if (!id)
+      throw new Refusal(404, code, "Not found.");
+    const record = await options.load(id, context);
+    if (record === undefined || record === null)
+      throw new Refusal(404, code, "Not found.");
+    return { [as]: record, [`${as}Id`]: id };
+  });
+}
+function requireOwner(options) {
+  const of = options.of ?? "target";
+  const subject = options.subject ?? ((context) => context.session?.userKey);
+  return define("requireOwner", options.routes, [{ status: 404, code: "NOT_FOUND", when: "the record belongs to somebody else" }], (context, state) => {
+    const record = required(state, of, "requireOwner");
+    const who = subject(context);
+    if (!who || options.owner(record) !== who)
+      throw new Refusal(404, "NOT_FOUND", "Not found.");
+  });
+}
+function requireState(options) {
+  const of = options.of ?? "target";
+  const code = options.code ?? "STATE_INVALID";
+  return define("requireState", options.routes, [{ status: 409, code, when: `the record is not ${options.allowed.join(" or ")}` }], (_context, state) => {
+    const record = required(state, of, "requireState");
+    const current = options.status(record);
+    if (!options.allowed.includes(current)) {
+      throw new Refusal(409, code, `This is not possible while the record is ${current}.`, {
+        status: current,
+        allowed: options.allowed
+      });
+    }
+  });
+}
+function requireVersion(options) {
+  const of = options.of ?? "target";
+  const read = options.expected ?? ((context) => context.headers.get("if-match") ?? context.body?.version);
+  return define("requireVersion", options.routes, [{ status: 412, code: "VERSION_CONFLICT", when: "the record changed since it was read" }], (context, state) => {
+    const record = required(state, of, "requireVersion");
+    const expected = read(context);
+    if (expected === undefined)
+      return;
+    const current = options.version(record);
+    if (String(current) !== String(expected).replace(/^"|"$/g, "")) {
+      throw new Refusal(412, "VERSION_CONFLICT", "This record changed since you loaded it. Reload and try again.", {
+        current: String(current)
+      });
+    }
+  });
+}
+function requireIdempotency(options) {
+  const read = options.key ?? ((context) => context.headers.get("idempotency-key") ?? undefined);
+  return define("requireIdempotency", options.routes, [
+    { status: 400, code: "IDEMPOTENCY_KEY_REQUIRED", when: "strict and the header is absent" },
+    { status: 409, code: "IDEMPOTENCY_IN_FLIGHT", when: "an identical request is still running" }
+  ], async (context) => {
+    const key = read(context);
+    if (!key) {
+      if (options.strict) {
+        throw new Refusal(400, "IDEMPOTENCY_KEY_REQUIRED", "This request needs an Idempotency-Key header.");
+      }
+      return;
+    }
+    const claim = await options.store.claim(key, context.route);
+    if (claim.state === "replay")
+      throw new Settled(claim.value, claim.status);
+    if (claim.state === "pending") {
+      throw new Refusal(409, "IDEMPOTENCY_IN_FLIGHT", "This request is already being processed.", {}, true);
+    }
+    return { idempotencyKey: key };
+  });
+}
+function requireUnlocked(options) {
+  return define("requireUnlocked", options.routes, [{ status: 423, code: "VAULT_LOCKED", when: "the master seed is not resident" }], async () => {
+    if (!await options.unlocked()) {
+      throw new Refusal(423, "VAULT_LOCKED", "The vault is locked. Custodians must unlock it before this can run.");
+    }
+  });
+}
+function requireService(options) {
+  return define("requireService", options.routes, [{ status: 503, code: "SERVICE_UNAVAILABLE", when: "every provider for the service is offline" }], async () => {
+    if (!await options.healthy(options.service)) {
+      throw new Refusal(503, "SERVICE_UNAVAILABLE", `The ${options.service} service is unavailable. Try again shortly.`, { service: options.service }, true);
+    }
+  });
+}
+function requireNotFrozen(options) {
+  return define("requireNotFrozen", options.routes, [{ status: 423, code: "FROZEN", when: "an operator or rule halted this subject" }], async (context, state) => {
+    const reason = await options.frozen(context, state);
+    if (reason)
+      throw new Refusal(423, "FROZEN", reason, { frozen: true });
+  });
+}
+function requireTier(options) {
+  const code = options.code ?? "TIER_REQUIRED";
+  return define("requireTier", options.routes, [{ status: 403, code, when: `the subject is below tier ${options.atLeast}` }], async (context, state) => {
+    const current = await options.tier(context, state);
+    if (current < options.atLeast) {
+      throw new Refusal(403, code, "This needs a higher tier than the account currently holds.", {
+        required: options.atLeast,
+        current,
+        ...options.ladder ? { ladder: options.ladder } : {}
+      });
+    }
+  });
+}
+function requireBalance(options) {
+  return define("requireBalance", options.routes, [{ status: 409, code: "INSUFFICIENT_BALANCE", when: "the available balance is below the amount" }], async (context, state) => {
+    const [amount, available] = await Promise.all([
+      options.amount(context, state),
+      options.available(context, state)
+    ]);
+    if (amount <= 0n)
+      throw new Refusal(422, "AMOUNT_INVALID", "The amount must be positive.");
+    if (available < amount) {
+      throw new Refusal(409, "INSUFFICIENT_BALANCE", "The available balance does not cover this.", {
+        required: amount.toString(),
+        available: available.toString(),
+        ...options.asset ? { asset: options.asset(context, state) } : {}
+      });
+    }
+  });
+}
+function requireQuota(options) {
+  const code = options.code ?? "QUOTA_EXCEEDED";
+  return define("requireQuota", options.routes, [{ status: 409, code, when: `the ${options.window} cap would be exceeded` }], async (context, state) => {
+    const [cap, amount, used] = await Promise.all([
+      options.cap(context, state),
+      options.amount(context, state),
+      options.used(context, state)
+    ]);
+    if (used + amount > cap) {
+      throw new Refusal(409, code, `This exceeds the ${options.window} limit for this account.`, {
+        window: options.window,
+        cap: cap.toString(),
+        used: used.toString(),
+        remaining: (cap > used ? cap - used : 0n).toString()
+      });
+    }
+  });
+}
+function requireApproval(options) {
+  return define("requireApproval", options.routes, [
+    { status: 409, code: "APPROVAL_PENDING", when: "the required approvals have not been collected" },
+    { status: 403, code: "APPROVAL_REJECTED", when: "an approver rejected it" }
+  ], async (context, state) => {
+    const approval = await options.approval(context, state);
+    if (approval.status === "rejected") {
+      throw new Refusal(403, "APPROVAL_REJECTED", approval.reason ?? "This was rejected by an approver.");
+    }
+    if (approval.status !== "approved") {
+      throw new Refusal(409, "APPROVAL_PENDING", "This is waiting on approval.", {
+        approvals: approval.approvals ?? 0,
+        required: approval.required ?? 1
+      }, true);
+    }
+  });
+}
+function assertDeclaredRefusals(args) {
+  const ignore = new Set(args.ignore ?? [401, 403, 404, 422, 428, 429, 500]);
+  const missing = [];
+  for (const condition of args.conditions) {
+    for (const routeKey of condition.routes) {
+      const route = args.routes[routeKey];
+      if (!route?.response)
+        continue;
+      for (const refusal of condition.refusals) {
+        if (ignore.has(refusal.status))
+          continue;
+        if (!(refusal.status in route.response)) {
+          missing.push(`${routeKey} can ${refusal.status} (${condition.condition}) but does not declare it`);
+        }
+      }
+    }
+  }
+  if (missing.length > 0) {
+    throw new Error(`Undeclared refusals:
+  ${missing.join(`
+  `)}`);
+  }
+}
+function refusalsFor(routeKey, conditions) {
+  return conditions.filter((condition) => condition.routes.includes(routeKey)).flatMap((condition) => condition.refusals.map((refusal) => ({ ...refusal, condition: condition.condition })));
+}
+export {
+  requireVersion,
+  requireUnlocked,
+  requireTier,
+  requireState,
+  requireService,
+  requireQuota,
+  requireOwner,
+  requireNotFrozen,
+  requireIdempotency,
+  requireBalance,
+  requireApproval,
+  refusalsFor,
+  loadTarget,
+  assertDeclaredRefusals
+};

package/dist/effects.d.ts

@@ -0,0 +1,168 @@
+import { type AfterHandler, type RequestContext } from './index';
+/**
+ * Effects — the reusable `after` catalog.
+ *
+ * What happens once a request has been decided: it is recorded, it is announced,
+ * it is metered, caches holding the old answer are dropped. Four things every
+ * project writes, all four easy to write in a way that is subtly wrong.
+ *
+ * ## Three rules every effect here obeys
+ *
+ * 1. **It cannot fail the request.** The pipeline queues after-handlers and
+ *    swallows throws, and these swallow their own too. An audit sink being down
+ *    must not turn a successful withdrawal into a 500 — the money already moved.
+ *
+ * 2. **It runs on refusals as well.** The pipeline calls the chain even when a
+ *    `before` threw, because a log missing every denied request is missing
+ *    exactly the requests worth having. Each effect below decides for itself
+ *    whether a refusal is interesting; `audit` says yes, `meter` says no.
+ *
+ * 3. **It redacts.** Logs, spans and event payloads all end up somewhere the
+ *    value was never meant to go. Every payload here goes through `redact`, so
+ *    an effect is not the accidental exfiltration path.
+ */
+type State = Record<string, unknown>;
+type Routes<K extends string> = {
+    routes: readonly K[];
+};
+export interface Effect<K extends string> extends AfterHandler<K> {
+    effect: string;
+}
+/** What the pipeline handed the after-chain, classified once instead of five times. */
+export interface Settlement {
+    outcome: 'allowed' | 'denied' | 'error' | 'settled';
+    status: number;
+    code?: string;
+    result: unknown;
+}
+export declare function settlementOf(result: unknown): Settlement;
+export interface AuditRecord {
+    route: string;
+    method: string;
+    outcome: Settlement['outcome'];
+    status: number;
+    code?: string;
+    userKey?: string;
+    realm?: string;
+    targetKey?: string;
+    atSec: number;
+    detail?: Record<string, unknown>;
+}
+export interface AuditSink {
+    /** Fire-and-forget. Anything that can reject must handle it internally. */
+    write(record: AuditRecord): void | Promise<void>;
+}
+export interface AuditOptions<K extends string> extends Routes<K> {
+    sink: AuditSink;
+    /** Extra context worth keeping. Redacted before it is written. */
+    detail?: (context: RequestContext, state: State, settlement: Settlement) => Record<string, unknown>;
+    /** State key holding the record identifier. Defaults to `targetId`. */
+    target?: string;
+}
+/**
+ * Append to the audit trail — denials included.
+ *
+ * A trail of successes answers "what did we do" and not "who tried what", and
+ * the second question is the one asked during an incident. A run of 403s
+ * against admin routes from one session is the signal; a log that keeps only
+ * what succeeded has thrown it away.
+ *
+ * `atSec`, not `atMs`. Seconds match the TTL indexes the retention policy runs
+ * on, and mixing the two units in one collection has produced records expiring
+ * a thousand times too early more than once.
+ */
+export declare function audit<K extends string>(options: AuditOptions<K>): Effect<K>;
+export interface OutboxEvent {
+    type: string;
+    route: string;
+    payload: Record<string, unknown>;
+    realm?: string;
+    atSec: number;
+}
+export interface Outbox {
+    publish(event: OutboxEvent): void | Promise<void>;
+}
+export interface EmitOptions<K extends string> extends Routes<K> {
+    outbox: Outbox;
+    type: string;
+    payload: (context: RequestContext, result: unknown, state: State) => Record<string, unknown> | undefined;
+    /** Emit on refusals too. Off by default — a failed attempt is not an event. */
+    onDenied?: boolean;
+}
+/**
+ * Announce that something happened.
+ *
+ * Named `emit`, not `webhook` or `publish`, because the transport is the
+ * outbox's business: same call whether it ends up in a queue, a webhook or a
+ * websocket fan-out. A route that knows it is sending a webhook is a route that
+ * has to change when the transport does.
+ *
+ * `payload` returning undefined skips the event — the honest way to express "an
+ * update that changed nothing is not news".
+ */
+export declare function emit<K extends string>(options: EmitOptions<K>): Effect<K>;
+export interface UsageMeter {
+    record(usage: {
+        realm?: string;
+        userKey?: string;
+        unit: string;
+        quantity: number;
+        route: string;
+        atSec: number;
+    }): void | Promise<void>;
+}
+export interface MeterOptions<K extends string> extends Routes<K> {
+    meter: UsageMeter;
+    unit: string;
+    /** Defaults to 1 — one call, one unit. */
+    quantity?: (context: RequestContext, result: unknown, state: State) => number;
+}
+/**
+ * Count billable usage — successes only.
+ *
+ * Metering a refused request bills a customer for being told no, which is the
+ * kind of thing that ends up in a support thread and then a refund. It is also
+ * the default a naive implementation lands on, because the after-chain runs on
+ * denials too.
+ */
+export declare function meter<K extends string>(options: MeterOptions<K>): Effect<K>;
+export interface CacheInvalidator {
+    drop(keys: readonly string[]): void | Promise<void>;
+}
+export interface InvalidateOptions<K extends string> extends Routes<K> {
+    cache: CacheInvalidator;
+    keys: (context: RequestContext, state: State) => readonly string[];
+}
+/**
+ * Drop what this write made stale — successes only.
+ *
+ * Invalidating after a refusal is harmless and wasteful; invalidating after a
+ * `Settled` replay is neither, since the first attempt already did it. Both are
+ * cheap to get wrong and free to get right by classifying once.
+ */
+export declare function invalidate<K extends string>(options: InvalidateOptions<K>): Effect<K>;
+export interface Notification {
+    to: string;
+    template: string;
+    data: Record<string, unknown>;
+    realm?: string;
+}
+export interface Notifier {
+    send(notification: Notification): void | Promise<void>;
+}
+export interface NotifyOptions<K extends string> extends Routes<K> {
+    notifier: Notifier;
+    template: string;
+    to: (context: RequestContext, result: unknown, state: State) => string | undefined;
+    data?: (context: RequestContext, result: unknown, state: State) => Record<string, unknown>;
+    onDenied?: boolean;
+}
+/**
+ * Tell somebody. Queued like every effect, never awaited.
+ *
+ * `onDenied` exists for one real case: a failed sign-in or a refused withdrawal
+ * is exactly what the account holder wants to hear about, and it is the only
+ * signal they get that somebody else has their password.
+ */
+export declare function notify<K extends string>(options: NotifyOptions<K>): Effect<K>;
+export {};