zero_auth 0.2.0

Backend-agnostic auth state machine & session lifecycle for Dart/Flutter.

Changelog

0.2.0

Added / 新增

• Session (de)serialization — AuthSession now exposes toJson() / AuthSession.fromJson() (and RefreshToken gains matching toJson() / fromJson()), so a session can be persisted to disk or secure storage and rehydrated losslessly across app restarts. null fields are omitted and claims round-trips as a plain map.
  • 会话（反）序列化——AuthSession 现提供 toJson() / AuthSession.fromJson() （RefreshToken 也增加对应的 toJson() / fromJson()），会话可被持久化到 磁盘或安全存储，并在应用重启后无损恢复。null 字段会被省略，claims 作为普通映射原样往返。
• Proactive auto-refresh — AuthManager accepts a new optional autoRefreshAhead duration. When a session carries both an expiresAt and a refresh token, the manager schedules a single-flight refresh() that many minutes before expiry, so callers rarely hit an expired access token. Disabled by default (backwards compatible).
  • 临近过期自动刷新——AuthManager 新增可选参数 autoRefreshAhead。当会话同时 带有 expiresAt 与刷新令牌时，管理器会在过期前该时长调度一次单飞 refresh()， 调用方几乎不会撞上过期的访问令牌。默认关闭，向后兼容。

Example / 示例

• Added example/lib/json_token_store.dart — a dart:io file-backed TokenStore built on the new serialization, for server / CLI / desktop.
  • 新增 example/lib/json_token_store.dart——基于新序列化、面向服务端 / CLI / 桌面的 dart:io 文件型 TokenStore。

0.1.0

Added / 新增

• Auth state machine — AuthManager drives the explicit Unauthenticated → Authenticating → Authenticated → AuthError lifecycle and broadcasts it on a Stream<AuthState> that replays the latest value to new listeners, so a widget can render the correct screen on its first frame.
  • 认证状态机——AuthManager 驱动显式的 Unauthenticated → Authenticating → Authenticated → AuthError 生命周期， 并通过「重放最近值」的 Stream<AuthState> 广播，使 widget 在首帧即可渲染正确界面。
• Backend boundary (AuthStrategy) — a single four-method interface (login / register / logout / refresh) is all a backend has to implement. The core ships no HTTP, no SDK and no native code, so REST, gRPC, Firebase or a private RPC are equally valid targets.
  • 后端边界（AuthStrategy）——后端只需实现 login / register / logout / refresh 四个方法。内核不含任何 HTTP、SDK 或原生代码，因此 REST、gRPC、Firebase 或自有 RPC 均可平等接入。
• Silent restore & single-flight refresh — restore() rehydrates the persisted session at startup, and concurrent refresh() callers share one in-flight request instead of stampeding the backend; a failed refresh clears the session and emits AuthError.
  • 静默恢复与单飞刷新——restore() 在启动时恢复持久化会话；并发的 refresh() 调用方共享同一次进行中的请求，而不会同时冲击后端；刷新失败会清空会话并发出 AuthError。
• Pluggable persistence (TokenStore) — the only persistence surface is save / load / clear. InMemoryTokenStore ships in the core; a flutter_secure_storage-backed reference implementation lives in example/lib/secure_token_store.dart for production use.
  • 可插拔持久化（TokenStore）——唯一的持久化接口是 save / load / clear。 内核自带 InMemoryTokenStore；生产可用的 flutter_secure_storage 参考实现位于 example/lib/secure_token_store.dart。
• Strongly-typed session (AuthSession) — carries access token, refresh token, expiry (isExpired), user id, display name and raw claims, so callers never parse token payloads by hand.
  • 强类型会话（AuthSession）——携带访问令牌、刷新令牌、过期时间（isExpired）、 用户 ID、显示名与原始 claims，调用方无需手工解析令牌载荷。
• Unified errors — every domain failure is mapped to AppException from this package's error kernel (AuthException for auth-specific cases), and a Result<T> wrapper is available for explicit Ok / Err handling. Raw Exceptions never cross the public surface.
  • 统一错误——所有领域失败都映射为本包错误内核的 AppException（认证相关场景为 AuthException），并提供 Result<T> 以支持显式的 Ok / Err 处理。 裸 Exception 绝不会跨越公共 API 边界。
• Network integration (AuthTokenSource) — AuthManager itself is an AuthTokenSource, so a Dio interceptor can attach Authorization: Bearer <token> without depending on the manager. A ready-to-use interceptor lives in example/lib/dio_interceptor.dart.
  • 网络集成（AuthTokenSource）——AuthManager 本身即是一个 AuthTokenSource， 因此 Dio 拦截器可在不依赖管理器的前提下附加 Authorization: Bearer <token>。 开箱可用的拦截器位于 example/lib/dio_interceptor.dart。
• Runnable example & demo backend — example/ is a full Flutter app (Android / iOS / Web / Windows) that exercises login, refresh, logout and a protected GET /me call. server/ is a zero-dependency dart:io backend (dart run bin/server.dart) exposing /login, /refresh, /logout and /me; any username works and the password must be b, so both the success and the AuthError path are reproducible without external infrastructure.
  • 可运行示例与演示后端——example/ 是完整的 Flutter App （Android / iOS / Web / Windows），覆盖登录、刷新、登出与受保护的 GET /me 调用； server/ 是零依赖的 dart:io 后端（dart run bin/server.dart），提供 /login、 /refresh、/logout 与 /me；用户名任意、密码必须是 b， 因此无需外部基础设施即可复现成功与 AuthError 两条路径。