HarmonyOS 安全存储实战：Token 生命周期、刷新互斥、退出清理和日志脱敏

HarmonyOS 安全存储实战：Token 生命周期、刷新互斥、退出清理和日志脱敏

登录态问题通常不是登录接口本身，而是 Token 生命周期没有设计好：access token 过期后多个请求同时刷新，refresh token 被覆盖，退出登录只清了内存没清安全存储，日志里打印了敏感字段，用户切账号后仍拿到上一个账号的数据。

这篇文章只解决一个工程问题：HarmonyOS 应用如何把 Token 安全存储、过期判断、刷新互斥、退出清理和日志脱敏做成一条可靠链路。

本文会落到四个结果：

一、先区分四类数据：不是所有登录信息都能同样存

登录相关数据要分级。

最常见的问题是把所有登录信息都塞进一个 UserInfo，然后随手写到 Preferences 或日志里。安全存储的第一步是分级。

二、资料与版本边界：本文写应用层凭据治理

本文示例面向 HarmonyOS NEXT / ArkTS 工程，应用层重点放在 Token 模型、持久化边界、刷新互斥、退出清理和日志脱敏。具体加密存储能力可结合 Keychain / Universal Keystore Kit / Preferences 等官方能力与项目安全要求选择。

三、Token 模型：明确过期时间和来源

Token 不能只保存字符串。

export interface TokenBundle {
accessToken: string;
refreshToken: string;
accessExpireAt: number;
refreshExpireAt: number;
userId: string;
issuedAt: number;
}

export function accessTokenExpired(bundle: TokenBundle, safeWindowMs: number): boolean {
return Date.now() + safeWindowMs >= bundle.accessExpireAt;
}

export function refreshTokenExpired(bundle: TokenBundle): boolean {
return Date.now() >= bundle.refreshExpireAt;
}

这里的 safeWindowMs 很重要。不要等 Token 刚好过期才刷新，可以提前一两分钟刷新，减少临界点失败。

四、安全存储接口：页面不能直接碰 Token

把 Token 读写封装成仓储，不让页面直接访问存储能力。

export interface TokenStore {
save(bundle: TokenBundle): Promise<void>;
load(): Promise<TokenBundle | undefined>;
clear(): Promise<void>;
}

export class SecureTokenRepository {
constructor(private readonly store: TokenStore) {}

async saveToken(bundle: TokenBundle): Promise<void> {
await this.store.save(bundle);
}

async getToken(): Promise<TokenBundle | undefined> {
return this.store.load();
}

async clearToken(): Promise<void> {
await this.store.clear();
}
}

这层的价值：

五、刷新互斥：多个请求不要同时刷新

并发刷新是登录态最常见的坑。多个接口同时发现 access token 过期，如果都去刷新，可能导致 refresh token 被服务端轮换后互相覆盖。

export interface RefreshResult {
success: boolean;
bundle?: TokenBundle;
message: string;
}

export class TokenRefreshGate {
private refreshing?: Promise<RefreshResult>;

async run(refreshAction: () => Promise<RefreshResult>): Promise<RefreshResult> {
if (this.refreshing !== undefined) {
return this.refreshing;
}

this.refreshing = refreshAction();
try {
return await this.refreshing;
} finally {
this.refreshing = undefined;
}
}
}

这段代码保证同一时间只有一个刷新动作。其他请求等待结果，避免把 refresh token 用乱。

六、请求前拦截：先判断，再带 Token

请求层要在发送前拿到可用 Token。

export class AuthHeaderProvider {
constructor(
private readonly repository: SecureTokenRepository,
private readonly refreshGate: TokenRefreshGate
) {}

async buildAuthHeader(refreshAction: () => Promise<RefreshResult>): Promise<Record<string, string>> {
const bundle = await this.repository.getToken();
if (bundle === undefined) {
return {};
}

if (refreshTokenExpired(bundle)) {
await this.repository.clearToken();
return {};
}

if (accessTokenExpired(bundle, 120000)) {
const refreshed = await this.refreshGate.run(refreshAction);
if (!refreshed.success || refreshed.bundle === undefined) {
return {};
}
await this.repository.saveToken(refreshed.bundle);
return { Authorization: `Bearer ${refreshed.bundle.accessToken}` };
}

return { Authorization: `Bearer ${bundle.accessToken}` };
}
}

边界说明：

七、退出登录：清理不止一个 Token

退出登录要清理内存、持久化、请求队列、页面状态和用户缓存。

export interface LogoutCleaner {
clearMemory(): Promise<void>;
clearSecureStore(): Promise<void>;
cancelPendingRequests(): Promise<void>;
clearUserCache(): Promise<void>;
resetNavigation(): Promise<void>;
}

export async function logoutCompletely(cleaner: LogoutCleaner): Promise<void> {
await cleaner.cancelPendingRequests();
await cleaner.clearMemory();
await cleaner.clearSecureStore();
await cleaner.clearUserCache();
await cleaner.resetNavigation();
}

顺序也有意义：先取消未完成请求，再清 Token；否则某个请求可能在退出后继续拿旧 Token 写数据。

八、切账号：比退出登录更容易漏数据

切账号要防止 A 账号缓存污染 B 账号。

export interface AccountSession {
userId: string;
token: TokenBundle;
createdAt: number;
}

export function sameAccount(current: AccountSession | undefined, nextUserId: string): boolean {
return current !== undefined && current.userId === nextUserId;
}

export async function switchAccount(
current: AccountSession | undefined,
next: AccountSession,
cleaner: LogoutCleaner,
repository: SecureTokenRepository
): Promise<void> {
if (!sameAccount(current, next.userId)) {
await logoutCompletely(cleaner);
}
await repository.saveToken(next.token);
}

切账号时要清页面栈、用户缓存、草稿和请求队列。否则最容易出现“头像变了，但列表还是上一个账号的数据”。

九、日志脱敏：排查不能牺牲安全

日志里不要打印完整 Token。

export function maskToken(token: string): string {
if (token.length <= 12) {
return '***';
}
return `${token.slice(0, 6)}***${token.slice(–4)}`;
}

export interface AuthLog {
action: 'login' | 'refresh' | 'logout' | 'expired' | 'switchAccount';
userIdMasked: string;
tokenMasked?: string;
success: boolean;
message: string;
timestamp: number;
}

日志需要能排查，但不能泄露。userId、手机号、邮箱、Token、设备标识都要按安全要求处理。

十、Token 问题排查表

登录态问题排查不要只看接口返回码，要看 Token 生命周期和请求并发。

十一、上线前安全验收表

这张表适合放到登录态改造和发版前自查里。

十二、安全存储相关官方资料

十三、把登录态做成可恢复也可清理的系统

安全存储不是单点能力，而是登录态治理的一部分。Token 模型、存储仓储、刷新互斥、退出清理、切账号隔离和日志脱敏缺一不可。

最后用这张表复盘：