与 Freebuff 签约

@freebuff/auth 让有Freebuff帐号的人进入您的网站: Google、 GitHub 或 Apple 通过 Freebuff , 没有配置, 没有 秘密要保密 秘密要保密 您的服务器了解访问者是谁( Q)sub,并与其 同意他们的电子邮件、姓名和图片)。 它从来没有看到他们的密码, 提供商证书或Freebuff账户代号.

这是标准的 OpenID 连接(授权代码 + PKCE),带有 服务器侧会话,并随处运行 fetch 和网络加密 : Cloudflare Workers, Bun, Node 20+, Deno and Next.js. 互联网档案馆的存檔,存档日期2013-12-22.

1. 获得客户身份

每个项目环境都有自己的公共客户身份证,由 project的创建者针对精确的回调 URL :

# Production: the site's real origin
npx @freebuff/auth register --project notes --name "Notes" \
  --environment production --redirect-uri https://notes.example/auth/freebuff/callback

# Local development: any port on localhost
npx @freebuff/auth register --project notes --name "Notes" \
  --environment development --redirect-uri http://localhost:8787/auth/freebuff/callback

它以您的 Freebuff CLI 登录方式( 或 FREEBUFF_TOKEN和 指纹 FREEBUFF_CLIENT_ID以及你网站的出处 这里有配置 也不是一个秘密。 重新运行是安全的; 添加一个 新设 --redirect-uri 当网站获得新域名时.

2. 上马

云旗工人、邦克、德诺、霍诺

包好你的接线员 它服务于四个认证路线,维持会话 新鲜的,和制作 getUser 可在内部任何地方使用:

import { createFreebuffAuth } from '@freebuff/auth'

const auth = createFreebuffAuth({
  clientId: env.FREEBUFF_CLIENT_ID,
  baseUrl: 'https://notes.example', // your canonical origin
})

export default {
  fetch: auth.wrap(async (request) => {
    const user = await auth.getUser(request)
    if (new URL(request.url).pathname.startsWith('/api/') && !user) {
      return Response.json({ error: 'Sign in required' }, { status: 401 })
    }
    return app.fetch(request)
  }),
}

见 examples/cloudflare-worker.ts (静态) 资产+API)和 examples/hono.ts。 。 。 .

Next.js (App路由器) (英语)

// lib/freebuff.ts
import { createFreebuffNext } from '@freebuff/auth/next'
export const freebuff = createFreebuffNext({
  clientId: process.env.FREEBUFF_CLIENT_ID!,
  baseUrl: process.env.APP_ORIGIN!,
})

// app/auth/freebuff/[...freebuff]/route.ts
export const { GET, POST } = freebuff.handlers

// proxy.ts (middleware.ts before Next 16): refreshes sessions before render
export const proxy = freebuff.proxy
export const config = { matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'] }

// Any Server Component, Route Handler or Server Action
const user = await freebuff.getUser()

见 examples/nextjs。 。 。 .

按钮和客户端状态( 反应)

import { SignInWithFreebuff, SignOutButton, useFreebuffUser } from '@freebuff/auth/react'

<SignInWithFreebuff />                 // link to /auth/freebuff/signin, returns here
<SignOutButton returnTo="/" />         // a POST form; sign-out is never a link
const { user, isLoading } = useFreebuffUser() // reads /auth/freebuff/session

无反应: 链接到 /auth/freebuff/signin?returnTo=/somewhere签名 与 <form method="post" action="/auth/freebuff/signout">,并读 GET /auth/freebuff/session → { "user": { ... } | null }。 。 。 .

用户

interface FreebuffUser {
  sub: string            // always; stable for this visitor in this project
  email?: string         // `email` scope, when present
  email_verified?: boolean
  name?: string          // `profile` scope, when set
  picture?: string       // https URL
}

• 键入您的数据 sub。 。 。 . 你的项目也一样 开发和生产客户,以及所有其他项目的不同, 网站无法与访客联系 它永远不会改变.
• 电子邮件是配置数据,不是身份. 它可以改变,可能缺席,以及 可能无法核实。 从不通过电子邮件合并或查询账户 .
• 请求少用 scopes: ['openid'] (刚刚) sub)或(或) ['openid', 'email']。 。 。 .

会议和安全

• 你的项目没有秘密. Freebuff 签名符; 您 服务器用 Freebuff 的公钥验证它们( 已选中; 无请求) 网络呼叫.
• 这届会议是一场 __Host-freebuff_session 饼干: HttpOnly, (中文(简体) ), Secure, (中文(简体) ), SameSite=Lax仅限主机。 它有一个一小时的进入符和一个刷新 符号 。 托肯斯从未达到页面JavaScript.
• 刷新符号在每次使用时旋转 。 一个被窃取的、已经使用的刷新符号 结束整个会话。 平行请求是安全的:收到相同的请求 继任者.
• 会期最长可达30天无活动,最多可达90天,然后 访客再次签名(通常是一击:Freebuff记得同意).
• 签出 POST,只有同源;它撤销了Freebuff的会话.
• 如果禁用 Freebuff 账户, 或项目禁用, 则其会话 在一个小时之内(进入-连接寿命)停止,不能更新.
• 登录使用 PKCE, state 财务报告和审定财务报表 nonce固定的发行者 准确的回调URL, 和RFC 9207 发行商检查。 浏览器拒绝托肯请求 .

getUser 只在内部刷新 wrap,下一个.js proxy,或 /auth/freebuff/session 路由,因为更新的会话必须到达 浏览器或它的下个刷新 看起来像偷窃。 在其他地方,它验证 当前访问符和返回 null 一旦它过期.

地方发展

使用您的项目 发展 客户身份和 allowInsecureLocalhost: true 带有 http://localhost:<port> 或者说 http://127.0.0.1:<port> baseUrl. 开发客户接受任何港口 在已注册回回路主机上。 永远不要使用开发客户端或 allowInsecureLocalhost 在生产中.

选项

将整合此软件包的 AI 编码代理器改为: AGENTS.md。 。 。 .