@vectros-ai/cli 0.21.0 → 0.22.0

package/AUTHORING.md

@@ -625,14 +625,47 @@ version and compares the stored `source` and `declaredInputContract` against
 what the blueprint declares, and pushes only on a real difference. So a re-apply
 of an unedited blueprint writes nothing, and editing `source` stores exactly one
 new version, which every `version: latest` rule then picks up. The apply summary
-reports which of the two happened per script.
-
-Two consequences worth planning for. A concurrent apply of the same blueprint
-can collide on one script name; the loader re-reads and retries once, so two
-runners applying identical content converge rather than storing it twice, but a
-sustained collision fails the apply and asks you to re-run. And **removing a
-`scripts:` entry does not delete anything** — every stored version stays, because
-a script carries no record of which blueprint pushed it. Remove one deliberately
+reports which of `created` (no prior version) / `superseded` (this blueprint's
+own prior version, replaced) / `adopted` (see below) / `unchanged` happened per
+script.
+
+**A THIRD qualification: pushing onto a name that already has a version is
+gated on OWNING it.** A script name is a flat, per-context namespace shared
+with every other blueprint and every hand-pushed script, so before superseding
+one, the loader checks who pushed the current version:
+- **owned by a different blueprint** — refused outright, no override. Ship
+  under a different name instead, or coordinate with whoever owns it.
+- **no owner recorded** (hand-authored via `vectros scripts push`, or pushed
+  before this check existed) — refused unless the OPERATOR re-runs
+  `bootstrap` with `--allow-script-adoption`. This is deliberately a
+  human-supplied CLI flag, never something a blueprint's own YAML/JSON can
+  set — the blueprint is untrusted input, and "I already own this name" is not
+  something it gets to assert for itself. A successful adopting push reports
+  `adopted`, distinct from an ordinary `superseded`.
+
+  **Know before you rely on this: adoption is safe for an account owner,
+  and refused for a Dev Portal sub-user adopting someone else's hand-push.**
+  The platform's own authorization still applies underneath this flag, and it
+  resolves caller identity differently for the two shapes. An account owner
+  always authenticates as the same identity regardless of which login session
+  minted the token, so adopting a script you (the owner) hand-pushed earlier —
+  or one nobody's identity is recorded against at all — succeeds. A distinct
+  team member (a sub-user) resolves to their own, different identity, and the
+  platform refuses to supersede an unmarked name pushed by anyone else — so
+  one sub-user cannot adopt a script a DIFFERENT sub-user hand-pushed, even
+  with this flag. If you hit that, either have the original pusher run the
+  adopting apply, or push the script under the account owner's own login
+  first.
+- **owned by this SAME blueprint, or the name is brand new** — no flag needed;
+  this is the ordinary re-apply / first-push path.
+
+Two more consequences worth planning for. A concurrent apply of the same
+blueprint can collide on one script name; the loader re-reads and retries once,
+so two runners applying identical content converge rather than storing it
+twice, but a sustained collision fails the apply and asks you to re-run. And
+**removing a `scripts:` entry does not delete anything** — every stored version
+stays, because there is no second, principal-shaped factor to safely gate a
+DELETE the way a trigger row's provenance marker does. Remove one deliberately
 with `vectros scripts delete`.
 
 ## Distribution

package/CHANGELOG.md

