Topolo Bytes

Public overview of the media-management and sharing surface built around Cloudflare edge storage and media tooling.

publicverified 2026-07-28mediaassetssharing

What It Is

Topolo Bytes is the media and asset-management surface in the Topolo portfolio. It manages uploads, organization, sharing, and guest-friendly access flows over Cloudflare-backed storage.

Architecture

Bytes combines a browser interface with a worker/API surface and Cloudflare storage primitives such as R2 and KV. It also exposes guest-sharing and media-processing workflows.

Workspace Management

The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces.

Runtime Surfaces

Use /systems/topolo-bytes for the current deployment inventory and service metadata.

API Reference

The contract is currently curated in the docs platform rather than OpenAPI-backed. The active surface centers on asset listing, upload, organization, sharing, and media-processing workflows.

Auth and Permissions

Authenticated operator flows rely on Topolo Auth. Guest collection views are a distinct sharing surface and should be treated separately from operator access. The operator browser session path now uses the shared Topolo cookie-refresh auth client. Browser SSO callbacks delegate Auth /sso/exchange handling to the shared Auth client, so callback URLs carry one-time sso_code values rather than bearer tokens. Callback completion stays inside the SPA so the memory-only access token can hydrate the protected media workspace. Bytes does not expose a legacy /sso?token= browser handoff route. The operator API now requires Topolo Auth validation for bearer tokens and does not retain a Bytes-local JWT secret or development auth bypass path. Bytes resolves its concrete Auth app id at runtime from the canonical topolo-bytes service slug rather than embedding environment-specific app ids in browser or Worker code. Platform-wide Bytes operator access is reserved for Auth users whose role is super_admin in the admin organization.

Data Ownership

Bytes owns asset metadata, folder organization, sharing links, and media-processing state while depending on Cloudflare storage bindings for object persistence.

Mobile Experience

The checked-in mobile experience contract is published in native_capability mode. Its fallback route is /files, its offline policy is read_through_cache, and it requires organization context.

Published permissions: files:read, sharing:read.

  • /files uses /api/list with the record.list template and bytes.files.list data source.
  • /shares uses /api/shares with the record.list template and bytes.shares.list data source.

The native clients consume this manifest as an explicit rendering contract. A web mode record intentionally opens the product web experience; native_capability publishes the listed native routes and actions. Do not infer unlisted native behavior.

Deployments

Bytes deploys as a Cloudflare worker plus browser app pair with storage and sharing bindings.

Failure Modes

  • guest-sharing behavior drifts from operator permission rules
  • storage bindings or sharing namespaces are misconfigured
  • auth assumptions leak into guest-only access paths

Debugging

Start with /systems/topolo-bytes and the worker /health endpoint, then verify whether the issue belongs to storage, guest sharing, auth, or media-processing flows.

Use It

Open Bytes for the human product surface. The system handbook records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact.

Discover the credential-scoped automation surface before making an API call:

topolo services --query topolo-bytes --json
topolo actions --service topolo-bytes --json
topolo actions capabilities --service topolo-bytes --json

Choose an action, inspect it with topolo actions get <action-id> --json, then validate and plan a published example. The Agent Actions reference exposes the same public schemas, effects, examples, verification, and recovery guidance.

Example workflow:

  1. Confirm the active identity and organization with topolo whoami --json.
  2. Discover Bytes and select one published action rather than guessing a route.
  3. Inspect its input/output schemas and published example.
  4. Validate and plan the exact payload; obtain confirmation for a mutation.
  5. Execute and perform every published verification step.

Change Log / Verification

  • Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found.

  • Verified the native_capability mobile experience contract and its 2 published route(s) against apps/TopoloBytes origin/staging cbca40ebd3da on 2026-07-27.

  • Reconciled this page against apps/TopoloBytes origin/staging a5c9472232fa on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract.

  • Removed retired debug media-processing surfaces and enforced privacy-safe structured worker logging at staging commit bed31076 on 2026-07-22.

  • Reconciled workspace verification on 2026-06-28 against apps/TopoloBytes commits through ca61087; reviewed 447 commits since 2026-05-14, including ca61087 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 34606f2 Split Bytes startup root bundle; b4b82fc Adopt canonical Topolo typography; 3bf31d1 Remove Bytes topbar app navigation.

  • Added the Bytes worker public /health endpoint on 2026-04-29 for staging and deployment probes.

  • Removed hard-coded concrete Bytes app ids from the browser and Worker runtime on 2026-05-13; Bytes now resolves app identity through Auth service-slug lookup.

  • Restricted Bytes platform-wide operator recognition to Auth super_admin users in the admin organization on 2026-04-23.

  • Deferred closed Bytes lazy panels and modals on 2026-04-21 so the signed-in media browser reaches a usable workspace without mounting hidden panel loaders during startup.

  • Corrected the Bytes post-callback SPA navigation on 2026-04-20 so successful handoff reaches the media workspace without losing the memory-only Auth token.

  • Removed the remaining Bytes worker-local JWT secret handoff and unused development auth bypass on 2026-04-18

  • Promoted Bytes browser SSO callbacks to Auth /sso/exchange on 2026-04-17 so callback URLs require a one-time sso_code instead of bearer tokens

  • Delegated Bytes browser callback exchange to the shared Auth client on 2026-04-18 and removed the legacy /sso?token= browser route

  • Standardized Topolo Bytes browser auth on the shared Topolo auth client on 2026-03-31

  • Standardized the public product label to Bytes, aligned the frontend launcher/catalog source with Auth-managed metadata, and removed stale CloudControl placeholder frontend targets on 2026-04-04

  • Added canonical Topolo Bytes coverage and retired repo-local media-manager docs on 2026-03-30