@chamesh2020/keystone 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chames
+
+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

@@ -0,0 +1,204 @@
+# @chamesh2020/keystone
+
+A Zero-Knowledge Secret Vault CLI tool and SDK built with TypeScript.
+
+Keystone allows you to store and retrieve application secrets securely. It employs **hybrid encryption (AES-256-GCM + RSA-OAEP envelope)** to encrypt all secrets locally before transmitting them to the server. The server only sees encrypted ciphertext, ensuring that your raw secrets and private keys are never exposed.
+
+## Features
+
+- **Zero-Knowledge Architecture:** Cryptographic keys are generated and stored locally. Encryption and decryption occur entirely client-side.
+- **Hybrid Cryptography:** Combines the speed and size-limitless flexibility of AES-256-GCM with the secure key distribution of RSA-OAEP.
+- **Secure by Default:** Generated credentials files are locked down with `0o600` permissions (read/write only by owner) and automatically added to `.gitignore` and `.npmignore`.
+- **Dotenv Integration:** Automatically loads your `.env` files and resolves placeholders (e.g., `LOAD_FROM_KEYSTONE`) dynamically from the Keystone vault at runtime.
+- **Programmatic & CLI Access:** Fully-featured CLI tool and Node.js SDK.
+
+---
+
+## Installation
+
+Install globally via npm:
+
+```bash
+npm install -g @chamesh2020/keystone
+```
+
+Or run it directly without installing using `npx`:
+
+```bash
+npx @chamesh2020/keystone --help
+```
+
+---
+
+## CLI Usage
+
+### 1. Initialize a Project
+
+Initialize your project, generate local cryptographic keys, and register the project on the server:
+
+```bash
+keystone init <projectId>
+```
+
+- **What it does:**
+  - Generates an Ed25519 key pair for authenticating requests and an RSA-OAEP key pair for encryption/decryption.
+  - Stores the keys locally at `.keystone/project-credentials.json` with secure file permissions (`chmod 600`).
+  - Registers your public keys on the Keystone server.
+  - Automatically appends `.keystone` to your `.gitignore` and `.npmignore` files to prevent committing credentials.
+
+### 2. Store a Secret
+
+Store an encrypted secret on the server:
+
+```bash
+keystone set <secretName> [secretValue]
+```
+
+_Alias: `keystone store`, `keystone add`_
+
+- If `secretValue` is omitted and the terminal is interactive (TTY), you will be securely prompted to type it.
+- If the terminal is non-interactive, it will read from `stdin`. This allows piping values:
+  ```bash
+  cat password.txt | keystone set MY_DB_PASSWORD
+  ```
+- **Automatic `.env` Update:** Storing a secret automatically appends or updates the key-value pair in your local `.env` file (or equivalent, e.g., `.env.local`, `.env.development`, `.env.dev`) with the `LOAD_FROM_KEYSTONE` placeholder, ensuring it is ready for programmatic resolution.
+
+### 3. Retrieve a Secret
+
+Retrieve and decrypt a secret:
+
+```bash
+keystone get <secretName>
+```
+
+_Alias: `keystone retrieve`_
+
+- Decrypts the secret locally using your RSA private key.
+- Prints **only** the raw decrypted secret value to `stdout` (with all logging/errors sent to `stderr`), allowing for clean pipes:
+  ```bash
+  export DB_PASSWORD=$(keystone get MY_DB_PASSWORD)
+  ```
+
+### Global Options
+
+- `-c, --credentials <path>`: Path to credentials file (defaults to `.keystone/project-credentials.json` or `KEYSTONE_CREDENTIALS` env variable).
+- `-u, --url <url>`: Base URL of the Keystone server (defaults to `https://keystone.chames.dev` or `KEYSTONE_URL` env variable).
+- `-h, --help`: Show help text.
+- `-v, --version`: Show version number.
+
+---
+
+## Programmatic SDK Integration
+
+You can integrate Keystone into your Node.js/TypeScript applications to load secrets dynamically at runtime.
+
+### Dynamic `.env` Integration
+
+Add placeholders to your `.env` (or `.env.local`, `.env.production`) file:
+
+```env
+# .env
+PORT=3000
+DATABASE_URL=LOAD_FROM_KEYSTONE
+API_CLIENT_SECRET=LOAD_FROM_KEYSTONE
+```
+
+Then, call `loadSecrets` early in your application's entrypoint:
+
+```typescript
+import { loadSecrets } from "@chamesh2020/keystone";
+
+async function bootstrap() {
+  // 1. Reads standard .env files
+  // 2. Fetches & decrypts marked secrets from the Keystone vault
+  // 3. Injects them directly into process.env
+  await loadSecrets();
+
+  console.log(process.env.DATABASE_URL); // => "postgres://..."
+}
+
+bootstrap();
+```
+
+`loadSecrets` (and its snake_case alias `load_secrets`) accepts an optional options object:
+
+```typescript
+await loadSecrets({
+  credentialsPath: "./custom/path/credentials.json",
+  baseUrl: "https://custom-keystone-server.com",
+  cwd: process.cwd(),
+});
+```
+
+### Low-Level Cryptography & API Client
+
+For custom workflows, you can import the cryptographic and network clients directly:
+
+```typescript
+import {
+  generateProjectKeys,
+  encryptSecret,
+  decryptSecret,
+  initProject,
+  storeSecret,
+  retrieveSecret,
+} from "@chamesh2020/keystone";
+
+// Generate keys programmatically
+const keys = await generateProjectKeys("my-custom-project");
+
+// Encrypt locally
+const ciphertext = await encryptSecret(
+  "my-secret-payload",
+  keys.encryption.publicJwk,
+);
+
+// Decrypt locally
+const decrypted = await decryptSecret(ciphertext, keys.encryption.privateJwk);
+```
+
+---
+
+## Configuration Settings
+
+You can configure Keystone using the following environment variables:
+
+| Environment Variable   | Description                                   | Default                              |
+| ---------------------- | --------------------------------------------- | ------------------------------------ |
+| `KEYSTONE_URL`         | Base URL of the backend Keystone API          | `https://keystone.chames.dev`        |
+| `KEYSTONE_CREDENTIALS` | Path to the JSON file containing project keys | `.keystone/project-credentials.json` |
+
+---
+
+## Development & Testing
+
+To set up Keystone locally for development:
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run in watch mode
+npm run dev
+
+# Run Vitest test suite
+npm test
+
+# Format code
+npm run format
+
+# Run linter
+npm run lint
+
+# Run TypeScript typechecks
+npm run typecheck
+```
+
+---
+
+## License
+
+MIT