secnote

Password-based text and note-file encryption for Node.js.

The package is both:

• a library exporting encrypt() and decrypt();
• a CLI for encrypting and decrypting one or many note files.

Install

npm install secnote

Library

import { encrypt, decrypt } from "secnote";

const encrypted = await encrypt("secret text", "password");
const plaintext = await decrypt(encrypted, "password");

Programmatic API

The library API works entirely with UTF-8 strings in memory. It does not read or write files, prompt for passwords, inspect CLI password environment variables, manage the CLI passHash file, expand globs, or terminate the calling Node.js process. Those behaviors are isolated to the secnote CLI.

This makes the package suitable for virtual editors, VS Code extensions, databases, HTTP services, or any other caller that already owns the input/output lifecycle:

import { encrypt, decrypt } from "secnote";

const sourceText = "const value = 123;";
const password = "example-password";

const encryptedText = await encrypt(sourceText, password);
const restoredText = await decrypt(encryptedText, password);

The programmatic API is intentionally small:

export function encrypt(text: string, password: string): Promise<string>;
export function decrypt(encryptedText: string, password: string): Promise<string>;

encrypt() writes the current SecNote format using:

• AES-256-CBC;
• scrypt password-based key derivation;
• a random 16-byte salt per encryption;
• a random 16-byte IV per encryption.

decrypt() keeps backward compatibility with all known SecNote formats:

1. current format: independent random hexKeySalt and hexCipherIv;
2. legacy WebSecNote format: random iv with fixed scrypt salt "salt";
3. oldest legacy format: the same iv used as both scrypt salt and AES IV.

Encryption only writes the current format. Legacy formats are decrypt-only.

CLI

The CLI follows the same command shape as secbyte:

[SECNOTEPASS=yourPassword] secnote encrypt|decrypt [--delete] [--overwrite] [--password <password>] <inputPattern...>

Execution mode aliases:

enc      encrypt
dec      decrypt

Encrypt one file:

secnote encrypt note.txt

This creates note.txt.secnote.

Decrypt one file:

secnote decrypt note.txt.secnote

This creates note.txt.

Process glob patterns:

secnote encrypt '**/*.txt'
secnote decrypt '**/*.secnote'

Multiple paths and patterns can be supplied:

secnote encrypt notes/*.txt docs/**/*.md

Quote recursive glob patterns when you want SecNote, rather than the shell, to expand them.

Password sources

Password precedence is:

1. -p, --password <password>;
2. SECNOTEPASS;
3. hidden interactive prompt.

Examples:

SECNOTEPASS="$PASSWORD" secnote encrypt note.txt
secnote encrypt --password "$PASSWORD" note.txt

Modern CLI usage stores a short password confirmation hash in:

~/.secnote.passhash

On first use, SecNote shows the passHash and asks you to type it back. On later runs it rejects a password whose passHash does not match the stored value.

File options

Delete each source file only after its output was successfully written:

secnote encrypt --delete '**/*.txt'

Overwrite existing destination files:

secnote encrypt --overwrite note.txt

During encryption, files already ending in .secnote are excluded. During decryption, inputs not ending in .secnote are excluded.

Legacy CLI compatibility

The historical command remains supported:

secnote note.txt password
secnote note.txt.secnote password

This legacy form infers encrypt/decrypt from the .secnote extension and intentionally preserves its original behavior. New scripts should use the explicit encrypt|decrypt interface.

Compatibility policy

Backward decryption compatibility is intentional. Historical encrypted notes should remain decryptable even though new encryption no longer writes the legacy formats.