@vectros-ai/cli 0.7.0 → 0.10.0

package/AUTHORING.md

@@ -142,8 +142,9 @@ accessProfile:
   allowedActions: [records:r, records:c, records:u, search:r, schemas:r]
   # dataScope binds the key to specific owners. Include `null` to ALSO grant
   # tenant-level (shared) records — without it the key sees ONLY the listed
-  # owners' records, not shared/seed data:
-  # dataScope: { orgId: [<org-uuid>, null] }
+  # owners' records, not shared/seed data. Keys are userId + namespaced scopes
+  # (scope:org, scope:client, ...):
+  # dataScope: { "scope:org": [<org-uuid>, null] }
 
 servicePrincipal:
   externalId: my-thing-sp   # stable; the principal the profile + key bind to
@@ -214,7 +215,7 @@ than one surface, so the surface disambiguates which lookup resolves the link):
 - fieldId: establishedByDecision
   fieldType: reference
   targetTypeName: decision      # the typeName it points at
-  targetSurface: record         # record | document | user | org | client (REQUIRED)
+  targetSurface: record         # record | document | user | a namespace (org, client, ...) — REQUIRED
   targetField: externalId       # the target's UNIQUE lookup to match (defaults to externalId)
   cardinality: one              # one (a single id) | many (an array of ids)
 ```

package/CHANGELOG.md

@@ -3,6 +3,142 @@
 All notable changes to `@vectros-ai/cli` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.10.0
+
+### Changed (breaking)
+
+- **Organization and client identities are now namespaces.** `org` and `client`
+  join any namespace you define (teams, projects, …), so the `identity` command
+  and ownership flags generalize:
+  - `identity create|list|get|delete --type <user|namespace>` — `user` for a
+    user, or a namespace (`org`, `client`, or one you define). `--type org` and
+    `--type client` keep working.
+  - `--scope <namespace>:<value>` (repeatable) replaces `--org <id>` on
+    `identity create`, `access grant`, and `join` — e.g. `--scope org:<id>`.
+  - Schema ownership in blueprints uses `scopes` instead of `orgId` / `clientId`,
+    and `--data-scope` keys use the `scope:<namespace>` form. The old `orgId` /
+    `clientId` keys are no longer accepted.
+
+### Added
+
+- **Keys are now kept in your OS credential store** (Windows Credential Manager,
+  Linux Secret Service) instead of an encrypted file, on machines that have one —
+  so a copy of your `~/.vectros` directory no longer gives up a key. Existing
+  secrets migrate automatically the first time each key is used. Where no store is
+  usable (a headless Linux box, or no prebuilt for the optional native package) the
+  encrypted file remains the fallback. Set `VECTROS_KEYRING_BACKEND=file` to opt
+  out. macOS keeps using the encrypted file for now. Note: `vectros bootstrap`
+  still writes its key as plain JSON to `~/.vectros/<pack>.key.json`, so treat
+  `~/.vectros` as a secret if you use it.
+- **The keyring is now a credential helper.** `keyring show --format raw` prints
+  the bare secret and is the contract other tools resolve through:
+  `@vectros-ai/mcp-server` 0.10.0+ runs it when `VECTROS_API_KEY` is unset, so a
+  key lives in the keyring instead of being copied into each tool's config. Set
+  `VECTROS_KEYRING_ALIAS` to target a specific entry.
+- **`vectros keyring doctor`** — a health check for the keyring: the active entry,
+  whether each secret is readable, where each lives, and which hold live keys.
+  Exits non-zero when it finds anything to fix; `--json` for scripts.
+- **`vectros keyring prune`** — drop orphaned entries (an index entry with no
+  stored secret). Narrow by design: an entry whose secret is merely unreadable or
+  locked is reported, never removed. `--dry-run` previews; `--force` skips the prompt.
+- **`vectros context list` now enumerates the whole tenant**, not just contexts you
+  have joined, with an `active`/`purging` status column. `--mine` limits it to the
+  contexts you hold an access profile in. Now account-owner-only (a sub-user reads a
+  single context with `context get`).
+- **`vectros key list --all-contexts`** — every active scoped key across all your
+  contexts and both tenants, the account-wide view a context-scoped `key list`
+  cannot show. Owner-only.
+- **Actionable error messages** for known server errors — the active-key limit
+  (enumerate → revoke → retry), a 403 (owner/scope), a 404 (`context list`) —
+  instead of the raw SDK error. Correlation id under `VECTROS_MCP_DEBUG`.
+- **`bootstrap` apply is now legible** — the preview states that apply is a
+  non-destructive reconcile, and each resource reports `created` vs `reconciled`.
+
+### Fixed
+
+- **Two `vectros` commands running at once can no longer lose each other's keyring
+  entries** — index updates now take a lock and queue instead of overwriting. A
+  process killed mid-write leaves a lock the next command clears automatically.
+- **`vectros keyring remove` refuses instead of silently stranding a key.** If it
+  cannot confirm the secret was deleted (a locked store), it declines and prints the
+  key id rather than discarding the only local record of a still-live key.
+- **`vectros join` now reports a key it had to abandon** — when a replaced key's
+  secret cannot be deleted, it prints that key's id and the `vectros key revoke`
+  command, the last time you will see the id.
+
+### Changed
+
+- The internal `--env` flag is no longer advertised in customer-facing output (help
+  text, examples, the post-login hint). It remains fully functional; production is
+  the default.
+
+## 0.9.0
+
+### Added
+
+- **Ownership scopes across the provisioning verbs.** `role create` gains
+  `--data-scope <json>` to confine a role's clause to owned data (e.g.
+  `'{"userId":["${{ self.userId }}"]}'` for per-request "records I own", or
+  `'{"scope:org":["<orgId>", null]}'` for one org's data plus scope-less records).
+  `access grant` and `vectros join` gain `--org <orgId>` (and `access grant` the
+  general `--identity-overrides <json>`), placing the principal under an
+  organization for the context so its key can write org/team-scoped data — a
+  credential can only stamp ownership its identity carries.
+- **`vectros access explain`** — renders what a principal's binding actually
+  grants: the clause list plus a concrete access matrix (your private records, a
+  teammate's shared records, another team's, scope-less content, …) evaluated
+  under the documented matching rules — per-dimension match, AND across a
+  clause's keys, UNION across clauses, and the `null` opt-in for scope-less
+  items. Answers "who can see what?" before any data exists, and catches the
+  classic one-clause mis-authoring that silently denies teammates' shared
+  records.
+- **`vectros join` + the multi-principal keyring** — `vectros join <context>
+  (--role <r> | --actions <csv>) [--as me|usr_<id>] [--alias <name>]` enrolls a
+  principal in a context in one step: it grants the role, issues a scoped key,
+  and stores that key as a named keyring entry, then makes it the active
+  identity. Several identities can now live side by side. `vectros switch
+  <alias>` (or `vectros keyring use <alias>`) flips the active one; `vectros
+  keyring list` shows them all with the active one marked; `vectros keyring show
+  [--format env|raw]` reveals the active key (e.g. `--format env` prints
+  `VECTROS_API_KEY=…` to export into the MCP server); `vectros keyring remove
+  <alias>` drops one. Re-joining an alias whose key is still held is idempotent
+  (it re-activates without churning the key); it only rotates when the local
+  secret is missing.
+- **Keys are encrypted at rest** — keyring secrets are stored AES-256-GCM
+  encrypted under a machine-derived key, rather than in plaintext. (An OS-native
+  secret store is a planned follow-up for login/hardware-gated protection.)
+- **Bundled blueprints updated to `0.7.0`** — `agentic-sdlc` gains governed agent
+  memory (enroll with `vectros join agentic-sdlc --role member`), and the blueprint
+  format gains `accessProfile.identityOverrides` + per-seed `scopes`, which
+  `bootstrap`/`blueprint-test` apply. **Full detail in the `@vectros-ai/blueprints`
+  changelog** — this entry is an overview; the schema, role, and format specifics
+  live there.
+
+## 0.8.1 — 2026-07-10
+
+### Changed
+
+- **Dependency maintenance** — repinned the bundled `@vectros-ai/sdk` to `0.34.0`
+  (additive `scopes` read-back on record/document/folder responses, plus webhooks).
+  The CLI bundles the SDK into its published binary, so this is a rebuild against the
+  current SDK; no CLI behavior changes.
+
+## 0.8.0
+
+### Added
+
+- **Blueprint identity resolution** — a blueprint can now declare a top-level
+  `identities:` block (tenant-wide principals: `user`, `org`, or `client`) and reference
+  them with `${{ identities.<name> }}` tokens in ownership and data-scope positions
+  (schema `userId`/`orgId`/`clientId`, access-profile and role `dataScope`). At apply
+  time (`vectros bootstrap` / `vectros blueprint-test`) each declared identity is ensured
+  (idempotent by `externalId`) and every token is substituted with the principal's
+  resolved id — so a blueprint can provision data owned by, or a credential scoped to,
+  specific principals. `vectros blueprint validate` / `plan` accept an identity-using
+  blueprint offline (linting that every reference is declared) and defer resolution to
+  apply time; the plan preview discloses the identities that will be ensured. Declared
+  identities are tenant-global and are never removed by `blueprint-test` teardown.
+
 ## 0.7.0 — 2026-07-08
 
 ### Added

package/README.md

@@ -3,15 +3,17 @@
 [![npm](https://img.shields.io/npm/v/@vectros-ai/cli)](https://www.npmjs.com/package/@vectros-ai/cli)
 [![license](https://img.shields.io/npm/l/@vectros-ai/cli)](https://www.apache.org/licenses/LICENSE-2.0)
 
-The Vectros provisioning CLI — the `vectros` binary. Two command groups:
+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 keyring`** — hold several identities on one machine, pick which is active, and let other tools resolve keys from one place.
 
 ```bash
 npx -y @vectros-ai/cli bootstrap          # provision a credential
 npx -y @vectros-ai/cli blueprint --help   # the authoring commands
+npx -y @vectros-ai/cli keyring list       # the identities on this machine
 ```
 
 Every command has `--help`. The authoring loop is documented in
