---
hip: 1192
title: Space — Drives Folders and File Storage
author: Hanzo AI
type: Standards Track
category: Infrastructure
capability: space
status: Final
implementation-go: shipped
created: 2026-09-10
requires: HIP-0026, HIP-0106, HIP-0139
---

# HIP-1192: Space — Drives Folders and File Storage

## Abstract

`/v1/space` is the canonical capability for space within the Hanzo Cloud platform.
Package space is where work lives: drives, folders and the files in them.
The implementation is `hanzoai/cloud` `apps/space` and `plugin/space` (HIP-0106, HIP-0139).
All operations are native, composable, and authenticated against Hanzo IAM (HIP-0026).

## Motivation

Before this specification, space operations lacked a unified canonical surface or were scattered
across disparate endpoints. Under HIP-0139 (§1), every cloud capability maps 1:1 with exactly
one plugin binary, one address prefix, one client class, and one authoritative specification.
This eliminates duplicate implementations and ensures strict physical isolation, predictable billing,
and orthogonal composability across the estate.

## Specification

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

### §1 Addresses and Operations

The `space` capability answers exclusively under its assigned route prefixes:

| Method | Path | Summary |
|---|---|---|
| `GET` | `/v1/space/health` | Health reports whether this deployment can serve spaces, drives and files. |
| `GET` | `/v1/space/spaces` | Lists the caller org's own spaces. |
| `POST` | `/v1/space/spaces` | Makes a new space for the caller's org and answers 201 with it. |
| `GET` | `/v1/space/{space}/drives` | Lists a space's drives. |
| `POST` | `/v1/space/{space}/drives` | Makes a new drive in a space and answers 201 with it. |
| `DELETE` | `/v1/space/{space}/drives/{drive}` | Removes an EMPTY drive and answers 204. |
| `GET` | `/v1/space/{space}/drives/{drive}/files` | Lists one folder level of a drive. |
| `GET` | `/v1/space/{space}/drives/{drive}/files/{wildcard1}` | Mints a URL the caller downloads the file from DIRECTLY. |
| `PUT` | `/v1/space/{space}/drives/{drive}/files/{wildcard1}` | Mints a URL the caller uploads the file to DIRECTLY. |
| `DELETE` | `/v1/space/{space}/drives/{drive}/files/{wildcard1}` | Removes one file and answers 204. |

### §2 Storage and Physical Isolation

Data is isolated physically per organization using `cloud.OrgDB`:
`{DataDir}/orgs/{org}/space.db`. Isolation is strictly enforced at the filesystem and OS level;
no cross-tenant queries are permitted. Where temporal or timeseries data is captured, postings
are signed and immutably appended.

### §3 Authentication and Principal

Every request reaching `/v1/space` MUST present a valid Hanzo IAM bearer token (HIP-0026, HIP-0111).
Anonymous requests are rejected at the edge gateway before invoking the plugin. The executing
principal is extracted from the token and bound to the request context.

## Security Considerations

1. **Physical Separation**: Each tenant retains an isolated SQLite database file.
2. **Replay & Channel Binding**: Direct dials and internal RPCs enforce channel binding over ZAP native transport.
3. **Audit Trails**: All state-modifying actions emit immutable audit events to the centralized event plane (HIP-1190).

## References

- HIP-0026: Identity & Access Management Standard
- HIP-0106: Hanzo Plugin Contract
- HIP-0139: Capability Standard