bus-gateway
Overview
bus-gateway is the local entry layer for authenticated BusDK browser modules.
It is intended to sit in front of modules such as bus-ledger,
bus-portal, and bus-inspection, own workspace-local login and session
state, and start plus proxy the configured downstream tools for the current
user.
bus-gateway serve starts a token-gated local HTTP server, creates
gateway-owned managed tables and schema files at the workspace root on first
use, prints a one-time bootstrap admin password to stdout, and serves
anonymous plus authenticated session responses over /v1/app,
/v1/session/login, and /v1/session/logout. The same token-gated root page
also supports plain HTML form login/logout, so the shared login screen works
without module-local JavaScript.
The gateway state is intentionally local-first and deterministic. Users,
password hashes, the workspace service catalog, and per-user visible-service
settings live in the selected workspace rather than in a mandatory remote
identity service. The gateway stores that configuration through the shared
bus-data layer, so the same logical tables work on filesystem-backed
workspaces and on workspaces that opt into PostgreSQL storage. The
authenticated UI uses the shared bus-ui sidebar shell: the default launcher
view lists the current user’s tools, while workspace settings, services, users,
and access rows are split into separate views for cleaner administration. The
services page itself stays a navigable catalog list, and each service has its
own dedicated settings route under that section. Each launchable tool is
exposed through a stable gateway route under
/<token>/apps/<service-id>/.
When the gateway proxies a child module request, it also forwards a short-lived
signed trusted-identity envelope for the current account. That lets child
modules such as bus-inspection rely on gateway-owned authentication instead
of running a second login flow.
The workspace can also customize the login-card title and optional helper
copy. When those settings are blank, the page falls back to a generic Sign
in heading and omits helper text entirely.
The repository also ships a ready-to-run Docker Compose example for a
PostgreSQL-backed gateway workspace at
examples/bus-gateway-postgresql/compose.yaml. That stack starts PostgreSQL,
builds the gateway runtime image, initializes an empty workspace descriptor on
the first run, and exposes the gateway on
http://127.0.0.1:8080/gateway-postgres/. The container log prints the
one-time bootstrap admin password in the same
BOOTSTRAP_PASSWORD admin <password> format as a local process run.
Usage
Start the gateway server and print the token-gated URL:
bus-gateway serve --print-url
Or use the default command:
bus-gateway --print-url
On the first run in a workspace, the server prints:
BOOTSTRAP_PASSWORD admin <password>
Use that password with either the login page or the login API. The gateway keeps the credential out of anonymous API payloads after startup.
Service and user configuration
The gateway stores downstream launcher rows, user assignments, and singleton workspace login-page settings in shared managed tables at the workspace root. The main logical rows define:
- a stable service id such as
bus-ledger - a user-facing title
- the downstream command to execute
- how the workspace root is passed to that command
- optional extra launcher arguments
- whether the service is enabled
User settings then define which configured services are visible and launchable for each account. This keeps the service catalog separate from per-user access while still using the same workspace storage backend as the rest of BusDK data.
The CLI exposes the same model for automation. bus-gateway -C ./workspace
service add/get/set/remove ... and service list provide full CRUD-style
control over the workspace service catalog. bus-gateway -C ./workspace user
add/get/set/remove ... and user list do the same for local gateway users,
while bus-gateway -C ./workspace user services set ... replaces the
visible-service list for one account. bus-gateway -C ./workspace settings
get and settings set ... read or update the login title/helper copy for the
workspace.