refactor(asset-storage): fix security problems

api/agent-notes/configs/feature/__init__.py.md

@@ -0,0 +1,9 @@
+Summary:
+Summary:
+- Application configuration definitions, including file access settings.
+
+Invariants:
+- File access settings drive signed URL expiration and base URLs.
+
+Tests:
+- Config parsing tests under tests/unit_tests/configs.

api/agent-notes/controllers/files/__init__.py.md

@@ -0,0 +1,9 @@
+Summary:
+- Registers file-related API namespaces and routes for files service.
+- Includes app-assets download proxy controller.
+
+Invariants:
+- files_ns must include all file controller modules to register routes.
+
+Tests:
+- Coverage via controller unit tests and route registration smoke checks.

api/agent-notes/controllers/files/app_assets_download.py.md

@@ -0,0 +1,14 @@
+Summary:
+- App assets download proxy endpoint (signed URL verification, stream from storage).
+
+Invariants:
+- Validates AssetPath fields (UUIDs, asset_type allowlist).
+- Verifies tenant-scoped signature and expiration before reading storage.
+- URL uses expires_at/nonce/sign query params.
+
+Edge Cases:
+- Missing files return NotFound.
+- Invalid signature or expired link returns Forbidden.
+
+Tests:
+- Verify signature validation and invalid/expired cases.

api/agent-notes/core/app_assets/builder/file_builder.py.md

@@ -0,0 +1,9 @@
+Summary:
+Summary:
+- Collects file assets and emits FileAsset entries with storage keys.
+
+Invariants:
+- Storage keys are derived via AppAssetStorage for draft files.
+
+Tests:
+- Covered by asset build pipeline tests.

api/agent-notes/core/app_assets/builder/skill_builder.py.md

@@ -0,0 +1,14 @@
+Summary:
+Summary:
+- Builds skill artifacts from markdown assets and uploads resolved outputs.
+
+Invariants:
+- Reads draft asset content via AppAssetStorage refs.
+- Writes resolved artifacts via AppAssetStorage refs.
+- FileAsset storage keys are derived via AppAssetStorage.
+
+Edge Cases:
+- Missing or invalid JSON content yields empty skill content/metadata.
+
+Tests:
+- Build pipeline unit tests covering compile/upload paths.

api/agent-notes/core/app_assets/converters.py.md

@@ -0,0 +1,9 @@
+Summary:
+Summary:
+- Converts AppAssetFileTree to FileAsset items for packaging.
+
+Invariants:
+- Storage keys for assets are derived via AppAssetStorage.
+
+Tests:
+- Used in packaging/service tests for asset bundles.

api/agent-notes/core/app_assets/parser/asset_parser.py.md

@@ -0,0 +1,9 @@
+Summary:
+Summary:
+- Builds AssetItem entries for asset trees using AssetPath-derived storage keys.
+
+Invariants:
+- Uses AssetPath to compute draft storage keys.
+
+Tests:
+- Covered by asset parsing and packaging tests.

api/agent-notes/core/app_assets/storage.py.md

@@ -0,0 +1,19 @@
+Summary:
+- Defines AssetPath facade + typed asset path classes for app-asset storage access.
+- Maps asset paths to storage keys and generates presigned or signed-proxy URLs.
+- Signs proxy URLs using tenant private keys and enforces expiration.
+- Exposes app_asset_storage singleton for reuse.
+
+Invariants:
+- AssetPathBase fields (tenant_id/app_id/resource_id/node_id) must be UUIDs.
+- AssetPath.from_components enforces valid types and resolved node_id presence.
+- Storage keys are derived internally via AssetPathBase.get_storage_key; callers never supply raw paths.
+- AppAssetStorage.storage returns the cached presign wrapper (not the raw storage).
+
+Edge Cases:
+- Storage backends without presign support must fall back to signed proxy URLs.
+- Signed proxy verification enforces expiration and tenant-scoped signing keys.
+- load_or_none treats SilentStorage "File Not Found" bytes as missing.
+
+Tests:
+- Unit tests for ref validation, storage key mapping, and signed URL verification.

api/agent-notes/core/app_bundle/source_zip_extractor.py.md

@@ -0,0 +1,10 @@
+Summary:
+Summary:
+- Extracts asset files from a zip and persists them into app asset storage.
+
+Invariants:
+- Rejects path traversal/absolute/backslash paths.
+- Saves extracted files via AppAssetStorage draft refs.
+
+Tests:
+- Zip security edge cases and tree construction tests.

api/agent-notes/core/sandbox/initializer/app_assets_initializer.py.md

@@ -0,0 +1,9 @@
+Summary:
+Summary:
+- Downloads published app asset zip into sandbox and extracts it.
+
+Invariants:
+- Uses AppAssetStorage to generate download URLs for build zips (internal URL).
+
+Tests:
+- Sandbox initialization integration tests.

api/agent-notes/core/sandbox/initializer/draft_app_assets_initializer.py.md

@@ -0,0 +1,12 @@
+Summary:
+Summary:
+- Downloads draft/resolved assets into sandbox for draft execution.
+
+Invariants:
+- Uses AppAssetStorage to generate download URLs for draft/resolved refs (internal URL).
+
+Edge Cases:
+- No nodes -> returns early.
+
+Tests:
+- Sandbox draft initialization tests.

api/agent-notes/core/skill/skill_manager.py.md

@@ -0,0 +1,9 @@
+Summary:
+Summary:
+- Loads/saves skill bundles to app asset storage.
+
+Invariants:
+- Skill bundles use AppAssetStorage refs and JSON serialization.
+
+Tests:
+- Covered by skill bundle build/load unit tests.

api/agent-notes/services/app_asset_service.py.md

@@ -0,0 +1,14 @@
+Summary:
+- App asset CRUD, publish/build pipeline, and presigned URL generation.
+
+Invariants:
+- Asset storage access goes through AppAssetStorage + AssetPath, using app_asset_storage singleton.
+- Tree operations require tenant/app scoping and lock for mutation.
+- Asset zips are packaged via raw storage with storage keys from AppAssetStorage.
+
+Edge Cases:
+- File nodes larger than preview limit are rejected.
+- Deletion runs asynchronously; storage failures are logged.
+
+Tests:
+- Unit tests for storage URL generation and publish/build flows.

api/agent-notes/services/app_bundle_service.py.md

@@ -0,0 +1,10 @@
+Summary:
+Summary:
+- Imports app bundles, including asset extraction into app asset storage.
+
+Invariants:
+- Asset imports respect zip security checks and tenant/app scoping.
+- Draft asset packaging uses AppAssetStorage for key mapping.
+
+Tests:
+- Bundle import unit tests and zip validation coverage.

api/agent-notes/tests/unit_tests/core/app_assets/test_storage.py.md

@@ -0,0 +1,6 @@
+Summary:
+Summary:
+- Unit tests for AppAssetStorage ref validation, key mapping, and signing.
+
+Tests:
+- Covers valid/invalid refs, signature verify, expiration handling, and proxy URL generation.