dsh-webdav-sync 0.0.0-stage → 1.0.1

package/lib/crypto.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The sealed envelope the backup travels in: AES-256-GCM under a key derived
+ * from the passphrase with PBKDF2-SHA256. Nothing in it can be read without the
+ * passphrase — not by the WebDAV server, not by whoever else reaches the file.
+ *
+ * The envelope's own fields are authenticated as additional data, so the KDF
+ * parameters or salt cannot be swapped for weaker ones unnoticed.
+ */
+/** Envelope format word. A file that does not carry it is not ours. */
+export declare const FORMAT = "dsh-webdav-sync-backup";
+/** PBKDF2 rounds. Matches the cost magpie settled on for the same job. */
+export declare const ITERATIONS = 600000;
+/** The wire envelope. Every field is authenticated by {@link header}. */
+export interface Envelope {
+    format: string;
+    version: number;
+    kdf: string;
+    iterations: number;
+    salt: string;
+    nonce: string;
+    data: string;
+}
+/** The passphrase does not open this file — wrong passphrase, or the file changed. */
+export declare class PassphraseError extends Error {
+    constructor();
+}
+/** The bytes are not a backup of ours, or are one cut short. */
+export declare class CorruptError extends Error {
+    constructor(message?: string);
+}
+/** The file is a backup, but of a format this build does not read. */
+export declare class NotBackupError extends Error {
+    constructor();
+}
+/** `true` when the body begins like a sealed backup, whatever it does after that. */
+export declare function looksSealed(data: Uint8Array): boolean;
+/**
+ * Seal a value into the envelope. The returned bytes are what leaves the
+ * computer; nothing else of the setup ever does.
+ */
+export declare function seal(value: unknown, passphrase: string): Promise<Uint8Array>;
+/**
+ * Open a sealed envelope. Throws {@link PassphraseError} when the passphrase is
+ * wrong and {@link CorruptError} / {@link NotBackupError} when the bytes are not
+ * a readable backup of ours.
+ */
+export declare function open(data: Uint8Array, passphrase: string): Promise<unknown>;
+/** Lowercase hex SHA-256, the plugin's one hash. */
+export declare function sum(data: Uint8Array | string): string;
+/** Lowercase hex SHA-256 of a value's canonical JSON, for whole-object hashing. */
+export declare function hashJson(value: unknown): string;
+/**
+ * JSON with object keys sorted, so the same value hashes the same however the
+ * YAML it came from happened to order its keys.
+ */
+export declare function stableJson(value: unknown): string;
+/** Constant-time string comparison, for anything secret-shaped. */
+export declare function sameSecret(a: string, b: string): boolean;
+/**
+ * The bytes without a byte-order mark. An editor on Windows may leave one at the
+ * head of a file it wrote, and a JSON parse fails on it for a reason that says
+ * nothing about what is actually wrong.
+ */
+export declare function stripBom(data: Uint8Array): Uint8Array;

package/lib/crypto.js

