spell-runtime 1.2.1 → 1.2.5

package/README.md

@@ -5,18 +5,19 @@ Minimal CLI runtime for SpellBundle v1.
 ## Setup
 
 - Node.js >= 20
-- npm
+- pnpm (recommended)
+- npm (supported)
 
 ```bash
-npm i
-npm run build
-npm test
+pnpm install
+pnpm run build
+pnpm test
 ```
 
 Local dev:
 
 ```bash
-npm run dev -- --help
+pnpm run dev -- --help
 ```
 
 ## Install as CLI
@@ -43,11 +44,11 @@ npm run smoke:npx
 
 ## Commands
 
-- `spell install <local-path>`
+- `spell install <source>`
 - `spell list`
 - `spell inspect <id> [--version x.y.z]`
-- `spell cast <id> [--version x.y.z] [-p key=value ...] [--input input.json] [--dry-run] [--yes] [--allow-billing] [--require-signature] [--verbose] [--profile <name>]`
-- `spell license add <name> <token>`
+- `spell cast <id> [--version x.y.z] [-p key=value ...] [--input input.json] [--dry-run] [--yes] [--allow-billing] [--allow-unsigned] [--require-signature] [--verbose] [--profile <name>]`
+- `spell license add <name> <entitlement-token>`
 - `spell license list`
 - `spell license remove <name>`
 - `spell sign keygen <publisher> [--key-id default] [--out-dir .spell-keys]`
@@ -59,15 +60,19 @@ npm run smoke:npx
 
 ## Install Sources
 
-`spell install <local-path>` keeps the same CLI interface and now accepts:
+`spell install <source>` accepts:
 
 - local bundle paths (existing behavior)
-- git URLs:
-  - `https://...`
-  - `ssh://...`
-  - `git@...`
+- pinned git URLs with an explicit ref suffix:
+  - `https://...#<ref>`
+  - `ssh://...#<ref>`
+  - `git@...#<ref>`
 
-When a git URL is provided, runtime performs a shallow clone (`git clone --depth 1`) into a temporary directory and installs from the cloned repository root.
+Git sources must include `#<ref>`. If omitted, install fails with:
+
+- `git source requires explicit ref (#<ref>)`
+
+When a git source is provided, runtime clones the repository, checks out the requested ref, resolves the checked-out commit SHA (`git rev-parse HEAD`), and installs from that checkout.
 
 Limitations:
 
@@ -79,8 +84,17 @@ Limitations:
 
 - Spells: `~/.spell/spells/<id_key>/<version>/`
 - ID index: `~/.spell/spells/<id_key>/spell.id.txt`
+- Install provenance: `~/.spell/spells/<id_key>/<version>/source.json`
 - Logs: `~/.spell/logs/<timestamp>_<id>_<version>.json`
-- Billing license tokens: `~/.spell/licenses/*.json`
+- Billing entitlement records: `~/.spell/licenses/*.json`
+
+`source.json` captures install provenance:
+
+- `type`: `local` or `git`
+- `source`: original install input
+- `ref`: requested git ref (git installs only)
+- `commit`: resolved git commit SHA (git installs only)
+- `installed_at`: install timestamp (ISO-8601)
 
 `id_key` is fixed as `base64url(utf8(id))`.
 
@@ -99,16 +113,34 @@ Consistency rule:
 - bundle resolution by id (and optional version)
 - input assembly (`--input` + `-p` overrides)
 - JSON Schema validation by Ajv
-- optional signature verification (`--require-signature`)
+- signature verification (default on; bypass only with `--allow-unsigned`)
+- runtime policy guard (`~/.spell/policy.json`)
 - platform guard
 - risk guard (`high`/`critical` requires `--yes`)
 - billing guard (`billing.enabled` requires `--allow-billing`)
-- billing license guard (`billing.enabled` + `--allow-billing` requires a local token from `spell license add ...`)
+- billing entitlement guard (`billing.enabled` + `--allow-billing` requires a matching valid entitlement from `spell license add ...`)
 - connector token guard (`CONNECTOR_<NAME>_TOKEN`)
 - execution summary output
 
 If `--dry-run` is set, command exits after summary and validation.
 
