aether-vault
Advanced tools
Official NodeJS SDK for Aether Vault - Unified secrets and TOTP management
🔐 Official SDK for Aether Vault - Centralized secrets, TOTP, and identity management for modern applications.
This SDK provides a comprehensive, type-safe interface for interacting with Aether Vault API, eliminating the need for raw /api/v1/* fetch calls throughout your codebase.
🚀 Quick Start • 📋 Features • 📖 Installation • 🎨 Usage Examples • 📚 API Reference • 🏗️ Architecture • 🛠️ Error Handling • ⚙️ Configuration • 🤝 Contributing
Aether Vault Node.js SDK is the official TypeScript client library for the Aether Vault secure secrets management platform. It provides a clean, intuitive, and type-safe interface that completely abstracts away HTTP complexity while giving developers full access to all Aether Vault capabilities.
# npm
npm install aether-vault
# yarn
yarn add aether-vault
# pnpm (recommended)
pnpm add aether-vault
# Verify installation
npm list aether-vault
import { createVaultClient } from "aether-vault";
// Create vault client
const vault = createVaultClient({
baseURL: "http://localhost:8080", // or "https://vault.example.com/api/v1"
auth: {
type: "session", // Uses browser cookies for web apps
// Other options:
// type: "jwt",
// token: "your-jwt-token",
// type: "bearer",
// token: "your-bearer-token",
},
timeout: 10000, // Request timeout in milliseconds
retry: true, // Enable automatic retries
maxRetries: 3, // Maximum retry attempts
});
// Login user
const session = await vault.auth.login({
username: "user@example.com",
password: "securePassword123",
});
console.log("Logged in as:", session.user.displayName);
console.log("Token expires:", session.expiresAt);
// Check current session
const currentSession = await vault.auth.session();
console.log("Session valid:", currentSession.valid);
// Create a secret
const secret = await vault.secrets.create({
name: "Database Connection",
value: "postgresql://user:pass@localhost:5432/mydb",
description: "Production database connection",
type: "database",
tags: "production,critical",
expiresAt: new Date("2025-12-31"),
});
// List all secrets
const { secrets } = await vault.secrets.list({
pageSize: 50,
tags: "production",
});
// Get a specific secret
const dbSecret = await vault.secrets.getValue("Database_Connection");
console.log("Database URL:", dbSecret);
// Update a secret
const updated = await vault.secrets.update("Database_Connection", {
description: "Updated database connection",
});
// Delete a secret
await vault.secrets.delete("old-api-key");
// Generate TOTP for a service
const totp = await vault.totp.generate({
name: "GitHub 2FA",
description: "Two-factor authentication for GitHub",
account: "user@example.com",
});
console.log("Scan QR code with:", totp.qrCode);
console.log("Backup codes:", totp.backupCodes);
// Generate a code
const { code, remainingSeconds } = await vault.totp.generate("github-2fa");
console.log("Your code:", code, "Valid for", remainingSeconds, "seconds");
// Get current user profile
const user = await vault.identity.me();
console.log("Current user:", user.email, user.displayName);
// Get user policies
const policies = await vault.identity.policies();
console.log("User policies:", policies);
// Get audit logs with filtering
const auditLogs = await vault.audit.list({
dateFrom: new Date("2025-01-01"),
action: "secret_access",
pageSize: 100,
});
// Get failed authentication attempts
const failedLogins = await vault.audit.getFailedAuth({
dateFrom: new Date(Date.now() - 24 * 60 * 60 * 1000), // Last 24 hours
pageSize: 50,
});
// Export audit logs to CSV
const csvData = await vault.audit.exportToCSV({
dateFrom: new Date("2025-01-01"),
dateTo: new Date("2025-01-31"),
});
// Check system health
const health = await vault.system.health();
console.log("System status:", health.status);
// Get version information
const version = await vault.system.version();
console.log("Aether Vault version:", version.version);
// Comprehensive system status
const status = await vault.system.status();
console.log("System healthy:", status.healthy);
console.log("Version:", status.version.version);
import { createVaultClient } from "aether-vault";
async function completeWorkflow() {
const vault = createVaultClient({
baseURL: "http://localhost:8080",
auth: { type: "session" },
});
try {
console.log("🚀 Starting Aether Vault workflow...");
// 1. Check system health
const health = await vault.system.health();
if (health.status !== "healthy") {
throw new Error("Aether Vault is not healthy");
}
console.log("✅ System is healthy");
// 2. Authenticate user
const session = await vault.auth.login({
username: "user@example.com",
password: "securePassword123",
});
console.log("✅ Authenticated as:", session.user.displayName);
// 3. Create a secret
const secret = await vault.secrets.create({
name: "API Key",
value: "sk_live_1234567890",
type: "api_key",
tags: "production,critical",
});
console.log("✅ Created secret:", secret.name);
// 4. Generate TOTP
const totp = await vault.totp.generate({
name: "Mobile App 2FA",
});
console.log("✅ Generated TOTP:", totp.name);
// 5. List secrets
const { secrets } = await vault.secrets.list();
console.log("✅ Found", secrets.total, "secrets");
// 6. Get user profile
const user = await vault.identity.me();
console.log("✅ Current user:", user.email);
// 7. Check audit logs
const auditLogs = await vault.audit.list({ pageSize: 10 });
console.log("✅ Recent audit entries:", auditLogs.entries.length);
// 8. Logout
await vault.auth.logout();
console.log("✅ Logged out successfully");
console.log("🎉 Workflow completed successfully!");
} catch (error) {
console.error("❌ Workflow failed:", error);
}
}
// Run the workflow
completeWorkflow();
// app/lib/vault.ts
import { createVaultClient } from "aether-vault";
export const vault = createVaultClient({
baseURL: process.env.NEXT_PUBLIC_VAULT_URL || "/api/v1",
auth: {
type: "session", // For web applications
},
});
export async function getServerSecrets() {
try {
return await vault.secrets.list();
} catch (error) {
console.error("Failed to fetch secrets:", error);
throw error;
}
}
// app/components/secrets-manager.tsx
"use client";
import { useState, useEffect } from "react";
import { vault } from "@/lib/vault";
export function SecretsManager() {
const [secrets, setSecrets] = useState<any[]>([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
async function loadSecrets() {
try {
const response = await vault.secrets.list({ pageSize: 20 });
setSecrets(response.secrets);
} catch (error) {
console.error("Failed to load secrets:", error);
} finally {
setLoading(false);
}
}
loadSecrets();
}, []);
const handleCreateSecret = async (name: string, value: string) => {
try {
await vault.secrets.create({ name, value });
const response = await vault.secrets.list({ pageSize: 20 });
setSecrets(response.secrets);
} catch (error) {
console.error("Failed to create secret:", error);
}
};
if (loading) return <div>Loading...</div>;
return (
<div>
<h1>Secrets Manager</h1>
<button onClick={() => handleCreateSecret("NEW_SECRET", "value")}>
Create Secret
</button>
<ul>
{secrets.map((secret) => (
<li key={secret.id}>
<strong>{secret.name}</strong> - {secret.description}
</li>
))}
</ul>
</div>
);
}
vault.auth.*)// Login with credentials
vault.auth.login(credentials: AuthCredentials): Promise<AuthSession>
// Logout current session
vault.auth.logout(): Promise<void>
// Get current session
vault.auth.session(): Promise<{ user: UserIdentity; valid: boolean }>
// Register new user
vault.auth.register(userData: RegisterData): Promise<UserIdentity>
// Change password
vault.auth.changePassword(data: PasswordChangeData): Promise<void>
// Request password reset
vault.auth.forgotPassword(email: string): Promise<void>
// Reset password with token
vault.auth.resetPassword(data: PasswordResetData): Promise<void>
// Validate token
vault.auth.validate(): Promise<boolean>
// Get current user
vault.auth.getCurrentUser(): Promise<UserIdentity>
vault.secrets.*)// List all secrets (with pagination)
vault.secrets.list(params?: SecretFilterParams): Promise<SecretListResponse>
// Get specific secret by ID
vault.secrets.get(id: string): Promise<Secret>
// Create new secret
vault.secrets.create(secret: SecretInput): Promise<Secret>
// Update existing secret
vault.secrets.update(id: string, updates: SecretUpdate): Promise<Secret>
// Delete secret
vault.secrets.delete(id: string): Promise<void>
vault.totp.*)// List TOTP entries
vault.totp.list(params?: TOTPFilterParams): Promise<TOTPListResponse>
// Generate new TOTP
vault.totp.generate(data: TOTPCreateInput): Promise<TOTPEntry>
// Generate TOTP code
vault.totp.generate(id: string): Promise<TOTPCode>
// Update TOTP entry
vault.totp.update(id: string, updates: Partial<TOTPCreateInput>): Promise<TOTPEntry>
// Delete TOTP entry
vault.totp.delete(id: string): Promise<void>
vault.identity.*)// Get current user profile
vault.identity.me(): Promise<UserIdentity>
// Get user policies
vault.identity.policies(): Promise<Policy[]>
vault.audit.*)// List audit entries
vault.audit.list(filter?: AuditFilter): Promise<AuditListResponse>
// Get specific audit entry
vault.audit.getEntry(id: string): Promise<AuditEntry>
// Get audit entries for specific user
vault.audit.getUserEntries(userId: string, options?: Omit<AuditFilter, "userId">): Promise<AuditListResponse>
// Get failed authentication attempts
vault.audit.getFailedAuth(options?: Omit<AuditFilter, "action">): Promise<AuditListResponse>
// Get secret access logs
vault.audit.getSecretAccess(options?: Omit<AuditFilter, "resource">): Promise<AuditListResponse>
// Export audit logs to CSV
vault.audit.exportToCSV(filter?: AuditFilter): Promise<string>
vault.system.*)// Check system health
vault.system.health(): Promise<HealthResponse>
// Get version information
vault.system.version(): Promise<VersionResponse>
// Check system readiness
vault.system.ready(): Promise<boolean>
// Get system metrics
vault.system.metrics(): Promise<SystemMetrics>
// Get comprehensive system status
vault.system.status(): Promise<SystemStatus>
The SDK provides comprehensive, typed error handling for all API operations:
import {
VaultError,
VaultAuthError,
VaultPermissionError,
VaultNotFoundError,
VaultServerError,
VaultNetworkError,
} from "aether-vault";
import { VaultError, VaultAuthError } from "aether-vault";
try {
const secret = await vault.secrets.get("non-existent-secret");
console.log("Secret value:", secret.value);
} catch (error) {
if (error instanceof VaultNotFoundError) {
console.log("Secret not found - create it first");
} else if (error instanceof VaultAuthError) {
console.log("Authentication failed - please login again");
window.location.href = "/login";
} else if (error instanceof VaultPermissionError) {
console.log("Permission denied - insufficient access rights");
} else if (error instanceof VaultError) {
console.log("Vault error:", error.message);
} else {
console.error("Unexpected error:", error);
}
}
interface VaultConfig {
// API base URL - no trailing slash
baseURL: string;
// Authentication configuration
auth: AuthConfig;
// Request timeout (milliseconds)
timeout?: number;
// Retry configuration
retry?: boolean;
maxRetries?: number;
retryDelay?: number;
// Custom headers
headers?: Record<string, string>;
// Debug mode for development
debug?: boolean;
}
// Session-based (recommended for web apps)
interface SessionAuthConfig {
type: "session";
}
// JWT-based (recommended for API services)
interface JwtAuthConfig {
type: "jwt";
token: string;
jwt?: {
autoRefresh?: boolean;
refreshEndpoint?: string;
refreshFn?: (token: string) => Promise<string>;
};
}
// Bearer token-based
interface BearerAuthConfig {
type: "bearer";
token: string;
}
// No authentication
interface NoAuthConfig {
type: "none";
}
# Local development
NEXT_PUBLIC_VAULT_URL=http://localhost:8080
# Cloud deployment
NEXT_PUBLIC_VAULT_URL=https://api.aethervault.com
# Appliance deployment
NEXT_PUBLIC_VAULT_URL=https://vault.company.internal
src/
├── core/ # HTTP client, configuration, and error handling
│ ├── client.ts # Main HTTP client with fetch/isomorphic support
│ ├── config.ts # Configuration management and validation
│ └── errors.ts # Typed error definitions
├── auth/ # Authentication domain client
│ └── auth.client.ts # Authentication operations
├── secrets/ # Secrets management domain client
│ └── secrets.client.ts # Secrets CRUD operations
├── totp/ # TOTP domain client
│ └── totp.client.ts # TOTP generation and verification
├── identity/ # Identity domain client
│ └── identity.client.ts # User profile and session management
├── audit/ # Audit domain client
│ └── audit.client.ts # Audit log operations
├── policies/ # Policy management client
│ └── policy.client.ts # Access control policies
├── system/ # System operations client
│ └── system.client.ts # Health checks and metrics
└── types/ # Type definitions
│ ├── vault.ts # Core API types
│ └── index.ts # Type exports
└── index.ts # Main SDK entry point
// tsconfig.json
{
"compilerOptions": {
"strict": true,
"noImplicitAny": true,
"noImplicitReturns": true,
"noUnusedLocals": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"forceConsistentCasingInFileNames": true,
"moduleResolution": "node",
"declaration": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist", "**/*.test.ts"]
}
# Install dependencies
pnpm install
# Run in development mode
pnpm dev
# Build for production
pnpm build
# Run tests
pnpm test
# Type checking
pnpm typecheck
const vault = createVaultClient({
baseURL: "http://localhost:8080",
debug: true, // Enable debug logging
});
// All requests and responses will be logged
We welcome contributions to help improve the Aether Vault Node.js SDK! Whether you're experienced with TypeScript, API clients, authentication systems, or security-focused development, there's a place for you.
pnpm commands for all operations# Install dependencies
pnpm install
# Run tests
pnpm test
# Type checking
pnpm typecheck
# Build library
pnpm build
# Run examples
pnpm dev examples/basic-usage.ts
MIT License - see LICENSE file for details.
When reporting bugs, please include:
| Component | Status | Technology | Evolution |
|---|---|---|---|
| Core SDK | ✅ Working | TypeScript + Native Fetch | Enhanced |
| Authentication | ✅ Working | JWT + Session + Refresh | Complete |
| Secrets Management | ✅ Working | Full CRUD + Encryption | Complete |
| TOTP Support | ✅ Working | QR Codes + Verification | Complete |
| Identity Management | ✅ Working | Profiles + Session Control | Complete |
| Audit Logging | ✅ Working | Full Audit + Export | Complete |
| System Operations | ✅ Working | Health + Metrics | Complete |
| Type Safety | ✅ Working | Strict Mode + Types | Complete |
| Error Handling | ✅ Working | Typed Errors + Catching | Complete |
| Documentation | ✅ Working | Complete Examples | Enhanced |
| Multi-Environment | ✅ Working | Local/Cloud/Appliance | Enhanced |
| Developer Experience | ✅ Working | Autocompletion + Debugging | Enhanced |
Made with ❤️ by the Sky Genesis Enterprise team
Building the future of secure secrets management for modern applications
FAQs
Official NodeJS SDK for Aether Vault - Unified secrets and TOTP management
The npm package aether-vault receives a total of 17 weekly downloads. As such, aether-vault popularity was classified as not popular.
We found that aether-vault demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.