@agent-blueprint-protocol/verifier 0.7.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.
Files changed (78) hide show
  1. package/CHANGELOG.md +891 -0
  2. package/LICENSE +190 -0
  3. package/NOTICE +4 -0
  4. package/README.md +199 -0
  5. package/dist/corpus/cases/base64url-decode.json +1 -0
  6. package/dist/corpus/cases/blueprint-decode.json +1 -0
  7. package/dist/corpus/cases/bounds-new.json +1 -0
  8. package/dist/corpus/cases/bounds_algebra-intersect.json +1 -0
  9. package/dist/corpus/cases/canonicalization-encode.json +1 -0
  10. package/dist/corpus/cases/compatibility-verify.json +1 -0
  11. package/dist/corpus/cases/deployment-decode.json +1 -0
  12. package/dist/corpus/cases/digest-tagged.json +1 -0
  13. package/dist/corpus/cases/extension-resolve.json +1 -0
  14. package/dist/corpus/cases/federation-decode.json +1 -0
  15. package/dist/corpus/cases/federation-verify_commitment.json +1 -0
  16. package/dist/corpus/cases/json-decode.json +1 -0
  17. package/dist/corpus/cases/negotiation-negotiate.json +1 -0
  18. package/dist/corpus/cases/portability-scan.json +1 -0
  19. package/dist/corpus/cases/schema-validate_instance.json +1 -0
  20. package/dist/corpus/cases/signature-verify.json +1 -0
  21. package/dist/corpus/index.json +1 -0
  22. package/dist/corpus/schemas/estate-contract.schema.json +1 -0
  23. package/dist/corpus/schemas/object.schema.json +1 -0
  24. package/dist/corpus/vectors/blueprint-golden.json +1 -0
  25. package/dist/corpus/vectors/deployment-golden.json +1 -0
  26. package/dist/corpus/vectors/rfc8785-numbers.json +1 -0
  27. package/dist/kit/cli.mjs +24 -0
  28. package/dist/verifier/b64url.d.ts +16 -0
  29. package/dist/verifier/b64url.js +36 -0
  30. package/dist/verifier/blueprint.d.ts +56 -0
  31. package/dist/verifier/blueprint.js +795 -0
  32. package/dist/verifier/bounds.d.ts +19 -0
  33. package/dist/verifier/bounds.js +45 -0
  34. package/dist/verifier/bounds_algebra.d.ts +27 -0
  35. package/dist/verifier/bounds_algebra.js +282 -0
  36. package/dist/verifier/canonical.d.ts +17 -0
  37. package/dist/verifier/canonical.js +160 -0
  38. package/dist/verifier/cli.d.ts +1 -0
  39. package/dist/verifier/cli.js +149 -0
  40. package/dist/verifier/compatibility.d.ts +22 -0
  41. package/dist/verifier/compatibility.js +112 -0
  42. package/dist/verifier/corpus.d.ts +42 -0
  43. package/dist/verifier/corpus.js +672 -0
  44. package/dist/verifier/decode.d.ts +16 -0
  45. package/dist/verifier/decode.js +457 -0
  46. package/dist/verifier/deployment.d.ts +49 -0
  47. package/dist/verifier/deployment.js +830 -0
  48. package/dist/verifier/digest.d.ts +23 -0
  49. package/dist/verifier/digest.js +58 -0
  50. package/dist/verifier/extension.d.ts +11 -0
  51. package/dist/verifier/extension.js +75 -0
  52. package/dist/verifier/federation.d.ts +76 -0
  53. package/dist/verifier/federation.js +817 -0
  54. package/dist/verifier/negotiation.d.ts +29 -0
  55. package/dist/verifier/negotiation.js +324 -0
  56. package/dist/verifier/portability.d.ts +12 -0
  57. package/dist/verifier/portability.js +184 -0
  58. package/dist/verifier/predicate.d.ts +10 -0
  59. package/dist/verifier/predicate.js +172 -0
  60. package/dist/verifier/registry.d.ts +16 -0
  61. package/dist/verifier/registry.js +120 -0
  62. package/dist/verifier/registry_engine.d.ts +42 -0
  63. package/dist/verifier/registry_engine.js +220 -0
  64. package/dist/verifier/report.d.ts +13 -0
  65. package/dist/verifier/report.js +29 -0
  66. package/dist/verifier/run_corpus.d.ts +1 -0
  67. package/dist/verifier/run_corpus.js +81 -0
  68. package/dist/verifier/runner.d.ts +20 -0
  69. package/dist/verifier/runner.js +778 -0
  70. package/dist/verifier/schema.d.ts +20 -0
  71. package/dist/verifier/schema.js +623 -0
  72. package/dist/verifier/self_checks.d.ts +1 -0
  73. package/dist/verifier/self_checks.js +316 -0
  74. package/dist/verifier/signature.d.ts +23 -0
  75. package/dist/verifier/signature.js +226 -0
  76. package/dist/verifier/value.d.ts +44 -0
  77. package/dist/verifier/value.js +77 -0
  78. package/package.json +42 -0