@@ -0,0 +1,185 @@
+/**
+ * The sealed envelope the backup travels in: AES-256-GCM under a key derived
+ * from the passphrase with PBKDF2-SHA256. Nothing in it can be read without the
+ * passphrase — not by the WebDAV server, not by whoever else reaches the file.
+ *
+ * The envelope's own fields are authenticated as additional data, so the KDF
+ * parameters or salt cannot be swapped for weaker ones unnoticed.
+ */
+import { createCipheriv, createDecipheriv, pbkdf2, randomBytes, createHash, timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+const pbkdf2Async = promisify(pbkdf2);
+/** Envelope format word. A file that does not carry it is not ours. */
+export const FORMAT = 'dsh-webdav-sync-backup';
+/** PBKDF2 rounds. Matches the cost magpie settled on for the same job. */
+export const ITERATIONS = 600_000;
+/** Rounds accepted when opening: a floor against a file that asks for a cheap KDF. */
+const MIN_ITERATIONS = 100_000;
+const MAX_ITERATIONS = 10_000_000;
+const SALT_BYTES = 16;
+const NONCE_BYTES = 12;
+const KEY_BYTES = 32;
+/** The passphrase does not open this file — wrong passphrase, or the file changed. */
+export class PassphraseError extends Error {
+    constructor() {
+        super('口令打不开服务器上的文件：请用你在其他机器上设置的那个口令');
+        this.name = 'PassphraseError';
+    }
+}
+/** The bytes are not a backup of ours, or are one cut short. */
+export class CorruptError extends Error {
+    constructor(message = '服务器上的文件不是一份完整的 dsh-webdav-sync 备份') {
+        super(message);
+        this.name = 'CorruptError';
+    }
+}
+/** The file is a backup, but of a format this build does not read. */
+export class NotBackupError extends Error {
+    constructor() {
+        super('服务器上的文件不是 dsh-webdav-sync 写出来的');
+        this.name = 'NotBackupError';
+    }
+}
+/** `true` when the body begins like a sealed backup, whatever it does after that. */
+export function looksSealed(data) {
+    const text = new TextDecoder().decode(data.subarray(0, 256)).replace(/\s+/g, '');
+    return text.startsWith('{"format":"' + FORMAT + '"');
+}
+/**
+ * Seal a value into the envelope. The returned bytes are what leaves the
+ * computer; nothing else of the setup ever does.
+ */
+export async function seal(value, passphrase) {
+    // An empty passphrase would seal the profile with a key anyone can derive,
+    // which is worse than not syncing at all: refuse rather than pretend.
+    if (passphrase.trim() === '')
+        throw new Error('备份需要一个口令来加密');
+    const salt = randomBytes(SALT_BYTES);
+    const nonce = randomBytes(NONCE_BYTES);
+    const envelope = {
+        format: FORMAT,
+        version: 1,
+        kdf: 'pbkdf2-sha256',
+        iterations: ITERATIONS,
+        salt: salt.toString('hex'),
+        nonce: nonce.toString('hex'),
+        data: '',
+    };
+    const key = await derive(passphrase, salt, envelope.iterations);
+    const cipher = createCipheriv('aes-256-gcm', key, nonce);
+    cipher.setAAD(header(envelope));
+    const plain = Buffer.from(JSON.stringify(value), 'utf8');
+    const sealed = Buffer.concat([cipher.update(plain), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    envelope.data = Buffer.concat([sealed, tag]).toString('base64');
+    // Indented so the head of the file reads as a backup at a glance, and a
+    // relay that cuts the body short still leaves a recognizable head behind.
+    return Buffer.from(JSON.stringify(envelope, null, 2), 'utf8');
+}
+/**
+ * Open a sealed envelope. Throws {@link PassphraseError} when the passphrase is
+ * wrong and {@link CorruptError} / {@link NotBackupError} when the bytes are not
+ * a readable backup of ours.
+ */
+export async function open(data, passphrase) {
+    const text = new TextDecoder().decode(stripBom(data));
+    let envelope;
+    try {
+        envelope = JSON.parse(text);
+    }
+    catch {
+        // A backup a relay cut short ends in the middle of `data` and fails here, as
+        // does a sign-in page a captive portal answered with. Only a body that
+        // begins like ours counts as damage.
+        if (looksSealed(data))
+            throw new CorruptError();
+        throw new NotBackupError();
+    }
+    if (envelope.format !== FORMAT)
+        throw new NotBackupError();
+    if (envelope.version !== 1 || envelope.kdf !== 'pbkdf2-sha256') {
+        throw new NotBackupError();
+    }
+    const salt = Buffer.from(envelope.salt ?? '', 'hex');
+    const nonce = Buffer.from(envelope.nonce ?? '', 'hex');
+    if (!Number.isInteger(envelope.iterations) ||
+        envelope.iterations < MIN_ITERATIONS ||
+        envelope.iterations > MAX_ITERATIONS ||
+        nonce.length !== NONCE_BYTES ||
+        salt.length < SALT_BYTES) {
+        throw new CorruptError();
+    }
+    const body = Buffer.from(envelope.data ?? '', 'base64');
+    if (body.length <= 16)
+        throw new CorruptError();
+    const key = await derive(passphrase, salt, envelope.iterations);
+    const decipher = createDecipheriv('aes-256-gcm', key, nonce);
+    decipher.setAAD(header(envelope));
+    decipher.setAuthTag(body.subarray(body.length - 16));
+    let plain;
+    try {
+        plain = Buffer.concat([decipher.update(body.subarray(0, body.length - 16)), decipher.final()]);
+    }
+    catch {
+        // A tag that does not verify means the passphrase is wrong or the file was
+        // changed after it was written; the two are indistinguishable on purpose.
+        throw new PassphraseError();
+    }
+    try {
+        return JSON.parse(plain.toString('utf8'));
+    }
+    catch {
+        throw new CorruptError('服务器上的文件解开了，但里面不是可读的 dsh 配置');
+    }
+}
+/** What the sealing authenticates besides the bundle: the envelope's own fields. */
+function header(envelope) {
+    return Buffer.from(`${envelope.format}/${envelope.version}/${envelope.kdf}/${envelope.iterations}/${envelope.salt}`, 'utf8');
+}
+async function derive(passphrase, salt, iterations) {
+    return (await pbkdf2Async(passphrase, salt, iterations, KEY_BYTES, 'sha256'));
+}
+/** Lowercase hex SHA-256, the plugin's one hash. */
+export function sum(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/** Lowercase hex SHA-256 of a value's canonical JSON, for whole-object hashing. */
+export function hashJson(value) {
+    return sum(stableJson(value));
+}
+/**
+ * JSON with object keys sorted, so the same value hashes the same however the
+ * YAML it came from happened to order its keys.
+ */
+export function stableJson(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const record = value;
+    const out = {};
+    for (const key of Object.keys(record).sort())
+        out[key] = sortValue(record[key]);
+    return out;
+}
+/** Constant-time string comparison, for anything secret-shaped. */
+export function sameSecret(a, b) {
+    const left = Buffer.from(a, 'utf8');
+    const right = Buffer.from(b, 'utf8');
+    if (left.length !== right.length)
+        return false;
+    return timingSafeEqual(left, right);
+}
+/**
+ * The bytes without a byte-order mark. An editor on Windows may leave one at the
+ * head of a file it wrote, and a JSON parse fails on it for a reason that says
+ * nothing about what is actually wrong.
+ */
+export function stripBom(data) {
+    if (data.length >= 3 && data[0] === 0xef && data[1] === 0xbb && data[2] === 0xbf)
+        return data.subarray(3);
+    return data;
+}

package/lib/dav.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The WebDAV client. One file lives at `<address>/dsh-webdav/dsh-profile.dshsync`,
+ * and the whole protocol between this computer and that file is:
+ *
+ *   - read it, with the version last seen so an unchanged file costs one request;
+ *   - write it over the version that was read, so another computer's write in
+ *     between is refused rather than silently overwritten.
+ *
+ * The servers that answer are as varied as the people who run them: 坚果云
+ * (Nutstore) counts requests per account and answers a read of a folder that is
+ * not there with 409 rather than 404; Synology answers 403 for a file in a
+ * missing folder; Apache's mod_deflate rewrites an ETag for the compressed copy
+ * it hands back, which then never matches in `If-Match`. Every one of those is
+ * handled where it happens, with the reason it exists written beside it.
+ */
+import { type ServerVersion } from './wire.js';
+/** The file was not written because it changed on the server since it was read. */
+export declare class ChangedError extends Error {
+    constructor();
+}
+/** The file is still the version last read; the server did not send it again. */
+export declare class NotModifiedError extends Error {
+    constructor();
+}
+/** The server refused the account. */
+export declare class LoginError extends Error {
+    constructor();
+}
+/** The server is limiting how often it is reached, or is busy. */
+export declare class RateLimitedError extends Error {
+    readonly status: number;
+    readonly after: number;
+    constructor(status: number, after: number);
+}
+/** A 403 the server would not explain; carries the folder the address names. */
+export declare class ForbiddenError extends Error {
+    readonly explained: boolean;
+    constructor(message: string, explained: boolean);
+}
+/** What one address and account reach. */
+export interface DavOptions {
+    url: string;
+    user: string;
+    password: string;
+}
+/**
+ * What one read found. `data` is absent when the server holds no file yet — which
+ * servers say in several ways, none of them an error. `notModified` is set when
+ * the server answered the conditional read with 304, in which case `data` is
+ * absent and `version` is the one that was asked about.
+ */
+export interface DavRead {
+    data?: Uint8Array;
+    version: ServerVersion;
+    notModified?: boolean;
+    /** Where a redirect ended, when it ended somewhere other than the file. */
+    redirectedTo?: string;
+}
+/** A resolved WebDAV endpoint. */
+export declare class Dav {
+    private readonly base;
+    /**
+     * The address's own path, without a trailing slash, and empty for a server
+     * root. It is kept aside because a URL cannot hold that emptiness: assigning
+     * `''` to a pathname puts the `/` straight back, and joining onto that `/`
+     * would build `//dsh-webdav`, which servers answer 400 to.
+     */
+    private readonly basePath;
+    private readonly user;
+    private readonly password;
+    constructor(options: DavOptions);
+    /** The address, without any credentials that may have ridden in on it. */
+    get address(): string;
+    /** The full URL of one path under the address. */
+    url(...parts: string[]): string;
+    /** Where the backup file itself lives. */
+    get fileUrl(): string;
+    /**
+     * Read the backup.
+     *
+     * Returns `undefined` when the server holds none yet — which several servers
+     * say in several ways. Throws {@link NotModifiedError} when `have` is still
+     * current, {@link LoginError}, {@link RateLimitedError} or {@link ForbiddenError}.
+     */
+    get(have?: ServerVersion): Promise<DavRead>;
+    /**
+     * Write the backup, only over the version that was read when there was one.
+     *
+     * Relays and tunnels cut long writes short, and the half that lands reads back
+     * as damage on every sync after, so what a write kept is read back and
+     * compared; a short write is tried again.
+     */
+    put(data: Uint8Array, etag?: string): Promise<ServerVersion>;
+    /** Whether the address is reachable and the account may read and write in it. */
+    check(): Promise<{
+        ok: true;
+    }>;
+    /** Read back what the file holds now, for the check action's report. */
+    stat(): Promise<{
+        exists: boolean;
+        size?: number;
+    }>;
+    /**
+     * Make the folder, tolerating the several ways servers say it is already
+     * there or that the folder above it is missing.
+     */
+    mkcol(): Promise<void>;
+    /**
+     * Say why a 403 was: servers answer it for a folder that is not there as much
+     * as for one the account may not write in, so the folder is looked at first.
+     */
+    private forbiddenMessage;
+    /**
+     * The folder a file could not be put in, named with the storages the address
+     * does hold — OpenList's and Alist's `/dav/` is a list of their storages, where
+     * MKCOL answers 405 and PUT 404, so the address has to go into one of them.
+     */
+    private nowhereMessage;
+    /** Whether PROPFIND finds a URL: a server answering 403 for what is not there may do so here too. */
+    private there;
+    /**
+     * The size a write kept, read back. `short` is true only when a real size was
+     * found and it is less than what was sent: a HEAD that cannot be done leaves
+     * the write unchecked, because it landed either way.
+     */
+    private verifyLength;
+    /** The file's size as PROPFIND (Depth 0) reports it; `undefined` when it says none. */
+    private length;
+    /** The child collections of a URL, as PROPFIND (Depth 1) lists them, and the status. */
+    private list;
+    /** One PROPFIND, with the Depth header the caller asks for. */
+    private propfind;
+    /** One request, with auth, redirect and rate-limit handling applied. */
+    private send;
+    /** The rate-limit error for an answer, carrying the server's own wait when it named one. */
+    private limited;
+}