@typinghare/trick 1.0.6 → 2.0.0

package/README.md

@@ -3,5 +3,91 @@
 # Install
 
 ```shell
+# npm
+npm install -g @typinghare/trick
+
+# pnpm
 pnpm add -g @typinghare/trick
+
+# yarn
+yarn add -g @typinghare/trick
+```
+
+## Philosophy
+
+We often add sensitive and credential files, such as `.env` and `api_key.conf`, to `.gitignore`, preventing them from being committed or even pushed to remote depots for safety reasons. Then, we have to manually copy the file to the server. It would be effortless if we only had one file, but imagine we have a lot in a bigger project. Even worse, some careless people (me) have even lost these sensitive files after changing computers!
+
+**Trick** helps you to encrypt sensitive files with a passphrase so that you can upload the credential file to Git platforms. Later on the server, just use the same passphrase to decrypt the files with ease.
+
+## Quick Example
+
+Set up the **target** with the files needed to be encrypted:
+
+```bash
+# This will create a trick.config.json in the current working directory
+# trick add <target> [files...]
+$ trick add MyTargetName .env api_key.conf
+
+# Display the list of target names and the files bound
+$ trick list
+```
+
+Create a `passphrase.json` file under `~/.config` with the following content:
+
+```json
+{
+    "MyTargetName": "Reg5eGPXWdmeW0i08uaygBlfbXP+tJlnu7z551Qt568="
+}
+```
+
+Here, the key is the target name, and the value is the `passphrase` that is used to encrypt/decrypt the files associated with this target name.
+
+Encrypt the files:
+
+```bash
+$ trick encrypt MyTargetName
+```
+
+You will see the following output:
+
+```text
+[ENCRYPTED] .env -> .trick/encrypted/.env.enc
+[ENCRYPTED] api_key.conf -> .trick/encrypted/api_key.conf.enc
+```
+
+Encrypted files are all saved to `.trick`. On the server, set the the `passphrase.json` in the same way, and execute:
+
+```bash
+$ trick decrypt MyTargetName
+```
+
+And you will see that the files are restored:
+
+```text
+[DECRYPTED] .trick/encrypted/.env.enc -> .env
+[DECRYPTED] .trick/encrypted/api_key.conf.enc -> api_key.conf
+```
+
+> [!IMPORTANT]
+> The `passphrase.json` collects all the passphrases you have. Please back it up in multiple devices every time you edit it!
+
+## More Features
+
+### Default Target Name
+
+You can set the default target name so that you don't need to input it every time:
+
+```bash
+# Set the default target name
+$ trick set-default MyTargetName
+
+# Display the default target name
+$ trick get-default
+```
+
+Now you can encrypt and decrypt more easily:
+
+```bash
+$ trick encrypt
+$ trick decrypt
 ```

package/dist/app.d.ts

@@ -1 +1 @@
-export declare function resolve_error(err: any): void;
+export {};

package/dist/app.js

@@ -1,92 +1,120 @@
 import { Command } from 'commander';
-import { getTargetFromConfig, ReadConfigError, TargetNotFoundError, updateConfig, WriteConfigError, } from './config.js';
-import { decryptFiles, encryptFiles, FailToDecryptFileError, FailToEncryptFileError, } from './encrypt.js';
-import { getSecret, SecretNotFoundError } from './secret.js';
-import { TRICK_ENCRYPTED_DIR } from './constant.js';
+import { getTargetFromConfig, updateConfig } from './config.js';
+import { decryptFiles, encryptFiles } from './encrypt.js';
 import fsExtra from 'fs-extra';
 import chalk from 'chalk';
+import { getPassphrase } from './passphrase.js';
+import { resolve_error } from './error.js';
 const program = new Command();
-program.version('Trick v1.0.6');
-program.description('Save credential files to remote safely.');
+program.version('2.0.0');
+program.description('Save credential files to remote safely and easily.');
 program
     .command('add')
