waterplane 0.0.1 → 0.1.11

package/packages/host/dist/auth.js

@@ -0,0 +1,276 @@
+/**
+ * LAN password gate. waterplane's boundary is normally the Tailscale network identity
+ * (loopback + Tailscale peers are trusted). When the LAN interface is bound
+ * (WATERPLANE_ALLOW_PUBLIC=1) that boundary is gone for same-WiFi devices, so those
+ * connections get password-gated here. The password is managed ONLY from the
+ * trusted path (loopback / Tailscale) — a LAN caller can never set or change it.
+ *
+ * Model:
+ *   - loopback  → always trusted (this is the management path; never gated).
+ *   - tailscale → trusted, UNLESS `gateTailscale` is on (defense-in-depth toggle).
+ *   - lan/other → always needs a valid token; if no password is set, no token can
+ *                 be valid, so LAN is denied outright ("deny until set").
+ *
+ * Tokens are per-DEVICE rows in the paired-device ledger (`deviceledger.ts`,
+ * `.waterplane/devices.json`, sha256 at rest), so they survive a host restart and each
+ * one can be revoked on its own. A browser gets one after a correct password, as
+ * an httpOnly cookie; the Android shell (whose cross-site cookie is withheld)
+ * mints one over the trusted path (`POST /api/auth/token`) and carries it as
+ * `Authorization: Bearer` on fetch and as the `<wsProtocol>-tok.<tok>` WebSocket
+ * subprotocol on the upgrade — `tokenFromRequest` reads all three.
+ * Changing/clearing the password drops every row — every gated device is
+ * logged out. No token is valid while no password is set (deny-until-set).
+ */
+import { randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+import { readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { readJsonGuardedDetail, writeJsonAtomic } from "./jsonstore.js";
+import { peerKind } from "./net.js";
+import { DeviceLedger } from "./deviceledger.js";
+import { PassiveGate } from "./passive.js";
+import { BRAND, LEGACY } from "@waterplane/shared";
+import { hostStateDir } from "./branddirs.js";
+export const AUTH_COOKIE = BRAND.cookie;
+/** Cookies set by past identities: still READ, so a paired browser stays signed in across the rename. */
+const LEGACY_AUTH_COOKIES = LEGACY.map((l) => l.cookie);
+/** The cookie's lifetime in the browser. The token itself lives until it is
+ *  revoked or the password changes. */
+const TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+const MIN_LEN = 8;
+/** The feed row for an `auth.json` that was unreadable at boot (`AuthManager.lost`). */
+export function authLostNotice(lost) {
+    return {
+        title: "Host password file was unreadable",
+        body: "auth.json could not be read at start-up, so this host has no password: every LAN device is refused until one is set again. " +
+            (lost.tailscaleGated
+                ? "It may have required the password from Tailscale too, so Tailscale devices are refused as well; set the password again on the desktop itself (loopback). "
+                : "Set the password again from Settings if you use LAN access. ") +
+            (lost.movedTo ? `The damaged file is kept as ${lost.movedTo}.` : "The file could not be moved aside."),
+        tag: "auth-lost",
+    };
+}
+export class AuthManager {
+    file;
+    stored = null;
+    /**
+     * Set when `auth.json` was PRESENT and unreadable at boot: where its bytes went,
+     * and whether Tailscale stays gated. Deny-until-set already keeps every LAN peer
+     * out with no password; the one thing a lost file could OPEN is the
+     * `gateTailscale` defense-in-depth toggle, so when the damaged bytes mention it
+     * (or could not be read at all) Tailscale is refused too until a person sets or
+     * clears the password from the desktop (loopback is never gated). Fail closed.
+     */
+    lost = null;
+    /** Every issued token, hashed, one row per device. Survives restarts. */
+    devices;
+    /** Passive devices' PIN and unlocks (`passive.ts`). */
+    passive;
+    constructor(root) {
+        this.file = join(hostStateDir(root), "auth.json");
+        this.devices = new DeviceLedger(root);
+        this.passive = new PassiveGate(root);
+        // Guarded: a corrupt auth.json is moved aside and logged (never silently
+        // overwritten by the next save). The fallback is "no password", which is
+        // still deny-until-set for every LAN peer — the gate never opens on a loss.
+        const isStored = (v) => !!v && typeof v.salt === "string" && typeof v.hash === "string";
+        const read = readJsonGuardedDetail(this.file, null, isStored);
+        this.stored = read.value;
+        if (read.corrupt) {
+            let bytes = null;
+            try {
+                bytes = read.corrupt.movedTo ? readFileSync(read.corrupt.movedTo, "utf8") : null;
+            }
+            catch {
+                bytes = null;
+            }
+            const tailscaleGated = bytes === null || /gateTailscale/.test(bytes);
+            this.lost = { movedTo: read.corrupt.movedTo, error: read.corrupt.error, tailscaleGated };
+        }
+    }
+    /** Tailscale is held gated by a lost file (see `lost`) until a person decides. */
+    lockedTailscale() { return !!this.lost?.tailscaleGated; }
+    persist() {
+        if (!this.stored) {
+            try {
+                rmSync(this.file, { force: true });
+            }
+            catch { /* nothing to remove */ }
+            return;
+        }
+        // Atomic: an in-place write truncated by a kill left a file that parsed as
+        // "no password" on the next boot. 0600 from the first byte.
+        writeJsonAtomic(this.file, this.stored, { mode: 0o600 });
+    }
+    isEnabled() { return !!this.stored; }
+    /** On when switched on, when a lost file holds it, and while ANY passive
+     *  device is paired: a passive phone must have no tokenless path on any
+     *  network (R-connection-012), Tailscale included. */
+    gateTailscale() { return !!this.stored?.gateTailscale || this.lockedTailscale() || (this.isEnabled() && this.devices.hasPassive()); }
+    /** Set (or replace) the password. Rotates all tokens — every device re-logs. */
+    setPassword(pw) {
+        if (!pw || pw.length < MIN_LEN)
+            throw new Error(`password too short (min ${MIN_LEN})`);
+        const salt = randomBytes(16).toString("hex");
+        const hash = scryptSync(pw, salt, 32).toString("hex");
+        // A file lost while it may have gated Tailscale keeps that gate on: turning
+        // it off is a separate, explicit tap.
+        const gate = this.stored?.gateTailscale || this.lockedTailscale();
+        this.stored = gate ? { salt, hash, gateTailscale: true } : { salt, hash };
+        if (this.lost)
+            this.lost = { ...this.lost, tailscaleGated: false };
+        this.devices.clear();
+        this.persist();
+    }
+    clearPassword() {
+        this.stored = null;
+        if (this.lost)
+            this.lost = { ...this.lost, tailscaleGated: false };
+        this.devices.clear();
+        this.persist();
+    }
+    setGateTailscale(on) {
+        if (!this.stored)
+            return; // meaningless without a password
+        if (!on && this.devices.hasPassive()) {
+            throw new Error("A passive device is paired, so Tailscale stays gated — otherwise it could reach everything without its token. Revoke the passive device first.");
+        }
+        this.stored.gateTailscale = on;
+        if (!on)
+            delete this.stored.gateTailscale;
+        this.persist();
+    }
+    verify(pw) {
+        if (!this.stored || !pw)
+            return false;
+        const got = scryptSync(pw, this.stored.salt, 32);
+        const want = Buffer.from(this.stored.hash, "hex");
+        return got.length === want.length && timingSafeEqual(got, want);
+    }
+    /** Mint a token for a new device row. Callers decide WHO may (a correct
+     *  password, or an already-trusted caller); this only refuses while no
+     *  password is set, because such a token could never pass the gate. */
+    issueToken(deviceName, kind, scope) {
+        if (!this.isEnabled())
+            throw new Error("no password set on host");
+        const { token, row } = this.devices.mint(deviceName, kind, Date.now(), scope);
+        // A passive device switches the Tailscale gate on for good (R-connection-012):
+        // stored, so it stays on after the passive row is revoked until a person
+        // switches it off.
+        if (scope === "passive" && this.stored && !this.stored.gateTailscale) {
+            this.stored.gateTailscale = true;
+            this.persist();
+        }
+        return { token, deviceId: row.id };
+    }
+    /** The device a token belongs to, or null. Null for every token while no
+     *  password is set. With `kind`, also notes the device as seen (throttled). */
+    deviceFor(tok, kind) {
+        if (!tok || !this.isEnabled())
+            return null;
+        const row = this.devices.lookup(tok);
+        if (row && kind)
+            this.devices.touch(row.id, kind);
+        return row;
+    }
+    /** The token is a passive one and not unlocked right now: the allowlist applies. */
+    restricted(tok) {
+        return this.passive.restricted(this.deviceFor(tok));
+    }
+    checkToken(tok, kind) {
+        return this.deviceFor(tok, kind) !== null;
+    }
+    /** Log a token out: its device row is deleted. */
+    revoke(tok) {
+        const row = tok ? this.devices.lookup(tok) : null;
+        if (row)
+            this.devices.revoke(row.id);
+    }
+    /** Whether a connection from `kind` must present a valid token to proceed. */
+    needsToken(kind) {
+        if (kind === "loopback")
+            return false;
+        if (kind === "tailscale")
+            return (this.isEnabled() && this.gateTailscale()) || this.lockedTailscale();
+        return true; // lan / public / unknown — no password set ⇒ can't pass ⇒ denied
+    }
+    /** Whether a connection from `kind` may set/change/clear the password. Only the
+     *  trusted path (loopback + Tailscale peers) manages auth — never LAN. */
+    canManage(kind) {
+        return kind === "loopback" || kind === "tailscale";
+    }
+}
+/** The WebSocket subprotocol prefix that carries a device token on the upgrade
+ *  (a browser WebSocket can set no other header). */
+export const WS_TOKEN_PROTOCOL_PREFIX = `${BRAND.wsProtocol}-tok.`;
+/** Past identities' prefixes: an installed APK / cached bundle still offers one. */
+const LEGACY_WS_TOKEN_PREFIXES = LEGACY.map((l) => `${l.wsProtocol}-tok.`);
+const WS_TOKEN_PREFIXES = [WS_TOKEN_PROTOCOL_PREFIX, ...LEGACY_WS_TOKEN_PREFIXES];
+/** Split a `Sec-WebSocket-Protocol` header into its offered protocols. */
+function wsProtocols(h) {
+    const all = Array.isArray(h) ? h.join(",") : (h ?? "");
+    return all.split(",").map((p) => p.trim()).filter(Boolean);
+}
+function bearer(h) {
+    const m = /^Bearer\s+([A-Za-z0-9._~+/=-]{1,256})\s*$/i.exec(h ?? "");
+    return m ? m[1] : null;
+}
+/**
+ * The token a request carries, first found wins: the `BRAND.cookie` cookie (the
+ * browser PWA), then `Authorization: Bearer <tok>` (the Android shell's fetch),
+ * then a `<wsProtocol>-tok.<tok>` WebSocket subprotocol (its socket). Null when none.
+ * Only ever an opaque string — validity is `AuthManager.deviceFor`'s question.
+ */
+export function tokenFromRequest(headers) {
+    const c = cookieToken(headers.cookie);
+    if (c)
+        return c;
+    const b = bearer(headers.authorization);
+    if (b)
+        return b;
+    for (const p of wsProtocols(headers["sec-websocket-protocol"])) {
+        for (const pre of WS_TOKEN_PREFIXES) {
+            if (p.startsWith(pre) && p.length > pre.length)
+                return p.slice(pre.length);
+        }
+    }
+    return null;
+}
+/**
+ * `WebSocketServer`'s `handleProtocols`: answer with the first offered protocol
+ * that is NOT a token carrier (the phone offers `[<wsProtocol>, "<wsProtocol>-tok.<tok>"]`
+ * and gets the base protocol back (an older client offers its own name; any non-token one is echoed)), so the token is never echoed in a response header.
+ * Nothing but a token offered ⇒ `false`, no protocol selected — and a browser
+ * then fails the handshake, which is why the client must offer a base protocol.
+ */
+export function selectWsProtocol(protocols) {
+    for (const p of protocols)
+        if (!WS_TOKEN_PREFIXES.some((pre) => p.startsWith(pre)))
+            return p;
+    return false;
+}
+/** Pull the auth token out of a request's Cookie header. */
+export function cookieToken(cookieHeader) {
+    if (!cookieHeader)
+        return null;
+    for (const part of cookieHeader.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq === -1)
+            continue;
+        const name = part.slice(0, eq).trim();
+        if (name === AUTH_COOKIE || LEGACY_AUTH_COOKIES.includes(name))
+            return part.slice(eq + 1).trim();
+    }
+    return null;
+}
+/** Build the Set-Cookie header value for a freshly issued token. Not `Secure` —
+ *  LAN access is plain HTTP; `HttpOnly` keeps it out of page JS, `SameSite=Lax`
+ *  is enough for same-origin fetch + WS upgrade. */
+export function authCookie(tok) {
+    return `${AUTH_COOKIE}=${tok}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${Math.floor(TOKEN_TTL_MS / 1000)}`;
+}
+export function clearAuthCookie() {
+    // Expire the legacy-named cookies too, so a logout really logs the browser out.
+    return [AUTH_COOKIE, ...LEGACY_AUTH_COOKIES].map((n) => `${n}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`);
+}
+export { peerKind };
+//# sourceMappingURL=auth.js.map

package/packages/host/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/packages/host/dist/authroutes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The HTTP routes of the LAN identity and the paired-device ledger:
+ *
+ *   GET  /api/lan/identity        loopback/Tailscale ONLY (403 otherwise, even
+ *                                 with a token), then the normal gate
+ *   POST /api/lan/verify {nonce}  PRE-auth, rate-limited per remote IP
+ *   GET  /api/devices             authed; `current` marks the caller's row
+ *   POST /api/devices/revoke {id} authed; deletes the row, closes its sockets
+ *
+ * `server/http.ts` calls `handleLanPreAuth` ahead of the auth gate (the
+ * identity scope check and verify) and `handleAuthedRoutes` behind it. Kept
+ * flat and handed its deps, like `api.ts`, so it never reaches `server/ctx`.
+ * Pairing routes (P2) hook in beside these in `server/http.ts`, and reuse
+ * `ratelimit.ts` for their own pre-auth redeem.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type PeerKind } from "@waterplane/shared";
+import type { AuthManager } from "./auth.js";
+export interface AuthRouteDeps {
+    root: string;
+    auth: AuthManager;
+    /** Close a revoked device's live sockets; how many. */
+    closeDevice(id: string): number;
+}
+/** Only these peers may learn the identity secret: it is what lets a phone
+ *  trust a LAN address, so it must come over a path that is already trusted. */
+export declare function mayReadLanIdentity(kind: PeerKind): boolean;
+/**
+ * Before the auth gate. Returns true when it answered. The identity route is
+ * REFUSED here for every other peer kind — a LAN token does not unlock it — and
+ * otherwise left for `handleAuthedRoutes`, so a gated Tailscale peer still
+ * needs its token.
+ */
+export declare function handleLanPreAuth(req: IncomingMessage, res: ServerResponse, kind: PeerKind, deps: AuthRouteDeps): Promise<boolean>;
+/** Behind the auth gate: the caller is trusted or holds a valid token. */
+export declare function handleAuthedRoutes(req: IncomingMessage, res: ServerResponse, kind: PeerKind, tok: string | null, deps: AuthRouteDeps): Promise<boolean>;

