@moxxy/channel-kit 0.27.0

package/src/ingest/http-server.ts

@@ -0,0 +1,173 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { readRequestBody } from '@moxxy/sdk/server';
+
+/**
+ * HTTP scaffold for inbound-webhook channels (Slack Events API today; Discord /
+ * WhatsApp / Signal-style ingest next). Binds a `node:http` server to an
+ * ephemeral loopback port; the channel exposes it publicly via a tunnel.
+ *
+ * The scaffold owns the gates that must run BEFORE any payload is trusted
+ * (skill A8/A46) and before the session is ever touched:
+ *   1. routing — POST-only on `eventsPath` (+ an optional GET health probe);
+ *      anything else is 404.
+ *   2. raw body read, size-capped → 413 (the raw bytes are what signature
+ *      schemes verify — never a reserialized JSON).
+ *   3. the `verify` hook → 401. Provider-specific signature schemes (Slack's
+ *      HMAC, Discord's ed25519, ...) stay in the channel as this hook.
+ *   4. every handler error is caught → 500, so a bad request can never
+ *      escalate to a process-level uncaughtException.
+ *
+ * Everything AFTER verification — schema validation, handshake echoes, dedupe,
+ * the immediate ACK, and fire-and-forget turn dispatch — is the channel's
+ * `handleVerified`, which owns writing the response.
+ */
+
+export type IngestVerdict = { readonly ok: true } | { readonly ok: false; readonly reason: string };
+
+export interface IngestLogger {
+  info?(msg: string, meta?: Record<string, unknown>): void;
+  warn?(msg: string, meta?: Record<string, unknown>): void;
+}
+
+export interface IngestHttpServerOptions {
+  /** Bind host. Default 127.0.0.1 (loopback; a tunnel provides public reach). */
+  readonly host?: string;
+  /** POST endpoint the provider delivers events to (e.g. '/slack/events'). */
+  readonly eventsPath: string;
+  /** Optional GET liveness probe (e.g. '/slack/health'). */
+  readonly healthPath?: string;
+  /** Health probe response body. Default `{ status: 'ok' }`. */
+  readonly healthBody?: () => unknown;
+  /** Max request body size in bytes. Default 1MB. */
+  readonly maxBodyBytes?: number;
+  /** Short channel label prefixed onto log lines (e.g. 'slack'). */
+  readonly label: string;
+  /** Signature gate over the EXACT raw bytes, before any parsing. */
+  readonly verify: (input: {
+    rawBody: Buffer;
+    headers: IncomingMessage['headers'];
+  }) => IngestVerdict;
+  /**
+   * The channel-specific pipeline for a verified delivery (parse → dedupe →
+   * ACK → dispatch). MUST write the response.
+   */
+  readonly handleVerified: (
+    rawBody: Buffer,
+    req: IncomingMessage,
+    res: ServerResponse,
+  ) => Promise<void>;
+  readonly logger?: IngestLogger;
+}
+
+export interface IngestHttpServerHandle {
+  readonly host: string;
+  readonly port: number;
+  stop(): Promise<void>;
+}
+
+export function respondJson(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+export class IngestHttpServer {
+  private server: Server | null = null;
+  private readonly host: string;
+  private readonly maxBodyBytes: number;
+  private boundPort = 0;
+
+  constructor(private readonly opts: IngestHttpServerOptions) {
+    this.host = opts.host ?? '127.0.0.1';
+    this.maxBodyBytes = opts.maxBodyBytes ?? 1024 * 1024;
+  }
+
+  get port(): number {
+    return this.boundPort;
+  }
+
+  /** Bind on an ephemeral loopback port. Resolves once listening. */
+  async start(): Promise<IngestHttpServerHandle> {
+    if (this.server) {
+      return { host: this.host, port: this.boundPort, stop: () => this.stop() };
+    }
+    const server = createServer((req, res) => {
+      this.handle(req, res).catch((err) => {
+        this.opts.logger?.warn?.(`${this.opts.label}: handler threw`, { err: String(err) });
+        if (!res.headersSent) {
+          respondJson(res, 500, { error: 'internal' });
+        } else {
+          try {
+            res.end();
+          } catch {
+            /* ignore */
+          }
+        }
+      });
+    });
+    this.server = server;
+
+    await new Promise<void>((resolve, reject) => {
+      const onError = (err: Error): void => reject(err);
+      server.once('error', onError);
+      // port 0 → OS assigns an ephemeral port; we read it back for the tunnel.
+      server.listen(0, this.host, () => {
+        server.off('error', onError);
+        const addr = server.address();
+        this.boundPort = addr && typeof addr === 'object' ? (addr as AddressInfo).port : 0;
+        this.opts.logger?.info?.(`${this.opts.label}: ingest listening`, {
+          host: this.host,
+          port: this.boundPort,
+        });
+        resolve();
+      });
+    });
+
+    return { host: this.host, port: this.boundPort, stop: () => this.stop() };
+  }
+
+  async stop(): Promise<void> {
+    const s = this.server;
+    if (!s) return;
+    this.server = null;
+    await new Promise<void>((resolve) => s.close(() => resolve()));
+  }
+
+  private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const url = (req.url ?? '/').split('?')[0] ?? '/';
+
+    // Liveness probe (a proxy relay / an operator can hit this).
+    if (this.opts.healthPath && req.method === 'GET' && url === this.opts.healthPath) {
+      respondJson(res, 200, this.opts.healthBody?.() ?? { status: 'ok' });
+      return;
+    }
+
+    if (req.method !== 'POST' || url !== this.opts.eventsPath) {
+      respondJson(res, 404, { error: 'not_found' });
+      return;
+    }
+
+    // Raw body bytes (needed for signature verification; BEFORE JSON.parse).
+    let raw: Buffer;
+    try {
+      raw = await readRequestBody(req, this.maxBodyBytes);
+    } catch (err) {
+      this.opts.logger?.warn?.(`${this.opts.label}: rejected oversized body`, {
+        limit: this.maxBodyBytes,
+        err: err instanceof Error ? err.message : String(err),
+      });
+      respondJson(res, 413, { error: 'payload_too_large' });
+      return;
+    }
+
+    // Signature gate.
+    const verdict = this.opts.verify({ rawBody: raw, headers: req.headers });
+    if (!verdict.ok) {
+      this.opts.logger?.warn?.(`${this.opts.label}: rejected delivery`, { reason: verdict.reason });
+      respondJson(res, 401, { error: 'verification_failed' });
+      return;
+    }
+
+    await this.opts.handleVerified(raw, req, res);
+  }
+}

