@camstack/addon-remote-storage 1.2.42 → 1.2.44

package/dist/smb.addon.mjs

@@ -0,0 +1,796 @@
+import { c as BaseAddon, i as rearmIdleAbort, o as scheduleIdleAbort, s as storageProviderCapability } from "./shared-DsnRUNmJ.mjs";
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import * as fsp from "node:fs/promises";
+import * as os from "node:os";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+//#region src/providers/smb/smb-config-schema.ts
+/**
+* SMB / CIFS `storage-provider` config schema — drives the "Add location"
+* wizard form in the admin UI.
+*
+* The shape follows the operator's own production Samba backup client
+* (`scrypted-remote-backup`, `src/main.ts`): a server address, a target
+* directory, username / password / domain, and a max-protocol override for
+* the servers that need one pinned.
+*
+* `share` is split out of the address rather than asking the operator for a
+* `//host/share` UNC string, because the pair `(host, share, basePath)` is the
+* duplicate-location key the provider refuses on — a free-form UNC string
+* would have to be re-parsed to ask that question, and would compare unequal
+* for two spellings of the same share.
+*/
+var SMB_CONFIG_SCHEMA = { sections: [{
+	id: "connection",
+	title: "Connection",
+	fields: [
+		{
+			type: "text",
+			key: "host",
+			label: "Server",
+			description: "SMB server hostname or IP (no slashes).",
+			required: true,
+			placeholder: "nas.local"
+		},
+		{
+			type: "text",
+			key: "share",
+			label: "Share",
+			description: "Share name as exported by the server, without slashes.",
+			required: true,
+			placeholder: "backups"
+		},
+		{
+			type: "number",
+			key: "port",
+			label: "Port",
+			description: "Leave empty for the default (445).",
+			min: 1,
+			max: 65535
+		},
+		{
+			type: "text",
+			key: "username",
+			label: "Username",
+			description: "Leave empty for a guest (anonymous) connection."
+		},
+		{
+			type: "password",
+			key: "password",
+			label: "Password",
+			showToggle: true
+		},
+		{
+			type: "text",
+			key: "domain",
+			label: "Domain / Workgroup",
+			description: "Optional. Required by some AD-joined servers."
+		},
+		{
+			type: "text",
+			key: "maxProtocol",
+			label: "Max protocol",
+			description: "Optional dialect ceiling, e.g. SMB3. Set this when a server negotiates a dialect the client mishandles.",
+			placeholder: "SMB3"
+		}
+	]
+}, {
+	id: "storage",
+	title: "Storage",
+	fields: [{
+		type: "text",
+		key: "basePath",
+		label: "Directory in share",
+		description: "Directory inside the share where files are written. Leave empty for the share root. Created if missing.",
+		placeholder: "camstack"
+	}]
+}] };
+//#endregion
+//#region src/providers/smb/smb-client.ts
+/**
+* The seam between the SMB provider and `samba-client`.
+*
+* `samba-client@7` is a thin wrapper around the **`smbclient` binary** — it
+* shells out through `execa` rather than speaking SMB in JavaScript. That is
+* the whole reason it was chosen over the pure-JS options: every SMB client on
+* npm is a fork of the abandoned `@marsaud/smb2` (last publish 2022), whereas
+* `smbclient` is Samba's own tool, maintained by the people who define the
+* protocol. It is the client the operator's `scrypted-remote-backup` plugin
+* has been running in production against this same NAS.
+*
+* The cost is stated plainly because it does not go away: **the provider
+* cannot work without the `smbclient` binary on PATH.** It is absent from the
+* CamStack container image. The binary is obtained through the framework's
+* manifest-declared system dependencies (`camstack.addons[].systemDependencies`
+* → `installManifestSystemDeps`), which runs before this addon's capabilities
+* register — and when that fails, {@link SmbBinaryUnavailableError} is what
+* every method of the provider raises, so a missing binary reads as a REFUSAL
+* and never as an empty share.
+*/
+var execFileAsync = promisify(execFile);
+/** The binary every operation ultimately runs. */
+var SMB_BINARY = "smbclient";
+/** How long the one-shot `command -v smbclient` probe may take. */
+var PROBE_TIMEOUT_MS = 1e4;
+/**
+* Raised by every provider method when `smbclient` is not on PATH.
+*
+* A distinct type, not a generic `Error`, because the difference between
+* "this share is empty" and "this provider cannot run" is the difference
+* between a location that D293's delete guard will let an operator destroy
+* and one it will not.
+*/
+var SmbBinaryUnavailableError = class extends Error {
+	constructor() {
+		super(`smb-storage: the "${SMB_BINARY}" binary is not available on this node. It is declared in the addon manifest under camstack.addons[].systemDependencies and installed by the runner before this addon initialises; check the runner log for "system dependency install failed". Until it resolves, this provider refuses every operation — its locations are UNREACHABLE, which is not the same as empty.`);
+		this.name = "SmbBinaryUnavailableError";
+	}
+};
+/**
+* Default factory — a real `samba-client`.
+*
+* Imported lazily so that merely LOADING this module (which the addon does at
+* boot, before the binary check) never fails on a host where the package's
+* own dependency tree is incomplete. A provider that cannot be constructed
+* takes its three sibling providers down with it: they share
+* `execution.group: "remote-storage"`, so one throw at import time respawns
+* SFTP, S3 and WebDAV too.
+*/
+async function defaultSmbClientFactory(options) {
+	const SambaClient = (await import("samba-client")).default;
+	return new SambaClient({
+		...options,
+		maskCmd: true
+	});
+}
+/** Is `smbclient` on PATH? */
+async function probeSmbBinary() {
+	try {
+		await execFileAsync("command", ["-v", SMB_BINARY], {
+			timeout: PROBE_TIMEOUT_MS,
+			shell: "/bin/sh"
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/providers/smb/smb-paths.ts
+/**
+* Path and identity helpers for the SMB provider.
+*
+* Two of these exist because `smbclient` is driven through a COMMAND STRING,
+* not an argument vector: `samba-client` builds `-c "<verb> <args>"` and hands
+* the whole thing to the binary, which parses it again. Anything that reaches
+* a remote path from outside — a `relativePath` the caller chose — therefore
+* has to be refused before it becomes part of that string.
+*/
+/**
+* Characters that would break out of, or corrupt, the `-c "<verb> <args>"`
+* command string smbclient re-parses.
+*
+* Refusing is the only safe option here: there is no escaping convention this
+* provider could apply that smbclient's own parser is guaranteed to undo the
+* same way. Every path CamStack itself generates (archive names are a UUID and
+* a timestamp) passes untouched, so the refusal costs nothing real.
+*/
+var FORBIDDEN_PATH_CHARS = /["'`$;&|<>\r\n\\]/;
+/** A path segment that would escape the location's own base. */
+var TRAVERSAL_SEGMENT = /(^|\/)\.\.(\/|$)/;
+/**
+* Validate a caller-supplied relative path, returning it normalised to
+* forward slashes.
+*/
+function safeSmbRelativePath(relativePath) {
+	if (relativePath.length === 0) return "";
+	if (FORBIDDEN_PATH_CHARS.test(relativePath)) throw new Error("smb-storage: relativePath contains a character that cannot be passed to smbclient safely (one of \" ' ` $ ; & | < > backslash or a newline). Refusing rather than escaping it.");
+	if (TRAVERSAL_SEGMENT.test(relativePath)) throw new Error(`smb-storage: relativePath "${relativePath}" escapes the location base`);
+	return relativePath.replace(/^\/+/, "");
+}
+/** `//host/share` — the address `smbclient` takes. */
+function smbAddress(host, share) {
+	return `//${host}/${share}`;
+}
+/**
+* Normalise a base path inside the share for COMPARISON, not for use:
+* lower-cased, slash-normalised, no leading or trailing slash. SMB is
+* case-insensitive, so `Backups` and `backups` are the same directory.
+*/
+function normalizedBasePath(basePath) {
+	return basePath.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "").toLowerCase();
+}
+/**
+* The identity of the PHYSICAL directory a location occupies.
+*
+* Two location records pointing at one directory is the hazard that has no
+* equivalent for a local disk: each carries its own retention policy and each
+* rewrites the destination's manifest, so the second one's sweep deletes
+* archives the first one still lists — and a restore then fails on a file the
+* manifest swears is present. Host and share are compared case-insensitively
+* because SMB is.
+*/
+function shareIdentity(input) {
+	return `${input.host.toLowerCase()}/${input.share.toLowerCase()}/${normalizedBasePath(input.basePath)}`;
+}
+/** Split a remote path into its directory segments, ignoring empties. */
+function pathSegments(remotePath) {
+	return remotePath.split("/").filter((s) => s.length > 0);
+}
+//#endregion
+//#region src/providers/smb/smb-provider.ts
+/**
+* SMB / CIFS `storage-provider` cap implementation — the fourth entry in
+* `@camstack/addon-remote-storage`.
+*
+* ── Scope, and why it is narrow ────────────────────────────────────────────
+* This provider serves `cap-mediated` storage kinds only, which today means
+* `backups`. That is not a limitation of SMB; it is the declared
+* service/location-kind constraint (D296). A kind whose owning service does
+* raw `node:fs` on the string `storage.resolve` hands back cannot be served by
+* ANY remote provider, and the orchestrator refuses the pairing at upsert time
+* rather than letting it fail at the first write — where, for recordings, it
+* would surface as a silent black window rather than an error.
+*
+* ── Why the I/O looks like this ────────────────────────────────────────────
+* `smbclient` is a file-at-a-time tool: `put`, `get`, `del`, `rename`. There
+* is no random-access write. So a chunked upload SPOOLS to a local temp file
+* and transfers once on `finalizeUpload`, and a chunked download fetches once
+* on `beginDownload` and serves ranges from the local copy. For the one
+* consumer this provider has — a nightly archive written by a single hub
+* singleton — that is the right trade: one transfer instead of N round trips,
+* and the transfer either completes or does not.
+*
+* ── Verify-on-finalize ─────────────────────────────────────────────────────
+* `finalizeUpload` stats the landed file and compares its size to the bytes
+* the session was given. `close()` returning is not a durability statement
+* over SMB — write-behind caching, oplocks and leases all sit between the
+* client and the server's platters — and the backup manifest carries no
+* checksum, so "the archive is there" is currently believed on the strength of
+* a call that returned. One round trip per nightly archive turns that into
+* "the server says the file is that many bytes", which is a materially
+* stronger claim and is the most this can assert without a `backup` cap
+* change.
+*
+* ── What every method does first ───────────────────────────────────────────
+* Checks that `smbclient` exists. A provider whose binary is missing must
+* REFUSE, loudly, and never resemble a provider whose share happens to be
+* empty: `empty` is what D293's delete guard needs to see before it will let
+* an operator destroy a location, and a full share behind a missing binary
+* must not clear that bar.
+*/
+var PROVIDER_ID = "smb-storage";
+var DISPLAY_NAME = "SMB / CIFS";
+/** Per-operation ceiling handed to smbclient (`-t`), in seconds. */
+var SMB_TIMEOUT_SECONDS = 60;
+function requireString(value, field, locationId) {
+	if (typeof value !== "string" || value.length === 0) throw new Error(`smb-storage: location "${locationId}" missing config.${field}`);
+	return value;
+}
+function optionalString(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function optionalNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+/** Read a `SmbConfig` out of a config record. Names the FIELD, never the value. */
+function smbConfigFromRecord(config, locationId) {
+	const host = requireString(config["host"], "host", locationId);
+	const share = requireString(config["share"], "share", locationId);
+	if (host.includes("/") || host.includes("\\")) throw new Error(`smb-storage: config.host must be a bare hostname, without slashes`);
+	if (share.includes("/") || share.includes("\\")) throw new Error(`smb-storage: config.share must be a bare share name, without slashes`);
+	return {
+		host,
+		share,
+		basePath: normalizedBasePathPreservingCase(optionalString(config["basePath"]) ?? ""),
+		...optionalNumber(config["port"]) !== void 0 ? { port: optionalNumber(config["port"]) } : {},
+		...optionalString(config["username"]) !== void 0 ? { username: optionalString(config["username"]) } : {},
+		...optionalString(config["password"]) !== void 0 ? { password: optionalString(config["password"]) } : {},
+		...optionalString(config["domain"]) !== void 0 ? { domain: optionalString(config["domain"]) } : {},
+		...optionalString(config["maxProtocol"]) !== void 0 ? { maxProtocol: optionalString(config["maxProtocol"]) } : {}
+	};
+}
+/** Trim slashes without lower-casing — the value is USED, not compared. */
+function normalizedBasePathPreservingCase(basePath) {
+	return basePath.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+}
+/**
+* Map a raw smbclient failure onto a closed set of operator-facing reasons.
+*
+* The raw text is never forwarded. `samba-client` puts `--password` on the
+* argv, and although `maskCmd` replaces the message with captured output, that
+* output still names accounts and domains on an NTLM failure — and
+* `storage.testConfig` returns this string verbatim to the caller.
+*/
+function mapSmbError(err) {
+	const text = (err instanceof Error ? err.message : String(err)).toUpperCase();
+	if (text.includes("LOGON_FAILURE") || text.includes("ACCESS_DENIED")) return "authentication failed";
+	if (text.includes("BAD_NETWORK_NAME") || text.includes("NO_SUCH_SHARE")) return "share not found";
+	if (text.includes("OBJECT_NAME_NOT_FOUND") || text.includes("OBJECT_PATH_NOT_FOUND")) return "path not found on the share";
+	if (text.includes("CONNECTION_REFUSED") || text.includes("ECONNREFUSED")) return "connection refused";
+	if (text.includes("TIMED OUT") || text.includes("ETIMEDOUT") || text.includes("IO_TIMEOUT")) return "timed out";
+	if (text.includes("HOST_UNREACHABLE") || text.includes("ENOTFOUND") || text.includes("EHOSTUNREACH")) return "server unreachable";
+	if (text.includes("DISK_FULL") || text.includes("NO_SPACE")) return "the share is full";
+	return "the SMB operation failed — see the addon log for the server response";
+}
+var SmbStorageProvider = class {
+	logger;
+	static providerId = PROVIDER_ID;
+	static displayName = DISPLAY_NAME;
+	uploads = /* @__PURE__ */ new Map();
+	downloads = /* @__PURE__ */ new Map();
+	createClient;
+	hasBinary;
+	spoolRoot;
+	/**
+	* Cached binary probe. Refreshed only from `false` → re-probe, so a node
+	* that gains the binary (the runner's install landing late, an operator
+	* fixing it by hand) recovers without a restart, while the healthy path
+	* costs one probe for the life of the process.
+	*/
+	binaryPresent = null;
+	constructor(logger, deps = {}) {
+		this.logger = logger;
+		this.createClient = deps.createClient ?? defaultSmbClientFactory;
+		this.hasBinary = deps.hasBinary ?? probeSmbBinary;
+		this.spoolRoot = deps.spoolDir ?? os.tmpdir();
+	}
+	async getProviderInfo() {
+		return {
+			providerId: PROVIDER_ID,
+			displayName: DISPLAY_NAME,
+			configSchema: SMB_CONFIG_SCHEMA,
+			nodeLocal: false,
+			shouldSaveDiskSpace: false,
+			minFreePercent: null
+		};
+	}
+	/**
+	* Validate config + probe connectivity.
+	*
+	* Three rules, all of them about what this string may contain: it goes
+	* straight back on the wire through `storage.testConfig`.
+	*  1. Validation errors name the FIELD, never the value — and a username is
+	*     half a credential, so it is not interpolated either.
+	*  2. Library errors are MAPPED, never forwarded. The raw text is logged.
+	*  3. The config object is never logged, at any level.
+	*/
+	async testLocation({ config }) {
+		if (!await this.binaryAvailable()) return {
+			ok: false,
+			error: new SmbBinaryUnavailableError().message
+		};
+		let cfg;
+		try {
+			cfg = smbConfigFromRecord(config, "(new)");
+		} catch (err) {
+			return {
+				ok: false,
+				error: err instanceof Error ? err.message : String(err)
+			};
+		}
+		try {
+			await (await this.clientFor(cfg)).list("");
+			return { ok: true };
+		} catch (err) {
+			this.logger.warn("smb-storage: testLocation failed", { meta: {
+				host: cfg.host,
+				share: cfg.share,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+			return {
+				ok: false,
+				error: mapSmbError(err)
+			};
+		}
+	}
+	/**
+	* Would this candidate config land on a share an existing location already
+	* owns? Two records on one directory each run their own retention sweep
+	* against a manifest the other also rewrites, so the second one deletes
+	* archives the first still lists — and the failure surfaces at RESTORE time,
+	* on a file the manifest swears is there.
+	*
+	* The identity of "the same share" is provider knowledge:
+	* `(host, share, basePath)` compared case-insensitively, which no generic
+	* uniqueness rule over an opaque `config` record could know.
+	*
+	* **NOT WIRED YET — say so rather than let the docblock imply otherwise.**
+	* Nothing calls this in production. The two surfaces that could are
+	* `storage.testConfig` (which passes only `{ providerId, config }`, so it
+	* cannot see siblings) and the orchestrator's `upsertLocation` (which can,
+	* but reaching a provider-specific method from generic dispatch means either
+	* a cast or a new method on the `storage-provider` cap — a cap change, and
+	* therefore codegen and a framework release).
+	*
+	* It ships as a tested predicate because the hazard is real and the identity
+	* rule is the part that is easy to get wrong; the plumbing is the cheap part
+	* and belongs with the cap change that carries it. Until then, two locations
+	* on one share are possible and nothing refuses them.
+	*/
+	findDuplicateShare(candidate, candidateId, existing) {
+		let candidateIdentity;
+		try {
+			candidateIdentity = shareIdentity(smbConfigFromRecord(candidate, candidateId));
+		} catch {
+			return null;
+		}
+		for (const other of existing) {
+			if (other.id === candidateId) continue;
+			if (other.providerId !== PROVIDER_ID) continue;
+			try {
+				if (shareIdentity(smbConfigFromRecord(other.config, other.id)) === candidateIdentity) return other;
+			} catch {
+				continue;
+			}
+		}
+		return null;
+	}
+	/**
+	* REFUSES, always.
+	*
+	* `resolve` exists on the cap to answer "give me a path I can open with
+	* node:fs", and there is no such path for a share this provider reaches over
+	* the wire. Returning `//nas/backups/camstack` — the shape SFTP, S3 and
+	* WebDAV return — is what makes the trap possible in the first place: the
+	* caller `fs.readdir`s it and gets either nothing or an unrelated local
+	* directory of the same name.
+	*
+	* The orchestrator already refuses this call before it arrives (D296). This
+	* is the second lock, and it is the one that holds if the orchestrator is
+	* ever bypassed — the provider itself never hands out a path that is not
+	* one.
+	*/
+	async resolve({ location, relativePath }) {
+		this.logger.warn("smb-storage: REFUSED resolve() — an SMB share has no local path", { meta: {
+			id: location.id,
+			relativePath
+		} });
+		throw new Error(`smb-storage: location "${location.id}" is a remote SMB share and has no path this node can open with node:fs. Use the storage cap's read/write or chunked upload/download instead of resolving a path.`);
+	}
+	async write({ location, relativePath, data }) {
+		const spool = await this.spoolFile();
+		try {
+			await fsp.writeFile(spool, data);
+			await this.putFile(location, relativePath, spool, data.byteLength);
+		} finally {
+			await this.discardSpool(spool);
+		}
+	}
+	async read({ location, relativePath }) {
+		const spool = await this.spoolFile();
+		try {
+			await this.fetchFile(location, relativePath, spool);
+			const buf = await fsp.readFile(spool);
+			const out = new Uint8Array(new ArrayBuffer(buf.byteLength));
+			out.set(buf);
+			return out;
+		} finally {
+			await this.discardSpool(spool);
+		}
+	}
+	async exists({ location, relativePath }) {
+		return await this.statRemote(location, relativePath) !== null;
+	}
+	async list({ location, prefix }) {
+		const client = await this.clientForLocation(location);
+		const dir = safeSmbRelativePath(prefix ?? "");
+		try {
+			return (await client.list(dir)).filter((e) => e.name !== "." && e.name !== "..").map((e) => dir === "" ? e.name : `${dir}/${e.name}`);
+		} catch (err) {
+			if (isNotFound(err)) return [];
+			this.logger.warn("smb-storage: list failed", { meta: {
+				id: location.id,
+				prefix: dir,
+				error: mapSmbError(err)
+			} });
+			throw err;
+		}
+	}
+	async delete({ location, relativePath }) {
+		const client = await this.clientForLocation(location);
+		const target = safeSmbRelativePath(relativePath);
+		try {
+			await client.deleteFile(target);
+		} catch (err) {
+			if (isNotFound(err)) {
+				this.logger.debug("smb-storage: delete of an already-absent file", { meta: {
+					id: location.id,
+					relativePath: target
+				} });
+				return;
+			}
+			throw err;
+		}
+	}
+	/** Always `null` — see `getProviderInfo`. */
+	async getAvailableSpace(_input) {
+		return null;
+	}
+	async beginUpload({ location, relativePath }) {
+		await this.assertBinary();
+		const target = safeSmbRelativePath(relativePath);
+		const uploadId = randomUUID();
+		const spoolPath = await this.spoolFile();
+		await fsp.writeFile(spoolPath, new Uint8Array(0));
+		const session = {
+			location,
+			relativePath: target,
+			spoolPath,
+			bytesWritten: 0,
+			timer: scheduleIdleAbort(() => {
+				this.logger.warn("smb-storage: upload session idle — aborting", { meta: {
+					id: location.id,
+					relativePath: target,
+					uploadId
+				} });
+				this.abortUpload({ uploadId });
+			})
+		};
+		this.uploads.set(uploadId, session);
+		return { uploadId };
+	}
+	async writeChunk({ uploadId, offset, data }) {
+		const session = this.uploads.get(uploadId);
+		if (!session) throw new Error(`smb-storage: unknown uploadId "${uploadId}"`);
+		if (offset !== session.bytesWritten) throw new Error(`smb-storage: out-of-order chunk for upload "${uploadId}" — expected offset ${session.bytesWritten}, got ${offset}. This provider spools sequentially.`);
+		const handle = await fsp.open(session.spoolPath, "a");
+		try {
+			await handle.write(data);
+		} finally {
+			await handle.close();
+		}
+		session.bytesWritten += data.byteLength;
+		session.timer = rearmIdleAbort(session.timer, () => {
+			this.logger.warn("smb-storage: upload session idle — aborting", { meta: {
+				id: session.location.id,
+				relativePath: session.relativePath,
+				uploadId
+			} });
+			this.abortUpload({ uploadId });
+		});
+	}
+	/**
+	* Transfer the spooled file, then VERIFY it landed at the right size.
+	*
+	* The sequence is `put` to `<name>.partial`, delete any existing target,
+	* rename onto it, stat. Rename-over-existing is not universally permitted on
+	* SMB, hence the delete — which means the finalize is NOT atomic: a crash
+	* between the delete and the rename destroys the previous file without
+	* landing the new one. For the one consumer this has (`backups`, whose
+	* archive names are unique per run) the target never exists, so that window
+	* is not entered in practice. It is written down because it WOULD be entered
+	* by any consumer that overwrites a stable filename.
+	*/
+	async finalizeUpload({ uploadId }) {
+		const session = this.uploads.get(uploadId);
+		if (!session) throw new Error(`smb-storage: unknown uploadId "${uploadId}"`);
+		clearTimeout(session.timer);
+		this.uploads.delete(uploadId);
+		try {
+			await this.putFile(session.location, session.relativePath, session.spoolPath, session.bytesWritten);
+		} finally {
+			await this.discardSpool(session.spoolPath);
+		}
+	}
+	async abortUpload({ uploadId }) {
+		const session = this.uploads.get(uploadId);
+		if (!session) return;
+		clearTimeout(session.timer);
+		this.uploads.delete(uploadId);
+		this.logger.info("smb-storage: upload aborted — nothing was written to the share", { meta: {
+			id: session.location.id,
+			relativePath: session.relativePath,
+			bytesSpooled: session.bytesWritten
+		} });
+		await this.discardSpool(session.spoolPath);
+	}
+	async beginDownload({ location, relativePath }) {
+		const spoolPath = await this.spoolFile();
+		let sizeBytes;
+		try {
+			await this.fetchFile(location, relativePath, spoolPath);
+			sizeBytes = (await fsp.stat(spoolPath)).size;
+		} catch (err) {
+			await this.discardSpool(spoolPath);
+			throw err;
+		}
+		const downloadId = randomUUID();
+		this.downloads.set(downloadId, {
+			spoolPath,
+			sizeBytes,
+			timer: scheduleIdleAbort(() => {
+				this.logger.warn("smb-storage: download session idle — closing", { meta: {
+					id: location.id,
+					relativePath,
+					downloadId
+				} });
+				this.endDownload({ downloadId });
+			})
+		});
+		return {
+			downloadId,
+			sizeBytes
+		};
+	}
+	async readChunk({ downloadId, offset, length }) {
+		const session = this.downloads.get(downloadId);
+		if (!session) throw new Error(`smb-storage: unknown downloadId "${downloadId}"`);
+		const handle = await fsp.open(session.spoolPath, "r");
+		try {
+			const out = new Uint8Array(new ArrayBuffer(Math.max(0, length)));
+			const { bytesRead } = await handle.read(out, 0, out.byteLength, offset);
+			session.timer = rearmIdleAbort(session.timer, () => {
+				this.endDownload({ downloadId });
+			});
+			return bytesRead === out.byteLength ? out : out.slice(0, bytesRead);
+		} finally {
+			await handle.close();
+		}
+	}
+	async endDownload({ downloadId }) {
+		const session = this.downloads.get(downloadId);
+		if (!session) return;
+		clearTimeout(session.timer);
+		this.downloads.delete(downloadId);
+		await this.discardSpool(session.spoolPath);
+	}
+	/** Drop every open session. Called from the addon's `onShutdown`. */
+	async dispose() {
+		for (const uploadId of [...this.uploads.keys()]) await this.abortUpload({ uploadId });
+		for (const downloadId of [...this.downloads.keys()]) await this.endDownload({ downloadId });
+	}
+	async binaryAvailable() {
+		if (this.binaryPresent === true) return true;
+		this.binaryPresent = await this.hasBinary();
+		return this.binaryPresent;
+	}
+	async assertBinary() {
+		if (await this.binaryAvailable()) return;
+		throw new SmbBinaryUnavailableError();
+	}
+	async clientForLocation(location) {
+		await this.assertBinary();
+		return this.clientFor(smbConfigFromRecord(location.config, location.id));
+	}
+	/**
+	* A client scoped to `(host, share, basePath)`.
+	*
+	* Deliberately NOT pooled. `samba-client` holds no connection between calls
+	* — every method spawns a fresh `smbclient` — so a pool would cache an
+	* options object and nothing else, while giving the false impression that a
+	* session survives. The cost of constructing one is an object literal.
+	*/
+	async clientFor(cfg) {
+		return this.createClient({
+			address: smbAddress(cfg.host, cfg.share),
+			timeout: SMB_TIMEOUT_SECONDS,
+			maskCmd: true,
+			...cfg.username !== void 0 ? { username: cfg.username } : {},
+			...cfg.password !== void 0 ? { password: cfg.password } : {},
+			...cfg.domain !== void 0 ? { domain: cfg.domain } : {},
+			...cfg.port !== void 0 ? { port: cfg.port } : {},
+			...cfg.maxProtocol !== void 0 ? { maxProtocol: cfg.maxProtocol } : {},
+			...cfg.basePath !== "" ? { directory: cfg.basePath } : {}
+		});
+	}
+	/** One entry of a remote listing, or `null` when the path does not exist. */
+	async statRemote(location, relativePath) {
+		const client = await this.clientForLocation(location);
+		const target = safeSmbRelativePath(relativePath);
+		const dir = target.includes("/") ? target.slice(0, target.lastIndexOf("/")) : "";
+		const name = target.includes("/") ? target.slice(target.lastIndexOf("/") + 1) : target;
+		try {
+			return (await client.list(dir)).find((e) => e.name.toLowerCase() === name.toLowerCase()) ?? null;
+		} catch (err) {
+			if (isNotFound(err)) return null;
+			throw err;
+		}
+	}
+	/** `put` the local file, then rename onto the target and verify its size. */
+	async putFile(location, relativePath, localPath, expectedBytes) {
+		const client = await this.clientForLocation(location);
+		const target = safeSmbRelativePath(relativePath);
+		const partial = `${target}.partial`;
+		await this.ensureRemoteDirs(client, target);
+		await client.sendFile(localPath, partial);
+		try {
+			await client.deleteFile(target);
+		} catch (err) {
+			if (!isNotFound(err)) throw err;
+		}
+		await client.execute("rename", [partial, target], "");
+		const landed = await this.statRemote(location, target);
+		if (landed === null) throw new Error(`smb-storage: "${target}" is not present on the share after the transfer completed`);
+		if (landed.size !== expectedBytes) {
+			this.logger.error("smb-storage: size mismatch after upload — the file did NOT land intact", { meta: {
+				id: location.id,
+				relativePath: target,
+				expectedBytes,
+				landedBytes: landed.size
+			} });
+			throw new Error(`smb-storage: "${target}" landed at ${landed.size} bytes but ${expectedBytes} were sent. Treating the transfer as failed — a returned write is not a durability statement over SMB.`);
+		}
+	}
+	async fetchFile(location, relativePath, localPath) {
+		const client = await this.clientForLocation(location);
+		const target = safeSmbRelativePath(relativePath);
+		await client.getFile(target, localPath);
+	}
+	/**
+	* `mkdir -p` for the parent chain of a target path. smbclient's `mkdir` is
+	* single-level and errors on an existing directory, so this walks the chain
+	* and treats every failure as "it is already there" — the subsequent `put`
+	* is what actually decides whether the directory exists.
+	*/
+	async ensureRemoteDirs(client, target) {
+		const segments = pathSegments(target);
+		if (segments.length <= 1) return;
+		let prefix = "";
+		for (const segment of segments.slice(0, -1)) {
+			prefix = prefix === "" ? segment : `${prefix}/${segment}`;
+			try {
+				await client.mkdir(prefix);
+			} catch {}
+		}
+	}
+	async spoolFile() {
+		const dir = await fsp.mkdtemp(path.join(this.spoolRoot, "camstack-smb-"));
+		return path.join(dir, "spool.bin");
+	}
+	async discardSpool(spoolPath) {
+		try {
+			await fsp.rm(path.dirname(spoolPath), {
+				recursive: true,
+				force: true
+			});
+		} catch (err) {
+			this.logger.warn("smb-storage: could not remove a spool directory", { meta: {
+				spoolPath,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+};
+/** smbclient's two "it is not there" statuses. */
+function isNotFound(err) {
+	const text = (err instanceof Error ? err.message : String(err)).toUpperCase();
+	return text.includes("NT_STATUS_OBJECT_NAME_NOT_FOUND") || text.includes("NT_STATUS_NO_SUCH_FILE") || text.includes("NT_STATUS_OBJECT_PATH_NOT_FOUND");
+}
+//#endregion
+//#region src/smb.addon.ts
+/**
+* SMB / CIFS storage-provider addon — the fourth manifest entry in
+* `@camstack/addon-remote-storage`.
+*
+* Each cap-collection registrant needs a distinct addonId: `CapabilityRegistry`
+* keys collection providers by `Map<addonId, …>`, so registering a second
+* provider from `sftp-storage` would silently replace SFTP rather than join it.
+*
+* The binary this provider wraps (`smbclient`) is declared in the package
+* manifest under `camstack.addons[].systemDependencies` and installed by the
+* runner BEFORE this class initialises. When that install fails the addon
+* still loads — the provider refuses every call with
+* `SmbBinaryUnavailableError`, so its locations read as unreachable rather
+* than as empty. Empty is deletable (D293); unreachable is not.
+*/
+var SmbStorageAddon = class extends BaseAddon {
+	impl = null;
+	constructor() {
+		super({});
+	}
+	async onInitialize() {
+		this.impl = new SmbStorageProvider(this.ctx.logger);
+		return [{
+			capability: storageProviderCapability,
+			provider: this.impl
+		}];
+	}
+	async onShutdown() {
+		await this.impl?.dispose();
+		this.impl = null;
+	}
+};
+//#endregion
+export { SmbStorageAddon, SmbStorageAddon as default, SmbBinaryUnavailableError as n, SmbStorageProvider as t };