feat(api): change key format to lh_pat_ with 16-char prefix

API key format changed from `lh_<entropy>` to `lh_pat_<entropy>` so that
secret-scanning tools (gitleaks, GitGuardian) can detect leaked tokens via
the unambiguous `pat_` discriminator.

- key_generator: plaintext = f"lh_pat_{body}", prefix = plaintext[:16]
- dependencies: prefix extraction 12 → 16 chars, min-length guard 12 → 16
- alembic 20260517: bootstrap key regenerated with lh_pat_ format
- alembic 20260518: new migration extends key_prefix to VARCHAR(16)
- all tests updated to lh_pat_ plaintext strings and [:16] prefix slices

Refs #22

Author: strausmann

backend/alembic/versions/20260517_phase7c_api_keys.py

@@ -24,8 +24,8 @@
 
 def _generate_bootstrap_key() -> tuple[str, str, str]:
     body = secrets.token_urlsafe(32)
-    plaintext = f"lh_{body}"
-    prefix = plaintext[:12]
+    plaintext = f"lh_pat_{body}"
+    prefix = plaintext[:16]
     hashed = bcrypt.hashpw(plaintext.encode(), bcrypt.gensalt(rounds=12)).decode()
     return plaintext, prefix, hashed
 

backend/alembic/versions/20260518_phase7c_pat_prefix.py

@@ -0,0 +1,39 @@
+"""Phase 7c — update key_prefix to VARCHAR(16) for lh_pat_ format.
+
+Revision ID: 20260518_phase7c_pat_prefix
+Revises: 20260517_phase7c_api_keys
+Create Date: 2026-05-18
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "20260518_phase7c_pat_prefix"
+down_revision = "20260517_phase7c_api_keys"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # SQLite via batch_alter_table supports column type changes.
+    # For PostgreSQL the String type without length is unlimited, so this
+    # migration is a no-op in production but makes the intent explicit.
+    with op.batch_alter_table("api_keys") as batch_op:
+        batch_op.alter_column(
+            "key_prefix",
+            existing_type=sa.String(),
+            type_=sa.String(16),
+            nullable=False,
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("api_keys") as batch_op:
+        batch_op.alter_column(
+            "key_prefix",
+            existing_type=sa.String(16),
+            type_=sa.String(12),
+            nullable=False,
+        )

backend/app/auth/dependencies.py

@@ -122,7 +122,7 @@ async def _validate_api_key(
 ) -> AuthContext:
     """Validate the X-Label-Hub-Key header.
 
-    1. Extract prefix (first 12 chars) to look up the key row.
+    1. Extract prefix (first 16 chars) to look up the key row.
     2. bcrypt-verify the full plaintext against the stored hash.
     3. Check the key is enabled and not expired.
     4. Check the key's scopes satisfy ``required_scope``.
