AIGC标识 API key 从生成到吊销:前缀、校验位、只存哈希,以及吊销后多久才真正失效(Node.js)

做付费 API 的时候,发 key 往往是最早写完、也最早被忘掉的一块。crypto.randomBytes(32).toString("hex") 生成一串,存进表里,请求进来 WHERE api_key = ? 查一下,就能跑了。直到第一次有客户来说「我的 key 好像被同事提交到公开仓库了」,才发现好几件事没想过:库里存的是不是明文?吊销以后多久才真正失效?客户要换 key,旧的能不能多撑一天,让他慢慢部署?

这篇按一把 key 从生成到吊销的顺序,把这些问题过一遍。后半段是重点:多台机器各自加了缓存以后,「吊销」到底什么时候生效,以及拒绝缓存一个看起来很合理的写法,怎么让别人把正常客户挡在门外。

先交代背景:我是 UsageRail 的三个创始人之一。UsageRail 给卖 API 的团队发 key、按客户限流和算额度,再用开发者自己的 Stripe 账号做 API 按量计费。文中的 key 格式和后面几个坑都来自我们自己的实现,代码是为这篇文章另写的简化版,只用 Node.js 内置模块(node:crypto、node:zlib、node:sqlite),在 Node 26.3 上跑过,输出原样贴出。

一、一把 key 拆成五段

我们用的格式长这样:

acme_live_29Hv1QhZLoUOeQc5Tl8Pgf1UzDmv57MPIMMRC6sQ4UKQCB

从左到右:

  • acme:前缀,一般是产品名,2 到 10 个小写字母或数字;
  • live:环境,live 或 test;
  • 29Hv1QhZ:8 位 key ID;
  • LoUOeQc5…RC6sQ:32 位 secret,真正要保密的只有这一段;
  • 4UKQCB:6 位校验位。

前缀和环境是给人看的:客户手上有好几家的 key,看前缀就知道是哪家的;test key 被配进生产环境,看一眼日志就能发现。前缀固定了,密钥扫描和日志脱敏也好按它写正则。GitHub 2021 年把 token 改成 ghp_ 这类带前缀的格式,Stripe 用 sk_live_ 和 sk_test_ 区分环境,都是这个考虑。

key ID 明文存在库里,它不是秘密。校验时按它查那一行,不用拿哈希去比一整张表;客户找客服时报 key ID 就够了,不用把整把 key 贴过来。

校验位是前面所有字符的 CRC32,转成 base62 后补齐到 6 位。它不是安全措施,CRC32 谁都会算。它挡的是抄错一个字符的 key 和随手乱填的字符串,这类请求在格式检查那一步就回 401,不用查库。我们官网上有个在浏览器里跑的 API key 生成器,生成的就是这个格式,旁边可以粘一把 key 进去,改一个字符就能看到校验失败。

生成和解析的代码:

import { createHash, randomBytes } from "node:crypto";
import { crc32 } from "node:zlib";

const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";

// 256 不是 62 的整数倍,直接 byte % 62 会让前 8 个字符出现得多一点。
// 248 = 62 × 4,大于等于 248 的字节丢掉不用
function randomBase62(length) {
  let out = "";
  while (out.length < length) {
    for (const byte of randomBytes(length * 2)) {
      if (byte < 248) out += BASE62[byte % 62];
      if (out.length === length) break;
    }
  }
  return out;
}

function toBase62(value, width) {
  let out = "";
  do {
    out = BASE62[value % 62] + out;
    value = Math.floor(value / 62);
  } while (value > 0);
  return out.padStart(width, "0");
}

export const checksum = (body) => toBase62(crc32(body), 6);

export function generateKey(prefix, env) {
  const keyId = randomBase62(8);
  const body = `${prefix}_${env}_${keyId}${randomBase62(32)}`;
  return { key: body + checksum(body), keyId };
}

const KEY_RE = /^([a-z0-9]{2,10})_(live|test)_([0-9A-Za-z]{8})([0-9A-Za-z]{32})([0-9A-Za-z]{6})$/;

