fix: URL-encode special characters in connection string passwords

Fixes #589 — stored passwords with special characters (`@`, `#`, `:`, `/`)
cause cryptic authentication failures when used in URI-style connection
strings because the userinfo section wasn't being percent-encoded.

Root cause:
- `sanitizeConnectionString()` existed in `normalize.ts` but was never
  wired into `normalizeConfig()` — connection strings with unencoded
  passwords went directly to drivers
- The userinfo regex split on the *first* `@` instead of the *last*, so
  passwords containing `@` were silently mis-parsed and the function
  returned early thinking no encoding was needed

Fix:
- Wire `sanitizeConnectionString()` into `normalizeConfig()` as a single
  integration point so every URI-based driver benefits automatically
- Fix the regex to use greedy matching for the userinfo portion and
  split on the last `@` before the host
- Leave already-encoded passwords (`%XX` sequences) untouched for
  idempotency; decodeURIComponent wrapped in try/catch for safety

Non-URI connection strings (Oracle TNS, key=value) and drivers using
individual config fields (host/user/password) are unaffected — the
fix only touches `connection_string`.

Tests cover @/#/:/ in passwords, already-encoded passthrough, multiple
URI schemes (postgresql://, mongodb://, mongodb+srv://), and the
connectionString alias path.

Author: VJ-yadav

packages/drivers/src/index.ts

@@ -2,7 +2,7 @@
 export type { Connector, ConnectorResult, SchemaColumn, ConnectionConfig } from "./types"
 
 // Re-export config normalization
-export { normalizeConfig } from "./normalize"
+export { normalizeConfig, sanitizeConnectionString } from "./normalize"
 
 // Re-export driver connect functions
 export { connect as connectPostgres } from "./postgres"

packages/drivers/src/normalize.ts

@@ -111,6 +111,67 @@ const DRIVER_ALIASES: Record<string, AliasMap> = {
   // duckdb and sqlite have simple configs — no aliases needed
 }
 
+// ---------------------------------------------------------------------------
+// Connection string password encoding
+// ---------------------------------------------------------------------------
+
+/**
+ * URI-style connection strings (postgres://, mongodb://, etc.) embed
+ * credentials in the userinfo section: `scheme://user:password@host/db`.
+ * If the password contains special characters (@, #, :, /, ?, etc.) and
+ * they are NOT percent-encoded, drivers will mis-parse the URI and fail
+ * with cryptic auth errors.
+ *
+ * This function detects an unencoded password in the userinfo portion and
+ * re-encodes it so the connection string is valid.  Already-encoded
+ * passwords (containing %XX sequences) are left untouched.
+ */
+export function sanitizeConnectionString(connectionString: string): string {
+  // Match scheme://userinfo@host... — we only touch the userinfo part.
+  // Schemes: postgresql, postgres, mongodb, mongodb+srv, clickhouse, http, https, redshift
+  //
+  // IMPORTANT: The password itself may contain '@' characters, so we must
+  // split on the LAST '@' before the host portion.  The regex below uses a
+  // greedy (.+) for userinfo so it consumes everything up to the final '@'.
+  const uriMatch = connectionString.match(
+    /^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)(.+)@([^@]+)$/,
+  )
+  if (!uriMatch) return connectionString // No userinfo section — nothing to fix
+
+  const [, scheme, userinfo, rest] = uriMatch
+
+  // Split userinfo into user:password on the FIRST colon only
+  const colonIdx = userinfo.indexOf(":")
+  if (colonIdx < 0) return connectionString // No password in userinfo
+
+  const user = userinfo.slice(0, colonIdx)
+  const password = userinfo.slice(colonIdx + 1)
+
+  // If the password already contains percent-encoded sequences, assume
+  // the caller encoded it properly and leave it alone.
+  if (/%[0-9A-Fa-f]{2}/.test(password)) return connectionString
+
+  // Check if the password contains characters that need encoding.
+  // RFC 3986 unreserved: A-Z a-z 0-9 - . _ ~
+  // We also allow ! * ' ( ) which are sub-delimiters often safe in passwords.
+  // Everything else (especially @ : / ? # [ ]) MUST be encoded.
+  const needsEncoding = /[@:#/?[\]%]/.test(password)
+  if (!needsEncoding) return connectionString
+
+  // Re-encode both user and password to be safe.
+  // decodeURIComponent can throw on malformed percent sequences — fall back to
+  // encoding the raw value if that happens.
+  let encodedUser: string
+  try {
+    encodedUser = encodeURIComponent(decodeURIComponent(user))
+  } catch {
+    encodedUser = encodeURIComponent(user)
+  }
+  const encodedPassword = encodeURIComponent(password)
+
+  return `${scheme}${encodedUser}:${encodedPassword}@${rest}`
+}
+
 // ---------------------------------------------------------------------------
 // Core logic
 // ---------------------------------------------------------------------------
@@ -178,6 +239,15 @@ export function normalizeConfig(config: ConnectionConfig): ConnectionConfig {
   const aliases = DRIVER_ALIASES[type]
   let result = aliases ? applyAliases(config, aliases) : { ...config }
 
+  // Sanitize connection_string: if the password contains special characters
+  // (@, #, :, /, etc.) that are not percent-encoded, URI-based drivers will
+  // mis-parse the string and fail with cryptic auth errors.  This is the
+  // single integration point — every caller of normalizeConfig() gets the
+  // fix automatically.
+  if (typeof result.connection_string === "string") {
+    result.connection_string = sanitizeConnectionString(result.connection_string)
+  }
+
   // Type-specific post-processing
   // Note: MySQL SSL fields (ssl_ca, ssl_cert, ssl_key) are NOT constructed
   // into an ssl object here. They stay as top-level fields so the credential

packages/opencode/test/altimate/driver-normalize.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test"
-import { normalizeConfig } from "@altimateai/drivers"
+import { normalizeConfig, sanitizeConnectionString } from "@altimateai/drivers"
 import { isSensitiveField } from "../../src/altimate/native/connections/credential-store"
 
 // ---------------------------------------------------------------------------
@@ -947,3 +947,133 @@ describe("normalizeConfig — ClickHouse", () => {
     expect(result.ssl_key).toBeUndefined()
   })
 })
