@kitsy/cnos-docs 1.9.2 → 1.11.0

package/docs/api/runtime.mdx

@@ -37,6 +37,8 @@ The runtime currently exposes:
 - `cnos.log(message)`
 - `cnos.loadProjection(path)`
 - `cnos.registerRuntimeProvider(namespace, provider)`
+- `cnos.registerSecretVaultProvider(factory)`
+- `cnos.registerSecretVaultProviders(factories)`
 - `cnos.refreshSecrets()`
 - `cnos.refreshSecret(key)`
 
@@ -111,6 +113,20 @@ cnos.registerRuntimeProvider('request', (key) => {
 
 That lets server-side derived values depend on live request, session, or app-framework context without adding a second config layer.
 
+## Secret Vault Providers
+
+Vault selection is declared in `.cnos/cnos.yml`; runtime code only declares which provider implementations were compiled into the bundle.
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createGcpSecretManagerVaultProvider } from '@kitsy/cnos-vault-gcp-secret-manager';
+
+cnos.registerSecretVaultProvider(createGcpSecretManagerVaultProvider());
+await cnos.ready();
+```
+
+Provider packages and batteries-included wrappers should register capabilities before `ready()`. CNOS does not dynamically load provider packages from manifest config.
+
 ## Typed values
 
 CNOS values are not limited to strings. If the underlying config stores numbers, booleans, arrays, or objects, runtime reads return those values as-is.

package/docs/cli/doctor.mdx

@@ -1,16 +1,18 @@
----
-title: cnos doctor
-description: Run diagnostics across workspaces, exports, and security rules.
----
-
-# cnos doctor
-
-```bash
-cnos doctor
-cnos doctor --json
-cnos doctor --fix-secret-env-mappings
-```
-
-The security diagnostics now flag explicit `secret.*` env mappings as a risk because they enable plaintext secret emission into private env surfaces.
-
-If those mappings were added by mistake, `cnos doctor --fix-secret-env-mappings` removes them from `envMapping.explicit` in one shot and then reruns diagnostics.
+---
+title: cnos doctor
+description: Run diagnostics across workspaces, exports, and security rules.
+---
+
+# cnos doctor
+
+```bash
+cnos doctor
+cnos doctor --json
+cnos doctor --fix-secret-env-mappings
+```
+
+The security diagnostics now flag explicit `secret.*` env mappings as a risk because they enable plaintext secret emission into private env surfaces.
+
+If those mappings were added by mistake, `cnos doctor --fix-secret-env-mappings` removes them from `envMapping.explicit` in one shot and then reruns diagnostics.
+
+When manifest `schema:` entries exist, `cnos doctor` also points to `cnos spec doctor` for spec-vs-config coverage and guided remediation.

package/docs/cli/spec.mdx

@@ -0,0 +1,75 @@
+---
+title: cnos spec
+description: Author and inspect CNOS config specs stored under schema.
+---
+
+# cnos spec
+
+`cnos spec` manages manifest-global config specification entries stored under `schema:` in `.cnos/cnos.yml`.
+
+Use `cnos define`, `cnos value set`, and `cnos secret set` for concrete config values and secret refs.
+
+## Commands
+
+```bash
+cnos spec list
+cnos spec show value.server.port
+cnos spec set value.server.port --type number --required --summary "HTTP server port"
+cnos spec delete value.legacy.flag
+cnos spec doctor
+```
+
+## list
+
+```bash
+cnos spec list
+cnos spec list --prefix value.server.
+```
+
+## show
+
+```bash
+cnos spec show value.server.port
+cnos spec show value.server.port --json
+```
+
+## set
+
+`cnos spec set` supports two modes:
+
+- Non-interactive: pass one or more field flags.
+- Interactive: no field flags in a TTY.
+
+Examples:
+
+```bash
+cnos spec set value.server.port --type number --required --summary "HTTP server port"
+cnos spec set value.app.stage --enum '["local","stage","prod"]'
+cnos spec set value.legacy.flag --clear-deprecated
+```
+
+Field flags use JSON-first parsing for `--default`, `--example`, and `--enum`.
+
+For `secret.*` keys, `--default`, `--example`, and `--enum` are rejected to avoid plaintext secret material in the manifest.
+
+## delete
+
+```bash
+cnos spec delete value.legacy.flag
+cnos spec remove value.legacy.flag --json
+```
+
+## doctor
+
+```bash
+cnos spec doctor
+cnos spec doctor --json
+cnos spec doctor --fill-missing
+cnos spec doctor --review-all
+```
+
+`--fill-missing` and `--review-all` are interactive write modes. They currently:
+
+- require a TTY,
+- require a writable local root (remote roots are read-only),
+- reject `--json`.

package/docs/guides/go-runtime.mdx

@@ -0,0 +1,206 @@
+---
+title: Go Runtime
+description: Use CNOS directly from Go services through projections, native .cnos resolution, and Git-backed remote roots.
+---
+
+# Go Runtime
+
+CNOS now ships a first-party Go runtime client in [`packages/go`](https://github.com/kitsyai/cnos/tree/main/packages/go).
+
+The Go client reads the same runtime bootstrap contracts that the Node runtime already understands:
+
+- `__CNOS_GRAPH__`
+- `__CNOS_PROJECTION__`
+- explicit `.cnos-server.json`
+- autodiscovered `.cnos-server.json` next to `.cnosrc.yml`
+
+That means a Go service can consume CNOS values and secrets directly without dropping back to `cnos build env -> .env`.
+
+When no projection is present, the Go runtime now falls back to native authoring-time resolution from `.cnos/` or `cnos/`. That path understands:
+
+- `.cnosrc.yml` anchor discovery
+- `git+https://...#ref` and `git+ssh://...#ref` remote roots
+- `.cnos-workspace.yml`
+- workspace inheritance and optional global roots
+- profile activation and inheritance
+- filesystem values and secrets
+- dotenv layers
+- process env mappings
+- public promotion
+- runtime-derived values
+- manifest vault mappings for environment and local vault secrets
+
+## Build the projection
+
+For deployment or local packaging:
+
+```bash
+cnos build server --profile prod --to .cnos-server.json
+```
+
+For process bootstrap during development:
+
+```bash
+cnos run -- ./your-go-service
+```
+
+## Import the runtime
+
+Current module path:
+
+```go
+import cnos "github.com/kitsyai/cnos/packages/go"
+```
+
+Then load the runtime:
+
+```go
+runtime, err := cnos.Load(cnos.Options{})
+if err != nil {
+	panic(err)
+}
+```
+
+Or use the package-level singleton for the closest Node-style runtime flow:
+
+```go
+if err := cnos.Ready(); err != nil {
+	panic(err)
+}
+
+value, ok, err := cnos.Read("value.app.version")
+if err != nil {
+	panic(err)
+}
+_ = value
+_ = ok
+```
+
+`Load()` checks sources in this order:
+
+1. `ProjectionData` passed through `LoadProjection`
+2. explicit path from `cnos.Options{ProjectionPath: ...}`
+3. `__CNOS_GRAPH__`
+4. `__CNOS_PROJECTION__`
+5. `.cnos-server.json` in the current working directory
+6. `.cnos-server.json` beside a discovered `.cnosrc.yml`
+7. native authoring-time resolution from `cnos.Options{Root: ...}` or a discovered `.cnosrc.yml`
+
+If the process already has `__CNOS_GRAPH__`, `__CNOS_PROJECTION__`, or a nearby `.cnos-server.json`, the package singleton bootstraps automatically and `Ready()` is optional.
+
+## Read values and secrets
+
+```go
+port, _, err := runtime.Value("server.port")
+if err != nil {
+	panic(err)
+}
+
+token, _, err := runtime.Secret("app.token")
+if err != nil {
+	panic(err)
+}
+```
+
+The Go runtime reconstructs the same logical keys used in CNOS:
+
+- `value.*`
+- `secret.*`
+- `public.*`
+- `meta.profile`
+- `meta.workspace`
+- `meta.cnos_version`
+
+Inspect/provenance is also available directly in Go:
+
+```go
+inspect, err := runtime.Inspect("value.app.version")
+if err != nil {
+	panic(err)
+}
+_ = inspect
+```
+
+## Derived values stay live
+
+Runtime-dependent derived formulas in the server projection are evaluated at read time, not frozen during build.
+
+Example CNOS config:
+
+```yaml
+app:
+  origin:
+    $derive: "https://${value.app.host}:${process.env.PORT}"
+```
+
+In Go:
+
+```go
+origin, _, err := runtime.Value("app.origin")
+if err != nil {
+	panic(err)
+}
+```
+
+If `PORT` changes in the host process, the next read re-evaluates the formula.
+
+## Custom runtime namespaces
+
+Custom server-only runtime namespaces work the same way as in Node. Register a provider for any namespace that was declared in the CNOS manifest and carried into the server projection.
+
+```go
+host := ""
+
+if err := runtime.RegisterRuntimeProvider("request", func(path string) any {
+	if path == "headers.host" && host != "" {
+		return host
+	}
+	return nil
+}); err != nil {
+	panic(err)
+}
+```
+
+The built-in `process.*` namespace covers `env.*`, `cwd`, `platform`, `arch`, and `pid`. `process.node.version` is still Node-only.
+
+## Secret hydration
+
+The Go runtime supports built-in secret-ref providers used by server projections:
+
+- `environment`
+- `github-secrets`
+- `local`
+
+Remote providers such as GCP Secret Manager, AWS Secrets Manager, HashiCorp Vault, and Azure Key Vault are compiled into the Go binary by registering provider factories:
+
+```go
+runtime, err := cnos.Load(cnos.Options{
+	SecretVaultProviders: []cnos.SecretVaultProviderFactory{gcpFactory},
+})
+```
+
+The manifest remains the configuration source for which named vault uses which provider. Go does not dynamically load provider packages from `.cnos.yml`.
+
+For local vaults, the Go client reuses the same CNOS auth conventions:
+
+- `__CNOS_VAULT_KEY_<VAULT>__`
+- `~/.cnos/secrets/sessions/<vault>.json`
+- `keychain:cnos/<vault>`
+- `CNOS_SECRET_PASSPHRASE_<VAULT>`
+- `CNOS_SECRET_PASSPHRASE`
+
+It also understands the encrypted secret payload generated by:
+
+```bash
+cnos run --auth -- ./your-go-service
+```
+
+That lets a Go process start with already-resolved secret values even when it is not re-authenticating to the local vault itself.
+
+## Current limits
+
+The remaining Go-specific gaps are:
+
+- browser/public runtime behavior
+
+Use it as the server-runtime companion to `cnos build server`, `cnos run`, local `.cnos/` authoring flows, and Git-backed shared config repos.

package/docs/guides/secrets.mdx

@@ -46,3 +46,21 @@ By default:
 - repo files store only refs
 - local secret material stays outside the repo
 - reads are masked unless `--reveal` is explicitly requested
+
+Remote provider packages are compiled into the runtime and selected through `vaults.<name>.provider` in the manifest. CNOS does not dynamically load provider packages from config.
+
+```yaml
+vaults:
+  prod-gcp:
+    provider: gcp-secret-manager
+    auth:
+      method: iam
+      config:
+        projectId: acme-prod
+    fallback:
+      - provider: environment
+        mapping:
+          DB_PASSWORD: db.password
+```
+
+See [Vault Providers](/guides/vault-providers) for the provider package contract, conformance testkit, and security rules.

package/docs/guides/vault-providers.mdx

@@ -0,0 +1,263 @@
+---
+title: Vault Provider Packages
+description: Build and test compiled-in CNOS secret vault providers.
+---
+
+# Vault Provider Packages
+
+Remote vault providers are compiled into the application runtime. CNOS never loads provider packages dynamically from `.cnos/cnos.yml`.
+
+## Package names
+
+Official providers use this package shape:
+
+- `@kitsy/cnos-vault-gcp-secret-manager`
+- `@kitsy/cnos-vault-aws-secrets-manager`
+- `@kitsy/cnos-vault-hashicorp`
+- `@kitsy/cnos-vault-azure-key-vault`
+- `@kitsy/cnos-vault-firebase-secrets`
+
+Each package must export a factory named `create<Vendor>VaultProvider()`. The factory returns a `SecretVaultProviderFactory` whose `provider` field exactly matches the manifest provider name.
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createGcpSecretManagerVaultProvider } from '@kitsy/cnos-vault-gcp-secret-manager';
+
+cnos.registerSecretVaultProvider(createGcpSecretManagerVaultProvider());
+await cnos.ready();
+```
+
+## Manifest contract
+
+Provider selection belongs in config:
+
+```yaml
+vaults:
+  prod-gcp:
+    provider: gcp-secret-manager
+    auth:
+      method: iam
+      config:
+        projectId: acme-prod
+    fallback:
+      - provider: environment
+        mapping:
+          DB_PASSWORD: db.password
+```
+
+Secret refs should normally inherit from the named vault:
+
+```yaml
+db:
+  password:
+    vault: prod-gcp
+    ref: db.password
+```
+
+Do not set a different `provider` on a ref that also names a vault. CNOS rejects provider/vault mismatches so Node, Go, and projections all agree.
+
+## Runtime contract
+
+Every provider must implement the `SecretVaultProvider` interface:
+
+- `authenticate(authConfig)` resolves credentials supplied by CNOS.
+- `batchGet(refs)` is the startup and refresh path.
+- `get(ref)` exists for compatibility and narrow single-ref use, but provider tests must prove startup and `refreshSecrets()` do not call it.
+- `set(ref, value)` and `delete(ref)` may be writable or may reject. Declare the expected capability in testkit setup.
+- `list()` returns known refs when the backing platform supports listing.
+- `healthCheck()` is optional for remote providers.
+
+Startup hydration and full refresh are batch-only. Individual application reads use the CNOS in-memory cache and must not perform remote I/O.
+
+## Auth and projection safety
+
+Provider auth should prefer platform identity:
+
+- GCP: Application Default Credentials or attached service account.
+- AWS: IAM role or standard AWS credential chain.
+- Azure: managed identity or default credential chain.
+- HashiCorp Vault: token sources such as `env:`, `file:`, or keychain.
+- Firebase: direct provider support plus explicit `environment` fallback for injected secrets.
+
+Server projections may include safe metadata such as `projectId`, `region`, `endpoint`, `address`, `namespace`, or `tenant`. They must not include raw secrets, private keys, bearer tokens, credential blobs, or client secrets. CNOS sanitizes projected `auth.config`, but provider authors should design manifest config so credential material is referenced by source (`env:NAME`, `file:PATH`, `keychain:NAME`) rather than stored inline.
+
+## Conformance tests
+
+Provider packages should use `@kitsy/cnos-vault-testkit`:
+
+```ts
+import {
+  defineSecretVaultProviderConformanceSuite,
+  defineSecretVaultRuntimeConformanceSuite,
+} from '@kitsy/cnos-vault-testkit';
+
+defineSecretVaultProviderConformanceSuite('gcp-secret-manager', () => ({
+  factory: createGcpSecretManagerVaultProvider(),
+  definition,
+  auth,
+  refs,
+}));
+
+defineSecretVaultRuntimeConformanceSuite('gcp-secret-manager', () => ({
+  factory: createGcpSecretManagerVaultProvider(),
+  vaultId: 'prod-gcp',
+  definition,
+  refs,
+  processEnv,
+}));
+```
+
+The shared suite verifies provider auth, batch reads, missing refs, runtime startup hydration, projection bootstrap, refresh batching, safe projection metadata, and explicit environment fallback behavior.
+
+## Google Secret Manager
+
+Install and register the compiled-in provider:
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createGcpSecretManagerVaultProvider } from '@kitsy/cnos-vault-gcp-secret-manager';
+
+cnos.registerSecretVaultProvider(createGcpSecretManagerVaultProvider());
+await cnos.ready();
+```
+
+Use `auth.method: iam` and let the official Google SDK resolve Application Default Credentials or an attached service account:
+
+```yaml
+vaults:
+  prod-gcp:
+    provider: gcp-secret-manager
+    auth:
+      method: iam
+      config:
+        projectId: acme-prod
+    mapping:
+      db-password: db.password
+```
+
+CNOS resolves `secret.db.password` from `projects/acme-prod/secrets/db-password/versions/latest`. Set `auth.config.version` to read a pinned version, or `auth.config.location` for regional Secret Manager resources. A full ref such as `projects/acme-prod/secrets/db-password/versions/5` is also accepted.
+
+## Firebase Secrets
+
+Install and register the compiled-in provider:
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createFirebaseSecretsVaultProvider } from '@kitsy/cnos-vault-firebase-secrets';
+
+cnos.registerSecretVaultProvider(createFirebaseSecretsVaultProvider());
+await cnos.ready();
+```
+
+Firebase Secrets are backed by Google Secret Manager. Use `auth.method: iam` and let the official Google SDK resolve Application Default Credentials or an attached service account:
+
+```yaml
+vaults:
+  prod-firebase:
+    provider: firebase-secrets
+    auth:
+      method: iam
+      config:
+        projectId: acme-prod
+    mapping:
+      DB_PASSWORD: db.password
+    fallback:
+      - provider: environment
+        mapping:
+          DB_PASSWORD: db.password
+```
+
+CNOS resolves `secret.db.password` from `projects/acme-prod/secrets/DB_PASSWORD/versions/latest`. Set `auth.config.version` to read a pinned version, or `auth.config.location` for regional Secret Manager resources. A full ref such as `projects/acme-prod/secrets/DB_PASSWORD/versions/5` is also accepted.
+
+Firebase and Google Cloud Functions can inject secrets as environment variables. Model that as an explicit `environment` fallback in the vault definition; CNOS never silently falls back to env when a remote provider fails.
+
+## AWS Secrets Manager
+
+Install and register the compiled-in provider:
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createAwsSecretsManagerVaultProvider } from '@kitsy/cnos-vault-aws-secrets-manager';
+
+cnos.registerSecretVaultProvider(createAwsSecretsManagerVaultProvider());
+await cnos.ready();
+```
+
+Use `auth.method: iam` and let AWS SDK v3 resolve credentials from IAM roles, web identity, environment credentials, or the standard AWS provider chain:
+
+```yaml
+vaults:
+  prod-aws:
+    provider: aws-secrets-manager
+    auth:
+      method: iam
+      config:
+        region: us-east-1
+    mapping:
+      db/password: db.password
+```
+
+CNOS resolves `secret.db.password` from the AWS secret ID `db/password`. Set `auth.config.versionId` or `auth.config.versionStage` for pinned or staged reads. Secret refs may also be direct AWS secret names or ARNs when no mapping is required.
+
+## HashiCorp Vault
+
+Install and register the compiled-in provider:
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createHashicorpVaultProvider } from '@kitsy/cnos-vault-hashicorp';
+
+cnos.registerSecretVaultProvider(createHashicorpVaultProvider());
+await cnos.ready();
+```
+
+Use `auth.method: token` and source the Vault token from env, file, or keychain. CNOS resolves the token and passes it to Vault as `X-Vault-Token`:
+
+```yaml
+vaults:
+  prod-vault:
+    provider: hashicorp-vault
+    auth:
+      method: token
+      token:
+        from:
+          - env:VAULT_TOKEN
+      config:
+        address: https://vault.example.com
+        mount: secret
+        namespace: admin/team-a
+        version: 2
+    mapping:
+      db/password#password: db.password
+```
+
+For KV v2, CNOS reads `secret.data.db/password` and extracts the `password` field. Use `path#field` refs or mapping keys to select fields from a Vault secret object. Set `auth.config.version: 1` for KV v1 mounts, and `auth.config.path` to apply a shared path prefix.
+
+## Azure Key Vault
+
+Install and register the compiled-in provider:
+
+```ts
+import cnos from '@kitsy/cnos';
+import { createAzureKeyVaultProvider } from '@kitsy/cnos-vault-azure-key-vault';
+
+cnos.registerSecretVaultProvider(createAzureKeyVaultProvider());
+await cnos.ready();
+```
+
+Use `auth.method: iam` and let Azure Identity resolve credentials from managed identity, workload identity, environment credentials, or the standard `DefaultAzureCredential` chain:
+
+```yaml
+vaults:
+  prod-azure:
+    provider: azure-key-vault
+    auth:
+      method: iam
+      config:
+        vaultUrl: https://acme-prod.vault.azure.net
+        tenantId: 00000000-0000-0000-0000-000000000000
+    mapping:
+      db-password: db.password
+```
+
+CNOS resolves `secret.db.password` from the Azure secret name `db-password`. Set `auth.config.version` for a pinned version, or use a full Azure secret URL such as `https://acme-prod.vault.azure.net/secrets/db-password/version-id` as the ref when no mapping is required.

