ctx-sync 1.0.0

package/dist/core/encryption.js

@@ -0,0 +1,111 @@
+/**
+ * Age encryption wrapper module.
+ *
+ * Provides key generation, encryption, and decryption operations
+ * using the Age encryption library. All operations are in-memory only —
+ * no temporary files are created during crypto operations.
+ *
+ * @module core/encryption
+ */
+import { Encrypter, Decrypter, generateIdentity, identityToRecipient } from 'age-encryption';
+import { armor } from 'age-encryption';
+/**
+ * Generate a new Age key pair.
+ *
+ * @returns Object containing the public key (age1...) and private key (AGE-SECRET-KEY-...).
+ */
+export async function generateKey() {
+    const privateKey = await generateIdentity();
+    const publicKey = await identityToRecipient(privateKey);
+    return { publicKey, privateKey };
+}
+/**
+ * Encrypt a plaintext string with an Age public key.
+ *
+ * @param plaintext - The string to encrypt.
+ * @param publicKey - The Age public key (age1...) to encrypt for.
+ * @returns ASCII-armored Age ciphertext.
+ * @throws If the public key is invalid.
+ */
+export async function encrypt(plaintext, publicKey) {
+    const encrypter = new Encrypter();
+    encrypter.addRecipient(publicKey);
+    const encrypted = await encrypter.encrypt(plaintext);
+    return armor.encode(encrypted);
+}
+/**
+ * Decrypt an ASCII-armored Age ciphertext with a private key.
+ *
+ * @param ciphertext - The ASCII-armored Age ciphertext.
+ * @param privateKey - The Age private key (AGE-SECRET-KEY-...).
+ * @returns The decrypted plaintext string.
+ * @throws If the private key cannot decrypt the ciphertext.
+ */
+export async function decrypt(ciphertext, privateKey) {
+    const decrypter = new Decrypter();
+    decrypter.addIdentity(privateKey);
+    const decoded = armor.decode(ciphertext);
+    return decrypter.decrypt(decoded, 'text');
+}
+/**
+ * Encrypt a typed data object as JSON into an Age ciphertext blob.
+ * The data is serialised to JSON in memory, then encrypted.
+ * No plaintext JSON is ever written to disk.
+ *
+ * @param data - The data to encrypt.
+ * @param publicKey - The Age public key to encrypt for.
+ * @returns ASCII-armored Age ciphertext containing the serialised JSON.
+ */
+export async function encryptState(data, publicKey) {
+    const json = JSON.stringify(data);
+    return encrypt(json, publicKey);
+}
+/**
+ * Decrypt an Age ciphertext blob and parse the JSON back into a typed object.
+ *
+ * @param ciphertext - The ASCII-armored Age ciphertext.
+ * @param privateKey - The Age private key.
+ * @returns The decrypted and parsed data.
+ * @throws If decryption fails or the JSON is invalid.
+ */
+export async function decryptState(ciphertext, privateKey) {
+    const json = await decrypt(ciphertext, privateKey);
+    return JSON.parse(json);
+}
+/**
+ * Encrypt a plaintext string for multiple Age recipients.
+ *
+ * All recipients can independently decrypt the resulting ciphertext
+ * using their own private key. This enables team/multi-machine support.
+ *
+ * @param plaintext - The string to encrypt.
+ * @param publicKeys - Array of Age public keys (age1...) to encrypt for.
+ * @returns ASCII-armored Age ciphertext.
+ * @throws If any public key is invalid or the array is empty.
+ */
+export async function encryptForRecipients(plaintext, publicKeys) {
+    if (publicKeys.length === 0) {
+        throw new Error('At least one recipient public key is required.');
+    }
+    const encrypter = new Encrypter();
+    for (const key of publicKeys) {
+        encrypter.addRecipient(key);
+    }
+    const encrypted = await encrypter.encrypt(plaintext);
+    return armor.encode(encrypted);
+}
+/**
+ * Encrypt a typed data object as JSON for multiple Age recipients.
+ *
+ * Serialises the data to JSON in memory, then encrypts for all recipients.
+ * No plaintext JSON is ever written to disk.
+ *
+ * @param data - The data to encrypt.
+ * @param publicKeys - Array of Age public keys to encrypt for.
+ * @returns ASCII-armored Age ciphertext containing the serialised JSON.
+ */
+export async function encryptStateForRecipients(data, publicKeys) {
+    const json = JSON.stringify(data);
+    return encryptForRecipients(json, publicKeys);
+}
+//# sourceMappingURL=encryption.js.map

