swarm-deploy 0.0.0 → 0.2.0

package/RELEASING.md

@@ -0,0 +1,71 @@
+# Releasing
+
+Releases are immutable npm versions published by the tag-triggered GitHub Actions workflow. Do not publish from a workstation.
+
+## One-time setup
+
+1. In npm, grant the maintainers publish access to the unscoped `swarm-deploy` package.
+2. Configure npm trusted publishing for this GitHub repository, workflow `publish.yml`, and environment `npm`.
+3. Protect the `npm` environment with the required reviewers and deployment-branch/tag rules. Do not add an npm token: the workflow uses OIDC.
+4. Protect release tags and require the CI checks on `main`.
+
+## Preflight
+
+1. Update `package.json` to the new SemVer version and update `CHANGELOG.md`.
+   Confirm the README and CLI examples use direct `--server-key` uploads and
+   repeatable static `--allow-key` server configuration; topics and discovery
+   are not release interfaces.
+2. From a clean checkout, run:
+
+   ```sh
+   npm install
+   npm run build
+   npm run build:test
+   npm run lint
+   npm run test:node
+   npm run test:bare
+   npm run test:package
+   npm audit --omit=dev
+   npm publish --dry-run
+   ```
+
+3. Verify `GITHUB_REF_NAME=vX.Y.Z npm run test:release-tag` with the intended version.
+4. Merge the release commit and wait for required `main` CI checks.
+
+## Publish and verify
+
+The following are deliberate external actions and are not performed by tests or local release preparation:
+
+```sh
+git tag -s vX.Y.Z <release-commit>
+git push origin vX.Y.Z
+```
+
+Approve the protected `npm` environment if required. Confirm the workflow used provenance, then verify the registry metadata, provenance statement, tarball contents, and a fresh install:
+
+```sh
+npm view swarm-deploy@X.Y.Z version dist.integrity
+npm install --global swarm-deploy@X.Y.Z
+swarm-deploy --help
+```
+
+PR/main CI is the full test authority. The tag workflow verifies the exact
+stable tag and package version, confirms the tagged commit is on `main`, builds
+the untracked `dist/`, and validates the package before delegating to
+`holepunchto/actions/publish` at
+`146b86c4d0237c124df06ecc992ddf2c585b3405`. That composite action currently
+references `create-release@v1` internally and publishes with
+`npm publish --ignore-scripts` and creates the GitHub release, so the workflow
+must build `dist/` before invoking it.
+
+Roll the package into one canary client/server pair first. Confirm `ready`, authentication, offer, progress, verification, commit, recovery, scrub, retention, and cleanup diagnostics before broader rollout.
+
+## Rollback
+
+Package versions and deployment configuration are immutable inputs. Roll clients and servers back by reinstalling and redeploying the last known-good exact version; never republish an existing version. If the bad version should not be selected by users, deprecate it with a clear replacement:
+
+```sh
+npm deprecate swarm-deploy@X.Y.Z "Use X.Y.(Z+1); reason: <summary>"
+```
+
+Do not roll a server back while a v2 replacement journal is in flight. Stop new uploads, drain active work, and allow the current version to recover or finish every replacement journal first. Back up the dedicated storage root after a clean shutdown, and test the previous version against a copy before production rollback. An older server may not understand v2 replacement state.

package/SECURITY.md

@@ -0,0 +1,40 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are provided for the latest published release. Unreleased commits
+are not a supported production distribution.
+
+## Report a vulnerability
+
+Email [security-oss@tether.io](mailto:security-oss@tether.io). Do not open a
+public issue for a suspected vulnerability and do not include live seeds,
+private infrastructure details, or production artifacts.
+
+Include the affected version and runtime, operating system, impact, minimal
+reproduction, and whether seed material or stored artifacts may have been
+exposed. We will acknowledge the report within five working days. Coordination
+and disclosure may use a private GitHub Security Advisory.
+
+## Operator precautions
+
+- Generate independent server and client seeds and prefer owner-readable files
+  or protected environment variables. The CLI accepts `--seed` for explicit
+  inline configuration, but command arguments may be exposed through shell
+  history, process listings, CI tracing, and diagnostic tooling. Never log a
+  seed. A client pins the server's full public key; the server's immutable
+  startup allowlist names permitted client public keys. If a seed may be
+  exposed, rotate it, restart with a revised allowlist, and purge the
+  compromised secret from logs and caches.
+- Run under a dedicated non-root account with a dedicated storage root.
+  Swarm Deploy protects against detected symlink and directory-identity
+  changes, but it does not defend against a malicious process with the same OS
+  permissions.
+- Protect the startup allowlist as security-sensitive configuration. It is not
+  watched or reloaded: use a controlled server restart to change access.
+- Do not manipulate `.swarm-deploy/` or copy an active storage root. Stop the
+  server cleanly before backup or restore, preserve the whole root, and let the
+  same or newer package version complete recovery before serving traffic.
+- Fingerprints and digests are not seeds, but full public keys still identify
+  deployment principals. Share only the server public key with uploaders and
+  only client public keys with server operators.

