stack/packages/cli/src/access.mjs

// `mosaic access list|grant|revoke` (federation design section 3.5, FED R5, #414).
// The human edits <configDir>/access.json here. Each write is checked against the
// instance's context before it lands, bumps the revision by one, and appends one
// receipt line to <dataRoot>/state/access-log.jsonl. The human proof is one call
// through humanTransport: a bus that does not see a human shell refuses it, so
// no agent and no tester can write. The context (providers, peers, businesses,
// ssoSubjects) comes in as a function; the caller decides where it comes from.

import { appendFileSync, mkdirSync, readdirSync, readFileSync, renameSync, openSync, writeSync, fsyncSync, closeSync, existsSync, unlinkSync } from "node:fs";
import { randomBytes } from "node:crypto";
import { join, dirname } from "node:path";
import { BusinessError, accessFilePath, checkAccess, configDir, loadAccess, loadBusiness, LEVELS } from "../../business/src/index.mjs";
import { rolesDir } from "./config.mjs";
import { CliError } from "./errors.mjs";
import { refuseInsideAgent } from "./transport.mjs";

export const ACCESS_USAGE = [
  "mosaic access list --business ID [--json]",
  "mosaic access grant --business ID --user ID --projects UUID|NAME,...|* --instances NAME,...|* --level collaborator|viewer [--expires ISO] --revision N",
  "mosaic access revoke --business ID --user ID [--grant GID] --revision N",
].join("\n");

// The help text. A grant's `instances` is the real limit: the granted instance
// runs with the owner's role, so a collaborator drives it with that authority.
// Removing a user acts at once. Removing a provider from console.sso waits for a
// Console restart, so take the users out of access.json first. Peer homes are
// empty until the federation key lands (row 203), so a grant naming a peer
// home refuses until then. A grant naming a subject needs console.sso.
export const ACCESS_HELP = `${ACCESS_USAGE}

A grant gives a user exactly what the granted instances can do. The instances
list is the real limit: a collaborator's message drives a granted instance with
the owner's role.
To cut a user off, revoke them here first. It acts at once. Removing a provider
from console.sso takes effect only after a Console restart, so do that second.
Peer homes are not read yet (row 203 adds the federation key), so a grant that
names a peer home refuses. A grant that names a sign-in subject needs console.sso
in the system config; without it every such grant refuses.
The command runs as the instance's uid: access.json must belong to it and must
not be writable by group or other, or the command refuses (exit 3) and writes nothing.`;

// The instance's context for checkAccess, read from the system config and the business
// files. providers and ssoSubjects come from console.sso (row 192's shape: each provider
// has an id and a subjects list). peers is empty until row 203. A business file that
// fails to load fails the whole command.
export function accessContextFor(system, env) {
  const providers = system.console?.sso?.providers ?? [];
  const ssoSubjects = providers.flatMap((p) => p.subjects.map((s) => ({ provider: p.id, sub: s.sub })));
  const dir = join(configDir(env), "businesses");
  const businesses = {};
  if (existsSync(dir)) {
    for (const file of readdirSync(dir).filter((f) => f.endsWith(".json")).sort()) {
      const id = file.slice(0, -".json".length);
      const doc = loadBusiness(id, { dir: configDir(env), rolesDir: rolesDir(env) });
      businesses[id] = { human: doc.human, instances: Object.keys(doc.roles) };
    }
  }
  return { providers: providers.map((p) => p.id), peers: [], businesses, ssoSubjects };
}

// Every verb needs --business: the human proof runs through that business's bus.
// --tester is refused outright on every verb, before any bus call.
function parse(args) {
  const out = { positional: [], flags: new Set(), values: {} };
  for (let i = 0; i < args.length; i++) {
    const a = args[i];
    if (a === "--json" || a === "--tester") out.flags.add(a);
    else if (a.startsWith("--")) {
      if (i + 1 >= args.length || args[i + 1].startsWith("--")) throw new CliError(`${a} needs one value\n${ACCESS_USAGE}`, 4);
      out.values[a] = args[++i];
    } else out.positional.push(a);
  }
  return out;
}

const list = (value) => (value === "*" ? ["*"] : value.split(",").filter(Boolean));

