@deveye/types 0.15.0

package/src/features/registry.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { audienceCommands } from './audience';
+import { backupCommands } from './backup';
+import { deviceCommands } from './device';
+import { deviceFilesCommands } from './deviceFiles';
+import { deviceLogCommands } from './deviceLogs';
+import { deviceTerminalCommands } from './deviceTerminal';
+import { databaseCommands } from './database';
+import { deployCommands } from './deploy';
+import { financeCommands } from './finance';
+import { gitCommands } from './git';
+import { homeCommands } from './home';
+import { liveCommands } from './live';
+import { logsCommands } from './logs';
+import { mailCommands } from './mail';
+import { metricsCommands } from './metrics';
+import { noteCommands } from './note';
+import { notifyCommands } from './notify';
+import { sharingCommands } from './sharing';
+import { passwordCommands } from './password';
+import { projectCommands } from './project';
+import { secrecyCommands } from './secrecy';
+import { sentinelCommands } from './sentinel';
+import { twoFactorCommands } from './twoFactor';
+import { uptimeCommands } from './uptime';
+import { userCommands } from './user';
+import { adminCommands } from './admin';
+import { workspaceCommands } from './workspace';
+
+export interface FeatureCommandDescriptor<C extends string = string> {
+    command: C;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
+}
+
+export const featureCommands = [
+    ...workspaceCommands,
+    ...adminCommands,
+    ...userCommands,
+    ...passwordCommands,
+    ...noteCommands,
+    ...projectCommands,
+    ...gitCommands,
+    ...deployCommands,
+    ...backupCommands,
+    ...databaseCommands,
+    ...financeCommands,
+    ...audienceCommands,
+    ...deviceCommands,
+    ...deviceLogCommands,
+    ...deviceTerminalCommands,
+    ...deviceFilesCommands,
+    ...metricsCommands,
+    ...sentinelCommands,
+    ...uptimeCommands,
+    ...twoFactorCommands,
+    ...secrecyCommands,
+    ...logsCommands,
+    ...homeCommands,
+    ...mailCommands,
+    ...notifyCommands,
+    ...sharingCommands,
+    ...liveCommands
+] as const;
+
+export const featureCommandRegistry: Record<string, FeatureCommandDescriptor> = Object.fromEntries(
+    featureCommands.map((c) => [c.command, c])
+);
+
+/**
+ * Verse les contrats d'un module installé dans le registre des commandes,
+ * celui que le `ws.send` du client consulte avant tout envoi. Sans cet
+ * enregistrement, chaque commande d'un module serait refusée côté client
+ * (« Unknown command ») avant même d'atteindre la socket, et son interface
+ * resterait en chargement pour toujours.
+ *
+ * Une native rapatriée déclare les MÊMES objets que le registre publié : la
+ * réinscription à l'identique est un no-op. Deux contrats différents sous le
+ * même nom, en revanche, sont une collision de config, et le chargement doit
+ * le dire plutôt que d'en servir un des deux au hasard.
+ */
+export function registerFeatureCommands(commands: readonly FeatureCommandDescriptor[]): void {
+    for (const c of commands) {
+        const existing = featureCommandRegistry[c.command];
+        if (existing === c) continue;
+        if (existing) {
+            throw new Error(
+                `registerFeatureCommands: « ${c.command} » est déjà enregistrée par un autre module`
+            );
+        }
+        featureCommandRegistry[c.command] = c;
+    }
+}
+
+export type FeatureCommandName = (typeof featureCommands)[number]['command'];
+
+export type CommandInput<N extends FeatureCommandName> = z.infer<
+    Extract<(typeof featureCommands)[number], { command: N }>['input']
+>;
+
+export type CommandOutput<N extends FeatureCommandName> = z.infer<
+    Extract<(typeof featureCommands)[number], { command: N }>['output']
+>;

