@kya-os/checkpoint-shared 1.2.1 → 1.3.1
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 +19 -0
- package/README.md +1 -1
- package/dist/beacon-types/index.d.mts +13 -2
- package/dist/beacon-types/index.d.ts +13 -2
- package/dist/beacon-types/index.js +35 -3
- package/dist/beacon-types/index.mjs +35 -4
- package/dist/browser-posture-report.d.mts +85 -0
- package/dist/browser-posture-report.d.ts +85 -0
- package/dist/browser-posture-report.js +1 -0
- package/dist/browser-posture-report.mjs +1 -0
- package/dist/browser-posture.d.mts +114 -0
- package/dist/browser-posture.d.ts +114 -0
- package/dist/browser-posture.js +4204 -0
- package/dist/browser-posture.mjs +4187 -0
- package/dist/browser.d.mts +35 -1
- package/dist/browser.d.ts +35 -1
- package/dist/browser.js +1 -1
- package/dist/browser.mjs +1 -1
- package/dist/canonical-signer/index.js +31 -2
- package/dist/canonical-signer/index.mjs +31 -2
- package/dist/deploy/index.d.mts +449 -2
- package/dist/deploy/index.d.ts +449 -2
- package/dist/deploy/index.js +238 -1
- package/dist/deploy/index.mjs +228 -2
- package/dist/errors/index.d.mts +104 -0
- package/dist/errors/index.d.ts +104 -0
- package/dist/errors/index.js +338 -0
- package/dist/errors/index.mjs +333 -0
- package/dist/gateway/index.d.mts +6 -1
- package/dist/gateway/index.d.ts +6 -1
- package/dist/gateway/index.js +4 -0
- package/dist/gateway/index.mjs +4 -1
- package/dist/index.d.mts +2388 -851
- package/dist/index.d.ts +2388 -851
- package/dist/index.js +2684 -686
- package/dist/index.mjs +2575 -669
- package/dist/mcpi/multibase-ed25519.d.mts +8 -0
- package/dist/mcpi/multibase-ed25519.d.ts +8 -0
- package/dist/mcpi/multibase-ed25519.js +125 -0
- package/dist/mcpi/multibase-ed25519.mjs +119 -0
- package/dist/signals/index.d.mts +158 -0
- package/dist/signals/index.d.ts +158 -0
- package/dist/signals/index.js +1667 -0
- package/dist/signals/index.mjs +1637 -0
- package/dist/test-fixtures/index.d.mts +37 -1
- package/dist/test-fixtures/index.d.ts +37 -1
- package/dist/test-fixtures/index.js +92 -1
- package/dist/test-fixtures/index.mjs +87 -2
- package/fixtures/client-ip-resolution.json +103 -0
- package/fixtures/detection/reason-codes.json +35 -0
- package/fixtures/detection/signal-exposure-example.json +62 -0
- package/fixtures/kya-http/README.md +112 -0
- package/fixtures/kya-http/challenge-proof.canonical.json +25 -0
- package/fixtures/kya-http/challenge.approval-quorum.json +37 -0
- package/fixtures/kya-http/challenge.delegation.fetcher-200.json +55 -0
- package/fixtures/kya-http/challenge.delegation.full.json +81 -0
- package/fixtures/kya-http/challenge.delegation.minimal.json +57 -0
- package/fixtures/kya-http/error-codes.json +35 -0
- package/fixtures/kya-http/fetcher-200-predicate.vectors.json +72 -0
- package/fixtures/kya-http/negative.challenges.json +54 -0
- package/fixtures/kya-http/pickup.transcript.json +96 -0
- package/fixtures/kya-http/pickup.transcript.quorum.json +156 -0
- package/fixtures/kya-http/protected-resource-metadata.full.json +30 -0
- package/fixtures/kya-http/protected-resource-metadata.global.json +28 -0
- package/fixtures/kya-http/registration.request.json +33 -0
- package/fixtures/kya-http/registration.response.json +32 -0
- package/package.json +42 -9
- package/src/data/compiled/merged-rules.json +8 -2
|
@@ -91,8 +91,44 @@ interface FetcherEnvelopePredicateVector {
|
|
|
91
91
|
description: string;
|
|
92
92
|
headers: Record<string, string>;
|
|
93
93
|
detectionClass: FetcherPredicateDetectionClass;
|
|
94
|
+
isAgent: boolean;
|
|
94
95
|
expected: boolean;
|
|
95
96
|
}
|
|
96
97
|
declare const FETCHER_200_PREDICATE_VECTORS: readonly FetcherEnvelopePredicateVector[];
|
|
97
98
|
|
|
98
|
-
|
|
99
|
+
type DelegationVerdictKind = 'Permit' | 'Block';
|
|
100
|
+
type CoarseReasonKind = 'signature' | 'claim' | 'time' | 'revocation' | 'scope' | 'resolve';
|
|
101
|
+
interface DelegationVerdictReason {
|
|
102
|
+
kind: CoarseReasonKind;
|
|
103
|
+
}
|
|
104
|
+
interface DelegationVerdict {
|
|
105
|
+
kind: DelegationVerdictKind;
|
|
106
|
+
reason: DelegationVerdictReason | null;
|
|
107
|
+
}
|
|
108
|
+
declare function toCoarseReasonKind(rawReasonKind: string): CoarseReasonKind;
|
|
109
|
+
declare function permitDelegationVerdict(): DelegationVerdict;
|
|
110
|
+
declare function blockDelegationVerdict(rawReasonKind: string): DelegationVerdict;
|
|
111
|
+
|
|
112
|
+
declare function detectionSignalFixture(overrides?: Partial<{
|
|
113
|
+
signalType: 'signature' | 'pattern' | 'behavioral' | 'network' | 'fingerprint';
|
|
114
|
+
confidence: number;
|
|
115
|
+
weight: number;
|
|
116
|
+
source: string;
|
|
117
|
+
explanation: string;
|
|
118
|
+
}>): {
|
|
119
|
+
signalType: "signature" | "pattern" | "behavioral" | "network" | "fingerprint";
|
|
120
|
+
confidence: number;
|
|
121
|
+
weight: number;
|
|
122
|
+
source: string;
|
|
123
|
+
explanation: string;
|
|
124
|
+
};
|
|
125
|
+
declare const TWO_SIGNAL_EVIDENCE_FIXTURE: {
|
|
126
|
+
signalType: "signature" | "pattern" | "behavioral" | "network" | "fingerprint";
|
|
127
|
+
confidence: number;
|
|
128
|
+
weight: number;
|
|
129
|
+
source: string;
|
|
130
|
+
explanation: string;
|
|
131
|
+
}[];
|
|
132
|
+
declare const TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE = 94.78;
|
|
133
|
+
|
|
134
|
+
export { type CoarseReasonKind, type DelegationVerdict, type DelegationVerdictKind, type DelegationVerdictReason, FETCHER_200_PREDICATE_VECTORS, type FetcherEnvelopePredicateVector, type FetcherPredicateDetectionClass, MCPI_DELEGATION_AGENT_DID, MCPI_DELEGATION_AUDIENCE, MCPI_DELEGATION_CANONICAL_PAYLOAD, MCPI_DELEGATION_EXPECTED_HEADER, MCPI_DELEGATION_EXPECTED_JWT, MCPI_DELEGATION_ISSUER_DID, MCPI_DELEGATION_ISSUER_KID, MCPI_DELEGATION_STATUS_LIST_URL, MCPI_DELEGATION_TEST_KEYPAIR, MCPI_DELEGATION_USER_DID, TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE, TWO_SIGNAL_EVIDENCE_FIXTURE, VAULT_WIRE_CONTRACT_CANONICAL_PAYLOAD, VAULT_WIRE_CONTRACT_EXPECTED_HEADER, VAULT_WIRE_CONTRACT_EXPECTED_JWT, VAULT_WIRE_CONTRACT_EXPECTED_REQUEST_BODY, VAULT_WIRE_CONTRACT_TEST_KEYPAIR, VAULT_WIRE_CONTRACT_URL_PATH, blockDelegationVerdict, detectionSignalFixture, permitDelegationVerdict, toCoarseReasonKind };
|
|
@@ -91,8 +91,44 @@ interface FetcherEnvelopePredicateVector {
|
|
|
91
91
|
description: string;
|
|
92
92
|
headers: Record<string, string>;
|
|
93
93
|
detectionClass: FetcherPredicateDetectionClass;
|
|
94
|
+
isAgent: boolean;
|
|
94
95
|
expected: boolean;
|
|
95
96
|
}
|
|
96
97
|
declare const FETCHER_200_PREDICATE_VECTORS: readonly FetcherEnvelopePredicateVector[];
|
|
97
98
|
|
|
98
|
-
|
|
99
|
+
type DelegationVerdictKind = 'Permit' | 'Block';
|
|
100
|
+
type CoarseReasonKind = 'signature' | 'claim' | 'time' | 'revocation' | 'scope' | 'resolve';
|
|
101
|
+
interface DelegationVerdictReason {
|
|
102
|
+
kind: CoarseReasonKind;
|
|
103
|
+
}
|
|
104
|
+
interface DelegationVerdict {
|
|
105
|
+
kind: DelegationVerdictKind;
|
|
106
|
+
reason: DelegationVerdictReason | null;
|
|
107
|
+
}
|
|
108
|
+
declare function toCoarseReasonKind(rawReasonKind: string): CoarseReasonKind;
|
|
109
|
+
declare function permitDelegationVerdict(): DelegationVerdict;
|
|
110
|
+
declare function blockDelegationVerdict(rawReasonKind: string): DelegationVerdict;
|
|
111
|
+
|
|
112
|
+
declare function detectionSignalFixture(overrides?: Partial<{
|
|
113
|
+
signalType: 'signature' | 'pattern' | 'behavioral' | 'network' | 'fingerprint';
|
|
114
|
+
confidence: number;
|
|
115
|
+
weight: number;
|
|
116
|
+
source: string;
|
|
117
|
+
explanation: string;
|
|
118
|
+
}>): {
|
|
119
|
+
signalType: "signature" | "pattern" | "behavioral" | "network" | "fingerprint";
|
|
120
|
+
confidence: number;
|
|
121
|
+
weight: number;
|
|
122
|
+
source: string;
|
|
123
|
+
explanation: string;
|
|
124
|
+
};
|
|
125
|
+
declare const TWO_SIGNAL_EVIDENCE_FIXTURE: {
|
|
126
|
+
signalType: "signature" | "pattern" | "behavioral" | "network" | "fingerprint";
|
|
127
|
+
confidence: number;
|
|
128
|
+
weight: number;
|
|
129
|
+
source: string;
|
|
130
|
+
explanation: string;
|
|
131
|
+
}[];
|
|
132
|
+
declare const TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE = 94.78;
|
|
133
|
+
|
|
134
|
+
export { type CoarseReasonKind, type DelegationVerdict, type DelegationVerdictKind, type DelegationVerdictReason, FETCHER_200_PREDICATE_VECTORS, type FetcherEnvelopePredicateVector, type FetcherPredicateDetectionClass, MCPI_DELEGATION_AGENT_DID, MCPI_DELEGATION_AUDIENCE, MCPI_DELEGATION_CANONICAL_PAYLOAD, MCPI_DELEGATION_EXPECTED_HEADER, MCPI_DELEGATION_EXPECTED_JWT, MCPI_DELEGATION_ISSUER_DID, MCPI_DELEGATION_ISSUER_KID, MCPI_DELEGATION_STATUS_LIST_URL, MCPI_DELEGATION_TEST_KEYPAIR, MCPI_DELEGATION_USER_DID, TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE, TWO_SIGNAL_EVIDENCE_FIXTURE, VAULT_WIRE_CONTRACT_CANONICAL_PAYLOAD, VAULT_WIRE_CONTRACT_EXPECTED_HEADER, VAULT_WIRE_CONTRACT_EXPECTED_JWT, VAULT_WIRE_CONTRACT_EXPECTED_REQUEST_BODY, VAULT_WIRE_CONTRACT_TEST_KEYPAIR, VAULT_WIRE_CONTRACT_URL_PATH, blockDelegationVerdict, detectionSignalFixture, permitDelegationVerdict, toCoarseReasonKind };
|
|
@@ -110,58 +110,143 @@ var FETCHER_200_PREDICATE_VECTORS = [
|
|
|
110
110
|
description: "opt-in header present, non-agent detection \u2192 200 (header is the primary signal)",
|
|
111
111
|
headers: { "kya-accept-challenge": "delegation" },
|
|
112
112
|
detectionClass: "human",
|
|
113
|
+
isAgent: false,
|
|
113
114
|
expected: true
|
|
114
115
|
},
|
|
115
116
|
{
|
|
116
117
|
description: "opt-in header present, detection absent \u2192 200",
|
|
117
118
|
headers: { "kya-accept-challenge": "delegation" },
|
|
118
119
|
detectionClass: null,
|
|
120
|
+
isAgent: false,
|
|
119
121
|
expected: true
|
|
120
122
|
},
|
|
121
123
|
{
|
|
122
|
-
description: "detected ai_agent, no opt-in \u2192 200 (transitional UA heuristic)",
|
|
124
|
+
description: "detected ai_agent (isAgent agrees), no opt-in \u2192 200 (transitional UA heuristic)",
|
|
123
125
|
headers: {},
|
|
124
126
|
detectionClass: "ai_agent",
|
|
127
|
+
isAgent: true,
|
|
125
128
|
expected: true
|
|
126
129
|
},
|
|
127
130
|
{
|
|
128
131
|
description: "Accept: text/html on a detected agent \u2192 200 (Accept MUST NOT branch the body)",
|
|
129
132
|
headers: { accept: "text/markdown, text/html, */*" },
|
|
130
133
|
detectionClass: "ai_agent",
|
|
134
|
+
isAgent: true,
|
|
131
135
|
expected: true
|
|
132
136
|
},
|
|
137
|
+
{
|
|
138
|
+
description: "ai_agent class but isAgent=false (signals disagree) \u2192 401 (require both, matches .NET + worker)",
|
|
139
|
+
headers: {},
|
|
140
|
+
detectionClass: "ai_agent",
|
|
141
|
+
isAgent: false,
|
|
142
|
+
expected: false
|
|
143
|
+
},
|
|
133
144
|
{
|
|
134
145
|
description: "human, no opt-in \u2192 401 (spec path)",
|
|
135
146
|
headers: {},
|
|
136
147
|
detectionClass: "human",
|
|
148
|
+
isAgent: false,
|
|
137
149
|
expected: false
|
|
138
150
|
},
|
|
139
151
|
{
|
|
140
152
|
description: "bot, no opt-in \u2192 401 (non-cooperative / spoofer lands on spec path)",
|
|
141
153
|
headers: {},
|
|
142
154
|
detectionClass: "bot",
|
|
155
|
+
isAgent: false,
|
|
143
156
|
expected: false
|
|
144
157
|
},
|
|
145
158
|
{
|
|
146
159
|
description: "incomplete_data, no opt-in \u2192 401",
|
|
147
160
|
headers: {},
|
|
148
161
|
detectionClass: "incomplete_data",
|
|
162
|
+
isAgent: false,
|
|
149
163
|
expected: false
|
|
150
164
|
},
|
|
151
165
|
{
|
|
152
166
|
description: "no signals at all \u2192 401",
|
|
153
167
|
headers: {},
|
|
154
168
|
detectionClass: null,
|
|
169
|
+
isAgent: false,
|
|
155
170
|
expected: false
|
|
156
171
|
},
|
|
157
172
|
{
|
|
158
173
|
description: "empty opt-in value is ignored, human \u2192 401",
|
|
159
174
|
headers: { "kya-accept-challenge": "" },
|
|
160
175
|
detectionClass: "human",
|
|
176
|
+
isAgent: false,
|
|
161
177
|
expected: false
|
|
162
178
|
}
|
|
163
179
|
];
|
|
164
180
|
|
|
181
|
+
// src/mcpi/delegation-verdict.ts
|
|
182
|
+
var REASON_KIND_MAP = {
|
|
183
|
+
// --- gateway: apps/gateway/src/lib/mcpi-auth-resolver.ts ---
|
|
184
|
+
missing_bearer_token: "claim",
|
|
185
|
+
parse_error: "claim",
|
|
186
|
+
did_resolve_failed: "resolve",
|
|
187
|
+
signature_invalid: "signature",
|
|
188
|
+
audience_mismatch: "claim",
|
|
189
|
+
expired: "time",
|
|
190
|
+
not_yet_valid: "time",
|
|
191
|
+
revoked: "revocation",
|
|
192
|
+
delegation_inactive: "revocation",
|
|
193
|
+
missing_claim: "claim",
|
|
194
|
+
claim_invalid: "claim",
|
|
195
|
+
// --- gateway: apps/gateway/src/lib/dashboard-delegation-verifier.ts ---
|
|
196
|
+
not_configured: "claim",
|
|
197
|
+
header_missing: "claim",
|
|
198
|
+
claim_mismatch: "claim",
|
|
199
|
+
malformed: "claim",
|
|
200
|
+
// --- engine-rust: rust/crates/kya-os-engine/src/types.rs BlockReason ---
|
|
201
|
+
Revoked: "revocation",
|
|
202
|
+
InvalidSignature: "signature",
|
|
203
|
+
Unauthenticated: "claim",
|
|
204
|
+
Expired: "time",
|
|
205
|
+
OutOfScope: "scope"
|
|
206
|
+
};
|
|
207
|
+
function toCoarseReasonKind(rawReasonKind) {
|
|
208
|
+
const coarse = REASON_KIND_MAP[rawReasonKind];
|
|
209
|
+
if (!coarse) {
|
|
210
|
+
throw new Error(
|
|
211
|
+
`toCoarseReasonKind: unrecognized raw reason kind ${JSON.stringify(rawReasonKind)} \u2014 add it to REASON_KIND_MAP in delegation-verdict.ts with a deliberate coarse classification`
|
|
212
|
+
);
|
|
213
|
+
}
|
|
214
|
+
return coarse;
|
|
215
|
+
}
|
|
216
|
+
function permitDelegationVerdict() {
|
|
217
|
+
return { kind: "Permit", reason: null };
|
|
218
|
+
}
|
|
219
|
+
function blockDelegationVerdict(rawReasonKind) {
|
|
220
|
+
return { kind: "Block", reason: { kind: toCoarseReasonKind(rawReasonKind) } };
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
// src/test-fixtures/verdict-evidence-fixture.ts
|
|
224
|
+
function detectionSignalFixture(overrides = {}) {
|
|
225
|
+
return {
|
|
226
|
+
signalType: "pattern",
|
|
227
|
+
confidence: 80,
|
|
228
|
+
weight: 0.4,
|
|
229
|
+
source: "tier3_ua_pattern",
|
|
230
|
+
explanation: "Matches a known agent UA pattern",
|
|
231
|
+
...overrides
|
|
232
|
+
};
|
|
233
|
+
}
|
|
234
|
+
var TWO_SIGNAL_EVIDENCE_FIXTURE = [
|
|
235
|
+
detectionSignalFixture({
|
|
236
|
+
source: "known_scraper_ua",
|
|
237
|
+
signalType: "pattern",
|
|
238
|
+
weight: 1,
|
|
239
|
+
confidence: 90
|
|
240
|
+
}),
|
|
241
|
+
detectionSignalFixture({
|
|
242
|
+
source: "datacenter_ip",
|
|
243
|
+
signalType: "network",
|
|
244
|
+
weight: 0.6,
|
|
245
|
+
confidence: 70
|
|
246
|
+
})
|
|
247
|
+
];
|
|
248
|
+
var TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE = 94.78;
|
|
249
|
+
|
|
165
250
|
exports.FETCHER_200_PREDICATE_VECTORS = FETCHER_200_PREDICATE_VECTORS;
|
|
166
251
|
exports.MCPI_DELEGATION_AGENT_DID = MCPI_DELEGATION_AGENT_DID;
|
|
167
252
|
exports.MCPI_DELEGATION_AUDIENCE = MCPI_DELEGATION_AUDIENCE;
|
|
@@ -173,9 +258,15 @@ exports.MCPI_DELEGATION_ISSUER_KID = MCPI_DELEGATION_ISSUER_KID;
|
|
|
173
258
|
exports.MCPI_DELEGATION_STATUS_LIST_URL = MCPI_DELEGATION_STATUS_LIST_URL;
|
|
174
259
|
exports.MCPI_DELEGATION_TEST_KEYPAIR = MCPI_DELEGATION_TEST_KEYPAIR;
|
|
175
260
|
exports.MCPI_DELEGATION_USER_DID = MCPI_DELEGATION_USER_DID;
|
|
261
|
+
exports.TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE = TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE;
|
|
262
|
+
exports.TWO_SIGNAL_EVIDENCE_FIXTURE = TWO_SIGNAL_EVIDENCE_FIXTURE;
|
|
176
263
|
exports.VAULT_WIRE_CONTRACT_CANONICAL_PAYLOAD = VAULT_WIRE_CONTRACT_CANONICAL_PAYLOAD;
|
|
177
264
|
exports.VAULT_WIRE_CONTRACT_EXPECTED_HEADER = VAULT_WIRE_CONTRACT_EXPECTED_HEADER;
|
|
178
265
|
exports.VAULT_WIRE_CONTRACT_EXPECTED_JWT = VAULT_WIRE_CONTRACT_EXPECTED_JWT;
|
|
179
266
|
exports.VAULT_WIRE_CONTRACT_EXPECTED_REQUEST_BODY = VAULT_WIRE_CONTRACT_EXPECTED_REQUEST_BODY;
|
|
180
267
|
exports.VAULT_WIRE_CONTRACT_TEST_KEYPAIR = VAULT_WIRE_CONTRACT_TEST_KEYPAIR;
|
|
181
268
|
exports.VAULT_WIRE_CONTRACT_URL_PATH = VAULT_WIRE_CONTRACT_URL_PATH;
|
|
269
|
+
exports.blockDelegationVerdict = blockDelegationVerdict;
|
|
270
|
+
exports.detectionSignalFixture = detectionSignalFixture;
|
|
271
|
+
exports.permitDelegationVerdict = permitDelegationVerdict;
|
|
272
|
+
exports.toCoarseReasonKind = toCoarseReasonKind;
|
|
@@ -108,56 +108,141 @@ var FETCHER_200_PREDICATE_VECTORS = [
|
|
|
108
108
|
description: "opt-in header present, non-agent detection \u2192 200 (header is the primary signal)",
|
|
109
109
|
headers: { "kya-accept-challenge": "delegation" },
|
|
110
110
|
detectionClass: "human",
|
|
111
|
+
isAgent: false,
|
|
111
112
|
expected: true
|
|
112
113
|
},
|
|
113
114
|
{
|
|
114
115
|
description: "opt-in header present, detection absent \u2192 200",
|
|
115
116
|
headers: { "kya-accept-challenge": "delegation" },
|
|
116
117
|
detectionClass: null,
|
|
118
|
+
isAgent: false,
|
|
117
119
|
expected: true
|
|
118
120
|
},
|
|
119
121
|
{
|
|
120
|
-
description: "detected ai_agent, no opt-in \u2192 200 (transitional UA heuristic)",
|
|
122
|
+
description: "detected ai_agent (isAgent agrees), no opt-in \u2192 200 (transitional UA heuristic)",
|
|
121
123
|
headers: {},
|
|
122
124
|
detectionClass: "ai_agent",
|
|
125
|
+
isAgent: true,
|
|
123
126
|
expected: true
|
|
124
127
|
},
|
|
125
128
|
{
|
|
126
129
|
description: "Accept: text/html on a detected agent \u2192 200 (Accept MUST NOT branch the body)",
|
|
127
130
|
headers: { accept: "text/markdown, text/html, */*" },
|
|
128
131
|
detectionClass: "ai_agent",
|
|
132
|
+
isAgent: true,
|
|
129
133
|
expected: true
|
|
130
134
|
},
|
|
135
|
+
{
|
|
136
|
+
description: "ai_agent class but isAgent=false (signals disagree) \u2192 401 (require both, matches .NET + worker)",
|
|
137
|
+
headers: {},
|
|
138
|
+
detectionClass: "ai_agent",
|
|
139
|
+
isAgent: false,
|
|
140
|
+
expected: false
|
|
141
|
+
},
|
|
131
142
|
{
|
|
132
143
|
description: "human, no opt-in \u2192 401 (spec path)",
|
|
133
144
|
headers: {},
|
|
134
145
|
detectionClass: "human",
|
|
146
|
+
isAgent: false,
|
|
135
147
|
expected: false
|
|
136
148
|
},
|
|
137
149
|
{
|
|
138
150
|
description: "bot, no opt-in \u2192 401 (non-cooperative / spoofer lands on spec path)",
|
|
139
151
|
headers: {},
|
|
140
152
|
detectionClass: "bot",
|
|
153
|
+
isAgent: false,
|
|
141
154
|
expected: false
|
|
142
155
|
},
|
|
143
156
|
{
|
|
144
157
|
description: "incomplete_data, no opt-in \u2192 401",
|
|
145
158
|
headers: {},
|
|
146
159
|
detectionClass: "incomplete_data",
|
|
160
|
+
isAgent: false,
|
|
147
161
|
expected: false
|
|
148
162
|
},
|
|
149
163
|
{
|
|
150
164
|
description: "no signals at all \u2192 401",
|
|
151
165
|
headers: {},
|
|
152
166
|
detectionClass: null,
|
|
167
|
+
isAgent: false,
|
|
153
168
|
expected: false
|
|
154
169
|
},
|
|
155
170
|
{
|
|
156
171
|
description: "empty opt-in value is ignored, human \u2192 401",
|
|
157
172
|
headers: { "kya-accept-challenge": "" },
|
|
158
173
|
detectionClass: "human",
|
|
174
|
+
isAgent: false,
|
|
159
175
|
expected: false
|
|
160
176
|
}
|
|
161
177
|
];
|
|
162
178
|
|
|
163
|
-
|
|
179
|
+
// src/mcpi/delegation-verdict.ts
|
|
180
|
+
var REASON_KIND_MAP = {
|
|
181
|
+
// --- gateway: apps/gateway/src/lib/mcpi-auth-resolver.ts ---
|
|
182
|
+
missing_bearer_token: "claim",
|
|
183
|
+
parse_error: "claim",
|
|
184
|
+
did_resolve_failed: "resolve",
|
|
185
|
+
signature_invalid: "signature",
|
|
186
|
+
audience_mismatch: "claim",
|
|
187
|
+
expired: "time",
|
|
188
|
+
not_yet_valid: "time",
|
|
189
|
+
revoked: "revocation",
|
|
190
|
+
delegation_inactive: "revocation",
|
|
191
|
+
missing_claim: "claim",
|
|
192
|
+
claim_invalid: "claim",
|
|
193
|
+
// --- gateway: apps/gateway/src/lib/dashboard-delegation-verifier.ts ---
|
|
194
|
+
not_configured: "claim",
|
|
195
|
+
header_missing: "claim",
|
|
196
|
+
claim_mismatch: "claim",
|
|
197
|
+
malformed: "claim",
|
|
198
|
+
// --- engine-rust: rust/crates/kya-os-engine/src/types.rs BlockReason ---
|
|
199
|
+
Revoked: "revocation",
|
|
200
|
+
InvalidSignature: "signature",
|
|
201
|
+
Unauthenticated: "claim",
|
|
202
|
+
Expired: "time",
|
|
203
|
+
OutOfScope: "scope"
|
|
204
|
+
};
|
|
205
|
+
function toCoarseReasonKind(rawReasonKind) {
|
|
206
|
+
const coarse = REASON_KIND_MAP[rawReasonKind];
|
|
207
|
+
if (!coarse) {
|
|
208
|
+
throw new Error(
|
|
209
|
+
`toCoarseReasonKind: unrecognized raw reason kind ${JSON.stringify(rawReasonKind)} \u2014 add it to REASON_KIND_MAP in delegation-verdict.ts with a deliberate coarse classification`
|
|
210
|
+
);
|
|
211
|
+
}
|
|
212
|
+
return coarse;
|
|
213
|
+
}
|
|
214
|
+
function permitDelegationVerdict() {
|
|
215
|
+
return { kind: "Permit", reason: null };
|
|
216
|
+
}
|
|
217
|
+
function blockDelegationVerdict(rawReasonKind) {
|
|
218
|
+
return { kind: "Block", reason: { kind: toCoarseReasonKind(rawReasonKind) } };
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
// src/test-fixtures/verdict-evidence-fixture.ts
|
|
222
|
+
function detectionSignalFixture(overrides = {}) {
|
|
223
|
+
return {
|
|
224
|
+
signalType: "pattern",
|
|
225
|
+
confidence: 80,
|
|
226
|
+
weight: 0.4,
|
|
227
|
+
source: "tier3_ua_pattern",
|
|
228
|
+
explanation: "Matches a known agent UA pattern",
|
|
229
|
+
...overrides
|
|
230
|
+
};
|
|
231
|
+
}
|
|
232
|
+
var TWO_SIGNAL_EVIDENCE_FIXTURE = [
|
|
233
|
+
detectionSignalFixture({
|
|
234
|
+
source: "known_scraper_ua",
|
|
235
|
+
signalType: "pattern",
|
|
236
|
+
weight: 1,
|
|
237
|
+
confidence: 90
|
|
238
|
+
}),
|
|
239
|
+
detectionSignalFixture({
|
|
240
|
+
source: "datacenter_ip",
|
|
241
|
+
signalType: "network",
|
|
242
|
+
weight: 0.6,
|
|
243
|
+
confidence: 70
|
|
244
|
+
})
|
|
245
|
+
];
|
|
246
|
+
var TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE = 94.78;
|
|
247
|
+
|
|
248
|
+
export { FETCHER_200_PREDICATE_VECTORS, MCPI_DELEGATION_AGENT_DID, MCPI_DELEGATION_AUDIENCE, MCPI_DELEGATION_CANONICAL_PAYLOAD, MCPI_DELEGATION_EXPECTED_HEADER, MCPI_DELEGATION_EXPECTED_JWT, MCPI_DELEGATION_ISSUER_DID, MCPI_DELEGATION_ISSUER_KID, MCPI_DELEGATION_STATUS_LIST_URL, MCPI_DELEGATION_TEST_KEYPAIR, MCPI_DELEGATION_USER_DID, TWO_SIGNAL_EVIDENCE_EXPECTED_CONFIDENCE, TWO_SIGNAL_EVIDENCE_FIXTURE, VAULT_WIRE_CONTRACT_CANONICAL_PAYLOAD, VAULT_WIRE_CONTRACT_EXPECTED_HEADER, VAULT_WIRE_CONTRACT_EXPECTED_JWT, VAULT_WIRE_CONTRACT_EXPECTED_REQUEST_BODY, VAULT_WIRE_CONTRACT_TEST_KEYPAIR, VAULT_WIRE_CONTRACT_URL_PATH, blockDelegationVerdict, detectionSignalFixture, permitDelegationVerdict, toCoarseReasonKind };
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
[
|
|
2
|
+
{
|
|
3
|
+
"name": "vercel platform header wins over caller-set headers",
|
|
4
|
+
"headers": {
|
|
5
|
+
"x-vercel-forwarded-for": "203.0.113.9",
|
|
6
|
+
"x-forwarded-for": "6.6.6.6",
|
|
7
|
+
"x-real-ip": "198.51.100.4"
|
|
8
|
+
},
|
|
9
|
+
"policy": { "platform": "vercel" },
|
|
10
|
+
"expected": { "ip": "203.0.113.9", "source": "x-vercel-forwarded-for", "trusted": true }
|
|
11
|
+
},
|
|
12
|
+
{
|
|
13
|
+
"name": "vercel uses its overwritten XFF when the platform-specific header is absent",
|
|
14
|
+
"headers": { "x-forwarded-for": "203.0.113.10, 192.0.2.4" },
|
|
15
|
+
"policy": { "platform": "vercel" },
|
|
16
|
+
"expected": { "ip": "203.0.113.10", "source": "x-forwarded-for", "trusted": true }
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
"name": "vercel marks X-Real-IP observational when platform values are absent",
|
|
20
|
+
"headers": { "x-real-ip": "198.51.100.4" },
|
|
21
|
+
"policy": { "platform": "vercel" },
|
|
22
|
+
"expected": { "ip": "198.51.100.4", "source": "x-real-ip", "trusted": false }
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
"name": "cloudflare CF-Connecting-IP wins and ignores spoofed XFF",
|
|
26
|
+
"headers": { "cf-connecting-ip": "203.0.113.11", "x-forwarded-for": "6.6.6.6" },
|
|
27
|
+
"policy": { "platform": "cloudflare" },
|
|
28
|
+
"expected": { "ip": "203.0.113.11", "source": "cf-connecting-ip", "trusted": true }
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
"name": "cloudflare falls back to the worker socket",
|
|
32
|
+
"headers": { "x-forwarded-for": "6.6.6.6" },
|
|
33
|
+
"directAddress": "192.0.2.10",
|
|
34
|
+
"policy": { "platform": "cloudflare" },
|
|
35
|
+
"expected": { "ip": "192.0.2.10", "source": "socket", "trusted": true }
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
"name": "cloudflare observational fallback is untrusted",
|
|
39
|
+
"headers": { "x-forwarded-for": "6.6.6.6" },
|
|
40
|
+
"policy": { "platform": "cloudflare" },
|
|
41
|
+
"expected": { "ip": "6.6.6.6", "source": "x-forwarded-for", "trusted": false }
|
|
42
|
+
},
|
|
43
|
+
{
|
|
44
|
+
"name": "trusted proxy selects the first untrusted hop from the trusted side",
|
|
45
|
+
"headers": { "x-forwarded-for": "203.0.113.12, 198.51.100.10, 192.0.2.10" },
|
|
46
|
+
"policy": { "platform": "trusted-proxy", "trustedHops": 2 },
|
|
47
|
+
"expected": { "ip": "203.0.113.12", "source": "x-forwarded-for", "trusted": true }
|
|
48
|
+
},
|
|
49
|
+
{
|
|
50
|
+
"name": "trusted proxy does not shift around an invalid token",
|
|
51
|
+
"headers": { "x-forwarded-for": "203.0.113.13, invalid, 192.0.2.10" },
|
|
52
|
+
"frameworkAddress": "192.0.2.20",
|
|
53
|
+
"policy": { "platform": "trusted-proxy", "trustedHops": 2 },
|
|
54
|
+
"expected": { "ip": "192.0.2.20", "source": "framework", "trusted": true }
|
|
55
|
+
},
|
|
56
|
+
{
|
|
57
|
+
"name": "direct ignores all forwarding headers",
|
|
58
|
+
"headers": { "x-forwarded-for": "6.6.6.6", "cf-connecting-ip": "203.0.113.14" },
|
|
59
|
+
"directAddress": "192.0.2.30",
|
|
60
|
+
"policy": { "platform": "direct" },
|
|
61
|
+
"expected": { "ip": "192.0.2.30", "source": "socket", "trusted": true }
|
|
62
|
+
},
|
|
63
|
+
{
|
|
64
|
+
"name": "authenticated explicit address wins",
|
|
65
|
+
"headers": { "x-forwarded-for": "6.6.6.6" },
|
|
66
|
+
"explicitAddress": "[2001:db8::1]:443",
|
|
67
|
+
"explicitAddressTrusted": true,
|
|
68
|
+
"policy": { "platform": "direct" },
|
|
69
|
+
"expected": { "ip": "2001:db8::1", "source": "explicit", "trusted": true }
|
|
70
|
+
},
|
|
71
|
+
{
|
|
72
|
+
"name": "unauthenticated explicit address is not honored",
|
|
73
|
+
"headers": {},
|
|
74
|
+
"explicitAddress": "203.0.113.15",
|
|
75
|
+
"policy": { "platform": "direct" },
|
|
76
|
+
"expected": { "ip": null, "source": "none", "trusted": false }
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
"name": "IPv4 port is removed",
|
|
80
|
+
"headers": { "x-real-ip": " 203.0.113.16:8443 " },
|
|
81
|
+
"policy": { "platform": "direct" },
|
|
82
|
+
"expected": { "ip": null, "source": "none", "trusted": false }
|
|
83
|
+
},
|
|
84
|
+
{
|
|
85
|
+
"name": "IPv6 is compressed and unbracketed",
|
|
86
|
+
"headers": { "x-real-ip": "[2001:0db8:0:0:0:0:0:1]:443" },
|
|
87
|
+
"frameworkAddress": "2001:db8::2",
|
|
88
|
+
"policy": { "platform": "vercel" },
|
|
89
|
+
"expected": { "ip": "2001:db8::1", "source": "x-real-ip", "trusted": false }
|
|
90
|
+
},
|
|
91
|
+
{
|
|
92
|
+
"name": "IPv4-mapped IPv6 is normalized",
|
|
93
|
+
"headers": { "x-real-ip": "::ffff:192.0.2.1" },
|
|
94
|
+
"policy": { "platform": "vercel" },
|
|
95
|
+
"expected": { "ip": "::ffff:c000:201", "source": "x-real-ip", "trusted": false }
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
"name": "control characters are rejected",
|
|
99
|
+
"headers": { "x-real-ip": "203.0.113.17\r\nX-Admin: true" },
|
|
100
|
+
"policy": { "platform": "vercel" },
|
|
101
|
+
"expected": { "ip": null, "source": "none", "trusted": false }
|
|
102
|
+
}
|
|
103
|
+
]
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$fixture": "detection/reason-codes",
|
|
3
|
+
"$spec": "GODPROMPTS/detection-reason-codes — detection reason codes on the wire",
|
|
4
|
+
"description": "The detection/* reason-code registry: a worker-side machine-readable projection of the engine's structured detection evidence (signals[], verificationMethod, detectionClass, isAiCrawler) onto the KYA-Reason-Codes wire header and persisted detection metadata. Emitters MUST use these exact strings.",
|
|
5
|
+
"verified": {
|
|
6
|
+
"detection/signature-verified": "verificationMethod === 'kya-http'",
|
|
7
|
+
"detection/delegation-verified": "verificationMethod === 'kya-http-delegated'",
|
|
8
|
+
"detection/mcp-i-verified": "verificationMethod === 'mcp-i' | 'kya-os' (wire values; isKyaOsWireMethod)",
|
|
9
|
+
"detection/did-signature-verified": "verificationMethod === 'did'",
|
|
10
|
+
"detection/rfc9421-signature-verified": "verificationMethod === 'signature'",
|
|
11
|
+
"detection/tier1-attribution-verified": "verificationMethod starts with 'tier1_'",
|
|
12
|
+
"detection/verification-error": "verificationMethod === 'error'"
|
|
13
|
+
},
|
|
14
|
+
"signal": {
|
|
15
|
+
"detection/ua-pattern-match": "a signals[] entry with source === 'user_agent_pattern'",
|
|
16
|
+
"detection/header-heuristic": "source === 'header_heuristic'",
|
|
17
|
+
"detection/ip-heuristic": "source === 'ip_heuristic'",
|
|
18
|
+
"detection/vendor-ip-corroborated": "source === 'vendor_ip_feed'",
|
|
19
|
+
"detection/ja4-fingerprint-match": "source === 'transport.ja4'",
|
|
20
|
+
"detection/client-attribute-signal": "source === 'client.attributes'",
|
|
21
|
+
"detection/behavioral-signal": "source === 'behavioural.interaction'",
|
|
22
|
+
"detection/mcp-i-signal": "source === 'mcp_i'",
|
|
23
|
+
"detection/kya-http-binding-signal": "source === 'kya_http_binding'",
|
|
24
|
+
"detection/kya-delegation-bearer-signal": "source === 'kya_delegation_bearer'",
|
|
25
|
+
"detection/tier1-attribution-signal": "a signals[] entry whose source starts with 'tier1_'"
|
|
26
|
+
},
|
|
27
|
+
"flag": {
|
|
28
|
+
"detection/ai-crawler-flag": "isAiCrawler === true"
|
|
29
|
+
},
|
|
30
|
+
"fallback": {
|
|
31
|
+
"detection/zero-evidence-human": "detectionClass === 'human' with no contributing signals and no verification",
|
|
32
|
+
"detection/incomplete-data-override": "detectionClass === 'incomplete_data' | 'unknown' (or absent)",
|
|
33
|
+
"detection/classified-without-signal-evidence": "a non-human, non-incomplete-data class reached with zero contributing signals and no verification"
|
|
34
|
+
}
|
|
35
|
+
}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$fixture": "detection/signal-exposure-example",
|
|
3
|
+
"$spec": "KYA-1107: one full POST /api/v1/enforce response showing the always-on signal exposure (the Adobe Golden Snapshot example). Captured verbatim from the route-level test (signal-exposure.test.ts) against the deterministic GPTBot engine mock, whose signals mirror the engine's real emission shapes (api.rs signal_detail / vendor_feed_signal_detail).",
|
|
4
|
+
"description": "The detection object's signals/reasonCodes/confidenceLevel/isAiCrawler fields are the exposure block carried on every detection payload; __tests__/signal-exposure.test.ts parses them against DetectionSignalExposureSchema, and generate-signal-exposure-docs.ts embeds this response verbatim in the generated reference, so example, schema, and docs stay in lockstep.",
|
|
5
|
+
"response": {
|
|
6
|
+
"success": true,
|
|
7
|
+
"data": {
|
|
8
|
+
"decision": {
|
|
9
|
+
"action": "allow",
|
|
10
|
+
"reason": "enforcement_disabled",
|
|
11
|
+
"isAgent": true,
|
|
12
|
+
"confidence": 96
|
|
13
|
+
},
|
|
14
|
+
"processingTimeMs": 0,
|
|
15
|
+
"requestId": "req_golden_1",
|
|
16
|
+
"detection": {
|
|
17
|
+
"isAgent": true,
|
|
18
|
+
"confidence": 96,
|
|
19
|
+
"detectionClass": "bot",
|
|
20
|
+
"agentName": "GPTBot",
|
|
21
|
+
"agentType": "GPTBot",
|
|
22
|
+
"verificationMethod": "pattern",
|
|
23
|
+
"reasons": ["Tier3UAMatch"],
|
|
24
|
+
"signals": [
|
|
25
|
+
{
|
|
26
|
+
"signalType": "pattern",
|
|
27
|
+
"confidence": 96,
|
|
28
|
+
"weight": 1,
|
|
29
|
+
"source": "user_agent_pattern",
|
|
30
|
+
"explanation": "User-Agent matched known agent pattern: GPTBot"
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
"signalType": "pattern",
|
|
34
|
+
"confidence": 60,
|
|
35
|
+
"weight": 0.4,
|
|
36
|
+
"source": "header_heuristic",
|
|
37
|
+
"explanation": "Header heuristic fired: missing_accept_language"
|
|
38
|
+
},
|
|
39
|
+
{
|
|
40
|
+
"signalType": "network",
|
|
41
|
+
"confidence": 92,
|
|
42
|
+
"weight": 1,
|
|
43
|
+
"source": "vendor_ip_feed",
|
|
44
|
+
"explanation": "Vendor IP + User-Agent cross-match: OpenAI",
|
|
45
|
+
"metadata": {
|
|
46
|
+
"vendor_id": "openai",
|
|
47
|
+
"tier": 2
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
],
|
|
51
|
+
"reasonCodes": [
|
|
52
|
+
"detection/ua-pattern-match",
|
|
53
|
+
"detection/header-heuristic",
|
|
54
|
+
"detection/vendor-ip-corroborated",
|
|
55
|
+
"detection/ai-crawler-flag"
|
|
56
|
+
],
|
|
57
|
+
"confidenceLevel": "very_high",
|
|
58
|
+
"isAiCrawler": true
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|