@openparachute/agent 0.1.2 → 0.2.0

package/src/modules/permissions/sender-approval.ts

@@ -1,165 +0,0 @@
-/**
- * Unknown-sender approval flow.
- *
- * When `messaging_groups.unknown_sender_policy = 'request_approval'` and a
- * non-member writes into a wired chat, the access gate drops the routing
- * attempt and calls `requestSenderApproval` to:
- *
- *   1. Pick an eligible approver (owner / admin of the agent group).
- *   2. Open / reuse a DM to that approver on a reachable channel.
- *   3. Deliver an Approve / Deny card.
- *   4. Record a pending_sender_approvals row that holds the original message
- *      so it can be re-routed on approve.
- *
- * On approve: the handler in index.ts adds an agent_group_members row for
- * the sender and re-invokes routeInbound with the stored event — the second
- * routing attempt passes the gate because the user is now a member.
- *
- * Failure modes (logged + row NOT created, so the dedup gate lets a future
- * attempt try again):
- *   - No eligible approver in user_roles — fresh install, no owner yet.
- *   - Approver has no reachable DM (no user_dms row + channel can't
- *     openDM) — e.g. owner hasn't registered on any channel we're wired to.
- *   - Delivery adapter missing.
- *
- * Dedup: `pending_sender_approvals` has UNIQUE(messaging_group_id,
- * sender_identity). A retry / rapid second message from the same unknown
- * sender is silently dropped (no duplicate card sent).
- */
-import { normalizeOptions, type RawOption } from '../../channels/ask-question.js';
-import { getMessagingGroup } from '../../db/messaging-groups.js';
-import { getDeliveryAdapter } from '../../delivery.js';
-import { log } from '../../log.js';
-import { decodePlatformIdAs } from '../../platform-id.js';
-import type { InboundEvent } from '../../channels/adapter.js';
-import { appendFallbackNotice, pickApprovalDelivery, pickApprover } from '../approvals/primitive.js';
-import { createPendingSenderApproval, hasInFlightSenderApproval } from './db/pending-sender-approvals.js';
-
-// Three-button card per design doc PR #75 phase 4. The "always allow" branch
-// flips the messaging group's unknown_sender_policy to 'public' so future
-// strangers walk through with no gate. Shown unconditionally — even on
-// 'strict' MGs that wouldn't normally render this card — so the operator can
-// recover from a too-restrictive default with one click. The handler short-
-// circuits if the policy is already 'public', so the click is idempotent.
-const APPROVAL_OPTIONS: RawOption[] = [
-  { label: 'Allow', selectedLabel: '✅ Allowed', value: 'approve' },
-  { label: 'Allow & open channel', selectedLabel: '✅ Channel opened', value: 'approve_and_allow' },
-  { label: 'Deny', selectedLabel: '❌ Denied', value: 'reject' },
-];
-
-function generateId(): string {
-  return `nsa-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-}
-
-export interface RequestSenderApprovalInput {
-  messagingGroupId: string;
-  agentGroupId: string;
-  senderIdentity: string; // namespaced user id (channel_type:handle)
-  senderName: string | null;
-  event: InboundEvent;
-}
-
-export async function requestSenderApproval(input: RequestSenderApprovalInput): Promise<void> {
-  const { messagingGroupId, agentGroupId, senderIdentity, senderName, event } = input;
-
-  // In-flight dedup: don't spam the admin if the same unknown sender
-  // retries while a card is already pending.
-  if (hasInFlightSenderApproval(messagingGroupId, senderIdentity)) {
-    log.debug('Unknown-sender approval already in flight — dropping retry', {
-      messagingGroupId,
-      senderIdentity,
-    });
-    return;
-  }
-
-  const approvers = pickApprover(agentGroupId);
-  if (approvers.length === 0) {
-    log.warn('Unknown-sender approval skipped — no owner or admin configured', {
-      messagingGroupId,
-      agentGroupId,
-      senderIdentity,
-    });
-    return;
-  }
-
-  const originMg = getMessagingGroup(messagingGroupId);
-  const originChannelType = originMg?.channel_type ?? '';
-  const originBotId = originMg ? decodePlatformIdAs(originMg.platform_id, 'v2').botId : null;
-  const target = await pickApprovalDelivery(approvers, originChannelType, originBotId);
-  if (!target) {
-    log.warn('Unknown-sender approval skipped — no DM channel for any approver', {
-      messagingGroupId,
-      agentGroupId,
-      senderIdentity,
-    });
-    return;
-  }
-
-  const approvalId = generateId();
-  const senderDisplay = senderName && senderName.length > 0 ? senderName : senderIdentity;
-  const originName = originMg?.name ?? `a ${originChannelType} channel`;
-
-  const title = '👤 New sender';
-  const question = `${senderDisplay} wants to talk to your agent in ${originName}. Allow?`;
-  const options = normalizeOptions(APPROVAL_OPTIONS);
-
-  createPendingSenderApproval({
-    id: approvalId,
-    messaging_group_id: messagingGroupId,
-    agent_group_id: agentGroupId,
-    sender_identity: senderIdentity,
-    sender_name: senderName,
-    original_message: JSON.stringify(event),
-    approver_user_id: target.userId,
-    created_at: new Date().toISOString(),
-    title,
-    options_json: JSON.stringify(options),
-  });
-
-  const adapter = getDeliveryAdapter();
-  if (!adapter) {
-    // Without a delivery adapter, the card can't be sent. Log + leave the
-    // row in place so the admin can see it via DB or manual tooling; the
-    // dedup gate will suppress further cards until it's cleared.
-    log.error('Unknown-sender approval row created but no delivery adapter is wired', {
-      approvalId,
-    });
-    return;
-  }
-
-  try {
-    await adapter.deliver(
-      target.messagingGroup.channel_type,
-      target.messagingGroup.platform_id,
-      null,
-      'chat-sdk',
-      JSON.stringify({
-        type: 'ask_question',
-        questionId: approvalId,
-        title,
-        question: appendFallbackNotice(question, target.viaFallbackBot, originBotId),
-        options,
-      }),
-    );
-    log.info('Unknown-sender approval card delivered', {
-      approvalId,
-      senderIdentity,
-      approver: target.userId,
-      messagingGroupId,
-      agentGroupId,
-    });
-  } catch (err) {
-    log.error('Unknown-sender approval card delivery failed', {
-      approvalId,
-      err,
-    });
-  }
-}
-
-/**
- * Option value the admin clicked that means "allow" — shared with the
- * response handler so the two sides can't drift.
- */
-export const APPROVE_VALUE = 'approve';
-export const APPROVE_AND_ALLOW_VALUE = 'approve_and_allow';
-export const REJECT_VALUE = 'reject';

package/src/modules/permissions/user-dm.ts

@@ -1,200 +0,0 @@
-/**
- * User DM resolution.
- *
- * Exposes one primitive: `ensureUserDm(userId, opts?)` returns (or lazily
- * creates) the `messaging_groups` row that the host should deliver to
- * when it wants to DM a given user. Everything that needs to cold-DM a
- * user — approvals, pairing handshakes, host notifications — goes
- * through this function.
- *
- * ## Two-class resolution
- *
- * Channels split cleanly into two classes based on whether the user id is
- * already the DM platform id:
- *
- *   - **Direct-addressable** (Telegram, WhatsApp, iMessage, email, Matrix):
- *     user handle IS the DM chat id. No adapter method needed; we just
- *     mint a messaging_group row with `platform_id = handle`.
- *
- *   - **Resolution-required** (Discord, Slack, Teams, Webex, gChat):
- *     user id and DM channel id are different. The adapter must implement
- *     `openDM(handle)`, which Chat SDK's `chat.openDM` handles for us via
- *     the bridge. The returned channel id becomes the `platform_id`.
- *
- * ## Bot-aware caching (migration 026)
- *
- * The cache PK is `(user_id, channel_type, bot_id)`. Callers that know
- * which bot the DM should reach pass `opts.botId` and get bot-pinned
- * resolution: cache reads scope to that bot, cold-resolve goes through
- * the live adapter for `(channel, botId)` (not just the first adapter
- * for that channel), and the resulting cache row is written under that
- * bot's id.
- *
- * Callers that don't pass a bot id get the legacy "first adapter for
- * this channel" behavior, with cache rows under `bot_id = ''` — the
- * configurable channel-default slot. The settings UI lets the operator
- * point that slot at a specific bot's DM, and `pickApprovalDelivery`
- * falls through to it when an exact-bot resolve fails.
- *
- * ## Caching
- *
- * Successful resolutions are persisted in `user_dms`. The cache survives
- * restarts; first-time DMs on a given `(channel, bot)` pair pay one
- * `openDM` round trip, everyone after is a pure DB read.
- *
- * The underlying platform APIs (`POST /users/@me/channels` on Discord,
- * `conversations.open` on Slack, etc.) are idempotent and return the
- * same channel on repeated calls, so re-resolving after a cache miss is
- * always safe — worst case we round-trip redundantly.
- */
-import { getChannelAdapter, getChannelAdapterByBotId } from '../../channels/channel-registry.js';
-import { getMessagingGroup, getMessagingGroupByPlatform, createMessagingGroup } from '../../db/messaging-groups.js';
-import { log } from '../../log.js';
-import type { ChannelAdapter } from '../../channels/adapter.js';
-import type { MessagingGroup, User } from '../../types.js';
-import { getUser } from './db/users.js';
-import { getUserDm, upsertUserDm } from './db/user-dms.js';
-
-export interface EnsureUserDmOptions {
-  /**
-   * Pin the resolution to a specific bot. When set, the cache is read /
-   * written under that exact bot id and cold-resolve uses the adapter
-   * registered for `(channelType, botId)`. When omitted (or empty
-   * string), the legacy "first adapter for this channel" path runs and
-   * the cache row lands under `bot_id = ''` (the configurable
-   * channel-default slot).
-   */
-  botId?: string | null;
-}
-
-/**
- * Return a messaging_group usable to DM this user, creating it lazily if
- * needed. Returns null when:
- *   - the user id isn't namespaced (no `kind:handle` prefix)
- *   - the user's channel has no adapter registered (or, when `opts.botId`
- *     is set, no adapter is registered for that exact `(channel, bot)`)
- *   - the channel needs openDM but its adapter doesn't implement it
- *   - openDM throws (platform error, user blocked bot, the bot can't
- *     initiate a DM until the user has messaged it first, etc.)
- *
- * Callers should treat null as "this user is unreachable on this
- * channel + bot pair." `pickApprovalDelivery` translates that into a
- * channel-default fallback before giving up entirely.
- */
-export async function ensureUserDm(userId: string, opts?: EnsureUserDmOptions): Promise<MessagingGroup | null> {
-  const user = getUser(userId);
-  if (!user) {
-    log.warn('ensureUserDm: user not found', { userId });
-    return null;
-  }
-
-  const { channelType, handle } = parseUserId(user);
-  if (!channelType || !handle) {
-    log.warn('ensureUserDm: user id not namespaced', { userId });
-    return null;
-  }
-
-  const botId = opts?.botId ?? '';
-
-  // Cache hit: existing user_dms row → load and return the messaging_group.
-  const cached = getUserDm(userId, channelType, botId);
-  if (cached) {
-    const mg = getMessagingGroup(cached.messaging_group_id);
-    if (mg) return mg;
-    // Row points to a deleted messaging_group — fall through and re-resolve.
-    log.warn('ensureUserDm: cached row references missing messaging_group, re-resolving', {
-      userId,
-      botId,
-      messagingGroupId: cached.messaging_group_id,
-    });
-  }
-
-  // Cache miss: pick the adapter. With a bot id we MUST use that exact
-  // bot's adapter — falling back to "any adapter for this channel" would
-  // re-introduce the bug Proposal C is fixing (cross-bot delivery).
-  const adapter = botId ? getChannelAdapterByBotId(channelType, botId) : getChannelAdapter(channelType);
-  if (!adapter) {
-    log.warn('ensureUserDm: no adapter for channel/bot', { channelType, botId });
-    return null;
-  }
-
-  const dmPlatformId = await resolveDmPlatformId(adapter, channelType, handle);
-  if (!dmPlatformId) return null;
-
-  // Find-or-create the underlying messaging_group. A DM we received
-  // earlier may already have a row matching (channel_type, platform_id).
-  const now = new Date().toISOString();
-  let mg = getMessagingGroupByPlatform(channelType, dmPlatformId);
-  if (!mg) {
-    const mgId = `mg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    mg = {
-      id: mgId,
-      channel_type: channelType,
-      platform_id: dmPlatformId,
-      name: user.display_name,
-      is_group: 0,
-      unknown_sender_policy: 'strict',
-      created_at: now,
-    };
-    createMessagingGroup(mg);
-    log.info('ensureUserDm: created DM messaging_group', {
-      userId,
-      channelType,
-      botId,
-      messagingGroupId: mgId,
-    });
-  }
-
-  upsertUserDm({
-    user_id: userId,
-    channel_type: channelType,
-    bot_id: botId,
-    messaging_group_id: mg.id,
-    resolved_at: now,
-  });
-
-  return mg;
-}
-
-/**
- * Call the adapter's openDM if it has one; otherwise fall through to using
- * the handle directly. Returns null if openDM throws (platform-side
- * refusal — Telegram bots can't DM first, Discord blocked-by-recipient,
- * etc.).
- */
-async function resolveDmPlatformId(
-  adapter: ChannelAdapter,
-  channelType: string,
-  handle: string,
-): Promise<string | null> {
-  if (!adapter.openDM) {
-    // Direct-addressable channel — handle doubles as the DM chat id.
-    return handle;
-  }
-  try {
-    return await adapter.openDM(handle);
-  } catch (err) {
-    log.error('ensureUserDm: adapter.openDM failed', {
-      channelType,
-      botId: adapter.botId ?? null,
-      handle,
-      err,
-    });
-    return null;
-  }
-}
-
-function parseUserId(user: User): { channelType: string; handle: string } | { channelType: null; handle: null } {
-  const idx = user.id.indexOf(':');
-  if (idx < 0) return { channelType: null, handle: null };
-  const prefix = user.id.slice(0, idx);
-  const handle = user.id.slice(idx + 1);
-  if (!prefix || !handle) return { channelType: null, handle: null };
-  // Teams user IDs use a `29:` prefix, not `teams:`. When the id prefix
-  // isn't a registered adapter, fall back to user.kind and treat the full
-  // id as the handle.
-  if (!getChannelAdapter(prefix) && user.kind && getChannelAdapter(user.kind)) {
-    return { channelType: user.kind, handle: user.id };
-  }
-  return { channelType: prefix, handle };
-}

