@wpelevator/tug 0.6.0 → 0.8.0

package/dist/pki.d.ts

@@ -0,0 +1,119 @@
+import 'reflect-metadata';
+import crypto from 'node:crypto';
+import tls from 'node:tls';
+type CryptoKey = crypto.webcrypto.CryptoKey;
+type CryptoKeyPair = crypto.webcrypto.CryptoKeyPair;
+/** `notBefore` is back-dated so a host whose clock runs slightly slow can still install and renew. */
+export declare const BACKDATE_MS: number;
+export declare const CA_LIFETIME_MS: number;
+export declare const SERVER_LIFETIME_MS: number;
+export declare const NODE_LIFETIME_MS: number;
+export declare const OPERATOR_MAX_LIFETIME_MS: number;
+export declare const ENROLL_DEFAULT_TTL_MS: number;
+export type IdentityClass = 'node' | 'operator' | 'enroll';
+export declare const identityUri: (klass: IdentityClass, id: string) => string;
+export declare function parseIdentityUri(uri: string): {
+    klass: IdentityClass;
+    id: string;
+} | null;
+/** Everything a client needs to reach control: the public URL, the CA to trust and its own certificate and key. */
+export interface Credential {
+    v: 1;
+    url: string;
+    ca: string;
+    cert: string;
+    key: string;
+}
+export declare const encodeCredential: (credential: Credential) => string;
+/** Validates the shape and the HTTPS origin of an untrusted credential document, and that the key matches the certificate. */
+export declare function parseCredential(value: unknown): Credential;
+export declare function decodeCredential(text: string): Credential;
+export declare function assertKeyMatchesCertificate(certPem: string, keyPem: string): void;
+/** SHA-256 of the DER SubjectPublicKeyInfo: the identity a principal is authorized by. */
+export declare const hashSpki: (spki: Uint8Array | Buffer) => string;
+export declare const certKeyHash: (certPem: string) => string;
+/** Durable write: temporary file in the same directory, flushed, renamed over the target, directory flushed. */
+export interface PersistHooks {
+    /** Called after the temporary file is flushed and before the rename. Tests throw here to simulate a crash. */
+    afterFlush?: () => void;
+    /** Called after the rename and before the directory flush. */
+    afterRename?: () => void;
+}
+export declare function writeFileDurable(file: string, content: string, mode?: number, hooks?: PersistHooks): Promise<void>;
+export interface KeyPair {
+    privateKeyPem: string;
+    publicKey: CryptoKey;
+    privateKey: CryptoKey;
+}
+export declare function generateKeyPair(): Promise<KeyPair>;
+export declare function importPrivateKey(pem: string): Promise<CryptoKeyPair>;
+/** A PEM CSR for the key; the requester's subject is irrelevant because control assigns identities. */
+export declare function createCsr(privateKeyPem: string): Promise<string>;
+/** Parses a CSR, verifies its signature and requires a P-256 key. Returns the key hash and public key. */
+export declare function verifyCsr(csrPem: unknown): Promise<{
+    keyHash: string;
+    publicKey: CryptoKey;
+}>;
+export interface SubjectNames {
+    dns: string[];
+    ip: string[];
+}
+/** The DNS names and IP addresses a server certificate covers, from the public URL plus optional extras. */
+export declare function serverNames(publicUrl: string, extras?: string[]): SubjectNames;
+export declare const namesKey: (names: SubjectNames) => string;
+export declare class Pki {
+    readonly caPem: string;
+    private readonly caCert;
+    private readonly caKey;
+    private constructor();
+    get caNotAfter(): Date;
+    get caFingerprint(): string;
+    /** Loads the CA from `dir`, creating it only when `create` is set and no CA files exist. Corrupt or partial material fails closed. */
+    static load(dir: string, create: boolean): Promise<Pki>;
+    private static create;
+    /** Signs a leaf with an assigned profile. Requester-supplied subjects, SANs, validity and extensions are never used. */
+    signLeaf(options: {
+        publicKey: CryptoKey;
+        kind: 'client' | 'server';
+        uri?: string;
+        names?: SubjectNames;
+        lifetimeMs: number;
+    }): Promise<{
+        cert: string;
+        notAfter: Date;
+    }>;
+    /** Verifies a CSR and signs a client certificate naming `uri` for its key. */
+    signClientCsr(csrPem: unknown, uri: string, lifetimeMs: number): Promise<{
+        cert: string;
+        keyHash: string;
+        notAfter: Date;
+    }>;
+    /** A client keypair and certificate for `uri`, for credentials issued on control (operators, enrollment keys, root). */
+    issueClient(uri: string, lifetimeMs: number, url: string): Promise<{
+        credential: Credential;
+        keyHash: string;
+        notAfter: Date;
+    }>;
+    /** The server certificate and key for the given names. */
+    issueServer(names: SubjectNames): Promise<{
+        cert: string;
+        key: string;
+        notAfter: Date;
+    }>;
+}
+/** Checks that a certificate chains to `ca`, names `uri` and is bound to the key. Used by the agent before installing. */
+export declare function validateInstalledCertificate(options: {
+    cert: string;
+    ca: string;
+    keyPem: string;
+    uri: string;
+}): void;
+/** TLS client options pinned to the credential's CA. Verification is always against the public host, even through a tunnel. */
+export declare function clientTlsOptions(credential: Credential): tls.ConnectionOptions;
+/** The peer identity presented on a TLS socket, or null when none can be established. */
+export declare function peerIdentity(socket: tls.TLSSocket): {
+    uri: string;
+    keyHash: string;
+    notAfter: number;
+} | null;
+export {};

