@oxpulse/intro-protocol 0.2.0

package/dist/intro-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intro-wire.d.ts","sourceRoot":"","sources":["../src/intro-wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2DxB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;iBAa/B,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;iBAM9B,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;iBAI/B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;iBAI5B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;iBAIhC,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;iBAU7B,CAAC;AAMH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAO7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;AAM7C;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAG5D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,CAEjE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,YAAY,EACjB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAET"}

package/dist/intro-wire.js

@@ -0,0 +1,160 @@
+/**
+ * intro-wire.ts — Wire format codec for L2 introduction protocol messages.
+ *
+ * Encodes/decodes all 6 message types per sub-spec §4.1. Outer envelope
+ * is JSON (matches chat-sdk inner-payload pattern at sdk-inbox-bridge
+ * dispatch). Zod discriminated union validates at the receive boundary.
+ *
+ * ADR-002: JSON + Zod wire format (NOT wire-codec CBOR/zstd — the intro
+ * protocol is its own bounded context per ADR-010).
+ *
+ * Plan: docs/superpowers/plans/2026-05-22-discovery-l2-plan.md (S3)
+ */
+import { z } from 'zod';
+// Constant-time comparison — single source of truth (ADR-008, ADR-011).
+import { timingSafePubkeyEqualB64u } from '@oxpulse/crypto-primitives';
+// ---------------------------------------------------------------------------
+// Primitive validators
+// ---------------------------------------------------------------------------
+/** 22-char URL-safe base64 — encodes 16 bytes (128-bit session ID) */
+const SessionId = z.string().regex(/^[A-Za-z0-9_-]{22}$/);
+/** 43-char URL-safe base64 — encodes 32 bytes (Ed25519/X25519 public key) */
+const PubkeyB64u = z.string().regex(/^[A-Za-z0-9_-]{43}$/);
+/** 43-char URL-safe base64 — X25519 ephemeral public key (same 32B → 43-char) */
+const EphPubB64u = z.string().regex(/^[A-Za-z0-9_-]{43}$/);
+/**
+ * Generic URL-safe base64 string (no fixed length) — used for variable-length
+ * payloads like profile_key_b64u. Constrains charset to base64url to fail
+ * fast on malformed input rather than passing through to downstream decode.
+ */
+const B64uString = z.string().regex(/^[A-Za-z0-9_-]+$/).min(1);
+/**
+ * Deterministically CBOR-encodable transport properties (ADR-013 / #218 nit #6).
+ *
+ * Constrained to scalar types that cborg's rfc8949EncodeOptions encode
+ * canonically: string | number | int | bool | null | arrays thereof.
+ * Rejects floats-with-NaN-payloads, bigint, Map, Set, and other shapes
+ * whose CBOR encoding can diverge between two parties constructing the
+ * "same" logical value (which would break transcript/MAC verification).
+ */
+const TransportProps = z.record(z.string(), z.union([
+    z.string(),
+    z.number(),
+    z.bigint(),
+    z.boolean(),
+    z.null(),
+    z.array(z.unknown()),
+])).default({});
+/**
+ * AEAD ciphertext: 24B nonce ‖ ciphertext ‖ 16B tag, URL-safe base64.
+ * Minimum 54 chars = ceil((24 + 0 + 16) * 4 / 3) = ceil(160/3) = 54.
+ */
+const AeadCiphertextB64u = z
+    .string()
+    .regex(/^[A-Za-z0-9_-]+$/)
+    .min(54);
+// ---------------------------------------------------------------------------
+// Per-kind schemas
+// ---------------------------------------------------------------------------
+export const IntroRequestV1Schema = z.object({
+    kind: z.literal('intro_request_v1'),
+    sessionId: SessionId,
+    target: z.object({
+        pubkey_b64u: PubkeyB64u,
+        author_b64u: PubkeyB64u,
+        profile_key_b64u: B64uString,
+        short_id: z.string().optional(),
+        handle: z.string().optional(),
+        transport_props: TransportProps,
+    }),
+    note: z.string().max(280).optional(),
+    created_at: z.number().int().nonnegative(),
+});
+export const IntroAcceptV1Schema = z.object({
+    kind: z.literal('intro_accept_v1'),
+    sessionId: SessionId,
+    eph_pub_b64u: EphPubB64u,
+    accepted_at: z.number().int().nonnegative(),
+    transport_props: TransportProps,
+});
+export const IntroDeclineV1Schema = z.object({
+    kind: z.literal('intro_decline_v1'),
+    sessionId: SessionId,
+    reason: z.enum(['declined', 'unknown_introducer', 'silent', 'blocked']).optional(),
+});
+export const IntroAuthV1Schema = z.object({
+    kind: z.literal('intro_auth_v1'),
+    sessionId: SessionId,
+    aead_ciphertext: AeadCiphertextB64u,
+});
+export const IntroActivateV1Schema = z.object({
+    kind: z.literal('intro_activate_v1'),
+    sessionId: SessionId,
+    aead_ciphertext: AeadCiphertextB64u,
+});
+export const IntroAbortV1Schema = z.object({
+    kind: z.literal('intro_abort_v1'),
+    sessionId: SessionId,
+    reason: z.enum([
+        'timeout',
+        'invariant_violation',
+        'user_cancel',
+        'peer_declined',
+        'cross_instance_unsupported',
+    ]),
+});
+// ---------------------------------------------------------------------------
+// Discriminated union over all 6 kinds
+// ---------------------------------------------------------------------------
+export const IntroMessageSchema = z.discriminatedUnion('kind', [
+    IntroRequestV1Schema,
+    IntroAcceptV1Schema,
+    IntroDeclineV1Schema,
+    IntroAuthV1Schema,
+    IntroActivateV1Schema,
+    IntroAbortV1Schema,
+]);
+// ---------------------------------------------------------------------------
+// Codec functions
+// ---------------------------------------------------------------------------
+/**
+ * Encode an introduction protocol message to a JSON wire string.
+ *
+ * Validates before encoding (defensive — refuses to produce invalid wire
+ * payloads even when TypeScript types are satisfied at call site).
+ */
+export function encodeIntroMessage(msg) {
+    const validated = IntroMessageSchema.parse(msg);
+    return JSON.stringify(validated);
+}
+/**
+ * Decode an introduction protocol message from an unknown payload.
+ *
+ * The payload is the JSON-parsed object received from sdk-inbox-bridge
+ * onSealedPayload callback. Throws a ZodError on validation failure —
+ * callers must catch and treat as a rejected/malformed message.
+ */
+export function decodeIntroMessage(payload) {
+    return IntroMessageSchema.parse(payload);
+}
+/**
+ * Verify the sessionId redundancy check per sub-spec §4.1.
+ *
+ * The receiver re-derives the sessionId locally from the introducer's
+ * public key + their own key material, then asserts equality against
+ * the value carried on the wire. A mismatch indicates either an
+ * introducer forgery attempt or a deterministic-derivation drift bug.
+ *
+ * Returns true if the wire sessionId matches the locally-derived value.
+ *
+ * *** SECURITY (ADR-011, CWE-208) ***
+ * The comparison uses `timingSafePubkeyEqualB64u` (constant-time XOR-reduce
+ * over the decoded bytes) instead of plain `===`. A plain `===` on the
+ * crypto-derived b64url sessionId leaks the first-mismatch byte position
+ * via timing, enabling a session-id oracle (OWASP ASVS V11.3.1, CWE-208).
+ * The sessionId is attacker-influenced (an introducer forgery attempt
+ * controls the wire value), so it MUST be compared in constant time.
+ */
+export function verifySessionIdRedundancy(msg, derivedSessionId) {
+    return timingSafePubkeyEqualB64u(msg.sessionId, derivedSessionId);
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@oxpulse/intro-protocol",
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "license": "AGPL-3.0-or-later",
+  "author": "Anatoly Koptev",
+  "homepage": "https://github.com/anatolykoptev/oxpulse-chat-sdk/tree/main/packages/intro-protocol",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anatolykoptev/oxpulse-chat-sdk.git",
+    "directory": "packages/intro-protocol"
+  },
+  "bugs": {
+    "url": "https://github.com/anatolykoptev/oxpulse-chat-sdk/issues"
+  },
+  "keywords": [
+    "oxpulse",
+    "chat",
+    "e2ee",
+    "crypto",
+    "introduction",
+    "contact",
+    "safety-number",
+    "timing-safe",
+    "cwe-208"
+  ],
+  "description": "L2 introduction protocol — Briar-faithful intro crypto (X25519+HKDF+AEAD), JSON+Zod wire codec, and Signal-style safety numbers. Fixes CWE-208 timing oracle in sessionId redundancy check. EXPERIMENTAL (0.1.0).",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "scripts": {
+    "prepare": "tsc --outDir dist",
+    "build": "tsc --outDir dist",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@oxpulse/crypto-primitives": "^0.2.0",
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "@noble/ciphers": "^2.2.0",
+    "cborg": "^5.1.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}