JWT Authentication Helper

JWTは、ウェブアプリケーションで認証と認可のために広く使用されているトークンです。このヘルパーは、JWTのエンコード、デコード、署名、検証のための機能を提供します。

まず、このヘルパーを使うには、次のようにインポートします。

import { decode, sign, verify } from 'hono/jwt'

`sign()`関数

この関数は、指定されたアルゴリズムとシークレットを使用してペイロードを署名し、JWTトークンを生成します。

const payload = {
  sub: 'user123',
  role: 'admin',
}
const secret = 'mySecretKey'
const token = await sign(payload, secret)

payloadは、署名されるJWTのペイロードです。
secretは、JWT検証や署名に使用される秘密鍵です。
algは、JWT署名や検証に使用されるアルゴリズムで、デフォルトはHS256です。

`verify()`関数

この関数は、JWTトークンが本物で有効であるかどうかを確認します。トークンが変更されていないことを確認し、ペイロード検証を追加した場合にのみ有効性をチェックします。

const tokenToVerify = 'token'
const secretKey = 'mySecretKey'

const decodedPayload = await verify(tokenToVerify, secretKey)
console.log(decodedPayload)

tokenは、検証されるJWTトークンです。
secretは、JWT検証や署名に使用される秘密鍵です。
algは、JWT署名や検証に使用されるアルゴリズムで、デフォルトはHS256です。

`decode()`関数

この関数は、署名検証を行わずにJWTトークンをデコードします。トークンからヘッダーとペイロードを抽出して返します。

const tokenToDecode = 'eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiAidXNlcjEyMyIsICJyb2xlIjogImFkbWluIn0.JxUwx6Ua1B0D1B0FtCrj72ok5cm1Pkmr_hL82sd7ELA'

const { header, payload } = decode(tokenToDecode)

console.log('Decoded Header:', header)
console.log('Decoded Payload:', payload)

tokenは、デコードされるJWTトークンです。

decode関数を使用すると、検証を行わずにJWTトークンのヘッダーとペイロードを確認できます。これは、デバッグやJWTトークンから情報を抽出するのに便利です。

ペイロード検証

JWTトークンを検証する際、次のペイロード検証が行われます。

exp：トークンの有効期限が切れていないことを確認します。
nbf：トークンが指定された時間より前に使用されていないことを確認します。
iat：トークンが未来に発行されていないことを確認します。

検証時にこれらのチェックを行う場合は、JWTペイロードにこれらのフィールドをオブジェクトとして含めてください。

カスタムエラータイプ

このモジュールでは、JWT関連のエラーを処理するためのカスタムエラータイプも定義されています。

JwtAlgorithmNotImplemented：要求されたJWTアルゴリズムが実装されていないことを示します。
JwtTokenInvalid：JWTトークンが無効であることを示します。
JwtTokenNotBefore：トークンが有効な日付より前に使用されていることを示します。
JwtTokenExpired：トークンの有効期限が切れていることを示します。
JwtTokenIssuedAt：トークンの「iat」クレームが正しくないことを示します。
JwtTokenSignatureMismatched：トークンの署名が一致しないことを示します。

サポートされているアルゴリズムタイプ

このモジュールは、次のJWT暗号化アルゴリズムをサポートしています。

HS256：SHA-256を使用したHMAC
HS384：SHA-384を使用したHMAC
HS512：SHA-512を使用したHMAC

JWTは、ウェブアプリケーションでユーザー認証と認可を管理するための強力な方法です。このヘルパーを使用すると、JWTの生成、検証、デコードを簡単に行うことができます。

midorinotanuki

HonoRequest

HonoRequestは、Honoフレームワークにおいて、HTTPリクエストの情報を扱うオブジェクトです。c.reqを通じてアクセスできます。

`param()`メソッド

param()メソッドは、URLのパスパラメータの値を取得するために使用します。

// パスパラメータの取得
app.get('/entry/:id', (c) => {
  const id = c.req.param('id')
  // ...
})

// 複数のパスパラメータを一度に取得
app.get('/entry/:id/comment/:commentId', (c) => {
  const { id, commentId } = c.req.param()
  // ...
})

`query()`メソッド

query()メソッドは、クエリ文字列のパラメータの値を取得するために使用します。

// クエリパラメータの取得
app.get('/search', (c) => {
  const query = c.req.query('q')
  // ...
})

// 複数のクエリパラメータを一度に取得
app.get('/search', (c) => {
  const { q, limit, offset } = c.req.query()
  // ...
})

`queries()`メソッド

queries()メソッドは、同じ名前の複数のクエリ文字列パラメータの値を取得するために使用します。

