# HonoJsonWebKey

**Kind:** Interface

**Source:** [`src/utils/jwt/jws.ts`](https://github.com/honojs/hono/blob/main/src/utils/jwt/jws.ts#L23)

**Part of:** [Utils](subsystem-src-utils)

`HonoJsonWebKey` represents a JSON Web Key with a required `kid` property. The key identifier lets JWT handling code select the matching key from a key set when processing a token.

## Properties

| Property | Type |
|---|---|
| `kid` | `string` |

## Diagram

```mermaid
graph LR
  JWT[JWT header] --> KID[kid]
  KID --> JWK[HonoJsonWebKey]
  JWK --> Verify[JWT verification]
```

## Usage

```ts
import type { HonoJsonWebKey } from 'hono/utils/jwt/jws'

const signingKey = {
  kid: 'active-signing-key',
} as HonoJsonWebKey

const keys: HonoJsonWebKey[] = [signingKey]

const key = keys.find((candidate) => candidate.kid === 'active-signing-key')
```

## AI Coding Instructions

- Set `kid` to the identifier expected by the JWT header.
- Keep `kid` values unique within a key set.
- Preserve the remaining JSON Web Key fields when passing keys to JWT signing or verification code.
- Match keys by `kid` before importing them for cryptographic operations.

## How it works

`HonoJsonWebKey` is an exported TypeScript interface that extends the platform `JsonWebKey` type with an optional string `kid` property. [`src/utils/jwt/jws.ts:21-25`](src/utils/jwt/jws.ts#L21-L25)

It has no runtime implementation, validation, error path, or direct side effect of its own; it is a type declaration. [`src/utils/jwt/jws.ts:23-25`](src/utils/jwt/jws.ts#L23-L25)

It is one accepted member of `SignatureKey`, alongside a string or `CryptoKey`, so it can be passed to JWT signing and verification routines. [`src/utils/jwt/jws.ts:27-37`](src/utils/jwt/jws.ts#L27-L37) [`src/utils/jwt/jws.ts:39-48`](src/utils/jwt/jws.ts#L39-L48) When such an object is imported as a signing or verification key, the code passes it to Web Crypto as a JWK with `crypto.subtle.importKey('jwk', ...)`; import failures are propagated by the awaited Web Crypto call. [`src/utils/jwt/jws.ts:66-75`](src/utils/jwt/jws.ts#L66-L75) [`src/utils/jwt/jws.ts:95-104`](src/utils/jwt/jws.ts#L95-L104)

For `Jwt.sign`, if the supplied key is an object containing `alg`, its `alg` value selects the signing algorithm and its `kid` value is written into the JWT header. [`src/utils/jwt/jwt.ts:56-75`](src/utils/jwt/jwt.ts#L56-L75)

For JWKS verification, `verifyWithJwks` accepts an array of `HonoJsonWebKey` values, requires the decoded token header to contain `kid`, and selects the first key whose `kid` strictly equals the header’s `kid`. [`src/utils/jwt/jwt.ts:197-216`](src/utils/jwt/jwt.ts#L197-L216) [`src/utils/jwt/jwt.ts:228-251`](src/utils/jwt/jwt.ts#L228-L251) If no matching key exists, it throws `JwtTokenInvalid`; if the selected key declares `alg` and it differs from the JWT header algorithm, it throws `JwtAlgorithmMismatch`. [`src/utils/jwt/jwt.ts:248-256`](src/utils/jwt/jwt.ts#L248-L256)

## Relationships

- IMPORTS → `getRuntimeKey`
- IMPORTS → `decodeBase64`
- IMPORTS → `CryptoKeyUsage`
- IMPORTS → `JwtAlgorithmNotImplemented`
- IMPORTS → `utf8Encoder`