package/dist/abort.d.ts

@@ -0,0 +1,16 @@
+import { SwarmDeployError } from './errors.js';
+export interface AbortSignalLike {
+    readonly aborted: boolean;
+    addEventListener(event: 'abort', callback: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(event: 'abort', callback: () => void): void;
+}
+export interface AbortControllerLike {
+    readonly signal: AbortSignalLike;
+    abort(): void;
+}
+export declare function abortError(): SwarmDeployError;
+export declare function throwIfAborted(signal: Pick<AbortSignalLike, 'aborted'> | null | undefined): void;
+export declare function onAbort(signal: AbortSignalLike | null | undefined, callback: () => void): () => void;
+export declare function createAbortController(): AbortControllerLike;

package/dist/abort.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.abortError = abortError;
+exports.throwIfAborted = throwIfAborted;
+exports.onAbort = onAbort;
+exports.createAbortController = createAbortController;
+const errors_js_1 = require("./errors.js");
+function abortError() {
+    return new errors_js_1.SwarmDeployError(errors_js_1.ERRORS.ABORTED, 'Operation aborted');
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw abortError();
+}
+function onAbort(signal, callback) {
+    if (!signal)
+        return () => { };
+    if (signal.aborted) {
+        callback();
+        return () => { };
+    }
+    signal.addEventListener('abort', callback, { once: true });
+    return () => signal.removeEventListener('abort', callback);
+}
+function createAbortController() {
+    if (typeof globalThis.AbortController === 'function')
+        return new globalThis.AbortController();
+    const listeners = new Set();
+    const signal = {
+        aborted: false,
+        addEventListener(event, callback) {
+            if (event === 'abort')
+                listeners.add(callback);
+        },
+        removeEventListener(event, callback) {
+            if (event === 'abort')
+                listeners.delete(callback);
+        }
+    };
+    return {
+        signal,
+        abort() {
+            if (signal.aborted)
+                return;
+            signal.aborted = true;
+            for (const callback of listeners)
+                callback();
+            listeners.clear();
+        }
+    };
+}
+//# sourceMappingURL=abort.js.map

package/dist/abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":";;;;;;AAAA,2CAAsD;AAatD;IACE,OAAO,IAAI,4BAAgB,CAAC,kBAAM,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAA;AAClE,CAAC;AAED,wBAA+B,MAA2D;IACxF,IAAI,MAAM,EAAE,OAAO;QAAE,MAAM,UAAU,EAAE,CAAA;AACzC,CAAC;AAED,iBACE,MAA0C,EAC1C,QAAoB;IAEpB,IAAI,CAAC,MAAM;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;IAC5B,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,QAAQ,EAAE,CAAA;QACV,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;IACjB,CAAC;IACD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAC1D,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;AAC5D,CAAC;AAED;IACE,IAAI,OAAO,UAAU,CAAC,eAAe,KAAK,UAAU;QAAE,OAAO,IAAI,UAAU,CAAC,eAAe,EAAE,CAAA;IAC7F,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAA;IACvC,MAAM,MAAM,GAA2C;QACrD,OAAO,EAAE,KAAK;QACd,gBAAgB,CAAC,KAAc,EAAE,QAAoB;YACnD,IAAI,KAAK,KAAK,OAAO;gBAAE,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;QAChD,CAAC;QACD,mBAAmB,CAAC,KAAc,EAAE,QAAoB;YACtD,IAAI,KAAK,KAAK,OAAO;gBAAE,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QACnD,CAAC;KACF,CAAA;IACD,OAAO;QACL,MAAM;QACN,KAAK;YACH,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAM;YAC1B,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;YACrB,KAAK,MAAM,QAAQ,IAAI,SAAS;gBAAE,QAAQ,EAAE,CAAA;YAC5C,SAAS,CAAC,KAAK,EAAE,CAAA;QACnB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/allowlist.d.ts

@@ -0,0 +1,2 @@
+/** Parses immutable, canonical client public keys for server startup. */
+export declare function parseAllowlist(text: string): Set<string>;

package/dist/allowlist.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAllowlist = parseAllowlist;
+const identity_js_1 = require("./identity.js");
+/** Parses immutable, canonical client public keys for server startup. */
+function parseAllowlist(text) {
+    if (typeof text !== 'string')
+        throw new TypeError('Allowlist must be text');
+    const keys = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        const key = line.trim();
+        if (key === '' || key.startsWith('#'))
+            continue;
+        (0, identity_js_1.parsePublicKey)(key);
+        if (keys.has(key))
+            throw new TypeError('Duplicate allowlist key');
+        keys.add(key);
+    }
+    return keys;
+}
+//# sourceMappingURL=allowlist.js.map

