@camstack/system 1.2.389 → 1.2.391

package/dist/builtins/storage-orchestrator/storage-pressure-manager.d.ts

@@ -1,115 +1,115 @@
-import { IScopedLogger, IStorageEvictableProvider } from '@camstack/types';
-import { DrainProgress, DrainState } from './drain-ratchet.js';
+import type { IScopedLogger, IStorageEvictableProvider } from "@camstack/types";
+import type { DrainProgress, DrainState } from "./drain-ratchet.js";
 /**
- * One draining location and the ACTIVE locations of its class the drain is
- * paced against (D386). Supplied by the orchestrator, which is the only thing
- * that knows a location's mode.
- */
+* One draining location and the ACTIVE locations of its class the drain is
+* paced against (D386). Supplied by the orchestrator, which is the only thing
+* that knows a location's mode.
+*/
 export interface DrainPlanEntry {
-    readonly locationId: string;
-    /** Locations of the SAME class whose growth the drain is matched to. Empty
-     *  means the pace is unmeasurable and the cap stands still. */
-    readonly activePeerLocationIds: readonly string[];
+	readonly locationId: string;
+	/** Locations of the SAME class whose growth the drain is matched to. Empty
+	*  means the pace is unmeasurable and the cap stands still. */
+	readonly activePeerLocationIds: readonly string[];
 }
 /**
- * Durable home for the ratchet state. It MUST survive a process restart: a cap
- * recomputed from today's usage starts again at the top and silently undoes
- * every byte of progress.
- */
+* Durable home for the ratchet state. It MUST survive a process restart: a cap
+* recomputed from today's usage starts again at the top and silently undoes
+* every byte of progress.
+*/
 export interface DrainStateStore {
-    load(): Promise<readonly DrainState[]>;
-    save(state: DrainState): Promise<void>;
-    clear(locationId: string): Promise<void>;
+	load(): Promise<readonly DrainState[]>;
+	save(state: DrainState): Promise<void>;
+	clear(locationId: string): Promise<void>;
 }
 /**
- * StoragePressureManager — core-owned TRIGGER for disk-space relief.
- *
- * Monitors free space per managed location and, when a location drops below its
- * `minFreePercent`, asks each registered `storage-evictable` provider to free a
- * proportional share of the byte deficit. The PROVIDER decides what to delete
- * and does the deletion — core never deletes data it doesn't understand. This
- * makes disk-pressure one cross-consumer concern instead of per-addon guards.
- *
- * Convergence: a bounded round loop re-reads free% after each fan-out and stops
- * when the location recovers, when nothing is evictable, or when a round makes
- * no progress (every provider exhausted). Lossless feedback (`reclaimedBytes`)
- * drives the stop condition; the addon re-runs `sweep()` on a timer so a partial
- * relief finishes on the next tick.
- */
+* StoragePressureManager — core-owned TRIGGER for disk-space relief.
+*
+* Monitors free space per managed location and, when a location drops below its
+* `minFreePercent`, asks each registered `storage-evictable` provider to free a
+* proportional share of the byte deficit. The PROVIDER decides what to delete
+* and does the deletion — core never deletes data it doesn't understand. This
+* makes disk-pressure one cross-consumer concern instead of per-addon guards.
+*
+* Convergence: a bounded round loop re-reads free% after each fan-out and stops
+* when the location recovers, when nothing is evictable, or when a round makes
+* no progress (every provider exhausted). Lossless feedback (`reclaimedBytes`)
+* drives the stop condition; the addon re-runs `sweep()` on a timer so a partial
+* relief finishes on the next tick.
+*/
 export interface PressureManagerDeps {
-    readonly logger: IScopedLogger;
-    /** Free capacity (%) on the location's volume. */
-    readonly getFreePercent: (locationId: string) => Promise<number>;
-    /** Total bytes on the location's volume (to turn a deficit % into a byte target). */
-    readonly getVolumeTotalBytes: (locationId: string) => Promise<number>;
-    /** Registered `storage-evictable` providers (cross-process proxies). */
-    readonly getEvictableProviders: () => readonly IStorageEvictableProvider[];
-    /** locationId → minFreePercent threshold; entries with `<= 0` have the guard off. */
-    readonly getLocationThresholds: () => Promise<ReadonlyMap<string, number>>;
-    /** locationId → hard cap on EVICTABLE bytes (`config.maxUsedGb`, operator's
-     *  "recordings may use at most N GB total"). Optional — absent = no caps. */
-    readonly getLocationMaxUsedBytes?: () => Promise<ReadonlyMap<string, number>>;
-    /** Max relief rounds per location per sweep (backstop, default 8). */
-    readonly maxRounds?: number;
-    /** Extra headroom % freed beyond the threshold to avoid re-breaching immediately (default 1). */
-    readonly hysteresisPercent?: number;
-    /**
-     * Optional: map a locationId to a stable key identifying its PHYSICAL storage
-     * device — the `realpath` of the location's `basePath`, so aliases (symlinks /
-     * bind-mounts) and same-root managed locations (`recordings:default` +
-     * `recordingsLow:default`, both at `/recordings`) share one key.
-     *
-     * Powers an in-sweep dedup: once a physical device has actually been RELIEVED
-     * this sweep, other locations resolving to the SAME device are skipped for the
-     * rest of the tick. This closes a bounded OVER-eviction window — after the
-     * first alias frees the shared disk, a second alias re-reading not-yet-settled
-     * `statfs` free% (lazy fs accounting, open fds) could see it still breached and
-     * evict the oldest footage a second time. A fresh sweep on the next timer tick
-     * re-checks the settled free% and finishes any genuinely-residual pressure, so
-     * skipping can only ever DEFER relief (self-correcting), never over-delete.
-     *
-     * Omitted, or returning `null`, → no dedup (each location relieved
-     * independently), preserving prior single-disk behaviour.
-     */
-    readonly getLocationDeviceKey?: (locationId: string) => Promise<string | null>;
-    /** Locations in `drain` mode, each with the active peers of its class.
-     *  Absent → no drain (the behaviour before D386). */
-    readonly getDrainPlan?: () => Promise<readonly DrainPlanEntry[]>;
-    /** Where the ratchet state lives across restarts. Absent → drain is inert:
-     *  without persistence the cap would reset on every boot, which is worse
-     *  than not draining. */
-    readonly drainState?: DrainStateStore;
+	readonly logger: IScopedLogger;
+	/** Free capacity (%) on the location's volume. */
+	readonly getFreePercent: (locationId: string) => Promise<number>;
+	/** Total bytes on the location's volume (to turn a deficit % into a byte target). */
+	readonly getVolumeTotalBytes: (locationId: string) => Promise<number>;
+	/** Registered `storage-evictable` providers (cross-process proxies). */
+	readonly getEvictableProviders: () => readonly IStorageEvictableProvider[];
+	/** locationId → minFreePercent threshold; entries with `<= 0` have the guard off. */
+	readonly getLocationThresholds: () => Promise<ReadonlyMap<string, number>>;
+	/** locationId → hard cap on EVICTABLE bytes (`config.maxUsedGb`, operator's
+	*  "recordings may use at most N GB total"). Optional — absent = no caps. */
+	readonly getLocationMaxUsedBytes?: () => Promise<ReadonlyMap<string, number>>;
+	/** Max relief rounds per location per sweep (backstop, default 8). */
+	readonly maxRounds?: number;
+	/** Extra headroom % freed beyond the threshold to avoid re-breaching immediately (default 1). */
+	readonly hysteresisPercent?: number;
+	/**
+	* Optional: map a locationId to a stable key identifying its PHYSICAL storage
+	* device — the `realpath` of the location's `basePath`, so aliases (symlinks /
+	* bind-mounts) and same-root managed locations (`recordings:default` +
+	* `recordingsLow:default`, both at `/recordings`) share one key.
+	*
+	* Powers an in-sweep dedup: once a physical device has actually been RELIEVED
+	* this sweep, other locations resolving to the SAME device are skipped for the
+	* rest of the tick. This closes a bounded OVER-eviction window — after the
+	* first alias frees the shared disk, a second alias re-reading not-yet-settled
+	* `statfs` free% (lazy fs accounting, open fds) could see it still breached and
+	* evict the oldest footage a second time. A fresh sweep on the next timer tick
+	* re-checks the settled free% and finishes any genuinely-residual pressure, so
+	* skipping can only ever DEFER relief (self-correcting), never over-delete.
+	*
+	* Omitted, or returning `null`, → no dedup (each location relieved
+	* independently), preserving prior single-disk behaviour.
+	*/
+	readonly getLocationDeviceKey?: (locationId: string) => Promise<string | null>;
+	/** Locations in `drain` mode, each with the active peers of its class.
+	*  Absent → no drain (the behaviour before D386). */
+	readonly getDrainPlan?: () => Promise<readonly DrainPlanEntry[]>;
+	/** Where the ratchet state lives across restarts. Absent → drain is inert:
+	*  without persistence the cap would reset on every boot, which is worse
+	*  than not draining. */
+	readonly drainState?: DrainStateStore;
 }
 export declare class StoragePressureManager {
-    private readonly deps;
-    /** Last sweep's drain progress, by location. Read-only surface for the UI. */
-    private drainProgress;
-    constructor(deps: PressureManagerDeps);
-    /** Relieve every managed location currently under its threshold. */
-    sweep(): Promise<void>;
-    /**
-     * The drain pass (D386). A `drain` location is excluded from nothing — it is
-     * given a monotonically descending effective usage cap and handed to the SAME
-     * `relieveToUsageCap` machinery every other cap uses. There is no second
-     * eviction path, and no operator-facing rate.
-     */
-    private sweepDrains;
-    /** Progress for every draining location, as of the last sweep. The read a UI
-     *  asks for — it never triggers work of its own. */
-    drainProgressSnapshot(): readonly DrainProgress[];
-    /** Evictable bytes on one location, summed across every provider. */
-    private evictableUsageOf;
-    /** Evictable bytes across a set of locations. */
-    private evictableUsageOfAll;
-    /** Evict oldest-first until the location's evictable usage fits `maxBytes`. */
-    private relieveToUsageCap;
-    /**
-     * Relieve one location until it recovers, nothing is evictable, or a round
-     * makes no progress. Returns `true` when at least one relief round actually
-     * reclaimed bytes (so the caller marks the location's physical device relieved
-     * for this sweep — the trigger for the over-eviction dedup: freed bytes mean a
-     * sibling alias may re-read a not-yet-settled `statfs`), `false` when nothing
-     * was freed (never breached, or breached with no evictable data).
-     */
-    private relieveLocation;
+	private readonly deps;
+	/** Last sweep's drain progress, by location. Read-only surface for the UI. */
+	private drainProgress;
+	constructor(deps: PressureManagerDeps);
+	/** Relieve every managed location currently under its threshold. */
+	sweep(): Promise<void>;
+	/**
+	* The drain pass (D386). A `drain` location is excluded from nothing — it is
+	* given a monotonically descending effective usage cap and handed to the SAME
+	* `relieveToUsageCap` machinery every other cap uses. There is no second
+	* eviction path, and no operator-facing rate.
+	*/
+	private sweepDrains;
+	/** Progress for every draining location, as of the last sweep. The read a UI
+	*  asks for — it never triggers work of its own. */
+	drainProgressSnapshot(): readonly DrainProgress[];
+	/** Evictable bytes on one location, summed across every provider. */
+	private evictableUsageOf;
+	/** Evictable bytes across a set of locations. */
+	private evictableUsageOfAll;
+	/** Evict oldest-first until the location's evictable usage fits `maxBytes`. */
+	private relieveToUsageCap;
+	/**
+	* Relieve one location until it recovers, nothing is evictable, or a round
+	* makes no progress. Returns `true` when at least one relief round actually
+	* reclaimed bytes (so the caller marks the location's physical device relieved
+	* for this sweep — the trigger for the over-eviction dedup: freed bytes mean a
+	* sibling alias may re-read a not-yet-settled `statfs`), `false` when nothing
+	* was freed (never breached, or breached with no evictable data).
+	*/
+	private relieveLocation;
 }

