@7h3/protocol 0.1.2 → 0.5.0

package/src/queueBinding.ts

@@ -0,0 +1,102 @@
+import {
+  type ProtocolEnvelope,
+  createEnvelope,
+  signEnvelopeEd25519,
+  verifyEnvelopeEd25519,
+} from './protocol'
+
+export interface QueueSignOptions {
+  privateKey: string
+  sender: string
+  recipient?: string
+  ttlMs?: number
+  keyId?: string
+}
+
+export interface QueueVerifyOptions {
+  publicKey: string
+}
+
+export type SignedEnvelope = ProtocolEnvelope
+
+export interface QueueMessage<T> {
+  envelope: SignedEnvelope
+  payload: T
+}
+
+/**
+ * Signs a payload for queue transit (Kafka/SQS/Pub-Sub/RabbitMQ).
+ * Returns a JSON string: {"envelope": SignedEnvelope, "payload": T}
+ * Default TTL is 1 hour (3 600 000 ms).
+ */
+export async function signQueueMessage<T>(
+  payload: T,
+  opts: QueueSignOptions,
+): Promise<string> {
+  const ttlMs = opts.ttlMs ?? 3_600_000
+  const content = typeof payload === 'string' ? payload : JSON.stringify(payload)
+
+  const envelope = createEnvelope({
+    sender: opts.sender,
+    recipient: opts.recipient,
+    intent: 'TASK',
+    content,
+    ttlMs,
+  })
+
+  const signed = await signEnvelopeEd25519(envelope, opts.privateKey, opts.keyId)
+
+  const message: QueueMessage<T> = { envelope: signed, payload }
+  return JSON.stringify(message)
+}
+
+/**
+ * Parses a queue message JSON string and verifies the envelope signature.
+ * Throws if the message is malformed or the signature is invalid.
+ */
+export async function verifyQueueMessage<T>(
+  message: string,
+  opts: QueueVerifyOptions,
+): Promise<{ payload: T; envelope: ProtocolEnvelope }> {
+  let parsed: QueueMessage<T>
+  try {
+    parsed = JSON.parse(message) as QueueMessage<T>
+  } catch {
+    throw new Error('Queue message is not valid JSON')
+  }
+
+  if (!parsed.envelope || typeof parsed.envelope !== 'object') {
+    throw new Error('Queue message missing envelope')
+  }
+
+  const valid = await verifyEnvelopeEd25519(parsed.envelope, opts.publicKey)
+  if (!valid) {
+    throw new Error('Queue message signature verification failed')
+  }
+
+  return { payload: parsed.payload, envelope: parsed.envelope }
+}
+
+/**
+ * Verifies a batch of queue message strings.
+ * Never throws — returns per-message success/failure objects.
+ */
+export async function verifyQueueBatch<T>(
+  messages: string[],
+  opts: QueueVerifyOptions,
+): Promise<Array<{ ok: true; payload: T; envelope: ProtocolEnvelope } | { ok: false; raw: string; error: string }>> {
+  return Promise.all(
+    messages.map(async (raw) => {
+      try {
+        const { payload, envelope } = await verifyQueueMessage<T>(raw, opts)
+        return { ok: true as const, payload, envelope }
+      } catch (err) {
+        return {
+          ok: false as const,
+          raw,
+          error: err instanceof Error ? err.message : String(err),
+        }
+      }
+    }),
+  )
+}

