cfenv-kv-sync 0.1.0-beta.1

package/dist/lib/cloudflare-api.js

@@ -0,0 +1,252 @@
+const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_RETRY_BASE_DELAY_MS = 500;
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function parseRetryAfter(retryAfterHeader) {
+    if (!retryAfterHeader) {
+        return null;
+    }
+    const seconds = Number(retryAfterHeader);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.floor(seconds * 1000);
+    }
+    const retryDate = Date.parse(retryAfterHeader);
+    if (Number.isNaN(retryDate)) {
+        return null;
+    }
+    const ms = retryDate - Date.now();
+    if (ms <= 0) {
+        return null;
+    }
+    return ms;
+}
+function jitteredExponentialBackoff(baseMs, attempt) {
+    const exponential = baseMs * 2 ** attempt;
+    const jitter = Math.floor(Math.random() * baseMs);
+    return Math.min(exponential + jitter, 30_000);
+}
+function normalizeHeaders(input) {
+    if (!input) {
+        return {};
+    }
+    if (Array.isArray(input)) {
+        return Object.fromEntries(input);
+    }
+    if (input instanceof Headers) {
+        const result = {};
+        for (const [key, value] of input.entries()) {
+            result[key] = value;
+        }
+        return result;
+    }
+    return { ...input };
+}
+export class CloudflareApiClient {
+    accountId;
+    apiToken;
+    baseUrl = "https://api.cloudflare.com/client/v4";
+    requestTimeoutMs;
+    maxRetries;
+    retryBaseDelayMs;
+    userAgent;
+    constructor(input) {
+        this.accountId = input.accountId;
+        this.apiToken = input.apiToken;
+        this.requestTimeoutMs = input.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.maxRetries = input.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.retryBaseDelayMs = input.retryBaseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS;
+        this.userAgent = input.userAgent ?? "cfenv-kv-sync/0.1.0";
+    }
+    async verifyToken() {
+        const url = `${this.baseUrl}/user/tokens/verify`;
+        return this.requestJson(url, { method: "GET" });
+    }
+    async putValue(namespaceId, key, value) {
+        const url = this.accountUrl(`/storage/kv/namespaces/${encodeURIComponent(namespaceId)}/values/${encodeURIComponent(key)}`);
+        const response = await this.executeFetch(url, {
+            method: "PUT",
+            headers: this.authHeaders({
+                "Content-Type": "text/plain; charset=utf-8"
+            }),
+            body: value
+        });
+        if (!response.ok) {
+            throw new Error(await this.extractError(response));
+        }
+    }
+    async getValue(namespaceId, key) {
+        const url = this.accountUrl(`/storage/kv/namespaces/${encodeURIComponent(namespaceId)}/values/${encodeURIComponent(key)}`);
+        const response = await this.executeFetch(url, {
+            method: "GET",
+            headers: this.authHeaders()
+        });
+        if (response.status === 404) {
+            return null;
+        }
+        if (!response.ok) {
+            throw new Error(await this.extractError(response));
+        }
+        return response.text();
+    }
+    async deleteValue(namespaceId, key) {
+        const url = this.accountUrl(`/storage/kv/namespaces/${encodeURIComponent(namespaceId)}/values/${encodeURIComponent(key)}`);
+        const response = await this.executeFetch(url, {
+            method: "DELETE",
+            headers: this.authHeaders()
+        });
+        if (!response.ok) {
+            throw new Error(await this.extractError(response));
+        }
+    }
+    async listKeys(namespaceId, prefix, limit = 1000) {
+        const results = [];
+        let cursor;
+        do {
+            const url = new URL(this.accountUrl(`/storage/kv/namespaces/${encodeURIComponent(namespaceId)}/keys`));
+            url.searchParams.set("prefix", prefix);
+            url.searchParams.set("limit", String(limit));
+            if (cursor) {
+                url.searchParams.set("cursor", cursor);
+            }
+            const response = await this.requestEnvelope(url.toString(), { method: "GET" });
+            results.push(...response.result);
+            cursor = response.result_info?.cursor;
+        } while (cursor);
+        return results;
+    }
+    async listNamespaces(perPage = 100) {
+        const results = [];
+        let page = 1;
+        let totalPages = 1;
+        while (page <= totalPages) {
+            const url = new URL(this.accountUrl("/storage/kv/namespaces"));
+            url.searchParams.set("page", String(page));
+            url.searchParams.set("per_page", String(perPage));
+            const response = await this.requestEnvelope(url.toString(), { method: "GET" });
+            results.push(...response.result);
+            totalPages = response.result_info?.total_pages ?? page;
+            page += 1;
+        }
+        return results;
+    }
+    async createNamespace(title) {
+        if (!title.trim()) {
+            throw new Error("Namespace title cannot be empty.");
+        }
+        const url = this.accountUrl("/storage/kv/namespaces");
+        return this.requestJson(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({ title })
+        });
+    }
+    accountUrl(pathname) {
+        return `${this.baseUrl}/accounts/${encodeURIComponent(this.accountId)}${pathname}`;
+    }
+    authHeaders(extra = {}) {
+        return {
+            Authorization: `Bearer ${this.apiToken}`,
+            "User-Agent": this.userAgent,
+            ...extra
+        };
+    }
+    async requestJson(url, init) {
+        const envelope = await this.requestEnvelope(url, init);
+        return envelope.result;
+    }
+    async requestEnvelope(url, init) {
+        const response = await this.executeFetch(url, {
+            ...init,
+            headers: this.authHeaders(normalizeHeaders(init.headers))
+        });
+        let payload;
+        try {
+            payload = (await response.json());
+        }
+        catch {
+            throw new Error(`Cloudflare API returned non-JSON response (${response.status}).`);
+        }
+        if (!response.ok || !payload.success) {
+            const apiMessage = payload.errors?.map((err) => err.message).join("; ");
+            throw new Error(apiMessage || `Cloudflare API request failed with HTTP ${response.status}.`);
+        }
+        return payload;
+    }
+    async executeFetch(url, init) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+            try {
+                const response = await fetch(url, {
+                    ...init,
+                    signal: controller.signal
+                });
+                clearTimeout(timeout);
+                if (!this.shouldRetryResponse(response) || attempt >= this.maxRetries) {
+                    return response;
+                }
+                const waitMs = parseRetryAfter(response.headers.get("retry-after"))
+                    ?? jitteredExponentialBackoff(this.retryBaseDelayMs, attempt);
+                await sleep(waitMs);
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                lastError = error;
+                if (!this.shouldRetryError(error) || attempt >= this.maxRetries) {
+                    throw this.toNetworkError(error);
+                }
+                const waitMs = jitteredExponentialBackoff(this.retryBaseDelayMs, attempt);
+                await sleep(waitMs);
+            }
+        }
+        throw this.toNetworkError(lastError);
+    }
+    shouldRetryResponse(response) {
+        return response.status === 408 || response.status === 429 || response.status >= 500;
+    }
+    shouldRetryError(error) {
+        if (!(error instanceof Error)) {
+            return false;
+        }
+        if (error.name === "AbortError") {
+            return true;
+        }
+        // Undici/network failures in Node fetch commonly show as TypeError.
+        if (error instanceof TypeError) {
+            return true;
+        }
+        return /fetch failed|network/i.test(error.message);
+    }
+    toNetworkError(error) {
+        if (error instanceof Error) {
+            if (error.name === "AbortError") {
+                return new Error(`Cloudflare API request timed out after ${this.requestTimeoutMs}ms.`);
+            }
+            return new Error(`Cloudflare API network error: ${error.message}`);
+        }
+        return new Error("Cloudflare API network error.");
+    }
+    async extractError(response) {
+        try {
+            const payload = (await response.json());
+            const apiMessage = payload.errors?.map((err) => err.message).join("; ");
+            if (apiMessage) {
+                return apiMessage;
+            }
+        }
+        catch {
+            const text = await response.text().catch(() => "");
+            if (text) {
+                return text;
+            }
+        }
+        return `Cloudflare API request failed with HTTP ${response.status}.`;
+    }
+}

