@typinghare/trick 2.0.1 → 2.1.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 James Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,8 +1,21 @@
 # [Trick](https://github.com/typinghare/trick)
 
-# Install
+**Trick** is a CLI tool that helps you **safely encrypt sensitive files** (such as `.env`, API keys, or credentials) so they can be stored in Git repositories and easily restored on other machines or servers.
 
-```shell
+It uses **OpenSSL (AES-256-CBC + PBKDF2)** under the hood and keeps encryption keys **outside your repository**.
+
+## Features
+
+* 🔐 Encrypt and decrypt sensitive files with strong encryption
+* 🎯 Group files into **targets**
+* 📦 Store encrypted files under a dedicated `.trick/` directory
+* 🗝️ Keep passphrases outside your repo (per-target, permission-protected)
+* 🔁 Works across machines and servers
+* ⚙️ Fully configurable, project-aware
+
+## Installation
+
+```bash
 # npm
 npm install -g @typinghare/trick
 
@@ -13,81 +26,202 @@ pnpm add -g @typinghare/trick
 yarn add -g @typinghare/trick
 ```
 
+> **Requirements**
+>
+> * Node.js ≥ 18
+> * `openssl` available in your system PATH
+
 ## 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!
+Sensitive files are usually added to `.gitignore` to avoid accidental leaks.
+But that means:
+
+* You must manually copy them to every new machine
+* They’re easy to lose
+* They don’t version well
+
+**Trick encrypts those files**, allowing you to commit the encrypted versions safely, while keeping passphrases out of Git entirely.
+
 
-**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
+## Getting Started
 
-Set up the **target** with the files needed to be encrypted:
+### 1. Initialize Trick
+
+Run this inside your project:
 
 ```bash
-# This will create a trick.config.json in the current working directory
-# trick add <target> [files...]
-$ trick add MyTargetName .env api_key.conf
+trick init
+```
+
+This creates a `trick.config.json` in your project root.
+
 
-# Display the list of target names and the files bound
-$ trick list
+
+### 2. Add Files to a Target
+
+A **target** is a named group of files to encrypt together.
+
+```bash
+trick add MyTarget .env api_key.conf
 ```
 
-Create a `passphrase.json` file under `~/.config` with the following content:
+List all targets:
 
-```json
-{
-    "MyTargetName": "Reg5eGPXWdmeW0i08uaygBlfbXP+tJlnu7z551Qt568="
-}
+```bash
+trick list
 ```
 
-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:
+
+### 3. Set a Passphrase for the Target
+
+Each target has its **own passphrase file** stored locally (not in Git).
 
 ```bash
-$ trick encrypt MyTargetName
+trick set-passphrase MyTarget
 ```
 
-You will see the following output:
+This creates a file at:
 
-```text
-[ENCRYPTED] .env -> .trick/encrypted/.env.enc
-[ENCRYPTED] api_key.conf -> .trick/encrypted/api_key.conf.enc
 ```
+~/.config/trick/passphrases/MyTarget
+```
+
+* File permissions are set to `600`
+* You must manually edit this file and paste your passphrase
+* The file content is read as plain text (trimmed)
 
-Encrypted files are all saved to `.trick`. On the server, set the the `passphrase.json` in the same way, and execute:
+> ⚠️ **Important**
+> Back up your passphrase files. Losing them means losing access to your encrypted data.
+
+
+
+### 4. Encrypt Files
 
 ```bash
-$ trick decrypt MyTargetName
+trick encrypt MyTarget
+```
+
+Encrypted files are written to:
+
+```
+.trick/<original-path>.enc
 ```
 
-And you will see that the files are restored:
+Example output:
 
-```text
-[DECRYPTED] .trick/encrypted/.env.enc -> .env
-[DECRYPTED] .trick/encrypted/api_key.conf.enc -> api_key.conf
+```
+🟩 Encrypted: .env -> .trick/.env.enc
+🟩 Encrypted: api_key.conf -> .trick/api_key.conf.enc
 ```
 
-> [!IMPORTANT]
-> The `passphrase.json` collects all the passphrases you have. Please back it up in multiple devices every time you edit it!
+You can now commit the `.trick/` directory safely.
 
-## More Features
 
-### Default Target Name
 
