@deveye/types 0.24.5 → 0.25.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.
@@ -93,6 +93,16 @@ export interface FeatureQuotaSpec {
93
93
  perOperation?: true;
94
94
  }
95
95
 
96
+ /** One tab of `adminTabs`. */
97
+ export interface AdminTabSpec {
98
+ /** Same shape as an extra permission key: the key of `FeatureClient.AdminTabs` and of `adminPending`. */
99
+ id: string;
100
+ /** A noun, as a tab reads: "Reports". */
101
+ label: string;
102
+ /** Moderators open it too; without it, global administrators only. */
103
+ moderation?: true;
104
+ }
105
+
96
106
  /** Hard cap on `extraPermissions`: keeps role editors legible. */
97
107
  export const MAX_EXTRA_PERMISSIONS = 10;
98
108
 
@@ -168,7 +178,12 @@ export type NativeCapability =
168
178
  * behalf of its members, on the server's disk or on the S3 bucket the host
169
179
  * configured. Declared, because what lands there is billed to the host.
170
180
  */
171
- | 'objects';
181
+ | 'objects'
182
+ /**
183
+ * The country of a client address (`deps.geo`), from a database the host
184
+ * downloads and refreshes only while an installed module declares this.
185
+ */
186
+ | 'geoip';
172
187
 
173
188
  /**
174
189
  * Settings tabs the shell can render for you.
@@ -359,13 +374,15 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
359
374
  adminTools?: boolean;
360
375
  };
361
376
  /**
362
- * A page of yours among the system pages of the account menu, which only a
363
- * global administrator sees and opens: what the operator of the instance
364
- * handles for everyone (reports to moderate). Needs
365
- * `FeatureClient.AdminView`, and every command it sends declares
366
- * `access.admin`. `icon` defaults to the manifest's.
377
+ * Your tabs in the feature administration popup, after the overview the
378
+ * host draws: what the operator of the instance handles for everyone,
379
+ * across accounts. A `moderation` tab (reports to handle) also opens to
380
+ * moderators, and every command it sends declares `access.moderation`;
381
+ * any other is for global administrators only, its commands declaring
382
+ * `access.admin`. Each id needs its component in `FeatureClient.AdminTabs`;
383
+ * `server.adminPending` lights the badges, by tab id.
367
384
  */
