spell-runtime 1.0.0 → 1.2.0

package/README.md

@@ -46,7 +46,12 @@ npm run smoke:npx
 - `spell install <local-path>`
 - `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] [--verbose] [--profile <name>]`
+- `spell cast <id> [--version x.y.z] [-p key=value ...] [--input input.json] [--dry-run] [--yes] [--allow-billing] [--require-signature] [--verbose] [--profile <name>]`
+- `spell sign keygen <publisher> [--key-id default] [--out-dir .spell-keys]`
+- `spell sign bundle <local-path> --private-key <file> [--key-id default] [--publisher <name>]`
+- `spell trust add <publisher> <public-key> [--key-id default]`
+- `spell trust list`
+- `spell trust remove <publisher>`
 - `spell log <execution-id>`
 
 ## Storage Layout
@@ -72,6 +77,7 @@ Consistency rule:
 - bundle resolution by id (and optional version)
 - input assembly (`--input` + `-p` overrides)
 - JSON Schema validation by Ajv
+- optional signature verification (`--require-signature`)
 - platform guard
 - risk guard (`high`/`critical` requires `--yes`)
 - billing guard (`billing.enabled` requires `--allow-billing`)
@@ -82,14 +88,17 @@ If `--dry-run` is set, command exits after summary and validation.
 
 ## Runtime Model
 
-v1 supports host execution only.
+v1 supports:
 
 - host: steps run in order, shell/http supported.
-- docker: explicitly unsupported in v1 and fails with a clear error.
+- docker: steps run in a linux container via "runner-in-image".
 
-Future docker direction:
+Docker mode (v1) details:
 
-- docker image contains `spell-runner` and executes bundle in container.
+- `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).
 
 ## Windows Policy
 
@@ -111,11 +120,38 @@ Use these `effect.type` words where possible:
 ## v1 Limitations (Intentionally Not Implemented)
 
 - name search or ambiguous resolution (id only)
-- registry/marketplace/signature enforcement/license verification
+- registry/marketplace/license verification
 - real billing execution (Stripe)
 - DAG/parallel/rollback/self-healing
 - advanced templating language (only `{{INPUT.*}}` and `{{ENV.*}}`)
-- docker step execution runtime
+- docker env passthrough beyond connector tokens
+
+## Signature (Sign + Verify)
+
+If a bundle contains `spell.sig.json`, you can require signature verification at execution time:
+
+```bash
+spell cast <id> --require-signature ...
+```
+
+Signing flow:
+
+```bash
+spell sign keygen samples --key-id default --out-dir .spell-keys
+spell trust add samples <public_key_base64url> --key-id default
+spell sign bundle ./examples/spells/call-webhook --private-key .spell-keys/samples__default.private.pem --key-id default
+```
+
+Trust store:
+
+- `spell trust add <publisher> <public-key>`
+- `spell trust list`
+- `spell trust remove <publisher>`
+
+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.
 
 ## Example Flow
 
@@ -128,9 +164,75 @@ spell cast fixtures/hello-host -p name=world
 spell log <execution-id>
 ```
 
+## Real-Use Sample Spells
+
+These are product-facing examples (separate from test fixtures):
+
+- `/Users/koichinishizuka/spell-runtime/examples/spells/call-webhook`
+- `/Users/koichinishizuka/spell-runtime/examples/spells/repo-ops`
+- `/Users/koichinishizuka/spell-runtime/examples/spells/publish-site`
+
+Quick try:
+
+```bash
+spell install ./examples/spells/call-webhook
+spell inspect samples/call-webhook
+spell cast samples/call-webhook --dry-run -p event=deploy -p source=manual -p payload='{"service":"web"}'
+```
+
 ## UI Connection Spec
 
 - Decision-complete button integration spec:
   - `/Users/koichinishizuka/spell-runtime/docs/ui-connection-spec-v1.md`
 - Sample button registry:
   - `/Users/koichinishizuka/spell-runtime/examples/button-registry.v1.json`
