US07-02: Harden API Authorization and Path Boundaries (#84)

photo_pipeline/path_policy.py

@@ -49,6 +49,29 @@ def resolve_within(root: Path, path: os.PathLike | str) -> Path:
     return resolved
 
 
+def resolve_in_roots(roots: Iterable[os.PathLike | str], path: os.PathLike | str) -> Path:
+    """The resolved path, proven to be inside one of ``roots`` and not excluded.
+
+    Callers must use the **returned** path for whatever they do next: validating one
+    name and then opening another is the symlink race this exists to close (US07-02).
+    The message names no path — it reaches API responses.
+
+    With no roots configured there is no boundary to check; that is a property of the
+    configuration, not permission granted to this call.
+    """
+    if is_excluded(path):
+        raise PathPolicyError("path is inside an excluded (_IGNORE/) tree")
+    roots = list(roots)
+    if not roots:
+        return Path(path)
+    for root in roots:
+        try:
+            return resolve_within(Path(root), path)
+        except PathPolicyError:
+            continue
+    raise PathPolicyError("path is outside the configured library roots")
+
+
 def iter_supported_files(root: os.PathLike | str) -> Iterator[Path]:
     """Yield supported, non-excluded files under ``root`` in deterministic order.