@fetchproxy/protocol

Wire-protocol types, runtime validators, and crypto wrappers for the fetchproxy WebSocket protocol.

Internal-ish: most users want @fetchproxy/server instead. @fetchproxy/server re-exports the few protocol types MCP authors typically need (Capability, FetchInit); pull this package in directly only if you're building your own bridge endpoint (alternate server, test harness, custom extension).

See:

• Top-level README — what fetchproxy is.
• docs/PROTOCOL.md — full wire-format reference (frames, handshake, crypto).

Install

npm install @fetchproxy/protocol

What's in here

| Module | Exports | Purpose | |---|---|---| | frames | PROTOCOL_VERSION, Capability, KNOWN_CAPABILITIES, all …Frame types, FetchInit, ReadCookiesInit, InnerFrame union, StoragePointerDecl, IndexedDbScopeDecl, CaptureHeaderDecl | Static + runtime descriptions of every frame on the wire. | | validate | validateFrame, validateInnerFrame, ProtocolError, HOSTNAME_RE | Defensive JSON validators with no third-party dependencies. Reject prototype-pollution attempts, malformed base64, unknown ops/capabilities, bad hostnames. | | crypto | RawKeyPair, generateX25519, generateEd25519, ecdhX25519, hkdfSha256, ed25519Sign, ed25519Verify, aesGcmSeal, aesGcmOpen, sha256 | Thin async wrappers around WebCrypto subtle. Used by both server and extension. | | mcp-id | generateMcpId, parseMcpId, isValidMcpId, McpIdParts | Per-process <serverName>:<version>:<rand> ids. | | pair-code | pairTranscript | Deterministic 8-digit SAS code over the pair transcript — both identity pubs, both hello nonces and the MCP's session ephemeral (SHA256('fetchproxy/4/pair' \| NUL \| …)[0..7] as a big-endian BigInt mod 100_000_000, formatted XXXX-XXXX). 3.0.0+; the v3 pair of functions over the two long-term identity pubs alone is gone, so a code cannot be ground offline once and reused against that MCP forever. | | seal | sealInnerFrame, openEncryptedFrame | AES-256-GCM encrypt/decrypt of inner JSON payloads keyed by sessionKey. | | encoding | toB64, fromB64, toHex, concatBytes | Shared base64/hex helpers. | | json-pointer | evalJsonPointer, isValidJsonPointer, matchesDeclaredKey, undeclaredKeys | JSON-pointer evaluation + glob matching for storage-pointer extraction. |

Stability

All exports are part of the published surface and follow semver:

• Major bumps signal wire-incompatible changes (new required fields, removed fields, semantic shifts).
• Minor bumps add fields or accepted values additively.
• Patch bumps are pure fixes.

0.2.0 was a wire-incompatible jump from 0.1.x (singular domain: string → domains: string[]; added capabilities; added op discriminator on inner request/response).

License

MIT.