@forgezero/access 0.1.0

package/dist/fetch.js

@@ -0,0 +1,587 @@
+// 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/pipeline.ts
+function defineHandlers(routes, handlers) {
+  for (const key of Object.keys(handlers)) {
+    if (!(key in routes)) {
+      throw new AccessError("HANDLER_UNKNOWN_ROUTE", `Handler "${key}" is not a route.`);
+    }
+    if (routes[key].kind !== "action") {
+      throw new AccessError("HANDLER_ON_PAGE", `"${key}" is a page; only actions take handlers.`);
+    }
+  }
+  return handlers;
+}
+var WINDOWS = { s: 1, m: 60, h: 3600, d: 86400 };
+function windowSeconds(window) {
+  const match = /^(\d+)([smhd])$/.exec(window);
+  if (!match)
+    throw new AccessError("RATE_WINDOW_INVALID", `"${window}" is not a window like 30s, 1m, 15m, 1h, 1d.`);
+  return Number(match[1]) * WINDOWS[match[2]];
+}
+var problem = (status, code, message, extra = {}) => new Response(JSON.stringify({ ok: false, error: { code, message }, ...extra }), {
+  status,
+  headers: { "content-type": "application/json" }
+});
+var outcomeResponse = (outcome) => {
+  const headers = { "content-type": "application/json" };
+  if (outcome.status === 428) {
+    headers["x-security-mode"] = "session";
+    if (outcome.missing)
+      headers["x-security-required"] = outcome.missing.join(",");
+  }
+  return new Response(JSON.stringify({
+    ok: false,
+    error: { code: outcome.code, message: refusalMessage(outcome.status) },
+    ...outcome.missing ? { missing: outcome.missing } : {}
+  }), { status: outcome.status, headers });
+};
+function refusalMessage(status) {
+  switch (status) {
+    case 404:
+      return "Not found.";
+    case 401:
+      return "Sign in to continue.";
+    case 403:
+      return "Your role cannot perform this action.";
+    case 428:
+      return "Complete the required security check to continue.";
+    case 429:
+      return "Too many requests. Try again shortly.";
+    default:
+      return "Refused.";
+  }
+}
+function createPipeline(options) {
+  const {
+    access,
+    handlers,
+    session: resolveSession,
+    rateStore,
+    validator,
+    stepUp,
+    telemetry,
+    validateResponses = false
+  } = options;
+  return async function run(request, routeKey, params = {}) {
+    const url = new URL(request.url);
+    const stage = options.stage?.();
+    const realm = options.realm?.(request);
+    const record = (attributes) => telemetry?.record(attributes);
+    record({ "access.route": routeKey, "access.realm": realm, "access.stage": stage });
+    if (!access.exists(routeKey, { stage, realm })) {
+      record({ "access.outcome": "denied", "access.status": 404, "access.reason": "not_found" });
+      return problem(404, "NOT_FOUND", "Not found.");
+    }
+    const route = access.get(routeKey);
+    const session = await resolveSession?.(request);
+    const roles = await access.source?.roles() ?? [];
+    const outcome = authorise({ access, routeKey, stage, realm, session, roles });
+    if (!outcome.allow) {
+      record({
+        "access.outcome": "denied",
+        "access.status": outcome.status,
+        "access.reason": outcome.code,
+        "access.policy": outcome.policy
+      });
+      return outcomeResponse(outcome);
+    }
+    const rate = access.ratePolicyFor(routeKey);
+    if (rate && rateStore) {
+      const subject = rate.by === "session" ? session?.userKey ?? "anon" : rate.by === "realm" ? realm ?? "none" : rate.by === "apiKey" ? request.headers.get("x-api-key") ?? "none" : request.headers.get("x-forwarded-for") ?? "unknown";
+      const allowed = await rateStore.take(`${routeKey}:${rate.by}:${subject}`, rate.limit, windowSeconds(rate.window));
+      if (!allowed) {
+        record({ "access.outcome": "denied", "access.status": 429, "access.reason": "rate_limited" });
+        return problem(429, "RATE_LIMITED", refusalMessage(429));
+      }
+    }
+    let body;
+    const query = Object.fromEntries(url.searchParams);
+    if (validator) {
+      const checks = [];
+      if (route.params)
+        checks.push(["params", route.params, params]);
+      if (route.query)
+        checks.push(["query", route.query, query]);
+      if (route.headers)
+        checks.push(["headers", route.headers, Object.fromEntries(request.headers)]);
+      if (route.body) {
+        body = await request.json().catch(() => {
+          return;
+        });
+        checks.push(["body", route.body, body]);
+      }
+      for (const [where, schema, value] of checks) {
+        const result2 = validator.validate(schema, value);
+        if (!result2.ok) {
+          record({ "access.outcome": "denied", "access.status": 422, "access.reason": `invalid_${where}` });
+          return problem(422, "INVALID_REQUEST", `The ${where} did not match what this route accepts.`, {
+            errors: result2.errors
+          });
+        }
+        if (where === "body")
+          body = result2.value;
+      }
+    } else if (route.body) {
+      body = await request.json().catch(() => {
+        return;
+      });
+    }
+    const context = {
+      route: routeKey,
+      method: route.method,
+      url,
+      params,
+      query,
+      body,
+      headers: request.headers,
+      session,
+      realm,
+      stage,
+      ok: (value) => new Response(JSON.stringify(value), { headers: { "content-type": "application/json" } })
+    };
+    const state = {};
+    const completed = [];
+    const before = access.beforeFor(routeKey);
+    let failure;
+    for (let index = 0;index < before.length; index += 1) {
+      try {
+        Object.assign(state, await before[index].run(context, state) ?? {});
+        completed.push(index);
+      } catch (error) {
+        failure = error;
+        break;
+      }
+    }
+    const runAfter = (result2) => {
+      queueMicrotask(() => {
+        for (const handler2 of [...access.afterFor(routeKey)].reverse()) {
+          try {
+            handler2.run(context, result2, state);
+          } catch {}
+        }
+      });
+    };
+    if (failure) {
+      runAfter(failure);
+      if (isSettled(failure)) {
+        record({ "access.outcome": "settled", "access.status": failure.status });
+        return failure.value instanceof Response ? failure.value : new Response(failure.status === 204 ? null : JSON.stringify(failure.value), {
+          status: failure.status,
+          headers: { "content-type": "application/json", ...failure.headers }
+        });
+      }
+      if (isRefusal(failure)) {
+        record({
+          "access.outcome": "denied",
+          "access.status": failure.status,
+          "access.reason": failure.code
+        });
+        return problem(failure.status, failure.code, failure.message, {
+          ...failure.details,
+          ...failure.retryable ? { retryable: true } : {}
+        });
+      }
+      record({ "access.outcome": "error", "access.reason": "before_threw" });
+      return problem(500, "INTERNAL", "The request could not be completed.");
+    }
+    const actionPolicy = access.actionPolicyFor(routeKey);
+    if (actionPolicy && session) {
+      const enabled = await access.source?.enabledFactors() ?? actionPolicy.factors;
+      const { satisfiable, available } = resolveActionFactors(actionPolicy, enabled);
+      if (!satisfiable) {
+        record({ "access.outcome": "denied", "access.status": 403, "access.reason": "factors_unavailable" });
+        return problem(403, "FACTORS_UNAVAILABLE", "A required security method is not enabled on this account.");
+      }
+      const presented = request.headers.get("x-security-request-key");
+      const targetKey = typeof body?.id === "string" ? body.id : undefined;
+      const consumed = presented && stepUp ? await stepUp.consume(presented, { route: routeKey, method: route.method, targetKey }) : false;
+      if (!consumed) {
+        const key = stepUp ? await stepUp.issue({
+          route: routeKey,
+          method: route.method,
+          target: actionPolicy.target,
+          targetKey,
+          userKey: session.userKey,
+          factors: available,
+          required: actionPolicy.required
+        }) : "";
+        record({ "access.outcome": "denied", "access.status": 428, "access.reason": "step_up_required" });
+        return new Response(JSON.stringify({
+          ok: false,
+          error: { code: "SECURITY_REQUIRED", message: refusalMessage(428) },
+          security: {
+            scope: "action",
+            route: routeKey,
+            factors: available,
+            required: actionPolicy.required,
+            satisfied: fulfilledActionFactors()
+          }
+        }), {
+          status: 428,
+          headers: {
+            "content-type": "application/json",
+            "x-security-mode": "action",
+            "x-security-request-key": key,
+            "x-security-required": available.join(",")
+          }
+        });
+      }
+    }
+    const handler = handlers[routeKey];
+    if (!handler) {
+      return problem(501, "NOT_IMPLEMENTED", "This route has no handler.");
+    }
+    const result = await (telemetry ? telemetry.span("handler", { "access.route": routeKey }, async () => handler(context, state)) : handler(context, state));
+    if (validateResponses && validator && route.response) {
+      const schema = route.response[200];
+      if (schema && !(result instanceof Response)) {
+        const check = validator.validate(schema, result);
+        if (!check.ok) {
+          throw new AccessError("RESPONSE_MISMATCH", `"${routeKey}" returned a shape it does not declare: ${check.errors[0]?.message}`);
+        }
+      }
+    }
+    runAfter(result);
+    record({ "access.outcome": "allowed", "access.status": 200 });
+    return result instanceof Response ? result : new Response(JSON.stringify(result), { headers: { "content-type": "application/json" } });
+  };
+}
+
+// src/fetch.ts
+function compile(key, route) {
+  return {
+    key,
+    method: route.method,
+    segments: key.split("/").map((segment) => {
+      const rest = /^\[\.\.\.(\w+)\]$/.exec(segment);
+      if (rest)
+        return { name: rest[1], rest: true };
+      const named = /^\[(\w+)\]$/.exec(segment);
+      return named ? { name: named[1] } : { literal: segment };
+    })
+  };
+}
+function match(compiled, method, path) {
+  const parts = path.replace(/^\/+|\/+$/g, "").split("/");
+  const scored = [...compiled].sort((a, b) => b.segments.filter((s) => s.literal).length - a.segments.filter((s) => s.literal).length);
+  for (const route of scored) {
+    if (route.method !== method)
+      continue;
+    const params = {};
+    let matched = true;
+    for (let index = 0;index < route.segments.length; index += 1) {
+      const segment = route.segments[index];
+      if (segment.rest) {
+        params[segment.name] = parts.slice(index).join("/");
+        return { key: route.key, params };
+      }
+      const part = parts[index];
+      if (part === undefined) {
+        matched = false;
+        break;
+      }
+      if (segment.literal !== undefined) {
+        if (segment.literal !== part) {
+          matched = false;
+          break;
+        }
+      } else {
+        params[segment.name] = decodeURIComponent(part);
+      }
+    }
+    if (matched && parts.length === route.segments.length)
+      return { key: route.key, params };
+  }
+  return;
+}
+function toFetch(options) {
+  const run = createPipeline(options);
+  const compiled = options.access.keys().map((key) => [key, options.access.get(key)]).filter(([, route]) => route?.kind === "action").map(([key, route]) => compile(key, route));
+  return async function handle(request) {
+    const found = match(compiled, request.method, new URL(request.url).pathname);
+    if (!found) {
+      return new Response(JSON.stringify({ ok: false, error: { code: "NOT_FOUND", message: "Not found." } }), { status: 404, headers: { "content-type": "application/json" } });
+    }
+    return run(request, found.key, found.params);
+  };
+}
+export {
+  toFetch,
+  match as matchRoute,
+  compile as compileRoute
+};