@@ -3,6 +3,192 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.22.0 — 2026-09-17
+
+### Changed
+
+- **⚠️ BREAKING: `vectros bootstrap --blueprint` now refuses to push a script version onto a name it
+  cannot show it owns.** Previously, a blueprint declaring `scripts:` could push a new version onto
+  ANY existing script name in the target context — including one it never declared, hand-authored, or
+  belonging to a different blueprint — with no error. If a pre-existing trigger rule referenced that
+  name via `version: 'latest'` (the only form a blueprint-shipped script may use), the newly pushed
+  code would run under that rule's own, unrelated grant from its very next firing. An apply that used
+  to succeed against such a name now refuses before minting anything: a name already owned by a
+  DIFFERENT blueprint refuses unconditionally (push under a different name instead); a name with no
+  ownership marker at all (hand-authored, or pushed before this marker existed) refuses unless the new
+  `--allow-script-adoption` flag is passed, reporting the outcome as `adopted` rather than
+  `superseded`. **This is a MINOR bump, not a patch, for the same reason as the entry above:** an
+  operator or CI pipeline that did nothing wrong and passed no new flag can now see an apply that
+  previously succeeded fail instead. A blueprint re-applying onto a name it already owns, or shipping
+  a brand-new name, is unaffected either way. See `AUTHORING.md`'s *idempotency contract* section for
+  the full behavior.
+- **⚠️ BREAKING: `--no-merge` no longer implies an unattended run.** `--no-merge`'s documented
+  purpose is only to change where the resulting config goes (printed vs. merged into your
+  client's config file) — it still mints/reconciles the same real state either way — but both
+  the "Apply this plan?" confirmation and the seed-data opt-out prompt used to treat it as an
+  implicit `--yes`, so an operator (or a script) that had been relying on `--no-merge` alone to
+  run without either prompt will now be asked, if the session is interactive. **This is a MINOR
+  bump, not a patch, for the same reason as `@vectros-ai/blueprints`' own bump below: narrowing
+  an UNATTENDED-RUN contract is a breaking change for a script or wrapper that passes no new
+  flag, arguably a sharper break than narrowing an input contract, since the caller did nothing
+  wrong and gets no error — it just now blocks on a prompt it never used to see.** Pass `--yes`
+  explicitly if you need `--no-merge` to keep running unattended; a genuinely non-interactive
+  session (no TTY — the common case for CI) is unaffected either way, since neither prompt ever
+  fires there. The help text is corrected to say so.
+
+### Security
+
+- **`vectros login`'s persisted Cognito refresh token could be POSTed to an attacker-controlled
+  host.** `VECTROS_COGNITO_DOMAIN` (and `VECTROS_COGNITO_REGION`, interpolated into the default
+  domain) were read verbatim from the environment and never validated — unlike the partner-API base
+  URL, which already goes through the same credential-exfil guard (`validateBaseUrl`). A developer
+  with an env var influenced by a repo-scoped config they never read as executable (a `.envrc`, a
+  devcontainer, a CI variable, an `.mcp.json` snippet) could have their long-lived Cognito refresh
+  token — and, on the interactive flow, the authorization code + PKCE verifier — sent to that host
+  on the very next creds-bearing command, with no prompt and no warning.
+
+  The Cognito domain now goes through `validateBaseUrl` too, extended with an allow-list entry for
+  the two exact Cognito hosted-UI hosts this CLI actually talks to (the Cognito domain is never a
+  `vectros.ai` host, so it needed its own entry rather than the partner-API allow-list unchanged —
+  and a broad `*.amazoncognito.com` suffix was deliberately rejected as too wide: that apex is
+  AWS's shared namespace for every Cognito user pool of every AWS customer, not a Vectros-owned
+  one); `VECTROS_COGNITO_REGION` is checked against an AWS-region shape before it is ever interpolated
+  into a URL. Only affects anyone who has run `vectros login` and does not use
+  `--token`/`VECTROS_BOOTSTRAP_TOKEN`.
+
+  **This narrows the vector; it does not close it against an attacker with unconstrained
+  environment control.** `VECTROS_ALLOW_INSECURE_BASE_URL=1` still opts out of the new allow-list
+  (loudly — a warning is logged), same as the pre-existing partner-API base-url guard it mirrors —
+  so an attacker able to set `VECTROS_COGNITO_DOMAIN` can, in principle, also set that opt-out
+  variable in the same reach. The fix protects the common case (an env var landing without the
+  reach to also flip a second, differently-named one) but is not a guarantee against an attacker
+  who already controls the whole environment.
+- **A blueprint-authored free-text field with no character-set constraint could forge a fake
+  extra line, hide/reorder text, or otherwise misrepresent what `vectros bootstrap --blueprint`'s
+  pre-apply plan preview AND its identity-disclosure/confirmation prompt show an operator before
+  they approve a real mint** — a raw newline/CR, an ANSI escape sequence, a Unicode line/paragraph
+  separator, a bidi-override/isolate/mark character, or an invisible/zero-width character embedded
+  in a value like a role's `allowedActions`/`dataScope`, a declared identity's `externalId`
+  (printed immediately before the "Apply this plan?" gate), or a blueprint's own `name`/
+  `contextName` could make the rendered plan (or the confirmation prompt itself) show something
+  other than what would actually be provisioned. **A separate, stronger check now also closes the
+  HOMOGLYPH class for an issuer's `issuer`/`jwksUri`/`userinfoUri`** — a Unicode look-alike domain
+  (e.g. a Cyrillic character standing in for a Latin one), invisible to any character blocklist —
+  by requiring those three fields to be printable-ASCII `https://` URLs whose AUTHORITY contains
+  only letters, digits, dot, dash, and an optional port (no userinfo, no percent-encoding, no
+  non-ASCII host); an internationalized domain must be supplied in its already-punycode (`xn--…`)
+  form. `http://` is explicitly rejected — the platform hard-refuses a non-`https` issuer at
+  registration, so accepting it here would repeat this ecosystem's own "lints clean, then 400s at
+  apply" anti-pattern for the exact field this check exists to catch problems in beforehand.
+
+  Requires **`@vectros-ai/blueprints@0.19.0`** (a MINOR bump, not patch — this narrows what the
+  library accepts, which is a breaking change for a validation library's published contract, even
+  though this repo's own blueprints are unaffected; see that package's own CHANGELOG entry for the
+  full field list, the named residuals of the URL check — a trailing-dot host and a bare IPv4
+  literal still pass, a bracketed IPv6 literal is rejected as an accepted side effect — and,
+  importantly, what is deliberately NOT covered — length is still unbounded, and the homoglyph
+  class stays open for non-URL fields like `name`/`contextName`/`fieldId`, since no enumerable
+  blocklist can close it there the way a positive URL-authority grammar can for a URL). The schema
+  closes both classes at parse time, once, for every current and future rendered surface, rather
+  than requiring each renderer to sanitize its own inputs. This preview's own per-field
+  sanitization (`jwksUri`/`userinfoUri`/`issuer`/`capturedClaims`, added in the previous entry
+  below) stays in place as a second line of defense for a caller that reaches `buildPlan` without
+  going through the parser — which is how every bundled/first-party blueprint (`--blueprint
+  task-management`, etc.) is loaded today.
+- **The plan preview for `vectros bootstrap --blueprint` omitted an issuer's trust-anchor
+  fields.** `jwksUri` (whoever controls it can mint identities the platform accepts) and, when
+  set, `userinfoUri` (fetched with the presented token as bearer) were never rendered — an
+  operator approving the plan for a pack declaring a malicious issuer saw its context and a
+  self-signup policy count, never the field that actually decides trust. Both are now always
+  disclosed, and a self-signup policy is now listed by its actual `signupType→roleId` pairing
+  instead of a bare count, matching the standard the preview already applies to captured
+  identity-provider claims.
+
+### Fixed
+
+- **A degraded credential store (file-backed, not your OS keychain) now warns — at write time,
+  and now at read time too — for BOTH ways this can be a fixable install accident, not just
+  one.** Previously: the optional `@napi-rs/keyring` package loading but being BROKEN (a
+  version/ABI mismatch, a corrupt native binary, an unrecognised module shape) already warned;
+  but the package being entirely ABSENT was always treated as an ordinary, nothing-to-fix
+  platform limitation — even on a platform/arch this CLI ships a prebuilt native binary for,
+  where the only way to end up without it is an npm install that silently skipped the optional
+  dependency. Both throw the identical `MODULE_NOT_FOUND` error, so telling them apart needed a
+  new check: whether a prebuilt is actually known to exist for the current `process.platform`/
+  `process.arch`, read from `@napi-rs/keyring`'s own published platform matrix — consulted
+  regardless of what the underlying failure looks like, not only for a recognised
+  `MODULE_NOT_FOUND`-shaped error (a genuinely-unsupported platform's own failure can carry no
+  error code at all, and every other error/code was previously treated as an install accident
+  unconditionally, which produced permanent, un-fixable "try reinstalling" noise on exactly the
+  platforms this feature must stay silent on). Now, a write about to land in the weaker store,
+  or a read of an entry already stamped for the OS keychain, prints one warning naming the
+  actual cause and the remedy on EITHER fixable path — install failure or silent absence —
+  while a genuinely-unsupported platform/arch stays quiet, whatever shape its failure takes.
+  **One accepted, disclosed residual:** this can't distinguish glibc from musl on Linux — `arm`
+  and `riscv64` each have a real GNU-libc prebuilt (so a glibc machine there is fully covered),
+  but neither has a MUSL prebuilt, and this check cannot tell the two libcs apart. A musl
+  machine on `arm`/`riscv64` will still get an unnecessary warning naming a remedy that won't
+  help — a false positive, the direction this control is meant to err in, not a silent miss.
+- **`bootstrap --rotate` could no longer recover once the local key record it needs was itself
+  the thing missing.** `--rotate` revoked a prior key only by a `keyId` read from this machine's
+  own local record — so when that record was lost (the exact situation `--rotate` exists to
+  recover from), nothing was revoked, the subsequent mint hit the same already-exists response,
+  and the CLI re-threw the identical error telling the caller to run `--rotate` — which they just
+  had. `--rotate` now falls back to resolving the key to revoke server-side (listing this
+  principal's active keys in the context and matching by name) when no local record exists. The
+  error message for the case that still can't be resolved now points at `vectros key list` /
+  `vectros key revoke` instead of repeating the same `--rotate` advice a second time.
+- **Any verb (not just credential minting) could abort the whole process with a native Windows
+  crash instead of the CLI's own exit code.** Every verb ended with `process.exit(await
+  runVerb(...))`; on Windows, a `fetch` still settling when `process.exit()` runs races libuv and
+  aborts the process, printing an `Assertion failed` line and replacing the real exit code with
+  `127` — which reads to a script, CI job, or wrapping agent as "command not found" rather than as
+  the CLI's own, already-printed, correctly-diagnosed failure (a bad `--context`, a suspended
+  member, an expired/invalid bearer, and so on). Every verb now sets `process.exitCode` and lets
+  the event loop drain naturally instead of hard-exiting, the same idiom `role`/`access` already
+  used for their own top-level exit.
+
+  **A related hazard was introduced by this conversion itself, and closed in the same pass —
+  not a pre-existing bug.** A shared helper, `parseTenantFlag()`, validates `--tenant` for 24 call
+  sites (`role`, `access`, `scripts`, `issuers`, `key`, `identity list-all`) and used to call
+  `process.exit(2)` directly: an unconditional stop from any call-stack depth, so no released
+  version could ever fall through past it. Converting the helper to the same `process.exitCode`
+  idiom broke that guarantee, because `exitCode` only unwinds the helper's own stack frame — a
+  caller that didn't check it after calling the helper would silently continue into the real
+  command with an invalid `--tenant` (defaulting to the **live** tenant, since `undefined` is also
+  this helper's valid "no `--tenant` given" result). All 24 call sites were audited and given an
+  explicit check immediately after the call, so no release ever shipped the fall-through — but it
+  is why this entry calls it out as a hazard of the refactor, not a latent defect the refactor
+  happened to discover.
+
+- **Eight source comments named internal backend classes/methods, or an internal gotcha filename,
+  by name** (`src/commands/issuers.ts`, `src/loader.ts` x3, `src/scope-gate.ts`, `src/scope-grammar.ts`,
+  `src/keyring.ts`, `src/os-keychain.ts`). This package has no GitHub source mirror, but `dist/`'s
+  sourcemaps embed the original source comments verbatim, so all eight shipped in every npm
+  tarball. Reworded to describe the mechanism without the identifier; no behavioral change.
+
+- **Six more shipped sources named a sibling package by monorepo-relative path or an internal
+  process stage** (`src/base-url.ts`'s doc comment, `src/scope-gate.ts` x3 — a backend method
+  name and two sibling-package references, one of them also a monorepo path —
+  `THIRD-PARTY-NOTICES.md`'s generation note naming an internal build-script path, and
+  `src/harness.ts`'s "the Tier-2 panel caught three times" wording) — found by a post-merge
+  audit. All reworded to describe the mechanism/sibling generically, keeping the substantive
+  rationale; no behavioral change.
+
+- **`scripts delete`'s pre-delete warning no longer claims the platform doesn't check whether a
+  live trigger rule still references the version being deleted.** The platform now refuses that
+  delete (409, naming the offending rule) instead of silently allowing it; the warning described
+  the older, unguarded behavior. No behavior changed — the delete itself already surfaced whatever
+  the platform returned either way; only the pre-emptive warning text was stale.
+
+### Docs
+
+- **`vectros issuers register`/`update`'s flag tables now document three refusal conditions
+  those commands can hit.** `--jwks-uri`/`--userinfo-uri` must be `https://` (an `http://` value
+  is refused with 400); a tenant is capped at 50 registered issuers; and a `--self-signup-policy`
+  naming a role that authors, updates, or deletes scripts is refused. No behavior changed — the
+  CLI already surfaced whatever the platform returned; the tables just didn't mention these yet.
+
 ## 0.21.0 — 2026-09-07
 
 ### Added
