No description
  • TypeScript 97.9%
  • CSS 2.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-22 12:00:00 -05:00
sql feat: initial impl 2026-11-22 12:00:00 -05:00
src feat: initial impl 2026-11-22 12:00:00 -05:00
test feat: initial impl 2026-11-22 12:00:00 -05:00
.gitignore chore(git): create .gitignore 2026-11-22 12:00:00 -05:00
bun.lock build(bun): init 2026-11-22 12:00:00 -05:00
bunfig.toml feat: initial impl 2026-11-22 12:00:00 -05:00
LICENSE-APACHE chore(license): initial release 2026-11-22 12:00:00 -05:00
LICENSE-MIT chore(license): initial release 2026-11-22 12:00:00 -05:00
package.json build(bun): init 2026-11-22 12:00:00 -05:00
README.md docs(readme): initial document 2026-11-22 12:00:00 -05:00
tsconfig.json build(bun): init 2026-11-22 12:00:00 -05:00

admin

A self-hosted admin portal for any API with an OpenAPI spec. Built with Elysia and Solid on Bun, stored in SQLite.

License supports Linux supports macOS

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 as s.
  • 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.