368
- adminEntry?: { label: string; icon?: string };
385
+ adminTabs?: readonly AdminTabSpec[];
369
386
  /**
370
387
  * The module lives in the user menu only: no card, no row in the roles
371
388
  * screen, `Widget` and `Full` not required. Requires `accountEntry`, no
@@ -526,7 +543,13 @@ export function validateManifest(m: FeatureManifest): void {
526
543
  }
527
544
 
528
545
  if (m.accountEntry && !m.accountEntry.label.trim()) fail(m.id, 'accountEntry requires a label');
529
- if (m.adminEntry && !m.adminEntry.label.trim()) fail(m.id, 'adminEntry requires a label');
546
+ const adminTabIds = new Set<string>();
547
+ for (const tab of m.adminTabs ?? []) {
548
+ if (!EXTRA_KEY_PATTERN.test(tab.id)) fail(m.id, `invalid admin tab id « ${tab.id} »`);
549
+ if (adminTabIds.has(tab.id)) fail(m.id, `duplicate admin tab id « ${tab.id} »`);
550
+ adminTabIds.add(tab.id);
551
+ if (!tab.label.trim()) fail(m.id, `admin tab « ${tab.id} »: empty label`);
552
+ }
530
553
  if (m.accountOnly) {
531
554
  if (!m.accountEntry) fail(m.id, 'accountOnly requires accountEntry');
532
555
  if (m.hasItems) fail(m.id, 'accountOnly modules own no items');
@@ -5,7 +5,7 @@ import test from 'node:test';
5
5
  import { isPublicIp, isRemoteFailure, isSafePublicUrl, NetRefused, safeFetchText } from './net';
6
6
 
7
7
  test('isPublicIp: the private ranges of both families read as false', () => {
8
- for (const ip of ['8.8.8.8', '1.1.1.1', '2001:4860:4860::8888']) {
8
+ for (const ip of ['8.8.8.8', '1.1.1.1', '2001:4860:4860::8888', '::ffff:808:808']) {
9
9
  assert.equal(isPublicIp(ip), true, ip);
10
10
  }
11
11
  for (const ip of [
@@ -21,8 +21,13 @@ test('isPublicIp: the private ranges of both families read as false', () => {
21
21
  '::1',
22
22
  'fd00::1',
23
23
  'fe80::1',
24
- // IPv4-mapped: judged on the v4 part, not on the v6 prefix.
24
+ // IPv4 written in IPv6, dotted or in the hex form a URL parser gives
25
+ // back: judged on the v4 part, not on the v6 prefix.
25
26
  '::ffff:127.0.0.1',
27
+ '::ffff:7f00:1',
28
+ '::ffff:a9fe:a9fe',
29
+ '::ffff:a00:1',
30
+ '::7f00:1',
26
31
  'not-an-ip'
27
32
  ]) {
28
33
  assert.equal(isPublicIp(ip), false, ip);
@@ -40,6 +45,9 @@ test('isSafePublicUrl: only public http(s) hosts, string or URL', () => {
40
45
  'https://app.localhost',
41
46
  'http://192.168.1.10/admin',
42
47
  'http://[::1]:8080',
48
+ // The parser turns these into `[::ffff:7f00:1]` and `[::ffff:a9fe:a9fe]`.
49
+ 'http://[::ffff:127.0.0.1]:3000/',
50
+ 'http://[::ffff:169.254.169.254]/latest/meta-data/',
43
51
  // Anything but http(s): a git `ext::` or a `file://` would run a
44
52
  // command or read the server's disk.
45
53
  'file:///etc/passwd',
package/src/sdk/net.ts CHANGED
@@ -13,41 +13,46 @@
13
13
  * fetch built on them, for a small text body (a domain's proof, a calendar).
14
14
  */
15
15
  import { resolve4, resolve6 } from 'node:dns/promises';
16
- import { isIP } from 'node:net';
16
+ import { BlockList, isIP } from 'node:net';
17
17
 
18
18
  /**
19
- * Is this a public, routable IP address? Loopback, private ranges, link-local,
20
- * CGNAT and multicast all read as false, in both families.
19
+ * Every address that is not public, in both families: loopback, private
20
+ * ranges, link-local, CGNAT, multicast and reserved, and the IPv4-compatible
21
+ * `::/96` (which holds `::` and `::1`).
21
22
  */
