@penclipai/server 2026.704.0 → 2026.714.0

package/dist/services/secrets.js

@@ -1,12 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { and, desc, eq, inArray, like, ne, notInArray, or, sql } from "drizzle-orm";
-import { agents, companySecretBindings, companySecretProviderConfigs, companySecrets, companySecretVersions, environments, heartbeatRuns, issues, projects, routines, secretAccessEvents, } from "@penclipai/db";
+import { agents, companySecretBindings, companySecretProviderConfigs, companySecrets, companySecretVersions, companyMemberships, environments, heartbeatRuns, issues, projects, routines, secretAccessEvents, userSecretDeclarations, userSecretDefinitions, } from "@penclipai/db";
 import { createSecretProviderConfigSchema, deriveProjectUrlKey, envBindingSchema, isUuidLike, normalizeAgentUrlKey, secretProviderConfigPayloadSchema, secretProviderConfigDiscoveryPreviewSchema, updateSecretProviderConfigSchema, } from "@penclipai/shared";
 import { conflict, forbidden, HttpError, notFound, unprocessable } from "../errors.js";
 import { logger } from "../middleware/logger.js";
 import { checkSecretProviders, getSecretProvider, listSecretProviders, } from "../secrets/provider-registry.js";
 import { isSecretProviderClientError } from "../secrets/types.js";
-import { authorizationService } from "./authorization.js";
+import { authorizationDeniedDetails, authorizationService } from "./authorization.js";
 import { findActiveServerAdapter } from "../adapters/index.js";
 const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const SENSITIVE_ENV_KEY_RE = /(api[-_]?key|access[-_]?token|auth(?:_?token)?|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)/i;
