@volter/twin-livekit 0.1.0

package/src/livekit-data.ts

@@ -0,0 +1,278 @@
+import { createHash } from 'node:crypto';
+import { projectResources } from '@volter/world-core';
+import type {
+  LiveKitAgentDispatch,
+  LiveKitEgress,
+  LiveKitIngress,
+  LiveKitParticipant,
+  LiveKitRoom,
+  LiveKitSIPDispatchRule,
+  LiveKitSIPInboundTrunk,
+  LiveKitSIPOutboundTrunk,
+  LiveKitSIPParticipant,
+} from './livekit-types.ts';
+
+export const SERVICE = 'livekit';
+export const FIXED_NOW = '1970-01-01T00:00:00.000Z';
+
+export const TRACK_SOURCE = {
+  UNKNOWN: 0,
+  CAMERA: 1,
+  MICROPHONE: 2,
+  SCREEN_SHARE: 3,
+  SCREEN_SHARE_AUDIO: 4,
+} as const;
+
+export const TRACK_TYPE = { AUDIO: 0, VIDEO: 1, DATA: 2 } as const;
+export const PARTICIPANT_STATE = { JOINING: 0, JOINED: 1, ACTIVE: 2, DISCONNECTED: 3 } as const;
+export const EGRESS_STATUS = {
+  STARTING: 0,
+  ACTIVE: 1,
+  ENDING: 2,
+  COMPLETE: 3,
+  FAILED: 4,
+  ABORTED: 5,
+  LIMIT_REACHED: 6,
+} as const;
+
+export const INGRESS_INPUT = { RTMP_INPUT: 0, WHIP_INPUT: 1, URL_INPUT: 2 } as const;
+export const INGRESS_STATUS = {
+  ENDPOINT_INACTIVE: 0,
+  ENDPOINT_BUFFERING: 1,
+  ENDPOINT_PUBLISHING: 2,
+  ENDPOINT_ERROR: 3,
+  ENDPOINT_COMPLETE: 4,
+} as const;
+
+/** active egress statuses, used by both ListEgress(active) and room activeRecording */
+export function isActiveEgressStatus(status: number): boolean {
+  return status === EGRESS_STATUS.STARTING || status === EGRESS_STATUS.ACTIVE || status === EGRESS_STATUS.ENDING;
+}
+
+export function ingressInput(input: unknown): number {
+  if (typeof input === 'number') return input;
+  const value = String(input ?? '').toUpperCase();
+  if (value === 'WHIP_INPUT' || value === 'WHIP') return INGRESS_INPUT.WHIP_INPUT;
+  if (value === 'URL_INPUT' || value === 'URL') return INGRESS_INPUT.URL_INPUT;
+  return INGRESS_INPUT.RTMP_INPUT;
+}
+
+export function stableHash(input: unknown): string {
+  return createHash('sha256').update(JSON.stringify(input)).digest('hex').slice(0, 16);
+}
+
+export function seconds(iso: string): string {
+  return String(Math.floor(new Date(iso).getTime() / 1000));
+}
+
+export function millis(iso: string): string {
+  return String(new Date(iso).getTime());
+}
+
+export function roomId(name: string): string {
+  return `room_${stableHash(name)}`;
+}
+
+export function roomSid(name: string): string {
+  return `RM_${stableHash(name)}`;
+}
+
+export function participantId(roomName: string, identity: string): string {
+  return `participant_${stableHash({ roomName, identity })}`;
+}
+
+export function participantSid(roomName: string, identity: string): string {
+  return `PA_${stableHash({ roomName, identity })}`;
+}
+
+export function egressId(roomName: string, request: unknown, occurredAt: string, sequence: number): string {
+  return `EG_${stableHash({ roomName, request, occurredAt, sequence })}`;
+}
+
+export function egressResourceId(id: string): string {
+  return `egress_${id}`;
+}
+
+export function ingressId(roomName: string, participantIdentity: string, request: unknown, sequence: number): string {
+  return `IN_${stableHash({ roomName, participantIdentity, request, sequence })}`;
+}
+
+export function ingressResourceId(id: string): string {
+  return `ingress_${id}`;
+}
+
+export function ingressStreamKey(id: string): string {
+  return stableHash({ streamKey: id });
+}
+
+export function trackSource(input: unknown): number {
+  if (typeof input === 'number') return input;
+  const value = String(input ?? '').toUpperCase();
+  if (value === 'SCREEN_SHARE') return TRACK_SOURCE.SCREEN_SHARE;
+  if (value === 'SCREEN_SHARE_AUDIO') return TRACK_SOURCE.SCREEN_SHARE_AUDIO;
+  if (value === 'MICROPHONE') return TRACK_SOURCE.MICROPHONE;
+  if (value === 'CAMERA') return TRACK_SOURCE.CAMERA;
+  return TRACK_SOURCE.UNKNOWN;
+}
+
+export function defaultRoom(name: string, occurredAt = FIXED_NOW, input: Record<string, unknown> = {}): LiveKitRoom {
+  return {
+    id: roomId(name),
+    sid: roomSid(name),
+    name,
+    emptyTimeout: Number(input.emptyTimeout ?? 300),
+    departureTimeout: Number(input.departureTimeout ?? 20),
+    maxParticipants: Number(input.maxParticipants ?? 0),
+    metadata: String(input.metadata ?? ''),
+    creationTime: seconds(occurredAt),
+    creationTimeMs: millis(occurredAt),
+    numParticipants: 0,
+    activeRecording: false,
+    generation: Number(input.generation ?? 0),
+    deleted: false,
+  };
+}
+
+export function defaultParticipant(roomName: string, identity: string, occurredAt = FIXED_NOW, input: Record<string, any> = {}): LiveKitParticipant {
+  const tracks = Array.isArray(input.tracks) ? input.tracks : [];
+  return {
+    id: participantId(roomName, identity),
+    sid: String(input.sid ?? participantSid(roomName, identity)),
+    roomName,
+    identity,
+    state: Number(input.state ?? PARTICIPANT_STATE.ACTIVE),
+    tracks: tracks.map((track, index) => ({
+      sid: String(track.sid ?? `TR_${stableHash({ roomName, identity, index })}`),
+      name: String(track.name ?? `track-${index + 1}`),
+      type: Number(track.type ?? (trackSource(track.source) === TRACK_SOURCE.MICROPHONE || trackSource(track.source) === TRACK_SOURCE.SCREEN_SHARE_AUDIO ? TRACK_TYPE.AUDIO : TRACK_TYPE.VIDEO)),
+      muted: Boolean(track.muted ?? false),
+      width: Number(track.width ?? 1280),
+      height: Number(track.height ?? 720),
+      source: trackSource(track.source),
+      mimeType: String(track.mimeType ?? 'video/vp8'),
+    })),
+    metadata: String(input.metadata ?? ''),
+    joinedAt: seconds(occurredAt),
+    joinedAtMs: millis(occurredAt),
+    name: String(input.name ?? identity),
+    version: Number(input.version ?? 1),
+    isPublisher: Boolean(input.isPublisher ?? true),
+    kind: Number(input.kind ?? 0),
+    attributes: input.attributes && typeof input.attributes === 'object' ? input.attributes : {},
+    permission: input.permission && typeof input.permission === 'object'
+      ? {
+          canSubscribe: Boolean(input.permission.canSubscribe ?? true),
+          canPublish: Boolean(input.permission.canPublish ?? true),
+          canPublishData: Boolean(input.permission.canPublishData ?? true),
+          canUpdateMetadata: Boolean(input.permission.canUpdateMetadata ?? false),
+          hidden: Boolean(input.permission.hidden ?? false),
+          canSubscribeMetrics: Boolean(input.permission.canSubscribeMetrics ?? false),
+        }
+      : { canSubscribe: true, canPublish: true, canPublishData: true, canUpdateMetadata: false, hidden: false, canSubscribeMetrics: false },
+    subscribedTracks: Array.isArray(input.subscribedTracks) ? input.subscribedTracks.map(String) : [],
+  };
+}
+
+export function rowList<T>(type: string, root?: string): T[] {
+  return projectResources(SERVICE, root)
+    .filter((r) => r.type === type)
+    .map((r) => {
+      const { type: _type, updatedAt: _updatedAt, ...rest } = r;
+      return rest as T;
+    });
+}
+
+export const rooms = (root?: string): LiveKitRoom[] => rowList<LiveKitRoom>('room', root);
+export const participants = (root?: string): LiveKitParticipant[] => rowList<LiveKitParticipant>('participant', root);
+export const egresses = (root?: string): LiveKitEgress[] => rowList<LiveKitEgress>('egress', root);
+export const ingresses = (root?: string): LiveKitIngress[] => rowList<LiveKitIngress>('ingress', root);
+
+export function defaultIngress(id: string, inputType: number, occurredAt = FIXED_NOW, input: Record<string, any> = {}): LiveKitIngress {
+  // WHIP defaults to bypass (no transcoding); RTMP/URL require transcoding.
+  const enableTranscoding = input.enableTranscoding !== undefined
+    ? Boolean(input.enableTranscoding)
+    : inputType !== INGRESS_INPUT.WHIP_INPUT;
+  return {
+    id: ingressResourceId(id),
+    ingressId: id,
+    name: String(input.name ?? ''),
+    streamKey: inputType === INGRESS_INPUT.URL_INPUT ? '' : ingressStreamKey(id),
+    url: ingressUrl(inputType, id, input),
+    inputType,
+    bypassTranscoding: !enableTranscoding,
+    enableTranscoding,
+    roomName: String(input.roomName ?? ''),
+    participantIdentity: String(input.participantIdentity ?? ''),
+    participantName: String(input.participantName ?? ''),
+    participantMetadata: String(input.participantMetadata ?? ''),
+    reusable: inputType === INGRESS_INPUT.RTMP_INPUT,
+    enabled: input.enabled === undefined ? true : Boolean(input.enabled),
+    audio: input.audio && typeof input.audio === 'object' ? input.audio : undefined,
+    video: input.video && typeof input.video === 'object' ? input.video : undefined,
+    state: {
+      status: INGRESS_STATUS.ENDPOINT_INACTIVE,
+      error: '',
+      roomId: '',
+      startedAt: '0',
+      endedAt: '0',
+      updatedAt: seconds(occurredAt),
+      resourceId: '',
+    },
+    deleted: false,
+  };
+}
+
+function ingressUrl(inputType: number, id: string, input: Record<string, any>): string {
+  if (inputType === INGRESS_INPUT.URL_INPUT) return String(input.url ?? '');
+  if (inputType === INGRESS_INPUT.WHIP_INPUT) return 'https://twin.whip.livekit.cloud/w';
+  return 'rtmp://twin.rtmp.livekit.cloud/x';
+}
+
+// --- SIP + Agent dispatch -------------------------------------------------
+
+/** SIP transport enum JSON names (mirrors @livekit/protocol SIPTransport). */
+export const SIP_TRANSPORT = {
+  SIP_TRANSPORT_AUTO: 'SIP_TRANSPORT_AUTO',
+  SIP_TRANSPORT_UDP: 'SIP_TRANSPORT_UDP',
+  SIP_TRANSPORT_TCP: 'SIP_TRANSPORT_TCP',
+  SIP_TRANSPORT_TLS: 'SIP_TRANSPORT_TLS',
+} as const;
+
+export function sipTransport(input: unknown): string {
+  if (typeof input === 'number') {
+    return ['SIP_TRANSPORT_AUTO', 'SIP_TRANSPORT_UDP', 'SIP_TRANSPORT_TCP', 'SIP_TRANSPORT_TLS'][input] ?? SIP_TRANSPORT.SIP_TRANSPORT_AUTO;
+  }
+  const value = String(input ?? '').toUpperCase();
+  return (SIP_TRANSPORT as Record<string, string>)[value] ?? SIP_TRANSPORT.SIP_TRANSPORT_AUTO;
+}
+
+export function sipInboundTrunkId(name: string, numbers: unknown, sequence: number): string {
+  return `ST_${stableHash({ kind: 'inbound', name, numbers, sequence })}`;
+}
+export function sipOutboundTrunkId(name: string, address: string, sequence: number): string {
+  return `ST_${stableHash({ kind: 'outbound', name, address, sequence })}`;
+}
+export function sipDispatchRuleId(request: unknown, sequence: number): string {
+  return `SDR_${stableHash({ request, sequence })}`;
+}
+export function sipCallId(roomName: string, sipCallTo: string, sequence: number): string {
+  return `SCL_${stableHash({ roomName, sipCallTo, sequence })}`;
+}
+export function sipParticipantSid(roomName: string, identity: string): string {
+  return `PA_${stableHash({ sip: true, roomName, identity })}`;
+}
+export function agentDispatchId(room: string, agentName: string, sequence: number): string {
+  return `AD_${stableHash({ room, agentName, sequence })}`;
+}
+
+export const sipInboundTrunks = (root?: string): LiveKitSIPInboundTrunk[] => rowList<LiveKitSIPInboundTrunk>('sip_inbound_trunk', root);
+export const sipOutboundTrunks = (root?: string): LiveKitSIPOutboundTrunk[] => rowList<LiveKitSIPOutboundTrunk>('sip_outbound_trunk', root);
+export const sipDispatchRules = (root?: string): LiveKitSIPDispatchRule[] => rowList<LiveKitSIPDispatchRule>('sip_dispatch_rule', root);
+export const sipParticipants = (root?: string): LiveKitSIPParticipant[] => rowList<LiveKitSIPParticipant>('sip_participant', root);
+export const agentDispatches = (root?: string): LiveKitAgentDispatch[] => rowList<LiveKitAgentDispatch>('agent_dispatch', root);
+
+export function withCounts(room: LiveKitRoom, root?: string): LiveKitRoom {
+  const numParticipants = participants(root).filter((p) => p.roomName === room.name && p.state !== PARTICIPANT_STATE.DISCONNECTED).length;
+  const activeRecording = egresses(root).some((e) => e.roomName === room.name && isActiveEgressStatus(e.status));
+  return { ...room, numParticipants, activeRecording };
+}

