@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 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` | `false` (`true` from 0.6.0) | Deny any decision that arrives without a valid signed receipt. A receipt that is present but invalid always denies. Env `OKED_REQUIRE_RECEIPT=1`. |
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 `1` or `true` to deny any decision without a valid signed receipt. |
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 (or a missing one with `requireReceipt`) 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.
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 any decision that arrives without a valid receipt. See OKedConfig.requireReceipt. */
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
- requireReceipt: config?.requireReceipt ?? envRequireReceipt() ?? persisted.requireReceipt ?? false,
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 a missing one
221
- // when requireReceipt is on.
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 `required`.
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 `required`.
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
- * only when the backend sent none and requireReceipt is off, or when the
21
- * request timed out on our side.
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 any decision that arrives without a valid receipt. A receipt that is
65
- * present but does not verify always denies, whatever this says. Default
66
- * false in 0.5.0, true from 0.6.0. Env OKED_REQUIRE_RECEIPT=1.
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.5.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.5.0"
48
+ "@oked/receipt-core": "0.6.1"
49
49
  },
50
50
  "devDependencies": {
51
51
  "@types/node": "^22.13.10",