22
- export function isPublicIp(raw: string): boolean {
23
- const ip = raw.replace(/^\[|\]$/g, '').toLowerCase();
24
- const v = isIP(ip);
25
- if (v === 0) return false;
26
-
27
- if (v === 4) return isPublicIpv4(ip);
28
-
29
- // IPv4-mapped or compatible: judge the real v4 part.
30
- const mapped = ip.match(/^::(?:ffff:)?(\d+\.\d+\.\d+\.\d+)$/);
31
- if (mapped) return isPublicIpv4(mapped[1]);
32
-
33
- if (ip === '::' || ip === '::1') return false;
34
- // fc00::/7 (unique-local), fe80::/10 (link-local), ff00::/8 (multicast).
35
- if (/^f[cd]/.test(ip)) return false;
36
- if (/^fe[89ab]/.test(ip)) return false;
37
- if (/^ff/.test(ip)) return false;
38
- return true;
23
+ const NON_PUBLIC = new BlockList();
24
+ for (const [net, prefix] of [
25
+ ['0.0.0.0', 8],
26
+ ['10.0.0.0', 8],
27
+ ['100.64.0.0', 10],
28
+ ['127.0.0.0', 8],
29
+ ['169.254.0.0', 16],
30
+ ['172.16.0.0', 12],
31
+ ['192.168.0.0', 16],
32
+ ['224.0.0.0', 3]
33
+ ] as const) {
34
+ NON_PUBLIC.addSubnet(net, prefix, 'ipv4');
35
+ }
36
+ for (const [net, prefix] of [
37
+ ['::', 96],
38
+ ['fc00::', 7],
39
+ ['fe80::', 10],
40
+ ['ff00::', 8]
41
+ ] as const) {
42
+ NON_PUBLIC.addSubnet(net, prefix, 'ipv6');
39
43
  }
40
44
 
41
- function isPublicIpv4(ip: string): boolean {
42
- const o = ip.split('.').map(Number);
43
- if (o.length !== 4 || o.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return false;
44
- if (o[0] === 0 || o[0] === 10 || o[0] === 127) return false;
45
- if (o[0] === 169 && o[1] === 254) return false; // link-local
46
- if (o[0] === 172 && o[1] >= 16 && o[1] <= 31) return false;
47
- if (o[0] === 192 && o[1] === 168) return false;
48
- if (o[0] === 100 && o[1] >= 64 && o[1] <= 127) return false; // CGNAT
49
- if (o[0] >= 224) return false; // multicast and reserved
50
- return true;
45
+ /**
46
+ * Is this a public, routable IP address? Loopback, private ranges, link-local,
47
+ * CGNAT and multicast all read as false, in both families. An IPv4 address
48
+ * written in IPv6 (`::ffff:7f00:1`, the form a URL parser gives back) is judged
49
+ * on its IPv4 part: `BlockList.check` matches it against the IPv4 rules.
50
+ */
51
+ export function isPublicIp(raw: string): boolean {
52
+ const ip = raw.replace(/^\[|\]$/g, '');
53
+ const family = isIP(ip);
54
+ if (family === 0) return false;
55
+ return !NON_PUBLIC.check(ip, family === 4 ? 'ipv4' : 'ipv6');
51
56
  }
52
57
 
53
58
  /**
@@ -205,6 +205,13 @@ export interface DatabaseMeasureProvider {
205
205
  workspaceId: number,
206
206
  queries: readonly string[]
207
207
  ): Promise<readonly DatabaseNumberOutcome[] | null>;
208
+ /**
209
+ * May this member run their own queries against the database? The same
210
+ * right as exploring it from the feature's screens, the item's override
211
+ * included: a measurement reads any table. Ask it before linking a
212
+ * database and before saving, testing or running a measurement.
213
+ */
214
+ authorize(databaseId: number, workspaceId: number, userId: number): Promise<SdkAccessVerdict>;
208
215
  }
209
216
 
210
217
  export const DATABASE_ITEMS_PROVIDER = 'database.items' as const;
package/src/sdk/server.ts CHANGED
@@ -17,6 +17,7 @@ import type { SdkDnsRecord } from './domains';
17
17
  import type { MailTransportMessage } from './providers';
18
18
  import type { ModuleEnvSpec } from './env';
19
19
  import type { ExternalService } from '../domain/externalService';
20
+ import type { AdminFeatureFact } from '../features/admin';
20
21
  import type {
21
22
  AgentSyncAckPayload,
22
23
  AgentSyncApplyChunkPayload,
@@ -81,6 +82,14 @@ export {
81
82
  normaliseDomainHost,
82
83
  type SdkDnsRecord
83
84
  } from './domains';
85
+ export {
86
+ looksLikeBot,
87
+ normalizeReferrer,
88
+ originHost,
89
+ parseUserAgent,
90
+ visitorRef,
91
+ type UserAgentInfo
92
+ } from './visitors';
84
93
 
85
94
  /**
86
95
  * Server-side SDK surface: what a feature module's handlers and background
@@ -263,6 +272,24 @@ export interface SdkTelemetrySnapshot {
263
272
  activeConnections: number | null;
264
273
  }
265
274
 
275
+ /**
276
+ * The country of a client address, from a database the host downloads and
277
+ * refreshes on its own (capability `'geoip'`). Answers from memory: cheap
278
+ * enough for a public route. Keep the country, never the address.
279
+ */
280
+ export interface SdkGeo {
281
+ /**
282
+ * The ISO 3166-1 alpha-2 code (`FR`), or `null` for a private or unknown
283
+ * address, and while the database is not loaded yet.
284
+ */
285
+ country(ip: string): string | null;
286
+ /**
287
+ * The credit the database's licence requires next to whatever shows its
288
+ * results, with its link: show both wherever a country appears.
289
+ */
290
+ readonly attribution: { text: string; url: string };
291
+ }
292
+
266
293
  /**
267
294
  * Read access to the devices' telemetry (capability `'telemetry.read'`,
268
295
  * reserved to native-id modules: the metric store is app infrastructure).
@@ -348,13 +375,36 @@ export interface DevEyeFacade {
348
375
  /**
349
376
  * Throws `not_found` unless the device exists AND is visible in this
350
377
  * workspace (its own, or shared into it), a global administrator
351
- * included: membership is the boundary. With `extras`, a handler also requires the CALLER to hold these
352
- * permissions of the Devices feature on this device (`docker` to drive
353
- * its containers), and throws `forbidden` otherwise: a module cannot
354
- * name another feature's permissions in its own `access`.
378
+ * included: membership is the boundary. In a command, the CALLER must
379
+ * also see it: Devices open to their role, and the device not hidden
380
+ * from it. `level: 'write'` requires the device writable for them
381
+ * (`forbidden` on a read-only one), for a handler that changes what
382
+ * the machine does. With `extras`, a handler also requires the CALLER
383
+ * to hold these permissions of the Devices feature on this device
384
+ * (`docker` to drive its containers), and throws `forbidden`
385
+ * otherwise: a module cannot name another feature's permissions in its
386
+ * own `access`.
387
+ *
388
+ * `control: true` where the handler is about to make the machine act
389
+ * (save a source it reads, a target it deploys to, a folder it syncs):
390
+ * the caller must also have confirmed with an authenticator code
391
+ * lately, `stepup_required` otherwise, which the client turns into the
392
+ * prompt and a retry. Leave it out of a mere check of rights (a list of
393
+ * what the caller could pick).
394
+ */
395
+ authorize(
396
+ deviceId: string,
397
+ options?: { level?: FeatureAccess; extras?: readonly string[]; control?: boolean }
398
+ ): Promise<SdkDevice>;
399
+ /**
400
+ * The `control` confirmation alone, where no device exists yet (a code
401
+ * that pairs new machines).
402
+ */
403
+ assertControl(): Promise<void>;
404
+ /**
405
+ * The devices this workspace sees: its own, and those shared into it.
406
+ * In a command, without those hidden from the caller.
355
407
  */
356
- authorize(deviceId: string, options?: { extras?: readonly string[] }): Promise<SdkDevice>;
357
- /** The devices this workspace sees: its own, and those shared into it. */
358
408
  list(): Promise<readonly SdkDevice[]>;
359
409
  isOnline(deviceId: string): boolean;
360
410
  };
@@ -391,6 +441,8 @@ export interface SdkAccount {
391
441
  username: string;
392
442
  /** A global administrator of this DevEye. */
393
443
  isAdmin: boolean;
444
+ /** A moderator or a global administrator: the accounts that handle reports. */
445
+ canModerate: boolean;
394
446
  /**
395
447
  * A throwaway account the app's end-to-end runner created and will delete:
396
448
  * never a person, and its address receives nothing. Check this, never the
@@ -482,12 +534,14 @@ export interface SdkAccountMail {
482
534
  */
483
535
  send(userId: number, message: SdkAccountMailMessage): Promise<string>;
484
536
  /**
485
- * One copy to each active administrator of this DevEye, for what only the
486
- * operator can act on (a report of illicit content). Resolves the addresses
487
- * reached, empty when there is no active administrator. Every address is
488
- * tried; the first refusal then rejects. Throws `conflict` without a transport.
537
+ * One copy to each active moderator and administrator of this DevEye, for
538
+ * what awaits their decision (a report of illicit content). A moderator
539
+ * never sees where a report came from: leave the reporter's address and IP
540
+ * out of the message. Resolves the addresses reached, empty when there is
541
+ * no one. Every address is tried; the first refusal then rejects. Throws
542
+ * `conflict` without a transport.
489
543
  */
490
- sendToAdmins(message: SdkAccountMailMessage): Promise<readonly string[]>;
544
+ sendToModerators(message: SdkAccountMailMessage): Promise<readonly string[]>;
491
545
  }
492
546
 
493
547
  /**
@@ -677,7 +731,11 @@ export interface AgentsFacade {
677
731
  */
678
732
  requestFilesMutate(deviceId: string, payload: AgentFilesMutatePayload): boolean;
679
733
  requestFilesUpload(deviceId: string, payload: AgentFilesUploadPayload): boolean;
680
- awaitFilesOp(opId: string, timeoutMs: number): Promise<{ ok: boolean; error?: string }>;
734
+ awaitFilesOp(
735
+ deviceId: string,
736
+ opId: string,
737
+ timeoutMs: number
738
+ ): Promise<{ ok: boolean; error?: string }>;
681
739
  /** Forgets a pending `awaitFilesOp` (the frame was never sent, or the caller gave up). */
682
740
  cancelFilesOp(opId: string): void;
683
741
  /**
@@ -935,6 +993,15 @@ export interface SdkSecrecy {
935
993
  * sees a session id nor a key. Default life: two minutes.
936
994
  */
937
995
  ticket(payload: unknown, opts?: { ttlSeconds?: number }): Promise<string>;
996
+ /**
997
+ * The payload of a ticket THIS session minted (same caller, session,
998
+ * workspace and module), `null` for any other: expired, forged, or minted
999
+ * elsewhere. For a gesture that must end where it began: an OAuth popup
1000
+ * hands `code` and `state` back to the page that opened it, which sends
1001
+ * them through a command, so a consent link mailed to someone else never
1002
+ * lands anywhere.
1003
+ */
1004
+ redeem(ticket: string): Promise<{ payload: unknown } | null>;
938
1005
  }
939
1006
 
940
1007
  /**
@@ -952,8 +1019,9 @@ export interface SdkItems {
952
1019
  restrictions(): Promise<ReadonlyMap<string, ItemAccess>>;
953
1020
  /**
954
1021
  * Throws `forbidden` unless THIS item is open to the caller at `level`
955
- * (default `'read'`), role restriction included. Commands that target one
956
- * item call it first.
1022
+ * (default `'read'`), its override included. A command that names its
1023
+ * item in `access.item` is already checked; call it for an item reached
1024
+ * another way (the item a row belongs to).
957
1025
  */
958
1026
  assert(itemId: string, level?: FeatureAccess): Promise<void>;
959
1027
  /**
@@ -1040,6 +1108,8 @@ export interface SdkLive {
1040
1108
  publish(workspaceId: number, event: string, payload: unknown): void;
1041
1109
  /** {@link SdkContextLive.accountChanged}, from a service (a webhook, a ticker). */
1042
1110
  accountChanged(userId: number): void;
1111
+ /** {@link SdkContextLive.pendingChanged}, from a service or a public route (a report just filed). */
1112
+ pendingChanged(): void;
1043
1113
  }
