refactor: enhance key rotation and secure storage hooks with eager re-encryption support

Author: mCodex

example/src/components/KeyRotationPanel.tsx

@@ -32,7 +32,7 @@ const KeyRotationPanel: React.FC<KeyRotationPanelProps> = ({ service }) => {
 	}, [refreshVersion, rotate])
 
 	const handleRotateEager = useCallback(async () => {
-		const ack = await rotate()
+		const ack = await rotate({ reEncryptEagerly: true })
 		if (ack.success) {
 			await refreshVersion()
 		}

ios/HybridSensitiveInfo.swift

@@ -59,7 +59,7 @@ public final class HybridSensitiveInfo: HybridSensitiveInfoSpec {
       var valueData = Data(request.value.utf8)
       defer { zeroize(&valueData) }
 
-      let tag = (try? integrity.sign(
+      let tag = try integrity.sign(
         integrityInput(
           service: service,
           account: request.key,
@@ -69,7 +69,7 @@ public final class HybridSensitiveInfo: HybridSensitiveInfoSpec {
           timestamp: timestamp,
           value: valueData
         )
-      ))
+      )
 
       let metadata = buildMetadata(
         securityLevel: resolved.securityLevel,
@@ -104,7 +104,7 @@ public final class HybridSensitiveInfo: HybridSensitiveInfoSpec {
       }
 
       if status == errSecParam, resolved.accessControlRef != nil {
-        let fallbackTag = (try? integrity.sign(
+        let fallbackTag = try integrity.sign(
           integrityInput(
             service: service,
             account: request.key,
@@ -114,7 +114,7 @@ public final class HybridSensitiveInfo: HybridSensitiveInfoSpec {
             timestamp: timestamp,
             value: valueData
           )
-        ))
+        )
         let fallbackMetadata = buildMetadata(
           securityLevel: .software,
           accessControl: .none,

ios/Internal/Security/MetadataIntegrity.swift

@@ -28,7 +28,7 @@ struct MetadataIntegrity {
   }
 
   /// Process-local cache so we don't pay a Keychain round-trip on every read. Guarded by a
-  /// recursive lock — first-touch creation is rare, but reads are on the hot path.
+  /// non-recursive lock — first-touch creation is rare, callers must not re-enter `getOrCreateKey`.
   private static let cacheLock = NSLock()
   private static var keyCache: [String: SymmetricKey] = [:]
 
@@ -121,10 +121,23 @@ struct MetadataIntegrity {
     addAttributes[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
     addAttributes[kSecValueData as String] = rawKey
     let addStatus = SecItemAdd(addAttributes as CFDictionary, nil)
+
+    if addStatus == errSecDuplicateItem {
+      // Cross-process race: another writer added the key between our lookup and add.
+      // Re-fetch the canonical stored key so HMACs stay consistent across producers.
+      zeroize(&rawKey)
+      var raceResult: CFTypeRef?
+      let raceStatus = SecItemCopyMatching(fetchQuery as CFDictionary, &raceResult)
+      if raceStatus == errSecSuccess, let data = raceResult as? Data {
+        return SymmetricKey(data: data)
+      }
+      throw IntegrityError.keyUnavailable(service: service)
+    }
+
     let key = SymmetricKey(data: rawKey)
     zeroize(&rawKey)
 
-    if addStatus != errSecSuccess && addStatus != errSecDuplicateItem {
+    if addStatus != errSecSuccess {
       throw IntegrityError.keyUnavailable(service: service)
     }
     return key

src/errors.ts

@@ -133,6 +133,10 @@ const extractCode = (error: unknown): ErrorCodeValue | null => {
 const extractMessage = (error: unknown, fallback: string): string => {
 	if (error instanceof Error && error.message) return error.message
 	if (typeof error === 'string' && error.length > 0) return error
+	if (error !== null && typeof error === 'object' && 'message' in error) {
+		const candidate = (error as { message?: unknown }).message
+		if (typeof candidate === 'string' && candidate.length > 0) return candidate
+	}
 	return fallback
 }
 

src/hooks/useKeyRotation.ts

@@ -19,15 +19,25 @@ export interface UseKeyRotationOptions extends SensitiveInfoOptions {
 	readonly reEncryptEagerly?: boolean
 }
 
+/** Per-call overrides accepted by {@link UseKeyRotationResult.rotate}. */
+export interface RotateCallOptions {
+	readonly reEncryptEagerly?: boolean
+}
+
 export interface UseKeyRotationResult {
 	/** Most recent rotation result, if any. */
 	readonly lastResult: RotationResult | null
 	/** Current error bag for rotation operations. */
 	readonly error: HookError | null
 	/** True while a rotation call is in flight. */
 	readonly isRotating: boolean
-	/** Trigger a master-key rotation for the configured service. */
-	readonly rotate: () => Promise<HookMutationResult>
+	/**
+	 * Trigger a master-key rotation for the configured service. Pass
+	 * `{ reEncryptEagerly: true }` to override the hook-level default for this call only.
+	 */
+	readonly rotate: (
+		overrides?: RotateCallOptions
+	) => Promise<HookMutationResult>
 	/** Imperatively read the active key version from the native module. */
 	readonly readVersion: () => Promise<number | null>
 }
@@ -51,18 +61,22 @@ export function useKeyRotation(
 		'Check that the service exists and that no auth-gated entries are blocking eager rotation.'
 	)
 
-	const rotate = useCallback(async (): Promise<HookMutationResult> => {
-		const request: RotateKeysRequest = {
-			...options,
-			reEncryptEagerly: options?.reEncryptEagerly ?? false,
-		}
-		const outcome = await mutate(() => rotateKeys(request))
-		if (outcome.success) {
-			setLastResult(outcome.data)
-			return createHookSuccessResult()
-		}
-		return createHookFailureResult(outcome.error)
-	}, [mutate, options])
+	const rotate = useCallback(
+		async (overrides?: RotateCallOptions): Promise<HookMutationResult> => {
+			const request: RotateKeysRequest = {
+				...options,
+				reEncryptEagerly:
+					overrides?.reEncryptEagerly ?? options?.reEncryptEagerly ?? false,
+			}
+			const outcome = await mutate(() => rotateKeys(request))
+			if (outcome.success) {
+				setLastResult(outcome.data)
+				return createHookSuccessResult()
+			}
+			return createHookFailureResult(outcome.error)
+		},
+		[mutate, options]
+	)
 
 	const readVersion = useCallback(async () => {
 		try {

src/hooks/useSecureStorage.ts

@@ -99,7 +99,8 @@ export function useSecureStorage(
 
 	const [localItems, setLocalItems] = useState<SensitiveInfoItem[] | null>(null)
 
-	// Reset any local override whenever a fresh fetch lands.
+	// Drop the local override whenever a fresh fetch result arrives, so the next
+	// `refetch()` (or option change) is always reflected in the rendered list.
 	useEffect(() => {
 		setLocalItems(null)
 	}, [])