@7h3/protocol 0.4.0 → 0.5.1

package/src/revocation.test.ts

@@ -1,98 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-import { InMemoryRedisLikeClient } from './redisClient'
-import {
-  InMemoryRevocationStore,
-  createRedisRevocationStore,
-  withRevocationCheck,
-} from './revocation'
-import type { SignatureVerificationMaterial } from './protocol'
-
-describe('InMemoryRevocationStore', () => {
-  it('reports a key as not revoked until it is revoked', async () => {
-    const store = new InMemoryRevocationStore()
-    expect(await store.isRevoked('agent.a', 'k1')).toBe(false)
-    await store.revoke('agent.a', 'k1')
-    expect(await store.isRevoked('agent.a', 'k1')).toBe(true)
-  })
-
-  it('scopes revocation to the exact (sender, keyId) pair', async () => {
-    const store = new InMemoryRevocationStore()
-    await store.revoke('agent.a', 'k1')
-    expect(await store.isRevoked('agent.a', 'k2')).toBe(false)
-    expect(await store.isRevoked('agent.b', 'k1')).toBe(false)
-  })
-
-  it('honors a time-bounded revocation (untilMs)', async () => {
-    let now = 1000
-    const store = new InMemoryRevocationStore({ now: () => now })
-    await store.revoke('agent.a', 'k1', { untilMs: 2000 })
-    expect(await store.isRevoked('agent.a', 'k1')).toBe(true)
-    now = 2500
-    expect(await store.isRevoked('agent.a', 'k1')).toBe(false)
-  })
-})
-
-describe('createRedisRevocationStore', () => {
-  it('revoke writes a key that isRevoked reads back', async () => {
-    const store = createRedisRevocationStore(new InMemoryRedisLikeClient())
-    expect(await store.isRevoked('agent.a', 'k1')).toBe(false)
-    await store.revoke('agent.a', 'k1')
-    expect(await store.isRevoked('agent.a', 'k1')).toBe(true)
-  })
-
-  it('caches reads so repeated checks within the freshness window hit Redis once', async () => {
-    let now = 1000
-    const client = new InMemoryRedisLikeClient({ now: () => now })
-    const getSpy = vi.spyOn(client, 'get')
-    const store = createRedisRevocationStore(client, { cacheTtlMs: 5000, now: () => now })
-    await store.isRevoked('agent.a', 'k1')
-    await store.isRevoked('agent.a', 'k1')
-    expect(getSpy).toHaveBeenCalledOnce()
-    now = 7000 // past the cache window
-    await store.isRevoked('agent.a', 'k1')
-    expect(getSpy).toHaveBeenCalledTimes(2)
-  })
-
-  it('fails closed by default: a Redis error means the key is treated as revoked', async () => {
-    const onDegraded = vi.fn()
-    const throwing = {
-      set: async () => 'OK' as const,
-      get: async () => {
-        throw new Error('redis unreachable')
-      },
-    }
-    const store = createRedisRevocationStore(throwing, { onDegraded })
-    expect(await store.isRevoked('agent.a', 'k1')).toBe(true)
-    expect(onDegraded).toHaveBeenCalledOnce()
-  })
-
-  it('errorBehavior "allow" treats a Redis error as not revoked', async () => {
-    const throwing = {
-      set: async () => 'OK' as const,
-      get: async () => {
-        throw new Error('redis unreachable')
-      },
-    }
-    const store = createRedisRevocationStore(throwing, { errorBehavior: 'allow' })
-    expect(await store.isRevoked('agent.a', 'k1')).toBe(false)
-  })
-})
-
-describe('withRevocationCheck (signature resolver wrapper)', () => {
-  const material: SignatureVerificationMaterial = { alg: 'HS256', secret: 's3cret' }
-  const innerResolver = async () => material
-  const signature = { alg: 'HS256' as const, keyId: 'k1', value: 'sig' }
-
-  it('returns material for a key that is not revoked', async () => {
-    const store = new InMemoryRevocationStore()
-    const resolver = withRevocationCheck(innerResolver, store)
-    expect(await resolver(signature, 'agent.a')).toEqual(material)
-  })
-
-  it('returns undefined (verification fails) for a revoked key', async () => {
-    const store = new InMemoryRevocationStore()
-    await store.revoke('agent.a', 'k1')
-    const resolver = withRevocationCheck(innerResolver, store)
-    expect(await resolver(signature, 'agent.a')).toBeUndefined()
-  })
-})

