@forgezero/access 0.1.1 → 0.1.3

package/dist/principal.js

@@ -0,0 +1,366 @@
+// 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, accessGroup: "default", ...options };
+}
+function action(label, method, options = {}) {
+  return { kind: "action", label, method, accessGroup: "default", ...options };
+}
+function defineRoutes(routes) {
+  for (const [key, route] of Object.entries(routes)) {
+    if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
+      throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
+    }
+    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?.factors.length ?? 0) === 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/principal.ts
+var ATOM = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,255}$/;
+var GROUP = /^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/;
+var METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+function uniqueAtoms(values, max, pattern = ATOM) {
+  return values.length <= max && new Set(values).size === values.length && values.every((value) => pattern.test(value));
+}
+function defineRbacPrincipal(principal) {
+  if (!ATOM.test(principal.kind) || !ATOM.test(principal.principalKey) || principal.assignments.length > 32) {
+    throw new AccessError("PRINCIPAL_INVALID", "The principal kind, key, or assignment count is invalid.");
+  }
+  const assignmentKeys = new Set;
+  for (const assignment of principal.assignments) {
+    if (!ATOM.test(assignment.assignmentKey) || assignmentKeys.has(assignment.assignmentKey) || !uniqueAtoms(assignment.roleKeys, 128) || !uniqueAtoms(assignment.accessGroups, 32, GROUP) || !uniqueAtoms(assignment.sessionFactors, 32) || assignment.methods.length === 0 || assignment.methods.length > METHODS.size || new Set(assignment.methods).size !== assignment.methods.length || assignment.methods.some((method) => !METHODS.has(method))) {
+      throw new AccessError("PRINCIPAL_ASSIGNMENT_INVALID", "A principal assignment is malformed, duplicate, or unbounded.");
+    }
+    if (assignment.idleTtlMs === undefined !== (assignment.lastActiveAtMs === undefined) || assignment.idleTtlMs !== undefined && (!Number.isSafeInteger(assignment.idleTtlMs) || assignment.idleTtlMs <= 0) || assignment.lastActiveAtMs !== undefined && (!Number.isSafeInteger(assignment.lastActiveAtMs) || assignment.lastActiveAtMs < 0) || assignment.absoluteExpiresAtMs !== undefined && (!Number.isSafeInteger(assignment.absoluteExpiresAtMs) || assignment.absoluteExpiresAtMs < 0)) {
+      throw new AccessError("PRINCIPAL_ASSIGNMENT_INVALID", "Assignment expiry coordinates are incomplete or invalid.");
+    }
+    if (assignment.delegatedBy && (!ATOM.test(assignment.delegatedBy.userKey) || !ATOM.test(assignment.delegatedBy.sessionKey) || !Number.isSafeInteger(assignment.delegatedBy.atMs))) {
+      throw new AccessError("PRINCIPAL_ASSIGNMENT_INVALID", "Assignment delegation binding is invalid.");
+    }
+    assignmentKeys.add(assignment.assignmentKey);
+  }
+  return principal;
+}
+function assignmentIsActive(assignment, now = Date.now()) {
+  if (assignment.absoluteExpiresAtMs !== undefined && now >= assignment.absoluteExpiresAtMs)
+    return false;
+  if (assignment.idleTtlMs !== undefined && assignment.lastActiveAtMs !== undefined && now >= assignment.lastActiveAtMs + assignment.idleTtlMs)
+    return false;
+  return true;
+}
+function touchPrincipalAssignment(assignment, now = Date.now()) {
+  if (!assignmentIsActive(assignment, now) || assignment.idleTtlMs === undefined)
+    return assignment;
+  return { ...assignment, lastActiveAtMs: now };
+}
+function decidePrincipalAccess(args) {
+  const route = args.access.get(args.routeKey);
+  if (!route || !args.access.exists(args.routeKey, { stage: args.stage, realm: args.realm }) || route.kind === "action" && args.method !== undefined && route.method !== args.method) {
+    return { allow: false, status: 404, code: "NOT_FOUND" };
+  }
+  if (route.accessGroup === "public")
+    return { allow: true, public: true };
+  if (!args.principal)
+    return { allow: false, status: 401, code: "AUTH_REQUIRED" };
+  const principal = defineRbacPrincipal(args.principal);
+  const policy = args.access.sessionPolicyFor(args.routeKey);
+  const requiredFactors = policy?.factors ?? [];
+  let missing;
+  for (const assignment of principal.assignments) {
+    if (!assignmentIsActive(assignment, args.now) || !assignment.accessGroups.includes(route.accessGroup) || route.kind === "action" && !assignment.methods.includes(route.method))
+      continue;
+    const absent = requiredFactors.filter((factor) => !assignment.sessionFactors.includes(factor));
+    if (absent.length > 0) {
+      missing = missing === undefined ? absent : [...new Set([...missing, ...absent])];
+      continue;
+    }
+    const grants = args.roles.filter((role) => assignment.roleKeys.includes(role.roleKey)).flatMap((role) => role.grants);
+    if (!grantsRoute(grants, args.routeKey, {
+      mode: route.grantMode,
+      sharesGrantWith: route.sharesGrantWith
+    }))
+      continue;
+    const action2 = args.access.actionPolicyFor(args.routeKey);
+    if (action2 && !args.actionProofSatisfied) {
+      return {
+        allow: false,
+        status: 428,
+        code: "ACTION_REQUIRED",
+        missing: action2.factors,
+        required: action2.required
+      };
+    }
+    return { allow: true, public: false, assignmentKey: assignment.assignmentKey };
+  }
+  if (missing?.length)
+    return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
+  return { allow: false, status: 403, code: "ACCESS_DENIED" };
+}
+export {
+  touchPrincipalAssignment,
+  defineRbacPrincipal,
+  decidePrincipalAccess,
+  assignmentIsActive
+};

package/dist/testing.js

@@ -60,13 +60,16 @@ function defineFactors(factors) {
   return factors;
 }
 function page(label, options = {}) {
-  return { kind: "page", label, ...options };
+  return { kind: "page", label, accessGroup: "default", ...options };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, ...options };
+  return { kind: "action", label, method, accessGroup: "default", ...options };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
+      throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
+    }
     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/.`);
@@ -242,11 +245,11 @@ function authorise(args) {
     return { allow: false, status: 404, code: "NOT_FOUND" };
   }
   const policy = access.sessionPolicyFor(routeKey);
-  if (!policy || policy.factors.length === 0)
+  if ((policy?.factors.length ?? 0) === 0)
     return { allow: true };
   if (!session)
     return { allow: false, status: 401, code: "AUTH_REQUIRED" };
-  const missing = policy.factors.filter((factor) => !session.factors.includes(factor));
+  const missing = (policy?.factors ?? []).filter((factor) => !session.factors.includes(factor));
   if (missing.length > 0) {
     return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/access",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -39,6 +39,18 @@
       "types": "./dist/security.d.ts",
       "default": "./dist/security.js"
     },
+    "./header": {
+      "types": "./dist/header.d.ts",
+      "default": "./dist/header.js"
+    },
+    "./principal": {
+      "types": "./dist/principal.d.ts",
+      "default": "./dist/principal.js"
+    },
+    "./principal-session": {
+      "types": "./dist/principal-session.d.ts",
+      "default": "./dist/principal-session.js"
+    },
     "./conditions": {
       "types": "./dist/conditions.d.ts",
       "default": "./dist/conditions.js"
@@ -59,7 +71,7 @@
 	"scripts": {
 		"check": "tsc --noEmit",
 		"prebuild": "rm -rf dist",
-    "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",
+    "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/header.ts src/principal.ts src/principal-session.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": {