@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.
- package/package.json +1 -1
- package/src/domain/featureRegistry.ts +14 -0
- package/src/domain/feedback.ts +4 -3
- package/src/domain/home.ts +15 -1
- package/src/domain/live.ts +9 -0
- package/src/domain/loginChecks.ts +38 -0
- package/src/domain/notifications.ts +2 -1
- package/src/domain/role.ts +9 -3
- package/src/domain/stepUp.ts +27 -0
- package/src/domain/user.ts +17 -4
- package/src/domain/workspace.ts +21 -0
- package/src/domain/workspaceRole.ts +7 -2
- package/src/features/admin.ts +60 -3
- package/src/features/feedback.ts +8 -7
- package/src/features/loginChecks.ts +80 -0
- package/src/features/registry.ts +4 -0
- package/src/features/stepUp.ts +26 -0
- package/src/features/twoFactor.ts +13 -6
- package/src/features/user.ts +23 -0
- package/src/features/workspace.ts +63 -7
- package/src/http/auth.ts +44 -12
- package/src/index.ts +62 -6
- package/src/protocol/agent.ts +25 -8
- package/src/protocol/error.ts +5 -1
- package/src/sdk/client.ts +7 -7
- package/src/sdk/copy.test.ts +23 -0
- package/src/sdk/copy.ts +24 -2
- package/src/sdk/csv.test.ts +28 -0
- package/src/sdk/csv.ts +24 -0
- package/src/sdk/deviceRelay.ts +8 -2
- package/src/sdk/index.ts +1 -0
- package/src/sdk/manifest.ts +31 -8
- package/src/sdk/net.test.ts +10 -2
- package/src/sdk/net.ts +35 -30
- package/src/sdk/providers.ts +7 -0
- package/src/sdk/server.ts +199 -19
- package/src/sdk/testing.test.ts +1 -0
- package/src/sdk/testing.ts +46 -12
- package/src/sdk/visitors.test.ts +74 -0
- package/src/sdk/visitors.ts +146 -0
package/src/sdk/manifest.ts
CHANGED
|
@@ -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
|
-
*
|
|
363
|
-
*
|
|
364
|
-
*
|
|
365
|
-
*
|
|
366
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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');
|
package/src/sdk/net.test.ts
CHANGED
|
@@ -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
|
|
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
|
-
*
|
|
20
|
-
* CGNAT
|
|
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
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
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
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
return
|
|
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
|
/**
|
package/src/sdk/providers.ts
CHANGED
|
@@ -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.
|
|
352
|
-
*
|
|
353
|
-
*
|
|
354
|
-
*
|
|
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
|
|
486
|
-
*
|
|
487
|
-
*
|
|
488
|
-
*
|
|
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
|
-
|
|
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(
|
|
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'`),
|
|
956
|
-
* item call it
|
|
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.
|
|
1246
|
-
* feature
|
|
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
|
-
/**
|
|
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),
|
package/src/sdk/testing.test.ts
CHANGED