@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 +53 -37
- package/dist/classify.js +280 -2
- package/dist/describe.js +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
# @oked/sdk
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@oked/sdk)
|
|
4
|
-
[](./dist/index.d.ts)
|
|
4
|
+
[](./LICENSE)
|
|
6
5
|
|
|
7
|
-
|
|
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
|
|
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
|
|
46
|
-
| `backendUrl` | `string` | `https://api.oked.ai` |
|
|
47
|
-
| `timeout` | `number` | `630000` |
|
|
48
|
-
| `strictFailClosed` | `boolean` | `false` | When true, backend
|
|
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
|
|
51
|
-
| `receiptKeys` | `ReceiptKey[]` | | Verify with exactly these keys and never fetch
|
|
52
|
-
| `
|
|
53
|
-
| `
|
|
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
|
-
|
|
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
|
|
66
|
-
| `description` | `string` | yes |
|
|
67
|
-
| `tier` | `"safe" \| "warning" \| "review" \| "high_stakes"` | yes | Risk tier. Use `classify()` if
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
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
|
|
77
|
-
| `approval_id` | `string \| null` |
|
|
78
|
-
| `decision` | `"approved" \| "denied" \| "timeout"` |
|
|
79
|
-
| `receipt` | `SignedReceipt` |
|
|
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
|
|
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(
|
|
88
|
-
- `describe(
|
|
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
|
|
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 |
|
|
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 |
|
|
99
|
-
| `OKED_REQUIRE_RECEIPT` | no |
|
|
100
|
-
| `OKED_RECEIPT_KEYS_URL` | no | Where to fetch receipt keys
|
|
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
|
|
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
|
-
*
|
|
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.
|
|
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.
|
|
48
|
+
"@oked/receipt-core": "0.6.21"
|
|
49
49
|
},
|
|
50
50
|
"devDependencies": {
|
|
51
51
|
"@types/node": "^22.13.10",
|