Permission Gating

Contents

Overview

flowchart TD
  MSG["Incoming command message"]
  AG{"Access groups enabled?"}
  MODE{"modeWhenAccessGroupsOff?"}
  ALLOW_ALL["Return true (allow all)"]
  DENY_ALL["Return false (deny all)"]
  CONFIGURED{"Any authorizer configured?"}
  NONE_CFG["Return true (no config = open)"]
  CHECK_AUTH{"Any configured authorizer allowed?"}
  GRANTED["commandAuthorized = true"]
  DENIED["commandAuthorized = false"]
  CTRL{"allowTextCommands && hasControlCommand?"}
  BLOCK["shouldBlock = true"]
  PASS["shouldBlock = false"]

  MSG --> AG
  AG -->|No| MODE
  MODE -->|"allow"| ALLOW_ALL
  MODE -->|"deny"| DENY_ALL
  MODE -->|"configured"| CONFIGURED
  CONFIGURED -->|No| NONE_CFG
  CONFIGURED -->|Yes| CHECK_AUTH
  AG -->|Yes| CHECK_AUTH
  CHECK_AUTH -->|Yes| GRANTED
  CHECK_AUTH -->|No| DENIED
  GRANTED --> CTRL
  DENIED --> CTRL
  CTRL -->|"Yes && !authorized"| BLOCK
  CTRL -->|Otherwise| PASS

The diagram above traces the complete authorization decision tree. The first branch checks whether access groups are enabled. When they are off, the modeWhenAccessGroupsOff setting determines the fallback behavior — allow all, deny all, or only evaluate configured authorizers. When access groups are on, the system always requires at least one configured-and-allowed authorizer entry.

Core Types

The permission gating layer relies on a small set of types that flow through the entire authorization pipeline. The CommandAuthorizer type is the fundamental unit, while CommandGatingModeWhenAccessGroupsOff controls fallback behavior.

// src/channels/command-gating.ts — CommandAuthorizer type
export type CommandAuthorizer = {
  configured: boolean;
  allowed: boolean;
};

export type CommandGatingModeWhenAccessGroupsOff =
  | "allow"   // All commands permitted when access groups are disabled
  | "deny"    // All commands blocked when access groups are disabled
  | "configured";  // Evaluate configured authorizers even without access groups

The ingress opts type narrows optional fields to required ones, ensuring downstream handlers always have definitive authorization context:

// src/agents/command/types.ts — AgentCommandOpts and ingress narrowing
export type AgentCommandOpts = {
  // ...
  senderIsOwner?: boolean;
  allowModelOverride?: boolean;
  // ...
};

export type AgentCommandIngressOpts = Omit<
  AgentCommandOpts,
  "senderIsOwner" | "allowModelOverride"
> & {
  senderIsOwner: boolean;       // Required at ingress
  allowModelOverride: boolean;  // Required at ingress
};

Decision Points

How It Works

Permission gating operates in three phases: command gating resolution in command-gating.ts, ingress authorization via AgentCommandIngressOpts, and allowlist policy evaluation in the doctor subsystem. The three phases are intentionally decoupled so each can be tested and reasoned about independently.

Phase 1 — Command Gating Resolution

The resolveCommandAuthorizedFromAuthorizers function is the core authorization engine. It evaluates an array of CommandAuthorizer entries and returns a single boolean. The function is pure — no side effects, no state mutation.

// src/channels/command-gating.ts — resolveCommandAuthorizedFromAuthorizers
export function resolveCommandAuthorizedFromAuthorizers(params: {
  useAccessGroups: boolean;
  authorizers: CommandAuthorizer[];
  modeWhenAccessGroupsOff?: CommandGatingModeWhenAccessGroupsOff;
}): boolean {
  const { useAccessGroups, authorizers } = params;
  const mode = params.modeWhenAccessGroupsOff ?? "allow";

  if (!useAccessGroups) {
    // Access groups are disabled — apply fallback mode
    if (mode === "allow") return true;
    if (mode === "deny") return false;
    // mode === "configured": evaluate authorizers normally
    const anyConfigured = authorizers.some((entry) => entry.configured);
    if (!anyConfigured) return true;  // No config = open access
    return authorizers.some((entry) => entry.configured && entry.allowed);
  }

  // Access groups enabled — require at least one configured + allowed
  return authorizers.some((entry) => entry.configured && entry.allowed);
}

Phase 2 — Control Command Gate

The resolveControlCommandGate function wraps the base authorizer resolution and adds control-command-specific blocking logic. It returns both the raw authorization result and a shouldBlock flag that callers use to suppress execution.