package/src/rateLimiter.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { SlidingWindowRateLimiter } from './rateLimiter'
+
+describe('SlidingWindowRateLimiter', () => {
+  let limiter: SlidingWindowRateLimiter
+
+  beforeEach(() => {
+    limiter = new SlidingWindowRateLimiter()
+  })
+
+  it('check() allows when under limit', () => {
+    const result = limiter.check('alice', { requests: 5, windowMs: 1000 })
+    expect(result.allowed).toBe(true)
+    expect(result.remaining).toBe(4) // 4 left after this one would be consumed
+  })
+
+  it('check() does not record a timestamp', () => {
+    const policy = { requests: 1, windowMs: 1000 }
+    limiter.check('alice', policy)
+    limiter.check('alice', policy)
+    // Still allowed — check doesn't consume
+    const result = limiter.check('alice', policy)
+    expect(result.allowed).toBe(true)
+  })
+
+  it('consume() records and blocks at limit', () => {
+    const policy = { requests: 2, windowMs: 10_000 }
+    const r1 = limiter.consume('alice', policy)
+    expect(r1.allowed).toBe(true)
+    expect(r1.remaining).toBe(1)
+
+    const r2 = limiter.consume('alice', policy)
+    expect(r2.allowed).toBe(true)
+    expect(r2.remaining).toBe(0)
+
+    const r3 = limiter.consume('alice', policy)
+    expect(r3.allowed).toBe(false)
+    expect(r3.remaining).toBe(0)
+  })
+
+  it('consume() sliding window expires old timestamps', () => {
+    const policy = { requests: 2, windowMs: 1000 }
+    const baseMs = 10_000
+
+    // Fill the window at t=0
+    limiter.consume('alice', policy, baseMs)
+    limiter.consume('alice', policy, baseMs)
+
+    // Blocked at t=500 (still inside window)
+    const blocked = limiter.consume('alice', policy, baseMs + 500)
+    expect(blocked.allowed).toBe(false)
+
+    // Allowed at t=1001 (first entry has expired)
+    const allowed = limiter.consume('alice', policy, baseMs + 1001)
+    expect(allowed.allowed).toBe(true)
+  })
+
+  it('reset() clears a specific key', () => {
+    const policy = { requests: 1, windowMs: 10_000 }
+    limiter.consume('alice', policy)
+    const blocked = limiter.consume('alice', policy)
+    expect(blocked.allowed).toBe(false)
+
+    limiter.reset('alice')
+    const allowed = limiter.consume('alice', policy)
+    expect(allowed.allowed).toBe(true)
+  })
+
+  it('clear() clears all keys', () => {
+    const policy = { requests: 1, windowMs: 10_000 }
+    limiter.consume('alice', policy)
+    limiter.consume('bob', policy)
+
+    limiter.clear()
+
+    expect(limiter.consume('alice', policy).allowed).toBe(true)
+    expect(limiter.consume('bob', policy).allowed).toBe(true)
+  })
+
+  it('resetMs is non-zero when window has entries', () => {
+    const policy = { requests: 5, windowMs: 1000 }
+    const baseMs = 50_000
+    limiter.consume('alice', policy, baseMs)
+    const result = limiter.check('alice', policy, baseMs + 100)
+    expect(result.resetMs).toBeGreaterThan(0)
+    expect(result.resetMs).toBeLessThanOrEqual(1000)
+  })
+
+  it('different keys are independent', () => {
+    const policy = { requests: 1, windowMs: 10_000 }
+    limiter.consume('alice', policy)
+    // alice is blocked, but bob is not
+    expect(limiter.consume('alice', policy).allowed).toBe(false)
+    expect(limiter.consume('bob', policy).allowed).toBe(true)
+  })
+})

package/src/rateLimiter.ts

@@ -0,0 +1,46 @@
+export type RateLimitPolicy = { requests: number; windowMs: number }
+export type RateLimitResult = { allowed: boolean; remaining: number; resetMs: number }
+
+class SlidingWindowRateLimiter {
+  private windows: Map<string, number[]> = new Map()
+
+  // Check without recording — pure read
+  check(key: string, policy: RateLimitPolicy, nowMs = Date.now()): RateLimitResult {
+    const cutoff = nowMs - policy.windowMs
+    const timestamps = (this.windows.get(key) ?? []).filter(t => t > cutoff)
+    const used = timestamps.length
+    const allowed = used < policy.requests
+    const remaining = Math.max(0, policy.requests - used - (allowed ? 1 : 0))
+    // resetMs: time until the oldest timestamp falls out of window (0 if window empty)
+    const resetMs = timestamps.length > 0 ? Math.max(0, timestamps[0] + policy.windowMs - nowMs) : 0
+    return { allowed, remaining, resetMs }
+  }
+
+  // Consume — record a timestamp if allowed
+  consume(key: string, policy: RateLimitPolicy, nowMs = Date.now()): RateLimitResult {
+    const cutoff = nowMs - policy.windowMs
+    const timestamps = (this.windows.get(key) ?? []).filter(t => t > cutoff)
+    const used = timestamps.length
+    const allowed = used < policy.requests
+
+    if (allowed) {
+      timestamps.push(nowMs)
+      this.windows.set(key, timestamps)
+    }
+
+    const remaining = Math.max(0, policy.requests - timestamps.length)
+    const resetMs = timestamps.length > 0 ? Math.max(0, timestamps[0] + policy.windowMs - nowMs) : 0
+    return { allowed, remaining, resetMs }
+  }
+
+  reset(key: string): void {
+    this.windows.delete(key)
+  }
+
+  clear(): void {
+    this.windows.clear()
+  }
+}
+
+export const globalRateLimiter = new SlidingWindowRateLimiter()
+export { SlidingWindowRateLimiter }

