@oj-bin/oj-aarch64-apple-darwin 0.1.13

package/devkit/global.d.ts

@@ -0,0 +1,332 @@
+// .route 声明的 TS 支持（编辑器不报错；dev server 不依赖此文件运行）。
+//
+// 下面为 src/bridge/bootstrap.js 在运行时注入的全局对象提供类型声明，
+// 使 sample/src 中的业务代码在编辑器内不报 TS 错误。
+//
+// ext_boot.js（config.yaml 同目录，可选）在运行时补充的全局**不在本文件声明** ——
+// 它们是项目自定义的，框架无法预知。用 ext_boot.js 增补了全局（如 `json.page()`）后，
+// 在业务项目里另建一个 .d.ts 自行声明（并加进 tsconfig 的 include），否则编辑器报
+// TS2339 "Property 'page' does not exist"。运行时不受影响——类型只影响编辑器与 tsc。
+
+// JSON 反序列化后可能出现的值（SQL 行 / KV / fetch body 等）。
+type Json = string | number | boolean | null | Json[] | { [k: string]: Json };
+
+// 数据库查询返回的一行（列名 -> 值）。
+type Row = Record<string, Json>;
+
+// db.table(...).where(cond) 的单个条件。
+interface WhereCond {
+  field: string;
+  op?: string; // eq/neq/gt/gte/lt/lte/like/in/... 依服务端支持
+  value?: unknown;
+  and?: WhereCond[];
+  or?: WhereCond[];
+}
+
+// db.table(...).orderBy(items) 的单个排序项。
+interface OrderByItem {
+  field: string;
+  dir?: "asc" | "desc" | null;
+}
+
+// db.table(name) 返回的安全查询构造器（流式、结构化）。
+interface QueryBuilder {
+  select(cols?: string[]): QueryBuilder;
+  where(cond: WhereCond): QueryBuilder;
+  orderBy(items?: OrderByItem[]): QueryBuilder;
+  limit(n: number): QueryBuilder;
+  offset(n: number): QueryBuilder;
+  all(): Promise<Json[]>;
+}
+
+// DB(name) 返回的命名数据库实例。
+interface DBInstance {
+  // 原始 SQL + 绑定参数（params 可选）。返回行数组。
+  query(sql: string, params?: unknown[]): Promise<Row[]>;
+  // 执行写操作，返回受影响行数。
+  exec(sql: string, params?: unknown[]): Promise<number>;
+  // 安全查询构造器（标识符白名单 + 参数化值）。
+  table(name: string): QueryBuilder;
+  // 事务：回调 resolve 提交 / throw 回滚再抛；tx.query/exec/table 同签名走同一连接。
+  // 每请求至多一个活跃事务（嵌套报错）；请求结束未完结自动回滚。
+  tx(fn: (tx: DBInstance) => unknown): Promise<unknown>;
+}
+
+// json.* ：统一响应信封 + 响应头。
+interface JsonApi {
+  ok(data?: unknown): void;
+  fail(code: number, msg: string, data?: unknown): void;
+  header(name: string, value: string): void;
+}
+
+// http.* ：当前请求上下文（只读，懒加载，per-request 最新）。
+interface HttpApi {
+  method: string;
+  params: Record<string, string>;
+  query: Record<string, string>;
+  headers: Record<string, string>;
+  body: any;
+  // 取路由参数或 query 参数：路径参数优先，query 兜底，均缺失返回 def 原值。
+  param(name: string, def?: unknown): any;
+  // 租户 id（tenant 启用时从租户头提取；未启用为 null）。
+  tenantId: string | null;
+  // 已验签用户（auth 启用且通过 Bearer 守卫；否则 null）。
+  user: AuthUser | null;
+  // multipart 上传文件元信息（非 multipart 为空数组）。
+  files: UploadedFileMeta[];
+  // 取第 i 个上传文件的字节（越界报错 no such file）。
+  file(i: number): Promise<Uint8Array>;
+}
+
+// 已验签用户（JWT claims）。
+interface AuthUser {
+  id: string | number;
+  roles: string[];
+  claims: Record<string, Json>;
+}
+
+// multipart 上传文件元信息。
+interface UploadedFileMeta {
+  field: string;
+  filename: string;
+  content_type: string;
+  size: number;
+}
+
+// log.* ：结构化日志（zap SugaredLogger 风格：msg + 交替键值对）。
+interface Logger {
+  debug(msg: string, ...kv: unknown[]): void;
+  info(msg: string, ...kv: unknown[]): void;
+  warn(msg: string, ...kv: unknown[]): void;
+  error(msg: string, ...kv: unknown[]): void;
+}
+
+// redis.* / kv.* ：KV 存储（redis.default 配置即真 Redis，否则进程内存 KV）。
+interface KVApi {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<boolean>;
+  del(key: string): Promise<boolean>;
+  // 设过期（秒）。真 Redis 走 EXPIRE；内存 KV 惰性过期。
+  expire(key: string, ttlSec: number): Promise<boolean>;
+  // 自增返回新值（键不存在从 0 起）。
+  incr(key: string): Promise<number>;
+}
+
+// ws.* ：WebSocket 生命周期钩子内的主动发送/关闭控制（HTTP 路径 no-op）。
+interface WSApi {
+  send(data: string): void;
+  close(): void;
+}
+
+// blob.* ：对象存储（可调用取命名实例：blob("media").put(...)；裸调用 blob.put(...) 等价 default）。
+interface BlobApi {
+  (name?: string): BlobApi;
+  put(key: string, bytes: Uint8Array, contentType?: string): Promise<boolean>;
+  get(key: string): Promise<Uint8Array>;
+  // 幂等：不存在视为成功。
+  del(key: string): Promise<boolean>;
+  // local = {base}/blob/{key}；s3 = presigned URL（15min）。
+  url(key: string): Promise<string>;
+  // local 缺失 sidecar 且无法按扩展名推断时返回空串；s3 无 Content-Type 时返回 null。
+  contentType(key: string): Promise<string | null>;
+}
+
+// bus.* ：主题广播。publish 广播给订阅 topic 的全部 WS 会话，返回接收方数；
+// subscribe 仅 WS 会话内可用（HTTP 路径报错）；kind 报告活跃 broker 类型。
+interface BusApi {
+  publish(topic: string, data?: unknown): Promise<number>;
+  subscribe(topic: string): Promise<void>;
+  kind(): Promise<string>;
+}
+
+// cert.* ：JWS 证书生成/重签（RSA + RS256 在 Rust 侧；纯内存，不落盘）。
+interface CertApi {
+  // 生成密钥对并签发 JWS。bits >= 2048；nbf/exp 为 Unix 秒，exp 必须 > nbf。
+  generate(
+    bits: number,
+    nbf: number,
+    exp: number,
+  ): Promise<{ private_pem: string; public_pem: string; cert_jws: string }>;
+  // 用现有 PKCS#8 私钥重签续期（公钥不变），返回新 cert.jws 串。
+  renew(privatePem: string, nbf: number, exp: number): Promise<string>;
+}
+
+// es.* ：Elasticsearch 薄客户端（直通 ES 响应体；未配置调用报 es not configured）。
+interface EsApi {
+  search(index: string, dsl?: unknown): Promise<Json>;
+  index(index: string, id: string, doc?: unknown): Promise<Json>;
+  del(index: string, id: string): Promise<Json>;
+}
+
+// jwt.* ：JWT 签发/验签（secret/alg/durations 由 config auth: 注入；未配置调用报
+// jwt not configured）。iat/exp 由 Rust 补（JS 不可控有效期），exp 取 access 时长。
+interface JwtApi {
+  // payload 至少含 sub；roles 可选（缺省空数组）。返回签名 token。
+  sign(payload: { sub: string; roles?: string[] }): string;
+  // 验签 + exp（leeway 0）；篡改/过期/算法不符直接抛错。
+  verify(token: string): { sub: string; roles: string[]; iat: number; exp: number };
+  // 配置的有效期（秒；getter 惰性求值）。
+  readonly accessDuration: number;
+  readonly refreshDuration: number;
+}
+
+// oidc.* ：内置 OP/RP（RS256 私钥只在 Rust 侧；issuer/rp/clients 由 config oidc: 注入；
+// 未配置段调用报 oidc not configured）。verify 传 jwks 时按其 RS256 kid 匹配验签，
+// 不传（或 null）回落本地私钥；篡改/过期/无匹配钥直接抛错。
+interface OidcApi {
+  // claims 至少含 iss/sub/aud/iat/exp。返回签名 token。
+  sign(claims: Record<string, unknown>): string;
+  // 验签 + exp；jwks 可选（缺省用本地钥）。
+  verify(token: string, jwks?: unknown): Record<string, unknown>;
+  // 本地公钥 JWKS（keys[0].kid/kty/alg/n/e）。
+  jwks(): unknown;
+  // config oidc.issuer（getter 惰性求值）。
+  readonly issuer: string;
+  // RP 侧 tenant → IdP 配置。
+  readonly rp: Record<string, { issuer: string; client_id: string; client_secret: string; scope: string }>;
+  // OP 侧客户端白名单。
+  readonly clients: Record<string, { secret: string; redirect_uris: string[]; tenant: string }>;
+}
+
+// bcrypt.* ：密码哈希（Rust 侧 spawn_blocking，CPU 密集不卡 isolate）。
+interface BcryptApi {
+  hash(password: string, cost?: number): Promise<string>;
+  // 非法 hash 返回 false（不抛错）。
+  verify(password: string, hash: string): Promise<boolean>;
+}
+
+declare global {
+  interface Function {
+    route?: string;
+  }
+
+  const json: JsonApi;
+  const http: HttpApi;
+  const log: Logger;
+  const kv: KVApi;
+  const redis: KVApi;
+  const ws: WSApi;
+  const blob: BlobApi;
+  const bus: BusApi;
+  const es: EsApi;
+
+  // 命名数据库实例；未配置的名字返回 undefined。
+  function DB(name: string): DBInstance | undefined;
+  // 默认（"default"）数据库实例。
+  const db: DBInstance;
+  const cert: CertApi;
+  const jwt: JwtApi;
+  const oidc: OidcApi;
+  const bcrypt: BcryptApi;
+
+  // crypto 增补（bootstrap 对原生 crypto 做 Object.assign 合并，原生成员保留）：
+  // sha256Hex = 十六进制摘要；randomHex = nBytes 字节随机数的 hex（默认 32 字节）。
+  interface Crypto {
+    sha256Hex(s: string): string;
+    randomHex(nBytes?: number): string;
+  }
+
+  // ---- oj test L1 测试 SDK（oj test 运行时注入；仅测试文件使用） ----
+  // 进程内 HTTP 派发助手，对标 Go Fiber app.Test：client.get/post/... 触发真实
+  // 路由 + 真实运行时 + 真实后端（零 TCP）。path 为相对 base 的路径（如 "/user/account"）。
+  interface ClientResp {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+    upgrade: boolean;
+  }
+  interface ClientOptions {
+    headers?: Record<string, string>;
+    body?: string;
+  }
+  interface Client {
+    get(path: string, opts?: ClientOptions): Promise<ClientResp>;
+    post(path: string, opts?: ClientOptions): Promise<ClientResp>;
+    put(path: string, opts?: ClientOptions): Promise<ClientResp>;
+    del(path: string, opts?: ClientOptions): Promise<ClientResp>;
+    patch(path: string, opts?: ClientOptions): Promise<ClientResp>;
+    head(path: string, opts?: ClientOptions): Promise<ClientResp>;
+    options(path: string, opts?: ClientOptions): Promise<ClientResp>;
+    // 登录助手：POST /auth/login → 返回 access_token（失败抛错）。headers 透传（如租户头）。
+    login(username: string, password: string, headers?: Record<string, string>): Promise<string>;
+  }
+  const client: Client;
+
+  // 轻量测试框架（vitest 风格子集）：describe/it/expect/beforeEach。
+  function describe(name: string, fn: () => void): void;
+  function it(name: string, fn: () => void | Promise<void>): void;
+  function beforeEach(fn: () => void | Promise<void>): void;
+  function expect(actual: unknown): {
+    toBe(e: unknown): void;
+    toEqual(e: unknown): void;
+    toBeTruthy(): void;
+    toBeFalsy(): void;
+    toContain(sub: unknown): void;
+  };
+
+  // 标记会话结束。
+  function finish(): void;
+  // CJS 同步 require（eval + 进程级缓存）。
+  function __ojRequire(name: string, referrerPath?: string): any;
+  // 浏览器兼容的 fetch（url 必填，options 同 RequestInit 的常用子集）。
+  function fetch(url: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string | null;
+  }): Promise<OjFetchResponse>;
+  // 已加载插件自省：[{name, semver, abi_version, fingerprint, host_abi_version}]。
+  function plugins(): any[];
+
+  // 命名 MQ 客户端（config kafkas:/rabbits: 段；未配置的名 → undefined）。
+  // 消费方法（poll/commit/ack/nack）仅长任务上下文可用（HTTP/WS 内调用报错）。
+  function Kafka(name: string): OjKafkaClient | undefined;
+  function RabbitMQ(name: string): OjRabbitClient | undefined;
+  // 长任务上下文（对象全局）：stopping = 停机信号（HTTP/WS 上下文恒 false）；
+  // sleep = 等待原语（本运行时无 timer 全局，setTimeout 不可用）。
+  const tasks: {
+    stopping(): boolean;
+    sleep(ms: number): Promise<void>;
+  };
+}
+
+interface OjMqMessage {
+  topic: string;
+  partition?: number;
+  offset?: number;
+  key?: string;
+  value: any;
+  headers?: Record<string, string>;
+  ts?: number;
+  delivery_tag?: number; // rabbit 专属：ack/nack 载荷原样回传
+}
+
+interface OjKafkaClient {
+  kind(): Promise<string>;
+  send(topic: string, o: { key?: string; partition?: number; headers?: Record<string, string>; value: any }): Promise<{ sent: number }>;
+  poll(topics: string[], o?: { max?: number; timeoutMs?: number }): Promise<{ messages: OjMqMessage[] }>;
+  commit(m: OjMqMessage): Promise<Record<string, never>>;
+  metadata(): Promise<any>;
+}
+
+interface OjRabbitClient {
+  kind(): Promise<string>;
+  publish(exchange: string, routingKey: string, value: any, o?: { headers?: Record<string, string> }): Promise<{ sent: number }>;
+  poll(queues: string[], o?: { max?: number; timeoutMs?: number }): Promise<{ messages: OjMqMessage[] }>;
+  ack(m: OjMqMessage): Promise<Record<string, never>>;
+  nack(m: OjMqMessage, requeue?: boolean): Promise<Record<string, never>>;
+  metadata(): Promise<any>;
+}
+
+// fetch 返回的 Response（浏览器风格子集）。
+interface OjFetchResponse {
+  ok: boolean;
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  json(): Promise<Json | null>;
+  text(): Promise<string>;
+  arrayBuffer(): Promise<Uint8Array>;
+  clone(): OjFetchResponse;
+}
+
+export {};

