@oked/claude-code 0.4.0 → 0.5.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 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`. Set `OKED_REQUIRE_RECEIPT=1` to deny any decision without a valid receipt (the default from 0.6.0). See [docs/receipts.md](../../docs/receipts.md).
65
+
61
66
  ## Degraded-mode behavior
62
67
 
63
- Explicit denials and invalid API keys 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.
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 OKedAuthError) {
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>;
@@ -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
+ }
@@ -0,0 +1,2 @@
1
+ export declare const CLIENT_VERSION: string;
2
+ export declare const CLIENT_ID: string;
@@ -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.4.0",
3
+ "version": "0.5.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.4.0"
47
+ "@oked/sdk": "0.5.0"
48
48
  },
49
49
  "devDependencies": {
50
50
  "typescript": "^5.6.0"