Web Storage 的边界从 SESSION 差异到手机 LOCAL 空值
存储分区与 postMessage 客户端 RPC

STEP 01先区分 origin、site、页面会话与存储分区

Origin · 源

由协议、主机、端口决定。路径和 query 改变通常不改变 origin。

Site · 站点

现代 schemeful site 通常按协议与可注册域划分，不包含端口；本地主机需按其站点规则理解。

Page session · 页面会话

sessionStorage 的会话生命周期边界，通常以标签页／顶层可遍历上下文理解。

Storage partition · 存储分区

浏览器进一步隔离嵌入上下文的数据空间；它可以把同一 origin 在不同顶层上下文中的存储拆开。

因此，讨论“跨域 SSO”时，应进一步说清是跨 origin 但同 site，还是真正跨 site。把域名字符串简单截掉第一段来计算 site 也不可靠，可注册域取决于 Public Suffix List。

STEP 02sessionStorage 的基础边界：标签页内仍按 origin 分组

规范层面，session storage 随顶层可遍历上下文维护，并通过 storage key 找到对应存储区域。入门时可以把它理解为 页面会话 × 存储 origin，再叠加浏览器实际的隐私分区规则。单独写“sessionStorage 只按标签页隔离”是不完整的。

STEP 03早期 SESSION 案例：Safari 与 Chrome 的边界差在哪里？

读写代码都属于认证 origin A，变化的是 A 所处的顶层上下文。登录时 top = A；回跳业务站之后，top = B、iframe = A。即使 tab 没变，浏览器也可能把这两次访问映射到不同存储区。

上图是 WebKit 已记录的分区方式的教学模型，不是所有版本统一的规范公式，也不是对本次机器内部存储键的直接观测。

WebKit 工程师在对应问题中解释，其存储分区会使用主 frame 与子 frame 的 origin。于是同一 tab 里的 A 顶层 与 B → A iframe 可以访问不同区域。这与本次 Safari 的 SESSION 现象一致。

Chrome 的现代分区通常考虑当前 origin 与顶层 site；SESSION 还保留页面会话维度。单层嵌入时，如果 A 与 B 是同站，不同端口改变了 origin，却没有改变顶层 site，因此可以解释本次 Chrome 仍可读的表现。Chrome 的跨站嵌套还可能引入祖先位，不能把“tab + origin”当作它的完整永久规则。

STEP 04LOCAL 也要逐环境验证：桌面成功，手机为何返回 null？

早期顶层写入、iframe 读取的 LOCAL 探针成功，后续 PC 的 Chrome 与 Safari 测试也反馈可读。但手机测试返回 null，且两边都是 localStorage。改成 LOCAL 只改变存储类型，不能保证不同顶层上下文访问同一个区域。

localStorage 通常不随单个标签页结束而清空，但“保存得更久”和“跨分区可见”是两个问题。WebKit 也记录过 localStorage 分区行为及其与隐私设置的关系，因此不能从这次成功推断用户关闭了某个设置，也不能把 LOCAL 写成所有 Safari 场景的通用修复。

同一个认证 origin，为什么还可能读到不同的数据？

WebKit 工程师在 localStorage 跨子域共享问题中确认了按 origin 分区的设计，以及它与隐私设置的关系。即使 A、B 属于同一主域，也可能得到不同区域。上表是帮助理解该实现的简化模型，不是所有浏览器统一的公式，也不是对本次手机内部存储键的直接观测。

Chrome 的分区通常考虑顶层 site、存储 origin 及跨站祖先条件，同站子域与真正跨站应分别验证。桌面 Safari 成功时，还要对照手机的版本、隐私设置和写入位置；不能只凭“同一个浏览器名称”推断两端规则相同。

手机端最短排查路径：在当前 iframe 内写，再从父页读

当前两个调试页都固定使用 hello，它是测试 key。真正登录 token 的 key 由 TOKEN_KEY 配置。只有匹配 GET 请求的 storage-result 或 response-received 中 value = null 且没有 error，才应按“当前可见区域没有该 key”分析；单独一条请求到达事件不能证明读取结果。

