Rocky
0af35d44f4
Provide the production foundation for Apple identity, immutable credits, referrals, integrity checks, managed providers, and hardened Docker deployment.
67 lines
3.0 KiB
Markdown
67 lines
3.0 KiB
Markdown
# 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.
|