@tribe-nest/media-protocol 1.0.0

package/build/_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/build/claims.d.ts

@@ -0,0 +1,327 @@
+import { z } from "zod";
+/**
+ * The join token's claims: the whole authorization decision, made once by the
+ * backend and carried to a media plane that never asks it anything.
+ *
+ * Names here were contested by the parallel phase plans; each disagreement is
+ * resolved once, in this file, and everything else imports it.
+ */
+/**
+ * The longest display name a join token may carry.
+ *
+ * Exported because it is a MINT-TIME refusal, not a preference: `signJoinToken`
+ * hard-parses these claims, so a caller that builds a name out of stored text
+ * and does not clamp it throws instead of minting. Every such caller has to
+ * know the bound, and a caller that hard-codes 200 is a caller that will not
+ * follow this number if it ever moves.
+ */
+export declare const MEDIA_PARTICIPANT_NAME_MAX_LENGTH = 200;
+/**
+ * A display name cut to what a token may carry.
+ *
+ * Lives HERE, beside the bound it enforces, rather than in each surface that
+ * mints. Two reasons, and the second is the one that matters.
+ *
+ * A minting surface builds the name out of stored text (a buyer's name off a
+ * booking, a seat's display name off a roster) and cannot promise a length, so
+ * every one of them needs this. And a surface that instead compared against the
+ * exported NUMBER would go silently unclamped the moment it read a stale build
+ * of this package: `value.length > undefined` is `false`, so the clamp
+ * evaporates and the failure only shows up as a 500 from `signJoinToken` in
+ * production. A missing FUNCTION throws on the first call instead.
+ *
+ * Truncation rather than refusal is deliberate. A name is a label on a tile,
+ * and no call should fail to open over one.
+ */
+export declare function clampParticipantName(value: string): string;
+/**
+ * `iss` IS the instance id (`legal-de`, `main`), not a service name.
+ *
+ * One plan proposed `iss: "tribenest-backend"` with the instance in a separate
+ * `inst` claim. That displaces the one value a verifier actually checks, and a
+ * legal-de token would then verify happily on the main instance - which is the
+ * whole reason instances are separate.
+ */
+export declare const mediaJoinClaimsSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    iss: z.ZodString;
+    aud: z.ZodLiteral<"media">;
+    room: z.ZodString;
+    /** `identity`, not `sub`: it is a first-class concept the barrier rules name. */
+    identity: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    /** Top level, NOT inside grants - it decides what may be minted at all. */
+    kind: z.ZodEnum<["human", "agent", "egress", "sip", "ingress"]>;
+    /** Top level. Transport authority is not media authority. */
+    transport: z.ZodEnum<["webrtc", "plain", "pipe"]>;
+    grants: z.ZodObject<{
+        canPublish: z.ZodBoolean;
+        canSubscribe: z.ZodBoolean;
+        canPublishData: z.ZodBoolean;
+        subscribe: z.ZodOptional<z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
+            mode: z.ZodLiteral<"all">;
+        }, "strict", z.ZodTypeAny, {
+            mode: "all";
+        }, {
+            mode: "all";
+        }>, z.ZodObject<{
+            mode: z.ZodLiteral<"none">;
+        }, "strict", z.ZodTypeAny, {
+            mode: "none";
+        }, {
+            mode: "none";
+        }>, z.ZodObject<{
+            mode: z.ZodLiteral<"allow">;
+            identities: z.ZodArray<z.ZodString, "many">;
+        }, "strict", z.ZodTypeAny, {
+            mode: "allow";
+            identities: string[];
+        }, {
+            mode: "allow";
+            identities: string[];
+        }>, z.ZodObject<{
+            mode: z.ZodLiteral<"deny">;
+            identities: z.ZodArray<z.ZodString, "many">;
+        }, "strict", z.ZodTypeAny, {
+            mode: "deny";
+            identities: string[];
+        }, {
+            mode: "deny";
+            identities: string[];
+        }>]>>;
+        visibleTo: z.ZodOptional<z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
+            mode: z.ZodLiteral<"all">;
+        }, "strict", z.ZodTypeAny, {
+            mode: "all";
+        }, {
+            mode: "all";
+        }>, z.ZodObject<{
+            mode: z.ZodLiteral<"none">;
+        }, "strict", z.ZodTypeAny, {
+            mode: "none";
+        }, {
+            mode: "none";
+        }>, z.ZodObject<{
+            mode: z.ZodLiteral<"allow">;
+            identities: z.ZodArray<z.ZodString, "many">;
+        }, "strict", z.ZodTypeAny, {
+            mode: "allow";
+            identities: string[];
+        }, {
+            mode: "allow";
+            identities: string[];
+        }>, z.ZodObject<{
+            mode: z.ZodLiteral<"deny">;
+            identities: z.ZodArray<z.ZodString, "many">;
+        }, "strict", z.ZodTypeAny, {
+            mode: "deny";
+            identities: string[];
+        }, {
+            mode: "deny";
+            identities: string[];
+        }>]>>;
+        publishKinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["audio", "video", "screen"]>, "many">>;
+        subscribeExempt: z.ZodOptional<z.ZodBoolean>;
+        maxSubscriptions: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        canPublish: boolean;
+        canSubscribe: boolean;
+        canPublishData: boolean;
+        subscribe?: {
+            mode: "all";
+        } | {
+            mode: "none";
+        } | {
+            mode: "allow";
+            identities: string[];
+        } | {
+            mode: "deny";
+            identities: string[];
+        } | undefined;
+        visibleTo?: {
+            mode: "all";
+        } | {
+            mode: "none";
+        } | {
+            mode: "allow";
+            identities: string[];
+        } | {
+            mode: "deny";
+            identities: string[];
+        } | undefined;
+        publishKinds?: ("audio" | "video" | "screen")[] | undefined;
+        subscribeExempt?: boolean | undefined;
+        maxSubscriptions?: number | undefined;
+    }, {
+        canPublish: boolean;
+        canSubscribe: boolean;
+        canPublishData: boolean;
+        subscribe?: {
+            mode: "all";
+        } | {
+            mode: "none";
+        } | {
+            mode: "allow";
+            identities: string[];
+        } | {
+            mode: "deny";
+            identities: string[];
+        } | undefined;
+        visibleTo?: {
+            mode: "all";
+        } | {
+            mode: "none";
+        } | {
+            mode: "allow";
+            identities: string[];
+        } | {
+            mode: "deny";
+            identities: string[];
+        } | undefined;
+        publishKinds?: ("audio" | "video" | "screen")[] | undefined;
+        subscribeExempt?: boolean | undefined;
+        maxSubscriptions?: number | undefined;
+    }>;
+    jti: z.ZodString;
+    iat: z.ZodNumber;
+    nbf: z.ZodOptional<z.ZodNumber>;
+    exp: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    v: 1;
+    iss: string;
+    aud: "media";
+    room: string;
+    identity: string;
+    kind: "human" | "agent" | "egress" | "sip" | "ingress";
+    transport: "webrtc" | "plain" | "pipe";
+    grants: {
+        canPublish: boolean;
+        canSubscribe: boolean;
+        canPublishData: boolean;
+        subscribe?: {
+            mode: "all";
+        } | {
+            mode: "none";
+        } | {
+            mode: "allow";
+            identities: string[];
+        } | {
+            mode: "deny";
+            identities: string[];
+        } | undefined;
+        visibleTo?: {
+            mode: "all";
+        } | {
+            mode: "none";
+        } | {
+            mode: "allow";
+            identities: string[];
+        } | {
+            mode: "deny";
+            identities: string[];
+        } | undefined;
+        publishKinds?: ("audio" | "video" | "screen")[] | undefined;
+        subscribeExempt?: boolean | undefined;
+        maxSubscriptions?: number | undefined;
+    };
+    jti: string;
+    iat: number;
+    exp: number;
+    name?: string | undefined;
+    nbf?: number | undefined;
+}, {
+    v: 1;
+    iss: string;
+    aud: "media";
+    room: string;
+    identity: string;
+    kind: "human" | "agent" | "egress" | "sip" | "ingress";
+    transport: "webrtc" | "plain" | "pipe";
+    grants: {
+        canPublish: boolean;
+        canSubscribe: boolean;
+        canPublishData: boolean;
+        subscribe?: {
+            mode: "all";
+        } | {
+            mode: "none";
+        } | {
+            mode: "allow";
+            identities: string[];
+        } | {
+            mode: "deny";
+            identities: string[];
+        } | undefined;
+        visibleTo?: {
+            mode: "all";
+        } | {
+            mode: "none";
+        } | {
+            mode: "allow";
+            identities: string[];
+        } | {
+            mode: "deny";
+            identities: string[];
+        } | undefined;
+        publishKinds?: ("audio" | "video" | "screen")[] | undefined;
+        subscribeExempt?: boolean | undefined;
+        maxSubscriptions?: number | undefined;
+    };
+    jti: string;
+    iat: number;
+    exp: number;
+    name?: string | undefined;
+    nbf?: number | undefined;
+}>;
+export type MediaJoinClaims = z.infer<typeof mediaJoinClaimsSchema>;
+/**
+ * Server-to-server control calls (create room, end room, attach an agent).
+ *
+ * A separate audience so a join token can never be replayed as a control call.
+ * It carries no room, identity, kind, transport or grants: a control caller is
+ * not a participant, and giving it participant-shaped claims invites code that
+ * treats it as one.
+ */
+export declare const mediaControlClaimsSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    iss: z.ZodString;
+    aud: z.ZodLiteral<"control">;
+    jti: z.ZodString;
+    iat: z.ZodNumber;
+    nbf: z.ZodOptional<z.ZodNumber>;
+    exp: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    v: 1;
+    iss: string;
+    aud: "control";
+    jti: string;
+    iat: number;
+    exp: number;
+    nbf?: number | undefined;
+}, {
+    v: 1;
+    iss: string;
+    aud: "control";
+    jti: string;
+    iat: number;
+    exp: number;
+    nbf?: number | undefined;
+}>;
+export type MediaControlClaims = z.infer<typeof mediaControlClaimsSchema>;
+/**
+ * Why a token was refused.
+ *
+ * Deliberately granular for the SERVER's logs and deliberately NOT returned to
+ * the client, which gets `unauthorized` and nothing else. Telling a caller
+ * whether the signature or the room was wrong is an oracle.
+ */
+export type JoinTokenRejection = "malformed" | "unknown_kid" | "bad_signature" | "expired" | "not_yet_valid" | "ttl_too_long" | "wrong_audience" | "wrong_issuer" | "wrong_room" | "bad_claims";
+export type VerifyResult<T> = {
+    ok: true;
+    claims: T;
+    kid: string;
+} | {
+    ok: false;
+    reason: JoinTokenRejection;
+};
+//# sourceMappingURL=claims.d.ts.map

