@marinoscar/vault-contract 0.1.0-next.3 → 0.1.0-next.4
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 +16 -0
- package/README.md +17 -5
- package/dist/cjs/agent/cards-identity.d.ts +456 -0
- package/dist/cjs/agent/cards-identity.js +272 -0
- package/dist/cjs/agent/contract-version.d.ts +58 -0
- package/dist/cjs/agent/contract-version.js +58 -0
- package/dist/cjs/agent/index.d.ts +196 -54
- package/dist/cjs/agent/index.js +176 -37
- package/dist/cjs/agent-testing/canary.d.ts +57 -0
- package/dist/cjs/agent-testing/canary.js +165 -0
- package/dist/cjs/agent-testing/fake-vault.d.ts +111 -0
- package/dist/cjs/agent-testing/fake-vault.js +707 -0
- package/dist/cjs/agent-testing/guard.d.ts +16 -0
- package/dist/cjs/agent-testing/guard.js +28 -0
- package/dist/cjs/agent-testing/index.d.ts +28 -0
- package/dist/cjs/agent-testing/index.js +43 -0
- package/dist/cjs/agent-testing/recorder.d.ts +70 -0
- package/dist/cjs/agent-testing/recorder.js +127 -0
- package/dist/cjs/agent-testing/reference-runtime.d.ts +8 -0
- package/dist/cjs/agent-testing/reference-runtime.js +112 -0
- package/dist/cjs/agent-testing/scenarios.d.ts +128 -0
- package/dist/cjs/agent-testing/scenarios.js +566 -0
- package/dist/cjs/agent-testing/seed.d.ts +84 -0
- package/dist/cjs/agent-testing/seed.js +89 -0
- package/dist/cjs/agent-testing/totp.d.ts +10 -0
- package/dist/cjs/agent-testing/totp.js +45 -0
- package/dist/cjs/errors/index.js +13 -1
- package/dist/cjs/media/index.d.ts +2 -2
- package/dist/cjs/secret-types/index.d.ts +4 -0
- package/dist/cjs/secret-types/index.js +29 -1
- package/dist/cjs/secrets/index.d.ts +13 -3
- package/dist/cjs/secrets/index.js +14 -3
- package/dist/esm/agent/cards-identity.d.ts +456 -0
- package/dist/esm/agent/cards-identity.js +266 -0
- package/dist/esm/agent/contract-version.d.ts +58 -0
- package/dist/esm/agent/contract-version.js +54 -0
- package/dist/esm/agent/index.d.ts +196 -54
- package/dist/esm/agent/index.js +160 -36
- package/dist/esm/agent-testing/canary.d.ts +57 -0
- package/dist/esm/agent-testing/canary.js +157 -0
- package/dist/esm/agent-testing/fake-vault.d.ts +111 -0
- package/dist/esm/agent-testing/fake-vault.js +704 -0
- package/dist/esm/agent-testing/guard.d.ts +16 -0
- package/dist/esm/agent-testing/guard.js +23 -0
- package/dist/esm/agent-testing/index.d.ts +28 -0
- package/dist/esm/agent-testing/index.js +27 -0
- package/dist/esm/agent-testing/recorder.d.ts +70 -0
- package/dist/esm/agent-testing/recorder.js +122 -0
- package/dist/esm/agent-testing/reference-runtime.d.ts +8 -0
- package/dist/esm/agent-testing/reference-runtime.js +109 -0
- package/dist/esm/agent-testing/scenarios.d.ts +128 -0
- package/dist/esm/agent-testing/scenarios.js +560 -0
- package/dist/esm/agent-testing/seed.d.ts +84 -0
- package/dist/esm/agent-testing/seed.js +85 -0
- package/dist/esm/agent-testing/totp.d.ts +10 -0
- package/dist/esm/agent-testing/totp.js +42 -0
- package/dist/esm/errors/index.js +13 -1
- package/dist/esm/media/index.d.ts +2 -2
- package/dist/esm/secret-types/index.d.ts +4 -0
- package/dist/esm/secret-types/index.js +28 -0
- package/dist/esm/secrets/index.d.ts +13 -3
- package/dist/esm/secrets/index.js +13 -2
- package/package.json +11 -1
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The production guard of the conformance kit: every part that holds seeded values or serves HTTP
|
|
3
|
+
* refuses to run when `NODE_ENV` is `production`. The kit is for a runtime's tests, never a store.
|
|
4
|
+
*/
|
|
5
|
+
/** Thrown when a kit part is started with `NODE_ENV=production`. @stability beta */
|
|
6
|
+
export declare class ConformanceKitInProductionError extends Error {
|
|
7
|
+
constructor(what: string);
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Throws {@link ConformanceKitInProductionError} when `NODE_ENV` is `production`. `env` defaults to
|
|
11
|
+
* the process environment: this is the one place the packages read it, and only to refuse to run
|
|
12
|
+
* (a safety stop, never configuration).
|
|
13
|
+
*
|
|
14
|
+
* @stability beta
|
|
15
|
+
*/
|
|
16
|
+
export declare function assertNotProduction(what: string, env?: Record<string, string | undefined>): void;
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* The production guard of the conformance kit: every part that holds seeded values or serves HTTP
|
|
4
|
+
* refuses to run when `NODE_ENV` is `production`. The kit is for a runtime's tests, never a store.
|
|
5
|
+
*/
|
|
6
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
7
|
+
exports.ConformanceKitInProductionError = void 0;
|
|
8
|
+
exports.assertNotProduction = assertNotProduction;
|
|
9
|
+
/** Thrown when a kit part is started with `NODE_ENV=production`. @stability beta */
|
|
10
|
+
class ConformanceKitInProductionError extends Error {
|
|
11
|
+
constructor(what) {
|
|
12
|
+
super(`${what} is a test tool and refuses to run with NODE_ENV=production`);
|
|
13
|
+
this.name = 'ConformanceKitInProductionError';
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
exports.ConformanceKitInProductionError = ConformanceKitInProductionError;
|
|
17
|
+
/**
|
|
18
|
+
* Throws {@link ConformanceKitInProductionError} when `NODE_ENV` is `production`. `env` defaults to
|
|
19
|
+
* the process environment: this is the one place the packages read it, and only to refuse to run
|
|
20
|
+
* (a safety stop, never configuration).
|
|
21
|
+
*
|
|
22
|
+
* @stability beta
|
|
23
|
+
*/
|
|
24
|
+
function assertNotProduction(what, env) {
|
|
25
|
+
const source = env ?? process.env;
|
|
26
|
+
if ((source.NODE_ENV ?? '').trim().toLowerCase() === 'production')
|
|
27
|
+
throw new ConformanceKitInProductionError(what);
|
|
28
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The conformance kit of the agent contract (`@marinoscar/vault-contract/agent-testing`, issue
|
|
3
|
+
* #196), for the tests of an agent runtime that types Vault logins:
|
|
4
|
+
*
|
|
5
|
+
* - {@link createFakeVault}: a small in-memory `/api/agent/v1` built from the contract schemas,
|
|
6
|
+
* seeded with invented data, refusing to start with `NODE_ENV=production`. Not a secrets store.
|
|
7
|
+
* - {@link seedCanaries}, {@link assertNoCanary}, {@link findCanaries}: canary values and the scan
|
|
8
|
+
* of a runtime's logs, traces, transcripts, screenshots and files.
|
|
9
|
+
* - {@link AGENT_CONFORMANCE_SCENARIOS} (the list as data) and {@link runAgentConformance} /
|
|
10
|
+
* {@link assertAgentConformance}: the scenario suite, called with the runtime's own
|
|
11
|
+
* "sign in to this page" function.
|
|
12
|
+
* - {@link createReferenceSignIn}: a minimal runtime that passes the suite, as a worked example.
|
|
13
|
+
*
|
|
14
|
+
* Node only (it uses `node:http`, `node:crypto`, `node:fs`); no test framework at run time. Passing
|
|
15
|
+
* the kit shows the runtime follows the guide's rules against a Vault that behaves like Vault; it
|
|
16
|
+
* does not prove the runtime keeps values out of places the kit cannot see (see the README).
|
|
17
|
+
*
|
|
18
|
+
* @stability beta
|
|
19
|
+
* @packageDocumentation
|
|
20
|
+
*/
|
|
21
|
+
export * from './guard.js';
|
|
22
|
+
export * from './canary.js';
|
|
23
|
+
export * from './seed.js';
|
|
24
|
+
export * from './totp.js';
|
|
25
|
+
export * from './fake-vault.js';
|
|
26
|
+
export * from './scenarios.js';
|
|
27
|
+
export * from './reference-runtime.js';
|
|
28
|
+
export type { ConformanceEvent } from './recorder.js';
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* The conformance kit of the agent contract (`@marinoscar/vault-contract/agent-testing`, issue
|
|
4
|
+
* #196), for the tests of an agent runtime that types Vault logins:
|
|
5
|
+
*
|
|
6
|
+
* - {@link createFakeVault}: a small in-memory `/api/agent/v1` built from the contract schemas,
|
|
7
|
+
* seeded with invented data, refusing to start with `NODE_ENV=production`. Not a secrets store.
|
|
8
|
+
* - {@link seedCanaries}, {@link assertNoCanary}, {@link findCanaries}: canary values and the scan
|
|
9
|
+
* of a runtime's logs, traces, transcripts, screenshots and files.
|
|
10
|
+
* - {@link AGENT_CONFORMANCE_SCENARIOS} (the list as data) and {@link runAgentConformance} /
|
|
11
|
+
* {@link assertAgentConformance}: the scenario suite, called with the runtime's own
|
|
12
|
+
* "sign in to this page" function.
|
|
13
|
+
* - {@link createReferenceSignIn}: a minimal runtime that passes the suite, as a worked example.
|
|
14
|
+
*
|
|
15
|
+
* Node only (it uses `node:http`, `node:crypto`, `node:fs`); no test framework at run time. Passing
|
|
16
|
+
* the kit shows the runtime follows the guide's rules against a Vault that behaves like Vault; it
|
|
17
|
+
* does not prove the runtime keeps values out of places the kit cannot see (see the README).
|
|
18
|
+
*
|
|
19
|
+
* @stability beta
|
|
20
|
+
* @packageDocumentation
|
|
21
|
+
*/
|
|
22
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
23
|
+
if (k2 === undefined) k2 = k;
|
|
24
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
25
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
26
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
27
|
+
}
|
|
28
|
+
Object.defineProperty(o, k2, desc);
|
|
29
|
+
}) : (function(o, m, k, k2) {
|
|
30
|
+
if (k2 === undefined) k2 = k;
|
|
31
|
+
o[k2] = m[k];
|
|
32
|
+
}));
|
|
33
|
+
var __exportStar = (this && this.__exportStar) || function(m, exports) {
|
|
34
|
+
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
|
|
35
|
+
};
|
|
36
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
37
|
+
__exportStar(require("./guard.js"), exports);
|
|
38
|
+
__exportStar(require("./canary.js"), exports);
|
|
39
|
+
__exportStar(require("./seed.js"), exports);
|
|
40
|
+
__exportStar(require("./totp.js"), exports);
|
|
41
|
+
__exportStar(require("./fake-vault.js"), exports);
|
|
42
|
+
__exportStar(require("./scenarios.js"), exports);
|
|
43
|
+
__exportStar(require("./reference-runtime.js"), exports);
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A recording reverse proxy in front of the Vault under test: the runtime talks to it, it talks to
|
|
3
|
+
* the Vault. It sees the same traffic whether the Vault is the fake or a real deployment, which is
|
|
4
|
+
* what lets one scenario list check both. Bodies are held in memory for the run only.
|
|
5
|
+
*/
|
|
6
|
+
/** One event of a scenario, in order. @stability beta */
|
|
7
|
+
export type ConformanceEvent = {
|
|
8
|
+
kind: 'request';
|
|
9
|
+
seq: number;
|
|
10
|
+
at: number;
|
|
11
|
+
method: string;
|
|
12
|
+
/** Path under the Vault, without the query. */
|
|
13
|
+
path: string;
|
|
14
|
+
query: Record<string, string>;
|
|
15
|
+
body: unknown;
|
|
16
|
+
/** The page's top-level origin when the request was sent. */
|
|
17
|
+
pageOrigin: string | null;
|
|
18
|
+
} | {
|
|
19
|
+
kind: 'response';
|
|
20
|
+
seq: number;
|
|
21
|
+
at: number;
|
|
22
|
+
requestSeq: number;
|
|
23
|
+
method: string;
|
|
24
|
+
path: string;
|
|
25
|
+
status: number;
|
|
26
|
+
code?: string;
|
|
27
|
+
headers: Record<string, string>;
|
|
28
|
+
body: unknown;
|
|
29
|
+
} | {
|
|
30
|
+
kind: 'type';
|
|
31
|
+
seq: number;
|
|
32
|
+
at: number;
|
|
33
|
+
field: string;
|
|
34
|
+
value: string;
|
|
35
|
+
pageOrigin: string;
|
|
36
|
+
} | {
|
|
37
|
+
kind: 'ask';
|
|
38
|
+
seq: number;
|
|
39
|
+
at: number;
|
|
40
|
+
choices: number;
|
|
41
|
+
answer: string | null;
|
|
42
|
+
} | {
|
|
43
|
+
kind: 'connect';
|
|
44
|
+
seq: number;
|
|
45
|
+
at: number;
|
|
46
|
+
};
|
|
47
|
+
/** An event before the log stamps it. */
|
|
48
|
+
type WithoutStamp<E> = E extends unknown ? Omit<E, 'seq' | 'at'> : never;
|
|
49
|
+
/** The shared event log of a run. */
|
|
50
|
+
export declare class ConformanceLog {
|
|
51
|
+
private seqCounter;
|
|
52
|
+
events: ConformanceEvent[];
|
|
53
|
+
push<E extends ConformanceEvent = ConformanceEvent>(event: WithoutStamp<E>): E;
|
|
54
|
+
/** Forgets every event (and with them every value seen). */
|
|
55
|
+
clear(): void;
|
|
56
|
+
}
|
|
57
|
+
/** A started recorder. */
|
|
58
|
+
export interface ConformanceRecorder {
|
|
59
|
+
baseUrl: string;
|
|
60
|
+
/** Called with each response before it reaches the runtime. */
|
|
61
|
+
onResponse: ((event: Extract<ConformanceEvent, {
|
|
62
|
+
kind: 'response';
|
|
63
|
+
}>) => void) | null;
|
|
64
|
+
/** Reads the page origin to stamp on a request. */
|
|
65
|
+
pageOrigin: () => string | null;
|
|
66
|
+
stop(): Promise<void>;
|
|
67
|
+
}
|
|
68
|
+
/** Starts a recorder in front of `targetBaseUrl` on 127.0.0.1. */
|
|
69
|
+
export declare function startRecorder(targetBaseUrl: string, log: ConformanceLog): Promise<ConformanceRecorder>;
|
|
70
|
+
export {};
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.ConformanceLog = void 0;
|
|
4
|
+
exports.startRecorder = startRecorder;
|
|
5
|
+
const node_http_1 = require("node:http");
|
|
6
|
+
const node_https_1 = require("node:https");
|
|
7
|
+
/** The shared event log of a run. */
|
|
8
|
+
class ConformanceLog {
|
|
9
|
+
seqCounter = 0;
|
|
10
|
+
events = [];
|
|
11
|
+
push(event) {
|
|
12
|
+
const full = { ...event, seq: ++this.seqCounter, at: Date.now() };
|
|
13
|
+
this.events.push(full);
|
|
14
|
+
return full;
|
|
15
|
+
}
|
|
16
|
+
/** Forgets every event (and with them every value seen). */
|
|
17
|
+
clear() {
|
|
18
|
+
this.events = [];
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
exports.ConformanceLog = ConformanceLog;
|
|
22
|
+
const SAFE_HEADERS = ['cache-control', 'pragma', 'retry-after', 'www-authenticate', 'content-type'];
|
|
23
|
+
function parseJson(text) {
|
|
24
|
+
if (!text)
|
|
25
|
+
return undefined;
|
|
26
|
+
try {
|
|
27
|
+
return JSON.parse(text);
|
|
28
|
+
}
|
|
29
|
+
catch {
|
|
30
|
+
return text;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
/** Starts a recorder in front of `targetBaseUrl` on 127.0.0.1. */
|
|
34
|
+
async function startRecorder(targetBaseUrl, log) {
|
|
35
|
+
const target = new URL(targetBaseUrl);
|
|
36
|
+
const send = target.protocol === 'https:' ? node_https_1.request : node_http_1.request;
|
|
37
|
+
const recorder = {
|
|
38
|
+
baseUrl: '',
|
|
39
|
+
onResponse: null,
|
|
40
|
+
pageOrigin: () => null,
|
|
41
|
+
stop: async () => undefined,
|
|
42
|
+
};
|
|
43
|
+
const handle = (req, res) => {
|
|
44
|
+
const chunks = [];
|
|
45
|
+
req.on('data', (c) => chunks.push(c));
|
|
46
|
+
req.on('end', () => {
|
|
47
|
+
const raw = Buffer.concat(chunks);
|
|
48
|
+
const url = new URL(req.url ?? '/', 'http://recorder.invalid');
|
|
49
|
+
const requestEvent = log.push({
|
|
50
|
+
kind: 'request',
|
|
51
|
+
method: (req.method ?? 'GET').toUpperCase(),
|
|
52
|
+
path: url.pathname,
|
|
53
|
+
query: Object.fromEntries(url.searchParams),
|
|
54
|
+
body: parseJson(raw.toString('utf8')),
|
|
55
|
+
pageOrigin: recorder.pageOrigin(),
|
|
56
|
+
});
|
|
57
|
+
const headers = { ...req.headers, host: target.host };
|
|
58
|
+
delete headers['content-length'];
|
|
59
|
+
const upstream = send({
|
|
60
|
+
protocol: target.protocol,
|
|
61
|
+
hostname: target.hostname,
|
|
62
|
+
port: target.port,
|
|
63
|
+
method: req.method,
|
|
64
|
+
path: `${target.pathname.replace(/\/+$/, '')}${req.url ?? '/'}`,
|
|
65
|
+
headers: { ...headers, ...(raw.length > 0 ? { 'content-length': String(raw.length) } : {}) },
|
|
66
|
+
}, (up) => {
|
|
67
|
+
const body = [];
|
|
68
|
+
up.on('data', (c) => body.push(c));
|
|
69
|
+
up.on('end', () => {
|
|
70
|
+
const text = Buffer.concat(body);
|
|
71
|
+
const kept = {};
|
|
72
|
+
for (const name of SAFE_HEADERS) {
|
|
73
|
+
const value = up.headers[name];
|
|
74
|
+
if (value !== undefined)
|
|
75
|
+
kept[name] = Array.isArray(value) ? value.join(', ') : String(value);
|
|
76
|
+
}
|
|
77
|
+
const parsed = parseJson(text.toString('utf8'));
|
|
78
|
+
const code = parsed && typeof parsed === 'object' && typeof parsed.code === 'string'
|
|
79
|
+
? parsed.code
|
|
80
|
+
: undefined;
|
|
81
|
+
const responseEvent = log.push({
|
|
82
|
+
kind: 'response',
|
|
83
|
+
requestSeq: requestEvent.seq,
|
|
84
|
+
method: requestEvent.method,
|
|
85
|
+
path: requestEvent.path,
|
|
86
|
+
status: up.statusCode ?? 0,
|
|
87
|
+
...(code ? { code } : {}),
|
|
88
|
+
headers: kept,
|
|
89
|
+
body: parsed,
|
|
90
|
+
});
|
|
91
|
+
try {
|
|
92
|
+
recorder.onResponse?.(responseEvent);
|
|
93
|
+
}
|
|
94
|
+
catch {
|
|
95
|
+
// A scenario hook never breaks the transport.
|
|
96
|
+
}
|
|
97
|
+
const out = {};
|
|
98
|
+
for (const [name, value] of Object.entries(up.headers)) {
|
|
99
|
+
if (value !== undefined && name !== 'transfer-encoding' && name !== 'connection')
|
|
100
|
+
out[name] = value;
|
|
101
|
+
}
|
|
102
|
+
out['content-length'] = String(text.length);
|
|
103
|
+
res.writeHead(up.statusCode ?? 502, out);
|
|
104
|
+
res.end(text);
|
|
105
|
+
});
|
|
106
|
+
});
|
|
107
|
+
upstream.on('error', () => {
|
|
108
|
+
if (!res.headersSent)
|
|
109
|
+
res.writeHead(502, { 'content-type': 'application/json' });
|
|
110
|
+
res.end(JSON.stringify({ message: 'The Vault under test did not answer' }));
|
|
111
|
+
});
|
|
112
|
+
upstream.end(raw);
|
|
113
|
+
});
|
|
114
|
+
};
|
|
115
|
+
const server = (0, node_http_1.createServer)(handle);
|
|
116
|
+
await new Promise((resolve, reject) => {
|
|
117
|
+
server.once('error', reject);
|
|
118
|
+
server.listen(0, '127.0.0.1', () => resolve());
|
|
119
|
+
});
|
|
120
|
+
const port = server.address().port;
|
|
121
|
+
recorder.baseUrl = `http://127.0.0.1:${port}`;
|
|
122
|
+
recorder.stop = async () => {
|
|
123
|
+
server.closeAllConnections?.();
|
|
124
|
+
await new Promise((resolve) => server.close(() => resolve()));
|
|
125
|
+
};
|
|
126
|
+
return recorder;
|
|
127
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { ConformanceSignIn } from './scenarios.js';
|
|
2
|
+
/**
|
|
3
|
+
* The reference runtime's `signIn`. It keeps one access token between pages (tokens are not
|
|
4
|
+
* values), and nothing else: every page starts with a fresh lookup.
|
|
5
|
+
*
|
|
6
|
+
* @stability beta
|
|
7
|
+
*/
|
|
8
|
+
export declare function createReferenceSignIn(): ConformanceSignIn;
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.createReferenceSignIn = createReferenceSignIn;
|
|
4
|
+
/**
|
|
5
|
+
* A minimal runtime that follows the guide (`docs/agent-credential-api.md`, sections 4 and 5). Vault
|
|
6
|
+
* runs the scenario list with it against the fake and against the real API; a runtime author can
|
|
7
|
+
* read it as a worked example. It is not a product: no browser, no model, one page at a time.
|
|
8
|
+
*/
|
|
9
|
+
/** Thrown inside the reference runtime to end a sign-in with a result. */
|
|
10
|
+
class Stop extends Error {
|
|
11
|
+
result;
|
|
12
|
+
constructor(result) {
|
|
13
|
+
super(result.status);
|
|
14
|
+
this.result = result;
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
18
|
+
/**
|
|
19
|
+
* The reference runtime's `signIn`. It keeps one access token between pages (tokens are not
|
|
20
|
+
* values), and nothing else: every page starts with a fresh lookup.
|
|
21
|
+
*
|
|
22
|
+
* @stability beta
|
|
23
|
+
*/
|
|
24
|
+
function createReferenceSignIn() {
|
|
25
|
+
let tokens = null;
|
|
26
|
+
return async (page, vault) => {
|
|
27
|
+
/** One agent API call: reconnects once on 401, waits out a 429, stops on any other refusal. */
|
|
28
|
+
const call = async (method, path, body) => {
|
|
29
|
+
let reconnected = false;
|
|
30
|
+
for (let attempt = 0; attempt < 4; attempt += 1) {
|
|
31
|
+
if (!tokens)
|
|
32
|
+
tokens = await vault.connect();
|
|
33
|
+
const res = await fetch(`${vault.apiBaseUrl}${path}`, {
|
|
34
|
+
method,
|
|
35
|
+
headers: {
|
|
36
|
+
authorization: `Bearer ${tokens.accessToken}`,
|
|
37
|
+
...(body !== undefined ? { 'content-type': 'application/json' } : {}),
|
|
38
|
+
},
|
|
39
|
+
...(body !== undefined ? { body: JSON.stringify(body) } : {}),
|
|
40
|
+
});
|
|
41
|
+
const json = (await res.json().catch(() => ({})));
|
|
42
|
+
if (res.ok)
|
|
43
|
+
return json.data;
|
|
44
|
+
if (res.status === 401 && !reconnected) {
|
|
45
|
+
// A revoked grant: the person reconnects once. Never retry the dead token.
|
|
46
|
+
tokens = null;
|
|
47
|
+
reconnected = true;
|
|
48
|
+
continue;
|
|
49
|
+
}
|
|
50
|
+
if (res.status === 429) {
|
|
51
|
+
const seconds = Number(res.headers.get('retry-after') ?? '1');
|
|
52
|
+
await sleep(Math.max(1, Number.isFinite(seconds) ? seconds : 1) * 1000);
|
|
53
|
+
continue;
|
|
54
|
+
}
|
|
55
|
+
if (res.status === 404)
|
|
56
|
+
throw new Stop({ status: 'no_login' });
|
|
57
|
+
// ORIGIN_MISMATCH, the kill switches, a missing scope: stop and tell the person. No retry.
|
|
58
|
+
throw new Stop({ status: 'stopped', ...(json.code ? { code: json.code } : {}), message: `Vault refused (${res.status})` });
|
|
59
|
+
}
|
|
60
|
+
throw new Stop({ status: 'stopped', message: 'Vault kept refusing' });
|
|
61
|
+
};
|
|
62
|
+
/** Fills ONE field: the page's origin read right before, the value typed at once, the buffer zeroed. */
|
|
63
|
+
const fillAndType = async (id, field, target) => {
|
|
64
|
+
const origin = page.origin;
|
|
65
|
+
const data = (await call('POST', `/credentials/${id}/fill`, { field, origin, purpose: 'login' }));
|
|
66
|
+
if (page.origin !== origin)
|
|
67
|
+
throw new Stop({ status: 'stopped', message: 'The page navigated' });
|
|
68
|
+
const buffer = new TextEncoder().encode(data.value);
|
|
69
|
+
try {
|
|
70
|
+
await page.type(target, buffer);
|
|
71
|
+
}
|
|
72
|
+
finally {
|
|
73
|
+
buffer.fill(0);
|
|
74
|
+
}
|
|
75
|
+
};
|
|
76
|
+
try {
|
|
77
|
+
const origin = page.origin;
|
|
78
|
+
const found = (await call('GET', `/credentials?origin=${encodeURIComponent(origin)}`));
|
|
79
|
+
const exact = found.filter((c) => c.matchKind === 'exact');
|
|
80
|
+
if (exact.length === 0)
|
|
81
|
+
return { status: 'no_login' };
|
|
82
|
+
let chosen = exact[0];
|
|
83
|
+
if (exact.length > 1) {
|
|
84
|
+
const id = await page.askPerson('Which login should be used?', exact.map((c) => ({ id: c.id, label: `${c.name} (${c.username ?? 'no username'})` })));
|
|
85
|
+
const pick = exact.find((c) => c.id === id);
|
|
86
|
+
if (!pick)
|
|
87
|
+
return { status: 'no_login', message: 'The person chose none' };
|
|
88
|
+
chosen = pick;
|
|
89
|
+
}
|
|
90
|
+
await fillAndType(chosen.id, 'username', 'username');
|
|
91
|
+
await fillAndType(chosen.id, 'password', 'password');
|
|
92
|
+
if (page.asksForCode && chosen.hasTotp) {
|
|
93
|
+
// Fetched right before typing: a code lives for its period only.
|
|
94
|
+
const codeOrigin = page.origin;
|
|
95
|
+
const data = (await call('POST', `/credentials/${chosen.id}/totp`, { origin: codeOrigin, purpose: 'mfa' }));
|
|
96
|
+
const buffer = new TextEncoder().encode(data.code);
|
|
97
|
+
try {
|
|
98
|
+
await page.type('code', buffer);
|
|
99
|
+
}
|
|
100
|
+
finally {
|
|
101
|
+
buffer.fill(0);
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
return { status: 'signed_in' };
|
|
105
|
+
}
|
|
106
|
+
catch (error) {
|
|
107
|
+
if (error instanceof Stop)
|
|
108
|
+
return error.result;
|
|
109
|
+
return { status: 'stopped', message: 'The runtime failed' };
|
|
110
|
+
}
|
|
111
|
+
};
|
|
112
|
+
}
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
import { type CanarySource } from './canary.js';
|
|
2
|
+
import type { AgentConformanceTarget, AgentTokens } from './fake-vault.js';
|
|
3
|
+
/** A field of the simulated sign-in form. @stability beta */
|
|
4
|
+
export type ConformanceField = 'username' | 'password' | 'code';
|
|
5
|
+
/** A choice offered to the person. @stability beta */
|
|
6
|
+
export interface ConformanceChoice {
|
|
7
|
+
/** The credential id the choice stands for. */
|
|
8
|
+
id: string;
|
|
9
|
+
label: string;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* The simulated page a runtime signs in to. It stands for the browser tab: its top-level origin
|
|
13
|
+
* (read it from here, never from model output), the form's fields, and the person behind the screen.
|
|
14
|
+
*
|
|
15
|
+
* @stability beta
|
|
16
|
+
*/
|
|
17
|
+
export interface ConformancePage {
|
|
18
|
+
/** The page's top-level origin, now. It can change between reads (the page navigated). */
|
|
19
|
+
readonly origin: string;
|
|
20
|
+
/** Whether the site asks for a one-time code after the password. */
|
|
21
|
+
readonly asksForCode: boolean;
|
|
22
|
+
/** Types a value into a field. Pass a `Uint8Array` you zero right after, where you can. */
|
|
23
|
+
type(field: ConformanceField, value: string | Uint8Array): Promise<void>;
|
|
24
|
+
/** Asks the person to pick one of several logins; resolves to the chosen `id`, or `null`. */
|
|
25
|
+
askPerson(question: string, choices: readonly ConformanceChoice[]): Promise<string | null>;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* How a sign-in ended. `stopped` carries the Vault `code` that stopped it (for example
|
|
29
|
+
* `AGENT_ACCESS_DISABLED` or `ORIGIN_MISMATCH`), which is what the runtime reports to the person.
|
|
30
|
+
*
|
|
31
|
+
* @stability beta
|
|
32
|
+
*/
|
|
33
|
+
export type SignInResult = {
|
|
34
|
+
status: 'signed_in';
|
|
35
|
+
} | {
|
|
36
|
+
status: 'no_login';
|
|
37
|
+
message?: string;
|
|
38
|
+
} | {
|
|
39
|
+
status: 'stopped';
|
|
40
|
+
code?: string;
|
|
41
|
+
message?: string;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* What the kit hands the runtime on every call: where the Vault is and how to get tokens.
|
|
45
|
+
*
|
|
46
|
+
* @stability beta
|
|
47
|
+
*/
|
|
48
|
+
export interface ConformanceVaultAccess {
|
|
49
|
+
/** The Vault's base URL (the kit's recorder in front of it). */
|
|
50
|
+
baseUrl: string;
|
|
51
|
+
/** `baseUrl + AGENT_API_BASE_PATH`. */
|
|
52
|
+
apiBaseUrl: string;
|
|
53
|
+
/**
|
|
54
|
+
* The person connects the runtime (consent): fresh tokens for the login scopes. Call it when you
|
|
55
|
+
* hold no token, and after a `401` (a revoked grant); never in a loop.
|
|
56
|
+
*/
|
|
57
|
+
connect(): Promise<AgentTokens>;
|
|
58
|
+
/** The id of the running scenario, for the runtime's own logs. */
|
|
59
|
+
scenario: string;
|
|
60
|
+
}
|
|
61
|
+
/** The function a runtime gives the kit: "sign in to this page". @stability beta */
|
|
62
|
+
export type ConformanceSignIn = (page: ConformancePage, vault: ConformanceVaultAccess) => Promise<SignInResult>;
|
|
63
|
+
/** One scenario, as data. `server` scenarios check the Vault; `runtime` ones check the sign-in. @stability beta */
|
|
64
|
+
export interface AgentConformanceScenario {
|
|
65
|
+
id: string;
|
|
66
|
+
kind: 'server' | 'runtime';
|
|
67
|
+
title: string;
|
|
68
|
+
/** What passing requires, in plain words. */
|
|
69
|
+
expectation: string;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Every scenario of the kit, in run order. The `server` ones first (they check that the Vault in
|
|
73
|
+
* front of the runtime behaves like Vault), then the `runtime` ones (the guide's rules).
|
|
74
|
+
*
|
|
75
|
+
* @stability beta
|
|
76
|
+
*/
|
|
77
|
+
export declare const AGENT_CONFORMANCE_SCENARIOS: readonly AgentConformanceScenario[];
|
|
78
|
+
/** A scenario id. @stability beta */
|
|
79
|
+
export type AgentConformanceScenarioId = string;
|
|
80
|
+
/** One scenario's outcome. @stability beta */
|
|
81
|
+
export interface AgentConformanceResult {
|
|
82
|
+
id: string;
|
|
83
|
+
kind: 'server' | 'runtime';
|
|
84
|
+
title: string;
|
|
85
|
+
status: 'passed' | 'failed' | 'skipped';
|
|
86
|
+
/** Why it failed or was skipped. Never a secret value. */
|
|
87
|
+
problems: string[];
|
|
88
|
+
durationMs: number;
|
|
89
|
+
}
|
|
90
|
+
/** A whole run. @stability beta */
|
|
91
|
+
export interface AgentConformanceReport {
|
|
92
|
+
passed: boolean;
|
|
93
|
+
results: AgentConformanceResult[];
|
|
94
|
+
}
|
|
95
|
+
/** Thrown by {@link assertAgentConformance} when a scenario failed. @stability beta */
|
|
96
|
+
export declare class AgentConformanceError extends Error {
|
|
97
|
+
readonly report: AgentConformanceReport;
|
|
98
|
+
constructor(report: AgentConformanceReport);
|
|
99
|
+
}
|
|
100
|
+
/** Options of {@link runAgentConformance}. @stability beta */
|
|
101
|
+
export interface AgentConformanceOptions {
|
|
102
|
+
/** The Vault: a {@link createFakeVault} (started) or a real deployment wrapped in the target interface. */
|
|
103
|
+
target: AgentConformanceTarget;
|
|
104
|
+
/** The runtime's "sign in to this page". Required for `runtime` scenarios; without it they are skipped. */
|
|
105
|
+
signIn?: ConformanceSignIn;
|
|
106
|
+
/** Run only these scenario ids (default: all). */
|
|
107
|
+
only?: readonly string[];
|
|
108
|
+
/** Everything the runtime wrote during the run (logs, traces, transcripts, `{ files }`), for the canary scan. */
|
|
109
|
+
artifacts?: () => CanarySource[] | Promise<CanarySource[]>;
|
|
110
|
+
/** Per scenario (default 20 s). */
|
|
111
|
+
timeoutMs?: number;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Runs the scenario list against a Vault (the fake or a real one) with the runtime's `signIn`, and
|
|
115
|
+
* returns one result per scenario. Never throws for a failed scenario (see
|
|
116
|
+
* {@link assertAgentConformance}); refuses to run with `NODE_ENV=production`. Uses no test
|
|
117
|
+
* framework: call it from any.
|
|
118
|
+
*
|
|
119
|
+
* @stability beta
|
|
120
|
+
*/
|
|
121
|
+
export declare function runAgentConformance(options: AgentConformanceOptions): Promise<AgentConformanceReport>;
|
|
122
|
+
/**
|
|
123
|
+
* {@link runAgentConformance}, then throws {@link AgentConformanceError} when a scenario failed.
|
|
124
|
+
* Returns the report otherwise (skipped scenarios are listed in it).
|
|
125
|
+
*
|
|
126
|
+
* @stability beta
|
|
127
|
+
*/
|
|
128
|
+
export declare function assertAgentConformance(options: AgentConformanceOptions): Promise<AgentConformanceReport>;
|