@trap_stevo/aegis

🛡️ @trap_stevo/aegis

The Shield of Secrets.
An encrypted, attestable, process-safe credentials vault with bootstrap, admin passkeys, developer enrollment, and enum-based storage — designed to safeguard credentials while staying effortless to use across machines, CI/CD pipelines, and runtime apps.

🚀 Features

• 🧱 Machine-Bound Encryption – Secrets are sealed to your machine’s identity
• 🧩 Bootstrap & Admin Flow – Securely initialize, bootstrap, and manage passkeys
• 👥 Developer Enrollment – Invite and register developers with time-limited codes
• 🔑 Grant System – Enforce which scripts, tokens, or modules can read secrets
• ⚙️ Enum-Based Storage – Portable secure paths (PROJECT, USER, SYSTEM, TEMP)
• 🔒 Vault API & Client API – Use high-level or low-level interfaces as needed
• 🧰 CLI Ready – Initialize, bootstrap, set, or read secrets interactively
• 💨 process.env Integration – Optional runtime injector for dynamic secret binding

⚙️ System Requirements

Requirement	Version
Node.js	≥ 18.x
npm	≥ 9.x
OS	Windows, macOS, Linux

Entry Points

const { createAegis, createAegisEnv, inject } = require("@trap_stevo/aegis");

🧠 Core Concepts

Layer	Description
Aegis API	Full administrative access (bootstrap, manage, rotate, invite)
Aegis Env API	Lightweight, read-only runtime access for apps
Inject API	Auto-injects vault secrets into process.env dynamically

⚙️ Configuration

createAegis(options)

Option	Type	Default	Description
storagePath	string	required	Base directory or enum (PROJECT, USER, SYSTEM, TEMP)
namespace	string	"vault"	Folder name under storage path
offset	string	"machine-v1"	Salted key derivation offset
lockprint	string	null	Custom fingerprint override
lockprintOptions	object	{}	Fingerprint file and size options
shardCount	number	32	Internal vault shard count

createAegisEnv(options)

Option	Type	Default	Description
storagePath	string	required	Same enum or path as createVault
namespace	string	"vault"	Name of vault directory
offset	string	"machine-v1"	Salt key for machine binding
lockprint	string	null	Optional fingerprint override
lockprintOptions	object	{}	Lockprint configuration
AEGIS_GRANTS_MODE	string	"strict"	Env override for dev mode ("permissive")

inject(options)

Option	Type	Default	Description
storagePath	string	required	Vault root path or enum
namespace	string	"vault"	Vault directory
offset	string	"machine-v1"	Key offset
lockprint	string	null	Custom fingerprint
preload	boolean	true	Preload all secrets to process.env
cacheSeconds	number	0	Cache TTL for injected secrets
enforceNoPlainOverwrite	boolean	true	Prevent overwriting existing env vars

🧰 API Specifications

🔐 Aegis Methods

Method	Description	Async
init()	Initialize the vault and create bootstrap token	✅
bootstrapAdmin(adminID, token, passphrase)	Secure the vault and establish admin credentials	✅
addDeveloper(devID, tempPass, adminID, adminPass)	Create a new developer entry	✅
createInvite(devID, adminID, adminPass, opts)	Generate one-time invite codes	✅
addDevWithInvite(devID, inviteCode, adminID, adminPass)	Add developer directly using an invite	✅
claimInvite(devID, code, newPassphrase)	Developer claims an invite and sets password	✅
changePassphrase(devID, oldPass, newPass)	Change developer password	✅
removeDeveloper(devID, adminID, adminPass)	Remove developer access	✅
setSecret(name, value, adminID, adminPass)	Store a secret securely	✅
importSecrets(object, adminID, adminPass, opts)	Bulk import secrets	✅
getSecret(name, opts)	Retrieve a secret by key	✅
listNames()	List all stored secret names	✅
deleteSecret(name, adminID, adminPass)	Delete a secret	✅
addGrant(appID, grant, adminID, adminPass)	Add a new grant rule	✅
removeGrant(appID, adminID, adminPass)	Remove a grant rule	✅

🧩 Aegis Env Methods

Method	Description	Async
get(name, { appID, appCWD })	Retrieve secret (grant enforced)	✅
getSync(name, { appID, appCWD })	Retrieve secret synchronously	❌

Supported Grant Types

• file_hash – pin to file SHA-256 hash
• token – signed token file verification
• plugin – external module-based verifier

🌐 Aegis Inject API

Method	Description	Async
injectKey(name)	Inject one secret into process.env	✅
refresh()	Clear cache and reload all injected values	✅
list()	List all injected secret names	✅

🔑 Grant Types

Type	Description	Ideal Use
file_hash	Locks access to a specific file checksum	CLI or local scripts
token	Validates signed token file (ed25519)	CI/CD, build pipelines
plugin	Loads verifier module dynamically	Custom policies or SDKs

