Token Authentication

{ "rtcUids": [10001, 10002, 2147483647], "channelName": "weekly-sync" }

getRTCTokenInfo({ channelName, userId?, role?, ttlSeconds? })
  → { appId, rtcToken, rtcUid, expireAt? }

getUserIdsWithRTCUids(rtcUids: number[], channelName?)
  → Record<string /* uid */, string /* IM userId */>

import { createHash, createHmac } from 'node:crypto';
import { basicAuth } from './_lib.mjs';

export const meta = {
  id: '11-im-provider',
  title: 'IM RTC Provider 双方法 + 独立回退',
  safe: true,
  needsApi: true,
};

/**
 * 实现 the public API definition 的两个方法，并演示“各自独立配置、各自独立回退”：
 *
 *   getRTCTokenInfo:        nimeet-http → local-hmac → disabled
 *   getUserIdsWithRTCUids:  nimeet-http → local-cache → identity-echo → disabled
 *
 * 三个场景：
 *   1. 全部可用：走 nimeet-http，Token 由服务端签发；
 *   2. 主通道不可用：Token 回退到本地 HMAC 签名（App Certificate 只在可信后端持有），
 *      并用 /v1/tokens/verify 证明本地签出的 Token 与服务端签名方案一致；
 *   3. 方法独立：tokenInfo 全链路失败时，uidMapping 仍能照常返回（反之亦然）。
 */

