@oked/claude-code 0.4.0 → 0.6.0
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 +6 -1
- package/dist/cli.js +36 -13
- package/dist/hook.js +19 -8
- package/dist/receipts.d.ts +23 -0
- package/dist/receipts.js +52 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +16 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -22,6 +22,7 @@ oked init
|
|
|
22
22
|
|---|---|
|
|
23
23
|
| `oked init` | Install or update the project hook and pair this device. |
|
|
24
24
|
| `oked status` | Show install state and ping the backend. |
|
|
25
|
+
| `oked receipts verify [file]` | Check this machine's copy of approval receipts (default `~/.oked/receipts.jsonl`): every signature, and the chain links between neighbouring receipts. |
|
|
25
26
|
| `oked uninstall` | Remove the project hook entry (other hooks are preserved). |
|
|
26
27
|
|
|
27
28
|
## What gets intercepted
|
|
@@ -58,9 +59,13 @@ to `safe` — running a command is not, by itself, something we interrupt you fo
|
|
|
58
59
|
| `OKED_BACKEND_URL` | no | Override the hosted backend URL. |
|
|
59
60
|
| `OKED_STRICT_FAIL_CLOSED` | no | Set to `1` or `true` to deny every sensitive action when the backend is unreachable. |
|
|
60
61
|
|
|
62
|
+
## Receipts
|
|
63
|
+
|
|
64
|
+
Every decision comes with a receipt signed by OKed (who decided, how they were verified, the exact command, when). The hook verifies it before allowing the action, shows its short id (`Approved via OKed (receipt rcpt_7Q2F)`), and keeps your own copy in `~/.oked/receipts.jsonl`. Check that file any time with `oked receipts verify`. Since 0.6.0 the hook denies any approval that comes without a valid receipt. Set `OKED_REQUIRE_RECEIPT=0` only for a backend that does not sign receipts. See [docs/receipts.md](../../docs/receipts.md).
|
|
65
|
+
|
|
61
66
|
## Degraded-mode behavior
|
|
62
67
|
|
|
63
|
-
Explicit denials
|
|
68
|
+
Explicit denials, invalid API keys and approval receipts that do not verify deny the action. If the backend is unreachable, OKed denies `high_stakes` actions and, by default, allows lower tiers so a temporary outage does not stop every Claude Code workflow. If no API key is configured, the hook returns `ask` so Claude Code's native permission flow can handle the decision. Set `OKED_STRICT_FAIL_CLOSED=1` to deny every sensitive action during backend outages.
|
|
64
69
|
|
|
65
70
|
## License
|
|
66
71
|
|
package/dist/cli.js
CHANGED
|
@@ -2,24 +2,13 @@
|
|
|
2
2
|
import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "fs";
|
|
3
3
|
import { hostname } from "os";
|
|
4
4
|
import { join, dirname } from "path";
|
|
5
|
-
import { fileURLToPath } from "url";
|
|
6
5
|
import { spawn } from "child_process";
|
|
7
6
|
import { createInterface } from "readline";
|
|
8
7
|
import { OKedClient, loadOKedConfig, OKED_CONFIG_PATH } from "@oked/sdk";
|
|
9
8
|
import { HOOK_CONFIG, hasOkedCommandHook, ensureMcpMatcher, ensureHookTimeout, } from "./hook-config.js";
|
|
9
|
+
import { CLIENT_VERSION } from "./version.js";
|
|
10
|
+
import { OKED_RECEIPTS_LOG, verifyReceiptsFile } from "./receipts.js";
|
|
10
11
|
const DEFAULT_BACKEND_URL = process.env.OKED_BACKEND_URL || "https://api.oked.ai";
|
|
11
|
-
// Derived from this package's package.json at runtime so the version the
|
|
12
|
-
// backend sees (client_version) can never drift from what's actually shipped.
|
|
13
|
-
// From dist/cli.js, package.json sits one dir up at the package root.
|
|
14
|
-
const CLIENT_VERSION = (() => {
|
|
15
|
-
try {
|
|
16
|
-
const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
|
|
17
|
-
return JSON.parse(readFileSync(pkgPath, "utf-8")).version ?? "0.0.0";
|
|
18
|
-
}
|
|
19
|
-
catch {
|
|
20
|
-
return "0.0.0";
|
|
21
|
-
}
|
|
22
|
-
})();
|
|
23
12
|
function getSettingsPath() {
|
|
24
13
|
return join(process.cwd(), ".claude", "settings.json");
|
|
25
14
|
}
|
|
@@ -295,6 +284,33 @@ function uninstall() {
|
|
|
295
284
|
writeSettings(settingsPath, settings);
|
|
296
285
|
console.log("OKed hooks removed from this project.");
|
|
297
286
|
}
|
|
287
|
+
async function receipts() {
|
|
288
|
+
if (process.argv[3] !== "verify") {
|
|
289
|
+
console.log("Usage: oked receipts verify [file]");
|
|
290
|
+
console.log(` file defaults to ${OKED_RECEIPTS_LOG}`);
|
|
291
|
+
return;
|
|
292
|
+
}
|
|
293
|
+
const file = process.argv[4] || OKED_RECEIPTS_LOG;
|
|
294
|
+
const report = await verifyReceiptsFile(file);
|
|
295
|
+
console.log(`${file}: ${report.total} receipt(s), ${report.valid} valid`);
|
|
296
|
+
for (const bad of report.invalid) {
|
|
297
|
+
console.log(` line ${bad.line} ${bad.receipt_id ?? "(no id)"}: ${bad.problems.join(", ")}`);
|
|
298
|
+
}
|
|
299
|
+
for (const line of report.unparsable)
|
|
300
|
+
console.log(` line ${line}: not valid JSON`);
|
|
301
|
+
for (const chain of report.chains) {
|
|
302
|
+
const gaps = chain.gaps.length
|
|
303
|
+
? `, ${chain.gaps.length} gap(s) (expected when other devices share this chain)`
|
|
304
|
+
: "";
|
|
305
|
+
console.log(` chain ${chain.chain_id}: seq ${chain.first_seq}..${chain.last_seq}${gaps}`);
|
|
306
|
+
for (const b of chain.breaks)
|
|
307
|
+
console.log(` BROKEN at seq ${b.seq}: ${b.reason}`);
|
|
308
|
+
}
|
|
309
|
+
const ok = report.invalid.length === 0 && report.unparsable.length === 0 && report.chains.every((c) => c.breaks.length === 0);
|
|
310
|
+
console.log(ok ? "OK" : "PROBLEMS FOUND");
|
|
311
|
+
if (!ok)
|
|
312
|
+
process.exitCode = 1;
|
|
313
|
+
}
|
|
298
314
|
// CLI entry point
|
|
299
315
|
const command = process.argv[2];
|
|
300
316
|
switch (command) {
|
|
@@ -307,6 +323,12 @@ switch (command) {
|
|
|
307
323
|
case "uninstall":
|
|
308
324
|
uninstall();
|
|
309
325
|
break;
|
|
326
|
+
case "receipts":
|
|
327
|
+
receipts().catch((err) => {
|
|
328
|
+
console.error(err instanceof Error ? err.message : err);
|
|
329
|
+
process.exitCode = 1;
|
|
330
|
+
});
|
|
331
|
+
break;
|
|
310
332
|
default:
|
|
311
333
|
console.log("Usage: oked <command>");
|
|
312
334
|
console.log("");
|
|
@@ -314,5 +336,6 @@ switch (command) {
|
|
|
314
336
|
console.log(" init Install OKed hooks in current project and pair this device");
|
|
315
337
|
console.log(" status Show current config and connection status");
|
|
316
338
|
console.log(" uninstall Remove OKed hooks from current project");
|
|
339
|
+
console.log(" receipts verify [file] Check this machine's approval receipts");
|
|
317
340
|
break;
|
|
318
341
|
}
|
package/dist/hook.js
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import { OKedClient, classify, describe, describeFields, applyRules, degradedDecision, OKedAuthError, OKedBackendUnreachableError, } from "@oked/sdk";
|
|
2
|
+
import { OKedClient, classify, describe, describeFields, applyRules, degradedDecision, OKedAuthError, OKedBackendUnreachableError, OKedReceiptError, shortReceiptId, } from "@oked/sdk";
|
|
3
|
+
import { CLIENT_ID } from "./version.js";
|
|
4
|
+
import { appendReceipt } from "./receipts.js";
|
|
3
5
|
function makeOutput(decision, reason) {
|
|
4
6
|
return {
|
|
5
7
|
hookSpecificOutput: {
|
|
@@ -30,14 +32,14 @@ async function main() {
|
|
|
30
32
|
const { tool_name: toolName, tool_input: toolInput } = input;
|
|
31
33
|
// Classify risk
|
|
32
34
|
const tier = classify(toolName, toolInput);
|
|
33
|
-
const client = new OKedClient();
|
|
35
|
+
const client = new OKedClient({ client: CLIENT_ID, source: "claude-code" });
|
|
34
36
|
// Presence ping (throttled to once/day on disk, never throws). Fired before
|
|
35
37
|
// the safe/warning fast-path return so installs that only ever run safe
|
|
36
38
|
// actions still register for retention. Bounded by the 3s internal timeout,
|
|
37
39
|
// and only the once/day send actually waits.
|
|
38
40
|
if (client.apiKey)
|
|
39
41
|
await client.heartbeat();
|
|
40
|
-
const fields = describeFields(toolName, toolInput) ?? undefined;
|
|
42
|
+
const fields = describeFields(toolName, toolInput, { cwd: input.cwd }) ?? undefined;
|
|
41
43
|
// safe/warning normally short-circuit locally with no network call. But a
|
|
42
44
|
// user rule can escalate (or auto-decide) such an action, and rules live
|
|
43
45
|
// server-side. Consult the locally-cached rules: if one matches this action,
|
|
@@ -75,7 +77,7 @@ async function main() {
|
|
|
75
77
|
return;
|
|
76
78
|
}
|
|
77
79
|
// Generate human-readable description
|
|
78
|
-
const description = describe(toolName, toolInput);
|
|
80
|
+
const description = describe(toolName, toolInput, { cwd: input.cwd });
|
|
79
81
|
log(`${toolName}: "${description}" - ${tier}`);
|
|
80
82
|
log("Requesting approval... (check your phone)");
|
|
81
83
|
try {
|
|
@@ -88,17 +90,26 @@ async function main() {
|
|
|
88
90
|
session_id: input.session_id,
|
|
89
91
|
cwd: input.cwd,
|
|
90
92
|
});
|
|
93
|
+
// Keep our own copy of every verified receipt (approve, deny or timeout).
|
|
94
|
+
if (result.receipt)
|
|
95
|
+
appendReceipt(result.receipt);
|
|
96
|
+
const receiptNote = result.receipt ? ` (receipt ${shortReceiptId(result.receipt.body.receipt_id)})` : "";
|
|
91
97
|
if (result.approved) {
|
|
92
|
-
log(`Approved (${result.approval_id})`);
|
|
93
|
-
process.stdout.write(JSON.stringify(makeOutput("allow", `Approved via OKed`)));
|
|
98
|
+
log(`Approved (${result.approval_id})${receiptNote}`);
|
|
99
|
+
process.stdout.write(JSON.stringify(makeOutput("allow", `Approved via OKed${receiptNote}`)));
|
|
94
100
|
}
|
|
95
101
|
else {
|
|
96
|
-
log(`Denied (${result.approval_id})`);
|
|
102
|
+
log(`Denied (${result.approval_id})${receiptNote}`);
|
|
97
103
|
process.stdout.write(JSON.stringify(makeOutput("deny", `Denied via OKed: ${description}`)));
|
|
98
104
|
}
|
|
99
105
|
}
|
|
100
106
|
catch (err) {
|
|
101
|
-
if (err instanceof
|
|
107
|
+
if (err instanceof OKedReceiptError) {
|
|
108
|
+
// A decision we cannot prove is not a decision - always deny.
|
|
109
|
+
log(`Approval receipt did not verify (${err.problems.join(", ")}) - action denied`);
|
|
110
|
+
process.stdout.write(JSON.stringify(makeOutput("deny", `OKed: the approval receipt did not verify (${err.problems.join(", ")}); action denied`)));
|
|
111
|
+
}
|
|
112
|
+
else if (err instanceof OKedAuthError) {
|
|
102
113
|
// Auth misconfig is not an outage - always deny.
|
|
103
114
|
log(`Invalid API key - action denied`);
|
|
104
115
|
process.stdout.write(JSON.stringify(makeOutput("deny", "OKed: invalid API key")));
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { verifyChain, type SignedReceipt } from "@oked/sdk";
|
|
2
|
+
/** The customer's own copy of every receipt this machine received. */
|
|
3
|
+
export declare const OKED_RECEIPTS_LOG: string;
|
|
4
|
+
/** Append one verified receipt. Best-effort: never blocks or breaks the agent. */
|
|
5
|
+
export declare function appendReceipt(receipt: SignedReceipt, path?: string): void;
|
|
6
|
+
export interface LocalVerifyReport {
|
|
7
|
+
total: number;
|
|
8
|
+
valid: number;
|
|
9
|
+
invalid: {
|
|
10
|
+
line: number;
|
|
11
|
+
receipt_id: string | null;
|
|
12
|
+
problems: string[];
|
|
13
|
+
}[];
|
|
14
|
+
unparsable: number[];
|
|
15
|
+
chains: ReturnType<typeof verifyChain>;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Verify a receipts file: every signature against OKed's published keys, and
|
|
19
|
+
* chain links between receipts that are adjacent. Gaps in seq are expected in a
|
|
20
|
+
* local copy (other devices and agents share the operator's chain); a broken
|
|
21
|
+
* link between adjacent receipts is not.
|
|
22
|
+
*/
|
|
23
|
+
export declare function verifyReceiptsFile(path?: string): Promise<LocalVerifyReport>;
|
package/dist/receipts.js
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import { appendFileSync, mkdirSync, readFileSync } from "fs";
|
|
2
|
+
import { homedir } from "os";
|
|
3
|
+
import { dirname, join } from "path";
|
|
4
|
+
import { keysFor, loadOKedConfig, verifyChain, verifyReceipt, OKED_RECEIPT_KEYS_URL, } from "@oked/sdk";
|
|
5
|
+
/** The customer's own copy of every receipt this machine received. */
|
|
6
|
+
export const OKED_RECEIPTS_LOG = join(homedir(), ".oked", "receipts.jsonl");
|
|
7
|
+
/** Append one verified receipt. Best-effort: never blocks or breaks the agent. */
|
|
8
|
+
export function appendReceipt(receipt, path = OKED_RECEIPTS_LOG) {
|
|
9
|
+
try {
|
|
10
|
+
mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
|
|
11
|
+
appendFileSync(path, JSON.stringify(receipt) + "\n", { mode: 0o600 });
|
|
12
|
+
}
|
|
13
|
+
catch {
|
|
14
|
+
// The receipt is still stored by OKed; the local copy is a convenience.
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Verify a receipts file: every signature against OKed's published keys, and
|
|
19
|
+
* chain links between receipts that are adjacent. Gaps in seq are expected in a
|
|
20
|
+
* local copy (other devices and agents share the operator's chain); a broken
|
|
21
|
+
* link between adjacent receipts is not.
|
|
22
|
+
*/
|
|
23
|
+
export async function verifyReceiptsFile(path = OKED_RECEIPTS_LOG) {
|
|
24
|
+
const keysUrl = process.env.OKED_RECEIPT_KEYS_URL || loadOKedConfig().receiptKeysUrl || OKED_RECEIPT_KEYS_URL;
|
|
25
|
+
const lines = readFileSync(path, "utf-8").split("\n");
|
|
26
|
+
const receipts = [];
|
|
27
|
+
const report = { total: 0, valid: 0, invalid: [], unparsable: [], chains: [] };
|
|
28
|
+
for (let i = 0; i < lines.length; i++) {
|
|
29
|
+
const text = lines[i].trim();
|
|
30
|
+
if (!text)
|
|
31
|
+
continue;
|
|
32
|
+
report.total++;
|
|
33
|
+
let receipt;
|
|
34
|
+
try {
|
|
35
|
+
receipt = JSON.parse(text);
|
|
36
|
+
}
|
|
37
|
+
catch {
|
|
38
|
+
report.unparsable.push(i + 1);
|
|
39
|
+
continue;
|
|
40
|
+
}
|
|
41
|
+
const check = verifyReceipt(receipt, { keys: await keysFor(String(receipt?.kid ?? ""), { keysUrl }) });
|
|
42
|
+
if (check.ok) {
|
|
43
|
+
report.valid++;
|
|
44
|
+
receipts.push(receipt);
|
|
45
|
+
}
|
|
46
|
+
else {
|
|
47
|
+
report.invalid.push({ line: i + 1, receipt_id: receipt?.body?.receipt_id ?? null, problems: check.problems });
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
report.chains = verifyChain(receipts);
|
|
51
|
+
return report;
|
|
52
|
+
}
|
package/dist/version.js
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { readFileSync } from "fs";
|
|
2
|
+
import { dirname, join } from "path";
|
|
3
|
+
import { fileURLToPath } from "url";
|
|
4
|
+
// Derived from this package's package.json at runtime so the version the
|
|
5
|
+
// backend sees (client_version, receipts' requester.client) can never drift
|
|
6
|
+
// from what's actually shipped. From dist/*.js, package.json sits one dir up.
|
|
7
|
+
export const CLIENT_VERSION = (() => {
|
|
8
|
+
try {
|
|
9
|
+
const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
|
|
10
|
+
return JSON.parse(readFileSync(pkgPath, "utf-8")).version ?? "0.0.0";
|
|
11
|
+
}
|
|
12
|
+
catch {
|
|
13
|
+
return "0.0.0";
|
|
14
|
+
}
|
|
15
|
+
})();
|
|
16
|
+
export const CLIENT_ID = `@oked/claude-code@${CLIENT_VERSION}`;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oked/claude-code",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0",
|
|
4
4
|
"description": "OKed for Claude Code - zero-code human approval for sensitive actions",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -44,7 +44,7 @@
|
|
|
44
44
|
"access": "public"
|
|
45
45
|
},
|
|
46
46
|
"dependencies": {
|
|
47
|
-
"@oked/sdk": "0.
|
|
47
|
+
"@oked/sdk": "0.6.0"
|
|
48
48
|
},
|
|
49
49
|
"devDependencies": {
|
|
50
50
|
"typescript": "^5.6.0"
|