@crosslink/protocol 0.1.0

package/LICENSE

@@ -0,0 +1,163 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by the
+   copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all other
+   entities that control, are controlled by, or are under common control
+   with that entity. For the purposes of this definition, "control" means
+   (i) the power, direct or indirect, to cause the direction or management
+   of such entity, whether by contract or otherwise, or (ii) ownership of
+   fifty percent (50%) or more of the outstanding shares, or (iii) beneficial
+   ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity exercising
+   permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation source,
+   and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical transformation
+   or translation of a Source form, including but not limited to compiled
+   object code, generated documentation, and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or Object
+   form, made available under the License, as indicated by a copyright notice
+   that is included in or attached to the work.
+
+   "Derivative Works" shall mean any work, whether in Source or Object form,
+   that is based on (or derived from) the Work and for which the editorial
+   revisions, annotations, elaborations, or other modifications represent, as
+   a whole, an original work of authorship. For the purposes of this License,
+   Derivative Works shall not include works that remain separable from, or
+   merely link (or bind by name) to the interfaces of, the Work and Derivative
+   Works thereof.
+
+   "Contribution" shall mean any work of authorship, including the original
+   version of the Work and any modifications or additions to that Work or
+   Derivative Works thereof, that is intentionally submitted to the Licensor
+   for inclusion in the Work by the copyright owner or by an individual or
+   Legal Entity authorized to submit on behalf of the copyright owner. For the
+   purposes of this definition, "submitted" means any form of electronic,
+   verbal, or written communication sent to the Licensor or its representatives,
+   including but not limited to communication on electronic mailing lists,
+   source code control systems, and issue tracking systems that are managed by,
+   or on behalf of, the Licensor for the purpose of discussing and improving
+   the Work, but excluding communication that is conspicuously marked or
+   otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity on
+   behalf of whom a Contribution has been received by the Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+   License, each Contributor hereby grants to You a perpetual, worldwide,
+   non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+   reproduce, prepare Derivative Works of, publicly display, publicly perform,
+   sublicense, and distribute the Work and such Derivative Works in Source or
+   Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+   License, each Contributor hereby grants to You a perpetual, worldwide,
+   non-exclusive, no-charge, royalty-free, irrevocable (except as stated in
+   this section) patent license to make, have made, use, offer to sell, sell,
+   import, and otherwise transfer the Work, where such license applies only to
+   those patent claims licensable by such Contributor that are necessarily
+   infringed by their Contribution(s) alone or by combination of their
+   Contribution(s) with the Work to which such Contribution(s) was submitted.
+   If You institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+   Contribution incorporated within the Work constitutes direct or contributory
+   patent infringement, then any patent licenses granted to You under this
+   License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+   Derivative Works thereof in any medium, with or without modifications, and
+   in Source or Object form, provided that You meet the following conditions:
+
+   (a) You must give any other recipients of the Work or Derivative Works
+       a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices stating
+       that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works that You
+       distribute, all copyright, patent, trademark, and attribution notices
+       from the Source form of the Work, excluding those notices that do not
+       pertain to any part of the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its distribution,
+       then any Derivative Works that You distribute must include a readable
+       copy of the attribution notices contained within such NOTICE file,
+       excluding any notices that do not pertain to any part of the Derivative
+       Works, in at least one of the following places: within a NOTICE text
+       file distributed as part of the Derivative Works; within the Source
+       form or documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and wherever
+       such third-party notices normally appear. The contents of the NOTICE
+       file are for informational purposes only and do not modify the License.
+       You may add Your own attribution notices within Derivative Works that
+       You distribute, alongside or as an addendum to the NOTICE text from
+       the Work, provided that such additional attribution notices cannot be
+       construed as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and may
+   provide additional or different license terms and conditions for use,
+   reproduction, or distribution of Your modifications, or for any such
+   Derivative Works as a whole, provided Your use, reproduction, and
+   distribution of the Work otherwise complies with the conditions stated
+   in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+   Contribution intentionally submitted for inclusion in the Work by You to
+   the Licensor shall be under the terms and conditions of this License,
+   without any additional terms or conditions. Notwithstanding the above,
+   nothing herein shall supersede or modify the terms of any separate license
+   agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+   trademarks, service marks, or product names of the Licensor, except as
+   required for reasonable and customary use in describing the origin of the
+   Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+   writing, Licensor provides the Work (and each Contributor provides its
+   Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied, including, without limitation, any warranties
+   or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any risks
+   associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+   tort (including negligence), contract, or otherwise, unless required by
+   applicable law (such as deliberate and grossly negligent acts) or agreed to
+   in writing, shall any Contributor be liable to You for damages, including
+   any direct, indirect, special, incidental, or consequential damages of any
+   character arising as a result of this License or out of the use or inability
+   to use the Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all other
+   commercial damages or losses), even if such Contributor has been advised of
+   the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work
+   or Derivative Works thereof, You may choose to offer, and charge a fee for,
+   acceptance of support, warranty, indemnity, or other liability obligations
+   and/or rights consistent with this License. However, in accepting such
+   obligations, You may act only on Your own behalf and on Your sole
+   responsibility, not on behalf of any other Contributor, and only if You
+   agree to indemnify, defend, and hold each Contributor harmless for any
+   liability incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,11 @@
+# @crosslink/protocol
+
+<p align="center"><img src="https://crosslink.mintlify.site/crosslink.svg" alt="Crosslink" width="320" /></p>
+
+Language-neutral Crosslink wire types, framing, versioning, errors, and conformance fixtures.
+
+```bash
+npm install @crosslink/protocol
+```
+
+See the [Crosslink documentation](https://crosslink.mintlify.site) and [repository](https://github.com/jacobpowaza/crosslink).

package/dist/index.d.ts

@@ -0,0 +1,396 @@
+/**
+ * Crosslink protocol versioning.
+ *
+ * Versions are MAJOR.MINOR strings. Implementations MUST negotiate the highest
+ * mutually supported version during hello and MUST refuse to operate below
+ * MIN_SECURE_VERSION (no silent downgrade).
+ */
+declare const PROTOCOL_VERSION = "1.0";
+declare const MIN_SECURE_VERSION = "1.0";
+declare const SUPPORTED_VERSIONS: readonly string[];
+declare function parseVersion(v: unknown): {
+    major: number;
+    minor: number;
+} | null;
+declare function compareVersions(a: string, b: string): number;
+/** Highest version supported by both lists, or null when incompatible. */
+declare function negotiateVersions(offered: readonly string[], supported: readonly string[]): string | null;
+declare function versionAtLeast(v: string, floor: string): boolean;
+
+/**
+ * Protocol-level error codes. These travel on the wire and must remain stable;
+ * new codes may be appended, existing ones never repurposed.
+ */
+declare const ErrorCodes: {
+    readonly PARSE_ERROR: "parse_error";
+    readonly INVALID_MESSAGE: "invalid_message";
+    readonly VERSION_UNSUPPORTED: "version_unsupported";
+    readonly UNAUTHORIZED: "unauthorized";
+    readonly CAPABILITY_DENIED: "capability_denied";
+    readonly METHOD_NOT_FOUND: "method_not_found";
+    readonly VALIDATION_FAILED: "validation_failed";
+    readonly PAYLOAD_TOO_LARGE: "payload_too_large";
+    readonly RATE_LIMITED: "rate_limited";
+    readonly DEVICE_REVOKED: "device_revoked";
+    readonly SESSION_EXPIRED: "session_expired";
+    readonly PAIRING_EXPIRED: "pairing_expired";
+    readonly PAIRING_INVALID: "pairing_invalid";
+    readonly HOST_OFFLINE: "host_offline";
+    readonly TIMEOUT: "timeout";
+    readonly CANCELLED: "cancelled";
+    readonly INTERNAL: "internal";
+    readonly NOT_CONNECTED: "not_connected";
+    readonly PEER_LOST: "peer_lost";
+    /** the capability is granted but the grant has lapsed and must be renewed */
+    readonly GRANT_EXPIRED: "grant_expired";
+    /** the host user declined a per-use confirmation prompt */
+    readonly CONSENT_DENIED: "consent_denied";
+    /** the host could not obtain a per-use confirmation in time */
+    readonly CONSENT_TIMEOUT: "consent_timeout";
+    /** host permission policy forbids this, independent of what was granted */
+    readonly POLICY_DENIED: "policy_denied";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+declare const ALL_ERROR_CODES: readonly string[];
+interface WireError {
+    code: string;
+    message: string;
+    data?: unknown;
+}
+declare class CrosslinkError extends Error {
+    readonly code: ErrorCode | string;
+    readonly data?: unknown;
+    constructor(code: ErrorCode | string, message: string, data?: unknown);
+    toWire(): WireError;
+    static from(err: unknown): CrosslinkError;
+    /** True for codes that must never leak internal detail across the wire. */
+    static isInternal(code: string): boolean;
+}
+
+/**
+ * Canonical JSON: deterministic serialization used wherever bytes must be
+ * stable across implementations — transcript hashing, signatures, fixtures.
+ *
+ * Rules:
+ *  - object keys sorted lexicographically (by UTF-16 code unit)
+ *  - no insignificant whitespace
+ *  - undefined-valued object keys omitted
+ *  - non-finite numbers and BigInt rejected (not representable interoperably)
+ */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+declare function canonicalJson(value: unknown): string;
+
+/**
+ * Base64 / base64url / hex byte helpers, isomorphic across Node and browsers.
+ * Binary payloads inside JSON messages use the BinaryRef shape.
+ */
+interface BinaryRef {
+    /** discriminator marking this object as a binary payload */
+    $b: true;
+    /** optional MIME type */
+    c?: string;
+    /** standard base64 payload */
+    d: string;
+}
+declare function bytesToBase64(bytes: Uint8Array): string;
+declare function base64ToBytes(b64: string): Uint8Array;
+declare function bytesToBase64Url(bytes: Uint8Array): string;
+declare function base64UrlToBytes(s: string): Uint8Array;
+declare function bytesToHex(bytes: Uint8Array): string;
+declare function hexToBytes(hex: string): Uint8Array;
+declare const utf8ToBytes: (s: string) => Uint8Array;
+declare const bytesToUtf8: (b: Uint8Array) => string;
+declare function encodeBinary(bytes: Uint8Array, mime?: string): BinaryRef;
+declare function decodeBinary(ref: unknown): Uint8Array;
+declare function isBinaryRef(value: unknown): value is BinaryRef;
+
+declare const PROTOCOL = "crosslink";
+/** All message types. */
+declare const MessageTypes: {
+    readonly HELLO: "hello";
+    readonly HELLO_OK: "hello_ok";
+    readonly REQ: "req";
+    readonly RES: "res";
+    readonly ERR: "err";
+    readonly CHUNK: "chunk";
+    readonly END: "end";
+    readonly EVT: "evt";
+    readonly SUB: "sub";
+    readonly UNSUB: "unsub";
+    readonly CANCEL: "cancel";
+    readonly PING: "ping";
+    readonly PONG: "pong";
+    readonly BYE: "bye";
+};
+type MessageType = (typeof MessageTypes)[keyof typeof MessageTypes];
+interface HelloMsg {
+    v: string;
+    t: "hello";
+    /** versions the sender supports, highest last */
+    versions: string[];
+    deviceId: string;
+    appId: string;
+    features?: string[];
+}
+interface HelloOkMsg {
+    v: string;
+    t: "hello_ok";
+    version: string;
+    features?: string[];
+}
+interface RequestMsg {
+    v: string;
+    t: "req";
+    i: string;
+    m: string;
+    p?: Json;
+    /** true when safe to auto-retry/queue across reconnects */
+    idem?: true;
+    ts?: number;
+}
+interface ResponseMsg {
+    v: string;
+    t: "res";
+    i: string;
+    p?: Json;
+}
+interface ErrorMessage {
+    v: string;
+    t: "err";
+    i: string;
+    e: {
+        code: string;
+        message: string;
+        data?: unknown;
+    };
+}
+interface ChunkMsg {
+    v: string;
+    t: "chunk";
+    i: string;
+    n: number;
+    d: Json;
+}
+interface EndMsg {
+    v: string;
+    t: "end";
+    i: string;
+    p?: Json;
+}
+interface EventMsg {
+    v: string;
+    t: "evt";
+    s: string;
+    e: string;
+    p?: Json;
+}
+interface SubMsg {
+    v: string;
+    t: "sub";
+    s: string;
+    e: string;
+}
+interface UnsubMsg {
+    v: string;
+    t: "unsub";
+    s: string;
+}
+interface CancelMsg {
+    v: string;
+    t: "cancel";
+    i: string;
+}
+interface PingMsg {
+    v: string;
+    t: "ping";
+    ts: number;
+}
+interface PongMsg {
+    v: string;
+    t: "pong";
+    ts: number;
+}
+interface ByeMsg {
+    v: string;
+    t: "bye";
+    code?: string;
+    reason?: string;
+}
+type CrosslinkMessage = HelloMsg | HelloOkMsg | RequestMsg | ResponseMsg | ErrorMessage | ChunkMsg | EndMsg | EventMsg | SubMsg | UnsubMsg | CancelMsg | PingMsg | PongMsg | ByeMsg;
+declare function makeRequestId(rand: (n: number) => Uint8Array): string;
+/**
+ * Structural validation of a decoded message. Returns null when valid,
+ * otherwise a machine-readable problem description.
+ *
+ * Deliberately cheap and allocation-light — it runs on every inbound frame.
+ * Deep payload validation belongs to schema validators at the RPC layer.
+ */
+declare function validateMessage(msg: unknown): string | null;
+declare function isMessageType(value: unknown): value is MessageType;
+/** Error codes that indicate the session itself is broken (no point retrying). */
+declare function isFatalErrorCode(code: string): boolean;
+
+declare function encodeMessage(msg: object): Uint8Array;
+declare function decodeMessage(data: Uint8Array | string): unknown;
+declare function encodeFrame(msg: object, maxFrameBytes?: number): Uint8Array;
+declare class FrameDecoder {
+    private readonly maxFrameBytes;
+    private buf;
+    constructor(maxFrameBytes?: number);
+    /** Feed raw bytes; returns every complete message that became available. */
+    push(chunk: Uint8Array): Json[];
+}
+
+/**
+ * Wire limits. Every implementation MUST enforce these by default;
+ * operators may tighten but not loosen beyond documented maxima.
+ */
+declare const Limits: {
+    readonly DEFAULT_MAX_FRAME_BYTES: number;
+    readonly MAX_FRAME_BYTES_HARD: number;
+    readonly DEFAULT_CHUNK_BYTES: number;
+    readonly DEFAULT_REQUEST_TIMEOUT_MS: 30000;
+    readonly DEFAULT_MAX_INFLIGHT: 32;
+    readonly DEFAULT_RATE_PER_SEC: 50;
+    readonly PAIRING_CODE_TTL_MS: 120000;
+    readonly HEARTBEAT_INTERVAL_MS: 15000;
+    readonly HEARTBEAT_TIMEOUT_MS: 45000;
+    readonly CLOCK_SKEW_MS: 120000;
+};
+
+/**
+ * Outer wire shapes: the plaintext control vocabulary exchanged *before* an
+ * encrypted session exists (handshake, pairing) plus the encrypted-frame
+ * envelope itself, and the signaling/relay service protocols.
+ *
+ * All base64 fields are standard base64 unless suffixed `b64u` (base64url).
+ * See docs/reference/protocol.mdx for byte-level details.
+ */
+type OuterFrame = SessionInitFrame | SessionAcceptFrame | SessionRejectFrame | EncryptedFrame | OuterPingFrame | OuterPongFrame | ByeFrame;
+interface SessionInitFrame {
+    kind: "sinit";
+    v: string;
+    /** target application id — binds handshake to one app */
+    app: string;
+    /** client device id */
+    dev: string;
+    /** client static X25519 public key (base64) */
+    sx: string;
+    /** client ephemeral X25519 public key (base64) */
+    epk: string;
+    /** client nonce (base64, 32 bytes) */
+    nc: string;
+    ts: number;
+    sig: string;
+    /** Optional ephemeral ML-KEM encapsulation key, transcript-bound by sig. */
+    pq?: {
+        suite: "ML-KEM-768";
+        ek: string;
+    };
+}
+interface SessionAcceptFrame {
+    kind: "sack";
+    v: string;
+    epk: string;
+    nh: string;
+    sig: string;
+    /** Ciphertext for the client's ephemeral ML-KEM key. */
+    pq?: {
+        suite: "ML-KEM-768";
+        ct: string;
+    };
+}
+interface SessionRejectFrame {
+    kind: "srej";
+    code: string;
+    message: string;
+}
+interface EncryptedFrame {
+    kind: "enc";
+    /** monotonic per-direction counter starting at 1; strictly increasing */
+    n: number;
+    /** random 24-byte XChaCha nonce (base64) */
+    iv: string;
+    /** ciphertext+tag (base64) */
+    ct: string;
+}
+interface OuterPingFrame {
+    kind: "oping";
+    ts: number;
+}
+interface OuterPongFrame {
+    kind: "opong";
+    ts: number;
+}
+interface ByeFrame {
+    kind: "bye";
+    code?: string;
+    reason?: string;
+}
+declare function isOuterKind(value: unknown): value is OuterFrame["kind"];
+declare const OUTER_KINDS: typeof isOuterKind;
+interface PairClaimFrame {
+    ps: string;
+    dev: string;
+    name: string;
+    pub_ed: string;
+    pub_x: string;
+    nonce: string;
+    caps_req?: string[];
+    sig: string;
+}
+interface PairChallengeFrame {
+    ps: string;
+    claim_nonce: string;
+    host_pub_ed: string;
+    host_pub_x: string;
+    nonce: string;
+    granted_caps: string[];
+    link?: true;
+    sig: string;
+}
+interface PairCompleteFrame {
+    ps: string;
+    claim_nonce: string;
+    challenge_nonce: string;
+    sig: string;
+}
+interface PairDoneFrame {
+    ps: string;
+    relay?: {
+        url: string;
+        channel: string;
+    };
+    lan?: {
+        host: string;
+        port: number;
+    };
+}
+interface PairErrorFrame {
+    error: {
+        code: string;
+        message: string;
+    };
+}
+
+/** Stable fixture corpus for cross-language conformance testing.
+ *
+ * The committed JSON file is generated by scripts/generate-fixtures.mjs and
+ * MUST NOT be edited by hand. Independent implementations assert their
+ * encoder/decoder against it.
+ */
+declare const FIXTURES_VERSION = 1;
+interface FixtureCase {
+    name: string;
+    obj: unknown;
+    canonical: string;
+    frame_hex: string;
+}
+declare function sampleMessages(): Array<{
+    name: string;
+    obj: Record<string, unknown>;
+}>;
+
+export { ALL_ERROR_CODES, type BinaryRef, type ByeFrame, type ByeMsg, type CancelMsg, type ChunkMsg, CrosslinkError, type CrosslinkMessage, type EncryptedFrame, type EndMsg, type ErrorCode, ErrorCodes, type ErrorMessage, type EventMsg, FIXTURES_VERSION, type FixtureCase, FrameDecoder, type HelloMsg, type HelloOkMsg, type Json, Limits, MIN_SECURE_VERSION, type MessageType, MessageTypes, OUTER_KINDS, type OuterFrame, type OuterPingFrame, type OuterPongFrame, PROTOCOL, PROTOCOL_VERSION, type PairChallengeFrame, type PairClaimFrame, type PairCompleteFrame, type PairDoneFrame, type PairErrorFrame, type PingMsg, type PongMsg, type RequestMsg, type ResponseMsg, SUPPORTED_VERSIONS, type SessionAcceptFrame, type SessionInitFrame, type SessionRejectFrame, type SubMsg, type UnsubMsg, type WireError, base64ToBytes, base64UrlToBytes, bytesToBase64, bytesToBase64Url, bytesToHex, bytesToUtf8, canonicalJson, compareVersions, decodeBinary, decodeMessage, encodeBinary, encodeFrame, encodeMessage, hexToBytes, isBinaryRef, isFatalErrorCode, isMessageType, isOuterKind, makeRequestId, negotiateVersions, parseVersion, sampleMessages, utf8ToBytes, validateMessage, versionAtLeast };

package/dist/index.js

@@ -0,0 +1,477 @@
+// src/version.ts
+var PROTOCOL_VERSION = "1.0";
+var MIN_SECURE_VERSION = "1.0";
+var SUPPORTED_VERSIONS = [PROTOCOL_VERSION];
+var VERSION_RE = /^(\d+)\.(\d+)$/;
+function parseVersion(v) {
+  if (typeof v !== "string") return null;
+  const m = VERSION_RE.exec(v);
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]) };
+}
+function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa || !pb) throw new TypeError(`invalid version: ${JSON.stringify([a, b])}`);
+  return pa.major !== pb.major ? pa.major - pb.major : pa.minor - pb.minor;
+}
+function negotiateVersions(offered, supported) {
+  const mutual = [...offered].filter((v) => supported.includes(v)).sort(compareVersions);
+  return mutual.length ? mutual[mutual.length - 1] : null;
+}
+function versionAtLeast(v, floor) {
+  return compareVersions(v, floor) >= 0;
+}
+
+// src/errors.ts
+var ErrorCodes = {
+  PARSE_ERROR: "parse_error",
+  INVALID_MESSAGE: "invalid_message",
+  VERSION_UNSUPPORTED: "version_unsupported",
+  UNAUTHORIZED: "unauthorized",
+  CAPABILITY_DENIED: "capability_denied",
+  METHOD_NOT_FOUND: "method_not_found",
+  VALIDATION_FAILED: "validation_failed",
+  PAYLOAD_TOO_LARGE: "payload_too_large",
+  RATE_LIMITED: "rate_limited",
+  DEVICE_REVOKED: "device_revoked",
+  SESSION_EXPIRED: "session_expired",
+  PAIRING_EXPIRED: "pairing_expired",
+  PAIRING_INVALID: "pairing_invalid",
+  HOST_OFFLINE: "host_offline",
+  TIMEOUT: "timeout",
+  CANCELLED: "cancelled",
+  INTERNAL: "internal",
+  NOT_CONNECTED: "not_connected",
+  PEER_LOST: "peer_lost",
+  /** the capability is granted but the grant has lapsed and must be renewed */
+  GRANT_EXPIRED: "grant_expired",
+  /** the host user declined a per-use confirmation prompt */
+  CONSENT_DENIED: "consent_denied",
+  /** the host could not obtain a per-use confirmation in time */
+  CONSENT_TIMEOUT: "consent_timeout",
+  /** host permission policy forbids this, independent of what was granted */
+  POLICY_DENIED: "policy_denied"
+};
+var ALL_ERROR_CODES = Object.values(ErrorCodes);
+var CrosslinkError = class _CrosslinkError extends Error {
+  code;
+  data;
+  constructor(code, message, data) {
+    super(message);
+    this.name = "CrosslinkError";
+    this.code = code;
+    this.data = data;
+  }
+  toWire() {
+    return { code: this.code, message: this.message, data: this.data };
+  }
+  static from(err) {
+    if (err instanceof _CrosslinkError) return err;
+    const message = err instanceof Error ? err.message : String(err);
+    return new _CrosslinkError(ErrorCodes.INTERNAL, message);
+  }
+  /** True for codes that must never leak internal detail across the wire. */
+  static isInternal(code) {
+    return code === ErrorCodes.INTERNAL || code === ErrorCodes.PARSE_ERROR || code === ErrorCodes.INVALID_MESSAGE;
+  }
+};
+
+// src/json.ts
+function canonicalJson(value) {
+  return serialize(value);
+}
+function serialize(value) {
+  if (value === null) return "null";
+  const t = typeof value;
+  if (t === "boolean") return value ? "true" : "false";
+  if (t === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("canonicalJson: non-finite number");
+    }
+    return String(value);
+  }
+  if (t === "bigint") {
+    throw new TypeError("canonicalJson: bigint not allowed");
+  }
+  if (t === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    let out = "[";
+    for (let i = 0; i < value.length; i++) {
+      if (i > 0) out += ",";
+      out += serialize(value[i]);
+    }
+    return out + "]";
+  }
+  if (t === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+    let out = "{";
+    for (let i = 0; i < keys.length; i++) {
+      if (i > 0) out += ",";
+      out += `${JSON.stringify(keys[i])}:${serialize(obj[keys[i]])}`;
+    }
+    return out + "}";
+  }
+  throw new TypeError(`canonicalJson: unsupported type ${t}`);
+}
+
+// src/encoding.ts
+var HAS_BUFFER = typeof Buffer !== "undefined";
+function bytesToBase64(bytes) {
+  if (HAS_BUFFER) return Buffer.from(bytes).toString("base64");
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin);
+}
+function base64ToBytes(b64) {
+  if (HAS_BUFFER) {
+    const buf = Buffer.from(b64, "base64");
+    return new Uint8Array(buf);
+  }
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function bytesToBase64Url(bytes) {
+  return bytesToBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlToBytes(s) {
+  let b64 = s.replace(/-/g, "+").replace(/_/g, "/");
+  while (b64.length % 4 !== 0) b64 += "=";
+  return base64ToBytes(b64);
+}
+var HEX = "0123456789abcdef";
+function bytesToHex(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += HEX[bytes[i] >> 4] + HEX[bytes[i] & 15];
+  }
+  return out;
+}
+function hexToBytes(hex) {
+  if (hex.length % 2 !== 0 || /[^0-9a-f]/i.test(hex)) {
+    throw new TypeError("invalid hex string");
+  }
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+var te = new TextEncoder();
+var td = new TextDecoder();
+var utf8ToBytes = (s) => te.encode(s);
+var bytesToUtf8 = (b) => td.decode(b);
+function encodeBinary(bytes, mime) {
+  const ref = { $b: true, d: bytesToBase64(bytes) };
+  if (mime !== void 0) ref.c = mime;
+  return ref;
+}
+function decodeBinary(ref) {
+  if (!isBinaryRef(ref)) throw new TypeError("not a BinaryRef");
+  return base64ToBytes(ref.d);
+}
+function isBinaryRef(value) {
+  return typeof value === "object" && value !== null && value.$b === true && typeof value.d === "string";
+}
+
+// src/messages.ts
+var PROTOCOL = "crosslink";
+var MessageTypes = {
+  HELLO: "hello",
+  HELLO_OK: "hello_ok",
+  REQ: "req",
+  RES: "res",
+  ERR: "err",
+  CHUNK: "chunk",
+  END: "end",
+  EVT: "evt",
+  SUB: "sub",
+  UNSUB: "unsub",
+  CANCEL: "cancel",
+  PING: "ping",
+  PONG: "pong",
+  BYE: "bye"
+};
+var REQUEST_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+var METHOD_RE = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,127}$/;
+var EVENT_RE = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,127}$/;
+var DEVICE_ID_RE = /^cd1_[0-9a-f]{32}$/;
+var VERSION_RE2 = /^\d+\.\d+$/;
+function makeRequestId(rand) {
+  return toUrlSafeBase64ish(rand(12));
+}
+function toUrlSafeBase64ish(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) out += String.fromCharCode(bytes[i]);
+  const b64 = globalThis.btoa !== void 0 ? btoa(out) : BufferFrom(out);
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function BufferFrom(s) {
+  return Buffer.from(s).toString("base64");
+}
+function validateMessage(msg) {
+  if (typeof msg !== "object" || msg === null) return "not-an-object";
+  const m = msg;
+  if (typeof m.v !== "string" || !VERSION_RE2.test(m.v)) return "bad-version";
+  if (!isMessageType(m.t)) return "bad-type";
+  switch (m.t) {
+    case MessageTypes.HELLO: {
+      if (!Array.isArray(m.versions) || m.versions.length === 0) return "hello-versions";
+      if (!m.versions.every((x) => typeof x === "string" && VERSION_RE2.test(x))) {
+        return "hello-version-format";
+      }
+      if (typeof m.deviceId !== "string" || !DEVICE_ID_RE.test(m.deviceId)) return "hello-device-id";
+      if (typeof m.appId !== "string" || m.appId.length === 0 || m.appId.length > 256) {
+        return "hello-app-id";
+      }
+      break;
+    }
+    case MessageTypes.HELLO_OK:
+      if (typeof m.version !== "string" || !VERSION_RE2.test(m.version)) return "hello-ok-version";
+      break;
+    case MessageTypes.REQ:
+      if (typeof m.i !== "string" || !REQUEST_ID_RE.test(m.i)) return "req-id";
+      if (typeof m.m !== "string" || !METHOD_RE.test(m.m)) return "req-method";
+      if (m.idem !== void 0 && m.idem !== true) return "req-idem-flag";
+      break;
+    case MessageTypes.RES:
+    case MessageTypes.END:
+    case MessageTypes.CANCEL:
+      if (typeof m.i !== "string" || !REQUEST_ID_RE.test(m.i)) return `${m.t}-id`;
+      break;
+    case MessageTypes.ERR:
+      if (typeof m.i !== "string" || !REQUEST_ID_RE.test(m.i)) return "err-id";
+      if (typeof m.e !== "object" || m.e === null || typeof m.e.code !== "string" || !ALL_ERROR_CODES.includes(m.e.code) || typeof m.e.message !== "string") {
+        return "err-body";
+      }
+      break;
+    case MessageTypes.CHUNK:
+      if (typeof m.i !== "string" || !REQUEST_ID_RE.test(m.i)) return "chunk-id";
+      if (typeof m.n !== "number" || !Number.isInteger(m.n) || m.n < 0) return "chunk-n";
+      if (m.d === void 0) return "chunk-data-missing";
+      break;
+    case MessageTypes.EVT:
+      if (typeof m.s !== "string" || !REQUEST_ID_RE.test(m.s)) return "evt-sub";
+      if (typeof m.e !== "string" || !EVENT_RE.test(m.e)) return "evt-name";
+      break;
+    case MessageTypes.SUB:
+    case MessageTypes.UNSUB:
+      if (typeof m.s !== "string" || !REQUEST_ID_RE.test(m.s)) return `${m.t}-sub`;
+      if (m.t === MessageTypes.SUB && (typeof m.e !== "string" || !EVENT_RE.test(m.e))) {
+        return "sub-event";
+      }
+      break;
+    case MessageTypes.PING:
+    case MessageTypes.PONG:
+      if (typeof m.ts !== "number" || !Number.isFinite(m.ts)) return "ts";
+      break;
+    case MessageTypes.BYE:
+      break;
+  }
+  return null;
+}
+function isMessageType(value) {
+  return typeof value === "string" && Object.values(MessageTypes).includes(value);
+}
+function isFatalErrorCode(code) {
+  return code === ErrorCodes.DEVICE_REVOKED || code === ErrorCodes.SESSION_EXPIRED || code === ErrorCodes.VERSION_UNSUPPORTED || code === ErrorCodes.UNAUTHORIZED;
+}
+
+// src/limits.ts
+var Limits = {
+  DEFAULT_MAX_FRAME_BYTES: 4 * 1024 * 1024,
+  MAX_FRAME_BYTES_HARD: 16 * 1024 * 1024,
+  DEFAULT_CHUNK_BYTES: 256 * 1024,
+  DEFAULT_REQUEST_TIMEOUT_MS: 3e4,
+  DEFAULT_MAX_INFLIGHT: 32,
+  DEFAULT_RATE_PER_SEC: 50,
+  PAIRING_CODE_TTL_MS: 12e4,
+  HEARTBEAT_INTERVAL_MS: 15e3,
+  HEARTBEAT_TIMEOUT_MS: 45e3,
+  CLOCK_SKEW_MS: 12e4
+};
+
+// src/framing.ts
+function encodeMessage(msg) {
+  return utf8ToBytes(canonicalJson(msg));
+}
+function decodeMessage(data) {
+  let text;
+  try {
+    text = typeof data === "string" ? data : bytesToUtf8(data);
+  } catch {
+    throw new CrosslinkError(ErrorCodes.PARSE_ERROR, "payload is not valid UTF-8");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new CrosslinkError(ErrorCodes.PARSE_ERROR, "payload is not valid JSON");
+  }
+  rejectProto(parsed, 0);
+  if (parsed !== null && typeof parsed === "object" && typeof parsed.v === "string" && !SUPPORTED_VERSIONS.includes(parsed.v)) {
+    throw new CrosslinkError(ErrorCodes.VERSION_UNSUPPORTED, "protocol version is not supported");
+  }
+  const problem = validateMessage(parsed);
+  if (problem) {
+    throw new CrosslinkError(ErrorCodes.INVALID_MESSAGE, `invalid message: ${problem}`);
+  }
+  return parsed;
+}
+function rejectProto(value, depth) {
+  if (depth > 64) {
+    throw new CrosslinkError(ErrorCodes.INVALID_MESSAGE, "payload nesting exceeds 64");
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) rejectProto(item, depth + 1);
+  } else if (value !== null && typeof value === "object") {
+    for (const item of Object.values(value)) rejectProto(item, depth + 1);
+  }
+}
+function encodeFrame(msg, maxFrameBytes = Limits.DEFAULT_MAX_FRAME_BYTES) {
+  const payload = encodeMessage(msg);
+  if (payload.length > maxFrameBytes) {
+    throw new CrosslinkError(
+      ErrorCodes.PAYLOAD_TOO_LARGE,
+      `frame ${payload.length}B exceeds limit ${maxFrameBytes}B`
+    );
+  }
+  const out = new Uint8Array(4 + payload.length);
+  const view = new DataView(out.buffer);
+  view.setUint32(0, payload.length, false);
+  out.set(payload, 4);
+  return out;
+}
+var FrameDecoder = class {
+  constructor(maxFrameBytes = Limits.DEFAULT_MAX_FRAME_BYTES) {
+    this.maxFrameBytes = maxFrameBytes;
+  }
+  maxFrameBytes;
+  buf = new Uint8Array(0);
+  /** Feed raw bytes; returns every complete message that became available. */
+  push(chunk) {
+    const merged = new Uint8Array(this.buf.length + chunk.length);
+    merged.set(this.buf);
+    merged.set(chunk, this.buf.length);
+    this.buf = merged;
+    const out = [];
+    for (; ; ) {
+      if (this.buf.length < 4) break;
+      const view = new DataView(this.buf.buffer, this.buf.byteOffset, this.buf.byteLength);
+      const len = view.getUint32(0, false);
+      if (len > this.maxFrameBytes) {
+        throw new CrosslinkError(
+          ErrorCodes.PAYLOAD_TOO_LARGE,
+          `declared frame ${len}B exceeds limit ${this.maxFrameBytes}B`
+        );
+      }
+      if (this.buf.length < 4 + len) break;
+      const payload = this.buf.subarray(4, 4 + len);
+      out.push(decodeMessage(payload));
+      this.buf = this.buf.slice(4 + len);
+    }
+    return out;
+  }
+};
+
+// src/wire.ts
+function isOuterKind(value) {
+  return value === "sinit" || value === "sack" || value === "srej" || value === "enc" || value === "oping" || value === "opong" || value === "bye";
+}
+var OUTER_KINDS = isOuterKind;
+
+// src/fixtures.ts
+var FIXTURES_VERSION = 1;
+function sampleMessages() {
+  return [
+    {
+      name: "request",
+      obj: { v: PROTOCOL_VERSION, t: MessageTypes.REQ, i: "AAAAAAAAAAAAAAAA", m: "echo", p: { hello: "world", n: 42 } }
+    },
+    {
+      name: "response",
+      obj: { v: PROTOCOL_VERSION, t: MessageTypes.RES, i: "AAAAAAAAAAAAAAAA", p: { echoed: true } }
+    },
+    {
+      name: "error",
+      obj: {
+        v: PROTOCOL_VERSION,
+        t: MessageTypes.ERR,
+        i: "AAAAAAAAAAAAAAAA",
+        e: { code: ALL_ERROR_CODES[0], message: "boom" }
+      }
+    },
+    {
+      name: "chunk-binary",
+      obj: {
+        v: PROTOCOL_VERSION,
+        t: MessageTypes.CHUNK,
+        i: "AAAAAAAAAAAAAAAA",
+        n: 0,
+        d: { $b: true, c: "application/octet-stream", d: "AQIDBA==" }
+      }
+    },
+    {
+      name: "end",
+      obj: { v: PROTOCOL_VERSION, t: MessageTypes.END, i: "AAAAAAAAAAAAAAAA", p: { total: 3 } }
+    },
+    {
+      name: "event",
+      obj: { v: PROTOCOL_VERSION, t: MessageTypes.EVT, s: "BBBBBBBBBBBB", e: "tasks.status", p: { pct: 50 } }
+    },
+    {
+      name: "subscribe",
+      obj: { v: PROTOCOL_VERSION, t: MessageTypes.SUB, s: "BBBBBBBBBBBB", e: "tasks.status" }
+    },
+    {
+      name: "cancel",
+      obj: { v: PROTOCOL_VERSION, t: MessageTypes.CANCEL, i: "AAAAAAAAAAAAAAAA" }
+    },
+    {
+      name: "ping",
+      obj: { v: PROTOCOL_VERSION, t: MessageTypes.PING, ts: 17e11 }
+    }
+  ];
+}
+export {
+  ALL_ERROR_CODES,
+  CrosslinkError,
+  ErrorCodes,
+  FIXTURES_VERSION,
+  FrameDecoder,
+  Limits,
+  MIN_SECURE_VERSION,
+  MessageTypes,
+  OUTER_KINDS,
+  PROTOCOL,
+  PROTOCOL_VERSION,
+  SUPPORTED_VERSIONS,
+  base64ToBytes,
+  base64UrlToBytes,
+  bytesToBase64,
+  bytesToBase64Url,
+  bytesToHex,
+  bytesToUtf8,
+  canonicalJson,
+  compareVersions,
+  decodeBinary,
+  decodeMessage,
+  encodeBinary,
+  encodeFrame,
+  encodeMessage,
+  hexToBytes,
+  isBinaryRef,
+  isFatalErrorCode,
+  isMessageType,
+  isOuterKind,
+  makeRequestId,
+  negotiateVersions,
+  parseVersion,
+  sampleMessages,
+  utf8ToBytes,
+  validateMessage,
+  versionAtLeast
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@crosslink/protocol",
+  "version": "0.1.0",
+  "description": "Crosslink language-neutral wire protocol: envelopes, framing, versioning, errors, fixtures",
+  "license": "Apache-2.0",
+  "repository": { "type": "git", "url": "git+https://github.com/jacobpowaza/crosslink.git", "directory": "packages/protocol" },
+  "homepage": "https://crosslink.mintlify.site",
+  "bugs": { "url": "https://github.com/jacobpowaza/crosslink/issues" },
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "gen:fixtures": "npm run build && node scripts/generate-fixtures.mjs"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.6",
+    "typescript": "^5.6.3"
+  }
+}