// 格式和校验位都对才返回 key ID,否则返回 null。这一步不碰数据库
export function parseKey(key) {
  const m = KEY_RE.exec(key);
  if (!m || checksum(key.slice(0, -6)) !== m[5]) return null;
  return { env: m[2], keyId: m[3] };
}

export const sha256Hex = (text) => createHash("sha256").update(text).digest("hex");

有两处要注意。随机数必须来自 crypto.randomBytes,不能用 Math.random()。另外是 base62 的取模:一个字节有 256 种取值,256 不是 62 的整数倍,直接 byte % 62 的话,前 8 个字符出现的概率会比别的字符略高。代码里把 248 及以上的字节丢掉,248 正好是 62 的 4 倍。32 位 base62 大约是 190 bit 的随机性,比常说的 128 bit 下限高出不少。zlib.crc32 是 Node 较新的版本才内置的,老版本得自己写查表。

二、库里存什么

CREATE TABLE api_keys (
  key_id       TEXT PRIMARY KEY,     -- 明文存,不是秘密
  key_hash     TEXT NOT NULL,        -- SHA-256(完整 key),hex
  customer_id  TEXT NOT NULL,
  name         TEXT NOT NULL,
  created_at   INTEGER NOT NULL,     -- 毫秒时间戳,Postgres 里用 timestamptz
  expires_at   INTEGER,              -- 轮换时才设
  revoked_at   INTEGER,
  last_used_at INTEGER
);
CREATE INDEX api_keys_by_customer ON api_keys (customer_id);

完整的 key 不进库。库里存的是 SHA-256(完整 key),原文只在创建时给客户看一次,之后谁也拿不回来,丢了只能换一把新的。这样即使库被拖走,对方拿到的哈希也不能直接拿去调你的 API。

这里用 SHA-256 而不是 bcrypt,是因为两者要防的东西不一样:慢哈希是给人设的弱密码准备的,190 bit 的随机串用多快的哈希都猜不出来;而 key 每个请求都要校验一次,换成慢哈希只会拖慢正常请求。

last_used_at 在出事时用得上:客户说 key 可能泄露了,先看它最近一次被用是什么时候。生产环境里别每个请求都写一次这一列,可以在内存里攒着,或者距上次更新超过一分钟再写。

还有一条很容易漏:key 原文不能进日志。请求日志里记 key ID,错误上报时把 Authorization 头去掉。

三、校验的顺序

完整的 store.mjs,后面几节都用它:

import { readFileSync } from "node:fs";
import { DatabaseSync } from "node:sqlite";
import { timingSafeEqual } from "node:crypto";
import { generateKey, parseKey, sha256Hex } from "./keys.mjs";

const HOUR = 3600_000;
const MAX_ACTIVE_KEYS = 10;
const CLOCK_MARGIN = 30_000; // 比过期时间早 30 秒判失效,抵消各台机器的时钟误差

export function openDb() {
  const db = new DatabaseSync(":memory:");
  db.exec(readFileSync(new URL("./schema.sql", import.meta.url), "utf8"));
  return db;
}

// 「有效」= 没吊销,且没设过期或者还没到期
const ACTIVE = "revoked_at IS NULL AND (expires_at IS NULL OR expires_at > ?)";

export function createKey(db, customerId, name, now) {
  const { n } = db.prepare(`SELECT count(*) AS n FROM api_keys WHERE customer_id = ? AND ${ACTIVE}`).get(customerId, now);
  if (n >= MAX_ACTIVE_KEYS) throw new Error("key_limit_reached");
  const { key, keyId } = generateKey("acme", "live");
  db.prepare("INSERT INTO api_keys (key_id, key_hash, customer_id, name, created_at) VALUES (?, ?, ?, ?, ?)")
    .run(keyId, sha256Hex(key), customerId, name, now);
  return { key, keyId }; // 完整 key 只在这里出现一次
}

