@deveye/types 0.20.3 → 0.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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`. Requires
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 caller's own in a
139
- * handler, any account from a service, by id, by email or by search. For
140
- * what belongs to an account and not to a workspace (a subscription, 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.read';
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. External modules declare `'never'` for now.
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 (external && m.shareTier !== 'never') {
390
- fail(m.id, "external modules must declare shareTier 'never' for now");
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');
@@ -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
- * Pure predicates, no I/O: a hostname is NOT resolved. DNS would change under
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
+ });
@@ -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
+ }
@@ -182,17 +182,15 @@ export interface MailTransportProvider {
182
182
  * `text` stays mandatory whatever else is given: a recipient whose client
183
183
  * shows no HTML must lose nothing.
184
184
  */
185
- send(
186
- accountId: number,
187
- workspaceId: number,
188
- message: {
189
- to: string;
190
- subject: string;
191
- text: string;
192
- html?: string;
193
- attachments?: readonly MailAttachment[];
194
- }
195
- ): Promise<boolean>;
185
+ send(accountId: number, workspaceId: number, message: MailTransportMessage): Promise<boolean>;
186
+ }
187
+
188
+ export interface MailTransportMessage {
189
+ to: string;
190
+ subject: string;
191
+ text: string;
192
+ html?: string;
193
+ attachments?: readonly MailAttachment[];
196
194
  }
197
195
 
198
196
  /**
@@ -223,6 +221,62 @@ export interface AudienceItemsProvider {
223
221
  labelOf(siteId: number, workspaceId: number): Promise<string | null>;
224
222
  }
225
223
 
224
+ /**
225
+ * Key under `FeatureService.providers` for DevEye's own usage figures: the
226
+ * app reports the pages its members open and the actions they take into an
227
+ * Audience site of this very instance, chosen by an administrator. Absent
228
+ * module: nothing is reported, and the admin page says why.
229
+ */
230
+ export const AUDIENCE_SELF_PROVIDER = 'audience.self' as const;
231
+
232
+ export interface AudienceSelfSite {
233
+ siteId: number;
234
+ workspaceId: number;
235
+ name: string;
236
+ active: boolean;
237
+ }
238
+
239
+ /** One measure, as the public beacon takes it: a page or an action, never who. */
240
+ export interface AudienceSelfEvent {
241
+ type: 'view' | 'event';
242
+ /** A static path (`/uptime/settings`), never an id or a name. */
243
+ path: string;
244
+ /** Required for an `event`. */
245
+ name?: string;
246
+ /** Milliseconds since the epoch; now when absent. */
247
+ at?: number;
248
+ referrer?: string;
249
+ language?: string;
250
+ timezone?: string;
251
+ tzOffset?: number;
252
+ screenWidth?: number;
253
+ }
254
+
255
+ export interface AudienceSelfProvider {
256
+ /**
257
+ * Creates an anonymous site for this host in this workspace, active, with
258
+ * no per-visitor limit. The caller owns the authorisation; the owner's
259
+ * plan still applies.
260
+ */
261
+ createSite(
262
+ workspaceId: number,
263
+ input: { name: string; host: string }
264
+ ): Promise<AudienceSelfSite & { publicKey: string }>;
265
+ /** The site behind this key, wherever it lives; `null` when unknown. */
266
+ findByKey(publicKey: string): Promise<AudienceSelfSite | null>;
267
+ /**
268
+ * Queued as if sent through the public beacon by that visitor, the Origin
269
+ * check aside: the app vouches for them. The bot filter and the plan's
270
+ * monthly limit still apply. Never throws.
271
+ */
272
+ ingest(req: {
273
+ key: string;
274
+ ip: string;
275
+ userAgent: string;
276
+ events: readonly AudienceSelfEvent[];
277
+ }): void;
278
+ }
279
+
226
280
  /**
227
281
  * Key under `FeatureClient.providers` for the Audience pieces the app's
228
282
  * Projects screens compose: the list of the workspace's sites, a linked site
@@ -297,6 +351,33 @@ export const DEPLOY_CLIENT_PROVIDER = 'deploy.client' as const;
297
351
  */
298
352
  export const DATABASE_CLIENT_PROVIDER = 'database.client' as const;
299
353
 
354
+ /**
355
+ * Key under `FeatureService.providers` for the Hosting folders the app's
356
+ * Projects feature links to: same shape and same reason as
357
+ * `UPTIME_ITEMS_PROVIDER` (`project_hosting_links` is Projects' table).
358
+ * Hosting is a private module: absent, the tab never shows and nothing links.
359
+ */
360
+ export const HOSTING_ITEMS_PROVIDER = 'hosting.items' as const;
361
+
362
+ export interface HostingItemsProvider {
363
+ /** Is this folder visible from this workspace: its home, or one it is projected into? */
364
+ exists(packId: number, workspaceId: number): Promise<boolean>;
365
+ /**
366
+ * The item's display name as seen from `workspaceId` (its home, or a
367
+ * workspace it is projected into): the provider resolves the home and its
368
+ * OPEN cipher itself. `null` when it is gone or unreadable.
369
+ */
370
+ labelOf(packId: number, workspaceId: number): Promise<string | null>;
371
+ }
372
+
373
+ /**
374
+ * Key under `FeatureClient.providers` for the Hosting pieces the app's
375
+ * Projects screens compose: the list of the workspace's folders, a linked
376
+ * folder shown inside a project's tab, and the feature's own folder dialog.
377
+ * The contract types live in `@deveye/types/sdk/client`.
378
+ */
379
+ export const HOSTING_CLIENT_PROVIDER = 'hosting.client' as const;
380
+
300
381
  /**
301
382
  * Key of what Projects knows about the items of OTHER features: the projects
302
383
  * of the workspace that link them (a module's list shows how many projects use
@@ -564,6 +645,12 @@ export interface AccountPlan {
564
645
  label: string;
565
646
  /** `<featureId>.<quotaKey>` to its maximum. An absent key is unlimited. */
566
647
  limits: Readonly<Record<string, number>>;
648
+ /**
649
+ * The account is served first when the host sheds load. While the admin
650
+ * gives priority to such accounts, every limit of the others reads 0: their
651
+ * stock is paused and their creations refused, until the mode ends.
652
+ */
653
+ priority: boolean;
567
654
  /** The plan is a trial ending then (ms since the epoch). */
568
655
  trialEndsAt?: number;
569
656
  /**
@@ -573,6 +660,15 @@ export interface AccountPlan {
573
660
  changesAt?: number;
574
661
  }
575
662
 
663
+ /**
664
+ * Whether a plan is a paying one: the paid tier (trial included), an
665
+ * administrator, a plan granted on the paid tier (`priority`), or no provider
666
+ * at all (`null`, a self-hosted instance).
667
+ */
668
+ export function isPaidPlan(plan: AccountPlan | null): boolean {
669
+ return plan === null || plan.id === 'pro' || plan.id === 'admin' || plan.priority;
670
+ }
671
+
576
672
  export interface AccountPlanProvider {
577
673
  /** `fresh`: never from a cache, the host is about to pause or resume on the answer. */
578
674
  planFor(userId: number, opts?: { fresh?: boolean }): Promise<AccountPlan>;