# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## The key A key is three parts joined by underscores: ``` ak_3kTn9QxWb2aZ_p8HcR2mXv7LqY4sJd0fGtB6nKwE1uZa9oCiV5xQ2mB7 ``` | Part | What it is | | --- | --- | | Prefix | The `key_prefix` input. It lets secret scanners recognise a leaked key. | | Id | 12 random characters. It is public, and it finds the row. | | Secret | 32 random bytes written in base 62, padded on the left to 43 characters. | Use letters and digits only inside each part, so a double-click selects the whole key. The sample above is a prefix, a 12 character id and a 43 character secret. ## Data model Use the database in the `database` input. | Table | Columns | | --- | --- | | `api_keys` | `id` (the id part, primary key), `owner_id`, `name`, `secret_hash`, `last4`, `scopes`, `created_by`, `created_at`, `last_used_at`, `last_used_ip`, `expires_at`, `revoke_at`, `replaces` | `owner_id` is a user id or a workspace id, as the `owner` input says. `scopes` is only used when the `scopes` option is on, and `expires_at` when `expiry` is. `revoke_at` is when the key stops working: now for a revoked key, later for a key that was rotated with time to spare. ## Rules - Hash the secret with SHA-256. It is random and long, so a slow password hash would add cost to every request and no safety. - To check a key: split it, find the row by id, hash the secret and compare with `secret_hash` in constant time. Then check `revoke_at` and `expires_at` against the clock. - A key that does not split into three parts with the right prefix is malformed. Do not look it up. - Take the time from one function, so tests can set it. - Update `last_used_at` only when it is more than a minute old, so a busy key does not write on every request. - Never log the `Authorization` header. Log the id part when a key must be named. - Count failed attempts per IP address in memory or in the database, whichever the app already uses for such things. ## Errors Every error is JSON with one shape: ```json { "error": { "code": "key_revoked", "message": "This API key was revoked." } } ``` Codes: `key_missing`, `key_malformed`, `key_unknown`, `key_revoked`, `key_expired`, `scope_missing`, `too_many_attempts`. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | ## Who is signed in The spec reaches the app's sign-in through one function, `current_user(request)`. It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session. When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.