package/src/pairing/host-code.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+import {
+  clearHostCodePairing,
+  createHostCodeState,
+  greetPeer,
+  isPeerAuthorized,
+  openHostCodeWindow,
+  submitPeerCode,
+} from './host-code.js';
+
+describe('host-code pairing machine', () => {
+  it('starts idle', () => {
+    const s = createHostCodeState<number>();
+    expect(s.phase).toBe('idle');
+    expect(s.authorizedPeer).toBeNull();
+  });
+
+  it('starts paired when an authorized peer is restored', () => {
+    const s = createHostCodeState({ authorizedPeer: 42 });
+    expect(s.phase).toBe('paired');
+    expect(isPeerAuthorized(s, 42)).toBe(true);
+    expect(isPeerAuthorized(s, 99)).toBe(false);
+  });
+
+  it('openHostCodeWindow arms the window with the caller-minted code', () => {
+    const { state, code } = openHostCodeWindow(createHostCodeState<number>(), { code: '123456' });
+    expect(state.phase).toBe('awaiting-host-code');
+    expect(code).toBe('123456');
+    expect(state.code).toBe('123456');
+    // No TTL by default — the window lives as long as the channel runs unpaired.
+    expect(state.expiresAt).toBeNull();
+  });
+
+  it('submitPeerCode pairs the presenting peer on the correct code', () => {
+    const { state } = openHostCodeWindow(createHostCodeState<number>(), { code: '123456' });
+    const r = submitPeerCode(state, 1, '123456');
+    expect(r.action.kind).toBe('paired');
+    expect(r.state.phase).toBe('paired');
+    expect(r.state.authorizedPeer).toBe(1);
+    expect(isPeerAuthorized(r.state, 1)).toBe(true);
+  });
+
+  it('accepts the code with surrounding whitespace', () => {
+    const { state } = openHostCodeWindow(createHostCodeState<number>(), { code: '123456' });
+    const r = submitPeerCode(state, 7, '  123 456 ');
+    expect(r.action.kind).toBe('paired');
+    expect(r.state.authorizedPeer).toBe(7);
+  });
+
+  it('reports a mismatch on a wrong or non-code message', () => {
+    const { state } = openHostCodeWindow(createHostCodeState<number>(), { code: '123456' });
+    expect(submitPeerCode(state, 1, '654321').action.kind).toBe('mismatch');
+    expect(submitPeerCode(state, 1, 'hello!').action.kind).toBe('mismatch');
+    expect(submitPeerCode(state, 1, '').action.kind).toBe('mismatch');
+  });
+
+  it('reports not-pending when no window is open', () => {
+    const r = submitPeerCode(createHostCodeState<number>(), 1, '123456');
+    expect(r.action.kind).toBe('not-pending');
+  });
+
+  it('acknowledges the already-paired peer (idempotent)', () => {
+    const r = submitPeerCode(createHostCodeState({ authorizedPeer: 5 }), 5, '123456');
+    expect(r.action.kind).toBe('still-paired');
+  });
+
+  it('rejects a different peer once one is paired', () => {
+    const r = submitPeerCode(createHostCodeState({ authorizedPeer: 5 }), 6, '123456');
+    expect(r.action.kind).toBe('rejected-foreign-peer');
+  });
+
+  it('expires after the optional TTL window', () => {
+    const t0 = 1_000_000;
+    const { state } = openHostCodeWindow(createHostCodeState<number>(), {
+      code: '123456',
+      now: t0,
+      ttlMs: 1000,
+    });
+    const r = submitPeerCode(state, 1, '123456', t0 + 2000);
+    expect(r.action.kind).toBe('expired');
+    expect(r.state.phase).toBe('expired');
+  });
+
+  it('works with string peers (thread / JID style ids)', () => {
+    const { state } = openHostCodeWindow(createHostCodeState<string>(), { code: '987654' });
+    const r = submitPeerCode(state, 'chat:abc', '987654');
+    expect(r.action.kind).toBe('paired');
+    expect(isPeerAuthorized(r.state, 'chat:abc')).toBe(true);
+    expect(isPeerAuthorized(r.state, 'chat:zzz')).toBe(false);
+  });
+
+  it('clearHostCodePairing forgets everything', () => {
+    const s = clearHostCodePairing(createHostCodeState({ authorizedPeer: 5 }));
+    expect(s.phase).toBe('idle');
+    expect(s.authorizedPeer).toBeNull();
+    expect(s.code).toBeNull();
+  });
+});
+
+describe('greetPeer (bare hello, no code presented)', () => {
+  it('nudges toward starting pairing when no window is open', () => {
+    expect(greetPeer(createHostCodeState<number>(), 1).action.kind).toBe('no-window');
+  });
+
+  it('nudges toward the QR / code while a window is open', () => {
+    const { state } = openHostCodeWindow(createHostCodeState<number>(), { code: '123456' });
+    expect(greetPeer(state, 1).action.kind).toBe('window-open-hint');
+  });
+
+  it('acknowledges the already-paired peer', () => {
+    expect(greetPeer(createHostCodeState({ authorizedPeer: 7 }), 7).action.kind).toBe(
+      'still-paired',
+    );
+  });
+
+  it('rejects a different peer when one is paired', () => {
+    expect(greetPeer(createHostCodeState({ authorizedPeer: 7 }), 999).action.kind).toBe(
+      'rejected-foreign-peer',
+    );
+  });
+});

