feat: per-client API keys with per-key rate limiting (sustainability-software-lab#248)

* feat: add per-client API keys with rate limiting

Introduces X-API-Key authentication as a third auth path alongside
Bearer JWT and HTTP-only cookie, so each consumer (frontend, external
researcher, partner) gets an individually revocable key with per-key
sliding-window rate limiting.

Key design choices:
- Store only Argon2 hash + 8-char prefix; raw key returned once at
  creation and never persisted
- Prefix-based lookup narrows Argon2 candidates before expensive verify
- Rate limit state (window_start/count) stored on the api_key row with
  SELECT FOR UPDATE to handle concurrent requests
- rate_limit_per_minute=0 means unlimited (for trusted internal callers)
- Existing JWT/cookie auth unchanged — no regression for browser clients

New endpoints (admin-only):
  POST   /v1/auth/api-keys
  GET    /v1/auth/api-keys
  DELETE /v1/auth/api-keys/{id}
  PATCH  /v1/auth/api-keys/{id}

Includes Alembic migration (down_revision=eacbc6544a10) and 14-test
suite covering create/list/revoke/update/auth/rate-limit scenarios.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Update src/ca_biositing/webservice/ca_biositing/webservice/services/auth_service.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update src/ca_biositing/webservice/ca_biositing/webservice/services/auth_service.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update alembic/versions/b3f2d1c8e9a0_add_api_key_table.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update src/ca_biositing/datamodels/ca_biositing/datamodels/models/auth/api_key.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fix: address security review findings from PR sustainability-software-lab#248

Resolves all 'before merge' items from @lsetiawan's audit plus two
correctness bugs flagged by Copilot:

FINDING-01 (HIGH): Add constant-time dummy Argon2 verify when no prefix
  candidates exist, preventing prefix enumeration via timing side-channel.
  Mirrors the existing authenticate_user / DUMMY_HASH pattern.

FINDING-03 (MEDIUM): Admin endpoints now require JWT-only auth via a new
  get_jwt_user() dependency. X-API-Key is intentionally excluded from
  AdminUserDep so a leaked key can never manage other keys regardless of
  the linked account's role. Returns 401 (not 403) on missing JWT.

FINDING-05 (LOW): Rename 'sliding window' to 'fixed window' throughout
  — comments, docstrings, and model class docstring. Field names unchanged
  to avoid a migration. Added burst-tolerance note.

FINDING-07 (LOW): GET /v1/auth/api-keys now supports optional api_user_id
  filter and limit/offset pagination. Covered by a new test.

FINDING-12 (MEDIUM): validate_api_key early-exits for keys longer than
  128 chars before touching the DB or running Argon2.

FINDING-02 (MEDIUM): logger.warning on auth failure and rate limit hit;
  logger.info on key creation and revocation. Raw key/hash never logged.

Copilot: rollback before return False when rate limit is exceeded, so the
  SELECT FOR UPDATE row lock is released immediately rather than held until
  session teardown.

Copilot: re-check ApiKey.is_active in the FOR UPDATE query to handle
  concurrent revocation between validate_api_key and the counter update.

Copilot: fix timezone mismatch — rate_window_start and last_used_at now
  use an explicit sa.DateTime(timezone=True) column to match the migration
  and avoid naive/aware subtraction errors on Postgres.

All 168 unit tests pass (3 pre-existing integration failures unchanged).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: rebase alembic migration down_revision to current main head

The api_user migration pointed to an older revision (97a23076c0d9),
creating multiple Alembic heads and failing CI. Updated to point to
60b08397200f (current main head).

* fix: resolve circular dependency in migration chain

eacbc6544a10 was incorrectly rebased onto 60b08397200f, which is a
descendant of eacbc6544a10 itself, creating a cycle that caused
alembic upgrade head to hang indefinitely.

Restore eacbc6544a10 to its original down_revision (97a23076c0d9)
and point the new b3f2d1c8e9a0 (api_key table) at 60b08397200f,
the actual current chain head.

* fix: use timezone-aware DateTime in api_key migration

Align migration column types with the model's sa.DateTime(timezone=True)
for rate_window_start and last_used_at to fix alembic check drift.

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Landung 'Don' Setiawan <landungs@uw.edu>

Author: 4 people

alembic/versions/b3f2d1c8e9a0_add_api_key_table.py

@@ -0,0 +1,49 @@
+"""Add api_key table
+
+Revision ID: b3f2d1c8e9a0
+Revises: 60b08397200f
+Create Date: 2026-04-02 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+# revision identifiers, used by Alembic.
+revision: str = 'b3f2d1c8e9a0'
+down_revision: Union[str, Sequence[str], None] = '60b08397200f'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add api_key table for per-client API key authentication."""
+    op.create_table(
+        'api_key',
+        sa.Column('id', sa.Integer(), nullable=False),
+        sa.Column('api_user_id', sa.Integer(), nullable=False),
+        sa.Column('name', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column('key_prefix', sqlmodel.sql.sqltypes.AutoString(length=8), nullable=False),
+        sa.Column('key_hash', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column('is_active', sa.Boolean(), nullable=False, server_default=sa.text('true')),
+        sa.Column('rate_limit_per_minute', sa.Integer(), nullable=False, server_default=sa.text('60')),
+        sa.Column('rate_window_start', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('rate_window_count', sa.Integer(), nullable=False, server_default=sa.text('0')),
+        sa.Column('last_used_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('created_at', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=True),
+        sa.Column('updated_at', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=True),
+        sa.ForeignKeyConstraint(['api_user_id'], ['api_user.id'], ),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('key_hash'),
+    )
+    op.create_index(op.f('ix_api_key_api_user_id'), 'api_key', ['api_user_id'], unique=False)
+    op.create_index(op.f('ix_api_key_key_prefix'), 'api_key', ['key_prefix'], unique=False)
+
+
+def downgrade() -> None:
+    """Drop api_key table."""
+    op.drop_index(op.f('ix_api_key_key_prefix'), table_name='api_key')
+    op.drop_index(op.f('ix_api_key_api_user_id'), table_name='api_key')
+    op.drop_table('api_key')

src/ca_biositing/datamodels/ca_biositing/datamodels/models/__init__.py

@@ -2,7 +2,7 @@
 from .base import BaseEntity, LookupBase, Aim1RecordBase, Aim2RecordBase
 
 # Auth
-from .auth import ApiUser
+from .auth import ApiKey, ApiUser
 
 # Aim1 Records
 from .aim1_records import CalorimetryRecord, CompositionalRecord, FtnirRecord, IcpRecord, ProximateRecord, RgbRecord, UltimateRecord, XrdRecord, XrfRecord

src/ca_biositing/datamodels/ca_biositing/datamodels/models/auth/__init__.py

@@ -1 +1,2 @@
+from .api_key import ApiKey
 from .api_user import ApiUser

src/ca_biositing/datamodels/ca_biositing/datamodels/models/auth/api_key.py

@@ -0,0 +1,56 @@
+"""ApiKey model for per-client API key authentication."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+
+import sqlalchemy as sa
+from sqlmodel import Field, SQLModel
+
+
+class ApiKey(SQLModel, table=True):
+    """Per-client API key for authenticating external callers.
+
+    Raw keys are shown exactly once at creation and never stored. Only the
+    Argon2 hash is persisted. The key_prefix (first 8 chars of the raw key)
+    is stored in plaintext to allow efficient lookup before hash verification.
+
+    Rate limiting uses a DB-based fixed-window counter with SELECT FOR UPDATE
+    to handle multiple Cloud Run instances without requiring Redis. The window
+    resets each time 60 seconds have elapsed since rate_window_start, meaning
+    a burst of up to 2N requests in ~2s is possible at a window boundary —
+    acceptable for a research API.
+    """
+
+    __tablename__ = "api_key"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    api_user_id: int = Field(foreign_key="api_user.id", nullable=False, index=True)
+    name: str = Field(nullable=False)
+    key_prefix: str = Field(nullable=False, index=True)
+    key_hash: str = Field(nullable=False, unique=True)
+    is_active: bool = Field(default=True, nullable=False)
+    rate_limit_per_minute: int = Field(default=60, nullable=False)
+    # Fixed-window rate limit state. Stored with explicit timezone=True so that
+    # SQLAlchemy maps these to TIMESTAMPTZ on Postgres, matching the migration.
+    rate_window_start: Optional[datetime] = Field(
+        default=None,
+        sa_column=sa.Column(sa.DateTime(timezone=True), nullable=True),
+    )
+    rate_window_count: int = Field(default=0, nullable=False)
+    last_used_at: Optional[datetime] = Field(
+        default=None,
+        sa_column=sa.Column(sa.DateTime(timezone=True), nullable=True),
+    )
+    created_at: Optional[datetime] = Field(
+        default=None,
+        sa_column_kwargs={"server_default": sa.text("CURRENT_TIMESTAMP")},
+    )
+    updated_at: Optional[datetime] = Field(
+        default=None,
+        sa_column_kwargs={
+            "server_default": sa.text("CURRENT_TIMESTAMP"),
+            "onupdate": lambda: datetime.now(timezone.utc),
+        },
+    )

src/ca_biositing/webservice/ca_biositing/webservice/dependencies.py

@@ -8,14 +8,18 @@
 
 from typing import Annotated, Optional
 
-from fastapi import Depends, HTTPException, Query, Request, status
+from fastapi import Depends, Header, HTTPException, Query, Request, status
 from fastapi.security import OAuth2PasswordBearer
 from sqlmodel import Session, select
 
 from ca_biositing.datamodels.database import get_session
 from ca_biositing.datamodels.models import ApiUser
 from ca_biositing.webservice.config import config
-from ca_biositing.webservice.services.auth_service import decode_access_token
+from ca_biositing.webservice.services.auth_service import (
+    check_and_increment_rate_limit,
+    decode_access_token,
+    validate_api_key,
+)
 
 
 # Database session dependency
@@ -38,35 +42,23 @@ def pagination_params(
 oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/v1/auth/token", auto_error=False)
 
 
-def get_current_user(
-    token: Annotated[Optional[str], Depends(oauth2_scheme)],
-    request: Request,
-    session: SessionDep,
-) -> ApiUser:
-    """Resolve the current authenticated user from Bearer token or HTTP-only cookie.
+def _resolve_jwt_user(token: Optional[str], request: Request, session: Session) -> Optional[ApiUser]:
+    """Shared helper: resolve a user from a JWT Bearer token or HTTP-only cookie.
 
-    Checks the Authorization: Bearer header first; if absent, falls back to the
-    access_token cookie. Raises 401 if no valid token is found or the user is disabled.
+    Returns the ApiUser on success, or None if no valid JWT is present.
+    Raises 401 if a token is present but invalid/expired.
     """
     credentials_exception = HTTPException(
         status_code=status.HTTP_401_UNAUTHORIZED,
         detail="Could not validate credentials",
         headers={"WWW-Authenticate": "Bearer"},
     )
-
-    # Prefer Bearer header; fall back to cookie
     resolved_token: Optional[str] = token or request.cookies.get("access_token")
     if not resolved_token:
-        raise credentials_exception
-
-    username = decode_access_token(
-        resolved_token,
-        config.jwt_secret_key,
-        config.jwt_algorithm,
-    )
+        return None
+    username = decode_access_token(resolved_token, config.jwt_secret_key, config.jwt_algorithm)
     if not username:
         raise credentials_exception
-
     user = session.exec(select(ApiUser).where(ApiUser.username == username)).first()
     if user is None:
         raise credentials_exception
@@ -78,12 +70,86 @@ def get_current_user(
     return user
 
 
+def get_jwt_user(
+    token: Annotated[Optional[str], Depends(oauth2_scheme)],
+    request: Request,
+    session: SessionDep,
+) -> ApiUser:
+    """JWT-only authentication (Bearer header or HTTP-only cookie).
+
+    Does NOT accept X-API-Key. Used for admin endpoints so that a leaked
+    API key can never access key-management operations.
+
+    Raises 401 if no valid JWT credential is present.
+    """
+    user = _resolve_jwt_user(token, request, session)
+    if user is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Could not validate credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return user
+
+
+def get_current_user(
+    token: Annotated[Optional[str], Depends(oauth2_scheme)],
+    request: Request,
+    session: SessionDep,
+    x_api_key: Annotated[Optional[str], Header(alias="X-API-Key")] = None,
+) -> ApiUser:
+    """Resolve the current authenticated user.
+
+    Auth check order:
+    1. Authorization: Bearer <jwt> header
+    2. access_token HTTP-only cookie
+    3. X-API-Key header (per-client API key with rate limiting)
+
+    Raises 401 if no valid credential is found or the user is disabled.
+    Raises 429 if the API key's rate limit is exceeded.
+    """
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+
+    # --- Path 1 & 2: JWT (Bearer header or cookie) ---
+    jwt_user = _resolve_jwt_user(token, request, session)
+    if jwt_user is not None:
+        return jwt_user
+
+    # --- Path 3: X-API-Key header ---
+    if x_api_key:
+        api_key = validate_api_key(session, x_api_key)
+        if not api_key:
+            raise credentials_exception
+        user = session.exec(select(ApiUser).where(ApiUser.id == api_key.api_user_id)).first()
+        if user is None or user.disabled:
+            raise credentials_exception
+        if not check_and_increment_rate_limit(session, api_key):
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Rate limit exceeded",
+                headers={"Retry-After": "60"},
+            )
+        return user
+
+    raise credentials_exception
+
+
 # Typed dependency aliases
 CurrentUserDep = Annotated[ApiUser, Depends(get_current_user)]
+JWTCurrentUserDep = Annotated[ApiUser, Depends(get_jwt_user)]
 
 
-def get_current_admin_user(current_user: CurrentUserDep) -> ApiUser:
-    """Require the current user to be an admin. Raises 403 otherwise."""
+def get_current_admin_user(current_user: JWTCurrentUserDep) -> ApiUser:
+    """Require the current user to be an admin, authenticated via JWT only.
+
+    API keys are intentionally excluded — a leaked key must not be able to
+    manage other keys even if the linked account has admin privileges.
+    Raises 403 if the user is not an admin.
+    """
     if not current_user.is_admin:
         raise HTTPException(
             status_code=status.HTTP_403_FORBIDDEN,