refactor(modules): extract permissions as optional module

Moves user-roles / users / agent-group-members / user-dms /
dropped-messages / user-dm / canAccessAgentGroup into
src/modules/permissions/. Module registers a single inbound-gate that
owns sender resolution, access decision, unknown-sender policy, and
drop-audit recording.

Router slimmed from 357 → 179 lines; the inline fallback chain
(extractAndUpsertUser / enforceAccess / handleUnknownSender /
recordDroppedMessage) is gone — without the permissions module core
defaults to allow-all with userId=null.

container-runner's admin-ID query is now inline SQL guarded by
sqlite_master on user_roles, keeping core free of any import from the
permissions module. The container-side formatter falls back to
permissionless mode when NANOCLAW_ADMIN_USER_IDS is empty: every sender
with an identifiable senderId is treated as admin.

Module contract doc formalizes the tier model and the dependency rule
(core ← default modules ← optional modules). One transitional violation
flagged: src/access.ts (core) imports from the permissions module for
its remaining approver-picking helpers; resolves in the planned PR #7
re-tier.

Validation: host build clean, 137/137 host tests, 17/17 container
tests, typecheck clean, service boots to "NanoClaw running" with
permissions module registering its gate and clean SIGTERM shutdown.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: gavrielc

container/agent-runner/src/poll-loop.ts

