Docs 00-shared OPEN-QUESTIONS.md
Open Questions & Spec Gaps
Gaps between the API (spec v1.4.0) and what the Hub clients need. Each has a working assumption so building can start; the "Status" column says what changed with v1.4.0.
| # | Topic | Gap | Working assumption | Affects | Status |
|---|---|---|---|---|---|
| 1 | Avatar upload | API stores avatar_url only; no upload endpoint |
A small signed-URL upload service, then PATCH the URL. Until it exists, avatar editing is hidden (initials shown). | ACC-01, APL-02 icon | Open |
| 2 | Push on Windows and Linux | The API's providers are APNs, FCM and Web Push only — no WNS, and Linux desktops have no push service | Windows and Linux poll unread-count / new inbox items (60 s while running, opt-in background) and raise local notifications and badges. Ask the API team whether to add a wns provider. |
NTF-*, Windows, Linux | Resolved for iOS/macOS/Android/Web by the API's Push Notifications; open for Windows (WNS) |
| 3 | Hub as an Application | Devices must belong to an Application | The Hub is the first-party Application app_hub: access_tier: free, receives_platform_notifications: true, visibility: internal, with APNs/FCM/Web Push credentials. iOS and macOS share one bundle id (Universal Purchase) because an Application has one APNs credential with one topic. Confirm with the API team that one APNs topic per Application is intended, or ask for multiple topics. |
CLIENT-ARCHITECTURE §2, §6 | Changed — was "Hub is not an Application" |
| 4 | SSO & passkeys | SSO callback returns 501; no WebAuthn endpoints | Buttons hidden behind sso / passkeys. |
AUTH-01 | Open |
| 5 | Role holders | No GET /users?role_id= filter |
"People with this role" hidden on ROL-02. | ROL-02 | Open |
| 6 | Bulk operations | No bulk endpoints except notifications/mark-read |
Bulk actions run one request per row (max 4 in parallel) with per-row results. Inbox "mark all read" uses the real bulk endpoint. | USR-01, ACX-05, NTF-01 | Partly resolved |
| 7 | Session and device names | Session has user_agent + ip_address; Device has an optional name |
Hub sends a descriptive User-Agent, and registers devices with a readable name ("Dana's iPhone", "Chrome on macOS") the person can rename in NTF-03. |
ACC-04, NTF-03 | Partly resolved |
| 8 | Locale list | No endpoint listing locales/time zones | Use the platform's locale and IANA lists. | SET-01 | Open |
| 9 | App launch contract | How each app receives the app token isn't standardized | launch_url with #app_token= by default; per-app override client-side until the API adds a field. |
APP-03 | Open |
| 10 | Store payment rules | Standard is now a consumer subscription ($6/user/month) that unlocks apps — App Store and Play generally require in-app purchase for digital subscriptions used in the app | Mobile shows plan status and "Manage billing"; the Upgrade button is flag-gated per store (billing_upgrade_ios, billing_upgrade_android) and defaults off until legal/policy review (US external-purchase link entitlement, other regions' rules, or adding StoreKit / Play Billing products that the API would need to recognize). Web, macOS (outside the Mac App Store build), Windows and Linux upgrade via Stripe Checkout. |
BIL-01/02/03 | Changed — was a B2B developer plan |
| 11 | Audit export | Phase 3 | Hidden behind audit_export. |
AUD-01 | Open |
| 12 | Org suspension by admins | Needs organizations.manage |
Org admins see no suspend control. | ORG-08 | Open |
| 13 | Test mode in UI | test_mode on users, keys, webhooks, devices, notifications, subscriptions |
Developer builds expose test-mode sign-in; test-mode devices register with APNs sandbox; test-mode checkout needs Stripe test mode (409 test_mode_billing_unavailable otherwise). |
AUTH-01, KEY-, NTF-, BIL-* | Extended |
| 14 | Web session storage | No OS secure store in browsers | Same-origin BFF holds the refresh token in an HttpOnly cookie. | Web | Open |
| 15 | CORS | Web app needs Authorization, Idempotency-Key, If-Match allowed and ETag, Retry-After, Audit-Hot-Window-Start exposed |
Confirm API CORS config for https://dashboard.substratalapps.com. |
Web | Open (header list extended) |
| 16 | Notifications not built yet | Every Notifications operation returns 501 not_implemented today |
Ship NTF-* and APL-07 behind notifications / push / push_credentials flags; 501 flips them off. |
D13, APL-07 | New |
| 17 | Erasure vs. billing | Deleting an account doesn't cancel a Stripe subscription | ACC-08 warns subscribers and links to Manage billing first. Ask the API team whether erasure should cancel at period end. | ACC-08 | New |
| 18 | Annual plans / Standard trial | DECISIONS #31 still open | No UI; BIL-01 copy avoids promising either. | BIL-01 | New |
| 19 | Price display | Price shown before a subscription exists isn't returned by any endpoint | Show "$6 per month" from remote config (matches Pricing), and unit_amount once a subscription exists. |
BIL-01/02 | New |
| 20 | Hub access disabled | An admin can disable someone's app_hub Entitlement |
They can still sign in to the Hub (platform session) but can't register devices (403) — inbox-only mode with an explanation in NTF-03. | NTF-03/04 | New |
| 21 | Notification actions from the lock screen | Accepting an org invitation from a notification needs a valid platform session | Mobile/macOS require device unlock and refresh the session in the background; if refresh fails, open the app to ORG-09. | ORG-09, NTF-02 | New |
| 22 | Theme choice storage | Settings only has theme (light/dark/system); there is no field for which light or dark theme |
Store appearance.light_theme / appearance.dark_theme as app_hub per-app settings, which requires both keys (string enums, defaults moss-paper / forest-floor) in app_hub's settings_schema. Until then, keep them on the device. Alternative: add light_theme / dark_theme to Settings. |
SET-01, THEMES.md | New |