-You can set the default target name so that you don't need to input it every time:
+### 5. Decrypt Files (on another machine or server)
+
+1. Copy or recreate the passphrase file:
+
+   ```
+   ~/.config/trick/passphrases/MyTarget
+   ```
+2. Run:
+
+   ```bash
+   trick decrypt MyTarget
+   ```
+
+Files are restored to their original locations.
+
+
+
+## Default Targets
+
+You can mark targets as **default**, so you don’t need to specify them every time.
 
 ```bash
-# Set the default target name
-$ trick set-default MyTargetName
+trick add-default MyTarget
+```
 
-# Display the default target name
-$ trick get-default
+List default targets:
+
+```bash
+trick list-defaults
 ```
 
-Now you can encrypt and decrypt more easily:
+Now you can simply run:
 
 ```bash
-$ trick encrypt
-$ trick decrypt
+trick encrypt
+trick decrypt
 ```
+
+
+
+## Configuration
+
+### `trick.config.json`
+
+Example:
+
+```json
+{
+  "targets": {
+    "MyTarget": {
+      "files": [".env", "api_key.conf"]
+    }
+  },
+  "trickRootDirectory": ".trick",
+  "passphraseDirectory": "~/.config/trick/passphrases",
+  "defaultTargetNames": ["MyTarget"],
+  "encryption": {
+    "iterationCount": 100000
+  }
+}
+```
+
+### Key Fields
+
+| Field                       | Description                           |
+| ------------------------ | ------------------------------------- |
+| `targets`                   | Mapping of target names to file lists |
+| `trickRootDirectory`        | Where encrypted files are stored      |
+| `passphraseDirectory`       | Where passphrase files live           |
+| `defaultTargetNames`        | Targets used when none specified      |
+| `encryption.iterationCount` | PBKDF2 iteration count                |
+
+
+
+## Commands Overview
+
+| Command                            | Description                |
+| ---------------------------------- | -------------------------- |
+| `trick init`                       | Initialize configuration   |
+| `trick config`                     | Print current config       |
+| `trick add <target> [files...]`    | Add files to a target      |
+| `trick remove <target> [files...]` | Remove files from a target |
+| `trick remove <target> --target`   | Remove a target            |
+| `trick list`                       | List targets and files     |
+| `trick set-passphrase <target>`    | Create passphrase file     |
+| `trick encrypt [targets...]`       | Encrypt files              |
+| `trick decrypt [targets...]`       | Decrypt files              |
+| `trick add-default [targets...]`   | Add default targets        |
+| `trick list-defaults`              | Show default targets       |
+
+## Security Notes
+
+* Encryption uses:
+
+  * **AES-256-CBC**
+  * **PBKDF2** with configurable iteration count
+* Passphrases:
+
+  * Never stored in Git
+  * Stored as local files with strict permissions
+* Losing passphrases = losing access to encrypted files
+
+## License
+
+MIT

package/dist/app.js

@@ -1,27 +1,62 @@
 import { Command } from 'commander';
