@redditech/agent-protocol 0.0.0-stage → 0.2.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/CHANGELOG.md +89 -0
- package/LICENSE +21 -0
- package/README.md +394 -2
- package/dist/adl.d.ts +141 -0
- package/dist/adl.js +3601 -0
- package/dist/agent-stack-fixtures.d.ts +743 -0
- package/dist/agent-stack-fixtures.js +1554 -0
- package/dist/ai-catalog.d.ts +128 -0
- package/dist/ai-catalog.js +373 -0
- package/dist/attestation-reputation.d.ts +102 -0
- package/dist/attestation-reputation.js +279 -0
- package/dist/audd-rail-config.d.ts +102 -0
- package/dist/audd-rail-config.js +294 -0
- package/dist/browser-wallet-approval.d.ts +293 -0
- package/dist/browser-wallet-approval.js +1201 -0
- package/dist/discovery-source.d.ts +115 -0
- package/dist/discovery-source.js +251 -0
- package/dist/evidence-archive.d.ts +73 -0
- package/dist/evidence-archive.js +238 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.js +23 -0
- package/dist/mpp-tempo-receipt-shapes.d.ts +201 -0
- package/dist/mpp-tempo-receipt-shapes.js +330 -0
- package/dist/okf-adapter.d.ts +229 -0
- package/dist/okf-adapter.js +556 -0
- package/dist/okf-conformance.d.ts +208 -0
- package/dist/okf-conformance.js +651 -0
- package/dist/okf-instruction-safety.d.ts +192 -0
- package/dist/okf-instruction-safety.js +509 -0
- package/dist/onboarding-analyser-handoff.d.ts +391 -0
- package/dist/onboarding-analyser-handoff.js +959 -0
- package/dist/onboarding-state-machine.d.ts +228 -0
- package/dist/onboarding-state-machine.js +432 -0
- package/dist/payment-records.d.ts +181 -0
- package/dist/payment-records.js +599 -0
- package/dist/policy.d.ts +33 -0
- package/dist/policy.js +45 -0
- package/dist/provider-trust.d.ts +113 -0
- package/dist/provider-trust.js +346 -0
- package/dist/quasar-registry-compatibility.d.ts +113 -0
- package/dist/quasar-registry-compatibility.js +214 -0
- package/dist/ranking-explainability.d.ts +202 -0
- package/dist/ranking-explainability.js +302 -0
- package/dist/receipt-v2.d.ts +202 -0
- package/dist/receipt-v2.js +418 -0
- package/dist/repo-explorer-evidence-manifest.d.ts +387 -0
- package/dist/repo-explorer-evidence-manifest.js +1187 -0
- package/dist/source-diagnostics.d.ts +84 -0
- package/dist/source-diagnostics.js +193 -0
- package/dist/source-trust-conformance-matrix.d.ts +207 -0
- package/dist/source-trust-conformance-matrix.js +672 -0
- package/examples/ard-no-spend-ai-catalog.json +51 -0
- package/examples/ard-no-spend-demo.mjs +355 -0
- package/examples/interpretation-guide-scenarios.mjs +302 -0
- package/package.json +144 -4
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
import { type AiCatalogSnapshot } from './ai-catalog.js';
|
|
2
|
+
import { type NormalizeAiCatalogTrustOptions, type ProviderTrustRecord, type ProviderTrustVerificationStatus } from './provider-trust.js';
|
|
3
|
+
export declare const DISCOVERY_CANDIDATE_SCHEMA_VERSION: "reddi.discovery-candidate.v1";
|
|
4
|
+
export type DiscoverySourceKind = 'local-specialist' | 'direct-ai-catalog' | 'ard-registry' | 'source-adapter' | 'hosted-rap-registry';
|
|
5
|
+
export type DiscoveryCandidateReasonCode = 'candidate_ready_for_policy_preflight' | 'malformed_candidate' | 'provider_trust_mismatch' | 'missing_quote' | 'source_not_allowed' | 'trust_verification_required' | 'unsupported_asset' | 'unsupported_network' | 'over_budget';
|
|
6
|
+
export type DiscoveryCandidateDiagnostic = {
|
|
7
|
+
code: DiscoveryCandidateReasonCode;
|
|
8
|
+
path: string;
|
|
9
|
+
message: string;
|
|
10
|
+
};
|
|
11
|
+
export type DiscoveryCandidateQuote = {
|
|
12
|
+
amount: string;
|
|
13
|
+
asset: string;
|
|
14
|
+
network: string;
|
|
15
|
+
expiresAt?: string;
|
|
16
|
+
payee?: string;
|
|
17
|
+
};
|
|
18
|
+
export type DiscoveryCandidate = {
|
|
19
|
+
schemaVersion: typeof DISCOVERY_CANDIDATE_SCHEMA_VERSION;
|
|
20
|
+
sourceKind: DiscoverySourceKind;
|
|
21
|
+
identifier: string;
|
|
22
|
+
publisher?: {
|
|
23
|
+
id: string;
|
|
24
|
+
name?: string;
|
|
25
|
+
domain?: string;
|
|
26
|
+
};
|
|
27
|
+
name: string;
|
|
28
|
+
description?: string;
|
|
29
|
+
resourceType: string;
|
|
30
|
+
mediaType: string;
|
|
31
|
+
url?: string;
|
|
32
|
+
endpoint?: string;
|
|
33
|
+
trustMetadata?: ProviderTrustRecord['trustMetadata'];
|
|
34
|
+
providerTrust?: ProviderTrustRecord;
|
|
35
|
+
relevance?: {
|
|
36
|
+
score?: number;
|
|
37
|
+
reason?: string;
|
|
38
|
+
source?: string;
|
|
39
|
+
};
|
|
40
|
+
rawSnapshotRef?: string;
|
|
41
|
+
quote?: DiscoveryCandidateQuote;
|
|
42
|
+
policyPreflightRequired: true;
|
|
43
|
+
};
|
|
44
|
+
export type DiscoveryCandidateNormalizationResult = {
|
|
45
|
+
ok: true;
|
|
46
|
+
candidates: DiscoveryCandidate[];
|
|
47
|
+
diagnostics: DiscoveryCandidateDiagnostic[];
|
|
48
|
+
} | {
|
|
49
|
+
ok: false;
|
|
50
|
+
errors: DiscoveryCandidateDiagnostic[];
|
|
51
|
+
};
|
|
52
|
+
export type DiscoveryCandidateValidationResult = {
|
|
53
|
+
ok: true;
|
|
54
|
+
candidate: DiscoveryCandidate;
|
|
55
|
+
diagnostics: DiscoveryCandidateDiagnostic[];
|
|
56
|
+
} | {
|
|
57
|
+
ok: false;
|
|
58
|
+
errors: DiscoveryCandidateDiagnostic[];
|
|
59
|
+
};
|
|
60
|
+
export type CreateAiCatalogDiscoveryCandidatesOptions = {
|
|
61
|
+
sourceKind?: Extract<DiscoverySourceKind, 'direct-ai-catalog' | 'ard-registry' | 'hosted-rap-registry'>;
|
|
62
|
+
trustOptionsByResourceId?: Record<string, NormalizeAiCatalogTrustOptions>;
|
|
63
|
+
relevanceScores?: Record<string, number>;
|
|
64
|
+
};
|
|
65
|
+
export type DiscoveryCandidatePolicy = {
|
|
66
|
+
allowedSourceKinds?: DiscoverySourceKind[];
|
|
67
|
+
requireVerifiedTrust?: boolean;
|
|
68
|
+
allowedAssets?: string[];
|
|
69
|
+
allowedNetworks?: string[];
|
|
70
|
+
maxQuote?: {
|
|
71
|
+
amount: string;
|
|
72
|
+
asset: string;
|
|
73
|
+
network: string;
|
|
74
|
+
};
|
|
75
|
+
};
|
|
76
|
+
export type DiscoveryCandidatePolicyPreflightDecision = {
|
|
77
|
+
allowed: boolean;
|
|
78
|
+
reasonCodes: DiscoveryCandidateReasonCode[];
|
|
79
|
+
auditNotes: string[];
|
|
80
|
+
candidate: {
|
|
81
|
+
identifier: string;
|
|
82
|
+
sourceKind: DiscoverySourceKind;
|
|
83
|
+
relevanceScore?: number;
|
|
84
|
+
trustStatus?: ProviderTrustVerificationStatus;
|
|
85
|
+
};
|
|
86
|
+
quote?: DiscoveryCandidateQuote;
|
|
87
|
+
};
|
|
88
|
+
export declare function validateDiscoveryCandidate(input: unknown): DiscoveryCandidateValidationResult;
|
|
89
|
+
export declare function createAiCatalogDiscoveryCandidates(catalog: AiCatalogSnapshot, options?: CreateAiCatalogDiscoveryCandidatesOptions): DiscoveryCandidateNormalizationResult;
|
|
90
|
+
export declare function evaluateDiscoveryCandidatePolicyPreflight(candidate: DiscoveryCandidate, policy: DiscoveryCandidatePolicy): DiscoveryCandidatePolicyPreflightDecision;
|
|
91
|
+
export declare const discoverySourceFixtures: {
|
|
92
|
+
readonly localSpecialistCandidate: {
|
|
93
|
+
readonly schemaVersion: "reddi.discovery-candidate.v1";
|
|
94
|
+
readonly sourceKind: "local-specialist";
|
|
95
|
+
readonly identifier: "urn:ai:local:specialists:lint";
|
|
96
|
+
readonly publisher: {
|
|
97
|
+
readonly id: "local";
|
|
98
|
+
};
|
|
99
|
+
readonly name: "Local Lint Specialist";
|
|
100
|
+
readonly resourceType: "application/mcp-server-card+json";
|
|
101
|
+
readonly mediaType: "application/mcp-server-card+json";
|
|
102
|
+
readonly endpoint: "http://localhost:4100/mcp";
|
|
103
|
+
readonly relevance: {
|
|
104
|
+
readonly score: 0.4;
|
|
105
|
+
readonly source: "local-fixture";
|
|
106
|
+
};
|
|
107
|
+
readonly rawSnapshotRef: "sha256:local-specialist-fixture";
|
|
108
|
+
readonly quote: {
|
|
109
|
+
readonly amount: "1000";
|
|
110
|
+
readonly asset: "AUDD";
|
|
111
|
+
readonly network: "solana-devnet";
|
|
112
|
+
};
|
|
113
|
+
readonly policyPreflightRequired: true;
|
|
114
|
+
};
|
|
115
|
+
};
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
import { normalizeAiCatalogProviderTrustRecord, } from './provider-trust.js';
|
|
2
|
+
export const DISCOVERY_CANDIDATE_SCHEMA_VERSION = 'reddi.discovery-candidate.v1';
|
|
3
|
+
const SOURCE_KINDS = new Set([
|
|
4
|
+
'local-specialist',
|
|
5
|
+
'direct-ai-catalog',
|
|
6
|
+
'ard-registry',
|
|
7
|
+
'source-adapter',
|
|
8
|
+
'hosted-rap-registry',
|
|
9
|
+
]);
|
|
10
|
+
function diagnostic(code, path, message) {
|
|
11
|
+
return { code, path, message };
|
|
12
|
+
}
|
|
13
|
+
function isPlainObject(value) {
|
|
14
|
+
if (value === null || typeof value !== 'object' || Array.isArray(value))
|
|
15
|
+
return false;
|
|
16
|
+
const prototype = Object.getPrototypeOf(value);
|
|
17
|
+
return prototype === Object.prototype || prototype === null;
|
|
18
|
+
}
|
|
19
|
+
function asString(value) {
|
|
20
|
+
return typeof value === 'string' && value.trim() ? value.trim() : undefined;
|
|
21
|
+
}
|
|
22
|
+
function asDiscoverySourceKind(value) {
|
|
23
|
+
return typeof value === 'string' && SOURCE_KINDS.has(value)
|
|
24
|
+
? value
|
|
25
|
+
: undefined;
|
|
26
|
+
}
|
|
27
|
+
function amountToBigInt(value) {
|
|
28
|
+
if (typeof value !== 'string')
|
|
29
|
+
return undefined;
|
|
30
|
+
if (!/^[0-9]+$/.test(value))
|
|
31
|
+
return undefined;
|
|
32
|
+
return BigInt(value);
|
|
33
|
+
}
|
|
34
|
+
function resourceReference(resource) {
|
|
35
|
+
return {
|
|
36
|
+
url: resource.url ?? resource.catalogUrl,
|
|
37
|
+
endpoint: resource.endpoint,
|
|
38
|
+
};
|
|
39
|
+
}
|
|
40
|
+
export function validateDiscoveryCandidate(input) {
|
|
41
|
+
const errors = [];
|
|
42
|
+
if (!isPlainObject(input)) {
|
|
43
|
+
return { ok: false, errors: [diagnostic('malformed_candidate', '$', 'Discovery candidate must be a plain object.')] };
|
|
44
|
+
}
|
|
45
|
+
const sourceKind = asDiscoverySourceKind(input.sourceKind);
|
|
46
|
+
if (!sourceKind) {
|
|
47
|
+
errors.push(diagnostic('malformed_candidate', '$.sourceKind', 'Discovery candidate must include a supported sourceKind.'));
|
|
48
|
+
}
|
|
49
|
+
const identifier = asString(input.identifier);
|
|
50
|
+
if (!identifier) {
|
|
51
|
+
errors.push(diagnostic('malformed_candidate', '$.identifier', 'Discovery candidate must include an identifier.'));
|
|
52
|
+
}
|
|
53
|
+
const name = asString(input.name);
|
|
54
|
+
if (!name) {
|
|
55
|
+
errors.push(diagnostic('malformed_candidate', '$.name', 'Discovery candidate must include a name.'));
|
|
56
|
+
}
|
|
57
|
+
const resourceType = asString(input.resourceType);
|
|
58
|
+
const mediaType = asString(input.mediaType);
|
|
59
|
+
if (!resourceType || !mediaType) {
|
|
60
|
+
errors.push(diagnostic('malformed_candidate', '$.mediaType', 'Discovery candidate must include resourceType and mediaType.'));
|
|
61
|
+
}
|
|
62
|
+
const relevance = isPlainObject(input.relevance) ? input.relevance : undefined;
|
|
63
|
+
const relevanceScore = relevance?.score;
|
|
64
|
+
if (relevanceScore !== undefined && (typeof relevanceScore !== 'number' || !Number.isFinite(relevanceScore) || relevanceScore < 0 || relevanceScore > 1)) {
|
|
65
|
+
errors.push(diagnostic('malformed_candidate', '$.relevance.score', 'Relevance score must be a finite number between 0 and 1.'));
|
|
66
|
+
}
|
|
67
|
+
const providerTrust = input.providerTrust;
|
|
68
|
+
if (providerTrust !== undefined) {
|
|
69
|
+
if (!isPlainObject(providerTrust) || providerTrust.schemaVersion !== 'reddi.provider-trust.v1') {
|
|
70
|
+
errors.push(diagnostic('malformed_candidate', '$.providerTrust', 'Provider trust must be a reddi.provider-trust.v1 record.'));
|
|
71
|
+
}
|
|
72
|
+
else if (!isPlainObject(providerTrust.provider) || !asString(providerTrust.provider.id)) {
|
|
73
|
+
errors.push(diagnostic('malformed_candidate', '$.providerTrust.provider.id', 'Provider trust record must include a provider id.'));
|
|
74
|
+
}
|
|
75
|
+
else if (identifier && providerTrust.provider.id !== identifier) {
|
|
76
|
+
errors.push(diagnostic('provider_trust_mismatch', '$.providerTrust.provider.id', 'Provider trust record must match the discovery candidate identifier.'));
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
const quote = input.quote;
|
|
80
|
+
if (quote !== undefined) {
|
|
81
|
+
if (!isPlainObject(quote)) {
|
|
82
|
+
errors.push(diagnostic('malformed_candidate', '$.quote', 'Discovery candidate quote must be an object.'));
|
|
83
|
+
}
|
|
84
|
+
else if (!asString(quote.amount) || amountToBigInt(asString(quote.amount)) === undefined || !asString(quote.asset) || !asString(quote.network)) {
|
|
85
|
+
errors.push(diagnostic('malformed_candidate', '$.quote', 'Discovery candidate quote must include decimal amount, asset, and network.'));
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
if (errors.length > 0)
|
|
89
|
+
return { ok: false, errors };
|
|
90
|
+
return {
|
|
91
|
+
ok: true,
|
|
92
|
+
candidate: {
|
|
93
|
+
schemaVersion: DISCOVERY_CANDIDATE_SCHEMA_VERSION,
|
|
94
|
+
sourceKind: sourceKind,
|
|
95
|
+
identifier: identifier,
|
|
96
|
+
publisher: isPlainObject(input.publisher)
|
|
97
|
+
? {
|
|
98
|
+
id: asString(input.publisher.id) ?? 'unknown',
|
|
99
|
+
name: asString(input.publisher.name),
|
|
100
|
+
domain: asString(input.publisher.domain),
|
|
101
|
+
}
|
|
102
|
+
: undefined,
|
|
103
|
+
name: name,
|
|
104
|
+
description: asString(input.description),
|
|
105
|
+
resourceType: resourceType,
|
|
106
|
+
mediaType: mediaType,
|
|
107
|
+
url: asString(input.url),
|
|
108
|
+
endpoint: asString(input.endpoint),
|
|
109
|
+
trustMetadata: providerTrust?.trustMetadata ?? input.trustMetadata,
|
|
110
|
+
providerTrust,
|
|
111
|
+
relevance: relevance
|
|
112
|
+
? {
|
|
113
|
+
score: relevanceScore,
|
|
114
|
+
reason: asString(relevance.reason),
|
|
115
|
+
source: asString(relevance.source),
|
|
116
|
+
}
|
|
117
|
+
: undefined,
|
|
118
|
+
rawSnapshotRef: asString(input.rawSnapshotRef),
|
|
119
|
+
quote: isPlainObject(input.quote)
|
|
120
|
+
? {
|
|
121
|
+
amount: asString(input.quote.amount) ?? '',
|
|
122
|
+
asset: asString(input.quote.asset) ?? '',
|
|
123
|
+
network: asString(input.quote.network) ?? '',
|
|
124
|
+
expiresAt: asString(input.quote.expiresAt),
|
|
125
|
+
payee: asString(input.quote.payee),
|
|
126
|
+
}
|
|
127
|
+
: undefined,
|
|
128
|
+
policyPreflightRequired: true,
|
|
129
|
+
},
|
|
130
|
+
diagnostics: [diagnostic('candidate_ready_for_policy_preflight', '$', 'Discovery candidate is normalized for explicit RAP policy preflight.')],
|
|
131
|
+
};
|
|
132
|
+
}
|
|
133
|
+
export function createAiCatalogDiscoveryCandidates(catalog, options = {}) {
|
|
134
|
+
const sourceKind = options.sourceKind ?? 'direct-ai-catalog';
|
|
135
|
+
const candidates = [];
|
|
136
|
+
const errors = [];
|
|
137
|
+
for (const resource of catalog.resources) {
|
|
138
|
+
const trust = normalizeAiCatalogProviderTrustRecord(catalog, resource.id, options.trustOptionsByResourceId?.[resource.id]);
|
|
139
|
+
if (!trust.ok) {
|
|
140
|
+
for (const trustError of trust.errors) {
|
|
141
|
+
errors.push(diagnostic('malformed_candidate', `$.resources[${resource.id}]${trustError.path}`, trustError.message));
|
|
142
|
+
}
|
|
143
|
+
continue;
|
|
144
|
+
}
|
|
145
|
+
const reference = resourceReference(resource);
|
|
146
|
+
const validation = validateDiscoveryCandidate({
|
|
147
|
+
schemaVersion: DISCOVERY_CANDIDATE_SCHEMA_VERSION,
|
|
148
|
+
sourceKind,
|
|
149
|
+
identifier: resource.id,
|
|
150
|
+
publisher: catalog.publisher,
|
|
151
|
+
name: resource.name,
|
|
152
|
+
description: resource.description,
|
|
153
|
+
resourceType: resource.type,
|
|
154
|
+
mediaType: resource.mediaType,
|
|
155
|
+
url: reference.url,
|
|
156
|
+
endpoint: reference.endpoint,
|
|
157
|
+
providerTrust: trust.record,
|
|
158
|
+
trustMetadata: trust.record.trustMetadata,
|
|
159
|
+
relevance: {
|
|
160
|
+
score: options.relevanceScores?.[resource.id],
|
|
161
|
+
source: sourceKind,
|
|
162
|
+
},
|
|
163
|
+
rawSnapshotRef: catalog.rawSnapshotRef,
|
|
164
|
+
policyPreflightRequired: true,
|
|
165
|
+
});
|
|
166
|
+
if (validation.ok)
|
|
167
|
+
candidates.push(validation.candidate);
|
|
168
|
+
else
|
|
169
|
+
errors.push(...validation.errors);
|
|
170
|
+
}
|
|
171
|
+
if (errors.length > 0)
|
|
172
|
+
return { ok: false, errors };
|
|
173
|
+
return {
|
|
174
|
+
ok: true,
|
|
175
|
+
candidates,
|
|
176
|
+
diagnostics: [diagnostic('candidate_ready_for_policy_preflight', '$', 'Discovery candidates require explicit policy preflight before quote/payment/invocation.')],
|
|
177
|
+
};
|
|
178
|
+
}
|
|
179
|
+
export function evaluateDiscoveryCandidatePolicyPreflight(candidate, policy) {
|
|
180
|
+
const reasonCodes = [];
|
|
181
|
+
const auditNotes = [
|
|
182
|
+
'Discovery relevance is informational only and is not used for trust, safety, payment, or budget approval.',
|
|
183
|
+
];
|
|
184
|
+
if (policy.allowedSourceKinds && !policy.allowedSourceKinds.includes(candidate.sourceKind)) {
|
|
185
|
+
reasonCodes.push('source_not_allowed');
|
|
186
|
+
auditNotes.push(`Denied: discovery source ${candidate.sourceKind} is not allowed by policy.`);
|
|
187
|
+
}
|
|
188
|
+
const trustStatus = candidate.providerTrust?.verification?.status;
|
|
189
|
+
if (policy.requireVerifiedTrust && trustStatus !== 'verified') {
|
|
190
|
+
reasonCodes.push('trust_verification_required');
|
|
191
|
+
auditNotes.push(`Denied: provider trust status is ${trustStatus ?? 'missing'}, but policy requires verified trust.`);
|
|
192
|
+
}
|
|
193
|
+
if (!candidate.quote) {
|
|
194
|
+
reasonCodes.push('missing_quote');
|
|
195
|
+
auditNotes.push('Denied: discovery candidate has no quote; RAP quote/payment preflight must happen before invocation.');
|
|
196
|
+
}
|
|
197
|
+
else {
|
|
198
|
+
const quoted = amountToBigInt(candidate.quote.amount);
|
|
199
|
+
if (quoted === undefined || !candidate.quote.asset || !candidate.quote.network) {
|
|
200
|
+
reasonCodes.push('malformed_candidate');
|
|
201
|
+
auditNotes.push('Denied: discovery candidate quote must include decimal amount, asset, and network.');
|
|
202
|
+
}
|
|
203
|
+
if (policy.allowedAssets && !policy.allowedAssets.includes(candidate.quote.asset)) {
|
|
204
|
+
reasonCodes.push('unsupported_asset');
|
|
205
|
+
auditNotes.push(`Denied: quote asset ${candidate.quote.asset} is not allowed by policy.`);
|
|
206
|
+
}
|
|
207
|
+
if (policy.allowedNetworks && !policy.allowedNetworks.includes(candidate.quote.network)) {
|
|
208
|
+
reasonCodes.push('unsupported_network');
|
|
209
|
+
auditNotes.push(`Denied: quote network ${candidate.quote.network} is not allowed by policy.`);
|
|
210
|
+
}
|
|
211
|
+
if (policy.maxQuote) {
|
|
212
|
+
const maximum = amountToBigInt(policy.maxQuote.amount);
|
|
213
|
+
if (quoted === undefined
|
|
214
|
+
|| maximum === undefined
|
|
215
|
+
|| candidate.quote.asset !== policy.maxQuote.asset
|
|
216
|
+
|| candidate.quote.network !== policy.maxQuote.network
|
|
217
|
+
|| quoted > maximum) {
|
|
218
|
+
reasonCodes.push('over_budget');
|
|
219
|
+
auditNotes.push('Denied: quote exceeds the policy maximum or does not match the expected asset/network.');
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
return {
|
|
224
|
+
allowed: reasonCodes.length === 0,
|
|
225
|
+
reasonCodes: reasonCodes.length === 0 ? ['candidate_ready_for_policy_preflight'] : reasonCodes,
|
|
226
|
+
auditNotes,
|
|
227
|
+
candidate: {
|
|
228
|
+
identifier: candidate.identifier,
|
|
229
|
+
sourceKind: candidate.sourceKind,
|
|
230
|
+
relevanceScore: candidate.relevance?.score,
|
|
231
|
+
trustStatus,
|
|
232
|
+
},
|
|
233
|
+
quote: candidate.quote,
|
|
234
|
+
};
|
|
235
|
+
}
|
|
236
|
+
export const discoverySourceFixtures = {
|
|
237
|
+
localSpecialistCandidate: {
|
|
238
|
+
schemaVersion: DISCOVERY_CANDIDATE_SCHEMA_VERSION,
|
|
239
|
+
sourceKind: 'local-specialist',
|
|
240
|
+
identifier: 'urn:ai:local:specialists:lint',
|
|
241
|
+
publisher: { id: 'local' },
|
|
242
|
+
name: 'Local Lint Specialist',
|
|
243
|
+
resourceType: 'application/mcp-server-card+json',
|
|
244
|
+
mediaType: 'application/mcp-server-card+json',
|
|
245
|
+
endpoint: 'http://localhost:4100/mcp',
|
|
246
|
+
relevance: { score: 0.4, source: 'local-fixture' },
|
|
247
|
+
rawSnapshotRef: 'sha256:local-specialist-fixture',
|
|
248
|
+
quote: { amount: '1000', asset: 'AUDD', network: 'solana-devnet' },
|
|
249
|
+
policyPreflightRequired: true,
|
|
250
|
+
},
|
|
251
|
+
};
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
export declare const EVIDENCE_ARCHIVE_RECORD_SCHEMA_VERSION: "reddi.evidence-archive.v1";
|
|
2
|
+
export type EvidenceArchiveRecord = {
|
|
3
|
+
schemaVersion: typeof EVIDENCE_ARCHIVE_RECORD_SCHEMA_VERSION;
|
|
4
|
+
id: string;
|
|
5
|
+
receiptId: string;
|
|
6
|
+
sourceId: string;
|
|
7
|
+
requestHash: string;
|
|
8
|
+
responseHash: string;
|
|
9
|
+
evidenceHash: string;
|
|
10
|
+
evidenceRef: string;
|
|
11
|
+
attestationId?: string;
|
|
12
|
+
externalArchivePointer?: {
|
|
13
|
+
provider: 'walrus' | 'seal' | 'ipfs' | 'custom';
|
|
14
|
+
uri: string;
|
|
15
|
+
contentHash?: string;
|
|
16
|
+
};
|
|
17
|
+
createdAt: string;
|
|
18
|
+
metadata?: Record<string, unknown>;
|
|
19
|
+
};
|
|
20
|
+
export type EvidenceArchiveValidationErrorCode = 'malformed_evidence_record' | 'hash_mismatch' | 'evidence_missing' | 'credential_leakage_rejected' | 'evidence_id_conflict';
|
|
21
|
+
export type EvidenceArchiveValidationError = {
|
|
22
|
+
code: EvidenceArchiveValidationErrorCode;
|
|
23
|
+
path: string;
|
|
24
|
+
message: string;
|
|
25
|
+
};
|
|
26
|
+
export type EvidenceArchiveValidationResult = {
|
|
27
|
+
ok: true;
|
|
28
|
+
record: EvidenceArchiveRecord;
|
|
29
|
+
} | {
|
|
30
|
+
ok: false;
|
|
31
|
+
errors: EvidenceArchiveValidationError[];
|
|
32
|
+
};
|
|
33
|
+
export type EvidenceArchiveLookupResult = {
|
|
34
|
+
ok: true;
|
|
35
|
+
record: EvidenceArchiveRecord;
|
|
36
|
+
} | {
|
|
37
|
+
ok: false;
|
|
38
|
+
error: EvidenceArchiveValidationError;
|
|
39
|
+
};
|
|
40
|
+
export type EvidenceArchiveCreateInput = Omit<EvidenceArchiveRecord, 'schemaVersion' | 'evidenceHash'> & {
|
|
41
|
+
evidencePayload?: unknown;
|
|
42
|
+
evidenceHash?: string;
|
|
43
|
+
};
|
|
44
|
+
export type EvidenceArchiveValidationOptions = {
|
|
45
|
+
requireEvidencePayloadOrPointer?: boolean;
|
|
46
|
+
};
|
|
47
|
+
export type LocalEvidenceArchive = {
|
|
48
|
+
put(record: EvidenceArchiveRecord): EvidenceArchiveValidationResult;
|
|
49
|
+
get(id: string): EvidenceArchiveLookupResult;
|
|
50
|
+
has(id: string): boolean;
|
|
51
|
+
list(): EvidenceArchiveRecord[];
|
|
52
|
+
};
|
|
53
|
+
export declare function validateEvidenceArchiveRecord(input: unknown, evidencePayload?: unknown, options?: EvidenceArchiveValidationOptions): EvidenceArchiveValidationResult;
|
|
54
|
+
export declare function createEvidenceArchiveRecord(input: EvidenceArchiveCreateInput): EvidenceArchiveRecord;
|
|
55
|
+
/**
|
|
56
|
+
* A stored record is never replaced. Putting the identical record again is a no-op that
|
|
57
|
+
* succeeds; putting different content under an existing id is refused with
|
|
58
|
+
* `evidence_id_conflict` and the first record stays as it was, so a retry cannot erase the
|
|
59
|
+
* first observation without anyone knowing (#724).
|
|
60
|
+
*/
|
|
61
|
+
export declare function createLocalEvidenceArchive(initialRecords?: EvidenceArchiveRecord[]): LocalEvidenceArchive;
|
|
62
|
+
export declare const evidenceArchiveFixtures: {
|
|
63
|
+
readonly evidencePayload: {
|
|
64
|
+
readonly request: {
|
|
65
|
+
readonly hash: "sha256:7b2d0ef8455d0f0f41a37ea5e6a47f52c0d73d97f426097f159a98f8c8fb6b15";
|
|
66
|
+
};
|
|
67
|
+
readonly response: {
|
|
68
|
+
readonly hash: "sha256:8c9d1f1e3d0f02b5afcbb31dfbb3ab3de70ce1b84ff3ca856d272b2f4f7f4501";
|
|
69
|
+
};
|
|
70
|
+
readonly resultSummary: "Planning specialist completed a deterministic no-spend fixture run.";
|
|
71
|
+
};
|
|
72
|
+
};
|
|
73
|
+
export declare const evidenceArchiveFixtureRecord: EvidenceArchiveRecord;
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
import { canonicalizePaymentObject } from './payment-records.js';
|
|
3
|
+
export const EVIDENCE_ARCHIVE_RECORD_SCHEMA_VERSION = 'reddi.evidence-archive.v1';
|
|
4
|
+
const HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
|
|
5
|
+
const SENSITIVE_KEY_PATTERN = /(^|[_-])(api[_-]?key|authorization|bearer|cookie|credential|mnemonic|password|private[_-]?key|refresh[_-]?token|secret|seed|session[_-]?token|signature|sig|signed|token)($|[_-])|apiKey|accessToken|refreshToken|sessionToken|privateKey|X-Goog-Signature|X-Amz-Signature/i;
|
|
6
|
+
const SENSITIVE_VALUE_PATTERN = /(-----BEGIN [A-Z ]*PRIVATE KEY-----|authorization:\s*bearer\s+|bearer\s+[a-z0-9._-]{8,}|sk-[a-z0-9_-]{8,})/i;
|
|
7
|
+
function error(code, path, message) {
|
|
8
|
+
return { code, path, message };
|
|
9
|
+
}
|
|
10
|
+
function isPlainObject(value) {
|
|
11
|
+
if (value === null || typeof value !== 'object' || Array.isArray(value))
|
|
12
|
+
return false;
|
|
13
|
+
const prototype = Object.getPrototypeOf(value);
|
|
14
|
+
return prototype === Object.prototype || prototype === null;
|
|
15
|
+
}
|
|
16
|
+
function isNonEmptyString(value) {
|
|
17
|
+
return typeof value === 'string' && value.trim().length > 0;
|
|
18
|
+
}
|
|
19
|
+
function hashJson(value) {
|
|
20
|
+
try {
|
|
21
|
+
return `sha256:${createHash('sha256').update(JSON.stringify(value)).digest('hex')}`;
|
|
22
|
+
}
|
|
23
|
+
catch {
|
|
24
|
+
return undefined;
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
function findCredentialMaterial(value, path = '$') {
|
|
28
|
+
if (typeof value === 'string')
|
|
29
|
+
return SENSITIVE_VALUE_PATTERN.test(value) ? path : undefined;
|
|
30
|
+
if (!value || typeof value !== 'object')
|
|
31
|
+
return undefined;
|
|
32
|
+
if (Array.isArray(value)) {
|
|
33
|
+
for (let index = 0; index < value.length; index += 1) {
|
|
34
|
+
const found = findCredentialMaterial(value[index], `${path}[${index}]`);
|
|
35
|
+
if (found)
|
|
36
|
+
return found;
|
|
37
|
+
}
|
|
38
|
+
return undefined;
|
|
39
|
+
}
|
|
40
|
+
for (const [key, nested] of Object.entries(value)) {
|
|
41
|
+
const nextPath = `${path}.${key}`;
|
|
42
|
+
if (SENSITIVE_KEY_PATTERN.test(key))
|
|
43
|
+
return nextPath;
|
|
44
|
+
const found = findCredentialMaterial(nested, nextPath);
|
|
45
|
+
if (found)
|
|
46
|
+
return found;
|
|
47
|
+
}
|
|
48
|
+
return undefined;
|
|
49
|
+
}
|
|
50
|
+
function requireString(value, path, errors) {
|
|
51
|
+
if (!isNonEmptyString(value))
|
|
52
|
+
errors.push(error('malformed_evidence_record', path, 'required string is missing'));
|
|
53
|
+
}
|
|
54
|
+
function requireHash(value, path, errors) {
|
|
55
|
+
if (!isNonEmptyString(value) || !HASH_PATTERN.test(value)) {
|
|
56
|
+
errors.push(error('malformed_evidence_record', path, 'hash must be a sha256:<hex> reference'));
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
function validatePublicReference(value, path, errors) {
|
|
60
|
+
if (!isNonEmptyString(value))
|
|
61
|
+
return;
|
|
62
|
+
if (SENSITIVE_VALUE_PATTERN.test(value)) {
|
|
63
|
+
errors.push(error('credential_leakage_rejected', path, 'public evidence references must not include credential-shaped values'));
|
|
64
|
+
return;
|
|
65
|
+
}
|
|
66
|
+
let parsed;
|
|
67
|
+
try {
|
|
68
|
+
parsed = new URL(value);
|
|
69
|
+
}
|
|
70
|
+
catch {
|
|
71
|
+
return;
|
|
72
|
+
}
|
|
73
|
+
if (parsed.username || parsed.password) {
|
|
74
|
+
errors.push(error('credential_leakage_rejected', path, 'public evidence references must not embed credentials'));
|
|
75
|
+
}
|
|
76
|
+
for (const key of parsed.searchParams.keys()) {
|
|
77
|
+
if (SENSITIVE_KEY_PATTERN.test(key)) {
|
|
78
|
+
errors.push(error('credential_leakage_rejected', `${path}.${key}`, 'public evidence references must not include credential-shaped query keys'));
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
for (const queryValue of parsed.searchParams.values()) {
|
|
82
|
+
if (SENSITIVE_VALUE_PATTERN.test(queryValue)) {
|
|
83
|
+
errors.push(error('credential_leakage_rejected', path, 'public evidence references must not include credential-shaped query values'));
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
function validateExternalPointer(value, errors) {
|
|
88
|
+
if (value === undefined)
|
|
89
|
+
return;
|
|
90
|
+
if (!isPlainObject(value)) {
|
|
91
|
+
errors.push(error('malformed_evidence_record', '$.externalArchivePointer', 'externalArchivePointer must be an object'));
|
|
92
|
+
return;
|
|
93
|
+
}
|
|
94
|
+
if (!['walrus', 'seal', 'ipfs', 'custom'].includes(String(value.provider))) {
|
|
95
|
+
errors.push(error('malformed_evidence_record', '$.externalArchivePointer.provider', 'external archive provider is unsupported'));
|
|
96
|
+
}
|
|
97
|
+
requireString(value.uri, '$.externalArchivePointer.uri', errors);
|
|
98
|
+
validatePublicReference(value.uri, '$.externalArchivePointer.uri', errors);
|
|
99
|
+
if (value.contentHash !== undefined)
|
|
100
|
+
requireHash(value.contentHash, '$.externalArchivePointer.contentHash', errors);
|
|
101
|
+
}
|
|
102
|
+
export function validateEvidenceArchiveRecord(input, evidencePayload, options = {}) {
|
|
103
|
+
const errors = [];
|
|
104
|
+
if (!isPlainObject(input)) {
|
|
105
|
+
return { ok: false, errors: [error('malformed_evidence_record', '$', 'evidence archive record must be a plain object')] };
|
|
106
|
+
}
|
|
107
|
+
const record = input;
|
|
108
|
+
if (record.schemaVersion !== EVIDENCE_ARCHIVE_RECORD_SCHEMA_VERSION) {
|
|
109
|
+
errors.push(error('malformed_evidence_record', '$.schemaVersion', `expected ${EVIDENCE_ARCHIVE_RECORD_SCHEMA_VERSION}`));
|
|
110
|
+
}
|
|
111
|
+
requireString(record.id, '$.id', errors);
|
|
112
|
+
requireString(record.receiptId, '$.receiptId', errors);
|
|
113
|
+
requireString(record.sourceId, '$.sourceId', errors);
|
|
114
|
+
requireHash(record.requestHash, '$.requestHash', errors);
|
|
115
|
+
requireHash(record.responseHash, '$.responseHash', errors);
|
|
116
|
+
requireHash(record.evidenceHash, '$.evidenceHash', errors);
|
|
117
|
+
requireString(record.evidenceRef, '$.evidenceRef', errors);
|
|
118
|
+
validatePublicReference(record.evidenceRef, '$.evidenceRef', errors);
|
|
119
|
+
if (record.attestationId !== undefined)
|
|
120
|
+
requireString(record.attestationId, '$.attestationId', errors);
|
|
121
|
+
if (!isNonEmptyString(record.createdAt) || Number.isNaN(Date.parse(record.createdAt))) {
|
|
122
|
+
errors.push(error('malformed_evidence_record', '$.createdAt', 'createdAt must be an ISO timestamp'));
|
|
123
|
+
}
|
|
124
|
+
validateExternalPointer(record.externalArchivePointer, errors);
|
|
125
|
+
const credentialPath = findCredentialMaterial(record.metadata);
|
|
126
|
+
if (credentialPath) {
|
|
127
|
+
errors.push(error('credential_leakage_rejected', `$.metadata${credentialPath.slice(1)}`, 'evidence metadata contains credential-shaped material'));
|
|
128
|
+
}
|
|
129
|
+
const requireEvidencePayloadOrPointer = options.requireEvidencePayloadOrPointer ?? true;
|
|
130
|
+
if (requireEvidencePayloadOrPointer && evidencePayload === undefined && !record.externalArchivePointer) {
|
|
131
|
+
errors.push(error('evidence_missing', '$.evidencePayload', 'local evidence payload or external archive pointer is required'));
|
|
132
|
+
}
|
|
133
|
+
if (evidencePayload !== undefined) {
|
|
134
|
+
const payloadCredentialPath = findCredentialMaterial(evidencePayload);
|
|
135
|
+
if (payloadCredentialPath) {
|
|
136
|
+
errors.push(error('credential_leakage_rejected', `$.evidencePayload${payloadCredentialPath.slice(1)}`, 'evidence payload contains credential-shaped material'));
|
|
137
|
+
}
|
|
138
|
+
const expectedHash = hashJson(evidencePayload);
|
|
139
|
+
if (!expectedHash) {
|
|
140
|
+
errors.push(error('malformed_evidence_record', '$.evidencePayload', 'evidence payload must be JSON-serializable'));
|
|
141
|
+
}
|
|
142
|
+
else if (record.evidenceHash && expectedHash !== record.evidenceHash) {
|
|
143
|
+
errors.push(error('hash_mismatch', '$.evidenceHash', 'evidenceHash does not match the supplied evidence payload'));
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
return errors.length === 0 ? { ok: true, record } : { ok: false, errors };
|
|
147
|
+
}
|
|
148
|
+
export function createEvidenceArchiveRecord(input) {
|
|
149
|
+
const evidenceHash = input.evidenceHash ?? hashJson(input.evidencePayload);
|
|
150
|
+
const record = {
|
|
151
|
+
schemaVersion: EVIDENCE_ARCHIVE_RECORD_SCHEMA_VERSION,
|
|
152
|
+
id: input.id,
|
|
153
|
+
receiptId: input.receiptId,
|
|
154
|
+
sourceId: input.sourceId,
|
|
155
|
+
requestHash: input.requestHash,
|
|
156
|
+
responseHash: input.responseHash,
|
|
157
|
+
evidenceHash: evidenceHash ?? '',
|
|
158
|
+
evidenceRef: input.evidenceRef,
|
|
159
|
+
attestationId: input.attestationId,
|
|
160
|
+
externalArchivePointer: input.externalArchivePointer,
|
|
161
|
+
createdAt: input.createdAt,
|
|
162
|
+
metadata: input.metadata,
|
|
163
|
+
};
|
|
164
|
+
const validation = validateEvidenceArchiveRecord(record, input.evidencePayload);
|
|
165
|
+
if (!validation.ok) {
|
|
166
|
+
throw new Error(`invalid_evidence_archive_record:${validation.errors.map((item) => `${item.code}:${item.path}`).join(',')}`);
|
|
167
|
+
}
|
|
168
|
+
return validation.record;
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* A stored record is never replaced. Putting the identical record again is a no-op that
|
|
172
|
+
* succeeds; putting different content under an existing id is refused with
|
|
173
|
+
* `evidence_id_conflict` and the first record stays as it was, so a retry cannot erase the
|
|
174
|
+
* first observation without anyone knowing (#724).
|
|
175
|
+
*/
|
|
176
|
+
export function createLocalEvidenceArchive(initialRecords = []) {
|
|
177
|
+
const records = new Map();
|
|
178
|
+
function conflictWithStored(record) {
|
|
179
|
+
const stored = records.get(record.id);
|
|
180
|
+
if (stored === undefined || canonicalizePaymentObject(stored) === canonicalizePaymentObject(record))
|
|
181
|
+
return undefined;
|
|
182
|
+
return error('evidence_id_conflict', '$.id', `A different evidence archive record is already stored under ${record.id}`);
|
|
183
|
+
}
|
|
184
|
+
for (const record of initialRecords) {
|
|
185
|
+
const result = validateEvidenceArchiveRecord(record, undefined, { requireEvidencePayloadOrPointer: false });
|
|
186
|
+
if (!result.ok) {
|
|
187
|
+
throw new Error(`invalid_initial_evidence_archive_record:${result.errors.map((item) => item.code).join(',')}`);
|
|
188
|
+
}
|
|
189
|
+
const conflict = conflictWithStored(result.record);
|
|
190
|
+
if (conflict) {
|
|
191
|
+
throw new Error(`invalid_initial_evidence_archive_record:${conflict.code}`);
|
|
192
|
+
}
|
|
193
|
+
records.set(record.id, result.record);
|
|
194
|
+
}
|
|
195
|
+
return {
|
|
196
|
+
put(record) {
|
|
197
|
+
const result = validateEvidenceArchiveRecord(record, undefined, { requireEvidencePayloadOrPointer: false });
|
|
198
|
+
if (!result.ok)
|
|
199
|
+
return result;
|
|
200
|
+
const conflict = conflictWithStored(result.record);
|
|
201
|
+
if (conflict)
|
|
202
|
+
return { ok: false, errors: [conflict] };
|
|
203
|
+
records.set(record.id, result.record);
|
|
204
|
+
return result;
|
|
205
|
+
},
|
|
206
|
+
get(id) {
|
|
207
|
+
const record = records.get(id);
|
|
208
|
+
if (!record) {
|
|
209
|
+
return { ok: false, error: error('evidence_missing', '$.id', `No evidence archive record found for ${id}`) };
|
|
210
|
+
}
|
|
211
|
+
return { ok: true, record };
|
|
212
|
+
},
|
|
213
|
+
has(id) {
|
|
214
|
+
return records.has(id);
|
|
215
|
+
},
|
|
216
|
+
list() {
|
|
217
|
+
return [...records.values()];
|
|
218
|
+
},
|
|
219
|
+
};
|
|
220
|
+
}
|
|
221
|
+
export const evidenceArchiveFixtures = {
|
|
222
|
+
evidencePayload: {
|
|
223
|
+
request: { hash: 'sha256:7b2d0ef8455d0f0f41a37ea5e6a47f52c0d73d97f426097f159a98f8c8fb6b15' },
|
|
224
|
+
response: { hash: 'sha256:8c9d1f1e3d0f02b5afcbb31dfbb3ab3de70ce1b84ff3ca856d272b2f4f7f4501' },
|
|
225
|
+
resultSummary: 'Planning specialist completed a deterministic no-spend fixture run.',
|
|
226
|
+
},
|
|
227
|
+
};
|
|
228
|
+
export const evidenceArchiveFixtureRecord = createEvidenceArchiveRecord({
|
|
229
|
+
id: 'evidence:planning-001',
|
|
230
|
+
receiptId: 'job:planning-001',
|
|
231
|
+
sourceId: 'source:planning',
|
|
232
|
+
requestHash: 'sha256:7b2d0ef8455d0f0f41a37ea5e6a47f52c0d73d97f426097f159a98f8c8fb6b15',
|
|
233
|
+
responseHash: 'sha256:8c9d1f1e3d0f02b5afcbb31dfbb3ab3de70ce1b84ff3ca856d272b2f4f7f4501',
|
|
234
|
+
evidenceRef: 'file://fixtures/evidence/planning-001.json',
|
|
235
|
+
attestationId: 'attestation:planning-001',
|
|
236
|
+
createdAt: '2026-06-18T12:15:00.000Z',
|
|
237
|
+
evidencePayload: evidenceArchiveFixtures.evidencePayload,
|
|
238
|
+
});
|