mcpmake 0.1.0

package/dist/cloud/caddy-manager.js

@@ -0,0 +1,97 @@
+/**
+ * Dynamic reverse proxy routing via Caddy Admin API.
+ *
+ * Manages routes that map {slug}.{domain} -> localhost:{port}.
+ * Caddy Admin API is assumed to run at http://localhost:2019.
+ */
+import http from 'node:http';
+import { logger } from '../utils/logger.js';
+const CADDY_ADMIN = 'http://localhost:2019';
+/**
+ * Add a route: {slug}.{domain} -> localhost:{port}
+ */
+export async function addRoute(slug, port, domain) {
+    const hostname = `${slug}.${domain}`;
+    const route = {
+        '@id': `mcpmake-${slug}`,
+        match: [
+            {
+                host: [hostname],
+            },
+        ],
+        handle: [
+            {
+                handler: 'reverse_proxy',
+                upstreams: [
+                    {
+                        dial: `localhost:${port}`,
+                    },
+                ],
+            },
+        ],
+    };
+    await caddyRequest('POST', '/config/apps/http/servers/srv0/routes', route);
+    logger.info(`Caddy route added: ${hostname} -> localhost:${port}`);
+}
+/**
+ * Remove a route by slug.
+ */
+export async function removeRoute(slug, _domain) {
+    await caddyRequest('DELETE', `/id/mcpmake-${slug}`, undefined);
+    logger.info(`Caddy route removed: ${slug}`);
+}
+/**
+ * Check if a route exists for a given slug.
+ */
+export async function routeExists(slug, _domain) {
+    try {
+        const body = await caddyRequest('GET', `/id/mcpmake-${slug}`, undefined);
+        return body !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Low-level helper to call the Caddy Admin API.
+ */
+function caddyRequest(method, path, body) {
+    return new Promise((resolve, reject) => {
+        const url = new URL(path, CADDY_ADMIN);
+        const payload = body !== undefined ? JSON.stringify(body) : undefined;
+        const req = http.request({
+            hostname: url.hostname,
+            port: Number(url.port),
+            path: url.pathname,
+            method,
+            headers: {
+                ...(payload
+                    ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) }
+                    : {}),
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                const responseBody = Buffer.concat(chunks).toString('utf-8');
+                if (res.statusCode && res.statusCode >= 400) {
+                    reject(new Error(`Caddy API ${method} ${path} returned ${res.statusCode}: ${responseBody}`));
+                    return;
+                }
+                try {
+                    resolve(responseBody ? JSON.parse(responseBody) : null);
+                }
+                catch {
+                    resolve(responseBody || null);
+                }
+            });
+        });
+        req.on('error', (err) => {
+            reject(new Error(`Caddy API request failed: ${err.message}`));
+        });
+        if (payload) {
+            req.write(payload);
+        }
+        req.end();
+    });
+}

