@volter/twin-livekit 0.1.0

package/src/livekit-types.ts

@@ -0,0 +1,211 @@
+export type LiveKitRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  root?: string;
+  readOnly?: boolean;
+  occurredAt?: string;
+  /** Bearer access token (LiveKit JWT). When `apiKeys` is set, auth is enforced. */
+  authToken?: string;
+  /** apiKey -> apiSecret map. Presence enables JWT grant enforcement (vendor-faithful auth). */
+  apiKeys?: Record<string, string>;
+  /** Now (unix seconds) for token exp/nbf checks; defaults to occurredAt. */
+  nowSeconds?: number;
+  /** Max simultaneously-active egress jobs before quota_capacity is returned. */
+  maxActiveEgress?: number;
+};
+
+export type LiveKitResponse = { status: number; body: unknown };
+
+export type LiveKitRoom = {
+  id: string;
+  sid: string;
+  name: string;
+  emptyTimeout: number;
+  departureTimeout: number;
+  maxParticipants: number;
+  metadata: string;
+  creationTime: string;
+  creationTimeMs: string;
+  numParticipants: number;
+  activeRecording: boolean;
+  generation: number;
+  deleted?: boolean;
+};
+
+export type LiveKitTrack = {
+  sid: string;
+  name: string;
+  type: number;
+  muted: boolean;
+  width: number;
+  height: number;
+  source: number;
+  mimeType: string;
+};
+
+export type LiveKitParticipantPermission = {
+  canSubscribe: boolean;
+  canPublish: boolean;
+  canPublishData: boolean;
+  canUpdateMetadata: boolean;
+  hidden: boolean;
+  canSubscribeMetrics: boolean;
+};
+
+export type LiveKitParticipant = {
+  id: string;
+  sid: string;
+  roomName: string;
+  identity: string;
+  state: number;
+  tracks: LiveKitTrack[];
+  metadata: string;
+  joinedAt: string;
+  joinedAtMs: string;
+  name: string;
+  version: number;
+  isPublisher: boolean;
+  kind: number;
+  attributes: Record<string, string>;
+  permission: LiveKitParticipantPermission;
+  /** track sids this participant is subscribed to (UpdateSubscriptions) */
+  subscribedTracks: string[];
+};
+
+export type EgressRequestCase = 'roomComposite' | 'web' | 'participant' | 'trackComposite' | 'track';
+
+export type LiveKitEgress = {
+  id: string;
+  egressId: string;
+  roomId: string;
+  roomName: string;
+  sourceType: number;
+  status: number;
+  startedAt: string;
+  endedAt: string;
+  updatedAt: string;
+  details: string;
+  error: string;
+  errorCode: number;
+  layout: string;
+  requestCase: EgressRequestCase;
+  streamUrls: string[];
+  fileOutputs: unknown[];
+  streamOutputs: unknown[];
+  segmentOutputs: unknown[];
+  imageOutputs: unknown[];
+  request: Record<string, unknown>;
+};
+
+export type LiveKitIngress = {
+  id: string;
+  ingressId: string;
+  name: string;
+  streamKey: string;
+  url: string;
+  inputType: number;
+  bypassTranscoding: boolean;
+  enableTranscoding: boolean;
+  roomName: string;
+  participantIdentity: string;
+  participantName: string;
+  participantMetadata: string;
+  reusable: boolean;
+  enabled: boolean;
+  audio?: Record<string, unknown>;
+  video?: Record<string, unknown>;
+  state: {
+    status: number;
+    error: string;
+    roomId: string;
+    startedAt: string;
+    endedAt: string;
+    updatedAt: string;
+    resourceId: string;
+  };
+  deleted?: boolean;
+};
+
+export type LiveKitSIPInboundTrunk = {
+  id: string;
+  sipTrunkId: string;
+  name: string;
+  metadata: string;
+  numbers: string[];
+  allowedAddresses: string[];
+  allowedNumbers: string[];
+  authUsername: string;
+  authPassword: string;
+  headers: Record<string, string>;
+  headersToAttributes: Record<string, string>;
+  krispEnabled: boolean;
+  includeHeaders: string;
+  mediaEncryption: string;
+  deleted?: boolean;
+};
+
+export type LiveKitSIPOutboundTrunk = {
+  id: string;
+  sipTrunkId: string;
+  name: string;
+  metadata: string;
+  address: string;
+  transport: string;
+  numbers: string[];
+  authUsername: string;
+  authPassword: string;
+  headers: Record<string, string>;
+  headersToAttributes: Record<string, string>;
+  includeHeaders: string;
+  mediaEncryption: string;
+  destinationCountry: string;
+  deleted?: boolean;
+};
+
+/** SIP dispatch rule: the protobuf `rule` oneof is either dispatchRuleDirect or dispatchRuleIndividual. */
+export type LiveKitSIPDispatchRule = {
+  id: string;
+  sipDispatchRuleId: string;
+  name: string;
+  metadata: string;
+  trunkIds: string[];
+  hidePhoneNumber: boolean;
+  attributes: Record<string, string>;
+  roomPreset: string;
+  inboundNumbers: string[];
+  /** the active oneof case + its value (direct: { roomName, pin }; individual: { roomPrefix, pin }) */
+  rule: { case: 'dispatchRuleDirect' | 'dispatchRuleIndividual'; value: Record<string, unknown> };
+  deleted?: boolean;
+};
+
+export type LiveKitSIPParticipant = {
+  id: string;
+  participantId: string;
+  participantIdentity: string;
+  roomName: string;
+  sipCallId: string;
+  sipTrunkId: string;
+  sipCallTo: string;
+  fromNumber: string;
+};
+
+export type LiveKitAgentDispatch = {
+  id: string;
+  dispatchId: string;
+  agentName: string;
+  room: string;
+  metadata: string;
+  createdAt: string;
+  deleted?: boolean;
+};
+
+export type LiveKitWebhookEvent = {
+  event: string;
+  id: string;
+  createdAt: number;
+  room?: Record<string, unknown>;
+  participant?: Record<string, unknown>;
+  egressInfo?: Record<string, unknown>;
+  ingressInfo?: Record<string, unknown>;
+};