package/dist/pki.js

@@ -0,0 +1,339 @@
+import 'reflect-metadata';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import net from 'node:net';
+import path from 'node:path';
+import tls from 'node:tls';
+import * as x509 from '@peculiar/x509';
+x509.cryptoProvider.set(crypto.webcrypto);
+const SIGNING = { name: 'ECDSA', hash: 'SHA-256' };
+const KEY_ALG = { name: 'ECDSA', namedCurve: 'P-256' };
+const MINUTE = 60_000;
+const DAY = 86_400_000;
+/** `notBefore` is back-dated so a host whose clock runs slightly slow can still install and renew. */
+export const BACKDATE_MS = 5 * MINUTE;
+export const CA_LIFETIME_MS = 3650 * DAY;
+export const SERVER_LIFETIME_MS = 90 * DAY;
+export const NODE_LIFETIME_MS = 90 * DAY;
+export const OPERATOR_MAX_LIFETIME_MS = 365 * DAY;
+export const ENROLL_DEFAULT_TTL_MS = 60 * MINUTE;
+const IDENTITY_URI = /^tug:(node|operator|enroll):([A-Za-z0-9_.-]+)$/;
+export const identityUri = (klass, id) => `tug:${klass}:${id}`;
+export function parseIdentityUri(uri) {
+    const m = IDENTITY_URI.exec(uri);
+    return m ? { klass: m[1], id: m[2] } : null;
+}
+export const encodeCredential = (credential) => Buffer.from(JSON.stringify(credential)).toString('base64url');
+/** Validates the shape and the HTTPS origin of an untrusted credential document, and that the key matches the certificate. */
+export function parseCredential(value) {
+    if (!value || typeof value !== 'object')
+        throw new Error('credential must be a JSON object');
+    const c = value;
+    if (c.v !== 1)
+        throw new Error('credential version must be 1');
+    for (const field of ['url', 'ca', 'cert', 'key'])
+        if (typeof c[field] !== 'string' || !c[field])
+            throw new Error(`credential is missing ${field}`);
+    const url = new URL(c.url);
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash)
+        throw new Error('credential url must be a credential-free https origin');
+    if (url.pathname !== '/')
+        throw new Error('credential url must be an origin without a path');
+    const credential = c;
+    assertKeyMatchesCertificate(credential.cert, credential.key);
+    return credential;
+}
+export function decodeCredential(text) {
+    const trimmed = text.trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed.startsWith('{') ? trimmed : Buffer.from(trimmed, 'base64url').toString('utf8'));
+    }
+    catch (e) {
+        throw new Error('credential is not valid JSON or base64url-encoded JSON', { cause: e });
+    }
+    return parseCredential(parsed);
+}
+export function assertKeyMatchesCertificate(certPem, keyPem) {
+    const cert = new crypto.X509Certificate(certPem);
+    const derived = crypto.createPublicKey(crypto.createPrivateKey(keyPem));
+    if (!cert.checkPrivateKey(crypto.createPrivateKey(keyPem)) || !derived)
+        throw new Error('certificate does not match the private key');
+}
+/** SHA-256 of the DER SubjectPublicKeyInfo: the identity a principal is authorized by. */
+export const hashSpki = (spki) => crypto.createHash('sha256').update(spki).digest('hex');
+export const certKeyHash = (certPem) => hashSpki(new crypto.X509Certificate(certPem).publicKey.export({ type: 'spki', format: 'der' }));
+export async function writeFileDurable(file, content, mode = 0o600, hooks = {}) {
+    const dir = path.dirname(file);
+    await fs.mkdir(dir, { recursive: true });
+    const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`);
+    const handle = await fs.open(tmp, 'w', mode);
+    try {
+        await handle.writeFile(content);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        hooks.afterFlush?.();
+        await fs.rename(tmp, file);
+    }
+    catch (e) {
+        // A crash leaves the temporary file behind; a failed write must not.
+        await fs.rm(tmp, { force: true });
+        throw e;
+    }
+    hooks.afterRename?.();
+    const dirHandle = await fs.open(dir, 'r').catch(() => null);
+    if (dirHandle) {
+        await dirHandle.sync().catch(() => { });
+        await dirHandle.close();
+    }
+}
+export async function generateKeyPair() {
+    const keys = (await crypto.webcrypto.subtle.generateKey(KEY_ALG, true, [
+        'sign',
+        'verify',
+    ]));
+    const pkcs8 = Buffer.from(await crypto.webcrypto.subtle.exportKey('pkcs8', keys.privateKey));
+    return {
+        privateKeyPem: toPem(pkcs8, 'PRIVATE KEY'),
+        publicKey: keys.publicKey,
+        privateKey: keys.privateKey,
+    };
+}
+export async function importPrivateKey(pem) {
+    const privateKey = await crypto.webcrypto.subtle.importKey('pkcs8', pemToDer(pem), KEY_ALG, true, ['sign']);
+    const jwk = await crypto.webcrypto.subtle.exportKey('jwk', privateKey);
+    const publicKey = await crypto.webcrypto.subtle.importKey('jwk', { kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y }, KEY_ALG, true, ['verify']);
+    return { privateKey, publicKey };
+}
+const toPem = (der, label) => `-----BEGIN ${label}-----\n${der
+    .toString('base64')
+    .replace(/(.{64})/g, '$1\n')
+    .trimEnd()}\n-----END ${label}-----\n`;
+function pemToDer(pem) {
+    return Buffer.from(pem.replace(/-----[^-]+-----/g, '').replace(/\s+/g, ''), 'base64');
+}
+/** A PEM CSR for the key; the requester's subject is irrelevant because control assigns identities. */
+export async function createCsr(privateKeyPem) {
+    const keys = await importPrivateKey(privateKeyPem);
+    const csr = await x509.Pkcs10CertificateRequestGenerator.create({
+        name: 'CN=tug',
+        keys,
+        signingAlgorithm: SIGNING,
+    });
+    return csr.toString('pem');
+}
+/** Parses a CSR, verifies its signature and requires a P-256 key. Returns the key hash and public key. */
+export async function verifyCsr(csrPem) {
+    if (typeof csrPem !== 'string' || csrPem.length > 8192)
+        throw new Error('csr must be a PEM string');
+    let csr;
+    try {
+        csr = new x509.Pkcs10CertificateRequest(csrPem);
+    }
+    catch (e) {
+        throw new Error('csr is not a valid PKCS#10 request', { cause: e });
+    }
+    if (!(await csr.verify()))
+        throw new Error('csr signature is invalid');
+    const alg = csr.publicKey.algorithm;
+    if (alg.name !== 'ECDSA' || alg.namedCurve !== 'P-256')
+        throw new Error('csr key must be ECDSA P-256');
+    return {
+        keyHash: hashSpki(new Uint8Array(csr.publicKey.rawData)),
+        publicKey: await csr.publicKey.export(KEY_ALG, ['verify']),
+    };
+}
+const serial = () => `0${crypto.randomBytes(15).toString('hex')}`;
+/** The DNS names and IP addresses a server certificate covers, from the public URL plus optional extras. */
+export function serverNames(publicUrl, extras = []) {
+    const names = { dns: [], ip: [] };
+    const host = new URL(publicUrl).hostname.replace(/^\[|\]$/g, '');
+    for (const entry of [host, ...extras.map((e) => e.trim()).filter(Boolean)]) {
+        const bucket = net.isIP(entry) ? names.ip : names.dns;
+        if (!bucket.includes(entry))
+            bucket.push(entry);
+    }
+    return names;
+}
+export const namesKey = (names) => JSON.stringify([[...names.dns].sort(), [...names.ip].sort()]);
+export class Pki {
+    caPem;
+    caCert;
+    caKey;
+    constructor(caPem, caCert, caKey) {
+        this.caPem = caPem;
+        this.caCert = caCert;
+        this.caKey = caKey;
+    }
+    get caNotAfter() {
+        return this.caCert.notAfter;
+    }
+    get caFingerprint() {
+        return hashSpki(new Uint8Array(this.caCert.publicKey.rawData));
+    }
+    /** Loads the CA from `dir`, creating it only when `create` is set and no CA files exist. Corrupt or partial material fails closed. */
+    static async load(dir, create) {
+        const keyFile = path.join(dir, 'ca.key');
+        const certFile = path.join(dir, 'ca.crt');
+        const [key, cert] = await Promise.all([
+            fs.readFile(keyFile, 'utf8').catch(() => null),
+            fs.readFile(certFile, 'utf8').catch(() => null),
+        ]);
+        if (key === null && cert === null) {
+            if (!create)
+                throw new Error(`control has existing state but its CA is missing from ${dir}; restore pki/ from a backup`);
+            return Pki.create(dir);
+        }
+        if (key === null || cert === null)
+            throw new Error(`incomplete CA material in ${dir}`);
+        try {
+            const caCert = new x509.X509Certificate(cert);
+            const keys = await importPrivateKey(key);
+            const same = hashSpki(new Uint8Array(caCert.publicKey.rawData)) ===
+                hashSpki(Buffer.from(await crypto.webcrypto.subtle.exportKey('spki', keys.publicKey)));
+            if (!same)
+                throw new Error('CA key does not match the CA certificate');
+            return new Pki(cert, caCert, keys.privateKey);
+        }
+        catch (e) {
+            throw new Error(`corrupt CA material in ${dir}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+        }
+    }
+    static async create(dir) {
+        const keys = (await crypto.webcrypto.subtle.generateKey(KEY_ALG, true, [
+            'sign',
+            'verify',
+        ]));
+        const now = Date.now();
+        const cert = await x509.X509CertificateGenerator.createSelfSigned({
+            serialNumber: serial(),
+            name: 'CN=Tug CA',
+            notBefore: new Date(now - BACKDATE_MS),
+            notAfter: new Date(now + CA_LIFETIME_MS),
+            signingAlgorithm: SIGNING,
+            keys,
+            extensions: [
+                new x509.BasicConstraintsExtension(true, 0, true),
+                new x509.KeyUsagesExtension(x509.KeyUsageFlags.keyCertSign | x509.KeyUsageFlags.cRLSign, true),
+                await x509.SubjectKeyIdentifierExtension.create(keys.publicKey),
+            ],
+        });
+        const pkcs8 = Buffer.from(await crypto.webcrypto.subtle.exportKey('pkcs8', keys.privateKey));
+        await writeFileDurable(path.join(dir, 'ca.key'), toPem(pkcs8, 'PRIVATE KEY'), 0o600);
+        await writeFileDurable(path.join(dir, 'ca.crt'), cert.toString('pem'), 0o644);
+        return Pki.load(dir, false);
+    }
+    /** Signs a leaf with an assigned profile. Requester-supplied subjects, SANs, validity and extensions are never used. */
+    async signLeaf(options) {
+        const now = Date.now();
+        const notAfter = new Date(Math.min(now + options.lifetimeMs, this.caCert.notAfter.getTime()));
+        const san = [];
+        if (options.uri)
+            san.push({ type: 'url', value: options.uri });
+        for (const dns of options.names?.dns ?? [])
+            san.push({ type: 'dns', value: dns });
+        for (const ip of options.names?.ip ?? [])
+            san.push({ type: 'ip', value: ip });
+        const cert = await x509.X509CertificateGenerator.create({
+            serialNumber: serial(),
+            subject: options.kind === 'server' ? 'CN=tug-control' : 'CN=tug-client',
+            issuer: this.caCert.subject,
+            notBefore: new Date(now - BACKDATE_MS),
+            notAfter,
+            signingAlgorithm: SIGNING,
+            publicKey: options.publicKey,
+            signingKey: this.caKey,
+            extensions: [
+                new x509.BasicConstraintsExtension(false, undefined, true),
+                new x509.KeyUsagesExtension(x509.KeyUsageFlags.digitalSignature, true),
+                new x509.ExtendedKeyUsageExtension([
+                    options.kind === 'server'
+                        ? x509.ExtendedKeyUsage.serverAuth
+                        : x509.ExtendedKeyUsage.clientAuth,
+                ], true),
+                new x509.SubjectAlternativeNameExtension(san, false),
+                await x509.AuthorityKeyIdentifierExtension.create(this.caCert, false),
+            ],
+        });
+        return { cert: cert.toString('pem'), notAfter };
+    }
+    /** Verifies a CSR and signs a client certificate naming `uri` for its key. */
+    async signClientCsr(csrPem, uri, lifetimeMs) {
+        const { keyHash, publicKey } = await verifyCsr(csrPem);
+        const { cert, notAfter } = await this.signLeaf({ publicKey, kind: 'client', uri, lifetimeMs });
+        return { cert, keyHash, notAfter };
+    }
+    /** A client keypair and certificate for `uri`, for credentials issued on control (operators, enrollment keys, root). */
+    async issueClient(uri, lifetimeMs, url) {
+        const keys = await generateKeyPair();
+        const { cert, notAfter } = await this.signLeaf({
+            publicKey: keys.publicKey,
+            kind: 'client',
+            uri,
+            lifetimeMs,
+        });
+        const credential = { v: 1, url, ca: this.caPem, cert, key: keys.privateKeyPem };
+        return { credential, keyHash: certKeyHash(cert), notAfter };
+    }
+    /** The server certificate and key for the given names. */
+    async issueServer(names) {
+        const keys = await generateKeyPair();
+        const { cert, notAfter } = await this.signLeaf({
+            publicKey: keys.publicKey,
+            kind: 'server',
+            names,
+            lifetimeMs: SERVER_LIFETIME_MS,
+        });
+        return { cert, key: keys.privateKeyPem, notAfter };
+    }
+}
+/** Checks that a certificate chains to `ca`, names `uri` and is bound to the key. Used by the agent before installing. */
+export function validateInstalledCertificate(options) {
+    const cert = new crypto.X509Certificate(options.cert);
+    if (!cert.verify(new crypto.X509Certificate(options.ca).publicKey))
+        throw new Error('certificate is not signed by the supplied CA');
+    if (!cert.checkPrivateKey(crypto.createPrivateKey(options.keyPem)))
+        throw new Error('certificate does not match the pending private key');
+    if (!(cert.subjectAltName ?? '').split(/,\s*/).includes(`URI:${options.uri}`))
+        throw new Error(`certificate does not name ${options.uri}`);
+}
+/** TLS client options pinned to the credential's CA. Verification is always against the public host, even through a tunnel. */
+export function clientTlsOptions(credential) {
+    const publicHost = new URL(credential.url).hostname.replace(/^\[|\]$/g, '');
+    return {
+        ca: credential.ca,
+        cert: credential.cert,
+        key: credential.key,
+        minVersion: 'TLSv1.3',
+        ...(net.isIP(publicHost) ? {} : { servername: publicHost }),
+        checkServerIdentity: (_host, cert) => tls.checkServerIdentity(publicHost, cert),
+    };
+}
+/** The peer identity presented on a TLS socket, or null when none can be established. */
+export function peerIdentity(socket) {
+    if (!socket.authorized)
+        return null;
+    const peer = socket.getPeerCertificate(false);
+    if (!peer || !peer.raw)
+        return null;
+    const x = new crypto.X509Certificate(peer.raw);
+    const uri = (x.subjectAltName ?? '')
+        .split(/,\s*/)
+        .map((s) => s.trim())
+        .find((s) => s.startsWith('URI:'))
+        ?.slice(4);
+    if (!uri)
+        return null;
+    const notAfter = Date.parse(x.validTo);
+    if (!(notAfter > Date.now()) || !(Date.parse(x.validFrom) <= Date.now() + 60_000))
+        return null;
+    return {
+        uri,
+        keyHash: hashSpki(x.publicKey.export({ type: 'spki', format: 'der' })),
+        notAfter,
+    };
+}

