.agent/PLATFORM_API_RULES.md

Feature Rules — Platform API Credentials (SuperAdmin)

Status: Implemented (ad1b7c6). Source of truth for retailer API key management.

1. Problem & scope

• User story: As platform operator, I enter optional paid retailer API keys in SuperAdmin so price/presence scans use reliable APIs instead of blocked free scraping — without exposing keys in env files or logs.
• In scope:
  • SuperAdmin UI to create/update/disable/delete per-platform credentials
  • Fernet encryption at rest in PostgreSQL
  • Provider registry (Rainforest, ScrapingBee, Google Books)
  • Priority resolution: SuperAdmin DB → env fallback → free logic
  • Integration with fetch_listing_price() during platform presence scans
  • Audit log on every mutation
  • Masked read API (never return raw keys)
• Out of scope:
  • Author-facing credential management (SuperAdmin only)
  • Billing/metering of third-party API usage
  • Presence scanning via paid APIs (future — pricing only today)
  • Goodreads / Open Library paid APIs (none exist)

2. Architecture decisions

Decision	Choice	Why
Storage	platform_api_credentials table	Auditable, encrypted, UI-manageable
Encryption	Fernet derived from SECRET_KEY	R-174; no plaintext in DB
Resolution	platform_api_registry.resolve_platform_credential()	Single place for priority chain
Providers	Strategy in registry (fetch_price_via_credential)	Open/closed — add provider without changing routes
Cache	Redis platform_api_cred:v1:{platform_id}, TTL 300s	Performance; invalidate on write (R-179)
Routes	Thin router → PlatformApiService	SRP; no logic in handlers
Env fallback	Documented in PLATFORM_API_META	Bootstrap only — not primary UX

Principles:

• Single responsibility — PlatformApiService CRUD; registry resolves/fetches
• Open/closed — new provider = new branch in registry, not new endpoint
• Dependency inversion — pricing calls registry, not HTTP directly from presence
• Thin client — UI posts key once; server encrypts, masks, audits
• Fail secure — no key → fall through; never log raw secrets

3. Data & security

• Tables/columns: platform_api_credentials (see migration 003_platform_api_credentials)
• Encryption at rest: yes — credential_crypto.encrypt_secret() / Fernet
• Who can read/write: role=superadmin only; mutations require JWT + TOTP (X-TOTP-Code)
• Audit log actions: upsert_platform_api, disable_platform_api, delete_platform_api
• Never log: raw api_key, api_secret, decrypted values; audit uses mask_secret() only

4. API contract

Method	Path	Auth	Request schema	Response
GET	/api/super/platform-apis	JWT + TOTP	—	list[PlatformApiCredentialView]
PUT	/api/super/platform-apis/{platform_id}	JWT + TOTP	PlatformApiCredentialUpsert	masked view
POST	/api/super/platform-apis/{platform_id}/disable	JWT + TOTP	—	masked view
DELETE	/api/super/platform-apis/{platform_id}	JWT + TOTP	—	masked view

• Pydantic only (PlatformApiCredentialUpsert) — R-180
• platform_id in path must match body on PUT

5. UI

• Location: SuperAdmin → Platform Settings → Retailer API Keys
• Complete UX path:
  1. Login (JWT)
  2. Complete TOTP enrollment if not configured (see SUPERADMIN_TOTP_RULES.md)
  3. Enter 6-digit TOTP in settings header
  4. Per platform: select provider → paste API key → Save / Disable / Remove
  5. Env-sourced keys show read-only env badge
• Error states: missing TOTP → toast; invalid provider → 400; unknown platform → 400

6. Priority / fallback chains

For each platform_id on price fetch:

1. SuperAdmin DB row (is_enabled=true) → fetch_price_via_credential()
2. Environment variable (see table below)
3. Built-in free logic (platform_pricing.py)

If step 1 fails (HTTP/parse), fall through to 2 then 3.

platform_id	SuperAdmin providers	Env fallback	Free fallback
amazon	rainforest, scrapingbee	RAINFOREST_API_KEY	US-locale HTML
google_books	google_books	GOOGLE_BOOKS_API_KEY	Anonymous Books API
barnes_noble	scrapingbee	—	HTML patterns
apple_books	scrapingbee	—	iTunes Lookup API
kobo	scrapingbee	—	HTML (often blocked)
thriftbooks	scrapingbee	—	HTML (often blocked)
abebooks	scrapingbee	—	HTML patterns
bookshop	scrapingbee	—	HTML (often blocked)
goodreads	—	—	from-price rollup
open_library	—	—	catalog "Free"

Never instruct operators to use HF Secrets or .env as the primary key entry path. Env is emergency/bootstrap only.

7. Provider contracts

google_books

• GET https://www.googleapis.com/books/v1/volumes/{id}?key=...&country=US
• ISBN fallback via q=isbn:{isbn13}

rainforest (Amazon only)

• GET https://api.rainforestapi.com/request?api_key=...&type=product&amazon_domain=amazon.com&asin={asin}

scrapingbee

• GET https://app.scrapingbee.com/api/v1?api_key=...&url={listing_url}&premium_proxy=true&country_code=us
• Parse via extract_price_from_html()

8. Tests

• Unit — tests/unit/test_platform_api_registry.py (priority, crypto, parsers)
• Unit — tests/unit/test_platform_api_service.py (upsert, audit, delete)
• Integration — SuperAdmin upsert happy path (mocked DB)
• BDD — see .agent/BDD_SPECS.md → Platform API Credentials

9. Definition of done

• Rules doc approved
• Migration 003_platform_api_credentials
• FILE_MAP.md updated
• End-to-end UI (requires TOTP enrollment)
• Pushed to hf/main

10. Rule IDs

• R-174: Fernet encrypt API keys at rest
• R-175: Mask secrets in API/audit/logs (•••• + last 4)
• R-176: Mutations require JWT + TOTP
• R-177: Audit every mutation
• R-178: SuperAdmin role only
• R-179: Redis cache TTL ≤ 300s; invalidate on write
• R-180: Pydantic schemas only on routes

11. File map

File	Role
app/core/crypto/credential_crypto.py	Encrypt/decrypt/mask
app/models/platform_api_credential.py	ORM model
app/repositories/platform_api_credential_repo.py	DB access
app/services/platform_api_registry.py	Resolution + providers
app/services/platform_api_service.py	CRUD + audit
app/superadmin/routers/platform_apis.py	HTTP routes
app/services/platform_pricing.py	Consumes credential in fetch_listing_price()