@7h3/protocol 0.1.2 → 0.4.0

package/src/policyEnforcer.ts

@@ -0,0 +1,169 @@
+import { loadRuntimePolicy, type LoadRuntimePolicyOptions, type RuntimePolicy } from './runtimePolicy'
+
+export type RuntimeMode =
+  | 'http'
+  | 'ws'
+  | 'http-binary'
+  | 'http-batch'
+  | 'http-binary-batch'
+  | 'ws-batch'
+  | 'ws-binary'
+  | 'ws-binary-batch'
+
+export interface ModeSelectionInput {
+  concurrency: number
+  latencySensitive?: boolean
+  compatibilityFirst?: boolean
+}
+
+export interface TuningInput {
+  trafficClass: 'low' | 'medium' | 'high'
+  p99Ms?: number
+  dropPct?: number
+}
+
+export interface TuningDecision {
+  batchSizeRange: [number, number]
+  inflightCapRange: [number, number]
+  retryBackoffMsRange: [number, number]
+  actions: string[]
+}
+
+export interface RetryInput {
+  error: unknown
+  attempt: number
+}
+
+export interface InvariantConfig {
+  signatureVerification: boolean
+  canonicalization: boolean
+  replayDefense: boolean
+  ttlClockSkewEnforcement: boolean
+}
+
+function asNumberPair(value: unknown, label: string): [number, number] {
+  if (!Array.isArray(value) || value.length !== 2) {
+    throw new Error(`Invalid policy tuning range '${label}': expected [min,max]`)
+  }
+  const min = Number(value[0])
+  const max = Number(value[1])
+  if (!Number.isFinite(min) || !Number.isFinite(max) || min <= 0 || max < min) {
+    throw new Error(`Invalid policy tuning range '${label}': expected positive ascending numbers`)
+  }
+  return [Math.floor(min), Math.floor(max)]
+}
+
+function includeHttpLiteral(mode: string): mode is RuntimeMode {
+  return (
+    mode === 'http' ||
+    mode === 'ws' ||
+    mode === 'http-binary' ||
+    mode === 'http-batch' ||
+    mode === 'http-binary-batch' ||
+    mode === 'ws-batch' ||
+    mode === 'ws-binary' ||
+    mode === 'ws-binary-batch'
+  )
+}
+
+export function createPolicyEnforcer(policy: RuntimePolicy) {
+  const dropPctMax = Number((policy.slo_defaults ?? {}).drop_pct_max ?? 0.1)
+  const p99MsMax = Number((policy.slo_defaults ?? {}).p99_ms_max ?? 20)
+  const maxRetryAttempts = Number((policy.tuning ?? {}).max_retry_attempts ?? 3)
+  const retriableStatusCodes = Array.isArray((policy.tuning ?? {}).retriable_status_codes)
+    ? ((policy.tuning ?? {}).retriable_status_codes as unknown[])
+        .map((value) => Number(value))
+        .filter((value) => Number.isFinite(value))
+    : [503]
+
+  const tuning = policy.tuning ?? {}
+  const batchSize = tuning.batch_size as Record<string, unknown>
+  const inflightCap = tuning.inflight_cap as Record<string, unknown>
+  const retryBackoff = tuning.retry_backoff_ms as Record<string, unknown>
+
+  const getRanges = (trafficClass: 'low' | 'medium' | 'high') => ({
+    batchSizeRange: asNumberPair(batchSize?.[`${trafficClass}_traffic`], `batch_size.${trafficClass}_traffic`),
+    inflightCapRange: asNumberPair(inflightCap?.[`${trafficClass}_traffic`], `inflight_cap.${trafficClass}_traffic`),
+    retryBackoffMsRange: asNumberPair(retryBackoff?.[`${trafficClass}_traffic`], `retry_backoff_ms.${trafficClass}_traffic`),
+  })
+
+  function selectMode(input: ModeSelectionInput): RuntimeMode {
+    if (input.concurrency >= 100) return 'http-binary-batch'
+    if (input.latencySensitive) return 'ws-batch'
+    if (input.compatibilityFirst) return 'http'
+    return 'ws-batch'
+  }
+
+  function tune(input: TuningInput): TuningDecision {
+    const ranges = getRanges(input.trafficClass)
+    const actions: string[] = []
+
+    if (typeof input.dropPct === 'number' && input.dropPct > dropPctMax) {
+      actions.push('reduce inflight cap')
+      actions.push('reduce batch size')
+      actions.push('increase retry backoff')
+      actions.push('switch to binary-batch mode')
+    }
+    if (typeof input.p99Ms === 'number' && input.p99Ms > p99MsMax) {
+      actions.push('reduce batch size')
+      actions.push('reduce inflight cap')
+      actions.push('re-run adaptive benchmark')
+    }
+
+    return {
+      ...ranges,
+      actions,
+    }
+  }
+
+  function shouldRetry(input: RetryInput): boolean {
+    if (input.attempt >= maxRetryAttempts) return false
+    const message = input.error instanceof Error ? input.error.message : String(input.error)
+    const statusFromMessage = /http status\s+(\d+)/i.exec(message)
+    const statusCode = statusFromMessage ? Number(statusFromMessage[1]) : NaN
+    return Number.isFinite(statusCode) && retriableStatusCodes.includes(statusCode)
+  }
+
+  function assertInvariant(config: InvariantConfig): void {
+    const failures: string[] = []
+    if (!config.signatureVerification) failures.push('signatureVerification=false')
+    if (!config.canonicalization) failures.push('canonicalization=false')
+    if (!config.replayDefense) failures.push('replayDefense=false')
+    if (!config.ttlClockSkewEnforcement) failures.push('ttlClockSkewEnforcement=false')
+    if (failures.length > 0) {
+      throw new Error(`Invariant violation: ${failures.join(', ')}`)
+    }
+  }
+
+  return {
+    selectMode,
+    tune,
+    shouldRetry,
+    assertInvariant,
+    metadata: {
+      policyName: policy.name,
+      policyVersion: policy.version,
+      policyStatus: policy.status,
+      enforcedSlo: {
+        dropPctMax,
+        p99MsMax,
+      },
+    },
+  }
+}
+
+export type PolicyEnforcer = ReturnType<typeof createPolicyEnforcer>
+
+export type BootstrapRuntimePolicyEnforcerOptions = LoadRuntimePolicyOptions
+
+export async function bootstrapRuntimePolicyEnforcer(
+  options: BootstrapRuntimePolicyEnforcerOptions = {},
+): Promise<{ policy: RuntimePolicy; enforcer: PolicyEnforcer }> {
+  const policy = await loadRuntimePolicy(options)
+  const enforcer = createPolicyEnforcer(policy)
+  return { policy, enforcer }
+}
+
+export function isRuntimeMode(value: string): value is RuntimeMode {
+  return includeHttpLiteral(value)
+}

