yang_base/action/
upload.rs1use 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#[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 #[serde(default)]
34 temp_root: Option<PathBuf>,
35}
36
37impl UploadedFile {
38 pub fn field_name(&self) -> &str {
40 &self.field_name
41 }
42
43 pub fn original_filename(&self) -> &str {
45 &self.original_filename
46 }
47
48 pub fn content_type(&self) -> &str {
50 &self.content_type
51 }
52
53 pub const fn size(&self) -> u64 {
55 self.size
56 }
57
58 pub fn path(&self) -> &Path {
60 &self.path
61 }
62
63 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 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 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 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 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 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}