+Policy file format (`~/.spell/policy.json`):
+
+```json
+{
+  "version": "v1",
+  "default": "allow",
+  "publishers": { "allow": ["samples"], "deny": ["blocked"] },
+  "max_risk": "high",
+  "runtime": { "allow_execution": ["host", "docker"] }
+}
+```
+
+Notes:
+- missing policy file => allow by default
+- invalid policy file => `invalid policy: ...`
+- policy rejection => `policy denied: <reason>`
+
 ## Runtime Safety Limits (v2 isolation)
 
 `cast` enforces these runtime limits (used by direct CLI casts and API-triggered casts because the API invokes `spell cast`):
@@ -129,7 +161,22 @@ Docker mode (v1) details:
 - `runtime.execution=docker` requires `runtime.docker_image`.
 - the image must provide `spell-runner` on `PATH` (this repo publishes it as a second npm bin).
 - the bundle is mounted read-only at `/spell`; the runner copies it into a writable temp workdir before executing steps.
-- environment variables passed from host -> container are restricted to connector tokens only (`CONNECTOR_<NAME>_TOKEN`). If your spell needs `{{ENV.*}}` for other values, provide them inside the image (or extend the runtime later).
+- hardened `docker run` defaults:
+  - `--network none`
+  - `--cap-drop ALL`
+  - `--security-opt no-new-privileges`
+  - `--read-only`
+  - `--user 65532:65532`
+  - `--pids-limit 256`
+  - `--tmpfs /tmp:rw,noexec,nosuid,size=64m`
+- hardening env overrides (all optional):
+  - `SPELL_DOCKER_NETWORK` (`none|bridge|host`, default `none`)
+  - `SPELL_DOCKER_USER` (default `65532:65532`; set empty to disable `--user`)
+  - `SPELL_DOCKER_READ_ONLY` (`1` default; set `0` to disable `--read-only`)
+  - `SPELL_DOCKER_PIDS_LIMIT` (`256` default; set `0` to disable `--pids-limit`)
+  - `SPELL_DOCKER_MEMORY` (default empty; when set adds `--memory`)
+  - `SPELL_DOCKER_CPUS` (default empty; when set adds `--cpus`)
+- environment variables passed from host -> container are restricted to connector tokens (`CONNECTOR_<NAME>_TOKEN`) plus `SPELL_RUNTIME_STEP_TIMEOUT_MS`.
 
 ## Windows Policy
 
@@ -151,20 +198,22 @@ Use these `effect.type` words where possible:
 ## v1 Limitations (Intentionally Not Implemented)
 
 - name search or ambiguous resolution (id only)
-- registry/marketplace/license verification
+- registry/marketplace integration
 - real billing execution (Stripe)
 - DAG/parallel/rollback/self-healing
 - advanced templating language (only `{{INPUT.*}}` and `{{ENV.*}}`)
-- docker env passthrough beyond connector tokens
+- docker env passthrough beyond connector tokens and `SPELL_RUNTIME_STEP_TIMEOUT_MS`
 
 ## Signature (Sign + Verify)
 
-If a bundle contains `spell.sig.json`, you can require signature verification at execution time:
+`spell cast` requires signature verification by default. To bypass this for unsigned bundle workflows, use:
 
 ```bash
-spell cast <id> --require-signature ...
+spell cast <id> --allow-unsigned ...
 ```
 
+`--require-signature` remains accepted for backward compatibility.
+
 Signing flow:
 
 ```bash
@@ -184,6 +233,40 @@ Notes:
 - publisher is derived from the spell id prefix before the first `/` (example: `samples/call-webhook` -> `samples`).
 - public key format is ed25519 `spki` DER encoded as base64url.
 
+## Entitlement Tokens (Billing)
+
+`spell license add <name> <token>` now validates and stores signed entitlement tokens.
+
+Token format:
+
+- `ent1.<payloadBase64url>.<signatureBase64url>`
+
+Payload JSON required fields:
+
+- `version` (`"v1"`)
+- `issuer` (string)
+- `key_id` (string)
+- `mode` (`"upfront" | "on_success" | "subscription"`)
+- `currency` (string)
+- `max_amount` (number)
+- `not_before` (ISO string)
+- `expires_at` (ISO string)
+
+Verification rules:
+
+- signature algorithm is ed25519
+- signed message is the raw payload segment bytes (the exact payload base64url segment string bytes)
+- trust source is the publisher trust store (`spell trust add ...`) keyed by `issuer + key_id`
+- token must be within `not_before <= now <= expires_at`
+
+Billing-enabled cast requires a matching currently-valid entitlement:
+
+- entitlement `mode === manifest.billing.mode`
+- entitlement `currency` equals `manifest.billing.currency` (case-insensitive)
+- entitlement `max_amount >= manifest.billing.max_amount`
+
+`spell license list` prints entitlement summary columns (`issuer`, `mode`, `currency`, `max_amount`, `expires_at`) and never prints raw tokens.
+
 ## Example Flow
 
 ```bash
