@deveye/types 0.15.1 → 0.16.0

package/src/sdk/client.ts

@@ -1,4 +1,4 @@
-import type { ComponentType } from 'react';
+import type { ComponentType, ReactNode } from 'react';
 
 /**
  * Client-side SDK contracts: what your package's `./client` entry exports and
@@ -10,12 +10,17 @@ import type { ComponentType } from 'react';
  * shapes both sides must agree on.
  */
 
-/** The scope a settings panel is opened for. */
-export type SdkSettingsScope =
-    { kind: 'feature' } | { kind: 'item'; itemId: number; itemLabel: string };
+/**
+ * The scope a settings panel is opened for. An item id is a number for every
+ * row-keyed feature (the default), a string for a device (a UUID): a module
+ * whose items are strings types its panels `SettingsPanelProps<string>`. The
+ * shell's own sections (sharing, permissions, notifications) key on the number.
+ */
+export type SdkSettingsScope<Id extends number | string = number> =
+    { kind: 'feature' } | { kind: 'item'; itemId: Id; itemLabel: string };
 
-export interface SettingsPanelProps {
-    scope: SdkSettingsScope;
+export interface SettingsPanelProps<Id extends number | string = number> {
+    scope: SdkSettingsScope<Id>;
     /** Caller has `write` on the feature. Render read-only when false. */
     canWrite: boolean;
 }
@@ -39,19 +44,18 @@ export interface FeatureClient {
     Full: ComponentType<FeatureViewProps>;
     /**
      * Panels for the manifest's settings tabs that need one: `'general'`,
-     * `'sources'`, and any custom tab id. Generic tabs (`'notifications'`,
-     * `'permissions'`) need no panel.
+     * `'sources'`, `'encryption'`, and any custom tab id. Generic tabs
+     * (`'notifications'`, `'permissions'`) need no panel.
      */
-    settingsPanels?: Readonly<Record<string, ComponentType<SettingsPanelProps>>>;
+    // `never` as the id: a panel typed for numbers and one typed for strings
+    // are both assignable here (props are contravariant), and the shell, which
+    // holds a `number | string`, casts once at that boundary.
+    settingsPanels?: Readonly<Record<string, ComponentType<SettingsPanelProps<never>>>>;
     /**
-     * The compact topbar widget declared by `manifest.topbarWidget`.
-     *
-     * Rendered with NO props, on purpose: that is the security contract. The
-     * host hands the component nothing (no user, no stores, no other feature's
-     * state); everything it shows must come through YOUR feature's commands
-     * (`featureApi`), which the server authorizes against the caller's grants
-     * like any other call. The host also only mounts it for members whose role
-     * grants your feature. Freedom inside the box, nothing outside it.
+     * The compact topbar widget declared by `manifest.topbarWidget`. Rendered
+     * with NO props: everything it shows must come through YOUR feature's
+     * commands, which the server authorizes against the caller's grants. The
+     * host mounts it only for members whose role grants your feature.
      */
     TopbarWidget?: ComponentType;
     /**
@@ -63,4 +67,260 @@ export interface FeatureClient {
     preload?: boolean;
     /** Hold the password-encryption unlock alive while the full view is open. */
     holdSecrecy?: boolean;
+    /**
+     * Named contracts offered to the host's screens (see `sdk/providers.ts`),
+     * the client twin of `FeatureService.providers`. The app looks a provider
+     * up at render time and degrades cleanly when the module is absent.
+     */
+    providers?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A monitored service, as the Uptime client provider hands it to the host.
+ * Deliberately a subset of the module's own contract: what a linked-service
+ * block needs, and nothing the module may want to change later.
+ */
+export interface UptimeLinkedService {
+    id: number;
+    name: string;
+    url: string;
+    enabled: boolean;
+    status: string;
+    lastCheckedAt: number | null;
+    ratio24h: number | null;
+    ratio7d: number | null;
+    ratio30d: number | null;
+}
+
+/** One bucket of a service's availability history. */
+export interface UptimeHistoryPoint {
+    at: number;
+    checks: number;
+    upChecks: number;
+    avgMs: number | null;
+    minMs: number | null;
+    maxMs: number | null;
+}
+
+export type UptimeHistoryResolution = 'raw' | 'hour' | 'day';
+
+/**
+ * What the Devices module offers the app's own screens (`DEVICES_CLIENT_PROVIDER`):
+ * the workspace's devices as a live store, the panel of one device (the home
+ * renders one view per placed device), and its compact tile. Without the
+ * module the home places no device and the topbar counts none.
+ */
+export interface DevicesClientProvider {
+    /** The active workspace's devices, refreshed by the `devices` live topic. */
+    useDevices(): { devices: readonly SdkDeviceSummary[]; loading: boolean; error: string | null };
+    refreshDevices(): void;
+    /** Forgets every loaded device (the app calls it when the session ends). */
+    resetDevices(): void;
+    DevicePanel: ComponentType<{ deviceId: string }>;
+    DeviceWidget: ComponentType<{ deviceId: string; hideStatus?: boolean }>;
+}
+
+/** What the app's screens need of a device: identity and liveness, never the report. */
+export interface SdkDeviceSummary {
+    id: string;
+    name: string;
+    online: boolean;
+    status: string;
+    platform: string;
+}
+
+/**
+ * What the Uptime module offers the host's screens under
+ * `UPTIME_CLIENT_PROVIDER`: the availability strip, the ratios, the history
+ * hook feeding the strip, the workspace's services, and the feature's own
+ * service dialog.
+ */
+export interface UptimeClientProvider {
+    /** The workspace's services, as `uptime.list` returns them. */
+    listServices(): Promise<readonly UptimeLinkedService[]>;
+    /**
+     * A service's history for the strip. `stamp` is what re-reads it (pass
+     * `service.lastCheckedAt`); no timer.
+     */
+    useServiceHistory(
+        id: number,
+        stamp: number | null
+    ): {
+        points: UptimeHistoryPoint[];
+        resolution: UptimeHistoryResolution;
+        axis: { from: number; to: number };
+    };
+    /** The availability strip over a window. */
+    StatusBars: ComponentType<{
+        points: UptimeHistoryPoint[];
+        from: number;
+        to: number;
+        resolution: UptimeHistoryResolution;
+        /** Rendered facing the legend (the ratios, typically). */
+        trailing?: ReactNode;
+    }>;
+    /** The three-window availability ratios of a service. */
+    Ratios: ComponentType<{ service: UptimeLinkedService; compact?: boolean }>;
+    /** The feature's service form: `service: null` declares a new one. */
+    ServiceDialog: ComponentType<{
+        open: boolean;
+        service: UptimeLinkedService | null;
+        onClose: () => void;
+        onSaved: (service: UptimeLinkedService) => void;
+    }>;
+}
+
+/**
+ * A database of the workspace, as the Databases client provider lists it for
+ * a project's "add a database" picker. Deliberately a subset of the module's
+ * own contract: what a picker shows, and nothing the module may change later.
+ */
+export interface DatabaseLinkedCandidate {
+    id: number;
+    name: string;
+    /** The engine as the module labels it (« MySQL », « PostgreSQL »). */
+    engineLabel: string;
+    /** How many projects of the workspace already use it. */
+    projectCount: number;
+}
+
+/**
+ * What the Databases module offers the host's screens under
+ * `DATABASE_CLIENT_PROVIDER`: the workspace's databases, a linked database
+ * rendered in full inside a project's tab, and the feature's own dialog.
+ */
+export interface DatabaseClientProvider {
+    /** The workspace's databases, as `database.list` returns them. */
+    listDatabases(): Promise<readonly DatabaseLinkedCandidate[]>;
+    /**
+     * A database linked to a project, shown in full: header (name, address,
+     * actions, its own settings button), state, alerts, table explorer. Loads
+     * itself by `database.get`, follows the feature's invalidations, and
+     * renders the host's "unlink" as its trailing action. Handles the
+     * explorer's expanded mode on its own.
+     */
+    LinkedDatabase: ComponentType<{ databaseId: number; canWrite: boolean; onUnlink: () => void }>;
+    /** The feature's database form, to declare a new database from a project. */
+    DatabaseDialog: ComponentType<{
+        open: boolean;
+        onClose: () => void;
+        onSaved: (databaseId: number) => void;
+    }>;
+}
+
+/**
+ * A deploy target of the workspace, as the Deploy client provider lists it
+ * for a project's "add a target" picker.
+ */
+export interface DeployLinkedCandidate {
+    id: number;
+    name: string;
+    /** The instance host, as the module labels it (« dokploy.example.com »). */
+    host: string;
+}
+
+/**
+ * What the Deploy module offers the host's screens under
+ * `DEPLOY_CLIENT_PROVIDER`: the workspace's targets, a linked target rendered
+ * in full inside a project's tab, and the feature's own dialog.
+ */
+export interface DeployClientProvider {
+    /** The workspace's targets, as `deploy.list` returns them. */
+    listTargets(): Promise<readonly DeployLinkedCandidate[]>;
+    /**
+     * A target linked to a project, shown in full: identity, last deployment,
+     * trigger, its own settings button. Loads itself by `deploy.get`, follows
+     * the feature's invalidations, and renders the host's "unlink" as its
+     * trailing action. `projectId` files a trigger in that project's timeline.
+     */
+    LinkedTarget: ComponentType<{
+        targetId: number;
+        projectId: number;
+        canWrite: boolean;
+        onUnlink: () => void;
+    }>;
+    /** The feature's target form, to declare a new target from a project. */
+    TargetDialog: ComponentType<{
+        open: boolean;
+        onClose: () => void;
+        onSaved: (targetId: number) => void;
+    }>;
+}
+
+/**
+ * A git repository of the workspace, as the Git client provider lists it for
+ * a project's "add a repository" picker.
+ */
+export interface GitLinkedCandidate {
+    id: number;
+    owner: string;
+    repo: string;
+}
+
+/**
+ * What the Git module offers the host's screens under `GIT_CLIENT_PROVIDER`:
+ * the workspace's repositories, a linked repository rendered in full inside a
+ * project's tab, and the feature's own dialog.
+ */
+export interface GitClientProvider {
+    /** The workspace's repositories, as `git.repoList` returns them. */
+    listRepos(): Promise<readonly GitLinkedCandidate[]>;
+    /**
+     * A repository linked to a project, shown in full: header (name, sync
+     * state, actions, its own settings button), graph and panels. Loads
+     * itself by `git.repoGet`, follows the feature's invalidations and the
+     * sync progress, and renders the host's "unlink" as its trailing action.
+     */
+    LinkedRepo: ComponentType<{ repoId: number; canWrite: boolean; onUnlink: () => void }>;
+    /** The feature's repository form, to declare a new repository from a project. */
+    RepoDialog: ComponentType<{
+        open: boolean;
+        onClose: () => void;
+        onSaved: (repoId: number) => void;
+    }>;
+}
+
+/** A tracked site of the workspace, as the Audience client provider lists it for a project's picker. */
+export interface AudienceLinkedCandidate {
+    id: number;
+    name: string;
+}
+
+/**
+ * What the Audience module offers the host's screens under
+ * `AUDIENCE_CLIENT_PROVIDER`: the workspace's sites, a linked site rendered
+ * in full inside a project's tab, and the feature's own dialog.
+ */
+export interface AudienceClientProvider {
+    /** The workspace's sites, as `audience.list` returns them. */
+    listSites(): Promise<readonly AudienceLinkedCandidate[]>;
+    /**
+     * A site linked to a project, shown in full: its sticky heading, actions
+     * (install, its own settings button), stats, funnels. Loads itself by
+     * `audience.get`, follows the feature's invalidations and the live beat,
+     * and renders the host's "unlink" as its trailing action.
+     */
+    LinkedSite: ComponentType<{ siteId: number; canWrite: boolean; onUnlink: () => void }>;
+    /** The feature's site form, to declare a new site from a project. */
+    SiteDialog: ComponentType<{
+        open: boolean;
+        onClose: () => void;
+        onSaved: (siteId: number) => void;
+    }>;
+}
+
+/**
+ * What the Mail module offers the host's screens under `MAIL_CLIENT_PROVIDER`:
+ * the ready senders (open tier, enabled) an email notification channel picks
+ * from, and the feature's own account dialog.
+ */
+export interface MailClientProvider {
+    /** The workspace's ready senders, as the module lists them. */
+    listSenders(): Promise<readonly { id: number; label: string; address: string }[]>;
+    /**
+     * The feature's account form (manual connection or OAuth consent), to
+     * declare a mailbox from the channel form. `onSaved` fires when a mailbox
+     * came out of it; the host re-lists to find which.
+     */
+    AccountDialog: ComponentType<{ open: boolean; onClose: () => void; onSaved: () => void }>;
 }

package/src/sdk/devb.ts

@@ -0,0 +1,120 @@
+import crypto from 'crypto';
+
+/**
+ * `DEVB` : le conteneur chiffré que CloudSync (blobs) et Backup (archives)
+ * partagent. Une seule définition parce que le format est figé : un octet de
+ * divergence et une sauvegarde ne se rouvre plus. Ne s'occupe que du FORMAT ;
+ * la clé est l'affaire de chaque module (`scripts/restore-backup.mjs` côté app
+ * relit ce format sans DevEye).
+ *
+ * v1, flux unique (lu, plus jamais écrit) :
+ *   magic 'DEVB' (4) | 0x01 (1) | nonce (12) | ciphertext | tag GCM (16)
+ * Un seul AES-256-GCM ; irreprenable après redémarrage, l'état du cipher ne se
+ * sérialise pas.
+ *
+ * v2, scellé par blocs (format d'écriture) :
+ *   magic 'DEVB' (4) | 0x02 (1) | nonce de base (12) | bloc* | bloc final
+ *   bloc = ciphertext ({@link BLOB_CHUNK_BYTES} octets de clair) | tag (16)
+ * Nonce = nonce de base XOR compteur, AAD = compteur (8) + marqueur de fin (1) :
+ * le marqueur ferme la troncature, le compteur le réordonnancement. La reprise
+ * d'un partiel relit les blocs complets en local pour reconstituer le SHA-256
+ * courant, sans retransmettre un octet.
+ */
+
+const BLOB_MAGIC = Buffer.from('DEVB');
+const BLOB_V1 = 0x01;
+const BLOB_V2 = 0x02;
+
+/** Longueur de l'en-tête (magic + version + nonce) et d'un tag GCM. */
+export const BLOB_HEADER_LEN = BLOB_MAGIC.length + 1 + 12;
+export const BLOB_TAG_LEN = 16;
+
+/**
+ * Clair par bloc en v2. 1 Mio : assez grand pour que le surcoût des tags soit
+ * négligeable (16 octets par Mio, soit 0,0015 %), assez petit pour qu'une
+ * reprise ne reperde jamais plus d'un Mio de travail.
+ */
+export const BLOB_CHUNK_BYTES = 1024 * 1024;
+/** Taille d'un bloc v2 complet sur le disque. */
+export const BLOB_CHUNK_SEALED = BLOB_CHUNK_BYTES + BLOB_TAG_LEN;
+
+export const BLOB_VERSION_STREAM = BLOB_V1;
+export const BLOB_VERSION_CHUNKED = BLOB_V2;
+
+/** L'en-tête d'un nouveau blob v2 (magic + version + nonce de base aléatoire). */
+export function createBlobHeader(): Buffer {
+    return Buffer.concat([BLOB_MAGIC, Buffer.from([BLOB_V2]), crypto.randomBytes(12)]);
+}
+
+/** Valide un en-tête et rend sa version + son nonce de base. */
+export function parseBlobHeader(header: Buffer): { version: number; nonce: Buffer } {
+    if (header.length !== BLOB_HEADER_LEN || !header.subarray(0, 4).equals(BLOB_MAGIC)) {
+        throw new Error('DEVB : blob corrompu (en-tête invalide)');
+    }
+    const version = header[4];
+    if (version !== BLOB_V1 && version !== BLOB_V2) {
+        throw new Error(`DEVB : version de blob inconnue (${version})`);
+    }
+    return { version, nonce: header.subarray(5, 17) };
+}
+
+/**
+ * Le nonce du bloc `index` : nonce de base XOR le compteur en big-endian sur
+ * les 8 derniers octets. Deux blobs n'ont jamais le même nonce de base (12
+ * octets aléatoires), donc jamais la même paire (clé, nonce) — la règle d'or
+ * de GCM tient.
+ */
+function chunkNonce(base: Buffer, index: number): Buffer {
+    const nonce = Buffer.from(base);
+    const counter = Buffer.alloc(8);
+    counter.writeBigUInt64BE(BigInt(index));
+    for (let i = 0; i < 8; i += 1) nonce[4 + i] ^= counter[i];
+    return nonce;
+}
+
+/** L'AAD d'un bloc : son rang, et s'il termine le blob. */
+function chunkAad(index: number, final: boolean): Buffer {
+    const aad = Buffer.alloc(9);
+    aad.writeBigUInt64BE(BigInt(index));
+    aad[8] = final ? 1 : 0;
+    return aad;
+}
+
+/** Scelle un bloc de clair en `ciphertext | tag`. */
+export function sealChunk(
+    key: Buffer,
+    base: Buffer,
+    index: number,
+    plain: Buffer,
+    final: boolean
+): Buffer {
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, chunkNonce(base, index));
+    cipher.setAAD(chunkAad(index, final));
+    const body = Buffer.concat([cipher.update(plain), cipher.final()]);
+    return Buffer.concat([body, cipher.getAuthTag()]);
+}
+
+/**
+ * Ouvre un bloc scellé. Lève si le tag ne colle pas — donc si le contenu, son
+ * rang ou son statut de dernier bloc ont bougé.
+ */
+export function openChunk(
+    key: Buffer,
+    base: Buffer,
+    index: number,
+    sealed: Buffer,
+    final: boolean
+): Buffer {
+    if (sealed.length < BLOB_TAG_LEN) throw new Error('DEVB : bloc de blob tronqué');
+    const body = sealed.subarray(0, sealed.length - BLOB_TAG_LEN);
+    const tag = sealed.subarray(sealed.length - BLOB_TAG_LEN);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, chunkNonce(base, index));
+    decipher.setAAD(chunkAad(index, final));
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(body), decipher.final()]);
+}
+
+/** Ouvre le déchiffrement d'un blob v1 (flux unique) depuis son en-tête. */
+export function openStreamDecipher(key: Buffer, nonce: Buffer): crypto.DecipherGCM {
+    return crypto.createDecipheriv('aes-256-gcm', key, nonce);
+}

