cursedbelt-server 1.0.0

package/dist/server/dropzone/scan.js

@@ -0,0 +1,272 @@
+/**
+ * The drop-folder scraper — the reusable half.
+ *
+ * Owner's ask, 2026-08-13: *"Do this to prepare a reusable strategy for multiple apps to get
+ * intelligent processing for binary-server. Some functionality may be reusable in multiple
+ * apps in different ways and can go in cb where standardized app functionality is shared. The
+ * specific ingestion logic that only binary-server or one app needs can go to the specific
+ * app."* … *"Make this tool reusable in case we need something like it on other folders
+ * later."*
+ *
+ * So: WALKING a drop folder, deciding a file has finished copying, sorting content from junk,
+ * deleting only what has been confirmed elsewhere, and leaving nothing behind — all of that is
+ * the same for music, family photographs, collections videos and notes documents, and all of
+ * it is here. What a file MEANS — which album, which artist, which collection — is the app's,
+ * and none of it is here.
+ *
+ * ── 🔴 Three rules that look like paranoia and are not ─────────────────────────────────
+ *
+ * 1. **A file is deleted only after the destination CONFIRMS it.** The dropzone is the one
+ *    place the owner's copy may be the only copy: they dragged it in expecting it to be taken.
+ *    A sweep that deletes on "the upload didn't throw" turns any catalog failure into data
+ *    loss. The handler returns `stored`/`duplicate` and only then does the original go.
+ *
+ * 2. **A file must measure the same size twice before it is touched.** Dropping a 4 GB video
+ *    into a folder is not atomic. Without this the sweep ingests a truncated file, reports
+ *    success, and deletes the real one as it is still being written. notes' ingester and
+ *    collections' both learned this the same way.
+ *
+ * 3. **One bad file never stops the sweep.** Every handler outcome is per-file, and a throw is
+ *    caught and recorded. The owner's instruction is explicit about the duplicate case — *"This
+ *    should not stall uploading the rest of the in progress uploads"* — and it generalizes: a
+ *    dropzone with one unreadable file in it must still drain the other 4,000.
+ */
+import { readdir, rm, rmdir, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+/** OS bookkeeping and editor scratch. Never content, in any app. */
+const OS_JUNK = new Set([
+    ".DS_Store",
+    ".localized",
+    "Icon\r",
+    "Thumbs.db",
+    "desktop.ini",
+    "README.md",
+]);
+const PARTIAL_SUFFIXES = [".download", ".crdownload", ".part", ".partial", ".tmp"];
+/** A name that is OS noise, editor scratch, or a copy still in flight. */
+export function isJunkName(name) {
+    if (OS_JUNK.has(name))
+        return true;
+    // A dotfile in a drop folder is the operating system's or another tool's state. The owner
+    // drops content, and content does not begin with a dot.
+    if (name.startsWith("."))
+        return true;
+    if (name.startsWith("._"))
+        return true; // AppleDouble resource forks
+    return PARTIAL_SUFFIXES.some((s) => name.toLowerCase().endsWith(s));
+}
+const extOf = (name) => {
+    const dot = name.lastIndexOf(".");
+    return dot > 0 ? name.slice(dot).toLowerCase() : "";
+};
+/**
+ * Every candidate file under `root`, deepest-last, with each one's sibling listing.
+ *
+ * Junk is NOT filtered out here — it is returned like anything else, because a sweep whose job
+ * includes *"if it's a wrong type of file delete it"* has to see it in order to delete it.
+ * {@link isJunkName} is exported so a handler can classify without re-deriving the list.
+ */
+export async function scanDropzone(root, opts = {}) {
+    const skip = new Set(opts.skipDirs ?? []);
+    const out = [];
+    const walk = async (dir) => {
+        if (opts.limit !== undefined && out.length >= opts.limit)
+            return;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // vanished mid-walk — a dropzone is a moving target by nature
+        }
+        const siblings = opts.captureSiblings
+            ? entries.filter((e) => e.isFile()).map((e) => e.name)
+            : [];
+        for (const entry of entries) {
+            if (opts.limit !== undefined && out.length >= opts.limit)
+                return;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (skip.has(entry.name))
+                    continue;
+                await walk(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            try {
+                const info = await stat(full);
+                out.push({
+                    path: full,
+                    relativePath: relative(root, full),
+                    name: entry.name,
+                    ext: extOf(entry.name),
+                    size: info.size,
+                    mtimeMs: info.mtimeMs,
+                    siblings,
+                });
+            }
+            catch {
+                /* gone between readdir and stat */
+            }
+        }
+    };
+    await walk(root);
+    return out;
+}
+/**
+ * How old an EMPTY file has to be before it is believed. See {@link isStable}.
+ *
+ * A file that has just been created and has no bytes yet is almost certainly mid-copy; the
+ * same file a minute later really is empty.
+ */
+export const EMPTY_FILE_GRACE_MS = 60_000;
+/**
+ * Has this file finished being copied in? See rule 2 in the header.
+ *
+ * 🔴 A zero-byte file needs its own answer, and getting it wrong strands the folder forever.
+ * The obvious test — "same size twice AND non-empty" — treats a genuinely empty file as
+ * permanently mid-copy: it is never handled, never deleted, and so the dropzone never empties,
+ * which is the one outcome the owner's brief measures success by (*"in the end there should be
+ * nothing left"*). Measured on a first run: three real files, all 0 bytes, reported as "still
+ * copying" on every sweep for as long as they sat there.
+ *
+ * Emptiness is only evidence of an unfinished copy while the file is NEW, so age decides. A
+ * file created a minute ago with no bytes in it is empty, not arriving.
+ */
+export async function isStable(file, stabilityMs = 750) {
+    await new Promise((resolve) => setTimeout(resolve, stabilityMs));
+    try {
+        const now = await stat(file.path);
+        if (now.size !== file.size)
+            return false; // still growing
+        if (now.size > 0)
+            return true;
+        return Date.now() - now.mtimeMs > EMPTY_FILE_GRACE_MS;
+    }
+    catch {
+        return false; // taken by something else, or never really there
+    }
+}
+/**
+ * Remove directories left empty by a sweep, deepest first — and never the root.
+ *
+ * 🔴 `rmdir` refuses a non-empty directory, and that refusal IS the safety property. A
+ * recursive delete here would take a file the sweep deliberately chose not to ingest — a held
+ * duplicate, a failure left in place for the owner to look at — which is precisely the set of
+ * files that must survive.
+ */
+export async function pruneEmptyDirs(root, dir = root) {
+    let removed = 0;
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return 0;
+    }
+    for (const name of entries) {
+        const full = join(dir, name);
+        try {
+            if ((await stat(full)).isDirectory())
+                removed += await pruneEmptyDirs(root, full);
+        }
+        catch {
+            /* gone */
+        }
+    }
+    if (dir === root)
+        return removed;
+    try {
+        await rmdir(dir);
+        return removed + 1;
+    }
+    catch {
+        return removed; // not empty — the right outcome, and not an error
+    }
+}
+/**
+ * Walk a dropzone, hand every file to `handle`, and leave nothing behind that was dealt with.
+ *
+ * 🔴 The DELETION is here, and it is deliberately not the handler's job. Every app would
+ * otherwise reimplement rule 1, and the one that got it wrong would lose the owner's only copy
+ * silently. A handler says what happened; this decides what that means for the file on disk.
+ */
+export async function sweepDropzone(root, handle, opts = {}) {
+    const report = {
+        scanned: 0,
+        stored: 0,
+        duplicate: 0,
+        discarded: 0,
+        held: 0,
+        failed: [],
+        unstable: [],
+        bytesRemoved: 0,
+        emptyDirsRemoved: 0,
+        remaining: 0,
+    };
+    const files = await scanDropzone(root, opts);
+    for (const [index, file] of files.entries()) {
+        report.scanned++;
+        opts.onProgress?.(index + 1, files.length);
+        if (!(await isStable(file, opts.stabilityMs))) {
+            report.unstable.push(file.relativePath);
+            continue;
+        }
+        let outcome;
+        try {
+            outcome = opts.dryRun ? { kind: "held", detail: "dry run" } : await handle(file);
+        }
+        catch (error) {
+            // Rule 3: a handler that throws costs one file, never the sweep.
+            outcome = {
+                kind: "failed",
+                detail: error instanceof Error ? error.message : String(error),
+            };
+        }
+        switch (outcome.kind) {
+            case "stored":
+            case "duplicate":
+            case "discard": {
+                if (outcome.kind === "stored")
+                    report.stored++;
+                else if (outcome.kind === "duplicate")
+                    report.duplicate++;
+                else
+                    report.discarded++;
+                if (opts.dryRun)
+                    break;
+                try {
+                    await rm(file.path);
+                    report.bytesRemoved += file.size;
+                }
+                catch (error) {
+                    // The bytes are safe at the destination; only the tidying failed. Reporting it
+                    // as a FAILURE would send the owner looking for a file that arrived perfectly.
+                    report.failed.push({
+                        relativePath: file.relativePath,
+                        error: `filed, but the original could not be removed: ${error instanceof Error ? error.message : String(error)}`,
+                    });
+                }
+                break;
+            }
+            case "held":
+                report.held++;
+                break;
+            case "failed":
+                report.failed.push({ relativePath: file.relativePath, error: outcome.detail });
+                break;
+        }
+    }
+    if (!opts.dryRun)
+        report.emptyDirsRemoved = await pruneEmptyDirs(root);
+    report.remaining = (await scanDropzone(root, { skipDirs: opts.skipDirs })).length;
+    return report;
+}
+/** A one-line summary — every consumer prints one, and they should read alike. */
+export const describeSweep = (report) => `${report.stored} added, ${report.duplicate} already had, ${report.discarded} discarded, ` +
+    `${report.held} held, ${report.failed.length} failed, ${report.unstable.length} still copying` +
+    (report.bytesRemoved > 0
+        ? ` · ${(report.bytesRemoved / 1024 ** 3).toFixed(2)} GB freed from the queue`
+        : "") +
+    (report.remaining > 0 ? ` · ${report.remaining} left in the folder` : " · folder is empty");