export function verifyKey(db, rawKey, now) {
  const parsed = parseKey(rawKey ?? "");
  if (!parsed) return { ok: false, reason: "bad_format" }; // 没查库
  const row = db.prepare("SELECT * FROM api_keys WHERE key_id = ?").get(parsed.keyId);
  const hash = Buffer.from(sha256Hex(rawKey), "hex");
  if (!row || !timingSafeEqual(Buffer.from(row.key_hash, "hex"), hash)) {
    return { ok: false, reason: "unknown_key" };
  }
  if (row.revoked_at !== null) return { ok: false, reason: "revoked", customerId: row.customer_id };
  if (row.expires_at !== null && row.expires_at - CLOCK_MARGIN <= now) {
    return { ok: false, reason: "expired", customerId: row.customer_id };
  }
  db.prepare("UPDATE api_keys SET last_used_at = ? WHERE key_id = ?").run(now, row.key_id);
  return { ok: true, customerId: row.customer_id, keyId: row.key_id };
}

export function rotateKey(db, keyId, now, graceMs = 24 * HOUR) {
  if (graceMs < HOUR || graceMs > 30 * 24 * HOUR) throw new Error("grace must be 1h..30d");
  const old = db.prepare("SELECT * FROM api_keys WHERE key_id = ?").get(keyId);
  // 已经在倒计时里的不再轮换:该换的是轮换出来的那把新 key
  if (!old || old.revoked_at !== null || old.expires_at !== null) throw new Error("not_rotatable");
  // 旧 key 在宽限期里还占名额,所以轮换可以临时超出上限,但只能多一把
  const { n } = db.prepare(`SELECT count(*) AS n FROM api_keys WHERE customer_id = ? AND ${ACTIVE}`).get(old.customer_id, now);
  if (n > MAX_ACTIVE_KEYS) throw new Error("key_limit_reached");
  const { key, keyId: newKeyId } = generateKey("acme", "live");
  db.exec("BEGIN");
  db.prepare("UPDATE api_keys SET expires_at = ? WHERE key_id = ?").run(now + graceMs, keyId);
  db.prepare("INSERT INTO api_keys (key_id, key_hash, customer_id, name, created_at) VALUES (?, ?, ?, ?, ?)")
    .run(newKeyId, sha256Hex(key), old.customer_id, old.name, now);
  db.exec("COMMIT");
  return { key, keyId: newKeyId };
}

export function revokeKey(db, keyId, now) {
  db.prepare("UPDATE api_keys SET revoked_at = ? WHERE key_id = ? AND revoked_at IS NULL").run(now, keyId);
}

verifyKey 的顺序是:格式和校验位 → 按 key ID 查那一行 → 比较哈希 → 吊销和过期。

  • 格式不对就直接返回,一次数据库都不碰。
  • 哈希比较用 timingSafeEqual。比的是哈希,计时攻击能拿到的东西其实很有限,但它没有成本,没理由不用。
  • 过期判断提前 30 秒。几台机器的时钟不会完全一致,宁可早半分钟失效,也别让某台机器多放行。
  • 哈希已经对上、只是吊销或过期了,返回里带上 customerId。这时候我们知道是谁,401 可以记在这个客户名下,客服查「为什么突然 401」时有据可查。

跑一下(run-basic.mjs 前半段):

新 key: acme_live_29Hv1QhZLoUOeQc5Tl8Pgf1UzDmv57MPIMMRC6sQ4UKQCB
库里存的: [Object: null prototype] {
  key_id: '29Hv1QhZ',
  key_hash: 'dc98bf23105567bc3fede80d6b342cce11cb80a1a8722047b9620064f3274ec8',
  customer_id: 'cus_42'
}
正确的 key       { ok: true, customerId: 'cus_42', keyId: '29Hv1QhZ' }
改了一个字符      { ok: false, reason: 'bad_format' }
真 ID + 假 secret { ok: false, reason: 'unknown_key' }

第三个 key 是拿真 key 的前 18 个字符(前缀加 key ID)配一段随机 secret,再按规则算好校验位拼出来的。格式检查照样放行,最后靠哈希比较才拦下,这就是校验位不算安全措施的原因。

四、轮换:新旧 key 并存一段时间

