@deveye/types 0.15.2 → 0.16.0

package/src/sdk/server.ts

@@ -2,6 +2,11 @@ import type { z, ZodType } from 'zod';
 import type { ErrorCode } from '../protocol/error';
 import type { FeatureAccess } from '../domain/workspaceRole';
 import type { LogLevelName } from '../domain/logs';
+import type { ItemAccess } from '../domain/sharing';
+import type { AuthWindow, DeviceReport, IntegrityReport, ReportProcess } from '../domain/report';
+import type { AgentManifest } from '../http/device';
+import type { MetricSnapshot } from '../domain/metrics';
+import type { UserColor } from '../domain/user';
 import type {
     AgentSyncAckPayload,
     AgentSyncApplyChunkPayload,
@@ -17,6 +22,8 @@ import type {
     AgentSyncOpResultPayload,
     AgentSyncPushPayload,
     AgentSyncScanPayload,
+    AgentFilesMutatePayload,
+    AgentFilesUploadPayload,
     CloudSyncChunkPush,
     CloudSyncProgressPush,
     CloudSyncStatePush
@@ -133,6 +140,54 @@ export interface SdkQueryable {
     execute(sql: string, params?: unknown[]): Promise<{ affectedRows: number; insertId: number }>;
 }
 
+/**
+ * An alert as the notify facade delivers it. `subject` and `body` are what every
+ * channel receives (mail, Slack, a custom webhook); `payload` adds structured
+ * fields for a custom endpoint; `embeds` is the optional Discord layout, used
+ * only on a Discord channel, where it replaces the plain text (see the app's
+ * `Services/notifications.ts`). Keep the text complete on its own: a channel
+ * that knows no embeds must lose nothing.
+ */
+export interface SdkAlert {
+    subject: string;
+    body: string;
+    payload?: Record<string, unknown>;
+    /** Discord embed objects, as the Discord webhook API takes them. */
+    embeds?: readonly Record<string, unknown>[];
+}
+
+/** A routed channel that can carry a live message (see `notify.liveChannels`). */
+export interface SdkLiveChannel {
+    id: number;
+}
+
+/** A rich message for a live channel: what the Discord webhook API takes. */
+export interface SdkRichMessage {
+    content?: string;
+    embeds?: readonly Record<string, unknown>[];
+}
+
+/**
+ * One process-list instant next to its metric row: what a security engine
+ * needs to judge a device at a given timestamp. Capability `'telemetry.read'`.
+ */
+export interface SdkTelemetrySnapshot {
+    ts: number;
+    processes: ReportProcess[];
+    activeConnections: number | null;
+}
+
+/**
+ * Read access to the devices' telemetry (capability `'telemetry.read'`,
+ * reserved to native-id modules: the metric store is app infrastructure).
+ */
+export interface SdkTelemetry {
+    /** The instant nearest `ts` (process list plus the metric row), or null when nothing was recorded around it. */
+    snapshot(deviceId: string, ts: number): Promise<SdkTelemetrySnapshot | null>;
+    /** Pins the instant at `ts` so retention never prunes the evidence a finding rests on. */
+    pinInstant(deviceId: string, ts: number): Promise<void>;
+}
+
 /**
  * Native features, reachable only if declared in `manifest.nativeCapabilities`.
  * An undeclared call throws `forbidden`.
@@ -142,11 +197,33 @@ export interface DevEyeFacade {
     notify: {
         /** Is at least one usable channel routed to this target? */
         hasRoute(itemId?: number): Promise<boolean>;
-        /** Delivers to the configured channels. Resolves `true` if at least one accepted. */
+        /**
+         * Delivers to the configured channels. Resolves `true` if at least one
+         * accepted. `except`: channel ids to skip, those a live message
+         * (`postLive`) already concluded on, so a channel never hears the
+         * same news twice.
+         */
         send(
-            alert: { subject: string; body: string; payload?: Record<string, unknown> },
-            opts?: { itemId?: number }
+            alert: SdkAlert,
+            opts?: { itemId?: number; except?: readonly number[] }
         ): Promise<boolean>;
+        /**
+         * The routed channels able to carry a LIVE message: a rich message
+         * posted once and edited until it concludes (Discord webhooks today).
+         * Empty when none is routed to this target. Same routing as `send`.
+         */
+        liveChannels(opts?: { itemId?: number }): Promise<readonly SdkLiveChannel[]>;
+        /**
+         * Posts a rich message on one live channel of YOUR feature, or edits
+         * it when `messageId` is given. Resolves the message id to keep for
+         * the next edit, `null` when the channel refused (a message deleted
+         * by hand, a revoked webhook): stop there, never repost.
+         */
+        postLive(
+            channelId: number,
+            message: SdkRichMessage,
+            messageId?: string | null
+        ): Promise<string | null>;
     };
     /** Requires capability `'mail.accounts'`. Open-tier accounts, metadata only, never credentials. */
     mail: {
@@ -154,30 +231,98 @@ export interface DevEyeFacade {
             ReadonlyArray<{ id: number; label: string; address: string | null }>
         >;
     };
+    /**
+     * Requires capability `'workspaces.read'` AND a global administrator as
+     * caller (`forbidden` otherwise): every workspace of this DevEye.
+     */
+    workspaces: {
+        list(): Promise<readonly SdkWorkspaceSummary[]>;
+    };
     /** Requires capability `'members.read'`. */
     members: {
-        list(): Promise<ReadonlyArray<{ userId: number; name: string; isOwner: boolean }>>;
+        /**
+         * The workspace's members, owner included. `color` is the account's
+         * colour, the one its live presence wears everywhere; null for an
+         * account never coloured (fall back to `defaultUserColor(userId)`,
+         * exactly like the app does).
+         */
+        list(): Promise<
+            ReadonlyArray<{
+                userId: number;
+                name: string;
+                isOwner: boolean;
+                color: UserColor | null;
+            }>
+        >;
     };
     /** Requires capability `'devices.read'`. */
     devices: {
-        /** Throws `not_found` unless the device exists AND belongs to this workspace. */
+        /**
+         * Throws `not_found` unless the device exists AND belongs to this
+         * workspace (a global administrator passes the membership check).
+         */
         authorize(deviceId: string): Promise<SdkDevice>;
+        /**
+         * The devices this workspace sees: its own, or the whole fleet for a
+         * global administrator in their PERSONAL workspace (the app's own rule
+         * for its device list: that is where an admin watches their machines).
+         */
         list(): Promise<readonly SdkDevice[]>;
         isOnline(deviceId: string): boolean;
     };
+    /** Requires capability `'telemetry.read'` (native-id modules only). */
+    telemetry: SdkTelemetry;
     /** Requires capability `'agents'`. Same object as the service deps' `agents`. */
     agents: AgentsFacade;
 }
 
+/** A workspace as the fleet sees it: enough to attach a device to it. */
+export interface SdkWorkspaceSummary {
+    id: number;
+    name: string;
+    kind: 'personal' | 'shared';
+    ownerUserId: number;
+}
+
 /**
  * The agent-fleet sync transport (capability `'agents'`, native-id modules
- * only). Method names and semantics mirror the app's MonitorHub exactly, so a
- * repatriated engine swaps its hub handle for this facade and changes nothing
- * else. Outbound calls return `false` when the agent is offline (frame
- * dropped, never queued).
+ * only). Method names mirror the app's MonitorHub. Outbound calls return
+ * `false` when the agent is offline (frame dropped, never queued).
  */
 export interface AgentsFacade {
     isOnline(deviceId: string): boolean;
+    /**
+     * The three orders a device's lifecycle gives the hub. `requestDestroy`
+     * asks the agent to uninstall itself (deletion path); `disconnectAgent`
+     * closes its socket now (a revoked or force-deleted device);
+     * `resetAgentSession` drops what the hub remembered of it (a device
+     * confirmed or reactivated starts clean). All three answer `false` when
+     * the agent is not connected, which is not an error.
+     */
+    requestDestroy(deviceId: string): boolean;
+    disconnectAgent(deviceId: string): boolean;
+    resetAgentSession(deviceId: string): boolean;
+    /**
+     * The manifest of the agent binaries the app serves (the build version and,
+     * per target, whether the binary is signed), or null while nothing is
+     * synced. What a fleet screen needs to flag an agent able to self-update
+     * (`agent.update`); the binaries and their distribution stay the app's.
+     */
+    servedManifest(): Promise<AgentManifest | null>;
+    /**
+     * Asks the agent for an immediate security scan (persistence manifest and
+     * authentication window). Distinct from the metric refresh on purpose: a
+     * scan fingerprints hundreds of files.
+     */
+    requestScan(deviceId: string): boolean;
+    /**
+     * Pushes the device's collection config to its agent, recomposed by the
+     * app from the device row and the installed modules' contributions (see
+     * `SENTINEL_AGENT_CONFIG_PROVIDER`). Call it after changing what your
+     * module contributes to that config. Resolves `false` when the agent is
+     * offline (it receives the config at its next connection anyway).
+     */
+    pushConfig(deviceId: string): Promise<boolean>;
     requestSyncConfig(deviceId: string, payload: AgentSyncConfigPayload): boolean;
     requestSyncScan(deviceId: string, payload: AgentSyncScanPayload): boolean;
     requestSyncPush(deviceId: string, payload: AgentSyncPushPayload): boolean;
@@ -190,6 +335,27 @@ export interface AgentsFacade {
     /** Fan-out to the browsers subscribed to the payload's share. */
     publishSyncProgress(payload: CloudSyncProgressPush): void;
     publishSyncState(payload: CloudSyncStatePush): void;
+    /**
+     * File orders on a device, the ones the file explorer already speaks
+     * (`files.mutate`: mkdir, rename, delete; `files.upload`: a chunk at an
+     * offset, `done` on the last one). What makes an enrolled machine a
+     * backup target without changing the agent. The agent answers ONE
+     * `files.op` frame per `opId`: arm `awaitFilesOp` before sending, and
+     * for an upload before the FIRST chunk (the answer comes with the last
+     * one, or with the first write failure).
+     */
+    requestFilesMutate(deviceId: string, payload: AgentFilesMutatePayload): boolean;
+    requestFilesUpload(deviceId: string, payload: AgentFilesUploadPayload): boolean;
+    awaitFilesOp(opId: string, timeoutMs: number): Promise<{ ok: boolean; error?: string }>;
+    /** Forgets a pending `awaitFilesOp` (the frame was never sent, or the caller gave up). */
+    cancelFilesOp(opId: string): void;
+    /**
+     * Bytes queued on the agent's socket, not yet on the wire. A sender that
+     * streams towards an agent must watch it: the socket accepts everything,
+     * and without backpressure the server's memory follows the size of what
+     * is sent.
+     */
+    buffered(deviceId: string): number;
 }
 
 /**
@@ -206,14 +372,23 @@ export interface SdkSocketTransport {
 }
 
 /**
- * Inbound agent events, dispatched by the app's agent socket layer to the
- * modules that declare `'agents'`. Every hook is optional; an absent hook is a
- * no-op. Hooks may fire before your service's `start()` has completed: drop
- * quietly in that case, the agent will resend or reconcile.
+ * Inbound agent events, dispatched to the modules that declare `'agents'`.
+ * Every hook is optional. Hooks may fire before your service's `start()` has
+ * completed: drop quietly, the agent will resend or reconcile. Telemetry hooks
+ * fire once the app has persisted it, and only for ACTIVE devices; whether the
+ * device is watched by YOUR feature is your decision.
  */
 export interface FeatureAgentHooks {
     onAgentConnect?(deviceId: string): void | Promise<void>;
     onAgentOffline?(deviceId: string): void;
+    /** The OS/security report (`agent.report`), just written to the device row. */
+    onReport?(deviceId: string, report: DeviceReport): void | Promise<void>;
+    /** A batch of metric instants, oldest first, just written to the metric store. */
+    onMetricsBatch?(deviceId: string, snapshots: readonly MetricSnapshot[]): void | Promise<void>;
+    /** The persistence manifest (`agent.integrity`). Never stored by the app: it only exists here. */
+    onIntegrity?(deviceId: string, integrity: IntegrityReport): void | Promise<void>;
+    /** An authentication window (`agent.authEvents`). Never stored by the app either. */
+    onAuthEvents?(deviceId: string, auth: AuthWindow): void | Promise<void>;
     /** `deviceId` est l'identite AUTHENTIFIEE du socket ; le payload en porte une copie non fiable. */
     onSyncChanged?(deviceId: string, payload: AgentSyncChangedPayload): void;
     onSyncIndex?(deviceId: string, payload: AgentSyncIndexPayload): void;
@@ -222,6 +397,17 @@ export interface FeatureAgentHooks {
     onSyncOpResult?(deviceId: string, payload: AgentSyncOpResultPayload): void;
 }
 
+/**
+ * The named contracts the host holds (`sdk/providers.ts`): what the installed
+ * modules offer on their services. Looked up at call time, `undefined` when
+ * nobody offers the key; the caller degrades cleanly. A reader cannot tell who
+ * offers a key, on purpose: a contract can change hands without anything
+ * changing here.
+ */
+export interface SdkProviders {
+    get<T>(key: string): T | undefined;
+}
+
 /**
  * Raw bytes under the SERVER key (the `Encryption.encryptWithKey` wire format,
  * byte-compatible with what native code wrote). For wrapping module-owned key
@@ -231,6 +417,14 @@ export interface SdkServerKeys {
     sealBytes(plain: Uint8Array): string;
     /** null when the sealed blob cannot be opened (tampered, or server keys changed). */
     openBytes(sealed: string): Uint8Array | null;
+    /**
+     * A key DERIVED from the server key (HKDF-SHA256 over the same material
+     * as `sealBytes`), never stored anywhere. For material that must survive
+     * the database: a key kept in a table would sit inside the very backup it
+     * protects. The same (salt, info) always yields the same key, as long as
+     * `CRYPT_KEY_A`/`CRYPT_KEY_B` do not change.
+     */
+    derive(salt: string, info: string, length: number): Uint8Array;
 }
 
 /** A workspace device, as the devices facade reveals it. */
@@ -238,6 +432,113 @@ export interface SdkDevice {
     id: string;
     name: string;
     online: boolean;
+    /** `active` is the only status whose telemetry the app records. */
+    status: string;
+    /** The account that enrolled the device (the actor of its audit lines). */
+    ownerUserId: number;
+    /** The workspace the device was paired in, or null once that workspace is gone. */
+    workspaceId: number | null;
+    /** The agent's metric cadence in seconds, null when it follows the default. */
+    metricIntervalSeconds: number | null;
+    /** The last OS/security report, null before the first one (or unreadable). */
+    report: DeviceReport | null;
+}
+
+/** The session's password-encryption lock, seen from a handler. */
+export interface SdkSecrecy {
+    /**
+     * True when the guarded tier is readable in this session: password-based
+     * encryption is off for the account, or the session was unlocked. A
+     * `'private'` read throws `locked` on its own; ask here when you need to
+     * decide BEFORE reading (list rows as masked, refuse an edit that would
+     * overwrite a body the session cannot see).
+     */
+    isUnlocked(): Promise<boolean>;
+    /**
+     * A short-lived ticket, signed by the host and bound to the caller (their
+     * session, this workspace, YOUR module), carrying `payload`. Hand it to
+     * the browser (a download URL, an OAuth `state`); a public route of your
+     * service redeems it (`deps.secrecy.redeem`) into the caller's ciphers,
+     * private tier included while the session is unlocked. The module never
+     * sees a session id nor a key. Default life: two minutes.
+     */
+    ticket(payload: unknown, opts?: { ttlSeconds?: number }): Promise<string>;
+}
+
+/**
+ * Your feature's items, as the workspace's roles see them. Items are the rows
+ * a module declares with `hasItems`; both members answer for THIS feature.
+ */
+export interface SdkItems {
+    /**
+     * The items the caller's role sees differently from the others: `'none'`
+     * hidden, `'read'` read-only. Restrictive only: it can lower what the
+     * feature grants, never raise it. Empty for the owner and for a member
+     * without a role. Listings filter with it.
+     */
+    restrictions(): Promise<ReadonlyMap<number, ItemAccess>>;
+    /**
+     * Throws `forbidden` unless THIS item is open to the caller at `level`
+     * (default `'read'`), role restriction included. Commands that target one
+     * item call it first.
+     */
+    assert(itemId: number, level?: FeatureAccess): Promise<void>;
+    /**
+     * The item no longer exists: drops its projections, its role restrictions
+     * and its notification route. Call it from your delete handler; nothing
+     * links those rows to your table (the item lives in a different table per
+     * feature), so without this call the next item to inherit the id would
+     * inherit them too.
+     */
+    forget(itemId: number): Promise<void>;
+}
+
+/**
+ * What is projected INTO the active workspace, for one listing or read.
+ *
+ * A shared item keeps a single home: it stays encrypted under its home
+ * workspace's key, and is read elsewhere with that workspace's OPEN cipher.
+ * `cipherFor` is the only path to it, and it only answers for items whose
+ * projection really exists: an invented id yields the active workspace's own
+ * cipher, never a foreign one.
+ */
+export interface SdkShareScope {
+    /** The ids of the items projected into the active workspace from elsewhere. */
+    readonly foreignIds: ReadonlySet<number>;
+    /** The home workspace of a projected item, or null when it is at home. */
+    homeOf(itemId: number): number | null;
+    /** The open cipher of the workspace the item lives in (the active one when it is at home). */
+    cipherFor(itemId: number): Promise<SdkCipher>;
+}
+
+/** Cross-workspace projection of your items (manifest `shareTier` other than `'never'`). */
+export interface SdkSharing {
+    /**
+     * Loads what is projected into the active workspace. Once per listing or
+     * read command; the result does not outlive the command.
+     */
+    scope(): Promise<SdkShareScope>;
+}
+
+/** Live invalidation from a background service, which writes without a command. */
+export interface SdkLive {
+    /**
+     * Something of YOUR feature changed in this workspace: every member's
+     * client re-fetches your declared resources (and, for a share-wired
+     * feature, so do the workspaces linked by projections). Call it on state
+     * transitions, never on every tick: each call re-fetches for everyone.
+     * `topics` beats those instead of your id: your own secondary topics
+     * (`manifest.topics`), or another feature's topic whose screens mirror
+     * this data.
+     */
+    changed(workspaceId: number, topics?: readonly string[]): void;
+}
+
+/** The whole fleet, sessionless (capability `'devices.read'`), for services. */
+export interface SdkFleetDevices {
+    /** One device by id, whatever its workspace, or null. */
+    find(deviceId: string): Promise<SdkDevice | null>;
+    isOnline(deviceId: string): boolean;
 }
 
 /** What a handler receives. One request, one workspace, rights pre-resolved. */
@@ -246,6 +547,12 @@ export interface SdkFeatureContext<Repo = unknown> {
     workspaceId: number;
     workspace: { id: number; kind: 'personal' | 'shared'; name: string };
     isOwner: boolean;
+    /**
+     * The caller is a global administrator of this DevEye. What a fleet-wide
+     * view keys on (the admin in their personal workspace sees every device);
+     * a command that must REQUIRE it declares `access: { admin: true }`.
+     */
+    isAdmin: boolean;
     /** Caller's level on THIS feature. `read` is already guaranteed by the dispatcher. */
     canWrite: boolean;
     /** Extra permission of type `toggle`. Absent from the grant = false; owner = true. */
@@ -262,6 +569,14 @@ export interface SdkFeatureContext<Repo = unknown> {
     deveye: DevEyeFacade;
     /** The caller's socket (capability `'agents'`); every method throws `forbidden` otherwise. */
     transport: SdkSocketTransport;
+    /** The session's password-encryption lock. */
+    secrecy: SdkSecrecy;
+    /** Your items as the roles see them (restrictions), and their removal bookkeeping. */
+    items: SdkItems;
+    /** Projections into the active workspace. Throws `forbidden` when the manifest says `shareTier: 'never'`. */
+    sharing: SdkSharing;
+    /** The named contracts the host holds, see `SdkProviders`. */
+    providers: SdkProviders;
     /** Fire-and-forget audit line; actor, IP and workspace are pre-bound. */
     audit(entry: {
         action: string;
@@ -271,6 +586,16 @@ export interface SdkFeatureContext<Repo = unknown> {
     }): void;
     logger: SdkLogger;
     requestId: string;
+    /** The server key derivations, the same `keys` a service gets. */
+    keys: SdkServerKeys;
+    /**
+     * Where DevEye lives, as URLs without a trailing slash: `app` is the
+     * origin members use (`PUBLIC_ORIGIN`), `public` the one reachable
+     * without the VPN when the host has a public surface (else the same).
+     * For what a module hands to the outside world (an install snippet, a
+     * callback URL): never derive it from the browser's location.
+     */
+    origins: { app: string; public: string };
 }
 
 /**
@@ -289,12 +614,21 @@ export interface SdkFeatureDefinition<
     input: I;
     output: O;
     /**
-     * `level` defaults to `'read'`; `extras` are ALL required. Your feature id
-     * is implied: you cannot gate on another feature's rights.
+     * `level`: the caller's level on your feature (`read` by default).
+     * `extras`: the extra permissions the caller must hold, ALL required.
+     * `admin`: the caller must be a global administrator; the feature check
+     * still applies. Your feature id is implied: you cannot gate on another
+     * feature's rights.
+     */
+    access?: { level?: FeatureAccess; extras?: readonly string[]; admin?: boolean };
+    /**
+     * This command changes data other members can see. `true` beats your
+     * feature's own live topic (its id); a list names the topics to beat
+     * instead: your id, one of your `manifest.topics`, or another feature's
+     * topic (native or module) whose screens mirror this data (Projects when a
+     * linked item goes away). An unknown topic is refused at boot.
      */
-    access?: { level?: FeatureAccess; extras?: readonly string[] };
-    /** This command changes data other members can see. */
-    mutates?: boolean;
+    mutates?: boolean | readonly string[];
     handler(ctx: SdkFeatureContext<Repo>, input: z.output<I>): Promise<z.input<O>>;
 }
 
@@ -305,6 +639,61 @@ export function defineSdkFeature<Repo, Cmd extends string, I extends ZodType, O
     return def;
 }
 
+/** The request a public route sees: headers, decoded body, client address. Nothing of a session. */
+export interface SdkPublicRequest {
+    headers: Readonly<Record<string, string | string[] | undefined>>;
+    /** The JSON body, already decoded (`undefined` when absent or unreadable). */
+    body: unknown;
+    /**
+     * The query string, decoded by the host into an object (`?a=1&b=2` reads
+     * `{ a: '1', b: '2' }`). `unknown` like `body`: read it through a schema.
+     * What a ticketed GET (a download URL, an OAuth callback) carries.
+     */
+    query?: unknown;
+    ip: string;
+}
+
+/** The reply of a public route, the minimal chainable surface the host maps onto its HTTP server. */
+export interface SdkPublicReply {
+    header(name: string, value: string): SdkPublicReply;
+    code(status: number): SdkPublicReply;
+    send(payload?: unknown): unknown;
+}
+
+export interface SdkPublicRouteOptions {
+    /** A ceiling per client address, on top of the host's own: `{ max, timeWindow: '1 minute' }`. */
+    rateLimit?: { max: number; timeWindow: string };
+    /**
+     * Which listeners serve the route. `'everywhere'` (default): the app and
+     * the public surface, for what the outside world calls (a beacon).
+     * `'app'`: the app's own origin only, for what the logged-in browser
+     * fetches without a session header (a ticketed download, an OAuth
+     * callback that lands back in the app).
+     */
+    exposure?: 'everywhere' | 'app';
+}
+
+/** What a redeemed ticket gives a public route back (see `SdkSecrecy.ticket`). */
+export interface SdkRedeemedTicket {
+    userId: number;
+    workspaceId: number;
+    payload: unknown;
+    /** The caller's ciphers: the open tier always, the private tier while their session is unlocked. */
+    cipher: { server: SdkCipher; private: SdkCipher | null };
+}
+
+export type SdkPublicHandler = (req: SdkPublicRequest, reply: SdkPublicReply) => Promise<unknown>;
+
+/**
+ * Where a module declares its public routes (capability `'routes.public'`).
+ * Paths are absolute (`/t.js`, `/api/t/b`); a path the host already serves
+ * is refused at boot. Every route is registered on every public listener.
+ */
+export interface SdkPublicApp {
+    get(path: string, opts: SdkPublicRouteOptions, handler: SdkPublicHandler): void;
+    post(path: string, opts: SdkPublicRouteOptions, handler: SdkPublicHandler): void;
+}
+
 /**
  * A background worker. Started during boot (awaited, before the agent socket
  * layer registers), stopped on shutdown.
@@ -320,6 +709,12 @@ export interface FeatureService {
      * provider up at call time and degrades cleanly when the module is absent.
      */
     providers?: Readonly<Record<string, unknown>>;
+    /**
+     * Your public HTTP routes, declared once at boot (capability
+     * `'routes.public'`). Called by the host for each listener it exposes to
+     * the outside; register the same routes each time.
+     */
+    publicRoutes?(app: SdkPublicApp): void;
 }
 
 /**
@@ -337,6 +732,12 @@ export interface FeatureServiceDeps<Repo = unknown> {
     deveyeFor(workspaceId: number): Pick<DevEyeFacade, 'notify'>;
     /** Devices of one workspace, sessionless (capability `'devices.read'`). */
     devicesFor(workspaceId: number): Pick<DevEyeFacade['devices'], 'list' | 'isOnline'>;
+    /** The whole fleet by id, sessionless (capability `'devices.read'`). */
+    devices: SdkFleetDevices;
+    /** The devices' telemetry, sessionless (capability `'telemetry.read'`). */
+    telemetry: SdkTelemetry;
+    /** Live invalidation of your feature's resources, from a service. */
+    live: SdkLive;
     /**
      * Audit line recorded as the SYSTEM (no session). `userId` attributes the
      * line to a user when the work concerns their data.
@@ -350,8 +751,14 @@ export interface FeatureServiceDeps<Repo = unknown> {
     }): void;
     /** The agent-fleet transport (capability `'agents'`). */
     agents: AgentsFacade;
-    /** Raw key wrapping under the server key. */
+    /** Raw key wrapping under the server key, and derived keys. */
     keys: SdkServerKeys;
+    /** Redeems a ticket minted by `ctx.secrecy.ticket` of THIS module; `null` when invalid, expired or another module's. */
+    secrecy: { redeem(ticket: string): Promise<SdkRedeemedTicket | null> };
+    /** Where DevEye lives (the same `origins` a request context gets): for a page or a link a route hands to the browser. */
+    origins: { app: string; public: string };
+    /** The named contracts the host holds, see `SdkProviders`. */
+    providers: SdkProviders;
     /**
      * The app's standard loop: setInterval + reentrancy guard + unref, the
      * exact pattern of every native service. Use it instead of rolling your own.
@@ -375,4 +782,61 @@ export interface FeatureServer<Repo = unknown> {
      */
     migrationsDir?: string;
     createService?(deps: FeatureServiceDeps<Repo>): FeatureService;
+    /**
+     * What the app needs to know about your items without opening your
+     * feature: required for a `shareTier` other than `'never'` (the sharing
+     * commands must find an item's home), useful to any `hasItems` feature that
+     * notifies (the channels screen names the item a route points to).
+     */
+    items?: FeatureItemsEntry<Repo>;
+}
+
+/**
+ * Your items, seen from the app's transversal commands (sharing, notification
+ * routes). Both calls are sessionless as far as you are concerned: the repo is
+ * yours, the cipher is the OPEN cipher of the calling workspace.
+ */
+export interface FeatureItemsEntry<Repo = unknown> {
+    /**
+     * The workspace an item lives in, when it is visible from `workspaceId`
+     * (its own, or one it is projected into); null when it does not exist
+     * there. The sharing commands rely on it to tell a home from a window.
+     */
+    homeOf(repo: Repo, itemId: number, workspaceId: number): Promise<number | null>;
+    /**
+     * The item's display name, decrypted with `cipher` (the open cipher of
+     * `workspaceId`), or null when the item is gone or unreadable. Names the
+     * target a notification route points to; null reads as "a target that
+     * disappeared", which is exactly what the screen must show then.
+     */
+    labelOf(
+        repo: Repo,
+        cipher: SdkCipher,
+        itemId: number,
+        workspaceId: number
+    ): Promise<string | null>;
+    /**
+     * May this item be projected into another workspace? Omit when every item
+     * of yours can (an open-tier feature). A `'perItem'` feature answers
+     * `false` for an item encrypted under the caller's password (its guarded
+     * tier): no other workspace could read it, so the share is refused at the
+     * moment it is asked, with a message that says why. Called with the item's
+     * HOME workspace.
+     */
+    shareable?(repo: Repo, itemId: number, workspaceId: number): Promise<boolean>;
 }
