typeclaw 0.1.4 → 0.1.6

package/src/role-claim/client.ts

@@ -0,0 +1,182 @@
+import type {
+  ClaimCompletedPayload,
+  ClaimErrorPayload,
+  ClaimStartedPayload,
+  ClientMessage,
+  ServerMessage,
+} from '@/shared'
+
+import { generateClaimCode } from './code'
+
+export type ClaimSessionOptions = {
+  url: string
+  role: string
+  channel?: string
+  ttlMs?: number
+  connectTimeoutMs?: number
+  onStarted?: (payload: ClaimStartedPayload) => void
+}
+
+export type ClaimSessionResult =
+  | { kind: 'completed'; payload: ClaimCompletedPayload }
+  | { kind: 'error'; payload: ClaimErrorPayload }
+  | { kind: 'timeout' }
+
+const DEFAULT_TTL_MS = 10 * 60 * 1000
+const DEFAULT_CONNECT_TIMEOUT_MS = 30_000
+
+export async function runClaimSession(opts: ClaimSessionOptions): Promise<ClaimSessionResult> {
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS
+  const connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS
+  const code = generateClaimCode()
+
+  const ws = new WebSocket(opts.url)
+  const displayUrl = redactUrl(opts.url)
+  await waitForOpen(ws, displayUrl, connectTimeoutMs)
+  await waitForConnected(ws, displayUrl, connectTimeoutMs)
+
+  try {
+    const request: ClientMessage = {
+      type: 'claim_start',
+      code,
+      role: opts.role,
+      ttlMs,
+      ...(opts.channel !== undefined ? { channel: opts.channel } : {}),
+    }
+    ws.send(JSON.stringify(request))
+
+    return await waitForOutcome(ws, code, ttlMs, opts.onStarted)
+  } finally {
+    try {
+      const cancel: ClientMessage = { type: 'claim_cancel' }
+      ws.send(JSON.stringify(cancel))
+    } catch {}
+    ws.close()
+  }
+}
+
+async function waitForOpen(ws: WebSocket, displayUrl: string, timeoutMs: number): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup()
+      ws.close()
+      reject(new Error(`timed out connecting to ${displayUrl} after ${timeoutMs}ms`))
+    }, timeoutMs)
+    const onOpen = () => {
+      cleanup()
+      resolve()
+    }
+    const onError = (err: unknown) => {
+      cleanup()
+      reject(new Error(`failed to connect to ${displayUrl}: ${err instanceof Error ? err.message : String(err)}`))
+    }
+    const onClose = () => {
+      cleanup()
+      reject(new Error(`connection to ${displayUrl} closed before opening`))
+    }
+    const cleanup = () => {
+      clearTimeout(timer)
+      ws.removeEventListener('open', onOpen)
+      ws.removeEventListener('error', onError)
+      ws.removeEventListener('close', onClose)
+    }
+    ws.addEventListener('open', onOpen, { once: true })
+    ws.addEventListener('error', onError, { once: true })
+    ws.addEventListener('close', onClose, { once: true })
+  })
+}
+
+// The server's WS `open` handler is async (it awaits createSession) and only
+// registers per-ws state and sends `connected` after that resolves. Bun
+// delivers any client messages received before `open` completes, but the
+// server's `claim_start` handler silently drops messages when state is null.
+// Waiting here mirrors what the TUI client does (see src/tui/index.ts) and
+// fixes the hatching-time hang where the spinner stayed on "Generating your
+// claim code..." until the ttl expired.
+async function waitForConnected(ws: WebSocket, displayUrl: string, timeoutMs: number): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup()
+      ws.close()
+      reject(new Error(`timed out waiting for connected message from ${displayUrl} after ${timeoutMs}ms`))
+    }, timeoutMs)
+    const onMessage = (event: MessageEvent): void => {
+      let msg: ServerMessage
+      try {
+        msg = JSON.parse(String(event.data)) as ServerMessage
+      } catch {
+        return
+      }
+      if (msg.type === 'connected') {
+        cleanup()
+        resolve()
+        return
+      }
+      if (msg.type === 'error') {
+        cleanup()
+        reject(new Error(`server rejected connection to ${displayUrl}: ${msg.message}`))
+      }
+    }
+    const onClose = () => {
+      cleanup()
+      reject(new Error(`connection to ${displayUrl} closed before the session was ready`))
+    }
+    const cleanup = () => {
+      clearTimeout(timer)
+      ws.removeEventListener('message', onMessage)
+      ws.removeEventListener('close', onClose)
+    }
+    ws.addEventListener('message', onMessage)
+    ws.addEventListener('close', onClose, { once: true })
+  })
+}
+
+async function waitForOutcome(
+  ws: WebSocket,
+  code: string,
+  ttlMs: number,
+  onStarted?: (payload: ClaimStartedPayload) => void,
+): Promise<ClaimSessionResult> {
+  return new Promise<ClaimSessionResult>((resolve) => {
+    const timer = setTimeout(() => {
+      ws.removeEventListener('message', onMessage)
+      resolve({ kind: 'timeout' })
+    }, ttlMs + 5_000)
+
+    const onMessage = (event: MessageEvent): void => {
+      let msg: ServerMessage
+      try {
+        msg = JSON.parse(String(event.data)) as ServerMessage
+      } catch {
+        return
+      }
+      if (msg.type === 'claim_started' && msg.payload.code === code) {
+        onStarted?.(msg.payload)
+        return
+      }
+      if (msg.type === 'claim_completed' && msg.payload.code === code) {
+        clearTimeout(timer)
+        ws.removeEventListener('message', onMessage)
+        resolve({ kind: 'completed', payload: msg.payload })
+        return
+      }
+      if (msg.type === 'claim_error' && msg.payload.code === code) {
+        clearTimeout(timer)
+        ws.removeEventListener('message', onMessage)
+        resolve({ kind: 'error', payload: msg.payload })
+        return
+      }
+    }
+    ws.addEventListener('message', onMessage)
+  })
+}
+
+function redactUrl(url: string): string {
+  try {
+    const parsed = new URL(url)
+    if (parsed.searchParams.has('token')) parsed.searchParams.set('token', '<redacted>')
+    return parsed.toString()
+  } catch {
+    return url
+  }
+}