package/dist/server/errors.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Server-side re-export of the canonical error primitives, which now live in the
+ * framework-free {@link ../shared/errors} module so cursedshell's plugin-pure layer
+ * can import the SAME `ApiError` + envelope without pulling any server code
+ * (`cursedbelt-core/errors` subpath). Server modules keep importing from `./errors`.
+ */
+export { AppError, type AppErrorSummary, ApiError, type ApiErrorOptions, type ErrorEnvelope, isAppError, isApiError, type ToErrorEnvelopeOptions, toErrorEnvelope, type ValidationIssue, VALIDATION_ERROR_CODE, VALIDATION_STATUS, toValidationIssues, validationEnvelope, } from 'cursedbelt-core/errors';

package/dist/server/errors.js

@@ -0,0 +1,7 @@
+/**
+ * Server-side re-export of the canonical error primitives, which now live in the
+ * framework-free {@link ../shared/errors} module so cursedshell's plugin-pure layer
+ * can import the SAME `ApiError` + envelope without pulling any server code
+ * (`cursedbelt-core/errors` subpath). Server modules keep importing from `./errors`.
+ */
+export { AppError, ApiError, isAppError, isApiError, toErrorEnvelope, VALIDATION_ERROR_CODE, VALIDATION_STATUS, toValidationIssues, validationEnvelope, } from 'cursedbelt-core/errors';