function readCurrent(file, context) {
  if (!existsSync(file)) return { document: { accessVersion: 1, revision: null, users: [], grants: [] }, revision: 0 };
  const document = loadAccess(file, context);
  return { document, revision: document.revision };
}

// The file calls the write path makes. A test passes a stand-in through deps.fs.
const realFs = { openSync, writeSync, fsyncSync, closeSync, renameSync, unlinkSync };

// Atomic write: a temp file in the same directory, 0600, fsynced, then renamed over
// the old file. A reader sees the old bytes or the new bytes, never a mix. A failure
// before or at the rename removes the temp file and leaves the old bytes in place.
function writeAtomic(file, text, fs = realFs) {
  const tmp = join(dirname(file), `.access-${randomBytes(8).toString("hex")}.tmp`);
  try {
    const fd = fs.openSync(tmp, "wx", 0o600);
    try {
      fs.writeSync(fd, text);
      fs.fsyncSync(fd);
    } finally {
      fs.closeSync(fd);
    }
    fs.renameSync(tmp, file);
  } catch (error) {
    try {
      fs.unlinkSync(tmp);
    } catch {
      // Already gone: the temp file was never created.
    }
    throw error;
  }
}

function receipt(dataRoot, line) {
  const dir = join(dataRoot, "state");
  mkdirSync(dir, { recursive: true });
  appendFileSync(join(dir, "access-log.jsonl"), `${JSON.stringify(line)}\n`, { mode: 0o600 });
}

// Two writers never interleave: the read, the check and the rename happen under an
// exclusive lock file, `<access.json>.lock`, mode 0600. The file holds the holder's
// pid and a newline. A lock whose holder is alive refuses. A lock that is empty,
// unreadable, or whose pid is gone also refuses, and nothing reclaims it: a human
// removes it once no write is running. Fail closed, with no reclaim race.
const BUSY = "refused: the access file is being written by another command; try again";

function lockPid(lock) {
  let text;
  try {
    text = readFileSync(lock, "utf8");
  } catch {
    return null;
  }
  const pid = Number(text.trim());
  return Number.isSafeInteger(pid) && pid >= 1 ? pid : null;
}

function pidAlive(pid) {
  try {
    process.kill(pid, 0);
    return true;
  } catch (error) {
    return error.code !== "ESRCH";
  }
}

function lockRefusal(lock) {
  const pid = lockPid(lock);
  if (pid !== null && pidAlive(pid)) return BUSY;
  if (pid === null) return `refused: lock ${lock} is unreadable or not a pid; if no write is running, remove it by hand and try again`;
  return `refused: lock ${lock} is left by pid ${pid}, which is not running; if no write is running, remove it by hand and try again`;
}

function takeLock(lock, fs) {
  try {
    return fs.openSync(lock, "wx", 0o600);
  } catch (error) {
    if (error.code !== "EEXIST") throw error;
  }
  throw new CliError(lockRefusal(lock), 3);
}

export function withLock(file, fn, fs = realFs) {
  const lock = `${file}.lock`;
  const fd = takeLock(lock, fs);
  try {
    fs.writeSync(fd, `${process.pid}\n`);
  } finally {
    fs.closeSync(fd);
  }
  try {
    return fn();
  } finally {
    fs.unlinkSync(lock);
  }
}

// The one human-proof call: project.list, which the bus gates with #human
// (broker.mjs:2319, and #human at :377). It also returns the rows that resolve
// project names. Row R4 swaps this call for access.reload.
async function proveHuman(transport, business) {
  return transport(business)("project.list", {});
}

// Resolve a --projects item: "*" and UUIDs pass through, anything else is a project
// name looked up in project.list at grant time (the id is what gets written).
function resolveProjects(items, rows) {
  return items.map((item) => {
    if (item === "*" || /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(item)) return item;
    const hits = rows.filter((r) => r.name === item);
    if (hits.length !== 1) throw new CliError(`refused: project-not-found: no project named ${item} in this business (or the name is ambiguous)`, 2);
    return hits[0].id;
  });
}

// deps: { system: { dataRoot }, transport(business) -> call(verb, args), contextFor() -> context, configDir?, now?, fs? }
export async function accessCommand(args, io, deps) {
  refuseInsideAgent(io.env);
  try {
    return await accessVerb(args, io, deps);
  } catch (error) {
    // A file or business doc the checks refuse to load (group-writable, a wrong uid, a
    // hand edit) is a refusal with exit 3 and the file and key path, not a crash.
    if (error instanceof BusinessError) throw new CliError(`refused: ${error.message}`, 3);
    throw error;
  }
}