package/src/features/secrecy.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import { secrecyStatusSchema } from '../domain/secrecy';
+
+/** Current state of password-based encryption for the caller. */
+export const secrecyStatus = {
+    command: 'secrecy.status' as const,
+    input: z.object({}),
+    output: z.object({ status: secrecyStatusSchema })
+};
+
+/**
+ * Unlock the DEK for this session by supplying the account password. Required
+ * before reading/writing encrypted data while the feature is enabled.
+ */
+export const secrecyUnlock = {
+    command: 'secrecy.unlock' as const,
+    input: z.object({ password: z.string().min(1) }),
+    output: z.object({ status: secrecyStatusSchema })
+};
+
+/**
+ * Enable password-based encryption: re-wrap the DEK with a password-derived
+ * key. When `recovery` is true a one-time recovery code is generated and
+ * returned exactly once (it also wraps the DEK as a safety net).
+ */
+export const secrecyEnable = {
+    command: 'secrecy.enable' as const,
+    input: z.object({
+        password: z.string().min(1),
+        recovery: z.boolean()
+    }),
+    output: z.object({
+        status: secrecyStatusSchema,
+        /** Present only when `recovery` was requested. Shown once. */
+        recoveryCode: z.string().min(1).optional()
+    })
+};
+
+/** Disable the feature: re-wrap the DEK with the server key. */
+export const secrecyDisable = {
+    command: 'secrecy.disable' as const,
+    input: z.object({ password: z.string().min(1) }),
+    output: z.object({ status: secrecyStatusSchema })
+};
+
+/**
+ * Set how long the password stays validated after entry (the "sudo-like" grace
+ * window), in seconds. `0` disables it: the password is then required for every
+ * encrypted action. Bounded to a day to keep the window meaningful.
+ */
+export const secrecySetReauth = {
+    command: 'secrecy.setReauth' as const,
+    input: z.object({ seconds: z.number().int().min(0).max(86400) }),
+    output: z.object({ status: secrecyStatusSchema })
+};
+
+/**
+ * Hold (or release) the cached DEK for the duration of an open action popup.
+ *
+ * `active: true` is a heartbeat: it pins the DEK so the sliding grace window
+ * cannot flush it while the user composes a long action, and must be re-sent
+ * periodically — the server only honours the hold for a short lease, so if the
+ * popup vanishes for *any* reason (close, navigation, crash, disconnect) the
+ * heartbeats stop and the DEK reverts to a normal countdown. `active: false`
+ * releases the hold and restarts a fresh grace window. The DEK can therefore
+ * never linger indefinitely: only a genuinely-still-open popup keeps it alive.
+ */
+export const secrecyHold = {
+    command: 'secrecy.hold' as const,
+    input: z.object({ active: z.boolean() }),
+    output: z.object({ status: secrecyStatusSchema })
+};
+
+/**
+ * Slide the grace window forward by one full interval, as if an encrypted action
+ * had just happened — used by the topbar timer widget to let the user manually
+ * postpone the password flush. No-op when locked or when the feature is off.
+ */
+export const secrecyTouch = {
+    command: 'secrecy.touch' as const,
+    input: z.object({}),
+    output: z.object({ status: secrecyStatusSchema })
+};
+
+/**
+ * Immediately flush the cached DEK for this session, re-locking the vault so the
+ * next encrypted action re-prompts — the manual counterpart to {@link secrecyTouch},
+ * letting the user force a re-lock ahead of the grace window. No-op when already
+ * locked or when the feature is off.
+ */
+export const secrecyLock = {
+    command: 'secrecy.lock' as const,
+    input: z.object({}),
+    output: z.object({ status: secrecyStatusSchema })
+};
+
+/**
+ * Recover access after a forgotten password using the recovery code, choosing
+ * a new password to re-wrap the DEK with.
+ */
+export const secrecyRecover = {
+    command: 'secrecy.recover' as const,
+    input: z.object({
+        recoveryCode: z.string().min(1),
+        newPassword: z.string().min(1)
+    }),
+    output: z.object({ status: secrecyStatusSchema })
+};
+
+export const secrecyCommands = [
+    secrecyStatus,
+    secrecyUnlock,
+    secrecyEnable,
+    secrecyDisable,
+    secrecySetReauth,
+    secrecyHold,
+    secrecyTouch,
+    secrecyLock,
+    secrecyRecover
+] as const;

package/src/features/sentinel.ts