package/src/policyTelemetryFeedback.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { recommendPolicyAdjustments } from './policyTelemetryFeedback'
+
+describe('policy telemetry feedback', () => {
+  it('returns critical recommendation for severe drop/latency', () => {
+    const rec = recommendPolicyAdjustments({
+      mode: 'http',
+      p99Ms: 120,
+      dropPct: 5,
+      concurrency: 200,
+    })
+    expect(rec.severity).toBe('critical')
+    expect(rec.actions.length).toBeGreaterThan(0)
+  })
+
+  it('returns normal when metrics are healthy', () => {
+    const rec = recommendPolicyAdjustments({
+      mode: 'http-binary-batch',
+      p99Ms: 8,
+      dropPct: 0,
+      concurrency: 100,
+    })
+    expect(rec.severity).toBe('normal')
+  })
+})

package/src/policyTelemetryFeedback.ts

@@ -0,0 +1,38 @@
+export interface TelemetryFeedbackInput {
+  mode: string
+  p99Ms: number
+  dropPct: number
+  concurrency: number
+}
+
+export interface TelemetryFeedbackRecommendation {
+  severity: 'normal' | 'warn' | 'critical'
+  actions: string[]
+}
+
+export function recommendPolicyAdjustments(input: TelemetryFeedbackInput): TelemetryFeedbackRecommendation {
+  const actions: string[] = []
+  let severity: TelemetryFeedbackRecommendation['severity'] = 'normal'
+
+  if (input.dropPct > 0.1) {
+    actions.push('reduce inflight cap')
+    actions.push('reduce batch size')
+    actions.push('increase retry backoff')
+    if (input.mode === 'http' && input.concurrency >= 100) {
+      actions.push('switch to http-binary-batch')
+    }
+    severity = input.dropPct > 2 ? 'critical' : 'warn'
+  }
+
+  if (input.p99Ms > 20) {
+    actions.push('reduce batch size')
+    actions.push('run adaptive benchmark and re-baseline')
+    if (severity === 'normal') severity = 'warn'
+    if (input.p99Ms > 100) severity = 'critical'
+  }
+
+  return {
+    severity,
+    actions,
+  }
+}

