如何使用针对用户的OAuth访问机制来构建人工智能代理程序【完整手册】

mkcert -install
mkcert localhost

Slack 应用程序，以及那个至关重要的设置

在重定向URL选项下，添加https://localhost:3000/callback。

接下来，请找到相关的权限范围。该页面分为两个部分，如果选错了部分，共享机器人的配置将会被自动重新设置：

在用户令牌权限范围选项下，添加以下内容：

• channels:history：允许读取用户所属公共频道中的消息

• chat:write：允许以用户的身份发布内容

• users:read：能够将用户ID转换为对应的用户名

“机器人令牌权限范围”选项保持空白即可。请从基本信息中复制客户端ID和客户端密钥。

GitHub OAuth应用配置

在“设置” → “开发者设置” → “OAuth应用” → “新建OAuth应用”中，将授权回调URL设置为相同的https://localhost:3000/callback，然后生成客户端密钥。如果您需要了解更多详细信息，GitHub的文档中有完整的说明。

对于问题创建功能而言，GitHub规定的权限范围会根据仓库类型而有所不同：

• repo：适用于私有仓库，可授予访问代码的读写权限

• public_repo：这个选项的范围更有限，但当您的测试仓库是公共仓库时，使用这个权限范围就足够了

只要有可能，就应该选择范围较窄的选项。那些不必要的权限范围日后反而会带来解释上的麻烦。

环境文件配置

这两个应用都会生成客户端ID和客户端密钥，而系统还需要一个加密密钥。请先生成这个密钥：

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"

接下来，请填写.env文件的内容：

OAUTH_REDIRECT_URI=https://localhost:3000/callback
TLS_CERT_PATH=./localhost.pem
TLS_KEY_PATH=./localhost-key.pem

SLACK_CLIENT_ID=
SLACK_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

TOKEN_ENCRYPTION_KEY=

SLACK_CHANNEL_ID=C0XXXXXXXXX
GITHUB_REPO=your-name/your-test-repo

这些客户端密钥用于让您的应用程序能够向各服务提供商进行身份验证。它们并不是用户的登录凭证，也绝不应该出现在浏览器中。

如何运行授权流程

所有与特定服务提供商相关的配置都应集中在一个地方，这样以后如果需要添加第三家服务提供商，只需添加相应的配置项即可，而无需进行复杂的修改。

步骤1：逐一描述各服务提供商的配置要求

const REDIRECT_URI = process.env.OAUTH_REDIRECT_URI;

export const providers = {
  slack: {
    label: 'Slack',
    authorizeUrl: 'https://slack.com/oauth/v2/authorize',
    tokenUrl: 'https://slack.com/api/oauth.v2.access',

    // 这些参数应该被设置在 `user_scope` 中，而不是 `scope` 中。`scope` 下列出的权限是用于获取机器人令牌的，
    // 而这个项目正是为了避免使用机器人令牌而存在的。
    userScopes: ['channels:history', 'chat:write', 'users:read'],
    buildAuthorizeUrl(state) {
      const url = new URL(this.authorizeUrl);
      url.searchParams.set('client_id', process.env.SLACK_CLIENT_ID);
      url.searchParams.set('user_scope', this.userScopes.join(','));
      url.searchParams.set('redirect_uri', REDIRECT_URI);
      url.searchParams.set('state', state);
      return url.toString();
    },
    // exchangeCode 和 refresh 的相关代码如下
  },
};

`user_scope` 这个参数需要将所有所需的信息放在同一行中。Slack会用 scope 来获取机器人权限，而用 user_scope 来获取用户权限。这个项目只设置了后者，因此响应中根本不会包含机器人令牌。

state 这个参数是必填的。你需要生成一个随机字符串，将其发送给提供者，在接收到回复时再检查这个字符串是否正确。如果没有这个参数，任何网页都可以将用户的浏览器指向你的回调URL，并且攻击者还可以附上自己的 code；这样一来，你的服务器就会错误地交换令牌，并将攻击者的令牌存储在用户的账户下。

步骤2：交换代码并获取正确的令牌

async exchangeCode(code) {
  const response = await fetch(this.tokenUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      code,
      client_id: process.env.SLACK_CLIENT_ID,
      client_secret: process.env.SLACK_CLIENT_SECRET,
      redirect_uri: REDIRECT_URI,
    }),
  });

  const json = await response.json();

  // 即使交换失败，Slack也会返回HTTP 200状态码。实际上，真正的状态信息在 `ok` 字段中。
  if (!json.ok) {
    throw new Error(`Slack令牌交换失败：${json.error}`);
  }

  return normalizeSlackTokens(json.authed_user);
}

如果忽略了该函数中的两个细节，就会花费大量的时间进行调试。

