@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
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
import type { SdkCipher, SdkLogger, SdkQueryable, SdkServerKeys } from './server';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The holder's data export (GDPR portability): a zip streamed to their browser,
|
|
5
|
+
* never stored. Everything in it is PLAINTEXT, private tier included: the holder
|
|
6
|
+
* typed their password for it. What never goes in: what opens a service or
|
|
7
|
+
* protects the account (tokens, API keys, integration passwords, secret URLs,
|
|
8
|
+
* hashes, key material).
|
|
9
|
+
*
|
|
10
|
+
* The host exports your `FeatureStore` itself, minus `store.omit`, and every
|
|
11
|
+
* table you declare as an {@link SdkExportTable}. Your hooks write the rest:
|
|
12
|
+
* files, or a table whose rows need shaping.
|
|
13
|
+
*/
|
|
14
|
+
export interface FeatureAccountExport<Repo = unknown> {
|
|
15
|
+
/**
|
|
16
|
+
* Every table your feature owns, and its fate: exported by the host, by
|
|
17
|
+
* your hooks (`'custom'`), or left out with the sentence the holder reads
|
|
18
|
+
* in the archive. Checked at boot against the tables that exist, and
|
|
19
|
+
* against their columns (see {@link SdkExportTable.omit}).
|
|
20
|
+
*/
|
|
21
|
+
tables: Readonly<Record<string, SdkExportTable | 'custom' | SdkExportSkip>>;
|
|
22
|
+
/** Keys of your `FeatureStore` never exported (a token, an API key). The host exports the rest. */
|
|
23
|
+
store?: { omit: readonly string[] };
|
|
24
|
+
/** The large files you carry, measured for the dialog; `optional` ones the holder may leave out. */
|
|
25
|
+
files?: Readonly<Record<string, SdkExportFiles<Repo>>>;
|
|
26
|
+
/** Once per export: what you keep by account rather than by workspace. */
|
|
27
|
+
account?(ctx: SdkAccountExportContext<Repo>): Promise<void>;
|
|
28
|
+
/** Once per workspace the export covers: the personal one and the shared ones the holder owns. */
|
|
29
|
+
workspace?(ctx: SdkWorkspaceExportContext<Repo>): Promise<void>;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Left out on purpose; `skip` is the sentence the holder reads in the archive, in French. */
|
|
33
|
+
export interface SdkExportSkip {
|
|
34
|
+
skip: string;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** A table the host writes for you, paged, sealed cells opened. */
|
|
38
|
+
export interface SdkExportTable {
|
|
39
|
+
/** File within your folder, ending in `.json`. */
|
|
40
|
+
file: string;
|
|
41
|
+
/** `'workspace'` (default): the `?` of `where` is the workspace id. `'account'`: the holder's user id. */
|
|
42
|
+
scope?: 'workspace' | 'account';
|
|
43
|
+
/** Selects the rows, with exactly one `?`. A literal of your module, never built from input. */
|
|
44
|
+
where: string;
|
|
45
|
+
/** A unique ordering key, for keyset paging. */
|
|
46
|
+
key: readonly [string, ...string[]];
|
|
47
|
+
/**
|
|
48
|
+
* Encrypted columns, opened whatever their tier. One ending in `_enc` is
|
|
49
|
+
* written without the suffix (`query_enc` as `query`), unless the row
|
|
50
|
+
* already has a column of that name.
|
|
51
|
+
*/
|
|
52
|
+
sealed?: readonly string[];
|
|
53
|
+
/** Columns (sealed or not) holding JSON: written as values, not strings. */
|
|
54
|
+
json?: readonly string[];
|
|
55
|
+
/** Epoch columns, written as ISO 8601. */
|
|
56
|
+
dates?: Readonly<Record<string, 's' | 'ms'>>;
|
|
57
|
+
/** Never written. A column named like a secret MUST be here unless listed in `keep`. */
|
|
58
|
+
omit?: readonly string[];
|
|
59
|
+
/** Columns the secret-name rule would drop that are not secrets (`dedup_hash`). */
|
|
60
|
+
keep?: readonly string[];
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** Large files your hooks write, measured before the export so the holder knows what to expect. */
|
|
64
|
+
export interface SdkExportFiles<Repo = unknown> {
|
|
65
|
+
/** As the dialog names them, in French: `'les fichiers CloudSync'`. */
|
|
66
|
+
label: string;
|
|
67
|
+
/** The holder may leave them out of the archive. */
|
|
68
|
+
optional?: boolean;
|
|
69
|
+
/** Bytes over the holder's owned workspaces; 0 hides them from the dialog. */
|
|
70
|
+
bytes(ctx: {
|
|
71
|
+
repo: Repo;
|
|
72
|
+
q: SdkQueryable;
|
|
73
|
+
userId: number;
|
|
74
|
+
workspaceIds: readonly number[];
|
|
75
|
+
}): Promise<number>;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** Where your hooks write, rooted at your folder in the archive. Paths are made safe by the host. */
|
|
79
|
+
export interface SdkExportWriter {
|
|
80
|
+
/** A small JSON document. */
|
|
81
|
+
json(path: string, value: unknown): Promise<void>;
|
|
82
|
+
/** Rows as a JSON array, written as they come. Writes nothing when there is none. */
|
|
83
|
+
rows(path: string, rows: AsyncIterable<unknown>): Promise<void>;
|
|
84
|
+
/** One of your tables, as a declared {@link SdkExportTable} would be written. */
|
|
85
|
+
table(table: string, spec: SdkExportTable): Promise<void>;
|
|
86
|
+
/**
|
|
87
|
+
* A file, streamed. `compress: false` for bytes already compressed (an
|
|
88
|
+
* archive, an image). `mtime` in epoch seconds.
|
|
89
|
+
*/
|
|
90
|
+
file(
|
|
91
|
+
path: string,
|
|
92
|
+
bytes: Uint8Array | AsyncIterable<Uint8Array>,
|
|
93
|
+
opts?: { mtime?: number; compress?: boolean }
|
|
94
|
+
): Promise<void>;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
interface SdkExportContextBase<Repo> {
|
|
98
|
+
repo: Repo;
|
|
99
|
+
/** Reads only. */
|
|
100
|
+
q: SdkQueryable;
|
|
101
|
+
/** The holder. */
|
|
102
|
+
userId: number;
|
|
103
|
+
out: SdkExportWriter;
|
|
104
|
+
/** Whether the holder kept `files[key]` in the archive. */
|
|
105
|
+
includes(filesKey: string): boolean;
|
|
106
|
+
keys: SdkServerKeys;
|
|
107
|
+
/** Aborted when the download stops: check it in long loops. */
|
|
108
|
+
signal: AbortSignal;
|
|
109
|
+
logger: SdkLogger;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
export interface SdkAccountExportContext<Repo = unknown> extends SdkExportContextBase<Repo> {
|
|
113
|
+
/** Every workspace the export covers. */
|
|
114
|
+
workspaceIds: readonly number[];
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
export interface SdkWorkspaceExportContext<Repo = unknown> extends SdkExportContextBase<Repo> {
|
|
118
|
+
workspace: { id: number; kind: 'personal' | 'shared'; name: string };
|
|
119
|
+
/** Both tiers are readable for the length of this export. */
|
|
120
|
+
cipher(mode?: 'server' | 'private'): SdkCipher;
|
|
121
|
+
/** A sealed cell opened whatever its tier; `null` (and counted in the report) when no key opens it. */
|
|
122
|
+
open(blob: string): Promise<string | null>;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** A column name that looks like a secret: {@link SdkExportTable.omit} it, or `keep` it knowingly. */
|
|
126
|
+
export const EXPORT_SECRET_COLUMN = /(secret|token|passw|_hash$|private_key|credential|wrapped)/i;
|
|
127
|
+
|
|
128
|
+
const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
129
|
+
|
|
130
|
+
/** What is wrong with a declaration, or `null`. Checked at boot, before any table is read. */
|
|
131
|
+
export function accountExportProblem(entry: FeatureAccountExport<unknown>): string | null {
|
|
132
|
+
const files = new Map<string, string>();
|
|
133
|
+
for (const [table, fate] of Object.entries(entry.tables)) {
|
|
134
|
+
if (!IDENTIFIER.test(table)) return `table « ${table} »: not an identifier`;
|
|
135
|
+
if (fate === 'custom') continue;
|
|
136
|
+
if ('skip' in fate) {
|
|
137
|
+
if (!fate.skip.trim()) return `table « ${table} »: a skip says why`;
|
|
138
|
+
continue;
|
|
139
|
+
}
|
|
140
|
+
if (!/^[a-z0-9][a-z0-9-]*\.json$/.test(fate.file)) {
|
|
141
|
+
return `table « ${table} »: file « ${fate.file} »`;
|
|
142
|
+
}
|
|
143
|
+
const scoped = `${fate.scope ?? 'workspace'}:${fate.file}`;
|
|
144
|
+
const other = files.get(scoped);
|
|
145
|
+
if (other) return `tables « ${other} » and « ${table} » write the same file`;
|
|
146
|
+
files.set(scoped, table);
|
|
147
|
+
if ((fate.where.match(/\?/g) ?? []).length !== 1) {
|
|
148
|
+
return `table « ${table} »: where takes exactly one ?`;
|
|
149
|
+
}
|
|
150
|
+
if (fate.where.includes(';')) return `table « ${table} »: where holds a ;`;
|
|
151
|
+
const columns = [
|
|
152
|
+
...fate.key,
|
|
153
|
+
...(fate.sealed ?? []),
|
|
154
|
+
...(fate.json ?? []),
|
|
155
|
+
...Object.keys(fate.dates ?? {}),
|
|
156
|
+
...(fate.omit ?? []),
|
|
157
|
+
...(fate.keep ?? [])
|
|
158
|
+
];
|
|
159
|
+
const bad = columns.find((column) => !IDENTIFIER.test(column));
|
|
160
|
+
if (bad) return `table « ${table} »: column « ${bad} »`;
|
|
161
|
+
const omitted = new Set(fate.omit ?? []);
|
|
162
|
+
const clash = (fate.sealed ?? []).find((column) => omitted.has(column));
|
|
163
|
+
if (clash) return `table « ${table} »: « ${clash} » is both sealed and omitted`;
|
|
164
|
+
}
|
|
165
|
+
if (entry.store && entry.store.omit.some((key) => !key.trim())) {
|
|
166
|
+
return 'store.omit holds an empty key';
|
|
167
|
+
}
|
|
168
|
+
return null;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
const MIN_PAGE = 10;
|
|
172
|
+
const MAX_PAGE = 1000;
|
|
173
|
+
/** A page aims at this many bytes: a table of data-URL images must not load a thousand of them at once. */
|
|
174
|
+
const PAGE_BYTES = 4 * 1024 * 1024;
|
|
175
|
+
|
|
176
|
+
/** A cell as JSON can carry it: dates to ISO 8601, large integers to strings, bytes to base64. */
|
|
177
|
+
function plainCell(value: unknown): unknown {
|
|
178
|
+
if (typeof value === 'bigint') {
|
|
179
|
+
return Number.isSafeInteger(Number(value)) ? Number(value) : value.toString();
|
|
180
|
+
}
|
|
181
|
+
if (value instanceof Date) return value.toISOString();
|
|
182
|
+
if (value instanceof Uint8Array) return { base64: Buffer.from(value).toString('base64') };
|
|
183
|
+
return value;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
function isoOf(value: unknown, unit: 's' | 'ms'): unknown {
|
|
187
|
+
if (value === null || value === undefined || value === '') return null;
|
|
188
|
+
const n = Number(value);
|
|
189
|
+
if (!Number.isFinite(n) || n === 0) return value;
|
|
190
|
+
return new Date(unit === 's' ? n * 1000 : n).toISOString();
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* The rows of one declared table, oldest key first, one page at a time: the
|
|
195
|
+
* page size follows the bytes read, so a table of large cells never loads
|
|
196
|
+
* whole. Omitted columns never leave this function; sealed ones are opened by
|
|
197
|
+
* `open`, a `null` there meaning no key opens the cell (`onUnreadable` counts
|
|
198
|
+
* it).
|
|
199
|
+
*/
|
|
200
|
+
export async function* exportTableRows(
|
|
201
|
+
q: SdkQueryable,
|
|
202
|
+
table: string,
|
|
203
|
+
spec: SdkExportTable,
|
|
204
|
+
scopeId: number,
|
|
205
|
+
open: (blob: string) => Promise<string | null>,
|
|
206
|
+
onUnreadable: () => void = () => undefined
|
|
207
|
+
): AsyncGenerator<Record<string, unknown>> {
|
|
208
|
+
const omitted = new Set(spec.omit ?? []);
|
|
209
|
+
const sealed = new Set(spec.sealed ?? []);
|
|
210
|
+
const json = new Set(spec.json ?? []);
|
|
211
|
+
const dates = spec.dates ?? {};
|
|
212
|
+
const order = spec.key.map((column) => `\`${column}\``).join(', ');
|
|
213
|
+
let size = 200;
|
|
214
|
+
let last: unknown[] | null = null;
|
|
215
|
+
for (;;) {
|
|
216
|
+
const after: string =
|
|
217
|
+
last === null ? '' : ` AND (${order}) > (${spec.key.map(() => '?').join(', ')})`;
|
|
218
|
+
const rows: Record<string, unknown>[] = await q.query<Record<string, unknown>>(
|
|
219
|
+
`SELECT * FROM \`${table}\` WHERE (${spec.where})${after} ORDER BY ${order} LIMIT ${size}`,
|
|
220
|
+
[scopeId, ...(last ?? [])]
|
|
221
|
+
);
|
|
222
|
+
let bytes = 0;
|
|
223
|
+
for (const row of rows) {
|
|
224
|
+
const out: Record<string, unknown> = {};
|
|
225
|
+
for (const [column, raw] of Object.entries(row)) {
|
|
226
|
+
if (omitted.has(column)) continue;
|
|
227
|
+
let value: unknown = raw;
|
|
228
|
+
if (sealed.has(column) && typeof raw === 'string' && raw !== '') {
|
|
229
|
+
value = await open(raw);
|
|
230
|
+
if (value === null) onUnreadable();
|
|
231
|
+
}
|
|
232
|
+
if (json.has(column) && typeof value === 'string') {
|
|
233
|
+
try {
|
|
234
|
+
value = JSON.parse(value);
|
|
235
|
+
} catch {
|
|
236
|
+
// Un JSON qui ne se relit pas reste tel quel : la donnée prime sur sa forme.
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
if (column in dates) value = isoOf(value, dates[column]);
|
|
240
|
+
const plain =
|
|
241
|
+
sealed.has(column) && column.endsWith('_enc') ? column.slice(0, -4) : column;
|
|
242
|
+
out[plain !== column && !(plain in row) ? plain : column] = plainCell(value);
|
|
243
|
+
}
|
|
244
|
+
bytes += JSON.stringify(out).length;
|
|
245
|
+
yield out;
|
|
246
|
+
}
|
|
247
|
+
if (rows.length < size) return;
|
|
248
|
+
last = spec.key.map((column) => rows[rows.length - 1][column]);
|
|
249
|
+
size = Math.min(
|
|
250
|
+
MAX_PAGE,
|
|
251
|
+
Math.max(MIN_PAGE, Math.round((size * PAGE_BYTES) / Math.max(1, bytes)))
|
|
252
|
+
);
|
|
253
|
+
}
|
|
254
|
+
}
|
|
@@ -13,6 +13,7 @@ declare module 'deveye-sdk-client' {
|
|
|
13
13
|
CSSProperties,
|
|
14
14
|
ChangeEvent,
|
|
15
15
|
ComponentType,
|
|
16
|
+
DragEvent,
|
|
16
17
|
InputHTMLAttributes,
|
|
17
18
|
ReactNode,
|
|
18
19
|
RefObject,
|
|
@@ -463,6 +464,81 @@ declare module 'deveye-sdk-client' {
|
|
|
463
464
|
draggingId: string | number | null;
|
|
464
465
|
};
|
|
465
466
|
|
|
467
|
+
// ── Files ──────────────────────────────────────────────────────────────
|
|
468
|
+
/** A file picked or dropped, with its relative path, name included (`photos/a.jpg`; `a.jpg` outside a folder). */
|
|
469
|
+
export interface PickedFile {
|
|
470
|
+
file: File;
|
|
471
|
+
path: string;
|
|
472
|
+
}
|
|
473
|
+
export interface UploadHandle {
|
|
474
|
+
done: Promise<void>;
|
|
475
|
+
abort(): void;
|
|
476
|
+
}
|
|
477
|
+
/** What `UploadHandle.done` rejects with: the server's message, or why the connection ended. */
|
|
478
|
+
export class UploadError extends Error {
|
|
479
|
+
readonly aborted: boolean;
|
|
480
|
+
constructor(message: string, aborted?: boolean);
|
|
481
|
+
}
|
|
482
|
+
/**
|
|
483
|
+
* POSTs the file as is (`application/octet-stream`) to a route of yours,
|
|
484
|
+
* typically a `postStream` URL carrying a ticket. `onProgress` gets 0 to 1;
|
|
485
|
+
* at 1 the server is still writing.
|
|
486
|
+
*/
|
|
487
|
+
export function uploadFile(
|
|
488
|
+
url: string,
|
|
489
|
+
file: File,
|
|
490
|
+
onProgress: (ratio: number) => void
|
|
491
|
+
): UploadHandle;
|
|
492
|
+
/** Downloads a URL served as an attachment, without leaving the page. */
|
|
493
|
+
export function saveFrom(url: string): void;
|
|
494
|
+
/** Opens the system picker; `folder` takes a whole folder, relative paths included. Cancelled: empty. */
|
|
495
|
+
export function pickFiles(opts?: {
|
|
496
|
+
multiple?: boolean;
|
|
497
|
+
folder?: boolean;
|
|
498
|
+
accept?: string;
|
|
499
|
+
}): Promise<PickedFile[]>;
|
|
500
|
+
/** Reads a drop: its files and, recursively, the content of the folders dropped. */
|
|
501
|
+
export function filesOfDrop(data: DataTransfer): Promise<PickedFile[]>;
|
|
502
|
+
/** Makes any element a drop target: spread `props` on it, `over` while files hover. */
|
|
503
|
+
export function useFileDrop(
|
|
504
|
+
onFiles: (files: PickedFile[]) => void,
|
|
505
|
+
disabled?: boolean
|
|
506
|
+
): {
|
|
507
|
+
over: boolean;
|
|
508
|
+
props: {
|
|
509
|
+
onDragOver: (event: DragEvent) => void;
|
|
510
|
+
onDragLeave: (event: DragEvent) => void;
|
|
511
|
+
onDrop: (event: DragEvent) => void;
|
|
512
|
+
};
|
|
513
|
+
};
|
|
514
|
+
/**
|
|
515
|
+
* The drop area: a real button that opens the picker, dropping is a
|
|
516
|
+
* shortcut. `multiple` takes several files and whole folders; otherwise
|
|
517
|
+
* only the first file.
|
|
518
|
+
*/
|
|
519
|
+
export const Dropzone: ComponentType<{
|
|
520
|
+
onFiles: (files: PickedFile[]) => void;
|
|
521
|
+
title: string;
|
|
522
|
+
hint?: string;
|
|
523
|
+
accept?: string;
|
|
524
|
+
multiple?: boolean;
|
|
525
|
+
disabled?: boolean;
|
|
526
|
+
className?: string;
|
|
527
|
+
}>;
|
|
528
|
+
/**
|
|
529
|
+
* The quiet gauge of a quota in a feature's header: the same count as the
|
|
530
|
+
* refusal. It warns at 80 %, alarms at 95 %, and leads the workspace owner
|
|
531
|
+
* to the plans. `limit: null` shows the usage alone. Bytes by default.
|
|
532
|
+
*/
|
|
533
|
+
export const UsageMeter: ComponentType<{
|
|
534
|
+
used: number;
|
|
535
|
+
limit: number | null;
|
|
536
|
+
label: string;
|
|
537
|
+
explain?: string;
|
|
538
|
+
format?: (value: number) => string;
|
|
539
|
+
usedWord?: string;
|
|
540
|
+
}>;
|
|
541
|
+
|
|
466
542
|
// ── Server push events ─────────────────────────────────────────────────
|
|
467
543
|
/** Typed push subscription: filters `event`, safeParses, drops mismatches. */
|
|
468
544
|
export function onServerEvent<T>(
|
|
@@ -475,6 +551,16 @@ declare module 'deveye-sdk-client' {
|
|
|
475
551
|
/** Whether the socket is open right now (to tell a real error from an outage). */
|
|
476
552
|
export function isSocketOpen(): boolean;
|
|
477
553
|
|
|
554
|
+
// ── Usage ──────────────────────────────────────────────────────────────
|
|
555
|
+
/**
|
|
556
|
+
* Names the screen shown inside your feature's view (`'history'`,
|
|
557
|
+
* `'site/traffic'`), for the instance's usage figures and bug reports.
|
|
558
|
+
* Static segments only (lowercase letters, digits, dashes, slashes): never
|
|
559
|
+
* an id, a name or anything typed. Counted only while your view is the one
|
|
560
|
+
* open; the deepest screen mounted wins. `null` withdraws it.
|
|
561
|
+
*/
|
|
562
|
+
export function useSubView(segment: string | null): void;
|
|
563
|
+
|
|
478
564
|
// ── Data ───────────────────────────────────────────────────────────────
|
|
479
565
|
/**
|
|
480
566
|
* A resource key an EXTERNAL module may own: `x-<slug>.<name>`, as listed
|
package/src/sdk/client.ts
CHANGED
|
@@ -51,6 +51,11 @@ export interface AccountViewProps {
|
|
|
51
51
|
hint?: string;
|
|
52
52
|
}
|
|
53
53
|
|
|
54
|
+
/** Props of {@link FeatureClient.AdminView}. */
|
|
55
|
+
export interface AdminViewProps {
|
|
56
|
+
close(): void;
|
|
57
|
+
}
|
|
58
|
+
|
|
54
59
|
/**
|
|
55
60
|
* Your package's `./client` export.
|
|
56
61
|
*/
|
|
@@ -65,6 +70,8 @@ export interface FeatureClient {
|
|
|
65
70
|
Full?: ComponentType<FeatureViewProps>;
|
|
66
71
|
/** The view `manifest.accountEntry` opens from the user menu. */
|
|
67
72
|
AccountView?: ComponentType<AccountViewProps>;
|
|
73
|
+
/** The system page `manifest.adminEntry` opens, for a global administrator only. */
|
|
74
|
+
AdminView?: ComponentType<AdminViewProps>;
|
|
68
75
|
/**
|
|
69
76
|
* The vignette shown on your card in the home grid's add market and on
|
|
70
77
|
* your "About" sheet. Without one, the host draws a neutral module mark:
|
|
@@ -418,6 +425,43 @@ export interface AudienceClientProvider {
|
|
|
418
425
|
}>;
|
|
419
426
|
}
|
|
420
427
|
|
|
428
|
+
/** A folder of the workspace, as the Hosting client provider lists it for a project's picker. */
|
|
429
|
+
export interface HostingLinkedCandidate {
|
|
430
|
+
id: number;
|
|
431
|
+
name: string;
|
|
432
|
+
/** Projected here from another workspace. */
|
|
433
|
+
foreign?: boolean;
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
/**
|
|
437
|
+
* What the Hosting module offers the host's screens under
|
|
438
|
+
* `HOSTING_CLIENT_PROVIDER`: the workspace's folders, a linked folder shown
|
|
439
|
+
* inside a project's tab, and the feature's own folder dialog.
|
|
440
|
+
*/
|
|
441
|
+
export interface HostingClientProvider {
|
|
442
|
+
/** The workspace's folders, in the module's own order. */
|
|
443
|
+
listPacks(): Promise<readonly HostingLinkedCandidate[]>;
|
|
444
|
+
/**
|
|
445
|
+
* The given folders, summarised for a project's dashboard tile, in ONE
|
|
446
|
+
* round trip. An id the caller cannot read, or that is gone, comes back
|
|
447
|
+
* `unavailable`, never as a throw.
|
|
448
|
+
*/
|
|
449
|
+
summarize(packIds: readonly number[]): Promise<readonly SdkTileSummary[]>;
|
|
450
|
+
/**
|
|
451
|
+
* A folder linked to a project: its heading and status, its addresses,
|
|
452
|
+
* its latest files with their preview. Loads itself, follows the
|
|
453
|
+
* feature's invalidations, and renders the host's "unlink" as its
|
|
454
|
+
* trailing action.
|
|
455
|
+
*/
|
|
456
|
+
LinkedPack: ComponentType<{ packId: number; canWrite: boolean; onUnlink: () => void }>;
|
|
457
|
+
/** The feature's folder form, to create a folder from a project. */
|
|
458
|
+
PackDialog: ComponentType<{
|
|
459
|
+
open: boolean;
|
|
460
|
+
onClose: () => void;
|
|
461
|
+
onSaved: (packId: number) => void;
|
|
462
|
+
}>;
|
|
463
|
+
}
|
|
464
|
+
|
|
421
465
|
/**
|
|
422
466
|
* What the Invoicing module offers other screens under
|
|
423
467
|
* `INVOICING_CLIENT_PROVIDER`. It sends Invoicing's own command under the
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
import assert from 'node:assert/strict';
|
|
2
|
+
import crypto from 'node:crypto';
|
|
3
|
+
import { describe, it } from 'node:test';
|
|
4
|
+
|
|
5
|
+
import {
|
|
6
|
+
BLOB_CHUNK_BYTES,
|
|
7
|
+
openSealedRange,
|
|
8
|
+
openSealedStream,
|
|
9
|
+
sealedSize,
|
|
10
|
+
sealStream
|
|
11
|
+
} from './devb';
|
|
12
|
+
|
|
13
|
+
const KEY = crypto.createHash('sha256').update('test key').digest();
|
|
14
|
+
|
|
15
|
+
async function* once(data: Buffer): AsyncGenerator<Buffer> {
|
|
16
|
+
yield data;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** Hands a slice back in small pieces, as a network read would. */
|
|
20
|
+
async function* sliced(data: Buffer, start: number, end: number): AsyncGenerator<Buffer> {
|
|
21
|
+
for (let at = start; at <= end; at += 70_001) {
|
|
22
|
+
yield data.subarray(at, Math.min(at + 70_001, end + 1));
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
async function collect(source: AsyncIterable<Buffer>): Promise<Buffer> {
|
|
27
|
+
const parts: Buffer[] = [];
|
|
28
|
+
for await (const chunk of source) parts.push(chunk);
|
|
29
|
+
return Buffer.concat(parts);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
const seal = (data: Buffer, source?: AsyncIterable<Buffer>) =>
|
|
33
|
+
collect(sealStream(KEY, source ?? once(data)));
|
|
34
|
+
|
|
35
|
+
describe('sealStream / openSealedStream', () => {
|
|
36
|
+
it('gives back exactly what it was given, empty included, at every chunk boundary', async () => {
|
|
37
|
+
for (const size of [
|
|
38
|
+
0,
|
|
39
|
+
1,
|
|
40
|
+
1024,
|
|
41
|
+
BLOB_CHUNK_BYTES - 1,
|
|
42
|
+
BLOB_CHUNK_BYTES,
|
|
43
|
+
BLOB_CHUNK_BYTES + 1
|
|
44
|
+
]) {
|
|
45
|
+
const data = crypto.randomBytes(size);
|
|
46
|
+
const sealed = await seal(data);
|
|
47
|
+
assert.equal(sealed.length, sealedSize(size), `sealed size of ${size}`);
|
|
48
|
+
assert.deepEqual(
|
|
49
|
+
await collect(openSealedStream(KEY, once(sealed))),
|
|
50
|
+
data,
|
|
51
|
+
`size ${size}`
|
|
52
|
+
);
|
|
53
|
+
}
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
it('ignores how the source is cut', async () => {
|
|
57
|
+
const data = crypto.randomBytes(BLOB_CHUNK_BYTES + 9999);
|
|
58
|
+
async function* ragged(): AsyncGenerator<Buffer> {
|
|
59
|
+
let offset = 0;
|
|
60
|
+
for (const size of [1, 7, 100_000, 3, BLOB_CHUNK_BYTES, 512]) {
|
|
61
|
+
if (offset >= data.length) break;
|
|
62
|
+
yield data.subarray(offset, Math.min(offset + size, data.length));
|
|
63
|
+
offset += size;
|
|
64
|
+
}
|
|
65
|
+
if (offset < data.length) yield data.subarray(offset);
|
|
66
|
+
}
|
|
67
|
+
assert.deepEqual(
|
|
68
|
+
await collect(openSealedStream(KEY, once(await seal(data, ragged())))),
|
|
69
|
+
data
|
|
70
|
+
);
|
|
71
|
+
});
|
|
72
|
+
|
|
73
|
+
it('refuses a truncated blob, a tampered one, and another key', async () => {
|
|
74
|
+
const sealed = await seal(crypto.randomBytes(BLOB_CHUNK_BYTES * 2));
|
|
75
|
+
await assert.rejects(() =>
|
|
76
|
+
collect(openSealedStream(KEY, once(sealed.subarray(0, sealed.length - 64))))
|
|
77
|
+
);
|
|
78
|
+
const tampered = Buffer.from(sealed);
|
|
79
|
+
tampered[tampered.length - 40] ^= 0xff;
|
|
80
|
+
await assert.rejects(() => collect(openSealedStream(KEY, once(tampered))));
|
|
81
|
+
const other = crypto.createHash('sha256').update('other key').digest();
|
|
82
|
+
await assert.rejects(() => collect(openSealedStream(other, once(sealed))));
|
|
83
|
+
});
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
describe('openSealedRange', () => {
|
|
87
|
+
const C = BLOB_CHUNK_BYTES;
|
|
88
|
+
|
|
89
|
+
it('reads any inclusive range, within a chunk or across several, up to the last byte', async () => {
|
|
90
|
+
for (const size of [1, 5000, C, C + 1, 3 * C + 17]) {
|
|
91
|
+
const data = crypto.randomBytes(size);
|
|
92
|
+
const sealed = await seal(data);
|
|
93
|
+
const read = (r: { start: number; end: number }) => sliced(sealed, r.start, r.end);
|
|
94
|
+
const clamp = (n: number) => Math.min(size - 1, Math.max(0, n));
|
|
95
|
+
const ranges = [
|
|
96
|
+
[0, 0],
|
|
97
|
+
[0, size - 1],
|
|
98
|
+
[size - 1, size - 1],
|
|
99
|
+
[Math.floor(size / 2), size - 1],
|
|
100
|
+
[clamp(C - 3), clamp(C + 2)],
|
|
101
|
+
[clamp(C), clamp(2 * C + 5)]
|
|
102
|
+
];
|
|
103
|
+
for (const [start, end] of ranges) {
|
|
104
|
+
const got = await collect(openSealedRange(KEY, read, size, { start, end }));
|
|
105
|
+
assert.deepEqual(
|
|
106
|
+
got,
|
|
107
|
+
data.subarray(start, end + 1),
|
|
108
|
+
`size ${size}, ${start}-${end}`
|
|
109
|
+
);
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
});
|
|
113
|
+
|
|
114
|
+
it('reads only the header and the chunks that hold the range', async () => {
|
|
115
|
+
const size = 3 * C + 10;
|
|
116
|
+
const sealed = await seal(crypto.randomBytes(size));
|
|
117
|
+
const reads: { start: number; end: number }[] = [];
|
|
118
|
+
const read = (r: { start: number; end: number }) => {
|
|
119
|
+
reads.push(r);
|
|
120
|
+
return sliced(sealed, r.start, r.end);
|
|
121
|
+
};
|
|
122
|
+
await collect(openSealedRange(KEY, read, size, { start: C + 5, end: C + 10 }));
|
|
123
|
+
assert.equal(reads.length, 2);
|
|
124
|
+
assert.equal(reads[1].end - reads[1].start + 1, C + 16);
|
|
125
|
+
});
|
|
126
|
+
|
|
127
|
+
it('refuses a range outside the blob, a tampered chunk, and a short read', async () => {
|
|
128
|
+
const size = 2 * C;
|
|
129
|
+
const sealed = await seal(crypto.randomBytes(size));
|
|
130
|
+
const read = (r: { start: number; end: number }) => sliced(sealed, r.start, r.end);
|
|
131
|
+
await assert.rejects(() =>
|
|
132
|
+
collect(openSealedRange(KEY, read, size, { start: 0, end: size }))
|
|
133
|
+
);
|
|
134
|
+
await assert.rejects(() => collect(openSealedRange(KEY, read, size, { start: 5, end: 4 })));
|
|
135
|
+
const tampered = Buffer.from(sealed);
|
|
136
|
+
tampered[C + 100] ^= 0xff;
|
|
137
|
+
const readTampered = (r: { start: number; end: number }) =>
|
|
138
|
+
sliced(tampered, r.start, r.end);
|
|
139
|
+
await assert.rejects(() =>
|
|
140
|
+
collect(openSealedRange(KEY, readTampered, size, { start: C - 10, end: C + 10 }))
|
|
141
|
+
);
|
|
142
|
+
const short = (r: { start: number; end: number }) =>
|
|
143
|
+
sliced(sealed, r.start, Math.min(r.end, r.start + 100));
|
|
144
|
+
await assert.rejects(() =>
|
|
145
|
+
collect(openSealedRange(KEY, short, size, { start: 0, end: 10 }))
|
|
146
|
+
);
|
|
147
|
+
});
|
|
148
|
+
});
|