@tribe-nest/media-protocol 1.0.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@tribe-nest/media-protocol",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "The contract between the backend, the media plane and every client: wire frames, join-token claims, grants, and the pure sign/verify pair. Zero mediasoup, zero DOM, zero React - apps/backend and apps/media-server may not import each other, so the types have nowhere else to live.",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "module": "./src/index.ts",
+      "default": "./build/index.js"
+    },
+    "./token": {
+      "types": "./build/token.d.ts",
+      "module": "./src/token.ts",
+      "default": "./build/token.js"
+    },
+    "./fixtures": "./src/_fixtures/joinTokenVectors.json"
+  },
+  "typesVersions": {
+    "*": {
+      "token": [
+        "./build/token.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "build",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "gen:vectors": "tsx scripts/generateVectors.ts",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@repo/typescript-config": "*",
+    "tsx": "^4.19.2",
+    "typescript": "5.8.2",
+    "vitest": "^3.2.4"
+  },
+  "license": "ISC"
+}

package/src/_fixtures/joinTokenVectors.json

@@ -0,0 +1,103 @@
+{
+  "_comment": "GENERATED by scripts/generateVectors.ts - do not hand-edit. One fixture read by BOTH the backend minter spec and the media-server verifier spec, so the two cannot drift. The keys are test keys and are committed on purpose.",
+  "nowSeconds": 1760000000,
+  "issuer": "legal-de",
+  "kid": "test-v1",
+  "keys": {
+    "test-v1": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEADDA6KSONGhJqPWozH6py1Gu6M53ZpupI9cLMN/RZtws=\n-----END PUBLIC KEY-----\n"
+  },
+  "privateKeyForMinterTests": "-----BEGIN PRIVATE KEY-----\nMC4CAQAwBQYDK2VwBCIEIO8H96J+s7hghw0TR4cDCVjjaBwMciXpPte0hx7WSFf3\n-----END PRIVATE KEY-----\n",
+  "vectors": [
+    {
+      "name": "valid_human",
+      "why": "the ordinary case: a human joining over webrtc",
+      "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QtdjEifQ.eyJ2IjoxLCJpc3MiOiJsZWdhbC1kZSIsImF1ZCI6Im1lZGlhIiwicm9vbSI6InJvb20tMSIsImlkZW50aXR5IjoiYWxpY2UiLCJraW5kIjoiaHVtYW4iLCJ0cmFuc3BvcnQiOiJ3ZWJydGMiLCJncmFudHMiOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJjYW5QdWJsaXNoRGF0YSI6dHJ1ZX0sImp0aSI6Imp0aS0wMDAwMDAwMSIsImlhdCI6MTc2MDAwMDAwMCwiZXhwIjoxNzYwMDAwMzAwfQ.cHwZ_nFkDQoHVtB6-mA2Rg-KcuVTralgw1cS908OQh7_8JUOKAP9l6kFiKpmfHFMEz6aBt7yXeIRKnBvTfJlBw",
+      "expect": "ok"
+    },
+    {
+      "name": "valid_agent_exempt",
+      "why": "a non-human may be exempt from the active-set ceiling; a human may not",
+      "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QtdjEifQ.eyJ2IjoxLCJpc3MiOiJsZWdhbC1kZSIsImF1ZCI6Im1lZGlhIiwicm9vbSI6InJvb20tMSIsImlkZW50aXR5IjoidHJhbnNjcmliZXIiLCJraW5kIjoiYWdlbnQiLCJ0cmFuc3BvcnQiOiJwbGFpbiIsImdyYW50cyI6eyJjYW5QdWJsaXNoIjpmYWxzZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJjYW5QdWJsaXNoRGF0YSI6ZmFsc2UsInN1YnNjcmliZUV4ZW1wdCI6dHJ1ZX0sImp0aSI6Imp0aS0wMDAwMDAwMSIsImlhdCI6MTc2MDAwMDAwMCwiZXhwIjoxNzYwMDAwMzAwfQ.Mc3KKrczwe0j6YYpe-HXBiYn5C8CeOhYaE2HI64tANDzhucO0BxAgTg9fTdJAGKW8W9RymwV6j83HRWZr854AQ",
+      "expect": "ok"
+    },
+    {
+      "name": "valid_barrier",
+      "why": "an information barrier: alice may receive only carol, and only carol may receive alice",
+      "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QtdjEifQ.eyJ2IjoxLCJpc3MiOiJsZWdhbC1kZSIsImF1ZCI6Im1lZGlhIiwicm9vbSI6InJvb20tMSIsImlkZW50aXR5IjoiYWxpY2UiLCJraW5kIjoiaHVtYW4iLCJ0cmFuc3BvcnQiOiJ3ZWJydGMiLCJncmFudHMiOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJjYW5QdWJsaXNoRGF0YSI6dHJ1ZSwic3Vic2NyaWJlIjp7Im1vZGUiOiJhbGxvdyIsImlkZW50aXRpZXMiOlsiY2Fyb2wiXX0sInZpc2libGVUbyI6eyJtb2RlIjoiYWxsb3ciLCJpZGVudGl0aWVzIjpbImNhcm9sIl19fSwianRpIjoianRpLTAwMDAwMDAxIiwiaWF0IjoxNzYwMDAwMDAwLCJleHAiOjE3NjAwMDAzMDB9.1jx23AACBL-tvtUFSUGQAjjBCuEs6pv7MHSeqAfy7HY-ki65Rf-YadxsPk5Nzg-OrOopu08J6m_Wdm5YA3TMDw",
+      "expect": "ok"
+    },
+    {
+      "name": "unknown_grant_key",
+      "why": "THE fail-open case. One phase minted `subscribeOnly` while another read `subscribe`; a lenient schema would have read 'no rule' as 'everyone' and put two Mandanten in one room.",
+      "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QtdjEifQ.eyJ2IjoxLCJpc3MiOiJsZWdhbC1kZSIsImF1ZCI6Im1lZGlhIiwicm9vbSI6InJvb20tMSIsImlkZW50aXR5IjoiYWxpY2UiLCJraW5kIjoiaHVtYW4iLCJ0cmFuc3BvcnQiOiJ3ZWJydGMiLCJncmFudHMiOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJjYW5QdWJsaXNoRGF0YSI6dHJ1ZSwic3Vic2NyaWJlT25seSI6WyJjYXJvbCJdfSwianRpIjoianRpLTAwMDAwMDAxIiwiaWF0IjoxNzYwMDAwMDAwLCJleHAiOjE3NjAwMDAzMDB9.uda5k_gP-zizkivazZkx1QoSj-54DgnTzCMoTBZ-Pzfyn1jZdw49IvPbAD-88yOfn7ukVYCOko0DRHkxmfu8Aw",
+      "expect": "bad_claims"
+    },
+    {
+      "name": "human_with_subscribe_exempt",
+      "why": "exemption bypasses the active-set ceiling; a human holding it can pull every track in a 1,000-person room",
+      "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QtdjEifQ.eyJ2IjoxLCJpc3MiOiJsZWdhbC1kZSIsImF1ZCI6Im1lZGlhIiwicm9vbSI6InJvb20tMSIsImlkZW50aXR5IjoiYWxpY2UiLCJraW5kIjoiaHVtYW4iLCJ0cmFuc3BvcnQiOiJ3ZWJydGMiLCJncmFudHMiOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJjYW5QdWJsaXNoRGF0YSI6dHJ1ZSwic3Vic2NyaWJlRXhlbXB0Ijp0cnVlfSwianRpIjoianRpLTAwMDAwMDAxIiwiaWF0IjoxNzYwMDAwMDAwLCJleHAiOjE3NjAwMDAzMDB9.o34OTK5D0qRD5enDABkljr_aFerqzoZYLR_uqgTKwO1DsszjDkIG8gUxvjucYZ9apvwWIq3tuwAPVRSAotqYCA",
+      "expect": "bad_claims"
+    },
+    {
+      "name": "expired",
+      "why": "a join ticket outlives its window",
+      "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QtdjEifQ.eyJ2IjoxLCJpc3MiOiJsZWdhbC1kZSIsImF1ZCI6Im1lZGlhIiwicm9vbSI6InJvb20tMSIsImlkZW50aXR5IjoiYWxpY2UiLCJraW5kIjoiaHVtYW4iLCJ0cmFuc3BvcnQiOiJ3ZWJydGMiLCJncmFudHMiOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJjYW5QdWJsaXNoRGF0YSI6dHJ1ZX0sImp0aSI6Imp0aS0wMDAwMDAwMSIsImlhdCI6MTc1OTk5OTQwMCwiZXhwIjoxNzU5OTk5NzAwfQ.hTM23tP-4IP044XhjXNSmzpXMWzi1GC7LrV5vLN_H1SnnI0ZFgLmg8VTW34cPbZy6yIs8mXRZT8uNJ6xsCAQDQ",
+      "expect": "expired"
+    },
+    {
+      "name": "not_yet_valid",
+      "why": "nbf in the future",
+      "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QtdjEifQ.eyJ2IjoxLCJpc3MiOiJsZWdhbC1kZSIsImF1ZCI6Im1lZGlhIiwicm9vbSI6InJvb20tMSIsImlkZW50aXR5IjoiYWxpY2UiLCJraW5kIjoiaHVtYW4iLCJ0cmFuc3BvcnQiOiJ3ZWJydGMiLCJncmFudHMiOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJjYW5QdWJsaXNoRGF0YSI6dHJ1ZX0sImp0aSI6Imp0aS0wMDAwMDAwMSIsImlhdCI6MTc2MDAwMDAwMCwibmJmIjoxNzYwMDAwNjAwLCJleHAiOjE3NjAwMDA5MDB9.xpFjHBt5XYyG6pP9_3j5C-h0FS5Y7byfo_M8qkkGn33iK9i4qO3L_SzFxYebTEoX-jmlTu8Y8MCPlhLzb3MFCw",
+      "expect": "not_yet_valid"
+    },
+    {
+      "name": "ttl_too_long",
+      "why": "enforced at VERIFY as well as mint, because a compromised minter would simply skip the mint check",
+      "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QtdjEifQ.eyJ2IjoxLCJpc3MiOiJsZWdhbC1kZSIsImF1ZCI6Im1lZGlhIiwicm9vbSI6InJvb20tMSIsImlkZW50aXR5IjoiYWxpY2UiLCJraW5kIjoiaHVtYW4iLCJ0cmFuc3BvcnQiOiJ3ZWJydGMiLCJncmFudHMiOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJjYW5QdWJsaXNoRGF0YSI6dHJ1ZX0sImp0aSI6Imp0aS0wMDAwMDAwMSIsImlhdCI6MTc2MDAwMDAwMCwiZXhwIjoxNzYwMDg2NDAwfQ.UCA0foITm9CL3z1ZslwGf4Dvmqe0xkOpYhN9l13-DKRPjje6pGez4jcvhKDGwPuy8f7lovvUfoRwCWG4UGYWCg",
+      "expect": "ttl_too_long"
+    },
+    {
+      "name": "wrong_issuer",
+      "why": "a token minted for the main instance must be worthless on the legal one",
+      "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QtdjEifQ.eyJ2IjoxLCJpc3MiOiJtYWluIiwiYXVkIjoibWVkaWEiLCJyb29tIjoicm9vbS0xIiwiaWRlbnRpdHkiOiJhbGljZSIsImtpbmQiOiJodW1hbiIsInRyYW5zcG9ydCI6IndlYnJ0YyIsImdyYW50cyI6eyJjYW5QdWJsaXNoIjp0cnVlLCJjYW5TdWJzY3JpYmUiOnRydWUsImNhblB1Ymxpc2hEYXRhIjp0cnVlfSwianRpIjoianRpLTAwMDAwMDAxIiwiaWF0IjoxNzYwMDAwMDAwLCJleHAiOjE3NjAwMDAzMDB9.Z33LRIVYrY7KlvUUsQCZ52x7HBxPKWBuJSKySb6d0Ncmenu8CpFSxC2JRm_s7NPbuMwBymgQjKUiFmTeUm_FCA",
+      "expect": "wrong_issuer"
+    },
+    {
+      "name": "wrong_audience_control_as_join",
+      "why": "a control token replayed as a join",
+      "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QtdjEifQ.eyJ2IjoxLCJpc3MiOiJsZWdhbC1kZSIsImF1ZCI6ImNvbnRyb2wiLCJqdGkiOiJqdGktY29udHJvbC0xIiwiaWF0IjoxNzYwMDAwMDAwLCJleHAiOjE3NjAwMDAzMDB9.q9LAV0vxFy95CqICQ9jl5dm7ll_iD8HSDADK0cQu85wJxVx1roQL-RZggjcrxhShH2uzfKufTW9211pF56caDA",
+      "expect": "wrong_audience"
+    },
+    {
+      "name": "unknown_kid",
+      "why": "signed by a key this node does not carry",
+      "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InJvdGF0ZWQtYXdheSJ9.eyJ2IjoxLCJpc3MiOiJsZWdhbC1kZSIsImF1ZCI6Im1lZGlhIiwicm9vbSI6InJvb20tMSIsImlkZW50aXR5IjoiYWxpY2UiLCJraW5kIjoiaHVtYW4iLCJ0cmFuc3BvcnQiOiJ3ZWJydGMiLCJncmFudHMiOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJjYW5QdWJsaXNoRGF0YSI6dHJ1ZX0sImp0aSI6Imp0aS0wMDAwMDAwMSIsImlhdCI6MTc2MDAwMDAwMCwiZXhwIjoxNzYwMDAwMzAwfQ.W_BZBx_p9W245Xw89H3Dy_MEYf5JfNb8KpSeLok4ZjYUc_EWx8wxvghDrWjaidXp6yxOK3Su_r_b_QHOis7tCA",
+      "expect": "unknown_kid"
+    },
+    {
+      "name": "bad_signature",
+      "why": "correct kid, wrong key - a forgery attempt rather than a rotation",
+      "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QtdjEifQ.eyJ2IjoxLCJpc3MiOiJsZWdhbC1kZSIsImF1ZCI6Im1lZGlhIiwicm9vbSI6InJvb20tMSIsImlkZW50aXR5IjoiYWxpY2UiLCJraW5kIjoiaHVtYW4iLCJ0cmFuc3BvcnQiOiJ3ZWJydGMiLCJncmFudHMiOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJjYW5QdWJsaXNoRGF0YSI6dHJ1ZX0sImp0aSI6Imp0aS0wMDAwMDAwMSIsImlhdCI6MTc2MDAwMDAwMCwiZXhwIjoxNzYwMDAwMzAwfQ.Chdv_Jl7v6HTE5u1TpP6f7j2mqFPocPKfBSdwgbL_lNIN708mHHA5oGeR8AOjPakn16WLTW6jODEUnbj_KTLAA",
+      "expect": "bad_signature"
+    },
+    {
+      "name": "alg_none",
+      "why": "classic JWT algorithm confusion. Only EdDSA is ever accepted.",
+      "token": "eyJhbGciOiJub25lIiwidHlwIjoiSldUIiwia2lkIjoidGVzdC12MSJ9.eyJ2IjoxLCJpc3MiOiJsZWdhbC1kZSIsImF1ZCI6Im1lZGlhIiwicm9vbSI6InJvb20tMSIsImlkZW50aXR5IjoiYWxpY2UiLCJraW5kIjoiaHVtYW4iLCJ0cmFuc3BvcnQiOiJ3ZWJydGMiLCJncmFudHMiOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJjYW5QdWJsaXNoRGF0YSI6dHJ1ZX0sImp0aSI6Imp0aS0wMDAwMDAwMSIsImlhdCI6MTc2MDAwMDAwMCwiZXhwIjoxNzYwMDAwMzAwfQ.",
+      "expect": "malformed"
+    },
+    {
+      "name": "wrong_room",
+      "why": "a valid token for a different room",
+      "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6InRlc3QtdjEifQ.eyJ2IjoxLCJpc3MiOiJsZWdhbC1kZSIsImF1ZCI6Im1lZGlhIiwicm9vbSI6InJvb20tMiIsImlkZW50aXR5IjoiYWxpY2UiLCJraW5kIjoiaHVtYW4iLCJ0cmFuc3BvcnQiOiJ3ZWJydGMiLCJncmFudHMiOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJjYW5QdWJsaXNoRGF0YSI6dHJ1ZX0sImp0aSI6Imp0aS0wMDAwMDAwMSIsImlhdCI6MTc2MDAwMDAwMCwiZXhwIjoxNzYwMDAwMzAwfQ.EWEv-Np5ECbj4TZXt3KTgcPUHEoDM2G4Wx-M0L25pTkE0onIRMm5vmbVBypULUtIWtKxOxsdDNBezcl8Nqy8Bg",
+      "expect": "wrong_room",
+      "room": "room-1"
+    },
+    {
+      "name": "malformed",
+      "why": "not three segments",
+      "token": "not.a.token.at.all",
+      "expect": "malformed"
+    }
+  ]
+}

package/src/_tests/codecs.spec.ts

@@ -0,0 +1,66 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { MEDIA_CODECS, audioOnlyCapabilities } from "../codecs";
+
+/**
+ * The list every Router in the fleet is created from, and every server-side
+ * participant derives its capabilities from.
+ *
+ * It lives here because the node is not the only party that has to agree: a
+ * room agent, the SIP gateway and the RTMP ingress each declare RTP
+ * capabilities on `consume`, each runs in its own app, and none may import
+ * `apps/media-server`. Their only alternative was a second hand-written copy,
+ * and a second copy is the drift the pinning exists to prevent.
+ */
+describe("MEDIA_CODECS", () => {
+  it("pins exactly the codecs the fleet negotiates", () => {
+    expect(MEDIA_CODECS.map((codec) => codec.mimeType)).toEqual(["audio/opus", "video/VP8", "video/H264"]);
+  });
+
+  it("keeps the RTCP feedback a keyframe request needs a wire representation", () => {
+    // Drop `pli` and every active-speaker switch shows macroblocks until the
+    // encoder happens to send an IDR on its own schedule.
+    for (const codec of MEDIA_CODECS.filter((c) => c.kind === "video")) {
+      expect(codec.rtcpFeedback?.some((fb) => fb.type === "nack" && fb.parameter === "pli")).toBe(true);
+    }
+  });
+
+  it("stays free of mediasoup, so a browser can import a frame type", () => {
+    // The structural types are declared here rather than imported for exactly
+    // this reason. `apps/media-server` re-exports these values through
+    // mediasoup-typed bindings, so a divergence fails ITS compile.
+    const source = readFileSync(join(__dirname, "..", "codecs.ts"), "utf8");
+    expect(source).not.toMatch(/from ["']mediasoup/);
+  });
+});
+
+describe("audioOnlyCapabilities", () => {
+  it("keeps the audio codecs and drops the video ones", () => {
+    const derived = audioOnlyCapabilities();
+    expect(derived.codecs.map((codec) => codec.mimeType)).toEqual(["audio/opus"]);
+    expect(derived.codecs.every((codec) => codec.kind === "audio")).toBe(true);
+    expect(derived.headerExtensions).toEqual([]);
+  });
+
+  it("carries the codec parameters through rather than restating them", () => {
+    // `useinbandfec` buys intelligibility across the packet loss a consultation
+    // actually hits. A participant that negotiated without it is the one that
+    // degrades first, and nothing anywhere would say why.
+    const opus = MEDIA_CODECS.find((codec) => codec.mimeType === "audio/opus");
+    expect(audioOnlyCapabilities().codecs[0]?.parameters).toEqual(opus?.parameters);
+  });
+
+  it("assigns a payload type in the dynamic range when the fleet pins none", () => {
+    const derived = audioOnlyCapabilities([{ kind: "audio", mimeType: "audio/opus", clockRate: 48000 }]);
+    expect(derived.codecs[0]?.preferredPayloadType).toBe(100);
+  });
+
+  it("respects a payload type the fleet does pin", () => {
+    const derived = audioOnlyCapabilities([
+      { kind: "audio", mimeType: "audio/opus", clockRate: 48000, preferredPayloadType: 111 },
+    ]);
+    expect(derived.codecs[0]?.preferredPayloadType).toBe(111);
+  });
+});

package/src/_tests/publishGrants.spec.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+
+import { mayPublish, requiredPublishKind, type MediaGrants } from "../grants";
+
+/**
+ * The two vocabularies, pinned against each other.
+ *
+ * A grant lists KINDS ("audio", "video", "screen"); a publisher declares a
+ * SOURCE ("microphone", "camera", "screen", "rtmp"). Comparing the two lists
+ * directly is what shipped: a booking token minted with every kind refused
+ * every microphone and every camera, because neither word appears in a grant,
+ * and let a screen share through because "screen" is the one word both lists
+ * contain. Every assertion below is one half of that mistake.
+ */
+
+const open: MediaGrants = { canPublish: true, canSubscribe: true, canPublishData: false };
+
+describe("requiredPublishKind", () => {
+  it("maps the sources the browser SDK actually sends", () => {
+    // These three are exactly what `room.publish(track, source)` puts in
+    // `appData`. Nothing else in the SDK can produce a source.
+    expect(requiredPublishKind("microphone", "audio")).toBe("audio");
+    expect(requiredPublishKind("camera", "video")).toBe("video");
+    expect(requiredPublishKind("screen", "video")).toBe("screen");
+  });
+
+  it("falls back to the track's kind for a source it does not know", () => {
+    // The RTMP relay publishes `{ source: "rtmp" }` on both an audio and a
+    // video track, and its token is minted `["audio", "video"]`. A fallback to
+    // the KIND is what lets a new source exist without a protocol change.
+    expect(requiredPublishKind("rtmp", "audio")).toBe("audio");
+    expect(requiredPublishKind("rtmp", "video")).toBe("video");
+    expect(requiredPublishKind(undefined, "audio")).toBe("audio");
+  });
+
+  it("discards a source the track contradicts, rather than letting the label decide", () => {
+    // The bypass this closes: the label outranking the fact. A "microphone"
+    // carrying a VIDEO track used to resolve to "audio", so an audio-only seat
+    // published a camera by renaming it. mediasoup knows the kind; the client
+    // only asserts the source, and an assertion the media contradicts is worth
+    // nothing.
+    expect(requiredPublishKind("microphone", "video")).toBe("video");
+    expect(requiredPublishKind("camera", "audio")).toBe("audio");
+
+    // A screen share is the one source that legitimately carries either, because
+    // a shared window may bring its system audio along.
+    expect(requiredPublishKind("screen", "audio")).toBe("screen");
+    expect(requiredPublishKind("screen", "video")).toBe("screen");
+  });
+
+  it("never resolves an undeclared source to `screen`", () => {
+    // The fallback must not become a way round the one grant that cannot be
+    // inferred from the media: a screen share is only ever reachable by saying
+    // so, which is what keeps `["audio", "video"]` meaningful.
+    for (const source of [undefined, "rtmp", "camera", "microphone", "anything"]) {
+      expect(requiredPublishKind(source, "video")).not.toBe("screen");
+    }
+  });
+});
+
+describe("mayPublish", () => {
+  it("lets the grants a booking room mints carry a microphone and a camera", () => {
+    // `BOOKING_GRANTS` and the consultation grants both mint exactly this.
+    const booking: MediaGrants = { ...open, publishKinds: ["audio", "video", "screen"] };
+
+    expect(mayPublish(booking, { source: "microphone", trackKind: "audio" })).toBe(true);
+    expect(mayPublish(booking, { source: "camera", trackKind: "video" })).toBe(true);
+    expect(mayPublish(booking, { source: "screen", trackKind: "video" })).toBe(true);
+  });
+
+  it("still refuses a screen share on a token that was granted audio and video", () => {
+    const ingress: MediaGrants = { ...open, publishKinds: ["audio", "video"] };
+
+    expect(mayPublish(ingress, { source: "rtmp", trackKind: "audio" })).toBe(true);
+    expect(mayPublish(ingress, { source: "rtmp", trackKind: "video" })).toBe(true);
+    expect(mayPublish(ingress, { source: "screen", trackKind: "video" })).toBe(false);
+  });
+
+  it("refuses a camera on an audio-only seat", () => {
+    const listenAndTalk: MediaGrants = { ...open, publishKinds: ["audio"] };
+
+    expect(mayPublish(listenAndTalk, { source: "microphone", trackKind: "audio" })).toBe(true);
+    expect(mayPublish(listenAndTalk, { source: "camera", trackKind: "video" })).toBe(false);
+    expect(mayPublish(listenAndTalk, { source: "screen", trackKind: "video" })).toBe(false);
+    // And not by dropping the label either.
+    expect(mayPublish(listenAndTalk, { source: undefined, trackKind: "video" })).toBe(false);
+  });
+
+  it("refuses a camera on an audio-only seat that calls itself a microphone", () => {
+    // The two audio-only grants the product mints are a SIP gateway
+    // (`SIP_GRANTS`) and an assistant runtime (`ASSISTANT_GRANTS`). Both are
+    // processes on somebody else's box, so `publishKinds` is the claim that has
+    // to hold once the holder is compromised - and a compromised holder writes
+    // its own `appData`.
+    const listenAndTalk: MediaGrants = { ...open, publishKinds: ["audio"] };
+
+    expect(mayPublish(listenAndTalk, { source: "microphone", trackKind: "video" })).toBe(false);
+    // The mirror of it: a video-only seat must not send audio by calling it a
+    // camera.
+    const seeOnly: MediaGrants = { ...open, publishKinds: ["video"] };
+    expect(mayPublish(seeOnly, { source: "camera", trackKind: "audio" })).toBe(false);
+  });
+
+  it("reads an absent `publishKinds` as every kind, and `canPublish: false` as none", () => {
+    expect(mayPublish(open, { source: "camera", trackKind: "video" })).toBe(true);
+    expect(mayPublish({ ...open, canPublish: false }, { source: "microphone", trackKind: "audio" })).toBe(false);
+    expect(mayPublish(undefined, { source: "microphone", trackKind: "audio" })).toBe(false);
+  });
+});

package/src/_tests/token.spec.ts

@@ -0,0 +1,272 @@
+import { describe, expect, it } from "vitest";
+
+import vectors from "../_fixtures/joinTokenVectors.json";
+import type { MediaGrants } from "../grants";
+import { maySubscribe } from "../grants";
+import {
+  MAX_TOKEN_TTL_SECONDS,
+  assertPublicKeyringIsPublicOnly,
+  generateKeypair,
+  signJoinToken,
+  verifyJoinToken,
+} from "../token";
+import { MEDIA_PARTICIPANT_NAME_MAX_LENGTH, clampParticipantName, type MediaJoinClaims } from "../claims";
+
+/**
+ * The golden vectors are the point of this file.
+ *
+ * The same JSON is read by the backend's minter spec and the media server's
+ * verifier spec, so a rename on one side fails on the other rather than
+ * producing tokens that verify in unit tests and not in staging. That drift is
+ * exactly what the phase reconciliation found: six independently written plans,
+ * seven different claim sets.
+ */
+describe("golden vectors", () => {
+  const args = { keys: vectors.keys as Record<string, string>, issuer: vectors.issuer, nowSeconds: vectors.nowSeconds };
+
+  it("covers every rejection reason the verifier can return", () => {
+    // A vector set that only tests the happy path is decoration.
+    const covered = new Set(vectors.vectors.map((v) => v.expect));
+    for (const reason of [
+      "ok",
+      "malformed",
+      "unknown_kid",
+      "bad_signature",
+      "expired",
+      "not_yet_valid",
+      "ttl_too_long",
+      "wrong_audience",
+      "wrong_issuer",
+      "wrong_room",
+      "bad_claims",
+    ]) {
+      expect(covered.has(reason), `no vector produces ${reason}`).toBe(true);
+    }
+  });
+
+  for (const v of vectors.vectors) {
+    it(`${v.name}: ${v.expect}`, () => {
+      const result = verifyJoinToken({
+        token: v.token,
+        ...args,
+        ...(v.room ? { expectedRoom: v.room } : {}),
+      });
+      if (v.expect === "ok") {
+        expect(result.ok, `${v.name} should verify: ${v.why}`).toBe(true);
+      } else {
+        expect(result.ok).toBe(false);
+        expect(result.ok === false && result.reason, v.why).toBe(v.expect);
+      }
+    });
+  }
+});
+
+/**
+ * The fail-open case, stated on its own because it is the one with a §203
+ * consequence rather than a broken-feature consequence.
+ */
+describe("an unknown grant key is REFUSED, never partially understood", () => {
+  const { publicKey, privateKey } = generateKeypair();
+  const keys = { k1: publicKey };
+  const now = 1_800_000_000;
+
+  const claims = (grants: unknown): MediaJoinClaims =>
+    ({
+      v: 1,
+      iss: "legal-de",
+      aud: "media",
+      room: "r",
+      identity: "alice",
+      kind: "human",
+      transport: "webrtc",
+      grants,
+      jti: "jti-aaaaaaaa",
+      iat: now,
+      exp: now + 300,
+    }) as MediaJoinClaims;
+
+  it("rejects a misspelled subscribe rule rather than reading it as 'no rule, so everyone'", () => {
+    // Hand-signed: the minter would refuse this, which is the point - the
+    // verifier must not be the only thing standing in the way, and must not
+    // wave it through either.
+    const raw = (payload: unknown) => {
+      const b = (x: Buffer) => x.toString("base64url");
+      const h = b(Buffer.from(JSON.stringify({ alg: "EdDSA", typ: "JWT", kid: "k1" })));
+      const p = b(Buffer.from(JSON.stringify(payload)));
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const crypto = require("crypto") as typeof import("crypto");
+      return `${h}.${p}.${b(crypto.sign(null, Buffer.from(`${h}.${p}`), privateKey))}`;
+    };
+
+    const token = raw(claims({ canPublish: true, canSubscribe: true, canPublishData: true, subscribeOnly: ["carol"] }));
+    const result = verifyJoinToken({ token, keys, issuer: "legal-de", nowSeconds: now });
+
+    expect(result.ok).toBe(false);
+    expect(result.ok === false && result.reason).toBe("bad_claims");
+  });
+});
+
+describe("minting refuses tokens that should not exist", () => {
+  const { privateKey } = generateKeypair();
+  const now = 1_800_000_000;
+  const base = {
+    v: 1 as const,
+    iss: "legal-de",
+    aud: "media" as const,
+    room: "r",
+    identity: "alice",
+    jti: "jti-aaaaaaaa",
+    iat: now,
+  };
+
+  it("refuses a ttl beyond the ceiling", () => {
+    expect(() =>
+      signJoinToken(privateKey, "k1", {
+        ...base,
+        kind: "human",
+        transport: "webrtc",
+        grants: { canPublish: true, canSubscribe: true, canPublishData: true },
+        exp: now + MAX_TOKEN_TTL_SECONDS + 1,
+      }),
+    ).toThrow(/ttl exceeds/);
+  });
+
+  it("refuses subscribeExempt for a human", () => {
+    expect(() =>
+      signJoinToken(privateKey, "k1", {
+        ...base,
+        kind: "human",
+        transport: "webrtc",
+        grants: { canPublish: true, canSubscribe: true, canPublishData: true, subscribeExempt: true },
+        exp: now + 300,
+      }),
+    ).toThrow(/subscribeExempt/);
+  });
+
+  /**
+   * The refusal that has to be prevented UPSTREAM rather than handled.
+   *
+   * A minting surface builds `name` out of stored text it cannot bound (a
+   * buyer's name off a booking row, a seat's display name off a roster), and
+   * this parse throws rather than truncating - which on the bookings surface
+   * meant a permanent 500 on every join attempt, after the room rows had
+   * already been committed. `clampParticipantName` is the fix, and it lives in
+   * this package so there is exactly one thing to call.
+   */
+  it("refuses a name longer than the claim allows, and accepts a clamped one", () => {
+    const tooLong = "N".repeat(MEDIA_PARTICIPANT_NAME_MAX_LENGTH + 1);
+    const mint = (name: string) =>
+      signJoinToken(privateKey, "k1", {
+        ...base,
+        name,
+        kind: "human",
+        transport: "webrtc",
+        grants: { canPublish: true, canSubscribe: true, canPublishData: true },
+        exp: now + 300,
+      });
+
+    expect(() => mint(tooLong)).toThrow();
+    expect(() => mint(clampParticipantName(tooLong))).not.toThrow();
+  });
+
+  it("clamps to exactly the bound and leaves a short name alone", () => {
+    expect(clampParticipantName("N".repeat(400))).toHaveLength(MEDIA_PARTICIPANT_NAME_MAX_LENGTH);
+    expect(clampParticipantName("N".repeat(MEDIA_PARTICIPANT_NAME_MAX_LENGTH))).toHaveLength(
+      MEDIA_PARTICIPANT_NAME_MAX_LENGTH,
+    );
+    expect(clampParticipantName("Bought Session")).toBe("Bought Session");
+  });
+
+  /** A browser asking for a PlainTransport pointed anywhere is an RTP
+   * reflector plus an unauthenticated publish path into the room. */
+  it("refuses a non-webrtc transport for a human", () => {
+    expect(() =>
+      signJoinToken(privateKey, "k1", {
+        ...base,
+        kind: "human",
+        transport: "plain",
+        grants: { canPublish: true, canSubscribe: true, canPublishData: true },
+        exp: now + 300,
+      }),
+    ).toThrow(/webrtc/);
+  });
+});
+
+describe("a node's keyring must be verify-only", () => {
+  it("refuses to boot when a PRIVATE key is in the node's keyring", () => {
+    const { privateKey } = generateKeypair();
+    expect(() => assertPublicKeyringIsPublicOnly({ k1: privateKey })).toThrow(/PRIVATE key/);
+  });
+
+  it("refuses an unreadable key", () => {
+    expect(() => assertPublicKeyringIsPublicOnly({ k1: "not a key" })).toThrow(/readable public key/);
+  });
+
+  it("accepts a public keyring", () => {
+    const { publicKey } = generateKeypair();
+    expect(() => assertPublicKeyringIsPublicOnly({ k1: publicKey })).not.toThrow();
+  });
+});
+
+/**
+ * The information barrier. A boolean cannot express "A and B are in one room
+ * and must not receive each other, while C may receive both", which is the
+ * actual requirement for a Kanzlei.
+ */
+describe("maySubscribe", () => {
+  const open: MediaGrants = { canPublish: true, canSubscribe: true, canPublishData: false };
+  const walled = (from: string[]): MediaGrants => ({ ...open, subscribe: { mode: "deny", identities: from } });
+  const hidden = (from: string[]): MediaGrants => ({ ...open, visibleTo: { mode: "deny", identities: from } });
+
+  const may = (c: string, cg: MediaGrants, p: string, pg: MediaGrants | undefined) =>
+    maySubscribe({ consumerIdentity: c, consumerGrants: cg, producerIdentity: p, ownerGrants: pg });
+
+  it("allows an ordinary pair", () => {
+    expect(may("alice", open, "bob", open)).toBe(true);
+  });
+
+  it("holds a two-way barrier between A and B while C sees both", () => {
+    // The case a boolean cannot express.
+    const alice = walled(["bob"]);
+    const bob = walled(["alice"]);
+    expect(may("alice", alice, "bob", bob)).toBe(false);
+    expect(may("bob", bob, "alice", alice)).toBe(false);
+    expect(may("carol", open, "alice", alice)).toBe(true);
+    expect(may("carol", open, "bob", bob)).toBe(true);
+  });
+
+  /** One-sided is not enough: a generously minted consumer must not be able to
+   * receive someone who was explicitly walled off from them. */
+  it("refuses on the PRODUCER's rule even when the consumer's is open", () => {
+    expect(may("alice", open, "bob", hidden(["alice"]))).toBe(false);
+  });
+
+  it("treats an unreadable owner as NO, not as the permissive default", () => {
+    // "I do not know" and "everyone" must never be the same answer in a room
+    // with a barrier. Note this differs from an ABSENT rule on a record that
+    // was found, which does mean everyone.
+    expect(may("alice", open, "bob", undefined)).toBe(false);
+  });
+
+  it("treats an absent rule on a found record as everyone", () => {
+    expect(may("alice", open, "bob", open)).toBe(true);
+  });
+
+  it("refuses when the consumer cannot subscribe at all", () => {
+    expect(may("alice", { ...open, canSubscribe: false }, "bob", open)).toBe(false);
+  });
+
+  it("refuses self-subscription", () => {
+    expect(may("alice", open, "alice", open)).toBe(false);
+  });
+
+  it("honours an allow list in both directions", () => {
+    const onlyCarol: MediaGrants = { ...open, subscribe: { mode: "allow", identities: ["carol"] } };
+    expect(may("alice", onlyCarol, "carol", open)).toBe(true);
+    expect(may("alice", onlyCarol, "bob", open)).toBe(false);
+  });
+
+  it("refuses everything under mode none", () => {
+    expect(may("alice", { ...open, subscribe: { mode: "none" } }, "bob", open)).toBe(false);
+  });
+});