Webcloster Storage Wrapper

What the Wrapper is

The Webcloster Storage Wrapper is a multi-tenant file-storage API. It sits in front of an object store (Cloudflare R2, or any S3-compatible bucket) and turns raw blob storage into a governed service: projects, per-user quotas, plans, signed URLs, asynchronous image compression, per-integration rate limits, and — its defining feature — isolation that survives a leaked API key.

One deployment serves many projects (tenants). Each project brings its own users, files, quota rules, and one or more client applications. The wrapper keeps every tenant’s data strictly partitioned, and then goes one step further: it partitions data within a tenant, down to an individual end-user and even to a single workspace (“Ruta”) beneath that user.

The multi-tenant problem it solves

Most “storage-as-a-feature” backends authorize with a shared integration key: the mobile or web app ships with one API key, and that key can read and write everything the tenant owns. This is convenient and dangerous. A key baked into an app build is extractable — an APK can be unpacked in minutes — and once extracted, it grants the attacker the same blanket access the app had: every user’s files, every workspace, across the whole tenant.

The wrapper refuses to make the integration key the security boundary. The key only answers the question “which app is calling?”. The real boundary is the login: when an end-user (or a workspace) signs in, the wrapper mints a short-lived, subject-bound token scoped to exactly that identity. That token — not the shared key — decides what the caller can see.

The one-line philosophy

Identify apps with keys; authorize identities with tokens. A leaked build key can mint nothing it could not already do under its declared scopes, and can never see one specific user’s or workspace’s private files.

Who this is for

Integrators

Teams embedding the wrapper into a web or mobile app. Start with the Liquida integration guide to mint user and space tokens and wire rate limits and CORS.

Platform / DevOps

Operators bringing the stack up. See Deployment and Redis, migrations & env.

New engineers

Anyone who needs to understand why the system is built this way, not just which endpoints exist. Read the isolation model and authorization axes.

Security reviewers

The guard-per-axis design and its rationale are documented in authorization axes and design decisions.

High-level capabilities

• Multi-tenant projects — each project is an isolated tenant with its own API keys, integrations, plans, users, and storage accounting.
• Subject-bound tokens — end-user tokens and space (“Ruta”) tokens pin a caller to a single identity, enforced by hard guards independent of scopes.
• Five authorization axes — project, scope, actor-type, subject, and space — each covered by a dedicated middleware guard.
• Plans & quotas — per-user max_file_size, allowed_mimes, and storage_limit, enforced atomically on upload.
• Files & signed URLs — multipart upload, folder/tag/classifier metadata, public permanent URLs, and TTL-bounded signed URLs for private objects.
• Asynchronous image compression — upload returns 202 immediately; a separate worker compresses with Sharp and replaces the object in place.
• Per-integration rate limiting & CORS — hierarchical policy (integration → project → global) with a dev_mode bypass.
• Real-time & historical stats — Redis day-counters flushed to Postgres.
• Live API reference — an OpenAPI 3.1 spec rendered with Scalar at /api/v1/docs, plus a machine-readable /llms.txt guide for LLMs and coding agents.

Architecture at a glance

The portal and demo front-ends reach the Hono API — directly, or through the demo BFF that holds the integration key server-side. The API and a separate, CPU-isolated compression worker share Postgres, Redis, and Cloudflare R2.

Note

The async image-compression flow and the isolation model each have their own diagram.

Where to go next

Isolation modelProject → integration → user (Master) → space (Ruta), and why the token is subject-bound.

Authorization axesThe five axes and the guard that covers each — plus the Hono shared-prefix bleed gotcha.

Integration guide (Liquida)Mint user tokens, sign into a space, and declare the scopes an integration needs.

Image compressionThe async pipeline: 202 → worker → poll the job.

DeploymentBring the whole stack up with Compose, DNS, env alignment, and migrations.

Design decisionsWhat was rejected and why — the reasoning behind the architecture.