@fadhilp/stateql 0.3.0 → 0.4.0

package/README.md

@@ -238,9 +238,8 @@ Interrupted commits remain fail-closed; stale `committing` records become
 ```ts
 import { StateQL } from "@fadhilp/stateql";
 
-const stateql = new StateQL({
+const stateql = StateQL.forActor({
   home: "./.stql",
-  session: "shared-workspace",
   actor: "pi-session-id",
   timeoutMs: 30_000,
   maxResultBytes: 16 * 1024 * 1024,
@@ -258,6 +257,68 @@ 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 are passed directly to the adapter.
+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.
+Use `new StateQL({ session, actor })` when the session is already known.
+
 Membership is managed only through the library API, not batch commands:
 `linkActor(session, actorId)`, `unlinkActor(session, actorId)`,
 `listActors(session)`, and `resolveActor(actorId)`. An existing member must link

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/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, 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

@@ -1,5 +1,6 @@
-import type { BatchCommand, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, StateQLOptions, StateQLSnapshot } from "./types.js";
+import type { BatchCommand, BatchOptions, ConnectOptions, ExecOptions, ExecutionOptions, FilterOptions, HistoryEntry, PlanOptions, ProfileOptions, QueryOptions, Response, RowsOptions, StateQLActorOptions, StateQLOptions, StateQLSnapshot } from "./types.js";
 export declare class StateQL {
+    static forActor(options: StateQLActorOptions): StateQL;
     private readonly store;
     private readonly sessionName;
     private readonly actorId;
@@ -11,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;
@@ -66,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

@@ -3,7 +3,7 @@ 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 { 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";
@@ -12,6 +12,23 @@ import { compactRows, defaultHome, hash, parseJson, redact, } from "./util.js";
 const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
 const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
 export class StateQL {
+    static forActor(options) {
+        if (!options.actor.trim()) {
+            throw new StateQLError("INVALID_COMMAND", "Actor ID is required.");
+        }
+        const now = options.now ?? (() => new Date());
+        const store = new StateStore(options.home ?? defaultHome(), now);
+        try {
+            const session = store.resolveActor(options.actor);
+            if (session)
+                return new StateQL({ ...options, session: session.name });
+            const { actor, ...legacyOptions } = options;
+            return new StateQL({ ...legacyOptions, session: actor });
+        }
+        finally {
+            store.close();
+        }
+    }
     store;
     sessionName;
     actorId;
@@ -23,6 +40,7 @@ export class StateQL {
     maxResultBytes;
     timeoutMs;
     signal;
+    credentialResolver;
     now;
     constructor(options = {}) {
         this.now = options.now ?? (() => new Date());
@@ -39,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.");
         }
@@ -67,11 +86,20 @@ 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);
             if (driver !== "sqlite" &&
@@ -81,16 +109,15 @@ export class StateQL {
                     suggestedAction: "Set the URL in an environment variable and reconnect with --env NAME.",
                 });
             }
+            const adapterSource = 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,
@@ -103,7 +130,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", []);
             }
@@ -111,10 +138,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,
@@ -481,7 +508,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();
@@ -554,13 +583,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);
             }
         });
     }
@@ -775,7 +804,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.");
@@ -796,12 +827,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.",
                     });
@@ -828,7 +857,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.",
                     });
@@ -880,7 +909,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 {
@@ -894,13 +925,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);
             }
         });
     }
@@ -912,7 +943,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();
@@ -956,13 +989,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);
             }
         });
     }
@@ -997,26 +1032,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 },
@@ -1056,6 +1094,7 @@ export class StateQL {
                     persistent_sessions: true,
                     result_filtering: true,
                     schema_inspection: true,
+                    credential_resolver: true,
                     deadlines: true,
                     cancellation: true,
                 },
@@ -1211,7 +1250,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." });
         }
@@ -1319,12 +1358,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,
             });
         }
@@ -1377,12 +1422,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.",
             });
@@ -1462,6 +1505,62 @@ 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;
+        return 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),
+            },
+        });
+    }
+    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);
     }
@@ -1622,6 +1721,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,8 +121,12 @@ export interface StateQLOptions extends ExecutionOptions {
     maxCellCharacters?: number;
     maxResultRows?: number;
     maxResultBytes?: number;
+    credentialResolver?: CredentialResolver;
     now?: () => Date;
 }
+export type StateQLActorOptions = Omit<StateQLOptions, "session" | "actor"> & {
+    actor: string;
+};
 export interface QueryOptions extends ExecutionOptions {
     params?: SqlParameters;
     cache?: "auto" | "bypass" | "require";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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": [