package/devkit/oidc-implementation.md

@@ -0,0 +1,177 @@
+# OIDC 实现文档（OP + RP 双角色）
+
+> 实现走读：sample 内置 OIDC 的架构、时序与数据流。接入视角见
+> [oidc-integration.md](oidc-integration.md)，设计裁决见
+> `docs/superpowers/specs/2026-09-05-sample-oidc-design.md`。
+
+## 1. 总体架构
+
+同进程双角色：`src/idp/` 是 OP（OIDC Provider，签发身份），`src/oidc/` 是 RP
+（Relying Party，消费身份）。两者共享 core 注入的 `oidc` 全局（RS256 原语 + 配置态）
+与 KV；会话桥接复用既有 `auth` 模块的 `issueTokens`。业务请求鉴权不变——oj-auth 插件
+Bearer 守卫 + 租户头照旧，OIDC 只负责「换 token」那一跳。
+
+```mermaid
+flowchart TD
+    subgraph Client["浏览器 / 调用方"]
+        UA["浏览器 / curl"]
+    end
+
+    subgraph Server["oj server（同进程）"]
+        subgraph RP["RP 模块 sample/src/oidc/"]
+            LOGIN["oidc/login<br/>state+nonce+PKCE"]
+            CB["oidc/callback<br/>交换+验签+JIT"]
+            LO["oidc/logout"]
+        end
+        subgraph OP["OP 模块 sample/src/idp/"]
+            DISC[".well-known/openid-configuration"]
+            JWKS["jwks.json"]
+            AUTHZ["authorize<br/>白名单+PKCE+code"]
+            ILOGIN["login<br/>bcrypt+cookie 会话"]
+            TOK["token<br/>RS256 签发"]
+            UI["userinfo"]
+        end
+        subgraph Core["core（Rust 注入）"]
+            OIDCG["oidc 全局<br/>sign / verify / jwks / issuer / rp / clients"]
+            RAW["json.raw<br/>裸 JSON（OP 对外端点）"]
+            EXEMPT["tenant.anonymous_paths<br/>跳转腿豁免"]
+        end
+        KV["KV<br/>OJ-OIDC:STATE:* / OJ-OIDC:CODE:* / OJ-IDP:SESS:*"]
+        USERS["users 表（_platform）"]
+        SESSION["auth/_shared session.ts<br/>issueTokens + Bearer 会话"]
+    end
+
+    UA -->|"GET ?tenant=X（豁免租户头）"| LOGIN
+    UA -->|"GET ?code&state（豁免）"| CB
+    UA -->|"POST username/password（豁免）"| ILOGIN
+    UA -->|"GET authorize（豁免）"| AUTHZ
+    LOGIN -->|"fetch discovery"| DISC
+    LOGIN -->|"快照"| KV
+    AUTHZ -->|"code（60s 一次一用）"| KV
+    ILOGIN -->|"bcrypt.verify"| USERS
+    ILOGIN -->|"IDP_SESSION"| KV
+    CB -->|"code+verifier 换 token"| TOK
+    CB -->|"fetch jwks_uri"| JWKS
+    CB -->|"verify(id_token, jwks)"| OIDCG
+    CB -->|"JIT：oidc:<tenant>:<sub>"| USERS
+    CB -->|"issueTokens 桥接"| SESSION
+    TOK -->|"claims 签名"| OIDCG
+    DISC --> RAW
+    JWKS --> RAW
+    TOK --> RAW
+    UI --> RAW
+    LOGIN -.->|"302 跳转腿免租户头"| EXEMPT
+```
+
+要点：
+
+- **密钥不出 Rust**：私钥装配期经 `OidcState::from_section` 装入 `StableState`（构造期、
+  不可变），JS 只见 sign/verify/jwks 接口面；手写脱敏 `Debug`，PEM/secret 不进日志。
+- **OP 对外端点说标准协议**：discovery/jwks/token/userinfo 成功用 `json.raw` 回裸 JSON
+  （RFC 6749 要求 `access_token` 是顶层字段），错误仍走 `{code,msg,data}` 信封。
+- **豁免面最小**：`tenant.anonymous_paths` 只豁免「缺失租户头的 400」，且仅列出三条
+  跳转腿路径（`/oidc/*`、`/idp/*`、`/idp/.well-known/*`）；带有效租户头的请求照常注入
+  `http.tenantId`。匹配是严格一层通配（比 oj-auth 插件的多层前缀更严，深路径需显式列出）。
+
+## 2. 全链时序图
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor UA as 浏览器/调用方
+    participant RP as RP oidc/*
+    participant KV as KV
+    participant OP as OP idp/*
+    participant DB as users 表
+    participant Core as oidc 全局(Rust)
+
+    UA->>RP: GET /oidc/login?tenant=default
+    RP->>KV: state -> {tenant,nonce,verifier,IdP 快照} (TTL 600s)
+    RP->>OP: fetch /.well-known/openid-configuration
+    OP-->>RP: discovery（裸 JSON）
+    RP-->>UA: 302 authorize_url?...code_challenge=S256(nonce,state)
+
+    UA->>OP: GET /idp/authorize?...
+    OP-->>UA: 401 login required（无 cookie 会话）
+    UA->>OP: POST /idp/login {username,password}
+    OP->>DB: select + bcrypt.verify
+    OP-->>UA: Set-Cookie IDP_SESSION（KV TTL=refresh 时长）
+    UA->>OP: GET /idp/authorize（带 cookie）
+    OP->>KV: code -> {client_id,redirect_uri,state,nonce,challenge,uid,tenant} (TTL 60s)
+    OP-->>UA: 302 redirect_uri?code&state
+
+    UA->>RP: GET /oidc/callback?code&state
+    RP->>KV: 取 state 并立即删除（一次一用）
+    RP->>OP: POST /idp/token（code+verifier+凭证，form）
+    OP->>KV: 取 code 并立即删除（一次一用）
+    OP->>Core: 校验 PKCE/redirect_uri/client 绑定
+    OP->>Core: oidc.sign({iss,sub,aud,iat,exp,nonce,tenant}) ×2
+    OP-->>RP: access_token + id_token（裸 JSON）
+    RP->>OP: fetch jwks_uri
+    OP-->>RP: JWKS
+    RP->>Core: oidc.verify(id_token, jwks)（RS256/kid/exp/nonce/iss/aud）
+    RP->>DB: JIT：username = oidc:<tenant>:<sub>，无则插入（'!oidc' 占位不可登录）
+    RP->>UA: 200 信封 issueTokens()（access/refresh HS256 桥接会话）
+
+    UA->>RP: 重放 callback?code&state
+    RP->>KV: state 已删除
+    RP-->>UA: 401 invalid or expired state
+```
+
+安全闸门与失效路径：
+
+| 闸门 | 失败返回 |
+|---|---|
+| authorize：client_id/redirect_uri 白名单不命中 | 400（**绝不重定向**） |
+| authorize：response_type ≠ code / scope 无 openid / PKCE 非 S256 | 400 |
+| authorize / token：会话或 code 无效、过期、已用 | 401 |
+| callback：state 无效/过期/重放 | 401 |
+| callback：jwks 拉取失败 | 502（**不回落本地验签**） |
+| callback：id_token 验签失败 / nonce、iss、aud 与快照不符 | 401 |
+| token：code 归属 client 与凭证不符 | 401（RFC 6749 §4.1.3） |
+
+## 3. 多租户数据流
+
+```mermaid
+flowchart LR
+    Q["GET /oidc/login?tenant=acme"] --> LOOK["oidc.rp[acme]<br/>（config 段，未知 -> 400）"]
+    LOOK --> SNAP["state 快照绑定 IdP 配置<br/>（callback 只信快照，不信 query）"]
+    SNAP --> IDP["按 issuer 对接该租户的 IdP<br/>（通用 discovery）"]
+    IDP --> TOK2["id_token.tenant =<br/>clients.<client>.tenant"]
+    TOK2 --> JIT["JIT 本地行 username=<br/>oidc:acme:<sub>（租户隔离）"]
+    JIT --> API["业务请求：X-TENANT-ID 头恢复强制<br/>租户隔离沿用既有语义"]
+```
+
+- **RP 侧**：tenant 决定用哪个 IdP。tenant 从 query 进入豁免路由，建 state 时快照进 KV，
+  后续只信快照——query 无法劫持已建立的登录流。
+- **OP 侧**：tenant 来自 client 注册（`oidc.clients.<id>.tenant`），随 code 进入
+  id_token/access_token claims。
+- **豁免边界**：只有跳转腿豁免；登录后的业务请求照常强制 `X-TENANT-ID`，与全站语义一致。
+
+## 4. 组件与文件清单
+
+| 组件 | 文件 | 职责 |
+|---|---|---|
+| 配置段 | `src/config.rs` | `OidcSection{issuer, private_key_path, rp, clients}` + `TenantCfg.anonymous_paths` |
+| 状态 | `src/bridge/oidc.rs` | `OidcState`：PKCS#8 装载、kid（sha256(b64u(n)) 前 16 hex）、JWKS、rp/clients 透出；`from_section` fail-fast |
+| ops | `src/bridge/oidc.rs` | `op_oidc_sign`（RS256+kid header）/ `op_oidc_verify`（本机或 jwks 按 kid，锁 RS256，leeway 0）/ `op_oidc_info` |
+| 裸 JSON | `src/bridge/json.rs` | `json.raw(data)`——200 裸 JSON，默认 content-type，`json.header` 可覆盖 |
+| 全局挂载 | `src/bridge/bootstrap.js` | `oidc` 全局（sign/verify/jwks/issuer/rp/clients）；ASCII 纪律 |
+| 装配 | `oj/src/app.rs` | `cfg.oidc → OidcState::from_section → Extras.oidc/StableState`（构造期，fail-fast） |
+| 租户豁免 | `server/src/lib.rs` | `Pipeline.tenant_anon` + `path_matches`（严格一层通配）；run 闭包豁免缺失头 400 |
+| OP | `sample/src/idp/` | discovery / jwks.json / authorize / login / token / userinfo（六端点） |
+| RP | `sample/src/oidc/` | login / callback / logout（三端点） |
+| 共享工具 | `sample/src/auth/_shared/util.ts` | redirect / nowSecs / b64uFromHex / parseForm / parseCookies（构建顺序 auth 最先） |
+| 测试 | `sample/tests/oidc.test.ts` | L1：39 用例（进程内） |
+| 测试 | `oj/tests/oidc_e2e.rs` | 真 TCP 全链 e2e。**独立测试目标**：oj-auth 插件 `static GUARD: OnceLock` 进程级只认首次 init，与 e2e.rs 共进程会互染 |
+
+## 5. 已知边界（刻意不做的）
+
+- OP sub = `users.id` 字符串；自举登录 JIT 出 `oidc:default:<id>` 本地行，与原 demo 行
+  **不合并**（外部 IdP 语义下 sub 本就 opaque）。
+- 不支持：consent 页（登录即同意）、refresh_token / client_credentials grant、
+  OP end_session、JWKS 轮换运维（kid 机制已就位，轮换是配置问题）。
+- code/state 的消费是 get→del 非原子（重放必落空；并发窗口由 PKCE/state 绑定兜底；
+  redis 后端可换 GETDEL）。secret/PKCE 比较非常量时间（demo 范围）。
+- `client_secret` 明文存 config（与 `auth.jwt_secret` 同信任级），经 `oidc.rp/clients`
+  可读——handler JS 与 jwt_secret 同级受信。

package/devkit/oidc-integration.md

@@ -0,0 +1,168 @@
+# OIDC 接入手册
+
+> 面向要在自己的 oj 项目里启用 OIDC 的开发者：接外部 IdP（RP 角色）、用内置 OP、
+> 多租户接线与排障。实现原理见 [oidc-implementation.md](oidc-implementation.md)，
+> JS 全局签名见 [devkit/api-manual.md](devkit/api-manual.md) §6 `oidc` 行。
+
+## 1. 前置条件
+
+- oj ≥ 本特性版本；`plugins:` 里装配了 `oj-auth`（Bearer 守卫；OIDC 会话桥接依赖它）。
+- RS256 私钥一把（PKCS#8 PEM）。生成任选：
+
+```bash
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out config/oidc_rs256.pem
+# 或复用 oj-cert（其 private.pem 即 PKCS#8）：
+cargo run -p oj-cert -- gen -o config --days 365
+```
+
+- RP 角色对接的 IdP 必须支持：**authorization code flow + PKCE S256 + RS256 id_token +
+  discovery**（`<issuer>/.well-known/openid-configuration`）。四者缺一不可（RP 强制 PKCE
+  S256、强制验签）。
+
+## 2. 最小可用配置
+
+```yaml
+oidc:
+  issuer: "https://idp.example.com"          # 本机 OP 的对外 URL；只当 RP 时此字段仍必填（OP 侧身份）
+  private_key_path: "./config/oidc_rs256.pem" # 相对 config.yaml 所在目录
+  rp:                                         # tenant → 外部 IdP 注册
+    default:
+      issuer: "https://idp.example.com"       # IdP 的 issuer（与它 discovery 文档里的 issuer 一字不差）
+      client_id: "my-app"
+      client_secret: "..."
+      scope: "openid profile"
+```
+
+只当 RP、不用内置 OP 时，`rp` 段配好即可——`clients` 段可以省略。`oidc:` 段缺省 =
+不启用（`oidc` 全局不存在，调用报 `oidc not configured`）。
+
+IdP 侧注册（在 IdP 的管理台上做）：
+
+- redirect_uri 填你服务的**精确串**：`https://<host>/v1/api/oidc/callback`
+  （`server.api_prefix` 非默认时替换前缀）。
+- 允许的 grant：`authorization_code`；强制 PKCE S256 最好（本 RP 永远发 PKCE）。
+- 签名算法 RS256。
+
+## 3. 登录链路（RP 角色）
+
+业务前端只需两步：
+
+```bash
+# 1) 拿 IdP 授权地址（302，Location 即 IdP authorize URL）
+curl -si 'https://your.app/v1/api/oidc/login?tenant=default'
+#    → 302 Location: https://idp.example.com/authorize?...code_challenge=...
+
+# 2) 浏览器走完 IdP 登录后回跳 callback，callback 直接返回会话信封：
+#    {"code":0,"msg":"ok","data":{"access_token":"...","refresh_token":"...",
+#                               "expires_in":60,"user":{"id":"42","roles":[]}}}
+# 之后所有业务 API 照常：Authorization: Bearer <access_token> + X-TENANT-ID 头
+```
+
+要点：
+
+- `?tenant=` 必须是 `oidc.rp` 里的键，未知租户 400。
+- `tenant` 与 `state` 一起快照进 KV（TTL 10 分钟），callback 只信快照——用户改 query
+  动不了已建立的登录流。
+- 登录成功后本地账号按 **`oidc:<tenant>:<sub>`** JIT 创建（首次登录自动建行，不可密码
+  登录），与本地口令账号天然隔离；`roles` 取该行 `roles` 列。
+- `/oidc/*`、`/idp/*` 路径必须同时加进 **`auth.anonymous_paths` 与
+  `tenant.anonymous_paths`**（浏览器跳转腿带不了 Bearer 和租户头）：
+
+```yaml
+auth:
+  anonymous_paths:
+    - "/oidc/*"
+    - "/idp/*"
+    - "/idp/.well-known/*"
+tenant:
+  enable: true
+  anonymous_paths:          # 与 auth 的同名机制同形，但匹配是严格一层通配
+    - "/oidc/*"
+    - "/idp/*"
+    - "/idp/.well-known/*"
+```
+
+## 4. 用内置 OP（自己当身份源）
+
+在 `oidc:` 段再加 `clients`（OP 侧 client 白名单），并把要自举的租户的 `rp.<tenant>.issuer`
+指向本机 OP：
+
+```yaml
+oidc:
+  issuer: "http://localhost:9778/v1/api/idp"   # OP 对外身份（必须与实际可达地址一致）
+  private_key_path: "./config/oidc_rs256.pem"
+  clients:                                      # OP 侧：谁可以来登录
+    sample-rp:
+      secret: "rp-secret"
+      redirect_uris:                            # 精确串白名单；不在表内绝不重定向
+        - "http://localhost:9778/v1/api/oidc/callback"
+      tenant: "default"                         # 该 client 登录成功后 id_token.tenant 的值
+  rp:
+    default:                                    # 指向自己 = 自举演示
+      issuer: "http://localhost:9778/v1/api/idp"
+      client_id: "sample-rp"
+      client_secret: "rp-secret"
+      scope: "openid profile"
+```
+
+OP 端点一览（对外标准协议，成功响应为裸 JSON）：
+
+| 端点 | 方法 | 说明 |
+|---|---|---|
+| `/v1/api/idp/.well-known/openid-configuration` | GET | discovery（勿硬编码下游地址，走发现） |
+| `/v1/api/idp/jwks.json` | GET | 验签公钥（RS256，kid） |
+| `/v1/api/idp/authorize` | GET | 无 OP 会话 → 401 `login required`（先 POST login 持 cookie 重来） |
+| `/v1/api/idp/login` | POST | `{username,password}` → `Set-Cookie: IDP_SESSION`（users 表 + bcrypt） |
+| `/v1/api/idp/token` | POST | form：`grant_type=authorization_code&code&client_id&client_secret&redirect_uri&code_verifier` |
+| `/v1/api/idp/userinfo` | GET | `Authorization: Bearer <access_token>` → `{sub, tenant}` |
+
+OP 的登录用户 = 本库 `users` 表（bcrypt）。给用户开号即插一行（`INSERT OR IGNORE INTO
+users (username, password_hash, roles) VALUES (?, '<bcrypt hash>', '[]')`）。
+
+## 5. 多租户接线
+
+| 位置 | 配置 | 语义 |
+|---|---|---|
+| RP（接谁的 IdP） | `oidc.rp.<tenant>` | tenant → IdP issuer/凭证；`/oidc/login?tenant=<键>` 选用 |
+| OP（谁可以登录） | `oidc.clients.<id>.tenant` | 该 client 的登录会签发到哪个租户（id_token.tenant） |
+| 跳转腿豁免 | `tenant.anonymous_paths` | 浏览器 302 带不了租户头；列表外照常 400 |
+| 业务隔离 | `X-TENANT-ID` 头 | 登录后恢复全站强制；行级过滤仍由业务 SQL 自理（框架不自动改写） |
+
+一个 users 表服务多租户时，本地账号名 `oidc:<tenant>:<sub>` 已按租户隔离；**不要**把
+两个不同信任级的 IdP 指向同一租户键。
+
+## 6. 会话与登出
+
+- callback 返回的 `access_token/refresh_token` 就是既有 `auth` 会话（HS256 + KV 轮换，
+  时长取 `auth.access_token_duration/refresh_token_duration`）——**后续鉴权、refresh、
+  logout 与本地登录完全同构**，前端无感。
+- OP 侧会话（`IDP_SESSION` cookie）独立存在，只用于 authorize 免重复输密码；Path 限定
+  `/…/idp`，HttpOnly + SameSite=Lax。
+- `POST /v1/api/oidc/logout`（body `{refresh_token}`）等价 `auth/logout`。
+
+## 7. 排障表
+
+| 症状 | 原因 / 处置 |
+|---|---|
+| `oidc not configured` | config 没有 `oidc:` 段（或 `oj build` 产物未带新二进制）；段存在但 `issuer`/`private_key_path` 为空 → 启动即报错退出 |
+| 启动报 `oidc private key … parse pkcs8 pem` | 私钥不是 PKCS#8 PEM（`BEGIN PRIVATE KEY`）；用 §1 命令重新生成 |
+| `/oidc/login` → 400 `unknown tenant` | `?tenant=` 不在 `oidc.rp` 键里 |
+| `/oidc/login` → 502 `discovery failed` | IdP 不可达 / issuer 写错 / IdP 无 discovery 端点；`curl <issuer>/.well-known/openid-configuration` 自查 |
+| `/oidc/callback` → 502 `jwks fetch failed` | jwks_uri 拉取失败（IdP 抖动）；**不会**静默回落本机验签，重试即可 |
+| `/oidc/callback` → 401 `id_token verification failed` | RS256/kid 不匹配（IdP 轮了密钥）或 token 被篡改 |
+| `/oidc/callback` → 401 `id_token claims mismatch` | nonce/iss/aud 与快照不符：多为 issuer 大小写/尾斜杠不一致 |
+| `/oidc/callback` → 401 `invalid or expired state` | state 已用或超 10 分钟；回 `/oidc/login` 重新起流程 |
+| authorize → 400 `redirect_uri not registered` | 跳转地址不在 `oidc.clients.<id>.redirect_uris` 精确表内（scheme/host/端口/路径全都要一致） |
+| authorize → 401 `login required` | 正常：先 `POST /idp/login` 拿 IDP_SESSION cookie 再访问 authorize |
+| 登录后业务 API 400 `missing tenant header` | 正常：跳转腿豁免不覆盖业务请求；客户端把 `X-TENANT-ID` 带上 |
+| e2e/测试里 `/oidc/*` 意外 401 | oj-auth 插件 `static GUARD` 进程级只认首次 init 的匿名表——同进程多服务器测试请把用例放进独立测试目标（参考 `oj/tests/oidc_e2e.rs`） |
+
+## 8. 安全清单（上线前自查）
+
+- [ ] `redirect_uris` 精确串（无通配、无 query）；白名单外绝不发生 302
+- [ ] PKCE S256 强制（RP 已强制；IdP 侧也开）
+- [ ] `client_secret` 不进前端/日志；轮换时 `rp` 与 IdP 两侧同步
+- [ ] 生产 IdP 走 HTTPS（issuer 与 discovery 返回值逐字一致）
+- [ ] `auth.anonymous_paths` 与 `tenant.anonymous_paths` 只列跳转腿三段，不加业务路径
+- [ ] 私钥文件权限收紧（600）；`config/` 不进镜像分发
+- [ ] 已知晓：demo 私钥 `sample/config/oidc_rs256.pem` 仅供演示，勿用于生产