package/dist/cloud/container-backend.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Container backend driver abstraction.
+ *
+ * All container lifecycle operations go through a `ContainerBackend` rather than
+ * calling the Docker socket helpers directly. Today the only implementation is
+ * `LocalDockerDriver` (the local `/var/run/docker.sock`, no behavior change).
+ *
+ * The seam exists so a future cloud / multi-node move is a driver swap, not a
+ * rewrite: a `RemoteDockerDriver` (TCP + mTLS) or a managed-cloud driver
+ * (Fly Machines / Cloud Run) implements the same interface, and a placement
+ * layer picks which driver to use per server. See TODO.md Sprint 8 — "Prep
+ * seams" and "Tiered placement".
+ */
+import type { StartContainerOpts, ContainerStatus } from './container-manager.js';
+export type { StartContainerOpts, ContainerStatus };
+/**
+ * A backend capable of building images and running tenant containers.
+ *
+ * Method contracts mirror the existing `container-manager` functions exactly,
+ * so swapping the default driver is invisible to callers.
+ */
+export interface ContainerBackend {
+    /** Stable identifier for logs / the server record (which backend ran a container). */
+    readonly name: string;
+    /** Build an image from a generated project directory containing a Dockerfile. */
+    buildImage(buildDir: string, imageName: string, imageTag: string): Promise<void>;
+    /** Create + start a container; resolves to the container ID. */
+    startContainer(opts: StartContainerOpts): Promise<string>;
+    /** Stop and remove a container (best-effort; never throws on already-stopped). */
+    stopContainer(containerId: string): Promise<void>;
+    /** Stream container logs (multiplexed Docker frames decoded to text lines). */
+    getContainerLogs(containerId: string): AsyncIterable<string>;
+    /** Current runtime status; resolves to 'error' if the backend is unreachable. */
+    getContainerStatus(containerId: string): Promise<ContainerStatus>;
+    /** Reclaim disk by removing dangling images (best-effort). */
+    pruneDanglingImages(): Promise<void>;
+}
+/**
+ * Default driver: the local Docker daemon over its Unix socket.
+ *
+ * Delegates to the `container-manager` helpers at call time (not construction)
+ * so the well-tested socket code stays the single implementation and module
+ * mocks still intercept.
+ */
+export declare class LocalDockerDriver implements ContainerBackend {
+    readonly name = "local-docker";
+    buildImage(buildDir: string, imageName: string, imageTag: string): Promise<void>;
+    startContainer(opts: StartContainerOpts): Promise<string>;
+    stopContainer(containerId: string): Promise<void>;
+    getContainerLogs(containerId: string): AsyncIterable<string>;
+    getContainerStatus(containerId: string): Promise<ContainerStatus>;
+    pruneDanglingImages(): Promise<void>;
+}
+/**
+ * Resolve the container backend.
+ *
+ * Single local driver for now; the future placement layer will pass the target
+ * server/plan here to pick a driver per tenant.
+ */
+export declare function getContainerBackend(): ContainerBackend;
+/** Override the backend (tests / future placement wiring). Pass null to reset. */
+export declare function setContainerBackend(backend: ContainerBackend | null): void;

package/dist/cloud/container-backend.js

@@ -0,0 +1,59 @@
+/**
+ * Container backend driver abstraction.
+ *
+ * All container lifecycle operations go through a `ContainerBackend` rather than
+ * calling the Docker socket helpers directly. Today the only implementation is
+ * `LocalDockerDriver` (the local `/var/run/docker.sock`, no behavior change).
+ *
+ * The seam exists so a future cloud / multi-node move is a driver swap, not a
+ * rewrite: a `RemoteDockerDriver` (TCP + mTLS) or a managed-cloud driver
+ * (Fly Machines / Cloud Run) implements the same interface, and a placement
+ * layer picks which driver to use per server. See TODO.md Sprint 8 — "Prep
+ * seams" and "Tiered placement".
+ */
+import * as docker from './container-manager.js';
+/**
+ * Default driver: the local Docker daemon over its Unix socket.
+ *
+ * Delegates to the `container-manager` helpers at call time (not construction)
+ * so the well-tested socket code stays the single implementation and module
+ * mocks still intercept.
+ */
+export class LocalDockerDriver {
+    name = 'local-docker';
+    buildImage(buildDir, imageName, imageTag) {
+        return docker.buildImage(buildDir, imageName, imageTag);
+    }
+    startContainer(opts) {
+        return docker.startContainer(opts);
+    }
+    stopContainer(containerId) {
+        return docker.stopContainer(containerId);
+    }
+    getContainerLogs(containerId) {
+        return docker.getContainerLogs(containerId);
+    }
+    getContainerStatus(containerId) {
+        return docker.getContainerStatus(containerId);
+    }
+    pruneDanglingImages() {
+        return docker.pruneDanglingImages();
+    }
+}
+let cached = null;
+/**
+ * Resolve the container backend.
+ *
+ * Single local driver for now; the future placement layer will pass the target
+ * server/plan here to pick a driver per tenant.
+ */
+export function getContainerBackend() {
+    if (!cached) {
+        cached = new LocalDockerDriver();
+    }
+    return cached;
+}
+/** Override the backend (tests / future placement wiring). Pass null to reset. */
+export function setContainerBackend(backend) {
+    cached = backend;
+}