app.get('/search', (c) => {
  // tagsは文字列の配列になります
  const tags = c.req.queries('tags')
  // ...
})

`header()`メソッド

header()メソッドは、リクエストヘッダの値を取得するために使用します。

app.get('/', (c) => {
  const userAgent = c.req.header('User-Agent')
  // ...
})

`parseBody()`メソッド

parseBody()メソッドは、multipart/form-dataまたはapplication/x-www-form-urlencoded形式のリクエストボディを解析するために使用します。

app.post('/entry', async (c) => {
  const body = await c.req.parseBody()
  // ...
})

parseBody()メソッドは、以下のような動作をサポートしています。

単一ファイルのアップロード
複数ファイルのアップロード
同じ名前の複数ファイルのアップロード

`json()`メソッド

json()メソッドは、application/json形式のリクエストボディを解析するために使用します。

app.post('/entry', async (c) => {
  const body = await c.req.json()
  // ...
})

`text()`メソッド

text()メソッドは、text/plain形式のリクエストボディを解析するために使用します。

app.post('/entry', async (c) => {
  const body = await c.req.text()
  // ...
})

`arrayBuffer()`メソッド

arrayBuffer()メソッドは、リクエストボディをArrayBufferとして解析するために使用します。

app.post('/entry', async (c) => {
  const body = await c.req.arrayBuffer()
  // ...
})

`valid()`メソッド

valid()メソッドは、バリデーションが適用されたデータを取得するために使用します。

app.post('/posts', (c) => {
  const { title, body } = c.req.valid('form')
  // ...
})

使用可能なターゲットは、form、json、query、header、cookie、paramなどがあります。

`routePath()`メソッド

routePath()メソッドは、登録されたパスを取得するために使用します。

app.get('/posts/:id', (c) => {
  return c.json({ path: c.req.routePath })
})

`matchedRoutes()`メソッド

matchedRoutes()メソッドは、マッチしたルートを取得するために使用します。デバッグに役立ちます。

app.use(async function logger(c, next) {
  await next()
  c.req.matchedRoutes.forEach(({ handler, method, path }, i) => {
    const name = handler.name || (handler.length < 2 ? '[handler]' : '[middleware]')
    console.log(
      method,
      ' ',
      path,
      ' '.repeat(Math.max(10 - path.length, 0)),
      name,
      i === c.req.routeIndex ? '<- respond from here' : ''
    )
  })
})

`path`プロパティ

pathプロパティは、リクエストのパス名を取得するために使用します。

app.get('/about/me', (c) => {
  const pathname = c.req.path // `/about/me`
  // ...
})

`url`プロパティ

urlプロパティは、リクエストのURLを取得するために使用します。

app.get('/about/me', (c) => {
  const url = c.req.url // `http://localhost:8787/about/me`
  // ...
})

`method`プロパティ

methodプロパティは、リクエストのHTTPメソッド名を取得するために使用します。

app.get('/about/me', (c) => {
  const method = c.req.method // `GET`
  // ...
})

`raw`プロパティ

rawプロパティは、生のRequestオブジェクトを取得するために使用します。

// Cloudflare Workersの場合
app.post('/', async (c) => {
  const metadata = c.req.raw.cf?.hostMetadata?
  // ...
})

以上が、HonoRequestオブジェクトの主要なメソッドとプロパティの説明です。これらを使用することで、HTTPリクエストの情報を簡単に取得し、処理することができます。

midorinotanuki

Cookie Helper は、開発者がクッキーを簡単に管理できるようにするためのインターフェースを提供します。クッキーの設定、解析、削除などの操作を簡単に行うことができます。

まず、Cookie Helper を使うには、次のようにインポートします。

import { Hono } from 'hono'
import { getCookie, getSignedCookie, setCookie, setSignedCookie, deleteCookie } from 'hono/cookie'

使い方

クッキーの設定と取得には、以下のようにします。

const app = new Hono()

app.get('/cookie', (c) => {
  // すべてのクッキーを取得
  const allCookies = getCookie(c)
  // 特定のクッキーを取得
  const yummyCookie = getCookie(c, 'yummy_cookie')
  // ...
  // クッキーを設定
  setCookie(c, 'delicious_cookie', 'macha')
  // クッキーを削除
  deleteCookie(c, 'delicious_cookie')
  //
})

