feat(auth): 声明式权限键 + 写操作二次校验

影响:写操作(新建 / 修改 / 逻辑删除)现在多一道**权限键**判定;
能力集来自 `tdc_identity.f_capability`,解析不出时 **fail-open 放行**
(对齐上游「菜单未映射即放行」口径)⇒ 存量连接器不受影响。

改动:
- `src/registry.rs`:新增 `PERMISSION_KEYS`(18 个实体 → 权限键)与 `permission_key()`,
  另加一条单测守住「每个实体都有权限键」。
- `src/domain/identity.rs`:新增 `capabilities()` —— 解析 `f_capability` 自由文本
  (`,` `;` 空白分隔)成 token 集合;解析不出返回 `None`。
- `src/crud.rs`:新增 `require_write_permission()`;`create` / `update` / `delete`
  改走它(读接口 `list` / `all` / `detail` / `detail_aggregate` **不动**,
  读不做权限键判定)。
- `tests/permission_gate.rs`:5 个用例(能力集解析 / fail-open / 命中与未命中 /
  通配符 / 内部令牌与无凭证),含一条**接线自证**——三个写路径未命中权限键时必须是 403。

设计:能力集解析不出 ⇒ 放行(fail-open);本地账号(无 `tdc_identity` 来源)同 footing。

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
adminandClaude Code committed 2026-10-25 10:54:19 +08:00
1 parent 0828bcfbc1
commit e75dcf9370
4 files changed
+311 -3

No files matched your search

