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
@@ -19,10 +19,26 @@ As a developer, I want to properly register my application with a unique App ID

 ## Technical Notes
 - Current client has `id: ''` placeholder (TODO in code)
- Need Application model in database
- App credentials similar to OAuth client credentials
+- App ID is now part of the unified Apps model (`IApp` discriminated union)
+- Three app types exist: Global Apps, Partner Apps, Custom OIDC Apps
+- For custom applications, use the Custom OIDC Apps flow (ORG-011)
+- App credentials stored as `IOAuthCredentials` with hashed client secret
 - Validate redirect URIs to prevent open redirector attacks
- App ID should be included in JWT claims
+- App ID/Client ID is included in JWT claims
+
+## Apps Architecture
+
+The Apps system supports three types:
+1. **Global Apps** (ORG-009) - First-party platform apps (foss.global, task.vc)
+2. **Partner Apps** (ORG-010, DEV-008) - AppStore model for third-party apps
+3. **Custom OIDC Apps** (ORG-011) - Organization-created OAuth/OIDC clients
+
+## Related Stories
+- ORG-009: Connect Global Apps
+- ORG-010: Browse and Install Partner Apps
+- ORG-011: Create Custom OIDC Apps
+- DEV-005: Register OAuth Client App
+- DEV-008: Submit App to AppStore

 ## Related TODOs
 - `ts_idpclient/classes.idpclient.ts:30` - `id: '', // TODO`
@@ -18,11 +18,34 @@ As a developer, I want to register my application as an OAuth client so that use
 - [ ] Client credentials flow for server-to-server

 ## Technical Notes
- OAuth keywords in package.json suggest this is planned
- Implement OAuth 2.0 authorization server endpoints
+- OAuth/OIDC client registration is now part of the Apps system
+- **For organization owners**: Use Custom OIDC Apps (ORG-011) to create OAuth clients
+- **For third-party developers**: Submit to AppStore (DEV-008) for public apps
+- Standard OAuth 2.0 / OpenID Connect flows supported
 - Scopes: openid, profile, email, organizations
- Consider OpenID Connect for identity layer
 - PKCE is required for mobile and SPA security

+## Implementation Path
+
+This story's functionality is now implemented through:
+1. **Custom OIDC Apps** (ORG-011) - Create org-specific OAuth clients via the Apps UI
+2. **Partner Apps** (DEV-008) - Submit public apps to the AppStore
+
+Both use the same underlying `IOAuthCredentials` model:
+```typescript
+interface IOAuthCredentials {
+  clientId: string;
+  clientSecretHash: string;
+  redirectUris: string[];
+  allowedScopes: string[];
+  grantTypes: ('authorization_code' | 'client_credentials' | 'refresh_token')[];
+}
+```
+
+## Related Stories
+- ORG-011: Create Custom OIDC Apps (primary implementation)
+- DEV-004: Proper App ID Initialization
+- DEV-008: Submit App to AppStore
+
 ## Related TODOs
 - New feature - OAuth server implementation
@@ -0,0 +1,70 @@
+# Submit App to AppStore
+
+**ID:** DEV-008
+**Priority:** Low
+**Status:** Planned
+**Phase:** 4
+
+## User Story
+As a developer, I want to submit my application to the AppStore so that other organizations can discover and install my app.
+
+## Acceptance Criteria
+- [ ] Submit a new app to the AppStore
+- [ ] Provide app name, description, and logo
+- [ ] Add screenshots for the store listing
+- [ ] Select app category and tags
+- [ ] Set pricing model (free, paid, freemium)
+- [ ] Configure OAuth credentials (redirect URIs, scopes)
+- [ ] Submit for review
+- [ ] View submission status (draft, pending_review, approved, rejected, suspended)
+- [ ] Receive notification on approval/rejection
+- [ ] Edit app listing after approval
+- [ ] View app analytics (install count, usage)
+
+## Technical Notes
+- Submitter organization becomes `ownerOrganizationId`
+- Apps start in `draft` status, move to `pending_review` on submit
+- Platform admins review and approve/reject apps
+- Approved apps become visible in the AppStore
+- App updates may require re-approval
+
+## Approval Workflow
+
+```
+draft → pending_review → approved → published
+                      ↘ rejected
+
+approved ↔ suspended (admin action)
+```
+
+## Data Model
+
+```typescript
+interface IPartnerApp {
+  id: string;
+  type: 'partner';
+  data: {
+    ownerOrganizationId: string;
+    appStoreMetadata: {
+      shortDescription: string;
+      longDescription: string;
+      screenshots: string[];
+      category: string;
+      tags: string[];
+      pricing: { model: 'free' | 'paid' | 'freemium' };
+    };
+    approvalStatus: 'draft' | 'pending_review' | 'approved' | 'rejected' | 'suspended';
+    isPublished: boolean;
+    installCount: number;
+    // ... other fields
+  };
+}
+```
+
+## UI Components
+- **AppSubmissionView** (`/account/org/:orgName/apps/submit`) - Submit new partner app form
+
+## Related Stories
+- ORG-010: Browse and Install Partner Apps
+- ORG-011: Create Custom OIDC Apps
+- ADM-008: Review Partner App Submissions (new admin story)