settld 0.1.2 → 0.2.0

package/docs/QUICKSTART_PROFILES.md

@@ -0,0 +1,198 @@
+# Quickstart: Profiles CLI
+
+Goal: scaffold, validate, and simulate a policy profile with the Settld CLI.
+
+## Prerequisites
+
+- Node.js 20+
+- Repo checkout with dependencies installed (`npm ci`)
+
+## 0) One-command runtime setup (recommended before `profile apply`)
+
+Non-interactive setup (manual mode):
+
+```bash
+./bin/settld.js setup --yes --mode manual --host codex --base-url http://127.0.0.1:3000 --tenant-id tenant_default --api-key sk_runtime_apply --profile-id engineering-spend
+```
+
+`settld setup` now also emits `SETTLD_PAID_TOOLS_AGENT_PASSPORT` automatically, so paid MCP tools run with policy-bound passport context without manual JSON editing.
+Add `--smoke` if you want setup to run an immediate MCP probe before moving on.
+
+Bootstrap mode (same flow, runtime key minted by onboarding endpoint):
+
+```bash
+./bin/settld.js setup --yes --mode bootstrap --host codex --base-url https://api.settld.work --tenant-id tenant_default --bootstrap-api-key mlk_admin_xxx --bootstrap-key-id sk_runtime --bootstrap-scopes runs:read,runs:write --idempotency-key profile_setup_bootstrap_1
+```
+
+If you only want runtime env + host wiring (without applying a profile), add:
+
+```bash
+--skip-profile-apply
+```
+
+To validate payment evidence early, run a paid demo after setup and verify the first exported receipt:
+
+```bash
+npm run demo:mcp-paid-exa
+jq -c 'first' artifacts/mcp-paid-exa/*/x402-receipts.export.jsonl > /tmp/settld-first-receipt.json
+settld x402 receipt verify /tmp/settld-first-receipt.json --format json --json-out /tmp/settld-first-receipt.verify.json
+```
+
+To verify MCP wiring immediately during setup, add:
+
+```bash
+--smoke
+```
+
+Single command that loads setup exports and applies a profile:
+
+```bash
+eval "$(./bin/settld.js setup --yes --mode manual --host codex --base-url http://127.0.0.1:3000 --tenant-id tenant_default --api-key sk_runtime_apply | grep '^export ')" && ./bin/settld.js profile apply ./profiles/engineering-spend.profile.json --format json
+```
+
+## 1) List available starter profiles
+
+Installed CLI:
+
+```bash
+npx settld profile list
+```
+
+Repo checkout:
+
+```bash
+./bin/settld.js profile list
+```
+
+Example output:
+
+```text
+engineering-spend	engineering	Engineering Spend	<profile_fingerprint_sha256>
+procurement	procurement	Procurement	<profile_fingerprint_sha256>
+data-api-buyer	data	Data API Buyer	<profile_fingerprint_sha256>
+support-automation	support	Support Automation	<profile_fingerprint_sha256>
+finance-controls	finance	Finance Controls	<profile_fingerprint_sha256>
+growth-marketing	marketing	Growth Marketing	<profile_fingerprint_sha256>
+```
+
+## 2) Initialize a profile
+
+Installed CLI:
+
+```bash
+npx settld profile init engineering-spend --out ./profiles/engineering-spend.profile.json
+```
+
+Repo checkout:
+
+```bash
+./bin/settld.js profile init engineering-spend --out ./profiles/engineering-spend.profile.json
+```
+
+Example output:
+
+```text
+ok	engineering-spend	/home/you/repo/profiles/engineering-spend
+```
+
+## 3) Validate profile schema + semantics
+
+Installed CLI:
+
+```bash
+npx settld profile validate ./profiles/engineering-spend.profile.json --format json
+```
+
+Repo checkout:
+
+```bash
+./bin/settld.js profile validate ./profiles/engineering-spend.profile.json --format json
+```
+
+Example output:
+
+```json
+{
+  "schemaVersion": "SettldProfileValidationReport.v1",
+  "ok": true,
+  "profileId": "engineering-spend",
+  "profileFingerprintVersion": "SettldProfileFingerprint.v1",
+  "profileFingerprint": "<sha256>",
+  "errors": [],
+  "warnings": []
+}
+```
+
+## 4) Simulate policy decisions
+
+Installed CLI:
+
+```bash
+npx settld profile simulate ./profiles/engineering-spend.profile.json --format json
+```
+
+Repo checkout:
+
+```bash
+./bin/settld.js profile simulate ./profiles/engineering-spend.profile.json --format json
+```
+
+Example output:
+
+```json
+{
+  "schemaVersion": "SettldProfileSimulationReport.v1",
+  "ok": true,
+  "profileId": "engineering-spend",
+  "decision": "allow",
+  "requiredApprovers": 0,
+  "approvalsProvided": 0,
+  "selectedApprovalTier": "auto",
+  "reasons": [],
+  "reasonCodes": [],
+  "reasonDetails": [],
+  "reasonRegistryVersion": "SettldProfileSimulationReasonRegistry.v1",
+  "profileFingerprintVersion": "SettldProfileFingerprint.v1",
+  "profileFingerprint": "<sha256>"
+}
+```
+
+To simulate with explicit scenario data:
+
+```bash
+./bin/settld.js profile simulate ./profiles/engineering-spend.profile.json --scenario ./test/fixtures/profile/scenario-allow.json --format json
+```
+
+## 5) Apply profile to runtime
+
+Set runtime connection/auth values:
+
+```bash
+export SETTLD_BASE_URL=http://127.0.0.1:3000
+export SETTLD_TENANT_ID=tenant_default
+export SETTLD_API_KEY=sk_runtime_apply
+# optional override:
+export SETTLD_SPONSOR_WALLET_REF=wallet_ops_default
+```
+
+Dry-run first (no live writes):
+
+```bash
+./bin/settld.js profile apply ./profiles/engineering-spend.profile.json --dry-run --format json
+```
+
+Then execute live apply:
+
+```bash
+./bin/settld.js profile apply ./profiles/engineering-spend.profile.json --format json
+```
+
+`profile apply` also accepts runtime-prefixed aliases:
+`SETTLD_RUNTIME_BASE_URL`, `SETTLD_RUNTIME_TENANT_ID`, `SETTLD_RUNTIME_BEARER_TOKEN`.
+
+## Common troubleshooting
+
+- `unknown profile`: run `settld profile list` and use one of the listed IDs.
+- `validation failed`: fix reported schema/semantic errors, then rerun `profile validate`.
+- `scenario file not found`: pass an existing JSON scenario path to `profile simulate`.
+- `profile apply missing runtime config`: set runtime base URL, tenant ID, bearer token, and wallet ref before running live apply.