// src/channels/command-gating.ts — resolveControlCommandGate
export function resolveControlCommandGate(params: {
  useAccessGroups: boolean;
  authorizers: CommandAuthorizer[];
  allowTextCommands: boolean;
  hasControlCommand: boolean;
  modeWhenAccessGroupsOff?: CommandGatingModeWhenAccessGroupsOff;
}): { commandAuthorized: boolean; shouldBlock: boolean } {
  const commandAuthorized = resolveCommandAuthorizedFromAuthorizers({
    useAccessGroups: params.useAccessGroups,
    authorizers: params.authorizers,
    modeWhenAccessGroupsOff: params.modeWhenAccessGroupsOff,
  });
  const shouldBlock =
    params.allowTextCommands &&
    params.hasControlCommand &&
    !commandAuthorized;
  return { commandAuthorized, shouldBlock };
}

Phase 3 — Allowlist Policy Evaluation

The doctor subsystem provides a secondary authorization layer through allowlist policies. These policies define which senders are allowed to invoke commands from specific contexts — top-level only, nested only, or both.

// src/commands/doctor/shared/allow-from-mode.ts
export type AllowFromMode =
  | "topOnly"       // Only top-level senders (direct messages)
  | "topOrNested"   // Both top-level and nested (forwarded) senders
  | "nestedOnly";   // Only nested senders (forwarded messages)

// src/commands/doctor/shared/allowlist.ts
export function hasAllowFromEntries(
  list?: DoctorAllowFromList,
): boolean {
  // Returns true if the allowlist has at least one entry configured
  // Used to determine whether allowlist evaluation should proceed
}

Authorization Flow

The sequence diagram below shows how an authorized command and a blocked command proceed through the permission gating pipeline. The critical divergence point is the resolveControlCommandGate return value.

sequenceDiagram
    participant Sender
    participant Router as Command Router
    participant Gating as command-gating.ts
    participant Allowlist as allowlist.ts
    participant Handler as Command Handler

    Note over Sender,Handler: Scenario A — Authorized sender
    Sender->>Router: /model set gpt-4
    Router->>Gating: resolveControlCommandGate(authorizers, ...)
    Gating->>Gating: resolveCommandAuthorizedFromAuthorizers()
    Gating-->>Router: { commandAuthorized: true, shouldBlock: false }
    Router->>Allowlist: hasAllowFromEntries(policy)
    Allowlist-->>Router: true (sender in allowlist)
    Router->>Handler: dispatch "model set gpt-4"
    Handler-->>Sender: "Default model updated to gpt-4"

    Note over Sender,Handler: Scenario B — Blocked sender
    Sender->>Router: /reset agent
    Router->>Gating: resolveControlCommandGate(authorizers, ...)
    Gating->>Gating: resolveCommandAuthorizedFromAuthorizers()
    Gating-->>Router: { commandAuthorized: false, shouldBlock: true }
    Router-->>Sender: "Permission denied: not authorized"

In Scenario A, the sender passes both the command gating check and the allowlist check, so the command handler executes normally. In Scenario B, the sender fails the command gating check and the router immediately returns a denial without ever reaching the allowlist or the handler.

Code Walkthrough

Let us trace the path of a /model set gpt-4 command from a non-owner sender when access groups are enabled and one authorizer grants access.

const authorizers: CommandAuthorizer[] = [
  { configured: true, allowed: true },   // Role: admin
  { configured: true, allowed: false },   // Channel: restricted
  { configured: false, allowed: false },  // User override: not set
];

Edge Cases

Configuration

Plugin-Level Authorization

In addition to the channel-level command gating, individual plugins can declare their own auth requirement via the requireAuth flag in the plugin type definition:

// src/plugins/types.ts — Plugin requireAuth flag
export interface PluginCommandDefinition {
  name: string;
  description: string;
  acceptsArgs: boolean;
  requireAuth?: boolean;  // Whether only authorized senders can use this command
  handler: (args?: string) => Promise<string>;
}

Related Topics

Source Files

src/
├── channels/
│   └── command-gating.ts             ← CommandAuthorizer type, resolveCommandAuthorizedFromAuthorizers(),
│                                        resolveControlCommandGate()
├── agents/
│   └── command/
│       └── types.ts                  ← AgentCommandOpts, AgentCommandIngressOpts
├── commands/
│   └── doctor/
│       └── shared/
│           ├── allowlist.ts          ← hasAllowFromEntries()
│           ├── allow-from-mode.ts    ← AllowFromMode type
│           ├── allowlist-policy-repair.ts ← maybeRepairAllowlistPolicyAllowFrom()
│           ├── empty-allowlist-policy.ts  ← Default empty allowlist policy
│           ├── empty-allowlist-scan.ts    ← Empty allowlist scan behavior
│           └── open-policy-allowfrom.ts   ← Open policy allow-from defaults
└── plugins/
    └── types.ts                      ← requireAuth flag on plugin commands