@7h3/protocol 0.1.2 → 0.5.0

package/src/grpcBinding.test.ts

@@ -0,0 +1,211 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  signGrpcCall,
+  verifyGrpcCall,
+  withGrpcVerification,
+  GRPC_METADATA_KEY,
+} from './grpcBinding'
+import { createStaticKeyRegistry, type KeyRegistry } from './keyRegistry'
+import {
+  generateEd25519KeypairBase64Url,
+  createEnvelope,
+  signEnvelopeEd25519,
+  type ProtocolEnvelope,
+} from './protocol'
+
+// Helper: build a KeyRegistry that holds HMAC shared secrets but no public keys
+function createHmacKeyRegistry(secrets: Record<string, string>): KeyRegistry {
+  return {
+    async getPublicKey() { return null },
+    async getSharedSecret(keyId) { return secrets[keyId] ?? null },
+  }
+}
+
+describe('signGrpcCall', () => {
+  it('produces metadata with the correct key', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-client-agent'
+
+    const metadata = await signGrpcCall({ privateKey, sender })
+
+    expect(metadata[GRPC_METADATA_KEY]).toBeDefined()
+    expect(typeof metadata[GRPC_METADATA_KEY]).toBe('string')
+
+    // Parse and validate structure
+    const parsed = JSON.parse(metadata[GRPC_METADATA_KEY]) as ProtocolEnvelope
+    expect(parsed.header.sender).toBe(sender)
+    expect(parsed.signature?.alg).toBe('ED25519')
+  })
+
+  it('uses a custom metadataKey when provided', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const customKey = 'x-custom-grpc-sig'
+
+    const metadata = await signGrpcCall({ privateKey, sender: 'agent-x', metadataKey: customKey })
+
+    expect(metadata[customKey]).toBeDefined()
+    expect(metadata[GRPC_METADATA_KEY]).toBeUndefined()
+  })
+})
+
+describe('verifyGrpcCall', () => {
+  it('valid signed call returns ok:true with envelope', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-server-agent'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const metadata = await signGrpcCall({ privateKey, sender })
+    const result = await verifyGrpcCall(metadata, { keyRegistry: registry })
+
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.envelope.header.sender).toBe(sender)
+      expect(result.envelope.body.intent).toBe('TASK')
+    }
+  })
+
+  it('missing metadata returns ok:false with code 16', async () => {
+    const registry = createStaticKeyRegistry({})
+    const result = await verifyGrpcCall({}, { keyRegistry: registry })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.code).toBe(16)
+      expect(result.message).toContain('missing')
+    }
+  })
+
+  it('tampered envelope returns ok:false with code 16', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-tamper-agent'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'original', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+
+    // Tamper with content after signing
+    const tampered: ProtocolEnvelope = {
+      ...signed,
+      body: { ...signed.body, content: 'tampered' },
+    }
+    const metadata = { [GRPC_METADATA_KEY]: JSON.stringify(tampered) }
+
+    const result = await verifyGrpcCall(metadata, { keyRegistry: registry })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.code).toBe(16)
+    }
+  })
+
+  it('expired envelope returns ok:false with code 4', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-expired-agent'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const pastNow = Date.now() - 120_000 // 2 minutes ago
+    const env = createEnvelope({
+      sender,
+      intent: 'TASK',
+      content: 'expired-task',
+      ttlMs: 1_000, // 1 second TTL — already expired
+      nowMs: pastNow,
+    })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const metadata = { [GRPC_METADATA_KEY]: JSON.stringify(signed) }
+
+    const result = await verifyGrpcCall(metadata, { keyRegistry: registry, strictTtl: true })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.code).toBe(4)
+    }
+  })
+
+  it('unknown sender returns ok:false with code 16', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const registry = createStaticKeyRegistry({}) // empty registry
+
+    const env = createEnvelope({ sender: 'unknown-grpc-agent', intent: 'TASK', content: 'hi', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const metadata = { [GRPC_METADATA_KEY]: JSON.stringify(signed) }
+
+    const result = await verifyGrpcCall(metadata, { keyRegistry: registry })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.code).toBe(16)
+      expect(result.message).toContain('unknown-grpc-agent')
+    }
+  })
+
+  it('accepts Buffer values in metadata', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-buffer-agent'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'buf-test', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const metadata: Record<string, Buffer> = {
+      [GRPC_METADATA_KEY]: Buffer.from(JSON.stringify(signed), 'utf8'),
+    }
+
+    const result = await verifyGrpcCall(metadata, { keyRegistry: registry })
+    expect(result.ok).toBe(true)
+  })
+
+  it('accepts string array values in metadata', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-array-agent'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'arr-test', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const metadata: Record<string, string[]> = {
+      [GRPC_METADATA_KEY]: [JSON.stringify(signed)],
+    }
+
+    const result = await verifyGrpcCall(metadata, { keyRegistry: registry })
+    expect(result.ok).toBe(true)
+  })
+})
+
+describe('withGrpcVerification', () => {
+  it('calls handler on valid call and attaches envelope to call object', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'grpc-wrap-agent'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const signedMeta = await signGrpcCall({ privateKey, sender })
+    const call = { metadata: signedMeta, someField: 'value' }
+
+    const handler = vi.fn().mockResolvedValue({ status: 'ok' })
+    const wrapped = withGrpcVerification(handler, { keyRegistry: registry })
+
+    const response = await wrapped(call)
+
+    expect(handler).toHaveBeenCalledOnce()
+    expect(handler).toHaveBeenCalledWith(call)
+    expect(response).toEqual({ status: 'ok' })
+    expect((call as any)['7h3Envelope']).toBeDefined()
+    expect((call as any)['7h3Envelope'].header.sender).toBe(sender)
+  })
+
+  it('throws on invalid call and does not invoke handler', async () => {
+    const registry = createStaticKeyRegistry({})
+    const call = { metadata: {} } // no envelope metadata
+
+    const handler = vi.fn().mockResolvedValue({ status: 'ok' })
+    const wrapped = withGrpcVerification(handler, { keyRegistry: registry })
+
+    await expect(wrapped(call)).rejects.toThrow()
+    expect(handler).not.toHaveBeenCalled()
+
+    // The thrown error should carry the gRPC status code
+    try {
+      await wrapped(call)
+    } catch (err: any) {
+      expect(err.code).toBe(16)
+    }
+  })
+})