@@ -0,0 +1,233 @@
+import { z } from 'zod';
+import {
+    allowEntrySchema,
+    allowScopeSchema,
+    baselineEntrySchema,
+    baselineKindSchema,
+    devicePostureSchema,
+    deviceSentinelStateSchema,
+    findingSchema,
+    findingSeveritySchema,
+    findingStateSchema,
+    SENTINEL_INTEGRITY_MINUTES_MAX,
+    SENTINEL_INTEGRITY_MINUTES_MIN,
+    SENTINEL_LEARNING_DAYS_MAX,
+    SENTINEL_LEARNING_DAYS_MIN,
+    sentinelRuleIdSchema,
+    severityCountsSchema
+} from '../domain/sentinel';
+
+const deviceId = z.uuid();
+const findingId = z.number().int().positive();
+
+/** Plafond d'une page de constats. Au-delà, on filtre plutôt qu'on déroule. */
+export const SENTINEL_PAGE_MAX = 200;
+
+/**
+ * L'état de la flotte en une réponse : de quoi peindre la carte d'accueil et
+ * l'en-tête de la vue plein écran sans second aller-retour.
+ */
+export const sentinelOverview = {
+    command: 'sentinel.overview' as const,
+    input: z.object({}),
+    output: z.object({
+        /** Constats ouverts de tout l'espace, par gravité. */
+        open: severityCountsSchema,
+        /**
+         * Score de posture de la flotte : moyenne des scores concluants. `null`
+         * quand aucune machine n'a encore de posture mesurable — et non `0`, qui
+         * se lirait comme une flotte en ruine.
+         */
+        fleetScore: z.number().int().min(0).max(100).nullable(),
+        devices: z.array(deviceSentinelStateSchema).max(500)
+    })
+};
+
+/**
+ * Le décompte seul, pour la carte de grille et la pastille de Monitoring.
+ *
+ * Séparé d'`overview` parce qu'il se rafraîchit à chaque changement et qu'il
+ * n'a besoin d'aucune jointure : deux `COUNT` indexés contre un balayage de
+ * toute la flotte.
+ */
+export const sentinelCount = {
+    command: 'sentinel.count' as const,
+    input: z.object({}),
+    output: z.object({
+        open: severityCountsSchema,
+        /** Appareils sur lesquels Sentinelle est active. */
+        watched: z.number().int().nonnegative()
+    })
+};
+
+/** Les constats, filtrables. Tri imposé : gravité décroissante puis fraîcheur. */
+export const sentinelFindings = {
+    command: 'sentinel.findings' as const,
+    input: z.object({
+        deviceId: deviceId.nullable().default(null),
+        state: findingStateSchema.nullable().default(null),
+        minSeverity: findingSeveritySchema.nullable().default(null),
+        rule: sentinelRuleIdSchema.nullable().default(null),
+        limit: z.number().int().min(1).max(SENTINEL_PAGE_MAX).default(50),
+        offset: z.number().int().nonnegative().default(0)
+    }),
+    output: z.object({
+        findings: z.array(findingSchema).max(SENTINEL_PAGE_MAX),
+        /** Total correspondant au filtre, pour paginer sans deviner. */
+        total: z.number().int().nonnegative()
+    })
+};
+
+/** L'inventaire appris d'une machine, par nature. */
+export const sentinelBaseline = {
+    command: 'sentinel.baseline' as const,
+    input: z.object({
+        deviceId,
+        kind: baselineKindSchema.nullable().default(null),
+        limit: z.number().int().min(1).max(1000).default(500)
+    }),
+    output: z.object({
+        deviceId,
+        entries: z.array(baselineEntrySchema).max(1000),
+        total: z.number().int().nonnegative()
+    })
+};
+
+/** Le détail de posture d'une machine, contrôle par contrôle. */
+export const sentinelPosture = {
+    command: 'sentinel.posture' as const,
+    input: z.object({ deviceId }),
+    output: z.object({ posture: devicePostureSchema })
+};
+
+/**
+ * « Ceci est légitime. »
+ *
+ * Écrit une autorisation **et** résout le constat, dans cet ordre : si l'écriture
+ * échoue, le constat reste ouvert plutôt que de disparaître sans qu'aucune règle
+ * ne l'en empêche de revenir. En portée `fleet`, l'autorisation vaut pour tout
+ * l'espace, y compris les machines qui le rejoindront ensuite.
+ */
+export const sentinelAcknowledge = {
+    command: 'sentinel.acknowledge' as const,
+    input: z.object({
+        findingId,
+        scope: allowScopeSchema.default('device'),
+        reason: z.string().max(255).nullable().default(null)
+    }),
+    output: z.object({
+        finding: findingSchema,
+        allow: allowEntrySchema
+    })
+};
+
+/**
+ * « C'est réglé. »
+ *
+ * Ferme le constat **sans** écrire d'autorisation : la situation a cessé, elle
+ * n'a pas été jugée normale. La distinction n'est pas cosmétique — un constat
+ * acquitté ne rouvrira plus jamais, un constat réglé rouvre au premier relevé
+ * qui le revoit, et c'est précisément ce qu'on veut d'une correction.
+ *
+ * Le moteur résout tout seul ce qu'il sait rejouer (les règles d'instant). Restent
+ * les constats d'**événement** — une authentification, une entrée de persistance :
+ * ils décrivent quelque chose qui a eu lieu, donc rien ne cessera de les
+ * déclencher, et sans cette commande la seule sortie était de les déclarer
+ * légitimes. C'est-à-dire de mentir pour faire le ménage.
+ */
+export const sentinelResolve = {
+    command: 'sentinel.resolve' as const,
+    input: z.object({ findingId }),
+    output: z.object({ finding: findingSchema })
+};
+
+/** Annule un acquittement ou une résolution : retire l'autorisation et rouvre le constat. */
+export const sentinelReopen = {
+    command: 'sentinel.reopen' as const,
+    input: z.object({ findingId }),
+    output: z.object({ finding: findingSchema })
+};
+
+/** Les décisions humaines en vigueur dans l'espace. */
+export const sentinelAllowlist = {
+    command: 'sentinel.allowlist' as const,
+    input: z.object({ deviceId: deviceId.nullable().default(null) }),
+    output: z.object({ entries: z.array(allowEntrySchema).max(1000) })
+};
+
+/** Retire une autorisation. Le constat correspondant pourra rouvrir. */
+export const sentinelRemoveAllow = {
+    command: 'sentinel.removeAllow' as const,
+    input: z.object({ allowId: z.number().int().positive() }),
+    output: z.object({ removed: z.boolean() })
+};
+
+/**
+ * Active Sentinelle sur une machine et règle ses cadences.
+ *
+ * Activer (re)part une fenêtre d'apprentissage de `learningDays` : sans elle, le
+ * premier jour produirait des centaines de constats « nouveau programme » et la
+ * liste deviendrait illisible avant d'avoir servi.
+ */
+export const sentinelSetConfig = {
+    command: 'sentinel.setConfig' as const,
+    input: z.object({
+        deviceId,
+        enabled: z.boolean(),
+        learningDays: z
+            .number()
+            .int()
+            .min(SENTINEL_LEARNING_DAYS_MIN)
+            .max(SENTINEL_LEARNING_DAYS_MAX)
+            .nullable()
+            .default(null),
+        integrityMinutes: z
+            .number()
+            .int()
+            .min(SENTINEL_INTEGRITY_MINUTES_MIN)
+            .max(SENTINEL_INTEGRITY_MINUTES_MAX)
+            .nullable()
+            .default(null),
+        authEvents: z.boolean().nullable().default(null)
+    }),
+    output: z.object({ device: deviceSentinelStateSchema })
+};
+
+/** Demande un relevé de persistance + authentification immédiat. */
+export const sentinelScanNow = {
+    command: 'sentinel.scanNow' as const,
+    input: z.object({ deviceId }),
+    /** `requested` est faux quand l'agent n'est pas connecté. */
+    output: z.object({ deviceId, requested: z.boolean() })
+};
+
+/**
+ * Efface la ligne de base d'une machine et relance l'apprentissage.
+ *
+ * Le geste à faire après une montée de version d'agent qui change ce qui est
+ * observé — typiquement l'arrivée des chemins d'exécutables, qui redéfinit la
+ * clé d'un programme. **Les autorisations survivent** : ce sont des décisions,
+ * pas des observations, et les réclamer une seconde fois serait une punition
+ * pour avoir mis l'agent à jour.
+ */
+export const sentinelResetBaseline = {
+    command: 'sentinel.resetBaseline' as const,
+    input: z.object({ deviceId }),
+    output: z.object({ deviceId, cleared: z.number().int().nonnegative() })
+};
+
+export const sentinelCommands = [
+    sentinelOverview,
+    sentinelCount,
+    sentinelFindings,
+    sentinelBaseline,
+    sentinelPosture,
+    sentinelAcknowledge,
+    sentinelResolve,
+    sentinelReopen,
+    sentinelAllowlist,
+    sentinelRemoveAllow,
+    sentinelSetConfig,
+    sentinelScanNow,
+    sentinelResetBaseline
+] as const;