app.get('/signed-cookie', async (c) => {
  const secret = 'secret ingredient'
  // 署名付きクッキーを取得（署名が改ざんされていたり無効な場合は `false` を返す）
  const allSignedCookies = await getSignedCookie(c, secret)
  const fortuneCookie = await getSignedCookie(c, secret, 'fortune_cookie')
  // ...
  const anotherSecret = 'secret chocolate chips'
  // 署名付きクッキーを設定
  await setSignedCookie(c, 'great_cookie', 'blueberry', anotherSecret)
  // 署名付きクッキーを削除
  deleteCookie(c, 'great_cookie')
  //
})

署名付きクッキーの設定と取得は非同期処理になります。これは、署名の作成に WebCrypto API を使用しているためです。

オプション

setCookie と setSignedCookie には以下のオプションがあります。

domain: string - クッキーの有効なドメイン
expires: Date - クッキーの有効期限
httpOnly: boolean - クッキーを HTTP のみで利用可能にするかどうか
maxAge: number - クッキーの有効期間（秒単位）
path: string - クッキーの有効なパス
secure: boolean - クッキーをセキュアな接続でのみ利用可能にするかどうか
sameSite: 'Strict' | 'Lax' | 'None' - クッキーの SameSite 属性
prefix: secure | 'host' - クッキー名のプレフィックス
partitioned: boolean - クッキーをパーティション化するかどうか

例:

// 通常のクッキー
setCookie(c, 'great_cookie', 'banana', {
  path: '/',
  secure: true,
  domain: 'example.com',
  httpOnly: true,
  maxAge: 1000,
  expires: new Date(Date.UTC(2000, 11, 24, 10, 30, 59, 900)),
  sameSite: 'Strict',
})

// 署名付きクッキー
await setSignedCookie(c, 'fortune_cookie', 'lots-of-money', 'secret ingredient', {
  path: '/',
  secure: true,
  domain: 'example.com',
  httpOnly: true,
  maxAge: 1000,
  expires: new Date(Date.UTC(2000, 11, 24, 10, 30, 59, 900)),
  sameSite: 'Strict',
})

deleteCookie には以下のオプションがあります。

path: string - 削除するクッキーのパス
secure: boolean - 削除するクッキーがセキュアかどうか
domain: string - 削除するクッキーのドメイン

例:

deleteCookie(c, 'banana', {
  path: '/',
  secure: true,
  domain: 'example.com',
})

`Secure-` と `Host-` プレフィックス

Cookie Helper は、クッキー名の __Secure- と __Host- プレフィックスをサポートしています。

クッキー名にプレフィックスがあるかどうかを確認するには、プレフィックスオプションを指定します。

const securePrefixCookie = getCookie(c, 'yummy_cookie', 'secure')
const hostPrefixCookie = getCookie(c, 'yummy_cookie', 'host')

const securePrefixSignedCookie = await getSignedCookie(c, secret, 'fortune_cookie', 'secure')
const hostPrefixSignedCookie = await getSignedCookie(c, secret, 'fortune_cookie', 'host')

また、クッキーを設定する際にプレフィックスを指定する場合は、プレフィックスオプションに値を指定します。

setCookie(c, 'delicious_cookie', 'macha', {
  prefix: 'secure', // または `host`
})

await setSignedCookie(c, 'delicious_cookie', 'macha', 'secret choco chips', {
  prefix: 'secure', // または `host`
})

ベストプラクティスに従う

新しい Cookie RFC（別名 cookie-bis）と CHIPS には、開発者が従うべきクッキー設定に関するいくつかのベストプラクティスが含まれています。

RFC6265bis-13
- Max-Age/Expires の制限
- --Host-/--Secure_ プレフィックスの制限
CHIPS-01
- Partitioned の制限

Hono はこれらのベストプラクティスに従っています。Cookie Helper は、以下の条件でクッキーを解析するときに Error をスローします。

クッキー名が __Secure- で始まっているが、secure オプションが設定されていない場合
クッキー名が __Host- で始まっているが、secure オプションが設定されていない場合
クッキー名が __Host- で始まっているが、path が / でない場合
クッキー名が __Host- で始まっているが、domain が設定されている場合
maxAge オプションの値が 400 日より大きい場合
expires オプションの値が現在時刻から 400 日より後の場合

以上が、Hono の Cookie Helper の詳細な説明です。この Helper を使用することで、クッキーの設定、取得、削除などの操作を簡単かつ安全に行うことができます。また、ベストプラクティスに従ってクッキーを管理することで、セキュリティを向上させることができます。

midorinotanuki

CORS

CORS（Cross-Origin Resource Sharing）は、WebアプリケーションがHTTPリクエストを異なるドメインに送信する際に使用されるセキュリティメカニズムです。Cloudflare WorkersをWebAPIとして使用し、外部のフロントエンドアプリケーションから呼び出す場合、CORSを実装する必要があります。