1. 手机打开业务读取页，保持当前顶层页面；在页面下方已经嵌入的认证调试 iframe 内选择 localStorage，写入 hello = mobile-probe-v1。
2. 立即点击 iframe 自己的读取按钮，确认写入成功；记录所选 storage、key、当前 origin 与事件类型。
3. 在同一个页面上，父页也选择 localStorage，再点击读取按钮；对照 requestId，确认是否读到相同的探针值。
4. 再比较独立打开认证页时同一 key 的值。若 iframe 自读和父页代读一致，而独立页不同，在排除 URL、模式及写入失败差异后，强烈支持存储上下文隔离。

源码复核没有发现 GET 正常值被转换为 null：代理直接返回 getItem 的结果，异常会附 error，客户端收到 error 会拒绝 Promise。另有待补齐的 event.source 校验，见后文加固章节；目前没有证据把它认定为此次手机空值的原因。模拟环境中的逻辑检查也不能替代真实手机的分区验证。

通用探针：在开发者工具中分别比较 SESSION 与 LOCAL

// 在认证站的顶层页面执行；这是测试值，不是真实 token。
(() => {
  const key = '__storage_boundary_probe__';
  for (const type of ['sessionStorage', 'localStorage']) {
    try {
      window[type].setItem(key, 'probe-v1');
      console.log(type, { origin: location.origin, written: true });
    } catch (error) {
      console.log(type, { written: false, error: error.name });
    }
  }
})();

// 回到业务页，把开发者工具执行上下文切到认证 iframe。
(() => {
  const key = '__storage_boundary_probe__';
  for (const type of ['sessionStorage', 'localStorage']) {
    try {
      console.log(type, {
        origin: location.origin,
        embedded: window.parent !== window,
        matched: window[type].getItem(key) === 'probe-v1'
      });
    } catch (error) {
      console.log(type, { error: error.name });
    }
  }
})();
// 记录结果后，在写入和读取上下文分别删除测试 key。

1. 记录浏览器与系统版本、普通／无痕模式、隐私设置、完整跳转链和两端 origin；不要记录真实 token。
2. 先确认顶层写入成功，再在 iframe 中读取，避免把“未写入”误判成“被分区”。
3. 比较同一 key、同一 storage 类型；切换 LOCAL 后重新登录，SESSION 数据不会自动搬过去。
4. 如果 LOCAL 可读而 SESSION 不可读，支持按存储边界继续排查；如果都不可读，还应检查实际地址、上下文、写入失败和浏览器策略。
5. LOCAL 的成功记录只覆盖对应探针环境；手机、真实 token 获取、刷新、多标签、登出与生产拓扑仍应单独验收。

STEP 05iframe + postMessage：把跨域访问转换为客户端 RPC

业务页不能直接取得跨源 iframe 的 Storage 对象。它持有 iframe.contentWindow，向这个窗口发送操作描述；认证 iframe 收到消息后，在自己的执行上下文与存储权限内完成操作，再把结果发回业务页。

postMessage() 本身不会返回 iframe 的计算结果；它也不会自动把对端异常变成调用端异常。请求协议、返回值关联、Promise、超时和错误传播，都是 CrosStorage 在消息 API 之上构建的 RPC 层。

STEP 06协议：用数据描述调用，用 requestId 关联返回值

协议定义在 CrosProtocol.ts。它没有传递函数引用，而是传递“执行什么、操作哪种存储、哪个 key、写什么值”。下面保留当前类型定义；枚举字符串即实际传输值。

// 定义消息协议

export enum CommandType {
  GET = "get",
  SET = "set",
  REMOVE = "remove",
  INIT = "init"
}
export enum StorageType{
  LOCAL = "local",
  SESSION = "session",
  AUTOMATIC = "automatic"
}

export interface StorageRequest {
  storage: StorageType;
  command: CommandType;
  key: string;
  requestId: string; // 唯一请求ID，用于匹配响应
  value?: string;
}

export interface StorageResponse {
  requestId: string;
  value: string | null;
  error?: string;
}