package/src/sdk/manifest.test.ts

@@ -0,0 +1,96 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { z } from 'zod';
+
+import {
+    externalDescriptorOf,
+    resolveExtras,
+    validateManifest,
+    type FeatureManifest
+} from './manifest';
+
+const base: FeatureManifest = {
+    id: 'x-demo',
+    label: 'Demo',
+    description: 'A demo module.',
+    icon: 'x-demo-icon',
+    category: 'daily',
+    notifies: false,
+    hasItems: false,
+    shareTier: 'never',
+    resources: ['x-demo.state'],
+    commands: [{ command: 'x-demo.get', input: z.object({}), output: z.object({}) }]
+};
+
+test('validateManifest accepts a minimal external manifest', () => {
+    assert.doesNotThrow(() => validateManifest(base));
+});
+
+test('validateManifest rejects the classic mistakes', () => {
+    const rejects = (patch: Partial<FeatureManifest>, fragment: string) =>
+        assert.throws(() => validateManifest({ ...base, ...patch }), new RegExp(fragment));
+    rejects({ label: '  ' }, 'empty label');
+    rejects({ hasItems: true }, 'itemNoun');
+    rejects({ shareTier: 'open' }, "shareTier 'never'");
+    rejects({ commandPrefix: 'x-demo.' }, 'commandPrefix');
+    rejects(
+        { commands: [{ command: 'other.get', input: z.object({}), output: z.object({}) }] },
+        'x-demo'
+    );
+});
+
+test('externalDescriptorOf projects the identity fields only, and refuses a native id', () => {
+    assert.deepEqual(
+        externalDescriptorOf({ ...base, itemNoun: 'thing', sources: { hint: 'keys' } }),
+        {
+            id: 'x-demo',
+            label: 'Demo',
+            description: 'A demo module.',
+            icon: 'x-demo-icon',
+            notifies: false,
+            hasItems: false,
+            itemNoun: 'thing',
+            sources: { hint: 'keys' },
+            shareTier: 'never'
+        }
+    );
+    assert.throws(() => externalDescriptorOf({ ...base, id: 'weather' }), /not an external id/);
+});
+
+test('resolveExtras: the owner holds everything, a member what the grant says, unknown keys nothing', () => {
+    const specs: FeatureManifest['extraPermissions'] = [
+        { key: 'reset', type: 'toggle', label: 'Reset', description: '' },
+        {
+            key: 'limit',
+            type: 'choice',
+            label: 'Limit',
+            description: '',
+            options: [
+                { value: 'low', label: 'Low' },
+                { value: 'high', label: 'High' }
+            ],
+            default: 'low',
+            ownerValue: 'high'
+        }
+    ];
+    const owner = resolveExtras(specs, true, {});
+    assert.equal(owner.canExtra('reset'), true);
+    assert.equal(owner.extraValue('limit'), 'high');
+
+    const member = resolveExtras(specs, false, { reset: true, limit: 'high' });
+    assert.equal(member.canExtra('reset'), true);
+    assert.equal(member.extraValue('limit'), 'high');
+
+    const restricted = resolveExtras(specs, false, { reset: false, limit: 'bogus' });
+    assert.equal(restricted.canExtra('reset'), false);
+    assert.equal(
+        restricted.extraValue('limit'),
+        'low',
+        'a value outside the options falls back to the default'
+    );
+
+    // Wrong kind or undeclared: nothing, owner or not.
+    assert.equal(owner.canExtra('limit'), false);
+    assert.equal(owner.extraValue('reset'), '');
+    assert.equal(resolveExtras(undefined, true, { reset: true }).canExtra('reset'), false);
+});