@@ -326,7 +512,7 @@ This project adheres to [Semantic Versioning](https://semver.org).
   install path) used to print only on `--no-merge` / a declined / a failed
   merge — a successful auto-merge silently hid it; it's now shown there too.
 - Scrubbed internal issue/MR references, review-process citations, and
-  backend class names out of `packages/cli`'s comments — visible in the
+  backend class names out of this package's comments — visible in the
   published npm package's sourcemaps to anyone who reads mapped source.
   Comment-only; no behavior change.
 - **Keyring secret-store hardening.** A 0-byte salt file removed by

package/README.md

@@ -174,8 +174,8 @@ 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), `--captured-claim <name>` (repeatable), `--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. |
-| `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`, `--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`. |
+| `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), `--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. |
+| `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`, `--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. |
 | `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 and captured claims. |
@@ -311,12 +311,10 @@ rejects. Supersede a version by pushing a new one.
 the rule that wanted it still unresolvable. `--tenant` defaults to `live`; pass `--tenant test` to
 reach the versions a `blueprint-test --tenant test` run created.
 
-⚠️ **`delete` is not reference-checked.** Nothing verifies whether a trigger rule still points at the
-version being removed, and the two outcomes differ: a rule pinned to that version fails on every
-subsequent firing, while a rule on `version: latest` silently resolves to the PREVIOUS version and
-carries on running older code with nothing to indicate it. This CLI has no verb that lists trigger
-rules, so it cannot answer that question for you — check against the API before removing a version a
-rule may still use.
+⚠️ **`delete` is permanent — the stored source is the only copy.** The platform refuses the delete
+(409, naming the rule) if a trigger rule still references the version being removed — directly, or
+via `version: latest` when the version is the current newest of its name — so it either succeeds
+cleanly or is refused with an explanation, never silently.
 
 A blueprint can ship a script instead of pushing one — see `scripts:` in
 [`@vectros-ai/blueprints`](https://www.npmjs.com/package/@vectros-ai/blueprints). An apply is

package/THIRD-PARTY-NOTICES.md

@@ -4,9 +4,8 @@
 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 `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
+This file is GENERATED from `tsup.config.ts`'s `noExternal` list by an internal build
+script. Do not edit it by hand. CI fails if it is stale, because a
 notices file that silently drifts is worse than none: it asserts a compliance that
 nobody checked.