package/src/redisClient.ts

@@ -0,0 +1,140 @@
+/**
+ * Minimal Redis command surface the AIP stores depend on.
+ *
+ * The library stays client-agnostic: any Redis client (ioredis, node-redis,
+ * Upstash, a cluster proxy, ...) can be adapted to this interface, so
+ * `@7h3/protocol` ships with no Redis dependency of its own.
+ *
+ * # High-Availability topologies
+ *
+ * ## Redis Sentinel
+ * ioredis connects to a Sentinel group transparently — adapt the same client
+ * to `RedisLikeClient` with the same three-line wrapper. The library requires
+ * no topology-specific changes:
+ *
+ * ```ts
+ * import Redis from 'ioredis'
+ * import { adaptIoredis } from './adaptIoredis'  // your adapter module
+ *
+ * const client = new Redis({
+ *   sentinels: [
+ *     { host: 'sentinel-1', port: 26379 },
+ *     { host: 'sentinel-2', port: 26379 },
+ *     { host: 'sentinel-3', port: 26379 },
+ *   ],
+ *   name: 'mymaster',
+ * })
+ * const aipRedis = adaptIoredis(client)  // same adapter as standalone Redis
+ * ```
+ *
+ * ## Redis Cluster
+ * Cluster mode shards keys across nodes using CRC16. AIP replay keys
+ * (`aip:replay:{sender}:{messageId}:{nonce}`) and revocation keys
+ * (`aip:revoked:{keyId}`) are independent — no cross-slot transactions are
+ * required. Adapt a Cluster client the same way as a standalone client.
+ *
+ * ## Upstash / serverless Redis
+ * Upstash's HTTP-based Redis client exposes a `set(key, value, options)`
+ * interface compatible with `RedisLikeClient` without any wrapping.
+ *
+ * ## Operational requirements
+ * - **Clock sync**: AIP TTL checks require clocks within the configured skew
+ *   window (default ±30 s). NTP or PTP is required across all nodes.
+ * - **HA of the replay store itself**: the protocol degrades gracefully on
+ *   Redis outage (`errorBehavior: 'fallback'` or `'allow'`), but a hard
+ *   `'reject'` posture prevents replay-store outage from becoming a
+ *   denial-of-service vector. Choose the posture that matches your threat model.
+ * - See `docs/DISTRIBUTED_REPLAY.md` for full operational guidance.
+ */
+
+export interface RedisSetOptions {
+  /** Only set when the key does not already exist (Redis `NX`). */
+  nx?: boolean
+  /** Expire the key after this many milliseconds (Redis `PX`). */
+  pxMs?: number
+}
+
+/** A queued, chainable batch of `set` commands flushed in a single round-trip. */
+export interface RedisPipelineLike {
+  set(key: string, value: string, options?: RedisSetOptions): RedisPipelineLike
+  exec(): Promise<Array<'OK' | null>>
+}
+
+export interface RedisLikeClient {
+  /** Returns `'OK'` when the value was written, or `null` when `NX` prevented it. */
+  set(key: string, value: string, options?: RedisSetOptions): Promise<'OK' | null>
+  /** Truthy when the key exists and has not expired. */
+  get?(key: string): Promise<string | null>
+  /** Removes a key; returns the number of keys removed. */
+  del?(key: string): Promise<number>
+  /** Optional batch pipeline; when present, batch reserves use a single round-trip. */
+  pipeline?(): RedisPipelineLike
+}
+
+interface Entry {
+  value: string
+  expiresAt?: number
+}
+
+/**
+ * In-memory reference implementation of {@link RedisLikeClient}.
+ *
+ * It is a faithful stand-in for a single Redis node's `SET NX PX` / `GET` /
+ * `DEL` semantics — useful for tests, local development, and as the default
+ * degraded-mode fallback. It is NOT a distributed store: it provides no
+ * cross-process guarantees and must not be used as a production replay store
+ * for a horizontally scaled deployment.
+ */
+export class InMemoryRedisLikeClient implements RedisLikeClient {
+  private readonly entries = new Map<string, Entry>()
+  private readonly now: () => number
+
+  constructor(options: { now?: () => number } = {}) {
+    this.now = options.now ?? (() => Date.now())
+  }
+
+  private live(key: string): Entry | undefined {
+    const entry = this.entries.get(key)
+    if (!entry) return undefined
+    if (entry.expiresAt !== undefined && entry.expiresAt <= this.now()) {
+      this.entries.delete(key)
+      return undefined
+    }
+    return entry
+  }
+
+  async set(key: string, value: string, options: RedisSetOptions = {}): Promise<'OK' | null> {
+    if (options.nx && this.live(key)) return null
+    const expiresAt = options.pxMs !== undefined ? this.now() + options.pxMs : undefined
+    this.entries.set(key, { value, expiresAt })
+    return 'OK'
+  }
+
+  async get(key: string): Promise<string | null> {
+    return this.live(key)?.value ?? null
+  }
+
+  async del(key: string): Promise<number> {
+    const existed = this.live(key) !== undefined
+    this.entries.delete(key)
+    return existed ? 1 : 0
+  }
+
+  pipeline(): RedisPipelineLike {
+    const commands: Array<{ key: string; value: string; options?: RedisSetOptions }> = []
+    const pipeline: RedisPipelineLike = {
+      set: (key: string, value: string, options?: RedisSetOptions) => {
+        commands.push({ key, value, options })
+        return pipeline
+      },
+      exec: async () => {
+        const results: Array<'OK' | null> = []
+        for (const command of commands) {
+          results.push(await this.set(command.key, command.value, command.options))
+        }
+        return results
+      },
+    }
+    return pipeline
+  }
+}