package/dist/server/guard/argon2Binding.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Wiring a REAL argon2id into the KDF seam (01 §3.3/§3.4, finding 1.2).
+ *
+ * cwip ships no KDF — it is zero-dependency by contract — so
+ * `setArgon2idDeriver` sat inert: nothing registered a binding, and every
+ * `unlock()` would have thrown `GUARD_KDF_UNAVAILABLE` the first time a real
+ * user tried it in production. `assertArgon2idReady()` converts that into a boot
+ * failure; this module is the other half — the adapter that makes registering a
+ * binding a one-liner, and the reason a host has no excuse to hand-roll one.
+ *
+ * The requirements on a binding are not negotiable, and the adapter enforces
+ * them rather than documenting them:
+ *
+ *   * **Raw bytes out.** A binding that returns a PHC/base64 STRING is a
+ *     `key-material-as-string` violation regardless of how strong the KDF is —
+ *     a JS string is immutable and GC-managed, so the key lingers in
+ *     unallocated RAM until the collector happens to overwrite it.
+ *   * **Caller-supplied salt.** Anything that generates its own salt (e.g.
+ *     `Bun.password`) cannot re-derive the key for an existing envelope, so it
+ *     cannot open a secret it sealed yesterday.
+ *   * **Synchronous.** The seam is sync on purpose and its throughput ceiling is
+ *     documented on `Argon2idDeriver`; an async binding would hand back a
+ *     promise AND (usually) a string.
+ */
+import { type Argon2idDeriver } from 'cwip/guard';
+/**
+ * The shape of a raw, synchronous argon2id binding, in the REFERENCE
+ * implementation's vocabulary: `algorithm` is the argon2 variant number
+ * (2 = argon2id) and `version` is the argon2 algorithm version as the spec
+ * writes it (`0x10` / `0x13`) — the same number the envelope's `kdf.ver`
+ * records.
+ *
+ * `@node-rs/argon2`'s `hashRawSync` is shape-compatible but NOT
+ * vocabulary-compatible: its `version` is a NAPI enum (`Version.V0x10 = 0`,
+ * `Version.V0x13 = 1`), so handing it `0x13` is an `InvalidArg` throw on every
+ * single derivation. {@link nodeRsArgon2idBinding} is the (tiny) translation,
+ * and {@link registerNodeRsArgon2id} applies it — libsodium's `crypto_pwhash`
+ * needs a comparable shim.
+ */
+export interface RawArgon2idBinding {
+    hashRawSync(password: Uint8Array, options: {
+        salt: Uint8Array;
+        /** Memory cost in KiB. */
+        memoryCost: number;
+        /** Time cost (iterations). */
+        timeCost: number;
+        /** Parallelism (lanes). */
+        parallelism: number;
+        /** Output length in bytes. */
+        outputLen: number;
+        /** argon2 variant: 2 = argon2id. */
+        algorithm?: number;
+        /** argon2 algorithm version (0x10 | 0x13). */
+        version?: number;
+    }): Uint8Array;
+}
+/** argon2id's variant number in the `@node-rs/argon2` / reference-implementation vocabulary. */
+export declare const ARGON2ID_ALGORITHM = 2;
+/**
+ * Build a deriver from a raw binding, checking the two properties that make it
+ * usable as key material. The length check is not paranoia: a binding that
+ * silently truncates would weaken every secret sealed under it, and the failure
+ * would look like nothing at all.
+ */
+export declare const argon2idDeriverFrom: (binding: RawArgon2idBinding) => Argon2idDeriver;
+/**
+ * Translate a `@node-rs/argon2` module into a {@link RawArgon2idBinding}.
+ *
+ * The whole translation is the `version` field, and skipping it is not a
+ * cosmetic bug: node-rs validates the enum, so an unmapped `0x13` throws
+ * `InvalidArg` from the native layer on EVERY derivation — the first unlock, the
+ * first login, every password verify. That failure is invisible until a host
+ * actually registers this binding, which is exactly what the local host now does
+ * at boot.
+ */
+export declare const nodeRsArgon2idBinding: (module: RawArgon2idBinding) => RawArgon2idBinding;
+/** Register a raw binding as the process-wide deriver, then prove the seam is armed. */
+export declare const registerArgon2idBinding: (binding: RawArgon2idBinding) => void;
+/**
+ * Register `@node-rs/argon2` if the host installed it.
+ *
+ * It is an OPTIONAL peer dependency: a generated app with no GuardEngine surface
+ * should not carry a native module, and an app that has one must make the choice
+ * explicitly. The specifier is held in a variable so bundlers and `tsc` do not
+ * try to resolve a package that may not be there.
+ *
+ * @throws {AppError} `GUARD_KDF_BINDING_MISSING` naming the install command —
+ * an unhelpful `ERR_MODULE_NOT_FOUND` at boot is exactly the failure this
+ * module exists to prevent.
+ *
+ * The same indirection that hides the specifier from a bundler hides it from
+ * every static import walker, so the guard's peer map would report
+ * this edge as absent. The pragma is what puts it back.
+ *
+ * @peer @node-rs/argon2
+ */
+export declare const registerNodeRsArgon2id: () => Promise<void>;

