@fadhilp/stateql 0.3.1 → 0.4.1

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,20 @@ 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.
 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
@@ -257,6 +264,65 @@ if (response.ok) {
 }
 ```
 
+### Harness credential resolution
+
+Library integrations can resolve a profile's credential reference through a
+trusted approval or secret-storage layer instead of mutating `process.env`:
+
+```ts
+import {
+  CredentialResolutionError,
+  StateQL,
+  type CredentialRequest,
+} from "@fadhilp/stateql";
+
+async function resolveCredential(
+  request: CredentialRequest,
+): Promise<string | undefined> {
+  const approved = await credentialBroker.request({
+    reference: request.reference,
+    actor: request.actorId,
+    session: request.session.id,
+    operation: request.operation,
+    access: request.access,
+    signal: request.signal,
+  });
+  if (approved.denied) throw new CredentialResolutionError("denied");
+  return approved.value;
+}
+
+const stateql = StateQL.forActor({
+  actor: "agent-session-id",
+  credentialResolver: resolveCredential,
+});
+```
+
+When no custom resolver is configured, StateQL continues to read references
+from `process.env`. A configured resolver is authoritative: returning
+`undefined` produces `CREDENTIAL_UNAVAILABLE` and never falls back to the
+process environment. Resolvers may throw `CredentialResolutionError` with
+`denied`, `cancelled`, `timeout`, or `unavailable` to produce controlled,
+secret-free failures. Unknown resolver errors are replaced with a generic
+`CREDENTIAL_RESOLUTION_FAILED` response.
+
+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 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,
+binding lifetime, revocation, and keeping values out of their own logs and
+model-visible data.
+
+For writes, credential resolution happens after StateQL atomically reserves the
+operation for duplicate protection. A resolution failure keeps a non-executed
+`failed` audit record, does not consume the idempotency key, and permits a safe
+retry.
+
 `StateQL.forActor(...)` resolves the actor's attached session directly from
 StateQL storage, avoiding a duplicate actor-to-session mapping in integrations.
 On first use, it creates a legacy-compatible session named after the actor.

package/dist/src/adapters.d.ts

@@ -34,4 +34,6 @@ export interface Adapter {
     close(): Promise<void>;
 }
 export declare function createAdapterContext(timeoutMs: number, signal?: AbortSignal): AdapterContext;
-export declare function createAdapter(connection: ConnectionRecord, context: AdapterContext): Promise<Adapter>;
+export declare function createAdapter(connection: ConnectionRecord, context: AdapterContext, input: {
+    source: string;
+}): Promise<Adapter>;

package/dist/src/adapters.js

@@ -34,13 +34,8 @@ export function createAdapterContext(timeoutMs, signal) {
         ...(signal ? { signal } : {}),
     };
 }
-export async function createAdapter(connection, context) {
-    const source = connection.secret_env
-        ? process.env[connection.secret_env]
-        : connection.source;
-    if (!source) {
-        throw new Error(`Environment variable ${connection.secret_env ?? "(missing)"} is not set.`);
-    }
+export async function createAdapter(connection, context, input) {
+    const { source } = input;
     if (connection.driver === "sqlite") {
         return new SQLiteAdapter(source, Boolean(connection.read_only), context);
     }

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/errors.d.ts

@@ -1,4 +1,9 @@
 import type { StateQLErrorShape } from "./types.js";
+export type CredentialResolutionFailure = "unavailable" | "denied" | "cancelled" | "timeout";
+export declare class CredentialResolutionError extends Error {
+    readonly reason: CredentialResolutionFailure;
+    constructor(reason: CredentialResolutionFailure);
+}
 export declare class StateQLError extends Error {
     readonly details: StateQLErrorShape;
     constructor(code: string, message: string, options?: {

package/dist/src/errors.js

@@ -1,3 +1,11 @@
+export class CredentialResolutionError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Credential resolution ${reason}.`);
+        this.reason = reason;
+        this.name = "CredentialResolutionError";
+    }
+}
 export class StateQLError extends Error {
     details;
     constructor(code, message, options = {}) {
@@ -18,7 +26,7 @@ export class StateQLError extends Error {
 export function exitCodeFor(code) {
     if (code === "INVALID_COMMAND" || code === "INVALID_SQL")
         return 2;
-    if (code.startsWith("CONNECTION_"))
+    if (code.startsWith("CONNECTION_") || code.startsWith("CREDENTIAL_"))
         return 3;
     if (code === "QUERY_FAILED" ||
         code === "DEADLINE_EXCEEDED" ||

package/dist/src/index.d.ts

@@ -1,3 +1,4 @@
 export { StateQL } from "./stateql.js";
-export { StateQLError, exitCodeFor } from "./errors.js";
-export type { BatchCommand, BatchCommandName, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, Failure, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, SqlParameters, StateQLActorOptions, StateQLOptions, StateQLSnapshot, Success, } from "./types.js";
+export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
+export type { CredentialResolutionFailure } from "./errors.js";
+export type { BatchCommand, BatchCommandName, BatchOptions, ConnectOptions, CredentialAccess, CredentialOperation, CredentialRequest, CredentialResolver, ExecOptions, ExecutionOptions, Failure, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, SqlParameters, StateQLActorOptions, StateQLOptions, StateQLSnapshot, Success, } from "./types.js";

package/dist/src/index.js

@@ -1,2 +1,2 @@
 export { StateQL } from "./stateql.js";
-export { StateQLError, exitCodeFor } from "./errors.js";
+export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";

package/dist/src/stateql.d.ts

@@ -12,6 +12,7 @@ export declare class StateQL {
     private readonly maxResultBytes;
     private readonly timeoutMs;
     private readonly signal?;
+    private readonly credentialResolver?;
     private readonly now;
     constructor(options?: StateQLOptions);
     close(): void;
@@ -67,6 +68,9 @@ export declare class StateQL {
     private requireSelectedSession;
     private validateActorId;
     private throwMembershipDenied;
+    private resolveConnectionSource;
+    private resolveCredential;
+    private openAdapter;
     private executionContext;
     private resultData;
     private cacheValid;

package/dist/src/stateql.js

@@ -2,8 +2,8 @@ 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 { asStateQLError, StateQLError } from "./errors.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";
 import { analyzeSql } from "./sql.js";
@@ -40,6 +40,7 @@ export class StateQL {
     maxResultBytes;
     timeoutMs;
     signal;
+    credentialResolver;
     now;
     constructor(options = {}) {
         this.now = options.now ?? (() => new Date());
@@ -56,6 +57,7 @@ export class StateQL {
         this.maxResultBytes = positiveInteger(options.maxResultBytes ?? 16 * 1024 * 1024, "maxResultBytes");
         this.timeoutMs = executionTimeout(options.timeoutMs ?? 30_000);
         this.signal = options.signal;
+        this.credentialResolver = options.credentialResolver;
         if (this.maxResultRows >= Number.MAX_SAFE_INTEGER) {
             throw new StateQLError("INVALID_COMMAND", "maxResultRows is too large.");
         }
@@ -70,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)
@@ -84,13 +88,25 @@ export class StateQL {
             }
             const resolvedTarget = profile?.target ?? target;
             const secretEnv = options.secretEnv ?? profile?.secret_env ?? undefined;
-            const secret = secretEnv ? env[secretEnv] : resolvedTarget;
+            if (secretEnv && !isEnvironmentName(secretEnv)) {
+                throw new StateQLError("INVALID_COMMAND", "Secret environment variable name is invalid.");
+            }
+            const readOnly = options.readOnly ??
+                (profile ? Boolean(profile.read_only) : true);
+            const context = this.executionContext(options);
+            const secret = secretEnv
+                ? await this.resolveCredential(secretEnv, session, "connect", readOnly ? "read" : "write", context, {
+                    ...(profile ? { profile: { name: profile.name } } : {}),
+                    requestedReadOnly: readOnly,
+                })
+                : resolvedTarget;
             if (!secret) {
-                throw new StateQLError("INVALID_COMMAND", secretEnv
-                    ? `Environment variable ${secretEnv} is not set.`
-                    : "Connection target is required.");
+                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)) {
@@ -98,16 +114,17 @@ export class StateQL {
                     suggestedAction: "Set the URL in an environment variable and reconnect with --env NAME.",
                 });
             }
+            const adapterSource = secretEnv
+                ? resolvedSource.source
+                : driver === "sqlite" ? normalizeSqliteSource(secret) : secret;
             const source = driver === "sqlite"
-                ? normalizeSqliteSource(secret)
+                ? adapterSource
                 : secretEnv
                     ? redact(secret)
-                    : secret;
+                    : adapterSource;
             const databaseName = driver === "sqlite"
-                ? basename(source)
+                ? basename(adapterSource)
                 : new URL(secret).pathname.replace(/^\//, "") || driver;
-            const readOnly = options.readOnly ??
-                (profile ? Boolean(profile.read_only) : true);
             const draft = {
                 id: "pending",
                 session_id: session.id,
@@ -120,7 +137,7 @@ export class StateQL {
                 version: 0,
                 created_at: this.now().toISOString(),
             };
-            const adapter = await createAdapter(draft, this.executionContext(options));
+            const adapter = await this.openAdapter(draft, context, adapterSource);
             try {
                 await adapter.read("SELECT 1", []);
             }
@@ -128,10 +145,10 @@ export class StateQL {
                 if (error instanceof AdapterExecutionError) {
                     throw stoppedStateQLError(error, false);
                 }
-                throw new StateQLError("CONNECTION_FAILED", errorMessage(error), { retryable: true });
+                throw new StateQLError("CONNECTION_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true });
             }
             finally {
-                await adapter.close();
+                await closeAdapterQuietly(adapter);
             }
             const connection = this.store.addConnection({
                 sessionId: session.id,
@@ -498,7 +515,9 @@ export class StateQL {
                 throw new StateQLError("INVALID_SQL", "query accepts read statements only; use exec for writes.");
             }
             const parameters = options.params ?? [];
-            const adapter = await createAdapter(connection, this.executionContext(options));
+            const context = this.executionContext(options);
+            const adapterSource = await this.resolveConnectionSource(connection, session, "query", "read", context);
+            const adapter = await this.openAdapter(connection, context, adapterSource);
             try {
                 const stateVersion = version(connection);
                 const stateSignature = await adapter.signature();
@@ -571,13 +590,13 @@ export class StateQL {
                 if (error instanceof AdapterExecutionError) {
                     throw stoppedStateQLError(error, true);
                 }
-                throw new StateQLError("QUERY_FAILED", errorMessage(error), {
+                throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), {
                     retryable: true,
                     executed: true,
                 });
             }
             finally {
-                await adapter.close();
+                await closeAdapterQuietly(adapter);
             }
         });
     }
@@ -792,7 +811,9 @@ export class StateQL {
             if (version(connection) !== transaction.start_version) {
                 throw new StateQLError("TRANSACTION_FAILED", "Connection state changed after the transaction began.", { suggestedAction: "Roll back and begin a new transaction." });
             }
-            const adapter = await createAdapter(connection, this.executionContext(options));
+            const context = this.executionContext(options);
+            const adapterSource = await this.resolveConnectionSource(connection, session, "transaction.commit", "write", context);
+            const adapter = await this.openAdapter(connection, context, adapterSource);
             try {
                 if (!this.store.markTransactionCommitting(transaction.id, session.id, this.actorId)) {
                     throw new StateQLError("TRANSACTION_FAILED", "Transaction is no longer active.");
@@ -813,12 +834,10 @@ export class StateQL {
                         if (error instanceof AdapterExecutionError) {
                             throw stoppedStateQLError(error, false);
                         }
-                        throw new StateQLError("TRANSACTION_FAILED", error.message, {
-                            retryable: true,
-                        });
+                        throw new StateQLError("TRANSACTION_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true });
                     }
                     markTransactionOutcomeUnknown(this.store, transaction.id, session.id, this.actorId);
-                    throw new StateQLError("OUTCOME_UNKNOWN", errorMessage(error), {
+                    throw new StateQLError("OUTCOME_UNKNOWN", safeCredentialErrorMessage(error, adapterSource), {
                         executed: true,
                         suggestedAction: "Inspect database state before issuing any replacement write.",
                     });
@@ -845,7 +864,7 @@ export class StateQL {
                 }
                 catch (error) {
                     markTransactionOutcomeUnknown(this.store, transaction.id, session.id, this.actorId);
-                    throw new StateQLError("OUTCOME_UNKNOWN", errorMessage(error), {
+                    throw new StateQLError("OUTCOME_UNKNOWN", safeCredentialErrorMessage(error, adapterSource), {
                         executed: true,
                         suggestedAction: "Inspect database state before issuing any replacement write.",
                     });
@@ -897,7 +916,9 @@ export class StateQL {
         return this.run(`inspect.${kind}`, async (session) => {
             const connection = this.requireConnection(session);
             this.rejectDuringStagedTransaction(session, "Schema inspection");
-            const adapter = await createAdapter(connection, this.executionContext(options));
+            const context = this.executionContext(options);
+            const adapterSource = await this.resolveConnectionSource(connection, session, "inspect", "read", context);
+            const adapter = await this.openAdapter(connection, context, adapterSource);
             try {
                 const data = await adapter.inspect(kind, table);
                 return {
@@ -911,13 +932,13 @@ export class StateQL {
                 if (error instanceof AdapterExecutionError) {
                     throw stoppedStateQLError(error, true);
                 }
-                throw new StateQLError("QUERY_FAILED", errorMessage(error), {
+                throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), {
                     retryable: false,
                     executed: true,
                 });
             }
             finally {
-                await adapter.close();
+                await closeAdapterQuietly(adapter);
             }
         });
     }
@@ -929,7 +950,9 @@ export class StateQL {
             if (analysis.read) {
                 throw new StateQLError("INVALID_SQL", "plan accepts write statements only.");
             }
-            const adapter = await createAdapter(connection, this.executionContext(options));
+            const context = this.executionContext(options);
+            const adapterSource = await this.resolveConnectionSource(connection, session, "plan", "read", context);
+            const adapter = await this.openAdapter(connection, context, adapterSource);
             try {
                 const stateSignature = await adapter.signature();
                 const expiresAt = new Date(this.now().getTime() + 10 * 60_000).toISOString();
@@ -973,13 +996,15 @@ export class StateQL {
                 };
             }
             catch (error) {
+                if (error instanceof StateQLError)
+                    throw error;
                 if (error instanceof AdapterExecutionError) {
                     throw stoppedStateQLError(error, true);
                 }
-                throw error;
+                throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true, executed: true });
             }
             finally {
-                await adapter.close();
+                await closeAdapterQuietly(adapter);
             }
         });
     }
@@ -1014,26 +1039,29 @@ export class StateQL {
                     throw new StateQLError("STALE_PLAN", "Database state changed after this plan was created.");
                 }
                 const context = this.executionContext(options);
-                const adapter = await createAdapter(connection, context);
+                const adapterSource = await this.resolveConnectionSource(connection, session, "apply", "write", context);
+                const adapter = await this.openAdapter(connection, context, adapterSource);
                 try {
                     if ((await adapter.signature()) !== claimed.state_signature) {
                         throw new StateQLError("STALE_PLAN", "Database state changed after this plan was created.");
                     }
                 }
                 catch (error) {
+                    if (error instanceof StateQLError)
+                        throw error;
                     if (error instanceof AdapterExecutionError) {
                         throw stoppedStateQLError(error, true);
                     }
-                    throw error;
+                    throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true, executed: true });
                 }
                 finally {
-                    await adapter.close();
+                    await closeAdapterQuietly(adapter);
                 }
                 const result = await this.performExec(session, connection, claimed.sql, {
                     params: parseJson(claimed.parameters, []),
                     allowUnbounded: Boolean(claimed.allow_unbounded),
                     allowDestructive: Boolean(claimed.allow_destructive),
-                }, context, { planId: claimed.id, claimToken });
+                }, context, { planId: claimed.id, claimToken }, adapterSource);
                 return {
                     ...result,
                     data: { plan_id: claimed.id, ...result.data },
@@ -1073,6 +1101,7 @@ export class StateQL {
                     persistent_sessions: true,
                     result_filtering: true,
                     schema_inspection: true,
+                    credential_resolver: true,
                     deadlines: true,
                     cancellation: true,
                 },
@@ -1228,7 +1257,7 @@ export class StateQL {
                 return;
         }
     }
-    async performExec(session, connection, sql, options, context, planClaim) {
+    async performExec(session, connection, sql, options, context, planClaim, resolvedSource) {
         if (connection.read_only) {
             throw new StateQLError("READ_ONLY_CONNECTION", "Connection is read-only.", { suggestedAction: "Reconnect with --read-write." });
         }
@@ -1336,12 +1365,18 @@ export class StateQL {
             };
         }
         let adapter;
+        let adapterSource;
         try {
-            adapter = await createAdapter(connection, context);
+            adapterSource =
+                resolvedSource ??
+                    (await this.resolveConnectionSource(connection, session, "exec", "write", context));
+            adapter = await this.openAdapter(connection, context, adapterSource);
         }
         catch (error) {
             this.store.failOperation(operation.id);
-            throw new StateQLError("QUERY_FAILED", errorMessage(error), {
+            if (error instanceof StateQLError)
+                throw error;
+            throw new StateQLError("CONNECTION_FAILED", "Database connection failed.", {
                 retryable: true,
             });
         }
@@ -1394,12 +1429,10 @@ export class StateQL {
             }
             if (error instanceof AdapterWriteError && !error.outcomeUnknown) {
                 this.store.failOperation(operation.id);
-                throw new StateQLError("QUERY_FAILED", error.message, {
-                    executed: true,
-                });
+                throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { executed: true });
             }
             this.store.markOperationOutcomeUnknown(operation.id);
-            throw new StateQLError("OUTCOME_UNKNOWN", errorMessage(error), {
+            throw new StateQLError("OUTCOME_UNKNOWN", safeCredentialErrorMessage(error, adapterSource), {
                 executed: true,
                 suggestedAction: "Inspect database state, then use --replay only if another execution is safe.",
             });
@@ -1479,6 +1512,63 @@ export class StateQL {
     throwMembershipDenied(session) {
         throw new StateQLError("PERMISSION_DENIED", `Actor "${this.actorId}" is not attached to session "${session.name}".`);
     }
+    async resolveConnectionSource(connection, session, operation, access, context) {
+        if (!connection.secret_env)
+            return connection.source;
+        const value = await this.resolveCredential(connection.secret_env, session, operation, access, context, {
+            connection: {
+                id: connection.id,
+                name: connection.name,
+                driver: connection.driver,
+                database: connection.database_name,
+                readOnly: Boolean(connection.read_only),
+            },
+        });
+        return credentialSource(value, connection.driver).source;
+    }
+    async resolveCredential(reference, session, operation, access, context, details = {}) {
+        const resolver = this.credentialResolver;
+        if (!resolver) {
+            if (context.signal?.aborted) {
+                throw credentialStateQLError(reference, new CredentialResolutionError("cancelled"));
+            }
+            if (context.deadline <= Date.now()) {
+                throw credentialStateQLError(reference, new CredentialResolutionError("timeout"));
+            }
+            const value = env[reference];
+            if (value)
+                return value;
+            throw credentialStateQLError(reference, new CredentialResolutionError("unavailable"));
+        }
+        const request = {
+            reference,
+            actorId: this.actorId,
+            session: { id: session.id, name: session.name },
+            operation,
+            access,
+            ...(context.signal ? { signal: context.signal } : {}),
+            ...details,
+        };
+        try {
+            const value = await resolveCredentialBeforeDeadline(resolver, request, context);
+            if (!value)
+                throw new CredentialResolutionError("unavailable");
+            return value;
+        }
+        catch (error) {
+            throw credentialStateQLError(reference, error);
+        }
+    }
+    async openAdapter(connection, context, source) {
+        try {
+            return await createAdapter(connection, context, { source });
+        }
+        catch (error) {
+            if (error instanceof StateQLError)
+                throw error;
+            throw new StateQLError("CONNECTION_FAILED", safeCredentialErrorMessage(error, source), { retryable: true });
+        }
+    }
     executionContext(options) {
         return createAdapterContext(executionTimeout(options.timeoutMs ?? this.timeoutMs), options.signal ?? this.signal);
     }
@@ -1639,6 +1729,59 @@ function positiveInteger(value, name) {
         return value;
     throw new StateQLError("INVALID_COMMAND", `${name} must be a positive integer.`);
 }
+async function closeAdapterQuietly(adapter) {
+    try {
+        await adapter.close();
+    }
+    catch {
+        // Preserve the operation result or primary sanitized error.
+    }
+}
+async function resolveCredentialBeforeDeadline(resolver, request, context) {
+    if (context.signal?.aborted) {
+        throw new CredentialResolutionError("cancelled");
+    }
+    const remaining = context.deadline - Date.now();
+    if (remaining <= 0)
+        throw new CredentialResolutionError("timeout");
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (action, value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            context.signal?.removeEventListener("abort", abort);
+            action(value);
+        };
+        const abort = () => finish(() => reject(new CredentialResolutionError("cancelled")));
+        const timer = setTimeout(() => finish(() => reject(new CredentialResolutionError("timeout"))), remaining);
+        timer.unref?.();
+        context.signal?.addEventListener("abort", abort, { once: true });
+        Promise.resolve()
+            .then(() => resolver(request))
+            .then((value) => finish(resolve, value), (error) => finish(() => reject(error)));
+    });
+}
+function credentialStateQLError(reference, error) {
+    if (error instanceof CredentialResolutionError) {
+        switch (error.reason) {
+            case "unavailable":
+                return new StateQLError("CREDENTIAL_UNAVAILABLE", `Credential reference "${reference}" is unavailable.`, { retryable: true });
+            case "denied":
+                return new StateQLError("PERMISSION_DENIED", `Credential access for "${reference}" was denied.`);
+            case "cancelled":
+                return new StateQLError("OPERATION_CANCELLED", "Credential resolution was cancelled.", { retryable: true });
+            case "timeout":
+                return new StateQLError("DEADLINE_EXCEEDED", "Credential resolution exceeded the operation deadline.", { retryable: true });
+        }
+    }
+    return new StateQLError("CREDENTIAL_RESOLUTION_FAILED", `Credential reference "${reference}" could not be resolved.`, { retryable: true });
+}
+function safeCredentialErrorMessage(error, source) {
+    return redact(errorMessage(error).split(source).join("[credential redacted]"))
+        .replace(/\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+(?::[^\s/@]*)?@/giu, "$1***@");
+}
 function executionTimeout(value) {
     const timeout = positiveInteger(value, "timeoutMs");
     if (timeout > 2_147_483_647) {

package/dist/src/types.d.ts

@@ -1,4 +1,29 @@
 export type Driver = "sqlite" | "postgres" | "mysql";
+export type CredentialAccess = "read" | "write";
+export type CredentialOperation = "connect" | "query" | "inspect" | "plan" | "exec" | "apply" | "transaction.commit";
+export interface CredentialRequest {
+    reference: string;
+    actorId: string;
+    session: {
+        id: string;
+        name: string;
+    };
+    operation: CredentialOperation;
+    access: CredentialAccess;
+    signal?: AbortSignal;
+    profile?: {
+        name: string;
+    };
+    requestedReadOnly?: boolean;
+    connection?: {
+        id: string;
+        name: string;
+        driver: Driver;
+        database: string;
+        readOnly: boolean;
+    };
+}
+export type CredentialResolver = (request: CredentialRequest) => string | undefined | Promise<string | undefined>;
 export type StateConfidence = "authoritative" | "transaction_snapshot" | "database_reported" | "local" | "ttl_based" | "unknown";
 export interface Warning {
     code: string;
@@ -96,6 +121,7 @@ export interface StateQLOptions extends ExecutionOptions {
     maxCellCharacters?: number;
     maxResultRows?: number;
     maxResultBytes?: number;
+    credentialResolver?: CredentialResolver;
     now?: () => Date;
 }
 export type StateQLActorOptions = Omit<StateQLOptions, "session" | "actor"> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Stateful, agent-oriented database CLI for safe result reuse",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test dist/test/cli.test.js dist/test/mysql.test.js dist/test/postgres.test.js dist/test/query.test.js dist/test/sqlite.test.js dist/test/store.test.js dist/test/terminal.test.js dist/test/transaction.test.js dist/test/write.test.js",
+    "test": "npm run build && node --test dist/test/cli.test.js dist/test/credential.test.js dist/test/mysql.test.js dist/test/postgres.test.js dist/test/query.test.js dist/test/sqlite.test.js dist/test/store.test.js dist/test/terminal.test.js dist/test/transaction.test.js dist/test/write.test.js",
     "prepack": "npm test"
   },
   "keywords": [