package/src/pairing/host-code.ts

@@ -0,0 +1,159 @@
+/**
+ * Host-issued-code pairing — the pure state machine behind Telegram's QR /
+ * deep-link chat pairing, generic over the peer identifier (a Telegram chat id,
+ * a Discord DM channel, a WhatsApp JID, ...).
+ *
+ * A control surface (desktop Channels panel, `moxxy channels <name> pair` in a
+ * terminal) opens a window with {@link openHostCodeWindow}: the code is minted
+ * UP FRONT by the caller so the surface can embed it in a deep link and render
+ * that as a QR. The user scans / opens the link (the messenger round-trips the
+ * code back to the bot) or simply sends the code as a message; the channel
+ * calls {@link submitPeerCode}, and on match that peer is authorized.
+ *
+ * Security property: "prove you can see the host's screen" — the code only ever
+ * lives on the surface. No TTL by default: the window's lifetime is the channel
+ * process's lifetime while unpaired; a caller may still bound it with `ttlMs`.
+ *
+ * Decisions carry semantic `kind`s only — user-facing messages (and their
+ * channel-specific wording, e.g. "run `moxxy channels telegram pair`") are
+ * mapped by each channel.
+ */
+
+export type HostCodePhase =
+  | 'idle'
+  // Host generated a code and is waiting for a peer to present it.
+  | 'awaiting-host-code'
+  | 'paired'
+  | 'expired';
+
+export interface HostCodeState<P> {
+  readonly phase: HostCodePhase;
+  readonly code: string | null;
+  readonly expiresAt: number | null;
+  readonly authorizedPeer: P | null;
+}
+
+export type HostCodeAction<P> =
+  /** The presented code matched — the peer is now authorized. */
+  | { readonly kind: 'paired'; readonly peer: P }
+  /** The already-authorized peer showed up again (idempotent; greet it). */
+  | { readonly kind: 'still-paired'; readonly peer: P }
+  /** A DIFFERENT peer while one is authorized — access denied. */
+  | { readonly kind: 'rejected-foreign-peer' }
+  /** Bare hello while a window is open — nudge toward the QR / code. */
+  | { readonly kind: 'window-open-hint' }
+  /** Bare hello with no window open — nudge toward starting pairing. */
+  | { readonly kind: 'no-window' }
+  /** A code was presented but no window is open. */
+  | { readonly kind: 'not-pending' }
+  /** The window's optional TTL elapsed. */
+  | { readonly kind: 'expired' }
+  /** The presented code didn't match. */
+  | { readonly kind: 'mismatch' };
+
+export interface HostCodeDecision<P> {
+  readonly state: HostCodeState<P>;
+  readonly action: HostCodeAction<P>;
+}
+
+export function createHostCodeState<P>(
+  opts: { authorizedPeer?: P | null } = {},
+): HostCodeState<P> {
+  return {
+    phase: opts.authorizedPeer != null ? 'paired' : 'idle',
+    code: null,
+    expiresAt: null,
+    authorizedPeer: opts.authorizedPeer ?? null,
+  };
+}
+
+/**
+ * Open a host-issued pairing window with a pre-minted code (the caller mints it
+ * so it can embed the code in the deep link / QR it shows the user).
+ */
+export function openHostCodeWindow<P>(
+  state: HostCodeState<P>,
+  opts: { code: string; now?: number; ttlMs?: number | null },
+): { state: HostCodeState<P>; code: string } {
+  const ttlMs = opts.ttlMs ?? null;
+  const now = opts.now ?? Date.now();
+  return {
+    state: {
+      ...state,
+      phase: 'awaiting-host-code',
+      code: opts.code,
+      expiresAt: ttlMs == null ? null : now + ttlMs,
+    },
+    code: opts.code,
+  };
+}
+
+/**
+ * A peer said hello WITHOUT presenting a code (e.g. a bare Telegram `/start` —
+ * the user opened the chat manually rather than via the pairing deep link).
+ */
+export function greetPeer<P>(state: HostCodeState<P>, peer: P): HostCodeDecision<P> {
+  if (state.authorizedPeer === peer && state.phase === 'paired') {
+    return { state, action: { kind: 'still-paired', peer } };
+  }
+  if (state.authorizedPeer !== null && state.authorizedPeer !== peer) {
+    return { state, action: { kind: 'rejected-foreign-peer' } };
+  }
+  if (state.phase === 'awaiting-host-code') {
+    return { state, action: { kind: 'window-open-hint' } };
+  }
+  return { state, action: { kind: 'no-window' } };
+}
+
+/**
+ * A peer PRESENTED a code (deep-link payload or a plain message). Whitespace is
+ * stripped before comparing; on match the peer is authorized.
+ */
+export function submitPeerCode<P>(
+  state: HostCodeState<P>,
+  peer: P,
+  rawCode: string,
+  now: number = Date.now(),
+): HostCodeDecision<P> {
+  if (state.phase === 'paired' && state.authorizedPeer === peer) {
+    return { state, action: { kind: 'still-paired', peer } };
+  }
+  if (state.authorizedPeer !== null && state.authorizedPeer !== peer) {
+    return { state, action: { kind: 'rejected-foreign-peer' } };
+  }
+  if (state.phase !== 'awaiting-host-code') {
+    return { state, action: { kind: 'not-pending' } };
+  }
+  if (state.expiresAt !== null && now > state.expiresAt) {
+    return {
+      state: { ...state, phase: 'expired', code: null, expiresAt: null },
+      action: { kind: 'expired' },
+    };
+  }
+  const normalized = rawCode.replace(/\s+/g, '');
+  if (!normalized || normalized !== state.code) {
+    return { state, action: { kind: 'mismatch' } };
+  }
+  return {
+    state: {
+      phase: 'paired',
+      code: null,
+      expiresAt: null,
+      authorizedPeer: peer,
+    },
+    action: { kind: 'paired', peer },
+  };
+}
+
+export function isPeerAuthorized<P>(state: HostCodeState<P>, peer: P): boolean {
+  return state.phase === 'paired' && state.authorizedPeer === peer;
+}
+
+export function clearHostCodePairing<P>(_state: HostCodeState<P>): HostCodeState<P> {
+  return {
+    phase: 'idle',
+    code: null,
+    expiresAt: null,
+    authorizedPeer: null,
+  };
+}

