@oked/sdk 0.5.0 → 0.6.1
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 +3 -3
- package/dist/classify.js +23 -0
- package/dist/config.d.ts +1 -1
- package/dist/describe.js +9 -0
- package/dist/index.js +6 -3
- package/dist/kinds.d.ts +1 -1
- package/dist/receipt.d.ts +2 -1
- package/dist/receipt.js +3 -2
- package/dist/types.d.ts +6 -5
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -46,7 +46,7 @@ Pass to `new OKedClient(config)`:
|
|
|
46
46
|
| `backendUrl` | `string` | `https://api.oked.ai` | Override the OKed backend URL. |
|
|
47
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
48
|
| `strictFailClosed` | `boolean` | `false` | When true, backend outages deny every tier. When false, outages deny only `high_stakes` and allow lower tiers. |
|
|
49
|
-
| `requireReceipt` | `boolean` | `
|
|
49
|
+
| `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
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
51
|
| `receiptKeys` | `ReceiptKey[]` | | Verify with exactly these keys and never fetch (self-hosted backends, tests). |
|
|
52
52
|
| `client` | `string` | | Your integration's name and version, e.g. `my-agent@1.2.0`. Recorded in receipts. |
|
|
@@ -96,12 +96,12 @@ Full type definitions ship with the package (`dist/index.d.ts`).
|
|
|
96
96
|
| `OKED_API_KEY` | yes, unless passed in code | Your OKed API key. |
|
|
97
97
|
| `OKED_BACKEND_URL` | no | Override the hosted backend URL. |
|
|
98
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 `
|
|
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
100
|
| `OKED_RECEIPT_KEYS_URL` | no | Where to fetch receipt keys (default OKed's published set). |
|
|
101
101
|
|
|
102
102
|
## Degraded-mode behavior
|
|
103
103
|
|
|
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
|
|
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.
|
|
105
105
|
|
|
106
106
|
## Development
|
|
107
107
|
|
package/dist/classify.js
CHANGED
|
@@ -1286,9 +1286,32 @@ function classifyBrowserTool(tool, toolInput, server) {
|
|
|
1286
1286
|
}
|
|
1287
1287
|
return "review";
|
|
1288
1288
|
}
|
|
1289
|
+
/**
|
|
1290
|
+
* Desktop app folder access (`ccd_directory`): change_directory moves the
|
|
1291
|
+
* session to a folder, request_directory adds a folder to it. The app already
|
|
1292
|
+
* shows its own approval for the exact folder (except in bypass permissions
|
|
1293
|
+
* mode), so a second OKed prompt is approval fatigue. Log it (`warning`), but
|
|
1294
|
+
* keep `review` for a broad or sensitive grant: the filesystem root, the home
|
|
1295
|
+
* folder or one of its parents, secret stores and system folders. Without a
|
|
1296
|
+
* path, request_directory opens a native picker the user drives: `safe`.
|
|
1297
|
+
*/
|
|
1298
|
+
function classifyDirectoryGrant(tool, toolInput) {
|
|
1299
|
+
const dir = typeof toolInput.path === "string" ? toolInput.path.trim() : "";
|
|
1300
|
+
if (!dir)
|
|
1301
|
+
return tool === "request_directory" ? "safe" : "review";
|
|
1302
|
+
const home = os.homedir();
|
|
1303
|
+
const resolved = path.resolve(dir.replace(/^~(?=\/|$)/, home).replace(/^\$\{?HOME\}?(?=\/|$)/, home));
|
|
1304
|
+
const isHomeOrParent = home === resolved || home.startsWith(resolved.endsWith(path.sep) ? resolved : resolved + path.sep);
|
|
1305
|
+
if (isHomeOrParent || isSensitiveWritePath(resolved))
|
|
1306
|
+
return "review";
|
|
1307
|
+
return "warning";
|
|
1308
|
+
}
|
|
1289
1309
|
function classifyMcpTool(toolName, toolInput = {}) {
|
|
1290
1310
|
const parts = toolName.split("__");
|
|
1291
1311
|
const tool = parts[parts.length - 1] || "";
|
|
1312
|
+
if (parts.includes("ccd_directory") && (tool === "change_directory" || tool === "request_directory")) {
|
|
1313
|
+
return classifyDirectoryGrant(tool, toolInput);
|
|
1314
|
+
}
|
|
1292
1315
|
const browserServer = parts.slice(1, -1).find((p) => BROWSER_MCP_SERVERS.has(p));
|
|
1293
1316
|
if (browserServer)
|
|
1294
1317
|
return classifyBrowserTool(tool, toolInput, browserServer);
|
package/dist/config.d.ts
CHANGED
|
@@ -6,7 +6,7 @@ export interface PersistedConfig {
|
|
|
6
6
|
rulesCacheTtlSeconds?: number;
|
|
7
7
|
/** Min interval (seconds) between heartbeats. See OKedConfig.heartbeatIntervalMs. */
|
|
8
8
|
heartbeatIntervalSeconds?: number;
|
|
9
|
-
/** Deny
|
|
9
|
+
/** Deny an approval that arrives without a receipt (default true). See OKedConfig.requireReceipt. */
|
|
10
10
|
requireReceipt?: boolean;
|
|
11
11
|
/** Where to fetch receipt keys. See OKedConfig.receiptKeysUrl. */
|
|
12
12
|
receiptKeysUrl?: string;
|
package/dist/describe.js
CHANGED
|
@@ -858,6 +858,15 @@ function summarizeMcp(toolName, input) {
|
|
|
858
858
|
const parts = toolName.split("__");
|
|
859
859
|
const server = parts[1] || "unknown";
|
|
860
860
|
const tool = parts[2] || "";
|
|
861
|
+
if (parts.includes("ccd_directory") && (tool === "change_directory" || tool === "request_directory")) {
|
|
862
|
+
const dir = typeof input.path === "string" && input.path.trim() ? shortenPath(input.path.trim()) : undefined;
|
|
863
|
+
if (tool === "change_directory") {
|
|
864
|
+
return { title: "Move session to folder", target: dir, footnote: "Claude can read and change files in this folder", kind: "folder_access" };
|
|
865
|
+
}
|
|
866
|
+
return dir
|
|
867
|
+
? { title: "Give session access to folder", target: dir, footnote: "Claude can read and change files in this folder", kind: "folder_access" }
|
|
868
|
+
: { title: "Ask you to pick a folder for this session", kind: "folder_access" };
|
|
869
|
+
}
|
|
861
870
|
const browser = parts.slice(1, -1).find((p) => p === "Claude_Browser" || p === "claude-in-chrome");
|
|
862
871
|
if (browser)
|
|
863
872
|
return summarizeBrowser(parts[parts.length - 1] || "", input, browser);
|
package/dist/index.js
CHANGED
|
@@ -117,7 +117,10 @@ export class OKedClient {
|
|
|
117
117
|
? persisted.heartbeatIntervalSeconds * 1000
|
|
118
118
|
: undefined) ??
|
|
119
119
|
86_400_000,
|
|
120
|
-
|
|
120
|
+
// On by default from 0.6.0: an approval only counts with a valid receipt.
|
|
121
|
+
// OKED_REQUIRE_RECEIPT=0 (or requireReceipt: false) for a backend that
|
|
122
|
+
// does not sign receipts yet, e.g. an older self-hosted one.
|
|
123
|
+
requireReceipt: config?.requireReceipt ?? envRequireReceipt() ?? persisted.requireReceipt ?? true,
|
|
121
124
|
receiptKeysUrl: config?.receiptKeysUrl ||
|
|
122
125
|
process.env.OKED_RECEIPT_KEYS_URL ||
|
|
123
126
|
persisted.receiptKeysUrl ||
|
|
@@ -217,8 +220,8 @@ export class OKedClient {
|
|
|
217
220
|
throw err;
|
|
218
221
|
}
|
|
219
222
|
// Nobody acts on a decision we cannot prove: an invalid receipt throws
|
|
220
|
-
// OKedReceiptError (every integration denies), and so does
|
|
221
|
-
//
|
|
223
|
+
// OKedReceiptError (every integration denies), and so does an approval
|
|
224
|
+
// with no receipt while requireReceipt is on (the default).
|
|
222
225
|
const receipt = await checkReceipt(result, { action: request.action, description: request.description, toolInput: request.tool_input, source, nonce }, {
|
|
223
226
|
required: this.config.requireReceipt,
|
|
224
227
|
trust: { keys: this.config.receiptKeys, keysUrl: this.config.receiptKeysUrl },
|
package/dist/kinds.d.ts
CHANGED
|
@@ -7,4 +7,4 @@
|
|
|
7
7
|
* classifier that produced them.
|
|
8
8
|
*/
|
|
9
9
|
export declare const CLASSIFIER_VERSION = "v2";
|
|
10
|
-
export type OperationKind = "file_create" | "file_append" | "file_edit" | "file_touch" | "file_copy" | "file_move" | "file_delete" | "sql_drop" | "sql_truncate" | "sql_alter" | "sql_create" | "sql_delete_rows" | "sql_delete_all_rows" | "sql_update_rows" | "sql_update_every_row" | "sql_insert" | "sql_query" | "git_push" | "git_force_push" | "git_reset_hard" | "git_clean" | "git_checkout" | "git_restore" | "git_commit" | "git_pr_create" | "ssh_remote" | "http_get" | "http_post" | "http_put" | "http_delete" | "http_pipe_to_shell" | "docker_up" | "docker_down" | "docker_rm" | "docker_rmi" | "docker_prune" | "npm_install" | "npm_run" | "npm_test" | "npm_publish" | "npm_unpublish" | "npx_deploy" | "kill_process" | "sudo" | "chmod_777" | "email_send" | "email_delete" | "email_purge" | "payment_charge" | "payment_create" | "chat_message" | "mcp_delete" | "mcp_update" | "mcp_create" | "mcp_post" | "mcp_publish" | "mcp_send" | "mcp_submit_form" | "mcp_fill" | "mcp_submit" | "mcp_query" | "browser_navigate" | "browser_interact" | "browser_script" | "browser_dev_server" | "agent_launch" | "shell_pipeline" | "unknown_bash" | "unknown_tool";
|
|
10
|
+
export type OperationKind = "file_create" | "file_append" | "file_edit" | "file_touch" | "file_copy" | "file_move" | "file_delete" | "sql_drop" | "sql_truncate" | "sql_alter" | "sql_create" | "sql_delete_rows" | "sql_delete_all_rows" | "sql_update_rows" | "sql_update_every_row" | "sql_insert" | "sql_query" | "git_push" | "git_force_push" | "git_reset_hard" | "git_clean" | "git_checkout" | "git_restore" | "git_commit" | "git_pr_create" | "ssh_remote" | "http_get" | "http_post" | "http_put" | "http_delete" | "http_pipe_to_shell" | "docker_up" | "docker_down" | "docker_rm" | "docker_rmi" | "docker_prune" | "npm_install" | "npm_run" | "npm_test" | "npm_publish" | "npm_unpublish" | "npx_deploy" | "kill_process" | "sudo" | "chmod_777" | "email_send" | "email_delete" | "email_purge" | "payment_charge" | "payment_create" | "chat_message" | "mcp_delete" | "mcp_update" | "mcp_create" | "mcp_post" | "mcp_publish" | "mcp_send" | "mcp_submit_form" | "mcp_fill" | "mcp_submit" | "mcp_query" | "browser_navigate" | "browser_interact" | "browser_script" | "browser_dev_server" | "folder_access" | "agent_launch" | "shell_pipeline" | "unknown_bash" | "unknown_tool";
|
package/dist/receipt.d.ts
CHANGED
|
@@ -24,7 +24,8 @@ export declare function keysFor(kid: string, trust: ReceiptTrust): Promise<Recei
|
|
|
24
24
|
* Check the receipt that came with a decision before anyone acts on it: a
|
|
25
25
|
* valid signature by a published OKed key, for this request id, this
|
|
26
26
|
* decision, and the exact action and nonce we sent. Throws OKedReceiptError
|
|
27
|
-
* on any mismatch. A missing receipt throws only when
|
|
27
|
+
* on any mismatch. A missing receipt throws only for an approval, when
|
|
28
|
+
* `required`: a deny or timeout without one is a deny anyway.
|
|
28
29
|
*/
|
|
29
30
|
export declare function checkReceipt(result: {
|
|
30
31
|
approval_id: string | null;
|
package/dist/receipt.js
CHANGED
|
@@ -68,11 +68,12 @@ export async function keysFor(kid, trust) {
|
|
|
68
68
|
* Check the receipt that came with a decision before anyone acts on it: a
|
|
69
69
|
* valid signature by a published OKed key, for this request id, this
|
|
70
70
|
* decision, and the exact action and nonce we sent. Throws OKedReceiptError
|
|
71
|
-
* on any mismatch. A missing receipt throws only when
|
|
71
|
+
* on any mismatch. A missing receipt throws only for an approval, when
|
|
72
|
+
* `required`: a deny or timeout without one is a deny anyway.
|
|
72
73
|
*/
|
|
73
74
|
export async function checkReceipt(result, sent, opts) {
|
|
74
75
|
if (result.receipt === undefined || result.receipt === null) {
|
|
75
|
-
if (opts.required)
|
|
76
|
+
if (opts.required && result.decision === "approved")
|
|
76
77
|
throw new OKedReceiptError("missing", ["missing"]);
|
|
77
78
|
return undefined;
|
|
78
79
|
}
|
package/dist/types.d.ts
CHANGED
|
@@ -17,8 +17,8 @@ export interface ApprovalResponse {
|
|
|
17
17
|
/**
|
|
18
18
|
* The signed receipt for this decision, already verified: OKed's signature,
|
|
19
19
|
* this request, this decision, and the exact action and nonce sent. Absent
|
|
20
|
-
*
|
|
21
|
-
*
|
|
20
|
+
* for a deny or timeout that came without one (e.g. a client-side timeout),
|
|
21
|
+
* or when requireReceipt is off and the backend sent none.
|
|
22
22
|
*/
|
|
23
23
|
receipt?: SignedReceipt;
|
|
24
24
|
}
|
|
@@ -61,9 +61,10 @@ export interface OKedConfig {
|
|
|
61
61
|
*/
|
|
62
62
|
heartbeatIntervalMs: number;
|
|
63
63
|
/**
|
|
64
|
-
* Deny
|
|
65
|
-
*
|
|
66
|
-
*
|
|
64
|
+
* Deny an approval that arrives without a receipt. A receipt that is present
|
|
65
|
+
* but does not verify always denies, whatever this says. Default true (since
|
|
66
|
+
* 0.6.0); set false, or env OKED_REQUIRE_RECEIPT=0, only for a backend that
|
|
67
|
+
* does not sign receipts.
|
|
67
68
|
*/
|
|
68
69
|
requireReceipt: boolean;
|
|
69
70
|
/**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oked/sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.1",
|
|
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.
|
|
48
|
+
"@oked/receipt-core": "0.6.1"
|
|
49
49
|
},
|
|
50
50
|
"devDependencies": {
|
|
51
51
|
"@types/node": "^22.13.10",
|