@haiai/haiai 0.1.2

package/tests/key-rotation.test.ts

@@ -0,0 +1,362 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { HaiClient } from '../src/client.js';
+import { generateTestKeypair as generateKeypair } from './setup.js';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+/** Create a test client with a generated keypair and a temporary key directory. */
+async function setupTestAgent(tmpDir: string) {
+  const keypair = generateKeypair();
+  const keyDir = path.join(tmpDir, 'keys');
+  await fs.mkdir(keyDir, { recursive: true });
+
+  // Write key files
+  const privPath = path.join(keyDir, 'agent_private_key.pem');
+  const pubPath = path.join(keyDir, 'agent_public_key.pem');
+  await fs.writeFile(privPath, keypair.privateKeyPem, { mode: 0o600 });
+  await fs.writeFile(pubPath, keypair.publicKeyPem, { mode: 0o644 });
+
+  // Write config file
+  const config = {
+    jacsAgentName: 'test-rotation-agent',
+    jacsAgentVersion: 'v1-original',
+    jacsKeyDir: keyDir,
+    jacsId: 'test-jacs-id-12345',
+  };
+  const configPath = path.join(tmpDir, 'jacs.config.json');
+  await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+
+  // Build client via fromCredentials (now async)
+  const client = await HaiClient.fromCredentials(
+    config.jacsId,
+    keypair.privateKeyPem,
+    { url: 'https://hai.example', privateKeyPassphrase: 'keygen-password' },
+  );
+  // Patch the config to have the real keyDir and version
+  (client as any).config = { ...config };
+
+  return { client, keypair, keyDir, privPath, pubPath, configPath, config };
+}
+
+describe('rotateKeys', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'hai-rotation-test-'));
+  });
+
+  afterEach(async () => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+    // Clean up temp directory
+    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('generates new key files and archives old ones', async () => {
+    const { client, privPath, pubPath, keyDir, configPath } = await setupTestAgent(tmpDir);
+
+    // Stub fetch so register() doesn't make real requests
+    vi.stubGlobal('fetch', vi.fn());
+
+    // Set JACS_CONFIG_PATH to point to our tmp config
+    process.env.JACS_CONFIG_PATH = configPath;
+
+    const result = await client.rotateKeys({ registerWithHai: false });
+
+    // New key files should exist at standard paths
+    const newPrivExists = await fs.stat(privPath).then(() => true).catch(() => false);
+    const newPubExists = await fs.stat(pubPath).then(() => true).catch(() => false);
+    expect(newPrivExists).toBe(true);
+    expect(newPubExists).toBe(true);
+
+    // Old keys should be archived with version suffix
+    const archivePriv = path.join(keyDir, 'agent_private_key.v1-original.pem');
+    const archiveExists = await fs.stat(archivePriv).then(() => true).catch(() => false);
+    expect(archiveExists).toBe(true);
+
+    delete process.env.JACS_CONFIG_PATH;
+  });
+
+  it('returns a valid RotationResult with correct fields', async () => {
+    const { client, configPath } = await setupTestAgent(tmpDir);
+    vi.stubGlobal('fetch', vi.fn());
+    process.env.JACS_CONFIG_PATH = configPath;
+
+    const result = await client.rotateKeys({ registerWithHai: false });
+
+    expect(result.jacsId).toBe('test-jacs-id-12345');
+    expect(result.oldVersion).toBe('v1-original');
+    expect(result.newVersion).not.toBe('v1-original');
+    expect(result.newVersion.length).toBeGreaterThan(0);
+    // SHA-256 hex is 64 chars
+    expect(result.newPublicKeyHash).toHaveLength(64);
+    expect(result.registeredWithHai).toBe(false);
+    expect(result.signedAgentJson.length).toBeGreaterThan(0);
+
+    // Signed agent JSON should be valid JSON with expected fields
+    const doc = JSON.parse(result.signedAgentJson);
+    expect(doc.jacsId).toBe('test-jacs-id-12345');
+    expect(doc.jacsVersion).toBe(result.newVersion);
+    expect(doc.jacsPreviousVersion).toBe('v1-original');
+    expect(doc.jacsSignature).toBeDefined();
+
+    delete process.env.JACS_CONFIG_PATH;
+  });
+
+  it('updates config file with new version', async () => {
+    const { client, configPath } = await setupTestAgent(tmpDir);
+    vi.stubGlobal('fetch', vi.fn());
+    process.env.JACS_CONFIG_PATH = configPath;
+
+    const result = await client.rotateKeys({ registerWithHai: false });
+
+    // Read config file and verify version was updated
+    const updatedConfig = JSON.parse(await fs.readFile(configPath, 'utf-8'));
+    expect(updatedConfig.jacsAgentVersion).toBe(result.newVersion);
+    // jacsId should be unchanged
+    expect(updatedConfig.jacsId).toBe('test-jacs-id-12345');
+
+    delete process.env.JACS_CONFIG_PATH;
+  });
+
+  it('updates in-memory config version', async () => {
+    const { client, configPath } = await setupTestAgent(tmpDir);
+    vi.stubGlobal('fetch', vi.fn());
+    process.env.JACS_CONFIG_PATH = configPath;
+
+    const result = await client.rotateKeys({ registerWithHai: false });
+
+    // In-memory config should reflect the new version
+    expect((client as any).config.jacsAgentVersion).toBe(result.newVersion);
+    // The private key PEM should have changed
+    expect((client as any).privateKeyPem).not.toBe('');
+
+    delete process.env.JACS_CONFIG_PATH;
+  });
+
+  it('calls register when registerWithHai is true', async () => {
+    const { client, configPath } = await setupTestAgent(tmpDir);
+    process.env.JACS_CONFIG_PATH = configPath;
+
+    const fetchMock = vi.fn(async (_url: string | URL, _init?: RequestInit) => {
+      return new Response(
+        JSON.stringify({
+          agent_id: 'hai-agent-uuid',
+          jacs_id: 'test-jacs-id-12345',
+          hai_signature: 'sig-abc',
+          registration_id: 'reg-123',
+          registered_at: '2026-03-02T00:00:00Z',
+        }),
+        { status: 201, headers: { 'Content-Type': 'application/json' } },
+      );
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await client.rotateKeys({
+      registerWithHai: true,
+      haiUrl: 'https://hai.example',
+    });
+
+    expect(result.registeredWithHai).toBe(true);
+    // Verify register was called (fetch was invoked)
+    expect(fetchMock).toHaveBeenCalled();
+    const callUrl = String(fetchMock.mock.calls[0][0]);
+    expect(callUrl).toContain('/api/v1/agents/register');
+
+    delete process.env.JACS_CONFIG_PATH;
+  });
+
+  it('preserves local rotation when HAI registration fails', async () => {
+    const { client, configPath } = await setupTestAgent(tmpDir);
+    process.env.JACS_CONFIG_PATH = configPath;
+
+    const fetchMock = vi.fn(async () => {
+      return new Response('Internal Server Error', {
+        status: 500,
+        headers: { 'Content-Type': 'text/plain' },
+      });
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await client.rotateKeys({
+      registerWithHai: true,
+      haiUrl: 'https://hai.example',
+    });
+
+    // Local rotation should succeed
+    expect(result.jacsId).toBe('test-jacs-id-12345');
+    expect(result.newVersion).not.toBe('v1-original');
+    // But HAI registration should have failed
+    expect(result.registeredWithHai).toBe(false);
+
+    delete process.env.JACS_CONFIG_PATH;
+  });
+
+  it('throws when no jacsId is set', async () => {
+    const keypair = generateKeypair();
+    const client = await HaiClient.fromCredentials(
+      'no-id-agent',
+      keypair.privateKeyPem,
+      { url: 'https://hai.example', privateKeyPassphrase: 'keygen-password' },
+    );
+    // Remove jacsId from config
+    (client as any).config = {
+      jacsAgentName: 'no-id-agent',
+      jacsAgentVersion: 'v1',
+      jacsKeyDir: '/nonexistent',
+    };
+
+    await expect(client.rotateKeys({ registerWithHai: false }))
+      .rejects.toThrow(/no jacsId/i);
+  });
+
+  it('throws when private key file not found', async () => {
+    const keypair = generateKeypair();
+    const emptyKeyDir = path.join(tmpDir, 'empty-keys');
+    await fs.mkdir(emptyKeyDir, { recursive: true });
+
+    const client = await HaiClient.fromCredentials(
+      'test-id',
+      keypair.privateKeyPem,
+      { url: 'https://hai.example', privateKeyPassphrase: 'keygen-password' },
+    );
+    (client as any).config = {
+      jacsAgentName: 'test-agent',
+      jacsAgentVersion: 'v1',
+      jacsKeyDir: emptyKeyDir,
+      jacsId: 'test-id',
+    };
+
+    await expect(client.rotateKeys({ registerWithHai: false }))
+      .rejects.toThrow(/private key not found/i);
+  });
+
+  it('new key produces valid signature on agent document', async () => {
+    const { client, configPath, pubPath } = await setupTestAgent(tmpDir);
+    vi.stubGlobal('fetch', vi.fn());
+    process.env.JACS_CONFIG_PATH = configPath;
+
+    const result = await client.rotateKeys({ registerWithHai: false });
+
+    // Read the new public key from disk
+    const newPubPem = await fs.readFile(pubPath, 'utf-8');
+    expect(newPubPem).toContain('-----BEGIN PUBLIC KEY-----');
+
+    // Parse signed agent JSON and ensure the signed payload references the
+    // rotated key/version material. The native binding currently cannot
+    // reload freshly generated temp agents reliably in-process, so this test
+    // stays at the contract/document level rather than duplicating JACS
+    // verification behavior.
+    const doc = JSON.parse(result.signedAgentJson);
+    expect(doc.jacsSignature?.signature).toBeDefined();
+    expect(doc.jacsPublicKey).toContain('BEGIN PUBLIC KEY');
+    expect(doc.jacsVersion).toBe(result.newVersion);
+    expect(doc.jacsPreviousVersion).toBe('v1-original');
+
+    delete process.env.JACS_CONFIG_PATH;
+  });
+
+  it('new version is a valid UUID v4', async () => {
+    const { client, configPath } = await setupTestAgent(tmpDir);
+    vi.stubGlobal('fetch', vi.fn());
+    process.env.JACS_CONFIG_PATH = configPath;
+
+    const result = await client.rotateKeys({ registerWithHai: false });
+
+    // UUID v4 pattern: 8-4-4-4-12 hex chars
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    expect(result.newVersion).toMatch(uuidRegex);
+
+    delete process.env.JACS_CONFIG_PATH;
+  });
+
+  it('double rotation archives both versions', async () => {
+    const { client, configPath, keyDir, privPath, pubPath } = await setupTestAgent(tmpDir);
+    vi.stubGlobal('fetch', vi.fn());
+    process.env.JACS_CONFIG_PATH = configPath;
+
+    // First rotation: V1 -> V2
+    const result1 = await client.rotateKeys({ registerWithHai: false });
+    const v2 = result1.newVersion;
+
+    // Second rotation: V2 -> V3
+    const result2 = await client.rotateKeys({ registerWithHai: false });
+
+    // Current key files should exist
+    const newPrivExists = await fs.stat(privPath).then(() => true).catch(() => false);
+    const newPubExists = await fs.stat(pubPath).then(() => true).catch(() => false);
+    expect(newPrivExists).toBe(true);
+    expect(newPubExists).toBe(true);
+
+    // V1 archive should exist
+    const archiveV1 = path.join(keyDir, 'agent_private_key.v1-original.pem');
+    const v1Exists = await fs.stat(archiveV1).then(() => true).catch(() => false);
+    expect(v1Exists).toBe(true);
+
+    // V2 archive should exist
+    const archiveV2 = path.join(keyDir, `agent_private_key.${v2}.pem`);
+    const v2Exists = await fs.stat(archiveV2).then(() => true).catch(() => false);
+    expect(v2Exists).toBe(true);
+
+    // Version chain should be consistent
+    expect(result1.oldVersion).toBe('v1-original');
+    expect(result1.newVersion).toBe(result2.oldVersion);
+    expect(result2.newVersion).not.toBe(result2.oldVersion);
+
+    delete process.env.JACS_CONFIG_PATH;
+  });
+
+  it('rotation result fields match shared fixture contract', async () => {
+    const fixturePath = path.join(__dirname, '..', '..', 'fixtures', 'rotation_result.json');
+    let fixture: Record<string, unknown>;
+    try {
+      fixture = JSON.parse(await fs.readFile(fixturePath, 'utf-8'));
+    } catch {
+      // Skip if fixture doesn't exist
+      return;
+    }
+
+    // RotationResult interface fields (snake_case in fixture -> camelCase in TS)
+    const fixtureKeys = new Set(Object.keys(fixture));
+    const expectedKeys = new Set([
+      'jacs_id', 'old_version', 'new_version',
+      'new_public_key_hash', 'registered_with_hai', 'signed_agent_json',
+    ]);
+    expect(fixtureKeys).toEqual(expectedKeys);
+  });
+
+  it('register payload contains agent_json with new version', async () => {
+    const { client, configPath } = await setupTestAgent(tmpDir);
+    process.env.JACS_CONFIG_PATH = configPath;
+
+    let capturedBody: Record<string, unknown> | null = null;
+    const fetchMock = vi.fn(async (_url: string | URL, init?: RequestInit) => {
+      capturedBody = JSON.parse(String(init?.body ?? '{}'));
+      return new Response(
+        JSON.stringify({
+          agent_id: 'hai-uuid',
+          jacs_id: 'test-jacs-id-12345',
+          hai_signature: 'sig',
+          registration_id: 'reg-1',
+          registered_at: '2026-03-02T00:00:00Z',
+        }),
+        { status: 201, headers: { 'Content-Type': 'application/json' } },
+      );
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await client.rotateKeys({
+      registerWithHai: true,
+      haiUrl: 'https://hai.example',
+    });
+
+    expect(capturedBody).not.toBeNull();
+    expect(capturedBody!.agent_json).toBeDefined();
+    const agentDoc = JSON.parse(capturedBody!.agent_json as string);
+    expect(agentDoc.jacsVersion).toBe(result.newVersion);
+    expect(agentDoc.jacsId).toBe('test-jacs-id-12345');
+
+    delete process.env.JACS_CONFIG_PATH;
+  });
+});

package/tests/mime.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect } from 'vitest';
+import { buildRfc5322Email } from '../src/mime.js';
+import type { MimeSendEmailOptions } from '../src/mime.js';
+
+describe('buildRfc5322Email', () => {
+  it('produces valid RFC 5322 for simple text email', () => {
+    const opts: MimeSendEmailOptions = {
+      to: 'recipient@hai.ai',
+      subject: 'Test Subject',
+      body: 'Hello, world!',
+    };
+    const raw = buildRfc5322Email(opts, 'sender@hai.ai');
+    const text = raw.toString('utf-8');
+
+    expect(text).toContain('From: <sender@hai.ai>\r\n');
+    expect(text).toContain('To: recipient@hai.ai\r\n');
+    expect(text).toContain('Subject: Test Subject\r\n');
+    expect(text).toContain('Date: ');
+    expect(text).toContain('Message-ID: <');
+    expect(text).toContain('MIME-Version: 1.0\r\n');
+    expect(text).toContain('Content-Type: text/plain; charset=utf-8\r\n');
+    expect(text).toContain('Hello, world!');
+  });
+
+  it('handles attachments', () => {
+    const opts: MimeSendEmailOptions = {
+      to: 'recipient@hai.ai',
+      subject: 'With Attachments',
+      body: 'See attached.',
+      attachments: [
+        {
+          filename: 'file1.txt',
+          contentType: 'text/plain',
+          data: Buffer.from('content of file 1'),
+        },
+        {
+          filename: 'file2.pdf',
+          contentType: 'application/pdf',
+          data: Buffer.from('fake pdf content'),
+        },
+      ],
+    };
+
+    const raw = buildRfc5322Email(opts, 'sender@hai.ai');
+    const text = raw.toString('utf-8');
+
+    expect(text).toContain('Content-Type: multipart/mixed; boundary=');
+    expect(text).toContain('Content-Disposition: attachment; filename="file1.txt"');
+    expect(text).toContain('Content-Disposition: attachment; filename="file2.pdf"');
+    expect(text).toContain('Content-Transfer-Encoding: base64');
+    expect(text).toContain('See attached.');
+  });
+
+  it('handles reply threading', () => {
+    const opts: MimeSendEmailOptions = {
+      to: 'recipient@hai.ai',
+      subject: 'Re: Original',
+      body: 'Reply body',
+      inReplyTo: '<original-id@hai.ai>',
+    };
+
+    const raw = buildRfc5322Email(opts, 'sender@hai.ai');
+    const text = raw.toString('utf-8');
+
+    expect(text).toContain('In-Reply-To: <original-id@hai.ai>\r\n');
+    expect(text).toContain('References: <original-id@hai.ai>\r\n');
+  });
+
+  it('sanitizes CRLF injection', () => {
+    const opts: MimeSendEmailOptions = {
+      to: 'recipient@hai.ai',
+      subject: 'Bad\r\nBcc: attacker@evil.com',
+      body: 'Body',
+    };
+
+    const raw = buildRfc5322Email(opts, 'sender@hai.ai');
+    const text = raw.toString('utf-8');
+
+    // No line should start with "Bcc:" (CRLF injection prevented)
+    const lines = text.split('\r\n');
+    for (const line of lines) {
+      expect(line.startsWith('Bcc:')).toBe(false);
+    }
+    // Subject should be sanitized
+    expect(text).toContain('Subject: BadBcc: attacker@evil.com\r\n');
+  });
+
+  it('sanitizes double quotes in filenames to prevent parameter injection', () => {
+    const opts: MimeSendEmailOptions = {
+      to: 'recipient@hai.ai',
+      subject: 'Test',
+      body: 'Body',
+      attachments: [
+        {
+          filename: 'file"; name="evil',
+          contentType: 'text/plain',
+          data: Buffer.from('content'),
+        },
+      ],
+    };
+
+    const raw = buildRfc5322Email(opts, 'sender@hai.ai');
+    const text = raw.toString('utf-8');
+
+    expect(text).not.toContain('filename="file"');
+    expect(text).not.toContain('name="evil"');
+  });
+
+  it('uses CRLF line endings', () => {
+    const opts: MimeSendEmailOptions = {
+      to: 'recipient@hai.ai',
+      subject: 'Test',
+      body: 'Body',
+    };
+
+    const raw = buildRfc5322Email(opts, 'sender@hai.ai');
+    const text = raw.toString('utf-8');
+
+    expect(text).toContain('\r\n');
+    // Split by CRLF, no remaining bare \n in any part (except within body text)
+    const headerSection = text.split('\r\n\r\n')[0];
+    const headerParts = headerSection.split('\r\n');
+    for (const part of headerParts) {
+      expect(part).not.toContain('\n');
+    }
+  });
+});

package/tests/security.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { HaiClient } from '../src/client.js';
+import { generateTestKeypair as generateKeypair } from './setup.js';
+
+async function makeClient(): Promise<HaiClient> {
+  const kp = generateKeypair();
+  const client = await HaiClient.fromCredentials('security-agent', kp.privateKeyPem, {
+    url: 'https://hai.example',
+    privateKeyPassphrase: 'keygen-password',
+  });
+  (client as any)._publicKeyPem = kp.publicKeyPem;
+  return client;
+}
+
+describe('security behaviors (node)', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('register does not send private key material and keeps bootstrap request unauthenticated', async () => {
+    const client = await makeClient();
+
+    const fetchMock = vi.fn(async (_url: string | URL, init?: RequestInit) => {
+      const headers = new Headers(init?.headers);
+      expect(headers.get('Authorization')).toBeNull();
+      expect(headers.get('Content-Type')).toBe('application/json');
+
+      const rawBody = String(init?.body ?? '');
+      expect(rawBody).not.toContain('BEGIN PRIVATE KEY');
+
+      const payload = JSON.parse(rawBody) as Record<string, string>;
+      expect(typeof payload.agent_json).toBe('string');
+      expect(payload.public_key).toBeTypeOf('string');
+
+      return new Response(JSON.stringify({
+        agent_id: 'agent-123',
+        jacs_id: 'security-agent',
+        registered_at: '2026-01-01T00:00:00Z',
+      }), {
+        status: 201,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    await client.register({
+      ownerEmail: 'owner@hai.ai',
+      domain: 'agent.example',
+      description: 'Security test agent',
+    });
+  });
+
+  it('checkUsername remains unauthenticated public endpoint', async () => {
+    const client = await makeClient();
+
+    const fetchMock = vi.fn(async (_url: string | URL, init?: RequestInit) => {
+      const headers = new Headers(init?.headers);
+      expect(headers.get('Authorization')).toBeNull();
+
+      return new Response(JSON.stringify({
+        available: true,
+        username: 'agent',
+      }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await client.checkUsername('agent');
+    expect(result.available).toBe(true);
+  });
+
+  it('registerNewAgent omits Authorization and sends base64 public key only', async () => {
+    const client = await makeClient();
+
+    const fetchMock = vi.fn(async (_url: string | URL, init?: RequestInit) => {
+      const headers = new Headers(init?.headers);
+      expect(headers.get('Authorization')).toBeNull();
+      expect(headers.get('Content-Type')).toBe('application/json');
+
+      const payload = JSON.parse(String(init?.body ?? '{}')) as Record<string, string>;
+      const decodedPublicKey = Buffer.from(payload.public_key, 'base64').toString('utf-8');
+      expect(decodedPublicKey).toContain('BEGIN PUBLIC KEY');
+      expect(decodedPublicKey).not.toContain('BEGIN PRIVATE KEY');
+
+      return new Response(JSON.stringify({
+        agent_id: 'agent-999',
+        jacs_id: 'security-agent',
+        registration_id: 'reg-999',
+        registered_at: '2026-01-01T00:00:00Z',
+      }), {
+        status: 201,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await client.registerNewAgent('security-agent', {
+      ownerEmail: 'owner@hai.ai',
+      domain: 'agent.example',
+      description: 'Security bootstrap',
+      quiet: true,
+    });
+
+    expect(result.agentId).toBe('agent-999');
+  });
+});

package/tests/setup.ts

@@ -0,0 +1,60 @@
+import { generateKeyPairSync } from 'node:crypto';
+import { JacsAgent } from '@hai.ai/jacs';
+
+/** Strong test password that meets JACS security requirements. */
+export const TEST_PASSWORD = 'Xk9#mP2vL7qR4!nB8wZ';
+
+/** A test JACS ID. */
+export const TEST_JACS_ID = 'test-agent-001';
+
+/** The test JACS agent (ephemeral, in-memory). Can sign and verify. */
+export const TEST_AGENT = new JacsAgent();
+const _ephResult = JSON.parse(TEST_AGENT.ephemeralSync('ring-Ed25519'));
+
+/**
+ * A PEM-encoded public key from a generated Ed25519 keypair.
+ * Used for tests that need deterministic PEM-shaped key material without
+ * depending on JACS on-disk agent layout.
+ */
+export const TEST_PUBLIC_KEY_PEM = (() => {
+  const { publicKey } = generateKeyPairSync('ed25519');
+  return publicKey.export({ format: 'pem', type: 'spki' }).toString().trim();
+})();
+
+/**
+ * Generate an Ed25519 keypair as plaintext PEM for tests that only need
+ * stable key fixtures or a public/private pair written to disk.
+ */
+export function generateTestKeypair(): { publicKeyPem: string; privateKeyPem: string } {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  return {
+    publicKeyPem: publicKey.export({ format: 'pem', type: 'spki' }).toString().trim(),
+    privateKeyPem: privateKey.export({ format: 'pem', type: 'pkcs8' }).toString().trim(),
+  };
+}
+
+/**
+ * Create a mock SSE response body from a list of events.
+ */
+export function createSseBody(events: Array<{ event?: string; data: string; id?: string }>): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  let sent = false;
+
+  return new ReadableStream({
+    pull(controller) {
+      if (sent) {
+        controller.close();
+        return;
+      }
+      sent = true;
+
+      let text = '';
+      for (const evt of events) {
+        if (evt.event) text += `event: ${evt.event}\n`;
+        if (evt.id) text += `id: ${evt.id}\n`;
+        text += `data: ${evt.data}\n\n`;
+      }
+      controller.enqueue(encoder.encode(text));
+    },
+  });
+}