// `mosaic access list|grant|revoke` (federation design section 3.5, FED R5, #414). // The human edits /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 /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, `.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`; }