プッシュ連携（ID ハンドシェイク / 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 を解析して信頼できる ID として扱わないこと）
  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 });
  }
});