/** base64url，无 padding。 */
function base64Url(buffer) {
  return Buffer.from(buffer).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

/** 本地 HMAC 签发：与 the control plane 的 nrt1 格式一致。 */
function signLocalToken({ appId, appCertificate, channelName, uid, role, ttlSeconds, userRef }) {
  const now = Math.floor(Date.now() / 1000);
  const privileges =
    role === 'audience'
      ? ['join_channel', 'subscribe']
      : ['join_channel', 'publish_audio', 'publish_video', 'publish_data', 'subscribe'];
  const payload = {
    v: 1,
    app: appId,
    ch: channelName || '*',
    uid,
    role,
    priv: privileges,
    iat: now,
    exp: now + ttlSeconds,
    pexp: now + ttlSeconds,
    salt: Math.floor(Math.random() * 2147483646) + 1,
    ...(userRef ? { usr: userRef } : {}),
  };
  const body = base64Url(JSON.stringify(payload));
  const signingInput = `nrt1.${body}`;
  const signature = base64Url(createHmacSha256(appCertificate, signingInput));
  return { rtcToken: `${signingInput}.${signature}`, expireAt: new Date((now + ttlSeconds) * 1000).toISOString(), payload };
}

function createHmacSha256(secret, input) {
  return createHmac('sha256', secret).update(input).digest();
}

/** 稳定派生 uid（仅 local-hmac 回退使用；同一 (appId,userId) 恒定）。 */
function deriveUid(appId, userId) {
  const digest = createHash('sha256').update(`${appId}:${userId}`).digest();
  const value = digest.readUInt32BE(0) % 2147483647;
  return value === 0 ? 1 : value;
}

function providerError(code, message) {
  const error = new Error(message ?? code);
  error.code = code;
  return error;
}

export function createRtcProvider({ credentials, config }) {
  const uidCache = new Map(); // rtcUid(string) -> userId

  async function httpJson(baseUrl, pathname, body, timeoutMs) {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), timeoutMs);
    try {
      const response = await fetch(new URL(pathname, baseUrl), {
        method: 'POST',
        headers: {
          'content-type': 'application/json',
          authorization: basicAuth(credentials),
        },
        body: JSON.stringify(body),
        signal: controller.signal,
      });
      const text = await response.text();
      let json = null;
      try {
        json = JSON.parse(text);
      } catch {
        json = null;
      }
      if (!response.ok) {
        const code =
          response.status === 403 ? 'RTC_TOKEN_DENIED' : response.status === 400 ? 'RTC_TOKEN_INVALID_REQUEST' : 'RTC_PROVIDER_UNAVAILABLE';
        throw providerError(code, `${pathname} → ${response.status} ${json?.code ?? text.slice(0, 120)}`);
      }
      return json;
    } catch (error) {
      if (error.code) throw error;
      throw providerError('RTC_PROVIDER_UNAVAILABLE', `${pathname} → ${error.message}`);
    } finally {
      clearTimeout(timer);
    }
  }

  async function issueVia(provider, input, settings) {
    const { channelName, userId, role = settings.defaultRole ?? 'host', ttlSeconds = settings.defaultTtlSeconds ?? 3600 } = input;
    if (provider === 'disabled') throw providerError('RTC_PROVIDER_DISABLED', 'tokenInfo provider is disabled');
    if (provider === 'nimeet-http') {
      const issued = await httpJson(
        settings.baseUrl,
        '/v1/tokens',
        { channelName, ...(userId ? { userId } : {}), role, ttlSeconds },
        settings.timeoutMs ?? 2000,
      );
      if (userId) uidCache.set(String(issued.rtcUid), userId);
      return { appId: issued.appId, rtcToken: issued.rtcToken, rtcUid: issued.rtcUid, expireAt: issued.expireAt };
    }
    if (provider === 'local-hmac') {
      if (!settings.appCertificate || !settings.appId) {
        throw providerError('RTC_PROVIDER_DISABLED', 'local-hmac requires appId + appCertificate in a trusted backend');
      }
      const uid = userId ? deriveUid(settings.appId, userId) : Math.floor(Math.random() * 2147483646) + 1;
      const signed = signLocalToken({
        appId: settings.appId,
        appCertificate: settings.appCertificate,
        channelName,
        uid,
        role,
        ttlSeconds,
        userRef: userId,
      });
      if (userId) uidCache.set(String(uid), userId);
      return { appId: settings.appId, rtcToken: signed.rtcToken, rtcUid: uid, expireAt: signed.expireAt };
    }
    throw providerError('RTC_PROVIDER_UNAVAILABLE', `unknown token provider ${provider}`);
  }

  async function getRTCTokenInfo(input) {
    const settings = { ...config.tokenInfo };
    const chain = [settings.provider, ...(settings.fallback ?? [])];
    let lastError = null;
    for (const provider of chain) {
      try {
        return await issueVia(provider, input, settings);
      } catch (error) {
        lastError = error;
        if (error.code === 'RTC_PROVIDER_DISABLED') throw error; // 配置级禁用：不再尝试
      }
    }
    throw lastError ?? providerError('RTC_PROVIDER_UNAVAILABLE', 'no token provider configured');
  }

  async function resolveVia(provider, uids, channelName, settings) {
    if (provider === 'disabled') throw providerError('RTC_PROVIDER_DISABLED', 'uidMapping provider is disabled');
    if (provider === 'nimeet-http') {
      const mapping = await httpJson(
        settings.baseUrl,
        '/v1/uids:resolve',
        { rtcUids: uids, ...(channelName ? { channelName } : {}) },
        settings.timeoutMs ?? 2000,
      );
      for (const [uid, userId] of Object.entries(mapping)) uidCache.set(String(uid), userId);
      return mapping;
    }
    if (provider === 'local-cache') {
      const mapping = {};
      for (const uid of uids) if (uidCache.has(String(uid))) mapping[String(uid)] = uidCache.get(String(uid));
      return mapping;
    }
    if (provider === 'identity-echo') {
      const mapping = {};
      for (const uid of uids) mapping[String(uid)] = String(uid); // 降级但永不失败
      return mapping;
    }
    throw providerError('RTC_PROVIDER_UNAVAILABLE', `unknown uid provider ${provider}`);
  }

  /** 部分结果语义：未知 uid 省略，绝不整体失败。 */
  async function getUserIdsWithRTCUids(input) {
    const settings = { ...config.uidMapping };
    const pending = [...new Set(input.rtcUids ?? [])];
    const result = {};
    let lastError = null;
    for (const provider of [settings.provider, ...(settings.fallback ?? [])]) {
      const missing = pending.filter((uid) => result[String(uid)] === undefined);
      if (missing.length === 0) break;
      try {
        const mapping = await resolveVia(provider, missing, input.channelName, settings);
        for (const uid of missing) {
          if (mapping[String(uid)] !== undefined) result[String(uid)] = mapping[String(uid)];
        }
      } catch (error) {
        lastError = error;
        if (error.code === 'RTC_PROVIDER_DISABLED') break;
      }
    }
    void lastError; // 完全解析不到时仍返回 {}（调用方渲染兜底显示 uid）
    return result;
  }

  return { getRTCTokenInfo, getUserIdsWithRTCUids };
}

