@fadhilp/stateql 0.10.1 → 0.11.1

package/dist/src/migrations.js

@@ -126,6 +126,11 @@ const MIGRATIONS = [
             requireIndexes(db, ["connections_alias"]);
         },
     },
+    {
+        name: "password_refs_v1",
+        apply: migratePasswordRefs,
+        validate: validatePasswordRefs,
+    },
 ];
 export function runMigrations(db, now) {
     db.exec(`
@@ -364,7 +369,11 @@ function validateSharedSessionActors(db) {
 function migrateCredentialRefs(db) {
     const profileColumns = new Set(db.prepare("PRAGMA table_info(profiles)").all().map((column) => column.name));
     const hasCredentialRef = profileColumns.has("credential_ref");
+    const hasPasswordRef = profileColumns.has("password_ref");
     if (!profileCredentialRefSchemaCurrent(db)) {
+        if (hasPasswordRef) {
+            throw new Error("State migration cannot safely rebuild a profile schema that already contains password references.");
+        }
         const missingSources = db.prepare(`SELECT COUNT(*) AS count FROM profiles
        WHERE target IS NULL AND secret_env IS NULL${hasCredentialRef ? " AND credential_ref IS NULL" : ""}`).get();
         if (missingSources.count) {
@@ -424,6 +433,117 @@ function profileCredentialRefSchemaCurrent(db) {
     const row = db.prepare("SELECT sql FROM sqlite_schema WHERE type = 'table' AND name = 'profiles'").get();
     return Boolean(row?.sql && /CHECK\s*\(\s*\(target IS NOT NULL\)\s*\+\s*\(secret_env IS NOT NULL\)\s*\+\s*\(credential_ref IS NOT NULL\)\s*=\s*1\s*\)/i.test(row.sql));
 }
+function migratePasswordRefs(db) {
+    const profileColumns = tableColumns(db, "profiles");
+    const profilePasswordRef = profileColumns.has("password_ref") ? "password_ref" : "NULL";
+    if (!profilePasswordRefSchemaCurrent(db)) {
+        const invalid = db.prepare(`SELECT COUNT(*) AS count FROM profiles
+       WHERE ${profilePasswordRef} IS NOT NULL AND target IS NULL`).get();
+        if (invalid.count) {
+            throw new Error("State migration found a password reference without a target profile source.");
+        }
+        db.exec(`
+      ALTER TABLE profiles RENAME TO profiles_legacy_password_refs_v1;
+      CREATE TABLE profiles (
+        name TEXT PRIMARY KEY,
+        target TEXT,
+        secret_env TEXT,
+        credential_ref TEXT,
+        password_ref TEXT,
+        read_only INTEGER NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        CHECK (
+          (target IS NOT NULL) +
+          (secret_env IS NOT NULL) +
+          (credential_ref IS NOT NULL) = 1
+        ),
+        CHECK (password_ref IS NULL OR target IS NOT NULL)
+      );
+      INSERT INTO profiles
+        (name, target, secret_env, credential_ref, password_ref, read_only, created_at, updated_at)
+      SELECT name, target, secret_env, credential_ref, ${profilePasswordRef}, read_only, created_at, updated_at
+      FROM profiles_legacy_password_refs_v1;
+      DROP TABLE profiles_legacy_password_refs_v1;
+    `);
+    }
+    const connectionColumns = tableColumns(db, "connections");
+    const connectionPasswordRef = connectionColumns.has("password_ref") ? "password_ref" : "NULL";
+    if (!connectionPasswordRefSchemaCurrent(db)) {
+        const invalid = db.prepare(`SELECT COUNT(*) AS count FROM connections
+       WHERE ${connectionPasswordRef} IS NOT NULL
+         AND (secret_env IS NOT NULL OR credential_ref IS NOT NULL OR
+              driver NOT IN ('postgres', 'mysql', 'mongodb', 'redis'))`).get();
+        if (invalid.count) {
+            throw new Error("State migration found a password reference on a non-target connection source.");
+        }
+        db.exec(`
+      ALTER TABLE connections RENAME TO connections_legacy_password_refs_v1;
+      CREATE TABLE connections (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        name TEXT NOT NULL,
+        driver TEXT NOT NULL,
+        database_name TEXT NOT NULL,
+        source TEXT NOT NULL,
+        secret_env TEXT,
+        credential_ref TEXT,
+        password_ref TEXT,
+        read_only INTEGER NOT NULL,
+        version INTEGER NOT NULL,
+        created_at TEXT NOT NULL,
+        alias TEXT,
+        CHECK (
+          password_ref IS NULL OR
+          (secret_env IS NULL AND credential_ref IS NULL AND
+           driver IN ('postgres', 'mysql', 'mongodb', 'redis'))
+        ),
+        FOREIGN KEY(session_id) REFERENCES sessions(id)
+      );
+      INSERT INTO connections
+        (id, session_id, name, driver, database_name, source, secret_env,
+         credential_ref, password_ref, read_only, version, created_at, alias)
+      SELECT id, session_id, name, driver, database_name, source, secret_env,
+             credential_ref, ${connectionPasswordRef}, read_only, version, created_at, alias
+      FROM connections_legacy_password_refs_v1;
+      DROP TABLE connections_legacy_password_refs_v1;
+      CREATE UNIQUE INDEX connections_alias ON connections(alias);
+    `);
+    }
+}
+function validatePasswordRefs(db) {
+    requireColumns(db, "profiles", ["password_ref"]);
+    requireColumns(db, "connections", ["password_ref"]);
+    if (!profilePasswordRefSchemaCurrent(db) || !connectionPasswordRefSchemaCurrent(db)) {
+        throw new Error("State migration did not enforce password-reference source constraints.");
+    }
+    const invalidProfiles = db.prepare(`SELECT COUNT(*) AS count FROM profiles
+     WHERE password_ref IS NOT NULL AND target IS NULL`).get();
+    const invalidConnections = db.prepare(`SELECT COUNT(*) AS count FROM connections
+     WHERE password_ref IS NOT NULL
+       AND (secret_env IS NOT NULL OR credential_ref IS NOT NULL OR
+            driver NOT IN ('postgres', 'mysql', 'mongodb', 'redis'))`).get();
+    if (invalidProfiles.count || invalidConnections.count) {
+        throw new Error("State migration left an invalid password-reference source.");
+    }
+}
+function profilePasswordRefSchemaCurrent(db) {
+    const sql = tableSql(db, "profiles");
+    return profileCredentialRefSchemaCurrent(db) &&
+        /CHECK\s*\(\s*password_ref IS NULL OR target IS NOT NULL\s*\)/i.test(sql);
+}
+function connectionPasswordRefSchemaCurrent(db) {
+    return /CHECK\s*\(\s*password_ref IS NULL OR\s*\(secret_env IS NULL AND credential_ref IS NULL AND\s*driver IN \('postgres', 'mysql', 'mongodb', 'redis'\)\)\s*\)/i
+        .test(tableSql(db, "connections"));
+}
+function tableSql(db, table) {
+    const row = db.prepare("SELECT sql FROM sqlite_schema WHERE type = 'table' AND name = ?").get(table);
+    return row?.sql ?? "";
+}
+function tableColumns(db, table) {
+    return new Set(db.prepare(`PRAGMA table_info(${table})`).all()
+        .map((column) => column.name));
+}
 function addColumn(db, table, column, definition) {
     const columns = db.prepare(`PRAGMA table_info(${table})`).all();
     if (!columns.some((candidate) => candidate.name === column)) {

package/dist/src/response-data.js

@@ -14,6 +14,7 @@ export function profileData(profile) {
         target: profile.target,
         secret_env: profile.secret_env,
         credential_ref: profile.credential_ref,
+        password_ref: profile.password_ref,
         read_only: Boolean(profile.read_only),
     };
 }

package/dist/src/stateql.d.ts

@@ -1,7 +1,11 @@
 import { type TableChange } from "./table-editor.js";
-import type { ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, StateQLActorOptions, StateQLOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
+import type { ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, StateQLActorOptions, StateQLOptions, StateQLWorkspaceOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
 export declare class StateQL {
+    /** Runtime contract marker for passwordRef/password_ref support. */
+    static readonly passwordReferenceVersion: 1;
     static forActor(options: StateQLActorOptions): StateQL;
+    /** Opens one actor in a named shared workspace for a trusted library host. */
+    static forWorkspace(options: StateQLWorkspaceOptions): StateQL;
     private readonly store;
     private readonly sessionName;
     private readonly actorId;

package/dist/src/stateql.js

@@ -5,7 +5,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, credentialSource, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, mongoDatabaseName, redisDatabaseName, normalizeSqliteSource, validateCredentialRef, validateProfileName, version, } from "./connection.js";
+import { confidence, credentialSource, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, injectPassword, mongoDatabaseName, redisDatabaseName, normalizeSqliteSource, validateCredentialRef, validatePasswordReferenceTarget, validateProfileName, version, } from "./connection.js";
 import { asStateQLError, CredentialResolutionError, StateQLError, } from "./errors.js";
 import { analyzeMongoWriteSafety, deserializeMongoWriteCommand, serializeMongoCommand, validateMongoReadCommand, validateMongoWriteCommand, MongoAdapter, } from "./mongodb.js";
 import { deserializeRedisCommand, RedisAdapter, serializeRedisCommand, validateRedisReadCommand, validateRedisWriteCommand, } from "./redis.js";
@@ -17,7 +17,10 @@ import { compactRows, defaultHome, hash, isSqlParameters, parseJson, redact, } f
 const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
 const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
 const DEFAULT_CREDENTIAL_RESOLUTION_TIMEOUT_MS = 120_000;
+const WORKSPACE_BOOTSTRAP = Symbol("StateQL.workspaceBootstrap");
 export class StateQL {
+    /** Runtime contract marker for passwordRef/password_ref support. */
+    static passwordReferenceVersion = 1;
     static forActor(options) {
         if (!options.actor.trim()) {
             throw new StateQLError("INVALID_COMMAND", "Actor ID is required.");
@@ -35,6 +38,21 @@ export class StateQL {
             store.close();
         }
     }
+    /** Opens one actor in a named shared workspace for a trusted library host. */
+    static forWorkspace(options) {
+        if (!options.workspace.trim()) {
+            throw new StateQLError("INVALID_COMMAND", "Workspace name is required.");
+        }
+        if (!options.actor.trim()) {
+            throw new StateQLError("INVALID_COMMAND", "Actor ID is required.");
+        }
+        const { workspace, ...actorOptions } = options;
+        return new StateQL({
+            ...actorOptions,
+            session: workspace,
+            [WORKSPACE_BOOTSTRAP]: true,
+        });
+    }
     store;
     sessionName;
     actorId;
@@ -78,7 +96,12 @@ export class StateQL {
         }
         const store = new StateStore(options.home ?? defaultHome(), this.now, maxStateBytes);
         try {
-            store.bootstrapSession(this.sessionName, this.actorId, options.actor === undefined);
+            if (options[WORKSPACE_BOOTSTRAP]) {
+                store.bootstrapWorkspace(this.sessionName, this.actorId);
+            }
+            else {
+                store.bootstrapSession(this.sessionName, this.actorId, options.actor === undefined);
+            }
         }
         catch (error) {
             store.close();
@@ -112,7 +135,13 @@ export class StateQL {
             if (sourceCount !== 1) {
                 throw new StateQLError("INVALID_COMMAND", "Use exactly one connection target, profile, secret environment variable, or credential reference.");
             }
-            const implicitProfile = !options.profile && !options.secretEnv && !options.credentialRef && target
+            if (options.passwordRef !== undefined &&
+                (target === undefined || options.profile !== undefined ||
+                    options.secretEnv !== undefined || options.credentialRef !== undefined)) {
+                throw new StateQLError("INVALID_COMMAND", "A password reference requires a literal remote connection target.");
+            }
+            const implicitProfile = !options.profile && !options.secretEnv && !options.credentialRef &&
+                options.passwordRef === undefined && target
                 ? this.store.getProfile(target)
                 : undefined;
             const profile = options.profile
@@ -122,18 +151,27 @@ export class StateQL {
                 throw new StateQLError("CONNECTION_NOT_FOUND", `Profile "${options.profile}" was not found.`, { suggestedAction: "Run stql profile list." });
             }
             if (profile &&
-                [profile.target, profile.secret_env, profile.credential_ref]
-                    .filter((value) => value !== null).length !== 1) {
-                throw new StateQLError("STATE_CORRUPTED", `Profile "${profile.name}" does not have exactly one connection source.`);
+                ([profile.target, profile.secret_env, profile.credential_ref]
+                    .filter((value) => value !== null).length !== 1 ||
+                    (profile.password_ref !== null && profile.target === null))) {
+                throw new StateQLError("STATE_CORRUPTED", `Profile "${profile.name}" has an invalid connection source.`);
             }
             const resolvedTarget = profile?.target ?? target;
             const secretEnv = options.secretEnv ?? profile?.secret_env ?? undefined;
             const credentialRef = options.credentialRef ?? profile?.credential_ref ?? undefined;
+            const passwordRef = options.passwordRef ?? profile?.password_ref ?? undefined;
             if (secretEnv !== undefined && !isEnvironmentName(secretEnv)) {
                 throw new StateQLError("INVALID_COMMAND", "Secret environment variable name is invalid.");
             }
             if (credentialRef !== undefined)
                 validateCredentialRef(credentialRef);
+            if (passwordRef !== undefined) {
+                validateCredentialRef(passwordRef);
+                if (!resolvedTarget) {
+                    throw new StateQLError("INVALID_COMMAND", "A password reference requires a literal remote connection target.");
+                }
+                validatePasswordReferenceTarget(resolvedTarget);
+            }
             const credentialReference = secretEnv ?? credentialRef;
             const credentialReferenceSource = secretEnv !== undefined
                 ? "secret_env"
@@ -141,50 +179,65 @@ export class StateQL {
             const readOnly = options.readOnly ??
                 (profile ? Boolean(profile.read_only) : true);
             const context = this.executionContext(options);
-            const secret = credentialReference && credentialReferenceSource
-                ? await this.resolveCredential(credentialReference, credentialReferenceSource, session, "connect", readOnly ? "read" : "write", context, {
+            let adapterSource;
+            let driver;
+            if (passwordRef !== undefined) {
+                const password = await this.resolveCredential(passwordRef, "password_ref", session, "connect", readOnly ? "read" : "write", context, {
                     ...(profile ? { profile: { name: profile.name } } : {}),
                     requestedReadOnly: readOnly,
-                })
-                : resolvedTarget;
-            if (!secret) {
-                throw new StateQLError("INVALID_COMMAND", "Connection target is required.");
-            }
-            const resolvedSource = credentialReferenceSource
-                ? credentialSource(secret, undefined, credentialReferenceSource)
-                : { driver: detectDriver(secret), source: secret };
-            const { driver } = resolvedSource;
-            if (driver !== "sqlite" &&
-                !credentialReference &&
-                databaseUrlHasSecret(secret)) {
-                throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env or --credential-ref.`, {
-                    suggestedAction: "Use an environment variable or trusted host credential reference.",
-                });
+                }, resolvedTarget);
+                ({ driver, source: adapterSource } = injectPassword(resolvedTarget, password));
             }
