@fadhilp/stateql 0.10.0 → 0.11.0

package/README.md

@@ -7,7 +7,7 @@ reusable and operations traceable across commands.
 
 StateQL is built around durable handles:
 
-1. Run a query and receive a result handle such as `q_1`.
+1. Run a query and receive a result handle such as `q_k7m2v5x9c3d6f8h4j2n7p5r9tw`.
 2. Reuse, filter, page, count, alias, or export that stored result without
    rerunning the original SQL.
 3. Use operation, plan, and transaction handles to inspect and control writes.
@@ -40,25 +40,25 @@ Parameters keep values separate from SQL. `ORDER BY` makes paging stable, and
 one-line JSON:
 
 ```json
-{"ok":true,"handle":"q_1","rows":[{"id":7,"name":"Ada","email":"ada@example.com"},{"id":12,"name":"Grace","email":"grace@example.com"},{"id":18,"name":"Linus","email":"linus@kernel.org"}],"truncated":false,"cached":false,"total":3,"next_offset":null}
+{"ok":true,"handle":"q_k7m2v5x9c3d6f8h4j2n7p5r9tw","rows":[{"id":7,"name":"Ada","email":"ada@example.com"},{"id":12,"name":"Grace","email":"grace@example.com"},{"id":18,"name":"Linus","email":"linus@kernel.org"}],"truncated":false,"cached":false,"total":3,"next_offset":null}
 ```
 
-`q_1` is a durable snapshot. Filter it locally without accessing the original
+`q_k7m2v5x9c3d6f8h4j2n7p5r9tw` is a durable snapshot. Filter it locally without accessing the original
 database:
 
 ```bash
-stql filter q_1 "email LIKE ?" --param "%@example.com"
+stql filter q_k7m2v5x9c3d6f8h4j2n7p5r9tw "email LIKE ?" --param "%@example.com"
 ```
 
 ```json
-{"ok":true,"handle":"q_2","rows":[{"id":7,"name":"Ada","email":"ada@example.com"},{"id":12,"name":"Grace","email":"grace@example.com"}],"truncated":false,"cached":false,"total":2,"next_offset":null}
+{"ok":true,"handle":"q_z4n8c2v6b3m7k5j9h2g4f6d8sa","rows":[{"id":7,"name":"Ada","email":"ada@example.com"},{"id":12,"name":"Grace","email":"grace@example.com"}],"truncated":false,"cached":false,"total":2,"next_offset":null}
 ```
 
 The filtered snapshot receives its own handle. Give it a readable alias, page
 through it, inspect its count, or export it without rerunning SQL:
 
 ```bash
-stql alias set example-users q_2
+stql alias set example-users q_z4n8c2v6b3m7k5j9h2g4f6d8sa
 stql rows example-users --offset 0 --limit 1
 stql rows example-users --offset 1 --limit 1
 stql count example-users
@@ -68,16 +68,18 @@ stql export example-users --output example-users.csv --format csv
 Example first page:
 
 ```json
-{"ok":true,"handle":"q_2","rows":[{"id":7,"name":"Ada","email":"ada@example.com"}],"total":2,"truncated":true,"next_offset":1}
+{"ok":true,"handle":"q_z4n8c2v6b3m7k5j9h2g4f6d8sa","rows":[{"id":7,"name":"Ada","email":"ada@example.com"}],"total":2,"truncated":true,"next_offset":1}
 ```
 
-Running the same normalized query with the same parameters reuses `q_1` while
+Running the same normalized query with the same parameters reuses `q_k7m2v5x9c3d6f8h4j2n7p5r9tw` while
 its cache entry is valid. Use `--cache bypass` when a fresh read is required.
 
 ## Connections and profiles
 
 A connection accepts exactly one source: a direct target, `--env`,
-`--credential-ref`, or `--profile`.
+`--credential-ref`, or `--profile`. Library and batch callers may additionally
+attach `passwordRef`/`password_ref` to a literal password-free remote target;
+it is not a fourth source.
 
 ```bash
 stql connect <sqlite-path|postgres-url|mysql-url|mongodb-url> [--name NAME] [--read-write]