package/src/routePolicy.test.ts

@@ -1,87 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { matchGlob, matchPolicy, isAllowedSender, type RoutePolicy } from './routePolicy'
-
-describe('matchGlob', () => {
-  it('exact match', () => {
-    expect(matchGlob('/health', '/health')).toBe(true)
-    expect(matchGlob('/health', '/healthz')).toBe(false)
-  })
-
-  it('single * does not cross segments', () => {
-    expect(matchGlob('/api/*', '/api/users')).toBe(true)
-    expect(matchGlob('/api/*', '/api/users/list')).toBe(false)
-    expect(matchGlob('/api/*', '/api/')).toBe(true) // empty segment is still "within"
-  })
-
-  it('double ** matches any depth', () => {
-    expect(matchGlob('/api/**', '/api/users')).toBe(true)
-    expect(matchGlob('/api/**', '/api/users/list')).toBe(true)
-    expect(matchGlob('/api/**', '/api/a/b/c/d')).toBe(true)
-    expect(matchGlob('/api/**', '/other/users')).toBe(false)
-  })
-
-  it('? matches single non-slash char', () => {
-    expect(matchGlob('/v?/api', '/v1/api')).toBe(true)
-    expect(matchGlob('/v?/api', '/v12/api')).toBe(false)
-    expect(matchGlob('/v?/api', '/v//api')).toBe(false)
-  })
-
-  it('handles regex metacharacters in literal path', () => {
-    expect(matchGlob('/api/v1.0/health', '/api/v1.0/health')).toBe(true)
-    expect(matchGlob('/api/v1.0/health', '/api/v100/health')).toBe(false)
-  })
-})
-
-describe('matchPolicy', () => {
-  const policies: RoutePolicy[] = [
-    { path: '/health', require: 'none' },
-    { path: '/api/admin/**', require: 'ed25519', allowedSenders: ['admin-agent'] },
-    { path: '/api/*', require: 'any' },
-    { path: '/webhook/**', require: 'hmac' },
-  ]
-
-  it('returns first matching policy (exact before wildcard)', () => {
-    const result = matchPolicy(policies, '/health')
-    expect(result?.require).toBe('none')
-  })
-
-  it('matches /api/users with /api/*', () => {
-    const result = matchPolicy(policies, '/api/users')
-    expect(result?.require).toBe('any')
-  })
-
-  it('/api/admin/delete matches /api/admin/** before /api/*', () => {
-    const result = matchPolicy(policies, '/api/admin/delete')
-    expect(result?.require).toBe('ed25519')
-  })
-
-  it('matches deep webhook path', () => {
-    const result = matchPolicy(policies, '/webhook/stripe/events')
-    expect(result?.require).toBe('hmac')
-  })
-
-  it('returns null for no match', () => {
-    const result = matchPolicy(policies, '/unknown')
-    expect(result).toBeNull()
-  })
-})
-
-describe('isAllowedSender', () => {
-  it('allows all senders when allowedSenders not set', () => {
-    const policy: RoutePolicy = { path: '/api/*', require: 'any' }
-    expect(isAllowedSender(policy, 'any-agent')).toBe(true)
-    expect(isAllowedSender(policy, 'another-agent')).toBe(true)
-  })
-
-  it('allows only listed senders', () => {
-    const policy: RoutePolicy = { path: '/api/*', require: 'ed25519', allowedSenders: ['trusted-agent', 'another-agent'] }
-    expect(isAllowedSender(policy, 'trusted-agent')).toBe(true)
-    expect(isAllowedSender(policy, 'another-agent')).toBe(true)
-    expect(isAllowedSender(policy, 'unknown-agent')).toBe(false)
-  })
-
-  it('empty allowedSenders array allows all', () => {
-    const policy: RoutePolicy = { path: '/api/*', require: 'any', allowedSenders: [] }
-    expect(isAllowedSender(policy, 'anyone')).toBe(true)
-  })
-})

