dsh-zju-lecture-note 2.2.5 → 2.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,6 +5,7 @@ Pure Python standard library implementation with zero external dependencies.
5
5
  """
6
6
 
7
7
  import http.client
8
+ import ipaddress
8
9
  import json
9
10
  import os
10
11
  import random
@@ -15,7 +16,7 @@ import time
15
16
  import urllib.error
16
17
  import urllib.parse
17
18
  import urllib.request
18
- from typing import Any, Dict, List, Optional
19
+ from typing import Any, Dict, List, Optional, Tuple
19
20
 
20
21
  from .security import REDACTOR, sanitize_cookie_header
21
22
 
@@ -210,6 +211,7 @@ def _fetch_bytes(
210
211
  attempts: int = _RETRY_ATTEMPTS,
211
212
  max_bytes: Optional[int] = None,
212
213
  allow_cross_host_redirect: bool = False,
214
+ diagnostics: Optional[List[str]] = None,
213
215
  ) -> bytes:
214
216
  """GET ``url`` and read the **whole** body, retrying transient failures.
215
217
 
@@ -229,7 +231,11 @@ def _fetch_bytes(
229
231
  try:
230
232
  if allow_cross_host_redirect:
231
233
  context = _open_request(
232
- url, headers, timeout, allow_cross_host_redirect=True
234
+ url,
235
+ headers,
236
+ timeout,
237
+ allow_cross_host_redirect=True,
238
+ diagnostics=diagnostics,
233
239
  )
234
240
  else:
235
241
  context = _open_request(url, headers, timeout)
@@ -252,22 +258,77 @@ def _fetch_bytes(
252
258
  raise last
253
259
 
254
260
 
261
+ _DEFAULT_PORTS = {"http": 80, "https": 443}
262
+
263
+
264
+ def _origin(url: str) -> Tuple[str, str, int]:
265
+ """``(scheme, host, port)`` with default ports filled in.
266
+
267
+ hostname+scheme is not enough: ``https://a:443`` and ``https://a:8443`` are
268
+ different origins, and credentials must not cross that boundary.
269
+ """
270
+ parsed = urllib.parse.urlparse(url or "")
271
+ scheme = (parsed.scheme or "").lower()
272
+ host = (parsed.hostname or "").lower().rstrip(".")
273
+ try:
274
+ port = parsed.port
275
+ except ValueError:
276
+ port = None
277
+ if port is None:
278
+ port = _DEFAULT_PORTS.get(scheme, 0)
279
+ return scheme, host, port
280
+
281
+
282
+ def _is_forbidden_redirect_host(host: str) -> bool:
283
+ """IP literals, loopback and private names are never valid redirect targets."""
284
+ value = (host or "").strip().lower().rstrip(".")
285
+ if not value:
286
+ return True
287
+ if value == "localhost" or value.endswith(".localhost"):
288
+ return True
289
+ try:
290
+ ipaddress.ip_address(value)
291
+ except ValueError:
292
+ return False
293
+ # Any IP literal (loopback, link-local, RFC1918, ::1, ...) is refused:
294
+ # a media CDN never needs one, and a redirect to one is the classic SSRF.
295
+ return True
296
+
297
+
298
+ def _redirect_block_reason(old_url: str, new_url: str) -> str:
299
+ """Why a redirect must not be followed, or an empty string to allow it."""
300
+ old_scheme, _, _ = _origin(old_url)
301
+ new_scheme, new_host, new_port = _origin(new_url)
302
+ parsed = urllib.parse.urlparse(new_url or "")
303
+ if parsed.username or parsed.password:
304
+ return "已阻止跳转到含凭据的 URL(保护登录态)"
305
+ if old_scheme == "https" and new_scheme != "https":
306
+ return "已阻止 HTTPS 降级重定向(保护登录凭据)"
307
+ if new_scheme not in ("http", "https"):
308
+ return f"已阻止跳转到非 HTTP(S) 地址: {new_scheme or '(无协议)'}"
309
+ if _is_forbidden_redirect_host(new_host):
310
+ return f"已阻止跳转到受限主机: {new_host or '(未知主机)'}"
311
+ return ""
312
+
313
+
255
314
  class _SameHostRedirectHandler(urllib.request.HTTPRedirectHandler):
256
- """Follow redirects only on the classroom host.
315
+ """Follow redirects only on the classroom **origin**.
257
316
 
258
317
  ``urllib`` re-sends request headers on a redirect, so a compromised or
259
318
  misconfigured endpoint that answers ``302`` to another origin would leak
260
- the ``Cookie`` header. Cross-origin redirects are refused instead.
319
+ the ``Cookie`` header. Scheme, host and port must all match — a downgrade
320
+ to HTTP or a different port is refused as well.
261
321
  """
262
322
 
263
323
  def redirect_request(self, req, fp, code, msg, headers, newurl): # noqa: D401
264
- parsed = urllib.parse.urlparse(newurl)
265
- target = (parsed.hostname or "").lower()
266
- if target != BASE_HOST or parsed.scheme != "https":
324
+ reason = _redirect_block_reason(req.full_url, newurl)
325
+ if not reason and _origin(newurl) != _origin(BASE_URL):
326
+ reason = f"拒绝跨域重定向到 {_origin(newurl)[1] or '(未知主机)'}(保护登录凭据)"
327
+ if reason:
267
328
  raise urllib.error.HTTPError(
268
329
  req.full_url,
269
330
  code,
270
- f"拒绝跨域或非 HTTPS 重定向到 {target or '(未知主机)'}(保护登录凭据)",
331
+ reason,
271
332
  headers,
272
333
  fp,
273
334
  )
@@ -277,21 +338,36 @@ class _SameHostRedirectHandler(urllib.request.HTTPRedirectHandler):
277
338
  class _StripAuthOnCrossHostRedirectHandler(urllib.request.HTTPRedirectHandler):
278
339
  """Allow slide-CDN redirects, but never carry credentials across origins.
279
340
 
280
- Slide screenshots are static files and may redirect to a media host. The
281
- classroom API keeps the stricter same-host rule; this handler is only used
282
- for image downloads, and it drops ``Cookie`` / ``Authorization`` whenever
283
- the redirect changes the host.
341
+ Slide screenshots are static files and may redirect to a media host. Only
342
+ ``*.zju.edu.cn`` targets are followed (one hop at a time, re-validated by
343
+ urllib for every hop); everything else is blocked and recorded. Whenever
344
+ the redirect changes scheme/host/port, ``Cookie`` / ``Authorization`` /
345
+ ``Proxy-Authorization`` are dropped.
284
346
  """
285
347
 
348
+ def __init__(self, diagnostics: Optional[List[str]] = None) -> None:
349
+ super().__init__()
350
+ self.diagnostics = diagnostics
351
+
352
+ def _blocked(self, reason: str) -> None:
353
+ if self.diagnostics is not None:
354
+ self.diagnostics.append(reason)
355
+
286
356
  def redirect_request(self, req, fp, code, msg, headers, newurl): # noqa: D401
357
+ reason = _redirect_block_reason(req.full_url, newurl)
358
+ if not reason:
359
+ _, new_host, _ = _origin(newurl)
360
+ if not is_zju_host(new_host):
361
+ reason = f"已阻止跳转到非浙大域: {new_host or '(未知主机)'}"
362
+ if reason:
363
+ self._blocked(reason)
364
+ return None
287
365
  new_request = super().redirect_request(req, fp, code, msg, headers, newurl)
288
366
  if new_request is None:
289
367
  return None
290
- old_host = (urllib.parse.urlparse(req.full_url).hostname or "").lower()
291
- new_host = (urllib.parse.urlparse(newurl).hostname or "").lower()
292
- if old_host != new_host:
293
- new_request.remove_header("Cookie")
294
- new_request.remove_header("Authorization")
368
+ if _origin(req.full_url) != _origin(newurl):
369
+ for header in ("Cookie", "Authorization", "Proxy-Authorization"):
370
+ new_request.remove_header(header)
295
371
  return new_request
296
372
 
297
373
 
@@ -300,10 +376,11 @@ def _open_request(
300
376
  headers: Dict[str, str],
301
377
  timeout: int,
302
378
  allow_cross_host_redirect: bool = False,
379
+ diagnostics: Optional[List[str]] = None,
303
380
  ):
304
381
  """Open ``url`` with certificate verification and a redirect policy."""
305
382
  redirect_handler = (
306
- _StripAuthOnCrossHostRedirectHandler()
383
+ _StripAuthOnCrossHostRedirectHandler(diagnostics)
307
384
  if allow_cross_host_redirect
308
385
  else _SameHostRedirectHandler()
309
386
  )
@@ -19,6 +19,37 @@ class CoursewareError(Exception):
19
19
  pass
20
20
 
21
21
 
22
+ #: 课件是 zip 容器:解压前先按声明的 file_size 累计,避免 zip bomb。
23
+ MAX_ARCHIVE_TOTAL_BYTES = 64 * 1024 * 1024
24
+ MAX_ARCHIVE_MEMBER_BYTES = 16 * 1024 * 1024
25
+
26
+
27
+ def _validate_zip_members(archive: zipfile.ZipFile) -> None:
28
+ """Reject an archive whose declared uncompressed size exceeds the budget."""
29
+ total = 0
30
+ for info in archive.infolist():
31
+ if info.file_size > MAX_ARCHIVE_MEMBER_BYTES:
32
+ raise CoursewareError(
33
+ f"课件包含超过 {MAX_ARCHIVE_MEMBER_BYTES // (1024 * 1024)} MiB "
34
+ f"的成员({info.filename}),已拒绝解压"
35
+ )
36
+ total += info.file_size
37
+ if total > MAX_ARCHIVE_TOTAL_BYTES:
38
+ raise CoursewareError(
39
+ f"课件解压后超过 {MAX_ARCHIVE_TOTAL_BYTES // (1024 * 1024)} MiB "
40
+ "上限,已拒绝解压"
41
+ )
42
+
43
+
44
+ def _read_zip_member(archive: zipfile.ZipFile, name: str) -> bytes:
45
+ info = archive.getinfo(name)
46
+ if info.file_size > MAX_ARCHIVE_MEMBER_BYTES:
47
+ raise CoursewareError(
48
+ f"课件成员 {name} 超过 {MAX_ARCHIVE_MEMBER_BYTES // (1024 * 1024)} MiB 上限"
49
+ )
50
+ return archive.read(info)
51
+
52
+
22
53
  def extract_courseware_text(path: str, max_chars: Optional[int] = None) -> str:
23
54
  """Extract plain text from local courseware files.
24
55
 
@@ -73,6 +104,7 @@ def _extract_pptx(path: str) -> str:
73
104
  """Extract text from slides inside PPTX zip package."""
74
105
  try:
75
106
  with zipfile.ZipFile(path, "r") as z:
107
+ _validate_zip_members(z)
76
108
  slide_names = [
77
109
  n for n in z.namelist()
78
110
  if re.match(r"^ppt/slides/slide\d+\.xml$", n)
@@ -84,7 +116,7 @@ def _extract_pptx(path: str) -> str:
84
116
 
85
117
  parts = []
86
118
  for idx, name in enumerate(slide_names, start=1):
87
- xml_content = z.read(name).decode("utf-8", "ignore")
119
+ xml_content = _read_zip_member(z, name).decode("utf-8", "ignore")
88
120
  texts = re.findall(r"<a:t>([^<]*)</a:t>", xml_content)
89
121
  cleaned = " ".join(t.strip() for t in texts if t.strip())
90
122
  if cleaned:
@@ -115,7 +147,10 @@ def _extract_docx(path: str) -> str:
115
147
  """
116
148
  try:
117
149
  with zipfile.ZipFile(path, "r") as z:
118
- xml_content = z.read("word/document.xml").decode("utf-8", "ignore")
150
+ _validate_zip_members(z)
151
+ xml_content = _read_zip_member(z, "word/document.xml").decode(
152
+ "utf-8", "ignore"
153
+ )
119
154
  except Exception as e:
120
155
  raise CoursewareError(f"读取 DOCX 课件失败: {e}")
121
156
 
@@ -26,16 +26,20 @@ import hashlib
26
26
  import json
27
27
  import os
28
28
  import platform
29
+ import re
29
30
  import shutil
30
31
  import subprocess
31
32
  import sys
32
33
  import tarfile
33
34
  import tempfile
34
35
  import time
36
+ import urllib.parse
35
37
  import zipfile
36
38
  from dataclasses import dataclass, field
37
39
  from typing import Any, Dict, List, Optional, Tuple
38
40
 
41
+ from .security import REDACTOR
42
+
39
43
  TYPST_ENV = "ZJU_TYPST_BIN"
40
44
  AUTO_INSTALL_ENV = "ZJU_TYPST_AUTO_INSTALL"
41
45
  MIRROR_ENV = "ZJU_TYPST_MIRROR"
@@ -45,6 +49,17 @@ MIN_VERSION = (0, 13, 0)
45
49
  RELEASE_URL = "https://github.com/typst/typst/releases/download/v{version}/{file}"
46
50
  CACHE_APP = "dsh-zju-lecture"
47
51
 
52
+ #: Typst 归档实测约 20–30 MB;256 MiB 是硬上限,异常大响应直接中断。
53
+ MAX_DOWNLOAD_BYTES = 256 * 1024 * 1024
54
+
55
+
56
+ def _size_text(byte_count: int) -> str:
57
+ if byte_count >= 1024 * 1024:
58
+ return f"{byte_count // (1024 * 1024)} MiB"
59
+ if byte_count >= 1024:
60
+ return f"{byte_count // 1024} KiB"
61
+ return f"{byte_count} 字节"
62
+
48
63
  HERE = os.path.dirname(os.path.abspath(__file__))
49
64
  MANIFEST_PATH = os.path.join(HERE, "typst_assets.json")
50
65
  PACKAGE_PATH = os.path.join(HERE, "typst-packages")
@@ -261,10 +276,46 @@ def probe(auto_install: bool = False) -> TypstInfo:
261
276
  # ---------------------------------------------------------------- 安装
262
277
 
263
278
 
279
+ _URL_RE = re.compile(r"https?://[^\s]+", re.IGNORECASE)
280
+
281
+
282
+ def _redact_url(url: str) -> str:
283
+ """只保留 ``scheme://host[:port]/path``,去掉 userinfo / query / fragment。"""
284
+ text = str(url or "").strip()
285
+ if not text:
286
+ return ""
287
+ try:
288
+ parsed = urllib.parse.urlparse(text)
289
+ except ValueError:
290
+ return "[REDACTED]"
291
+ if not parsed.scheme or not parsed.netloc:
292
+ return REDACTOR.redact(text)
293
+ host = parsed.hostname or ""
294
+ netloc = f"[{host}]" if ":" in host and not host.startswith("[") else host
295
+ try:
296
+ port = parsed.port
297
+ except ValueError:
298
+ port = None
299
+ if port:
300
+ netloc = f"{netloc}:{port}"
301
+ return REDACTOR.redact(f"{parsed.scheme}://{netloc}{parsed.path}")
302
+
303
+
304
+ def _redact_text(message: object) -> str:
305
+ """脱敏任意诊断文本:先洗掉 URL 里的凭据,再交给进程级 redactor。"""
306
+ text = str(message)
307
+ text = _URL_RE.sub(lambda match: _redact_url(match.group(0)), text)
308
+ return REDACTOR.redact(text)
309
+
310
+
264
311
  def _progress(message: str) -> None:
265
- """进度只写 stderr:工具的返回值要保持可读,不混入下载日志。"""
312
+ """进度只写 stderr:工具的返回值要保持可读,不混入下载日志。
313
+
314
+ 镜像 URL 可能带 userinfo 或签名 query;进入 stderr 前必须先脱敏,
315
+ 否则宿主的日志/会话记录会替用户保存一份凭据。
316
+ """
266
317
  try:
267
- sys.stderr.write(message + "\n")
318
+ sys.stderr.write(_redact_text(message) + "\n")
268
319
  sys.stderr.flush()
269
320
  except Exception: # noqa: BLE001 - 日志永远不能影响主流程
270
321
  pass
@@ -298,14 +349,24 @@ def _download(url: str, target: str, retries: int = 3) -> None:
298
349
  )
299
350
  with urllib.request.urlopen(request, timeout=180, context=context) as response:
300
351
  total = int(response.headers.get("Content-Length") or 0)
352
+ if total > MAX_DOWNLOAD_BYTES:
353
+ raise RuntimeError(
354
+ f"下载内容 {total} 字节,超过 "
355
+ f"{_size_text(MAX_DOWNLOAD_BYTES)} 上限"
356
+ )
301
357
  done = 0
302
358
  with open(target, "wb") as handle:
303
359
  while True:
304
360
  chunk = response.read(1 << 20)
305
361
  if not chunk:
306
362
  break
307
- handle.write(chunk)
308
363
  done += len(chunk)
364
+ if done > MAX_DOWNLOAD_BYTES:
365
+ raise RuntimeError(
366
+ f"下载超过 {_size_text(MAX_DOWNLOAD_BYTES)} "
367
+ "上限,已中断"
368
+ )
369
+ handle.write(chunk)
309
370
  if total and done % (5 << 20) < (1 << 20):
310
371
  _progress(
311
372
  f" 下载 Typst {done * 100 // max(total, 1)}% "
@@ -314,26 +375,46 @@ def _download(url: str, target: str, retries: int = 3) -> None:
314
375
  return
315
376
  except Exception as exc: # noqa: BLE001 - 网络抖动要重试
316
377
  last = exc
378
+ try:
379
+ os.remove(target)
380
+ except OSError:
381
+ pass
317
382
  _progress(f" 下载失败(第 {attempt}/{retries} 次):{exc}")
318
383
  if attempt < retries:
319
384
  time.sleep(2 * attempt)
320
- raise RuntimeError(str(last) if last else "下载失败")
321
-
385
+ raise RuntimeError(_redact_text(last) if last else "下载失败")
386
+
387
+
388
+ def _safe_members(
389
+ archive: zipfile.ZipFile | tarfile.TarFile,
390
+ destination: str = "",
391
+ ) -> List[str]:
392
+ """拒绝绝对路径、``..``、符号链接/硬链接与越界解压目标。"""
393
+ root = os.path.abspath(destination) if destination else ""
394
+
395
+ def check(name: str) -> None:
396
+ normalized = os.path.normpath(name)
397
+ if normalized.startswith("..") or os.path.isabs(normalized):
398
+ raise ValueError(f"归档包含可疑路径:{name}")
399
+ if not root:
400
+ return
401
+ try:
402
+ target = os.path.abspath(os.path.join(root, normalized))
403
+ if os.path.commonpath([root, target]) != root:
404
+ raise ValueError(f"归档成员会解压到目录之外:{name}")
405
+ except ValueError as exc:
406
+ raise ValueError(f"归档成员路径不合法:{name}") from exc
322
407
 
323
- def _safe_members(archive: zipfile.ZipFile | tarfile.TarFile) -> List[str]:
324
- """拒绝绝对路径与 ``..``:解压不能让归档写到缓存目录之外。"""
325
408
  names: List[str] = []
326
409
  if isinstance(archive, zipfile.ZipFile):
327
410
  for name in archive.namelist():
328
- normalized = os.path.normpath(name)
329
- if normalized.startswith("..") or os.path.isabs(normalized):
330
- raise ValueError(f"归档包含可疑路径:{name}")
411
+ check(name)
331
412
  names.append(name)
332
413
  else:
333
414
  for member in archive.getmembers():
334
- normalized = os.path.normpath(member.name)
335
- if normalized.startswith("..") or os.path.isabs(normalized):
336
- raise ValueError(f"归档包含可疑路径:{member.name}")
415
+ if member.issym() or member.islnk():
416
+ raise ValueError(f"归档包含链接成员,已拒绝:{member.name}")
417
+ check(member.name)
337
418
  names.append(member.name)
338
419
  return names
339
420
 
@@ -345,11 +426,11 @@ def _extract(archive_path: str, kind: str, destination: str) -> str:
345
426
 
346
427
  if kind == "zip":
347
428
  with zipfile.ZipFile(archive_path) as archive:
348
- _safe_members(archive)
429
+ _safe_members(archive, destination)
349
430
  archive.extractall(destination)
350
431
  else:
351
432
  with tarfile.open(archive_path, "r:xz") as archive:
352
- _safe_members(archive)
433
+ _safe_members(archive, destination)
353
434
  archive.extractall(destination)
354
435
 
355
436
  for current, _dirs, files in os.walk(destination):
@@ -441,7 +522,7 @@ def install(force: bool = False) -> TypstInfo:
441
522
  _download(url, archive_path)
442
523
  except Exception as exc: # noqa: BLE001 - 网络失败要能解释
443
524
  return _fail([
444
- f"下载 Typst 失败:{exc}",
525
+ f"下载 Typst 失败:{_redact_text(exc)}",
445
526
  "可设置 ZJU_TYPST_MIRROR 走镜像,或手动安装后设置 ZJU_TYPST_BIN。",
446
527
  ])
447
528
 
@@ -509,7 +590,7 @@ def describe(workspace_root: str = "", auto_install: bool = False) -> Dict[str,
509
590
  "cache": os.path.join(cache_root(), f"v{manifest.get('version') or '?'}"),
510
591
  "compile_cache": compile_cache_path(workspace_root) if workspace_root else "",
511
592
  "auto_install": auto_install,
512
- "mirror": os.environ.get(MIRROR_ENV, "").strip(),
593
+ "mirror": _redact_url(os.environ.get(MIRROR_ENV, "").strip()),
513
594
  }
514
595
 
515
596
 
@@ -15,7 +15,9 @@ Two severity levels:
15
15
 
16
16
  import os
17
17
  import re
18
+ import secrets
18
19
  import shutil
20
+ import stat
19
21
  import tempfile
20
22
  import time
21
23
  from typing import List, NamedTuple
@@ -523,20 +525,25 @@ def backup_directory() -> str:
523
525
  ``ZJU_BACKUP_DIR`` lets a host point it at a directory of its own.
524
526
  """
525
527
  override = os.environ.get(BACKUP_DIR_ENV, "").strip()
526
- if override:
527
- return os.path.abspath(os.path.expanduser(override))
528
- return os.path.join(tempfile.gettempdir(), _BACKUP_DIRNAME)
528
+ directory = (
529
+ os.path.abspath(os.path.expanduser(override))
530
+ if override
531
+ else os.path.join(tempfile.gettempdir(), _BACKUP_DIRNAME)
532
+ )
533
+ # 讲义原文的副本只给当前系统用户看:目录必须是 0700,而不是继承 umask。
534
+ try:
535
+ os.makedirs(directory, mode=0o700, exist_ok=True)
536
+ os.chmod(directory, 0o700)
537
+ except OSError:
538
+ pass
539
+ return directory
529
540
 
530
541
 
531
542
  def _unique_backup_path(directory: str, source: str) -> str:
543
+ """Predictable names let another local user pre-create/read the backup."""
532
544
  stem = os.path.splitext(os.path.basename(source))[0] or "note"
533
545
  stamp = time.strftime("%Y%m%d-%H%M%S")
534
- candidate = os.path.join(directory, f"{stem}.{stamp}.bak")
535
- counter = 1
536
- while os.path.exists(candidate):
537
- counter += 1
538
- candidate = os.path.join(directory, f"{stem}.{stamp}-{counter}.bak")
539
- return candidate
546
+ return os.path.join(directory, f"{stem}.{stamp}.{secrets.token_hex(4)}.bak")
540
547
 
541
548
 
542
549
  def write_atomic(path: str, text: str) -> None:
@@ -570,14 +577,31 @@ def write_with_backup(path: str, text: str, backup_dir: str = None) -> str:
570
577
  ``backup_dir`` (or ``ZJU_BACKUP_DIR``) selects the destination; when it
571
578
  cannot be created the backup falls back to ``<path>.bak`` so the data is
572
579
  never silently unprotected.
580
+
581
+ Symbolic links are refused before anything is copied: ``copyfile`` and a
582
+ plain ``open`` would follow them and let a pre-planted link redirect the
583
+ write outside the workspace.
573
584
  """
585
+ try:
586
+ if stat.S_ISLNK(os.lstat(path).st_mode):
587
+ raise OSError(f"拒绝写入符号链接: {path}")
588
+ except FileNotFoundError:
589
+ pass
590
+
574
591
  directory = os.path.abspath(os.path.expanduser(backup_dir)) if backup_dir else backup_directory()
575
592
  try:
576
- os.makedirs(directory, exist_ok=True)
593
+ os.makedirs(directory, mode=0o700, exist_ok=True)
594
+ os.chmod(directory, 0o700)
577
595
  backup = _unique_backup_path(directory, path)
578
596
  except OSError:
579
597
  backup = path + ".bak"
598
+ if os.path.islink(backup):
599
+ raise OSError(f"拒绝写入符号链接备份: {backup}")
580
600
  shutil.copyfile(path, backup)
601
+ try:
602
+ os.chmod(backup, 0o600)
603
+ except OSError:
604
+ pass
581
605
  write_atomic(path, text)
582
606
  return backup
583
607
 
@@ -32,9 +32,9 @@ file is opened or created, and note writing refuses to leave the workspace.
32
32
 
33
33
  import os
34
34
  import re
35
- from typing import List, Optional, Sequence, Tuple
35
+ from typing import Iterable, List, Optional, Sequence, Tuple
36
36
 
37
- from .security import LocalFileError
37
+ from .security import LocalFileError, guard_local_file
38
38
 
39
39
  #: The session workspace, injected by the host (dsh plugin sets it per call).
40
40
  WORKSPACE_ENV = "ZJU_WORKSPACE"
@@ -271,6 +271,61 @@ def is_inside_workspace(path: str) -> bool:
271
271
  return False
272
272
 
273
273
 
274
+ def require_workspace_path(
275
+ raw: str,
276
+ *,
277
+ extensions: Iterable[str],
278
+ kind: str = "文件",
279
+ write: bool = False,
280
+ ) -> Tuple[Optional[str], Optional[str]]:
281
+ """Resolve, guard and confine a model-supplied path to the workspace.
282
+
283
+ Returns ``(resolved, error)``. ``error`` is a user-facing sentence that
284
+ never contains file contents. Order matters: resolve → realpath →
285
+ workspace check → credential/extension guard → (for writes) realpath
286
+ again, so a symlink planted between the two checks cannot move the
287
+ target outside the workspace.
288
+ """
289
+ text = str(raw or "").strip()
290
+ if not text:
291
+ return None, f"{kind}路径不能为空"
292
+
293
+ resolved, tried = resolve_path(text)
294
+ if resolved is None:
295
+ return None, f"找不到{kind}: {text}{describe_attempts(tried)}"
296
+
297
+ base = primary_workspace()
298
+ if not _is_inside(base, resolved):
299
+ return None, f"拒绝访问工作区之外的文件: {resolved}"
300
+
301
+ try:
302
+ real_path = os.path.realpath(resolved)
303
+ except OSError as exc:
304
+ return None, f"无法解析{kind}路径: {exc}"
305
+
306
+ if not _is_inside(base, real_path):
307
+ return None, f"拒绝访问工作区之外的文件: {resolved}"
308
+
309
+ try:
310
+ guarded = guard_local_file(real_path, extensions, kind=kind)
311
+ except LocalFileError as exc:
312
+ return None, str(exc)
313
+
314
+ if not _is_inside(base, guarded):
315
+ return None, f"拒绝访问工作区之外的文件: {guarded}"
316
+
317
+ if write:
318
+ try:
319
+ again = os.path.realpath(guarded)
320
+ except OSError as exc:
321
+ return None, f"无法解析{kind}路径: {exc}"
322
+ if not _is_inside(base, again):
323
+ return None, f"拒绝访问工作区之外的文件: {guarded}"
324
+ guarded = again
325
+
326
+ return guarded, None
327
+
328
+
274
329
  def artifact_dir(
275
330
  subdir: str = "",
276
331
  default: str = "artifacts",
@@ -146,7 +146,15 @@
146
146
  )
147
147
  }
148
148
 
149
- // ── 6. 类型速查(写正文时照着选色相) ──
149
+ // ── 6. 封面包装 ──
150
+ // 调用处只传命名参数(`#scholia-cover(title: "...")`),值由渲染器按
151
+ // Typst 字符串字面量转义;位置参数一旦被注入的引号截断,后面就能接
152
+ // `#read(...)` 之类的可执行代码。
153
+ #let scholia-cover(title: "", subtitle: none, author: none, date: none, kicker: none) = {
154
+ cover(title, subtitle: subtitle, author: author, date: date, kicker: kicker)
155
+ }
156
+
157
+ // ── 7. 类型速查(写正文时照着选色相) ──
150
158
  // 结论/定理/证明/回指 → thm 蓝
151
159
  // 定义/公理/术语/标签 → def 青绿
152
160
  // 例子/练习/填空缺口 → eg 琥珀