package/src/protocol.bench.ts

@@ -0,0 +1,37 @@
+import { bench, describe } from 'vitest'
+import { canonicalizeEnvelope, createEnvelope, signEnvelopeHmac, verifyEnvelopeHmac } from './protocol'
+import { decodeEnvelope, encodeEnvelope } from './protocolTransport'
+
+const unsigned = createEnvelope({
+  sender: 'agent.alpha',
+  recipient: 'agent.beta',
+  intent: 'TASK',
+  content: 'route-optimize:alpha-beta',
+  capability: 'task.plan',
+  correlationId: 'corr-1',
+  messageId: 'bench-1',
+  nonce: 'bench-nonce',
+  nowMs: 1_000,
+  ttlMs: 120_000,
+})
+
+describe('protocol throughput', () => {
+  bench('canonicalize envelope', () => {
+    canonicalizeEnvelope(unsigned)
+  })
+
+  bench('encode/decode envelope json', () => {
+    const encoded = encodeEnvelope({ ...unsigned })
+    decodeEnvelope(encoded)
+  })
+
+  bench('encode/decode envelope compact', () => {
+    const encoded = encodeEnvelope({ ...unsigned }, 'compact')
+    decodeEnvelope(encoded)
+  })
+
+  bench('sign + verify envelope', async () => {
+    const signed = await signEnvelopeHmac(unsigned, 'bench-secret', 'bench-k1')
+    await verifyEnvelopeHmac(signed, 'bench-secret')
+  })
+})

