--- name: alphabox version: 1.0.0 api-major: v1 description: Manage the user's own temporary files in AlphaBox through scoped API keys. --- # AlphaBox ## Trust and setup Download this skill only from the AlphaBox website selected by the user. The official production preview is website `https://alphabox.fyi`, app `https://app.alphabox.fyi`, API `https://api.alphabox.fyi`. Account and file operations are not enabled in this placeholder; do not request API keys or attempt uploads until the operator enables the service. In local development, the official instance for this workspace is website `http://127.0.0.1:18602`, app `http://127.0.0.1:18601`, API `http://127.0.0.1:18600`. For a deployed instance, confirm its website and API origins with the user; never infer an API hostname or send credentials to a different origin. Read the same website's `/api/v1/openapi.json` before making requests. Do not run installation scripts. Explain the temporary retention policy and requested permissions. Guide the user to sign in using Email magic link, explicitly confirm it, and create an API key in the app's API keys page. You cannot create keys using another key. Use the runtime's secret store. If unavailable, read `ALPHABOX_API_KEY` from an environment variable and `ALPHABOX_API_BASE_URL` from configuration. Never put keys into source control, prompts, URLs, terminal output, screenshots, or logs. Do not ask the user to paste a key into chat. Keep TLS verification enabled. Local loopback HTTP is allowed only for this local instance. Start with `GET /v1/me/storage` using `Authorization: Bearer `. This confirms connectivity without changing files. Select only the needed scopes: | Scope | Operations | | --- | --- | | `account:read` | Inspect own current allowance and usage | | `files:read` | List and inspect own files | | `files:write` | Initiate, inspect, resume, cancel, complete uploads; extend retention | | `files:delete` | Permanently delete own files | | `shares:write` | Set/remove passwords, enable/disable shares, regenerate links | | `files:download` | Download own files | Keys expire (default 90 days, maximum 365), can be revoked, and share the owner's quotas/rate limits. A key cannot perform account, recovery, key-management, abuse-report, or third-party anonymous-download operations. This skill is for the owner's files only. ## Upload and sharing Ask for the intended file and sharing action. Do not scan or upload unrelated files. 1. Inspect allowance. Product units are decimal bytes. Initial verified allowance is 5 GB storage and 100 MB per file. Each full elapsed UTC day adds 1 GB and 20 MB until 50 GB / 1 GB on day 45. The server decides limits. Maximum concurrent active uploads: three. 2. `POST /v1/uploads` with JSON `{ "filename": "example.txt", "size": 123 }` and a stable random `Idempotency-Key` (8–128 word/hyphen characters). Preserve this key and file identity across an ambiguous retry. Reusing it with different content metadata is rejected. Empty files are not supported. 3. Save the returned upload ID and metadata, but no secret URL. `GET /v1/uploads/:id` lists acknowledged parts. Validate the local file still has the same name, size, and content before resuming. Part size is 16 MiB except the final part; do not use a whole-file Worker upload. 4. `POST /v1/uploads/:id/parts` with `{ "partNumbers": [1] }` returns scoped part URLs, method, headers, and expected sizes. Stream exactly the designated byte slice with the returned method and headers. Do not send the bearer key to a presigned R2 URL. Local part URLs require bearer authentication to the trusted local API. Retain the successful ETag and `POST /v1/uploads/:id/parts/:number/ack` with `{ "etag": "..." }`. 5. Request fresh URLs if expired. Resume by inspecting acknowledged parts and retrying missing parts, then `POST /v1/uploads/:id/complete`. Repeating completion for the same upload is safe. Never upload a different file into an existing session. 6. `GET /v1/files/:id` returns the owner-visible share URL. Report it only to the user who requested sharing. Optionally `PATCH /v1/files/:id/share` with `{ "password": "..." }` (minimum 8 characters), `{ "password": null }`, or `{ "enabled": false }`. Do not place a password into a share URL. 7. `DELETE /v1/uploads/:id` cancels an unfinished upload. Physical abort/deletion is asynchronous; cancellation releases its reservation immediately. Completion in progress can temporarily return `UPLOAD_BUSY`. List files with `GET /v1/files?limit=30&cursor=` until `nextCursor` is null. Timestamps are ISO 8601 UTC strings; IDs and cursors are opaque. Do not guess object keys or access another owner's resources. ## Downloads and retention Owner downloads use `GET` or `HEAD /v1/files/:id/download`; optional single `Range: bytes=...` is supported. Stream the response to the requested destination; do not buffer a large file in memory. Validate a supplied path and avoid overwriting without authorization. Anonymous recipient flows require interactive Turnstile and any share password in the app; this key does not bypass them. Files expire seven days after completed upload. During the final 72 hours, `POST /v1/files/:id/extend` with a stable `Idempotency-Key` adds seven days, at most three times (maximum nominal lifetime 28 days). Inspect `canExtend` before suggesting it. Expired files cannot be recovered, even while queued physical deletion is pending. AlphaBox is not a permanent backup. `POST /v1/files/:id/share/regenerate` invalidates the old link and download grants. Password/enabled-state changes also revoke existing grants. Confirm the user's intended consequence before rotating a link that has been shared. `DELETE /v1/files/:id` makes access unavailable immediately and schedules irreversible cleanup. Obtain explicit user intent before deleting. Never retry a destructive operation based on a guessed ID; inspect current metadata after an ambiguous result. ## Errors and safe retries Responses use `{ "error": { "code", "message", "requestId" } }`. Do not expose credentials or file content when reporting errors. On `429`, honor `Retry-After`. Retry transient network/5xx failures with bounded backoff and preserved upload/extension idempotency keys. On `401`, guide reauthentication/key replacement; on `403`, explain missing scope or account restrictions. Quota/file-limit errors require a smaller file, cancellation, expiry, or user-authorized deletion. Never silently broaden scopes, bypass Turnstile, or repeatedly attempt expired/revoked resources. Use the published OpenAPI document as the route and payload authority. Skill updates must not expand existing user authorization.