package/dist/allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.js","sourceRoot":"","sources":["../src/allowlist.ts"],"names":[],"mappings":";;;AAAA,+CAA8C;AAE9C,yEAAyE;AACzE,wBAA+B,IAAY;IACzC,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,MAAM,IAAI,SAAS,CAAC,wBAAwB,CAAC,CAAA;IAC3E,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACvB,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAQ;QAC/C,IAAA,4BAAc,EAAC,GAAG,CAAC,CAAA;QACnB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,yBAAyB,CAAC,CAAA;QACjE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACf,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/bin/swarm-deploy.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/swarm-deploy.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const _process_1 = __importDefault(require("#process"));
+const cli_js_1 = require("../cli.js");
+function reportFatal(err) {
+    try {
+        const message = err &&
+            typeof err === 'object' &&
+            'message' in err &&
+            typeof err.message === 'string' &&
+            err.message
+            ? err.message
+            : 'Unknown error';
+        if (_process_1.default.stderr && typeof _process_1.default.stderr.write === 'function') {
+            _process_1.default.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
+        }
+    }
+    catch { }
+}
+function exitWith(code) {
+    _process_1.default.exitCode = Number.isInteger(code) ? code : 1;
+}
+(0, cli_js_1.main)(_process_1.default.argv, _process_1.default.env, { process: _process_1.default }).then(exitWith, (err) => {
+    reportFatal(err);
+    exitWith(1);
+});
+if (typeof _process_1.default.on === 'function') {
+    _process_1.default.on('uncaughtException', (err) => {
+        reportFatal(err);
+        _process_1.default.exit(1);
+    });
+    _process_1.default.on('unhandledRejection', (err) => {
+        reportFatal(err);
+        _process_1.default.exit(1);
+    });
+}
+//# sourceMappingURL=swarm-deploy.js.map

package/dist/bin/swarm-deploy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"swarm-deploy.js","sourceRoot":"","sources":["../../src/bin/swarm-deploy.ts"],"names":[],"mappings":";;;;;;AAEA,wDAA8B;AAC9B,sCAAgC;AAEhC,SAAS,WAAW,CAAC,GAAY;IAC/B,IAAI,CAAC;QACH,MAAM,OAAO,GACX,GAAG;YACH,OAAO,GAAG,KAAK,QAAQ;YACvB,SAAS,IAAI,GAAG;YAChB,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;YAC/B,GAAG,CAAC,OAAO;YACT,CAAC,CAAC,GAAG,CAAC,OAAO;YACb,CAAC,CAAC,eAAe,CAAA;QACrB,IAAI,kBAAO,CAAC,MAAM,IAAI,OAAO,kBAAO,CAAC,MAAM,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YACjE,kBAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,CAAA;QACzE,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAA,CAAC;AACZ,CAAC;AAED,SAAS,QAAQ,CAAC,IAAa;IAC7B,kBAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,IAAe,CAAC,CAAC,CAAC,CAAC,CAAA;AAClE,CAAC;AAED,IAAA,aAAI,EAAC,kBAAO,CAAC,IAAI,EAAE,kBAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAP,kBAAO,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,GAAY,EAAE,EAAE;IAC3E,WAAW,CAAC,GAAG,CAAC,CAAA;IAChB,QAAQ,CAAC,CAAC,CAAC,CAAA;AACb,CAAC,CAAC,CAAA;AAEF,IAAI,OAAO,kBAAO,CAAC,EAAE,KAAK,UAAU,EAAE,CAAC;IACrC,kBAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAY,EAAE,EAAE;QAC/C,WAAW,CAAC,GAAG,CAAC,CAAA;QAChB,kBAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC,CAAC,CAAA;IACF,kBAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,GAAY,EAAE,EAAE;QAChD,WAAW,CAAC,GAAG,CAAC,CAAA;QAChB,kBAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,27 @@
+import { Server, type ServerOptions } from './server.js';
+import { Client, type ClientOptions } from './client.js';
+import type { DirectDhtNode } from './direct-dht.js';
+type Env = Record<string, string | undefined>;
+type Output = {
+    write(value: string): unknown;
+};
+type SignalProcess = {
+    on(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+    off?(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+    removeListener?(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+};
+type CliIo = {
+    stdout?: Output;
+    stderr?: Output;
+    process?: SignalProcess;
+    Server?: new (options: ServerOptions) => Server;
+    Client?: new (options: ClientOptions) => Client;
+    dht?: DirectDhtNode;
+    connectTimeout?: number;
+    idleTimeout?: number;
+    /** Directory that relative `--hooks` paths resolve against; defaults to `process.cwd()`. */
+    cwd?: string;
+};
+declare const USAGE: string;
+declare function main(argv: Iterable<string> | null | undefined, env: Env, io?: CliIo): Promise<number>;
+export { main, USAGE };