feat(apps): Add Apps subsystem: App and AppConnection models, managers, typed request handlers, web UI routes and documentation

2025-12-01 09:18:48 +00:00
parent f54588e877
commit 6b04c529da
28 changed files with 1491 additions and 21 deletions
@@ -0,0 +1,130 @@
+# Manage Global Apps
+
+**ID:** ADM-008
+**Priority:** High
+**Status:** In Development
+**Phase:** 1
+
+## User Story
+As a global administrator, I want to create, configure, and manage first-party global apps (foss.global, task.vc, etc.) so that organization owners can connect to these integrated services.
+
+## Acceptance Criteria
+- [ ] Only users with `isGlobalAdmin: true` can access the admin page
+- [ ] View list of all global apps with their status
+- [ ] Create new global apps with OAuth credentials
+- [ ] Edit existing global app details (name, description, logo, URLs)
+- [ ] Activate/deactivate global apps (inactive apps hidden from org owners)
+- [ ] View connection statistics per app (how many orgs connected)
+- [ ] Regenerate OAuth client credentials for an app
+- [ ] Delete global apps (with confirmation and impact warning)
+- [ ] Admin page accessible at `/admin` route
+
+## Technical Notes
+- Global admin flag stored on user: `isGlobalAdmin: boolean`
+- Separate from organization roles (platform-level permission)
+- OAuth credentials generated server-side, secrets never exposed in full
+- App deletion should warn about existing connections
+- Audit logging for all admin actions
+
+## Data Model
+
+```typescript
+interface IUser {
+  id: string;
+  data: {
+    // ... existing fields ...
+    isGlobalAdmin?: boolean; // Platform-level admin flag
+  };
+}
+
+interface IGlobalApp {
+  id: string;
+  type: 'global';
+  data: {
+    name: string;
+    description: string;
+    logoUrl: string;
+    appUrl: string;
+    oauthCredentials: IOAuthCredentials;
+    isActive: boolean;
+    category: string;
+    createdAt: number;
+    createdByUserId: string;
+  };
+}
+```
+
+## Request Interfaces
+
+```typescript
+interface IReq_CreateGlobalApp {
+  method: 'createGlobalApp';
+  request: {
+    jwt: string;
+    name: string;
+    description: string;
+    logoUrl: string;
+    appUrl: string;
+    category: string;
+    redirectUris: string[];
+    allowedScopes: string[];
+  };
+  response: {
+    app: IGlobalApp;
+    clientSecret: string; // Only shown once on creation
+  };
+}
+
+interface IReq_UpdateGlobalApp {
+  method: 'updateGlobalApp';
+  request: {
+    jwt: string;
+    appId: string;
+    updates: Partial<IGlobalApp['data']>;
+  };
+  response: {
+    app: IGlobalApp;
+  };
+}
+
+interface IReq_DeleteGlobalApp {
+  method: 'deleteGlobalApp';
+  request: {
+    jwt: string;
+    appId: string;
+  };
+  response: {
+    success: boolean;
+    disconnectedOrganizations: number;
+  };
+}
+
+interface IReq_GetGlobalAppStats {
+  method: 'getGlobalAppStats';
+  request: {
+    jwt: string;
+  };
+  response: {
+    apps: Array<{
+      app: IGlobalApp;
+      connectionCount: number;
+    }>;
+  };
+}
+```
+
+## UI Components
+- **GlobalAdminView** (`/admin`) - Main admin dashboard
+- **Global Apps Tab** - List of global apps with CRUD operations
+- **Create/Edit App Dialog** - Form for app configuration
+- Navigation shows "Admin" link only for global admins
+
+## Security Considerations
+- Server-side validation of `isGlobalAdmin` flag on all admin endpoints
+- JWT must be validated and user's admin status checked
+- Rate limiting on credential regeneration
+- Audit trail for all changes
+
+## Related Stories
+- ORG-009: Connect Global Apps (organization perspective)
+- ADM-003: Platform-wide Audit Logging