@swimmingliu/autovpn 2.2.4 → 2.3.0

package/dist/cli/accounts-commands.js

@@ -7,16 +7,16 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { AccountStore } from '../pool/account-store.js';
+import { AccountStore, retiredRetentionDays } from '../pool/account-store.js';
 import { BRANDS, brandLabel, normalizeBrand } from '../pool/brands.js';
 import { CSV_COLUMNS, RETIRED_STATUSES, parseAccountFile, stringifyCsv } from '../pool/csv.js';
 import { CliUsageError } from './errors.js';
 import { readOptionValue } from './global-options.js';
-export const ACCOUNTS_SUBCOMMANDS = ['import', 'list', 'stats', 'snapshot', 'disable', 'enable', 'expire', 'export', 'template', 'refresh-expiry'];
+export const ACCOUNTS_SUBCOMMANDS = ['import', 'list', 'stats', 'snapshot', 'disable', 'enable', 'expire', 'export', 'template', 'refresh-expiry', 'purge'];
 /** Options that consume the next argv slot, so positionals can be found. */
 const VALUE_OPTIONS = new Set([
     '--project-root', '--format', '--output', '--brand', '--status', '--reason', '--date', '--file', '--limit', '--query', '--id',
-    '--concurrency'
+    '--concurrency', '--days'
 ]);
 /**
  * Resolve the pipeline worker lazily.
@@ -94,6 +94,16 @@ export function validateAccountsCommand(argv) {
             throw new CliUsageError('accounts refresh-expiry --concurrency must be a positive integer');
         }
     }
+    if (subcommand === 'purge') {
+        const days = readOptionValue(argv, '--days');
+        // Whole days only. The cutoff is built from `days * 86_400_000` and rows
+        // are compared as strings, so a fraction would have to be rounded one way
+        // or the other anyway; refuse it rather than quietly giving a different
+        // window than the operator typed. 0 is legal and means "keep everything".
+        if (days !== undefined && !/^\d+$/.test(days)) {
+            throw new CliUsageError('accounts purge --days must be a non-negative whole number of days');
+        }
+    }
     if (['disable', 'enable', 'expire'].includes(subcommand)) {
         const id = readOptionValue(argv, '--id');
         if (id !== undefined) {
@@ -223,7 +233,7 @@ export async function runAccountsCommand(argv, context) {
     if (subcommand === 'refresh-expiry') {
         return await runRefreshExpiry(argv, context);
     }
-    const dryRun = subcommand === 'import' && argv.includes('--dry-run');
+    const dryRun = (subcommand === 'import' || subcommand === 'purge') && argv.includes('--dry-run');
     // A preview must not write: the store's getters sweep expired rows, so even
     // opening it read-write would mutate the pool before showing the plan.
     const store = context.store ?? new AccountStore({ env: context.env, now: context.now, readOnly: dryRun });
@@ -240,6 +250,47 @@ export async function runAccountsCommand(argv, context) {
             context.io.writeStdout(jsonLine(payload));
             return 0;
         }
+        if (subcommand === 'purge') {
+            // An explicit, unconditional sweep: the operator asked for it now, so it
+            // ignores the once-per-window stamp that read paths use. `--dry-run`
+            // reports what would go without erasing anything, and opens the store
+            // read-only so not even the lapse sweep writes.
+            //
+            // The count has two parts because they are two different answers. Retired
+            // rows past the window go on this run. Unrecorded lapses are retired by
+            // the sweep first, and their own window starts at that moment - so they
+            // are reported as a separate number rather than promised as erased.
+            const daysRaw = readOptionValue(argv, '--days');
+            // Checked here as well as in `validateAccountsCommand`, because this
+            // function is also the entry point for callers that skip validation; a
+            // fractional value would otherwise be silently truncated to whole days.
+            if (daysRaw !== undefined && !/^\d+$/.test(daysRaw)) {
+                throw new CliUsageError('accounts purge --days must be a non-negative whole number of days');
+            }
+            const days = daysRaw === undefined ? retiredRetentionDays(context.env) : Number.parseInt(daysRaw, 10);
+            const dryRun = argv.includes('--dry-run');
+            if (dryRun) {
+                const counted = store.countRetired(days);
+                context.io.writeStdout(wantsHuman(argv)
+                    ? `would purge ${counted.purgeable} retired account(s); retention ${days} day(s)` +
+                        `${counted.pendingLapse ? `; ${counted.pendingLapse} lapsed account(s) will be retired now and counted next window` : ''}\n`
+                    : jsonLine({ ok: true, retired_retention_days: days, erased: 0, would_erase: counted.purgeable, pending_lapse: counted.pendingLapse, dry_run: true }));
+                return 0;
+            }
+            // Retire first, so a row whose date lapsed before anyone read the pool is
+            // reported as expired rather than left invisible to both numbers.
+            const lapsed = store.expireDue();
+            const erased = store.sweepRetired(days, true);
+            // `--days 0` means "keep everything", so the report itself must not
+            // sweep with the default window on the way out.
+            const after = store.stats({ maintain: days > 0 });
+            const payload = { ok: true, retired_retention_days: days, erased, lapsed, dry_run: false, stats: after };
+            context.io.writeStdout(wantsHuman(argv)
+                ? `purged ${erased} retired account(s); retention ${days} day(s); ${after.total} row(s) remain` +
+                    `${lapsed ? `; ${lapsed} expired account(s) newly retired` : ''}\n`
+                : jsonLine(payload));
+            return 0;
+        }
         if (subcommand === 'list') {
             const limitRaw = readOptionValue(argv, '--limit');
             let limit;

package/dist/cli/output.js

@@ -18,7 +18,7 @@ Usage:
 
 Commands:
   profile show|save|summary
-  accounts import|list|stats|snapshot|disable|enable|expire|refresh-expiry|export|template
+  accounts import|list|stats|snapshot|disable|enable|expire|refresh-expiry|export|template|purge
   doctor
   artifacts latest|list|preview
   run

package/dist/pool/account-store.js

@@ -24,6 +24,34 @@ export function resolveAccountsDbPath(env = process.env) {
         return path.resolve(override);
     return path.join(resolveUserRuntimeRoot(env), 'accounts.db');
 }
+/**
+ * How long a retired account's row, and its password, stay in the file.
+ *
+ * The default is a month: long enough that "where did that account go?" has an
+ * answer after a renewal cycle, short enough that a lapsed credential is not
+ * still sitting on disk a year later. `0` keeps retired rows forever, which is
+ * the behaviour before this existed.
+ */
+export function retiredRetentionDays(env = process.env) {
+    const raw = String(env.AUTOVPN_ACCOUNT_RETIRED_RETENTION_DAYS ?? '').trim();
+    if (!raw)
+        return 30;
+    const parsed = Number.parseFloat(raw);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return 30;
+    return Math.trunc(parsed);
+}
+/**
+ * The cutoff row for a retention window, in the same UTC ISO spelling the
+ * ledger writes for `deleted_at`.
+ *
+ * Rows are compared as strings, so both sides must be truncated to whole
+ * seconds: a stamp of `2026-07-01T00:00:00Z` is shorter than a cutoff of
+ * `2026-07-01T00:00:00.000Z` and would read as "older than itself".
+ */
+function retentionCutoff(now, days) {
+    return isoNow(new Date(now.getTime() - Math.trunc(days) * 86_400_000));
+}
 /** Keep the first and last character; a 6-char account still reads as itself. */
 export function maskAccount(value) {
     const text = String(value ?? '');
@@ -69,6 +97,7 @@ CREATE TABLE IF NOT EXISTS accounts (
   UNIQUE (brand, account)
 );
 CREATE INDEX IF NOT EXISTS accounts_rotation ON accounts (brand, status, deleted_at, last_used_at);
+CREATE INDEX IF NOT EXISTS accounts_retired ON accounts (deleted_at, status);
 CREATE TABLE IF NOT EXISTS pool_events (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   account_id INTEGER NOT NULL,
@@ -77,16 +106,22 @@ CREATE TABLE IF NOT EXISTS pool_events (
   detail TEXT NOT NULL DEFAULT ''
 );
 CREATE INDEX IF NOT EXISTS pool_events_account ON pool_events (account_id, id);
+CREATE TABLE IF NOT EXISTS pool_meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
 `;
 export class AccountStore {
     db;
     now;
     readOnly;
+    env;
     dbPath;
     constructor(options = {}) {
         this.dbPath = options.dbPath ?? resolveAccountsDbPath(options.env ?? process.env);
         this.now = options.now ?? (() => new Date());
         this.readOnly = options.readOnly === true;
+        this.env = options.env ?? process.env;
         const inMemory = this.dbPath === ':memory:';
         if (!inMemory) {
             // The pool holds plaintext credentials in the main file *and* in the WAL
@@ -129,6 +164,18 @@ export class AccountStore {
             .prepare('INSERT INTO pool_events (account_id, at, kind, detail) VALUES (?, ?, ?, ?)')
             .run(accountId, isoNow(this.now()), kind, detail);
     }
+    /**
+     * The housekeeping every read path owes the pool: lapse what is due, then
+     * erase what has been retired long enough.
+     *
+     * Both are cheap and both are idempotent, so a read is the natural trigger:
+     * there is no daemon to depend on, and whichever surface reads first does
+     * the work. `readOnly` connections skip both (see the constructor).
+     */
+    maintain() {
+        this.expireDue();
+        this.sweepRetired(retiredRetentionDays(this.env));
+    }
     /**
      * Retire accounts whose membership date has passed.
      *
@@ -154,6 +201,117 @@ export class AccountStore {
         }
         return due.length;
     }
+    /**
+     * Erase retired rows whose retirement is older than `days`.
+     *
+     * `expireDue` only flips a lapsed row to `expired` and soft-deletes it; the
+     * row and its password stay in the file forever, so a pool that has been
+     * rotated for a year carries every credential it ever held. This is the one
+     * place that removes them, and it removes the password with them.
+     *
+     * Only rows already retired by the sweep or by an operator qualify:
+     *
+     * - `expired` is erased, because its date is known and the pool already
+     *   refuses to lease it. `invalid` is too: a rejected password is not coming
+     *   back, and keeping the credential is the liability with no upside.
+     * - `disabled` is kept. It is an operator's deliberate pause, not a verdict,
+     *   and re-enabling it is documented behaviour.
+     * - Rows with no `deleted_at` are never touched, whatever their status: that
+     *   is the only column this sweep trusts to mean "already retired".
+     *
+     * `0` disables the sweep. The window is measured from the retirement stamp,
+     * so a row retired this morning survives a sweep run this afternoon however
+     * far in the past its membership date is.
+     */
+    purgeRetired(days) {
+        if (this.readOnly)
+            return 0;
+        if (!Number.isFinite(days) || days <= 0)
+            return 0;
+        const cutoff = retentionCutoff(this.now(), days);
+        const doomed = this.db
+            .prepare(`SELECT id FROM accounts
+         WHERE deleted_at IS NOT NULL AND deleted_at < ? AND status IN ('expired', 'invalid')`)
+            .all(cutoff);
+        if (doomed.length === 0)
+            return 0;
+        // One transaction: a half-purged pool would leave events pointing at rows
+        // that no longer exist, and the next sweep would have to reconcile both.
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const eraseEvents = this.db.prepare('DELETE FROM pool_events WHERE account_id = ?');
+            const eraseRow = this.db.prepare('DELETE FROM accounts WHERE id = ?');
+            for (const row of doomed) {
+                eraseEvents.run(row.id);
+                eraseRow.run(row.id);
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+        return doomed.length;
+    }
+    /**
+     * Count what `purgeRetired` would erase, without erasing anything.
+     *
+     * `accounts purge --dry-run` must leave the file byte-identical, and every
+     * reader runs the retention sweep, so a preview cannot go through `stats()`.
+     *
+     * A lapse that no read has recorded yet is reported separately, not counted
+     * as purgeable: the sweep that retires it stamps `deleted_at` with the moment
+     * it runs, so that row's retention window starts then, not in the past.
+     */
+    countRetired(days) {
+        const pendingRow = this.db
+            .prepare(`SELECT COUNT(*) AS total FROM accounts
+         WHERE deleted_at IS NULL AND status = 'active' AND expires_at != '' AND expires_at < ?`)
+            .get(isoDay(this.now()));
+        const pendingLapse = Number(pendingRow?.total ?? 0);
+        if (!Number.isFinite(days) || days <= 0)
+            return { purgeable: 0, pendingLapse };
+        const cutoff = retentionCutoff(this.now(), days);
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS total FROM accounts
+         WHERE deleted_at IS NOT NULL AND deleted_at < ? AND status IN ('expired', 'invalid')`)
+            .get(cutoff);
+        return { purgeable: Number(row?.total ?? 0), pendingLapse };
+    }
+    /**
+     * Run `purgeRetired` at most once per retention window.
+     *
+     * Nothing here owns a long-lived process: `autovpn serve` starts and stops,
+     * the desktop app opens and closes, and a cron run is one CLI invocation. A
+     * timer in any one of them would clean the pool only while that surface
+     * happened to be open. Instead every store open runs the sweep, and a stamp
+     * in the database (`pool_meta`) makes the work a no-op until the window has
+     * passed. Whichever surface touches the pool first each day does the sweep;
+     * the rest see the stamp and skip it.
+     *
+     * Returns the number of erased rows, or 0 when the window had not elapsed.
+     */
+    sweepRetired(days, force = false) {
+        if (this.readOnly)
+            return 0;
+        if (!Number.isFinite(days) || days <= 0)
+            return 0;
+        const now = this.now();
+        if (!force) {
+            const last = this.db.prepare("SELECT value FROM pool_meta WHERE key = 'retired_purged_at'").get();
+            if (last?.value) {
+                const elapsed = now.getTime() - Date.parse(last.value);
+                if (Number.isFinite(elapsed) && elapsed >= 0 && elapsed < days * 86_400_000)
+                    return 0;
+            }
+        }
+        // Stamp first: a sweep that throws midway must not retry on every open and
+        // hold the write lock each time. The next window will finish the job.
+        this.db
+            .prepare("INSERT INTO pool_meta (key, value) VALUES ('retired_purged_at', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
+            .run(isoNow(now));
+        return this.purgeRetired(days);
+    }
     /**
      * Insert or refresh rows from an import file.
      *
@@ -261,7 +419,7 @@ export class AccountStore {
     }
     /** Masked rows for the UI and `accounts list`. Never carries a password. */
     list(filter = {}) {
-        this.expireDue();
+        this.maintain();
         const clauses = [];
         const params = [];
         if (!filter.includeDeleted)
@@ -288,8 +446,16 @@ export class AccountStore {
             .all(...params);
         return rows.map((row) => this.toPublic(row));
     }
-    stats() {
-        this.expireDue();
+    /**
+     * Totals for the UI and `accounts stats`.
+     *
+     * `maintain: false` is for `accounts purge --days 0`, which just promised to
+     * keep every retired row: the read that reports the result must not turn
+     * around and sweep with the default window.
+     */
+    stats({ maintain = true } = {}) {
+        if (maintain)
+            this.maintain();
         const rows = this.db
             .prepare('SELECT brand, status, deleted_at, expires_at FROM accounts')
             .all();
@@ -347,6 +513,10 @@ export class AccountStore {
      * never by a display path.
      */
     lease(brand) {
+        // Lapse-only, not `maintain()`: a lease is the hottest write path in the
+        // pool (once per login per account), and erasing retired rows there would
+        // take the write lock in the middle of a run for work that a plain read
+        // will do later. Expiring is cheap and decides whether this lease is legal.
         this.expireDue();
         const key = normalizeBrand(brand);
         if (!key)
@@ -367,6 +537,7 @@ export class AccountStore {
     }
     /** Every usable credential for a brand, for a run that wants to fan out. */
     leaseAll(brand) {
+        // Same reasoning as `lease`: expiry decides legality, the purge waits.
         this.expireDue();
         const key = normalizeBrand(brand);
         if (!key)