两个调用可以同时发出，例如读取登录 token 与读取用户偏好。响应先后顺序不应成为关联依据；即使响应顺序改变，各自的 requestId 也能让结果回到正确的等待者。当前实现为每个请求注册独立 listener，而非共用一个会被覆盖的回调。

TypeScript 接口在运行时不存在，因此“声明了 StorageResponse 类型”不等于来自窗口消息的数据已经可信，接收端仍需要运行时检查。

STEP 07CrosStorage 调用端：同源直读，跨源创建代理并等待 INIT

common/lib/CrosStorage.ts 是业务调用入口。构造时把当前页面与 STORAGE_PROXY 比较：协议、主机、端口一致则直接操作本页存储；否则创建或复用隐藏的认证 iframe。

1. 创建 iframe，并把父页 origin 编码到代理 URL 的 query。该 query 是路由信息，不是认证凭据。
2. 父页先安装 INIT 消息监听器，再把 iframe 加入 DOM，减少错过就绪通知的风险。
3. 代理解析 query，校验 allowlist，先注册 handleMessage，再发送 INIT。
4. 父页收到预期 origin 的 INIT，把 iframe 的 loaded 属性置为 true。这里是应用层握手，不是只依赖 DOM load。
5. 请求轮询 loaded，每 100ms 检查一次；就绪后发送请求。等待握手的时间计入该请求的 10 秒超时。

iframe.src = `${STORAGE_PROXY}?${encodeURIComponent(window.location.origin)}`;

// 代理页：先注册处理器，再宣告就绪。
window.addEventListener('message', handleMessage);
window.parent.postMessage({
  storage: StorageType.AUTOMATIC,
  requestId: Utils.randomUUID(),
  key: 'cros-iframe-storage',
  command: CommandType.INIT,
}, parentOrigin);

AUTOMATIC 通常在调用端先被解析：配置严格等于 SESSION 时选择 session，否则选择 local。代理也保留 automatic 兜底分支，但不能据此认为所有调用都由认证站配置统一决定。

private getStorageType(storageType: StorageType) {
  if (storageType === StorageType.AUTOMATIC) {
    storageType = TOKEN_STORAGE === "SESSION"
      ? StorageType.SESSION
      : StorageType.LOCAL;
  }
  return storageType;
}

所以登录写入端、业务读取端都要核对配置。只改一处就可能变成“写 LOCAL、读 SESSION”。调整公开构建变量后，应确保运行中的开发服务／构建产物使用新配置，并重新登录。

STEP 08request()：把异步消息包装为一次可等待的调用

这是客户端 RPC 的核心。每个请求拥有自己的 Promise、响应处理器、轮询定时器和超时定时器。匹配 origin 与 requestId 的响应才能作为结果结算；超时、发送异常与 destroy 也会结束请求。

private request(req: StorageRequest): Promise<string | null> {
        return new Promise((resolve, reject) => {
            let poll: ReturnType<typeof setTimeout>;
            const cleanup = () => {
                clearTimeout(poll);
                clearTimeout(timeout);
                window.removeEventListener("message", handleMessage);
                this.pending.delete(cancel);
            };
            const cancel = () => {
                cleanup();
                reject(new Error("Storage client destroyed"));
            };
            const handleMessage = (event: MessageEvent<StorageResponse>) => {
                if (event.origin !== this.iframeOrigin ||
                    !event.data || event.data.requestId !== req.requestId) return;
                cleanup();
                if (event.data.error) reject(new Error(event.data.error));
                else resolve(event.data.value);
            };
            this.pending.add(cancel);
            window.addEventListener("message", handleMessage);
            const timeout = setTimeout(() => {
                cleanup();
                reject(new Error("Account storage request timed out"));
            }, 10000);
            const send = () => {
                if (this.iframe.getAttribute("loaded") !== "true") {
                    poll = setTimeout(send, 100);
                    return;
                }
                try {
                    this.iframe.contentWindow?.postMessage(req, this.iframeOrigin);
                } catch (error) {
                    cleanup();
                    reject(error);
                }
            };
            send();
        });
    }