package/dist/core/encryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.js","sourceRoot":"","sources":["../../src/core/encryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC7F,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,UAAU,GAAG,MAAM,gBAAgB,EAAE,CAAC;IAC5C,MAAM,SAAS,GAAG,MAAM,mBAAmB,CAAC,UAAU,CAAC,CAAC;IACxD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,SAAiB,EAAE,SAAiB;IAChE,MAAM,SAAS,GAAG,IAAI,SAAS,EAAE,CAAC;IAClC,SAAS,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACrD,OAAO,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,UAAkB,EAAE,UAAkB;IAClE,MAAM,SAAS,GAAG,IAAI,SAAS,EAAE,CAAC;IAClC,SAAS,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAClC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACzC,OAAO,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,IAAO,EAAE,SAAiB;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,UAAkB,EAAE,UAAkB;IAC1E,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IACnD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,SAAiB,EACjB,UAAoB;IAEpB,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,SAAS,EAAE,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACrD,OAAO,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,IAAO,EACP,UAAoB;IAEpB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,oBAAoB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AAChD,CAAC"}

package/dist/core/env-handler.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Environment variable handler module.
+ *
+ * Implements encrypt-by-default semantics: all env vars are encrypted
+ * unless they appear on an explicit safe-list AND --allow-plain is used.
+ * Even safe-listed keys are encrypted if their value looks like a secret
+ * (high entropy or matches a known credential pattern).
+ *
+ * Secrets are NEVER accepted as CLI arguments — only via interactive
+ * prompt (hidden input), stdin pipe, or file descriptor.
+ *
+ * @module core/env-handler
+ */
+/**
+ * Determine whether an environment variable should be encrypted.
+ *
+ * Default: ALWAYS encrypt. Only safe-listed keys may be stored plain,
+ * and even then only if the value does not look sensitive.
+ *
+ * @param key - The env var key name.
+ * @param value - The env var value.
+ * @param safeList - Override safe-list (defaults to DEFAULT_SAFE_LIST).
+ * @returns `true` if the value should be encrypted.
+ */
+export declare function shouldEncrypt(key: string, value: string, safeList?: readonly string[]): boolean;
+/**
+ * Calculate Shannon entropy for a string.
+ *
+ * High-entropy strings (> 4.0 bits/char) are likely API keys, tokens,
+ * or other random secrets. Strings shorter than 16 chars are ignored
+ * (too short for meaningful entropy measurement).
+ *
+ * @param value - The string to check.
+ * @returns `true` if the string has high entropy (likely a secret).
+ */
+export declare function hasHighEntropy(value: string): boolean;
+/**
+ * Check whether a value matches known credential patterns.
+ *
+ * Detects common service token prefixes, JWTs, PEM keys, and
+ * URLs with embedded credentials.
+ *
+ * @param value - The string to check.
+ * @returns `true` if the value matches a known credential pattern.
+ */
+export declare function containsCredentialPattern(value: string): boolean;
+/** Parsed environment variable from a .env file */
+export interface ParsedEnvVar {
+    key: string;
+    value: string;
+}
+/**
+ * Parse the content of a `.env` file.
+ *
+ * Handles:
+ * - Standard `KEY=value` pairs
+ * - Comments (lines starting with `#`)
+ * - Empty lines
+ * - Quoted values (single and double)
+ * - `export` prefix (`export KEY=value`)
+ * - Windows line endings (`\r\n`)
+ * - Lines with no `=` (ignored)
+ * - Lines with `=` but no value (empty string value)
+ * - Duplicate keys (last value wins)
+ *
+ * @param content - The raw content of a `.env` file.
+ * @returns Array of parsed key-value pairs.
+ */
+export declare function parseEnvFile(content: string): ParsedEnvVar[];
+/**
+ * Import multiple environment variables for a project.
+ *
+ * Reads existing env-vars.age (if any), merges in new vars, encrypts
+ * and writes back. All vars are encrypted by default — the entire .age
+ * file is a single encrypted blob.
+ *
+ * @param project - The project name.
+ * @param vars - Array of key-value pairs to import.
+ * @param stateDir - The sync directory path.
+ * @param publicKey - The Age public key for encryption.
+ * @param privateKey - The Age private key for decryption (to read existing state).
+ * @returns The count of imported variables.
+ */
+export declare function importEnvVars(project: string, vars: ParsedEnvVar[], stateDir: string, publicKey: string, privateKey: string): Promise<number>;
+/**
+ * Add a single environment variable for a project.
+ *
+ * @param project - The project name.
+ * @param key - The variable key.
+ * @param value - The variable value (must come from hidden input / stdin, NEVER CLI args).
+ * @param stateDir - The sync directory path.
+ * @param publicKey - The Age public key.
+ * @param privateKey - The Age private key.
+ */
+export declare function addEnvVar(project: string, key: string, value: string, stateDir: string, publicKey: string, privateKey: string): Promise<void>;
+/** A listed env var (value optionally hidden) */
+export interface ListedEnvVar {
+    key: string;
+    value: string;
+    addedAt: string;
+}
+/**
+ * List environment variables for a project.
+ *
+ * @param project - The project name.
+ * @param stateDir - The sync directory path.
+ * @param privateKey - The Age private key for decryption.
+ * @param showValues - If `true`, decrypted values are returned; otherwise masked as '********'.
+ * @returns Array of env vars (values hidden by default).
+ */
+export declare function listEnvVars(project: string, stateDir: string, privateKey: string, showValues?: boolean): Promise<ListedEnvVar[]>;
+/**
+ * Validate that a key argument does not contain an embedded value.
+ *
+ * Rejects `KEY=value` syntax in CLI arguments to prevent secrets
+ * from appearing in shell history and process lists.
+ *
+ * @param keyArg - The key argument from the CLI.
+ * @throws If the key contains `=` followed by a value.
+ */
+export declare function validateKeyArg(keyArg: string): string;
+/**
+ * Read a value from stdin (for piped input).
+ *
+ * @returns The value read from stdin, trimmed.
+ */
+export declare function readValueFromStdin(): Promise<string>;
+//# sourceMappingURL=env-handler.d.ts.map