package/packages/host/dist/authroutes.js

@@ -0,0 +1,108 @@
+import { isDeviceId, } from "@waterplane/shared";
+import { lanIdentity, lanMac, validNonce } from "./lanid.js";
+import { hostName } from "./net.js";
+import { RateLimiter, rateKey } from "./ratelimit.js";
+import { corsHeaders } from "./origin.js";
+/** 10 verifies in a burst, then one every 2 s, per remote IP: a phone asks
+ *  once per LAN connect, a scanner gets nowhere fast. */
+const verifyLimit = new RateLimiter({ burst: 10, perSec: 0.5 });
+/** Only these peers may learn the identity secret: it is what lets a phone
+ *  trust a LAN address, so it must come over a path that is already trusted. */
+export function mayReadLanIdentity(kind) {
+    return kind === "loopback" || kind === "tailscale";
+}
+function reply(req, res, status, body, extra = {}) {
+    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store", ...corsHeaders(req.headers), ...extra });
+    res.end(JSON.stringify(body));
+}
+async function readJson(req, max = 4096) {
+    const chunks = [];
+    let n = 0;
+    for await (const c of req) {
+        n += c.length;
+        if (n > max) {
+            req.destroy();
+            return {};
+        }
+        chunks.push(c);
+    }
+    try {
+        const j = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+        return j && typeof j === "object" ? j : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Before the auth gate. Returns true when it answered. The identity route is
+ * REFUSED here for every other peer kind — a LAN token does not unlock it — and
+ * otherwise left for `handleAuthedRoutes`, so a gated Tailscale peer still
+ * needs its token.
+ */
+export async function handleLanPreAuth(req, res, kind, deps) {
+    const path = (req.url ?? "/").split("?")[0];
+    const method = req.method ?? "GET";
+    if (path === "/api/lan/identity") {
+        if (mayReadLanIdentity(kind))
+            return false;
+        reply(req, res, 403, { error: "the LAN identity is served over loopback or Tailscale only" });
+        return true;
+    }
+    if (path === "/api/lan/verify") {
+        if (method !== "POST") {
+            reply(req, res, 405, { error: "POST only" });
+            return true;
+        }
+        const key = rateKey(req);
+        if (!verifyLimit.take(key)) {
+            reply(req, res, 429, { error: "too many requests" }, { "retry-after": String(Math.ceil(verifyLimit.retryAfterMs(key) / 1000) || 1) });
+            return true;
+        }
+        const body = await readJson(req);
+        if (!validNonce(body.nonce)) {
+            reply(req, res, 400, { error: "nonce must be 16–128 printable characters" });
+            return true;
+        }
+        const id = lanIdentity(deps.root);
+        const out = { hostId: id.hostId, mac: lanMac(id.secret, id.hostId, body.nonce) };
+        reply(req, res, 200, out);
+        return true;
+    }
+    return false;
+}
+/** Behind the auth gate: the caller is trusted or holds a valid token. */
+export async function handleAuthedRoutes(req, res, kind, tok, deps) {
+    const path = (req.url ?? "/").split("?")[0];
+    const method = req.method ?? "GET";
+    if (path === "/api/lan/identity" && method === "GET") {
+        if (!mayReadLanIdentity(kind)) {
+            reply(req, res, 403, { error: "not from this connection" });
+            return true;
+        }
+        const id = lanIdentity(deps.root);
+        const out = { hostId: id.hostId, secret: id.secret, hostName: hostName() };
+        reply(req, res, 200, out);
+        return true;
+    }
+    if (path === "/api/devices" && method === "GET") {
+        const me = deps.auth.deviceFor(tok);
+        const out = { devices: deps.auth.devices.list(me?.id) };
+        reply(req, res, 200, out);
+        return true;
+    }
+    if (path === "/api/devices/revoke" && method === "POST") {
+        const body = await readJson(req);
+        if (!isDeviceId(body.id)) {
+            reply(req, res, 400, { ok: false, error: "bad device id" });
+            return true;
+        }
+        const revoked = deps.auth.devices.revoke(body.id);
+        const closedSockets = revoked ? deps.closeDevice(body.id) : 0;
+        const out = { ok: true, revoked, closedSockets };
+        reply(req, res, 200, out);
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=authroutes.js.map

package/packages/host/dist/authroutes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authroutes.js","sourceRoot":"","sources":["../src/authroutes.ts"],"names":[],"mappings":"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"}

package/packages/host/dist/autopull.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Auto-download: the inbox in reverse.
+ *
+ * The phone can push images INTO a repo, and the gallery can pull one back out
+ * when you tap it. What was missing is the case that matters on a bad link: an
+ * agent drops a 90 MB APK (or a report) into the outbox while the phone is in a
+ * tunnel, and by the time you look, tapping "download" starts a fresh transfer
+ * that a passing dead spot kills at 80%. This module is the rule engine for
+ * "start pulling it the moment it exists, and keep the byte offset so a resume
+ * costs only what's left".
+ *
+ * Two halves, deliberately split:
+ *  - the RULE, per repo, in <repoDir>/<state dir>/autopull.json (next to builds.json),
+ *    because what's worth auto-pulling is a property of the project;
+ *  - the QUEUE, host-wide, in <STATE_DIR>/pulls.json, because the file usually
+ *    lands while nothing is connected. A broadcast at detection time only ever
+ *    reaches a phone that happens to be online; the queue is what the phone reads
+ *    when it comes back. It is persisted for the same reason the ack ledger is —
+ *    `npm run restart` is routine, and a queue that a restart empties is a queue
+ *    that silently drops exactly the pull you were waiting for.
+ *
+ * What is NOT tracked here: whether a device already has the file. Several phones
+ * can subscribe to the same host, so "done" is per-device client state
+ * (web/pull.ts). The host's job ends at "this file is worth having".
+ */
+import { EventEmitter } from "node:events";
+import { familyKey, type AutoPullConfig, type PullItem } from "@waterplane/shared";
+/** Re-exported where it was born: the rule moved to `@waterplane/shared` when the
+ *  post-build prune started asking the same question ("is this an older build
+ *  of the thing I just made?"), and two answers to it would mean the phone
+ *  de-duplicating one way while the desktop deletes another. */
+export { familyKey };
+/** Sanitize a persisted/phone-supplied rule (defensive against a hand-edited file). */
+export declare function cleanConfig(v: any): AutoPullConfig;
+/**
+ * Does this file match the rule? A pattern with a slash is matched against the
+ * repo-relative path (`.claude/outbox/*.zip`), one without against the bare name
+ * — otherwise "*.apk" would never match, since every candidate is nested.
+ */
+export declare function matches(cfg: AutoPullConfig, file: {
+    name: string;
+    relPath: string;
+    size: number;
+}): boolean;
+/** Stable id: the same file re-detected (a second turn, a host restart, a
+ *  re-scan) must be the same queue entry, or the phone downloads it twice. The
+ *  mtime is in the key on purpose — a REGENERATED file at the same path is a new
+ *  thing to fetch, exactly like the gallery's read marks treat it. */
+export declare function pullId(repoId: string, relPath: string, mtime: number): string;
+export interface PullCandidate {
+    name: string;
+    relPath: string;
+    size: number;
+    mtime: number;
+}
+/** Catch-up: how far back a rule that was just switched ON looks, and how many
+ *  artifacts it may queue from what is already on disk. */
+export declare const CATCHUP_AGE_MS: number;
+export declare const CATCHUP_MAX = 3;
+/**
+ * What a rule that was just turned ON should fetch from what is ALREADY here.
+ *
+ * Auto-download is a DETECTOR everywhere else: the turn-end scan diffs the
+ * scope and a finished build hands over what it produced, so both only ever see
+ * a file that appears AFTER the rule exists. Measured here: the rule for
+ * picture-app was saved at 10:43 and the 227 MB APK it was saved FOR finished
+ * at 10:42 — one minute earlier, so nothing was ever queued, silently, and the
+ * switch looked broken. The file a person is looking at when they turn the
+ * switch on is precisely the file they mean.
+ *
+ * Bounded, because the same argument does not extend to a year of artifacts:
+ * the NEWEST of each family only (two builds of one app are one thing to
+ * fetch, `familyKey`), at most `max` of them, and nothing older than a day.
+ * Whether any of them MATCHES the rule is still `matches`' decision — this
+ * only picks which candidates are worth asking about.
+ */
+export declare function catchUpCandidates<T extends PullCandidate>(files: T[], now?: number, maxAgeMs?: number, max?: number): T[];
+export declare class AutoPullManager extends EventEmitter {
+    private items;
+    private queuePath;
+    constructor(root: string);
+    private configPath;
+    /** A repo's rule (defaults when there is no file). */
+    config(repoDir: string): AutoPullConfig;
+    /** Persist a repo's rule; returns what was actually written. */
+    saveConfig(repoDir: string, cfg: AutoPullConfig): AutoPullConfig;
+    list(): PullItem[];
+    /**
+     * Offer newly-seen files to a repo's rule. Returns the ones that were queued
+     * (already-queued ids are dropped silently — the caller's "new file" detection
+     * and ours are independent, and a re-offer must not re-queue).
+     *
+     * `source: "manual"` bypasses the rule entirely: that is the gallery's "send
+     * this to my phone" button, an explicit human decision, and gating it on a
+     * configured pattern would make the button silently do nothing.
+     */
+    consider(repo: {
+        repoId: string;
+        repoDir: string;
+        repoName: string;
+    }, files: PullCandidate[], source: PullItem["source"]): PullItem[];
+    /** Drop one item, or the whole queue when `id` is omitted. */
+    dismiss(id?: string): void;
+    /** tmp+rename so a kill mid-write can't leave truncated JSON that the
+     *  constructor's catch turns into an empty queue. */
+    private save;
+}