package/dist/server/guard/argon2Binding.js

@@ -0,0 +1,138 @@
+/**
+ * Wiring a REAL argon2id into the KDF seam (01 §3.3/§3.4, finding 1.2).
+ *
+ * cwip ships no KDF — it is zero-dependency by contract — so
+ * `setArgon2idDeriver` sat inert: nothing registered a binding, and every
+ * `unlock()` would have thrown `GUARD_KDF_UNAVAILABLE` the first time a real
+ * user tried it in production. `assertArgon2idReady()` converts that into a boot
+ * failure; this module is the other half — the adapter that makes registering a
+ * binding a one-liner, and the reason a host has no excuse to hand-roll one.
+ *
+ * The requirements on a binding are not negotiable, and the adapter enforces
+ * them rather than documenting them:
+ *
+ *   * **Raw bytes out.** A binding that returns a PHC/base64 STRING is a
+ *     `key-material-as-string` violation regardless of how strong the KDF is —
+ *     a JS string is immutable and GC-managed, so the key lingers in
+ *     unallocated RAM until the collector happens to overwrite it.
+ *   * **Caller-supplied salt.** Anything that generates its own salt (e.g.
+ *     `Bun.password`) cannot re-derive the key for an existing envelope, so it
+ *     cannot open a secret it sealed yesterday.
+ *   * **Synchronous.** The seam is sync on purpose and its throughput ceiling is
+ *     documented on `Argon2idDeriver`; an async binding would hand back a
+ *     promise AND (usually) a string.
+ */
+import { assertArgon2idReady, CC_ARGON2ID_VERSION, setArgon2idDeriver, } from 'cwip/guard';
+import { AppError } from '../errors';
+/** argon2id's variant number in the `@node-rs/argon2` / reference-implementation vocabulary. */
+export const ARGON2ID_ALGORITHM = 2;
+/**
+ * Build a deriver from a raw binding, checking the two properties that make it
+ * usable as key material. The length check is not paranoia: a binding that
+ * silently truncates would weaken every secret sealed under it, and the failure
+ * would look like nothing at all.
+ */
+export const argon2idDeriverFrom = (binding) => {
+    return (input) => {
+        const output = binding.hashRawSync(input.password, {
+            salt: input.salt,
+            memoryCost: input.params.m,
+            timeCost: input.params.t,
+            parallelism: input.params.p,
+            outputLen: input.keyLength,
+            algorithm: ARGON2ID_ALGORITHM,
+            // Honor the version the ENVELOPE was sealed with, not the binding's
+            // compile-time default: 0x10 and 0x13 produce different bytes for
+            // identical m/t/p/salt/password, which is why the envelope records it.
+            version: input.version ?? CC_ARGON2ID_VERSION,
+        });
+        if (typeof output === 'string')
+            throw new AppError('The registered argon2id binding returned a string. Key material must be raw bytes — a string cannot be zeroized (01 §3.4).', { code: 'GUARD_KDF_BINDING_INVALID', status: 500, category: 'security', isOperational: false });
+        if (!(output instanceof Uint8Array))
+            throw new AppError('The registered argon2id binding did not return a Uint8Array.', {
+                code: 'GUARD_KDF_BINDING_INVALID',
+                status: 500,
+                category: 'security',
+                isOperational: false,
+            });
+        return output;
+    };
+};
+/**
+ * `@node-rs/argon2`'s `Version` enum, keyed by the argon2 version number the
+ * ENVELOPE records. Held here rather than imported so the adapter never has to
+ * load the optional native module to know how to talk to it.
+ */
+// 0x10 and 0x13 ARE the Argon2 version identifiers: the spec, the reference
+// implementation and every envelope on disk write them in hex. Biome's autofix
+// rewrites them as 16 and 19 — the same map and a worse one, because nobody
+// reading an `$argon2id$v=19$` record would recognise the decimal.
+// biome-ignore lint/complexity/useSimpleNumberKeys: see above — hex IS the spec's spelling
+const NODE_RS_VERSION = { 0x10: 0, 0x13: 1 };
+/**
+ * Translate a `@node-rs/argon2` module into a {@link RawArgon2idBinding}.
+ *
+ * The whole translation is the `version` field, and skipping it is not a
+ * cosmetic bug: node-rs validates the enum, so an unmapped `0x13` throws
+ * `InvalidArg` from the native layer on EVERY derivation — the first unlock, the
+ * first login, every password verify. That failure is invisible until a host
+ * actually registers this binding, which is exactly what the local host now does
+ * at boot.
+ */
+export const nodeRsArgon2idBinding = (module) => ({
+    hashRawSync(password, options) {
+        const declared = options.version ?? CC_ARGON2ID_VERSION;
+        const mapped = NODE_RS_VERSION[declared];
+        if (mapped === undefined)
+            throw new AppError(`argon2 version 0x${declared.toString(16)} is not one @node-rs/argon2 implements (0x10 or 0x13). The envelope asking for it cannot be opened by this binding — reseal it, or register a binding that supports the version.`, {
+                code: 'GUARD_KDF_BINDING_INVALID',
+                status: 500,
+                category: 'security',
+                isOperational: false,
+                context: { version: declared },
+            });
+        return module.hashRawSync(password, { ...options, version: mapped });
+    },
+});
+/** Register a raw binding as the process-wide deriver, then prove the seam is armed. */
+export const registerArgon2idBinding = (binding) => {
+    setArgon2idDeriver(argon2idDeriverFrom(binding));
+    // Fail here rather than at the first unlock: this call is the whole point.
+    assertArgon2idReady();
+};
+/**
+ * Register `@node-rs/argon2` if the host installed it.
+ *
+ * It is an OPTIONAL peer dependency: a generated app with no GuardEngine surface
+ * should not carry a native module, and an app that has one must make the choice
+ * explicitly. The specifier is held in a variable so bundlers and `tsc` do not
+ * try to resolve a package that may not be there.
+ *
+ * @throws {AppError} `GUARD_KDF_BINDING_MISSING` naming the install command —
+ * an unhelpful `ERR_MODULE_NOT_FOUND` at boot is exactly the failure this
+ * module exists to prevent.
+ *
+ * The same indirection that hides the specifier from a bundler hides it from
+ * every static import walker, so the guard's peer map would report
+ * this edge as absent. The pragma is what puts it back.
+ *
+ * @peer @node-rs/argon2
+ */
+export const registerNodeRsArgon2id = async () => {
+    const specifier = '@node-rs/argon2';
+    let loaded;
+    try {
+        loaded = (await import(specifier));
+    }
+    catch (cause) {
+        throw new AppError('GuardEngine needs an argon2id binding and `@node-rs/argon2` is not installed. Run `bun add @node-rs/argon2` in the app, or call registerArgon2idBinding(...) with your own raw, synchronous binding.', { code: 'GUARD_KDF_BINDING_MISSING', status: 500, category: 'security', isOperational: false, cause });
+    }
+    if (typeof loaded.hashRawSync !== 'function')
+        throw new AppError('`@node-rs/argon2` is installed but exposes no `hashRawSync` — it is too old for the raw-bytes seam.', {
+            code: 'GUARD_KDF_BINDING_INVALID',
+            status: 500,
+            category: 'security',
+            isOperational: false,
+        });
+    registerArgon2idBinding(nodeRsArgon2idBinding(loaded));
+};