package/src/routePolicy.ts

@@ -1,72 +0,0 @@
-export type PolicyRequirement = 'ed25519' | 'hmac' | 'any' | 'none'
-
-export interface RoutePolicy {
-  path: string
-  require: PolicyRequirement
-  rateLimit?: { requests: number; windowMs: number }
-  allowedSenders?: string[]
-  signResponse?: boolean
-}
-
-/**
- * Translate a glob pattern to a RegExp.
- * Supported:
- *   - exact: '/health'
- *   - '?'  → any single non-slash char
- *   - '*'  → any chars within a single segment (no slash)
- *   - '**' → any chars at any depth (including slashes)
- */
-export function matchGlob(pattern: string, path: string): boolean {
-  // Build regex from pattern, handling ** before * to avoid double-expanding
-  let regexStr = '^'
-  let i = 0
-  while (i < pattern.length) {
-    const ch = pattern[i]
-    if (ch === '*') {
-      if (pattern[i + 1] === '*') {
-        // Double star: matches anything including /
-        regexStr += '.*'
-        i += 2
-      } else {
-        // Single star: matches any non-slash sequence
-        regexStr += '[^/]*'
-        i += 1
-      }
-    } else if (ch === '?') {
-      // Single char, not slash
-      regexStr += '[^/]'
-      i += 1
-    } else {
-      // Escape regex metacharacters in literal segments
-      regexStr += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&')
-      i += 1
-    }
-  }
-  regexStr += '$'
-
-  return new RegExp(regexStr).test(path)
-}
-
-/**
- * Find the first matching policy for a given path.
- * Returns null if no policy matches.
- */
-export function matchPolicy(policies: RoutePolicy[], path: string): RoutePolicy | null {
-  for (const policy of policies) {
-    if (matchGlob(policy.path, path)) {
-      return policy
-    }
-  }
-  return null
-}
-
-/**
- * Check whether a sender is permitted by a policy.
- * If allowedSenders is not set, all senders are allowed.
- */
-export function isAllowedSender(policy: RoutePolicy, sender: string): boolean {
-  if (!policy.allowedSenders || policy.allowedSenders.length === 0) {
-    return true
-  }
-  return policy.allowedSenders.includes(sender)
-}

package/src/runtimePolicy.test.ts

@@ -1,49 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { loadRuntimePolicy, parseRuntimePolicyJson, validateRuntimePolicy } from './runtimePolicy'
-
-describe('runtime policy loader', () => {
-  it('parses valid policy JSON', () => {
-    const policy = parseRuntimePolicyJson(
-      JSON.stringify({
-        version: '1.0',
-        name: 'gluv-runtime-policy',
-        status: 'active',
-      }),
-    )
-
-    expect(policy.version).toBe('1.0')
-    expect(policy.name).toBe('gluv-runtime-policy')
-    expect(policy.status).toBe('active')
-  })
-
-  it('rejects invalid JSON', () => {
-    expect(() => parseRuntimePolicyJson('{')).toThrow(/Invalid runtime policy JSON/i)
-  })
-
-  it('rejects invalid root object', () => {
-    expect(() => validateRuntimePolicy('not-an-object')).toThrow(/root must be an object/i)
-  })
-
-  it('rejects missing required fields', () => {
-    expect(() => validateRuntimePolicy({ name: 'x', status: 'active' })).toThrow(/version/i)
-    expect(() => validateRuntimePolicy({ version: '1.0', status: 'active' })).toThrow(/name/i)
-    expect(() => validateRuntimePolicy({ version: '1.0', name: 'x' })).toThrow(/status/i)
-  })
-
-  it('loads policy using injected reader and path', async () => {
-    const policy = await loadRuntimePolicy({
-      path: '/virtual/AI_RUNTIME_POLICY.json',
-      readTextFile: async (filePath) => {
-        expect(filePath).toBe('/virtual/AI_RUNTIME_POLICY.json')
-        return JSON.stringify({
-          version: '1.0',
-          name: 'gluv-runtime-policy',
-          status: 'active',
-          owner: 'platform-ai-ops',
-        })
-      },
-    })
-
-    expect(policy.owner).toBe('platform-ai-ops')
-  })
-})

