推式接入（身份握手 / Push Handoff）

                      
                      import { consumeHandoff } from '@gptbots/workspace-extension-sdk';

try {
  const identity = await consumeHandoff({
    exchangeUrl: '/session/exchange', // 你自己的後端校驗介面
    // search:   location.search,     // 預設讀 location.search
    // paramName: 'wsa',              // 預設參數名 wsa
    // strip:     true,              // 預設成功後抹除 URL 中的 wsa
  });
  bootYourApp(identity);
} catch (e) {
  // 沒有 wsa（使用者直接存取）、或後端校驗失敗
  showLoginOrError(e);
}

                    

                      
                      import { readHandoffToken, stripHandoffToken } from '@gptbots/workspace-extension-sdk';

const token = readHandoffToken();   // 純函數，回傳原始 JWT 字串或 null
if (token) {
  // 仍建議把 token 發給你後端 verifyWsa 後再信任其內容（不要在前端解析 JWT 當可信身份）
  await fetch('/telemetry/visit', { method: 'POST', body: JSON.stringify({ wsa: token }) });
}
stripHandoffToken();                // 無論如何抹掉 URL 裡的 wsa

                    

                      
                      import { verifyWsa, WsaVerificationError } from '@gptbots/workspace-extension-verify';

app.post('/session/exchange', (req, res) => {
  try {
    const identity = verifyWsa(req.body.wsa, {
      secret: process.env.EXTENSION_APP_SECRET, // Tier2 per-app 金鑰 或 Tier1 共享金鑰
      audience: 'app.example.com',              // 擴充應用程式 host，必須等於 aud
      // issuer: 'gptbots-workspace',          // 預設
      // leewaySeconds: 30,                    // 時鐘漂移容忍，預設 30s
      // algorithms: ['HS256'],                // 預設
    });

    // 多租戶隔離：把請求歸到 identity.workspaceId 名下
    const sid = createSession(identity);
    res.cookie('sid', sid, { httpOnly: true, secure: true, sameSite: 'lax' });
    res.json(identity);
  } catch (e) {
    const code = e instanceof WsaVerificationError ? e.code : 'Error';
    res.status(401).json({ code });
  }
});