即使交换失败，Slack也会返回HTTP 200状态码。检查 response.ok 只能告诉你HTTP请求是否成功完成了，而真正判断OAuth交换是否成功的应该是 json.ok 这个字段。

需要使用的是 json.authed_user，而不是 json。注意这里的区别——如果直接读取 json.access_token，就会错误地获取到令牌，并导致所有使用该代理的用户都获得相同的机器人身份。

对结果进行规范化处理，可以使代码库的其他部分保持与具体提供者无关的状态：

GitHub实现的相同功能在两个方面存在差异，这些差异值得注意：

如果省略`Accept: application/json`这个头部，就会导致程序出现错误：当响应体的内容为`access_token=gho_...&scope=repo`时，调用`response.json()`会抛出异常。

步骤3：捕获重定向请求

OAuth流程需要一个接收响应的服务器。对于命令行工具来说，只需启动一个服务器，处理每个提供者的回调请求，然后退出即可。但由于Slack要求使用HTTPS协议，因此`OAUTH_REDIRECT_URI`这个参数决定了应该启动哪种类型的服务器：

如果缺少TLS证书，肯定会有用户遇到问题，而单独出现`ENOENT`错误并不能说明与OAuth流程有关的问题。因此，异常处理代码用四行文字说明了在这种情况下应该执行什么操作。

在`handleCallback`函数中，才会检查`state`变量的值：

“pending”映射实际上就是用来检查状态的变化的。只有当某个进程生成了某个状态值时，该状态值才会被添加到这个映射中；而一旦该状态值被使用完毕，它就会立即从映射中删除。如果某个状态值没有被识别出来，那就意味着相应的回调请求并不是来自你启动的那个流程；而如果某个状态值出现了两次，那就说明发生了数据重放的情况。这两种情况都可以通过查询同一个Map来得到判断结果。

生成状态值并等待其对应的回调请求的到来：

function connect(providerName) {
  const provider = providers[providerName];
  const state = randomBytes(16).toString('hex');

  console.log(`\n[${providerName}] authorize as "${IDENTIFIER}":`);
  console.log/provider.buildAuthorizeUrl(state));

  return new Promise((resolve, reject) => {
    pending.set(state, {
      provider: providerName,
      reject,
      async finish(code, response) {
        const tokens = await provider.exchangeCode(code);
        saveGrant(IDENTIFIER, providerName, tokens);
        response
          .writeHead(200, { 'Content-Type': 'text/html' })
          .end(`
${provider.label}已经连接成功。您可以关闭此标签页。
`);
        resolve();
      },
    });
  });
}

这里应该使用randomBytes(16)而不是Math.random()，因为如果状态参数是可以预测的，那么实际上就相当于没有设置任何状态参数一样。

运行这个程序时，会依次访问每一个尚未被连接的提供者：

[slack] authorize as "alice@example.com":
https://slack.com/oauth/v2/authorize?client_id=123.456&user_scope=channels%3Ahistory%2Cchat%3:write%2Cusers%3:read&redirect_uri=https%3A%2F%2Flocalhost%3A3000%2Fcallback&state=1159699dbf1a808fd33ba31c7b643505

注意看，这个URL中并没有包含任何scope参数。由于Slack并没有要求生成机器人令牌的指令，因此它也不会自动生成这样的令牌。

如何将令牌加密并使用用户自定义的密钥进行存储

存储令牌的关键在于回答这样一个问题：对于这个用户来说，哪个令牌是属于哪个提供者的？而关于令牌的其他所有信息，其实都是基于这个答案来确定的。

从Node v22.5开始，node:sqlite模块就已经被内置到了Node.js中，并且从v22.13版本起，不再需要使用任何额外的配置标志了。这样一来，人们就可以直接使用这个模块来创建一个真正的数据库，而无需再进行任何额外的安装操作：

import { DatabaseSync } from 'node:sqlite';
import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';

const KEY = Buffer.from(process.env.TOKEN_ENCRYPTION_KEY ?? '', 'base64');

if (KEY.length !== 32) {
  throw new Error(
    'TOKEN_ENCRYPTION_KEY必须是由32个字节组成的、经过base64编码的字符串。'
    + `当前得到的键的长度为${KEY.length}字节。`
  );
}

const db = new DatabaseSync(
  process.env.TOKEN_DB_PATH ?? new URL('../tokens.db', import.meta.url).pathname
);

// 每个用户对应一个记录，每个提供者也对应一条记录。由于“expires_at”字段被存储在密文之中，因此无需解密就可以检查令牌的有效期。
db.exec(`
  CREATE TABLE IF NOT EXISTS grants (
    identifier TEXT    NOT NULL,
    provider   TEXT    NOT NULL,
    ciphertext BLOB    NOT NULL,
    iv         BLOB    NOT NULL,
    auth_tag   BLOB    NOT NULL,
    expires_at INTEGER,
    PRIMARY KEY (identifier, provider)
  )
`);