@@ -108,6 +110,76 @@ 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 keyring` — one home for your keys
+
+A machine can hold several Vectros identities (one per context or principal).
+The keyring stores them as named entries plus one **active** pointer, so you can
+switch between them without re-issuing keys. `vectros join <context>` adds an
+entry and activates it; `vectros switch <alias>` flips the active one.
+
+```bash
+vectros keyring list                 # the entries; * marks the active one
+vectros switch <alias>               # make <alias> active  (= keyring use)
+vectros keyring show                 # the active entry's fields + its key
+vectros keyring show --format raw    # JUST the secret, for scripts (see below)
+vectros keyring doctor               # is the keyring healthy? which keys are live?
+vectros keyring prune                # drop entries whose stored secret is gone
+vectros keyring remove <alias>       # drop one entry + its secret
+```
+
+These are local — no network, no auth. The index itself never holds a secret.
+
+**Where your keys are kept.** In your **OS credential store** (Windows Credential
+Manager, Linux Secret Service) where one is available, so they are protected by
+your OS login. Where none is — a headless Linux box with no Secret Service, or a
+platform with no prebuilt for the optional native package — the CLI falls back to
+an encrypted file under `~/.vectros/secrets` rather than failing. Be aware of what
+that fallback does and doesn't buy you: it protects a single stray `.enc` file, but
+its encryption key is derived from material stored alongside it, so anyone with a
+copy of your **whole `~/.vectros` directory** can decrypt it. Treat that directory
+as a secret in its own right. `vectros keyring doctor` tells you which store you
+are on and why; `VECTROS_KEYRING_BACKEND=file` forces the fallback (existing keychain keys keep
+working and move back to the file as you use them).
+
+On **macOS** the encrypted file is used for now. A Keychain item grants access to
+the application that created it and prompts for anything else — and the
+"application" here is the `node` binary running this CLI, which is not stable
+across installs. We expect that to put a password prompt in the startup path of
+any tool resolving a key unattended, which on a headless host nobody can answer.
+We have not yet verified it on real hardware, and would rather ship the honest
+fallback than a claim we haven't tested.
+
+Upgrading from an older CLI needs no action: an existing encrypted secret moves
+into the credential store the first time that key is used.
+
+**Resolving a key from another tool.** `keyring show --format raw` prints the bare
+secret and nothing else, which makes it a credential helper in the shape of
+`git credential` / `docker-credential-*` / `aws credential_process`:
+
+```bash
+export VECTROS_API_KEY=$(vectros keyring show --format raw)                      # active
+export VECTROS_API_KEY=$(vectros keyring show --format raw --alias support-bot)  # a specific entry
+```
+
+[`@vectros-ai/mcp-server`](https://www.npmjs.com/package/@vectros-ai/mcp-server)
+does this for you: leave `VECTROS_API_KEY` unset and it resolves the key from
+this keyring, so you don't paste a copy into its config. Exit codes: `0` secret
+printed, `2` no such (or no active) entry, `1` the entry exists but its secret
+can't be read.
+
+**When something's off**, `vectros keyring doctor` is the first stop — it shows
+which entry is active, whether each secret is readable, which entries are live
+keys (the ones that act on real data), and which store is holding them, exiting
+non-zero when it finds something to fix.
+
+`vectros keyring prune` drops entries whose secret is gone, but only where "gone"
+is knowable — that is, on the encrypted-file store. **Entries kept in the OS
+credential store are never pruned.** That store can't tell us "no such secret"
+apart from "couldn't read it right now", so a locked keychain would otherwise
+look like a keyring full of dead entries; deleting one would throw away the key
+id you need to revoke a key that may still be live. Use
+`vectros keyring remove <alias>` to drop one deliberately.
+
 ## The scope gate (the trust boundary)
 
 Blueprints are **untrusted input** (agent- or community-authored) and the
@@ -130,6 +202,13 @@ after the window resets, or split a large blueprint. See the
 - [`@vectros-ai/mcp-server`](https://www.npmjs.com/package/@vectros-ai/mcp-server) — the runtime this CLI provisions for.
 - [`@vectros-ai/blueprints`](https://www.npmjs.com/package/@vectros-ai/blueprints) — the curated use-case library the CLI applies.
 
+## Security & trust
+
+Vectros enforces per-customer, fail-closed isolation and least-privilege scoped keys, with a
+tamper-evident audit and version history. Customer-facing surfaces are hardened through extensive
+adversarial security review. For the full trust posture, drawn plainly with its boundaries, see the
+[compliance and trust guide](https://docs.vectros.ai/guides/operations-trust/compliance).
+
 ## License
 
 Apache-2.0. See the LICENSE file.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,117 @@
+# 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.
+
+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
+`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.
+
+Packages resolved at RUNTIME (ordinary dependencies) are not listed here — the
+consumer's own install carries their licenses.
+
+---
+
+## graceful-fs 4.2.11
+
+License: ISC
+
+```
+The ISC License
+
+Copyright (c) 2011-2022 Isaac Z. Schlueter, Ben Noordhuis, and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```
+
+## proper-lockfile 4.1.2
+
+License: MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2018 Made With MOXY Lda <hello@moxy.studio>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+## retry 0.12.0
+
+License: MIT
+
+```
+Copyright (c) 2011:
+Tim Koschützki (tim@debuggable.com)
+Felix Geisendörfer (felix@debuggable.com)
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in
+ all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ THE SOFTWARE.
+```
+
+## signal-exit 3.0.7
+
+License: ISC
+
+```
+The ISC License
+
+Copyright (c) 2015, Contributors
+
+Permission to use, copy, modify, and/or distribute this software
+for any purpose with or without fee is hereby granted, provided
+that the above copyright notice and this permission notice
+appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE
+LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```