business: 193a access level check widened to viewer (row 204, #1702)

Squash of Morgana's 7f07da4aa..f869fd062 on origin/morgana/row193a (diff
from R1's candidate 44e36fc4c), the three manifest paths, manifest d38de8c9
(Duckworth approve, comment 29595). LEVELS gains collaborator and viewer,
covers() takes a required least level, and an unknown grant level covers
nothing. Gate on base 4385b9ec1 with the patch: packages and
scripts/test-*.sh 2789 pass 0 fail. Refactor moved to c9f374284 since, a
SESSIONS line only. Mutants 7 of 7 killed (agents/morgana/work/queue-193a/
mutants.log on the branch). No live change.

packages/business/src/access.mjs

@@ -10,8 +10,9 @@ import { refuse } from "./errors.mjs";
 import { configDir } from "./business.mjs";
 import { isPlainObject, requireObject, rejectUnknownKeys, requireId, requirePositiveInt, readJsonFile, deepFreeze } from "./util.mjs";
 
-// The grant levels. Row 193a widens this to collaborator and viewer.
-export const LEVELS = Object.freeze(["collaborator"]);
+// The grant levels, most to least (row 193a, #1691): a viewer reads threads shared with it and drives
+// no instance. covers() relies on this order.
+export const LEVELS = Object.freeze(["collaborator", "viewer"]);
 // Ids a user may never take: the bus's own principals.
 const RESERVED_USERS = Object.freeze(["human", "tester"]);
 const LOCAL_HOME = "local";
@@ -172,14 +173,18 @@ export function loadAccess(file, context, { uid = process.getuid() } = {}) {
 }
 
 // Does a checked grant cover a thread? `target` is the thread's business, bus
-// project id and instance. With `level`, the grant's level must be that one;
-// without it, any level covers. An expired grant covers nothing.
+// project id and instance. `level` is required (row 193a, Duckworth's N1 on R1):
+// it is the least level the action needs (LEVELS runs from most to least), so `viewer` asks for
+// read and any grant covers it, while `collaborator` asks to drive the instance
+// and a viewer grant never covers it. An expired grant covers nothing.
 export function covers(grant, { business, project, instance }, now, { level } = {}) {
   if (!(now instanceof Date) || Number.isNaN(now.getTime())) throw new TypeError("covers needs a valid Date for now");
+  if (!LEVELS.includes(level)) throw new TypeError(`covers needs a level, one of ${LEVELS.join(", ")} (got ${JSON.stringify(level)})`);
   if (grant.expires !== undefined && now.getTime() >= Date.parse(grant.expires)) return false;
   if (grant.business !== business) return false;
   if (!(grant.projects[0] === ALL || grant.projects.includes(project))) return false;
   if (!(grant.instances[0] === ALL || grant.instances.includes(instance))) return false;
-  if (level !== undefined && grant.level !== level) return false;
+  // A grant whose own level is unknown covers nothing, even if it skipped checkAccess.
+  if (!LEVELS.includes(grant.level) || LEVELS.indexOf(grant.level) > LEVELS.indexOf(level)) return false;
   return true;
 }

packages/business/tests/access-levels.test.mjs

@@ -0,0 +1,81 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { BusinessError } from "../src/errors.mjs";
+import * as access from "../src/access.mjs";
+
+// Row 193a (#1691): the viewer level. R1 (federation design r4.5, section 7) owns access.mjs and its
+// tests; this file pins only what row 193 adds: a grant's level is collaborator or viewer, and covers()
+// tells the two apart with a required least level. Every call into R1 goes through check() below, so a change to R1's loader
+// interface edits one place.
+const CONTEXT = {
+  providers: ["authentik"],
+  peers: ["factory"],
+  businesses: { "creative-hub": { human: "melanie", instances: ["researcher", "writer"] } },
+  ssoSubjects: [],
+};
+const check = (doc) => access.checkAccess(doc, CONTEXT);
+
+const PROJECT = "0b6f4a52-6f1e-4c7a-9a0e-3f1d2c4b5a69";
+const NOW = new Date("2026-10-20T19:30:00Z");
+
+function file(level) {
+  const grant = { id: "g-1", user: "jason", business: "creative-hub", projects: ["*"], instances: ["researcher"] };
+  if (level !== undefined) grant.level = level;
+  return {
+    accessVersion: 1,
+    revision: 1,
+    users: [{ id: "jason", home: "local", subjects: [{ provider: "authentik", sub: "s-1" }] }],
+    grants: [grant],
+  };
+}
+
+function refuses(fn, pattern) {
+  assert.throws(fn, (error) => {
+    assert.ok(error instanceof BusinessError, `expected BusinessError, got ${error}`);
+    assert.equal(error.exitCode, 2);
+    assert.match(error.message, pattern);
+    return true;
+  });
+}
+
+test("a grant's level is collaborator or viewer", () => {
+  for (const level of ["collaborator", "viewer"]) {
+    assert.doesNotThrow(() => check(file(level)), level);
+  }
+});
+
+test("any other level refuses with the key path named", () => {
+  for (const level of ["owner", "admin", "member", "Viewer", "viewer ", "", null, 1, ["viewer"], undefined]) {
+    refuses(() => check(file(level)), /grants\[0\]\.level/);
+  }
+});
+
+test("covers tells a viewer grant from a collaborator grant", () => {
+  const target = { business: "creative-hub", project: PROJECT, instance: "researcher" };
+  const viewer = file("viewer").grants[0];
+  const collaborator = file("collaborator").grants[0];
+  // The level is the least one the action needs: share reads ask viewer; create, open, send and share ask
+  // collaborator (design 9).
+  assert.equal(access.covers(viewer, target, NOW, { level: "viewer" }), true);
+  assert.equal(access.covers(viewer, target, NOW, { level: "collaborator" }), false);
+  assert.equal(access.covers(collaborator, target, NOW, { level: "viewer" }), true);
+  assert.equal(access.covers(collaborator, target, NOW, { level: "collaborator" }), true);
+});
+
+test("covers refuses a call with no level, so a viewer grant can't slip past a collaborator check", () => {
+  const target = { business: "creative-hub", project: PROJECT, instance: "researcher" };
+  const viewer = file("viewer").grants[0];
+  assert.throws(() => access.covers(viewer, target, NOW), TypeError);
+  assert.throws(() => access.covers(viewer, target, NOW, {}), TypeError);
+});
+
+test("a viewer grant still needs its business, project, instance and expiry to cover", () => {
+  const viewer = { ...file("viewer").grants[0], projects: [PROJECT], expires: "2026-10-21T00:00:00Z" };
+  const target = { business: "creative-hub", project: PROJECT, instance: "researcher" };
+  const read = { level: "viewer" };
+  assert.equal(access.covers(viewer, target, NOW, read), true);
+  assert.equal(access.covers(viewer, { ...target, business: "other" }, NOW, read), false);
+  assert.equal(access.covers(viewer, { ...target, project: "7c1e2d3f-0a9b-4c8d-8e7f-6a5b4c3d2e1f" }, NOW, read), false);
+  assert.equal(access.covers(viewer, { ...target, instance: "writer" }, NOW, read), false);
+  assert.equal(access.covers(viewer, target, new Date("2026-10-21T00:00:01Z"), read), false);
+});

packages/business/tests/access.test.mjs

@@ -70,8 +70,8 @@ test("checkAccess does not freeze or alias the caller's document", () => {
   assert.notEqual(checked.grants, d.grants);
 });
 
-test("LEVELS is the single allowed level set, collaborator only", () => {
-  assert.deepEqual([...LEVELS], ["collaborator"]);
+test("LEVELS is the single allowed level set, collaborator and viewer (row 193a)", () => {
+  assert.deepEqual([...LEVELS], ["collaborator", "viewer"]);
   assert.ok(Object.isFrozen(LEVELS));
 });
 
@@ -168,11 +168,11 @@ test("grants: instances is [\"*\"] or distinct declared instances of that busine
   assert.ok(checkAccess(mutated((d) => { d.grants[0].instances = ["researcher", "writer"]; }), context()));
 });
 
-test("grants: any level other than collaborator refuses, naming grants[i].level", () => {
-  for (const bad of ["viewer", "owner", "Collaborator", "COLLABORATOR", "", null, 1]) {
-    refuses(() => checkAccess(mutated((d) => { d.grants[1].level = bad; }), context()), /grants\[1\]\.level must be one of collaborator/);
+test("grants: any level other than collaborator or viewer refuses, naming grants[i].level", () => {
+  for (const bad of ["owner", "Collaborator", "COLLABORATOR", "Viewer", "", null, 1]) {
+    refuses(() => checkAccess(mutated((d) => { d.grants[1].level = bad; }), context()), /grants\[1\]\.level must be one of collaborator, viewer/);
   }
-  refuses(() => checkAccess(mutated((d) => { delete d.grants[0].level; }), context()), /grants\[0\]\.level must be one of collaborator \(got undefined\)/);
+  refuses(() => checkAccess(mutated((d) => { delete d.grants[0].level; }), context()), /grants\[0\]\.level must be one of collaborator, viewer \(got undefined\)/);
 });
 
 test("grants: expires is optional ISO time, and a past expiry is not refused", () => {
@@ -240,41 +240,61 @@ test("loadAccess refuses bad JSON and a bad document with exit 2", () => {
 
 const NOW = new Date("2026-10-20T12:00:00Z");
 const target = (over = {}) => ({ business: "creative-hub", project: P1, instance: "researcher", ...over });
+// Any level reads: the least level is viewer (row 193a).
+const READ = { level: "viewer" };
 
 test("covers: * and listed ids match", () => {
   const [g1, g2] = checkAccess(doc(), context()).grants;
-  assert.equal(covers(g1, target({ project: P2 }), NOW), true);
-  assert.equal(covers(g2, target({ instance: "writer" }), NOW), true);
-  assert.equal(covers(g2, target(), NOW), true);
+  assert.equal(covers(g1, target({ project: P2 }), NOW, READ), true);
+  assert.equal(covers(g2, target({ instance: "writer" }), NOW, READ), true);
+  assert.equal(covers(g2, target(), NOW, READ), true);
 });
 
 test("covers: an unlisted project, instance or business doesn't match", () => {
   const [g1, g2] = checkAccess(doc(), context()).grants;
-  assert.equal(covers(g2, target({ project: P2 }), NOW), false);
-  assert.equal(covers(g1, target({ instance: "writer" }), NOW), false);
-  assert.equal(covers(g2, target({ business: "acme" }), NOW), false);
-  assert.equal(covers(g1, target({ business: "acme" }), NOW), false);
+  assert.equal(covers(g2, target({ project: P2 }), NOW, READ), false);
+  assert.equal(covers(g1, target({ instance: "writer" }), NOW, READ), false);
+  assert.equal(covers(g2, target({ business: "acme" }), NOW, READ), false);
+  assert.equal(covers(g1, target({ business: "acme" }), NOW, READ), false);
 });
 
 test("covers: an expired grant doesn't match, at and after the instant", () => {
   const [g1, g2] = checkAccess(doc(), context()).grants;
-  assert.equal(covers(g1, target(), new Date("2026-12-30T23:59:59.999Z")), true);
-  assert.equal(covers(g1, target(), new Date("2026-12-31T00:00:00Z")), false);
-  assert.equal(covers(g1, target(), new Date("2027-01-01T00:00:00Z")), false);
+  assert.equal(covers(g1, target(), new Date("2026-12-30T23:59:59.999Z"), READ), true);
+  assert.equal(covers(g1, target(), new Date("2026-12-31T00:00:00Z"), READ), false);
+  assert.equal(covers(g1, target(), new Date("2027-01-01T00:00:00Z"), READ), false);
   // No expires never expires.
-  assert.equal(covers(g2, target(), new Date("2099-01-01T00:00:00Z")), true);
+  assert.equal(covers(g2, target(), new Date("2099-01-01T00:00:00Z"), READ), true);
 });
 
-test("covers: a level filter rejects another level, and no filter accepts any", () => {
+test("covers: level is the least level asked for (row 193a)", () => {
   const g = checkAccess(doc(), context()).grants[0];
+  const v = { ...g, level: "viewer" };
   assert.equal(covers(g, target(), NOW, { level: "collaborator" }), true);
-  assert.equal(covers(g, target(), NOW, {}), true);
-  assert.equal(covers(g, target(), NOW, { level: "viewer" }), false);
-  assert.equal(covers({ ...g, level: "viewer" }, target(), NOW, { level: "collaborator" }), false);
+  assert.equal(covers(g, target(), NOW, READ), true);
+  assert.equal(covers(v, target(), NOW, READ), true);
+  assert.equal(covers(v, target(), NOW, { level: "collaborator" }), false);
+});
+
+test("covers: a missing or unknown level throws (row 193a, N1)", () => {
+  const v = { ...checkAccess(doc(), context()).grants[0], level: "viewer" };
+  assert.throws(() => covers(v, target(), NOW), TypeError);
+  assert.throws(() => covers(v, target(), NOW, {}), TypeError);
+  assert.throws(() => covers(v, target(), NOW, { level: undefined }), TypeError);
+  for (const bad of ["owner", "Viewer", "", null, 1]) {
+    assert.throws(() => covers(v, target(), NOW, { level: bad }), /covers needs a level, one of collaborator, viewer/);
+  }
+});
+
+test("covers: a grant with an unknown level covers nothing (row 193a)", () => {
+  const g = checkAccess(doc(), context()).grants[0];
+  for (const bad of ["owner", "Collaborator", undefined]) {
+    assert.equal(covers({ ...g, level: bad }, target(), NOW, READ), false);
+  }
 });
 
 test("covers: now must be a valid Date", () => {
   const g = checkAccess(doc(), context()).grants[0];
-  assert.throws(() => covers(g, target(), Date.now()), TypeError);
-  assert.throws(() => covers(g, target(), new Date("nope")), TypeError);
+  assert.throws(() => covers(g, target(), Date.now(), READ), TypeError);
+  assert.throws(() => covers(g, target(), new Date("nope"), READ), TypeError);
 });