plugin-auth: `convertWhere()` 整体忽略 better-auth 的 `Where.mode: 'insensitive'`(SCIM 会发它)

[baozhoutao]

实测于 origin/main@1624f4a,在实施 #5710 时发现。

Blocked-by: #5702($icontains 的执行面;今天写 $icontains 会被五个 driver 全部拒收/丢弃)

测到的东西

better-auth 1.7 的 Where 有第四个字段(@better-auth/core/src/db/adapter/index.ts:324-343):

mode?: "sensitive" | "insensitive" | undefined;   // @default "sensitive"

packages/plugins/plugin-auth/src/objectql-adapter.ts 的 convertWhere() 只读 condition.field / operator / value,从不读 mode。默认值是 "sensitive",所以绝大多数调用不受影响 —— 但显式要求不敏感的调用,其要求被静默丢弃,实际大小写行为退化成「当前 driver 恰好怎么做」。

谁会发 mode: 'insensitive'

@better-auth/scim(dist/index.mjs:566-576):对 caseExact === false 的 SCIM 属性,解析出的 where 条件会带上 mode: "insensitive"。userName 正是这样一个属性(SCIM 的 userName 按 RFC 7643 是大小写不敏感的),而 SCIM 今天只映射 eq(SCIMFilterOperatorMap = { eq: "eq" })。

后果:身份提供方用 userName eq "Alice@example.com" 查一个以 alice@example.com 存下的用户时,匹配与否取决于 driver —— 在大小写敏感的后端上查不到,而 SCIM 语义要求查得到。SCIM 的典型消费路径是「先查、查不到就建」,所以症状是重复用户而不是报错。

作用域:SCIM 默认关闭(OS_SCIM_ENABLED),所以今天只有开了 SCIM 的部署会碰到。

为什么现在还修不了

不敏感的包含匹配对应的算子是 $icontains,它今天是纯声明面:不在 FILTER_OPERATORS(packages/spec/src/data/filter.zod.ts:1066-1081 写明这是刻意分期),五个 driver 均不执行。所以在 #5702 给出执行面之前,adapter 无处可译。

更麻烦的一半:SCIM 发的是 eq + insensitive,而词表里没有「大小写不敏感的相等」算子 —— $icontains 是包含不是相等。所以本单落地时需要先回答一个契约问题:

1. 加一个 $ieq(词表扩张,要有真实业务拉动);
2. 或者把 eq + insensitive 降为 $icontains 再在应用层收窄(语义不等价,会多命中);
3. 或者判定「大小写不敏感的相等」由 SCIM 侧规范化(比如 userName 一律小写存储)来解决,adapter 侧不引入新算子。

个人倾向 3 → 1 的顺序:先看 SCIM 的实际部署是否已经靠规范化解决;只有在真实业务拉动出现时才扩词表(初创聚焦原则)。这需要维护者裁决,不是实施细节。

相关