@@ -0,0 +1,149 @@
1
+ // The verifier CLI — the mirror of AgentBlueprintProtocol.Conformance.Cli:
2
+ // `--corpus <dir>` is REQUIRED (no default, so a vacuous run is impossible);
3
+ // exit 0 agreement, 1 disagreement, 2 usage error or corpus integrity
4
+ // failure. Report bytes go to stdout with NO trailing newline — including
5
+ // on exit 1 (disagreement still prints the report; the escript's
6
+ // IO.binwrite parity). Exit 3 marks an internal invariant (outside the
7
+ // 0/1/2 contract, exactly as an escript crash is — loud, never laundered
8
+ // into "disagreement").
9
+ import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
10
+ import { join } from "node:path";
11
+ import { load } from "./corpus.js";
12
+ import { encode } from "./canonical.js";
13
+ import { toBytes } from "./report.js";
14
+ import { run } from "./runner.js";
15
+ import { decode as decodeBlueprint } from "./blueprint.js";
16
+ import { decode as decodeDeployment } from "./deployment.js";
17
+ import { decode as decodeEnvelope } from "./federation.js";
18
+ import { obj, str } from "./value.js";
19
+ const USAGE = "usage: node verifier/cli.ts --corpus <dir> | --artifact <file>";
20
+ const BYTE_CAP = 5_000_000;
21
+ function main(argv) {
22
+ if (argv.length === 2 && argv[0] === "--artifact" && argv[1] !== "" && typeof argv[1] === "string") {
23
+ return verifyArtifact(argv[1]);
24
+ }
25
+ if (!(argv.length === 2 && argv[0] === "--corpus" && argv[1] !== "" && typeof argv[1] === "string")) {
26
+ process.stderr.write(USAGE + "\n");
27
+ return 2;
28
+ }
29
+ const dir = argv[1];
30
+ let map;
31
+ try {
32
+ map = readCorpus(dir);
33
+ }
34
+ catch {
35
+ process.stderr.write("corpus unreadable: a file is missing, unreadable, or over the byte ceiling\n");
36
+ return 2;
37
+ }
38
+ const corpus = load(map);
39
+ if (!corpus.ok) {
40
+ // Value-free by construction: the code names the corpus's own state.
41
+ // The ":" prefix mirrors the escript's inspect(error.code) formatting.
42
+ process.stderr.write("corpus integrity failure: :" + corpus.e + "\n");
43
+ return 2;
44
+ }
45
+ const results = run(corpus.v);
46
+ const bytes = toBytes(corpus.v.identity, results);
47
+ // exitCode (not process.exit) so piped stdout drains before exit.
48
+ process.stdout.write(bytes);
49
+ const agreed = results.flat().filter((r) => r.agree).length;
50
+ return agreed === results.flat().length && agreed > 0 ? 0 : 1;
51
+ }
52
+ // Single-artifact mode — a kit-side convenience the escript deliberately
53
+ // does NOT mirror (its CLI contract stays --corpus-only, so a vacuous run
54
+ // stays impossible there). One artifact file, verified against all three
55
+ // artifact kinds; valid iff any kind decodes. A valid report names the
56
+ // kind; an invalid report names each kind's typed denial code, so the
57
+ // file's own shape is legible from the report alone. The agreement
58
+ // script replays every decode-surface corpus case through this mode and
59
+ // requires the case's own expected verdict (the mode's gate).
60
+ function verifyArtifact(path) {
61
+ let bytes;
62
+ try {
63
+ const info = statSync(path);
64
+ if (!info.isFile())
65
+ throw new Error("not a regular file");
66
+ if (info.size > BYTE_CAP)
67
+ throw new Error("over byte ceiling");
68
+ bytes = readFileSync(path);
69
+ }
70
+ catch {
71
+ process.stderr.write("artifact unreadable: missing, not a regular file, or over the byte ceiling\n");
72
+ return 2;
73
+ }
74
+ const blueprint = decodeBlueprint(bytes);
75
+ const deployment = decodeDeployment(bytes);
76
+ const envelope = decodeEnvelope(bytes);
77
+ const kind = blueprint.ok ? "blueprint" : deployment.ok ? "deployment" : envelope.ok ? "federation" : null;
78
+ const members = [
79
+ ["format", str("agent-blueprint-protocol-artifact-report")],
80
+ ["verdict", str(kind === null ? "invalid" : "valid")],
81
+ ];
82
+ if (kind === null) {
83
+ members.push(["blueprint", str(blueprint.ok ? "valid" : blueprint.e)], ["deployment", str(deployment.ok ? "valid" : deployment.e)], ["federation", str(envelope.ok ? "valid" : envelope.e)]);
84
+ }
85
+ else {
86
+ members.push(["kind", str(kind)]);
87
+ }
88
+ const encoded = encode(obj(members));
89
+ if (!encoded.ok)
90
+ throw new Error("artifact report must encode");
91
+ process.stdout.write(encoded.v);
92
+ return kind === null ? 1 : 0;
93
+ }
94
+ // Reads EVERY file under the corpus directory — dotfiles included — so the
95
+ // loader's file-set equality sees exactly what the directory carries.
96
+ // Per-file size cap at the Bounds byte ceiling; a hostile corpus directory
97
+ // cannot exhaust memory or crash past the exit-code contract. Directory
98
+ // symlinks are followed (Path.wildcard parity).
99
+ function readCorpus(dir) {
100
+ const map = new Map();
101
+ const visited = new Set();
102
+ const walk = (current) => {
103
+ // Cycle bound: directory symlinks repeat their realpath; a repeat is
104
+ // skipped so the walk terminates inside the corpus-error contract.
105
+ const real = realpathSync(current);
106
+ if (visited.has(real))
107
+ return;
108
+ visited.add(real);
109
+ for (const entry of readdirSync(current, { withFileTypes: true })) {
110
+ const path = join(current, entry.name);
111
+ if (entry.isDirectory() || (entry.isSymbolicLink() && statSync(path).isDirectory())) {
112
+ walk(path);
113
+ }
114
+ else {
115
+ const info = statSync(path);
116
+ // Regular files only: a FIFO/socket/device planted in the corpus
117
+ // directory would block readFileSync past the exit contract — skip
118
+ // it and let the loader's file-set equality deny (loud, not a hang).
119
+ if (info.isFile()) {
120
+ if (info.size > BYTE_CAP)
121
+ throw new Error("over byte ceiling");
122
+ map.set(path.slice(dir.length + 1), readFileSync(path));
123
+ }
124
+ }
125
+ }
126
+ };
127
+ // A missing (or non-directory) corpus root yields an EMPTY map — the
128
+ // loader then denies corpus_index_invalid, exactly as the escript's
129
+ // empty-wildcard path does (integrity failure, not unreadable).
130
+ if (!existsDirectory(dir))
131
+ return map;
132
+ walk(dir);
133
+ return map;
134
+ }
135
+ function existsDirectory(dir) {
136
+ try {
137
+ return statSync(dir).isDirectory();
138
+ }
139
+ catch {
140
+ return false;
141
+ }
142
+ }
143
+ try {
144
+ process.exitCode = main(process.argv.slice(2));
145
+ }
146
+ catch (error) {
147
+ process.stderr.write("verifier internal error: " + error.message + "\n");
148
+ process.exitCode = 3;
149
+ }
@@ -0,0 +1,22 @@
1
+ import type { Deployment } from "./deployment.ts";
2
+ import type { Value } from "./value.ts";
3
+ export interface ObservedIdentity {
4
+ kind: string | null | Value;
5
+ name: string | null | Value;
6
+ version: string | null | Value;
7
+ digest: string | null | Value;
8
+ }
9
+ export interface Observed {
10
+ identities: ObservedIdentity[];
11
+ }
12
+ type VResult = {
13
+ ok: true;
14
+ } | {
15
+ ok: false;
16
+ e: string;
17
+ };
18
+ export declare function verify(deployment: Deployment, observed: Observed): VResult;
19
+ export declare function exact(identity: {
20
+ version: string | null;
21
+ }): boolean;
22
+ export {};
@@ -0,0 +1,112 @@
1
+ // The compatibility surface — the mirror of AgentBlueprintProtocol.Compatibility:
2
+ // identity-exact or error. A manifest identity (one build_identities entry)
3
+ // is matched only by an observed identity carrying the EXACT
4
+ // (kind, name, version, digest) tuple; ranges deny
5
+ // compatibility_identity_inexact on BOTH sides; a manifest identity with no
6
+ // exact observed counterpart denies compatibility_entry_missing; duplicate
7
+ // candidates deny compatibility_duplicate_entry.
8
+ import * as digest from "./digest.js";
9
+ import { keyfind } from "./registry_engine.js";
10
+ const IDENTITY_KEYS = ["kind", "name", "version", "digest"];
11
+ const EXACT_CHARSET = /^[A-Za-z0-9.+-]+$/;
12
+ export function verify(deployment, observed) {
13
+ const manifest = manifestIdentities(deployment);
14
+ if (!manifest.ok)
15
+ return manifest;
16
+ const validated = validatedObserved(observed.identities);
17
+ if (!validated.ok)
18
+ return validated;
19
+ return matchManifest(manifest.v, validated.v);
20
+ }
21
+ // The exactness predicate (public on the twin): total over junk input — any
22
+ // non-conforming shape answers false.
23
+ export function exact(identity) {
24
+ const version = identity.version;
25
+ if (typeof version !== "string")
26
+ return false;
27
+ const release = version.split("-")[0].split("+")[0];
28
+ const segments = release.split(".");
29
+ const lowered = version.toLowerCase();
30
+ return (version !== "" &&
31
+ EXACT_CHARSET.test(version) &&
32
+ !["*", "latest"].includes(lowered) &&
33
+ !segments.some((s) => ["x", "X", "*"].includes(s)));
34
+ }
35
+ // The manifest side: read build_identities with member indices. Absent
36
+ // member, non-array member, empty array, or a malformed entry denies typed.
37
+ function manifestIdentities(deployment) {
38
+ if (deployment.value.t !== "obj")
39
+ return { ok: false, e: "invalid_type" };
40
+ const found = keyfind(deployment.value.v, "build_identities");
41
+ if (found === null)
42
+ return { ok: false, e: "missing_required_field" };
43
+ if (found.t !== "arr")
44
+ return { ok: false, e: "invalid_type" };
45
+ if (found.v.length === 0)
46
+ return { ok: false, e: "invalid_cardinality" };
47
+ const out = [];
48
+ for (const entry of found.v) {
49
+ const identity = identityOf(entry);
50
+ if (identity === null)
51
+ return { ok: false, e: "invalid_type" };
52
+ out.push(identity);
53
+ }
54
+ return { ok: true, v: out };
55
+ }
56
+ // Exactly the four members, every value a string.
57
+ function identityOf(entry) {
58
+ if (entry.t !== "obj" || entry.v.length !== 4)
59
+ return null;
60
+ const identity = {};
61
+ for (const key of IDENTITY_KEYS) {
62
+ const found = keyfind(entry.v, key);
63
+ if (found === null || found.t !== "str")
64
+ return null;
65
+ identity[key] = found.v;
66
+ }
67
+ return identity;
68
+ }
69
+ // The observed side: host-built, so every shape is checked here.
70
+ function validatedObserved(identities) {
71
+ const out = [];
72
+ for (const identity of identities) {
73
+ const record = identity;
74
+ const wellFormed = typeof record === "object" &&
75
+ record !== null &&
76
+ Object.keys(record).length === 4 &&
77
+ IDENTITY_KEYS.every((key) => typeof record[key] === "string");
78
+ if (!wellFormed)
79
+ return { ok: false, e: "invalid_type" };
80
+ const shaped = identity;
81
+ if (!exact(shaped))
82
+ return { ok: false, e: "compatibility_identity_inexact" };
83
+ out.push(shaped);
84
+ }
85
+ return { ok: true, v: out };
86
+ }
87
+ // Match, manifest member order: per identity — its own exactness, the
88
+ // unique-by name re-assertion, then the observed candidates with the exact
89
+ // tuple. None denies missing; many deny duplicate; one emits the check with
90
+ // the parsed observed digest.
91
+ function matchManifest(manifest, observed) {
92
+ const seen = new Set();
93
+ for (const identity of manifest) {
94
+ if (!exact(identity))
95
+ return { ok: false, e: "compatibility_identity_inexact" };
96
+ if (seen.has(identity.name))
97
+ return { ok: false, e: "compatibility_duplicate_entry" };
98
+ const candidates = observed.filter((o) => matches(identity, o));
99
+ if (candidates.length === 0)
100
+ return { ok: false, e: "compatibility_entry_missing" };
101
+ if (candidates.length > 1)
102
+ return { ok: false, e: "compatibility_duplicate_entry" };
103
+ const parsed = digest.fromTagged(candidates[0].digest);
104
+ if (!parsed.ok)
105
+ return parsed;
106
+ seen.add(identity.name);
107
+ }
108
+ return { ok: true };
109
+ }
110
+ function matches(identity, observed) {
111
+ return IDENTITY_KEYS.every((key) => identity[key] === observed[key]);
112
+ }
@@ -0,0 +1,42 @@
1
+ import type { Value } from "./value.ts";
2
+ export declare const SURFACES: readonly ["json.decode", "canonicalization.encode", "base64url.decode", "digest.tagged", "signature.verify", "schema.validate_instance", "blueprint.decode", "deployment.decode", "negotiation.negotiate", "extension.resolve", "bounds.new", "bounds_algebra.intersect", "portability.scan", "compatibility.verify", "federation.decode", "federation.verify_commitment"];
3
+ export declare const CLASSES: readonly ["valid", "boundary_near", "exact_bound", "maximum_plus_one", "invalid_encoding", "invalid_duplicate", "invalid_type", "invalid_constraint", "invalid_cardinality", "unknown_member", "tamper_meaningful_byte", "digest_mismatch", "signature_invalid", "revision_above_max", "revision_below_min", "required_field_unsupported", "required_field_not_covered", "extension_unknown_critical", "extension_unknown_optional_roundtrip", "extension_criticality_conflict", "extension_schema_unavailable", "extension_deprecated_retained", "bound_widening_operational", "bound_widening_protected", "forbidden_portable_value", "compatibility_range_rejected", "binding_stale", "federation_state_unmappable", "federation_terminal_conflict", "audience_mismatch", "terminal_equivocation"];
4
+ export interface LoadedCorpus {
5
+ index: Value;
6
+ indexBytes: Buffer;
7
+ cases: {
8
+ path: string;
9
+ cases: CaseObj[];
10
+ }[];
11
+ data: Map<string, Value>;
12
+ raws: Map<string, Buffer>;
13
+ caseIds: Set<string>;
14
+ identity: string;
15
+ }
16
+ export interface CaseObj {
17
+ id: string;
18
+ surface: string;
19
+ klass: string;
20
+ input: Value;
21
+ expected: Value;
22
+ tamper: TamperSpec | null;
23
+ raw: Value;
24
+ }
25
+ export interface TamperSpec {
26
+ baseCase: string;
27
+ byteIndex: number;
28
+ target: string | null;
29
+ xor: number;
30
+ }
31
+ type LoadResult = {
32
+ ok: true;
33
+ v: LoadedCorpus;
34
+ } | {
35
+ ok: false;
36
+ e: string;
37
+ };
38
+ export declare function load(map: Map<string, Buffer>): LoadResult;
39
+ export declare function member(container: Value, key: string): Value | null;
40
+ export declare function memberString(container: Value, key: string): string | null;
41
+ export declare function memberNumber(container: Value, key: string): number | null;
42
+ export {};