@openparachute/agent 0.1.0

package/src/modules/permissions/index.ts

@@ -0,0 +1,421 @@
+/**
+ * Permissions module — sender resolution + access gate.
+ *
+ * Registers two hooks into the core router:
+ *   1. setSenderResolver — runs before agent resolution. Parses the payload,
+ *      derives a namespaced user id, and upserts the `users` row on first
+ *      sight. Returns null when the payload doesn't carry enough to identify
+ *      a sender.
+ *   2. setAccessGate — runs after agent resolution. Enforces the
+ *      unknown_sender_policy (strict/request_approval/public) and the
+ *      owner/global-admin/scoped-admin/member access hierarchy. Records its
+ *      own `dropped_messages` row on refusal (structural drops are recorded
+ *      by core).
+ *
+ * Without this module: sender resolution is a no-op (userId=null); the
+ * access gate is not registered and core defaults to allow-all.
+ */
+import { recordDroppedMessage } from '../../db/dropped-messages.js';
+import {
+  createMessagingGroupAgent,
+  getMessagingGroup,
+  setMessagingGroupDeniedAt,
+  updateMessagingGroup,
+} from '../../db/messaging-groups.js';
+import {
+  routeInbound,
+  setAccessGate,
+  setChannelRequestGate,
+  setSenderResolver,
+  setSenderScopeGate,
+  type AccessGateResult,
+} from '../../router.js';
+import type { InboundEvent } from '../../channels/adapter.js';
+import { registerResponseHandler, type ResponsePayload } from '../../response-registry.js';
+import { log } from '../../log.js';
+import type { MessagingGroup, MessagingGroupAgent } from '../../types.js';
+import { canAccessAgentGroup } from './access.js';
+import { requestChannelApproval } from './channel-approval.js';
+import { addMember } from './db/agent-group-members.js';
+import { deletePendingChannelApproval, getPendingChannelApproval } from './db/pending-channel-approvals.js';
+import { deletePendingSenderApproval, getPendingSenderApproval } from './db/pending-sender-approvals.js';
+import { hasAdminPrivilege } from './db/user-roles.js';
+import { getUser, upsertUser } from './db/users.js';
+import { requestSenderApproval } from './sender-approval.js';
+
+function extractAndUpsertUser(event: InboundEvent): string | null {
+  let content: Record<string, unknown>;
+  try {
+    content = JSON.parse(event.message.content) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+
+  // chat-sdk-bridge serializes author info as a nested `author.userId` and
+  // does NOT populate top-level `senderId`. Older adapters (v1, native) put
+  // `senderId` or `sender` directly at the top level. Check all three.
+  const senderIdField = typeof content.senderId === 'string' ? content.senderId : undefined;
+  const senderField = typeof content.sender === 'string' ? content.sender : undefined;
+  const author =
+    typeof content.author === 'object' && content.author !== null
+      ? (content.author as Record<string, unknown>)
+      : undefined;
+  const authorUserId = typeof author?.userId === 'string' ? (author.userId as string) : undefined;
+  const senderName =
+    (typeof content.senderName === 'string' ? content.senderName : undefined) ??
+    (typeof author?.fullName === 'string' ? (author.fullName as string) : undefined) ??
+    (typeof author?.userName === 'string' ? (author.userName as string) : undefined);
+
+  const rawHandle = senderIdField ?? senderField ?? authorUserId;
+  if (!rawHandle) return null;
+
+  const userId = rawHandle.includes(':') ? rawHandle : `${event.channelType}:${rawHandle}`;
+  if (!getUser(userId)) {
+    upsertUser({
+      id: userId,
+      kind: event.channelType,
+      display_name: senderName ?? null,
+      created_at: new Date().toISOString(),
+    });
+  }
+  return userId;
+}
+
+function safeParseContent(raw: string): { text?: string; sender?: string; senderId?: string } {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return { text: raw };
+  }
+}
+
+function handleUnknownSender(
+  mg: MessagingGroup,
+  userId: string | null,
+  agentGroupId: string,
+  accessReason: string,
+  event: InboundEvent,
+): void {
+  const parsed = safeParseContent(event.message.content);
+  const senderName = parsed.sender ?? null;
+  const dropRecord = {
+    channel_type: event.channelType,
+    platform_id: event.platformId,
+    user_id: userId,
+    sender_name: senderName,
+    reason: `unknown_sender_${mg.unknown_sender_policy}`,
+    messaging_group_id: mg.id,
+    agent_group_id: agentGroupId,
+  };
+
+  if (mg.unknown_sender_policy === 'strict') {
+    log.info('MESSAGE DROPPED — unknown sender (strict policy)', {
+      messagingGroupId: mg.id,
+      agentGroupId,
+      userId,
+      accessReason,
+    });
+    recordDroppedMessage(dropRecord);
+    return;
+  }
+
+  if (mg.unknown_sender_policy === 'request_approval') {
+    log.info('MESSAGE DROPPED — unknown sender (approval requested)', {
+      messagingGroupId: mg.id,
+      agentGroupId,
+      userId,
+      accessReason,
+    });
+    recordDroppedMessage(dropRecord);
+    // Fire-and-forget; pick-approver + delivery + row-insert are all async.
+    // If it fails it logs internally — the user's message still stays dropped
+    // either way. Requires a resolved userId (senderResolver populates users
+    // row before the gate fires); if we got here without one, there's nothing
+    // to identify for approval and we just stay in the "silent strict" branch.
+    if (userId) {
+      requestSenderApproval({
+        messagingGroupId: mg.id,
+        agentGroupId,
+        senderIdentity: userId,
+        senderName,
+        event,
+      }).catch((err) => log.error('Sender-approval flow threw', { err }));
+    }
+    return;
+  }
+
+  // 'public' should have been handled before the gate; fall through silently.
+}
+
+setSenderResolver(extractAndUpsertUser);
+
+setAccessGate((event, userId, mg, agentGroupId): AccessGateResult => {
+  // Public channels skip the access check entirely.
+  if (mg.unknown_sender_policy === 'public') {
+    return { allowed: true };
+  }
+
+  if (!userId) {
+    handleUnknownSender(mg, null, agentGroupId, 'unknown_user', event);
+    return { allowed: false, reason: 'unknown_user' };
+  }
+
+  const decision = canAccessAgentGroup(userId, agentGroupId);
+  if (decision.allowed) {
+    return { allowed: true };
+  }
+
+  handleUnknownSender(mg, userId, agentGroupId, decision.reason, event);
+  return { allowed: false, reason: decision.reason };
+});
+
+/**
+ * Per-wiring sender-scope enforcement. Stricter than the messaging-group
+ * `unknown_sender_policy` — a wiring can require `sender_scope='known'`
+ * (explicit owner / admin / member) even on a 'public' messaging group.
+ *
+ * 'all' is a no-op; any sender passes. 'known' requires a userId that
+ * canAccessAgentGroup accepts (owner, admin, or group member).
+ */
+setSenderScopeGate(
+  (_event: InboundEvent, userId: string | null, _mg: MessagingGroup, agent: MessagingGroupAgent): AccessGateResult => {
+    if (agent.sender_scope === 'all') return { allowed: true };
+    if (!userId) return { allowed: false, reason: 'unknown_user_scope' };
+    const decision = canAccessAgentGroup(userId, agent.agent_group_id);
+    if (decision.allowed) return { allowed: true };
+    return { allowed: false, reason: `sender_scope_${decision.reason}` };
+  },
+);
+
+/**
+ * Response handler for the unknown-sender approval card.
+ *
+ * Claim rule: questionId matches a row in pending_sender_approvals. If no
+ * such row, return false so the next handler (approvals module, interactive)
+ * gets a shot.
+ *
+ * Approve: add the sender to agent_group_members + re-invoke routeInbound
+ * with the stored event. The second routing attempt clears the gate because
+ * the user is now a member.
+ *
+ * Deny: delete the row (no "deny list" — a future message re-triggers a
+ * fresh card per ACTION-ITEMS item 5 "no denial persistence").
+ */
+async function handleSenderApprovalResponse(payload: ResponsePayload): Promise<boolean> {
+  const row = getPendingSenderApproval(payload.questionId);
+  if (!row) return false;
+
+  // payload.userId is the raw platform userId (e.g. "6037840640"); namespace it
+  // with the channel type so it matches users(id) format. Then verify the
+  // clicker is the designated approver OR has owner/admin privilege over this
+  // agent group — any other click is rejected so random users can't self-admit
+  // via stolen card forwarding.
+  const clickerId = payload.userId ? `${payload.channelType}:${payload.userId}` : null;
+  const isAuthorized =
+    clickerId !== null && (clickerId === row.approver_user_id || hasAdminPrivilege(clickerId, row.agent_group_id));
+  if (!isAuthorized) {
+    log.warn('Unknown-sender approval click rejected — unauthorized clicker', {
+      approvalId: row.id,
+      clickerId,
+      expectedApprover: row.approver_user_id,
+    });
+    return true; // claim the response so it's not unclaimed-logged, but do nothing
+  }
+  const approverId = clickerId;
+  const alsoAllow = payload.value === 'approve_and_allow';
+  const approved = payload.value === 'approve' || alsoAllow;
+
+  if (approved) {
+    addMember({
+      user_id: row.sender_identity,
+      agent_group_id: row.agent_group_id,
+      added_by: approverId,
+      added_at: new Date().toISOString(),
+    });
+    log.info('Unknown sender approved — member added', {
+      approvalId: row.id,
+      senderIdentity: row.sender_identity,
+      agentGroupId: row.agent_group_id,
+      approverId,
+    });
+
+    if (alsoAllow) {
+      // Snapshot the prior policy for the audit line — read before the
+      // update so the "fromPolicy" field reflects pre-flip state even if
+      // a concurrent click had already flipped it. fromPolicy=null means
+      // the MG row was deleted between approval-creation and click; the
+      // updateMessagingGroup call below silently no-ops on a missing row.
+      const mg = getMessagingGroup(row.messaging_group_id);
+      const fromPolicy = mg?.unknown_sender_policy ?? null;
+      if (fromPolicy !== 'public') {
+        updateMessagingGroup(row.messaging_group_id, { unknown_sender_policy: 'public' });
+      }
+      log.info('Unknown-sender policy flipped to public via approval card', {
+        audit: 'sender_approval_policy_flip',
+        approvalId: row.id,
+        messagingGroupId: row.messaging_group_id,
+        agentGroupId: row.agent_group_id,
+        approverId,
+        fromPolicy,
+        toPolicy: 'public',
+      });
+    }
+
+    // Clear the pending row BEFORE re-routing so the gate check on the
+    // second attempt doesn't see the in-flight row and short-circuit.
+    deletePendingSenderApproval(row.id);
+
+    try {
+      const event = JSON.parse(row.original_message) as InboundEvent;
+      await routeInbound(event);
+    } catch (err) {
+      log.error('Failed to replay message after sender approval', { approvalId: row.id, err });
+    }
+    return true;
+  }
+
+  log.info('Unknown sender denied', {
+    approvalId: row.id,
+    senderIdentity: row.sender_identity,
+    agentGroupId: row.agent_group_id,
+    approverId,
+  });
+  deletePendingSenderApproval(row.id);
+  return true;
+}
+
+registerResponseHandler(handleSenderApprovalResponse);
+
+// ── Unknown-channel registration flow ──
+
+setChannelRequestGate(async (mg, event) => {
+  await requestChannelApproval({ messagingGroupId: mg.id, event });
+});
+
+/**
+ * Response handler for the unknown-channel registration card.
+ *
+ * Claim rule: questionId matches a pending_channel_approvals row (keyed
+ * by messaging_group_id). If no such row, return false so downstream
+ * handlers get a shot.
+ *
+ * Approve: create the wiring with MVP defaults (mention-sticky for
+ * groups / pattern='.' for DMs; sender_scope='known';
+ * ignored_message_policy='accumulate'), add the triggering sender as a
+ * member so sender_scope doesn't immediately bounce them into a
+ * sender-approval card, then replay the original event.
+ *
+ * Deny: set `messaging_groups.denied_at = now()` so future mentions on
+ * this channel drop silently until an admin explicitly wires it.
+ */
+async function handleChannelApprovalResponse(payload: ResponsePayload): Promise<boolean> {
+  const row = getPendingChannelApproval(payload.questionId);
+  if (!row) return false;
+
+  // Click-auth: same pattern as sender-approval (see commit 68058cb).
+  // Raw platform userId → namespace with channelType → must match the
+  // designated approver OR have admin privilege over the target agent.
+  const clickerId = payload.userId ? `${payload.channelType}:${payload.userId}` : null;
+  const isAuthorized =
+    clickerId !== null && (clickerId === row.approver_user_id || hasAdminPrivilege(clickerId, row.agent_group_id));
+  if (!isAuthorized) {
+    log.warn('Channel registration click rejected — unauthorized clicker', {
+      messagingGroupId: row.messaging_group_id,
+      clickerId,
+      expectedApprover: row.approver_user_id,
+    });
+    return true; // claim but take no action
+  }
+  const approverId = clickerId;
+  const approved = payload.value === 'approve';
+
+  if (!approved) {
+    setMessagingGroupDeniedAt(row.messaging_group_id, new Date().toISOString());
+    deletePendingChannelApproval(row.messaging_group_id);
+    log.info('Channel registration denied', {
+      messagingGroupId: row.messaging_group_id,
+      agentGroupId: row.agent_group_id,
+      approverId,
+    });
+    return true;
+  }
+
+  // Rehydrate the original event to know (a) whether it was a DM or group
+  // (chooses engage_mode default), and (b) who the triggering sender was
+  // (auto-member-add so sender_scope='known' doesn't bounce the replay).
+  let event: InboundEvent;
+  try {
+    event = JSON.parse(row.original_message) as InboundEvent;
+  } catch (err) {
+    log.error('Channel registration: failed to parse stored event', {
+      messagingGroupId: row.messaging_group_id,
+      err,
+    });
+    deletePendingChannelApproval(row.messaging_group_id);
+    return true;
+  }
+
+  // Decide engage_mode from the original event. DMs (`isMention=true` &
+  // not in a group) get `pattern='.'` (always respond). Group mentions
+  // get `mention-sticky` (respond now + follow the thread).
+  //
+  // We can't read `mg.is_group` reliably here because we only auto-create
+  // the mg with `is_group=0` on first sight — the adapter hasn't told us
+  // yet whether it's actually a group. Fall back to the InboundEvent's
+  // `threadId`: a non-null threadId implies a threaded platform (Slack
+  // channel thread, Discord thread), which we treat as a group.
+  const isGroup = event.threadId !== null;
+  const engageMode: MessagingGroupAgent['engage_mode'] = isGroup ? 'mention-sticky' : 'pattern';
+  const engagePattern = isGroup ? null : '.';
+
+  const mgaId = `mga-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  createMessagingGroupAgent({
+    id: mgaId,
+    messaging_group_id: row.messaging_group_id,
+    agent_group_id: row.agent_group_id,
+    engage_mode: engageMode,
+    engage_pattern: engagePattern,
+    sender_scope: 'known',
+    ignored_message_policy: 'accumulate',
+    session_mode: 'shared',
+    priority: 0,
+    created_at: new Date().toISOString(),
+  });
+  log.info('Channel registration approved — wiring created', {
+    messagingGroupId: row.messaging_group_id,
+    agentGroupId: row.agent_group_id,
+    mgaId,
+    engageMode,
+    approverId,
+  });
+
+  // Auto-admit the triggering sender. Without this, the replay below
+  // would bounce through sender-approval (sender_scope='known' +
+  // sender-is-not-a-member).
+  const senderUserId = extractAndUpsertUser(event);
+  if (senderUserId) {
+    addMember({
+      user_id: senderUserId,
+      agent_group_id: row.agent_group_id,
+      added_by: approverId,
+      added_at: new Date().toISOString(),
+    });
+  }
+
+  // Clear the pending row BEFORE replay so the gate check on the second
+  // attempt sees a wired channel (agentCount > 0) and takes the fan-out
+  // path normally.
+  deletePendingChannelApproval(row.messaging_group_id);
+
+  try {
+    await routeInbound(event);
+  } catch (err) {
+    log.error('Failed to replay message after channel approval', {
+      messagingGroupId: row.messaging_group_id,
+      err,
+    });
+  }
+  return true;
+}
+
+registerResponseHandler(handleChannelApprovalResponse);