@openparachute/agent 0.1.2 → 0.2.0

package/src/types.ts

@@ -1,233 +0,0 @@
-// ── Central DB entities ──
-
-export type SecretMode = 'all' | 'selective';
-
-export interface AgentGroup {
-  id: string;
-  name: string;
-  folder: string;
-  agent_provider: string | null;
-  /**
-   * Per-group injection policy for secrets in this group's scope (its own
-   * scoped secrets + globals): `all` injects every in-scope secret;
-   * `selective` injects only those with an explicit `secret_assignments`
-   * row pointing to this group. Defaults to `selective` (migration 023).
-   */
-  secret_mode: SecretMode;
-  created_at: string;
-}
-
-/**
- * Exact wire mirror — `UnknownSenderPolicy` in `web/ui/src/lib/api.ts` MUST
- * stay in lock-step with this union. No translator; the values cross the
- * wire as-is. If you add or rename a value here, update the client too.
- */
-export type UnknownSenderPolicy = 'strict' | 'request_approval' | 'public';
-
-export interface MessagingGroup {
-  id: string;
-  channel_type: string;
-  platform_id: string;
-  name: string | null;
-  is_group: number; // 0 | 1
-  unknown_sender_policy: UnknownSenderPolicy;
-  /**
-   * When set, the owner explicitly denied registering this channel — the
-   * router drops silently and does not re-escalate. Cleared by any explicit
-   * wiring mutation (admin command). See migration 012.
-   *
-   * Optional on the TS type so pre-migration-012 callers that build
-   * MessagingGroup objects in code (fixtures, etc.) don't need to update;
-   * the column itself defaults to NULL in SQLite.
-   */
-  denied_at?: string | null;
-  created_at: string;
-}
-
-// ── Identity & privilege ──
-
-/**
- * User = a messaging-platform identifier. Namespaced so distinct channels
- * with numeric IDs don't collide: "phone:+1555...", "tg:123", "discord:456",
- * "email:a@x.com". A single human with a phone AND a telegram handle has
- * two separate users — no cross-channel linking (yet).
- */
-export interface User {
-  id: string;
-  kind: string; // 'phone' | 'email' | 'discord' | 'telegram' | 'matrix' | ...
-  display_name: string | null;
-  created_at: string;
-}
-
-export type UserRoleKind = 'owner' | 'admin';
-
-/**
- * Role grant. Owner is always global. Admin is either global
- * (agent_group_id = null) or scoped to a specific agent group.
- * Admin @ A implicitly makes the user a member of A — we do not require
- * a separate agent_group_members row for admins.
- */
-export interface UserRole {
-  user_id: string;
-  role: UserRoleKind;
-  agent_group_id: string | null;
-  granted_by: string | null;
-  granted_at: string;
-}
-
-/** "Known" membership in an agent group — required for unprivileged users. */
-export interface AgentGroupMember {
-  user_id: string;
-  agent_group_id: string;
-  added_by: string | null;
-  added_at: string;
-}
-
-/**
- * Cached DM channel for a user on a specific `(channel_type, bot_id)` pair.
- *
- * `bot_id = ''` (empty string) is the configurable channel-default slot —
- * the operator points it at whichever bot they want approvals to fall
- * back to when a `(user, channel, originBotId)` exact-bot lookup misses
- * AND the cold-DM resolve also fails. Migration 026 added the column;
- * pre-multi-bot installs land every row at `bot_id = ''`.
- */
-export interface UserDm {
-  user_id: string;
-  channel_type: string;
-  bot_id: string;
-  messaging_group_id: string;
-  resolved_at: string;
-}
-
-// DB vocabulary. See dbToApi* in src/web/routes/channels.ts for wire equivalents in web/ui/src/lib/api.ts.
-export type EngageMode = 'pattern' | 'mention' | 'mention-sticky';
-// DB vocabulary. The DB-side `'all'` means "no sender filter"; the wire side
-// uses `'allowlist' | 'unrestricted'` (paraclaw#94 — kept the two unions
-// literal-disjoint so a grep-refactor can't conflate them through the
-// translator).
-export type SenderScope = 'all' | 'known';
-// DB vocabulary. See dbToApi* in src/web/routes/channels.ts for wire equivalents in web/ui/src/lib/api.ts.
-export type IgnoredMessagePolicy = 'drop' | 'accumulate';
-
-export interface MessagingGroupAgent {
-  id: string;
-  messaging_group_id: string;
-  agent_group_id: string;
-  engage_mode: EngageMode;
-  /**
-   * Regex source string used when engage_mode='pattern'. `'.'` is the sentinel
-   * for "match every message" (the "always" flavor). Ignored for 'mention' /
-   * 'mention-sticky' modes.
-   */
-  engage_pattern: string | null;
-  sender_scope: SenderScope;
-  ignored_message_policy: IgnoredMessagePolicy;
-  session_mode: 'shared' | 'per-thread' | 'agent-shared';
-  priority: number;
-  created_at: string;
-}
-
-export interface Session {
-  id: string;
-  agent_group_id: string;
-  messaging_group_id: string | null;
-  thread_id: string | null;
-  agent_provider: string | null;
-  status: 'active' | 'closed';
-  container_status: 'running' | 'idle' | 'stopped';
-  last_active: string | null;
-  created_at: string;
-}
-
-// ── Session DB entities ──
-
-export type MessageInKind = 'chat' | 'chat-sdk' | 'task' | 'webhook' | 'system';
-export type MessageInStatus = 'pending' | 'processing' | 'completed' | 'failed';
-
-export interface MessageIn {
-  id: string;
-  kind: MessageInKind;
-  timestamp: string;
-  status: MessageInStatus;
-  status_changed: string | null;
-  process_after: string | null;
-  recurrence: string | null;
-  tries: number;
-  platform_id: string | null;
-  channel_type: string | null;
-  thread_id: string | null;
-  content: string; // JSON blob
-}
-
-export interface MessageOut {
-  id: string;
-  in_reply_to: string | null;
-  timestamp: string;
-  delivered: number; // 0 | 1
-  deliver_after: string | null;
-  recurrence: string | null;
-  kind: string;
-  platform_id: string | null;
-  channel_type: string | null;
-  thread_id: string | null;
-  content: string; // JSON blob
-}
-
-// ── Approvals (central DB) ──
-
-/**
- * Open-string discriminator. The host knows two well-known values
- * (`'question'` for inline UX prompts; module-action strings like
- * `'install_packages'` / `'add_mcp_server'` / `'credential'` for admin
- * gating), but third-party modules can register their own action strings
- * via `registerApprovalHandler`, so this is intentionally not a closed
- * union.
- */
-export type ApprovalKind = string;
-export type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
-
-export interface QuestionApprovalBody {
-  title: string;
-  options: import('./channels/ask-question.js').NormalizedOption[];
-  message_out_id: string;
-  platform_id: string | null;
-  channel_type: string | null;
-  thread_id: string | null;
-}
-
-export interface ActionApprovalBody {
-  title: string;
-  options: import('./channels/ask-question.js').NormalizedOption[];
-  request_id: string;
-  payload: Record<string, unknown>;
-  platform_id: string | null;
-  channel_type: string | null;
-  thread_id: string | null;
-  platform_message_id: string | null;
-}
-
-export type ApprovalBody = QuestionApprovalBody | ActionApprovalBody | Record<string, unknown>;
-
-export interface Approval {
-  id: string;
-  kind: ApprovalKind;
-  agent_group_id: string;
-  session_id: string | null;
-  body: ApprovalBody;
-  status: ApprovalStatus;
-  approver_user_id: string | null;
-  decided_at: string | null;
-  created_at: string;
-  expires_at: string | null;
-}
-
-// ── Agent destinations (central DB) ──
-
-export interface AgentDestination {
-  agent_group_id: string;
-  local_name: string;
-  target_type: 'channel' | 'agent';
-  target_id: string;
-  created_at: string;
-}