@@ -108,16 +110,18 @@ export SQLITE_DATABASE='sqlite:./app.sqlite'
 stql connect --env SQLITE_DATABASE --name local --read-only
 ```
 
-StateQL stores no PostgreSQL, MySQL, or MongoDB password. Credential-bearing
-URLs must be supplied through `--env`. SQLite paths remain persisted as
-connection metadata.
+StateQL stores no PostgreSQL, MySQL, MongoDB, or Redis password.
+Credential-bearing URLs must be supplied through `--env` or an opaque full-URL
+credential reference. SQLite paths remain persisted as connection metadata.
 
 ### Local profiles
 
 Profiles store exactly one connection target, environment-variable name, or
-opaque credential reference together with read-only policy. Credential values
-are never stored. Profiles persist under `STQL_HOME` with other StateQL
-metadata, and list/show responses include `credential_ref` when configured.
+opaque credential reference together with read-only policy. A remote literal
+target may additionally store a `password_ref`; SQLite, environment-backed, and
+full-URL `credential_ref` profiles cannot. Credential values are never stored.
+Profiles persist under `STQL_HOME` with other StateQL metadata, and list/show
+responses include nullable `credential_ref` and `password_ref` fields.
 
 ```bash
 stql profile add local ./app.sqlite --read-write
@@ -134,6 +138,21 @@ apply environment-variable syntax or normalization to them. They can only be
 resolved by a trusted host `CredentialResolver`, so the standalone CLI may
 store them in profiles but cannot connect with them.
 
+Library callers can keep nonsecret endpoint, username, database, TLS, and CA
+options in the literal URL while resolving only its password:
+
+```ts
+await stateql.connect(
+  "postgres://app@db.example/app?sslmode=verify-full&sslrootcert=/etc/app-ca.pem",
+  { passwordRef: "vault://database/app/password", readOnly: true },
+);
+```
+
+The same field is accepted by `addProfile`, `updateProfile`, and batch
+`connect`/`profile.add`/`profile.update` commands (snake case in batch input).
+Targets with an embedded password or query parameters that override endpoint or
+credential fields are rejected before credential resolution or driver access.
+
 A bare connection target matching a profile name resolves to that profile;
 otherwise it remains a path or database URL.
 
@@ -473,9 +492,21 @@ for user confirmation before changing membership or the shared connection.
 
 ### Harness credential resolution
 
-Library integrations can resolve environment-variable names or opaque
-credential references through a trusted approval or secret-storage layer
-instead of mutating `process.env`:
+Library integrations can resolve environment-variable names, opaque full-URL
+credential references, or password-only references through a trusted approval
+or secret-storage layer instead of mutating `process.env`:
+
+Integrations pinned to an older published package should gate setup before
+sending `password_ref`:
+
+```ts
+if ((StateQL.passwordReferenceVersion ?? 0) < 1) {
+  throw new Error("Installed StateQL does not support password references.");
+}
+```
+
+`passwordReferenceVersion = 1` guarantees the password-only resolver request,
+validation, persistence, reconnect, and redaction contract documented below.
 
 ```ts
 import {
@@ -512,27 +543,31 @@ Credential resolution has its own two-minute default deadline
 The database-operation timeout begins after a credential is resolved.
 
 When no custom resolver is configured, StateQL reads only `secret_env`
-references from `process.env`; `credential_ref` never falls back to the
-environment. A configured resolver is authoritative for both sources: returning
-`undefined` produces `CREDENTIAL_UNAVAILABLE` and never falls back to the
-process environment. Resolver requests include `source` (`secret_env` or
-`credential_ref`) while retaining `reference`; source may be omitted only on
-legacy secret-environment request objects. 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.
+references from `process.env`; `credential_ref` and `password_ref` never fall
+back to the environment. A configured resolver is authoritative for all
+sources: returning `undefined` produces `CREDENTIAL_UNAVAILABLE` and never falls
+back to the process environment. Resolver requests retain `reference` and
+include `source` (`secret_env`, `credential_ref`, or `password_ref`); source may
+be omitted only on legacy secret-environment request objects. A `password_ref`
+request additionally includes the exact password-free effective `target`.
+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 and session identity, the
 operation's effective read/write access, an abort signal, and sanitized
 connection metadata.
 
-Returned values must be complete PostgreSQL, MySQL, MongoDB, or Redis URLs, or
-explicit `sqlite:` sources. StateQL validates the source and its stored driver before
-adapter construction and normalizes SQLite paths. Credential-bearing database
-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.
+For `secret_env` and `credential_ref`, returned values must be complete
+PostgreSQL, MySQL, MongoDB, or Redis URLs, or explicit `sqlite:` sources. For
+`password_ref`, the resolver returns only the password; an explicit empty string
+is a resolved password, while `undefined` fails closed. StateQL percent-encodes
+and injects only that password into the original target for adapter use, leaving
+all nonsecret URL/TLS/CA bytes unchanged. It persists only the original target
+and reference. Resolved credentials never enter connection metadata, history,
+snapshots, cache keys, responses, or stored errors.
 
 Harnesses remain responsible for approval policy, binding lifetime, revocation,
 and keeping values out of their own logs and model-visible data.
@@ -547,13 +582,26 @@ retry.
 ### Result identities and aliases
 
 Every materialized SQL, MongoDB, Redis, table, or derived result keeps its
-immutable `q_*` `result_id` and receives a cryptographically random 10-character
-lowercase base32 `display_alias`. `ResultData.alias` normally equals that alias.
-When a batch command supplies `as`, `alias` remains the caller alias for backward
-compatibility while `display_alias` remains canonical. Generated aliases are
-session-scoped, allocated atomically with the result, stable on cache reuse, and
-cannot be reassigned by `setAlias`; explicit aliases and all old handles continue
-to resolve.
+immutable canonical `q_*` `result_id`. New canonical resource IDs use a
+cryptographically random 26-character lowercase base32 suffix; existing
+incremental IDs such as `q_121` remain valid and are not rewritten. Results also
+receive a random 10-character lowercase base32 `display_alias`.
+`ResultData.alias` normally equals that alias. When a batch command supplies
+`as`, `alias` remains the caller alias for backward compatibility while
+`display_alias` remains canonical. Generated aliases are session-scoped,
+allocated atomically with the result, stable on cache reuse, and cannot be
+reassigned by `setAlias`; explicit aliases and all old handles continue to
+resolve.
+
+Connections likewise retain canonical `conn_*` IDs with random 26-character
+suffixes and receive persistent random 10-character lowercase base32 aliases,
+exposed as `alias` and `display_alias` by `connect()` and
+`snapshot().connection` (optional in snapshot types for older producers).
+Connection aliases are unique within the state store, allocated atomically with
+the connection, and backfilled for existing records on startup. They survive
+reopening; reconnecting creates a new ID and alias. They are display identities
+only, separate from result aliases; internal references and lookups continue to
+use canonical connection IDs.
 
 ### Safe profile updates
 
@@ -562,19 +610,33 @@ updateProfile(name, {
   target?: string | null,
   secretEnv?: string | null,
   credentialRef?: string | null,
+  passwordRef?: string | null,
   readOnly?: boolean,
 })
 ```
 