package/src/protocol.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it } from 'vitest'
+import {
+  canonicalizeEnvelope,
+  createEnvelope,
+  generateEd25519KeypairBase64Url,
+  signCanonicalPayloadHmac,
+  signEnvelopeEd25519,
+  signEnvelopeHmac,
+  verifyCanonicalPayloadEd25519,
+  validateEnvelope,
+  verifyCanonicalPayloadHmac,
+  verifyEnvelopeEd25519,
+  verifyEnvelopeHmac,
+} from './protocol'
+
+describe('GLUV AIP protocol', () => {
+  it('uses stable canonical field order', () => {
+    const envelope = createEnvelope({
+      sender: 'agent.alpha',
+      recipient: 'agent.beta',
+      intent: 'TASK',
+      content: 'compute route',
+      capability: 'task.plan',
+      correlationId: 'c-1',
+      messageId: 'm0',
+      nonce: 'n0',
+      nowMs: 500,
+      ttlMs: 10_000,
+    })
+
+    expect(canonicalizeEnvelope(envelope)).toBe(
+      '{"body":{"capability":"task.plan","content":"compute route","correlationId":"c-1","intent":"TASK"},"header":{"messageId":"m0","nonce":"n0","recipient":"agent.beta","sender":"agent.alpha","timestampMs":500,"ttlMs":10000,"version":"7h3/0.1"}}',
+    )
+  })
+
+  it('canonicalizes envelopes deterministically', () => {
+    const envelope = createEnvelope({
+      sender: 'agent.alpha',
+      recipient: 'agent.beta',
+      intent: 'TASK',
+      content: 'compute route',
+      messageId: 'm1',
+      nonce: 'n1',
+      nowMs: 1000,
+      ttlMs: 10000,
+    })
+
+    const c1 = canonicalizeEnvelope(envelope)
+    const c2 = canonicalizeEnvelope({ header: envelope.header, body: envelope.body })
+    expect(c1).toBe(c2)
+  })
+
+  it('signs and verifies with HMAC', async () => {
+    const unsigned = createEnvelope({
+      sender: 'agent.alpha',
+      intent: 'PING',
+      content: 'hello',
+      messageId: 'm2',
+      nonce: 'n2',
+      nowMs: 2000,
+      ttlMs: 10000,
+    })
+
+    const signed = await signEnvelopeHmac(unsigned, 'secret-key', 'dev-1')
+    const ok = await verifyEnvelopeHmac(signed, 'secret-key')
+    expect(ok).toBe(true)
+
+    const tampered = {
+      ...signed,
+      body: {
+        ...signed.body,
+        content: 'tampered',
+      },
+    }
+    const bad = await verifyEnvelopeHmac(tampered, 'secret-key')
+    expect(bad).toBe(false)
+  })
+
+  it('signs and verifies canonical payload directly', async () => {
+    const unsigned = createEnvelope({
+      sender: 'agent.alpha',
+      intent: 'PING',
+      content: 'hello',
+      messageId: 'm2b',
+      nonce: 'n2b',
+      nowMs: 2000,
+      ttlMs: 10000,
+    })
+
+    const payload = canonicalizeEnvelope(unsigned)
+    const sig = await signCanonicalPayloadHmac(payload, 'secret-key')
+    expect(await verifyCanonicalPayloadHmac(payload, sig, 'secret-key')).toBe(true)
+    expect(await verifyCanonicalPayloadHmac(`${payload}x`, sig, 'secret-key')).toBe(false)
+  })
+
+  it('signs and verifies with Ed25519', async () => {
+    const keys = await generateEd25519KeypairBase64Url()
+    const unsigned = createEnvelope({
+      sender: 'agent.alpha',
+      intent: 'TASK',
+      content: 'route:ed25519',
+      messageId: 'm-ed1',
+      nonce: 'n-ed1',
+      nowMs: 3000,
+      ttlMs: 10000,
+    })
+
+    const signed = await signEnvelopeEd25519(unsigned, keys.privateKey, 'ed-1')
+    const ok = await verifyEnvelopeEd25519(signed, keys.publicKey)
+    expect(ok).toBe(true)
+
+    const tampered = {
+      ...signed,
+      body: {
+        ...signed.body,
+        content: 'tampered',
+      },
+    }
+    const bad = await verifyEnvelopeEd25519(tampered, keys.publicKey)
+    expect(bad).toBe(false)
+  })
+
+  it('signs and verifies Ed25519 canonical payload directly', async () => {
+    const keys = await generateEd25519KeypairBase64Url()
+    const unsigned = createEnvelope({
+      sender: 'agent.alpha',
+      intent: 'PING',
+      content: 'hello-ed25519',
+      messageId: 'm-ed2',
+      nonce: 'n-ed2',
+      nowMs: 3100,
+      ttlMs: 10000,
+    })
+
+    const payload = canonicalizeEnvelope(unsigned)
+    const sig = await signEnvelopeEd25519(unsigned, keys.privateKey, 'ed-2')
+    expect(sig.signature?.alg).toBe('ED25519')
+    expect(await verifyCanonicalPayloadEd25519(payload, sig.signature?.value ?? '', keys.publicKey)).toBe(true)
+    expect(await verifyCanonicalPayloadEd25519(`${payload}x`, sig.signature?.value ?? '', keys.publicKey)).toBe(false)
+  })
+
+  it('flags expired messages', () => {
+    const unsigned = createEnvelope({
+      sender: 'agent.alpha',
+      intent: 'RESULT',
+      content: 'done',
+      messageId: 'm3',
+      nonce: 'n3',
+      nowMs: 0,
+      ttlMs: 100,
+    })
+    const diagnostics = validateEnvelope({ ...unsigned }, 500)
+    expect(diagnostics.some((d) => d.message === 'Message TTL expired')).toBe(true)
+  })
+})