Merge pull request #356 from diggerhq/preview-url-auth

add preview url auth

Author: breardon2011

cmd/oc/internal/commands/preview.go

@@ -113,6 +113,29 @@ var previewDeleteCmd = &cobra.Command{
 	},
 }
 
+// previewRotateAuthCmd issues a fresh bearer token for the sandbox's
+// edge-enforced preview-URL auth gate. The old token stops working
+// immediately — no dual-token grace period in v1.
+var previewRotateAuthCmd = &cobra.Command{
+	Use:   "rotate-auth <sandbox-id>",
+	Short: "Rotate the sandbox's preview-URL bearer token",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		c := client.FromContext(cmd.Context())
+		var resp struct {
+			PreviewAuthToken string `json:"previewAuthToken"`
+			Scheme           string `json:"scheme"`
+		}
+		if err := c.Post(cmd.Context(), fmt.Sprintf("/sandboxes/%s/preview/rotate", args[0]), nil, &resp); err != nil {
+			return err
+		}
+		printer.Print(resp, func() {
+			fmt.Printf("New preview auth token (shown once): %s\n", resp.PreviewAuthToken)
+		})
+		return nil
+	},
+}
+
 func init() {
 	previewCreateCmd.Flags().Int("port", 0, "Container port to expose (required)")
 	previewCreateCmd.Flags().String("domain", "", "Custom domain")
@@ -121,4 +144,5 @@ func init() {
 	previewCmd.AddCommand(previewCreateCmd)
 	previewCmd.AddCommand(previewListCmd)
 	previewCmd.AddCommand(previewDeleteCmd)
+	previewCmd.AddCommand(previewRotateAuthCmd)
 }

cmd/oc/internal/commands/sandbox.go

@@ -27,6 +27,8 @@ var sandboxCreateCmd = &cobra.Command{
 		envSlice, _ := cmd.Flags().GetStringSlice("env")
 		metaSlice, _ := cmd.Flags().GetStringSlice("metadata")
 		secretStore, _ := cmd.Flags().GetString("secret-store")
+		previewAuth, _ := cmd.Flags().GetBool("preview-auth")
+		previewAuthToken, _ := cmd.Flags().GetString("preview-auth-token")
 
 		config := types.SandboxConfig{
 			Timeout:  timeout,
@@ -55,6 +57,20 @@ var sandboxCreateCmd = &cobra.Command{
 		if secretStore != "" {
 			body["secretStore"] = secretStore
 		}
+		// --preview-auth-token implies --preview-auth. Either flag attaches the
+		// previewAuth block to the create payload; only the token-having flag
+		// supplies a caller-chosen secret. The plaintext is returned exactly
+		// once via the sandbox response's PreviewAuthToken field; print it
+		// prominently so a piped/scripted caller can capture it.
+		if previewAuth || previewAuthToken != "" {
+			pa := map[string]string{"scheme": "bearer"}
+			if previewAuthToken != "" {
+				pa["token"] = previewAuthToken
+			} else {
+				pa["token"] = "auto"
+			}
+			body["previewAuth"] = pa
+		}
 
 		var sandbox types.Sandbox
 		if err := c.Post(cmd.Context(), "/sandboxes", body, &sandbox); err != nil {
@@ -63,6 +79,9 @@ var sandboxCreateCmd = &cobra.Command{
 
 		printer.Print(sandbox, func() {
 			fmt.Printf("Created sandbox %s (status: %s)\n", sandbox.ID, sandbox.Status)
+			if sandbox.PreviewAuthToken != "" {
+				fmt.Printf("Preview auth token (shown once): %s\n", sandbox.PreviewAuthToken)
+			}
 		})
 		return nil
 	},
@@ -274,6 +293,8 @@ func init() {
 		cmd.Flags().StringSlice("env", nil, "Environment variables (KEY=VALUE)")
 		cmd.Flags().StringSlice("metadata", nil, "Metadata (KEY=VALUE)")
 		cmd.Flags().String("secret-store", "", "Secret store name (injects encrypted secrets)")
+		cmd.Flags().Bool("preview-auth", false, "Require a bearer token on the sandbox's preview URLs (server generates a 256-bit token, printed once)")
+		cmd.Flags().String("preview-auth-token", "", "Bring your own preview-URL bearer token (>=16 chars); implies --preview-auth")
 	}
 
 	// sandbox wake flags

docs/api-reference/preview/rotate-auth.mdx

@@ -0,0 +1,31 @@
+---
+title: 'Rotate Preview-URL Auth Token'
+api: 'POST /api/sandboxes/{id}/preview/rotate'
+---
+
+Mint a new bearer token for the sandbox's preview-URL auth gate. The old token stops working immediately — there is no zero-downtime dual-token mode, so roll the new token out to your caller before discarding the old one.
+
+If the sandbox was originally created without [`previewAuth`](/api-reference/sandboxes/create), this call installs a token and starts enforcing the gate from that point on.
+
+The plaintext is returned exactly once in the response. Only the SHA-256 hash is persisted server-side; the server cannot show you the token again later.
+
+<ParamField path="id" type="string" required>
+  Sandbox ID
+</ParamField>
+
+<ResponseExample>
+```json 200
+{
+  "previewAuthToken": "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI",
+  "scheme": "bearer"
+}
+```
+</ResponseExample>
+
+### Errors
+
+| Status | When |
+| --- | --- |
+| `404` | Sandbox not found, or owned by a different org |
+| `410` | Sandbox is `stopped` or `error` |
+| `503` | Database not configured (combined-mode CP without PG) |

docs/api-reference/sandboxes/create.mdx

@@ -45,13 +45,27 @@ If both `cpuCount` and `memoryMB` are provided, they must match a platform tier.
   Name of a pre-built snapshot for instant boot
 </ParamField>
 
+<ParamField body="previewAuth" type="object">
+  Opt in to bearer-token authentication on the sandbox's preview URLs. When set, every request to `https://sb-<id>-p<port>.<domain>` must include an `Authorization: Bearer <token>` (or `X-OC-Preview-Token: <token>`) header; missing or wrong → 401.
+
+  - `scheme` *(string)*: must be `"bearer"`. Reserved for HMAC/JWT later.
+  - `token` *(string)*: `"auto"` (or omitted) → server generates a 256-bit random token. An explicit string of at least 16 characters lets you bring your own.
+
+  The plaintext is returned exactly once in the response as `previewAuthToken`; only its SHA-256 hash is stored. Use [`POST /api/sandboxes/{id}/preview/rotate`](/api-reference/preview/rotate-auth) to mint a new one.
+
+  Omit this field for the legacy open behavior — preview URLs respond to anyone who can reach the hostname.
+</ParamField>
+
 <ResponseExample>
 ```json 201
 {
   "sandboxID": "sb-abc123",
   "status": "running",
   "region": "use2",
-  "workerID": "w-use2-abc123"
+  "workerID": "w-use2-abc123",
+  "previewAuthToken": "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI"
 }
 ```
+
+`previewAuthToken` is only present when `previewAuth` was set in the request. Read it once and store it durably — the server will not return it again.
 </ResponseExample>

docs/cli/preview.mdx

@@ -57,6 +57,37 @@ oc preview delete sb-abc123 3000
 
 Preview URLs persist across hibernation/wake cycles — no need to re-create them.
 
+## Bearer-Token Authentication
+
+By default, anyone who knows the preview hostname can hit your sandbox's port. To require an `Authorization: Bearer <token>` header on every request, opt in at create time:
+
+```bash
+oc sandbox create --preview-auth
+# Created sandbox sb-abc123 (status: running)
+# Preview auth token (shown once): qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI
+```
+
+Then call your preview URL with the token:
+
+```bash
+curl -H "Authorization: Bearer qx2sSi5IYX..." https://sb-abc123-p3000.workers.opencomputer.dev/
+```
+
+Bring your own token if your gateway already has a shared secret:
+
+```bash
+oc sandbox create --preview-auth-token "$GATEWAY_TOKEN"
+```
+
+Rotate the token (old one stops working immediately):
+
+```bash
+oc preview rotate-auth sb-abc123
+# New preview auth token (shown once): <new token>
+```
+
+Token is shown exactly once and only its SHA-256 hash is stored. See [Authentication](/sandboxes/preview-urls#authentication) for the SDK equivalents.
+
 <Tip>
   SDK usage: [Preview URLs](/sandboxes/preview-urls). Full flags: [CLI Reference](/reference/cli#oc-preview).
 </Tip>

docs/docs.json

@@ -303,7 +303,8 @@
             "pages": [
               "api-reference/preview/create",
               "api-reference/preview/list",
-              "api-reference/preview/delete"
+              "api-reference/preview/delete",
+              "api-reference/preview/rotate-auth"
             ]
           },
           {

docs/reference/cli/preview.mdx

@@ -34,3 +34,20 @@ Output columns: `PORT`, `HOSTNAME`, `SSL`, `CREATED`
 ## `oc preview delete <sandbox-id> <port>`
 
 [HTTP API →](/api-reference/preview/delete)
+
+---
+
+## `oc preview rotate-auth <sandbox-id>`
+
+[HTTP API →](/api-reference/preview/rotate-auth)
+
+Mint a new bearer token for the sandbox's preview URLs. The old token stops working immediately. The new plaintext is printed once — capture it before moving on; the server will not return it again.
+
+```bash
+oc preview rotate-auth sb-abc
+# New preview auth token (shown once): qx2sSi5IYX...
+```
+
+Calling this on a sandbox that was created without `--preview-auth` installs a token and starts enforcing the gate from that point on.
+
+See [`oc sandbox create --preview-auth`](/reference/cli/sandbox#oc-sandbox-create) to enable at create time, or [`--preview-auth-token`](/reference/cli/sandbox#oc-sandbox-create) to bring your own.

docs/reference/cli/sandbox.mdx

@@ -29,8 +29,18 @@ Create a new sandbox. **Alias:** `oc create`
   Metadata `KEY=VALUE` (repeatable)
 </ParamField>
 
+<ParamField query="--preview-auth" type="bool">
+  Require a bearer token on the sandbox's preview URLs. The server generates a 256-bit random token and prints it once. See [Preview-URL authentication](/sandboxes/preview-urls#authentication).
+</ParamField>
+
+<ParamField query="--preview-auth-token" type="string">
+  Bring your own preview-URL bearer token (≥16 characters). Implies `--preview-auth`. Useful when your gateway already has a shared secret.
+</ParamField>
+
 ```bash
 oc create --timeout 600 --cpu 2 --memory 1024 --env NODE_ENV=production
+oc create --preview-auth                                    # server-generated token
+oc create --preview-auth-token "$GATEWAY_TOKEN"             # bring your own
 ```
 
 ---

docs/sandboxes/preview-urls.mdx

@@ -23,6 +23,115 @@ console.log(sandbox.getPreviewDomain(3000));
 
 The `domain` and `getPreviewDomain(port)` properties construct the preview hostname directly — no API call needed. Traffic is routed through the control plane proxy to the correct sandbox.
 
+## Authentication
+
+Preview URLs are public by default — anyone who can guess or learn the hostname can hit your sandbox's port. To require a bearer token in front of every request, opt in at create time with `previewAuth`.
+
+When enabled, the control plane validates an `Authorization: Bearer <token>` (or `X-OC-Preview-Token: <token>`) header on every preview-URL request. Missing or wrong → 401. The check happens before traffic ever reaches your sandbox, so a brute-force run also can't wake a hibernated sandbox.
+
+### Enable at create time
+
+<CodeGroup>
+
+```typescript TypeScript
+const sandbox = await Sandbox.create({
+  previewAuth: { scheme: "bearer", token: "auto" },
+});
+
+// previewAuthToken is returned exactly once — store it somewhere durable.
+console.log(sandbox.previewAuthToken);
+// → "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI"
+```
+
+```python Python
+sandbox = await Sandbox.create(
+    preview_auth={"scheme": "bearer", "token": "auto"},
+)
+
+# preview_auth_token is returned exactly once — store it somewhere durable.
+print(sandbox.preview_auth_token)
+# → "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI"
+```
+
+```bash CLI
+oc sandbox create --preview-auth
+# Created sandbox sb-abc123 (status: running)
+# Preview auth token (shown once): qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI
+```
+
+</CodeGroup>
+
+`token: "auto"` (or omitting the field) tells the server to generate a 256-bit random token. To bring your own — useful when your gateway already has a secret it can share with both ends — pass an explicit string of at least 16 characters:
+
+<CodeGroup>
+
+```typescript TypeScript
+await Sandbox.create({
+  previewAuth: { scheme: "bearer", token: process.env.GATEWAY_TOKEN! },
+});
+```
+
+```python Python
+await Sandbox.create(
+    preview_auth={"scheme": "bearer", "token": os.environ["GATEWAY_TOKEN"]},
+)
+```
+
+```bash CLI
+oc sandbox create --preview-auth-token "$GATEWAY_TOKEN"
+```
+
+</CodeGroup>
+
+### Making authenticated requests
+
+Send the token on every request to the preview URL. Two header forms are accepted; pick whichever fits your client:
+
+```bash
+curl -H "Authorization: Bearer $TOKEN" https://sb-abc123-p3000.workers.opencomputer.dev/
+curl -H "X-OC-Preview-Token: $TOKEN"   https://sb-abc123-p3000.workers.opencomputer.dev/
+```
+
+The token gates **every port** on the sandbox — there's one token per sandbox, shared across all preview URLs you create on it.
+
+### Rotation
+
+When you need to roll the token — exposure, scheduled rotation, employee offboarding — call `rotate`. The old token stops working immediately and the new plaintext is returned exactly once:
+
+<CodeGroup>
+
+```typescript TypeScript
+const newToken = await sandbox.rotatePreviewAuthToken();
+// sandbox.previewAuthToken is also updated in place.
+```
+
+```python Python
+new_token = await sandbox.rotate_preview_auth_token()
+# sandbox.preview_auth_token is also updated in place.
+```
+
+```bash CLI
+oc preview rotate-auth sb-abc123
+# New preview auth token (shown once): <new token>
+```
+
+</CodeGroup>
+
+There is no zero-downtime dual-token mode in v1 — roll out the new token to your caller before discarding the old one, or expect a brief window of 401s during the swap.
+
+### What's stored and what's not
+
+- Only the **SHA-256 hash** of the token is persisted. The server never sees the plaintext after the create or rotate response returns.
+- There is no GET endpoint that returns the token. If you lose it, your only options are to rotate (mint a new one) or recreate the sandbox.
+- A sandbox created **without** `previewAuth` has open preview URLs — exactly the same as before this feature existed. The feature is fully opt-in and backwards compatible.
+
+### Where the check happens
+
+Authentication is enforced by the cell's control plane immediately before the request is proxied to the worker. That means:
+
+- **Hibernated sandboxes** stay hibernated on missing/wrong tokens — bad tokens can't burn wake capacity.
+- **Self-hosted deployments** without the Cloudflare edge get the same gate for free — the check follows the sandbox, not the front door.
+
 ## Explicit Preview URLs
 
 For tracking, custom domains, or auth configuration, use the preview URL API:

internal/api/router.go

@@ -442,6 +442,7 @@ func NewServer(mgr sandbox.Manager, ptyMgr *sandbox.PTYManager, apiKey string, o
 	api.POST("/sandboxes/:id/preview", s.createPreviewURL)
 	api.GET("/sandboxes/:id/preview", s.listPreviewURLs)
 	api.DELETE("/sandboxes/:id/preview/:port", s.deletePreviewURL)
+	api.POST("/sandboxes/:id/preview/rotate", s.rotateSandboxPreviewAuth)
 
 	// Data-plane routes: in server mode, proxy to workers; otherwise handle locally
 	if s.sandboxAPIProxy != nil {