@wpelevator/tug 0.7.0 → 0.8.0

package/dist/credentials.d.ts

@@ -0,0 +1,111 @@
+import type { Request, RequestHandler } from 'express';
+import type { Db, EnrollmentCredentialRow, NodeRow } from './db.ts';
+import type { Credential, Pki } from './pki.ts';
+/** Roles are cumulative: `deploy` includes `read`, and `admin` includes both. */
+export declare const ROLES: readonly ["read", "deploy", "admin"];
+export type Role = (typeof ROLES)[number];
+export type RouteRole = Role | 'public';
+/** Name of the admin credential issued on the control host at installation. It is an ordinary named admin. */
+export declare const ROOT_ACTOR = "root";
+/** Reserved actor for rollbacks control starts on its own. Credential names cannot contain a colon, so none can use it. */
+export declare const AUTO_ROLLBACK_ACTOR = "system:auto-rollback";
+export declare const CREDENTIAL_NAME_PATTERN: RegExp;
+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. 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. */
+export interface Actor {
+    name: string;
+    role: Role;
+    projects: string[] | null;
+}
+export interface CredentialRow {
+    id: string;
+    name: string;
+    key_hash: string;
+    role: Role;
+    projects_json: string | null;
+    created_at: string;
+    created_by: string;
+    last_used_at: string | null;
+    expires_at: string | null;
+    revoked_at: string | null;
+}
+export interface CredentialInfo {
+    name: string;
+    role: Role;
+    projects: string[] | null;
+    createdAt: string;
+    createdBy: string;
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+    revokedAt: string | null;
+}
+/** The principal behind a request, resolved from the client certificate and current database state. */
+export type Identity = {
+    klass: 'node';
+    node: NodeRow;
+} | {
+    klass: 'operator';
+    actor: Actor;
+    credentialId: string;
+} | {
+    klass: 'enroll';
+    row: EnrollmentCredentialRow;
+};
+declare module 'express-serve-static-core' {
+    interface Request {
+        identity?: Identity;
+        actor?: Actor;
+    }
+}
+export declare const isRole: (value: unknown) => value is Role;
+export declare const hasRole: (actor: Actor, required: Role) => boolean;
+/** Validates a credential request body, throwing a 400 error describing the first problem. */
+export declare function parseCredentialRequest(body: unknown): {
+    name: string;
+    role: Role;
+    projects: string[] | null;
+    expiresAt: string;
+};
+/**
+ * Creates an operator credential. Control generates the keypair, stores only the key hash and returns the credential once;
+ * the certificate and the database row expire together.
+ */
+export declare function createCredential(db: Db, pki: Pki, url: string, request: ReturnType<typeof parseCredentialRequest>, createdBy: string, options?: {
+    replace?: boolean;
+}): Promise<CredentialInfo & {
+    credential: Credential;
+}>;
+export declare function listCredentials(db: Db): CredentialInfo[];
+/** Revokes a credential immediately. Returns false if no such credential exists; revoking twice keeps the first revocation time. */
+export declare function revokeCredential(db: Db, name: string): boolean;
+/**
+ * Resolves an operator certificate identity to an actor from current database state: the principal must exist, the
+ * certificate's key must be the stored key, and the credential must be neither revoked nor expired.
+ */
+export declare function authenticate(db: Db, credentialId: string, keyHash: 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 credentials without saying why, so they
+ * cannot probe which IDs or projects exist.
+ */
+export type ProjectResolver = (req: Request) => string | null | undefined | Promise<string | null | undefined>;
+export declare const bodyProject: ProjectResolver;
+export declare const queryProject: ProjectResolver;
+/** Throws 403 unless the actor may act on `project`. Used where the project is only known after the body is parsed. */
+export declare function assertProject(actor: Actor, project: string): void;
+/** Builds the request guard: read the operator identity resolved by the class gate (401), check the role (403), then check project scope (403). */
+export declare function createGuard(): (required: Role, resolve?: ProjectResolver) => RequestHandler;
+/** Appends a control-originated audit event naming the acting credential. */
+export declare function recordEvent(db: Db, event: {
+    actor: string;
+    type: string;
+    message: string;
+    project?: string | null;
+    deploymentId?: string | null;
+    metadata?: Record<string, unknown>;
+}): void;

package/dist/{tokens.js → credentials.js}

@@ -1,21 +1,20 @@
 import { isUniqueViolation } from "./db-driver.js";
-import { hashToken, id, now, token } from "./util.js";
+import { id, now } from "./util.js";
+import { OPERATOR_MAX_LIFETIME_MS, identityUri } from "./pki.js";
 /** Roles are cumulative: `deploy` includes `read`, and `admin` includes both. */
 export const ROLES = ['read', 'deploy', 'admin'];
 const RANK = { read: 1, deploy: 2, admin: 3 };
-/** Name recorded in the audit trail for the root operator token. */
-export const OPERATOR_ACTOR = 'operator';
-/** Reserved actor for rollbacks control starts on its own. Token names cannot contain a colon, so no token can use it. */
+/** Name of the admin credential issued on the control host at installation. It is an ordinary named admin. */
+export const ROOT_ACTOR = 'root';
+/** Reserved actor for rollbacks control starts on its own. Credential names cannot contain a colon, so none can use it. */
 export const AUTO_ROLLBACK_ACTOR = 'system:auto-rollback';
-export const TOKEN_PREFIX = 'tug_tok';
-export const TOKEN_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$/;
+export const CREDENTIAL_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$/;
 export const PROJECT_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
-/** `last_used_at` is refreshed at most this often per token, so reads do not turn into writes. */
+/** `last_used_at` is refreshed at most this often per credential, so reads do not turn into writes. */
 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 and are not behind the token guard. docs/access-control.md mirrors this table.
+ * register an unlisted route, and a test compares this table with the live router. docs/access-control.md mirrors this table.
  */
 export const ROUTE_ROLES = {
     'GET /api/v1/live': 'deploy',
@@ -37,8 +36,9 @@ export const ROUTE_ROLES = {
     'DELETE /api/v1/secrets/:name': 'admin',
     'DELETE /api/v1/volumes/:name': 'admin',
     'GET /api/v1/nodes': 'admin',
-    'POST /api/v1/nodes/register': 'admin',
-    'POST /api/v1/nodes/enroll-token': 'admin',
+    'POST /api/v1/nodes/enrollment-credential': 'admin',
+    'POST /api/v1/nodes/:name/identity': 'admin',
+    'POST /api/v1/nodes/:name/disable': 'admin',
     'POST /api/v1/nodes/:name/rotate-wg-key': 'admin',
     'POST /api/v1/nodes/:name/ingress': 'admin',
     'DELETE /api/v1/nodes/:name': 'admin',
@@ -51,26 +51,24 @@ export const ROUTE_ROLES = {
     'GET /api/v1/backup/destination': 'admin',
     'POST /api/v1/backup/destination': 'admin',
     'DELETE /api/v1/backup/destination': 'admin',
-    'GET /api/v1/backup/key': 'admin',
+    'GET /api/v1/backup/repository-password': 'admin',
     'POST /api/v1/control/backups/run': 'admin',
     'POST /api/v1/control/restore': 'admin',
     'GET /api/v1/diagnostics': 'admin',
     'POST /api/v1/diagnostics/nodes': 'admin',
-    'POST /api/v1/tokens': 'admin',
-    'GET /api/v1/tokens': 'admin',
-    'DELETE /api/v1/tokens/:name': 'admin',
+    'POST /api/v1/credentials': 'admin',
+    'GET /api/v1/credentials': 'admin',
+    'DELETE /api/v1/credentials/:name': 'admin',
 };
 const statusError = (status, message) => Object.assign(new Error(message), { status });
 export const isRole = (value) => typeof value === 'string' && ROLES.includes(value);
 export const hasRole = (actor, required) => RANK[actor.role] >= RANK[required];
-/** Validates a token request body, throwing a 400 error describing the first problem. */
-export function parseTokenRequest(body) {
+/** Validates a credential request body, throwing a 400 error describing the first problem. */
+export function parseCredentialRequest(body) {
     const input = (body && typeof body === 'object' ? body : {});
     const { name, role, projects, expiresInSeconds } = input;
-    if (typeof name !== 'string' || !TOKEN_NAME_PATTERN.test(name))
-        throw statusError(400, 'token name must be 1-64 letters, numbers, dots, underscores or hyphens, starting with a letter or number');
-    if (name === OPERATOR_ACTOR)
-        throw statusError(400, `token name ${OPERATOR_ACTOR} is reserved for the root operator token`);
+    if (typeof name !== 'string' || !CREDENTIAL_NAME_PATTERN.test(name))
+        throw statusError(400, 'credential name must be 1-64 letters, numbers, dots, underscores or hyphens, starting with a letter or number');
     if (!isRole(role))
         throw statusError(400, `role must be one of ${ROLES.join(', ')}`);
     let scope = null;
@@ -81,16 +79,16 @@ export function parseTokenRequest(body) {
             projects.some((p) => typeof p !== 'string' || !PROJECT_NAME_PATTERN.test(p)))
             throw statusError(400, 'projects must be a nonempty list of valid project names, or omitted for all projects');
         if (role === 'admin')
-            throw statusError(400, 'admin tokens manage the whole control plane and cannot be limited to projects');
+            throw statusError(400, 'admin credentials manage the whole control plane and cannot be limited to projects');
         scope = [...new Set(projects)].sort();
     }
-    let expiresAt = null;
+    let expiresAt = new Date(Date.now() + OPERATOR_MAX_LIFETIME_MS).toISOString();
     if (expiresInSeconds !== undefined && expiresInSeconds !== null) {
         if (typeof expiresInSeconds !== 'number' ||
             !Number.isSafeInteger(expiresInSeconds) ||
             expiresInSeconds < 1 ||
-            expiresInSeconds > 10 * 365 * 86400)
-            throw statusError(400, 'expiresInSeconds must be a positive integer of at most ten years');
+            expiresInSeconds > OPERATOR_MAX_LIFETIME_MS / 1000)
+            throw statusError(400, 'expiresInSeconds must be a positive integer of at most one year');
         expiresAt = new Date(Date.now() + expiresInSeconds * 1000).toISOString();
     }
     return { name, role, projects: scope, expiresAt };
@@ -105,48 +103,66 @@ const info = (row) => ({
     expiresAt: row.expires_at,
     revokedAt: row.revoked_at,
 });
-/** Creates a token. The plaintext is returned once; only its hash is stored. */
-export function createToken(db, request, createdBy) {
-    const value = token(TOKEN_PREFIX);
+/**
+ * Creates an operator credential. Control generates the keypair, stores only the key hash and returns the credential once;
+ * the certificate and the database row expire together.
+ */
+export async function createCredential(db, pki, url, request, createdBy, options = {}) {
+    const credentialId = id('cred');
+    const lifetime = Math.min(Date.parse(request.expiresAt) - Date.now(), OPERATOR_MAX_LIFETIME_MS);
+    const issued = await pki.issueClient(identityUri('operator', credentialId), lifetime, url);
+    const expiresAt = issued.notAfter.toISOString();
     try {
-        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);
+        if (options.replace) {
+            const existing = db.get('SELECT * FROM operator_credentials WHERE name=?', request.name);
+            if (existing) {
+                db.run('UPDATE operator_credentials SET id=?,key_hash=?,role=?,projects_json=?,created_at=?,created_by=?,last_used_at=NULL,expires_at=?,revoked_at=NULL WHERE name=?', credentialId, issued.keyHash, request.role, request.projects ? JSON.stringify(request.projects) : null, now(), createdBy, expiresAt, request.name);
+                return {
+                    ...info(db.get('SELECT * FROM operator_credentials WHERE name=?', request.name)),
+                    credential: issued.credential,
+                };
+            }
+        }
+        db.run('INSERT INTO operator_credentials(id,name,key_hash,role,projects_json,created_at,created_by,expires_at) VALUES(?,?,?,?,?,?,?,?)', credentialId, request.name, issued.keyHash, request.role, request.projects ? JSON.stringify(request.projects) : null, now(), createdBy, expiresAt);
     }
     catch (e) {
         if (isUniqueViolation(e))
-            throw statusError(409, `token name ${request.name} is already used (revoked tokens keep their names for the audit trail)`);
+            throw statusError(409, `credential name ${request.name} is already used (revoked credentials keep their names for the audit trail)`);
         throw e;
     }
     return {
-        ...info(db.get('SELECT * FROM api_tokens WHERE name=?', request.name)),
-        token: value,
+        ...info(db.get('SELECT * FROM operator_credentials WHERE name=?', request.name)),
+        credential: issued.credential,
     };
 }
-export function listTokens(db) {
-    return db.all('SELECT * FROM api_tokens ORDER BY created_at, name').map(info);
+export function listCredentials(db) {
+    return db
+        .all('SELECT * FROM operator_credentials 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 function revokeToken(db, name) {
-    const row = db.get('SELECT * FROM api_tokens WHERE name=?', name);
+/** Revokes a credential immediately. Returns false if no such credential exists; revoking twice keeps the first revocation time. */
+export function revokeCredential(db, name) {
+    const row = db.get('SELECT * FROM operator_credentials WHERE name=?', name);
     if (!row)
         return false;
-    db.run('UPDATE api_tokens SET revoked_at=? WHERE id=? AND revoked_at IS NULL', now(), row.id);
+    db.run('UPDATE operator_credentials 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 function authenticate(db, raw) {
-    if (!raw)
-        return null;
-    const hash = hashToken(raw);
-    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 = db.get('SELECT * FROM api_tokens WHERE token_hash=?', hash);
-    if (!row || row.revoked_at || (row.expires_at && row.expires_at <= now()))
+/**
+ * Resolves an operator certificate identity to an actor from current database state: the principal must exist, the
+ * certificate's key must be the stored key, and the credential must be neither revoked nor expired.
+ */
+export function authenticate(db, credentialId, keyHash) {
+    const row = db.get('SELECT * FROM operator_credentials WHERE id=?', credentialId);
+    if (!row ||
+        row.key_hash !== keyHash ||
+        row.revoked_at ||
+        (row.expires_at && row.expires_at <= now()))
         return null;
     // 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)
         try {
-            db.run('UPDATE api_tokens SET last_used_at=? WHERE id=?', now(), row.id);
+            db.run('UPDATE operator_credentials SET last_used_at=? WHERE id=?', now(), row.id);
         }
         catch {
             /* Best-effort bookkeeping. */
@@ -159,17 +175,17 @@ export function authenticate(db, raw) {
 }
 export const bodyProject = (req) => String(req.body?.project || 'site');
 export const queryProject = (req) => String(req.query.project || 'site');
-const FORBIDDEN_PROJECT = 'forbidden: this token may not access that project';
+const FORBIDDEN_PROJECT = 'forbidden: this credential may not access that project';
 /** Throws 403 unless the actor may act on `project`. Used where the project is only known after the body is parsed. */
 export function assertProject(actor, project) {
     if (actor.projects && !actor.projects.includes(project))
         throw statusError(403, FORBIDDEN_PROJECT);
 }
-/** Builds the request guard: authenticate (401), check the role (403), then check project scope (403). */
-export function createGuard(db) {
+/** Builds the request guard: read the operator identity resolved by the class gate (401), check the role (403), then check project scope (403). */
+export function createGuard() {
     return (required, resolve) => async (req, res, next) => {
         try {
-            const actor = authenticate(db, (req.headers.authorization || '').replace(/^Bearer /, ''));
+            const actor = req.identity?.klass === 'operator' ? req.identity.actor : null;
             if (!actor) {
                 res.status(401).json({ error: 'unauthorized' });
                 return;
@@ -198,7 +214,7 @@ export function createGuard(db) {
         }
     };
 }
-/** Appends a control-originated audit event naming the acting token. */
+/** Appends a control-originated audit event naming the acting credential. */
 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/dist/db.d.ts

@@ -9,6 +9,7 @@ export interface ProjectRow {
     updated_at: string;
 }
 export interface NodeRow {
+    /** Immutable and random (`node_...`): never derived from the name and never reused after the node is removed. */
     id: string;
     name: string;
     address: string | null;
@@ -18,8 +19,15 @@ export interface NodeRow {
     ingress_status_json: string | null;
     status: string;
     labels_json: string | null;
-    agent_token_hash: string | null;
+    /** SHA-256 of the node key's SubjectPublicKeyInfo: the identity the node is authorized by. */
+    key_hash: string | null;
+    disabled_at: string | null;
+    cert_not_after: string | null;
+    last_renewed_at: string | null;
     last_seen_at: string | null;
+    /** The node clock minus the control clock when its last status report arrived, in milliseconds (includes request latency). */
+    clock_skew_ms: number | null;
+    clock_observed_at: string | null;
     created_at: string;
     updated_at: string;
 }
@@ -31,11 +39,18 @@ export interface WgPeerRow {
     allowed_ips: string;
     updated_at: string;
 }
-export interface EnrollTokenRow {
-    token_hash: string;
-    name: string | null;
-    uses_remaining: number;
+export interface EnrollmentCredentialRow {
+    id: string;
+    key_hash: string;
+    name: string;
+    labels_json: string | null;
     expires_at: string;
+    revoked_at: string | null;
+    /** Set when the key is consumed: the node created from it. Null while unconsumed. */
+    node_id: string | null;
+    /** The immutable node ID this key will create, assigned when the key is minted so the bootstrap flow signs a stable identity. */
+    reserved_node_id: string;
+    node_key_hash: string | null;
     created_at: string;
 }
 export interface DeploymentRow {

package/dist/db.js

@@ -54,9 +54,9 @@ function initializeControl(db) {
     db.exec(`
 CREATE TABLE IF NOT EXISTS meta(key TEXT PRIMARY KEY, value TEXT NOT NULL);
 CREATE TABLE IF NOT EXISTS projects(id TEXT PRIMARY KEY, name TEXT UNIQUE NOT NULL, current_deployment_id TEXT, created_at TEXT, updated_at TEXT);
-CREATE TABLE IF NOT EXISTS nodes(id TEXT PRIMARY KEY, name TEXT UNIQUE NOT NULL, address TEXT, public_address TEXT, overlay_ip TEXT UNIQUE, ingress INTEGER NOT NULL DEFAULT 0, ingress_status_json TEXT, status TEXT, labels_json TEXT, agent_token_hash TEXT, last_seen_at TEXT, created_at TEXT, updated_at TEXT);
+CREATE TABLE IF NOT EXISTS nodes(id TEXT PRIMARY KEY, name TEXT UNIQUE NOT NULL, address TEXT, public_address TEXT, overlay_ip TEXT UNIQUE, ingress INTEGER NOT NULL DEFAULT 0, ingress_status_json TEXT, status TEXT, labels_json TEXT, key_hash TEXT, disabled_at TEXT, cert_not_after TEXT, last_renewed_at TEXT, last_seen_at TEXT, clock_skew_ms INTEGER, clock_observed_at TEXT, created_at TEXT, updated_at TEXT);
 CREATE TABLE IF NOT EXISTS wg_peers(node_id TEXT PRIMARY KEY, public_key TEXT NOT NULL UNIQUE, overlay_ip TEXT NOT NULL, endpoint TEXT, allowed_ips TEXT NOT NULL, updated_at TEXT);
-CREATE TABLE IF NOT EXISTS enroll_tokens(token_hash TEXT PRIMARY KEY, name TEXT, uses_remaining INTEGER, expires_at TEXT, created_at TEXT);
+CREATE TABLE IF NOT EXISTS enrollment_credentials(id TEXT PRIMARY KEY, key_hash TEXT UNIQUE NOT NULL, name TEXT NOT NULL, labels_json TEXT, expires_at TEXT NOT NULL, revoked_at TEXT, node_id TEXT, reserved_node_id TEXT NOT NULL, node_key_hash TEXT, created_at TEXT);
 CREATE TABLE IF NOT EXISTS deployments(id TEXT PRIMARY KEY, project_id TEXT, version TEXT, state TEXT, created_at TEXT, updated_at TEXT, error_message TEXT, actor TEXT);
 CREATE TABLE IF NOT EXISTS desired_states(id TEXT PRIMARY KEY, project_id TEXT, deployment_id TEXT, version TEXT, state_json TEXT, created_at TEXT);
 CREATE TABLE IF NOT EXISTS node_statuses(id TEXT PRIMARY KEY, node_id TEXT, project_id TEXT, observed_version TEXT, status_json TEXT, health TEXT, updated_at TEXT, UNIQUE(node_id, project_id));
@@ -67,7 +67,7 @@ CREATE TABLE IF NOT EXISTS backups(id TEXT PRIMARY KEY, project_id TEXT, target
 CREATE TABLE IF NOT EXISTS commands(id TEXT PRIMARY KEY, node_id TEXT, project_id TEXT, type TEXT, state TEXT, payload_json TEXT, result_json TEXT, attempts INTEGER DEFAULT 0, run_after TEXT, deadline TEXT, created_at TEXT, updated_at TEXT);
 CREATE TABLE IF NOT EXISTS events(id TEXT PRIMARY KEY, project_id TEXT, deployment_id TEXT, node_id TEXT, level TEXT, type TEXT, message TEXT, metadata_json TEXT, created_at TEXT, actor TEXT);
 CREATE INDEX IF NOT EXISTS events_project_created ON events(project_id, created_at);
-CREATE TABLE IF NOT EXISTS api_tokens(id TEXT PRIMARY KEY, name TEXT UNIQUE NOT NULL, token_hash TEXT UNIQUE NOT NULL, role TEXT NOT NULL, projects_json TEXT, created_at TEXT, created_by TEXT, last_used_at TEXT, expires_at TEXT, revoked_at TEXT);
+CREATE TABLE IF NOT EXISTS operator_credentials(id TEXT PRIMARY KEY, name TEXT UNIQUE NOT NULL, key_hash TEXT UNIQUE NOT NULL, role TEXT NOT NULL, projects_json TEXT, created_at TEXT, created_by TEXT, last_used_at TEXT, expires_at TEXT, revoked_at TEXT);
 CREATE INDEX IF NOT EXISTS events_by_time ON events(created_at);
 CREATE TABLE IF NOT EXISTS locks(name TEXT PRIMARY KEY, owner TEXT, expires_at TEXT, created_at TEXT);
 CREATE TABLE IF NOT EXISTS backup_destination(id TEXT PRIMARY KEY CHECK(id='default'), url TEXT NOT NULL, env_names_json TEXT NOT NULL, checked_at TEXT, check_result_json TEXT, updated_at TEXT);

package/dist/diagnostics.d.ts

@@ -0,0 +1,44 @@
+/** Days of remaining validity below which each certificate kind is reported as expiring (renewal is overdue). */
+export declare const EXPIRY_WARN_DAYS: {
+    readonly ca: 90;
+    readonly server: 30;
+    readonly node: 14;
+};
+/** A clock this far from control's is worth a look; it is far below the five-minute certificate back-dating. */
+export declare const SKEW_WARN_MS = 30000;
+/** At this skew new certificates look not yet valid (or old ones expired) to the node, so renewal and TLS break. */
+export declare const SKEW_FAIL_MS: number;
+export type ExpiryState = 'ok' | 'expiring' | 'expired';
+export interface CertificateExpiry {
+    notAfter: string;
+    daysLeft: number;
+    state: ExpiryState;
+}
+export declare function certificateExpiry(notAfter: Date, nowMs: number, warnDays: number): CertificateExpiry;
+/** Clock skew is only known for a node that is reporting now; an offline node has an unknown clock, not a zero skew. */
+export type ClockSkew = {
+    state: 'observed';
+    ms: number;
+    observedAt: string;
+} | {
+    state: 'unknown';
+    reason: 'offline' | 'never reported' | 'disabled';
+};
+export type Connectivity = 'online' | 'stale' | 'never-seen' | 'disabled';
+export interface NodeDiagnosticInput {
+    name: string;
+    disabled_at: string | null;
+    last_seen_at: string | null;
+    cert_not_after: string | null;
+    clock_skew_ms: number | null;
+    clock_observed_at: string | null;
+}
+export interface NodeDiagnostic {
+    name: string;
+    connectivity: Connectivity;
+    certificate: CertificateExpiry | null;
+    clockSkew: ClockSkew;
+    problems: string[];
+    warnings: string[];
+}
+export declare function diagnoseNode(node: NodeDiagnosticInput, nowMs: number, staleSeconds: number): NodeDiagnostic;

package/dist/diagnostics.js

@@ -0,0 +1,65 @@
+import { BACKDATE_MS } from "./pki.js";
+const DAY = 86_400_000;
+/** Days of remaining validity below which each certificate kind is reported as expiring (renewal is overdue). */
+export const EXPIRY_WARN_DAYS = { ca: 90, server: 30, node: 14 };
+/** A clock this far from control's is worth a look; it is far below the five-minute certificate back-dating. */
+export const SKEW_WARN_MS = 30_000;
+/** At this skew new certificates look not yet valid (or old ones expired) to the node, so renewal and TLS break. */
+export const SKEW_FAIL_MS = BACKDATE_MS;
+export function certificateExpiry(notAfter, nowMs, warnDays) {
+    const left = notAfter.getTime() - nowMs;
+    return {
+        notAfter: notAfter.toISOString(),
+        daysLeft: Math.floor(left / DAY),
+        state: left <= 0 ? 'expired' : left < warnDays * DAY ? 'expiring' : 'ok',
+    };
+}
+export function diagnoseNode(node, nowMs, staleSeconds) {
+    const staleBefore = nowMs - staleSeconds * 1000;
+    const fresh = (iso) => !!iso && Date.parse(iso) >= staleBefore;
+    const connectivity = node.disabled_at
+        ? 'disabled'
+        : !node.last_seen_at
+            ? 'never-seen'
+            : fresh(node.last_seen_at)
+                ? 'online'
+                : 'stale';
+    const certificate = node.cert_not_after
+        ? certificateExpiry(new Date(node.cert_not_after), nowMs, EXPIRY_WARN_DAYS.node)
+        : null;
+    let clockSkew;
+    if (connectivity === 'online' && node.clock_skew_ms !== null && fresh(node.clock_observed_at))
+        clockSkew = {
+            state: 'observed',
+            ms: node.clock_skew_ms,
+            observedAt: node.clock_observed_at,
+        };
+    else
+        clockSkew = {
+            state: 'unknown',
+            reason: connectivity === 'disabled'
+                ? 'disabled'
+                : connectivity === 'online'
+                    ? 'never reported'
+                    : connectivity === 'never-seen'
+                        ? 'never reported'
+                        : 'offline',
+        };
+    const problems = [];
+    const warnings = [];
+    // A disabled node's certificate is irrelevant until it is replaced, so it never fails the diagnostics.
+    const report = connectivity === 'disabled' ? warnings : problems;
+    if (certificate?.state === 'expired')
+        report.push(`certificate expired ${certificate.notAfter}; run node-replace-identity ${node.name}`);
+    else if (certificate?.state === 'expiring')
+        warnings.push(`certificate expires in ${certificate.daysLeft} days and has not renewed; check the agent logs on node ${node.name}`);
+    if (clockSkew.state === 'observed') {
+        const abs = Math.abs(clockSkew.ms);
+        const seconds = Math.round(clockSkew.ms / 1000);
+        if (abs >= SKEW_FAIL_MS)
+            problems.push(`clock differs from the control plane by ${seconds}s (certificates are back-dated ${BACKDATE_MS / 60_000} minutes); fix time sync on node ${node.name}`);
+        else if (abs >= SKEW_WARN_MS)
+            warnings.push(`clock differs from the control plane by ${seconds}s`);
+    }
+    return { name: node.name, connectivity, certificate, clockSkew, problems, warnings };
+}

package/dist/ingress.js

@@ -1,11 +1,12 @@
-// Service endpoints (health-aware DNS source), ingress route resolution and Caddyfile rendering
+// Service endpoints (the source of cross-node service names), ingress route resolution and Caddyfile rendering
 // on the control side; the managed Caddy container reconcile on the agent side. Docker access goes
-// through the injectable DockerRunner.
+// through the injectable DockerApi.
 import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { loopbackIngressServices, publishedPort } from "./compose.js";
 import { ensureDir, errMessage } from "./util.js";
+import { isPort } from "./status-report.js";
 import * as tar from 'tar';
 import { isNotFound } from "./docker-api.js";
 export const CADDY_CONTAINER = 'tug-caddy';
@@ -35,7 +36,7 @@ export function resolveServiceEndpoints(states, nodes, statuses, staleBefore) {
                 endpoints.push({
                     node: nodeName,
                     address,
-                    ...(serviceState.port ? { port: serviceState.port } : {}),
+                    ...(isPort(serviceState.port) ? { port: serviceState.port } : {}),
                 });
             }
             if (endpoints.length)

package/dist/main.js

@@ -1,14 +1,49 @@
 #!/usr/bin/env node
 // Single entrypoint for the control plane and agent images; role picked via TUG_ROLE or argv.
 const role = process.argv[2] || process.env.TUG_ROLE;
+const command = process.argv[3];
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+const usage = `Usage: tug-runtime <control|agent> [command]
+  control                          run the control plane (needs TUG_PUBLIC_URL)
+  control issue-credential         issue an operator credential on the control-plane host (--name, --role, --replace)
+  agent                            run the node agent
+  agent identity                   print the CSR for this node's pending key
+  agent install-cert               install an identity response read from stdin`;
+if (process.argv.slice(2).some((a) => a === '--help' || a === '-h' || a === 'help')) {
+    console.log(usage);
+    process.exit(0);
+}
 switch (role) {
     case 'control': {
+        if (command === 'issue-credential') {
+            const { issueHostCredential, parseIssueArgs } = await import("./control-credential.js");
+            process.stdout.write(`${await issueHostCredential(parseIssueArgs(process.argv.slice(4)))}\n`);
+            break;
+        }
         const { createApp, listen } = await import("./control.js");
         const app = await createApp();
         await listen(app);
         break;
     }
     case 'agent': {
+        if (command === 'identity') {
+            // One-shot: print the CSR for the pending key (generated into the state volume on first use). Safe to repeat.
+            const { agentIdentityCsr } = await import("./agent-credential.js");
+            process.stdout.write(await agentIdentityCsr(process.env.TUG_STATE_DIR || '/var/lib/tug'));
+            break;
+        }
+        if (command === 'install-cert') {
+            // One-shot: read the identity response from stdin, validate it against the pending key and install it durably.
+            const { installCertFromText } = await import("./agent-credential.js");
+            const doc = await installCertFromText(process.env.TUG_STATE_DIR || '/var/lib/tug', await readStdin());
+            console.log(`installed identity for node ${doc.nodeName}`);
+            break;
+        }
         const { main } = await import("./agent.js");
         await main();
         break;

package/dist/normalize.js

@@ -4,7 +4,7 @@
 // (`x-tug`), while the YAML rendering keeps them.
 // Control secrets are not resolved on the operator's machine: each one is interpolated as a sentinel
 // that the agent replaces with the node's released value when it creates the container.
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 import { run } from "./build.js";
 const SECRET_NAME = '[A-Za-z_][A-Za-z0-9_]*';
 const SENTINEL = new RegExp(`@@tug:secret:(${SECRET_NAME})@@`, 'g');