fauth — forge-auth CLI

fauth is the forge-auth member of the federation CLI family, alongside fgit (forge-git), forge (forge-control) and packr-cli. It signs in with forge-auth's device flow and tells you who you are, so you no longer need to read the production database to find your own user id.

fauth login                                # device flow for app "fauth": open the URL, enter the code
fauth whoami                               # user id, email, name, org memberships
fauth whoami --json
fauth orgs list | show <idOrSlug> | members <idOrSlug>
fauth orgs create --name "Acme" --slug acme --yes
fauth logout                               # revokes the key on the server, deletes the local file

Commands

Global option: --base-url <url> (env FAUTH_BASE_URL), default https://forge-auth.blueforge.studio. The URL must use https; plain http is allowed only for localhost.

Exit codes

Agentic login

Use this when an agent or script needs to be the operator without a browser. It follows the same pattern as fgit and packr: a secret in ~/.forge-secrets, one command, no TTY. The device flow is still the path for humans.

fauth login --admin --email you@example.com            # app "fauth", key valid for 30 days
fauth login --admin --email you@example.com --days 7 --json
FAUTH_EMAIL=you@example.com fauth login --admin --app fauth

Steps:

1. Reads the forge-auth admin API key (the server's FORGE_GIT_AUTH_ADMIN_KEY), trying these sources in order:

   1. the FAUTH_ADMIN_KEY env var
   2. ~/.forge-secrets/forge-auth-admin.key, which must be mode 0600. fauth refuses a group- or world-readable file and prints a chmod 600 hint.
   3. on macOS, the keychain item forge-auth-admin-key (security find-generic-password -s forge-auth-admin-key -w)

   The key is never read from argv.

2. Calls POST /api/admin/users/keys with { email, app, expiresInDays }. The server looks up the existing user by email (case-insensitive; it never creates users) and mints a key tied to that user and app, carrying the user's own scope set (user.scopes), as a device-flow key would. It uses the same code path as the device flow, so every /api/v1 route accepts the key the same way.

3. Checks the new key with GET /api/v1/me. If that fails, fauth revokes the key and saves nothing.

4. Saves the key to ~/.forge-secrets/forge-auth.json (0600) in the same form as the device flow, plus expiresAt, then prints whoami (or --json).

The email comes from --email, otherwise FAUTH_EMAIL, otherwise the command exits 2. --days accepts 1–90 and defaults to 30.

Security. The admin key can mint a key for any user. Keep it only in ~/.forge-secrets/forge-auth-admin.key (mode 0600) or the keychain. Never commit it, paste it into a chat, or pass it as a command-line argument. fauth never prints the admin key or the minted key. Each mint writes an audit line on the server (forge_auth.admin.user_key_minted: target user, app, key id, expiry; never the key), and fauth logout revokes the minted key.

Storing the admin key once, without it touching argv or shell history:

pbpaste > ~/.forge-secrets/forge-auth-admin.key && chmod 600 ~/.forge-secrets/forge-auth-admin.key
# or: security add-generic-password -s forge-auth-admin-key -a "$USER" -w   (prompts for the value)

Credentials

• The credential is stored in ~/.forge-secrets/forge-auth.json with mode 0600, inside a 0700 directory. It is written to a temp file and then renamed into place. FORGE_SECRETS_DIR overrides the directory.
• The file holds { baseUrl, token, appId, userId, email, savedAt }. The token is never printed.
• A stored key is only ever sent to the baseUrl it was issued by. If --base-url names a different server, the command exits with 2 and makes no request.
• FAUTH_TOKEN (env) takes precedence over the file. This matches how FORGE_GIT_TOKEN works for fgit.
• Secrets never go in argv. The key is sent only in a JSON body (/api/v1/users/resolve) or an Authorization: Bearer header, never in a URL.
• If the file is group- or world-readable, fauth prints a warning.

Before first login: register the fauth app (once)

forge-auth's device flow issues its key for a registered app (POST /api/auth/device { appId }). appId can be the app's id or its slug, and an unknown app returns 404 APP_NOT_FOUND. fauth login defaults to the slug fauth, so an admin registers that app once (safe to repeat):

fauth admin apps create --name "fauth CLI" --slug fauth
fauth admin apps show fauth        # prints the app_… id

Until then, pass any existing app id or slug with --app-id. The key is bound to its user, and the /api/v1 routes don't care which app it came from.

Server endpoints

The /api/v1 routes authenticate with Authorization: Bearer fk_…, and the admin mint uses X-Admin-Api-Key. The key must be user-bound (an app/admin key with no user gets 401) and unexpired (expires_at is honored). api_key rows have no scopes yet, so there is no scope check: a user-bound key acts as its user for these self-service routes. When key scopes land, the routes map to the scopes in the table. Every route is rate-limited in memory per key.

If a server predates these routes, whoami falls back to POST /api/v1/users/resolve (id + email only), and the orgs commands report that the server needs upgrading. An admin user lookup (fauth users find) is not built yet.

Build, install, publish

This directory is not a pnpm workspace member. commander and esbuild are devDependencies of the forge-auth root, and the bundle includes everything, so the published package has no runtime dependencies.

# from the forge-auth repo root
pnpm install
pnpm fauth:bundle                     # → packages/fauth/dist/fauth.mjs
pnpm fauth whoami                     # or run from source via tsx

# install the local build globally (before it is on packr)
cd packages/fauth && npm pack --pack-destination /tmp && npm install -g /tmp/blueforge-studio-fauth-$(node -p "require('./package.json').version").tgz

To publish to packr (operator only; not automated yet):

pnpm fauth:bundle
cd packages/fauth
npm view @blueforge-studio/fauth@$(node -p "require('./package.json').version") --registry https://api.packr.blueforge.studio/ version \
  && echo "already published — bump the version first"      # packr answers 409 to an overwrite
npm publish --registry https://api.packr.blueforge.studio/   # auth: PACKR_TOKEN via ~/.npmrc
# consumers: npm install -g @blueforge-studio/fauth --registry https://api.packr.blueforge.studio/

Never probe packr with curl -X PUT, because an empty PUT creates an empty version. The same rule is documented in fgit's scripts/publish-fgit.sh.