function encrypt(payload) {
  const iv = randomBytes(12);
  const cipher = createCipheriv('aes-256-gcm', KEY, iv);
  const ciphertext = Buffer.concat([
    cipher.update(JSON.stringify(payload), 'utf8'),
    cipher.final(),
  ]);
  return { ciphertext, iv, authTag: cipher.getAuthTag() };
}

function decrypt({ ciphertext, iv, authTag }) {
  const decipher = createDecipheriv('aes-256-gcm', KEY, iv);
  decipher.setAuthTag(authTag);
  const plaintext = Buffer.concat([
    decipher.update(ciphertext),
    decipher.final(),
  ]);
  return JSON.parse(plaintext.toString('utf8'));
}

export function saveGrant(identifier, provider, tokens) {
  const { ciphertext, iv, authTag } = encrypt(tokens);
  db.prepare(
    `INSERT INTO grants (identifier, provider, ciphertext, iv, auth_tag, expires_at)
     VALUES (?, ?, ?, ?, ?, ?)
     ON CONFLICT (identifier, provider) DO UPDATE SET
       ciphertext = excluded.ciphertext,
       iv         = excluded.iv,
       auth_tag   = excluded.auth_tag,
       expires_at = excludedexpires_at`
  ).run(identifier, provider, ciphertext, iv, authTag, tokens.expiresAt ?? null);
}

每个返回值都值得单独进行审查。createIssue函数会返回问题的编号、URL和标题，而postThreadReply函数则会返回一个时间戳。这两种函数都不会返回token，也不会返回提供商的实际响应数据——如果真的需要隐藏token的话，也应该把这些信息放在响应数据中。

这些由提供商自己发起的HTTP请求其实都是普通的HTTP请求而已：

export async function createIssue(token, owner, repo, { title, body }) {
  const response = await fetch(
    `https://api.github.com/repos/${owner}/${repo}/issues`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        Accept: 'application/vnd.github+json',
        'X-GitHub-Api-Version': '2022-11-28',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ title, body }),
    }
  );

  const json = await response.json();

  if (!response.ok) {
    // 在这里，403错误通常表示授权信息中缺少`repo`权限。
    throw new Error(
      `在GitHub上创建问题失败（状态码：${response.status}）：${json.message}`
    );
  }

  return { number: json.number, url: json.html_url, title: json.title };
}

步骤4：阅读聊天记录

Slack的conversations.history方法返回结构清晰的JSON数据，但其中存在一个问题：这些消息中包含的是用户ID，而非显示名称。因此，若要将这些信息转换为显示名称，就需要对每条消息分别调用users.info接口；而这正是users:read方法被用于实现这一功能的原因。

export async function readChannel(token, channelId, limit = 20) {
  const { messages } = await slackCall(token, 'conversations.history', {
    channel: channelId,
    limit: String(limit),
  });

  const authors = await resolveAuthors(
    token,
    messages.filter((m) => m.user).map((m) => m.user)
  );

  return messages
    .filter((message) => message.text)
    .map((message) => ({
      author: authors.get(message.user) ?? 'unknown',
      userId: message.user,
      text: message.text,
      ts: message.ts,
    }))
    .reverse(); // 按时间顺序倒序排列
}

在这个函数中，有三个关键的决策需要考虑：

async refresh() {
  throw new Error(
    'GitHub OAuth应用用户的令牌是不会过期的。如果这里出现错误，那就意味着令牌已经被撤销了——需要再次征求用户的同意。’
  );
}

“不会过期”并不等同于“永远有效”。事实上，GitHub会出于一些合理的理由撤销令牌，了解这些原因是很重要的。

• 用户可以通过账户设置撤销对该令牌的授权。

• 如果该令牌在一年内未被使用，它将会被弃用。

• 如果该令牌被保存到公共仓库或Gist中，GitHub会自动撤销其有效性。

• 如果某个应用程序为同一用户和相同的权限范围积累了超过10个令牌，那么最旧的那些令牌将会被撤销。

Slack：令牌轮换是可选且永久性的

async refresh(refreshToken) {
  const response = await fetch(this.tokenUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: process.env.SLACK_CLIENT_ID,
      client_secret: process.env.SLACK_CLIENT_SECRET,
    }),
  });

  const json = await response.json();
  if (!json.ok) {
    throw new Error(`Slack令牌刷新失败：${json.error}`);
  }

  return normalizeSlackTokens(json.authed_user ?? json);
}