package/build/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../src/claims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAErD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;IAM9B,iFAAiF;;;IAGjF,2EAA2E;;IAE3E,6DAA6D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQtD,CAAC;AAEZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;EAU1B,CAAC;AAEZ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,aAAa,GACb,eAAe,GACf,SAAS,GACT,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,cAAc,GACd,YAAY,GACZ,YAAY,CAAC;AAEjB,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,CAAC,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC"}

package/build/claims.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mediaControlClaimsSchema = exports.mediaJoinClaimsSchema = exports.MEDIA_PARTICIPANT_NAME_MAX_LENGTH = void 0;
+exports.clampParticipantName = clampParticipantName;
+const zod_1 = require("zod");
+const grants_1 = require("./grants");
+/**
+ * The join token's claims: the whole authorization decision, made once by the
+ * backend and carried to a media plane that never asks it anything.
+ *
+ * Names here were contested by the parallel phase plans; each disagreement is
+ * resolved once, in this file, and everything else imports it.
+ */
+/**
+ * The longest display name a join token may carry.
+ *
+ * Exported because it is a MINT-TIME refusal, not a preference: `signJoinToken`
+ * hard-parses these claims, so a caller that builds a name out of stored text
+ * and does not clamp it throws instead of minting. Every such caller has to
+ * know the bound, and a caller that hard-codes 200 is a caller that will not
+ * follow this number if it ever moves.
+ */
+exports.MEDIA_PARTICIPANT_NAME_MAX_LENGTH = 200;
+/**
+ * A display name cut to what a token may carry.
+ *
+ * Lives HERE, beside the bound it enforces, rather than in each surface that
+ * mints. Two reasons, and the second is the one that matters.
+ *
+ * A minting surface builds the name out of stored text (a buyer's name off a
+ * booking, a seat's display name off a roster) and cannot promise a length, so
+ * every one of them needs this. And a surface that instead compared against the
+ * exported NUMBER would go silently unclamped the moment it read a stale build
+ * of this package: `value.length > undefined` is `false`, so the clamp
+ * evaporates and the failure only shows up as a 500 from `signJoinToken` in
+ * production. A missing FUNCTION throws on the first call instead.
+ *
+ * Truncation rather than refusal is deliberate. A name is a label on a tile,
+ * and no call should fail to open over one.
+ */
+function clampParticipantName(value) {
+    return value.length > exports.MEDIA_PARTICIPANT_NAME_MAX_LENGTH ? value.slice(0, exports.MEDIA_PARTICIPANT_NAME_MAX_LENGTH) : value;
+}
+/**
+ * `iss` IS the instance id (`legal-de`, `main`), not a service name.
+ *
+ * One plan proposed `iss: "tribenest-backend"` with the instance in a separate
+ * `inst` claim. That displaces the one value a verifier actually checks, and a
+ * legal-de token would then verify happily on the main instance - which is the
+ * whole reason instances are separate.
+ */
+exports.mediaJoinClaimsSchema = zod_1.z
+    .object({
+    v: zod_1.z.literal(1),
+    iss: zod_1.z.string().min(1),
+    aud: zod_1.z.literal("media"),
+    room: zod_1.z.string().min(1).max(200),
+    /** `identity`, not `sub`: it is a first-class concept the barrier rules name. */
+    identity: zod_1.z.string().min(1).max(200),
+    name: zod_1.z.string().max(exports.MEDIA_PARTICIPANT_NAME_MAX_LENGTH).optional(),
+    /** Top level, NOT inside grants - it decides what may be minted at all. */
+    kind: grants_1.participantKindSchema,
+    /** Top level. Transport authority is not media authority. */
+    transport: grants_1.transportKindSchema,
+    grants: grants_1.mediaGrantsSchema,
+    jti: zod_1.z.string().min(8),
+    iat: zod_1.z.number().int().positive(),
+    nbf: zod_1.z.number().int().positive().optional(),
+    exp: zod_1.z.number().int().positive(),
+})
+    .strict();
+/**
+ * Server-to-server control calls (create room, end room, attach an agent).
+ *
+ * A separate audience so a join token can never be replayed as a control call.
+ * It carries no room, identity, kind, transport or grants: a control caller is
+ * not a participant, and giving it participant-shaped claims invites code that
+ * treats it as one.
+ */
+exports.mediaControlClaimsSchema = zod_1.z
+    .object({
+    v: zod_1.z.literal(1),
+    iss: zod_1.z.string().min(1),
+    aud: zod_1.z.literal("control"),
+    jti: zod_1.z.string().min(8),
+    iat: zod_1.z.number().int().positive(),
+    nbf: zod_1.z.number().int().positive().optional(),
+    exp: zod_1.z.number().int().positive(),
+})
+    .strict();
+//# sourceMappingURL=claims.js.map

