@wpelevator/tug 0.4.0 → 0.6.0

package/dist/protocol.d.ts

@@ -24,6 +24,40 @@ export interface IngressSpec {
     cert?: string;
     key?: string;
 }
+/** What a backup captures: the output of a command run in a service, or the files of a volume. */
+export type BackupType = 'command' | 'volume';
+/** A restic keep policy; at least one key is required. */
+export interface BackupRetention {
+    last?: number;
+    hourly?: number;
+    daily?: number;
+    weekly?: number;
+    monthly?: number;
+    yearly?: number;
+}
+/** `x-tug.backup` on a service or top-level volume, as an object. */
+export interface BackupSpec {
+    /** Five-field cron in UTC, or `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`. */
+    schedule?: string;
+    retention?: BackupRetention;
+    /** Seconds of deterministic per-target delay after the scheduled minute. */
+    jitter?: number;
+    /** Hard limit for one run, such as `30m` or `2h`. */
+    timeout?: string | number;
+    /** Services only: run in the service's container; its standard output is the backup. A string runs through `sh -c`. */
+    command?: string | string[];
+    /** Services only: run in the service container to restore; the stored file arrives on its standard input. */
+    restore?: string | string[];
+    /** Services only: name of the file inside the snapshot (default `<service>.out`). */
+    filename?: string;
+    /** Services only: text that must appear in the last 4 KiB of output, so a command cut short is not kept as a good backup. */
+    verify?: string;
+    /** Volumes only: restic exclude patterns. */
+    exclude?: string[];
+    /** Services to hold during a restore. */
+    writers?: string[];
+}
+export type BackupConfig = boolean | string | BackupSpec;
 export type RolloutStrategy = 'recreate' | 'rolling';
 /** `x-tug.rollout`: how a service is replaced on a new deployment. `recreate` (default) is `docker compose up -d`. */
 export interface RolloutSpec {
@@ -39,11 +73,14 @@ export interface ServiceExtension {
     health?: HealthCheck;
     ingress?: IngressSpec;
     rollout?: RolloutSpec;
+    backup?: BackupConfig;
 }
 /** The top-level `x-tug` extension of a Compose file. */
 export interface ProjectExtension {
     /** `auto` creates a rollback deployment when a deployment fails on health; `manual` (default) only reports it. */
     rollback?: 'auto' | 'manual';
+    /** Defaults for every `x-tug.backup` target; they enable nothing by themselves. */
+    backup?: Pick<BackupSpec, 'schedule' | 'retention'>;
 }
 /** The `x-tug` extension on a top-level Compose volume. */
 export interface VolumeExtension {
@@ -51,10 +88,7 @@ export interface VolumeExtension {
     driver?: string;
     persistent?: boolean;
     placement?: Placement;
-    /** NFS exporter address; control fills in the exporter's overlay IP (or node address) at deploy time. */
-    address?: string;
-    /** Directory exported by the NFS server on the exporter node (default `/srv/tug/<volume>`). */
-    export?: string;
+    backup?: BackupConfig;
 }
 export type BuildConfig = string | {
     context?: string;
@@ -130,7 +164,74 @@ export declare const ACTIVE_DEPLOYMENT_STATES: readonly ["uploading", "building"
 /** Deployment states a CLI wait loop stops on. */
 export declare const TERMINAL_DEPLOYMENT_STATES: readonly ["succeeded", "failed", "build_failed", "cancelled"];
 export type DeploymentState = (typeof ACTIVE_DEPLOYMENT_STATES)[number] | (typeof TERMINAL_DEPLOYMENT_STATES)[number];
-export type CommandType = 'diagnostics.run' | 'service.restart' | 'logs.fetch' | 'volume.delete' | 'wg.rotate-key';
+export type CommandType = 'diagnostics.run' | 'service.restart' | 'logs.fetch' | 'volume.delete' | 'wg.rotate-key' | 'backup.check' | 'backup.run' | 'backup.restore' | 'backup.list';
+/** Commands whose helper containers need the backup destination's credentials. */
+export declare const BACKUP_COMMAND_TYPES: readonly CommandType[];
+/** `GET /agent/v1/backup/credentials`: environment for the restic helper of one running backup command. */
+export interface BackupCredentialsResponse {
+    env: Record<string, string>;
+}
+/** Why a command may be refused or a run marked missed; recorded on the run. */
+export type BackupMissReason = 'node_offline' | 'control_down' | 'deadline';
+export type JobPhase = 'queued' | 'pulling' | 'checking' | 'dumping' | 'uploading' | 'forgetting' | 'restoring';
+/** Payload of `backup.check`, `backup.run` and `backup.restore`. Restic credentials are never in a payload. */
+export interface BackupJobPayload {
+    runId: string;
+    project: string;
+    /** `service:db` or `volume:uploads`; empty for `backup.check`. */
+    target: string;
+    type: BackupType;
+    /** The project's restic repository, `<destination>/<project>`. */
+    repository: string;
+    resticImage: string;
+    /** Used as restic's `--host`, so each node keeps its own snapshot chain. */
+    node: string;
+    tags: string[];
+    retention?: BackupRetention;
+    /** Command targets: what to run in the service's container, and how to name and check its output. */
+    command?: {
+        service: string;
+        argv: string[];
+        filename: string;
+        verify?: string;
+        /** Run in the service container with the snapshot's file on stdin when restoring. */
+        restoreArgv?: string[];
+    };
+    /** Volume targets: the Docker volume to mount read-only; it must already exist on the node. */
+    volume?: {
+        name: string;
+        dockerVolume: string;
+        exclude?: string[];
+    };
+    limits: {
+        memory: string;
+        timeoutSec: number;
+    };
+    restore?: {
+        snapshotId: string;
+        mode: 'in-place' | 'scratch';
+        scratchVolume?: string;
+    };
+}
+export interface BackupJobResult {
+    runId: string;
+    snapshotId?: string;
+    addedBytes?: number;
+    totalBytes?: number;
+    durationMs: number;
+    resticVersion?: string;
+    /** Repository state for `backup.check`. */
+    repository?: 'ok' | 'initialized';
+    warnings?: string[];
+}
+/** Live jobs in `StatusReport.jobs`, so control can tell "running" from "lost". */
+export interface JobStatus {
+    commandId: string;
+    runId: string;
+    phase: JobPhase;
+    startedAt: string;
+    bytes?: number;
+}
 /** A `commands` table row as delivered in `GET /agent/v1/work`. */
 export interface Command {
     id: string;
@@ -173,7 +274,7 @@ export type CommandResultPayload = {
     deleted: true;
 } | {
     publicKey: string;
-} | {
+} | BackupJobResult | {
     error: string;
 };
 export interface CommandResult {
@@ -206,6 +307,8 @@ export type LiveRequest = {
     tty: boolean;
     columns?: number;
     rows?: number;
+    /** Run the command in a new container cloned from the service's, instead of in the running one. */
+    oneOff?: boolean;
 } | {
     operation: 'logs';
     project: string;
@@ -327,6 +430,8 @@ export interface WorkResponse {
     ingress?: IngressWork;
     /** Host addresses for published ports that name no host IP. */
     ports?: PortBinding;
+    /** Per project, services that must stay stopped because a restore is rewriting their data. */
+    holds?: Record<string, string[]>;
 }
 /**
  * Where a node's published ports listen when a `ports` entry names no host IP. Entries with an
@@ -393,7 +498,9 @@ export interface IngressStatus {
     error?: string;
 }
 export type ProjectHealth = 'serving' | 'skipped' | 'failed';
-export type RolloutState = 'pending' | 'pulling' | 'starting' | 'health_checking' | 'serving';
+export type RolloutState = 'pending' | 'pulling' | 'starting' | 'health_checking' | 'serving'
+/** Stopped on purpose while a restore rewrites its data. */
+ | 'held';
 export interface ServiceState {
     rolloutState: RolloutState;
     image?: string;
@@ -419,8 +526,14 @@ export interface StatusReport {
     projects: ProjectStatus[];
     commandResults: CommandResult[];
     ingress?: IngressStatus;
+    /** Backup jobs still running on this node; absent when none. */
+    jobs?: JobStatus[];
 }
 export interface SecretsResponse {
+    registryAuth?: Record<string, {
+        username: string;
+        password: string;
+    }>;
     secrets: Record<string, string>;
     versions: Record<string, number>;
 }
@@ -447,7 +560,6 @@ export interface NodeInfo {
 export interface RegisterResponse {
     node: NodeInfo;
     agentToken: string;
-    registryToken: string;
 }
 /** Body of `POST /agent/v1/enroll`. */
 export interface EnrollRequest {
@@ -461,16 +573,13 @@ export interface EnrollRequest {
     labels?: string[];
 }
 /** Response of `POST /agent/v1/enroll`. */
-export interface EnrollResponse extends RegisterResponse {
-    registry: string;
-}
+export type EnrollResponse = RegisterResponse;
 /** Response of `POST /api/v1/nodes/enroll-token`. */
 export interface EnrollTokenResponse {
     enrollToken: string;
     name: string | null;
     usesRemaining: number;
     expiresAt: string;
-    registry: string;
 }
 /** The base64url-encoded JSON payload of TUG_JOIN_KEY. */
 export interface JoinKey {

package/dist/protocol.js

@@ -16,6 +16,13 @@ export const TERMINAL_DEPLOYMENT_STATES = [
     'build_failed',
     'cancelled',
 ];
+/** Commands whose helper containers need the backup destination's credentials. */
+export const BACKUP_COMMAND_TYPES = [
+    'backup.check',
+    'backup.run',
+    'backup.restore',
+    'backup.list',
+];
 export const LIVE_MAX_FRAME_BYTES = 256 * 1024;
 export const LIVE_MAX_BUFFERED_BYTES = 1024 * 1024;
 export const LIVE_MAX_SESSIONS = 64;

package/dist/registry.d.ts

@@ -0,0 +1,17 @@
+export declare const REGISTRY_AUTH_SECRET = "TUG_REGISTRY_AUTH";
+export interface RegistryCredential {
+    username: string;
+    password: string;
+}
+export type RegistryCredentials = Record<string, RegistryCredential>;
+/** A project secret containing registry-host -> username/password entries; never a desired-state field. */
+export declare function parseRegistryCredentials(value?: string): RegistryCredentials;
+export declare function imageLocation(image: string): {
+    host: string;
+    repository: string;
+    tag: string;
+    digest: string;
+    name: string;
+};
+/** Pin the complete index, so amd64 and arm64 agents select from the same immutable manifest. */
+export declare function resolveImage(image: string, credentials?: RegistryCredentials, request?: typeof fetch): Promise<string>;

package/dist/registry.js

@@ -0,0 +1,133 @@
+import { createHash } from 'node:crypto';
+export const REGISTRY_AUTH_SECRET = 'TUG_REGISTRY_AUTH';
+/** A project secret containing registry-host -> username/password entries; never a desired-state field. */
+export function parseRegistryCredentials(value) {
+    if (!value)
+        return {};
+    try {
+        const entries = JSON.parse(value);
+        if (!entries || typeof entries !== 'object' || Array.isArray(entries))
+            throw new Error();
+        const credentials = {};
+        for (const [host, auth] of Object.entries(entries)) {
+            if (!/^[a-zA-Z0-9.:[\]-]+$/.test(host) ||
+                !auth ||
+                typeof auth !== 'object' ||
+                typeof auth.username !== 'string' ||
+                typeof auth.password !== 'string')
+                throw new Error();
+            credentials[host] = { username: auth.username, password: auth.password };
+        }
+        return credentials;
+    }
+    catch {
+        throw new Error(`${REGISTRY_AUTH_SECRET} must be a JSON object mapping registry hosts to username/password objects`);
+    }
+}
+export function imageLocation(image) {
+    const match = /^(?<name>[^@\s]+?)(?:@(?<digest>sha256:[a-f0-9]{64}))?$/.exec(image);
+    if (!match?.groups)
+        throw new Error('invalid image reference');
+    const { name, digest } = match.groups;
+    const slash = name.indexOf('/');
+    const qualified = slash >= 0 && /[.:]|^localhost$/.test(name.slice(0, slash));
+    let host = qualified ? name.slice(0, slash) : 'docker.io';
+    if (host === 'index.docker.io')
+        host = 'docker.io';
+    let repository = qualified ? name.slice(slash + 1) : name;
+    const colon = repository.lastIndexOf(':');
+    const tag = colon >= 0 ? repository.slice(colon + 1) : 'latest';
+    if (colon >= 0)
+        repository = repository.slice(0, colon);
+    if (host === 'docker.io' && !repository.includes('/'))
+        repository = `library/${repository}`;
+    if (!/^[a-z0-9]+(?:[._-]+[a-z0-9]+)*(?:\/[a-z0-9]+(?:[._-]+[a-z0-9]+)*)*$/.test(repository) ||
+        !/^[\w][\w.-]{0,127}$/.test(tag) ||
+        !/^[a-zA-Z0-9.:[\]-]+$/.test(host))
+        throw new Error('invalid image reference');
+    return { host, repository, tag, digest, name };
+}
+const accept = [
+    'application/vnd.oci.image.index.v1+json',
+    'application/vnd.docker.distribution.manifest.list.v2+json',
+    'application/vnd.oci.image.manifest.v1+json',
+    'application/vnd.docker.distribution.manifest.v2+json',
+].join(', ');
+/** Pin the complete index, so amd64 and arm64 agents select from the same immutable manifest. */
+export async function resolveImage(image, credentials = {}, request = fetch) {
+    const location = imageLocation(image);
+    if (location.digest)
+        return image;
+    const { host, repository, tag, name } = location;
+    const endpoint = host === 'docker.io' ? 'registry-1.docker.io' : host;
+    const url = `https://${endpoint}/v2/${repository}/manifests/${tag}`;
+    const auth = credentials[host];
+    const basic = auth
+        ? `Basic ${Buffer.from(`${auth.username}:${auth.password}`).toString('base64')}`
+        : undefined;
+    const get = (authorization) => request(url, {
+        headers: { Accept: accept, ...(authorization ? { Authorization: authorization } : {}) },
+        redirect: 'error',
+        signal: AbortSignal.timeout(30_000),
+    });
+    try {
+        let response = await get();
+        if (response.status === 401) {
+            const challenge = response.headers.get('www-authenticate') || '';
+            await response.body?.cancel();
+            if (/^Basic\s/i.test(challenge) && basic)
+                response = await get(basic);
+            else if (/^Bearer\s/i.test(challenge)) {
+                const params = Object.fromEntries([...challenge.matchAll(/(\w+)="([^"]*)"/g)].map((m) => [m[1], m[2]]));
+                const tokenUrl = new URL(params.realm);
+                if (tokenUrl.protocol !== 'https:' || tokenUrl.username || tokenUrl.password)
+                    throw new Error();
+                if (params.service)
+                    tokenUrl.searchParams.set('service', params.service);
+                tokenUrl.searchParams.set('scope', `repository:${repository}:pull`);
+                const tokenResponse = await request(tokenUrl, {
+                    headers: basic ? { Authorization: basic } : {},
+                    redirect: 'error',
+                    signal: AbortSignal.timeout(30_000),
+                });
+                if (!tokenResponse.ok) {
+                    await tokenResponse.body?.cancel();
+                    throw new Error();
+                }
+                const body = (await tokenResponse.json());
+                const token = body.token || body.access_token;
+                if (!token || typeof token !== 'string')
+                    throw new Error();
+                response = await get(`Bearer ${token}`);
+            }
+            else
+                throw new Error();
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new Error();
+        }
+        // Hash the exact bytes instead of trusting a registry's digest header. Bound manifest memory use.
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of response.body) {
+            size += chunk.length;
+            if (size > 8 * 1024 * 1024)
+                throw new Error();
+            chunks.push(chunk);
+        }
+        const bytes = Buffer.concat(chunks);
+        const manifest = JSON.parse(bytes.toString());
+        if (manifest.schemaVersion !== 2 ||
+            !(Array.isArray(manifest.manifests) || (manifest.config && Array.isArray(manifest.layers))))
+            throw new Error();
+        const digest = `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+        const reported = response.headers.get('docker-content-digest');
+        if (reported && reported !== digest)
+            throw new Error();
+        return `${name}@${digest}`;
+    }
+    catch {
+        throw new Error(`cannot resolve image ${image}; check registry availability and project ${REGISTRY_AUTH_SECRET} credentials`);
+    }
+}

package/dist/templates/control-compose.yml

@@ -8,12 +8,8 @@ services:
       TUG_DATA_DIR: /data
       TUG_OPERATOR_TOKEN: {{OPERATOR_TOKEN}}
       TUG_MESH: {{MESH}}
-      TUG_REGISTRY: {{REGISTRY_HOST}}
-      TUG_REGISTRY_AUTH_PATH: {{REGISTRY_AUTH_PATH}}
-      TUG_REGISTRY_CONTAINER: {{REGISTRY_CONTAINER}}
     ports:
       - "{{PORT}}:8080"
     volumes:
       - /var/lib/tug-control:/data
-      - /var/lib/tug-registry-auth:/registry-auth
       - /var/run/docker.sock:/var/run/docker.sock

package/dist/templates/node-install.sh

@@ -3,6 +3,5 @@ mkdir -p /etc/tug /var/lib/tug
 cat > /etc/tug/agent.env <<'ENV'
 {{ENV}}ENV
 chmod 0600 /etc/tug/agent.env
-{{DOCKER_LOGIN}}
 docker rm -f tug-agent >/dev/null 2>&1 || true
 docker run -d --name tug-agent --restart unless-stopped --env-file /etc/tug/agent.env {{RUN_FLAGS}}-v /var/run/docker.sock:/var/run/docker.sock -v /var/lib/tug:/var/lib/tug {{IMAGE_SH}} agent

package/dist/tokens.d.ts

@@ -14,7 +14,7 @@ export declare const PROJECT_NAME_PATTERN: RegExp;
 /**
  * The single source of truth for who may call what. Every `/api/v1` route must appear here: createApp refuses to
  * register an unlisted route, and a test compares this table with the live router. `public` routes do their own
- * credential check (the registry hook) and are not behind the token guard. docs/access-control.md mirrors this table.
+ * credential check and are not behind the token guard. docs/access-control.md mirrors this table.
  */
 export declare const ROUTE_ROLES: Record<string, RouteRole>;
 /** The authenticated caller of an API request. `projects` is null when the credential is not project-scoped. */
@@ -60,14 +60,14 @@ export declare function parseTokenRequest(body: unknown): {
     expiresAt: string | null;
 };
 /** Creates a token. The plaintext is returned once; only its hash is stored. */
-export declare function createToken(db: Db, request: ReturnType<typeof parseTokenRequest>, createdBy: string): Promise<TokenInfo & {
+export declare function createToken(db: Db, request: ReturnType<typeof parseTokenRequest>, createdBy: string): TokenInfo & {
     token: string;
-}>;
-export declare function listTokens(db: Db): Promise<TokenInfo[]>;
+};
+export declare function listTokens(db: Db): TokenInfo[];
 /** Revokes a token immediately. Returns false if no such token exists; revoking twice keeps the first revocation time. */
-export declare function revokeToken(db: Db, name: string): Promise<boolean>;
+export declare function revokeToken(db: Db, name: string): boolean;
 /** Resolves a bearer value to an actor by hash lookup: the root operator token first, then named tokens. */
-export declare function authenticate(db: Db, raw: string): Promise<Actor | null>;
+export declare function authenticate(db: Db, raw: string): Actor | null;
 /**
  * Which project a request targets: a name, `null` for control-wide data (admin only), or `undefined` when it cannot be
  * resolved (for example an unknown ID). Unresolvable targets are denied to scoped tokens without saying why, so they
@@ -88,4 +88,4 @@ export declare function recordEvent(db: Db, event: {
     project?: string | null;
     deploymentId?: string | null;
     metadata?: Record<string, unknown>;
-}): Promise<void>;
+}): void;

package/dist/tokens.js

@@ -1,3 +1,4 @@
+import { isUniqueViolation } from "./db-driver.js";
 import { hashToken, id, now, token } from "./util.js";
 /** Roles are cumulative: `deploy` includes `read`, and `admin` includes both. */
 export const ROLES = ['read', 'deploy', 'admin'];
@@ -14,7 +15,7 @@ const LAST_USED_INTERVAL_MS = 60_000;
 /**
  * The single source of truth for who may call what. Every `/api/v1` route must appear here: createApp refuses to
  * register an unlisted route, and a test compares this table with the live router. `public` routes do their own
- * credential check (the registry hook) and are not behind the token guard. docs/access-control.md mirrors this table.
+ * credential check and are not behind the token guard. docs/access-control.md mirrors this table.
  */
 export const ROUTE_ROLES = {
     'GET /api/v1/live': 'deploy',
@@ -38,11 +39,19 @@ export const ROUTE_ROLES = {
     'GET /api/v1/nodes': 'admin',
     'POST /api/v1/nodes/register': 'admin',
     'POST /api/v1/nodes/enroll-token': 'admin',
-    'POST /api/v1/nodes/:name/rotate-registry-token': 'admin',
-    'POST /api/v1/nodes/:name/revoke-registry-token': 'admin',
     'POST /api/v1/nodes/:name/rotate-wg-key': 'admin',
     'POST /api/v1/nodes/:name/ingress': 'admin',
     'DELETE /api/v1/nodes/:name': 'admin',
+    'POST /api/v1/backups/run': 'deploy',
+    'GET /api/v1/backups': 'read',
+    'POST /api/v1/restores': 'admin',
+    'GET /api/v1/restores': 'read',
+    'POST /api/v1/restores/:id/release': 'admin',
+    'POST /api/v1/restores/:id/resume': 'admin',
+    'GET /api/v1/backup/destination': 'admin',
+    'POST /api/v1/backup/destination': 'admin',
+    'DELETE /api/v1/backup/destination': 'admin',
+    'GET /api/v1/backup/key': 'admin',
     'POST /api/v1/control/backups/run': 'admin',
     'POST /api/v1/control/restore': 'admin',
     'GET /api/v1/diagnostics': 'admin',
@@ -50,7 +59,6 @@ export const ROUTE_ROLES = {
     'POST /api/v1/tokens': 'admin',
     'GET /api/v1/tokens': 'admin',
     'DELETE /api/v1/tokens/:name': 'admin',
-    'POST /api/v1/registry/auth': 'public',
 };
 const statusError = (status, message) => Object.assign(new Error(message), { status });
 export const isRole = (value) => typeof value === 'string' && ROLES.includes(value);
@@ -98,46 +106,51 @@ const info = (row) => ({
     revokedAt: row.revoked_at,
 });
 /** Creates a token. The plaintext is returned once; only its hash is stored. */
-export async function createToken(db, request, createdBy) {
+export function createToken(db, request, createdBy) {
     const value = token(TOKEN_PREFIX);
     try {
-        await db.run('INSERT INTO api_tokens(id,name,token_hash,role,projects_json,created_at,created_by,expires_at) VALUES(?,?,?,?,?,?,?,?)', id('tok'), request.name, hashToken(value), request.role, request.projects ? JSON.stringify(request.projects) : null, now(), createdBy, request.expiresAt);
+        db.run('INSERT INTO api_tokens(id,name,token_hash,role,projects_json,created_at,created_by,expires_at) VALUES(?,?,?,?,?,?,?,?)', id('tok'), request.name, hashToken(value), request.role, request.projects ? JSON.stringify(request.projects) : null, now(), createdBy, request.expiresAt);
     }
     catch (e) {
-        if (/UNIQUE constraint/.test(e.message))
+        if (isUniqueViolation(e))
             throw statusError(409, `token name ${request.name} is already used (revoked tokens keep their names for the audit trail)`);
         throw e;
     }
     return {
-        ...info((await db.get('SELECT * FROM api_tokens WHERE name=?', request.name))),
+        ...info(db.get('SELECT * FROM api_tokens WHERE name=?', request.name)),
         token: value,
     };
 }
-export async function listTokens(db) {
-    return (await db.all('SELECT * FROM api_tokens ORDER BY created_at, name')).map(info);
+export function listTokens(db) {
+    return db.all('SELECT * FROM api_tokens ORDER BY created_at, name').map(info);
 }
 /** Revokes a token immediately. Returns false if no such token exists; revoking twice keeps the first revocation time. */
-export async function revokeToken(db, name) {
-    const row = await db.get('SELECT * FROM api_tokens WHERE name=?', name);
+export function revokeToken(db, name) {
+    const row = db.get('SELECT * FROM api_tokens WHERE name=?', name);
     if (!row)
         return false;
-    await db.run('UPDATE api_tokens SET revoked_at=? WHERE id=? AND revoked_at IS NULL', now(), row.id);
+    db.run('UPDATE api_tokens SET revoked_at=? WHERE id=? AND revoked_at IS NULL', now(), row.id);
     return true;
 }
 /** Resolves a bearer value to an actor by hash lookup: the root operator token first, then named tokens. */
-export async function authenticate(db, raw) {
+export function authenticate(db, raw) {
     if (!raw)
         return null;
     const hash = hashToken(raw);
-    const operator = await db.get('SELECT value FROM meta WHERE key=?', 'operator_token_hash');
+    const operator = db.get('SELECT value FROM meta WHERE key=?', 'operator_token_hash');
     if (operator && hash === operator.value)
         return { name: OPERATOR_ACTOR, role: 'admin', projects: null };
-    const row = await db.get('SELECT * FROM api_tokens WHERE token_hash=?', hash);
+    const row = db.get('SELECT * FROM api_tokens WHERE token_hash=?', hash);
     if (!row || row.revoked_at || (row.expires_at && row.expires_at <= now()))
         return null;
-    // Best effort and throttled: a slow or failing bookkeeping write must never fail or delay the request.
+    // Best effort and throttled: bookkeeping failures must never fail authentication.
     if (!row.last_used_at || Date.parse(row.last_used_at) < Date.now() - LAST_USED_INTERVAL_MS)
-        void db.run('UPDATE api_tokens SET last_used_at=? WHERE id=?', now(), row.id).catch(() => { });
+        try {
+            db.run('UPDATE api_tokens SET last_used_at=? WHERE id=?', now(), row.id);
+        }
+        catch {
+            /* Best-effort bookkeeping. */
+        }
     return {
         name: row.name,
         role: row.role,
@@ -156,7 +169,7 @@ export function assertProject(actor, project) {
 export function createGuard(db) {
     return (required, resolve) => async (req, res, next) => {
         try {
-            const actor = await authenticate(db, (req.headers.authorization || '').replace(/^Bearer /, ''));
+            const actor = authenticate(db, (req.headers.authorization || '').replace(/^Bearer /, ''));
             if (!actor) {
                 res.status(401).json({ error: 'unauthorized' });
                 return;
@@ -186,6 +199,6 @@ export function createGuard(db) {
     };
 }
 /** Appends a control-originated audit event naming the acting token. */
-export async function recordEvent(db, event) {
-    await db.run('INSERT INTO events(id,project_id,deployment_id,node_id,level,type,message,metadata_json,created_at,actor) VALUES(?,?,?,?,?,?,?,?,?,?)', id('evt'), event.project ?? null, event.deploymentId ?? null, null, 'info', event.type, event.message, JSON.stringify(event.metadata ?? {}), now(), event.actor);
+export function recordEvent(db, event) {
+    db.run('INSERT INTO events(id,project_id,deployment_id,node_id,level,type,message,metadata_json,created_at,actor) VALUES(?,?,?,?,?,?,?,?,?,?)', id('evt'), event.project ?? null, event.deploymentId ?? null, null, 'info', event.type, event.message, JSON.stringify(event.metadata ?? {}), now(), event.actor);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpelevator/tug",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Portable VPS deployments with Docker Compose",
   "repository": {
     "type": "git",
@@ -29,6 +29,7 @@
     "test:integration": "bash tools/scripts/integration-test.sh",
     "test:integration:network": "bash tools/scripts/integration-network-test.sh",
     "test:integration:agent": "node --test 'tests/integration/**/*.test.ts'",
+    "test:integration:backups": "node --test tests/integration/backup-job.test.ts tests/integration/run-job.test.ts",
     "test:smoke:dist": "npm run build && CLI_ENTRY=dist/cli.js node --test src/cli.templates.test.ts",
     "changeset": "changeset",
     "version-packages": "changeset version && npm install --package-lock-only --ignore-scripts",
@@ -43,8 +44,6 @@
     "express": "^4.21.2",
     "js-yaml": "^4.1.0",
     "multer": "^2.2.0",
-    "sqlite": "^5.1.1",
-    "sqlite3": "^5.1.7",
     "tar": "^7.4.3",
     "ws": "^8.22.1"
   },