@mccaskie-labs/workbench-config 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @mccaskie-labs/workbench-config
+
+## 0.1.0
+
+- First release: `workbenchEnv`, `defineConfig`, `workerSecret`, `sharedSecret`, `redact`, `redactAll`, the capabilities manifests (`gateway`, `config`, `ai`) with `capabilitySchema`, and the `workbench-config check` CLI.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @mccaskie-labs/workbench-config
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Configuration for apps built on Workbench, a private platform. Published publicly so Workbench projects can install it with no token; it is not supported for other uses.
+
+```sh
+npm install @mccaskie-labs/workbench-config zod
+```
+
+```ts
+import { z } from 'zod'
+import { defineConfig, workbenchEnv } from '@mccaskie-labs/workbench-config'
+
+const config = defineConfig({
+  WORKBENCH_GATEWAY_KEY: z.string().startsWith('wbk_'),
+  SITE_NAME: z.string().default('my-app'),
+})
+
+const stage = workbenchEnv(env)            // 'development' | 'staging' | 'production'; throws if WORKBENCH_ENV is missing
+const { WORKBENCH_GATEWAY_KEY } = config.parse(env)
+```
+
+| Export | What it does |
+| --- | --- |
+| `workbenchEnv(env)` | Reads `WORKBENCH_ENV`. Throws if it is missing or not one of the three environments. Never reads `NODE_ENV` |
+| `defineConfig(shape).parse(env)` | Validates the named variables with zod. An empty string counts as missing. Throws `WorkbenchConfigError` naming every bad variable; the error never holds a value |
+| `workerSecret(env, name)` | A Worker secret or variable by name; throws, naming it, if it is missing or empty |
+| `sharedSecret(binding, name?)` | Reads a Secrets Store binding; throws if it is empty |
+| `redact(value)`, `redactAll(text, secrets)` | `[redacted]` in place of a secret, for logs |
+| `capabilities`, `MANIFEST_VERSION`, `capabilitySchema` | The Workbench capabilities manifests and their schema. The JSON files are also at `@mccaskie-labs/workbench-config/capabilities/<component>.json` |
+| `DEFAULT_GATEWAY_URL` | `https://gateway.mccaskielabs.dev` |
+
+`npx workbench-config check [dir]` compares the variable names in `.dev.vars` with `.dev.vars.example` and prints names only.
+
+Runs on Node 24 and the Cloudflare Workers runtime. `zod` 4 is a peer dependency.