当前 pending 是取消函数的 Set，不是 Map<requestId, Promise>。用统一 listener 与 pending Map 是可选重构，不应写成当前已有实现。

STEP 09cros-storage 页面：在自己的权限内执行，再显式返回

(cros)/cros-storage/page.tsx 是客户端 RPC 的服务端角色。这里的“服务端”是协议角色，实际代码仍运行在浏览器 iframe 内。React 页面返回 null，因为它提供存储服务而非可见 UI；监听逻辑放在 useEffect 中，在浏览器运行。

现有页面已经做了基础校验：必须嵌入运行；query 中的父 origin 可解析并在 allowlist 中；消息 origin 与父 origin 一致；数据为对象；requestId/key 为字符串；command/storage 属于允许枚举；SET 的 value 为字符串。通过后才进入存储执行分支。

// 当前代理执行分支的等价节选：省略上方基础校验与调试日志。
const response: StorageResponse = {
  requestId: request.requestId,
  value: null,
};
try {
  const local = request.storage === StorageType.LOCAL ||
    (request.storage === StorageType.AUTOMATIC && TOKEN_STORAGE !== 'SESSION');
  const storage = local ? window.localStorage : window.sessionStorage;

  switch (request.command) {
    case CommandType.GET:
      response.value = storage.getItem(request.key);
      break;
    case CommandType.SET:
      if (typeof request.value !== 'string')
        throw new Error('Value is required for set command');
      storage.setItem(request.key, request.value);
      response.value = request.value;
      break;
    case CommandType.REMOVE:
      response.value = storage.getItem(request.key);
      storage.removeItem(request.key);
      break;
  }
} catch (error) {
  response.error = error instanceof Error ? error.message : 'Storage unavailable';
}
window.parent.postMessage(response, parentOrigin);

异常必须被序列化到 response.error 才能被调用端感知。iframe 内直接 throw，不会自动穿过 postMessage 通道。另一方面，getItem() 返回 null 是一次合法读取结果，不会触发 catch。

当前代理卸载时移除 handleMessage；各客户端实例的清理是否真的被调用，还取决于调用方 Hook 的实现。下面的源码审查会区分两层责任。

STEP 10用一次消息往返理解 RPC：通信成功也可能返回 null

下面演示请求从创建、就绪、执行到完成的过程。选择不同结果，再逐步推进，可比较“无 token”和“请求没有完成”的区别。

两次并发调用即使收到顺序颠倒的响应，也要按 requestId 分别结算。当前代码在超时后移除该请求 listener，因此迟到响应不应再改变已结束的 Promise。进一步提高可靠性时，可加入协议版本、命名空间和严格响应 schema。

STEP 11将 RPC 接入 SSO：共享登录材料，认证仍由后端完成

当前登录页先等待 setToken() 完成，再回跳。Fetcher 调用 getToken() 后构造 Authorization 请求头。用户信息的本地解码与缓存只服务于界面展示，不能替代后端对签名、有效期和权限的验证。

这套方案成立需要两个独立前提：授权业务站可以与代理通信；代理能读到登录流程保存的同一份 token。前者由 RPC 与消息授权解决，后者由存储类型、写入位置、浏览器策略和页面拓扑决定。

当前同站架构优先评估 Cookie，跨站场景保留授权码方案

本项目的生产配置使用 HTTPS，认证站、业务站与集中 API 属于同一可注册域下的不同子域。对于这个拓扑，用 Cookie 承载 token 或会话标识，并由服务端完成鉴权，可以让业务请求直接获得认证，消除从认证 iframe 取 localStorage 的依赖。这里描述的是待实施方案，当前 Fetcher、上传与 WebSocket 仍然依赖前端读取 token。

Cookie 方案的核心：浏览器携带凭据，API 验证登录态

这条流程中，业务页不需要知道 Cookie 的具体值，也不需要通过 iframe 读取认证页的 Web Storage。HttpOnly Cookie 仍会随符合条件的请求发送，但前端 JavaScript 无法读取它；因此它不能直接用于现有的“getToken() 后拼 Authorization”代码。

