@fadhilp/stateql 0.4.0 → 0.4.2

package/README.md

@@ -64,7 +64,9 @@ Example first page:
 Running the same normalized query with the same parameters reuses `q_1` while
 its cache is valid. Use `--cache bypass` when a fresh read is required.
 
-PostgreSQL and MySQL credentials should come from environment variables:
+PostgreSQL and MySQL credentials should come from environment variables. The
+variable must contain the complete connection URL, not only its password.
+Environment-backed SQLite paths require an explicit `sqlite:` prefix.
 
 ```bash
 export APP_DATABASE_URL='postgres://user:password@host/app'
@@ -72,15 +74,25 @@ stql connect --env APP_DATABASE_URL --name app --read-only
 
 export MYSQL_DATABASE_URL='mysql://user:password@host/app'
 stql connect --env MYSQL_DATABASE_URL --name mysql-app --read-only
+
+export SQLITE_DATABASE='sqlite:./app.sqlite'
+stql connect --env SQLITE_DATABASE --name local --read-only
 ```
 
+A connection accepts exactly one direct target, `--env`, or `--profile` source.
+For PostgreSQL, StateQL preserves strict TLS verification by normalizing
+`sslmode=prefer`, `require`, and `verify-ca` to `verify-full` before opening the
+adapter. Use `sslmode=verify-full` explicitly for clarity. Setting
+`uselibpqcompat=true` opts out and keeps libpq-compatible SSL semantics.
+
 MySQL uses positional `?` parameters. MariaDB compatibility is not currently
 claimed.
 
 ## Commands
 
 ```text
-stql connect <sqlite-path|postgres-url|mysql-url> [--name NAME] [--env ENV] [--read-write]
+stql connect <sqlite-path|postgres-url|mysql-url> [--name NAME] [--read-write]
+stql connect --env ENV [--name NAME] [--read-write]
 stql connect --profile NAME
 stql status
 stql profile add|list|show|remove
@@ -301,8 +313,10 @@ secret-free failures. Unknown resolver errors are replaced with a generic
 StateQL calls the resolver only immediately before database access, after SQL
 safety and duplicate checks. Requests contain actor/session identity, the
 operation's effective read/write access, an abort signal, and sanitized
-connection metadata. Returned values are passed directly to the adapter.
-Credential-bearing PostgreSQL and MySQL URLs are redacted before connection
+connection metadata. Returned values must be complete PostgreSQL/MySQL URLs or
+explicit `sqlite:` sources. StateQL validates the source and its stored driver
+before adapter construction, and normalizes SQLite paths. Credential-bearing
+PostgreSQL and MySQL URLs are redacted before connection
 metadata is persisted and never enter history, snapshots, cache keys, or
 responses. SQLite paths remain persisted connection metadata, as they are for
 direct SQLite connections. Harnesses remain responsible for approval policy,

package/dist/src/adapters.d.ts

@@ -37,3 +37,4 @@ export declare function createAdapterContext(timeoutMs: number, signal?: AbortSi
 export declare function createAdapter(connection: ConnectionRecord, context: AdapterContext, input: {
     source: string;
 }): Promise<Adapter>;
+export declare function normalizePostgresConnectionString(source: string): string;

package/dist/src/adapters.js

@@ -182,6 +182,23 @@ class SQLiteAdapter {
         this.pending.clear();
     }
 }
+const STRICT_POSTGRES_SSL_MODE_ALIASES = new Set(["prefer", "require", "verify-ca"]);
+export function normalizePostgresConnectionString(source) {
+    try {
+        const url = new URL(source);
+        const parameters = [...url.searchParams.entries()];
+        const libpqCompat = parameters.filter(([key]) => key === "uselibpqcompat").at(-1)?.[1];
+        const sslMode = parameters.filter(([key]) => key === "sslmode").at(-1)?.[1];
+        if (libpqCompat === "true" || !sslMode || !STRICT_POSTGRES_SSL_MODE_ALIASES.has(sslMode))
+            return source;
+        url.searchParams.delete("sslmode");
+        url.searchParams.append("sslmode", "verify-full");
+        return url.toString();
+    }
+    catch {
+        return source;
+    }
+}
 class PostgresAdapter {
     readOnly;
     context;
@@ -194,7 +211,7 @@ class PostgresAdapter {
         this.context = context;
         const timeout = Math.min(2_147_483_647, remainingMilliseconds(context));
         this.client = new Client({
-            connectionString: source,
+            connectionString: normalizePostgresConnectionString(source),
             connectionTimeoutMillis: timeout,
             statement_timeout: timeout,
         });

package/dist/src/connection.d.ts

@@ -2,6 +2,10 @@ import type { ConnectionRecord } from "./store.js";
 import type { Driver, StateConfidence } from "./types.js";
 export declare function databaseIdentity(connection: ConnectionRecord): unknown;
 export declare function detectDriver(target: string): Driver;
+export declare function credentialSource(value: string, expectedDriver?: Driver): {
+    driver: Driver;
+    source: string;
+};
 export declare function normalizeSqliteSource(target: string): string;
 export declare function databaseUrlHasSecret(target: string): boolean;
 export declare function version(connection: ConnectionRecord): string;

package/dist/src/connection.js

@@ -18,8 +18,34 @@ export function detectDriver(target) {
     }
     return "sqlite";
 }
+export function credentialSource(value, expectedDriver) {
+    const explicitSqlite = /^sqlite:(?!\/\/)/i.test(value);
+    const driver = explicitSqlite ? "sqlite" : detectDriver(value);
+    if (driver === "sqlite" && (!explicitSqlite || value.length === 7)) {
+        throw new StateQLError("INVALID_COMMAND", "Secret environment variable must contain a complete PostgreSQL/MySQL URL or an explicit sqlite: source.", {
+            suggestedAction: "Store the full database URL, or prefix an SQLite path with sqlite:.",
+        });
+    }
+    if (driver !== "sqlite") {
+        try {
+            const url = new URL(value);
+            if (!url.hostname && !url.pathname.replaceAll("/", ""))
+                throw new Error();
+        }
+        catch {
+            throw new StateQLError("INVALID_COMMAND", "Secret environment variable must contain a valid database URL.");
+        }
+    }
+    if (expectedDriver && driver !== expectedDriver) {
+        throw new StateQLError("INVALID_COMMAND", "Resolved credential driver does not match the selected database connection.");
+    }
+    return {
+        driver,
+        source: driver === "sqlite" ? normalizeSqliteSource(value) : value,
+    };
+}
 export function normalizeSqliteSource(target) {
-    const source = target.startsWith("sqlite:") ? target.slice(7) : target;
+    const source = target.replace(/^sqlite:/i, "");
     if (source === ":memory:") {
         throw new StateQLError("INVALID_COMMAND", "SQLite :memory: databases cannot persist across StateQL commands.");
     }

package/dist/src/stateql.js

@@ -2,7 +2,7 @@ import { writeFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { env } from "node:process";
 import { AdapterExecutionError, AdapterWriteError, BatchWriteError, createAdapter, createAdapterContext, } from "./adapters.js";
-import { confidence, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, normalizeSqliteSource, validateProfileName, version, } from "./connection.js";
+import { confidence, credentialSource, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, normalizeSqliteSource, validateProfileName, version, } from "./connection.js";
 import { asStateQLError, CredentialResolutionError, StateQLError, } from "./errors.js";
 import { filterMaterializedRows, prepareFilterStatement, validateFilterParameters, } from "./filter.js";
 import { operationData, paginationWarnings, profileData, rowsToCsv, sessionData, transactionData, } from "./response-data.js";
@@ -72,8 +72,10 @@ export class StateQL {
             if (session.active_transaction_id) {
                 throw new StateQLError("TRANSACTION_FAILED", "Commit or roll back the active transaction before connecting again.");
             }
-            if (options.profile && target) {
-                throw new StateQLError("INVALID_COMMAND", "Use either a profile or a connection target, not both.");
+            const sourceCount = [target, options.profile, options.secretEnv]
+                .filter((value) => value !== undefined).length;
+            if (sourceCount > 1) {
+                throw new StateQLError("INVALID_COMMAND", "Use exactly one connection target, profile, or secret environment variable.");
             }
             const implicitProfile = !options.profile && !options.secretEnv && target
                 ? this.store.getProfile(target)
@@ -101,7 +103,10 @@ export class StateQL {
             if (!secret) {
                 throw new StateQLError("INVALID_COMMAND", "Connection target is required.");
             }
-            const driver = detectDriver(secret);
+            const resolvedSource = secretEnv
+                ? credentialSource(secret)
+                : { driver: detectDriver(secret), source: secret };
+            const { driver } = resolvedSource;
             if (driver !== "sqlite" &&
                 !secretEnv &&
                 databaseUrlHasSecret(secret)) {
@@ -109,7 +114,9 @@ export class StateQL {
                     suggestedAction: "Set the URL in an environment variable and reconnect with --env NAME.",
                 });
             }
-            const adapterSource = driver === "sqlite" ? normalizeSqliteSource(secret) : secret;
+            const adapterSource = secretEnv
+                ? resolvedSource.source
+                : driver === "sqlite" ? normalizeSqliteSource(secret) : secret;
             const source = driver === "sqlite"
                 ? adapterSource
                 : secretEnv
@@ -1508,7 +1515,7 @@ export class StateQL {
     async resolveConnectionSource(connection, session, operation, access, context) {
         if (!connection.secret_env)
             return connection.source;
-        return this.resolveCredential(connection.secret_env, session, operation, access, context, {
+        const value = await this.resolveCredential(connection.secret_env, session, operation, access, context, {
             connection: {
                 id: connection.id,
                 name: connection.name,
@@ -1517,6 +1524,7 @@ export class StateQL {
                 readOnly: Boolean(connection.read_only),
             },
         });
+        return credentialSource(value, connection.driver).source;
     }
     async resolveCredential(reference, session, operation, access, context, details = {}) {
         const resolver = this.credentialResolver;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Stateful, agent-oriented database CLI for safe result reuse",
   "repository": {
     "type": "git",