package/src/features/sharing.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+
+import {
+    itemAccessSchema,
+    itemGrantStateSchema,
+    itemRefSchema,
+    itemShareStateSchema
+} from '../domain/sharing';
+
+/**
+ * Le partage d'un élément et ses restrictions par rôle.
+ *
+ * Un module transversal plutôt qu'un jeu de commandes par fonctionnalité : ce
+ * que ces commandes prennent est toujours le même couple `(feature, itemId)`, et
+ * les recopier par émetteur aurait reproduit exactement ce que l'unification des
+ * notifications vient de défaire.
+ *
+ * L'autorisation ne peut pas être déclarative — la fonctionnalité visée est une
+ * **donnée d'entrée**. Elle est vérifiée en tête de handler, comme pour
+ * `notify.route*` et `device.setConfig`.
+ */
+
+/** Où cet élément est visible, et pourquoi il ne pourrait pas l'être. */
+export const shareGet = {
+    command: 'share.get' as const,
+    input: itemRefSchema,
+    output: itemShareStateSchema
+};
+
+/**
+ * Projette (ou retire) l'élément dans un espace.
+ *
+ * Un seul espace par appel : la case de l'écran est la commande, ce qui rend
+ * l'échec lisible — cocher une case qui échoue ne laisse pas les autres dans un
+ * état incertain.
+ */
+export const shareSet = {
+    command: 'share.set' as const,
+    input: itemRefSchema.extend({
+        workspaceId: z.number().int().positive(),
+        shared: z.boolean()
+    }),
+    output: itemShareStateSchema
+};
+
+/**
+ * Ce que chaque rôle d'un espace voit de cet élément — l'hérité et l'exception.
+ *
+ * `workspaceId` absent = l'espace actif. Renseigné, il vise n'importe quel
+ * espace où l'élément est visible : c'est ce qui permet de régler, depuis
+ * l'onglet Partage du domicile, ce que chaque fenêtre montre — sans changer
+ * d'espace. L'appelant doit être membre de l'espace visé ; y **écrire** exige
+ * d'y tenir `workspace.roles`.
+ */
+export const itemGrantList = {
+    command: 'share.grantList' as const,
+    input: itemRefSchema.extend({ workspaceId: z.number().int().positive().optional() }),
+    output: itemGrantStateSchema
+};
+
+/**
+ * Abaisse (ou rétablit) ce qu'un rôle peut faire sur cet élément, dans l'espace
+ * visé (`workspaceId` absent = l'actif).
+ *
+ * `access: null` **retire** la restriction : le rôle reprend ce que la
+ * fonctionnalité lui donne. C'est l'absence de ligne qui exprime « rien de
+ * particulier », pas une valeur.
+ */
+export const itemGrantSet = {
+    command: 'share.grantSet' as const,
+    input: itemRefSchema.extend({
+        workspaceId: z.number().int().positive().optional(),
+        roleId: z.number().int().positive(),
+        access: itemAccessSchema.nullable()
+    }),
+    output: itemGrantStateSchema
+};
+
+export const sharingCommands = [shareGet, shareSet, itemGrantList, itemGrantSet] as const;

