@userbox/cli 0.0.0-bootstrap.0 → 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to `@userbox/cli` are documented in this file.
+
+## [0.1.0-alpha.0] — 2026-11-04
+
+### Added
+- First release. `userbox login`, `logout`, `whoami`, `init` (Next.js App
+  Router), `apply` (`userbox.yaml`), `dev seed` and `doctor`. Every command
+  takes `--json` for coding agents.

package/README.md

@@ -1,3 +1,57 @@
-# @userbox/cli
+# `@userbox/cli`
 
-Placeholder. Install `@userbox/cli@alpha`.
+The Userbox command-line tool, binary `userbox`. It sets up
+[Userbox](https://docs.test.userbox.app) in a Next.js App Router app: allowed
+redirect domain, API key, `.env.local`, SDKs and the auth files. It then keeps
+permissions and roles in sync with a `userbox.yaml` in your repository.
+
+Status: alpha, `test` environment only. The unscoped npm name `userbox` belongs
+to an unrelated third party; the CLI is only published as `@userbox/cli`.
+
+```bash
+npx @userbox/cli login      # a human, once: tenant slug, email, password
+npx @userbox/cli init       # in the app root
+npx @userbox/cli apply      # sync userbox.yaml
+npx @userbox/cli dev seed   # a dev workspace where you are admin
+npx @userbox/cli doctor     # check everything
+```
+
+## For coding agents
+
+Every command takes `--json` and exits non-zero with `{ "ok": false, "error": { "code", "message", "hint" } }`.
+Secrets never pass through the model:
+
+- `login` refuses to run without an interactive terminal. If a command fails
+  with `NOT_LOGGED_IN`, `SESSION_EXPIRED` or `NEEDS_HUMAN`, ask the human to
+  run `npx @userbox/cli login` in their own terminal.
+- `init` writes the API key straight to `.env.local` and never prints it.
+- `apply` without `--yes` only prints the plan when there is no terminal: show
+  it to the human, then run `apply --yes`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `login` | Logs in as a tenant admin (a user with console access). Stores the session in `~/.config/userbox/credentials.json`, mode 600. `--api-url` picks another API. |
+| `logout` / `whoami` | Forget / show the login. |
+| `init` | Needs Next.js with `app/` or `src/app/`. Adds the `--origin` host (default `http://localhost:3000`) to the allowed redirect domains, creates an API key with `access:check`, `memberships:read`, `workspaces:read` unless `.env.local` already has one, merges the five variables into `.env.local` without touching existing values (`--force` replaces them), makes sure `.env.local` is git-ignored, installs `@userbox/react@alpha` and `@userbox/node@alpha` (`--skip-install` skips it), and writes `providers.tsx`, `auth/callback/page.tsx` and `api/auth/refresh/route.ts` if they do not exist. It wraps `{children}` in the root layout with `<Providers>` when that edit is unambiguous. |
+| `apply` | Reads `userbox.yaml`, creates missing permissions, and makes every declared role in every active workspace hold exactly its listed permissions. Permissions and roles that are not in the file are reported, never deleted. |
+| `dev seed` | Creates (or reuses) the workspace `dev`, syncs `userbox.yaml` into it and gives you the `admin` role. `--invite email[:role]` invites more users by email (role defaults to `member`). Warns when the default environment is a production environment. |
+| `doctor` | Checks the project, SDK versions, auth files, `.env.local`, secrets in `NEXT_PUBLIC_*`, `.gitignore`, the API and JWKS, the API key's tenant and `access:check` scope, and, when logged in, the redirect domain and sign-up mode. Exits 1 when a check fails. |
+
+## `userbox.yaml`
+
+```yaml
+permissions: [projects.read, projects.create, projects.delete]
+roles:
+  admin:  [projects.*]
+  member: [projects.read, projects.create]
+```
+
+Permission keys have 2 to 5 lowercase segments separated by dots. `prefix.*`
+expands to every declared permission with that prefix. Roles live in
+workspaces: run `userbox apply` again after creating a workspace.
+
+## License
+
+Apache-2.0

package/SECURITY.md

@@ -0,0 +1,26 @@
+# Security policy — `@userbox/cli`
+
+## Threat model summary
+
+- **Server-side only.** The client authenticates with a Userbox API key (or a
+  JWT for audit logs). Never ship it to a browser bundle: an API key in client
+  code is a leaked key.
+- **Credentials are never logged.** The client has no logging. Error messages,
+  `UserboxError` objects and their serialised forms never contain the API key,
+  the tenant ID header value or the request headers. A unit test
+  (`tests/credentials-not-logged.unit.test.ts`) asserts this for every API-key
+  prefix, and asserts that the source contains no `console.*` call.
+- **Zero runtime dependencies.** The client uses the runtime's global `fetch`,
+  `URL` and `Headers`. Nothing is pulled in at install time.
+- **Fail closed.** `can()` returns `true` only when the API answers
+  `allowed: true`. Any error throws; it never resolves to `true`.
+- **Response shape guard.** 2xx bodies are checked at the top level before use.
+  A malformed body raises an error instead of being trusted.
+- **Server authority.** Permission decisions are made by the Userbox API on
+  every call. The client caches nothing.
+
+## Reporting a vulnerability
+
+See the repository [security policy](../SECURITY.md). Report privately through
+GitHub private vulnerability reporting or **security@osbxtech.nl**, never in a
+public issue.