package/src/grpcBinding.ts

@@ -0,0 +1,103 @@
+import {
+  signEnvelopeEd25519,
+  verifyEnvelopeEd25519, verifyEnvelopeHmac,
+  createEnvelope, validateEnvelope,
+  type ProtocolEnvelope,
+} from './protocol'
+import type { KeyRegistry } from './keyRegistry'
+
+export { type KeyRegistry }
+
+export const GRPC_METADATA_KEY = '7h3-envelope-bin'  // -bin suffix = binary safe in gRPC
+
+export interface GrpcSignOptions {
+  privateKey: string
+  sender: string
+  recipient?: string
+  ttlMs?: number
+  metadataKey?: string
+}
+
+export interface GrpcVerifyOptions {
+  keyRegistry: KeyRegistry
+  metadataKey?: string
+  strictTtl?: boolean
+}
+
+export type GrpcVerifyResult =
+  | { ok: true; envelope: ProtocolEnvelope }
+  | { ok: false; code: number; message: string }  // code = gRPC status code
+
+// Client side: produce metadata to attach to outbound call
+export async function signGrpcCall(
+  opts: GrpcSignOptions
+): Promise<Record<string, string>> {
+  const envelope = createEnvelope({
+    sender: opts.sender,
+    recipient: opts.recipient,
+    ttlMs: opts.ttlMs ?? 60_000,
+    intent: 'TASK',
+    content: 'grpc-call',
+  })
+  const signed = await signEnvelopeEd25519(envelope, opts.privateKey)
+  return { [opts.metadataKey ?? GRPC_METADATA_KEY]: JSON.stringify(signed) }
+}
+
+// Server side: verify metadata from incoming call
+export async function verifyGrpcCall(
+  metadata: Record<string, string | Buffer | string[]>,
+  opts: GrpcVerifyOptions
+): Promise<GrpcVerifyResult> {
+  const key = opts.metadataKey ?? GRPC_METADATA_KEY
+  const raw = metadata[key]
+  const rawStr = Array.isArray(raw) ? raw[0] : (raw instanceof Uint8Array ? new TextDecoder().decode(raw) : raw)
+  if (!rawStr) return { ok: false, code: 16, message: '7h3: missing gRPC envelope metadata' }
+
+  let envelope: ProtocolEnvelope
+  try { envelope = JSON.parse(typeof rawStr === 'string' ? rawStr : String(rawStr)) as ProtocolEnvelope }
+  catch { return { ok: false, code: 3, message: '7h3: malformed envelope metadata' } }
+
+  if (opts.strictTtl !== false) {
+    const diags = validateEnvelope(envelope)
+    if (diags.some(d => d.level === 'error')) {
+      return { ok: false, code: 4, message: '7h3: envelope expired or invalid' }
+    }
+  }
+
+  const sender = envelope.header?.sender
+  const alg = envelope.signature?.alg
+  if (!sender || !alg) return { ok: false, code: 3, message: '7h3: missing sender or alg' }
+
+  if (alg === 'ED25519') {
+    const publicKey = await opts.keyRegistry.getPublicKey(sender)
+    if (!publicKey) return { ok: false, code: 16, message: `7h3: unknown sender ${sender}` }
+    const valid = await verifyEnvelopeEd25519(envelope, publicKey)
+    if (!valid) return { ok: false, code: 16, message: '7h3: invalid signature' }
+  } else if (alg === 'HS256') {
+    const secret = await opts.keyRegistry.getSharedSecret?.(envelope.signature!.keyId)
+    if (!secret) return { ok: false, code: 16, message: '7h3: unknown key' }
+    const valid = await verifyEnvelopeHmac(envelope, secret)
+    if (!valid) return { ok: false, code: 16, message: '7h3: invalid signature' }
+  } else {
+    return { ok: false, code: 3, message: `7h3: unsupported alg ${String(alg)}` }
+  }
+
+  return { ok: true, envelope }
+}
+
+// Factory: creates a function that wraps any async gRPC handler with verify logic
+// Usage: const handler = withGrpcVerification(myHandler, verifyOpts)
+export function withGrpcVerification<TCall extends { metadata: Record<string, string | Buffer | string[]> }, TResp>(
+  handler: (call: TCall) => Promise<TResp>,
+  opts: GrpcVerifyOptions
+): (call: TCall) => Promise<TResp> {
+  return async (call: TCall) => {
+    const result = await verifyGrpcCall(call.metadata, opts)
+    if (!result.ok) {
+      const err = Object.assign(new Error(result.message), { code: result.code })
+      throw err
+    }
+    ;(call as any)['7h3Envelope'] = result.envelope
+    return handler(call)
+  }
+}