package/src/pairing/tofu.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it, vi } from 'vitest';
+import { TofuPairingWindow } from './tofu.js';
+
+interface Candidate {
+  readonly teamId: string;
+  readonly channelId: string;
+}
+
+describe('TofuPairingWindow', () => {
+  it('ignores candidates while disarmed', () => {
+    const w = new TofuPairingWindow<Candidate>();
+    const seen: Candidate[] = [];
+    w.onCandidate((c) => seen.push(c));
+    expect(w.offer({ teamId: 'T1', channelId: 'C1' })).toBe(false);
+    expect(seen).toHaveLength(0);
+  });
+
+  it('captures and consumes candidates while armed', () => {
+    const w = new TofuPairingWindow<Candidate>();
+    const seen: Candidate[] = [];
+    w.onCandidate((c) => seen.push(c));
+    w.arm();
+    expect(w.isArmed).toBe(true);
+    expect(w.offer({ teamId: 'T1', channelId: 'C1' })).toBe(true);
+    expect(seen).toEqual([{ teamId: 'T1', channelId: 'C1' }]);
+  });
+
+  it('stays armed until disarmed (operator confirms out of band)', () => {
+    const w = new TofuPairingWindow<Candidate>();
+    w.arm();
+    expect(w.offer({ teamId: 'T1', channelId: 'C1' })).toBe(true);
+    expect(w.offer({ teamId: 'T2', channelId: 'C2' })).toBe(true);
+    w.disarm();
+    expect(w.isArmed).toBe(false);
+    expect(w.offer({ teamId: 'T3', channelId: 'C3' })).toBe(false);
+  });
+
+  it('unsubscribe stops a listener', () => {
+    const w = new TofuPairingWindow<Candidate>();
+    const seen: Candidate[] = [];
+    const unsubscribe = w.onCandidate((c) => seen.push(c));
+    w.arm();
+    w.offer({ teamId: 'T1', channelId: 'C1' });
+    unsubscribe();
+    w.offer({ teamId: 'T2', channelId: 'C2' });
+    expect(seen).toEqual([{ teamId: 'T1', channelId: 'C1' }]);
+  });
+
+  it('a throwing listener is reported and never breaks the offer', () => {
+    const onListenerError = vi.fn();
+    const w = new TofuPairingWindow<Candidate>({ onListenerError });
+    const seen: Candidate[] = [];
+    w.onCandidate(() => {
+      throw new Error('boom');
+    });
+    w.onCandidate((c) => seen.push(c));
+    w.arm();
+    expect(w.offer({ teamId: 'T1', channelId: 'C1' })).toBe(true);
+    expect(onListenerError).toHaveBeenCalledTimes(1);
+    expect(seen).toHaveLength(1);
+  });
+});