1044
1114
 
1045
1115
  /**
@@ -1057,6 +1127,12 @@ export interface SdkContextLive {
1057
1127
  * (pauses and resumes). No payload, so no capability.
1058
1128
  */
1059
1129
  accountChanged(userId: number): void;
1130
+ /**
1131
+ * What `server.adminPending` counts may have moved (a report decided): the
1132
+ * host counts again and relights the badges of every moderator and
1133
+ * administrator connected. Coalesced by the host, cheap to call.
1134
+ */
1135
+ pendingChanged(): void;
1060
1136
  }
1061
1137
 
1062
1138
  /** The whole fleet, sessionless (capability `'devices.read'`), for services. */
@@ -1223,6 +1299,18 @@ export interface SdkFeatureContext<Repo = unknown> {
1223
1299
  origins: SdkOrigins;
1224
1300
  }
1225
1301
 
1302
+ /**
1303
+ * Finds the item a command reaches through another row; `undefined` or `null`
1304
+ * when that row does not exist. Method-shaped so a definition typed with your
1305
+ * repo stays assignable to the host's list of commands.
1306
+ */
1307
+ export type SdkItemFinder<Repo, I extends ZodType> = {
1308
+ find(
1309
+ ctx: SdkFeatureContext<Repo>,
1310
+ input: z.output<I>
1311
+ ): Promise<string | number | null | undefined>;
1312
+ }['find'];
1313
+
1226
1314
  /**
1227
1315
  * One command your module handles. The dispatcher validates `input` before the
1228
1316
  * handler and `output` after it, enforces `access` first, and broadcasts your
@@ -1242,16 +1330,28 @@ export interface SdkFeatureDefinition<
1242
1330
  * `level`: the caller's level on your feature (`read` by default).
1243
1331
  * `extras`: the extra permissions the caller must hold, ALL required.
1244
1332
  * `admin`: the caller must be a global administrator; the feature check
1245
- * still applies. Your feature id is implied: you cannot gate on another
1246
- * feature's rights.
1333
+ * still applies. `moderation`: a moderator or a global administrator, for
1334
+ * the commands of a `moderation` admin tab. Your feature id is implied:
1335
+ * you cannot gate on another feature's rights.
1247
1336
  * `scope: 'account'`: the command acts on the caller's ACCOUNT, not on a
1248
1337
  * workspace. The host runs it in the caller's personal workspace whatever
1249
1338
  * the client sent, so the role held in a shared workspace never decides.
1339
+ * `item`: the item the command targets, as the input field holding its
1340
+ * id, or as a function that finds it when the command reaches it through
1341
+ * another row (the site a form belongs to). The host checks `level` and
1342
+ * `extras` on THAT item, whose override replaces the role in both
1343
+ * directions, before your handler runs. The function runs first, with the
1344
+ * same context; it returns `undefined` when the row does not exist. Without
1345
+ * an item (or when the optional field is absent from a request), the role
1346
+ * on your feature decides alone: an override never opens a command that
1347
+ * does not name its item.
1250
1348
  */
