@fadhilp/stateql 0.7.0 → 0.8.0

package/README.md

@@ -76,12 +76,13 @@ 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`, or
-`--profile`.
+A connection accepts exactly one source: a direct target, `--env`,
+`--credential-ref`, or `--profile`.
 
 ```bash
 stql connect <sqlite-path|postgres-url|mysql-url|mongodb-url> [--name NAME] [--read-write]
 stql connect --env ENV [--name NAME] [--read-write]
+stql connect --credential-ref REF [--name NAME] [--read-write]
 stql connect --profile NAME
 stql disconnect
 stql status
@@ -113,19 +114,26 @@ connection metadata.
 
 ### Local profiles
 
-Profiles store connection targets, read-only policy, and environment-variable
-names. Credential values are never stored. Profiles persist under `STQL_HOME`
-with other StateQL metadata.
+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.
 
 ```bash
 stql profile add local ./app.sqlite --read-write
 stql profile add production --env PROD_DATABASE_URL --read-only
+stql profile add hosted --credential-ref 'vault://team/app' --read-only
 stql profile list
 stql profile show production
 stql connect local
 stql connect --profile production
 ```
 
+Credential references are bounded nonempty opaque strings; StateQL does not
+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.
+
 A bare connection target matching a profile name resolves to that profile;
 otherwise it remains a path or database URL.
 
@@ -464,8 +472,9 @@ for user confirmation before changing membership or the shared connection.
 
 ### 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`:
+Library integrations can resolve environment-variable names or opaque
+credential references through a trusted approval or secret-storage layer
+instead of mutating `process.env`:
 
 ```ts
 import {
@@ -479,6 +488,7 @@ async function resolveCredential(
 ): Promise<string | undefined> {
   const approved = await credentialBroker.request({
     reference: request.reference,
+    source: request.source ?? "secret_env",
     actor: request.actorId,
     session: request.session.id,
     operation: request.operation,
@@ -496,13 +506,16 @@ const stateql = StateQL.forActor({
 });
 ```
 
-When no custom resolver is configured, StateQL reads 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.
+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.
 
 StateQL calls the resolver only immediately before database access, after SQL
 safety and duplicate checks. Requests contain actor and session identity, the

package/dist/src/cli.js

