@true-and-useful/janee 0.8.3 → 0.8.5

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.3",
+  "version": "0.8.5",
   "description": "Secrets management for AI agents via MCP",
   "main": "dist/index.js",
   "bin": {