客户换 key 时最怕新 key 还没部署完,旧 key 已经失效。所以轮换是新建一把,同时给旧的设一个过期时间,默认 24 小时,可以设 1 小时到 30 天,见上面的 rotateKey。

轮换和名额要放在一起想。每个客户最多 10 把有效 key,旧 key 在宽限期里仍然有效,也仍然占名额。如果轮换受名额限制,已经用满 10 把的客户就没法轮换;如果完全不管,对同一把 key 反复轮换就能变出任意多把。代码里的折中是轮换可以临时超出上限,但只能多一把,已经在倒计时里的 key 也不能再轮换。

轮换后 23 小时,旧 key { ok: true, customerId: 'cus_42', keyId: '29Hv1QhZ' }
轮换后 23 小时,新 key { ok: true, customerId: 'cus_42', keyId: 'ARWEk4hP' }
轮换后 24 小时,旧 key { ok: false, reason: 'expired', customerId: 'cus_42' }
再轮换旧 key: not_rotatable
吊销后,新 key    { ok: false, reason: 'revoked', customerId: 'cus_42' }
第 11 把: key_limit_reached
轮换 k0:成功
再轮换 k1: key_limit_reached

五、泄露以后:吊销到底多久生效

先说一个常见的误用:确认泄露时不要用轮换。轮换给旧 key 留了宽限期,泄露的 key 在这段时间里照样能用。应该直接吊销,再给客户建一把新的。

单机直接查库的话,revoked_at 一提交,下一个请求就会被拒。但生产环境很少这么跑,每个请求查一次库太贵,于是会在每个应用实例里加一层缓存。加了缓存,吊销的生效时间就变成了缓存的 TTL。

下面是一种很常见的写法:通过的结果按完整 key 的哈希缓存 60 秒,拒绝的结果也缓存 60 秒,免得有人拿乱填的 key 一直打数据库。

import { parseKey, sha256Hex } from "./keys.mjs";
import { verifyKey } from "./store.mjs";

// 每个应用实例在数据库前面挡一层缓存
export class CachedVerifier {
  constructor(db, { ttl = 60_000, rejectTtl = 60_000, rejectBy = "id+hash" } = {}) {
    Object.assign(this, { db, ttl, rejectTtl, rejectBy });
    this.accepted = new Map(); // 完整 key 的哈希 -> 校验结果
    this.rejected = new Map(); // 见 rejectKey()
  }

  rejectKey(keyId, hash) {
    return this.rejectBy === "id" ? keyId : `${keyId}:${hash}`;
  }

  verify(rawKey, now) {
    const parsed = parseKey(rawKey ?? "");
    if (!parsed) return { ok: false, reason: "bad_format" };
    const hash = sha256Hex(rawKey);

    const hit = this.accepted.get(hash);
    if (hit && now < hit.cachedUntil) return hit.result;

    const rejectedUntil = this.rejected.get(this.rejectKey(parsed.keyId, hash));
    if (rejectedUntil && now < rejectedUntil) return { ok: false, reason: "cached_reject" };

    const result = verifyKey(this.db, rawKey, now);
    if (result.ok) this.accepted.set(hash, { result, cachedUntil: now + this.ttl });
    else this.rejected.set(this.rejectKey(parsed.keyId, hash), now + this.rejectTtl);
    return result;
  }
}

测试脚本 run-cache.mjs 用的是假时钟,不用真等一分钟:

import { checksum, generateKey } from "./keys.mjs";
import { createKey, openDb, revokeKey } from "./store.mjs";
import { CachedVerifier } from "./cache.mjs";

const t0 = Date.parse("2026-11-16T09:00:00Z");
const sec = (s) => t0 + s * 1000;
const db = openDb();

// 1. 吊销以后,缓存里的结果还能用多久
const leaked = createKey(db, "cus_42", "ci", sec(0));
const instance = new CachedVerifier(db, { ttl: 60_000 });
console.log("t=0   ", instance.verify(leaked.key, sec(0)).ok);
revokeKey(db, leaked.keyId, sec(1));
console.log("t=1   吊销");
console.log("t=30  ", instance.verify(leaked.key, sec(30)).ok);
console.log("t=61  ", instance.verify(leaked.key, sec(61)).ok);

