@deveye/types 0.20.3 → 0.21.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/package.json +1 -1
- package/src/domain/admission.ts +37 -0
- package/src/domain/device.ts +7 -3
- package/src/domain/featureRegistry.ts +3 -2
- package/src/domain/maintenance.ts +7 -1
- package/src/domain/notifications.ts +16 -0
- package/src/domain/packages.ts +34 -2
- package/src/domain/report.ts +15 -3
- package/src/domain/secrecy.ts +13 -0
- package/src/domain/user.ts +10 -1
- package/src/features/admin.ts +59 -1
- package/src/features/debug.ts +372 -0
- package/src/features/registry.ts +2 -0
- package/src/features/user.ts +46 -0
- package/src/http/auth.ts +2 -0
- package/src/http/device.ts +33 -15
- package/src/http/status.ts +6 -0
- package/src/index.ts +125 -6
- package/src/protocol/agent.ts +127 -5
- package/src/protocol/error.ts +4 -1
- package/src/sdk/accountExport.test.ts +115 -0
- package/src/sdk/accountExport.ts +254 -0
- package/src/sdk/client-ambient.d.ts +86 -0
- package/src/sdk/client.ts +44 -0
- package/src/sdk/devb.test.ts +148 -0
- package/src/sdk/devb.ts +146 -0
- package/src/sdk/download.test.ts +40 -0
- package/src/sdk/download.ts +48 -0
- package/src/sdk/manifest.test.ts +17 -1
- package/src/sdk/manifest.ts +51 -11
- package/src/sdk/net.test.ts +42 -1
- package/src/sdk/net.ts +100 -2
- package/src/sdk/pool.test.ts +36 -0
- package/src/sdk/pool.ts +26 -0
- package/src/sdk/providers.ts +107 -11
- package/src/sdk/server.ts +402 -13
- package/src/sdk/testing.test.ts +66 -0
- package/src/sdk/testing.ts +222 -2
package/src/sdk/devb.ts
CHANGED
|
@@ -118,3 +118,149 @@ export function openChunk(
|
|
|
118
118
|
export function openStreamDecipher(key: Buffer, nonce: Buffer): crypto.DecipherGCM {
|
|
119
119
|
return crypto.createDecipheriv('aes-256-gcm', key, nonce);
|
|
120
120
|
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Scelle un clair en v2. Ré-agrège en blocs de {@link BLOB_CHUNK_BYTES} quel
|
|
124
|
+
* que soit le découpage d'entrée : l'ouvreur compte les blocs pour retrouver
|
|
125
|
+
* leur rang.
|
|
126
|
+
*/
|
|
127
|
+
export async function* sealStream(
|
|
128
|
+
key: Buffer,
|
|
129
|
+
source: AsyncIterable<Uint8Array>
|
|
130
|
+
): AsyncGenerator<Buffer> {
|
|
131
|
+
const header = createBlobHeader();
|
|
132
|
+
const nonce = header.subarray(5, 17);
|
|
133
|
+
yield header;
|
|
134
|
+
|
|
135
|
+
let pending: Buffer[] = [];
|
|
136
|
+
let pendingLen = 0;
|
|
137
|
+
let index = 0;
|
|
138
|
+
|
|
139
|
+
for await (const part of source) {
|
|
140
|
+
pending.push(Buffer.from(part.buffer, part.byteOffset, part.byteLength));
|
|
141
|
+
pendingLen += part.byteLength;
|
|
142
|
+
while (pendingLen >= BLOB_CHUNK_BYTES) {
|
|
143
|
+
const joined = Buffer.concat(pending, pendingLen);
|
|
144
|
+
yield sealChunk(key, nonce, index, joined.subarray(0, BLOB_CHUNK_BYTES), false);
|
|
145
|
+
index += 1;
|
|
146
|
+
const rest = joined.subarray(BLOB_CHUNK_BYTES);
|
|
147
|
+
pending = rest.length > 0 ? [rest] : [];
|
|
148
|
+
pendingLen = rest.length;
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
// Toujours un dernier bloc, même vide : c'est lui qui porte le marqueur de
|
|
153
|
+
// fin dans l'AAD, et donc ce qui rend un blob tronqué détectable.
|
|
154
|
+
yield sealChunk(key, nonce, index, Buffer.concat(pending, pendingLen), true);
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** Ouvre un flux v2. Lève dès qu'un bloc ne s'authentifie pas : jamais de lecture tolérante. */
|
|
158
|
+
export async function* openSealedStream(
|
|
159
|
+
key: Buffer,
|
|
160
|
+
source: AsyncIterable<Buffer>
|
|
161
|
+
): AsyncGenerator<Buffer> {
|
|
162
|
+
let buffer: Buffer = Buffer.alloc(0);
|
|
163
|
+
let nonce: Buffer | null = null;
|
|
164
|
+
let index = 0;
|
|
165
|
+
|
|
166
|
+
const take = (n: number): Buffer | null => {
|
|
167
|
+
if (buffer.length < n) return null;
|
|
168
|
+
const out = buffer.subarray(0, n);
|
|
169
|
+
buffer = buffer.subarray(n);
|
|
170
|
+
return out;
|
|
171
|
+
};
|
|
172
|
+
|
|
173
|
+
for await (const part of source) {
|
|
174
|
+
buffer = buffer.length === 0 ? part : Buffer.concat([buffer, part]);
|
|
175
|
+
|
|
176
|
+
if (nonce === null) {
|
|
177
|
+
const header = take(BLOB_HEADER_LEN);
|
|
178
|
+
if (header === null) continue;
|
|
179
|
+
const parsed = parseBlobHeader(header);
|
|
180
|
+
if (parsed.version !== BLOB_V2) throw new Error('DEVB : format de bloc inattendu');
|
|
181
|
+
nonce = parsed.nonce;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
// Garder de quoi former un dernier bloc : à exactement `BLOB_CHUNK_SEALED`
|
|
185
|
+
// octets, on ne sait pas s'il est intermédiaire ou final, et l'AAD diffère.
|
|
186
|
+
while (buffer.length > BLOB_CHUNK_SEALED) {
|
|
187
|
+
const sealed = take(BLOB_CHUNK_SEALED);
|
|
188
|
+
if (sealed === null) break;
|
|
189
|
+
yield openChunk(key, nonce, index, sealed, false);
|
|
190
|
+
index += 1;
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
if (nonce === null) throw new Error('DEVB : en-tête absent ou tronqué');
|
|
195
|
+
yield openChunk(key, nonce, index, buffer, true);
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/** Taille sur le disque d'un clair de `plainSize` octets scellé en v2. */
|
|
199
|
+
export function sealedSize(plainSize: number): number {
|
|
200
|
+
const full = Math.floor(plainSize / BLOB_CHUNK_BYTES);
|
|
201
|
+
return (
|
|
202
|
+
BLOB_HEADER_LEN +
|
|
203
|
+
full * BLOB_CHUNK_SEALED +
|
|
204
|
+
(plainSize - full * BLOB_CHUNK_BYTES) +
|
|
205
|
+
BLOB_TAG_LEN
|
|
206
|
+
);
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/**
|
|
210
|
+
* Les octets `[start, end]` (inclus) du clair d'un blob v2 de `plainSize`
|
|
211
|
+
* octets, sans lire le reste : l'en-tête, puis les seuls blocs qui les
|
|
212
|
+
* portent, chacun authentifié avec son rang et son statut de dernier bloc.
|
|
213
|
+
* `read` lit une étendue inclusive du blob scellé, `SdkObjectStore.get` tel
|
|
214
|
+
* quel. Une troncature hors de l'étendue n'est pas vue : c'est une lecture
|
|
215
|
+
* partielle.
|
|
216
|
+
*/
|
|
217
|
+
export async function* openSealedRange(
|
|
218
|
+
key: Buffer,
|
|
219
|
+
read: (range: { start: number; end: number }) => AsyncIterable<Buffer>,
|
|
220
|
+
plainSize: number,
|
|
221
|
+
range: { start: number; end: number }
|
|
222
|
+
): AsyncGenerator<Buffer> {
|
|
223
|
+
const { start, end } = range;
|
|
224
|
+
if (
|
|
225
|
+
!Number.isInteger(start) ||
|
|
226
|
+
!Number.isInteger(end) ||
|
|
227
|
+
start < 0 ||
|
|
228
|
+
end < start ||
|
|
229
|
+
end >= plainSize
|
|
230
|
+
) {
|
|
231
|
+
throw new Error('DEVB : étendue hors du blob');
|
|
232
|
+
}
|
|
233
|
+
const parts: Buffer[] = [];
|
|
234
|
+
for await (const part of read({ start: 0, end: BLOB_HEADER_LEN - 1 })) parts.push(part);
|
|
235
|
+
const { version, nonce } = parseBlobHeader(Buffer.concat(parts));
|
|
236
|
+
if (version !== BLOB_V2) throw new Error('DEVB : format de bloc inattendu');
|
|
237
|
+
|
|
238
|
+
const finalIndex = Math.floor(plainSize / BLOB_CHUNK_BYTES);
|
|
239
|
+
const finalPlain = plainSize - finalIndex * BLOB_CHUNK_BYTES;
|
|
240
|
+
const sealedLength = (i: number) =>
|
|
241
|
+
i === finalIndex ? finalPlain + BLOB_TAG_LEN : BLOB_CHUNK_SEALED;
|
|
242
|
+
const first = Math.floor(start / BLOB_CHUNK_BYTES);
|
|
243
|
+
const last = Math.floor(end / BLOB_CHUNK_BYTES);
|
|
244
|
+
const from = BLOB_HEADER_LEN + first * BLOB_CHUNK_SEALED;
|
|
245
|
+
const to = BLOB_HEADER_LEN + last * BLOB_CHUNK_SEALED + sealedLength(last) - 1;
|
|
246
|
+
|
|
247
|
+
let buffer: Buffer = Buffer.alloc(0);
|
|
248
|
+
let index = first;
|
|
249
|
+
const emit = (plain: Buffer): Buffer => {
|
|
250
|
+
const offset = index * BLOB_CHUNK_BYTES;
|
|
251
|
+
const lo = index === first ? start - offset : 0;
|
|
252
|
+
const hi = index === last ? end - offset + 1 : plain.length;
|
|
253
|
+
return plain.subarray(lo, hi);
|
|
254
|
+
};
|
|
255
|
+
for await (const part of read({ start: from, end: to })) {
|
|
256
|
+
buffer = buffer.length === 0 ? part : Buffer.concat([buffer, part]);
|
|
257
|
+
while (index <= last && buffer.length >= sealedLength(index)) {
|
|
258
|
+
const n = sealedLength(index);
|
|
259
|
+
const plain = openChunk(key, nonce, index, buffer.subarray(0, n), index === finalIndex);
|
|
260
|
+
buffer = buffer.subarray(n);
|
|
261
|
+
yield emit(plain);
|
|
262
|
+
index += 1;
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
if (index <= last) throw new Error('DEVB : blob tronqué');
|
|
266
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import assert from 'node:assert/strict';
|
|
2
|
+
import { describe, it } from 'node:test';
|
|
3
|
+
|
|
4
|
+
import { contentDisposition, parseByteRange } from './download';
|
|
5
|
+
|
|
6
|
+
describe('contentDisposition', () => {
|
|
7
|
+
it('keeps a safe ASCII fallback and the real name in filename*', () => {
|
|
8
|
+
assert.equal(
|
|
9
|
+
contentDisposition('Été "final"\r\n.pdf'),
|
|
10
|
+
`attachment; filename="_t_ final__.pdf"; filename*=UTF-8''${encodeURIComponent('Été "final"\r\n.pdf')}`
|
|
11
|
+
);
|
|
12
|
+
assert.match(contentDisposition('é', 'inline'), /^inline; filename="_"/);
|
|
13
|
+
assert.match(contentDisposition(' '), /filename="fichier"/);
|
|
14
|
+
});
|
|
15
|
+
});
|
|
16
|
+
|
|
17
|
+
describe('parseByteRange', () => {
|
|
18
|
+
it('reads the three forms, clamped to the body', () => {
|
|
19
|
+
assert.deepEqual(parseByteRange('bytes=0-99', 1000), { start: 0, end: 99 });
|
|
20
|
+
assert.deepEqual(parseByteRange('bytes=900-', 1000), { start: 900, end: 999 });
|
|
21
|
+
assert.deepEqual(parseByteRange('bytes=-100', 1000), { start: 900, end: 999 });
|
|
22
|
+
assert.deepEqual(parseByteRange('bytes=-5000', 1000), { start: 0, end: 999 });
|
|
23
|
+
assert.deepEqual(parseByteRange('bytes=10-5000', 1000), { start: 10, end: 999 });
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
it('serves the whole body when there is nothing it can honour', () => {
|
|
27
|
+
assert.equal(parseByteRange(undefined, 1000), null);
|
|
28
|
+
assert.equal(parseByteRange('bytes=0-1,5-9', 1000), null);
|
|
29
|
+
assert.equal(parseByteRange('items=0-1', 1000), null);
|
|
30
|
+
assert.equal(parseByteRange('bytes=-', 1000), null);
|
|
31
|
+
assert.equal(parseByteRange('bytes=9-5', 1000), null);
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
it('calls out what lies past the end', () => {
|
|
35
|
+
assert.equal(parseByteRange('bytes=1000-', 1000), 'unsatisfiable');
|
|
36
|
+
assert.equal(parseByteRange('bytes=-0', 1000), 'unsatisfiable');
|
|
37
|
+
assert.equal(parseByteRange('bytes=0-', 0), 'unsatisfiable');
|
|
38
|
+
assert.equal(parseByteRange('bytes=-10', 0), 'unsatisfiable');
|
|
39
|
+
});
|
|
40
|
+
});
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Serving a stored file over HTTP: the two headers every download route
|
|
3
|
+
* writes, the same way everywhere.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* `Content-Disposition` for a name that came from a user. The plain
|
|
8
|
+
* `filename=` form is reduced to safe ASCII (a newline, which Node rejects
|
|
9
|
+
* outright, would turn the download into a 500); the real name rides in the
|
|
10
|
+
* RFC 5987 `filename*` form, which browsers prefer when both are present.
|
|
11
|
+
* `inline` only for types that cannot run script on your origin.
|
|
12
|
+
*/
|
|
13
|
+
export function contentDisposition(
|
|
14
|
+
filename: string,
|
|
15
|
+
disposition: 'attachment' | 'inline' = 'attachment'
|
|
16
|
+
): string {
|
|
17
|
+
const ascii = filename.replace(/[^\x20-\x7e]/g, '_').replace(/["\\]/g, '');
|
|
18
|
+
const fallback = ascii.trim() || 'fichier';
|
|
19
|
+
return `${disposition}; filename="${fallback}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Reads a `Range` request header against a body of `size` bytes (RFC 9110
|
|
24
|
+
* §14.1.2). One range only: `null` means serve the whole body with a 200 (no
|
|
25
|
+
* header, a malformed one, or several ranges, which a server may ignore);
|
|
26
|
+
* `'unsatisfiable'` calls for a 416 whose `Content-Range` states the size
|
|
27
|
+
* after an asterisk. The range is inclusive, as `SdkObjectStore.get` takes it.
|
|
28
|
+
*/
|
|
29
|
+
export function parseByteRange(
|
|
30
|
+
header: string | undefined,
|
|
31
|
+
size: number
|
|
32
|
+
): { start: number; end: number } | 'unsatisfiable' | null {
|
|
33
|
+
if (header === undefined) return null;
|
|
34
|
+
const match = /^\s*bytes\s*=\s*(\d*)\s*-\s*(\d*)\s*$/i.exec(header);
|
|
35
|
+
if (!match) return null;
|
|
36
|
+
const [, first, last] = match;
|
|
37
|
+
if (first === '' && last === '') return null;
|
|
38
|
+
if (first === '') {
|
|
39
|
+
const suffix = Number(last);
|
|
40
|
+
if (suffix === 0 || size === 0) return 'unsatisfiable';
|
|
41
|
+
return { start: Math.max(0, size - suffix), end: size - 1 };
|
|
42
|
+
}
|
|
43
|
+
const start = Number(first);
|
|
44
|
+
const end = last === '' ? size - 1 : Math.min(Number(last), size - 1);
|
|
45
|
+
if (last !== '' && Number(last) < start) return null;
|
|
46
|
+
if (start >= size) return 'unsatisfiable';
|
|
47
|
+
return { start, end };
|
|
48
|
+
}
|
package/src/sdk/manifest.test.ts
CHANGED
|
@@ -26,12 +26,18 @@ test('validateManifest accepts a minimal external manifest', () => {
|
|
|
26
26
|
assert.doesNotThrow(() => validateManifest(base));
|
|
27
27
|
});
|
|
28
28
|
|
|
29
|
+
test('validateManifest lets an external module with items share them', () => {
|
|
30
|
+
assert.doesNotThrow(() =>
|
|
31
|
+
validateManifest({ ...base, hasItems: true, itemNoun: 'pack', shareTier: 'open' })
|
|
32
|
+
);
|
|
33
|
+
});
|
|
34
|
+
|
|
29
35
|
test('validateManifest rejects the classic mistakes', () => {
|
|
30
36
|
const rejects = (patch: Partial<FeatureManifest>, fragment: string) =>
|
|
31
37
|
assert.throws(() => validateManifest({ ...base, ...patch }), new RegExp(fragment));
|
|
32
38
|
rejects({ label: ' ' }, 'empty label');
|
|
33
39
|
rejects({ hasItems: true }, 'itemNoun');
|
|
34
|
-
rejects({ shareTier: 'open' },
|
|
40
|
+
rejects({ shareTier: 'open' }, 'requires hasItems');
|
|
35
41
|
rejects({ commandPrefix: 'x-demo.' }, 'commandPrefix');
|
|
36
42
|
rejects(
|
|
37
43
|
{ commands: [{ command: 'other.get', input: z.object({}), output: z.object({}) }] },
|
|
@@ -166,6 +172,16 @@ test('validateManifest checks quotas and the account entry', () => {
|
|
|
166
172
|
{ quotas: [{ key: 'storage', label: 'of storage', unit: 'bytes', stock: true }] },
|
|
167
173
|
'a stock counts things'
|
|
168
174
|
);
|
|
175
|
+
assert.doesNotThrow(() =>
|
|
176
|
+
validateManifest({
|
|
177
|
+
...base,
|
|
178
|
+
quotas: [{ key: 'fileBytes', label: 'm', unit: 'bytes', perOperation: true }]
|
|
179
|
+
})
|
|
180
|
+
);
|
|
181
|
+
rejects(
|
|
182
|
+
{ quotas: [{ key: 'monitors', label: 'm', stock: true, perOperation: true }] },
|
|
183
|
+
'a per-operation limit is no stock'
|
|
184
|
+
);
|
|
169
185
|
rejects({ accountOnly: true }, 'accountOnly requires accountEntry');
|
|
170
186
|
rejects({ accountOnly: true, accountEntry: { label: 'S' }, tile: {} }, 'no tile');
|
|
171
187
|
rejects({ accountEntry: { label: ' ' } }, 'requires a label');
|
package/src/sdk/manifest.ts
CHANGED
|
@@ -65,7 +65,9 @@ export const MAX_FEATURE_QUOTAS = 8;
|
|
|
65
65
|
/**
|
|
66
66
|
* Something your feature creates that an account plan may bound (monitors,
|
|
67
67
|
* paired agents). You count, the host decides: see `SdkQuota`. Without a plan
|
|
68
|
-
* provider installed (a self-hosted DevEye), every quota is unlimited.
|
|
68
|
+
* provider installed (a self-hosted DevEye), every quota is unlimited. A quota
|
|
69
|
+
* that is neither `stock` nor `perOperation` is a flow, counted by
|
|
70
|
+
* `server.quotas[key].count`.
|
|
69
71
|
*/
|
|
70
72
|
export interface FeatureQuotaSpec {
|
|
71
73
|
/** Same shape as an extra permission key. The plan names it `<featureId>.<key>`. */
|
|
@@ -79,10 +81,16 @@ export interface FeatureQuotaSpec {
|
|
|
79
81
|
* agent), as opposed to a flow checked at each use (events per month, the
|
|
80
82
|
* size of one file). When the limit drops below what exists, the host
|
|
81
83
|
* pauses the most recently created ones, never deletes them, and resumes
|
|
82
|
-
* them once the limit rises or a slot frees: see `SdkPlanPauses`.
|
|
83
|
-
* `server.quotas[key]`; never with `unit: 'bytes'`.
|
|
84
|
+
* them once the limit rises or a slot frees: see `SdkPlanPauses`. Listed by
|
|
85
|
+
* `server.quotas[key].list`; never with `unit: 'bytes'`.
|
|
84
86
|
*/
|
|
85
87
|
stock?: true;
|
|
88
|
+
/**
|
|
89
|
+
* The limit bounds ONE operation (the size of one file): nothing
|
|
90
|
+
* accumulates, so there is nothing to count, no `server.quotas[key]`, and
|
|
91
|
+
* an account's usage reads `null`. Never with `stock`.
|
|
92
|
+
*/
|
|
93
|
+
perOperation?: true;
|
|
86
94
|
}
|
|
87
95
|
|
|
88
96
|
/** Hard cap on `extraPermissions`: keeps role editors legible. */
|
|
@@ -135,12 +143,32 @@ export type NativeCapability =
|
|
|
135
143
|
*/
|
|
136
144
|
| 'live.publish'
|
|
137
145
|
/**
|
|
138
|
-
* Read accounts (id, email, username, creation date): the
|
|
139
|
-
* handler, any account from a service, by id, by email
|
|
140
|
-
* what belongs to an account and not to a
|
|
141
|
-
* receipt to address).
|
|
146
|
+
* Read accounts (id, email, username, creation date, suspension): the
|
|
147
|
+
* caller's own in a handler, any account from a service, by id, by email,
|
|
148
|
+
* by search or all of them. For what belongs to an account and not to a
|
|
149
|
+
* workspace (a subscription, a receipt to address).
|
|
150
|
+
*/
|
|
151
|
+
| 'accounts.read'
|
|
152
|
+
/**
|
|
153
|
+
* What an account uses of every limit a plan may bound, across every
|
|
154
|
+
* feature (`ctx.deveye.usage`, `deps.usage`): the caller's own, or any
|
|
155
|
+
* account's for a global administrator. What a plan provider shows beside
|
|
156
|
+
* the limits it sets.
|
|
157
|
+
*/
|
|
158
|
+
| 'accounts.usage'
|
|
159
|
+
/**
|
|
160
|
+
* Email an account of this DevEye at its own address, in the server's
|
|
161
|
+
* name (`deps.accountMail`): what the account must receive, by law or by
|
|
162
|
+
* its contract with you (a renewal notice). Never marketing, which the
|
|
163
|
+
* account never agreed to.
|
|
142
164
|
*/
|
|
143
|
-
| 'accounts.
|
|
165
|
+
| 'accounts.mail'
|
|
166
|
+
/**
|
|
167
|
+
* The host's object store (`deps.objects`): the files a module keeps on
|
|
168
|
+
* behalf of its members, on the server's disk or on the S3 bucket the host
|
|
169
|
+
* configured. Declared, because what lands there is billed to the host.
|
|
170
|
+
*/
|
|
171
|
+
| 'objects';
|
|
144
172
|
|
|
145
173
|
/**
|
|
146
174
|
* Settings tabs the shell can render for you.
|
|
@@ -284,7 +312,7 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
|
|
|
284
312
|
* but `'never'` commits the module to the sharing contract: a server entry
|
|
285
313
|
* with `items`, listings that read `ctx.sharing.scope()` and pick the
|
|
286
314
|
* cipher row by row, and `ctx.items.restrictions()` applied to what they
|
|
287
|
-
* return.
|
|
315
|
+
* return. Requires `hasItems`: without items there is nothing to project.
|
|
288
316
|
*/
|
|
289
317
|
shareTier: 'open' | 'perItem' | 'never';
|
|
290
318
|
|
|
@@ -318,6 +346,14 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
|
|
|
318
346
|
* installed module at most may ask for it.
|
|
319
347
|
*/
|
|
320
348
|
accountEntry?: { label: string; signupHint?: boolean };
|
|
349
|
+
/**
|
|
350
|
+
* A page of yours among the system pages of the account menu, which only a
|
|
351
|
+
* global administrator sees and opens: what the operator of the instance
|
|
352
|
+
* handles for everyone (reports to moderate). Needs
|
|
353
|
+
* `FeatureClient.AdminView`, and every command it sends declares
|
|
354
|
+
* `access.admin`. `icon` defaults to the manifest's.
|
|
355
|
+
*/
|
|
356
|
+
adminEntry?: { label: string; icon?: string };
|
|
321
357
|
/**
|
|
322
358
|
* The module lives in the user menu only: no card, no row in the roles
|
|
323
359
|
* screen, `Widget` and `Full` not required. Requires `accountEntry`, no
|
|
@@ -386,8 +422,8 @@ export function validateManifest(m: FeatureManifest): void {
|
|
|
386
422
|
if (!m.label.trim()) fail(m.id, 'empty label');
|
|
387
423
|
if (!m.description.trim()) fail(m.id, 'empty description');
|
|
388
424
|
if (m.hasItems && !m.itemNoun?.trim()) fail(m.id, 'hasItems requires itemNoun');
|
|
389
|
-
if (
|
|
390
|
-
fail(m.id,
|
|
425
|
+
if (m.shareTier !== 'never' && !m.hasItems) {
|
|
426
|
+
fail(m.id, `shareTier '${m.shareTier}' requires hasItems`);
|
|
391
427
|
}
|
|
392
428
|
|
|
393
429
|
if (m.commandPrefix !== undefined) {
|
|
@@ -465,9 +501,13 @@ export function validateManifest(m: FeatureManifest): void {
|
|
|
465
501
|
if (quota.stock && quota.unit === 'bytes') {
|
|
466
502
|
fail(m.id, `quota « ${quota.key} »: a stock counts things`);
|
|
467
503
|
}
|
|
504
|
+
if (quota.stock && quota.perOperation) {
|
|
505
|
+
fail(m.id, `quota « ${quota.key} »: a per-operation limit is no stock`);
|
|
506
|
+
}
|
|
468
507
|
}
|
|
469
508
|
|
|
470
509
|
if (m.accountEntry && !m.accountEntry.label.trim()) fail(m.id, 'accountEntry requires a label');
|
|
510
|
+
if (m.adminEntry && !m.adminEntry.label.trim()) fail(m.id, 'adminEntry requires a label');
|
|
471
511
|
if (m.accountOnly) {
|
|
472
512
|
if (!m.accountEntry) fail(m.id, 'accountOnly requires accountEntry');
|
|
473
513
|
if (m.hasItems) fail(m.id, 'accountOnly modules own no items');
|
package/src/sdk/net.test.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import assert from 'node:assert/strict';
|
|
2
|
+
import { createServer, type Server } from 'node:http';
|
|
2
3
|
import test from 'node:test';
|
|
3
4
|
|
|
4
|
-
import { isPublicIp, isSafePublicUrl } from './net';
|
|
5
|
+
import { isPublicIp, isSafePublicUrl, NetRefused, safeFetchText } from './net';
|
|
5
6
|
|
|
6
7
|
test('isPublicIp: the private ranges of both families read as false', () => {
|
|
7
8
|
for (const ip of ['8.8.8.8', '1.1.1.1', '2001:4860:4860::8888']) {
|
|
@@ -49,3 +50,43 @@ test('isSafePublicUrl: only public http(s) hosts, string or URL', () => {
|
|
|
49
50
|
assert.equal(isSafePublicUrl(url), false, url);
|
|
50
51
|
}
|
|
51
52
|
});
|
|
53
|
+
|
|
54
|
+
const OPTIONS = { maxBytes: 1024, timeoutMs: 2000 };
|
|
55
|
+
|
|
56
|
+
async function listening(
|
|
57
|
+
handler: Parameters<typeof createServer>[1]
|
|
58
|
+
): Promise<{ url: string; close: () => void }> {
|
|
59
|
+
const server: Server = createServer(handler);
|
|
60
|
+
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
|
|
61
|
+
const address = server.address();
|
|
62
|
+
const port = typeof address === 'object' && address !== null ? address.port : 0;
|
|
63
|
+
return { url: `http://127.0.0.1:${port}`, close: () => server.close() };
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
test('safeFetchText: a loopback server is refused before any connection', async () => {
|
|
67
|
+
let touched = false;
|
|
68
|
+
const server = await listening((_req, res) => {
|
|
69
|
+
touched = true;
|
|
70
|
+
res.end('token');
|
|
71
|
+
});
|
|
72
|
+
try {
|
|
73
|
+
await assert.rejects(safeFetchText(server.url, OPTIONS), NetRefused);
|
|
74
|
+
assert.equal(touched, false);
|
|
75
|
+
} finally {
|
|
76
|
+
server.close();
|
|
77
|
+
}
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
test('safeFetchText: other schemes, names that do not resolve and private IPs are refused', async () => {
|
|
81
|
+
for (const url of [
|
|
82
|
+
'file:///etc/passwd',
|
|
83
|
+
'gopher://example.com',
|
|
84
|
+
'ftp://example.com/a',
|
|
85
|
+
'https://this-name-does-not-exist.invalid/a.ics',
|
|
86
|
+
'http://169.254.169.254/latest/meta-data/',
|
|
87
|
+
'http://10.0.0.1/',
|
|
88
|
+
'http://[::1]/'
|
|
89
|
+
]) {
|
|
90
|
+
await assert.rejects(safeFetchText(url, OPTIONS), NetRefused, url);
|
|
91
|
+
}
|
|
92
|
+
});
|
package/src/sdk/net.ts
CHANGED
|
@@ -6,11 +6,13 @@
|
|
|
6
6
|
* because an external module has no import path into the app: without this, a
|
|
7
7
|
* third-party module either reimplements the ranges or ships no guard at all.
|
|
8
8
|
*
|
|
9
|
-
*
|
|
9
|
+
* The predicates do no I/O: a hostname is NOT resolved. DNS would change under
|
|
10
10
|
* the caller's feet between the check and the connection anyway, so the answer
|
|
11
11
|
* is about the URL, and a caller that must also bound the address it finally
|
|
12
|
-
* connects to has to say so at connection time.
|
|
12
|
+
* connects to has to say so at connection time. `safeFetchText` is the one
|
|
13
|
+
* fetch built on them, for a small text body (a domain's proof, a calendar).
|
|
13
14
|
*/
|
|
15
|
+
import { resolve4, resolve6 } from 'node:dns/promises';
|
|
14
16
|
import { isIP } from 'node:net';
|
|
15
17
|
|
|
16
18
|
/**
|
|
@@ -74,3 +76,99 @@ export function isSafePublicUrl(input: URL | string): boolean {
|
|
|
74
76
|
if (isIP(bare) !== 0) return isPublicIp(bare);
|
|
75
77
|
return true;
|
|
76
78
|
}
|
|
79
|
+
|
|
80
|
+
const MAX_REDIRECTS = 3;
|
|
81
|
+
|
|
82
|
+
/** What `safeFetchText` throws for anything it refuses, its message readable as is. */
|
|
83
|
+
export class NetRefused extends Error {}
|
|
84
|
+
|
|
85
|
+
/** Do all the addresses of a name read as public? A name without any address is refused. */
|
|
86
|
+
export async function resolvesPublicly(host: string): Promise<boolean> {
|
|
87
|
+
const bare = host.replace(/^\[|\]$/g, '');
|
|
88
|
+
if (isIP(bare) !== 0) return isPublicIp(bare);
|
|
89
|
+
const found: string[] = [];
|
|
90
|
+
for (const lookup of [resolve4(host), resolve6(host)]) {
|
|
91
|
+
try {
|
|
92
|
+
found.push(...(await lookup));
|
|
93
|
+
} catch {
|
|
94
|
+
// One family missing is not an error; both missing is.
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
return found.length > 0 && found.every((address) => isPublicIp(address));
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
export interface SafeFetchOptions {
|
|
101
|
+
/** The read stops beyond it: a hostile server does not fill the memory. */
|
|
102
|
+
maxBytes: number;
|
|
103
|
+
timeoutMs: number;
|
|
104
|
+
/** Required of the final response, as a prefix. Omitted: anything. */
|
|
105
|
+
contentType?: string;
|
|
106
|
+
accept?: string;
|
|
107
|
+
userAgent?: string;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Fetches a text body, refusing anything off the public network: the URL,
|
|
112
|
+
* every address its name resolves to, and the same again at each redirect.
|
|
113
|
+
* Rebinding between the resolution and the connection stays possible with a
|
|
114
|
+
* bare `fetch`: fine for a token you compare, which is why the body is capped.
|
|
115
|
+
*/
|
|
116
|
+
export async function safeFetchText(raw: string, options: SafeFetchOptions): Promise<string> {
|
|
117
|
+
let target = raw;
|
|
118
|
+
|
|
119
|
+
for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
|
|
120
|
+
if (!isSafePublicUrl(target)) {
|
|
121
|
+
throw new NetRefused('Adresse refusée : elle n’est pas publique.');
|
|
122
|
+
}
|
|
123
|
+
const url = new URL(target);
|
|
124
|
+
if (!(await resolvesPublicly(url.hostname))) {
|
|
125
|
+
throw new NetRefused('Adresse refusée : elle ne résout pas vers une adresse publique.');
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
const response = await fetch(url, {
|
|
129
|
+
redirect: 'manual',
|
|
130
|
+
signal: AbortSignal.timeout(options.timeoutMs),
|
|
131
|
+
headers: {
|
|
132
|
+
accept: options.accept ?? 'text/plain, */*',
|
|
133
|
+
'user-agent': options.userAgent ?? 'DevEye/1.0'
|
|
134
|
+
}
|
|
135
|
+
});
|
|
136
|
+
|
|
137
|
+
if (response.status >= 300 && response.status < 400) {
|
|
138
|
+
const next = response.headers.get('location');
|
|
139
|
+
if (next === null) throw new NetRefused('Redirection sans destination.');
|
|
140
|
+
target = new URL(next, url).toString();
|
|
141
|
+
continue;
|
|
142
|
+
}
|
|
143
|
+
if (!response.ok) throw new NetRefused(`Réponse ${response.status}`);
|
|
144
|
+
|
|
145
|
+
const kind = (response.headers.get('content-type') ?? '').toLowerCase();
|
|
146
|
+
if (options.contentType !== undefined && !kind.startsWith(options.contentType)) {
|
|
147
|
+
throw new NetRefused(`Type inattendu : ${kind.split(';')[0] || 'aucun'}`);
|
|
148
|
+
}
|
|
149
|
+
return readBounded(response, options.maxBytes);
|
|
150
|
+
}
|
|
151
|
+
throw new NetRefused('Trop de redirections.');
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
async function readBounded(response: Response, maxBytes: number): Promise<string> {
|
|
155
|
+
const body = response.body;
|
|
156
|
+
if (body === null) return '';
|
|
157
|
+
|
|
158
|
+
const reader = body.getReader();
|
|
159
|
+
const chunks: Uint8Array[] = [];
|
|
160
|
+
let size = 0;
|
|
161
|
+
for (;;) {
|
|
162
|
+
const { done, value } = await reader.read();
|
|
163
|
+
if (done) break;
|
|
164
|
+
size += value.byteLength;
|
|
165
|
+
if (size > maxBytes) {
|
|
166
|
+
await reader.cancel();
|
|
167
|
+
throw new NetRefused(
|
|
168
|
+
`Réponse trop longue (plus de ${Math.round(maxBytes / 1024)} ko).`
|
|
169
|
+
);
|
|
170
|
+
}
|
|
171
|
+
chunks.push(value);
|
|
172
|
+
}
|
|
173
|
+
return Buffer.concat(chunks).toString('utf8');
|
|
174
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import assert from 'node:assert/strict';
|
|
2
|
+
import { describe, it } from 'node:test';
|
|
3
|
+
|
|
4
|
+
import { mapLimit } from './pool';
|
|
5
|
+
|
|
6
|
+
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
7
|
+
|
|
8
|
+
describe('mapLimit', () => {
|
|
9
|
+
it('keeps the order and never runs more than the limit at once', async () => {
|
|
10
|
+
let running = 0;
|
|
11
|
+
let peak = 0;
|
|
12
|
+
const out = await mapLimit([30, 5, 20, 1, 10, 2], 2, async (ms, i) => {
|
|
13
|
+
running++;
|
|
14
|
+
peak = Math.max(peak, running);
|
|
15
|
+
await sleep(ms);
|
|
16
|
+
running--;
|
|
17
|
+
return `${i}:${ms}`;
|
|
18
|
+
});
|
|
19
|
+
assert.deepEqual(out, ['0:30', '1:5', '2:20', '3:1', '4:10', '5:2']);
|
|
20
|
+
assert.equal(peak, 2);
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
it('lets fast items pass a slow one instead of waiting for it', async () => {
|
|
24
|
+
const done: number[] = [];
|
|
25
|
+
await mapLimit([50, 1, 1, 1], 2, async (ms, i) => {
|
|
26
|
+
await sleep(ms);
|
|
27
|
+
done.push(i);
|
|
28
|
+
});
|
|
29
|
+
assert.deepEqual(done, [1, 2, 3, 0]);
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
it('resolves at once on nothing, and treats a limit below one as one', async () => {
|
|
33
|
+
assert.deepEqual(await mapLimit([], 4, () => Promise.resolve(1)), []);
|
|
34
|
+
assert.deepEqual(await mapLimit([1, 2], 0, (n) => Promise.resolve(n * 2)), [2, 4]);
|
|
35
|
+
});
|
|
36
|
+
});
|
package/src/sdk/pool.ts
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Runs `fn` on every item, at most `limit` at once, and resolves in the items'
|
|
3
|
+
* order. A pool, not waves: a slow item holds one slot, never the whole
|
|
4
|
+
* batch, which is what lets a scheduler probe a hundred targets when a few
|
|
5
|
+
* of them hang until their timeout.
|
|
6
|
+
*/
|
|
7
|
+
export async function mapLimit<T, R>(
|
|
8
|
+
items: readonly T[],
|
|
9
|
+
limit: number,
|
|
10
|
+
fn: (item: T, index: number) => Promise<R>
|
|
11
|
+
): Promise<R[]> {
|
|
12
|
+
const out = new Array<R>(items.length);
|
|
13
|
+
let next = 0;
|
|
14
|
+
const workers = Array.from(
|
|
15
|
+
{ length: Math.min(Math.max(1, Math.floor(limit)), items.length) },
|
|
16
|
+
async () => {
|
|
17
|
+
for (;;) {
|
|
18
|
+
const i = next++;
|
|
19
|
+
if (i >= items.length) return;
|
|
20
|
+
out[i] = await fn(items[i], i);
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
);
|
|
24
|
+
await Promise.all(workers);
|
|
25
|
+
return out;
|
|
26
|
+
}
|