package/src/livekit-webhook.ts

@@ -0,0 +1,91 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import type { LiveKitWebhookEvent } from './livekit-types.ts';
+
+// LiveKit webhooks POST a JSON event body plus an `Authorization` header that is
+// a signed JWT (same HS256 scheme as access tokens) whose `sha256` claim is the
+// base64 (standard padding) SHA-256 digest of the raw body. The vendor SDK's
+// WebhookReceiver.receive() verifies the JWT and then checks the body hash.
+// We replicate the producer side (build the body + signed header) and a verifier
+// that is byte-compatible with WebhookReceiver — see livekit-twin.test.ts.
+
+function base64url(input: Buffer | string): string {
+  return Buffer.from(input).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function base64urlDecode(input: string): Buffer {
+  const pad = input.length % 4 === 0 ? '' : '='.repeat(4 - (input.length % 4));
+  return Buffer.from(input.replace(/-/g, '+').replace(/_/g, '/') + pad, 'base64');
+}
+
+function bodyHash(body: string): string {
+  return createHash('sha256').update(body).digest('base64');
+}
+
+function sign(signingInput: string, secret: string): string {
+  return base64url(createHmac('sha256', secret).update(signingInput).digest());
+}
+
+export type WebhookEventInput = {
+  event: LiveKitWebhookEvent['event'];
+  id?: string;
+  createdAtSeconds?: number;
+  room?: Record<string, unknown>;
+  participant?: Record<string, unknown>;
+  egressInfo?: Record<string, unknown>;
+  ingressInfo?: Record<string, unknown>;
+};
+
+/** Serialize a webhook event to its JSON body string. */
+export function buildWebhookBody(input: WebhookEventInput): string {
+  const event: Record<string, unknown> = {
+    event: input.event,
+    id: input.id ?? `EV_${createHash('sha256').update(`${input.event}:${input.id ?? ''}`).digest('hex').slice(0, 16)}`,
+    createdAt: input.createdAtSeconds ?? 0,
+  };
+  if (input.room) event.room = input.room;
+  if (input.participant) event.participant = input.participant;
+  if (input.egressInfo) event.egressInfo = input.egressInfo;
+  if (input.ingressInfo) event.ingressInfo = input.ingressInfo;
+  return JSON.stringify(event);
+}
+
+/** Build the signed `Authorization` header JWT for a webhook body. */
+export function signWebhookHeader(body: string, apiKey: string, apiSecret: string, nowSeconds = 0, ttlSeconds = 6 * 60 * 60): string {
+  const header = base64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+  const payload = base64url(JSON.stringify({ iss: apiKey, nbf: nowSeconds, exp: nowSeconds + ttlSeconds, sha256: bodyHash(body) }));
+  const signingInput = `${header}.${payload}`;
+  return `${signingInput}.${sign(signingInput, apiSecret)}`;
+}
+
+export type WebhookVerifyResult =
+  | { ok: true; event: LiveKitWebhookEvent }
+  | { ok: false; reason: 'missing_header' | 'malformed' | 'bad_signature' | 'expired' | 'hash_mismatch' };
+
+/** Verify a webhook delivery (header JWT signature + body sha256), byte-compatible with WebhookReceiver. */
+export function verifyWebhook(body: string, authHeader: string | undefined, apiSecret: string, opts: { nowSeconds?: number; clockToleranceSeconds?: number } = {}): WebhookVerifyResult {
+  if (!authHeader) return { ok: false, reason: 'missing_header' };
+  const parts = authHeader.split('.');
+  if (parts.length !== 3) return { ok: false, reason: 'malformed' };
+  const [h, p, sig] = parts as [string, string, string];
+  let claims: { exp?: number; nbf?: number; sha256?: string };
+  try {
+    claims = JSON.parse(base64urlDecode(p).toString('utf8'));
+  } catch {
+    return { ok: false, reason: 'malformed' };
+  }
+  const expected = sign(`${h}.${p}`, apiSecret);
+  const a = Buffer.from(sig);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length || !timingSafeEqual(a, b)) return { ok: false, reason: 'bad_signature' };
+  const now = opts.nowSeconds ?? 0;
+  const tol = opts.clockToleranceSeconds ?? 0;
+  if (typeof claims.exp === 'number' && now > claims.exp + tol) return { ok: false, reason: 'expired' };
+  if (claims.sha256 !== bodyHash(body)) return { ok: false, reason: 'hash_mismatch' };
+  let event: LiveKitWebhookEvent;
+  try {
+    event = JSON.parse(body);
+  } catch {
+    return { ok: false, reason: 'malformed' };
+  }
+  return { ok: true, event };
+}