@@ -195,6 +278,38 @@ spell cast fixtures/hello-host -p name=world
 spell log <execution-id>
 ```
 
+## OSS Release (pnpm + GitHub Actions)
+
+Release automation is defined in:
+
+- `.github/workflows/release.yml`
+
+Prerequisites:
+
+- npm account with `2FA` enabled
+- GitHub repository secret `NPM_TOKEN` (publish-capable npm token)
+
+Local release checks:
+
+```bash
+pnpm install
+pnpm run typecheck
+pnpm run lint
+pnpm run build
+pnpm test
+pnpm run pack:check
+```
+
+Tag-based release flow:
+
+```bash
+npm version patch
+git push --follow-tags
+```
+
+Pushing tag `vX.Y.Z` triggers GitHub Actions release and runs `npm publish`.
+The workflow verifies that the git tag version matches `package.json`.
+
 ## Real-Use Sample Spells
 
 These are product-facing examples (separate from test fixtures):
@@ -220,12 +335,20 @@ spell cast samples/call-webhook --dry-run -p event=deploy -p source=manual -p pa
 - Button registry schema:
   - `/Users/koichinishizuka/spell-runtime/examples/button-registry.v1.schema.json`
 - Registry optional policy:
-  - `require_signature` (when true, Execution API adds `--require-signature`)
+  - `require_signature`:
+    - `true`: Execution API enforces signature (`--require-signature`)
+    - `false`/omitted: Execution API opts into unsigned path (`--allow-unsigned`)
 
 ## Runtime Decision Log
 
 - `/Users/koichinishizuka/spell-runtime/docs/runtime-decisions-v1.md`
 
+## Repository Policies
+
+- `/Users/koichinishizuka/spell-runtime/CONTRIBUTING.md`
+- `/Users/koichinishizuka/spell-runtime/CODE_OF_CONDUCT.md`
+- `/Users/koichinishizuka/spell-runtime/SECURITY.md`
+
 ## Execution API (Async)
 
 Start API server:
@@ -245,14 +368,14 @@ By default it listens on `:8787` and reads:
   - `GET /` (minimal Receipts UI)
   - `GET /ui/app.js` (UI client script)
   - `GET /api/buttons`
-  - `GET /api/spell-executions` (`status`, `button_id`, `limit` query supported)
+  - `GET /api/spell-executions` (`status`, `button_id`, `tenant_id`, `limit` query supported)
   - `POST /api/spell-executions`
   - `GET /api/spell-executions/:execution_id`
 
 Optional environment variables:
 - `SPELL_API_PORT`
 - `SPELL_BUTTON_REGISTRY_PATH`
-- `SPELL_API_AUTH_KEYS` (comma-separated `role=token` entries; when set, `/api/*` requires auth and derives `actor_role` from token)
+- `SPELL_API_AUTH_KEYS` (comma-separated `role=token` or `tenant:role=token` entries; when set, `/api/*` requires auth and derives `actor_role` + `tenant_id` from token)
 - `SPELL_API_AUTH_TOKENS` (legacy: comma-separated tokens; when set, `/api/*` requires auth but does not bind role)
 - `SPELL_API_BODY_LIMIT_BYTES`
 - `SPELL_API_EXECUTION_TIMEOUT_MS`
@@ -266,4 +389,5 @@ Security note:
 - execution logs redact secret-like keys (`token`, `authorization`, `apiKey`, etc.)
 - environment-derived secret values are masked in persisted logs
 - when auth is enabled, pass `Authorization: Bearer <token>` (or `x-api-key`) for `/api` routes
+- with `SPELL_API_AUTH_KEYS`, non-admin list requests are restricted to their own tenant and cross-tenant `tenant_id` filters return `403` (`TENANT_FORBIDDEN`)
 - do not set both `SPELL_API_AUTH_KEYS` and `SPELL_API_AUTH_TOKENS` at the same time

package/README.txt

@@ -4,19 +4,20 @@ Minimal CLI runtime for SpellBundle v1.
 
 1. Setup
 - Node.js >= 20
-- npm
+- pnpm (recommended)
+- npm (supported)
 
 Install dependencies:
-  npm i
+  pnpm install
 
 Build:
-  npm run build
+  pnpm run build
 
 Test:
-  npm test
+  pnpm test
 
 Local dev:
-  npm run dev -- --help
+  pnpm run dev -- --help
 
 Binary smoke checks:
   npm run smoke:link
@@ -30,11 +31,11 @@ Manual npx (local package):
   npx --yes --package file:. spell --help
 
 2. CLI commands
-- spell install <local-path>
+- spell install <source>
 - spell list
 - spell inspect <id> [--version x.y.z]
-- spell cast <id> [--version x.y.z] [-p key=value ...] [--input input.json] [--dry-run] [--yes] [--allow-billing] [--require-signature] [--verbose] [--profile <name>]
-- spell license add <name> <token>
+- spell cast <id> [--version x.y.z] [-p key=value ...] [--input input.json] [--dry-run] [--yes] [--allow-billing] [--allow-unsigned] [--require-signature] [--verbose] [--profile <name>]
+- spell license add <name> <entitlement-token>
 - spell license list
 - spell license remove <name>
 - spell sign keygen <publisher> [--key-id default] [--out-dir .spell-keys]
@@ -45,14 +46,17 @@ Manual npx (local package):
 - spell log <execution-id>
 
 2.1 Install sources
-- spell install <local-path> keeps the same CLI interface and now accepts:
+- spell install <source> accepts:
   - local bundle paths (existing behavior)
-  - git URLs:
-    - https://...
-    - ssh://...
-    - git@...
+  - pinned git URLs with explicit refs:
+    - https://...#<ref>
+    - ssh://...#<ref>
+    - git@...#<ref>
 
-When a git URL is provided, runtime performs a shallow clone (git clone --depth 1) into a temporary directory and installs from the cloned repository root.
+Git sources must include #<ref>. If omitted, install fails with:
+  git source requires explicit ref (#<ref>)
+
+When a git source is provided, runtime clones the repository, checks out the requested ref, resolves the checked-out commit SHA (git rev-parse HEAD), and installs from that checkout.
 
 Limitations:
 - git must be installed and available on PATH.
@@ -62,8 +66,16 @@ Limitations:
 3. Storage layout
 - Spells: ~/.spell/spells/<id_key>/<version>/
 - ID index: ~/.spell/spells/<id_key>/spell.id.txt
+- Install provenance: ~/.spell/spells/<id_key>/<version>/source.json
 - Logs: ~/.spell/logs/<timestamp>_<id>_<version>.json
-- Billing license tokens: ~/.spell/licenses/*.json
+- Billing entitlement records: ~/.spell/licenses/*.json
+
+source.json captures install provenance:
+- type: local or git
+- source: original install input
+- ref: requested git ref (git installs only)
+- commit: resolved git commit SHA (git installs only)
+- installed_at: install timestamp (ISO-8601)
 
 id_key is fixed as base64url(utf8(id)).
 - id is the logical identifier (display, package identity).
@@ -78,16 +90,31 @@ Cast performs these checks before execution:
 - Bundle resolution by id (and optional version)
 - Input assembly (--input + -p overrides)
 - JSON Schema validation by Ajv
-- Optional signature verification (--require-signature)
+- Signature verification (default on; bypass only with --allow-unsigned)
+- Runtime policy guard (~/.spell/policy.json)
 - Platform guard
 - Risk guard (high/critical requires --yes)
 - Billing guard (billing.enabled requires --allow-billing)
-- Billing license guard (billing.enabled + --allow-billing requires a local token from spell license add ...)
+- Billing entitlement guard (billing.enabled + --allow-billing requires a matching valid entitlement from spell license add ...)
 - Connector token guard (CONNECTOR_<NAME>_TOKEN)
 - Execution summary output
 
 If --dry-run is set, command exits after summary and validation.
 
+Policy file format (~/.spell/policy.json):
+{
+  "version": "v1",
+  "default": "allow",
+  "publishers": { "allow": ["samples"], "deny": ["blocked"] },
+  "max_risk": "high",
+  "runtime": { "allow_execution": ["host", "docker"] }
+}
+
+Notes:
+- missing policy file => allow by default
+- invalid policy file => invalid policy: ...
+- policy rejection => policy denied: <reason>
+
 4.1 Runtime safety limits (v2 isolation)
 cast enforces these runtime limits (for direct CLI casts and API-triggered casts, because the API invokes spell cast):
 - SPELL_RUNTIME_INPUT_MAX_BYTES (default 65536): max bytes for merged cast input (--input + -p overrides)
@@ -103,7 +130,22 @@ Docker mode (v1) details:
 - runtime.execution=docker requires runtime.docker_image.
 - the image must provide spell-runner on PATH (this repo publishes it as a second npm bin).
 - the bundle is mounted read-only at /spell; the runner copies it into a writable temp workdir before executing steps.
-- env vars passed from host -> container are restricted to connector tokens only (CONNECTOR_<NAME>_TOKEN). If your spell needs {{ENV.*}} for other values, provide them inside the image (or extend the runtime later).
+- hardened docker run defaults:
+  - --network none
+  - --cap-drop ALL
+  - --security-opt no-new-privileges
+  - --read-only
+  - --user 65532:65532
+  - --pids-limit 256
+  - --tmpfs /tmp:rw,noexec,nosuid,size=64m
+- hardening env overrides (all optional):
+  - SPELL_DOCKER_NETWORK (none|bridge|host, default none)
+  - SPELL_DOCKER_USER (default 65532:65532; set empty to disable --user)
+  - SPELL_DOCKER_READ_ONLY (1 default; set 0 to disable --read-only)
+  - SPELL_DOCKER_PIDS_LIMIT (256 default; set 0 to disable --pids-limit)
+  - SPELL_DOCKER_MEMORY (default empty; when set adds --memory)
+  - SPELL_DOCKER_CPUS (default empty; when set adds --cpus)
+- env vars passed from host -> container are restricted to connector tokens (CONNECTOR_<NAME>_TOKEN) plus SPELL_RUNTIME_STEP_TIMEOUT_MS.
 
 6. Windows policy
 - host mode does not assume bash/sh.
@@ -121,15 +163,17 @@ Use these effect.type words where possible:
 
 8. v1 limitations (intentionally not implemented)
 - name search or ambiguous resolution (id only)
-- registry/marketplace/license verification
+- registry/marketplace integration
 - real billing execution (Stripe)
 - DAG/parallel/rollback/self-healing
 - advanced templating language (only {{INPUT.*}} and {{ENV.*}})
-- docker env passthrough beyond connector tokens
+- docker env passthrough beyond connector tokens and SPELL_RUNTIME_STEP_TIMEOUT_MS
 
 8.1 Signature (sign + verify)
-If a bundle contains spell.sig.json, you can require signature verification at execution time:
-  spell cast <id> --require-signature ...
+spell cast requires signature verification by default. To bypass this for unsigned bundle workflows:
+  spell cast <id> --allow-unsigned ...
+
+--require-signature remains accepted for backward compatibility.
 
 Signing flow:
   spell sign keygen samples --key-id default --out-dir .spell-keys
@@ -145,6 +189,35 @@ Notes:
 - publisher is derived from the spell id prefix before the first / (example: samples/call-webhook -> samples).
 - public key format is ed25519 spki DER encoded as base64url.
 
+8.2 Entitlement tokens (billing)
+spell license add <name> <token> now validates and stores signed entitlement tokens.
+
+Token format:
+- ent1.<payloadBase64url>.<signatureBase64url>
+
+Payload JSON required fields:
+- version ("v1")
+- issuer (string)
+- key_id (string)
+- mode ("upfront" | "on_success" | "subscription")
+- currency (string)
+- max_amount (number)
+- not_before (ISO string)
+- expires_at (ISO string)
+
+Verification rules:
+- signature algorithm: ed25519
+- signed message: raw payload segment bytes (exact payload base64url segment string bytes)
+- trust source: publisher trust store (spell trust add ...) keyed by issuer + key_id
+- token must be within not_before <= now <= expires_at
+
+Billing-enabled cast requires a matching currently-valid entitlement:
+- entitlement mode equals manifest.billing.mode
+- entitlement currency equals manifest.billing.currency (case-insensitive)
+- entitlement max_amount >= manifest.billing.max_amount
+
+spell license list prints entitlement summary columns (issuer/mode/currency/max_amount/expires_at) and does not print raw tokens.
+
 9. Example flow
 1) Install a local fixture
   spell install ./fixtures/spells/hello-host
@@ -164,6 +237,29 @@ Notes:
 6) Show execution log
   spell log <execution-id>
 
+9.1 OSS release (pnpm + GitHub Actions)
+Automation file:
+  .github/workflows/release.yml
+
+Prerequisites:
+- npm account with 2FA enabled
+- GitHub repository secret NPM_TOKEN (publish-capable npm token)
+
+Local release checks:
+  pnpm install
+  pnpm run typecheck
+  pnpm run lint
+  pnpm run build
+  pnpm test
+  pnpm run pack:check
+
+Tag-based release flow:
+  npm version patch
+  git push --follow-tags
+
+Tag push vX.Y.Z triggers GitHub Actions release and runs npm publish.
+The workflow verifies that tag version matches package.json.
+
 10. UI connection spec
 - Decision-complete button integration spec:
   /Users/koichinishizuka/spell-runtime/docs/ui-connection-spec-v1.md
@@ -172,7 +268,8 @@ Notes:
 - Button registry schema:
   /Users/koichinishizuka/spell-runtime/examples/button-registry.v1.schema.json
 - Registry optional policy:
-  require_signature (when true, Execution API adds --require-signature)
+  require_signature=true: Execution API enforces signature (--require-signature)
+  require_signature=false or omitted: Execution API opts into unsigned path (--allow-unsigned)
 
 11. Install from npm
 Global install:
@@ -195,6 +292,11 @@ Quick try:
 13. Runtime decision log
 - /Users/koichinishizuka/spell-runtime/docs/runtime-decisions-v1.md
 
+13.1 Repository policies
+- /Users/koichinishizuka/spell-runtime/CONTRIBUTING.md
+- /Users/koichinishizuka/spell-runtime/CODE_OF_CONDUCT.md
+- /Users/koichinishizuka/spell-runtime/SECURITY.md
+
 14. Execution API (async)
 Start:
   npm run api:dev
@@ -211,14 +313,14 @@ Defaults:
   GET /
   GET /ui/app.js
   GET /api/buttons
-  GET /api/spell-executions (status/button_id/limit query supported)
+  GET /api/spell-executions (status/button_id/tenant_id/limit query supported)
   POST /api/spell-executions
   GET /api/spell-executions/:execution_id
 
 Optional environment variables:
 - SPELL_API_PORT
 - SPELL_BUTTON_REGISTRY_PATH
-- SPELL_API_AUTH_KEYS (comma-separated role=token entries; when set, /api/* requires auth and derives actor_role from token)
+- SPELL_API_AUTH_KEYS (comma-separated role=token or tenant:role=token entries; when set, /api/* requires auth and derives actor_role + tenant_id from token)
 - SPELL_API_AUTH_TOKENS (legacy: comma-separated tokens; when set, /api/* requires auth but does not bind role)
 - SPELL_API_BODY_LIMIT_BYTES
 - SPELL_API_EXECUTION_TIMEOUT_MS
@@ -232,4 +334,5 @@ Security note:
 - execution logs redact secret-like keys (token, authorization, apiKey, etc.)
 - environment-derived secret values are masked in persisted logs
 - when auth is enabled, pass Authorization: Bearer <token> (or x-api-key) for /api routes
+- with SPELL_API_AUTH_KEYS, non-admin list requests are restricted to their own tenant and cross-tenant tenant_id filters return 403 (TENANT_FORBIDDEN)
 - do not set both SPELL_API_AUTH_KEYS and SPELL_API_AUTH_TOKENS at the same time