Add JSDoc to security hooks

Add comprehensive JSDoc comments to useHasSecret, useKeyRotation, useSecureOperation, and useSecurityAvailability. The updates document params, return types, remarks, examples, and related links; clarify behaviors such as avoiding biometric prompts when only checking existence, lazy vs eager key rotation and its biometric implications, execute() swallowing errors and exposing AuthenticationCanceledError as a cause, and caching/refetch semantics for security capability queries. Improves developer guidance and API discoverability.

Author: mCodex

src/hooks/useHasSecret.ts

@@ -17,6 +17,26 @@ export interface UseHasSecretResult extends AsyncState<boolean> {
 
 /**
  * Checks if a secure item exists without fetching its payload.
+ *
+ * @param key     - Identifier to look up. Changing the key triggers a fresh check.
+ * @param options - Storage scoping plus a `skip` flag.
+ * @returns A {@link UseHasSecretResult} where `data` is the boolean existence flag and `refetch`
+ * re-runs the check on demand.
+ *
+ * @remarks Prefer this over {@link useSecret} / {@link useSecretItem} when you only need to know
+ * whether a key exists \u2014 it never decrypts and never triggers biometric prompts.
+ *
+ * @example
+ * ```tsx
+ * const { data: hasToken, isLoading } = useHasSecret('session-token', {
+ *   service: 'com.example.auth',
+ * })
+ *
+ * if (isLoading) return null
+ * return hasToken ? <Dashboard /> : <Onboarding />
+ * ```
+ *
+ * @see {@link hasItem}
  */
 export function useHasSecret(
 	key: string,

src/hooks/useKeyRotation.ts

@@ -45,6 +45,30 @@ export interface UseKeyRotationResult {
 /**
  * Provides a minimal wrapper around {@link rotateKeys} / {@link getKeyVersion} with loading,
  * result, and error state wired up for UI consumption.
+ *
+ * @param options - Storage scoping plus a `reEncryptEagerly` default for the `rotate()` helper.
+ * @returns A {@link UseKeyRotationResult} with `lastResult`, `error`, `isRotating`, and the
+ * imperative `rotate` / `readVersion` helpers.
+ *
+ * @remarks
+ * - `rotate({ reEncryptEagerly: true })` may trigger one biometric prompt **per protected entry**.
+ *   Prefer the default lazy rotation unless you have a compliance reason to migrate ciphertext
+ *   immediately.
+ * - `rotate()` never throws \u2014 it resolves with a {@link HookMutationResult}.
+ *
+ * @example
+ * ```tsx
+ * const { rotate, readVersion, isRotating, lastResult } = useKeyRotation({
+ *   service: 'com.example.auth',
+ * })
+ *
+ * await rotate()                          // lazy: returns immediately
+ * await rotate({ reEncryptEagerly: true }) // eager: re-encrypts every entry now
+ * const version = await readVersion()
+ * ```
+ *
+ * @see {@link rotateKeys}
+ * @see {@link getKeyVersion}
  */
 export function useKeyRotation(
 	options?: UseKeyRotationOptions

src/hooks/useSecureOperation.ts

@@ -13,11 +13,23 @@ export interface UseSecureOperationResult extends VoidAsyncState {
 /**
  * Wraps a single asynchronous procedure (such as clearing a service) with loading and error state.
  *
+ * @returns A {@link UseSecureOperationResult} with `error`/`isLoading`/`isPending` flags and an
+ * `execute(operation)` helper that runs the supplied async callback while tracking lifecycle.
+ *
+ * @remarks
+ * - `execute()` swallows the underlying throw and surfaces the failure as `error` (a typed
+ *   {@link HookError}). It never re-throws.
+ * - User-cancelled biometric prompts surface as a `HookError` whose `cause` is an
+ *   {@link AuthenticationCanceledError} \u2014 inspect `.cause` if you need to differentiate.
+ *
  * @example
  * ```tsx
  * const secureLogout = useSecureOperation()
  *
- * const handleLogout = () => secureLogout.execute(() => SensitiveInfo.clearService({ service: 'auth' }))
+ * const handleLogout = () =>
+ *   secureLogout.execute(() => clearService({ service: 'com.example.auth' }))
+ *
+ * if (secureLogout.error) toast(secureLogout.error.message)
  * ```
  */
 export function useSecureOperation(): UseSecureOperationResult {

src/hooks/useSecurityAvailability.ts

@@ -11,6 +11,29 @@ export interface UseSecurityAvailabilityResult
 
 /**
  * Queries which security primitives are available on the current device and caches the outcome.
+ *
+ * @returns A {@link UseSecurityAvailabilityResult} with `data` (the latest snapshot),
+ * `error`/`isLoading`/`isPending` flags, and a `refetch` helper that bypasses the cache.
+ *
+ * @remarks
+ * - The hook caches the first successful response per component instance \u2014 subsequent renders
+ *   reuse the cached value without hitting the native module.
+ * - `refetch()` forces a fresh native call \u2014 use it after the user changes biometric enrollment
+ *   in system settings.
+ * - On error, the previously cached `data` is preserved so you can render fallback UI without
+ *   losing capability info.
+ *
+ * @example
+ * ```tsx
+ * const { data: caps, isLoading } = useSecurityAvailability()
+ *
+ * if (isLoading || !caps) return null
+ * return caps.biometry
+ *   ? <EnableFaceIdToggle />
+ *   : <Text>Biometrics unavailable on this device.</Text>
+ * ```
+ *
+ * @see {@link getSupportedSecurityLevels}
  */
 export function useSecurityAvailability(): UseSecurityAvailabilityResult {
 	const cacheRef = useRef<SecurityAvailability | null>(null)