package/docs/QUICKSTART_RELEASE_VERIFY.md

@@ -0,0 +1,39 @@
+# Quickstart: Verify a Settld Release (Authenticity)
+
+This verifies Settld **distribution artifacts** (npm tarballs, conformance pack, audit packet) using a signed `ReleaseIndex.v1` rooted in a release trust file.
+
+## Offline verification (recommended)
+
+1) Download a release’s assets into a directory (example: `./release/`), including:
+
+- `release_index_v1.json`
+- `release_index_v1.sig`
+- every artifact listed in `release_index_v1.json.artifacts[]`
+
+2) Verify using the pinned release trust roots:
+
+```sh
+settld-release verify --dir ./release --trust-file trust/release-trust.json --format json --explain
+```
+
+- Exit code `0` means verified.
+- `--format json` prints `VerifyReleaseOutput.v1` to stdout (pipe-safe, deterministic).
+- `--explain` prints deterministic diagnostics to stderr.
+
+## Mirror/HTTP verification (base URL)
+
+If your org mirrors release assets under a single base URL:
+
+```sh
+settld-release verify --base-url https://example.com/settld/releases/v1.0.0-rc.1/ --trust-file trust/release-trust.json --format json --explain
+```
+
+This downloads `release_index_v1.json`, `release_index_v1.sig`, then downloads every artifact referenced by the index (relative to the base URL) into a temp directory before verifying.
+
+## Trust domains (important)
+
+Release authenticity trust roots are **separate** from bundle verification trust roots.
+
+- Release trust: `trust/release-trust.json`
+- Bundle verification trust: `SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON` / `trust.json` (see `docs/spec/TRUST_ANCHORS.md`)
+

package/docs/QUICKSTART_SDK.md