package/capabilities/ai.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "./schema.json",
+  "format": 1,
+  "component": "ai",
+  "title": "Claude through the Gateway",
+  "summary": "Text, structured output and streaming from Claude, metered against the project's budget. Apps never hold an Anthropic key.",
+  "status": "planned",
+  "surfaces": {
+    "gateway": ["POST /anthropic/v1/messages", "POST /anthropic/v1/messages/count_tokens"],
+    "package": ["createAi", "Ai.text", "Ai.structured", "Ai.stream", "Ai.budget", "createFakeAi"]
+  },
+  "config": [
+    {
+      "name": "WORKBENCH_GATEWAY_KEY",
+      "required": true,
+      "secret": true,
+      "environments": ["staging", "production"],
+      "description": "Project key with the ai scope, delivered as a Worker secret by gw_key_issue"
+    },
+    {
+      "name": "WORKBENCH_ENV",
+      "required": true,
+      "secret": false,
+      "environments": ["development", "staging", "production"],
+      "description": "Drives key checks; never NODE_ENV"
+    }
+  ],
+  "allowed": {
+    "aliases": [
+      { "alias": "claude-default", "provider": "anthropic", "default_model": "claude-sonnet-5-5" },
+      { "alias": "claude-best", "provider": "anthropic", "default_model": "claude-opus-5-5" },
+      { "alias": "claude-fast", "provider": "anthropic", "default_model": "claude-haiku-5-5" }
+    ],
+    "explicit_models": ["claude-sonnet-5", "claude-opus-5"],
+    "server_tools": ["web_search", "web_fetch", "code_execution"],
+    "required_headers": ["X-Workbench-Job"]
+  },
+  "limits": [
+    { "id": "ai.retry-attempts", "value": 3, "unit": "attempts", "per": "request", "enforced_by": "gateway" }
+  ],
+  "errors": [
+    { "code": "model_not_allowed", "http": 400, "retryable": false, "meaning": "Not an alias or an allowlisted model id" },
+    { "code": "budget_exceeded", "http": 402, "retryable": false, "meaning": "Enforced monthly budget reached" }
+  ],
+  "rules": [
+    { "id": "ai.no-partial-success", "kind": "must_not", "text": "Treat a refusal or a max_tokens truncation as a successful result.", "enforced_by": "types", "probe": "ai.text.truncation-throws" },
+    { "id": "ai.store-resolved-model", "kind": "must", "text": "Store the resolved model and request id with any output kept.", "enforced_by": "review", "probe": "ai.text.claude-default" },
+    { "id": "ai.aliases-only", "kind": "must", "text": "Ask for a Workbench alias (or an allowlisted explicit id), never an arbitrary model id.", "enforced_by": "gateway", "probe": "ai.model-not-allowed" }
+  ],
+  "examples": [
+    {
+      "id": "ai.example.text",
+      "title": "One-shot text",
+      "lang": "ts",
+      "probe": "ai.text.claude-default",
+      "code": "const ai = createAi({ key: env.WORKBENCH_GATEWAY_KEY, env: workbenchEnv(env) })\nconst r = await ai.text({ model: 'claude-default', job: 'article.write', prompt })\nawait save({ text: r.text, model: r.model, requestId: r.requestId })"
+    }
+  ],
+  "probes": [
+    { "id": "ai.text.claude-default", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0.002 },
+    { "id": "ai.text.claude-best", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.004 },
+    { "id": "ai.text.claude-fast", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.001 },
+    { "id": "ai.stream", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.002 },
+    { "id": "ai.structured", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.003 },
+    { "id": "ai.text.truncation-throws", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.001 },
+    { "id": "ai.model-not-allowed", "half": "runtime", "expect": "refused_as_expected", "refusal": "model_not_allowed", "cost_hint_usd": 0 },
+    { "id": "ai.count-tokens", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0 }
+  ]
+}

package/capabilities/config.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "./schema.json",
+  "format": 1,
+  "component": "config",
+  "title": "App configuration with workbench-config",
+  "summary": "Reads WORKBENCH_ENV and the app's own variables and secrets. A missing or invalid variable fails at startup, by name, and no value is ever printed.",
+  "status": "built",
+  "surfaces": {
+    "package": [
+      "workbenchEnv",
+      "defineConfig",
+      "sharedSecret",
+      "workerSecret",
+      "redact",
+      "redactAll",
+      "WorkbenchConfigError",
+      "capabilitySchema",
+      "capabilities",
+      "MANIFEST_VERSION",
+      "compareDevVars"
+    ]
+  },
+  "config": [
+    {
+      "name": "WORKBENCH_ENV",
+      "required": true,
+      "secret": false,
+      "environments": ["development", "staging", "production"],
+      "description": "development, staging or production. Drives key checks and the email transport; never NODE_ENV (audit F9)"
+    }
+  ],
+  "allowed": {
+    "environments": ["development", "staging", "production"]
+  },
+  "rules": [
+    { "id": "config.fail-by-name", "kind": "must", "text": "Fail at startup when a required variable is missing or invalid, naming every bad variable in one error.", "enforced_by": "types", "probe": "config.missing-variable-named" },
+    { "id": "config.never-print-values", "kind": "must_not", "text": "Print, log or include in an error the value of any variable, valid or not.", "enforced_by": "types", "probe": "config.value-never-printed" },
+    { "id": "config.no-node-env", "kind": "must_not", "text": "Decide the environment from NODE_ENV or a default. WORKBENCH_ENV is required and has no fallback.", "enforced_by": "types", "probe": "config.env-required" },
+    { "id": "config.dev-vars-example", "kind": "must", "text": "Keep .dev.vars.example listing every variable .dev.vars has, with no values; check with npx workbench-config check.", "enforced_by": "review", "probe": "config.dev-vars-check" }
+  ],
+  "examples": [
+    {
+      "id": "config.example.define",
+      "title": "Declare and read the app's variables",
+      "lang": "ts",
+      "probe": "config.missing-variable-named",
+      "code": "import { z } from 'zod'\nimport { defineConfig, workbenchEnv } from '@mccaskie-labs/workbench-config'\n\nconst config = defineConfig({\n  WORKBENCH_GATEWAY_KEY: z.string().startsWith('wbk_'),\n  SITE_NAME: z.string().default('wb-probe'),\n})\n\nexport default {\n  async fetch(request: Request, env: Env) {\n    const stage = workbenchEnv(env)\n    const { WORKBENCH_GATEWAY_KEY, SITE_NAME } = config.parse(env)\n    return new Response(`${SITE_NAME} on ${stage}`)\n  },\n}"
+    }
+  ],
+  "probes": [
+    { "id": "config.missing-variable-named", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0 },
+    { "id": "config.value-never-printed", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0 },
+    { "id": "config.env-required", "half": "runtime", "expect": "pass", "cost_hint_usd": 0 },
+    { "id": "config.dev-vars-check", "half": "runtime", "expect": "pass", "cost_hint_usd": 0, "note": "Manual: run npx workbench-config check in the project" }
+  ]
+}