-Omitting all source fields keeps the existing source. Supplying any source field
-replaces the source atomically: exactly one non-null source is required and the
-other source columns are cleared. Direct non-SQLite URLs containing credentials
-or secret-like query parameters are rejected. `profile.list/show/update` return
-only `{profile,target,secret_env,credential_ref,read_only}`. `target` is therefore
-a normalized SQLite path or a secret-free URL; reference-backed profiles expose
-only the environment-variable name or opaque credential reference, never a
-resolved value. Profile changes affect subsequent `connect` calls and do not
-silently mutate an already-open connection.
+Omitting all source and password-reference fields keeps the existing source and
+adjunct reference. Supplying any source field replaces the source atomically:
+exactly one non-null source is required and the other source columns are
+cleared. An omitted `passwordRef` is preserved when the existing literal target
+is unchanged; changing the target clears it unless the update explicitly supplies
+a replacement. Replacing the source with `secretEnv` or `credentialRef` clears
+it. An explicit non-null password reference combined with either
+reference-backed source is rejected. Direct URLs
+with embedded passwords or secret-like query parameters are rejected.
+`profile.list/show/update` return only
+`{profile,target,secret_env,credential_ref,password_ref,read_only}`. Profile
+changes affect subsequent `connect` calls and do not silently mutate an
+already-open connection.
+
+The `password_refs_v1` migration adds nullable `password_ref` columns to both
+profiles and connections and enforces that they accompany only literal target
+configuration. It rejects incompatible profile schemas/rows instead of dropping
+references. Downgrading a state home containing password references is
+unsupported: older binaries do not resolve this source and may attempt the
+password-free target using ambient/trust authentication; constraint-protected
+source replacements may also fail. Use the same or newer StateQL binary, or
+explicitly clear all password references before downgrade.
 
 ### Bounded catalog
 

package/dist/src/connection.d.ts

@@ -4,12 +4,18 @@ export declare function databaseIdentity(connection: ConnectionRecord): unknown;
 export declare function detectDriver(target: string): Driver;
 export declare function mongoDatabaseName(target: string): string;
 export declare function redisDatabaseName(target: string): string;