package/dist/cloud/container-manager.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Docker container lifecycle management via the Docker Engine API.
+ *
+ * Communicates over the Unix socket at /var/run/docker.sock using
+ * native http.request — no dockerode dependency.
+ */
+export interface ContainerInfo {
+    slug: string;
+    containerId: string;
+    port: number;
+    status: 'building' | 'running' | 'stopped' | 'error';
+    endpoint: string;
+    bearerToken: string;
+    createdAt: string;
+    lastActiveAt: string;
+}
+/** Runtime status of a container as reported by the backend. */
+export type ContainerStatus = 'running' | 'stopped' | 'error';
+/** Parameters for launching a tenant container. */
+export interface StartContainerOpts {
+    slug: string;
+    imageName: string;
+    imageTag: string;
+    envVars: Record<string, string>;
+    port: number;
+    serverType?: 'http' | 'playwright';
+    /** Decrypted secrets to merge into the container environment. */
+    secrets?: Record<string, string>;
+}
+/**
+ * Build a Docker image from a generated project directory.
+ *
+ * Uses `tar` to create the build context and streams it to the Docker build API.
+ * The directory must contain a Dockerfile.
+ */
+export declare function buildImage(buildDir: string, imageName: string, imageTag: string): Promise<void>;
+/**
+ * Start a container with strict resource limits and security constraints.
+ *
+ * Returns the container ID.
+ */
+export declare function startContainer(opts: StartContainerOpts): Promise<string>;
+/**
+ * Stop and remove a container.
+ */
+export declare function stopContainer(containerId: string): Promise<void>;
+/**
+ * Get container logs as an async generator (streaming).
+ */
+export declare function getContainerLogs(containerId: string): AsyncGenerator<string>;
+/**
+ * Check if a container is running.
+ */
+export declare function getContainerStatus(containerId: string): Promise<ContainerStatus>;
+/**
+ * Reclaim disk by removing dangling (untagged) images. A re-deploy reuses the
+ * same image tag, so the previous build becomes dangling — left unchecked these
+ * silently fill the disk. Best-effort: errors are logged, never thrown.
+ *
+ * NOTE: images orphaned by *deleting* a server are still tagged (not dangling),
+ * so they are not reclaimed here — that is left to the daily `docker image
+ * prune` cron / a future targeted removal.
+ */
+export declare function pruneDanglingImages(): Promise<void>;

package/dist/cloud/container-manager.js

