@mandateops/cli-darwin-arm64 0.0.0-stage → 0.7.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/LICENSE +55 -0
- package/README.md +175 -2
- package/audit-lab/README.md +194 -0
- package/audit-lab/bin/mandateops +0 -0
- package/audit-lab/contracts/contact-plain-text.vectors.json +85 -0
- package/audit-lab/contracts/history-reading.md +185 -0
- package/audit-lab/contracts/history-reading.vectors.json +284 -0
- package/audit-lab/contracts/profiles.md +161 -0
- package/audit-lab/contracts/properties.md +512 -0
- package/audit-lab/contracts/sdk-config.md +155 -0
- package/audit-lab/contracts/system-under-test.md +385 -0
- package/audit-lab/contracts/test-provider.md +350 -0
- package/audit-lab/lab/compose.audit.yml +181 -0
- package/audit-lab/lab/config/fault-control.json +14 -0
- package/audit-lab/lab/examples/agents/Dockerfile +28 -0
- package/audit-lab/lab/examples/agents/codeloc.cjs +199 -0
- package/audit-lab/lab/examples/agents/load.cjs +9 -0
- package/audit-lab/lab/examples/agents/package-lock.json +2840 -0
- package/audit-lab/lab/examples/agents/package.json +9 -0
- package/audit-lab/lab/examples/agents/python/mandateops_codeloc.py +271 -0
- package/audit-lab/lab/examples/agents/python/sitecustomize.py +51 -0
- package/audit-lab/lab/examples/agents/requirements-python.txt +522 -0
- package/audit-lab/lab/examples/agents/telemetry-router.cjs +272 -0
- package/audit-lab/lab/examples/test-provider/.dockerignore +4 -0
- package/audit-lab/lab/examples/test-provider/Dockerfile +28 -0
- package/audit-lab/lab/examples/test-provider/bun.lock +405 -0
- package/audit-lab/lab/examples/test-provider/package.json +42 -0
- package/audit-lab/lab/examples/test-provider/src/amount.ts +32 -0
- package/audit-lab/lab/examples/test-provider/src/app.ts +538 -0
- package/audit-lab/lab/examples/test-provider/src/auth.ts +30 -0
- package/audit-lab/lab/examples/test-provider/src/barrier.ts +262 -0
- package/audit-lab/lab/examples/test-provider/src/codeloc.ts +27 -0
- package/audit-lab/lab/examples/test-provider/src/config.ts +311 -0
- package/audit-lab/lab/examples/test-provider/src/connect.ts +204 -0
- package/audit-lab/lab/examples/test-provider/src/declaration.ts +270 -0
- package/audit-lab/lab/examples/test-provider/src/declared.ts +198 -0
- package/audit-lab/lab/examples/test-provider/src/domain.ts +193 -0
- package/audit-lab/lab/examples/test-provider/src/egress.ts +396 -0
- package/audit-lab/lab/examples/test-provider/src/flow.ts +263 -0
- package/audit-lab/lab/examples/test-provider/src/gate.ts +301 -0
- package/audit-lab/lab/examples/test-provider/src/main.ts +31 -0
- package/audit-lab/lab/examples/test-provider/src/notify.ts +157 -0
- package/audit-lab/lab/examples/test-provider/src/owner.ts +60 -0
- package/audit-lab/lab/examples/test-provider/src/payment.ts +103 -0
- package/audit-lab/lab/examples/test-provider/src/profile.ts +417 -0
- package/audit-lab/lab/examples/test-provider/src/request.ts +201 -0
- package/audit-lab/lab/examples/test-provider/src/rows.ts +173 -0
- package/audit-lab/lab/examples/test-provider/src/schema.ts +114 -0
- package/audit-lab/lab/examples/test-provider/src/signature.ts +86 -0
- package/audit-lab/lab/examples/test-provider/src/staged.ts +318 -0
- package/audit-lab/lab/examples/test-provider/src/store.ts +432 -0
- package/audit-lab/lab/examples/test-provider/src/traffic.ts +50 -0
- package/audit-lab/lab/examples/test-provider/src/webauthn.d.ts +11 -0
- package/audit-lab/lab/examples/test-provider/src/wire.ts +153 -0
- package/audit-lab/lab/examples/test-provider/tsconfig.build.json +9 -0
- package/audit-lab/lab/examples/test-provider/tsconfig.json +24 -0
- package/audit-lab/lab/images/capture/Dockerfile +15 -0
- package/audit-lab/lab/images/capture/LICENSE +201 -0
- package/audit-lab/lab/images/fault-control/Dockerfile +13 -0
- package/audit-lab/lab/images/fault-control/LICENSE +21 -0
- package/audit-lab/lab/images/provider-store/Dockerfile +4 -0
- package/audit-lab/lab/images/provider-store/LICENSE +23 -0
- package/audit-lab/lab/images/telemetry/Dockerfile +14 -0
- package/audit-lab/lab/images/telemetry/LICENSE +201 -0
- package/audit-lab/lab/scripts/compose-down.sh +143 -0
- package/audit-lab/lab/scripts/compose-lib.sh +632 -0
- package/audit-lab/lab/scripts/compose-up.sh +240 -0
- package/package.json +16 -4
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
|
|
4
|
+
/** The audit core's `u128` maximum; amounts are integer minor units. */
|
|
5
|
+
export const MAX_MINOR_UNITS =
|
|
6
|
+
340_282_366_920_938_463_463_374_607_431_768_211_455n;
|
|
7
|
+
/** Upper bound on effects and on notifications in one disposable run. */
|
|
8
|
+
export const MAX_RECORDS_PER_RUN = 1000;
|
|
9
|
+
/**
|
|
10
|
+
* Default caller identity behind the provider token. Idempotency keys are
|
|
11
|
+
* scoped to the provider account, never to fields of the request body.
|
|
12
|
+
*/
|
|
13
|
+
export const DEFAULT_PROVIDER_ACCOUNT = "lab-backend";
|
|
14
|
+
/** Default provider operation; recorded on each effect. */
|
|
15
|
+
export const DEFAULT_PROVIDER_OPERATION = "payout-create";
|
|
16
|
+
/** The scope within which this provider treats a key as one request. */
|
|
17
|
+
export const DEFAULT_IDEMPOTENCY_SCOPE = "provider-account";
|
|
18
|
+
|
|
19
|
+
/** Every runner control route sits under this; no format may claim it. */
|
|
20
|
+
export const CONTROL_PREFIX = "/_control/";
|
|
21
|
+
|
|
22
|
+
/** A route a format may claim: anywhere but the runner's controls. */
|
|
23
|
+
export const routeSchema = z
|
|
24
|
+
.string()
|
|
25
|
+
.regex(/^\/[a-zA-Z0-9_\-/:.]{0,200}$/)
|
|
26
|
+
.refine((path) => !path.startsWith(CONTROL_PREFIX), "reserved path");
|
|
27
|
+
|
|
28
|
+
export const idSchema = z.string().regex(/^[a-zA-Z0-9_-]{1,80}$/);
|
|
29
|
+
/** A key as a provider's format allows it; `recordKey` bounds what is stored. */
|
|
30
|
+
export const providerKeySchema = z.string().regex(/^[\x20-\x7e]+$/);
|
|
31
|
+
|
|
32
|
+
/** The form a digested key takes, which no kept key may share. */
|
|
33
|
+
const DIGESTED_KEY = /^key-[0-9a-f]{64}$/;
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* A key the record format can hold, kept, or else its digest: still one key.
|
|
37
|
+
* A key already in digest form is digested again, so none can pose as another.
|
|
38
|
+
* `fixtures/wire/vectors.json` pins this rule for the checker's side.
|
|
39
|
+
*/
|
|
40
|
+
export function recordKey(key: string): string {
|
|
41
|
+
if (idSchema.safeParse(key).success && !DIGESTED_KEY.test(key)) return key;
|
|
42
|
+
return `key-${createHash("sha256").update(key).digest("hex")}`;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export const amountSchema = z
|
|
46
|
+
.string()
|
|
47
|
+
.regex(/^[1-9][0-9]{0,38}$/)
|
|
48
|
+
.pipe(
|
|
49
|
+
z
|
|
50
|
+
.string()
|
|
51
|
+
.refine(
|
|
52
|
+
(value) => BigInt(value) <= MAX_MINOR_UNITS,
|
|
53
|
+
"amount exceeds the u128 range",
|
|
54
|
+
),
|
|
55
|
+
);
|
|
56
|
+
/** Wire contract shared with the payout backend; field order is canonical. */
|
|
57
|
+
export const instructionSchema = z
|
|
58
|
+
.object({
|
|
59
|
+
payment: idSchema,
|
|
60
|
+
tenant: idSchema,
|
|
61
|
+
agent: idSchema,
|
|
62
|
+
delegation: idSchema,
|
|
63
|
+
account: idSchema,
|
|
64
|
+
destination: idSchema,
|
|
65
|
+
currency: idSchema,
|
|
66
|
+
asset: idSchema,
|
|
67
|
+
network: idSchema,
|
|
68
|
+
amount: amountSchema,
|
|
69
|
+
})
|
|
70
|
+
.strict();
|
|
71
|
+
export type Instruction = Readonly<z.infer<typeof instructionSchema>>;
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Canonical encoding version 1: JSON of the validated instruction with fields
|
|
75
|
+
* in the schema's declared order and string values only. Zod constructs every
|
|
76
|
+
* parsed instruction in that order, so equal terms give equal bytes.
|
|
77
|
+
*/
|
|
78
|
+
export function canonicalInstruction(instruction: Instruction): string {
|
|
79
|
+
const ordered = instructionSchema.parse(instruction);
|
|
80
|
+
return JSON.stringify(ordered);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** SHA-256 over the version-1 canonical encoding, as lowercase hex. */
|
|
84
|
+
export function instructionDigest(instruction: Instruction): string {
|
|
85
|
+
return createHash("sha256")
|
|
86
|
+
.update(`test-provider/instruction/v1\n`)
|
|
87
|
+
.update(canonicalInstruction(instruction))
|
|
88
|
+
.digest("hex");
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** The most providers one run serves; the gate names each by its own host. */
|
|
92
|
+
export const MAX_PROVIDERS = 8;
|
|
93
|
+
/** The name of the provider a run that lists none serves. */
|
|
94
|
+
export const DEFAULT_PROVIDER_NAME = "provider";
|
|
95
|
+
/** The host the first provider is reached at; later ones add their position. */
|
|
96
|
+
const PROVIDER_HOST = "mandateops-provider";
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* The host the provider at `index` in the run's list is reached at:
|
|
100
|
+
* `mandateops-provider` for the first, `mandateops-provider-2` for the second
|
|
101
|
+
* and so on. `contracts/test-provider.md` states the same rule for the host.
|
|
102
|
+
*/
|
|
103
|
+
export function providerHostname(index: number): string {
|
|
104
|
+
return index === 0 ? PROVIDER_HOST : `${PROVIDER_HOST}-${String(index + 1)}`;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
export type Effect = Readonly<{
|
|
108
|
+
effectId: string;
|
|
109
|
+
/** The name of the provider in the run's list that committed it. */
|
|
110
|
+
provider: string;
|
|
111
|
+
key: string;
|
|
112
|
+
instruction: Instruction;
|
|
113
|
+
providerAccount: string;
|
|
114
|
+
operation: string;
|
|
115
|
+
idempotencyScope: string;
|
|
116
|
+
committedAt: string;
|
|
117
|
+
}>;
|
|
118
|
+
/** Why a request was refused with no effect. */
|
|
119
|
+
export const REJECTION_REASONS = [
|
|
120
|
+
"declined",
|
|
121
|
+
"idempotency_key_conflict",
|
|
122
|
+
] as const;
|
|
123
|
+
export type RejectionReason = (typeof REJECTION_REASONS)[number];
|
|
124
|
+
|
|
125
|
+
/** Most keys one effect-count request may ask about. */
|
|
126
|
+
export const MAX_COUNTED_KEYS = 1000;
|
|
127
|
+
/** Duplicate keys a summary names; the rest are counted. */
|
|
128
|
+
export const MAX_NAMED_DUPLICATES = 20;
|
|
129
|
+
|
|
130
|
+
/** Effects across a whole run, without listing them. */
|
|
131
|
+
export type EffectSummary = Readonly<{
|
|
132
|
+
effects: number;
|
|
133
|
+
keys: number;
|
|
134
|
+
/** At most `MAX_NAMED_DUPLICATES` keys holding more than one effect. */
|
|
135
|
+
duplicateKeys: readonly string[];
|
|
136
|
+
duplicateKeyCount: number;
|
|
137
|
+
}>;
|
|
138
|
+
|
|
139
|
+
/** A request refused without an effect, with the terms it carried. */
|
|
140
|
+
export type RejectedRequest = Readonly<{
|
|
141
|
+
/** The name of the provider in the run's list that refused it. */
|
|
142
|
+
provider: string;
|
|
143
|
+
key: string;
|
|
144
|
+
instruction: Instruction;
|
|
145
|
+
providerAccount: string;
|
|
146
|
+
operation: string;
|
|
147
|
+
reason: RejectionReason;
|
|
148
|
+
paymentFromKey: boolean;
|
|
149
|
+
rejectedAt: string;
|
|
150
|
+
}>;
|
|
151
|
+
/**
|
|
152
|
+
* One delivery of a notification to the backend, in delivery order.
|
|
153
|
+
* `issued` is the order the runner issued it in; `sentAt` and `status` are
|
|
154
|
+
* null when nothing was sent or nothing answered.
|
|
155
|
+
*/
|
|
156
|
+
export type Notification = Readonly<{
|
|
157
|
+
effectId: string;
|
|
158
|
+
deliveredAt: string;
|
|
159
|
+
deliveryId: string;
|
|
160
|
+
issued: number;
|
|
161
|
+
sentAt: string | null;
|
|
162
|
+
status: number | null;
|
|
163
|
+
}>;
|
|
164
|
+
|
|
165
|
+
/** Result of one idempotent payout request against durable provider state. */
|
|
166
|
+
export type ExecutionResult =
|
|
167
|
+
| Readonly<{ kind: "effect"; effect: Effect; created: boolean }>
|
|
168
|
+
| Readonly<{ kind: "key_conflict" }>
|
|
169
|
+
/** `repeated` says this answers an earlier refusal with no refusal armed. */
|
|
170
|
+
| Readonly<{ kind: "declined"; repeated: boolean }>;
|
|
171
|
+
|
|
172
|
+
export class ProviderError extends Error {
|
|
173
|
+
constructor(
|
|
174
|
+
readonly status: number,
|
|
175
|
+
readonly code: string,
|
|
176
|
+
) {
|
|
177
|
+
super(code);
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* The most records one run may hold when the deployment raises the default,
|
|
183
|
+
* as a scaled run does: every record is kept, none dropped.
|
|
184
|
+
*/
|
|
185
|
+
export const RECORD_LIMIT_CEILING = 10_000_000;
|
|
186
|
+
|
|
187
|
+
/** Refuses growth past the run's record bound rather than dropping state. */
|
|
188
|
+
export function requireRoom(
|
|
189
|
+
records: ReadonlyMap<unknown, unknown>,
|
|
190
|
+
limit: number = MAX_RECORDS_PER_RUN,
|
|
191
|
+
): void {
|
|
192
|
+
if (records.size >= limit) throw new ProviderError(409, "stage_limit");
|
|
193
|
+
}
|
|
@@ -0,0 +1,396 @@
|
|
|
1
|
+
import type { Socket } from "node:net";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Egress to a real provider's sandbox, by TLS passthrough. The backend keeps
|
|
5
|
+
* its real HTTPS URL; on the customer network that host name names the gate,
|
|
6
|
+
* which forwards the connection to the lab's fault-control proxy and from
|
|
7
|
+
* there to that host alone. Nothing is decrypted: the gate reads only TLS
|
|
8
|
+
* record headers and the cleartext ClientHello and ServerHello.
|
|
9
|
+
*
|
|
10
|
+
* A connection is forwarded only when its ClientHello names exactly the one
|
|
11
|
+
* allowed host (SNI). Replies are framed by TLS record so a hold acts on
|
|
12
|
+
* whole replies: a reply is the first application data the provider sends
|
|
13
|
+
* after the client sent some, so its request already reached the provider.
|
|
14
|
+
* The gate cannot tell which call a reply answers, and need not: the runner
|
|
15
|
+
* holds replies one at a time and asks the provider itself whether the
|
|
16
|
+
* effect it waits for exists, so a reply that is no answer to a request
|
|
17
|
+
* (such as an HTTP/2 SETTINGS frame) is only held and let go.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
/** TLS record content types the gate tells apart. */
|
|
21
|
+
const HANDSHAKE = 22;
|
|
22
|
+
const APPLICATION_DATA = 23;
|
|
23
|
+
/** Handshake message types. */
|
|
24
|
+
const CLIENT_HELLO = 1;
|
|
25
|
+
const SERVER_HELLO = 2;
|
|
26
|
+
/** Extensions read from the hellos. */
|
|
27
|
+
const SERVER_NAME = 0;
|
|
28
|
+
const SUPPORTED_VERSIONS = 43;
|
|
29
|
+
const TLS_1_3 = 0x0304;
|
|
30
|
+
/** A record header, and the largest record TLS allows (2^14 + 2048). */
|
|
31
|
+
const RECORD_HEADER = 5;
|
|
32
|
+
const MAX_RECORD = 16_384 + 2_048;
|
|
33
|
+
/** Most bytes read before a ClientHello must be complete. */
|
|
34
|
+
export const MAX_CLIENT_HELLO = 16_384;
|
|
35
|
+
/** How often a held reply checks whether its fault was lifted. */
|
|
36
|
+
const HOLD_POLL_MS = 100;
|
|
37
|
+
|
|
38
|
+
/** One complete TLS record. */
|
|
39
|
+
export type TlsRecord = Readonly<{ type: number; bytes: Buffer }>;
|
|
40
|
+
|
|
41
|
+
/** Splits a byte stream into whole TLS records; refuses malformed ones. */
|
|
42
|
+
export class RecordFramer {
|
|
43
|
+
private pending: Buffer = Buffer.alloc(0);
|
|
44
|
+
|
|
45
|
+
/** Whole records completed by `chunk`, in order. */
|
|
46
|
+
push(chunk: Buffer): TlsRecord[] {
|
|
47
|
+
this.pending = Buffer.concat([this.pending, chunk]);
|
|
48
|
+
const records: TlsRecord[] = [];
|
|
49
|
+
while (this.pending.length >= RECORD_HEADER) {
|
|
50
|
+
const length = this.pending.readUInt16BE(3);
|
|
51
|
+
if (length > MAX_RECORD) throw new Error("oversized TLS record");
|
|
52
|
+
const end = RECORD_HEADER + length;
|
|
53
|
+
if (this.pending.length < end) break;
|
|
54
|
+
records.push({
|
|
55
|
+
type: this.pending.readUInt8(0),
|
|
56
|
+
bytes: this.pending.subarray(0, end),
|
|
57
|
+
});
|
|
58
|
+
this.pending = this.pending.subarray(end);
|
|
59
|
+
}
|
|
60
|
+
return records;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** Bytes received but not yet part of a whole record. */
|
|
64
|
+
get buffered(): number {
|
|
65
|
+
return this.pending.length;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** A bounds-checked reader over one handshake message body. */
|
|
70
|
+
class Cursor {
|
|
71
|
+
private offset = 0;
|
|
72
|
+
constructor(private readonly bytes: Buffer) {}
|
|
73
|
+
|
|
74
|
+
private take(length: number): Buffer {
|
|
75
|
+
const end = this.offset + length;
|
|
76
|
+
if (end > this.bytes.length) throw new Error("truncated hello");
|
|
77
|
+
const slice = this.bytes.subarray(this.offset, end);
|
|
78
|
+
this.offset = end;
|
|
79
|
+
return slice;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
skip(length: number): void {
|
|
83
|
+
this.take(length);
|
|
84
|
+
}
|
|
85
|
+
u8(): number {
|
|
86
|
+
return this.take(1).readUInt8(0);
|
|
87
|
+
}
|
|
88
|
+
u16(): number {
|
|
89
|
+
return this.take(2).readUInt16BE(0);
|
|
90
|
+
}
|
|
91
|
+
vector8(): Buffer {
|
|
92
|
+
return this.take(this.u8());
|
|
93
|
+
}
|
|
94
|
+
vector16(): Buffer {
|
|
95
|
+
return this.take(this.u16());
|
|
96
|
+
}
|
|
97
|
+
get done(): boolean {
|
|
98
|
+
return this.offset === this.bytes.length;
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** Each extension of a hello's extension block, by type. */
|
|
103
|
+
function extensions(block: Buffer): Map<number, Buffer> {
|
|
104
|
+
const found = new Map<number, Buffer>();
|
|
105
|
+
const cursor = new Cursor(block);
|
|
106
|
+
while (!cursor.done) {
|
|
107
|
+
const type = cursor.u16();
|
|
108
|
+
if (found.has(type)) throw new Error("repeated extension");
|
|
109
|
+
found.set(type, cursor.vector16());
|
|
110
|
+
}
|
|
111
|
+
return found;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* The handshake message of `type` carried by `payload` (the concatenated
|
|
116
|
+
* handshake record bodies), or `undefined` while it is incomplete.
|
|
117
|
+
*/
|
|
118
|
+
function handshakeBody(payload: Buffer, type: number): Buffer | undefined {
|
|
119
|
+
if (payload.length < 4) return undefined;
|
|
120
|
+
if (payload.readUInt8(0) !== type) throw new Error("unexpected handshake");
|
|
121
|
+
const length = payload.readUIntBE(1, 3);
|
|
122
|
+
if (payload.length < 4 + length) return undefined;
|
|
123
|
+
return payload.subarray(4, 4 + length);
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* The one host name a complete ClientHello names, lowercased. A hello naming
|
|
128
|
+
* none, more than one, or a name type other than host_name is refused.
|
|
129
|
+
*/
|
|
130
|
+
export function serverName(hello: Buffer): string {
|
|
131
|
+
const cursor = new Cursor(hello);
|
|
132
|
+
cursor.skip(2 + 32);
|
|
133
|
+
cursor.vector8();
|
|
134
|
+
cursor.vector16();
|
|
135
|
+
cursor.vector8();
|
|
136
|
+
const named = extensions(cursor.vector16()).get(SERVER_NAME);
|
|
137
|
+
if (!named) throw new Error("no server name");
|
|
138
|
+
const list = new Cursor(new Cursor(named).vector16());
|
|
139
|
+
if (list.u8() !== 0) throw new Error("not a host name");
|
|
140
|
+
const host = list.vector16().toString("latin1");
|
|
141
|
+
if (!list.done) throw new Error("more than one server name");
|
|
142
|
+
if (!/^[A-Za-z0-9.-]{1,253}$/.test(host)) throw new Error("bad host name");
|
|
143
|
+
return host.toLowerCase();
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** Whether a complete ServerHello selected TLS 1.3. */
|
|
147
|
+
export function selectsTls13(hello: Buffer): boolean {
|
|
148
|
+
const cursor = new Cursor(hello);
|
|
149
|
+
cursor.skip(2 + 32);
|
|
150
|
+
cursor.vector8();
|
|
151
|
+
cursor.skip(2 + 1);
|
|
152
|
+
if (cursor.done) return false;
|
|
153
|
+
const version = extensions(cursor.vector16()).get(SUPPORTED_VERSIONS);
|
|
154
|
+
return version?.length === 2 && version.readUInt16BE(0) === TLS_1_3;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** A complete ClientHello: the host it names and every byte read so far. */
|
|
158
|
+
export type Hello = Readonly<{ host: string; bytes: Buffer }>;
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* Reads the client's first bytes until its ClientHello is complete and
|
|
162
|
+
* returns them with the host it names. Fails on a hello that is malformed,
|
|
163
|
+
* larger than [`MAX_CLIENT_HELLO`] or not the first thing sent.
|
|
164
|
+
*/
|
|
165
|
+
export class HelloReader {
|
|
166
|
+
private readonly framer = new RecordFramer();
|
|
167
|
+
private readonly received: Buffer[] = [];
|
|
168
|
+
private payload: Buffer = Buffer.alloc(0);
|
|
169
|
+
private size = 0;
|
|
170
|
+
|
|
171
|
+
/** The host and every byte read so far once the hello is complete. */
|
|
172
|
+
push(chunk: Buffer): Hello | undefined {
|
|
173
|
+
if (
|
|
174
|
+
this.size === 0 &&
|
|
175
|
+
chunk.length > 0 &&
|
|
176
|
+
chunk.readUInt8(0) !== HANDSHAKE
|
|
177
|
+
) {
|
|
178
|
+
throw new Error("hello expected");
|
|
179
|
+
}
|
|
180
|
+
this.size += chunk.length;
|
|
181
|
+
if (this.size > MAX_CLIENT_HELLO) throw new Error("oversized hello");
|
|
182
|
+
this.received.push(chunk);
|
|
183
|
+
for (const record of this.framer.push(chunk)) {
|
|
184
|
+
if (record.type !== HANDSHAKE) throw new Error("hello expected");
|
|
185
|
+
this.payload = Buffer.concat([
|
|
186
|
+
this.payload,
|
|
187
|
+
record.bytes.subarray(RECORD_HEADER),
|
|
188
|
+
]);
|
|
189
|
+
}
|
|
190
|
+
const hello = handshakeBody(this.payload, CLIENT_HELLO);
|
|
191
|
+
if (!hello) return undefined;
|
|
192
|
+
return { host: serverName(hello), bytes: Buffer.concat(this.received) };
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** Hold reply N, counted from the first marker: `hold-reply-N`. */
|
|
197
|
+
const HOLD_MARKER = /^hold-reply-([1-9][0-9]{0,2})$/;
|
|
198
|
+
/** The gate's report that it holds reply N. */
|
|
199
|
+
export const HELD_PREFIX = "held-reply-";
|
|
200
|
+
|
|
201
|
+
/**
|
|
202
|
+
* The reply to hold, from the egress proxy's toxics: the highest N any
|
|
203
|
+
* `hold-reply-N` marker names, or none. The fault-control proxy is the lab's
|
|
204
|
+
* one fault surface: the runner arms a hold there as an inert marker, the
|
|
205
|
+
* gate enforces it and reports it there, and the runner moves the hold on
|
|
206
|
+
* by arming the next reply before lifting the last.
|
|
207
|
+
*/
|
|
208
|
+
export function heldReply(toxics: unknown): number | undefined {
|
|
209
|
+
if (!Array.isArray(toxics)) throw new Error("toxics are not a list");
|
|
210
|
+
let highest: number | undefined;
|
|
211
|
+
for (const toxic of toxics as unknown[]) {
|
|
212
|
+
const name =
|
|
213
|
+
typeof toxic === "object" && toxic !== null && "name" in toxic
|
|
214
|
+
? toxic.name
|
|
215
|
+
: undefined;
|
|
216
|
+
const reply = Number(
|
|
217
|
+
(typeof name === "string" ? HOLD_MARKER.exec(name) : null)?.[1],
|
|
218
|
+
);
|
|
219
|
+
if (Number.isInteger(reply) && reply > (highest ?? 0)) highest = reply;
|
|
220
|
+
}
|
|
221
|
+
return highest;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/** The fault-control surface the gate reads holds from and reports to. */
|
|
225
|
+
export type FaultControl = Readonly<{
|
|
226
|
+
/** The reply to hold, failing when it cannot say. */
|
|
227
|
+
armed: () => Promise<number | undefined>;
|
|
228
|
+
/** Record that reply `reply` is held. */
|
|
229
|
+
held: (reply: number) => Promise<void>;
|
|
230
|
+
}>;
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* Counts replies across every egress connection while any hold is armed,
|
|
234
|
+
* so a reply's number does not depend on how the backend pools connections.
|
|
235
|
+
* The count starts afresh once no hold is armed.
|
|
236
|
+
*/
|
|
237
|
+
export class ReplyFaults {
|
|
238
|
+
private replies = 0;
|
|
239
|
+
|
|
240
|
+
constructor(private readonly control: FaultControl) {}
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* Whether the reply now starting is held: its number, reported to fault
|
|
244
|
+
* control, or `undefined` to forward it.
|
|
245
|
+
*/
|
|
246
|
+
async next(): Promise<number | undefined> {
|
|
247
|
+
const armed = await this.control.armed();
|
|
248
|
+
if (armed === undefined) {
|
|
249
|
+
this.replies = 0;
|
|
250
|
+
return undefined;
|
|
251
|
+
}
|
|
252
|
+
this.replies += 1;
|
|
253
|
+
if (this.replies !== armed) return undefined;
|
|
254
|
+
await this.control.held(this.replies);
|
|
255
|
+
return this.replies;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/** Whether reply `reply` is still the one held. */
|
|
259
|
+
async holding(reply: number): Promise<boolean> {
|
|
260
|
+
return (await this.control.armed()) === reply;
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
/** Fault control of the egress proxy at `toxics`, its toxics URL. */
|
|
265
|
+
export function toxicsAt(toxics: string): FaultControl {
|
|
266
|
+
const call = async (init: RequestInit): Promise<Response> => {
|
|
267
|
+
const response = await fetch(toxics, {
|
|
268
|
+
...init,
|
|
269
|
+
redirect: "error",
|
|
270
|
+
signal: AbortSignal.timeout(2_000),
|
|
271
|
+
});
|
|
272
|
+
if (!response.ok)
|
|
273
|
+
throw new Error(`fault control answered ${String(response.status)}`);
|
|
274
|
+
return response;
|
|
275
|
+
};
|
|
276
|
+
return {
|
|
277
|
+
armed: async () => heldReply(await (await call({})).json()),
|
|
278
|
+
held: async (reply) => {
|
|
279
|
+
await call({
|
|
280
|
+
method: "POST",
|
|
281
|
+
headers: { "content-type": "application/json" },
|
|
282
|
+
body: JSON.stringify({
|
|
283
|
+
name: `${HELD_PREFIX}${String(reply)}`,
|
|
284
|
+
type: "latency",
|
|
285
|
+
stream: "upstream",
|
|
286
|
+
toxicity: 1,
|
|
287
|
+
attributes: { latency: 0, jitter: 0 },
|
|
288
|
+
}),
|
|
289
|
+
});
|
|
290
|
+
},
|
|
291
|
+
};
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/** Tracks where a connection is in its exchange, from record types alone. */
|
|
295
|
+
export class Exchange {
|
|
296
|
+
private tls13: boolean | undefined;
|
|
297
|
+
private serverHandshake: Buffer = Buffer.alloc(0);
|
|
298
|
+
private clientData = 0;
|
|
299
|
+
private requestPending = false;
|
|
300
|
+
|
|
301
|
+
/** A whole record the client sent, already forwarded upstream. */
|
|
302
|
+
fromClient(record: TlsRecord): void {
|
|
303
|
+
if (record.type !== APPLICATION_DATA) return;
|
|
304
|
+
this.clientData += 1;
|
|
305
|
+
// Under TLS 1.3 the client's first encrypted record is its Finished.
|
|
306
|
+
if (this.tls13 === true && this.clientData === 1) return;
|
|
307
|
+
this.requestPending = true;
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
/** Whether a whole record from the provider starts a reply. */
|
|
311
|
+
fromServer(record: TlsRecord): boolean {
|
|
312
|
+
if (record.type === HANDSHAKE && this.tls13 === undefined) {
|
|
313
|
+
this.serverHandshake = Buffer.concat([
|
|
314
|
+
this.serverHandshake,
|
|
315
|
+
record.bytes.subarray(RECORD_HEADER),
|
|
316
|
+
]);
|
|
317
|
+
const hello = handshakeBody(this.serverHandshake, SERVER_HELLO);
|
|
318
|
+
if (hello) this.tls13 = selectsTls13(hello);
|
|
319
|
+
return false;
|
|
320
|
+
}
|
|
321
|
+
if (record.type !== APPLICATION_DATA || !this.requestPending) return false;
|
|
322
|
+
this.requestPending = false;
|
|
323
|
+
return true;
|
|
324
|
+
}
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
/**
|
|
328
|
+
* Pipes one egress connection after its ClientHello was accepted and sent:
|
|
329
|
+
* client bytes go upstream as they arrive; provider records reach the client
|
|
330
|
+
* whole, after each reply's fault was decided. Either side closing closes
|
|
331
|
+
* the other, so a cut reaches the backend as a lost connection.
|
|
332
|
+
*/
|
|
333
|
+
export function relay(
|
|
334
|
+
client: Socket,
|
|
335
|
+
upstream: Socket,
|
|
336
|
+
faults: ReplyFaults,
|
|
337
|
+
): void {
|
|
338
|
+
const exchange = new Exchange();
|
|
339
|
+
const fromClient = new RecordFramer();
|
|
340
|
+
const fromServer = new RecordFramer();
|
|
341
|
+
const close = (): void => {
|
|
342
|
+
client.destroy();
|
|
343
|
+
upstream.destroy();
|
|
344
|
+
};
|
|
345
|
+
for (const side of [client, upstream]) {
|
|
346
|
+
side.on("error", close);
|
|
347
|
+
side.on("close", close);
|
|
348
|
+
}
|
|
349
|
+
client.on("data", (chunk: Buffer) => {
|
|
350
|
+
upstream.write(chunk);
|
|
351
|
+
try {
|
|
352
|
+
for (const record of fromClient.push(chunk)) exchange.fromClient(record);
|
|
353
|
+
} catch {
|
|
354
|
+
close();
|
|
355
|
+
}
|
|
356
|
+
});
|
|
357
|
+
let queue = Promise.resolve();
|
|
358
|
+
upstream.on("data", (chunk: Buffer) => {
|
|
359
|
+
let records: TlsRecord[];
|
|
360
|
+
try {
|
|
361
|
+
records = fromServer.push(chunk);
|
|
362
|
+
} catch {
|
|
363
|
+
close();
|
|
364
|
+
return;
|
|
365
|
+
}
|
|
366
|
+
upstream.pause();
|
|
367
|
+
queue = queue
|
|
368
|
+
.then(async () => {
|
|
369
|
+
for (const record of records) {
|
|
370
|
+
if (exchange.fromServer(record)) {
|
|
371
|
+
const held = await faults.next();
|
|
372
|
+
if (held !== undefined)
|
|
373
|
+
await holdWhileArmed(faults, held, upstream);
|
|
374
|
+
}
|
|
375
|
+
if (client.destroyed) return;
|
|
376
|
+
client.write(record.bytes);
|
|
377
|
+
}
|
|
378
|
+
upstream.resume();
|
|
379
|
+
})
|
|
380
|
+
.catch(close);
|
|
381
|
+
});
|
|
382
|
+
}
|
|
383
|
+
|
|
384
|
+
/**
|
|
385
|
+
* Waits while reply `reply` stays the one held, or until the path closes:
|
|
386
|
+
* a cut of the proxy closes it, and the held reply is then lost.
|
|
387
|
+
*/
|
|
388
|
+
async function holdWhileArmed(
|
|
389
|
+
faults: ReplyFaults,
|
|
390
|
+
reply: number,
|
|
391
|
+
upstream: Socket,
|
|
392
|
+
): Promise<void> {
|
|
393
|
+
while (!upstream.destroyed && (await faults.holding(reply))) {
|
|
394
|
+
await new Promise((resolve) => setTimeout(resolve, HOLD_POLL_MS));
|
|
395
|
+
}
|
|
396
|
+
}
|