Heimdall/docs/app-profiles/spotiverse.md

Spotiverse App Profile

RETIRED from the live registry 2026-09-06. This document is the restore spec — it is deliberately kept current, not archived.

Spotiverse was a small daemon exposing the Spotify API to agents. It was lost with the E: drive and has no repository in the swarm. The capability is wanted back — letting a Persona manage the queue during a stream is the motivating case — so this profile was removed in a way that is cheap to undo.

What was removed: the spotiverseProfile object and its registry entry in src/app-profiles.ts, the spotiverse slug from appSlugs in src/contracts.ts, the hardcoded callback arm in src/app.ts, and three spotiverse-specific tests in tests/app.test.ts.

What was deliberately kept: the whole spotify OAuth provider — the catalog entry in src/providers.ts, spotifyRuntime and its token/profile exchange in src/oauth.ts, and "spotify" in the providers union in src/contracts.ts. The provider is intact and unreferenced. Runtime health still reports providers=2/6, which counts it.

Why it was removed anyway: /v1/oauth/spotify/start is gated by admitsProviderForMode(profile, provider, mode), so a provider with no app behind it is unreachable. While the profile existed, that path was publicly reachable and would have run a real OAuth handshake against a real client secret, taking custody of a user's Spotify refresh token on behalf of a consumer that could not use it. Removing the profile closes the path; keeping the provider keeps the capability.

Restoring

Everything below this line is still accurate. To bring Spotiverse back:

1. Re-add spotiverseProfile and its registry entry to src/app-profiles.ts, and "spotiverse" to appSlugs in src/contracts.ts. Both are recoverable verbatim from commit 5a15f71, the last commit before removal.
2. Re-add the backend callback arm in src/app.ts. The daemon ran on http://127.0.0.1:8796/auth/heimdall/callback; that exact URL was the allowlisted value.
3. Configure GC_ACCESS_PROVIDER_SPOTIFY_CLIENT_ID and GC_ACCESS_PROVIDER_SPOTIFY_CLIENT_SECRET_FILE pointing at a credential file. They were removed from /srv/heimdall/env/service.env on retirement, so a fresh Spotify application registration may be needed.
4. Restore the three tests from 5a15f71 if the capabilities they covered (managed-credential resolve for spotify, portal backend callbacks) are not otherwise exercised. At retirement both were covered independently by the streampixels managed-credential tests and the generic untrusted_backend_callback test, so no coverage was lost by removing them.

No provider or protocol work is required. The retirement was a registry change.

---

Spotiverse consumes Heimdall as a managed Spotify credential authority.

Boundary

• Heimdall owns Spotify OAuth, linked identity custody, refresh-token custody, and managed access-token projection.
• Spotiverse owns Spotify playback polling, queue command execution, command receipts, and its CultMesh/Eve provider surface.
• Odin, Eve, VoidBot Faces, and renderers consume the surface and command boundary; they do not receive Spotify tokens.

Providers

• identity providers: spotify
• entitlement sources: none
• managed connection providers: spotify

Capabilities

• spotify_player_read: shared capability after a linked Spotify identity.
• spotify_queue_add: shared capability after a linked Spotify identity; Spotiverse still owns URI validation and command receipts.

Local Configuration

Heimdall needs:

GC_ACCESS_PROVIDER_SPOTIFY_CLIENT_ID=...
GC_ACCESS_PROVIDER_SPOTIFY_CLIENT_SECRET_FILE=/absolute/path/to/spotify-client-secret
GC_ACCESS_APP_SPOTIVERSE_BACKEND_CALLBACK_URLS=https://your-spotiverse-portal.example/auth/heimdall/callback

Spotiverse needs only the Heimdall base URL and local portal callback/return URLs. The callback URL Spotiverse sends in HEIMDALL_CALLBACK_URL must exactly match one URL in Heimdall's GC_ACCESS_APP_SPOTIVERSE_BACKEND_CALLBACK_URLS allowlist unless both services are running on the same local host.