package/capabilities/gateway.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "./schema.json",
+  "format": 1,
+  "component": "gateway",
+  "title": "Workbench Gateway: keys, headers, budgets and errors",
+  "summary": "What every Gateway endpoint shares: project keys by environment and scope, the request and response headers, the monthly budget check and the error codes. Apps hold one Workbench key and never a vendor key.",
+  "status": "planned",
+  "surfaces": {
+    "gateway": ["GET /v1/health", "GET /v1/usage", "GET /v1/capabilities"],
+    "package": ["DEFAULT_GATEWAY_URL"]
+  },
+  "config": [
+    {
+      "name": "WORKBENCH_GATEWAY_KEY",
+      "required": true,
+      "secret": true,
+      "environments": ["staging", "production"],
+      "description": "The project's Gateway key for this environment, delivered as a Worker secret by gw_key_issue. Never in code, .dev.vars.example or logs"
+    },
+    {
+      "name": "WORKBENCH_GATEWAY_URL",
+      "required": false,
+      "secret": false,
+      "default": "https://gateway.mccaskielabs.dev",
+      "environments": ["development", "staging", "production"],
+      "description": "Gateway base URL. Leave unset outside tests"
+    }
+  ],
+  "allowed": {
+    "scopes": ["ai", "images", "search", "email"],
+    "key_environments": [
+      { "environment": "development", "prefix": "wbk_dev_" },
+      { "environment": "staging", "prefix": "wbk_stg_" },
+      { "environment": "production", "prefix": "wbk_prd_" }
+    ],
+    "request_headers": [
+      { "name": "Authorization", "required": true, "description": "Bearer <key>. On /anthropic/* the key goes in x-api-key instead, so the official SDK works unchanged" },
+      { "name": "X-Workbench-Job", "required": true, "pattern": "^[a-z0-9._-]{1,64}$", "description": "What the call is for, e.g. article.write. Recorded with usage" },
+      { "name": "X-Workbench-Prompt-Version", "required": false, "description": "The app's prompt version, recorded with usage (audit F17)" },
+      { "name": "X-Workbench-Subject", "required": false, "pattern": "^[a-z0-9_-]+:[^\\s]{1,128}$", "description": "type:id of the thing the call is about" },
+      { "name": "Idempotency-Key", "required": false, "description": "Email only: a repeat within 24 hours returns the stored result" }
+    ],
+    "response_headers": ["X-Workbench-Request-Id", "Server-Timing"],
+    "server_timing_metrics": ["gw", "vendor_fb", "vendor", "total"]
+  },
+  "limits": [
+    { "id": "gateway.key-cache", "value": 60, "unit": "seconds", "per": "isolate", "enforced_by": "gateway" },
+    { "id": "gateway.budget-cache", "value": 60, "unit": "seconds", "per": "isolate", "enforced_by": "gateway" },
+    { "id": "gateway.job-format", "value": "[a-z0-9._-]{1,64}", "unit": "pattern", "per": "request", "enforced_by": "gateway", "refusal": "invalid_request" }
+  ],
+  "errors": [
+    { "code": "unauthorised", "http": 401, "retryable": false, "meaning": "No key, a malformed or unknown key, a revoked key, or a key from the wrong environment" },
+    { "code": "forbidden_scope", "http": 403, "retryable": false, "meaning": "The key doesn't carry the scope this endpoint needs" },
+    { "code": "invalid_request", "http": 400, "retryable": false, "meaning": "The body or a required header is missing or malformed" },
+    { "code": "budget_exceeded", "http": 402, "retryable": false, "meaning": "The environment's enforced monthly budget, or the global ceiling, is reached" },
+    { "code": "rate_limited", "http": 429, "retryable": true, "meaning": "Per-key rate limit; it stops runaway loops, budgets limit spend" },
+    { "code": "not_available", "http": 501, "retryable": false, "meaning": "Not built yet, e.g. bulk email" },
+    { "code": "upstream_error", "http": 502, "retryable": true, "meaning": "The vendor failed after the Gateway's retries" },
+    { "code": "upstream_timeout", "http": 504, "retryable": true, "meaning": "The vendor didn't answer in time" }
+  ],
+  "rules": [
+    { "id": "gateway.no-vendor-keys", "kind": "must_not", "text": "Hold a vendor key (Anthropic, Google, OpenAI, Serper, email) in an app. The Gateway key is the only Workbench credential an app has.", "enforced_by": "review", "probe": "gateway.no-vendor-keys.scan" },
+    { "id": "gateway.key-per-environment", "kind": "must", "text": "Use the key issued for the Worker's own environment. A staging key is refused by production and the other way round.", "enforced_by": "gateway", "probe": "gateway.wrong-environment" },
+    { "id": "gateway.request-id-kept", "kind": "must", "text": "Keep X-Workbench-Request-Id with any output stored or any error logged, so it can be matched to a usage row.", "enforced_by": "review", "probe": "gateway.health" }
+  ],
+  "probes": [
+    { "id": "gateway.health", "half": "runtime", "expect": "pass", "smoke": true, "cost_hint_usd": 0 },
+    { "id": "gateway.bad-key", "half": "runtime", "expect": "refused_as_expected", "refusal": "unauthorised", "smoke": true, "cost_hint_usd": 0 },
+    { "id": "gateway.wrong-scope", "half": "runtime", "expect": "refused_as_expected", "refusal": "forbidden_scope", "cost_hint_usd": 0 },
+    { "id": "gateway.wrong-environment", "half": "runtime", "expect": "refused_as_expected", "refusal": "unauthorised", "cost_hint_usd": 0 },
+    { "id": "gateway.revoked-key", "half": "runtime", "expect": "refused_as_expected", "refusal": "unauthorised", "cost_hint_usd": 0, "note": "Stops within 60 seconds of revocation" },
+    { "id": "gateway.budget-enforced", "half": "runtime", "expect": "refused_as_expected", "refusal": "budget_exceeded", "cost_hint_usd": 0.01, "note": "Uses the development key's US$0.01 enforce budget (docs/phase-4-plan.md §3 Q10)" },
+    { "id": "gateway.no-vendor-keys.scan", "half": "runtime", "expect": "pass", "cost_hint_usd": 0, "note": "Manual: grep of the repo and cf_worker_secret_list show only WORKBENCH_GATEWAY_* secrets" }
+  ]
+}