package/src/web/auth.test.ts

@@ -1,335 +0,0 @@
-/**
- * Hub-JWT validation + scope-check tests. Mirrors vault's hub-jwt.test.ts
- * shape but uses vitest + node:http (paraclaw's suite is vitest, not
- * bun:test). A fake JWKS endpoint signs locally with a known RSA keypair;
- * cases cover the spec failure modes plus paraclaw's agent-scope inheritance
- * + vault:admin catch-all + legacy `claw:*` compat normalization.
- */
-import http from 'node:http';
-import type { AddressInfo } from 'node:net';
-
-import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
-import { exportJWK, generateKeyPair, SignJWT } from 'jose';
-
-import {
-  authenticate,
-  getHubOrigin,
-  hasScope,
-  HubJwtError,
-  resetJwksCache,
-  SCOPE_AGENT_ADMIN,
-  SCOPE_AGENT_READ,
-  SCOPE_AGENT_WRITE,
-  SCOPE_VAULT_ADMIN,
-  validateHubJwt,
-} from './auth.js';
-
-interface Keypair {
-  // jose's generateKeyPair returns CryptoKey under WebCrypto; type narrowly to
-  // avoid pulling in lib.dom.
-  privateKey: Awaited<ReturnType<typeof generateKeyPair>>['privateKey'];
-  publicJwk: { kty: string; n: string; e: string; kid: string; alg: string; use: string };
-  kid: string;
-}
-
-async function makeKeypair(kid: string): Promise<Keypair> {
-  const { privateKey, publicKey } = await generateKeyPair('RS256', { extractable: true });
-  const jwk = await exportJWK(publicKey);
-  return {
-    privateKey,
-    publicJwk: {
-      kty: 'RSA',
-      n: jwk.n!,
-      e: jwk.e!,
-      kid,
-      alg: 'RS256',
-      use: 'sig',
-    },
-    kid,
-  };
-}
-
-interface JwksFixture {
-  origin: string;
-  stop: () => Promise<void>;
-  setKeys: (keys: Keypair[]) => void;
-  setUnreachable: (down: boolean) => void;
-}
-
-function startJwksFixture(): Promise<JwksFixture> {
-  return new Promise((resolve) => {
-    let keys: Keypair[] = [];
-    let down = false;
-    const server = http.createServer((req, res) => {
-      if (req.url !== '/.well-known/jwks.json') {
-        res.writeHead(404).end('not found');
-        return;
-      }
-      if (down) {
-        res.writeHead(503).end('upstream down');
-        return;
-      }
-      res.writeHead(200, { 'content-type': 'application/json' });
-      res.end(JSON.stringify({ keys: keys.map((k) => k.publicJwk) }));
-    });
-    server.listen(0, '127.0.0.1', () => {
-      const { port } = server.address() as AddressInfo;
-      resolve({
-        origin: `http://127.0.0.1:${port}`,
-        stop: () =>
-          new Promise<void>((r) => {
-            server.close(() => r());
-          }),
-        setKeys: (next) => {
-          keys = next;
-        },
-        setUnreachable: (v) => {
-          down = v;
-        },
-      });
-    });
-  });
-}
-
-interface SignOpts {
-  iss?: string;
-  aud?: string;
-  sub?: string;
-  scope?: string;
-  ttlSeconds?: number;
-  expiresAtSeconds?: number;
-  kid?: string;
-  clientId?: string;
-}
-
-async function signJwt(kp: Keypair, opts: SignOpts): Promise<string> {
-  const iat = Math.floor(Date.now() / 1000);
-  const exp = opts.expiresAtSeconds ?? iat + (opts.ttlSeconds ?? 60);
-  return await new SignJWT({
-    scope: opts.scope ?? 'agent:read',
-    client_id: opts.clientId ?? 'test-client',
-  })
-    .setProtectedHeader({ alg: 'RS256', kid: opts.kid ?? kp.kid })
-    .setIssuer(opts.iss ?? 'http://issuer.invalid')
-    .setSubject(opts.sub ?? 'user-1')
-    .setAudience(opts.aud ?? 'hub')
-    .setIssuedAt(iat)
-    .setExpirationTime(exp)
-    .setJti('jti-1')
-    .sign(kp.privateKey);
-}
-
-let fixture: JwksFixture;
-let kp: Keypair;
-let prevHubOrigin: string | undefined;
-
-beforeAll(async () => {
-  fixture = await startJwksFixture();
-  kp = await makeKeypair('k1');
-  fixture.setKeys([kp]);
-});
-
-afterAll(async () => {
-  await fixture.stop();
-  if (prevHubOrigin === undefined) delete process.env.PARACHUTE_AGENT_HUB_ORIGIN;
-  else process.env.PARACHUTE_AGENT_HUB_ORIGIN = prevHubOrigin;
-});
-
-beforeEach(() => {
-  prevHubOrigin = process.env.PARACHUTE_AGENT_HUB_ORIGIN;
-  process.env.PARACHUTE_AGENT_HUB_ORIGIN = fixture.origin;
-  fixture.setUnreachable(false);
-  fixture.setKeys([kp]);
-  resetJwksCache();
-});
-
-afterEach(() => {
-  if (prevHubOrigin === undefined) delete process.env.PARACHUTE_AGENT_HUB_ORIGIN;
-  else process.env.PARACHUTE_AGENT_HUB_ORIGIN = prevHubOrigin;
-});
-
-describe('validateHubJwt', () => {
-  it('happy path — surfaces sub + scopes + clientId', async () => {
-    const token = await signJwt(kp, { iss: fixture.origin, scope: 'agent:read agent:write' });
-    const claims = await validateHubJwt(token);
-    expect(claims.sub).toBe('user-1');
-    expect(claims.scopes).toEqual(['agent:read', 'agent:write']);
-    expect(claims.clientId).toBe('test-client');
-  });
-
-  it('rejects token with wrong issuer', async () => {
-    const token = await signJwt(kp, { iss: 'http://attacker.example' });
-    await expect(validateHubJwt(token)).rejects.toBeInstanceOf(HubJwtError);
-  });
-
-  it('rejects expired token', async () => {
-    const past = Math.floor(Date.now() / 1000) - 10;
-    const token = await signJwt(kp, { iss: fixture.origin, expiresAtSeconds: past });
-    await expect(validateHubJwt(token)).rejects.toBeInstanceOf(HubJwtError);
-  });
-
-  it('rejects token signed by an unpublished key', async () => {
-    const otherKp = await makeKeypair('k1');
-    const token = await signJwt(otherKp, { iss: fixture.origin });
-    await expect(validateHubJwt(token)).rejects.toBeInstanceOf(HubJwtError);
-  });
-
-  it('rejects when JWKS endpoint is unreachable', async () => {
-    fixture.setUnreachable(true);
-    const token = await signJwt(kp, { iss: fixture.origin });
-    await expect(validateHubJwt(token)).rejects.toBeInstanceOf(HubJwtError);
-  });
-});
-
-describe('getHubOrigin', () => {
-  // The hub lifecycle (parachute-hub/src/commands/lifecycle.ts) stamps
-  // PARACHUTE_HUB_ORIGIN onto every spawned service so iss-strict JWT
-  // validation works behind tailnet proxying. PARACHUTE_AGENT_HUB_ORIGIN
-  // is the test/per-service override; legacy PARACLAW_HUB_ORIGIN is read
-  // through 0.1.x with a one-shot deprecation warning (drop in 0.2.0).
-  // Loopback fallback exists for local-dev when the hub isn't supervising
-  // the process.
-  let prevAgent: string | undefined;
-  let prevParaclaw: string | undefined;
-  let prevParachute: string | undefined;
-
-  beforeEach(() => {
-    prevAgent = process.env.PARACHUTE_AGENT_HUB_ORIGIN;
-    prevParaclaw = process.env.PARACLAW_HUB_ORIGIN;
-    prevParachute = process.env.PARACHUTE_HUB_ORIGIN;
-    delete process.env.PARACHUTE_AGENT_HUB_ORIGIN;
-    delete process.env.PARACLAW_HUB_ORIGIN;
-    delete process.env.PARACHUTE_HUB_ORIGIN;
-  });
-
-  afterEach(() => {
-    if (prevAgent === undefined) delete process.env.PARACHUTE_AGENT_HUB_ORIGIN;
-    else process.env.PARACHUTE_AGENT_HUB_ORIGIN = prevAgent;
-    if (prevParaclaw === undefined) delete process.env.PARACLAW_HUB_ORIGIN;
-    else process.env.PARACLAW_HUB_ORIGIN = prevParaclaw;
-    if (prevParachute === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
-    else process.env.PARACHUTE_HUB_ORIGIN = prevParachute;
-  });
-
-  it('reads PARACHUTE_HUB_ORIGIN as primary (set by hub lifecycle)', () => {
-    process.env.PARACHUTE_HUB_ORIGIN = 'https://parachute.taildf9ce2.ts.net';
-    expect(getHubOrigin()).toBe('https://parachute.taildf9ce2.ts.net');
-  });
-
-  it('PARACHUTE_AGENT_HUB_ORIGIN overrides PARACHUTE_HUB_ORIGIN', () => {
-    process.env.PARACHUTE_HUB_ORIGIN = 'https://parachute.taildf9ce2.ts.net';
-    process.env.PARACHUTE_AGENT_HUB_ORIGIN = 'http://localhost:9999';
-    expect(getHubOrigin()).toBe('http://localhost:9999');
-  });
-
-  it('falls back to legacy PARACLAW_HUB_ORIGIN through 0.1.x compat', () => {
-    process.env.PARACHUTE_HUB_ORIGIN = 'https://parachute.taildf9ce2.ts.net';
-    process.env.PARACLAW_HUB_ORIGIN = 'http://localhost:9998';
-    expect(getHubOrigin()).toBe('http://localhost:9998');
-  });
-
-  it('PARACHUTE_AGENT_HUB_ORIGIN takes precedence over legacy PARACLAW_HUB_ORIGIN', () => {
-    process.env.PARACLAW_HUB_ORIGIN = 'http://legacy.example';
-    process.env.PARACHUTE_AGENT_HUB_ORIGIN = 'http://current.example';
-    expect(getHubOrigin()).toBe('http://current.example');
-  });
-
-  it('falls back to loopback when neither env is set', () => {
-    expect(getHubOrigin()).toBe('http://127.0.0.1:1939');
-  });
-
-  it('strips trailing slash from either env', () => {
-    process.env.PARACHUTE_HUB_ORIGIN = 'https://hub.example/';
-    expect(getHubOrigin()).toBe('https://hub.example');
-    process.env.PARACHUTE_AGENT_HUB_ORIGIN = 'https://override.example/';
-    expect(getHubOrigin()).toBe('https://override.example');
-  });
-});
-
-describe('hasScope', () => {
-  it('exact match', () => {
-    expect(hasScope([SCOPE_AGENT_READ], SCOPE_AGENT_READ)).toBe(true);
-  });
-
-  it('agent:admin ⊇ agent:write ⊇ agent:read', () => {
-    expect(hasScope([SCOPE_AGENT_ADMIN], SCOPE_AGENT_READ)).toBe(true);
-    expect(hasScope([SCOPE_AGENT_ADMIN], SCOPE_AGENT_WRITE)).toBe(true);
-    expect(hasScope([SCOPE_AGENT_WRITE], SCOPE_AGENT_READ)).toBe(true);
-    expect(hasScope([SCOPE_AGENT_READ], SCOPE_AGENT_WRITE)).toBe(false);
-    expect(hasScope([SCOPE_AGENT_WRITE], SCOPE_AGENT_ADMIN)).toBe(false);
-  });
-
-  it('vault:admin (operator-token catch-all) satisfies every agent scope', () => {
-    expect(hasScope([SCOPE_VAULT_ADMIN], SCOPE_AGENT_READ)).toBe(true);
-    expect(hasScope([SCOPE_VAULT_ADMIN], SCOPE_AGENT_WRITE)).toBe(true);
-    expect(hasScope([SCOPE_VAULT_ADMIN], SCOPE_AGENT_ADMIN)).toBe(true);
-  });
-
-  it('hub:admin does NOT satisfy agent scopes', () => {
-    expect(hasScope(['hub:admin'], SCOPE_AGENT_READ)).toBe(false);
-    expect(hasScope(['hub:admin'], SCOPE_AGENT_WRITE)).toBe(false);
-    expect(hasScope(['hub:admin'], SCOPE_AGENT_ADMIN)).toBe(false);
-  });
-
-  it('legacy `claw:*` grants are normalized to `agent:*` (pre-0.1.0 compat)', () => {
-    expect(hasScope(['claw:read'], SCOPE_AGENT_READ)).toBe(true);
-    expect(hasScope(['claw:write'], SCOPE_AGENT_READ)).toBe(true);
-    expect(hasScope(['claw:admin'], SCOPE_AGENT_WRITE)).toBe(true);
-    expect(hasScope(['claw:admin'], SCOPE_AGENT_ADMIN)).toBe(true);
-    expect(hasScope(['claw:read'], SCOPE_AGENT_WRITE)).toBe(false);
-  });
-
-  it('empty scopes never satisfy', () => {
-    expect(hasScope([], SCOPE_AGENT_READ)).toBe(false);
-  });
-});
-
-describe('authenticate', () => {
-  it('returns ok with claims for a valid Bearer + sufficient scope', async () => {
-    const token = await signJwt(kp, { iss: fixture.origin, scope: 'agent:write' });
-    const r = await authenticate(`Bearer ${token}`, SCOPE_AGENT_READ);
-    expect(r.ok).toBe(true);
-    if (r.ok) expect(r.claims.scopes).toContain('agent:write');
-  });
-
-  it('401 on missing header', async () => {
-    const r = await authenticate(undefined, SCOPE_AGENT_READ);
-    expect(r.ok).toBe(false);
-    if (!r.ok) expect(r.status).toBe(401);
-  });
-
-  it('401 on malformed header (no Bearer prefix)', async () => {
-    const token = await signJwt(kp, { iss: fixture.origin });
-    const r = await authenticate(token, SCOPE_AGENT_READ);
-    expect(r.ok).toBe(false);
-    if (!r.ok) expect(r.status).toBe(401);
-  });
-
-  it('401 on invalid token (wrong issuer)', async () => {
-    const token = await signJwt(kp, { iss: 'http://attacker.example' });
-    const r = await authenticate(`Bearer ${token}`, SCOPE_AGENT_READ);
-    expect(r.ok).toBe(false);
-    if (!r.ok) expect(r.status).toBe(401);
-  });
-
-  it('403 on insufficient scope — surfaces error_type + required + granted', async () => {
-    const token = await signJwt(kp, { iss: fixture.origin, scope: 'agent:read' });
-    const r = await authenticate(`Bearer ${token}`, SCOPE_AGENT_WRITE);
-    expect(r.ok).toBe(false);
-    if (!r.ok) {
-      expect(r.status).toBe(403);
-      expect(r.errorType).toBe('insufficient_scope');
-      expect(r.requiredScope).toBe(SCOPE_AGENT_WRITE);
-      expect(r.grantedScopes).toEqual(['agent:read']);
-    }
-  });
-
-  it('operator-token shape (vault:admin scope) passes any agent gate', async () => {
-    const token = await signJwt(kp, {
-      iss: fixture.origin,
-      scope: 'hub:admin vault:admin scribe:admin channel:send',
-    });
-    const r = await authenticate(`Bearer ${token}`, SCOPE_AGENT_ADMIN);
-    expect(r.ok).toBe(true);
-  });
-});