@vectros-ai/cli 0.15.0 → 0.19.0

package/README.md

@@ -8,7 +8,14 @@ The Vectros provisioning CLI — the `vectros` binary:
 - **`vectros bootstrap`** — provision a least-privilege MCP credential (+ optional blueprint).
 - **`vectros blueprint`** — author + inspect blueprints (`init` / `validate` / `plan` / `list`), creds-free.
 - **`vectros blueprint-test`** — apply a blueprint to a live env, assert it provisioned a working credential, then tear it down.
+- **`vectros context`** — create, list, and destroy app contexts.
+- **`vectros issuers`** — inspect registered third-party IdP issuers (token-exchange trust anchors) for a context.
+- **`vectros identity`** — manage tenant-wide principals (users, orgs, clients, and namespaces you register).
+- **`vectros role`** — define reusable, context-scoped access rules.
+- **`vectros access`** — bind principals to contexts, and inspect what a binding grants.
+- **`vectros key`** — issue, list, revoke, and rotate scoped API keys (`ssk_*`).
 - **`vectros keyring`** — hold several identities on one machine, pick which is active, and let other tools resolve keys from one place.
+- **`vectros join`** — enroll a principal in a context and keep the resulting credential in the keyring, in one step.
 
 ```bash
 npx -y @vectros-ai/cli bootstrap          # provision a credential
@@ -58,6 +65,11 @@ npx -y @vectros-ai/cli bootstrap --help
 ```
 
 Re-running is idempotent; `--rotate` revokes + re-mints just this machine's key.
+On a machine with no local record of a prior mint (e.g. an ephemeral CI
+container re-running `--yes` for the first time) against a blueprint whose
+service principal already exists in the tenant, `--yes` alone isn't enough —
+add `--confirm-existing-principal` to make that expected case explicit and
+non-interactive; see AUTHORING.md's "idempotency contract" for why.
 
 A bundled blueprint ships with **sample seed records** so the credential works
 the moment it's minted. For a **production** context that's synthetic clutter:
