- TypeScript 97.9%
- CSS 2.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| sql | ||
| src | ||
| test | ||
| .gitignore | ||
| bun.lock | ||
| bunfig.toml | ||
| LICENSE-APACHE | ||
| LICENSE-MIT | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
admin
A self-hosted admin portal for any API with an OpenAPI spec. Built with Elysia and Solid on Bun, stored in SQLite.
The portal builds its pages in the browser from each API's spec. A collection becomes a table with its query parameters as a filter form, an item becomes a detail view, each write becomes a form built from its request body, and a delete asks to be confirmed. Users sign in through an OpenID Connect (OIDC) provider, and only members of one group are let in. Each API's credentials are kept encrypted on the server and attached to the calls that need them, so they never reach the browser.
Usage
Requires Bun to be installed.
bun install # install dependencies
bun run build # compile executable to ./dist/admin
bun run src/index.ts # run from source instead
The app and its styles are compiled into the executable, so dist/admin is
the whole program.
Commands
As a single binary, admin provides several commands. Run it with -h to see
usage information.
serve: starts the HTTP server, applying the database schema first. This is the default command. Aliased ass.oidc: sets the sign-in provider, reading the client secret from standard input.key: prints a new master key.rekey: re-encrypts every secret from the current master key to a new one, read from standard input.
Settings
There is no configuration file. Each setting comes from a flag, else the environment, else its default.
Table 1. Process settings. A flag wins over the environment, which wins over
the default. ADMIN_KEY wins over a key file.
| Setting | CLI flag | Environment | Default |
|---|---|---|---|
| Bind address | --bind |
ADMIN_BIND |
[::1]:3000, also host:port or unix:/path |
| Public origin | --origin |
ADMIN_ORIGIN |
none: built from each request |
| Data directory | --data |
ADMIN_DATA |
$XDG_DATA_HOME/admin, else ~/.local/share/admin |
| Master key | none | ADMIN_KEY |
none, the key itself in base64 |
| Key file | --key-file |
ADMIN_KEY_FILE |
$XDG_CONFIG_HOME/admin/key, else ~/.config/admin/key |
| Log level | -v and -q, repeatable |
ADMIN_LOG |
info, also debug, warn and error |
| Demo mode | --demo |
ADMIN_DEMO |
off, on when 1 or true |
A bare :port is refused, since the host it implies is every interface. While
sign-in is not set up, any bind beyond loopback is refused, and so is a Unix
socket, since a reverse proxy may forward the public to it. The data directory
holds admin.db.
The public origin is the scheme, host and optional port browsers reach the
portal at, such as https://foo.example.bar. A path, query, fragment or
credentials are refused. Once it is set, the redirect URL and the origin a
request must come from are built from it alone, and cookies are marked Secure
whenever it is HTTPS. Without it, they follow each request's Host header,
and X-Forwarded-Proto from a reverse proxy on this machine.
Log records go to standard error, formatted on a terminal and as JSON lines
otherwise. -v and -q step up and down from the level ADMIN_LOG names.
Master Key
Credentials and the client secret are encrypted with AES-256-GCM under a
master key that never lives in the database. On first run with no key given,
serve creates the key file with a fresh key, readable by its owner alone. A
key file that others may read is refused.
Important
Back the key up apart from the database. Without it, every stored secret is lost, and with both, every secret can be read.
To replace the key, print a new one, re-encrypt under it, then put it where the old one was:
admin key > new.key
admin rekey < new.key
chmod 600 new.key && mv new.key ~/.config/admin/key
rekey reads the current key the same way serve does, and changes nothing
when any secret fails to open under it. A running server holds its data
directory, so rekey refuses to run until the server stops. Start it again
once the new key is in place.
Demo Mode
serve --demo runs a demo of the portal held wholly in memory. Sign-in is
off and every browser is signed in as a demo user, so the setup page is never
shown and the sign-in provider cannot be set. The database and a fresh master
key live in memory alone. Nothing is read from or written to the data
directory or the key file, which are ignored along with ADMIN_KEY, and
everything is gone once the server stops. Every page shows a banner saying
so. Since anyone who reaches a demo may change it, any bind beyond loopback
is refused, and so is a Unix socket.
Sign-In
Users sign in through the authorization code flow with Proof Key for Code
Exchange (PKCE). The ID token's signature is checked against the provider's
published keys, along with its issuer, audience, expiry and nonce, and the user
must be listed in its groups claim as a member of the allowed group. The
portal asks for the openid, profile and groups scopes, where the provider
supports them.
Register the portal at the provider as a confidential client with this redirect URL, using the origin the browser will see:
https://admin.example.com/auth/callback
For a portal reached on this machine alone, that is
http://localhost:3000/auth/callback.
Setup
Sign-in can be set up two ways. The first is the command line, which checks the provider's discovery document before saving anything:
admin oidc --issuer https://sso.example.com --client admin --allow admins
The second is the setup page. While sign-in is not set up and the server listens on loopback, opening the portal in a browser on the same machine shows a form for the same settings. It is never offered to a request that names another host or came through a proxy, so on a remote server, either use the command line or reach the page through a tunnel:
ssh -L 3000:[::1]:3000 server # then open http://localhost:3000
Once set, the provider can be changed from the portal's OpenID Connect page. A new issuer needs its client secret entered again, and any change ends every session.
Sessions
A session lasts twelve hours, and signing out ends it on the server. The session cookie is HttpOnly and SameSite=Lax, and is marked Secure whenever the public origin is HTTPS, the request arrived over HTTPS with no public origin set, or the server listens beyond loopback. Every call to the portal's data or to an API carries a cross-site request forgery token in a header, which the server compares with the one issued at sign-in.
APIs
An API is added with a name, the base URL calls go to, and the URL of its spec. The spec is fetched when the API is added and whenever asked, then kept in the database with the time it was fetched, so the portal keeps working while the API is down. The base URL must be HTTPS, unless its host is this machine, and moving it to another origin clears the API's credentials.
Each security scheme the spec declares holds one credential: an HTTP bearer
token, HTTP basic credentials, or an API key sent in a header, the query or a
cookie. A call gets the credential its operation's security requires, or
else the spec's. OAuth 2.0 and OpenID Connect schemes are shown as
unsupported.
The browser only ever talks to the portal. Calls go through
/proxy/{api}/{path}, which forwards only the paths and methods the spec
declares, attaches the credentials, refuses to follow redirects, and scrubs
any credential an API echoes back in a text answer. A call that gets no usable
answer fails as a gateway would: 504 after 30 seconds, 503 when the API
refuses the connection or answers 503 itself, and 502 for any other failure.
The app shows each as a page of its own, with a button to retry.
Large binary bodies, such as file uploads, are not supported yet, nor are header and cookie parameters.
Deploying
Run admin under a service manager, listening on loopback with the public
origin set, and put Caddy in front of it:
admin --origin https://foo.example.bar
foo.example.bar {
reverse_proxy [::1]:3000
}
Register this redirect URL with the provider:
https://foo.example.bar/auth/callback
The redirect URL comes from the origin whatever host the request names, and
cookies are marked Secure since it is HTTPS. Set up sign-in with admin oidc
before the first start, or open the setup page through a tunnel as above. The
page accepts a form sent from the public origin or from the loopback address
the browser opened.
Without --origin, Caddy passes the original host through and sets
X-Forwarded-Proto, which the portal believes only from a peer on the same
machine, so cookies are marked Secure and the redirect URL matches the
registered one.
A Unix socket works too, as --bind unix:/run/admin/admin.sock with
reverse_proxy unix//run/admin/admin.sock, once Caddy's user may write to the
socket.
Organization
The server lives under src/ beside the app in src/ui/. The spec reader in
src/oas/ is shared by both, so the server matches calls against the same
operations the app builds pages from.
./
├── package.json # project manifest
├── README.md # this document
├── tsconfig.json # compiler options
├── sql/ # schema
│ └── main.sql # data definitions
├── src/ # source files
│ ├── index.ts # entrypoint
│ ├── app/ # application
│ │ ├── cfg.ts # process settings
│ │ ├── cli.ts # argument parsing
│ │ ├── err.ts # failures, exit statuses
│ │ ├── log.ts # logging
│ │ └── tty.ts # terminal input
│ ├── exe/ # subcommands
│ │ ├── key.ts # new key
│ │ ├── oidc.ts # sign-in setup
│ │ ├── rekey.ts # re-encryption
│ │ └── serve.ts # http server
│ ├── oas/ # openapi specs
│ │ ├── auth.ts # security schemes
│ │ ├── doc.ts # documents
│ │ ├── ops.ts # operations, matching
│ │ └── schema.ts # widgets, validation
│ ├── sec/ # secrets
│ │ ├── key.ts # master key
│ │ └── seal.ts # encryption
│ ├── sql/ # database
│ │ └── store.ts # stored state
│ ├── ui/ # browser app
│ │ ├── build.ts # app compiler
│ │ ├── bundle.ts # build macro
│ │ └── main.css # styles
│ └── web/ # http server
│ ├── assets.ts # embedded app
│ ├── auth.ts # sign-in, sessions
│ ├── data.ts # portal data
│ ├── oidc.ts # openid connect
│ └── proxy.ts # api proxy
└── test/ # tests
└── fake/ # fake provider, browser
Tip
The app is compiled by a macro when the server is loaded or built, so there is no separate build step and nothing generated is committed.
Testing
bun test # run every test
bun run check # type-check
Tests point HOME and every XDG directory at scratch, and sign in against a
fake provider of their own on a loopback port. The end-to-end tests run a
local copy of media, and are skipped unless ADMIN_MEDIA_DIR names a checkout
of it with its dependencies installed.
License
This project is dual-licensed under both MIT License and Apache License 2.0. You have permission to use this code under the conditions of either license pursuant to the rights granted by the chosen license.