package/capabilities/schema.json

@@ -0,0 +1,414 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "./schema.json"
+    },
+    "format": {
+      "type": "number",
+      "const": 1
+    },
+    "component": {
+      "type": "string",
+      "enum": [
+        "gateway",
+        "ai",
+        "images",
+        "image-search",
+        "config",
+        "email",
+        "email-inbound",
+        "email-sending",
+        "database",
+        "workers",
+        "domains",
+        "dns",
+        "analytics",
+        "access",
+        "r2",
+        "kv",
+        "github"
+      ]
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "planned",
+        "built",
+        "deprecated"
+      ]
+    },
+    "surfaces": {
+      "type": "object",
+      "properties": {
+        "gateway": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(GET|POST|PUT|PATCH|DELETE) \\/\\S*$"
+          }
+        },
+        "tools": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z]+_[a-z0-9_]+$"
+          }
+        },
+        "package": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "config": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[A-Z][A-Z0-9_]*$"
+          },
+          "required": {
+            "type": "boolean"
+          },
+          "secret": {
+            "type": "boolean"
+          },
+          "default": {
+            "type": [
+              "string",
+              "number",
+              "boolean"
+            ]
+          },
+          "environments": {
+            "minItems": 1,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "development",
+                "staging",
+                "production"
+              ]
+            }
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "name",
+          "required",
+          "secret",
+          "environments",
+          "description"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "allowed": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {}
+    },
+    "limits": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9.-]*$"
+          },
+          "value": {
+            "type": [
+              "string",
+              "number"
+            ]
+          },
+          "unit": {
+            "type": "string",
+            "minLength": 1
+          },
+          "per": {
+            "type": "string",
+            "minLength": 1
+          },
+          "enforced_by": {
+            "type": "string",
+            "enum": [
+              "types",
+              "gateway",
+              "control",
+              "database"
+            ]
+          },
+          "refusal": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$"
+          }
+        },
+        "required": [
+          "id",
+          "value",
+          "unit",
+          "per",
+          "enforced_by"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "actions": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "tool": {
+            "type": "string",
+            "pattern": "^[a-z]+_[a-z0-9_]+$"
+          },
+          "gate": {
+            "type": "string",
+            "enum": [
+              "free",
+              "two_step",
+              "two_step_on_production",
+              "two_step_when"
+            ]
+          },
+          "when": {
+            "type": "string",
+            "minLength": 1
+          },
+          "ships": {
+            "type": "string",
+            "enum": [
+              "3",
+              "4",
+              "later"
+            ]
+          }
+        },
+        "required": [
+          "tool",
+          "gate",
+          "ships"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "errors": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$"
+          },
+          "http": {
+            "type": "integer",
+            "minimum": 400,
+            "maximum": 599
+          },
+          "retryable": {
+            "type": "boolean"
+          },
+          "meaning": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "code",
+          "http",
+          "retryable",
+          "meaning"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "rules": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9.-]*$"
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "must",
+              "must_not"
+            ]
+          },
+          "text": {
+            "type": "string",
+            "minLength": 1
+          },
+          "enforced_by": {
+            "type": "string",
+            "enum": [
+              "types",
+              "gateway",
+              "control",
+              "database",
+              "review"
+            ]
+          },
+          "probe": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9.-]*$"
+          }
+        },
+        "required": [
+          "id",
+          "kind",
+          "text",
+          "enforced_by",
+          "probe"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "examples": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9.-]*$"
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "lang": {
+            "type": "string",
+            "enum": [
+              "ts",
+              "js",
+              "sh",
+              "ps1",
+              "json",
+              "sql"
+            ]
+          },
+          "code": {
+            "type": "string",
+            "minLength": 1
+          },
+          "probe": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9.-]*$"
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "lang",
+          "code",
+          "probe"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "probes": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9.-]*$"
+          },
+          "half": {
+            "type": "string",
+            "enum": [
+              "runtime",
+              "drill"
+            ]
+          },
+          "expect": {
+            "type": "string",
+            "enum": [
+              "pass",
+              "refused_as_expected"
+            ]
+          },
+          "refusal": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$"
+          },
+          "smoke": {
+            "type": "boolean"
+          },
+          "cost_hint_usd": {
+            "type": "number",
+            "minimum": 0
+          },
+          "two_step": {
+            "type": "boolean"
+          },
+          "note": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "id",
+          "half",
+          "expect"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "$schema",
+    "format",
+    "component",
+    "title",
+    "summary",
+    "status",
+    "surfaces",
+    "rules",
+    "probes"
+  ],
+  "additionalProperties": false,
+  "title": "Workbench capabilities manifest",
+  "description": "Generated from capabilitySchema in @mccaskie-labs/workbench-config by `npm run capabilities:build`. Do not edit."
+}