package/dist/core/env-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-handler.d.ts","sourceRoot":"","sources":["../../src/core/env-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,SAAS,MAAM,EAAsB,GAC9C,OAAO,CAYT;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAkBrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBhE;AAED,mDAAmD;AACnD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CA8D5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,YAAY,EAAE,EACpB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,UAAU,GAAE,OAAe,GAC1B,OAAO,CAAC,YAAY,EAAE,CAAC,CAazB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAgBrD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAuBpD"}

package/dist/core/env-handler.js

@@ -0,0 +1,272 @@
+/**
+ * Environment variable handler module.
+ *
+ * Implements encrypt-by-default semantics: all env vars are encrypted
+ * unless they appear on an explicit safe-list AND --allow-plain is used.
+ * Even safe-listed keys are encrypted if their value looks like a secret
+ * (high entropy or matches a known credential pattern).
+ *
+ * Secrets are NEVER accepted as CLI arguments — only via interactive
+ * prompt (hidden input), stdin pipe, or file descriptor.
+ *
+ * @module core/env-handler
+ */
+import { DEFAULT_SAFE_LIST } from '@ctx-sync/shared';
+import { readState, writeState } from './state-manager.js';
+/**
+ * Determine whether an environment variable should be encrypted.
+ *
+ * Default: ALWAYS encrypt. Only safe-listed keys may be stored plain,
+ * and even then only if the value does not look sensitive.
+ *
+ * @param key - The env var key name.
+ * @param value - The env var value.
+ * @param safeList - Override safe-list (defaults to DEFAULT_SAFE_LIST).
+ * @returns `true` if the value should be encrypted.
+ */
+export function shouldEncrypt(key, value, safeList = DEFAULT_SAFE_LIST) {
+    // If not on the safe-list → always encrypt
+    if (!safeList.includes(key.toUpperCase())) {
+        return true;
+    }
+    // On the safe-list, but double-check value doesn't look sensitive
+    if (hasHighEntropy(value) || containsCredentialPattern(value)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Calculate Shannon entropy for a string.
+ *
+ * High-entropy strings (> 4.0 bits/char) are likely API keys, tokens,
+ * or other random secrets. Strings shorter than 16 chars are ignored
+ * (too short for meaningful entropy measurement).
+ *
+ * @param value - The string to check.
+ * @returns `true` if the string has high entropy (likely a secret).
+ */
+export function hasHighEntropy(value) {
+    if (value.length < 16) {
+        return false;
+    }
+    const freq = {};
+    for (const ch of value) {
+        freq[ch] = (freq[ch] ?? 0) + 1;
+    }
+    const len = value.length;
+    let entropy = 0;
+    for (const count of Object.values(freq)) {
+        const p = count / len;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy > 4.0;
+}
+/**
+ * Check whether a value matches known credential patterns.
+ *
+ * Detects common service token prefixes, JWTs, PEM keys, and
+ * URLs with embedded credentials.
+ *
+ * @param value - The string to check.
+ * @returns `true` if the value matches a known credential pattern.
+ */
+export function containsCredentialPattern(value) {
+    const patterns = [
+        /^sk_/, // Stripe
+        /^ghp_/, // GitHub PAT
+        /^gho_/, // GitHub OAuth
+        /^github_pat_/, // GitHub fine-grained PAT
+        /^xoxb-/, // Slack bot
+        /^xoxp-/, // Slack user
+        /^AIza/, // Google API
+        /^AKIA/, // AWS Access Key
+        /^eyJ[A-Za-z0-9_-]+\./, // JWT tokens
+        /-----BEGIN\s+(RSA\s+)?PRIVATE KEY-----/, // PEM private keys
+        /-----BEGIN\s+CERTIFICATE-----/, // Certificates
+        /:\/\/[^:]*:[^@]+@/, // URLs with embedded credentials
+        /^SG\./, // SendGrid
+        /^AC[a-f0-9]{32}/, // Twilio
+        /^sk-[a-zA-Z0-9]{20,}/, // OpenAI
+    ];
+    return patterns.some((p) => p.test(value));
+}
+/**
+ * Parse the content of a `.env` file.
+ *
+ * Handles:
+ * - Standard `KEY=value` pairs
+ * - Comments (lines starting with `#`)
+ * - Empty lines
+ * - Quoted values (single and double)
+ * - `export` prefix (`export KEY=value`)
+ * - Windows line endings (`\r\n`)
+ * - Lines with no `=` (ignored)
+ * - Lines with `=` but no value (empty string value)
+ * - Duplicate keys (last value wins)
+ *
+ * @param content - The raw content of a `.env` file.
+ * @returns Array of parsed key-value pairs.
+ */
+export function parseEnvFile(content) {
+    const result = [];
+    const seen = new Map();
+    // Strip null bytes and other control characters (except \n, \r, \t)
+    // eslint-disable-next-line no-control-regex
+    const sanitised = content.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '');
+    // Normalise line endings
+    const lines = sanitised.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        // Skip empty lines and comments
+        if (!line || line.startsWith('#')) {
+            continue;
+        }
+        // Strip optional `export ` prefix
+        const stripped = line.startsWith('export ')
+            ? line.slice('export '.length).trim()
+            : line;
+        // Must contain `=`
+        const eqIndex = stripped.indexOf('=');
+        if (eqIndex === -1) {
+            continue;
+        }
+        const key = stripped.slice(0, eqIndex).trim();
+        if (!key) {
+            continue; // Skip lines like `=value`
+        }
+        let value = stripped.slice(eqIndex + 1).trim();
+        // Strip surrounding quotes
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        // Truncate excessively long values (> 1MB) to prevent memory issues
+        const MAX_VALUE_LENGTH = 1_048_576; // 1 MB
+        if (value.length > MAX_VALUE_LENGTH) {
+            value = value.slice(0, MAX_VALUE_LENGTH);
+        }
+        // Handle duplicate keys — last value wins
+        const existingIndex = seen.get(key);
+        if (existingIndex !== undefined) {
+            result[existingIndex] = { key, value };
+        }
+        else {
+            seen.set(key, result.length);
+            result.push({ key, value });
+        }
+    }
+    return result;
+}
+/**
+ * Import multiple environment variables for a project.
+ *
+ * Reads existing env-vars.age (if any), merges in new vars, encrypts
+ * and writes back. All vars are encrypted by default — the entire .age
+ * file is a single encrypted blob.
+ *
+ * @param project - The project name.
+ * @param vars - Array of key-value pairs to import.
+ * @param stateDir - The sync directory path.
+ * @param publicKey - The Age public key for encryption.
+ * @param privateKey - The Age private key for decryption (to read existing state).
+ * @returns The count of imported variables.
+ */
+export async function importEnvVars(project, vars, stateDir, publicKey, privateKey) {
+    // Read existing env vars
+    const existing = (await readState(stateDir, privateKey, 'env-vars')) ?? {};
+    // Ensure project bucket exists
+    const projectBucket = existing[project] ?? {};
+    existing[project] = projectBucket;
+    const now = new Date().toISOString();
+    for (const { key, value } of vars) {
+        projectBucket[key] = {
+            value,
+            addedAt: now,
+        };
+    }
+    // Write encrypted state
+    await writeState(stateDir, existing, publicKey, 'env-vars');
+    return vars.length;
+}
+/**
+ * Add a single environment variable for a project.
+ *
+ * @param project - The project name.
+ * @param key - The variable key.
+ * @param value - The variable value (must come from hidden input / stdin, NEVER CLI args).
+ * @param stateDir - The sync directory path.
+ * @param publicKey - The Age public key.
+ * @param privateKey - The Age private key.
+ */
+export async function addEnvVar(project, key, value, stateDir, publicKey, privateKey) {
+    await importEnvVars(project, [{ key, value }], stateDir, publicKey, privateKey);
+}
+/**
+ * List environment variables for a project.
+ *
+ * @param project - The project name.
+ * @param stateDir - The sync directory path.
+ * @param privateKey - The Age private key for decryption.
+ * @param showValues - If `true`, decrypted values are returned; otherwise masked as '********'.
+ * @returns Array of env vars (values hidden by default).
+ */
+export async function listEnvVars(project, stateDir, privateKey, showValues = false) {
+    const envVars = await readState(stateDir, privateKey, 'env-vars');
+    if (!envVars || !envVars[project]) {
+        return [];
+    }
+    const projectVars = envVars[project] ?? {};
+    return Object.entries(projectVars).map(([key, entry]) => ({
+        key,
+        value: showValues ? entry.value : '********',
+        addedAt: entry.addedAt,
+    }));
+}
+/**
+ * Validate that a key argument does not contain an embedded value.
+ *
+ * Rejects `KEY=value` syntax in CLI arguments to prevent secrets
+ * from appearing in shell history and process lists.
+ *
+ * @param keyArg - The key argument from the CLI.
+ * @throws If the key contains `=` followed by a value.
+ */
+export function validateKeyArg(keyArg) {
+    if (keyArg.includes('=')) {
+        const eqIndex = keyArg.indexOf('=');
+        const afterEq = keyArg.slice(eqIndex + 1);
+        if (afterEq.length > 0) {
+            throw new Error('Cannot pass secret values as CLI arguments.\n' +
+                'Secret values are visible in shell history and process lists.\n\n' +
+                'Use one of these secure methods instead:\n' +
+                `  Interactive:  ctx-sync env add <project> ${keyArg.slice(0, eqIndex)}\n` +
+                `  Stdin pipe:   echo "value" | ctx-sync env add <project> ${keyArg.slice(0, eqIndex)} --stdin\n` +
+                `  File desc:    ctx-sync env add <project> ${keyArg.slice(0, eqIndex)} --from-fd 3 3< <(pass show key)`);
+        }
+    }
+    return keyArg;
+}
+/**
+ * Read a value from stdin (for piped input).
+ *
+ * @returns The value read from stdin, trimmed.
+ */
+export function readValueFromStdin() {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        if (process.stdin.isTTY) {
+            reject(new Error('No data piped to stdin.\n' +
+                'Usage: echo "value" | ctx-sync env add <project> <key> --stdin'));
+            return;
+        }
+        process.stdin.setEncoding('utf-8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => {
+            resolve(data.trim());
+        });
+        process.stdin.on('error', reject);
+    });
+}
+//# sourceMappingURL=env-handler.js.map

