refactor: simplify encryption key management and remove V1/V2 version distinction

- Make secretPepper configurable via ROOT_SECRET_PEPPER env var
- Derive HKDF salt/info dynamically from pepper instead of hardcoding
- Remove KeyVersion field from Project model (Go GORM + Python SQLAlchemy)
- Merge DeriveMasterKeyWrappingKey into single DeriveUserKEK function
- Rename ParseTokenV2 to ParseProjectToken, remove Version field
- Consolidate ResetSecretKey + RotateSecretKey(V2) into single RotateSecretKey
- Split key rotation into JWT admin route (non-encrypted only) and Bearer route
- Remove extractMasterKey, OldAPIKey param, GetParsedToken from admin handler
- Update Dashboard to route rotation based on encryption_enabled status
- Remove legacy key_version checks from Dashboard settings page
- Update E2E tests and unit tests to match simplified model

Author: GenerQAQ

dashboard/app/project/[id]/api-keys/actions.ts

@@ -59,7 +59,7 @@ export async function getSecretKeyHistory(projectId: string) {
  * Rotate (generate new) secret key for a project
  * Returns the full key for one-time display
  */
-export async function rotateSecretKey(projectId: string, oldApiKey?: string) {
+export async function rotateSecretKey(projectId: string, encryptionEnabled: boolean, apiKey?: string) {
   // Get current user (will redirect if not authenticated)
   const user = await getCurrentUser();
 
@@ -86,8 +86,21 @@ export async function rotateSecretKey(projectId: string, oldApiKey?: string) {
 
   try {
     // Call API to generate new secret key
+    // Encrypted projects must use Bearer route to preserve master key
+    // Non-encrypted projects can use either route
     const client = new AcontextClient();
-    const fullSecretKey = await client.updateProjectSecretKey(projectId, oldApiKey);
+    let fullSecretKey: string;
+    if (encryptionEnabled) {
+      if (!apiKey) {
+        return { error: "Encrypted projects require a saved API key to rotate. Please save your API key first." };
+      }
+      fullSecretKey = await client.rotateProjectSecretKey(apiKey);
+    } else if (apiKey) {
+      // Prefer Bearer route when API key is available (preserves master key)
+      fullSecretKey = await client.rotateProjectSecretKey(apiKey);
+    } else {
+      fullSecretKey = await client.rotateProjectSecretKeyAdmin(projectId);
+    }
 
     if (!fullSecretKey) {
       return { error: "Failed to generate secret key" };

dashboard/app/project/[id]/api-keys/api-keys-page-client.tsx

@@ -164,8 +164,11 @@ console.log(await client.ping());`,
 
   const performKeyGeneration = () => {
     startTransition(async () => {
-      // Pass the saved API key so the server can preserve the master key (V2 rotation)
-      const result = await rotateSecretKey(project.id, savedApiKey ?? undefined);
+      const result = await rotateSecretKey(
+        project.id,
+        project.encryption_enabled ?? false,
+        savedApiKey ?? undefined,
+      );
       if (result.error) {
         toast.error(result.error);
       } else if (result.secretKey) {

dashboard/app/project/[id]/settings/general/general-page-client.tsx

@@ -461,13 +461,6 @@ export function GeneralPageClient({
                               );
                               return;
                             }
-                            if (checked && (project.key_version ?? 1) < 2) {
-                              toast.error(
-                                "Your API key uses a legacy format. Please rotate your API key first to upgrade it, then enable encryption.",
-                                { duration: 7000 }
-                              );
-                              return;
-                            }
                             if (checked) {
                               setShowEncryptDialog(true);
                             } else {
@@ -495,23 +488,6 @@ export function GeneralPageClient({
                       </Alert>
                     )}
 
-                    {!encryptionEnabled && (project.key_version ?? 1) < 2 && (
-                      <Alert>
-                        <AlertTriangle className="h-4 w-4" />
-                        <AlertDescription>
-                          Your API key uses a legacy format that does not support encryption.
-                          Please{" "}
-                          <a
-                            href={`/project/${encodeId(project.id)}/api-keys`}
-                            className="font-medium underline underline-offset-4"
-                          >
-                            rotate your API key
-                          </a>{" "}
-                          to upgrade to the new format before enabling encryption.
-                        </AlertDescription>
-                      </Alert>
-                    )}
-
                     {encryptionEnabled && (
                       <Alert>
                         <Shield className="h-4 w-4" />

dashboard/lib/acontext/operations/admin.ts

@@ -133,20 +133,33 @@ export function AdminOperations<T extends Constructor<BaseClient>>(Base: T) {
     }
 
     /**
-     * Update/rotate project secret key via acontext API.
-     * If oldApiKey is provided, the master key is preserved (V2 rotation).
+     * Rotate project secret key via admin JWT route (no master key preservation).
+     * Only works for non-encrypted projects.
      * Returns the new secret key.
      */
-    async updateProjectSecretKey(projectId: string, oldApiKey?: string): Promise<string> {
-      const body = oldApiKey ? { old_api_key: oldApiKey } : undefined;
+    async rotateProjectSecretKeyAdmin(projectId: string): Promise<string> {
       const result = await this.request<{ secret_key?: string; secretKey?: string }>(
         `/admin/v1/project/${projectId}/secret_key`,
         {
           method: "PUT",
-          ...(body && {
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(body),
-          }),
+        }
+      );
+      return result.secret_key || result.secretKey || "";
+    }
+
+    /**
+     * Rotate project secret key via Bearer project auth route.
+     * Preserves the master key (required for encrypted projects).
+     * Returns the new secret key.
+     */
+    async rotateProjectSecretKey(apiKey: string): Promise<string> {
+      const result = await this.request<{ secret_key?: string; secretKey?: string }>(
+        `/admin/v1/project/secret_key`,
+        {
+          method: "PUT",
+          headers: {
+            "Authorization": `Bearer ${apiKey}`,
+          },
         }
       );
       return result.secret_key || result.secretKey || "";

dashboard/types/index.ts

@@ -25,7 +25,6 @@ export interface Project {
   name: string
   organization_id: string
   encryption_enabled?: boolean
-  key_version?: number
   created_at?: string
 }
 

src/server/api/go/configs/config.admin.yaml

@@ -7,7 +7,7 @@ app:
 
 root:
   apiBearerToken: "${ROOT_API_BEARER_TOKEN}"
-  secretPepper: "your-secret-pepper"
+  secretPepper: "${ROOT_SECRET_PEPPER}"
   enableArgon2Verification: ${ENABLE_ARGON2_VERIFICATION}
 
 log:

src/server/api/go/configs/config.yaml

@@ -7,7 +7,7 @@ app:
 
 root:
   apiBearerToken: "${ROOT_API_BEARER_TOKEN}"
-  secretPepper: "your-secret-pepper"
+  secretPepper: "${ROOT_SECRET_PEPPER}"
   enableArgon2Verification: ${ENABLE_ARGON2_VERIFICATION}
 
 log:

src/server/api/go/internal/config/config.go

@@ -123,6 +123,7 @@ func setDefaults(v *viper.Viper) {
 	v.SetDefault("app.externalurl", "")
 	v.SetDefault("root.apiBearerToken", "your-root-api-bearer-token")
 	v.SetDefault("root.projectBearerTokenPrefix", "sk-ac-")
+	v.SetDefault("root.secretPepper", "your-secret-pepper")
 	v.SetDefault("root.enableArgon2Verification", true)
 	v.SetDefault("database.dsn", "host=127.0.0.1 user=acontext password=helloworld dbname=acontext port=15432 sslmode=disable TimeZone=UTC")
 	v.SetDefault("database.enableTLS", false)

src/server/api/go/internal/infra/crypto/envelope_test.go

@@ -283,35 +283,25 @@ func TestMetadataFromMap_NoEncryption(t *testing.T) {
 	}
 }
 
-func TestDeriveMasterKeyWrappingKey_Deterministic(t *testing.T) {
-	k1, err := DeriveMasterKeyWrappingKey("auth-secret", "pepper")
+func TestDeriveUserKEK_Deterministic(t *testing.T) {
+	k1, err := DeriveUserKEK("auth-secret", "pepper")
 	if err != nil {
 		t.Fatal(err)
 	}
-	k2, err := DeriveMasterKeyWrappingKey("auth-secret", "pepper")
+	k2, err := DeriveUserKEK("auth-secret", "pepper")
 	if err != nil {
 		t.Fatal(err)
 	}
 	if !bytes.Equal(k1, k2) {
-		t.Fatal("DeriveMasterKeyWrappingKey should be deterministic")
+		t.Fatal("DeriveUserKEK should be deterministic")
 	}
 	if len(k1) != KeySize {
 		t.Fatalf("expected key size %d, got %d", KeySize, len(k1))
 	}
 }
 
-func TestDeriveMasterKeyWrappingKey_DifferentFromUserKEK(t *testing.T) {
-	// Wrapping key should differ from user KEK even with same inputs
-	// (different domain separation)
-	wk, _ := DeriveMasterKeyWrappingKey("secret", "pepper")
-	uk, _ := DeriveUserKEK("secret", "pepper")
-	if bytes.Equal(wk, uk) {
-		t.Fatal("wrapping key and user KEK should differ (different HKDF domain)")
-	}
-}
-
 func TestWrapUnwrapMasterKey(t *testing.T) {
-	wk, _ := DeriveMasterKeyWrappingKey("auth-secret", "pepper")
+	wk, _ := DeriveUserKEK("auth-secret", "pepper")
 	mk, err := GenerateMasterKey()
 	if err != nil {
 		t.Fatal(err)
@@ -335,8 +325,8 @@ func TestWrapUnwrapMasterKey(t *testing.T) {
 }
 
 func TestUnwrapMasterKey_WrongWrappingKey(t *testing.T) {
-	wk1, _ := DeriveMasterKeyWrappingKey("auth1", "pepper")
-	wk2, _ := DeriveMasterKeyWrappingKey("auth2", "pepper")
+	wk1, _ := DeriveUserKEK("auth1", "pepper")
+	wk2, _ := DeriveUserKEK("auth2", "pepper")
 	mk, _ := GenerateMasterKey()
 
 	encB64, _ := WrapMasterKey(wk1, mk)
@@ -376,8 +366,8 @@ func TestMasterKeyRewrapPreservesDecryption(t *testing.T) {
 	ciphertext, meta, _ := EncryptData(mk, plaintext)
 
 	// Re-wrap master_key with new auth_secret (simulating rotation)
-	oldWK, _ := DeriveMasterKeyWrappingKey("old-auth", "pepper")
-	newWK, _ := DeriveMasterKeyWrappingKey("new-auth", "pepper")
+	oldWK, _ := DeriveUserKEK("old-auth", "pepper")
+	newWK, _ := DeriveUserKEK("new-auth", "pepper")
 
 	encB64, _ := WrapMasterKey(oldWK, mk)
 	unwrapped, _ := UnwrapMasterKey(oldWK, encB64)

src/server/api/go/internal/infra/crypto/service.go

@@ -6,25 +6,13 @@ import (
 	"fmt"
 )
 
-var (
-	userKEKSalt = []byte("acontext-user-kek")
-	userKEKInfo = []byte("acontext envelope encryption user KEK")
-
-	masterKeyWrapSalt = []byte("acontext-master-key-wrap")
-	masterKeyWrapInfo = []byte("acontext master key wrapping")
-)
-
-// DeriveUserKEK derives a user KEK from the raw API key and pepper.
-func DeriveUserKEK(apiKeyRaw, pepper string) ([]byte, error) {
-	secret := []byte(apiKeyRaw + pepper)
-	return DeriveKEK(secret, userKEKSalt, userKEKInfo)
-}
-
-// DeriveMasterKeyWrappingKey derives a wrapping key from the auth secret and pepper.
-// This key is used to encrypt/decrypt the master key embedded in V2 API tokens.
-func DeriveMasterKeyWrappingKey(authSecret, pepper string) ([]byte, error) {
+// DeriveUserKEK derives a wrapping key from the auth secret and pepper.
+// This key is used to encrypt/decrypt the master key embedded in API tokens.
+func DeriveUserKEK(authSecret, pepper string) ([]byte, error) {
 	secret := []byte(authSecret + pepper)
-	return DeriveKEK(secret, masterKeyWrapSalt, masterKeyWrapInfo)
+	salt := []byte(pepper + "-master-key-wrap")
+	info := []byte(pepper + " master key wrapping")
+	return DeriveKEK(secret, salt, info)
 }
 
 // WrapMasterKey encrypts a 32-byte master key with a wrapping key derived from auth_secret.