@7h3/protocol 0.1.2 → 0.5.0

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]
+}

package/src/signedResponse.test.ts

@@ -0,0 +1,111 @@
+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')
+  })
+})

package/src/signedResponse.ts

@@ -0,0 +1,83 @@
+import {
+  createEnvelope,
+  signEnvelopeEd25519,
+  verifyEnvelopeEd25519,
+  type ProtocolEnvelope,
+} from './protocol'
+
+export const RESPONSE_HEADER = 'x-7h3-response'
+
+export async function signResponse(
+  body: string,
+  opts: {
+    privateKey: string
+    sender: string
+    recipient?: string
+    correlationId?: string
+    ttlMs?: number
+  },
+): Promise<{ headers: { 'x-7h3-response': string } }> {
+  const envelope = createEnvelope({
+    sender: opts.sender,
+    recipient: opts.recipient,
+    intent: 'RESULT',
+    content: body,
+    correlationId: opts.correlationId,
+    ttlMs: opts.ttlMs ?? 60_000,
+  })
+
+  const signed = await signEnvelopeEd25519(envelope, opts.privateKey)
+
+  return {
+    headers: {
+      [RESPONSE_HEADER]: JSON.stringify(signed),
+    },
+  }
+}
+
+export async function verifyResponse(
+  body: string,
+  headers: Record<string, string | string[] | undefined>,
+  opts: {
+    publicKey: string
+    maxAgeMs?: number
+  },
+): Promise<{ ok: boolean; envelope?: ProtocolEnvelope; reason?: string }> {
+  const raw = headers[RESPONSE_HEADER]
+  const rawStr = Array.isArray(raw) ? raw[0] : raw
+  if (!rawStr) {
+    return { ok: false, reason: 'missing-header' }
+  }
+
+  let envelope: ProtocolEnvelope
+  try {
+    envelope = JSON.parse(rawStr) as ProtocolEnvelope
+  } catch {
+    return { ok: false, reason: 'malformed-envelope' }
+  }
+
+  // Check TTL from envelope
+  const nowMs = Date.now()
+  const { timestampMs, ttlMs } = envelope.header
+  if (timestampMs + ttlMs < nowMs) {
+    return { ok: false, reason: 'ttl-expired', envelope }
+  }
+
+  // Check maxAgeMs if provided
+  if (opts.maxAgeMs !== undefined && nowMs - timestampMs > opts.maxAgeMs) {
+    return { ok: false, reason: 'ttl-expired', envelope }
+  }
+
+  // Verify signature
+  const valid = await verifyEnvelopeEd25519(envelope, opts.publicKey)
+  if (!valid) {
+    return { ok: false, reason: 'invalid-signature', envelope }
+  }
+
+  // Verify body matches envelope content
+  if (envelope.body.content !== body) {
+    return { ok: false, reason: 'content-mismatch', envelope }
+  }
+
+  return { ok: true, envelope }
+}