+
+// Le conteneur chiffré que CloudSync et Backup partagent (voir `devb.ts`).
+export {
+    BLOB_CHUNK_BYTES,
+    BLOB_CHUNK_SEALED,
+    BLOB_HEADER_LEN,
+    BLOB_TAG_LEN,
+    BLOB_VERSION_CHUNKED,
+    BLOB_VERSION_STREAM,
+    createBlobHeader,
+    openChunk,
+    openStreamDecipher,
+    parseBlobHeader,
+    sealChunk
+} from './devb';

package/src/sdk/testing.test.ts

@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { z } from 'zod';
 
-import { createTestContext, createTestServiceDeps } from './testing';
+import { createTestContext, createTestServiceDeps, testDevice } from './testing';
 
 test('createTestContext follows the manifest for extras, and records what handlers do', async () => {
     const manifest = {
@@ -36,7 +36,7 @@ test('createTestContext follows the manifest for extras, and records what handle
 test('createTestServiceDeps: one store per workspace, hand-driven tickers, a wrapper that round-trips', async () => {
     const deps = createTestServiceDeps({
         workspaceIds: [1, 2],
-        devices: [{ id: 'd1', name: 'One', online: false }]
+        devices: [testDevice({ id: 'd1', name: 'One', online: false })]
     });
     assert.deepEqual(await deps.listWorkspaceIds(), [1, 2]);
     await deps.storeFor(1).put('a', '1');