package/src/livekit-perform-harness.ts

@@ -0,0 +1,17 @@
+// A MINIATURE OF THE HEAD, for this pack's own claims and suites (protocol 2). Not on the serve path.
+import { confirmAction, deployableEntries, worldNow } from '@volter/world-core';
+import { pushLiveKitAction, type LiveKitExecute } from './livekit-connector.ts';
+
+export async function performPending(execute: LiveKitExecute, opts: { root?: string; occurredAt?: string } = {}): Promise<number> {
+  let pushed = 0;
+  for (const entry of deployableEntries('livekit', opts.root)) {
+    if (!(await pushLiveKitAction(entry, execute))) continue;
+    confirmAction({
+      service: 'livekit', actionId: entry.id, subject: entry.subject, fields: entry.fields ?? {},
+      occurredAt: opts.occurredAt ?? worldNow(), receipt: { status: 'deployed' },
+      ...(opts.root !== undefined ? { root: opts.root } : {}),
+    });
+    pushed += 1;
+  }
+  return pushed;
+}

package/src/livekit-server.ts

@@ -0,0 +1,67 @@
+// LiveKit twin HTTP server.
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, built from the
+// kernel's ONE adaptation (`createTwinFetchFromHandler`) — the access-token bearer is threaded
+// per request through `extras`, and the pinned api keys / egress ceiling ride the static
+// `handlerOptions`. The server is one line of Bun.serve around that same closure.
+import { serveHttp } from '@volter/world-core';
+import { handleLiveKitTwinRequest } from './livekit-twin.ts';
+import { egresses, ingresses, participants, rooms } from './livekit-data.ts';
+import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+
+export type LiveKitServerOptions = {
+  root?: string;
+  port?: number;
+  readOnly?: boolean;
+  /** apiKey -> apiSecret. When set, the server enforces access-token JWT auth. */
+  apiKeys?: Record<string, string>;
+  /** Max simultaneously-active egress jobs before quota_capacity (429). */
+  maxActiveEgress?: number;
+};
+
+/** Options every LiveKit-twin HTTP surface needs, independent of who owns the socket. */
+export interface LiveKitTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  /** apiKey -> apiSecret. When set, the fetch enforces access-token JWT auth. */
+  apiKeys?: Record<string, string>;
+  /** Max simultaneously-active egress jobs before quota_capacity (429). */
+  maxActiveEgress?: number;
+}
+
+export function createLiveKitTwinFetch(options: LiveKitTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  return createTwinFetchFromHandler(handleLiveKitTwinRequest, {
+    root: options.root,
+    readOnly: options.readOnly,
+    manifest: statefulTwinManifest({ vendor: 'livekit', twinOf: 'the LiveKit control plane', stores: 'rooms, participants and egress state' }),
+    // THE STORE DOOR (R5c): LiveKit's server API is Twirp — EVERY operation, listings included, is
+    // a POST to `/twirp/livekit.<Service>/<Method>`. The twin has no GET at all, so its state was
+    // unreadable by anything that reads a twin the ordinary way (a mirror, an operator, the
+    // resource-level determinism row). These four are that read: the pack's own named deterministic
+    // projections over stored state, served by the same adapter the Twirp paths come out of.
+    stores: {
+      rooms: () => rooms(options.root),
+      participants: () => participants(options.root),
+      egress: () => egresses(options.root),
+      ingress: () => ingresses(options.root),
+    },
+    handlerOptions: {
+      ...(options.apiKeys ? { apiKeys: options.apiKeys } : {}),
+      ...(options.maxActiveEgress !== undefined ? { maxActiveEgress: options.maxActiveEgress } : {}),
+    },
+    extras: (request) => {
+      const auth = request.headers.get('authorization') ?? '';
+      const authToken = auth.toLowerCase().startsWith('bearer ') ? auth.slice(7).trim() : auth.trim();
+      return authToken ? { authToken } : {};
+    },
+  });
+}
+
+export async function createLiveKitTwinServer(options: LiveKitServerOptions = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createLiveKitTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/src/livekit-service-cli.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import { spawn } from 'node:child_process';
+import dgram from 'node:dgram';
+import net from 'node:net';
+import { networkInterfaces } from 'node:os';
+
+const PORT = process.env.PORT;
+const REDIS_HOST = process.env.REDIS_HOST;
+if (!PORT) throw new Error('PORT is required');
+
+function hostReachableIp(): string {
+  if (process.env.LIVEKIT_NODE_IP) return process.env.LIVEKIT_NODE_IP;
+  for (const entries of Object.values(networkInterfaces())) {
+    for (const entry of entries ?? []) {
+      if (entry.family === 'IPv4' && !entry.internal) return entry.address;
+    }
+  }
+  return '127.0.0.1';
+}
+
+async function freeUdpPort(): Promise<number> {
+  return await new Promise((resolve, reject) => {
+    const socket = dgram.createSocket('udp4');
+    socket.once('error', reject);
+    socket.bind(0, '127.0.0.1', () => {
+      const address = socket.address();
+      const port = typeof address === 'object' ? address.port : 0;
+      socket.close(() => resolve(port));
+    });
+  });
+}
+
+async function freeTcpPort(): Promise<number> {
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      const port = typeof address === 'object' && address ? address.port : 0;
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+// Redis answers PING before LiveKit is allowed to dial it. The store is a container whose host
+// port is published by the VM's forwarder, which ACCEPTS a connection before the container can
+// answer on it; livekit-server dials once with a short deadline and exits on "i/o timeout". The
+// World's readiness is port-based, so the consumer is where the wait belongs.
+async function redisAnswers(hostPort: string): Promise<boolean> {
+  const [host, port] = hostPort.split(':');
+  return await new Promise((resolve) => {
+    const socket = net.connect({ host, port: Number(port) });
+    const done = (value: boolean) => { socket.destroy(); resolve(value); };
+    socket.setTimeout(2000, () => done(false));
+    socket.once('error', () => done(false));
+    socket.once('connect', () => socket.write('PING\r\n'));
+    socket.once('data', (chunk) => done(chunk.toString().startsWith('+PONG')));
+  });
+}
+
+// A single node needs no store: without REDIS_HOST, livekit-server keeps rooms in memory. A
+// multi-node plane (or one with egress) names its store, and then waits for it as above.
+if (REDIS_HOST) {
+  const redisDeadline = Date.now() + 90_000;
+  while (!(await redisAnswers(REDIS_HOST))) {
+    if (Date.now() > redisDeadline) throw new Error(`redis at ${REDIS_HOST} did not answer PING within 90s`);
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+}
+
+const udpPort = await freeUdpPort();
+const tcpPort = await freeTcpPort();
+const nodeIp = hostReachableIp();
+const child = spawn('livekit-server', [
+  '--dev',
+  '--bind',
+  '0.0.0.0',
+  '--node-ip',
+  nodeIp,
+  '--port',
+  PORT,
+  '--udp-port',
+  String(udpPort),
+  '--rtc.tcp_port',
+  String(tcpPort),
+  ...(REDIS_HOST ? ['--redis-host', REDIS_HOST] : []),
+], { stdio: 'inherit' });
+
+process.on('SIGTERM', () => child.kill('SIGTERM'));
+process.on('SIGINT', () => child.kill('SIGINT'));
+
+child.on('exit', (code) => process.exit(code ?? 0));

package/src/livekit-token.ts

@@ -0,0 +1,133 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+// LiveKit access tokens are HS256 JWTs whose payload is the grant claim set
+// (name?, video?, sip?, inference?, metadata?, attributes?, ...) plus the
+// standard JWT registered claims (iss=apiKey, sub=identity, exp, nbf).
+// livekit-server-sdk's AccessToken.toJwt() / TokenVerifier.verify() use exactly
+// this scheme; replicating it here gives real, byte-faithful grant parity that
+// the vendor SDK can cross-verify (see livekit-twin.test.ts).
+
+export type LiveKitVideoGrant = {
+  roomCreate?: boolean;
+  roomJoin?: boolean;
+  roomList?: boolean;
+  roomRecord?: boolean;
+  roomAdmin?: boolean;
+  room?: string;
+  ingressAdmin?: boolean;
+  canPublish?: boolean;
+  canPublishSources?: string[];
+  canSubscribe?: boolean;
+  canPublishData?: boolean;
+  canUpdateOwnMetadata?: boolean;
+  hidden?: boolean;
+  recorder?: boolean;
+  agent?: boolean;
+  canSubscribeMetrics?: boolean;
+  destinationRoom?: string;
+};
+
+export type LiveKitSIPGrant = { admin?: boolean; call?: boolean };
+
+export type LiveKitClaimGrants = {
+  iss?: string;
+  sub?: string;
+  exp?: number;
+  nbf?: number;
+  name?: string;
+  video?: LiveKitVideoGrant;
+  sip?: LiveKitSIPGrant;
+  metadata?: string;
+  attributes?: Record<string, string>;
+  kind?: string;
+  sha256?: string;
+  [key: string]: unknown;
+};
+
+export type MintTokenInput = {
+  apiKey: string;
+  apiSecret: string;
+  identity?: string;
+  name?: string;
+  metadata?: string;
+  attributes?: Record<string, string>;
+  ttlSeconds?: number;
+  /** issued/now reference, for deterministic exp/nbf */
+  nowSeconds?: number;
+  video?: LiveKitVideoGrant;
+  sip?: LiveKitSIPGrant;
+  kind?: string;
+};
+
+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 sign(signingInput: string, secret: string): string {
+  return base64url(createHmac('sha256', secret).update(signingInput).digest());
+}
+
+/** Mint a LiveKit access token (HS256 JWT) with grant parity to AccessToken.toJwt(). */
+export function mintAccessToken(input: MintTokenInput): string {
+  if (!input.apiKey || !input.apiSecret) throw new Error('apiKey and apiSecret are required');
+  if (input.apiSecret.length < 32) throw new Error('apiSecret must be at least 32 bytes');
+  const now = input.nowSeconds ?? 0;
+  const ttl = input.ttlSeconds ?? 6 * 60 * 60;
+  const payload: LiveKitClaimGrants = {
+    iss: input.apiKey,
+    nbf: now,
+    exp: now + ttl,
+  };
+  if (input.identity !== undefined) payload.sub = input.identity;
+  if (input.name !== undefined) payload.name = input.name;
+  if (input.metadata !== undefined) payload.metadata = input.metadata;
+  if (input.attributes !== undefined) payload.attributes = input.attributes;
+  if (input.kind !== undefined) payload.kind = input.kind;
+  if (input.video !== undefined) payload.video = input.video;
+  if (input.sip !== undefined) payload.sip = input.sip;
+  const header = base64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+  const body = base64url(JSON.stringify(payload));
+  const signingInput = `${header}.${body}`;
+  return `${signingInput}.${sign(signingInput, input.apiSecret)}`;
+}
+
+export type VerifyResult =
+  | { ok: true; grants: LiveKitClaimGrants }
+  | { ok: false; reason: 'malformed' | 'bad_signature' | 'expired' | 'not_yet_valid' | 'unknown_key' };
+
+/**
+ * Verify a LiveKit access token against the apiSecret resolved from the token's
+ * issuer (apiKey). Failable: a forged/tampered/expired token returns ok:false.
+ */
+export function verifyAccessToken(
+  token: string,
+  resolveSecret: (apiKey: string) => string | undefined,
+  opts: { nowSeconds?: number; clockToleranceSeconds?: number } = {},
+): VerifyResult {
+  const parts = token.split('.');
+  if (parts.length !== 3) return { ok: false, reason: 'malformed' };
+  const [header, body, signature] = parts as [string, string, string];
+  let payload: LiveKitClaimGrants;
+  try {
+    payload = JSON.parse(base64urlDecode(body).toString('utf8'));
+  } catch {
+    return { ok: false, reason: 'malformed' };
+  }
+  const apiKey = String(payload.iss ?? '');
+  const secret = resolveSecret(apiKey);
+  if (!secret) return { ok: false, reason: 'unknown_key' };
+  const expected = sign(`${header}.${body}`, secret);
+  const a = Buffer.from(signature);
+  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 payload.exp === 'number' && now > payload.exp + tol) return { ok: false, reason: 'expired' };
+  if (typeof payload.nbf === 'number' && now + tol < payload.nbf) return { ok: false, reason: 'not_yet_valid' };
+  return { ok: true, grants: payload };
+}