package/build/claims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.js","sourceRoot":"","sources":["../src/claims.ts"],"names":[],"mappings":";;;AAuCA,oDAEC;AAzCD,6BAAwB;AACxB,qCAAyF;AAEzF;;;;;;GAMG;AAEH;;;;;;;;GAQG;AACU,QAAA,iCAAiC,GAAG,GAAG,CAAC;AAErD;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,oBAAoB,CAAC,KAAa;IAChD,OAAO,KAAK,CAAC,MAAM,GAAG,yCAAiC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,yCAAiC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACtH,CAAC;AAED;;;;;;;GAOG;AACU,QAAA,qBAAqB,GAAG,OAAC;KACnC,MAAM,CAAC;IACN,CAAC,EAAE,OAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACf,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtB,GAAG,EAAE,OAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACvB,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAChC,iFAAiF;IACjF,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACpC,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,yCAAiC,CAAC,CAAC,QAAQ,EAAE;IAClE,2EAA2E;IAC3E,IAAI,EAAE,8BAAqB;IAC3B,6DAA6D;IAC7D,SAAS,EAAE,4BAAmB;IAC9B,MAAM,EAAE,0BAAiB;IACzB,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtB,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAChC,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC3C,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC;KACD,MAAM,EAAE,CAAC;AAIZ;;;;;;;GAOG;AACU,QAAA,wBAAwB,GAAG,OAAC;KACtC,MAAM,CAAC;IACN,CAAC,EAAE,OAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACf,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtB,GAAG,EAAE,OAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IACzB,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtB,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAChC,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC3C,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC;KACD,MAAM,EAAE,CAAC"}

