@oked/sdk 0.6.19 → 0.6.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,12 +1,13 @@
1
1
  # @oked/sdk
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/@oked/sdk.svg)](https://www.npmjs.com/package/@oked/sdk)
4
- [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE)
5
- [![Types: included](https://img.shields.io/npm/types/@oked/sdk.svg)](./dist/index.d.ts)
4
+ [![License: Apache-2.0](https://img.shields.io/npm/l/@oked/sdk.svg)](./LICENSE)
6
5
 
7
- Core library - programmatic approval API for AI agents. Sends sensitive actions to the OKed backend, waits for a human decision, and resolves only when the user approves or denies.
6
+ Programmatic approval API for AI agents. Send a sensitive action to the OKed backend, wait for a person, and continue only when they approve.
8
7
 
9
- Use this package directly from any Node.js agent (OpenAI SDK, LangChain, custom). For drop-in integrations, see [`@oked/claude-code`](../claude-code) or [`@oked/openclaw`](../openclaw).
8
+ Use this package from any Node.js agent. For drop-in integrations, see [`@oked/claude-code`](../claude-code), [`@oked/claude-agent-sdk`](../claude-agent-sdk), and [`@oked/openclaw`](../openclaw).
9
+
10
+ Decisions are made in Telegram and on the [web dashboard](https://oked.ai/dashboard). The iPhone app is coming soon. [Sign up](https://oked.ai/signup) to get an API key.
10
11
 
11
12
  ## Install
12
13
 
@@ -14,6 +15,8 @@ Use this package directly from any Node.js agent (OpenAI SDK, LangChain, custom)
14
15
  npm install @oked/sdk
15
16
  ```
16
17
 
18
+ Node.js 18 or newer.
19
+
17
20
  ## Quick start
18
21
 
19
22
  ```ts
@@ -36,78 +39,91 @@ if (!result.approved) {
36
39
  }
37
40
  ```
38
41
 
42
+ The approval window is 10 minutes. The client waits 630 seconds (`630000` ms, `DEFAULT_APPROVAL_TIMEOUT_MS`), 30 seconds past that window, so the backend's `timeout` answer arrives before the client aborts. A timeout is a denial. If you raise `timeout`, raise the harness hook limit above it. Otherwise the process can be killed before the deny is written.
43
+
39
44
  ## Configuration
40
45
 
41
- Pass to `new OKedClient(config)`:
46
+ Pass any of these to `new OKedClient(config)`. Constructor values win over environment variables, which win over `~/.oked/config.json`.
42
47
 
43
48
  | Key | Type | Default | Description |
44
49
  |---|---|---|---|
45
- | `apiKey` | `string` | `OKED_API_KEY` env | Your OKed API key. Required. |
46
- | `backendUrl` | `string` | `https://api.oked.ai` | Override the OKed backend URL. |
47
- | `timeout` | `number` | `630000` | Per-approval timeout in ms (10.5 minutes, just above the backend's 10 minute expiry, so the backend's `timeout` answer arrives first). If you raise it, raise the harness hook timeout to match: it must stay above this value so the fail-safe deny is written before the hook process is killed. |
48
- | `strictFailClosed` | `boolean` | `false` | When true, backend outages deny every tier. When false, outages deny only `high_stakes` and allow lower tiers. |
50
+ | `apiKey` | `string` | `OKED_API_KEY`, then the config file | OKed API key. Required for `approve`. |
51
+ | `backendUrl` | `string` | `https://api.oked.ai` | Backend URL. |
52
+ | `timeout` | `number` | `630000` | How long to wait for a decision, in milliseconds. See above. |
53
+ | `strictFailClosed` | `boolean` | `false` | When true, an unreachable backend denies every tier. When false, it denies only `high_stakes`. |
49
54
  | `requireReceipt` | `boolean` | `true` | Deny an approval that arrives without a signed receipt. A receipt that is present but invalid always denies. Set `false` (env `OKED_REQUIRE_RECEIPT=0`) only for a backend that does not sign receipts. |
50
- | `receiptKeysUrl` | `string` | `https://api.oked.ai/.well-known/oked-receipt-keys.json` | Where to fetch a receipt key the SDK has not seen. Independent of `backendUrl`; https only, except loopback. |
51
- | `receiptKeys` | `ReceiptKey[]` | | Verify with exactly these keys and never fetch (self-hosted backends, tests). |
52
- | `client` | `string` | | Your integration's name and version, e.g. `my-agent@1.2.0`. Recorded in receipts. |
53
- | `source` | `string` | `"sdk"` | Where requests come from. Part of each receipt's subject. |
55
+ | `receiptKeysUrl` | `string` | `https://api.oked.ai/.well-known/oked-receipt-keys.json` | Where to fetch a receipt key the SDK has not seen. Independent of `backendUrl`. https only, except loopback. |
56
+ | `receiptKeys` | `ReceiptKey[]` | | Verify with exactly these keys and never fetch. For self-hosted backends and tests. |
57
+ | `rulesCacheTtlMs` | `number` | `300000` | How long the on-disk rules cache stays fresh. Env `OKED_RULES_CACHE_TTL` is in seconds. |
58
+ | `heartbeatIntervalMs` | `number` | `86400000` | Minimum gap between presence pings. Env `OKED_HEARTBEAT_INTERVAL` is in seconds. |
59
+ | `client` | `string` | | Your integration's name and version, for example `my-agent@1.2.0`. Recorded on the receipt. |
60
+ | `source` | `string` | `"sdk"` | Where the request came from. Part of the receipt subject. |
54
61
 
55
62
  ## API
56
63
 
57
64
  ### `approve(request)`
58
65
 
59
- Request an approval for a sensitive action. Resolves when the user responds, the request times out, or the backend denies.
60
-
61
- Request fields:
66
+ Ask for a decision. Resolves when the person responds, the request times out, or the backend returns an error as a thrown exception (see below).
62
67
 
63
68
  | Field | Type | Required | Description |
64
69
  |---|---|---|---|
65
- | `action` | `string` | yes | Short action identifier (e.g. `"deploy"`, `"send_email"`). |
66
- | `description` | `string` | yes | Human-readable summary shown in the approval UI. |
67
- | `tier` | `"safe" \| "warning" \| "review" \| "high_stakes"` | yes | Risk tier. Use `classify()` if unsure. |
68
- | `tool_input` | `unknown` | no | Raw tool arguments, included in the audit log. |
69
- | `session_id` | `string` | no | Groups related approvals under one session. |
70
- | `cwd` | `string` | no | Working directory, shown in the UI for context. |
71
-
72
- Response fields:
70
+ | `action` | `string` | yes | Short action id, for example `"deploy"`. |
71
+ | `description` | `string` | yes | Text shown on the approval card. |
72
+ | `tier` | `"safe" \| "warning" \| "review" \| "high_stakes"` | yes | Risk tier. Use `classify()` if you are not sure. |
73
+ | `fields` | `Record<string, string>` | no | Card fields (title, target, body, and so on). |
74
+ | `tool_input` | `unknown` | no | Raw tool arguments. Included in the receipt subject. |
75
+ | `session_id` | `string` | no | Groups related approvals. |
76
+ | `cwd` | `string` | no | Working directory, shown for context. |
73
77
 
74
78
  | Field | Type | Description |
75
79
  |---|---|---|
76
- | `approved` | `boolean` | `true` only when the user approved. |
77
- | `approval_id` | `string \| null` | Opaque id for logs / audit. |
78
- | `decision` | `"approved" \| "denied" \| "timeout"` | Exact outcome. |
79
- | `receipt` | `SignedReceipt` | The signed receipt for this decision, already verified: OKed's signature, this request, this decision, and the exact action you sent. See [docs/receipts.md](../../docs/receipts.md). |
80
+ | `approved` | `boolean` | `true` only when the person approved. |
81
+ | `approval_id` | `string \| null` | Id for logs. `null` when the backend created no request row. |
82
+ | `decision` | `"approved" \| "denied" \| "timeout"` | Outcome. |
83
+ | `receipt` | `SignedReceipt \| undefined` | Signed receipt, already verified against this request, this decision, and the exact action you sent. Absent for some denials and timeouts that carry no receipt. See [docs/receipts.md](../../docs/receipts.md). |
80
84
 
81
85
  ### `ping()`
82
86
 
83
- Returns `true` when the backend is reachable. Use for startup health checks.
87
+ Returns `true` when `GET {backendUrl}/health` succeeds within 3 seconds.
88
+
89
+ ### `getRules()` and `heartbeat()`
90
+
91
+ `getRules()` returns the operator's rules, cached on disk. `heartbeat()` sends a throttled presence ping and never throws. Integrations call both. You do not need them to use `approve`.
84
92
 
85
93
  ### Helpers
86
94
 
87
- - `classify(input)` - classifies a shell command or tool call into a risk tier.
88
- - `describe(input)` - generates a human-readable description for the approval UI.
95
+ - `classify(toolName, toolInput)` returns a risk tier for a tool call.
96
+ - `describe(toolName, toolInput, ctx?)` returns a one-line description.
97
+ - `describeFields(toolName, toolInput, ctx?)` returns the card fields.
89
98
 
90
- Full type definitions ship with the package (`dist/index.d.ts`).
99
+ Full type definitions ship in the package (`dist/index.d.ts`).
91
100
 
92
101
  ## Environment
93
102
 
94
103
  | Var | Required | Description |
95
104
  |---|---|---|
96
- | `OKED_API_KEY` | yes, unless passed in code | Your OKed API key. |
105
+ | `OKED_API_KEY` | yes, unless passed in code or saved by `oked init` | OKed API key. |
97
106
  | `OKED_BACKEND_URL` | no | Override the hosted backend URL. |
98
- | `OKED_STRICT_FAIL_CLOSED` | no | Set to `1` or `true` to deny every sensitive action when the backend is unreachable. |
99
- | `OKED_REQUIRE_RECEIPT` | no | Set to `0` to allow an approval that has no receipt (a backend that does not sign receipts). On by default. |
100
- | `OKED_RECEIPT_KEYS_URL` | no | Where to fetch receipt keys (default OKed's published set). |
107
+ | `OKED_STRICT_FAIL_CLOSED` | no | `1` or `true` denies every sensitive action when the backend is unreachable. |
108
+ | `OKED_REQUIRE_RECEIPT` | no | `0` allows an approval that has no receipt. On by default. |
109
+ | `OKED_RECEIPT_KEYS_URL` | no | Where to fetch receipt keys. Default is OKed's published set. |
110
+ | `OKED_RULES_CACHE_TTL` | no | Rules cache TTL, in seconds. Default 300. |
111
+ | `OKED_HEARTBEAT_INTERVAL` | no | Minimum seconds between heartbeats. Default 86400. |
101
112
 
102
113
  ## Degraded-mode behavior
103
114
 
104
- Explicit user denials return `{ approved: false }` and should always be treated as final. Invalid API keys throw `OKedAuthError` and should deny. A receipt that does not verify, or an approval with no receipt, throws `OKedReceiptError` and should deny. A request the backend accepted but nobody answered in time returns `decision: "timeout"`, never an outage. If the backend is unreachable, `OKedBackendUnreachableError` lets integrations apply degraded mode: `high_stakes` denies, while lower tiers may proceed unless `strictFailClosed` is enabled. Unexpected errors should be treated as deny.
115
+ Explicit denials return `{ approved: false }` and are final. Invalid API keys throw `OKedAuthError`. A receipt that does not verify, or an approval with no receipt while `requireReceipt` is on, throws `OKedReceiptError`. A request the backend accepted and nobody answered returns `decision: "timeout"`, not an outage error. HTTP 429 throws `OKedTooManyPendingError` (too many approvals are already waiting). Other HTTP errors throw `OKedHttpError`.
116
+
117
+ If the backend is unreachable, `OKedBackendUnreachableError` is the outage signal. `high_stakes` denies. Lower tiers may proceed unless `strictFailClosed` is set. Treat anything else as a deny.
105
118
 
106
119
  ## Development
107
120
 
121
+ From the repo root:
122
+
108
123
  ```bash
109
124
  npm install
110
125
  npm run build
126
+ npm test
111
127
  ```
112
128
 
113
129
  ## License
package/dist/classify.js CHANGED
@@ -17,12 +17,14 @@ import { TIER_ORDER } from "./degraded.js";
17
17
  // Tier 3 - review: push notification, tap to approve. Prompt-worthy but not
18
18
  // catastrophic: sensitive-path writes (~/.ssh, shell rc, system
19
19
  // dirs, OKed's own config), sudo, outward message/email sends,
20
- // curl POST/PUT/PATCH with an inline body.
20
+ // curl POST/PUT/PATCH with an inline body, other cloud CLI writes
21
+ // (create, update, upload, preview deploy, kubectl apply/exec).
21
22
  // Tier 4 - high_stakes: push + number matching. Destructive / irreversible /
22
23
  // external: rm of non-temp data, DROP/TRUNCATE/DELETE FROM,
23
24
  // git push --force / reset --hard / branch -D, mkfs / dd-to-device /
24
25
  // shutdown, curl DELETE / file upload / pay-or-send API, ssh/scp,
25
- // npm publish, kill.
26
+ // npm publish, kill, cloud and cluster deletes, terraform apply /
27
+ // pulumi up, production deploys, Stripe CLI writes.
26
28
  // Tools that are always safe (read-only, no side effects)
27
29
  const SAFE_TOOLS = new Set([
28
30
  "Read",
@@ -325,6 +327,277 @@ const REVIEW_COMMANDS = [
325
327
  /^gh\s+run\s+(?:cancel|rerun)\b/,
326
328
  /^gh\s+(?:gist|label)\s+(?:create|edit)\b/,
327
329
  ];
330
+ // Cloud, cluster, infrastructure, deploy and payment CLIs change live systems
331
+ // that other people use, so the `safe` default for an unknown command is wrong
332
+ // for their writes. The CLI's own subcommand words pick the tier: a delete, an
333
+ // infrastructure apply, a production deploy or a payment → high_stakes; any
334
+ // other write (create, update, upload, a preview deploy, exec into a pod) →
335
+ // review; reads (`aws s3 ls`, `kubectl get`, `terraform plan`) stay safe, and so
336
+ // do `--help` and dry runs. Matched on the stage's command word, so the CLI name
337
+ // in an argument or a commit message is not the command.
338
+ // A package runner in front of the CLI (`npx vercel@latest --prod`).
339
+ const CLI_RUNNER_RE = /^(?:npx|bunx|pnpx|(?:pnpm|yarn|bun)\s+(?:dlx|exec|x))\s+(?:-\S+\s+)*/;
340
+ // `--dry-run=none` (kubectl) and `--dry-run=false` are real runs.
341
+ const CLI_PREVIEW_ARG_RE = /^(?:--help|-help|--dry-?run(?:=(?:true|client|server))?)$/;
342
+ // Subcommand words that delete, tear down or redeploy a live resource, and
343
+ // words that create or change one. A hyphenated word (`delete-stack`,
344
+ // `add-iam-policy-binding`) is read by its first part.
345
+ const CLOUD_DELETE_WORDS = new Set(["delete", "destroy", "terminate", "purge", "remove", "rm", "rb", "uninstall", "drain"]);
346
+ const CLOUD_DEPLOY_WORDS = new Set(["deploy", "rollback", "promote"]);
347
+ const CLOUD_WRITE_WORDS = new Set([
348
+ "create", "update", "patch", "apply", "set", "unset", "add", "put", "push", "upload", "import",
349
+ "start", "stop", "restart", "reboot", "reset", "resize", "scale", "enable", "disable", "attach",
350
+ "detach", "move", "rename", "restore", "cancel", "upgrade", "install", "invoke", "call", "execute",
351
+ "exec", "ssh", "scp", "submit", "connect", "failover", "issue", "transfer", "clone", "extend",
352
+ "launch", "console",
353
+ ]);
354
+ function cloudWordTier(word) {
355
+ const [head, ...rest] = word.split("-");
356
+ if (rest.length === 0) {
357
+ if (CLOUD_DELETE_WORDS.has(word) || CLOUD_DEPLOY_WORDS.has(word))
358
+ return "high_stakes";
359
+ return CLOUD_WRITE_WORDS.has(word) ? "review" : "safe";
360
+ }
361
+ if (/^(?:delete|destroy|terminate|purge|deregister)$/.test(head))
362
+ return "high_stakes";
363
+ return CLOUD_WRITE_WORDS.has(head) || head === "remove" ? "review" : "safe";
364
+ }
365
+ function maxCloudWordTier(words) {
366
+ return words.reduce((t, w) => maxTier(t, cloudWordTier(w)), "safe");
367
+ }
368
+ /** The non-flag arguments, without the values of `valueFlags` and redirects. */
369
+ function cliPositionals(args, valueFlags = new Set()) {
370
+ const out = [];
371
+ for (let i = 0; i < args.length; i++) {
372
+ const a = args[i];
373
+ if (/^(?:\d|&)?>{1,2}$|^<$/.test(a)) {
374
+ i++;
375
+ continue;
376
+ } // `> log`
377
+ if (/^(?:\d|&)?>|^</.test(a))
378
+ continue; // `2>&1`, `>log`
379
+ if (a.startsWith("-")) {
380
+ if (valueFlags.has(a))
381
+ i++;
382
+ continue;
383
+ }
384
+ out.push(a);
385
+ }
386
+ return out;
387
+ }
388
+ /** `aws s3`, `gsutil`, `gcloud storage`: delete, upload, or download. */
389
+ function objectStoreTier(op, pos, args, scheme) {
390
+ if (op === "rm" || op === "rb")
391
+ return "high_stakes";
392
+ if (op === "mv" || op === "mb")
393
+ return "review";
394
+ if (op === "cp" || op === "sync" || op === "rsync") {
395
+ if (op !== "cp" && args.some((a) => /^(?:--delete|-d|--delete-unmatched-destination-objects)$/.test(a)))
396
+ return "high_stakes";
397
+ return (pos[pos.length - 1] ?? "").startsWith(scheme) ? "review" : "safe"; // to a bucket, or a download
398
+ }
399
+ return null;
400
+ }
401
+ const AWS_VALUE_FLAGS = new Set(["--profile", "--region", "--output", "--endpoint-url", "--query", "--color",
402
+ "--ca-bundle", "--cli-read-timeout", "--cli-connect-timeout", "--cli-binary-format"]);
403
+ // Operations that only read. An aws operation that is not a read is a write.
404
+ const AWS_READ_OP_RE = /^(?:describe|list|get|head|batch-get|search|scan|query|lookup|filter|select|estimate|validate|simulate|test|preview|wait|tail|ls|help|check|presign)(?:-|$)/;
405
+ const AWS_LOCAL_SERVICES = new Set(["configure", "sso", "sso-oidc", "sts", "help", "history"]);
406
+ function awsTier(args) {
407
+ const pos = cliPositionals(args, AWS_VALUE_FLAGS);
408
+ const [service, op] = pos;
409
+ if (!service || !op || AWS_LOCAL_SERVICES.has(service))
410
+ return "safe";
411
+ if (service === "s3")
412
+ return objectStoreTier(op, pos, args, "s3://") ?? (op === "ls" ? "safe" : "review");
413
+ if (/^(?:delete|terminate|purge|deregister|destroy)-/.test(op) || op === "deploy")
414
+ return "high_stakes";
415
+ return AWS_READ_OP_RE.test(op) ? "safe" : "review";
416
+ }
417
+ const KUBECTL_VALUE_FLAGS = new Set(["-n", "--namespace", "--context", "--kubeconfig", "--cluster", "--user",
418
+ "-s", "--server", "--as", "--as-group", "--token", "--request-timeout", "-l", "--selector", "-f",
419
+ "--filename", "-c", "--container", "-o", "--output"]);
420
+ const KUBECTL_WRITE_VERBS = new Set(["apply", "create", "patch", "replace", "edit", "scale", "autoscale", "set",
421
+ "label", "annotate", "taint", "cordon", "uncordon", "expose", "run", "exec", "cp", "attach", "debug", "certificate"]);
422
+ function kubectlTier(args) {
423
+ const [verb, sub] = cliPositionals(args, KUBECTL_VALUE_FLAGS);
424
+ if (verb === "delete" || verb === "drain")
425
+ return "high_stakes";
426
+ if (verb === "rollout")
427
+ return ["restart", "undo", "pause", "resume"].includes(sub) ? "review" : "safe";
428
+ return KUBECTL_WRITE_VERBS.has(verb) ? "review" : "safe";
429
+ }
430
+ function terraformTier(args) {
431
+ let [verb, sub] = cliPositionals(args);
432
+ // terragrunt `run-all apply`
433
+ if (verb === "run-all" || verb === "run")
434
+ [verb, sub] = cliPositionals(args).slice(1);
435
+ if (verb === "apply" || verb === "destroy")
436
+ return "high_stakes";
437
+ if (["import", "taint", "untaint", "force-unlock", "refresh"].includes(verb))
438
+ return "review";
439
+ if (verb === "state" && ["rm", "mv", "push", "replace-provider"].includes(sub))
440
+ return "review";
441
+ if (verb === "workspace" && sub === "delete")
442
+ return "review";
443
+ return "safe";
444
+ }
445
+ const VERCEL_VALUE_FLAGS = new Set(["--scope", "-S", "--token", "-t", "--cwd", "-A", "--local-config", "-Q",
446
+ "--global-config", "--target", "-e", "--env", "-b", "--build-env", "-m", "--meta", "--regions", "--archive"]);
447
+ // Subcommands other than a deploy. A first word that is none of these is a
448
+ // path to deploy, as vercel reads it.
449
+ const VERCEL_SUBCOMMANDS = new Set(["alias", "bisect", "blob", "build", "cache", "certs", "curl", "dev", "dns",
450
+ "domains", "env", "git", "help", "init", "inspect", "install", "integration", "link", "list", "login",
451
+ "logout", "logs", "ls", "mcp", "microfrontends", "open", "project", "projects", "promote", "pull",
452
+ "redeploy", "remove", "rm", "rollback", "switch", "target", "teams", "telemetry", "whoami"]);
453
+ function vercelTier(args) {
454
+ const [sub, op] = cliPositionals(args, VERCEL_VALUE_FLAGS);
455
+ const prod = args.some((a, i) => a === "--prod" || a === "--target=production" ||
456
+ (a === "--target" && args[i + 1] === "production"));
457
+ if (sub === undefined || sub === "deploy" || !VERCEL_SUBCOMMANDS.has(sub))
458
+ return prod ? "high_stakes" : "review";
459
+ if (sub === "redeploy")
460
+ return prod ? "high_stakes" : "review";
461
+ if (["rm", "remove", "promote", "rollback"].includes(sub))
462
+ return "high_stakes";
463
+ if (sub === "alias")
464
+ return op === "set" || op === "rm" || op === "remove" ? "high_stakes" : "safe";
465
+ if (["env", "domains", "dns", "certs", "project", "projects", "teams", "blob", "integration"].includes(sub)) {
466
+ return op === undefined ? "safe" : cloudWordTier(op);
467
+ }
468
+ return "safe";
469
+ }
470
+ /** Tier of a single stage that runs a cloud CLI, or null for any other stage. */
471
+ function classifyCloudCliStage(stage) {
472
+ // The same wrappers the delete scan strips (`xargs kubectl delete`, `do aws
473
+ // s3 rb …`, `time terraform apply`), then a package runner.
474
+ const args = splitArgs(stage.replace(DELETE_LEAD, "").replace(CLI_RUNNER_RE, ""));
475
+ const tool = (args.shift() ?? "").replace(/^.*\//, "").replace(/(?<=.)@.*$/, "");
476
+ const known = ["aws", "kubectl", "helm", "terraform", "tofu", "terragrunt", "pulumi", "cdk", "serverless",
477
+ "sls", "gcloud", "gsutil", "az", "doctl", "eksctl", "vercel", "netlify", "fly", "flyctl", "heroku",
478
+ "wrangler", "firebase", "stripe"];
479
+ if (!known.includes(tool))
480
+ return null;
481
+ // Arguments after `--` belong to another command (`kubectl exec pod -- x
482
+ // --help`), so a `--help` there does not make this one a preview.
483
+ const sep = args.indexOf("--");
484
+ if ((sep === -1 ? args : args.slice(0, sep)).some((a) => CLI_PREVIEW_ARG_RE.test(a)))
485
+ return "safe";
486
+ const pos = cliPositionals(args);
487
+ if (pos[0] === "help")
488
+ return "safe";
489
+ const has = (re) => args.some((a) => re.test(a));
490
+ switch (tool) {
491
+ case "aws": return awsTier(args);
492
+ case "kubectl": return kubectlTier(args);
493
+ case "helm": {
494
+ const [verb] = cliPositionals(args, new Set(["-n", "--namespace", "--kube-context", "--kubeconfig"]));
495
+ if (["uninstall", "delete", "del", "un", "rollback"].includes(verb))
496
+ return "high_stakes";
497
+ return ["install", "upgrade", "push"].includes(verb) ? "review" : "safe";
498
+ }
499
+ case "terraform":
500
+ case "tofu":
501
+ case "terragrunt": return terraformTier(args);
502
+ case "pulumi": {
503
+ const [verb, sub] = cliPositionals(args, new Set(["-s", "--stack", "-C", "--cwd"]));
504
+ if (["up", "update", "destroy"].includes(verb) || (verb === "stack" && sub === "rm"))
505
+ return "high_stakes";
506
+ if (["refresh", "import", "cancel"].includes(verb))
507
+ return "review";
508
+ return verb === "state" && ["delete", "move", "unprotect"].includes(sub) ? "review" : "safe";
509
+ }
510
+ case "cdk": return ["deploy", "destroy"].includes(pos[0]) ? "high_stakes" : pos[0] === "bootstrap" ? "review" : "safe";
511
+ case "serverless":
512
+ case "sls":
513
+ if (["deploy", "remove"].includes(pos[0]))
514
+ return "high_stakes";
515
+ return pos[0] === "invoke" && pos[1] !== "local" ? "review" : "safe";
516
+ case "gcloud":
517
+ case "az":
518
+ case "doctl":
519
+ case "eksctl": {
520
+ const flags = {
521
+ gcloud: ["--project", "--account", "--configuration", "--format", "--verbosity", "--impersonate-service-account"],
522
+ az: ["--subscription", "-o", "--output", "--query"],
523
+ doctl: ["--context", "-t", "--access-token", "-o", "--output", "--config"],
524
+ eksctl: [],
525
+ }[tool];
526
+ const words = cliPositionals(args, new Set(flags));
527
+ // Local CLI config and sign-in (`gcloud config set project x`).
528
+ const local = { gcloud: ["config", "auth", "components", "info", "init", "version", "topic"],
529
+ az: ["account", "config", "configure", "login", "logout", "extension", "version", "upgrade", "cloud", "find"],
530
+ doctl: ["auth", "version", "completion"], eksctl: ["version", "info"] }[tool];
531
+ if (local.includes(words[0]))
532
+ return "safe";
533
+ if (tool === "gcloud" && words[0] === "storage") {
534
+ const t = objectStoreTier(words[1], words, args, "gs://");
535
+ if (t !== null)
536
+ return t;
537
+ }
538
+ // The first word of gcloud, az and doctl is a product group (`gcloud
539
+ // deploy`, `gcloud run`), not a verb. eksctl is verb first.
540
+ return maxCloudWordTier(tool === "eksctl" ? words : words.slice(1));
541
+ }
542
+ case "gsutil": {
543
+ const words = cliPositionals(args, new Set(["-o", "-h", "-u"]));
544
+ const t = objectStoreTier(words[0], words, args, "gs://");
545
+ if (t !== null)
546
+ return t;
547
+ return words[1] === "set" || words[1] === "ch" || words[0] === "setmeta" ? "review" : "safe";
548
+ }
549
+ case "vercel": return vercelTier(args);
550
+ case "netlify": {
551
+ const words = cliPositionals(args, new Set(["--site", "--dir", "-d", "--auth", "--filter", "-a", "-s", "-m", "--message", "--alias"]));
552
+ if (words[0] === "deploy")
553
+ return has(/^(?:--prod|-p|--prodIfUnlocked|--prod-if-unlocked)$/) ? "high_stakes" : "review";
554
+ return cloudWordTier((words[0] ?? "").split(":").pop() ?? "");
555
+ }
556
+ case "fly":
557
+ case "flyctl": {
558
+ const words = cliPositionals(args, new Set(["-a", "--app", "-c", "--config", "-r", "--region", "--image", "-t", "--access-token"]));
559
+ return words.includes("run") ? maxTier("review", maxCloudWordTier(words)) : maxCloudWordTier(words);
560
+ }
561
+ case "heroku": {
562
+ const parts = (cliPositionals(args, new Set(["-a", "--app", "-r", "--remote"]))[0] ?? "").split(":");
563
+ const last = parts[parts.length - 1];
564
+ if (parts[0] === "pg" && ["reset", "copy", "push"].includes(last))
565
+ return "high_stakes";
566
+ return last === "run" ? "review" : cloudWordTier(last);
567
+ }
568
+ case "wrangler": {
569
+ const words = cliPositionals(args, new Set(["-c", "--config", "-e", "--env", "--name"]))
570
+ // `d1 execute` runs on a local database unless `--remote`.
571
+ .filter((w) => w !== "execute" || args.includes("--remote"));
572
+ return words.includes("publish") ? "high_stakes" : maxCloudWordTier(words);
573
+ }
574
+ case "firebase": {
575
+ const words = cliPositionals(args, new Set(["-P", "--project", "--only", "--except", "--token"]));
576
+ const parts = (words[0] ?? "").split(":");
577
+ const last = parts[parts.length - 1];
578
+ if (parts[0] === "emulators")
579
+ return "safe";
580
+ if (words[0] === "deploy" || words[0] === "hosting:disable")
581
+ return "high_stakes";
582
+ // A preview channel deploy (`hosting:channel:deploy`) does not reach the live site.
583
+ return last === "deploy" ? "review" : cloudWordTier(last);
584
+ }
585
+ case "stripe": {
586
+ const [resource, op] = cliPositionals(args, new Set(["--api-key", "--project-name", "-p", "--device-name",
587
+ "--color", "--log-level", "--config"]));
588
+ // A raw API write, or any resource operation that is not a read. Matches
589
+ // the curl rule for the Stripe API: it can move money.
590
+ if (resource === "post" || resource === "delete")
591
+ return "high_stakes";
592
+ const local = ["get", "listen", "logs", "login", "logout", "config", "samples", "trigger", "open",
593
+ "status", "version", "completion", "serve", "resources", "feedback", "community", "daemon", "plugin", "fixtures"];
594
+ if (!resource || !op || local.includes(resource))
595
+ return "safe";
596
+ return ["list", "retrieve", "search"].includes(op) ? "safe" : "high_stakes";
597
+ }
598
+ }
599
+ return null;
600
+ }
328
601
  /**
329
602
  * `gh api` is curl for GitHub: a mutating method, or fields without a method
330
603
  * (gh then sends a POST), is an outward write like a curl POST. A GraphQL call
@@ -1175,8 +1448,13 @@ function classifyBashCommand(command, ephemeralVars = new Set()) {
1175
1448
  * Shell-effect classification of a SINGLE, already-body-stripped stage. No SQL
1176
1449
  * detection here — that runs on the body-intact view in classifyBashCommand and
1177
1450
  * is folded in by the caller. Returns the stage's tier (default `safe`).
1451
+ * A cloud CLI tier is a floor: it never lowers what the other detectors find
1452
+ * (`kubectl exec pod -- curl -X DELETE …` stays high_stakes).
1178
1453
  */
1179
1454
  function classifyStageShellEffects(stage, ephemeralVars = new Set()) {
1455
+ return maxTier(classifyCloudCliStage(stage) ?? "safe", classifyStageEffects(stage, ephemeralVars));
1456
+ }
1457
+ function classifyStageEffects(stage, ephemeralVars) {
1180
1458
  // File deletion in COMMAND POSITION, per-stage so the ephemeral-temp carve-out
1181
1459
  // can win: deleting only throwaway temp files (/tmp, $TMPDIR, /var/folders, …)
1182
1460
  // → warning; any non-temp target (or the temp root itself) → high_stakes.
package/dist/describe.js CHANGED
@@ -1015,7 +1015,7 @@ function summarizeSql(sql, originalCommand) {
1015
1015
  * to X", "Delete email N", "Purge folder Y") instead of a raw shell line.
1016
1016
  *
1017
1017
  * Used for both the approval-card display (so the user sees "Send email to
1018
- * orendor@gmail.com" with the subject + sender, not a printf|himalaya
1018
+ * contact@oked.ai" with the subject + sender, not a printf|himalaya
1019
1019
  * pipeline) and the analytics `operation_kind`.
1020
1020
  *
1021
1021
  * Returns null if the command mentions himalaya but doesn't match a known
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oked/sdk",
3
- "version": "0.6.19",
3
+ "version": "0.6.21",
4
4
  "description": "OKed SDK - human approval layer for AI agents",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -45,7 +45,7 @@
45
45
  "access": "public"
46
46
  },
47
47
  "dependencies": {
48
- "@oked/receipt-core": "0.6.19"
48
+ "@oked/receipt-core": "0.6.21"
49
49
  },
50
50
  "devDependencies": {
51
51
  "@types/node": "^22.13.10",