1251
1349
  access?: {
1252
1350
  level?: FeatureAccess;
1253
1351
  extras?: readonly string[];
1352
+ item?: Extract<keyof z.input<I>, string> | SdkItemFinder<Repo, I>;
1254
1353
  admin?: boolean;
1354
+ moderation?: boolean;
1255
1355
  scope?: 'account';
1256
1356
  };
1257
1357
  /**
@@ -1302,6 +1402,8 @@ export interface SdkPublicRequest {
1302
1402
  */
1303
1403
  host?: string;
1304
1404
  ip: string;
1405
+ /** The HTTP method as received: a GET route also answers HEAD, which wants no page and counts no visit. */
1406
+ method?: string;
1305
1407
  }
1306
1408
 
1307
1409
  /** The reply of a public route, the minimal chainable surface the host maps onto its HTTP server. */
@@ -1311,6 +1413,16 @@ export interface SdkPublicReply {
1311
1413
  send(payload?: unknown): unknown;
1312
1414
  }
1313
1415
 
1416
+ /**
1417
+ * A request that no route matched, handed whole to `FeatureService.hostRequest`:
1418
+ * the host has no route to decode it, so the path comes as received.
1419
+ */
1420
+ export interface SdkHostRequest extends SdkPublicRequest {
1421
+ method: 'GET' | 'HEAD';
1422
+ /** As received, still percent-encoded, without the query string: `/` at the root, `/promo` below it. */
1423
+ path: string;
1424
+ }
1425
+
1314
1426
  export interface SdkPublicRouteOptions {
1315
1427
  /** A ceiling per client address, on top of the host's own: `{ max, timeWindow: '1 minute' }`. */
1316
1428
  rateLimit?: { max: number; timeWindow: string };
@@ -1380,7 +1492,8 @@ export type SdkPublicStreamHandler = (
1380
1492
  * Paths are absolute (`/t.js`, `/api/t/b`); a path the host already serves
1381
1493
  * is refused at boot. Every route is registered on every public listener.
1382
1494
  * `/` belongs to the host: a page served at the root of a customer domain goes
1383
- * through `FeatureService.domainRoot`.
1495
+ * through `FeatureService.domainRoot`, and every other path of a name you
1496
+ * serve whole through `FeatureService.hostRequest`.
1384
1497
  */
1385
1498
  export interface SdkPublicApp {
1386
1499
  get(path: string, opts: SdkPublicRouteOptions, handler: SdkPublicHandler): void;
@@ -1433,6 +1546,43 @@ export interface FeatureService {
1433
1546
  * `'routes.public'` and manifest `domains.web`.
1434
1547
  */
1435
1548
  domainRoot?(req: SdkPublicRequest, reply: SdkPublicReply, domain: SdkDomain): Promise<unknown>;
1549
+ /**
1550
+ * Names your feature serves WHOLE, outside any customer: a short domain of
1551
+ * the instance, read from your env (`go.example.com`). Each must match
1552
+ * `DOMAIN_HOST_PATTERN`, differ from the app's and the public surface's
1553
+ * hosts, and be claimed by one feature only: the boot refuses otherwise.
1554
+ * Reserved like the instance's own hosts: no workspace can declare them as
1555
+ * a domain, and the domain proxy never routes them (route them yourself to
1556
+ * the public listener). Requires `hostRequest`.
1557
+ */
1558
+ ownHosts?: readonly string[];
1559
+ /**
1560
+ * A listener of your own, on this port, beside the app's and the public
1561
+ * surface's: the host serves there your public routes and your
1562
+ * `hostRequest`, for your `ownHosts` and your verified web domains, and
1563
+ * nothing of anyone else. None of your routes is mounted on the other
1564
+ * listeners, and the domain proxy sends your domains here: what you serve
1565
+ * shares no port with the instance's own names. Read the port from your
1566
+ * env; leave it out to stay on the public surface. Requires `ownHosts` and
1567
+ * `hostRequest`; a port another listener holds is refused at boot.
1568
+ */
1569
+ ownListener?: { port: number };
1570
+ /**
1571
+ * Every GET or HEAD that no route matched, root included, on one of your
1572
+ * `ownHosts` (`domain` is `null`) or on one of YOUR verified web domains
1573
+ * (`domain` is that domain): for names whose paths are yours to define
1574
+ * (`go.example.com/promo`). Behind the maintenance gate, rate-limited by
1575
+ * the host. Your routes from `publicRoutes` still win where they match.
1576
+ * When several features verified the same name, the first installed that
1577
+ * answers the path takes it (`domainRoot` for `/`, `hostRequest` for any).
1578
+ * Exclusive with `domainRoot`. Requires capability `'routes.public'` and,
1579
+ * when your manifest declares `domains`, `domains.web`.
1580
+ */
1581
+ hostRequest?(
1582
+ req: SdkHostRequest,
1583
+ reply: SdkPublicReply,
1584
+ domain: SdkDomain | null
1585
+ ): Promise<unknown>;
1436
1586
  /**
1437
1587
  * Your `stock` items that a plan just paused or resumed, once written: for
1438
1588
  * what you hold OPEN (a connection, a session, a timer). What you run on
@@ -1510,6 +1660,8 @@ export interface FeatureServiceDeps<Repo = unknown> {
1510
1660
  pauses: SdkPlanPauses;
1511
1661
  /** The devices' telemetry, sessionless (capability `'telemetry.read'`). */
1512
1662
  telemetry: SdkTelemetry;
1663
+ /** Where a client address comes from (capability `'geoip'`). */
1664
+ geo: SdkGeo;
1513
1665
  /** Live invalidation of your feature's resources, from a service. */
1514
1666
  live: SdkLive;
1515
1667
  /**
@@ -1636,8 +1788,31 @@ export interface FeatureServer<Repo = unknown> {
1636
1788
  mailSamples?: readonly SdkMailSample[];
1637
1789
  /** Your end-to-end scenarios, run by an administrator against this very server. */
1638
1790
  e2e?: FeatureE2eEntry<Repo>;
1791
+ /**
1792
+ * What awaits a human decision, by id of `manifest.adminTabs` (open
1793
+ * reports, a queue running late): the badges of the account menu and of
1794
+ * the administration popup. A tab absent or at 0 lights nothing. Cheap
1795
+ * counts only: the host asks again on every `live.pendingChanged()`.
1796
+ */
1797
+ adminPending?(ctx: SdkAdminContext<Repo>): Promise<Readonly<Record<string, number>>>;
1798
+ /**
1799
+ * Your own figures for the overview of the administration popup, across
1800
+ * every account (links created, files stored): what the host cannot count
1801
+ * from your tables and quotas alone.
1802
+ */
1803
+ adminFacts?(ctx: SdkAdminContext<Repo>): Promise<readonly SdkAdminFact[]>;
1804
+ }
1805
+
1806
+ /** What `FeatureServer.adminPending` and `adminFacts` are called with: no session, every account at once. */
1807
+ export interface SdkAdminContext<Repo = unknown> {
1808
+ repo: Repo;
1809
+ /** Your paused `stock` items, whatever the workspace. */
1810
+ pauses: SdkPlanPauses;
1639
1811
  }
1640
1812
 
1813
+ /** One figure of `FeatureServer.adminFacts`. */
1814
+ export type SdkAdminFact = AdminFeatureFact;
1815
+
1641
1816
  /** What `FeatureServer.externalServices` is called with. */
1642
1817
  export interface SdkExternalServicesContext<Repo = unknown> {
1643
1818
  repo: Repo;
@@ -1693,11 +1868,16 @@ export interface SdkE2eContext<Repo = unknown> {
1693
1868
  * dispatcher. Rejects with a `FeatureError` carrying the server's code.
1694
1869
  */
1695
1870
  send<T = unknown>(command: string, input: unknown, opts?: { workspaceId?: number }): Promise<T>;
1696
- /** A sessionless request to this server's own listener: what a visitor's browser sends to a public route. */
1871
+ /**
1872
+ * A sessionless request to this server's own listener: what a visitor's
1873
+ * browser sends to a public route. Redirects are not followed: a 302 comes
1874
+ * back as is, its target in `headers.location`. Header names are lowercase,
1875
+ * repeated ones joined by `, `.
1876
+ */
1697
1877
  fetch(
1698
1878
  path: string,
1699
1879
  init?: { method?: 'GET' | 'POST'; headers?: Record<string, string>; body?: string }
1700
- ): Promise<{ status: number; body: string }>;
1880
+ ): Promise<{ status: number; body: string; headers: Readonly<Record<string, string>> }>;
1701
1881
  /**
1702
1882
  * Polls until `probe` answers something other than `null`, `undefined` or
1703
1883
  * `false`, then resolves with it. Rejects after `timeoutMs` (default 10 s),
@@ -80,6 +80,7 @@ test('the harness searches accounts like the app: substring, exact id first, cap
80
80
  username,
81
81
  email: `${username}@example.com`,
82
82
  isAdmin: false,
83
+ canModerate: false,
83
84
  e2e: false,
84
85
  suspended: false,
85
86
  created: 0