@vectros-ai/cli 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.24.0 — 2026-10-01
+
+### Added
+
+- **`vectros provider-config <create|list|get|update|delete>`** manages your bring-your-own-model provider
+  configs (owner-gated). `create` and `list` take `--tenant test|live`; `get`, `update` and `delete` address a
+  config by its id. The provider credential is read from `--api-key-secret-file <path>` (`-` for stdin); there is
+  no flag that takes the credential on the command line. `update` is a partial patch: an omitted field, including
+  `--api-key-secret-file`, keeps the stored value.
+- **`vectros domains <register|list|delete|verify>`** manages domain ownership verification by DNS TXT record
+  (owner-gated) — the proof of control that `issuers register --restricted-to-domain` and webhook targets rely on.
+  `register` prints the exact TXT record to publish and the `verify` command to run next; registering a domain you
+  already hold returns a `409`. `verify` performs one DNS lookup per call and never polls. Domains are shared
+  across your live and test tenants, so none of the four verbs take `--tenant`. A verified domain that a webhook
+  uses is re-checked periodically; `list` and `verify` report a domain whose re-checks keep failing as
+  `REVOKED`.
+
+### Changed
+
+- **`vectros --version` reports SDK 0.46.0 and blueprints 0.20.1.**
+
+### Fixed
+
+- **`issuers update --clear-restricted-to-domain` is described as the platform applies it.** The platform refuses
+  to clear a domain scope unless the registration already holds the unrestricted `(issuer, audience)` pair, which
+  a registration created scoped to a domain does not. To get an unrestricted issuer, `issuers delete` the scoped
+  registration, register one without `--restricted-to-domain`, and `issuers verify` it. A context holds one
+  active issuer, and the delete is refused once any user has been created or matched through the issuer; in that
+  case register the new issuer under a different app context. The README, the flag's help and the hints shown for
+  a blank `--restricted-to-domain` state this.
+
 ## 0.23.0 — 2026-09-22
 
 ### Added

package/README.md

@@ -11,6 +11,8 @@ The Vectros provisioning CLI — the `vectros` binary:
 - **`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 provider-config`** — create, list, get, update, and delete BYOM (bring-your-own-model) tenant-level provider configs.
+- **`vectros domains`** — register a domain, list your registrations, and prove DNS TXT ownership.
 - **`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.
@@ -198,11 +200,11 @@ the result (the app-context + each schema are readable back, and the freshly
 minted `ssk_*` authenticates as a scoped key with the requested actions), then
 **tears down** what it created — schemas, the AccessProfile, seed records, and
 the key. Teardown is *created-only*: anything that already existed before the run
-is left untouched, so it's safe to point at a shared staging tenant.
+is left untouched, so it can be pointed at a tenant other people use.
 
 ```bash
-# Apply → assert → teardown against staging (sign in first, or pass --token).
-vectros blueprint-test ./my-thing.blueprint.yaml --env staging
+# Apply → assert → teardown against your test tenant (sign in first, or pass --token).
+vectros blueprint-test ./my-thing.blueprint.yaml --tenant test
 
 # Leave the provisioned graph in place to inspect it.
 vectros blueprint-test task-management --keep
@@ -262,7 +264,7 @@ vectros issuers verify auth0-prod --context my-app --idp-token-file ./idp-token.
 | 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), `--captured-claim <name>` (repeatable), `--restricted-to-domain <domain>`, `--tenant test\|live` | Idempotent by `--issuer-id` within the tenant — a repeat returns the existing registration unchanged, not an error. `--captured-claim` names additional OIDC claims to capture beyond the email claim on every successful token exchange, stored as your tenant's golden identity-provider-asserted copy for that user; omit it to capture nothing beyond email. At most 20 names of at most 64 characters, no duplicates. `--jwks-uri`/`--userinfo-uri` must be `https://` — an `http://` value is refused with 400. A tenant may hold at most 50 registrations at once; registering past that cap is also refused with 400. A `--self-signup-policy` naming a role that authors, updates, or deletes scripts (`scripts:c`/`u`/`d`) is refused — a self-signup role may still read or execute scripts. `--restricted-to-domain` scopes the registration to a domain already verified for your account (verified once, in the developer portal): a token then matches only when its `hd` claim equals that domain, so the registration is never blocked by an unrelated registration of the same issuer and audience. Google Workspace emits `hd` natively; other identity providers need a claims-mapping rule that emits a claim named exactly `hd`, otherwise none of their tokens will match. An unverified domain is refused with 400; a value that is not a DNS name (including a blank one) is refused locally. `register` never changes an existing registration, so when the response does not carry the requested scope (an existing `--issuer-id` with a different one, or a platform that predates the field) it fails with exit 1 and names `issuers update`, which does apply it; a repeat with the same scope is still an idempotent success. |