-import { getTargetFromConfig, updateConfig } from './config.js';
+import { CONFIG_FILE_NAME, getRootDirectory, 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';
+import { getPassphrase, getPassphraseDirectory } from './passphrase.js';
+import { resolveError } from './error.js';
+import path from 'path';
+import { colorFilePath, colorTargetName } from './color.js';
+import { success, warning } from './console.js';
 const program = new Command();
-program.version('2.0.1');
+program.version('2.1.0');
 program.description('Save credential files to remote safely and easily.');
+program
+    .command('config')
+    .description('Display the current configuration.')
+    .action(function () {
+    updateConfig((config) => {
+        console.log(JSON.stringify(config, null, 2));
+    });
+});
+program
+    .command('init')
+    .description('Initialize the configuration file.')
+    .option('-r, --root', 'Create the configuration file in the root directory.', false)
+    .action(function (options) {
+    const configFilePath = options.root
+        ? path.join(getRootDirectory(), CONFIG_FILE_NAME)
+        : path.join(process.cwd(), CONFIG_FILE_NAME);
+    if (fsExtra.existsSync(configFilePath)) {
+        console.log(warning(`Configuration file already exists: ${configFilePath}`));
+        return;
+    }
+    else {
+        updateConfig(() => true, options.root);
+        console.log(success(`Initialized configuration file: ${configFilePath}`));
+    }
+});
 program
     .command('add')
     .description('Add files to a target.')
-    .argument('<target>', 'The name of the target')
-    .argument('[files...]', 'Files that are encrypted')
-    .action(async (targetName, files) => {
-    await updateConfig((config) => {
-        try {
-            const target = getTargetFromConfig(config, targetName);
-            target.files.push(...files);
-        }
-        catch (err) {
-            config.default_target_name = targetName;
+    .argument('<target>', 'The name of the target to add to')
+    .argument('[files...]', 'Files that are added to the target')
+    .action(function (targetName, files) {
+    updateConfig((config) => {
+        const target = config.targets[targetName];
+        if (!target) {
             config.targets[targetName] = { files };
+            console.log(success(`Added files to target: ${targetName}`));
+        }
+        else {
+            for (const file of files) {
+                if (target.files.includes(file)) {
+                    console.log(warning(`File already exists in the target: ${file}`));
+                }
+                else {
+                    target.files.push(file);
+                    console.log(success(`Added file to target: ${file}`));
+                }
+            }
         }
         return true;
     });
@@ -29,13 +64,13 @@ program
 program
     .command('remove')
     .description('Remove files from a target.')
-    .argument('<target>', 'The name of the target')
-    .argument('[files...]', 'Files to remove')
+    .argument('<target>', 'The name of the target to remove from')
+    .argument('[files...]', 'Files to remove from the target')
     .option('-t, --target', 'Remove the target instead.')
-    .action(async (targetName, files, options) => {
+    .action(function (targetName, files, options) {
     if (options.target) {
         // Remove the target
-        return await updateConfig((config) => {
+        return updateConfig((config) => {
             getTargetFromConfig(config, targetName);
             delete config.targets[targetName];
             console.log(`[SUCCESS] Removed target: ${targetName}`);
@@ -43,14 +78,14 @@ program
         });
     }
     // Remove files from the target
-    await updateConfig((config) => {
+    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}`);
+                console.log(success(`Removed file: ${file}`));
             }
             else {
                 remainingFiles.push(file);
@@ -59,79 +94,136 @@ program
         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}`);
+            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 targetName;
-}
 program
     .command('encrypt')
     .description('Encrypt the credential files.')
-    .argument('[target]', 'The name of the target', null)
-    .action(async (targetNameOrNull) => {
-    await updateConfig((config) => {
-        const targetName = getTargetName(targetNameOrNull, config.default_target_name);
-        const target = getTargetFromConfig(config, targetName);
-        const passphrase = getPassphrase(config, targetName);
-        const srcFilePaths = target.files;
-        fsExtra.ensureDir(config.root_directory);
-        encryptFiles(srcFilePaths, config.root_directory, passphrase, config.encryption.iteration_count);
+    .argument('[targetNames...]', 'The names of targets')
+    .action(function (targetNames) {
+    updateConfig((config) => {
+        if (targetNames.length === 0) {
+            targetNames.push(...config.defaultTargetNames);
+        }
+        if (targetNames.length === 0) {
+            console.log(warning('No target names specified and no default targets set.'));
+            return;
+        }
+        const rootDirectory = getRootDirectory();
+        const trickRootDirectory = path.resolve(rootDirectory, config.trickRootDirectory);
+        for (const targetName of targetNames) {
+            const target = getTargetFromConfig(config, targetName);
+            const passphrase = getPassphrase(config, targetName);
+            const srcFilePaths = target.files;
+            fsExtra.ensureDir(trickRootDirectory);
+            encryptFiles(srcFilePaths, trickRootDirectory, passphrase, config.encryption.iterationCount);
+        }
     });
 });
 program
     .command('decrypt')
     .description('Decrypt the credential files.')
-    .argument('[target]', 'The name of the target', null)
-    .action(async (targetNameOrNull) => {
-    await updateConfig((config) => {
-        const targetName = getTargetName(targetNameOrNull, config.default_target_name);
-        const target = getTargetFromConfig(config, targetName);
-        const passphrase = getPassphrase(config, targetName);
-        const srcFilePaths = target.files;
-        fsExtra.ensureDir(config.root_directory);
-        decryptFiles(srcFilePaths, config.root_directory, passphrase, config.encryption.iteration_count);
+    .argument('[targetNames...]', 'The names of the targets')
+    .action(function (targetNames) {
+    updateConfig((config) => {
+        if (targetNames.length === 0) {
+            targetNames.push(...config.defaultTargetNames);
+        }
+        if (targetNames.length === 0) {
+            console.log(warning('No target names specified and no default targets set.'));
+            return;
+        }
+        const rootDirectory = getRootDirectory();
+        const trickRootDirectory = path.resolve(rootDirectory, config.trickRootDirectory);
+        for (const targetName of targetNames) {
+            const target = getTargetFromConfig(config, targetName);
+            const passphrase = getPassphrase(config, targetName);
+            const srcFilePaths = target.files;
+            fsExtra.ensureDir(trickRootDirectory);
+            decryptFiles(srcFilePaths, trickRootDirectory, passphrase, config.encryption.iterationCount);
+        }
     });
 });
 program
-    .command('set-default')
-    .description('Set the default target name.')
-    .argument('<target>', 'The name of the target to set')
-    .action(async (targetName) => {
-    await updateConfig((config) => {
-        config.default_target_name = targetName;
-        return true;
+    .command('add-default')
+    .description('Add default target names.')
+    .argument('[targetNames...]', 'The names of targets to add')
+    .action(function (targetNames) {
+    updateConfig((config) => {
+        let addedAny = false;
+        for (const targetName of targetNames) {
+            if (!config.targets[targetName]) {
+                console.log(warning(`Target not found: ${targetName}`));
+                continue;
+            }
+            if (config.defaultTargetNames.includes(targetName)) {
+                console.log(warning(`Target name already in default list: ${targetName}`));
+                continue;
+            }
+            config.defaultTargetNames.push(targetName);
+            console.log(success(`Added default target name: ${targetName}`));
+            addedAny = true;
+        }
+        return addedAny;
     });
 });
 program
-    .command('get-default')
-    .description('Get the default target name.')
-    .action(async () => {
-    await updateConfig((config) => {
-        console.log(config.default_target_name);
+    .command('list-defaults')
+    .description('Display  the default target name.')
+    .action(function () {
+    updateConfig((config) => {
+        for (const targetName of config.defaultTargetNames) {
+            console.log(colorTargetName(targetName));
+        }
     });
 });
 program
     .command('list')
     .description('Display a list of targets.')
-    .action(async () => {
-    await updateConfig((config) => {
+    .action(function () {
+    updateConfig((config) => {
         for (const [targetName, target] of Object.entries(config.targets)) {
-            console.log(chalk.cyan(targetName));
+            console.log(colorTargetName(targetName));
             for (const file of target.files) {
-                console.log('    ' + chalk.yellow(file));
+                console.log('    ' + colorFilePath(file));
             }
         }
     });
 });
-program.parse();
+program
+    .command('set-passphrase')
+    .description('Set passphrase for a target.')
+    .argument('<target>', 'The name of the target to set passphrase for')
+    .action(function (targetName) {
+    updateConfig((config) => {
+        const passphraseDirectory = getPassphraseDirectory(config);
+        if (!fsExtra.existsSync(passphraseDirectory)) {
+            fsExtra.ensureDirSync(passphraseDirectory);
+            console.log(success(`Created passphrase directory: ${passphraseDirectory}`));
+        }
+        const passphraseFile = path.join(passphraseDirectory, targetName);
+        if (!fsExtra.existsSync(passphraseFile)) {
+            fsExtra.createFileSync(passphraseFile);
+            fsExtra.chmodSync(passphraseFile, 0o600);
+            console.log(success(`Created passphrase file: ${passphraseFile}`));
+            console.log(success(`You have to edit the file to set the passphrase.`));
+        }
+        else {
+            console.log(warning(`Passphrase file already exists: ${passphraseFile}`));
+        }
+    });
+});
+try {
+    program.parse();
+}
+catch (err) {
+    resolveError(err);
+    process.exit(1);
+}
 process.on('uncaughtException', (err) => {
-    resolve_error(err);
+    resolveError(err);
     process.exit(1);
 });

package/dist/color.d.ts

@@ -0,0 +1,2 @@
+export declare function colorTargetName(targetName: string): string;
+export declare function colorFilePath(filePath: string): string;

package/dist/color.js

@@ -0,0 +1,7 @@
+import chalk from 'chalk';
+export function colorTargetName(targetName) {
+    return chalk.cyan(targetName);
+}
+export function colorFilePath(filePath) {
+    return chalk.yellow(filePath);
+}