hip-1337

HIP-1337: Space — Sovereign Organization Workspaces, Virtual Drives & File Namespaces. Status Final. Hanzo architectural specification.

HIP-1337: Space — Sovereign Organization Workspaces, Virtual Drives & File Namespaces

Abstract

Package space (/v1/space) establishes a multi-tenant workspace, drive, and file abstraction layered over Hanzo's S-Chain distributed object store (hanzoai/s3). While Hanzo IAM answers "who" (organization, team, user, agent), space answers "where" (namespaces, drives, and file trees).

This proposal specifies the virtual drive model, presigned zero-copy file uploads/downloads, and cardinality management across organizations and team spaces.

Motivation

Direct object storage APIs expose low-level bucket management that conflicts with multi-tenant organization boundaries. Creating a discrete cloud bucket per drive causes high cardinality that severely degrades bucket listing performance and complicates billing attribution. Conversely, flat shared buckets lack organizational boundaries, permission inheritance, and human folder semantics.

space resolves this by decoupling logical drives from physical buckets: one physical bucket exists per (org, space) pair, and drives are represented as key prefixes within that bucket. This preserves sub-millisecond prefix listing, eliminates per-tenant bucket explosion, and enables billing rollups directly to the parent organization.

Specification

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in RFC 2119.

1. Concepts and Hierarchy

• Space: An organization-owned namespace representing a functional domain (e.g. engineering, legal, finance). Billing attaches strictly to the owning organization.
• Drive: A named logical drive within a space. A drive is implemented as the first key segment of an S3 object path (<org>-<space>/<drive>/...).
• Folder: Emergent from / delimiters in object keys. No explicit folders table exists, preventing naming drift upon file renames.
• Bucket Mapping: Exactly one S3 bucket is provisioned per (org, space) pair. Name syntax matches ^a-z0-9?$.

2. Zero-Copy I/O via Presigned URLs

File payloads MUST NOT pass through the API gateway or control plane process:

• Upload: Clients call POST /v1/space/:space/drives/:drive/files to mint an authenticated presigned PUT URL against the public S3 endpoint.
• Download: Clients call GET /v1/space/:space/drives/:drive/files/* to mint an authenticated presigned GET URL.
• Presign TTL: Presigned URLs MUST expire after 5 minutes (presignTTL = 5 * time.Minute). The short TTL serves as the primary capability revocation window.

3. HTTP Endpoints

| Method | Path | Description | |:---|:---|:---| | GET | /v1/space | List all spaces in the authenticated organization | | POST | /v1/space | Create a new space | | GET | /v1/space/:space | Get space metadata and storage stats | | DELETE | /v1/space/:space | Delete a space and purge underlying buckets | | GET | /v1/space/:space/drives | List drives in a space | | POST | /v1/space/:space/drives | Provision a new drive prefix | | GET | /v1/space/:space/drives/:drive/files | List files and folders within a drive prefix | | POST | /v1/space/:space/drives/:drive/files | Request presigned upload URL | | GET | /v1/space/:space/drives/:drive/files/ | Request presigned download URL | | DELETE | /v1/space/:space/drives/:drive/files/ | Delete an object |