package/src/httpBinding.test.ts

@@ -0,0 +1,376 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  verifyHttpEnvelope,
+  signHttpRequest,
+  signHttpRequestHmac,
+  createHttpMiddleware,
+  signFetchRequest,
+  createSignedFetchRequest,
+  DEFAULT_HEADER,
+} from './httpBinding'
+import { createStaticKeyRegistry, type KeyRegistry } from './keyRegistry'
+import {
+  generateEd25519KeypairBase64Url,
+  createEnvelope,
+  signEnvelopeEd25519,
+  signEnvelopeHmac,
+  type ProtocolEnvelope,
+} from './protocol'
+
+// Helper: build a static KeyRegistry that also holds HMAC shared secrets
+function createHmacKeyRegistry(secrets: Record<string, string>): KeyRegistry {
+  return {
+    async getPublicKey() { return null },
+    async getSharedSecret(keyId) { return secrets[keyId] ?? null },
+  }
+}
+
+describe('verifyHttpEnvelope', () => {
+  it('returns missing-header when header is absent', async () => {
+    const registry = createStaticKeyRegistry({})
+    const result = await verifyHttpEnvelope({}, { keyRegistry: registry })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('missing-header')
+  })
+
+  it('returns missing-header when header value is undefined', async () => {
+    const registry = createStaticKeyRegistry({})
+    const result = await verifyHttpEnvelope(
+      { [DEFAULT_HEADER]: undefined },
+      { keyRegistry: registry },
+    )
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('missing-header')
+  })
+
+  it('returns malformed-envelope for invalid JSON', async () => {
+    const registry = createStaticKeyRegistry({})
+    const result = await verifyHttpEnvelope(
+      { [DEFAULT_HEADER]: 'not-json' },
+      { keyRegistry: registry },
+    )
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.reason).toBe('malformed-envelope')
+      expect(result.detail).toContain('JSON parse failed')
+    }
+  })
+
+  it('returns malformed-envelope when required fields are missing', async () => {
+    const registry = createStaticKeyRegistry({})
+    const result = await verifyHttpEnvelope(
+      { [DEFAULT_HEADER]: JSON.stringify({ header: {} }) },
+      { keyRegistry: registry },
+    )
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('malformed-envelope')
+  })
+
+  it('passes a valid Ed25519 signed envelope', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-alice'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hello', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(signed) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(true)
+    if (result.ok) expect(result.envelope.header.sender).toBe(sender)
+  })
+
+  it('returns invalid-signature when envelope is tampered', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-bob'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hello', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+
+    // Tamper with the content after signing
+    const tampered: ProtocolEnvelope = {
+      ...signed,
+      body: { ...signed.body, content: 'tampered-content' },
+    }
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(tampered) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('invalid-signature')
+  })
+
+  it('returns unknown-sender when sender is not in registry', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const registry = createStaticKeyRegistry({}) // empty registry
+
+    const env = createEnvelope({ sender: 'unknown-agent', intent: 'PING', content: 'hi', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(signed) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.reason).toBe('unknown-sender')
+      expect(result.detail).toBe('unknown-agent')
+    }
+  })
+
+  it('returns ttl-expired for an expired envelope', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-expired'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    // Create envelope with past timestamp so it is already expired
+    const pastNow = Date.now() - 120_000 // 2 minutes ago
+    const env = createEnvelope({
+      sender,
+      intent: 'PING',
+      content: 'hello',
+      ttlMs: 1_000,      // 1 second TTL
+      nowMs: pastNow,
+    })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(signed) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry, strictTtl: true })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('ttl-expired')
+  })
+
+  it('skips TTL check when strictTtl is false', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-nostrictttl'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const pastNow = Date.now() - 120_000
+    const env = createEnvelope({
+      sender,
+      intent: 'PING',
+      content: 'hello',
+      ttlMs: 1_000,
+      nowMs: pastNow,
+    })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(signed) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry, strictTtl: false })
+    expect(result.ok).toBe(true)
+  })
+})
+
+describe('signHttpRequest + verifyHttpEnvelope round trip (Ed25519)', () => {
+  it('signs and verifies successfully', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-roundtrip'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'do something', ttlMs: 60_000 })
+    const { headers } = await signHttpRequest(env, privateKey)
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.envelope.header.sender).toBe(sender)
+      expect(result.envelope.body.intent).toBe('TASK')
+    }
+  })
+
+  it('uses custom header name when provided', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-custom-header'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+    const customHeader = 'x-custom-sig'
+
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hi', ttlMs: 60_000 })
+    const { headers } = await signHttpRequest(env, privateKey, { headerName: customHeader })
+
+    expect(headers[customHeader]).toBeDefined()
+    expect(headers[DEFAULT_HEADER]).toBeUndefined()
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry, headerName: customHeader })
+    expect(result.ok).toBe(true)
+  })
+})
+
+describe('createHttpMiddleware', () => {
+  it('calls next() when envelope is valid', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-middleware'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hi', ttlMs: 60_000 })
+    const signed = await signEnvelopeEd25519(env, privateKey)
+    const req = { headers: { [DEFAULT_HEADER]: JSON.stringify(signed) } }
+
+    const res = { status: vi.fn().mockReturnThis(), json: vi.fn() }
+    const next = vi.fn()
+
+    const middleware = createHttpMiddleware({ keyRegistry: registry })
+    await middleware(req, res as any, next)
+
+    expect(next).toHaveBeenCalledOnce()
+    expect(next).toHaveBeenCalledWith()  // no error argument
+    expect(res.status).not.toHaveBeenCalled()
+    // The envelope should be attached to req
+    expect((req as any)['7h3Envelope']).toBeDefined()
+  })
+
+  it('returns 401 and does not call next() when envelope is missing', async () => {
+    const registry = createStaticKeyRegistry({})
+    const req = { headers: {} }
+    const jsonMock = vi.fn()
+    const res = { status: vi.fn().mockReturnValue({ json: jsonMock }) }
+    const next = vi.fn()
+
+    const middleware = createHttpMiddleware({ keyRegistry: registry })
+    await middleware(req, res as any, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(jsonMock).toHaveBeenCalledWith(
+      expect.objectContaining({ reason: 'missing-header' }),
+    )
+    expect(next).not.toHaveBeenCalled()
+  })
+
+  it('returns 401 for invalid signature', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const { privateKey: otherPrivateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-bad-sig'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hi', ttlMs: 60_000 })
+    // Sign with wrong key
+    const signed = await signEnvelopeEd25519(env, otherPrivateKey)
+    const req = { headers: { [DEFAULT_HEADER]: JSON.stringify(signed) } }
+
+    const jsonMock = vi.fn()
+    const res = { status: vi.fn().mockReturnValue({ json: jsonMock }) }
+    const next = vi.fn()
+
+    const middleware = createHttpMiddleware({ keyRegistry: registry })
+    await middleware(req, res as any, next)
+
+    expect(res.status).toHaveBeenCalledWith(401)
+    expect(next).not.toHaveBeenCalled()
+  })
+})
+
+describe('signFetchRequest', () => {
+  it('adds the envelope header to a Request', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-fetch'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'fetch-task', ttlMs: 60_000 })
+    const originalRequest = new Request('https://example.com/api')
+    const signedRequest = await signFetchRequest(originalRequest, env, privateKey)
+
+    expect(signedRequest.headers.get(DEFAULT_HEADER)).not.toBeNull()
+
+    // Parse and verify
+    const headerVal = signedRequest.headers.get(DEFAULT_HEADER)!
+    const headers = { [DEFAULT_HEADER]: headerVal }
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(true)
+  })
+
+  it('preserves existing headers on the Request', async () => {
+    const { privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-headers'
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hi', ttlMs: 60_000 })
+    const originalRequest = new Request('https://example.com/api', {
+      headers: { 'Authorization': 'Bearer token123', 'Content-Type': 'application/json' },
+    })
+    const signedRequest = await signFetchRequest(originalRequest, env, privateKey)
+
+    expect(signedRequest.headers.get('Authorization')).toBe('Bearer token123')
+    expect(signedRequest.headers.get('Content-Type')).toBe('application/json')
+    expect(signedRequest.headers.get(DEFAULT_HEADER)).not.toBeNull()
+  })
+})
+
+describe('HMAC round trip', () => {
+  it('signs with HMAC and verifies successfully', async () => {
+    const secret = 'super-secret-hmac-key'
+    const keyId = 'hmac-key-1'
+    const sender = 'agent-hmac'
+    const registry = createHmacKeyRegistry({ [keyId]: secret })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'hmac task', ttlMs: 60_000 })
+    const { headers } = await signHttpRequestHmac(env, secret, keyId)
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.envelope.header.sender).toBe(sender)
+      expect(result.envelope.signature?.alg).toBe('HS256')
+    }
+  })
+
+  it('returns invalid-signature when HMAC tampered', async () => {
+    const secret = 'super-secret-hmac-key'
+    const keyId = 'hmac-key-2'
+    const sender = 'agent-hmac-tamper'
+    const registry = createHmacKeyRegistry({ [keyId]: secret })
+
+    const env = createEnvelope({ sender, intent: 'TASK', content: 'hmac task', ttlMs: 60_000 })
+    const signed = await signEnvelopeHmac(env, secret, keyId)
+
+    const tampered: ProtocolEnvelope = {
+      ...signed,
+      body: { ...signed.body, content: 'tampered' },
+    }
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(tampered) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('invalid-signature')
+  })
+
+  it('returns unknown-sender when HMAC keyId not in registry', async () => {
+    const secret = 'super-secret-hmac-key'
+    const keyId = 'hmac-key-missing'
+    const sender = 'agent-hmac-unknown'
+    const registry = createHmacKeyRegistry({}) // empty
+
+    const env = createEnvelope({ sender, intent: 'PING', content: 'hi', ttlMs: 60_000 })
+    const signed = await signEnvelopeHmac(env, secret, keyId)
+    const headers = { [DEFAULT_HEADER]: JSON.stringify(signed) }
+
+    const result = await verifyHttpEnvelope(headers, { keyRegistry: registry })
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.reason).toBe('unknown-sender')
+      expect(result.detail).toBe(keyId)
+    }
+  })
+})
+
+describe('createSignedFetchRequest', () => {
+  it('creates a signed fetch request with correct sender', async () => {
+    const { publicKey, privateKey } = await generateEd25519KeypairBase64Url()
+    const sender = 'agent-create-signed'
+    const registry = createStaticKeyRegistry({ [sender]: publicKey })
+
+    const originalRequest = new Request('https://example.com/api/task')
+    const signedRequest = await createSignedFetchRequest(originalRequest, {
+      privateKey,
+      sender,
+      ttlMs: 60_000,
+    })
+
+    const headerVal = signedRequest.headers.get(DEFAULT_HEADER)
+    expect(headerVal).not.toBeNull()
+
+    const result = await verifyHttpEnvelope(
+      { [DEFAULT_HEADER]: headerVal! },
+      { keyRegistry: registry },
+    )
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.envelope.header.sender).toBe(sender)
+      expect(result.envelope.body.intent).toBe('TASK')
+    }
+  })
+})