🧩 Example Grant

await vault.addGrant("demo-app", {
     type : "file_hash",
     path : "./aegisClientDemo.js",
     sha256 : "abc123..."
}, "admin:local", "admin-pass");

💻 CLI Command Reference

Command	Description
aegis init	Initialize a new vault and print bootstrap token
aegis bootstrap-admin <adminID>	Secure vault and create admin credentials
aegis add-dev <devID> <adminID>	Register a new developer
aegis create-invite <devID> <adminID>	Create a one-time invite code
aegis claim-invite <devID> <code>	Developer claims an invite and sets password
aegis set <key> <value> <adminID>	Store a new secret
aegis get <key>	Read a secret value
aegis list	List all stored secret names
aegis delete <key>	Delete a secret
aegis add-grant <appID>	Add a file_hash, token, or plugin grant
aegis remove-grant <appID>	Remove an existing grant
aegis info	Display vault configuration summary

🧪 Example CLI Workflow

npm run start-aegis-init  
npm run start-aegis-set -- --grant  
npm run start-aegis-client

Re-run npm run start-aegis-set -- --grant whenever your file hash changes to refresh the grant.

📦 Installation

npm install @trap_stevo/aegis

🏁 Quick Start

Initialize and Bootstrap

npx aegis init  
npx aegis bootstrap-admin <adminDevID>

Add Developer

npx aegis add-dev <devID> <adminDevID>

Set Secret

npx aegis set API_KEY my-secret-value <adminDevID>

Read Secret Programmatically

const { createAegisEnv } = require("@trap_stevo/aegis");

(async () => {
     const env = createAegisEnv({ storagePath : "PROJECT", namespace : "vault" });
     
     const key = await env.get("API_KEY", { appID : "demo-app" });
     
     console.log("API Key:", key);
})();

🧭Initializing Aegis via Code

Initializes the vault and bootstraps an admin account.

"use strict";
const { createAegis } = require("@trap_stevo/aegis");
const path = require("path");

const STORAGE = path.resolve(__dirname, ".aegis_store");
const NAMESPACE = "vault";
const ADMIN_ID = process.env.AEGIS_ADMIN_ID  || "admin:local";
const ADMIN_PASS= process.env.AEGIS_ADMIN_PASS|| "aegis";

(async () => {
     const vault = createAegis({ storagePath : STORAGE, namespace : NAMESPACE });
     const token = vault.init();
     console.log("[init] bootstrap token:", token);
     vault.bootstrapAdmin(ADMIN_ID, token, ADMIN_PASS);
     console.log("[init] admin bootstrapped:", ADMIN_ID);
     console.log(`[init] vault ready at ${path.join(STORAGE, NAMESPACE)}`);
})();

🧱 Setting Secrets via Code

Sets secrets into the vault and optionally registers a grant (using --grant).

"use strict";
const { createAegis } = require("@trap_stevo/aegis");
const crypto = require("crypto");
const path = require("path");
const fs = require("fs");

const STORAGE = path.resolve(__dirname, ".aegis_store");
const NAMESPACE = "vault";
const ADMIN_ID = process.env.AEGIS_ADMIN_ID || "admin:local";
const ADMIN_PASS = process.env.AEGIS_ADMIN_PASS || "aegis";
const ADD_GRANT = process.argv.includes("--grant") || process.env.AEGIS_ADD_GRANT === "1";
const APP_ID = process.env.AEGIS_APP_ID || "demo-app";
const READER_REL = process.env.AEGIS_READER_REL || "./aegisClientDemo.js";

function sha256FileHex(p)
{
     const h = crypto.createHash("sha256");
     h.update(fs.readFileSync(p));
     return h.digest("hex");
};

(async () => {
     const vault = createAegis({ storagePath: STORAGE, namespace: NAMESPACE });
     await vault.setSecret("SERVICE_API_KEY", "sk_live_123", ADMIN_ID, ADMIN_PASS);
     await vault.setSecret("DB_PASSWORD", "p@ssw0rd!", ADMIN_ID, ADMIN_PASS);
     await vault.importSecrets({ MAILGUN_KEY: "mg_abc", S3_SECRET: "s3_xyz" }, ADMIN_ID, ADMIN_PASS, { overwrite: false });
     console.log("[set] secrets written.");
     if (ADD_GRANT)
     {
          const fullReader = path.resolve(__dirname, READER_REL);
          const readerHash = sha256FileHex(fullReader);
          await vault.addGrant(
               APP_ID,
               { type : "file_hash", path : READER_REL, sha256 : readerHash },
               ADMIN_ID,
               ADMIN_PASS
          );
          console.log(`[grant] Added file_hash grant for appID=${APP_ID}`);
          console.log(`[grant] path=${READER_REL}`);
          console.log(`[grant] sha256=${readerHash}`);
          console.log("[grant] Vault now in STRICT mode (since at least one grant exists).");
     }
})();