-            const adapterSource = credentialReferenceSource
-                ? resolvedSource.source
-                : driver === "sqlite" ? normalizeSqliteSource(secret) : secret;
-            const source = driver === "sqlite"
-                ? adapterSource
-                : credentialReferenceSource
-                    ? redact(secret)
-                    : adapterSource;
+            else {
+                const secret = credentialReference && credentialReferenceSource
+                    ? await this.resolveCredential(credentialReference, credentialReferenceSource, session, "connect", readOnly ? "read" : "write", context, {
+                        ...(profile ? { profile: { name: profile.name } } : {}),
+                        requestedReadOnly: readOnly,
+                    })
+                    : resolvedTarget;
+                if (!secret) {
+                    throw new StateQLError("INVALID_COMMAND", "Connection target is required.");
+                }
+                const resolvedSource = credentialReferenceSource
+                    ? credentialSource(secret, undefined, credentialReferenceSource)
+                    : { driver: detectDriver(secret), source: secret };
+                driver = resolvedSource.driver;
+                if (driver !== "sqlite" &&
+                    !credentialReference &&
+                    databaseUrlHasSecret(secret)) {
+                    throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env or --credential-ref.`, {
+                        suggestedAction: "Use an environment variable or trusted host credential reference.",
+                    });
+                }
+                adapterSource = credentialReferenceSource
+                    ? resolvedSource.source
+                    : driver === "sqlite" ? normalizeSqliteSource(secret) : secret;
+            }
+            const persistedSource = passwordRef !== undefined
+                ? resolvedTarget
+                : driver === "sqlite"
+                    ? adapterSource
+                    : credentialReferenceSource
+                        ? redact(adapterSource)
+                        : adapterSource;
+            const identitySource = passwordRef !== undefined ? resolvedTarget : adapterSource;
             const databaseName = driver === "sqlite"
                 ? basename(adapterSource)
                 : driver === "mongodb"
-                    ? mongoDatabaseName(adapterSource)
+                    ? mongoDatabaseName(identitySource)
                     : driver === "redis"
-                        ? redisDatabaseName(adapterSource)
-                        : new URL(secret).pathname.replace(/^\//, "") || driver;
+                        ? redisDatabaseName(identitySource)
+                        : new URL(identitySource).pathname.replace(/^\//, "") || driver;
             const draft = {
                 id: "pending",
                 session_id: session.id,
                 name: options.name ?? profile?.name ?? databaseName,
                 driver,
                 database_name: databaseName,
-                source,
+                source: persistedSource,
                 secret_env: secretEnv ?? null,
                 credential_ref: credentialRef ?? null,
+                password_ref: passwordRef ?? null,
                 read_only: readOnly ? 1 : 0,
                 version: 0,
                 created_at: this.now().toISOString(),
@@ -212,9 +265,10 @@ export class StateQL {
                 name: draft.name,
                 driver,
                 databaseName,
-                source,
+                source: persistedSource,
                 ...(secretEnv ? { secretEnv } : {}),
                 ...(credentialRef ? { credentialRef } : {}),
+                ...(passwordRef !== undefined ? { passwordRef } : {}),
                 readOnly,
             });
             if (!connection) {
@@ -250,12 +304,14 @@ export class StateQL {
                 target,
                 secretEnv: options.secretEnv,
                 credentialRef: options.credentialRef,
+                passwordRef: options.passwordRef,
             });
             const profile = this.store.addProfile({
                 name,
                 target: source.target ?? undefined,
                 secretEnv: source.secretEnv ?? undefined,
                 credentialRef: source.credentialRef ?? undefined,
+                passwordRef: source.passwordRef ?? undefined,
                 readOnly: options.readOnly ?? true,
             });
             return {
@@ -272,22 +328,32 @@ export class StateQL {
             if (!existing)
                 throw new StateQLError("CONNECTION_NOT_FOUND", `Profile "${name}" was not found.`);
             if (!changes || typeof changes !== "object" || Array.isArray(changes) ||
-                Object.keys(changes).some((key) => !["target", "secretEnv", "credentialRef", "readOnly"].includes(key))) {
+                Object.keys(changes).some((key) => !["target", "secretEnv", "credentialRef", "passwordRef", "readOnly"].includes(key))) {
                 throw new StateQLError("INVALID_COMMAND", "Profile update contains unknown fields.");
             }
             if (changes.readOnly !== undefined && typeof changes.readOnly !== "boolean")
                 throw new StateQLError("INVALID_COMMAND", "Profile readOnly must be boolean.");
             const changesSource = Object.hasOwn(changes, "target") || Object.hasOwn(changes, "secretEnv") || Object.hasOwn(changes, "credentialRef");
-            if (!changesSource && changes.readOnly === undefined)
+            const changesPassword = Object.hasOwn(changes, "passwordRef");
+            if (!changesSource && !changesPassword && changes.readOnly === undefined)
                 throw new StateQLError("INVALID_COMMAND", "Profile update has no changes.");
-            const source = changesSource
-                ? validatedProfileSource({ target: changes.target ?? undefined, secretEnv: changes.secretEnv ?? undefined, credentialRef: changes.credentialRef ?? undefined })
-                : { target: existing.target, secretEnv: existing.secret_env, credentialRef: existing.credential_ref };
+            const targetSource = changesSource ? changes.target ?? undefined : existing.target ?? undefined;
+            const source = validatedProfileSource({
+                target: targetSource,
+                secretEnv: changesSource ? changes.secretEnv ?? undefined : existing.secret_env ?? undefined,
+                credentialRef: changesSource ? changes.credentialRef ?? undefined : existing.credential_ref ?? undefined,
+                passwordRef: changesPassword
+                    ? changes.passwordRef ?? undefined
+                    : !changesSource || targetSource === existing.target
+                        ? existing.password_ref ?? undefined
+                        : undefined,
+            });
             const profile = this.store.updateProfile({
                 name,
                 target: source.target,
                 secretEnv: source.secretEnv,
                 credentialRef: source.credentialRef,
+                passwordRef: source.passwordRef,
                 readOnly: changes.readOnly ?? Boolean(existing.read_only),
             });
             if (!profile)
@@ -1711,7 +1777,7 @@ export class StateQL {
             const planParameters = compiled?.params ?? (nativePlan || tableUpdates
                 ? undefined
                 : parseJson(plan.parameters, `plan "${plan.id}" parameters`, isSqlParameters));
-            const claimToken = this.store.nextId("claim");
+            const claimToken = this.store.randomId("claim");
             const claimed = this.store.claimPlan(plan.id, session.id, this.actorId, claimToken);
             if (!claimed) {
                 throw new StateQLError("STALE_PLAN", "Plan is already being applied.");
@@ -1900,6 +1966,7 @@ export class StateQL {
                             readOnly: command.read_only,
                             secretEnv: command.secret_env,
                             credentialRef: command.credential_ref,
+                            passwordRef: command.password_ref ?? undefined,
                             profile: command.profile,
                             timeoutMs: command.timeout_ms,
                         });
@@ -1912,12 +1979,14 @@ export class StateQL {
                             readOnly: command.read_only ?? true,
                             secretEnv: command.secret_env,
                             credentialRef: command.credential_ref,
+                            passwordRef: command.password_ref ?? undefined,
                         });
                     case "profile.update":
                         return this.updateProfile(batchString(command.name, "name"), {
                             ...(command.target !== undefined ? { target: command.target } : {}),
                             ...(command.secret_env !== undefined ? { secretEnv: command.secret_env } : {}),
                             ...(command.credential_ref !== undefined ? { credentialRef: command.credential_ref } : {}),
+                            ...(command.password_ref !== undefined ? { passwordRef: command.password_ref } : {}),
                             ...(command.read_only !== undefined ? { readOnly: command.read_only } : {}),
                         });
                     case "profile.list":
@@ -2718,6 +2787,28 @@ export class StateQL {
         throw new StateQLError("PERMISSION_DENIED", `Actor "${this.actorId}" is not attached to session "${session.name}".`);
     }
     async resolveConnectionSource(connection, session, operation, access, context) {
+        const references = [connection.secret_env, connection.credential_ref, connection.password_ref]
+            .filter((value) => value !== null);
+        if (references.length > 1) {
+            throw new StateQLError("STATE_CORRUPTED", "Connection has ambiguous credential references.");
+        }
+        if (connection.password_ref !== null) {
+            validateCredentialRef(connection.password_ref);
+            const driver = validatePasswordReferenceTarget(connection.source);
+            if (driver !== connection.driver) {
+                throw new StateQLError("STATE_CORRUPTED", "Password-reference target driver does not match the stored connection.");
+            }
+            const password = await this.resolveCredential(connection.password_ref, "password_ref", session, operation, access, context, {
+                connection: {
+                    id: connection.id,
+                    name: connection.name,
+                    driver: connection.driver,
+                    database: connection.database_name,
+                    readOnly: Boolean(connection.read_only),
+                },
+            }, connection.source);
+            return injectPassword(connection.source, password).source;
+        }
         const reference = connection.secret_env ?? connection.credential_ref;
         if (!reference)
             return connection.source;
@@ -2735,7 +2826,7 @@ export class StateQL {
         });
         return credentialSource(value, connection.driver, source).source;
     }
-    async resolveCredential(reference, source, session, operation, access, context, details = {}) {
+    async resolveCredential(reference, source, session, operation, access, context, details = {}, passwordTarget) {
         const resolver = this.credentialResolver;
         const credentialContext = createAdapterContext(this.credentialTimeoutMs, context.signal);
         let value;
@@ -2750,9 +2841,8 @@ export class StateQL {
                 value = env[reference];
         }
         else {
-            const request = {
+            const baseRequest = {
                 reference,
-                source,
                 actorId: this.actorId,
                 session: { id: session.id, name: session.name },
                 operation,
@@ -2760,6 +2850,9 @@ export class StateQL {
                 ...(context.signal ? { signal: context.signal } : {}),
                 ...details,
             };
+            const request = source === "password_ref"
+                ? { ...baseRequest, source, target: passwordTarget }
+                : { ...baseRequest, source };
             try {
                 value = await resolveCredentialBeforeDeadline(resolver, request, credentialContext);
             }
@@ -2767,7 +2860,7 @@ export class StateQL {
                 throw credentialStateQLError(reference, error);
             }
         }
-        if (!value) {
+        if (value === undefined || (source !== "password_ref" && value === "")) {
             throw credentialStateQLError(reference, new CredentialResolutionError("unavailable"));
         }
         context.deadline = Date.now() + (context.timeoutMs ?? this.timeoutMs);
@@ -2844,8 +2937,8 @@ export class StateQL {
         const category = historyCategory(command);
         const internal = commandContext?.internal ?? false;
         let session = this.store.ensureSession(this.sessionName);
-        const commandId = this.store.nextId("cmd");
         if (!this.store.isSessionMember(session.id, this.actorId)) {
+            const commandId = this.store.randomId("cmd");
             const error = new StateQLError("PERMISSION_DENIED", `Actor "${this.actorId}" is not attached to session "${session.name}".`);
             return {
                 ok: false,
@@ -2861,8 +2954,7 @@ export class StateQL {
             const result = await action(session);
             const responseSession = result.session ?? session;
             const sqlText = resolveHistorySql(historySql);
-            this.store.addHistory({
-                id: commandId,
+            const history = this.store.addHistory({
                 sessionId: session.id,
                 actorId: this.actorId,
                 origin,
@@ -2878,7 +2970,7 @@ export class StateQL {
             });
             return {
                 ok: true,
-                command_id: commandId,
+                command_id: history.id,
                 session_id: responseSession.id,
                 data: result.data,
                 warnings: result.warnings ?? [],
@@ -2896,8 +2988,7 @@ export class StateQL {
         catch (error) {
             const stateqlError = asStateQLError(error);
             const sqlText = resolveHistorySql(historySql);
-            this.store.addHistory({
-                id: commandId,
+            const history = this.store.addHistory({
                 sessionId: session.id,
                 actorId: this.actorId,
                 origin,
@@ -2913,7 +3004,7 @@ export class StateQL {
             });
             return {
                 ok: false,
-                command_id: commandId,
+                command_id: history.id,
                 session_id: session.id,
                 error: stateqlError.details,
                 meta: {
@@ -3214,7 +3305,23 @@ function credentialStateQLError(reference, error) {
     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]"))
+    let message = errorMessage(error).split(source).join("[credential redacted]");
+    const authority = /^[a-z][a-z\d+.-]*:\/\/([^/?#]*)/i.exec(source)?.[1];
+    if (authority) {
+        const at = authority.lastIndexOf("@");
+        const colon = at < 0 ? -1 : authority.slice(0, at).indexOf(":");
+        const password = colon < 0 ? "" : authority.slice(colon + 1, at);
+        const secrets = new Set([password]);
+        try {
+            secrets.add(decodeURIComponent(password));
+        }
+        catch { /* malformed values stay encoded */ }
+        for (const secret of secrets) {
+            if (secret)
+                message = message.split(secret).join("[credential redacted]");
+        }
+    }
+    return redact(message)
         .replace(/\b([a-z][a-z0-9+.-]*:\/\/)[^\s\/@]+(?::[^\s\/@]*)?@/giu, "$1***@");
 }
 function executionTimeout(value, name = "timeoutMs") {
@@ -3236,15 +3343,27 @@ function validatedProfileSource(input) {
         throw new StateQLError("INVALID_COMMAND", "Secret environment variable name is invalid.");
     if (input.credentialRef !== undefined)
         validateCredentialRef(input.credentialRef);
+    if (input.passwordRef !== undefined)
+        validateCredentialRef(input.passwordRef);
     let target = input.target ?? null;
+    if (input.passwordRef !== undefined && target === null) {
+        throw new StateQLError("INVALID_COMMAND", "A password reference requires a literal remote profile target.");
+    }
     if (target) {
-        const driver = detectDriver(target);
-        if (driver !== "sqlite" && databaseUrlHasSecret(target))
+        const driver = input.passwordRef !== undefined
+            ? validatePasswordReferenceTarget(target)
+            : detectDriver(target);
+        if (input.passwordRef === undefined && driver !== "sqlite" && databaseUrlHasSecret(target))
             throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env or --credential-ref.`);
         if (driver === "sqlite")
             target = normalizeSqliteSource(target);
     }
-    return { target, secretEnv: input.secretEnv ?? null, credentialRef: input.credentialRef ?? null };
+    return {
+        target,
+        secretEnv: input.secretEnv ?? null,
+        credentialRef: input.credentialRef ?? null,
+        passwordRef: input.passwordRef ?? null,
+    };
 }
 function historyCategory(command) {
     if (["query", "exec", "plan", "apply", "mongo.query", "mongo.exec", "mongo.plan", "redis.query", "redis.exec", "redis.plan", "filter"].includes(command))