Honoの CORS ミドルウェアを使用すると、CORSの設定を簡単に行うことができます。

まず、CORS ミドルウェアを使うには、次のようにインポートします。

import { Hono } from 'hono'
import { cors } from 'hono/cors'

次に、Honoアプリケーションでミドルウェアを使用します。

const app = new Hono()

app.use('/api/*', cors())
app.use(
  '/api2/*',
  cors({
    origin: 'http://example.com',
    allowHeaders: ['X-Custom-Header', 'Upgrade-Insecure-Requests'],
    allowMethods: ['POST', 'GET', 'OPTIONS'],
    exposeHeaders: ['Content-Length', 'X-Kuma-Revision'],
    maxAge: 600,
    credentials: true,
  })
)

app.all('/api/abc', (c) => {
  return c.json({ success: true })
})
app.all('/api2/abc', (c) => {
  return c.json({ success: true })
})

上記の例では、/api/*パスに対してデフォルトのCORS設定が適用され、/api2/*パスに対してカスタムのCORS設定が適用されています。

複数のオリジンを許可する場合は、次のようにします。

app.use(
  '/api3/*',
  cors({
    origin: ['https://example.com', 'https://example.org'],
  })
)

// または、関数を使用することもできます
app.use(
  '/api4/*',
  cors({
    origin: (origin) => {
      return origin.endsWith('.example.com') ? origin : 'http://example.com'
    },
  })
)

CORS ミドルウェアのオプションは以下の通りです。

origin: string | string[] | (origin: string) => string
- "Access-Control-Allow-Origin" CORSヘッダーの値を指定します。デフォルトは*です。
- コールバック関数を使用して、オリジンに基づいて動的に値を決定することもできます。
allowMethods: string[]
- "Access-Control-Allow-Methods" CORSヘッダーの値を指定します。デフォルトは['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH']です。
allowHeaders: string[]
- "Access-Control-Allow-Headers" CORSヘッダーの値を指定します。デフォルトは[]です。
maxAge: number
- "Access-Control-Max-Age" CORSヘッダーの値を指定します。
credentials: boolean
- "Access-Control-Allow-Credentials" CORSヘッダーの値を指定します。
exposeHeaders: string[]
- "Access-Control-Expose-Headers" CORSヘッダーの値を指定します。デフォルトは[]です。

これらのオプションを適切に設定することで、CORSの動作をカスタマイズできます。

CORS ミドルウェアを使用することで、Cloudflare WorkersをWebAPIとして使用する際のCORS設定を簡単に行うことができます。適切なCORS設定を行うことで、セキュリティを確保しつつ、外部のフロントエンドアプリケーションからのリクエストを許可することができます。

midorinotanuki

Routing

ルーティングとは、アプリケーションが受け取ったHTTPリクエストを、適切なハンドラ関数に振り分ける仕組みのことです。Honoのルーティングは柔軟で直感的に設定できます。

基本的な使い方
まず、基本的なルーティングの設定方法を見ていきましょう。

// HTTP Methods
app.get('/', (c) => c.text('GET /'))
app.post('/', (c) => c.text('POST /'))
app.put('/', (c) => c.text('PUT /'))
app.delete('/', (c) => c.text('DELETE /'))

これらのメソッドを使用すると、特定のHTTPメソッド（GET、POST、PUT、DELETE）とパスに対するルートを定義できます。

ワイルドカードを使用したルーティング
ワイルドカード（*）を使用して、パスの一部を任意の文字列にマッチさせることができます。

app.get('/wild/*/card', (c) => {
  return c.text('GET /wild/*/card')
})

この例では、/wild/と/cardの間に任意の文字列が入ったパスにマッチします。

任意のHTTPメソッドにマッチさせる
allメソッドを使用すると、任意のHTTPメソッドにマッチさせることができます。

app.all('/hello', (c) => c.text('Any Method /hello'))

カスタムHTTPメソッドの定義
onメソッドを使用すると、カスタムHTTPメソッドを定義できます。

app.on('PURGE', '/cache', (c) => c.text('PURGE Method /cache'))

複数のHTTPメソッドにマッチさせる
onメソッドに配列を渡すことで、複数のHTTPメソッドにマッチさせることができます。

app.on(['PUT', 'DELETE'], '/post', (c) => c.text('PUT or DELETE /post'))

複数のパスにマッチさせる
onメソッドの第2引数に配列を渡すことで、複数のパスにマッチさせることができます。

app.on('GET', ['/hello', '/ja/hello', '/en/hello'], (c) => c.text('Hello'))

