@true-and-useful/janee 0.8.4 → 0.9.0

package/dist/providers/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Secrets Provider Plugin Interface
+ *
+ * Defines the contract all secrets providers must implement.
+ * See RFC 0005 for full design: docs/rfcs/0005-plugin-architecture.md
+ */
+/**
+ * Error codes for categorizing secrets operation failures.
+ * Enables callers to handle errors programmatically without message matching.
+ */
+export declare enum SecretErrorCode {
+    /** Provider is not initialized (call initialize() first) */
+    NOT_INITIALIZED = "NOT_INITIALIZED",
+    /** Secret was not found (normal -- not an error for most callers) */
+    NOT_FOUND = "NOT_FOUND",
+    /** Authentication failure (bad credentials, expired token) */
+    AUTH_FAILED = "AUTH_FAILED",
+    /** Permission denied (authenticated but not authorized) */
+    ACCESS_DENIED = "ACCESS_DENIED",
+    /** Provider unreachable (network error, timeout) */
+    PROVIDER_UNAVAILABLE = "PROVIDER_UNAVAILABLE",
+    /** Secret path is invalid (traversal attempt, bad characters) */
+    INVALID_PATH = "INVALID_PATH",
+    /** URI format is invalid */
+    INVALID_URI = "INVALID_URI",
+    /** Encryption/decryption failure */
+    CRYPTO_ERROR = "CRYPTO_ERROR",
+    /** Provider-specific configuration error */
+    CONFIG_ERROR = "CONFIG_ERROR",
+    /** Generic internal error */
+    INTERNAL = "INTERNAL"
+}
+/**
+ * Typed error for secrets operations.
+ * Enables programmatic error handling without message parsing.
+ */
+export declare class SecretError extends Error {
+    readonly code: SecretErrorCode;
+    readonly provider?: string;
+    readonly secretPath?: string;
+    constructor(code: SecretErrorCode, message: string, options?: {
+        provider?: string;
+        secretPath?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Core interface that all secrets providers must implement.
+ */
+export interface SecretsProvider {
+    /** Human-readable provider name (e.g., "my-vault") */
+    readonly name: string;
+    /** Provider type identifier (e.g., "hashicorp-vault", "aws-secrets-manager") */
+    readonly type: string;
+    /**
+     * Initialize the provider (connect, authenticate, validate config).
+     * Called once before any secret operations.
+     * @throws SecretError if provider cannot be initialized
+     */
+    initialize(): Promise<void>;
+    /**
+     * Retrieve a secret by path.
+     * @param path - Provider-specific path (e.g., "mcp/agents/stripe/api-key")
+     * @returns The secret value, or null if not found
+     * @throws SecretError on connection/auth errors (NOT on missing secrets)
+     */
+    getSecret(path: string): Promise<string | null>;
+    /**
+     * Store a secret. Optional -- not all providers support writes.
+     * @param path - Provider-specific path
+     * @param value - Secret value to store
+     */
+    setSecret?(path: string, value: string): Promise<void>;
+    /**
+     * Delete a secret. Optional.
+     */
+    deleteSecret?(path: string): Promise<void>;
+    /**
+     * List available secret paths. Optional -- useful for CLI tooling.
+     */
+    listSecrets?(prefix?: string): Promise<string[]>;
+    /**
+     * Clean up resources (close connections, etc.).
+     */
+    dispose(): Promise<void>;
+    /**
+     * Health check -- is the provider accessible and authenticated?
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+}
+export interface HealthCheckResult {
+    healthy: boolean;
+    error?: string;
+    /** Optional latency in milliseconds */
+    latencyMs?: number;
+}
+/**
+ * Configuration for a provider instance.
+ * The `config` field is provider-type-specific.
+ */
+export interface ProviderConfig {
+    /** Instance name (referenced in service configs) */
+    name: string;
+    /** Provider type (determines which class to instantiate) */
+    type: string;
+    /** Type-specific configuration */
+    config: Record<string, unknown>;
+}
+/**
+ * Factory function type for creating provider instances.
+ */
+export type ProviderFactory = (config: ProviderConfig) => SecretsProvider;
+/**
+ * Parse a provider URI like "vault://mcp/stripe/api-key"
+ * Returns { provider: "vault", path: "mcp/stripe/api-key" }
+ * If no scheme, returns { provider: null, path: original }
+ *
+ * Enforces:
+ *   - Provider names normalized to lowercase, 1-64 chars
+ *   - Percent-decoding of path components
+ *   - Rejection of ".." path segments (traversal prevention)
+ *   - Max path length of 1024 characters
+ *
+ * @throws SecretError with INVALID_URI code on validation failure
+ */
+export declare function parseProviderURI(uri: string): {
+    provider: string | null;
+    path: string;
+};
+/**
+ * Validate a secret path for safety.
+ * Rejects traversal attempts, overly long paths, and empty paths.
+ *
+ * @throws SecretError with INVALID_PATH code on validation failure
+ */
+export declare function validateSecretPath(secretPath: string): void;
+//# sourceMappingURL=types.d.ts.map

package/dist/providers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;GAGG;AACH,oBAAY,eAAe;IACzB,4DAA4D;IAC5D,eAAe,oBAAoB;IACnC,qEAAqE;IACrE,SAAS,cAAc;IACvB,8DAA8D;IAC9D,WAAW,gBAAgB;IAC3B,2DAA2D;IAC3D,aAAa,kBAAkB;IAC/B,oDAAoD;IACpD,oBAAoB,yBAAyB;IAC7C,iEAAiE;IACjE,YAAY,iBAAiB;IAC7B,4BAA4B;IAC5B,WAAW,gBAAgB;IAC3B,oCAAoC;IACpC,YAAY,iBAAiB;IAC7B,4CAA4C;IAC5C,YAAY,iBAAiB;IAC7B,6BAA6B;IAC7B,QAAQ,aAAa;CACtB;AAED;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAG3B,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE;CAQtE;AAID;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEhD;;;;OAIG;IACH,SAAS,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvD;;OAEG;IACH,YAAY,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3C;;OAEG;IACH,WAAW,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjD;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,cAAc,KAAK,eAAe,CAAC;AAW1E;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAgDvF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CA8B3D"}

package/dist/providers/types.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Secrets Provider Plugin Interface
+ *
+ * Defines the contract all secrets providers must implement.
+ * See RFC 0005 for full design: docs/rfcs/0005-plugin-architecture.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretError = exports.SecretErrorCode = void 0;
+exports.parseProviderURI = parseProviderURI;
+exports.validateSecretPath = validateSecretPath;
+// --- Error Taxonomy --------------------------------------
+/**
+ * Error codes for categorizing secrets operation failures.
+ * Enables callers to handle errors programmatically without message matching.
+ */
+var SecretErrorCode;
+(function (SecretErrorCode) {
+    /** Provider is not initialized (call initialize() first) */
+    SecretErrorCode["NOT_INITIALIZED"] = "NOT_INITIALIZED";
+    /** Secret was not found (normal -- not an error for most callers) */
+    SecretErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    /** Authentication failure (bad credentials, expired token) */
+    SecretErrorCode["AUTH_FAILED"] = "AUTH_FAILED";
+    /** Permission denied (authenticated but not authorized) */
+    SecretErrorCode["ACCESS_DENIED"] = "ACCESS_DENIED";
+    /** Provider unreachable (network error, timeout) */
+    SecretErrorCode["PROVIDER_UNAVAILABLE"] = "PROVIDER_UNAVAILABLE";
+    /** Secret path is invalid (traversal attempt, bad characters) */
+    SecretErrorCode["INVALID_PATH"] = "INVALID_PATH";
+    /** URI format is invalid */
+    SecretErrorCode["INVALID_URI"] = "INVALID_URI";
+    /** Encryption/decryption failure */
+    SecretErrorCode["CRYPTO_ERROR"] = "CRYPTO_ERROR";
+    /** Provider-specific configuration error */
+    SecretErrorCode["CONFIG_ERROR"] = "CONFIG_ERROR";
+    /** Generic internal error */
+    SecretErrorCode["INTERNAL"] = "INTERNAL";
+})(SecretErrorCode || (exports.SecretErrorCode = SecretErrorCode = {}));
+/**
+ * Typed error for secrets operations.
+ * Enables programmatic error handling without message parsing.
+ */
+class SecretError extends Error {
+    code;
+    provider;
+    secretPath;
+    constructor(code, message, options) {
+        super(message, options?.cause ? { cause: options.cause } : undefined);
+        this.name = 'SecretError';
+        this.code = code;
+        this.provider = options?.provider;
+        this.secretPath = options?.secretPath;
+    }
+}
+exports.SecretError = SecretError;
+// --- URI Parsing -----------------------------------------
+/** Maximum length of a provider name */
+const MAX_PROVIDER_NAME_LENGTH = 64;
+/** Maximum length of a secret path */
+const MAX_SECRET_PATH_LENGTH = 1024;
+/** Valid provider name: lowercase alphanumeric, hyphens, underscores, 1-64 chars */
+const PROVIDER_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+/**
+ * Parse a provider URI like "vault://mcp/stripe/api-key"
+ * Returns { provider: "vault", path: "mcp/stripe/api-key" }
+ * If no scheme, returns { provider: null, path: original }
+ *
+ * Enforces:
+ *   - Provider names normalized to lowercase, 1-64 chars
+ *   - Percent-decoding of path components
+ *   - Rejection of ".." path segments (traversal prevention)
+ *   - Max path length of 1024 characters
+ *
+ * @throws SecretError with INVALID_URI code on validation failure
+ */
+function parseProviderURI(uri) {
+    if (!uri || typeof uri !== 'string') {
+        throw new SecretError(SecretErrorCode.INVALID_URI, 'URI must be a non-empty string');
+    }
+    const match = uri.match(/^([a-zA-Z][a-zA-Z0-9_-]*):\/\/(.+)$/);
+    if (!match) {
+        // Plain path -- validate and return
+        validateSecretPath(uri);
+        return { provider: null, path: uri };
+    }
+    const rawProvider = match[1];
+    const rawPath = match[2];
+    // Normalize provider name to lowercase
+    const provider = rawProvider.toLowerCase();
+    // Validate provider name length
+    if (provider.length > MAX_PROVIDER_NAME_LENGTH) {
+        throw new SecretError(SecretErrorCode.INVALID_URI, `Provider name exceeds maximum length of ${MAX_PROVIDER_NAME_LENGTH} characters: "${provider}"`);
+    }
+    // Validate provider name format
+    if (!PROVIDER_NAME_PATTERN.test(provider)) {
+        throw new SecretError(SecretErrorCode.INVALID_URI, `Invalid provider name "${provider}": must be lowercase alphanumeric with hyphens/underscores, starting with a letter`);
+    }
+    // Percent-decode the path
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(rawPath);
+    }
+    catch {
+        throw new SecretError(SecretErrorCode.INVALID_URI, `Invalid percent-encoding in URI path: "${rawPath}"`);
+    }
+    validateSecretPath(decodedPath);
+    return { provider, path: decodedPath };
+}
+/**
+ * Validate a secret path for safety.
+ * Rejects traversal attempts, overly long paths, and empty paths.
+ *
+ * @throws SecretError with INVALID_PATH code on validation failure
+ */
+function validateSecretPath(secretPath) {
+    if (!secretPath || secretPath.length === 0) {
+        throw new SecretError(SecretErrorCode.INVALID_PATH, 'Secret path must not be empty');
+    }
+    if (secretPath.length > MAX_SECRET_PATH_LENGTH) {
+        throw new SecretError(SecretErrorCode.INVALID_PATH, `Secret path exceeds maximum length of ${MAX_SECRET_PATH_LENGTH} characters`);
+    }
+    // Reject absolute paths
+    if (secretPath.startsWith('/') || /^[A-Za-z]:/.test(secretPath)) {
+        throw new SecretError(SecretErrorCode.INVALID_PATH, `Secret path must be relative, got: "${secretPath}"`);
+    }
+    // Reject ".." segments (path traversal)
+    const segments = secretPath.split(/[/\\]/);
+    for (const segment of segments) {
+        if (segment === '..') {
+            throw new SecretError(SecretErrorCode.INVALID_PATH, `Secret path must not contain ".." segments: "${secretPath}"`);
+        }
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@true-and-useful/janee",
   "mcpName": "io.github.rsdouglas/janee",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "Secrets management for AI agents via MCP",
   "main": "dist/index.js",
   "bin": {