hiveops-guide/backend/src/main/resources/content/fleet/artifacts/claude.md at f21c783d8c86c4417233071e4378169bc4042f7a

Files

T

johannes f21c783d8c fix(guide): gate Architect + Claude tabs to BCOS_ADMIN only (#16 )

The 162 Architect/Claude docs were tagged 'audience: dev'. The 'dev' tier
resolves to isInternal() = ROLE_MSP_ADMIN || ROLE_BCOS_ADMIN, so every
MSP_ADMIN could read full internal architecture: source paths, DB tables,
service ports, NGINX routes. Verified live on bcos.dev as msp_a@msp1.bcos.dev.

Retag them to 'audience: bcos' (isBcos, BCOS_ADMIN only). Content-only change;
the 'dev' tier mapping is deliberately left alone so the 15 Internal, 35
Overview and 66 Testing docs stay MSP-visible.

Also add platform.guide-access documenting the audience tiers and the
per-role visibility matrix, so the access model is queryable from the Guide
instead of re-derived from source each time.

Verified: MSP module count unchanged (116 across 17 apps); no module loses
all its tabs. Guide is bcos.dev only, not deployed to production.

Closes #16

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-14 17:55:07 -04:00

4.0 KiB

Raw Blame History

module, title, tab, order, audience

module	title	tab	order	audience
fleet.artifacts	Artifact Import Guide	Claude	40	bcos

Act-without-guessing cheat-sheet. Owner service: hiveops-fleet (com.hiveops.fleet, port 8097, DB hiveiq_fleet). Never write artifact data anywhere else.

Ownership

Table fleet_artifacts (DB hiveiq_fleet) is the ONLY store for artifacts. Column cdn_url added in V7__add_artifact_cdn_url.sql.
Component: frontend/src/components/FleetManagement/FleetArtifacts.svelte.
Service: FleetArtifactService. User REST: FleetApiController. Agent REST: InternalFleetController.

Endpoints (METHOD path → roles)

METHOD path	Roles
GET `/api/fleet/artifacts` (opt `?type=<ArtifactType>`)	USER,CUSTOMER,ADMIN,MSP_ADMIN,BCOS_ADMIN
GET `/api/fleet/artifacts/{id}`	same read roles
POST `/api/fleet/artifacts` (multipart)	ADMIN,MSP_ADMIN,BCOS_ADMIN
GET `/api/fleet/cdn-manifest/{type}`	MSP_ADMIN,BCOS_ADMIN
POST `/api/fleet/artifacts/import-cdn` (JSON)	ADMIN,MSP_ADMIN,BCOS_ADMIN
POST `/api/fleet/artifacts/{id}/toggle-enabled`	ADMIN,MSP_ADMIN,BCOS_ADMIN
DELETE `/api/fleet/artifacts/{id}`	ADMIN,MSP_ADMIN,BCOS_ADMIN
GET `/api/internal/fleet/tasks/{taskId}/download?offset=N`	ROLE_INTERNAL (`X-Internal-Secret`)

Base URL: https://api.bcos.cloud/fleet (prod) / https://api.bcos.dev/fleet (dev). Frontend fleetAPI prefixes /api/fleet.

Request shapes

multipart POST /artifacts params: file, name, version, artifactType, description?, institutionKey?.
import-cdn POST /artifacts/import-cdn JSON body: { "cdnUrl", "name", "version", "artifactType", "description"?, "institutionKey"? }.

`ArtifactType` (exact enum values)

UPDATE_AGENT · UPDATE_HOTFIX · UPDATE_SOFTWARE · UPDATE_MODULE · SCRIPT (UI labels: Agent Patch / Hotfix / Software Update / Module Update / Script — labels are NOT the stored values.)

CDN manifest types (path `{type}`)

Only agent, hotfix, software are valid server-side → resolve to https://cdn.bcos.cloud/downloads/{type}/latest.json. Any other {type} (e.g. modules) ⇒ 400 Unknown manifest type.

Topics

Artifact import emits NO Kafka event (synchronous DB write only).
Fleet's task topic is hiveops.fleet.task.events (tasks, not artifacts).
device_summary is synced from hiveops.device.events (read-only mirror; do not write it here).

Env / config

CDN_TOKEN → cdn.token → sent as X-CDN-Token.
FLEET_UPLOAD_DIR → fleet.artifact.upload.dir (default /app/uploads/fleet).
Multipart cap 100MB. INTERNAL_SECRET, JWT_SECRET, DB_URL standard.

Gotchas

CDN import does HEAD only — file is NOT stored in fleet. Row has cdn_url, no sha256_hash, no storage_path. Agent downloads from CDN directly (artifactCdnUrl in tasks/next).
Uploads (multipart) DO store storage_path + sha256_hash; agent downloads chunked via internal endpoint.
readChunk on a CDN-only artifact throws 410 GONE — CDN artifacts must be pulled from cdnUrl, never fleet's chunk endpoint.
Delete blocked (409 CONFLICT) while any PENDING/QUEUED/RUNNING task references the artifact.
institution_key null ⇒ Global (all institutions); set ⇒ scoped; max length 10.
enabled defaults true; toggled via /toggle-enabled.
CDN download bypasses fleet, so task download_offset staying 0 is NORMAL, not a stall.

Do NOT

❌ Write artifact rows to any DB other than hiveiq_fleet.fleet_artifacts.
❌ Add an artifact endpoint on incident / devices / mgmt — fleet owns artifacts.
❌ Use UI labels ("Agent Patch") as artifactType — send the enum value (UPDATE_AGENT).
❌ Call /cdn-manifest/modules — unsupported, 400.
❌ Expect a SHA-256 on CDN-imported artifacts — there isn't one.
❌ Point an agent at /tasks/{id}/download for a CDN artifact — expect 410.
❌ Fetch manifests without X-CDN-Token in a token-gated environment — expect 401/403.

4.0 KiB Raw Blame History