package/dist/lib/encryption.js

@@ -0,0 +1,93 @@
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from "node:crypto";
+const ENCRYPTION_FORMAT = "cfenv-aes-256-gcm-v1";
+const ENCRYPTION_ALGO = "aes-256-gcm";
+const KEY_LENGTH_BYTES = 32;
+const SALT_LENGTH_BYTES = 16;
+const IV_LENGTH_BYTES = 12;
+const DEFAULT_SECRET_BYTES = 32;
+function deriveKey(secret, salt) {
+    return scryptSync(secret, salt, KEY_LENGTH_BYTES);
+}
+function encode(value) {
+    return value.toString("base64");
+}
+function decode(value) {
+    return Buffer.from(value, "base64");
+}
+export function generateEncryptionSecret(byteLength = DEFAULT_SECRET_BYTES) {
+    if (!Number.isInteger(byteLength) || byteLength < 16 || byteLength > 1024) {
+        throw new Error("Encryption secret length must be an integer between 16 and 1024 bytes.");
+    }
+    return randomBytes(byteLength).toString("base64url");
+}
+export function encryptSnapshotPayload(plaintext, secret) {
+    if (!secret.trim()) {
+        throw new Error("Missing encryption secret.");
+    }
+    const salt = randomBytes(SALT_LENGTH_BYTES);
+    const iv = randomBytes(IV_LENGTH_BYTES);
+    const key = deriveKey(secret, salt);
+    const cipher = createCipheriv(ENCRYPTION_ALGO, key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const envelope = {
+        format: ENCRYPTION_FORMAT,
+        kdf: "scrypt",
+        saltB64: encode(salt),
+        ivB64: encode(iv),
+        authTagB64: encode(authTag),
+        ciphertextB64: encode(ciphertext)
+    };
+    return JSON.stringify(envelope);
+}
+function isEncryptedEnvelope(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const item = value;
+    return (item.format === ENCRYPTION_FORMAT &&
+        item.kdf === "scrypt" &&
+        typeof item.saltB64 === "string" &&
+        typeof item.ivB64 === "string" &&
+        typeof item.authTagB64 === "string" &&
+        typeof item.ciphertextB64 === "string");
+}
+export function decryptSnapshotPayload(payload, secret) {
+    let parsed;
+    try {
+        parsed = JSON.parse(payload);
+    }
+    catch {
+        return payload;
+    }
+    if (!isEncryptedEnvelope(parsed)) {
+        return payload;
+    }
+    if (!secret?.trim()) {
+        throw new Error("Snapshot is encrypted. Pass --encryption-key or set CFENV_ENCRYPTION_KEY.");
+    }
+    const envelope = parsed;
+    const salt = decode(envelope.saltB64);
+    const iv = decode(envelope.ivB64);
+    const authTag = decode(envelope.authTagB64);
+    const ciphertext = decode(envelope.ciphertextB64);
+    const key = deriveKey(secret, salt);
+    try {
+        const decipher = createDecipheriv(ENCRYPTION_ALGO, key, iv);
+        decipher.setAuthTag(authTag);
+        const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return plaintext.toString("utf8");
+    }
+    catch {
+        throw new Error("Failed to decrypt snapshot. Encryption key is missing or incorrect.");
+    }
+}
+export function isEncryptedSnapshotPayload(payload) {
+    try {
+        const parsed = JSON.parse(payload);
+        return isEncryptedEnvelope(parsed);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/env-file.js

@@ -0,0 +1,60 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const VALID_ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function decodeValue(rawValue) {
+    const value = rawValue.trim();
+    if (value.startsWith("\"") && value.endsWith("\"")) {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value.slice(1, -1);
+        }
+    }
+    if (value.startsWith("'") && value.endsWith("'")) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+export async function parseEnvFile(filePath) {
+    const absolutePath = path.resolve(filePath);
+    const raw = await fs.readFile(absolutePath, "utf8");
+    const entries = {};
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+            continue;
+        }
+        const exportPrefix = trimmed.startsWith("export ") ? "export ".length : 0;
+        const content = trimmed.slice(exportPrefix);
+        const separator = content.indexOf("=");
+        if (separator <= 0) {
+            continue;
+        }
+        const key = content.slice(0, separator).trim();
+        if (!VALID_ENV_KEY.test(key)) {
+            throw new Error(`Invalid env key "${key}" in ${absolutePath}.`);
+        }
+        const value = decodeValue(content.slice(separator + 1));
+        entries[key] = value;
+    }
+    return entries;
+}
+export function serializeEnvFile(entries) {
+    const lines = Object.keys(entries)
+        .sort((a, b) => a.localeCompare(b))
+        .map((key) => `${key}=${JSON.stringify(entries[key])}`);
+    return `${lines.join("\n")}\n`;
+}
+export async function writeTextFileAtomic(filePath, content) {
+    const absolutePath = path.resolve(filePath);
+    const tmpPath = `${absolutePath}.cfenv.tmp-${process.pid}-${Date.now()}`;
+    await fs.writeFile(tmpPath, content, "utf8");
+    if (process.platform !== "win32") {
+        await fs.chmod(tmpPath, 0o600).catch(() => undefined);
+    }
+    await fs.rename(tmpPath, absolutePath);
+}
+export async function writeEnvFileAtomic(filePath, content) {
+    await writeTextFileAtomic(filePath, content);
+}

package/dist/lib/fs-utils.js

@@ -0,0 +1,22 @@
+import { promises as fs } from "node:fs";
+export async function exists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function ensurePrivateDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+    if (process.platform !== "win32") {
+        await fs.chmod(dirPath, 0o700).catch(() => undefined);
+    }
+}
+export async function writePrivateFile(filePath, content) {
+    await fs.writeFile(filePath, content, { encoding: "utf8" });
+    if (process.platform !== "win32") {
+        await fs.chmod(filePath, 0o600).catch(() => undefined);
+    }
+}

