# 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.