パスパラメータ
パスパラメータを使用すると、パスの一部を変数として扱うことができます。

app.get('/user/:name', (c) => {
  const name = c.req.param('name')
  // ...
})

この例では、/user/の後に任意の文字列が続くパスにマッチし、その文字列をnameパラメータとして取得しています。

オプションパラメータ
パスパラメータの末尾に?を付けることで、オプションパラメータを定義できます。

// Will match `/api/animal` and `/api/animal/:type`
app.get('/api/animal/:type?', (c) => c.text('Animal!'))

この例では、/api/animalと/api/animal/:typeの両方のパスにマッチします。

正規表現によるルーティング
パスパラメータに正規表現を指定することで、より細かいルーティングが可能です。

app.get('/post/:date{[0-9]+}/:title{[a-z]+}', (c) => {
  const { date, title } = c.req.param()
  // ...
})

この例では、dateパラメータは数字のみ、titleパラメータは小文字のみにマッチします。

スラッシュを含むパスパラメータ
正規表現を使用することで、スラッシュを含むパスパラメータを定義できます。

app.get('/posts/:filename{.+\\.png$}', (c) => {
  // ...
})

この例では、.pngで終わるファイル名にマッチします。

チェーンによるルーティング
同じパスに対して複数のHTTPメソッドを定義する場合、チェーンを使用すると簡潔に書けます。

app
  .get('/endpoint', (c) => {
    return c.text('GET /endpoint')
  })
  .post((c) => {
    return c.text('POST /endpoint')
  })
  .delete((c) => {
    return c.text('DELETE /endpoint')
  })

グループ化
Honoインスタンスを使用してルートをグループ化し、routeメソッドを使用してメインのアプリケーションに追加できます。

const book = new Hono()

book.get('/', (c) => c.text('List Books')) // GET /book
book.get('/:id', (c) => {
  // GET /book/:id
  const id = c.req.param('id')
  return c.text('Get Book: ' + id)
})
book.post('/', (c) => c.text('Create Book')) // POST /book

const app = new Hono()
app.route('/book', book)

ベースパス
basePathメソッドを使用して、グループのベースパスを指定できます。

const api = new Hono().basePath('/api')
api.get('/book', (c) => c.text('List Books')) // GET /api/book

ホスト名を含むルーティング
HonoコンストラクタのgetPathオプションを設定することで、ホスト名を含むルーティングが可能です。

const app = new Hono({
  getPath: (req) => req.url.replace(/^https?:\/(.+?)$/, '$1'),
})

app.get('/www1.example.com/hello', (c) => c.text('hello www1'))
app.get('/www2.example.com/hello', (c) => c.text('hello www2'))

ホストヘッダーの値によるルーティング
HonoコンストラクタのgetPathオプションを設定することで、ホストヘッダーの値によるルーティングが可能です。

const app = new Hono({
  getPath: (req) =>
    '/' + req.headers.get('host') + req.url.replace(/^https?:\/\/[^/]+(\/[^?]*)/, '$1'),
})

app.get('/www1.example.com/hello', () => c.text('hello www1'))

この例では、hostヘッダーの値がwww1.example.comの場合にマッチします。

ルーティングの優先順位
ハンドラやミドルウェアは、登録された順番に実行されます。

app.get('/book/a', (c) => c.text('a')) // a
app.get('/book/:slug', (c) => c.text('common')) // common

この例では、/book/aへのリクエストはaハンドラにマッチし、/book/bへのリクエストはcommonハンドラにマッチします。

ハンドラが実行されると、処理は停止します。

app.get('*', (c) => c.text('common')) // common
app.get('/foo', (c) => c.text('foo')) // foo

この例では、/fooへのリクエストはcommonハンドラにマッチし、fooハンドラは実行されません。

必ず実行したいミドルウェアがある場合は、ハンドラより前に登録します。

app.use(logger())
app.get('/foo', (c) => c.text('foo'))

フォールバックハンドラを設定したい場合は、他のハンドラより後に登録します。

app.get('/foo', (c) => c.text('foo')) // foo
app.get('*', (c) => c.text('fallback')) // fallback

この例では、/barへのリクエストはfallbackハンドラにマッチします。

グループ化の注意点
グループ化の際は、ルーティングの順番に注意が必要です。route関数は、第2引数以降のルーティングを、自身のルーティングに追加します。

three.get('/hi', (c) => c.text('hi'))
two.route('/three', three)
app.route('/two', two)

export default app

この例では、/two/three/hiへのリクエストはhiハンドラにマッチします。

ただし、順番が間違っていると、404エラーになります。

