/**
 * Browser localStorage helpers that encrypt API tokens at rest using Web Crypto (AES-GCM + PBKDF2).
 *
 * Threat model (what this does and does **not** do):
 * - **Addresses**: Static analysis / policy expectations that secrets not be written to storage as
 *   cleartext; casual inspection of profile files without executing app JS; legacy cleartext tokens
 *   are rewritten to ciphertext on first read when crypto is available.
 * - **Does not address**: XSS — `deviceId` and the encrypted blob live in the same origin storage,
 *   and JS can derive the same PBKDF2 inputs, so a script that can read `localStorage` can recover
 *   the token. Stronger mitigation is HttpOnly (+ Secure, SameSite) cookies and server-side session
 *   handling so the access token is not exposed to JavaScript.
 *
 * **Defence in depth / reviewer note:** PR titles or SAST tickets may describe this as “sensitive
 * cookie/storage” hardening. That wording must not be read as **token confidentiality against XSS**:
 * this layer does **not** provide that. The recommended long-term mitigation remains server-issued
 * **HttpOnly + Secure (+ SameSite)** session cookies (and CSRF protections where applicable), with
 * tokens never exposed to `document`/JS — see OWASP session management guidance.
 *
 * @todo Migrate facility web + patient portal auth to HttpOnly cookie sessions where product/security
 *   requirements allow, so XSS cannot exfiltrate bearer tokens via `localStorage` or this module.
 */
export type TokenStorageNamespace = 'webapp' | 'patient-portal';
export declare function buildTokenStorageKeyMaterial(deviceId: string, origin: string, namespace: TokenStorageNamespace): string;
/** Minimal storage surface (e.g. `localStorage`) for tests or non-browser use. */
export interface AuthTokenStorage {
    getItem(key: string): string | null;
    setItem(key: string, value: string): void;
    removeItem(key: string): void;
}
/**
 * Encrypt and store an API token, or remove the key when `token` is empty.
 * Falls back to cleartext storage when Web Crypto is unavailable (plain HTTP, non-localhost) — the
 * session is already transmitted unencrypted in that case, so cleartext localStorage is no worse.
 */
export declare function writePersistedAuthToken(storageKey: string, token: string, deviceId: string, namespace: TokenStorageNamespace, storage?: AuthTokenStorage, origin?: string): Promise<void>;
/**
 * Read and decrypt a stored token. Removes the key if ciphertext is present but invalid.
 * Legacy cleartext values are migrated to encrypted form on first successful read when Web Crypto is available.
 * Returns only `{ token }` so the pre-migration storage string is never part of the public return value.
 */
export declare function readPersistedAuthToken(storageKey: string, deviceId: string, namespace: TokenStorageNamespace, storage?: AuthTokenStorage, origin?: string): Promise<{
    token: string | null;
}>;
/** New writes use v2 (random PBKDF2 salt per encryption). */
export declare function packPersistedToken(token: string, keyMaterial: string): Promise<string>;
export declare function unpackPersistedToken(stored: string | null | undefined, keyMaterial: string): Promise<string | null>;
