WBSP
ProvidersWikiSign in
All pages

The WBSP Platform Model

This document states the settled model of the platform as principles — who authenticates where, what a subscriber is, what must keep working when wbsp.ai is unreachable, and where the authoritative record of installations lives. It exists so the next platform (an appliance, a third-party cluster) is built against principles rather than folklore. The component-level architecture (adaptors, provisioning, request flow) is architecture.md; this page is about what must remain true, not how the machinery is built.

The governing principles, settled 2026-08-10 and not up for casual relitigation: declarations are universal, values are local; wbsp.ai is required to acquire, never to operate; one writer per installation, fixed at creation, no transitions; mutual distrust by default; applications read environment variables only.

The three identity planes, and the subscriber

Three kinds of people authenticate, in three different places, and the planes never blur:

  1. The platform owner (operator) authenticates to the platform's own surfaces — the CLI (wbsp login), the API, the platform's config UI — through the platform's local identity provider. Operators administer the platform; their authority is platform-wide.
  2. The subscriber is the acquiring party: the person or organisation that agrees to pay for what a platform hosts. A subscriber authenticates in two places, because two authorities answer two different questions (issuers corrected 2026-08-11 — see the portal's ask): to wbsp.ai to browse the catalog and acquire the right to run an application — the PTA (permission to access: the licence to run, and the image pull credential); and to their platform's subscriber portal (the wbsp-subscribers project or a fork of it), which agrees to host and to bill, and mints the RTH (request to host). Grants attach to the subscriber, not to a machine or a tenant: the PTA to the subscriber's acquisition, the RTH to the subscriber's subscription on the issuing platform — revoking either bites every installation that leans on it. (Transitional: the website still mints the RTH for the main platform until that platform runs its own portal instance.)
  3. Tenant users (app users) authenticate to the applications through the platform's local identity provider at its tenant-scoped issuer. They never hold platform authority and never touch wbsp.ai.

The website knows who may acquire what. The platform knows what is running where. The identity provider knows who a person is. No component substitutes for another.

The object model

platform
└── subscription            (the subscriber's relationship to this platform)
    └── tenant(s)           (isolation domains on the platform)
        └── installations   (tenant + application + destination — the unit
        │                    everything keys on)
        └── app users       (people who sign in to the applications)
  • An installation is the unit of configuration, custody, and mode: it carries its values (with secret markers), its one writer (fixed at creation), its retained image and pull credential, its enclave placement, and its registered sign-in client. Everything the platform knows about a running application hangs off this record.
  • Tenant admins are nominated at tenant creation, pre-created by email. The alternative — the first person to log in claims the admin role — was rejected as a race: whoever wins the race owns the tenant.
  • Break-glass is a role grant/revoke, audit-logged, and nothing else. There is no super-path that bypasses the model; an emergency is an ordinary, recorded change of authority that is reverted the same way.

Acquire versus operate

wbsp.ai is required to ACQUIRE, never to OPERATE. The website is where rights are obtained — the catalog, the grants, the subscriber's ledger. Once acquired, a platform must run, configure, redeploy, and sign users into its applications with wbsp.ai unreachable.

The invariant has two non-optional consequences:

  1. A local image mirror. What a platform runs, it holds. An image the platform can only fetch from a remote registry at the moment of need is an operate-time dependency on the acquire-time authority.
  2. Offline-verifiable grants. A grant must verify against a trust anchor the platform holds (public keys), not by phoning home. Revocation propagates when the platform next touches the acquire-time surface (an image re-pull re-presents the token and the gateway re-decides) — but the verification of what the platform already holds never requires wbsp.ai to answer.

Everything else follows this shape: the config UI is served by the platform itself; completeness is evaluated by the platform from its own store; the pull credential is retained on the installation so a platform-initiated redeploy (a node replacement, a settings change) re-presents it unattended. Retention never outlives revocation: a revoked credential fails the next image access exactly as a hand-carried one would.

Configuration: declarations are universal, values are local

An image declares what it needs (names, prompts, groups, types, required markers, who supplies each — published in the image's run manifest). The declarations travel with the image to every platform. The values live only in the platform that runs the installation — one record per installation, secret-marked, one writer. The website may show declarations and completeness status; it never renders a form, stores a value, or proxies one — masked included.

Every installation has exactly one writer, fixed at creation: either the developer's deploy maintains its configuration (deploy-managed) or the operator's config surfaces do (operator-managed). There are no transitions; changing one's mind is delete-and-recreate, deliberately.

The platform supplies what only it can mint: the per-installation sign-in client in its local identity provider, the tenant-scoped issuer, the application URL, and declared pure-entropy values (minted once, stable ever after). An operator types only what genuinely only a person has.

Enclaves: mutual distrust by default

An enclave is the platform's isolation boundary for the private in-cluster surface. The defaults, settled by feature 089:

  • Every installation gets its own enclave by default, created with it and gone with it, shared by the application's own components and nothing else. Catalog applications are written by strangers to each other; co-locating them silently is the vulnerability.
  • Co-location is an explicit act: a shared enclave is tenant-scoped, registered by name, and joined by reference. An unregistered name refuses at install — no silent creation of an island.
  • Public routes remain public. Enclave isolation governs only the private in-cluster surface; reaching an application's public URL is a routing concern, not an enclave concern.
  • Installations placed before these defaults keep their placement — the default binds new installations only, and a recorded placement never moves on redeploy.

The one-record principle

Every deploy path writes through one authoritative installation record per platform. Whatever creates, changes, or removes a running application — the repository deploy, deploy-from-image, a backdoor operator command, a future path — must read and write the same record of what exists.

The rationale is an incident, not a preference. On 2026-08-11, a tenant's shared Redis was torn down under a live application because one deploy path's records could not see a sibling created through another path — each process consulted only its own registry, and "no other app uses this" was true in one ledger and false in the cluster. The immediate fixes made the teardown trust the cluster-side state; the principle generalises them: derived views (a process's registry, a cache, a state file) may accelerate decisions, but the authoritative record — and the cluster state it describes — decides.

Feature 089 applies the principle to placements (an installation's enclave is recorded on the installation and adopted from the live cluster for pre-089 deployments), custody (the retained image and credential live on the installation record), and identity (the registered client id is recorded on the installation, not remembered by a process). Retrofitting every legacy deploy path onto one record is tracked as future work; new paths are built this way from the start.

What this means for the next platform builder

Build to these tests:

  • A person can be pointed at each of the three planes and told exactly where they authenticate and what their authority covers.
  • With wbsp.ai unreachable: existing applications serve, operators configure through the platform's own UI, redeploys succeed on retained credentials, and app users sign in. Only acquiring something new waits.
  • Two applications installed with defaults cannot reach each other's private services; their public routes both serve.
  • The answer to "what is installed here, who configures it, where does it run, what does it hold" is one record, whichever path created it.