export async function run(ctx) {
  const { credentials, request } = ctx;
  const appId = credentials.appId ?? null;
  ctx.assert(appId, '需要 appId（演示凭证包含）');

  // 场景 1：全部可用，主通道 nimeet-http。
  const provider = createRtcProvider({
    credentials,
    config: {
      tokenInfo: {
        provider: 'nimeet-http',
        fallback: ['local-hmac'],
        baseUrl: ctx.baseUrl,
        appId,
        appCertificate: credentials.appCertificate ?? null,
        timeoutMs: 2000,
      },
      uidMapping: { provider: 'nimeet-http', fallback: ['local-cache', 'identity-echo'], baseUrl: ctx.baseUrl, timeoutMs: 2000 },
    },
  });

  const tokenInfo = await provider.getRTCTokenInfo({ channelName: 'weekly-sync', userId: 'im_user_1', role: 'host', ttlSeconds: 600 });
  ctx.assert(tokenInfo.appId === appId, 'appId 应一致');
  ctx.assert(Number.isInteger(tokenInfo.rtcUid) && tokenInfo.rtcUid >= 1, 'rtcUid 必须是 [1, 2147483647] 内整数');
  ctx.assert(typeof tokenInfo.rtcToken === 'string' && tokenInfo.rtcToken.startsWith('nrt1.'), 'rtcToken 应为 nrt1 Token');

  const mapping = await provider.getUserIdsWithRTCUids({ rtcUids: [tokenInfo.rtcUid, 2147483647], channelName: 'weekly-sync' });
  ctx.assert(mapping[String(tokenInfo.rtcUid)] === 'im_user_1', '主通道应解析出 uid → IM userId');
  // 该配置带 identity-echo 兜底：未知 uid 会降级映射为十进制字符串（接口定义允许的降级语义）。
  ctx.assert(mapping['2147483647'] === '2147483647', 'identity-echo 兜底应把未知 uid 映射为其十进制字符串');

  // 严格模式（不带 identity-echo）：未知 uid 必须被省略。
  const strict = createRtcProvider({
    credentials,
    config: {
      tokenInfo: { provider: 'nimeet-http', fallback: [], baseUrl: ctx.baseUrl, timeoutMs: 2000 },
      uidMapping: { provider: 'nimeet-http', fallback: [], baseUrl: ctx.baseUrl, timeoutMs: 2000 },
    },
  });
  const strictMapping = await strict.getUserIdsWithRTCUids({ rtcUids: [tokenInfo.rtcUid, 2147483647], channelName: 'weekly-sync' });
  ctx.assert(strictMapping[String(tokenInfo.rtcUid)] === 'im_user_1', '严格模式仍应解析已知 uid');
  ctx.assert(strictMapping['2147483647'] === undefined, '严格模式下未知 uid 必须省略（部分结果语义）');

  // 场景 2：主通道不可用 → local-hmac 回退（仅当后端持有 App Certificate）。
  let fallbackSummary = '未配置 appCertificate，跳过 local-hmac 回退验证';
  if (credentials.appCertificate) {
    const degraded = createRtcProvider({
      credentials,
      config: {
        tokenInfo: {
          provider: 'nimeet-http',
          fallback: ['local-hmac'],
          baseUrl: 'http://127.0.0.1:1', // 模拟主通道不可达
          appId,
          appCertificate: credentials.appCertificate,
          timeoutMs: 300,
        },
        uidMapping: {
          provider: 'nimeet-http',
          fallback: ['local-cache', 'identity-echo'],
          baseUrl: 'http://127.0.0.1:1',
          timeoutMs: 300,
        },
      },
    });
    const local = await degraded.getRTCTokenInfo({ channelName: 'weekly-sync', userId: 'im_user_2', role: 'host', ttlSeconds: 600 });
    ctx.assert(local.rtcToken.startsWith('nrt1.'), '回退后仍应得到 nrt1 Token');

    // 用服务端 verify 证明本地签名与 @nimeet/shared 的校验一致。
    const verification = await request('GET', '/v1/tokens/verify', { query: { token: local.rtcToken } });
    ctx.assert(verification.json?.valid === true, `本地签发的 Token 应能通过服务端校验: ${verification.text.slice(0, 200)}`);
    const cached = await degraded.getUserIdsWithRTCUids({ rtcUids: [local.rtcUid] });
    ctx.assert(cached[String(local.rtcUid)] === 'im_user_2', 'uidMapping 应能从 local-cache 回退');
    fallbackSummary = `主通道不可达时 local-hmac 签发成功（服务端 verify 通过），uidMapping 从 local-cache 命中`;
  }

  // 场景 3：方法独立 —— tokenInfo 全链路失败不影响 uidMapping。
  const independent = createRtcProvider({
    credentials,
    config: {
      tokenInfo: { provider: 'nimeet-http', fallback: [], baseUrl: 'http://127.0.0.1:1', timeoutMs: 300 },
      uidMapping: { provider: 'nimeet-http', fallback: [], baseUrl: ctx.baseUrl, timeoutMs: 2000 },
    },
  });
  let tokenFailure = null;
  try {
    await independent.getRTCTokenInfo({ channelName: 'weekly-sync', userId: 'im_user_3' });
  } catch (error) {
    tokenFailure = error.code ?? error.message;
  }
  ctx.assert(tokenFailure === 'RTC_PROVIDER_UNAVAILABLE', `tokenInfo 失败应带 RTC_PROVIDER_UNAVAILABLE，实际 ${tokenFailure}`);
  const stillWorks = await independent.getUserIdsWithRTCUids({ rtcUids: [tokenInfo.rtcUid] });
  ctx.assert(stillWorks[String(tokenInfo.rtcUid)] === 'im_user_1', 'tokenInfo 失败不得影响 uidMapping');

  return {
    summary:
      `主通道 uid=${tokenInfo.rtcUid} → im_user_1（identity-echo 下未知 uid 映射为十进制串，严格模式下省略）；` +
      `${fallbackSummary}；tokenInfo 失败(${tokenFailure}) 时 uidMapping 仍返回 ${JSON.stringify(stillWorks)}`,
    details: { tokenInfo, mapping, strictMapping, independence: { tokenFailure, stillWorks } },
  };
}