@intentrax/sdk 1.6.0 → 1.8.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 +56 -3
- package/cli/intentrax.mjs +57 -1
- package/index.js +4 -2
- package/index.ts +4 -2
- package/mcp/README.md +138 -0
- package/mcp/canonical.d.ts +12 -0
- package/mcp/canonical.mjs +70 -0
- package/mcp/cli.d.ts +16 -0
- package/mcp/cli.mjs +214 -0
- package/mcp/client.d.ts +131 -0
- package/mcp/client.mjs +955 -0
- package/mcp/commands.d.ts +113 -0
- package/mcp/commands.mjs +575 -0
- package/mcp/index.d.ts +12 -0
- package/mcp/index.mjs +12 -0
- package/mcp/proxy.d.ts +47 -0
- package/mcp/proxy.mjs +434 -0
- package/mcp/receipt-meta.d.ts +59 -0
- package/mcp/receipt-meta.mjs +178 -0
- package/mcp/tool-manifest.d.ts +74 -0
- package/mcp/tool-manifest.mjs +154 -0
- package/package.json +19 -1
- package/readback/README.md +352 -0
- package/readback/bridge.mjs +71 -0
- package/readback/cli.mjs +150 -0
- package/readback/confirm.mjs +404 -0
- package/readback/index.mjs +12 -0
- package/readback/recipe-worker.mjs +33 -0
- package/readback/recipes/_shared.mjs +126 -0
- package/readback/recipes/email-delivery.mjs +136 -0
- package/readback/recipes/github-issue.mjs +88 -0
- package/readback/recipes/http-json.mjs +109 -0
- package/readback/recipes/sql-row.mjs +96 -0
- package/readback/recipes/stripe-refund.mjs +73 -0
- package/readback/redact.mjs +68 -0
- package/sandbox/README.md +255 -0
- package/sandbox/authority.mjs +66 -0
- package/sandbox/bundle.mjs +93 -0
- package/sandbox/canonical.mjs +64 -0
- package/sandbox/check-runner.mjs +50 -0
- package/sandbox/check-worker.mjs +30 -0
- package/sandbox/cli.mjs +376 -0
- package/sandbox/effect-verifier.mjs +242 -0
- package/sandbox/effects.mjs +80 -0
- package/sandbox/envelope.mjs +174 -0
- package/sandbox/examples/read-only-check.example.mjs +32 -0
- package/sandbox/external-decision.mjs +364 -0
- package/sandbox/keys.mjs +179 -0
- package/sandbox/model.mjs +170 -0
- package/sandbox/run.mjs +324 -0
- package/sandbox/time.mjs +18 -0
- package/sandbox/verifier.mjs +503 -0
- package/scan/README.md +211 -0
- package/scan/classify.mjs +276 -0
- package/scan/cli.mjs +102 -0
- package/scan/configs.mjs +261 -0
- package/scan/credentials.mjs +121 -0
- package/scan/extract.mjs +323 -0
- package/scan/gates.mjs +94 -0
- package/scan/report.mjs +58 -0
- package/scan/scan.mjs +571 -0
- package/scan/text.mjs +186 -0
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
// Effect definition for the local assurance sandbox.
|
|
2
|
+
//
|
|
3
|
+
// Adapted from examples/effect-assurance-demo/src/effects.mjs (PRs #449,
|
|
4
|
+
// #477). The demo defines three synthetic cloud operations; the sandbox has
|
|
5
|
+
// one generic operation, `SetState`: "make these fields of this resource have
|
|
6
|
+
// these values". It covers both the built-in sample action and a developer's
|
|
7
|
+
// own action checked with `--check`.
|
|
8
|
+
//
|
|
9
|
+
// The EXPECTED state is derived only from the signed decision (the fields and
|
|
10
|
+
// values that were authorised), never from anything the executor reports. The
|
|
11
|
+
// OBSERVED state is extracted from the read, limited to the authorised fields
|
|
12
|
+
// (the coverage boundary).
|
|
13
|
+
|
|
14
|
+
import { digest } from "./canonical.mjs";
|
|
15
|
+
|
|
16
|
+
export const OPERATION = "SetState";
|
|
17
|
+
|
|
18
|
+
export const OUTCOMES = Object.freeze({ APPLIED: "APPLIED", NOT_APPLIED: "NOT_APPLIED", PENDING: "PENDING" });
|
|
19
|
+
|
|
20
|
+
// Execution-report status -> the outcome it claims.
|
|
21
|
+
export function claimedOutcome(reportStatus) {
|
|
22
|
+
switch (reportStatus) {
|
|
23
|
+
case "SUCCEEDED":
|
|
24
|
+
return OUTCOMES.APPLIED;
|
|
25
|
+
case "ACCEPTED":
|
|
26
|
+
return OUTCOMES.PENDING;
|
|
27
|
+
case "FAILED":
|
|
28
|
+
return OUTCOMES.NOT_APPLIED;
|
|
29
|
+
default:
|
|
30
|
+
return null;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function pick(obj, keys) {
|
|
35
|
+
const out = {};
|
|
36
|
+
const src = obj !== null && typeof obj === "object" && !Array.isArray(obj) ? obj : {};
|
|
37
|
+
for (const k of keys.slice().sort()) {
|
|
38
|
+
out[k] = Object.prototype.hasOwnProperty.call(src, k) ? src[k] : null;
|
|
39
|
+
}
|
|
40
|
+
return out;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export const SET_STATE = Object.freeze({
|
|
44
|
+
operation: OPERATION,
|
|
45
|
+
max_age_seconds: 300,
|
|
46
|
+
consistency_model: "read treated as final; eventual consistency is not modelled in the sandbox",
|
|
47
|
+
coverage_boundary: "Only the fields named in the authorised state of one resource; nothing else about the resource was read.",
|
|
48
|
+
probe: (request) => ({ resource: request.resource, fields: Object.keys(request.params.state).sort() }),
|
|
49
|
+
// The read must be about this decision's resource.
|
|
50
|
+
bound: (request, body) => body !== null && typeof body === "object" && body.resource === request.resource,
|
|
51
|
+
expected(request, outcome) {
|
|
52
|
+
if (outcome !== OUTCOMES.APPLIED) return null; // NOT_APPLIED is not checkable without a pre-state
|
|
53
|
+
return { resource: request.resource, state: pick(request.params.state, Object.keys(request.params.state)) };
|
|
54
|
+
},
|
|
55
|
+
// A read only counts if it is an object that carries EVERY authorised field.
|
|
56
|
+
// A missing field must not be read as null: otherwise `{}` (or a string)
|
|
57
|
+
// would "confirm" an authorised `{ deleted_at: null }`.
|
|
58
|
+
observationProblems(request, body) {
|
|
59
|
+
const s = body.state;
|
|
60
|
+
if (s === null || typeof s !== "object" || Array.isArray(s)) return ["OBSERVED_STATE_NOT_AN_OBJECT"];
|
|
61
|
+
const missing = Object.keys(request.params.state)
|
|
62
|
+
.filter((k) => !Object.prototype.hasOwnProperty.call(s, k))
|
|
63
|
+
.sort();
|
|
64
|
+
return missing.length ? ["OBSERVED_FIELDS_MISSING:" + missing.join(",")] : [];
|
|
65
|
+
},
|
|
66
|
+
observed(request, body) {
|
|
67
|
+
return { resource: body.resource, state: pick(body.state, Object.keys(request.params.state)) };
|
|
68
|
+
},
|
|
69
|
+
finality: () => "FINAL",
|
|
70
|
+
});
|
|
71
|
+
|
|
72
|
+
export function effectFor(operation) {
|
|
73
|
+
if (operation !== OPERATION) throw new Error("no effect definition for " + operation);
|
|
74
|
+
return SET_STATE;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
export function expectedStateDigest(request, outcome) {
|
|
78
|
+
const e = effectFor(request.operation).expected(request, outcome);
|
|
79
|
+
return e === null ? null : digest(e);
|
|
80
|
+
}
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
// Signed envelopes for the local assurance sandbox.
|
|
2
|
+
//
|
|
3
|
+
// Ported from examples/effect-assurance-demo/src/envelope.mjs (PRs #449,
|
|
4
|
+
// #477). Changes: a sandbox-specific signing domain (so a local signature can
|
|
5
|
+
// never be replayed as any other Intentrax envelope), the payload types the
|
|
6
|
+
// sandbox uses, and no revocation handling (local keys are never revoked;
|
|
7
|
+
// they simply expire with the run).
|
|
8
|
+
//
|
|
9
|
+
// { payload_type, payload, signatures: [{ key_id, alg, public_key, sig }] }
|
|
10
|
+
//
|
|
11
|
+
// The signed message is ALWAYS rebuilt by the verifier from `payload_type` and
|
|
12
|
+
// `payload`: DOMAIN || canonical_json({ payload_type, payload }).
|
|
13
|
+
// `public_key` inside a signature entry is SELF-ASSERTED; it is used only to
|
|
14
|
+
// check record integrity when no pinned key matches and never establishes who
|
|
15
|
+
// signed.
|
|
16
|
+
|
|
17
|
+
import { sign as edSign, verify as edVerify } from "node:crypto";
|
|
18
|
+
import { canonicalJson, digest } from "./canonical.mjs";
|
|
19
|
+
import { publicKeyFromRaw, ROLES } from "./keys.mjs";
|
|
20
|
+
import { isoMs } from "./time.mjs";
|
|
21
|
+
|
|
22
|
+
const DOMAIN = "intentrax-local-sandbox-envelope/0.1\n";
|
|
23
|
+
|
|
24
|
+
export const PAYLOAD_TYPES = Object.freeze({
|
|
25
|
+
MANDATE: "intentrax.mandate/0.1",
|
|
26
|
+
DECISION: "intentrax.decision/0.1",
|
|
27
|
+
EXECUTION_REPORT: "intentrax.execution_report/0.1",
|
|
28
|
+
EFFECT_EVIDENCE: "intentrax.effect_evidence/0.1",
|
|
29
|
+
BUNDLE_SEAL: "intentrax.local_bundle_seal/0.1",
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
export const SIGNING_TIME_FIELD = Object.freeze({
|
|
33
|
+
[PAYLOAD_TYPES.MANDATE]: "issued_at",
|
|
34
|
+
[PAYLOAD_TYPES.DECISION]: "decided_at",
|
|
35
|
+
[PAYLOAD_TYPES.EXECUTION_REPORT]: "reported_at",
|
|
36
|
+
[PAYLOAD_TYPES.EFFECT_EVIDENCE]: "attested_at",
|
|
37
|
+
[PAYLOAD_TYPES.BUNDLE_SEAL]: "sealed_at",
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
export function expectedRole(payloadType) {
|
|
41
|
+
switch (payloadType) {
|
|
42
|
+
case PAYLOAD_TYPES.MANDATE:
|
|
43
|
+
return ROLES.PRINCIPAL;
|
|
44
|
+
case PAYLOAD_TYPES.DECISION:
|
|
45
|
+
case PAYLOAD_TYPES.BUNDLE_SEAL:
|
|
46
|
+
return ROLES.DECISION_SERVICE;
|
|
47
|
+
case PAYLOAD_TYPES.EXECUTION_REPORT:
|
|
48
|
+
return ROLES.EXECUTOR;
|
|
49
|
+
case PAYLOAD_TYPES.EFFECT_EVIDENCE:
|
|
50
|
+
return ROLES.EFFECT_VERIFIER;
|
|
51
|
+
default:
|
|
52
|
+
return null;
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function signingMessage(payloadType, payload) {
|
|
57
|
+
return Buffer.from(DOMAIN + canonicalJson({ payload_type: payloadType, payload }), "utf8");
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export function signEnvelope(payloadType, payload, signer) {
|
|
61
|
+
const sig = edSign(null, signingMessage(payloadType, payload), signer.privateKey);
|
|
62
|
+
return {
|
|
63
|
+
payload_type: payloadType,
|
|
64
|
+
payload,
|
|
65
|
+
signatures: [{
|
|
66
|
+
key_id: signer.key_id,
|
|
67
|
+
alg: "Ed25519",
|
|
68
|
+
public_key: signer.public_key,
|
|
69
|
+
sig: sig.toString("base64url"),
|
|
70
|
+
}],
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
// Content digest of an envelope: binds payload_type + payload.
|
|
75
|
+
export function envelopeDigest(envelope) {
|
|
76
|
+
return digest({ payload_type: envelope.payload_type, payload: envelope.payload });
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// Verify one envelope. Returns a structured result; never throws on bad input.
|
|
80
|
+
// integrity: VERIFIED | FAILED
|
|
81
|
+
// authenticity: VERIFIED | FAILED | INSUFFICIENT_EVIDENCE (signer unknown) | NOT_ASSESSED (no key set)
|
|
82
|
+
export function verifyEnvelope(envelope, { pinned = null } = {}) {
|
|
83
|
+
const out = { integrity: "FAILED", authenticity: "FAILED", key_id: null, reasons: [] };
|
|
84
|
+
const fail = (reason, which = "both") => {
|
|
85
|
+
out.reasons.push(reason);
|
|
86
|
+
if (which === "both" || which === "integrity") out.integrity = "FAILED";
|
|
87
|
+
if (which === "both" || which === "authenticity") out.authenticity = "FAILED";
|
|
88
|
+
return out;
|
|
89
|
+
};
|
|
90
|
+
if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
|
|
91
|
+
return fail("ENVELOPE_MALFORMED");
|
|
92
|
+
}
|
|
93
|
+
if (Object.keys(envelope).sort().join(",") !== "payload,payload_type,signatures") {
|
|
94
|
+
return fail("ENVELOPE_UNEXPECTED_FIELDS");
|
|
95
|
+
}
|
|
96
|
+
if (!Object.values(PAYLOAD_TYPES).includes(envelope.payload_type)) {
|
|
97
|
+
return fail("ENVELOPE_UNKNOWN_PAYLOAD_TYPE");
|
|
98
|
+
}
|
|
99
|
+
if (!Array.isArray(envelope.signatures) || envelope.signatures.length !== 1) {
|
|
100
|
+
return fail("ENVELOPE_REQUIRES_EXACTLY_ONE_SIGNATURE");
|
|
101
|
+
}
|
|
102
|
+
const s = envelope.signatures[0];
|
|
103
|
+
if (!s || typeof s !== "object" || Object.keys(s).sort().join(",") !== "alg,key_id,public_key,sig" || s.alg !== "Ed25519") {
|
|
104
|
+
return fail("SIGNATURE_ENTRY_MALFORMED");
|
|
105
|
+
}
|
|
106
|
+
out.key_id = s.key_id;
|
|
107
|
+
let message;
|
|
108
|
+
try {
|
|
109
|
+
message = signingMessage(envelope.payload_type, envelope.payload);
|
|
110
|
+
} catch {
|
|
111
|
+
return fail("PAYLOAD_NOT_CANONICALIZABLE");
|
|
112
|
+
}
|
|
113
|
+
const sig = Buffer.from(String(s.sig), "base64url");
|
|
114
|
+
const check = (publicKey) => {
|
|
115
|
+
try {
|
|
116
|
+
return edVerify(null, message, publicKey, sig);
|
|
117
|
+
} catch {
|
|
118
|
+
return false;
|
|
119
|
+
}
|
|
120
|
+
};
|
|
121
|
+
|
|
122
|
+
const pinnedEntry = pinned ? pinned.get(s.key_id) : undefined;
|
|
123
|
+
if (pinnedEntry) {
|
|
124
|
+
if (s.public_key !== pinnedEntry.public_key) {
|
|
125
|
+
return fail("EMBEDDED_KEY_DIFFERS_FROM_PINNED_KEY");
|
|
126
|
+
}
|
|
127
|
+
if (!check(pinnedEntry.publicKey)) {
|
|
128
|
+
return fail("SIGNATURE_INVALID_FOR_PINNED_KEY");
|
|
129
|
+
}
|
|
130
|
+
out.integrity = "VERIFIED";
|
|
131
|
+
const role = expectedRole(envelope.payload_type);
|
|
132
|
+
if (pinnedEntry.role !== role) {
|
|
133
|
+
return fail("SIGNER_ROLE_MISMATCH:" + pinnedEntry.role + "!=" + role, "authenticity");
|
|
134
|
+
}
|
|
135
|
+
const field = SIGNING_TIME_FIELD[envelope.payload_type];
|
|
136
|
+
// Strict timestamps (explicit offset; #491 parity).
|
|
137
|
+
const signedAt = isoMs(envelope.payload && envelope.payload[field]);
|
|
138
|
+
if (signedAt === null) {
|
|
139
|
+
return fail("SIGNING_TIME_MISSING", "authenticity");
|
|
140
|
+
}
|
|
141
|
+
// The loader guarantees the bounds parse (strict, explicit offset, from < until).
|
|
142
|
+
if (signedAt < isoMs(pinnedEntry.valid_from) || signedAt >= isoMs(pinnedEntry.valid_until)) {
|
|
143
|
+
return fail("SIGNER_KEY_NOT_VALID_AT_SIGNING_TIME", "authenticity");
|
|
144
|
+
}
|
|
145
|
+
out.authenticity = "VERIFIED";
|
|
146
|
+
out.signer = {
|
|
147
|
+
key_id: pinnedEntry.key_id,
|
|
148
|
+
role: pinnedEntry.role,
|
|
149
|
+
principal: pinnedEntry.principal,
|
|
150
|
+
environment: pinnedEntry.environment,
|
|
151
|
+
trust_bearing: pinnedEntry.trust_bearing,
|
|
152
|
+
};
|
|
153
|
+
return out;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
let embedded;
|
|
157
|
+
try {
|
|
158
|
+
embedded = publicKeyFromRaw(String(s.public_key));
|
|
159
|
+
} catch {
|
|
160
|
+
return fail("SIGNATURE_UNVERIFIABLE_NO_KEY");
|
|
161
|
+
}
|
|
162
|
+
if (!check(embedded)) {
|
|
163
|
+
return fail("SIGNATURE_INVALID_FOR_EMBEDDED_KEY");
|
|
164
|
+
}
|
|
165
|
+
out.integrity = "VERIFIED";
|
|
166
|
+
if (pinned) {
|
|
167
|
+
out.authenticity = "INSUFFICIENT_EVIDENCE";
|
|
168
|
+
out.reasons.push("SIGNER_NOT_IN_PINNED_KEY_SET");
|
|
169
|
+
} else {
|
|
170
|
+
out.authenticity = "NOT_ASSESSED";
|
|
171
|
+
out.reasons.push("NO_LOCAL_KEY_SET_SUPPLIED");
|
|
172
|
+
}
|
|
173
|
+
return out;
|
|
174
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
// Example read-only check for `intentrax sandbox --check`.
|
|
2
|
+
//
|
|
3
|
+
// Copy this file, point it at YOUR system, and run it AFTER your agent's
|
|
4
|
+
// action has run:
|
|
5
|
+
//
|
|
6
|
+
// intentrax sandbox --check ./my-check.mjs
|
|
7
|
+
//
|
|
8
|
+
// Contract:
|
|
9
|
+
// - `expected` (required): the fields your action should have set, and the
|
|
10
|
+
// values it should have set them to. Plain JSON, integers only. This is
|
|
11
|
+
// what the local decision authorises, and what the read is compared with.
|
|
12
|
+
// - `resource` (optional): a label for the thing being checked.
|
|
13
|
+
// - default export: an async function that READS the current state and
|
|
14
|
+
// returns an object containing at least the fields in `expected`. Only
|
|
15
|
+
// those fields are compared (the coverage boundary).
|
|
16
|
+
//
|
|
17
|
+
// Read-only by contract: the sandbox calls this function once and never
|
|
18
|
+
// calls your write path. It cannot stop this function from writing, so keep
|
|
19
|
+
// it to reads. Because you wrote it, the sandbox labels the read
|
|
20
|
+
// SELF_REPORTED, not an Intentrax-pulled authoritative read.
|
|
21
|
+
|
|
22
|
+
export const resource = "ticket:EXAMPLE-1";
|
|
23
|
+
|
|
24
|
+
export const expected = { status: "closed", assignee: "agent:triage" };
|
|
25
|
+
|
|
26
|
+
export default async function check({ resource: _resource, fields: _fields }) {
|
|
27
|
+
// Replace with a real read of your system, for example:
|
|
28
|
+
// const res = await fetch(`https://your-api.example/tickets/1`, { headers: { authorization: `Bearer ${readOnlyToken}` } });
|
|
29
|
+
// const ticket = await res.json();
|
|
30
|
+
// return { status: ticket.status, assignee: ticket.assignee };
|
|
31
|
+
return { status: "closed", assignee: "agent:triage" };
|
|
32
|
+
}
|
|
@@ -0,0 +1,364 @@
|
|
|
1
|
+
// External decision evidence for the local assurance sandbox (B3), VERIFIER
|
|
2
|
+
// SIDE ONLY.
|
|
3
|
+
//
|
|
4
|
+
// Ported from examples/effect-assurance-demo/src/external-decision.mjs (PR
|
|
5
|
+
// #481; docs/architecture/INTENTRAX_EXTERNAL_DECISION_EVIDENCE.md). The
|
|
6
|
+
// sandbox never issues or ingests external decisions itself: a bundle may
|
|
7
|
+
// carry them (`external_decisions`), and `sandbox verify` assesses them.
|
|
8
|
+
//
|
|
9
|
+
// A third party's signed authorization decision is EVIDENCE, never trust:
|
|
10
|
+
// - the original decision bytes are kept verbatim inside an
|
|
11
|
+
// `intentrax.external_decision_evidence/0.1` wrapper, sealed with the bundle;
|
|
12
|
+
// - the signature is checked ONLY against an issuer key set the relying party
|
|
13
|
+
// pinned out of band. This module has no network code at all: it never
|
|
14
|
+
// fetches a key set, a JWKS or a revocation list;
|
|
15
|
+
// - the result is its own optional dimension, EXTERNAL_AUTHORIZATION, with
|
|
16
|
+
// provenance THIRD_PARTY_ATTESTED. It never changes AUTHORIZATION;
|
|
17
|
+
// - the decision must bind the same tool, target, parameters digest and time
|
|
18
|
+
// window as the local decision, otherwise UNBOUND_EXTERNAL_DECISION;
|
|
19
|
+
// - an external DENY against a local ALLOW is CONTRADICTED.
|
|
20
|
+
// - the sandbox ceiling still applies: a bundle with a genuinely signed,
|
|
21
|
+
// bound, required external decision is still LOCAL_NON_TRUST_BEARING.
|
|
22
|
+
//
|
|
23
|
+
// Format profile: a generic Ed25519-over-JCS decision SHAPED LIKE an Open
|
|
24
|
+
// Agent Passport (OAP) decision, plus one profile extension (`action_binding`).
|
|
25
|
+
// Interoperability with genuine APort/OAP decisions is UNVERIFIED: this has
|
|
26
|
+
// never been run against a real signed APort decision. No APort compatibility
|
|
27
|
+
// is claimed.
|
|
28
|
+
|
|
29
|
+
import { verify as edVerify } from "node:crypto";
|
|
30
|
+
import { canonicalJson, digest, sha256Hex } from "./canonical.mjs";
|
|
31
|
+
import { publicKeyFromRaw } from "./keys.mjs";
|
|
32
|
+
import { actionDigest } from "./authority.mjs";
|
|
33
|
+
import { PROVENANCE } from "./model.mjs";
|
|
34
|
+
import { isoMs } from "./time.mjs";
|
|
35
|
+
|
|
36
|
+
export const EXTERNAL_EVIDENCE_SCHEMA = "intentrax.external_decision_evidence/0.1";
|
|
37
|
+
|
|
38
|
+
// The relying party's pinned issuer key set, as the sandbox reads it. Same
|
|
39
|
+
// document shape as the demo's `intentrax.demo.pinned_external_issuers/0.1`,
|
|
40
|
+
// under a sandbox schema id. Kept separate from the local key set: external
|
|
41
|
+
// issuers never sign Intentrax records, and local keys never sign external
|
|
42
|
+
// decisions.
|
|
43
|
+
export const ISSUER_KEY_SET_SCHEMA = "intentrax.local.sandbox_pinned_external_issuers/0.1";
|
|
44
|
+
|
|
45
|
+
// Profile id. Deliberately NOT named "oap" or "aport": it is our reading of the
|
|
46
|
+
// published shape, not a tested implementation of it.
|
|
47
|
+
export const PROFILE_ED25519_JCS_OAP_SHAPED = "intentrax.ext_profile.ed25519_jcs_oap_shaped/0.1";
|
|
48
|
+
export const SUPPORTED_PROFILES = Object.freeze([PROFILE_ED25519_JCS_OAP_SHAPED]);
|
|
49
|
+
|
|
50
|
+
export const WRAPPER_FIELDS = Object.freeze([
|
|
51
|
+
"bound_to",
|
|
52
|
+
"decision_bytes_b64",
|
|
53
|
+
"decision_digest",
|
|
54
|
+
"evidence_id",
|
|
55
|
+
"ingested_at",
|
|
56
|
+
"issuer",
|
|
57
|
+
"issuer_key_set_digest",
|
|
58
|
+
"kid",
|
|
59
|
+
"profile",
|
|
60
|
+
"schema_version",
|
|
61
|
+
]);
|
|
62
|
+
|
|
63
|
+
// Fields the profile requires in the decision object (OAP prose field list,
|
|
64
|
+
// 2026-10-12, not decision-schema.json, which cannot be satisfied as published).
|
|
65
|
+
const REQUIRED_STRINGS = ["decision_id", "policy_id", "agent_id", "owner_id", "assurance_level", "passport_digest", "kid"];
|
|
66
|
+
|
|
67
|
+
export class IssuerKeySetError extends Error {}
|
|
68
|
+
|
|
69
|
+
function isObj(v) {
|
|
70
|
+
return v !== null && typeof v === "object" && !Array.isArray(v);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
// Strict timestamps (RFC 3339 with an explicit offset): the shared parser in
|
|
74
|
+
// time.mjs, used everywhere the verifier compares a time.
|
|
75
|
+
|
|
76
|
+
// Parse a pinned issuer key set. Fails closed on anything malformed, including
|
|
77
|
+
// a missing, malformed or inverted validity window (Date.parse() of a bad
|
|
78
|
+
// value is NaN, every NaN comparison is false, and the signing-time checks
|
|
79
|
+
// would otherwise silently pass). The returned digest is what wrappers record
|
|
80
|
+
// as `issuer_key_set_digest`.
|
|
81
|
+
export function loadPinnedIssuerKeySet(doc) {
|
|
82
|
+
const fail = (msg) => {
|
|
83
|
+
throw new IssuerKeySetError("pinned issuer key set: " + msg);
|
|
84
|
+
};
|
|
85
|
+
if (!isObj(doc) || doc.schema_version !== ISSUER_KEY_SET_SCHEMA || !Array.isArray(doc.issuers)) {
|
|
86
|
+
fail("unsupported or malformed document (expected schema_version " + ISSUER_KEY_SET_SCHEMA + ")");
|
|
87
|
+
}
|
|
88
|
+
const byIssuer = new Map();
|
|
89
|
+
const kidOwner = new Map();
|
|
90
|
+
for (const entry of doc.issuers) {
|
|
91
|
+
if (!isObj(entry) || typeof entry.issuer !== "string" || !entry.issuer || byIssuer.has(entry.issuer)) {
|
|
92
|
+
fail("missing or duplicate issuer");
|
|
93
|
+
}
|
|
94
|
+
if (!SUPPORTED_PROFILES.includes(entry.profile) || !Array.isArray(entry.keys) || entry.keys.length === 0) {
|
|
95
|
+
fail("bad profile/keys for " + entry.issuer);
|
|
96
|
+
}
|
|
97
|
+
const keys = new Map();
|
|
98
|
+
for (const k of entry.keys) {
|
|
99
|
+
if (!isObj(k) || k.alg !== "Ed25519" || typeof k.kid !== "string" || !k.kid || kidOwner.has(k.kid)) {
|
|
100
|
+
fail("bad alg or duplicate kid " + (isObj(k) ? k.kid : k));
|
|
101
|
+
}
|
|
102
|
+
const from = isoMs(k.valid_from);
|
|
103
|
+
const until = isoMs(k.valid_until);
|
|
104
|
+
if (from === null || until === null || from >= until) {
|
|
105
|
+
fail("missing or invalid validity window for " + k.kid);
|
|
106
|
+
}
|
|
107
|
+
if (k.revoked_at !== undefined && isoMs(k.revoked_at) === null) {
|
|
108
|
+
fail("invalid revoked_at for " + k.kid);
|
|
109
|
+
}
|
|
110
|
+
let publicKey;
|
|
111
|
+
try {
|
|
112
|
+
publicKey = publicKeyFromRaw(k.public_key);
|
|
113
|
+
} catch {
|
|
114
|
+
fail("bad public key for " + k.kid);
|
|
115
|
+
}
|
|
116
|
+
keys.set(k.kid, Object.freeze({ ...k, publicKey }));
|
|
117
|
+
kidOwner.set(k.kid, entry.issuer);
|
|
118
|
+
}
|
|
119
|
+
byIssuer.set(entry.issuer, { profile: entry.profile, keys });
|
|
120
|
+
}
|
|
121
|
+
let setDigest;
|
|
122
|
+
try {
|
|
123
|
+
setDigest = digest(doc);
|
|
124
|
+
} catch {
|
|
125
|
+
fail("not canonicalizable");
|
|
126
|
+
}
|
|
127
|
+
return Object.freeze({ digest: setDigest, byIssuer, kidOwner });
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
// The profile's binding extension, derived from a local decision request.
|
|
131
|
+
export function actionBindingFor({ operation, resource, params }) {
|
|
132
|
+
return { tool: operation, target: resource, parameters_digest: digest(params) };
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
// Signed message: RFC 8785 JCS of the decision object WITHOUT its `signature`
|
|
136
|
+
// member. OAP says only "signature over JCS-canonicalized decision payload";
|
|
137
|
+
// which members that payload excludes is not specified (UNVERIFIED).
|
|
138
|
+
export function externalSigningBytes(decisionWithoutSignature) {
|
|
139
|
+
return Buffer.from(canonicalJson(decisionWithoutSignature), "utf8");
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function decodeBytes(wrapper) {
|
|
143
|
+
const s = wrapper.decision_bytes_b64;
|
|
144
|
+
if (typeof s !== "string") return null;
|
|
145
|
+
const bytes = Buffer.from(s, "base64");
|
|
146
|
+
return bytes.toString("base64") === s ? bytes : null;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
// Record-integrity checks on the wrapper (shape, digest of the carried bytes,
|
|
150
|
+
// and that the wrapper names THIS local decision). Returns reason codes.
|
|
151
|
+
export function wrapperIntegrityReasons(wrapper, d, i) {
|
|
152
|
+
const where = ":" + i;
|
|
153
|
+
if (!isObj(wrapper) || Object.keys(wrapper).sort().join(",") !== WRAPPER_FIELDS.join(",")
|
|
154
|
+
|| wrapper.schema_version !== EXTERNAL_EVIDENCE_SCHEMA || !isObj(wrapper.bound_to)) {
|
|
155
|
+
return ["EXTERNAL_EVIDENCE_MALFORMED" + where];
|
|
156
|
+
}
|
|
157
|
+
const reasons = [];
|
|
158
|
+
const bytes = decodeBytes(wrapper);
|
|
159
|
+
if (!bytes || "sha256:" + sha256Hex(bytes) !== wrapper.decision_digest) {
|
|
160
|
+
reasons.push("EXTERNAL_DECISION_DIGEST_MISMATCH" + where);
|
|
161
|
+
}
|
|
162
|
+
if (wrapper.bound_to.intentrax_decision_id !== d.decision_id || wrapper.bound_to.action_digest !== actionDigest(d.request)) {
|
|
163
|
+
reasons.push("EXTERNAL_EVIDENCE_BINDING_MISMATCH" + where);
|
|
164
|
+
}
|
|
165
|
+
return reasons;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
// ---- verification ---------------------------------------------------------
|
|
169
|
+
|
|
170
|
+
export const EXTERNAL_LIMITATION_TEXT = Object.freeze({
|
|
171
|
+
EXTERNAL_ISSUER_POLICY_UNKNOWN:
|
|
172
|
+
"Intentrax cannot re-evaluate the external issuer's policy; the decision shows what the issuer concluded, not that it was right.",
|
|
173
|
+
EXTERNAL_ISSUER_REVOCATION_NOT_REQUERIED:
|
|
174
|
+
"Passport or key suspension/revocation after issuance is not re-queried offline; only the pinned key set's validity window is applied.",
|
|
175
|
+
EXTERNAL_AGENT_IDENTITY_NOT_MAPPED:
|
|
176
|
+
"The issuer's agent_id/owner_id are not mapped to the sandbox agent; the binding covers tool, target, parameters and time only.",
|
|
177
|
+
EXTERNAL_PROFILE_INTEROP_UNVERIFIED:
|
|
178
|
+
"The OAP-shaped profile follows the published OAP text; it has not been tested against a genuine signed APort decision. No APort compatibility is claimed.",
|
|
179
|
+
EXTERNAL_SIGNING_TIME_SELF_ASSERTED:
|
|
180
|
+
"The external decision's created_at is asserted by its issuer; key validity and expiry are judged against it.",
|
|
181
|
+
ISSUER_KEY_SET_CHANGED_SINCE_INGESTION:
|
|
182
|
+
"The relying party's pinned issuer key set differs from the one recorded at ingestion; the verifier used its own pinned set.",
|
|
183
|
+
});
|
|
184
|
+
|
|
185
|
+
const BASE_LIMITATIONS = [
|
|
186
|
+
"EXTERNAL_ISSUER_POLICY_UNKNOWN",
|
|
187
|
+
"EXTERNAL_ISSUER_REVOCATION_NOT_REQUERIED",
|
|
188
|
+
"EXTERNAL_AGENT_IDENTITY_NOT_MAPPED",
|
|
189
|
+
"EXTERNAL_PROFILE_INTEROP_UNVERIFIED",
|
|
190
|
+
"EXTERNAL_SIGNING_TIME_SELF_ASSERTED",
|
|
191
|
+
];
|
|
192
|
+
|
|
193
|
+
const SIG_RE = /^ed25519:[A-Za-z0-9+/]+={0,2}$/;
|
|
194
|
+
|
|
195
|
+
// Assess one wrapped decision. Never throws.
|
|
196
|
+
// ctx: { d (local decision payload), reports, effectConfirmed, issuerKeys }
|
|
197
|
+
function assessOne(wrapper, ctx) {
|
|
198
|
+
const { d, reports, effectConfirmed, issuerKeys } = ctx;
|
|
199
|
+
const out = {
|
|
200
|
+
evidence_id: wrapper.evidence_id,
|
|
201
|
+
issuer: wrapper.issuer,
|
|
202
|
+
kid: wrapper.kid,
|
|
203
|
+
profile: wrapper.profile,
|
|
204
|
+
result: "INSUFFICIENT_EVIDENCE",
|
|
205
|
+
reasons: [],
|
|
206
|
+
signature: "NOT_CHECKED",
|
|
207
|
+
bound: null,
|
|
208
|
+
outcome: null,
|
|
209
|
+
created_at: null,
|
|
210
|
+
expires_at: null,
|
|
211
|
+
key_set_digest_matches: issuerKeys ? wrapper.issuer_key_set_digest === issuerKeys.digest : null,
|
|
212
|
+
};
|
|
213
|
+
const done = (result, ...reasons) => {
|
|
214
|
+
out.result = result;
|
|
215
|
+
out.reasons.push(...reasons);
|
|
216
|
+
return out;
|
|
217
|
+
};
|
|
218
|
+
|
|
219
|
+
if (!SUPPORTED_PROFILES.includes(wrapper.profile)) return done("INSUFFICIENT_EVIDENCE", "UNSUPPORTED_EXTERNAL_PROFILE");
|
|
220
|
+
let decision;
|
|
221
|
+
try {
|
|
222
|
+
decision = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(decodeBytes(wrapper)));
|
|
223
|
+
} catch {
|
|
224
|
+
return done("FAILED", "EXTERNAL_DECISION_MALFORMED");
|
|
225
|
+
}
|
|
226
|
+
if (!isObj(decision)) return done("FAILED", "EXTERNAL_DECISION_MALFORMED");
|
|
227
|
+
if (decision.kid !== wrapper.kid) return done("FAILED", "EXTERNAL_KID_MISMATCH");
|
|
228
|
+
|
|
229
|
+
// -- signature, against the pinned issuer key set only --
|
|
230
|
+
if (!issuerKeys) return done("NOT_ASSESSED", "NO_PINNED_ISSUER_KEY_SET");
|
|
231
|
+
const owner = issuerKeys.kidOwner.get(wrapper.kid);
|
|
232
|
+
if (owner === undefined) return done("INSUFFICIENT_EVIDENCE", "EXTERNAL_ISSUER_KEY_NOT_PINNED");
|
|
233
|
+
if (owner !== wrapper.issuer) return done("INSUFFICIENT_EVIDENCE", "KID_PINNED_FOR_DIFFERENT_ISSUER");
|
|
234
|
+
const pinnedIssuer = issuerKeys.byIssuer.get(owner);
|
|
235
|
+
if (pinnedIssuer.profile !== wrapper.profile) return done("INSUFFICIENT_EVIDENCE", "PROFILE_NOT_PINNED_FOR_ISSUER");
|
|
236
|
+
const key = pinnedIssuer.keys.get(wrapper.kid);
|
|
237
|
+
const { signature, ...unsigned } = decision;
|
|
238
|
+
if (typeof signature !== "string" || !SIG_RE.test(signature)) return done("FAILED", "EXTERNAL_SIGNATURE_MALFORMED");
|
|
239
|
+
const sig = Buffer.from(signature.slice("ed25519:".length), "base64");
|
|
240
|
+
let message;
|
|
241
|
+
try {
|
|
242
|
+
message = externalSigningBytes(unsigned);
|
|
243
|
+
} catch {
|
|
244
|
+
// The sandbox's JCS covers integers only; a decision with other numbers
|
|
245
|
+
// cannot be checked here (RFC 8785 number serialization not implemented).
|
|
246
|
+
return done("INSUFFICIENT_EVIDENCE", "EXTERNAL_DECISION_NOT_CANONICALIZABLE");
|
|
247
|
+
}
|
|
248
|
+
let valid = false;
|
|
249
|
+
try {
|
|
250
|
+
valid = sig.length === 64 && edVerify(null, message, key.publicKey, sig);
|
|
251
|
+
} catch {
|
|
252
|
+
valid = false;
|
|
253
|
+
}
|
|
254
|
+
if (!valid) {
|
|
255
|
+
out.signature = "INVALID";
|
|
256
|
+
return done("FAILED", "EXTERNAL_SIGNATURE_INVALID_FOR_PINNED_KEY");
|
|
257
|
+
}
|
|
258
|
+
out.signature = "VALID_PINNED_KEY";
|
|
259
|
+
|
|
260
|
+
// -- shape (profile) --
|
|
261
|
+
const bad = REQUIRED_STRINGS.filter((f) => typeof decision[f] !== "string");
|
|
262
|
+
if (typeof decision.allow !== "boolean") bad.push("allow");
|
|
263
|
+
if (!Array.isArray(decision.reasons) || !decision.reasons.length || !decision.reasons.every((r) => isObj(r) && typeof r.code === "string")) {
|
|
264
|
+
bad.push("reasons");
|
|
265
|
+
}
|
|
266
|
+
const created = isoMs(decision.created_at);
|
|
267
|
+
if (created === null) bad.push("created_at");
|
|
268
|
+
if (!Number.isSafeInteger(decision.expires_in) || decision.expires_in < 0) bad.push("expires_in");
|
|
269
|
+
if (bad.length) return done("INSUFFICIENT_EVIDENCE", ...bad.map((f) => "EXTERNAL_DECISION_SHAPE_INVALID:" + f));
|
|
270
|
+
out.outcome = decision.allow ? "ALLOW" : "DENY";
|
|
271
|
+
out.created_at = decision.created_at;
|
|
272
|
+
const expires = created + decision.expires_in * 1000;
|
|
273
|
+
out.expires_at = new Date(expires).toISOString().replace(/\.\d{3}Z$/, "Z");
|
|
274
|
+
|
|
275
|
+
// -- key validity at the (self-asserted) signing time --
|
|
276
|
+
if (created < isoMs(key.valid_from) || created >= isoMs(key.valid_until)) {
|
|
277
|
+
return done("INSUFFICIENT_EVIDENCE", "EXTERNAL_KEY_NOT_VALID_AT_SIGNING_TIME");
|
|
278
|
+
}
|
|
279
|
+
if (key.revoked_at !== undefined && created >= isoMs(key.revoked_at)) {
|
|
280
|
+
return done("INSUFFICIENT_EVIDENCE", "EXTERNAL_KEY_REVOKED_AT_SIGNING_TIME");
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
// -- binding: same tool, target, parameters digest, time window --
|
|
284
|
+
const unbound = [];
|
|
285
|
+
const b = decision.action_binding;
|
|
286
|
+
if (!isObj(b)) {
|
|
287
|
+
unbound.push("UNBOUND_EXTERNAL_DECISION:NO_ACTION_BINDING");
|
|
288
|
+
} else {
|
|
289
|
+
if (b.tool !== d.request.operation) unbound.push("UNBOUND_EXTERNAL_DECISION:tool");
|
|
290
|
+
if (b.target !== d.request.resource) unbound.push("UNBOUND_EXTERNAL_DECISION:target");
|
|
291
|
+
if (b.parameters_digest !== digest(d.request.params)) unbound.push("UNBOUND_EXTERNAL_DECISION:parameters_digest");
|
|
292
|
+
}
|
|
293
|
+
// The action happens at the first execution start, or (no execution) at the
|
|
294
|
+
// local decision. The external decision must precede it...
|
|
295
|
+
// Strict (explicit offset), and no `??` fallback: a report whose
|
|
296
|
+
// started_at is missing or unparseable fails closed instead of silently
|
|
297
|
+
// using the decision time (demo #490/#491 parity).
|
|
298
|
+
const actionAt = isoMs(reports.length ? reports[0].started_at : d.decided_at);
|
|
299
|
+
if (actionAt === null || created > actionAt) unbound.push("UNBOUND_EXTERNAL_DECISION:issued_after_action");
|
|
300
|
+
out.bound = unbound.length === 0;
|
|
301
|
+
if (unbound.length) return done("INSUFFICIENT_EVIDENCE", ...unbound);
|
|
302
|
+
// ...and still be in force when it happens.
|
|
303
|
+
if (actionAt >= expires) return done("INSUFFICIENT_EVIDENCE", "EXTERNAL_DECISION_EXPIRED");
|
|
304
|
+
|
|
305
|
+
// -- conflict rules --
|
|
306
|
+
if (out.outcome === "DENY" && d.outcome === "ALLOW") {
|
|
307
|
+
return done("CONTRADICTED", "EXTERNAL_DENY_INTENTRAX_ALLOW",
|
|
308
|
+
...(reports.length ? ["EXECUTED_DESPITE_EXTERNAL_DENY"] : []));
|
|
309
|
+
}
|
|
310
|
+
// Informational cross-checks: the external decision is genuine and bound,
|
|
311
|
+
// so the dimension stays VERIFIED, but the report says what happened next.
|
|
312
|
+
if (out.outcome === "ALLOW" && d.outcome === "DENY") out.reasons.push("EXTERNAL_ALLOW_INTENTRAX_DENY");
|
|
313
|
+
if (out.outcome === "ALLOW" && effectConfirmed === "CONTRADICTED") out.reasons.push("EXTERNAL_ALLOW_BUT_EFFECT_CONTRADICTED");
|
|
314
|
+
out.result = "VERIFIED";
|
|
315
|
+
return out;
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
// Assess every wrapped decision and aggregate into one EXTERNAL_AUTHORIZATION
|
|
319
|
+
// assessment body: { result, provenance, reasons, limitations, evidence_digests, detail }.
|
|
320
|
+
// authorizationIssuers: issuers the relying party's assurance profile names.
|
|
321
|
+
// Empty = EXTERNAL_AUTHORIZATION is informational (non-required) and any
|
|
322
|
+
// pinned issuer's VERIFIED decision counts as VERIFIED.
|
|
323
|
+
export function assessExternalAuthorization({
|
|
324
|
+
wrappers, d, reports, effectConfirmed, issuerKeys, authorizationIssuers = [],
|
|
325
|
+
}) {
|
|
326
|
+
const per = wrappers.map((w) => assessOne(w, { d, reports, effectConfirmed, issuerKeys }));
|
|
327
|
+
const limitations = [...BASE_LIMITATIONS];
|
|
328
|
+
if (per.some((p) => p.key_set_digest_matches === false)) limitations.push("ISSUER_KEY_SET_CHANGED_SINCE_INGESTION");
|
|
329
|
+
const reasons = [...new Set(per.flatMap((p) => p.reasons))];
|
|
330
|
+
const results = per.map((p) => p.result);
|
|
331
|
+
let result;
|
|
332
|
+
if (!per.length) {
|
|
333
|
+
result = "INSUFFICIENT_EVIDENCE";
|
|
334
|
+
reasons.push("NO_EXTERNAL_DECISION_IN_BUNDLE");
|
|
335
|
+
} else if (results.includes("FAILED")) {
|
|
336
|
+
result = "FAILED";
|
|
337
|
+
} else if (results.includes("CONTRADICTED")) {
|
|
338
|
+
result = "CONTRADICTED";
|
|
339
|
+
} else {
|
|
340
|
+
const eligible = per.filter((p) => p.result === "VERIFIED"
|
|
341
|
+
&& (!authorizationIssuers.length || authorizationIssuers.includes(p.issuer)));
|
|
342
|
+
if (eligible.length) {
|
|
343
|
+
result = "VERIFIED";
|
|
344
|
+
} else if (results.includes("VERIFIED")) {
|
|
345
|
+
result = "INSUFFICIENT_EVIDENCE";
|
|
346
|
+
reasons.push("EXTERNAL_ISSUER_NOT_NAMED_BY_PROFILE");
|
|
347
|
+
} else {
|
|
348
|
+
result = results.every((r) => r === "NOT_ASSESSED") ? "NOT_ASSESSED" : "INSUFFICIENT_EVIDENCE";
|
|
349
|
+
}
|
|
350
|
+
}
|
|
351
|
+
return {
|
|
352
|
+
result,
|
|
353
|
+
provenance: PROVENANCE.THIRD_PARTY_ATTESTED,
|
|
354
|
+
reasons,
|
|
355
|
+
limitations,
|
|
356
|
+
evidence_digests: wrappers.map((w) => w.decision_digest),
|
|
357
|
+
detail: {
|
|
358
|
+
substitutes_for_authorization: false,
|
|
359
|
+
profile_names_issuers: authorizationIssuers,
|
|
360
|
+
pinned_issuer_key_set_digest: issuerKeys ? issuerKeys.digest : null,
|
|
361
|
+
decisions: per,
|
|
362
|
+
},
|
|
363
|
+
};
|
|
364
|
+
}
|