@@ -0,0 +1,301 @@
+/**
+ * Docker container lifecycle management via the Docker Engine API.
+ *
+ * Communicates over the Unix socket at /var/run/docker.sock using
+ * native http.request — no dockerode dependency.
+ */
+import http from 'node:http';
+import { logger } from '../utils/logger.js';
+import { execFile } from 'node:child_process';
+const DOCKER_SOCKET = '/var/run/docker.sock';
+const TENANT_NETWORK = 'mcp-tenant';
+/** Docker container IDs are 64-char hex strings (or short 12-char prefixes). */
+const CONTAINER_ID_RE = /^[a-f0-9]{12,64}$/;
+function validateContainerId(id) {
+    if (!CONTAINER_ID_RE.test(id)) {
+        throw new Error(`Invalid container ID: ${id}`);
+    }
+}
+/**
+ * Build a Docker image from a generated project directory.
+ *
+ * Uses `tar` to create the build context and streams it to the Docker build API.
+ * The directory must contain a Dockerfile.
+ */
+export async function buildImage(buildDir, imageName, imageTag) {
+    const fullTag = `${imageName}:${imageTag}`;
+    logger.info(`Building Docker image: ${fullTag} from ${buildDir}`);
+    // Create a tar archive of the build directory and pipe it to Docker build API.
+    // We use a child process for tar since Node's native APIs don't include tar.
+    const tarStream = await createTarStream(buildDir);
+    await new Promise((resolve, reject) => {
+        const req = http.request({
+            socketPath: DOCKER_SOCKET,
+            path: `/build?t=${encodeURIComponent(fullTag)}&rm=true`,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-tar',
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                if (res.statusCode && res.statusCode >= 400) {
+                    const body = Buffer.concat(chunks).toString('utf-8');
+                    reject(new Error(`Docker build failed (${res.statusCode}): ${body}`));
+                    return;
+                }
+                // Check for build errors in the stream output
+                const output = Buffer.concat(chunks).toString('utf-8');
+                if (output.includes('"error"')) {
+                    // Docker build streams JSON objects; check for error fields
+                    for (const line of output.split('\n')) {
+                        if (!line.trim())
+                            continue;
+                        try {
+                            const msg = JSON.parse(line);
+                            if (msg.error) {
+                                reject(new Error(`Docker build error: ${msg.error}`));
+                                return;
+                            }
+                        }
+                        catch {
+                            // Not JSON, skip
+                        }
+                    }
+                }
+                logger.info(`Docker image built: ${fullTag}`);
+                resolve();
+            });
+        });
+        req.on('error', (err) => {
+            reject(new Error(`Docker build request failed: ${err.message}`));
+        });
+        tarStream.pipe(req);
+    });
+}
+/**
+ * Start a container with strict resource limits and security constraints.
+ *
+ * Returns the container ID.
+ */
+export async function startContainer(opts) {
+    const fullTag = `${opts.imageName}:${opts.imageTag}`;
+    const containerName = `mcpmake-${opts.slug}`;
+    const isPlaywright = opts.serverType === 'playwright';
+    // Merge explicit env vars with decrypted secrets (envVars take precedence)
+    const mergedEnv = { ...(opts.secrets ?? {}), ...opts.envVars };
+    const envList = Object.entries(mergedEnv).map(([k, v]) => `${k}=${v}`);
+    // Resource limits differ for Playwright containers (Chromium needs more resources)
+    const hostConfig = {
+        // Port mapping: host port -> container port 3000
+        PortBindings: {
+            '3000/tcp': [{ HostIp: '127.0.0.1', HostPort: String(opts.port) }],
+        },
+        // Resource limits
+        Memory: isPlaywright ? 768 * 1024 * 1024 : 256 * 1024 * 1024,
+        NanoCPUs: isPlaywright ? 1_000_000_000 : 500_000_000,
+        // Security: Chromium needs write access to the root filesystem
+        ReadonlyRootfs: !isPlaywright,
+        // tmpfs: Playwright needs a larger temp directory
+        Tmpfs: isPlaywright
+            ? { '/tmp': 'rw,noexec,nosuid,size=256m' }
+            : { '/tmp': 'rw,noexec,nosuid,size=64m' },
+        // Network
+        NetworkMode: TENANT_NETWORK,
+        // Drop all capabilities
+        CapDrop: ['ALL'],
+        // Prevent privilege escalation
+        SecurityOpt: ['no-new-privileges'],
+    };
+    // Chromium rendering requires a larger shared memory segment
+    if (isPlaywright) {
+        hostConfig.ShmSize = 256 * 1024 * 1024;
+    }
+    // Create the container
+    const createBody = {
+        Image: fullTag,
+        name: containerName,
+        Env: [...envList, 'PORT=3000', 'TRANSPORT=http', 'NODE_ENV=production'],
+        ExposedPorts: { '3000/tcp': {} },
+        HostConfig: hostConfig,
+        Labels: {
+            'mcpmake.slug': opts.slug,
+            'mcpmake.managed': 'true',
+        },
+    };
+    const createResult = await dockerRequest('POST', `/containers/create?name=${encodeURIComponent(containerName)}`, createBody);
+    const containerId = createResult.Id;
+    validateContainerId(containerId);
+    logger.info(`Container created: ${containerId.slice(0, 12)} (${containerName})`);
+    // Start the container
+    await dockerRequest('POST', `/containers/${containerId}/start`, undefined);
+    logger.info(`Container started: ${containerId.slice(0, 12)}`);
+    return containerId;
+}
+/**
+ * Stop and remove a container.
+ */
+export async function stopContainer(containerId) {
+    validateContainerId(containerId);
+    const shortId = containerId.slice(0, 12);
+    try {
+        await dockerRequest('POST', `/containers/${containerId}/stop?t=10`, undefined);
+        logger.info(`Container stopped: ${shortId}`);
+    }
+    catch (err) {
+        // Container might already be stopped
+        logger.warn(`Stop failed for ${shortId} (may already be stopped): ${err}`);
+    }
+    try {
+        await dockerRequest('DELETE', `/containers/${containerId}?force=true`, undefined);
+        logger.info(`Container removed: ${shortId}`);
+    }
+    catch (err) {
+        logger.warn(`Remove failed for ${shortId}: ${err}`);
+    }
+}
+/**
+ * Get container logs as an async generator (streaming).
+ */
+export async function* getContainerLogs(containerId) {
+    validateContainerId(containerId);
+    const res = await new Promise((resolve, reject) => {
+        const req = http.request({
+            socketPath: DOCKER_SOCKET,
+            path: `/containers/${containerId}/logs?follow=true&stdout=true&stderr=true&timestamps=true`,
+            method: 'GET',
+        }, resolve);
+        req.on('error', reject);
+        req.end();
+    });
+    if (res.statusCode && res.statusCode >= 400) {
+        const chunks = [];
+        for await (const chunk of res) {
+            chunks.push(chunk);
+        }
+        throw new Error(`Failed to get logs (${res.statusCode}): ${Buffer.concat(chunks).toString('utf-8')}`);
+    }
+    // Docker log stream uses a multiplexed format:
+    // 8-byte header: [stream_type(1), 0, 0, 0, size(4 big-endian)]
+    // followed by `size` bytes of payload.
+    let buffer = Buffer.alloc(0);
+    for await (const chunk of res) {
+        buffer = Buffer.concat([buffer, chunk]);
+        while (buffer.length >= 8) {
+            const payloadSize = buffer.readUInt32BE(4);
+            const totalFrameSize = 8 + payloadSize;
+            if (buffer.length < totalFrameSize)
+                break;
+            const payload = buffer.subarray(8, totalFrameSize).toString('utf-8');
+            buffer = buffer.subarray(totalFrameSize);
+            yield payload;
+        }
+    }
+}
+/**
+ * Check if a container is running.
+ */
+export async function getContainerStatus(containerId) {
+    validateContainerId(containerId);
+    try {
+        const info = await dockerRequest('GET', `/containers/${containerId}/json`, undefined);
+        if (info.State.Running)
+            return 'running';
+        if (info.State.Status === 'exited' || info.State.Status === 'dead')
+            return 'stopped';
+        return 'error';
+    }
+    catch {
+        return 'error';
+    }
+}
+/**
+ * Reclaim disk by removing dangling (untagged) images. A re-deploy reuses the
+ * same image tag, so the previous build becomes dangling — left unchecked these
+ * silently fill the disk. Best-effort: errors are logged, never thrown.
+ *
+ * NOTE: images orphaned by *deleting* a server are still tagged (not dangling),
+ * so they are not reclaimed here — that is left to the daily `docker image
+ * prune` cron / a future targeted removal.
+ */
+export async function pruneDanglingImages() {
+    try {
+        const filters = encodeURIComponent(JSON.stringify({ dangling: ['true'] }));
+        await dockerRequest('POST', `/images/prune?filters=${filters}`, undefined);
+        logger.info('Pruned dangling Docker images');
+    }
+    catch (err) {
+        logger.warn(`Dangling image prune failed: ${err}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Create a tar stream from a directory using the system `tar` command.
+ * Uses execFile (no shell) to avoid command injection.
+ * Returns a readable stream.
+ */
+function createTarStream(dir) {
+    // Validate path contains only safe characters
+    if (!/^[a-zA-Z0-9_.\/\-]+$/.test(dir)) {
+        throw new Error(`Unsafe path for tar: ${dir}`);
+    }
+    return new Promise((resolve, reject) => {
+        const child = execFile('tar', ['-cf', '-', '-C', dir, '.'], {
+            maxBuffer: 100 * 1024 * 1024, // 100 MB max
+            encoding: 'buffer',
+        });
+        if (!child.stdout) {
+            reject(new Error('Failed to create tar stream'));
+            return;
+        }
+        child.on('error', reject);
+        resolve(child.stdout);
+    });
+}
+/**
+ * Make a request to the Docker Engine API via Unix socket.
+ */
+function dockerRequest(method, path, body) {
+    return new Promise((resolve, reject) => {
+        const payload = body !== undefined ? JSON.stringify(body) : undefined;
+        const req = http.request({
+            socketPath: DOCKER_SOCKET,
+            path,
+            method,
+            headers: {
+                ...(payload
+                    ? {
+                        'Content-Type': 'application/json',
+                        'Content-Length': Buffer.byteLength(payload),
+                    }
+                    : {}),
+            },
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                const responseBody = Buffer.concat(chunks).toString('utf-8');
+                if (res.statusCode && res.statusCode >= 400) {
+                    reject(new Error(`Docker API ${method} ${path} returned ${res.statusCode}: ${responseBody}`));
+                    return;
+                }
+                try {
+                    resolve(responseBody ? JSON.parse(responseBody) : null);
+                }
+                catch {
+                    resolve(responseBody);
+                }
+            });
+        });
+        req.on('error', (err) => {
+            reject(new Error(`Docker API request failed: ${err.message}`));
+        });
+        if (payload) {
+            req.write(payload);
+        }
+        req.end();
+    });
+}

package/dist/cloud/crypto.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AES-256-GCM encryption module for secret storage.
+ *
+ * Uses Node.js built-in `crypto` — no external dependencies.
+ * Each record gets its own random salt so that the same plaintext
+ * encrypted twice produces different ciphertexts (key isolation).
+ *
+ * Wire format: "enc:v1:<base64 payload>"
+ *   payload = salt(16) || iv(12) || authTag(16) || ciphertext
+ */
+/**
+ * Encrypt a plaintext string with AES-256-GCM.
+ *
+ * Derives a per-record key via scrypt(masterKey, randomSalt, 32).
+ * Returns a prefixed, base64-encoded string.
+ */
+export declare function encrypt(plaintext: string, masterKey: string): string;
+/**
+ * Decrypt a value previously produced by `encrypt()`.
+ *
+ * Throws on tampered data, wrong key, or malformed input.
+ */
+export declare function decrypt(encrypted: string, masterKey: string): string;
+/**
+ * Check whether a value looks like an encrypted string from this module.
+ */
+export declare function isEncrypted(value: string): boolean;

package/dist/cloud/crypto.js

@@ -0,0 +1,63 @@
+/**
+ * AES-256-GCM encryption module for secret storage.
+ *
+ * Uses Node.js built-in `crypto` — no external dependencies.
+ * Each record gets its own random salt so that the same plaintext
+ * encrypted twice produces different ciphertexts (key isolation).
+ *
+ * Wire format: "enc:v1:<base64 payload>"
+ *   payload = salt(16) || iv(12) || authTag(16) || ciphertext
+ */
+import { randomBytes, scryptSync, createCipheriv, createDecipheriv } from 'node:crypto';
+const PREFIX = 'enc:v1:';
+const SALT_LEN = 16;
+const IV_LEN = 12;
+const TAG_LEN = 16;
+const KEY_LEN = 32; // 256 bits
+/**
+ * Encrypt a plaintext string with AES-256-GCM.
+ *
+ * Derives a per-record key via scrypt(masterKey, randomSalt, 32).
+ * Returns a prefixed, base64-encoded string.
+ */
+export function encrypt(plaintext, masterKey) {
+    const salt = randomBytes(SALT_LEN);
+    const key = scryptSync(masterKey, salt, KEY_LEN);
+    const iv = randomBytes(IV_LEN);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    // Pack: salt || iv || tag || ciphertext
+    const payload = Buffer.concat([salt, iv, tag, encrypted]);
+    return PREFIX + payload.toString('base64');
+}
+/**
+ * Decrypt a value previously produced by `encrypt()`.
+ *
+ * Throws on tampered data, wrong key, or malformed input.
+ */
+export function decrypt(encrypted, masterKey) {
+    if (!isEncrypted(encrypted)) {
+        throw new Error('Value is not in encrypted format (missing enc:v1: prefix)');
+    }
+    const payload = Buffer.from(encrypted.slice(PREFIX.length), 'base64');
+    const minLen = SALT_LEN + IV_LEN + TAG_LEN;
+    if (payload.length < minLen) {
+        throw new Error('Encrypted payload too short');
+    }
+    const salt = payload.subarray(0, SALT_LEN);
+    const iv = payload.subarray(SALT_LEN, SALT_LEN + IV_LEN);
+    const tag = payload.subarray(SALT_LEN + IV_LEN, SALT_LEN + IV_LEN + TAG_LEN);
+    const ciphertext = payload.subarray(SALT_LEN + IV_LEN + TAG_LEN);
+    const key = scryptSync(masterKey, salt, KEY_LEN);
+    const decipher = createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return decrypted.toString('utf8');
+}
+/**
+ * Check whether a value looks like an encrypted string from this module.
+ */
+export function isEncrypted(value) {
+    return value.startsWith(PREFIX);
+}