package/dist/core/env-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-handler.js","sourceRoot":"","sources":["../../src/core/env-handler.ts"],"names":[],"mappings":"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"}

package/dist/core/git-sync.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Git sync engine module.
+ *
+ * Manages the local Git repository used for syncing encrypted state
+ * files between machines. Provides operations for init, commit, push,
+ * pull, and status queries. All remote operations validate transport
+ * security before proceeding.
+ *
+ * @module core/git-sync
+ */
+/** Result of a getStatus() call */
+export interface SyncStatus {
+    /** List of changed/untracked files */
+    files: string[];
+    /** Number of commits ahead of remote */
+    ahead: number;
+    /** Number of commits behind remote */
+    behind: number;
+    /** Whether the working tree is clean */
+    isClean: boolean;
+}
+/**
+ * Initialise a Git repository in the given directory.
+ *
+ * If the directory already contains a `.git/` folder, this is a no-op.
+ * Otherwise, a new Git repository is created with `git init`.
+ *
+ * @param dir - The directory to initialise.
+ * @returns `true` if a new repo was created, `false` if one already existed.
+ */
+export declare function initRepo(dir: string): Promise<boolean>;
+/**
+ * Add a remote to the Git repository.
+ *
+ * Validates the URL using transport security before adding.
+ * If a remote with the given name already exists, it is updated.
+ *
+ * @param dir - The Git repository directory.
+ * @param url - The remote URL (SSH or HTTPS).
+ * @param remoteName - The name for the remote (default: 'origin').
+ * @throws If the URL uses an insecure protocol.
+ */
+export declare function addRemote(dir: string, url: string, remoteName?: string): Promise<void>;
+/**
+ * Stage files and commit changes to the sync repository.
+ *
+ * Stages the specified files, then commits with the given message.
+ * If there are no changes to commit (working tree is clean after staging),
+ * the commit is skipped and `null` is returned.
+ *
+ * @param dir - The Git repository directory.
+ * @param files - List of file paths (relative to dir) to stage.
+ * @param message - The commit message.
+ * @returns The commit hash, or `null` if no changes were committed.
+ */
+export declare function commitState(dir: string, files: string[], message: string): Promise<string | null>;
+/**
+ * Push the local sync repository to the remote.
+ *
+ * Validates the remote URL before pushing. If no remote is configured,
+ * the push is skipped.
+ *
+ * @param dir - The Git repository directory.
+ * @param remoteName - The remote name (default: 'origin').
+ * @param branch - The branch to push (default: 'main').
+ * @throws If the remote URL uses an insecure protocol.
+ */
+export declare function pushState(dir: string, remoteName?: string, branch?: string): Promise<void>;
+/**
+ * Pull the latest changes from the remote sync repository.
+ *
+ * Validates the remote URL before pulling. If no remote is configured,
+ * the pull is skipped.
+ *
+ * @param dir - The Git repository directory.
+ * @param remoteName - The remote name (default: 'origin').
+ * @param branch - The branch to pull (default: 'main').
+ * @throws If the remote URL uses an insecure protocol.
+ */
+export declare function pullState(dir: string, remoteName?: string, branch?: string): Promise<void>;
+/**
+ * Get the current sync status of the repository.
+ *
+ * @param dir - The Git repository directory.
+ * @returns An object describing changed files, ahead/behind counts, and cleanliness.
+ */
+export declare function getStatus(dir: string): Promise<SyncStatus>;
+//# sourceMappingURL=git-sync.d.ts.map

package/dist/core/git-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-sync.d.ts","sourceRoot":"","sources":["../../src/core/git-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAY5D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,MAAiB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,MAAiB,EAC7B,MAAM,GAAE,MAAe,GACtB,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,MAAiB,EAC7B,MAAM,GAAE,MAAe,GACtB,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAUhE"}