@rubytech/create-maxy-code 0.1.353 → 0.1.355

package/payload/platform/lib/admins-write/src/index.ts

@@ -19,7 +19,7 @@
 // returns is_error: true with the [admins-write] line; set-pin returns 500
 // with the same). Same trust model as the [admin-auth-store] pair.
 
-import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, readdirSync, statSync, appendFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 export interface UserEntry {
@@ -27,6 +27,71 @@ export interface UserEntry {
   pin: string; // SHA-256 hash
 }
 
+/**
+ * Identity + destination for one credential-store audit line. The writer is
+ * pure (it only knows the file paths); the caller is the only party that knows
+ * WHO is acting and WHERE the audit log lives, so it is threaded in. `actor` is
+ * an admin userId or a non-user sentinel (`onboarding` | `install` | `boot` |
+ * `unknown` when an MCP caller has no resolvable USER_ID); `session` is the
+ * spawning agent session (SESSION_NODE_ID) when one drove the write. `logFile`
+ * is the absolute path to the append-only users-audit log, distinct from
+ * server.log. Mirrored in platform/lib/admin-access-password.
+ */
+export interface AuditContext {
+  actor: string;
+  session?: string;
+  logFile: string;
+}
+
+/** First 8 chars — the short-id convention used across the auth logs. */
+function id8(value: string): string {
+  return value.slice(0, 8);
+}
+
+/** Format a userId list as the comma-joined short-id set used in audit lines.
+ *  Exported for direct users.json writers that do not route through
+ *  writeAdminEntry (the MCP admin-update-pin path). */
+export function formatAuditRowIds(userIds: string[]): string {
+  return userIds.map(id8).join(",");
+}
+
+/**
+ * Append one canonical `[users-audit]` line. Append failures never propagate —
+ * an audit-write fault must not break the credential write it records; the
+ * fault is surfaced once on stderr instead.
+ */
+function appendUsersAuditLine(
+  audit: AuditContext,
+  fields: { action: string; field: string; rowsBefore: string; rowsAfter: string },
+): void {
+  const sess = audit.session ? ` session=${id8(audit.session)}` : "";
+  // userIds are uuids (shortened to id8); sentinels (boot|install|onboarding|
+  // unknown) carry no dash and are written whole so attribution stays readable.
+  const actor = audit.actor.includes("-") ? id8(audit.actor) : audit.actor;
+  const line =
+    `[users-audit] action=${fields.action} actor=${actor}${sess} ` +
+    `field=${fields.field} rowsBefore=${fields.rowsBefore} rowsAfter=${fields.rowsAfter} ` +
+    `ts=${new Date().toISOString()}\n`;
+  try {
+    mkdirSync(dirname(audit.logFile), { recursive: true, mode: 0o700 });
+    appendFileSync(audit.logFile, line, { mode: 0o600 });
+  } catch (err) {
+    console.error(
+      `[users-audit] op=write-failed logFile=${audit.logFile} error=${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+/** Public wrapper so a direct users.json writer that cannot route through
+ *  writeAdminEntry (the MCP admin-update-pin path) still emits the one
+ *  canonical `[users-audit]` line, keeping every write covered. */
+export function logUsersAudit(
+  audit: AuditContext,
+  fields: { action: string; field: string; rowsBefore: string; rowsAfter: string },
+): void {
+  appendUsersAuditLine(audit, fields);
+}
+
 export interface AdminEntry {
   userId: string;
   role: "owner" | "admin";
@@ -39,6 +104,7 @@ export interface AdminWriteInput {
   usersFile: string;    // absolute path to users.json
   accountDir: string;   // absolute path to account dir (containing account.json)
   caller: string;       // identifier for the [admins-write] log line
+  audit: AuditContext;  // actor/session/logFile for the [users-audit] line
 }
 
 export interface AdminWriteResult {
@@ -93,6 +159,7 @@ export function writeAdminEntry(input: AdminWriteInput): AdminWriteResult {
       }
     }
 
+    const rowsBefore = users.map(u => id8(u.userId)).join(",");
     const existing = users.findIndex(u => u.userId === input.userId);
     if (existing === -1) {
       users.push({ userId: input.userId, pin: input.pin });
@@ -103,6 +170,13 @@ export function writeAdminEntry(input: AdminWriteInput): AdminWriteResult {
 
     writeFileAtomic(input.usersFile, JSON.stringify(users, null, 2) + "\n", 0o600);
     result.usersJsonResult = "ok";
+    // A new userId is a row add; an existing userId is a pin rotation.
+    appendUsersAuditLine(input.audit, {
+      action: existing === -1 ? "add" : "set-pin",
+      field: existing === -1 ? "row" : "pin",
+      rowsBefore,
+      rowsAfter: users.map(u => id8(u.userId)).join(","),
+    });
   } catch (err) {
     result.usersJsonResult = "fail";
     result.usersError = err instanceof Error ? err.message : String(err);
@@ -139,6 +213,7 @@ export interface AdminRemoveInput {
   userId: string;
   accountDir: string;
   caller: string;
+  audit: AuditContext;  // actor/session/logFile for the [users-audit] line
 }
 
 export interface AdminRemoveResult {
@@ -163,6 +238,7 @@ export function removeAdminFromAccount(input: AdminRemoveInput): AdminRemoveResu
     }
     const config = JSON.parse(readFileSync(accountJsonPath, "utf-8")) as Record<string, unknown>;
     const admins = (config.admins ?? []) as AdminEntry[];
+    const rowsBefore = admins.map(a => id8(a.userId)).join(",");
     const targetIndex = admins.findIndex(a => a.userId === input.userId);
     if (targetIndex === -1) {
       result.accountJsonResult = "noop";
@@ -171,6 +247,13 @@ export function removeAdminFromAccount(input: AdminRemoveInput): AdminRemoveResu
       config.admins = admins;
       writeFileAtomic(accountJsonPath, JSON.stringify(config, null, 2) + "\n");
       result.accountJsonResult = "ok";
+      // Removal touches account.json admins[] only; the row-set is that store's.
+      appendUsersAuditLine(input.audit, {
+        action: "remove",
+        field: "row",
+        rowsBefore,
+        rowsAfter: admins.map(a => id8(a.userId)).join(","),
+      });
     }
   } catch (err) {
     result.accountJsonResult = "fail";
@@ -202,29 +285,29 @@ export interface InvariantCheckResult {
   usersWithoutAccount: Array<{ userId: string }>;
 }
 
+/** Pure divergence computation — read faults collected, never logged. */
+export interface DivergenceResult {
+  divergences: number;
+  /** Userids in account.json admins[] that have no row in users.json. */
+  accountWithoutUsers: Array<{ userId: string; source: string }>;
+  /** Userids in users.json that no account.json admins[] references. */
+  usersWithoutAccount: Array<{ userId: string }>;
+  /** Read faults encountered during the walk (unreadable users/account file). */
+  errors: Array<{ source: string; detail: string }>;
+}
+
 /**
  * Walk every account.json under accountsDir and compare its admins[] to
- * users.json. Emits one log line per divergence and one summary line.
- *
- * Behaviour: log-only — does NOT throw, does NOT refuse boot or install.
- * Pre-Task-904 installs that already diverged would otherwise brick on the
- * first boot of a Task-904 device. The summary line `divergences=<n>` is
- * always emitted (wired-up assertion); per-divergence lines fire only when
- * divergences > 0. Operators grep `[install-invariant]` or `[admin-invariant]`
- * to detect the regression class without reading every install log.
- *
- * Promotion to refuse-or-degrade is a future sprint; capture as a TODO once
- * the deployed fleet has been audited clean.
+ * users.json. PURE: returns the divergence sets and any read faults; does no
+ * logging and never throws. Shared by `checkAdminAuthInvariant` (the
+ * `[admin-invariant]` boot one-shot) and the `[users-reconcile]` standing tick
+ * so the two never disagree on the predicate. An absent users.json or accounts
+ * dir is a legitimate first-boot state → empty set, not a fault.
  */
-export function checkAdminAuthInvariant(input: InvariantCheckInput): InvariantCheckResult {
-  const result: InvariantCheckResult = {
-    divergences: 0,
-    accountWithoutUsers: [],
-    usersWithoutAccount: [],
-  };
+export function computeAdminStoreDivergence(input: { usersFile: string; accountsDir: string }): DivergenceResult {
+  const result: DivergenceResult = { divergences: 0, accountWithoutUsers: [], usersWithoutAccount: [], errors: [] };
 
-  // Read users.json userIds (persistent file). Absent file == empty set; do
-  // not abort — first-boot before set-pin has run is a legitimate state.
+  // Read users.json userIds (persistent file). Absent file == empty set.
   const usersUserIds = new Set<string>();
   if (existsSync(input.usersFile)) {
     try {
@@ -236,8 +319,7 @@ export function checkAdminAuthInvariant(input: InvariantCheckInput): InvariantCh
         }
       }
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.error(`[${input.tag}] users.json unreadable usersFile=${input.usersFile} error=${msg}`);
+      result.errors.push({ source: input.usersFile, detail: err instanceof Error ? err.message : String(err) });
     }
   }
 
@@ -248,9 +330,7 @@ export function checkAdminAuthInvariant(input: InvariantCheckInput): InvariantCh
     try {
       entries = readdirSync(input.accountsDir);
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.error(`[${input.tag}] accounts-dir unreadable accountsDir=${input.accountsDir} error=${msg}`);
-      console.error(`[${input.tag}] check complete divergences=0 (accounts-dir unreadable)`);
+      result.errors.push({ source: input.accountsDir, detail: err instanceof Error ? err.message : String(err) });
       return result;
     }
 
@@ -269,8 +349,7 @@ export function checkAdminAuthInvariant(input: InvariantCheckInput): InvariantCh
         const config = JSON.parse(readFileSync(accountJsonPath, "utf-8")) as Record<string, unknown>;
         admins = (config.admins ?? []) as AdminEntry[];
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        console.error(`[${input.tag}] account.json unreadable source=${accountJsonPath} error=${msg}`);
+        result.errors.push({ source: accountJsonPath, detail: err instanceof Error ? err.message : String(err) });
         continue;
       }
 
@@ -278,10 +357,6 @@ export function checkAdminAuthInvariant(input: InvariantCheckInput): InvariantCh
         if (typeof a.userId !== "string") continue;
         accountUserIds.add(a.userId);
         if (!usersUserIds.has(a.userId)) {
-          const userIdShort = a.userId.slice(0, 8);
-          console.error(
-            `[${input.tag}] direction=account-without-users userId=${userIdShort} source=${accountJsonPath}`,
-          );
           result.accountWithoutUsers.push({ userId: a.userId, source: accountJsonPath });
           result.divergences += 1;
         }
@@ -291,15 +366,37 @@ export function checkAdminAuthInvariant(input: InvariantCheckInput): InvariantCh
 
   for (const uid of usersUserIds) {
     if (!accountUserIds.has(uid)) {
-      const userIdShort = uid.slice(0, 8);
-      console.error(
-        `[${input.tag}] direction=users-without-account userId=${userIdShort} source=${input.usersFile}`,
-      );
       result.usersWithoutAccount.push({ userId: uid });
       result.divergences += 1;
     }
   }
 
-  console.error(`[${input.tag}] check complete divergences=${result.divergences}`);
   return result;
 }
+
+/**
+ * `[admin-invariant]` / `[install-invariant]` boot one-shot. Wraps the pure
+ * `computeAdminStoreDivergence` and emits the documented grep lines:
+ * `direction=…`, the per-fault unreadable line, and the always-emitted
+ * `check complete divergences=<n>` summary. Log-only — does NOT throw, does NOT
+ * refuse boot or install. The recurring standing check is the separate
+ * `[users-reconcile]` tick in the admin server boot.
+ */
+export function checkAdminAuthInvariant(input: InvariantCheckInput): InvariantCheckResult {
+  const d = computeAdminStoreDivergence({ usersFile: input.usersFile, accountsDir: input.accountsDir });
+  for (const e of d.errors) {
+    console.error(`[${input.tag}] unreadable source=${e.source} error=${e.detail}`);
+  }
+  for (const a of d.accountWithoutUsers) {
+    console.error(`[${input.tag}] direction=account-without-users userId=${a.userId.slice(0, 8)} source=${a.source}`);
+  }
+  for (const u of d.usersWithoutAccount) {
+    console.error(`[${input.tag}] direction=users-without-account userId=${u.userId.slice(0, 8)} source=${input.usersFile}`);
+  }
+  console.error(`[${input.tag}] check complete divergences=${d.divergences}`);
+  return {
+    divergences: d.divergences,
+    accountWithoutUsers: d.accountWithoutUsers,
+    usersWithoutAccount: d.usersWithoutAccount,
+  };
+}

package/payload/platform/plugins/admin/PLUGIN.md

@@ -126,6 +126,10 @@ Tools are available via the `admin` MCP server.
 
 **Three-store admin auth invariant.** `admin-add` writes to all three identity stores (`users.json` PIN auth at the persistent `~/{configDir}/users.json` location , `account.json` `admins[]` role, Neo4j `:AdminUser`/`:Person` graph identity) with per-leg `[admin-auth-store]` log lines plus the `[admins-write]` chokepoint line, and returns `is_error: true` on any leg failure naming what's already written. `admin-update-pin` writes `users.json` only and emits the same `[admin-auth-store]` line. **Single chokepoint:** every `users.json` + `account.json admins[]` mutation routes through `platform/lib/admins-write` (`writeAdminEntry` for admin-add/set-pin, `removeAdminFromAccount` for admin-remove); the static check `grep -rnE 'admins\.push\|config\.admins\s*=' platform/ \| grep -v lib/admins-write` returns 0. Direct `Edit`/`Write` on `account.json` is forbidden by IDENTITY.md doctrine — mutations go through `account-update`, `plugin-toggle-enabled`, or the `admin-*` tools. **Install + boot invariants:** the installer and admin-server boot walk every account.json admins[] vs users.json; `[install-invariant]` / `[admin-invariant] direction=… userId=<id8> source=<file>` fires per divergence with a `check complete divergences=<n>` summary. Log-only — does not block. See `.docs/agents.md` § "Three-store admin auth invariant" for the full contract.
 
+**Credential audit trail (append-only).** Every write to the credential stores emits one canonical `[users-audit] action=<set-access|clear-access|add|remove|set-pin|migrate> actor=<id8|onboarding|install|boot|unknown> [session=<id8>] field=<accessHash|pin|row> rowsBefore=<id8,…> rowsAfter=<id8,…> ts=<iso>` line to `~/{configDir}/logs/users-audit.log` — a dedicated file, distinct from `server.log`, so a credential mutation is greppable in isolation. The line is emitted at the writer chokepoint (`admin-access-password` for accessHash set/clear/migrate, `admins-write` `writeAdminEntry`/`removeAdminFromAccount` for row/pin/role) so every caller is covered; the one direct users.json writer that does not route through `writeAdminEntry` — `admin-update-pin` — emits the same line via the exported `logUsersAudit`. A write that changes no field (a clear with no hash, a migrate noop, an absent-admin remove) emits nothing. Credential-mutating MCP tools add `session=<id8>` from `SESSION_NODE_ID` so a mutation traces to its agent session even when the transcript is gone.
+
+**Standing divergence reconcile.** An out-of-band rewrite has no audited caller, so detection is a standing check, not a write hook. The admin-server boot runs `[users-reconcile] op=ok admins=<n>` on parity / `op=divergence accountOnly=<id8,…> usersOnly=<id8,…>` on mismatch / `op=error detail=…` on a read fault, at boot AND hourly — a dropped admin surfaces within one interval, not at the dropped admin's next failed login. It shares the pure `computeAdminStoreDivergence` predicate with the `[admin-invariant]` one-shot (kept alongside) so the two never disagree. The predicate is admin-set membership between the two stores — disjoint from the account-dir registry sweep, so the two never double-report.
+
 **AdminUser graph stamp + boot self-heal.** The seed cypher in `platform/scripts/seed-neo4j.sh` stamps `:AdminUser.accountId` + `:AdminUser.role='owner'` ON CREATE so the graph-write gate's account-scoped MATCH succeeds on the first user-domain write. Admin-server boot additionally runs `platform/ui/app/lib/adminuser-self-heal.ts` to repair legacy nodes whose `accountId` or `role` is null — emits `[adminuser-self-heal] healed=<N> userId=<8> accountId=<8>` once per boot, idempotent. The `graph-write-gate` reject log gains a `subReason=` field (`no-admin-user-node` / `admin-user-no-accountid` / `no-business-or-personal-profile`) for operator diagnosis. See `.docs/agents.md` § "AdminUser graph stamp contract" for the full contract.
 
 `logs-read { type: "agent-stream" }` is the canonical name for the per-conversation tool-use/tool-result archive previously called `system`; both names work and the legacy alias is preserved.

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -8,7 +8,7 @@ import { readFile, writeFile } from "node:fs/promises";
 import { resolve, join } from "node:path";
 import { execFileSync } from "node:child_process";
 import { appendFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { writeAdminEntry, removeAdminFromAccount } from "../../../../lib/admins-write/dist/index.js";
+import { writeAdminEntry, removeAdminFromAccount, logUsersAudit, formatAuditRowIds } from "../../../../lib/admins-write/dist/index.js";
 import { setAccessPassword as setAccessPasswordHash, clearAccessPassword as clearAccessPasswordHash, accessPasswordCollides } from "../../../../lib/admin-access-password/dist/index.js";
 import { embed } from "../../../../lib/embed-client/dist/index.js";
 import { requirePortEnv } from "../../../../lib/require-port-env/dist/index.js";
@@ -209,6 +209,9 @@ const CORE_PLUGINS = ["admin", "memory", "docs", "cloudflare"];
 // resolve the same file via brand-aware $HOME/<configDir>, so the device-level
 // admin auth store is single-pathed across both processes.
 const USERS_FILE = resolve(CONFIG_DIR, "users.json");
+// Append-only credential-store audit log — same path the admin server resolves
+// from app/lib/paths (CONFIG_DIR == MAXY_DIR for both processes).
+const USERS_AUDIT_LOG = resolve(CONFIG_DIR, "logs", "users-audit.log");
 /** Maximum number of admin users allowed per tier. */
 const MAX_ADMINS_BY_TIER = {
     solo: 1,
@@ -917,6 +920,7 @@ eagerTool(server, "admin-add", "Add a new admin user to this account. Creates a
         usersFile: USERS_FILE,
         accountDir: getAccountDir(),
         caller: "admin-add",
+        audit: { actor: callerUserId ?? "unknown", session: process.env.SESSION_NODE_ID, logFile: USERS_AUDIT_LOG },
     });
     console.error(`[admin-auth-store] action=add userId=${userIdShort} result=${authResult.usersJsonResult} store=users${authResult.usersError ? ` error=${authResult.usersError}` : ""}`);
     if (authResult.usersJsonResult !== "ok") {
@@ -1092,6 +1096,7 @@ eagerTool(server, "admin-remove", "Remove an admin from this account. Removes th
         userId,
         accountDir: getAccountDir(),
         caller: "admin-remove",
+        audit: { actor: callerUserId ?? "unknown", session: process.env.SESSION_NODE_ID, logFile: USERS_AUDIT_LOG },
     });
     if (removeResult.accountJsonResult === "fail") {
         return { content: [{ type: "text", text: `${TAG} Failed to write account.json: ${removeResult.accountError ?? "unknown error"}` }], isError: true };
@@ -1217,6 +1222,13 @@ eagerTool(server, "admin-update-pin", "Update an existing admin user's PIN. Defa
     }
     console.error(`${TAG} userId=${userIdLabel} result=ok`);
     console.error(`[admin-auth-store] action=update-pin userId=${userIdLabel} result=ok store=users`);
+    // admin-update-pin writes users.json directly (not via writeAdminEntry), so
+    // it emits the [users-audit] line itself to stay covered. Row-set unchanged
+    // (a pin rotation); the audited field is the pin.
+    {
+        const rows = formatAuditRowIds(users.map(u => u.userId));
+        logUsersAudit({ actor: callerUserId ?? "unknown", session: process.env.SESSION_NODE_ID, logFile: USERS_AUDIT_LOG }, { action: "set-pin", field: "pin", rowsBefore: rows, rowsAfter: rows });
+    }
     const self = userId === callerUserId;
     return {
         content: [{ type: "text", text: `PIN updated${self ? "" : ` for userId ${userId}`}. The new PIN takes effect on the next login.` }],
@@ -2111,7 +2123,7 @@ lifelineTool(server, "remote-auth-set-password", "Set an admin's remote access p
         return { content: [{ type: "text", text: `That password is already in use by another admin. Choose a different one.` }], isError: true };
     }
     try {
-        await setAccessPasswordHash(targetUserId, password, USERS_FILE);
+        await setAccessPasswordHash(targetUserId, password, USERS_FILE, { actor: process.env.USER_ID ?? "unknown", session: process.env.SESSION_NODE_ID, logFile: USERS_AUDIT_LOG });
         console.error(`[admin] remote-access-password set userId=${targetUserId.slice(0, 8)}`);
         return { content: [{ type: "text", text: `Remote access password set for userId ${targetUserId}.` }] };
     }
@@ -2145,7 +2157,7 @@ lifelineTool(server, "remote-auth-revoke-password", "Revoke an admin's remote ac
         return { content: [{ type: "text", text: "Refusing to revoke the last remaining remote access password — the install would have no remote access. Set another admin's password first." }], isError: true };
     }
     try {
-        clearAccessPasswordHash(userId, USERS_FILE);
+        clearAccessPasswordHash(userId, USERS_FILE, { actor: process.env.USER_ID ?? "unknown", session: process.env.SESSION_NODE_ID, logFile: USERS_AUDIT_LOG });
         console.error(`[admin] remote-access-password revoked userId=${userId.slice(0, 8)}`);
         return { content: [{ type: "text", text: `Remote access password revoked for userId ${userId}.` }] };
     }