Skip to main content

yang_base/action/
upload.rs

1//! 请求作用域上传文件句柄。
2
3use crate::error::BaseError;
4use schemars::gen::SchemaGenerator;
5use schemars::schema::{InstanceType, Schema, SchemaObject, SingleOrVec};
6use schemars::JsonSchema;
7use serde::Deserialize;
8use std::fmt;
9use std::path::{Path, PathBuf};
10
11/// 由受信传输层创建的请求作用域上传文件。
12///
13/// 临时路径只在当前 Handler 执行期间有效。需要持久化时调用 [`copy_to`](Self::copy_to)
14/// 或使用受控存储服务显式转存;保存本路径供请求结束后使用是无效的。
15///
16/// # 受信边界(C-1)
17///
18/// 实例只能由 multipart 传输层在服务端构造的 JSON 反序列化得到:传输层在构造处注入
19/// `temp_root`(请求作用域临时目录)。客户端 JSON 缺省该字段,反序列化后为 `None`,
20/// [`copy_to`](Self::copy_to) 一律拒绝,防止普通 JSON Action 伪造 `path` 读取本地文件。
21/// 构建期 `AppBuilder` 另有双向校验:含二进制文件字段的输入必须声明 multipart,
22/// multipart Action 必须至少声明一个文件字段。
23#[derive(Clone, Deserialize)]
24#[serde(deny_unknown_fields)]
25pub struct UploadedFile {
26    field_name: String,
27    original_filename: String,
28    content_type: String,
29    size: u64,
30    path: PathBuf,
31    /// 受信临时根目录;仅 multipart 传输层在服务端构造的 JSON 中注入,
32    /// 客户端反序列化(缺省)为 `None`。
33    #[serde(default)]
34    temp_root: Option<PathBuf>,
35}
36
37impl UploadedFile {
38    /// 返回 multipart 字段名。
39    pub fn field_name(&self) -> &str {
40        &self.field_name
41    }
42
43    /// 返回去除客户端路径片段后的原始文件名。
44    pub fn original_filename(&self) -> &str {
45        &self.original_filename
46    }
47
48    /// 返回已通过 Action 白名单校验的客户端声明 MIME 类型。
49    pub fn content_type(&self) -> &str {
50        &self.content_type
51    }
52
53    /// 返回实际接收的文件字节数。
54    pub const fn size(&self) -> u64 {
55        self.size
56    }
57
58    /// 返回只在当前请求期间有效的临时路径。
59    pub fn path(&self) -> &Path {
60        &self.path
61    }
62
63    /// 将上传内容显式复制到业务拥有的目标位置。
64    ///
65    /// 安全校验(fail-closed):实例必须持有受信临时根(即来自 multipart 传输层),
66    /// 且 `path` 与临时根经 `canonicalize` 解析后必须位于临时根之内,否则拒绝复制;
67    /// 复制使用校验时解析出的规范路径,消除符号链接交换(TOCTOU)竞争窗口。
68    pub async fn copy_to(&self, destination: impl AsRef<Path>) -> Result<u64, BaseError> {
69        let temp_root = self.temp_root.as_ref().ok_or_else(|| {
70            BaseError::PermissionDenied(
71                "上传文件缺少受信临时根(疑似不可信反序列化实例),拒绝复制".to_string(),
72            )
73        })?;
74        let root = temp_root.canonicalize().map_err(|error| {
75            BaseError::PermissionDenied(format!("受信临时根校验失败,拒绝复制: {error}"))
76        })?;
77        let source = self.path.canonicalize().map_err(|error| {
78            BaseError::PermissionDenied(format!("上传临时文件校验失败,拒绝复制: {error}"))
79        })?;
80        if !source.starts_with(&root) {
81            return Err(BaseError::PermissionDenied(
82                "上传文件路径越出受信临时根,拒绝复制".to_string(),
83            ));
84        }
85        tokio::fs::copy(&source, destination)
86            .await
87            .map_err(BaseError::from)
88    }
89}
90
91impl fmt::Debug for UploadedFile {
92    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
93        formatter
94            .debug_struct("UploadedFile")
95            .field("field_name", &self.field_name)
96            .field("original_filename", &self.original_filename)
97            .field("content_type", &self.content_type)
98            .field("size", &self.size)
99            .field("path", &"[REQUEST_SCOPED_TEMP_FILE]")
100            .field("trusted", &self.temp_root.is_some())
101            .finish()
102    }
103}
104
105impl JsonSchema for UploadedFile {
106    fn schema_name() -> String {
107        "UploadedFile".to_string()
108    }
109
110    fn json_schema(_generator: &mut SchemaGenerator) -> Schema {
111        Schema::Object(SchemaObject {
112            instance_type: Some(SingleOrVec::Single(Box::new(InstanceType::String))),
113            format: Some("binary".to_string()),
114            ..SchemaObject::default()
115        })
116    }
117}
118
119#[cfg(test)]
120mod tests {
121    use super::*;
122
123    /// 创建带唯一名字的测试临时目录(不依赖 tempfile,兼容无 transport-axum 的测试矩阵)。
124    fn unique_test_dir(tag: &str) -> PathBuf {
125        let nanos = std::time::SystemTime::now()
126            .duration_since(std::time::UNIX_EPOCH)
127            .map(|duration| duration.as_nanos())
128            .unwrap_or(0);
129        let dir = std::env::temp_dir().join(format!(
130            "yang_upload_test_{tag}_{}_{nanos}",
131            std::process::id()
132        ));
133        std::fs::create_dir_all(&dir).expect("测试临时目录应创建成功");
134        dir
135    }
136
137    #[test]
138    fn uploaded_file_projects_as_openapi_binary_input() {
139        let schema = schemars::schema_for!(UploadedFile);
140        let value = serde_json::to_value(schema).expect("UploadedFile schema 应可序列化");
141
142        assert_eq!(value["type"], "string");
143        assert_eq!(value["format"], "binary");
144        assert!(value.get("path").is_none(), "临时路径不得进入输入契约");
145    }
146
147    #[tokio::test]
148    async fn copy_to_rejects_deserialized_instance_without_trusted_temp_root() {
149        // C-1:客户端经 JSON 通道伪造的实例没有受信临时根,copy_to 必须 fail-closed 拒绝。
150        // 以当前可执行文件为受害路径:修复前 copy_to 会以服务进程权限直接复制它(漏洞复现)。
151        let victim = std::env::current_exe().expect("当前可执行文件路径应可获取");
152        let forged: UploadedFile = serde_json::from_value(serde_json::json!({
153            "field_name": "file",
154            "original_filename": "payload.bin",
155            "content_type": "application/octet-stream",
156            "size": 1,
157            "path": victim,
158        }))
159        .expect("伪造实例应可反序列化");
160        let dir = unique_test_dir("untrusted");
161        let destination = dir.join("stolen.bin");
162
163        let error = forged
164            .copy_to(&destination)
165            .await
166            .expect_err("无受信临时根的实例必须拒绝复制");
167        assert!(
168            matches!(error, BaseError::PermissionDenied(_)),
169            "无受信临时根应返回 PermissionDenied: {error}"
170        );
171        assert!(!destination.exists(), "拒绝复制不得产生目标文件");
172        let _ = std::fs::remove_dir_all(&dir);
173    }
174
175    #[tokio::test]
176    async fn copy_to_rejects_path_escaping_trusted_temp_root() {
177        // C-1:即使实例持有受信临时根,越出根目录的路径也必须拒绝(防 symlink/../ 逃逸)。
178        let root = unique_test_dir("root");
179        let outside = unique_test_dir("outside");
180        let secret = outside.join("secret.txt");
181        std::fs::write(&secret, b"top-secret").expect("越界文件应写入成功");
182        let file = UploadedFile {
183            field_name: "file".to_string(),
184            original_filename: "secret.txt".to_string(),
185            content_type: "text/plain".to_string(),
186            size: 10,
187            path: secret,
188            temp_root: Some(root.clone()),
189        };
190        let destination = root.join("copy.txt");
191
192        let error = file
193            .copy_to(&destination)
194            .await
195            .expect_err("越出受信临时根的路径必须拒绝");
196        assert!(
197            matches!(error, BaseError::PermissionDenied(_)),
198            "越界路径应返回 PermissionDenied: {error}"
199        );
200        assert!(!destination.exists(), "拒绝复制不得产生目标文件");
201        let _ = std::fs::remove_dir_all(&root);
202        let _ = std::fs::remove_dir_all(&outside);
203    }
204
205    #[tokio::test]
206    async fn copy_to_copies_file_inside_trusted_temp_root() {
207        // 受信临时根内的合法文件应正常复制(canonicalize 双端解析后 starts_with 通过)。
208        let root = unique_test_dir("trusted");
209        let source = root.join("yang-upload-1");
210        std::fs::write(&source, b"hello").expect("源文件应写入成功");
211        let file = UploadedFile {
212            field_name: "file".to_string(),
213            original_filename: "upload.bin".to_string(),
214            content_type: "application/octet-stream".to_string(),
215            size: 5,
216            path: source,
217            temp_root: Some(root.clone()),
218        };
219        let destination = root.join("saved.bin");
220
221        let copied = file
222            .copy_to(&destination)
223            .await
224            .expect("受信临时根内的文件应复制成功");
225        assert_eq!(copied, 5);
226        assert_eq!(
227            std::fs::read(&destination).expect("目标文件应可读"),
228            b"hello"
229        );
230        let _ = std::fs::remove_dir_all(&root);
231    }
232
233    #[test]
234    fn transport_injected_temp_root_deserializes_into_trusted_instance() {
235        // transport 在服务端构造的 JSON 会注入 temp_root;缺省(客户端 JSON)则不得获得。
236        let trusted: UploadedFile = serde_json::from_value(serde_json::json!({
237            "field_name": "file",
238            "original_filename": "a.txt",
239            "content_type": "text/plain",
240            "size": 3,
241            "path": "/tmp/scope/yang-upload-1",
242            "temp_root": "/tmp/scope",
243        }))
244        .expect("transport 注入的 temp_root 应可反序列化");
245        assert_eq!(
246            trusted.temp_root.as_deref(),
247            Some(Path::new("/tmp/scope")),
248            "transport 注入的临时根必须保留"
249        );
250
251        let forged: UploadedFile = serde_json::from_value(serde_json::json!({
252            "field_name": "file",
253            "original_filename": "a.txt",
254            "content_type": "text/plain",
255            "size": 3,
256            "path": "/etc/passwd",
257        }))
258        .expect("缺省 temp_root 应可反序列化");
259        assert!(
260            forged.temp_root.is_none(),
261            "客户端 JSON 反序列化的实例不得获得受信临时根"
262        );
263    }
264}