@fracabu/fastify-api-key

Complete API Key authentication for Fastify

Scopes, multiple sources, and TypeScript support

🇬🇧 English | 🇮🇹 Italiano

---

Overview

---

🇬🇧 English

Features

• Fastify v5 support
• TypeScript-first with complete type definitions
• Multiple extraction sources (header, query, body, cookie)
• Scopes/permissions system
• Rate limiting information support
• Timing-safe key comparison (prevents timing attacks)
• Custom error handlers
• ESM and CJS dual module support

Install

npm install @fracabu/fastify-api-key

Quick Start

import Fastify from 'fastify'
import fastifyApiKey from '@fracabu/fastify-api-key'

const app = Fastify()

await app.register(fastifyApiKey, {
  validate: async (key) => {
    const apiKey = await db.apiKeys.findByKey(key)
    if (!apiKey) return { valid: false }
    return { valid: true, scopes: apiKey.scopes }
  }
})

// Protected route
app.get('/api/users', {
  preHandler: app.apiKey()
}, async (request) => {
  return { users: [] }
})

// Route with required scopes
app.delete('/api/users/:id', {
  preHandler: app.apiKey({ scopes: ['admin', 'users:delete'] })
}, handler)

Utilities

import { generateApiKey, timingSafeCompare } from '@fracabu/fastify-api-key'

const key = generateApiKey({ prefix: 'myapp', length: 32 })
// => 'myapp_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345'

---

🇮🇹 Italiano

Funzionalita

• Supporto Fastify v5
• TypeScript-first con definizioni di tipo complete
• Sorgenti di estrazione multiple (header, query, body, cookie)
• Sistema scopes/permessi
• Supporto informazioni rate limiting
• Confronto chiavi timing-safe (previene timing attacks)
• Error handler personalizzati
• Supporto modulo duale ESM e CJS

Installazione

npm install @fracabu/fastify-api-key

Quick Start

import Fastify from 'fastify'
import fastifyApiKey from '@fracabu/fastify-api-key'

const app = Fastify()

await app.register(fastifyApiKey, {
  validate: async (key) => {
    const apiKey = await db.apiKeys.findByKey(key)
    if (!apiKey) return { valid: false }
    return { valid: true, scopes: apiKey.scopes }
  }
})

// Rotta protetta
app.get('/api/users', {
  preHandler: app.apiKey()
}, async (request) => {
  return { users: [] }
})

// Rotta con scopes richiesti
app.delete('/api/users/:id', {
  preHandler: app.apiKey({ scopes: ['admin', 'users:delete'] })
}, handler)

---

Security

This package is published with supply chain security in mind:

Feature	Status	Verification
npm Provenance	✅	npm audit signatures
GitHub Attestations	✅	gh attestation verify
SLSA Level	2	Build provenance
Timing-safe comparison	✅	Prevents timing attacks

Verify Package Authenticity

# Verify npm provenance
npm audit signatures

# Verify GitHub attestation
gh attestation verify $(npm pack @fracabu/fastify-api-key) --owner fracabu

For more details, see our Wiki - Security.

---

Requirements

• Node.js >= 20.0.0
• Fastify >= 5.0.0

License

MIT

---