# Sandbox SDK 1.0 migration — R2 connectivity report & migration prompt

> Status: **completed**. The SDK 1.0 preview
> (`@cloudflare/sandbox@0.13.0-next.776.1`, PR #306) is merged into `develop`, and
> the release **and** client-docs R2 bridges now run on it: the pinned stable
> reference was uncommented and `Sandbox.outboundByHost` is registered in
> `src/index.ts`. The canonical `static outboundByHost` API is unchanged in the
> preview, so no handler code changed. The R2 S3 credential stays deprecated for
> the container. Validated with the Worker (1528) and client (44) suites and the
> local E2E gateway-boot smoke.

---

## 1. Complete report — what exists and what it uses

### 1.1 The stable API

`@cloudflare/sandbox`'s `Sandbox` extends `Container` from
`@cloudflare/containers`, which declares (stable `0.3.7`):

```ts
type OutboundHandler<E = Cloudflare.Env, P = unknown> = (
  req: Request,
  env: E,
  ctx: { containerId: string; className: string },
) => Promise<Response> | Response;

class Container {
  static get/set outboundByHost: Record<string, OutboundHandler>;
  static get/set outboundHandlers: Record<string, OutboundHandler>;
  static get/set outbound: OutboundHandler; // catch-all
}
```

A sandbox makes a plain HTTP request to a virtual hostname
(`http://<host>/<path>`); the matching `outboundByHost` handler runs **in the
Workers runtime** where `env` bindings (R2, KV, D1, DOs) are available. Handlers
are selected by exact hostname; anything unmatched falls through to the
catch-all `outbound`. This is the canonical API described by
<https://developers.cloudflare.com/sandbox/guides/workers-connections/> and is
**unchanged** in the 1.0 preview.

### 1.2 What was implemented (this feature)

- **`apps/fouria/src/sandbox-r2-bridge.ts`** — `handleReleasesR2Request` maps
  HTTP onto the tenant `BACKUP_BUCKET` under a fixed `releases/` prefix:
  `GET /` (list), `GET/HEAD/PUT/DELETE /<key>`. Keys are sanitized against
  traversal; `PUT` uses `FixedLengthStream` (bounded memory) when
  `content-length` is advertised. Missing binding → `503`.
- **`apps/fouria/src/index.ts`** — registers both bridges:
  ```ts
  Sandbox.outboundByHost = {
    [RELEASES_R2_HOST]: (request, env) => handleReleasesR2Request(request, env),
    [DOCS_R2_HOST]: (request, env, ctx) => handleDocsR2Request(request, env, ctx),
  };
  Sandbox.outbound = async (request) => fetch(request); // catch-all
  ```
- **`apps/fouria/src/sandbox-docs-bridge.ts`** — `handleDocsR2Request` maps
  `http://docs.r2.internal/...` onto `customers/<slug>/docs/` via
  `R2ClientDocsStore` (list/get/head/put/delete). The tenant slug is derived from
  `ctx.containerId` (`customer-<slug>`) and validated with `sanitizeCustomerSlug`.
  `GET/HEAD /<name>`, `PUT /<name>`, `DELETE /<name>`, `GET /` (list); `503`
  without a binding, `400` when the slug cannot be resolved.
- **R2 credentials deprecated for the container** — `gateway/env.ts` no longer
  forwards `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` into the sandbox (they
  remain Worker bindings for the SDK presigned-URL backup path). See
  `apps/fouria/src/gateway/env.test.ts`.
- **Tests** — `apps/fouria/src/sandbox-r2-bridge.test.ts`,
  `apps/fouria/src/sandbox-docs-bridge.test.ts`, `apps/fouria/src/index.test.ts`,
  `apps/fouria/src/gateway/env.test.ts`.
- **Docs** — `apps/fouria/docs/WORKER-DEVELOPMENT.md` §"Sandbox → R2 Connectivity".

Storage layout (in the tenant bucket, which lerma provisions as
`fouria-backup-<slug>` — already tenant-isolated):

```
releases/<key>        e.g. releases/v0.1.0/tarjetero.bundle
```

### 1.3 Current R2 access inventory (migration surface)

| Flow                           | Access path today                                                             | Container sees R2 creds?                    | Migration target                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------- |
| Backups / restore              | SDK `createBackup`/`restoreBackup` presigned URLs + Worker F4E1               | S3 creds injected as `secret_text` bindings | **Keep** — snapshots are purpose-built (COW/FUSE); do not port to `outboundByHost` |
| Client docs (`fouria-docs`)    | `docs.r2.internal` bridge (on-demand) + optional `materializeClientDocsIfDev` | No                                          | **Done (stable)** — migration carries it over and retires materialization          |
| Secrets (`R2SecretsStore`)     | Worker-side F4E1 in `BACKUP_BUCKET`                                           | No                                          | Optional follow-up                                                                 |
| Release bundles (this feature) | `outboundByHost` → `releases/`                                                | No                                          | Done (stable)                                                                      |

### 1.4 Migration constraints to preserve

1. **`outboundByHost` is host-keyed and per-class.** Keep the same virtual host
   (`releases.r2.internal`, and a new `docs.r2.internal` for docs) and the same
   handler signatures.
2. **Unmatched traffic must still passthrough** via the catch-all `outbound`.
   Do not replace it with an allowlist-only handler.
3. **Tenant scoping lives in the handler** (path sanitization + the per-tenant
   bucket binding). Never trust the sandbox-requested path.
4. **Memory-bounded uploads** — keep the `FixedLengthStream` + `content-length`
   pattern for `PUT`.
5. **Backups stay on the SDK presigned path.** Only the docs/release flows move
   to `outboundByHost`.

---

## 2. Ready-to-use prompt — carry the R2 bridges onto SDK 1.0

> Copy the block below verbatim into the Sandbox SDK 1.0 migration agent
> (the agent working [PR #306](https://github.com/0xCAB0/fouria/pull/306)).

```
You are completing the fouria Sandbox SDK 1.0 migration (PR #306,
`feat/sandbox-sdk-1.0`, `@cloudflare/sandbox@0.13.0-next`).

TASK: carry the already-implemented stable-SDK R2 bridges (release +
client-docs) and the R2-credential deprecation onto `@cloudflare/sandbox@next`,
and retire Worker-side docs materialization now that the sandbox fetches docs
on demand.

REFERENCE IMPLEMENTATION (read first, do not break it):
- apps/fouria/src/sandbox-r2-bridge.ts (release bridge: GET/HEAD/PUT/DELETE +
  `GET /` list, path sanitization, FixedLengthStream uploads, 503 when unbound)
- apps/fouria/src/sandbox-docs-bridge.ts (client-docs bridge: list/get/head/put/
  delete over R2ClientDocsStore, slug derived from ctx.containerId)
- apps/fouria/src/index.ts (Sandbox.outboundByHost registration + catch-all
  Sandbox.outbound passthrough)
- apps/fouria/src/sandbox-r2-bridge.test.ts, sandbox-docs-bridge.test.ts,
  index.test.ts, gateway/env.test.ts
- apps/fouria/src/gateway/env.ts (R2 S3 credential NOT forwarded to container)
- apps/fouria/docs/WORKER-DEVELOPMENT.md §"Sandbox → R2 Connectivity"
- docs/plans/sandbox-sdk-1.0-r2-migration.md (this report)

CONTEXT — current docs flow:
- apps/fouria/src/services/fouria-docs/R2ClientDocsStore.ts stores docs at
  `customers/<slug>/docs/<path>` in the tenant BACKUP_BUCKET (plaintext).
- apps/fouria/src/services/fouria-docs/materialize.ts
  (materializeClientDocsIfDev) currently READS R2 in the Worker and WRITES the
  files into `/home/openclaw/clawd/client-docs/` via sandbox.writeFile/exec.
- The dev-only admin API is /api/admin/fouria-docs (routes/api/fouria-docs.ts).

REQUIRED WORK:
1. Confirm `static outboundByHost` is unchanged in `@cloudflare/sandbox@next`
   (0.13.0-next) and that the reference bridge still compiles/behaves. If the
   API changed, record the exact diff in this file and adapt.
2. Carry over the `docs.r2.internal` handler from
   `apps/fouria/src/sandbox-docs-bridge.ts` and the release bridge from
   `sandbox-r2-bridge.ts`; verify both compile/behave under `@next`.
3. Confirm the tenant-slug derivation (`ctx.containerId` -> `customer-<slug>`)
   is unchanged in `@next`; keep the cross-tenant isolation tests.
4. Retire Worker-side `materializeClientDocsIfDev` (or keep it behind a flag):
   the sandbox fetches docs on demand via `docs.r2.internal`. Update the Fouria
   Builder workspace persona/docs paths. Do NOT remove the admin API write path.
5. Preserve security posture: keep the R2 S3 credential out of the container env
   (deprecated in `gateway/env.ts`), traversal sanitization, bounded-memory
   uploads, catch-all passthrough intact.
6. Tests: keep the bridge unit tests green (mock R2 bucket: list/get/put/delete,
   traversal rejection, 503) and the index.test.ts host-registration assertions.
   Keep coverage ≥ 80%.
7. Docs: update apps/fouria/docs/WORKER-DEVELOPMENT.md, docs/ENV-VARIABLES.md
   and this report's status. Run
   `bun run format:check && bun run lint && bun run typecheck && bun run test`
   plus `cctr apps/fouria/test/business-rules/`.

DO NOT MIGRATE:
- Backups/restore (keep the SDK `createBackup`/`restoreBackup` presigned path).
- Anything that would place R2 credentials inside the container.

ACCEPTANCE:
- Both bridges registered; sandbox reads/writes docs and release bundles with no
  credentials; container env carries no R2 credentials; release + docs bridges
  green; full test suite green; docs updated.
- Report back with: the `@cloudflare/sandbox@next` version, any API diff vs the
  stable reference, files changed, and test output.
```

---

## 3. Issue linkage

Track this hand-off in **[issue #309](https://github.com/0xCAB0/fouria/issues/309)**,
which links the SDK 1.0 migration
[PR #306](https://github.com/0xCAB0/fouria/pull/306) to the stable
`outboundByHost` implementation added here.