package/docs/reference/manifest.mdx

@@ -18,3 +18,23 @@ Key sections:
 - `writePolicy`
 
 Use the main repo spec for the exhaustive schema until this reference grows into the full field-by-field version.
+
+## Vaults
+
+`vaults` declare named secret backends. Secret refs can name a vault and omit `provider`; CNOS resolves the provider from the vault definition.
+
+```yaml
+vaults:
+  prod-gcp:
+    provider: gcp-secret-manager
+    auth:
+      method: iam
+      config:
+        projectId: my-prod-project
+    fallback:
+      - provider: environment
+        mapping:
+          DB_PASSWORD: db.password
+```
+
+Fallbacks are explicit and ordered. CNOS never silently falls back to environment variables unless a fallback provider is declared.

package/manifest.yml

@@ -19,6 +19,8 @@ sidebar:
     items:
       - path: guides/backend
         label: Backend Projects
+      - path: guides/go-runtime
+        label: Go Runtime
       - path: guides/frontend-vite
         label: Frontend with Vite
       - path: guides/frontend-webpack
@@ -41,6 +43,8 @@ sidebar:
         label: Derived Values
       - path: guides/secrets
         label: Secrets and Vaults
+      - path: guides/vault-providers
+        label: Vault Providers
       - path: guides/migration
         label: Migrating from .env
       - path: guides/generated-env-files
@@ -67,6 +71,8 @@ sidebar:
         label: cnos secret
       - path: cli/define
         label: cnos define
+      - path: cli/spec
+        label: cnos spec
       - path: cli/list
         label: cnos list
       - path: cli/read

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitsy/cnos-docs",
-  "version": "1.9.2",
+  "version": "1.11.0",
   "description": "Source-of-truth CNOS documentation content for Astro Starlight and other static docs consumers.",
   "type": "module",
   "exports": {