raqeb 1.0.0

package/README.md

@@ -0,0 +1,316 @@
+# Raqeb Node.js SDK
+
+Official Node.js/TypeScript SDK for Raqeb Database PAM and Secrets Management.
+
+## Installation
+
+```bash
+npm install raqeb
+# or
+yarn add raqeb
+```
+
+## Quick Start
+
+### TypeScript
+
+```typescript
+import { RaqebClient } from 'raqeb';
+
+// Initialize client
+const client = new RaqebClient({
+  apiKey: 'sa_your_api_key_here'
+});
+
+// Get a secret
+const secret = await client.getSecret('secret-id');
+console.log(`Secret value: ${secret.value}`);
+
+// Get temporary database credentials
+const creds = await client.getDatabaseCredentials('db-id', {
+  ttlHours: 4,
+  accessLevel: 'read-only'
+});
+
+console.log(`Username: ${creds.username}`);
+console.log(`Password: ${creds.password}`);
+console.log(`Expires: ${creds.expiresAt}`);
+
+// Revoke credentials when done
+await client.revokeLease(creds.leaseId);
+```
+
+### JavaScript
+
+```javascript
+const { RaqebClient } = require('raqeb');
+
+const client = new RaqebClient({
+  apiKey: 'sa_your_api_key_here'
+});
+
+// Use async/await
+(async () => {
+  const secret = await client.getSecret('secret-id');
+  console.log(secret.value);
+})();
+```
+
+## Usage Examples
+
+### Secrets Management
+
+```typescript
+import { RaqebClient } from 'raqeb';
+
+const client = new RaqebClient({ apiKey: process.env.RAQEB_API_KEY });
+
+// Retrieve a secret
+const secret = await client.getSecret('api-key-prod');
+const apiKey = secret.value;
+
+// Use the secret
+import axios from 'axios';
+const response = await axios.get('https://api.example.com/data', {
+  headers: { Authorization: `Bearer ${apiKey}` }
+});
+```
+
+### Database Access with PostgreSQL
+
+```typescript
+import { RaqebClient } from 'raqeb';
+import { Client } from 'pg';
+
+const raqeb = new RaqebClient({ apiKey: process.env.RAQEB_API_KEY });
+
+// Get temporary credentials
+const creds = await raqeb.getDatabaseCredentials('prod-postgres', {
+  ttlHours: 2,
+  accessLevel: 'read-only'
+});
+
+// Connect to database
+const db = new Client({
+  host: 'db.example.com',
+  port: 5432,
+  database: 'myapp',
+  user: creds.username,
+  password: creds.password,
+});
+
+try {
+  await db.connect();
+  const result = await db.query('SELECT * FROM users LIMIT 10');
+  console.log(result.rows);
+} finally {
+  await db.end();
+  // Revoke credentials
+  await raqeb.revokeLease(creds.leaseId);
+}
+```
+
+### Database Access with MySQL
+
+```typescript
+import { RaqebClient } from 'raqeb';
+import mysql from 'mysql2/promise';
+
+const raqeb = new RaqebClient({ apiKey: process.env.RAQEB_API_KEY });
+
+const creds = await raqeb.getDatabaseCredentials('prod-mysql', {
+  ttlHours: 1,
+  accessLevel: 'read-write'
+});
+
+const connection = await mysql.createConnection({
+  host: 'db.example.com',
+  user: creds.username,
+  password: creds.password,
+  database: 'myapp'
+});
+
+try {
+  const [rows] = await connection.execute('SELECT * FROM products');
+  console.log(rows);
+} finally {
+  await connection.end();
+  await raqeb.revokeLease(creds.leaseId);
+}
+```
+
+### API Key Management
+
+```typescript
+import { RaqebClient } from 'raqeb';
+
+const client = new RaqebClient({ apiKey: process.env.RAQEB_API_KEY });
+
+// List API keys
+const keys = await client.listAPIKeys();
+keys.forEach(key => {
+  console.log(`${key.name}: ${key.keyPrefix}...`);
+  console.log(`  Active: ${key.isActive}`);
+  console.log(`  Last used: ${key.lastUsedAt || 'Never'}`);
+});
+
+// Create new API key
+const newKey = await client.createAPIKey({
+  name: 'CI/CD Pipeline',
+  scopes: ['secrets:read', 'databases:read'],
+  description: 'Key for automated deployments'
+});
+console.log(`New API Key: ${newKey.apiKey}`); // Save this!
+
+// Delete API key
+await client.deleteAPIKey('key-id');
+```
+
+### Error Handling
+
+```typescript
+import {
+  RaqebClient,
+  AuthenticationError,
+  PermissionError,
+  NotFoundError,
+  RaqebError
+} from 'raqeb';
+
+const client = new RaqebClient({ apiKey: process.env.RAQEB_API_KEY });
+
+try {
+  const secret = await client.getSecret('secret-id');
+  console.log(secret.value);
+  
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid or expired API key');
+  } else if (error instanceof PermissionError) {
+    console.error('Insufficient permissions - check API key scopes');
+  } else if (error instanceof NotFoundError) {
+    console.error('Secret not found');
+  } else if (error instanceof RaqebError) {
+    console.error(`API error: ${error.message}`);
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+### Express.js Middleware
+
+```typescript
+import express from 'express';
+import { RaqebClient } from 'raqeb';
+
+const app = express();
+const raqeb = new RaqebClient({ apiKey: process.env.RAQEB_API_KEY });
+
+// Middleware to inject database credentials
+app.use(async (req, res, next) => {
+  try {
+    const creds = await raqeb.getDatabaseCredentials('prod-db', {
+      ttlHours: 1,
+      accessLevel: 'read-only'
+    });
+    
+    req.dbCreds = creds;
+    
+    // Cleanup after response
+    res.on('finish', async () => {
+      await raqeb.revokeLease(creds.leaseId);
+    });
+    
+    next();
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to get database credentials' });
+  }
+});
+
+app.get('/users', async (req, res) => {
+  // Use req.dbCreds to connect to database
+  // ...
+});
+```
+
+## API Reference
+
+### RaqebClient
+
+#### Constructor
+
+```typescript
+new RaqebClient(options: RaqebClientOptions)
+```
+
+**Options:**
+- `apiKey` (string, required): Service account API key
+- `baseUrl` (string, optional): Base URL for Raqeb API (default: `https://app.raqeb.cloud/api/v1`)
+- `timeout` (number, optional): Request timeout in milliseconds (default: 30000)
+
+#### Methods
+
+##### `getSecret(secretId: string): Promise<Secret>`
+Retrieve a secret value.
+
+##### `getDatabaseCredentials(databaseId: string, options?: DatabaseCredentialsOptions): Promise<DatabaseCredentials>`
+Generate temporary database credentials.
+
+**Options:**
+- `ttlHours` (number): Time to live in hours (default: 4)
+- `accessLevel` ('read-only' | 'read-write' | 'admin'): Access level (default: 'read-only')
+
+##### `revokeLease(leaseId: string): Promise<void>`
+Revoke a dynamic secret lease.
+
+##### `listAPIKeys(): Promise<APIKey[]>`
+List user's API keys.
+
+##### `createAPIKey(data: APIKeyCreate): Promise<APIKey & { apiKey: string }>`
+Create a new API key.
+
+##### `deleteAPIKey(keyId: string): Promise<void>`
+Delete an API key.
+
+## TypeScript Support
+
+This SDK is written in TypeScript and includes full type definitions.
+
+```typescript
+import { RaqebClient, DatabaseCredentials, Secret } from 'raqeb';
+
+const client: RaqebClient = new RaqebClient({ apiKey: 'sa_key' });
+const creds: DatabaseCredentials = await client.getDatabaseCredentials('db-id');
+const secret: Secret = await client.getSecret('secret-id');
+```
+
+## Environment Variables
+
+```typescript
+import { RaqebClient } from 'raqeb';
+
+const client = new RaqebClient({
+  apiKey: process.env.RAQEB_API_KEY!,
+  baseUrl: process.env.RAQEB_BASE_URL
+});
+```
+
+## Best Practices
+
+1. **Use environment variables** - Never hardcode API keys
+2. **Minimal scopes** - Only grant necessary permissions
+3. **Short TTLs** - Use shortest time needed for database access
+4. **Always revoke** - Clean up credentials when done
+5. **Error handling** - Catch and handle SDK exceptions
+6. **TypeScript** - Leverage type safety for better development experience
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Support
+
+- Documentation: https://docs.raqeb.cloud
+- Email: support@raqeb.cloud
+- GitHub: https://github.com/raqeb/nodejs-sdk

