前端接入（JS SDK）

不想自己实现授权跳转？在页面上引一段脚本：

<script src="https://auth.rankhub.cc/oauth/sdk.js" defer></script>
<div id="login"></div>
<script>
  window.addEventListener('DOMContentLoaded', function () {
    RankHubAuth.button('#login', {
      clientId: 'your-client-id',
      redirectUri: 'https://app.example.com/auth/callback',
      scope: 'openid profile',
      variant: 'filled',
      onSuccess: function (result) { console.log(result.code); },
      onError: function (error) { console.warn(error.code, error.message); },
    });
  });
</script>

SDK 只做三件事：渲染按钮、开小窗 / 挂 iframe、收 postMessage。它自己从不调用 Auth 接口 ——所有协议调用都发生在 auth 域自己的页面里（同源），所以不需要你配 CORS，也不依赖第三方 Cookie。

小窗还是内嵌

小窗流程唯一必须额外写的代码，是一个回调页：

<!-- https://app.example.com/auth/callback -->
<script src="https://auth.rankhub.cc/oauth/sdk.js"></script>

就这些 —— SDK 加载时会发现「我在小窗里 + URL 里有 code + 本地存着这次请求」，于是投递结果并关窗。

API

RankHubAuth.config(options)

RankHubAuth.button(target, options)

按钮渲染在 Shadow DOM 里，宿主页的 button { … } 不会影响它。要改样式用 CSS 变量：

#login { --rankhub-auth-bg: #0f766e; --rankhub-auth-fg: #fff; --rankhub-auth-radius: 999px; }

RankHubAuth.embed(target, options)

const handle = RankHubAuth.embed('#slot', { mode: 'overlay', height: 560 });
handle.result.then(r => console.log(r.code)).catch(e => console.warn(e.code));

ready 在授权面确认「我被允许框住」之后 resolve；8 秒内没有任何消息会以 origin_not_registered 报错（通常是来源没登记，或浏览器按 frame-ancestors 拦掉了）。

其他方法

回调页可以只靠声明式属性挂载（脚本标签加 data-auto="on" 时自动扫描）：

<div data-rankhub-auth="button" data-client-id="…" data-redirect-uri="…"
     data-variant="outlined" data-label="登录"></div>

错误码

error 是 RankHubAuthError（error.code / error.message / error.state）。

浏览器边界

• 不依赖第三方 Cookie：所有协议调用都在 auth 域内完成，Safari 的跨站跟踪防护不影响内嵌模式。
• 内嵌模式不支持 prompt=none：iframe 里的存储/会话本来就被拦，服务端会直接拒绝。
• 内嵌模式可能不显示「近期账号」列表：那份列表存在 auth 域的 localStorage，第三方 iframe 里 可能被隔离。流程本身不受影响（走「使用其他账号」）。
• 小窗的回调页必须与宿主页同源：state / code_verifier 存在宿主页自己的存储里。
• 一次性：code 用一次就作废，state 每次请求新生成。
• 脚本 URL 稳定（/oauth/sdk.js），内容可能修 bug；破坏性变更会换路径。

登记可内嵌来源

要把授权面内嵌进 https://app.example.com，把该裸 origin 填进 开发者平台 里该应用的 可嵌入来源（Embed Origins） 字段 （创建或编辑时都能改，保存后立即生效，不需要重新审核）。详见注册应用与凭据。

规则：只允许 https（http 仅限 localhost / 127.0.0.1 / [::1]）、不带路径/查询/片段、 小写 host、最多 20 项。登记一个来源 = 允许把该客户端的授权码交付给它，所以只登记你控制的域名。

未登记的来源仍然能被浏览器加载页面，但拿不到授权结果，而且不会创建任何授权请求。