尧图网站建设 
Puter 认证 API 实战用 Puter.js 在网页应用中接入 Puter 账号体系【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puterPuter 是一个开源、可自托管的云端计算机平台而puter.auth是 Puter.js SDK 中负责身份认证的核心模块。它让第三方网页应用能够借助用户的 Puter 账号完成登录从而解锁后续的 FS 文件系统、KV 存储、AI 能力等一系列 Puter.js API。本指南以仓库中 Auth.md 为骨架结合 SDK 源码 与全部六个认证函数文档讲解 sign-in / sign-out、登录状态检测、用户信息拉取与用量查询的完整用法、参数语义、平台差异与底层认证原理读完即可在你的应用中接入 Puter 账号认证。一、Puter 认证 API 解决什么问题Puter.js 提供多个面向网页应用的高级 API文件系统、KV、AI、Hosting 等而这些 API 几乎都要求调用者是已认证用户。认证 API 就是打通这一步的入口它支持Sign In发起登录流程让用户用 Puter 账号授权你的应用Check Sign In检测当前用户是否已登录Get User获取当前用户的基础信息Sign Out让用户退出你的应用用量查询查询用户当前的月度资源用量与应用维度的详细用量统计。一个关键设计理念在 signIn.md 中写得很清楚Puter 中几乎所有核心方法都会自动处理认证。puter.auth这套方法只在你想手动驱动认证流程时才必须出现例如构建自定义登录界面或切换账号按钮。自动认证 vs 手动认证理解两套运行模型至关重要运行在 Puter 内部的 App应用本身就是被用户从 Puter 桌面启动的Puter 会话在启动那一刻就把令牌交给了应用所以应用天然处于已登录状态。对这类应用直接调用puter.auth.getUser()读取当前用户即可不需要也不能再走弹窗登录流程外部网页Website站点通过script srchttps://js.puter.com/v2//script引入 SDK 后通常没有用户令牌此时需要通过puter.auth.signIn()弹窗授权来获得令牌。从源码 index.js 的注释可以看出SDK 内部把这类随应用令牌而来的说明与puter.auth.getUser()明确关联整套设计正是围绕上述两种模型展开。二、快速上手在网页中发起登录signIn()会打开一个弹窗进入 Puter 的认证界面并在用户完成登录后 resolve。原文档提供了一个可以直接运行的完整 HTML 示例html body script srchttps://js.puter.com/v2//script button idsign-inSign in/button script // Because signIn() opens a popup window, it must be called from a user action. document.getElementById(sign-in).addEventListener(click, async () { // signIn() will resolve when the user has signed in. await puter.auth.signIn().then((res) { puter.print(Signed inbr JSON.stringify(res)); }); }); /script /body /html两个必须记住的要点必须由用户动作触发。signIn()打开的是浏览器弹窗浏览器通常会拦截非用户手势触发的弹窗。所以它必须挂在 click 等事件回调里或任何有用户激活的时机Promise 语义。signIn()返回一个Promise用户完成登录后 resolve 为一个SignInResult对象如果流程失败弹窗被拦截、用户关闭窗口等则 reject 并携带错误码与可读信息详见下文signIn()小节。该页面同样存在于仓库的 playground 可交互示例中auth-sign-in.html你可以边改边跑体验真实流程。三、六个认证函数逐一详解原文档 Auth.md 的 Functions 部分列出了开箱即用的六个函数。下表给出了函数、说明与仓库内对应文档的映射函数作用详细文档puter.auth.signIn()登录用户signIn.mdputer.auth.signOut()退出当前用户signOut.mdputer.auth.isSignedIn()判断用户是否已登录isSignedIn.mdputer.auth.getUser()获取当前用户信息getUser.mdputer.auth.getMonthlyUsage()获取当月资源用量getMonthlyUsage.mdputer.auth.getDetailedAppUsage()获取某个应用的详细用量getDetailedAppUsage.md这六个方法在 Auth.js 中由AuthModule类统一实现。下面结合各函数文档与实现源码逐一展开。3.1 puter.auth.signIn()发起登录这是整个认证模块最复杂的一个方法。它的签名是puter.auth.signIn() puter.auth.signIn(options)options 参数options为可选对象包含以下两个布尔属性属性默认说明attempt_temp_user_creationfalse是否让 Puter 自动创建一个临时用户。适合希望快速引入用户而无需其立即注册的场景——用户以后随时可以正式注册/升级账号request_authfalse即使你的站点已经持有该用户的令牌也强制弹窗让用户重新选择账号。Puter 对访问过的站点通常会跳过这一步因此该选项适合做显式的切换账号switch account按钮从源码Auth.js可以看到这两个选项最终会被拼进弹窗 URL 的查询参数里${defaultGUIOrigin}/action/sign-in?embedded_in_popuptruemsg_id...attempt_temp_user_creationtruerequest_authtrue返回值signIn()返回一个Promise成功时 resolve 为一个SignInResult对象。依据 Auth.js 的 JSDoc 定义其结构为success布尔值登录是否成功token认证令牌app_uid可选应用的唯一标识username可选登录用户的用户名error可选失败时的错误信息msg可选关于登录过程的附加信息。返回对象更详细的说明可参考 signinresult.md。拒绝Rejection场景signIn()在下列情况下会 reject错误对象包含error错误码与人类可读的msg错误码触发条件popup_blocked登录弹窗被浏览器拦截。通常是因为signIn()没有在用户动作如 click中调用auth_window_closed用户未完成登录就关闭了登录窗口或取消了授权对话框not_available_in_app在运行于 Puter 内部的 App 中调用signIn()。App 已随启动会话获得令牌无需弹窗应改用getUser()读取当前用户最后一类场景在源码中有直接体现Auth.js 首先检查puter.env app命中即返回not_available_in_app。原文档还提示Promise 也可能 reject 认证窗口自身返回的失败响应。底层认证流程源码视角阅读 Auth.js 可以还原一次完整登录的实现细节SDK 生成signinsessioncrypto.randomUUID()与自增的msg_id拼出 GUI 的/action/sign-in授权地址若当前文档具有用户激活hasUserActivation()立即用 openAuthPopup 打开一个居中、600×700的弹窗否则先展示一个 PuterDialog 同意对话框让用户在点击它时获得浏览器所需的用户手势再从该点击中打开弹窗监听message事件校验四个条件后才接受令牌消息e.origin必须是puter.defaultGUIOrigin、消息来源必须是本次打开的弹窗窗口event.source对齐、消息类型必须是puter.token、且msg_id必须匹配本次尝试——这防止了同域其他 frame 伪造令牌投递成功后调用puter.setAuthToken(token)保存令牌并 resolve若浏览器返回null弹窗被拦截→ rejectpopup_blocked用定时器轮询popup.closed检测用户关闭窗口 → rejectauth_window_closed在crossOriginIsolated跨域隔离模式下不依赖 postMessage而是轮询后端${defaultAPIOrigin}/login/wait接口携带{ session: signinsession }拿到auth_token后保存并 resolve。用户激活探测本身在 auth-popup.js 中实现优先使用navigator.userActivationAPI对不支持该 API 的浏览器通过尝试打开一个 1×1 的屏幕外测试窗口来探测——能打开说明有用户手势。3.2 puter.auth.isSignedIn()检测登录状态puter.auth.isSignedIn()无参数返回布尔值true表示已登录false表示未登录。原文档示例html body script srchttps://js.puter.com/v2//script script puter.print(Sign in status: ${puter.auth.isSignedIn()}); /script /body /html该实现非常轻量Auth.js本质上就是判断 SDK 内存中是否持有authToken。可交互示例见 auth-is-signed-in.html。3.3 puter.auth.getUser()获取用户信息puter.auth.getUser()无参数返回一个 resolve 为User对象的Promise。原文档示例html body script srchttps://js.puter.com/v2//script script puter.auth.getUser().then(function(user) { puter.print(JSON.stringify(user)); }); /script /body /html值得注意的实现细节若当前没有登录令牌getUser()会同步抛出{ status: 401, message: Unauthorized }Auth.js这是为了向后兼容而预演服务端必然失败的响应有令牌时它通过 XHR 请求后端/whoami接口获取用户信息SDK 还提供一个同源的、仅 Promise 风格的方法whoami()Auth.js底层同样走/whoami未登录时同样 rejectUnauthorized——它不属于 Auth.md 文档主表可作为需要纯 Promise 语法时的额外选择。User对象字段依据 Auth.js 的类型定义字段类型说明uuidstring用户唯一标识usernamestring用户名email_confirmedboolean / number邮箱是否已验证actual_free_storagenumber用户的免费存储额度app_namestring当前活跃应用created_tsnumber账号创建时间unix 秒。仅对用户自己的令牌返回代表用户执行操作的 App 拿不到它is_tempboolean账号是否为临时账号last_activity_tsnumber用户最后活跃时间戳paid_storagenumber付费存储额度referral_codestring用户邀请码requires_email_confirmationboolean / number账号是否需要邮箱确认subscribedboolean用户是否已订阅otp、feature_flags、hasDevAccountAccess混合视部署与账号类型返回字段的权威说明见 user.md。可交互示例见 auth-get-user.html。3.4 puter.auth.signOut()退出登录puter.auth.signOut()无参数、无返回值将用户从当前应用中登出。原文档示例html body script srchttps://js.puter.com/v2//script script puter.auth.signOut(); /script /body /html实现上Auth.js它调用puter.resetAuthToken()即丢弃本地保存的认证令牌。可交互示例见 auth-sign-out.html。3.5 puter.auth.getMonthlyUsage()当月用量puter.auth.getMonthlyUsage()无参数返回 resolve 为MonthlyUsage对象的Promise描述用户在 Puter 生态内的当月资源用量。原文档特别提示两个事实用量数据仅作用于调用它的应用本身scoped to the calling app资源金额以microcents百万分之一美分计量例如$0.01记作1,000,000。原文档示例html body script srchttps://js.puter.com/v2//script script puter.auth.getMonthlyUsage().then(function (usage) { puter.print(pre${JSON.stringify(usage, null, 2)}/pre); }); /script /body /html在源码中该方法请求后端/metering/usage接口Auth.js。MonthlyUsage的结构Auth.jsallowanceInfo用户的资源配额与消耗含monthUsageAllowance当月总配额、remaining剩余配额与可选unit当服务端把所有金额字段换算为 credits 显示时为credits否则为原始金额appTotals按应用 id 聚合的总用量count为调用次数、total为总资源消耗usage按 API 名称聚合的用量cost总消耗、count调用次数、units计量单位如 AI 调用的 token、FS 操作的字节。对应文档见 monthlyusage.md可交互示例见 auth-get-monthly-usage.html。3.6 puter.auth.getDetailedAppUsage(appId)应用级详细用量puter.auth.getDetailedAppUsage(appId)唯一的必填参数appIdString为应用 id。返回 resolve 为DetailedAppUsage对象的Promise。注意事项原文档明确用户只能查看其曾经访问过的应用的用量用量数据仅作用于调用它的应用本身。原文档示例html body script srchttps://js.puter.com/v2//script script puter.auth.getDetailedAppUsage(appId).then(function (result) { puter.print(pre${JSON.stringify(result, null, 2)}/pre); }); /script /body /html源码实现Auth.js会对缺失的appId直接抛出Error(appId is required)然后请求/metering/usage/${appId}。返回的DetailedAppUsage定义为{ total: number } Recordstring, APIUsageAuth.js即一个总额total加上每个 API 名称的用量明细金额同样以 microcents 计量。对应文档见 detailedappusage.md。四、平台适用性对照六个函数在不同运行平台上的可用范围并不相同。各函数文档的 frontmatter 中标注了platforms汇总如下函数Websites外部网页AppsPuter 内应用Node.jsWorkerssignIn()✔✘rejectnot_available_in_app✘✘signOut()✔✔✘✘isSignedIn()✔✔✔✔getUser()✔✔✔✔getMonthlyUsage()✔✔✔✔getDetailedAppUsage()✔✔✔✔可以看出signIn()是仅限外部网页的方法——Puter 内运行的应用由启动它的会话直接授予令牌无需也不能再走弹窗而signOut()适用于网页与 Puter 内应用其余四个查询类方法则在网页、应用、Node.js、Worker 四种环境下都可用。值得补充的是源码注释Auth.js解释了为何 App 模式拒绝弹窗App 的令牌来自启动它的 GUI若走弹窗流程令牌会被投递到启动 URL 指定的api_origin——在 App 模式下该 origin 是 URL 提供的存在被恶意指定的风险。五、认证流程与安全设计小结结合文档与源码Puter 网页认证可归纳为一条完整链路入口外部站点在用户手势中调用puter.auth.signIn(options)弹窗SDK 检测用户激活后打开指向 GUI/action/sign-in的居中弹窗auth-popup.js无激活时先弹同意对话框授权与令牌投递用户在 Puter 侧完成登录后认证窗口通过postMessage回传puter.token消息SDK 通过origin 白名单 event.source 窗口对齐 msg_id 绑定三重校验后调用puter.setAuthToken()保存令牌跨域隔离模式改为轮询/login/wait后续 API此后 FS、KV、AI 等 Puter.js API 都会自动携带该令牌查询身份用getUser()退出则signOut()丢弃令牌。服务端侧/whoami等认证相关能力由 AuthController.ts 与 AuthService.ts 实现SDK 的网络层位于 networkUtils.js。如果你要为自己的 Puter 部署提供前端认证支持自托管文档 说明了如何把 Puter 部署起来再将页面中的 SDK 指向你自己的实例。六、深入阅读与相关资源认证总览Auth.md六个函数文档见 signIn.md、signOut.md、isSignedIn.md、getUser.md、getMonthlyUsage.md、getDetailedAppUsage.md返回对象文档signinresult.md、user.md、monthlyusage.md、detailedappusage.md可运行的 playground 示例auth-sign-in.html、auth-sign-out.html、auth-is-signed-in.html、auth-get-user.html、auth-get-monthly-usage.htmlSDK 源码Auth.js模块实现与全部类型定义、auth-popup.js弹窗与用户激活探测、index.js令牌保存/重置与全局集成类型声明index.d.ts编译产物供 TypeScript 使用者参考服务端实现AuthController.ts、AuthService.ts。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Puter 认证 API 实战：用 Puter.js 在网页应用中接入 Puter 账号体系
Puter 认证 API 实战用 Puter.js 在网页应用中接入 Puter 账号体系【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puterPuter 是一个开源、可自托管的云端计算机平台而puter.auth是 Puter.js SDK 中负责身份认证的核心模块。它让第三方网页应用能够借助用户的 Puter 账号完成登录从而解锁后续的 FS 文件系统、KV 存储、AI 能力等一系列 Puter.js API。本指南以仓库中 Auth.md 为骨架结合 SDK 源码 与全部六个认证函数文档讲解 sign-in / sign-out、登录状态检测、用户信息拉取与用量查询的完整用法、参数语义、平台差异与底层认证原理读完即可在你的应用中接入 Puter 账号认证。一、Puter 认证 API 解决什么问题Puter.js 提供多个面向网页应用的高级 API文件系统、KV、AI、Hosting 等而这些 API 几乎都要求调用者是已认证用户。认证 API 就是打通这一步的入口它支持Sign In发起登录流程让用户用 Puter 账号授权你的应用Check Sign In检测当前用户是否已登录Get User获取当前用户的基础信息Sign Out让用户退出你的应用用量查询查询用户当前的月度资源用量与应用维度的详细用量统计。一个关键设计理念在 signIn.md 中写得很清楚Puter 中几乎所有核心方法都会自动处理认证。puter.auth这套方法只在你想手动驱动认证流程时才必须出现例如构建自定义登录界面或切换账号按钮。自动认证 vs 手动认证理解两套运行模型至关重要运行在 Puter 内部的 App应用本身就是被用户从 Puter 桌面启动的Puter 会话在启动那一刻就把令牌交给了应用所以应用天然处于已登录状态。对这类应用直接调用puter.auth.getUser()读取当前用户即可不需要也不能再走弹窗登录流程外部网页Website站点通过script srchttps://js.puter.com/v2//script引入 SDK 后通常没有用户令牌此时需要通过puter.auth.signIn()弹窗授权来获得令牌。从源码 index.js 的注释可以看出SDK 内部把这类随应用令牌而来的说明与puter.auth.getUser()明确关联整套设计正是围绕上述两种模型展开。二、快速上手在网页中发起登录signIn()会打开一个弹窗进入 Puter 的认证界面并在用户完成登录后 resolve。原文档提供了一个可以直接运行的完整 HTML 示例html body script srchttps://js.puter.com/v2//script button idsign-inSign in/button script // Because signIn() opens a popup window, it must be called from a user action. document.getElementById(sign-in).addEventListener(click, async () { // signIn() will resolve when the user has signed in. await puter.auth.signIn().then((res) { puter.print(Signed inbr JSON.stringify(res)); }); }); /script /body /html两个必须记住的要点必须由用户动作触发。signIn()打开的是浏览器弹窗浏览器通常会拦截非用户手势触发的弹窗。所以它必须挂在 click 等事件回调里或任何有用户激活的时机Promise 语义。signIn()返回一个Promise用户完成登录后 resolve 为一个SignInResult对象如果流程失败弹窗被拦截、用户关闭窗口等则 reject 并携带错误码与可读信息详见下文signIn()小节。该页面同样存在于仓库的 playground 可交互示例中auth-sign-in.html你可以边改边跑体验真实流程。三、六个认证函数逐一详解原文档 Auth.md 的 Functions 部分列出了开箱即用的六个函数。下表给出了函数、说明与仓库内对应文档的映射函数作用详细文档puter.auth.signIn()登录用户signIn.mdputer.auth.signOut()退出当前用户signOut.mdputer.auth.isSignedIn()判断用户是否已登录isSignedIn.mdputer.auth.getUser()获取当前用户信息getUser.mdputer.auth.getMonthlyUsage()获取当月资源用量getMonthlyUsage.mdputer.auth.getDetailedAppUsage()获取某个应用的详细用量getDetailedAppUsage.md这六个方法在 Auth.js 中由AuthModule类统一实现。下面结合各函数文档与实现源码逐一展开。3.1 puter.auth.signIn()发起登录这是整个认证模块最复杂的一个方法。它的签名是puter.auth.signIn() puter.auth.signIn(options)options 参数options为可选对象包含以下两个布尔属性属性默认说明attempt_temp_user_creationfalse是否让 Puter 自动创建一个临时用户。适合希望快速引入用户而无需其立即注册的场景——用户以后随时可以正式注册/升级账号request_authfalse即使你的站点已经持有该用户的令牌也强制弹窗让用户重新选择账号。Puter 对访问过的站点通常会跳过这一步因此该选项适合做显式的切换账号switch account按钮从源码Auth.js可以看到这两个选项最终会被拼进弹窗 URL 的查询参数里${defaultGUIOrigin}/action/sign-in?embedded_in_popuptruemsg_id...attempt_temp_user_creationtruerequest_authtrue返回值signIn()返回一个Promise成功时 resolve 为一个SignInResult对象。依据 Auth.js 的 JSDoc 定义其结构为success布尔值登录是否成功token认证令牌app_uid可选应用的唯一标识username可选登录用户的用户名error可选失败时的错误信息msg可选关于登录过程的附加信息。返回对象更详细的说明可参考 signinresult.md。拒绝Rejection场景signIn()在下列情况下会 reject错误对象包含error错误码与人类可读的msg错误码触发条件popup_blocked登录弹窗被浏览器拦截。通常是因为signIn()没有在用户动作如 click中调用auth_window_closed用户未完成登录就关闭了登录窗口或取消了授权对话框not_available_in_app在运行于 Puter 内部的 App 中调用signIn()。App 已随启动会话获得令牌无需弹窗应改用getUser()读取当前用户最后一类场景在源码中有直接体现Auth.js 首先检查puter.env app命中即返回not_available_in_app。原文档还提示Promise 也可能 reject 认证窗口自身返回的失败响应。底层认证流程源码视角阅读 Auth.js 可以还原一次完整登录的实现细节SDK 生成signinsessioncrypto.randomUUID()与自增的msg_id拼出 GUI 的/action/sign-in授权地址若当前文档具有用户激活hasUserActivation()立即用 openAuthPopup 打开一个居中、600×700的弹窗否则先展示一个 PuterDialog 同意对话框让用户在点击它时获得浏览器所需的用户手势再从该点击中打开弹窗监听message事件校验四个条件后才接受令牌消息e.origin必须是puter.defaultGUIOrigin、消息来源必须是本次打开的弹窗窗口event.source对齐、消息类型必须是puter.token、且msg_id必须匹配本次尝试——这防止了同域其他 frame 伪造令牌投递成功后调用puter.setAuthToken(token)保存令牌并 resolve若浏览器返回null弹窗被拦截→ rejectpopup_blocked用定时器轮询popup.closed检测用户关闭窗口 → rejectauth_window_closed在crossOriginIsolated跨域隔离模式下不依赖 postMessage而是轮询后端${defaultAPIOrigin}/login/wait接口携带{ session: signinsession }拿到auth_token后保存并 resolve。用户激活探测本身在 auth-popup.js 中实现优先使用navigator.userActivationAPI对不支持该 API 的浏览器通过尝试打开一个 1×1 的屏幕外测试窗口来探测——能打开说明有用户手势。3.2 puter.auth.isSignedIn()检测登录状态puter.auth.isSignedIn()无参数返回布尔值true表示已登录false表示未登录。原文档示例html body script srchttps://js.puter.com/v2//script script puter.print(Sign in status: ${puter.auth.isSignedIn()}); /script /body /html该实现非常轻量Auth.js本质上就是判断 SDK 内存中是否持有authToken。可交互示例见 auth-is-signed-in.html。3.3 puter.auth.getUser()获取用户信息puter.auth.getUser()无参数返回一个 resolve 为User对象的Promise。原文档示例html body script srchttps://js.puter.com/v2//script script puter.auth.getUser().then(function(user) { puter.print(JSON.stringify(user)); }); /script /body /html值得注意的实现细节若当前没有登录令牌getUser()会同步抛出{ status: 401, message: Unauthorized }Auth.js这是为了向后兼容而预演服务端必然失败的响应有令牌时它通过 XHR 请求后端/whoami接口获取用户信息SDK 还提供一个同源的、仅 Promise 风格的方法whoami()Auth.js底层同样走/whoami未登录时同样 rejectUnauthorized——它不属于 Auth.md 文档主表可作为需要纯 Promise 语法时的额外选择。User对象字段依据 Auth.js 的类型定义字段类型说明uuidstring用户唯一标识usernamestring用户名email_confirmedboolean / number邮箱是否已验证actual_free_storagenumber用户的免费存储额度app_namestring当前活跃应用created_tsnumber账号创建时间unix 秒。仅对用户自己的令牌返回代表用户执行操作的 App 拿不到它is_tempboolean账号是否为临时账号last_activity_tsnumber用户最后活跃时间戳paid_storagenumber付费存储额度referral_codestring用户邀请码requires_email_confirmationboolean / number账号是否需要邮箱确认subscribedboolean用户是否已订阅otp、feature_flags、hasDevAccountAccess混合视部署与账号类型返回字段的权威说明见 user.md。可交互示例见 auth-get-user.html。3.4 puter.auth.signOut()退出登录puter.auth.signOut()无参数、无返回值将用户从当前应用中登出。原文档示例html body script srchttps://js.puter.com/v2//script script puter.auth.signOut(); /script /body /html实现上Auth.js它调用puter.resetAuthToken()即丢弃本地保存的认证令牌。可交互示例见 auth-sign-out.html。3.5 puter.auth.getMonthlyUsage()当月用量puter.auth.getMonthlyUsage()无参数返回 resolve 为MonthlyUsage对象的Promise描述用户在 Puter 生态内的当月资源用量。原文档特别提示两个事实用量数据仅作用于调用它的应用本身scoped to the calling app资源金额以microcents百万分之一美分计量例如$0.01记作1,000,000。原文档示例html body script srchttps://js.puter.com/v2//script script puter.auth.getMonthlyUsage().then(function (usage) { puter.print(pre${JSON.stringify(usage, null, 2)}/pre); }); /script /body /html在源码中该方法请求后端/metering/usage接口Auth.js。MonthlyUsage的结构Auth.jsallowanceInfo用户的资源配额与消耗含monthUsageAllowance当月总配额、remaining剩余配额与可选unit当服务端把所有金额字段换算为 credits 显示时为credits否则为原始金额appTotals按应用 id 聚合的总用量count为调用次数、total为总资源消耗usage按 API 名称聚合的用量cost总消耗、count调用次数、units计量单位如 AI 调用的 token、FS 操作的字节。对应文档见 monthlyusage.md可交互示例见 auth-get-monthly-usage.html。3.6 puter.auth.getDetailedAppUsage(appId)应用级详细用量puter.auth.getDetailedAppUsage(appId)唯一的必填参数appIdString为应用 id。返回 resolve 为DetailedAppUsage对象的Promise。注意事项原文档明确用户只能查看其曾经访问过的应用的用量用量数据仅作用于调用它的应用本身。原文档示例html body script srchttps://js.puter.com/v2//script script puter.auth.getDetailedAppUsage(appId).then(function (result) { puter.print(pre${JSON.stringify(result, null, 2)}/pre); }); /script /body /html源码实现Auth.js会对缺失的appId直接抛出Error(appId is required)然后请求/metering/usage/${appId}。返回的DetailedAppUsage定义为{ total: number } Recordstring, APIUsageAuth.js即一个总额total加上每个 API 名称的用量明细金额同样以 microcents 计量。对应文档见 detailedappusage.md。四、平台适用性对照六个函数在不同运行平台上的可用范围并不相同。各函数文档的 frontmatter 中标注了platforms汇总如下函数Websites外部网页AppsPuter 内应用Node.jsWorkerssignIn()✔✘rejectnot_available_in_app✘✘signOut()✔✔✘✘isSignedIn()✔✔✔✔getUser()✔✔✔✔getMonthlyUsage()✔✔✔✔getDetailedAppUsage()✔✔✔✔可以看出signIn()是仅限外部网页的方法——Puter 内运行的应用由启动它的会话直接授予令牌无需也不能再走弹窗而signOut()适用于网页与 Puter 内应用其余四个查询类方法则在网页、应用、Node.js、Worker 四种环境下都可用。值得补充的是源码注释Auth.js解释了为何 App 模式拒绝弹窗App 的令牌来自启动它的 GUI若走弹窗流程令牌会被投递到启动 URL 指定的api_origin——在 App 模式下该 origin 是 URL 提供的存在被恶意指定的风险。五、认证流程与安全设计小结结合文档与源码Puter 网页认证可归纳为一条完整链路入口外部站点在用户手势中调用puter.auth.signIn(options)弹窗SDK 检测用户激活后打开指向 GUI/action/sign-in的居中弹窗auth-popup.js无激活时先弹同意对话框授权与令牌投递用户在 Puter 侧完成登录后认证窗口通过postMessage回传puter.token消息SDK 通过origin 白名单 event.source 窗口对齐 msg_id 绑定三重校验后调用puter.setAuthToken()保存令牌跨域隔离模式改为轮询/login/wait后续 API此后 FS、KV、AI 等 Puter.js API 都会自动携带该令牌查询身份用getUser()退出则signOut()丢弃令牌。服务端侧/whoami等认证相关能力由 AuthController.ts 与 AuthService.ts 实现SDK 的网络层位于 networkUtils.js。如果你要为自己的 Puter 部署提供前端认证支持自托管文档 说明了如何把 Puter 部署起来再将页面中的 SDK 指向你自己的实例。六、深入阅读与相关资源认证总览Auth.md六个函数文档见 signIn.md、signOut.md、isSignedIn.md、getUser.md、getMonthlyUsage.md、getDetailedAppUsage.md返回对象文档signinresult.md、user.md、monthlyusage.md、detailedappusage.md可运行的 playground 示例auth-sign-in.html、auth-sign-out.html、auth-is-signed-in.html、auth-get-user.html、auth-get-monthly-usage.htmlSDK 源码Auth.js模块实现与全部类型定义、auth-popup.js弹窗与用户激活探测、index.js令牌保存/重置与全局集成类型声明index.d.ts编译产物供 TypeScript 使用者参考服务端实现AuthController.ts、AuthService.ts。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考