GraphQL持久化查询与Allowlist门禁（SHA256/签名/回退）最佳实践

背景与价值持久化查询可减少负荷并防止注入。结合Allowlist与签名治理，保证入口仅执行受控查询。统一规范哈希标识：统一使用 `sha256` 标识持久化查询。门禁策略：只允许白名单哈希；可选签名校验。受控回退：无哈希时可选择拒绝或受限回退。核心实现哈希与白名单type Persisted = { hash: string; query: string } const allow = new Map<string, string>() // hash -> query function validHash(h: string): boolean { return /^[a-f0-9]{64}$/.test(h) } function registered(h: string): boolean { return allow.has(h) } 签名校验（可选）async function importKey(spki: ArrayBuffer): Promise<CryptoKey> { return crypto.subtle.importKey('spki', spki, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']) } function enc(s: string): Uint8Array { return new TextEncoder().encode(s) } async function verifySig(key: CryptoKey, payload: string, sigB64: string): Promise<boolean> { const sig = Uint8Array.from(atob(sigB64.replace(/-/g,'+').replace(/_/g,'/')), c => c.charCodeAt(0)).buffer; return crypto.subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, key, sig, enc(payload)) } 执行门禁type Req = { headers: Record<string, string | undefined>; body: { hash?: string; query?: string; variables?: Record<string, any>; sig?: string } } async function gate(req: Req, pub?: CryptoKey): Promise<{ ok: boolean; query?: string }> { const h = req.body.hash || '' if (!validHash(h)) return { ok: false } if (!registered(h)) return { ok: false } const q = allow.get(h)! if (pub && req.body.sig) { const ok = await verifySig(pub, h, req.body.sig); if (!ok) return { ok: false } } return { ok: true, query: q } } 落地建议默认仅接受持久化查询；必要时开启签名校验以防哈希被劫持。无哈希请求按受控回退策略处理（例如拒绝或仅允许少量读查询）。验证清单哈希是否有效且命中白名单；签名是否验证通过；回退策略是否受控。