@@ -0,0 +1,125 @@
+# Quickstart: First verified agent run with the SDK
+
+Goal: run one end-to-end agent transaction (register identities, append run events, verify `green`, release settlement) using `SettldClient.firstVerifiedRun(...)`.
+
+## 0) Install deps
+
+```sh
+npm ci
+```
+
+## Fast Path (recommended)
+
+Use the helper scripts to avoid manual export churn across shells:
+
+```sh
+npm run dev:env:init
+# edit .env.dev with your DATABASE_URL once
+```
+
+Start API:
+
+```sh
+npm run dev:start
+```
+
+In another shell:
+
+```sh
+source scripts/dev/env.sh
+npm run dev:sdk:first-run
+```
+
+Run the full billing + dispute + arbitration doctor flow:
+
+```sh
+source scripts/dev/env.sh
+npm run dev:billing:doctor
+```
+
+Optional: make `sdk:first-run` create a disputable settlement window:
+
+```sh
+SETTLD_SDK_DISPUTE_WINDOW_DAYS=3 npm run sdk:first-run
+```
+
+## 1) Start the API with a local ops token
+
+```sh
+export PROXY_OPS_TOKEN=dev_ops_token
+npm run dev:api
+```
+
+## 2) Create an API key for SDK calls
+
+In a second shell:
+
+```sh
+export SETTLD_BASE_URL=http://127.0.0.1:3000
+export SETTLD_TENANT_ID=tenant_default
+export SETTLD_API_KEY="$(
+  curl -sS -X POST "$SETTLD_BASE_URL/ops/api-keys" \
+    -H "authorization: Bearer $PROXY_OPS_TOKEN" \
+    -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+    -H "content-type: application/json" \
+    -d '{"scopes":["ops_read","ops_write","finance_read","finance_write","audit_read"],"description":"sdk quickstart"}' \
+  | jq -r '.keyId + "." + .secret'
+)"
+```
+
+## 3) Run the SDK example
+
+```sh
+node scripts/examples/sdk-first-verified-run.mjs
+```
+
+Expected output:
+
+```json
+{
+  "runId": "run_sdk_...",
+  "payeeAgentId": "agt_payee_...",
+  "payerAgentId": "agt_payer_...",
+  "runStatus": "completed",
+  "verificationStatus": "green",
+  "settlementStatus": "released"
+}
+```
+
+## 4) Use the helper directly in code
+
+```js
+import { SettldClient } from "./packages/api-sdk/src/index.js";
+
+const client = new SettldClient({
+  baseUrl: process.env.SETTLD_BASE_URL,
+  tenantId: process.env.SETTLD_TENANT_ID,
+  apiKey: process.env.SETTLD_API_KEY,
+  xApiKey: process.env.SETTLD_X_API_KEY // optional for Magic Link deployments that enforce x-api-key
+});
+
+const result = await client.firstVerifiedRun({
+  payeeAgent: { publicKeyPem: "...", owner: { ownerType: "service", ownerId: "svc_a" } },
+  payerAgent: { publicKeyPem: "...", owner: { ownerType: "service", ownerId: "svc_b" } },
+  payerCredit: { amountCents: 5000 },
+  settlement: { amountCents: 1200 },
+  run: { taskType: "translation" }
+});
+```
+
+## 5) Pull tenant analytics + trust graph (Magic Link)
+
+```js
+const analytics = await client.getTenantAnalytics("tenant_default", { month: "2026-02", bucket: "day", limit: 20 });
+const graph = await client.getTenantTrustGraph("tenant_default", { month: "2026-02", minRuns: 1, maxEdges: 200 });
+const diff = await client.diffTenantTrustGraph("tenant_default", { baseMonth: "2026-01", compareMonth: "2026-02", limit: 50 });
+```
+
+Or run the prebuilt script:
+
+```sh
+SETTLD_BASE_URL=http://127.0.0.1:8787 \
+SETTLD_TENANT_ID=tenant_default \
+SETTLD_X_API_KEY=test_key \
+npm run sdk:analytics
+```

package/docs/QUICKSTART_SDK_PYTHON.md