package/src/redisIntegration.test.ts

@@ -0,0 +1,134 @@
+import net from 'node:net'
+import { afterAll, describe, expect, it } from 'vitest'
+import type { RedisLikeClient, RedisSetOptions } from './redisClient'
+import { createRedisReplayStore } from './replayStores'
+import { createRedisRevocationStore } from './revocation'
+
+/**
+ * Minimal RESP client over a raw socket — just enough of the Redis wire
+ * protocol to drive SET/GET/DEL. Dependency-free so the integration test can
+ * run against a real redis-server without adding an npm Redis client.
+ */
+class NetRedisClient implements RedisLikeClient {
+  private socket!: net.Socket
+  private buffer = Buffer.alloc(0)
+  private readonly waiters: Array<(reply: string | number | null | Error) => void> = []
+
+  connect(host = '127.0.0.1', port = 6379): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.socket = net.createConnection({ host, port }, resolve)
+      this.socket.on('error', reject)
+      this.socket.on('data', (chunk) => {
+        this.buffer = Buffer.concat([this.buffer, chunk])
+        this.drain()
+      })
+    })
+  }
+
+  close(): void {
+    this.socket?.end()
+  }
+
+  private drain(): void {
+    while (this.waiters.length > 0) {
+      const parsed = this.parseReply(this.buffer)
+      if (!parsed) return
+      this.buffer = this.buffer.subarray(parsed.consumed)
+      this.waiters.shift()!(parsed.value)
+    }
+  }
+
+  private parseReply(buf: Buffer): { value: string | number | null | Error; consumed: number } | null {
+    const end = buf.indexOf('\r\n')
+    if (end < 0) return null
+    const type = String.fromCharCode(buf[0]!)
+    const line = buf.toString('utf8', 1, end)
+    const headerConsumed = end + 2
+    if (type === '+') return { value: line, consumed: headerConsumed }
+    if (type === '-') return { value: new Error(line), consumed: headerConsumed }
+    if (type === ':') return { value: Number(line), consumed: headerConsumed }
+    if (type === '$') {
+      const len = Number(line)
+      if (len === -1) return { value: null, consumed: headerConsumed }
+      const dataEnd = headerConsumed + len
+      if (buf.length < dataEnd + 2) return null
+      return { value: buf.toString('utf8', headerConsumed, dataEnd), consumed: dataEnd + 2 }
+    }
+    return { value: new Error(`unsupported RESP type: ${type}`), consumed: headerConsumed }
+  }
+
+  private command(args: string[]): Promise<string | number | null> {
+    const payload = `*${args.length}\r\n${args.map((a) => `$${Buffer.byteLength(a)}\r\n${a}\r\n`).join('')}`
+    return new Promise((resolve, reject) => {
+      this.waiters.push((reply) => (reply instanceof Error ? reject(reply) : resolve(reply)))
+      this.socket.write(payload)
+    })
+  }
+
+  async set(key: string, value: string, options: RedisSetOptions = {}): Promise<'OK' | null> {
+    const args = ['SET', key, value]
+    if (options.pxMs !== undefined) args.push('PX', String(options.pxMs))
+    if (options.nx) args.push('NX')
+    const reply = await this.command(args)
+    return reply === 'OK' ? 'OK' : null
+  }
+
+  async get(key: string): Promise<string | null> {
+    const reply = await this.command(['GET', key])
+    return reply === null ? null : String(reply)
+  }
+
+  async del(key: string): Promise<number> {
+    const reply = await this.command(['DEL', key])
+    return Number(reply)
+  }
+}
+
+async function redisAvailable(): Promise<NetRedisClient | null> {
+  const client = new NetRedisClient()
+  try {
+    await client.connect()
+    return client
+  } catch {
+    return null
+  }
+}
+
+const client = await redisAvailable()
+const runOrSkip = client ? describe : describe.skip
+if (!client) {
+  console.warn('[redisIntegration] redis-server unreachable on 127.0.0.1:6379 — skipping live integration tests')
+}
+
+// Unique namespace per run so concurrent/previous runs never collide.
+const ns = `aip:test:${Date.now()}:${Math.floor(Math.random() * 1e6)}:`
+
+runOrSkip('Redis integration (live server)', () => {
+  const touched: string[] = []
+
+  afterAll(async () => {
+    if (!client) return
+    for (const key of touched) await client.del(key)
+    client.close()
+  })
+
+  it('replay store reserves a key once against real Redis', async () => {
+    const prefix = `${ns}replay:`
+    const store = createRedisReplayStore(client!, { keyPrefix: prefix })
+    const now = Date.now()
+    touched.push(`${prefix}s|m1|n1`)
+    expect(await store.reserve('s|m1|n1', now + 5000, now)).toBe(true)
+    expect(await store.reserve('s|m1|n1', now + 5000, now)).toBe(false)
+    expect(await store.reserve('s|m2|n2', now + 5000, now)).toBe(true)
+    touched.push(`${prefix}s|m2|n2`)
+  })
+
+  it('revocation store reflects a revoke against real Redis', async () => {
+    const prefix = `${ns}revoked:`
+    const store = createRedisRevocationStore(client!, { keyPrefix: prefix, cacheTtlMs: 0 })
+    touched.push(`${prefix}agent.a agent-k1`)
+    expect(await store.isRevoked('agent.a', 'agent-k1')).toBe(false)
+    await store.revoke('agent.a', 'agent-k1')
+    expect(await store.isRevoked('agent.a', 'agent-k1')).toBe(true)
+  })
+})