@@ -110,6 +122,214 @@ Exit `0` = applied and every assertion passed; `1` = an assertion failed or appl
 errored; `2` = no credential, or the blueprint requested control-plane scope.
 The app-context is intentionally **not** deleted (it's idempotent and reused).
 
+## `vectros context` — app contexts
+
+A context is the namespace all data (records, documents, schemas, roles, access
+profiles) lives in — the unit `bootstrap`/`blueprint-test` provision into.
+`vectros context` manages contexts directly, outside of a blueprint.
+
+```bash
+vectros context create my-app --name "My App"   # idempotent — re-running converges
+vectros context list                            # every context in the tenant
+vectros context list --mine                     # only contexts you hold an access profile in
+vectros context get my-app
+vectros context destroy my-app                  # irreversible — asks you to re-type the id
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `create <contextId>` | `--name <name>` (defaults to the id), `--tenant test\|live` | Idempotent by `contextId`; re-running converges. |
+| `list` | `--mine`, `--tenant test\|live` | Default lists every context in the tenant; `--mine` narrows to contexts you hold an active access profile in. |
+| `get <contextId>` | `--tenant test\|live` | |
+| `destroy <contextId>` | `--force`, `--tenant test\|live` | **Irreversible.** Permanently erases the context and ALL of its records, documents, folders, schemas, roles, and access profiles, and revokes its scoped keys up front. Interactively you must re-type the context id to confirm; `--force` skips the prompt and is **required** when stdin is not a TTY (scripts/CI). Reports `status: purging` — the teardown itself runs asynchronously. |
+
+All four accept `--json` for machine-readable output, plus the common auth
+flags (`--base-url`, `--token`).
+
+## `vectros issuers` — registered third-party IdP issuers
+
+Read the third-party identity-provider registrations a context trusts for
+[RFC 8693 token exchange](https://www.rfc-editor.org/rfc/rfc8693) — the
+`issuer`/`jwksUri`/`audience` a blueprint's `issuers[]` entries register, plus
+any self-signup policy attached to one. Read-only: registering an issuer is
+done through a blueprint (`bootstrap`/`blueprint-test`), not this command.
+
+```bash
+vectros issuers list --context my-app
+vectros issuers get primary --context my-app
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `list` | `--context <contextId>` (required), `--tenant test\|live` | Every issuer registered in that context. `--context` has no default — an issuer read is confined to the context you name; there's no tenant-wide "every issuer in every context" view. |
+| `get <issuerId>` | `--context <contextId>` (required), `--tenant test\|live` | One issuer's full registration, including its self-signup policies. |
+
+Both accept `--json`, plus the common auth flags (`--base-url`, `--token`).
+
+## `vectros identity` — tenant-wide principals
+
+Manage the principals a context's access profiles and roles reference: users
+(the one fixed principal surface, `--type user`) and namespaced identity
+entities (`org`, `client`, or any namespace you registered, via `--type
+<namespace>`). Identities are **tenant-wide and orthogonal to context** — a
+blueprint or role *references* one by id, it never creates one.
+
+```bash
+vectros identity create --type user --external-id alice@example.com --email alice@example.com
+vectros identity create --type org --external-id acme-inc --name "Acme Inc"
+vectros identity list --type user
+vectros identity get --type org --id <vectrosId>
+vectros identity delete --type org --id <vectrosId>
+vectros identity invite --context my-app --role editor --email bob@example.com \
+  --accept-url https://my-app.example.com/accept
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `create` | `--type <user\|namespace>` (required), `--external-id <id>` (required — your stable idempotency key) | Idempotent, upsert-by-`externalId`. |
+| | `--type user` only: `--email <email>`, `--service` (mint a SERVICE principal; default HUMAN) | `--name`/`--scope` are rejected for `--type user`. |
+| | entity namespaces only: `--name <name>`, `--scope <ns:value>` (repeatable, up to 2 parent ownership edges) | `--email`/`--service` are rejected for an entity namespace. |
+| | both: `--metadata <json>` | Free-form JSON object. |
+| `list` | `--type <user\|namespace>` (required), `--external-id <id>` (filter), `--limit <n>` | Omit `--limit` and the CLI drains every page for the complete set; pass `--limit` (1–100) and it returns exactly one page of that size instead. |
+| `get` | `--type <user\|namespace>` (required), `--id <vectrosId>` (required) | `--id` is the Vectros-assigned id from `create`/`list`, not the `--external-id`. |
+| `delete` | `--type <user\|namespace>` (required), `--id <vectrosId>` (required) | |
+| `invite` | `--context <c>`, `--role <roleId>`, `--email <e>` (all required); `--first-name <n>`, `--accept-url <url>`, `--no-send-email` | Onboards a person into a context by email (`POST /v1/users/invite`) — no root key required, your `vectros login` session already carries enough scope. `--role` is an existing Role's own id (no separate lookup). `--accept-url` is required unless `--no-send-email` is given, in which case the response carries the raw `inviteToken`/`acceptLink` for you to deliver yourself. |
+
+`create`/`list`/`get`/`invite` accept `--json`; `delete` does not.
+
+## `vectros role` — reusable, context-scoped access rules
+
+A Role is a reusable, identity-agnostic scope rule bound to a principal later
+via `vectros access grant --role <roleId>` — the same rule can be shared
+across many principals. `role create` builds a **single-clause** role from a
+flat `--actions` list; author a multi-clause role (several rules unioned
+together) in a blueprint's `roles:` block instead.
+
+```bash
+vectros role create --context my-app --role-id editor --name Editor \
+  --actions records:cru,search:r
+vectros role create --context my-app --role-id own-org --name "Own org" \
+  --actions records:r --data-scope '{"scope:org":["<orgId>", null]}'
+vectros role list --context my-app
+vectros role get --context my-app --role-id editor
+vectros role delete --context my-app --role-id editor
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `create` | `--context <c>`, `--role-id <id>`, `--name <n>`, `--actions <csv>` (all required); `--data-scope <json>`, `--description <text>` | Idempotent by `roleId`. `--data-scope` confines the clause to owned data — a JSON map of ownership dimension → allowed values, ANDed across keys (e.g. `{"userId":["${{ self.userId }}"]}`, or `{"scope:org":["<orgId>", null]}` — the `null` entry additionally admits scope-less/tenant-shared records). Keys must be `userId` or `scope:<namespace>` (the legacy flat `orgId`/`clientId` keys are rejected server-side). |
+| `list` | `--context <c>` (required) | |
+| `get` | `--context <c>`, `--role-id <id>` (both required) | Also shows the role's `assumable` grant (which values, per namespace, a holder of this role may become via `POST /v1/auth/token/assume`), if any is set. `role create` has no `--assumable` flag today — author it via a blueprint's `roleAssumable:` block or a direct API call. |
+| `delete` | `--context <c>`, `--role-id <id>` (both required) | No cascade — any access profile still referencing the role fails to mint (not silently downgraded) until reassigned. |
+
+`create`/`list`/`get` accept `--json`; `delete` does not.
+
+## `vectros access` — bind principals to contexts
+
+The binding layer between an identity and a context: `access grant` joins a
+principal to a context via a Role reference (`--role`) **or** inline actions
+(`--actions`) — never both. A later `vectros key issue` mints a credential
+that authenticates *as* the bound principal and can never exceed this
+binding.
+
+```bash
+vectros access grant --principal me --context my-app --role editor
+vectros access grant --principal usr_<id> --context my-app --actions records:r,search:r \
+  --scope org:<orgId>
+vectros access list --context my-app        # who's in this context
+vectros access list --principal me          # which contexts I'm bound to
+vectros access get --principal me --context my-app
+vectros access explain --principal me --context my-app
+vectros access revoke --principal usr_<id> --context my-app
+```
+
+`--principal` accepts `usr_<userId>`, `key_<keyId>`, or the alias `me` (your
+own signed-in user, resolved from your login) — every `access` subcommand
+shares this grammar.
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `grant` | `--principal <p>`, `--context <c>` (required); exactly one of `--role <roleId>` (repeatable — 2+ compose additively) / `--actions <csv>`; `--scope <ns:value>` (repeatable), `--identity-overrides <json>` | Idempotent **upsert** — re-granting an existing binding updates it to the newly-declared shape (role(s)/actions/overrides), it does not no-op. Repeating `--role` composes: `--role case-handler --role hr-admin` grants each role's own clauses, concatenated in the order given — never merged, so each clause keeps meaning exactly what its own author wrote. `--scope`/`--identity-overrides` extend the principal's stamped identity (e.g. `--scope org:<id>` → `scope:org`) — a credential can only stamp ownership its identity carries, so granting write access to org-scoped data requires that scope on the profile. When both are given, `--identity-overrides` wins on key conflicts. |
+| `revoke` | `--principal <p>`, `--context <c>` (required) | |
+| `list` | Exactly one of `--context <c>` / `--principal <p>` | `--context` lists the context's members; `--principal` lists every context that principal is bound to. |
+| `get` | `--principal <p>`, `--context <c>` (required) | |
+| `explain` | `--principal <p>`, `--context <c>` (required) | Resolves the binding's clauses (following every referenced role and concatenating their clauses, if bound via one or more) and renders a concrete **access matrix** — a canned set of record-ownership archetypes (yours alone, another user's, org-shared, scope-less, …) evaluated against the clauses. A client-side preview for authoring-time sanity, not the platform's own evaluator: it models READ reachability only — a `c`/`u`/`d` action shown as granted is advisory, not a guarantee a specific write will succeed, since the platform's write rule (a clause must explicitly name a dimension to place a value into it) diverges from its read rule (an unmentioned dimension never narrows reads). |
+
+`grant`/`list`/`get`/`explain` accept `--json`; `revoke` does not.
+
+## `vectros join` — enroll and keep the credential, in one step
+
+`join` is a **composition verb**: everything it does already exists as a
+discrete command (`access grant`, `key issue`, `keyring add`) — `join` runs
+them in order against one context and records the outcome as a keyring
+entry, so `vectros switch <alias>` (and the MCP server / recall hook) can act
+as that principal from then on.
+
+```bash
+vectros join my-app --role editor                       # enroll "me" via a role
+vectros join my-app --role case-handler --role hr-admin  # compose 2+ roles additively
+vectros join my-app --actions records:cru,search:r --scope org:<orgId>
+vectros join my-app --as usr_<id> --role editor --alias teammate
+```
+
+| Flag | Notes |
+|---|---|
+| `--role <roleId>` | Repeatable — 2+ compose additively, same semantics as `access grant --role`. XOR with `--actions`. |
+| `--actions <csv>` | Inline single-clause grant. XOR with `--role`. |
+| `--as me\|usr_<id>` (default `me`) | Which principal to enroll — `me` resolves to your own signed-in user. |
+| `--scope <ns:value>` | Repeatable. Places the member under a scope for this context (an identity override on the profile) so their key can WRITE that scope's data. |
+| `--alias <name>` | Keyring entry name (defaults to the context id). |
+| `--activate` / `--no-activate` | Force (or skip) making the freshly-stored key this machine's active identity. |
+
+Re-joining an alias whose secret is still held locally is idempotent: it
+re-grants (a no-op upsert) and re-activates without churning the key. Only
+when the local secret is missing does it rotate to obtain a fresh one.
+
+## `vectros key` — the scoped API key (`ssk_*`) lifecycle
+
+Mint, inspect, revoke, and rotate the scoped keys (`ssk_*`) that authenticate
+as a principal already bound to a context (`vectros access grant` first — a
+key can never exceed its profile). The raw secret is disclosed **exactly
+once**, on `issue`/`rotate`; if you lose it, `key rotate` mints a fresh one.
+
+```bash
+vectros key issue --principal usr_<id> --context my-app                  # print the secret (default)
+vectros key issue --principal usr_<id> --context my-app --to-keyring     # store it instead
+vectros key list                                                         # keys in the default context
+vectros key list --all-contexts                                         # every key, every context (owner-only)
+vectros key get <keyId>
+vectros key revoke <keyId>
+vectros key rotate --principal usr_<id> --context my-app                 # revoke + re-mint the same tuple
+```
+
+`--principal` here is `usr_<userId>` **or a bare user id** (the leading `usr_`
+is optional and stripped if present) — narrower than `access`'s grammar: there
+is no `me` alias on any `key` subcommand, and a key never authenticates as a
+`key_*` principal. Look your own id up first with `vectros identity list
+--type user` (or `vectros whoami`), or grant/issue via `vectros join`, which
+does resolve `--as me`.
+
+A minted secret has exactly two destinations, and the flags for choosing one
+are shared by `issue` and `rotate`:
+
+| Flag | Meaning |
+|---|---|
+| `--format human\|raw\|env\|json` (default `human`) | Print the secret — `raw` = bare secret only, `env` = a `VECTROS_API_KEY=...` line, `json` = the full key object. |
+| `--to-keyring` | Store the secret in this machine's keyring instead of printing it (the desktop/MCP path). Mutually exclusive with an explicit `--format raw\|env\|json`. |
+| `--alias <name>` | Keyring entry name for `--to-keyring` (defaults to the context id). |
+| `--no-activate` | With `--to-keyring`, store the entry without making it the active identity. |
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `issue` | `--principal <p>`, `--context <c>` (required); `--name <n>` (default `default`), `--label <l>`, `--tenant test\|live`, destination flags above | Idempotent on `(tenant, context, principal, name)` — re-issuing an existing tuple returns the key **without** the secret (never re-disclosed); the CLI detects that and points you at `rotate`. |
+| `list` | `--principal <p>`, `--context <c>`, `--tenant test\|live` **or** `--all-contexts` (owner-only; spans both tenants, not combinable with `--tenant`) | **The default lists only ONE context's keys** (the token's context — `default`, or `--context`), not your whole account — easy to miss since the active-key limit is tenant-wide across all contexts. `--all-contexts` is the true account-wide view. |
+| `get <keyId>` | `--context <c>`, `--tenant test\|live` | `--context` pins the verb token to the key's context — omit it for a key bound to a non-default context (e.g. one `bootstrap` minted) and the lookup 404s. |
+| `revoke <keyId>` | `--context <c>`, `--tenant test\|live` | Soft-delete; ~5 minutes to take effect (authorizer cache). Same `--context` pinning caveat as `get`. |
+| `rotate` | `--principal <p>`, `--context <c>` (required); `--name <n>`, `--force-new`, `--tenant test\|live`, destination flags above | Revokes the matching active key (by the exact `(context, principal, name)` tuple), then mints a fresh one — there is no dedicated rotate endpoint. **Default-name guard:** if no key is currently active under `--name` (default `default`) but the principal/context has *other* active keys, `rotate` refuses rather than silently minting an unrelated second key — pass the right `--name` or `--force-new` to proceed anyway. |
+
+`issue`/`rotate` have no `--json` (use `--format json` instead); `list`/`get`
+accept `--json`, `revoke` does not.
+
 ## `vectros keyring` — one home for your keys
 
 A machine can hold several Vectros identities (one per context or principal).
@@ -188,11 +408,42 @@ Blueprints are **untrusted input** (agent- or community-authored) and the
 CLI runs under an elevated ephemeral bridge token. So the trust boundary is
 **this binary, not the blueprint**: a hardcoded **scope gate** bounds every
 mint to a data-plane allowlist (`records` / `schemas` / `search` / `documents`
-/ `folders` / `inference` / `entities`). Any control-plane scope (keys /
-profiles / users / billing / admin / namespaces) or `*` wildcard
+/ `folders` / `inference` / `entities`). Most control-plane scope (keys /
+app-contexts / users / billing / admin / namespaces) or a `*` wildcard
 **hard-rejects** — the CLI mints nothing and exits non-zero. There is
 intentionally **no override flag**.
 
+**One narrow, deliberate exception:** `profiles` (which configures who has
+access to what — control-plane by nature) admits its `r`/`u`/`d` operations,
+because the platform enforces an unconditional check that a write to an
+AccessProfile can never grant more scope than the requesting credential
+already holds — those verbs can only disclose or redistribute access, never
+manufacture new reach. `profiles:c` (creating a profile for an arbitrary,
+caller-chosen principal name) still hard-rejects — **except** `profiles:c:self`,
+which the platform resolves from the credential's own identity at request
+time, never from anything the blueprint declares, and **except a bare
+`profiles:c` on a clause that also declares the `member-lifecycle` capability**
+(see Capabilities, below) — that combination is admitted because
+`member-lifecycle` already grants unbounded principal-creation reach, so
+gating bare `profiles:c` behind it adds no further technical bound but keeps
+the same explicit, fail-closed opt-in signal every other admission here
+requires. A literal-qualified `profiles:c:usr_<id>` naming another principal
+still hard-rejects regardless of `member-lifecycle`, same as every other
+control-plane scope.
+
+### Capabilities (`granted_capabilities`) — a separate, equally-gated dimension
+
+A blueprint's `accessProfile` and role clauses may also declare
+`capabilities: [...]` — named platform effects (like creating or removing an
+identity in your tenant) that reach across a partition boundary in a way no
+`resource:ops` verb can express. This rides a field entirely separate from
+`allowedActions`, and it has its own allowlist: **only `member-lifecycle` is
+admitted today.** Every other capability name — including ones the platform's
+own registry recognizes — is refused, the same fail-closed, deliberately-widen
+posture as the scope gate above. `vectros blueprint validate`/`plan` and
+`bootstrap` all report a rejected capability the same way they report a
+rejected scope: nothing mints, and the CLI exits non-zero.
+
 ## Rate limits
 
 `blueprint-test` provisions against the live API, so a large blueprint can brush the per-account

package/THIRD-PARTY-NOTICES.md

@@ -1,11 +1,11 @@
 # Third-party notices
 
 `@vectros-ai/cli` compiles the following third-party packages directly into its
-published binary (`dist/cli.js`). Their licenses require that these notices travel
-with the code, so they are reproduced in full below.
+published bundle. Their licenses require that these notices travel with the code,
+so they are reproduced in full below.
 
-This file is GENERATED by `pipelines/third_party_notices.mjs` from the `noExternal`
-lists in `packages/*/tsup.config.ts`. Do not edit it by hand — run
+This file is GENERATED by `pipelines/third_party_notices.mjs` from `packages/cli/tsup.config.ts`'s
+`noExternal` list. Do not edit it by hand — run
 `node pipelines/third_party_notices.mjs --write`. CI fails if it is stale, because a
 notices file that silently drifts is worse than none: it asserts a compliance that
 nobody checked.