@@ -13,6 +13,7 @@ const parsed = parseArgs({
         name: { type: "string" },
         profile: { type: "string" },
         env: { type: "string" },
+        "credential-ref": { type: "string" },
         "read-only": { type: "boolean" },
         "read-write": { type: "boolean" },
         params: { type: "string" },
@@ -143,6 +144,7 @@ async function dispatch() {
             return stateql.connect(subcommand, {
                 ...(values.name ? { name: values.name } : {}),
                 ...(values.env ? { secretEnv: values.env } : {}),
+                ...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
                 ...(values.profile ? { profile: values.profile } : {}),
                 ...(values["read-only"]
                     ? { readOnly: true }
@@ -282,6 +284,7 @@ async function dispatchProfile(action, args) {
             }
             return stateql.addProfile(requireValue(args[0], "profile name"), args[1], {
                 ...(values.env ? { secretEnv: values.env } : {}),
+                ...(values["credential-ref"] ? { credentialRef: values["credential-ref"] } : {}),
                 readOnly: !values["read-write"],
             });
         case "list":
@@ -576,9 +579,10 @@ function helpText() {
 Usage: stql <command> [arguments] [options]
 
 Commands:
-  connect, disconnect, status
-  profile add|list|show|remove
-  session start|list|show|summary|close
+  connect TARGET | --env ENV | --credential-ref REF | --profile NAME
+  disconnect, status
+  profile add NAME [TARGET | --env ENV | --credential-ref REF]
+  profile list|show|remove
   query, filter, exec, show, rows, count, columns, export
   mongo query|exec|plan '<EJSON command>'
   alias set
@@ -590,6 +594,7 @@ Commands:
 
 SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
 Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
+Credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
 State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
 Output: --output agent|json|jsonl|text|silent (default: agent).
 Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;

package/dist/src/connection.d.ts

@@ -1,9 +1,9 @@
 import type { ConnectionRecord } from "./store.js";
-import type { Driver, StateConfidence } from "./types.js";
+import type { CredentialSource, Driver, StateConfidence } from "./types.js";
 export declare function databaseIdentity(connection: ConnectionRecord): unknown;
 export declare function detectDriver(target: string): Driver;
 export declare function mongoDatabaseName(target: string): string;
-export declare function credentialSource(value: string, expectedDriver?: Driver): {
+export declare function credentialSource(value: string, expectedDriver?: Driver, referenceSource?: CredentialSource): {
     driver: Driver;
     source: string;
 };
@@ -13,3 +13,4 @@ export declare function version(connection: ConnectionRecord): string;
 export declare function confidence(connection: ConnectionRecord): StateConfidence;
 export declare function validateProfileName(name: string): void;
 export declare function isEnvironmentName(name: string): boolean;
+export declare function validateCredentialRef(reference: unknown): asserts reference is string;

package/dist/src/connection.js

@@ -6,6 +6,7 @@ export function databaseIdentity(connection) {
         database: connection.database_name,
         source: connection.source,
         secretEnvironment: connection.secret_env,
+        credentialReference: connection.credential_ref,
     };
 }
 export function detectDriver(target) {
@@ -43,11 +44,14 @@ export function mongoDatabaseName(target) {
     }
     throw new StateQLError("INVALID_COMMAND", "MongoDB URL must include an explicit database name.");
 }
-export function credentialSource(value, expectedDriver) {
+export function credentialSource(value, expectedDriver, referenceSource = "secret_env") {
+    const sourceLabel = referenceSource === "credential_ref"
+        ? "Credential reference"
+        : "Secret environment variable";
     const explicitSqlite = /^sqlite:(?!\/\/)/i.test(value);
     const driver = explicitSqlite ? "sqlite" : detectDriver(value);
     if (driver === "sqlite" && (!explicitSqlite || value.length === 7)) {
-        throw new StateQLError("INVALID_COMMAND", "Secret environment variable must contain a complete PostgreSQL/MySQL URL or an explicit sqlite: source; MongoDB URLs are also supported.", {
+        throw new StateQLError("INVALID_COMMAND", `${sourceLabel} must contain a complete PostgreSQL/MySQL URL or an explicit sqlite: source; MongoDB URLs are also supported.`, {
             suggestedAction: "Store the full database URL, or prefix an SQLite path with sqlite:.",
         });
     }
@@ -58,7 +62,7 @@ export function credentialSource(value, expectedDriver) {
                 throw new Error();
         }
         catch {
-            throw new StateQLError("INVALID_COMMAND", "Secret environment variable must contain a valid database URL.");
+            throw new StateQLError("INVALID_COMMAND", `${sourceLabel} must contain a valid database URL.`);
         }
     }
     if (expectedDriver && driver !== expectedDriver) {
@@ -101,3 +105,10 @@ export function validateProfileName(name) {
 export function isEnvironmentName(name) {
     return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name);
 }
+export function validateCredentialRef(reference) {
+    if (typeof reference === "string" &&
+        reference.trim().length > 0 &&
+        reference.length <= 1_024)
+        return;
+    throw new StateQLError("INVALID_COMMAND", "Credential reference must be a nonempty string of at most 1024 characters.");
+}

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
 export { StateQL } from "./stateql.js";
 export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
 export type { CredentialResolutionFailure } from "./errors.js";
-export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfilesData, PurgeData, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";
+export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialSource, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfilesData, PurgeData, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";

package/dist/src/migrations.js

@@ -75,6 +75,11 @@ const MIGRATIONS = [
             requireIndexes(db, ["history_session_origin"]);
         },
     },
+    {
+        name: "credential_refs_v1",
+        apply: migrateCredentialRefs,
+        validate: validateCredentialRefs,
+    },
 ];
 export function runMigrations(db, now) {
     db.exec(`
@@ -130,10 +135,15 @@ function createInitialSchema(db) {
       name TEXT PRIMARY KEY,
       target TEXT,
       secret_env TEXT,
+      credential_ref TEXT,
       read_only INTEGER NOT NULL,
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL,
-      CHECK(target IS NOT NULL OR secret_env IS NOT NULL)
+      CHECK (
+        (target IS NOT NULL) +
+        (secret_env IS NOT NULL) +
+        (credential_ref IS NOT NULL) = 1
+      )
     );
     CREATE TABLE IF NOT EXISTS connections (
       id TEXT PRIMARY KEY,
@@ -143,6 +153,7 @@ function createInitialSchema(db) {
       database_name TEXT NOT NULL,
       source TEXT NOT NULL,
       secret_env TEXT,
+      credential_ref TEXT,
       read_only INTEGER NOT NULL,
       version INTEGER NOT NULL,
       created_at TEXT NOT NULL,
@@ -301,6 +312,69 @@ function validateSharedSessionActors(db) {
             throw new Error(`State migration left ${table}.${column} empty.`);
     }
 }
+function migrateCredentialRefs(db) {
+    const profileColumns = new Set(db.prepare("PRAGMA table_info(profiles)").all().map((column) => column.name));
+    const hasCredentialRef = profileColumns.has("credential_ref");
+    if (!profileCredentialRefSchemaCurrent(db)) {
+        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) {
+            throw new Error("State migration found a profile without a connection source.");
+        }
+        const legacyCredentialRef = hasCredentialRef ? "credential_ref" : "NULL";
+        db.exec(`
+      ALTER TABLE profiles RENAME TO profiles_legacy_credential_refs_v1;
+      CREATE TABLE profiles (
+        name TEXT PRIMARY KEY,
+        target TEXT,
+        secret_env TEXT,
+        credential_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
+        )
+      );
+      INSERT INTO profiles
+        (name, target, secret_env, credential_ref, read_only, created_at, updated_at)
+      SELECT
+        name,
+        CASE
+          WHEN ${legacyCredentialRef} IS NULL AND secret_env IS NULL THEN target
+          ELSE NULL
+        END,
+        CASE WHEN ${legacyCredentialRef} IS NULL THEN secret_env ELSE NULL END,
+        ${legacyCredentialRef},
+        read_only,
+        created_at,
+        updated_at
+      FROM profiles_legacy_credential_refs_v1;
+      DROP TABLE profiles_legacy_credential_refs_v1;
+    `);
+    }
+    addColumn(db, "connections", "credential_ref", "TEXT");
+}
+function validateCredentialRefs(db) {
+    requireColumns(db, "profiles", ["credential_ref"]);
+    requireColumns(db, "connections", ["credential_ref"]);
+    if (!profileCredentialRefSchemaCurrent(db)) {
+        throw new Error("State migration did not enforce exactly one profile source.");
+    }
+    const invalid = db.prepare(`SELECT COUNT(*) AS count FROM profiles
+     WHERE (target IS NOT NULL) +
+           (secret_env IS NOT NULL) +
+           (credential_ref IS NOT NULL) != 1`).get();
+    if (invalid.count) {
+        throw new Error("State migration left a profile with ambiguous connection sources.");
+    }
+}
+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 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

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

package/dist/src/stateql.js

@@ -3,7 +3,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, normalizeSqliteSource, validateProfileName, version, } from "./connection.js";
+import { confidence, credentialSource, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, mongoDatabaseName, normalizeSqliteSource, validateCredentialRef, validateProfileName, version, } from "./connection.js";
 import { asStateQLError, CredentialResolutionError, StateQLError, } from "./errors.js";
 import { analyzeMongoWriteSafety, deserializeMongoWriteCommand, serializeMongoCommand, validateMongoReadCommand, validateMongoWriteCommand, MongoAdapter, } from "./mongodb.js";
 import { filterMaterializedRows, prepareFilterStatement, validateFilterParameters, } from "./filter.js";
@@ -90,12 +90,16 @@ export class StateQL {
             if (session.active_transaction_id) {
                 throw new StateQLError("TRANSACTION_FAILED", "Commit or roll back the active transaction before connecting again.");
             }
-            const sourceCount = [target, options.profile, options.secretEnv]
-                .filter((value) => value !== undefined).length;
-            if (sourceCount > 1) {
-                throw new StateQLError("INVALID_COMMAND", "Use exactly one connection target, profile, or secret environment variable.");
+            const sourceCount = [
+                target,
+                options.profile,
+                options.secretEnv,
+                options.credentialRef,
+            ].filter((value) => value !== undefined).length;
+            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 && target
+            const implicitProfile = !options.profile && !options.secretEnv && !options.credentialRef && target
                 ? this.store.getProfile(target)
                 : undefined;
             const profile = options.profile
@@ -104,16 +108,28 @@ export class StateQL {
             if (options.profile && !profile) {
                 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.`);
+            }
             const resolvedTarget = profile?.target ?? target;
             const secretEnv = options.secretEnv ?? profile?.secret_env ?? undefined;
-            if (secretEnv && !isEnvironmentName(secretEnv)) {
+            const credentialRef = options.credentialRef ?? profile?.credential_ref ?? undefined;
+            if (secretEnv !== undefined && !isEnvironmentName(secretEnv)) {
                 throw new StateQLError("INVALID_COMMAND", "Secret environment variable name is invalid.");
             }
+            if (credentialRef !== undefined)
+                validateCredentialRef(credentialRef);
+            const credentialReference = secretEnv ?? credentialRef;
+            const credentialReferenceSource = secretEnv !== undefined
+                ? "secret_env"
+                : credentialRef !== undefined ? "credential_ref" : undefined;
             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, {
+            const secret = credentialReference && credentialReferenceSource
+                ? await this.resolveCredential(credentialReference, credentialReferenceSource, session, "connect", readOnly ? "read" : "write", context, {
                     ...(profile ? { profile: { name: profile.name } } : {}),
                     requestedReadOnly: readOnly,
                 })
@@ -121,23 +137,23 @@ export class StateQL {
             if (!secret) {
                 throw new StateQLError("INVALID_COMMAND", "Connection target is required.");
             }
-            const resolvedSource = secretEnv
-                ? credentialSource(secret)
+            const resolvedSource = credentialReferenceSource
+                ? credentialSource(secret, undefined, credentialReferenceSource)
                 : { driver: detectDriver(secret), source: secret };
             const { driver } = resolvedSource;
             if (driver !== "sqlite" &&
-                !secretEnv &&
+                !credentialReference &&
                 databaseUrlHasSecret(secret)) {
-                throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env.`, {
-                    suggestedAction: "Set the URL in an environment variable and reconnect with --env NAME.",
+                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.",
                 });
             }
-            const adapterSource = secretEnv
+            const adapterSource = credentialReferenceSource
                 ? resolvedSource.source
                 : driver === "sqlite" ? normalizeSqliteSource(secret) : secret;
             const source = driver === "sqlite"
                 ? adapterSource
-                : secretEnv
+                : credentialReferenceSource
                     ? redact(secret)
                     : adapterSource;
             const databaseName = driver === "sqlite"
@@ -153,6 +169,7 @@ export class StateQL {
                 database_name: databaseName,
                 source,
                 secret_env: secretEnv ?? null,
+                credential_ref: credentialRef ?? null,
                 read_only: readOnly ? 1 : 0,
                 version: 0,
                 created_at: this.now().toISOString(),
@@ -180,6 +197,7 @@ export class StateQL {
                 databaseName,
                 source,
                 ...(secretEnv ? { secretEnv } : {}),
+                ...(credentialRef ? { credentialRef } : {}),
                 readOnly,
             });
             if (!connection) {
@@ -206,20 +224,25 @@ export class StateQL {
     async addProfile(name, target, options = {}) {
         return this.run("profile.add", async () => {
             validateProfileName(name);
-            if (Boolean(target) === Boolean(options.secretEnv)) {
-                throw new StateQLError("INVALID_COMMAND", "Profile requires exactly one target or secret environment variable.");
+            const sourceCount = [target, options.secretEnv, options.credentialRef]
+                .filter((value) => value !== undefined).length;
+            if (sourceCount !== 1 || target === "") {
+                throw new StateQLError("INVALID_COMMAND", "Profile requires exactly one target, secret environment variable, or credential reference.");
             }
             if (this.store.getProfile(name)) {
                 throw new StateQLError("INVALID_COMMAND", `Profile "${name}" already exists.`);
             }
-            if (options.secretEnv && !isEnvironmentName(options.secretEnv)) {
+            if (options.secretEnv !== undefined && !isEnvironmentName(options.secretEnv)) {
                 throw new StateQLError("INVALID_COMMAND", "Secret environment variable name is invalid.");
             }
+            if (options.credentialRef !== undefined) {
+                validateCredentialRef(options.credentialRef);
+            }
             let storedTarget = target;
             if (target) {
                 const driver = detectDriver(target);
                 if (driver !== "sqlite" && databaseUrlHasSecret(target)) {
-                    throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env.`);
+                    throw new StateQLError("PERMISSION_DENIED", `Credential-bearing ${databaseDisplayName(driver)} URLs must use --env or --credential-ref.`);
                 }
                 if (driver === "sqlite")
                     storedTarget = normalizeSqliteSource(target);
@@ -228,6 +251,7 @@ export class StateQL {
                 name,
                 target: storedTarget,
                 secretEnv: options.secretEnv,
+                credentialRef: options.credentialRef,
                 readOnly: options.readOnly ?? true,
             });
             return {
@@ -1387,6 +1411,7 @@ export class StateQL {
                             name: command.name,
                             readOnly: command.read_only,
                             secretEnv: command.secret_env,
+                            credentialRef: command.credential_ref,
                             profile: command.profile,
                             timeoutMs: command.timeout_ms,
                         });
@@ -1398,6 +1423,7 @@ export class StateQL {
                         return this.addProfile(batchString(command.name, "name"), command.target, {
                             readOnly: command.read_only ?? true,
                             secretEnv: command.secret_env,
+                            credentialRef: command.credential_ref,
                         });
                     case "profile.list":
                         return this.listProfiles();
@@ -2022,9 +2048,13 @@ 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) {
-        if (!connection.secret_env)
+        const reference = connection.secret_env ?? connection.credential_ref;
+        if (!reference)
             return connection.source;
-        const value = await this.resolveCredential(connection.secret_env, session, operation, access, context, {
+        const source = connection.secret_env
+            ? "secret_env"
+            : "credential_ref";
+        const value = await this.resolveCredential(reference, source, session, operation, access, context, {
             connection: {
                 id: connection.id,
                 name: connection.name,
@@ -2033,9 +2063,9 @@ export class StateQL {
                 readOnly: Boolean(connection.read_only),
             },
         });
-        return credentialSource(value, connection.driver).source;
+        return credentialSource(value, connection.driver, source).source;
     }
-    async resolveCredential(reference, session, operation, access, context, details = {}) {
+    async resolveCredential(reference, source, session, operation, access, context, details = {}) {
         const resolver = this.credentialResolver;
         if (!resolver) {
             if (context.signal?.aborted) {
@@ -2044,13 +2074,16 @@ export class StateQL {
             if (context.deadline <= Date.now()) {
                 throw credentialStateQLError(reference, new CredentialResolutionError("timeout"));
             }
-            const value = env[reference];
-            if (value)
-                return value;
+            if (source === "secret_env") {
+                const value = env[reference];
+                if (value)
+                    return value;
+            }
             throw credentialStateQLError(reference, new CredentialResolutionError("unavailable"));
         }
         const request = {
             reference,
+            source,
             actorId: this.actorId,
             session: { id: session.id, name: session.name },
             operation,

package/dist/src/store.d.ts

@@ -17,6 +17,7 @@ export interface ConnectionRecord {
     database_name: string;
     source: string;
     secret_env: string | null;
+    credential_ref: string | null;
     read_only: number;
     version: number;
     created_at: string;
@@ -25,6 +26,7 @@ export interface ProfileRecord {
     name: string;
     target: string | null;
     secret_env: string | null;
+    credential_ref: string | null;
     read_only: number;
     created_at: string;
     updated_at: string;
@@ -136,6 +138,7 @@ export declare class StateStore {
         name: string;
         target?: string;
         secretEnv?: string;
+        credentialRef?: string;
         readOnly: boolean;
     }): ProfileRecord;
     getProfile(name: string): ProfileRecord | undefined;
@@ -149,6 +152,7 @@ export declare class StateStore {
         databaseName: string;
         source: string;
         secretEnv?: string;
+        credentialRef?: string;
         readOnly: boolean;
     }): ConnectionRecord | undefined;
     getConnection(id: string): ConnectionRecord | undefined;

package/dist/src/store.js

@@ -235,9 +235,9 @@ export class StateStore {
         const timestamp = this.now().toISOString();
         this.db
             .prepare(`INSERT INTO profiles
-          (name, target, secret_env, read_only, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?)`)
-            .run(input.name, input.target ?? null, input.secretEnv ?? null, input.readOnly ? 1 : 0, timestamp, timestamp);
+          (name, target, secret_env, credential_ref, read_only, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`)
+            .run(input.name, input.target ?? null, input.secretEnv ?? null, input.credentialRef ?? null, input.readOnly ? 1 : 0, timestamp, timestamp);
         return this.getProfile(input.name);
     }
     getProfile(name) {
@@ -274,9 +274,9 @@ export class StateStore {
             this.db
                 .prepare(`INSERT INTO connections
             (id, session_id, name, driver, database_name, source, secret_env,
-             read_only, version, created_at)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, ?)`)
-                .run(id, input.sessionId, input.name, input.driver, input.databaseName, input.source, input.secretEnv ?? null, input.readOnly ? 1 : 0, timestamp);
+             credential_ref, read_only, version, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0, ?)`)
+                .run(id, input.sessionId, input.name, input.driver, input.databaseName, input.source, input.secretEnv ?? null, input.credentialRef ?? null, input.readOnly ? 1 : 0, timestamp);
             this.db
                 .prepare(`UPDATE sessions
            SET active_connection_id = ?, updated_at = ?
@@ -415,6 +415,8 @@ export class StateStore {
              AND previous_connection.source = current_connection.source
              AND COALESCE(previous_connection.secret_env, '') =
                  COALESCE(current_connection.secret_env, '')
+             AND COALESCE(previous_connection.credential_ref, '') =
+                 COALESCE(current_connection.credential_ref, '')
              AND previous_connection.database_name = current_connection.database_name
            ORDER BY operations.created_at DESC LIMIT 1`)
                 .get(input.connectionId, input.idempotencyKey);

package/dist/src/types.d.ts

@@ -8,7 +8,8 @@ export interface CommandExecutionContext {
 }
 export type CredentialAccess = "read" | "write";
 export type CredentialOperation = "connect" | "query" | "inspect" | "plan" | "exec" | "apply" | "transaction.commit";
-export interface CredentialRequest {
+export type CredentialSource = "secret_env" | "credential_ref";
+interface CredentialRequestBase {
     reference: string;
     actorId: string;
     session: {
@@ -30,6 +31,12 @@ export interface CredentialRequest {
         readOnly: boolean;
     };
 }
+/** Omitted source remains backward-compatible with legacy secret_env requests. */
+export type CredentialRequest = CredentialRequestBase & ({
+    source?: "secret_env";
+} | {
+    source: "credential_ref";
+});
 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 {
@@ -239,10 +246,12 @@ export interface ConnectOptions extends ExecutionOptions {
     readOnly?: boolean;
     secretEnv?: string;
     profile?: string;
+    credentialRef?: string;
 }
 export interface ProfileOptions {
     readOnly?: boolean;
     secretEnv?: string;
+    credentialRef?: string;
 }
 export interface RowsOptions {
     offset?: number;
@@ -273,6 +282,7 @@ export interface BatchCommand {
     cache?: "auto" | "bypass" | "require";
     read_only?: boolean;
     secret_env?: string;
+    credential_ref?: string;
     profile?: string;
     replay?: boolean;
     idempotency_key?: string;
@@ -311,6 +321,7 @@ export interface ProfileData {
     profile: string;
     target: string | null;
     secret_env: string | null;
+    credential_ref: string | null;
     read_only: boolean;
 }
 export interface ProfilesData {
@@ -534,3 +545,4 @@ export interface CloseSessionData {
     session_id: string;
     state: string;
 }
+export {};

package/package.json

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