The key store persists the information associated with an API key which is only ever accessed using the SHA256 hash of the key, for security purposes.

Provided implementations include an in-memory store, Firestore, and Redis. Other stores such as any popular RDBMS can be created by implementing a simple `KeyStore` interface.

We'll use `src/lib/api_keys.ts` to to store the code in all the following examples:

This uses an internal `Map` which is _not_ persisted so is suitable for development, testing and demonstration purposes only!

import { InMemoryKeyStore } from 'svelte-api-keys'

const storage = new InMemoryKeyStore()

Firestore is a popular cloud data store from Google. Use the `firebase-admin/firestore` lib to create a Firestore instance and pass it to the `FirestoreKeyStore` constructor. By default, key information is stored in a collection called `api` but this can be overridden in the constructor. To save read costs and improve performance, wrap the store in an `LruCacheKeyStore` instance:

import { initializeApp } from 'firebase-admin/app'

import { getFirestore } from 'firebase-admin/firestore'

import { FirestoreKeyStore, LruCacheKeyStore } from 'svelte-api-keys'

import { env } from '$env/dynamic/private'

const app = initializeApp({ projectId: env.FIREBASE_PROJECT_ID })

const firestore = getFirestore(app)

const storage = new LruCacheKeyStore(new FirestoreKeyStore(firestore))

Redis is a fast persistable cache and makes for an excellent store. Use the node `redis` package to create a redis client instance and pass it to the `RedisKeyStore` static `create` method, which is used to ensure a search index exists. By default, key information is stored in a hash structure with the prefix `api:` but this can be overridden in the constructor:

import { createClient } from 'redis'

import { RedisKeyStore } from 'svelte-api-keys'

import { env } from '$env/dynamic/private'

const redis = createClient({ url: env.REDIS_URL })

await redis.connect()

const storage = await RedisKeyStore.create(redis)

The token bucket store maintains the state of each token bucket.

Provided implementations include an in-memory store, and Redis. Other stores such as any popular RDBMS can be created by extending a base `TokenBucket` class and implementing a `consume` method.

This uses an internal `Map` which is _not_ persisted or shared so is suitable for single-server use where potentially allowing excess requests in the event of a process restart would be acceptable, or for development, testing and demonstration purposes only!

import { InMemoryTokenBucket } from 'svelte-api-keys'

const buckets = new InMemoryTokenBucket()

The Redis implementation uses a server-side javascript function to handle the token bucket update logic, so Redis Stack Server is recommended. This function is created automatically when the redis client instance is passed to the `RedisTokenBucket` static `create` method. You can also override the default storage prefix (`bucket:`), module name (`TokenBucket`), and function name (`consume`) if needed.

The key store and token bucket implementations are independent of each other and can be mix-and-matched as required, but it's likely that if you're using redis you'll use the Redis implementations of both so they can be created using the same redis client instance:

import { createClient } from 'redis'

import { RedisKeyStore, RedisTokenBucket } from 'svelte-api-keys'

import { env } from '$env/dynamic/private'

const redis = createClient({ url: env.REDIS_URL })

await redis.connect()

const storage = await RedisKeyStore.create(redis)

const buckets = await RedisTokenBucket.create(redis)

The `ApiKeys` manager provides the interface to generate, validate, and manage API keys. It uses the API Key Store internally, and applies SHA256 hashing to keys for security when storing and retrieving them (you can never leak keys if you don't store them!). Normally, you should never access the key store directly - aways use the key manager to do so. When generating keys, it will ensure a key doesn't contain any 'bad words' (which could otherwise be unfortunate and embarrassing!).

The simplest use just requires the key store and token bucket implementations be passed to it:

export const api_keys = new ApiKeys(storage, buckets)

There is an optional parameters object that can also control it's behavior by passing:

`cookie` (default `api-key`) sets the name of a cookie to inspect for an API Key on any incoming request.

`httpHeader` (default `x-api-key`) sets the name of an http header to inspect for an API Key on any incoming request. A request containing the http header `x-api-key: my-api-key` would find the key `my-api-key` automatically. Any key found in the http header will override a key found from a cookie.

`searchParam` (default `key`) sets the name of a URL search parameter to inspect for an API Key on any incoming request. A request for `POST /my-endpoint?key=my-api-key` would find the key `my-api-key` automatically. Any key found in the search param will override a key found from an http header or cookie.

`custom` (default undefined) sets a custom key extraction & transform function that allows you to perform your own key lookups, perhaps via an existing session cookie or similar, and also allows you to transform any existing key that has been extracted using the previous settings - you might [prefix keys to indicate their usage as Stripe does](https://docs.stripe.com/docs/api/authentication) for instance. This will override all other methods if specified.

`key_length` (default 32) sets the length, in bytes, of the API key to generate. If you want shorter API keys you could consider setting it to a lower value such as 24 or 16 (but too low risks conflicts when generating new keys). Keys are converted to human-readable format using Base62 for compactness and easy copy-paste.

So as a more complete example your `src/lib/api_keys.ts` may end up looking something like this, but using whatever key store and token bucket implementations make sense for you:

import { ApiKeys, InMemoryKeyStore, InMemoryTokenBucket } from 'svelte-api-keys'

const storage = new InMemoryKeyStore()

export const api_keys = new ApiKeys(storage, buckets, { searchParam: 'api-key', key_length: 16 })

The `ApiKeys` instance we created provides a `.handle` property that can be used to hook it into the SvelteKit request pipeline. Just return this from `hooks.server.ts`:

import { api_keys } from '$lib/api_keys`

export const handle = api_keys.handle

If you already have a `handle` function you can chain them together using the [`sequence`](https://kit.svelte.dev/docs/modules#sveltejs-kit-hooks-sequence) helper function.

Now our API Key manager is hooked into the SvelteKit pipeline, any request will have an `api` object available on `locals`. This will have a `key`, and `info` property depending on whether an API Key was sent with the request and whether it was valid. It also provides a fluent API that any endpoint can use to `limit()` the request by passing in the refill rate to apply.

import { api_keys } from '$lib/api_keys`

// fetchTierForUser is an example API that will return the appropriate tier based on the key info user

// tip: this would benefit from an in-memory LRU + TTL cache to avoid slowing down repeated lookups...

export const handle = sequence(api_keys.handle, handleTiers)

Finally, should you need them for whatever reason, the `.limit(rate)` method returns details about the result of the call which are also set as HTTP Response headers - these will allow well-behaved clients to automatically back off when they hit rate limits.

- Warn if an endpoint fails to call `.limit(rate)`, at least after any other api methods

- Provide a ready-to-go UI for managing keys

"version": "0.1.0",

import { ApiKeys } from 'svelte-api-keys'

export const api_keys = new ApiKeys(storage, buckets)

const handleApi = api_keys.handle

const handleTiers: Handle = async ({ event, resolve }) => {