Bearer Auth 中间件

Bearer Auth 中间件会通过校验请求头中的 API 令牌来提供身份验证功能。 访问端点的 HTTP 客户端需要添加 Authorization 请求头，并设置为 Bearer {token}。

在终端中使用 curl 时类似如下：

curl -H 'Authorization: Bearer honoiscool' http://localhost:8787/auth/page

导入

import { Hono } from 'hono'
import { bearerAuth } from 'hono/bearer-auth'

用法

NOTE

令牌必须匹配正则 /[A-Za-z0-9._~+/-]+=*/，否则会返回 400 错误。该正则既兼容 URL 安全的 Base64，也兼容标准 Base64 编码的 JWT。中间件并不要求 Bearer 令牌一定是 JWT，只需符合上述正则即可。

const app = new Hono()

const token = 'honoiscool'

app.use('/api/*', bearerAuth({ token }))

app.get('/api/page', (c) => {
  return c.json({ message: 'You are authorized' })
})

若要将认证限定在特定的路由与方法组合：

const app = new Hono()

const token = 'honoiscool'

app.get('/api/page', (c) => {
  return c.json({ message: 'Read posts' })
})

app.post('/api/page', bearerAuth({ token }), (c) => {
  return c.json({ message: 'Created post!' }, 201)
})

如果要实现多种令牌（例如：任意有效令牌可读取，但创建/更新/删除需特权令牌）：

const app = new Hono()

const readToken = 'read'
const privilegedToken = 'read+write'
const privilegedMethods = ['POST', 'PUT', 'PATCH', 'DELETE']

app.on('GET', '/api/page/*', async (c, next) => {
  // 有效令牌列表
  const bearer = bearerAuth({ token: [readToken, privilegedToken] })
  return bearer(c, next)
})
app.on(privilegedMethods, '/api/page/*', async (c, next) => {
  // 单个特权令牌
  const bearer = bearerAuth({ token: privilegedToken })
  return bearer(c, next)
})

// 定义 GET、POST 等处理器

若想自行验证令牌值，可以指定 verifyToken 选项；返回 true 即表示通过。

const app = new Hono()

app.use(
  '/auth-verify-token/*',
  bearerAuth({
    verifyToken: async (token, c) => {
      return token === 'dynamic-token'
    },
  })
)

选项

required token：string | string[]

用于校验传入 Bearer 令牌的字符串。

optional realm：string

作为 WWW-Authenticate 挑战头一部分返回的领域名称，默认值为 ""。 更多信息：https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate#directives

optional prefix：string

Authorization 头部值的前缀（也称为 schema），默认值为 "Bearer"。

optional headerName：string

要检查的请求头名称，默认是 Authorization。

optional hashFunction：Function

用于处理哈希并安全比较认证令牌的函数。

optional verifyToken：(token: string, c: Context) => boolean | Promise<boolean>

自定义的令牌验证函数。

optional noAuthenticationHeaderMessage：string | object | MessageFunction

MessageFunction 的签名为 (c: Context) => string | object | Promise<string | object>，在请求未携带认证头时返回自定义消息。

optional invalidAuthenticationHeaderMessage：string | object | MessageFunction

当认证头无效时返回的自定义消息。

optional invalidTokenMessage：string | object | MessageFunction

当令牌无效时返回的自定义消息。