package/src/role-claim/code.ts

@@ -0,0 +1,53 @@
+import { randomBytes } from 'node:crypto'
+
+// Role-claim codes are short, human-typeable tokens the operator sends from
+// their host CLI to the bot via a channel DM to prove ownership of that
+// channel identity. Shape: `claim-XXXX-YYYY` where each block is 4 chars
+// from a Crockford-style base32 alphabet (0-9 + A-Z minus I, L, O, U to
+// dodge OCR-confusable / profane shapes). 8 chars * 5 bits = 40 bits of
+// entropy, which is overkill for a TTL'd in-memory window but cheap to
+// display and dictate over voice.
+//
+// The `claim-` prefix lets the channel router recognize potential claim
+// attempts in a DM body without scanning the whole text for hex blocks,
+// and distinguishes claim DMs from normal first-message text like "hi"
+// which would otherwise need a regex of its own to disambiguate.
+
+export const CLAIM_CODE_PREFIX = 'claim-'
+
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+const BLOCK_SIZE = 4
+const BLOCK_COUNT = 2
+
+export function generateClaimCode(): string {
+  const bytes = randomBytes(BLOCK_SIZE * BLOCK_COUNT)
+  const chars: string[] = []
+  for (let i = 0; i < bytes.length; i++) {
+    chars.push(ALPHABET[bytes[i]! % ALPHABET.length]!)
+  }
+  const blocks: string[] = []
+  for (let b = 0; b < BLOCK_COUNT; b++) {
+    blocks.push(chars.slice(b * BLOCK_SIZE, (b + 1) * BLOCK_SIZE).join(''))
+  }
+  return `${CLAIM_CODE_PREFIX}${blocks.join('-')}`
+}
+
+// Extracts the first claim-code-shaped token from inbound text. Returns
+// the canonical-case (upper) code, or null. Tolerates surrounding
+// whitespace, punctuation, and case — chat clients may auto-correct case
+// or surround pastes with quotes/backticks.
+export function extractClaimCode(text: string): string | null {
+  const pattern = new RegExp(
+    `${CLAIM_CODE_PREFIX}([0-9a-zA-Z]{${BLOCK_SIZE}}(?:-[0-9a-zA-Z]{${BLOCK_SIZE}}){${BLOCK_COUNT - 1}})`,
+    'i',
+  )
+  const match = pattern.exec(text)
+  if (!match) return null
+  return `${CLAIM_CODE_PREFIX}${match[1]!.toUpperCase()}`
+}
+
+export function normalizeClaimCode(code: string): string {
+  const trimmed = code.trim()
+  if (!trimmed.toLowerCase().startsWith(CLAIM_CODE_PREFIX)) return trimmed.toUpperCase()
+  return `${CLAIM_CODE_PREFIX}${trimmed.slice(CLAIM_CODE_PREFIX.length).toUpperCase()}`
+}

