@tribe-nest/media-protocol 1.0.0

package/src/grants.ts

@@ -0,0 +1,248 @@
+import { z } from "zod";
+
+/**
+ * What a participant is allowed to do, and - the part that matters most - who
+ * they may receive.
+ *
+ * ## Why the schema is `.strict()`
+ *
+ * This is the single line that stops the information barrier failing open.
+ *
+ * Ten phase plans were written in parallel and two of them disagreed on a name:
+ * one minted `grants.subscribeOnly`, the other read `grants.subscribe`. The
+ * reader would have found nothing, applied its documented default ("an absent
+ * rule means everyone"), and two Mandanten in one room would have received each
+ * other with nothing anywhere erroring. That is a §203 incident whose start
+ * date is unrecoverable from logs.
+ *
+ * `.strict()` turns that class of mistake from silent permissiveness into a
+ * loud verification failure: a token carrying an unknown grant key is rejected
+ * with `bad_claims` rather than partially understood. Any future rename fails
+ * the same way, at mint time, in a test.
+ */
+
+/**
+ * Who a participant may receive, or be received by.
+ *
+ * A boolean cannot express an information barrier. "A and B are in one room and
+ * must not receive each other, while C may receive both" is the actual
+ * requirement for a Kanzlei, and it is a per-identity rule rather than a
+ * per-room one.
+ */
+export const subscribeRuleSchema = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("all") }).strict(),
+  z.object({ mode: z.literal("none") }).strict(),
+  z.object({ mode: z.literal("allow"), identities: z.array(z.string()).max(500) }).strict(),
+  z.object({ mode: z.literal("deny"), identities: z.array(z.string()).max(500) }).strict(),
+]);
+
+export type SubscribeRule = z.infer<typeof subscribeRuleSchema>;
+
+export const participantKindSchema = z.enum(["human", "agent", "egress", "sip", "ingress"]);
+export type ParticipantKind = z.infer<typeof participantKindSchema>;
+
+/**
+ * Transport authority is NOT media authority, which is why this is its own
+ * claim rather than something inferred from `kind`.
+ *
+ * A browser holding a perfectly valid join token must not be able to ask for a
+ * `PlainTransport` pointed at an address of its choosing. That is an RTP
+ * reflector and an unauthenticated publish path into whatever room the token
+ * names. Three phases independently needed to refuse it and none could, because
+ * nothing carried the fact.
+ */
+export const transportKindSchema = z.enum(["webrtc", "plain", "pipe"]);
+export type TransportKind = z.infer<typeof transportKindSchema>;
+
+/**
+ * The two vocabularies, and the ONE place they are reconciled.
+ *
+ * A grant is written in kinds - "audio", "video", "screen" - because that is
+ * what a person minting a token thinks in: may this seat talk, may it be seen,
+ * may it present. A publisher labels its track with a SOURCE, because that is
+ * what it knows and what the other side renders: "microphone", "camera",
+ * "screen", "rtmp". The two lists overlap on one word and disagree on the rest.
+ *
+ * That disagreement shipped as a defect. The node compared the declared source
+ * against `publishKinds` directly, so a booking token minted with the full
+ * `["audio", "video", "screen"]` refused every microphone and every camera the
+ * browser SDK offered it - "microphone" is not in the list - and the only thing
+ * a coaching call could publish was a screen share. It refused the RTMP ingress
+ * for the same reason, whose source is "rtmp".
+ *
+ * So the translation lives here, next to the schema that creates the need for
+ * it, and both the node and the UI read it. An unrecognised source falls back to
+ * the TRACK's kind, which is a fact about the media rather than a claim: that is
+ * what lets a new source ("rtmp") work without a protocol change while a token
+ * granting audio only still cannot send video by inventing a label for it. The
+ * one thing a client can never do is send a screen share on an audio-or-video
+ * grant, because "screen" is only ever reachable by declaring it.
+ *
+ * ## A declaration is only honoured when the track could carry it
+ *
+ * The label is the client's claim; the track's kind is a fact mediasoup already
+ * knows. Translating the claim UNCONDITIONALLY made the claim outrank the fact,
+ * which is the bypass restated: `{ source: "microphone", kind: "video" }`
+ * resolved to "audio", so a seat minted `publishKinds: ["audio"]` published a
+ * camera and the node created a video producer with the real kind. The two
+ * audio-only grants in the product are a SIP gateway and an assistant runtime,
+ * and `publishKinds` is precisely the claim that has to survive the holder being
+ * compromised.
+ *
+ * So a source is translated only when it can actually carry the track in hand
+ * (a microphone carries audio, a camera carries video, a screen share carries
+ * either, because a shared window may bring system audio with it). A declaration
+ * the track contradicts is not a translation, it is a relabelling, and it is
+ * discarded in favour of the fact.
+ */
+export const publishKindSchema = z.enum(["audio", "video", "screen"]);
+export type PublishKind = z.infer<typeof publishKindSchema>;
+
+/** The sources the browser SDK publishes with. Others are legal on the wire. */
+export const publishSourceSchema = z.enum(["microphone", "camera", "screen"]);
+export type PublishSource = z.infer<typeof publishSourceSchema>;
+
+const SOURCE_KINDS: Record<PublishSource, PublishKind> = {
+  microphone: "audio",
+  camera: "video",
+  screen: "screen",
+};
+
+/**
+ * What each source is physically able to carry.
+ *
+ * A screen share holds both, because sharing a window may bring its system
+ * audio; a microphone and a camera hold exactly one each. Anything outside this
+ * is a label that disagrees with the media, and the media wins.
+ */
+const SOURCE_TRACK_KINDS: Record<PublishSource, readonly ("audio" | "video")[]> = {
+  microphone: ["audio"],
+  camera: ["video"],
+  screen: ["audio", "video"],
+};
+
+/** Which grant a publish needs, from what it declares and what it carries. */
+export function requiredPublishKind(source: string | undefined, trackKind: "audio" | "video"): PublishKind {
+  const declared = source ? SOURCE_KINDS[source as PublishSource] : undefined;
+  if (!declared) return trackKind;
+  // The declaration is honoured only where the track bears it out. A camera on
+  // an audio track, or a microphone on a video one, is a relabelling, and
+  // falling back to the track's own kind is what stops it buying a grant the
+  // token was never given.
+  if (!SOURCE_TRACK_KINDS[source as PublishSource].includes(trackKind)) return trackKind;
+  return declared;
+}
+
+/**
+ * May this token publish this? The node's decision, and the UI's hint, from one
+ * function so the button and the enforcement cannot disagree.
+ */
+export function mayPublish(
+  grants: MediaGrants | undefined,
+  input: { source: string | undefined; trackKind: "audio" | "video" },
+): boolean {
+  if (!grants?.canPublish) return false;
+  if (!grants.publishKinds) return true;
+  return grants.publishKinds.includes(requiredPublishKind(input.source, input.trackKind));
+}
+
+export const mediaGrantsSchema = z
+  .object({
+    canPublish: z.boolean(),
+    canSubscribe: z.boolean(),
+    canPublishData: z.boolean(),
+    /** Who I may receive. Omitted means `{ mode: "all" }`. */
+    subscribe: subscribeRuleSchema.optional(),
+    /**
+     * Who may receive ME. Enforced on the PRODUCER side from the owner's stored
+     * grants, so a barrier holds even if the other party's token is generous.
+     */
+    visibleTo: subscribeRuleSchema.optional(),
+    /**
+     * Which kinds of media this token may send, in the vocabulary of
+     * `publishKindSchema`. A publisher labels its track with a SOURCE
+     * ("microphone", "camera", "screen", "rtmp", ...) and those are not the same
+     * words: `requiredPublishKind` below is the one translation between them.
+     */
+    publishKinds: z.array(publishKindSchema).optional(),
+    /**
+     * Bypasses the top-N active-speaker refusal. Mintable ONLY for a non-human
+     * kind: a recorder needs every track, a human asking for 1,000 does not.
+     */
+    subscribeExempt: z.boolean().optional(),
+    /** Hard ceiling on concurrent consumers, for a non-human participant. */
+    maxSubscriptions: z.number().int().positive().max(5000).optional(),
+  })
+  .strict();
+
+export type MediaGrants = z.infer<typeof mediaGrantsSchema>;
+
+/** An omitted rule means everyone. Stated once so both sides agree. */
+const DEFAULT_RULE: SubscribeRule = { mode: "all" };
+
+function ruleAllows(rule: SubscribeRule | undefined, identity: string): boolean {
+  const r = rule ?? DEFAULT_RULE;
+  switch (r.mode) {
+    case "all":
+      return true;
+    case "none":
+      return false;
+    case "allow":
+      return r.identities.includes(identity);
+    case "deny":
+      return !r.identities.includes(identity);
+  }
+}
+
+/**
+ * May `consumer` receive `producer`? Two-sided, and deny wins.
+ *
+ * One-sided is not enough. If only the consumer's rule were consulted, a
+ * participant whose own token was minted generously could receive someone who
+ * had been explicitly walled off from them. So the producer's `visibleTo` is
+ * checked from the OWNER's stored grants, not from anything the consumer
+ * presents.
+ *
+ * **An unreadable owner is `false`.** If the producer's grants cannot be found,
+ * this refuses rather than falling through to the permissive default. A missing
+ * record is exactly the state a race or a partial failure produces, and in a
+ * room with an information barrier the safe reading of "I do not know" is "no".
+ * Note this differs deliberately from an ABSENT RULE on a record that WAS
+ * found, which means everyone.
+ */
+export function maySubscribe(input: {
+  consumerIdentity: string;
+  consumerGrants: MediaGrants;
+  producerIdentity: string;
+  /** `undefined` when the owner's record could not be read. */
+  ownerGrants: MediaGrants | undefined;
+}): boolean {
+  if (!input.consumerGrants.canSubscribe) return false;
+  // Nobody subscribes to themselves; asking is a client bug, not a denial.
+  if (input.consumerIdentity === input.producerIdentity) return false;
+  if (!input.ownerGrants) return false;
+
+  return (
+    ruleAllows(input.consumerGrants.subscribe, input.producerIdentity) &&
+    ruleAllows(input.ownerGrants.visibleTo, input.consumerIdentity)
+  );
+}
+
+/**
+ * `subscribeExempt` and `maxSubscriptions` are meaningless for a human and
+ * dangerous if mintable for one: exemption is what lets a recorder take every
+ * track, and a human with it can pull a thousand streams through a node.
+ * Checked at MINT time so a bad token never exists.
+ */
+export function grantsAreValidForKind(grants: MediaGrants, kind: ParticipantKind): true | string {
+  if (kind === "human" && grants.subscribeExempt) {
+    return "subscribeExempt may not be minted for a human participant";
+  }
+  if (!grants.canSubscribe && (grants.subscribe || grants.subscribeExempt || grants.maxSubscriptions)) {
+    return "subscribe rules are meaningless when canSubscribe is false";
+  }
+  if (!grants.canPublish && grants.publishKinds?.length) {
+    return "publishKinds is meaningless when canPublish is false";
+  }
+  return true;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * The contract between the backend, the media plane and every client.
+ *
+ * The root export is ISOMORPHIC: types, zod schemas, wire frames and the pure
+ * `maySubscribe` decision. It pulls in no `node:crypto`, no mediasoup, no DOM,
+ * so a browser SDK can import it.
+ *
+ * Signing and verifying live at `@tribe-nest/media-protocol/token`, which is
+ * Node-only. Keeping them apart is what stops importing a frame type from
+ * dragging crypto into a browser bundle.
+ *
+ * This package exists because `apps/backend` and `apps/media-server` may not
+ * import each other (there is a test), and six independently written phase
+ * plans each invented a different wire envelope for want of somewhere neutral
+ * to put one.
+ */
+export * from "./version";
+export * from "./errors";
+export * from "./errorSchema";
+export * from "./grants";
+export * from "./claims";
+export * from "./frames";
+export * from "./codecs";

package/src/token.ts

@@ -0,0 +1,237 @@
+import * as crypto from "crypto";
+import {
+  mediaControlClaimsSchema,
+  mediaJoinClaimsSchema,
+  type JoinTokenRejection,
+  type MediaControlClaims,
+  type MediaJoinClaims,
+  type VerifyResult,
+} from "./claims";
+import { grantsAreValidForKind } from "./grants";
+
+/**
+ * Ed25519-signed join and control tokens.
+ *
+ * ## Why asymmetric, when LiveKit uses a shared secret
+ *
+ * LiveKit signs with an API key + secret, which is HMAC: every party that can
+ * verify can also mint. Media nodes are public-facing, accept connections from
+ * anyone, and there are many of them. Under a shared secret, compromising ONE
+ * node yields the ability to mint a token for any room in the system -
+ * including a Mandantengespräch.
+ *
+ * So the backend holds a PRIVATE key and signs; nodes hold only PUBLIC keys and
+ * verify. A compromised node can verify and nothing else. The cost is a keypair
+ * instead of a string.
+ *
+ * ## Why this file is Node-only, and the package root is not
+ *
+ * Signing and verifying need `node:crypto`. The client SDK imports the wire
+ * frames and grant TYPES and never verifies anything - it only carries a token
+ * it was handed - so those live at the package root and stay isomorphic. This
+ * module is a separate entry point (`@tribe-nest/media-protocol/token`) so
+ * importing a frame type cannot drag `crypto` into a browser bundle.
+ *
+ * ## Why verification is PURE
+ *
+ * No I/O, no clock unless you pass one, no Redis. Replay defence needs state
+ * and therefore lives in the media server (`auth/replayGuard`), composed
+ * around this. Keeping the crypto and claim checks free of state is what lets
+ * the golden vectors pin exactly one code path on both sides of the wire.
+ */
+
+export type PublicKeyring = Record<string, string>;
+export type PrivateKeyring = Record<string, string>;
+
+const ALG = "EdDSA";
+const b64u = (b: Buffer) => b.toString("base64url");
+const fromB64u = (s: string) => Buffer.from(s, "base64url");
+
+/** Default ceiling on `exp - iat`. A join ticket, not a session. */
+export const MAX_TOKEN_TTL_SECONDS = 15 * 60;
+
+function encodeSegment(value: unknown): string {
+  return b64u(Buffer.from(JSON.stringify(value), "utf8"));
+}
+
+function signCompact(privateKeyPem: string, kid: string, payload: unknown): string {
+  const header = encodeSegment({ alg: ALG, typ: "JWT", kid });
+  const body = encodeSegment(payload);
+  const signingInput = `${header}.${body}`;
+  // For Ed25519 the digest algorithm is null: the curve prescribes it.
+  const signature = crypto.sign(null, Buffer.from(signingInput, "utf8"), privateKeyPem);
+  return `${signingInput}.${b64u(signature)}`;
+}
+
+export function signJoinToken(privateKeyPem: string, kid: string, claims: MediaJoinClaims): string {
+  const parsed = mediaJoinClaimsSchema.parse(claims);
+
+  // Mint-time refusals. A token that should never exist is better stopped here
+  // than relied upon to be refused by every future verifier.
+  const grantCheck = grantsAreValidForKind(parsed.grants, parsed.kind);
+  if (grantCheck !== true) throw new Error(`refusing to mint: ${grantCheck}`);
+  if (parsed.exp <= parsed.iat) throw new Error("refusing to mint: exp is not after iat");
+  if (parsed.exp - parsed.iat > MAX_TOKEN_TTL_SECONDS) {
+    throw new Error(`refusing to mint: ttl exceeds ${MAX_TOKEN_TTL_SECONDS}s`);
+  }
+  if (parsed.transport !== "webrtc" && parsed.kind === "human") {
+    throw new Error("refusing to mint: a human participant may only use a webrtc transport");
+  }
+
+  return signCompact(privateKeyPem, kid, parsed);
+}
+
+export function signControlToken(privateKeyPem: string, kid: string, claims: MediaControlClaims): string {
+  const parsed = mediaControlClaimsSchema.parse(claims);
+  if (parsed.exp <= parsed.iat) throw new Error("refusing to mint: exp is not after iat");
+  return signCompact(privateKeyPem, kid, parsed);
+}
+
+type VerifyArgs = {
+  token: string;
+  keys: PublicKeyring;
+  issuer: string;
+  maxTtlSeconds?: number;
+  /** Seconds since epoch. Injected so vectors are deterministic. */
+  nowSeconds?: number;
+  skewSeconds?: number;
+  /** When given, the token's room must match. */
+  expectedRoom?: string;
+};
+
+function verifyCompact(
+  args: VerifyArgs,
+  audience: "media" | "control",
+): { ok: true; payload: unknown; kid: string } | { ok: false; reason: JoinTokenRejection } {
+  const parts = args.token.split(".");
+  if (parts.length !== 3) return { ok: false, reason: "malformed" };
+  const [headerSeg, bodySeg, sigSeg] = parts as [string, string, string];
+
+  let header: { alg?: unknown; kid?: unknown };
+  try {
+    header = JSON.parse(fromB64u(headerSeg).toString("utf8"));
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+
+  // Only ever EdDSA. Accepting whatever the token names is the classic JWT
+  // algorithm-confusion hole, and `none` is the worst case of it.
+  if (header.alg !== ALG) return { ok: false, reason: "malformed" };
+  if (typeof header.kid !== "string" || !header.kid) return { ok: false, reason: "malformed" };
+
+  const publicKeyPem = args.keys[header.kid];
+  if (!publicKeyPem) return { ok: false, reason: "unknown_kid" };
+
+  // Signature BEFORE claims: never parse a payload that has not been shown to
+  // come from us.
+  let signatureValid = false;
+  try {
+    signatureValid = crypto.verify(
+      null,
+      Buffer.from(`${headerSeg}.${bodySeg}`, "utf8"),
+      publicKeyPem,
+      fromB64u(sigSeg),
+    );
+  } catch {
+    return { ok: false, reason: "bad_signature" };
+  }
+  if (!signatureValid) return { ok: false, reason: "bad_signature" };
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(fromB64u(bodySeg).toString("utf8"));
+  } catch {
+    return { ok: false, reason: "malformed" };
+  }
+
+  const asRecord = payload as Record<string, unknown>;
+  if (asRecord?.aud !== audience) return { ok: false, reason: "wrong_audience" };
+  if (asRecord?.iss !== args.issuer) return { ok: false, reason: "wrong_issuer" };
+
+  return { ok: true, payload, kid: header.kid };
+}
+
+function checkTiming(
+  claims: { iat: number; exp: number; nbf?: number },
+  args: VerifyArgs,
+): JoinTokenRejection | null {
+  const now = args.nowSeconds ?? Math.floor(Date.now() / 1000);
+  const skew = args.skewSeconds ?? 30;
+  const maxTtl = args.maxTtlSeconds ?? MAX_TOKEN_TTL_SECONDS;
+
+  if (claims.exp + skew <= now) return "expired";
+  if (claims.nbf !== undefined && claims.nbf - skew > now) return "not_yet_valid";
+  // A long-lived token is a stolen credential with a long life, so the ceiling
+  // is enforced at VERIFY too - not only at mint, which a compromised minter
+  // would simply skip.
+  if (claims.exp - claims.iat > maxTtl) return "ttl_too_long";
+  return null;
+}
+
+export function verifyJoinToken(args: VerifyArgs): VerifyResult<MediaJoinClaims> {
+  const base = verifyCompact(args, "media");
+  if (!base.ok) return base;
+
+  const parsed = mediaJoinClaimsSchema.safeParse(base.payload);
+  // `.strict()` fires here. A token carrying `subscribeOnly` instead of
+  // `subscribe` is rejected outright rather than read as "no rule, so
+  // everyone" - which is how an information barrier fails open.
+  if (!parsed.success) return { ok: false, reason: "bad_claims" };
+
+  const timing = checkTiming(parsed.data, args);
+  if (timing) return { ok: false, reason: timing };
+
+  if (args.expectedRoom !== undefined && parsed.data.room !== args.expectedRoom) {
+    return { ok: false, reason: "wrong_room" };
+  }
+  if (grantsAreValidForKind(parsed.data.grants, parsed.data.kind) !== true) {
+    return { ok: false, reason: "bad_claims" };
+  }
+
+  return { ok: true, claims: parsed.data, kid: base.kid };
+}
+
+export function verifyControlToken(args: VerifyArgs): VerifyResult<MediaControlClaims> {
+  const base = verifyCompact(args, "control");
+  if (!base.ok) return base;
+
+  const parsed = mediaControlClaimsSchema.safeParse(base.payload);
+  if (!parsed.success) return { ok: false, reason: "bad_claims" };
+
+  const timing = checkTiming(parsed.data, args);
+  if (timing) return { ok: false, reason: timing };
+
+  return { ok: true, claims: parsed.data, kid: base.kid };
+}
+
+/**
+ * Boot guard for a media node.
+ *
+ * A node must hold verification keys ONLY. If a private key reaches a node's
+ * keyring - a copy-paste, a shared secrets bundle - that node can mint, and the
+ * whole reason for the asymmetric split is gone silently. This makes it a
+ * refusal to start rather than a latent capability.
+ */
+export function assertPublicKeyringIsPublicOnly(keys: PublicKeyring): void {
+  for (const [kid, pem] of Object.entries(keys)) {
+    if (/PRIVATE KEY/.test(pem)) {
+      throw new Error(
+        `media token keyring "${kid}" contains a PRIVATE key. Nodes verify and must never be able to mint.`,
+      );
+    }
+    try {
+      crypto.createPublicKey(pem);
+    } catch {
+      throw new Error(`media token keyring "${kid}" is not a readable public key`);
+    }
+  }
+}
+
+/** Convenience for tooling and tests; not used at runtime. */
+export function generateKeypair(): { publicKey: string; privateKey: string } {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+  return {
+    publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(),
+    privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+  };
+}

package/src/version.ts

@@ -0,0 +1,8 @@
+/**
+ * Bumped when a frame shape changes in a way an older peer cannot parse.
+ *
+ * The client sends it on connect and a node refuses a mismatch outright, rather
+ * than negotiating: a half-understood signalling session fails later, somewhere
+ * else, and looks like a media bug.
+ */
+export const MEDIA_PROTOCOL_VERSION = 1 as const;