API 设计 / 系统课时

使用可信操作白名单

使用可信操作白名单

可信操作白名单把 GraphQL 的执行入口从“客户端可提交任意文档”收紧为“只能引用已审核文档”。本课用 persisted operations 与 trusted documents 的共同机制,建立构建期清单、运行时门禁和可平滑升级的发布流程。

学习目标

  • 区分自动持久化查询与真正具备安全边界的可信操作机制。
  • 构建“操作文档 → 稳定 ID → 服务端清单 → 运行时查表执行”的门禁。
  • 处理未知操作、版本错配和变量滥用,避免白名单被旁路。

先区分缓存优化和安全白名单

“persisted operation”只描述操作文档被预先或持续存储,并不自动等于安全白名单。某些 APQ 流程在服务端未命中哈希时,允许客户端补交完整文档并注册缓存,这能省带宽,却不能阻止新操作进入系统。

机制 未知 ID 时可提交新文档 能否作为执行白名单
APQ 自动注册 通常可以,取决于实现 否
预注册 persisted operation 不可以 可以
trusted documents 不可以 可以

安全边界的关键规则只有一句:生产执行入口遇到未知 ID 必须拒绝,不能回退到任意 query 文本执行。 操作名也不能代替 ID,因为不同文档可以使用相同 operation name。

建立构建期清单和运行时门禁

推荐在 CI 中提取客户端操作,完成代码评审与安全检查后生成 manifest。服务端先发布这份 manifest,客户端再发布只携带操作 ID 与 variables 的版本。运行时先查表,命中后才把服务端保存的原始文档交给 GraphQL 执行器。

可信 GraphQL 操作白名单链路

哈希型 ID 必须基于构建产物中约定的精确文档字节或统一规范化结果生成,客户端和服务端算法也必须一致。另一种更直接的做法是由构建系统分配不可变 ID;ID 是否可猜并不重要,因为它不是秘密,真正的授权仍由身份与字段级规则负责。

可运行的白名单门禁

下面示例依赖 Node.js 20+ 与 graphql 16.x。为了把重点放在门禁上,服务端只预注册一个 Viewer 操作;客户端提交完整 GraphQL 文本或未知 ID 都会被拒绝。

js
import { createHash } from "node:crypto";
import { buildSchema, graphql } from "graphql";

const schema = buildSchema(`
  type User {
    id: ID!
    name: String!
  }

  type Query {
    viewer: User!
  }
`);

const rootValue = {
  viewer: () => ({ id: "u-1", name: "Ada" })
};

const trustedSources = [
  `query Viewer {
    viewer {
      id
      name
    }
  }`
];

// 构建端与服务端必须对同一份文档使用完全一致的 ID 算法。
function documentId(source) {
  return createHash("sha256").update(source).digest("hex");
}

// 生产环境通常从经过审核、带版本的 manifest 加载这张表。
const manifest = new Map(
  trustedSources.map((source) => [documentId(source), source])
);

async function handleRequest(body) {
  // 不接受“没有可信 ID、只有 query 文本”的回退路径。
  if (typeof body.id !== "string") {
    return {
      status: 403,
      body: { errors: [{ message: "TRUSTED_DOCUMENT_REQUIRED" }] }
    };
  }

  const source = manifest.get(body.id);
  // 未知 ID 必须在执行器之前被拒绝,不能自动注册客户端文档。
  if (!source) {
    return {
      status: 403,
      body: { errors: [{ message: "TRUSTED_DOCUMENT_REQUIRED" }] }
    };
  }

  const result = await graphql({
    schema,
    source,
    rootValue,
    variableValues: body.variables ?? {}
  });

  return {
    status: result.errors ? 400 : 200,
    body: result
  };
}

const allowedId = documentId(trustedSources[0]);

console.log(JSON.stringify(
  await handleRequest({ id: allowedId, variables: {} })
));
console.log(JSON.stringify(
  await handleRequest({ id: "deadbeef", variables: {} })
));
console.log(JSON.stringify(
  await handleRequest({ query: trustedSources[0], variables: {} })
));

预期输出:

text
{"status":200,"body":{"data":{"viewer":{"id":"u-1","name":"Ada"}}}}
{"status":403,"body":{"errors":[{"message":"TRUSTED_DOCUMENT_REQUIRED"}]}}
{"status":403,"body":{"errors":[{"message":"TRUSTED_DOCUMENT_REQUIRED"}]}}

示例使用 403 表达“生产门禁不允许该文档”;实际系统也可以按网关约定选择其他 4xx 状态,但必须保证未知操作不会继续进入 GraphQL 解析与执行阶段。

防止白名单被旁路

白名单只限制“能执行哪份文档”,不能替代认证、授权和变量校验。一个被批准的列表查询如果允许客户端把 first 传到极大值,仍可能制造高成本操作,因此变量范围、分页上限和上一课的成本保护仍然需要保留。

还要检查是否存在第二入口,例如调试路由、旧版 /graphql、WebSocket 订阅端点或批处理端点。如果其中任何一个仍接受任意文档,主入口的 trusted documents 就不再构成完整边界。对开发环境开放任意查询时,也应使用独立配置而不是在生产代码中“未命中就回退”。

处理版本错配和回滚

服务端 manifest 与客户端版本必须按兼容顺序发布。Web 客户端通常可以先让服务端同时接受版本 N 与 N-1 的 ID,再发布 N 客户端,观察旧版本流量归零后删除 N-1;移动端升级更慢,保留窗口通常更长。

发布验证至少覆盖三类请求:当前版本合法 ID 应成功,未知 ID 应被拒绝,只有 query 文本而没有可信 ID 的请求也应被拒绝。这样才能证明白名单是执行前的硬门禁,而不是一个可以被自动注册、旧路由或回退逻辑绕开的缓存层。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用可信操作白名单

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通