package/src/role-claim/controller.ts

@@ -0,0 +1,194 @@
+import type { ClaimHandler } from '@/channels/router'
+import { grantRole, type PermissionService } from '@/permissions'
+
+import { extractClaimCode } from './code'
+import { formatClaimMatchRule } from './match-rule'
+import { createPendingClaimRegistry, type PendingClaim, type PendingClaimRegistry } from './pending'
+
+// ClaimController is the runtime singleton that ties the four moving parts
+// of the role-claim flow together:
+//
+//   1. The host CLI (typeclaw role claim) opens a WS and sends `claim_start`.
+//   2. The WS server forwards that to controller.startClaim().
+//   3. The channel router's claimHandler (also wired here) intercepts DMs
+//      bearing the code and calls controller.tryConsumeInbound().
+//   4. On consume, the controller writes to typeclaw.json#roles.<role>.match
+//      via grantRole, then reloads the live PermissionService so the new
+//      match rule takes effect without a container restart.
+//
+// Result events (completed / error / cancelled) are pushed to subscribers
+// the WS server registers, so the host CLI's open WS receives the outcome
+// over the same connection.
+
+export type ClaimCompletedEvent = {
+  kind: 'completed'
+  code: string
+  role: string
+  matchRule: string
+  adapter: string
+  authorId: string
+}
+
+export type ClaimErrorEvent = {
+  kind: 'error'
+  code: string
+  reason: string
+}
+
+export type ClaimCancelledEvent = {
+  kind: 'cancelled'
+  code: string
+}
+
+export type ClaimResultEvent = ClaimCompletedEvent | ClaimErrorEvent | ClaimCancelledEvent
+
+export type ClaimController = {
+  startClaim: (input: { code: string; role: string; channel?: string; ttlMs: number }) =>
+    | {
+        ok: true
+        expiresAt: number
+      }
+    | { ok: false; reason: string }
+  cancelClaim: (code: string) => boolean
+  current: () => PendingClaim | null
+  onResult: (subscriber: (event: ClaimResultEvent) => void) => () => void
+  claimHandler: ClaimHandler
+}
+
+export type CreateClaimControllerOptions = {
+  cwd: string
+  permissions: PermissionService
+  rolesProvider: () => import('@/permissions').RolesConfig | undefined
+  now?: () => number
+  registry?: PendingClaimRegistry
+  // Test seam: injectable role granter so tests don't touch disk. Production
+  // wires the real `grantRole` from src/permissions/grant.ts.
+  grant?: (roleName: string, matchRule: string) => { ok: true; added: boolean } | { ok: false; reason: string }
+  logger?: { info: (m: string) => void; warn: (m: string) => void; error: (m: string) => void }
+}
+
+const KNOWN_BUILT_IN_ROLES = new Set(['owner', 'member', 'trusted'])
+
+export function createClaimController(opts: CreateClaimControllerOptions): ClaimController {
+  const now = opts.now ?? Date.now
+  const registry = opts.registry ?? createPendingClaimRegistry({ now })
+  const grant =
+    opts.grant ?? ((roleName: string, matchRule: string) => grantRole({ cwd: opts.cwd, roleName, matchRule }))
+  const logger = opts.logger ?? defaultLogger
+  const subscribers = new Set<(event: ClaimResultEvent) => void>()
+
+  const emit = (event: ClaimResultEvent): void => {
+    for (const sub of subscribers) {
+      try {
+        sub(event)
+      } catch (err) {
+        logger.warn(`[role-claim] subscriber threw: ${describe(err)}`)
+      }
+    }
+  }
+
+  const startClaim: ClaimController['startClaim'] = ({ code, role, channel, ttlMs }) => {
+    if (!isValidRoleName(role)) {
+      return { ok: false, reason: `unknown role '${role}' — built-in roles are owner, member, trusted` }
+    }
+    const startedAt = now()
+    const pending: PendingClaim = {
+      code,
+      role,
+      ttlMs,
+      startedAt,
+      expiresAt: startedAt + ttlMs,
+      ...(channel !== undefined ? { channel } : {}),
+    }
+    registry.start(pending)
+    return { ok: true, expiresAt: pending.expiresAt }
+  }
+
+  const claimHandler: ClaimHandler = async (input) => {
+    const code = extractClaimCode(input.text)
+    if (code === null) return { kind: 'fallthrough' }
+
+    const result = registry.tryConsume(
+      code,
+      {
+        adapter: input.adapter,
+        workspace: input.workspace,
+        chat: input.chat,
+        isDm: input.isDm,
+        authorId: input.authorId,
+      },
+      formatClaimMatchRule,
+    )
+
+    if (result.kind === 'no-pending') return { kind: 'fallthrough' }
+    if (result.kind === 'no-match') return { kind: 'fallthrough' }
+    if (result.kind === 'wrong-channel') {
+      const reply = `That claim is for a different channel — please run typeclaw role claim again on this one.`
+      emit({ kind: 'error', code, reason: 'wrong-channel' })
+      return { kind: 'fail', reply }
+    }
+    if (result.kind === 'expired') {
+      const reply = `That claim code has expired. Run typeclaw role claim again to start a new one.`
+      emit({ kind: 'error', code, reason: 'expired' })
+      return { kind: 'fail', reply }
+    }
+
+    const granted = grant(result.role, result.matchRule)
+    if (!granted.ok) {
+      const reply = `Sorry, I couldn't save your role: ${granted.reason}`
+      emit({ kind: 'error', code, reason: granted.reason })
+      return { kind: 'fail', reply }
+    }
+
+    try {
+      opts.permissions.replaceRoles(opts.rolesProvider())
+    } catch (err) {
+      logger.warn(`[role-claim] replaceRoles failed after grant: ${describe(err)}`)
+    }
+
+    emit({
+      kind: 'completed',
+      code,
+      role: result.role,
+      matchRule: result.matchRule,
+      adapter: result.origin.adapter,
+      authorId: result.origin.authorId,
+    })
+
+    const noteAdded = granted.added ? '' : ' (already on file)'
+    const reply = `You're paired as ${result.role}${noteAdded}. Welcome aboard!`
+    return { kind: 'consumed', reply }
+  }
+
+  return {
+    startClaim,
+    cancelClaim: (code) => {
+      const cancelled = registry.cancel(code)
+      if (cancelled) emit({ kind: 'cancelled', code })
+      return cancelled
+    },
+    current: () => registry.current(),
+    onResult: (sub) => {
+      subscribers.add(sub)
+      return () => {
+        subscribers.delete(sub)
+      }
+    },
+    claimHandler,
+  }
+}
+
+function isValidRoleName(role: string): boolean {
+  if (KNOWN_BUILT_IN_ROLES.has(role)) return true
+  return /^[a-z][a-z0-9-]*$/.test(role) && role !== 'guest'
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+const defaultLogger = {
+  info: (m: string) => console.log(m),
+  warn: (m: string) => console.warn(m),
+  error: (m: string) => console.error(m),
+}

package/src/role-claim/index.ts

@@ -0,0 +1,19 @@
+export { runClaimSession, type ClaimSessionOptions, type ClaimSessionResult } from './client'
+export { CLAIM_CODE_PREFIX, extractClaimCode, generateClaimCode, normalizeClaimCode } from './code'
+export {
+  createClaimController,
+  type ClaimCancelledEvent,
+  type ClaimCompletedEvent,
+  type ClaimController,
+  type ClaimErrorEvent,
+  type ClaimResultEvent,
+  type CreateClaimControllerOptions,
+} from './controller'
+export { formatClaimMatchRule, type PartialChannelOrigin } from './match-rule'
+export {
+  createPendingClaimRegistry,
+  type ClaimResult,
+  type PendingClaim,
+  type PendingClaimRegistry,
+  type PendingClaimRegistryOptions,
+} from './pending'

package/src/role-claim/match-rule.ts

@@ -0,0 +1,43 @@
+// Builds a canonical match-rule DSL string from an inbound channel origin,
+// for the role table. Output shapes:
+//
+//   slack:T0123 author:U_ALICE
+//   discord:9999 author:U_ALICE
+//   telegram:42 author:U_ALICE
+//   kakao:dm/<chatId> author:<authorId>
+//
+// The author qualifier is always emitted so a claim grants the specific
+// human, not the whole workspace. To grant the whole workspace, the
+// operator edits typeclaw.json by hand or runs a future `typeclaw role grant`
+// without --claim.
+
+import type { ChannelKey } from '@/channels/types'
+
+export type PartialChannelOrigin = {
+  adapter: ChannelKey['adapter']
+  workspace: string
+  chat: string
+  isDm: boolean
+  authorId: string
+}
+
+const ADAPTER_TO_PLATFORM: Record<ChannelKey['adapter'], 'slack' | 'discord' | 'telegram' | 'kakao'> = {
+  'slack-bot': 'slack',
+  'discord-bot': 'discord',
+  'telegram-bot': 'telegram',
+  kakaotalk: 'kakao',
+}
+
+export function formatClaimMatchRule(origin: PartialChannelOrigin): string {
+  const platform = ADAPTER_TO_PLATFORM[origin.adapter]
+  const authorQual = ` author:${origin.authorId}`
+  if (origin.adapter === 'kakaotalk') {
+    // Kakao has no workspace; routes use dm/group/open buckets. We can't
+    // know which bucket from a partial origin alone (adapter-side classifies
+    // it), so claim flows are restricted to DM and we emit the specific
+    // chat-id form so the rule grants only this 1:1 conversation, not every
+    // DM the agent is in.
+    return `${platform}:dm/${origin.chat}${authorQual}`
+  }
+  return `${platform}:${origin.workspace}${authorQual}`
+}

package/src/role-claim/pending.ts

@@ -0,0 +1,100 @@
+import type { PartialChannelOrigin } from './match-rule'
+
+export type PendingClaim = {
+  code: string
+  role: string
+  channel?: string
+  ttlMs: number
+  startedAt: number
+  expiresAt: number
+}
+
+export type ClaimResult =
+  | { kind: 'consumed'; code: string; role: string; matchRule: string; origin: PartialChannelOrigin }
+  | { kind: 'no-pending' }
+  | { kind: 'no-match' }
+  | { kind: 'expired' }
+  | { kind: 'wrong-channel' }
+
+export type PendingClaimRegistry = {
+  start: (claim: PendingClaim) => void
+  cancel: (code: string) => boolean
+  current: () => PendingClaim | null
+  // Snapshot of consumption result without actually committing the grant.
+  // The router calls this on every DM-shaped inbound; the grant only fires
+  // when the result is 'consumed'.
+  tryConsume: (
+    code: string,
+    origin: PartialChannelOrigin,
+    formatMatchRule: (origin: PartialChannelOrigin) => string,
+  ) => ClaimResult
+  size: () => number
+}
+
+export type PendingClaimRegistryOptions = {
+  now?: () => number
+}
+
+// Single-claim-at-a-time registry. A second `start` while one is pending
+// replaces the prior code (cancels it implicitly): the operator running
+// `typeclaw role claim` twice from two terminals expects the second invocation
+// to take over, not error.
+//
+// Stored in-memory only — claim sessions are short-lived (default 10 min)
+// and a container restart legitimately invalidates any pending window.
+export function createPendingClaimRegistry(opts: PendingClaimRegistryOptions = {}): PendingClaimRegistry {
+  const now = opts.now ?? Date.now
+  let pending: PendingClaim | null = null
+
+  type ExpiryCheck = { live: PendingClaim } | { live: null; reason: 'no-pending' | 'expired' }
+
+  const expireIfDue = (): ExpiryCheck => {
+    if (pending === null) return { live: null, reason: 'no-pending' }
+    if (now() >= pending.expiresAt) {
+      pending = null
+      return { live: null, reason: 'expired' }
+    }
+    return { live: pending }
+  }
+
+  return {
+    start(claim) {
+      pending = { ...claim }
+    },
+    cancel(code) {
+      if (pending !== null && pending.code === code) {
+        pending = null
+        return true
+      }
+      return false
+    },
+    current() {
+      const check = expireIfDue()
+      return check.live
+    },
+    tryConsume(code, origin, formatMatchRule) {
+      const check = expireIfDue()
+      if (check.live === null) {
+        return { kind: check.reason }
+      }
+      const live = check.live
+      if (code !== live.code) return { kind: 'no-match' }
+      if (live.channel !== undefined && live.channel !== origin.adapter) {
+        return { kind: 'wrong-channel' }
+      }
+      const matchRule = formatMatchRule(origin)
+      const consumed: ClaimResult = {
+        kind: 'consumed',
+        code: live.code,
+        role: live.role,
+        matchRule,
+        origin,
+      }
+      pending = null
+      return consumed
+    },
+    size() {
+      return expireIfDue().live === null ? 0 : 1
+    },
+  }
+}