Establish secure account and managed AI backend

Provide the production foundation for Apple identity, immutable credits, referrals, integrity checks, managed providers, and hardened Docker deployment.
2026-08-16 14:46:23 +08:00
commit 0af35d44f4
124 changed files with 21052 additions and 0 deletions
@@ -0,0 +1,66 @@
+# OSGAccountServer architecture
+
+OSGAccountServer is a modular Ktor application. It owns OSG accounts, credits,
+referrals, integrity checks, and metered access to OSG-hosted providers.
+
+It does not replace the app's local ASR, BYOK provider access, or iCloud sync.
+
+## Trust boundaries
+
+1. Sign in with Apple identifies a user. The service stores only Apple's stable
+   subject, encrypted Apple refresh credentials, and internal identifiers.
+2. The host app owns account-management credentials in its private Keychain.
+3. The keyboard extension receives a separately revocable gateway grant. That
+   grant cannot delete an account, redeem referrals, or mutate credits directly.
+4. Provider credentials exist only in the server process.
+5. Audio and text are transient request data. They must not be persisted or
+   included in logs, traces, metrics labels, or error messages.
+
+## Modules
+
+- `auth` verifies Apple credentials and manages rotating application sessions.
+- `account` reads and deletes accounts.
+- `appleevents` handles consent and account lifecycle notifications.
+- `credits` owns the immutable ledger and its balance projection.
+- `referrals` binds one inviter and awards both users after qualified usage.
+- `integrity` evaluates DeviceCheck and App Attest evidence.
+- `gateway` proxies Volcengine ASR and DeepSeek text requests.
+- `inviteweb` serves the first-party invitation landing page.
+
+Modules communicate through narrow ports. Provider clients, Apple clients,
+integrity clients, clocks, token generators, and repositories are replaceable in
+tests.
+
+## Monetary invariants
+
+- Credit amounts are signed 64-bit integers; public inputs never accept decimal
+  credit values.
+- Ledger rows are immutable.
+- Every mutation has a unique idempotency key.
+- Available and reserved balances never become negative.
+- Reservation, settlement, release, refund, and referral rewards run in database
+  transactions with the account rows locked.
+- A referral can transition to `rewarded` exactly once.
+- Usage records reference the exact rate-card version used for settlement.
+
+## Hosted request lifecycle
+
+1. Authenticate a gateway-scoped principal and verify request integrity.
+2. Validate payload size and feature-specific policy.
+3. Reserve the maximum expected credits.
+4. Call the allowlisted upstream provider.
+5. Settle from provider usage or server-observed ASR duration.
+6. Release on transport/provider failure or empty output.
+7. Qualify a pending referral only after a successful non-zero settlement.
+
+## Data retention
+
+- No audio, transcript, prompt, context, or generated response body is stored.
+- Authentication and integrity payloads are retained only as hashes or validated
+  claims required for replay protection.
+- Usage metadata contains feature, model, metering units, latency, status, and
+  rate-card version.
+- Operational logs use request IDs and internal opaque IDs, never Apple subjects
+  or bearer credentials.
+- Account deletion revokes credentials and removes user-linked records. Only
+  non-identifying aggregate service metrics may remain.