-export declare function credentialSource(value: string, expectedDriver?: Driver, referenceSource?: CredentialSource): {
+export declare function credentialSource(value: string, expectedDriver?: Driver, referenceSource?: Exclude<CredentialSource, "password_ref">): {
     driver: Driver;
     source: string;
 };
 export declare function normalizeSqliteSource(target: string): string;
 export declare function databaseUrlHasSecret(target: string): boolean;
+export declare function validatePasswordReferenceTarget(target: string): Driver;
+/** Injects only password userinfo while retaining every nonsecret target byte. */
+export declare function injectPassword(target: string, password: string): {
+    driver: Driver;
+    source: string;
+};
 export declare function version(connection: ConnectionRecord): string;
 export declare function confidence(connection: ConnectionRecord): StateConfidence;
 export declare function validateProfileName(name: string): void;

package/dist/src/connection.js

@@ -7,6 +7,7 @@ export function databaseIdentity(connection) {
         source: connection.source,
         secretEnvironment: connection.secret_env,
         credentialReference: connection.credential_ref,
+        passwordReference: connection.password_ref,
     };
 }
 export function detectDriver(target) {
@@ -24,22 +25,26 @@ export function detectDriver(target) {
     return "sqlite";
 }
 export function mongoDatabaseName(target) {
-    let url;
+    let pathname;
     try {
-        url = new URL(target);
+        const url = new URL(target);
+        if (!["mongodb:", "mongodb+srv:"].includes(url.protocol.toLowerCase()) || !url.hostname)
+            throw new Error();
+        pathname = url.pathname;
     }
     catch {
-        throw new StateQLError("INVALID_COMMAND", "Invalid MongoDB URL.");
-    }
-    if (!["mongodb:", "mongodb+srv:"].includes(url.protocol.toLowerCase()) ||
-        !url.hostname) {
-        throw new StateQLError("INVALID_COMMAND", "Invalid MongoDB URL.");
+        const match = /^mongodb(?:\+srv)?:\/\/([^/?#]+)(\/[^?#]*)?(?:[?#]|$)/i.exec(target);
+        if (!match)
+            throw new StateQLError("INVALID_COMMAND", "Invalid MongoDB URL.");
+        const authority = match[1];
+        const at = authority.lastIndexOf("@");
+        validateMongoHosts(authority.slice(at + 1), /^mongodb\+srv:/i.test(target));
+        pathname = match[2] ?? "";
     }
     try {
-        const database = decodeURIComponent(url.pathname.replace(/^\//, ""));
-        if (database && !database.includes("/") && !database.includes("\0")) {
+        const database = decodeURIComponent(pathname.replace(/^\//, ""));
+        if (database && !database.includes("/") && !database.includes("\0"))
             return database;
-        }
     }
     catch {
         // Report malformed escaping as an invalid explicit database name.
@@ -98,8 +103,15 @@ export function normalizeSqliteSource(target) {
 }
 export function databaseUrlHasSecret(target) {
     try {
-        const url = new URL(target);
-        return (Boolean(url.username) ||
+        const match = /^([a-z][a-z\d+.-]*:\/\/)([^/?#]*)([\s\S]*)$/i.exec(target);
+        if (!match)
+            throw new Error();
+        const authority = match[2];
+        const at = authority.lastIndexOf("@");
+        const url = /^mongodb(?:\+srv)?:\/\//i.test(target)
+            ? new URL(`http://placeholder${match[3]}`)
+            : new URL(target);
+        return ((at >= 0 && authority.slice(0, at).includes(":")) ||
             Boolean(url.password) ||
             [...url.searchParams.keys()].some((key) => /pass|token|secret|private[_-]?key|api[_-]?key/i.test(key)));
     }
@@ -107,6 +119,99 @@ export function databaseUrlHasSecret(target) {
         throw new StateQLError("INVALID_COMMAND", "Invalid database URL.");
     }
 }
+const AMBIGUOUS_PASSWORD_TARGET_PARAMETERS = new Set([
+    "host",
+    "hostaddr",
+    "hostname",
+    "port",
+    "socket",
+    "socketpath",
+    "user",
+    "username",
+]);
+export function validatePasswordReferenceTarget(target) {
+    if (/\s/.test(target)) {
+        throw new StateQLError("INVALID_COMMAND", "Password-reference target must not contain whitespace.");
+    }
+    const driver = detectDriver(target);
+    if (driver === "sqlite") {
+        throw new StateQLError("INVALID_COMMAND", "Password references require a remote PostgreSQL, MySQL, MongoDB, or Redis target.");
+    }
+    const authorityMatch = /^([a-z][a-z\d+.-]*:\/\/)([^/?#]*)([\s\S]*)$/i.exec(target);
+    if (!authorityMatch) {
+        throw new StateQLError("INVALID_COMMAND", "Password-reference target must be a valid remote database URL.");
+    }
+    const authority = authorityMatch[2];
+    const at = authority.lastIndexOf("@");
+    const userinfo = at >= 0 ? authority.slice(0, at) : "";
+    if (userinfo.includes(":") || userinfo.includes("@")) {
+        throw new StateQLError("PERMISSION_DENIED", "Password-reference target must not contain an embedded password.");
+    }
+    if (/%(?![0-9a-f]{2})/i.test(userinfo)) {
+        throw new StateQLError("INVALID_COMMAND", "Password-reference target contains malformed username escaping.");
+    }
+    try {
+        if (userinfo)
+            decodeURIComponent(userinfo);
+    }
+    catch {
+        throw new StateQLError("INVALID_COMMAND", "Password-reference target contains malformed username escaping.");
+    }
+    let url;
+    try {
+        if (driver === "mongodb") {
+            validateMongoHosts(authority.slice(at + 1), /^mongodb\+srv:/i.test(target));
+            url = new URL(`http://placeholder${authorityMatch[3]}`);
+        }
+        else {
+            url = new URL(target);
+            if (!url.hostname || url.password)
+                throw new Error();
+        }
+    }
+    catch {
+        throw new StateQLError("INVALID_COMMAND", "Password-reference target must be a valid remote database URL.");
+    }
+    for (const key of url.searchParams.keys()) {
+        const normalized = key.toLowerCase().replaceAll("_", "").replaceAll("-", "");
+        if (AMBIGUOUS_PASSWORD_TARGET_PARAMETERS.has(normalized) ||
+            /pass|token|secret|privatekey|apikey/.test(normalized)) {
+            throw new StateQLError("PERMISSION_DENIED", "Password-reference target must not contain endpoint or credential query overrides.");
+        }
+    }
+    if (driver === "mongodb" && !userinfo) {
+        throw new StateQLError("INVALID_COMMAND", "MongoDB password-reference targets require a username.");
+    }
+    return driver;
+}
+function validateMongoHosts(hosts, srv) {
+    const entries = hosts.split(",");
+    if (!hosts || (srv && entries.length !== 1) || entries.some((host) => {
+        if (srv)
+            return !/^[^:[\],%]+$/u.test(host);
+        return !(/^[^:[\],%]+(?::\d+)?$/u.test(host) || /^\[[0-9a-f:.]+\](?::\d+)?$/iu.test(host));
+    })) {
+        throw new StateQLError("INVALID_COMMAND", "Password-reference target must be a valid remote database URL.");
+    }
+}
+/** Injects only password userinfo while retaining every nonsecret target byte. */
+export function injectPassword(target, password) {
+    const driver = validatePasswordReferenceTarget(target);
+    let encoded;
+    try {
+        encoded = encodeURIComponent(password);
+    }
+    catch {
+        throw new StateQLError("CREDENTIAL_RESOLUTION_FAILED", "Resolved password could not be encoded.");
+    }
+    const match = /^([a-z][a-z\d+.-]*:\/\/)([^/?#]*)([\s\S]*)$/i.exec(target);
+    const authority = match[2];
+    const at = authority.lastIndexOf("@");
+    const injectedAuthority = at >= 0
+        ? `${authority.slice(0, at)}:${encoded}${authority.slice(at)}`
+        : `:${encoded}@${authority}`;
+    return { driver, source: `${match[1]}${injectedAuthority}${match[3]}` };
+}
 export function version(connection) {
     return `sv_${connection.version}`;
 }

package/dist/src/migrations.js

@@ -115,6 +115,22 @@ const MIGRATIONS = [
             requireIndexes(db, ["history_session_category"]);
         },
     },
+    {
+        name: "connection_aliases_v1",
+        apply(db) {
+            addColumn(db, "connections", "alias", "TEXT");
+            db.exec("CREATE UNIQUE INDEX IF NOT EXISTS connections_alias ON connections(alias)");
+        },
+        validate(db) {
+            requireColumns(db, "connections", ["alias"]);
+            requireIndexes(db, ["connections_alias"]);
+        },
+    },
+    {
+        name: "password_refs_v1",
+        apply: migratePasswordRefs,
+        validate: validatePasswordRefs,
+    },
 ];
 export function runMigrations(db, now) {
     db.exec(`
@@ -353,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) {
@@ -413,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,6 +1,8 @@
 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";
 export declare class StateQL {
+    /** Runtime contract marker for passwordRef/password_ref support. */
+    static readonly passwordReferenceVersion: 1;
     static forActor(options: StateQLActorOptions): StateQL;
     private readonly store;
     private readonly sessionName;