Channels/Allowlists — Access Control Engine

Allowlists Command Gating Mention Gating Access Groups

Architecture

flowchart TD
    subgraph Input["Inbound Message"]
        SENDER["Sender Identity"]
        CMD["Command Detected?"]
        MENTION["Was @mentioned?"]
    end
    subgraph Allowlist["Allowlist Engine"]
        COMPILE["compileAllowlist()"]
        RESOLVE["resolveCompiledAllowlistMatch()"]
        CANDIDATES["Identity Candidates"]
    end
    subgraph AllowFrom["AllowFrom Sources"]
        DMMERGE["mergeDmAllowFromSources()"]
        GROUPFROM["resolveGroupAllowFromSources()"]
    end
    subgraph Gating["Command & Mention Gating"]
        CMDGATE["resolveControlCommandGate()"]
        MGATE["resolveMentionGating()"]
    end
    subgraph Result["Access Decision"]
        ALLOW["Allowed"]
        DENY["Denied / Blocked"]
    end

    SENDER --> CANDIDATES
    CANDIDATES --> COMPILE
    COMPILE --> RESOLVE
    RESOLVE --> ALLOW
    RESOLVE --> DENY
    DMMERGE --> COMPILE
    GROUPFROM --> COMPILE
    CMD --> CMDGATE
    CMDGATE --> ALLOW
    CMDGATE --> DENY
    MENTION --> MGATE
    MGATE --> ALLOW
    MGATE --> DENY

Allowlist Matching Pipeline

The core matching function accepts a compiled allowlist and an ordered array of identity candidates. Each candidate has a value (the identifier string) and a source (how it was derived). The engine checks candidates in order; the first match wins.

Match Sources

Compilation

export function compileAllowlist(entries: ReadonlyArray<string>): CompiledAllowlist {
  const set = new Set(entries.filter(Boolean));
  return {
    set,
    wildcard: set.has("*"),
  };
}

AllowFrom Source Resolution

DM and group contexts have separate allowFrom sources that are merged before compilation:

flowchart LR
    subgraph DM["DM Context"]
        AF["allowFrom config"]
        SAF["storeAllowFrom"]
        DMP["dmPolicy"]
    end
    subgraph Group["Group Context"]
        GAF["groupAllowFrom"]
        FAF["fallbackToAllowFrom"]
    end
    DM --> MERGE["mergeDmAllowFromSources()"]
    Group --> GRESOLVE["resolveGroupAllowFromSources()"]
    MERGE --> COMPILED["CompiledAllowlist"]
    GRESOLVE --> COMPILED

export function mergeDmAllowFromSources(params: {
  allowFrom?: Array<string | number>;
  storeAllowFrom?: Array<string | number>;
  dmPolicy?: string;
}): string[] {
  const storeEntries = params.dmPolicy === "allowlist" ? [] : (params.storeAllowFrom ?? []);
  return [...(params.allowFrom ?? []), ...storeEntries]
    .map((value) => String(value).trim())
    .filter(Boolean);
}

Command Gating

Slash commands can be restricted to authorized users only. The gating system supports three modes when access groups are disabled:

export function resolveControlCommandGate(params: {
  useAccessGroups: boolean;
  authorizers: CommandAuthorizer[];
  allowTextCommands: boolean;
  hasControlCommand: boolean;
  modeWhenAccessGroupsOff?: CommandGatingModeWhenAccessGroupsOff;
}): { commandAuthorized: boolean; shouldBlock: boolean }

Mention Gating

In group chats, the agent can require an @mention before processing. The system handles implicit mentions, bypass rules (authorized control commands), and detection capability flags.

export function resolveMentionGating(params: MentionGateParams): MentionGateResult {
  const implicit = params.implicitMention === true;
  const bypass = params.shouldBypassMention === true;
  const effectiveWasMentioned = params.wasMentioned || implicit || bypass;
  const shouldSkip = params.requireMention && params.canDetectMention && !effectiveWasMentioned;
  return { effectiveWasMentioned, shouldSkip };
}

Focus Deep-Dives