-| `update <issuerId>` | `--context <contextId>` (required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--status active\|suspended`, `--self-signup-policy <type:roleId>` (repeatable), `--clear-self-signup-policies`, `--captured-claim <name>` (repeatable), `--clear-captured-claims`, `--restricted-to-domain <domain>`, `--clear-restricted-to-domain`, `--tenant test\|live` | Omitting `--captured-claim` leaves the stored list UNCHANGED; `--clear-captured-claims` sends an explicit empty list (capture nothing beyond email). The two are mutually exclusive, and the same absent-vs-clear split applies to `--self-signup-policy`. 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`. `--sub-claim` is refused with 400 once any user has ever bound through this issuer — supplying the value it already has is still a no-op. `--userinfo-uri` must be `https://`, same as at registration. Omitting `--restricted-to-domain` leaves the stored scope UNCHANGED; `--clear-restricted-to-domain` removes it, and a blank `--restricted-to-domain ''` is refused locally rather than read as a clear. The two are mutually exclusive, and a new domain must already be verified for your account. The platform can refuse to clear a scope (for example when another registration already holds the unrestricted `(issuer, audience)` pair); its message says why. ⚠️ Scoping an existing issuer stops matching every token that carries no matching `hd` claim, including those of users who signed in before. |
+| `update <issuerId>` | `--context <contextId>` (required); `--sub-claim`, `--email-claim`, `--userinfo-uri`, `--status active\|suspended`, `--self-signup-policy <type:roleId>` (repeatable), `--clear-self-signup-policies`, `--captured-claim <name>` (repeatable), `--clear-captured-claims`, `--restricted-to-domain <domain>`, `--clear-restricted-to-domain`, `--tenant test\|live` | Omitting `--captured-claim` leaves the stored list UNCHANGED; `--clear-captured-claims` sends an explicit empty list (capture nothing beyond email). The two are mutually exclusive, and the same absent-vs-clear split applies to `--self-signup-policy`. 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`. `--sub-claim` is refused with 400 once any user has ever bound through this issuer — supplying the value it already has is still a no-op. `--userinfo-uri` must be `https://`, same as at registration. Omitting `--restricted-to-domain` leaves the stored scope UNCHANGED; `--clear-restricted-to-domain` removes it, and a blank `--restricted-to-domain ''` is refused locally rather than read as a clear. The two are mutually exclusive, and a new domain must already be verified for your account. From platform 0.45.0 the platform refuses to clear the scope unless the registration already holds the unrestricted `(issuer, audience)` pair, which a registration created scoped to a domain normally does not, since it never proved control of that pair. To get an unrestricted issuer instead, `delete` the scoped registration, `register` a new one without `--restricted-to-domain`, and `verify` it. A context holds one active issuer, and `delete` is refused once any user has been created or matched through the issuer; in that case register the new issuer under a different app context. ⚠️ Scoping an existing issuer stops matching every token that carries no matching `hd` claim, including those of users who signed in before. |
 | `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, captured claims and `restrictedToDomain`. |
@@ -273,6 +275,71 @@ challenge of a `pending_verification` registration (the claim, the one-time valu
 instructions and the exact `verify` command; a registration made without `--restricted-to-domain` starts that way on
 platform 0.45.0 and later, and `register` exits `0` because a pending issuer is its expected result.
 
+## `vectros provider-config` — BYOM tenant-level provider configs
+
+Manage per-tenant "bring your own model" provider configs — a customer-supplied inference
+endpoint + credential the platform can route to, instead of (or alongside) Vectros's own
+platform-billed models. A tenant may hold more than one, each independently selected by its
+`alias`. There is no SDK support for this route (it is a dev-portal-only surface, like
+`vectros context`) — every verb here calls the owner-gated developer route directly.
+
+```bash
+vectros provider-config create --tenant live --alias primary \
+  --provider-type ANTHROPIC_NATIVE --billing-mode CUSTOMER_DIRECT \
+  --waiver-type byo-model-inference:customer-key \
+  --api-key-secret-file ./anthropic-key.txt
+vectros provider-config list --tenant live
+vectros provider-config get pc_abc123
+vectros provider-config update pc_abc123 --status DISABLED
+vectros provider-config delete pc_abc123   # re-types the id to confirm
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `create` | `--alias`, `--provider-type ANTHROPIC_NATIVE\|OPENAI_COMPATIBLE`, `--billing-mode PLATFORM_BILLED\|CUSTOMER_DIRECT`, `--waiver-type`, `--api-key-secret-file <path>` (all required); `--endpoint`, `--declared-processing-region`, `--default-provider-model-id`, `--platform-token-factor`, `--platform-output-weight` (required together, only under `PLATFORM_BILLED`), `--status`, `--tenant test\|live` | NOT idempotent — a repeat `--alias` in the same tenant 400s. `--endpoint` is required for `OPENAI_COMPATIBLE` (no default — every self-hosted deployment is a distinct URL) and an optional override for `ANTHROPIC_NATIVE`; it must be an `https://` URL whose host resolves to a public address. `--status ACTIVE` (the default) requires the tenant already hold a granted waiver for `--waiver-type`. |
+| `list` | `--tenant test\|live` | Every config in one tenant — there is no combined test+live view. |
+| `get <id>` | | One config's metadata. The secret is never returned by the platform, on this or any other verb. |
+| `update <id>` | Same fields as `create` except `--tenant`, all optional | Partial update — an omitted field (`--api-key-secret-file` included) leaves the stored value unchanged. Switching `--billing-mode CUSTOMER_DIRECT` clears the platform pricing fields server-side regardless of what else is sent. |
+| `delete <id>` | `--force` | Re-types the id to confirm (mirrors `issuers delete`); `--force` skips the prompt and is required when stdin is not a TTY. |
+
+**There is deliberately no `--api-key-secret <value>` flag** — a live provider credential on the
+command line is visible in shell history and the process list. Pass `--api-key-secret-file
+<path>` (`-` for stdin instead of a file), the same shape `issuers verify
+--idp-token-file` already uses for a different live credential.
+
+All five accept `--json`, plus the common auth flags (`--base-url`, `--token`).
+
+## `vectros domains` — domain ownership verification
+
+Prove control of a domain via a DNS TXT record — the same proof-of-control a `vectros issuers
+register --restricted-to-domain` scope, or a webhook target, is checked against. Verification is
+Account-level (shared across your live and test tenants), so none of these commands take
+`--tenant`.
+
+```bash
+vectros domains register --domain example.com
+# → prints the TXT record to publish and the exact verify command
+vectros domains list
+vectros domains verify dom_abc123
+vectros domains delete dom_abc123   # re-types the id to confirm
+```
+
+| Subcommand | Flags | Notes |
+|---|---|---|
+| `register` | `--domain <domain>` (required) | NOT idempotent — registering a domain you already hold 409s, naming the existing id/status and (if still pending) the `verify` command to run instead. Prints the exact DNS TXT record to publish. |
+| `list` | | Every domain registered for your account, across both tenants. |
+| `verify <id>` | | Performs ONE DNS TXT lookup and reports `VERIFIED`, `FAILED` (never proved) or `REVOKED` (proved once, since lost) — always safe to re-run, never polls for you (the platform's TXT lookup can only succeed once your DNS provider has actually propagated the record). Exit `0` verified, `1` not verified — the platform reports `200` either way, so the exit code (not the HTTP status) is what a script should branch on. |
+| `delete <id>` | `--force` | Re-types the id to confirm; refused server-side (`409`) while any active webhook still references the domain. |
+
+All four accept `--json`, plus the common auth flags (`--base-url`, `--token`). A blueprint can
+only REFERENCE an already-verified domain (as `issuers`' `restrictedToDomain` already does) — it
+cannot declare/register one.
+
+A verified domain that a webhook uses is re-checked periodically. After repeated consecutive failed
+re-checks it becomes `REVOKED` and the webhooks that use it are suspended; `verify` on a `REVOKED`
+domain restores it to `VERIFIED` once the TXT record is published again, and each suspended webhook is
+then re-enabled individually.
+
 ## `vectros namespace` — scope-namespace registrations
 
 Register and inspect the namespaces a `scope:<namespace>` value can belong
@@ -327,7 +394,7 @@ vectros identity invite --context my-app --role editor --email bob@example.com \
 | `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. |
+| `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` (and an `acceptLink` when you passed `--accept-url`) for you to deliver yourself. Whenever it is supplied, the accept URL must be an `https://` URL with a domain-name host, never an IP literal. |
 
 `create`/`list`/`list-all`/`get`/`invite` accept `--json`; `delete` does not.