• plugin-auth: better-auth 的 contains 被译成裸 $regex,用户输入当正则求值 —— 且是 $regex 退役唯一挡路的生产者 #5710(同一函数的 contains 支译成裸 $regex;已修)
• spec: $regex 按 ADR-0049 退役 + $icontains 入算子词表与 FILTER_LOGIC_CASES(#4706 裁决 B 案 · 契约半边,先行) #5701 Q1=A($icontains = ASCII-only 不敏感)/ Q2=A($contains 家族大小写敏感)
• drivers: $regex 响亮拒收 + $icontains 各后端实现(#4706 裁决 B 案 · 驱动半边) #5702(driver 侧下译 + $icontains 执行面)

[os-zhuang]

分诊:needs-user-decision + domain:identity。⛔ 不入 pm:queue。

落点锚定:packages/plugins/plugin-auth/src/objectql-adapter.ts ⇒ identity 行。(算子的执行半边在 packages/drivers/*,由 #5702 的 drivers 车道承担;本单只是 adapter 侧的翻译面。)

为什么是决策卡而不是缺陷单:正文自己把问题定在契约层,分诊核过后同意 —— SCIM 发的是 eq + insensitive,而词表里根本没有「大小写不敏感的相等」这个算子。三条路($ieq 扩词表 / 降级 $icontains 再收窄 / SCIM 侧规范化)分别是扩公共契约、接受语义不等价、改存储姿态,任一条都不是实施细节。按 step 0 的分类,这属于「产品语义 / 公共契约拍板类」。

过时前提检查(origin/main@846ed1f,实读):git grep -n "\.mode" packages/plugins/plugin-auth/src/objectql-adapter.ts ⇒ 唯一命中是 :138 的注释(Where.mode defaults to "sensitive"),即该字段只被注释提及、从未被读取 ✅ 前提成立。convertWhere 的算子链实读为 eq/ne/in/gt/gte/lt/lte/contains 八支,与 #5813 的读数一致。

依赖(已在正文,此处只作登记):Blocked-by: #5702(pm:queue + pm:blocked,drivers 车道,其自身又 Blocked-by #5701)。⚠️ 注意这是两道闸,顺序不能颠倒:即使 #5702 落地给出 $icontains 执行面,本单仍然要等上面那条裁决 —— 因为缺的不是执行面,是「不敏感的相等」这个算子在词表里不存在。故本轮只打决策标签;pm:blocked 未叠加,理由是解除阻塞也不会让它变得可派发,决策标签才是那个真正被选批读到的门。

作用域(给维护者定优先级用):SCIM 默认关闭(OS_SCIM_ENABLED),今天只有开了 SCIM 的部署受影响;症状是重复用户(先查后建、查不到就建)而非报错,所以是静默的,但不是广谱的。个人读法与正文一致:选项 3(SCIM 侧规范化)最省且不动词表,只有真实业务拉动出现时才走 1。

查重:三仓各搜一遍(convertWhere / insensitive / $icontains / SCIM)。#5710 已 closed(同函数的 contains 支,已修);#5701 / #5702 / #4706 是同族但各自半边,无重复入口;无影子单。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[claude]

处置(2026-08-06):改标 pm:on-hold。

理由:SCIM 默认关闭(OS_SCIM_ENABLED),零已知启用部署;方案 1 的 $ieq 词表扩张属零消费能力面(创业聚焦原则,先例 #5021/#4988/#4834);止血式响亮拒绝(3')会把「偶发重复」升级成「userName 查询全量不可用」,fail-closed 在此害大于利。

重启条件:(a) 出现开启 SCIM 的真实部署并报告大小写问题,或 (b) #5702 落地且 identity 车道有余量时重评。重启后默认方向:方案 3(SCIM 侧规范化存储/查询 + 存量迁移),仅真实业务拉动出现才升级方案 1($ieq);方案 2(降级 $icontains)否决——认证路径不接受语义不等价。

经办:PM 会话 session_01GcjbQLUQKysMU9uXB34iyv;维护者 2026-08-06 审阅决策简报后授权按建议执行(否决窗口:可评论/重开推翻)。

---

Generated by Claude Code

[os-zhuang]

【裁决落地】维护者 2026-08-06 批复全舰队决策箱评估报告(批复「同意」),本单裁定:

裁 3 → 1 分步:第一步走 3——SCIM 侧规范化存储(userName 等大小写不敏感字段存规范形),不动查询词表;$ieq 扩词表(1)仅当出现真实业务拉动时再启,2(降 $icontains 收窄)语义不等价,不做。

⚠️ Blocked-by: #5702(其上游 #5701/#5710)——裁决已给但暂不可实施,identity 车道待链条解锁后按本裁派发。

流转:摘 needs-user-decision → pm:blocked,归 identity 车道。

评估与落地会话:session_01N3uGFF8teXbpgtbEJ1aYXu

---

Generated by Claude Code