@oked/verify 0.0.0-stage → 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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 OKed
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,55 @@
1
- # Temporary Holding Version
1
+ # @oked/verify
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Verify OKed signed approval receipts offline. For auditors, security reviewers
4
+ and anyone who needs to prove what an agent was allowed to do, without
5
+ trusting OKed's database.
6
+
7
+ ```bash
8
+ npx @oked/verify oked-receipts-2026-09-01-to-2026-10-01.zip
9
+ ```
10
+
11
+ ```
12
+ 412 receipts: 412 valid, 0 invalid
13
+ decided by: 377 human, 21 rule, 14 system (3 where the approver also ran the agent)
14
+ outcomes: 389 approved, 9 denied, 14 timed out
15
+ chain op_7f3c...: 412 receipts, from seq 1 to 412
16
+ signed chain head (seq 412) matches
17
+ OK
18
+ ```
19
+
20
+ It checks:
21
+
22
+ - **Every signature** (Ed25519 over the RFC 8785 canonical body) against OKed's
23
+ public keys, and that the key was valid when the receipt was issued.
24
+ - **The hash chain**: each receipt names the digest of the one before it, so a
25
+ deleted receipt shows as a gap in `seq` and an edited one breaks the next link.
26
+ - **Signed chain heads** in the bundle (or ones you saved earlier) agree with
27
+ the receipts.
28
+ - **The exact action**, for one receipt, when you pass the original request
29
+ with `--subject`.
30
+
31
+ Inputs: an export bundle from the OKed dashboard (`.zip`), a `.jsonl` file
32
+ (one receipt per line, such as `~/.oked/receipts.jsonl`), or a `.json` file
33
+ with one receipt or an array. Keys come from the bundle's `keys.json`, from
34
+ `--keys <file>`, or from https://api.oked.ai/.well-known/oked-receipt-keys.json.
35
+
36
+ | Option | |
37
+ |---|---|
38
+ | `--keys <keys.json>` | Verify with these keys |
39
+ | `--keys-url <url>` | Fetch keys from this URL (https) |
40
+ | `--subject <file>` | The original request (`subject_core` JSON) for one receipt |
41
+ | `--json` | Print the full report as JSON |
42
+
43
+ Exit code 0 when everything verifies, 1 otherwise.
44
+
45
+ As a library:
46
+
47
+ ```ts
48
+ import { readBundle, verifyBundle, fetchKeys } from "@oked/verify";
49
+
50
+ const bundle = readBundle("export.zip");
51
+ const report = verifyBundle(bundle, bundle.keys ?? (await fetchKeys()));
52
+ ```
53
+
54
+ What a receipt proves and what it does not:
55
+ [docs/receipts.md](https://github.com/oked-ai/oked-sdk/blob/main/docs/receipts.md). MIT.
package/dist/cli.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
package/dist/cli.js ADDED
@@ -0,0 +1,92 @@
1
+ #!/usr/bin/env node
2
+ import { readFileSync } from "node:fs";
3
+ import { OKED_RECEIPT_KEYS_URL } from "@oked/receipt-core";
4
+ import { fetchKeys, readBundle, verifyBundle } from "./index.js";
5
+ const USAGE = `Usage: oked-verify <bundle.zip | receipts.jsonl | receipt.json> [options]
6
+
7
+ Verifies OKed signed approval receipts offline: every signature against OKed's
8
+ public keys, each key's validity window, and the hash chain (missing receipts,
9
+ edited receipts, agreement with signed chain heads).
10
+
11
+ Options:
12
+ --keys <keys.json> Verify with these keys (default: the bundle's keys.json,
13
+ else ${OKED_RECEIPT_KEYS_URL})
14
+ --keys-url <url> Fetch keys from this URL instead (https)
15
+ --subject <file> The original request (subject_core JSON) for one receipt;
16
+ checks that the receipt is for exactly that action
17
+ --json Print the full report as JSON
18
+ -h, --help Show this help
19
+
20
+ Exit code 0 when everything verifies, 1 otherwise.`;
21
+ function arg(args, name) {
22
+ const i = args.indexOf(name);
23
+ return i >= 0 ? args[i + 1] : undefined;
24
+ }
25
+ function plural(n, word) {
26
+ return `${n} ${word}${n === 1 ? "" : "s"}`;
27
+ }
28
+ function print(file, r) {
29
+ console.log(`${file}`);
30
+ console.log(` ${plural(r.total, "receipt")}: ${r.valid} valid, ${r.invalid.length + r.unparsable.length} invalid`);
31
+ const deciders = Object.entries(r.byDecider).map(([k, n]) => `${n} ${k}`).join(", ");
32
+ const decisions = Object.entries(r.byDecision).map(([k, n]) => `${n} ${k.replace("_", " ")}`).join(", ");
33
+ if (deciders)
34
+ console.log(` decided by: ${deciders}${r.samePerson ? ` (${r.samePerson} where the approver also ran the agent)` : ""}`);
35
+ if (decisions)
36
+ console.log(` outcomes: ${decisions}`);
37
+ for (const bad of r.invalid) {
38
+ console.log(` INVALID ${bad.receipt_id ?? "(no id)"}${bad.seq !== null ? ` seq ${bad.seq}` : ""}: ${bad.problems.join(", ")}`);
39
+ }
40
+ for (const where of r.unparsable)
41
+ console.log(` INVALID ${where}: not JSON`);
42
+ for (const c of r.chains) {
43
+ const start = c.from_genesis ? "from seq 1" : `from seq ${c.first_seq} (partial export)`;
44
+ console.log(` chain ${c.chain_id}: ${plural(c.count, "receipt")}, ${start} to ${c.last_seq}`);
45
+ for (const g of c.gaps)
46
+ console.log(` GAP: seq ${g.after + 1}..${g.before - 1} missing`);
47
+ for (const b of c.breaks)
48
+ console.log(` BROKEN at seq ${b.seq}: ${b.reason}`);
49
+ if (c.head) {
50
+ const head = c.head.digest_matches === false ? "DOES NOT MATCH" : c.head.missing_tail ? "is ahead of this export" : "matches";
51
+ console.log(` signed chain head (seq ${c.head.seq}) ${head}`);
52
+ }
53
+ }
54
+ for (const chain of r.badHeads)
55
+ console.log(` INVALID chain head for ${chain}`);
56
+ if (r.subject) {
57
+ console.log(` subject for ${r.subject.request_id}: ${r.subject.matches ? "matches the receipt" : "DOES NOT MATCH"}`);
58
+ }
59
+ console.log(r.ok ? "OK" : "PROBLEMS FOUND");
60
+ }
61
+ async function main() {
62
+ const args = process.argv.slice(2);
63
+ const file = args.find((a, i) => !a.startsWith("-") && !["--keys", "--keys-url", "--subject"].includes(args[i - 1]));
64
+ if (!file || args.includes("-h") || args.includes("--help")) {
65
+ console.log(USAGE);
66
+ return file ? 0 : 1;
67
+ }
68
+ const bundle = readBundle(file);
69
+ const keysFile = arg(args, "--keys");
70
+ const keysUrl = arg(args, "--keys-url");
71
+ let keys;
72
+ if (keysFile)
73
+ keys = JSON.parse(readFileSync(keysFile, "utf8")).keys;
74
+ else if (keysUrl)
75
+ keys = await fetchKeys(keysUrl);
76
+ else
77
+ keys = bundle.keys ?? (await fetchKeys());
78
+ const subjectFile = arg(args, "--subject");
79
+ const subject = subjectFile ? JSON.parse(readFileSync(subjectFile, "utf8")) : undefined;
80
+ const report = verifyBundle(bundle, keys, subject);
81
+ if (args.includes("--json"))
82
+ console.log(JSON.stringify(report, null, 2));
83
+ else
84
+ print(file, report);
85
+ return report.ok ? 0 : 1;
86
+ }
87
+ main().then((code) => {
88
+ process.exitCode = code;
89
+ }, (err) => {
90
+ console.error(err instanceof Error ? err.message : err);
91
+ process.exitCode = 1;
92
+ });
@@ -0,0 +1,51 @@
1
+ import { type ChainReport, type ReceiptKey, type ReceiptProblem, type SignedChainHead, type SignedReceipt, type ToolCallSubject } from "@oked/receipt-core";
2
+ import { unzip } from "./unzip.js";
3
+ export interface Bundle {
4
+ receipts: SignedReceipt[];
5
+ /** Keys shipped with the bundle (keys.json), if any. */
6
+ keys?: ReceiptKey[];
7
+ /** Signed chain heads shipped with the bundle (chain-head.json), if any. */
8
+ heads?: SignedChainHead[];
9
+ /** Lines or entries that were not valid JSON. */
10
+ unparsable: string[];
11
+ }
12
+ /**
13
+ * Read a receipt source: an export bundle (.zip with receipts.jsonl,
14
+ * keys.json, chain-head.json), a .jsonl file (one receipt per line, e.g.
15
+ * ~/.oked/receipts.jsonl), or a .json file with one receipt or an array.
16
+ */
17
+ export declare function readBundle(path: string): Bundle;
18
+ /** Fetch OKed's published keys. https only. */
19
+ export declare function fetchKeys(url?: string): Promise<ReceiptKey[]>;
20
+ export interface VerifyReport {
21
+ total: number;
22
+ valid: number;
23
+ invalid: {
24
+ receipt_id: string | null;
25
+ seq: number | null;
26
+ problems: ReceiptProblem[];
27
+ }[];
28
+ unparsable: string[];
29
+ /** Valid receipts by who decided: human, rule, system. */
30
+ byDecider: Record<string, number>;
31
+ /** Valid receipts by outcome: approved, denied, timed_out. */
32
+ byDecision: Record<string, number>;
33
+ /** Human decisions where the approver also ran the agent. */
34
+ samePerson: number;
35
+ chains: ChainReport[];
36
+ /** Chain heads that failed their own signature check. */
37
+ badHeads: string[];
38
+ /** Set when a subject was given (one receipt): does it match? */
39
+ subject?: {
40
+ request_id: string;
41
+ matches: boolean;
42
+ };
43
+ ok: boolean;
44
+ }
45
+ /**
46
+ * Verify a set of receipts: every signature and key window, the hash chain
47
+ * (gaps, broken links, agreement with signed chain heads) and, for one
48
+ * receipt, the original request when given.
49
+ */
50
+ export declare function verifyBundle(bundle: Bundle, keys: ReceiptKey[], subject?: ToolCallSubject): VerifyReport;
51
+ export { unzip };
package/dist/index.js ADDED
@@ -0,0 +1,106 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { OKED_RECEIPT_KEYS_URL, verifyChain, verifyReceipt, verifySigned, } from "@oked/receipt-core";
3
+ import { unzip } from "./unzip.js";
4
+ function parseJsonLines(text, where, unparsable) {
5
+ const out = [];
6
+ text.split("\n").forEach((line, i) => {
7
+ if (!line.trim())
8
+ return;
9
+ try {
10
+ out.push(JSON.parse(line));
11
+ }
12
+ catch {
13
+ unparsable.push(`${where}:${i + 1}`);
14
+ }
15
+ });
16
+ return out;
17
+ }
18
+ /**
19
+ * Read a receipt source: an export bundle (.zip with receipts.jsonl,
20
+ * keys.json, chain-head.json), a .jsonl file (one receipt per line, e.g.
21
+ * ~/.oked/receipts.jsonl), or a .json file with one receipt or an array.
22
+ */
23
+ export function readBundle(path) {
24
+ const raw = readFileSync(path);
25
+ const unparsable = [];
26
+ if (raw.subarray(0, 4).equals(Buffer.from([0x50, 0x4b, 0x03, 0x04]))) {
27
+ const files = unzip(raw);
28
+ const receipts = parseJsonLines(files.get("receipts.jsonl")?.toString("utf8") ?? "", "receipts.jsonl", unparsable);
29
+ const keys = files.has("keys.json") ? JSON.parse(files.get("keys.json").toString("utf8")).keys : undefined;
30
+ const heads = files.has("chain-head.json")
31
+ ? JSON.parse(files.get("chain-head.json").toString("utf8"))
32
+ : undefined;
33
+ return { receipts, keys, heads, unparsable };
34
+ }
35
+ const text = raw.toString("utf8");
36
+ if (path.endsWith(".jsonl"))
37
+ return { receipts: parseJsonLines(text, path, unparsable), unparsable };
38
+ const parsed = JSON.parse(text);
39
+ return { receipts: Array.isArray(parsed) ? parsed : [parsed], unparsable };
40
+ }
41
+ /** Fetch OKed's published keys. https only. */
42
+ export async function fetchKeys(url = OKED_RECEIPT_KEYS_URL) {
43
+ if (!url.startsWith("https://") && !/^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?\//.test(url)) {
44
+ throw new Error(`refusing to fetch keys over plain http: ${url}`);
45
+ }
46
+ const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
47
+ if (!res.ok)
48
+ throw new Error(`could not fetch keys from ${url}: HTTP ${res.status}`);
49
+ return (await res.json()).keys;
50
+ }
51
+ /**
52
+ * Verify a set of receipts: every signature and key window, the hash chain
53
+ * (gaps, broken links, agreement with signed chain heads) and, for one
54
+ * receipt, the original request when given.
55
+ */
56
+ export function verifyBundle(bundle, keys, subject) {
57
+ const report = {
58
+ total: bundle.receipts.length + bundle.unparsable.length,
59
+ valid: 0,
60
+ invalid: [],
61
+ unparsable: bundle.unparsable,
62
+ byDecider: {},
63
+ byDecision: {},
64
+ samePerson: 0,
65
+ chains: [],
66
+ badHeads: [],
67
+ ok: false,
68
+ };
69
+ const valid = [];
70
+ for (const r of bundle.receipts) {
71
+ const check = verifyReceipt(r, { keys });
72
+ if (!check.ok) {
73
+ report.invalid.push({ receipt_id: r?.body?.receipt_id ?? null, seq: r?.body?.seq ?? null, problems: check.problems });
74
+ continue;
75
+ }
76
+ report.valid++;
77
+ valid.push(r);
78
+ report.byDecider[r.body.decider.kind] = (report.byDecider[r.body.decider.kind] ?? 0) + 1;
79
+ report.byDecision[r.body.decision] = (report.byDecision[r.body.decision] ?? 0) + 1;
80
+ if (r.body.same_person)
81
+ report.samePerson++;
82
+ }
83
+ const heads = [];
84
+ for (const h of bundle.heads ?? []) {
85
+ if (verifySigned(h, keys).ok)
86
+ heads.push(h.body);
87
+ else
88
+ report.badHeads.push(h?.body?.chain_id ?? "(unknown chain)");
89
+ }
90
+ report.chains = verifyChain(valid, heads);
91
+ if (subject) {
92
+ const target = bundle.receipts.find((r) => r?.body?.request_id === subject.request_id);
93
+ report.subject = {
94
+ request_id: subject.request_id,
95
+ matches: !!target && verifyReceipt(target, { keys, subject }).ok,
96
+ };
97
+ }
98
+ report.ok =
99
+ report.invalid.length === 0 &&
100
+ report.unparsable.length === 0 &&
101
+ report.badHeads.length === 0 &&
102
+ report.chains.every((c) => c.breaks.length === 0 && c.head?.digest_matches !== false) &&
103
+ (report.subject?.matches ?? true);
104
+ return report;
105
+ }
106
+ export { unzip };
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Read the files of a zip (stored or deflate entries, no zip64) through its
3
+ * central directory. Enough for OKed export bundles.
4
+ */
5
+ export declare function unzip(buf: Buffer): Map<string, Buffer>;
package/dist/unzip.js ADDED
@@ -0,0 +1,35 @@
1
+ import { inflateRawSync } from "node:zlib";
2
+ /**
3
+ * Read the files of a zip (stored or deflate entries, no zip64) through its
4
+ * central directory. Enough for OKed export bundles.
5
+ */
6
+ export function unzip(buf) {
7
+ const sig = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
8
+ const end = buf.lastIndexOf(sig);
9
+ if (end < 0)
10
+ throw new Error("not a zip file");
11
+ const count = buf.readUInt16LE(end + 10);
12
+ let p = buf.readUInt32LE(end + 16);
13
+ const files = new Map();
14
+ for (let i = 0; i < count; i++) {
15
+ if (buf.readUInt32LE(p) !== 0x02014b50)
16
+ throw new Error("corrupt zip central directory");
17
+ const method = buf.readUInt16LE(p + 10);
18
+ const size = buf.readUInt32LE(p + 20);
19
+ const nameLen = buf.readUInt16LE(p + 28);
20
+ const extraLen = buf.readUInt16LE(p + 30);
21
+ const commentLen = buf.readUInt16LE(p + 32);
22
+ const local = buf.readUInt32LE(p + 42);
23
+ const name = buf.toString("utf8", p + 46, p + 46 + nameLen);
24
+ const start = local + 30 + buf.readUInt16LE(local + 26) + buf.readUInt16LE(local + 28);
25
+ const data = buf.subarray(start, start + size);
26
+ if (method === 8)
27
+ files.set(name, inflateRawSync(data));
28
+ else if (method === 0)
29
+ files.set(name, Buffer.from(data));
30
+ else
31
+ throw new Error(`unsupported zip compression method ${method} for ${name}`);
32
+ p += 46 + nameLen + extraLen + commentLen;
33
+ }
34
+ return files;
35
+ }
package/package.json CHANGED
@@ -1,6 +1,57 @@
1
1
  {
2
2
  "name": "@oked/verify",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.6.0",
4
+ "description": "Verify OKed signed approval receipts offline: signatures, keys, hash chain, subject",
5
+ "type": "module",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "bin": {
9
+ "oked-verify": "./dist/cli.js"
10
+ },
11
+ "exports": {
12
+ ".": {
13
+ "import": "./dist/index.js",
14
+ "types": "./dist/index.d.ts"
15
+ }
16
+ },
17
+ "scripts": {
18
+ "prebuild": "npm run build --workspace=@oked/receipt-core",
19
+ "build": "tsc",
20
+ "test": "tsx --test test/*.test.ts",
21
+ "prepublishOnly": "npm run build"
22
+ },
23
+ "files": [
24
+ "dist"
25
+ ],
26
+ "keywords": [
27
+ "approval",
28
+ "receipt",
29
+ "audit",
30
+ "verify",
31
+ "agents"
32
+ ],
33
+ "repository": {
34
+ "type": "git",
35
+ "url": "git+https://github.com/oked-ai/oked-sdk.git",
36
+ "directory": "packages/verify"
37
+ },
38
+ "bugs": {
39
+ "url": "https://github.com/oked-ai/oked-sdk/issues"
40
+ },
41
+ "homepage": "https://github.com/oked-ai/oked-sdk/blob/main/docs/receipts.md",
42
+ "license": "MIT",
43
+ "engines": {
44
+ "node": ">=18"
45
+ },
46
+ "publishConfig": {
47
+ "access": "public"
48
+ },
49
+ "dependencies": {
50
+ "@oked/receipt-core": "0.6.0"
51
+ },
52
+ "devDependencies": {
53
+ "@types/node": "^22.13.10",
54
+ "tsx": "^4.22.0",
55
+ "typescript": "^5.6.0"
56
+ }
57
+ }