@@ -18,6 +18,21 @@ const COMING_SOON_SECRET_PROVIDERS = new Set([
 const FALLBACK_ADAPTER_SCHEMA_SECRET_FIELDS = {
     hermes_gateway: ["apiKey"],
 };
+const USER_SECRET_DEFINITION_KEY_UNIQUE_CONSTRAINT = "user_secret_definitions_company_key_uq";
+const USER_SECRET_VALUE_UNIQUE_CONSTRAINT = "company_secrets_user_definition_owner_uq";
+function isUniqueConstraintViolation(error, constraintName) {
+    const seen = new Set();
+    let current = error;
+    while (typeof current === "object" && current !== null && !seen.has(current)) {
+        seen.add(current);
+        const maybe = current;
+        const constraint = maybe.constraint ?? maybe.constraint_name;
+        if (maybe.code === "23505" && constraint === constraintName)
+            return true;
+        current = maybe.cause;
+    }
+    return false;
+}
 function remoteProviderHttpError(error, context) {
     if (isSecretProviderClientError(error)) {
         logger.warn({
@@ -42,10 +57,110 @@ function remoteProviderHttpError(error, context) {
     }, "remote secret provider request failed");
     return new HttpError(502, "Remote secret provider request failed.", safeRemoteProviderErrorDetails(null, context));
 }
+function remoteProviderWriteHttpError(error, context) {
+    return remoteProviderHttpError(error, {
+        companyId: context.companyId,
+        provider: context.provider,
+        providerConfigId: context.providerConfig?.id ?? context.providerConfigId ?? "deployment-default",
+        operation: context.operation,
+        providerConfig: context.providerConfig?.config ?? null,
+    });
+}
+async function throwProviderWriteOrReservedRowRollbackError(input) {
+    const providerError = remoteProviderWriteHttpError(input.error, input);
+    try {
+        await input.rollbackReservedRow();
+    }
+    catch (rollbackError) {
+        const providerConfigId = input.providerConfig?.id ?? input.providerConfigId ?? "deployment-default";
+        logger.warn({
+            err: rollbackError,
+            providerErr: providerError,
+            companyId: input.companyId,
+            provider: input.provider,
+            providerConfigId,
+            operation: input.operation,
+        }, "remote secret provider write failed and reserved secret rollback failed");
+        throw new HttpError(500, "Secret create failed and Paperclip could not roll back the local secret reservation.", {
+            code: "secret_create_rollback_failed",
+            provider: input.provider,
+            operation: input.operation,
+            providerConfigId,
+            providerError: {
+                status: providerError.status,
+                message: providerError.message,
+                details: providerError.details ?? null,
+            },
+        });
+    }
+    throw providerError;
+}
+function providerConfigIdentifier(input) {
+    return input.providerConfig?.id ?? input.providerConfigId ?? "deployment-default";
+}
+async function deleteLocalSecretCreateReservationOrThrow(input) {
+    try {
+        await input.db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, input.secretId));
+        await input.db.delete(companySecrets).where(eq(companySecrets.id, input.secretId));
+    }
+    catch (rollbackError) {
+        const providerConfigId = providerConfigIdentifier(input);
+        logger.warn({
+            err: rollbackError,
+            companyId: input.companyId,
+            provider: input.provider,
+            providerConfigId,
+            operation: input.operation,
+        }, "secret create failed and local reserved secret rollback failed");
+        throw new HttpError(500, "Secret create failed and Paperclip could not roll back the local secret reservation.", {
+            code: "secret_create_rollback_failed",
+            provider: input.provider,
+            operation: input.operation,
+            providerConfigId,
+        });
+    }
+}
+function throwProviderCleanupFailedAfterCreateRollback(input) {
+    const providerConfigId = providerConfigIdentifier(input);
+    throw new HttpError(500, "Secret create failed and Paperclip could not clean up the remote provider secret.", {
+        code: "secret_create_provider_cleanup_failed",
+        provider: input.provider,
+        operation: input.operation,
+        providerConfigId,
+        localCleanupHandle: true,
+    });
+}
 function safeRemoteProviderErrorDetails(error, context) {
     if (context.provider !== "aws_secrets_manager" ||
         context.operation !== "secret_provider_config.discovery.preview") {
-        return { code: error?.code ?? "provider_error" };
+        if (context.provider !== "aws_secrets_manager") {
+            return { code: error?.code ?? "provider_error" };
+        }
+        const details = {
+            code: error?.code ?? "provider_error",
+            provider: context.provider,
+            operation: context.operation,
+            providerConfigId: context.providerConfigId,
+        };
+        const region = safeString(context.providerConfig?.region);
+        if (region)
+            details.region = region;
+        details.credentialPath = "Paperclip server runtime/provider credential path";
+        if (error?.code === "access_denied") {
+            if (context.operation === "secret.create") {
+                details.requiredCapability = "secretsmanager:CreateSecret";
+                details.actionableMessage =
+                    "AWS managed secret creation needs secretsmanager:CreateSecret in the selected region for this provider vault. If the vault config uses a KMS key, the runtime credentials also need KMS write permissions for that key.";
+                details.safeAlternative =
+                    "If the secret already exists in AWS, link it as an external reference instead of creating a Paperclip-managed value.";
+            }
+            else if (context.operation === "secret.rotate") {
+                details.requiredCapability = "secretsmanager:PutSecretValue";
+                details.actionableMessage =
+                    "AWS managed secret rotation needs secretsmanager:PutSecretValue for the selected provider vault and managed secret path.";
+            }
+        }
+        return details;
     }
     const details = {
         code: error?.code ?? "provider_error",
@@ -145,6 +260,15 @@ function canonicalizeBinding(binding) {
     if (binding.type === "plain") {
         return { type: "plain", value: String(binding.value) };
     }
+    if (binding.type === "user_secret_ref") {
+        return {
+            type: "user_secret_ref",
+            key: binding.key,
+            version: binding.version ?? "latest",
+            required: binding.required ?? true,
+            allowMissingOverride: binding.allowMissingOverride ?? false,
+        };
+    }
     return {
         type: "secret_ref",
         secretId: binding.secretId,
@@ -170,6 +294,18 @@ function secretResolutionErrorCode(error) {
         }
         if (error.message === "Secret is not active")
             return "secret_inactive";
+        if (error.message === "User secret value is not configured")
+            return "user_secret_missing";
+        if (error.message === "Responsible user is required for user secret resolution") {
+            return "responsible_user_missing";
+        }
+        if (error.message === "User secret definition not found")
+            return "user_secret_definition_missing";
+        if (error.message === "User secret definition is not active")
+            return "user_secret_definition_inactive";
+        if (error.message === "User-scoped secrets must be resolved through user secret declarations") {
+            return "secret_scope_invalid";
+        }
         if (error.message === "Secret version not found")
             return "version_missing";
         if (error.message === "Secret version is not active")
@@ -183,6 +319,22 @@ function secretResolutionErrorCode(error) {
     }
     return "provider_error";
 }
+function missingUserSecretDefinitionRuntimeBinding(entry, context, definition, errorCode) {
+    return {
+        consumerType: context.consumerType,
+        consumerId: context.consumerId,
+        configPath: entry.configPath,
+        envKey: entry.key,
+        bindingType: "user_secret_ref",
+        secretId: null,
+        secretName: null,
+        userSecretDefinitionId: definition?.id ?? null,
+        userSecretDefinitionKey: definition?.key ?? entry.binding.key,
+        userSecretDefinitionName: definition?.name ?? null,
+        responsibleUserId: context.responsibleUserId ?? null,
+        errorCode,
+    };
+}
 function assertSelectableProviderConfig(config, companyId, provider) {
     if (config.companyId !== companyId)
         throw unprocessable("Provider vault must belong to same company");
@@ -208,9 +360,54 @@ export function secretService(db) {
         return db
             .select()
             .from(companySecrets)
-            .where(and(eq(companySecrets.companyId, companyId), eq(companySecrets.name, name), ne(companySecrets.status, "deleted")))
+            .where(and(eq(companySecrets.companyId, companyId), eq(companySecrets.scope, "company"), eq(companySecrets.name, name), ne(companySecrets.status, "deleted")))
+            .then((rows) => rows[0] ?? null);
+    }
+    async function getUserSecretDefinitionById(companyId, definitionId, source = db) {
+        return source
+            .select()
+            .from(userSecretDefinitions)
+            .where(and(eq(userSecretDefinitions.companyId, companyId), eq(userSecretDefinitions.id, definitionId)))
+            .then((rows) => rows[0] ?? null);
+    }
+    async function getUserSecretDefinitionByKey(companyId, key, source = db) {
+        return source
+            .select()
+            .from(userSecretDefinitions)
+            .where(and(eq(userSecretDefinitions.companyId, companyId), eq(userSecretDefinitions.key, key), ne(userSecretDefinitions.status, "deleted")))
+            .then((rows) => rows[0] ?? null);
+    }
+    async function resolveUserSecretDefinition(companyId, input, source = db) {
+        const definition = input.definitionId
+            ? await getUserSecretDefinitionById(companyId, input.definitionId, source)
+            : input.definitionKey
+                ? await getUserSecretDefinitionByKey(companyId, input.definitionKey, source)
+                : null;
+        if (!definition || definition.deletedAt || definition.status === "deleted") {
+            throw notFound("User secret definition not found");
+        }
+        if (definition.companyId !== companyId) {
+            throw unprocessable("User secret definition must belong to same company");
+        }
+        return definition;
+    }
+    async function getUserSecretValue(input) {
+        return db
+            .select()
+            .from(companySecrets)
+            .where(and(eq(companySecrets.companyId, input.companyId), eq(companySecrets.scope, "user"), eq(companySecrets.ownerUserId, input.ownerUserId), eq(companySecrets.userSecretDefinitionId, input.definitionId), ne(companySecrets.status, "deleted")))
             .then((rows) => rows[0] ?? null);
     }
+    async function getUserSecretValueById(companyId, ownerUserId, secretId) {
+        const secret = await getById(secretId);
+        if (!secret || secret.status === "deleted" || secret.scope !== "user") {
+            throw notFound("User secret value not found");
+        }
+        if (secret.companyId !== companyId || secret.ownerUserId !== ownerUserId) {
+            throw notFound("User secret value not found");
+        }
+        return secret;
+    }
     async function getSecretVersion(secretId, version) {
         return db
             .select()
@@ -253,8 +450,14 @@ export function secretService(db) {
         await db.insert(secretAccessEvents).values({
             companyId: input.companyId,
             secretId: input.secretId,
+            userSecretDefinitionId: input.userSecretDefinitionId ?? null,
+            secretScope: input.secretScope ?? "company",
             version: input.version,
             provider: input.provider,
+            responsibleUserId: input.context.responsibleUserId ?? null,
+            credentialOwnerUserId: input.credentialOwnerUserId ?? null,
+            credentialSubjectType: input.credentialSubjectType ?? null,
+            credentialSubjectId: input.credentialSubjectId ?? null,
             actorType: input.context.actorType ?? "system",
             actorId: input.context.actorId ?? null,
             consumerType: input.context.consumerType,
@@ -275,6 +478,8 @@ export function secretService(db) {
             throw notFound("Secret not found");
         if (secret.companyId !== companyId)
             throw unprocessable("Secret must belong to same company");
+        if (secret.scope !== "company")
+            throw unprocessable("Secret references require company-scoped secrets");
         return secret;
     }
     async function getProviderConfigById(id) {
@@ -377,6 +582,11 @@ export function secretService(db) {
             throw notFound("Secret not found");
         if (secret.companyId !== companyId)
             throw unprocessable("Secret must belong to same company");
+        if (secret.scope !== "company" && !options?.allowUserSecretScope) {
+            throw unprocessable("User-scoped secrets must be resolved through user secret declarations", {
+                code: "secret_scope_invalid",
+            });
+        }
         const resolvedVersion = version === "latest" ? secret.latestVersion : version;
         const providerId = secret.provider;
         const configPath = accessContext?.configPath ?? null;
@@ -421,9 +631,14 @@ export function secretService(db) {
                 recordAccessEvent({
                     companyId,
                     secretId: secret.id,
+                    userSecretDefinitionId: secret.userSecretDefinitionId ?? null,
+                    secretScope: secret.scope,
                     version: resolvedVersion,
                     provider: providerId,
                     context: accessContext,
+                    credentialOwnerUserId: secret.ownerUserId ?? null,
+                    credentialSubjectType: secret.scope === "user" ? "user" : null,
+                    credentialSubjectId: secret.ownerUserId ?? null,
                     outcome: "success",
                 }).catch(() => undefined),
             ]);
@@ -447,9 +662,14 @@ export function secretService(db) {
             await recordAccessEvent({
                 companyId,
                 secretId: secret.id,
+                userSecretDefinitionId: secret.userSecretDefinitionId ?? null,
+                secretScope: secret.scope,
                 version: resolvedVersion,
                 provider: providerId,
                 context: accessContext,
+                credentialOwnerUserId: secret.ownerUserId ?? null,
+                credentialSubjectType: secret.scope === "user" ? "user" : null,
+                credentialSubjectId: secret.ownerUserId ?? null,
                 outcome: "failure",
                 errorCode,
             }).catch(() => undefined);
@@ -494,7 +714,7 @@ export function secretService(db) {
             resource: { type: "company", companyId },
         });
         if (!decision.allowed) {
-            throw forbidden(decision.explanation);
+            throw forbidden(decision.explanation, authorizationDeniedDetails(decision));
         }
         return (await resolveSecretValueInternal(companyId, secretId, version, {
             accessContext: context,
@@ -524,6 +744,10 @@ export function secretService(db) {
                 normalized[key] = binding;
                 continue;
             }
+            if (binding.type === "user_secret_ref") {
+                normalized[key] = binding;
+                continue;
+            }
             await assertSecretInCompany(companyId, binding.secretId);
             normalized[key] = {
                 type: "secret_ref",
@@ -594,6 +818,9 @@ export function secretService(db) {
                 version: binding.version,
             };
         }
+        if (binding.type === "user_secret_ref") {
+            throw unprocessable(`${input.key} must be a string, plain binding, or company secret reference`);
+        }
         const value = binding.value.trim();
         if (!value)
             return undefined;
@@ -625,7 +852,7 @@ export function secretService(db) {
         const duplicateKey = await db
             .select()
             .from(companySecrets)
-            .where(and(eq(companySecrets.companyId, companyId), eq(companySecrets.key, key), ne(companySecrets.status, "deleted")))
+            .where(and(eq(companySecrets.companyId, companyId), eq(companySecrets.scope, "company"), eq(companySecrets.key, key), ne(companySecrets.status, "deleted")))
             .then((rows) => rows[0] ?? null);
         if (duplicateKey)
             throw conflict(`Secret key already exists: ${key}`);
@@ -946,6 +1173,238 @@ export function secretService(db) {
         assertSelectableProviderConfig(providerConfig, companyId, provider);
         return { providerConfig, provider, runtimeConfig: toProviderVaultRuntimeConfig(providerConfig) };
     }
+    async function createUserSecretValueInternal(companyId, ownerUserId, input, actor) {
+        const definition = await resolveUserSecretDefinition(companyId, input);
+        if (definition.status !== "active") {
+            throw unprocessable("User secret definition is not active");
+        }
+        const existing = await getUserSecretValue({
+            companyId,
+            ownerUserId,
+            definitionId: definition.id,
+        });
+        if (existing)
+            throw conflict("User secret value already exists");
+        const providerId = definition.provider;
+        const managedMode = definition.managedMode;
+        if (managedMode === "external_reference" && !input.externalRef?.trim()) {
+            throw unprocessable("External reference user secrets require externalRef");
+        }
+        if (managedMode === "paperclip_managed" && input.externalRef?.trim()) {
+            throw unprocessable("Managed user secrets cannot override externalRef");
+        }
+        if (managedMode === "paperclip_managed" && !input.value?.trim()) {
+            throw unprocessable("Managed user secrets require value");
+        }
+        const providerConfigId = input.providerConfigId === undefined ? definition.providerConfigId : input.providerConfigId;
+        const provider = getSecretProvider(providerId);
+        const providerConfig = await getSelectableRuntimeProviderConfig({
+            companyId,
+            provider: providerId,
+            providerConfigId,
+        });
+        const idSuffix = randomUUID();
+        const key = normalizeSecretKey(`user.${definition.key}.${idSuffix}`);
+        const name = `${definition.name} (${ownerUserId})`;
+        const providerWriteContext = {
+            companyId,
+            secretKey: key,
+            secretName: definition.name,
+            version: 1,
+        };
+        let reservedSecret;
+        try {
+            reservedSecret = await db
+                .insert(companySecrets)
+                .values({
+                companyId,
+                scope: "user",
+                ownerUserId,
+                userSecretDefinitionId: definition.id,
+                key,
+                name,
+                provider: providerId,
+                providerConfigId: providerConfigId ?? null,
+                status: "archived",
+                managedMode,
+                externalRef: null,
+                providerMetadata: definition.providerMetadata ?? null,
+                latestVersion: 0,
+                description: definition.description ?? null,
+                createdByAgentId: actor?.agentId ?? null,
+                createdByUserId: actor?.userId ?? null,
+            })
+                .returning()
+                .then((rows) => rows[0]);
+        }
+        catch (error) {
+            if (isUniqueConstraintViolation(error, USER_SECRET_VALUE_UNIQUE_CONSTRAINT)) {
+                throw conflict("User secret value already exists");
+            }
+            throw error;
+        }
+        let prepared;
+        try {
+            prepared =
+                managedMode === "external_reference"
+                    ? await provider.linkExternalSecret({
+                        externalRef: input.externalRef ?? "",
+                        providerVersionRef: input.providerVersionRef ?? null,
+                        providerConfig,
+                        context: providerWriteContext,
+                    })
+                    : await provider.createSecret({
+                        value: input.value ?? "",
+                        externalRef: null,
+                        providerConfig,
+                        context: providerWriteContext,
+                    });
+        }
+        catch (error) {
+            throw await throwProviderWriteOrReservedRowRollbackError({
+                error,
+                rollbackReservedRow: () => db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)),
+                companyId,
+                provider: provider.id,
+                providerConfigId,
+                providerConfig,
+                operation: "secret.create",
+            });
+        }
+        try {
+            return await db.transaction(async (tx) => {
+                await tx.insert(companySecretVersions).values({
+                    secretId: reservedSecret.id,
+                    version: 1,
+                    material: prepared.material,
+                    valueSha256: prepared.valueSha256,
+                    fingerprintSha256: prepared.fingerprintSha256 ?? prepared.valueSha256,
+                    providerVersionRef: prepared.providerVersionRef ?? null,
+                    status: "current",
+                    createdByAgentId: actor?.agentId ?? null,
+                    createdByUserId: actor?.userId ?? null,
+                });
+                const secret = await tx
+                    .update(companySecrets)
+                    .set({
+                    status: "active",
+                    externalRef: prepared.externalRef,
+                    latestVersion: 1,
+                    lastRotatedAt: new Date(),
+                    updatedAt: new Date(),
+                })
+                    .where(eq(companySecrets.id, reservedSecret.id))
+                    .returning()
+                    .then((rows) => rows[0]);
+                if (!secret)
+                    throw notFound("User secret value not found");
+                return secret;
+            });
+        }
+        catch (error) {
+            if (managedMode === "paperclip_managed") {
+                const cleaned = await cleanupPreparedProviderWrite({
+                    provider,
+                    prepared,
+                    providerConfig,
+                    context: providerWriteContext,
+                    mode: "delete",
+                    operation: "user_secret_value.create_rollback",
+                });
+                if (!cleaned) {
+                    throwProviderCleanupFailedAfterCreateRollback({
+                        companyId,
+                        provider: provider.id,
+                        providerConfigId,
+                        providerConfig,
+                        operation: "user_secret_value.create_rollback",
+                    });
+                }
+            }
+            await deleteLocalSecretCreateReservationOrThrow({
+                db,
+                secretId: reservedSecret.id,
+                companyId,
+                provider: provider.id,
+                providerConfigId,
+                providerConfig,
+                operation: "user_secret_value.create_rollback",
+            });
+            throw error;
+        }
+    }
+    async function removeSecretInternal(secretId) {
+        const secret = await getById(secretId);
+        if (!secret)
+            return null;
+        const versionRow = await getSecretVersion(secret.id, secret.latestVersion);
+        const providerId = secret.provider;
+        const provider = getSecretProvider(providerId);
+        if (secret.status !== "deleted") {
+            await db
+                .update(companySecrets)
+                .set({
+                key: `${secret.key}__deleted__${secret.id}`,
+                name: `${secret.name}__deleted__${secret.id}`,
+                status: "deleted",
+                deletedAt: secret.deletedAt ?? new Date(),
+                updatedAt: new Date(),
+            })
+                .where(eq(companySecrets.id, secretId));
+        }
+        const providerConfig = secret.providerConfigId
+            ? await getProviderConfigById(secret.providerConfigId)
+            : null;
+        const providerRuntimeConfig = providerConfig && providerConfig.status !== "disabled" && providerConfig.status !== "coming_soon"
+            ? toProviderVaultRuntimeConfig(providerConfig)
+            : null;
+        if (!secret.providerConfigId || providerRuntimeConfig) {
+            try {
+                await provider.deleteOrArchive({
+                    material: versionRow?.material,
+                    externalRef: secret.externalRef,
+                    providerConfig: providerRuntimeConfig,
+                    context: {
+                        companyId: secret.companyId,
+                        secretKey: secret.key,
+                        secretName: secret.name,
+                        version: secret.latestVersion,
+                    },
+                    mode: "delete",
+                });
+            }
+            catch (error) {
+                if (!isSecretProviderClientError(error) || error.code !== "not_found") {
+                    throw error;
+                }
+            }
+        }
+        await db.delete(companySecrets).where(eq(companySecrets.id, secretId));
+        return secret;
+    }
+    async function removeUserSecretDefinitionInternal(companyId, definitionId, actor) {
+        const existing = await resolveUserSecretDefinition(companyId, { definitionId });
+        const values = await db
+            .select({ id: companySecrets.id })
+            .from(companySecrets)
+            .where(and(eq(companySecrets.companyId, companyId), eq(companySecrets.scope, "user"), eq(companySecrets.userSecretDefinitionId, definitionId)));
+        for (const value of values) {
+            await removeSecretInternal(value.id);
+        }
+        return db
+            .update(userSecretDefinitions)
+            .set({
+            key: `${existing.key}__deleted__${existing.id}`,
+            status: "deleted",
+            deletedAt: existing.deletedAt ?? new Date(),
+            updatedByAgentId: actor?.agentId ?? null,
+            updatedByUserId: actor?.userId ?? null,
+            updatedAt: new Date(),
+        })
+            .where(and(eq(userSecretDefinitions.companyId, companyId), eq(userSecretDefinitions.id, definitionId)))
+            .returning()
+            .then((rows) => rows[0] ?? null);
+    }
     return {
         listProviders: () => listSecretProviders(),
         checkProviders: () => checkSecretProviders(),
@@ -1159,7 +1618,7 @@ export function secretService(db) {
                 db
                     .select()
                     .from(companySecrets)
-                    .where(and(eq(companySecrets.companyId, companyId), ne(companySecrets.status, "deleted")))
+                    .where(and(eq(companySecrets.companyId, companyId), eq(companySecrets.scope, "company"), ne(companySecrets.status, "deleted")))
                     .orderBy(desc(companySecrets.createdAt)),
                 db
                     .select({
@@ -1201,6 +1660,270 @@ export function secretService(db) {
             .from(secretAccessEvents)
             .where(and(eq(secretAccessEvents.companyId, companyId), eq(secretAccessEvents.secretId, secretId)))
             .orderBy(desc(secretAccessEvents.createdAt)),
+        listUserSecretDefinitions: (companyId) => db
+            .select()
+            .from(userSecretDefinitions)
+            .where(and(eq(userSecretDefinitions.companyId, companyId), ne(userSecretDefinitions.status, "deleted")))
+            .orderBy(desc(userSecretDefinitions.createdAt)),
+        getUserSecretDefinitionById: (companyId, definitionId) => getUserSecretDefinitionById(companyId, definitionId),
+        createUserSecretDefinition: async (companyId, input, actor) => {
+            const key = input.key.trim();
+            const duplicate = await getUserSecretDefinitionByKey(companyId, key);
+            if (duplicate)
+                throw conflict(`User secret definition already exists: ${key}`);
+            await assertProviderConfigForSecret(companyId, input.provider, input.providerConfigId);
+            try {
+                return await db
+                    .insert(userSecretDefinitions)
+                    .values({
+                    companyId,
+                    key,
+                    name: input.name.trim(),
+                    description: input.description ?? null,
+                    status: input.status ?? "active",
+                    provider: input.provider,
+                    providerConfigId: input.providerConfigId ?? null,
+                    managedMode: input.managedMode ?? "paperclip_managed",
+                    providerMetadata: input.providerMetadata ?? null,
+                    usageGuidance: input.usageGuidance ?? null,
+                    createdByAgentId: actor?.agentId ?? null,
+                    createdByUserId: actor?.userId ?? null,
+                    updatedByAgentId: actor?.agentId ?? null,
+                    updatedByUserId: actor?.userId ?? null,
+                })
+                    .returning()
+                    .then((rows) => rows[0]);
+            }
+            catch (error) {
+                if (isUniqueConstraintViolation(error, USER_SECRET_DEFINITION_KEY_UNIQUE_CONSTRAINT)) {
+                    throw conflict(`User secret definition already exists: ${key}`);
+                }
+                throw error;
+            }
+        },
+        updateUserSecretDefinition: async (companyId, definitionId, patch, actor) => {
+            const existing = await resolveUserSecretDefinition(companyId, { definitionId });
+            if (patch.status === "deleted") {
+                return removeUserSecretDefinitionInternal(companyId, existing.id, actor);
+            }
+            const nextKey = patch.key?.trim() ?? existing.key;
+            if (nextKey !== existing.key) {
+                const duplicate = await getUserSecretDefinitionByKey(companyId, nextKey);
+                if (duplicate && duplicate.id !== existing.id) {
+                    throw conflict(`User secret definition already exists: ${nextKey}`);
+                }
+            }
+            if (patch.providerConfigId !== undefined) {
+                await assertProviderConfigForSecret(companyId, existing.provider, patch.providerConfigId);
+            }
+            return db
+                .update(userSecretDefinitions)
+                .set({
+                key: nextKey,
+                name: patch.name?.trim() ?? existing.name,
+                description: patch.description === undefined ? existing.description : patch.description,
+                status: patch.status ?? existing.status,
+                providerConfigId: patch.providerConfigId === undefined ? existing.providerConfigId : patch.providerConfigId,
+                providerMetadata: patch.providerMetadata === undefined ? existing.providerMetadata : patch.providerMetadata,
+                usageGuidance: patch.usageGuidance === undefined ? existing.usageGuidance : patch.usageGuidance,
+                updatedByAgentId: actor?.agentId ?? null,
+                updatedByUserId: actor?.userId ?? null,
+                deletedAt: existing.deletedAt,
+                updatedAt: new Date(),
+            })
+                .where(and(eq(userSecretDefinitions.companyId, companyId), eq(userSecretDefinitions.id, definitionId)))
+                .returning()
+                .then((rows) => rows[0] ?? null);
+        },
+        removeUserSecretDefinition: async (companyId, definitionId, actor) => removeUserSecretDefinitionInternal(companyId, definitionId, actor),
+        getUserSecretDefinitionCoverage: async (companyId, definitionId) => {
+            await resolveUserSecretDefinition(companyId, { definitionId });
+            const [members, values] = await Promise.all([
+                db
+                    .select({ principalId: companyMemberships.principalId })
+                    .from(companyMemberships)
+                    .where(and(eq(companyMemberships.companyId, companyId), eq(companyMemberships.principalType, "user"), eq(companyMemberships.status, "active"))),
+                db
+                    .select({ status: companySecrets.status, ownerUserId: companySecrets.ownerUserId })
+                    .from(companySecrets)
+                    .where(and(eq(companySecrets.companyId, companyId), eq(companySecrets.scope, "user"), eq(companySecrets.userSecretDefinitionId, definitionId), ne(companySecrets.status, "deleted"))),
+            ]);
+            const memberIds = new Set(members.map((member) => member.principalId));
+            const configuredCount = values.filter((value) => value.status === "active" && value.ownerUserId && memberIds.has(value.ownerUserId)).length;
+            const inactiveCount = values.filter((value) => value.status !== "active" && value.ownerUserId && memberIds.has(value.ownerUserId)).length;
+            return {
+                definitionId,
+                configuredCount,
+                inactiveCount,
+                missingCount: Math.max(0, memberIds.size - configuredCount - inactiveCount),
+            };
+        },
+        listCurrentUserSecretValues: async (companyId, ownerUserId) => {
+            const definitions = await db
+                .select()
+                .from(userSecretDefinitions)
+                .where(and(eq(userSecretDefinitions.companyId, companyId), ne(userSecretDefinitions.status, "deleted")))
+                .orderBy(desc(userSecretDefinitions.createdAt));
+            const values = await db
+                .select()
+                .from(companySecrets)
+                .where(and(eq(companySecrets.companyId, companyId), eq(companySecrets.scope, "user"), eq(companySecrets.ownerUserId, ownerUserId), ne(companySecrets.status, "deleted")));
+            const valuesByDefinitionId = new Map(values.map((value) => [value.userSecretDefinitionId, value]));
+            return definitions.map((definition) => ({
+                definition,
+                secret: valuesByDefinitionId.get(definition.id) ?? null,
+            }));
+        },
+        createCurrentUserSecretValue: createUserSecretValueInternal,
+        rotateCurrentUserSecretValue: async (companyId, ownerUserId, secretId, input, actor) => {
+            const secret = await getUserSecretValueById(companyId, ownerUserId, secretId);
+            return await (async () => {
+                await resolveUserSecretDefinition(companyId, { definitionId: secret.userSecretDefinitionId });
+                return (await secretService(db).rotate(secret.id, input, actor));
+            })();
+        },
+        updateCurrentUserSecretValue: async (companyId, ownerUserId, secretId, patch, actor) => {
+            const secret = await getUserSecretValueById(companyId, ownerUserId, secretId);
+            if (patch.value != null ||
+                patch.externalRef != null ||
+                patch.providerVersionRef != null ||
+                patch.providerConfigId != null) {
+                return await secretService(db).rotateCurrentUserSecretValue(companyId, ownerUserId, secret.id, patch, actor);
+            }
+            if (patch.status === "deleted") {
+                return await secretService(db).removeCurrentUserSecretValue(companyId, ownerUserId, secret.id);
+            }
+            return db
+                .update(companySecrets)
+                .set({
+                status: patch.status ?? secret.status,
+                updatedAt: new Date(),
+            })
+                .where(eq(companySecrets.id, secret.id))
+                .returning()
+                .then((rows) => rows[0] ?? null);
+        },
+        removeCurrentUserSecretValue: async (companyId, ownerUserId, secretId) => {
+            const secret = await getUserSecretValueById(companyId, ownerUserId, secretId);
+            return await secretService(db).remove(secret.id);
+        },
+        syncUserSecretDeclarationsForTarget: async (companyId, target, refs, options) => {
+            const targetDb = options?.db ?? db;
+            const normalizedRefs = [];
+            for (const ref of refs) {
+                const definition = await resolveUserSecretDefinition(companyId, { definitionKey: ref.definitionKey }, targetDb);
+                normalizedRefs.push({
+                    definitionId: definition.id,
+                    configPath: ref.configPath,
+                    envKey: ref.envKey,
+                    versionSelector: ref.versionSelector ?? "latest",
+                    required: ref.required ?? true,
+                    allowMissingOverride: ref.allowMissingOverride ?? false,
+                    label: ref.label ?? null,
+                });
+            }
+            const pathPrefix = target.pathPrefix ?? "env";
+            const writeDeclarations = async (executor) => {
+                if (options?.replaceAll) {
+                    await executor
+                        .delete(userSecretDeclarations)
+                        .where(and(eq(userSecretDeclarations.companyId, companyId), eq(userSecretDeclarations.targetType, target.targetType), eq(userSecretDeclarations.targetId, target.targetId)));
+                }
+                else {
+                    await executor
+                        .delete(userSecretDeclarations)
+                        .where(and(eq(userSecretDeclarations.companyId, companyId), eq(userSecretDeclarations.targetType, target.targetType), eq(userSecretDeclarations.targetId, target.targetId), like(userSecretDeclarations.configPath, `${pathPrefix}.%`)));
+                }
+                if (normalizedRefs.length === 0)
+                    return;
+                await executor.insert(userSecretDeclarations).values(normalizedRefs.map((ref) => ({
+                    companyId,
+                    userSecretDefinitionId: ref.definitionId,
+                    targetType: target.targetType,
+                    targetId: target.targetId,
+                    configPath: ref.configPath,
+                    envKey: ref.envKey,
+                    versionSelector: String(ref.versionSelector),
+                    required: ref.required,
+                    allowMissingOverride: ref.allowMissingOverride,
+                    label: ref.label,
+                })));
+            };
+            if (options?.db) {
+                await writeDeclarations(targetDb);
+            }
+            else {
+                await db.transaction(async (tx) => writeDeclarations(tx));
+            }
+            return normalizedRefs;
+        },
+        resolveUserSecretValue: async (companyId, input, context) => {
+            const responsibleUserId = input.responsibleUserId ?? context?.responsibleUserId ?? null;
+            const optionalBinding = input.allowMissingOverride || input.required === false;
+            let definition;
+            try {
+                definition = await resolveUserSecretDefinition(companyId, input);
+            }
+            catch (error) {
+                if (optionalBinding && error instanceof HttpError && error.status === 404)
+                    return null;
+                throw error;
+            }
+            if (definition.status !== "active") {
+                if (optionalBinding)
+                    return null;
+                throw unprocessable("User secret definition is not active");
+            }
+            if (!responsibleUserId?.trim()) {
+                if (optionalBinding)
+                    return null;
+                throw unprocessable("Responsible user is required for user secret resolution", {
+                    code: "responsible_user_missing",
+                });
+            }
+            let declaration = null;
+            if (context?.configPath) {
+                declaration = await db
+                    .select()
+                    .from(userSecretDeclarations)
+                    .where(and(eq(userSecretDeclarations.companyId, companyId), eq(userSecretDeclarations.userSecretDefinitionId, definition.id), eq(userSecretDeclarations.targetType, context.consumerType), eq(userSecretDeclarations.targetId, context.consumerId), eq(userSecretDeclarations.configPath, context.configPath)))
+                    .then((rows) => rows[0] ?? null);
+                if (!declaration) {
+                    if (optionalBinding)
+                        return null;
+                    throw unprocessable(`User secret is not declared for ${context.consumerType}:${context.consumerId} at ${context.configPath}`, { code: "binding_missing" });
+                }
+            }
+            if (Array.isArray(context?.allowedBindingIds) &&
+                (!declaration || !context.allowedBindingIds.includes(declaration.id))) {
+                throw unprocessable("User secret declaration is outside the active low-trust boundary", { code: "binding_not_allowed" });
+            }
+            const secret = await getUserSecretValue({
+                companyId,
+                ownerUserId: responsibleUserId,
+                definitionId: definition.id,
+            });
+            if (!secret) {
+                if (optionalBinding)
+                    return null;
+                throw unprocessable("User secret value is not configured", {
+                    code: "user_secret_missing",
+                    definitionId: definition.id,
+                    responsibleUserId,
+                });
+            }
+            const resolution = await resolveSecretValueInternal(companyId, secret.id, input.version ?? "latest", {
+                accessContext: context ? { ...context, responsibleUserId } : undefined,
+                allowUserSecretScope: true,
+            });
+            return {
+                ...resolution,
+                manifestEntry: {
+                    ...resolution.manifestEntry,
+                    bindingId: declaration?.id ?? resolution.manifestEntry.bindingId ?? null,
+                },
+            };
+        },
         previewRemoteImport: async (companyId, input) => {
             const { providerConfig, provider: providerId, runtimeConfig } = await getRemoteImportProviderConfig(companyId, input.providerConfigId);
             const provider = getSecretProvider(providerId);
@@ -1478,7 +2201,7 @@ export function secretService(db) {
             const duplicateKey = await db
                 .select()
                 .from(companySecrets)
-                .where(and(eq(companySecrets.companyId, companyId), eq(companySecrets.key, key), ne(companySecrets.status, "deleted")))
+                .where(and(eq(companySecrets.companyId, companyId), eq(companySecrets.scope, "company"), eq(companySecrets.key, key), ne(companySecrets.status, "deleted")))
                 .then((rows) => rows[0] ?? null);
             if (duplicateKey)
                 throw conflict(`Secret key already exists: ${key}`);
@@ -1541,8 +2264,15 @@ export function secretService(db) {
                         });
             }
             catch (error) {
-                await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);
-                throw error;
+                throw await throwProviderWriteOrReservedRowRollbackError({
+                    error,
+                    rollbackReservedRow: () => db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)),
+                    companyId,
+                    provider: provider.id,
+                    providerConfigId: input.providerConfigId ?? null,
+                    providerConfig,
+                    operation: "secret.create",
+                });
             }
             try {
                 await db
@@ -1575,15 +2305,25 @@ export function secretService(db) {
                         mode: "delete",
                         operation: "create.prepare_rollback",
                     });
-                    if (cleaned) {
-                        await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);
-                        await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);
+                    if (!cleaned) {
+                        throwProviderCleanupFailedAfterCreateRollback({
+                            companyId,
+                            provider: provider.id,
+                            providerConfigId: input.providerConfigId ?? null,
+                            providerConfig,
+                            operation: "create.prepare_rollback",
+                        });
                     }
                 }
-                else {
-                    await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);
-                    await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);
-                }
+                await deleteLocalSecretCreateReservationOrThrow({
+                    db,
+                    secretId: reservedSecret.id,
+                    companyId,
+                    provider: provider.id,
+                    providerConfigId: input.providerConfigId ?? null,
+                    providerConfig,
+                    operation: "create.prepare_rollback",
+                });
                 throw error;
             }
             try {
@@ -1619,15 +2359,25 @@ export function secretService(db) {
                         mode: "delete",
                         operation: "create.rollback",
                     });
-                    if (cleaned) {
-                        await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);
-                        await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);
+                    if (!cleaned) {
+                        throwProviderCleanupFailedAfterCreateRollback({
+                            companyId,
+                            provider: provider.id,
+                            providerConfigId: input.providerConfigId ?? null,
+                            providerConfig,
+                            operation: "create.rollback",
+                        });
                     }
                 }
-                else {
-                    await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);
-                    await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);
-                }
+                await deleteLocalSecretCreateReservationOrThrow({
+                    db,
+                    secretId: reservedSecret.id,
+                    companyId,
+                    provider: provider.id,
+                    providerConfigId: input.providerConfigId ?? null,
+                    providerConfig,
+                    operation: "create.rollback",
+                });
                 throw error;
             }
         },
@@ -1661,19 +2411,32 @@ export function secretService(db) {
                 secretName: secret.name,
                 version: nextVersion,
             };
-            const prepared = secret.managedMode === "external_reference"
-                ? await provider.linkExternalSecret({
-                    externalRef: input.externalRef ?? secret.externalRef ?? "",
-                    providerVersionRef: input.providerVersionRef ?? null,
-                    providerConfig,
-                    context: providerWriteContext,
-                })
-                : await provider.createVersion({
-                    value: input.value ?? "",
-                    externalRef: secret.externalRef ?? null,
+            let prepared;
+            try {
+                prepared =
+                    secret.managedMode === "external_reference"
+                        ? await provider.linkExternalSecret({
+                            externalRef: input.externalRef ?? secret.externalRef ?? "",
+                            providerVersionRef: input.providerVersionRef ?? null,
+                            providerConfig,
+                            context: providerWriteContext,
+                        })
+                        : await provider.createVersion({
+                            value: input.value ?? "",
+                            externalRef: secret.externalRef ?? null,
+                            providerConfig,
+                            context: providerWriteContext,
+                        });
+            }
+            catch (error) {
+                throw remoteProviderWriteHttpError(error, {
+                    companyId: secret.companyId,
+                    provider: provider.id,
+                    providerConfigId,
                     providerConfig,
-                    context: providerWriteContext,
+                    operation: "secret.rotate",
                 });
+            }
             try {
                 await db.insert(companySecretVersions).values({
                     secretId: secret.id,
@@ -1766,7 +2529,7 @@ export function secretService(db) {
                 const duplicateKey = await db
                     .select()
                     .from(companySecrets)
-                    .where(and(eq(companySecrets.companyId, secret.companyId), eq(companySecrets.key, nextKey), ne(companySecrets.status, "deleted")))
+                    .where(and(eq(companySecrets.companyId, secret.companyId), eq(companySecrets.scope, "company"), eq(companySecrets.key, nextKey), ne(companySecrets.status, "deleted")))
                     .then((rows) => rows[0] ?? null);
                 if (duplicateKey && duplicateKey.id !== secret.id) {
                     throw conflict(`Secret key already exists: ${nextKey}`);
@@ -1892,6 +2655,7 @@ export function secretService(db) {
         syncEnvBindingsForTarget: async (companyId, target, envValue, options) => {
             const record = asRecord(envValue) ?? {};
             const refs = [];
+            const userRefs = [];
             const pathPrefix = target.pathPrefix ?? "env";
             const bindingDb = options?.db ?? db;
             for (const [key, rawBinding] of Object.entries(record)) {
@@ -1899,6 +2663,18 @@ export function secretService(db) {
                 if (!parsed.success)
                     continue;
                 const binding = canonicalizeBinding(parsed.data);
+                if (binding.type === "user_secret_ref") {
+                    await resolveUserSecretDefinition(companyId, { definitionKey: binding.key }, bindingDb);
+                    userRefs.push({
+                        definitionKey: binding.key,
+                        configPath: `${pathPrefix}.${key}`,
+                        envKey: key,
+                        versionSelector: binding.version,
+                        required: binding.required,
+                        allowMissingOverride: binding.allowMissingOverride,
+                    });
+                    continue;
+                }
                 if (binding.type !== "secret_ref")
                     continue;
                 await assertSecretInCompany(companyId, binding.secretId, bindingDb);
@@ -1924,63 +2700,42 @@ export function secretService(db) {
                     required: true,
                 })));
             };
+            const writeUserDeclarations = async (targetDb) => {
+                await targetDb
+                    .delete(userSecretDeclarations)
+                    .where(and(eq(userSecretDeclarations.companyId, companyId), eq(userSecretDeclarations.targetType, target.targetType), eq(userSecretDeclarations.targetId, target.targetId), like(userSecretDeclarations.configPath, `${pathPrefix}.%`)));
+                if (userRefs.length === 0)
+                    return;
+                const definitions = new Map();
+                for (const ref of userRefs) {
+                    const definition = await resolveUserSecretDefinition(companyId, { definitionKey: ref.definitionKey }, targetDb);
+                    definitions.set(ref.definitionKey, definition.id);
+                }
+                await targetDb.insert(userSecretDeclarations).values(userRefs.map((ref) => ({
+                    companyId,
+                    userSecretDefinitionId: definitions.get(ref.definitionKey),
+                    targetType: target.targetType,
+                    targetId: target.targetId,
+                    configPath: ref.configPath,
+                    envKey: ref.envKey,
+                    versionSelector: String(ref.versionSelector),
+                    required: ref.required,
+                    allowMissingOverride: ref.allowMissingOverride,
+                })));
+            };
             if (options?.db) {
                 await writeBindings(options.db);
+                await writeUserDeclarations(options.db);
             }
             else {
-                await db.transaction(async (tx) => writeBindings(tx));
+                await db.transaction(async (tx) => {
+                    await writeBindings(tx);
+                    await writeUserDeclarations(tx);
+                });
             }
             return refs;
         },
-        remove: async (secretId) => {
-            const secret = await getById(secretId);
-            if (!secret)
-                return null;
-            const versionRow = await getSecretVersion(secret.id, secret.latestVersion);
-            const providerId = secret.provider;
-            const provider = getSecretProvider(providerId);
-            if (secret.status !== "deleted") {
-                await db
-                    .update(companySecrets)
-                    .set({
-                    key: `${secret.key}__deleted__${secret.id}`,
-                    name: `${secret.name}__deleted__${secret.id}`,
-                    status: "deleted",
-                    deletedAt: secret.deletedAt ?? new Date(),
-                    updatedAt: new Date(),
-                })
-                    .where(eq(companySecrets.id, secretId));
-            }
-            const providerConfig = secret.providerConfigId
-                ? await getProviderConfigById(secret.providerConfigId)
-                : null;
-            const providerRuntimeConfig = providerConfig && providerConfig.status !== "disabled" && providerConfig.status !== "coming_soon"
-                ? toProviderVaultRuntimeConfig(providerConfig)
-                : null;
-            if (!secret.providerConfigId || providerRuntimeConfig) {
-                try {
-                    await provider.deleteOrArchive({
-                        material: versionRow?.material,
-                        externalRef: secret.externalRef,
-                        providerConfig: providerRuntimeConfig,
-                        context: {
-                            companyId: secret.companyId,
-                            secretKey: secret.key,
-                            secretName: secret.name,
-                            version: secret.latestVersion,
-                        },
-                        mode: "delete",
-                    });
-                }
-                catch (error) {
-                    if (!isSecretProviderClientError(error) || error.code !== "not_found") {
-                        throw error;
-                    }
-                }
-            }
-            await db.delete(companySecrets).where(eq(companySecrets.id, secretId));
-            return secret;
-        },
+        remove: removeSecretInternal,
         normalizeAdapterConfigForPersistence: async (companyId, adapterConfig, opts) => normalizeAdapterConfigForPersistenceInternal(companyId, adapterConfig, opts),
         normalizeEnvBindingsForPersistence: async (companyId, envValue, opts) => normalizeEnvConfig(companyId, envValue, opts),
         normalizeHireApprovalPayloadForPersistence: async (companyId, payload, opts) => {
@@ -2010,7 +2765,7 @@ export function secretService(db) {
                 if (binding.type === "plain") {
                     resolved[key] = binding.value;
                 }
-                else {
+                else if (binding.type === "secret_ref") {
                     const secretResolution = await resolveSecretValueInternal(companyId, binding.secretId, binding.version, context
                         ? {
                             bindingContext: { ...context, configPath: `env.${key}` },
@@ -2021,6 +2776,25 @@ export function secretService(db) {
                     manifest.push(secretResolution.manifestEntry);
                     secretKeys.add(key);
                 }
+                else {
+                    const secretResolution = await secretService(db).resolveUserSecretValue(companyId, {
+                        definitionKey: binding.key,
+                        version: binding.version,
+                        required: binding.required,
+                        allowMissingOverride: binding.allowMissingOverride,
+                    }, context
+                        ? {
+                            ...context,
+                            configPath: `env.${key}`,
+                            responsibleUserId: context.responsibleUserId ?? null,
+                        }
+                        : undefined);
+                    if (secretResolution) {
+                        resolved[key] = secretResolution.value;
+                        manifest.push(secretResolution.manifestEntry);
+                        secretKeys.add(key);
+                    }
+                }
             }
             return { env: resolved, secretKeys, manifest };
         },
@@ -2043,7 +2817,20 @@ export function secretService(db) {
                     return [];
                 return [{ key, configPath: `env.${key}`, secretId: binding.secretId }];
             });
-            if (secretRefs.length === 0)
+            const userSecretRefs = Object.entries(record).flatMap(([key, rawBinding]) => {
+                if (!ENV_KEY_RE.test(key))
+                    return [];
+                const parsed = envBindingSchema.safeParse(rawBinding);
+                if (!parsed.success)
+                    return [];
+                const binding = canonicalizeBinding(parsed.data);
+                if (binding.type !== "user_secret_ref")
+                    return [];
+                if (!binding.required || binding.allowMissingOverride)
+                    return [];
+                return [{ key, configPath: `env.${key}`, binding }];
+            });
+            if (secretRefs.length === 0 && userSecretRefs.length === 0)
                 return [];
             const bindingChecks = await Promise.all(secretRefs.map(async (entry) => ({
                 entry,
@@ -2058,21 +2845,96 @@ export function secretService(db) {
             const missingEntries = bindingChecks
                 .filter((check) => !check.found)
                 .map((check) => check.entry);
-            if (missingEntries.length === 0)
-                return [];
             const secretRows = await Promise.all([...new Set(missingEntries.map((entry) => entry.secretId))].map(async (secretId) => [
                 secretId,
                 await getById(secretId).catch(() => null),
             ]));
             const secretsById = new Map(secretRows);
-            return missingEntries.map((entry) => ({
+            const missingSecretBindings = missingEntries.map((entry) => ({
                 consumerType: context.consumerType,
                 consumerId: context.consumerId,
                 configPath: entry.configPath,
                 envKey: entry.key,
+                bindingType: "secret_ref",
                 secretId: entry.secretId,
                 secretName: secretsById.get(entry.secretId)?.name ?? null,
             }));
+            const missingUserSecretBindings = [];
+            for (const entry of userSecretRefs) {
+                let definition = null;
+                try {
+                    definition = await resolveUserSecretDefinition(companyId, { definitionKey: entry.binding.key });
+                }
+                catch {
+                    missingUserSecretBindings.push(missingUserSecretDefinitionRuntimeBinding(entry, context, null, "user_secret_definition_missing"));
+                    continue;
+                }
+                if (definition.status !== "active") {
+                    missingUserSecretBindings.push(missingUserSecretDefinitionRuntimeBinding(entry, context, definition, "user_secret_definition_inactive"));
+                    continue;
+                }
+                const declaration = await db
+                    .select()
+                    .from(userSecretDeclarations)
+                    .where(and(eq(userSecretDeclarations.companyId, companyId), eq(userSecretDeclarations.userSecretDefinitionId, definition.id), eq(userSecretDeclarations.targetType, context.consumerType), eq(userSecretDeclarations.targetId, context.consumerId), eq(userSecretDeclarations.configPath, entry.configPath)))
+                    .then((rows) => rows[0] ?? null);
+                if (!declaration) {
+                    missingUserSecretBindings.push({
+                        consumerType: context.consumerType,
+                        consumerId: context.consumerId,
+                        configPath: entry.configPath,
+                        envKey: entry.key,
+                        bindingType: "user_secret_ref",
+                        secretId: null,
+                        secretName: null,
+                        userSecretDefinitionId: definition.id,
+                        userSecretDefinitionKey: definition.key,
+                        userSecretDefinitionName: definition.name,
+                        responsibleUserId: context.responsibleUserId ?? null,
+                        errorCode: "binding_missing",
+                    });
+                    continue;
+                }
+                if (!context.responsibleUserId?.trim()) {
+                    missingUserSecretBindings.push({
+                        consumerType: context.consumerType,
+                        consumerId: context.consumerId,
+                        configPath: entry.configPath,
+                        envKey: entry.key,
+                        bindingType: "user_secret_ref",
+                        secretId: null,
+                        secretName: null,
+                        userSecretDefinitionId: definition.id,
+                        userSecretDefinitionKey: definition.key,
+                        userSecretDefinitionName: definition.name,
+                        responsibleUserId: null,
+                        errorCode: "responsible_user_missing",
+                    });
+                    continue;
+                }
+                const secret = await getUserSecretValue({
+                    companyId,
+                    ownerUserId: context.responsibleUserId,
+                    definitionId: definition.id,
+                });
+                if (!secret || secret.status !== "active") {
+                    missingUserSecretBindings.push({
+                        consumerType: context.consumerType,
+                        consumerId: context.consumerId,
+                        configPath: entry.configPath,
+                        envKey: entry.key,
+                        bindingType: "user_secret_ref",
+                        secretId: secret?.id ?? null,
+                        secretName: null,
+                        userSecretDefinitionId: definition.id,
+                        userSecretDefinitionKey: definition.key,
+                        userSecretDefinitionName: definition.name,
+                        responsibleUserId: context.responsibleUserId,
+                        errorCode: secret ? "secret_inactive" : "user_secret_missing",
+                    });
+                }
+            }
+            return [...missingSecretBindings, ...missingUserSecretBindings];
         },
         collectMissingAdapterConfigRuntimeBindings: async (companyId, adapterConfig, adapterType, context) => {
             const secretFieldKeys = await listAdapterSchemaSecretFieldKeys(adapterType);
@@ -2085,7 +2947,18 @@ export function secretService(db) {
                     return [];
                 return [{ key, configPath: key, secretId: binding.secretId }];
             });
-            if (secretRefs.length === 0)
+            const userSecretRefs = secretFieldKeys.flatMap((key) => {
+                const parsed = envBindingSchema.safeParse(adapterConfig[key]);
+                if (!parsed.success)
+                    return [];
+                const binding = canonicalizeBinding(parsed.data);
+                if (binding.type !== "user_secret_ref")
+                    return [];
+                if (!binding.required || binding.allowMissingOverride)
+                    return [];
+                return [{ key, configPath: key, binding }];
+            });
+            if (secretRefs.length === 0 && userSecretRefs.length === 0)
                 return [];
             const bindingChecks = await Promise.all(secretRefs.map(async (entry) => ({
                 entry,
@@ -2100,21 +2973,96 @@ export function secretService(db) {
             const missingEntries = bindingChecks
                 .filter((check) => !check.found)
                 .map((check) => check.entry);
-            if (missingEntries.length === 0)
-                return [];
             const secretRows = await Promise.all([...new Set(missingEntries.map((entry) => entry.secretId))].map(async (secretId) => [
                 secretId,
                 await getById(secretId).catch(() => null),
             ]));
             const secretsById = new Map(secretRows);
-            return missingEntries.map((entry) => ({
+            const missingSecretBindings = missingEntries.map((entry) => ({
                 consumerType: context.consumerType,
                 consumerId: context.consumerId,
                 configPath: entry.configPath,
                 envKey: entry.key,
+                bindingType: "secret_ref",
                 secretId: entry.secretId,
                 secretName: secretsById.get(entry.secretId)?.name ?? null,
             }));
+            const missingUserSecretBindings = [];
+            for (const entry of userSecretRefs) {
+                let definition = null;
+                try {
+                    definition = await resolveUserSecretDefinition(companyId, { definitionKey: entry.binding.key });
+                }
+                catch {
+                    missingUserSecretBindings.push(missingUserSecretDefinitionRuntimeBinding(entry, context, null, "user_secret_definition_missing"));
+                    continue;
+                }
+                if (definition.status !== "active") {
+                    missingUserSecretBindings.push(missingUserSecretDefinitionRuntimeBinding(entry, context, definition, "user_secret_definition_inactive"));
+                    continue;
+                }
+                const declaration = await db
+                    .select()
+                    .from(userSecretDeclarations)
+                    .where(and(eq(userSecretDeclarations.companyId, companyId), eq(userSecretDeclarations.userSecretDefinitionId, definition.id), eq(userSecretDeclarations.targetType, context.consumerType), eq(userSecretDeclarations.targetId, context.consumerId), eq(userSecretDeclarations.configPath, entry.configPath)))
+                    .then((rows) => rows[0] ?? null);
+                if (!declaration) {
+                    missingUserSecretBindings.push({
+                        consumerType: context.consumerType,
+                        consumerId: context.consumerId,
+                        configPath: entry.configPath,
+                        envKey: entry.key,
+                        bindingType: "user_secret_ref",
+                        secretId: null,
+                        secretName: null,
+                        userSecretDefinitionId: definition.id,
+                        userSecretDefinitionKey: definition.key,
+                        userSecretDefinitionName: definition.name,
+                        responsibleUserId: context.responsibleUserId ?? null,
+                        errorCode: "binding_missing",
+                    });
+                    continue;
+                }
+                if (!context.responsibleUserId?.trim()) {
+                    missingUserSecretBindings.push({
+                        consumerType: context.consumerType,
+                        consumerId: context.consumerId,
+                        configPath: entry.configPath,
+                        envKey: entry.key,
+                        bindingType: "user_secret_ref",
+                        secretId: null,
+                        secretName: null,
+                        userSecretDefinitionId: definition.id,
+                        userSecretDefinitionKey: definition.key,
+                        userSecretDefinitionName: definition.name,
+                        responsibleUserId: null,
+                        errorCode: "responsible_user_missing",
+                    });
+                    continue;
+                }
+                const secret = await getUserSecretValue({
+                    companyId,
+                    ownerUserId: context.responsibleUserId,
+                    definitionId: definition.id,
+                });
+                if (!secret || secret.status !== "active") {
+                    missingUserSecretBindings.push({
+                        consumerType: context.consumerType,
+                        consumerId: context.consumerId,
+                        configPath: entry.configPath,
+                        envKey: entry.key,
+                        bindingType: "user_secret_ref",
+                        secretId: secret?.id ?? null,
+                        secretName: null,
+                        userSecretDefinitionId: definition.id,
+                        userSecretDefinitionKey: definition.key,
+                        userSecretDefinitionName: definition.name,
+                        responsibleUserId: context.responsibleUserId,
+                        errorCode: secret ? "secret_inactive" : "user_secret_missing",
+                    });
+                }
+            }
+            return [...missingSecretBindings, ...missingUserSecretBindings];
         },
         resolveAdapterConfigForRuntime: async (companyId, adapterConfig, context, opts) => {
             const resolved = { ...adapterConfig };
@@ -2139,7 +3087,7 @@ export function secretService(db) {
                         if (binding.type === "plain") {
                             env[key] = binding.value;
                         }
-                        else {
+                        else if (binding.type === "secret_ref") {
                             const secretResolution = await resolveSecretValueInternal(companyId, binding.secretId, binding.version, context
                                 ? {
                                     bindingContext: { ...context, configPath: `env.${key}` },
@@ -2150,6 +3098,27 @@ export function secretService(db) {
                             manifest.push(secretResolution.manifestEntry);
                             secretKeys.add(key);
                         }
+                        else {
+                            if (opts?.skipUserSecrets)
+                                continue;
+                            const secretResolution = await secretService(db).resolveUserSecretValue(companyId, {
+                                definitionKey: binding.key,
+                                version: binding.version,
+                                required: binding.required,
+                                allowMissingOverride: binding.allowMissingOverride,
+                            }, context
+                                ? {
+                                    ...context,
+                                    configPath: `env.${key}`,
+                                    responsibleUserId: context.responsibleUserId ?? null,
+                                }
+                                : undefined);
+                            if (secretResolution) {
+                                env[key] = secretResolution.value;
+                                manifest.push(secretResolution.manifestEntry);
+                                secretKeys.add(key);
+                            }
+                        }
                     }
                     resolved.env = env;
                 }
@@ -2162,6 +3131,30 @@ export function secretService(db) {
                 const binding = canonicalizeBinding(parsed.data);
                 if (binding.type === "plain")
                     continue;
+                if (binding.type === "user_secret_ref") {
+                    if (opts?.skipUserSecrets) {
+                        delete resolved[key];
+                        continue;
+                    }
+                    const secretResolution = await secretService(db).resolveUserSecretValue(companyId, {
+                        definitionKey: binding.key,
+                        version: binding.version,
+                        required: binding.required,
+                        allowMissingOverride: binding.allowMissingOverride,
+                    }, context
+                        ? {
+                            ...context,
+                            configPath: key,
+                            responsibleUserId: context.responsibleUserId ?? null,
+                        }
+                        : undefined);
+                    if (secretResolution) {
+                        resolved[key] = secretResolution.value;
+                        manifest.push(secretResolution.manifestEntry);
+                        secretKeys.add(key);
+                    }
+                    continue;
+                }
                 const secretResolution = await resolveSecretValueInternal(companyId, binding.secretId, binding.version, context
                     ? {
                         bindingContext: { ...context, configPath: key },