package/dist/server/guard/index.d.ts

@@ -0,0 +1,4 @@
+export * from './argon2Binding';
+export * from './verifier';
+export * from './revocationStore';
+export * from './sessionSigner';

package/dist/server/guard/index.js

@@ -0,0 +1,6 @@
+// The GuardEngine server wiring (02 §4): the argon2id binding adapter that arms
+// cwip's KDF seam, and the Ed25519 session signer that mints and revokes.
+export * from './argon2Binding';
+export * from './verifier';
+export * from './revocationStore';
+export * from './sessionSigner';

package/dist/server/guard/kdfWorker.d.ts

@@ -0,0 +1,101 @@
+import { createInProcessPasswordVerifier, type PasswordVerifierPort } from './passwordVerifier';
+/** Raised when the worker thread dies, fails to start, or is disposed mid-flight. */
+export declare const GUARD_KDF_WORKER_FAILED = "GUARD_KDF_WORKER_FAILED";
+/** Raised when the worker does not answer within the configured budget. */
+export declare const GUARD_KDF_WORKER_TIMEOUT = "GUARD_KDF_WORKER_TIMEOUT";
+/**
+ * Default per-request ceiling. Generous relative to a ~250 ms derivation on
+ * purpose: this is a liveness backstop for a wedged thread, not a latency SLO,
+ * and a tight budget here would turn a loaded machine into a login outage.
+ */
+export declare const KDF_WORKER_DEFAULT_TIMEOUT_MS = 15000;
+export type KdfWorkerRequest = {
+    id: number;
+    kind: 'seal';
+    userId: string;
+    password: Uint8Array;
+} | {
+    id: number;
+    kind: 'verify';
+    userId: string;
+    envelopeJson: string;
+    password: Uint8Array;
+};
+export type KdfWorkerResponse = {
+    id: number;
+    ok: true;
+    value: string | boolean;
+} | {
+    id: number;
+    ok: false;
+    code: string;
+    message: string;
+};
+/** The subset of a worker-thread global this module needs, in either runtime. */
+interface WorkerScope {
+    postMessage(data: unknown): void;
+    onMessage(handler: (data: unknown) => void): void;
+}
+/**
+ * Run the KDF worker's message loop. A worker entry module is this call and
+ * nothing else (see `kdfWorkerEntry.ts`).
+ *
+ * `register` is injectable so the spec can drive the loop with a cheap fake
+ * binding — registering the real native argon2 in a test that only checks
+ * message plumbing would pay 250 ms per case to prove nothing about the
+ * plumbing. The DEFAULT is the real binding, because a worker that silently ran
+ * a fake KDF would be a catastrophe rather than a bug.
+ */
+export declare function serveKdfWorker(options?: {
+    scope?: WorkerScope;
+    register?: () => Promise<void>;
+}): Promise<void>;
+/**
+ * The subset of both runtimes' Worker the client needs.
+ *
+ * `post` RESOLVES ONCE THE DATA HAS BEEN HANDED TO THE THREAD, and that is not a
+ * stylistic choice. A worker is constructed asynchronously, so early requests
+ * are queued; the queue holds the caller's `Uint8Array` by reference. A client
+ * that zeroized the password right after a fire-and-forget `post()` would blank
+ * the buffer the queue is still holding, and the worker would then derive a key
+ * from 32 zero bytes — accepting every wrong password that happened to be
+ * presented during startup. Awaiting the post is what makes "zeroize as early as
+ * possible" and "send the real bytes" compatible.
+ */
+interface HostWorker {
+    post(data: unknown): Promise<void>;
+    onMessage(handler: (data: unknown) => void): void;
+    onError(handler: (error: unknown) => void): void;
+    terminate(): void;
+}
+export interface KdfWorkerOptions {
+    /** Module specifier / URL of an entry that calls {@link serveKdfWorker}. */
+    entry: string | URL;
+    /** Per-request ceiling. Defaults to {@link KDF_WORKER_DEFAULT_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Spawn override — the spec uses it to drive the protocol without a real thread. */
+    spawn?: (entry: string | URL) => HostWorker;
+}
+/**
+ * A {@link PasswordVerifierPort} backed by one long-lived worker thread.
+ *
+ * Hand it to `createAccountService({ passwords })` on a host that expects login
+ * concurrency. Local single-user hosts should NOT — they would pay a thread and
+ * a native module load to serialize a workload that was never contended.
+ */
+export declare function createKdfWorkerPasswordVerifier(options: KdfWorkerOptions): PasswordVerifierPort;
+/**
+ * The URL of the entry module {@link createKdfWorkerPasswordVerifier} spawns.
+ *
+ * Resolved relative to THIS module rather than hard-coded by the host, so an app
+ * never has to know where inside the package the entry lives:
+ *
+ *   createKdfWorkerPasswordVerifier({ entry: kdfWorkerEntryUrl() })
+ *
+ * Under the `bun` export condition this resolves to the TypeScript source, which
+ * is what every first-party consumer runs (see the monorepo's zero-build-lag
+ * contract). A non-Bun host consuming built `dist/` names its own built entry.
+ */
+export declare const kdfWorkerEntryUrl: () => URL;
+/** Re-exported so a host wiring the guard tier needs one import. */
+export { createInProcessPasswordVerifier, type PasswordVerifierPort };