three.get('/hi', (c) => c.text('hi'))
app.route('/two', two) // `two` does not have routes
two.route('/three', three)

export default app

この例では、/two/three/hiへのリクエストは404エラーになります。

以上が、Honoのルーティングについての詳細な説明です。Honoのルーティングは柔軟で強力な機能を提供しており、アプリケーションのニーズに合わせて適切に設定することができます。

midorinotanuki

CSRF Protection

CSRF（Cross-Site Request Forgery）は、ウェブアプリケーションの脆弱性を利用した攻撃手法の一つです。攻撃者は、ユーザーが意図しないリクエストをユーザーの権限で実行させることができます。

Hono の CSRF 保護ミドルウェアは、このような CSRF 攻撃を防ぐために使用されます。このミドルウェアは、リクエストヘッダーをチェックすることで、CSRF 攻撃を防ぎます。

具体的には、フォーム要素を使用した送信などの CSRF 攻撃を防ぐために、Origin ヘッダーの値とリクエストされた URL を比較します。

ただし、Origin ヘッダーを送信しない古いブラウザや、リバースプロキシを使用して Origin ヘッダーを削除する環境では、うまく動作しない可能性があります。そのような環境では、他の CSRF トークンの方法を使用する必要があります。

まず、CSRF 保護ミドルウェアを使うには、次のようにインポートします。

import { Hono } from 'hono'
import { csrf } from 'hono/csrf'

次に、Hono アプリケーションでミドルウェアを使用します。

const app = new Hono()

app.use(csrf())

これにより、デフォルトの設定で CSRF 保護が有効になります。

オプションで、許可するオリジンを指定することもできます。

文字列で指定する場合：

app.use(csrf({ origin: 'myapp.example.com' }))

文字列の配列で指定する場合：

app.use(
  csrf({
    origin: ['myapp.example.com', 'development.myapp.example.com'],
  })
)

関数で指定する場合：

app.use(
  '*',
  csrf({
    origin: (origin) => /https:\/\/(\w+\.)?myapp\.example\.com$/.test(origin),
  })
)

関数で指定する場合は、プロトコルを検証して $ に一致することを強くお勧めします。前方一致を使用してはいけません。

CSRF 保護ミドルウェアのオプションは以下の通りです。

origin: string | string[] | Function
- 許可するオリジンを指定します。

CSRF 保護は、ウェブアプリケーションのセキュリティを確保するために重要な機能です。Hono の CSRF 保護ミドルウェアを使用することで、CSRF 攻撃を防ぎ、アプリケーションのセキュリティを向上させることができます。

ただし、CSRF 保護ミドルウェアにも制限があることに注意してください。Origin ヘッダーを送信しない古いブラウザや、リバースプロキシを使用する環境では、うまく動作しない可能性があります。そのような環境では、他の CSRF 対策を検討する必要があります。

CSRF 保護は、ウェブアプリケーションのセキュリティを確保するための重要な要素の一つです。Hono の CSRF 保護ミドルウェアを適切に使用することで、アプリケーションのセキュリティを向上させることができます。

midorinotanuki

HonoRequest

HonoRequestは、Honoフレームワークにおいて、HTTPリクエストの情報を扱うオブジェクトです。c.reqを通じてアクセスできます。

`param()`メソッド

param()メソッドは、URLのパスパラメータの値を取得するために使用します。

// パスパラメータの取得
app.get('/entry/:id', (c) => {
  const id = c.req.param('id')
  // ...
})

// 複数のパスパラメータを一度に取得
app.get('/entry/:id/comment/:commentId', (c) => {
  const { id, commentId } = c.req.param()
  // ...
})

`query()`メソッド

query()メソッドは、クエリ文字列のパラメータの値を取得するために使用します。

// クエリパラメータの取得
app.get('/search', (c) => {
  const query = c.req.query('q')
  // ...
})

// 複数のクエリパラメータを一度に取得
app.get('/search', (c) => {
  const { q, limit, offset } = c.req.query()
  // ...
})

`queries()`メソッド

queries()メソッドは、同じ名前の複数のクエリ文字列パラメータの値を取得するために使用します。

app.get('/search', (c) => {
  // tagsは文字列の配列になります
  const tags = c.req.queries('tags')
  // ...
})

`header()`メソッド

header()メソッドは、リクエストヘッダの値を取得するために使用します。

app.get('/', (c) => {
  const userAgent = c.req.header('User-Agent')
  // ...
})

`parseBody()`メソッド

parseBody()メソッドは、multipart/form-dataまたはapplication/x-www-form-urlencoded形式のリクエストボディを解析するために使用します。

app.post('/entry', async (c) => {
  const body = await c.req.parseBody()
  // ...
})

