@7h3/protocol 0.5.4 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7h3/protocol",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "7h3 Protocol: deterministic, signed, replay-safe AI-to-AI message envelopes (wire 7h3/0.1).",
   "type": "module",
   "main": "./index.js",

package/protocol.d.ts

@@ -57,6 +57,16 @@ export declare function verifyEnvelopeEd25519(envelope: ProtocolEnvelope, public
 export declare function verifyEnvelopeSignature(envelope: ProtocolEnvelope, material: SignatureVerificationMaterial): Promise<boolean>;
 export declare function verifyCanonicalPayloadSignature(payload: string, signature: ProtocolSignature | undefined, material: SignatureVerificationMaterial): Promise<boolean>;
 export declare const MAX_TTL_MS = 86400000;
+/**
+ * How far into the future a timestamp may sit before it is rejected.
+ *
+ * Matches the transport binding's default so every entry point agrees. Without
+ * this ceiling, MAX_TTL_MS bounds nothing: a sender can post-date `timestampMs`
+ * by a year and still pass a 24h `ttlMs`, producing an envelope that validates
+ * for a year and stays replayable long after any replay store has forgotten its
+ * nonce.
+ */
+export declare const MAX_CLOCK_SKEW_MS = 30000;
 export declare function validateEnvelope(envelope: ProtocolEnvelope, nowMs?: number): ProtocolDiagnostic[];
 export declare function createEnvelope(input: {
     sender: string;

package/rateLimiter.d.ts

@@ -20,6 +20,10 @@ export interface RateLimitStore {
 }
 declare class SlidingWindowRateLimiter {
     private windows;
+    private readonly maxKeys;
+    constructor(opts?: {
+        maxKeys?: number;
+    });
     check(key: string, policy: RateLimitPolicy, nowMs?: number): RateLimitResult;
     consume(key: string, policy: RateLimitPolicy, nowMs?: number): RateLimitResult;
     reset(key: string): void;

package/webhookBinding.d.ts

@@ -2,6 +2,26 @@ import { generateEd25519KeypairBase64Url } from './protocol';
 export declare const WEBHOOK_SIG_HEADER = "x-7h3-sig";
 export declare const WEBHOOK_TS_HEADER = "x-7h3-ts";
 export declare const WEBHOOK_DEFAULT_TTL_MS = 300000;
+/**
+ * A verified webhook signature is otherwise valid to replay any number of
+ * times until it ages out of maxAgeMs — the signature+timestamp cover
+ * authenticity and freshness, but nothing dedupes delivery. A replayCache
+ * closes that gap. The Ed25519/HMAC signature is deterministic per
+ * (timestampMs, body, key), so it doubles as a stable dedup key — no wire
+ * format change needed.
+ */
+export interface WebhookReplayCache {
+    /** Returns true if this key was successfully reserved (first use), false if already seen. */
+    consume(key: string, expiresAtMs: number, nowMs: number): boolean | Promise<boolean>;
+}
+/** Bounded in-memory WebhookReplayCache — single process only, does not survive a restart. */
+export declare class InMemoryWebhookReplayCache implements WebhookReplayCache {
+    private readonly seen;
+    private readonly maxEntries;
+    constructor(maxEntries?: number);
+    private prune;
+    consume(key: string, expiresAtMs: number, nowMs: number): boolean;
+}
 export interface WebhookSignOptions {
     privateKey: string;
     ttlMs?: number;
@@ -13,10 +33,14 @@ export interface WebhookSignHmacOptions {
 export interface WebhookVerifyOptions {
     publicKey: string;
     maxAgeMs?: number;
+    /** Optional — rejects a signature that's already been consumed within its TTL window. */
+    replayCache?: WebhookReplayCache;
 }
 export interface WebhookVerifyHmacOptions {
     secret: string;
     maxAgeMs?: number;
+    /** Optional — rejects a signature that's already been consumed within its TTL window. */
+    replayCache?: WebhookReplayCache;
 }
 export interface WebhookHeaders {
     [WEBHOOK_SIG_HEADER]: string;

package/wsBinding.d.ts

@@ -1,5 +1,6 @@
 import { generateEd25519KeypairBase64Url, type ProtocolEnvelope } from './protocol';
 import type { KeyRegistry } from './keyRegistry';
+import type { ReplayCache } from './protocolReplay';
 import { SignedStreamWriter, type StreamSignerOpts, type StreamVerifierOpts, type StreamVerifyResult, type StreamChunk } from './stream';
 export { type KeyRegistry, generateEd25519KeypairBase64Url };
 export type { StreamSignerOpts, StreamVerifierOpts, StreamVerifyResult, StreamChunk };
@@ -21,6 +22,13 @@ export interface WsBindingOptions {
     keyRegistry: KeyRegistry;
     ttlMs?: number;
     onVerifyFail?: (err: Error, rawData: string) => void;
+    /**
+     * Optional — signature+TTL alone don't stop a captured frame from being
+     * replayed verbatim any number of times within its TTL window. Pass an
+     * InMemoryReplayCache (or a distributed one) to dedupe incoming frames by
+     * sender/messageId/nonce, same as the HTTP gateway does.
+     */
+    replayCache?: ReplayCache;
 }
 export interface ProtectedWebSocket {
     send(payload: unknown): Promise<void>;