+- 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`)
+
+## Runtime Decision Log
+
+- `/Users/koichinishizuka/spell-runtime/docs/runtime-decisions-v1.md`
+
+## Execution API (Async)
+
+Start API server:
+
+```bash
+npm run api:dev
+```
+
+By default it listens on `:8787` and reads:
+- button registry: `./examples/button-registry.v1.json`
+- limits:
+  - request body: `64KB`
+  - execution timeout: `60s`
+  - in-flight executions: `4`
+- execution index persistence: `~/.spell/logs/index.json`
+- routes:
+  - `GET /` (minimal Receipts UI)
+  - `GET /ui/app.js` (UI client script)
+  - `GET /api/buttons`
+  - `GET /api/spell-executions` (`status`, `button_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_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`
+- `SPELL_API_RATE_LIMIT_WINDOW_MS`
+- `SPELL_API_RATE_LIMIT_MAX_REQUESTS`
+- `SPELL_API_MAX_CONCURRENT_EXECUTIONS`
+- `SPELL_API_LOG_RETENTION_DAYS` (default `14`, `0` disables age-based pruning)
+- `SPELL_API_LOG_MAX_FILES` (default `500`, `0` disables count-based pruning)
+
+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
+- do not set both `SPELL_API_AUTH_KEYS` and `SPELL_API_AUTH_TOKENS` at the same time

package/README.txt

@@ -33,7 +33,12 @@ Manual npx (local package):
 - spell install <local-path>
 - 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] [--verbose] [--profile <name>]
+- spell cast <id> [--version x.y.z] [-p key=value ...] [--input input.json] [--dry-run] [--yes] [--allow-billing] [--require-signature] [--verbose] [--profile <name>]
+- spell sign keygen <publisher> [--key-id default] [--out-dir .spell-keys]
+- spell sign bundle <local-path> --private-key <file> [--key-id default] [--publisher <name>]
+- spell trust add <publisher> <public-key> [--key-id default]
+- spell trust list
+- spell trust remove <publisher>
 - spell log <execution-id>
 
 3. Storage layout
@@ -54,6 +59,7 @@ 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)
 - Platform guard
 - Risk guard (high/critical requires --yes)
 - Billing guard (billing.enabled requires --allow-billing)
@@ -63,12 +69,15 @@ Cast performs these checks before execution:
 If --dry-run is set, command exits after summary and validation.
 
 5. Runtime model
-v1 supports host execution only.
+v1 supports:
 - host: steps run in order, shell/http supported.
-- docker: explicitly unsupported in v1 and fails with a clear error.
+- docker: steps run in a linux container via "runner-in-image".
 
-Future docker direction:
-- docker image contains spell-runner and executes bundle in container.
+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).
 
 6. Windows policy
 - host mode does not assume bash/sh.
@@ -86,11 +95,29 @@ Use these effect.type words where possible:
 
 8. v1 limitations (intentionally not implemented)
 - name search or ambiguous resolution (id only)
-- registry/marketplace/signature enforcement/license verification
+- registry/marketplace/license verification
 - real billing execution (Stripe)
 - DAG/parallel/rollback/self-healing
 - advanced templating language (only {{INPUT.*}} and {{ENV.*}})
-- docker step execution runtime
+- docker env passthrough beyond connector tokens
+
+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 ...
+
+Signing flow:
+  spell sign keygen samples --key-id default --out-dir .spell-keys
+  spell trust add samples <public_key_base64url> --key-id default
+  spell sign bundle ./examples/spells/call-webhook --private-key .spell-keys/samples__default.private.pem --key-id default
+
+Trust store:
+- spell trust add <publisher> <public-key>
+- spell trust list
+- spell trust remove <publisher>
+
+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.
 
 9. Example flow
 1) Install a local fixture
@@ -116,6 +143,10 @@ Use these effect.type words where possible:
   /Users/koichinishizuka/spell-runtime/docs/ui-connection-spec-v1.md
 - Sample button registry:
   /Users/koichinishizuka/spell-runtime/examples/button-registry.v1.json
+- 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)
 
 11. Install from npm
 Global install:
@@ -124,3 +155,55 @@ Global install:
 
 Run with npx:
   npx --yes --package spell-runtime spell --help
+
+12. Real-use sample spells
+- /Users/koichinishizuka/spell-runtime/examples/spells/call-webhook
+- /Users/koichinishizuka/spell-runtime/examples/spells/repo-ops
+- /Users/koichinishizuka/spell-runtime/examples/spells/publish-site
+
+Quick try:
+  spell install ./examples/spells/call-webhook
+  spell inspect samples/call-webhook
+  spell cast samples/call-webhook --dry-run -p event=deploy -p source=manual -p payload='{"service":"web"}'
+
+13. Runtime decision log
+- /Users/koichinishizuka/spell-runtime/docs/runtime-decisions-v1.md
+
+14. Execution API (async)
+Start:
+  npm run api:dev
+
+Defaults:
+- listens on :8787
+- reads registry: ./examples/button-registry.v1.json
+- limits:
+  - request body: 64KB
+  - execution timeout: 60s
+  - in-flight executions: 4
+- execution index persistence: ~/.spell/logs/index.json
+- routes:
+  GET /
+  GET /ui/app.js
+  GET /api/buttons
+  GET /api/spell-executions (status/button_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_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
+- SPELL_API_RATE_LIMIT_WINDOW_MS
+- SPELL_API_RATE_LIMIT_MAX_REQUESTS
+- SPELL_API_MAX_CONCURRENT_EXECUTIONS
+- SPELL_API_LOG_RETENTION_DAYS (default 14, 0 disables age-based pruning)
+- SPELL_API_LOG_MAX_FILES (default 500, 0 disables count-based pruning)
+
+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
+- do not set both SPELL_API_AUTH_KEYS and SPELL_API_AUTH_TOKENS at the same time

package/dist/api/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api/index.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_1 = require("./server");
+async function main() {
+    const port = readIntegerEnv("SPELL_API_PORT", 1, 8787);
+    const registryPath = process.env.SPELL_BUTTON_REGISTRY_PATH;
+    const requestBodyLimitBytes = readOptionalIntegerEnv("SPELL_API_BODY_LIMIT_BYTES", 1);
+    const executionTimeoutMs = readOptionalIntegerEnv("SPELL_API_EXECUTION_TIMEOUT_MS", 1);
+    const rateLimitWindowMs = readOptionalIntegerEnv("SPELL_API_RATE_LIMIT_WINDOW_MS", 1);
+    const rateLimitMaxRequests = readOptionalIntegerEnv("SPELL_API_RATE_LIMIT_MAX_REQUESTS", 1);
+    const maxConcurrentExecutions = readOptionalIntegerEnv("SPELL_API_MAX_CONCURRENT_EXECUTIONS", 0);
+    const authTokens = readOptionalCsvEnv("SPELL_API_AUTH_TOKENS");
+    const authKeys = readOptionalCsvEnv("SPELL_API_AUTH_KEYS");
+    const logRetentionDays = readOptionalIntegerEnv("SPELL_API_LOG_RETENTION_DAYS", 0);
+    const logMaxFiles = readOptionalIntegerEnv("SPELL_API_LOG_MAX_FILES", 0);
+    const started = await (0, server_1.startExecutionApiServer)({
+        port,
+        registryPath,
+        requestBodyLimitBytes,
+        executionTimeoutMs,
+        rateLimitWindowMs,
+        rateLimitMaxRequests,
+        maxConcurrentExecutions,
+        authTokens,
+        authKeys,
+        logRetentionDays,
+        logMaxFiles
+    });
+    process.stdout.write(`spell execution api listening on :${started.port}\n`);
+}
+main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+});
+function readOptionalIntegerEnv(name, min) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === "") {
+        return undefined;
+    }
+    return readInteger(name, raw, min);
+}
+function readIntegerEnv(name, min, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === "") {
+        return fallback;
+    }
+    return readInteger(name, raw, min);
+}
+function readInteger(name, raw, min) {
+    const num = Number(raw);
+    if (!Number.isInteger(num) || num < min) {
+        throw new Error(`${name} must be an integer >= ${min}`);
+    }
+    return num;
+}
+function readOptionalCsvEnv(name) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === "") {
+        return undefined;
+    }
+    const values = raw
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    if (values.length === 0) {
+        return undefined;
+    }
+    return values;
+}
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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"}

package/dist/api/server.d.ts

@@ -0,0 +1,19 @@
+export interface ExecutionApiServerOptions {
+    port?: number;
+    registryPath?: string;
+    requestBodyLimitBytes?: number;
+    executionTimeoutMs?: number;
+    rateLimitWindowMs?: number;
+    rateLimitMaxRequests?: number;
+    maxConcurrentExecutions?: number;
+    authTokens?: string[];
+    authKeys?: string[];
+    logRetentionDays?: number;
+    logMaxFiles?: number;
+}
+interface StartExecutionApiServerResult {
+    port: number;
+    close: () => Promise<void>;
+}
+export declare function startExecutionApiServer(options?: ExecutionApiServerOptions): Promise<StartExecutionApiServerResult>;
+export {};