package/dist/client.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Raqeb Client for Node.js
+ */
+import { RaqebClientOptions, Secret, DatabaseCredentials, APIKey, APIKeyCreate, DatabaseCredentialsOptions } from './types';
+export declare class RaqebClient {
+    private client;
+    private apiKey;
+    /**
+     * Create a new Raqeb client
+     *
+     * @param options - Client configuration options
+     * @example
+     * ```typescript
+     * const client = new RaqebClient({
+     *   apiKey: 'sa_your_api_key',
+     *   baseUrl: 'https://app.raqeb.cloud/api/v1'
+     * });
+     * ```
+     */
+    constructor(options: RaqebClientOptions);
+    private handleError;
+    /**
+     * Retrieve a secret value
+     *
+     * @param secretId - ID of the secret to retrieve
+     * @returns Secret object with value
+     * @example
+     * ```typescript
+     * const secret = await client.getSecret('secret-123');
+     * console.log(secret.value);
+     * ```
+     */
+    getSecret(secretId: string): Promise<Secret>;
+    /**
+     * Generate temporary database credentials
+     *
+     * @param databaseId - ID of the database
+     * @param options - Credential options (ttlHours, accessLevel)
+     * @returns Temporary database credentials
+     * @example
+     * ```typescript
+     * const creds = await client.getDatabaseCredentials('db-123', {
+     *   ttlHours: 4,
+     *   accessLevel: 'read-only'
+     * });
+     * console.log(`Username: ${creds.username}`);
+     * console.log(`Password: ${creds.password}`);
+     * console.log(`Expires: ${creds.expiresAt}`);
+     * ```
+     */
+    getDatabaseCredentials(databaseId: string, options?: DatabaseCredentialsOptions): Promise<DatabaseCredentials>;
+    /**
+     * Revoke a dynamic secret lease
+     *
+     * @param leaseId - ID of the lease to revoke
+     * @example
+     * ```typescript
+     * await client.revokeLease('lease-123');
+     * ```
+     */
+    revokeLease(leaseId: string): Promise<void>;
+    /**
+     * List user's API keys
+     *
+     * @returns Array of API key objects
+     * @example
+     * ```typescript
+     * const keys = await client.listAPIKeys();
+     * keys.forEach(key => {
+     *   console.log(`${key.name}: ${key.keyPrefix}...`);
+     * });
+     * ```
+     */
+    listAPIKeys(): Promise<APIKey[]>;
+    /**
+     * Create a new API key
+     *
+     * @param data - API key creation data
+     * @returns Created API key (includes the key value - save it!)
+     * @example
+     * ```typescript
+     * const key = await client.createAPIKey({
+     *   name: 'My App',
+     *   scopes: ['secrets:read', 'databases:read'],
+     *   description: 'Key for CI/CD'
+     * });
+     * console.log(`API Key: ${key.apiKey}`); // Save this!
+     * ```
+     */
+    createAPIKey(data: APIKeyCreate): Promise<APIKey & {
+        apiKey: string;
+    }>;
+    /**
+     * Delete an API key
+     *
+     * @param keyId - ID of the key to delete
+     * @example
+     * ```typescript
+     * await client.deleteAPIKey('key-123');
+     * ```
+     */
+    deleteAPIKey(keyId: string): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,175 @@
+"use strict";
+/**
+ * Raqeb Client for Node.js
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RaqebClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+const errors_1 = require("./errors");
+class RaqebClient {
+    /**
+     * Create a new Raqeb client
+     *
+     * @param options - Client configuration options
+     * @example
+     * ```typescript
+     * const client = new RaqebClient({
+     *   apiKey: 'sa_your_api_key',
+     *   baseUrl: 'https://app.raqeb.cloud/api/v1'
+     * });
+     * ```
+     */
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.client = axios_1.default.create({
+            baseURL: options.baseUrl || 'https://app.raqeb.cloud/api/v1',
+            headers: {
+                'Authorization': `Bearer ${options.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            timeout: options.timeout || 30000,
+        });
+        // Error interceptor
+        this.client.interceptors.response.use((response) => response, (error) => {
+            return Promise.reject(this.handleError(error));
+        });
+    }
+    handleError(error) {
+        if (!error.response) {
+            return new errors_1.RaqebError(`Network error: ${error.message}`);
+        }
+        const status = error.response.status;
+        const detail = error.response.data?.detail || error.message;
+        switch (status) {
+            case 401:
+                return new errors_1.AuthenticationError(detail);
+            case 403:
+                return new errors_1.PermissionError(detail);
+            case 404:
+                return new errors_1.NotFoundError(detail);
+            default:
+                return new errors_1.RaqebError(`HTTP ${status}: ${detail}`);
+        }
+    }
+    // ============================================================================
+    // Secrets Management
+    // ============================================================================
+    /**
+     * Retrieve a secret value
+     *
+     * @param secretId - ID of the secret to retrieve
+     * @returns Secret object with value
+     * @example
+     * ```typescript
+     * const secret = await client.getSecret('secret-123');
+     * console.log(secret.value);
+     * ```
+     */
+    async getSecret(secretId) {
+        const response = await this.client.post('/service-accounts/secrets/retrieve', null, {
+            params: { secret_id: secretId },
+        });
+        return response.data;
+    }
+    // ============================================================================
+    // Database Credentials
+    // ============================================================================
+    /**
+     * Generate temporary database credentials
+     *
+     * @param databaseId - ID of the database
+     * @param options - Credential options (ttlHours, accessLevel)
+     * @returns Temporary database credentials
+     * @example
+     * ```typescript
+     * const creds = await client.getDatabaseCredentials('db-123', {
+     *   ttlHours: 4,
+     *   accessLevel: 'read-only'
+     * });
+     * console.log(`Username: ${creds.username}`);
+     * console.log(`Password: ${creds.password}`);
+     * console.log(`Expires: ${creds.expiresAt}`);
+     * ```
+     */
+    async getDatabaseCredentials(databaseId, options = {}) {
+        const payload = {
+            database_id: databaseId,
+            ttl_hours: options.ttlHours || 4,
+            access_level: options.accessLevel || 'read-only',
+        };
+        const response = await this.client.post('/service-accounts/databases/dynamic-credentials', payload);
+        return response.data;
+    }
+    /**
+     * Revoke a dynamic secret lease
+     *
+     * @param leaseId - ID of the lease to revoke
+     * @example
+     * ```typescript
+     * await client.revokeLease('lease-123');
+     * ```
+     */
+    async revokeLease(leaseId) {
+        await this.client.post(`/service-accounts/leases/${leaseId}/revoke`);
+    }
+    // ============================================================================
+    // API Keys Management
+    // ============================================================================
+    /**
+     * List user's API keys
+     *
+     * @returns Array of API key objects
+     * @example
+     * ```typescript
+     * const keys = await client.listAPIKeys();
+     * keys.forEach(key => {
+     *   console.log(`${key.name}: ${key.keyPrefix}...`);
+     * });
+     * ```
+     */
+    async listAPIKeys() {
+        const response = await this.client.get('/service-accounts/api-keys');
+        return response.data;
+    }
+    /**
+     * Create a new API key
+     *
+     * @param data - API key creation data
+     * @returns Created API key (includes the key value - save it!)
+     * @example
+     * ```typescript
+     * const key = await client.createAPIKey({
+     *   name: 'My App',
+     *   scopes: ['secrets:read', 'databases:read'],
+     *   description: 'Key for CI/CD'
+     * });
+     * console.log(`API Key: ${key.apiKey}`); // Save this!
+     * ```
+     */
+    async createAPIKey(data) {
+        const payload = {
+            name: data.name,
+            description: data.description,
+            scopes: data.scopes || ['secrets:read', 'databases:read'],
+            expires_at: data.expiresAt,
+        };
+        const response = await this.client.post('/service-accounts/api-keys', payload);
+        return response.data;
+    }
+    /**
+     * Delete an API key
+     *
+     * @param keyId - ID of the key to delete
+     * @example
+     * ```typescript
+     * await client.deleteAPIKey('key-123');
+     * ```
+     */
+    async deleteAPIKey(keyId) {
+        await this.client.delete(`/service-accounts/api-keys/${keyId}`);
+    }
+}
+exports.RaqebClient = RaqebClient;

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Error classes for Raqeb SDK
+ */
+export declare class RaqebError extends Error {
+    constructor(message: string);
+}
+export declare class AuthenticationError extends RaqebError {
+    constructor(message: string);
+}
+export declare class PermissionError extends RaqebError {
+    constructor(message: string);
+}
+export declare class NotFoundError extends RaqebError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Error classes for Raqeb SDK
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotFoundError = exports.PermissionError = exports.AuthenticationError = exports.RaqebError = void 0;
+class RaqebError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RaqebError';
+        Object.setPrototypeOf(this, RaqebError.prototype);
+    }
+}
+exports.RaqebError = RaqebError;
+class AuthenticationError extends RaqebError {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthenticationError';
+        Object.setPrototypeOf(this, AuthenticationError.prototype);
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class PermissionError extends RaqebError {
+    constructor(message) {
+        super(message);
+        this.name = 'PermissionError';
+        Object.setPrototypeOf(this, PermissionError.prototype);
+    }
+}
+exports.PermissionError = PermissionError;
+class NotFoundError extends RaqebError {
+    constructor(message) {
+        super(message);
+        this.name = 'NotFoundError';
+        Object.setPrototypeOf(this, NotFoundError.prototype);
+    }
+}
+exports.NotFoundError = NotFoundError;

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Raqeb Node.js SDK - Database PAM and Secrets Management
+ *
+ * @example
+ * ```typescript
+ * import { RaqebClient } from 'raqeb';
+ *
+ * const client = new RaqebClient({ apiKey: 'sa_your_api_key' });
+ *
+ * // Get secret
+ * const secret = await client.getSecret('secret-id');
+ * console.log(secret.value);
+ *
+ * // Get database credentials
+ * const creds = await client.getDatabaseCredentials('db-id', { ttlHours: 4 });
+ * console.log(`Username: ${creds.username}`);
+ * console.log(`Password: ${creds.password}`);
+ *
+ * // Revoke when done
+ * await client.revokeLease(creds.leaseId);
+ * ```
+ */
+export { RaqebClient } from './client';
+export * from './types';
+export * from './errors';

package/dist/index.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Raqeb Node.js SDK - Database PAM and Secrets Management
+ *
+ * @example
+ * ```typescript
+ * import { RaqebClient } from 'raqeb';
+ *
+ * const client = new RaqebClient({ apiKey: 'sa_your_api_key' });
+ *
+ * // Get secret
+ * const secret = await client.getSecret('secret-id');
+ * console.log(secret.value);
+ *
+ * // Get database credentials
+ * const creds = await client.getDatabaseCredentials('db-id', { ttlHours: 4 });
+ * console.log(`Username: ${creds.username}`);
+ * console.log(`Password: ${creds.password}`);
+ *
+ * // Revoke when done
+ * await client.revokeLease(creds.leaseId);
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RaqebClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "RaqebClient", { enumerable: true, get: function () { return client_1.RaqebClient; } });
+__exportStar(require("./types"), exports);
+__exportStar(require("./errors"), exports);

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Type definitions for Raqeb SDK
+ */
+export interface RaqebClientOptions {
+    /** Service account API key */
+    apiKey: string;
+    /** Base URL for Raqeb API */
+    baseUrl?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+export interface Secret {
+    secretId: string;
+    name: string;
+    value: string;
+    retrievedAt: string;
+}
+export interface DatabaseCredentials {
+    leaseId: string;
+    username: string;
+    password: string;
+    databaseId: string;
+    accessLevel: 'read-only' | 'read-write' | 'admin';
+    issuedAt: string;
+    expiresAt: string;
+    ttlSeconds: number;
+}
+export interface DatabaseCredentialsOptions {
+    /** Time to live in hours (default: 4) */
+    ttlHours?: number;
+    /** Access level (default: 'read-only') */
+    accessLevel?: 'read-only' | 'read-write' | 'admin';
+}
+export interface APIKey {
+    id: string;
+    name: string;
+    keyPrefix: string;
+    scopes: string[];
+    isActive: boolean;
+    createdAt: string;
+    lastUsedAt?: string;
+    expiresAt?: string;
+}
+export interface APIKeyCreate {
+    name: string;
+    description?: string;
+    scopes?: string[];
+    expiresAt?: string;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Type definitions for Raqeb SDK
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "raqeb",
+  "version": "1.0.0",
+  "description": "Node.js SDK for Raqeb Database PAM and Secrets Management",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "raqeb",
+    "pam",
+    "secrets",
+    "database",
+    "security",
+    "credentials"
+  ],
+  "author": "Raqeb",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/raqeb/nodejs-sdk"
+  },
+  "dependencies": {
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}