fix(dashboard,api): improve encryption error handling for legacy API keys (#513)

GenerQAQ · web-flow · commit e20c0ce90a5b · 2026-03-30T17:25:47.000+08:00
Legacy API keys lack embedded master keys and cannot derive KEK for
encryption. The API returned a generic "parameter error" with no
guidance, and the Dashboard had no client-side validation.

- API: return descriptive error messages instead of generic "parameter error"
- Dashboard: detect legacy vs compact keys using configurable prefix
- Dashboard: show warning banner and disable toggle for legacy keys
- Dashboard: validate API key prefix on save
- Dashboard: add eye toggle and autoComplete=off on API key input
diff --git a/dashboard/app/project/[id]/api-keys/api-keys-page-client.tsx b/dashboard/app/project/[id]/api-keys/api-keys-page-client.tsx
@@ -59,7 +59,7 @@ import {
 import { rotateSecretKey } from "./actions";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { CodeEditor } from "@/components/code-editor";
-import { useApiKeyStorage } from "@/lib/hooks/use-api-key-storage";
+import { useApiKeyStorage, hasValidApiKeyPrefix } from "@/lib/hooks/use-api-key-storage";
 
 const SERVICE_URL = "api.acontext.app/api/v1";
 
@@ -70,6 +70,7 @@ interface ApiKeysPageClientProps {
   projects: Project[];
   keyRotations: SecretKeyRotation[];
   role: "owner" | "member";
+  apiKeyPrefix: string;
 }
 
 export function ApiKeysPageClient({
@@ -79,6 +80,7 @@ export function ApiKeysPageClient({
   projects,
   keyRotations,
   role,
+  apiKeyPrefix,
 }: ApiKeysPageClientProps) {
   const { initialize, setHasSidebar } = useTopNavStore();
   const router = useRouter();
@@ -95,9 +97,10 @@ export function ApiKeysPageClient({
   );
 
   // Saved API key in localStorage
-  const { apiKey: savedApiKey, hasApiKey: hasSavedApiKey, saveApiKey, removeApiKey } = useApiKeyStorage(project.id);
+  const { apiKey: savedApiKey, hasApiKey: hasSavedApiKey, saveApiKey, removeApiKey } = useApiKeyStorage(project.id, apiKeyPrefix);
   const [apiKeyInput, setApiKeyInput] = useState("");
   const [showSavedKey, setShowSavedKey] = useState(false);
+  const [showApiKeyInput, setShowApiKeyInput] = useState(false);
 
   const isOwner = role === "owner";
   const hasExistingKey = keyRotations.length > 0;
@@ -519,21 +522,43 @@ IMPORTANT: Store this key securely. It will not be shown again.
                   <div className="space-y-2">
                     <Label htmlFor="api-key-input">API Key</Label>
                     <div className="flex items-center gap-2">
-                      <Input
-                        id="api-key-input"
-                        type="password"
-                        value={apiKeyInput}
-                        onChange={(e) => setApiKeyInput(e.target.value)}
-                        placeholder="Paste your API key here"
-                        className="font-mono text-sm"
-                      />
+                      <div className="relative flex-1">
+                        <Input
+                          id="api-key-input"
+                          type={showApiKeyInput ? "text" : "password"}
+                          value={apiKeyInput}
+                          onChange={(e) => setApiKeyInput(e.target.value)}
+                          placeholder="Paste your API key here"
+                          className="font-mono text-sm pr-10"
+                          autoComplete="off"
+                        />
+                        <Button
+                          variant="ghost"
+                          size="icon"
+                          className="absolute right-1 top-1/2 -translate-y-1/2 h-7 w-7"
+                          onClick={() => setShowApiKeyInput(!showApiKeyInput)}
+                          title={showApiKeyInput ? "Hide API key" : "Show API key"}
+                          type="button"
+                        >
+                          {showApiKeyInput ? (
+                            <EyeOff className="h-4 w-4" />
+                          ) : (
+                            <Eye className="h-4 w-4" />
+                          )}
+                        </Button>
+                      </div>
                       <Button
                         onClick={() => {
-                          if (apiKeyInput.trim()) {
-                            saveApiKey(apiKeyInput.trim());
-                            setApiKeyInput("");
-                            toast.success("API key saved to browser");
+                          const trimmed = apiKeyInput.trim();
+                          if (!trimmed) return;
+                          if (!hasValidApiKeyPrefix(trimmed, apiKeyPrefix)) {
+                            toast.error(`Invalid API key format. API key must start with "${apiKeyPrefix}".`);
+                            return;
                           }
+                          saveApiKey(trimmed);
+                          setApiKeyInput("");
+                          setShowApiKeyInput(false);
+                          toast.success("API key saved to browser");
                         }}
                         disabled={!apiKeyInput.trim()}
                       >
diff --git a/dashboard/app/project/[id]/api-keys/page.tsx b/dashboard/app/project/[id]/api-keys/page.tsx
@@ -7,6 +7,7 @@ import {
   getSecretKeyRotations,
 } from "@/lib/supabase";
 import { decodeId } from "@/lib/id-codec";
+import { getProjectApiKeyPrefix } from "@/lib/acontext/server";
 
 interface PageProps {
   params: Promise<{
@@ -70,6 +71,7 @@ export default async function ApiKeysPage({ params }: PageProps) {
       projects={projects}
       keyRotations={keyRotations}
       role={currentOrganization.role ?? "member"}
+      apiKeyPrefix={getProjectApiKeyPrefix()}
     />
   );
 }
diff --git a/dashboard/app/project/[id]/settings/encryption/encryption-page-client.tsx b/dashboard/app/project/[id]/settings/encryption/encryption-page-client.tsx
@@ -3,7 +3,7 @@
 import { useEffect, useState, useTransition } from "react";
 import { useRouter } from "next/navigation";
 import { encodeId } from "@/lib/id-codec";
-import { AlertTriangle, Lock, Loader2, Shield } from "lucide-react";
+import { AlertTriangle, KeyRound, Lock, Loader2, Shield } from "lucide-react";
 import { toast } from "sonner";
 import { useTopNavStore } from "@/stores/top-nav";
 import { Organization, Project } from "@/types";
@@ -36,6 +36,7 @@ interface EncryptionPageClientProps {
   allOrganizations: Organization[];
   projects: Project[];
   role: "owner" | "member";
+  apiKeyPrefix: string;
 }
 
 export function EncryptionPageClient({
@@ -44,6 +45,7 @@ export function EncryptionPageClient({
   allOrganizations,
   projects,
   role,
+  apiKeyPrefix,
 }: EncryptionPageClientProps) {
   const { initialize, setHasSidebar } = useTopNavStore();
   const router = useRouter();
@@ -54,7 +56,7 @@ export function EncryptionPageClient({
   const [showEncryptDialog, setShowEncryptDialog] = useState(false);
   const [showDecryptDialog, setShowDecryptDialog] = useState(false);
   const [isEncryptionPending, startEncryptionTransition] = useTransition();
-  const { hasApiKey, apiKey } = useApiKeyStorage(project.id);
+  const { hasApiKey, apiKey, isCompactKey } = useApiKeyStorage(project.id, apiKeyPrefix);
 
   useEffect(() => {
     initialize({
@@ -119,13 +121,20 @@ export function EncryptionPageClient({
                       );
                       return;
                     }
+                    if (!isCompactKey) {
+                      toast.error(
+                        "Your API key is in legacy format and does not support encryption. Please rotate your API key on the API Keys page to get a new key that supports encryption.",
+                        { duration: 8000 }
+                      );
+                      return;
+                    }
                     if (checked) {
                       setShowEncryptDialog(true);
                     } else {
                       setShowDecryptDialog(true);
                     }
                   }}
-                  disabled={isEncryptionPending || !isOwner}
+                  disabled={isEncryptionPending || !isOwner || (hasApiKey && !isCompactKey)}
                 />
               </div>
             </div>
@@ -146,6 +155,23 @@ export function EncryptionPageClient({
               </Alert>
             )}
 
+            {hasApiKey && !isCompactKey && (
+              <Alert variant="destructive">
+                <KeyRound className="h-4 w-4" />
+                <AlertDescription>
+                  Your saved API key is in legacy format and does not support encryption.
+                  Please go to the{" "}
+                  <a
+                    href={`/project/${encodeId(project.id)}/api-keys`}
+                    className="font-medium underline underline-offset-4"
+                  >
+                    API Keys page
+                  </a>{" "}
+                  and rotate your API key to get a new key that supports encryption.
+                </AlertDescription>
+              </Alert>
+            )}
+
             {encryptionEnabled && (
               <Alert>
                 <Shield className="h-4 w-4" />
diff --git a/dashboard/app/project/[id]/settings/encryption/page.tsx b/dashboard/app/project/[id]/settings/encryption/page.tsx
@@ -6,6 +6,7 @@ import {
   getOrganizationDataWithPlan,
 } from "@/lib/supabase";
 import { decodeId } from "@/lib/id-codec";
+import { getProjectApiKeyPrefix } from "@/lib/acontext/server";
 
 interface PageProps {
   params: Promise<{
@@ -60,6 +61,7 @@ export default async function EncryptionPage({ params }: PageProps) {
       allOrganizations={allOrganizations}
       projects={projects}
       role={currentOrganization.role ?? "member"}
+      apiKeyPrefix={getProjectApiKeyPrefix()}
     />
   );
 }
diff --git a/dashboard/lib/acontext/server.ts b/dashboard/lib/acontext/server.ts
@@ -23,6 +23,14 @@ export * from "./operations";
 const ACONTEXT_API_BASE_URL =
   process.env.ACONTEXT_API_BASE_URL ?? "https://admin.acontext.app";
 
+/**
+ * Get the project API key prefix from environment.
+ * Use this to pass the prefix to client components that need to validate API key format.
+ */
+export function getProjectApiKeyPrefix(): string {
+  return process.env.ACONTEXT_PROJECT_BEARER_TOKEN_PREFIX || "sk-ac-";
+}
+
 /**
  * Base Acontext API Client class
  * Contains core infrastructure: authentication, request handling, and utilities
diff --git a/dashboard/lib/hooks/use-api-key-storage.ts b/dashboard/lib/hooks/use-api-key-storage.ts
@@ -2,8 +2,26 @@
 import { useState, useCallback } from "react";
 
 const STORAGE_KEY_PREFIX = "acontext_api_key_";
+// Compact format body: base64url(0x01 | auth_16B | aes_kw_40B) = 76 chars
+const COMPACT_BODY_LENGTH = 76;
 
-export function useApiKeyStorage(projectId: string) {
+/**
+ * Check if an API key has a valid prefix.
+ */
+export function hasValidApiKeyPrefix(key: string, prefix: string): boolean {
+  return key.startsWith(prefix);
+}
+
+/**
+ * Check if an API key is in compact format (supports encryption).
+ * Compact keys: prefix + 76-char base64url body.
+ * Legacy keys have a different body length and do not support encryption.
+ */
+export function isCompactApiKey(key: string, prefix: string): boolean {
+  return hasValidApiKeyPrefix(key, prefix) && key.length === prefix.length + COMPACT_BODY_LENGTH;
+}
+
+export function useApiKeyStorage(projectId: string, apiKeyPrefix: string) {
   const storageKey = `${STORAGE_KEY_PREFIX}${projectId}`;
 
   const [apiKey, setApiKeyState] = useState<string | null>(() => {
@@ -24,9 +42,13 @@ export function useApiKeyStorage(projectId: string) {
     setApiKeyState(null);
   }, [storageKey]);
 
+  const hasApiKey = apiKey !== null && apiKey !== "";
+
   return {
     apiKey,
-    hasApiKey: apiKey !== null && apiKey !== "",
+    hasApiKey,
+    hasValidPrefix: hasApiKey && hasValidApiKeyPrefix(apiKey!, apiKeyPrefix),
+    isCompactKey: hasApiKey && isCompactApiKey(apiKey!, apiKeyPrefix),
     saveApiKey,
     removeApiKey,
   };
diff --git a/src/server/api/go/internal/modules/handler/encryption.go b/src/server/api/go/internal/modules/handler/encryption.go
@@ -20,13 +20,13 @@ import (
 func encryptProject(c *gin.Context, db *gorm.DB, rdb *redis.Client, s3 *blob.S3Deps, assetRefRepo repo.AssetReferenceRepo) {
 	project, ok := c.MustGet("project").(*model.Project)
 	if !ok {
-		c.JSON(http.StatusBadRequest, serializer.ParamErr("", fmt.Errorf("project not found")))
+		c.JSON(http.StatusBadRequest, serializer.ParamErr("project not found", fmt.Errorf("project not found")))
 		return
 	}
 
 	userKEK := middleware.GetUserKEK(c)
 	if userKEK == nil {
-		c.JSON(http.StatusBadRequest, serializer.ParamErr("", fmt.Errorf("API key required to derive encryption key")))
+		c.JSON(http.StatusBadRequest, serializer.ParamErr("compact API key required to derive encryption key; rotate your API key to enable encryption", nil))
 		return
 	}
 
@@ -73,13 +73,13 @@ func encryptProject(c *gin.Context, db *gorm.DB, rdb *redis.Client, s3 *blob.S3D
 func decryptProject(c *gin.Context, db *gorm.DB, rdb *redis.Client, s3 *blob.S3Deps, assetRefRepo repo.AssetReferenceRepo) {
 	project, ok := c.MustGet("project").(*model.Project)
 	if !ok {
-		c.JSON(http.StatusBadRequest, serializer.ParamErr("", fmt.Errorf("project not found")))
+		c.JSON(http.StatusBadRequest, serializer.ParamErr("project not found", fmt.Errorf("project not found")))
 		return
 	}
 
 	userKEK := middleware.GetUserKEK(c)
 	if userKEK == nil {
-		c.JSON(http.StatusBadRequest, serializer.ParamErr("", fmt.Errorf("API key required to derive encryption key")))
+		c.JSON(http.StatusBadRequest, serializer.ParamErr("compact API key required to derive encryption key; rotate your API key to disable encryption", nil))
 		return
 	}
 
