@oked/hook-core 0.6.21 → 0.6.23
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 +11 -3
- package/dist/decide.d.ts +9 -1
- package/dist/decide.js +19 -4
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/sandbox.d.ts +35 -0
- package/dist/sandbox.js +134 -0
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -5,13 +5,21 @@
|
|
|
5
5
|
|
|
6
6
|
Shared gate for OKed coding-agent hooks. It is the part of [`@oked/claude-code`](../claude-code) that does not depend on Claude Code: classify the tool call, build the approval request, wait for a person, check the signed receipt, and fail closed.
|
|
7
7
|
|
|
8
|
-
Host packages read the host's payload, map tool names, call `decide()`, and write the host's own allow or deny output. `@oked/claude-code` does this with unchanged behavior. `@oked/codex`, `@oked/cursor`, and `@oked/copilot` do it for those hosts.
|
|
8
|
+
Host packages read the host's payload, map tool names, call `decide()`, and write the host's own allow or deny output. `@oked/claude-code` does this with unchanged behavior. `@oked/codex`, `@oked/cursor`, and `@oked/copilot` do it for those hosts.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
npm install @oked/hook-core
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
This package has no `init` command. Install a host package (`@oked/claude-code`, `@oked/codex`, `@oked/cursor`, or `@oked/copilot`) unless you are building a hook.
|
|
17
|
+
|
|
18
|
+
Decisions are made in Telegram or on the [web dashboard](https://oked.ai/dashboard). The iPhone app is coming soon. Questions: [contact@oked.ai](mailto:contact@oked.ai).
|
|
11
19
|
|
|
12
20
|
## What `decide()` does
|
|
13
21
|
|
|
14
|
-
1. Classify the call with `@oked/sdk`. `safe` returns allow, with no notification. `warning` returns allow and writes a terminal line. A cached user rule that matches either tier sends the call to the backend instead.
|
|
22
|
+
1. Classify the call with `@oked/sdk`. `safe` returns allow, with no notification. `warning` returns allow and writes a terminal line. A cached user rule that matches either tier sends the call to the backend instead. For `source: "claude-code"`, an opaque runner (`cargo test`, `npm test`, a script file, `npx`) is `review` unless Claude Code's Bash sandbox is on with `allowUnsandboxedCommands: false`. Other sources leave those commands `safe`.
|
|
15
23
|
2. With no API key, return the host's unpaired decision. Claude Code asks the host's own prompt. A host that cannot enforce `ask` should deny, and the reason should say `Pair first`.
|
|
16
24
|
3. For `review` and `high_stakes`, send the approval and wait. The SDK waits 630 seconds (`DEFAULT_APPROVAL_TIMEOUT_MS`), which is 30 seconds past the backend's 10 minute window.
|
|
17
25
|
4. An approval counts only when the signed receipt verifies. The hook keeps a copy in `~/.oked/receipts.jsonl`.
|
package/dist/decide.d.ts
CHANGED
|
@@ -11,7 +11,7 @@ export interface GateDecision {
|
|
|
11
11
|
reason?: string;
|
|
12
12
|
}
|
|
13
13
|
export interface DecideOptions {
|
|
14
|
-
/** Recorded on receipts and in the decision log, e.g. `@oked/claude-code@0.6.
|
|
14
|
+
/** Recorded on receipts and in the decision log, e.g. `@oked/claude-code@0.6.22`. */
|
|
15
15
|
clientId: string;
|
|
16
16
|
/** Receipt subject source, e.g. `claude-code`. */
|
|
17
17
|
source: string;
|
|
@@ -31,6 +31,14 @@ export interface DecideOptions {
|
|
|
31
31
|
*/
|
|
32
32
|
invalidKeyReason?: (status: number) => string;
|
|
33
33
|
log?: (msg: string) => void;
|
|
34
|
+
/**
|
|
35
|
+
* When set, overrides Claude Code sandbox detection.
|
|
36
|
+
* `false`: an opaque code runner (test runner, script file, npx) is `review`.
|
|
37
|
+
* `true`: those commands stay `safe`.
|
|
38
|
+
* Omitted: `source: "claude-code"` reads sandbox settings. Other hosts omit
|
|
39
|
+
* it and keep the previous behaviour.
|
|
40
|
+
*/
|
|
41
|
+
sandboxEnforced?: boolean;
|
|
34
42
|
}
|
|
35
43
|
/**
|
|
36
44
|
* Classify one tool call and, when the tier needs a person, wait for the
|
package/dist/decide.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { OKedClient, classify, describe, describeFields, lookupPrTitle, applyRules, degradedDecision, OKedAuthError, OKedBackendUnreachableError, OKedHttpError, OKedReceiptError, OKedTooManyPendingError, shortReceiptId, } from "@oked/sdk";
|
|
2
2
|
import { appendReceipt } from "./receipts.js";
|
|
3
3
|
import { errorInfo, logDecision } from "./log.js";
|
|
4
|
+
import { claudeSandboxEnforced } from "./sandbox.js";
|
|
4
5
|
function defaultInvalidKeyReason(status) {
|
|
5
6
|
return `OKed: invalid API key (HTTP ${status}). Run \`oked init\` to pair again, or \`oked uninstall\` to remove OKed.`;
|
|
6
7
|
}
|
|
@@ -8,6 +9,10 @@ function errorText(err) {
|
|
|
8
9
|
const info = errorInfo(err);
|
|
9
10
|
return `${info.name}: ${info.message}`;
|
|
10
11
|
}
|
|
12
|
+
function commandOf(toolInput) {
|
|
13
|
+
const command = toolInput.command ?? toolInput.cmd;
|
|
14
|
+
return typeof command === "string" ? command : undefined;
|
|
15
|
+
}
|
|
11
16
|
/**
|
|
12
17
|
* Classify one tool call and, when the tier needs a person, wait for the
|
|
13
18
|
* decision. Safe and warning calls return allow without a prompt, unless a
|
|
@@ -38,7 +43,17 @@ export async function decide(call, options) {
|
|
|
38
43
|
};
|
|
39
44
|
const toolName = call.toolName;
|
|
40
45
|
const toolInput = call.toolInput;
|
|
41
|
-
const
|
|
46
|
+
const command = commandOf(toolInput);
|
|
47
|
+
const sandboxEnforced = options.sandboxEnforced !== undefined
|
|
48
|
+
? options.sandboxEnforced
|
|
49
|
+
: options.source === "claude-code"
|
|
50
|
+
? claudeSandboxEnforced(call.cwd ?? process.cwd(), command)
|
|
51
|
+
: undefined;
|
|
52
|
+
const tier = classify(toolName, toolInput, sandboxEnforced === undefined ? undefined : { sandboxEnforced });
|
|
53
|
+
const describeCtx = {
|
|
54
|
+
cwd: call.cwd,
|
|
55
|
+
...(sandboxEnforced === false ? { sandboxEnforced: false } : {}),
|
|
56
|
+
};
|
|
42
57
|
const client = new OKedClient({ client: options.clientId, source: options.source });
|
|
43
58
|
// Presence ping (throttled to once/day on disk, never throws). Fired before
|
|
44
59
|
// the safe/warning fast-path return so installs that only ever run safe
|
|
@@ -46,7 +61,7 @@ export async function decide(call, options) {
|
|
|
46
61
|
// and only the once/day send actually waits.
|
|
47
62
|
if (client.apiKey)
|
|
48
63
|
await client.heartbeat();
|
|
49
|
-
let fields = describeFields(toolName, toolInput,
|
|
64
|
+
let fields = describeFields(toolName, toolInput, describeCtx) ?? undefined;
|
|
50
65
|
// safe/warning normally short-circuit locally with no network call. But a
|
|
51
66
|
// user rule can escalate (or auto-decide) such an action, and rules live
|
|
52
67
|
// server-side. Consult the locally-cached rules: if one matches this action,
|
|
@@ -81,8 +96,8 @@ export async function decide(call, options) {
|
|
|
81
96
|
}
|
|
82
97
|
const prTitle = await lookupPrTitle(fields);
|
|
83
98
|
if (prTitle)
|
|
84
|
-
fields = describeFields(toolName, toolInput, {
|
|
85
|
-
const description = describe(toolName, toolInput, {
|
|
99
|
+
fields = describeFields(toolName, toolInput, { ...describeCtx, prTitle }) ?? undefined;
|
|
100
|
+
const description = describe(toolName, toolInput, { ...describeCtx, prTitle });
|
|
86
101
|
log(`${toolName}: "${description}" - ${tier}`);
|
|
87
102
|
log("Requesting approval... (check your phone)");
|
|
88
103
|
try {
|
package/dist/index.d.ts
CHANGED
|
@@ -5,4 +5,5 @@ export { appendReceipt, verifyReceiptsFile, OKED_RECEIPTS_LOG, type LocalVerifyR
|
|
|
5
5
|
export { findClaudeOkedHooks, settingsHasOkedHook, claudeUserSettingsPath, type ClaudeHookHit, type ClaudeHookScope, } from "./claude-hooks.js";
|
|
6
6
|
export { stringField, withNormalizedFields, asToolInput, shQuote, mapFileDelete, extractPatchPaths, mapPatch, } from "./normalize.js";
|
|
7
7
|
export { pairDevice, writeOkedConfig, maskKey, type PairOptions } from "./pair.js";
|
|
8
|
+
export { claudeSandboxEnforced, readClaudeSandbox, exclusionCoversCommand, SANDBOX_INIT_HINT, type ClaudeSandboxView, } from "./sandbox.js";
|
|
8
9
|
export { encodeQR, renderQR } from "./qr.js";
|
package/dist/index.js
CHANGED
|
@@ -5,4 +5,5 @@ export { appendReceipt, verifyReceiptsFile, OKED_RECEIPTS_LOG, } from "./receipt
|
|
|
5
5
|
export { findClaudeOkedHooks, settingsHasOkedHook, claudeUserSettingsPath, } from "./claude-hooks.js";
|
|
6
6
|
export { stringField, withNormalizedFields, asToolInput, shQuote, mapFileDelete, extractPatchPaths, mapPatch, } from "./normalize.js";
|
|
7
7
|
export { pairDevice, writeOkedConfig, maskKey } from "./pair.js";
|
|
8
|
+
export { claudeSandboxEnforced, readClaudeSandbox, exclusionCoversCommand, SANDBOX_INIT_HINT, } from "./sandbox.js";
|
|
8
9
|
export { encodeQR, renderQR } from "./qr.js";
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Printed by `oked init` when Claude Code's Bash sandbox is not containing
|
|
3
|
+
* child processes. The approval card uses the same idea as a footnote.
|
|
4
|
+
*/
|
|
5
|
+
export declare const SANDBOX_INIT_HINT: string;
|
|
6
|
+
export interface ClaudeSandboxView {
|
|
7
|
+
enabled: boolean;
|
|
8
|
+
/** Effective value. Claude's default is true when no file sets it. */
|
|
9
|
+
allowUnsandboxedCommands: boolean;
|
|
10
|
+
filesystemDisabled: boolean;
|
|
11
|
+
excludedCommands: string[];
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* True when the Claude Code settings this hook can see contain Bash child
|
|
15
|
+
* processes in the working directory.
|
|
16
|
+
*
|
|
17
|
+
* Containment requires `sandbox.enabled` and `allowUnsandboxedCommands: false`.
|
|
18
|
+
* A `false` in `~/.claude/settings.json` holds against a project `true`, matching
|
|
19
|
+
* Claude Code. `sandbox.filesystem.disabled: true` is read only from user
|
|
20
|
+
* settings (project files cannot turn filesystem isolation off). A command is
|
|
21
|
+
* not contained when `sandbox.excludedCommands` covers every part of it.
|
|
22
|
+
*
|
|
23
|
+
* Files, highest precedence first for ordinary booleans: `.claude/settings.local.json`,
|
|
24
|
+
* `.claude/settings.json`, then the user file (`CLAUDE_CONFIG_DIR` or `~/.claude`).
|
|
25
|
+
* Managed settings and `--settings` are not on disk here. Missing them can only
|
|
26
|
+
* add a prompt, because a sandbox we cannot see stays "not enforced".
|
|
27
|
+
*/
|
|
28
|
+
export declare function claudeSandboxEnforced(cwd: string, command?: string): boolean;
|
|
29
|
+
export declare function readClaudeSandbox(cwd: string): ClaudeSandboxView;
|
|
30
|
+
/**
|
|
31
|
+
* Claude takes a Bash call out of the sandbox only when an excludedCommands
|
|
32
|
+
* entry covers every command in it. `docker *` does not cover `cargo test`,
|
|
33
|
+
* and it does not cover `cd x && cargo test` either.
|
|
34
|
+
*/
|
|
35
|
+
export declare function exclusionCoversCommand(command: string, patterns: string[]): boolean;
|
package/dist/sandbox.js
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
import { existsSync, readFileSync } from "fs";
|
|
2
|
+
import { join } from "path";
|
|
3
|
+
import { splitTopLevel } from "@oked/sdk";
|
|
4
|
+
import { claudeUserSettingsPath } from "./claude-hooks.js";
|
|
5
|
+
/**
|
|
6
|
+
* Printed by `oked init` when Claude Code's Bash sandbox is not containing
|
|
7
|
+
* child processes. The approval card uses the same idea as a footnote.
|
|
8
|
+
*/
|
|
9
|
+
export const SANDBOX_INIT_HINT = [
|
|
10
|
+
"Test commands and scripts (cargo test, npm test, npm run, pytest, ./script.sh)",
|
|
11
|
+
"ask for approval, because OKed cannot see what they run. To skip those prompts,",
|
|
12
|
+
"turn on Claude Code's Bash sandbox and set allowUnsandboxedCommands to false:",
|
|
13
|
+
'{ "sandbox": { "enabled": true, "allowUnsandboxedCommands": false } }',
|
|
14
|
+
"Put that in ~/.claude/settings.json or .claude/settings.local.json.",
|
|
15
|
+
].join("\n");
|
|
16
|
+
/**
|
|
17
|
+
* True when the Claude Code settings this hook can see contain Bash child
|
|
18
|
+
* processes in the working directory.
|
|
19
|
+
*
|
|
20
|
+
* Containment requires `sandbox.enabled` and `allowUnsandboxedCommands: false`.
|
|
21
|
+
* A `false` in `~/.claude/settings.json` holds against a project `true`, matching
|
|
22
|
+
* Claude Code. `sandbox.filesystem.disabled: true` is read only from user
|
|
23
|
+
* settings (project files cannot turn filesystem isolation off). A command is
|
|
24
|
+
* not contained when `sandbox.excludedCommands` covers every part of it.
|
|
25
|
+
*
|
|
26
|
+
* Files, highest precedence first for ordinary booleans: `.claude/settings.local.json`,
|
|
27
|
+
* `.claude/settings.json`, then the user file (`CLAUDE_CONFIG_DIR` or `~/.claude`).
|
|
28
|
+
* Managed settings and `--settings` are not on disk here. Missing them can only
|
|
29
|
+
* add a prompt, because a sandbox we cannot see stays "not enforced".
|
|
30
|
+
*/
|
|
31
|
+
export function claudeSandboxEnforced(cwd, command) {
|
|
32
|
+
const view = readClaudeSandbox(cwd);
|
|
33
|
+
if (!view.enabled || view.allowUnsandboxedCommands || view.filesystemDisabled)
|
|
34
|
+
return false;
|
|
35
|
+
if (command && exclusionCoversCommand(command, view.excludedCommands))
|
|
36
|
+
return false;
|
|
37
|
+
return true;
|
|
38
|
+
}
|
|
39
|
+
export function readClaudeSandbox(cwd) {
|
|
40
|
+
const local = readSandboxFile(join(cwd, ".claude", "settings.local.json"));
|
|
41
|
+
const project = readSandboxFile(join(cwd, ".claude", "settings.json"));
|
|
42
|
+
const user = readSandboxFile(claudeUserSettingsPath());
|
|
43
|
+
const excludedCommands = [
|
|
44
|
+
...(local?.excludedCommands ?? []),
|
|
45
|
+
...(project?.excludedCommands ?? []),
|
|
46
|
+
...(user?.excludedCommands ?? []),
|
|
47
|
+
];
|
|
48
|
+
return {
|
|
49
|
+
enabled: firstBoolean(local?.enabled, project?.enabled, user?.enabled) ?? false,
|
|
50
|
+
allowUnsandboxedCommands: effectiveAllowUnsandboxed(user?.allowUnsandboxedCommands, project?.allowUnsandboxedCommands, local?.allowUnsandboxedCommands),
|
|
51
|
+
filesystemDisabled: user?.filesystemDisabled === true,
|
|
52
|
+
excludedCommands,
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
function firstBoolean(...values) {
|
|
56
|
+
for (const value of values) {
|
|
57
|
+
if (typeof value === "boolean")
|
|
58
|
+
return value;
|
|
59
|
+
}
|
|
60
|
+
return undefined;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* User `false` holds against a project or local `true`. Otherwise the highest
|
|
64
|
+
* file that sets the key wins. Unset means Claude's default, true.
|
|
65
|
+
*/
|
|
66
|
+
function effectiveAllowUnsandboxed(user, project, local) {
|
|
67
|
+
const userFalse = user === false;
|
|
68
|
+
if (typeof local === "boolean") {
|
|
69
|
+
if (local === true && userFalse)
|
|
70
|
+
return false;
|
|
71
|
+
return local;
|
|
72
|
+
}
|
|
73
|
+
if (typeof project === "boolean") {
|
|
74
|
+
if (project === true && userFalse)
|
|
75
|
+
return false;
|
|
76
|
+
return project;
|
|
77
|
+
}
|
|
78
|
+
if (typeof user === "boolean")
|
|
79
|
+
return user;
|
|
80
|
+
return true;
|
|
81
|
+
}
|
|
82
|
+
function readSandboxFile(path) {
|
|
83
|
+
if (!existsSync(path))
|
|
84
|
+
return undefined;
|
|
85
|
+
let parsed;
|
|
86
|
+
try {
|
|
87
|
+
parsed = JSON.parse(readFileSync(path, "utf-8"));
|
|
88
|
+
}
|
|
89
|
+
catch {
|
|
90
|
+
return undefined;
|
|
91
|
+
}
|
|
92
|
+
if (!parsed || typeof parsed !== "object")
|
|
93
|
+
return undefined;
|
|
94
|
+
const sandbox = parsed.sandbox;
|
|
95
|
+
if (!sandbox || typeof sandbox !== "object")
|
|
96
|
+
return { excludedCommands: [] };
|
|
97
|
+
const record = sandbox;
|
|
98
|
+
const filesystem = record.filesystem;
|
|
99
|
+
const filesystemDisabled = Boolean(filesystem) &&
|
|
100
|
+
typeof filesystem === "object" &&
|
|
101
|
+
filesystem.disabled === true;
|
|
102
|
+
const excludedCommands = Array.isArray(record.excludedCommands)
|
|
103
|
+
? record.excludedCommands.filter((entry) => typeof entry === "string")
|
|
104
|
+
: [];
|
|
105
|
+
return {
|
|
106
|
+
enabled: typeof record.enabled === "boolean" ? record.enabled : undefined,
|
|
107
|
+
allowUnsandboxedCommands: typeof record.allowUnsandboxedCommands === "boolean" ? record.allowUnsandboxedCommands : undefined,
|
|
108
|
+
filesystemDisabled: filesystemDisabled || undefined,
|
|
109
|
+
excludedCommands,
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Claude takes a Bash call out of the sandbox only when an excludedCommands
|
|
114
|
+
* entry covers every command in it. `docker *` does not cover `cargo test`,
|
|
115
|
+
* and it does not cover `cd x && cargo test` either.
|
|
116
|
+
*/
|
|
117
|
+
export function exclusionCoversCommand(command, patterns) {
|
|
118
|
+
const usable = patterns.map((pattern) => pattern.trim()).filter(Boolean);
|
|
119
|
+
if (usable.length === 0)
|
|
120
|
+
return false;
|
|
121
|
+
const stages = splitTopLevel(command);
|
|
122
|
+
if (stages.length === 0)
|
|
123
|
+
return false;
|
|
124
|
+
return stages.every((stage) => usable.some((pattern) => globMatch(stage.trim(), pattern)));
|
|
125
|
+
}
|
|
126
|
+
function globMatch(text, pattern) {
|
|
127
|
+
if (!pattern.includes("*"))
|
|
128
|
+
return text === pattern;
|
|
129
|
+
const body = pattern.split("*").map(escapeRegExp).join(".*");
|
|
130
|
+
return new RegExp(`^${body}$`).test(text);
|
|
131
|
+
}
|
|
132
|
+
function escapeRegExp(value) {
|
|
133
|
+
return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
134
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oked/hook-core",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.23",
|
|
4
4
|
"description": "Shared OKed approval gate for coding-agent hooks. Builds the request, waits for a decision, checks the receipt, and fails closed.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -38,7 +38,7 @@
|
|
|
38
38
|
"bugs": {
|
|
39
39
|
"url": "https://github.com/oked-ai/oked-sdk/issues"
|
|
40
40
|
},
|
|
41
|
-
"homepage": "https://oked.ai
|
|
41
|
+
"homepage": "https://oked.ai",
|
|
42
42
|
"license": "Apache-2.0",
|
|
43
43
|
"engines": {
|
|
44
44
|
"node": ">=18"
|
|
@@ -47,10 +47,10 @@
|
|
|
47
47
|
"access": "public"
|
|
48
48
|
},
|
|
49
49
|
"dependencies": {
|
|
50
|
-
"@oked/sdk": "0.6.
|
|
50
|
+
"@oked/sdk": "0.6.23"
|
|
51
51
|
},
|
|
52
52
|
"devDependencies": {
|
|
53
|
-
"@types/node": "^
|
|
54
|
-
"typescript": "^
|
|
53
|
+
"@types/node": "^26.6.5",
|
|
54
|
+
"typescript": "^7.0.2"
|
|
55
55
|
}
|
|
56
56
|
}
|