@@ -0,0 +1,111 @@
+# Quickstart: First verified agent run (Python SDK)
+
+Goal: run one end-to-end agent transaction (register identities, append run events, verify `green`, release settlement) using Python.
+
+## 0) Install deps
+
+```sh
+npm ci
+```
+
+## 1) Start the API with a local ops token
+
+```sh
+export PROXY_OPS_TOKEN=dev_ops_token
+npm run dev:api
+```
+
+## 2) Create an API key for SDK calls
+
+In a second shell:
+
+```sh
+export SETTLD_BASE_URL=http://127.0.0.1:3000
+export SETTLD_TENANT_ID=tenant_default
+export SETTLD_API_KEY="$(
+  curl -sS -X POST "$SETTLD_BASE_URL/ops/api-keys" \
+    -H "authorization: Bearer $PROXY_OPS_TOKEN" \
+    -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+    -H "content-type: application/json" \
+    -d '{"scopes":["ops_read","ops_write","finance_read","finance_write","audit_read"],"description":"python sdk quickstart"}' \
+  | jq -r '.keyId + "." + .secret'
+)"
+```
+
+## 3) Run the Python SDK example
+
+```sh
+PYTHONDONTWRITEBYTECODE=1 python3 scripts/examples/sdk-first-verified-run.py
+```
+
+Expected output:
+
+```json
+{
+  "runId": "run_sdk_py_...",
+  "payeeAgentId": "agt_py_payee_...",
+  "payerAgentId": "agt_py_payer_...",
+  "runStatus": "completed",
+  "verificationStatus": "green",
+  "settlementStatus": "released"
+}
+```
+
+## 4) Use the helper directly in code
+
+```python
+from settld_api_sdk import SettldClient
+
+client = SettldClient(
+    base_url="http://127.0.0.1:3000",
+    tenant_id="tenant_default",
+    api_key="keyId.secret",
+    x_api_key="magic_link_api_key",  # optional for Magic Link deployments that enforce x-api-key
+)
+
+result = client.first_verified_run(
+    {
+        "payee_agent": {"publicKeyPem": "...", "owner": {"ownerType": "service", "ownerId": "svc_a"}},
+        "payer_agent": {"publicKeyPem": "...", "owner": {"ownerType": "service", "ownerId": "svc_b"}},
+        "payer_credit": {"amountCents": 5000},
+        "settlement": {"amountCents": 1200},
+        "run": {"taskType": "translation"},
+    }
+)
+```
+
+## 5) Run a paid marketplace RFQ flow
+
+```sh
+PYTHONDONTWRITEBYTECODE=1 python3 scripts/examples/sdk-first-paid-rfq.py
+```
+
+Expected output:
+
+```json
+{
+  "rfqId": "rfq_py_...",
+  "runId": "run_rfq_py_...",
+  "posterAgentId": "agt_py_poster_...",
+  "bidderAgentId": "agt_py_bidder_...",
+  "verificationStatus": "green",
+  "settlementStatus": "released"
+}
+```
+
+## 6) Pull tenant analytics + trust graph (Magic Link)
+
+```python
+analytics = client.get_tenant_analytics("tenant_default", {"month": "2026-02", "bucket": "day", "limit": 20})
+graph = client.get_tenant_trust_graph("tenant_default", {"month": "2026-02", "minRuns": 1, "maxEdges": 200})
+diff = client.diff_tenant_trust_graph("tenant_default", {"baseMonth": "2026-01", "compareMonth": "2026-02", "limit": 50})
+```
+
+Or run the prebuilt script:
+
+```sh
+SETTLD_BASE_URL=http://127.0.0.1:8787 \
+SETTLD_TENANT_ID=tenant_default \
+SETTLD_X_API_KEY=test_key \
+npm run sdk:analytics:py
+```

package/docs/QUICKSTART_VERIFY.md

@@ -0,0 +1,54 @@
+# Quickstart: Verify a bundle
+
+Goal: verify a Settld bundle directory and produce a stable machine-readable receipt (`VerifyCliOutput.v1`) suitable for CI gating and audit retention.
+
+## From source (this repo)
+
+Install dependencies:
+
+```sh
+npm ci
+```
+
+Verify a bundle fixture (strict):
+
+```sh
+export SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON="$(node -e "import fs from 'node:fs'; const t=JSON.parse(fs.readFileSync('test/fixtures/bundles/v1/trust.json','utf8')); process.stdout.write(JSON.stringify(t.governanceRoots||{}))")"
+node packages/artifact-verify/bin/settld-verify.js --format json --strict --job-proof test/fixtures/bundles/v1/jobproof/strict-pass > settld-verify-output.json
+```
+
+Optional: emit SARIF for GitHub annotations:
+
+```sh
+node packages/artifact-verify/bin/settld-verify.js --format sarif --strict --job-proof test/fixtures/bundles/v1/jobproof/strict-pass > settld-verify.sarif
+```
+
+## Strict vs non-strict
+
+- **Strict** (`--strict`): audit posture; missing required protocol surfaces are hard failures.
+- **Non-strict** (omit `--strict`): compatibility posture; missing legacy surfaces become warnings.
+
+## Warnings and CI gating
+
+- Warnings are structured codes (see `docs/spec/WARNINGS.md`).
+- To fail CI when warnings exist, add `--fail-on-warnings`.
+
+## Trust anchors
+
+Strict verification needs trusted governance root keys. Provide them via:
+
+- `SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON`
+- `SETTLD_TRUSTED_TIME_AUTHORITY_KEYS_JSON` (only if you want to verify timestamp proofs)
+
+See `docs/spec/TRUST_ANCHORS.md`.
+
+## Output + provenance
+
+`settld-verify --format json` emits `VerifyCliOutput.v1`:
+
+- `ok`: overall CLI verdict (includes `--fail-on-warnings`)
+- `verificationOk`: underlying verification verdict
+- `errors[]` / `warnings[]`: stable codes, deterministically sorted
+- `tool.version` / `tool.commit`: provenance identifiers
+
+If `tool.version` or `tool.commit` cannot be determined, you may see warnings like `TOOL_VERSION_UNKNOWN` / `TOOL_COMMIT_UNKNOWN` (see `docs/spec/TOOL_PROVENANCE.md`).