Download desktop installer

Outcome

Download one public object under desktop/releases. Raw HTTP returns attachment bytes; SDK, CLI and MCP transport return a base64 binary envelope.

Before you start

• This handler is public. Discover the exact catalog action and its input before use; no workspace membership is granted by a public release or share URL.
• A public sharing route remains confined to the supplied share and file; release downloads remain confined to desktop/releases.

Discover the target

topolo whoami --json
topolo actions get app_topolo_bytes.desktop.download --detail --json

Request

GET /api/desktop/download

Save action input as payload.json. The reviewed plan separates path identifiers, query fields and the HTTP body.

Inspect and test this action in the signed action console. A test response still requires the verification below.

Input fields

Exact input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false
}

Effects

• Reads a public release object; keys outside desktop/releases are refused.

Interpret the response

This response does not return a guaranteed canonical target identifier. Keep the discovered request context and interpret its documented values without inventing a resource id.

Check contentType and contentLength, decode contentBase64 to bytes and verify the chosen release artifact. An HTTP 404 text body is an error, not a binary installer.

The schema describes supported success fields; optional metadata and integration-dependent values may vary. Errors have the exact shapes shown in refused examples. Raw HTTP returns installer bytes with attachment headers; SDK, CLI and MCP use the binary envelope below.

Success schema:

{
  "type": "object",
  "required": [
    "contentType",
    "contentLength",
    "contentBase64"
  ],
  "properties": {
    "contentType": {
      "type": "string"
    },
    "contentLength": {
      "type": "integer",
      "minimum": 0
    },
    "contentBase64": {
      "type": "string"
    }
  },
  "description": "SDK, CLI and MCP binary envelope. Raw HTTP serves installer bytes with Content-Disposition."
}

Worked examples

Actual exported Worker handlers with local Miniflare R2/KV. Auth, workspace grants, R2 multipart, notification, usage and semantic integrations are simulated at their configured test boundaries. Synthetic ids, timestamps and signed URLs confer no live access. No deployed provider outcome, external delivery or live grant is established. Upload-session credential values are explicitly redacted; binary responses use the tested SDK transport envelope. Replace synthetic identifiers through credential-scoped discovery. Refused scenarios document failure boundaries; they are not successful workflows.

Successful request

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured. The binary body is represented through the SDK transport envelope, verified by the transport regression test.

Input · payload.json:

{
  "key": "desktop/releases/Bytes-3.0.0.dmg"
}

CLI:

topolo actions validate app_topolo_bytes.desktop.download --data @payload.json --json
topolo actions plan app_topolo_bytes.desktop.download --data @payload.json --json
topolo actions call app_topolo_bytes.desktop.download --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_bytes.desktop.download",
    "input": {
      "key": "desktop/releases/Bytes-3.0.0.dmg"
    }
  }
}

Captured binary represented by SDK transport · HTTP 200:

{
  "contentType": "application/x-apple-diskimage",
  "contentLength": 12,
  "contentBase64": "YmluYXJ5LWJ5dGVz"
}

HTTP 200. Check contentType and contentLength, decode contentBase64 to bytes and verify the chosen release artifact. An HTTP 404 text body is an error, not a binary installer.

Another supported request

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured. The binary body is represented through the SDK transport envelope, verified by the transport regression test.

Input · payload.json:

{
  "key": "desktop/releases/Bytes-2.0.0.dmg"
}

CLI:

topolo actions validate app_topolo_bytes.desktop.download --data @payload.json --json
topolo actions plan app_topolo_bytes.desktop.download --data @payload.json --json
topolo actions call app_topolo_bytes.desktop.download --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_bytes.desktop.download",
    "input": {
      "key": "desktop/releases/Bytes-2.0.0.dmg"
    }
  }
}

Captured binary represented by SDK transport · HTTP 200:

{
  "contentType": "application/x-apple-diskimage",
  "contentLength": 12,
  "contentBase64": "YmluYXJ5LWJ5dGVz"
}

HTTP 200. Check contentType and contentLength, decode contentBase64 to bytes and verify the chosen release artifact. An HTTP 404 text body is an error, not a binary installer.

Refused request · HTTP 404

Actual worker response with local Miniflare R2/KV and simulated Auth, workspace grants and outbound integration boundaries. No authorization header is captured.

Input · payload.json:

{
  "key": "acme/secret.txt"
}

CLI:

topolo actions validate app_topolo_bytes.desktop.download --data @payload.json --json
topolo actions plan app_topolo_bytes.desktop.download --data @payload.json --json

Captured local response · HTTP 404:

Not found

HTTP 404. This request was refused; preserve the exact response and correct its cause before retrying.

Verify the result

• Check contentType and contentLength, decode contentBase64 to bytes and verify the chosen release artifact. An HTTP 404 text body is an error, not a binary installer.

Errors and recovery

• Not found (HTTP 404): Discover the existing file, share or release in the intended scope. A missing or inaccessible target is not authorization to create a replacement.

Authentication, the action-input validator or resource middleware can refuse a request before this handler. Preserve the exact request id, error and selected credential context. The fixtures establish no live credentials or configured provider.

Recovery boundary

No service state changes.

Related actions

• Get latest desktop release: Read the newest published desktop installer metadata from the shared desktop/releases prefix; a missing release answers 404.

Evidence

Actual exported Worker handlers with local Miniflare R2/KV. Auth, workspace grants, R2 multipart, notification, usage and semantic integrations are simulated at their configured test boundaries. Synthetic ids, timestamps and signed URLs confer no live access. No deployed provider outcome, external delivery or live grant is established. Upload-session credential values are explicitly redacted; binary responses use the tested SDK transport envelope. Capture digests and test scenarios are retained in the source fixture records.