+50 -3
View File
@@ -572,6 +572,53 @@ async fn fetch_alive(
Ok(rows.into_iter().next())
}
/// 写操作的权限键校验(设计文档 §5.1)。
///
/// - 内部令牌 ⇒ 直接放行。
/// - 无凭证 ⇒ 拒(403)。
/// - 已登录 ⇒ 取身份能力集:
/// - **解析不出(`None`)⇒ fail-open 放行**;
/// - 解析出来 ⇒ 必须命中该实体的权限键(或通配符 `*` / `all`),否则 403。
pub async fn require_write_permission(
state: &AppState,
spec: &'static TableSpec,
principal: Option<&Principal>,
) -> Result<(), Response> {
let p = match principal {
Some(p) => p,
None => {
return Err(crate::auth::reject(
axum::http::StatusCode::FORBIDDEN,
"缺少有效凭证(需登录或内部凭证)",
))
}
};
let identity_code = match p {
Principal::Internal { .. } => return Ok(()),
// 🔴 `Principal` 是**三变体**枚举(`src/auth.rs`):`Internal` / `Session` / `Account`。
// 漏掉 `Account` 分支 ⇒ E0004 non-exhaustive match,**编译不过**。
// 本地账号(Task 12 引入)没有 `tdc_identity.f_capability` 来源 ⇒ 与
// `capabilities()` 返回 `None` 的情形同 footing,**fail-open 放行**。
Principal::Account { .. } => return Ok(()),
Principal::Session { identity_code, .. } => identity_code.clone(),
};
let key = registry::permission_key(spec.api_name).unwrap_or(spec.api_name);
let caps = crate::domain::identity::capabilities(state, &identity_code).await;
match caps {
None => Ok(()),
Some(set) => {
if set.iter().any(|c| c == "*" || c == "all" || c == key) {
Ok(())
} else {
Err(crate::auth::reject(
axum::http::StatusCode::FORBIDDEN,
&format!("当前身份无「{}」的操作权限", key),
))
}
}
}
}
/// 新增:`POST /api/ssw/tdc/{Entity}`。
pub async fn create(
state: &AppState,
@@ -579,7 +626,7 @@ pub async fn create(
body: &Value,
principal: Option<&Principal>,
) -> Response {
if let Err(resp) = require_menu_permission(principal) {
if let Err(resp) = require_write_permission(state, spec, principal).await {
return resp;
}
if let Some(msg) = spec.no_create {
@@ -721,7 +768,7 @@ pub async fn update(
body: &Value,
principal: Option<&Principal>,
) -> Response {
if let Err(resp) = require_menu_permission(principal) {
if let Err(resp) = require_write_permission(state, spec, principal).await {
return resp;
}
if let Some(msg) = spec.no_update {
@@ -806,7 +853,7 @@ pub async fn delete(
id: &str,
principal: Option<&Principal>,
) -> Response {
if let Err(resp) = require_menu_permission(principal) {
if let Err(resp) = require_write_permission(state, spec, principal).await {
return resp;
}
// 🔴 **「不存在」判定必须先于「禁删」守卫**(上游 `TdcCrudController#delete:250-266`:
+41
View File
@@ -439,6 +439,47 @@ pub async fn sso_config() -> Response {
.into_response()
}
/// 解析连接器身份的能力集(`tdc_identity.f_capability`)。
///
/// 上游把能力存在一列自由文本里(`f_capability text`),**没有结构化约定**。
/// Rust 侧按 `,` `;` 空白 换行分隔成 token 集合:
///
/// - `None` ⇒ **解析不出**(列为空 / 行不存在)⇒ 调用方按 **fail-open** 放行
/// (对齐上游 `SswPermissionGuard` 的「菜单未映射即放行」口径)。
/// - `Some(set)` ⇒ 解析成功 ⇒ 写操作必须命中该实体的权限键(或通配符 `*` / `all`)。
pub async fn capabilities(state: &AppState, identity_code: &str) -> Option<Vec<String>> {
let sql = "SELECT f_capability FROM tdc_identity \
WHERE f_identity_code = CAST($1 AS character varying) \
AND (f_delete_mark IS NULL OR f_delete_mark = 0) LIMIT 1";
let rows = {
let _g = state.db_lock.lock().await;
crate::db::query_json_params(state.db.as_ref(), sql, &[&identity_code])
.await
.ok()?
};
let raw = rows
.first()?
.get("f_capability")?
.as_str()?
.trim()
.to_string();
if raw.is_empty() {
return None;
}
let mut set: Vec<String> = Vec::new();
for tok in raw.split(|c: char| c == ',' || c == ';' || c.is_whitespace()) {
let t = tok.trim();
if !t.is_empty() && !set.iter().any(|x| x == t) {
set.push(t.to_string());
}
}
if set.is_empty() {
None
} else {
Some(set)
}
}
#[cfg(test)]
mod tests {
use super::*;
+50
View File
@@ -476,6 +476,39 @@ pub static REGISTRY: &[TableSpec] = &[
},
];
/// 实体 → 权限键(设计文档 §5.1「声明式权限键」)。
///
/// 键名 = 实体名的 snake_case;**只用于服务端对写操作的二次校验**,不用于隐藏菜单。
/// 18 个实体一个不少 —— `permission_keys_cover_every_entity` 会守住这条。
pub const PERMISSION_KEYS: &[(&str, &str)] = &[
("ApiConsumeLog", "api_consume_log"),
("AuditLog", "audit_log"),
("Contract", "contract"),
("Credential", "credential"),
("DataInterface", "data_interface"),
("Dataset", "dataset"),
("Datasource", "datasource"),
("DeliveryLog", "delivery_log"),
("DeliveryTask", "delivery_task"),
("DestroyLog", "destroy_log"),
("Identity", "identity"),
("Notification", "notification"),
("Order", "order"),
("Policy", "policy"),
("PolicyCheckLog", "policy_check_log"),
("PolicyTemplate", "policy_template"),
("Product", "product"),
("Resource", "resource"),
];
/// 查实体的权限键。
pub fn permission_key(api_name: &str) -> Option<&'static str> {
PERMISSION_KEYS
.iter()
.find(|(name, _)| *name == api_name)
.map(|(_, key)| *key)
}
/// 按实体名查注册表。
pub fn find(api_name: &str) -> Option<&'static TableSpec> {
REGISTRY.iter().find(|s| s.api_name == api_name)
@@ -643,6 +676,23 @@ mod tests {
assert_eq!(find("Product").unwrap().tenant_column, Some("f_tenant_id"));
}
#[test]
fn permission_keys_cover_every_entity() {
assert_eq!(PERMISSION_KEYS.len(), 18);
let mut seen = HashSet::new();
for (name, key) in PERMISSION_KEYS {
assert!(seen.insert(*name), "权限键重复: {}", name);
assert!(!key.is_empty(), "权限键不得为空: {}", name);
}
for s in REGISTRY {
assert!(
permission_key(s.api_name).is_some(),
"实体 {} 缺权限键",
s.api_name
);
}
}
#[test]
fn api_consume_log_keyword_columns_exist_in_its_table() {
// 上游用基类默认的 f_name,但 tdc_api_consume_log 没有该列 —— Rust 侧必须改掉
+170
View File
@@ -0,0 +1,170 @@
//! 权限键:能力集解析 + 写操作二次校验。
//!
//! ⚠️ 本测试二进制内共用一个 PGlite 实例(pglite-rs 每进程只允许一个)。
use std::sync::Arc;
use axum::http::StatusCode;
use pglite::PGlite;
use tdc_connector::auth::Principal;
use tdc_connector::config::Config;
use tdc_connector::crud::require_write_permission;
use tdc_connector::domain::identity;
use tdc_connector::registry;
use tdc_connector::session::SessionStore;
use tdc_connector::state::{AppState, BootstrapIdentity};
use tokio::sync::OnceCell;
static DB: OnceCell<Arc<PGlite>> = OnceCell::const_new();
async fn shared_db() -> Arc<PGlite> {
DB.get_or_init(|| async {
let db = Arc::new(PGlite::open_temp().await.expect("打开临时 PGlite 失败"));
tdc_connector::db::ensure_schema(db.as_ref())
.await
.expect("建表失败");
db
})
.await
.clone()
}
async fn test_state() -> AppState {
let db = shared_db().await;
let mut config = Config::from_env(std::env::current_dir().unwrap());
config.identity_code = "TEST-CONNECTOR".to_string();
AppState::new(
config,
db,
Arc::new(SessionStore::new()),
BootstrapIdentity::default(),
)
}
/// 插入一条测试身份;`capability` 为 `None` 时该列为 NULL。
async fn upsert_identity(code: &str, capability: Option<&str>) {
let state = test_state().await;
let cap = match capability {
Some(c) => format!("'{}'", c),
None => "NULL".to_string(),
};
let id = format!("ID-{}", code);
let sql = format!(
"INSERT INTO tdc_identity (f_id, f_identity_code, f_name, f_capability) \
VALUES ('{}', '{}', '测试身份', {})",
id, code, cap
);
// 🔴 所有 DB 访问必须持 `state.db_lock`(PGlite 单 in-process backend,CLAUDE.md 红线)
// —— 测试代码也不例外,否则与并行的 `capabilities()` 查询在同一个 backend 上抢。
let _g = state.db_lock.lock().await;
state.db.exec(&sql).await.expect("插入测试身份失败");
}
fn session(code: &str) -> Principal {
Principal::Session {
identity_id: format!("ID-{}", code),
identity_code: code.to_string(),
}
}
#[tokio::test]
async fn missing_capability_fails_open() {
upsert_identity("NO-CAP", None).await;
let state = test_state().await;
let caps = identity::capabilities(&state, "NO-CAP").await;
assert!(caps.is_none(), "空能力集应解析为 None(⇒ fail-open)");
let spec = registry::find("Product").expect("Product 应在注册表里");
let r = require_write_permission(&state, spec, Some(&session("NO-CAP"))).await;
assert!(r.is_ok(), "能力集解析不出时必须 fail-open 放行");
}
#[tokio::test]
async fn parsed_capability_is_enforced_on_write() {
upsert_identity("ONLY-PRODUCT", Some("product")).await;
let state = test_state().await;
let caps = identity::capabilities(&state, "ONLY-PRODUCT").await;
assert_eq!(caps, Some(vec!["product".to_string()]));
let product = registry::find("Product").expect("Product 应在注册表里");
assert!(
require_write_permission(&state, product, Some(&session("ONLY-PRODUCT")))
.await
.is_ok(),
"命中权限键应放行"
);
let contract = registry::find("Contract").expect("Contract 应在注册表里");
assert!(
require_write_permission(&state, contract, Some(&session("ONLY-PRODUCT")))
.await
.is_err(),
"未命中权限键必须被拒"
);
}
#[tokio::test]
async fn wildcard_capability_allows_everything() {
upsert_identity("ROOT", Some("*")).await;
let state = test_state().await;
let spec = registry::find("Contract").expect("Contract 应在注册表里");
assert!(
require_write_permission(&state, spec, Some(&session("ROOT")))
.await
.is_ok(),
"通配符应放行全部实体"
);
}
#[tokio::test]
async fn internal_principal_bypasses_the_gate() {
let state = test_state().await;
let spec = registry::find("Contract").expect("Contract 应在注册表里");
assert!(
require_write_permission(&state, spec, Some(&Principal::Internal { operator: None }))
.await
.is_ok(),
"内部令牌必须直接放行"
);
assert!(
require_write_permission(&state, spec, None).await.is_err(),
"无凭证必须被拒"
);
}
/// 🔴 **接线自证**:三个**写路径**(`create` / `update` / `delete`)真的走了权限键判定。
///
/// 三个写函数都把权限判定放在**函数最开头**(在任何 DB 访问之前)⇒
/// 即便 id 不存在,被拒的也应该是 **403**,而不是业务层的「记录不存在或已删除」(200)。
/// ⇒ 这条用例是「把 `create` 里的 `require_write_permission` 换回 `require_menu_permission`」
/// 那次变异的**红点**(没有它,CRUD 写路径的接线是**测不到**的)。
#[tokio::test]
async fn crud_write_paths_enforce_the_permission_key() {
// ⚠️ 身份码要**唯一**:本测试二进制里的用例并行跑、共用同一个库 ⇒
// 复用别的用例的 `f_identity_code` 会撞主键。
upsert_identity("CAP-PRODUCT-ONLY", Some("product")).await;
let state = test_state().await;
let contract = registry::find("Contract").expect("Contract 应在注册表里");
let p = session("CAP-PRODUCT-ONLY");
let body = serde_json::json!({});
let r = tdc_connector::crud::create(&state, contract, &body, Some(&p)).await;
assert_eq!(
r.status(),
StatusCode::FORBIDDEN,
"create 未命中权限键必须 403"
);
let r = tdc_connector::crud::update(&state, contract, "NOT-EXIST", &body, Some(&p)).await;
assert_eq!(
r.status(),
StatusCode::FORBIDDEN,
"update 未命中权限键必须 403"
);
let r = tdc_connector::crud::delete(&state, contract, "NOT-EXIST", Some(&p)).await;
assert_eq!(
r.status(),
StatusCode::FORBIDDEN,
"delete 未命中权限键必须 403"
);
}