async function accessVerb(args, io, deps) {
  const parsed = parse(args);
  const sub = parsed.positional[0];
  if (!["list", "grant", "revoke"].includes(sub) || parsed.positional.length !== 1) throw new CliError(ACCESS_HELP, 4);
  if (parsed.flags.has("--tester")) throw new CliError("refused: access writes take the human's shell, not --tester", 3);
  const business = parsed.values["--business"];
  if (!business) throw new CliError(`--business is required\n${ACCESS_USAGE}`, 4);

  const rows = await proveHuman(deps.transport, business);
  const file = deps.file ?? accessFilePath(deps.configDir ?? configDir(io.env));
  // Built after the human proof, so a refused caller never reads the business files.
  const context = deps.contextFor();

  if (sub === "list") {
    const { document } = readCurrent(file, context);
    io.stdout.write(parsed.flags.has("--json") ? `${JSON.stringify(document, null, 2)}\n` : formatList(document));
    return;
  }

  const expected = parsed.values["--revision"];
  if (!/^\d+$/.test(expected ?? "")) throw new CliError(`--revision takes the revision you read\n${ACCESS_USAGE}`, 4);
  const user = parsed.values["--user"];
  if (!user) throw new CliError(`${sub} needs --user\n${ACCESS_USAGE}`, 4);

  const result = withLock(file, () => {
    const { document, revision } = readCurrent(file, context);
    if (Number(expected) !== revision) {
      throw new CliError(`refused: revision-conflict: the access file is at revision ${revision}, not ${expected}; run list again`, 3);
    }
    let next;
    let touched;
    if (sub === "grant") {
      const level = parsed.values["--level"];
      if (!parsed.values["--projects"] || !parsed.values["--instances"] || level === undefined) {
        throw new CliError(`grant needs --projects, --instances and --level\n${ACCESS_USAGE}`, 4);
      }
      if (!LEVELS.includes(level)) throw new CliError(`--level takes ${LEVELS.join(", ")}`, 2);
      const id = `g-${randomBytes(4).toString("hex")}`;
      const grant = {
        id,
        user,
        business,
        projects: resolveProjects(list(parsed.values["--projects"]), rows),
        instances: list(parsed.values["--instances"]),
        level,
      };
      if (parsed.values["--expires"] !== undefined) grant.expires = parsed.values["--expires"];
      touched = [id];
      next = { ...document, revision: revision + 1, grants: [...document.grants, grant] };
    } else {
      const only = parsed.values["--grant"];
      const drop = (g) => g.user === user && g.business === business && (only === undefined || g.id === only);
      touched = document.grants.filter(drop).map((g) => g.id);
      if (touched.length === 0) throw new CliError(`refused: no grant for ${user} at ${business} to revoke`, 2);
      next = { ...document, revision: revision + 1, grants: document.grants.filter((g) => !drop(g)) };
    }
    // Every check runs on the new document before a byte is written.
    const checked = checkAccess(next, context);
    writeAtomic(file, `${JSON.stringify(checked, null, 2)}\n`, deps.fs);
    return { checked, revision, touched };
  }, deps.fs);

  receipt(deps.system.dataRoot, {
    at: (deps.now ?? (() => new Date()))().toISOString(),
    verb: sub,
    business,
    user,
    actor: "human",
    revisionBefore: result.revision,
    revisionAfter: result.checked.revision,
    grants: result.touched,
  });
  io.stdout.write(`access ${sub}: ${result.touched.join(", ")} at ${business}, revision ${result.checked.revision}\n`);
}

function formatList(doc) {
  const lines = [`access file revision ${doc.revision ?? "none"}`];
  for (const u of doc.users) lines.push(`user ${u.id} home ${u.home}`);
  for (const g of doc.grants) {
    lines.push(`grant ${g.id} user ${g.user} business ${g.business} projects ${g.projects.join(",")} instances ${g.instances.join(",")} level ${g.level}${g.expires ? ` expires ${g.expires}` : ""}`);
  }
  return `${lines.join("\n")}\n`;
}