Hasura GraphQL Engine 中复用 Insert 权限做 Action 数据校验：RFC 方案解析与工程落地

后端API网关数据库GraphQL【免费下载链接】graphql-engineBlazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.项目地址https://gitcode.com/gh_mirrors/gr/graphql-engine点击查看免费下载本文围绕 rfcs/reuse-insert-permission-in-action.md 这一 RFC 展开当业务校验无法用 Hasura 的权限表达式或 Postgres 的 check 约束表达时如何借助 Actions 调用外部 webhook 完成校验同时不丢失原有 insert 权限如{channel: {members: {user_id: x-hasura-user-id}}}这类基于角色的行级约束的复用能力。读完本文你将掌握该 RFC 的问题背景、admin_only提案的完整语义以及仓库中已落地的输入验证input validations机制如何最终解决了同一类问题。一、RFC 要解决的核心矛盾1.1 场景用 Hasura 权限表达不了的校验设想一张消息表其结构如下RFC 原例create table message ( id serial primary key, content text not null, channel_id integer not null references channel(id) ) create table channel (..) create table channel_members (..)业务要求user角色只有在其所属频道的成员列表中时才能向该频道发消息。这一约束天然可以用 Hasura 的 insert 权限check表达式表达{channel: {members: {user_id: x-hasura-user-id}}}也就是说用户只能向channel_members中user_id等于当前会话变量x-hasura-user-id的频道发消息。但问题来了如果还要对message.content本身做复杂校验例如调用外部内容审核服务判断是否违规这类校验既写不进 Hasura 的权限布尔表达式也无法用 Postgres 的 check 约束完成check 约束只能引用当前行的列值不能调用外部服务。1.2 矛盾点为什么必须删掉 insert 权限RFC 指出在这种权限 外部校验并存的场景下推荐的做法是使用Actions开发者移除message表上user角色的 insert 权限把全部校验逻辑搬进 action 的 webhook handler 里。但这会带来一个明显的副作用webhook 现在不仅要做 content 的校验还必须自己重新实现{channel: {members: {user_id: x-hasura-user-id}}}这一原本由 Hasura 权限系统负责的约束——等于把权限逻辑从声明式配置退化成 webhook 里的命令式代码Hasura 权限系统的可复用性就此丢失。那么为什么必须移除 insert 权限而不能权限和 action 并存RFC 给出了关键原因如果 insert 权限被定义insert_message变更就会被自动生成任何持有user角色的人都能直接调用它从而绕过对message内容的校验。也就是说只要user角色对message表有 insert 权限GraphQL schema 的mutation_root上就会暴露insert_message字段客户端可以绕过 action 直接插入数据外部校验形同虚设。这正是复用 insert 权限于 action这一需求的原始动机。该问题最初在 Hasura 官方 Discord 频道被报告。二、RFC 提案insert 权限新增admin_only字段2.1 提案语义RFC 提出的解决方案是在 insert permission 中引入一个新字段admin_only行为一当某角色对该表的 insert 权限设置了admin_only时mutation_root上不再为该角色生成该表的 insert 变更字段普通客户端无法直接调用行为二但该 insert 变更在携带admin-secret的请求中仍然可用行为三action 的 handler 可以在调用 GraphQL Engine 时带上admin-secret并把x-hasura-role设置为用户的真实角色从而以该角色身份执行 insert使 insert 权限中定义的角色级约束check 条件照常生效——权限校验由 Engine 完成webhook 只需专注内容校验。2.2 与 GraphiQL角色模拟机制的关系RFC 特别指出当前 Engine 已经支持通过admin-secretx-hasura-role在 GraphiQL 中模拟某个角色发起请求。因此admin_only的 insert 变更将同样允许以admin-secret认证、以指定角色身份执行的请求通过。这意味着实现该提案时需要在文档中明确说明admin_secret配合x-hasura-role可以访问admin_only的插入变更这是有意为之的信任模型——只有持有admin-secret的后端如 action webhook才能以受约束的角色身份执行插入普通角色直接访问该字段则会被拒绝。2.3 设计权衡从 RFC 的表述可以提炼出该方案的核心权衡维度说明安全性admin_only从 schema 层面隐藏了角色的 insert 字段避免绕过外部校验权限复用通过admin-secretx-hasura-role继续使用声明式的角色 check 约束webhook 无需重复实现权限逻辑信任边界约束的正确性依赖admin-secret只被可信后端webhook持有文档义务需要向开发者说明admin_only变更在 GraphiQL 角色模拟场景下同样可执行三、仓库中的演进从 RFC 到输入验证Input Validations落地3.1 当前仓库中的实现现状需要说明的是在 graphql-engine 当前仓库的源码与文档中admin_only字段并未以该名字落地在server/src-lib与docs中均未检索到admin_only。从源码演进看该 RFC 所提出的insert 前执行外部 webhook 校验诉求最终由输入验证Input Validations机制在 v2.29.0 起落地实现。该机制允许在 insert/update/delete 权限上挂载validate_input配置把变更的输入参数在真正写库前路由到一个 HTTP webhook 做校验。其官方文档位于 docs/docs/schema/postgres/input-validations.mdx。3.2 与 RFC 方案的关系RFC 与落地机制解决的是同一类问题复杂数据校验但路径不同RFC 方案admin_only把直接 insert从角色 schema 中隐藏将插入委托给带admin-secret的 action handler让 Engine 代为执行角色约束——校验与插入分离在 action 的 webhook 与 Engine 两端落地机制validate_input把校验 webhook 直接挂在权限上由 Engine 在变更执行前先调用校验 webhook校验通过后才开启数据库事务写入——校验与插入统一由 Engine 编排无需隐藏 insert 字段也就不需要admin_only的 schema 隐藏语义。两者都需要一个共识前提webhook 校验失败时请求被中止并返回错误。RFC 中必须移除 insert 权限否则可被绕过的担忧在validate_input落地后由 Engine 的执行流程直接接管无需再移除权限。3.3 输入验证的配置方式实战以 Postgres 为例在 CLI 管理的 Metadata 文件metadata - databases - [database-name] - tables - [table-name].yaml中可以这样为一个角色的 insert 权限挂上校验 webhook- table: schema: public name: products insert_permissions: - role: user permission: columns: [] filter: {} validate_input: type: http definition: url: http://www.somedomain.com/validateProducts headers: - name: X-Validate-Input-API-Key value_from_env: VALIDATION_HOOK_API_KEY forward_client_headers: true timeout: 5各字段含义type校验接口类型当前支持httpwebhook URLdefinition.url必填校验 webhook 的 URLdefinition.headers可选随请求发送的自定义头value_from_env支持从环境变量取值definition.forward_client_headers是否把客户端请求头转发给校验 webhookdefinition.timeoutwebhook 超时时间秒可理解为该配置项的核心调优参数。应用 Metadatahasura metadata apply也可以通过 Metadata API 创建对应pg_create_(insert|update|delete)_permission见 server/src-lib/Hasura/RQL/DDL/Permission.hs 中buildInsPermInfo/buildUpdPermInfo对validateInput的解析POST /v1/metadata HTTP/1.1 Content-Type: application/json X-Hasura-Role: admin { type: pg_create_insert_permission, args: { source: db_name, table: products, role: user, permission: { columns: *, filter: {}, validate_input: { type: http, definition: { url: http://www.somedomain.com/validateProducts } } } } }3.4 执行流程官方文档明确了带校验的 insert 的执行顺序摘自 docs/docs/schema/postgres/input-validations.mdx 的流程说明变更输入参数会先被发送到校验 webhook对所有涉及的表都会执行数据库事务只在所有校验成功完成后才开始任一 webhook 拒绝数据请求被中止并返回错误信息。这意味着校验 webhook 是写入路径上的强制门禁——与 RFC 中action webhook 负责校验、Engine 负责权限的分工相比validate_input把两者统一在 Engine 的变更执行管线中。文档同时提示涉及校验的变更可能比无校验变更更慢webhook 执行时间是潜在瓶颈受timeout限制。四、仓库中的测试验证端到端校验 webhook仓库的 API 测试套件中有与该主题直接对应的端到端测试server/lib/api-tests/src/Test/Mutations/Insert/ValidationSpec.hs。该测试在 Postgres、Citus、CockroachDB 三个后端上运行同一套用例测试的建表与权限结构如下user表id / name / email / phone_number角色user_1拥有 insert 权限并挂载/validateUser校验 webhooktweet表id / content / user_id角色user_1拥有 insert 权限并挂载/validateTweet校验 webhook。测试用例覆盖的校验行为包括用例校验规则期望错误邮箱格式错误email 必须是合法邮箱Invalid email id random email手机号格式错误phone_number 必须合法Invalid phone number 987654321关联插入超过限制一个用户最多关联 1 条 tweetOnly one tweet is allowed to be added with a usertweet 内容超长content 不超过 30 字符Tweet should not contain more than 30 characters测试通过携带X-Hasura-Role: user_1请求头发起变更断言返回code: validation-failed错误证明校验 webhook 在权限生效的同时被强制执行。承载这些校验的测试 webhook 实现在 server/lib/test-harness/src/Harness/Webhook.hs 中其runInputValidationWebhook起了一个本地 Spock 服务提供/validateUser与/validateTweet两个校验端点从请求体$rows中提取数据后逐条执行校验逻辑任一失败即返回校验错误。这一实现恰好演示了 RFC 中action 的 handler / 校验 webhook 需要做内容级校验的最小落地形态。五、admin-secretx-hasura-role角色模拟的官方语义RFC 方案成立的关键前提是admin-secretx-hasura-role可模拟指定角色执行请求。这一机制在官方文档 docs/docs/auth/authentication/admin-secret-access.mdx 中有明确记载如果请求同时携带X-Hasura-Admin-Secret头以及X-Hasura-Role等用户特定头如X-Hasura-User-IdHasura GraphQL Engine 将使用该用户与角色对应的访问控制规则处理请求而不是以 admin 身份处理。这正是 RFC 中admin_only方案的核心依据action 的 handler持有admin-secret可以扮演任意角色发起插入从而让该角色在 insert 权限里声明的 check 约束例如频道成员关系由 Engine 强制执行。官方文档同时给出了安全警示admin-secret绝不能在面向用户的客户端暴露否则恶意用户可以通过检查请求获取它——这与 RFC 方案中admin_only的可达性依赖 admin-secret 只被可信后端持有的信任模型完全一致。相关的会话变量传递机制action 请求体中的session_variables如x-hasura-user-id、x-hasura-role可参见 docs/docs/actions/action-handlers.mdx 中关于 action 请求负载的说明。六、方案对比与选型建议综合 RFC 与仓库现状可以把两类实现路径放在一起对比维度RFC 方案admin_only action落地机制validate_input输入验证校验执行者action 的 webhook handler挂在权限上的校验 webhookEngine 统一编排insert 字段暴露角色 schema 中隐藏仅admin-secret可访问正常暴露但写库前必经校验门禁权限约束复用依赖admin-secretx-hasura-role角色模拟权限 check 与校验 webhook 并存无需移除权限信任边界要求admin-secret仅存于可信后端校验 webhook 必须被正确配置且可达落地状态RFC 提案当前仓库未以该字段名实现已实现文档见 input-validations.mdx测试见 ValidationSpec.hs选型建议如果你的场景只是在插入/更新/删除前调用外部服务做内容校验优先使用已经落地的validate_input机制它无需隐藏 insert 字段权限与校验天然共存如果你的场景是用 action 承担完整的数据写入含内容处理但希望角色级约束仍由 Engine 声明式执行RFC 的admin_only思路依然有参考价值——它揭示了admin-secretx-hasura-role角色模拟这一底层能力可用于在 action handler 内以受约束角色身份执行插入无论走哪条路都要守住同一条底线校验入口webhook / action handler与权限判定Engine不能被客户端绕过这正是 RFC 最初强调必须移除 insert 权限否则校验被绕过的教训所在。七、小结reuse-insert-permission-in-action.md这份 RFC 记录了一个小而典型的工程问题外部校验与声明式权限如何共存而不互相绕过。它提出的admin_only方案虽然未在当前仓库中以同名落地但其问题分析、信任模型admin-secretx-hasura-role角色模拟和校验失败即中止的执行语义都直接反映在仓库现已实现的输入验证机制及其测试中。理解这份 RFC有助于把握 Hasura 权限系统与 Actions 的分工边界也能在遇到权限表达不了 check 约束做不到的校验需求时快速定位到正确的实现路径。赞分享后端API网关数据库GraphQL【免费下载链接】graphql-engineBlazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.项目地址https://gitcode.com/gh_mirrors/gr/graphql-engine点击查看免费下载相关推荐GraphQL Engine 输入校验 RFC 深度解析用 validate_input Webhook 在 Mutation 落库前拦截非法数据GraphQL Engine 输入校验 RFC 深度解析用 validate_input Webhook 在 Mutation 落库前拦截非法数据 本文基于仓后端API网关数据库GraphQLHasura GraphQL Engine 继承角色权限改进技术解析从 RFC 到源码实现Hasura GraphQL Engine 继承角色权限改进技术解析从 RFC 到源码实现 本篇基于仓库中的技术规格文档 inherited roles im后端API网关数据库GraphQLHasura GraphQL Engine 中 Computed Field 的过滤、权限与排序能力解析Hasura GraphQL Engine 中 Computed Field 的过滤、权限与排序能力解析 本文基于 Hasura GraphQL Engine后端API网关数据库GraphQL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考