> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplehost.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How It Works

> Security, reliability, and the publish flow

## Built for trust

SimpleHost is designed with security and reliability at every layer.

<CardGroup cols={2}>
  <Card title="Edge-first" icon="globe">
    Every request is served from the nearest edge location across 300+ cities. No origin servers, no single point of failure.
  </Card>

  <Card title="Encrypted at rest" icon="lock">
    All files are encrypted at rest in storage. SSL/TLS is enforced on every connection.
  </Card>

  <Card title="Presigned uploads" icon="shield-check">
    Files are uploaded directly to secure storage using time-limited, single-use presigned URLs. Upload tokens expire after 1 hour.
  </Card>

  <Card title="Zero egress fees" icon="money-bill">
    Serving your site costs nothing. No bandwidth charges, no surprise bills, no matter how much traffic you get.
  </Card>
</CardGroup>

### Authentication & data protection

* **No passwords stored** — authentication uses one-time email verification codes
* **API keys are hashed** — only the SHA-256 hash is stored, never the raw key
* **Site passwords are hashed** — password-protected sites use server-side hashing
* **Rate limiting** — every endpoint is rate-limited per user and per IP to prevent abuse
* **Claim tokens are single-use** — anonymous site claim tokens cannot be reused

## The Publish Flow

When an agent publishes a directory, three things happen:

### 1. Create

The agent sends a JSON manifest listing every file — path, size, content type, and SHA-256 hash.

```json theme={null}
{
  "files": [
    { "path": "index.html", "size": 1024, "contentType": "text/html", "hash": "a1b2c3..." },
    { "path": "style.css", "size": 512, "contentType": "text/css", "hash": "d4e5f6..." }
  ]
}
```

The API creates a new **version** and returns presigned upload URLs for each file.

### 2. Upload

Each file is uploaded directly to secure storage using the presigned URL. Uploads go straight to storage — no middleman.

Upload URLs expire after **1 hour**.

### 3. Finalize

After all files are uploaded, a finalize call makes the new version live. The API verifies every file exists before activating.

The old version (if updating) is replaced. The new version becomes `active`.

## Site Serving

When someone visits `slug.simplehost.dev`:

1. The request hits the nearest edge location
2. The site's active version is resolved
3. The requested file is fetched from storage
4. It's returned with appropriate caching headers

If the requested path doesn't have an extension, `path/index.html` is tried as a fallback — so SPAs and clean URLs work out of the box.

## Hash Deduplication

When you update a site, files that haven't changed don't need to be re-uploaded:

1. The agent sends file hashes in the manifest
2. The API compares them against the previous version
3. Matching files are copied server-side (instant, zero cost)
4. Only new or changed files need uploading

This makes updates fast — even for large sites, you typically only upload the files you changed.

## Slugs

Every site gets a random slug like `bright-canvas-a7k2`. Slugs are:

* Generated using an `adjective-noun-xxxx` pattern
* Globally unique
* Permanent (even if the site is deleted, the slug is never reused)

## Anonymous vs Authenticated

|                  | Anonymous              | Authenticated |
| ---------------- | ---------------------- | ------------- |
| API key required | No                     | Yes           |
| Site expiry      | 24 hours               | Permanent     |
| Claimable        | Yes (with claim token) | N/A           |
| Rate limit       | 5 req/hour             | 60+ req/hour  |

Anonymous sites receive a `claimToken` in the response. You can claim the site later by providing this token along with an API key, making it permanent.