@fadhilp/stateql 0.10.0 → 0.11.0

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";
@@ -18,6 +18,8 @@ const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
 const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
 const DEFAULT_CREDENTIAL_RESOLUTION_TIMEOUT_MS = 120_000;
 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.");
@@ -112,7 +114,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 +130,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 +158,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 +244,10 @@ export class StateQL {
                 name: draft.name,
                 driver,
                 databaseName,
-                source,
+                source: persistedSource,
                 ...(secretEnv ? { secretEnv } : {}),
                 ...(credentialRef ? { credentialRef } : {}),
+                ...(passwordRef !== undefined ? { passwordRef } : {}),
                 readOnly,
             });
             if (!connection) {
@@ -223,6 +256,8 @@ export class StateQL {
             return {
                 data: {
                     connection_id: connection.id,
+                    alias: connection.alias,
+                    display_alias: connection.alias,
                     driver,
                     database: databaseName,
                     name: connection.name,
@@ -248,12 +283,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 {
@@ -270,22 +307,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)
@@ -368,6 +415,8 @@ export class StateQL {
             connection: connection
                 ? {
                     connection_id: connection.id,
+                    alias: connection.alias,
+                    display_alias: connection.alias,
                     name: connection.name,
                     status: "connected",
                     driver: connection.driver,
@@ -1707,7 +1756,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.");
@@ -1896,6 +1945,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,
                         });
@@ -1908,12 +1958,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":
@@ -2714,6 +2766,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;
@@ -2731,7 +2805,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;
@@ -2746,9 +2820,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,
@@ -2756,6 +2829,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);
             }
@@ -2763,7 +2839,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);
@@ -2840,8 +2916,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,
@@ -2857,8 +2933,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,
@@ -2874,7 +2949,7 @@ export class StateQL {
             });
             return {
                 ok: true,
-                command_id: commandId,
+                command_id: history.id,
                 session_id: responseSession.id,
                 data: result.data,
                 warnings: result.warnings ?? [],
@@ -2892,8 +2967,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,
@@ -2909,7 +2983,7 @@ export class StateQL {
             });
             return {
                 ok: false,
-                command_id: commandId,
+                command_id: history.id,
                 session_id: session.id,
                 error: stateqlError.details,
                 meta: {
@@ -3210,7 +3284,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") {
@@ -3232,15 +3322,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))

package/dist/src/store.d.ts

@@ -11,6 +11,7 @@ export interface SessionRecord {
 }
 export interface ConnectionRecord {
     id: string;
+    alias?: string;
     session_id: string;
     name: string;
     driver: Driver;
@@ -18,6 +19,7 @@ export interface ConnectionRecord {
     source: string;
     secret_env: string | null;
     credential_ref: string | null;
+    password_ref: string | null;
     read_only: number;
     version: number;
     created_at: string;
@@ -27,6 +29,7 @@ export interface ProfileRecord {
     target: string | null;
     secret_env: string | null;
     credential_ref: string | null;
+    password_ref: string | null;
     read_only: number;
     created_at: string;
     updated_at: string;
@@ -125,7 +128,8 @@ export declare class StateStore {
     private closed;
     constructor(home: string, now: () => Date, maxStateBytes?: number);
     close(): void;
-    nextId(prefix: string): string;
+    randomId(prefix: string): string;
+    private insertWithRandomId;
     ensureSession(name?: string): SessionRecord;
     bootstrapSession(name: string, actorId: string, ensureLegacyMembership: boolean): SessionRecord;
     createSession(name: string): SessionRecord;
@@ -143,6 +147,7 @@ export declare class StateStore {
         target?: string;
         secretEnv?: string;
         credentialRef?: string;
+        passwordRef?: string;
         readOnly: boolean;
     }): ProfileRecord;
     updateProfile(input: {
@@ -150,6 +155,7 @@ export declare class StateStore {
         target: string | null;
         secretEnv: string | null;
         credentialRef: string | null;
+        passwordRef: string | null;
         readOnly: boolean;
     }): ProfileRecord | undefined;
     getProfile(name: string): ProfileRecord | undefined;
@@ -164,8 +170,11 @@ export declare class StateStore {
         source: string;
         secretEnv?: string;
         credentialRef?: string;
+        passwordRef?: string;
         readOnly: boolean;
     }): ConnectionRecord | undefined;
+    private allocateConnectionAlias;
+    private backfillConnectionAliases;
     getConnection(id: string): ConnectionRecord | undefined;
     activeConnection(session: SessionRecord): ConnectionRecord | undefined;
     disconnect(sessionId: string, actorId: string): boolean;