-    .description('Adds a target.')
-    .argument('<secret-name>', 'The name of secret in the environment')
-    .argument('[files...]', 'Files this target will encrypt')
-    .action(async (secretName, files) => {
+    .description('Add files to a target.')
+    .argument('<name>', 'The name of the target')
+    .argument('[files...]', 'Files that are encrypted')
+    .action(async (targetName, files) => {
     await updateConfig((config) => {
         try {
-            getTargetFromConfig(config, secretName);
+            const target = getTargetFromConfig(config, targetName);
+            target.files.push(...files);
         }
         catch (err) {
-            config.default_secret_name = secretName;
-            config.targets.push({
-                secret_name: secretName,
-                files,
-            });
-            return true;
+            config.default_target_name = targetName;
+            config.targets[targetName] = { files };
         }
-        console.error(`Target with the secret name already exists: ${secretName}`);
-        console.error('Abort adding target');
-        process.exit(1);
+        return true;
     });
 });
-function checkSecretName(secretName, defaultSecretName) {
-    if (!secretName) {
-        secretName = defaultSecretName;
+program
+    .command('remove')
+    .description('Remove files from a target.')
+    .argument('<name>', 'The name of the target')
+    .argument('[files...]', 'Files to remove')
+    .option('-t, --target', 'Remove the target instead.')
+    .action(async (targetName, files, options) => {
+    if (options.target) {
+        // Remove the target
+        return await updateConfig((config) => {
+            getTargetFromConfig(config, targetName);
+            delete config.targets[targetName];
+            console.log(`[SUCCESS] Removed target: ${targetName}`);
+            return true;
+        });
     }
-    if (!secretName) {
-        throw new Error('No secret name given, and the default secret name is not set.');
+    // Remove files from the target
+    await updateConfig((config) => {
+        const target = getTargetFromConfig(config, targetName);
+        const removedFiles = [];
+        const remainingFiles = [];
+        for (const file of target.files) {
+            if (files.includes(file)) {
+                removedFiles.push(file);
+                console.log(`[SUCCESS] Removed file: ${file}`);
+            }
+            else {
+                remainingFiles.push(file);
+            }
+        }
+        target.files = remainingFiles;
+        const notFoundFiles = files.filter((it) => !removedFiles.includes(it));
+        for (const notFoundFile of notFoundFiles) {
+            console.log(`[WARNING] File not found in the target: ${notFoundFile}`);
+        }
+        return true;
+    });
+});
+function getTargetName(targetNameOrNull, defaultTargetName) {
+    const targetName = targetNameOrNull === null ? defaultTargetName : targetNameOrNull;
+    if (targetName === null) {
+        throw new Error('Target is not specified and the default target name is null!');
     }
-    return secretName;
+    return targetName;
 }
 program
     .command('encrypt')
     .description('Encrypt the credential files.')
-    .argument('[secret-name]', 'The name of secret in the environment', undefined)
-    .action(async (secretName) => {
+    .argument('[target]', 'The name of the target', null)
+    .action(async (targetNameOrNull) => {
     await updateConfig((config) => {
-        secretName = checkSecretName(secretName, config.default_secret_name);
-        const target = getTargetFromConfig(config, secretName);
-        const secret = getSecret(target.secret_name);
+        const targetName = getTargetName(targetNameOrNull, config.default_target_name);
+        const target = getTargetFromConfig(config, targetName);
+        const passphrase = getPassphrase(config, targetName);
         const srcFilePaths = target.files;
-        fsExtra.ensureDir(TRICK_ENCRYPTED_DIR);
-        encryptFiles(srcFilePaths, TRICK_ENCRYPTED_DIR, secret, config.iteration_count);
-        return false;
+        fsExtra.ensureDir(config.root_directory);
+        encryptFiles(srcFilePaths, config.root_directory, passphrase, config.encryption.iteration_count);
     });
 });
 program
     .command('decrypt')
     .description('Decrypt the credential files.')
-    .argument('[secret-name]', 'The name of secret in the environment', undefined)
-    .action(async (secretName) => {
+    .argument('[target]', 'The name of the target', null)
+    .action(async (targetNameOrNull) => {
     await updateConfig((config) => {
-        secretName = checkSecretName(secretName, config.default_secret_name);
-        const target = getTargetFromConfig(config, secretName);
-        const secret = getSecret(target.secret_name);
+        const targetName = getTargetName(targetNameOrNull, config.default_target_name);
+        const target = getTargetFromConfig(config, targetName);
+        const passphrase = getPassphrase(config, targetName);
         const srcFilePaths = target.files;
-        fsExtra.ensureDir(TRICK_ENCRYPTED_DIR);
-        decryptFiles(srcFilePaths, TRICK_ENCRYPTED_DIR, secret, config.iteration_count);
-        return false;
+        fsExtra.ensureDir(config.root_directory);
+        decryptFiles(srcFilePaths, config.root_directory, passphrase, config.encryption.iteration_count);
     });
 });
 program
     .command('set-default')
-    .description('Set the default secret name.')
-    .argument('<secret-name>', 'The name of secret in the environment')
-    .action(async (secretName) => {
+    .description('Set the default target name.')
+    .argument('<target>', 'The name of the target to set')
+    .action(async (targetName) => {
     await updateConfig((config) => {
-        config.default_secret_name = secretName;
+        config.default_target_name = targetName;
         return true;
     });
 });
 program
     .command('get-default')
-    .description('Get the default secret name.')
+    .description('Get the default target name.')
     .action(async () => {
     await updateConfig((config) => {
-        console.log(config.default_secret_name);
-        return false;
+        console.log(config.default_target_name);
     });
 });
 program
@@ -94,13 +122,12 @@ program
     .description('Display a list of targets.')
     .action(async () => {
     await updateConfig((config) => {
-        for (const target of config.targets) {
-            console.log(chalk.cyan(target.secret_name));
+        for (const [targetName, target] of Object.entries(config.targets)) {
+            console.log(chalk.cyan(targetName));
             for (const file of target.files) {
                 console.log('    ' + chalk.yellow(file));
             }
         }
-        return false;
     });
 });
 program.parse();
@@ -108,40 +135,3 @@ process.on('uncaughtException', (err) => {
     resolve_error(err);
     process.exit(1);
 });
-export function resolve_error(err) {
-    if (!(err instanceof Error)) {
-        console.error(`Unknown error: ${err}`);
-        process.exit(2);
-    }
-    if (err instanceof WriteConfigError) {
-        console.error(chalk.red('Fail to write Trick config file'));
-    }
-    else if (err instanceof ReadConfigError) {
-        console.error(chalk.red('Fail to read Trick config file'));
-    }
-    else if (err instanceof SecretNotFoundError) {
-        console.error(chalk.red(err.message));
-    }
-    else if (err instanceof TargetNotFoundError) {
-        console.error(chalk.red(err.message));
-    }
-    else if (err instanceof FailToEncryptFileError) {
-        console.error(chalk.red(err.message));
-        if (err.opensslErrMessage) {
-            console.error(chalk.red(err.opensslErrMessage));
-        }
-        else {
-            console.error(chalk.yellow('Make sure the file exists and you have enough permission to access it'));
-        }
-    }
-    else if (err instanceof FailToDecryptFileError) {
-        console.error(chalk.red(err.message));
-        if (err.opensslErrMessage) {
-            console.error(chalk.red(err.opensslErrMessage));
-        }
-        else {
-            console.error(chalk.yellow('Make sure the file exists and you have enough permission to access it'));
-        }
-    }
-    process.exit(1);
-}

package/dist/config.d.ts

@@ -1,23 +1,80 @@
+/**
+ * The name of the configuration file to look for in the root directory.
+ */
 export declare const CONFIG_FILE_NAME: string;
+/**
+ * Config type.
+ *
+ * @property targets Mapping from target names to target objects.
+ * @property default_target_name The name of the default target.
+ * @property root_directory The root directory.
+ * @property passphrase_file_path The path to the passphrase file.
+ * @property encryption Encryption configuration.
+ */
 export interface Config {
-    iteration_count: number;
-    default_secret_name?: string;
-    targets: Target[];
+    targets: {
+        [name: string]: Target;
+    };
+    default_target_name: string | null;
+    root_directory: string;
+    passphrase_file_path: string;
+    encryption: Encryption;
 }
+/**
+ * Target type.
+ *
+ * @property files A list of files to encrypt/decrypt.
+ */
 export interface Target {
-    secret_name: string;
     files: string[];
 }
-export declare class WriteConfigError extends Error {
-}
-export declare class ReadConfigError extends Error {
+/**
+ * Encryption configuration.
+ *
+ * @property iteration_count The number of iteration.
+ */
+export interface Encryption {
+    iteration_count: number;
 }
+/**
+ * Writes a configuration object to the configuration file.
+ *
+ * @param config The configuration to write.
+ * @throws {WriteConfigError} If error occurs when writing to the configuration
+ *         file.
+ */
 export declare function writeConfig(config: Config): Promise<void>;
+/**
+ * Retrieves the configuration object from the configuration file.
+ *
+ * @return The configuration object retrieved from the configuration object;
+ *         null if the configuration file doesn't exist.
+ * @throws {ReadConfigError} If error occurs when reading the configuration
+ *         file.
+ */
 export declare function readConfig(): Promise<Config | null>;
-export declare function updateConfig(callback: UpdateConfigCallback): Promise<void>;
-export type UpdateConfigCallback = (config: Config) => boolean;
-export declare class TargetNotFoundError extends Error {
-    readonly secretName: string;
-    constructor(secretName: string);
-}
-export declare function getTargetFromConfig(config: Config, secretName: string): Target;
+/**
+ * Updates the configuration object.
+ *
+ * This function first retrieves the configuration object fromthe configuration
+ * file. If the configuration file doesn't exist, the default configuration will
+ * be used instead.
+ *
+ * Then it calls the callback function by passing on the configuration object.
+ * If the callback function returns `true`, then the object will be written to
+ * the configuration file.
+ *
+ * @param callback The callback function taking the configuraition object
+ *                 retrieved from the configuration file.
+ * @see DEFAULT_CONFIG
+ */
+export declare function updateConfig(callback: (Config: Config) => boolean | void): Promise<void>;
+/**
+ * Gets a target object from a specified configuration object.
+ *
+ * @param config The configuration object to get the target from.
+ * @param targetName The name of the target to get.
+ * @return The target object associated with the given name.
+ * @throws {TargetNotFoundError} If the target object is not found.
+ */
+export declare function getTargetFromConfig(config: Config, targetName: string): Target;

package/dist/config.js

@@ -1,21 +1,44 @@
 import fsExtra from 'fs-extra';
+import { ReadConfigError, TargetNotFoundError, WriteConfigError, } from './error.js';
+/**
+ * The name of the configuration file to look for in the root directory.
+ */
 export const CONFIG_FILE_NAME = 'trick.config.json';
-const defaultConfig = {
-    iteration_count: 114514,
-    targets: [],
+/**
+ * Default configuration.
+ */
+const DEFAULT_CONFIG = {
+    targets: {},
+    default_target_name: null,
+    root_directory: '.trick',
+    passphrase_file_path: '~/.config/trick_passphrase.json',
+    encryption: {
+        iteration_count: 0,
+    },
 };
-export class WriteConfigError extends Error {
-}
-export class ReadConfigError extends Error {
-}
+/**
+ * Writes a configuration object to the configuration file.
+ *
+ * @param config The configuration to write.
+ * @throws {WriteConfigError} If error occurs when writing to the configuration
+ *         file.
+ */
 export async function writeConfig(config) {
     try {
-        await fsExtra.writeJson(CONFIG_FILE_NAME, config);
+        await fsExtra.writeFile(CONFIG_FILE_NAME, JSON.stringify(config, null, 2));
     }
     catch (err) {
-        throw new WriteConfigError();
+        throw new WriteConfigError(err);
     }
 }
+/**
+ * Retrieves the configuration object from the configuration file.
+ *
+ * @return The configuration object retrieved from the configuration object;
+ *         null if the configuration file doesn't exist.
+ * @throws {ReadConfigError} If error occurs when reading the configuration
+ *         file.
+ */
 export async function readConfig() {
     if (!fsExtra.existsSync(CONFIG_FILE_NAME)) {
         return null;
@@ -24,28 +47,42 @@ export async function readConfig() {
         return (await fsExtra.readJSON(CONFIG_FILE_NAME));
     }
     catch (err) {
-        throw new ReadConfigError();
+        throw new ReadConfigError(err);
     }
 }
+/**
+ * Updates the configuration object.
+ *
+ * This function first retrieves the configuration object fromthe configuration
+ * file. If the configuration file doesn't exist, the default configuration will
+ * be used instead.
+ *
+ * Then it calls the callback function by passing on the configuration object.
+ * If the callback function returns `true`, then the object will be written to
+ * the configuration file.
+ *
+ * @param callback The callback function taking the configuraition object
+ *                 retrieved from the configuration file.
+ * @see DEFAULT_CONFIG
+ */
 export async function updateConfig(callback) {
-    const config = (await readConfig()) || defaultConfig;
+    const config = (await readConfig()) || DEFAULT_CONFIG;
     if (callback(config)) {
         await writeConfig(config);
     }
 }
-export class TargetNotFoundError extends Error {
-    secretName;
-    constructor(secretName) {
-        super(`Target not found: ${secretName}`);
-        this.secretName = secretName;
-    }
-}
-export function getTargetFromConfig(config, secretName) {
-    const targets = config.targets;
-    for (const target of targets) {
-        if (target.secret_name === secretName) {
-            return target;
-        }
+/**
+ * Gets a target object from a specified configuration object.
+ *
+ * @param config The configuration object to get the target from.
+ * @param targetName The name of the target to get.
+ * @return The target object associated with the given name.
+ * @throws {TargetNotFoundError} If the target object is not found.
+ */
+export function getTargetFromConfig(config, targetName) {
+    const target = config.targets[targetName];
+    if (!target) {
+        throw new TargetNotFoundError(targetName);
     }
-    throw new TargetNotFoundError(secretName);
+    return target;
 }

package/dist/encrypt.d.ts

@@ -1,14 +1,68 @@
-export declare class FailToEncryptFileError extends Error {
-    readonly srcFilePath: string;
-    readonly opensslErrMessage?: string | undefined;
-    constructor(srcFilePath: string, opensslErrMessage?: string | undefined);
-}
-export declare class FailToDecryptFileError extends Error {
-    readonly destFilePath: string;
-    readonly opensslErrMessage?: string | undefined;
-    constructor(destFilePath: string, opensslErrMessage?: string | undefined);
-}
-export declare function encryptFile(srcFilePath: string, destFilePath: string, secret: string, iteration_count: number): Promise<void>;
-export declare function decryptFile(srcFilePath: string, destFilePath: string, secret: string, iteration_count: number): Promise<void>;
-export declare function encryptFiles(srcFilePaths: string[], destDir: string, secret: string, iteration_count: number): Promise<void>;
-export declare function decryptFiles(srcFilePaths: string[], destDir: string, secret: string, iteration_count: number): Promise<void>;
+/**
+ * Encrypts a file using OpenSSL with AES-256-CBC and PBKDF2 key derivation.
+ *
+ * This function checks whether the source file exists, constructs an OpenSSL
+ * command, ensures the destination directory exists, and then executes the
+ * encryption command.
+ *
+ * @param srcFilePath The path to the source file that needs to be encrypted.
+ * @param destFilePath The path where the encrypted file will be saved.
+ * @param passphrase The passphrase used for encryption.
+ * @param iteration_count The number of iterations to use for PBKDF2.
+ * @returns Resolves when the file is successfully encrypted.
+ * @throws {FailToEncryptFileError} If the source file does not exist or if
+ *         OpenSSL returns an error during encryption.
+ * @throws {FailToDecryptFileError} If an unknown error occurs during
+ *         encryption.
+ */
+export declare function encryptFile(srcFilePath: string, destFilePath: string, passphrase: string, iteration_count: number): Promise<void>;
+/**
+ * Decrypts a file using OpenSSL with AES-256-CBC and PBKDF2 key derivation.
+ *
+ * This function checks whether the encrypted file exists, constructs an OpenSSL
+ * decryption command, ensures the destination directory exists, and then
+ * executes the decryption command.
+ *
+ * @param srcFilePath The path where the decrypted file will be saved.
+ * @param destFilePath The path to the encrypted source file.
+ * @param passphrase The passphrase used for decryption.
+ * @param iteration_count The number of iterations used for PBKDF2.
+ * @returns Resolves when the file is successfully decrypted.
+ * @throws {FailToDecryptFileError} If the encrypted file does not exist or if
+ *         OpenSSL returns an error during decryption.
+ * @throws {FailToDecryptFileError} If an unknown error occurs during
+ *         decryption.
+ */
+export declare function decryptFile(srcFilePath: string, destFilePath: string, passphrase: string, iteration_count: number): Promise<void>;
+/**
+ * Encrypts multiple files using OpenSSL with AES-256-CBC and PBKDF2 key
+ * derivation.
+ *
+ * For each source file path provided, this function constructs the destination
+ * file path by appending `.enc`, then calls `encryptFile` and logs the
+ * operation.
+ *
+ * @param srcFilePaths An array of file paths to be encrypted.
+ * @param destDir The directory where the encrypted files will be saved.
+ * @param passphrase The passphrase used for encryption.
+ * @param iteration_count The number of iterations to use for PBKDF2.
+ * @returns Resolves when all files are successfully encrypted.
+ * @throws {FailToEncryptFileError} If any file fails to encrypt.
+ */
+export declare function encryptFiles(srcFilePaths: string[], destDir: string, passphrase: string, iteration_count: number): Promise<void>;
+/**
+ * Decrypts multiple files using OpenSSL with AES-256-CBC and PBKDF2 key
+ * derivation.
+ *
+ * For each source file path provided, this function assumes the corresponding
+ * encrypted file has the `.enc` extension and calls `decryptFile`, logging the
+ * operation.
+ *
+ * @param srcFilePaths An array of original file paths that were encrypted.
+ * @param destDir The directory containing the encrypted files.
+ * @param passphrase The passphrase used for decryption.
+ * @param iteration_count The number of iterations used for PBKDF2.
+ * @returns Resolves when all files are successfully decrypted.
+ * @throws {FailToDecryptFileError} If any file fails to decrypt.
+ */
+export declare function decryptFiles(srcFilePaths: string[], destDir: string, passphrase: string, iteration_count: number): Promise<void>;