package/src/pairing/tofu.ts

@@ -0,0 +1,60 @@
+/**
+ * Trust-on-first-use pairing window — the mechanism behind Slack's pair flow,
+ * generic over the candidate shape (Slack: `{ teamId, channelId }`).
+ *
+ * A pair flow arms the window, then the channel's ingest path `offer`s every
+ * verified inbound event's origin. While armed, the first candidate is captured
+ * (listeners — the interactive pair flow — are notified and ask the operator to
+ * confirm) and CONSUMED, so the very first message just establishes trust
+ * rather than driving a turn. Confirmation + persistence stay with the channel
+ * (it owns the vault key format); it calls `disarm()` once authorized.
+ */
+export interface TofuPairingWindowOptions {
+  /** Observe a listener throwing (channels log it); never propagates. */
+  readonly onListenerError?: (err: unknown) => void;
+}
+
+export class TofuPairingWindow<C> {
+  private armed = false;
+  private readonly listeners = new Set<(candidate: C) => void>();
+  private readonly opts: TofuPairingWindowOptions;
+
+  constructor(opts: TofuPairingWindowOptions = {}) {
+    this.opts = opts;
+  }
+
+  get isArmed(): boolean {
+    return this.armed;
+  }
+
+  arm(): void {
+    this.armed = true;
+  }
+
+  disarm(): void {
+    this.armed = false;
+  }
+
+  /** Subscribe to captured candidates. Returns an unsubscribe function. */
+  onCandidate(listener: (candidate: C) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /**
+   * Present a verified inbound origin. While armed, notifies listeners and
+   * returns true — the event was consumed by pairing and must NOT also drive a
+   * turn. Returns false when no window is armed.
+   */
+  offer(candidate: C): boolean {
+    if (!this.armed) return false;
+    for (const listener of this.listeners) {
+      try {
+        listener(candidate);
+      } catch (err) {
+        this.opts.onListenerError?.(err);
+      }
+    }
+    return true;
+  }
+}

package/src/permission.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { PendingToolCall, PermissionContext } from '@moxxy/sdk';
+import { createAuditedAllowListResolver } from './permission.js';
+
+const ctx: PermissionContext = { sessionId: 's1' };
+function call(name: string): PendingToolCall {
+  return { callId: `c_${name}`, name, input: {} };
+}
+
+describe('createAuditedAllowListResolver', () => {
+  it('auto-approves a listed tool and denies an unlisted one', async () => {
+    const r = createAuditedAllowListResolver({
+      name: 'test-allow-list',
+      allowedTools: ['Read', 'Grep'],
+      allToolNames: ['Read', 'Grep', 'Bash', 'Write'],
+    });
+    expect((await r.check(call('Read'), ctx)).mode).not.toBe('deny');
+    expect((await r.check(call('Bash'), ctx)).mode).toBe('deny');
+  });
+
+  it('denies everything when the allow-list is empty (read-only)', async () => {
+    const r = createAuditedAllowListResolver({
+      name: 'test-allow-list',
+      allowedTools: [],
+      allToolNames: ['Read', 'Bash'],
+    });
+    expect((await r.check(call('Read'), ctx)).mode).toBe('deny');
+    expect((await r.check(call('Bash'), ctx)).mode).toBe('deny');
+  });
+
+  it('expands "*" to every registered tool name', async () => {
+    const r = createAuditedAllowListResolver({
+      name: 'test-allow-list',
+      allowedTools: ['*'],
+      allToolNames: ['Read', 'Bash'],
+    });
+    expect((await r.check(call('Read'), ctx)).mode).not.toBe('deny');
+    expect((await r.check(call('Bash'), ctx)).mode).not.toBe('deny');
+    // A name not in the registry is still denied even under '*'.
+    expect((await r.check(call('NotRegistered'), ctx)).mode).toBe('deny');
+  });
+
+  it('fires the audit hook for approvals only, flagging wildcard expansion', async () => {
+    const onAutoApprove = vi.fn();
+    const r = createAuditedAllowListResolver({
+      name: 'test-allow-list',
+      allowedTools: ['*'],
+      allToolNames: ['Read'],
+      onAutoApprove,
+    });
+    await r.check(call('Read'), ctx);
+    expect(onAutoApprove).toHaveBeenCalledTimes(1);
+    expect(onAutoApprove.mock.calls[0]?.[0]).toMatchObject({ name: 'Read' });
+    expect(onAutoApprove.mock.calls[0]?.[1]).toEqual({ wildcard: true });
+
+    onAutoApprove.mockClear();
+    await r.check(call('Denied'), ctx);
+    expect(onAutoApprove).not.toHaveBeenCalled();
+  });
+
+  it('carries the given resolver name', () => {
+    const r = createAuditedAllowListResolver({
+      name: 'my-channel-allow-list',
+      allowedTools: [],
+      allToolNames: [],
+    });
+    expect(r.name).toBe('my-channel-allow-list');
+  });
+});

package/src/permission.ts

@@ -0,0 +1,46 @@
+import { createAllowListResolver } from '@moxxy/sdk';
+import type { PendingToolCall, PermissionResolver } from '@moxxy/sdk';
+
+/**
+ * Autonomous allow-list permission resolver with an audit hook — the shared
+ * wiring for hands-off channels (Slack-style: no human in the loop; the
+ * operator declares trust upfront via an `allowedTools` list).
+ *
+ * Reuses the SDK's {@link createAllowListResolver} (exact-name match →
+ * `allow_session`, else `deny`) rather than re-implementing the trust check,
+ * and adds the two things every autonomous channel needs:
+ *
+ *   - `'*'` expansion — `['*']` means "allow every registered tool", expanded
+ *     against `allToolNames` at channel-start time (mirrors the CLI's
+ *     `--allow-all`). An empty list denies everything (effectively read-only).
+ *   - an audit hook — `onAutoApprove` fires for every non-denied call so an
+ *     autonomous run leaves a trail of what it ran (channels log it).
+ */
+export interface AuditedAllowListOptions {
+  /** Resolver name surfaced in permission events (e.g. 'slack-allow-list'). */
+  readonly name: string;
+  readonly allowedTools: ReadonlyArray<string>;
+  /** Every registered tool name — the expansion target for `'*'`. */
+  readonly allToolNames: ReadonlyArray<string>;
+  readonly onAutoApprove?: (
+    call: PendingToolCall,
+    info: { readonly wildcard: boolean },
+  ) => void;
+}
+
+export function createAuditedAllowListResolver(opts: AuditedAllowListOptions): PermissionResolver {
+  const wildcard = opts.allowedTools.includes('*');
+  const effective = wildcard ? [...opts.allToolNames] : [...opts.allowedTools];
+  const inner = createAllowListResolver(effective);
+
+  return {
+    name: opts.name,
+    async check(call, ctx) {
+      const decision = await inner.check(call, ctx);
+      if (decision.mode !== 'deny') {
+        opts.onAutoApprove?.(call, { wildcard });
+      }
+      return decision;
+    },
+  };
+}