@forgezero/access 0.1.0

package/dist/testing.js

@@ -0,0 +1,357 @@
+// 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/testing.ts
+function nameOf(policies, route) {
+  for (const [name, policy] of Object.entries(policies ?? {})) {
+    if (policy.routes.includes(route))
+      return name;
+  }
+  return;
+}
+function simulate(access, args, registries) {
+  const session = args.as ? typeof args.as === "string" ? { userKey: "simulated", roleKeys: [args.as], factors: sessionFactorsFor(access, args.route) } : {
+    userKey: "simulated",
+    roleKeys: args.as.roleKeys,
+    factors: args.as.factors ?? sessionFactorsFor(access, args.route)
+  } : undefined;
+  const outcome = authorise({
+    access,
+    routeKey: args.route,
+    stage: args.stage,
+    realm: args.realm,
+    session,
+    roles: args.roles ?? []
+  });
+  const actionPolicy = access.actionPolicyFor(args.route);
+  const sessionPolicyName = nameOf(registries?.sessionPolicies, args.route);
+  const actionPolicyName = nameOf(registries?.actionPolicies, args.route);
+  if (!outcome.allow) {
+    return {
+      allowed: false,
+      status: outcome.status === 429 ? 403 : outcome.status,
+      reason: outcome.code,
+      sessionPolicy: sessionPolicyName,
+      actionPolicy: actionPolicyName,
+      missingFactors: outcome.missing,
+      requiresStepUp: Boolean(actionPolicy)
+    };
+  }
+  if (actionPolicy && args.enabledFactors) {
+    const { satisfiable, available } = resolveActionFactors(actionPolicy, args.enabledFactors);
+    if (!satisfiable) {
+      return {
+        allowed: false,
+        status: 403,
+        reason: "FACTORS_UNAVAILABLE",
+        sessionPolicy: sessionPolicyName,
+        actionPolicy: actionPolicyName,
+        missingFactors: actionPolicy.factors.filter((factor) => !available.includes(factor)),
+        requiresStepUp: true
+      };
+    }
+  }
+  return {
+    allowed: true,
+    status: 200,
+    reason: "ALLOWED",
+    sessionPolicy: sessionPolicyName,
+    actionPolicy: actionPolicyName,
+    requiresStepUp: Boolean(actionPolicy)
+  };
+}
+function sessionFactorsFor(access, route) {
+  return access.sessionPolicyFor(route)?.factors ?? [];
+}
+function reachableRoutes(access, roles, roleKeys, context = {}) {
+  return access.keys().filter((key) => simulate(access, {
+    route: key,
+    roles,
+    as: { roleKeys },
+    stage: context.stage,
+    realm: context.realm
+  }).allowed);
+}
+function unreachableRoutes(access, roles) {
+  const everyRole = roles.map((role) => role.roleKey);
+  const reachable = new Set(reachableRoutes(access, roles, everyRole));
+  return access.keys().filter((key) => !reachable.has(key));
+}
+export {
+  unreachableRoutes,
+  simulate,
+  reachableRoutes
+};

package/package.json

@@ -0,0 +1,93 @@
+{
+  "//": "Publishing happens from an operator's machine, not CI \u2014 CLAUDE.md records that the absence of CI is deliberate. npm's `provenance` attests a tarball was built by a recognised CI provider from a named commit, so it cannot be produced here: it was set, and the first publish failed with `Automatic provenance generation not supported for provider: null`. A setting that can never be satisfied is worse than none, because it reads as a guarantee nobody is getting. Restore it the day this publishes from CI, and not before.",
+  "name": "@forgezero/access",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./fetch": {
+      "types": "./dist/fetch.d.ts",
+      "default": "./dist/fetch.js"
+    },
+    "./pipeline": {
+      "types": "./dist/pipeline.d.ts",
+      "default": "./dist/pipeline.js"
+    },
+    "./elysia": {
+      "types": "./dist/elysia.d.ts",
+      "default": "./dist/elysia.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./rate-limit": {
+      "types": "./dist/rate-limit.d.ts",
+      "default": "./dist/rate-limit.js"
+    },
+    "./security": {
+      "types": "./dist/security.d.ts",
+      "default": "./dist/security.js"
+    },
+    "./conditions": {
+      "types": "./dist/conditions.d.ts",
+      "default": "./dist/conditions.js"
+    },
+    "./effects": {
+      "types": "./dist/effects.d.ts",
+      "default": "./dist/effects.js"
+    },
+    "./authenticator": {
+      "types": "./dist/authenticator.d.ts",
+      "default": "./dist/authenticator.js"
+    },
+    "./ceremony-modes": {
+      "types": "./dist/ceremony-modes.d.ts",
+      "default": "./dist/ceremony-modes.js"
+    }
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "bun build src/index.ts src/fetch.ts src/pipeline.ts src/elysia.ts src/client.ts src/testing.ts src/rate-limit.ts src/security.ts src/conditions.ts src/effects.ts src/authenticator.ts src/ceremony-modes.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
+    "prepublishOnly": "bun run check && bun run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/bun": "latest"
+  },
+  "description": "Route matrix, RBAC and security factors. Zero runtime dependencies \u2014 runs anywhere fetch does.",
+  "keywords": [
+    "rbac",
+    "authorization",
+    "permissions",
+    "routes",
+    "webauthn",
+    "passkey",
+    "mfa"
+  ],
+  "license": "MIT",
+  "homepage": "https://forgezero.net/docs/access",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/axxra/forgezero.git",
+    "directory": "packages/access"
+  },
+  "bugs": "https://github.com/axxra/forgezero/issues",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}