package/dist/lib/hash.js

@@ -0,0 +1,17 @@
+import { createHash, randomUUID } from "node:crypto";
+export function canonicalizeEntries(entries) {
+    return Object.keys(entries)
+        .sort((a, b) => a.localeCompare(b))
+        .map((key) => `${key}=${JSON.stringify(entries[key])}`)
+        .join("\n");
+}
+export function sha256(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+export function checksumEntries(entries) {
+    return sha256(canonicalizeEntries(entries));
+}
+export function makeVersionId(now = new Date()) {
+    const stamp = now.toISOString().replace(/[-:.TZ]/g, "");
+    return `${stamp}-${randomUUID().slice(0, 8)}`;
+}

package/dist/lib/kv-keys.js

@@ -0,0 +1,21 @@
+function base(link) {
+    return `${link.keyPrefix}:${link.project}:${link.environment}`;
+}
+export function currentPointerKey(link) {
+    return `${base(link)}:current`;
+}
+export function versionsPrefix(link) {
+    return `${base(link)}:versions:`;
+}
+export function versionKey(link, versionId) {
+    return `${versionsPrefix(link)}${versionId}`;
+}
+export function flatEnvVarsPrefix(link) {
+    return `${base(link)}:vars:`;
+}
+export function flatEnvVarKey(link, envVarName) {
+    return `${flatEnvVarsPrefix(link)}${envVarName}`;
+}
+export function flatEnvMetaKey(link) {
+    return `${base(link)}:meta`;
+}

package/dist/lib/local-config.js

@@ -0,0 +1,180 @@
+import { promises as fs } from "node:fs";
+import { ensurePrivateDir, exists, writePrivateFile } from "./fs-utils.js";
+import { getLocalConfigDir, getLocalConfigPath } from "./paths.js";
+function makeLinkKey(project, environment) {
+    return `${project}:${environment}`;
+}
+function assertStringField(record, field) {
+    const value = record[field];
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`Invalid local config: "${field}" must be a non-empty string.`);
+    }
+    return value;
+}
+function parseProjectLink(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw new Error("Invalid local config: link entry must be an object.");
+    }
+    const record = raw;
+    const storageModeRaw = record.storageMode;
+    const storageMode = storageModeRaw === "snapshot" || storageModeRaw === "flat" ? storageModeRaw : undefined;
+    return {
+        version: 1,
+        profile: assertStringField(record, "profile"),
+        namespaceId: assertStringField(record, "namespaceId"),
+        keyPrefix: assertStringField(record, "keyPrefix"),
+        project: assertStringField(record, "project"),
+        environment: assertStringField(record, "environment"),
+        storageMode
+    };
+}
+function normalizeConfig(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw new Error("Invalid local config format.");
+    }
+    const parsed = raw;
+    if (parsed.version === 2 && typeof parsed.links === "object" && parsed.links !== null) {
+        const linksRaw = parsed.links;
+        const links = {};
+        for (const [key, value] of Object.entries(linksRaw)) {
+            links[key] = parseProjectLink(value);
+        }
+        return {
+            version: 2,
+            defaultLinkKey: typeof parsed.defaultLinkKey === "string" ? parsed.defaultLinkKey : undefined,
+            links
+        };
+    }
+    // Backward compatibility with old single-link config format.
+    if (typeof parsed.project === "string" && typeof parsed.environment === "string") {
+        const link = parseProjectLink(parsed);
+        const key = makeLinkKey(link.project, link.environment);
+        return {
+            version: 2,
+            defaultLinkKey: key,
+            links: {
+                [key]: link
+            }
+        };
+    }
+    throw new Error("Invalid local config format.");
+}
+export async function loadLocalConfig(cwd = process.cwd()) {
+    const configPath = getLocalConfigPath(cwd);
+    if (!(await exists(configPath))) {
+        return null;
+    }
+    const raw = await fs.readFile(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return normalizeConfig(parsed);
+}
+export async function saveLocalConfig(config, cwd = process.cwd()) {
+    const configDir = getLocalConfigDir(cwd);
+    const configPath = getLocalConfigPath(cwd);
+    await ensurePrivateDir(configDir);
+    await writePrivateFile(configPath, `${JSON.stringify(config, null, 2)}\n`);
+}
+export async function upsertLocalLink(link, input = {}) {
+    const cwd = input.cwd ?? process.cwd();
+    const existing = await loadLocalConfig(cwd);
+    const config = existing ?? {
+        version: 2,
+        defaultLinkKey: undefined,
+        links: {}
+    };
+    const key = makeLinkKey(link.project, link.environment);
+    config.links[key] = link;
+    if (input.setAsDefault ?? true) {
+        config.defaultLinkKey = key;
+    }
+    await saveLocalConfig(config, cwd);
+}
+export async function listLocalLinks(cwd = process.cwd()) {
+    const config = await loadLocalConfig(cwd);
+    if (!config) {
+        return [];
+    }
+    return Object.values(config.links).sort((a, b) => {
+        const projectCmp = a.project.localeCompare(b.project);
+        if (projectCmp !== 0) {
+            return projectCmp;
+        }
+        return a.environment.localeCompare(b.environment);
+    });
+}
+function resolveFromFilters(links, input) {
+    return links.filter((link) => {
+        if (input.project && link.project !== input.project) {
+            return false;
+        }
+        if (input.environment && link.environment !== input.environment) {
+            return false;
+        }
+        return true;
+    });
+}
+export async function requireLocalConfig(input = {}) {
+    const cwd = input.cwd ?? process.cwd();
+    const config = await loadLocalConfig(cwd);
+    if (!config) {
+        throw new Error("Missing local config. Run `cfenv setup` or `cfenv link` first.");
+    }
+    const links = Object.values(config.links);
+    if (!links.length) {
+        throw new Error("No links found in local config. Run `cfenv setup` or `cfenv link` first.");
+    }
+    const matches = resolveFromFilters(links, {
+        project: input.project,
+        environment: input.environment
+    });
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    if (matches.length > 1) {
+        if (config.defaultLinkKey) {
+            const defaultLink = config.links[config.defaultLinkKey];
+            if (defaultLink && matches.some((item) => item.project === defaultLink.project && item.environment === defaultLink.environment)) {
+                return defaultLink;
+            }
+        }
+        const options = matches.map((item) => `${item.project}/${item.environment}`).join(", ");
+        throw new Error(`Multiple matching links found. Specify --project/--env. Options: ${options}`);
+    }
+    if (input.project || input.environment) {
+        throw new Error(`No link found for project/env filters (${input.project ?? "*"} / ${input.environment ?? "*"}).`);
+    }
+    if (config.defaultLinkKey) {
+        const defaultLink = config.links[config.defaultLinkKey];
+        if (defaultLink) {
+            return defaultLink;
+        }
+    }
+    if (links.length === 1) {
+        return links[0];
+    }
+    const options = links.map((item) => `${item.project}/${item.environment}`).join(", ");
+    throw new Error(`Multiple environments configured. Specify --env (and optionally --project). Options: ${options}`);
+}
+export async function setDefaultLocalLink(input) {
+    const cwd = input.cwd ?? process.cwd();
+    const config = await loadLocalConfig(cwd);
+    if (!config) {
+        throw new Error("Missing local config. Run `cfenv setup` or `cfenv link` first.");
+    }
+    const links = Object.values(config.links);
+    const matches = resolveFromFilters(links, {
+        project: input.project,
+        environment: input.environment
+    });
+    if (matches.length !== 1) {
+        if (!matches.length) {
+            throw new Error(`No link found for environment "${input.environment}".`);
+        }
+        const options = matches.map((item) => `${item.project}/${item.environment}`).join(", ");
+        throw new Error(`Multiple matches for environment. Pass --project. Options: ${options}`);
+    }
+    const target = matches[0];
+    config.defaultLinkKey = makeLinkKey(target.project, target.environment);
+    await saveLocalConfig(config, cwd);
+    return target;
+}

package/dist/lib/paths.js

@@ -0,0 +1,21 @@
+import os from "node:os";
+import path from "node:path";
+export function getGlobalConfigDir() {
+    if (process.platform === "win32") {
+        return path.join(process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"), "cfenv");
+    }
+    const xdgConfig = process.env.XDG_CONFIG_HOME;
+    if (xdgConfig) {
+        return path.join(xdgConfig, "cfenv");
+    }
+    return path.join(os.homedir(), ".config", "cfenv");
+}
+export function getProfilesPath() {
+    return path.join(getGlobalConfigDir(), "profiles.json");
+}
+export function getLocalConfigDir(cwd) {
+    return path.join(cwd, ".cfenv");
+}
+export function getLocalConfigPath(cwd) {
+    return path.join(getLocalConfigDir(cwd), "config.json");
+}