@@ -132,13 +132,13 @@ async def _validate_api_key(
         HTTPException 401: key not found / bcrypt mismatch / disabled
         HTTPException 403: key valid but insufficient scope
     """
-    if len(key_header) < 12:
+    if len(key_header) < 16:
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail={"error_code": "invalid_key_format", "error_message": "Invalid key format"},
         )
 
-    prefix = key_header[:12]
+    prefix = key_header[:16]
     key_row = await api_keys_repo.get_by_prefix(session, prefix)
 
     if key_row is None:

backend/app/auth/key_generator.py

@@ -1,12 +1,13 @@
 """API key generation for Phase 7c — generates bcrypt-hashed keys with prefix.
 
-Key format: ``lh_<43-char-urlsafe-base64>``
-  - ``lh_`` — Label Hub prefix, distinguishes from other token formats
+Key format: ``lh_pat_<43-char-urlsafe-base64>``
+  - ``lh_pat_`` — Label Hub Personal Access Token infix, unambiguously
+    identifies token type for both humans and secret-scanning tools
   - 43-char body — secrets.token_urlsafe(32) produces ~43 URL-safe chars
     from 256 bits of entropy (no padding)
 
 The plaintext is returned only at generation time and must be shown to the
-user ONCE. Only the bcrypt hash and the 12-char prefix are persisted.
+user ONCE. Only the bcrypt hash and the 16-char prefix are persisted.
 """
 
 from __future__ import annotations
@@ -26,11 +27,11 @@ def generate_api_key() -> tuple[str, str, str]:
     Returns:
         (plaintext, prefix, bcrypt_hash) where:
         - plaintext — the full key, shown to the user ONCE, never persisted
-        - prefix    — first 12 chars (e.g. "lh_ab12cd34X"), stored for UI display
+        - prefix    — first 16 chars (e.g. "lh_pat_ab12cd34X"), stored for UI display
         - bcrypt_hash — stored in the DB, used for verify_api_key()
     """
     body = secrets.token_urlsafe(32)  # 256 bits of entropy, URL-safe charset
-    plaintext = f"lh_{body}"
-    prefix = plaintext[:12]
+    plaintext = f"lh_pat_{body}"
+    prefix = plaintext[:16]
     hashed = bcrypt.hashpw(plaintext.encode(), bcrypt.gensalt(rounds=_BCRYPT_ROUNDS)).decode()
     return plaintext, prefix, hashed

backend/tests/db/test_api_keys_repo.py

@@ -14,7 +14,7 @@ def _make_key(
     *,
     name="test-key",
     key_hash=r"\$2b\$12\$fake",
-    key_prefix="lh_ab12cd34",
+    key_prefix="lh_pat_ab12cd34",
     scopes=None,
     allowed_printer_ids=None,
     rate_limit_per_minute=60,
@@ -45,18 +45,18 @@ async def test_create_inserts_and_returns_key(session):
 
 @pytest.mark.asyncio
 async def test_create_multiple_keys(session):
-    k1 = await repo.create(session, _make_key(name="key1", key_prefix="lh_aaaaaaaaaa"))
-    k2 = await repo.create(session, _make_key(name="key2", key_prefix="lh_bbbbbbbbbb"))
+    k1 = await repo.create(session, _make_key(name="key1", key_prefix="lh_pat_aaaaaaa"))
+    k2 = await repo.create(session, _make_key(name="key2", key_prefix="lh_pat_bbbbbbb"))
     assert k1.id != k2.id
 
 
 @pytest.mark.asyncio
 async def test_get_by_prefix_returns_matching_key(session):
-    key = _make_key(key_prefix="lh_ab12cd34XX")
+    key = _make_key(key_prefix="lh_pat_ab12cd3X")
     await repo.create(session, key)
-    found = await repo.get_by_prefix(session, "lh_ab12cd34XX")
+    found = await repo.get_by_prefix(session, "lh_pat_ab12cd3X")
     assert found is not None
-    assert found.key_prefix == "lh_ab12cd34XX"
+    assert found.key_prefix == "lh_pat_ab12cd3X"
 
 
 @pytest.mark.asyncio
@@ -67,17 +67,17 @@ async def test_get_by_prefix_returns_none_for_unknown(session):
 
 @pytest.mark.asyncio
 async def test_list_active_returns_only_enabled_non_expired(session):
-    enabled = _make_key(name="enabled", key_prefix="lh_aaaaaaaaaa", enabled=True)
-    disabled = _make_key(name="disabled", key_prefix="lh_bbbbbbbbbb", enabled=False)
+    enabled = _make_key(name="enabled", key_prefix="lh_pat_aaaaaaa", enabled=True)
+    disabled = _make_key(name="disabled", key_prefix="lh_pat_bbbbbbb", enabled=False)
     expired = _make_key(
         name="expired",
-        key_prefix="lh_cccccccccc",
+        key_prefix="lh_pat_ccccccc",
         enabled=True,
         expires_at=datetime.now(UTC) - timedelta(hours=1),
     )
     future = _make_key(
         name="future-expiry",
-        key_prefix="lh_dddddddddd",
+        key_prefix="lh_pat_ddddddd",
         enabled=True,
         expires_at=datetime.now(UTC) + timedelta(days=30),
     )

backend/tests/integration/api/test_audit_trail.py

@@ -17,8 +17,8 @@
 
 
 async def _insert_print_key(factory):
-    plaintext = f"lh_audit_trail_test_{uuid4().hex[:16]}"
-    prefix = plaintext[:12]
+    plaintext = f"lh_pat_audit_trail_{uuid4().hex[:16]}"
+    prefix = plaintext[:16]
     hashed = bcrypt.hashpw(plaintext.encode(), bcrypt.gensalt(rounds=4)).decode()
     key_id = uuid4()
     async with factory() as s:

backend/tests/integration/api/test_auth_wiring.py

@@ -19,8 +19,8 @@
 
 async def _make_print_key(factory):
     """Insert an api-key with print scope and return (plaintext, ApiKey)."""
-    plaintext = "lh_print_integ_wiring_test_step4_001"
-    prefix = plaintext[:12]
+    plaintext = "lh_pat_print_integ_wiring_test_step4_001"
+    prefix = plaintext[:16]
     hashed = bcrypt.hashpw(plaintext.encode(), bcrypt.gensalt(rounds=4)).decode()
     async with factory() as s:
         key = ApiKey(
@@ -37,8 +37,8 @@ async def _make_print_key(factory):
 
 
 async def _make_read_key(factory):
-    plaintext = "lh_read_integ_wiring_test_step4_002"
-    prefix = plaintext[:12]
+    plaintext = "lh_pat_read_integ_wiring_test_step4_002"
+    prefix = plaintext[:16]
     hashed = bcrypt.hashpw(plaintext.encode(), bcrypt.gensalt(rounds=4)).decode()
     async with factory() as s:
         key = ApiKey(
@@ -55,8 +55,8 @@ async def _make_read_key(factory):
 
 
 async def _make_admin_key(factory):
-    plaintext = "lh_admin_integ_wiring_test_step4_003"
-    prefix = plaintext[:12]
+    plaintext = "lh_pat_admin_integ_wiring_test_step4_003"
+    prefix = plaintext[:16]
     hashed = bcrypt.hashpw(plaintext.encode(), bcrypt.gensalt(rounds=4)).decode()
     async with factory() as s:
         key = ApiKey(

backend/tests/integration/api/test_printer_acl.py

@@ -15,8 +15,8 @@
 
 async def _insert_restricted_key(factory, *, allowed_printer_ids: list[str], scopes=None):
     """Insert a key restricted to specific printer IDs."""
-    plaintext = f"lh_acl_test_{uuid4().hex[:20]}"
-    prefix = plaintext[:12]
+    plaintext = f"lh_pat_acl_t_{uuid4().hex[:16]}"
+    prefix = plaintext[:16]
     hashed = bcrypt.hashpw(plaintext.encode(), bcrypt.gensalt(rounds=4)).decode()
     async with factory() as s:
         key = ApiKey(

backend/tests/integration/api/test_rate_limit.py

@@ -19,8 +19,8 @@
 
 async def _insert_key(factory, *, rate_limit: int = 3, scopes=None):
     """Insert an API key with the given rate limit and return plaintext."""
-    plaintext = f"lh_ratelimit_test_{uuid4().hex[:20]}"
-    prefix = plaintext[:12]
+    plaintext = f"lh_pat_rlt_{uuid4().hex[:16]}"
+    prefix = plaintext[:16]
     hashed = bcrypt.hashpw(plaintext.encode(), bcrypt.gensalt(rounds=4)).decode()
     async with factory() as s:
         key = ApiKey(

backend/tests/unit/api/test_admin_api_keys_routes.py

@@ -66,7 +66,7 @@ async def test_list_api_keys_returns_existing_keys(session):
     key = ApiKey(
         name="existing-key",
         key_hash="fakehash",
-        key_prefix="lh_existing",
+        key_prefix="lh_pat_existg",
         scopes=["read"],
         allowed_printer_ids=[],
         enabled=True,
@@ -102,7 +102,7 @@ async def test_create_api_key_returns_plaintext_once(session):
     assert resp.status_code == 201
     body = resp.json()
     assert "plaintext" in body, "plaintext must be returned ONCE on creation"
-    assert body["plaintext"].startswith("lh_")
+    assert body["plaintext"].startswith("lh_pat_")
     assert "prefix" in body
     assert "key_id" in body
 
@@ -139,7 +139,7 @@ async def test_get_api_key_detail_returns_metadata(session):
     key = ApiKey(
         name="detail-key",
         key_hash="fakehash",
-        key_prefix="lh_detail",
+        key_prefix="lh_pat_detail",
         scopes=["print"],
         allowed_printer_ids=[],
         enabled=True,
@@ -170,7 +170,7 @@ async def test_patch_api_key_updates_fields(session):
     key = ApiKey(
         name="to-patch",
         key_hash="fakehash",
-        key_prefix="lh_topatch",
+        key_prefix="lh_pat_topatch",
         scopes=["read"],
         allowed_printer_ids=[],
         enabled=True,
@@ -201,7 +201,7 @@ async def test_delete_api_key_revokes_it(session):
     key = ApiKey(
         name="to-delete",
         key_hash="fakehash",
-        key_prefix="lh_todelete",
+        key_prefix="lh_pat_tdel",
         scopes=["read"],
         allowed_printer_ids=[],
         enabled=True,