package/src/features/twoFactor.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { twoFactorSetupSchema, twoFactorStatusSchema } from '../domain/twoFactor';
+
+export const twoFactorGetStatus = {
+    command: 'twofa.status' as const,
+    input: z.object({}),
+    output: z.object({ status: twoFactorStatusSchema })
+};
+
+/** Begin enrollment: returns a fresh secret, otpauth URL and backup codes. */
+export const twoFactorSetup = {
+    command: 'twofa.setup' as const,
+    input: z.object({}),
+    output: z.object({ setup: twoFactorSetupSchema })
+};
+
+/** Confirm enrollment by verifying the first TOTP code. */
+export const twoFactorEnable = {
+    command: 'twofa.enable' as const,
+    input: z.object({ code: z.string().min(6).max(8) }),
+    output: z.object({ status: twoFactorStatusSchema })
+};
+
+/** Disable 2FA (requires a valid current code or backup code). */
+export const twoFactorDisable = {
+    command: 'twofa.disable' as const,
+    input: z.object({ code: z.string().min(6).max(16) }),
+    output: z.object({ status: twoFactorStatusSchema })
+};
+
+/**
+ * Regenerate recovery codes (invalidates previous ones). Authenticated by the
+ * live session — no fresh TOTP code is required, only that 2FA be enabled.
+ */
+export const twoFactorRegenBackup = {
+    command: 'twofa.regenBackup' as const,
+    input: z.object({}),
+    output: z.object({ backupCodes: z.array(z.string().min(1)) })
+};
+
+export const twoFactorCommands = [
+    twoFactorGetStatus,
+    twoFactorSetup,
+    twoFactorEnable,
+    twoFactorDisable,
+    twoFactorRegenBackup
+] as const;