@tribe-nest/media-protocol 1.0.0

package/build/grants.js

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mediaGrantsSchema = exports.publishSourceSchema = exports.publishKindSchema = exports.transportKindSchema = exports.participantKindSchema = exports.subscribeRuleSchema = void 0;
+exports.requiredPublishKind = requiredPublishKind;
+exports.mayPublish = mayPublish;
+exports.maySubscribe = maySubscribe;
+exports.grantsAreValidForKind = grantsAreValidForKind;
+const zod_1 = require("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.
+ */
+exports.subscribeRuleSchema = zod_1.z.discriminatedUnion("mode", [
+    zod_1.z.object({ mode: zod_1.z.literal("all") }).strict(),
+    zod_1.z.object({ mode: zod_1.z.literal("none") }).strict(),
+    zod_1.z.object({ mode: zod_1.z.literal("allow"), identities: zod_1.z.array(zod_1.z.string()).max(500) }).strict(),
+    zod_1.z.object({ mode: zod_1.z.literal("deny"), identities: zod_1.z.array(zod_1.z.string()).max(500) }).strict(),
+]);
+exports.participantKindSchema = zod_1.z.enum(["human", "agent", "egress", "sip", "ingress"]);
+/**
+ * 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.
+ */
+exports.transportKindSchema = zod_1.z.enum(["webrtc", "plain", "pipe"]);
+/**
+ * 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.
+ */
+exports.publishKindSchema = zod_1.z.enum(["audio", "video", "screen"]);
+/** The sources the browser SDK publishes with. Others are legal on the wire. */
+exports.publishSourceSchema = zod_1.z.enum(["microphone", "camera", "screen"]);
+const SOURCE_KINDS = {
+    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 = {
+    microphone: ["audio"],
+    camera: ["video"],
+    screen: ["audio", "video"],
+};
+/** Which grant a publish needs, from what it declares and what it carries. */
+function requiredPublishKind(source, trackKind) {
+    const declared = source ? SOURCE_KINDS[source] : 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].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.
+ */
+function mayPublish(grants, input) {
+    if (!grants?.canPublish)
+        return false;
+    if (!grants.publishKinds)
+        return true;
+    return grants.publishKinds.includes(requiredPublishKind(input.source, input.trackKind));
+}
+exports.mediaGrantsSchema = zod_1.z
+    .object({
+    canPublish: zod_1.z.boolean(),
+    canSubscribe: zod_1.z.boolean(),
+    canPublishData: zod_1.z.boolean(),
+    /** Who I may receive. Omitted means `{ mode: "all" }`. */
+    subscribe: exports.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: exports.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: zod_1.z.array(exports.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: zod_1.z.boolean().optional(),
+    /** Hard ceiling on concurrent consumers, for a non-human participant. */
+    maxSubscriptions: zod_1.z.number().int().positive().max(5000).optional(),
+})
+    .strict();
+/** An omitted rule means everyone. Stated once so both sides agree. */
+const DEFAULT_RULE = { mode: "all" };
+function ruleAllows(rule, identity) {
+    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.
+ */
+function maySubscribe(input) {
+    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.
+ */
+function grantsAreValidForKind(grants, kind) {
+    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;
+}
+//# sourceMappingURL=grants.js.map

package/build/grants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grants.js","sourceRoot":"","sources":["../src/grants.ts"],"names":[],"mappings":"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"}

package/build/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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";
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}

package/build/index.js

@@ -0,0 +1,40 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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.
+ */
+__exportStar(require("./version"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./errorSchema"), exports);
+__exportStar(require("./grants"), exports);
+__exportStar(require("./claims"), exports);
+__exportStar(require("./frames"), exports);
+__exportStar(require("./codecs"), exports);
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;GAeG;AACH,4CAA0B;AAC1B,2CAAyB;AACzB,gDAA8B;AAC9B,2CAAyB;AACzB,2CAAyB;AACzB,2CAAyB;AACzB,2CAAyB"}

package/build/mp-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"
+        }
+    ]
+}