package/dist/protocol.d.ts

@@ -1,7 +1,6 @@
 export interface Placement {
     nodes?: string[];
     labels?: string[];
-    global?: boolean;
 }
 export interface HealthCheck {
     type: 'docker' | 'tcp' | 'http';
@@ -44,6 +43,8 @@ export interface BackupSpec {
     jitter?: number;
     /** Hard limit for one run, such as `30m` or `2h`. */
     timeout?: string | number;
+    /** Memory limit of the restic helper container, such as `256m` (default `512m`). */
+    memory?: string;
     /** 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. */
@@ -523,6 +524,8 @@ export interface ProjectStatus {
 }
 export interface StatusReport {
     node: string;
+    /** The agent clock when it sent the report (ISO 8601); control derives clock skew from it. */
+    sentAt?: string;
     projects: ProjectStatus[];
     commandResults: CommandResult[];
     ingress?: IngressStatus;
@@ -556,38 +559,66 @@ export interface NodeInfo {
     created_at: string;
     updated_at: string;
 }
-/** Response of `POST /api/v1/nodes/register`. */
-export interface RegisterResponse {
+/** Body of `POST /api/v1/nodes/:name/identity`, posted by an admin with a CSR the node generated for its own key. */
+export interface IdentityRequest {
+    csr: string;
+    /** `create` makes a new node (idempotent for the identical key); `replace` installs a new key on an existing node. */
+    mode: 'create' | 'replace';
+    address?: string;
+    publicAddress?: string;
+    labels?: string[];
+}
+/** Response of `POST /api/v1/nodes/:name/identity` and `POST /agent/v1/enroll`. */
+export interface IdentityResponse {
     node: NodeInfo;
-    agentToken: string;
+    certificate: string;
+    /** PEM CA certificate every client pins. */
+    ca: string;
+    /** Credential-free HTTPS origin the certificate is verified against. */
+    url: string;
 }
-/** Body of `POST /agent/v1/enroll`. */
+/** Body of `POST /agent/v1/enroll`, authenticated by the bootstrap certificate. Name and labels come from its row. */
 export interface EnrollRequest {
-    enrollToken?: string;
-    name?: string;
+    csr: string;
     address?: string;
     publicAddress?: string;
     /** Base64 WireGuard public key; the private key never leaves the node. */
     wgPublicKey?: string;
-    /** Node labels (tags) used for label-based placement. */
-    labels?: string[];
 }
 /** Response of `POST /agent/v1/enroll`. */
-export type EnrollResponse = RegisterResponse;
-/** Response of `POST /api/v1/nodes/enroll-token`. */
-export interface EnrollTokenResponse {
-    enrollToken: string;
-    name: string | null;
-    usesRemaining: number;
+export type EnrollResponse = IdentityResponse;
+/** Body of `POST /agent/v1/renew`: a CSR for the node's existing key. */
+export interface RenewRequest {
+    csr: string;
+}
+export interface RenewResponse {
+    certificate: string;
+}
+/** Response of `POST /api/v1/nodes/enrollment-credential`: the bootstrap credential, usable once for `POST /agent/v1/enroll`. */
+export interface EnrollmentCredentialResponse {
+    credential: {
+        v: 1;
+        url: string;
+        ca: string;
+        cert: string;
+        key: string;
+    };
+    name: string;
+    labels: string[];
     expiresAt: string;
 }
 /** The base64url-encoded JSON payload of TUG_JOIN_KEY. */
 export interface JoinKey {
-    v: number;
-    controlUrl?: string;
-    enrollToken: string;
-    /** PEM CA certificate to trust for a private/self-signed control plane. */
-    ca?: string;
-    /** Node labels to register at enrollment. */
-    labels?: string[];
+    v: 2;
+    /** The bootstrap credential. */
+    credential: {
+        v: 1;
+        url: string;
+        ca: string;
+        cert: string;
+        key: string;
+    };
+    name: string;
+    /** Connect-only target (for example a tunnel); verification always uses the credential's public url. */
+    connectUrl?: string;
 }

package/dist/status-report.d.ts

@@ -0,0 +1,11 @@
+import type { StatusReport } from './protocol.ts';
+export declare class StatusReportError extends Error {
+}
+/** A TCP port: an integer in 1..65535, never a string, so it cannot carry configuration syntax. */
+export declare function isPort(value: unknown): value is number;
+/**
+ * Validates and normalizes a node's `POST /agent/v1/status` body before anything is stored. Reported values
+ * flow into other nodes' work responses and the shared ingress configuration, so unknown fields are dropped
+ * and every kept field is checked against its protocol type. Throws `StatusReportError` for a malformed report.
+ */
+export declare function parseStatusReport(body: unknown): StatusReport;