package/src/runtimePolicy.ts

@@ -1,81 +0,0 @@
-export interface RuntimePolicy {
-  version: string
-  name: string
-  status: string
-  owner?: string
-  updated_at?: string
-  hard_invariants?: Record<string, unknown>
-  slo_defaults?: Record<string, unknown>
-  mode_selection?: Record<string, unknown>
-  guardrails?: Record<string, unknown>
-  tuning?: Record<string, unknown>
-  adaptive_flow?: Record<string, unknown>
-  benchmark_policy?: Record<string, unknown>
-  runtime_decision_tree?: unknown[]
-  operator_handoff_required_fields?: string[]
-  [key: string]: unknown
-}
-
-export interface LoadRuntimePolicyOptions {
-  path?: string
-  readTextFile?: (filePath: string) => Promise<string>
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-function asNonEmptyString(value: unknown, field: string): string {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`Invalid runtime policy: '${field}' must be a non-empty string`)
-  }
-  return value
-}
-
-export function validateRuntimePolicy(value: unknown): RuntimePolicy {
-  if (!isRecord(value)) {
-    throw new Error('Invalid runtime policy: root must be an object')
-  }
-
-  const version = asNonEmptyString(value.version, 'version')
-  const name = asNonEmptyString(value.name, 'name')
-  const status = asNonEmptyString(value.status, 'status')
-
-  return {
-    ...value,
-    version,
-    name,
-    status,
-  }
-}
-
-export function parseRuntimePolicyJson(jsonText: string): RuntimePolicy {
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(jsonText)
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
-    throw new Error(`Invalid runtime policy JSON: ${message}`)
-  }
-  return validateRuntimePolicy(parsed)
-}
-
-async function defaultReadTextFile(filePath: string): Promise<string> {
-  if (typeof fetch === 'function') {
-    const response = await fetch(filePath)
-    if (!response.ok) {
-      throw new Error(`Failed to fetch runtime policy at '${filePath}': ${response.status} ${response.statusText}`)
-    }
-    return response.text()
-  }
-  throw new Error(
-    "No default runtime file reader available in this environment. Provide 'readTextFile' in loadRuntimePolicy(options).",
-  )
-}
-
-export async function loadRuntimePolicy(options: LoadRuntimePolicyOptions = {}): Promise<RuntimePolicy> {
-  const filePath = options.path ?? 'AI_RUNTIME_POLICY.json'
-  const readTextFile = options.readTextFile ?? defaultReadTextFile
-  const text = await readTextFile(filePath)
-  return parseRuntimePolicyJson(text)
-}

package/src/runtimePolicyManager.test.ts

@@ -1,29 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { RuntimePolicyManager } from './runtimePolicyManager'
-
-describe('runtime policy manager', () => {
-  it('loads initial policy and exposes snapshot', async () => {
-    const manager = new RuntimePolicyManager({
-      path: '/virtual/AI_RUNTIME_POLICY.json',
-      readTextFile: async () =>
-        JSON.stringify({
-          version: '1.0',
-          name: 'gluv-runtime-policy',
-          status: 'active',
-          hard_invariants: {},
-          slo_defaults: {},
-          tuning: {
-            batch_size: { low_traffic: [4, 8], medium_traffic: [8, 32], high_traffic: [32, 64] },
-            inflight_cap: { low_traffic: [16, 64], medium_traffic: [64, 256], high_traffic: [256, 1024] },
-            retry_backoff_ms: { low_traffic: [1, 2], medium_traffic: [2, 8], high_traffic: [4, 16] },
-            max_retry_attempts: 3,
-            retriable_status_codes: [503],
-          },
-        }),
-    })
-
-    const loaded = await manager.loadInitial()
-    expect(loaded.policy.name).toBe('gluv-runtime-policy')
-    expect(manager.current().policy.version).toBe('1.0')
-  })
-})

