@7h3/protocol 0.1.2 → 0.4.0

package/src/replayStores.ts

@@ -0,0 +1,82 @@
+import type { DistributedReplayStore } from './protocolReplay'
+import { InMemoryRedisLikeClient, type RedisLikeClient } from './redisClient'
+
+/**
+ * What to do when the Redis client throws (network blip, server down).
+ *
+ * - `fallback` (default): degrade to a local in-memory store so traffic keeps
+ *   flowing with single-node replay protection still in force. Quality +
+ *   reliability + scalability: Redis is never a fleet-wide kill switch.
+ * - `reject`: fail closed — deny the message because uniqueness cannot be confirmed.
+ * - `allow`: fail open — accept the message (skip the check) to maximise uptime.
+ */
+export type ReplayErrorBehavior = 'fallback' | 'reject' | 'allow'
+
+export interface RedisReplayStoreOptions {
+  /** Key namespace in Redis. Default `aip:replay:`. */
+  keyPrefix?: string
+  /** Behavior when the Redis client throws. Default `fallback`. */
+  errorBehavior?: ReplayErrorBehavior
+  /** Local store used when `errorBehavior` is `fallback`. Defaults to an in-memory-backed store. */
+  fallback?: DistributedReplayStore
+  /** Observability hook fired whenever a Redis error forces degraded handling. */
+  onDegraded?: (error: unknown, context: { key: string; behavior: ReplayErrorBehavior }) => void
+}
+
+/**
+ * Creates a {@link DistributedReplayStore} backed by Redis-style `SET NX PX`.
+ *
+ * Drop the returned store into `new DistributedReplayCache(store)` (or pass a
+ * `DistributedReplayCache` as the transport `replayCache`).
+ */
+export function createRedisReplayStore(
+  client: RedisLikeClient,
+  options: RedisReplayStoreOptions = {},
+): DistributedReplayStore {
+  const keyPrefix = options.keyPrefix ?? 'aip:replay:'
+  const errorBehavior = options.errorBehavior ?? 'fallback'
+  const onDegraded = options.onDegraded
+  const fallback =
+    options.fallback ??
+    (errorBehavior === 'fallback'
+      ? // The local fallback runs over a non-throwing in-memory client, so it
+        // needs no fallback of its own — `reject` terminates the chain.
+        createRedisReplayStore(new InMemoryRedisLikeClient(), { keyPrefix, errorBehavior: 'reject' })
+      : undefined)
+
+  function degrade(error: unknown, key: string, expiresAtMs: number, nowMs: number): Promise<boolean> | boolean {
+    onDegraded?.(error, { key, behavior: errorBehavior })
+    if (errorBehavior === 'allow') return true
+    if (errorBehavior === 'reject') return false
+    return fallback ? fallback.reserve(key, expiresAtMs, nowMs) : false
+  }
+
+  return {
+    async reserve(key: string, expiresAtMs: number, nowMs: number): Promise<boolean> {
+      const pxMs = Math.max(1, expiresAtMs - nowMs)
+      try {
+        const result = await client.set(`${keyPrefix}${key}`, '1', { nx: true, pxMs })
+        return result === 'OK'
+      } catch (error) {
+        return degrade(error, key, expiresAtMs, nowMs)
+      }
+    },
+
+    async reserveMany(entries: Array<{ key: string; expiresAtMs: number }>, nowMs: number): Promise<boolean[]> {
+      if (entries.length === 0) return []
+      if (client.pipeline) {
+        try {
+          const batch = client.pipeline()
+          for (const { key, expiresAtMs } of entries) {
+            batch.set(`${keyPrefix}${key}`, '1', { nx: true, pxMs: Math.max(1, expiresAtMs - nowMs) })
+          }
+          const results = await batch.exec()
+          return results.map((result) => result === 'OK')
+        } catch (error) {
+          return Promise.all(entries.map((entry) => degrade(error, entry.key, entry.expiresAtMs, nowMs)))
+        }
+      }
+      return Promise.all(entries.map((entry) => this.reserve(entry.key, entry.expiresAtMs, nowMs)))
+    },
+  }
+}

package/src/revocation.test.ts

@@ -0,0 +1,98 @@
+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

@@ -0,0 +1,87 @@
+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

@@ -0,0 +1,72 @@
+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

@@ -0,0 +1,49 @@
+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

@@ -0,0 +1,81 @@
+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

@@ -0,0 +1,29 @@
+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

@@ -0,0 +1,50 @@
+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

@@ -0,0 +1,43 @@
+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]
+}