@forgezero/access 0.1.0

package/dist/effects.js

@@ -0,0 +1,505 @@
+// 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/security.ts
+var HEX = Array.from({ length: 256 }, (_, index) => index.toString(16).padStart(2, "0"));
+function toHex(bytes) {
+  let out = "";
+  for (const byte of bytes)
+    out += HEX[byte];
+  return out;
+}
+function fromHex(hex) {
+  if (hex.length % 2 !== 0)
+    throw new Error("Hex string must have an even length.");
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let index = 0;index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+function toBase64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(value) {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(padded + "=".repeat((4 - padded.length % 4) % 4));
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let difference = 0;
+  for (let index = 0;index < a.length; index += 1) {
+    difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return difference === 0;
+}
+function randomToken(bytes = 32) {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  return toBase64Url(buffer);
+}
+function randomHex(bytes = 32) {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  return toHex(buffer);
+}
+function randomDigits(length = 6) {
+  let digits = "";
+  for (let index = 0;index < length; index += 1)
+    digits += randomInt(10).toString();
+  return digits;
+}
+function randomInt(max) {
+  if (max <= 0 || max > 256)
+    throw new Error("randomInt supports 1..256.");
+  const limit = Math.floor(256 / max) * max;
+  const buffer = new Uint8Array(1);
+  for (;; ) {
+    crypto.getRandomValues(buffer);
+    if (buffer[0] < limit)
+      return buffer[0] % max;
+  }
+}
+async function sha256(input) {
+  const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return toHex(new Uint8Array(digest));
+}
+var hashToken = sha256;
+async function hmacSha256(key, message) {
+  const keyBytes = typeof key === "string" ? new TextEncoder().encode(key) : key;
+  const imported = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const signature = await crypto.subtle.sign("HMAC", imported, new TextEncoder().encode(message));
+  return toHex(new Uint8Array(signature));
+}
+async function verifyHmac(key, message, signature) {
+  return timingSafeEqual(await hmacSha256(key, message), signature);
+}
+async function hkdf(secret, info, length = 32, salt = new Uint8Array(32)) {
+  const key = await crypto.subtle.importKey("raw", secret, "HKDF", false, ["deriveBits"]);
+  const bits = await crypto.subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt, info: new TextEncoder().encode(info) }, key, length * 8);
+  return new Uint8Array(bits);
+}
+async function seal(key, plaintext, aad) {
+  const iv = new Uint8Array(12);
+  crypto.getRandomValues(iv);
+  const imported = await crypto.subtle.importKey("raw", key, "AES-GCM", false, ["encrypt"]);
+  const ciphertext = await crypto.subtle.encrypt({
+    name: "AES-GCM",
+    iv,
+    ...aad ? { additionalData: new TextEncoder().encode(aad) } : {}
+  }, imported, new TextEncoder().encode(plaintext));
+  return { iv: toBase64Url(iv), ciphertext: toBase64Url(new Uint8Array(ciphertext)) };
+}
+async function open(key, sealed, aad) {
+  const imported = await crypto.subtle.importKey("raw", key, "AES-GCM", false, ["decrypt"]);
+  const plaintext = await crypto.subtle.decrypt({
+    name: "AES-GCM",
+    iv: fromBase64Url(sealed.iv),
+    ...aad ? { additionalData: new TextEncoder().encode(aad) } : {}
+  }, imported, fromBase64Url(sealed.ciphertext));
+  return new TextDecoder().decode(plaintext);
+}
+var nowSeconds = () => Math.floor(Date.now() / 1000);
+var isLive = (expiresAtSec, at = nowSeconds()) => expiresAtSec > at;
+var SECRET_NAME = /token|secret|password|passphrase|credential|authorization|cookie|apikey|api_key|private/i;
+function redact(value) {
+  const out = {};
+  for (const [name, entry] of Object.entries(value)) {
+    if (SECRET_NAME.test(name))
+      out[name] = "[redacted]";
+    else if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+      out[name] = redact(entry);
+    } else
+      out[name] = entry;
+  }
+  return out;
+}
+// src/effects.ts
+function settlementOf(result) {
+  if (isSettled(result))
+    return { outcome: "settled", status: result.status, result: result.value };
+  if (isRefusal(result))
+    return { outcome: "denied", status: result.status, code: result.code, result };
+  if (result instanceof Error)
+    return { outcome: "error", status: 500, code: "INTERNAL", result };
+  if (result instanceof Response)
+    return { outcome: result.ok ? "allowed" : "denied", status: result.status, result };
+  return { outcome: "allowed", status: 200, result };
+}
+function define(effect, routes, run) {
+  return {
+    effect,
+    routes,
+    run(context, result, state) {
+      try {
+        run(context, result, state);
+      } catch {}
+    }
+  };
+}
+function audit(options) {
+  const target = options.target ?? "targetId";
+  return define("audit", options.routes, (context, result, state) => {
+    const settlement = settlementOf(result);
+    const detail = options.detail?.(context, state, settlement);
+    options.sink.write({
+      route: context.route,
+      method: context.method,
+      outcome: settlement.outcome,
+      status: settlement.status,
+      code: settlement.code,
+      userKey: context.session?.userKey,
+      realm: context.realm,
+      targetKey: typeof state[target] === "string" ? state[target] : undefined,
+      atSec: Math.floor(Date.now() / 1000),
+      ...detail ? { detail: redact(detail) } : {}
+    });
+  });
+}
+function emit(options) {
+  return define("emit", options.routes, (context, result, state) => {
+    const settlement = settlementOf(result);
+    if (settlement.outcome !== "allowed" && !options.onDenied)
+      return;
+    const payload = options.payload(context, settlement.result, state);
+    if (!payload)
+      return;
+    options.outbox.publish({
+      type: options.type,
+      route: context.route,
+      payload: redact(payload),
+      realm: context.realm,
+      atSec: Math.floor(Date.now() / 1000)
+    });
+  });
+}
+function meter(options) {
+  return define("meter", options.routes, (context, result, state) => {
+    const settlement = settlementOf(result);
+    if (settlement.outcome !== "allowed")
+      return;
+    const quantity = options.quantity?.(context, settlement.result, state) ?? 1;
+    if (quantity <= 0)
+      return;
+    options.meter.record({
+      realm: context.realm,
+      userKey: context.session?.userKey,
+      unit: options.unit,
+      quantity,
+      route: context.route,
+      atSec: Math.floor(Date.now() / 1000)
+    });
+  });
+}
+function invalidate(options) {
+  return define("invalidate", options.routes, (context, result, state) => {
+    if (settlementOf(result).outcome !== "allowed")
+      return;
+    const keys = options.keys(context, state);
+    if (keys.length > 0)
+      options.cache.drop(keys);
+  });
+}
+function notify(options) {
+  return define("notify", options.routes, (context, result, state) => {
+    const settlement = settlementOf(result);
+    if (settlement.outcome !== "allowed" && !options.onDenied)
+      return;
+    const to = options.to(context, settlement.result, state);
+    if (!to)
+      return;
+    options.notifier.send({
+      to,
+      template: options.template,
+      data: redact(options.data?.(context, settlement.result, state) ?? {}),
+      realm: context.realm
+    });
+  });
+}
+export {
+  settlementOf,
+  notify,
+  meter,
+  invalidate,
+  emit,
+  audit
+};

