Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

fix(docker): persist credential encryption secrets on the data volume

tianma-ifa853c92350ec
diff --git a/apps/api/src/ai-routes.ts b/apps/api/src/ai-routes.ts
index 564ae65e..f193baeb 100644
--- a/apps/api/src/ai-routes.ts
+++ b/apps/api/src/ai-routes.ts
@@ -85,6 +85,7 @@ const readSettings = (context: AppContext, dependencies: AiRouteDependencies) =>
encryptionConfigured(context),
dependencies.isDemoMode(context.env),
context.req.query("locale"),
+ context.env,
);
const denyMutation = (context: AppContext, dependencies: AiRouteDependencies) => {
diff --git a/apps/api/src/ai-service.test.mjs b/apps/api/src/ai-service.test.mjs
index 934249a5..9d1df877 100644
--- a/apps/api/src/ai-service.test.mjs
+++ b/apps/api/src/ai-service.test.mjs
@@ -322,6 +322,45 @@ describe("AI model service", () => {
})).toBeUndefined();
});
+ test("decrypts credentials with persisted fallback secrets after rotation", async () => {
+ const passwordEncrypted = await encryptSecret(
+ "provider-key",
+ resolvePrimaryAiCredentialEncryptionKey({ EDGE_EVER_AUTH_PASSWORD: "original-password" }),
+ );
+ await expect(decryptAiCredential(passwordEncrypted, {
+ EDGE_EVER_AUTH_PASSWORD: "rotated-password",
+ EDGE_EVER_AUTH_PASSWORD_FALLBACK: "original-password",
+ })).resolves.toBe("provider-key");
+
+ const credentialsEncrypted = await encryptSecret(
+ "provider-key",
+ resolvePrimaryAiCredentialEncryptionKey({
+ EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY: "original-credentials-key",
+ }),
+ );
+ await expect(decryptAiCredential(credentialsEncrypted, {
+ EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY: "rotated-credentials-key",
+ EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY_PREVIOUS: "original-credentials-key",
+ })).resolves.toBe("provider-key");
+ });
+
+ test("marks mapped providers when saved credentials are unavailable", () => {
+ const settings = mapAiProviderConfig({
+ id: "aip_personal",
+ workspace_id: "ws_personal",
+ provider: "openai-compatible",
+ display_name: "My model",
+ base_url: "https://models.example.com/v1",
+ api_key_encrypted: "v1.secret.ciphertext",
+ is_enabled: 1,
+ created_at: "2026-08-10T00:00:00.000Z",
+ updated_at: "2026-08-10T00:00:00.000Z",
+ }, [], true);
+ expect(settings.credentialsUnavailable).toBe(true);
+ expect(settings.hasApiKey).toBe(true);
+ expect(JSON.stringify(settings)).not.toContain("ciphertext");
+ });
+
test("never exposes the encrypted API key in settings", () => {
const settings = mapAiProviderConfig({
id: "aip_personal",
diff --git a/apps/api/src/ai-service.ts b/apps/api/src/ai-service.ts
index 2023069e..ed32d502 100644
--- a/apps/api/src/ai-service.ts
+++ b/apps/api/src/ai-service.ts
@@ -59,9 +59,11 @@ export const resolveCredentialEncryptionKey = (value: string | undefined) => {
export type AiCredentialEnvironment = {
EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY?: string;
+ EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY_PREVIOUS?: string;
EDGE_EVER_STORAGE_ENCRYPTION_KEY?: string;
EDGE_EVER_AUTH_PASSWORD?: string;
EDGE_EVER_AUTH_PASSWORD_HASH?: string;
+ EDGE_EVER_AUTH_PASSWORD_FALLBACK?: string;
};
const uniqueKeys = (values: Array<string | undefined>) => Array.from(new Set(values.filter(Boolean) as string[]));
@@ -79,6 +81,8 @@ export const resolveAiCredentialEncryptionKeys = (environment: AiCredentialEnvir
deriveAiCredentialKey(resolveCredentialEncryptionKey(environment.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY)),
deriveAiCredentialKey(resolveCredentialEncryptionKey(environment.EDGE_EVER_AUTH_PASSWORD)),
deriveAiCredentialKey(resolveCredentialEncryptionKey(environment.EDGE_EVER_AUTH_PASSWORD_HASH)),
+ deriveAiCredentialKey(resolveCredentialEncryptionKey(environment.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY_PREVIOUS)),
+ deriveAiCredentialKey(resolveCredentialEncryptionKey(environment.EDGE_EVER_AUTH_PASSWORD_FALLBACK)),
resolveCredentialEncryptionKey(environment.EDGE_EVER_STORAGE_ENCRYPTION_KEY),
]);
@@ -154,6 +158,7 @@ export const mapAiModelConfig = (row: AiModelConfigRow): AiModelConfig => ({
export const mapAiProviderConfig = (
row: AiProviderConfigRow,
models: AiModelConfigRow[],
+ credentialsUnavailable = false,
): AiProviderConfig => ({
id: row.id,
provider: row.provider,
@@ -162,14 +167,32 @@ export const mapAiProviderConfig = (
isEnabled: Boolean(row.is_enabled),
hasApiKey: Boolean(row.api_key_encrypted),
models: models.filter((model) => model.provider_config_id === row.id).map(mapAiModelConfig),
+ ...(credentialsUnavailable ? { credentialsUnavailable: true } : {}),
});
+const withAiCredentialAvailability = async (
+ row: AiProviderConfigRow,
+ models: AiModelConfigRow[],
+ encryptionConfigured: boolean,
+ environment?: AiCredentialEnvironment,
+): Promise<AiProviderConfig> => {
+ const mapped = mapAiProviderConfig(row, models);
+ if (!encryptionConfigured || !environment || !row.api_key_encrypted) return mapped;
+ try {
+ await decryptAiCredential(row.api_key_encrypted, environment);
+ return mapped;
+ } catch {
+ return mapAiProviderConfig(row, models, true);
+ }
+};
+
export const getAiSettings = async (
db: DatabaseAdapter,
workspaceId: string,
encryptionConfigured: boolean,
readOnly: boolean,
locale?: string,
+ environment?: AiCredentialEnvironment,
): Promise<AiSettings> => {
const [providersResult, modelsResult, defaultModelId, promptRow] = await Promise.all([
db.prepare(
@@ -191,8 +214,8 @@ export const getAiSettings = async (
const customizedPrompt = promptRow?.tag_suggestion_prompt?.trim() || null;
return {
- providers: providersResult.results.map((provider) =>
- mapAiProviderConfig(provider, modelsResult.results)),
+ providers: await Promise.all(providersResult.results.map((provider) =>
+ withAiCredentialAvailability(provider, modelsResult.results, encryptionConfigured, environment))),
defaultModelId,
tagSuggestionPrompt: customizedPrompt ?? getDefaultAiTagSuggestionPrompt(locale),
tagSuggestionPromptCustomized: Boolean(customizedPrompt),
diff --git a/apps/api/src/api-context.ts b/apps/api/src/api-context.ts
index eb0513ac..2e6b1c5b 100644
--- a/apps/api/src/api-context.ts
+++ b/apps/api/src/api-context.ts
@@ -14,6 +14,7 @@ export type Bindings = {
EDGE_EVER_DEPLOYMENT_METHOD?: string;
EDGE_EVER_AUTH_PASSWORD?: string;
EDGE_EVER_AUTH_PASSWORD_HASH?: string;
+ EDGE_EVER_AUTH_PASSWORD_FALLBACK?: string;
EDGE_EVER_SESSION_TTL_DAYS?: string;
EDGE_EVER_AUTH_LOGIN_WINDOW_SECONDS?: string;
EDGE_EVER_AUTH_LOGIN_USERNAME_MAX_ATTEMPTS?: string;
@@ -24,6 +25,7 @@ export type Bindings = {
/** Legacy decryption fallback; new credentials use auth-derived keys. */
EDGE_EVER_STORAGE_ENCRYPTION_KEY?: string;
EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY?: string;
+ EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY_PREVIOUS?: string;
EDGE_EVER_DEMO_MODE?: string;
EDGE_EVER_LOCAL_DEMO_SEED?: string;
EDGE_EVER_ALLOW_UNAUTHENTICATED?: string;
diff --git a/apps/api/src/object-storage.test.mjs b/apps/api/src/object-storage.test.mjs
index c66f7931..3d1173e0 100644
--- a/apps/api/src/object-storage.test.mjs
+++ b/apps/api/src/object-storage.test.mjs
@@ -51,6 +51,19 @@ describe("object storage credential encryption", () => {
expect(resolveObjectStorageEncryptionKeys(environment)).toEqual(["legacy-storage-key"]);
});
+ test("decrypts rotated object-storage secrets with the persisted auth fallback", () => {
+ const environment = {
+ EDGE_EVER_AUTH_PASSWORD: "rotated-password",
+ EDGE_EVER_AUTH_PASSWORD_FALLBACK: "original-password",
+ };
+
+ expect(resolvePrimaryObjectStorageEncryptionKey(environment))
+ .toBe("edgeever:object-storage:v1:rotated-password");
+ expect(resolveObjectStorageEncryptionKeys(environment)).toContain(
+ "edgeever:object-storage:v1:original-password",
+ );
+ });
+
test("migrates a legacy object-storage credential after decrypting it", async () => {
const plaintext = "legacy-secret-access-key";
const legacyKey = "legacy-storage-key";
diff --git a/apps/api/src/object-storage.ts b/apps/api/src/object-storage.ts
index 571c6643..47c4a70e 100644
--- a/apps/api/src/object-storage.ts
+++ b/apps/api/src/object-storage.ts
@@ -19,6 +19,7 @@ const deriveObjectStorageCredentialKey = (value: string | undefined) => value
export type ObjectStorageCredentialEnvironment = {
EDGE_EVER_AUTH_PASSWORD?: string;
EDGE_EVER_AUTH_PASSWORD_HASH?: string;
+ EDGE_EVER_AUTH_PASSWORD_FALLBACK?: string;
/** Legacy decryption fallback for credentials saved before auth-derived keys. */
EDGE_EVER_STORAGE_ENCRYPTION_KEY?: string;
};
@@ -34,6 +35,7 @@ export const resolveObjectStorageEncryptionKeys = (
environment: ObjectStorageCredentialEnvironment,
) => [
...resolveAuthDerivedObjectStorageEncryptionKeys(environment),
+ deriveObjectStorageCredentialKey(resolveCredentialEncryptionKey(environment.EDGE_EVER_AUTH_PASSWORD_FALLBACK)),
resolveCredentialEncryptionKey(environment.EDGE_EVER_STORAGE_ENCRYPTION_KEY),
].filter(Boolean) as string[];
@@ -59,6 +61,7 @@ type ObjectStorageEnvironment = {
storage: { db: DatabaseAdapter; resources: BlobStoreAdapter };
EDGE_EVER_AUTH_PASSWORD?: string;
EDGE_EVER_AUTH_PASSWORD_HASH?: string;
+ EDGE_EVER_AUTH_PASSWORD_FALLBACK?: string;
EDGE_EVER_STORAGE_ENCRYPTION_KEY?: string;
EDGE_EVER_R2_BUCKET_NAME?: string;
};
diff --git a/apps/api/src/plugin-capability-routes.ts b/apps/api/src/plugin-capability-routes.ts
index 1eeedd13..175e5f04 100644
--- a/apps/api/src/plugin-capability-routes.ts
+++ b/apps/api/src/plugin-capability-routes.ts
@@ -29,7 +29,7 @@ export function registerPluginCapabilityRoutes(app: Hono<AppEnv>, dependencies:
}
app.get('/api/v1/plugins/ai/status', async c => {
if (dependencies.aiStatus) return c.json(await dependencies.aiStatus());
- const settings = await getAiSettings(c.env.storage.db, getWorkspaceId(c), Boolean(resolvePrimaryAiCredentialEncryptionKey(c.env)), false);
+ const settings = await getAiSettings(c.env.storage.db, getWorkspaceId(c), Boolean(resolvePrimaryAiCredentialEncryptionKey(c.env)), false, undefined, c.env);
const provider = settings.providers.find(p => p.isEnabled && p.models.some(m => m.id === settings.defaultModelId));
const model = provider?.models.find(m => m.id === settings.defaultModelId);
return c.json({ configured: Boolean(model), ...(model ? { modelName: model.displayName } : {}) });
diff --git a/apps/web/src/components/settings/AiModelCard.tsx b/apps/web/src/components/settings/AiModelCard.tsx
index 97eae5c5..afff6673 100644
--- a/apps/web/src/components/settings/AiModelCard.tsx
+++ b/apps/web/src/components/settings/AiModelCard.tsx
@@ -12,6 +12,7 @@ import {
} from "@/components/settings/ai-provider-options";
import { Button } from "@/components/ui/button";
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
import {
SETTINGS_CARD_DESCRIPTION_CLASSNAME,
SETTINGS_CARD_HEADER_CLASSNAME,
@@ -99,6 +100,9 @@ export const AiModelCard = () => {
const settings = settingsQuery.data;
const readOnly = settings?.readOnly ?? true;
+ const encryptionConfigured = settings?.encryptionConfigured ?? false;
+ const canAddProvider = !readOnly && encryptionConfigured;
+ const hasUnavailableCredentials = settings?.providers.some((item) => item.credentialsUnavailable) ?? false;
const getDefaultProviderName = (index: number) => t("aiModel.defaultProviderName", {
ordinal: formatProviderOrdinal(index + 1, locale),
});
@@ -112,9 +116,11 @@ export const AiModelCard = () => {
|| allModels.some((model) => model.id === settings.defaultModelId && model.providerEnabled);
const error = defaultMutation.error ?? settingsQuery.error;
const openAddDialog = () => {
+ if (!canAddProvider) return;
resetAddForm(getDefaultProviderName(settings?.providers.length ?? 0));
setShowAdd(true);
};
+ const addDisabledReason = !encryptionConfigured ? t("aiModel.addDisabledReason") : undefined;
return (
<Collapsible open={expanded} onOpenChange={setExpanded} asChild>
@@ -139,11 +145,16 @@ export const AiModelCard = () => {
<p className="flex items-center gap-2 text-sm text-slate-500"><Loader2 className="h-4 w-4 animate-spin" />{t("common.loading")}</p>
) : (
<>
- {!settings?.encryptionConfigured ? (
+ {!encryptionConfigured ? (
<p className="flex items-start gap-2 rounded-lg border border-amber-200 bg-amber-50 p-3 text-xs leading-5 text-amber-800">
<TriangleAlert className="mt-0.5 h-4 w-4 shrink-0" />{t("aiModel.encryptionKeyMissing")}
</p>
) : null}
+ {hasUnavailableCredentials ? (
+ <p className="flex items-start gap-2 rounded-lg border border-amber-200 bg-amber-50 p-3 text-xs leading-5 text-amber-800">
+ <TriangleAlert className="mt-0.5 h-4 w-4 shrink-0" />{t("aiModel.savedCredentialsUnavailable")}
+ </p>
+ ) : null}
<section className="grid gap-2">
<span className="text-xs font-semibold text-slate-500">
@@ -207,9 +218,11 @@ export const AiModelCard = () => {
{settings?.providers.length ?? 0}
</span>
</div>
- <Button type="button" variant="outline" size="sm" className="h-8 gap-1.5 bg-white text-xs" disabled={readOnly} onClick={openAddDialog}>
- <Plus className="h-3.5 w-3.5" />{t("aiModel.addProvider")}
- </Button>
+ <DisabledActionTooltip label={!canAddProvider ? addDisabledReason : undefined}>
+ <Button type="button" variant="outline" size="sm" className="h-8 gap-1.5 bg-white text-xs" disabled={!canAddProvider} onClick={openAddDialog}>
+ <Plus className="h-3.5 w-3.5" />{t("aiModel.addProvider")}
+ </Button>
+ </DisabledActionTooltip>
</div>
{settings?.providers.length ? (
@@ -239,11 +252,16 @@ export const AiModelCard = () => {
<Dialog open={showAdd} onOpenChange={handleAddDialogChange}>
<DialogContent className="max-h-[calc(100vh-2rem)] overflow-y-auto sm:max-w-2xl">
- <form className="grid gap-5" onSubmit={(event: FormEvent) => { event.preventDefault(); createMutation.mutate(); }}>
+ <form className="grid gap-5" onSubmit={(event: FormEvent) => { event.preventDefault(); if (!canAddProvider) return; createMutation.mutate(); }}>
<DialogHeader>
<DialogTitle>{t("aiModel.addProvider")}</DialogTitle>
<DialogDescription>{t("aiModel.addProviderDescription")}</DialogDescription>
</DialogHeader>
+ {!encryptionConfigured ? (
+ <p className="flex items-start gap-2 rounded-lg border border-amber-200 bg-amber-50 p-3 text-xs leading-5 text-amber-800">
+ <TriangleAlert className="mt-0.5 h-4 w-4 shrink-0" />{t("aiModel.encryptionKeyMissing")}
+ </p>
+ ) : null}
<div className="grid gap-4 sm:grid-cols-2">
<Field label={t("aiModel.displayName")}>
<Input value={displayName} onChange={(event) => setDisplayName(event.target.value)} required maxLength={80} />
@@ -274,20 +292,22 @@ export const AiModelCard = () => {
</div>
{createMutation.isError ? (
<p className="text-xs font-medium text-rose-600" role="alert">
- {aiErrorMessage(createMutation.error, t("aiModel.failed"), t("aiModel.encryptionKeyMissing"))}
+ {aiErrorMessage(createMutation.error, t("aiModel.failed"), t("aiModel.encryptionKeyMissing"), t("aiModel.savedCredentialsUnavailable"))}
</p>
) : null}
<DialogFooter className="gap-2 sm:space-x-0">
<Button type="button" variant="outline" onClick={() => handleAddDialogChange(false)}>{t("common.cancel")}</Button>
- <Button type="submit" variant="solid" disabled={readOnly || createMutation.isPending || !settings?.encryptionConfigured}>
- {createMutation.isPending ? <Loader2 className="h-4 w-4 animate-spin" /> : null}{t("aiModel.createProvider")}
- </Button>
+ <DisabledActionTooltip label={!canAddProvider ? addDisabledReason : undefined}>
+ <Button type="submit" variant="solid" disabled={!canAddProvider || createMutation.isPending}>
+ {createMutation.isPending ? <Loader2 className="h-4 w-4 animate-spin" /> : null}{t("aiModel.createProvider")}
+ </Button>
+ </DisabledActionTooltip>
</DialogFooter>
</form>
</DialogContent>
</Dialog>
- {error ? <p className="text-xs font-medium text-rose-600" role="alert">{aiErrorMessage(error, t("aiModel.failed"), t("aiModel.encryptionKeyMissing"))}</p> : null}
+ {error ? <p className="text-xs font-medium text-rose-600" role="alert">{aiErrorMessage(error, t("aiModel.failed"), t("aiModel.encryptionKeyMissing"), t("aiModel.savedCredentialsUnavailable"))}</p> : null}
</>
)}
</CardContent>
@@ -302,3 +322,17 @@ const Field = ({ label, hint, children }: { label: string; hint?: string; childr
{label}{children}{hint ? <span className="text-xs font-normal leading-4 text-slate-500">{hint}</span> : null}
</label>
);
+
+const DisabledActionTooltip = ({ label, children }: { label?: string; children: ReactNode }) => {
+ if (!label) return children;
+ return (
+ <TooltipProvider delayDuration={0} skipDelayDuration={0}>
+ <Tooltip>
+ <TooltipTrigger asChild>
+ <span className="inline-flex" tabIndex={0}>{children}</span>
+ </TooltipTrigger>
+ <TooltipContent side="bottom">{label}</TooltipContent>
+ </Tooltip>
+ </TooltipProvider>
+ );
+};
diff --git a/apps/web/src/components/settings/AiProviderCard.tsx b/apps/web/src/components/settings/AiProviderCard.tsx
index 9593a47e..ca6adbd4 100644
--- a/apps/web/src/components/settings/AiProviderCard.tsx
+++ b/apps/web/src/components/settings/AiProviderCard.tsx
@@ -165,6 +165,11 @@ export const AiProviderCard = ({ provider: saved, defaultDisplayName, defaultMod
<div className="flex items-center justify-between gap-3">
<div className="flex min-w-0 flex-wrap items-center gap-2">
<span className="truncate text-sm font-semibold text-slate-900">{effectiveDisplayName}</span>
+ {saved.credentialsUnavailable ? (
+ <span className="rounded-md bg-amber-50 px-2 py-0.5 text-[11px] font-medium text-amber-800">
+ {t("aiModel.savedCredentialsUnavailableBadge")}
+ </span>
+ ) : null}
<span className="rounded-md bg-slate-100 px-2 py-0.5 text-[11px] font-medium text-slate-600">
{providerLabel}
</span>
@@ -276,7 +281,7 @@ export const AiProviderCard = ({ provider: saved, defaultDisplayName, defaultMod
{cardError ? (
<p className="border-t px-4 py-3 text-xs font-medium text-rose-600" role="alert">
- {aiErrorMessage(cardError, t("aiModel.failed"), t("aiModel.encryptionKeyMissing"))}
+ {aiErrorMessage(cardError, t("aiModel.failed"), t("aiModel.encryptionKeyMissing"), t("aiModel.savedCredentialsUnavailable"))}
</p>
) : null}
@@ -326,7 +331,7 @@ export const AiProviderCard = ({ provider: saved, defaultDisplayName, defaultMod
) : null}
{connectionError ? (
<p className="text-xs font-medium text-rose-600" role="alert">
- {aiErrorMessage(connectionError, t("aiModel.failed"), t("aiModel.encryptionKeyMissing"))}
+ {aiErrorMessage(connectionError, t("aiModel.failed"), t("aiModel.encryptionKeyMissing"), t("aiModel.savedCredentialsUnavailable"))}
</p>
) : null}
<DialogFooter className="gap-2 sm:space-x-0">
@@ -368,7 +373,7 @@ export const AiProviderCard = ({ provider: saved, defaultDisplayName, defaultMod
</Field>
{discoverMutation.error || addModelMutation.error ? (
<p className="text-xs font-medium text-rose-600" role="alert">
- {aiErrorMessage(discoverMutation.error ?? addModelMutation.error, t("aiModel.failed"), t("aiModel.encryptionKeyMissing"))}
+ {aiErrorMessage(discoverMutation.error ?? addModelMutation.error, t("aiModel.failed"), t("aiModel.encryptionKeyMissing"), t("aiModel.savedCredentialsUnavailable"))}
</p>
) : null}
<DialogFooter className="gap-2 sm:space-x-0 sm:justify-between">
diff --git a/apps/web/src/components/settings/ObjectStorageCard.tsx b/apps/web/src/components/settings/ObjectStorageCard.tsx
index 5c55a923..9ef8f925 100644
--- a/apps/web/src/components/settings/ObjectStorageCard.tsx
+++ b/apps/web/src/components/settings/ObjectStorageCard.tsx
@@ -4,6 +4,7 @@ import { CheckCircle2, Cloud, Database, Loader2, TriangleAlert } from "lucide-re
import { useTranslation } from "react-i18next";
import { Button } from "@/components/ui/button";
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
import {
SETTINGS_CARD_DESCRIPTION_CLASSNAME,
SETTINGS_CARD_HEADER_CLASSNAME,
@@ -146,7 +147,20 @@ export const ObjectStorageCard = ({ demoMode }: { demoMode: boolean }) => {
<div className="flex flex-wrap justify-end gap-2">
{provider === "s3" ? <Button type="button" variant="outline" disabled={testMutation.isPending || saveMutation.isPending} onClick={() => testMutation.mutate()}>{testMutation.isPending ? <Loader2 className="h-4 w-4 animate-spin" /> : null}{t("objectStorage.test")}</Button> : null}
- <Button type="submit" disabled={demoMode || saveMutation.isPending || (provider === "s3" && !encryptionConfigured)}>{saveMutation.isPending ? <Loader2 className="h-4 w-4 animate-spin" /> : null}{t("common.save")}</Button>
+ {provider === "s3" && !encryptionConfigured ? (
+ <TooltipProvider delayDuration={0} skipDelayDuration={0}>
+ <Tooltip>
+ <TooltipTrigger asChild>
+ <span className="inline-flex" tabIndex={0}>
+ <Button type="submit" disabled>{saveMutation.isPending ? <Loader2 className="h-4 w-4 animate-spin" /> : null}{t("common.save")}</Button>
+ </span>
+ </TooltipTrigger>
+ <TooltipContent side="bottom">{t("objectStorage.authenticationRequired")}</TooltipContent>
+ </Tooltip>
+ </TooltipProvider>
+ ) : (
+ <Button type="submit" disabled={demoMode || saveMutation.isPending}>{saveMutation.isPending ? <Loader2 className="h-4 w-4 animate-spin" /> : null}{t("common.save")}</Button>
+ )}
</div>
<p className="text-xs leading-5 text-slate-500">{demoMode ? t("objectStorage.demoDisabled") : t("objectStorage.switchHint")}</p>
</form>
diff --git a/apps/web/src/components/settings/ai-provider-options.test.mjs b/apps/web/src/components/settings/ai-provider-options.test.mjs
index 4a24562d..50439854 100644
--- a/apps/web/src/components/settings/ai-provider-options.test.mjs
+++ b/apps/web/src/components/settings/ai-provider-options.test.mjs
@@ -39,5 +39,8 @@ describe("AI settings cards tolerate missing text fields", () => {
expect(providerCard).toContain("trimAiText(displayName)");
expect(providerCard).toContain("trimAiText(baseUrl)");
expect(modelCard).toContain("!item.displayName");
+ expect(modelCard).toContain("canAddProvider");
+ expect(modelCard).toContain("addDisabledReason");
+ expect(modelCard).toContain("savedCredentialsUnavailable");
});
});
diff --git a/apps/web/src/components/settings/ai-provider-options.ts b/apps/web/src/components/settings/ai-provider-options.ts
index 4cb5325c..7190a6bf 100644
--- a/apps/web/src/components/settings/ai-provider-options.ts
+++ b/apps/web/src/components/settings/ai-provider-options.ts
@@ -22,7 +22,13 @@ export const trimAiText = (value: string | null | undefined) => (value ?? "").tr
export const isLegacyProviderDisplayName = (displayName: string | null | undefined, provider: AiProvider) =>
trimAiText(displayName).toLocaleLowerCase() === (providerDefaults[provider]?.displayName ?? "").toLocaleLowerCase();
-export const aiErrorMessage = (error: unknown, fallback: string, encryptionMessage: string) => {
+export const aiErrorMessage = (
+ error: unknown,
+ fallback: string,
+ encryptionMessage: string,
+ unavailableMessage = encryptionMessage,
+) => {
if (error instanceof ApiRequestError && error.code === "ai_encryption_key_missing") return encryptionMessage;
+ if (error instanceof ApiRequestError && error.code === "ai_credentials_unavailable") return unavailableMessage;
return error instanceof Error ? error.message : fallback;
};
diff --git a/docs/deploy-docker.md b/docs/deploy-docker.md
index 3c5e04f2..5a82398c 100644
--- a/docs/deploy-docker.md
+++ b/docs/deploy-docker.md
@@ -75,8 +75,9 @@ Compose creates one named volume. Everything that must survive a container
replacement is under `/data`:
```text
-/data/edgeever.sqlite SQLite database
-/data/resources/ local images and attachments
+/data/edgeever.sqlite SQLite database
+/data/edgeever-secrets.json credential encryption secret
+/data/resources/ local images and attachments
```
The image runs as the non-root `bun` user (UID/GID `1000`). If a NAS requires
@@ -99,7 +100,7 @@ Common environment variables:
| `EDGE_EVER_AUTH_PASSWORD_HASH` | none | PBKDF2 hash alternative to the plaintext bootstrap password |
| `EDGE_EVER_SESSION_TTL_DAYS` | `400` | Login session lifetime |
| `EDGE_EVER_IDLE_TIMEOUT_SECONDS` | `120` | Bun streaming idle timeout, from 10 to 255 seconds |
-| `EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY` | derived | Optional independent AI credential encryption key |
+| `EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY` | persisted on `/data` | Optional independent AI credential encryption key. If unset, Docker stores the authentication secret or a generated key in `/data/edgeever-secrets.json`. |
For secrets, append `_FILE` to a supported variable and point it at a Docker
secret, for example `EDGE_EVER_AUTH_PASSWORD_FILE=/run/secrets/auth_password`.
@@ -142,19 +143,20 @@ of the `/data` volume for complete instance recovery:
1. Run `docker compose stop edgeever` and wait for the shutdown-complete log.
EdgeEver checkpoints SQLite's WAL during graceful shutdown.
-2. Copy or snapshot the entire named volume, including the SQLite file and
- `resources` directory.
+2. Copy or snapshot the entire named volume, including the SQLite file,
+ `edgeever-secrets.json`, and the `resources` directory.
3. Start the service with `docker compose start edgeever`.
-Keep the instance authentication secret and any explicitly configured
-`EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY` in a separate secret backup. EdgeEver
-derives purpose-specific keys for saved credentials from the authentication
-secret, so a volume backup cannot decrypt them without it. When S3 storage is
+Docker persists the credential-encryption root in `/data/edgeever-secrets.json`,
+so a complete `/data` volume backup can decrypt saved AI and object-storage
+credentials after a container rebuild. Keep any explicit
+`EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY` in a separate secret backup if you
+manage secrets outside the volume. Cloudflare deployments still require the
+Worker authentication secret; they do not use this file. When S3 storage is
enabled, back up the bucket separately.
-Restore only while EdgeEver is stopped, into an empty volume, and restore the
-matching secret keys at the same time. Test backups periodically on a separate
-instance.
+Restore only while EdgeEver is stopped, into an empty volume. Test backups
+periodically on a separate instance.
## Upgrade and rollback
diff --git a/docs/deploy-docker.zh-CN.md b/docs/deploy-docker.zh-CN.md
index 45876b1a..edcc9db6 100644
--- a/docs/deploy-docker.zh-CN.md
+++ b/docs/deploy-docker.zh-CN.md
@@ -69,8 +69,9 @@ docker compose ps
Compose 会创建一个命名卷。所有需要在容器替换后保留的数据都位于 `/data`:
```text
-/data/edgeever.sqlite SQLite 数据库
-/data/resources/ 本地图片与附件
+/data/edgeever.sqlite SQLite 数据库
+/data/edgeever-secrets.json 凭据加密根密钥
+/data/resources/ 本地图片与附件
```
镜像以非 root 的 `bun` 用户运行(UID/GID 均为 `1000`)。如果 NAS 必须使用主机
@@ -90,7 +91,7 @@ Compose 会创建一个命名卷。所有需要在容器替换后保留的数据
| `EDGE_EVER_AUTH_PASSWORD_HASH` | 无 | 可替代明文引导密码的 PBKDF2 hash |
| `EDGE_EVER_SESSION_TTL_DAYS` | `400` | 登录会话有效期 |
| `EDGE_EVER_IDLE_TIMEOUT_SECONDS` | `120` | Bun 流式响应空闲超时,可设为 10 到 255 秒 |
-| `EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY` | 自动派生 | 可选的独立 AI 凭据加密密钥 |
+| `EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY` | 写入 `/data` | 可选的独立 AI 凭据加密密钥。未设置时,Docker 会把认证 Secret 或自动生成的密钥写入 `/data/edgeever-secrets.json`。 |
Secret 可在受支持的变量名后追加 `_FILE`,并指向 Docker secret,例如
`EDGE_EVER_AUTH_PASSWORD_FILE=/run/secrets/auth_password`。密码/hash 和 S3
@@ -131,15 +132,17 @@ HTTPS,并转发原始 Host 和客户端地址。严禁公开 SQLite、`/data`
1. 执行 `docker compose stop edgeever`,等待日志出现 shutdown complete。
EdgeEver 会在优雅停机时 checkpoint SQLite WAL。
-2. 完整复制或快照命名卷,包括 SQLite 文件与 `resources` 目录。
+2. 完整复制或快照命名卷,包括 SQLite 文件、`edgeever-secrets.json` 与
+ `resources` 目录。
3. 执行 `docker compose start edgeever` 恢复服务。
-请单独备份实例认证 Secret,以及显式配置的
-`EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY`。EdgeEver 会从认证 Secret 派生不同用途
-的凭据密钥,缺少它时卷备份无法解密已保存的凭据。使用 S3 时还需独立备份存储桶。
+Docker 会把凭据加密根密钥保存在 `/data/edgeever-secrets.json`,因此完整的
+`/data` 卷备份在容器重建后仍可解密已保存的 AI 与对象存储凭据。如果你在数据卷
+之外单独管理密钥,请继续备份显式配置的
+`EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY`。Cloudflare 部署仍使用 Worker Secret,
+不会读写该文件。使用 S3 时还需独立备份存储桶。
-只能在 EdgeEver 停止时恢复到空卷,并同时恢复匹配的 Secret。应定期在独立
-实例中验证备份。
+只能在 EdgeEver 停止时恢复到空卷。应定期在独立实例中验证备份。
## 升级与回滚
diff --git a/docs/self-hosting-architecture.md b/docs/self-hosting-architecture.md
index f2cfe751..0443e763 100644
--- a/docs/self-hosting-architecture.md
+++ b/docs/self-hosting-architecture.md
@@ -35,8 +35,9 @@ persistent `/data` mount:
```text
EdgeEver container
-├── SQLite database -> /data/edgeever.sqlite
-└── attachment store -> /data/resources
+├── SQLite database -> /data/edgeever.sqlite
+├── credential secrets -> /data/edgeever-secrets.json
+└── attachment store -> /data/resources
```
The self-hosted adapter preserves the existing SQLite schema and
@@ -55,11 +56,14 @@ ambiguous.
- Keep the current migration files append-only; do not fork the schema for
Docker.
- Keep root secrets in environment variables or Docker secrets, never in the
- image or database. Object-storage secrets and personal AI model API keys use
- separate purpose-specific keys derived from the existing instance
- authentication secret. An optional `EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY`
- can override the AI credential key for advanced rotation.
- Stored credentials must remain AES-GCM ciphertext.
+ image or database. The self-hosted runtime may persist a copy on `/data`
+ outside SQLite so NAS/GUI upgrades that drop container environment variables
+ keep credential encryption. Cloudflare continues to use Worker secrets only.
+ Object-storage secrets and personal AI model API keys use separate
+ purpose-specific keys derived from the existing instance authentication
+ secret. An optional `EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY` can override the
+ AI credential key for advanced rotation. Stored credentials must remain
+ AES-GCM ciphertext.
- Make `/data` the only required persistent application path so NAS users can
back up one volume.
- Support `EDGE_EVER_AUTH_USERNAME`, `EDGE_EVER_AUTH_PASSWORD`, and session
diff --git a/docs/self-hosting-architecture.zh-CN.md b/docs/self-hosting-architecture.zh-CN.md
index a332cc1b..3164f7bf 100644
--- a/docs/self-hosting-architecture.zh-CN.md
+++ b/docs/self-hosting-architecture.zh-CN.md
@@ -31,8 +31,9 @@ SQLite 仍是自托管默认数据库;未来 PostgreSQL 更适合较大团队
```text
EdgeEver 容器
-├── SQLite 数据库 -> /data/edgeever.sqlite
-└── 附件存储 -> /data/resources
+├── SQLite 数据库 -> /data/edgeever.sqlite
+├── 凭据加密根密钥 -> /data/edgeever-secrets.json
+└── 附件存储 -> /data/resources
```
自托管适配器继续复用现有 SQLite 结构和 `migrations/*.sql`;附件继续使用
@@ -46,7 +47,7 @@ S3 兼容对象存储两种后端。
- 保持 `/api/*`、`/mcp`、`/api/openapi.json` 和 `/api/health` 不变。
- 继续追加 `migrations/*.sql`,禁止为 Docker 分叉数据库结构。
-- 根密钥必须通过环境变量或 Docker secrets 注入,不能写入镜像或数据库。对象存储 Secret 与个人 AI 模型 API Key 默认从已有实例认证 Secret 派生各自用途的专用密钥;高级 AI 密钥轮换场景可选用 `EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY` 覆盖。所有凭据在数据库中只能保存为 AES-GCM 密文。
+- 根密钥必须通过环境变量或 Docker secrets 注入,不能写入镜像或数据库。自托管运行入口可以把副本写在 `/data`(SQLite 之外),以便 NAS/GUI 升级丢掉容器环境变量后仍能加密凭据。Cloudflare 继续只使用 Worker Secret。对象存储 Secret 与个人 AI 模型 API Key 默认从已有实例认证 Secret 派生各自用途的专用密钥;高级 AI 密钥轮换场景可选用 `EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY` 覆盖。所有凭据在数据库中只能保存为 AES-GCM 密文。
- 将 `/data` 作为唯一必需的应用持久化路径,方便 NAS 用户备份一个卷。
- 容器入口需要支持 `EDGE_EVER_AUTH_USERNAME`、`EDGE_EVER_AUTH_PASSWORD` 和
会话配置,同时不能把 Cloudflare 专有配置当作前置条件。
diff --git a/packages/shared/src/i18n/en-US.ts b/packages/shared/src/i18n/en-US.ts
index ac226ea5..b208b45f 100644
--- a/packages/shared/src/i18n/en-US.ts
+++ b/packages/shared/src/i18n/en-US.ts
@@ -828,7 +828,7 @@ export const enUS = {
testSucceeded: "Upload, read, and delete checks passed.",
saved: "Object storage settings saved.",
failed: "The object storage operation failed.",
- authenticationRequired: "Enable instance authentication before saving third-party storage credentials.",
+ authenticationRequired: "Set EDGE_EVER_AUTH_PASSWORD in the deployment environment before saving third-party storage credentials. Docker stores this secret on the data volume so later upgrades do not lose it.",
switchHint: "Switching only affects new uploads. Existing attachments remain in their original store and are not migrated automatically.",
demoDisabled: "Object storage cannot be changed on the demo instance.",
},
@@ -885,7 +885,10 @@ export const enUS = {
testSucceeded: "The model endpoint responded successfully.",
saved: "Model service saved.",
failed: "The AI model operation failed.",
- encryptionKeyMissing: "Encrypted AI credentials require instance authentication. Configure authentication first; an independent credential key is optional for advanced deployments.",
+ encryptionKeyMissing: "This instance cannot encrypt AI credentials. Set EDGE_EVER_AUTH_PASSWORD, or the optional EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY, in the deployment environment and restart. Docker stores the secret on the data volume so later upgrades do not lose it.",
+ addDisabledReason: "Configure the instance authentication secret before adding a model service",
+ savedCredentialsUnavailable: "Saved model credentials cannot be decrypted. Open the service and enter the API key again.",
+ savedCredentialsUnavailableBadge: "Re-enter API key",
privacyNotice: "Please use trusted model providers or API proxies to protect your personal privacy.",
},
aiPrompts: {
diff --git a/packages/shared/src/i18n/zh-CN.ts b/packages/shared/src/i18n/zh-CN.ts
index 8f502c21..10f6aef3 100644
--- a/packages/shared/src/i18n/zh-CN.ts
+++ b/packages/shared/src/i18n/zh-CN.ts
@@ -828,7 +828,7 @@ export const zhCN = {
testSucceeded: "上传、读取和删除测试均已通过。",
saved: "对象存储设置已保存。",
failed: "对象存储操作失败。",
- authenticationRequired: "保存第三方存储凭据前,请先启用实例认证。",
+ authenticationRequired: "保存第三方存储凭据前,请在部署环境中设置 EDGE_EVER_AUTH_PASSWORD。Docker 会把该密钥写入数据卷,避免以后升级时丢失。",
switchHint: "切换只影响后续上传;已有附件仍从原存储读取,不会自动迁移。",
demoDisabled: "演示实例不允许修改对象存储。",
},
@@ -885,7 +885,10 @@ export const zhCN = {
testSucceeded: "模型服务已成功响应。",
saved: "模型服务已保存。",
failed: "AI 模型操作失败。",
- encryptionKeyMissing: "加密保存 AI 凭据需要先启用实例认证;标准部署无需增加环境变量,高级部署可选用独立凭据密钥。",
+ encryptionKeyMissing: "当前实例无法加密保存 AI 凭据。请在部署环境中设置 EDGE_EVER_AUTH_PASSWORD,或可选的 EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY,然后重启实例。Docker 会把密钥写入数据卷,避免以后升级时丢失。",
+ addDisabledReason: "需要先配置实例认证密钥才能添加模型服务",
+ savedCredentialsUnavailable: "已保存的模型凭据无法解密,请打开该服务并重新填写 API Key。",
+ savedCredentialsUnavailableBadge: "需重新填写密钥",
privacyNotice: "请务必选用可信赖的模型服务商或 API 代理节点,避免个人隐私泄露。",
},
aiPrompts: {
diff --git a/packages/shared/src/types.ts b/packages/shared/src/types.ts
index ee2dbc66..afe0b197 100644
--- a/packages/shared/src/types.ts
+++ b/packages/shared/src/types.ts
@@ -172,6 +172,7 @@ export type AiProviderConfig = {
isEnabled: boolean;
hasApiKey: boolean;
models: AiModelConfig[];
+ credentialsUnavailable?: boolean;
};
export type AiSettings = {
diff --git a/scripts/docker-release.test.mjs b/scripts/docker-release.test.mjs
index ab7fe96a..a8a61d43 100644
--- a/scripts/docker-release.test.mjs
+++ b/scripts/docker-release.test.mjs
@@ -127,6 +127,21 @@ describe("Docker release contract", () => {
'import { createS3CompatibleStorageAdapter } from',
);
expect(selfHosted).not.toContain("worker.fetch(");
+ expect(selfHosted).toContain("ensureSelfHostedCredentialSecrets");
+ });
+
+ test("persists credential encryption secrets on the data volume", () => {
+ const secrets = readProjectFile("scripts/self-hosted-secrets.mjs");
+ expect(secrets).toContain("edgeever-secrets.json");
+ expect(secrets).not.toContain("edgeever.sqlite");
+ expect(readProjectFile("docs/deploy-docker.md")).toContain("edgeever-secrets.json");
+ expect(readProjectFile("docs/deploy-docker.zh-CN.md")).toContain("edgeever-secrets.json");
+ expect(readProjectFile("docs/self-hosting-architecture.md")).toContain(
+ "NAS/GUI upgrades that drop container environment variables",
+ );
+ expect(readProjectFile("docs/self-hosting-architecture.zh-CN.md")).toContain(
+ "NAS/GUI 升级丢掉容器环境变量",
+ );
});
test("gates official image publishing and release auditing", () => {
diff --git a/scripts/self-hosted-secrets.mjs b/scripts/self-hosted-secrets.mjs
index 4a142c16..1be29f09 100644
--- a/scripts/self-hosted-secrets.mjs
+++ b/scripts/self-hosted-secrets.mjs
@@ -1,4 +1,6 @@
-import { readFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { chmod, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
const FILE_SECRET_NAMES = [
"EDGE_EVER_AUTH_PASSWORD",
@@ -10,6 +12,18 @@ const FILE_SECRET_NAMES = [
"EDGE_EVER_S3_SECRET_ACCESS_KEY",
];
+export const SELF_HOSTED_SECRETS_FILE_NAME = "edgeever-secrets.json";
+const SECRETS_VERSION = 1;
+
+const trimSecret = (value) => {
+ const trimmed = typeof value === "string" ? value.trim() : "";
+ return trimmed || undefined;
+};
+
+export const resolveSelfHostedSecretsPath = (dataDirectory) => (
+ join(dataDirectory, SELF_HOSTED_SECRETS_FILE_NAME)
+);
+
export const loadSelfHostedEnvironment = async (environment = process.env) => {
const resolved = { ...environment };
@@ -27,3 +41,159 @@ export const loadSelfHostedEnvironment = async (environment = process.env) => {
return resolved;
};
+
+export const hasSelfHostedCredentialSeed = (environment) => Boolean(
+ trimSecret(environment.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY)
+ || trimSecret(environment.EDGE_EVER_AUTH_PASSWORD)
+ || trimSecret(environment.EDGE_EVER_AUTH_PASSWORD_HASH),
+);
+
+const corruptSecretsMessage = (filePath) => (
+ `Credential secrets file ${filePath} is corrupt or unsupported. Restore it from a /data backup; do not generate a replacement key.`
+);
+
+const readPersistedSecrets = async (filePath) => {
+ let raw;
+ try {
+ raw = await readFile(filePath, "utf8");
+ } catch (error) {
+ if (error && error.code === "ENOENT") return null;
+ throw error;
+ }
+
+ let parsed;
+ try {
+ parsed = JSON.parse(raw);
+ } catch {
+ throw new Error(corruptSecretsMessage(filePath));
+ }
+
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || parsed.version !== SECRETS_VERSION) {
+ throw new Error(corruptSecretsMessage(filePath));
+ }
+
+ const secrets = {
+ version: SECRETS_VERSION,
+ authPassword: trimSecret(parsed.authPassword),
+ authPasswordHash: trimSecret(parsed.authPasswordHash),
+ credentialsEncryptionKey: trimSecret(parsed.credentialsEncryptionKey),
+ };
+ if (!secrets.authPassword && !secrets.authPasswordHash && !secrets.credentialsEncryptionKey) {
+ throw new Error(corruptSecretsMessage(filePath));
+ }
+ return secrets;
+};
+
+const serializeSecrets = (secrets) => `${JSON.stringify({
+ version: SECRETS_VERSION,
+ ...(secrets.authPassword ? { authPassword: secrets.authPassword } : {}),
+ ...(secrets.authPasswordHash ? { authPasswordHash: secrets.authPasswordHash } : {}),
+ ...(secrets.credentialsEncryptionKey ? { credentialsEncryptionKey: secrets.credentialsEncryptionKey } : {}),
+}, null, 2)}\n`;
+
+const writePersistedSecrets = async (filePath, secrets) => {
+ const temporaryPath = `${filePath}.tmp`;
+ await writeFile(temporaryPath, serializeSecrets(secrets), { encoding: "utf8", mode: 0o600 });
+ await chmod(temporaryPath, 0o600);
+ await rename(temporaryPath, filePath);
+ await chmod(filePath, 0o600);
+};
+
+const fillMissingSecrets = (stored, envSecrets) => {
+ const next = { ...stored };
+ let changed = false;
+ if (!next.authPassword && envSecrets.authPassword) {
+ next.authPassword = envSecrets.authPassword;
+ changed = true;
+ }
+ if (!next.authPasswordHash && envSecrets.authPasswordHash) {
+ next.authPasswordHash = envSecrets.authPasswordHash;
+ changed = true;
+ }
+ if (!next.credentialsEncryptionKey && envSecrets.credentialsEncryptionKey) {
+ next.credentialsEncryptionKey = envSecrets.credentialsEncryptionKey;
+ changed = true;
+ }
+ return { secrets: next, changed };
+};
+
+const applyPersistedSecrets = (environment, stored, envSecrets) => {
+ if (!envSecrets.authPassword && stored.authPassword) {
+ environment.EDGE_EVER_AUTH_PASSWORD = stored.authPassword;
+ }
+ if (!envSecrets.authPasswordHash && stored.authPasswordHash) {
+ environment.EDGE_EVER_AUTH_PASSWORD_HASH = stored.authPasswordHash;
+ }
+ if (!envSecrets.credentialsEncryptionKey && stored.credentialsEncryptionKey) {
+ environment.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY = stored.credentialsEncryptionKey;
+ }
+ if (stored.authPassword && envSecrets.authPassword && stored.authPassword !== envSecrets.authPassword) {
+ environment.EDGE_EVER_AUTH_PASSWORD_FALLBACK = stored.authPassword;
+ }
+ if (
+ stored.credentialsEncryptionKey
+ && envSecrets.credentialsEncryptionKey
+ && stored.credentialsEncryptionKey !== envSecrets.credentialsEncryptionKey
+ ) {
+ environment.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY_PREVIOUS = stored.credentialsEncryptionKey;
+ }
+ return environment;
+};
+
+/**
+ * Persist the self-hosted credential-encryption root on the data volume so NAS
+ * GUI upgrades that drop container environment variables can still encrypt AI
+ * and object-storage secrets. The file lives beside SQLite, never inside it.
+ */
+export const ensureSelfHostedCredentialSecrets = async (
+ dataDirectory,
+ environment,
+ options = {},
+) => {
+ const generateIfMissing = options.generateIfMissing === true;
+ const filePath = resolveSelfHostedSecretsPath(dataDirectory);
+ const envSecrets = {
+ authPassword: trimSecret(environment.EDGE_EVER_AUTH_PASSWORD),
+ authPasswordHash: trimSecret(environment.EDGE_EVER_AUTH_PASSWORD_HASH),
+ credentialsEncryptionKey: trimSecret(environment.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY),
+ };
+ let stored = await readPersistedSecrets(filePath);
+ let persisted = false;
+ let generated = false;
+
+ if (!stored) {
+ stored = {
+ version: SECRETS_VERSION,
+ authPassword: envSecrets.authPassword,
+ authPasswordHash: envSecrets.authPasswordHash,
+ credentialsEncryptionKey: envSecrets.credentialsEncryptionKey,
+ };
+ if (!stored.authPassword && !stored.authPasswordHash && !stored.credentialsEncryptionKey) {
+ if (!generateIfMissing) return environment;
+ stored.credentialsEncryptionKey = randomBytes(32).toString("hex");
+ generated = true;
+ }
+ await writePersistedSecrets(filePath, stored);
+ persisted = true;
+ } else {
+ const merged = fillMissingSecrets(stored, envSecrets);
+ if (merged.changed) {
+ stored = merged.secrets;
+ await writePersistedSecrets(filePath, stored);
+ persisted = true;
+ } else {
+ stored = merged.secrets;
+ }
+ }
+
+ if (generated) {
+ console.info(
+ `[self-hosted] generated a credential encryption secret at ${filePath}. `
+ + "Existing encrypted AI or object-storage credentials cannot be decrypted unless the original authentication secret is restored.",
+ );
+ } else if (persisted) {
+ console.info(`[self-hosted] persisted credential encryption secret to ${filePath}`);
+ }
+
+ return applyPersistedSecrets(environment, stored, envSecrets);
+};
diff --git a/scripts/self-hosted-secrets.test.mjs b/scripts/self-hosted-secrets.test.mjs
new file mode 100644
index 00000000..0ff143bc
--- /dev/null
+++ b/scripts/self-hosted-secrets.test.mjs
@@ -0,0 +1,153 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import {
+ ensureSelfHostedCredentialSecrets,
+ hasSelfHostedCredentialSeed,
+ resolveSelfHostedSecretsPath,
+ SELF_HOSTED_SECRETS_FILE_NAME,
+} from "./self-hosted-secrets.mjs";
+import {
+ decryptAiCredential,
+ resolvePrimaryAiCredentialEncryptionKey,
+} from "../apps/api/src/ai-service.ts";
+import { encryptSecret } from "../apps/api/src/secret-encryption.ts";
+
+const makeDataDirectory = async () => mkdtemp(`${tmpdir()}/edgeever-secrets-`);
+
+describe("self-hosted credential secret persistence", () => {
+ test("names the secrets file beside SQLite, not inside it", () => {
+ expect(SELF_HOSTED_SECRETS_FILE_NAME).toBe("edgeever-secrets.json");
+ expect(resolveSelfHostedSecretsPath("/data")).toBe("/data/edgeever-secrets.json");
+ expect(resolveSelfHostedSecretsPath("/data")).not.toContain("sqlite");
+ });
+
+ test("persists the authentication secret and restores it after env vars disappear", async () => {
+ const dataDirectory = await makeDataDirectory();
+ try {
+ const first = await ensureSelfHostedCredentialSecrets(dataDirectory, {
+ EDGE_EVER_AUTH_PASSWORD: "instance-password",
+ });
+ const originalKey = resolvePrimaryAiCredentialEncryptionKey(first);
+ expect(originalKey).toBe("edgeever:ai-credentials:v1:instance-password");
+ expect(hasSelfHostedCredentialSeed(first)).toBe(true);
+
+ const stored = JSON.parse(await readFile(resolveSelfHostedSecretsPath(dataDirectory), "utf8"));
+ expect(stored).toEqual({
+ version: 1,
+ authPassword: "instance-password",
+ });
+ if (process.platform !== "win32") {
+ expect((await stat(resolveSelfHostedSecretsPath(dataDirectory))).mode & 0o777).toBe(0o600);
+ }
+
+ const restored = await ensureSelfHostedCredentialSecrets(dataDirectory, {});
+ expect(restored.EDGE_EVER_AUTH_PASSWORD).toBe("instance-password");
+ expect(resolvePrimaryAiCredentialEncryptionKey(restored)).toBe(originalKey);
+
+ const encrypted = await encryptSecret("provider-key", originalKey);
+ await expect(decryptAiCredential(encrypted, restored)).resolves.toBe("provider-key");
+ } finally {
+ await rm(dataDirectory, { recursive: true, force: true });
+ }
+ });
+
+ test("does not write a secrets file before the instance can start", async () => {
+ const dataDirectory = await makeDataDirectory();
+ try {
+ const environment = await ensureSelfHostedCredentialSecrets(dataDirectory, {});
+ expect(hasSelfHostedCredentialSeed(environment)).toBe(false);
+ await expect(readFile(resolveSelfHostedSecretsPath(dataDirectory), "utf8")).rejects.toMatchObject({
+ code: "ENOENT",
+ });
+ } finally {
+ await rm(dataDirectory, { recursive: true, force: true });
+ }
+ });
+
+ test("generates a dedicated credentials key when a running instance has no secret", async () => {
+ const dataDirectory = await makeDataDirectory();
+ try {
+ const environment = await ensureSelfHostedCredentialSecrets(dataDirectory, {}, { generateIfMissing: true });
+ expect(environment.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY).toMatch(/^[a-f0-9]{64}$/);
+ expect(resolvePrimaryAiCredentialEncryptionKey(environment)).toBe(
+ `edgeever:ai-credentials:v1:${environment.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY}`,
+ );
+
+ const second = await ensureSelfHostedCredentialSecrets(dataDirectory, {}, { generateIfMissing: true });
+ expect(second.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY).toBe(environment.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY);
+ } finally {
+ await rm(dataDirectory, { recursive: true, force: true });
+ }
+ });
+
+ test("keeps the original secret for decryption when environment values change", async () => {
+ const dataDirectory = await makeDataDirectory();
+ try {
+ await ensureSelfHostedCredentialSecrets(dataDirectory, {
+ EDGE_EVER_AUTH_PASSWORD: "original-password",
+ });
+ const rotated = await ensureSelfHostedCredentialSecrets(dataDirectory, {
+ EDGE_EVER_AUTH_PASSWORD: "rotated-password",
+ });
+ expect(rotated.EDGE_EVER_AUTH_PASSWORD).toBe("rotated-password");
+ expect(rotated.EDGE_EVER_AUTH_PASSWORD_FALLBACK).toBe("original-password");
+
+ const encrypted = await encryptSecret(
+ "provider-key",
+ resolvePrimaryAiCredentialEncryptionKey({ EDGE_EVER_AUTH_PASSWORD: "original-password" }),
+ );
+ await expect(decryptAiCredential(encrypted, rotated)).resolves.toBe("provider-key");
+ } finally {
+ await rm(dataDirectory, { recursive: true, force: true });
+ }
+ });
+
+ test("keeps a previous credentials key in the decrypt ring after rotation", async () => {
+ const dataDirectory = await makeDataDirectory();
+ try {
+ await ensureSelfHostedCredentialSecrets(dataDirectory, {
+ EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY: "original-credentials-key",
+ });
+ const rotated = await ensureSelfHostedCredentialSecrets(dataDirectory, {
+ EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY: "rotated-credentials-key",
+ });
+ expect(rotated.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY).toBe("rotated-credentials-key");
+ expect(rotated.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY_PREVIOUS).toBe("original-credentials-key");
+
+ const encrypted = await encryptSecret(
+ "provider-key",
+ resolvePrimaryAiCredentialEncryptionKey({
+ EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY: "original-credentials-key",
+ }),
+ );
+ await expect(decryptAiCredential(encrypted, rotated)).resolves.toBe("provider-key");
+ } finally {
+ await rm(dataDirectory, { recursive: true, force: true });
+ }
+ });
+
+ test("refuses to replace a corrupt secrets file with a new key", async () => {
+ const dataDirectory = await makeDataDirectory();
+ try {
+ await writeFile(resolveSelfHostedSecretsPath(dataDirectory), "{not-json", "utf8");
+ await expect(ensureSelfHostedCredentialSecrets(dataDirectory, {
+ EDGE_EVER_AUTH_PASSWORD: "instance-password",
+ }, { generateIfMissing: true })).rejects.toThrow(/do not generate a replacement key/);
+ } finally {
+ await rm(dataDirectory, { recursive: true, force: true });
+ }
+ });
+
+ test("refuses an empty secrets file even if a new environment secret is present", async () => {
+ const dataDirectory = await makeDataDirectory();
+ try {
+ await writeFile(resolveSelfHostedSecretsPath(dataDirectory), `${JSON.stringify({ version: 1 })}\n`, "utf8");
+ await expect(ensureSelfHostedCredentialSecrets(dataDirectory, {
+ EDGE_EVER_AUTH_PASSWORD: "instance-password",
+ })).rejects.toThrow(/do not generate a replacement key/);
+ } finally {
+ await rm(dataDirectory, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/scripts/self-hosted-server.mjs b/scripts/self-hosted-server.mjs
index 31409143..084e2b32 100644
--- a/scripts/self-hosted-server.mjs
+++ b/scripts/self-hosted-server.mjs
@@ -8,7 +8,7 @@ import { fetchEdgeEverApp } from "../apps/api/src/index.ts";
import { nodePublicFetch } from "../apps/api/src/node-public-network.ts";
import { createSelfHostedStorageAdapter } from "../apps/api/src/self-hosted-storage-adapter.ts";
import { resolveSelfHostedConfig } from "./self-hosted-config.mjs";
-import { loadSelfHostedEnvironment } from "./self-hosted-secrets.mjs";
+import { ensureSelfHostedCredentialSecrets, loadSelfHostedEnvironment } from "./self-hosted-secrets.mjs";
const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
const runtimeEnvironment = await loadSelfHostedEnvironment(process.env);
@@ -17,6 +17,7 @@ const { dataDirectory, databaseFile, resourcesDirectory, webDirectory } = config
await mkdir(dataDirectory, { recursive: true });
await mkdir(resourcesDirectory, { recursive: true });
+await ensureSelfHostedCredentialSecrets(dataDirectory, runtimeEnvironment);
const sqlite = new Database(databaseFile, { create: true });
sqlite.exec("PRAGMA foreign_keys = ON; PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL; PRAGMA busy_timeout = 5000;");
@@ -61,6 +62,8 @@ if (
);
}
+await ensureSelfHostedCredentialSecrets(dataDirectory, runtimeEnvironment, { generateIfMissing: true });
+
const storage = config.storageBackend === "s3"
? (
await import("../apps/api/src/s3-compatible-storage-adapter.ts")
@@ -85,6 +88,7 @@ const env = {
EDGE_EVER_DEPLOYMENT_METHOD: runtimeEnvironment.EDGE_EVER_DEPLOYMENT_METHOD,
EDGE_EVER_AUTH_PASSWORD: runtimeEnvironment.EDGE_EVER_AUTH_PASSWORD,
EDGE_EVER_AUTH_PASSWORD_HASH: runtimeEnvironment.EDGE_EVER_AUTH_PASSWORD_HASH,
+ EDGE_EVER_AUTH_PASSWORD_FALLBACK: runtimeEnvironment.EDGE_EVER_AUTH_PASSWORD_FALLBACK,
EDGE_EVER_SESSION_TTL_DAYS: runtimeEnvironment.EDGE_EVER_SESSION_TTL_DAYS ?? "400",
EDGE_EVER_AUTH_LOGIN_WINDOW_SECONDS: runtimeEnvironment.EDGE_EVER_AUTH_LOGIN_WINDOW_SECONDS,
EDGE_EVER_AUTH_LOGIN_USERNAME_MAX_ATTEMPTS: runtimeEnvironment.EDGE_EVER_AUTH_LOGIN_USERNAME_MAX_ATTEMPTS,
@@ -94,6 +98,7 @@ const env = {
// Legacy decryption fallback for credentials saved by older releases.
EDGE_EVER_STORAGE_ENCRYPTION_KEY: runtimeEnvironment.EDGE_EVER_STORAGE_ENCRYPTION_KEY,
EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY: runtimeEnvironment.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY,
+ EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY_PREVIOUS: runtimeEnvironment.EDGE_EVER_CREDENTIALS_ENCRYPTION_KEY_PREVIOUS,
EDGE_EVER_DEMO_MODE: runtimeEnvironment.EDGE_EVER_DEMO_MODE,
EDGE_EVER_ALLOW_UNAUTHENTICATED: runtimeEnvironment.EDGE_EVER_ALLOW_UNAUTHENTICATED,
};