parseBody()メソッドは、以下のような動作をサポートしています。

単一ファイルのアップロード
複数ファイルのアップロード
同じ名前の複数ファイルのアップロード

`json()`メソッド

json()メソッドは、application/json形式のリクエストボディを解析するために使用します。

app.post('/entry', async (c) => {
  const body = await c.req.json()
  // ...
})

`text()`メソッド

text()メソッドは、text/plain形式のリクエストボディを解析するために使用します。

app.post('/entry', async (c) => {
  const body = await c.req.text()
  // ...
})

`arrayBuffer()`メソッド

arrayBuffer()メソッドは、リクエストボディをArrayBufferとして解析するために使用します。

app.post('/entry', async (c) => {
  const body = await c.req.arrayBuffer()
  // ...
})

`valid()`メソッド

valid()メソッドは、バリデーションが適用されたデータを取得するために使用します。

app.post('/posts', (c) => {
  const { title, body } = c.req.valid('form')
  // ...
})

使用可能なターゲットは、form、json、query、header、cookie、paramなどがあります。

`routePath()`メソッド

routePath()メソッドは、登録されたパスを取得するために使用します。

app.get('/posts/:id', (c) => {
  return c.json({ path: c.req.routePath })
})

`matchedRoutes()`メソッド

matchedRoutes()メソッドは、マッチしたルートを取得するために使用します。デバッグに役立ちます。

app.use(async function logger(c, next) {
  await next()
  c.req.matchedRoutes.forEach(({ handler, method, path }, i) => {
    const name = handler.name || (handler.length < 2 ? '[handler]' : '[middleware]')
    console.log(
      method,
      ' ',
      path,
      ' '.repeat(Math.max(10 - path.length, 0)),
      name,
      i === c.req.routeIndex ? '<- respond from here' : ''
    )
  })
})

`path`プロパティ

pathプロパティは、リクエストのパス名を取得するために使用します。

app.get('/about/me', (c) => {
  const pathname = c.req.path // `/about/me`
  // ...
})

`url`プロパティ

urlプロパティは、リクエストのURLを取得するために使用します。

app.get('/about/me', (c) => {
  const url = c.req.url // `http://localhost:8787/about/me`
  // ...
})

`method`プロパティ

methodプロパティは、リクエストのHTTPメソッド名を取得するために使用します。

app.get('/about/me', (c) => {
  const method = c.req.method // `GET`
  // ...
})

`raw`プロパティ

rawプロパティは、生のRequestオブジェクトを取得するために使用します。

// Cloudflare Workersの場合
app.post('/', async (c) => {
  const metadata = c.req.raw.cf?.hostMetadata?
  // ...
})

midorinotanuki

JSX Renderer ミドルウェア

JSX Renderer ミドルウェアを使用すると、c.setRenderer() を使用せずに、c.render() 関数で JSX をレンダリングする際のレイアウトを設定できます。さらに、useRequestContext() を使用して、コンポーネント内で Context のインスタンスにアクセスできます。

インポート

npmDeno

import { Hono } from 'hono'
import { jsxRenderer, useRequestContext } from 'hono/jsx-renderer'

使用方法

jsx

const app = new Hono()

app.get(
  '/page/*',
  jsxRenderer(({ children }) => {
    return (
      <html>
        <body>
          <header>メニュー</header>
          <div>{children}</div>
        </body>
      </html>
    )
  })
)

app.get('/page/about', (c) => {
  return c.render(<h1>私について</h1>)
})

オプション

`docType`: `boolean` | `string`

HTML の先頭に DOCTYPE を追加したくない場合は、docType オプションを false に設定します。

tsx

app.use(
  '*',
  jsxRenderer(
    ({ children }) => {
      return (
        <html>
          <body>{children}</body>
        </html>
      )
    },
    { docType: false }
  )
)

また、DOCTYPE を指定することもできます。

tsx

app.use(
  '*',
  jsxRenderer(
    ({ children }) => {
      return (
        <html>
          <body>{children}</body>
        </html>
      )
    },
    {
      docType:
        '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">',
    }
  )
)

`stream`: `boolean` | `Record<string, string>`

true に設定するか、Record 値を提供すると、ストリーミングレスポンスとしてレンダリングされます。

tsx

const AsyncComponent = async () => {
  await new Promise((r) => setTimeout(r, 1000)) // 1秒スリープ
  return <div>こんにちは！</div>
}

app.get(
  '*',
  jsxRenderer(
    ({ children }) => {
      return (
        <html>
          <body>
            <h1>SSR ストリーミング</h1>
            {children}
          </body>
        </html>
      )
    },
    { stream: true }
  )
)