package/dist/builtins/system-backup/backup-encryption.d.ts

@@ -1,57 +1,94 @@
-import { KeyObject } from 'node:crypto';
-import { Transform } from 'node:stream';
+/**
+* Backup archive encryption — public key, streaming, chunked AEAD (D-backup
+* encryption, operator decision 2026-10-09).
+*
+* ## Why a public-key scheme
+*
+* Scheduled backups run with nobody present, so the hub must be able to
+* ENCRYPT on its own. With a symmetric key the hub would also hold what
+* DECRYPTS every archive it ever shipped — in its database, in the nightly
+* appdata tar, in any copy of the data volume — and the archives on SMB / S3
+* would be exactly as safe as the hub. Here the hub keeps only the PUBLIC key:
+* an attacker with the hub, its database or its volume backup still cannot
+* open an archive that already left. The operator keeps the secret key (shown
+* once at setup) and gives it back at restore time. It is independent of the
+* keychain master key, so a restore onto a fresh hub needs nothing from the
+* old one, and a keychain reset does not strand the backups.
+*
+* ## Format `x25519-hkdf-aes256gcm-stream-v1` (age's STREAM construction, AES-GCM)
+*
+*     header (69 bytes)
+*       magic "CSBKENC1" (8) | version 1 (1) | chunk size u32 BE (4)
+*       | recipient key id (8) | ephemeral X25519 public key (32) | salt (16)
+*     chunks
+*       AES-256-GCM(payloadKey, nonce, plaintext[≤ chunk]) ‖ tag(16)
+*
+* `payloadKey = HKDF-SHA256(X25519(ephemeral, recipient), salt,
+*  "camstack-backup-v1" ‖ header)` — the whole header is bound into the key,
+* so a changed byte in it fails the first chunk. The nonce is an 11-byte
+* big-endian chunk counter plus a final-chunk flag: a reordered, dropped or
+* appended chunk fails authentication, and an archive cut at a chunk boundary
+* is refused because its last chunk is not marked final. Every archive has a
+* final chunk (empty when the plaintext is a multiple of the chunk size).
+*
+* Memory is one chunk (64 KiB by default) per stream, whatever the archive
+* size. `scripts/ops/backup-decrypt.mjs` implements the same format with
+* nothing but Node, for a restore without a hub.
+*/
+import { type KeyObject } from "node:crypto";
+import { Transform } from "node:stream";
 export declare const BACKUP_ENCRYPTION_SCHEME = "x25519-hkdf-aes256gcm-stream-v1";
 export declare const ENCRYPTED_BACKUP_SUFFIX = ".csbk";
 export declare const BACKUP_ENCRYPTION_HEADER_BYTES: number;
 export declare const DEFAULT_BACKUP_CHUNK_BYTES: number;
 /** A key string that is not a backup key, or was mistyped. */
 export declare class BackupKeyFormatError extends Error {
-    constructor(message: string);
+	constructor(message: string);
 }
 /** The archive was encrypted to another backup key. */
 export declare class BackupKeyMismatchError extends Error {
-    readonly archiveKeyId: string;
-    readonly givenKeyId: string;
-    constructor(archiveKeyId: string, givenKeyId: string);
+	readonly archiveKeyId: string;
+	readonly givenKeyId: string;
+	constructor(archiveKeyId: string, givenKeyId: string);
 }
 /** The archive is damaged, truncated or tampered with. */
 export declare class BackupDecryptError extends Error {
-    constructor(message: string);
+	constructor(message: string);
 }
 export interface BackupKeyPair {
-    /** Shown ONCE to the operator; never stored on the hub. */
-    readonly secretKey: string;
-    /** What the hub keeps to encrypt. */
-    readonly publicKey: string;
-    /** 16 hex chars — names the key in the UI and in every archive header. */
-    readonly keyId: string;
+	/** Shown ONCE to the operator; never stored on the hub. */
+	readonly secretKey: string;
+	/** What the hub keeps to encrypt. */
+	readonly publicKey: string;
+	/** 16 hex chars — names the key in the UI and in every archive header. */
+	readonly keyId: string;
 }
 export declare function generateBackupKeyPair(): BackupKeyPair;
 export interface ParsedPublicKey {
-    readonly raw: Buffer;
-    readonly keyId: string;
+	readonly raw: Buffer;
+	readonly keyId: string;
 }
 export interface ParsedSecretKey {
-    readonly key: KeyObject;
-    readonly publicRaw: Buffer;
-    readonly keyId: string;
+	readonly key: KeyObject;
+	readonly publicRaw: Buffer;
+	readonly keyId: string;
 }
 export declare function parseBackupPublicKey(text: string): ParsedPublicKey;
 export declare function parseBackupSecretKey(text: string): ParsedSecretKey;
 /** Encrypt a byte stream to the holder of `publicKey`'s secret key. */
 export declare function createBackupEncryptStream(publicKey: string, opts?: {
-    readonly chunkBytes?: number;
+	readonly chunkBytes?: number;
 }): Transform;
 /** Decrypt a stream produced by {@link createBackupEncryptStream}. */
 export declare function createBackupDecryptStream(secretKey: string): Transform;
 /** The key id an encrypted archive names, or `null` for a plain (pre-encryption) archive. */
 export declare function readBackupEncryptionHeader(file: string): Promise<{
-    readonly keyId: string;
+	readonly keyId: string;
 } | null>;
 /** File → file. Used by tests and the offline path; the hub streams in its pipeline. */
 export declare function encryptBackupFile(input: string, output: string, publicKey: string): Promise<void>;
 /**
- * File → file. A failure of any kind removes the partial output: a restore
- * must never find half a tar where the archive should be.
- */
+* File → file. A failure of any kind removes the partial output: a restore
+* must never find half a tar where the archive should be.
+*/
 export declare function decryptBackupFile(input: string, output: string, secretKey: string): Promise<void>;