Skip to content

Security and Access Keys

mavrovde edited this page Nov 1, 2026 · 2 revisions

Security and Access Keys

This page describes how callers are identified, what they may read, and how keys are protected through their whole life. Everything here is design; see Project Status.

Key format

vf_live_<key id>_<secret><checksum>
Part Purpose
vf_live_ / vf_test_ prefix Distinguishes production keys from keys for the fixture-backed test instance, and lets secret scanners (including GitHub's) find leaked keys. The prefixes are configurable.
Key id Short, public, base62. Appears in logs, usage reports and audit records.
Secret 32 random bytes from a cryptographically secure generator, base62-encoded. Shown once, at issue time.
Checksum A short checksum (GitHub-token style) that rejects typos without a database lookup.

Storage

  • Only a MAC of the secret is stored: HMAC-SHA-256 with a server-side pepper. A fast MAC is the right choice for high-entropy random secrets; a slow password hash would only burn CPU.
  • The pepper comes from the environment or a secret file, never from the database. A previous pepper can be configured during pepper rotation; a key that matches under the old pepper is re-MACed.
  • Comparisons run in constant time.
  • Neither the secret nor the MAC is ever logged or returned.

Presenting a key

  • Authorization: Bearer <key> or X-API-Key: <key>.
  • A key in the query string is refused with 400 key-in-query, because URLs end up in logs.
  • A missing key returns 401 missing-key with a WWW-Authenticate challenge.

Plans, scopes and use classes

A key belongs to a plan. Plans are rows in the access store, so they can be changed without a deployment; configuration only seeds the defaults.

Plan attribute Meaning
Tier critical, standard or bulk: the priority under load (see [[Rate Limits and Priority
Use class consumer, non-commercial or commercial (wire values consumer, non_commercial, commercial): matched against each source's licence ([[Spec: Authentication and Authorisation
Rate and burst the per-key token bucket
Daily and monthly quota hard ceilings
History depth how far back history endpoints may reach
Maximum page size upper bound for limit
Source families which families the plan includes

Scopes are feature families: places, roads, energy, parking, transit, accessibility, weather, rules, history. Every operation declares the scope it needs.

The licence gate

A source family is allowed for a request only if all of the following hold:

  1. the family is part of the key's plan;
  2. the plan's use class is permitted by that family's licence terms;
  3. any terms that require explicit acceptance have been accepted for this key;
  4. the family is not disabled by configuration.
flowchart LR
  K[Key → plan] --> G{Licence gate}
  T[Source terms register] --> G
  A[Terms acceptance] --> G
  D[Disabled families<br/>configuration] --> G
  G -->|allowed families| Q[Query: only rows of<br/>allowed families are read]
  Q --> R[Post-check every row]
  R -->|violation| X[500 + alert metric]
  R --> OK[Response with attribution]
Loading
  • The allowed set is passed into the database query, so a forbidden row is never read at all.
  • Every returned row is checked again (defence in depth). A violation is an internal error plus an alerting metric that must stay at zero.
  • Default deny: a family is enabled for a use class only after its licence has been reviewed and signed off.

Illustrative cases (the reviewed licence matrix decides the real ones):

  • a source licensed for consumer information only is served only to consumer plans;
  • a source whose terms need explicit acceptance answers 403 terms-not-accepted until they are accepted;
  • share-alike sources are served with their condition note and a pointer to the share-alike export.

Key lifecycle

Keys are managed first through a command-line tool run by the operator, and later through a passkey-protected owner console. Every change writes an audit record in the same transaction.

Action Effect
Issue (plan, label, optional expiry) prints the key once
Rotate (with an overlap window) the old secret stays valid until the overlap ends, so clients can switch without downtime
Revoke (with a reason) effective immediately: the running service is notified and evicts the key from its cache; at the latest after the key-cache lifetime
List, show, usage read-only; never prints a secret

Defaults (configurable): keys expire after a year; rotation overlap is seven days.

Key cache and abuse resistance

  • Validated keys are cached for a short time; concurrent first requests for the same key cause one lookup.
  • Failed lookups are cached briefly, which blunts floods of random keys.
  • A per-IP limit applies before a key is known.
  • The TLS edge applies a coarse per-IP ceiling and body-size limits in front of the service.

Errors

Status Type
400 key-in-query
401 missing-key, invalid-key, key-expired, key-revoked
403 scope-denied, source-not-permitted, terms-not-accepted

Secrets in logs

  • A redactor masks Authorization, X-API-Key and any string that looks like a ViaFrei key in every log sink.
  • Secret configuration values have a type that cannot be printed or serialised in clear.
  • A test plants keys in a header, a query string and an error message, then searches every log output for them.

Database privileges

  • The read role is read-only by default for every transaction, limited to the read contract, with a role-level statement timeout and a hard connection limit.
  • Views that filter licensed rows are security barriers, owned by a role that cannot log in.
  • Tests assert that the read role cannot see an internal object and that any write fails.

Supply chain and repository security

CodeQL, dependency review, Dependabot, secret scanning with push protection and a custom key pattern, signed images with provenance and SBOM, image vulnerability scanning, OpenSSF Scorecard, and private vulnerability reporting. See Development Process.

Later: OAuth 2.1

OAuth 2.1 client credentials may be added for enterprise integrations once the specification is final. API keys cover the need until then.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally