@vectros-ai/cli 0.16.0 → 0.20.0

package/README.md

@@ -9,11 +9,15 @@ The Vectros provisioning CLI — the `vectros` binary:
 - **`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`** — register, update, delete, and inspect third-party IdP issuers (token-exchange trust anchors) for a context.
+- **`vectros namespace`** — register a new scope namespace, and list/get existing ones.
 - **`vectros identity`** — manage tenant-wide principals (users, orgs, clients, and namespaces you register).
 - **`vectros role`** — define reusable, context-scoped access rules.
+- **`vectros assume`** — switch identity namespace values on your own token, per a role's `assumable` grant.
 - **`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
@@ -144,6 +148,63 @@ vectros context destroy my-app                  # irreversible — asks you to r
 All four accept `--json` for machine-readable output, plus the common auth
 flags (`--base-url`, `--token`).
 
+## `vectros issuers` — registered third-party IdP issuers
+
+Manage 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. Everything a blueprint's `issuers:`
+block can do is available standalone here too — adding a second IdP, or
+editing one issuer's `selfSignupPolicies` after initial setup, no longer
+requires hand-authoring a blueprint and re-running a full apply.
+
+```bash
+vectros issuers register --context my-app --issuer-id auth0-prod \
+  --issuer https://your-tenant.us.auth0.com/ \
+  --jwks-uri https://your-tenant.us.auth0.com/.well-known/jwks.json \
+  --audience https://api.your-app.example.com
+vectros issuers list --context my-app
+vectros issuers get primary --context my-app
+vectros issuers update primary --context my-app --status suspended
+vectros issuers delete primary --context my-app   # re-types the id to confirm
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `register` | `--context`, `--issuer-id`, `--issuer`, `--jwks-uri`, `--audience` (all required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--self-signup-policy <type:roleId>` (repeatable), `--tenant test\|live` | Idempotent by `--issuer-id` within the tenant — a repeat returns the existing registration unchanged, not an error. |
+| `update <issuerId>` | `--context <contextId>` (required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--status active\|suspended`, `--self-signup-policy <type:roleId>` (repeatable), `--clear-self-signup-policies`, `--tenant test\|live` | Only ever sends the SAFE, mutable fields — `issuer`/`jwks-uri`/`audience`/`contextId` are trust-anchor fields, immutable via this route on the platform side; rotating one is `delete` + `register`. |
+| `delete <issuerId>` | `--context <contextId>` (required), `--force`, `--tenant test\|live` | Re-types the issuer id to confirm (mirrors `context destroy`); `--force` skips the prompt and is required when stdin isn't a TTY. Refused server-side while any user was ever created or matched through this issuer. |
+| `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. |
+
+All five accept `--json`, plus the common auth flags (`--base-url`, `--token`).
+
+## `vectros namespace` — scope-namespace registrations
+
+Register and inspect the namespaces a `scope:<namespace>` value can belong
+to — whether values in that namespace must resolve to a real identity entity
+(`entityBacked`, the same field `identity create --type <namespace>`
+relies on) or are free-form strings. Registering a brand-new namespace (e.g.
+a `practice`/`team` entity dimension) was blueprint-apply-only before this
+command existed.
+
+```bash
+vectros namespace register practice --context my-app --specificity-rank 1500 --entity-backed
+vectros namespace list                        # tenant-wide registrations
+vectros namespace list --context my-app       # just my-app's own
+vectros namespace get practice --context my-app
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `register <name>` | `--context`, `--specificity-rank <n>` (both required); `--entity-backed`, `--default-schema-id <id>` | NOT idempotent — a repeat name 400s (unlike `issuers register`). `--context` has no tenant-wide option here — a confined credential may only register against its own bound context. |
+| `list` | `--context <contextId>` (optional) | Omit for every tenant-wide registration; supply for one context's own. |
+| `get <name>` | `--context <contextId>` (optional) | Same two-mode read as `list`. |
+
+No `update`/`delete` — both routes require a genuine root API key on the
+platform side, which this CLI never holds, so neither could ever succeed
+here. All three subcommands accept `--json`.
+
 ## `vectros identity` — tenant-wide principals
 
 Manage the principals a context's access profiles and roles reference: users
@@ -158,6 +219,8 @@ 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 |
@@ -166,11 +229,13 @@ vectros identity delete --type org --id <vectrosId>
 | | `--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. |
+| `list` | `--type <user\|namespace>` (required), `--external-id <id>` (filter), `--limit <n>` | Scoped to your own context — see `list-all` below for a user created but never granted access anywhere. 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. |
+| `list-all` | `--external-id <id>` (filter), `--tenant test\|live`, `--limit <n>` | **Users only, and requires an account owner login.** Lists every user in the tenant, regardless of app-context access — for recovering a user `identity list` can never show you: one created but not (yet) granted access anywhere, so no context-scoped view can ever reach it, and a `create` retry with the same `--external-id` just collides with the same invisible row. Find it here by `--external-id`, then grant it access or `identity delete` it with an ordinary credential. |
 | `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` accept `--json`; `delete` does not.
+`create`/`list`/`list-all`/`get`/`invite` accept `--json`; `delete` does not.
 
 ## `vectros role` — reusable, context-scoped access rules
 
@@ -185,6 +250,8 @@ 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 create --context my-app --role-id hr-admin --name "HR Admin" \
+  --actions records:cru --assumable '{"scope:org":["org_engineering", "org_sales"]}'
 vectros role list --context my-app
 vectros role get --context my-app --role-id editor
 vectros role delete --context my-app --role-id editor
@@ -192,13 +259,35 @@ 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). |
+| `create` | `--context <c>`, `--role-id <id>`, `--name <n>`, `--actions <csv>` (all required); `--data-scope <json>`, `--assumable <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). `--assumable` is a SEPARATE, role-level grant — a JSON map of `scope:<namespace>` → allowed values naming which values a holder of this role may switch into via `vectros assume`; holding broad `--data-scope` reach in a namespace does not by itself grant assuming any value in it. |
 | `list` | `--context <c>` (required) | |
-| `get` | `--context <c>`, `--role-id <id>` (both required) | |
+| `get` | `--context <c>`, `--role-id <id>` (both required) | Also shows the role's `assumable` grant, if any is set. |
 | `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 assume` — switch identity namespace values on your own token
+
+Re-mints your own verb token with one or more `identity.<namespace>` values
+switched — the "org switcher" flow, named (like the platform endpoint it
+calls) after AWS STS `AssumeRole`. Only works if a role you currently hold
+explicitly grants assuming the requested value(s) via that role's own
+`--assumable` grant (checked live against your CURRENT roles, never a value
+frozen into your token at mint time).
+
+```bash
+vectros assume --context my-app --scope org:org_sales
+```
+
+| Flags | Notes |
+|---|---|
+| `--context <c>` (required), `--scope <ns:value>` (repeatable, at least one required) | Each `--scope` becomes one `scope:<namespace>` entry in the request. No artificial cap on how many namespaces you name — the platform requires a SINGLE role to jointly grant the whole combination and rejects an unsatisfiable one itself. |
+
+Prints the re-minted `access_token`/`expires_in` (accepts `--json`) — there
+is no `--to-keyring` here, since the result is an ephemeral bearer token
+with the same remaining lifetime as the verb token this command itself
+mints to make the call, not a durable secret the keyring is built to hold.
+
 ## `vectros access` — bind principals to contexts
 
 The binding layer between an identity and a context: `access grant` joins a
@@ -224,14 +313,42 @@ shares this grammar.
 
 | Subcommand | Flags | Notes |
 |---|---|---|
-| `grant` | `--principal <p>`, `--context <c>` (required); exactly one of `--role <roleId>` / `--actions <csv>`; `--scope <ns:value>` (repeatable), `--identity-overrides <json>` | Idempotent **upsert** — re-granting an existing binding updates it to the newly-declared shape (role/actions/overrides), it does not no-op. `--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. |
+| `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 its role, if bound via one) 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). |
+| `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
@@ -368,9 +485,15 @@ 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; a bare `profiles:c` or a
-literal `profiles:c:usr_<id>` naming another principal still hard-rejects,
-same as every other control-plane scope.
+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
 
@@ -378,10 +501,10 @@ 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
+`allowedActions`, and it has its own allowlist: **`member-lifecycle` and
+`delegate-principal-stamp` are 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.
 

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.