📖 Accessing Secrets Directly through Aegis

Reads secrets directly from the vault (admin access).

"use strict";
const { createAegis } = require("@trap_stevo/aegis");
const path = require("path");

const STORAGE = path.resolve(__dirname, ".aegis_store");
const NAMESPACE = "vault";
const ADMIN_ID = process.env.AEGIS_ADMIN_ID || "admin:local";
const ADMIN_PASS = process.env.AEGIS_ADMIN_PASS || "aegis";

(async () => {
     const vault = createAegis({ storagePath: STORAGE, namespace: NAMESPACE });
     try
     {
          const apiKey = await vault.getSecret("SERVICE_API_KEY", { devID : ADMIN_ID, passphrase : ADMIN_PASS });
          const dbPass = vault.getSecretSync("DB_PASSWORD", { devID : ADMIN_ID, passphrase : ADMIN_PASS });
          const names  = await vault.listNames();
          console.log("SERVICE_API_KEY =", apiKey);
          console.log("DB_PASSWORD =", dbPass);
          console.log("All keys =", names);
     }
     catch (error)
     {
          console.error("[Vault] read failed ~", error.message);
          process.exitCode = 1;
     }
})();

🔐 Accessing Secrets through Client

Reads secrets through the Aegis Env API, validating with grant enforcement.

"use strict";
const { createAegisEnv } = require("@trap_stevo/aegis");
const path = require("path");

const STORAGE = path.resolve(__dirname, ".aegis_store");
const NAMESPACE = "vault";
const APP_ID = process.env.AEGIS_APP_ID || "demo-app";

(async () => {
     const env = createAegisEnv({ storagePath : STORAGE, namespace : NAMESPACE });
     try
     {
          const apiKey = await env.get("SERVICE_API_KEY", { appID : APP_ID, appCWD : __dirname });
          console.log("SERVICE_API_KEY =", apiKey);
          const dbPass = env.getSync("DB_PASSWORD", { appID : APP_ID, appCWD : __dirname });
          console.log("DB_PASSWORD =", dbPass);
          const mailgun = await env.get("MAILGUN_KEY", { appID : APP_ID, appCWD : __dirname });
          console.log("MAILGUN_KEY =", mailgun);
     }
     catch (error)
     {
          console.error("[Client] read failed ~", error.code, error.message);
          process.exitCode = 1;
     }
})();

🧪 Example Workflows

🧭 Initialize Vault and Bootstrap Admin

const { createAegis } = require("@trap_stevo/aegis");

(async () => {
     const vault = createAegis({ storagePath : "PROJECT", namespace : "vault" });
     await vault.init();
     await vault.bootstrapAdmin("admin:local", "BOOTSTRAP_TOKEN", "supersecure");
     console.log("Vault initialized.");
})();

👤 Add Developer and Set Secrets

const vault = createAegis({ storagePath : "PROJECT" });
await vault.addDeveloper("devA", "temp123", "admin:local", "supersecure");
await vault.setSecret("SERVICE_API_KEY", "sk_live_123", "admin:local", "supersecure");

🧰 Using a Token Grant (CI/CD Mode)

await vault.addGrant("pipeline", {
     type : "token",
     path : "./deploy.sig",
     adminPubKey : "BASE64_PUB_KEY",
     alg : "ed25519"
}, "admin:local", "supersecure");

Then in the pipeline runner:

const { createAegisEnv } = require("@trap_stevo/aegis");
const env = createAegisEnv({ storagePath : "PROJECT" });
const key = await env.get("SERVICE_API_KEY", { appID : "pipeline", appCWD : process.cwd() });
console.log(key);

####🔌 Plugin Grant Example

await vault.addGrant("custom-app", {
     type : "plugin",
     modulePath : "./verifyCustom.js",
     moduleHash : "sha256_of_module",
     config : { allow : ["CI", "PROD"] }
}, "admin:local", "supersecure");

verifyCustom.js must export:

exports.verifySync = ({ meta, appCWD, config }) => {
     return config.allow.includes("PROD");
};

🧰 Development Mode (No Grant Enforcement)

Set environment variable:

AEGIS_GRANTS_MODE=permissive

This bypasses strict grant verification for local testing.

⚡ Troubleshooting

• ERR_NO_GRANT – Missing grant for appID
• ERR_UNAUTHORIZED – Invalid signature, token, or module hash
• ERR_UNVERIFIED_MACHINE – Lockprint mismatch; regenerate lockprint or re-init vault
• Grant mismatch after editing file – Re-run npm run start-aegis-set -- --grant

📜 License

See LICENSE.md

🛡️ Protect What Powers You

Aegis defends your application’s core credentials with simplicity and precision —
no agents, no cloud dependencies, no clutter. Just encrypted, attestable trust at rest and in runtime.