app.get('/', (c) => {
  return c.render(
    <Suspense fallback={<div>読み込み中...</div>}>
      <AsyncComponent />
    </Suspense>
  )
})

true が設定されている場合、次のヘッダーが追加されます。

{
  'Transfer-Encoding': 'chunked',
  'Content-Type': 'text/html; charset=UTF-8'
}

Record 値を指定することで、ヘッダーの値をカスタマイズできます。

ネストされたレイアウト

Layout コンポーネントを使用すると、レイアウトをネストできます。

tsx

app.use(
  jsxRenderer(({ children }) => {
    return (
      <html>
        <body>{children}</body>
      </html>
    )
  })
)

const blog = new Hono()
blog.use(
  jsxRenderer(({ children, Layout }) => {
    return (
      <Layout>
        <nav>ブログメニュー</nav>
        <div>{children}</div>
      </Layout>
    )
  })
)

app.route('/blog', blog)

`useRequestContext()`

useRequestContext() は Context のインスタンスを返します。

tsx

const RequestUrlBadge: FC = () => {
  const c = useRequestContext()
  return <b>{c.req.url}</b>
}

app.get('/page/info', (c) => {
  return c.render(
    <div>
      アクセス中: <RequestUrlBadge />
    </div>
  )
})

`ContextRenderer` の拡張

以下のように ContextRenderer を定義することで、レンダラーに追加のコンテンツを渡すことができます。これは、例えば、ページに応じて head タグの内容を変更したい場合に便利です。

tsx

declare module 'hono' {
  interface ContextRenderer {
    (content: string | Promise<string>, props: { title: string }): Response
  }
}

const app = new Hono()

app.get(
  '/page/*',
  jsxRenderer(({ children, title }) => {
    return (
      <html>
        <head>
          <title>{title}</title>
        </head>
        <body>
          <header>メニュー</header>
          <div>{children}</div>
        </body>
      </html>
    )
  })
)

app.get('/page/favorites', (c) => {
  return c.render(
    <div>
      <ul>
        <li>寿司を食べること</li>
        <li>野球観戦</li>
      </ul>
    </div>,
    {
      title: '私のお気に入り',
    }
  )
})

このページを GitHub で編集

JWT Authentication Helper

sign()関数

verify()関数

decode()関数

ペイロード検証

カスタムエラータイプ

サポートされているアルゴリズムタイプ

HonoRequest

param()メソッド

query()メソッド

queries()メソッド

header()メソッド

parseBody()メソッド

json()メソッド

text()メソッド

arrayBuffer()メソッド

valid()メソッド

routePath()メソッド

matchedRoutes()メソッド

pathプロパティ

urlプロパティ

methodプロパティ

rawプロパティ

Cookie Helper

使い方

オプション

__Secure- と __Host- プレフィックス

ベストプラクティスに従う

CORS

Routing

CSRF Protection

HonoRequest

param()メソッド

query()メソッド

queries()メソッド

header()メソッド

parseBody()メソッド

json()メソッド

text()メソッド

arrayBuffer()メソッド

valid()メソッド

routePath()メソッド

matchedRoutes()メソッド

pathプロパティ

urlプロパティ

methodプロパティ

rawプロパティ

JSX Renderer ミドルウェア

インポート​

使用方法​

オプション​

docType: boolean | string​

stream: boolean | Record<string, string>​

ネストされたレイアウト​

useRequestContext()​

ContextRenderer の拡張​

`sign()`関数

`verify()`関数

`decode()`関数

`param()`メソッド

`query()`メソッド

`queries()`メソッド

`header()`メソッド

`parseBody()`メソッド

`json()`メソッド

`text()`メソッド

`arrayBuffer()`メソッド

`valid()`メソッド

`routePath()`メソッド

`matchedRoutes()`メソッド

`path`プロパティ

`url`プロパティ

`method`プロパティ

`raw`プロパティ

`Secure-` と `Host-` プレフィックス

`param()`メソッド

`query()`メソッド

`queries()`メソッド

`header()`メソッド

`parseBody()`メソッド

`json()`メソッド

`text()`メソッド

`arrayBuffer()`メソッド

`valid()`メソッド

`routePath()`メソッド

`matchedRoutes()`メソッド

`path`プロパティ

`url`プロパティ

`method`プロパティ

`raw`プロパティ

インポート

使用方法

オプション

`docType`: `boolean` | `string`

`stream`: `boolean` | `Record<string, string>`

ネストされたレイアウト

`useRequestContext()`

`ContextRenderer` の拡張