package/src/runtimePolicyManager.ts

@@ -1,50 +0,0 @@
-import { bootstrapRuntimePolicyEnforcer, type BootstrapRuntimePolicyEnforcerOptions, type PolicyEnforcer } from './policyEnforcer'
-import type { RuntimePolicy } from './runtimePolicy'
-
-export interface RuntimePolicySnapshot {
-  policy: RuntimePolicy
-  enforcer: PolicyEnforcer
-  loadedAtMs: number
-}
-
-export class RuntimePolicyManager {
-  private snapshot: RuntimePolicySnapshot | null = null
-  private readonly options: BootstrapRuntimePolicyEnforcerOptions
-
-  constructor(options: BootstrapRuntimePolicyEnforcerOptions = {}) {
-    this.options = options
-  }
-
-  async loadInitial(): Promise<RuntimePolicySnapshot> {
-    const loaded = await bootstrapRuntimePolicyEnforcer(this.options)
-    this.snapshot = {
-      ...loaded,
-      loadedAtMs: Date.now(),
-    }
-    return this.snapshot
-  }
-
-  current(): RuntimePolicySnapshot {
-    if (!this.snapshot) {
-      throw new Error('Runtime policy not loaded. Call loadInitial() first.')
-    }
-    return this.snapshot
-  }
-
-  async refresh(): Promise<RuntimePolicySnapshot> {
-    const previous = this.snapshot
-    try {
-      const loaded = await bootstrapRuntimePolicyEnforcer(this.options)
-      this.snapshot = {
-        ...loaded,
-        loadedAtMs: Date.now(),
-      }
-      return this.snapshot
-    } catch (error) {
-      if (previous) {
-        return previous
-      }
-      throw error
-    }
-  }
-}

package/src/runtimePolicyPresets.ts

@@ -1,43 +0,0 @@
-import type { RuntimeMode } from './policyEnforcer'
-
-export type RuntimeEnvironment = 'dev' | 'staging' | 'prod'
-
-export interface RuntimeTuningPreset {
-  environment: RuntimeEnvironment
-  mode: RuntimeMode
-  poolSize: number
-  batchSize: number
-  inflightCap: number
-  retryMaxAttempts: number
-}
-
-const PRESETS: Record<RuntimeEnvironment, RuntimeTuningPreset> = {
-  dev: {
-    environment: 'dev',
-    mode: 'ws-batch',
-    poolSize: 1,
-    batchSize: 8,
-    inflightCap: 64,
-    retryMaxAttempts: 2,
-  },
-  staging: {
-    environment: 'staging',
-    mode: 'http-binary-batch',
-    poolSize: 2,
-    batchSize: 32,
-    inflightCap: 256,
-    retryMaxAttempts: 3,
-  },
-  prod: {
-    environment: 'prod',
-    mode: 'http-binary-batch',
-    poolSize: 4,
-    batchSize: 64,
-    inflightCap: 1024,
-    retryMaxAttempts: 3,
-  },
-}
-
-export function getRuntimeTuningPreset(environment: RuntimeEnvironment): RuntimeTuningPreset {
-  return PRESETS[environment]
-}

package/src/signedResponse.test.ts