// 2. 拒绝结果只按 key ID 缓存的后果
const fresh = createKey(db, "cus_7", "production", sec(100));
const forgedBody = fresh.key.slice(0, 18) + generateKey("acme", "live").key.slice(18, 50);
const forged = forgedBody + checksum(forgedBody);

for (const rejectBy of ["id", "id+hash"]) {
  const node = new CachedVerifier(db, { rejectBy });
  node.verify(forged, sec(100));               // 攻击者先发一个伪造的
  const real = node.verify(fresh.key, sec(105)); // 5 秒后客户用真 key
  console.log(`按 ${rejectBy.padEnd(7)} 缓存拒绝:真 key ->`, real);
}

输出:

t=0    true
t=1   吊销
t=30   true
t=61   false
按 id      缓存拒绝:真 key -> { ok: false, reason: 'cached_reject' }
按 id+hash 缓存拒绝:真 key -> { ok: true, customerId: 'cus_7', keyId: 'nNtYSE2p' }

前四行是吊销:第 1 秒就吊销了,这台实例到第 61 秒才开始拒绝。每台实例写缓存的时刻不一样,实例越多,全部失效的时间拖得越散。客户点了吊销,到这把 key 真正没用,中间隔着一个 TTL,这个数应该写进文档。

想缩短它,可以把 TTL 调短(查库变多),可以吊销时广播清缓存(多一套消息通道),也可以像我们的 SDK 那样,让每个实例在内存里放一份 key 列表(只有 key ID、哈希、状态和过期时间),每 15 秒增量同步一次,正常情况下吊销后约 20 秒全部生效。怎么选都行,但这个数你自己得清楚。

后两行是拒绝缓存的问题。只按 key ID 缓存拒绝结果,乍看很合理:这把 key 刚被拒过,60 秒内就别再查了。问题在于 key ID 不是秘密,它会出现在日志、控制台截图、客服工单里。有人拿到某个客户的 key ID,配一段随便的 secret,自己算好校验位发一次请求,这个 key ID 就进了拒绝缓存。接下来 60 秒,客户拿真 key 来也会被拒,对方每分钟发一次就能一直挡着。改成按「key ID + 哈希」记,伪造的请求只会挡住它自己那个组合。我们 SDK 里的拒绝缓存就是这么记的,代码注释里专门写了为什么不能只按 key ID。

六、几个容易漏的地方

删除过期 key 要留墓碑。 吊销和过期的 key 迟早要从表里清掉。如果各实例靠增量同步拿变更,直接 DELETE 掉的话,增量里看不到这次删除,手里有这把 key 的实例会一直留着它。我们的做法是删除时写一条墓碑,保留 30 天;实例的同步游标超过 7 天没更新,就不给增量,直接发全量。

从备份恢复数据库,吊销会被撤销。 恢复点之后吊销的 key,在恢复出来的库里又变回有效。我们把吊销、停用客户这类操作先写进一份只追加的重放日志,写成功了才改库;恢复以后先把日志补一遍,再启动服务。

新建 key 时通知客户本人。 key 不一定是客户自己建的,可能是同事,也可能是拿到他账号的人。我们在新 key 创建时给客户发邮件,不是他建的可以马上吊销。邮件只发给验证过邮箱的客户,不然任何人都能借这封信往任意地址发邮件。

吊销要随时能做。 账号欠费、只读或降级的时候,很多操作会被锁住,但吊销 key、停用客户这类收紧权限的操作不能锁,否则泄露的 key 收不回来。

最后

UsageRail 把 key 列表同步到每个实例,SDK 在你的 API 进程里校验已经同步到的 key,还没同步到的新 key 才去问服务端;客户可以在门户里自己建、轮换和吊销 key。自己实现的话,上面的简化代码可以当参考。换到 Postgres 要改数据库调用和时间类型,last_used_at 最好改成批量写。

作者:Super Lede,UsageRail 联合创始人。

posted @ 2026-11-17 12:23  superma11  阅读(4)  评论(0)    收藏  举报