package/build/codecs.d.ts

@@ -0,0 +1,102 @@
+/**
+ * THE codec list. Every Router in the fleet is created from this array and no
+ * other, and every server-side participant derives what it can receive FROM it.
+ *
+ * ## Why it is pinned rather than left to mediasoup's defaults
+ *
+ * Two Routers that disagree about codecs cannot be piped. `pipeToRouter` and
+ * the hand-rolled equivalent in the node's `pipe.ts` both require the receiving
+ * Router to be able to consume the producer, and "able" is decided by this
+ * list. A node booted from a different build with one extra codec still pipes
+ * fine until the day a client happens to negotiate that codec, and then exactly
+ * one leg of one room goes silent, which reads as a network fault.
+ *
+ * So the list lives in one place and every Router in the fleet is created from
+ * it. A change here is a fleet-wide change and a deploy that mixes versions is
+ * a deploy that mixes codec sets, which is why `DEPLOYMENT.md` says drain
+ * before upgrade rather than rolling.
+ *
+ * ## Why it lives in the PROTOCOL package
+ *
+ * The node is not the only party that has to agree. A room agent, the SIP
+ * gateway and the RTMP ingress are participants, not nodes: each one has to
+ * declare RTP capabilities on `consume`, each one runs in its own app, and none
+ * of them may import `apps/media-server`. Every phase that needed this list
+ * from outside the node had exactly one alternative, which is to write a second
+ * copy - and a second copy is the failure the pinning exists to prevent. The
+ * earlier agent plan proved it: its contract test compared two hand-written
+ * lists to EACH OTHER and never to this one, so both could drift together and
+ * stay green.
+ *
+ * Codec agreement is a wire contract between parties that cannot import each
+ * other, which is the same reason the frames and the claims are here.
+ *
+ * ## Zero mediasoup, deliberately
+ *
+ * The types below are declared structurally rather than imported from
+ * mediasoup, because this package is isomorphic and a browser must be able to
+ * import a frame type without pulling in a C++ addon. `apps/media-server`
+ * re-exports these values through explicitly mediasoup-typed bindings, so if
+ * the two shapes ever diverge the node fails to COMPILE rather than failing to
+ * pipe at three in the morning.
+ *
+ * ## What is in it, and what is deliberately not
+ *
+ * Opus for audio, because it is the only audio codec every browser publishes
+ * and the only one worth transcoding to for SIP and for agents.
+ *
+ * VP8 and H.264 for video. VP8 is universal and simple; H.264 is what Safari
+ * and every hardware encoder produce, and its absence is not a quality loss but
+ * a "video does not work on iPhone" bug. Both are listed with the RTCP feedback
+ * mediasoup needs for keyframes and bandwidth estimation: `nack`, `pli` and
+ * `transport-cc`. Drop `pli` and a keyframe request has no wire representation,
+ * so every active-speaker switch shows macroblocks until the encoder happens to
+ * send an IDR on its own schedule.
+ *
+ * VP9 and AV1 are deliberately absent. Both are real wins and both are a
+ * separate decision with a measurement behind it: SVC changes what
+ * `setPreferredLayers` means, and adding a codec that only some clients
+ * negotiate widens the "one leg is silent" surface above.
+ */
+export type MediaKind = "audio" | "video";
+export type MediaRtcpFeedback = {
+    type: string;
+    parameter?: string;
+};
+/** Structurally identical to mediasoup's `RouterRtpCodecCapability`. */
+export type MediaCodecCapability = {
+    kind: MediaKind;
+    mimeType: string;
+    clockRate: number;
+    channels?: number;
+    parameters?: Record<string, unknown>;
+    rtcpFeedback?: MediaRtcpFeedback[];
+    preferredPayloadType?: number;
+};
+/** Structurally identical to mediasoup's `RtpCapabilities`. */
+export type MediaRtpCapabilities = {
+    codecs: Array<MediaCodecCapability & {
+        preferredPayloadType: number;
+    }>;
+    /**
+     * Always empty, and typed as the empty tuple rather than an array of some
+     * element type.
+     *
+     * A server-side participant declares no header extensions: it reads the RTP
+     * header itself and wants nothing negotiated on top of it. Typing it this way
+     * also means this package never has to describe mediasoup's header-extension
+     * union in order for the node's mediasoup-typed re-export to stay assignable.
+     */
+    headerExtensions: [];
+};
+export declare const MEDIA_CODECS: MediaCodecCapability[];
+/**
+ * The audio half, for a participant that has no video at all.
+ *
+ * DERIVED, never written beside the list above. A hand-written copy for agents
+ * and SIP was compared against another hand-written copy in an earlier plan and
+ * never against this list, which is precisely the drift the pinning exists to
+ * prevent: both copies agree with each other and neither agrees with the fleet.
+ */
+export declare function audioOnlyCapabilities(codecs?: MediaCodecCapability[]): MediaRtpCapabilities;
+//# sourceMappingURL=codecs.d.ts.map

package/build/codecs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.d.ts","sourceRoot":"","sources":["../src/codecs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAE1C,MAAM,MAAM,iBAAiB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE,wEAAwE;AACxE,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACnC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF,+DAA+D;AAC/D,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,KAAK,CAAC,oBAAoB,GAAG;QAAE,oBAAoB,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvE;;;;;;;;OAQG;IACH,gBAAgB,EAAE,EAAE,CAAC;CACtB,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,oBAAoB,EA8C9C,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,GAAE,oBAAoB,EAAiB,GAAG,oBAAoB,CAiBzG"}