Set-Cookie: auth_token=<REDACTED>; Path=/; HttpOnly; Secure; SameSite=Lax

# 没有 Domain：Cookie 限定在设置它的 api.example.com。
# 示例不表示当前后端已经支持该 Cookie 名称或鉴权方式。
# 过期时间、刷新和撤销策略须与实际 token / 会话设计一致。

// /example-resource 是示意业务路径，需替换为实际接口。
const response = await fetch('https://api.example.com/example-resource', {
  credentials: 'include'
});
// Cookie 由浏览器处理；无需先调用 CrosStorage.getToken()。

当前 Fetcher 只有显式传入 withCookie: true 才设置 credentials，但即使打开这个选项，仍会先执行 getToken()。因此迁移不能只修改存储介质或新增一个开关。文中示例是改造方向，落地前还需确认后端的 Cookie 鉴权能力，并完成前后端适配。

共享域 Cookie 与 HttpOnly API Cookie 是两种不同用法

同主域不会自动把 host-only Cookie 变成共享 Cookie。认证主机可以在规则允许时设置父域 Cookie，但不能给兄弟 API 主机设置它专属的 host-only Cookie；后一种应由 API 自己的响应设置。

保留 Authorization 或扩展到跨站：顶层授权码回跳

如果需要继续使用现有 token 接口，或部署扩展到真正跨站、Cookie 不能按预期携带的环境，可以采用顶层认证回跳 + 一次性授权码兑换。各业务站在自己的上下文中管理凭据，不依赖认证 iframe 的持久化存储可见性。

采用成熟的授权码协议时，配套精确回调地址校验、请求绑定与 PKCE 等要求；前端公共客户端不能保管 client secret。URL 只传短期一次性 code，长期凭据通过受保护的兑换流程获取。当前前端尚未发现授权码签发与兑换接口，这是需要后端配合的迁移建议，并非已实现功能。

若业务都请求同一个 api.example.com，Cookie 会话可以限定在该 API 主机，不必默认给所有子域共享 Cookie。跨站部署仍需单独评估凭据策略；Cookie 方案不能被概括为绕过一切浏览器限制。

隐藏 iframe 中直接调用 requestStorageAccess() 也不是自动修复。应核对目标浏览器、存储类型、用户手势及权限要求；Cookie 的授权不能直接当作 Web Storage 的解分区保证。

STEP 12以当前源码为准：已有能力与需要补强的部分

文章分析的是当前工作区源码，不把建议伪装成已经完成的实现。尤其要注意：客户端注释写着同时匹配 origin 和 iframe window，但当前实际条件尚未检查 event.source。

// 父页面：INIT 和普通响应都需要验证预期 iframe。
if (event.origin !== iframeOrigin ||
    event.source !== iframe.contentWindow) return;

// 代理页：限定为发起嵌入的直接父窗口。
if (event.origin !== parentOrigin ||
    event.source !== window.parent ||
    !allowOrigin(event.origin)) return;

// 之后继续验证消息 schema、允许的 command 与 key。
// requestId 只关联响应，不证明调用者身份。

消息机制把哪些业务站可以读取认证数据的决定交给了应用。接收 token 的站点因此进入信任范围。精确 origin/source 校验、最小 key 授权与不记录明文 token，都是这一 RPC 服务自身需要完成的职责。

另外，同源分支先同步执行 Storage 方法，再包 Promise.resolve；存储异常可能同步抛出。不能把所有分支描述为已经统一的异步异常模型。当前 Utils.randomUUID 使用随机字符串拼接，其用途应限定为请求关联。

STEP 13验证矩阵：分别验收消息、存储与登录态

最有效的诊断顺序是：写入成功 → 读写配置一致 → iframe 确实就绪 → 请求到达 → 当前分区读到什么 → 响应是否匹配 → 后端如何处理 token。这样能把存储分区与消息协议故障分开，避免在 null 已经明确返回时继续调整握手超时。