package/src/modules/provider-credentials/db.ts

@@ -1,121 +0,0 @@
-/**
- * `provider_credentials` row helpers.
- *
- * The PK column doubles as a sentinel slot — id `'__default__'` is the
- * install-wide row; Phase 2 will add real `agent_group_id` rows alongside.
- *
- * Encryption: `api_key_encrypted` is AES-GCM ciphertext (HKDF-derived
- * key, info `paraclaw.provider-credentials.v1`). Plaintext only crosses
- * this module's boundary at put/get time.
- *
- * ⚠ The `paraclaw.` prefix in the HKDF info string is a cryptographic
- * domain separator and is frozen across the paraclaw → parachute-agent
- * rename. Renaming it derives a different key and renders existing
- * ciphertext undecryptable. The brand sweep does not touch these bytes.
- */
-import { getDb } from '../../db/connection.js';
-import { decryptSecret, deriveKey, encryptSecret } from '../../secrets/crypto.js';
-import { loadOrCreateMasterKey } from '../../secrets/master-key.js';
-
-export const DEFAULT_SCOPE_ID = '__default__';
-const PROVIDER_CREDS_INFO = 'paraclaw.provider-credentials.v1';
-
-export type ProviderSource = 'claude_setup_token' | 'anthropic_api_key' | 'external_server';
-
-export interface ProviderCredentialsRow {
-  agent_group_id: string;
-  source: ProviderSource;
-  api_key_encrypted: string | null;
-  server_url: string | null;
-  updated_at: string;
-}
-
-export interface ProviderCredentialsPlaintext {
-  agent_group_id: string;
-  source: ProviderSource;
-  /**
-   * Plaintext secret. For `claude_setup_token` this is the OAuth token
-   * (`sk-ant-oat01-...`). For `anthropic_api_key` and `external_server`
-   * it's the API key. Null when unset.
-   */
-  apiKey: string | null;
-  serverUrl: string | null;
-  updatedAt: string;
-}
-
-function key(): Buffer {
-  return deriveKey(loadOrCreateMasterKey(), PROVIDER_CREDS_INFO);
-}
-
-export function getProviderCredentialsRow(scopeId: string = DEFAULT_SCOPE_ID): ProviderCredentialsRow | undefined {
-  return getDb()
-    .prepare<ProviderCredentialsRow>('SELECT * FROM provider_credentials WHERE agent_group_id = ?')
-    .get(scopeId);
-}
-
-export function readProviderCredentials(scopeId: string = DEFAULT_SCOPE_ID): ProviderCredentialsPlaintext | undefined {
-  const row = getProviderCredentialsRow(scopeId);
-  if (!row) return undefined;
-  const k = key();
-  return {
-    agent_group_id: row.agent_group_id,
-    source: row.source,
-    apiKey: row.api_key_encrypted ? decryptSecret(row.api_key_encrypted, k) : null,
-    serverUrl: row.server_url,
-    updatedAt: row.updated_at,
-  };
-}
-
-export interface PutProviderCredentialsInput {
-  // Required so a future caller can't silently overwrite the install-wide
-  // row by forgetting the scope. Pass `DEFAULT_SCOPE_ID` explicitly when
-  // you mean the install-wide credential.
-  scopeId: string;
-  source: ProviderSource;
-  apiKey?: string | null;
-  serverUrl?: string | null;
-}
-
-/**
- * Upsert the row for the given scope. Plaintext fields are encrypted
- * here. Pass `null` to clear a field; pass `undefined` to leave it
- * unchanged (caller-side merge — we read-modify-write).
- */
-export function putProviderCredentials(input: PutProviderCredentialsInput): void {
-  const { scopeId } = input;
-  const existing = getProviderCredentialsRow(scopeId);
-  const k = key();
-  const api_key_encrypted =
-    input.apiKey === undefined
-      ? (existing?.api_key_encrypted ?? null)
-      : input.apiKey === null
-        ? null
-        : encryptSecret(input.apiKey, k);
-  const server_url = input.serverUrl === undefined ? (existing?.server_url ?? null) : input.serverUrl;
-  const updated_at = new Date().toISOString();
-
-  getDb()
-    .prepare(
-      `INSERT INTO provider_credentials
-         (agent_group_id, source, api_key_encrypted, server_url, updated_at)
-       VALUES
-         (@agent_group_id, @source, @api_key_encrypted, @server_url, @updated_at)
-       ON CONFLICT (agent_group_id) DO UPDATE SET
-         source = excluded.source,
-         api_key_encrypted = excluded.api_key_encrypted,
-         server_url = excluded.server_url,
-         updated_at = excluded.updated_at`,
-    )
-    .run({
-      agent_group_id: scopeId,
-      source: input.source,
-      api_key_encrypted,
-      server_url,
-      updated_at,
-    });
-}
-
-export function deleteProviderCredentials(scopeId: string = DEFAULT_SCOPE_ID): boolean {
-  const r = getDb().prepare('DELETE FROM provider_credentials WHERE agent_group_id = ?').run(scopeId);
-  return r.changes > 0;
-}

package/src/modules/provider-credentials/index.ts

@@ -1,12 +0,0 @@
-export {
-  DEFAULT_SCOPE_ID,
-  deleteProviderCredentials,
-  getProviderCredentialsRow,
-  putProviderCredentials,
-  readProviderCredentials,
-  type ProviderCredentialsPlaintext,
-  type ProviderCredentialsRow,
-  type ProviderSource,
-  type PutProviderCredentialsInput,
-} from './db.js';
-export { getProviderCredentialsForSpawn, type ProviderSpawnEnvelope } from './spawn.js';