Virtual File System (VFS) & Access Control List (ACL)

The Polymech Storage module implements a robust Virtual File System (VFS) with an integrated Access Control List (ACL) engine. This system presents a unified file interface across different mount points, providing advanced features like bind mounting, strict path sanitization, streaming, compression, and granular permission enforcement.

1. VFS Mounts

Mounts define the physical or virtual storage locations exposed by the VFS API.

Configuration (`config/vfs.json`)

Mount configs list the available storage volumes. It can be overridden per environment (e.g. vfs-production.json) or via the VFS_CONFIG environment variable.

[
  {
    "name": "root",
    "type": "local",
    "path": "./data/root"
  },
  {
    "name": "assets",
    "type": "local",
    "path": "./data/assets"
  }
]

Special Mount Types

Named Mounts: Declared directly in configured JSON files. (e.g. root, assets).
Home Mount (home): A virtual mount that maps to {root_mount_path}/{user_uuid}. This provides each user with an isolated personal storage area. The directory automatically creates itself on first access.
User Mount (user:{uuid}): Administrative or cross-user syntax to directly refer to a specific user's home folder.
UUID Mount ({uuid}): Also acts as a direct alias to a specific user's home folder, often used for sharing files anonymously or cross-user.

2. Bind Mounts

Bind mounts map a path from one mount into a different mount. This allows data to appear in multiple locations without duplicating files, akin to Linux mount --bind.

Configuration (`config/vfs-binds.json`)

Can also be overridden by environment (e.g. vfs-binds-production.json).

[
  {
    "id": "home-assets",
    "source": { "mount": "assets" },
    "target": { "mount": "home", "path": "assets" },
    "acl": "source" 
  }
]

acl: "source": Permissions are evaluated based on the source mount's ACL contexts.
acl: "inherit": Permissions evaluate against the target mount's context (e.g., if bound to a user's home, the user owns it).

3. Access Control Lists (ACL)

The VFS features a granular, path-based ACL system. Every physical mount root or user's home directory maintains a vfs-settings.json file defining ownership and permissions.

Settings Configuration (`vfs-settings.json`)

If a vfs-settings.json doesn't exist, it is auto-generated with the default owner when first accessed.

{
  "owner": "3bb4cfbf-318b-44d3-a9d3-35680e738421",
  "groups": [],
  "acl": [
    {
      "path": "/",
      "permissions": ["read", "list"],
      "userId": "anonymous"
    },
    {
      "path": "/shared",
      "permissions": ["read", "list", "write", "mkdir", "delete", "rename", "copy"],
      "userId": "authenticated"
    }
  ]
}

Roles and Identifiers

Owner (owner field): The system owner or user UUID. Has implicit full control. System mounts use a synthetic UUID (00000000-0000-0000-0000-000000000000).
userId values in ACL:
- anonymous: Any unauthenticated public requests.
- authenticated: Any user with a valid Supabase token.
- {uuid}: A specific Supabase user ID.
Permissions Options: read, list, write, mkdir, delete, rename, copy.

API ACL Management

Users or Admins can manipulate ACL records on their owned mounts via explicit routes:

POST /api/vfs/acl/grant/{mount}
POST /api/vfs/acl/revoke/{mount}

4. API Endpoints and Interactions

All VFS endpoints follow a /{action}/{mount}/{subpath} format.

List / Glob Search: /api/vfs/ls/{mount}/*
- Query params: glob=* (pattern matching), includeSize=true (recursively calculates folder sizing with 5-day caching).
- Automatically applies .gitignore filtering when listing physical local mounts via isIgnored().
Read / Serve:
- /api/vfs/read/{mount}/*: Returns raw text.
- /api/vfs/get/{mount}/*: Serves files with correct MIME types and supports HTTP Range requests (206 Partial Content), vital for streaming large media components (video/audio).
Write / Upload:
- /api/vfs/write/{mount}/*: Direct HTTP PUT text replacement.
- /api/vfs/upload/{mount}/*: Standard multipart/form-data uploads. Piped directly to disk recursively to mitigate loading entirely in memory for large files.
ZIP Compress: /api/vfs/compress/{mount}/*
- Dynamically streams a ZIP of the targeted folder structure. Rate-limited to 3 times per minute. Refuses anonymous usage implicitly.
Deep Search Engine: /api/vfs/search/{mount}/*
- Implements deep recursive search.
- Can force-synchronize to Supabase full-text search systems via Admin hooks (/api/vfs/admin/index).

5. Security & Path Traversal Protection

The primary VFS router enforces extreme security to prevent Directory Traversal or Payload injection.

Bans System:
- Detecting null-byte injection (%00), URL-encoded bypasses (..=%5c), double-encoded bypasses (%252e), or trailing malicious slashes will instantly enforce an IP Auto-Ban logging routine resulting in a 403 Fuck You text response unless requested explicitly from localhost testing vectors.
Path Sanitization: sanitizeWritePath() forcefully filters malformed characters (accidental square brackets, extra dots, invalid symbols) for created directories or files.

5.3 KiB Raw Blame History