package/src/redis-service-cli.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import { spawn, spawnSync } from 'node:child_process';
+
+const PORT = process.env.PORT;
+if (!PORT) throw new Error('PORT is required');
+
+const name = `volter-livekit-redis-${PORT}`;
+const args = [
+  'run',
+  '--rm',
+  '--name',
+  name,
+  '-p',
+  `127.0.0.1:${PORT}:6379`,
+  'redis:7-alpine',
+  'redis-server',
+  '--save',
+  '',
+  '--appendonly',
+  'no',
+];
+
+const child = spawn('docker', args, { stdio: 'inherit' });
+
+// Synchronous on purpose: the handler exits the process right after, and a spawned `docker rm`
+// that never ran is how a `volter-livekit-redis-<port>` container outlives every World that made it.
+function stop() {
+  try {
+    spawnSync('docker', ['rm', '-f', name], { stdio: 'ignore', timeout: 20_000 });
+  } catch {
+    // best effort
+  }
+}
+
+process.on('SIGTERM', () => { stop(); process.exit(0); });
+process.on('SIGINT', () => { stop(); process.exit(0); });
+
+child.on('exit', (code) => process.exit(code ?? 0));

package/test-fixtures/livekit-openapi-operations.SOURCE.md

@@ -0,0 +1,88 @@
+# livekit-openapi-operations.json — provenance
+
+The operation-inventory denominator for `../livekit-spec-census.json`: a scope-filtered subset of
+the vendor's published spec, enumerated by `deriveFromOpenAPI` (`packages/world-tooling/src/derive.ts`).
+
+- **Upstream:** https://github.com/livekit/protocol — `the 22 top-level .proto files of livekit/protocol@09c9697b`.
+- **How it was built:** `bun scripts/spec-proto-to-openapi.ts <out.json> --style twirp --fetched 2026-09-02 --upstream https://github.com/livekit/protocol test-fixtures/protobufs/*.proto`
+  over the vendored copies of the upstream files fetched 2026-09-02, then scope-filtered by
+  `buildScopedFixture` (`scripts/spec-fixture-build.ts`, the same code path `spec-census-bootstrap.ts`
+  runs); operation metadata only (operationId, summary, tags, `deprecated`, first response, servers),
+  schemas dropped. The gate never fetches — refreshing the fixture is re-running that conversion over a
+  newer checkout of the protocol repo.
+- **Scope (47 of 94 upstream operations):** every operation whose path starts with one of
+  `/twirp/livekit.RoomService/`, `/twirp/livekit.Egress/`, `/twirp/livekit.Ingress/`, `/twirp/livekit.SIP/`, `/twirp/livekit.AgentDispatchService/`.
+- **Mapping at birth:** 0 operations mapped to done capability ids by the rules in `scripts/spec-census-map.ts`
+  behind the static served-surface probe; 47 left `unmapped`. The census, not this file, records what
+  happened next: hand rulings (a `$ruled` marker, a remap) and the per-operation probe's demotions
+  (`$probeComment`). This fixture changes only through a spec refresh.
+
+## Derivation — livekit publishes NO OpenAPI
+
+`docs.livekit.io/openapi.json` answers 200 with the docs site's HTML, not a spec. LiveKit's server
+APIs are declared first-party as protobuf/Twirp service definitions in the open-source protocol
+repo, so the paths in this fixture come from the twitchtv/twirp v7 WIRE convention rather than from
+a document: for every `rpc <Method>` inside every `service <Service> { … }` block, one operation
+
+    POST /twirp/<the file's `package`>.<Service>/<Method>
+
+with `operationId` `<Service>.<Method>`, `tags` `[<Service>]`, `summary` from the rpc's leading `//`
+comment run, and `deprecated: true` when the rpc declares `option deprecated = true`. All 22 files
+declare `package livekit;`, so every path is `/twirp/livekit.<Service>/<Method>` — the exact shape
+`route()` in `../src/livekit-twin.ts` parses (`/^\/twirp\/livekit\.([^/]+)\/([^/?]+)$/`). These paths
+are really on the wire; nothing here is invented. 11 services, 94 rpcs at `livekit/protocol@09c9697b`
+(2026-09-02); 47 of them fall inside the scope above.
+
+## The source documents are VENDORED, and a test re-derives this file from them
+
+`protobufs/*.proto` ARE the 22 top-level `.proto` files of `livekit/protocol@09c9697b` — the head
+read when this census was born, fetched from
+`https://codeload.github.com/livekit/protocol/tar.gz/09c9697b`. They are committed so the derivation
+can be re-run without a network.
+
+`../src/livekit-spec-census.test.ts` re-runs the whole derivation over them — `protoToOpenApi`
+(`scripts/spec-proto-to-openapi.ts`, `--style twirp`) then `buildScopedFixture`
+(`scripts/spec-fixture-build.ts`) — and asserts the result is BYTE-IDENTICAL to this file. It also
+asserts the vendored set really declares the 11 services and 94 rpcs `../livekit-spec-census.json`
+counts, and that `SIP/ListSIPTrunk` still carries the deprecation the proto declares. That test is
+the drift tooth: this fixture cannot silently stop being the derivation of the documents beside it.
+Nothing is fetched at test time.
+
+The vendored documents and the test are declared in `../census.json` under `spec.rederivation`,
+where `bun scripts/spec-refresh.ts --self-check` checks they exist — the second of the two machine
+refresh paths a committed census must have.
+
+## RE-DERIVED 2026-09-03 with the committed converter (a ratified artifact revision)
+
+This fixture was originally built by an AD-HOC rule, written out in prose in this file and committed
+nowhere: `scripts/spec-proto-to-openapi.ts` did not exist yet, and the note here said so. It exists
+now, and this fixture is its output over the same 22 protos at the same pin. The **route set did not
+move** — the same 47 in-scope operations, so no census row changed — but the operation metadata did:
+
+| field | operations | was (ad-hoc rule) | is (committed converter) |
+|---|---|---|---|
+| `operationId` | 47 / 47 | `SIP_ListSIPTrunk` | `SIP.ListSIPTrunk` |
+| first response `description` | 47 / 47 | `ListSIPTrunk response` | `ok` |
+| `deprecated` | 1 / 47 | absent on `SIP/ListSIPTrunk` | `true` |
+| `info.title` / `info.version` | — | `LiveKit server APIs (Twirp, …)` / `09c9697b` | the converter's title / the fetch date |
+
+`summary` and `tags` are unchanged on all 47.
+
+The `deprecated` row is a **RESTORATION, not a change**: `livekit_sip.proto` has always marked
+`ListSIPTrunk` `option deprecated = true` (in favour of `ListSIPInboundTrunk` /
+`ListSIPOutboundTrunk`), the census's `$unmappedComment` already rules on the operation *because* of
+that deprecation, and the ad-hoc rule simply dropped the fact on the floor. The pin
+(`livekit/protocol@09c9697b`, fetched 2026-09-02) is untouched, so nothing here is a vendor change.
+
+Two converter defects were fixed to make this derivation true to the source, both proven by the
+counts this file records:
+
+- A wrapped signature (`rpc Foo(Req)\n    returns (Res) {}`) was not recognised, which silently
+  dropped all six rpcs of `PhoneNumberService` — the converter saw 88 rpcs where the protos declare
+  94. All six are OUTSIDE this fixture's scope, so no in-scope route moved; what they moved is the
+  converter's agreement with the census's `fullSpecEstimateOps: 94`, which the test now asserts.
+- A `//` block separated from an rpc by a BLANK line was still taken as that rpc's documentation.
+  `livekit_sip.proto` keeps a commented-out `rpc CreateSIPTrunk(…) … DELETED` line one blank line
+  above `ListSIPTrunk`, so the live rpc was captioned with a deleted one's signature. `ListSIPTrunk`
+  now has the empty summary the proto actually gives it — which is what the committed fixture
+  already said.