package/dist/elysia.d.ts

@@ -0,0 +1,78 @@
+import { type PipelineOptions } from './pipeline';
+import type { RouteRegistry } from './index';
+/**
+ * Elysia adapter.
+ *
+ * Glue over the shared pipeline, not a second implementation. Its whole job is
+ * to hand Elysia's matched route to `createPipeline` and turn the answer back
+ * into something Elysia returns.
+ *
+ * ## Two things that go wrong quietly
+ *
+ * **`.as('global')`.** Without it a guard silently does not run for routes
+ * mounted by a plugin — the most common way an Elysia security layer appears to
+ * work and does not. Every route registered here is inside this plugin, so the
+ * scope must be global or the plugin only guards itself.
+ *
+ * **`context.route`, not `context.path`.** Elysia exposes the matched PATTERN.
+ * Matching on the path makes `api/orders/[id]` a different route per id, which
+ * breaks grants, rate limits and step-up binding simultaneously and looks like
+ * nothing is wrong until an id changes.
+ *
+ * Route keys use `[id]`; Elysia uses `:id`. The translation happens here so a
+ * tenant writes one convention across every adapter.
+ */
+/** `api/orders/[id]/refund` → `/api/orders/:id/refund` */
+export declare function toElysiaPath(routeKey: string): string;
+/** Minimal shape of what we need from Elysia, so this file imports nothing. */
+interface ElysiaLike {
+    route(method: string, path: string, handler: (context: ElysiaContext) => unknown): ElysiaLike;
+    as?(scope: 'global' | 'scoped'): ElysiaLike;
+}
+interface ElysiaContext {
+    request: Request;
+    params?: Record<string, string>;
+    route?: string;
+}
+export interface ElysiaAdapterOptions<R extends RouteRegistry> extends PipelineOptions<R> {
+    /**
+     * Elysia constructor. Passed in rather than imported so this package keeps
+     * its zero-dependency claim — a project not using Elysia pulls none of it.
+     */
+    Elysia: new (options?: {
+        prefix?: string;
+        name?: string;
+    }) => ElysiaLike;
+    prefix?: string;
+}
+/**
+ * Build an Elysia plugin that mounts every action route through the pipeline.
+ *
+ * Pages are not mounted: they are UI surface, and the matrix knows about them so
+ * navigation can be generated from the same source the API enforces.
+ */
+export declare function elysia<R extends RouteRegistry>(options: ElysiaAdapterOptions<R>): ElysiaLike;
+/**
+ * OpenTelemetry bridge.
+ *
+ * Elysia emits its own HTTP spans; these nest inside them so a trace reads
+ * request → access decision → handler rather than two unrelated trees.
+ *
+ * `record` deliberately refuses anything that looks like a credential. A span
+ * exporter is an exfiltration path nobody thinks about, and an attribute named
+ * `token` reaches a third-party backend as plainly as a log line would.
+ */
+declare const FORBIDDEN_ATTRIBUTE: RegExp;
+export interface OtelTracer {
+    startActiveSpan<T>(name: string, options: {
+        attributes?: Record<string, unknown>;
+    }, run: (span: {
+        setAttributes(attributes: Record<string, unknown>): void;
+        end(): void;
+    }) => Promise<T>): Promise<T>;
+}
+export declare function telemetryFrom(tracer: OtelTracer): {
+    span<T>(name: string, attributes: Record<string, unknown>, run: () => Promise<T>): Promise<T>;
+    record(attributes: Record<string, unknown>): void;
+};
+export { FORBIDDEN_ATTRIBUTE as forbiddenTelemetryAttribute };