feat(credentials): add stage 1 encrypted server-side credential storage

Introduce an opt-in AES-256-GCM credential store keyed by environment,
application and principal. Bind ciphertext to identity, version and key ID
with authenticated data; support retained decryption keys and active-key
rotation. Use expected-version CAS to reject duplicate or stale writers.

Keep token values and scopes encrypted at rest, hide token fields from
object repr, and use fixed errors without credential contents. Add tests
for identity substitution, authenticated tampering, wrong keys, rotation,
persistence, concurrent writers and malformed inputs. Include an opt-in
PostgreSQL test using an isolated schema.

Validation: 102 passed, 2 skipped (no real PostgreSQL URL), 15 existing
uvicorn/websockets deprecation warnings. Python AST and diff checks pass.

This is stage 1 only: no public routes or existing OAuth/refresh behavior
are changed, no production key/database is initialized, and no ECS
runtime deployment or real platform requests were performed. Broker,
centralized refresh, access-token-only issuance and unbind lifecycle
integration remain subsequent stages. See deployable/CREDENTIAL_MIGRATION.md.
This commit is contained in:
ex_tianzy
2026-11-04 10:04:42 +08:00
parent f5a38e0808
commit 71b9678d22
4 changed files with 458 additions and 0 deletions
+217
View File
@@ -0,0 +1,217 @@
"""Stage 1 confidentiality, isolation, persistence, rotation and write fencing."""
import base64
import json
import os
import sys
from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
from threading import Barrier
import pytest
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from relay.credential_store import CredentialConflict, CredentialError, CredentialKeyring, CredentialStore
from relay.store import Store
def payload(suffix="a"):
return dict(access_token="test-access-" + suffix, refresh_token="test-refresh-" + suffix,
access_expires_at=2000000000, refresh_expires_at=2100000000,
scopes=["scope:b", "scope:a", "scope:a"])
@pytest.fixture
def vault(tmp_path):
store = Store(tmp_path / "metadata.sqlite")
keys = CredentialKeyring("k1", {"k1": os.urandom(32)})
vault = CredentialStore(store, keys)
yield store, keys, vault
store.close()
def test_encrypted_persistent_and_no_secret_repr(vault, tmp_path):
store, keys, vault = vault
assert vault.get("test", "app", "alice") is None
assert vault.save("test", "app", "alice", expected_version=0, **payload()) == 1
value = vault.get("test", "app", "alice")
assert value.refresh_token == payload()["refresh_token"]
assert value.scopes == ("scope:a", "scope:b")
assert "test-access" not in repr(value) and "test-refresh" not in repr(value)
dump = "\n".join(store.db.iterdump())
assert "test-access" not in dump and "test-refresh" not in dump and "scope:a" not in dump
other = Store(tmp_path / "metadata.sqlite")
try:
assert CredentialStore(other, keys).get("test", "app", "alice") == value
finally:
other.close()
for path in tmp_path.glob("metadata.sqlite*"):
assert b"test-refresh" not in path.read_bytes()
def test_identity_isolation_and_ciphertext_substitution(vault):
store, keys, vault = vault
for identity in [("test", "app", "alice"), ("test", "app", "bob"),
("test", "other-app", "alice"), ("production", "app", "alice")]:
vault.save(*identity, expected_version=0, **payload(identity[-1]))
row = store.db.execute("SELECT ciphertext FROM work_credentials_v2 WHERE principal_id=? AND app_id=? AND environment=?",
("alice", "app", "test")).fetchone()
for where, args in [("principal_id=? AND app_id=? AND environment=?", ("bob", "app", "test")),
("principal_id=? AND app_id=? AND environment=?", ("alice", "other-app", "test")),
("principal_id=? AND app_id=? AND environment=?", ("alice", "app", "production"))]:
with store.db:
store.db.execute("UPDATE work_credentials_v2 SET ciphertext=? WHERE " + where, (row["ciphertext"], *args))
for identity in [("test", "app", "bob"), ("test", "other-app", "alice"), ("production", "app", "alice")]:
with pytest.raises(CredentialError, match="decryption failed"):
vault.get(*identity)
@pytest.mark.parametrize("column,value", [("ciphertext", "broken"), ("key_id", "missing"), ("credential_version", 9)])
def test_tampering_fails_closed(vault, column, value):
store, keys, vault = vault
vault.save("test", "app", "alice", expected_version=0, **payload())
with store.db:
store.db.execute(f"UPDATE work_credentials_v2 SET {column}=?", (value,))
with pytest.raises(CredentialError, match="decryption failed") as error:
vault.get("test", "app", "alice")
assert "test-refresh" not in str(error.value)
def test_modified_authenticated_ciphertext_and_wrong_key(vault):
store, _, vault = vault
vault.save("test", "app", "alice", expected_version=0, **payload())
wrong = CredentialStore(store, CredentialKeyring("k1", {"k1": os.urandom(32)}))
with pytest.raises(CredentialError, match="decryption failed"):
wrong.get("test", "app", "alice")
row = store.db.execute("SELECT ciphertext FROM work_credentials_v2").fetchone()
raw = bytearray(base64.b64decode(row["ciphertext"]))
raw[-1] ^= 1
with store.db:
store.db.execute("UPDATE work_credentials_v2 SET ciphertext=?",
(base64.b64encode(raw).decode(),))
with pytest.raises(CredentialError, match="decryption failed"):
vault.get("test", "app", "alice")
def test_cas_rejects_stale_create_update_and_missing_record(vault):
_, _, vault = vault
vault.save("test", "app", "alice", expected_version=0, **payload())
with pytest.raises(CredentialConflict):
vault.save("test", "app", "alice", expected_version=0, **payload("stale"))
assert vault.save("test", "app", "alice", expected_version=1, **payload("new")) == 2
with pytest.raises(CredentialConflict):
vault.save("test", "app", "alice", expected_version=1, **payload("stale"))
with pytest.raises(CredentialConflict):
vault.save("test", "app", "missing", expected_version=1, **payload())
assert vault.get("test", "app", "alice").refresh_token == "test-refresh-new"
def test_two_connections_only_one_writer_wins(vault, tmp_path):
_, keys, vault = vault
vault.save("test", "app", "alice", expected_version=0, **payload())
barrier = Barrier(2)
def write(suffix):
store = Store(tmp_path / "metadata.sqlite")
try:
candidate = CredentialStore(store, keys)
assert candidate.get("test", "app", "alice").version == 1
barrier.wait(timeout=10)
try:
candidate.save("test", "app", "alice", expected_version=1, **payload(suffix))
return "saved"
except CredentialConflict:
return "conflict"
finally:
store.close()
with ThreadPoolExecutor(max_workers=2) as pool:
assert sorted(pool.map(write, ["one", "two"])) == ["conflict", "saved"]
assert vault.get("test", "app", "alice").version == 2
def test_key_rotation_and_removed_key_fail_closed(vault):
store, keys, vault = vault
vault.save("test", "app", "alice", expected_version=0, **payload())
new_key = os.urandom(32)
rotated = CredentialStore(store, CredentialKeyring("k2", {**keys._keys, "k2": new_key}))
old = rotated.get("test", "app", "alice")
assert old.version == 1
no_old_key = CredentialStore(store, CredentialKeyring("k2", {"k2": new_key}))
with pytest.raises(CredentialError):
no_old_key.get("test", "app", "alice")
rotated.save("test", "app", "alice", expected_version=1, **payload("rotated"))
assert no_old_key.get("test", "app", "alice").refresh_token == "test-refresh-rotated"
@pytest.mark.parametrize("change", [dict(refresh_token=""), dict(access_token=None),
dict(access_expires_at=float("nan")), dict(refresh_expires_at=-1), dict(scopes="scope:a"),
dict(scopes=[1]), dict(access_expires_at=True), dict(refresh_expires_at=10**400)])
def test_invalid_payload_does_not_write(vault, change):
_, _, vault = vault
with pytest.raises(CredentialError):
vault.save("test", "app", "alice", expected_version=0, **{**payload(), **change})
assert vault.get("test", "app", "alice") is None
@pytest.mark.parametrize("version", [-1, True, "1", 2147483647])
def test_invalid_version_rejected(vault, version):
_, _, vault = vault
with pytest.raises(CredentialError, match="invalid credential version"):
vault.save("test", "app", "alice", expected_version=version, **payload())
def test_empty_identity_and_missing_key_file_fail_closed(vault, tmp_path):
_, _, vault = vault
with pytest.raises(CredentialError, match="invalid credential identity"):
vault.save("test", "app", "", expected_version=0, **payload())
with pytest.raises(CredentialError, match="cannot load"):
CredentialKeyring.from_file(tmp_path / "missing.json")
def test_key_file_validation_and_safe_errors(tmp_path):
path = tmp_path / "keyring.json"
key = os.urandom(32)
path.write_text(json.dumps({"active_key_id": "k1", "keys": {"k1": base64.b64encode(key).decode()}}))
ring = CredentialKeyring.from_file(path)
key_id, cipher = ring.encrypt(b"test-secret", b"context")
assert ring.decrypt(key_id, cipher, b"context") == b"test-secret"
for content in ["not-json-test-secret", '{"active_key_id":"k1","keys":{"k1":"test-secret"}}',
'{"active_key_id":"missing","keys":{}}', '[]']:
path.write_text(content)
with pytest.raises(CredentialError, match="cannot load") as error:
CredentialKeyring.from_file(path)
assert "test-secret" not in str(error.value)
@pytest.mark.skipif(not os.environ.get("HN_TEST_DATABASE_URL"), reason="real PostgreSQL URL not supplied")
def test_postgres_encryption_cas_and_schema_reentry(tmp_path):
"""Runs in a unique test schema only, never against existing production tables."""
import uuid
import psycopg
from psycopg import sql
from psycopg.conninfo import make_conninfo
url = os.environ["HN_TEST_DATABASE_URL"]
schema = "hn_credential_test_" + uuid.uuid4().hex
admin = psycopg.connect(url, autocommit=True)
admin.execute(sql.SQL("CREATE SCHEMA {}").format(sql.Identifier(schema)))
store = None
try:
store = Store(tmp_path / "unused.sqlite", make_conninfo(url, options=f"-c search_path={schema}"))
keys = CredentialKeyring("test-key", {"test-key": os.urandom(32)})
vault = CredentialStore(store, keys)
CredentialStore(store, keys) # Additive initialization is repeatable.
vault.save("test", "app", "alice", expected_version=0, **payload())
with pytest.raises(CredentialConflict):
vault.save("test", "app", "alice", expected_version=0, **payload("duplicate"))
assert vault.save("test", "app", "alice", expected_version=1, **payload("new")) == 2
with pytest.raises(CredentialConflict):
vault.save("test", "app", "alice", expected_version=1, **payload("stale"))
assert vault.get("test", "app", "alice").refresh_token == "test-refresh-new"
row = store.db.execute("SELECT ciphertext FROM work_credentials_v2").fetchone()
assert "test-refresh" not in row["ciphertext"]
finally:
if store:
store.close()
admin.execute(sql.SQL("DROP SCHEMA {} CASCADE").format(sql.Identifier(schema)))
admin.close()