@@ -1,111 +0,0 @@
-import { describe, it, expect, beforeAll } from 'vitest'
-import { signResponse, verifyResponse, RESPONSE_HEADER } from './signedResponse'
-import { generateEd25519KeypairBase64Url } from './protocol'
-
-let keys: { publicKey: string; privateKey: string }
-let wrongKeys: { publicKey: string; privateKey: string }
-
-beforeAll(async () => {
-  keys = await generateEd25519KeypairBase64Url()
-  wrongKeys = await generateEd25519KeypairBase64Url()
-})
-
-describe('signedResponse', () => {
-  it('round-trip: signs and verifies correctly', async () => {
-    const body = 'hello world'
-    const { headers } = await signResponse(body, {
-      privateKey: keys.privateKey,
-      sender: 'gateway-agent',
-    })
-
-    const result = await verifyResponse(body, headers, { publicKey: keys.publicKey })
-    expect(result.ok).toBe(true)
-    expect(result.envelope?.body.intent).toBe('RESULT')
-    expect(result.envelope?.body.content).toBe(body)
-  })
-
-  it('fails when body does not match envelope content', async () => {
-    const body = 'original body'
-    const { headers } = await signResponse(body, {
-      privateKey: keys.privateKey,
-      sender: 'gateway-agent',
-    })
-
-    const result = await verifyResponse('tampered body', headers, { publicKey: keys.publicKey })
-    expect(result.ok).toBe(false)
-    expect(result.reason).toBe('content-mismatch')
-  })
-
-  it('fails with wrong public key', async () => {
-    const body = 'some content'
-    const { headers } = await signResponse(body, {
-      privateKey: keys.privateKey,
-      sender: 'gateway-agent',
-    })
-
-    const result = await verifyResponse(body, headers, { publicKey: wrongKeys.publicKey })
-    expect(result.ok).toBe(false)
-    expect(result.reason).toBe('invalid-signature')
-  })
-
-  it('fails when header is missing', async () => {
-    const result = await verifyResponse('body', {}, { publicKey: keys.publicKey })
-    expect(result.ok).toBe(false)
-    expect(result.reason).toBe('missing-header')
-  })
-
-  it('fails when envelope TTL is expired', async () => {
-    // Sign with 1ms ttl — immediately expired
-    const body = 'ttl-test'
-    const { headers } = await signResponse(body, {
-      privateKey: keys.privateKey,
-      sender: 'gateway-agent',
-      ttlMs: 1,
-    })
-
-    // Wait a tick to ensure expiry
-    await new Promise(r => setTimeout(r, 10))
-
-    const result = await verifyResponse(body, headers, { publicKey: keys.publicKey })
-    expect(result.ok).toBe(false)
-    expect(result.reason).toBe('ttl-expired')
-  })
-
-  it('fails when maxAgeMs exceeded', async () => {
-    const body = 'max-age-test'
-    const { headers } = await signResponse(body, {
-      privateKey: keys.privateKey,
-      sender: 'gateway-agent',
-      ttlMs: 60_000, // long ttl
-    })
-
-    // Wait to ensure age exceeds maxAgeMs
-    await new Promise(r => setTimeout(r, 10))
-
-    const result = await verifyResponse(body, headers, {
-      publicKey: keys.publicKey,
-      maxAgeMs: 1, // tiny window
-    })
-    expect(result.ok).toBe(false)
-    expect(result.reason).toBe('ttl-expired')
-  })
-
-  it('passes correlationId and recipient through envelope', async () => {
-    const body = 'corr-test'
-    const { headers } = await signResponse(body, {
-      privateKey: keys.privateKey,
-      sender: 'gateway-agent',
-      recipient: 'client-agent',
-      correlationId: 'req-123',
-    })
-
-    const result = await verifyResponse(body, headers, { publicKey: keys.publicKey })
-    expect(result.ok).toBe(true)
-    expect(result.envelope?.body.correlationId).toBe('req-123')
-    expect(result.envelope?.header.recipient).toBe('client-agent')
-  })
-
-  it('RESPONSE_HEADER constant is x-7h3-response', () => {
-    expect(RESPONSE_HEADER).toBe('x-7h3-response')
-  })
-})