+
+// ---------------------------------------------------------------------------
+// sanitizeConnectionString — special character encoding
+// ---------------------------------------------------------------------------
+
+describe("sanitizeConnectionString", () => {
+  test("encodes @ in password", () => {
+    const input = "postgresql://testuser:t@st@localhost:5432/testdb"
+    const result = sanitizeConnectionString(input)
+    expect(result).toBe("postgresql://testuser:t%40st@localhost:5432/testdb")
+  })
+
+  test("encodes # in password", () => {
+    const input = "postgresql://testuser:test#val@localhost:5432/testdb"
+    const result = sanitizeConnectionString(input)
+    expect(result).toBe("postgresql://testuser:test%23val@localhost:5432/testdb")
+  })
+
+  test("encodes : in password", () => {
+    const input = "postgresql://testuser:test:val@localhost:5432/testdb"
+    const result = sanitizeConnectionString(input)
+    expect(result).toBe("postgresql://testuser:test%3Aval@localhost:5432/testdb")
+  })
+
+  test("encodes multiple special characters", () => {
+    const input = "postgresql://testuser:t@st#v:al@localhost:5432/testdb"
+    const result = sanitizeConnectionString(input)
+    expect(result).toBe("postgresql://testuser:t%40st%23v%3Aal@localhost:5432/testdb")
+  })
+
+  test("encodes / in password", () => {
+    const input = "postgresql://testuser:test/val@localhost:5432/testdb"
+    const result = sanitizeConnectionString(input)
+    expect(result).toBe("postgresql://testuser:test%2Fval@localhost:5432/testdb")
+  })
+
+  test("encodes ? in password", () => {
+    const input = "postgresql://testuser:test?val@localhost:5432/testdb"
+    const result = sanitizeConnectionString(input)
+    expect(result).toBe("postgresql://testuser:test%3Fval@localhost:5432/testdb")
+  })
+
+  test("handles malformed percent sequence in username gracefully", () => {
+    const input = "postgresql://bad%ZZuser:t@st@localhost:5432/testdb"
+    const result = sanitizeConnectionString(input)
+    // Should not throw — falls back to encoding the raw username
+    expect(result).toContain("@localhost:5432/testdb")
+  })
+
+  test("leaves already-encoded passwords untouched", () => {
+    const input = "postgresql://testuser:t%40st%23val@localhost:5432/testdb"
+    expect(sanitizeConnectionString(input)).toBe(input)
+  })
+
+  test("leaves passwords without special characters untouched", () => {
+    const input = "postgresql://testuser:simpletestval@localhost:5432/testdb"
+    expect(sanitizeConnectionString(input)).toBe(input)
+  })
+
+  test("leaves non-URI strings untouched", () => {
+    const input = "host=localhost dbname=mydb"
+    expect(sanitizeConnectionString(input)).toBe(input)
+  })
+
+  test("handles mongodb scheme", () => {
+    const input = "mongodb://testuser:t@st@localhost:27017/testdb"
+    const result = sanitizeConnectionString(input)
+    expect(result).toBe("mongodb://testuser:t%40st@localhost:27017/testdb")
+  })
+
+  test("handles mongodb+srv scheme", () => {
+    const input = "mongodb+srv://testuser:t@st@cluster.example.com/testdb"
+    const result = sanitizeConnectionString(input)
+    expect(result).toBe("mongodb+srv://testuser:t%40st@cluster.example.com/testdb")
+  })
+
+  test("leaves URIs without password untouched", () => {
+    const input = "postgresql://testuser@localhost:5432/testdb"
+    expect(sanitizeConnectionString(input)).toBe(input)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// normalizeConfig — connection_string sanitization integration
+// ---------------------------------------------------------------------------
+
+describe("normalizeConfig — connection_string sanitization", () => {
+  test("sanitizes connection_string with special chars in password", () => {
+    const result = normalizeConfig({
+      type: "postgres",
+      connection_string: "postgresql://testuser:f@ke#PLACEHOLDER@localhost:5432/testdb",
+    })
+    expect(result.connection_string).toBe(
+      "postgresql://testuser:f%40ke%23PLACEHOLDER@localhost:5432/testdb",
+    )
+  })
+
+  test("sanitizes connectionString alias with special chars", () => {
+    const result = normalizeConfig({
+      type: "postgres",
+      connectionString: "postgresql://testuser:t@st@localhost:5432/testdb",
+    })
+    // alias resolved to connection_string, then sanitized
+    expect(result.connection_string).toBe(
+      "postgresql://testuser:t%40st@localhost:5432/testdb",
+    )
+    expect(result.connectionString).toBeUndefined()
+  })
+
+  test("does not alter connection_string without special chars", () => {
+    const result = normalizeConfig({
+      type: "redshift",
+      connection_string: "postgresql://testuser:testval@localhost:5439/testdb",
+    })
+    expect(result.connection_string).toBe(
+      "postgresql://testuser:testval@localhost:5439/testdb",
+    )
+  })
+
+  test("does not alter config without connection_string", () => {
+    const result = normalizeConfig({
+      type: "postgres",
+      host: "localhost",
+      password: "f@ke#PLACEHOLDER",
+    })
+    // Individual fields are NOT URI-encoded — drivers handle them natively
+    expect(result.password).toBe("f@ke#PLACEHOLDER")
+    expect(result.connection_string).toBeUndefined()
+  })
+})