@@ -80,6 +80,10 @@ export async function runPollLoop(config: PollLoopConfig): Promise<void> {
 
     // Handle commands: categorize chat messages
     const adminUserIds = config.adminUserIds ?? new Set<string>();
+    // Permissionless mode: when the permissions module isn't installed on
+    // the host, NANOCLAW_ADMIN_USER_IDS arrives empty. Treat every sender
+    // with an identifiable senderId as admin so admin commands still work.
+    const permissionless = adminUserIds.size === 0;
     const normalMessages = [];
     const commandIds: string[] = [];
 
@@ -99,7 +103,8 @@ export async function runPollLoop(config: PollLoopConfig): Promise<void> {
       }
 
       if (cmdInfo.category === 'admin') {
-        if (!cmdInfo.senderId || !adminUserIds.has(cmdInfo.senderId)) {
+        const authorized = permissionless ? !!cmdInfo.senderId : !!cmdInfo.senderId && adminUserIds.has(cmdInfo.senderId);
+        if (!authorized) {
           log(`Admin command denied: ${cmdInfo.command} from ${cmdInfo.senderId} (msg: ${msg.id})`);
           writeMessageOut({
             id: generateId(),

docs/module-contract.md

@@ -4,23 +4,46 @@ This doc is the authoritative reference for how core and modules connect. Everyt
 
 ## Principles
 
-- Core runs standalone. The `src/modules/index.ts` barrel can be empty and NanoClaw still routes messages in and delivers responses out.
-- Modules are independent. No module imports from another module. Cross-module coordination goes through a core dispatcher.
+- Core runs standalone (modulo default modules — see tiers below). The optional-module portion of the `src/modules/index.ts` barrel can be empty and NanoClaw still routes messages in and delivers responses out.
+- Optional modules are independent. No optional module imports from another optional module. Cross-module coordination goes through a core registry (delivery action, response handler, etc.).
 - Registries exist only when multiple modules plug into the same decision point. Single-consumer integrations use skill edits (`MODULE-HOOK` markers) or stay inline with `sqlite_master` guards.
-- Removing a module = delete files + remove barrel imports + revert any `MODULE-HOOK` content. Migration files stay (data is preserved).
+- Removing an optional module = delete files + remove barrel imports + revert any `MODULE-HOOK` content. Migration files stay (data is preserved). Removing a default module is more invasive: it requires editing the core files that import from it.
 
 ## Module taxonomy
 
-Three categories:
+Three categories. All three live under `src/modules/` (or equivalent adapter dirs) with the same folder layout; the distinction is about **shipping** and **who can depend on them**.
 
-1. **Default modules** — ship on `main`, live in `src/modules/` for signaling, core imports them directly. No hook, no registry. Removing requires editing core imports (deliberately less frictionless than registry modules — the friction signals "not really core, but you probably want it").
-2. **Registry-based modules** — live on the `modules` branch, installed via `/add-<name>` skills. Plug into core through one of the four registries below.
-3. **Channel adapters** — live on the `channels` branch, installed via `/add-<channel>` skills. Not covered by this contract; they use the pre-existing `ChannelAdapter` interface and `registerChannelAdapter()`.
+### 1. Default modules
 
-Current default modules:
+Ship with `main` in `src/modules/`. Imported by the default `src/modules/index.ts` barrel from day one. They are not really core — they live under `src/modules/` specifically to signal "not really core, rippable if needed" — but they're always present on a `main` install. Core imports from them directly. No hook, no registry indirection for the exports themselves.
 
-- `src/modules/typing/` — typing indicator refresh
-- `src/modules/mount-security/` — container mount allowlist validation
+Current: `typing`, `mount-security`.
+
+### 2. Optional modules
+
+Live on the `modules` branch. Installed via `/add-<name>` skills that cherry-pick files. Register into core via one of the four registries (or `MODULE-HOOK` skill edits). Core and other optional modules must not statically import an optional module's code.
+
+Current: `interactive`, `approvals`, `scheduling`, `permissions`. Pending: `agent-to-agent`.
+
+### 3. Channel adapters
+
+Live on the `channels` branch, installed via `/add-<channel>` skills. Not covered by this contract; they use the pre-existing `ChannelAdapter` interface and `registerChannelAdapter()`.
+
+## Dependency rule
+
+```
+core ← default modules ← optional modules
+```
+
+- **Core** may import from core and from default modules.
+- **Default modules** may import from core and from other default modules. They must not import from optional modules.
+- **Optional modules** may import from core and from default modules. They must not import from each other.
+
+Peer-to-peer coupling between optional modules goes through a core registry — see "The four registries" below. This keeps the module dependency graph a DAG and install order irrelevant.
+
+### Known transitional violations
+
+- `src/access.ts` (core) imports from `src/modules/permissions/` (optional). Shim left from PR #5; resolved in the planned approvals re-tier (PR #7) which moves approver-picking into a new default `approvals-primitive` module that may then depend on permissions however it likes — at which point `src/access.ts` ceases to exist.
 
 ## The four registries
 

src/access.test.ts

@@ -1,23 +1,15 @@
 import { beforeEach, afterEach, describe, expect, it } from 'vitest';
 
-import { canAccessAgentGroup, pickApprovalDelivery, pickApprover } from './access.js';
+import { pickApprovalDelivery, pickApprover } from './access.js';
 import type { ChannelAdapter, OutboundMessage } from './channels/adapter.js';
 import { initChannelAdapters, registerChannelAdapter, teardownChannelAdapters } from './channels/channel-registry.js';
-import {
-  addMember,
-  closeDb,
-  createAgentGroup,
-  createMessagingGroup,
-  createUser,
-  getUserDm,
-  grantRole,
-  hasAnyOwner,
-  initTestDb,
-  isMember,
-  isOwner,
-  runMigrations,
-} from './db/index.js';
-import { ensureUserDm } from './user-dm.js';
+import { closeDb, createAgentGroup, createMessagingGroup, initTestDb, runMigrations } from './db/index.js';
+import { canAccessAgentGroup } from './modules/permissions/access.js';
+import { addMember, isMember } from './modules/permissions/db/agent-group-members.js';
+import { createUser } from './modules/permissions/db/users.js';
+import { grantRole, hasAnyOwner, isOwner } from './modules/permissions/db/user-roles.js';
+import { getUserDm } from './modules/permissions/db/user-dms.js';
+import { ensureUserDm } from './modules/permissions/user-dm.js';
 
 function now(): string {
   return new Date().toISOString();

src/access.ts

@@ -1,56 +1,30 @@
 /**
- * Access control + approval routing.
+ * Approval routing helpers (temporary home).
  *
- * Privilege is user-level, not group-level. A user holds zero or more roles
- * (owner | admin) via `user_roles`, and is optionally "known" in specific
- * agent groups via `agent_group_members`. Admins are implicitly members of
- * the groups they administer.
+ * These functions pick an approver for a sensitive action and resolve the
+ * DM messaging_group they should be delivered to. They're called only from
+ * the approvals module.
  *
- * Sensitive actions trigger an approval flow, routed to the admin of the
- * originating agent group; if none, the owner. Approval delivery lands in
- * the approver's DM on (ideally) the same channel kind as the originating
- * request. DM resolution (including cold DMs) is handled by ensureUserDm.
+ * PR #5 moved the access-decision half of this file (canAccessAgentGroup +
+ * AccessDecision) into src/modules/permissions/. The approver-picking half
+ * stays here as a temporary shim — PR #7 relocates it into a new default
+ * approvals-primitive module alongside the approvals re-tier.
+ *
+ * Tier note: this file lives in core but imports from the permissions
+ * optional module. That's a deliberate temporary violation; see the module
+ * contract + REFACTOR_PLAN open question #3.
  */
-import { getAgentGroup } from './db/agent-groups.js';
-import { isMember } from './db/agent-group-members.js';
 import {
   getAdminsOfAgentGroup,
   getGlobalAdmins,
   getOwners,
-  hasAdminPrivilege,
-  isAdminOfAgentGroup,
-  isGlobalAdmin,
-  isOwner,
-} from './db/user-roles.js';
-import { getUser } from './db/users.js';
-import { ensureUserDm } from './user-dm.js';
+} from './modules/permissions/db/user-roles.js';
+import { ensureUserDm } from './modules/permissions/user-dm.js';
 import type { MessagingGroup } from './types.js';
 
-export type AccessDecision =
-  | { allowed: true; reason: 'owner' | 'global_admin' | 'admin_of_group' | 'member' }
-  | { allowed: false; reason: 'unknown_user' | 'not_member' };
-
-/** Can this user interact with this agent group? */
-export function canAccessAgentGroup(userId: string, agentGroupId: string): AccessDecision {
-  if (!getUser(userId)) return { allowed: false, reason: 'unknown_user' };
-  if (isOwner(userId)) return { allowed: true, reason: 'owner' };
-  if (isGlobalAdmin(userId)) return { allowed: true, reason: 'global_admin' };
-  if (isAdminOfAgentGroup(userId, agentGroupId)) return { allowed: true, reason: 'admin_of_group' };
-  if (isMember(userId, agentGroupId)) return { allowed: true, reason: 'member' };
-  return { allowed: false, reason: 'not_member' };
-}
-
-/** Can this user perform privileged (admin) operations on this agent group? */
-export function canAdminAgentGroup(userId: string, agentGroupId: string): boolean {
-  return hasAdminPrivilege(userId, agentGroupId);
-}
-
 /**
  * Ordered list of user IDs eligible to approve an action for the given agent
  * group. Preference: admins @ that group → global admins → owners.
- *
- * The approver-picking policy is to try local admins first (they have direct
- * context for the group), then fall back to global scope.
  */
 export function pickApprover(agentGroupId: string | null): string[] {
   const approvers: string[] = [];
@@ -100,15 +74,6 @@ export async function pickApprovalDelivery(
   return null;
 }
 
-/**
- * Resolve the agent group id for a session's originating request. Used by
- * approval routing so we know which scope to pick admins from.
- */
-export function agentGroupIdForSession(sessionAgentGroupId: string | null): string | null {
-  if (!sessionAgentGroupId) return null;
-  return getAgentGroup(sessionAgentGroupId)?.id ?? null;
-}
-
 function channelTypeOf(userId: string): string {
   const idx = userId.indexOf(':');
   return idx < 0 ? '' : userId.slice(0, idx);

src/container-runner.ts

@@ -14,7 +14,6 @@ import { readContainerConfig, writeContainerConfig } from './container-config.js
 import { CONTAINER_RUNTIME_BIN, hostGatewayArgs, readonlyMountArgs, stopContainer } from './container-runtime.js';
 import { getAgentGroup } from './db/agent-groups.js';
 import { getDb, hasTable } from './db/connection.js';
-import { getAdminsOfAgentGroup, getGlobalAdmins, getOwners } from './db/user-roles.js';
 import { initGroupFilesystem } from './group-init.js';
 import { stopTypingRefresh } from './modules/typing/index.js';
 import { log } from './log.js';
@@ -288,14 +287,26 @@ async function buildContainerArgs(
   // Computed at wake time: owners + global admins + admins scoped to this
   // agent group. Role changes take effect on next container spawn.
   //
-  // Guarded: if the permissions module isn't installed, `user_roles`
-  // doesn't exist and the set stays empty — the formatter treats an
-  // empty admin set as permissionless (every sender is admin).
+  // SQL inlined to keep core independent of the permissions module — we
+  // guard on the `user_roles` table directly. If the permissions module
+  // isn't installed, the table doesn't exist and the set stays empty; the
+  // formatter treats an empty admin set as permissionless mode (every
+  // sender is admin).
   const adminUserIds = new Set<string>();
   if (hasTable(getDb(), 'user_roles')) {
-    for (const r of getOwners()) adminUserIds.add(r.user_id);
-    for (const r of getGlobalAdmins()) adminUserIds.add(r.user_id);
-    for (const r of getAdminsOfAgentGroup(agentGroup.id)) adminUserIds.add(r.user_id);
+    const db = getDb();
+    const owners = db
+      .prepare("SELECT user_id FROM user_roles WHERE role = 'owner' AND agent_group_id IS NULL")
+      .all() as Array<{ user_id: string }>;
+    const globalAdmins = db
+      .prepare("SELECT user_id FROM user_roles WHERE role = 'admin' AND agent_group_id IS NULL")
+      .all() as Array<{ user_id: string }>;
+    const scopedAdmins = db
+      .prepare("SELECT user_id FROM user_roles WHERE role = 'admin' AND agent_group_id = ?")
+      .all(agentGroup.id) as Array<{ user_id: string }>;
+    for (const r of owners) adminUserIds.add(r.user_id);
+    for (const r of globalAdmins) adminUserIds.add(r.user_id);
+    for (const r of scopedAdmins) adminUserIds.add(r.user_id);
   }
   if (adminUserIds.size > 0) {
     args.push('-e', `NANOCLAW_ADMIN_USER_IDS=${Array.from(adminUserIds).join(',')}`);

src/db/index.ts

@@ -8,22 +8,6 @@ export {
   updateAgentGroup,
   deleteAgentGroup,
 } from './agent-groups.js';
-export { createUser, upsertUser, getUser, getAllUsers, updateDisplayName, deleteUser } from './users.js';
-export {
-  grantRole,
-  revokeRole,
-  getUserRoles,
-  isOwner,
-  isGlobalAdmin,
-  isAdminOfAgentGroup,
-  hasAdminPrivilege,
-  getOwners,
-  hasAnyOwner,
-  getGlobalAdmins,
-  getAdminsOfAgentGroup,
-} from './user-roles.js';
-export { addMember, removeMember, getMembers, isMember, hasMembershipRow } from './agent-group-members.js';
-export { upsertUserDm, getUserDm, getUserDmsForUser, deleteUserDm } from './user-dms.js';
 export {
   createMessagingGroup,
   getMessagingGroup,

src/modules/index.ts

@@ -16,4 +16,5 @@
 import './interactive/index.js';
 import './approvals/index.js';
 import './scheduling/index.js';
+import './permissions/index.js';
 

src/modules/permissions/access.ts

@@ -0,0 +1,29 @@
+/**
+ * Access control (permissions module half of src/access.ts).
+ *
+ * Privilege is user-level, not group-level. A user holds zero or more roles
+ * (owner | admin) via `user_roles`, and is optionally "known" in specific
+ * agent groups via `agent_group_members`. Admins are implicitly members of
+ * the groups they administer.
+ *
+ * The approver-picking functions (pickApprover, pickApprovalDelivery) stay
+ * in src/access.ts for now — they move into the approvals module in the
+ * planned PR #7 re-tier.
+ */
+import { isMember } from './db/agent-group-members.js';
+import { isAdminOfAgentGroup, isGlobalAdmin, isOwner } from './db/user-roles.js';
+import { getUser } from './db/users.js';
+
+export type AccessDecision =
+  | { allowed: true; reason: 'owner' | 'global_admin' | 'admin_of_group' | 'member' }
+  | { allowed: false; reason: 'unknown_user' | 'not_member' };
+
+/** Can this user interact with this agent group? */
+export function canAccessAgentGroup(userId: string, agentGroupId: string): AccessDecision {
+  if (!getUser(userId)) return { allowed: false, reason: 'unknown_user' };
+  if (isOwner(userId)) return { allowed: true, reason: 'owner' };
+  if (isGlobalAdmin(userId)) return { allowed: true, reason: 'global_admin' };
+  if (isAdminOfAgentGroup(userId, agentGroupId)) return { allowed: true, reason: 'admin_of_group' };
+  if (isMember(userId, agentGroupId)) return { allowed: true, reason: 'member' };
+  return { allowed: false, reason: 'not_member' };
+}

src/db/agent-group-members.ts …es/permissions/db/agent-group-members.tssrc/db/agent-group-members.ts renamed to src/modules/permissions/db/agent-group-members.ts src/db/agent-group-members.ts renamed to src/modules/permissions/db/agent-group-members.ts

@@ -1,5 +1,5 @@
-import type { AgentGroupMember } from '../types.js';
-import { getDb } from './connection.js';
+import type { AgentGroupMember } from '../../../types.js';
+import { getDb } from '../../../db/connection.js';
 import { isAdminOfAgentGroup, isGlobalAdmin, isOwner } from './user-roles.js';
 
 export function addMember(row: AgentGroupMember): void {

src/db/dropped-messages.ts …dules/permissions/db/dropped-messages.tssrc/db/dropped-messages.ts renamed to src/modules/permissions/db/dropped-messages.ts src/db/dropped-messages.ts renamed to src/modules/permissions/db/dropped-messages.ts

@@ -1,4 +1,4 @@
-import { getDb } from './connection.js';
+import { getDb } from '../../../db/connection.js';
 
 export interface UnregisteredSender {
   channel_type: string;