From f8e1a9457f54287f8be527adf039b7c7edddf404 Mon Sep 17 00:00:00 2001 From: Alessandro Franceschi Date: Wed, 10 Jun 2026 13:37:58 +0200 Subject: [PATCH 01/13] feat(auth): add Azure Entra ID (OpenID Connect) authentication - Add EntraIdService with OAuth 2.0 Authorization Code Flow and PKCE support - Implement ID token validation via JWKS with configurable caching - Add federated identity provisioning and account linking on first SSO login - Support automatic group-to-role synchronization from Entra ID claims - Add database migrations for federated_identities and oauth_state_store tables - Create /api/auth/entra-id/* routes for login, callback, and token exchange - Add EntraIdLoginButton component with Microsoft branding for frontend - Implement server-side ephemeral state store with 10-minute TTL - Add single-use authorization code flow for secure frontend token delivery - Update authentication middleware to treat federated and local auth identically - Add comprehensive unit, integration, and property-based test coverage - Update configuration schema and environment examples for Entra ID setup - Add Entra ID integration documentation with setup and group mapping examples - Ensure zero disruption to existing local authentication flows --- .kiro/specs/azure-entra-id-auth/.config.kiro | 1 + .kiro/specs/azure-entra-id-auth/design.md | 509 ++++++++++ .../specs/azure-entra-id-auth/requirements.md | 173 ++++ .kiro/specs/azure-entra-id-auth/tasks.md | 243 +++++ AGENTS.md | 4 +- backend/.env.example | 34 + backend/src/config/ConfigService.ts | 106 ++ backend/src/config/schema.ts | 18 + backend/src/container/DIContainer.ts | 2 + .../database/migrations/016_entra_id_auth.sql | 48 + .../migrations/017_nullable_password_hash.sql | 39 + backend/src/routes/auth.ts | 59 ++ backend/src/routes/entraIdAuth.ts | 264 +++++ backend/src/server.ts | 70 ++ backend/src/services/EntraIdService.ts | 902 ++++++++++++++++++ backend/src/services/UserService.ts | 215 +++++ .../database/migration-integration.test.ts | 10 +- backend/test/database/rbac-schema.test.ts | 2 +- .../test/integration/EntraIdAuthFlow.test.ts | 639 +++++++++++++ .../EntraIdAuthCode.property.test.ts | 377 ++++++++ .../EntraIdCallback.property.test.ts | 637 +++++++++++++ .../EntraIdGroupSync.property.test.ts | 462 +++++++++ .../EntraIdProviders.property.test.ts | 223 +++++ .../EntraIdProvisioning.property.test.ts | 519 ++++++++++ .../test/unit/services/EntraIdService.test.ts | 656 +++++++++++++ docs/api.md | 38 +- docs/architecture.md | 3 + docs/configuration.md | 18 + docs/integrations/entra-id.md | 149 +++ docs/permissions-rbac.md | 21 + .../src/components/EntraIdLoginButton.svelte | 32 + .../src/components/EntraIdLoginButton.test.ts | 68 ++ frontend/src/lib/auth.svelte.ts | 30 +- frontend/src/lib/entraIdAuth.svelte.test.ts | 180 ++++ frontend/src/lib/entraIdAuth.svelte.ts | 127 +++ frontend/src/pages/LoginPage.svelte | 288 ++++-- frontend/src/pages/LoginPage.test.ts | 161 ++++ scripts/setup.sh | 47 + 38 files changed, 7272 insertions(+), 102 deletions(-) create mode 100644 .kiro/specs/azure-entra-id-auth/.config.kiro create mode 100644 .kiro/specs/azure-entra-id-auth/design.md create mode 100644 .kiro/specs/azure-entra-id-auth/requirements.md create mode 100644 .kiro/specs/azure-entra-id-auth/tasks.md create mode 100644 backend/src/database/migrations/016_entra_id_auth.sql create mode 100644 backend/src/database/migrations/017_nullable_password_hash.sql create mode 100644 backend/src/routes/entraIdAuth.ts create mode 100644 backend/src/services/EntraIdService.ts create mode 100644 backend/test/integration/EntraIdAuthFlow.test.ts create mode 100644 backend/test/properties/EntraIdAuthCode.property.test.ts create mode 100644 backend/test/properties/EntraIdCallback.property.test.ts create mode 100644 backend/test/properties/EntraIdGroupSync.property.test.ts create mode 100644 backend/test/properties/EntraIdProviders.property.test.ts create mode 100644 backend/test/properties/EntraIdProvisioning.property.test.ts create mode 100644 backend/test/unit/services/EntraIdService.test.ts create mode 100644 docs/integrations/entra-id.md create mode 100644 frontend/src/components/EntraIdLoginButton.svelte create mode 100644 frontend/src/components/EntraIdLoginButton.test.ts create mode 100644 frontend/src/lib/entraIdAuth.svelte.test.ts create mode 100644 frontend/src/lib/entraIdAuth.svelte.ts create mode 100644 frontend/src/pages/LoginPage.test.ts diff --git a/.kiro/specs/azure-entra-id-auth/.config.kiro b/.kiro/specs/azure-entra-id-auth/.config.kiro new file mode 100644 index 00000000..88d16210 --- /dev/null +++ b/.kiro/specs/azure-entra-id-auth/.config.kiro @@ -0,0 +1 @@ +{"specId": "2cd475d9-ff37-4ae1-af19-3e546cc2ffff", "workflowType": "requirements-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/azure-entra-id-auth/design.md b/.kiro/specs/azure-entra-id-auth/design.md new file mode 100644 index 00000000..57a7e5fa --- /dev/null +++ b/.kiro/specs/azure-entra-id-auth/design.md @@ -0,0 +1,509 @@ +# Design Document: Azure Entra ID Authentication + +## Overview + +This design adds Azure Entra ID (OpenID Connect) as a federated authentication provider to Pabawi, running alongside the existing local username/password flow. The implementation follows the OAuth 2.0 Authorization Code Flow with PKCE, validates ID tokens via JWKS, and issues standard Pabawi JWT tokens so that downstream middleware and RBAC remain unaware of the authentication origin. + +Key design goals: +- **Zero disruption** to existing auth flows — local login continues unchanged +- **Identical JWT tokens** regardless of authentication method — auth middleware sees no difference +- **Automatic user provisioning** on first SSO login with optional account linking +- **Group-to-role synchronization** from Entra ID claims to Pabawi RBAC +- **Security-first** — PKCE, state/nonce validation, JWKS signature verification, short-lived ephemeral state + +## Architecture + +### High-Level Integration + +```mermaid +graph TB + subgraph Frontend + LP[Login Page] + AC[Auth Callback Handler] + end + + subgraph Backend + AR[Auth Routes - /api/auth/entra-id/*] + EIS[EntraIdService] + AS[AuthenticationService] + US[UserService] + RS[RoleService] + CS[ConfigService] + DB[(Database)] + SS[(State Store - DB)] + end + + subgraph External + ENTRA[Azure Entra ID] + JWKS[JWKS Endpoint] + end + + LP -->|1. Click SSO| AR + AR -->|2. 302 Redirect| ENTRA + ENTRA -->|3. Callback with code| AR + AR -->|4. Token exchange| ENTRA + AR -->|5. Validate ID token| JWKS + EIS -->|6. Provision/link user| US + EIS -->|7. Sync roles| RS + EIS -->|8. Issue Pabawi JWT| AS + AR -->|9. Redirect with auth code| AC + AC -->|10. Exchange code for tokens| AR +``` + +### Architectural Decisions + +| Decision | Rationale | +|----------|-----------| +| New `EntraIdService` class (not a BasePlugin) | This is an auth provider, not an infrastructure integration. Plugins are for inventory/execution sources. | +| Server-side state store in DB table | Supports clustered deployments; avoids in-memory state loss on restart. 10-minute TTL with cleanup. | +| Single-use authorization code for frontend token delivery | Prevents token exposure in URL fragments/history. Frontend exchanges ephemeral code for actual JWT pair. | +| JWKS caching with configurable TTL | Avoids hitting Microsoft on every login while allowing key rotation detection. | +| Group-to-role sync at login time only | Avoids continuous polling of Entra ID; roles reflect state at last login. | + +## Components and Interfaces + +### New Files + +| File | Purpose | +|------|---------| +| `backend/src/services/EntraIdService.ts` | Core SSO logic: authorization URL generation, token exchange, ID token validation, JWKS management, user provisioning orchestration | +| `backend/src/routes/entraIdAuth.ts` | Express route factory: `/api/auth/entra-id/login`, `/callback`, `/token`, and `/api/auth/providers` | +| `backend/src/database/migrations/016_entra_id_auth.sql` | New tables: `federated_identities`, `oauth_state_store` | +| `frontend/src/lib/entraIdAuth.svelte.ts` | Frontend SSO state: provider discovery, callback handling | +| `frontend/src/components/EntraIdLoginButton.svelte` | Microsoft-branded SSO button component | + +### Modified Files + +| File | Change | +|------|--------| +| `backend/src/config/ConfigService.ts` | Add Entra ID configuration parsing block | +| `backend/src/config/schema.ts` | Add `EntraIdConfigSchema` to Zod schemas | +| `backend/src/routes/auth.ts` | Add `/providers` endpoint; modify logout to include `entraIdLogoutUrl` | +| `backend/src/services/UserService.ts` | Add `createFederatedUser()` and `linkFederatedIdentity()` methods | +| `backend/src/container/DIContainer.ts` | Register `EntraIdService` in `ServiceRegistry` (optional, only when enabled) | +| `frontend/src/pages/Login.svelte` | Conditionally render SSO button based on provider discovery | + +### EntraIdService Interface + +```typescript +export interface EntraIdConfig { + enabled: boolean; + tenantId: string; + clientId: string; + clientSecret: string; + redirectUri: string; + scopes: string[]; + groupMapping: Record | null; + postLogoutRedirectUri: string; + jwksCacheTtlMs: number; +} + +export interface OAuthStateEntry { + state: string; + nonce: string; + codeVerifier: string; + createdAt: string; // ISO 8601 + expiresAt: string; // ISO 8601, createdAt + 10 minutes +} + +export interface AuthCodeEntry { + code: string; + accessToken: string; + refreshToken: string; + userId: string; + idToken: string; // stored for logout id_token_hint + authMethod: string; // 'entra-id' + createdAt: string; + expiresAt: string; // createdAt + 60 seconds +} + +export class EntraIdService { + constructor( + db: DatabaseAdapter, + config: EntraIdConfig, + authService: AuthenticationService, + userService: UserService, + roleService: RoleService, + auditLogger: AuditLoggingService, + logger: LoggerService, + ); + + /** Generate authorization URL and store state/nonce/PKCE verifier */ + generateAuthorizationUrl(): Promise<{ url: string; state: string }>; + + /** Handle callback: validate state, exchange code, validate ID token, provision user, issue tokens */ + handleCallback(code: string, state: string): Promise; + + /** Exchange frontend auth code for tokens */ + exchangeAuthCode(code: string): Promise<{ accessToken: string; refreshToken: string; user: UserDTO }>; + + /** Build Entra ID logout URL for single sign-out */ + buildLogoutUrl(idToken: string): string; + + /** Get provider info for discovery endpoint */ + getProviderInfo(): { enabled: true; name: string }; + + /** Cleanup expired state entries (called periodically) */ + cleanupExpiredState(): Promise; +} +``` + +### Route Factory + +```typescript +// backend/src/routes/entraIdAuth.ts +export function createEntraIdAuthRouter( + databaseService: DatabaseService, + container: DIContainer, +): Router; +``` + +Endpoints: +- `GET /api/auth/entra-id/login` → 302 redirect to Entra ID authorization endpoint +- `GET /api/auth/entra-id/callback` → handles OAuth callback, redirects to frontend with auth code +- `POST /api/auth/entra-id/token` → exchanges single-use auth code for Pabawi JWT pair +- `GET /api/auth/providers` → returns available auth methods (public, no auth required) + +## Data Models + +### Database Schema (Migration 016) + +```sql +-- Migration 016: Entra ID federated authentication support + +-- Federated identity links: maps external IdP subjects to Pabawi users +CREATE TABLE IF NOT EXISTS federated_identities ( + id TEXT PRIMARY KEY, + user_id TEXT NOT NULL, + provider TEXT NOT NULL, -- 'entra-id' + subject TEXT NOT NULL, -- Entra ID 'sub' claim (unique per tenant+user) + issuer TEXT NOT NULL, -- Token issuer URL + email TEXT, -- Email from IdP (informational, not authoritative) + id_token TEXT, -- Last ID token (for logout id_token_hint) + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL, + FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE, + UNIQUE(provider, subject) +); + +CREATE INDEX IF NOT EXISTS idx_federated_identities_user ON federated_identities(user_id); +CREATE INDEX IF NOT EXISTS idx_federated_identities_lookup ON federated_identities(provider, subject); + +-- OAuth state store: PKCE + state + nonce for in-flight authorization requests +CREATE TABLE IF NOT EXISTS oauth_state_store ( + state TEXT PRIMARY KEY, + nonce TEXT NOT NULL, + code_verifier TEXT NOT NULL, + created_at TEXT NOT NULL, + expires_at TEXT NOT NULL +); + +CREATE INDEX IF NOT EXISTS idx_oauth_state_expires ON oauth_state_store(expires_at); + +-- Single-use authorization codes for frontend token delivery +CREATE TABLE IF NOT EXISTS oauth_auth_codes ( + code TEXT PRIMARY KEY, + access_token TEXT NOT NULL, + refresh_token TEXT NOT NULL, + user_id TEXT NOT NULL, + id_token TEXT, + auth_method TEXT NOT NULL DEFAULT 'entra-id', + created_at TEXT NOT NULL, + expires_at TEXT NOT NULL, + exchanged INTEGER NOT NULL DEFAULT 0 +); + +CREATE INDEX IF NOT EXISTS idx_oauth_auth_codes_expires ON oauth_auth_codes(expires_at); +``` + +### TypeScript Interfaces + +```typescript +interface FederatedIdentity { + id: string; + userId: string; + provider: string; + subject: string; + issuer: string; + email: string | null; + idToken: string | null; + createdAt: string; + updatedAt: string; +} +``` + +### Configuration Schema (Zod) + +```typescript +export const EntraIdConfigSchema = z.object({ + enabled: z.boolean().default(false), + tenantId: z.string().min(1), + clientId: z.string().min(1), + clientSecret: z.string().min(1), + redirectUri: z.string().url(), + scopes: z.array(z.string()).default(['openid', 'profile', 'email']), + groupMapping: z.record(z.string(), z.string()).nullable().default(null), + postLogoutRedirectUri: z.string().url().optional(), + jwksCacheTtlMs: z.number().int().positive().default(86400000), // 24 hours +}); +``` + +The `ConfigService` parsing block follows the same pattern as other integrations: +- `ENTRA_ID_ENABLED !== "true"` → skip entirely, no other vars required +- `ENTRA_ID_ENABLED === "true"` → parse and validate all required vars; throw on missing/invalid + +## OAuth 2.0 Flow Sequence + +```mermaid +sequenceDiagram + participant U as User Browser + participant FE as Frontend + participant BE as Backend (EntraIdService) + participant DB as Database + participant AAD as Azure Entra ID + + Note over U,AAD: Phase 1: Initiation + U->>FE: Click "Sign in with Microsoft" + FE->>BE: GET /api/auth/entra-id/login + BE->>BE: Generate state (32 bytes), nonce (32 bytes), code_verifier (43-128 chars) + BE->>BE: Compute code_challenge = BASE64URL(SHA256(code_verifier)) + BE->>DB: Store {state, nonce, code_verifier} with 10min TTL + BE->>U: 302 → https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?... + + Note over U,AAD: Phase 2: User Authentication (at Microsoft) + U->>AAD: Authenticate (credentials, MFA, etc.) + AAD->>U: 302 → redirect_uri?code=...&state=... + + Note over U,AAD: Phase 3: Callback Processing + U->>BE: GET /api/auth/entra-id/callback?code=...&state=... + BE->>DB: Lookup state entry, verify not expired + BE->>DB: Delete state entry (one-time use) + BE->>AAD: POST /oauth2/v2.0/token {code, code_verifier, client_secret, ...} + AAD-->>BE: {access_token, id_token, ...} + + Note over U,AAD: Phase 4: Token Validation + BE->>AAD: GET /discovery/v2.0/keys (JWKS, cached) + BE->>BE: Verify ID token signature (RS256) + BE->>BE: Validate nonce, aud, iss, exp claims + + Note over U,AAD: Phase 5: User Provisioning + BE->>DB: Lookup federated_identities WHERE provider='entra-id' AND subject=sub + alt New user + BE->>DB: Check users WHERE email = id_token.email + alt Email match exists + BE->>DB: Link federated identity to existing user + else No match + BE->>DB: Create new user (federation-only, null password_hash) + BE->>DB: Assign default role + end + end + BE->>BE: Sync group-to-role mapping (if configured) + + Note over U,AAD: Phase 6: Session Issuance + BE->>BE: Generate Pabawi JWT (access + refresh) via AuthenticationService + BE->>DB: Store single-use auth code → tokens mapping (60s TTL) + BE->>DB: Update last_login_at + BE->>DB: Write audit log (AUTH, LOGIN_SUCCESS, method=entra-id) + BE->>U: 302 → frontend_url?code=auth_code + + Note over U,AAD: Phase 7: Frontend Token Exchange + U->>FE: Page loads with ?code= parameter + FE->>BE: POST /api/auth/entra-id/token {code} + BE->>DB: Lookup auth code, verify not expired/exchanged + BE->>DB: Mark auth code as exchanged + BE-->>FE: {token, refreshToken, user} + FE->>FE: Store in authManager, navigate to landing page +``` + +## Error Handling + +| Scenario | HTTP Status | Error Code | Response | +|----------|-------------|------------|----------| +| Entra ID disabled, SSO endpoint hit | 404 | — | Standard 404 | +| Missing/invalid state on callback | 400 | `INVALID_STATE` | State parameter missing or mismatched | +| State expired (>10 min) | 400 | `SESSION_EXPIRED` | Authentication session expired | +| Token exchange failure (non-2xx from AAD) | 401 | `TOKEN_EXCHANGE_FAILED` | Could not exchange authorization code | +| Token exchange network timeout (>10s) | 401 | `TOKEN_EXCHANGE_FAILED` | Token endpoint unreachable | +| ID token signature invalid | 401 | `INVALID_ID_TOKEN` | Token signature verification failed | +| ID token nonce mismatch | 401 | `INVALID_ID_TOKEN` | Token nonce validation failed | +| ID token aud/iss mismatch | 401 | `INVALID_ID_TOKEN` | Token audience/issuer mismatch | +| ID token expired (>5min skew) | 401 | `INVALID_ID_TOKEN` | Token has expired | +| AAD returns error parameter | 401 | `AUTH_PROVIDER_ERROR` | Includes AAD error + description | +| Missing email/preferred_username claims | 401 | `MISSING_CLAIMS` | Required identity claims absent | +| User provisioning DB failure | 500 | `PROVISIONING_FAILED` | Account creation failed | +| Auth code expired or already exchanged | 400 | `INVALID_AUTH_CODE` | Authorization code invalid | +| JWKS endpoint unreachable, no cache | 503 | `JWKS_UNAVAILABLE` | Cannot verify token signatures | +| Config missing at request time | 500 | `SERVER_CONFIGURATION_ERROR` | Server configuration problem | + +All error responses follow the existing `{ error: { code, message } }` pattern from `utils/errorHandling.ts`. + +Sensitive values (client_secret, authorization codes, tokens) are never logged. The `LoggerService` calls use only metadata like `{ component: 'EntraIdService', operation: 'handleCallback' }`. + + +## Correctness Properties + +*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* + +### Property 1: Non-"true" ENTRA_ID_ENABLED skips config validation + +*For any* string value of `ENTRA_ID_ENABLED` that is not exactly `"true"` (including undefined, empty, "false", "yes", "1", random strings), the ConfigService SHALL parse without error and without requiring any other `ENTRA_ID_*` variables. + +**Validates: Requirements 1.1** + +### Property 2: Missing required variables produce comprehensive error + +*For any* non-empty subset of the required variables (`ENTRA_ID_TENANT_ID`, `ENTRA_ID_CLIENT_ID`, `ENTRA_ID_CLIENT_SECRET`, `ENTRA_ID_REDIRECT_URI`) that are undefined or empty when `ENTRA_ID_ENABLED` is `"true"`, the ConfigService SHALL throw an error whose message contains the name of every missing variable in that subset. + +**Validates: Requirements 1.2, 1.3** + +### Property 3: Scope parsing discards empty entries + +*For any* comma-separated string set as `ENTRA_ID_SCOPES`, the parsed scope array SHALL contain no empty strings, and when `ENTRA_ID_SCOPES` is unset, the result SHALL default to `["openid", "profile", "email"]`. + +**Validates: Requirements 1.4** + +### Property 4: Group mapping JSON round-trip + +*For any* valid `Record` object serialized as JSON and set as `ENTRA_ID_GROUP_MAPPING`, the parsed configuration SHALL produce an equivalent object. For any string that is not valid JSON or does not parse to a `Record`, parsing SHALL throw a validation error. + +**Validates: Requirements 1.5, 1.6** + +### Property 5: Authorization URL contains all required parameters + +*For any* valid Entra ID configuration (tenant_id, client_id, redirect_uri, scopes), calling `generateAuthorizationUrl()` SHALL produce a URL containing query parameters `response_type=code`, `client_id` matching the configured value, `redirect_uri` matching the configured value, all configured scopes in the `scope` parameter, a `state` parameter of at least 32 bytes of entropy, a `nonce` parameter of at least 32 bytes of entropy, `code_challenge_method=S256`, and a `code_challenge` parameter. + +**Validates: Requirements 2.2** + +### Property 6: PKCE code_verifier/code_challenge correctness + +*For any* call to `generateAuthorizationUrl()`, the stored `code_verifier` SHALL be between 43 and 128 characters (inclusive) per RFC 7636, and the `code_challenge` parameter in the URL SHALL equal `BASE64URL(SHA256(code_verifier))`. + +**Validates: Requirements 2.3, 9.3** + +### Property 7: State mismatch rejects callback + +*For any* callback request where the `state` query parameter does not exactly match the stored state value (including missing, empty, or expired state), the service SHALL reject the request with HTTP 400 and error code `INVALID_STATE` without contacting the token endpoint. + +**Validates: Requirements 3.2, 3.6, 9.1** + +### Property 8: ID token signature validation + +*For any* JWT signed with a key present in the JWKS key set, signature validation SHALL pass. *For any* JWT signed with a key NOT present in the JWKS key set, signature validation SHALL fail and the callback SHALL return HTTP 401 with error code `INVALID_ID_TOKEN`. + +**Validates: Requirements 3.3** + +### Property 9: Nonce mismatch rejects token + +*For any* ID token where the `nonce` claim does not match the stored nonce value, the service SHALL reject the token and return HTTP 401 with error code `INVALID_ID_TOKEN`. + +**Validates: Requirements 3.4, 9.2** + +### Property 10: Audience and issuer validation + +*For any* ID token where the `aud` claim does not match the configured `client_id` OR the `iss` claim does not match `https://login.microsoftonline.com/{tenant_id}/v2.0`, the service SHALL reject the token with error code `INVALID_ID_TOKEN`. + +**Validates: Requirements 3.5** + +### Property 11: State entries deleted after callback processing + +*For any* callback execution (whether successful or failed), the `oauth_state_store` entry matching the request's state parameter SHALL be deleted, ensuring it cannot be reused. + +**Validates: Requirements 3.10** + +### Property 12: New federated user provisioning invariant + +*For any* valid ID token claims (sub, email, preferred_username/derived username, given_name, family_name) where no federated identity exists with that sub: the service SHALL create a user with `is_active=1`, null `password_hash`, a federated_identities record with `provider='entra-id'` and `subject=sub`, and SHALL assign the default viewer role. + +**Validates: Requirements 4.1, 4.2, 4.5** + +### Property 13: Existing federated user profile immutability + +*For any* returning user (federated identity already linked), calling the provisioning flow with different claim values (name, email) SHALL NOT modify the existing user record's `first_name`, `last_name`, or `email` fields. + +**Validates: Requirements 4.3** + +### Property 14: Username derivation from invalid preferred_username + +*For any* `preferred_username` that does not match the pattern `^[a-zA-Z0-9_]{3,50}$`, the service SHALL derive the username from the email local-part by replacing all characters not in `[a-zA-Z0-9_]` with underscores and truncating to 50 characters. + +**Validates: Requirements 4.7** + +### Property 15: Group-to-role synchronization correctness + +*For any* group mapping configuration and any `groups` claim array (with UUIDs in any case), the user SHALL end up with exactly the Pabawi roles whose group IDs are present in both the mapping keys (case-insensitive comparison) and the groups claim, plus any roles that were not part of the mapping (manually assigned). Roles previously assigned by the mapping whose group IDs are no longer in the claim SHALL be revoked. + +**Validates: Requirements 5.1, 5.2, 5.3** + +### Property 16: Authorization code single-use and TTL + +*For any* successfully generated auth code, the code SHALL have `expires_at` ≤ 60 seconds from creation. After a successful exchange, any subsequent exchange attempt with the same code SHALL be rejected. After the code expires, exchange SHALL also be rejected. + +**Validates: Requirements 6.2, 6.3, 6.4** + +### Property 17: Providers endpoint always includes local authentication + +*For any* application configuration state (Entra ID enabled or disabled, any combination of integrations), the `GET /api/auth/providers` response SHALL always contain `{ "local": true }`. + +**Validates: Requirements 11.2** + +## Testing Strategy + +### Property-Based Testing + +Property-based tests will use **fast-check** (already a project dependency) with a minimum of 100 iterations per property. + +Properties particularly well-suited for PBT in this feature: +- **Config parsing properties (1–4)**: Generate random env var combinations +- **PKCE correctness (6)**: Verify math relationship across many generations +- **Token validation properties (7–10)**: Generate tokens with random claim permutations +- **Username derivation (14)**: Generate random strings, verify transformation rules +- **Group-to-role sync (15)**: Generate random mappings and group claims, verify set arithmetic +- **Auth code single-use (16)**: Generate codes and attempt double-exchange + +Each property test will be tagged: +```typescript +// Feature: azure-entra-id-auth, Property 6: PKCE code_verifier/code_challenge correctness +``` + +### Unit Tests (Example-Based) + +- Provider discovery endpoint (11.1–11.5) +- OAuth error parameter handling (3.9) +- Email-match account linking (4.4) +- Logout URL construction (8.2, 8.3) +- Frontend component rendering based on provider state (7.5, 7.6) +- Federation-only account local login rejection (7.4) + +### Integration Tests + +- Full OAuth flow with mocked Entra ID endpoints (token exchange, JWKS fetch) +- JWKS cache fallback on endpoint failure (9.8) +- Token exchange timeout behavior (3.1) +- Database failure during provisioning — atomicity (4.8) +- Audit logging verification (6.6) + +### Frontend Tests + +- Login page provider discovery and conditional rendering (10.1–10.7) +- Auth callback handler — code extraction and token exchange (10.5, 10.6) +- SSO logout redirect (8.4) + +### Test Organization + +``` +backend/test/ +├── unit/ +│ └── EntraIdService.test.ts # Unit tests for service logic +├── properties/ +│ └── EntraIdAuth.property.test.ts # Property-based tests (fast-check) +├── integration/ +│ └── EntraIdAuthFlow.test.ts # Full flow with mocked external endpoints +└── middleware/ + └── entraIdRoutes.test.ts # Route-level tests with supertest + +frontend/src/ +├── components/ +│ └── EntraIdLoginButton.test.ts # Component test +└── lib/ + └── entraIdAuth.svelte.test.ts # Callback handler test +``` diff --git a/.kiro/specs/azure-entra-id-auth/requirements.md b/.kiro/specs/azure-entra-id-auth/requirements.md new file mode 100644 index 00000000..02fe396e --- /dev/null +++ b/.kiro/specs/azure-entra-id-auth/requirements.md @@ -0,0 +1,173 @@ +# Requirements Document + +## Introduction + +Azure Entra ID (formerly Azure AD) authentication for Pabawi, providing SSO/OAuth 2.0 + OpenID Connect as an alternative authentication method alongside the existing local username/password flow. Users authenticate via their organization's Azure tenant, with automatic provisioning on first login and group-to-role mapping from Entra ID claims. + +## Glossary + +- **Entra_ID_Provider**: The Azure Entra ID OpenID Connect identity provider that issues ID tokens and access tokens after user authentication +- **Auth_Service**: The Pabawi backend AuthenticationService responsible for issuing and verifying Pabawi JWT tokens +- **RBAC_Service**: The Pabawi permission system comprising UserService, RoleService, PermissionService, and GroupService +- **Config_Service**: The Pabawi ConfigService that loads and validates environment-variable-based configuration via Zod +- **SSO_Session**: A Pabawi session established via Entra ID authentication, represented by Pabawi-issued JWT access and refresh tokens +- **ID_Token**: An OpenID Connect JWT issued by Entra ID containing user identity claims (sub, email, name, groups) +- **Authorization_Code**: A short-lived code returned by Entra ID after user consent, exchangeable for tokens at the token endpoint +- **Nonce**: A cryptographically random value bound to the authentication request and validated in the returned ID token to prevent replay attacks +- **PKCE**: Proof Key for Code Exchange — a code_verifier/code_challenge mechanism that protects the authorization code flow against interception +- **Federated_User**: A Pabawi user account linked to an Entra ID identity via the `sub` claim (subject identifier) +- **Group_Claim**: An Entra ID token claim containing the user's Azure group memberships (object IDs or names) + +## Requirements + +### Requirement 1: Entra ID Provider Configuration + +**User Story:** As an administrator, I want to configure Azure Entra ID as an authentication provider, so that organization users can sign in with their corporate credentials. + +#### Acceptance Criteria + +1. IF `ENTRA_ID_ENABLED` is not set or is set to any value other than `"true"`, THEN THE Config_Service SHALL skip Entra ID configuration parsing and not require any other `ENTRA_ID_*` variables +2. IF `ENTRA_ID_ENABLED` is set to `"true"`, THEN THE Config_Service SHALL require `ENTRA_ID_TENANT_ID`, `ENTRA_ID_CLIENT_ID`, `ENTRA_ID_CLIENT_SECRET`, and `ENTRA_ID_REDIRECT_URI` to be non-empty strings, and SHALL validate that `ENTRA_ID_REDIRECT_URI` is a valid URL +3. IF `ENTRA_ID_ENABLED` is `"true"` and any required variable is undefined or an empty string, THEN THE Config_Service SHALL throw a configuration validation error at startup that includes the names of all missing variables +4. THE Config_Service SHALL accept an optional `ENTRA_ID_SCOPES` variable containing a comma-separated list of scope strings, defaulting to `"openid,profile,email"`, and SHALL discard empty entries resulting from the split +5. THE Config_Service SHALL accept an optional `ENTRA_ID_GROUP_MAPPING` variable containing a JSON object whose keys are Entra ID group identifier strings and whose values are Pabawi role name strings +6. IF `ENTRA_ID_GROUP_MAPPING` is set and contains invalid JSON or does not parse to an object with string keys and string values, THEN THE Config_Service SHALL throw a configuration validation error at startup indicating the parsing failure + +### Requirement 2: OAuth 2.0 Authorization Code Flow Initiation + +**User Story:** As a user, I want to click a "Sign in with Microsoft" button and be redirected to my organization's Azure login page, so that I can authenticate using my corporate credentials. + +#### Acceptance Criteria + +1. WHEN a GET request is received at `/api/auth/entra-id/login`, THE Auth_Service SHALL respond with an HTTP 302 redirect to the Entra ID authorization endpoint (`https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize`) with a valid OpenID Connect authorization request +2. THE Auth_Service SHALL include `response_type=code`, the configured `client_id`, the configured `redirect_uri`, scopes including at minimum `openid profile email`, a cryptographically random `state` parameter (minimum 32 bytes of entropy), and a cryptographically random `nonce` parameter (minimum 32 bytes of entropy) in the authorization URL query parameters +3. THE Auth_Service SHALL use PKCE by generating a `code_verifier` of 43 to 128 characters per RFC 7636, computing a `code_challenge` using S256, and including `code_challenge` and `code_challenge_method=S256` in the authorization URL +4. THE Auth_Service SHALL store the `state`, `nonce`, and `code_verifier` values server-side associated with the user's session, with a maximum time-to-live of 10 minutes, for validation during the callback +5. IF `ENTRA_ID_ENABLED` is not `"true"`, THEN THE Auth_Service SHALL return HTTP 404 for the `/api/auth/entra-id/login` endpoint +6. IF the Entra ID integration is enabled but required configuration values (`ENTRA_ID_TENANT_ID`, `ENTRA_ID_CLIENT_ID`, or `ENTRA_ID_REDIRECT_URI`) are missing or empty at request time, THEN THE Auth_Service SHALL return an HTTP 500 response with an error message indicating a server configuration problem without exposing the specific missing values + +### Requirement 3: Authorization Code Callback and Token Exchange + +**User Story:** As a user returning from Azure login, I want Pabawi to securely exchange the authorization code for tokens, so that my identity is verified without exposing credentials. + +#### Acceptance Criteria + +1. WHEN a GET request is received at `/api/auth/entra-id/callback` with a non-empty `code` query parameter and a non-empty `state` query parameter, THE Auth_Service SHALL exchange the authorization code for tokens at the Entra ID token endpoint using the stored `code_verifier`, completing the exchange within 10 seconds or treating it as a failure +2. WHEN performing the authorization code exchange, THE Auth_Service SHALL validate that the `state` query parameter matches the value stored for the session prior to contacting the token endpoint +3. THE Auth_Service SHALL validate the returned ID_Token signature against the Entra ID JWKS (JSON Web Key Set) endpoint keys +4. THE Auth_Service SHALL validate that the `nonce` claim in the ID_Token matches the stored nonce value +5. THE Auth_Service SHALL validate the `aud` (audience) claim matches the configured `client_id` and the `iss` (issuer) claim matches the expected Entra ID issuer URL for the configured tenant +6. IF the `state` query parameter is missing, empty, or does not match the value stored for the session, THEN THE Auth_Service SHALL return HTTP 400 with error code `INVALID_STATE` +7. IF the authorization code exchange fails due to a non-2xx response from the token endpoint or a network timeout, THEN THE Auth_Service SHALL return HTTP 401 with error code `TOKEN_EXCHANGE_FAILED` +8. IF the ID_Token validation fails (signature, nonce, audience, or issuer), THEN THE Auth_Service SHALL return HTTP 401 with error code `INVALID_ID_TOKEN` +9. IF the callback request contains an `error` query parameter instead of a `code` parameter, THEN THE Auth_Service SHALL return HTTP 401 with error code `AUTH_PROVIDER_ERROR` and include the `error` and `error_description` values from the query string in the response body +10. WHEN the authorization code exchange and token validation complete (whether successfully or unsuccessfully), THE Auth_Service SHALL delete the stored `state`, `nonce`, and `code_verifier` values for the session so they cannot be reused + +### Requirement 4: User Provisioning on First SSO Login + +**User Story:** As a user signing in via Entra ID for the first time, I want Pabawi to automatically create my account from my Azure profile, so that I do not need a separate registration step. + +#### Acceptance Criteria + +1. WHEN the ID_Token is validated and no Federated_User exists with the matching `sub` claim, THE Auth_Service SHALL create a new user account using the `preferred_username`, `email`, `given_name`, and `family_name` claims from the ID_Token, storing an empty or null password hash to indicate the account is federation-only +2. THE Auth_Service SHALL store the Entra ID `sub` claim as the federated identity link on the new user record +3. WHEN the ID_Token is validated and a Federated_User already exists with the matching `sub` claim, THE Auth_Service SHALL use the existing user account for session creation without modifying the stored profile claims +4. WHEN a local user account exists with the same email as the Entra ID user but no federated link, THE Auth_Service SHALL link the Entra ID identity to the existing local account rather than creating a duplicate, preserving the existing password hash so that local login remains available +5. THE Auth_Service SHALL set newly provisioned Federated_User accounts as active by default and assign the same default role that locally created non-admin users receive +6. IF the `email` or `preferred_username` claim is missing from the ID_Token, THEN THE Auth_Service SHALL reject the authentication attempt and return an error response indicating which required claims are absent +7. IF the `preferred_username` claim does not conform to the username validation rules (3–50 characters, alphanumeric and underscores only), THEN THE Auth_Service SHALL derive the username from the local-part of the `email` claim, truncated to 50 characters, replacing disallowed characters with underscores +8. IF account provisioning fails after token validation (database write error or uniqueness constraint violation on the derived username), THEN THE Auth_Service SHALL reject the authentication attempt and return an error response indicating that account creation failed, without creating a partial user record + +### Requirement 5: Group-to-Role Mapping + +**User Story:** As an administrator, I want Entra ID group memberships to map to Pabawi roles, so that access control is managed centrally in Azure. + +#### Acceptance Criteria + +1. WHEN `ENTRA_ID_GROUP_MAPPING` is configured and the ID_Token contains a `groups` claim, THE RBAC_Service SHALL assign Pabawi roles to the user by matching each group object ID in the claim against the mapping keys and assigning the corresponding role values, and SHALL revoke any previously-mapped roles whose group object IDs are no longer present in the current `groups` claim +2. THE RBAC_Service SHALL match Entra ID group object IDs from the `groups` claim against keys in the `ENTRA_ID_GROUP_MAPPING` configuration using case-insensitive string comparison of UUID values +3. WHEN the user holds Pabawi roles that were assigned independently of the group mapping (manually or via other mechanisms), THE RBAC_Service SHALL preserve those roles unchanged during SSO login group synchronization +4. WHEN no `ENTRA_ID_GROUP_MAPPING` is configured, THE RBAC_Service SHALL not modify the user's existing Pabawi roles during SSO login +5. IF `ENTRA_ID_GROUP_MAPPING` references a Pabawi role name that does not exist in the roles table, THEN THE RBAC_Service SHALL log a warning indicating the unresolvable role name and skip that mapping entry without failing the login +6. IF `ENTRA_ID_GROUP_MAPPING` is configured but the ID_Token does not contain a `groups` claim, THEN THE RBAC_Service SHALL skip group-to-role synchronization and preserve the user's existing Pabawi roles unchanged +7. IF `ENTRA_ID_GROUP_MAPPING` contains invalid JSON that cannot be parsed, THEN THE RBAC_Service SHALL log an error at startup indicating the malformed configuration and disable group-to-role synchronization until the configuration is corrected + +### Requirement 6: Pabawi Session Issuance After SSO Authentication + +**User Story:** As a user who authenticated via Entra ID, I want to receive Pabawi JWT tokens, so that subsequent API requests are authorized without re-contacting Azure. + +#### Acceptance Criteria + +1. WHEN user provisioning or lookup completes after Entra ID authentication, THE Auth_Service SHALL issue a Pabawi JWT access token containing the user's id, username, and Pabawi roles, and a refresh token, using the same signing algorithm, issuer, audience, and expiry configuration as locally-authenticated tokens +2. WHEN issuing tokens for an SSO-authenticated user, THE Auth_Service SHALL generate a single-use authorization code with a maximum lifetime of 60 seconds, store it server-side mapped to the issued tokens, and redirect the user to the frontend application URL with the authorization code as a query parameter +3. WHEN the frontend exchanges the authorization code at the token endpoint, THE Auth_Service SHALL return the mapped access token and refresh token, then immediately invalidate the authorization code so it cannot be reused +4. IF the authorization code has expired or has already been exchanged, THEN THE Auth_Service SHALL reject the exchange request with an error response indicating the code is invalid and SHALL NOT issue tokens +5. WHEN issuing tokens after successful SSO login, THE Auth_Service SHALL update the user's `last_login_at` timestamp to the current UTC time +6. WHEN issuing tokens after successful SSO login, THE Auth_Service SHALL record the login via the AuditLoggingService with event type AUTH, action LOGIN_SUCCESS, and authentication method set to `entra-id` + +### Requirement 7: Coexistence with Local Authentication + +**User Story:** As an administrator, I want both local and SSO authentication to work simultaneously, so that users can choose their preferred login method. + +#### Acceptance Criteria + +1. WHILE `ENTRA_ID_ENABLED` is `"true"`, THE Auth_Service SHALL continue to accept local username/password authentication at `/api/auth/login` +2. THE Auth_Service SHALL verify JWT tokens issued via either local or Entra ID authentication using the same middleware and grant equivalent access to protected API endpoints for tokens carrying identical role and permission claims +3. WHEN a Federated_User has a password hash set, THE Auth_Service SHALL allow that user to authenticate via either local credentials or Entra ID +4. IF a Federated_User has no password hash set and attempts local login, THEN THE Auth_Service SHALL reject the request with HTTP 401 and an error message indicating the account requires SSO authentication +5. WHILE `ENTRA_ID_ENABLED` is `"true"`, THE frontend SHALL display both the "Sign in with Microsoft" button and the local login form on the login page +6. WHILE `ENTRA_ID_ENABLED` is `"false"`, THE frontend SHALL display only the local login form and SHALL NOT render the "Sign in with Microsoft" button + +### Requirement 8: Logout Flow + +**User Story:** As a user who authenticated via SSO, I want to log out completely, so that my session is terminated in both Pabawi and optionally in Azure. + +#### Acceptance Criteria + +1. WHEN an authenticated user calls the `POST /api/auth/logout` endpoint, THE Auth_Service SHALL revoke the access token presented in the Authorization header and any associated refresh token, and return an HTTP 200 response +2. IF the user's session was established via Entra ID authentication, THEN THE Auth_Service SHALL include an `entraIdLogoutUrl` field in the logout response body containing the Entra ID end-session endpoint URL with the `post_logout_redirect_uri` parameter set to the configured redirect destination and the `id_token_hint` parameter set to the user's stored ID token +3. IF the user's session was established via local authentication (not via Entra ID), THEN THE Auth_Service SHALL omit the `entraIdLogoutUrl` field from the logout response body +4. WHEN the frontend receives a logout response containing an `entraIdLogoutUrl` field, THE frontend SHALL redirect the user to that URL to complete single sign-out at Azure +5. THE Auth_Service SHALL accept an optional `ENTRA_ID_POST_LOGOUT_REDIRECT_URI` configuration variable for the post-logout redirect destination, defaulting to the value of the application's base URL (the `HOST` and `PORT` configuration) +6. IF the access token presented in the logout request is already revoked or invalid, THEN THE Auth_Service SHALL return an HTTP 401 response with error code `TOKEN_REVOKED` + +### Requirement 9: Security Controls + +**User Story:** As an administrator, I want the SSO integration to follow security best practices, so that the authentication flow is resistant to common attacks. + +#### Acceptance Criteria + +1. THE Auth_Service SHALL validate the `state` parameter on every callback request and reject with HTTP 400 if missing or mismatched +2. THE Auth_Service SHALL validate the `nonce` in every ID_Token and reject with HTTP 401 if it does not match the stored value +3. THE Auth_Service SHALL use PKCE (S256) on every authorization request to prevent authorization code interception +4. THE Auth_Service SHALL validate ID_Token signatures using keys fetched from the Entra ID JWKS endpoint and cache the JWKS keys with a configurable TTL (default 24 hours) +5. THE Auth_Service SHALL reject ID_Tokens where the `exp` claim indicates the token has expired, allowing a clock skew tolerance of no more than 5 minutes +6. THE Auth_Service SHALL store `state`, `nonce`, and `code_verifier` values with a maximum lifetime of 10 minutes, and SHALL reject callback requests arriving after expiry with HTTP 400 and error code `SESSION_EXPIRED` +7. THE Auth_Service SHALL never log or expose the `client_secret`, authorization codes, or Entra ID tokens in application logs +8. IF the JWKS endpoint is unreachable (connection timeout exceeding 5 seconds or non-2xx response), THEN THE Auth_Service SHALL use cached keys if available and log a warning, or return HTTP 503 with error code `JWKS_UNAVAILABLE` if no cached keys exist + +### Requirement 10: Frontend SSO Integration + +**User Story:** As a user, I want the login page to clearly present SSO as an option, so that I can authenticate with my corporate account. + +#### Acceptance Criteria + +1. WHEN the frontend loads the login page, THE frontend SHALL call `/api/auth/providers` to determine which authentication methods are available +2. IF the `/api/auth/providers` call fails or does not respond within 5 seconds, THEN THE frontend SHALL display only the local login form and show an error indication that SSO availability could not be determined +3. WHEN the providers response indicates Entra ID is enabled, THE frontend SHALL display a "Sign in with Microsoft" button using the Microsoft identity branding guidelines +4. WHEN the user clicks "Sign in with Microsoft", THE frontend SHALL redirect to `/api/auth/entra-id/login` +5. WHEN the frontend receives the redirect back from the SSO callback with an authorization code in the URL query parameter, THE frontend SHALL POST the code to `/api/auth/entra-id/token` and upon receiving a successful response, store the returned access token, refresh token, and user object in auth state and navigate to the authenticated landing page +6. IF the token exchange request to `/api/auth/entra-id/token` returns a non-success response, THEN THE frontend SHALL display an error message indicating authentication failed, retain the login page, and not store any tokens +7. WHEN the providers response does not indicate Entra ID is enabled, THE frontend SHALL display only the local login form without SSO options + +### Requirement 11: Authentication Provider Discovery + +**User Story:** As a frontend application, I want to discover available authentication methods, so that I can render the appropriate login options. + +#### Acceptance Criteria + +1. WHEN a GET request is received at `/api/auth/providers`, THE Auth_Service SHALL return a 200 response with a JSON object listing available authentication methods +2. THE Auth_Service SHALL include `{ "local": true }` in the providers response at all times +3. IF `ENTRA_ID_ENABLED` is set to `"true"`, THEN THE Auth_Service SHALL include `{ "entraId": { "enabled": true, "name": "Microsoft Entra ID" } }` in the providers response +4. IF `ENTRA_ID_ENABLED` is not set to `"true"`, THEN THE Auth_Service SHALL omit the `entraId` key from the providers response +5. THE `/api/auth/providers` endpoint SHALL be accessible without authentication diff --git a/.kiro/specs/azure-entra-id-auth/tasks.md b/.kiro/specs/azure-entra-id-auth/tasks.md new file mode 100644 index 00000000..d031cc75 --- /dev/null +++ b/.kiro/specs/azure-entra-id-auth/tasks.md @@ -0,0 +1,243 @@ +# Implementation Plan: Azure Entra ID Authentication + +## Overview + +Implements Azure Entra ID (OpenID Connect) as a federated authentication provider using the OAuth 2.0 Authorization Code Flow with PKCE. The implementation adds a new `EntraIdService`, database migration, Express routes, and frontend SSO components while maintaining full backward compatibility with local authentication. + +## Tasks + +- [x] 1. Database migration and configuration schema + - [x] 1.1 Create database migration `016_entra_id_auth.sql` + - Create `federated_identities` table with columns: id, user_id, provider, subject, issuer, email, id_token, created_at, updated_at + - Create `oauth_state_store` table with columns: state, nonce, code_verifier, created_at, expires_at + - Create `oauth_auth_codes` table with columns: code, access_token, refresh_token, user_id, id_token, auth_method, created_at, expires_at, exchanged + - Add indexes: idx_federated_identities_user, idx_federated_identities_lookup, idx_oauth_state_expires, idx_oauth_auth_codes_expires + - Add FOREIGN KEY on federated_identities.user_id → users(id) ON DELETE CASCADE + - Add UNIQUE constraint on (provider, subject) in federated_identities + - _Requirements: 4.1, 4.2, 6.2, 9.6_ + + - [x] 1.2 Add `EntraIdConfigSchema` to `backend/src/config/schema.ts` + - Define Zod schema with: enabled (boolean, default false), tenantId (string min 1), clientId (string min 1), clientSecret (string min 1), redirectUri (string url), scopes (array of strings, default ["openid","profile","email"]), groupMapping (record string→string, nullable, default null), postLogoutRedirectUri (string url, optional), jwksCacheTtlMs (number int positive, default 86400000) + - Export `EntraIdConfigSchema` and inferred `EntraIdConfig` type + - Add `entraId` optional field to `AppConfigSchema` + - _Requirements: 1.1, 1.2, 1.4, 1.5, 1.6_ + + - [x] 1.3 Add Entra ID configuration parsing to `ConfigService.ts` + - Add `parseEntraIdConfig()` private method following existing integration parsing pattern + - Parse `ENTRA_ID_ENABLED`, `ENTRA_ID_TENANT_ID`, `ENTRA_ID_CLIENT_ID`, `ENTRA_ID_CLIENT_SECRET`, `ENTRA_ID_REDIRECT_URI` + - Parse optional `ENTRA_ID_SCOPES` (comma-separated, discard empty entries, default to openid,profile,email) + - Parse optional `ENTRA_ID_GROUP_MAPPING` (JSON Record, throw on invalid JSON) + - Parse optional `ENTRA_ID_POST_LOGOUT_REDIRECT_URI`, `ENTRA_ID_JWKS_CACHE_TTL_MS` + - Skip all parsing when `ENTRA_ID_ENABLED !== "true"`; throw with all missing variable names when enabled but required vars absent + - Add `getEntraIdConfig()` public accessor method + - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6_ + + - [x] 1.4 Write property tests for configuration parsing (Properties 1–4) + - **Property 1: Non-"true" ENTRA_ID_ENABLED skips config validation** + - **Property 2: Missing required variables produce comprehensive error** + - **Property 3: Scope parsing discards empty entries** + - **Property 4: Group mapping JSON round-trip** + - **Validates: Requirements 1.1, 1.2, 1.3, 1.4, 1.5, 1.6** + +- [x] 2. Checkpoint - Ensure all tests pass + - Ensure all tests pass, ask the user if questions arise. + +- [x] 3. Core EntraIdService implementation + - [x] 3.1 Create `backend/src/services/EntraIdService.ts` — authorization URL generation + - Implement class with constructor accepting DatabaseAdapter, EntraIdConfig, AuthenticationService, UserService, RoleService, AuditLoggingService, LoggerService + - Implement `generateAuthorizationUrl()`: generate state (32 bytes crypto random), nonce (32 bytes), code_verifier (43–128 chars per RFC 7636), compute code_challenge via SHA256+BASE64URL, store state/nonce/code_verifier in `oauth_state_store` with 10-minute TTL, return authorization URL with all required query parameters + - Implement `cleanupExpiredState()`: delete expired entries from oauth_state_store + - Implement `getProviderInfo()`: return `{ enabled: true, name: "Microsoft Entra ID" }` + - _Requirements: 2.1, 2.2, 2.3, 2.4, 9.3, 9.6_ + + - [x] 3.2 Write property tests for authorization URL and PKCE (Properties 5–6) + - **Property 5: Authorization URL contains all required parameters** + - **Property 6: PKCE code_verifier/code_challenge correctness** + - **Validates: Requirements 2.2, 2.3, 9.3** + + - [x] 3.3 Implement `handleCallback()` in EntraIdService + - Validate state parameter against stored entry (reject if missing/expired with INVALID_STATE) + - Delete state entry immediately (one-time use, even on failure) + - Exchange authorization code at `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token` with code_verifier, client_id, client_secret, redirect_uri (10s timeout) + - Fetch JWKS keys from `https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys` (cache with configurable TTL, fallback to cache on failure) + - Validate ID token: verify RS256 signature against JWKS keys, validate nonce, aud (=client_id), iss (=`https://login.microsoftonline.com/{tenant}/v2.0`), exp (5min skew max) + - On validation failure, return typed errors (INVALID_STATE, TOKEN_EXCHANGE_FAILED, INVALID_ID_TOKEN, AUTH_PROVIDER_ERROR, MISSING_CLAIMS) + - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10, 9.1, 9.2, 9.4, 9.5, 9.7, 9.8_ + + - [x] 3.4 Write property tests for callback validation (Properties 7–11) + - **Property 7: State mismatch rejects callback** + - **Property 8: ID token signature validation** + - **Property 9: Nonce mismatch rejects token** + - **Property 10: Audience and issuer validation** + - **Property 11: State entries deleted after callback processing** + - **Validates: Requirements 3.2, 3.3, 3.4, 3.5, 3.6, 3.10, 9.1, 9.2** + +- [x] 4. Checkpoint - Ensure all tests pass + - Ensure all tests pass, ask the user if questions arise. + +- [x] 5. User provisioning and group-to-role synchronization + - [x] 5.1 Add `createFederatedUser()` and `linkFederatedIdentity()` to `UserService.ts` + - `createFederatedUser(claims)`: create user with null password_hash, is_active=1, derive username from preferred_username or email local-part (replace non-[a-zA-Z0-9_] with underscores, truncate to 50 chars), assign default viewer role, create federated_identities record with provider='entra-id' and subject=sub + - `linkFederatedIdentity(userId, provider, subject, issuer, email)`: insert into federated_identities linking existing user to Entra ID identity + - `findByFederatedIdentity(provider, subject)`: lookup user by federated identity + - `findByEmail(email)`: public wrapper around existing private getUserByEmail + - Handle uniqueness constraint violations on derived username with retry/error + - _Requirements: 4.1, 4.2, 4.4, 4.5, 4.7, 4.8_ + + - [x] 5.2 Implement user provisioning logic in EntraIdService + - After ID token validation, look up federated_identities by (provider='entra-id', subject=sub) + - If found: use existing user, do NOT update profile claims (immutability) + - If not found: check users by email; if email match exists, link federated identity to existing account (preserve password_hash) + - If no match: create new federated user via UserService.createFederatedUser() + - Reject if email or preferred_username claims missing (MISSING_CLAIMS error) + - Validate username derivation when preferred_username doesn't match ^[a-zA-Z0-9_]{3,50}$ + - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7, 4.8_ + + - [x] 5.3 Write property tests for user provisioning (Properties 12–14) + - **Property 12: New federated user provisioning invariant** + - **Property 13: Existing federated user profile immutability** + - **Property 14: Username derivation from invalid preferred_username** + - **Validates: Requirements 4.1, 4.2, 4.3, 4.5, 4.7** + + - [x] 5.4 Implement group-to-role synchronization in EntraIdService + - If groupMapping is configured and groups claim is present: match group object IDs case-insensitively against mapping keys + - Assign corresponding Pabawi roles for matched groups + - Revoke previously-mapped roles whose group IDs are no longer in the claim + - Preserve roles assigned independently of the mapping (manually assigned) + - If mapping references non-existent Pabawi role: log warning, skip entry + - If no groups claim present or no mapping configured: skip sync entirely, preserve existing roles + - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6_ + + - [x] 5.5 Write property test for group-to-role synchronization (Property 15) + - **Property 15: Group-to-role synchronization correctness** + - **Validates: Requirements 5.1, 5.2, 5.3** + +- [x] 6. Checkpoint - Ensure all tests pass + - Ensure all tests pass, ask the user if questions arise. + +- [x] 7. Session issuance and routes + - [x] 7.1 Implement `exchangeAuthCode()` and session issuance in EntraIdService + - After user provisioning: generate Pabawi JWT access + refresh tokens via AuthenticationService + - Generate single-use authorization code (crypto random, 60s TTL), store in oauth_auth_codes mapped to tokens + userId + id_token + - `exchangeAuthCode(code)`: lookup code, verify not expired and not already exchanged, mark as exchanged, return tokens + user DTO + - Reject expired/exchanged codes with INVALID_AUTH_CODE error + - Update user's last_login_at timestamp + - Record audit log via AuditLoggingService (AUTH, LOGIN_SUCCESS, method=entra-id) + - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.6_ + + - [x] 7.2 Write property test for authorization code single-use and TTL (Property 16) + - **Property 16: Authorization code single-use and TTL** + - **Validates: Requirements 6.2, 6.3, 6.4** + + - [x] 7.3 Create `backend/src/routes/entraIdAuth.ts` route factory + - Export `createEntraIdAuthRouter(databaseService, container)` following existing pattern + - `GET /api/auth/entra-id/login`: call EntraIdService.generateAuthorizationUrl(), respond with 302 redirect + - `GET /api/auth/entra-id/callback`: handle OAuth callback — validate state, exchange code, provision user, issue tokens, redirect to frontend with auth code + - `POST /api/auth/entra-id/token`: exchange single-use auth code for Pabawi JWT pair (returns { token, refreshToken, user }) + - Return 404 for all endpoints when Entra ID is not enabled + - Return 500 with SERVER_CONFIGURATION_ERROR if config values missing at request time + - Handle error parameter from Entra ID (AUTH_PROVIDER_ERROR) + - _Requirements: 2.1, 2.5, 2.6, 3.1, 3.6, 3.7, 3.8, 3.9, 6.2, 6.3, 6.4_ + + - [x] 7.4 Add `/api/auth/providers` endpoint and modify logout in `auth.ts` + - Add `GET /api/auth/providers` endpoint (no auth required): return `{ local: true }` always, add `{ entraId: { enabled: true, name: "Microsoft Entra ID" } }` when enabled + - Modify `POST /api/auth/logout`: after token revocation, check if user session was established via Entra ID (lookup federated_identities + stored id_token), include `entraIdLogoutUrl` in response when applicable + - Implement `buildLogoutUrl(idToken)` in EntraIdService: construct Entra ID end-session URL with post_logout_redirect_uri and id_token_hint + - _Requirements: 7.4, 8.1, 8.2, 8.3, 8.5, 8.6, 11.1, 11.2, 11.3, 11.4, 11.5_ + + - [x] 7.5 Write property test for providers endpoint (Property 17) + - **Property 17: Providers endpoint always includes local authentication** + - **Validates: Requirements 11.2** + +- [x] 8. Checkpoint - Ensure all tests pass + - Ensure all tests pass, ask the user if questions arise. + +- [x] 9. DI container registration and server wiring + - [x] 9.1 Register EntraIdService in `DIContainer.ts` and wire in `server.ts` + - Add `entraId` as optional key in `ServiceRegistry` interface + - In server.ts: conditionally instantiate EntraIdService when Entra ID config is enabled + - Mount entraIdAuth router at `/api/auth/entra-id` (conditional on config) + - Ensure EntraIdService receives all required dependencies: DatabaseAdapter, EntraIdConfig, AuthenticationService, UserService, RoleService, AuditLoggingService, LoggerService + - Set up periodic cleanup of expired state entries (e.g., every 5 minutes) + - _Requirements: 2.5, 7.1, 7.2_ + + - [x] 9.2 Write integration tests for the full OAuth flow + - Test full authorization URL generation → callback → token exchange flow with mocked Entra ID endpoints + - Test JWKS cache fallback on endpoint failure + - Test token exchange timeout behavior (>10s) + - Test database failure during provisioning (atomicity) + - Test audit logging verification + - Test federation-only account local login rejection (HTTP 401) + - Test coexistence: local auth continues working when Entra ID enabled + - _Requirements: 2.1, 3.1, 7.1, 7.2, 7.3, 7.4, 9.4, 9.8_ + +- [x] 10. Frontend SSO integration + - [x] 10.1 Create `frontend/src/lib/entraIdAuth.svelte.ts` + - Reactive state for provider availability (call `/api/auth/providers` on init) + - Handle provider discovery failure (5s timeout → show only local login) + - Expose `isEntraIdEnabled` derived state and `entraIdProviderName` state + - Implement callback handler: extract `code` from URL query parameter, POST to `/api/auth/entra-id/token`, store tokens in auth state, navigate to landing page + - Handle token exchange errors: display error message, retain login page + - _Requirements: 10.1, 10.2, 10.5, 10.6, 10.7_ + + - [x] 10.2 Create `frontend/src/components/EntraIdLoginButton.svelte` + - Microsoft-branded "Sign in with Microsoft" button following Microsoft identity branding guidelines + - On click: redirect to `/api/auth/entra-id/login` + - Accessible: proper button semantics, ARIA label, keyboard interaction + - _Requirements: 10.3, 10.4_ + + - [x] 10.3 Modify `frontend/src/pages/Login.svelte` for SSO support + - Import and use entraIdAuth state module + - Conditionally render EntraIdLoginButton when `isEntraIdEnabled` is true + - Show only local login form when Entra ID is not enabled + - Show error indication when provider discovery fails + - Handle callback redirect: detect `?code=` in URL, trigger token exchange flow + - Implement SSO logout redirect when logout response contains `entraIdLogoutUrl` + - _Requirements: 7.5, 7.6, 8.4, 10.1, 10.2, 10.3, 10.5, 10.6, 10.7_ + + - [x] 10.4 Write frontend tests + - Test EntraIdLoginButton renders correctly with Microsoft branding + - Test Login.svelte conditionally renders SSO button based on provider state + - Test callback handler extracts code and exchanges for tokens + - Test error state when provider discovery or token exchange fails + - Test SSO logout redirect behavior + - _Requirements: 7.5, 7.6, 10.1, 10.2, 10.3, 10.5, 10.6_ + +- [x] 11. Final checkpoint - Ensure all tests pass + - Ensure all tests pass, ask the user if questions arise. + +## Notes + +- Tasks marked with `*` are optional and can be skipped for faster MVP +- Each task references specific requirements for traceability +- Checkpoints ensure incremental validation +- Property tests validate the 17 correctness properties from the design document using fast-check +- Unit tests validate specific examples and edge cases +- The project uses TypeScript strict mode; all code must pass `tsc --noEmit`, ESLint, and vitest +- Database columns use `snake_case` with `AS "camelCase"` aliases in SELECT queries (per database conventions) +- Phased execution: each task group touches ≤5 files to comply with workspace steering rules +- Never log client_secret, authorization codes, or tokens (security requirement 9.7) + +## Task Dependency Graph + +```json +{ + "waves": [ + { "id": 0, "tasks": ["1.1", "1.2"] }, + { "id": 1, "tasks": ["1.3", "1.4"] }, + { "id": 2, "tasks": ["3.1"] }, + { "id": 3, "tasks": ["3.2", "3.3"] }, + { "id": 4, "tasks": ["3.4", "5.1"] }, + { "id": 5, "tasks": ["5.2", "5.4"] }, + { "id": 6, "tasks": ["5.3", "5.5"] }, + { "id": 7, "tasks": ["7.1"] }, + { "id": 8, "tasks": ["7.2", "7.3"] }, + { "id": 9, "tasks": ["7.4", "7.5"] }, + { "id": 10, "tasks": ["9.1"] }, + { "id": 11, "tasks": ["9.2", "10.1"] }, + { "id": 12, "tasks": ["10.2"] }, + { "id": 13, "tasks": ["10.3"] }, + { "id": 14, "tasks": ["10.4"] } + ] +} +``` diff --git a/AGENTS.md b/AGENTS.md index e957d81c..87ecc53a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -95,9 +95,9 @@ The frontend uses **Svelte 5 runes** throughout (`$state()`, `$effect()`, `$deri ### Configuration -All configuration is via `backend/.env`. Run `scripts/setup.sh` for interactive setup. Key variable groups: `PORT/HOST/LOG_LEVEL`, `JWT_SECRET` (required), `PABAWI_LIFECYCLE_TOKEN` (optional), `BOLT_*`, `PUPPETDB_*`, `PUPPETSERVER_*`, `HIERA_*`, `ANSIBLE_*`, `SSH_*`, `AWS_*`, `AZURE_*`, `PROXMOX_*`, `COMMAND_WHITELIST*`, `CACHE_*`, `CONCURRENT_EXECUTION_LIMIT`, `MCP_ENABLED`. +All configuration is via `backend/.env`. Run `scripts/setup.sh` for interactive setup. Key variable groups: `PORT/HOST/LOG_LEVEL`, `JWT_SECRET` (required), `PABAWI_LIFECYCLE_TOKEN` (optional), `ENTRA_ID_*` (SSO), `BOLT_*`, `PUPPETDB_*`, `PUPPETSERVER_*`, `HIERA_*`, `ANSIBLE_*`, `SSH_*`, `AWS_*`, `AZURE_*`, `PROXMOX_*`, `COMMAND_WHITELIST*`, `CACHE_*`, `CONCURRENT_EXECUTION_LIMIT`, `MCP_ENABLED`. -See `docs/configuration.md` for the full reference. Other useful docs: `docs/mcp.md` (MCP setup and tools), `docs/permissions-rbac.md` (RBAC model), `docs/architecture.md` (system overview), `docs/api.md` (REST API reference), `docs/integrations/` (per-integration guides). +See `docs/configuration.md` for the full reference. Other useful docs: `docs/mcp.md` (MCP setup and tools), `docs/permissions-rbac.md` (RBAC model), `docs/architecture.md` (system overview), `docs/api.md` (REST API reference), `docs/integrations/` (per-integration guides), `docs/integrations/entra-id.md` (Azure Entra ID SSO setup). ### Testing conventions diff --git a/backend/.env.example b/backend/.env.example index 4774720e..b7e057b9 100644 --- a/backend/.env.example +++ b/backend/.env.example @@ -180,6 +180,40 @@ PROXMOX_SSL_REJECT_UNAUTHORIZED=true # PROXMOX_TIMEOUT=30000 # PROXMOX_PRIORITY=7 +# ----------------------------------------------------------------------------- +# Azure Entra ID SSO (optional) +# ----------------------------------------------------------------------------- +ENTRA_ID_ENABLED=false +# ENTRA_ID_TENANT_ID=12345678-abcd-efgh-ijkl-123456789012 +# ENTRA_ID_CLIENT_ID=abcdef01-2345-6789-abcd-ef0123456789 +# ENTRA_ID_CLIENT_SECRET= # pragma: allowlist secret +# ENTRA_ID_REDIRECT_URI=https://pabawi.example.com/api/auth/entra-id/callback +# Scopes (comma-separated, default: openid,profile,email) +# ENTRA_ID_SCOPES=openid,profile,email +# Group-to-role mapping (JSON object: {"azure-group-id": "pabawi-role-name"}) +# ENTRA_ID_GROUP_MAPPING={"e5f3a1b2-...":"administrator","c7d8e9f0-...":"operator"} +# Post-logout redirect URI (defaults to app base URL) +# ENTRA_ID_POST_LOGOUT_REDIRECT_URI=https://pabawi.example.com +# JWKS cache TTL in ms (default: 86400000 = 24 hours) +# ENTRA_ID_JWKS_CACHE_TTL_MS=86400000 + +# ----------------------------------------------------------------------------- +# Azure Entra ID SSO (optional) +# ----------------------------------------------------------------------------- +ENTRA_ID_ENABLED=false +# ENTRA_ID_TENANT_ID=12345678-abcd-efgh-ijkl-123456789012 +# ENTRA_ID_CLIENT_ID=abcdef01-2345-6789-abcd-ef0123456789 +# ENTRA_ID_CLIENT_SECRET= # pragma: allowlist secret +# ENTRA_ID_REDIRECT_URI=https://pabawi.example.com/api/auth/entra-id/callback +# Scopes (comma-separated, default: openid,profile,email) +# ENTRA_ID_SCOPES=openid,profile,email +# Group-to-role mapping (JSON object: {"azure-group-id": "pabawi-role-name"}) +# ENTRA_ID_GROUP_MAPPING={"e5f3a1b2-...":"administrator","c7d8e9f0-...":"operator"} +# Post-logout redirect URI (defaults to app base URL) +# ENTRA_ID_POST_LOGOUT_REDIRECT_URI=https://pabawi.example.com +# JWKS cache TTL in ms (default: 86400000 = 24 hours) +# ENTRA_ID_JWKS_CACHE_TTL_MS=86400000 + # ----------------------------------------------------------------------------- # AWS integration (optional) # ----------------------------------------------------------------------------- diff --git a/backend/src/config/ConfigService.ts b/backend/src/config/ConfigService.ts index f5f51bb3..a75937c2 100644 --- a/backend/src/config/ConfigService.ts +++ b/backend/src/config/ConfigService.ts @@ -2,6 +2,7 @@ import { config as loadDotenv } from "dotenv"; import { AppConfigSchema, type AppConfig, + type EntraIdConfig, type WhitelistConfig, } from "./schema"; import { z } from "zod"; @@ -13,6 +14,7 @@ import { parseJson } from "../utils/json"; */ export class ConfigService { private config: AppConfig; + private entraIdConfig: EntraIdConfig | null = null; constructor() { // Load .env file only if not in test environment @@ -610,6 +612,101 @@ export class ConfigService { return integrations; } + /** + * Parse Entra ID (Azure AD) authentication configuration from environment variables. + * Skips all parsing when ENTRA_ID_ENABLED is not "true". + * Throws with all missing variable names when enabled but required vars are absent. + */ + private parseEntraIdConfig(): EntraIdConfig | null { + if (process.env.ENTRA_ID_ENABLED !== "true") { + return null; + } + + // Collect all missing required variables + const missing: string[] = []; + const tenantId = process.env.ENTRA_ID_TENANT_ID; + const clientId = process.env.ENTRA_ID_CLIENT_ID; + const clientSecret = process.env.ENTRA_ID_CLIENT_SECRET; // pragma: allowlist secret + const redirectUri = process.env.ENTRA_ID_REDIRECT_URI; + + if (!tenantId) missing.push("ENTRA_ID_TENANT_ID"); + if (!clientId) missing.push("ENTRA_ID_CLIENT_ID"); + if (!clientSecret) missing.push("ENTRA_ID_CLIENT_SECRET"); // pragma: allowlist secret + if (!redirectUri) missing.push("ENTRA_ID_REDIRECT_URI"); + + if (missing.length > 0) { + throw new Error( + `Entra ID authentication is enabled but required configuration variables are missing: ${missing.join(", ")}`, + ); + } + + // After the guard above, these are guaranteed non-empty strings. + // Narrow explicitly so TypeScript tracks the guarantee without assertions. + if (!tenantId || !clientId || !clientSecret || !redirectUri) { + // Unreachable — the missing[] guard above already throws. + throw new Error("Unreachable: required Entra ID variables validated"); + } + + // Parse optional scopes (comma-separated, discard empty entries) + const scopesRaw = process.env.ENTRA_ID_SCOPES; + const scopes = scopesRaw + ? scopesRaw.split(",").map((s) => s.trim()).filter(Boolean) + : ["openid", "profile", "email"]; + + // Parse optional group mapping (JSON Record) + let groupMapping: Record | null = null; + const groupMappingRaw = process.env.ENTRA_ID_GROUP_MAPPING; + if (groupMappingRaw) { + try { + const parsed = parseJson(groupMappingRaw); + if ( + typeof parsed !== "object" || + parsed === null || + Array.isArray(parsed) + ) { + throw new Error("must be a JSON object"); + } + // Validate all keys and values are strings + for (const [key, value] of Object.entries(parsed as Record)) { + if (typeof key !== "string" || typeof value !== "string") { + throw new Error("all keys and values must be strings"); + } + } + groupMapping = parsed as Record; + } catch (error) { + throw new Error( + `ENTRA_ID_GROUP_MAPPING contains invalid JSON: ${error instanceof Error ? error.message : "parse error"}`, + ); + } + } + + // Parse optional post-logout redirect URI + const postLogoutRedirectUri = + process.env.ENTRA_ID_POST_LOGOUT_REDIRECT_URI ?? undefined; + + // Parse optional JWKS cache TTL + const jwksCacheTtlMs = process.env.ENTRA_ID_JWKS_CACHE_TTL_MS + ? parseInt(process.env.ENTRA_ID_JWKS_CACHE_TTL_MS, 10) + : undefined; + + // At this point tenantId, clientId, clientSecret, redirectUri are guaranteed non-empty + // (we threw above if any were falsy) + const config: EntraIdConfig = { + enabled: true, + tenantId, + clientId, + clientSecret, // pragma: allowlist secret + redirectUri, + scopes, + groupMapping, + postLogoutRedirectUri, + jwksCacheTtlMs: jwksCacheTtlMs ?? 86400000, + }; + + this.entraIdConfig = config; + return config; + } + /** * Load configuration from environment variables with validation */ @@ -728,6 +825,7 @@ export class ConfigService { ui, mcpEnabled: process.env.MCP_ENABLED === "true", mcpAuthToken: process.env.MCP_AUTH_TOKEN ?? undefined, + entraId: this.parseEntraIdConfig() ?? undefined, }; // Validate with Zod schema @@ -981,4 +1079,12 @@ export class ConfigService { } return null; } + + /** + * Get Entra ID authentication configuration if enabled. + * Returns null when ENTRA_ID_ENABLED is not "true". + */ + public getEntraIdConfig(): EntraIdConfig | null { + return this.entraIdConfig; + } } diff --git a/backend/src/config/schema.ts b/backend/src/config/schema.ts index 0a34e0c6..f253508c 100644 --- a/backend/src/config/schema.ts +++ b/backend/src/config/schema.ts @@ -376,6 +376,23 @@ export const CheckmkConfigSchema = z.object({ export type CheckmkConfig = z.infer; +/** + * Azure Entra ID (OpenID Connect) authentication provider configuration schema + */ +export const EntraIdConfigSchema = z.object({ + enabled: z.boolean().default(false), + tenantId: z.string().min(1), + clientId: z.string().min(1), + clientSecret: z.string().min(1), + redirectUri: z.string().url(), + scopes: z.array(z.string()).default(["openid", "profile", "email"]), + groupMapping: z.record(z.string(), z.string()).nullable().default(null), + postLogoutRedirectUri: z.string().url().optional(), + jwksCacheTtlMs: z.number().int().positive().default(86400000), // 24 hours +}); + +export type EntraIdConfig = z.infer; + /** * Integrations configuration schema */ @@ -434,6 +451,7 @@ export const AppConfigSchema = z.object({ ui: UIConfigSchema.default({ showHomePageRunChart: true }), mcpEnabled: z.boolean().default(false), mcpAuthToken: z.string().optional(), + entraId: EntraIdConfigSchema.optional(), }); export type AppConfig = z.infer; diff --git a/backend/src/container/DIContainer.ts b/backend/src/container/DIContainer.ts index 6f02db04..1e312998 100644 --- a/backend/src/container/DIContainer.ts +++ b/backend/src/container/DIContainer.ts @@ -1,11 +1,13 @@ import { LoggerService } from "../services/LoggerService"; import { ExpertModeService } from "../services/ExpertModeService"; import { ConfigService } from "../config/ConfigService"; +import type { EntraIdService } from "../services/EntraIdService"; export interface ServiceRegistry { logger: LoggerService; expertMode: ExpertModeService; config: ConfigService; + entraId?: EntraIdService; } export class DIContainer { diff --git a/backend/src/database/migrations/016_entra_id_auth.sql b/backend/src/database/migrations/016_entra_id_auth.sql new file mode 100644 index 00000000..fb642147 --- /dev/null +++ b/backend/src/database/migrations/016_entra_id_auth.sql @@ -0,0 +1,48 @@ +-- Migration 016: Entra ID federated authentication support +-- Adds tables for federated identity linking, OAuth state management, +-- and single-use authorization codes for the frontend token exchange flow. +-- Requirements: 4.1, 4.2, 6.2, 9.6 + +-- Federated identity links: maps external IdP subjects to Pabawi users +CREATE TABLE IF NOT EXISTS federated_identities ( + id TEXT PRIMARY KEY, + user_id TEXT NOT NULL, + provider TEXT NOT NULL, -- 'entra-id' + subject TEXT NOT NULL, -- Entra ID 'sub' claim (unique per tenant+user) + issuer TEXT NOT NULL, -- Token issuer URL + email TEXT, -- Email from IdP (informational, not authoritative) + id_token TEXT, -- Last ID token (for logout id_token_hint) + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL, + FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE, + UNIQUE(provider, subject) +); + +CREATE INDEX IF NOT EXISTS idx_federated_identities_user ON federated_identities(user_id); +CREATE INDEX IF NOT EXISTS idx_federated_identities_lookup ON federated_identities(provider, subject); + +-- OAuth state store: PKCE + state + nonce for in-flight authorization requests +CREATE TABLE IF NOT EXISTS oauth_state_store ( + state TEXT PRIMARY KEY, + nonce TEXT NOT NULL, + code_verifier TEXT NOT NULL, + created_at TEXT NOT NULL, + expires_at TEXT NOT NULL +); + +CREATE INDEX IF NOT EXISTS idx_oauth_state_expires ON oauth_state_store(expires_at); + +-- Single-use authorization codes for frontend token delivery +CREATE TABLE IF NOT EXISTS oauth_auth_codes ( + code TEXT PRIMARY KEY, + access_token TEXT NOT NULL, + refresh_token TEXT NOT NULL, + user_id TEXT NOT NULL, + id_token TEXT, + auth_method TEXT NOT NULL DEFAULT 'entra-id', + created_at TEXT NOT NULL, + expires_at TEXT NOT NULL, + exchanged INTEGER NOT NULL DEFAULT 0 +); + +CREATE INDEX IF NOT EXISTS idx_oauth_auth_codes_expires ON oauth_auth_codes(expires_at); diff --git a/backend/src/database/migrations/017_nullable_password_hash.sql b/backend/src/database/migrations/017_nullable_password_hash.sql new file mode 100644 index 00000000..7839302f --- /dev/null +++ b/backend/src/database/migrations/017_nullable_password_hash.sql @@ -0,0 +1,39 @@ +-- Migration 017: Make password_hash nullable for federated (SSO) users +-- +-- Federated users authenticated via Entra ID (or other OIDC providers) +-- have no local password. The design stores NULL in password_hash for +-- these accounts. SQLite does not support ALTER COLUMN, so we recreate +-- the users table with password_hash TEXT (nullable). + +-- Step 1: Create new table without NOT NULL on password_hash +CREATE TABLE users_new ( + id TEXT PRIMARY KEY, + username TEXT NOT NULL UNIQUE, + email TEXT NOT NULL UNIQUE, + password_hash TEXT, -- NULL for federation-only accounts + first_name TEXT NOT NULL, + last_name TEXT NOT NULL, + is_active INTEGER NOT NULL DEFAULT 1, + is_admin INTEGER NOT NULL DEFAULT 0, + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL, + last_login_at TEXT +); + +-- Step 2: Copy all existing data +INSERT INTO users_new (id, username, email, password_hash, first_name, last_name, is_active, is_admin, created_at, updated_at, last_login_at) +SELECT id, username, email, password_hash, first_name, last_name, is_active, is_admin, created_at, updated_at, last_login_at +FROM users; + +-- Step 3: Drop old table +DROP TABLE users; + +-- Step 4: Rename new table +ALTER TABLE users_new RENAME TO users; + +-- Step 5: Recreate indexes (username and email have UNIQUE in the CREATE TABLE) +-- The federated_identities FK ON DELETE CASCADE still references users(id) +-- which is the same PRIMARY KEY. +CREATE INDEX IF NOT EXISTS idx_users_username ON users(username); +CREATE INDEX IF NOT EXISTS idx_users_email ON users(email); +CREATE INDEX IF NOT EXISTS idx_users_active ON users(is_active); diff --git a/backend/src/routes/auth.ts b/backend/src/routes/auth.ts index 84952d07..7b2bd5a9 100644 --- a/backend/src/routes/auth.ts +++ b/backend/src/routes/auth.ts @@ -20,6 +20,7 @@ import { import { ZodError } from "zod"; import { createAuthMiddleware } from "../middleware/authMiddleware"; import { type DIContainer, createDefaultContainer } from "../container/DIContainer"; +import type { EntraIdService } from "../services/EntraIdService"; /** * Zod schema for user registration @@ -81,6 +82,35 @@ export function createAuthRouter( const setupService = new SetupService(databaseService.getAdapter()); const authMiddleware = createAuthMiddleware(databaseService.getAdapter(), jwtSecret); + /** + * Resolve EntraIdService from the container (if registered). + */ + function getEntraIdService(): EntraIdService | null { + const services = (container as unknown as { services: Map }).services; + const service = services.get("entraId") as EntraIdService | undefined; + return service ?? null; + } + + /** + * GET /api/auth/providers + * Returns available authentication methods (public, no auth required) + * + * Requirements: 11.1, 11.2, 11.3, 11.4, 11.5 + */ + router.get( + "/providers", + asyncHandler((_req: Request, res: Response): void => { + const providers: Record = { local: true }; + + const entraIdService = getEntraIdService(); + if (entraIdService) { + providers.entraId = entraIdService.getProviderInfo(); + } + + res.status(200).json(providers); + }), + ); + /** * POST /api/auth/register * Register a new user account @@ -389,6 +419,35 @@ export function createAuthRouter( metadata: { userId: req.user?.userId, username: req.user?.username }, }); + // Check if user session was established via Entra ID + const entraIdService = getEntraIdService(); + if (entraIdService && req.user?.userId) { + try { + const fedIdentity = await databaseService.getAdapter().queryOne<{ + idToken: string | null; + }>( + `SELECT id_token AS "idToken" FROM federated_identities WHERE user_id = ? AND provider = 'entra-id'`, + [req.user.userId], + ); + + if (fedIdentity?.idToken) { + const entraIdLogoutUrl = entraIdService.buildLogoutUrl(fedIdentity.idToken); + res.status(200).json({ + message: "Logout successful", + entraIdLogoutUrl, + }); + return; + } + } catch (lookupErr) { + // Best-effort: federated identity lookup must not fail the logout + logger.warn("Failed to look up federated identity during logout", { + component: "AuthRouter", + operation: "logout", + metadata: { userId: req.user.userId, error: lookupErr instanceof Error ? lookupErr.message : String(lookupErr) }, + }); + } + } + // Return 200 OK with success message res.status(200).json({ message: "Logout successful", diff --git a/backend/src/routes/entraIdAuth.ts b/backend/src/routes/entraIdAuth.ts new file mode 100644 index 00000000..97e29360 --- /dev/null +++ b/backend/src/routes/entraIdAuth.ts @@ -0,0 +1,264 @@ +import { Router, type Request, type Response } from "express"; +import { z } from "zod"; +import { asyncHandler } from "./asyncHandler"; +import { type EntraIdService, EntraIdError, ENTRA_ID_ERROR_CODES } from "../services/EntraIdService"; +import type { DatabaseService } from "../database/DatabaseService"; +import type { DIContainer } from "../container/DIContainer"; + +const TokenExchangeSchema = z.object({ + code: z.string().min(1, "Authorization code is required"), +}); + +/** + * Map EntraIdError codes to HTTP status codes. + */ +function httpStatusForEntraIdError(code: string): number { + switch (code) { + case ENTRA_ID_ERROR_CODES.INVALID_STATE: + return 400; + case ENTRA_ID_ERROR_CODES.INVALID_AUTH_CODE: + return 400; + case ENTRA_ID_ERROR_CODES.TOKEN_EXCHANGE_FAILED: + case ENTRA_ID_ERROR_CODES.INVALID_ID_TOKEN: + case ENTRA_ID_ERROR_CODES.AUTH_PROVIDER_ERROR: + case ENTRA_ID_ERROR_CODES.MISSING_CLAIMS: + return 401; + case ENTRA_ID_ERROR_CODES.JWKS_UNAVAILABLE: + return 503; + case ENTRA_ID_ERROR_CODES.PROVISIONING_FAILED: + return 500; + default: + return 500; + } +} + +/** + * Derive the frontend base URL from the configured redirectUri. + * The redirectUri is something like "https://app.example.com/api/auth/entra-id/callback". + * We want the origin: "https://app.example.com". + */ +function deriveFrontendUrl(redirectUri: string): string { + try { + const parsed = new URL(redirectUri); + return parsed.origin; + } catch { + return redirectUri; + } +} + +/** + * Create Entra ID authentication router. + * + * Endpoints (mounted at /api/auth/entra-id): + * GET /login — 302 redirect to Entra ID authorization endpoint + * GET /callback — handle OAuth callback, redirect to frontend with auth code + * POST /token — exchange single-use auth code for Pabawi JWT pair + * + * All endpoints return 404 when Entra ID is not enabled (service absent from container). + */ +export function createEntraIdAuthRouter( + _databaseService: DatabaseService, + container: DIContainer, +): Router { + const router = Router(); + const logger = container.resolve("logger"); + + /** + * Resolve EntraIdService from the container's service map. + * Returns null when Entra ID is not enabled. + */ + function getEntraIdService(): EntraIdService | null { + if (!container.has("entraId")) { + return null; + } + return container.resolve("entraId") ?? null; + } + + /** + * Middleware that gates all endpoints behind Entra ID availability. + */ + function requireEntraId( + _req: Request, + res: Response, + entraIdService: EntraIdService | null, + ): entraIdService is EntraIdService { + if (!entraIdService) { + res.status(404).json({ + error: { code: "NOT_FOUND", message: "Not found" }, + }); + return false; + } + return true; + } + + // ─── GET /login ───────────────────────────────────────────────────────────── + router.get( + "/login", + asyncHandler(async (_req: Request, res: Response): Promise => { + const entraIdService = getEntraIdService(); + if (!requireEntraId(_req, res, entraIdService)) return; + + try { + const { url } = await entraIdService.generateAuthorizationUrl(); + res.redirect(302, url); + } catch (error) { + if (error instanceof EntraIdError) { + const status = httpStatusForEntraIdError(error.code); + res.status(status).json({ + error: { code: error.code, message: error.message }, + }); + return; + } + + logger.error("Unexpected error during login redirect", { + component: "EntraIdAuthRouter", + operation: "login", + }, error instanceof Error ? error : undefined); + + res.status(500).json({ + error: { + code: "SERVER_CONFIGURATION_ERROR", + message: "Server configuration problem", + }, + }); + } + }), + ); + + // ─── GET /callback ────────────────────────────────────────────────────────── + router.get( + "/callback", + asyncHandler(async (req: Request, res: Response): Promise => { + const entraIdService = getEntraIdService(); + if (!requireEntraId(req, res, entraIdService)) return; + + // Handle error parameter from Entra ID (Requirement 3.9) + const errorParam = req.query.error as string | undefined; + if (errorParam) { + const errorDescription = + (req.query.error_description as string | undefined) ?? "Authentication denied by provider"; + + logger.warn("Entra ID returned error on callback", { + component: "EntraIdAuthRouter", + operation: "callback", + metadata: { error: errorParam }, + }); + + res.status(401).json({ + error: { + code: ENTRA_ID_ERROR_CODES.AUTH_PROVIDER_ERROR, + message: errorDescription, + details: { error: errorParam, errorDescription }, + }, + }); + return; + } + + const code = req.query.code as string | undefined; + const state = req.query.state as string | undefined; + + if (!code || !state) { + res.status(400).json({ + error: { + code: ENTRA_ID_ERROR_CODES.INVALID_STATE, + message: "Missing code or state parameter", + }, + }); + return; + } + + try { + const authCodeEntry = await entraIdService.handleCallback(code, state); + + // Derive frontend URL and redirect with the single-use auth code + const configService = container.resolve("config"); + const entraIdConfig = configService.getEntraIdConfig(); + if (!entraIdConfig) { + res.status(500).json({ + error: { + code: "SERVER_CONFIGURATION_ERROR", + message: "Server configuration problem", + }, + }); + return; + } + + const frontendUrl = deriveFrontendUrl(entraIdConfig.redirectUri); + res.redirect(302, `${frontendUrl}?code=${encodeURIComponent(authCodeEntry.code)}`); + } catch (error) { + if (error instanceof EntraIdError) { + const status = httpStatusForEntraIdError(error.code); + res.status(status).json({ + error: { code: error.code, message: error.message }, + }); + return; + } + + logger.error("Unexpected error during callback processing", { + component: "EntraIdAuthRouter", + operation: "callback", + }, error instanceof Error ? error : undefined); + + res.status(500).json({ + error: { + code: "SERVER_CONFIGURATION_ERROR", + message: "Server configuration problem", + }, + }); + } + }), + ); + + // ─── POST /token ──────────────────────────────────────────────────────────── + router.post( + "/token", + asyncHandler(async (req: Request, res: Response): Promise => { + const entraIdService = getEntraIdService(); + if (!requireEntraId(req, res, entraIdService)) return; + + const parseResult = TokenExchangeSchema.safeParse(req.body); + if (!parseResult.success) { + res.status(400).json({ + error: { + code: ENTRA_ID_ERROR_CODES.INVALID_AUTH_CODE, + message: "Authorization code is required", + }, + }); + return; + } + + try { + const { accessToken, refreshToken, user } = + await entraIdService.exchangeAuthCode(parseResult.data.code); + + res.status(200).json({ + token: accessToken, + refreshToken, + user, + }); + } catch (error) { + if (error instanceof EntraIdError) { + const status = httpStatusForEntraIdError(error.code); + res.status(status).json({ + error: { code: error.code, message: error.message }, + }); + return; + } + + logger.error("Unexpected error during token exchange", { + component: "EntraIdAuthRouter", + operation: "token", + }, error instanceof Error ? error : undefined); + + res.status(500).json({ + error: { + code: "SERVER_CONFIGURATION_ERROR", + message: "Server configuration problem", + }, + }); + } + }), + ); + + return router; +} diff --git a/backend/src/server.ts b/backend/src/server.ts index b8b85f19..cd44504a 100644 --- a/backend/src/server.ts +++ b/backend/src/server.ts @@ -74,6 +74,9 @@ import { AuthenticationService } from "./services/AuthenticationService"; import { UserService } from "./services/UserService"; import { RoleService } from "./services/RoleService"; import { PermissionService } from "./services/PermissionService"; +import { AuditLoggingService } from "./services/AuditLoggingService"; +import { EntraIdService } from "./services/EntraIdService"; +import { createEntraIdAuthRouter } from "./routes/entraIdAuth"; import { provisionMcpServiceUser } from "./mcp/McpServiceUser"; import { createMcpServer } from "./mcp/McpServer"; @@ -575,6 +578,70 @@ async function startServer(): Promise { const authRateLimitMiddleware = createAuthRateLimitMiddleware(); app.use("/api/auth", authRateLimitMiddleware, createAuthRouter(databaseService, container)); + // Conditionally initialize Entra ID SSO authentication + const entraIdConfig = configService.getEntraIdConfig(); + let entraIdCleanupInterval: ReturnType | undefined; + if (entraIdConfig?.enabled) { + logger.info("Entra ID authentication enabled, initializing...", { + component: "Server", + operation: "initializeEntraId", + }); + + try { + const auditLogger = new AuditLoggingService(databaseService.getAdapter()); + const authService = new AuthenticationService( + databaseService.getAdapter(), + configService.getJwtSecret(), + auditLogger, + ); + const userService = new UserService(databaseService.getAdapter(), authService); + const roleService = new RoleService(databaseService.getAdapter()); + + const entraIdService = new EntraIdService( + databaseService.getAdapter(), + entraIdConfig, + authService, + userService, + roleService, + auditLogger, + logger, + ); + container.register("entraId", entraIdService); + + app.use( + "/api/auth/entra-id", + authRateLimitMiddleware, + createEntraIdAuthRouter(databaseService, container), + ); + + // Periodic cleanup of expired OAuth state entries (every 5 minutes) + entraIdCleanupInterval = setInterval(() => { + entraIdService.cleanupExpiredState().catch((err: unknown) => { + logger.warn("Entra ID state cleanup failed", { + component: "Server", + operation: "entraIdCleanup", + metadata: { error: err instanceof Error ? err.message : String(err) }, + }); + }); + }, 5 * 60 * 1000); + + logger.info("Entra ID authentication initialized, /api/auth/entra-id routes mounted", { + component: "Server", + operation: "initializeEntraId", + }); + } catch (error) { + logger.error("Failed to initialize Entra ID authentication", { + component: "Server", + operation: "initializeEntraId", + }, error instanceof Error ? error : undefined); + } + } else { + logger.info("Entra ID authentication disabled", { + component: "Server", + operation: "initializeEntraId", + }); + } + // Create authentication and RBAC middleware instances // Wrap async middleware with asyncHandler to satisfy Express's void return expectation const authMiddleware = asyncHandler(createAuthMiddleware(databaseService.getAdapter(), configService.getJwtSecret())); @@ -1010,6 +1077,9 @@ async function startServer(): Promise { }); streamingManager.cleanup(); integrationManager.stopHealthCheckScheduler(); + if (entraIdCleanupInterval) { + clearInterval(entraIdCleanupInterval); + } server.close(() => { void databaseService.close().then(() => { logger.info("Server closed", { diff --git a/backend/src/services/EntraIdService.ts b/backend/src/services/EntraIdService.ts new file mode 100644 index 00000000..450d63b3 --- /dev/null +++ b/backend/src/services/EntraIdService.ts @@ -0,0 +1,902 @@ +import { createHash, createPublicKey, randomBytes } from 'crypto'; + +import jwt from 'jsonwebtoken'; + +import type { DatabaseAdapter } from '../database/DatabaseAdapter'; +import type { EntraIdConfig } from '../config/schema'; +import type { AuthenticationService } from './AuthenticationService'; +import type { UserService, User } from './UserService'; +import type { UserDTO } from './UserService'; +import type { RoleService } from './RoleService'; +import type { AuditLoggingService } from './AuditLoggingService'; +import type { LoggerService } from './LoggerService'; + +// --- Error code constants --- +export const ENTRA_ID_ERROR_CODES = { + INVALID_STATE: 'INVALID_STATE', + TOKEN_EXCHANGE_FAILED: 'TOKEN_EXCHANGE_FAILED', + INVALID_ID_TOKEN: 'INVALID_ID_TOKEN', + AUTH_PROVIDER_ERROR: 'AUTH_PROVIDER_ERROR', + MISSING_CLAIMS: 'MISSING_CLAIMS', + JWKS_UNAVAILABLE: 'JWKS_UNAVAILABLE', + PROVISIONING_FAILED: 'PROVISIONING_FAILED', + INVALID_AUTH_CODE: 'INVALID_AUTH_CODE', +} as const; + +export type EntraIdErrorCode = typeof ENTRA_ID_ERROR_CODES[keyof typeof ENTRA_ID_ERROR_CODES]; + +// --- Typed error class --- +export class EntraIdError extends Error { + readonly code: EntraIdErrorCode; + + constructor(code: EntraIdErrorCode, message: string) { + super(message); + this.name = 'EntraIdError'; + this.code = code; + } +} + +// --- IdTokenClaims interface --- +export interface IdTokenClaims { + sub: string; + email: string; + preferred_username: string; + given_name: string; + family_name: string; + nonce: string; + aud: string; + iss: string; + exp: number; + groups?: string[]; +} + +export interface OAuthStateEntry { + state: string; + nonce: string; + codeVerifier: string; + createdAt: string; + expiresAt: string; +} + +export interface AuthCodeEntry { + code: string; + accessToken: string; + refreshToken: string; + userId: string; + idToken: string; + authMethod: string; + createdAt: string; + expiresAt: string; +} + +// --- JWKS types --- +interface JwksKey { + kty: string; + use?: string; + kid: string; + n: string; + e: string; + x5c?: string[]; +} + +interface JwksCache { + keys: JwksKey[]; + fetchedAt: number; +} + +/** + * EntraIdService handles Azure Entra ID (OpenID Connect) authentication. + * + * This service manages: + * - Authorization URL generation with PKCE and state/nonce + * - State store lifecycle (creation + TTL-based expiry cleanup) + * - Token exchange and ID token validation + * - JWKS key fetching and caching + * - Provider metadata for frontend discovery + */ +export class EntraIdService { + private readonly db: DatabaseAdapter; + private readonly config: EntraIdConfig; + readonly authService: AuthenticationService; + readonly userService: UserService; + readonly roleService: RoleService; + readonly auditLogger: AuditLoggingService; + private readonly logger: LoggerService; + private jwksCache: JwksCache | null = null; + + constructor( + db: DatabaseAdapter, + config: EntraIdConfig, + authService: AuthenticationService, + userService: UserService, + roleService: RoleService, + auditLogger: AuditLoggingService, + logger: LoggerService, + ) { + this.db = db; + this.config = config; + this.authService = authService; + this.userService = userService; + this.roleService = roleService; + this.auditLogger = auditLogger; + this.logger = logger; + } + + /** + * Generate an authorization URL for the Entra ID OAuth 2.0 + OIDC flow. + * + * Creates cryptographically random state, nonce, and PKCE code_verifier, + * stores them in oauth_state_store with a 10-minute TTL, then returns + * the full authorization endpoint URL with all required query parameters. + */ + async generateAuthorizationUrl(): Promise<{ url: string; state: string }> { + const state = randomBytes(32).toString('hex'); + const nonce = randomBytes(32).toString('hex'); + const codeVerifier = this.generateCodeVerifier(64); + const codeChallenge = this.computeCodeChallenge(codeVerifier); + + const now = new Date(); + const createdAt = now.toISOString(); + const expiresAt = new Date(now.getTime() + 10 * 60 * 1000).toISOString(); + + await this.db.execute( + `INSERT INTO oauth_state_store (state, nonce, code_verifier, created_at, expires_at) + VALUES (?, ?, ?, ?, ?)`, + [state, nonce, codeVerifier, createdAt, expiresAt], + ); + + const params = new URLSearchParams({ + response_type: 'code', + client_id: this.config.clientId, + redirect_uri: this.config.redirectUri, + scope: this.config.scopes.join(' '), + state, + nonce, + code_challenge: codeChallenge, + code_challenge_method: 'S256', + }); + + const baseUrl = `https://login.microsoftonline.com/${this.config.tenantId}/oauth2/v2.0/authorize`; + const url = `${baseUrl}?${params.toString()}`; + + this.logger.info('Generated authorization URL', { + component: 'EntraIdService', + operation: 'generateAuthorizationUrl', + metadata: { tenantId: this.config.tenantId }, + }); + + return { url, state }; + } + + /** + * Delete expired entries from oauth_state_store. + * + * @returns Number of deleted rows + */ + async cleanupExpiredState(): Promise { + const now = new Date().toISOString(); + const result = await this.db.execute( + `DELETE FROM oauth_state_store WHERE expires_at < ?`, + [now], + ); + + const deleted = result.changes; + + if (deleted > 0) { + this.logger.info(`Cleaned up ${String(deleted)} expired OAuth state entries`, { + component: 'EntraIdService', + operation: 'cleanupExpiredState', + metadata: { deletedCount: deleted }, + }); + } + + return deleted; + } + + /** + * Return provider info for the discovery endpoint. + */ + getProviderInfo(): { enabled: true; name: string } { + return { enabled: true, name: 'Microsoft Entra ID' }; + } + + /** + * Handle the OAuth callback: validate state, exchange code for tokens, + * validate the ID token, provision/lookup user, sync roles, issue session. + * + * Returns an AuthCodeEntry containing the single-use authorization code + * that the frontend will exchange for the actual JWT pair. + */ + async handleCallback(code: string, state: string): Promise { + const logMeta = { component: 'EntraIdService', operation: 'handleCallback' }; + + // 1. Look up state entry + const stateEntry = await this.db.queryOne<{ + state: string; + nonce: string; + code_verifier: string; + created_at: string; + expires_at: string; + }>( + `SELECT state, nonce, code_verifier, created_at, expires_at + FROM oauth_state_store WHERE state = ?`, + [state], + ); + + // 2. Delete state entry immediately (one-time use, even on failure) + await this.db.execute( + `DELETE FROM oauth_state_store WHERE state = ?`, + [state], + ); + + // 3. Validate state exists + if (!stateEntry) { + this.logger.warn('OAuth callback received with invalid state', logMeta); + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.INVALID_STATE, + 'State parameter missing or mismatched', + ); + } + + // 4. Verify state not expired + const now = new Date(); + const expiresAt = new Date(stateEntry.expires_at); + if (now > expiresAt) { + this.logger.warn('OAuth callback received with expired state', logMeta); + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.INVALID_STATE, + 'Authentication session expired', + ); + } + + // 5. Exchange authorization code for tokens + const tokenResponse = await this.exchangeCodeForTokens( + code, + stateEntry.code_verifier, + ); + + // 6. Fetch JWKS keys (cached) + const jwksKeys = await this.getJwksKeys(); + + // 7. Verify ID token + const claims = this.verifyIdToken( + tokenResponse.id_token, + jwksKeys, + stateEntry.nonce, + ); + + this.logger.info('ID token validated successfully', { + ...logMeta, + metadata: { sub: claims.sub }, + }); + + // 8. Provision or look up the user + const user = await this.provisionUser(claims); + + // 9. Sync group-to-role mapping + await this.syncGroupRoles(user.id, claims.groups); + + // 10. Issue session tokens and generate auth code + const authCodeEntry = await this.issueSessionTokens( + user, + tokenResponse.id_token, + ); + + return authCodeEntry; + } + + /** + * Provision or locate a user based on validated ID token claims. + * + * Flow: + * 1. Reject if email AND preferred_username are both missing + * 2. Look up federated_identities by (provider='entra-id', subject=sub) + * 3. If found: return existing user without updating profile (immutability) + * 4. If not found: check users by email + * 5. If email match: link federated identity to existing account + * 6. If no match: create new federated user + * + * @param claims - Validated ID token claims + * @returns The provisioned or existing user + */ + async provisionUser(claims: IdTokenClaims): Promise { + const logMeta = { component: 'EntraIdService', operation: 'provisionUser' }; + + // 1. Reject if both email and preferred_username are missing + if (!claims.email && !claims.preferred_username) { + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.MISSING_CLAIMS, + 'Required identity claims absent: email and preferred_username', + ); + } + + // 2. Look up by federated identity + const existingUser = await this.userService.findByFederatedIdentity( + 'entra-id', + claims.sub, + ); + + if (existingUser) { + // 3. Returning user — do NOT update profile claims (immutability) + this.logger.info('Returning federated user found', { + ...logMeta, + metadata: { userId: existingUser.id, sub: claims.sub }, + }); + return existingUser; + } + + // 4. No federated identity — check by email + if (claims.email) { + const emailMatch = await this.userService.findByEmail(claims.email); + + if (emailMatch) { + // 5. Email match — link federated identity to existing account + try { + await this.userService.linkFederatedIdentity( + emailMatch.id, + 'entra-id', + claims.sub, + claims.iss, + claims.email, + ); + + this.logger.info('Linked federated identity to existing account', { + ...logMeta, + metadata: { userId: emailMatch.id, sub: claims.sub }, + }); + + return emailMatch; + } catch (err: unknown) { + const message = err instanceof Error ? err.message : String(err); + this.logger.error('Failed to link federated identity', { + ...logMeta, + metadata: { error: message }, + }); + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.PROVISIONING_FAILED, + 'Account creation failed', + ); + } + } + } + + // 6. No match — create new federated user + try { + const newUser = await this.userService.createFederatedUser(claims); + + this.logger.info('New federated user created', { + ...logMeta, + metadata: { userId: newUser.id, sub: claims.sub }, + }); + + return newUser; + } catch (err: unknown) { + const message = err instanceof Error ? err.message : String(err); + this.logger.error('Failed to create federated user', { + ...logMeta, + metadata: { error: message }, + }); + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.PROVISIONING_FAILED, + 'Account creation failed', + ); + } + } + + /** + * Issue Pabawi JWT session tokens and generate a single-use authorization code. + * + * Steps: + * 1. Generate access + refresh tokens via AuthenticationService + * 2. Generate a crypto-random single-use authorization code + * 3. Store the code in oauth_auth_codes with 60s TTL + * 4. Update user's last_login_at timestamp + * 5. Record audit log (AUTH, LOGIN_SUCCESS, method=entra-id) + * + * @returns AuthCodeEntry for the frontend to exchange + */ + private async issueSessionTokens( + user: User, + idToken: string, + ): Promise { + const logMeta = { component: 'EntraIdService', operation: 'issueSessionTokens' }; + + // 1. Generate Pabawi JWT tokens + const accessToken = await this.authService.generateToken(user); + const refreshToken = await this.authService.generateRefreshToken(user); + + // 2. Generate single-use authorization code (32 bytes of entropy) + const authCode = randomBytes(32).toString('hex'); + + // 3. Store in oauth_auth_codes with 60-second TTL + const now = new Date(); + const createdAt = now.toISOString(); + const expiresAt = new Date(now.getTime() + 60 * 1000).toISOString(); + + await this.db.execute( + `INSERT INTO oauth_auth_codes (code, access_token, refresh_token, user_id, id_token, auth_method, created_at, expires_at, exchanged) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)`, + [authCode, accessToken, refreshToken, user.id, idToken, 'entra-id', createdAt, expiresAt], + ); + + // 4. Update user's last_login_at + const loginTime = now.toISOString(); + await this.db.execute( + `UPDATE users SET last_login_at = ? WHERE id = ?`, + [loginTime, user.id], + ); + + // 5. Record audit log + await this.auditLogger.logAuthenticationAttempt( + user.username, + true, + user.id, + undefined, + undefined, + 'method=entra-id', + ); + + this.logger.info('Session tokens issued for SSO user', { + ...logMeta, + metadata: { userId: user.id }, + }); + + return { + code: authCode, + accessToken, + refreshToken, + userId: user.id, + idToken, + authMethod: 'entra-id', + createdAt, + expiresAt, + }; + } + + /** + * Exchange a single-use authorization code for Pabawi JWT tokens + user DTO. + * + * Validates that the code exists, is not expired, and has not been exchanged. + * Marks the code as exchanged atomically. Returns the stored tokens and user. + * + * @throws EntraIdError with INVALID_AUTH_CODE if code is invalid, expired, or already used. + */ + async exchangeAuthCode(code: string): Promise<{ + accessToken: string; + refreshToken: string; + user: UserDTO; + }> { + const logMeta = { component: 'EntraIdService', operation: 'exchangeAuthCode' }; + + // 1. Look up the code + const entry = await this.db.queryOne<{ + code: string; + accessToken: string; + refreshToken: string; + userId: string; + idToken: string; + authMethod: string; + createdAt: string; + expiresAt: string; + exchanged: number; + }>( + `SELECT code, + access_token AS "accessToken", + refresh_token AS "refreshToken", + user_id AS "userId", + id_token AS "idToken", + auth_method AS "authMethod", + created_at AS "createdAt", + expires_at AS "expiresAt", + exchanged + FROM oauth_auth_codes WHERE code = ?`, + [code], + ); + + // 2. Verify code exists + if (!entry) { + this.logger.warn('Auth code exchange attempted with invalid code', logMeta); + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.INVALID_AUTH_CODE, + 'Authorization code invalid', + ); + } + + // 3. Verify not already exchanged + if (entry.exchanged === 1) { + this.logger.warn('Auth code exchange attempted with already-used code', logMeta); + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.INVALID_AUTH_CODE, + 'Authorization code invalid', + ); + } + + // 4. Verify not expired + const now = new Date(); + const expiresAt = new Date(entry.expiresAt); + if (now > expiresAt) { + this.logger.warn('Auth code exchange attempted with expired code', logMeta); + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.INVALID_AUTH_CODE, + 'Authorization code invalid', + ); + } + + // 5. Mark as exchanged + await this.db.execute( + `UPDATE oauth_auth_codes SET exchanged = 1 WHERE code = ?`, + [code], + ); + + // 6. Look up the user + const user = await this.userService.getUserById(entry.userId); + if (!user) { + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.INVALID_AUTH_CODE, + 'Authorization code invalid', + ); + } + + this.logger.info('Auth code exchanged successfully', { + ...logMeta, + metadata: { userId: user.id }, + }); + + return { + accessToken: entry.accessToken, + refreshToken: entry.refreshToken, + user: this.userService.toUserDTO(user), + }; + } + + /** + * Exchange authorization code at the Entra ID token endpoint. + * Uses AbortSignal.timeout(10000) for 10-second timeout. + */ + private async exchangeCodeForTokens( + code: string, + codeVerifier: string, + ): Promise<{ id_token: string; access_token: string }> { + const logMeta = { component: 'EntraIdService', operation: 'exchangeCodeForTokens' }; + const tokenUrl = `https://login.microsoftonline.com/${this.config.tenantId}/oauth2/v2.0/token`; + + const body = new URLSearchParams({ + grant_type: 'authorization_code', + client_id: this.config.clientId, + client_secret: this.config.clientSecret, + code, + redirect_uri: this.config.redirectUri, + code_verifier: codeVerifier, + }); + + let response: Response; + try { + response = await fetch(tokenUrl, { + method: 'POST', + headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, + body: body.toString(), + signal: AbortSignal.timeout(10000), + }); + } catch (err: unknown) { + const message = err instanceof Error ? err.message : 'Unknown error'; + this.logger.error('Token exchange network failure', { + ...logMeta, + metadata: { error: message }, + }); + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.TOKEN_EXCHANGE_FAILED, + 'Token endpoint unreachable', + ); + } + + if (!response.ok) { + this.logger.error('Token exchange returned non-2xx', { + ...logMeta, + metadata: { status: response.status }, + }); + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.TOKEN_EXCHANGE_FAILED, + 'Could not exchange authorization code', + ); + } + + const data = await response.json() as { id_token?: string; access_token?: string }; + + if (!data.id_token || !data.access_token) { + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.TOKEN_EXCHANGE_FAILED, + 'Token response missing required fields', + ); + } + + return { id_token: data.id_token, access_token: data.access_token }; + } + + /** + * Fetch JWKS keys from the Entra ID discovery endpoint. + * Caches keys with configurable TTL. Falls back to cache on failure. + */ + private async getJwksKeys(): Promise { + const logMeta = { component: 'EntraIdService', operation: 'getJwksKeys' }; + const ttl = this.config.jwksCacheTtlMs; + + // Return cached keys if still valid + if (this.jwksCache && (Date.now() - this.jwksCache.fetchedAt) < ttl) { + return this.jwksCache.keys; + } + + const jwksUrl = `https://login.microsoftonline.com/${this.config.tenantId}/discovery/v2.0/keys`; + + try { + const response = await fetch(jwksUrl, { + signal: AbortSignal.timeout(5000), + }); + + if (!response.ok) { + throw new Error(`JWKS endpoint returned ${String(response.status)}`); + } + + const data = await response.json() as { keys: JwksKey[] }; + this.jwksCache = { keys: data.keys, fetchedAt: Date.now() }; + return data.keys; + } catch (err: unknown) { + const message = err instanceof Error ? err.message : 'Unknown error'; + this.logger.warn('JWKS fetch failed, attempting cache fallback', { + ...logMeta, + metadata: { error: message }, + }); + + // Fallback to stale cache if available + if (this.jwksCache) { + this.logger.warn('Using stale JWKS cache', logMeta); + return this.jwksCache.keys; + } + + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.JWKS_UNAVAILABLE, + 'Cannot verify token signatures', + ); + } + } + + /** + * Verify the ID token: signature (RS256 via JWKS), nonce, aud, iss, exp. + */ + private verifyIdToken( + idToken: string, + jwksKeys: JwksKey[], + expectedNonce: string, + ): IdTokenClaims { + // Decode header to find kid + const decoded = jwt.decode(idToken, { complete: true }); + if (!decoded || typeof decoded === 'string') { + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.INVALID_ID_TOKEN, + 'Token could not be decoded', + ); + } + + const kid = decoded.header.kid; + const key = jwksKeys.find((k) => k.kid === kid); + if (!key) { + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.INVALID_ID_TOKEN, + 'Token signature verification failed - key not found', + ); + } + + // Convert JWK to PEM + const pem = this.jwkToPem(key); + + // Verify signature, exp (with 5min clockTolerance), aud, iss + const expectedIssuer = `https://login.microsoftonline.com/${this.config.tenantId}/v2.0`; + + let payload: jwt.JwtPayload; + try { + payload = jwt.verify(idToken, pem, { + algorithms: ['RS256'], + audience: this.config.clientId, + issuer: expectedIssuer, + clockTolerance: 300, // 5 minutes in seconds + }) as jwt.JwtPayload; + } catch (err: unknown) { + const message = err instanceof Error ? err.message : 'Token verification failed'; + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.INVALID_ID_TOKEN, + message, + ); + } + + // Validate nonce + if (payload.nonce !== expectedNonce) { + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.INVALID_ID_TOKEN, + 'Token nonce validation failed', + ); + } + + // Validate required claims presence + const missingClaims: string[] = []; + if (!payload.sub) missingClaims.push('sub'); + if (!payload.email && !payload.preferred_username) { + missingClaims.push('email or preferred_username'); + } + + if (missingClaims.length > 0) { + throw new EntraIdError( + ENTRA_ID_ERROR_CODES.MISSING_CLAIMS, + `Required identity claims absent: ${missingClaims.join(', ')}`, + ); + } + + return { + sub: payload.sub!, + email: String(payload.email ?? ''), + preferred_username: String(payload.preferred_username ?? ''), + given_name: String(payload.given_name ?? ''), + family_name: String(payload.family_name ?? ''), + nonce: payload.nonce as string, + aud: (Array.isArray(payload.aud) ? payload.aud[0] : payload.aud)!, + iss: payload.iss!, + exp: payload.exp!, + groups: payload.groups as string[] | undefined, + }; + } + + /** + * Convert a JWK RSA key to PEM format using Node.js crypto. + */ + private jwkToPem(key: JwksKey): string { + const publicKey = createPublicKey({ + key: { + kty: key.kty, + n: key.n, + e: key.e, + }, + format: 'jwk', + }); + + return publicKey.export({ type: 'spki', format: 'pem' }) as string; + } + + /** + * Synchronize Entra ID group memberships to Pabawi roles. + * + * Algorithm: + * 1. If groupMapping is null or groups is undefined → skip (preserve existing roles) + * 2. Get all Pabawi roles to validate mapping targets + * 3. Get user's current roles + * 4. Determine which mapped roles the user should have (based on groups claim) + * 5. Add roles that are in "should have" but not currently assigned + * 6. Remove roles that are currently assigned via mapping but no longer in "should have" + * 7. Never touch roles that are not part of the mapping (manually assigned roles preserved) + */ + async syncGroupRoles(userId: string, groups: string[] | undefined): Promise { + const logMeta = { component: 'EntraIdService', operation: 'syncGroupRoles' }; + + // Skip sync if no mapping configured or no groups claim present + if (!this.config.groupMapping || groups === undefined) { + this.logger.info('Skipping group-to-role sync (no mapping or no groups claim)', logMeta); + return; + } + + const groupMapping = this.config.groupMapping; + + // Get all available Pabawi roles + const allRolesResult = await this.roleService.listRoles({ limit: 1000, offset: 0 }); + const allRoles = allRolesResult.items; + const rolesByName = new Map(allRoles.map((r) => [r.name.toLowerCase(), r])); + + // Get user's current roles + const currentRoles = await this.userService.getUserRoles(userId); + const currentRoleIds = new Set(currentRoles.map((r) => r.id)); + + // Normalize groups claim to lowercase for case-insensitive comparison + const normalizedGroups = new Set(groups.map((g) => g.toLowerCase())); + + // Determine which role IDs are managed by the mapping (all valid mapping targets) + const managedRoleIds = new Set(); + // Determine which role IDs the user should have based on current groups + const shouldHaveRoleIds = new Set(); + + for (const [groupId, roleName] of Object.entries(groupMapping)) { + const role = rolesByName.get(roleName.toLowerCase()); + + if (!role) { + this.logger.warn(`Group mapping references non-existent role "${roleName}", skipping`, { + ...logMeta, + metadata: { groupId, roleName }, + }); + continue; + } + + managedRoleIds.add(role.id); + + // Case-insensitive UUID comparison + if (normalizedGroups.has(groupId.toLowerCase())) { + shouldHaveRoleIds.add(role.id); + } + } + + // Assign roles that user should have but doesn't + let assigned = 0; + for (const roleId of shouldHaveRoleIds) { + if (!currentRoleIds.has(roleId)) { + try { + await this.userService.assignRoleToUser(userId, roleId); + assigned++; + } catch (err: unknown) { + // Role may already be assigned (race condition) — log and continue + const message = err instanceof Error ? err.message : 'Unknown error'; + this.logger.warn(`Failed to assign role during group sync: ${message}`, logMeta); + } + } + } + + // Revoke managed roles that user currently has but should no longer have + let revoked = 0; + for (const roleId of managedRoleIds) { + if (currentRoleIds.has(roleId) && !shouldHaveRoleIds.has(roleId)) { + try { + await this.userService.removeRoleFromUser(userId, roleId); + revoked++; + } catch (err: unknown) { + const message = err instanceof Error ? err.message : 'Unknown error'; + this.logger.warn(`Failed to revoke role during group sync: ${message}`, logMeta); + } + } + } + + this.logger.info('Group-to-role sync completed', { + ...logMeta, + metadata: { userId, assigned, revoked, groupCount: groups.length }, + }); + } + + /** + * Build the Entra ID end-session URL for single sign-out. + * + * Constructs the logout URL with: + * - post_logout_redirect_uri: from config (or fallback to base URL) + * - id_token_hint: the user's stored ID token + * + * @param idToken - The ID token stored from the user's SSO session + * @returns Full Entra ID logout URL + */ + buildLogoutUrl(idToken: string): string { + const baseLogoutUrl = + `https://login.microsoftonline.com/${this.config.tenantId}/oauth2/v2.0/logout`; + + const postLogoutRedirectUri = this.config.postLogoutRedirectUri ?? this.config.redirectUri; + + const params = new URLSearchParams({ + post_logout_redirect_uri: postLogoutRedirectUri, + id_token_hint: idToken, + }); + + return `${baseLogoutUrl}?${params.toString()}`; + } + + /** + * Generate a code_verifier per RFC 7636 Section 4.1. + * Uses unreserved characters [A-Z, a-z, 0-9, "-", ".", "_", "~"]. + */ + private generateCodeVerifier(length: number): string { + const unreserved = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~'; + const bytes = randomBytes(length); + let verifier = ''; + for (let i = 0; i < length; i++) { + verifier += unreserved[bytes[i] % unreserved.length]; + } + return verifier; + } + + /** + * Compute code_challenge from code_verifier using S256 method. + * SHA-256 hash → base64url encoding (no padding). + */ + private computeCodeChallenge(codeVerifier: string): string { + const hash = createHash('sha256').update(codeVerifier).digest(); + return hash.toString('base64url'); + } +} diff --git a/backend/src/services/UserService.ts b/backend/src/services/UserService.ts index 1fd51651..ca255b4a 100644 --- a/backend/src/services/UserService.ts +++ b/backend/src/services/UserService.ts @@ -3,6 +3,7 @@ import { randomUUID } from 'crypto'; import type { AuthenticationService } from './AuthenticationService'; import { SetupService } from './SetupService'; import { validatePassword } from '../utils/passwordValidation'; +import type { IdTokenClaims } from './EntraIdService'; /** * User model from database @@ -48,6 +49,16 @@ const ROLE_COLUMNS = `id, name, description, created_at AS "createdAt", updated_at AS "updatedAt"`; +const FEDERATED_IDENTITY_COLUMNS = `id, + user_id AS "userId", + provider, + subject, + issuer, + email, + id_token AS "idToken", + created_at AS "createdAt", + updated_at AS "updatedAt"`; + /** * User data transfer object (without password) */ @@ -133,6 +144,21 @@ export interface Role { updatedAt: string; } +/** + * Federated identity link — maps an external IdP subject to a Pabawi user + */ +export interface FederatedIdentity { + id: string; + userId: string; + provider: string; + subject: string; + issuer: string; + email: string | null; + idToken: string | null; + createdAt: string; + updatedAt: string; +} + /** * User service for managing user accounts, profiles, and user-group/role relationships * @@ -635,4 +661,193 @@ export class UserService { }; } + /** + * Derive a valid username from IdToken claims. + * + * If preferred_username matches ^[a-zA-Z0-9_]{3,50}$, use it directly. + * Otherwise, derive from the email local-part by replacing disallowed + * characters with underscores and truncating to 50 characters. + */ + private deriveUsername(claims: IdTokenClaims): string { + const validUsernamePattern = /^[a-zA-Z0-9_]{3,50}$/; + + if (claims.preferred_username && validUsernamePattern.test(claims.preferred_username)) { + return claims.preferred_username; + } + + const localPart = claims.email.split('@')[0]; + const sanitized = localPart.replace(/[^a-zA-Z0-9_]/g, '_'); + return sanitized.slice(0, 50); + } + + /** + * Create a new user from federated identity (SSO) claims. + * + * Creates the user with null password_hash, is_active=1, assigns the + * default viewer role, and creates a federated_identities record linking + * the user to the external IdP. + * + * @param claims - Validated ID token claims from the identity provider + * @returns Created user + * @throws Error if username uniqueness constraint is violated + */ + public async createFederatedUser(claims: IdTokenClaims): Promise { + const username = this.deriveUsername(claims); + + // Use a transaction to ensure atomicity — no partial records + return this.db.withTransaction(async () => { + // Check username uniqueness + const existingUsername = await this.getUserByUsername(username); + if (existingUsername) { + throw new Error( + `Account creation failed: derived username "${username}" already exists` + ); + } + + // Check email uniqueness (a separate user with this email should not exist; + // email-match linking is handled by the caller before invoking this method) + const existingEmail = await this.getUserByEmail(claims.email); + if (existingEmail) { + throw new Error( + `Account creation failed: email "${claims.email}" already exists` + ); + } + + const userId = randomUUID(); + const now = new Date().toISOString(); + + // Insert user with null password_hash (federation-only) + await this.db.execute( + `INSERT INTO users (id, username, email, password_hash, first_name, last_name, is_active, is_admin, created_at, updated_at) + VALUES (?, ?, ?, NULL, ?, ?, 1, 0, ?, ?)`, + [ + userId, + username, + claims.email, + claims.given_name || '', + claims.family_name || '', + now, + now + ] + ); + + // Assign default viewer role + const defaultRoleId = await this.setupService.getDefaultNewUserRole(); + if (defaultRoleId) { + await this.db.execute( + `INSERT INTO user_roles (user_id, role_id, assigned_at) VALUES (?, ?, ?)`, + [userId, defaultRoleId, now] + ); + } + + // Create federated identity record + const federatedId = randomUUID(); + await this.db.execute( + `INSERT INTO federated_identities (id, user_id, provider, subject, issuer, email, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, + [ + federatedId, + userId, + 'entra-id', + claims.sub, + claims.iss, + claims.email, + now, + now + ] + ); + + const user = await this.getUserById(userId); + if (!user) { + throw new Error('Failed to create federated user'); + } + + return user; + }); + } + + /** + * Link an existing user account to a federated identity. + * + * Used when a local user with the same email is found during SSO login — + * preserves the existing password_hash so local login remains available. + * + * @param userId - Existing Pabawi user ID + * @param provider - Identity provider name (e.g. 'entra-id') + * @param subject - The IdP subject claim (unique per tenant+user) + * @param issuer - Token issuer URL + * @param email - Email from the IdP (informational) + */ + public async linkFederatedIdentity( + userId: string, + provider: string, + subject: string, + issuer: string, + email: string | null, + ): Promise { + const id = randomUUID(); + const now = new Date().toISOString(); + + try { + await this.db.execute( + `INSERT INTO federated_identities (id, user_id, provider, subject, issuer, email, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, + [id, userId, provider, subject, issuer, email, now, now] + ); + } catch (err: unknown) { + const message = err instanceof Error ? err.message : String(err); + if (message.includes('UNIQUE') || message.includes('unique') || message.includes('duplicate')) { + throw new Error( + `Federated identity already linked: provider=${provider}, subject=${subject}` + ); + } + throw err; + } + + const identity = await this.db.queryOne( + `SELECT ${FEDERATED_IDENTITY_COLUMNS} FROM federated_identities WHERE id = ?`, + [id] + ); + if (!identity) { + throw new Error('Failed to create federated identity link'); + } + + return identity; + } + + /** + * Look up a user by their federated identity (provider + subject). + * + * @param provider - Identity provider name (e.g. 'entra-id') + * @param subject - The IdP subject claim + * @returns The linked user, or null if no matching federated identity exists + */ + public async findByFederatedIdentity( + provider: string, + subject: string, + ): Promise { + const identity = await this.db.queryOne( + `SELECT ${FEDERATED_IDENTITY_COLUMNS} FROM federated_identities + WHERE provider = ? AND subject = ?`, + [provider, subject] + ); + + if (!identity) { + return null; + } + + return this.getUserById(identity.userId); + } + + /** + * Public wrapper around the private getUserByEmail method. + * Used by EntraIdService for email-match account linking during SSO. + * + * @param email - Email address to search for + * @returns User or null if not found + */ + public async findByEmail(email: string): Promise { + return this.getUserByEmail(email); + } + } diff --git a/backend/test/database/migration-integration.test.ts b/backend/test/database/migration-integration.test.ts index ff123007..c9cc449a 100644 --- a/backend/test/database/migration-integration.test.ts +++ b/backend/test/database/migration-integration.test.ts @@ -28,8 +28,8 @@ describe('Migration Integration Test', () => { it('should apply all migrations on initialization', async () => { const status = await dbService.getMigrationStatus(); - // Should have applied all migrations (000 through 015, no 012 in source) - expect(status.applied).toHaveLength(15); + // Should have applied all migrations (000 through 017, no 012 in source) + expect(status.applied).toHaveLength(17); expect(status.applied[0].id).toBe('000'); expect(status.applied[1].id).toBe('001'); expect(status.applied[2].id).toBe('002'); @@ -45,6 +45,8 @@ describe('Migration Integration Test', () => { expect(status.applied[12].id).toBe('013'); expect(status.applied[13].id).toBe('014'); expect(status.applied[14].id).toBe('015'); + expect(status.applied[15].id).toBe('016'); + expect(status.applied[16].id).toBe('017'); expect(status.pending).toHaveLength(0); }); @@ -85,8 +87,8 @@ describe('Migration Integration Test', () => { const status = await dbService2.getMigrationStatus(); - // Should still have 15 applied, 0 pending - expect(status.applied).toHaveLength(15); + // Should still have 17 applied, 0 pending + expect(status.applied).toHaveLength(17); expect(status.pending).toHaveLength(0); await dbService2.close(); diff --git a/backend/test/database/rbac-schema.test.ts b/backend/test/database/rbac-schema.test.ts index 6dc7b1de..1b30ae6a 100644 --- a/backend/test/database/rbac-schema.test.ts +++ b/backend/test/database/rbac-schema.test.ts @@ -32,7 +32,7 @@ describe('RBAC Database Schema', () => { expect(result.sql).toContain('id TEXT PRIMARY KEY'); expect(result.sql).toContain('username TEXT NOT NULL UNIQUE'); expect(result.sql).toContain('email TEXT NOT NULL UNIQUE'); - expect(result.sql).toContain('password_hash TEXT NOT NULL'); + expect(result.sql).toContain('password_hash TEXT'); expect(result.sql).toContain('is_active INTEGER NOT NULL DEFAULT 1'); expect(result.sql).toContain('is_admin INTEGER NOT NULL DEFAULT 0'); }); diff --git a/backend/test/integration/EntraIdAuthFlow.test.ts b/backend/test/integration/EntraIdAuthFlow.test.ts new file mode 100644 index 00000000..e7f103e5 --- /dev/null +++ b/backend/test/integration/EntraIdAuthFlow.test.ts @@ -0,0 +1,639 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import express, { type Express } from 'express'; +import request from 'supertest'; +import crypto from 'crypto'; +import jwt from 'jsonwebtoken'; + +import { createEntraIdAuthRouter } from '../../src/routes/entraIdAuth'; +import { createAuthRouter } from '../../src/routes/auth'; +import { DatabaseService } from '../../src/database/DatabaseService'; +import { EntraIdService } from '../../src/services/EntraIdService'; +import { AuthenticationService } from '../../src/services/AuthenticationService'; +import { UserService } from '../../src/services/UserService'; +import { RoleService } from '../../src/services/RoleService'; +import { AuditLoggingService } from '../../src/services/AuditLoggingService'; +import { LoggerService } from '../../src/services/LoggerService'; +import { DIContainer } from '../../src/container/DIContainer'; +import { ConfigService } from '../../src/config/ConfigService'; +import type { EntraIdConfig } from '../../src/config/schema'; + +// --- Test RSA key pair for signing ID tokens --- +const { publicKey, privateKey } = crypto.generateKeyPairSync('rsa', { + modulusLength: 2048, + publicKeyEncoding: { type: 'spki', format: 'pem' }, + privateKeyEncoding: { type: 'pkcs8', format: 'pem' }, +}); + +const TEST_KID = 'test-key-id-001'; + +function pemToJwk(pem: string, kid: string): { + kty: string; use: string; kid: string; n: string; e: string; +} { + const keyObj = crypto.createPublicKey(pem); + const jwk = keyObj.export({ format: 'jwk' }); + return { + kty: 'RSA', + use: 'sig', + kid, + n: jwk.n as string, + e: jwk.e as string, + }; +} + +const TEST_JWK = pemToJwk(publicKey, TEST_KID); + +// --- Test Entra ID configuration --- +const TEST_TENANT_ID = 'test-tenant-id-12345'; +const TEST_CLIENT_ID = 'test-client-id-67890'; +const TEST_CLIENT_SECRET = 'test-client-secret-abcdef'; // pragma: allowlist secret +const TEST_REDIRECT_URI = 'http://localhost:3000/api/auth/entra-id/callback'; + +const testEntraIdConfig: EntraIdConfig = { + enabled: true, + tenantId: TEST_TENANT_ID, + clientId: TEST_CLIENT_ID, + clientSecret: TEST_CLIENT_SECRET, // pragma: allowlist secret + redirectUri: TEST_REDIRECT_URI, + scopes: ['openid', 'profile', 'email'], + groupMapping: null, + postLogoutRedirectUri: 'http://localhost:3000', + jwksCacheTtlMs: 86400000, +}; + +/** + * Sign a test ID token with our test private key. + * Note: Do NOT include `exp` in claims if using `expiresIn` option (jsonwebtoken rejects both). + */ +function signTestIdToken(claims: Record): string { + return jwt.sign(claims, privateKey, { + algorithm: 'RS256', + keyid: TEST_KID, + }); +} + +/** + * Create a valid test ID token with standard claims. + */ +function createValidIdToken(overrides: Partial> = {}, nonce?: string): string { + const now = Math.floor(Date.now() / 1000); + const claims = { + sub: 'entra-user-sub-12345', + email: 'testuser@example.com', + preferred_username: 'testuser', + given_name: 'Test', + family_name: 'User', + nonce: nonce ?? 'test-nonce', + aud: TEST_CLIENT_ID, + iss: `https://login.microsoftonline.com/${TEST_TENANT_ID}/v2.0`, + iat: now, + exp: now + 3600, + ...overrides, + }; + return signTestIdToken(claims); +} + +/** + * Integration Tests for the full Entra ID OAuth Flow + * + * Tests the complete authorization URL generation → callback → token exchange + * flow with mocked Entra ID endpoints. + * + * Validates: Requirements 2.1, 3.1, 7.1, 7.2, 7.3, 7.4, 9.4, 9.8 + */ +describe('Entra ID Auth Flow Integration Tests', () => { + let app: Express; + let databaseService: DatabaseService; + let entraIdService: EntraIdService; + let container: DIContainer; + let fetchSpy: ReturnType; + + beforeEach(async () => { + process.env.JWT_SECRET = 'test-secret-key-for-entra-id-integration'; // pragma: allowlist secret + process.env.ENTRA_ID_ENABLED = 'true'; + process.env.ENTRA_ID_TENANT_ID = TEST_TENANT_ID; + process.env.ENTRA_ID_CLIENT_ID = TEST_CLIENT_ID; + process.env.ENTRA_ID_CLIENT_SECRET = TEST_CLIENT_SECRET; // pragma: allowlist secret + process.env.ENTRA_ID_REDIRECT_URI = TEST_REDIRECT_URI; + + databaseService = new DatabaseService(':memory:'); + await databaseService.initialize(); + + const db = databaseService.getAdapter(); + const logger = new LoggerService(); + const auditLogger = new AuditLoggingService(db); + const jwtSecret = process.env.JWT_SECRET; + const authService = new AuthenticationService(db, jwtSecret, auditLogger, 4); + const userService = new UserService(db, authService); + const roleService = new RoleService(db); + + entraIdService = new EntraIdService( + db, + testEntraIdConfig, + authService, + userService, + roleService, + auditLogger, + logger, + ); + + container = new DIContainer(); + container.register('logger', logger); + + const configService = new ConfigService(); + container.register('config', configService); + + const { ExpertModeService } = await import('../../src/services/ExpertModeService'); + container.register('expertMode', new ExpertModeService()); + container.register('entraId', entraIdService); + + app = express(); + app.use(express.json()); + app.use('/api/auth/entra-id', createEntraIdAuthRouter(databaseService, container)); + app.use('/api/auth', createAuthRouter(databaseService, container)); + + // Mock global fetch for external Entra ID calls + fetchSpy = vi.spyOn(globalThis, 'fetch'); + }); + + afterEach(async () => { + vi.restoreAllMocks(); + await databaseService.close(); + delete process.env.ENTRA_ID_ENABLED; + delete process.env.ENTRA_ID_TENANT_ID; + delete process.env.ENTRA_ID_CLIENT_ID; + delete process.env.ENTRA_ID_CLIENT_SECRET; + delete process.env.ENTRA_ID_REDIRECT_URI; + }); + + describe('Full happy path: auth URL → callback → token exchange', () => { + it('should complete the full OAuth flow', async () => { + // Step 1: Get the authorization URL via /login endpoint + const loginResponse = await request(app) + .get('/api/auth/entra-id/login') + .expect(302); + + const redirectUrl = new URL(loginResponse.headers.location); + expect(redirectUrl.hostname).toBe('login.microsoftonline.com'); + expect(redirectUrl.pathname).toContain(TEST_TENANT_ID); + expect(redirectUrl.searchParams.get('response_type')).toBe('code'); + expect(redirectUrl.searchParams.get('client_id')).toBe(TEST_CLIENT_ID); + expect(redirectUrl.searchParams.get('code_challenge_method')).toBe('S256'); + + const state = redirectUrl.searchParams.get('state'); + const nonce = redirectUrl.searchParams.get('nonce'); + expect(state).toBeTruthy(); + expect(nonce).toBeTruthy(); + + // Step 2: Simulate callback from Entra ID + // We need to get the stored nonce from the DB to create a valid ID token + const stateEntry = await databaseService.getAdapter().queryOne<{ + nonce: string; + code_verifier: string; + }>( + `SELECT nonce, code_verifier FROM oauth_state_store WHERE state = ?`, + [state!], + ); + expect(stateEntry).not.toBeNull(); + + const validIdToken = createValidIdToken({ nonce: stateEntry!.nonce }, stateEntry!.nonce); + + // Mock the token endpoint + fetchSpy.mockImplementation(async (input: RequestInfo | URL) => { + const url = typeof input === 'string' ? input : input.toString(); + + if (url.includes('/oauth2/v2.0/token')) { + return new Response( + JSON.stringify({ + id_token: validIdToken, + access_token: 'mock-entra-access-token', + token_type: 'Bearer', + }), + { status: 200, headers: { 'Content-Type': 'application/json' } }, + ); + } + + if (url.includes('/discovery/v2.0/keys')) { + return new Response( + JSON.stringify({ keys: [TEST_JWK] }), + { status: 200, headers: { 'Content-Type': 'application/json' } }, + ); + } + + return new Response('Not found', { status: 404 }); + }); + + // Call the callback endpoint + const callbackResponse = await request(app) + .get('/api/auth/entra-id/callback') + .query({ code: 'mock-auth-code', state: state! }) + .expect(302); + + // Should redirect to frontend with an auth code + const frontendRedirect = new URL(callbackResponse.headers.location); + const authCode = frontendRedirect.searchParams.get('code'); + expect(authCode).toBeTruthy(); + expect(authCode!.length).toBeGreaterThan(0); + + // Step 3: Exchange the auth code for tokens + const tokenResponse = await request(app) + .post('/api/auth/entra-id/token') + .send({ code: authCode }) + .expect(200); + + expect(tokenResponse.body).toHaveProperty('token'); + expect(tokenResponse.body).toHaveProperty('refreshToken'); + expect(tokenResponse.body).toHaveProperty('user'); + expect(tokenResponse.body.user.username).toBe('testuser'); + expect(tokenResponse.body.user.email).toBe('testuser@example.com'); + + // Step 4: Verify the auth code cannot be reused (single-use) + const replayResponse = await request(app) + .post('/api/auth/entra-id/token') + .send({ code: authCode }) + .expect(400); + + expect(replayResponse.body.error.code).toBe('INVALID_AUTH_CODE'); + }); + }); + + describe('JWKS cache fallback on endpoint failure', () => { + it('should use cached JWKS keys when endpoint fails on second request', async () => { + // First: generate auth URL to get state + const loginRes = await request(app) + .get('/api/auth/entra-id/login') + .expect(302); + + const redirectUrl = new URL(loginRes.headers.location); + const state = redirectUrl.searchParams.get('state')!; + + const stateEntry = await databaseService.getAdapter().queryOne<{ + nonce: string; + code_verifier: string; + }>( + `SELECT nonce, code_verifier FROM oauth_state_store WHERE state = ?`, + [state], + ); + + const validIdToken = createValidIdToken({ nonce: stateEntry!.nonce }, stateEntry!.nonce); + + let jwksFetchCount = 0; + + fetchSpy.mockImplementation(async (input: RequestInfo | URL) => { + const url = typeof input === 'string' ? input : input.toString(); + + if (url.includes('/oauth2/v2.0/token')) { + return new Response( + JSON.stringify({ + id_token: validIdToken, + access_token: 'mock-access-token', + }), + { status: 200, headers: { 'Content-Type': 'application/json' } }, + ); + } + + if (url.includes('/discovery/v2.0/keys')) { + jwksFetchCount++; + if (jwksFetchCount === 1) { + // First call succeeds — populates the cache + return new Response( + JSON.stringify({ keys: [TEST_JWK] }), + { status: 200, headers: { 'Content-Type': 'application/json' } }, + ); + } + // Subsequent calls fail — should use cache + return new Response('Service unavailable', { status: 503 }); + } + + return new Response('Not found', { status: 404 }); + }); + + // First callback: should succeed and cache JWKS keys + const callbackRes1 = await request(app) + .get('/api/auth/entra-id/callback') + .query({ code: 'auth-code-1', state }) + .expect(302); + + const authCode1 = new URL(callbackRes1.headers.location).searchParams.get('code')!; + await request(app).post('/api/auth/entra-id/token').send({ code: authCode1 }).expect(200); + + // Now force cache to be stale by manipulating the service internals + // The jwksCache has a fetchedAt that we need to backdating. + // Since the cache TTL is 24h, the second request within the test will use + // the in-memory cache anyway. Let's verify via a second full flow. + + // Generate a new authorization URL for a second login + const loginRes2 = await request(app).get('/api/auth/entra-id/login').expect(302); + const state2 = new URL(loginRes2.headers.location).searchParams.get('state')!; + + const stateEntry2 = await databaseService.getAdapter().queryOne<{ + nonce: string; + }>( + `SELECT nonce FROM oauth_state_store WHERE state = ?`, + [state2], + ); + + const validIdToken2 = createValidIdToken( + { nonce: stateEntry2!.nonce, sub: 'returning-user-sub' }, + stateEntry2!.nonce, + ); + + // Update fetch mock to return the second token + fetchSpy.mockImplementation(async (input: RequestInfo | URL) => { + const url = typeof input === 'string' ? input : input.toString(); + if (url.includes('/oauth2/v2.0/token')) { + return new Response( + JSON.stringify({ id_token: validIdToken2, access_token: 'mock-access-2' }), + { status: 200, headers: { 'Content-Type': 'application/json' } }, + ); + } + if (url.includes('/discovery/v2.0/keys')) { + // JWKS endpoint fails completely + return new Response('Service unavailable', { status: 503 }); + } + return new Response('Not found', { status: 404 }); + }); + + // Force cache expiry by manipulating the internal cache timestamp + // eslint-disable-next-line @typescript-eslint/no-explicit-any + (entraIdService as any).jwksCache.fetchedAt = 0; + + // Second callback: JWKS endpoint fails but cache should serve + const callbackRes2 = await request(app) + .get('/api/auth/entra-id/callback') + .query({ code: 'auth-code-2', state: state2 }) + .expect(302); + + const authCode2 = new URL(callbackRes2.headers.location).searchParams.get('code')!; + const tokenRes2 = await request(app) + .post('/api/auth/entra-id/token') + .send({ code: authCode2 }) + .expect(200); + + expect(tokenRes2.body.user.email).toBe('testuser@example.com'); + }); + }); + + describe('Token exchange timeout behavior (>10s)', () => { + it('should return TOKEN_EXCHANGE_FAILED when token endpoint times out', async () => { + const loginRes = await request(app).get('/api/auth/entra-id/login').expect(302); + const state = new URL(loginRes.headers.location).searchParams.get('state')!; + + // Mock the token endpoint to abort (simulating a timeout via AbortError) + fetchSpy.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => { + const url = typeof input === 'string' ? input : input.toString(); + + if (url.includes('/oauth2/v2.0/token')) { + // Simulate AbortSignal.timeout(10000) firing + const error = new DOMException('The operation was aborted', 'AbortError'); + if (init?.signal) { + // Check if the signal is already aborted + if (init.signal.aborted) { + throw error; + } + } + throw error; + } + + return new Response('Not found', { status: 404 }); + }); + + const callbackRes = await request(app) + .get('/api/auth/entra-id/callback') + .query({ code: 'timeout-code', state }) + .expect(401); + + expect(callbackRes.body.error.code).toBe('TOKEN_EXCHANGE_FAILED'); + expect(callbackRes.body.error.message).toContain('unreachable'); + }); + }); + + describe('Database failure during provisioning (atomicity)', () => { + it('should reject with PROVISIONING_FAILED and leave no partial state', async () => { + const loginRes = await request(app).get('/api/auth/entra-id/login').expect(302); + const state = new URL(loginRes.headers.location).searchParams.get('state')!; + + const stateEntry = await databaseService.getAdapter().queryOne<{ nonce: string }>( + `SELECT nonce FROM oauth_state_store WHERE state = ?`, + [state], + ); + + const idToken = createValidIdToken({ nonce: stateEntry!.nonce }, stateEntry!.nonce); + + fetchSpy.mockImplementation(async (input: RequestInfo | URL) => { + const url = typeof input === 'string' ? input : input.toString(); + if (url.includes('/oauth2/v2.0/token')) { + return new Response( + JSON.stringify({ id_token: idToken, access_token: 'mock-access' }), + { status: 200, headers: { 'Content-Type': 'application/json' } }, + ); + } + if (url.includes('/discovery/v2.0/keys')) { + return new Response( + JSON.stringify({ keys: [TEST_JWK] }), + { status: 200, headers: { 'Content-Type': 'application/json' } }, + ); + } + return new Response('Not found', { status: 404 }); + }); + + // Spy on the UserService.createFederatedUser to throw a DB error + const createFederatedUserSpy = vi.spyOn( + entraIdService.userService, + 'createFederatedUser', + ); + createFederatedUserSpy.mockRejectedValueOnce(new Error('SQLITE_CONSTRAINT: UNIQUE')); + + const callbackRes = await request(app) + .get('/api/auth/entra-id/callback') + .query({ code: 'db-fail-code', state }) + .expect(500); + + expect(callbackRes.body.error.code).toBe('PROVISIONING_FAILED'); + + // Verify no user was partially created + const users = await databaseService.getAdapter().query<{ username: string }>( + `SELECT username FROM users WHERE email = 'testuser@example.com'`, + [], + ); + expect(users).toHaveLength(0); + + // Verify no federated identity was created + const identities = await databaseService.getAdapter().query<{ id: string }>( + `SELECT id FROM federated_identities WHERE subject = 'entra-user-sub-12345'`, + [], + ); + expect(identities).toHaveLength(0); + }); + }); + + describe('Audit logging verification', () => { + it('should record audit log entry after successful SSO login', async () => { + const loginRes = await request(app).get('/api/auth/entra-id/login').expect(302); + const state = new URL(loginRes.headers.location).searchParams.get('state')!; + + const stateEntry = await databaseService.getAdapter().queryOne<{ nonce: string }>( + `SELECT nonce FROM oauth_state_store WHERE state = ?`, + [state], + ); + + const idToken = createValidIdToken({ nonce: stateEntry!.nonce }, stateEntry!.nonce); + + fetchSpy.mockImplementation(async (input: RequestInfo | URL) => { + const url = typeof input === 'string' ? input : input.toString(); + if (url.includes('/oauth2/v2.0/token')) { + return new Response( + JSON.stringify({ id_token: idToken, access_token: 'mock-access' }), + { status: 200, headers: { 'Content-Type': 'application/json' } }, + ); + } + if (url.includes('/discovery/v2.0/keys')) { + return new Response( + JSON.stringify({ keys: [TEST_JWK] }), + { status: 200, headers: { 'Content-Type': 'application/json' } }, + ); + } + return new Response('Not found', { status: 404 }); + }); + + const callbackRes = await request(app) + .get('/api/auth/entra-id/callback') + .query({ code: 'audit-code', state }) + .expect(302); + + const authCode = new URL(callbackRes.headers.location).searchParams.get('code')!; + await request(app).post('/api/auth/entra-id/token').send({ code: authCode }).expect(200); + + // Verify audit log entry exists + const auditLogs = await databaseService.getAdapter().query<{ + eventType: string; + action: string; + details: string; + result: string; + }>( + `SELECT event_type AS "eventType", "action", details, result + FROM audit_logs + WHERE event_type = 'auth' AND "action" = 'login_success' + ORDER BY timestamp DESC LIMIT 1`, + [], + ); + + expect(auditLogs).toHaveLength(1); + expect(auditLogs[0].result).toBe('success'); + + const details = JSON.parse(auditLogs[0].details); + expect(details.username).toBe('testuser'); + expect(details.reason).toBe('method=entra-id'); + }); + }); + + describe('Federation-only account local login rejection', () => { + it('should reject local login with HTTP 401 for user with null password_hash', async () => { + // First: complete an SSO login to create a federation-only user + const loginRes = await request(app).get('/api/auth/entra-id/login').expect(302); + const state = new URL(loginRes.headers.location).searchParams.get('state')!; + + const stateEntry = await databaseService.getAdapter().queryOne<{ nonce: string }>( + `SELECT nonce FROM oauth_state_store WHERE state = ?`, + [state], + ); + + const idToken = createValidIdToken({ nonce: stateEntry!.nonce }, stateEntry!.nonce); + + fetchSpy.mockImplementation(async (input: RequestInfo | URL) => { + const url = typeof input === 'string' ? input : input.toString(); + if (url.includes('/oauth2/v2.0/token')) { + return new Response( + JSON.stringify({ id_token: idToken, access_token: 'mock-access' }), + { status: 200, headers: { 'Content-Type': 'application/json' } }, + ); + } + if (url.includes('/discovery/v2.0/keys')) { + return new Response( + JSON.stringify({ keys: [TEST_JWK] }), + { status: 200, headers: { 'Content-Type': 'application/json' } }, + ); + } + return new Response('Not found', { status: 404 }); + }); + + const callbackRes = await request(app) + .get('/api/auth/entra-id/callback') + .query({ code: 'fed-only-code', state }) + .expect(302); + + const authCode = new URL(callbackRes.headers.location).searchParams.get('code')!; + await request(app).post('/api/auth/entra-id/token').send({ code: authCode }).expect(200); + + // Verify user exists and has null password_hash + const user = await databaseService.getAdapter().queryOne<{ + passwordHash: string | null; + }>( + `SELECT password_hash AS "passwordHash" FROM users WHERE username = 'testuser'`, + [], + ); + expect(user).not.toBeNull(); + expect(user!.passwordHash).toBeNull(); + + // Attempt local login with this federation-only user + const localLoginRes = await request(app) + .post('/api/auth/login') + .send({ username: 'testuser', password: 'AnyPassword123!' }) + .expect(401); + + expect(localLoginRes.body.error).toBeDefined(); + }); + }); + + describe('Coexistence: local auth continues working when Entra ID enabled', () => { + it('should allow local user registration and login while Entra ID is enabled', async () => { + // Verify the providers endpoint shows both + const providersRes = await request(app) + .get('/api/auth/providers') + .expect(200); + + expect(providersRes.body.local).toBe(true); + expect(providersRes.body.entraId).toBeDefined(); + expect(providersRes.body.entraId.enabled).toBe(true); + expect(providersRes.body.entraId.name).toBe('Microsoft Entra ID'); + + // Enable self-registration for the test + await databaseService.getAdapter().execute( + `INSERT INTO config (key, value, updated_at) + VALUES ('allow_self_registration', 'true', datetime('now')) + ON CONFLICT(key) DO UPDATE SET value = 'true'`, + [], + ); + + // Register a local user + const registerRes = await request(app) + .post('/api/auth/register') + .send({ + username: 'localuser', + email: 'localuser@example.com', + password: 'SecurePass123!', + firstName: 'Local', + lastName: 'User', + }) + .expect(201); + + expect(registerRes.body.user.username).toBe('localuser'); + + // Login with local credentials + const localLoginRes = await request(app) + .post('/api/auth/login') + .send({ username: 'localuser', password: 'SecurePass123!' }) + .expect(200); + + expect(localLoginRes.body).toHaveProperty('token'); + expect(localLoginRes.body).toHaveProperty('refreshToken'); + expect(localLoginRes.body.user.username).toBe('localuser'); + + // Simultaneously, Entra ID endpoints are available + const entraLoginRes = await request(app) + .get('/api/auth/entra-id/login') + .expect(302); + + expect(entraLoginRes.headers.location).toContain('login.microsoftonline.com'); + }); + }); +}); diff --git a/backend/test/properties/EntraIdAuthCode.property.test.ts b/backend/test/properties/EntraIdAuthCode.property.test.ts new file mode 100644 index 00000000..e512e715 --- /dev/null +++ b/backend/test/properties/EntraIdAuthCode.property.test.ts @@ -0,0 +1,377 @@ +/** + * Property-Based Tests for EntraIdService — Authorization Code Single-Use and TTL (Property 16) + * + * **Validates: Requirements 6.2, 6.3, 6.4** + * + * Tests the correctness property from the design document: + * - Property 16: Authorization code single-use and TTL + * + * For any successfully generated auth code, the code SHALL have expires_at ≤ 60 + * seconds from creation. After a successful exchange, any subsequent exchange + * attempt with the same code SHALL be rejected. After the code expires, exchange + * SHALL also be rejected. + */ + +// Feature: azure-entra-id-auth, Property 16: Authorization code single-use and TTL + +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import * as fc from 'fast-check'; +import { randomUUID } from 'crypto'; + +import { SQLiteAdapter } from '../../src/database/SQLiteAdapter'; +import type { DatabaseAdapter } from '../../src/database/DatabaseAdapter'; +import { initializeTestSchema } from '../helpers/schema'; +import { + EntraIdService, + EntraIdError, + ENTRA_ID_ERROR_CODES, +} from '../../src/services/EntraIdService'; +import type { EntraIdConfig } from '../../src/config/schema'; +import type { AuthenticationService } from '../../src/services/AuthenticationService'; +import type { UserService } from '../../src/services/UserService'; +import type { RoleService } from '../../src/services/RoleService'; +import type { AuditLoggingService } from '../../src/services/AuditLoggingService'; +import type { LoggerService } from '../../src/services/LoggerService'; + +// --- Mock Factories --- + +function createMockConfig(): EntraIdConfig { + return { + enabled: true, + tenantId: 'test-tenant-id-000', + clientId: 'test-client-id-111', + clientSecret: 'test-client-secret-222', // pragma: allowlist secret + redirectUri: 'http://localhost:3000/api/auth/entra-id/callback', + scopes: ['openid', 'profile', 'email'], + groupMapping: null, + jwksCacheTtlMs: 86400000, + }; +} + +function createMockLogger(): LoggerService { + return { + info: vi.fn(), + warn: vi.fn(), + error: vi.fn(), + debug: vi.fn(), + shouldLog: vi.fn().mockReturnValue(true), + formatMessage: vi.fn().mockReturnValue(''), + getLevel: vi.fn().mockReturnValue('info'), + setLogBuffer: vi.fn(), + getLogBuffer: vi.fn().mockReturnValue(null), + } as unknown as LoggerService; +} + +const TEST_USER_ID = 'mock-user-id-001'; + +const mockUser = { + id: TEST_USER_ID, + username: 'testuser', + email: 'testuser@example.com', + passwordHash: '', + firstName: 'Test', + lastName: 'User', + isActive: 1, + isAdmin: 0, + createdAt: new Date().toISOString(), + updatedAt: new Date().toISOString(), + lastLoginAt: null, +}; + +// --- Test Suite --- + +describe('EntraIdService — Property 16: Authorization code single-use and TTL', () => { + let db: DatabaseAdapter; + let service: EntraIdService; + + beforeEach(async () => { + vi.restoreAllMocks(); + + db = new SQLiteAdapter(':memory:'); + await db.initialize(); + await initializeTestSchema(db); + + // Insert the test user + await db.execute( + `INSERT INTO users (id, username, email, password_hash, first_name, last_name, is_active, is_admin, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, + [ + mockUser.id, mockUser.username, mockUser.email, '', + mockUser.firstName, mockUser.lastName, mockUser.isActive, mockUser.isAdmin, + mockUser.createdAt, mockUser.updatedAt, + ], + ); + + const mockAuthService = { + generateToken: vi.fn().mockResolvedValue('mock-access-token'), + generateRefreshToken: vi.fn().mockResolvedValue('mock-refresh-token'), + } as unknown as AuthenticationService; + + const mockUserService = { + findByFederatedIdentity: vi.fn().mockResolvedValue(null), + findByEmail: vi.fn().mockResolvedValue(null), + createFederatedUser: vi.fn().mockResolvedValue(mockUser), + getUserById: vi.fn().mockResolvedValue(mockUser), + toUserDTO: vi.fn().mockReturnValue({ id: mockUser.id, username: mockUser.username }), + getUserRoles: vi.fn().mockResolvedValue([]), + } as unknown as UserService; + + const mockRoleService = { + listRoles: vi.fn().mockResolvedValue({ items: [], total: 0 }), + } as unknown as RoleService; + + const mockAuditLogger = { + logAuthenticationAttempt: vi.fn().mockResolvedValue(undefined), + } as unknown as AuditLoggingService; + + service = new EntraIdService( + db, + createMockConfig(), + mockAuthService, + mockUserService, + mockRoleService, + mockAuditLogger, + createMockLogger(), + ); + }); + + afterEach(async () => { + await db.close(); + }); + + /** + * Test 1: Auth code TTL is always ≤ 60 seconds + * + * For any successfully generated auth code, expires_at - created_at ≤ 60000ms. + */ + describe('Auth code TTL ≤ 60 seconds', () => { + it('generated auth codes always have expires_at ≤ 60s from created_at', async () => { + await fc.assert( + fc.asyncProperty( + fc.constant(null), + async () => { + const code = randomUUID(); + const now = new Date(); + const createdAt = now.toISOString(); + const expiresAt = new Date(now.getTime() + 60 * 1000).toISOString(); + + await db.execute( + `INSERT INTO oauth_auth_codes (code, access_token, refresh_token, user_id, id_token, auth_method, created_at, expires_at, exchanged) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)`, + [code, 'at', 'rt', TEST_USER_ID, 'idt', 'entra-id', createdAt, expiresAt], + ); + + const row = await db.queryOne<{ createdAt: string; expiresAt: string }>( + `SELECT created_at AS "createdAt", expires_at AS "expiresAt" + FROM oauth_auth_codes WHERE code = ?`, + [code], + ); + + expect(row).not.toBeNull(); + const created = new Date(row!.createdAt).getTime(); + const expires = new Date(row!.expiresAt).getTime(); + const ttlMs = expires - created; + + expect(ttlMs).toBeLessThanOrEqual(60 * 1000); + expect(ttlMs).toBeGreaterThan(0); + }, + ), + { numRuns: 100 }, + ); + }); + + it('exchangeAuthCode succeeds when TTL has not elapsed', async () => { + await fc.assert( + fc.asyncProperty( + fc.integer({ min: 1, max: 59 }), + async (secondsRemaining) => { + const code = randomUUID(); + const now = new Date(); + const createdAt = new Date(now.getTime() - (60 - secondsRemaining) * 1000).toISOString(); + const expiresAt = new Date(now.getTime() + secondsRemaining * 1000).toISOString(); + + await db.execute( + `INSERT INTO oauth_auth_codes (code, access_token, refresh_token, user_id, id_token, auth_method, created_at, expires_at, exchanged) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)`, + [code, 'access-tok', 'refresh-tok', TEST_USER_ID, 'id-tok', 'entra-id', createdAt, expiresAt], + ); + + const result = await service.exchangeAuthCode(code); + expect(result.accessToken).toBe('access-tok'); + expect(result.refreshToken).toBe('refresh-tok'); + expect(result.user).toBeDefined(); + }, + ), + { numRuns: 100 }, + ); + }); + }); + + /** + * Test 2: After successful exchange, second exchange with same code throws INVALID_AUTH_CODE + * + * Single-use guarantee: once a code has been exchanged, any subsequent attempt + * SHALL be rejected. + */ + describe('Single-use enforcement', () => { + it('rejects second exchange attempt after successful first exchange', async () => { + await fc.assert( + fc.asyncProperty( + fc.constant(null), + async () => { + const code = randomUUID(); + const now = new Date(); + const createdAt = now.toISOString(); + const expiresAt = new Date(now.getTime() + 60 * 1000).toISOString(); + + await db.execute( + `INSERT INTO oauth_auth_codes (code, access_token, refresh_token, user_id, id_token, auth_method, created_at, expires_at, exchanged) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)`, + [code, 'at', 'rt', TEST_USER_ID, 'idt', 'entra-id', createdAt, expiresAt], + ); + + // First exchange succeeds + const result = await service.exchangeAuthCode(code); + expect(result.accessToken).toBe('at'); + + // Second exchange must fail + try { + await service.exchangeAuthCode(code); + expect.fail('Second exchange should have thrown EntraIdError'); + } catch (err) { + expect(err).toBeInstanceOf(EntraIdError); + expect((err as EntraIdError).code).toBe(ENTRA_ID_ERROR_CODES.INVALID_AUTH_CODE); + } + }, + ), + { numRuns: 100 }, + ); + }); + + it('rejects all subsequent exchanges (N > 1) after first successful exchange', async () => { + await fc.assert( + fc.asyncProperty( + fc.integer({ min: 2, max: 5 }), + async (attempts) => { + const code = randomUUID(); + const now = new Date(); + const createdAt = now.toISOString(); + const expiresAt = new Date(now.getTime() + 60 * 1000).toISOString(); + + await db.execute( + `INSERT INTO oauth_auth_codes (code, access_token, refresh_token, user_id, id_token, auth_method, created_at, expires_at, exchanged) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)`, + [code, 'at', 'rt', TEST_USER_ID, 'idt', 'entra-id', createdAt, expiresAt], + ); + + // First exchange succeeds + await service.exchangeAuthCode(code); + + // All subsequent attempts fail + for (let i = 0; i < attempts; i++) { + try { + await service.exchangeAuthCode(code); + expect.fail(`Exchange attempt ${i + 2} should have thrown`); + } catch (err) { + expect(err).toBeInstanceOf(EntraIdError); + expect((err as EntraIdError).code).toBe(ENTRA_ID_ERROR_CODES.INVALID_AUTH_CODE); + } + } + }, + ), + { numRuns: 100 }, + ); + }); + }); + + /** + * Test 3: After code expires, exchange throws INVALID_AUTH_CODE + * + * Expired codes SHALL not be exchangeable regardless of whether they were + * previously used. + */ + describe('Expired code rejection', () => { + it('rejects exchange of expired codes', async () => { + await fc.assert( + fc.asyncProperty( + fc.integer({ min: 1, max: 3600 }), + async (secondsExpiredAgo) => { + const code = randomUUID(); + const now = new Date(); + const expiresAt = new Date(now.getTime() - secondsExpiredAgo * 1000).toISOString(); + const createdAt = new Date(now.getTime() - secondsExpiredAgo * 1000 - 60000).toISOString(); + + await db.execute( + `INSERT INTO oauth_auth_codes (code, access_token, refresh_token, user_id, id_token, auth_method, created_at, expires_at, exchanged) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)`, + [code, 'at', 'rt', TEST_USER_ID, 'idt', 'entra-id', createdAt, expiresAt], + ); + + try { + await service.exchangeAuthCode(code); + expect.fail('Expired code exchange should have thrown EntraIdError'); + } catch (err) { + expect(err).toBeInstanceOf(EntraIdError); + expect((err as EntraIdError).code).toBe(ENTRA_ID_ERROR_CODES.INVALID_AUTH_CODE); + } + }, + ), + { numRuns: 100 }, + ); + }); + + it('rejects expired codes even when never previously exchanged', async () => { + await fc.assert( + fc.asyncProperty( + fc.integer({ min: 1, max: 300 }), + async (secondsExpired) => { + const code = randomUUID(); + const now = new Date(); + const expiresAt = new Date(now.getTime() - secondsExpired * 1000).toISOString(); + const createdAt = new Date(now.getTime() - secondsExpired * 1000 - 60000).toISOString(); + + await db.execute( + `INSERT INTO oauth_auth_codes (code, access_token, refresh_token, user_id, id_token, auth_method, created_at, expires_at, exchanged) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0)`, + [code, 'at', 'rt', TEST_USER_ID, 'idt', 'entra-id', createdAt, expiresAt], + ); + + try { + await service.exchangeAuthCode(code); + expect.fail('Should have thrown for expired code'); + } catch (err) { + expect(err).toBeInstanceOf(EntraIdError); + expect((err as EntraIdError).code).toBe(ENTRA_ID_ERROR_CODES.INVALID_AUTH_CODE); + } + }, + ), + { numRuns: 100 }, + ); + }); + }); + + /** + * Test 4: Code that was never stored throws INVALID_AUTH_CODE + * + * Any code not present in the database SHALL be rejected. + */ + describe('Non-existent code rejection', () => { + it('rejects codes that were never stored', async () => { + await fc.assert( + fc.asyncProperty( + fc.stringMatching(/^[a-f0-9]{16,64}$/), + async (randomCode) => { + try { + await service.exchangeAuthCode(randomCode); + expect.fail('Non-existent code should have thrown EntraIdError'); + } catch (err) { + expect(err).toBeInstanceOf(EntraIdError); + expect((err as EntraIdError).code).toBe(ENTRA_ID_ERROR_CODES.INVALID_AUTH_CODE); + } + }, + ), + { numRuns: 100 }, + ); + }); + }); +}); diff --git a/backend/test/properties/EntraIdCallback.property.test.ts b/backend/test/properties/EntraIdCallback.property.test.ts new file mode 100644 index 00000000..63faadd0 --- /dev/null +++ b/backend/test/properties/EntraIdCallback.property.test.ts @@ -0,0 +1,637 @@ +/** + * Property-Based Tests for EntraIdService — Callback Validation (Properties 7–11) + * + * **Validates: Requirements 3.2, 3.3, 3.4, 3.5, 3.6, 3.10, 9.1, 9.2** + * + * Tests the five correctness properties from the design document: + * - Property 7: State mismatch rejects callback + * - Property 8: ID token signature validation + * - Property 9: Nonce mismatch rejects token + * - Property 10: Audience and issuer validation + * - Property 11: State entries deleted after callback processing + */ + +import { describe, it, expect, beforeEach, vi } from 'vitest'; +import * as fc from 'fast-check'; +import { generateKeyPairSync, createPublicKey } from 'crypto'; +import jwt from 'jsonwebtoken'; + +import { + EntraIdService, + EntraIdError, + ENTRA_ID_ERROR_CODES, +} from '../../src/services/EntraIdService'; +import type { DatabaseAdapter } from '../../src/database/DatabaseAdapter'; +import type { EntraIdConfig } from '../../src/config/schema'; +import type { AuthenticationService } from '../../src/services/AuthenticationService'; +import type { UserService } from '../../src/services/UserService'; +import type { RoleService } from '../../src/services/RoleService'; +import type { AuditLoggingService } from '../../src/services/AuditLoggingService'; +import type { LoggerService } from '../../src/services/LoggerService'; + +// --- Test RSA Key Pairs --- + +function generateTestKeyPair(): { privateKey: string; publicKey: string; kid: string } { + const { privateKey, publicKey } = generateKeyPairSync('rsa', { + modulusLength: 2048, + publicKeyEncoding: { type: 'spki', format: 'pem' }, + privateKeyEncoding: { type: 'pkcs8', format: 'pem' }, + }); + const kid = `test-kid-${Math.random().toString(36).slice(2, 10)}`; + return { privateKey, publicKey, kid }; +} + +function pemToJwkComponents(pem: string): { n: string; e: string } { + const keyObject = createPublicKey(pem); + const jwk = keyObject.export({ format: 'jwk' }) as { n: string; e: string }; + return { n: jwk.n, e: jwk.e }; +} + +// --- Mock Factories --- + +function createMockDb(): DatabaseAdapter { + return { + query: vi.fn().mockResolvedValue([]), + queryOne: vi.fn().mockResolvedValue(null), + execute: vi.fn().mockResolvedValue({ changes: 0 }), + beginTransaction: vi.fn().mockResolvedValue(undefined), + commit: vi.fn().mockResolvedValue(undefined), + rollback: vi.fn().mockResolvedValue(undefined), + withTransaction: vi.fn(), + initialize: vi.fn().mockResolvedValue(undefined), + close: vi.fn().mockResolvedValue(undefined), + isConnected: vi.fn().mockReturnValue(true), + getDialect: vi.fn().mockReturnValue('sqlite' as const), + }; +} + +function createMockConfig(): EntraIdConfig { + return { + enabled: true, + tenantId: 'test-tenant-id-000', + clientId: 'test-client-id-111', + clientSecret: 'test-client-secret-222', // pragma: allowlist secret + redirectUri: 'http://localhost:3000/api/auth/entra-id/callback', + scopes: ['openid', 'profile', 'email'], + groupMapping: null, + jwksCacheTtlMs: 86400000, + }; +} + +function createMockLogger(): LoggerService { + return { + info: vi.fn(), + warn: vi.fn(), + error: vi.fn(), + debug: vi.fn(), + shouldLog: vi.fn().mockReturnValue(true), + formatMessage: vi.fn().mockReturnValue(''), + getLevel: vi.fn().mockReturnValue('info'), + setLogBuffer: vi.fn(), + getLogBuffer: vi.fn().mockReturnValue(null), + } as unknown as LoggerService; +} + +// Pre-generate key pairs (expensive, do once) +const primaryKey = generateTestKeyPair(); +const primaryJwk = pemToJwkComponents(primaryKey.publicKey); + +function buildIdToken( + config: EntraIdConfig, + nonce: string, + overrides: Record = {}, + signingKey: string = primaryKey.privateKey, + kid: string = primaryKey.kid, +): string { + const now = Math.floor(Date.now() / 1000); + const payload = { + sub: 'test-subject-001', + email: 'user@example.com', + preferred_username: 'testuser', + given_name: 'Test', + family_name: 'User', + nonce, + aud: config.clientId, + iss: `https://login.microsoftonline.com/${config.tenantId}/v2.0`, + exp: now + 3600, + iat: now, + ...overrides, + }; + + return jwt.sign(payload, signingKey, { + algorithm: 'RS256', + header: { alg: 'RS256', kid, typ: 'JWT' }, + }); +} + +function mockFetchForToken(idToken: string): void { + const jwksResponse = { + keys: [{ + kty: 'RSA', + use: 'sig', + kid: primaryKey.kid, + n: primaryJwk.n, + e: primaryJwk.e, + }], + }; + + vi.stubGlobal('fetch', vi.fn().mockImplementation((url: string) => { + if (url.includes('/oauth2/v2.0/token')) { + return Promise.resolve({ + ok: true, + json: () => Promise.resolve({ + id_token: idToken, + access_token: 'mock-access-token', + }), + }); + } + if (url.includes('/discovery/v2.0/keys')) { + return Promise.resolve({ + ok: true, + json: () => Promise.resolve(jwksResponse), + }); + } + return Promise.reject(new Error(`Unexpected fetch: ${url}`)); + })); +} + +function mockFetchThatTracksTokenCalls(): { fetchMock: ReturnType; getTokenCalls: () => unknown[][] } { + const fetchMock = vi.fn().mockImplementation((url: string) => { + if (url.includes('/oauth2/v2.0/token')) { + // Return a valid-looking response to not throw before we check + return Promise.resolve({ + ok: true, + json: () => Promise.resolve({ id_token: 'x', access_token: 'y' }), + }); + } + if (url.includes('/discovery/v2.0/keys')) { + return Promise.resolve({ + ok: true, + json: () => Promise.resolve({ keys: [] }), + }); + } + return Promise.reject(new Error(`Unexpected fetch: ${url}`)); + }); + vi.stubGlobal('fetch', fetchMock); + + return { + fetchMock, + getTokenCalls: () => fetchMock.mock.calls.filter( + (call: unknown[]) => String(call[0]).includes('/oauth2/v2.0/token'), + ), + }; +} + +// --- Arbitraries --- +const hexStringArb = fc.stringMatching(/^[a-f0-9]{16,64}$/); +const codeArb = fc.stringMatching(/^[a-f0-9]{8,32}$/); + +describe('EntraIdService — Callback Validation Properties', () => { + let db: DatabaseAdapter; + let config: EntraIdConfig; + let logger: LoggerService; + let service: EntraIdService; + + const mockUser = { + id: 'mock-user-id-001', + username: 'testuser', + email: 'testuser@example.com', + passwordHash: '', + firstName: 'Test', + lastName: 'User', + isActive: 1, + isAdmin: 0, + createdAt: new Date().toISOString(), + updatedAt: new Date().toISOString(), + lastLoginAt: null, + }; + + beforeEach(() => { + vi.restoreAllMocks(); + db = createMockDb(); + config = createMockConfig(); + logger = createMockLogger(); + + const mockAuthService = { + generateToken: vi.fn().mockResolvedValue('mock-access-token'), + generateRefreshToken: vi.fn().mockResolvedValue('mock-refresh-token'), + } as unknown as AuthenticationService; + + const mockUserService = { + findByFederatedIdentity: vi.fn().mockResolvedValue(null), + findByEmail: vi.fn().mockResolvedValue(null), + createFederatedUser: vi.fn().mockResolvedValue(mockUser), + getUserById: vi.fn().mockResolvedValue(mockUser), + toUserDTO: vi.fn().mockReturnValue({ id: mockUser.id, username: mockUser.username }), + getUserRoles: vi.fn().mockResolvedValue([]), + } as unknown as UserService; + + const mockRoleService = { + listRoles: vi.fn().mockResolvedValue({ items: [], total: 0 }), + } as unknown as RoleService; + + const mockAuditLogger = { + logAuthenticationAttempt: vi.fn().mockResolvedValue(undefined), + } as unknown as AuditLoggingService; + + service = new EntraIdService( + db, + config, + mockAuthService, + mockUserService, + mockRoleService, + mockAuditLogger, + logger, + ); + }); + + // Feature: azure-entra-id-auth, Property 7: State mismatch rejects callback + /** + * Property 7: State mismatch rejects callback + * + * **Validates: Requirements 3.2, 3.6, 9.1** + * + * For any callback request where the state query parameter does not exactly + * match the stored state value (including missing, empty, or expired state), + * the service SHALL reject the request with INVALID_STATE without contacting + * the token endpoint. + */ + describe('Property 7: State mismatch rejects callback', () => { + it('rejects with INVALID_STATE when state is not found in store', async () => { + await fc.assert( + fc.asyncProperty( + hexStringArb, + codeArb, + async (state, code) => { + (db.queryOne as ReturnType).mockResolvedValue(null); + const { getTokenCalls } = mockFetchThatTracksTokenCalls(); + + try { + await service.handleCallback(code, state); + expect.fail('Should have thrown EntraIdError'); + } catch (err) { + expect(err).toBeInstanceOf(EntraIdError); + expect((err as EntraIdError).code).toBe(ENTRA_ID_ERROR_CODES.INVALID_STATE); + } + + // Token endpoint must NOT have been called + expect(getTokenCalls()).toHaveLength(0); + }, + ), + { numRuns: 100 }, + ); + }); + + it('rejects with INVALID_STATE when state entry is expired', async () => { + await fc.assert( + fc.asyncProperty( + hexStringArb, + codeArb, + fc.integer({ min: 1, max: 60 }), + async (state, code, minutesAgo) => { + const now = new Date(); + const expiredAt = new Date(now.getTime() - minutesAgo * 60 * 1000); + + (db.queryOne as ReturnType).mockResolvedValue({ + state, + nonce: 'test-nonce', + code_verifier: 'test-verifier-value-that-is-long-enough', + created_at: new Date(expiredAt.getTime() - 10 * 60 * 1000).toISOString(), + expires_at: expiredAt.toISOString(), + }); + + const { getTokenCalls } = mockFetchThatTracksTokenCalls(); + + try { + await service.handleCallback(code, state); + expect.fail('Should have thrown EntraIdError'); + } catch (err) { + expect(err).toBeInstanceOf(EntraIdError); + expect((err as EntraIdError).code).toBe(ENTRA_ID_ERROR_CODES.INVALID_STATE); + } + + // Token endpoint must NOT have been called + expect(getTokenCalls()).toHaveLength(0); + }, + ), + { numRuns: 100 }, + ); + }); + }); + + // Feature: azure-entra-id-auth, Property 8: ID token signature validation + /** + * Property 8: ID token signature validation + * + * **Validates: Requirements 3.3** + * + * For any JWT signed with a key present in the JWKS key set, signature + * validation SHALL pass. For any JWT signed with a key NOT in the JWKS key + * set, signature validation SHALL fail with INVALID_ID_TOKEN. + */ + describe('Property 8: ID token signature validation', () => { + const storedNonce = 'stored-nonce-value-for-sig-test'; + + function setupValidStateEntry(): void { + const future = new Date(Date.now() + 5 * 60 * 1000).toISOString(); + (db.queryOne as ReturnType).mockResolvedValue({ + state: 'valid-state', + nonce: storedNonce, + code_verifier: 'valid-code-verifier-value-here-long', + created_at: new Date().toISOString(), + expires_at: future, + }); + } + + it('accepts tokens signed with a key present in JWKS', async () => { + await fc.assert( + fc.asyncProperty( + codeArb, + async (code) => { + setupValidStateEntry(); + const idToken = buildIdToken(config, storedNonce); + mockFetchForToken(idToken); + + const result = await service.handleCallback(code, 'valid-state'); + expect(result.userId).toBe('mock-user-id-001'); + expect(result.authMethod).toBe('entra-id'); + expect(result.code).toBeDefined(); + }, + ), + { numRuns: 100 }, + ); + }); + + it('rejects tokens signed with a key NOT in JWKS', async () => { + await fc.assert( + fc.asyncProperty( + codeArb, + async (code) => { + setupValidStateEntry(); + + // Sign with a different key not in JWKS + const wrongKey = generateTestKeyPair(); + const idToken = buildIdToken( + config, + storedNonce, + {}, + wrongKey.privateKey, + wrongKey.kid, + ); + mockFetchForToken(idToken); + + try { + await service.handleCallback(code, 'valid-state'); + expect.fail('Should have thrown EntraIdError'); + } catch (err) { + expect(err).toBeInstanceOf(EntraIdError); + expect((err as EntraIdError).code).toBe(ENTRA_ID_ERROR_CODES.INVALID_ID_TOKEN); + } + }, + ), + { numRuns: 100 }, + ); + }); + }); + + // Feature: azure-entra-id-auth, Property 9: Nonce mismatch rejects token + /** + * Property 9: Nonce mismatch rejects token + * + * **Validates: Requirements 3.4, 9.2** + * + * For any ID token where the nonce claim does not match the stored nonce + * value, the service SHALL reject with INVALID_ID_TOKEN. + */ + describe('Property 9: Nonce mismatch rejects token', () => { + const noncePairArb = fc + .tuple( + fc.stringMatching(/^[a-f0-9]{16,64}$/), + fc.stringMatching(/^[a-f0-9]{16,64}$/), + ) + .filter(([a, b]) => a !== b); + + it('rejects when token nonce does not match stored nonce', async () => { + await fc.assert( + fc.asyncProperty( + noncePairArb, + codeArb, + async ([storedNonce, tokenNonce], code) => { + const future = new Date(Date.now() + 5 * 60 * 1000).toISOString(); + (db.queryOne as ReturnType).mockResolvedValue({ + state: 'valid-state', + nonce: storedNonce, + code_verifier: 'valid-code-verifier-value-here-long', + created_at: new Date().toISOString(), + expires_at: future, + }); + + // Valid signature but wrong nonce in token + const idToken = buildIdToken(config, tokenNonce); + mockFetchForToken(idToken); + + try { + await service.handleCallback(code, 'valid-state'); + expect.fail('Should have thrown EntraIdError'); + } catch (err) { + expect(err).toBeInstanceOf(EntraIdError); + expect((err as EntraIdError).code).toBe(ENTRA_ID_ERROR_CODES.INVALID_ID_TOKEN); + } + }, + ), + { numRuns: 100 }, + ); + }); + }); + + // Feature: azure-entra-id-auth, Property 10: Audience and issuer validation + /** + * Property 10: Audience and issuer validation + * + * **Validates: Requirements 3.5** + * + * For any ID token where aud ≠ clientId OR iss ≠ expected issuer URL, the + * service SHALL reject with INVALID_ID_TOKEN. + */ + describe('Property 10: Audience and issuer validation', () => { + const storedNonce = 'stored-nonce-for-aud-iss-test'; + + function setupValidState(): void { + const future = new Date(Date.now() + 5 * 60 * 1000).toISOString(); + (db.queryOne as ReturnType).mockResolvedValue({ + state: 'valid-state', + nonce: storedNonce, + code_verifier: 'valid-code-verifier-value-here-long', + created_at: new Date().toISOString(), + expires_at: future, + }); + } + + const wrongAudienceArb = fc + .stringMatching(/^[a-z0-9-]{8,40}$/) + .filter((s) => s !== 'test-client-id-111'); + + const wrongTenantArb = fc + .stringMatching(/^[a-z0-9-]{8,40}$/) + .filter((s) => s !== 'test-tenant-id-000'); + + it('rejects when audience does not match configured clientId', async () => { + await fc.assert( + fc.asyncProperty( + wrongAudienceArb, + codeArb, + async (wrongAud, code) => { + setupValidState(); + const idToken = buildIdToken(config, storedNonce, { aud: wrongAud }); + mockFetchForToken(idToken); + + try { + await service.handleCallback(code, 'valid-state'); + expect.fail('Should have thrown EntraIdError'); + } catch (err) { + expect(err).toBeInstanceOf(EntraIdError); + expect((err as EntraIdError).code).toBe(ENTRA_ID_ERROR_CODES.INVALID_ID_TOKEN); + } + }, + ), + { numRuns: 100 }, + ); + }); + + it('rejects when issuer does not match expected tenant URL', async () => { + await fc.assert( + fc.asyncProperty( + wrongTenantArb, + codeArb, + async (wrongTenant, code) => { + setupValidState(); + const wrongIss = `https://login.microsoftonline.com/${wrongTenant}/v2.0`; + const idToken = buildIdToken(config, storedNonce, { iss: wrongIss }); + mockFetchForToken(idToken); + + try { + await service.handleCallback(code, 'valid-state'); + expect.fail('Should have thrown EntraIdError'); + } catch (err) { + expect(err).toBeInstanceOf(EntraIdError); + expect((err as EntraIdError).code).toBe(ENTRA_ID_ERROR_CODES.INVALID_ID_TOKEN); + } + }, + ), + { numRuns: 100 }, + ); + }); + }); + + // Feature: azure-entra-id-auth, Property 11: State entries deleted after callback processing + /** + * Property 11: State entries deleted after callback processing + * + * **Validates: Requirements 3.10** + * + * For any callback execution (whether successful or failed), the + * oauth_state_store entry SHALL be deleted. + */ + describe('Property 11: State entries deleted after callback processing', () => { + const storedNonce = 'stored-nonce-for-deletion-test'; + + function assertStateDeleted(state: string): void { + const executeCalls = (db.execute as ReturnType).mock.calls; + const deleteCalls = executeCalls.filter( + (call: unknown[]) => String(call[0]).includes('DELETE FROM oauth_state_store'), + ); + expect(deleteCalls.length).toBeGreaterThanOrEqual(1); + const stateDeleteCall = deleteCalls.find( + (call: unknown[]) => (call[1] as unknown[]).includes(state), + ); + expect(stateDeleteCall).toBeDefined(); + } + + it('deletes state entry on successful callback', async () => { + await fc.assert( + fc.asyncProperty( + hexStringArb, + codeArb, + async (state, code) => { + const future = new Date(Date.now() + 5 * 60 * 1000).toISOString(); + (db.queryOne as ReturnType).mockResolvedValue({ + state, + nonce: storedNonce, + code_verifier: 'valid-code-verifier-value-here-long', + created_at: new Date().toISOString(), + expires_at: future, + }); + + const idToken = buildIdToken(config, storedNonce); + mockFetchForToken(idToken); + + await service.handleCallback(code, state); + assertStateDeleted(state); + }, + ), + { numRuns: 100 }, + ); + }); + + it('deletes state entry even when state is not found (failed callback)', async () => { + await fc.assert( + fc.asyncProperty( + hexStringArb, + codeArb, + async (state, code) => { + (db.queryOne as ReturnType).mockResolvedValue(null); + mockFetchThatTracksTokenCalls(); + + try { + await service.handleCallback(code, state); + } catch { + // Expected INVALID_STATE + } + + assertStateDeleted(state); + }, + ), + { numRuns: 100 }, + ); + }); + + it('deletes state entry when token validation fails', async () => { + await fc.assert( + fc.asyncProperty( + hexStringArb, + codeArb, + async (state, code) => { + const future = new Date(Date.now() + 5 * 60 * 1000).toISOString(); + (db.queryOne as ReturnType).mockResolvedValue({ + state, + nonce: storedNonce, + code_verifier: 'valid-code-verifier-value-here-long', + created_at: new Date().toISOString(), + expires_at: future, + }); + + // Sign with wrong key → INVALID_ID_TOKEN + const wrongKey = generateTestKeyPair(); + const idToken = buildIdToken( + config, + storedNonce, + {}, + wrongKey.privateKey, + wrongKey.kid, + ); + mockFetchForToken(idToken); + + try { + await service.handleCallback(code, state); + } catch { + // Expected INVALID_ID_TOKEN + } + + assertStateDeleted(state); + }, + ), + { numRuns: 100 }, + ); + }); + }); +}); diff --git a/backend/test/properties/EntraIdGroupSync.property.test.ts b/backend/test/properties/EntraIdGroupSync.property.test.ts new file mode 100644 index 00000000..39bfbae6 --- /dev/null +++ b/backend/test/properties/EntraIdGroupSync.property.test.ts @@ -0,0 +1,462 @@ +/** + * Property-Based Test for EntraIdService — Group-to-Role Synchronization (Property 15) + * + * Feature: azure-entra-id-auth, Property 15: Group-to-role synchronization correctness + * + * **Validates: Requirements 5.1, 5.2, 5.3** + * + * For any group mapping configuration and any groups claim array (with UUIDs + * in any case), the user SHALL end up with exactly the Pabawi roles whose + * group IDs are present in both the mapping keys (case-insensitive comparison) + * and the groups claim, plus any roles that were not part of the mapping + * (manually assigned). Roles previously assigned by the mapping whose group + * IDs are no longer in the claim SHALL be revoked. + */ + +import { describe, it, expect, beforeEach, vi } from 'vitest'; +import * as fc from 'fast-check'; + +import { EntraIdService } from '../../src/services/EntraIdService'; +import type { DatabaseAdapter } from '../../src/database/DatabaseAdapter'; +import type { EntraIdConfig } from '../../src/config/schema'; +import type { AuthenticationService } from '../../src/services/AuthenticationService'; +import type { UserService } from '../../src/services/UserService'; +import type { RoleService } from '../../src/services/RoleService'; +import type { Role } from '../../src/services/RoleService'; +import type { AuditLoggingService } from '../../src/services/AuditLoggingService'; +import type { LoggerService } from '../../src/services/LoggerService'; + +// --- Mock Factories --- + +function createMockDb(): DatabaseAdapter { + return { + query: vi.fn().mockResolvedValue([]), + queryOne: vi.fn().mockResolvedValue(null), + execute: vi.fn().mockResolvedValue({ changes: 0 }), + beginTransaction: vi.fn().mockResolvedValue(undefined), + commit: vi.fn().mockResolvedValue(undefined), + rollback: vi.fn().mockResolvedValue(undefined), + withTransaction: vi.fn(), + initialize: vi.fn().mockResolvedValue(undefined), + close: vi.fn().mockResolvedValue(undefined), + isConnected: vi.fn().mockReturnValue(true), + getDialect: vi.fn().mockReturnValue('sqlite' as const), + }; +} + +function createMockLogger(): LoggerService { + return { + info: vi.fn(), + warn: vi.fn(), + error: vi.fn(), + debug: vi.fn(), + shouldLog: vi.fn().mockReturnValue(true), + formatMessage: vi.fn().mockReturnValue(''), + getLevel: vi.fn().mockReturnValue('info'), + setLogBuffer: vi.fn(), + getLogBuffer: vi.fn().mockReturnValue(null), + } as unknown as LoggerService; +} + +function makeRole(id: string, name: string): Role { + return { + id, + name, + description: `Role: ${name}`, + isBuiltIn: 0, + createdAt: '2024-01-01T00:00:00.000Z', + updatedAt: '2024-01-01T00:00:00.000Z', + }; +} + +// --- Arbitraries --- + +/** Generate a UUID string (lowercase by default from fc.uuid()) */ +const uuidArb = fc.uuid(); + +/** Role name arbitrary */ +const roleNameArb = fc.stringMatching(/^[a-z][a-z0-9_]{2,15}$/); + +/** + * Generates a complete test scenario for group-to-role sync: + * - A set of available Pabawi roles (with unique names and IDs) + * - A group mapping: groupId → roleName (referencing some of the available roles, and possibly some non-existent ones) + * - A groups claim: list of group UUIDs (some matching mapping keys, some not) in random case + * - Existing user roles: some from the mapping, some manual (not in mapping) + */ +interface SyncScenario { + /** All roles that exist in Pabawi */ + availableRoles: Role[]; + /** The group mapping config: groupId → roleName */ + groupMapping: Record; + /** The groups claim from the ID token (UUIDs in mixed case) */ + groupsClaim: string[]; + /** Roles currently assigned to the user */ + existingUserRoles: Role[]; + /** Expected final role set (role IDs) after sync */ + expectedFinalRoleIds: Set; +} + +const syncScenarioArb: fc.Arbitrary = fc.tuple( + // Generate 2–8 available roles + fc.integer({ min: 2, max: 8 }), + // Generate 1–6 mapping entries + fc.integer({ min: 1, max: 6 }), + // Seed for randomizing which mapping entries have valid roles + fc.infiniteStream(fc.boolean()), + // Seed for randomizing which groups appear in claim + fc.infiniteStream(fc.boolean()), + // Seed for randomizing which mapped roles user currently has + fc.infiniteStream(fc.boolean()), + // Seed for randomizing which non-mapped roles user currently has + fc.infiniteStream(fc.boolean()), + // UUIDs for group IDs + fc.array(uuidArb, { minLength: 8, maxLength: 14 }), + // Role names + fc.array(roleNameArb, { minLength: 10, maxLength: 14 }), + // Booleans for case randomization + fc.infiniteStream(fc.boolean()), +).map(([ + numRoles, + numMappings, + validRoleStream, + groupInClaimStream, + userHasMappedRoleStream, + userHasManualRoleStream, + uuids, + roleNames, + caseStream, +]) => { + // Deduplicate role names + const uniqueRoleNames = [...new Set(roleNames)].slice(0, numRoles); + if (uniqueRoleNames.length < 2) { + uniqueRoleNames.push('fallback_role_a', 'fallback_role_b'); + } + + // Create available roles + const availableRoles: Role[] = uniqueRoleNames.map((name, i) => + makeRole(`role-id-${String(i)}`, name), + ); + + // Create group mapping + const groupMapping: Record = {}; + const mappingGroupIds: string[] = []; + const validRoleIterator = validRoleStream[Symbol.iterator](); + const actualNumMappings = Math.min(numMappings, uuids.length); + + for (let i = 0; i < actualNumMappings; i++) { + const groupId = uuids[i]; + const useValidRole = validRoleIterator.next().value; + if (useValidRole && availableRoles.length > 0) { + // Map to an existing role + const roleIdx = i % availableRoles.length; + groupMapping[groupId] = availableRoles[roleIdx].name; + } else { + // Map to a non-existent role (should be skipped with warning) + groupMapping[groupId] = `nonexistent_role_${String(i)}`; + } + mappingGroupIds.push(groupId); + } + + // Create groups claim — include some mapping group IDs (with random case) and some extra + const groupsClaim: string[] = []; + const groupInClaimIterator = groupInClaimStream[Symbol.iterator](); + const caseIterator = caseStream[Symbol.iterator](); + + for (const gid of mappingGroupIds) { + const includeInClaim = groupInClaimIterator.next().value; + if (includeInClaim) { + // Apply random case to the group ID + const casedGid = gid.split('').map((ch) => { + const upper = caseIterator.next().value; + return upper ? ch.toUpperCase() : ch.toLowerCase(); + }).join(''); + groupsClaim.push(casedGid); + } + } + // Add some extra UUIDs not in the mapping + for (let i = actualNumMappings; i < uuids.length && i < actualNumMappings + 3; i++) { + groupsClaim.push(uuids[i]); + } + + // Determine which role IDs are managed by the mapping (only valid ones) + const rolesByNameLower = new Map(availableRoles.map((r) => [r.name.toLowerCase(), r])); + const managedRoleIds = new Set(); + const shouldHaveRoleIds = new Set(); + const normalizedClaim = new Set(groupsClaim.map((g) => g.toLowerCase())); + + for (const [groupId, roleName] of Object.entries(groupMapping)) { + const role = rolesByNameLower.get(roleName.toLowerCase()); + if (!role) continue; // Non-existent role, skipped + managedRoleIds.add(role.id); + if (normalizedClaim.has(groupId.toLowerCase())) { + shouldHaveRoleIds.add(role.id); + } + } + + // Create existing user roles — mix of mapped and manual + const existingUserRoles: Role[] = []; + const userHasMappedIterator = userHasMappedRoleStream[Symbol.iterator](); + const userHasManualIterator = userHasManualRoleStream[Symbol.iterator](); + + // Add some mapped roles (simulates previously synced roles) + for (const roleId of managedRoleIds) { + if (userHasMappedIterator.next().value) { + const role = availableRoles.find((r) => r.id === roleId); + if (role) existingUserRoles.push(role); + } + } + + // Add some manual roles (not in the mapping) + for (const role of availableRoles) { + if (!managedRoleIds.has(role.id) && userHasManualIterator.next().value) { + existingUserRoles.push(role); + } + } + + // Compute expected final role set: + // = (manual roles not managed by mapping) ∪ (mapped roles the user should have) + const manualRoleIds = new Set( + existingUserRoles + .filter((r) => !managedRoleIds.has(r.id)) + .map((r) => r.id), + ); + + const expectedFinalRoleIds = new Set([...manualRoleIds, ...shouldHaveRoleIds]); + + return { + availableRoles, + groupMapping, + groupsClaim, + existingUserRoles, + expectedFinalRoleIds, + }; +}); + +describe('EntraIdService — Group-to-Role Sync Property', () => { + let db: DatabaseAdapter; + let logger: LoggerService; + + beforeEach(() => { + vi.restoreAllMocks(); + db = createMockDb(); + logger = createMockLogger(); + }); + + // Feature: azure-entra-id-auth, Property 15: Group-to-role synchronization correctness + /** + * Property 15: Group-to-role synchronization correctness + * + * **Validates: Requirements 5.1, 5.2, 5.3** + * + * For any group mapping configuration and any groups claim array (with UUIDs + * in any case), the user SHALL end up with exactly the Pabawi roles whose + * group IDs are present in both the mapping keys (case-insensitive comparison) + * and the groups claim, plus any roles that were not part of the mapping + * (manually assigned). Roles previously assigned by the mapping whose group + * IDs are no longer in the claim SHALL be revoked. + */ + describe('Property 15: Group-to-role synchronization correctness', () => { + it('after sync, user roles = (manual roles not in mapping) ∪ (mapped roles for matching groups)', async () => { + await fc.assert( + fc.asyncProperty( + syncScenarioArb, + async (scenario) => { + const { availableRoles, groupMapping, groupsClaim, existingUserRoles, expectedFinalRoleIds } = scenario; + + // Track role mutations + const assignedRoleIds = new Set(); + const removedRoleIds = new Set(); + + const mockUserService = { + getUserRoles: vi.fn().mockResolvedValue(existingUserRoles), + assignRoleToUser: vi.fn().mockImplementation((_userId: string, roleId: string) => { + assignedRoleIds.add(roleId); + return Promise.resolve(); + }), + removeRoleFromUser: vi.fn().mockImplementation((_userId: string, roleId: string) => { + removedRoleIds.add(roleId); + return Promise.resolve(); + }), + } as unknown as UserService; + + const mockRoleService = { + listRoles: vi.fn().mockResolvedValue({ + items: availableRoles, + total: availableRoles.length, + }), + } as unknown as RoleService; + + const config: EntraIdConfig = { + enabled: true, + tenantId: 'test-tenant', + clientId: 'test-client', + clientSecret: 'test-secret', // pragma: allowlist secret + redirectUri: 'http://localhost:3000/callback', + scopes: ['openid', 'profile', 'email'], + groupMapping, + jwksCacheTtlMs: 86400000, + }; + + const service = new EntraIdService( + db, + config, + {} as AuthenticationService, + mockUserService, + mockRoleService, + {} as AuditLoggingService, + logger, + ); + + const userId = 'test-user-id'; + await service.syncGroupRoles(userId, groupsClaim); + + // Compute actual final role set by applying mutations to existing roles + const existingRoleIds = new Set(existingUserRoles.map((r) => r.id)); + const finalRoleIds = new Set(); + + // Start with existing roles + for (const id of existingRoleIds) { + if (!removedRoleIds.has(id)) { + finalRoleIds.add(id); + } + } + // Add newly assigned roles + for (const id of assignedRoleIds) { + finalRoleIds.add(id); + } + + // Assert final role set matches expected + expect(finalRoleIds).toEqual(expectedFinalRoleIds); + }, + ), + { numRuns: 100 }, + ); + }); + + it('does not assign roles the user already has', async () => { + await fc.assert( + fc.asyncProperty( + syncScenarioArb, + async (scenario) => { + const { availableRoles, groupMapping, groupsClaim, existingUserRoles } = scenario; + + const assignCalls: Array<{ userId: string; roleId: string }> = []; + + const mockUserService = { + getUserRoles: vi.fn().mockResolvedValue(existingUserRoles), + assignRoleToUser: vi.fn().mockImplementation((userId: string, roleId: string) => { + assignCalls.push({ userId, roleId }); + return Promise.resolve(); + }), + removeRoleFromUser: vi.fn().mockResolvedValue(undefined), + } as unknown as UserService; + + const mockRoleService = { + listRoles: vi.fn().mockResolvedValue({ + items: availableRoles, + total: availableRoles.length, + }), + } as unknown as RoleService; + + const config: EntraIdConfig = { + enabled: true, + tenantId: 'test-tenant', + clientId: 'test-client', + clientSecret: 'test-secret', // pragma: allowlist secret + redirectUri: 'http://localhost:3000/callback', + scopes: ['openid', 'profile', 'email'], + groupMapping, + jwksCacheTtlMs: 86400000, + }; + + const service = new EntraIdService( + db, + config, + {} as AuthenticationService, + mockUserService, + mockRoleService, + {} as AuditLoggingService, + logger, + ); + + await service.syncGroupRoles('test-user-id', groupsClaim); + + // No assign call should be for a role the user already has + const existingRoleIds = new Set(existingUserRoles.map((r) => r.id)); + for (const call of assignCalls) { + expect(existingRoleIds.has(call.roleId)).toBe(false); + } + }, + ), + { numRuns: 100 }, + ); + }); + + it('does not remove roles that are not managed by the mapping', async () => { + await fc.assert( + fc.asyncProperty( + syncScenarioArb, + async (scenario) => { + const { availableRoles, groupMapping, groupsClaim, existingUserRoles } = scenario; + + const removeCalls: Array<{ userId: string; roleId: string }> = []; + + const mockUserService = { + getUserRoles: vi.fn().mockResolvedValue(existingUserRoles), + assignRoleToUser: vi.fn().mockResolvedValue(undefined), + removeRoleFromUser: vi.fn().mockImplementation((userId: string, roleId: string) => { + removeCalls.push({ userId, roleId }); + return Promise.resolve(); + }), + } as unknown as UserService; + + const mockRoleService = { + listRoles: vi.fn().mockResolvedValue({ + items: availableRoles, + total: availableRoles.length, + }), + } as unknown as RoleService; + + const config: EntraIdConfig = { + enabled: true, + tenantId: 'test-tenant', + clientId: 'test-client', + clientSecret: 'test-secret', // pragma: allowlist secret + redirectUri: 'http://localhost:3000/callback', + scopes: ['openid', 'profile', 'email'], + groupMapping, + jwksCacheTtlMs: 86400000, + }; + + const service = new EntraIdService( + db, + config, + {} as AuthenticationService, + mockUserService, + mockRoleService, + {} as AuditLoggingService, + logger, + ); + + await service.syncGroupRoles('test-user-id', groupsClaim); + + // Determine which role IDs are managed by the mapping + const rolesByNameLower = new Map(availableRoles.map((r) => [r.name.toLowerCase(), r])); + const managedRoleIds = new Set(); + for (const roleName of Object.values(groupMapping)) { + const role = rolesByNameLower.get(roleName.toLowerCase()); + if (role) managedRoleIds.add(role.id); + } + + // Every removed role must be a managed role + for (const call of removeCalls) { + expect(managedRoleIds.has(call.roleId)).toBe(true); + } + }, + ), + { numRuns: 100 }, + ); + }); + }); +}); diff --git a/backend/test/properties/EntraIdProviders.property.test.ts b/backend/test/properties/EntraIdProviders.property.test.ts new file mode 100644 index 00000000..161e63ac --- /dev/null +++ b/backend/test/properties/EntraIdProviders.property.test.ts @@ -0,0 +1,223 @@ +/** + * Property-Based Tests for Providers Endpoint — Property 17 + * + * **Validates: Requirements 11.2** + * + * Tests the correctness property from the design document: + * - Property 17: Providers endpoint always includes local authentication + * + * For any application configuration state (Entra ID enabled or disabled, any + * combination of integrations), the `GET /api/auth/providers` response SHALL + * always contain `{ "local": true }`. + */ + +// Feature: azure-entra-id-auth, Property 17: Providers endpoint always includes local authentication + +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import * as fc from 'fast-check'; +import express from 'express'; +import request from 'supertest'; + +import { createAuthRouter } from '../../src/routes/auth.ts'; +import { SQLiteAdapter } from '../../src/database/SQLiteAdapter'; +import { DatabaseService } from '../../src/database/DatabaseService'; +import type { DatabaseAdapter } from '../../src/database/DatabaseAdapter'; +import { DIContainer } from '../../src/container/DIContainer'; +import { LoggerService } from '../../src/services/LoggerService'; +import { ExpertModeService } from '../../src/services/ExpertModeService'; +import { ConfigService } from '../../src/config/ConfigService'; +import { initializeTestSchema } from '../helpers/schema'; + +/** + * Arbitrary that generates a configuration state for the test. + * - entraIdEnabled: whether an EntraIdService mock is registered + * - extraServices: random additional service keys registered on the container (noise) + */ +interface ConfigState { + entraIdEnabled: boolean; + extraServiceKeys: string[]; + providerName: string; +} + +const configStateArb: fc.Arbitrary = fc.record({ + entraIdEnabled: fc.boolean(), + extraServiceKeys: fc.array( + fc.stringMatching(/^[a-z][a-zA-Z0-9]{2,20}$/), + { minLength: 0, maxLength: 5 }, + ), + providerName: fc.constantFrom( + 'Microsoft Entra ID', + 'Azure AD', + 'Custom SSO Provider', + ), +}); + +describe('Providers Endpoint — Property 17: Providers endpoint always includes local authentication', () => { + let db: DatabaseAdapter; + let databaseService: DatabaseService; + + beforeEach(async () => { + vi.restoreAllMocks(); + + // Minimal env for ConfigService + process.env.JWT_SECRET = 'test-jwt-secret-for-property-tests-minimum-32chars!!'; // pragma: allowlist secret + process.env.HOST = 'localhost'; + process.env.PORT = '3000'; + + db = new SQLiteAdapter(':memory:'); + await db.initialize(); + await initializeTestSchema(db); + + databaseService = { + getAdapter: () => db, + } as unknown as DatabaseService; + }); + + afterEach(async () => { + await db.close(); + delete process.env.JWT_SECRET; + delete process.env.HOST; + delete process.env.PORT; + }); + + /** + * Build a container with the given configuration state. + * Optionally registers a mock EntraIdService on the "entraId" key. + */ + function buildContainer(state: ConfigState): DIContainer { + const container = new DIContainer(); + container.register('logger', new LoggerService()); + container.register('expertMode', new ExpertModeService()); + container.register('config', new ConfigService()); + + // Access internal service map to register additional keys (simulates other integrations) + const services = (container as unknown as { services: Map }).services; + + // Register noise services (random integrations that should not affect providers) + for (const key of state.extraServiceKeys) { + services.set(key, { name: key }); + } + + // Conditionally register EntraIdService mock + if (state.entraIdEnabled) { + services.set('entraId', { + getProviderInfo: () => ({ enabled: true as const, name: state.providerName }), + }); + } + + return container; + } + + /** + * Build an Express app with the auth router mounted at /api/auth. + */ + function buildApp(container: DIContainer): express.Application { + const app = express(); + app.use(express.json()); + const router = createAuthRouter(databaseService, container); + app.use('/api/auth', router); + return app; + } + + /** + * Property: For ANY configuration state, `GET /api/auth/providers` + * response always contains `{ local: true }`. + */ + it('response always contains local: true regardless of configuration', async () => { + await fc.assert( + fc.asyncProperty( + configStateArb, + async (state) => { + const container = buildContainer(state); + const app = buildApp(container); + + const res = await request(app) + .get('/api/auth/providers') + .expect(200); + + // Core invariant: local is always true + expect(res.body.local).toBe(true); + }, + ), + { numRuns: 100 }, + ); + }); + + /** + * Property: When Entra ID service is present, response also contains entraId info. + */ + it('includes entraId provider info when EntraIdService is registered', async () => { + await fc.assert( + fc.asyncProperty( + configStateArb.filter((s) => s.entraIdEnabled), + async (state) => { + const container = buildContainer(state); + const app = buildApp(container); + + const res = await request(app) + .get('/api/auth/providers') + .expect(200); + + // local is still present + expect(res.body.local).toBe(true); + + // entraId info is present + expect(res.body.entraId).toBeDefined(); + expect(res.body.entraId.enabled).toBe(true); + expect(res.body.entraId.name).toBe(state.providerName); + }, + ), + { numRuns: 100 }, + ); + }); + + /** + * Property: When Entra ID service is absent, response does NOT contain entraId key. + */ + it('omits entraId key when EntraIdService is not registered', async () => { + await fc.assert( + fc.asyncProperty( + configStateArb.filter((s) => !s.entraIdEnabled), + async (state) => { + const container = buildContainer(state); + const app = buildApp(container); + + const res = await request(app) + .get('/api/auth/providers'); + + expect(res.status).toBe(200); + + // local is always present + expect(res.body.local).toBe(true); + + // entraId key should be absent + expect(res.body.entraId).toBeUndefined(); + }, + ), + { numRuns: 100 }, + ); + }); + + /** + * Property: Endpoint is accessible without authentication (no auth header needed). + */ + it('endpoint responds 200 without any auth header for any config state', async () => { + await fc.assert( + fc.asyncProperty( + configStateArb, + async (state) => { + const container = buildContainer(state); + const app = buildApp(container); + + // No Authorization header at all — endpoint must not require auth + const res = await request(app) + .get('/api/auth/providers'); + + expect(res.status).toBe(200); + expect(res.body.local).toBe(true); + }, + ), + { numRuns: 100 }, + ); + }); +}); diff --git a/backend/test/properties/EntraIdProvisioning.property.test.ts b/backend/test/properties/EntraIdProvisioning.property.test.ts new file mode 100644 index 00000000..86b0c855 --- /dev/null +++ b/backend/test/properties/EntraIdProvisioning.property.test.ts @@ -0,0 +1,519 @@ +/** + * Property-Based Tests for EntraIdService — User Provisioning (Properties 12–14) + * + * **Validates: Requirements 4.1, 4.2, 4.3, 4.5, 4.7** + * + * Tests the three correctness properties from the design document: + * - Property 12: New federated user provisioning invariant + * - Property 13: Existing federated user profile immutability + * - Property 14: Username derivation from invalid preferred_username + */ + +import { describe, it, expect, beforeEach, vi } from 'vitest'; +import * as fc from 'fast-check'; + +import { + EntraIdService, + type IdTokenClaims, +} from '../../src/services/EntraIdService'; +import type { DatabaseAdapter } from '../../src/database/DatabaseAdapter'; +import type { EntraIdConfig } from '../../src/config/schema'; +import type { AuthenticationService } from '../../src/services/AuthenticationService'; +import type { UserService, User } from '../../src/services/UserService'; +import type { RoleService } from '../../src/services/RoleService'; +import type { AuditLoggingService } from '../../src/services/AuditLoggingService'; +import type { LoggerService } from '../../src/services/LoggerService'; + +// --- Mock Factories --- + +function createMockDb(): DatabaseAdapter { + return { + query: vi.fn().mockResolvedValue([]), + queryOne: vi.fn().mockResolvedValue(null), + execute: vi.fn().mockResolvedValue({ changes: 0 }), + beginTransaction: vi.fn().mockResolvedValue(undefined), + commit: vi.fn().mockResolvedValue(undefined), + rollback: vi.fn().mockResolvedValue(undefined), + withTransaction: vi.fn(), + initialize: vi.fn().mockResolvedValue(undefined), + close: vi.fn().mockResolvedValue(undefined), + isConnected: vi.fn().mockReturnValue(true), + getDialect: vi.fn().mockReturnValue('sqlite' as const), + }; +} + +function createMockConfig(): EntraIdConfig { + return { + enabled: true, + tenantId: 'test-tenant-id-000', + clientId: 'test-client-id-111', + clientSecret: 'test-client-secret-222', // pragma: allowlist secret + redirectUri: 'http://localhost:3000/api/auth/entra-id/callback', + scopes: ['openid', 'profile', 'email'], + groupMapping: null, + jwksCacheTtlMs: 86400000, + }; +} + +function createMockLogger(): LoggerService { + return { + info: vi.fn(), + warn: vi.fn(), + error: vi.fn(), + debug: vi.fn(), + shouldLog: vi.fn().mockReturnValue(true), + formatMessage: vi.fn().mockReturnValue(''), + getLevel: vi.fn().mockReturnValue('info'), + setLogBuffer: vi.fn(), + getLogBuffer: vi.fn().mockReturnValue(null), + } as unknown as LoggerService; +} + +function createMockUser(overrides: Partial = {}): User { + const now = new Date().toISOString(); + return { + id: 'user-id-001', + username: 'testuser', + email: 'user@example.com', + passwordHash: '', + firstName: 'Test', + lastName: 'User', + isActive: 1, + isAdmin: 0, + createdAt: now, + updatedAt: now, + lastLoginAt: null, + ...overrides, + }; +} + +// --- Arbitraries --- + +/** Generates a valid Entra ID subject identifier (opaque string) */ +const subArb = fc.stringMatching(/^[a-zA-Z0-9_-]{10,40}$/); + +/** Generates a valid email address */ +const emailArb = fc.tuple( + fc.stringMatching(/^[a-z][a-z0-9._]{2,15}$/), + fc.stringMatching(/^[a-z]{3,10}\.[a-z]{2,4}$/), +).map(([local, domain]) => `${local}@${domain}`); + +/** Generates a valid preferred_username (matches ^[a-zA-Z0-9_]{3,50}$) */ +const validUsernameArb = fc.stringMatching(/^[a-zA-Z][a-zA-Z0-9_]{2,49}$/); + +/** Generates first/last names */ +const nameArb = fc.stringMatching(/^[A-Z][a-z]{1,19}$/); + +/** Generates a complete valid IdTokenClaims set */ +const validClaimsArb = fc.record({ + sub: subArb, + email: emailArb, + preferred_username: validUsernameArb, + given_name: nameArb, + family_name: nameArb, + nonce: fc.stringMatching(/^[a-f0-9]{32,64}$/), + aud: fc.constant('test-client-id-111'), + iss: fc.constant('https://login.microsoftonline.com/test-tenant-id-000/v2.0'), + exp: fc.constant(Math.floor(Date.now() / 1000) + 3600), +}) as fc.Arbitrary; + +/** + * Generates a preferred_username that does NOT match ^[a-zA-Z0-9_]{3,50}$ + * (contains special chars, spaces, dots, hyphens, or is too short/long) + */ +const invalidUsernameArb = fc.oneof( + // Contains disallowed characters (dots, hyphens, spaces, @) + fc.stringMatching(/^[a-z]{3,10}[.\-@ ][a-z]{3,10}$/), + // Too short (1-2 chars) + fc.stringMatching(/^[a-z]{1,2}$/), + // Contains special characters + fc.stringMatching(/^[a-z]{3,8}[!#$%]{1,3}[a-z]{3,8}$/), +); + +describe('EntraIdService — User Provisioning Properties', () => { + let db: DatabaseAdapter; + let config: EntraIdConfig; + let logger: LoggerService; + let mockUserService: UserService; + let mockRoleService: RoleService; + let service: EntraIdService; + + beforeEach(() => { + vi.restoreAllMocks(); + db = createMockDb(); + config = createMockConfig(); + logger = createMockLogger(); + + mockUserService = { + findByFederatedIdentity: vi.fn().mockResolvedValue(null), + findByEmail: vi.fn().mockResolvedValue(null), + createFederatedUser: vi.fn().mockImplementation(async (claims: IdTokenClaims) => { + return createMockUser({ + id: `new-user-${claims.sub}`, + username: claims.preferred_username || claims.email.split('@')[0], + email: claims.email, + passwordHash: '', + firstName: claims.given_name, + lastName: claims.family_name, + isActive: 1, + }); + }), + linkFederatedIdentity: vi.fn().mockResolvedValue({ + id: 'fed-id-001', + userId: 'user-id-001', + provider: 'entra-id', + subject: 'test-sub', + issuer: 'test-issuer', + email: 'user@example.com', + idToken: null, + createdAt: new Date().toISOString(), + updatedAt: new Date().toISOString(), + }), + getUserRoles: vi.fn().mockResolvedValue([]), + assignRoleToUser: vi.fn().mockResolvedValue(undefined), + removeRoleFromUser: vi.fn().mockResolvedValue(undefined), + } as unknown as UserService; + + mockRoleService = { + listRoles: vi.fn().mockResolvedValue({ items: [] }), + } as unknown as RoleService; + + service = new EntraIdService( + db, + config, + {} as AuthenticationService, + mockUserService, + mockRoleService, + {} as AuditLoggingService, + logger, + ); + }); + + // Feature: azure-entra-id-auth, Property 12: New federated user provisioning invariant + /** + * Property 12: New federated user provisioning invariant + * + * **Validates: Requirements 4.1, 4.2, 4.5** + * + * For any valid ID token claims (sub, email, preferred_username/derived username, + * given_name, family_name) where no federated identity exists with that sub: + * the service SHALL create a user with is_active=1, null password_hash, + * a federated_identities record with provider='entra-id' and subject=sub, + * and SHALL assign the default viewer role. + */ + describe('Property 12: New federated user provisioning invariant', () => { + it('creates a new user via createFederatedUser when no federated identity exists', async () => { + await fc.assert( + fc.asyncProperty( + validClaimsArb, + async (claims) => { + // Reset mocks for each iteration + vi.mocked(mockUserService.findByFederatedIdentity).mockResolvedValue(null); + vi.mocked(mockUserService.findByEmail).mockResolvedValue(null); + vi.mocked(mockUserService.createFederatedUser).mockResolvedValue( + createMockUser({ + id: `new-user-${claims.sub}`, + username: claims.preferred_username, + email: claims.email, + passwordHash: '', + firstName: claims.given_name, + lastName: claims.family_name, + isActive: 1, + }), + ); + + const result = await service.provisionUser(claims); + + // Service looked up federated identity first + expect(mockUserService.findByFederatedIdentity).toHaveBeenCalledWith( + 'entra-id', + claims.sub, + ); + + // No existing identity → called createFederatedUser with the claims + expect(mockUserService.createFederatedUser).toHaveBeenCalledWith(claims); + + // Returned user has is_active=1 and empty passwordHash + expect(result.isActive).toBe(1); + expect(result.passwordHash).toBe(''); + + // linkFederatedIdentity should NOT be called (createFederatedUser does it internally) + expect(mockUserService.linkFederatedIdentity).not.toHaveBeenCalled(); + }, + ), + { numRuns: 100 }, + ); + }); + + it('the created user has correct profile fields from claims', async () => { + await fc.assert( + fc.asyncProperty( + validClaimsArb, + async (claims) => { + vi.mocked(mockUserService.findByFederatedIdentity).mockResolvedValue(null); + vi.mocked(mockUserService.findByEmail).mockResolvedValue(null); + + const createdUser = createMockUser({ + id: `new-user-${claims.sub}`, + username: claims.preferred_username, + email: claims.email, + passwordHash: '', + firstName: claims.given_name, + lastName: claims.family_name, + isActive: 1, + isAdmin: 0, + }); + vi.mocked(mockUserService.createFederatedUser).mockResolvedValue(createdUser); + + const result = await service.provisionUser(claims); + + expect(result.email).toBe(claims.email); + expect(result.firstName).toBe(claims.given_name); + expect(result.lastName).toBe(claims.family_name); + expect(result.isAdmin).toBe(0); + }, + ), + { numRuns: 100 }, + ); + }); + }); + + // Feature: azure-entra-id-auth, Property 13: Existing federated user profile immutability + /** + * Property 13: Existing federated user profile immutability + * + * **Validates: Requirements 4.3** + * + * For any returning user (federated identity already linked), calling the + * provisioning flow with different claim values (name, email) SHALL NOT + * modify the existing user record's first_name, last_name, or email fields. + */ + describe('Property 13: Existing federated user profile immutability', () => { + it('returns existing user unchanged when federated identity is already linked', async () => { + await fc.assert( + fc.asyncProperty( + validClaimsArb, + nameArb, + nameArb, + emailArb, + async (claims, differentFirst, differentLast, differentEmail) => { + // The existing user has different profile data than the incoming claims + const existingUser = createMockUser({ + id: 'existing-user-id', + username: 'existing_username', + email: differentEmail, + firstName: differentFirst, + lastName: differentLast, + passwordHash: 'hashed-password-value', + isActive: 1, + }); + + vi.mocked(mockUserService.findByFederatedIdentity).mockResolvedValue(existingUser); + + const result = await service.provisionUser(claims); + + // The returned user is the existing user, not modified + expect(result.id).toBe('existing-user-id'); + expect(result.email).toBe(differentEmail); + expect(result.firstName).toBe(differentFirst); + expect(result.lastName).toBe(differentLast); + + // createFederatedUser and linkFederatedIdentity must NOT be called + expect(mockUserService.createFederatedUser).not.toHaveBeenCalled(); + expect(mockUserService.linkFederatedIdentity).not.toHaveBeenCalled(); + }, + ), + { numRuns: 100 }, + ); + }); + + it('does not update the existing user password hash', async () => { + await fc.assert( + fc.asyncProperty( + validClaimsArb, + async (claims) => { + const existingUser = createMockUser({ + id: 'existing-user-id', + passwordHash: 'original-bcrypt-hash-value', + isActive: 1, + }); + + vi.mocked(mockUserService.findByFederatedIdentity).mockResolvedValue(existingUser); + + const result = await service.provisionUser(claims); + + // Password hash remains unchanged + expect(result.passwordHash).toBe('original-bcrypt-hash-value'); + }, + ), + { numRuns: 100 }, + ); + }); + }); + + // Feature: azure-entra-id-auth, Property 14: Username derivation from invalid preferred_username + /** + * Property 14: Username derivation from invalid preferred_username + * + * **Validates: Requirements 4.7** + * + * For any preferred_username that does not match ^[a-zA-Z0-9_]{3,50}$, + * the service SHALL derive the username from the email local-part by + * replacing all characters not in [a-zA-Z0-9_] with underscores and + * truncating to 50 characters. + */ + describe('Property 14: Username derivation from invalid preferred_username', () => { + it('derives username from email local-part when preferred_username is invalid', async () => { + await fc.assert( + fc.asyncProperty( + invalidUsernameArb, + emailArb, + nameArb, + nameArb, + subArb, + async (invalidUsername, email, firstName, lastName, sub) => { + const claims: IdTokenClaims = { + sub, + email, + preferred_username: invalidUsername, + given_name: firstName, + family_name: lastName, + nonce: 'test-nonce-value', + aud: config.clientId, + iss: `https://login.microsoftonline.com/${config.tenantId}/v2.0`, + exp: Math.floor(Date.now() / 1000) + 3600, + }; + + vi.mocked(mockUserService.findByFederatedIdentity).mockResolvedValue(null); + vi.mocked(mockUserService.findByEmail).mockResolvedValue(null); + + // Capture what createFederatedUser receives to verify username derivation + let receivedClaims: IdTokenClaims | null = null; + vi.mocked(mockUserService.createFederatedUser).mockImplementation( + async (c: IdTokenClaims) => { + receivedClaims = c; + return createMockUser({ + id: `new-user-${c.sub}`, + email: c.email, + // UserService.createFederatedUser internally derives the username + username: c.email.split('@')[0].replace(/[^a-zA-Z0-9_]/g, '_').slice(0, 50), + passwordHash: '', + isActive: 1, + }); + }, + ); + + const result = await service.provisionUser(claims); + + // createFederatedUser was called with original claims + // (UserService.deriveUsername handles the derivation internally) + expect(receivedClaims).not.toBeNull(); + expect(receivedClaims!.preferred_username).toBe(invalidUsername); + expect(receivedClaims!.email).toBe(email); + + // The returned username must be derived from email local-part: + // replace non-[a-zA-Z0-9_] with underscores, truncate to 50 + const expectedUsername = email.split('@')[0] + .replace(/[^a-zA-Z0-9_]/g, '_') + .slice(0, 50); + expect(result.username).toBe(expectedUsername); + }, + ), + { numRuns: 100 }, + ); + }); + + it('derived username is at most 50 characters', async () => { + // Generate emails with long local parts + const longLocalPartEmail = fc.tuple( + fc.stringMatching(/^[a-z][a-z0-9.]{50,80}$/), + fc.constant('example.com'), + ).map(([local, domain]) => `${local}@${domain}`); + + await fc.assert( + fc.asyncProperty( + longLocalPartEmail, + subArb, + async (email, sub) => { + const claims: IdTokenClaims = { + sub, + email, + preferred_username: 'ab', // Too short → invalid + given_name: 'Test', + family_name: 'User', + nonce: 'test-nonce', + aud: config.clientId, + iss: `https://login.microsoftonline.com/${config.tenantId}/v2.0`, + exp: Math.floor(Date.now() / 1000) + 3600, + }; + + vi.mocked(mockUserService.findByFederatedIdentity).mockResolvedValue(null); + vi.mocked(mockUserService.findByEmail).mockResolvedValue(null); + vi.mocked(mockUserService.createFederatedUser).mockImplementation( + async (c: IdTokenClaims) => { + const username = c.email.split('@')[0] + .replace(/[^a-zA-Z0-9_]/g, '_') + .slice(0, 50); + return createMockUser({ + id: `new-user-${c.sub}`, + email: c.email, + username, + passwordHash: '', + isActive: 1, + }); + }, + ); + + const result = await service.provisionUser(claims); + expect(result.username.length).toBeLessThanOrEqual(50); + }, + ), + { numRuns: 100 }, + ); + }); + + it('derived username only contains [a-zA-Z0-9_]', async () => { + await fc.assert( + fc.asyncProperty( + invalidUsernameArb, + emailArb, + subArb, + async (invalidUsername, email, sub) => { + const claims: IdTokenClaims = { + sub, + email, + preferred_username: invalidUsername, + given_name: 'Test', + family_name: 'User', + nonce: 'test-nonce', + aud: config.clientId, + iss: `https://login.microsoftonline.com/${config.tenantId}/v2.0`, + exp: Math.floor(Date.now() / 1000) + 3600, + }; + + vi.mocked(mockUserService.findByFederatedIdentity).mockResolvedValue(null); + vi.mocked(mockUserService.findByEmail).mockResolvedValue(null); + vi.mocked(mockUserService.createFederatedUser).mockImplementation( + async (c: IdTokenClaims) => { + const username = c.email.split('@')[0] + .replace(/[^a-zA-Z0-9_]/g, '_') + .slice(0, 50); + return createMockUser({ + id: `new-user-${c.sub}`, + email: c.email, + username, + passwordHash: '', + isActive: 1, + }); + }, + ); + + const result = await service.provisionUser(claims); + expect(result.username).toMatch(/^[a-zA-Z0-9_]+$/); + }, + ), + { numRuns: 100 }, + ); + }); + }); +}); diff --git a/backend/test/unit/services/EntraIdService.test.ts b/backend/test/unit/services/EntraIdService.test.ts new file mode 100644 index 00000000..8615b240 --- /dev/null +++ b/backend/test/unit/services/EntraIdService.test.ts @@ -0,0 +1,656 @@ +/** + * Unit tests for EntraIdService — authorization URL generation, state cleanup, + * and provider info. + */ + +import { describe, it, expect, beforeEach, vi } from 'vitest'; +import { EntraIdService, EntraIdError, ENTRA_ID_ERROR_CODES } from '../../../src/services/EntraIdService'; +import type { IdTokenClaims } from '../../../src/services/EntraIdService'; +import type { DatabaseAdapter } from '../../../src/database/DatabaseAdapter'; +import type { EntraIdConfig } from '../../../src/config/schema'; +import type { AuthenticationService } from '../../../src/services/AuthenticationService'; +import type { UserService, User } from '../../../src/services/UserService'; +import type { RoleService } from '../../../src/services/RoleService'; +import type { AuditLoggingService } from '../../../src/services/AuditLoggingService'; +import type { LoggerService } from '../../../src/services/LoggerService'; + +function createMockDb(): DatabaseAdapter { + return { + query: vi.fn().mockResolvedValue([]), + queryOne: vi.fn().mockResolvedValue(null), + execute: vi.fn().mockResolvedValue({ changes: 0 }), + beginTransaction: vi.fn().mockResolvedValue(undefined), + commit: vi.fn().mockResolvedValue(undefined), + rollback: vi.fn().mockResolvedValue(undefined), + withTransaction: vi.fn(), + initialize: vi.fn().mockResolvedValue(undefined), + close: vi.fn().mockResolvedValue(undefined), + isConnected: vi.fn().mockReturnValue(true), + getDialect: vi.fn().mockReturnValue('sqlite' as const), + }; +} + +function createMockConfig(): EntraIdConfig { + return { + enabled: true, + tenantId: 'test-tenant-id-000', + clientId: 'test-client-id-111', + clientSecret: 'test-client-secret-222', // pragma: allowlist secret + redirectUri: 'http://localhost:3000/api/auth/entra-id/callback', + scopes: ['openid', 'profile', 'email'], + groupMapping: null, + jwksCacheTtlMs: 86400000, + }; +} + +function createMockLogger(): LoggerService { + return { + info: vi.fn(), + warn: vi.fn(), + error: vi.fn(), + debug: vi.fn(), + shouldLog: vi.fn().mockReturnValue(true), + formatMessage: vi.fn().mockReturnValue(''), + getLevel: vi.fn().mockReturnValue('info'), + setLogBuffer: vi.fn(), + getLogBuffer: vi.fn().mockReturnValue(null), + } as unknown as LoggerService; +} + +describe('EntraIdService', () => { + let db: DatabaseAdapter; + let config: EntraIdConfig; + let logger: LoggerService; + let service: EntraIdService; + + beforeEach(() => { + db = createMockDb(); + config = createMockConfig(); + logger = createMockLogger(); + service = new EntraIdService( + db, + config, + {} as AuthenticationService, + {} as UserService, + {} as RoleService, + {} as AuditLoggingService, + logger, + ); + }); + + describe('generateAuthorizationUrl()', () => { + it('returns a URL targeting the correct Entra ID authorize endpoint', async () => { + const { url } = await service.generateAuthorizationUrl(); + expect(url).toContain( + `https://login.microsoftonline.com/${config.tenantId}/oauth2/v2.0/authorize`, + ); + }); + + it('includes response_type=code', async () => { + const { url } = await service.generateAuthorizationUrl(); + const params = new URL(url).searchParams; + expect(params.get('response_type')).toBe('code'); + }); + + it('includes the configured client_id', async () => { + const { url } = await service.generateAuthorizationUrl(); + const params = new URL(url).searchParams; + expect(params.get('client_id')).toBe(config.clientId); + }); + + it('includes the configured redirect_uri', async () => { + const { url } = await service.generateAuthorizationUrl(); + const params = new URL(url).searchParams; + expect(params.get('redirect_uri')).toBe(config.redirectUri); + }); + + it('includes space-separated scopes', async () => { + const { url } = await service.generateAuthorizationUrl(); + const params = new URL(url).searchParams; + expect(params.get('scope')).toBe('openid profile email'); + }); + + it('includes a state parameter with at least 32 bytes of entropy (64 hex chars)', async () => { + const { url, state } = await service.generateAuthorizationUrl(); + const params = new URL(url).searchParams; + expect(params.get('state')).toBe(state); + expect(state).toHaveLength(64); // 32 bytes = 64 hex chars + expect(state).toMatch(/^[0-9a-f]+$/); + }); + + it('includes a nonce parameter with at least 32 bytes of entropy', async () => { + const { url } = await service.generateAuthorizationUrl(); + const params = new URL(url).searchParams; + const nonce = params.get('nonce'); + expect(nonce).toHaveLength(64); + expect(nonce).toMatch(/^[0-9a-f]+$/); + }); + + it('includes code_challenge and code_challenge_method=S256', async () => { + const { url } = await service.generateAuthorizationUrl(); + const params = new URL(url).searchParams; + expect(params.get('code_challenge_method')).toBe('S256'); + const challenge = params.get('code_challenge'); + expect(challenge).toBeTruthy(); + // base64url: no +, /, or = characters + expect(challenge).toMatch(/^[A-Za-z0-9_-]+$/); + }); + + it('stores state, nonce, code_verifier in oauth_state_store with 10-minute TTL', async () => { + const before = Date.now(); + await service.generateAuthorizationUrl(); + const after = Date.now(); + + expect(db.execute).toHaveBeenCalledTimes(1); + const [sql, params] = (db.execute as ReturnType).mock.calls[0]; + expect(sql).toContain('INSERT INTO oauth_state_store'); + + const [state, nonce, codeVerifier, createdAt, expiresAt] = params as string[]; + expect(state).toHaveLength(64); + expect(nonce).toHaveLength(64); + // code_verifier: 64 chars from unreserved charset + expect(codeVerifier).toHaveLength(64); + expect(codeVerifier).toMatch(/^[A-Za-z0-9\-._~]+$/); + + // Verify 10-minute TTL + const createdMs = new Date(createdAt).getTime(); + const expiresMs = new Date(expiresAt).getTime(); + expect(createdMs).toBeGreaterThanOrEqual(before); + expect(createdMs).toBeLessThanOrEqual(after); + expect(expiresMs - createdMs).toBe(10 * 60 * 1000); + }); + + it('generates unique state values on each call', async () => { + const r1 = await service.generateAuthorizationUrl(); + const r2 = await service.generateAuthorizationUrl(); + expect(r1.state).not.toBe(r2.state); + }); + + it('logs the generation without exposing secrets', async () => { + await service.generateAuthorizationUrl(); + expect(logger.info).toHaveBeenCalledWith( + 'Generated authorization URL', + expect.objectContaining({ + component: 'EntraIdService', + operation: 'generateAuthorizationUrl', + }), + ); + }); + }); + + describe('cleanupExpiredState()', () => { + it('deletes expired entries and returns the count', async () => { + (db.execute as ReturnType).mockResolvedValue({ changes: 3 }); + const deleted = await service.cleanupExpiredState(); + expect(deleted).toBe(3); + expect(db.execute).toHaveBeenCalledWith( + expect.stringContaining('DELETE FROM oauth_state_store WHERE expires_at < ?'), + expect.any(Array), + ); + }); + + it('returns 0 when no expired entries exist', async () => { + (db.execute as ReturnType).mockResolvedValue({ changes: 0 }); + const deleted = await service.cleanupExpiredState(); + expect(deleted).toBe(0); + }); + + it('logs only when entries are actually deleted', async () => { + (db.execute as ReturnType).mockResolvedValue({ changes: 0 }); + await service.cleanupExpiredState(); + expect(logger.info).not.toHaveBeenCalled(); + + (db.execute as ReturnType).mockResolvedValue({ changes: 2 }); + await service.cleanupExpiredState(); + expect(logger.info).toHaveBeenCalledWith( + expect.stringContaining('2'), + expect.objectContaining({ + component: 'EntraIdService', + operation: 'cleanupExpiredState', + }), + ); + }); + }); + + describe('getProviderInfo()', () => { + it('returns enabled=true and name "Microsoft Entra ID"', () => { + const info = service.getProviderInfo(); + expect(info).toEqual({ enabled: true, name: 'Microsoft Entra ID' }); + }); + }); + + describe('provisionUser()', () => { + let mockUserService: { + findByFederatedIdentity: ReturnType; + findByEmail: ReturnType; + createFederatedUser: ReturnType; + linkFederatedIdentity: ReturnType; + }; + let provisionService: EntraIdService; + + const baseUser: User = { + id: 'user-123', + username: 'testuser', + email: 'test@example.com', + passwordHash: 'hashed', + firstName: 'Test', + lastName: 'User', + isActive: 1, + isAdmin: 0, + createdAt: '2024-01-01T00:00:00.000Z', + updatedAt: '2024-01-01T00:00:00.000Z', + lastLoginAt: null, + }; + + const baseClaims: IdTokenClaims = { + sub: 'entra-sub-abc123', + email: 'test@example.com', + preferred_username: 'testuser', + given_name: 'Test', + family_name: 'User', + nonce: 'nonce-value', + aud: 'test-client-id-111', + iss: 'https://login.microsoftonline.com/test-tenant-id-000/v2.0', + exp: Math.floor(Date.now() / 1000) + 3600, + }; + + beforeEach(() => { + mockUserService = { + findByFederatedIdentity: vi.fn().mockResolvedValue(null), + findByEmail: vi.fn().mockResolvedValue(null), + createFederatedUser: vi.fn().mockResolvedValue(baseUser), + linkFederatedIdentity: vi.fn().mockResolvedValue({ + id: 'fed-id-1', + userId: baseUser.id, + provider: 'entra-id', + subject: baseClaims.sub, + issuer: baseClaims.iss, + email: baseClaims.email, + idToken: null, + createdAt: '2024-01-01T00:00:00.000Z', + updatedAt: '2024-01-01T00:00:00.000Z', + }), + }; + + provisionService = new EntraIdService( + db, + config, + {} as AuthenticationService, + mockUserService as unknown as UserService, + {} as RoleService, + {} as AuditLoggingService, + logger, + ); + }); + + it('throws MISSING_CLAIMS when both email and preferred_username are absent', async () => { + const claims: IdTokenClaims = { + ...baseClaims, + email: '', + preferred_username: '', + }; + + await expect(provisionService.provisionUser(claims)).rejects.toThrow(EntraIdError); + await expect(provisionService.provisionUser(claims)).rejects.toMatchObject({ + code: ENTRA_ID_ERROR_CODES.MISSING_CLAIMS, + }); + }); + + it('returns existing user when federated identity is found (no profile update)', async () => { + mockUserService.findByFederatedIdentity.mockResolvedValue(baseUser); + + const result = await provisionService.provisionUser(baseClaims); + + expect(result).toBe(baseUser); + expect(mockUserService.findByFederatedIdentity).toHaveBeenCalledWith( + 'entra-id', + baseClaims.sub, + ); + // Must not call create or link + expect(mockUserService.createFederatedUser).not.toHaveBeenCalled(); + expect(mockUserService.linkFederatedIdentity).not.toHaveBeenCalled(); + expect(mockUserService.findByEmail).not.toHaveBeenCalled(); + }); + + it('links federated identity to existing email-match user', async () => { + mockUserService.findByFederatedIdentity.mockResolvedValue(null); + mockUserService.findByEmail.mockResolvedValue(baseUser); + + const result = await provisionService.provisionUser(baseClaims); + + expect(result).toBe(baseUser); + expect(mockUserService.linkFederatedIdentity).toHaveBeenCalledWith( + baseUser.id, + 'entra-id', + baseClaims.sub, + baseClaims.iss, + baseClaims.email, + ); + expect(mockUserService.createFederatedUser).not.toHaveBeenCalled(); + }); + + it('creates new federated user when no match found', async () => { + mockUserService.findByFederatedIdentity.mockResolvedValue(null); + mockUserService.findByEmail.mockResolvedValue(null); + + const newUser = { ...baseUser, id: 'new-user-456' }; + mockUserService.createFederatedUser.mockResolvedValue(newUser); + + const result = await provisionService.provisionUser(baseClaims); + + expect(result).toBe(newUser); + expect(mockUserService.createFederatedUser).toHaveBeenCalledWith(baseClaims); + }); + + it('wraps createFederatedUser errors as PROVISIONING_FAILED', async () => { + mockUserService.findByFederatedIdentity.mockResolvedValue(null); + mockUserService.findByEmail.mockResolvedValue(null); + mockUserService.createFederatedUser.mockRejectedValue( + new Error('UNIQUE constraint failed: users.username'), + ); + + await expect(provisionService.provisionUser(baseClaims)).rejects.toMatchObject({ + code: ENTRA_ID_ERROR_CODES.PROVISIONING_FAILED, + message: 'Account creation failed', + }); + }); + + it('wraps linkFederatedIdentity errors as PROVISIONING_FAILED', async () => { + mockUserService.findByFederatedIdentity.mockResolvedValue(null); + mockUserService.findByEmail.mockResolvedValue(baseUser); + mockUserService.linkFederatedIdentity.mockRejectedValue( + new Error('DB connection lost'), + ); + + await expect(provisionService.provisionUser(baseClaims)).rejects.toMatchObject({ + code: ENTRA_ID_ERROR_CODES.PROVISIONING_FAILED, + message: 'Account creation failed', + }); + }); + + it('proceeds to createFederatedUser when email is present but no email match', async () => { + mockUserService.findByFederatedIdentity.mockResolvedValue(null); + mockUserService.findByEmail.mockResolvedValue(null); + + await provisionService.provisionUser(baseClaims); + + expect(mockUserService.findByEmail).toHaveBeenCalledWith(baseClaims.email); + expect(mockUserService.createFederatedUser).toHaveBeenCalledWith(baseClaims); + }); + + it('skips email lookup and creates user when email is empty but preferred_username is present', async () => { + const claims: IdTokenClaims = { + ...baseClaims, + email: '', + preferred_username: 'someuser', + }; + + mockUserService.findByFederatedIdentity.mockResolvedValue(null); + + await provisionService.provisionUser(claims); + + // findByEmail should not be called with empty string + expect(mockUserService.findByEmail).not.toHaveBeenCalled(); + expect(mockUserService.createFederatedUser).toHaveBeenCalledWith(claims); + }); + + it('logs provisioning actions without exposing tokens or secrets', async () => { + mockUserService.findByFederatedIdentity.mockResolvedValue(null); + mockUserService.findByEmail.mockResolvedValue(null); + + await provisionService.provisionUser(baseClaims); + + expect(logger.info).toHaveBeenCalledWith( + 'New federated user created', + expect.objectContaining({ + component: 'EntraIdService', + operation: 'provisionUser', + }), + ); + }); + }); + + describe('syncGroupRoles()', () => { + let mockUserService: { + findByFederatedIdentity: ReturnType; + findByEmail: ReturnType; + createFederatedUser: ReturnType; + linkFederatedIdentity: ReturnType; + getUserRoles: ReturnType; + assignRoleToUser: ReturnType; + removeRoleFromUser: ReturnType; + }; + let mockRoleService: { + listRoles: ReturnType; + }; + let syncService: EntraIdService; + + const allRoles = [ + { id: 'role-admin', name: 'Administrator', description: '', isBuiltIn: 1, createdAt: '', updatedAt: '' }, + { id: 'role-operator', name: 'Operator', description: '', isBuiltIn: 1, createdAt: '', updatedAt: '' }, + { id: 'role-viewer', name: 'Viewer', description: '', isBuiltIn: 1, createdAt: '', updatedAt: '' }, + { id: 'role-deploy', name: 'Deployer', description: '', isBuiltIn: 0, createdAt: '', updatedAt: '' }, + ]; + + beforeEach(() => { + mockUserService = { + findByFederatedIdentity: vi.fn(), + findByEmail: vi.fn(), + createFederatedUser: vi.fn(), + linkFederatedIdentity: vi.fn(), + getUserRoles: vi.fn().mockResolvedValue([]), + assignRoleToUser: vi.fn().mockResolvedValue(undefined), + removeRoleFromUser: vi.fn().mockResolvedValue(undefined), + }; + + mockRoleService = { + listRoles: vi.fn().mockResolvedValue({ items: allRoles, total: allRoles.length, limit: 1000, offset: 0 }), + }; + }); + + function createSyncService(groupMapping: Record | null): EntraIdService { + const cfg = { ...createMockConfig(), groupMapping }; + syncService = new EntraIdService( + db, + cfg, + {} as AuthenticationService, + mockUserService as unknown as UserService, + mockRoleService as unknown as RoleService, + {} as AuditLoggingService, + logger, + ); + return syncService; + } + + it('skips sync when groupMapping is null', async () => { + createSyncService(null); + await syncService.syncGroupRoles('user-1', ['group-a']); + expect(mockRoleService.listRoles).not.toHaveBeenCalled(); + expect(mockUserService.getUserRoles).not.toHaveBeenCalled(); + }); + + it('skips sync when groups is undefined', async () => { + createSyncService({ 'group-a': 'Operator' }); + await syncService.syncGroupRoles('user-1', undefined); + expect(mockRoleService.listRoles).not.toHaveBeenCalled(); + expect(mockUserService.getUserRoles).not.toHaveBeenCalled(); + }); + + it('assigns roles for matched group IDs', async () => { + createSyncService({ + 'aaaaaaaa-1111-2222-3333-444444444444': 'Operator', + 'bbbbbbbb-1111-2222-3333-444444444444': 'Deployer', + }); + mockUserService.getUserRoles.mockResolvedValue([]); + + await syncService.syncGroupRoles('user-1', [ + 'aaaaaaaa-1111-2222-3333-444444444444', + 'bbbbbbbb-1111-2222-3333-444444444444', + ]); + + expect(mockUserService.assignRoleToUser).toHaveBeenCalledWith('user-1', 'role-operator'); + expect(mockUserService.assignRoleToUser).toHaveBeenCalledWith('user-1', 'role-deploy'); + expect(mockUserService.assignRoleToUser).toHaveBeenCalledTimes(2); + }); + + it('performs case-insensitive UUID matching', async () => { + createSyncService({ + 'AAAAAAAA-1111-2222-3333-444444444444': 'Operator', + }); + mockUserService.getUserRoles.mockResolvedValue([]); + + await syncService.syncGroupRoles('user-1', [ + 'aaaaaaaa-1111-2222-3333-444444444444', + ]); + + expect(mockUserService.assignRoleToUser).toHaveBeenCalledWith('user-1', 'role-operator'); + }); + + it('revokes mapped roles whose group IDs are no longer in the claim', async () => { + createSyncService({ + 'aaaaaaaa-1111-2222-3333-444444444444': 'Operator', + 'bbbbbbbb-1111-2222-3333-444444444444': 'Deployer', + }); + // User currently has Operator and Deployer + mockUserService.getUserRoles.mockResolvedValue([ + { id: 'role-operator', name: 'Operator', description: '', isBuiltIn: 1, createdAt: '', updatedAt: '' }, + { id: 'role-deploy', name: 'Deployer', description: '', isBuiltIn: 0, createdAt: '', updatedAt: '' }, + ]); + + // Only group-a is in the claim now (Operator stays, Deployer revoked) + await syncService.syncGroupRoles('user-1', [ + 'aaaaaaaa-1111-2222-3333-444444444444', + ]); + + expect(mockUserService.removeRoleFromUser).toHaveBeenCalledWith('user-1', 'role-deploy'); + expect(mockUserService.removeRoleFromUser).toHaveBeenCalledTimes(1); + expect(mockUserService.assignRoleToUser).not.toHaveBeenCalled(); + }); + + it('preserves roles assigned independently of the mapping (manually assigned)', async () => { + createSyncService({ + 'aaaaaaaa-1111-2222-3333-444444444444': 'Operator', + }); + // User has Viewer (manual) and Administrator (manual) — neither in mapping + mockUserService.getUserRoles.mockResolvedValue([ + { id: 'role-viewer', name: 'Viewer', description: '', isBuiltIn: 1, createdAt: '', updatedAt: '' }, + { id: 'role-admin', name: 'Administrator', description: '', isBuiltIn: 1, createdAt: '', updatedAt: '' }, + ]); + + // No groups match the mapping + await syncService.syncGroupRoles('user-1', []); + + // Should NOT remove Viewer or Administrator (they are not managed by this mapping) + expect(mockUserService.removeRoleFromUser).not.toHaveBeenCalled(); + expect(mockUserService.assignRoleToUser).not.toHaveBeenCalled(); + }); + + it('logs warning and skips mapping entry when role does not exist in Pabawi', async () => { + createSyncService({ + 'aaaaaaaa-1111-2222-3333-444444444444': 'NonExistentRole', + 'bbbbbbbb-1111-2222-3333-444444444444': 'Operator', + }); + mockUserService.getUserRoles.mockResolvedValue([]); + + await syncService.syncGroupRoles('user-1', [ + 'aaaaaaaa-1111-2222-3333-444444444444', + 'bbbbbbbb-1111-2222-3333-444444444444', + ]); + + // Should log warning about NonExistentRole + expect(logger.warn).toHaveBeenCalledWith( + expect.stringContaining('NonExistentRole'), + expect.objectContaining({ component: 'EntraIdService' }), + ); + // Should still assign the valid Operator role + expect(mockUserService.assignRoleToUser).toHaveBeenCalledWith('user-1', 'role-operator'); + expect(mockUserService.assignRoleToUser).toHaveBeenCalledTimes(1); + }); + + it('does not assign roles the user already has', async () => { + createSyncService({ + 'aaaaaaaa-1111-2222-3333-444444444444': 'Operator', + }); + // User already has Operator + mockUserService.getUserRoles.mockResolvedValue([ + { id: 'role-operator', name: 'Operator', description: '', isBuiltIn: 1, createdAt: '', updatedAt: '' }, + ]); + + await syncService.syncGroupRoles('user-1', [ + 'aaaaaaaa-1111-2222-3333-444444444444', + ]); + + expect(mockUserService.assignRoleToUser).not.toHaveBeenCalled(); + expect(mockUserService.removeRoleFromUser).not.toHaveBeenCalled(); + }); + + it('handles empty groups claim by revoking all mapped roles', async () => { + createSyncService({ + 'aaaaaaaa-1111-2222-3333-444444444444': 'Operator', + 'bbbbbbbb-1111-2222-3333-444444444444': 'Deployer', + }); + // User has both mapped roles + mockUserService.getUserRoles.mockResolvedValue([ + { id: 'role-operator', name: 'Operator', description: '', isBuiltIn: 1, createdAt: '', updatedAt: '' }, + { id: 'role-deploy', name: 'Deployer', description: '', isBuiltIn: 0, createdAt: '', updatedAt: '' }, + { id: 'role-viewer', name: 'Viewer', description: '', isBuiltIn: 1, createdAt: '', updatedAt: '' }, + ]); + + // Empty groups array — all mapped roles should be revoked, Viewer preserved + await syncService.syncGroupRoles('user-1', []); + + expect(mockUserService.removeRoleFromUser).toHaveBeenCalledWith('user-1', 'role-operator'); + expect(mockUserService.removeRoleFromUser).toHaveBeenCalledWith('user-1', 'role-deploy'); + expect(mockUserService.removeRoleFromUser).toHaveBeenCalledTimes(2); + // Viewer not touched + expect(mockUserService.assignRoleToUser).not.toHaveBeenCalled(); + }); + + it('logs sync completion with counts', async () => { + createSyncService({ + 'aaaaaaaa-1111-2222-3333-444444444444': 'Operator', + }); + mockUserService.getUserRoles.mockResolvedValue([]); + + await syncService.syncGroupRoles('user-1', [ + 'aaaaaaaa-1111-2222-3333-444444444444', + ]); + + expect(logger.info).toHaveBeenCalledWith( + 'Group-to-role sync completed', + expect.objectContaining({ + component: 'EntraIdService', + operation: 'syncGroupRoles', + metadata: expect.objectContaining({ + userId: 'user-1', + assigned: 1, + revoked: 0, + groupCount: 1, + }), + }), + ); + }); + + it('continues gracefully when assignRoleToUser throws (race condition)', async () => { + createSyncService({ + 'aaaaaaaa-1111-2222-3333-444444444444': 'Operator', + 'bbbbbbbb-1111-2222-3333-444444444444': 'Deployer', + }); + mockUserService.getUserRoles.mockResolvedValue([]); + mockUserService.assignRoleToUser + .mockRejectedValueOnce(new Error('Role is already assigned to this user')) + .mockResolvedValueOnce(undefined); + + // Should not throw — the error is swallowed with a log + await expect(syncService.syncGroupRoles('user-1', [ + 'aaaaaaaa-1111-2222-3333-444444444444', + 'bbbbbbbb-1111-2222-3333-444444444444', + ])).resolves.toBeUndefined(); + + expect(logger.warn).toHaveBeenCalledWith( + expect.stringContaining('Failed to assign role'), + expect.any(Object), + ); + }); + }); +}); diff --git a/docs/api.md b/docs/api.md index 44c07d5f..54052dca 100644 --- a/docs/api.md +++ b/docs/api.md @@ -583,8 +583,44 @@ Require `AUTH_ENABLED=true`. All endpoints require JWT auth and appropriate RBAC | Method | Endpoint | Description | |---|---|---| | `POST` | `/api/auth/login` | Login (returns JWT) | -| `POST` | `/api/auth/logout` | Logout | +| `POST` | `/api/auth/logout` | Logout (includes `entraIdLogoutUrl` for SSO sessions) | | `GET` | `/api/auth/me` | Current user info | +| `GET` | `/api/auth/providers` | Available auth methods (public, no auth required) | + +### Azure Entra ID SSO + +Available when `ENTRA_ID_ENABLED=true`. Returns 404 otherwise. + +| Method | Endpoint | Description | +|---|---|---| +| `GET` | `/api/auth/entra-id/login` | Redirects (302) to Microsoft login | +| `GET` | `/api/auth/entra-id/callback` | OAuth callback — exchanges code, redirects to frontend | +| `POST` | `/api/auth/entra-id/token` | Exchange single-use auth code for JWT pair | + +**`GET /api/auth/providers` response:** + +```json +{ + "local": true, + "entraId": { "enabled": true, "name": "Microsoft Entra ID" } +} +``` + +**`POST /api/auth/entra-id/token` request:** + +```json +{ "code": "" } +``` + +**`POST /api/auth/entra-id/token` response:** + +```json +{ + "token": "", + "refreshToken": "", + "user": { "id": "...", "username": "...", "email": "..." } +} +``` --- diff --git a/docs/architecture.md b/docs/architecture.md index 0b12a974..d484955e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -155,6 +155,7 @@ backend/src/ │ ├── CommandWhitelistService.ts security: allowed commands │ ├── DatabaseService.ts SQLite, migrations │ ├── AuthenticationService.ts JWT auth +│ ├── EntraIdService.ts Azure Entra ID SSO (OIDC, PKCE, user provisioning) │ ├── BatchExecutionService.ts multi-node execution │ ├── UserService.ts │ ├── RoleService.ts @@ -181,6 +182,7 @@ frontend/src/ └── lib/ ├── router.svelte.ts client-side router (Svelte 5 runes) ├── auth.svelte.ts JWT auth state + ├── entraIdAuth.svelte.ts Entra ID SSO state (provider discovery, callback handling) ├── api.ts HTTP infrastructure (get, post, put, del, error handling) ├── proxmoxApi.ts Proxmox provisioning API functions ├── awsApi.ts AWS EC2 API functions @@ -208,6 +210,7 @@ Schema is managed by sequential migration files in `database/migrations/`. A mig - **Command whitelisting** — `CommandWhitelistService` validates every command before execution. Set `COMMAND_WHITELIST_ALLOW_ALL=false` in production. - **JWT authentication** — all API routes behind auth middleware when `AUTH_ENABLED=true`. +- **Azure Entra ID SSO** — optional federated authentication via OpenID Connect (OAuth 2.0 Authorization Code + PKCE). Coexists with local auth. See [integrations/entra-id.md](integrations/entra-id.md). - **RBAC** — role-based access control via `UserService`, `RoleService`, `PermissionService`. See [permissions-rbac.md](./permissions-rbac.md). - **Rate limiting** — applied at middleware level. - **Security headers** — helmet middleware. diff --git a/docs/configuration.md b/docs/configuration.md index 4cf06ceb..ea57d5f1 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -73,6 +73,24 @@ DATABASE_URL=postgres://pabawi:pabawi@postgres:5432/pabawi | `JWT_SECRET` | **required** | Secret key for JWT token signing. Must be ≥ 32 chars of random entropy and not a placeholder (e.g. `your-secure-random-secret-here`, `change-me`). Generate with `openssl rand -base64 32`. The server refuses to start otherwise. Tokens are issued/verified with `iss=pabawi` / `aud=pabawi`. | | `PABAWI_LIFECYCLE_TOKEN` | _(empty)_ | Bearer token required for inventory lifecycle endpoints (`POST /api/nodes/:id/action`, `DELETE /api/inventory/:id`). When unset, those endpoints return 500 (`LIFECYCLE_AUTH_MISCONFIGURED`). | +### Azure Entra ID SSO + +Optional federated authentication via OpenID Connect. When enabled, the login page shows "Sign in with Microsoft" alongside local login. See [integrations/entra-id.md](./integrations/entra-id.md) for Azure portal setup. + +| Variable | Default | Description | +|---|---|---| +| `ENTRA_ID_ENABLED` | `false` | Set to `"true"` to enable Entra ID SSO. All other `ENTRA_ID_*` vars are ignored unless this is `"true"`. | +| `ENTRA_ID_TENANT_ID` | **required** | Azure tenant (directory) ID | +| `ENTRA_ID_CLIENT_ID` | **required** | Application (client) ID from the app registration | +| `ENTRA_ID_CLIENT_SECRET` | **required** | Client secret value | +| `ENTRA_ID_REDIRECT_URI` | **required** | OAuth callback URL (must match Azure app registration). Format: `https://your-host/api/auth/entra-id/callback` | +| `ENTRA_ID_SCOPES` | `openid,profile,email` | Comma-separated OAuth scopes. Empty entries are discarded. | +| `ENTRA_ID_GROUP_MAPPING` | _(none)_ | JSON object mapping Azure group IDs to Pabawi role names. Example: `{"uuid-1":"administrator","uuid-2":"operator"}` | +| `ENTRA_ID_POST_LOGOUT_REDIRECT_URI` | _(app base URL)_ | Where Microsoft redirects after SSO logout | +| `ENTRA_ID_JWKS_CACHE_TTL_MS` | `86400000` | How long to cache JWKS signing keys (ms). Default: 24 hours. | + +When `ENTRA_ID_ENABLED=true`, all four required variables must be set or the server refuses to start with a validation error listing the missing ones. + ## Bolt | Variable | Default | Description | diff --git a/docs/integrations/entra-id.md b/docs/integrations/entra-id.md new file mode 100644 index 00000000..1ce205f2 --- /dev/null +++ b/docs/integrations/entra-id.md @@ -0,0 +1,149 @@ +# Azure Entra ID Authentication + +Pabawi supports Azure Entra ID (formerly Azure AD) as a federated authentication provider via OpenID Connect. Users authenticate through their organization's Azure tenant and are automatically provisioned on first login. Group memberships can be mapped to Pabawi roles for centralized access control. + +## Prerequisites + +- Azure Entra ID tenant +- App registration in the Azure portal with: + - A client secret + - Redirect URI configured (e.g. `https://pabawi.example.com/api/auth/entra-id/callback`) + - `openid`, `profile`, and `email` permissions granted +- (Optional) Group claims configured in the token if using group-to-role mapping + +## Configuration + +```bash +ENTRA_ID_ENABLED=true +ENTRA_ID_TENANT_ID=12345678-abcd-efgh-ijkl-123456789012 +ENTRA_ID_CLIENT_ID=abcdef01-2345-6789-abcd-ef0123456789 +ENTRA_ID_CLIENT_SECRET=your-client-secret-value +ENTRA_ID_REDIRECT_URI=https://pabawi.example.com/api/auth/entra-id/callback + +# Optional +# ENTRA_ID_SCOPES=openid,profile,email +# ENTRA_ID_GROUP_MAPPING={"group-uuid-1":"administrator","group-uuid-2":"operator"} +# ENTRA_ID_POST_LOGOUT_REDIRECT_URI=https://pabawi.example.com +# ENTRA_ID_JWKS_CACHE_TTL_MS=86400000 +``` + +See [configuration.md](../configuration.md#azure-entra-id-sso) for the full variable reference. + +## Azure Portal Setup + +### 1. Register an Application + +1. Go to **Azure Portal → Microsoft Entra ID → App registrations → New registration** +2. Name: e.g. "Pabawi SSO" +3. Supported account types: "Accounts in this organizational directory only" (single tenant) +4. Redirect URI: Web → `https://your-pabawi-host/api/auth/entra-id/callback` +5. Click **Register** + +### 2. Configure Client Secret + +1. In the app registration → **Certificates & secrets → New client secret** +2. Set a description and expiry +3. Copy the **Value** (shown only once) → use as `ENTRA_ID_CLIENT_SECRET` + +### 3. Configure API Permissions + +1. Go to **API permissions → Add a permission → Microsoft Graph → Delegated permissions** +2. Add: `openid`, `profile`, `email` +3. If using group-to-role mapping, also add `GroupMember.Read.All` (requires admin consent) +4. Click **Grant admin consent** + +### 4. Configure Token Claims (Optional) + +For group-to-role mapping: + +1. Go to **Token configuration → Add groups claim** +2. Select "Security groups" and/or "All groups" +3. Under "ID token", ensure "Group ID" is selected + +### 5. Note Required Values + +From the app registration's **Overview** page: + +- **Application (client) ID** → `ENTRA_ID_CLIENT_ID` +- **Directory (tenant) ID** → `ENTRA_ID_TENANT_ID` + +## Authentication Flow + +``` +User → "Sign in with Microsoft" → Pabawi backend → 302 redirect to Microsoft login +Microsoft login → user authenticates → callback to Pabawi with authorization code +Pabawi → exchanges code for ID token → validates token → provisions user → issues Pabawi JWT +``` + +The flow uses OAuth 2.0 Authorization Code with PKCE (S256). State, nonce, and code verifier are stored server-side with a 10-minute TTL. + +## User Provisioning + +On first SSO login: + +1. If a Pabawi user with the same email already exists, the Entra ID identity is **linked** to that account. The existing password remains valid for local login. +2. If no matching user exists, a new account is created with: + - Username derived from `preferred_username` or email local-part + - No password (federation-only — cannot use local login) + - Default viewer role assigned + - Active status + +On subsequent logins, the existing account is used without modifying stored profile data. + +## Group-to-Role Mapping + +Map Azure group object IDs to Pabawi role names: + +```bash +ENTRA_ID_GROUP_MAPPING={"e5f3a1b2-...":"administrator","c7d8e9f0-...":"operator"} +``` + +Behavior: + +- Groups present in the token claim → corresponding Pabawi roles are assigned +- Groups removed since last login → corresponding mapped roles are revoked +- Roles assigned outside the mapping (manually) → preserved unchanged +- Mapping references a non-existent Pabawi role → warning logged, entry skipped +- No `groups` claim in token → no role changes made + +Group IDs are matched case-insensitively (UUIDs). + +## Logout + +When a user who authenticated via Entra ID logs out: + +1. Pabawi revokes the access and refresh tokens +2. The logout response includes an `entraIdLogoutUrl` +3. The frontend redirects to that URL for single sign-out at Microsoft +4. After Microsoft logout, the browser redirects to `ENTRA_ID_POST_LOGOUT_REDIRECT_URI` + +## Coexistence with Local Auth + +Both authentication methods work simultaneously: + +- The login page shows "Sign in with Microsoft" alongside the local login form +- Users with linked accounts can use either method +- Federation-only users (no password) must use SSO +- JWT tokens are identical regardless of auth method — middleware sees no difference + +## Security + +- PKCE (S256) on every authorization request +- State and nonce validated on every callback +- ID token signatures verified against JWKS keys (cached 24h by default) +- Single-use authorization codes (60s TTL) for frontend token delivery +- Clock skew tolerance: 5 minutes for token expiry +- Client secret, authorization codes, and tokens are never logged + +## Troubleshooting + +| Symptom | Cause | Fix | +|---|---|---| +| 404 on `/api/auth/entra-id/login` | `ENTRA_ID_ENABLED` not set to `"true"` | Check `.env` value is exactly `true` | +| `INVALID_STATE` on callback | State expired (>10 min) or browser cookies issue | Retry login; check server clock | +| `TOKEN_EXCHANGE_FAILED` | Network issue or invalid client secret | Verify `ENTRA_ID_CLIENT_SECRET`; check connectivity to `login.microsoftonline.com` | +| `INVALID_ID_TOKEN` | Tenant/client ID mismatch or clock skew | Verify `ENTRA_ID_TENANT_ID` and `ENTRA_ID_CLIENT_ID` match the app registration | +| `MISSING_CLAIMS` | App registration missing `email` or `profile` scope | Add permissions in Azure portal and grant admin consent | +| `JWKS_UNAVAILABLE` | Cannot reach Microsoft's key endpoint | Check outbound HTTPS; keys are cached so transient failures are tolerated | +| Group roles not syncing | No `groups` claim in token | Configure group claims in Token configuration (Azure portal) | +| Config validation error at startup | Missing required variables | Set all of: `TENANT_ID`, `CLIENT_ID`, `CLIENT_SECRET`, `REDIRECT_URI` | diff --git a/docs/permissions-rbac.md b/docs/permissions-rbac.md index 899b7d76..82d2f37a 100644 --- a/docs/permissions-rbac.md +++ b/docs/permissions-rbac.md @@ -2,6 +2,27 @@ Pabawi uses Role-Based Access Control (RBAC) when `AUTH_ENABLED=true`. Users are assigned roles. Roles contain permissions. Permissions gate specific actions. +## Authentication Methods + +Pabawi supports two authentication methods that can work simultaneously: + +- **Local authentication** — username/password login, always available +- **Azure Entra ID SSO** — federated login via OpenID Connect (optional, see [integrations/entra-id.md](./integrations/entra-id.md)) + +Both methods issue identical Pabawi JWT tokens. The RBAC middleware makes no distinction between authentication origins — permissions are determined by the user's assigned roles regardless of how they logged in. + +### Federated Users + +Users who authenticate via Entra ID for the first time are automatically provisioned: + +- If a local user with the same email exists, the Entra ID identity is linked to that account +- Otherwise, a new account is created with federation-only access (no local password) +- The default viewer role is assigned to new federated users + +### Group-to-Role Mapping + +When `ENTRA_ID_GROUP_MAPPING` is configured, Pabawi synchronizes roles at each SSO login based on the user's Azure group memberships. Manually assigned roles are preserved. See [integrations/entra-id.md](./integrations/entra-id.md#group-to-role-mapping) for details. + ## Permission Format ``` diff --git a/frontend/src/components/EntraIdLoginButton.svelte b/frontend/src/components/EntraIdLoginButton.svelte new file mode 100644 index 00000000..6ae22e11 --- /dev/null +++ b/frontend/src/components/EntraIdLoginButton.svelte @@ -0,0 +1,32 @@ + + + diff --git a/frontend/src/components/EntraIdLoginButton.test.ts b/frontend/src/components/EntraIdLoginButton.test.ts new file mode 100644 index 00000000..d7bd8ab4 --- /dev/null +++ b/frontend/src/components/EntraIdLoginButton.test.ts @@ -0,0 +1,68 @@ +import { describe, it, expect, beforeEach, afterEach } from 'vitest'; +import { render, screen, fireEvent } from '@testing-library/svelte'; +import EntraIdLoginButton from './EntraIdLoginButton.svelte'; + +describe('EntraIdLoginButton', () => { + let originalLocation: Location; + + beforeEach(() => { + originalLocation = window.location; + Object.defineProperty(window, 'location', { + writable: true, + value: { ...originalLocation, href: '' }, + }); + }); + + afterEach(() => { + Object.defineProperty(window, 'location', { + writable: true, + value: originalLocation, + }); + }); + + it('renders with Microsoft logo SVG', () => { + render(EntraIdLoginButton); + + const svg = document.querySelector('svg'); + expect(svg).not.toBeNull(); + expect(svg?.getAttribute('aria-hidden')).toBe('true'); + // Microsoft logo has 4 colored rectangles + const rects = svg?.querySelectorAll('rect'); + expect(rects?.length).toBe(4); + }); + + it('renders default "Sign in with Microsoft" text', () => { + render(EntraIdLoginButton); + + expect(screen.getByText('Sign in with Microsoft')).toBeTruthy(); + }); + + it('renders custom provider name when passed', () => { + render(EntraIdLoginButton, { props: { providerName: 'Contoso' } }); + + expect(screen.getByText('Sign in with Contoso')).toBeTruthy(); + }); + + it('has correct aria-label with default provider name', () => { + render(EntraIdLoginButton); + + const button = screen.getByRole('button'); + expect(button.getAttribute('aria-label')).toBe('Sign in with Microsoft'); + }); + + it('has correct aria-label with custom provider name', () => { + render(EntraIdLoginButton, { props: { providerName: 'Contoso' } }); + + const button = screen.getByRole('button'); + expect(button.getAttribute('aria-label')).toBe('Sign in with Contoso'); + }); + + it('redirects to /api/auth/entra-id/login on click', async () => { + render(EntraIdLoginButton); + + const button = screen.getByRole('button'); + await fireEvent.click(button); + + expect(window.location.href).toBe('/api/auth/entra-id/login'); + }); +}); diff --git a/frontend/src/lib/auth.svelte.ts b/frontend/src/lib/auth.svelte.ts index b9cce630..85b7c6b5 100644 --- a/frontend/src/lib/auth.svelte.ts +++ b/frontend/src/lib/auth.svelte.ts @@ -160,19 +160,23 @@ class AuthManager { } /** - * Logout and clear all auth data - * Requirement: 1.6, 6.4 + * Logout and clear all auth data. + * If the session was established via Entra ID, the backend returns an + * `entraIdLogoutUrl` — redirect the browser there for single sign-out. + * Requirement: 1.6, 6.4, 8.4 */ async logout(): Promise { logger.info('Auth', 'logout', 'Logging out user', { userId: this._user?.id, }); + let entraIdLogoutUrl: string | undefined; + // Call logout endpoint to revoke tokens — pass both access + refresh so // the backend can revoke them as a pair (C1 refresh-token rotation). if (this._token) { try { - await fetch(`${API_BASE_URL}/auth/logout`, { + const response = await fetch(`${API_BASE_URL}/auth/logout`, { method: 'POST', headers: { 'Authorization': `Bearer ${this._token}`, @@ -182,6 +186,11 @@ class AuthManager { ? JSON.stringify({ refreshToken: this._refreshToken }) : undefined, }); + + if (response.ok) { + const data = await response.json() as { entraIdLogoutUrl?: string }; + entraIdLogoutUrl = data.entraIdLogoutUrl; + } } catch (error) { logger.warn('Auth', 'logout', 'Logout API call failed', { error: error instanceof Error ? error.message : 'Unknown error', @@ -192,6 +201,13 @@ class AuthManager { this.clearAuthData(); + // Redirect to Entra ID end-session endpoint for SSO single sign-out + if (entraIdLogoutUrl) { + logger.info('Auth', 'logout', 'Redirecting to Entra ID logout'); + window.location.href = entraIdLogoutUrl; + return; + } + logger.info('Auth', 'logout', 'Logout complete'); } @@ -272,6 +288,14 @@ class AuthManager { this._error = null; } + /** + * Set auth data from an external SSO flow (Entra ID token exchange). + * Public wrapper around setAuthData for use by entraIdAuth module. + */ + setAuthDataFromSso(data: AuthResponse): void { + this.setAuthData(data); + } + // Private methods private setAuthData(data: AuthResponse): void { diff --git a/frontend/src/lib/entraIdAuth.svelte.test.ts b/frontend/src/lib/entraIdAuth.svelte.test.ts new file mode 100644 index 00000000..9527577c --- /dev/null +++ b/frontend/src/lib/entraIdAuth.svelte.test.ts @@ -0,0 +1,180 @@ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'; + +// Mock the api module before importing the module under test +vi.mock('./api', () => ({ + get: vi.fn(), + post: vi.fn(), +})); + +// Mock the auth module +vi.mock('./auth.svelte', () => ({ + authManager: { + setAuthDataFromSso: vi.fn(), + isAuthenticated: false, + }, +})); + +// Mock the router module +vi.mock('./router.svelte', () => ({ + router: { + navigate: vi.fn(), + }, +})); + +// Mock the toast module +vi.mock('./toast.svelte', () => ({ + showError: vi.fn(), +})); + +import * as api from './api'; +import { authManager } from './auth.svelte'; +import { router } from './router.svelte'; +import { entraIdAuth } from './entraIdAuth.svelte'; + +describe('EntraIdAuthStore', () => { + beforeEach(() => { + vi.clearAllMocks(); + // Reset store state between tests + entraIdAuth.isEntraIdEnabled = false; + entraIdAuth.entraIdProviderName = 'Microsoft Entra ID'; + entraIdAuth.providerDiscoveryError = false; + entraIdAuth.isExchangingCode = false; + entraIdAuth.exchangeError = null; + }); + + afterEach(() => { + vi.restoreAllMocks(); + }); + + describe('discoverProviders', () => { + it('sets isEntraIdEnabled to true when API returns entraId enabled', async () => { + vi.mocked(api.get).mockResolvedValue({ + local: true, + entraId: { enabled: true, name: 'Contoso SSO' }, + }); + + await entraIdAuth.discoverProviders(); + + expect(entraIdAuth.isEntraIdEnabled).toBe(true); + expect(entraIdAuth.entraIdProviderName).toBe('Contoso SSO'); + expect(entraIdAuth.providerDiscoveryError).toBe(false); + }); + + it('sets isEntraIdEnabled to false when entraId is not in response', async () => { + vi.mocked(api.get).mockResolvedValue({ local: true }); + + await entraIdAuth.discoverProviders(); + + expect(entraIdAuth.isEntraIdEnabled).toBe(false); + expect(entraIdAuth.providerDiscoveryError).toBe(false); + }); + + it('sets providerDiscoveryError on timeout/failure', async () => { + vi.mocked(api.get).mockRejectedValue(new Error('Request timed out')); + + await entraIdAuth.discoverProviders(); + + expect(entraIdAuth.providerDiscoveryError).toBe(true); + expect(entraIdAuth.isEntraIdEnabled).toBe(false); + }); + + it('calls /api/auth/providers with 5s timeout', async () => { + vi.mocked(api.get).mockResolvedValue({ local: true }); + + await entraIdAuth.discoverProviders(); + + expect(api.get).toHaveBeenCalledWith('/api/auth/providers', { + timeout: 5000, + maxRetries: 0, + showRetryNotifications: false, + }); + }); + }); + + describe('handleSsoCallback', () => { + let originalLocation: Location; + + beforeEach(() => { + originalLocation = window.location; + Object.defineProperty(window, 'location', { + writable: true, + value: { + ...originalLocation, + search: '', + pathname: '/login', + }, + }); + + // Mock window.history.replaceState + vi.spyOn(window.history, 'replaceState').mockImplementation(() => {}); + }); + + afterEach(() => { + Object.defineProperty(window, 'location', { + writable: true, + value: originalLocation, + }); + }); + + it('returns false when no code in URL', async () => { + window.location.search = ''; + + const result = await entraIdAuth.handleSsoCallback(); + + expect(result).toBe(false); + expect(api.post).not.toHaveBeenCalled(); + }); + + it('posts code and stores tokens on success', async () => { + window.location.search = '?code=test-auth-code'; + + const mockResponse = { + token: 'access-token-123', + refreshToken: 'refresh-token-456', + user: { id: '1', username: 'testuser', email: 'test@example.com' }, + }; + vi.mocked(api.post).mockResolvedValue(mockResponse); + + const result = await entraIdAuth.handleSsoCallback(); + + expect(result).toBe(true); + expect(api.post).toHaveBeenCalledWith( + '/api/auth/entra-id/token', + { code: 'test-auth-code' }, + { maxRetries: 0, showRetryNotifications: false }, + ); + expect(authManager.setAuthDataFromSso).toHaveBeenCalledWith(mockResponse); + expect(router.navigate).toHaveBeenCalledWith('/'); + }); + + it('sets exchangeError on token exchange failure', async () => { + window.location.search = '?code=invalid-code'; + vi.mocked(api.post).mockRejectedValue(new Error('Token exchange failed')); + + const result = await entraIdAuth.handleSsoCallback(); + + expect(result).toBe(false); + expect(entraIdAuth.exchangeError).toBe('Token exchange failed'); + }); + + it('cleans the URL after successful exchange', async () => { + window.location.search = '?code=test-code'; + vi.mocked(api.post).mockResolvedValue({ + token: 'tok', refreshToken: 'ref', user: {}, + }); + + await entraIdAuth.handleSsoCallback(); + + expect(window.history.replaceState).toHaveBeenCalledWith({}, '', '/login'); + }); + + it('cleans the URL after failed exchange', async () => { + window.location.search = '?code=bad-code'; + vi.mocked(api.post).mockRejectedValue(new Error('failed')); + + await entraIdAuth.handleSsoCallback(); + + expect(window.history.replaceState).toHaveBeenCalledWith({}, '', '/login'); + }); + }); +}); diff --git a/frontend/src/lib/entraIdAuth.svelte.ts b/frontend/src/lib/entraIdAuth.svelte.ts new file mode 100644 index 00000000..fd114310 --- /dev/null +++ b/frontend/src/lib/entraIdAuth.svelte.ts @@ -0,0 +1,127 @@ +/** + * Entra ID (Azure AD) authentication state management using Svelte 5 runes + * + * Handles: + * - Provider discovery via /api/auth/providers + * - SSO callback code extraction and token exchange + * - Error state for discovery and token exchange failures + * + * Requirements: 10.1, 10.2, 10.5, 10.6, 10.7 + */ + +import { get, post } from './api'; +import { authManager } from './auth.svelte'; +import type { AuthResponse } from './auth.svelte'; +import { router } from './router.svelte'; +import { showError } from './toast.svelte'; + +const PROVIDER_DISCOVERY_TIMEOUT_MS = 5000; + +interface ProvidersResponse { + local: boolean; + entraId?: { + enabled: boolean; + name: string; + }; +} + +class EntraIdAuthStore { + isEntraIdEnabled = $state(false); + entraIdProviderName = $state('Microsoft Entra ID'); + providerDiscoveryError = $state(false); + isDiscovering = $state(false); + isExchangingCode = $state(false); + exchangeError = $state(null); + + /** + * Discover available authentication providers. + * Calls GET /api/auth/providers with a 5s timeout. + * On failure or timeout, sets providerDiscoveryError = true and + * leaves isEntraIdEnabled = false (show only local login). + * + * Requirement: 10.1, 10.2, 10.7 + */ + async discoverProviders(): Promise { + this.isDiscovering = true; + this.providerDiscoveryError = false; + + try { + const response = await get('/api/auth/providers', { + timeout: PROVIDER_DISCOVERY_TIMEOUT_MS, + maxRetries: 0, + showRetryNotifications: false, + }); + + if (response.entraId?.enabled) { + this.isEntraIdEnabled = true; + this.entraIdProviderName = response.entraId.name || 'Microsoft Entra ID'; + } else { + this.isEntraIdEnabled = false; + } + } catch { + this.providerDiscoveryError = true; + this.isEntraIdEnabled = false; + } finally { + this.isDiscovering = false; + } + } + + /** + * Handle the SSO callback redirect. + * Extracts `code` from the current URL query parameters, POSTs it to + * /api/auth/entra-id/token, stores tokens in auth state, and navigates + * to the landing page. + * + * Returns true if a code was present and exchange was attempted, + * false if no code was found (not a callback). + * + * Requirement: 10.5, 10.6 + */ + async handleSsoCallback(): Promise { + const params = new URLSearchParams(window.location.search); + const code = params.get('code'); + + if (!code) { + return false; + } + + this.isExchangingCode = true; + this.exchangeError = null; + + try { + const response = await post('/api/auth/entra-id/token', { code }, { + maxRetries: 0, + showRetryNotifications: false, + }); + + // Store tokens in auth state using the same method as local login + authManager.setAuthDataFromSso(response); + + // Clean the URL (remove ?code= parameter) and navigate to landing page + window.history.replaceState({}, '', window.location.pathname); + router.navigate('/'); + + return true; + } catch (error) { + const message = error instanceof Error ? error.message : 'SSO authentication failed'; + this.exchangeError = message; + showError('SSO authentication failed', message); + + // Clean the URL to remove the code parameter but stay on login page + window.history.replaceState({}, '', window.location.pathname); + + return false; + } finally { + this.isExchangingCode = false; + } + } + + /** + * Clear exchange error state + */ + clearExchangeError(): void { + this.exchangeError = null; + } +} + +export const entraIdAuth = new EntraIdAuthStore(); diff --git a/frontend/src/pages/LoginPage.svelte b/frontend/src/pages/LoginPage.svelte index 63878a95..7f058f55 100644 --- a/frontend/src/pages/LoginPage.svelte +++ b/frontend/src/pages/LoginPage.svelte @@ -2,9 +2,10 @@ import { authManager } from '../lib/auth.svelte'; import { router } from '../lib/router.svelte'; import { showError, showSuccess } from '../lib/toast.svelte'; + import { entraIdAuth } from '../lib/entraIdAuth.svelte'; import LoadingSpinner from '../components/LoadingSpinner.svelte'; + import EntraIdLoginButton from '../components/EntraIdLoginButton.svelte'; import { get } from '../lib/api'; - import { onMount } from 'svelte'; let username = $state(''); let password = $state(''); // pragma: allowlist secret @@ -12,6 +13,7 @@ let validationErrors = $state<{ username?: string; password?: string }>({}); let selfRegistrationAllowed = $state(false); let checkingConfig = $state(true); + let initialized = false; // Redirect if already authenticated $effect(() => { @@ -20,18 +22,38 @@ } }); - // Check if self-registration is allowed - onMount(async () => { + // On mount: check for SSO callback code, then discover providers and config + $effect(() => { + if (initialized) return; + initialized = true; + void initializeLoginPage(); + }); + + async function initializeLoginPage(): Promise { + // First, check if this is an SSO callback with ?code= parameter + const handled = await entraIdAuth.handleSsoCallback(); + if (handled) { + // Callback was handled (code was exchanged or failed) — don't proceed with discovery + return; + } + + // Discover available auth providers and check self-registration in parallel + await Promise.all([ + entraIdAuth.discoverProviders(), + checkSelfRegistration(), + ]); + } + + async function checkSelfRegistration(): Promise { try { const status = await get<{ config: { allowSelfRegistration: boolean } | null }>('/api/setup/status'); selfRegistrationAllowed = status.config?.allowSelfRegistration ?? false; - } catch (error) { - console.error('Failed to check self-registration status:', error); + } catch { selfRegistrationAllowed = false; } finally { checkingConfig = false; } - }); + } function validateForm(): boolean { const errors: { username?: string; password?: string } = {}; @@ -66,7 +88,6 @@ if (success) { showSuccess('Login successful', `Welcome back, ${username}!`); - // Redirect to intended path or home router.navigateToIntendedOrDefault('/'); } else { showError('Login failed', authManager.error?.message || 'Invalid credentials'); @@ -98,57 +119,18 @@

-
-
- -
- - - {#if validationErrors.username} -

- {validationErrors.username} -

- {/if} -
- - -
- - - {#if validationErrors.password} -

- {validationErrors.password} -

- {/if} -
+ + {#if entraIdAuth.isExchangingCode} +
+ +

+ Completing sign-in... +

- - {#if authManager.error} + + {:else if entraIdAuth.exchangeError} +
@@ -157,47 +139,171 @@
-

- {authManager.error.message} +

+ SSO authentication failed +

+

+ {entraIdAuth.exchangeError}

- {/if} - - -
- + + + {#if entraIdAuth.isEntraIdEnabled} + +
+
+
+
+
+ or +
+
+ {/if}
- - {#if !checkingConfig && selfRegistrationAllowed} -
-

- Don't have an account? - -

+ {:else} + +
+ + {#if entraIdAuth.isEntraIdEnabled} + + + +
+
+
+
+
+ or +
+
+ {/if} + + + {#if entraIdAuth.providerDiscoveryError} +
+
+
+ + + +
+
+

+ SSO availability could not be determined. You can still sign in with your local credentials. +

+
+
+
+ {/if} +
+ {/if} + + + {#if !entraIdAuth.isExchangingCode} + +
+ +
+ + + {#if validationErrors.username} +

+ {validationErrors.username} +

+ {/if} +
+ + +
+ + + {#if validationErrors.password} +

+ {validationErrors.password} +

+ {/if} +
+
+ + + {#if authManager.error} +
+
+
+ + + +
+
+

+ {authManager.error.message} +

+
+
+
+ {/if} + + +
+
- {/if} - + + + {#if !checkingConfig && selfRegistrationAllowed} +
+

+ Don't have an account? + +

+
+ {/if} + + {/if}
diff --git a/frontend/src/pages/LoginPage.test.ts b/frontend/src/pages/LoginPage.test.ts new file mode 100644 index 00000000..d976f047 --- /dev/null +++ b/frontend/src/pages/LoginPage.test.ts @@ -0,0 +1,161 @@ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'; +import { render, screen } from '@testing-library/svelte'; + +vi.mock('../lib/entraIdAuth.svelte', () => ({ + entraIdAuth: { + isEntraIdEnabled: false, + entraIdProviderName: 'Microsoft Entra ID', + providerDiscoveryError: false, + isExchangingCode: false, + exchangeError: null as string | null, + isDiscovering: false, + discoverProviders: vi.fn().mockResolvedValue(undefined), + handleSsoCallback: vi.fn().mockResolvedValue(false), + clearExchangeError: vi.fn(), + }, +})); + +vi.mock('../lib/auth.svelte', () => ({ + authManager: { + isAuthenticated: false, + error: null, + login: vi.fn().mockResolvedValue(false), + clearError: vi.fn(), + }, +})); + +vi.mock('../lib/router.svelte', () => ({ + router: { + navigate: vi.fn(), + navigateToIntendedOrDefault: vi.fn(), + }, +})); + +vi.mock('../lib/toast.svelte', () => ({ + showError: vi.fn(), + showSuccess: vi.fn(), +})); + +vi.mock('../lib/api', () => ({ + get: vi.fn().mockResolvedValue({ config: null }), + post: vi.fn(), + getErrorGuidance: vi.fn(() => ({ guidance: undefined })), +})); + +import LoginPage from './LoginPage.svelte'; +import { entraIdAuth } from '../lib/entraIdAuth.svelte'; + +describe('LoginPage', () => { + beforeEach(() => { + vi.clearAllMocks(); + // Reset mock state + entraIdAuth.isEntraIdEnabled = false; + entraIdAuth.entraIdProviderName = 'Microsoft Entra ID'; + entraIdAuth.providerDiscoveryError = false; + entraIdAuth.isExchangingCode = false; + entraIdAuth.exchangeError = null; + vi.mocked(entraIdAuth.handleSsoCallback).mockResolvedValue(false); + vi.mocked(entraIdAuth.discoverProviders).mockResolvedValue(undefined); + }); + + afterEach(() => { + vi.restoreAllMocks(); + }); + + describe('SSO button conditional rendering', () => { + it('shows SSO button when entraIdAuth.isEntraIdEnabled is true', () => { + entraIdAuth.isEntraIdEnabled = true; + + render(LoginPage); + + expect(screen.getByRole('button', { name: /sign in with microsoft/i })).toBeTruthy(); + }); + + it('hides SSO button when entraIdAuth.isEntraIdEnabled is false', () => { + entraIdAuth.isEntraIdEnabled = false; + + render(LoginPage); + + expect(screen.queryByRole('button', { name: /sign in with microsoft/i })).toBeNull(); + }); + }); + + describe('Provider discovery error', () => { + it('shows warning when providerDiscoveryError is true', () => { + entraIdAuth.providerDiscoveryError = true; + + render(LoginPage); + + expect(screen.getByText(/SSO availability could not be determined/)).toBeTruthy(); + }); + + it('does not show warning when providerDiscoveryError is false', () => { + entraIdAuth.providerDiscoveryError = false; + + render(LoginPage); + + expect(screen.queryByText(/SSO availability could not be determined/)).toBeNull(); + }); + }); + + describe('SSO code exchange in progress', () => { + it('shows "Completing sign-in..." when isExchangingCode is true', () => { + entraIdAuth.isExchangingCode = true; + + render(LoginPage); + + expect(screen.getByText('Completing sign-in...')).toBeTruthy(); + }); + + it('hides local login form when isExchangingCode is true', () => { + entraIdAuth.isExchangingCode = true; + + render(LoginPage); + + expect(screen.queryByLabelText('Username')).toBeNull(); + }); + }); + + describe('Token exchange error', () => { + it('shows error message when exchangeError is set', () => { + entraIdAuth.exchangeError = 'Token exchange failed'; + + render(LoginPage); + + expect(screen.getByText('SSO authentication failed')).toBeTruthy(); + expect(screen.getByText('Token exchange failed')).toBeTruthy(); + }); + + it('shows SSO button below error when entraId is enabled', () => { + entraIdAuth.exchangeError = 'Something went wrong'; + entraIdAuth.isEntraIdEnabled = true; + + render(LoginPage); + + expect(screen.getByText('SSO authentication failed')).toBeTruthy(); + expect(screen.getByRole('button', { name: /sign in with microsoft/i })).toBeTruthy(); + }); + }); + + describe('Local login form always present', () => { + it('shows local login form when SSO is disabled', () => { + entraIdAuth.isEntraIdEnabled = false; + + render(LoginPage); + + expect(screen.getByLabelText('Username')).toBeTruthy(); + expect(screen.getByLabelText('Password')).toBeTruthy(); + expect(screen.getByRole('button', { name: /sign in$/i })).toBeTruthy(); + }); + + it('shows both SSO button and local login form when SSO is enabled', () => { + entraIdAuth.isEntraIdEnabled = true; + + render(LoginPage); + + expect(screen.getByRole('button', { name: /sign in with microsoft/i })).toBeTruthy(); + expect(screen.getByLabelText('Username')).toBeTruthy(); + expect(screen.getByLabelText('Password')).toBeTruthy(); + }); + }); +}); diff --git a/scripts/setup.sh b/scripts/setup.sh index 5826c7d5..04e978e6 100755 --- a/scripts/setup.sh +++ b/scripts/setup.sh @@ -388,6 +388,38 @@ if [[ "$SKIP_ENV" != "true" ]]; then ask AZURE_RESOURCE_GROUPS "Azure Resource Groups (comma-separated, leave empty for all)" "" fi + # ── Azure Entra ID SSO ─────────────────────────────────────────────── + ask_yn ENTRA_ID_ENABLED "Enable Azure Entra ID SSO (Sign in with Microsoft)?" "n" + ENTRA_ID_TENANT_ID="" + ENTRA_ID_CLIENT_ID="" + ENTRA_ID_CLIENT_SECRET="" + ENTRA_ID_REDIRECT_URI="" + ENTRA_ID_SCOPES="" + ENTRA_ID_GROUP_MAPPING="" + ENTRA_ID_POST_LOGOUT_REDIRECT_URI="" + if [[ "$ENTRA_ID_ENABLED" == "true" ]]; then + ask ENTRA_ID_TENANT_ID "Entra ID Tenant (Directory) ID" "" + while [[ -z "$ENTRA_ID_TENANT_ID" ]]; do + error "Tenant ID is required when Entra ID SSO is enabled." + ask ENTRA_ID_TENANT_ID "Entra ID Tenant (Directory) ID" "" + done + ask ENTRA_ID_CLIENT_ID "Entra ID Application (Client) ID" "" + while [[ -z "$ENTRA_ID_CLIENT_ID" ]]; do + error "Client ID is required when Entra ID SSO is enabled." + ask ENTRA_ID_CLIENT_ID "Entra ID Application (Client) ID" "" + done + ask ENTRA_ID_CLIENT_SECRET "Entra ID Client Secret" "" + while [[ -z "$ENTRA_ID_CLIENT_SECRET" ]]; do + error "Client Secret is required when Entra ID SSO is enabled." + ask ENTRA_ID_CLIENT_SECRET "Entra ID Client Secret" "" + done + local default_redirect="http://localhost:3000/api/auth/entra-id/callback" + ask ENTRA_ID_REDIRECT_URI "OAuth Redirect URI" "$default_redirect" + ask ENTRA_ID_SCOPES "OAuth Scopes (comma-separated, leave empty for default)" "" + ask ENTRA_ID_GROUP_MAPPING "Group-to-role mapping JSON (leave empty to skip)" "" + ask ENTRA_ID_POST_LOGOUT_REDIRECT_URI "Post-logout redirect URI (leave empty for app base URL)" "" + fi + # ── Puppet Node SSL Certificates ──────────────────────────────────────── PUPPET_NODE_CERTS_WRITE="false" PUPPET_NODE_SSL_CA="" @@ -537,6 +569,21 @@ EOF [[ -n "$AZURE_RESOURCE_GROUPS" ]] && echo "AZURE_RESOURCE_GROUPS=${AZURE_RESOURCE_GROUPS}" >> "$ENV_FILE" fi + if [[ "$ENTRA_ID_ENABLED" == "true" ]]; then + cat >> "$ENV_FILE" <> "$ENV_FILE" + [[ -n "$ENTRA_ID_GROUP_MAPPING" ]] && echo "ENTRA_ID_GROUP_MAPPING=${ENTRA_ID_GROUP_MAPPING}" >> "$ENV_FILE" + [[ -n "$ENTRA_ID_POST_LOGOUT_REDIRECT_URI" ]] && echo "ENTRA_ID_POST_LOGOUT_REDIRECT_URI=${ENTRA_ID_POST_LOGOUT_REDIRECT_URI}" >> "$ENV_FILE" + fi + if [[ "$PUPPET_NODE_CERTS_WRITE" == "true" ]]; then cat >> "$ENV_FILE" < Date: Wed, 10 Jun 2026 14:04:28 +0200 Subject: [PATCH 02/13] chore(release): bump version to 1.5.0 - Update Docker image version labels in Dockerfile, Dockerfile.alpine, and Dockerfile.ubuntu - Bump backend package.json version from 1.4.0 to 1.5.0 - Update backend API server version in health check endpoint - Bump frontend package.json version from 1.4.0 to 1.5.0 - Update Navigation component to display v1.5.0.alpha - Bump Helm chart appVersion from 1.4.0 to 1.5.0 - Update root package.json version from 1.4.0 to 1.5.0 --- Dockerfile | 2 +- Dockerfile.alpine | 2 +- Dockerfile.ubuntu | 2 +- backend/package.json | 2 +- backend/src/server.ts | 2 +- charts/pabawi/Chart.yaml | 2 +- frontend/package.json | 2 +- frontend/src/components/Navigation.svelte | 2 +- package.json | 2 +- 9 files changed, 9 insertions(+), 9 deletions(-) diff --git a/Dockerfile b/Dockerfile index 75614e35..f36891d3 100644 --- a/Dockerfile +++ b/Dockerfile @@ -67,7 +67,7 @@ ARG BUILDPLATFORM # Add metadata labels LABEL org.opencontainers.image.title="Pabawi" LABEL org.opencontainers.image.description="Puppet Ansible Bolt Awesome Web Interface" -LABEL org.opencontainers.image.version="1.4.0" +LABEL org.opencontainers.image.version="1.5.0" LABEL org.opencontainers.image.vendor="example42" LABEL org.opencontainers.image.source="https://github.com/example42/pabawi" diff --git a/Dockerfile.alpine b/Dockerfile.alpine index 979d54a5..0af49180 100644 --- a/Dockerfile.alpine +++ b/Dockerfile.alpine @@ -62,7 +62,7 @@ ARG BUILDPLATFORM # Add metadata labels LABEL org.opencontainers.image.title="Pabawi" LABEL org.opencontainers.image.description="Puppet Ansible Bolt Awesome Web Interface" -LABEL org.opencontainers.image.version="1.4.0" +LABEL org.opencontainers.image.version="1.5.0" LABEL org.opencontainers.image.vendor="example42" LABEL org.opencontainers.image.source="https://github.com/example42/pabawi" diff --git a/Dockerfile.ubuntu b/Dockerfile.ubuntu index ea441fac..c67cc218 100644 --- a/Dockerfile.ubuntu +++ b/Dockerfile.ubuntu @@ -66,7 +66,7 @@ ARG BUILDPLATFORM # Add metadata labels LABEL org.opencontainers.image.title="Pabawi" LABEL org.opencontainers.image.description="Puppet Ansible Bolt Awesome Web Interface" -LABEL org.opencontainers.image.version="1.4.0" +LABEL org.opencontainers.image.version="1.5.0" LABEL org.opencontainers.image.vendor="example42" LABEL org.opencontainers.image.source="https://github.com/example42/pabawi" diff --git a/backend/package.json b/backend/package.json index 4d295c43..140d6721 100644 --- a/backend/package.json +++ b/backend/package.json @@ -1,6 +1,6 @@ { "name": "backend", - "version": "1.4.0", + "version": "1.5.0", "description": "Backend API server for Pabawi", "main": "dist/server.js", "scripts": { diff --git a/backend/src/server.ts b/backend/src/server.ts index cd44504a..81a95654 100644 --- a/backend/src/server.ts +++ b/backend/src/server.ts @@ -564,7 +564,7 @@ async function startServer(): Promise { res.status(overall === "ok" ? 200 : 503).json({ status: overall, message: "Backend API is running", - version: "1.4.0", + version: "1.5.0", checks: { database: dbError ? { status: dbStatus, error: dbError } : { status: dbStatus }, }, diff --git a/charts/pabawi/Chart.yaml b/charts/pabawi/Chart.yaml index 306dc728..93f2fa17 100644 --- a/charts/pabawi/Chart.yaml +++ b/charts/pabawi/Chart.yaml @@ -3,7 +3,7 @@ name: pabawi description: Pabawi infrastructure management web UI type: application version: 0.1.0 -appVersion: "1.4.0" +appVersion: "1.5.0" home: https://github.com/example42/pabawi sources: - https://github.com/example42/pabawi diff --git a/frontend/package.json b/frontend/package.json index c87e638d..0929d630 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -1,6 +1,6 @@ { "name": "frontend", - "version": "1.4.0", + "version": "1.5.0", "description": "Pabawi frontend web interface", "type": "module", "scripts": { diff --git a/frontend/src/components/Navigation.svelte b/frontend/src/components/Navigation.svelte index 4b7bc0d7..34fa346d 100644 --- a/frontend/src/components/Navigation.svelte +++ b/frontend/src/components/Navigation.svelte @@ -143,7 +143,7 @@

Pabawi

- v1.4.0 + v1.5.0.alpha
diff --git a/package.json b/package.json index d7ffd952..9ecfd1f4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "pabawi", - "version": "1.4.0", + "version": "1.5.0", "description": "Pabawi - Web interface for Bolt automation tool", "private": true, "workspaces": [ From c622278fa0c687675cd8bffb03cae25a4de42655 Mon Sep 17 00:00:00 2001 From: Alessandro Franceschi Date: Thu, 11 Jun 2026 16:11:46 +0200 Subject: [PATCH 03/13] docs: add upgrade guide and update documentation for v1.5.0 - Add comprehensive upgrading.md guide covering Git, Docker, Docker Compose, and Kubernetes deployment methods - Document database backup requirements and migration behavior before upgrading - Update README with inline upgrading section and link to full upgrade guide - Add upgrading link to README documentation navigation - Update CHANGELOG to reflect v1.5.0 release with v1.4.0 dated as 2026-06-05 - Clarify "classic infrastructure" description to include Kubernetes nodes - Remove roadmap section and replace version history with CHANGELOG reference - Consolidate upgrade instructions across all deployment methods with clear step-by-step procedures --- CHANGELOG.md | 5 +- README.md | 45 ++-- docs/upgrading.md | 236 ++++++++++++++++++ .../src/pages/IntegrationConfigPage.svelte | 69 +++++ 4 files changed, 329 insertions(+), 26 deletions(-) create mode 100644 docs/upgrading.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 90b2deef..cedc4857 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,9 @@ # Changelog -## [1.4.0] - Unreleased +## [1.5.0] - + + +## [1.4.0] - 2026-06-05 ### Added diff --git a/README.md b/README.md index 65c7ec5f..3003b072 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ - **Mixed-tool environments** — if you use both Puppet and Ansible, Pabawi brings them together in one interface - **Homelabbers** who just want a web frontend for their servers (SSH-only works fine) -If you manage "classic infrastructure" — bare metal, VMs, not Kubernetes — Pabawi is built for you. +If you manage "classic infrastructure" — bare metal, VMs, Kubernetes nodes — Pabawi is built for you. ## Table of Contents @@ -43,6 +43,7 @@ If you manage "classic infrastructure" — bare metal, VMs, not Kubernetes — P - [Quick Start](#quick-start) - [Manual Setup](#manual-setup) - [Docker](#docker) +- [Upgrading](#upgrading) - [Configuration](#configuration) - [Project Structure](#project-structure) - [Troubleshooting](#troubleshooting) @@ -154,6 +155,21 @@ The application starts at . For full Docker and Kubernetes deployment instructions, see the [Docker Deployment Guide](docs/deployment/docker.md) and [Kubernetes Guide](docs/deployment/kubernetes.md). +## Upgrading + +For existing installations, the upgrade path depends on your deployment method: + +| Method | Command | +|---|---| +| Git / source | `git fetch --tags && git checkout v && npm run install:all && npm run build` | +| Docker | `docker pull example42/pabawi:latest` then recreate the container | +| Docker Compose | `docker compose pull && docker compose up -d` | +| Helm / Kubernetes | `helm upgrade pabawi ./charts/pabawi --set image.tag=` | + +Database migrations run automatically on startup. Always back up your database and review the [CHANGELOG](CHANGELOG.md) for breaking changes before upgrading. + +Full instructions: [Upgrade Guide](docs/upgrading.md). + ## Configuration All configuration is in `backend/.env`. The setup script generates this file, or use `backend/.env.example` as a template. @@ -217,32 +233,11 @@ See the [Troubleshooting Guide](docs/troubleshooting.md) for common issues with See the [Development Guide](docs/development.md) for setup, testing, and contribution guidelines. -## Roadmap - -### Planned integrations - -- **Icinga / CheckMK** — monitoring context in the same interface -- **Terraform / OpenTofu** — infrastructure provisioning alongside configuration management - -### Also planned - -Scheduled executions, custom dashboards, CLI tool, audit logging, Tiny Puppet integration. ### Version History -- **v1.2.0**: Embedded MCP server with 8 read-only tools, RBAC permission gaps fixed, CreateRoleDialog, new Azure/Hiera/SSH permissions -- **v1.1.0**: Azure integration, Global Journal with cross-node timeline, security hardening, docs rewrite -- **v1.0.0**: Configuration refactor (`.env` as single source of truth), Proxmox and AWS provisioning, Node Journal, setup wizard `.env` snippet generators, Integration Status Dashboard -- **v0.10.0**: AWS EC2 integration, integration configuration management -- **v0.9.0**: Proxmox integration, Node Journal -- **v0.8.0**: RBAC authentication, SSH integration, inventory groups -- **v0.7.0**: Ansible integration, class-aware Hiera lookups -- **v0.6.0**: Code consolidation and fixes -- **v0.5.0**: Report filtering, Puppet run history visualization, enhanced expert mode -- **v0.4.0**: Hiera integration, enhanced plugin architecture -- **v0.3.0**: Puppetserver integration, interface enhancements -- **v0.2.0**: PuppetDB integration, re-execution, expert mode -- **v0.1.0**: Initial release with Bolt integration +See [CHANGELOG](CHANGELOG.md). + ## License @@ -253,7 +248,7 @@ Apache License 2.0 — see [LICENSE](LICENSE). **Documentation** - [Architecture](docs/architecture.md) | [Configuration](docs/configuration.md) | [User Guide](docs/user-guide.md) | [API Reference](docs/api.md) -- [Permissions & RBAC](docs/permissions-rbac.md) | [MCP Server](docs/mcp.md) | [Troubleshooting](docs/troubleshooting.md) | [Development](docs/development.md) +- [Permissions & RBAC](docs/permissions-rbac.md) | [MCP Server](docs/mcp.md) | [Upgrading](docs/upgrading.md) | [Troubleshooting](docs/troubleshooting.md) | [Development](docs/development.md) **Integrations** diff --git a/docs/upgrading.md b/docs/upgrading.md new file mode 100644 index 00000000..73cd1557 --- /dev/null +++ b/docs/upgrading.md @@ -0,0 +1,236 @@ +# Upgrading Pabawi + +This guide covers upgrading existing Pabawi installations. For fresh installs, +see the main [README](../README.md#installation). + +## Before You Upgrade + +1. **Read the [CHANGELOG](../CHANGELOG.md)** for the target version. Look for + sections labelled "Security — breaking for operators" or "Action required + before upgrade" — these require configuration changes before starting the + new version. +2. **Back up your database.** SQLite: copy the `.db` file. PostgreSQL: run + `pg_dump`. +3. **Back up your `.env` file.** Some releases add required variables or change + defaults. + +Database migrations run automatically on startup. They are forward-only — there +is no built-in rollback. The backup is your rollback path. + +## Upgrade Methods + +- [Git / source install](#git--source-install) +- [Docker (standalone)](#docker-standalone) +- [Docker Compose](#docker-compose) +- [Kubernetes / Helm](#kubernetes--helm) + +--- + +## Git / Source Install + +For installations cloned from the repository and built locally. + +```bash +cd /path/to/pabawi + +# 1. Stop the running server +# (Ctrl-C if running in foreground, or stop your process manager) + +# 2. Pull the latest release +git fetch --tags +git checkout v # e.g. v1.4.0 +# or, to track the latest on main: +# git pull origin main + +# 3. Install / rebuild dependencies +npm run install:all + +# 4. Review .env changes +diff backend/.env.example backend/.env +# Add any new required variables shown in the CHANGELOG + +# 5. Build +npm run build + +# 6. Start +npm run dev:fullstack # development +# or your production process manager (systemd, pm2, etc.) +``` + +### Pinning to a release tag vs. tracking main + +Release tags (`v1.4.0`, `v1.3.1`, etc.) are stable cut points. Tracking `main` +gives you the latest commits but may include incomplete work between releases. +For production, pin to tags. + +--- + +## Docker (Standalone) + +```bash +# 1. Pull the new image +docker pull example42/pabawi:latest +# or a specific version: +# docker pull example42/pabawi:1.4.0 + +# 2. Stop and remove the old container +docker stop pabawi +docker rm pabawi + +# 3. Review .env for new required variables (check CHANGELOG) + +# 4. Start the new container with the same volumes and env +docker run -d \ + --name pabawi \ + --user "$(id -u):1001" \ + -p 127.0.0.1:3000:3000 \ + -v "$(pwd)/data:/opt/pabawi/data" \ + -v "$(pwd)/bolt-project:/opt/pabawi/bolt-project:ro" \ + --env-file .env \ + example42/pabawi:latest +``` + +Your data persists in the mounted volumes. The new container applies any +pending database migrations on startup. + +### Rollback + +If the new version fails to start: + +```bash +docker stop pabawi && docker rm pabawi +# Restore the database backup, then start the previous image: +docker run -d --name pabawi ... example42/pabawi: +``` + +--- + +## Docker Compose + +```bash +cd /path/to/pabawi # directory containing docker-compose.yml + +# 1. Pull the latest image +docker compose pull + +# 2. Review .env for new required variables + +# 3. Recreate the container +docker compose up -d + +# 4. Verify +docker compose logs -f app +curl http://localhost:3000/api/health +``` + +`docker compose up -d` recreates only containers whose image or config changed. +Volumes are preserved. + +### With PostgreSQL profile + +```bash +docker compose --profile postgres pull +docker compose --profile postgres up -d +``` + +### Pinning a version + +Edit `docker-compose.yml` (or use an override file) to pin the image tag: + +```yaml +services: + app: + image: example42/pabawi:1.4.0 +``` + +--- + +## Kubernetes / Helm + +```bash +# 1. Update the chart (if using a local copy) +cd charts/pabawi +git pull # or copy the updated chart + +# 2. Review values changes +helm diff upgrade pabawi ./charts/pabawi -f my-values.yaml +# (requires the helm-diff plugin; otherwise compare values.yaml manually) + +# 3. Upgrade +helm upgrade pabawi ./charts/pabawi \ + -f my-values.yaml \ + --set image.tag=1.4.0 + +# 4. Watch the rollout +kubectl rollout status deployment/pabawi +kubectl logs -l app.kubernetes.io/name=pabawi -f +``` + +If the chart includes a database migration Job, it runs before the new +Deployment pods start. Monitor the Job: + +```bash +kubectl get jobs -l app.kubernetes.io/component=migration +kubectl logs job/pabawi-migrate +``` + +### Rollback + +```bash +helm rollback pabawi +# Restore the database from backup if migrations are not backward-compatible +``` + +--- + +## Version-Specific Notes + +### Upgrading to 1.3.0 + +**Action required before starting the new version:** + +- `JWT_SECRET` must be ≥ 32 characters and not a placeholder value. The app + refuses to boot otherwise. Generate a proper secret: + + ```bash + JWT_SECRET=$(openssl rand -base64 32) + ``` + +- `DELETE /api/inventory/:id` now requires the lifecycle bearer token. If you + have scripts calling this endpoint, add + `Authorization: Bearer `. + +- SSE `?token=` URL parameter removed. Clients must use the stream-ticket + endpoint (`POST /api/executions/:id/stream-ticket`) instead. + +- Refresh-token rotation enforced. Clients must store and use the latest + `refreshToken` from each refresh response. + +### Upgrading to 1.3.0 with PostgreSQL + +If switching from SQLite to PostgreSQL during this upgrade: + +1. Set `DB_TYPE=postgres` and `DATABASE_URL` in `.env`. +2. The new schema is created automatically on first startup. There is no + automated SQLite-to-PostgreSQL data migration — export and re-import + manually if you need to preserve execution history or user accounts. + +### Upgrading to 1.4.0 + +New optional integration: **Checkmk monitoring**. No action required unless you +want to enable it. Add `CHECKMK_ENABLED=true` and the related variables to +`.env`. See [docs/integrations/checkmk.md](integrations/checkmk.md). + +--- + +## General Tips + +- **Health check:** After every upgrade, verify `curl http://localhost:3000/api/health` + returns `{"status":"ok"}` with HTTP 200. +- **Expert mode:** Enable expert mode in the UI after upgrading to see full + debug output if something looks wrong. +- **Logs:** Check logs immediately after startup. Failed migrations or missing + config surface within the first few seconds. +- **Permissions:** If new RBAC permissions were added in the release, built-in + roles (Viewer, Operator, Administrator) are updated automatically via + migration. Custom roles may need manual permission grants. diff --git a/frontend/src/pages/IntegrationConfigPage.svelte b/frontend/src/pages/IntegrationConfigPage.svelte index d3303ca5..02b015ab 100644 --- a/frontend/src/pages/IntegrationConfigPage.svelte +++ b/frontend/src/pages/IntegrationConfigPage.svelte @@ -29,17 +29,33 @@ const INTEGRATION_ICONS: Record = { proxmox: 'M5 12h14M5 12a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v4a2 2 0 01-2 2M5 12a2 2 0 00-2 2v4a2 2 0 002 2h14a2 2 0 002-2v-4a2 2 0 00-2-2', aws: 'M3 15a4 4 0 004 4h9a5 5 0 10-.1-9.999 5.002 5.002 0 10-9.78 2.096A4.001 4.001 0 003 15z', + azure: 'M3 15a4 4 0 004 4h9a5 5 0 10-.1-9.999 5.002 5.002 0 10-9.78 2.096A4.001 4.001 0 003 15z', puppetdb: 'M4 7v10c0 2.21 3.582 4 8 4s8-1.79 8-4V7M4 7c0 2.21 3.582 4 8 4s8-1.79 8-4M4 7c0-2.21 3.582-4 8-4s8 1.79 8 4', puppetserver: 'M9.75 17L9 20l-1 1h8l-1-1-.75-3M3 13h18M5 17h14a2 2 0 002-2V5a2 2 0 00-2-2H5a2 2 0 00-2 2v10a2 2 0 002 2z', ansible: 'M8 9l3 3-3 3m5 0h3M5 20h14a2 2 0 002-2V6a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z', hiera: 'M3 7v10a2 2 0 002 2h14a2 2 0 002-2V9a2 2 0 00-2-2h-6l-2-2H5a2 2 0 00-2 2z', ssh: 'M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z', bolt: 'M13 10V3L4 14h7v7l9-11h-7z', + checkmk: 'M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z', }; /** Integrations that support "Test Connection" */ const TESTABLE_INTEGRATIONS = ['proxmox', 'aws']; + /** All integrations that have setup guide pages */ + const ALL_SETUP_GUIDES: { type: string; label: string }[] = [ + { type: 'bolt', label: 'Puppet Bolt' }, + { type: 'puppetdb', label: 'PuppetDB' }, + { type: 'puppetserver', label: 'Puppet Server' }, + { type: 'hiera', label: 'Hiera' }, + { type: 'ansible', label: 'Ansible' }, + { type: 'ssh', label: 'SSH' }, + { type: 'proxmox', label: 'Proxmox' }, + { type: 'aws', label: 'AWS' }, + { type: 'azure', label: 'Azure' }, + { type: 'checkmk', label: 'Checkmk' }, + ]; + // State let integrations = $state([]); let loading = $state(true); @@ -124,6 +140,17 @@ return TESTABLE_INTEGRATIONS.includes(type) && integration.status !== 'not_configured'; } + /** Get setup guide URL for an integration type */ + function getSetupUrl(type: string): string { + return `/integrations/${type}/setup`; + } + + /** Check if an integration has a setup guide */ + function hasSetupGuide(integration: IntegrationStatus): boolean { + const type = integration.type || integration.name.toLowerCase(); + return ALL_SETUP_GUIDES.some(g => g.type === type); + } + /** Test connection for an integration */ async function handleTestConnection(integration: IntegrationStatus): Promise { const key = integration.name; @@ -248,6 +275,20 @@
+ + {#if hasSetupGuide(integration)} + { e.preventDefault(); router.navigate(getSetupUrl(integration.type || integration.name.toLowerCase())); }} + class="inline-flex items-center gap-1.5 text-sm text-primary-600 hover:text-primary-800 dark:text-primary-400 dark:hover:text-primary-200" + > + + + + Setup Guide + + {/if} + {#if isTestable(integration)}
+ + +
+

Integrations Setup guides

+

+ Click to view setup instructions for any integration. +

+
+ {#each ALL_SETUP_GUIDES as guide (guide.type)} + { e.preventDefault(); router.navigate(getSetupUrl(guide.type)); }} + class="flex items-center gap-3 rounded-lg border border-gray-200 bg-white p-4 hover:border-primary-300 hover:bg-primary-50 dark:border-gray-700 dark:bg-gray-800 dark:hover:border-primary-600 dark:hover:bg-primary-900/10 transition-colors" + > + + + +
+ {guide.label} +

View setup instructions

+
+ + + + + {/each} +
+
{/if} From e52abe8054d69b4713681a43eccde23bc2faaaab Mon Sep 17 00:00:00 2001 From: Alessandro Franceschi Date: Thu, 11 Jun 2026 17:23:36 +0200 Subject: [PATCH 04/13] chore(specs): organize and archive completed feature specifications - Add console-integration specification with design, requirements, and task documentation - Archive 70+ completed specifications to done directory including: * Puppet and PuppetDB integration specs * Release and testing documentation * RBAC authorization and SSH integration specs * Azure and Checkmk integration specs * Code review fixes and journal enhancements * Node groups, parallel execution, and Proxmox integration specs - Reorganize specification structure to separate active work from completed milestones - Improve project documentation organization for future reference and auditing --- .kiro/specs/console-integration/.config.kiro | 1 + .kiro/specs/console-integration/design.md | 586 ++++++++++++++++++ .../specs/console-integration/requirements.md | 178 ++++++ .kiro/specs/console-integration/tasks.md | 234 +++++++ .../070/hiera-codebase-integration/design.md | 0 .../requirements.md | 0 .../070/hiera-codebase-integration/tasks.md | 0 .../MANUAL_TESTING_COMPLETE.md | 0 .../pabawi-v0.5.0-release/TESTING_INDEX.md | 0 .../pabawi-v0.5.0-release/TESTING_README.md | 0 .../cache-issue-resolution.md | 0 .../code-consolidation-guide.md | 0 .../070/pabawi-v0.5.0-release/design.md | 0 .../expert-mode-coverage-checklist.md | 0 .../expert-mode-test-results.txt | 0 .../logging-expert-mode-audit.md | 0 .../logging-expert-mode-pattern.md | 0 .../logging-integration-summary.md | 0 .../manual-test-expert-mode.sh | 0 .../manual-testing-guide.md | 0 .../manual-testing-implementation-summary.md | 0 .../manual-testing-quick-reference.md | 0 .../migration-example.md | 0 .../070/pabawi-v0.5.0-release/requirements.md | 0 .../routes-refactoring-completion.md | 0 .../routes-refactoring-implementation.md | 0 .../routes-refactoring-plan.md | 0 .../task-10.5-completion-summary.md | 0 .../pabawi-v0.5.0-release/task-5.7-summary.md | 0 .../task-6.5.4-completion-report.md | 0 .../task-6.5.4-executions-completion.md | 0 .../task-6.5.4-summary.md | 0 .../task-6.5.4.1-facts-completion.md | 0 .../task-6.5.4.1-node-certname-completion.md | 0 .../task-6.5.4.1-verification-complete.md | 0 .../task-node-reports-completion.md | 0 .../070/pabawi-v0.5.0-release/tasks.md | 0 .../test-single-route.sh | 0 .../testing-checklist.md | 0 .../testing-flow-diagram.md | 0 .../testing-troubleshooting.md | 0 .../unified-logging-implementation.md | 0 .../070/pabawi/IMPLEMENTATION_STATUS.md | 0 .kiro/specs/{ => done}/070/pabawi/design.md | 0 .../{ => done}/070/pabawi/requirements.md | 0 .kiro/specs/{ => done}/070/pabawi/tasks.md | 0 .../requirements.md | 0 .../070/puppet-reports-pagination/design.md | 0 .../phase-4-audit-report.md | 0 .../phase-5-audit-report.md | 0 .../puppet-reports-pagination/requirements.md | 0 .../070/puppet-reports-pagination/tasks.md | 0 .../070/puppetdb-integration/design.md | 0 .../070/puppetdb-integration/requirements.md | 0 .../070/puppetdb-integration/tasks.md | 0 .../070/puppetserver-integration/design.md | 0 .../expert-mode-review.md | 0 .../manual-testing-guide.md | 0 .../puppetserver-integration/requirements.md | 0 .../070/puppetserver-integration/tasks.md | 0 .../090/inventory-node-groups/.config.kiro | 0 .../090/inventory-node-groups/design.md | 0 .../090/inventory-node-groups/requirements.md | 0 .../090/inventory-node-groups/tasks.md | 0 .../090/parallel-execution-ui/.config.kiro | 0 .../090/parallel-execution-ui/design.md | 0 .../090/parallel-execution-ui/requirements.md | 0 .../090/parallel-execution-ui/tasks.md | 0 .../090/proxmox-frontend-ui/.config.kiro | 0 .../090/proxmox-frontend-ui/design.md | 0 .../090/proxmox-frontend-ui/requirements.md | 0 .../090/proxmox-frontend-ui/tasks.md | 0 .../090/proxmox-integration/.config.kiro | 0 .../090/proxmox-integration/design.md | 0 .../090/proxmox-integration/requirements.md | 0 .../090/proxmox-integration/tasks.md | 0 .../puppet-pabawi-refactoring/.config.kiro | 0 .../090/puppet-pabawi-refactoring/design.md | 0 .../puppet-pabawi-refactoring/requirements.md | 0 .../090/puppet-pabawi-refactoring/tasks.md | 0 .../090/rbac-authorization/.config.kiro | 0 .../090/rbac-authorization/design.md | 0 .../090/rbac-authorization/requirements.md | 0 .../090/rbac-authorization/tasks.md | 0 .../090/ssh-integration/.config.kiro | 0 .../{ => done}/090/ssh-integration/design.md | 0 .../090/ssh-integration/requirements.md | 0 .../{ => done}/090/ssh-integration/tasks.md | 0 .../{ => done}/azure-integration/.config.kiro | 0 .../{ => done}/azure-integration/design.md | 0 .../azure-integration/requirements.md | 0 .../{ => done}/azure-integration/tasks.md | 0 .../checkmk-integration/.config.kiro | 0 .../{ => done}/checkmk-integration/design.md | 0 .../checkmk-integration/requirements.md | 0 .../{ => done}/checkmk-integration/tasks.md | 0 .../{ => done}/code-review-fixes/.config.kiro | 0 .../{ => done}/code-review-fixes/design.md | 0 .../code-review-fixes/requirements.md | 0 .../{ => done}/code-review-fixes/tasks.md | 0 .../journal-enhancements/.config.kiro | 0 .../{ => done}/journal-enhancements/design.md | 0 .../journal-enhancements/requirements.md | 0 .../{ => done}/journal-enhancements/tasks.md | 0 .../missing-lifecycle-actions/.config.kiro | 0 .../missing-lifecycle-actions/bugfix.md | 0 .../pabawi-release-1-0-0/.config.kiro | 0 .../{ => done}/pabawi-release-1-0-0/design.md | 0 .../pabawi-release-1-0-0/requirements.md | 0 .../{ => done}/pabawi-release-1-0-0/tasks.md | 0 .../rbac-and-mcp-server/.config.kiro | 0 .../{ => done}/rbac-and-mcp-server/design.md | 0 .../rbac-and-mcp-server/requirements.md | 0 .../{ => done}/rbac-and-mcp-server/tasks.md | 0 .../{ => done}/v1-release-prep/.config.kiro | 0 .../{ => done}/v1-release-prep/design.md | 0 .../v1-release-prep/requirements.md | 0 .../specs/{ => done}/v1-release-prep/tasks.md | 0 118 files changed, 999 insertions(+) create mode 100644 .kiro/specs/console-integration/.config.kiro create mode 100644 .kiro/specs/console-integration/design.md create mode 100644 .kiro/specs/console-integration/requirements.md create mode 100644 .kiro/specs/console-integration/tasks.md rename .kiro/specs/{ => done}/070/hiera-codebase-integration/design.md (100%) rename .kiro/specs/{ => done}/070/hiera-codebase-integration/requirements.md (100%) rename .kiro/specs/{ => done}/070/hiera-codebase-integration/tasks.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/MANUAL_TESTING_COMPLETE.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/TESTING_INDEX.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/TESTING_README.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/cache-issue-resolution.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/code-consolidation-guide.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/design.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/expert-mode-coverage-checklist.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/expert-mode-test-results.txt (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/logging-expert-mode-audit.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/logging-expert-mode-pattern.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/logging-integration-summary.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/manual-test-expert-mode.sh (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/manual-testing-guide.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/manual-testing-implementation-summary.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/manual-testing-quick-reference.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/migration-example.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/requirements.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/routes-refactoring-completion.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/routes-refactoring-implementation.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/routes-refactoring-plan.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/task-10.5-completion-summary.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/task-5.7-summary.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/task-6.5.4-completion-report.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/task-6.5.4-executions-completion.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/task-6.5.4-summary.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/task-6.5.4.1-facts-completion.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/task-6.5.4.1-node-certname-completion.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/task-6.5.4.1-verification-complete.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/task-node-reports-completion.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/tasks.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/test-single-route.sh (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/testing-checklist.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/testing-flow-diagram.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/testing-troubleshooting.md (100%) rename .kiro/specs/{ => done}/070/pabawi-v0.5.0-release/unified-logging-implementation.md (100%) rename .kiro/specs/{ => done}/070/pabawi/IMPLEMENTATION_STATUS.md (100%) rename .kiro/specs/{ => done}/070/pabawi/design.md (100%) rename .kiro/specs/{ => done}/070/pabawi/requirements.md (100%) rename .kiro/specs/{ => done}/070/pabawi/tasks.md (100%) rename .kiro/specs/{ => done}/070/puppet-reports-pagination-and-debug-fixes/requirements.md (100%) rename .kiro/specs/{ => done}/070/puppet-reports-pagination/design.md (100%) rename .kiro/specs/{ => done}/070/puppet-reports-pagination/phase-4-audit-report.md (100%) rename .kiro/specs/{ => done}/070/puppet-reports-pagination/phase-5-audit-report.md (100%) rename .kiro/specs/{ => done}/070/puppet-reports-pagination/requirements.md (100%) rename .kiro/specs/{ => done}/070/puppet-reports-pagination/tasks.md (100%) rename .kiro/specs/{ => done}/070/puppetdb-integration/design.md (100%) rename .kiro/specs/{ => done}/070/puppetdb-integration/requirements.md (100%) rename .kiro/specs/{ => done}/070/puppetdb-integration/tasks.md (100%) rename .kiro/specs/{ => done}/070/puppetserver-integration/design.md (100%) rename .kiro/specs/{ => done}/070/puppetserver-integration/expert-mode-review.md (100%) rename .kiro/specs/{ => done}/070/puppetserver-integration/manual-testing-guide.md (100%) rename .kiro/specs/{ => done}/070/puppetserver-integration/requirements.md (100%) rename .kiro/specs/{ => done}/070/puppetserver-integration/tasks.md (100%) rename .kiro/specs/{ => done}/090/inventory-node-groups/.config.kiro (100%) rename .kiro/specs/{ => done}/090/inventory-node-groups/design.md (100%) rename .kiro/specs/{ => done}/090/inventory-node-groups/requirements.md (100%) rename .kiro/specs/{ => done}/090/inventory-node-groups/tasks.md (100%) rename .kiro/specs/{ => done}/090/parallel-execution-ui/.config.kiro (100%) rename .kiro/specs/{ => done}/090/parallel-execution-ui/design.md (100%) rename .kiro/specs/{ => done}/090/parallel-execution-ui/requirements.md (100%) rename .kiro/specs/{ => done}/090/parallel-execution-ui/tasks.md (100%) rename .kiro/specs/{ => done}/090/proxmox-frontend-ui/.config.kiro (100%) rename .kiro/specs/{ => done}/090/proxmox-frontend-ui/design.md (100%) rename .kiro/specs/{ => done}/090/proxmox-frontend-ui/requirements.md (100%) rename .kiro/specs/{ => done}/090/proxmox-frontend-ui/tasks.md (100%) rename .kiro/specs/{ => done}/090/proxmox-integration/.config.kiro (100%) rename .kiro/specs/{ => done}/090/proxmox-integration/design.md (100%) rename .kiro/specs/{ => done}/090/proxmox-integration/requirements.md (100%) rename .kiro/specs/{ => done}/090/proxmox-integration/tasks.md (100%) rename .kiro/specs/{ => done}/090/puppet-pabawi-refactoring/.config.kiro (100%) rename .kiro/specs/{ => done}/090/puppet-pabawi-refactoring/design.md (100%) rename .kiro/specs/{ => done}/090/puppet-pabawi-refactoring/requirements.md (100%) rename .kiro/specs/{ => done}/090/puppet-pabawi-refactoring/tasks.md (100%) rename .kiro/specs/{ => done}/090/rbac-authorization/.config.kiro (100%) rename .kiro/specs/{ => done}/090/rbac-authorization/design.md (100%) rename .kiro/specs/{ => done}/090/rbac-authorization/requirements.md (100%) rename .kiro/specs/{ => done}/090/rbac-authorization/tasks.md (100%) rename .kiro/specs/{ => done}/090/ssh-integration/.config.kiro (100%) rename .kiro/specs/{ => done}/090/ssh-integration/design.md (100%) rename .kiro/specs/{ => done}/090/ssh-integration/requirements.md (100%) rename .kiro/specs/{ => done}/090/ssh-integration/tasks.md (100%) rename .kiro/specs/{ => done}/azure-integration/.config.kiro (100%) rename .kiro/specs/{ => done}/azure-integration/design.md (100%) rename .kiro/specs/{ => done}/azure-integration/requirements.md (100%) rename .kiro/specs/{ => done}/azure-integration/tasks.md (100%) rename .kiro/specs/{ => done}/checkmk-integration/.config.kiro (100%) rename .kiro/specs/{ => done}/checkmk-integration/design.md (100%) rename .kiro/specs/{ => done}/checkmk-integration/requirements.md (100%) rename .kiro/specs/{ => done}/checkmk-integration/tasks.md (100%) rename .kiro/specs/{ => done}/code-review-fixes/.config.kiro (100%) rename .kiro/specs/{ => done}/code-review-fixes/design.md (100%) rename .kiro/specs/{ => done}/code-review-fixes/requirements.md (100%) rename .kiro/specs/{ => done}/code-review-fixes/tasks.md (100%) rename .kiro/specs/{ => done}/journal-enhancements/.config.kiro (100%) rename .kiro/specs/{ => done}/journal-enhancements/design.md (100%) rename .kiro/specs/{ => done}/journal-enhancements/requirements.md (100%) rename .kiro/specs/{ => done}/journal-enhancements/tasks.md (100%) rename .kiro/specs/{ => done}/missing-lifecycle-actions/.config.kiro (100%) rename .kiro/specs/{ => done}/missing-lifecycle-actions/bugfix.md (100%) rename .kiro/specs/{ => done}/pabawi-release-1-0-0/.config.kiro (100%) rename .kiro/specs/{ => done}/pabawi-release-1-0-0/design.md (100%) rename .kiro/specs/{ => done}/pabawi-release-1-0-0/requirements.md (100%) rename .kiro/specs/{ => done}/pabawi-release-1-0-0/tasks.md (100%) rename .kiro/specs/{ => done}/rbac-and-mcp-server/.config.kiro (100%) rename .kiro/specs/{ => done}/rbac-and-mcp-server/design.md (100%) rename .kiro/specs/{ => done}/rbac-and-mcp-server/requirements.md (100%) rename .kiro/specs/{ => done}/rbac-and-mcp-server/tasks.md (100%) rename .kiro/specs/{ => done}/v1-release-prep/.config.kiro (100%) rename .kiro/specs/{ => done}/v1-release-prep/design.md (100%) rename .kiro/specs/{ => done}/v1-release-prep/requirements.md (100%) rename .kiro/specs/{ => done}/v1-release-prep/tasks.md (100%) diff --git a/.kiro/specs/console-integration/.config.kiro b/.kiro/specs/console-integration/.config.kiro new file mode 100644 index 00000000..69ea5a67 --- /dev/null +++ b/.kiro/specs/console-integration/.config.kiro @@ -0,0 +1 @@ +{"specId": "0152de7e-c322-4184-81b5-4e31c61d4cc5", "workflowType": "requirements-first", "specType": "feature"} diff --git a/.kiro/specs/console-integration/design.md b/.kiro/specs/console-integration/design.md new file mode 100644 index 00000000..3ed11447 --- /dev/null +++ b/.kiro/specs/console-integration/design.md @@ -0,0 +1,586 @@ +# Design Document: Console Integration + +## Overview + +The console integration feature introduces a `ConsolePlugin` interface into Pabawi's plugin architecture, enabling any infrastructure integration to expose remote console/terminal access (VNC, serial, SSH, SSM) to managed nodes. The system uses WebSocket proxying to relay binary VNC frames or terminal I/O between the browser and the upstream provider, with session lifecycle management, RBAC gating, and audit logging. + +The initial implementation targets Proxmox VNC consoles. The architecture is designed to accommodate future providers (AWS SSM, Azure Serial Console) without structural changes. + +### Key Design Decisions + +1. **WebSocket proxy over direct connection** — The backend mediates all console traffic. This enables session-level RBAC, audit logging, token-based access, and upstream credential isolation. The browser never connects directly to Proxmox/AWS/Azure. + +2. **Separate WebSocket server on shared HTTP server** — The `ws` library attaches to the existing Express HTTP server with path-based routing (`/ws/console/vnc`, `/ws/console/terminal`), avoiding a second port. + +3. **Session token for WebSocket auth** — JWT tokens authenticate the REST session creation, but a short-lived opaque session token authorizes the WebSocket upgrade. This decouples the WebSocket handshake (which can only pass tokens via query params) from JWT, limiting exposure. + +4. **ConsolePlugin as a third plugin interface** — Alongside `ExecutionToolPlugin` and `InformationSourcePlugin`, `ConsolePlugin` is registered in a dedicated map on `IntegrationManager`. This keeps concerns separated: console access is orthogonal to execution and information retrieval. + +5. **Provider-level VNC ticket acquisition** — The Proxmox provider acquires a time-limited VNC proxy ticket from the Proxmox API, then connects upstream using that ticket. The ticket never reaches the browser. + +## Architecture + +```mermaid +graph TB + subgraph Frontend + CV[ConsoleViewer Component] + NV[noVNC Adapter] + XT[xterm.js Adapter] + end + + subgraph Backend + CR[Console Routes] + CSM[ConsoleSessionManager] + WSP[WebSocket Proxy Server] + IM[IntegrationManager] + PCP[ProxmoxConsoleProvider] + end + + subgraph External + PAPI[Proxmox API] + PVNC[Proxmox VNC WebSocket] + end + + CV --> |REST: create/terminate session| CR + CV --> |WebSocket: data relay| WSP + NV --> CV + XT --> CV + + CR --> CSM + CR --> IM + CSM --> |session state| DB[(SQLite/Postgres)] + WSP --> |validate token| CSM + WSP --> |binary relay| PVNC + + IM --> PCP + PCP --> PAPI + PCP --> PVNC +``` + +### Console Open Flow — Sequence Diagram + +```mermaid +sequenceDiagram + participant F as Frontend + participant R as Console Routes + participant RBAC as RBAC Middleware + participant SM as SessionManager + participant IM as IntegrationManager + participant PCP as ProxmoxConsoleProvider + participant PAPI as Proxmox API + participant WSP as WebSocket Proxy + participant PVNC as Proxmox VNC WS + + F->>R: POST /api/console/sessions {nodeId, provider} + R->>RBAC: check console:access + RBAC-->>R: allowed + R->>SM: checkConcurrentLimit(userId) + SM-->>R: under limit + R->>IM: getConsoleProvider("proxmox") + IM-->>R: ProxmoxConsoleProvider + R->>PCP: createSession(nodeId, userId) + PCP->>PAPI: POST /nodes/{node}/{type}/{vmid}/vncproxy + PAPI-->>PCP: {ticket, port, upid} + PCP-->>R: ConsoleSession {sessionId, token, wsUrl} + R->>SM: storeSession(session) + SM->>DB: INSERT console_sessions + R-->>F: 201 {sessionId, token, wsUrl, transport} + + F->>WSP: WS connect /ws/console/vnc?token=xxx + WSP->>SM: validateToken(token) + SM-->>WSP: session (valid, owned by user) + WSP->>PVNC: WS connect wss://proxmox:port/?ticket=yyy + PVNC-->>WSP: connected + WSP-->>F: WS upgrade complete + + loop Binary Relay + F->>WSP: binary frame (keyboard/mouse) + WSP->>PVNC: forward unchanged + PVNC->>WSP: binary frame (screen update) + WSP->>F: forward unchanged + end + + F->>WSP: close + WSP->>PVNC: close + WSP->>SM: terminateSession(sessionId) + SM->>DB: UPDATE state = 'terminated' +``` + +## Components and Interfaces + +### ConsolePlugin Interface + +```typescript +import type { IntegrationPlugin } from "./types"; + +/** Supported transport protocols */ +type ConsoleTransport = "websocket-vnc" | "websocket-terminal"; + +/** Describes a console capability for a node */ +interface ConsoleCapability { + transport: ConsoleTransport; + displayName: string; // max 100 chars + connectionSchema: Record; +} + +/** Session state machine */ +type ConsoleSessionState = "creating" | "active" | "terminated" | "failed"; + +/** Session status returned by getSessionStatus */ +interface ConsoleSessionStatus { + state: ConsoleSessionState; + startedAt: string; // ISO 8601 + error?: string; // present when state === "failed" +} + +/** Full session object returned by createSession */ +interface ConsoleSession { + sessionId: string; + token: string; // session token for WS auth + wsUrl: string; // relative WebSocket URL + transport: ConsoleTransport; + state: ConsoleSessionState; + startedAt: string; + nodeId: string; + userId: string; + provider: string; +} + +/** Console plugin interface — third plugin type alongside execution/information */ +interface ConsolePlugin extends IntegrationPlugin { + getConsoleCapabilities(nodeId: string): Promise; + createSession(nodeId: string, userId: string): Promise; + terminateSession(sessionId: string): Promise; + getSessionStatus(sessionId: string): Promise; + getSupportedTransports(): ConsoleTransport[]; +} +``` + +### IntegrationManager Extension + +```typescript +// Added to IntegrationManager alongside executionTools and informationSources +private consoleProviders = new Map(); + +// Registration detects ConsolePlugin via type guard +private isConsolePlugin(plugin: IntegrationPlugin): plugin is ConsolePlugin { + return "getConsoleCapabilities" in plugin + && "createSession" in plugin + && "terminateSession" in plugin; +} + +// During registerPlugin: +if (this.isConsolePlugin(plugin)) { + this.consoleProviders.set(plugin.name, plugin); +} + +// New public methods: +getConsoleProvider(name: string): ConsolePlugin | null; +getAllConsoleProviders(): ConsolePlugin[]; +async getConsoleAvailability(nodeId: string): Promise; +``` + +### ConsoleSessionManager Service + +Manages session state, token generation/validation, timeout enforcement, and concurrent session limiting. + +```typescript +class ConsoleSessionManager { + constructor( + private db: DatabaseAdapter, + private config: ConsoleConfig, + private logger: LoggerService, + private auditLogger: AuditLoggingService, + ) {} + + /** Generate a cryptographically random session token (32+ bytes) */ + generateToken(): string; + + /** Store a new session and its token */ + async createSession(session: ConsoleSession): Promise; + + /** Validate token: exists, not expired (60s), owned by userId */ + async validateToken(token: string, userId: string): Promise; + + /** Mark token as used (consumed on WS upgrade) */ + async consumeToken(token: string): Promise; + + /** Record heartbeat for a session */ + async heartbeat(sessionId: string): Promise; + + /** Terminate a session and record audit */ + async terminateSession(sessionId: string, reason: string): Promise; + + /** Get count of active sessions for a user */ + async getActiveSessionCount(userId: string): Promise; + + /** Terminate all sessions for a provider (used on restart) */ + async terminateAllForProvider(provider: string): Promise; + + /** Cleanup expired sessions (called on interval) */ + async cleanupExpiredSessions(): Promise; + + /** Get session by ID */ + async getSession(sessionId: string): Promise; +} +``` + +### WebSocket Proxy Server + +```typescript +import { WebSocketServer, WebSocket } from "ws"; +import type { Server as HTTPServer } from "http"; + +class ConsoleWebSocketProxy { + private wss: WebSocketServer; + + constructor( + httpServer: HTTPServer, + private sessionManager: ConsoleSessionManager, + private config: ConsoleConfig, + private logger: LoggerService, + ) { + // Two paths: /ws/console/vnc and /ws/console/terminal + this.wss = new WebSocketServer({ noServer: true }); + + httpServer.on("upgrade", (req, socket, head) => { + // Origin validation + // Path routing + // Token extraction from query params + this.handleUpgrade(req, socket, head); + }); + } + + /** Handle VNC binary relay */ + private async handleVncConnection( + clientWs: WebSocket, + session: ConsoleSession, + upstreamUrl: string, + ): Promise; + + /** Handle terminal text/binary relay */ + private async handleTerminalConnection( + clientWs: WebSocket, + session: ConsoleSession, + upstreamUrl: string, + ): Promise; +} +``` + +### Console Route Factory + +```typescript +// backend/src/routes/console.ts +export function createConsoleRouter( + container: DIContainer, + integrationManager: IntegrationManager, + sessionManager: ConsoleSessionManager, + db: DatabaseAdapter, +): Router; +``` + +**Endpoints:** + +| Method | Path | Auth | Permission | Description | +|--------|------|------|------------|-------------| +| GET | `/api/console/availability/:nodeId` | JWT | `console:access` | Get available console options for a node | +| POST | `/api/console/sessions` | JWT | `console:access` | Create a console session | +| DELETE | `/api/console/sessions/:sessionId` | JWT | `console:access` or `console:admin` | Terminate a session | +| GET | `/api/console/sessions/:sessionId` | JWT | `console:access` | Get session status | +| POST | `/api/console/sessions/:sessionId/heartbeat` | JWT | `console:access` | Send heartbeat | + +### ProxmoxConsoleProvider + +Extends the existing `ProxmoxIntegration` class or lives as a companion that delegates to `ProxmoxService` for API calls. + +```typescript +class ProxmoxConsoleProvider implements ConsolePlugin { + constructor( + private proxmoxService: ProxmoxService, + private logger: LoggerService, + ) {} + + async getConsoleCapabilities(nodeId: string): Promise { + // Check if guest exists and is running + // Return [{transport: "websocket-vnc", displayName: "VNC Console", ...}] + } + + async createSession(nodeId: string, userId: string): Promise { + // 1. Determine guest type (qemu/lxc) from nodeId + // 2. Verify guest is running + // 3. POST /nodes/{node}/{type}/{vmid}/vncproxy → {ticket, port} + // 4. Build upstream WS URL: wss://proxmox:port/...?vncticket=xxx + // 5. Return ConsoleSession with token, wsUrl + } + + getSupportedTransports(): ConsoleTransport[] { + return ["websocket-vnc"]; + } +} +``` + +### Frontend: ConsoleViewer Component + +A single Svelte 5 component at `frontend/src/components/ConsoleViewer.svelte` that: + +1. Accepts `nodeId` and `capabilities` props +2. Renders transport-appropriate sub-component: + - noVNC canvas for `websocket-vnc` + - xterm.js terminal for `websocket-terminal` +3. Manages connection lifecycle (connect, heartbeat, disconnect) +4. Displays status indicator (`connecting` | `connected` | `disconnected`) +5. Handles error close codes (4401, 4502, 4408, 4504) with user-facing messages +6. Provides full-screen toggle +7. Uses `navigator.sendBeacon` for cleanup on page unload + +State is managed via Svelte runes (`$state`, `$effect`) inside the component. No separate `.svelte.ts` store file needed — console state is scoped to the viewer's lifecycle. + +## Data Models + +### Database Schema: `console_sessions` + +Migration file: `018_console_sessions.sql` + +```sql +CREATE TABLE console_sessions ( + id TEXT PRIMARY KEY, + user_id TEXT NOT NULL, + node_id TEXT NOT NULL, + provider TEXT NOT NULL, + transport TEXT NOT NULL, + state TEXT NOT NULL DEFAULT 'creating', + token TEXT, + token_created_at TEXT, + token_consumed INTEGER NOT NULL DEFAULT 0, + upstream_url TEXT, + started_at TEXT NOT NULL, + last_heartbeat_at TEXT, + terminated_at TEXT, + error_message TEXT, + created_at TEXT NOT NULL DEFAULT (datetime('now')), + CONSTRAINT chk_state CHECK (state IN ('creating', 'active', 'terminated', 'failed')), + CONSTRAINT chk_transport CHECK (transport IN ('websocket-vnc', 'websocket-terminal')) +); + +CREATE INDEX idx_console_sessions_user_id ON console_sessions(user_id); +CREATE INDEX idx_console_sessions_state ON console_sessions(state); +CREATE INDEX idx_console_sessions_token ON console_sessions(token); +``` + +### Console Configuration (Zod Schema Addition) + +```typescript +// Added to backend/src/config/schema.ts +export const ConsoleConfigSchema = z.object({ + sessionTimeoutMs: z.number().int().positive().default(300000), + maxSessionDuration: z.number().int().positive().default(28800000), + maxConcurrentSessions: z.number().int().min(1).default(3), + heartbeatIntervalMs: z.number().int().positive().default(30000), +}); + +export type ConsoleConfig = z.infer; +``` + +Added to `AppConfigSchema`: +```typescript +console: ConsoleConfigSchema.default({ + sessionTimeoutMs: 300000, + maxSessionDuration: 28800000, + maxConcurrentSessions: 3, + heartbeatIntervalMs: 30000, +}), +``` + +### RBAC Permissions (Migration) + +Migration file: `019_console_permissions.sql` + +```sql +INSERT INTO permissions (id, resource, action, description) +VALUES + (lower(hex(randomblob(16))), 'console', 'access', 'Access console sessions for nodes'), + (lower(hex(randomblob(16))), 'console', 'admin', 'Manage other users console sessions'); + +-- Grant console:access to operator and admin roles +INSERT INTO role_permissions (role_id, permission_id) +SELECT r.id, p.id +FROM roles r, permissions p +WHERE r.name IN ('operator', 'admin') + AND p.resource = 'console' AND p.action = 'access'; + +-- Grant console:admin to admin role only +INSERT INTO role_permissions (role_id, permission_id) +SELECT r.id, p.id +FROM roles r, permissions p +WHERE r.name = 'admin' + AND p.resource = 'console' AND p.action = 'admin'; +``` + +## Correctness Properties + +*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* + +### Property 1: Console provider registration invariant + +*For any* plugin that implements the `ConsolePlugin` interface, after registration with `IntegrationManager`, it SHALL appear in the console providers map and be retrievable by name. + +**Validates: Requirements 1.4** + +### Property 2: Session token validation correctness + +*For any* session token, the WebSocket validation function SHALL accept the token if and only if: it exists in the database, was created less than 60 seconds ago, has not been consumed, and the connecting user matches the session owner. All other tokens SHALL be rejected with close code 4401. + +**Validates: Requirements 4.2, 4.3, 5.2, 5.3, 8.1, 8.2** + +### Property 3: Binary frame relay integrity + +*For any* binary data frame sent through the VNC WebSocket proxy in either direction, the frame SHALL arrive at the other end byte-for-byte identical to what was sent. + +**Validates: Requirements 4.4** + +### Property 4: Terminal resize dimension validation + +*For any* resize control message, the system SHALL propagate the resize if columns are in [1, 500] and rows are in [1, 200]. For any values outside these ranges, the message SHALL be discarded without terminating the session. + +**Validates: Requirements 5.5, 5.8** + +### Property 5: RBAC enforcement for session creation + +*For any* user requesting console session creation, the system SHALL allow the request if and only if the user holds the `console:access` permission. Users without this permission SHALL receive a 403 response. + +**Validates: Requirements 6.2, 6.3** + +### Property 6: RBAC enforcement for cross-user termination + +*For any* user attempting to terminate a console session they do not own, the system SHALL allow the operation if and only if the user holds the `console:admin` permission. Users owning their own session need only `console:access`. + +**Validates: Requirements 6.4, 6.5, 6.6, 8.3** + +### Property 7: Concurrent session limit enforcement + +*For any* user who has reached the configured `maxConcurrentSessions` limit (default 3), new session creation requests SHALL be rejected with HTTP 429 status. + +**Validates: Requirements 8.6** + +### Property 8: Session record completeness + +*For any* created console session, the stored record SHALL contain non-null values for: session ID, user ID, node ID, provider name, creation timestamp, and last heartbeat timestamp. + +**Validates: Requirements 2.7** + +### Property 9: Audit log completeness for session events + +*For any* session creation or termination event, an audit log entry SHALL be recorded containing the user ID, node ID, provider name, action type, and ISO 8601 timestamp. + +**Validates: Requirements 8.4** + +### Property 10: Availability response structure and ordering + +*For any* console availability query returning multiple providers, each entry SHALL contain provider name, transport type, and display label, and entries SHALL be sorted by provider name in ascending alphabetical order. + +**Validates: Requirements 3.3, 3.4** + +### Property 11: Unsupported node returns empty availability + +*For any* node ID not supported by any registered console provider, the availability query SHALL return an empty array. + +**Validates: Requirements 3.2** + +### Property 12: Guest type routing correctness + +*For any* Proxmox guest, the console provider SHALL use the `/qemu/{vmid}/vncproxy` endpoint for QEMU guests and `/lxc/{vmid}/vncproxy` endpoint for LXC guests. + +**Validates: Requirements 9.4** + +### Property 13: Non-running guest rejection + +*For any* Proxmox guest not in the "running" state, console session creation SHALL fail with an error message indicating the guest must be running. + +**Validates: Requirements 9.6** + +### Property 14: Configuration parsing with defaults + +*For any* console environment variable that contains a non-numeric, non-integer, or less-than-1 value, the system SHALL use the documented default and log a warning. Additionally, if `heartbeatIntervalMs >= sessionTimeoutMs`, both SHALL revert to their defaults. + +**Validates: Requirements 11.1, 11.2, 11.3, 11.4, 11.5, 11.6** + +### Property 15: Unhealthy provider exclusion + +*For any* console provider that is unavailable or fails its health check, the system SHALL exclude it from availability responses while still returning results from healthy providers. + +**Validates: Requirements 10.1** + +### Property 16: Malformed control message resilience + +*For any* binary control frame received on a terminal WebSocket with an unrecognized message type byte or a payload shorter than expected for the declared type, the system SHALL discard the frame and continue relaying without terminating the session. + +**Validates: Requirements 5.8** + +## Error Handling + +### WebSocket Close Codes + +| Code | Meaning | When Used | +|------|---------|-----------| +| 4401 | Authentication failed | Invalid or expired session token | +| 4408 | Session duration exceeded | Max session duration reached | +| 4502 | Upstream failure | Provider connection dropped | +| 4504 | Connection timeout | Upstream failed to connect within 10s | + +### REST API Error Responses + +| Status | Condition | Body | +|--------|-----------|------| +| 403 | Missing `console:access` or `console:admin` | `{error: {code: "FORBIDDEN", message: "..."}}` | +| 404 | Session or node not found | `{error: {code: "NOT_FOUND", message: "..."}}` | +| 429 | Concurrent session limit reached | `{error: {code: "TOO_MANY_SESSIONS", message: "..."}}` | +| 502 | Provider unavailable or upstream error | `{error: {code: "PROVIDER_ERROR", message: "..."}}` | +| 504 | Session creation timeout (>30s) | `{error: {code: "TIMEOUT", message: "..."}}` | + +### Graceful Degradation Strategy + +- Provider health check failures → exclude from availability, don't affect other routes +- WebSocket proxy upstream drop → close client with 4502, terminate session, log +- Backend restart → mark all sessions terminated before accepting new ones +- Token expiry race condition → client gets 4401, can re-create session via REST + +## Testing Strategy + +### Property-Based Testing (fast-check) + +Property-based testing applies to this feature. The core logic around token validation, session state management, configuration parsing, and RBAC enforcement involves pure functions or clearly defined input/output behavior with large input spaces. + +**Library:** `fast-check` (already in project) +**Minimum iterations:** 100 per property test +**Tag format:** `Feature: console-integration, Property {N}: {title}` + +Properties to implement as PBT: +- Property 2 (token validation) — generate random tokens, timestamps, user IDs +- Property 4 (resize validation) — generate random dimension pairs +- Property 5 (RBAC creation) — generate random user/permission combinations +- Property 6 (RBAC cross-user termination) — generate random user/owner/permission combinations +- Property 7 (concurrent limit) — generate random session counts +- Property 8 (session record completeness) — generate random session inputs +- Property 10 (availability ordering) — generate random provider name arrays +- Property 14 (config parsing) — generate random env var values + +### Unit Tests (Vitest) + +- `ConsoleSessionManager`: session lifecycle, token generation, cleanup +- `ProxmoxConsoleProvider`: VNC ticket acquisition, guest type routing, error handling +- `ConsoleWebSocketProxy`: token extraction, origin validation, close code handling +- Config parsing: valid/invalid env vars, cross-field validation +- Route handlers: request validation, RBAC checks, response format + +### Integration Tests + +- Full session flow: create → WebSocket connect → relay → terminate +- Provider unavailability: health check failure → exclusion from availability +- Concurrent session enforcement across multiple requests +- Database: migration, session CRUD, cleanup queries + +### Frontend Tests + +- `ConsoleViewer.svelte`: transport-based rendering, status indicator, error display +- WebSocket lifecycle: connect, heartbeat timer, disconnect cleanup +- `sendBeacon` on page unload diff --git a/.kiro/specs/console-integration/requirements.md b/.kiro/specs/console-integration/requirements.md new file mode 100644 index 00000000..d638194c --- /dev/null +++ b/.kiro/specs/console-integration/requirements.md @@ -0,0 +1,178 @@ +# Requirements Document + +## Introduction + +This document specifies a generic console integration framework for Pabawi. The framework introduces a new `ConsolePlugin` interface that any integration can implement to provide remote console/terminal access to VMs, containers, or cloud instances. The initial implementation targets Proxmox (VNC/noVNC), with AWS (Systems Manager Session Manager) and Azure (Serial Console/Bastion) as future consumers. + +The console framework covers session lifecycle management, transport abstraction (WebSocket proxy for VNC, HTTP/SSE for terminal-based sessions), frontend UI embedding, RBAC-gated access, and discovery of console availability per node. + +## Glossary + +- **Console_Plugin**: A plugin interface extending the Pabawi integration system that provides remote console/terminal access to infrastructure nodes +- **Console_Session**: A server-side object representing an active console connection, tracking state, ownership, and timeout +- **Transport_Type**: The mechanism used to relay console data between the frontend and the target node (e.g., `websocket-vnc`, `websocket-terminal`, `sse-terminal`) +- **Session_Token**: A short-lived, cryptographically random token that authorizes a specific WebSocket or SSE connection to an established console session +- **Console_Provider**: A registered integration (e.g., Proxmox, AWS, Azure) that implements the Console_Plugin interface for its managed nodes +- **Integration_Manager**: The central Pabawi service that registers plugins and routes requests to the correct provider +- **Node**: A managed infrastructure entity (VM, container, or cloud instance) identified by a canonical node ID +- **RBAC_System**: The existing role-based access control system that gates feature access via resource+action permission checks +- **Heartbeat**: A periodic signal from the frontend to the backend indicating the console session is still actively used +- **Session_Timeout**: The maximum duration a console session can remain idle (no heartbeat) before automatic termination +- **noVNC**: A browser-based VNC client that communicates over WebSocket + +## Requirements + +### Requirement 1: ConsolePlugin Interface Definition + +**User Story:** As a plugin developer, I want a well-defined ConsolePlugin interface, so that I can implement console access for any infrastructure integration. + +#### Acceptance Criteria + +1. THE Console_Plugin interface SHALL extend IntegrationPlugin and define methods for `getConsoleCapabilities(nodeId: string)` returning an array of `ConsoleCapability`, `createSession(nodeId: string, userId: string)` returning a `ConsoleSession` object containing at minimum a session identifier and connection details, `terminateSession(sessionId: string)` returning a boolean indicating success, and `getSessionStatus(sessionId: string)` returning a `ConsoleSessionStatus` object containing the current session state +2. THE Console_Plugin interface SHALL define a `ConsoleCapability` type containing a `transport` field constrained to a string union of supported protocols (e.g., `websocket-vnc`, `websocket-terminal`), a `displayName` field of at most 100 characters, and a `connectionSchema` field represented as a record describing the required connection parameters for that transport +3. THE Console_Plugin interface SHALL define a `ConsoleSessionStatus` type containing a `state` field constrained to one of `creating`, `active`, `terminated`, or `failed`, a `startedAt` timestamp, and an optional `error` field present when state is `failed` +4. WHEN a plugin implements Console_Plugin, THE Integration_Manager SHALL store the plugin in a dedicated console providers map (analogous to the existing `executionTools` and `informationSources` maps) during registration +5. THE Console_Plugin interface SHALL define a `getSupportedTransports()` method that returns an array of strings representing the transport protocols the provider supports, containing at least 1 and at most 10 entries +6. IF `createSession` is called with a `nodeId` for which the plugin has no console capability, THEN THE Console_Plugin SHALL reject with a typed error indicating the node does not support console access via that provider +7. IF `terminateSession` is called with a `sessionId` that does not exist or has already been terminated, THEN THE Console_Plugin SHALL return false without throwing + +### Requirement 2: Console Session Lifecycle + +**User Story:** As a user, I want console sessions to be properly managed from creation to termination, so that resources are not leaked and connections are reliable. + +#### Acceptance Criteria + +1. WHEN a user requests a console session, THE Console_Session SHALL transition through states: `creating` → `active` → `terminated`, where the `creating` state SHALL NOT exceed 30 seconds before the session transitions to either `active` or `failed` +2. WHEN a Console_Session enters the `active` state, THE Console_Plugin SHALL return a Session_Token and connection parameters (URL, transport type, protocol-specific metadata) +3. WHILE a Console_Session is in the `active` state, THE Console_Plugin SHALL accept heartbeat signals to reset the idle timeout +4. IF a Console_Session does not receive a Heartbeat within the configured Session_Timeout, THEN THE Console_Plugin SHALL terminate the session, close any upstream provider connection, and update the session record state to `terminated` +5. WHEN a user explicitly disconnects, THE Console_Plugin SHALL terminate the session, close any upstream provider connection, and update the session record state to `terminated` within 5 seconds +6. IF the backend process restarts, THEN THE Console_Plugin SHALL mark all pre-existing sessions for the provider as `terminated` before accepting new session creation requests +7. THE Console_Session SHALL record the creating user ID, creation timestamp, last heartbeat timestamp, and provider name +8. IF session creation fails due to provider unavailability or upstream error, THEN THE Console_Plugin SHALL transition the session to a `failed` state and return an error message indicating the provider-specific failure reason + +### Requirement 3: Console Availability Discovery + +**User Story:** As a user, I want to know which nodes support console access and through which provider, so that I can open a console from the node detail page. + +#### Acceptance Criteria + +1. WHEN the frontend requests console availability for a node, THE Integration_Manager SHALL query all registered Console_Plugin providers in parallel and return an array of available console capabilities within 2 seconds +2. IF no Console_Plugin provider supports console access for a given node, THEN THE Integration_Manager SHALL return an empty capabilities array +3. WHEN the Integration_Manager constructs a console availability response, THE Integration_Manager SHALL include the provider name, transport type, and display label for each available console option +4. WHEN multiple Console_Plugin providers offer console access for the same node, THE Integration_Manager SHALL return all options sorted by provider name in ascending alphabetical order +5. IF a Console_Plugin provider does not respond within 3 seconds during capability discovery, THEN THE Integration_Manager SHALL exclude that provider from the response and include the remaining results + +### Requirement 4: WebSocket Transport for VNC + +**User Story:** As a user, I want to access VNC consoles through a WebSocket proxy, so that I can interact with graphical VM consoles in my browser. + +#### Acceptance Criteria + +1. WHEN a Console_Session uses the `websocket-vnc` transport type, THE backend SHALL establish a WebSocket endpoint that proxies traffic between the frontend noVNC client and the target VNC server +2. WHEN a client initiates a WebSocket connection to the VNC proxy endpoint, THE WebSocket proxy SHALL extract the Session_Token from the `token` query parameter and validate that the token exists, has not expired, and maps to a Console_Session owned by the connecting user before relaying any data +3. IF the Session_Token is invalid or expired, THEN THE WebSocket proxy SHALL reject the connection with a 4401 close code and an error reason +4. WHILE the WebSocket proxy is relaying data, THE proxy SHALL forward binary frames bidirectionally without modification +5. IF the upstream VNC connection drops, THEN THE WebSocket proxy SHALL close the client WebSocket with a 4502 close code indicating upstream failure +6. IF the client WebSocket closes (intentionally or unexpectedly), THEN THE WebSocket proxy SHALL close the upstream VNC connection and release associated resources within 5 seconds +7. IF the upstream VNC connection cannot be established within 10 seconds of session creation, THEN THE WebSocket proxy SHALL close the client WebSocket with a 4504 close code indicating connection timeout +8. WHEN the maximum session duration (configured via `console.maxSessionDuration`, default 8 hours) is reached, THE WebSocket proxy SHALL close the client WebSocket with a 4408 close code indicating session duration exceeded + +### Requirement 5: Terminal-Based Transport + +**User Story:** As a user, I want to access text-based consoles (SSH, serial console, SSM) through a WebSocket terminal stream, so that I can interact with CLI-based sessions in my browser. + +#### Acceptance Criteria + +1. WHEN a Console_Session uses the `websocket-terminal` transport type, THE backend SHALL establish a WebSocket endpoint that relays terminal I/O between the frontend terminal emulator and the provider's session +2. THE WebSocket terminal endpoint SHALL validate the Session_Token on the initial connection handshake before relaying data +3. IF the Session_Token is invalid or expired, THEN THE WebSocket terminal endpoint SHALL reject the connection with a 4401 close code and an error reason indicating whether the token was invalid or expired +4. THE WebSocket terminal endpoint SHALL support UTF-8 text frames for terminal I/O and binary frames for control messages (resize events) +5. WHEN the frontend sends a resize control message with valid dimensions (columns between 1 and 500, rows between 1 and 200), THE Console_Plugin SHALL propagate the new terminal dimensions to the remote session +6. IF the upstream provider connection drops while the terminal session is active, THEN THE WebSocket terminal endpoint SHALL close the client WebSocket with a 4502 close code indicating upstream failure and terminate the Console_Session +7. THE WebSocket terminal endpoint SHALL enforce the configured `console.maxSessionDuration` limit, closing the connection with a 4408 close code when the maximum duration is reached +8. IF the WebSocket terminal endpoint receives a binary control message with an unrecognized message type byte or a frame shorter than the expected payload length for the declared type, THEN THE endpoint SHALL discard the frame and continue relaying without terminating the session + +### Requirement 6: RBAC and Authorization + +**User Story:** As an administrator, I want console access to be gated by RBAC permissions, so that only authorized users can open console sessions. + +#### Acceptance Criteria + +1. THE RBAC_System SHALL define a `console` resource with `access` and `admin` actions +2. WHEN a user requests to create a Console_Session, THE backend SHALL verify the user holds the `console:access` permission before proceeding +3. IF a user does not hold the `console:access` permission, THEN THE backend SHALL reject the Console_Session creation request with a 403 response indicating the `console:access` permission is required +4. WHEN a user requests to terminate a Console_Session owned by a different user, THE backend SHALL verify the requesting user holds the `console:admin` permission before proceeding +5. IF a user requests to terminate a Console_Session owned by a different user and does not hold the `console:admin` permission, THEN THE backend SHALL reject the request with a 403 response indicating the `console:admin` permission is required +6. WHEN a user requests to terminate their own Console_Session, THE backend SHALL allow the operation if the user holds the `console:access` permission without requiring `console:admin` +7. THE RBAC_System SHALL use the unscoped `console:access` and `console:admin` permissions without per-integration scoping + +### Requirement 7: Frontend Console UI + +**User Story:** As a user, I want an embedded console viewer on the node detail page, so that I can interact with remote consoles without leaving Pabawi. + +#### Acceptance Criteria + +1. WHEN a user opens a console session from the node detail page, THE frontend SHALL render an embedded console component appropriate to the transport type (noVNC viewer for `websocket-vnc`, xterm.js terminal for `websocket-terminal`) +2. THE frontend console component SHALL display a connection status indicator showing `connecting`, `connected`, or `disconnected` states +3. WHILE the console session is in the `active` state, THE frontend SHALL send Heartbeat signals to the backend every 30 seconds and SHALL stop sending heartbeats when the connection status transitions to `disconnected` +4. WHEN the user closes the console component or navigates away, THE frontend SHALL send a terminate request to the backend using a best-effort delivery mechanism (e.g., `navigator.sendBeacon` or fire-and-forget fetch) to maximize delivery during page unload +5. IF the WebSocket connection closes with code 4401 (invalid or expired token), THEN THE frontend SHALL display an error message indicating the session authorization failed and offer an option to create a new session +6. IF the WebSocket connection closes with code 4502 (upstream target failure), THEN THE frontend SHALL display an error message indicating the remote host connection was lost and offer an option to create a new session +7. IF the WebSocket connection drops unexpectedly (close codes other than 4401, 4502, or normal closure initiated by the frontend), THEN THE frontend SHALL display a reconnection prompt with an option to create a new session +8. WHEN establishing the WebSocket connection, THE frontend SHALL pass the Session_Token received from session creation as a query parameter on the WebSocket handshake URL +9. THE frontend console component SHALL provide a full-screen toggle for the console viewport + +### Requirement 8: Security and Session Isolation + +**User Story:** As an administrator, I want console sessions to be isolated and auditable, so that the system maintains security boundaries. + +#### Acceptance Criteria + +1. THE Session_Token SHALL be a cryptographically random string of at least 32 bytes, generated using a secure random source +2. IF a Session_Token is not used to establish a WebSocket connection within 60 seconds of creation, THEN THE backend SHALL invalidate the token and reject any subsequent connection attempt using that token with an error indicating the token has expired +3. IF a user without `console:admin` permission attempts to access a Console_Session they did not create, THEN THE backend SHALL reject the request with a 403 status and an error indicating insufficient permissions +4. WHEN a Console_Session is created or terminated, THE backend SHALL record an audit log entry containing the user ID, node ID, provider, action, and timestamp +5. IF a WebSocket connection request presents an Origin header that does not match the configured allowed origins, THEN THE WebSocket proxy SHALL reject the connection before the upgrade completes +6. IF a user has more than 3 concurrent active Console_Sessions, THEN THE backend SHALL reject new session creation with a 429 status and an error indicating the concurrent session limit +7. WHEN a Console_Session is terminated or its Session_Token is invalidated, THE backend SHALL close the associated WebSocket connection within 5 seconds + +### Requirement 9: Proxmox Console Provider (Initial Implementation) + +**User Story:** As a user with Proxmox VMs or LXC containers, I want to open VNC consoles to my Proxmox guests, so that I can interact with them graphically. + +#### Acceptance Criteria + +1. THE Proxmox Console_Provider SHALL implement the Console_Plugin interface and register with the Integration_Manager when the Proxmox integration is enabled +2. WHEN a user requests console access for a Proxmox node, THE Proxmox Console_Provider SHALL request a VNC proxy ticket from the Proxmox API using the endpoint corresponding to the guest type (`qemu` or `lxc`) +3. WHEN the Proxmox API returns a VNC proxy ticket, THE Proxmox Console_Provider SHALL use the ticket to establish a WebSocket connection to the Proxmox VNC WebSocket endpoint +4. WHEN creating a session for a Proxmox guest, THE Proxmox Console_Provider SHALL determine the guest type and use the QEMU vncproxy endpoint for `qemu` guests and the LXC vncproxy endpoint for `lxc` guests +5. IF the Proxmox API returns an authentication error when requesting a VNC ticket, THEN THE Proxmox Console_Provider SHALL return a session creation failure with an error message indicating the authentication failure reason returned by the Proxmox API +6. IF the target guest is not in the `running` state when a VNC session is requested, THEN THE Proxmox Console_Provider SHALL return a session creation failure with an error message indicating that the guest must be running for console access +7. IF the Proxmox API returns a non-authentication error (connection timeout, unreachable host, or resource not found) when requesting a VNC ticket, THEN THE Proxmox Console_Provider SHALL return a session creation failure with an error message indicating the specific failure category +8. THE Proxmox Console_Provider SHALL advertise the `websocket-vnc` transport type in its console capabilities + +### Requirement 10: Graceful Degradation + +**User Story:** As a user, I want the console feature to degrade gracefully when console access is unavailable, so that the rest of the application remains fully functional. + +#### Acceptance Criteria + +1. IF a Console_Plugin provider is unavailable or unhealthy, THEN THE Integration_Manager SHALL exclude the provider from console availability responses and return the remaining available providers within the standard API response time, without affecting other application functionality +2. IF console session creation fails, THEN THE frontend SHALL display an error message with the provider-specific reason and offer a retry option that is available up to 3 consecutive attempts before disabling the retry button and displaying a message indicating the provider may be unavailable +3. IF no Console_Plugin providers are registered or all registered Console_Plugin providers are unhealthy, THEN THE frontend SHALL hide all console-related UI elements from the node detail page +4. IF the WebSocket proxy loses connection to the upstream target during an active session, THEN THE backend SHALL terminate the Console_Session and notify the frontend with a WebSocket close frame using close code 4502 +5. WHEN the frontend requests console availability for a node, THE frontend SHALL load and render the node detail page independently of the console availability response, treating the console availability check as a non-blocking asynchronous request that populates the console UI section upon completion + +### Requirement 11: Configuration + +**User Story:** As an administrator, I want to configure console behavior through environment variables, so that I can tune timeouts and limits without code changes. + +#### Acceptance Criteria + +1. THE ConfigService SHALL expose a `console.sessionTimeoutMs` setting, sourced from the `CONSOLE_SESSION_TIMEOUT_MS` environment variable, validated as a positive integer, with a default value of 300000 milliseconds (5 minutes) +2. THE ConfigService SHALL expose a `console.maxSessionDuration` setting, sourced from the `CONSOLE_MAX_SESSION_DURATION` environment variable, validated as a positive integer, with a default value of 28800000 milliseconds (8 hours) +3. THE ConfigService SHALL expose a `console.maxConcurrentSessions` setting, sourced from the `CONSOLE_MAX_CONCURRENT_SESSIONS` environment variable, validated as a positive integer with a minimum value of 1, with a default value of 3 +4. THE ConfigService SHALL expose a `console.heartbeatIntervalMs` setting, sourced from the `CONSOLE_HEARTBEAT_INTERVAL_MS` environment variable, validated as a positive integer, with a default value of 30000 milliseconds (30 seconds) +5. IF any console configuration environment variable contains a value that is non-numeric, not an integer, or less than 1, THEN THE ConfigService SHALL use the default value for that setting and log a warning via LoggerService with component "ConfigService" indicating which variable was invalid and what default was applied +6. WHEN the ConfigService initializes, THE ConfigService SHALL validate that `console.heartbeatIntervalMs` is less than `console.sessionTimeoutMs`, and if not, SHALL use the default values for both settings and log a warning diff --git a/.kiro/specs/console-integration/tasks.md b/.kiro/specs/console-integration/tasks.md new file mode 100644 index 00000000..01809da4 --- /dev/null +++ b/.kiro/specs/console-integration/tasks.md @@ -0,0 +1,234 @@ +# Implementation Plan: Console Integration + +## Overview + +This plan implements the console integration framework for Pabawi — a plugin-based system that enables remote console/terminal access (VNC, terminal) to managed infrastructure nodes. The initial implementation targets Proxmox VNC consoles. The work is broken into phases: core types and configuration, session management, WebSocket proxy, Proxmox provider, REST routes, and frontend UI. + +## Tasks + +- [ ] 1. Core types, configuration, and database schema + - [ ] 1.1 Define ConsolePlugin interface and related types + - Create `backend/src/integrations/console/types.ts` with `ConsoleTransport`, `ConsoleCapability`, `ConsoleSessionState`, `ConsoleSessionStatus`, `ConsoleSession`, and `ConsolePlugin` interface extending `IntegrationPlugin` + - Export all types for use by providers, session manager, and routes + - _Requirements: 1.1, 1.2, 1.3, 1.5, 1.6, 1.7_ + + - [ ] 1.2 Add console configuration to ConfigService and schema + - Add `ConsoleConfigSchema` to `backend/src/config/schema.ts` with `sessionTimeoutMs`, `maxSessionDuration`, `maxConcurrentSessions`, `heartbeatIntervalMs` + - Add console config parsing in `ConfigService` from `CONSOLE_*` env vars with validation (positive int, min 1 for concurrent sessions, heartbeat < timeout cross-check) + - Log warnings for invalid values and fall back to defaults + - _Requirements: 11.1, 11.2, 11.3, 11.4, 11.5, 11.6_ + + - [ ]* 1.3 Write property test for configuration parsing (Property 14) + - **Property 14: Configuration parsing with defaults** + - Generate random env var values (non-numeric, negative, zero, floats, valid) and verify defaults are applied for invalid values, heartbeat >= timeout triggers both defaults + - **Validates: Requirements 11.1, 11.2, 11.3, 11.4, 11.5, 11.6** + + - [ ] 1.4 Create database migration 018_console_sessions.sql + - Create `backend/src/database/migrations/018_console_sessions.sql` with `console_sessions` table (snake_case columns), indexes on `user_id`, `state`, `token` + - Include CHECK constraints for `state` and `transport` columns + - _Requirements: 2.7_ + + - [ ] 1.5 Create database migration 019_console_permissions.sql + - Create `backend/src/database/migrations/019_console_permissions.sql` inserting `console:access` and `console:admin` permissions + - Grant `console:access` to operator and admin roles, `console:admin` to admin only + - _Requirements: 6.1, 6.7_ + +- [ ] 2. Checkpoint - Ensure all tests pass + - Ensure all tests pass, ask the user if questions arise. + +- [ ] 3. ConsoleSessionManager service + - [ ] 3.1 Implement ConsoleSessionManager + - Create `backend/src/services/ConsoleSessionManager.ts` with token generation (crypto.randomBytes 32+), session CRUD, token validation (exists, <60s, not consumed, owner match), heartbeat recording, concurrent session counting, provider-level bulk termination, expired session cleanup + - Use `DatabaseAdapter` for all DB operations with snake_case columns and camelCase aliases in SELECTs + - Integrate `AuditLoggingService` for session create/terminate events + - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 8.1, 8.2, 8.4, 8.6, 8.7_ + + - [ ]* 3.2 Write property test for session token validation (Property 2) + - **Property 2: Session token validation correctness** + - Generate random tokens, timestamps, user IDs. Token accepted iff: exists in DB, created <60s ago, not consumed, connecting user matches owner. All others rejected. + - **Validates: Requirements 4.2, 4.3, 5.2, 5.3, 8.1, 8.2** + + - [ ]* 3.3 Write property test for concurrent session limit (Property 7) + - **Property 7: Concurrent session limit enforcement** + - Generate random session counts and verify that when active count >= maxConcurrentSessions, new creation is rejected with 429 semantics. + - **Validates: Requirements 8.6** + + - [ ]* 3.4 Write property test for session record completeness (Property 8) + - **Property 8: Session record completeness** + - Generate random session inputs and verify stored record always has non-null sessionId, userId, nodeId, provider, createdAt, lastHeartbeatAt. + - **Validates: Requirements 2.7** + + - [ ]* 3.5 Write property test for audit log completeness (Property 9) + - **Property 9: Audit log completeness for session events** + - Generate random session create/terminate events. Verify audit entry always contains userId, nodeId, provider, action, ISO 8601 timestamp. + - **Validates: Requirements 8.4** + +- [ ] 4. Checkpoint - Ensure all tests pass + - Ensure all tests pass, ask the user if questions arise. + +- [ ] 5. IntegrationManager extension and console availability + - [ ] 5.1 Extend IntegrationManager with console provider support + - Add `consoleProviders` map, `isConsolePlugin` type guard, registration logic in `registerPlugin`, and public methods `getConsoleProvider`, `getAllConsoleProviders`, `getConsoleAvailability` + - Console availability queries all providers in parallel with 3s timeout, excludes timed-out providers, sorts results by provider name ascending + - _Requirements: 1.4, 3.1, 3.2, 3.3, 3.4, 3.5, 10.1_ + + - [ ]* 5.2 Write property test for availability response ordering (Property 10) + - **Property 10: Availability response structure and ordering** + - Generate random provider name arrays. Verify response entries contain provider name, transport, display label; entries sorted alphabetically by provider name. + - **Validates: Requirements 3.3, 3.4** + + - [ ]* 5.3 Write property test for unsupported node empty response (Property 11) + - **Property 11: Unsupported node returns empty availability** + - Generate random node IDs not supported by any registered provider. Verify availability returns empty array. + - **Validates: Requirements 3.2** + + - [ ]* 5.4 Write property test for unhealthy provider exclusion (Property 15) + - **Property 15: Unhealthy provider exclusion** + - Generate random provider health states. Verify unavailable/unhealthy providers are excluded from availability while healthy providers are included. + - **Validates: Requirements 10.1** + +- [ ] 6. WebSocket proxy server + - [ ] 6.1 Implement ConsoleWebSocketProxy + - Create `backend/src/services/ConsoleWebSocketProxy.ts` using `ws` library attached to existing HTTP server with `noServer: true` + - Handle `upgrade` event with path-based routing (`/ws/console/vnc`, `/ws/console/terminal`) + - Validate origin header against configured allowed origins + - Extract and validate session token from query params via `ConsoleSessionManager` + - Implement VNC binary relay (bidirectional, unmodified frames) + - Implement terminal relay (UTF-8 text frames for I/O, binary frames for control messages) + - Handle terminal resize control messages: validate columns [1,500] and rows [1,200], discard invalid + - Discard unrecognized binary control message types or frames shorter than expected payload + - Enforce `maxSessionDuration` limit (close with 4408) + - Handle upstream connection timeout (close with 4504 after 10s) + - Handle upstream drop (close with 4502, terminate session) + - Handle client disconnect (close upstream within 5s, release resources) + - Handle invalid/expired token (close with 4401) + - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7, 4.8, 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 8.5, 8.7_ + + - [ ]* 6.2 Write property test for binary frame relay integrity (Property 3) + - **Property 3: Binary frame relay integrity** + - Generate random binary buffers. Verify frames pass through the proxy byte-for-byte identical. + - **Validates: Requirements 4.4** + + - [ ]* 6.3 Write property test for terminal resize validation (Property 4) + - **Property 4: Terminal resize dimension validation** + - Generate random column/row pairs. Verify resize propagated iff columns in [1,500] and rows in [1,200]; otherwise discarded without session termination. + - **Validates: Requirements 5.5, 5.8** + + - [ ]* 6.4 Write property test for malformed control message resilience (Property 16) + - **Property 16: Malformed control message resilience** + - Generate random binary frames with unrecognized type bytes or truncated payloads. Verify discarded without session termination. + - **Validates: Requirements 5.8** + +- [ ] 7. Checkpoint - Ensure all tests pass + - Ensure all tests pass, ask the user if questions arise. + +- [ ] 8. ProxmoxConsoleProvider + - [ ] 8.1 Implement ProxmoxConsoleProvider + - Create `backend/src/integrations/proxmox/ProxmoxConsoleProvider.ts` implementing `ConsolePlugin` + - Implement `getConsoleCapabilities`: check guest exists and is running, return `websocket-vnc` capability + - Implement `createSession`: determine guest type (qemu/lxc), verify running state, call appropriate vncproxy endpoint, build upstream WS URL, generate session token, return ConsoleSession + - Implement `terminateSession`: return false for non-existent/already-terminated sessions without throwing + - Implement `getSessionStatus`, `getSupportedTransports` + - Handle auth errors, non-running guest, connection timeout, resource not found from Proxmox API + - _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7, 9.8, 1.6, 1.7_ + + - [ ]* 8.2 Write property test for guest type routing (Property 12) + - **Property 12: Guest type routing correctness** + - Generate random guest types (qemu/lxc). Verify QEMU guests use `/qemu/{vmid}/vncproxy` and LXC guests use `/lxc/{vmid}/vncproxy`. + - **Validates: Requirements 9.4** + + - [ ]* 8.3 Write property test for non-running guest rejection (Property 13) + - **Property 13: Non-running guest rejection** + - Generate random guest states (running, stopped, paused, etc.). Verify session creation fails for any state other than "running" with appropriate error message. + - **Validates: Requirements 9.6** + + - [ ]* 8.4 Write property test for provider registration (Property 1) + - **Property 1: Console provider registration invariant** + - Generate random plugin names. After registration with IntegrationManager, verify plugin appears in console providers map and is retrievable by name. + - **Validates: Requirements 1.4** + +- [ ] 9. Console REST routes + - [ ] 9.1 Implement console route factory and endpoints + - Create `backend/src/routes/console.ts` exporting `createConsoleRouter(container, integrationManager, sessionManager, db)` + - Implement `GET /api/console/availability/:nodeId` — RBAC check `console:access`, query availability via IntegrationManager + - Implement `POST /api/console/sessions` — RBAC check `console:access`, check concurrent limit (429), create session via provider, store session + - Implement `DELETE /api/console/sessions/:sessionId` — RBAC check: own session needs `console:access`, other user's session needs `console:admin` (403 otherwise) + - Implement `GET /api/console/sessions/:sessionId` — RBAC check `console:access`, return session status + - Implement `POST /api/console/sessions/:sessionId/heartbeat` — RBAC check `console:access`, record heartbeat + - _Requirements: 6.2, 6.3, 6.4, 6.5, 6.6, 8.3, 8.6, 10.4_ + + - [ ]* 9.2 Write property test for RBAC session creation (Property 5) + - **Property 5: RBAC enforcement for session creation** + - Generate random user/permission combinations. Verify session creation allowed iff user holds `console:access`; otherwise 403. + - **Validates: Requirements 6.2, 6.3** + + - [ ]* 9.3 Write property test for RBAC cross-user termination (Property 6) + - **Property 6: RBAC enforcement for cross-user termination** + - Generate random user/owner/permission combinations. Verify cross-user termination requires `console:admin`; own session termination needs only `console:access`. + - **Validates: Requirements 6.4, 6.5, 6.6, 8.3** + +- [ ] 10. Wire backend components together + - [ ] 10.1 Register ProxmoxConsoleProvider and wire routes in server.ts + - Register `ProxmoxConsoleProvider` with `IntegrationManager` in the plugin registry when Proxmox is enabled + - Instantiate `ConsoleSessionManager` with DI container services + - Instantiate `ConsoleWebSocketProxy` attached to the HTTP server + - Mount console router at `/api/console` + - On server startup, call `terminateAllForProvider` for each registered console provider (graceful restart handling) + - Start session cleanup interval + - _Requirements: 2.6, 9.1_ + +- [ ] 11. Checkpoint - Ensure all tests pass + - Ensure all tests pass, ask the user if questions arise. + +- [ ] 12. Frontend ConsoleViewer component + - [ ] 12.1 Implement ConsoleViewer Svelte 5 component + - Create `frontend/src/components/ConsoleViewer.svelte` accepting `nodeId` and `capabilities` props + - Render noVNC canvas for `websocket-vnc` transport, xterm.js terminal for `websocket-terminal` + - Display connection status indicator (`connecting`, `connected`, `disconnected`) + - Implement heartbeat timer (30s interval while connected, stop on disconnect) + - Handle WebSocket close codes: 4401 (auth failed), 4502 (upstream failure), 4408 (duration exceeded), 4504 (timeout) with user-facing messages and "new session" option + - Handle unexpected close codes with reconnection prompt + - Implement full-screen toggle for the console viewport + - Use `navigator.sendBeacon` for terminate request on page unload/navigation away + - Pass session token as query parameter on WebSocket URL + - _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5, 7.6, 7.7, 7.8, 7.9_ + + - [ ] 12.2 Implement console availability UI on node detail page + - Add console availability fetch (non-blocking async) to the node detail page + - Show console options when available, hide all console UI when no providers available + - Implement retry logic: up to 3 consecutive attempts on failure, then disable retry button with "provider unavailable" message + - _Requirements: 10.2, 10.3, 10.5_ + +- [ ] 13. Final checkpoint - Ensure all tests pass + - Ensure all tests pass, ask the user if questions arise. + +## Notes + +- Tasks marked with `*` are optional and can be skipped for faster MVP +- Each task references specific requirements for traceability +- Checkpoints ensure incremental validation +- Property tests validate universal correctness properties from the design document using `fast-check` +- Unit tests validate specific examples and edge cases +- Database columns use `snake_case` with `camelCase` aliases in SELECT queries per project convention +- The WebSocket proxy uses the `ws` library attached to the shared HTTP server (no second port) +- Frontend uses noVNC for VNC transport and xterm.js for terminal transport +- All code must pass ESLint, `tsc --noEmit`, and `vitest` before proceeding to the next task + +## Task Dependency Graph + +```json +{ + "waves": [ + { "id": 0, "tasks": ["1.1", "1.4", "1.5"] }, + { "id": 1, "tasks": ["1.2"] }, + { "id": 2, "tasks": ["1.3", "3.1"] }, + { "id": 3, "tasks": ["3.2", "3.3", "3.4", "3.5", "5.1"] }, + { "id": 4, "tasks": ["5.2", "5.3", "5.4", "6.1"] }, + { "id": 5, "tasks": ["6.2", "6.3", "6.4", "8.1"] }, + { "id": 6, "tasks": ["8.2", "8.3", "8.4", "9.1"] }, + { "id": 7, "tasks": ["9.2", "9.3", "10.1"] }, + { "id": 8, "tasks": ["12.1"] }, + { "id": 9, "tasks": ["12.2"] } + ] +} +``` diff --git a/.kiro/specs/070/hiera-codebase-integration/design.md b/.kiro/specs/done/070/hiera-codebase-integration/design.md similarity index 100% rename from .kiro/specs/070/hiera-codebase-integration/design.md rename to .kiro/specs/done/070/hiera-codebase-integration/design.md diff --git a/.kiro/specs/070/hiera-codebase-integration/requirements.md b/.kiro/specs/done/070/hiera-codebase-integration/requirements.md similarity index 100% rename from .kiro/specs/070/hiera-codebase-integration/requirements.md rename to .kiro/specs/done/070/hiera-codebase-integration/requirements.md diff --git a/.kiro/specs/070/hiera-codebase-integration/tasks.md b/.kiro/specs/done/070/hiera-codebase-integration/tasks.md similarity index 100% rename from .kiro/specs/070/hiera-codebase-integration/tasks.md rename to .kiro/specs/done/070/hiera-codebase-integration/tasks.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/MANUAL_TESTING_COMPLETE.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/MANUAL_TESTING_COMPLETE.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/MANUAL_TESTING_COMPLETE.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/MANUAL_TESTING_COMPLETE.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/TESTING_INDEX.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/TESTING_INDEX.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/TESTING_INDEX.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/TESTING_INDEX.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/TESTING_README.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/TESTING_README.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/TESTING_README.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/TESTING_README.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/cache-issue-resolution.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/cache-issue-resolution.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/cache-issue-resolution.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/cache-issue-resolution.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/code-consolidation-guide.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/code-consolidation-guide.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/code-consolidation-guide.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/code-consolidation-guide.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/design.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/design.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/design.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/design.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/expert-mode-coverage-checklist.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/expert-mode-coverage-checklist.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/expert-mode-coverage-checklist.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/expert-mode-coverage-checklist.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/expert-mode-test-results.txt b/.kiro/specs/done/070/pabawi-v0.5.0-release/expert-mode-test-results.txt similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/expert-mode-test-results.txt rename to .kiro/specs/done/070/pabawi-v0.5.0-release/expert-mode-test-results.txt diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/logging-expert-mode-audit.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/logging-expert-mode-audit.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/logging-expert-mode-audit.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/logging-expert-mode-audit.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/logging-expert-mode-pattern.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/logging-expert-mode-pattern.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/logging-expert-mode-pattern.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/logging-expert-mode-pattern.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/logging-integration-summary.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/logging-integration-summary.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/logging-integration-summary.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/logging-integration-summary.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/manual-test-expert-mode.sh b/.kiro/specs/done/070/pabawi-v0.5.0-release/manual-test-expert-mode.sh similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/manual-test-expert-mode.sh rename to .kiro/specs/done/070/pabawi-v0.5.0-release/manual-test-expert-mode.sh diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/manual-testing-guide.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/manual-testing-guide.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/manual-testing-guide.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/manual-testing-guide.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/manual-testing-implementation-summary.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/manual-testing-implementation-summary.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/manual-testing-implementation-summary.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/manual-testing-implementation-summary.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/manual-testing-quick-reference.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/manual-testing-quick-reference.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/manual-testing-quick-reference.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/manual-testing-quick-reference.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/migration-example.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/migration-example.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/migration-example.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/migration-example.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/requirements.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/requirements.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/requirements.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/requirements.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/routes-refactoring-completion.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/routes-refactoring-completion.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/routes-refactoring-completion.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/routes-refactoring-completion.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/routes-refactoring-implementation.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/routes-refactoring-implementation.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/routes-refactoring-implementation.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/routes-refactoring-implementation.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/routes-refactoring-plan.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/routes-refactoring-plan.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/routes-refactoring-plan.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/routes-refactoring-plan.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/task-10.5-completion-summary.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/task-10.5-completion-summary.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/task-10.5-completion-summary.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/task-10.5-completion-summary.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/task-5.7-summary.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/task-5.7-summary.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/task-5.7-summary.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/task-5.7-summary.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/task-6.5.4-completion-report.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/task-6.5.4-completion-report.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/task-6.5.4-completion-report.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/task-6.5.4-completion-report.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/task-6.5.4-executions-completion.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/task-6.5.4-executions-completion.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/task-6.5.4-executions-completion.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/task-6.5.4-executions-completion.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/task-6.5.4-summary.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/task-6.5.4-summary.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/task-6.5.4-summary.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/task-6.5.4-summary.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/task-6.5.4.1-facts-completion.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/task-6.5.4.1-facts-completion.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/task-6.5.4.1-facts-completion.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/task-6.5.4.1-facts-completion.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/task-6.5.4.1-node-certname-completion.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/task-6.5.4.1-node-certname-completion.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/task-6.5.4.1-node-certname-completion.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/task-6.5.4.1-node-certname-completion.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/task-6.5.4.1-verification-complete.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/task-6.5.4.1-verification-complete.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/task-6.5.4.1-verification-complete.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/task-6.5.4.1-verification-complete.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/task-node-reports-completion.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/task-node-reports-completion.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/task-node-reports-completion.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/task-node-reports-completion.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/tasks.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/tasks.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/tasks.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/tasks.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/test-single-route.sh b/.kiro/specs/done/070/pabawi-v0.5.0-release/test-single-route.sh similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/test-single-route.sh rename to .kiro/specs/done/070/pabawi-v0.5.0-release/test-single-route.sh diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/testing-checklist.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/testing-checklist.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/testing-checklist.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/testing-checklist.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/testing-flow-diagram.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/testing-flow-diagram.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/testing-flow-diagram.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/testing-flow-diagram.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/testing-troubleshooting.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/testing-troubleshooting.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/testing-troubleshooting.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/testing-troubleshooting.md diff --git a/.kiro/specs/070/pabawi-v0.5.0-release/unified-logging-implementation.md b/.kiro/specs/done/070/pabawi-v0.5.0-release/unified-logging-implementation.md similarity index 100% rename from .kiro/specs/070/pabawi-v0.5.0-release/unified-logging-implementation.md rename to .kiro/specs/done/070/pabawi-v0.5.0-release/unified-logging-implementation.md diff --git a/.kiro/specs/070/pabawi/IMPLEMENTATION_STATUS.md b/.kiro/specs/done/070/pabawi/IMPLEMENTATION_STATUS.md similarity index 100% rename from .kiro/specs/070/pabawi/IMPLEMENTATION_STATUS.md rename to .kiro/specs/done/070/pabawi/IMPLEMENTATION_STATUS.md diff --git a/.kiro/specs/070/pabawi/design.md b/.kiro/specs/done/070/pabawi/design.md similarity index 100% rename from .kiro/specs/070/pabawi/design.md rename to .kiro/specs/done/070/pabawi/design.md diff --git a/.kiro/specs/070/pabawi/requirements.md b/.kiro/specs/done/070/pabawi/requirements.md similarity index 100% rename from .kiro/specs/070/pabawi/requirements.md rename to .kiro/specs/done/070/pabawi/requirements.md diff --git a/.kiro/specs/070/pabawi/tasks.md b/.kiro/specs/done/070/pabawi/tasks.md similarity index 100% rename from .kiro/specs/070/pabawi/tasks.md rename to .kiro/specs/done/070/pabawi/tasks.md diff --git a/.kiro/specs/070/puppet-reports-pagination-and-debug-fixes/requirements.md b/.kiro/specs/done/070/puppet-reports-pagination-and-debug-fixes/requirements.md similarity index 100% rename from .kiro/specs/070/puppet-reports-pagination-and-debug-fixes/requirements.md rename to .kiro/specs/done/070/puppet-reports-pagination-and-debug-fixes/requirements.md diff --git a/.kiro/specs/070/puppet-reports-pagination/design.md b/.kiro/specs/done/070/puppet-reports-pagination/design.md similarity index 100% rename from .kiro/specs/070/puppet-reports-pagination/design.md rename to .kiro/specs/done/070/puppet-reports-pagination/design.md diff --git a/.kiro/specs/070/puppet-reports-pagination/phase-4-audit-report.md b/.kiro/specs/done/070/puppet-reports-pagination/phase-4-audit-report.md similarity index 100% rename from .kiro/specs/070/puppet-reports-pagination/phase-4-audit-report.md rename to .kiro/specs/done/070/puppet-reports-pagination/phase-4-audit-report.md diff --git a/.kiro/specs/070/puppet-reports-pagination/phase-5-audit-report.md b/.kiro/specs/done/070/puppet-reports-pagination/phase-5-audit-report.md similarity index 100% rename from .kiro/specs/070/puppet-reports-pagination/phase-5-audit-report.md rename to .kiro/specs/done/070/puppet-reports-pagination/phase-5-audit-report.md diff --git a/.kiro/specs/070/puppet-reports-pagination/requirements.md b/.kiro/specs/done/070/puppet-reports-pagination/requirements.md similarity index 100% rename from .kiro/specs/070/puppet-reports-pagination/requirements.md rename to .kiro/specs/done/070/puppet-reports-pagination/requirements.md diff --git a/.kiro/specs/070/puppet-reports-pagination/tasks.md b/.kiro/specs/done/070/puppet-reports-pagination/tasks.md similarity index 100% rename from .kiro/specs/070/puppet-reports-pagination/tasks.md rename to .kiro/specs/done/070/puppet-reports-pagination/tasks.md diff --git a/.kiro/specs/070/puppetdb-integration/design.md b/.kiro/specs/done/070/puppetdb-integration/design.md similarity index 100% rename from .kiro/specs/070/puppetdb-integration/design.md rename to .kiro/specs/done/070/puppetdb-integration/design.md diff --git a/.kiro/specs/070/puppetdb-integration/requirements.md b/.kiro/specs/done/070/puppetdb-integration/requirements.md similarity index 100% rename from .kiro/specs/070/puppetdb-integration/requirements.md rename to .kiro/specs/done/070/puppetdb-integration/requirements.md diff --git a/.kiro/specs/070/puppetdb-integration/tasks.md b/.kiro/specs/done/070/puppetdb-integration/tasks.md similarity index 100% rename from .kiro/specs/070/puppetdb-integration/tasks.md rename to .kiro/specs/done/070/puppetdb-integration/tasks.md diff --git a/.kiro/specs/070/puppetserver-integration/design.md b/.kiro/specs/done/070/puppetserver-integration/design.md similarity index 100% rename from .kiro/specs/070/puppetserver-integration/design.md rename to .kiro/specs/done/070/puppetserver-integration/design.md diff --git a/.kiro/specs/070/puppetserver-integration/expert-mode-review.md b/.kiro/specs/done/070/puppetserver-integration/expert-mode-review.md similarity index 100% rename from .kiro/specs/070/puppetserver-integration/expert-mode-review.md rename to .kiro/specs/done/070/puppetserver-integration/expert-mode-review.md diff --git a/.kiro/specs/070/puppetserver-integration/manual-testing-guide.md b/.kiro/specs/done/070/puppetserver-integration/manual-testing-guide.md similarity index 100% rename from .kiro/specs/070/puppetserver-integration/manual-testing-guide.md rename to .kiro/specs/done/070/puppetserver-integration/manual-testing-guide.md diff --git a/.kiro/specs/070/puppetserver-integration/requirements.md b/.kiro/specs/done/070/puppetserver-integration/requirements.md similarity index 100% rename from .kiro/specs/070/puppetserver-integration/requirements.md rename to .kiro/specs/done/070/puppetserver-integration/requirements.md diff --git a/.kiro/specs/070/puppetserver-integration/tasks.md b/.kiro/specs/done/070/puppetserver-integration/tasks.md similarity index 100% rename from .kiro/specs/070/puppetserver-integration/tasks.md rename to .kiro/specs/done/070/puppetserver-integration/tasks.md diff --git a/.kiro/specs/090/inventory-node-groups/.config.kiro b/.kiro/specs/done/090/inventory-node-groups/.config.kiro similarity index 100% rename from .kiro/specs/090/inventory-node-groups/.config.kiro rename to .kiro/specs/done/090/inventory-node-groups/.config.kiro diff --git a/.kiro/specs/090/inventory-node-groups/design.md b/.kiro/specs/done/090/inventory-node-groups/design.md similarity index 100% rename from .kiro/specs/090/inventory-node-groups/design.md rename to .kiro/specs/done/090/inventory-node-groups/design.md diff --git a/.kiro/specs/090/inventory-node-groups/requirements.md b/.kiro/specs/done/090/inventory-node-groups/requirements.md similarity index 100% rename from .kiro/specs/090/inventory-node-groups/requirements.md rename to .kiro/specs/done/090/inventory-node-groups/requirements.md diff --git a/.kiro/specs/090/inventory-node-groups/tasks.md b/.kiro/specs/done/090/inventory-node-groups/tasks.md similarity index 100% rename from .kiro/specs/090/inventory-node-groups/tasks.md rename to .kiro/specs/done/090/inventory-node-groups/tasks.md diff --git a/.kiro/specs/090/parallel-execution-ui/.config.kiro b/.kiro/specs/done/090/parallel-execution-ui/.config.kiro similarity index 100% rename from .kiro/specs/090/parallel-execution-ui/.config.kiro rename to .kiro/specs/done/090/parallel-execution-ui/.config.kiro diff --git a/.kiro/specs/090/parallel-execution-ui/design.md b/.kiro/specs/done/090/parallel-execution-ui/design.md similarity index 100% rename from .kiro/specs/090/parallel-execution-ui/design.md rename to .kiro/specs/done/090/parallel-execution-ui/design.md diff --git a/.kiro/specs/090/parallel-execution-ui/requirements.md b/.kiro/specs/done/090/parallel-execution-ui/requirements.md similarity index 100% rename from .kiro/specs/090/parallel-execution-ui/requirements.md rename to .kiro/specs/done/090/parallel-execution-ui/requirements.md diff --git a/.kiro/specs/090/parallel-execution-ui/tasks.md b/.kiro/specs/done/090/parallel-execution-ui/tasks.md similarity index 100% rename from .kiro/specs/090/parallel-execution-ui/tasks.md rename to .kiro/specs/done/090/parallel-execution-ui/tasks.md diff --git a/.kiro/specs/090/proxmox-frontend-ui/.config.kiro b/.kiro/specs/done/090/proxmox-frontend-ui/.config.kiro similarity index 100% rename from .kiro/specs/090/proxmox-frontend-ui/.config.kiro rename to .kiro/specs/done/090/proxmox-frontend-ui/.config.kiro diff --git a/.kiro/specs/090/proxmox-frontend-ui/design.md b/.kiro/specs/done/090/proxmox-frontend-ui/design.md similarity index 100% rename from .kiro/specs/090/proxmox-frontend-ui/design.md rename to .kiro/specs/done/090/proxmox-frontend-ui/design.md diff --git a/.kiro/specs/090/proxmox-frontend-ui/requirements.md b/.kiro/specs/done/090/proxmox-frontend-ui/requirements.md similarity index 100% rename from .kiro/specs/090/proxmox-frontend-ui/requirements.md rename to .kiro/specs/done/090/proxmox-frontend-ui/requirements.md diff --git a/.kiro/specs/090/proxmox-frontend-ui/tasks.md b/.kiro/specs/done/090/proxmox-frontend-ui/tasks.md similarity index 100% rename from .kiro/specs/090/proxmox-frontend-ui/tasks.md rename to .kiro/specs/done/090/proxmox-frontend-ui/tasks.md diff --git a/.kiro/specs/090/proxmox-integration/.config.kiro b/.kiro/specs/done/090/proxmox-integration/.config.kiro similarity index 100% rename from .kiro/specs/090/proxmox-integration/.config.kiro rename to .kiro/specs/done/090/proxmox-integration/.config.kiro diff --git a/.kiro/specs/090/proxmox-integration/design.md b/.kiro/specs/done/090/proxmox-integration/design.md similarity index 100% rename from .kiro/specs/090/proxmox-integration/design.md rename to .kiro/specs/done/090/proxmox-integration/design.md diff --git a/.kiro/specs/090/proxmox-integration/requirements.md b/.kiro/specs/done/090/proxmox-integration/requirements.md similarity index 100% rename from .kiro/specs/090/proxmox-integration/requirements.md rename to .kiro/specs/done/090/proxmox-integration/requirements.md diff --git a/.kiro/specs/090/proxmox-integration/tasks.md b/.kiro/specs/done/090/proxmox-integration/tasks.md similarity index 100% rename from .kiro/specs/090/proxmox-integration/tasks.md rename to .kiro/specs/done/090/proxmox-integration/tasks.md diff --git a/.kiro/specs/090/puppet-pabawi-refactoring/.config.kiro b/.kiro/specs/done/090/puppet-pabawi-refactoring/.config.kiro similarity index 100% rename from .kiro/specs/090/puppet-pabawi-refactoring/.config.kiro rename to .kiro/specs/done/090/puppet-pabawi-refactoring/.config.kiro diff --git a/.kiro/specs/090/puppet-pabawi-refactoring/design.md b/.kiro/specs/done/090/puppet-pabawi-refactoring/design.md similarity index 100% rename from .kiro/specs/090/puppet-pabawi-refactoring/design.md rename to .kiro/specs/done/090/puppet-pabawi-refactoring/design.md diff --git a/.kiro/specs/090/puppet-pabawi-refactoring/requirements.md b/.kiro/specs/done/090/puppet-pabawi-refactoring/requirements.md similarity index 100% rename from .kiro/specs/090/puppet-pabawi-refactoring/requirements.md rename to .kiro/specs/done/090/puppet-pabawi-refactoring/requirements.md diff --git a/.kiro/specs/090/puppet-pabawi-refactoring/tasks.md b/.kiro/specs/done/090/puppet-pabawi-refactoring/tasks.md similarity index 100% rename from .kiro/specs/090/puppet-pabawi-refactoring/tasks.md rename to .kiro/specs/done/090/puppet-pabawi-refactoring/tasks.md diff --git a/.kiro/specs/090/rbac-authorization/.config.kiro b/.kiro/specs/done/090/rbac-authorization/.config.kiro similarity index 100% rename from .kiro/specs/090/rbac-authorization/.config.kiro rename to .kiro/specs/done/090/rbac-authorization/.config.kiro diff --git a/.kiro/specs/090/rbac-authorization/design.md b/.kiro/specs/done/090/rbac-authorization/design.md similarity index 100% rename from .kiro/specs/090/rbac-authorization/design.md rename to .kiro/specs/done/090/rbac-authorization/design.md diff --git a/.kiro/specs/090/rbac-authorization/requirements.md b/.kiro/specs/done/090/rbac-authorization/requirements.md similarity index 100% rename from .kiro/specs/090/rbac-authorization/requirements.md rename to .kiro/specs/done/090/rbac-authorization/requirements.md diff --git a/.kiro/specs/090/rbac-authorization/tasks.md b/.kiro/specs/done/090/rbac-authorization/tasks.md similarity index 100% rename from .kiro/specs/090/rbac-authorization/tasks.md rename to .kiro/specs/done/090/rbac-authorization/tasks.md diff --git a/.kiro/specs/090/ssh-integration/.config.kiro b/.kiro/specs/done/090/ssh-integration/.config.kiro similarity index 100% rename from .kiro/specs/090/ssh-integration/.config.kiro rename to .kiro/specs/done/090/ssh-integration/.config.kiro diff --git a/.kiro/specs/090/ssh-integration/design.md b/.kiro/specs/done/090/ssh-integration/design.md similarity index 100% rename from .kiro/specs/090/ssh-integration/design.md rename to .kiro/specs/done/090/ssh-integration/design.md diff --git a/.kiro/specs/090/ssh-integration/requirements.md b/.kiro/specs/done/090/ssh-integration/requirements.md similarity index 100% rename from .kiro/specs/090/ssh-integration/requirements.md rename to .kiro/specs/done/090/ssh-integration/requirements.md diff --git a/.kiro/specs/090/ssh-integration/tasks.md b/.kiro/specs/done/090/ssh-integration/tasks.md similarity index 100% rename from .kiro/specs/090/ssh-integration/tasks.md rename to .kiro/specs/done/090/ssh-integration/tasks.md diff --git a/.kiro/specs/azure-integration/.config.kiro b/.kiro/specs/done/azure-integration/.config.kiro similarity index 100% rename from .kiro/specs/azure-integration/.config.kiro rename to .kiro/specs/done/azure-integration/.config.kiro diff --git a/.kiro/specs/azure-integration/design.md b/.kiro/specs/done/azure-integration/design.md similarity index 100% rename from .kiro/specs/azure-integration/design.md rename to .kiro/specs/done/azure-integration/design.md diff --git a/.kiro/specs/azure-integration/requirements.md b/.kiro/specs/done/azure-integration/requirements.md similarity index 100% rename from .kiro/specs/azure-integration/requirements.md rename to .kiro/specs/done/azure-integration/requirements.md diff --git a/.kiro/specs/azure-integration/tasks.md b/.kiro/specs/done/azure-integration/tasks.md similarity index 100% rename from .kiro/specs/azure-integration/tasks.md rename to .kiro/specs/done/azure-integration/tasks.md diff --git a/.kiro/specs/checkmk-integration/.config.kiro b/.kiro/specs/done/checkmk-integration/.config.kiro similarity index 100% rename from .kiro/specs/checkmk-integration/.config.kiro rename to .kiro/specs/done/checkmk-integration/.config.kiro diff --git a/.kiro/specs/checkmk-integration/design.md b/.kiro/specs/done/checkmk-integration/design.md similarity index 100% rename from .kiro/specs/checkmk-integration/design.md rename to .kiro/specs/done/checkmk-integration/design.md diff --git a/.kiro/specs/checkmk-integration/requirements.md b/.kiro/specs/done/checkmk-integration/requirements.md similarity index 100% rename from .kiro/specs/checkmk-integration/requirements.md rename to .kiro/specs/done/checkmk-integration/requirements.md diff --git a/.kiro/specs/checkmk-integration/tasks.md b/.kiro/specs/done/checkmk-integration/tasks.md similarity index 100% rename from .kiro/specs/checkmk-integration/tasks.md rename to .kiro/specs/done/checkmk-integration/tasks.md diff --git a/.kiro/specs/code-review-fixes/.config.kiro b/.kiro/specs/done/code-review-fixes/.config.kiro similarity index 100% rename from .kiro/specs/code-review-fixes/.config.kiro rename to .kiro/specs/done/code-review-fixes/.config.kiro diff --git a/.kiro/specs/code-review-fixes/design.md b/.kiro/specs/done/code-review-fixes/design.md similarity index 100% rename from .kiro/specs/code-review-fixes/design.md rename to .kiro/specs/done/code-review-fixes/design.md diff --git a/.kiro/specs/code-review-fixes/requirements.md b/.kiro/specs/done/code-review-fixes/requirements.md similarity index 100% rename from .kiro/specs/code-review-fixes/requirements.md rename to .kiro/specs/done/code-review-fixes/requirements.md diff --git a/.kiro/specs/code-review-fixes/tasks.md b/.kiro/specs/done/code-review-fixes/tasks.md similarity index 100% rename from .kiro/specs/code-review-fixes/tasks.md rename to .kiro/specs/done/code-review-fixes/tasks.md diff --git a/.kiro/specs/journal-enhancements/.config.kiro b/.kiro/specs/done/journal-enhancements/.config.kiro similarity index 100% rename from .kiro/specs/journal-enhancements/.config.kiro rename to .kiro/specs/done/journal-enhancements/.config.kiro diff --git a/.kiro/specs/journal-enhancements/design.md b/.kiro/specs/done/journal-enhancements/design.md similarity index 100% rename from .kiro/specs/journal-enhancements/design.md rename to .kiro/specs/done/journal-enhancements/design.md diff --git a/.kiro/specs/journal-enhancements/requirements.md b/.kiro/specs/done/journal-enhancements/requirements.md similarity index 100% rename from .kiro/specs/journal-enhancements/requirements.md rename to .kiro/specs/done/journal-enhancements/requirements.md diff --git a/.kiro/specs/journal-enhancements/tasks.md b/.kiro/specs/done/journal-enhancements/tasks.md similarity index 100% rename from .kiro/specs/journal-enhancements/tasks.md rename to .kiro/specs/done/journal-enhancements/tasks.md diff --git a/.kiro/specs/missing-lifecycle-actions/.config.kiro b/.kiro/specs/done/missing-lifecycle-actions/.config.kiro similarity index 100% rename from .kiro/specs/missing-lifecycle-actions/.config.kiro rename to .kiro/specs/done/missing-lifecycle-actions/.config.kiro diff --git a/.kiro/specs/missing-lifecycle-actions/bugfix.md b/.kiro/specs/done/missing-lifecycle-actions/bugfix.md similarity index 100% rename from .kiro/specs/missing-lifecycle-actions/bugfix.md rename to .kiro/specs/done/missing-lifecycle-actions/bugfix.md diff --git a/.kiro/specs/pabawi-release-1-0-0/.config.kiro b/.kiro/specs/done/pabawi-release-1-0-0/.config.kiro similarity index 100% rename from .kiro/specs/pabawi-release-1-0-0/.config.kiro rename to .kiro/specs/done/pabawi-release-1-0-0/.config.kiro diff --git a/.kiro/specs/pabawi-release-1-0-0/design.md b/.kiro/specs/done/pabawi-release-1-0-0/design.md similarity index 100% rename from .kiro/specs/pabawi-release-1-0-0/design.md rename to .kiro/specs/done/pabawi-release-1-0-0/design.md diff --git a/.kiro/specs/pabawi-release-1-0-0/requirements.md b/.kiro/specs/done/pabawi-release-1-0-0/requirements.md similarity index 100% rename from .kiro/specs/pabawi-release-1-0-0/requirements.md rename to .kiro/specs/done/pabawi-release-1-0-0/requirements.md diff --git a/.kiro/specs/pabawi-release-1-0-0/tasks.md b/.kiro/specs/done/pabawi-release-1-0-0/tasks.md similarity index 100% rename from .kiro/specs/pabawi-release-1-0-0/tasks.md rename to .kiro/specs/done/pabawi-release-1-0-0/tasks.md diff --git a/.kiro/specs/rbac-and-mcp-server/.config.kiro b/.kiro/specs/done/rbac-and-mcp-server/.config.kiro similarity index 100% rename from .kiro/specs/rbac-and-mcp-server/.config.kiro rename to .kiro/specs/done/rbac-and-mcp-server/.config.kiro diff --git a/.kiro/specs/rbac-and-mcp-server/design.md b/.kiro/specs/done/rbac-and-mcp-server/design.md similarity index 100% rename from .kiro/specs/rbac-and-mcp-server/design.md rename to .kiro/specs/done/rbac-and-mcp-server/design.md diff --git a/.kiro/specs/rbac-and-mcp-server/requirements.md b/.kiro/specs/done/rbac-and-mcp-server/requirements.md similarity index 100% rename from .kiro/specs/rbac-and-mcp-server/requirements.md rename to .kiro/specs/done/rbac-and-mcp-server/requirements.md diff --git a/.kiro/specs/rbac-and-mcp-server/tasks.md b/.kiro/specs/done/rbac-and-mcp-server/tasks.md similarity index 100% rename from .kiro/specs/rbac-and-mcp-server/tasks.md rename to .kiro/specs/done/rbac-and-mcp-server/tasks.md diff --git a/.kiro/specs/v1-release-prep/.config.kiro b/.kiro/specs/done/v1-release-prep/.config.kiro similarity index 100% rename from .kiro/specs/v1-release-prep/.config.kiro rename to .kiro/specs/done/v1-release-prep/.config.kiro diff --git a/.kiro/specs/v1-release-prep/design.md b/.kiro/specs/done/v1-release-prep/design.md similarity index 100% rename from .kiro/specs/v1-release-prep/design.md rename to .kiro/specs/done/v1-release-prep/design.md diff --git a/.kiro/specs/v1-release-prep/requirements.md b/.kiro/specs/done/v1-release-prep/requirements.md similarity index 100% rename from .kiro/specs/v1-release-prep/requirements.md rename to .kiro/specs/done/v1-release-prep/requirements.md diff --git a/.kiro/specs/v1-release-prep/tasks.md b/.kiro/specs/done/v1-release-prep/tasks.md similarity index 100% rename from .kiro/specs/v1-release-prep/tasks.md rename to .kiro/specs/done/v1-release-prep/tasks.md From ba68bb97f243403d4346fb28f5fb68cde6e29512 Mon Sep 17 00:00:00 2001 From: Alessandro Franceschi Date: Sat, 13 Jun 2026 08:25:46 +0200 Subject: [PATCH 05/13] feat(console): implement console integration framework with session management and UI widgets - Add ConsolePlugin interface and console-specific types for transports, capabilities, and session states - Implement ConsoleSessionManager service with token generation, session CRUD, validation, and concurrent limits - Add ConsoleWebSocketProxy service for VNC/SPICE protocol relay and binary stream handling - Create console configuration schema with timeout, duration, and heartbeat parameters - Add database migrations for console_sessions and console_permissions tables with RBAC integration - Implement Proxmox console provider for VNC access to virtual machines - Add /console API routes for session creation, validation, connection, and termination - Create 14 property-based tests covering token validation, RBAC, availability, binary relay, malformed input handling, and concurrent limits - Add frontend widgets: ConsoleViewer, ConsoleAccessWidget, GeneralInfoWidget, LatestActionsWidget, MonitoringSummaryWidget, PuppetRunsWidget - Implement widget grid layout system with dynamic widget registry for node detail page - Add ActionRow and WidgetFrame components for consistent widget presentation - Include comprehensive audit logging for all console session operations - Update configuration service to parse and validate console environment variables - Completes console integration specification with full end-to-end functionality from session creation to user access and monitoring --- .kiro/specs/console-integration/tasks.md | 82 +- .../node-overview-widget-grid/.config.kiro | 1 + .../specs/node-overview-widget-grid/design.md | 534 +++++ .../node-overview-widget-grid/requirements.md | 110 ++ .../specs/node-overview-widget-grid/tasks.md | 142 ++ backend/package.json | 6 +- backend/src/config/ConfigService.ts | 85 + backend/src/config/schema.ts | 13 + .../migrations/018_console_sessions.sql | 28 + .../migrations/019_console_permissions.sql | 32 + .../src/integrations/IntegrationManager.ts | 129 ++ backend/src/integrations/console/types.ts | 79 + .../proxmox/ProxmoxConsoleProvider.ts | 406 ++++ backend/src/routes/console.ts | 300 +++ backend/src/server.ts | 83 + backend/src/services/ConsoleSessionManager.ts | 339 ++++ backend/src/services/ConsoleWebSocketProxy.ts | 321 +++ backend/test/config/ConsoleConfig.test.ts | 182 ++ .../database/migration-integration.test.ts | 10 +- .../consoleAuditLog.property.test.ts | 223 +++ .../consoleAvailability.property.test.ts | 162 ++ .../consoleBinaryRelay.property.test.ts | 286 +++ .../consoleConcurrentLimit.property.test.ts | 263 +++ .../properties/consoleConfig.property.test.ts | 256 +++ .../consoleGuestRouting.property.test.ts | 152 ++ .../consoleMalformedControl.property.test.ts | 295 +++ .../consoleNonRunningGuest.property.test.ts | 220 +++ ...nsoleProviderRegistration.property.test.ts | 189 ++ .../consoleRbacCreation.property.test.ts | 240 +++ .../consoleRbacTermination.property.test.ts | 302 +++ .../consoleResizeValidation.property.test.ts | 268 +++ .../consoleSessionRecord.property.test.ts | 196 ++ .../consoleTokenValidation.property.test.ts | 325 ++++ .../consoleUnhealthyProvider.property.test.ts | 334 ++++ .../consoleUnsupportedNode.property.test.ts | 151 ++ frontend/package.json | 4 + frontend/src/components/ActionRow.svelte | 19 + .../src/components/ConsoleAccessWidget.svelte | 59 + frontend/src/components/ConsoleViewer.svelte | 403 ++++ .../src/components/GeneralInfoWidget.svelte | 234 +++ .../src/components/LatestActionsWidget.svelte | 97 + .../components/MonitoringSummaryWidget.svelte | 147 ++ .../src/components/PuppetRunsWidget.svelte | 241 +++ frontend/src/components/WidgetFrame.svelte | 76 + frontend/src/components/WidgetGrid.svelte | 69 + frontend/src/lib/widgetRegistry.svelte.ts | 92 + .../src/lib/widgets/consoleAccess.widget.ts | 12 + .../src/lib/widgets/generalInfo.widget.ts | 12 + frontend/src/lib/widgets/index.ts | 8 + .../src/lib/widgets/latestActions.widget.ts | 12 + .../lib/widgets/monitoringSummary.widget.ts | 12 + frontend/src/lib/widgets/puppetRuns.widget.ts | 12 + frontend/src/novnc.d.ts | 21 + frontend/src/pages/NodeDetailPage.svelte | 589 +----- package-lock.json | 1720 +++++++++-------- 55 files changed, 9193 insertions(+), 1390 deletions(-) create mode 100644 .kiro/specs/node-overview-widget-grid/.config.kiro create mode 100644 .kiro/specs/node-overview-widget-grid/design.md create mode 100644 .kiro/specs/node-overview-widget-grid/requirements.md create mode 100644 .kiro/specs/node-overview-widget-grid/tasks.md create mode 100644 backend/src/database/migrations/018_console_sessions.sql create mode 100644 backend/src/database/migrations/019_console_permissions.sql create mode 100644 backend/src/integrations/console/types.ts create mode 100644 backend/src/integrations/proxmox/ProxmoxConsoleProvider.ts create mode 100644 backend/src/routes/console.ts create mode 100644 backend/src/services/ConsoleSessionManager.ts create mode 100644 backend/src/services/ConsoleWebSocketProxy.ts create mode 100644 backend/test/config/ConsoleConfig.test.ts create mode 100644 backend/test/properties/consoleAuditLog.property.test.ts create mode 100644 backend/test/properties/consoleAvailability.property.test.ts create mode 100644 backend/test/properties/consoleBinaryRelay.property.test.ts create mode 100644 backend/test/properties/consoleConcurrentLimit.property.test.ts create mode 100644 backend/test/properties/consoleConfig.property.test.ts create mode 100644 backend/test/properties/consoleGuestRouting.property.test.ts create mode 100644 backend/test/properties/consoleMalformedControl.property.test.ts create mode 100644 backend/test/properties/consoleNonRunningGuest.property.test.ts create mode 100644 backend/test/properties/consoleProviderRegistration.property.test.ts create mode 100644 backend/test/properties/consoleRbacCreation.property.test.ts create mode 100644 backend/test/properties/consoleRbacTermination.property.test.ts create mode 100644 backend/test/properties/consoleResizeValidation.property.test.ts create mode 100644 backend/test/properties/consoleSessionRecord.property.test.ts create mode 100644 backend/test/properties/consoleTokenValidation.property.test.ts create mode 100644 backend/test/properties/consoleUnhealthyProvider.property.test.ts create mode 100644 backend/test/properties/consoleUnsupportedNode.property.test.ts create mode 100644 frontend/src/components/ActionRow.svelte create mode 100644 frontend/src/components/ConsoleAccessWidget.svelte create mode 100644 frontend/src/components/ConsoleViewer.svelte create mode 100644 frontend/src/components/GeneralInfoWidget.svelte create mode 100644 frontend/src/components/LatestActionsWidget.svelte create mode 100644 frontend/src/components/MonitoringSummaryWidget.svelte create mode 100644 frontend/src/components/PuppetRunsWidget.svelte create mode 100644 frontend/src/components/WidgetFrame.svelte create mode 100644 frontend/src/components/WidgetGrid.svelte create mode 100644 frontend/src/lib/widgetRegistry.svelte.ts create mode 100644 frontend/src/lib/widgets/consoleAccess.widget.ts create mode 100644 frontend/src/lib/widgets/generalInfo.widget.ts create mode 100644 frontend/src/lib/widgets/index.ts create mode 100644 frontend/src/lib/widgets/latestActions.widget.ts create mode 100644 frontend/src/lib/widgets/monitoringSummary.widget.ts create mode 100644 frontend/src/lib/widgets/puppetRuns.widget.ts create mode 100644 frontend/src/novnc.d.ts diff --git a/.kiro/specs/console-integration/tasks.md b/.kiro/specs/console-integration/tasks.md index 01809da4..4fb928b0 100644 --- a/.kiro/specs/console-integration/tasks.md +++ b/.kiro/specs/console-integration/tasks.md @@ -6,89 +6,89 @@ This plan implements the console integration framework for Pabawi — a plugin-b ## Tasks -- [ ] 1. Core types, configuration, and database schema - - [ ] 1.1 Define ConsolePlugin interface and related types +- [x] 1. Core types, configuration, and database schema + - [x] 1.1 Define ConsolePlugin interface and related types - Create `backend/src/integrations/console/types.ts` with `ConsoleTransport`, `ConsoleCapability`, `ConsoleSessionState`, `ConsoleSessionStatus`, `ConsoleSession`, and `ConsolePlugin` interface extending `IntegrationPlugin` - Export all types for use by providers, session manager, and routes - _Requirements: 1.1, 1.2, 1.3, 1.5, 1.6, 1.7_ - - [ ] 1.2 Add console configuration to ConfigService and schema + - [x] 1.2 Add console configuration to ConfigService and schema - Add `ConsoleConfigSchema` to `backend/src/config/schema.ts` with `sessionTimeoutMs`, `maxSessionDuration`, `maxConcurrentSessions`, `heartbeatIntervalMs` - Add console config parsing in `ConfigService` from `CONSOLE_*` env vars with validation (positive int, min 1 for concurrent sessions, heartbeat < timeout cross-check) - Log warnings for invalid values and fall back to defaults - _Requirements: 11.1, 11.2, 11.3, 11.4, 11.5, 11.6_ - - [ ]* 1.3 Write property test for configuration parsing (Property 14) + - [x] 1.3 Write property test for configuration parsing (Property 14) - **Property 14: Configuration parsing with defaults** - Generate random env var values (non-numeric, negative, zero, floats, valid) and verify defaults are applied for invalid values, heartbeat >= timeout triggers both defaults - **Validates: Requirements 11.1, 11.2, 11.3, 11.4, 11.5, 11.6** - - [ ] 1.4 Create database migration 018_console_sessions.sql + - [x] 1.4 Create database migration 018_console_sessions.sql - Create `backend/src/database/migrations/018_console_sessions.sql` with `console_sessions` table (snake_case columns), indexes on `user_id`, `state`, `token` - Include CHECK constraints for `state` and `transport` columns - _Requirements: 2.7_ - - [ ] 1.5 Create database migration 019_console_permissions.sql + - [x] 1.5 Create database migration 019_console_permissions.sql - Create `backend/src/database/migrations/019_console_permissions.sql` inserting `console:access` and `console:admin` permissions - Grant `console:access` to operator and admin roles, `console:admin` to admin only - _Requirements: 6.1, 6.7_ -- [ ] 2. Checkpoint - Ensure all tests pass +- [x] 2. Checkpoint - Ensure all tests pass - Ensure all tests pass, ask the user if questions arise. -- [ ] 3. ConsoleSessionManager service - - [ ] 3.1 Implement ConsoleSessionManager +- [x] 3. ConsoleSessionManager service + - [x] 3.1 Implement ConsoleSessionManager - Create `backend/src/services/ConsoleSessionManager.ts` with token generation (crypto.randomBytes 32+), session CRUD, token validation (exists, <60s, not consumed, owner match), heartbeat recording, concurrent session counting, provider-level bulk termination, expired session cleanup - Use `DatabaseAdapter` for all DB operations with snake_case columns and camelCase aliases in SELECTs - Integrate `AuditLoggingService` for session create/terminate events - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 8.1, 8.2, 8.4, 8.6, 8.7_ - - [ ]* 3.2 Write property test for session token validation (Property 2) + - [x] 3.2 Write property test for session token validation (Property 2) - **Property 2: Session token validation correctness** - Generate random tokens, timestamps, user IDs. Token accepted iff: exists in DB, created <60s ago, not consumed, connecting user matches owner. All others rejected. - **Validates: Requirements 4.2, 4.3, 5.2, 5.3, 8.1, 8.2** - - [ ]* 3.3 Write property test for concurrent session limit (Property 7) + - [x] 3.3 Write property test for concurrent session limit (Property 7) - **Property 7: Concurrent session limit enforcement** - Generate random session counts and verify that when active count >= maxConcurrentSessions, new creation is rejected with 429 semantics. - **Validates: Requirements 8.6** - - [ ]* 3.4 Write property test for session record completeness (Property 8) + - [x] 3.4 Write property test for session record completeness (Property 8) - **Property 8: Session record completeness** - Generate random session inputs and verify stored record always has non-null sessionId, userId, nodeId, provider, createdAt, lastHeartbeatAt. - **Validates: Requirements 2.7** - - [ ]* 3.5 Write property test for audit log completeness (Property 9) + - [x] 3.5 Write property test for audit log completeness (Property 9) - **Property 9: Audit log completeness for session events** - Generate random session create/terminate events. Verify audit entry always contains userId, nodeId, provider, action, ISO 8601 timestamp. - **Validates: Requirements 8.4** -- [ ] 4. Checkpoint - Ensure all tests pass +- [x] 4. Checkpoint - Ensure all tests pass - Ensure all tests pass, ask the user if questions arise. -- [ ] 5. IntegrationManager extension and console availability - - [ ] 5.1 Extend IntegrationManager with console provider support +- [x] 5. IntegrationManager extension and console availability + - [x] 5.1 Extend IntegrationManager with console provider support - Add `consoleProviders` map, `isConsolePlugin` type guard, registration logic in `registerPlugin`, and public methods `getConsoleProvider`, `getAllConsoleProviders`, `getConsoleAvailability` - Console availability queries all providers in parallel with 3s timeout, excludes timed-out providers, sorts results by provider name ascending - _Requirements: 1.4, 3.1, 3.2, 3.3, 3.4, 3.5, 10.1_ - - [ ]* 5.2 Write property test for availability response ordering (Property 10) + - [x] 5.2 Write property test for availability response ordering (Property 10) - **Property 10: Availability response structure and ordering** - Generate random provider name arrays. Verify response entries contain provider name, transport, display label; entries sorted alphabetically by provider name. - **Validates: Requirements 3.3, 3.4** - - [ ]* 5.3 Write property test for unsupported node empty response (Property 11) + - [x] 5.3 Write property test for unsupported node empty response (Property 11) - **Property 11: Unsupported node returns empty availability** - Generate random node IDs not supported by any registered provider. Verify availability returns empty array. - **Validates: Requirements 3.2** - - [ ]* 5.4 Write property test for unhealthy provider exclusion (Property 15) + - [x] 5.4 Write property test for unhealthy provider exclusion (Property 15) - **Property 15: Unhealthy provider exclusion** - Generate random provider health states. Verify unavailable/unhealthy providers are excluded from availability while healthy providers are included. - **Validates: Requirements 10.1** -- [ ] 6. WebSocket proxy server - - [ ] 6.1 Implement ConsoleWebSocketProxy +- [x] 6. WebSocket proxy server + - [x] 6.1 Implement ConsoleWebSocketProxy - Create `backend/src/services/ConsoleWebSocketProxy.ts` using `ws` library attached to existing HTTP server with `noServer: true` - Handle `upgrade` event with path-based routing (`/ws/console/vnc`, `/ws/console/terminal`) - Validate origin header against configured allowed origins @@ -104,26 +104,26 @@ This plan implements the console integration framework for Pabawi — a plugin-b - Handle invalid/expired token (close with 4401) - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7, 4.8, 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 8.5, 8.7_ - - [ ]* 6.2 Write property test for binary frame relay integrity (Property 3) + - [x] 6.2 Write property test for binary frame relay integrity (Property 3) - **Property 3: Binary frame relay integrity** - Generate random binary buffers. Verify frames pass through the proxy byte-for-byte identical. - **Validates: Requirements 4.4** - - [ ]* 6.3 Write property test for terminal resize validation (Property 4) + - [x] 6.3 Write property test for terminal resize validation (Property 4) - **Property 4: Terminal resize dimension validation** - Generate random column/row pairs. Verify resize propagated iff columns in [1,500] and rows in [1,200]; otherwise discarded without session termination. - **Validates: Requirements 5.5, 5.8** - - [ ]* 6.4 Write property test for malformed control message resilience (Property 16) + - [x] 6.4 Write property test for malformed control message resilience (Property 16) - **Property 16: Malformed control message resilience** - Generate random binary frames with unrecognized type bytes or truncated payloads. Verify discarded without session termination. - **Validates: Requirements 5.8** -- [ ] 7. Checkpoint - Ensure all tests pass +- [x] 7. Checkpoint - Ensure all tests pass - Ensure all tests pass, ask the user if questions arise. -- [ ] 8. ProxmoxConsoleProvider - - [ ] 8.1 Implement ProxmoxConsoleProvider +- [x] 8. ProxmoxConsoleProvider + - [x] 8.1 Implement ProxmoxConsoleProvider - Create `backend/src/integrations/proxmox/ProxmoxConsoleProvider.ts` implementing `ConsolePlugin` - Implement `getConsoleCapabilities`: check guest exists and is running, return `websocket-vnc` capability - Implement `createSession`: determine guest type (qemu/lxc), verify running state, call appropriate vncproxy endpoint, build upstream WS URL, generate session token, return ConsoleSession @@ -132,23 +132,23 @@ This plan implements the console integration framework for Pabawi — a plugin-b - Handle auth errors, non-running guest, connection timeout, resource not found from Proxmox API - _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7, 9.8, 1.6, 1.7_ - - [ ]* 8.2 Write property test for guest type routing (Property 12) + - [x] 8.2 Write property test for guest type routing (Property 12) - **Property 12: Guest type routing correctness** - Generate random guest types (qemu/lxc). Verify QEMU guests use `/qemu/{vmid}/vncproxy` and LXC guests use `/lxc/{vmid}/vncproxy`. - **Validates: Requirements 9.4** - - [ ]* 8.3 Write property test for non-running guest rejection (Property 13) + - [x] 8.3 Write property test for non-running guest rejection (Property 13) - **Property 13: Non-running guest rejection** - Generate random guest states (running, stopped, paused, etc.). Verify session creation fails for any state other than "running" with appropriate error message. - **Validates: Requirements 9.6** - - [ ]* 8.4 Write property test for provider registration (Property 1) + - [x] 8.4 Write property test for provider registration (Property 1) - **Property 1: Console provider registration invariant** - Generate random plugin names. After registration with IntegrationManager, verify plugin appears in console providers map and is retrievable by name. - **Validates: Requirements 1.4** -- [ ] 9. Console REST routes - - [ ] 9.1 Implement console route factory and endpoints +- [x] 9. Console REST routes + - [x] 9.1 Implement console route factory and endpoints - Create `backend/src/routes/console.ts` exporting `createConsoleRouter(container, integrationManager, sessionManager, db)` - Implement `GET /api/console/availability/:nodeId` — RBAC check `console:access`, query availability via IntegrationManager - Implement `POST /api/console/sessions` — RBAC check `console:access`, check concurrent limit (429), create session via provider, store session @@ -157,18 +157,18 @@ This plan implements the console integration framework for Pabawi — a plugin-b - Implement `POST /api/console/sessions/:sessionId/heartbeat` — RBAC check `console:access`, record heartbeat - _Requirements: 6.2, 6.3, 6.4, 6.5, 6.6, 8.3, 8.6, 10.4_ - - [ ]* 9.2 Write property test for RBAC session creation (Property 5) + - [x] 9.2 Write property test for RBAC session creation (Property 5) - **Property 5: RBAC enforcement for session creation** - Generate random user/permission combinations. Verify session creation allowed iff user holds `console:access`; otherwise 403. - **Validates: Requirements 6.2, 6.3** - - [ ]* 9.3 Write property test for RBAC cross-user termination (Property 6) + - [x] 9.3 Write property test for RBAC cross-user termination (Property 6) - **Property 6: RBAC enforcement for cross-user termination** - Generate random user/owner/permission combinations. Verify cross-user termination requires `console:admin`; own session termination needs only `console:access`. - **Validates: Requirements 6.4, 6.5, 6.6, 8.3** -- [ ] 10. Wire backend components together - - [ ] 10.1 Register ProxmoxConsoleProvider and wire routes in server.ts +- [x] 10. Wire backend components together + - [x] 10.1 Register ProxmoxConsoleProvider and wire routes in server.ts - Register `ProxmoxConsoleProvider` with `IntegrationManager` in the plugin registry when Proxmox is enabled - Instantiate `ConsoleSessionManager` with DI container services - Instantiate `ConsoleWebSocketProxy` attached to the HTTP server @@ -177,11 +177,11 @@ This plan implements the console integration framework for Pabawi — a plugin-b - Start session cleanup interval - _Requirements: 2.6, 9.1_ -- [ ] 11. Checkpoint - Ensure all tests pass +- [x] 11. Checkpoint - Ensure all tests pass - Ensure all tests pass, ask the user if questions arise. -- [ ] 12. Frontend ConsoleViewer component - - [ ] 12.1 Implement ConsoleViewer Svelte 5 component +- [x] 12. Frontend ConsoleViewer component + - [x] 12.1 Implement ConsoleViewer Svelte 5 component - Create `frontend/src/components/ConsoleViewer.svelte` accepting `nodeId` and `capabilities` props - Render noVNC canvas for `websocket-vnc` transport, xterm.js terminal for `websocket-terminal` - Display connection status indicator (`connecting`, `connected`, `disconnected`) @@ -193,13 +193,13 @@ This plan implements the console integration framework for Pabawi — a plugin-b - Pass session token as query parameter on WebSocket URL - _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5, 7.6, 7.7, 7.8, 7.9_ - - [ ] 12.2 Implement console availability UI on node detail page + - [x] 12.2 Implement console availability UI on node detail page - Add console availability fetch (non-blocking async) to the node detail page - Show console options when available, hide all console UI when no providers available - Implement retry logic: up to 3 consecutive attempts on failure, then disable retry button with "provider unavailable" message - _Requirements: 10.2, 10.3, 10.5_ -- [ ] 13. Final checkpoint - Ensure all tests pass +- [x] 13. Final checkpoint - Ensure all tests pass - Ensure all tests pass, ask the user if questions arise. ## Notes diff --git a/.kiro/specs/node-overview-widget-grid/.config.kiro b/.kiro/specs/node-overview-widget-grid/.config.kiro new file mode 100644 index 00000000..e81f3f03 --- /dev/null +++ b/.kiro/specs/node-overview-widget-grid/.config.kiro @@ -0,0 +1 @@ +{"specId": "82458792-febb-45de-9d5d-b404052b2e56", "workflowType": "fast-task", "specType": "feature"} diff --git a/.kiro/specs/node-overview-widget-grid/design.md b/.kiro/specs/node-overview-widget-grid/design.md new file mode 100644 index 00000000..28e8f5c5 --- /dev/null +++ b/.kiro/specs/node-overview-widget-grid/design.md @@ -0,0 +1,534 @@ +# Design Document: Node Overview Widget Grid + +## Overview + +Reorganize the node detail overview tab into a composable, plugin-driven widget grid. Each integration plugin contributes one or more widgets via a frontend-only component registry. Widgets render in a 4-column responsive grid with priority-weighted ordering. Action buttons occupy a dedicated header row above the grid. Widgets load asynchronously and in parallel with graceful error handling per widget. + +## Architecture + +The widget grid system is a frontend-only architecture that transforms the node detail overview tab from a hard-coded layout into a composable, plugin-driven grid. Integration plugins contribute widgets through a central registry; the grid renders them in a priority-weighted 4-column layout after filtering out disabled integrations. + +``` +┌──────────────────────────────────────────────────┐ +│ Static Imports (side-effects at module load) │ +│ e.g. import '../widgets/generalInfo.widget' │ +│ import '../widgets/puppetRuns.widget' │ +└───────────────────────┬──────────────────────────┘ + │ registerWidget(def) + ▼ +┌──────────────────────────────────────────────────┐ +│ widgetRegistry.svelte.ts ($state collection) │ +│ - Widget_Definition[] │ +│ - getWidgets(): readonly Widget_Definition[] │ +└───────────────────────┬──────────────────────────┘ + │ consumed by + ▼ +┌──────────────────────────────────────────────────┐ +│ WidgetGrid.svelte │ +│ - Fetches /api/integrations/status │ +│ - Filters widgets by enabled integrations │ +│ - Separates "action" widgets → ActionRow │ +│ - Sorts by priority, renders WidgetFrame[] │ +└──────┬───────────────────────────────┬───────────┘ + │ │ + ▼ ▼ +┌──────────────┐ ┌───────────────────────┐ +│ ActionRow │ │ WidgetFrame.svelte │ +│ (flex row) │ │ (loading/error/content)│ +└──────────────┘ └───────────────────────┘ +``` + +## Components and Interfaces + +### 1. Widget Registry Module (`frontend/src/lib/widgetRegistry.svelte.ts`) + +Central store for widget definitions using Svelte 5 runes. + +```typescript +import type { Component } from 'svelte'; + +export type WidgetType = 'action' | 'list' | 'summary'; + +export interface WidgetDefinition { + /** Unique identifier for the widget */ + id: string; + /** Display name shown in error badges */ + name: string; + /** Svelte component to render */ + component: Component; + /** Integration name (must match /api/integrations/status response) */ + integration: string; + /** Widget category: determines placement (action → ActionRow, others → grid) */ + type: WidgetType; + /** Column span in the grid: 1, 2, or 3. Clamped to [1,3] on registration. */ + colSpan: number; + /** Numeric priority weight. Lower renders first. */ + priority: number; +} + +// Internal reactive state +let definitions = $state([]); + +/** + * Register a widget definition. Column span is clamped to [1,3]. + * Called at module load time as a side-effect of static imports. + */ +export function registerWidget(def: WidgetDefinition): void { + const clamped: WidgetDefinition = { + ...def, + colSpan: Math.max(1, Math.min(3, Math.round(def.colSpan))), + }; + definitions.push(clamped); +} + +/** + * Get all registered widget definitions (readonly snapshot). + */ +export function getWidgets(): readonly WidgetDefinition[] { + return definitions; +} + +/** + * Reset registry (used in tests only). + */ +export function _resetForTesting(): void { + definitions = []; +} +``` + +### 2. WidgetGrid Component (`frontend/src/components/WidgetGrid.svelte`) + +Orchestrator that fetches integration status, filters widgets, and renders the grid. + +```typescript + + +{#if statusError} +
+

+ Unable to load integration status: {statusError} +

+
+{:else} + {#if actionWidgets.length > 0} + + {/if} + +
+ {#each gridWidgets as widget (widget.id)} + + {/each} +
+{/if} +``` + +### 3. WidgetFrame Component (`frontend/src/components/WidgetFrame.svelte`) + +Container for each widget position. Manages loading, error, and content states. + +```typescript + + +
+ {#if state === 'loading'} +
+
+
+
+
+
+
+ {/if} + + {#if state === 'error'} +
+
+ {widget.integration} + {error} +
+ +
+ {/if} + + {#if state === 'loading' || state === 'ready'} +
+ {#key mountKey} + + {/key} +
+ {/if} +
+``` + +### 4. ActionRow Component (`frontend/src/components/ActionRow.svelte`) + +Horizontal flex container for action-type widgets. + +```typescript + + +{#if widgets.length > 0} +
+ {#each widgets as widget (widget.id)} + + {/each} +
+{/if} +``` + +### 5. Widget Self-Registration Pattern + +Each widget is a standalone module that registers itself as a side-effect. These modules are imported statically by the WidgetGrid (or a central barrel file) to guarantee registration before render. + +Example (`frontend/src/lib/widgets/generalInfo.widget.ts`): + +```typescript +import { registerWidget } from '../widgetRegistry.svelte'; +import GeneralInfoWidget from '../../components/GeneralInfoWidget.svelte'; + +registerWidget({ + id: 'core-general-info', + name: 'General Information', + component: GeneralInfoWidget, + integration: 'bolt', // always available when bolt is connected + type: 'summary', + colSpan: 2, + priority: 10, +}); +``` + +A barrel file (`frontend/src/lib/widgets/index.ts`) imports all widget registration modules: + +```typescript +// Core widgets +import './generalInfo.widget'; +import './latestActions.widget'; + +// Integration-dependent widgets +import './puppetRuns.widget'; +import './monitoringSummary.widget'; +import './consoleAccess.widget'; +``` + +The `WidgetGrid.svelte` imports this barrel file at the top of its script block, ensuring all widgets are registered before the first render. + +### 6. Integration Status Fetching + +The existing `GET /api/integrations/status` endpoint returns: + +```typescript +interface IntegrationStatusResponse { + integrations: Array<{ + name: string; + status: 'connected' | 'degraded' | 'not_configured' | 'error' | 'disconnected'; + type: 'execution' | 'information' | 'both'; + lastCheck?: string; + message?: string; + }>; +} +``` + +Filtering logic (pure function, testable independently): + +```typescript +export function filterWidgetsByStatus( + widgets: readonly WidgetDefinition[], + integrations: readonly IntegrationStatusEntry[], +): WidgetDefinition[] { + const enabled = new Set( + integrations + .filter(i => i.status === 'connected' || i.status === 'degraded') + .map(i => i.name), + ); + return widgets.filter(w => enabled.has(w.integration)); +} +``` + +### 7. Data Flow + +``` +Module load → widget registration side-effects fire → registry populated + │ +Page mount → WidgetGrid.svelte mounts ───────────────────►│ + │ │ + ├─ fetch /api/integrations/status │ + │ │ + ▼ ▼ + statusLoaded = true getWidgets() returns all defs + │ │ + └──── $derived: filterWidgetsByStatus ─────┘ + │ + ┌─────────────┼─────────────┐ + ▼ ▼ + actionWidgets gridWidgets + (type=action) (type=list|summary) + │ │ + ▼ ▼ + ActionRow CSS Grid with WidgetFrames + (flex-wrap) (4-col, responsive breakpoints) +``` + +### 8. Individual Widget Components (Migration) + +Each existing overview section becomes a standalone Svelte component: + +| Widget | Component | Type | Span | Priority | Integration | +|--------|-----------|------|------|----------|-------------| +| General Information | `GeneralInfoWidget.svelte` | summary | 2 | 10 | bolt | +| Latest Puppet Runs | `PuppetRunsWidget.svelte` | list | 3 | 100 | puppetdb | +| Latest Actions | `LatestActionsWidget.svelte` | list | 2 | 20 | bolt | +| Monitoring Summary | `MonitoringSummaryWidget.svelte` | summary | 2 | 100 | checkmk | +| Console Access | `ConsoleAccessWidget.svelte` | action | 1 | 100 | proxmox | + +The "General Information" and "Latest Actions" widgets use `bolt` as their integration since they rely on the core Bolt inventory which is always the base integration. Their priority values (10, 20) are lower than integration-contributed widgets (100+), ensuring they render first. + +### 9. Error Handling Strategy + +- **Per-widget isolation**: Each `WidgetFrame` catches errors from its child component independently. An error in one widget does not propagate to siblings. +- **Error badge**: Shows the integration name and a truncated error message within the widget's grid slot, preserving layout. +- **Retry**: A button in the error state increments a `mountKey`, causing Svelte's `{#key}` block to destroy and recreate the component. +- **Integration status error**: If the status endpoint fails entirely, no integration-dependent widgets render. A single inline notification explains the issue. + +### 10. Responsive Breakpoints + +The grid uses Tailwind's responsive prefixes: +- `grid-cols-1` (default, below `sm`) +- `sm:grid-cols-2` (≥640px) +- `lg:grid-cols-4` (≥1024px) + +Column spans are also responsive: +- `col-span-1` always applies at base +- `sm:col-span-N` applies at ≥640px +- `lg:col-span-N` applies at ≥1024px + +Below `sm`, all widgets collapse to full width regardless of declared span. + +## Data Models + +### WidgetDefinition + +```typescript +interface WidgetDefinition { + id: string; + name: string; + component: Component; + integration: string; + type: 'action' | 'list' | 'summary'; + colSpan: number; // clamped to [1,3] + priority: number; +} +``` + +### Widget Component Contract + +Every widget component must accept these props: + +```typescript +interface WidgetComponentProps { + nodeId: string; + onReady: () => void; + onError: (error: Error) => void; +} +``` + +The widget calls `onReady()` after its data loads successfully, and `onError(err)` if it fails. The `WidgetFrame` transitions states accordingly. + +### IntegrationStatusEntry + +```typescript +interface IntegrationStatusEntry { + name: string; + status: 'connected' | 'degraded' | 'not_configured' | 'error' | 'disconnected'; + type: 'execution' | 'information' | 'both'; +} +``` + +## Error Handling + +| Scenario | Behavior | +|----------|----------| +| Integration status endpoint fails | No integration widgets rendered; inline error notification | +| Widget throws on mount | Error badge with integration name + message; retry button | +| Widget throws during data fetch | Same as mount error (caught by onError callback) | +| Widget takes too long | Not enforced at frame level (individual widgets handle their own timeouts) | +| Unknown integration in widget def | Widget excluded from render (not in enabled set) | + +## Testing Strategy + +- **Unit tests** (Vitest + @testing-library/svelte): Verify individual component behavior — WidgetFrame states, ActionRow rendering, WidgetGrid filtering logic. +- **Property tests** (Vitest + fast-check): Validate universal properties of the registry (clamping, filtering, sorting) across randomized inputs. +- **Example tests**: Specific scenarios like error state rendering, retry behavior, empty action row. +- **E2E tests** (Playwright): Responsive breakpoints and full-page integration with real API responses. + +Unit tests cover the pure-logic layer (registry, filtering, sorting). Property tests target the 8 correctness properties below. Integration tests verify the component tree renders correctly with mocked API responses. + +## Correctness Properties + +*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* + +### Property 1: Registration preserves widget definitions + +For any valid WidgetDefinition, registering it in the Widget_Registry and then querying the registry SHALL return a definition with all original fields preserved (except colSpan which may be clamped). + +**Validates: Requirements 1.1, 1.2** + +### Property 2: Column span clamping + +For any integer value provided as colSpan during registration, the stored colSpan SHALL equal `Math.max(1, Math.min(3, Math.round(value)))`. + +**Validates: Requirements 1.3** + +### Property 3: Integration filtering + +For any set of registered WidgetDefinitions and any integration status response, the visible widget set SHALL contain exactly those widgets whose integration name appears in the status response with status "connected" or "degraded", and no others. + +**Validates: Requirements 2.2, 2.4** + +### Property 4: Stable priority ordering + +For any set of widgets rendered in the grid or action row, the rendered sequence SHALL be sorted by ascending priority weight, and widgets with equal priority weight SHALL appear in their original registration order (stable sort). + +**Validates: Requirements 3.2, 3.3, 4.3** + +### Property 5: Column span applied to frame element + +For any widget rendered in the grid, regardless of its internal state (loading, ready, or error), its containing frame element SHALL have a CSS class corresponding to its declared colSpan value. + +**Validates: Requirements 3.4, 5.4, 6.4** + +### Property 6: Action row composition + +For any set of visible widgets, the action row SHALL contain exactly those widgets with type "action" and no widgets of type "list" or "summary", rendered in ascending priority order. + +**Validates: Requirements 4.2, 4.3** + +### Property 7: Error badge content + +For any widget that throws an error, the displayed error badge SHALL contain the widget's integration name and a non-empty error summary string. + +**Validates: Requirements 6.1** + +### Property 8: Error isolation + +For any set of widgets where a subset throws errors, all non-erroring widgets SHALL render their content state independently and without interruption. + +**Validates: Requirements 6.3** diff --git a/.kiro/specs/node-overview-widget-grid/requirements.md b/.kiro/specs/node-overview-widget-grid/requirements.md new file mode 100644 index 00000000..e326e296 --- /dev/null +++ b/.kiro/specs/node-overview-widget-grid/requirements.md @@ -0,0 +1,110 @@ +# Requirements Document + +## Introduction + +Reorganize the node detail overview tab into a composable, plugin-driven widget grid. Each integration plugin contributes one or more widgets via a frontend-only component registry. Widgets render in a 4-column responsive grid with priority-weighted ordering. Action buttons occupy a dedicated header row above the grid. Widgets load asynchronously and in parallel with graceful error handling per widget. + +## Glossary + +- **Widget_Registry**: A frontend-only TypeScript module that maintains an ordered collection of widget definitions contributed by integration plugins +- **Widget_Definition**: A declarative descriptor containing a Svelte component reference, column span, priority weight, required integration name, and widget type +- **Widget_Grid**: A 4-column CSS grid layout that renders widget components according to their declared column spans and priority order +- **Action_Row**: A dedicated horizontal strip rendered between the page header and the Widget_Grid, containing action button widgets +- **Widget_Frame**: The container element rendered for each widget position in the grid, showing loading state until the widget component mounts +- **Integration_Status_Endpoint**: The existing `GET /api/integrations/status` backend endpoint that returns enabled/disabled state and health for each integration +- **Priority_Weight**: A numeric value declared per widget that determines render order within the grid (lower number renders first) +- **Column_Span**: An integer (1–3) declaring how many columns a widget occupies in the 4-column grid + +## Requirements + +### Requirement 1: Widget Registry + +**User Story:** As a plugin developer, I want to register widgets from my integration so that the overview tab dynamically displays plugin-contributed content without modifying the core page. + +#### Acceptance Criteria + +1. THE Widget_Registry SHALL expose a registration function that accepts a Widget_Definition containing: component reference, integration name, widget type, column span, and priority weight +2. THE Widget_Registry SHALL store all registered Widget_Definitions in a single ordered collection accessible at runtime +3. WHEN a Widget_Definition is registered with a column span value outside the range 1–3, THE Widget_Registry SHALL clamp the value to the nearest valid bound (1 or 3) +4. THE Widget_Registry SHALL accept Widget_Definitions with a widget type of "action", "list", or "summary" +5. THE Widget_Registry SHALL be implemented as a TypeScript module using Svelte 5 runes for reactive state + +### Requirement 2: Integration Filtering + +**User Story:** As an operator, I want the overview tab to display widgets only for integrations that are enabled and reachable so that I see relevant information without noise from disabled plugins. + +#### Acceptance Criteria + +1. WHEN the overview tab mounts, THE Widget_Grid SHALL fetch integration status from the Integration_Status_Endpoint +2. THE Widget_Grid SHALL render only Widget_Definitions whose declared integration name matches an integration with status "connected" or "degraded" from the Integration_Status_Endpoint response +3. WHEN the Integration_Status_Endpoint returns an error, THE Widget_Grid SHALL render no integration-dependent widgets and display a single inline error notification +4. IF a Widget_Definition declares an integration name that does not appear in the Integration_Status_Endpoint response, THEN THE Widget_Grid SHALL exclude that widget from rendering + +### Requirement 3: Widget Grid Layout + +**User Story:** As a user, I want the overview tab to display information in an organized grid so that I can scan node details at a glance. + +#### Acceptance Criteria + +1. THE Widget_Grid SHALL use a 4-column CSS grid layout with TailwindCSS utility classes +2. THE Widget_Grid SHALL render widgets in ascending Priority_Weight order (lowest weight first) +3. WHEN two widgets share the same Priority_Weight, THE Widget_Grid SHALL render them in registration order +4. THE Widget_Grid SHALL assign each widget a column span matching the widget's declared Column_Span value (1, 2, or 3 columns) +5. WHILE the viewport width is below the `sm` TailwindCSS breakpoint, THE Widget_Grid SHALL collapse to a single-column layout where each widget spans the full width +6. WHILE the viewport width is between the `sm` and `lg` TailwindCSS breakpoints, THE Widget_Grid SHALL use a 2-column layout + +### Requirement 4: Action Row + +**User Story:** As a user, I want quick-access action buttons (Run Puppet, VM controls, Console) rendered prominently above the detail grid so that I can take immediate actions without scrolling. + +#### Acceptance Criteria + +1. THE Action_Row SHALL render between the page header (hostname/metadata) and the Widget_Grid +2. THE Action_Row SHALL contain only widgets with widget type "action" +3. THE Action_Row SHALL render action widgets in ascending Priority_Weight order +4. THE Action_Row SHALL use a horizontal flex layout that wraps on smaller viewports +5. WHEN no action widgets are available (all associated integrations disabled), THE Action_Row SHALL not render any container element + +### Requirement 5: Async Widget Loading + +**User Story:** As a user, I want to see the grid frame immediately when the page loads so that I have spatial context while individual widgets fetch their data. + +#### Acceptance Criteria + +1. WHEN the overview tab renders, THE Widget_Grid SHALL display all Widget_Frames immediately with a loading skeleton placeholder +2. THE Widget_Grid SHALL mount all widget components in parallel without awaiting sequential completion +3. WHEN a widget component finishes loading its data, THE Widget_Frame SHALL replace the skeleton with the widget content without affecting other widgets +4. WHILE a widget is loading, THE Widget_Frame SHALL display an animated skeleton placeholder with dimensions matching the widget's declared Column_Span + +### Requirement 6: Widget Error Handling + +**User Story:** As a user, I want a widget that fails to load to show a contained error state so that one broken integration does not prevent me from using the rest of the overview. + +#### Acceptance Criteria + +1. IF a widget component throws an error during mount or data fetching, THEN THE Widget_Frame SHALL display an inline error badge showing the integration name and a short error summary +2. IF a widget component throws an error, THEN THE Widget_Frame SHALL offer a retry button that re-mounts the widget component +3. IF a widget component throws an error, THEN THE Widget_Grid SHALL continue rendering all other widgets without interruption +4. WHEN a widget error badge is displayed, THE Widget_Frame SHALL maintain its declared Column_Span to preserve grid layout stability + +### Requirement 7: No New Backend Endpoint + +**User Story:** As a developer, I want the widget registry to be purely frontend so that no backend changes are required for registration. + +#### Acceptance Criteria + +1. THE Widget_Registry SHALL operate entirely in the frontend without requiring a dedicated backend endpoint for widget metadata +2. THE Widget_Registry SHALL rely exclusively on the existing Integration_Status_Endpoint for determining which integrations are active +3. WHEN integration plugins register widgets, THE registration SHALL occur at module load time via static import side-effects + +### Requirement 8: Existing Widget Migration + +**User Story:** As a user, I want the current overview content (General Info, Latest Puppet Runs, Latest Actions, Monitoring Summary, Console) to appear in the new grid system so that no functionality is lost. + +#### Acceptance Criteria + +1. THE Widget_Registry SHALL include a "General Information" summary widget spanning 2 columns with Priority_Weight lower than all integration-contributed widgets +2. WHEN the puppetdb integration is enabled, THE Widget_Registry SHALL include a "Latest Puppet Runs" list widget spanning 3 columns +3. THE Widget_Registry SHALL include a "Latest Actions" list widget spanning 2 columns +4. WHEN the checkmk integration is enabled, THE Widget_Registry SHALL include a "Monitoring Summary" summary widget spanning 2 columns +5. WHEN console capabilities are available for the node, THE Widget_Registry SHALL include a "Console Access" action widget in the Action_Row diff --git a/.kiro/specs/node-overview-widget-grid/tasks.md b/.kiro/specs/node-overview-widget-grid/tasks.md new file mode 100644 index 00000000..0703acef --- /dev/null +++ b/.kiro/specs/node-overview-widget-grid/tasks.md @@ -0,0 +1,142 @@ +# Implementation Plan: Node Overview Widget Grid + +## Overview + +Refactor the node detail overview tab from a monolithic 2700-line page into a composable, plugin-driven widget grid. A frontend-only widget registry allows integration plugins to contribute widgets via static import side-effects. Widgets render in a responsive 4-column CSS grid with priority-weighted ordering, action buttons in a dedicated header row, and per-widget async loading with error isolation. + +## Tasks + +- [x] 1. Create widget registry module and types + - [x] 1.1 Create `frontend/src/lib/widgetRegistry.svelte.ts` with `WidgetDefinition` interface, `WidgetType` type, `registerWidget()`, `getWidgets()`, and `_resetForTesting()` using Svelte 5 `$state` rune + - Implement colSpan clamping to [1,3] on registration + - Export `filterWidgetsByStatus()` pure function for integration filtering + - Export `stableSortByPriority()` pure function for priority ordering + - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 7.1_ + + - [ ]* 1.2 Write property tests for widget registry (`frontend/src/lib/widgetRegistry.property.test.ts`) + - **Property 1: Registration preserves widget definitions** + - **Property 2: Column span clamping** + - **Property 3: Integration filtering** + - **Property 4: Stable priority ordering** + - **Validates: Requirements 1.1, 1.2, 1.3, 2.2, 2.4, 3.2, 3.3** + +- [x] 2. Implement WidgetFrame and ActionRow components + - [x] 2.1 Create `frontend/src/components/WidgetFrame.svelte` with loading skeleton, error badge with retry, and content states + - Accept `WidgetDefinition` and `nodeId` props + - Map colSpan to responsive Tailwind classes (`col-span-1`, `sm:col-span-2 lg:col-span-2`, `sm:col-span-2 lg:col-span-3`) + - Show animated skeleton placeholder during loading + - Show error badge with integration name, error summary, and retry button on failure + - Mount widget component with `onReady`/`onError` callbacks; use `{#key mountKey}` for retry remounting + - _Requirements: 5.1, 5.3, 5.4, 6.1, 6.2, 6.4_ + + - [x] 2.2 Create `frontend/src/components/ActionRow.svelte` with horizontal flex layout for action widgets + - Render only when action widgets are present (no empty container) + - Use `flex flex-wrap gap-2` layout + - Render each action widget inside a WidgetFrame + - _Requirements: 4.1, 4.2, 4.4, 4.5_ + + - [ ]* 2.3 Write unit tests for WidgetFrame (`frontend/src/components/WidgetFrame.test.ts`) + - **Property 5: Column span applied to frame element** + - **Property 7: Error badge content** + - Test loading skeleton display, error state with retry, and content transition + - **Validates: Requirements 3.4, 5.4, 6.1, 6.2, 6.4** + +- [x] 3. Implement WidgetGrid orchestrator component + - [x] 3.1 Create `frontend/src/components/WidgetGrid.svelte` that fetches integration status, filters widgets, and renders grid + - Fetch `/api/integrations/status` on mount + - Filter widgets by enabled integrations (connected or degraded) + - Separate action widgets from grid widgets + - Sort both sets by priority (stable sort preserving registration order for ties) + - Render ActionRow above a `grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4` container + - Show inline error notification when integration status endpoint fails + - _Requirements: 2.1, 2.2, 2.3, 2.4, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 5.2_ + + - [ ]* 3.2 Write unit tests for WidgetGrid (`frontend/src/components/WidgetGrid.test.ts`) + - **Property 6: Action row composition** + - **Property 8: Error isolation** + - Test integration status error displays notification + - Test widgets with unknown integrations are excluded + - **Validates: Requirements 2.2, 2.3, 2.4, 4.2, 6.3** + +- [x] 4. Checkpoint + - Ensure all tests pass, ask the user if questions arise. + +- [x] 5. Create widget registration modules for existing content + - [x] 5.1 Create `frontend/src/lib/widgets/generalInfo.widget.ts` and `frontend/src/components/GeneralInfoWidget.svelte` + - Extract "General Information" section from NodeDetailPage into standalone widget + - Register as type `summary`, colSpan 2, priority 10, integration `bolt` + - Component calls `onReady()` after data loads, `onError(err)` on failure + - _Requirements: 8.1_ + + - [x] 5.2 Create `frontend/src/lib/widgets/latestActions.widget.ts` and `frontend/src/components/LatestActionsWidget.svelte` + - Extract execution history section from NodeDetailPage into standalone widget + - Register as type `list`, colSpan 2, priority 20, integration `bolt` + - _Requirements: 8.3_ + + - [x] 5.3 Create `frontend/src/lib/widgets/puppetRuns.widget.ts` and `frontend/src/components/PuppetRunsWidget.svelte` + - Extract latest puppet runs section from NodeDetailPage into standalone widget + - Register as type `list`, colSpan 3, priority 100, integration `puppetdb` + - _Requirements: 8.2_ + +- [x] 6. Create remaining widget registration modules + - [x] 6.1 Create `frontend/src/lib/widgets/monitoringSummary.widget.ts` and `frontend/src/components/MonitoringSummaryWidget.svelte` + - Extract Checkmk monitoring summary from NodeDetailPage into standalone widget + - Register as type `summary`, colSpan 2, priority 100, integration `checkmk` + - _Requirements: 8.4_ + + - [x] 6.2 Create `frontend/src/lib/widgets/consoleAccess.widget.ts` and `frontend/src/components/ConsoleAccessWidget.svelte` + - Extract console access button from NodeDetailPage into standalone widget + - Register as type `action`, colSpan 1, priority 100, integration `proxmox` + - _Requirements: 8.5_ + + - [x] 6.3 Create barrel file `frontend/src/lib/widgets/index.ts` importing all widget registration modules + - Import order: generalInfo, latestActions, puppetRuns, monitoringSummary, consoleAccess + - _Requirements: 7.3_ + +- [x] 7. Checkpoint + - Ensure all tests pass, ask the user if questions arise. + +- [x] 8. Wire WidgetGrid into NodeDetailPage and clean up + - [x] 8.1 Import `frontend/src/lib/widgets/index.ts` barrel and replace the overview tab content in `NodeDetailPage.svelte` with `` + - Remove the hardcoded overview sections that are now handled by widgets + - Preserve all other tabs (facts, actions, puppet, hiera, journal, manage, monitor) unchanged + - _Requirements: 3.1, 4.1, 5.2_ + + - [ ]* 8.2 Write integration test verifying WidgetGrid renders registered widgets with correct filtering (`frontend/src/components/WidgetGrid.integration.test.ts`) + - Mock `/api/integrations/status` response + - Register test widgets with various integration names + - Verify only enabled-integration widgets render + - Verify action widgets appear in ActionRow, grid widgets in the grid + - **Validates: Requirements 2.2, 4.2, 8.1, 8.2, 8.3, 8.4, 8.5** + +- [x] 9. Final checkpoint + - Ensure all tests pass, ask the user if questions arise. + +## Notes + +- Tasks marked with `*` are optional and can be skipped for faster MVP +- Each task references specific requirements for traceability +- Checkpoints ensure incremental validation +- Property tests validate universal correctness properties from the design document +- Unit tests validate specific examples and edge cases +- The design specifies TypeScript with Svelte 5 runes — all new `.svelte.ts` files use `$state` +- The `filterWidgetsByStatus` and `stableSortByPriority` functions are extracted as pure functions for easy unit/property testing +- Widget components follow the contract: accept `nodeId`, `onReady`, `onError` props +- No backend changes required (Requirement 7) + +## Task Dependency Graph + +```json +{ + "waves": [ + { "id": 0, "tasks": ["1.1"] }, + { "id": 1, "tasks": ["1.2", "2.1", "2.2"] }, + { "id": 2, "tasks": ["2.3", "3.1"] }, + { "id": 3, "tasks": ["3.2", "5.1", "5.2", "5.3"] }, + { "id": 4, "tasks": ["6.1", "6.2"] }, + { "id": 5, "tasks": ["6.3"] }, + { "id": 6, "tasks": ["8.1"] }, + { "id": 7, "tasks": ["8.2"] } + ] +} +``` diff --git a/backend/package.json b/backend/package.json index 140d6721..c31d7536 100644 --- a/backend/package.json +++ b/backend/package.json @@ -20,7 +20,7 @@ "@azure/arm-resources-subscriptions": "^2.1.0", "@azure/identity": "^4.13.1", "@modelcontextprotocol/sdk": "^1.29.0", - "bcrypt": "^5.1.1", + "bcrypt": "^6.0.0", "cors": "^2.8.5", "dotenv": "^16.4.5", "express": "^4.19.2", @@ -28,8 +28,9 @@ "helmet": "^8.1.0", "jsonwebtoken": "^9.0.2", "pg": "^8.13.0", - "sqlite3": "^5.1.7", + "sqlite3": "^6.0.1", "ssh2": "^1.17.0", + "ws": "^8.21.0", "yaml": "^2.8.2", "zod": "^3.23.8" }, @@ -42,6 +43,7 @@ "@types/pg": "^8.11.0", "@types/ssh2": "^1.15.5", "@types/supertest": "^6.0.2", + "@types/ws": "^8.18.1", "fast-check": "^4.3.0", "supertest": "^7.0.0", "tsx": "^4.7.2", diff --git a/backend/src/config/ConfigService.ts b/backend/src/config/ConfigService.ts index a75937c2..90c8eb66 100644 --- a/backend/src/config/ConfigService.ts +++ b/backend/src/config/ConfigService.ts @@ -1,12 +1,15 @@ import { config as loadDotenv } from "dotenv"; import { AppConfigSchema, + ConsoleConfigSchema, type AppConfig, + type ConsoleConfig, type EntraIdConfig, type WhitelistConfig, } from "./schema"; import { z } from "zod"; import { parseJson } from "../utils/json"; +import { LoggerService } from "../services/LoggerService"; /** * Configuration service to load and validate application settings @@ -15,6 +18,7 @@ import { parseJson } from "../utils/json"; export class ConfigService { private config: AppConfig; private entraIdConfig: EntraIdConfig | null = null; + private consoleConfig: ConsoleConfig; constructor() { // Load .env file only if not in test environment @@ -22,10 +26,83 @@ export class ConfigService { loadDotenv(); } + // Parse console config with validation and warning logging + this.consoleConfig = this.parseConsoleConfig(); + // Parse and validate configuration this.config = this.loadConfiguration(); } + /** + * Parse and validate console configuration from CONSOLE_* environment variables. + * Logs warnings via LoggerService for invalid values and cross-field constraint violations. + */ + private parseConsoleConfig(): ConsoleConfig { + const logger = new LoggerService(); + const context = { component: "ConfigService" }; + const defaults = ConsoleConfigSchema.parse({}); + + const parsePositiveInt = ( + envName: string, + defaultValue: number, + minValue = 1, + ): number => { + const raw = process.env[envName]; + if (raw === undefined || raw === "") { + return defaultValue; + } + + const parsed = Number(raw); + if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < minValue) { + logger.warn( + `Invalid value for ${envName}="${raw}" (must be an integer >= ${String(minValue)}). Using default: ${String(defaultValue)}`, + context, + ); + return defaultValue; + } + + return parsed; + }; + + const sessionTimeoutMs = parsePositiveInt( + "CONSOLE_SESSION_TIMEOUT_MS", + defaults.sessionTimeoutMs, + ); + const maxSessionDuration = parsePositiveInt( + "CONSOLE_MAX_SESSION_DURATION", + defaults.maxSessionDuration, + ); + const maxConcurrentSessions = parsePositiveInt( + "CONSOLE_MAX_CONCURRENT_SESSIONS", + defaults.maxConcurrentSessions, + ); + const heartbeatIntervalMs = parsePositiveInt( + "CONSOLE_HEARTBEAT_INTERVAL_MS", + defaults.heartbeatIntervalMs, + ); + + // Cross-field validation: heartbeat must be less than session timeout (Req 11.6) + if (heartbeatIntervalMs >= sessionTimeoutMs) { + logger.warn( + `CONSOLE_HEARTBEAT_INTERVAL_MS (${String(heartbeatIntervalMs)}) must be less than CONSOLE_SESSION_TIMEOUT_MS (${String(sessionTimeoutMs)}). Using defaults for both: heartbeatIntervalMs=${String(defaults.heartbeatIntervalMs)}, sessionTimeoutMs=${String(defaults.sessionTimeoutMs)}`, + context, + ); + return { + sessionTimeoutMs: defaults.sessionTimeoutMs, + maxSessionDuration, + maxConcurrentSessions, + heartbeatIntervalMs: defaults.heartbeatIntervalMs, + }; + } + + return { + sessionTimeoutMs, + maxSessionDuration, + maxConcurrentSessions, + heartbeatIntervalMs, + }; + } + /** * Parse integrations configuration from environment variables */ @@ -826,6 +903,7 @@ export class ConfigService { mcpEnabled: process.env.MCP_ENABLED === "true", mcpAuthToken: process.env.MCP_AUTH_TOKEN ?? undefined, entraId: this.parseEntraIdConfig() ?? undefined, + console: this.consoleConfig, }; // Validate with Zod schema @@ -1087,4 +1165,11 @@ export class ConfigService { public getEntraIdConfig(): EntraIdConfig | null { return this.entraIdConfig; } + + /** + * Get console session configuration + */ + public getConsoleConfig(): ConsoleConfig { + return this.consoleConfig; + } } diff --git a/backend/src/config/schema.ts b/backend/src/config/schema.ts index f253508c..49384516 100644 --- a/backend/src/config/schema.ts +++ b/backend/src/config/schema.ts @@ -409,6 +409,18 @@ export const IntegrationsConfigSchema = z.object({ export type IntegrationsConfig = z.infer; +/** + * Console session configuration schema + */ +export const ConsoleConfigSchema = z.object({ + sessionTimeoutMs: z.number().int().positive().default(300000), + maxSessionDuration: z.number().int().positive().default(28800000), + maxConcurrentSessions: z.number().int().min(1).default(3), + heartbeatIntervalMs: z.number().int().positive().default(30000), +}); + +export type ConsoleConfig = z.infer; + /** * Application configuration schema with Zod validation */ @@ -449,6 +461,7 @@ export const AppConfigSchema = z.object({ integrations: IntegrationsConfigSchema.default({}), provisioning: ProvisioningConfigSchema.default({ allowDestructiveActions: false }), ui: UIConfigSchema.default({ showHomePageRunChart: true }), + console: ConsoleConfigSchema.default({}), mcpEnabled: z.boolean().default(false), mcpAuthToken: z.string().optional(), entraId: EntraIdConfigSchema.optional(), diff --git a/backend/src/database/migrations/018_console_sessions.sql b/backend/src/database/migrations/018_console_sessions.sql new file mode 100644 index 00000000..8254fda9 --- /dev/null +++ b/backend/src/database/migrations/018_console_sessions.sql @@ -0,0 +1,28 @@ +-- Migration 018: Console sessions +-- Adds console_sessions table for tracking interactive browser-based +-- console connections (VNC, terminal) to infrastructure nodes. +-- Requirements: 2.7 + +CREATE TABLE IF NOT EXISTS console_sessions ( + id TEXT PRIMARY KEY, + user_id TEXT NOT NULL, + node_id TEXT NOT NULL, + provider TEXT NOT NULL, + transport TEXT NOT NULL, + state TEXT NOT NULL DEFAULT 'creating', + token TEXT, + token_created_at TEXT, + token_consumed INTEGER NOT NULL DEFAULT 0, + upstream_url TEXT, + started_at TEXT NOT NULL, + last_heartbeat_at TEXT, + terminated_at TEXT, + error_message TEXT, + created_at TEXT NOT NULL DEFAULT (datetime('now')), + CONSTRAINT chk_state CHECK (state IN ('creating', 'active', 'terminated', 'failed')), + CONSTRAINT chk_transport CHECK (transport IN ('websocket-vnc', 'websocket-terminal')) +); + +CREATE INDEX IF NOT EXISTS idx_console_sessions_user_id ON console_sessions(user_id); +CREATE INDEX IF NOT EXISTS idx_console_sessions_state ON console_sessions(state); +CREATE INDEX IF NOT EXISTS idx_console_sessions_token ON console_sessions(token); diff --git a/backend/src/database/migrations/019_console_permissions.sql b/backend/src/database/migrations/019_console_permissions.sql new file mode 100644 index 00000000..8abb6798 --- /dev/null +++ b/backend/src/database/migrations/019_console_permissions.sql @@ -0,0 +1,32 @@ +-- Migration: 019_console_permissions +-- Description: Add console:access and console:admin permissions for the +-- console integration. Grant console:access to Operator and +-- Administrator roles; grant console:admin to Administrator only. +-- Date: 2025-07-14 +-- Requirements: 6.1, 6.7 + +-- ============================================================================ +-- PERMISSIONS: Console integration +-- ============================================================================ + +INSERT INTO permissions (id, resource, "action", description, created_at) VALUES + ('console-access-001', 'console', 'access', 'Access console sessions for nodes', CURRENT_TIMESTAMP), + ('console-admin-001', 'console', 'admin', 'Manage other users console sessions', CURRENT_TIMESTAMP) + ON CONFLICT DO NOTHING; + +-- ============================================================================ +-- ROLE-PERMISSION ASSIGNMENTS: Operator role — console:access +-- ============================================================================ + +INSERT INTO role_permissions (role_id, permission_id, assigned_at) VALUES + ('role-operator-001', 'console-access-001', CURRENT_TIMESTAMP) + ON CONFLICT DO NOTHING; + +-- ============================================================================ +-- ROLE-PERMISSION ASSIGNMENTS: Administrator role — console:access + console:admin +-- ============================================================================ + +INSERT INTO role_permissions (role_id, permission_id, assigned_at) VALUES + ('role-admin-001', 'console-access-001', CURRENT_TIMESTAMP), + ('role-admin-001', 'console-admin-001', CURRENT_TIMESTAMP) + ON CONFLICT DO NOTHING; diff --git a/backend/src/integrations/IntegrationManager.ts b/backend/src/integrations/IntegrationManager.ts index a4e1945d..0bcba673 100644 --- a/backend/src/integrations/IntegrationManager.ts +++ b/backend/src/integrations/IntegrationManager.ts @@ -16,6 +16,7 @@ import type { Action, NodeGroup, } from "./types"; +import type { ConsolePlugin, ConsoleTransport } from "./console/types"; import type { Node, Facts, ExecutionResult } from "./bolt/types"; import { NodeLinkingService, type LinkedNode } from "./NodeLinkingService"; import { LoggerService } from "../services/LoggerService"; @@ -63,6 +64,15 @@ export interface ProvisioningCapableExecutionTool { listProvisioningCapabilities(): ProvisioningCapability[]; } +/** + * Entry in the console availability response for a node + */ +export interface ConsoleAvailabilityEntry { + provider: string; + transport: ConsoleTransport; + displayName: string; +} + /** * Aggregated inventory from multiple sources */ @@ -117,6 +127,7 @@ export class IntegrationManager { private plugins = new Map(); private executionTools = new Map(); private informationSources = new Map(); + private consoleProviders = new Map(); private initialized = false; private nodeLinkingService: NodeLinkingService; private logger: LoggerService; @@ -183,6 +194,12 @@ export class IntegrationManager { ); } + // Detect console plugin via duck-typing (a plugin can be both an + // information source and a console provider simultaneously) + if (this.isConsolePlugin(plugin)) { + this.consoleProviders.set(plugin.name, plugin); + } + this.logger.info(`Registered plugin: ${plugin.name} (${plugin.type})`, { component: "IntegrationManager", operation: "registerPlugin", @@ -277,6 +294,102 @@ export class IntegrationManager { return Array.from(this.informationSources.values()); } + /** + * Get a console provider by name + * + * @param name - Provider name + * @returns ConsolePlugin instance or null if not found + */ + getConsoleProvider(name: string): ConsolePlugin | null { + return this.consoleProviders.get(name) ?? null; + } + + /** + * Register a standalone console provider without going through registerPlugin. + * + * Use this when the console provider shares its logical name with an already- + * registered integration plugin (e.g., the Proxmox console provider coexists + * with ProxmoxIntegration). The provider is added only to the console providers + * map and is not tracked in the main plugins map. + * + * @param provider - ConsolePlugin instance to register + */ + registerConsoleProvider(provider: ConsolePlugin): void { + this.consoleProviders.set(provider.name, provider); + this.logger.info(`Registered console provider: ${provider.name}`, { + component: "IntegrationManager", + operation: "registerConsoleProvider", + metadata: { providerName: provider.name }, + }); + } + + /** + * Get all registered console providers + * + * @returns Array of console plugins + */ + getAllConsoleProviders(): ConsolePlugin[] { + return Array.from(this.consoleProviders.values()); + } + + /** + * Query console availability for a specific node across all providers. + * + * Queries all registered console providers in parallel. Each provider call + * is given a 3-second timeout. Providers that timeout or throw are excluded + * from the response. Results are sorted by provider name ascending. + * + * @param nodeId - The node to query console availability for + * @returns Array of available console capabilities sorted by provider name + */ + async getConsoleAvailability(nodeId: string): Promise { + const CONSOLE_AVAILABILITY_TIMEOUT_MS = 3000; + + const providerEntries = Array.from(this.consoleProviders.entries()); + + const results = await Promise.all( + providerEntries.map(async ([name, provider]): Promise => { + try { + let timeoutHandle: ReturnType | undefined; + const timeoutPromise = new Promise((_, reject) => { + timeoutHandle = setTimeout( + () => { reject(new Error(`Console provider '${name}' timed out after ${String(CONSOLE_AVAILABILITY_TIMEOUT_MS)}ms`)); }, + CONSOLE_AVAILABILITY_TIMEOUT_MS, + ); + }); + + const workPromise = provider.getConsoleCapabilities(nodeId); + workPromise.catch(() => { /* handled by race */ }); + + let capabilities; + try { + capabilities = await Promise.race([workPromise, timeoutPromise]); + } finally { + clearTimeout(timeoutHandle); + } + + return capabilities.map((cap) => ({ + provider: name, + transport: cap.transport, + displayName: cap.displayName, + })); + } catch (error) { + const err = error instanceof Error ? error : new Error(String(error)); + this.logger.warn(`Console provider '${name}' excluded from availability response`, { + component: "IntegrationManager", + operation: "getConsoleAvailability", + metadata: { provider: name, nodeId, reason: err.message }, + }); + return []; + } + }), + ); + + const entries = results.flat(); + entries.sort((a, b) => a.provider.localeCompare(b.provider)); + return entries; + } + /** * Get all registered plugins * @@ -300,6 +413,21 @@ export class IntegrationManager { ); } + /** + * Type guard: check whether a plugin implements the ConsolePlugin interface. + * + * Detection uses duck-typing rather than narrowing the `type` field, since a + * single plugin (e.g. Proxmox) may implement both InformationSourcePlugin and + * ConsolePlugin simultaneously. + */ + private isConsolePlugin(plugin: IntegrationPlugin): plugin is ConsolePlugin { + return ( + "getConsoleCapabilities" in plugin && + "createSession" in plugin && + "terminateSession" in plugin + ); + } + /** * Get provisioning capabilities from all execution tools * @@ -1064,6 +1192,7 @@ export class IntegrationManager { this.plugins.delete(name); this.executionTools.delete(name); this.informationSources.delete(name); + this.consoleProviders.delete(name); this.logger.info(`Unregistered plugin: ${name}`, { component: "IntegrationManager", diff --git a/backend/src/integrations/console/types.ts b/backend/src/integrations/console/types.ts new file mode 100644 index 00000000..097887e5 --- /dev/null +++ b/backend/src/integrations/console/types.ts @@ -0,0 +1,79 @@ +import type { IntegrationPlugin } from "../types"; + +/** Supported transport protocols */ +export type ConsoleTransport = "websocket-vnc" | "websocket-terminal"; + +/** Describes a console capability for a node */ +export interface ConsoleCapability { + transport: ConsoleTransport; + /** Display label for the console option (max 100 chars) */ + displayName: string; + /** Provider-specific connection parameters schema */ + connectionSchema: Record; +} + +/** Session state machine */ +export type ConsoleSessionState = + | "creating" + | "active" + | "terminated" + | "failed"; + +/** Session status returned by getSessionStatus */ +export interface ConsoleSessionStatus { + state: ConsoleSessionState; + /** ISO 8601 timestamp */ + startedAt: string; + /** Present when state is "failed" */ + error?: string; +} + +/** Full session object returned by createSession */ +export interface ConsoleSession { + sessionId: string; + /** Short-lived session token for WebSocket auth */ + token: string; + /** Relative WebSocket URL for the client to connect */ + wsUrl: string; + transport: ConsoleTransport; + state: ConsoleSessionState; + /** ISO 8601 timestamp */ + startedAt: string; + nodeId: string; + userId: string; + provider: string; +} + +/** + * Console plugin interface — third plugin type alongside execution/information. + * + * Detected via duck-typing (type guard in IntegrationManager) rather than + * narrowing the `type` field, since a single plugin (e.g. Proxmox) may + * implement both InformationSourcePlugin and ConsolePlugin simultaneously. + */ +export interface ConsolePlugin extends IntegrationPlugin { + /** List console capabilities available for a given node */ + getConsoleCapabilities(nodeId: string): Promise; + + /** + * Create a new console session. + * Rejects with a typed error if the node has no console capability + * for this provider. + */ + createSession(nodeId: string, userId: string): Promise; + + /** + * Terminate an active session. + * Returns false without throwing for non-existent or already-terminated sessions. + */ + terminateSession(sessionId: string): Promise; + + /** Get current status of a session */ + getSessionStatus(sessionId: string): Promise; + + /** + * List transport protocols this provider supports. + * Must return between 1 and 10 entries. + */ + getSupportedTransports(): ConsoleTransport[]; +} diff --git a/backend/src/integrations/proxmox/ProxmoxConsoleProvider.ts b/backend/src/integrations/proxmox/ProxmoxConsoleProvider.ts new file mode 100644 index 00000000..1cb38414 --- /dev/null +++ b/backend/src/integrations/proxmox/ProxmoxConsoleProvider.ts @@ -0,0 +1,406 @@ +/** + * Proxmox Console Provider + * + * Implements the ConsolePlugin interface for Proxmox VMs and LXC containers, + * providing VNC console access via WebSocket proxy. + * + * Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7, 9.8, 1.6, 1.7 + */ + +import { randomBytes } from "crypto"; +import { randomUUID } from "crypto"; + +import type { + ConsoleCapability, + ConsolePlugin, + ConsoleSession, + ConsoleSessionStatus, + ConsoleTransport, +} from "../console/types"; +import type { IntegrationConfig } from "../types"; + +import type { LoggerService } from "../../services/LoggerService"; +import type { ProxmoxClient } from "./ProxmoxClient"; +import type { ProxmoxConfig, ProxmoxGuest } from "./types"; +import { ProxmoxAuthenticationError, ProxmoxError } from "./types"; + +/** Response from Proxmox vncproxy endpoint */ +interface VncProxyResponse { + ticket: string; + port: string; + upid?: string; +} + +/** Internal session store entry */ +interface SessionEntry { + session: ConsoleSession; + upstreamUrl: string; +} + +const COMPONENT = "ProxmoxConsoleProvider"; + +/** + * ProxmoxConsoleProvider — ConsolePlugin implementation for Proxmox VE. + * + * Advertises `websocket-vnc` transport. Creates VNC proxy sessions by + * requesting tickets from the Proxmox API and building upstream WS URLs. + */ +export class ProxmoxConsoleProvider implements ConsolePlugin { + readonly name = "proxmox"; + readonly type = "both" as const; + + /** In-memory session store (keyed by sessionId) */ + private sessions = new Map(); + private config: IntegrationConfig = { + enabled: true, + name: "proxmox", + type: "both", + config: {}, + }; + + constructor( + private proxmoxClient: ProxmoxClient, + private proxmoxConfig: ProxmoxConfig, + private logger: LoggerService, + ) { + this.logger.debug("ProxmoxConsoleProvider created", { + component: COMPONENT, + operation: "constructor", + }); + } + + // ======================================== + // IntegrationPlugin interface + // ======================================== + + initialize(config: IntegrationConfig): Promise { + this.config = config; + return Promise.resolve(); + } + + healthCheck(): Promise<{ + healthy: boolean; + message?: string; + lastCheck: string; + }> { + return Promise.resolve({ + healthy: true, + message: "Proxmox console provider healthy", + lastCheck: new Date().toISOString(), + }); + } + + getConfig(): IntegrationConfig { + return this.config; + } + + isInitialized(): boolean { + return true; + } + + // ======================================== + // ConsolePlugin interface + // ======================================== + + /** + * Check console capabilities for a node. + * + * Returns `websocket-vnc` capability if the guest exists and is running. + * Returns empty array if guest is not running or not found. + * + * Requirement 9.8 + */ + async getConsoleCapabilities(nodeId: string): Promise { + try { + const { node, vmid } = this.parseNodeId(nodeId); + const guestType = await this.getGuestType(node, vmid); + const status = await this.getGuestStatus(node, vmid, guestType); + + if (status !== "running") { + return []; + } + + return [ + { + transport: "websocket-vnc", + displayName: "VNC Console", + connectionSchema: {}, + }, + ]; + } catch (error) { + this.logger.debug("Cannot determine console capabilities", { + component: COMPONENT, + operation: "getConsoleCapabilities", + metadata: { + nodeId, + error: error instanceof Error ? error.message : String(error), + }, + }); + return []; + } + } + + /** + * Create a console session for a Proxmox guest. + * + * 1. Parse nodeId → node, vmid + * 2. Determine guest type (qemu/lxc) + * 3. Verify running state (Req 9.6) + * 4. Call vncproxy endpoint (Req 9.2, 9.4) + * 5. Build upstream WS URL (Req 9.3) + * 6. Generate session token and return ConsoleSession + * + * Error handling: + * - Auth errors → session failure with auth message (Req 9.5) + * - Not running → session failure with running message (Req 9.6) + * - Timeout/not found → session failure with category message (Req 9.7) + * - Node without console capability → typed error (Req 1.6) + */ + async createSession(nodeId: string, userId: string): Promise { + const { node, vmid } = this.parseNodeId(nodeId); + + // Determine guest type + let guestType: "qemu" | "lxc"; + try { + guestType = await this.getGuestType(node, vmid); + } catch (error) { + if (error instanceof ProxmoxError && error.code === "HTTP_404") { + throw new Error( + `Resource not found: guest ${String(vmid)} on node ${node} does not exist`, + ); + } + throw this.wrapApiError(error, "determine guest type"); + } + + // Verify guest is running (Req 9.6) + const status = await this.getGuestStatus(node, vmid, guestType); + if (status !== "running") { + throw new Error( + "Guest must be running for console access", + ); + } + + // Call vncproxy endpoint (Req 9.2, 9.4) + const vncProxyEndpoint = + `/api2/json/nodes/${node}/${guestType}/${String(vmid)}/vncproxy`; + + let vncResponse: VncProxyResponse; + try { + // ProxmoxClient.post() casts to string but actually returns the data object + const raw = await this.proxmoxClient.post(vncProxyEndpoint, { + websocket: 1, + }); + vncResponse = raw as unknown as VncProxyResponse; + } catch (error) { + throw this.wrapApiError(error, "request VNC proxy ticket"); + } + + // Build upstream WebSocket URL (Req 9.3) + const host = this.proxmoxConfig.host; + const port = vncResponse.port; + const ticket = encodeURIComponent(vncResponse.ticket); + const upstreamUrl = + `wss://${host}:${port}/api2/json/nodes/${node}/${guestType}/${String(vmid)}/vncwebsocket?port=${port}&vncticket=${ticket}`; + + // Generate session token and ID + const sessionId = randomUUID(); + const token = randomBytes(32).toString("hex"); + const now = new Date().toISOString(); + + const session: ConsoleSession = { + sessionId, + token, + wsUrl: `/ws/console/vnc?token=${token}`, + transport: "websocket-vnc", + state: "active", + startedAt: now, + nodeId, + userId, + provider: "proxmox", + }; + + // Store session locally for status/termination tracking + this.sessions.set(sessionId, { session, upstreamUrl }); + + this.logger.info("Proxmox console session created", { + component: COMPONENT, + operation: "createSession", + metadata: { sessionId, nodeId, userId, guestType }, + }); + + return session; + } + + /** + * Terminate a console session. + * + * Returns false without throwing for non-existent or already-terminated + * sessions (Req 1.7). + */ + terminateSession(sessionId: string): Promise { + const entry = this.sessions.get(sessionId); + if (!entry) { + return Promise.resolve(false); + } + + if (entry.session.state === "terminated") { + return Promise.resolve(false); + } + + entry.session.state = "terminated"; + this.sessions.delete(sessionId); + + this.logger.info("Proxmox console session terminated", { + component: COMPONENT, + operation: "terminateSession", + metadata: { sessionId }, + }); + + return Promise.resolve(true); + } + + /** + * Get current session status. + */ + getSessionStatus(sessionId: string): Promise { + const entry = this.sessions.get(sessionId); + if (!entry) { + return Promise.resolve({ + state: "terminated" as const, + startedAt: new Date().toISOString(), + }); + } + + return Promise.resolve({ + state: entry.session.state, + startedAt: entry.session.startedAt, + }); + } + + /** + * List supported transports. + * + * Requirement 9.8 + */ + getSupportedTransports(): ConsoleTransport[] { + return ["websocket-vnc"]; + } + + // ======================================== + // Internal helpers + // ======================================== + + /** + * Parse a node ID in format `proxmox:{node}:{vmid}`. + */ + private parseNodeId(nodeId: string): { node: string; vmid: number } { + const parts = nodeId.split(":"); + if (parts.length !== 3 || parts[0] !== "proxmox") { + throw new Error( + `Invalid nodeId format: ${nodeId}. Expected format: proxmox:{node}:{vmid}`, + ); + } + + const vmid = parseInt(parts[2], 10); + if (isNaN(vmid)) { + throw new Error(`Invalid VMID in nodeId: ${nodeId}`); + } + + return { node: parts[1], vmid }; + } + + /** + * Determine guest type by querying cluster resources. + */ + private async getGuestType( + node: string, + vmid: number, + ): Promise<"qemu" | "lxc"> { + const resources = await this.proxmoxClient.get( + "/api2/json/cluster/resources?type=vm", + ); + + if (!Array.isArray(resources)) { + throw new Error("Unexpected response format from Proxmox API"); + } + + const guest = (resources as ProxmoxGuest[]).find( + (r) => r.node === node && r.vmid === vmid, + ); + + if (!guest) { + throw new ProxmoxError( + `Guest with VMID ${String(vmid)} not found on node ${node}`, + "HTTP_404", + ); + } + + return guest.type; + } + + /** + * Get guest status from the Proxmox API. + */ + private async getGuestStatus( + node: string, + vmid: number, + guestType: "qemu" | "lxc", + ): Promise { + const endpoint = + `/api2/json/nodes/${node}/${guestType}/${String(vmid)}/status/current`; + + const response = (await this.proxmoxClient.get(endpoint)) as { + status: string; + }; + + return response.status; + } + + /** + * Wrap Proxmox API errors into descriptive messages for session failure. + * + * Handles: auth errors (Req 9.5), timeout (Req 9.7), not found (Req 9.7). + */ + private wrapApiError(error: unknown, operation: string): Error { + if (error instanceof ProxmoxAuthenticationError) { + return new Error( + `Authentication failed while attempting to ${operation}: ${error.message}`, + ); + } + + if (error instanceof ProxmoxError) { + if (error.code === "HTTP_404") { + return new Error( + `Resource not found while attempting to ${operation}: ${error.message}`, + ); + } + return new Error( + `Proxmox API error while attempting to ${operation}: ${error.message}`, + ); + } + + if (error instanceof Error) { + if ( + error.message.includes("timed out") || + error.message.includes("ETIMEDOUT") + ) { + return new Error( + `Connection timeout while attempting to ${operation}: ${error.message}`, + ); + } + if ( + error.message.includes("ECONNREFUSED") || + error.message.includes("ENOTFOUND") + ) { + return new Error( + `Connection failed while attempting to ${operation}: ${error.message}`, + ); + } + return new Error( + `Failed to ${operation}: ${error.message}`, + ); + } + + return new Error(`Failed to ${operation}: ${String(error)}`); + } +} diff --git a/backend/src/routes/console.ts b/backend/src/routes/console.ts new file mode 100644 index 00000000..13e51127 --- /dev/null +++ b/backend/src/routes/console.ts @@ -0,0 +1,300 @@ +import { Router, type Request, type Response } from "express"; +import { z } from "zod"; + +import type { DatabaseAdapter } from "../database/DatabaseAdapter"; +import type { IntegrationManager } from "../integrations/IntegrationManager"; +import { createAuthMiddleware } from "../middleware/authMiddleware"; +import { createRbacMiddleware } from "../middleware/rbacMiddleware"; +import { PermissionService } from "../services/PermissionService"; +import type { ConsoleSessionManager } from "../services/ConsoleSessionManager"; +import { type DIContainer, createDefaultContainer } from "../container/DIContainer"; + +import { asyncHandler } from "./asyncHandler"; + +const COMPONENT = "ConsoleRoutes"; + +/** + * Request validation schemas + */ +const CreateSessionSchema = z.object({ + nodeId: z.string().min(1, "nodeId is required"), + provider: z.string().min(1, "provider is required"), +}); + +/** + * Create console router with session management endpoints. + * + * Requirements: 6.2, 6.3, 6.4, 6.5, 6.6, 8.3, 8.6, 10.4 + */ +export function createConsoleRouter( + container: DIContainer = createDefaultContainer(), + integrationManager: IntegrationManager, + sessionManager: ConsoleSessionManager, + db: DatabaseAdapter, +): Router { + const router = Router(); + const logger = container.resolve("logger"); + const config = container.resolve("config"); + const consoleConfig = config.getConsoleConfig(); + + const jwtSecret = config.getJwtSecret(); + const authMiddleware = createAuthMiddleware(db, jwtSecret); + const rbacMiddleware = createRbacMiddleware(db); + const permissionService = new PermissionService(db); + + // All console routes require authentication + router.use(asyncHandler(authMiddleware)); + + /** + * GET /availability/:nodeId + * Get available console options for a node. + * Requirement 6.2 + */ + router.get( + "/availability/:nodeId", + asyncHandler(rbacMiddleware("console", "access")), + asyncHandler(async (req: Request, res: Response): Promise => { + const { nodeId } = req.params; + + logger.info("Fetching console availability", { + component: COMPONENT, + operation: "getAvailability", + metadata: { nodeId }, + }); + + const availability = + await integrationManager.getConsoleAvailability(nodeId); + + res.json({ availability }); + }), + ); + + /** + * POST /sessions + * Create a new console session. + * Requirements: 6.2, 8.6 + */ + router.post( + "/sessions", + asyncHandler(rbacMiddleware("console", "access")), + asyncHandler(async (req: Request, res: Response): Promise => { + const userId = req.user?.userId; + if (!userId) { + res.status(401).json({ + error: { code: "UNAUTHORIZED", message: "Authentication required" }, + }); + return; + } + + const parsed = CreateSessionSchema.safeParse(req.body); + if (!parsed.success) { + res.status(400).json({ + error: { + code: "INVALID_REQUEST", + message: "Invalid request body", + details: parsed.error.errors, + }, + }); + return; + } + + const { nodeId, provider: providerName } = parsed.data; + + logger.info("Creating console session", { + component: COMPONENT, + operation: "createSession", + metadata: { nodeId, provider: providerName, userId }, + }); + + // Check concurrent session limit (Requirement 8.6) + const activeCount = + await sessionManager.getActiveSessionCount(userId); + if (activeCount >= consoleConfig.maxConcurrentSessions) { + res.status(429).json({ + error: { + code: "TOO_MANY_SESSIONS", + message: `Concurrent session limit (${String(consoleConfig.maxConcurrentSessions)}) reached. Terminate an existing session first.`, + }, + }); + return; + } + + // Get the console provider + const provider = + integrationManager.getConsoleProvider(providerName); + if (!provider) { + res.status(404).json({ + error: { + code: "NOT_FOUND", + message: `Console provider '${providerName}' not found`, + }, + }); + return; + } + + // Create session via provider + let session; + try { + session = await provider.createSession(nodeId, userId); + } catch (error) { + const message = + error instanceof Error ? error.message : String(error); + logger.error("Provider failed to create console session", { + component: COMPONENT, + operation: "createSession", + metadata: { nodeId, provider: providerName, userId }, + }, error instanceof Error ? error : undefined); + + res.status(502).json({ + error: { + code: "PROVIDER_ERROR", + message, + }, + }); + return; + } + + // Persist session + await sessionManager.createSession(session); + + res.status(201).json({ session }); + }), + ); + + /** + * DELETE /sessions/:sessionId + * Terminate a console session. + * Requirements: 6.4, 6.5, 6.6 + */ + router.delete( + "/sessions/:sessionId", + asyncHandler(rbacMiddleware("console", "access")), + asyncHandler(async (req: Request, res: Response): Promise => { + const { sessionId } = req.params; + const userId = req.user?.userId; + if (!userId) { + res.status(401).json({ + error: { code: "UNAUTHORIZED", message: "Authentication required" }, + }); + return; + } + + logger.info("Terminating console session", { + component: COMPONENT, + operation: "terminateSession", + metadata: { sessionId, userId }, + }); + + const session = await sessionManager.getSession(sessionId); + if (!session) { + res.status(404).json({ + error: { + code: "NOT_FOUND", + message: `Session '${sessionId}' not found`, + }, + }); + return; + } + + // If not own session, require console:admin (Requirements 6.4, 6.5) + if (session.userId !== userId) { + const hasAdmin = await permissionService.hasPermission( + userId, + "console", + "admin", + ); + if (!hasAdmin) { + res.status(403).json({ + error: { + code: "FORBIDDEN", + message: + "The console:admin permission is required to terminate another user's session", + }, + }); + return; + } + } + + await sessionManager.terminateSession(sessionId, "user_terminated"); + + res.status(204).send(); + }), + ); + + /** + * GET /sessions/:sessionId + * Get session status. + * Requirement 6.3 + */ + router.get( + "/sessions/:sessionId", + asyncHandler(rbacMiddleware("console", "access")), + asyncHandler(async (req: Request, res: Response): Promise => { + const { sessionId } = req.params; + + logger.info("Fetching console session status", { + component: COMPONENT, + operation: "getSessionStatus", + metadata: { sessionId }, + }); + + const session = await sessionManager.getSession(sessionId); + if (!session) { + res.status(404).json({ + error: { + code: "NOT_FOUND", + message: `Session '${sessionId}' not found`, + }, + }); + return; + } + + res.json({ + session: { + sessionId: session.sessionId, + state: session.state, + transport: session.transport, + nodeId: session.nodeId, + provider: session.provider, + startedAt: session.startedAt, + }, + }); + }), + ); + + /** + * POST /sessions/:sessionId/heartbeat + * Record heartbeat for an active session. + * Requirement 6.3 + */ + router.post( + "/sessions/:sessionId/heartbeat", + asyncHandler(rbacMiddleware("console", "access")), + asyncHandler(async (req: Request, res: Response): Promise => { + const { sessionId } = req.params; + + logger.info("Recording console session heartbeat", { + component: COMPONENT, + operation: "heartbeat", + metadata: { sessionId }, + }); + + const session = await sessionManager.getSession(sessionId); + if (!session) { + res.status(404).json({ + error: { + code: "NOT_FOUND", + message: `Session '${sessionId}' not found`, + }, + }); + return; + } + + await sessionManager.heartbeat(sessionId); + + res.status(204).send(); + }), + ); + + return router; +} diff --git a/backend/src/server.ts b/backend/src/server.ts index 81a95654..a7ca5ffa 100644 --- a/backend/src/server.ts +++ b/backend/src/server.ts @@ -61,6 +61,12 @@ import type { PuppetDBService } from "./integrations/puppetdb/PuppetDBService"; import type { PuppetserverService } from "./integrations/puppetserver/PuppetserverService"; import type { HieraPlugin } from "./integrations/hiera/HieraPlugin"; import type { ProxmoxIntegration } from "./integrations/proxmox/ProxmoxIntegration"; +import type { ProxmoxClient } from "./integrations/proxmox/ProxmoxClient"; +import type { ProxmoxConfig } from "./integrations/proxmox/types"; +import { ProxmoxConsoleProvider } from "./integrations/proxmox/ProxmoxConsoleProvider"; +import { ConsoleSessionManager } from "./services/ConsoleSessionManager"; +import { ConsoleWebSocketProxy } from "./services/ConsoleWebSocketProxy"; +import { createConsoleRouter } from "./routes/console"; import type { CheckmkPlugin } from "./integrations/checkmk/CheckmkPlugin"; import { pluginRegistry } from "./plugins/registry"; import { LoggerService } from "./services/LoggerService"; @@ -444,6 +450,26 @@ async function startServer(): Promise { }); } + // Register ProxmoxConsoleProvider alongside the Proxmox plugin (Req 9.1, 2.6) + if (proxmoxPlugin) { + const rawClient = proxmoxPlugin.getClient(); + const proxmoxCfg = proxmoxPlugin.getConfig().config as unknown as ProxmoxConfig; + if (rawClient) { + const proxmoxClient = rawClient as unknown as ProxmoxClient; + const consoleProvider = new ProxmoxConsoleProvider(proxmoxClient, proxmoxCfg, logger); + integrationManager.registerConsoleProvider(consoleProvider); + logger.info("ProxmoxConsoleProvider registered with IntegrationManager", { + component: "Server", + operation: "initializeConsole", + }); + } else { + logger.warn("Proxmox client not available — skipping ProxmoxConsoleProvider registration", { + component: "Server", + operation: "initializeConsole", + }); + } + } + // Retrieve specific plugin instances needed by downstream consumers const puppetDBService = (integrationManager.getInformationSource("puppetdb") ?? undefined) as PuppetDBService | undefined; const puppetserverService = (integrationManager.getInformationSource("puppetserver") ?? undefined) as PuppetserverService | undefined; @@ -1044,6 +1070,26 @@ async function startServer(): Promise { }); } + // === Console Integration Wiring (session manager + routes) === + const consoleConfig = configService.getConsoleConfig(); + const auditLoggingService = new AuditLoggingService(databaseService.getAdapter()); + const consoleSessionManager = new ConsoleSessionManager( + databaseService.getAdapter(), + consoleConfig, + logger, + auditLoggingService, + ); + + // Mount console routes before SPA fallback so /api/console is handled correctly + app.use( + "/api/console", + createConsoleRouter(container, integrationManager, consoleSessionManager, databaseService.getAdapter()), + ); + logger.info("Console routes mounted at /api/console", { + component: "Server", + operation: "initializeConsole", + }); + // Serve static frontend files in production const publicPath = path.resolve(__dirname, "..", "public"); app.use(express.static(publicPath)); @@ -1069,6 +1115,42 @@ async function startServer(): Promise { }); }); + // Attach WebSocket proxy to the HTTP server (noServer: true, shared port) + new ConsoleWebSocketProxy( + server, + consoleSessionManager, + { allowedOrigins: config.corsAllowedOrigins, console: consoleConfig }, + logger, + ); + logger.info("ConsoleWebSocketProxy attached to HTTP server", { + component: "Server", + operation: "initializeConsole", + }); + + // Graceful restart: terminate all pre-existing sessions for each registered console provider (Req 2.6) + const consoleProviders = integrationManager.getAllConsoleProviders(); + for (const cp of consoleProviders) { + await consoleSessionManager.terminateAllForProvider(cp.name); + } + if (consoleProviders.length > 0) { + logger.info("Terminated stale console sessions from previous run", { + component: "Server", + operation: "initializeConsole", + metadata: { providerCount: consoleProviders.length }, + }); + } + + // Session cleanup interval: expire idle sessions periodically + const consoleCleanupInterval = setInterval(() => { + consoleSessionManager.cleanupExpiredSessions().catch((err: unknown) => { + logger.warn("Console session cleanup failed", { + component: "Server", + operation: "consoleCleanup", + metadata: { error: err instanceof Error ? err.message : String(err) }, + }); + }); + }, consoleConfig.sessionTimeoutMs); + // Graceful shutdown process.on("SIGTERM", () => { logger.info("SIGTERM received, shutting down gracefully...", { @@ -1080,6 +1162,7 @@ async function startServer(): Promise { if (entraIdCleanupInterval) { clearInterval(entraIdCleanupInterval); } + clearInterval(consoleCleanupInterval); server.close(() => { void databaseService.close().then(() => { logger.info("Server closed", { diff --git a/backend/src/services/ConsoleSessionManager.ts b/backend/src/services/ConsoleSessionManager.ts new file mode 100644 index 00000000..69309ebc --- /dev/null +++ b/backend/src/services/ConsoleSessionManager.ts @@ -0,0 +1,339 @@ +import { randomBytes } from "crypto"; + +import type { ConsoleConfig } from "../config/schema"; +import type { DatabaseAdapter } from "../database/DatabaseAdapter"; +import type { ConsoleSession } from "../integrations/console/types"; + +import type { AuditLoggingService } from "./AuditLoggingService"; +import type { LoggerService } from "./LoggerService"; + +/** + * Row shape returned by console_sessions SELECT queries. + */ +interface ConsoleSessionRow { + id: string; + userId: string; + nodeId: string; + provider: string; + transport: string; + state: string; + token: string | null; + tokenCreatedAt: string | null; + tokenConsumed: number; + upstreamUrl: string | null; + startedAt: string; + lastHeartbeatAt: string | null; + terminatedAt: string | null; + errorMessage: string | null; +} + +const COMPONENT = "ConsoleSessionManager"; + +const SESSION_SELECT = ` + SELECT + id, user_id AS "userId", node_id AS "nodeId", provider, transport, state, + token, token_created_at AS "tokenCreatedAt", token_consumed AS "tokenConsumed", + upstream_url AS "upstreamUrl", started_at AS "startedAt", + last_heartbeat_at AS "lastHeartbeatAt", terminated_at AS "terminatedAt", + error_message AS "errorMessage" + FROM console_sessions`; + +/** + * Manages console session lifecycle: token generation/validation, + * session CRUD, heartbeats, concurrent limiting, and cleanup. + * + * Requirements: 2.1–2.8, 8.1, 8.2, 8.4, 8.6, 8.7 + */ +export class ConsoleSessionManager { + constructor( + private db: DatabaseAdapter, + private config: ConsoleConfig, + private logger: LoggerService, + private auditLogger: AuditLoggingService, + ) {} + + /** Generate a cryptographically random session token (32 bytes → 64 hex chars). */ + generateToken(): string { + return randomBytes(32).toString("hex"); + } + + /** Store a new console session and record an audit log entry. */ + async createSession(session: ConsoleSession): Promise { + const now = new Date().toISOString(); + + await this.db.execute( + `INSERT INTO console_sessions ( + id, user_id, node_id, provider, transport, state, + token, token_created_at, token_consumed, upstream_url, + started_at, last_heartbeat_at + ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?)`, + [ + session.sessionId, + session.userId, + session.nodeId, + session.provider, + session.transport, + session.state, + session.token, + now, + null, + session.startedAt, + now, + ], + ); + + await this.auditLogger.logAdminAction( + "console_session_create", + session.userId, + { + nodeId: session.nodeId, + provider: session.provider, + sessionId: session.sessionId, + timestamp: now, + }, + ); + + this.logger.info("Console session created", { + component: COMPONENT, + metadata: { sessionId: session.sessionId, userId: session.userId }, + }); + } + + /** + * Validate a session token for WebSocket upgrade (no userId required). + * Token must: exist, be created < 60s ago, and not be consumed. + * Used by ConsoleWebSocketProxy where userId is not available at handshake time. + * Requirements 4.2, 5.2, 8.2 + */ + async validateTokenForUpgrade(token: string): Promise { + const row = await this.db.queryOne( + `${SESSION_SELECT} WHERE token = ?`, + [token], + ); + + if (!row) { + return null; + } + + // Token must not be consumed + if (row.tokenConsumed !== 0) { + return null; + } + + // Token must be created < 60s ago + if (!row.tokenCreatedAt) { + return null; + } + const tokenAge = Date.now() - new Date(row.tokenCreatedAt).getTime(); + if (tokenAge >= 60_000) { + return null; + } + + return this.rowToSession(row); + } + + /** + * Validate a session token. + * Token must: exist, be created < 60s ago, not be consumed, and match userId. + * Requirements 8.2, 4.2 + */ + async validateToken( + token: string, + userId: string, + ): Promise { + const row = await this.db.queryOne( + `${SESSION_SELECT} WHERE token = ?`, + [token], + ); + + if (!row) { + return null; + } + + // Token must not be consumed + if (row.tokenConsumed !== 0) { + return null; + } + + // Token must be created < 60s ago + if (!row.tokenCreatedAt) { + return null; + } + const tokenAge = + Date.now() - new Date(row.tokenCreatedAt).getTime(); + if (tokenAge >= 60_000) { + return null; + } + + // Owner must match + if (row.userId !== userId) { + return null; + } + + return this.rowToSession(row); + } + + /** Mark a token as consumed (after successful WebSocket upgrade). */ + async consumeToken(token: string): Promise { + await this.db.execute( + `UPDATE console_sessions SET token_consumed = 1 WHERE token = ?`, + [token], + ); + } + + /** + * Record a heartbeat for an active session. + * Requirement 2.3 + */ + async heartbeat(sessionId: string): Promise { + const now = new Date().toISOString(); + await this.db.execute( + `UPDATE console_sessions SET last_heartbeat_at = ? WHERE id = ?`, + [now, sessionId], + ); + } + + /** + * Terminate a session and record an audit log entry. + * Requirements 2.5, 8.4 + */ + async terminateSession(sessionId: string, reason: string): Promise { + const now = new Date().toISOString(); + + const session = await this.getSession(sessionId); + if (!session) { + this.logger.warn("Attempted to terminate non-existent session", { + component: COMPONENT, + metadata: { sessionId }, + }); + return; + } + + await this.db.execute( + `UPDATE console_sessions + SET state = 'terminated', terminated_at = ?, error_message = ? + WHERE id = ?`, + [now, reason, sessionId], + ); + + await this.auditLogger.logAdminAction( + "console_session_terminate", + session.userId, + { + nodeId: session.nodeId, + provider: session.provider, + sessionId, + reason, + timestamp: now, + }, + ); + + this.logger.info("Console session terminated", { + component: COMPONENT, + metadata: { sessionId, reason }, + }); + } + + /** + * Count active sessions for a user. + * Requirement 8.6 + */ + async getActiveSessionCount(userId: string): Promise { + const row = await this.db.queryOne<{ count: number }>( + `SELECT COUNT(*) AS "count" + FROM console_sessions + WHERE user_id = ? AND state = 'active'`, + [userId], + ); + return row?.count ?? 0; + } + + /** + * Terminate all active sessions for a provider (used on restart/shutdown). + * Requirement 2.6 + */ + async terminateAllForProvider(provider: string): Promise { + const now = new Date().toISOString(); + const result = await this.db.execute( + `UPDATE console_sessions + SET state = 'terminated', terminated_at = ? + WHERE provider = ? AND state IN ('creating', 'active')`, + [now, provider], + ); + + this.logger.info("Bulk terminated sessions for provider", { + component: COMPONENT, + metadata: { provider, count: result.changes }, + }); + } + + /** + * Cleanup expired sessions: active sessions whose last heartbeat + * is older than sessionTimeoutMs. + * Requirement 2.4 + */ + async cleanupExpiredSessions(): Promise { + const cutoff = new Date( + Date.now() - this.config.sessionTimeoutMs, + ).toISOString(); + const now = new Date().toISOString(); + + const result = await this.db.execute( + `UPDATE console_sessions + SET state = 'terminated', terminated_at = ?, error_message = 'session_timeout' + WHERE state = 'active' AND last_heartbeat_at < ?`, + [now, cutoff], + ); + + if (result.changes > 0) { + this.logger.info("Cleaned up expired console sessions", { + component: COMPONENT, + metadata: { count: result.changes }, + }); + } + } + + /** + * Retrieve a session by ID. + */ + async getSession(sessionId: string): Promise { + const row = await this.db.queryOne( + `${SESSION_SELECT} WHERE id = ?`, + [sessionId], + ); + + if (!row) { + return null; + } + + return this.rowToSession(row); + } + + /** + * Get the upstream WebSocket URL for a session. + */ + async getUpstreamUrl(sessionId: string): Promise { + const row = await this.db.queryOne<{ upstreamUrl: string | null }>( + `SELECT upstream_url AS "upstreamUrl" FROM console_sessions WHERE id = ?`, + [sessionId], + ); + return row?.upstreamUrl ?? null; + } + + /** + * Map a database row to a ConsoleSession object. + */ + private rowToSession(row: ConsoleSessionRow): ConsoleSession { + return { + sessionId: row.id, + userId: row.userId, + nodeId: row.nodeId, + provider: row.provider, + transport: row.transport as ConsoleSession["transport"], + state: row.state as ConsoleSession["state"], + token: row.token ?? "", + wsUrl: `/ws/console/${row.transport === "websocket-vnc" ? "vnc" : "terminal"}?token=${row.token ?? ""}`, + startedAt: row.startedAt, + }; + } +} diff --git a/backend/src/services/ConsoleWebSocketProxy.ts b/backend/src/services/ConsoleWebSocketProxy.ts new file mode 100644 index 00000000..00d31065 --- /dev/null +++ b/backend/src/services/ConsoleWebSocketProxy.ts @@ -0,0 +1,321 @@ +import { WebSocketServer, WebSocket } from "ws"; +import type { Server as HTTPServer, IncomingMessage } from "http"; +import type { Duplex } from "stream"; +import { URL } from "url"; + +import type { ConsoleConfig } from "../config/schema"; +import type { ConsoleSession } from "../integrations/console/types"; + +import type { ConsoleSessionManager } from "./ConsoleSessionManager"; +import type { LoggerService } from "./LoggerService"; + +/** WebSocket close codes for console proxy */ +const CLOSE_CODES = { + SESSION_DURATION_EXCEEDED: 4408, + UPSTREAM_FAILURE: 4502, + CONNECTION_TIMEOUT: 4504, +} as const; + +/** Terminal control message types */ +const CONTROL_MSG = { RESIZE: 0x01 } as const; + +/** Expected frame length for resize: 1 type byte + 4 data bytes */ +const RESIZE_FRAME_LENGTH = 5; + +const UPSTREAM_CONNECT_TIMEOUT_MS = 10_000; +const UPSTREAM_CLOSE_TIMEOUT_MS = 5_000; +const COMPONENT = "ConsoleWebSocketProxy"; + +interface ProxyConfig { + allowedOrigins: string[]; + console: ConsoleConfig; +} + +/** + * WebSocket proxy for console connections (VNC and terminal). + * Attaches to the existing HTTP server with `noServer: true`. + * Requirements: 4.1–4.8, 5.1–5.8, 8.5, 8.7 + */ +export class ConsoleWebSocketProxy { + private wss: WebSocketServer; + + constructor( + httpServer: HTTPServer, + private sessionManager: ConsoleSessionManager, + private config: ProxyConfig, + private logger: LoggerService, + ) { + this.wss = new WebSocketServer({ noServer: true }); + httpServer.on("upgrade", (req: IncomingMessage, socket: Duplex, head: Buffer) => { + this.handleUpgrade(req, socket, head); + }); + } + + private handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void { + const url = this.parseRequestUrl(req); + if (!url) { socket.destroy(); return; } + + const { pathname } = url; + if (pathname !== "/ws/console/vnc" && pathname !== "/ws/console/terminal") { + return; // Not our path + } + + if (!this.isOriginAllowed(req)) { + this.logger.warn("WebSocket upgrade rejected: invalid origin", { + component: COMPONENT, metadata: { origin: req.headers.origin ?? "none" }, + }); + socket.destroy(); + return; + } + + const token = url.searchParams.get("token"); + if (!token) { + this.logger.warn("WebSocket upgrade rejected: missing token", { component: COMPONENT }); + socket.destroy(); + return; + } + + void this.authenticateAndConnect(req, socket, head, token, pathname); + } + + private async authenticateAndConnect( + req: IncomingMessage, socket: Duplex, head: Buffer, token: string, pathname: string, + ): Promise { + try { + const session = await this.sessionManager.validateTokenForUpgrade(token); + if (!session) { + this.logger.warn("WebSocket upgrade rejected: invalid or expired token", { component: COMPONENT }); + socket.destroy(); + return; + } + + await this.sessionManager.consumeToken(token); + + this.wss.handleUpgrade(req, socket, head, (clientWs: WebSocket) => { + this.wss.emit("connection", clientWs, req); + void this.startRelay(clientWs, session, pathname); + }); + } catch (err) { + this.logger.error("Error during WebSocket authentication", { + component: COMPONENT, + metadata: { error: err instanceof Error ? err.message : String(err) }, + }); + socket.destroy(); + } + } + + private async startRelay( + clientWs: WebSocket, session: ConsoleSession, pathname: string, + ): Promise { + const upstreamUrl = await this.sessionManager.getUpstreamUrl(session.sessionId); + if (!upstreamUrl) { + clientWs.close(CLOSE_CODES.UPSTREAM_FAILURE, "No upstream URL configured"); + return; + } + + const upstream = await this.connectUpstream(clientWs, session, upstreamUrl); + if (!upstream) return; + + const durationTimer = this.startDurationTimer(clientWs, upstream, session); + const label = pathname === "/ws/console/vnc" ? "VNC" : "Terminal"; + + // Wire message relay based on transport type + if (pathname === "/ws/console/vnc") { + this.wireVncRelay(clientWs, upstream); + } else { + this.wireTerminalRelay(clientWs, upstream, session); + } + + // Shared lifecycle handlers + this.wireLifecycle(clientWs, upstream, session, durationTimer, label); + } + + /** VNC: bidirectional binary relay, no modification. */ + private wireVncRelay(clientWs: WebSocket, upstream: WebSocket): void { + upstream.on("message", (data: Buffer) => { + if (clientWs.readyState === WebSocket.OPEN) { + clientWs.send(data, { binary: true }); + } + }); + clientWs.on("message", (data: Buffer) => { + if (upstream.readyState === WebSocket.OPEN) { + upstream.send(data, { binary: true }); + } + }); + } + + /** Terminal: text frames for I/O, binary frames for control messages. */ + private wireTerminalRelay( + clientWs: WebSocket, upstream: WebSocket, session: ConsoleSession, + ): void { + upstream.on("message", (data: Buffer, isBinary: boolean) => { + if (clientWs.readyState !== WebSocket.OPEN) return; + if (isBinary) { + clientWs.send(data, { binary: true }); + } else { + clientWs.send(data.toString("utf-8"), { binary: false }); + } + }); + + clientWs.on("message", (data: Buffer, isBinary: boolean) => { + if (isBinary) { + this.handleTerminalControlMessage(data, upstream, session); + } else if (upstream.readyState === WebSocket.OPEN) { + upstream.send(data.toString("utf-8"), { binary: false }); + } + }); + } + + /** Shared close/error lifecycle wiring for both transport types. */ + private wireLifecycle( + clientWs: WebSocket, + upstream: WebSocket, + session: ConsoleSession, + durationTimer: ReturnType, + label: string, + ): void { + upstream.on("close", () => { + clearTimeout(durationTimer); + if (clientWs.readyState === WebSocket.OPEN) { + clientWs.close(CLOSE_CODES.UPSTREAM_FAILURE, "Upstream connection closed"); + } + void this.sessionManager.terminateSession(session.sessionId, "upstream_closed"); + }); + + upstream.on("error", (err: Error) => { + this.logger.error(`${label} upstream error`, { + component: COMPONENT, + metadata: { sessionId: session.sessionId, error: err.message }, + }); + }); + + clientWs.on("close", () => { + clearTimeout(durationTimer); + this.closeUpstreamGracefully(upstream); + void this.sessionManager.terminateSession(session.sessionId, "client_disconnected"); + }); + + clientWs.on("error", (err: Error) => { + this.logger.error(`${label} client error`, { + component: COMPONENT, + metadata: { sessionId: session.sessionId, error: err.message }, + }); + }); + } + + /** + * Handle binary control messages on terminal connections. + * Type 0x01 = resize: next 4 bytes = columns (uint16 BE) + rows (uint16 BE). + * Unrecognized types or frames shorter than expected → discard. + */ + private handleTerminalControlMessage( + data: Buffer, upstream: WebSocket, session: ConsoleSession, + ): void { + if (data.length < 1) return; + const msgType = data[0]; + + if (msgType !== CONTROL_MSG.RESIZE) { + this.logger.debug("Discarding unrecognized control message type", { + component: COMPONENT, metadata: { sessionId: session.sessionId, msgType }, + }); + return; + } + + if (data.length < RESIZE_FRAME_LENGTH) { + this.logger.debug("Discarding truncated resize control message", { + component: COMPONENT, metadata: { sessionId: session.sessionId, length: data.length }, + }); + return; + } + + const columns = data.readUInt16BE(1); + const rows = data.readUInt16BE(3); + if (columns < 1 || columns > 500 || rows < 1 || rows > 200) { + this.logger.debug("Discarding resize with invalid dimensions", { + component: COMPONENT, metadata: { sessionId: session.sessionId, columns, rows }, + }); + return; + } + + if (upstream.readyState === WebSocket.OPEN) { + upstream.send(data, { binary: true }); + } + } + + /** Connect upstream with 10s timeout. Returns null on failure. */ + private connectUpstream( + clientWs: WebSocket, session: ConsoleSession, upstreamUrl: string, + ): Promise { + return new Promise((resolve) => { + const upstream = new WebSocket(upstreamUrl, { rejectUnauthorized: false }); + + const timeout = setTimeout(() => { + upstream.terminate(); + if (clientWs.readyState === WebSocket.OPEN) { + clientWs.close(CLOSE_CODES.CONNECTION_TIMEOUT, "Upstream connection timeout"); + } + void this.sessionManager.terminateSession(session.sessionId, "upstream_timeout"); + resolve(null); + }, UPSTREAM_CONNECT_TIMEOUT_MS); + + upstream.on("open", () => { + clearTimeout(timeout); + this.logger.info("Upstream connection established", { + component: COMPONENT, metadata: { sessionId: session.sessionId }, + }); + resolve(upstream); + }); + + upstream.on("error", (err: Error) => { + clearTimeout(timeout); + this.logger.error("Upstream connection failed", { + component: COMPONENT, metadata: { sessionId: session.sessionId, error: err.message }, + }); + if (clientWs.readyState === WebSocket.OPEN) { + clientWs.close(CLOSE_CODES.CONNECTION_TIMEOUT, "Upstream connection failed"); + } + void this.sessionManager.terminateSession(session.sessionId, "upstream_error"); + resolve(null); + }); + }); + } + + private startDurationTimer( + clientWs: WebSocket, upstream: WebSocket, session: ConsoleSession, + ): ReturnType { + return setTimeout(() => { + this.logger.info("Session duration limit reached", { + component: COMPONENT, metadata: { sessionId: session.sessionId }, + }); + if (clientWs.readyState === WebSocket.OPEN) { + clientWs.close(CLOSE_CODES.SESSION_DURATION_EXCEEDED, "Session duration exceeded"); + } + this.closeUpstreamGracefully(upstream); + void this.sessionManager.terminateSession(session.sessionId, "max_duration_exceeded"); + }, this.config.console.maxSessionDuration); + } + + private closeUpstreamGracefully(upstream: WebSocket): void { + if (upstream.readyState === WebSocket.OPEN || upstream.readyState === WebSocket.CONNECTING) { + upstream.close(); + const forceTimer = setTimeout(() => { upstream.terminate(); }, UPSTREAM_CLOSE_TIMEOUT_MS); + upstream.on("close", () => { clearTimeout(forceTimer); }); + } + } + + private isOriginAllowed(req: IncomingMessage): boolean { + const { allowedOrigins } = this.config; + if (allowedOrigins.length === 0) return true; // Dev mode: no restriction + const origin = req.headers.origin; + if (!origin) return false; + return allowedOrigins.includes(origin); + } + + private parseRequestUrl(req: IncomingMessage): URL | null { + try { + return new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`); + } catch { + return null; + } + } +} diff --git a/backend/test/config/ConsoleConfig.test.ts b/backend/test/config/ConsoleConfig.test.ts new file mode 100644 index 00000000..682c8595 --- /dev/null +++ b/backend/test/config/ConsoleConfig.test.ts @@ -0,0 +1,182 @@ +/** + * Unit tests for console configuration parsing in ConfigService + * Validates: Requirements 11.1, 11.2, 11.3, 11.4, 11.5, 11.6 + */ + +import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"; +import { ConfigService } from "../../src/config/ConfigService"; + +const savedEnv: Record = {}; + +function snapshotEnv(): void { + Object.assign(savedEnv, process.env); +} + +function restoreEnv(): void { + for (const key of Object.keys(process.env)) { + if (!(key in savedEnv)) { + delete process.env[key]; + } + } + for (const [key, value] of Object.entries(savedEnv)) { + if (value === undefined) { + delete process.env[key]; + } else { + process.env[key] = value; + } + } +} + +function setRequiredEnv(): void { + process.env.JWT_SECRET = "test-jwt-secret-for-unit-tests-with-32"; // pragma: allowlist secret + process.env.PABAWI_LIFECYCLE_TOKEN = "test-lifecycle-token"; // pragma: allowlist secret +} + +describe("ConfigService - Console Configuration", () => { + beforeEach(() => { + snapshotEnv(); + setRequiredEnv(); + }); + + afterEach(() => { + restoreEnv(); + vi.restoreAllMocks(); + }); + + describe("defaults (Req 11.1–11.4)", () => { + it("should apply default values when no CONSOLE_* env vars are set", () => { + const config = new ConfigService(); + const console = config.getConsoleConfig(); + + expect(console.sessionTimeoutMs).toBe(300000); + expect(console.maxSessionDuration).toBe(28800000); + expect(console.maxConcurrentSessions).toBe(3); + expect(console.heartbeatIntervalMs).toBe(30000); + }); + }); + + describe("valid env var parsing (Req 11.1–11.4)", () => { + it("should parse CONSOLE_SESSION_TIMEOUT_MS", () => { + process.env.CONSOLE_SESSION_TIMEOUT_MS = "600000"; + const config = new ConfigService(); + expect(config.getConsoleConfig().sessionTimeoutMs).toBe(600000); + }); + + it("should parse CONSOLE_MAX_SESSION_DURATION", () => { + process.env.CONSOLE_MAX_SESSION_DURATION = "3600000"; + const config = new ConfigService(); + expect(config.getConsoleConfig().maxSessionDuration).toBe(3600000); + }); + + it("should parse CONSOLE_MAX_CONCURRENT_SESSIONS", () => { + process.env.CONSOLE_MAX_CONCURRENT_SESSIONS = "10"; + const config = new ConfigService(); + expect(config.getConsoleConfig().maxConcurrentSessions).toBe(10); + }); + + it("should parse CONSOLE_HEARTBEAT_INTERVAL_MS", () => { + process.env.CONSOLE_HEARTBEAT_INTERVAL_MS = "15000"; + const config = new ConfigService(); + expect(config.getConsoleConfig().heartbeatIntervalMs).toBe(15000); + }); + }); + + describe("invalid values fall back to defaults with warning (Req 11.5)", () => { + it("should use default for non-numeric session timeout", () => { + process.env.CONSOLE_SESSION_TIMEOUT_MS = "abc"; + const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); + const config = new ConfigService(); + expect(config.getConsoleConfig().sessionTimeoutMs).toBe(300000); + expect(warnSpy).toHaveBeenCalledWith( + expect.stringContaining("CONSOLE_SESSION_TIMEOUT_MS"), + ); + }); + + it("should use default for floating point value", () => { + process.env.CONSOLE_SESSION_TIMEOUT_MS = "300.5"; + const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); + const config = new ConfigService(); + expect(config.getConsoleConfig().sessionTimeoutMs).toBe(300000); + expect(warnSpy).toHaveBeenCalledWith( + expect.stringContaining("CONSOLE_SESSION_TIMEOUT_MS"), + ); + }); + + it("should use default for negative value", () => { + process.env.CONSOLE_MAX_SESSION_DURATION = "-1"; + const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); + const config = new ConfigService(); + expect(config.getConsoleConfig().maxSessionDuration).toBe(28800000); + expect(warnSpy).toHaveBeenCalledWith( + expect.stringContaining("CONSOLE_MAX_SESSION_DURATION"), + ); + }); + + it("should use default for zero concurrent sessions", () => { + process.env.CONSOLE_MAX_CONCURRENT_SESSIONS = "0"; + const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); + const config = new ConfigService(); + expect(config.getConsoleConfig().maxConcurrentSessions).toBe(3); + expect(warnSpy).toHaveBeenCalledWith( + expect.stringContaining("CONSOLE_MAX_CONCURRENT_SESSIONS"), + ); + }); + + it("should use default for empty string", () => { + process.env.CONSOLE_HEARTBEAT_INTERVAL_MS = ""; + const config = new ConfigService(); + expect(config.getConsoleConfig().heartbeatIntervalMs).toBe(30000); + }); + }); + + describe("cross-field validation (Req 11.6)", () => { + it("should reset both to defaults when heartbeat >= session timeout", () => { + process.env.CONSOLE_SESSION_TIMEOUT_MS = "30000"; + process.env.CONSOLE_HEARTBEAT_INTERVAL_MS = "30000"; + const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); + const config = new ConfigService(); + const consoleConf = config.getConsoleConfig(); + + expect(consoleConf.sessionTimeoutMs).toBe(300000); + expect(consoleConf.heartbeatIntervalMs).toBe(30000); + expect(warnSpy).toHaveBeenCalledWith( + expect.stringContaining("CONSOLE_HEARTBEAT_INTERVAL_MS"), + ); + }); + + it("should reset both to defaults when heartbeat > session timeout", () => { + process.env.CONSOLE_SESSION_TIMEOUT_MS = "10000"; + process.env.CONSOLE_HEARTBEAT_INTERVAL_MS = "20000"; + const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); + const config = new ConfigService(); + const consoleConf = config.getConsoleConfig(); + + expect(consoleConf.sessionTimeoutMs).toBe(300000); + expect(consoleConf.heartbeatIntervalMs).toBe(30000); + expect(warnSpy).toHaveBeenCalledWith( + expect.stringContaining("must be less than"), + ); + }); + + it("should keep valid values when heartbeat < session timeout", () => { + process.env.CONSOLE_SESSION_TIMEOUT_MS = "60000"; + process.env.CONSOLE_HEARTBEAT_INTERVAL_MS = "5000"; + const config = new ConfigService(); + const consoleConf = config.getConsoleConfig(); + + expect(consoleConf.sessionTimeoutMs).toBe(60000); + expect(consoleConf.heartbeatIntervalMs).toBe(5000); + }); + }); + + describe("AppConfig integration", () => { + it("should expose console config through getConfig()", () => { + process.env.CONSOLE_MAX_CONCURRENT_SESSIONS = "5"; + const config = new ConfigService(); + const appConfig = config.getConfig(); + + expect(appConfig.console).toBeDefined(); + expect(appConfig.console.maxConcurrentSessions).toBe(5); + }); + }); +}); diff --git a/backend/test/database/migration-integration.test.ts b/backend/test/database/migration-integration.test.ts index c9cc449a..a192e2e7 100644 --- a/backend/test/database/migration-integration.test.ts +++ b/backend/test/database/migration-integration.test.ts @@ -28,8 +28,8 @@ describe('Migration Integration Test', () => { it('should apply all migrations on initialization', async () => { const status = await dbService.getMigrationStatus(); - // Should have applied all migrations (000 through 017, no 012 in source) - expect(status.applied).toHaveLength(17); + // Should have applied all migrations (000 through 019, no 012 in source) + expect(status.applied).toHaveLength(19); expect(status.applied[0].id).toBe('000'); expect(status.applied[1].id).toBe('001'); expect(status.applied[2].id).toBe('002'); @@ -47,6 +47,8 @@ describe('Migration Integration Test', () => { expect(status.applied[14].id).toBe('015'); expect(status.applied[15].id).toBe('016'); expect(status.applied[16].id).toBe('017'); + expect(status.applied[17].id).toBe('018'); + expect(status.applied[18].id).toBe('019'); expect(status.pending).toHaveLength(0); }); @@ -87,8 +89,8 @@ describe('Migration Integration Test', () => { const status = await dbService2.getMigrationStatus(); - // Should still have 17 applied, 0 pending - expect(status.applied).toHaveLength(17); + // Should still have 19 applied, 0 pending + expect(status.applied).toHaveLength(19); expect(status.pending).toHaveLength(0); await dbService2.close(); diff --git a/backend/test/properties/consoleAuditLog.property.test.ts b/backend/test/properties/consoleAuditLog.property.test.ts new file mode 100644 index 00000000..e8051b1b --- /dev/null +++ b/backend/test/properties/consoleAuditLog.property.test.ts @@ -0,0 +1,223 @@ +/** + * Property-Based Tests for Console Audit Log Completeness + * + * Feature: console-integration, Property 9: Audit log completeness for session events + * + * **Validates: Requirements 8.4** + * + * Property 9: Audit log completeness for session events + * ∀ session create/terminate event: + * the audit log entry SHALL contain userId, nodeId, provider, action type, and ISO 8601 timestamp. + */ + +import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"; +import * as fc from "fast-check"; + +import { ConsoleSessionManager } from "../../src/services/ConsoleSessionManager"; +import { SQLiteAdapter } from "../../src/database/SQLiteAdapter"; +import type { DatabaseAdapter } from "../../src/database/DatabaseAdapter"; +import type { AuditLoggingService } from "../../src/services/AuditLoggingService"; +import type { LoggerService } from "../../src/services/LoggerService"; +import type { ConsoleConfig } from "../../src/config/schema"; +import type { ConsoleSession } from "../../src/integrations/console/types"; +import { initializeTestSchema } from "../helpers/schema"; + +// ============================================================ +// Constants +// ============================================================ + +const ISO_8601_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/; + +const DEFAULT_CONSOLE_CONFIG: ConsoleConfig = { + sessionTimeoutMs: 300000, + maxSessionDuration: 28800000, + maxConcurrentSessions: 3, + heartbeatIntervalMs: 30000, +}; + +// ============================================================ +// Arbitraries +// ============================================================ + +/** Non-empty alphanumeric string for IDs */ +const idArb = fc.stringMatching(/^[a-z0-9]{8,32}$/); + +/** Provider names */ +const providerArb = fc.constantFrom("proxmox", "aws", "azure", "ssh"); + +/** Transport types */ +const transportArb = fc.constantFrom( + "websocket-vnc" as const, + "websocket-terminal" as const, +); + +/** Terminate reasons */ +const terminateReasonArb = fc.constantFrom( + "user_disconnect", + "session_timeout", + "admin_terminate", + "upstream_failure", + "max_duration_exceeded", +); + +/** Arbitrary for session data used in createSession */ +const sessionDataArb = fc.record({ + sessionId: idArb, + userId: idArb, + nodeId: idArb, + provider: providerArb, + transport: transportArb, +}); + +// ============================================================ +// Test Helpers +// ============================================================ + +interface AuditCall { + action: string; + userId: string; + details?: Record; +} + +function createMockAuditLogger(): AuditLoggingService & { calls: AuditCall[] } { + const calls: AuditCall[] = []; + return { + calls, + logAdminAction: vi.fn( + async ( + action: string, + userId: string, + details?: Record, + ) => { + calls.push({ action, userId, details }); + }, + ), + } as unknown as AuditLoggingService & { calls: AuditCall[] }; +} + +function createMockLogger(): LoggerService { + return { + info: vi.fn(), + warn: vi.fn(), + error: vi.fn(), + debug: vi.fn(), + } as unknown as LoggerService; +} + +function buildConsoleSession(data: { + sessionId: string; + userId: string; + nodeId: string; + provider: string; + transport: "websocket-vnc" | "websocket-terminal"; +}): ConsoleSession { + return { + sessionId: data.sessionId, + userId: data.userId, + nodeId: data.nodeId, + provider: data.provider, + transport: data.transport, + state: "active", + token: `token-${data.sessionId}`, + wsUrl: `/ws/console/terminal?token=token-${data.sessionId}`, + startedAt: new Date().toISOString(), + }; +} + +// ============================================================ +// Tests +// ============================================================ + +describe("Feature: console-integration, Property 9: Audit log completeness for session events", () => { + let db: DatabaseAdapter; + let auditLogger: AuditLoggingService & { calls: AuditCall[] }; + let logger: LoggerService; + let sessionManager: ConsoleSessionManager; + + beforeEach(async () => { + db = new SQLiteAdapter(":memory:"); + await db.initialize(); + await initializeTestSchema(db); + + auditLogger = createMockAuditLogger(); + logger = createMockLogger(); + sessionManager = new ConsoleSessionManager( + db, + DEFAULT_CONSOLE_CONFIG, + logger, + auditLogger, + ); + }); + + afterEach(async () => { + await (db as SQLiteAdapter).close(); + vi.restoreAllMocks(); + }); + + it("createSession audit entry contains userId, nodeId, provider, action, and ISO 8601 timestamp", () => { + return fc.assert( + fc.asyncProperty(sessionDataArb, async (data) => { + auditLogger.calls.length = 0; + + const session = buildConsoleSession(data); + await sessionManager.createSession(session); + + expect(auditLogger.calls.length).toBe(1); + const call = auditLogger.calls[0]; + + // Action type + expect(call.action).toBe("console_session_create"); + + // userId passed as second arg + expect(call.userId).toBe(data.userId); + + // Details contain nodeId, provider, sessionId, timestamp + expect(call.details).toBeDefined(); + expect(call.details!.nodeId).toBe(data.nodeId); + expect(call.details!.provider).toBe(data.provider); + expect(call.details!.sessionId).toBe(data.sessionId); + expect(call.details!.timestamp).toMatch(ISO_8601_PATTERN); + }), + { numRuns: 100 }, + ); + }); + + it("terminateSession audit entry contains userId, nodeId, provider, action, and ISO 8601 timestamp", () => { + return fc.assert( + fc.asyncProperty( + sessionDataArb, + terminateReasonArb, + async (data, reason) => { + auditLogger.calls.length = 0; + + // First create the session so terminateSession can find it + const session = buildConsoleSession(data); + await sessionManager.createSession(session); + + // Clear audit calls from createSession + auditLogger.calls.length = 0; + + await sessionManager.terminateSession(data.sessionId, reason); + + expect(auditLogger.calls.length).toBe(1); + const call = auditLogger.calls[0]; + + // Action type + expect(call.action).toBe("console_session_terminate"); + + // userId passed as second arg + expect(call.userId).toBe(data.userId); + + // Details contain nodeId, provider, sessionId, reason, timestamp + expect(call.details).toBeDefined(); + expect(call.details!.nodeId).toBe(data.nodeId); + expect(call.details!.provider).toBe(data.provider); + expect(call.details!.sessionId).toBe(data.sessionId); + expect(call.details!.reason).toBe(reason); + expect(call.details!.timestamp).toMatch(ISO_8601_PATTERN); + }, + ), + { numRuns: 100 }, + ); + }); +}); diff --git a/backend/test/properties/consoleAvailability.property.test.ts b/backend/test/properties/consoleAvailability.property.test.ts new file mode 100644 index 00000000..69b6246f --- /dev/null +++ b/backend/test/properties/consoleAvailability.property.test.ts @@ -0,0 +1,162 @@ +/** + * Property-Based Tests for Console Availability Response Structure and Ordering + * + * Feature: console-integration, Property 10: Availability response structure and ordering + * + * **Validates: Requirements 3.3, 3.4** + * + * Property 10: Availability response structure and ordering + * ∀ console availability query returning multiple providers: + * each entry SHALL contain provider name, transport type, and display label, + * and entries SHALL be sorted by provider name in ascending alphabetical order. + */ + +import { describe, it, expect, vi } from "vitest"; +import * as fc from "fast-check"; + +import { IntegrationManager } from "../../src/integrations/IntegrationManager"; +import type { ConsolePlugin, ConsoleCapability, ConsoleTransport } from "../../src/integrations/console/types"; +import type { IntegrationConfig, HealthStatus } from "../../src/integrations/types"; +import type { LoggerService } from "../../src/services/LoggerService"; + +// ============================================================ +// Constants +// ============================================================ + +const TRANSPORTS: ConsoleTransport[] = ["websocket-vnc", "websocket-terminal"]; + +// ============================================================ +// Helpers +// ============================================================ + +function createMockLogger(): LoggerService { + return { + info: vi.fn(), + warn: vi.fn(), + error: vi.fn(), + debug: vi.fn(), + } as unknown as LoggerService; +} + +function createMockConsolePlugin( + name: string, + transport: ConsoleTransport, + displayName: string, +): ConsolePlugin { + return { + name, + type: "information" as const, + initialize: vi.fn().mockResolvedValue(undefined), + healthCheck: vi.fn().mockResolvedValue({ healthy: true, message: "ok", lastCheck: new Date().toISOString() } satisfies HealthStatus), + getConfig: vi.fn().mockReturnValue({ enabled: true } as unknown as IntegrationConfig), + isInitialized: vi.fn().mockReturnValue(true), + getConsoleCapabilities: vi.fn().mockResolvedValue([ + { transport, displayName, connectionSchema: {} } satisfies ConsoleCapability, + ]), + createSession: vi.fn().mockResolvedValue({}), + terminateSession: vi.fn().mockResolvedValue(true), + getSessionStatus: vi.fn().mockResolvedValue({ state: "active", startedAt: new Date().toISOString() }), + getSupportedTransports: vi.fn().mockReturnValue([transport]), + }; +} + +// ============================================================ +// Arbitraries +// ============================================================ + +/** Unique provider names: 2-6 alphabetically random strings */ +const providerNamesArb = fc + .uniqueArray(fc.stringMatching(/^[a-z]{3,12}$/), { minLength: 2, maxLength: 6 }) + .filter((arr) => arr.length >= 2); + +/** Random transport type */ +const transportArb = fc.constantFrom(...TRANSPORTS); + +/** Random display name (1-100 chars, printable) */ +const displayNameArb = fc.stringMatching(/^[A-Za-z0-9 _-]{1,50}$/).filter((s) => s.length >= 1); + +/** A provider definition: name + transport + displayName */ +const providerDefArb = fc.record({ + transport: transportArb, + displayName: displayNameArb, +}); + +// ============================================================ +// Tests +// ============================================================ + +describe("Feature: console-integration, Property 10: Availability response structure and ordering", () => { + it("availability response entries contain provider, transport, and displayName, sorted by provider name ascending", () => { + return fc.assert( + fc.asyncProperty( + providerNamesArb, + fc.array(providerDefArb, { minLength: 6, maxLength: 6 }), + async (names, defs) => { + const logger = createMockLogger(); + const manager = new IntegrationManager({ logger }); + + // Register mock console plugins — one per unique name + for (let i = 0; i < names.length; i++) { + const name = names[i]; + const def = defs[i % defs.length]; + const plugin = createMockConsolePlugin(name, def.transport, def.displayName); + + manager.registerPlugin(plugin, { enabled: true } as unknown as IntegrationConfig); + } + + const result = await manager.getConsoleAvailability("test-node-123"); + + // Each entry must have provider, transport, and displayName + for (const entry of result) { + expect(entry).toHaveProperty("provider"); + expect(entry).toHaveProperty("transport"); + expect(entry).toHaveProperty("displayName"); + + expect(typeof entry.provider).toBe("string"); + expect(entry.provider.length).toBeGreaterThan(0); + expect(TRANSPORTS).toContain(entry.transport); + expect(typeof entry.displayName).toBe("string"); + expect(entry.displayName.length).toBeGreaterThan(0); + expect(entry.displayName.length).toBeLessThanOrEqual(100); + } + + // Entries must be sorted by provider name ascending (alphabetical) + for (let i = 1; i < result.length; i++) { + expect( + result[i - 1].provider.localeCompare(result[i].provider), + ).toBeLessThanOrEqual(0); + } + }, + ), + { numRuns: 100 }, + ); + }); + + it("response length matches number of registered providers that return capabilities", () => { + return fc.assert( + fc.asyncProperty( + providerNamesArb, + fc.array(providerDefArb, { minLength: 6, maxLength: 6 }), + async (names, defs) => { + const logger = createMockLogger(); + const manager = new IntegrationManager({ logger }); + + for (let i = 0; i < names.length; i++) { + const name = names[i]; + const def = defs[i % defs.length]; + const plugin = createMockConsolePlugin(name, def.transport, def.displayName); + + manager.registerPlugin(plugin, { enabled: true } as unknown as IntegrationConfig); + } + + const result = await manager.getConsoleAvailability("test-node-456"); + + // Each provider returns exactly one capability in our mock, + // so result length should equal the number of providers registered + expect(result.length).toBe(names.length); + }, + ), + { numRuns: 100 }, + ); + }); +}); diff --git a/backend/test/properties/consoleBinaryRelay.property.test.ts b/backend/test/properties/consoleBinaryRelay.property.test.ts new file mode 100644 index 00000000..328857e8 --- /dev/null +++ b/backend/test/properties/consoleBinaryRelay.property.test.ts @@ -0,0 +1,286 @@ +/** + * Property-Based Tests for Console Binary Frame Relay Integrity + * + * Feature: console-integration, Property 3: Binary frame relay integrity + * + * **Validates: Requirements 4.4** + * + * Property 3: Binary frame relay integrity + * ∀ binary data frame sent through the VNC WebSocket proxy in either direction, + * the frame SHALL arrive at the other end byte-for-byte identical to what was sent. + * + * Testing approach: Creates a local WebSocket server pair and wires them using + * the same relay logic as ConsoleWebSocketProxy.wireVncRelay. Random binary + * buffers are sent in both directions and verified byte-for-byte on receipt. + */ + +import { describe, it, expect, beforeEach, afterEach } from "vitest"; +import * as fc from "fast-check"; +import { WebSocketServer, WebSocket } from "ws"; +import type { AddressInfo } from "net"; +import { createServer, type Server as HTTPServer } from "http"; + +/** Replicate the VNC relay logic from ConsoleWebSocketProxy.wireVncRelay */ +function wireVncRelay(clientWs: WebSocket, upstream: WebSocket): void { + upstream.on("message", (data: Buffer) => { + if (clientWs.readyState === WebSocket.OPEN) { + clientWs.send(data, { binary: true }); + } + }); + clientWs.on("message", (data: Buffer) => { + if (upstream.readyState === WebSocket.OPEN) { + upstream.send(data, { binary: true }); + } + }); +} + +/** + * Sets up a test relay topology: + * [sender] <--WS--> [proxyClient | proxyUpstream] <--WS--> [target] + * + * The proxy wires proxyClient↔proxyUpstream using wireVncRelay. + * "sender" represents the browser/noVNC client. + * "target" represents the upstream VNC server. + */ +interface RelayFixture { + senderServer: HTTPServer; + targetServer: HTTPServer; + senderWss: WebSocketServer; + targetWss: WebSocketServer; + sender: WebSocket; + target: WebSocket; + proxyClient: WebSocket; + proxyUpstream: WebSocket; + cleanup: () => Promise; +} + +async function createRelayFixture(): Promise { + // Create "target" WS server (simulates upstream VNC server) + const targetHttpServer = createServer(); + const targetWss = new WebSocketServer({ server: targetHttpServer }); + + await new Promise((resolve) => { + targetHttpServer.listen(0, "127.0.0.1", resolve); + }); + const targetPort = (targetHttpServer.address() as AddressInfo).port; + + // Create "sender" WS server (simulates client-facing endpoint) + const senderHttpServer = createServer(); + const senderWss = new WebSocketServer({ server: senderHttpServer }); + + await new Promise((resolve) => { + senderHttpServer.listen(0, "127.0.0.1", resolve); + }); + const senderPort = (senderHttpServer.address() as AddressInfo).port; + + // Wait for the proxy's upstream connection to the target + const targetConnectionPromise = new Promise((resolve) => { + targetWss.on("connection", (ws) => resolve(ws)); + }); + + // Wait for the proxy's client-side connection from sender + const senderConnectionPromise = new Promise((resolve) => { + senderWss.on("connection", (ws) => resolve(ws)); + }); + + // proxyUpstream connects to target + const proxyUpstream = new WebSocket(`ws://127.0.0.1:${targetPort}`); + await new Promise((resolve, reject) => { + proxyUpstream.on("open", resolve); + proxyUpstream.on("error", reject); + }); + + // sender connects to senderWss (represents browser → proxy endpoint) + const sender = new WebSocket(`ws://127.0.0.1:${senderPort}`); + await new Promise((resolve, reject) => { + sender.on("open", resolve); + sender.on("error", reject); + }); + + // Get the server-side sockets + const target = await targetConnectionPromise; + const proxyClient = await senderConnectionPromise; + + // Wire the relay (the logic under test) + wireVncRelay(proxyClient, proxyUpstream); + + const cleanup = async (): Promise => { + const closeWs = (ws: WebSocket): Promise => + new Promise((resolve) => { + if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) { + ws.on("close", () => resolve()); + ws.close(); + } else { + resolve(); + } + }); + + await Promise.all([ + closeWs(sender), + closeWs(proxyClient), + closeWs(proxyUpstream), + closeWs(target), + ]); + + await new Promise((resolve) => { senderWss.close(() => resolve()); }); + await new Promise((resolve) => { targetWss.close(() => resolve()); }); + await new Promise((resolve) => { senderHttpServer.close(() => resolve()); }); + await new Promise((resolve) => { targetHttpServer.close(() => resolve()); }); + }; + + return { + senderServer: senderHttpServer, + targetServer: targetHttpServer, + senderWss, + targetWss, + sender, + target, + proxyClient, + proxyUpstream, + cleanup, + }; +} + +/** Collect N messages from a WebSocket as Buffers */ +function collectMessages(ws: WebSocket, count: number): Promise { + return new Promise((resolve, reject) => { + const messages: Buffer[] = []; + const timeout = setTimeout(() => { + reject(new Error(`Timed out waiting for ${count} messages, received ${messages.length}`)); + }, 5000); + + ws.on("message", (data: Buffer) => { + messages.push(Buffer.isBuffer(data) ? data : Buffer.from(data)); + if (messages.length === count) { + clearTimeout(timeout); + resolve(messages); + } + }); + + ws.on("error", (err) => { + clearTimeout(timeout); + reject(err); + }); + }); +} + +/** Arbitrary: random binary buffer (1 byte to 64KB) */ +const binaryBufferArb = fc.integer({ min: 1, max: 65536 }).chain((size) => + fc.uint8Array({ minLength: size, maxLength: size }).map((arr) => Buffer.from(arr)), +); + +/** Arbitrary: array of 1-10 random binary buffers */ +const bufferBatchArb = fc.array(binaryBufferArb, { minLength: 1, maxLength: 10 }); + +describe("Feature: console-integration, Property 3: Binary frame relay integrity", () => { + let fixture: RelayFixture; + + beforeEach(async () => { + fixture = await createRelayFixture(); + }); + + afterEach(async () => { + await fixture.cleanup(); + }); + + it("binary frames sent from client to upstream arrive byte-for-byte identical", async () => { + await fc.assert( + fc.asyncProperty(bufferBatchArb, async (buffers) => { + // Rebuild fixture for each property run to avoid message accumulation + await fixture.cleanup(); + fixture = await createRelayFixture(); + + // Set up message collection on the target (upstream) side + const received = collectMessages(fixture.target, buffers.length); + + // Send all buffers from the sender (client) side + for (const buf of buffers) { + fixture.sender.send(buf, { binary: true }); + } + + // Wait for all messages to arrive + const receivedBuffers = await received; + + // Verify byte-for-byte identity + expect(receivedBuffers.length).toBe(buffers.length); + for (let i = 0; i < buffers.length; i++) { + expect(Buffer.compare(receivedBuffers[i], buffers[i])).toBe(0); + } + }), + { numRuns: 100 }, + ); + }); + + it("binary frames sent from upstream to client arrive byte-for-byte identical", async () => { + await fc.assert( + fc.asyncProperty(bufferBatchArb, async (buffers) => { + // Rebuild fixture for each property run + await fixture.cleanup(); + fixture = await createRelayFixture(); + + // Set up message collection on the sender (client) side + const received = collectMessages(fixture.sender, buffers.length); + + // Send all buffers from the target (upstream) side + for (const buf of buffers) { + fixture.target.send(buf, { binary: true }); + } + + // Wait for all messages to arrive + const receivedBuffers = await received; + + // Verify byte-for-byte identity + expect(receivedBuffers.length).toBe(buffers.length); + for (let i = 0; i < buffers.length; i++) { + expect(Buffer.compare(receivedBuffers[i], buffers[i])).toBe(0); + } + }), + { numRuns: 100 }, + ); + }); + + it("bidirectional relay: frames in both directions are byte-for-byte identical simultaneously", async () => { + await fc.assert( + fc.asyncProperty( + bufferBatchArb, + bufferBatchArb, + async (clientToServer, serverToClient) => { + // Rebuild fixture for each property run + await fixture.cleanup(); + fixture = await createRelayFixture(); + + // Set up collectors for both directions + const receivedAtTarget = collectMessages(fixture.target, clientToServer.length); + const receivedAtSender = collectMessages(fixture.sender, serverToClient.length); + + // Send in both directions simultaneously + for (const buf of clientToServer) { + fixture.sender.send(buf, { binary: true }); + } + for (const buf of serverToClient) { + fixture.target.send(buf, { binary: true }); + } + + // Wait for all messages + const [targetReceived, senderReceived] = await Promise.all([ + receivedAtTarget, + receivedAtSender, + ]); + + // Verify client → server direction + expect(targetReceived.length).toBe(clientToServer.length); + for (let i = 0; i < clientToServer.length; i++) { + expect(Buffer.compare(targetReceived[i], clientToServer[i])).toBe(0); + } + + // Verify server → client direction + expect(senderReceived.length).toBe(serverToClient.length); + for (let i = 0; i < serverToClient.length; i++) { + expect(Buffer.compare(senderReceived[i], serverToClient[i])).toBe(0); + } + }, + ), + { numRuns: 100 }, + ); + }); +}); diff --git a/backend/test/properties/consoleConcurrentLimit.property.test.ts b/backend/test/properties/consoleConcurrentLimit.property.test.ts new file mode 100644 index 00000000..f2819f9f --- /dev/null +++ b/backend/test/properties/consoleConcurrentLimit.property.test.ts @@ -0,0 +1,263 @@ +/** + * Property-Based Tests for Concurrent Session Limit Enforcement + * + * Feature: console-integration, Property 7: Concurrent session limit enforcement + * + * **Validates: Requirements 8.6** + * + * Property 7: Concurrent session limit enforcement + * ∀ activeCount ∈ [0..10], maxConcurrentSessions ∈ [1..10]: + * getActiveSessionCount returns the correct number of active sessions, + * and when activeCount >= maxConcurrentSessions, new creation is rejected (429 semantics). + */ + +import { describe, it, expect, beforeEach, afterEach } from "vitest"; +import * as fc from "fast-check"; + +import { SQLiteAdapter } from "../../src/database/SQLiteAdapter"; +import { ConsoleSessionManager } from "../../src/services/ConsoleSessionManager"; +import type { ConsoleConfig } from "../../src/config/schema"; +import type { AuditLoggingService } from "../../src/services/AuditLoggingService"; +import type { LoggerService } from "../../src/services/LoggerService"; +import type { ConsoleSession } from "../../src/integrations/console/types"; + +function makeLogger(): LoggerService { + return { + info: () => {}, + warn: () => {}, + error: () => {}, + debug: () => {}, + } as unknown as LoggerService; +} + +function makeAuditLogger(): AuditLoggingService { + return { + logAdminAction: async () => {}, + } as unknown as AuditLoggingService; +} + +function makeConfig(maxConcurrentSessions: number): ConsoleConfig { + return { + sessionTimeoutMs: 300000, + maxSessionDuration: 28800000, + maxConcurrentSessions, + heartbeatIntervalMs: 30000, + }; +} + +function makeSession(userId: string, index: number): ConsoleSession { + return { + sessionId: `session-${userId}-${String(index)}-${String(Date.now())}`, + userId, + nodeId: `node-${String(index)}`, + provider: "proxmox", + transport: "websocket-vnc", + state: "active", + token: `token-${String(index)}-${String(Math.random())}`, + wsUrl: `/ws/console/vnc?token=token-${String(index)}`, + startedAt: new Date().toISOString(), + }; +} + +const CREATE_TABLE_SQL = ` + CREATE TABLE console_sessions ( + id TEXT PRIMARY KEY, + user_id TEXT NOT NULL, + node_id TEXT NOT NULL, + provider TEXT NOT NULL, + transport TEXT NOT NULL, + state TEXT NOT NULL DEFAULT 'creating', + token TEXT, + token_created_at TEXT, + token_consumed INTEGER NOT NULL DEFAULT 0, + upstream_url TEXT, + started_at TEXT NOT NULL, + last_heartbeat_at TEXT, + terminated_at TEXT, + error_message TEXT, + created_at TEXT NOT NULL DEFAULT (datetime('now')), + CONSTRAINT chk_state CHECK (state IN ('creating', 'active', 'terminated', 'failed')), + CONSTRAINT chk_transport CHECK (transport IN ('websocket-vnc', 'websocket-terminal')) + ) +`; + +describe("Feature: console-integration, Property 7: Concurrent session limit enforcement", () => { + let db: SQLiteAdapter; + + beforeEach(async () => { + db = new SQLiteAdapter(":memory:"); + await db.initialize(); + await db.execute(CREATE_TABLE_SQL); + }); + + afterEach(async () => { + await db.close(); + }); + + it("getActiveSessionCount returns the exact number of active sessions for a user", () => { + return fc.assert( + fc.asyncProperty( + fc.string({ minLength: 1, maxLength: 20 }).filter((s) => s.trim().length > 0), + fc.integer({ min: 0, max: 10 }), + async (userId, activeCount) => { + // Clear table + await db.execute("DELETE FROM console_sessions"); + + const config = makeConfig(3); + const manager = new ConsoleSessionManager( + db, + config, + makeLogger(), + makeAuditLogger(), + ); + + // Insert N active sessions for this user + for (let i = 0; i < activeCount; i++) { + const session = makeSession(userId, i); + await manager.createSession(session); + } + + const count = await manager.getActiveSessionCount(userId); + expect(count).toBe(activeCount); + }, + ), + { numRuns: 100 }, + ); + }); + + it("when active count >= maxConcurrentSessions, new session creation should be rejected", () => { + return fc.assert( + fc.asyncProperty( + fc.string({ minLength: 1, maxLength: 20 }).filter((s) => s.trim().length > 0), + fc.integer({ min: 1, max: 10 }), + fc.integer({ min: 0, max: 10 }), + async (userId, maxConcurrent, activeCount) => { + // Clear table + await db.execute("DELETE FROM console_sessions"); + + const config = makeConfig(maxConcurrent); + const manager = new ConsoleSessionManager( + db, + config, + makeLogger(), + makeAuditLogger(), + ); + + // Insert active sessions for this user + for (let i = 0; i < activeCount; i++) { + const session = makeSession(userId, i); + await manager.createSession(session); + } + + const count = await manager.getActiveSessionCount(userId); + const shouldReject = count >= maxConcurrent; + + // The route layer uses this logic: if count >= max → reject with 429 + // We verify the count-based decision matches expectations + if (shouldReject) { + expect(count).toBeGreaterThanOrEqual(maxConcurrent); + } else { + expect(count).toBeLessThan(maxConcurrent); + } + }, + ), + { numRuns: 100 }, + ); + }); + + it("terminated/failed sessions do not count toward the concurrent limit", () => { + return fc.assert( + fc.asyncProperty( + fc.string({ minLength: 1, maxLength: 20 }).filter((s) => s.trim().length > 0), + fc.integer({ min: 1, max: 5 }), + fc.integer({ min: 1, max: 5 }), + fc.integer({ min: 1, max: 10 }), + async (userId, activeCount, terminatedCount, maxConcurrent) => { + // Clear table + await db.execute("DELETE FROM console_sessions"); + + const config = makeConfig(maxConcurrent); + const manager = new ConsoleSessionManager( + db, + config, + makeLogger(), + makeAuditLogger(), + ); + + // Insert active sessions + for (let i = 0; i < activeCount; i++) { + const session = makeSession(userId, i); + await manager.createSession(session); + } + + // Insert terminated sessions (create then terminate) + for (let i = 0; i < terminatedCount; i++) { + const session = makeSession(userId, activeCount + i); + await manager.createSession(session); + await manager.terminateSession(session.sessionId, "test-termination"); + } + + // Only active sessions should count + const count = await manager.getActiveSessionCount(userId); + expect(count).toBe(activeCount); + + // Enforcement check: only active count matters for limit + const wouldReject = count >= maxConcurrent; + expect(wouldReject).toBe(activeCount >= maxConcurrent); + }, + ), + { numRuns: 100 }, + ); + }); + + it("sessions from different users do not affect each other's concurrent count", () => { + return fc.assert( + fc.asyncProperty( + fc.string({ minLength: 1, maxLength: 10 }).filter((s) => s.trim().length > 0), + fc.string({ minLength: 1, maxLength: 10 }).filter((s) => s.trim().length > 0), + fc.integer({ min: 0, max: 5 }), + fc.integer({ min: 0, max: 5 }), + fc.integer({ min: 1, max: 10 }), + async (userA, userB, countA, countB, maxConcurrent) => { + // Ensure users are different + const actualUserB = userA === userB ? `${userB}_other` : userB; + + // Clear table + await db.execute("DELETE FROM console_sessions"); + + const config = makeConfig(maxConcurrent); + const manager = new ConsoleSessionManager( + db, + config, + makeLogger(), + makeAuditLogger(), + ); + + // Insert sessions for user A + for (let i = 0; i < countA; i++) { + const session = makeSession(userA, i); + await manager.createSession(session); + } + + // Insert sessions for user B + for (let i = 0; i < countB; i++) { + const session = makeSession(actualUserB, i + 100); + await manager.createSession(session); + } + + // Each user's count is independent + const activeA = await manager.getActiveSessionCount(userA); + const activeB = await manager.getActiveSessionCount(actualUserB); + + expect(activeA).toBe(countA); + expect(activeB).toBe(countB); + + // Limit enforcement is per-user + expect(activeA >= maxConcurrent).toBe(countA >= maxConcurrent); + expect(activeB >= maxConcurrent).toBe(countB >= maxConcurrent); + }, + ), + { numRuns: 100 }, + ); + }); +}); diff --git a/backend/test/properties/consoleConfig.property.test.ts b/backend/test/properties/consoleConfig.property.test.ts new file mode 100644 index 00000000..6a53c522 --- /dev/null +++ b/backend/test/properties/consoleConfig.property.test.ts @@ -0,0 +1,256 @@ +/** + * Property-Based Tests for Console Configuration Parsing + * + * Feature: console-integration, Property 14: Configuration parsing with defaults + * + * **Validates: Requirements 11.1, 11.2, 11.3, 11.4, 11.5, 11.6** + * + * Property 14: Configuration parsing with defaults + * ∀ env var value ∈ {non-numeric, negative, zero, float, valid positive int}: + * invalid values → defaults applied + warning logged + * heartbeatIntervalMs >= sessionTimeoutMs → both revert to defaults + warning logged + */ + +import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"; +import * as fc from "fast-check"; +import { ConfigService } from "../../src/config/ConfigService"; + +const DEFAULTS = { + sessionTimeoutMs: 300000, + maxSessionDuration: 28800000, + maxConcurrentSessions: 3, + heartbeatIntervalMs: 30000, +} as const; + +const ENV_VARS = [ + "CONSOLE_SESSION_TIMEOUT_MS", + "CONSOLE_MAX_SESSION_DURATION", + "CONSOLE_MAX_CONCURRENT_SESSIONS", + "CONSOLE_HEARTBEAT_INTERVAL_MS", +] as const; + +const ENV_TO_KEY: Record = { + CONSOLE_SESSION_TIMEOUT_MS: "sessionTimeoutMs", + CONSOLE_MAX_SESSION_DURATION: "maxSessionDuration", + CONSOLE_MAX_CONCURRENT_SESSIONS: "maxConcurrentSessions", + CONSOLE_HEARTBEAT_INTERVAL_MS: "heartbeatIntervalMs", +}; + +const savedEnv: Record = {}; + +function snapshotEnv(): void { + Object.assign(savedEnv, process.env); +} + +function restoreEnv(): void { + for (const key of Object.keys(process.env)) { + if (!(key in savedEnv)) { + delete process.env[key]; + } + } + for (const [key, value] of Object.entries(savedEnv)) { + if (value === undefined) { + delete process.env[key]; + } else { + process.env[key] = value; + } + } +} + +function setRequiredEnv(): void { + process.env.JWT_SECRET = "test-jwt-secret-for-property-tests-32chars"; // pragma: allowlist secret + process.env.PABAWI_LIFECYCLE_TOKEN = "test-lifecycle-token"; // pragma: allowlist secret +} + +function clearConsoleEnv(): void { + for (const envVar of ENV_VARS) { + delete process.env[envVar]; + } +} + +/** + * Determines if a string would be parsed as a valid positive integer by the ConfigService. + * Mirrors the parsePositiveInt logic: Number(raw) must be finite, integer, and >= 1. + */ +function wouldParseAsValidPositiveInt(raw: string): boolean { + const parsed = Number(raw); + return Number.isFinite(parsed) && Number.isInteger(parsed) && parsed >= 1; +} + +/** Arbitrary that produces strings that are NOT valid positive integers per ConfigService logic */ +const invalidEnvValueArb = fc.oneof( + // Pure non-numeric strings + fc.constantFrom("abc", "hello", "NaN", "undefined", "null", "true", "Infinity", "-Infinity"), + // Negative integers as strings + fc.integer({ min: -1000000, max: -1 }).map(String), + // Zero + fc.constant("0"), + // Floating point values (non-integer) + fc.tuple(fc.integer({ min: 1, max: 999999 }), fc.integer({ min: 1, max: 99 })).map(([a, b]) => `${String(a)}.${String(b)}`), + // Strings with letters embedded (guaranteed not parseable) + fc.tuple(fc.nat({ max: 999 }), fc.constantFrom("px", "ms", "abc", "x")).map(([n, s]) => `${String(n)}${s}`), +).filter((v) => !wouldParseAsValidPositiveInt(v)); + +/** Arbitrary that produces valid positive integer strings (>= 1) */ +const validPositiveIntArb = fc.integer({ min: 1, max: 10000000 }).map(String); + +describe("Feature: console-integration, Property 14: Configuration parsing with defaults", () => { + beforeEach(() => { + snapshotEnv(); + setRequiredEnv(); + clearConsoleEnv(); + }); + + afterEach(() => { + restoreEnv(); + vi.restoreAllMocks(); + }); + + it("invalid env var values → default applied for each config field", () => { + fc.assert( + fc.property( + fc.constantFrom(...ENV_VARS), + invalidEnvValueArb, + (envVar, invalidValue) => { + clearConsoleEnv(); + vi.spyOn(console, "warn").mockImplementation(() => {}); + + process.env[envVar] = invalidValue; + const config = new ConfigService(); + const consoleConfig = config.getConsoleConfig(); + const key = ENV_TO_KEY[envVar]; + + expect(consoleConfig[key]).toBe(DEFAULTS[key]); + }, + ), + { numRuns: 100 }, + ); + }); + + it("invalid env var values → warning logged mentioning the env var name", () => { + fc.assert( + fc.property( + fc.constantFrom(...ENV_VARS), + invalidEnvValueArb, + (envVar, invalidValue) => { + clearConsoleEnv(); + const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); + + process.env[envVar] = invalidValue; + new ConfigService(); + + const calls = warnSpy.mock.calls.map((c) => String(c[0])); + const mentionsEnvVar = calls.some((msg) => msg.includes(envVar)); + expect(mentionsEnvVar).toBe(true); + }, + ), + { numRuns: 100 }, + ); + }); + + it("valid positive integers → correctly parsed (no defaults applied)", () => { + fc.assert( + fc.property( + fc.constantFrom(...ENV_VARS), + validPositiveIntArb, + (envVar, validValue) => { + clearConsoleEnv(); + vi.spyOn(console, "warn").mockImplementation(() => {}); + + process.env[envVar] = validValue; + + // Ensure heartbeat < timeout to avoid cross-field default revert + if (envVar === "CONSOLE_HEARTBEAT_INTERVAL_MS") { + const hb = parseInt(validValue, 10); + process.env.CONSOLE_SESSION_TIMEOUT_MS = String(hb + 1000000); + } else if (envVar === "CONSOLE_SESSION_TIMEOUT_MS") { + const timeout = parseInt(validValue, 10); + process.env.CONSOLE_HEARTBEAT_INTERVAL_MS = String(Math.max(1, timeout - 1)); + } + + const config = new ConfigService(); + const consoleConfig = config.getConsoleConfig(); + const key = ENV_TO_KEY[envVar]; + + expect(consoleConfig[key]).toBe(parseInt(validValue, 10)); + }, + ), + { numRuns: 100 }, + ); + }); + + it("heartbeatIntervalMs >= sessionTimeoutMs → both revert to defaults", () => { + fc.assert( + fc.property( + // heartbeat value + fc.integer({ min: 1, max: 10000000 }), + // offset: 0 means equal, positive means heartbeat > timeout + fc.nat({ max: 5000000 }), + (heartbeat, offset) => { + clearConsoleEnv(); + vi.spyOn(console, "warn").mockImplementation(() => {}); + + const timeout = Math.max(1, heartbeat - offset); + // heartbeat >= timeout guaranteed since offset >= 0 + process.env.CONSOLE_HEARTBEAT_INTERVAL_MS = String(heartbeat); + process.env.CONSOLE_SESSION_TIMEOUT_MS = String(timeout); + + const config = new ConfigService(); + const consoleConfig = config.getConsoleConfig(); + + expect(consoleConfig.sessionTimeoutMs).toBe(DEFAULTS.sessionTimeoutMs); + expect(consoleConfig.heartbeatIntervalMs).toBe(DEFAULTS.heartbeatIntervalMs); + }, + ), + { numRuns: 100 }, + ); + }); + + it("heartbeatIntervalMs >= sessionTimeoutMs → warning logged", () => { + fc.assert( + fc.property( + fc.integer({ min: 2, max: 10000000 }), + (heartbeat) => { + clearConsoleEnv(); + const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); + + // Equal case: heartbeat === timeout + process.env.CONSOLE_HEARTBEAT_INTERVAL_MS = String(heartbeat); + process.env.CONSOLE_SESSION_TIMEOUT_MS = String(heartbeat); + + new ConfigService(); + + const calls = warnSpy.mock.calls.map((c) => String(c[0])); + const mentionsCrossField = calls.some( + (msg) => + msg.includes("CONSOLE_HEARTBEAT_INTERVAL_MS") && + msg.includes("must be less than"), + ); + expect(mentionsCrossField).toBe(true); + }, + ), + { numRuns: 100 }, + ); + }); + + it("no CONSOLE_* env vars set → all defaults applied", () => { + fc.assert( + fc.property( + fc.constant(null), + () => { + clearConsoleEnv(); + vi.spyOn(console, "warn").mockImplementation(() => {}); + + const config = new ConfigService(); + const consoleConfig = config.getConsoleConfig(); + + expect(consoleConfig.sessionTimeoutMs).toBe(DEFAULTS.sessionTimeoutMs); + expect(consoleConfig.maxSessionDuration).toBe(DEFAULTS.maxSessionDuration); + expect(consoleConfig.maxConcurrentSessions).toBe(DEFAULTS.maxConcurrentSessions); + expect(consoleConfig.heartbeatIntervalMs).toBe(DEFAULTS.heartbeatIntervalMs); + }, + ), + { numRuns: 10 }, + ); + }); +}); diff --git a/backend/test/properties/consoleGuestRouting.property.test.ts b/backend/test/properties/consoleGuestRouting.property.test.ts new file mode 100644 index 00000000..7d10bc95 --- /dev/null +++ b/backend/test/properties/consoleGuestRouting.property.test.ts @@ -0,0 +1,152 @@ +/** + * Property-Based Tests for Guest Type Routing Correctness + * + * Feature: console-integration, Property 12: Guest type routing correctness + * + * **Validates: Requirements 9.4** + * + * Property 12: Guest type routing correctness + * ∀ guestType ∈ {qemu, lxc}, node ∈ alphabetic strings, vmid ∈ positive integers: + * When createSession is called, the provider SHALL POST to + * `/api2/json/nodes/{node}/{guestType}/{vmid}/vncproxy`. + */ + +import { describe, it, expect, vi } from "vitest"; +import * as fc from "fast-check"; + +import { ProxmoxConsoleProvider } from "../../src/integrations/proxmox/ProxmoxConsoleProvider"; +import type { ProxmoxClient } from "../../src/integrations/proxmox/ProxmoxClient"; +import type { ProxmoxConfig } from "../../src/integrations/proxmox/types"; +import type { LoggerService } from "../../src/services/LoggerService"; + +function makeLogger(): LoggerService { + return { + info: () => {}, + warn: () => {}, + error: () => {}, + debug: () => {}, + } as unknown as LoggerService; +} + +function makeProxmoxConfig(): ProxmoxConfig { + return { + host: "proxmox.example.com", + port: 8006, + }; +} + +/** + * Create a mock ProxmoxClient that: + * - Returns a guest resource with the specified type from cluster/resources + * - Returns running status from the status endpoint + * - Returns a VNC ticket from the vncproxy endpoint + * - Tracks calls to `post` for assertion + */ +function makeMockClient( + node: string, + vmid: number, + guestType: "qemu" | "lxc", +): { client: ProxmoxClient; postSpy: ReturnType } { + const postSpy = vi.fn().mockResolvedValue({ + ticket: "PVEVNC:test-ticket", // pragma: allowlist secret + port: "5900", + }); + + const getSpy = vi.fn().mockImplementation((endpoint: string) => { + if (endpoint.includes("/cluster/resources")) { + return Promise.resolve([ + { node, vmid, name: `guest-${String(vmid)}`, type: guestType, status: "running" }, + ]); + } + if (endpoint.includes("/status/current")) { + return Promise.resolve({ status: "running" }); + } + return Promise.resolve({}); + }); + + const client = { + get: getSpy, + post: postSpy, + } as unknown as ProxmoxClient; + + return { client, postSpy }; +} + +describe("Feature: console-integration, Property 12: Guest type routing correctness", () => { + it("routes QEMU guests to /qemu/{vmid}/vncproxy endpoint", () => { + return fc.assert( + fc.asyncProperty( + fc.string({ minLength: 1, maxLength: 20, unit: fc.constantFrom(..."abcdefghijklmnopqrstuvwxyz") }), + fc.integer({ min: 100, max: 99999 }), + async (node, vmid) => { + const { client, postSpy } = makeMockClient(node, vmid, "qemu"); + const provider = new ProxmoxConsoleProvider(client, makeProxmoxConfig(), makeLogger()); + + const nodeId = `proxmox:${node}:${String(vmid)}`; + await provider.createSession(nodeId, "user-1"); + + expect(postSpy).toHaveBeenCalledOnce(); + const calledEndpoint = postSpy.mock.calls[0][0] as string; + expect(calledEndpoint).toBe( + `/api2/json/nodes/${node}/qemu/${String(vmid)}/vncproxy`, + ); + }, + ), + { numRuns: 100 }, + ); + }); + + it("routes LXC guests to /lxc/{vmid}/vncproxy endpoint", () => { + return fc.assert( + fc.asyncProperty( + fc.string({ minLength: 1, maxLength: 20, unit: fc.constantFrom(..."abcdefghijklmnopqrstuvwxyz") }), + fc.integer({ min: 100, max: 99999 }), + async (node, vmid) => { + const { client, postSpy } = makeMockClient(node, vmid, "lxc"); + const provider = new ProxmoxConsoleProvider(client, makeProxmoxConfig(), makeLogger()); + + const nodeId = `proxmox:${node}:${String(vmid)}`; + await provider.createSession(nodeId, "user-1"); + + expect(postSpy).toHaveBeenCalledOnce(); + const calledEndpoint = postSpy.mock.calls[0][0] as string; + expect(calledEndpoint).toBe( + `/api2/json/nodes/${node}/lxc/${String(vmid)}/vncproxy`, + ); + }, + ), + { numRuns: 100 }, + ); + }); + + it("uses the correct guest type path segment for any random guest type", () => { + return fc.assert( + fc.asyncProperty( + fc.constantFrom("qemu" as const, "lxc" as const), + fc.string({ minLength: 1, maxLength: 20, unit: fc.constantFrom(..."abcdefghijklmnopqrstuvwxyz") }), + fc.integer({ min: 100, max: 99999 }), + async (guestType, node, vmid) => { + const { client, postSpy } = makeMockClient(node, vmid, guestType); + const provider = new ProxmoxConsoleProvider(client, makeProxmoxConfig(), makeLogger()); + + const nodeId = `proxmox:${node}:${String(vmid)}`; + await provider.createSession(nodeId, "user-1"); + + expect(postSpy).toHaveBeenCalledOnce(); + const calledEndpoint = postSpy.mock.calls[0][0] as string; + + // The endpoint must contain the guest type as a path segment + expect(calledEndpoint).toContain(`/${guestType}/`); + expect(calledEndpoint).toBe( + `/api2/json/nodes/${node}/${guestType}/${String(vmid)}/vncproxy`, + ); + + // Verify it does NOT contain the other type + const otherType = guestType === "qemu" ? "lxc" : "qemu"; + expect(calledEndpoint).not.toContain(`/${otherType}/`); + }, + ), + { numRuns: 100 }, + ); + }); +}); diff --git a/backend/test/properties/consoleMalformedControl.property.test.ts b/backend/test/properties/consoleMalformedControl.property.test.ts new file mode 100644 index 00000000..501c5ab4 --- /dev/null +++ b/backend/test/properties/consoleMalformedControl.property.test.ts @@ -0,0 +1,295 @@ +/** + * Property-Based Tests for Malformed Control Message Resilience + * + * Feature: console-integration, Property 16: Malformed control message resilience + * + * **Validates: Requirements 5.8** + * + * Property 16: Malformed control message resilience + * ∀ binary control frame with unrecognized type byte or truncated payload: + * the system SHALL discard the frame and continue relaying without + * terminating the session. + * + * Specifically: + * - Empty frames (0 bytes) → discard + * - Unrecognized type byte (anything != 0x01) with any payload → discard + * - Type 0x01 (resize) but total length < 5 bytes → discard (truncated) + * + * In all discard cases: + * - upstream.send is NOT called + * - session is NOT terminated (no clientWs.close) + */ + +import { describe, it, expect, vi, beforeEach } from "vitest"; +import * as fc from "fast-check"; +import { WebSocket } from "ws"; + +import { ConsoleWebSocketProxy } from "../../src/services/ConsoleWebSocketProxy"; +import type { ConsoleSessionManager } from "../../src/services/ConsoleSessionManager"; +import type { ConsoleSession } from "../../src/integrations/console/types"; +import type { LoggerService } from "../../src/services/LoggerService"; +import type { Server as HTTPServer } from "http"; + +// ============================================================ +// Constants +// ============================================================ + +const RESIZE_TYPE = 0x01; +const RESIZE_FRAME_LENGTH = 5; + +// ============================================================ +// Helpers +// ============================================================ + +function createMockLogger(): LoggerService { + return { + info: vi.fn(), + warn: vi.fn(), + error: vi.fn(), + debug: vi.fn(), + } as unknown as LoggerService; +} + +function createMockSessionManager(): ConsoleSessionManager { + return { + validateTokenForUpgrade: vi.fn(), + consumeToken: vi.fn(), + getUpstreamUrl: vi.fn(), + terminateSession: vi.fn(), + validateToken: vi.fn(), + heartbeat: vi.fn(), + getSession: vi.fn(), + getActiveSessionCount: vi.fn(), + createSession: vi.fn(), + terminateAllForProvider: vi.fn(), + cleanupExpiredSessions: vi.fn(), + } as unknown as ConsoleSessionManager; +} + +function createMockUpstream(): WebSocket { + return { + readyState: WebSocket.OPEN, + send: vi.fn(), + close: vi.fn(), + terminate: vi.fn(), + on: vi.fn(), + } as unknown as WebSocket; +} + +function createMockClientWs(): WebSocket { + return { + readyState: WebSocket.OPEN, + send: vi.fn(), + close: vi.fn(), + terminate: vi.fn(), + on: vi.fn(), + } as unknown as WebSocket; +} + +function createMockSession(): ConsoleSession { + return { + sessionId: "test-session-id", + token: "test-token", + wsUrl: "/ws/console/terminal", + transport: "websocket-terminal", + state: "active", + startedAt: new Date().toISOString(), + nodeId: "node-test", + userId: "user-test", + provider: "proxmox", + }; +} + +/** + * Creates a ConsoleWebSocketProxy instance with mocked dependencies. + * We use a fake HTTP server that doesn't actually listen. + */ +function createProxy(): { + proxy: ConsoleWebSocketProxy; + sessionManager: ConsoleSessionManager; +} { + const mockHttpServer = { + on: vi.fn(), + } as unknown as HTTPServer; + + const sessionManager = createMockSessionManager(); + const logger = createMockLogger(); + const config = { + allowedOrigins: [], + console: { + sessionTimeoutMs: 300000, + maxSessionDuration: 28800000, + maxConcurrentSessions: 3, + heartbeatIntervalMs: 30000, + }, + }; + + const proxy = new ConsoleWebSocketProxy( + mockHttpServer, + sessionManager, + config, + logger, + ); + + return { proxy, sessionManager }; +} + +// ============================================================ +// Arbitraries +// ============================================================ + +/** + * Arbitrary: Unrecognized type byte (anything != 0x01). + * Combined with a random payload of 0–50 bytes. + */ +const unrecognizedTypeFrameArb: fc.Arbitrary = fc + .integer({ min: 0, max: 255 }) + .filter((b) => b !== RESIZE_TYPE) + .chain((typeByte) => + fc.uint8Array({ minLength: 0, maxLength: 50 }).map((payload) => { + const buf = Buffer.alloc(1 + payload.length); + buf[0] = typeByte; + payload.forEach((byte, i) => { buf[i + 1] = byte; }); + return buf; + }), + ); + +/** + * Arbitrary: Truncated resize frame. + * First byte is 0x01 (resize), but total length is 1–4 bytes (< 5). + */ +const truncatedResizeFrameArb: fc.Arbitrary = fc + .integer({ min: 1, max: RESIZE_FRAME_LENGTH - 1 }) + .chain((totalLength) => + fc.uint8Array({ minLength: totalLength, maxLength: totalLength }).map((bytes) => { + const buf = Buffer.from(bytes); + buf[0] = RESIZE_TYPE; // Force first byte to resize type + return buf; + }), + ); + +/** + * Arbitrary: Empty frame (0 bytes). + */ +const emptyFrameArb: fc.Arbitrary = fc.constant(Buffer.alloc(0)); + +/** + * Arbitrary: All malformed frames combined. + * Union of empty, unrecognized type, and truncated resize. + */ +const malformedFrameArb: fc.Arbitrary = fc.oneof( + emptyFrameArb, + unrecognizedTypeFrameArb, + truncatedResizeFrameArb, +); + +// ============================================================ +// Tests +// ============================================================ + +describe("Feature: console-integration, Property 16: Malformed control message resilience", () => { + let proxy: ConsoleWebSocketProxy; + let handleMessage: (data: Buffer, upstream: WebSocket, session: ConsoleSession) => void; + + beforeEach(() => { + const created = createProxy(); + proxy = created.proxy; + // Access private method via bracket notation, bound to the proxy instance + const rawFn = (proxy as unknown as Record)[ + "handleTerminalControlMessage" + ] as (data: Buffer, upstream: WebSocket, session: ConsoleSession) => void; + handleMessage = rawFn.bind(proxy); + }); + + it("discards frames with unrecognized type bytes without sending upstream or terminating session", () => { + fc.assert( + fc.property(unrecognizedTypeFrameArb, (frame) => { + const upstream = createMockUpstream(); + const session = createMockSession(); + + handleMessage(frame, upstream, session); + + // Upstream must NOT receive any data + expect(upstream.send).not.toHaveBeenCalled(); + // Session must NOT be terminated (no close on clientWs proxy) + expect(upstream.close).not.toHaveBeenCalled(); + }), + { numRuns: 100 }, + ); + }); + + it("discards truncated resize frames (type 0x01, length < 5) without sending upstream or terminating session", () => { + fc.assert( + fc.property(truncatedResizeFrameArb, (frame) => { + const upstream = createMockUpstream(); + const session = createMockSession(); + + handleMessage(frame, upstream, session); + + expect(upstream.send).not.toHaveBeenCalled(); + expect(upstream.close).not.toHaveBeenCalled(); + }), + { numRuns: 100 }, + ); + }); + + it("discards empty frames (0 bytes) without sending upstream or terminating session", () => { + fc.assert( + fc.property(emptyFrameArb, (frame) => { + const upstream = createMockUpstream(); + const session = createMockSession(); + + handleMessage(frame, upstream, session); + + expect(upstream.send).not.toHaveBeenCalled(); + expect(upstream.close).not.toHaveBeenCalled(); + }), + { numRuns: 100 }, + ); + }); + + it("all malformed frames are discarded: upstream never receives data, session continues", () => { + fc.assert( + fc.property(malformedFrameArb, (frame) => { + const upstream = createMockUpstream(); + const session = createMockSession(); + + handleMessage(frame, upstream, session); + + // Core property: malformed → discard without side effects + expect(upstream.send).not.toHaveBeenCalled(); + expect(upstream.close).not.toHaveBeenCalled(); + expect(upstream.terminate).not.toHaveBeenCalled(); + }), + { numRuns: 100 }, + ); + }); + + it("valid resize frames (type 0x01, length >= 5, valid dimensions) ARE forwarded upstream", () => { + // Counter-property: verifies that non-malformed frames DO get forwarded, + // confirming the test is not trivially passing. + const validResizeArb = fc.tuple( + fc.integer({ min: 1, max: 500 }), + fc.integer({ min: 1, max: 200 }), + ).map(([cols, rows]) => { + const buf = Buffer.alloc(RESIZE_FRAME_LENGTH); + buf[0] = RESIZE_TYPE; + buf.writeUInt16BE(cols, 1); + buf.writeUInt16BE(rows, 3); + return buf; + }); + + fc.assert( + fc.property(validResizeArb, (frame) => { + const upstream = createMockUpstream(); + const session = createMockSession(); + + handleMessage(frame, upstream, session); + + // Valid resize frame SHOULD be forwarded + expect(upstream.send).toHaveBeenCalledWith(frame, { binary: true }); + }), + { numRuns: 100 }, + ); + }); +}); diff --git a/backend/test/properties/consoleNonRunningGuest.property.test.ts b/backend/test/properties/consoleNonRunningGuest.property.test.ts new file mode 100644 index 00000000..518110aa --- /dev/null +++ b/backend/test/properties/consoleNonRunningGuest.property.test.ts @@ -0,0 +1,220 @@ +/** + * Property-Based Tests for Non-Running Guest Rejection + * + * Feature: console-integration, Property 13: Non-running guest rejection + * + * **Validates: Requirements 9.6** + * + * Property 13: Non-running guest rejection + * ∀ Proxmox guest not in the "running" state: + * console session creation SHALL fail with an error message indicating + * the guest must be running. + */ + +import { describe, it, expect, vi } from "vitest"; +import * as fc from "fast-check"; + +import { ProxmoxConsoleProvider } from "../../src/integrations/proxmox/ProxmoxConsoleProvider"; +import type { ProxmoxClient } from "../../src/integrations/proxmox/ProxmoxClient"; +import type { ProxmoxConfig } from "../../src/integrations/proxmox/types"; +import type { LoggerService } from "../../src/services/LoggerService"; + +// ============================================================ +// Constants +// ============================================================ + +/** Proxmox guest states from the API vocabulary */ +const PROXMOX_STATES = [ + "running", + "stopped", + "paused", + "suspended", + "shutdown", + "prelaunch", + "postmigrate", +] as const; + +const NON_RUNNING_STATES = PROXMOX_STATES.filter((s) => s !== "running"); + +const GUEST_TYPES = ["qemu", "lxc"] as const; + +// ============================================================ +// Helpers +// ============================================================ + +function createMockLogger(): LoggerService { + return { + info: vi.fn(), + warn: vi.fn(), + error: vi.fn(), + debug: vi.fn(), + } as unknown as LoggerService; +} + +function createMockProxmoxClient( + guestType: "qemu" | "lxc", + node: string, + vmid: number, + status: string, +): ProxmoxClient { + return { + get: vi.fn().mockImplementation((endpoint: string) => { + if (endpoint.includes("/cluster/resources")) { + return Promise.resolve([ + { node, vmid, type: guestType, name: `guest-${String(vmid)}`, status }, + ]); + } + if (endpoint.includes("/status/current")) { + return Promise.resolve({ status }); + } + return Promise.resolve({}); + }), + post: vi.fn().mockResolvedValue({ ticket: "PVEVNC:test", port: "5900" }), + authenticate: vi.fn().mockResolvedValue(undefined), + delete: vi.fn().mockResolvedValue(""), + waitForTask: vi.fn().mockResolvedValue(undefined), + } as unknown as ProxmoxClient; +} + +const defaultProxmoxConfig: ProxmoxConfig = { + host: "proxmox.test.local", + port: 8006, +}; + +// ============================================================ +// Arbitraries +// ============================================================ + +/** Random non-running guest state */ +const nonRunningStateArb = fc.constantFrom(...NON_RUNNING_STATES); + +/** Random guest type */ +const guestTypeArb = fc.constantFrom<"qemu" | "lxc">(...GUEST_TYPES); + +/** Random node name: lowercase alpha 3-12 chars */ +const nodeNameArb = fc.stringMatching(/^[a-z]{3,12}$/); + +/** Random VMID: positive integer in typical Proxmox range */ +const vmidArb = fc.integer({ min: 100, max: 99999 }); + +/** Random user ID */ +const userIdArb = fc.stringMatching(/^[a-z0-9-]{3,20}$/); + +/** Any Proxmox state (including running) */ +const anyStateArb = fc.constantFrom(...PROXMOX_STATES); + +// ============================================================ +// Tests +// ============================================================ + +describe("Feature: console-integration, Property 13: Non-running guest rejection", () => { + it("session creation fails with 'Guest must be running' for any non-running state", () => { + return fc.assert( + fc.asyncProperty( + nonRunningStateArb, + guestTypeArb, + nodeNameArb, + vmidArb, + userIdArb, + async (state, guestType, node, vmid, userId) => { + const logger = createMockLogger(); + const client = createMockProxmoxClient(guestType, node, vmid, state); + const provider = new ProxmoxConsoleProvider(client, defaultProxmoxConfig, logger); + + const nodeId = `proxmox:${node}:${String(vmid)}`; + + await expect( + provider.createSession(nodeId, userId), + ).rejects.toThrow("Guest must be running for console access"); + }, + ), + { numRuns: 100 }, + ); + }); + + it("session creation does NOT throw for running state", () => { + return fc.assert( + fc.asyncProperty( + guestTypeArb, + nodeNameArb, + vmidArb, + userIdArb, + async (guestType, node, vmid, userId) => { + const logger = createMockLogger(); + const client = createMockProxmoxClient(guestType, node, vmid, "running"); + const provider = new ProxmoxConsoleProvider(client, defaultProxmoxConfig, logger); + + const nodeId = `proxmox:${node}:${String(vmid)}`; + + // Should not throw — session creation proceeds past the running check + const session = await provider.createSession(nodeId, userId); + expect(session).toBeDefined(); + expect(session.sessionId).toBeDefined(); + expect(session.transport).toBe("websocket-vnc"); + }, + ), + { numRuns: 100 }, + ); + }); + + it("non-running rejection applies regardless of guest type", () => { + return fc.assert( + fc.asyncProperty( + nonRunningStateArb, + guestTypeArb, + vmidArb, + async (state, guestType, vmid) => { + const logger = createMockLogger(); + const node = "testnode"; + const client = createMockProxmoxClient(guestType, node, vmid, state); + const provider = new ProxmoxConsoleProvider(client, defaultProxmoxConfig, logger); + + const nodeId = `proxmox:${node}:${String(vmid)}`; + + try { + await provider.createSession(nodeId, "user-1"); + // If we get here, the test fails — non-running should always throw + expect.fail("Expected createSession to throw for non-running guest"); + } catch (error) { + expect(error).toBeInstanceOf(Error); + expect((error as Error).message).toBe( + "Guest must be running for console access", + ); + } + }, + ), + { numRuns: 100 }, + ); + }); + + it("only 'running' state permits session creation among all Proxmox states", () => { + return fc.assert( + fc.asyncProperty( + anyStateArb, + guestTypeArb, + nodeNameArb, + vmidArb, + userIdArb, + async (state, guestType, node, vmid, userId) => { + const logger = createMockLogger(); + const client = createMockProxmoxClient(guestType, node, vmid, state); + const provider = new ProxmoxConsoleProvider(client, defaultProxmoxConfig, logger); + + const nodeId = `proxmox:${node}:${String(vmid)}`; + + if (state === "running") { + // Should succeed + const session = await provider.createSession(nodeId, userId); + expect(session).toBeDefined(); + } else { + // Should fail with the expected message + await expect( + provider.createSession(nodeId, userId), + ).rejects.toThrow("Guest must be running for console access"); + } + }, + ), + { numRuns: 100 }, + ); + }); +}); diff --git a/backend/test/properties/consoleProviderRegistration.property.test.ts b/backend/test/properties/consoleProviderRegistration.property.test.ts new file mode 100644 index 00000000..e65fac87 --- /dev/null +++ b/backend/test/properties/consoleProviderRegistration.property.test.ts @@ -0,0 +1,189 @@ +/** + * Property-Based Tests for Console Provider Registration Invariant + * + * Feature: console-integration, Property 1: Console provider registration invariant + * + * **Validates: Requirements 1.4** + * + * Property 1: Console provider registration invariant + * ∀ plugin implementing ConsolePlugin interface: + * after registration with IntegrationManager, it SHALL appear in the + * console providers map and be retrievable by name. + */ + +import { describe, it, expect, vi } from "vitest"; +import * as fc from "fast-check"; + +import { IntegrationManager } from "../../src/integrations/IntegrationManager"; +import type { + ConsolePlugin, + ConsoleCapability, + ConsoleTransport, +} from "../../src/integrations/console/types"; +import type { + IntegrationConfig, + HealthStatus, +} from "../../src/integrations/types"; +import type { LoggerService } from "../../src/services/LoggerService"; + +// ============================================================ +// Helpers +// ============================================================ + +function createMockLogger(): LoggerService { + return { + info: vi.fn(), + warn: vi.fn(), + error: vi.fn(), + debug: vi.fn(), + } as unknown as LoggerService; +} + +function createMockConsolePlugin(name: string): ConsolePlugin { + return { + name, + type: "information" as const, + initialize: vi.fn().mockResolvedValue(undefined), + healthCheck: vi.fn().mockResolvedValue({ + healthy: true, + message: "ok", + lastCheck: new Date().toISOString(), + } satisfies HealthStatus), + getConfig: vi.fn().mockReturnValue({ + enabled: true, + name, + type: "information", + config: {}, + } satisfies IntegrationConfig), + isInitialized: vi.fn().mockReturnValue(true), + getConsoleCapabilities: vi.fn().mockResolvedValue([ + { + transport: "websocket-vnc", + displayName: "VNC Console", + connectionSchema: {}, + } satisfies ConsoleCapability, + ]), + createSession: vi.fn().mockResolvedValue({ + sessionId: "test", + token: "tok", + wsUrl: "/ws/console/vnc?token=tok", + transport: "websocket-vnc" as ConsoleTransport, + state: "active" as const, + startedAt: new Date().toISOString(), + nodeId: "node-1", + userId: "user-1", + provider: name, + }), + terminateSession: vi.fn().mockResolvedValue(true), + getSessionStatus: vi.fn().mockResolvedValue({ + state: "active" as const, + startedAt: new Date().toISOString(), + }), + getSupportedTransports: vi.fn().mockReturnValue(["websocket-vnc"]), + }; +} + +// ============================================================ +// Arbitraries +// ============================================================ + +/** Random plugin name: lowercase alpha, 3-15 chars */ +const pluginNameArb = fc.stringMatching(/^[a-z]{3,15}$/); + +/** Unique array of plugin names (1-8 plugins) */ +const pluginNamesArb = fc.uniqueArray(pluginNameArb, { + minLength: 1, + maxLength: 8, +}); + +// ============================================================ +// Tests +// ============================================================ + +describe("Feature: console-integration, Property 1: Console provider registration invariant", () => { + it("after registration, a ConsolePlugin is retrievable by name via getConsoleProvider", () => { + fc.assert( + fc.property(pluginNameArb, (name) => { + const logger = createMockLogger(); + const manager = new IntegrationManager({ logger }); + + const plugin = createMockConsolePlugin(name); + manager.registerPlugin(plugin, { + enabled: true, + name, + type: "information", + config: {}, + }); + + const retrieved = manager.getConsoleProvider(name); + expect(retrieved).not.toBeNull(); + expect(retrieved).toBe(plugin); + expect(retrieved!.name).toBe(name); + }), + { numRuns: 100 }, + ); + }); + + it("after registration of N plugins, all appear in getAllConsoleProviders", () => { + fc.assert( + fc.property(pluginNamesArb, (names) => { + const logger = createMockLogger(); + const manager = new IntegrationManager({ logger }); + + const plugins: ConsolePlugin[] = []; + for (const name of names) { + const plugin = createMockConsolePlugin(name); + plugins.push(plugin); + manager.registerPlugin(plugin, { + enabled: true, + name, + type: "information", + config: {}, + }); + } + + const allProviders = manager.getAllConsoleProviders(); + + // All registered plugins must be present + expect(allProviders.length).toBe(names.length); + + for (let i = 0; i < names.length; i++) { + const found = allProviders.find((p) => p.name === names[i]); + expect(found).toBeDefined(); + expect(found).toBe(plugins[i]); + } + }), + { numRuns: 100 }, + ); + }); + + it("unregistered plugin names return null from getConsoleProvider", () => { + fc.assert( + fc.property( + pluginNamesArb, + pluginNameArb.filter((n) => n.length >= 3), + (registeredNames, queryName) => { + // Skip if queryName is already in registeredNames + fc.pre(!registeredNames.includes(queryName)); + + const logger = createMockLogger(); + const manager = new IntegrationManager({ logger }); + + for (const name of registeredNames) { + const plugin = createMockConsolePlugin(name); + manager.registerPlugin(plugin, { + enabled: true, + name, + type: "information", + config: {}, + }); + } + + const result = manager.getConsoleProvider(queryName); + expect(result).toBeNull(); + }, + ), + { numRuns: 100 }, + ); + }); +}); diff --git a/backend/test/properties/consoleRbacCreation.property.test.ts b/backend/test/properties/consoleRbacCreation.property.test.ts new file mode 100644 index 00000000..44c50f0b --- /dev/null +++ b/backend/test/properties/consoleRbacCreation.property.test.ts @@ -0,0 +1,240 @@ +/** + * Property-Based Tests for RBAC Enforcement on Session Creation + * + * Feature: console-integration, Property 5: RBAC enforcement for session creation + * + * **Validates: Requirements 6.2, 6.3** + * + * Property 5: RBAC enforcement for session creation + * ∀ user ∈ Users, hasConsoleAccess ∈ {true, false}: + * POST /api/console/sessions returns 201 iff user holds `console:access`; + * otherwise 403 with FORBIDDEN error code. + */ + +import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"; +import * as fc from "fast-check"; +import express from "express"; +import request from "supertest"; +import { randomUUID } from "crypto"; + +import { createConsoleRouter } from "../../src/routes/console"; +import { SQLiteAdapter } from "../../src/database/SQLiteAdapter"; +import { AuthenticationService } from "../../src/services/AuthenticationService"; +import { UserService } from "../../src/services/UserService"; +import { PermissionService } from "../../src/services/PermissionService"; +import { RoleService } from "../../src/services/RoleService"; +import { DIContainer } from "../../src/container/DIContainer"; +import { LoggerService } from "../../src/services/LoggerService"; +import { ExpertModeService } from "../../src/services/ExpertModeService"; +import { ConfigService } from "../../src/config/ConfigService"; +import type { IntegrationManager } from "../../src/integrations/IntegrationManager"; +import type { ConsoleSessionManager } from "../../src/services/ConsoleSessionManager"; +import type { ConsoleSession } from "../../src/integrations/console/types"; +import { initializeTestSchema } from "../helpers/schema"; + +const JWT_SECRET = "test-jwt-secret-for-property-tests-minimum-32chars!!"; // pragma: allowlist secret + +function buildContainer(): DIContainer { + const container = new DIContainer(); + container.register("logger", new LoggerService()); + container.register("expertMode", new ExpertModeService()); + container.register("config", new ConfigService()); + return container; +} + +function makeMockIntegrationManager(): IntegrationManager { + return { + getConsoleProvider: vi.fn().mockReturnValue({ + createSession: vi.fn().mockImplementation( + (nodeId: string, userId: string): ConsoleSession => ({ + sessionId: randomUUID(), + token: randomUUID(), + wsUrl: `/ws/console/vnc?token=${randomUUID()}`, + transport: "websocket-vnc", + state: "active", + startedAt: new Date().toISOString(), + nodeId, + userId, + provider: "proxmox", + }), + ), + }), + } as unknown as IntegrationManager; +} + +function makeMockSessionManager(): ConsoleSessionManager { + return { + getActiveSessionCount: vi.fn().mockResolvedValue(0), + createSession: vi.fn().mockResolvedValue(undefined), + } as unknown as ConsoleSessionManager; +} + +describe("Feature: console-integration, Property 5: RBAC enforcement for session creation", () => { + let db: SQLiteAdapter; + let authService: AuthenticationService; + let userService: UserService; + let permissionService: PermissionService; + let roleService: RoleService; + + beforeEach(async () => { + process.env.JWT_SECRET = JWT_SECRET; + process.env.HOST = "localhost"; + process.env.PORT = "3000"; + + db = new SQLiteAdapter(":memory:"); + await db.initialize(); + await initializeTestSchema(db); + + authService = new AuthenticationService(db, JWT_SECRET); + userService = new UserService(db, authService); + permissionService = new PermissionService(db); + roleService = new RoleService(db); + }); + + afterEach(async () => { + await db.close(); + delete process.env.JWT_SECRET; + delete process.env.HOST; + delete process.env.PORT; + vi.restoreAllMocks(); + }); + + /** + * Helper: create a user with or without `console:access` permission. + * Returns the generated JWT token. + */ + async function createUserWithPermission( + hasConsoleAccess: boolean, + suffix: string, + ): Promise<{ token: string; userId: string }> { + const user = await userService.createUser({ + username: `user_${suffix}`, + email: `user_${suffix}@test.com`, + password: "TestPass123!", + firstName: "Test", + lastName: "User", + isAdmin: false, + }); + + if (hasConsoleAccess) { + // Find or create console:access permission + let consoleAccessPerm; + const allPerms = await permissionService.listPermissions(); + consoleAccessPerm = allPerms.items.find( + (p) => p.resource === "console" && p.action === "access", + ); + if (!consoleAccessPerm) { + consoleAccessPerm = await permissionService.createPermission({ + resource: "console", + action: "access", + description: "Access console sessions", + }); + } + + // Create a role with console:access and assign to user + const role = await roleService.createRole({ + name: `console_role_${suffix}`, + description: "Console access role", + }); + await roleService.assignPermissionToRole(role.id, consoleAccessPerm.id); + await userService.assignRoleToUser(user.id, role.id); + } + + const token = await authService.generateToken(user); + return { token, userId: user.id }; + } + + /** + * Build an Express app with the console router mounted. + */ + function buildApp(): express.Express { + const app = express(); + app.use(express.json()); + + const container = buildContainer(); + const integrationManager = makeMockIntegrationManager(); + const sessionManager = makeMockSessionManager(); + + const router = createConsoleRouter( + container, + integrationManager, + sessionManager, + db, + ); + app.use("/api/console", router); + return app; + } + + it("users with console:access get 201 on POST /sessions", () => { + return fc.assert( + fc.asyncProperty( + fc.integer({ min: 1, max: 100 }), + async (iteration) => { + const app = buildApp(); + const suffix = `access_${String(iteration)}_${String(Date.now())}`; + const { token } = await createUserWithPermission(true, suffix); + + const response = await request(app) + .post("/api/console/sessions") + .set("Authorization", `Bearer ${token}`) + .send({ nodeId: "node-1", provider: "proxmox" }); + + expect(response.status).toBe(201); + expect(response.body.session).toBeDefined(); + }, + ), + { numRuns: 100 }, + ); + }, 120000); + + it("users without console:access get 403 on POST /sessions", () => { + return fc.assert( + fc.asyncProperty( + fc.integer({ min: 1, max: 100 }), + async (iteration) => { + const app = buildApp(); + const suffix = `noaccess_${String(iteration)}_${String(Date.now())}`; + const { token } = await createUserWithPermission(false, suffix); + + const response = await request(app) + .post("/api/console/sessions") + .set("Authorization", `Bearer ${token}`) + .send({ nodeId: "node-1", provider: "proxmox" }); + + expect(response.status).toBe(403); + expect(response.body.error).toBeDefined(); + expect(response.body.error.code).toBe("INSUFFICIENT_PERMISSIONS"); + }, + ), + { numRuns: 100 }, + ); + }, 120000); + + it("RBAC enforcement is consistent: access iff console:access held", () => { + return fc.assert( + fc.asyncProperty( + fc.boolean(), + fc.integer({ min: 1, max: 100 }), + async (hasAccess, iteration) => { + const app = buildApp(); + const suffix = `rbac_${String(hasAccess)}_${String(iteration)}_${String(Date.now())}`; + const { token } = await createUserWithPermission(hasAccess, suffix); + + const response = await request(app) + .post("/api/console/sessions") + .set("Authorization", `Bearer ${token}`) + .send({ nodeId: "node-1", provider: "proxmox" }); + + if (hasAccess) { + expect(response.status).toBe(201); + expect(response.body.session).toBeDefined(); + } else { + expect(response.status).toBe(403); + expect(response.body.error.code).toBe("INSUFFICIENT_PERMISSIONS"); + } + }, + ), + { numRuns: 100 }, + ); + }, 120000); +}); diff --git a/backend/test/properties/consoleRbacTermination.property.test.ts b/backend/test/properties/consoleRbacTermination.property.test.ts new file mode 100644 index 00000000..f9f2d1dd --- /dev/null +++ b/backend/test/properties/consoleRbacTermination.property.test.ts @@ -0,0 +1,302 @@ +/** + * Property-Based Tests for RBAC Enforcement for Cross-User Termination + * + * Feature: console-integration, Property 6: RBAC enforcement for cross-user termination + * + * **Validates: Requirements 6.4, 6.5, 6.6, 8.3** + * + * Property 6: RBAC enforcement for cross-user termination + * ∀ user, owner ∈ Users, hasAccess ∈ Bool, hasAdmin ∈ Bool: + * - No console:access → 403 (RBAC middleware blocks) + * - Same user + console:access → 204 (own session) + * - Different user + console:access but NOT console:admin → 403 + * - Different user + console:access + console:admin → 204 + */ + +import { describe, it, expect, beforeAll, afterAll } from "vitest"; +import * as fc from "fast-check"; +import express, { type Express } from "express"; +import request from "supertest"; +import { randomUUID } from "crypto"; + +import { SQLiteAdapter } from "../../src/database/SQLiteAdapter"; +import { AuthenticationService } from "../../src/services/AuthenticationService"; +import { UserService } from "../../src/services/UserService"; +import { PermissionService } from "../../src/services/PermissionService"; +import { RoleService } from "../../src/services/RoleService"; +import { ConsoleSessionManager } from "../../src/services/ConsoleSessionManager"; +import { createConsoleRouter } from "../../src/routes/console"; +import { DIContainer } from "../../src/container/DIContainer"; +import { LoggerService } from "../../src/services/LoggerService"; +import { ConfigService } from "../../src/config/ConfigService"; +import { ExpertModeService } from "../../src/services/ExpertModeService"; +import { initializeTestSchema } from "../helpers/schema"; + +import type { IntegrationManager } from "../../src/integrations/IntegrationManager"; +import type { AuditLoggingService } from "../../src/services/AuditLoggingService"; +import type { ConsoleSession } from "../../src/integrations/console/types"; +import type { ConsoleConfig } from "../../src/config/schema"; + +const JWT_SECRET = "test-secret-for-rbac-termination-prop-test"; // pragma: allowlist secret + +function makeAuditLogger(): AuditLoggingService { + return { + logAdminAction: async () => {}, + logAuthorizationFailure: async () => {}, + } as unknown as AuditLoggingService; +} + +function makeConsoleConfig(): ConsoleConfig { + return { + sessionTimeoutMs: 300000, + maxSessionDuration: 28800000, + maxConcurrentSessions: 10, + heartbeatIntervalMs: 30000, + }; +} + +function makeMockIntegrationManager(): IntegrationManager { + return { + getConsoleProvider: () => null, + getAllConsoleProviders: () => [], + getConsoleAvailability: async () => [], + } as unknown as IntegrationManager; +} + +describe("Feature: console-integration, Property 6: RBAC enforcement for cross-user termination", () => { + let db: SQLiteAdapter; + let app: Express; + let authService: AuthenticationService; + let userService: UserService; + let permissionService: PermissionService; + let roleService: RoleService; + let sessionManager: ConsoleSessionManager; + + // Pre-created permission and role IDs + let accessPermId: string; + let adminPermId: string; + let accessOnlyRoleId: string; + let accessAdminRoleId: string; + + beforeAll(async () => { + process.env.JWT_SECRET = JWT_SECRET; + process.env.PABAWI_LIFECYCLE_TOKEN = "test-lifecycle-token"; // pragma: allowlist secret + + db = new SQLiteAdapter(":memory:"); + await db.initialize(); + await initializeTestSchema(db); + + authService = new AuthenticationService(db, JWT_SECRET); + userService = new UserService(db, authService); + permissionService = new PermissionService(db); + roleService = new RoleService(db); + sessionManager = new ConsoleSessionManager( + db, + makeConsoleConfig(), + new LoggerService(), + makeAuditLogger(), + ); + + // Find or create console:access and console:admin permissions + const allPerms = await permissionService.listPermissions(); + const existingAccess = allPerms.items.find( + (p) => p.resource === "console" && p.action === "access", + ); + const existingAdmin = allPerms.items.find( + (p) => p.resource === "console" && p.action === "admin", + ); + + if (existingAccess) { + accessPermId = existingAccess.id; + } else { + const perm = await permissionService.createPermission({ + resource: "console", + action: "access", + description: "Access console sessions", + }); + accessPermId = perm.id; + } + + if (existingAdmin) { + adminPermId = existingAdmin.id; + } else { + const perm = await permissionService.createPermission({ + resource: "console", + action: "admin", + description: "Admin console sessions", + }); + adminPermId = perm.id; + } + + // Create reusable roles: one with access only, one with access+admin + const accessRole = await roleService.createRole({ + name: "console_access_only", + description: "console:access only", + }); + accessOnlyRoleId = accessRole.id; + await roleService.assignPermissionToRole(accessOnlyRoleId, accessPermId); + + const accessAdminRole = await roleService.createRole({ + name: "console_access_admin", + description: "console:access + console:admin", + }); + accessAdminRoleId = accessAdminRole.id; + await roleService.assignPermissionToRole(accessAdminRoleId, accessPermId); + await roleService.assignPermissionToRole(accessAdminRoleId, adminPermId); + + // Build Express app with console router + const container = new DIContainer(); + container.register("logger", new LoggerService()); + container.register("expertMode", new ExpertModeService()); + container.register("config", new ConfigService()); + + app = express(); + app.use(express.json()); + app.use( + "/api/console", + createConsoleRouter(container, makeMockIntegrationManager(), sessionManager, db), + ); + }); + + afterAll(async () => { + await db.close(); + delete process.env.JWT_SECRET; + delete process.env.PABAWI_LIFECYCLE_TOKEN; + }); + + /** + * Helper: create a test user and return their ID + JWT token. + */ + async function createUserWithToken( + suffix: string, + hasAccess: boolean, + hasAdmin: boolean, + ): Promise<{ userId: string; token: string }> { + const id = randomUUID(); + const username = `user_${suffix}_${id.substring(0, 6)}`; + const user = await userService.createUser({ + username, + email: `${username}@test.com`, + password: "TestPass123!", + firstName: "Test", + lastName: "User", + isAdmin: false, + }); + + if (hasAccess && hasAdmin) { + await userService.assignRoleToUser(user.id, accessAdminRoleId); + } else if (hasAccess) { + await userService.assignRoleToUser(user.id, accessOnlyRoleId); + } + // If neither, user has no console permissions + + const token = await authService.generateToken(user); + return { userId: user.id, token }; + } + + /** + * Helper: create a console session owned by a specific user. + */ + async function createOwnedSession(ownerId: string): Promise { + const sessionId = randomUUID(); + const session: ConsoleSession = { + sessionId, + userId: ownerId, + nodeId: `node-${randomUUID().substring(0, 8)}`, + provider: "proxmox", + transport: "websocket-vnc", + state: "active", + token: randomUUID(), + wsUrl: `/ws/console/vnc?token=placeholder`, + startedAt: new Date().toISOString(), + }; + await sessionManager.createSession(session); + return sessionId; + } + + it("rejects with 403 when user lacks console:access (RBAC middleware blocks)", () => { + return fc.assert( + fc.asyncProperty( + fc.boolean(), // isSameUser (doesn't matter — blocked at middleware) + async (_isSameUser) => { + // User with no permissions at all + const { token } = await createUserWithToken("noaccess", false, false); + const owner = await createUserWithToken("owner", true, false); + const sessionId = await createOwnedSession(owner.userId); + + const res = await request(app) + .delete(`/api/console/sessions/${sessionId}`) + .set("Authorization", `Bearer ${token}`); + + expect(res.status).toBe(403); + }, + ), + { numRuns: 100 }, + ); + }, 120000); + + it("allows own session termination with only console:access (204)", () => { + return fc.assert( + fc.asyncProperty( + fc.boolean(), // has admin (irrelevant for own session — both should work) + async (hasAdmin) => { + const { userId, token } = await createUserWithToken( + "self", + true, + hasAdmin, + ); + const sessionId = await createOwnedSession(userId); + + const res = await request(app) + .delete(`/api/console/sessions/${sessionId}`) + .set("Authorization", `Bearer ${token}`); + + expect(res.status).toBe(204); + }, + ), + { numRuns: 100 }, + ); + }, 120000); + + it("rejects cross-user termination when user has console:access but NOT console:admin (403)", () => { + return fc.assert( + fc.asyncProperty( + fc.integer({ min: 0, max: 99999 }), // seed for unique user names + async (seed) => { + const owner = await createUserWithToken(`xo${String(seed)}`, true, false); + const { token } = await createUserWithToken(`xr${String(seed)}`, true, false); + const sessionId = await createOwnedSession(owner.userId); + + const res = await request(app) + .delete(`/api/console/sessions/${sessionId}`) + .set("Authorization", `Bearer ${token}`); + + expect(res.status).toBe(403); + expect(res.body.error.code).toBe("FORBIDDEN"); + expect(res.body.error.message).toContain("console:admin"); + }, + ), + { numRuns: 100 }, + ); + }, 120000); + + it("allows cross-user termination when user has console:access + console:admin (204)", () => { + return fc.assert( + fc.asyncProperty( + fc.integer({ min: 0, max: 99999 }), // seed for unique user names + async (seed) => { + const owner = await createUserWithToken(`ao${String(seed)}`, true, false); + const { token } = await createUserWithToken(`ad${String(seed)}`, true, true); + const sessionId = await createOwnedSession(owner.userId); + + const res = await request(app) + .delete(`/api/console/sessions/${sessionId}`) + .set("Authorization", `Bearer ${token}`); + + expect(res.status).toBe(204); + }, + ), + { numRuns: 100 }, + ); + }, 120000); +}); diff --git a/backend/test/properties/consoleResizeValidation.property.test.ts b/backend/test/properties/consoleResizeValidation.property.test.ts new file mode 100644 index 00000000..bb4ff126 --- /dev/null +++ b/backend/test/properties/consoleResizeValidation.property.test.ts @@ -0,0 +1,268 @@ +/** + * Property-Based Tests for Terminal Resize Dimension Validation + * + * Feature: console-integration, Property 4: Terminal resize dimension validation + * + * **Validates: Requirements 5.5, 5.8** + * + * Property 4: Terminal resize dimension validation + * ∀ resize control message with columns/rows: + * resize propagated iff columns ∈ [1, 500] AND rows ∈ [1, 200]; + * otherwise discarded without session termination. + */ + +import { describe, it, expect, vi, beforeEach } from "vitest"; +import * as fc from "fast-check"; +import { WebSocket } from "ws"; +import type { Server as HTTPServer } from "http"; + +import { ConsoleWebSocketProxy } from "../../src/services/ConsoleWebSocketProxy"; +import type { ConsoleSessionManager } from "../../src/services/ConsoleSessionManager"; +import type { LoggerService } from "../../src/services/LoggerService"; +import type { ConsoleSession } from "../../src/integrations/console/types"; + +// ============================================================ +// Helpers +// ============================================================ + +function createMockLogger(): LoggerService { + return { + info: vi.fn(), + warn: vi.fn(), + error: vi.fn(), + debug: vi.fn(), + } as unknown as LoggerService; +} + +function createMockSessionManager(): ConsoleSessionManager { + return { + generateToken: vi.fn(), + createSession: vi.fn(), + validateToken: vi.fn(), + consumeToken: vi.fn(), + heartbeat: vi.fn(), + terminateSession: vi.fn(), + getActiveSessionCount: vi.fn(), + terminateAllForProvider: vi.fn(), + cleanupExpiredSessions: vi.fn(), + getSession: vi.fn(), + } as unknown as ConsoleSessionManager; +} + +function createMockHttpServer(): HTTPServer { + return { on: vi.fn() } as unknown as HTTPServer; +} + +function createMockUpstream(): WebSocket { + return { + readyState: WebSocket.OPEN, + send: vi.fn(), + close: vi.fn(), + on: vi.fn(), + } as unknown as WebSocket; +} + +function createMockSession(): ConsoleSession { + return { + sessionId: "test-session-id", + token: "test-token", + wsUrl: "/ws/console/terminal", + transport: "websocket-terminal", + state: "active", + startedAt: new Date().toISOString(), + nodeId: "node-1", + userId: "user-1", + provider: "test-provider", + }; +} + +/** Build a valid 5-byte resize control message buffer. */ +function buildResizeBuffer(columns: number, rows: number): Buffer { + const buf = Buffer.alloc(5); + buf[0] = 0x01; // RESIZE type + buf.writeUInt16BE(columns, 1); + buf.writeUInt16BE(rows, 3); + return buf; +} + +// ============================================================ +// Arbitraries +// ============================================================ + +/** Full uint16 range for columns */ +const columnsArb = fc.integer({ min: 0, max: 65535 }); + +/** Full uint16 range for rows */ +const rowsArb = fc.integer({ min: 0, max: 65535 }); + +/** Valid columns: [1, 500] */ +const validColumnsArb = fc.integer({ min: 1, max: 500 }); + +/** Valid rows: [1, 200] */ +const validRowsArb = fc.integer({ min: 1, max: 200 }); + +/** Invalid columns: 0 or > 500 (within uint16) */ +const invalidColumnsArb = fc.oneof( + fc.constant(0), + fc.integer({ min: 501, max: 65535 }), +); + +/** Invalid rows: 0 or > 200 (within uint16) */ +const invalidRowsArb = fc.oneof( + fc.constant(0), + fc.integer({ min: 201, max: 65535 }), +); + +// ============================================================ +// Tests +// ============================================================ + +describe("Feature: console-integration, Property 4: Terminal resize dimension validation", () => { + let proxy: ConsoleWebSocketProxy; + let logger: LoggerService; + + beforeEach(() => { + logger = createMockLogger(); + const sessionManager = createMockSessionManager(); + const httpServer = createMockHttpServer(); + + proxy = new ConsoleWebSocketProxy( + httpServer, + sessionManager, + { allowedOrigins: ["http://localhost:3000"], console: { sessionTimeoutMs: 300000, maxSessionDuration: 28800000, maxConcurrentSessions: 3, heartbeatIntervalMs: 30000 } }, + logger, + ); + }); + + it("propagates resize when columns ∈ [1,500] AND rows ∈ [1,200]", () => { + fc.assert( + fc.property(validColumnsArb, validRowsArb, (columns, rows) => { + const upstream = createMockUpstream(); + const session = createMockSession(); + const data = buildResizeBuffer(columns, rows); + + // Call private method via bracket notation + (proxy as unknown as Record)["handleTerminalControlMessage"]( + data, upstream, session, + ); + + // upstream.send must have been called with the exact buffer + expect(upstream.send).toHaveBeenCalledTimes(1); + expect(upstream.send).toHaveBeenCalledWith(data, { binary: true }); + }), + { numRuns: 100 }, + ); + }); + + it("discards resize when columns or rows are outside valid range", () => { + fc.assert( + fc.property(columnsArb, rowsArb, (columns, rows) => { + // Pre-condition: at least one dimension is out of valid range + const columnsValid = columns >= 1 && columns <= 500; + const rowsValid = rows >= 1 && rows <= 200; + fc.pre(!(columnsValid && rowsValid)); + + const upstream = createMockUpstream(); + const session = createMockSession(); + const data = buildResizeBuffer(columns, rows); + + (proxy as unknown as Record)["handleTerminalControlMessage"]( + data, upstream, session, + ); + + // upstream.send must NOT have been called + expect(upstream.send).not.toHaveBeenCalled(); + }), + { numRuns: 100 }, + ); + }); + + it("never terminates session regardless of dimension validity", () => { + fc.assert( + fc.property(columnsArb, rowsArb, (columns, rows) => { + const upstream = createMockUpstream(); + const session = createMockSession(); + const sessionManager = createMockSessionManager(); + const httpServer = createMockHttpServer(); + const localLogger = createMockLogger(); + + const localProxy = new ConsoleWebSocketProxy( + httpServer, + sessionManager, + { allowedOrigins: ["http://localhost:3000"], console: { sessionTimeoutMs: 300000, maxSessionDuration: 28800000, maxConcurrentSessions: 3, heartbeatIntervalMs: 30000 } }, + localLogger, + ); + + const data = buildResizeBuffer(columns, rows); + + (localProxy as unknown as Record)["handleTerminalControlMessage"]( + data, upstream, session, + ); + + // Session must never be terminated + expect(sessionManager.terminateSession).not.toHaveBeenCalled(); + // Upstream must never be closed + expect(upstream.close).not.toHaveBeenCalled(); + }), + { numRuns: 100 }, + ); + }); + + it("resize propagation is correct: send called iff both dimensions valid", () => { + fc.assert( + fc.property(columnsArb, rowsArb, (columns, rows) => { + const upstream = createMockUpstream(); + const session = createMockSession(); + const data = buildResizeBuffer(columns, rows); + + (proxy as unknown as Record)["handleTerminalControlMessage"]( + data, upstream, session, + ); + + const shouldPropagate = columns >= 1 && columns <= 500 && rows >= 1 && rows <= 200; + + if (shouldPropagate) { + expect(upstream.send).toHaveBeenCalledTimes(1); + expect(upstream.send).toHaveBeenCalledWith(data, { binary: true }); + } else { + expect(upstream.send).not.toHaveBeenCalled(); + } + }), + { numRuns: 100 }, + ); + }); + + it("specifically tests invalid columns with valid rows → discarded", () => { + fc.assert( + fc.property(invalidColumnsArb, validRowsArb, (columns, rows) => { + const upstream = createMockUpstream(); + const session = createMockSession(); + const data = buildResizeBuffer(columns, rows); + + (proxy as unknown as Record)["handleTerminalControlMessage"]( + data, upstream, session, + ); + + expect(upstream.send).not.toHaveBeenCalled(); + }), + { numRuns: 100 }, + ); + }); + + it("specifically tests valid columns with invalid rows → discarded", () => { + fc.assert( + fc.property(validColumnsArb, invalidRowsArb, (columns, rows) => { + const upstream = createMockUpstream(); + const session = createMockSession(); + const data = buildResizeBuffer(columns, rows); + + (proxy as unknown as Record)["handleTerminalControlMessage"]( + data, upstream, session, + ); + + expect(upstream.send).not.toHaveBeenCalled(); + }), + { numRuns: 100 }, + ); + }); +}); diff --git a/backend/test/properties/consoleSessionRecord.property.test.ts b/backend/test/properties/consoleSessionRecord.property.test.ts new file mode 100644 index 00000000..a3dd4d80 --- /dev/null +++ b/backend/test/properties/consoleSessionRecord.property.test.ts @@ -0,0 +1,196 @@ +/** + * Property-Based Tests for Console Session Record Completeness + * + * Feature: console-integration, Property 8: Session record completeness + * + * **Validates: Requirements 2.7** + * + * Property 8: Session record completeness + * ∀ random ConsoleSession inputs: + * after createSession, the stored DB record SHALL have non-null + * id, user_id, node_id, provider, started_at, last_heartbeat_at. + */ + +import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"; +import * as fc from "fast-check"; +import { SQLiteAdapter } from "../../src/database/SQLiteAdapter"; +import { ConsoleSessionManager } from "../../src/services/ConsoleSessionManager"; +import type { ConsoleSession } from "../../src/integrations/console/types"; +import type { AuditLoggingService } from "../../src/services/AuditLoggingService"; +import type { LoggerService } from "../../src/services/LoggerService"; +import type { ConsoleConfig } from "../../src/config/schema"; + +const CREATE_TABLE_SQL = ` + CREATE TABLE IF NOT EXISTS console_sessions ( + id TEXT PRIMARY KEY, + user_id TEXT NOT NULL, + node_id TEXT NOT NULL, + provider TEXT NOT NULL, + transport TEXT NOT NULL, + state TEXT NOT NULL DEFAULT 'creating', + token TEXT, + token_created_at TEXT, + token_consumed INTEGER NOT NULL DEFAULT 0, + upstream_url TEXT, + started_at TEXT NOT NULL, + last_heartbeat_at TEXT, + terminated_at TEXT, + error_message TEXT, + CONSTRAINT chk_state CHECK (state IN ('creating', 'active', 'terminated', 'failed')), + CONSTRAINT chk_transport CHECK (transport IN ('websocket-vnc', 'websocket-terminal')) + ) +`; + +/** Arbitrary: hex string of given length */ +function hexStringArb(length: number): fc.Arbitrary { + return fc + .array( + fc.integer({ min: 0, max: 15 }).map((n) => n.toString(16)), + { minLength: length, maxLength: length }, + ) + .map((chars) => chars.join("")); +} + +/** Arbitrary: UUID-like string */ +const uuidArb = fc + .tuple( + hexStringArb(8), + hexStringArb(4), + hexStringArb(4), + hexStringArb(4), + hexStringArb(12), + ) + .map(([a, b, c, d, e]) => `${a}-${b}-${c}-${d}-${e}`); + +/** Arbitrary: random user IDs */ +const userIdArb = fc + .tuple(fc.constantFrom("user", "admin", "operator", "svc"), fc.nat({ max: 99999 })) + .map(([prefix, n]) => `${prefix}-${String(n)}`); + +/** Arbitrary: random node IDs */ +const nodeIdArb = fc + .tuple(fc.constantFrom("node", "vm", "lxc", "host"), fc.nat({ max: 99999 })) + .map(([prefix, n]) => `${prefix}-${String(n)}`); + +/** Arbitrary: random provider names */ +const providerArb = fc.constantFrom("proxmox", "aws", "azure", "ssh", "custom-provider"); + +/** Arbitrary: random transport types */ +const transportArb = fc.constantFrom<"websocket-vnc" | "websocket-terminal">( + "websocket-vnc", + "websocket-terminal", +); + +/** Arbitrary: a full ConsoleSession object */ +const consoleSessionArb = fc + .tuple(uuidArb, userIdArb, nodeIdArb, providerArb, transportArb) + .map(([sessionId, userId, nodeId, provider, transport]): ConsoleSession => ({ + sessionId, + userId, + nodeId, + provider, + transport, + state: "active", + token: `tok-${sessionId}`, + wsUrl: `/ws/console/${transport === "websocket-vnc" ? "vnc" : "terminal"}?token=tok-${sessionId}`, + startedAt: new Date().toISOString(), + })); + +function createMockLogger(): LoggerService { + return { + info: vi.fn(), + warn: vi.fn(), + error: vi.fn(), + debug: vi.fn(), + } as unknown as LoggerService; +} + +function createMockAuditLogger(): AuditLoggingService { + return { + logAdminAction: vi.fn().mockResolvedValue(undefined), + } as unknown as AuditLoggingService; +} + +const defaultConfig: ConsoleConfig = { + sessionTimeoutMs: 300000, + maxSessionDuration: 28800000, + maxConcurrentSessions: 3, + heartbeatIntervalMs: 30000, +}; + +describe("Feature: console-integration, Property 8: Session record completeness", () => { + let db: SQLiteAdapter; + let sessionManager: ConsoleSessionManager; + + beforeEach(async () => { + db = new SQLiteAdapter(":memory:"); + await db.initialize(); + await db.execute(CREATE_TABLE_SQL); + sessionManager = new ConsoleSessionManager( + db, + defaultConfig, + createMockLogger(), + createMockAuditLogger(), + ); + }); + + afterEach(async () => { + await db.close(); + }); + + it("stored session record always has non-null id, user_id, node_id, provider, started_at, last_heartbeat_at", async () => { + await fc.assert( + fc.asyncProperty(consoleSessionArb, async (session) => { + await sessionManager.createSession(session); + + const row = await db.queryOne<{ + id: string | null; + user_id: string | null; + node_id: string | null; + provider: string | null; + started_at: string | null; + last_heartbeat_at: string | null; + }>( + `SELECT id, user_id, node_id, provider, started_at, last_heartbeat_at + FROM console_sessions WHERE id = ?`, + [session.sessionId], + ); + + expect(row).not.toBeNull(); + expect(row!.id).not.toBeNull(); + expect(row!.user_id).not.toBeNull(); + expect(row!.node_id).not.toBeNull(); + expect(row!.provider).not.toBeNull(); + expect(row!.started_at).not.toBeNull(); + expect(row!.last_heartbeat_at).not.toBeNull(); + }), + { numRuns: 100 }, + ); + }); + + it("stored session record fields match the input values", async () => { + await fc.assert( + fc.asyncProperty(consoleSessionArb, async (session) => { + await sessionManager.createSession(session); + + const row = await db.queryOne<{ + id: string; + user_id: string; + node_id: string; + provider: string; + }>( + `SELECT id, user_id, node_id, provider + FROM console_sessions WHERE id = ?`, + [session.sessionId], + ); + + expect(row).not.toBeNull(); + expect(row!.id).toBe(session.sessionId); + expect(row!.user_id).toBe(session.userId); + expect(row!.node_id).toBe(session.nodeId); + expect(row!.provider).toBe(session.provider); + }), + { numRuns: 100 }, + ); + }); +}); diff --git a/backend/test/properties/consoleTokenValidation.property.test.ts b/backend/test/properties/consoleTokenValidation.property.test.ts new file mode 100644 index 00000000..2f4a40e2 --- /dev/null +++ b/backend/test/properties/consoleTokenValidation.property.test.ts @@ -0,0 +1,325 @@ +/** + * Property-Based Tests for Console Session Token Validation + * + * Feature: console-integration, Property 2: Session token validation correctness + * + * **Validates: Requirements 4.2, 4.3, 5.2, 5.3, 8.1, 8.2** + * + * Property 2: Session token validation correctness + * ∀ token, userId, timestamp, consumed state: + * validateToken(token, userId) returns a ConsoleSession iff: + * - token exists in DB + * - token was created < 60s ago + * - token has not been consumed (tokenConsumed === 0) + * - connecting userId matches session owner + * All other combinations → null (rejected) + */ + +import { describe, it, expect, beforeEach, afterEach } from "vitest"; +import * as fc from "fast-check"; + +import { SQLiteAdapter } from "../../src/database/SQLiteAdapter"; +import { ConsoleSessionManager } from "../../src/services/ConsoleSessionManager"; +import type { AuditLoggingService } from "../../src/services/AuditLoggingService"; +import type { LoggerService } from "../../src/services/LoggerService"; +import type { ConsoleConfig } from "../../src/config/schema"; + +const CONSOLE_CONFIG: ConsoleConfig = { + sessionTimeoutMs: 300000, + maxSessionDuration: 28800000, + maxConcurrentSessions: 3, + heartbeatIntervalMs: 30000, +}; + +const CREATE_TABLE_SQL = ` + CREATE TABLE IF NOT EXISTS console_sessions ( + id TEXT PRIMARY KEY, + user_id TEXT NOT NULL, + node_id TEXT NOT NULL, + provider TEXT NOT NULL, + transport TEXT NOT NULL, + state TEXT NOT NULL DEFAULT 'creating', + token TEXT, + token_created_at TEXT, + token_consumed INTEGER NOT NULL DEFAULT 0, + upstream_url TEXT, + started_at TEXT NOT NULL, + last_heartbeat_at TEXT, + terminated_at TEXT, + error_message TEXT, + created_at TEXT NOT NULL DEFAULT (datetime('now')), + CONSTRAINT chk_state CHECK (state IN ('creating', 'active', 'terminated', 'failed')), + CONSTRAINT chk_transport CHECK (transport IN ('websocket-vnc', 'websocket-terminal')) + ); + CREATE INDEX IF NOT EXISTS idx_console_sessions_token ON console_sessions(token); +`; + +function createMockLogger(): LoggerService { + return { + info: () => {}, + warn: () => {}, + error: () => {}, + debug: () => {}, + } as unknown as LoggerService; +} + +function createMockAuditLogger(): AuditLoggingService { + return { + logAdminAction: async () => {}, + } as unknown as AuditLoggingService; +} + +/** Arbitrary: hex-like token strings (16–64 hex chars) */ +const tokenArb = fc.stringMatching(/^[0-9a-f]{16,64}$/); + +/** Arbitrary: user IDs (alphanumeric, 4–20 chars) */ +const userIdArb = fc.stringMatching(/^[a-z0-9]{4,20}$/); + +/** Arbitrary: session IDs */ +const sessionIdArb = fc.uuid(); + +/** Arbitrary: node IDs */ +const nodeIdArb = fc.stringMatching(/^node-[a-z0-9]{3,10}$/); + +/** Arbitrary: provider names */ +const providerArb = fc.constantFrom("proxmox", "aws", "azure"); + +/** Arbitrary: transport types */ +const transportArb = fc.constantFrom( + "websocket-vnc" as const, + "websocket-terminal" as const, +); + +/** + * Represents a session row to insert, with controllable validity factors. + */ +interface TestSessionParams { + sessionId: string; + ownerUserId: string; + nodeId: string; + provider: string; + transport: "websocket-vnc" | "websocket-terminal"; + token: string; + /** Milliseconds ago the token was created (0 = now) */ + tokenAgeMs: number; + /** Whether token has been consumed */ + consumed: boolean; +} + +const testSessionArb: fc.Arbitrary = fc.record({ + sessionId: sessionIdArb, + ownerUserId: userIdArb, + nodeId: nodeIdArb, + provider: providerArb, + transport: transportArb, + token: tokenArb, + // Ages from 0ms to 120s to cover both valid (<60s) and expired (>=60s) + tokenAgeMs: fc.integer({ min: 0, max: 120000 }), + consumed: fc.boolean(), +}); + +async function insertSession( + db: SQLiteAdapter, + params: TestSessionParams, +): Promise { + const tokenCreatedAt = new Date( + Date.now() - params.tokenAgeMs, + ).toISOString(); + const now = new Date().toISOString(); + + await db.execute( + `INSERT INTO console_sessions ( + id, user_id, node_id, provider, transport, state, + token, token_created_at, token_consumed, upstream_url, + started_at, last_heartbeat_at + ) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, NULL, ?, ?)`, + [ + params.sessionId, + params.ownerUserId, + params.nodeId, + params.provider, + params.transport, + params.token, + tokenCreatedAt, + params.consumed ? 1 : 0, + now, + now, + ], + ); +} + +describe("Feature: console-integration, Property 2: Session token validation correctness", () => { + let db: SQLiteAdapter; + let sessionManager: ConsoleSessionManager; + + beforeEach(async () => { + db = new SQLiteAdapter(":memory:"); + await db.initialize(); + await db.execute(CREATE_TABLE_SQL); + sessionManager = new ConsoleSessionManager( + db, + CONSOLE_CONFIG, + createMockLogger(), + createMockAuditLogger(), + ); + }); + + afterEach(async () => { + await db.close(); + }); + + it("valid token accepted: exists, <60s old, not consumed, userId matches owner", async () => { + await fc.assert( + fc.asyncProperty(testSessionArb, async (params) => { + // Force all validity conditions + const validParams: TestSessionParams = { + ...params, + tokenAgeMs: Math.min(params.tokenAgeMs, 59000), // <60s + consumed: false, + }; + + // Clean slate for each run + await db.execute("DELETE FROM console_sessions"); + await insertSession(db, validParams); + + const result = await sessionManager.validateToken( + validParams.token, + validParams.ownerUserId, + ); + + expect(result).not.toBeNull(); + expect(result!.sessionId).toBe(validParams.sessionId); + expect(result!.userId).toBe(validParams.ownerUserId); + expect(result!.token).toBe(validParams.token); + }), + { numRuns: 100 }, + ); + }); + + it("token rejected when it does not exist in DB", async () => { + await fc.assert( + fc.asyncProperty(tokenArb, userIdArb, async (token, userId) => { + // Empty DB — no tokens exist + await db.execute("DELETE FROM console_sessions"); + + const result = await sessionManager.validateToken(token, userId); + expect(result).toBeNull(); + }), + { numRuns: 100 }, + ); + }); + + it("token rejected when consumed (tokenConsumed !== 0)", async () => { + await fc.assert( + fc.asyncProperty(testSessionArb, async (params) => { + const consumedParams: TestSessionParams = { + ...params, + tokenAgeMs: Math.min(params.tokenAgeMs, 59000), // valid age + consumed: true, // consumed → should be rejected + }; + + await db.execute("DELETE FROM console_sessions"); + await insertSession(db, consumedParams); + + const result = await sessionManager.validateToken( + consumedParams.token, + consumedParams.ownerUserId, + ); + expect(result).toBeNull(); + }), + { numRuns: 100 }, + ); + }); + + it("token rejected when expired (created >= 60s ago)", async () => { + await fc.assert( + fc.asyncProperty(testSessionArb, async (params) => { + const expiredParams: TestSessionParams = { + ...params, + tokenAgeMs: Math.max(params.tokenAgeMs, 60000), // >=60s + consumed: false, + }; + + await db.execute("DELETE FROM console_sessions"); + await insertSession(db, expiredParams); + + const result = await sessionManager.validateToken( + expiredParams.token, + expiredParams.ownerUserId, + ); + expect(result).toBeNull(); + }), + { numRuns: 100 }, + ); + }); + + it("token rejected when connecting userId does not match session owner", async () => { + await fc.assert( + fc.asyncProperty( + testSessionArb, + userIdArb, + async (params, differentUserId) => { + // Ensure the connecting user is different from the owner + fc.pre(differentUserId !== params.ownerUserId); + + const validParams: TestSessionParams = { + ...params, + tokenAgeMs: Math.min(params.tokenAgeMs, 59000), // valid age + consumed: false, + }; + + await db.execute("DELETE FROM console_sessions"); + await insertSession(db, validParams); + + const result = await sessionManager.validateToken( + validParams.token, + differentUserId, + ); + expect(result).toBeNull(); + }, + ), + { numRuns: 100 }, + ); + }); + + it("token validation is a conjunction: ALL conditions must hold for acceptance", async () => { + await fc.assert( + fc.asyncProperty( + testSessionArb, + userIdArb, + fc.boolean(), + async (params, connectingUserId, useCorrectUser) => { + const connectAs = useCorrectUser + ? params.ownerUserId + : connectingUserId; + + // Skip when "different" user accidentally equals owner + if (!useCorrectUser) { + fc.pre(connectAs !== params.ownerUserId); + } + + await db.execute("DELETE FROM console_sessions"); + await insertSession(db, params); + + const result = await sessionManager.validateToken( + params.token, + connectAs, + ); + + const isValid = + params.tokenAgeMs < 60000 && + !params.consumed && + connectAs === params.ownerUserId; + + if (isValid) { + expect(result).not.toBeNull(); + expect(result!.sessionId).toBe(params.sessionId); + } else { + expect(result).toBeNull(); + } + }, + ), + { numRuns: 100 }, + ); + }); +}); diff --git a/backend/test/properties/consoleUnhealthyProvider.property.test.ts b/backend/test/properties/consoleUnhealthyProvider.property.test.ts new file mode 100644 index 00000000..63232562 --- /dev/null +++ b/backend/test/properties/consoleUnhealthyProvider.property.test.ts @@ -0,0 +1,334 @@ +/** + * Property-Based Tests for Unhealthy Provider Exclusion + * + * Feature: console-integration, Property 15: Unhealthy provider exclusion + * + * **Validates: Requirements 10.1** + * + * Property 15: Unhealthy provider exclusion + * ∀ provider sets with random health states (healthy/throws): + * Only providers that return successfully from getConsoleCapabilities + * appear in the availability response. Providers that throw are excluded + * while healthy providers remain included. + */ + +import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"; +import * as fc from "fast-check"; + +import { IntegrationManager } from "../../src/integrations/IntegrationManager"; +import type { ConsolePlugin, ConsoleCapability, ConsoleSession, ConsoleSessionStatus, ConsoleTransport } from "../../src/integrations/console/types"; +import type { IntegrationConfig, HealthStatus } from "../../src/integrations/types"; +import type { LoggerService } from "../../src/services/LoggerService"; + +type ProviderHealthState = "healthy" | "throws" | "timeouts"; + +function makeLogger(): LoggerService { + return { + info: () => {}, + warn: () => {}, + error: () => {}, + debug: () => {}, + } as unknown as LoggerService; +} + +function makeMockConsolePlugin( + name: string, + healthState: ProviderHealthState, +): ConsolePlugin { + return { + name, + type: "information" as const, + + async initialize(_config: IntegrationConfig): Promise {}, + async healthCheck(): Promise { + return { healthy: healthState === "healthy", lastCheck: new Date().toISOString() }; + }, + getConfig(): IntegrationConfig { + return { enabled: true, name, type: "information", config: {} }; + }, + isInitialized(): boolean { + return true; + }, + + async getConsoleCapabilities(_nodeId: string): Promise { + if (healthState === "throws") { + throw new Error(`Provider '${name}' is unavailable`); + } + if (healthState === "timeouts") { + // Return a promise that never resolves (killed by the 3s timeout) + return new Promise(() => {}); + } + // Healthy: return capabilities + return [{ + transport: "websocket-vnc" as ConsoleTransport, + displayName: `${name} VNC Console`, + connectionSchema: {}, + }]; + }, + + async createSession(_nodeId: string, _userId: string): Promise { + return { + sessionId: "mock-session", + token: "mock-token", + wsUrl: "/ws/console/vnc", + transport: "websocket-vnc", + state: "active", + startedAt: new Date().toISOString(), + nodeId: "node-1", + userId: "user-1", + provider: name, + }; + }, + + async terminateSession(_sessionId: string): Promise { + return true; + }, + + async getSessionStatus(_sessionId: string): Promise { + return { state: "active", startedAt: new Date().toISOString() }; + }, + + getSupportedTransports(): ConsoleTransport[] { + return ["websocket-vnc"]; + }, + }; +} + +/** Arbitrary for a valid provider name (lowercase alpha, no duplicates handled externally) */ +const providerNameArb = fc.stringMatching(/^[a-z]{2,12}$/); + +/** Arbitrary for provider health state (throws only — timeouts tested separately) */ +const unhealthyStateArb = fc.constant("throws"); + +/** + * Arbitrary for a list of providers with random health states. + * Uses only "healthy" and "throws" to avoid real 3s waits per timeout provider. + */ +const providerListArb = fc + .array( + fc.tuple(providerNameArb, fc.constantFrom("healthy", "throws")), + { minLength: 1, maxLength: 6 }, + ) + .map((entries) => { + const seen = new Set(); + return entries.filter(([name]) => { + if (seen.has(name)) return false; + seen.add(name); + return true; + }); + }) + .filter((entries) => entries.length >= 1); + +describe("Feature: console-integration, Property 15: Unhealthy provider exclusion", () => { + beforeEach(() => { + vi.useFakeTimers(); + }); + + afterEach(() => { + vi.useRealTimers(); + }); + + it("only healthy providers appear in availability response; throwing providers are excluded", () => { + return fc.assert( + fc.asyncProperty( + providerListArb, + async (providers) => { + const manager = new IntegrationManager({ logger: makeLogger() }); + + for (const [name, healthState] of providers) { + const plugin = makeMockConsolePlugin(name, healthState); + manager.registerPlugin(plugin, { + enabled: true, + name, + type: "information", + config: {}, + }); + } + + const resultPromise = manager.getConsoleAvailability("test-node"); + // Advance timers to resolve any pending timeouts + await vi.advanceTimersByTimeAsync(0); + const result = await resultPromise; + + // Determine expected healthy providers + const healthyProviders = providers + .filter(([, state]) => state === "healthy") + .map(([name]) => name) + .sort(); + + // Result should contain exactly the healthy providers + const resultProviders = result.map((entry) => entry.provider).sort(); + expect(resultProviders).toEqual(healthyProviders); + + // Each entry from a healthy provider should have correct structure + for (const entry of result) { + expect(entry.provider).toBeTruthy(); + expect(entry.transport).toBe("websocket-vnc"); + expect(entry.displayName).toContain("VNC Console"); + } + }, + ), + { numRuns: 100 }, + ); + }); + + it("when all providers are unhealthy (throwing), availability returns empty array", () => { + return fc.assert( + fc.asyncProperty( + fc.array(providerNameArb, { minLength: 1, maxLength: 5 }) + .map((names) => [...new Set(names)]) + .filter((names) => names.length >= 1), + async (names) => { + const manager = new IntegrationManager({ logger: makeLogger() }); + + for (const name of names) { + const plugin = makeMockConsolePlugin(name, "throws"); + manager.registerPlugin(plugin, { + enabled: true, + name, + type: "information", + config: {}, + }); + } + + const resultPromise = manager.getConsoleAvailability("test-node"); + await vi.advanceTimersByTimeAsync(0); + const result = await resultPromise; + + expect(result).toEqual([]); + }, + ), + { numRuns: 100 }, + ); + }); + + it("when all providers are healthy, all appear in availability response", () => { + return fc.assert( + fc.asyncProperty( + fc.array(providerNameArb, { minLength: 1, maxLength: 6 }) + .map((names) => [...new Set(names)]) + .filter((names) => names.length >= 1), + async (names) => { + const manager = new IntegrationManager({ logger: makeLogger() }); + + for (const name of names) { + const plugin = makeMockConsolePlugin(name, "healthy"); + manager.registerPlugin(plugin, { + enabled: true, + name, + type: "information", + config: {}, + }); + } + + const resultPromise = manager.getConsoleAvailability("test-node"); + await vi.advanceTimersByTimeAsync(0); + const result = await resultPromise; + + const resultProviders = result.map((e) => e.provider).sort(); + const expectedProviders = [...names].sort(); + expect(resultProviders).toEqual(expectedProviders); + }, + ), + { numRuns: 100 }, + ); + }); + + it("healthy providers are included regardless of other providers' health states", () => { + return fc.assert( + fc.asyncProperty( + providerListArb.filter((providers) => { + const hasHealthy = providers.some(([, s]) => s === "healthy"); + const hasUnhealthy = providers.some(([, s]) => s !== "healthy"); + return hasHealthy && hasUnhealthy; + }), + async (providers) => { + const manager = new IntegrationManager({ logger: makeLogger() }); + + for (const [name, healthState] of providers) { + const plugin = makeMockConsolePlugin(name, healthState); + manager.registerPlugin(plugin, { + enabled: true, + name, + type: "information", + config: {}, + }); + } + + const resultPromise = manager.getConsoleAvailability("test-node"); + await vi.advanceTimersByTimeAsync(0); + const result = await resultPromise; + + const resultProviderSet = new Set(result.map((e) => e.provider)); + + // Every healthy provider must appear + for (const [name, state] of providers) { + if (state === "healthy") { + expect(resultProviderSet.has(name)).toBe(true); + } + } + + // No unhealthy provider should appear + for (const [name, state] of providers) { + if (state !== "healthy") { + expect(resultProviderSet.has(name)).toBe(false); + } + } + }, + ), + { numRuns: 100 }, + ); + }); + + it("timeout providers are excluded after the 3s deadline elapses", () => { + return fc.assert( + fc.asyncProperty( + fc.array(providerNameArb, { minLength: 1, maxLength: 3 }) + .map((names) => [...new Set(names)]) + .filter((names) => names.length >= 1), + async (names) => { + const manager = new IntegrationManager({ logger: makeLogger() }); + + // Register one healthy provider and all generated names as timeout providers + const healthyName = "healthyprovider"; + const healthyPlugin = makeMockConsolePlugin(healthyName, "healthy"); + manager.registerPlugin(healthyPlugin, { + enabled: true, + name: healthyName, + type: "information", + config: {}, + }); + + for (const name of names) { + // Skip if name collides with the healthy provider name + if (name === healthyName) continue; + const plugin = makeMockConsolePlugin(name, "timeouts"); + manager.registerPlugin(plugin, { + enabled: true, + name, + type: "information", + config: {}, + }); + } + + const resultPromise = manager.getConsoleAvailability("test-node"); + // Advance past the 3s timeout + await vi.advanceTimersByTimeAsync(3100); + const result = await resultPromise; + + // Only the healthy provider should appear + const resultProviderSet = new Set(result.map((e) => e.provider)); + expect(resultProviderSet.has(healthyName)).toBe(true); + + // Timeout providers should be excluded + for (const name of names) { + if (name !== healthyName) { + expect(resultProviderSet.has(name)).toBe(false); + } + } + }, + ), + { numRuns: 100 }, + ); + }); +}); diff --git a/backend/test/properties/consoleUnsupportedNode.property.test.ts b/backend/test/properties/consoleUnsupportedNode.property.test.ts new file mode 100644 index 00000000..2bd07b54 --- /dev/null +++ b/backend/test/properties/consoleUnsupportedNode.property.test.ts @@ -0,0 +1,151 @@ +/** + * Property-Based Tests for Unsupported Node Empty Availability + * + * Feature: console-integration, Property 11: Unsupported node returns empty availability + * + * **Validates: Requirements 3.2** + * + * Property 11: Unsupported node returns empty availability + * ∀ nodeId ∈ arbitrary strings, providers ∈ [0..5]: + * When no registered provider supports console access for the given nodeId + * (all return empty capabilities), getConsoleAvailability returns []. + */ + +import { describe, it, expect } from "vitest"; +import * as fc from "fast-check"; + +import { IntegrationManager } from "../../src/integrations/IntegrationManager"; +import type { ConsolePlugin, ConsoleCapability, ConsoleSession, ConsoleSessionStatus, ConsoleTransport } from "../../src/integrations/console/types"; +import type { IntegrationConfig, HealthStatus } from "../../src/integrations/types"; +import type { LoggerService } from "../../src/services/LoggerService"; + +function makeLogger(): LoggerService { + return { + info: () => {}, + warn: () => {}, + error: () => {}, + debug: () => {}, + } as unknown as LoggerService; +} + +/** + * Create a mock ConsolePlugin that returns empty capabilities for any node. + * This simulates a provider that does not support the queried node. + */ +function makeUnsupportingProvider(name: string): ConsolePlugin { + return { + name, + type: "information" as const, + initialize: async () => {}, + healthCheck: async (): Promise => ({ + healthy: true, + message: "OK", + lastCheck: new Date().toISOString(), + }), + getConfig: (): IntegrationConfig => ({ + name, + enabled: true, + priority: 5, + }), + isInitialized: () => true, + getConsoleCapabilities: async (): Promise => [], + createSession: async (): Promise => { + throw new Error("No console capability for this node"); + }, + terminateSession: async (): Promise => false, + getSessionStatus: async (): Promise => ({ + state: "terminated", + startedAt: new Date().toISOString(), + }), + getSupportedTransports: (): ConsoleTransport[] => ["websocket-vnc"], + }; +} + +describe("Feature: console-integration, Property 11: Unsupported node returns empty availability", () => { + it("returns empty array when no providers are registered", () => { + return fc.assert( + fc.asyncProperty( + fc.string({ minLength: 1, maxLength: 100 }), + async (nodeId) => { + const manager = new IntegrationManager({ logger: makeLogger() }); + + const result = await manager.getConsoleAvailability(nodeId); + + expect(result).toEqual([]); + }, + ), + { numRuns: 100 }, + ); + }); + + it("returns empty array when all registered providers return empty capabilities", () => { + return fc.assert( + fc.asyncProperty( + fc.string({ minLength: 1, maxLength: 100 }), + fc.integer({ min: 1, max: 5 }), + async (nodeId, providerCount) => { + const manager = new IntegrationManager({ logger: makeLogger() }); + + // Register N providers that all return empty capabilities + for (let i = 0; i < providerCount; i++) { + const provider = makeUnsupportingProvider(`provider-${String(i)}`); + manager.registerPlugin(provider, { + name: `provider-${String(i)}`, + enabled: true, + priority: 5, + }); + } + + const result = await manager.getConsoleAvailability(nodeId); + + expect(result).toEqual([]); + }, + ), + { numRuns: 100 }, + ); + }); + + it("returns empty array for varied node ID formats when providers do not support them", () => { + return fc.assert( + fc.asyncProperty( + fc.oneof( + // UUID-like IDs + fc.uuid(), + // Numeric IDs + fc.integer({ min: 1, max: 99999 }).map(String), + // Prefixed IDs (proxmox-style) + fc.tuple( + fc.constantFrom("proxmox", "aws", "azure", "ssh", "bolt"), + fc.string({ minLength: 1, maxLength: 30 }).filter((s) => s.trim().length > 0), + ).map(([prefix, suffix]) => `${prefix}:${suffix}`), + // Hostname-style IDs + fc.tuple( + fc.string({ minLength: 1, maxLength: 20, unit: fc.constantFrom(..."abcdefghijklmnopqrstuvwxyz0123456789") }), + fc.constantFrom(".local", ".internal", ".example.com", ""), + ).map(([host, domain]) => `${host}${domain}`), + // Arbitrary non-empty strings + fc.string({ minLength: 1, maxLength: 200 }).filter((s) => s.trim().length > 0), + ), + fc.integer({ min: 1, max: 5 }), + async (nodeId, providerCount) => { + const manager = new IntegrationManager({ logger: makeLogger() }); + + for (let i = 0; i < providerCount; i++) { + const provider = makeUnsupportingProvider(`provider-${String(i)}`); + manager.registerPlugin(provider, { + name: `provider-${String(i)}`, + enabled: true, + priority: 5, + }); + } + + const result = await manager.getConsoleAvailability(nodeId); + + expect(result).toEqual([]); + expect(Array.isArray(result)).toBe(true); + }, + ), + { numRuns: 100 }, + ); + }); +}); diff --git a/frontend/package.json b/frontend/package.json index 0929d630..a6ffc415 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -13,6 +13,10 @@ "lint:fix": "eslint src --ext .ts --fix" }, "dependencies": { + "@novnc/novnc": "^1.7.0", + "@xterm/addon-attach": "^0.12.0", + "@xterm/addon-fit": "^0.11.0", + "@xterm/xterm": "^6.0.0", "svelte": "^5.0.0" }, "devDependencies": { diff --git a/frontend/src/components/ActionRow.svelte b/frontend/src/components/ActionRow.svelte new file mode 100644 index 00000000..709f804e --- /dev/null +++ b/frontend/src/components/ActionRow.svelte @@ -0,0 +1,19 @@ + + +{#if widgets.length > 0} +
+ {#each widgets as widget (widget.id)} + + {/each} +
+{/if} diff --git a/frontend/src/components/ConsoleAccessWidget.svelte b/frontend/src/components/ConsoleAccessWidget.svelte new file mode 100644 index 00000000..6b5f02eb --- /dev/null +++ b/frontend/src/components/ConsoleAccessWidget.svelte @@ -0,0 +1,59 @@ + + +{#if loaded && capabilities.length > 0} +
+
+

Console

+
+
+ +
+
+{/if} diff --git a/frontend/src/components/ConsoleViewer.svelte b/frontend/src/components/ConsoleViewer.svelte new file mode 100644 index 00000000..c1a8b3ce --- /dev/null +++ b/frontend/src/components/ConsoleViewer.svelte @@ -0,0 +1,403 @@ + + +
+ +
+
+ + + {statusLabel} + {#if activeCapability} + — {activeCapability.displayName} + {/if} +
+ +
+ {#if status === 'disconnected' && !errorMessage} + + {/if} + + {#if status === 'connected'} + + {/if} + + +
+
+ + +
+ {#if errorMessage} +
+
+ + + +

{errorMessage}

+
+ +
+ {/if} + + {#if status === 'connecting'} +
+
+ + + + + Establishing connection... +
+
+ {/if} + + {#if !activeCapability} +
+

No console capabilities available for this node.

+
+ {/if} + + + {#if isVnc} +
+ {/if} + + + {#if isTerminal} +
+ {/if} +
+
diff --git a/frontend/src/components/GeneralInfoWidget.svelte b/frontend/src/components/GeneralInfoWidget.svelte new file mode 100644 index 00000000..0e60a1ef --- /dev/null +++ b/frontend/src/components/GeneralInfoWidget.svelte @@ -0,0 +1,234 @@ + + +{#if node} +
+
+

General Information

+
+ + {#if hasPuppetFacts} + + + + {/if} +
+
+
+
+
Node ID
+
{node.id}
+
+
+
Transport
+
{node.transport}
+
+
+
URI
+
{node.uri}
+
+ {#if generalInfo.os} +
+
Operating System
+
{generalInfo.os}
+
+ {/if} + {#if generalInfo.ip} +
+
IP Address
+
{generalInfo.ip}
+
+ {/if} + {#if generalInfo.hostname} +
+
Hostname
+
{generalInfo.hostname}
+
+ {/if} + {#if generalInfo.kernel} +
+
Kernel
+
{generalInfo.kernel}
+
+ {/if} + {#if generalInfo.architecture} +
+
Architecture
+
{generalInfo.architecture}
+
+ {/if} + {#if generalInfo.puppetVersion} +
+
Puppet Version
+
{generalInfo.puppetVersion}
+
+ {/if} + {#if generalInfo.memory} +
+
Memory
+
{generalInfo.memory}
+
+ {/if} + {#if generalInfo.cpuCount} +
+
Number of CPUs
+
{generalInfo.cpuCount}
+
+ {/if} + {#if generalInfo.uptime} +
+
Uptime
+
{generalInfo.uptime}
+
+ {/if} + {#if generalInfo.disks && generalInfo.disks.length > 0} +
+
Disks
+
{generalInfo.disks.join(', ')}
+
+ {/if} + {#if node.config.user} +
+
User
+
{node.config.user}
+
+ {/if} + {#if node.config.port} +
+
Port
+
{node.config.port}
+
+ {/if} +
+ {#if !generalInfo.os && !generalInfo.ip && !hasPuppetFacts} +
+
+ + + +

+ Additional system information (OS, IP) will appear here once PuppetDB facts are gathered. +

+
+
+ {/if} +
+{/if} diff --git a/frontend/src/components/LatestActionsWidget.svelte b/frontend/src/components/LatestActionsWidget.svelte new file mode 100644 index 00000000..15ec776f --- /dev/null +++ b/frontend/src/components/LatestActionsWidget.svelte @@ -0,0 +1,97 @@ + + +
+
+

Latest Actions

+ +
+ {#if loading} +
+ +
+ {:else if error} + + {:else if executions.length === 0} +

+ No executions found for this node. +

+ {:else} + router.navigate(`/executions?id=${execution.id}`)} + showTargets={false} + /> + {#if executions.length > 5} + { e.preventDefault(); router.navigate(`/executions?targetNode=${nodeId}`); }} + > + View all executions → + + {/if} + {/if} +
diff --git a/frontend/src/components/MonitoringSummaryWidget.svelte b/frontend/src/components/MonitoringSummaryWidget.svelte new file mode 100644 index 00000000..287e939a --- /dev/null +++ b/frontend/src/components/MonitoringSummaryWidget.svelte @@ -0,0 +1,147 @@ + + +
+
+

Monitoring Summary

+ +
+ + {#if loading} +
+ +
+ {:else if error} +

+ Unable to load monitoring data. + +

+ {:else if services.length === 0} +

+ No monitored services found for this node. +

+ {:else} + +
+
+
{summary.total}
+
Total
+
+
+
{summary.ok}
+
OK
+
+ {#if summary.warn > 0} +
+
{summary.warn}
+
Warning
+
+ {/if} + {#if summary.crit > 0} +
+
{summary.crit}
+
Critical
+
+ {/if} + {#if summary.unknown > 0} +
+
{summary.unknown}
+
Unknown
+
+ {/if} +
+ + + {#if critWarnServices.length > 0} +
+

Issues requiring attention

+
+ {#each critWarnServices.slice(0, 10) as service (service.description)} +
+
+ + {STATE_NAMES[service.state]} + + {service.description} +
+ {#if service.pluginOutput} +

{service.pluginOutput}

+ {/if} +
+ {/each} +
+ {#if critWarnServices.length > 10} + + {/if} +
+ {/if} + + {#if critWarnServices.length === 0} +

All monitored services are healthy.

+ {/if} + {/if} +
diff --git a/frontend/src/components/PuppetRunsWidget.svelte b/frontend/src/components/PuppetRunsWidget.svelte new file mode 100644 index 00000000..940ef0d0 --- /dev/null +++ b/frontend/src/components/PuppetRunsWidget.svelte @@ -0,0 +1,241 @@ + + +
+
+

Latest Puppet Runs

+ +
+ +
+ {#if !reports && loading} +

+ Loading Puppet runs... + +

+ {:else if reports && reports.length === 0} +

+ No Puppet runs found for this node. +

+ {:else if reports} +
+ + + + + + + + + + + + + + + + + + + {#each reports as report (report.hash)} + navigateToReports()} + > + + + + + + + + + + + + + + {/each} + +
+ Start Time + + Duration + + Environment + + Total + + Corrective + + Intentional + + Unchanged + + Failed + + Skipped + + Noop + + Compile Time + + Status +
+ {formatTimestamp(report.start_time)} + + {getDuration(report.start_time, report.end_time)} + +
+ {report.environment} + {#if report.noop} + + No-op + + {/if} +
+ 		+ {report.metrics.resources.total} + + {report.metrics.resources.corrective_change || 0} + + {getIntentionalChanges(report.metrics)} + + {getUnchanged(report.metrics)} + + {report.metrics.resources.failed} + + {report.metrics.resources.skipped} + + {report.metrics.events?.noop || 0} + + {formatCompilationTime(report.metrics.time?.config_retrieval)} + + +
+
+ + {#if reports.length >= 5} + + {/if} + {/if} +
+
diff --git a/frontend/src/components/WidgetFrame.svelte b/frontend/src/components/WidgetFrame.svelte new file mode 100644 index 00000000..786463be --- /dev/null +++ b/frontend/src/components/WidgetFrame.svelte @@ -0,0 +1,76 @@ + + +
+ {#if state === 'loading'} +
+
+
+
+
+
+
+ {/if} + + {#if state === 'error'} +
+
+ {widget.integration} + {error} +
+ +
+ {/if} + + {#if state === 'loading' || state === 'ready'} +
+ {#key mountKey} + + {/key} +
+ {/if} +
diff --git a/frontend/src/components/WidgetGrid.svelte b/frontend/src/components/WidgetGrid.svelte new file mode 100644 index 00000000..78972411 --- /dev/null +++ b/frontend/src/components/WidgetGrid.svelte @@ -0,0 +1,69 @@ + + +{#if statusError} +
+

+ Unable to load integration status: {statusError} +

+
+{:else} + {#if actionWidgets.length > 0} + + {/if} + +
+ {#each gridWidgets as widget (widget.id)} + + {/each} +
+{/if} diff --git a/frontend/src/lib/widgetRegistry.svelte.ts b/frontend/src/lib/widgetRegistry.svelte.ts new file mode 100644 index 00000000..eec99790 --- /dev/null +++ b/frontend/src/lib/widgetRegistry.svelte.ts @@ -0,0 +1,92 @@ +/** + * Widget Registry — frontend-only reactive store for plugin-contributed widgets. + * + * Integration plugins register widgets at module load time via static import + * side-effects. The registry maintains an ordered collection accessible to + * WidgetGrid for filtering and rendering. + * + * Uses Svelte 5 $state rune for reactive state. + * + * Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 7.1 + */ + +import type { Component } from 'svelte'; + +export type WidgetType = 'action' | 'list' | 'summary'; + +export interface WidgetDefinition { + /** Unique identifier for the widget */ + id: string; + /** Display name shown in error badges */ + name: string; + /** Svelte component to render */ + component: Component; + /** Integration name (must match /api/integrations/status response) */ + integration: string; + /** Widget category: determines placement (action → ActionRow, others → grid) */ + type: WidgetType; + /** Column span in the grid: 1, 2, or 3. Clamped to [1,3] on registration. */ + colSpan: number; + /** Numeric priority weight. Lower renders first. */ + priority: number; +} + +export interface IntegrationStatusEntry { + name: string; + status: 'connected' | 'degraded' | 'not_configured' | 'error' | 'disconnected'; + type: 'execution' | 'information' | 'both'; +} + +// Internal reactive state +let definitions = $state([]); + +/** + * Register a widget definition. Column span is clamped to [1,3]. + * Called at module load time as a side-effect of static imports. + */ +export function registerWidget(def: WidgetDefinition): void { + const clamped: WidgetDefinition = { + ...def, + colSpan: Math.max(1, Math.min(3, Math.round(def.colSpan))), + }; + definitions.push(clamped); +} + +/** + * Get all registered widget definitions (readonly snapshot). + */ +export function getWidgets(): readonly WidgetDefinition[] { + return definitions; +} + +/** + * Reset registry state. For use in tests only. + */ +export function _resetForTesting(): void { + definitions = []; +} + +/** + * Filter widgets to only those whose integration is connected or degraded. + * Pure function — no side effects, easily testable. + */ +export function filterWidgetsByStatus( + widgets: readonly WidgetDefinition[], + integrations: readonly IntegrationStatusEntry[], +): WidgetDefinition[] { + const enabled = new Set( + integrations + .filter(i => i.status === 'connected' || i.status === 'degraded') + .map(i => i.name), + ); + return widgets.filter(w => enabled.has(w.integration)); +} + +/** + * Sort widgets by ascending priority weight, preserving registration order + * for widgets with equal priority (stable sort). + * Pure function — no side effects, easily testable. + */ +export function stableSortByPriority(widgets: readonly WidgetDefinition[]): WidgetDefinition[] { + return [...widgets].sort((a, b) => a.priority - b.priority); +} diff --git a/frontend/src/lib/widgets/consoleAccess.widget.ts b/frontend/src/lib/widgets/consoleAccess.widget.ts new file mode 100644 index 00000000..81d0809b --- /dev/null +++ b/frontend/src/lib/widgets/consoleAccess.widget.ts @@ -0,0 +1,12 @@ +import { registerWidget } from '../widgetRegistry.svelte'; +import ConsoleAccessWidget from '../../components/ConsoleAccessWidget.svelte'; + +registerWidget({ + id: 'proxmox-console-access', + name: 'Console Access', + component: ConsoleAccessWidget, + integration: 'proxmox', + type: 'action', + colSpan: 1, + priority: 100, +}); diff --git a/frontend/src/lib/widgets/generalInfo.widget.ts b/frontend/src/lib/widgets/generalInfo.widget.ts new file mode 100644 index 00000000..d3eb4cb8 --- /dev/null +++ b/frontend/src/lib/widgets/generalInfo.widget.ts @@ -0,0 +1,12 @@ +import { registerWidget } from '../widgetRegistry.svelte'; +import GeneralInfoWidget from '../../components/GeneralInfoWidget.svelte'; + +registerWidget({ + id: 'core-general-info', + name: 'General Information', + component: GeneralInfoWidget, + integration: 'bolt', + type: 'summary', + colSpan: 2, + priority: 10, +}); diff --git a/frontend/src/lib/widgets/index.ts b/frontend/src/lib/widgets/index.ts new file mode 100644 index 00000000..3677cab1 --- /dev/null +++ b/frontend/src/lib/widgets/index.ts @@ -0,0 +1,8 @@ +// Core widgets +import './generalInfo.widget'; +import './latestActions.widget'; + +// Integration-dependent widgets +import './puppetRuns.widget'; +import './monitoringSummary.widget'; +import './consoleAccess.widget'; diff --git a/frontend/src/lib/widgets/latestActions.widget.ts b/frontend/src/lib/widgets/latestActions.widget.ts new file mode 100644 index 00000000..4fd2279a --- /dev/null +++ b/frontend/src/lib/widgets/latestActions.widget.ts @@ -0,0 +1,12 @@ +import { registerWidget } from '../widgetRegistry.svelte'; +import LatestActionsWidget from '../../components/LatestActionsWidget.svelte'; + +registerWidget({ + id: 'core-latest-actions', + name: 'Latest Actions', + component: LatestActionsWidget, + integration: 'bolt', + type: 'list', + colSpan: 2, + priority: 20, +}); diff --git a/frontend/src/lib/widgets/monitoringSummary.widget.ts b/frontend/src/lib/widgets/monitoringSummary.widget.ts new file mode 100644 index 00000000..be5afcd4 --- /dev/null +++ b/frontend/src/lib/widgets/monitoringSummary.widget.ts @@ -0,0 +1,12 @@ +import { registerWidget } from '../widgetRegistry.svelte'; +import MonitoringSummaryWidget from '../../components/MonitoringSummaryWidget.svelte'; + +registerWidget({ + id: 'checkmk-monitoring-summary', + name: 'Monitoring Summary', + component: MonitoringSummaryWidget, + integration: 'checkmk', + type: 'summary', + colSpan: 2, + priority: 100, +}); diff --git a/frontend/src/lib/widgets/puppetRuns.widget.ts b/frontend/src/lib/widgets/puppetRuns.widget.ts new file mode 100644 index 00000000..cefec844 --- /dev/null +++ b/frontend/src/lib/widgets/puppetRuns.widget.ts @@ -0,0 +1,12 @@ +import { registerWidget } from '../widgetRegistry.svelte'; +import PuppetRunsWidget from '../../components/PuppetRunsWidget.svelte'; + +registerWidget({ + id: 'puppetdb-latest-runs', + name: 'Latest Puppet Runs', + component: PuppetRunsWidget, + integration: 'puppetdb', + type: 'list', + colSpan: 3, + priority: 100, +}); diff --git a/frontend/src/novnc.d.ts b/frontend/src/novnc.d.ts new file mode 100644 index 00000000..8b37e551 --- /dev/null +++ b/frontend/src/novnc.d.ts @@ -0,0 +1,21 @@ +declare module '@novnc/novnc' { + interface RFBOptions { + shared?: boolean; + credentials?: { password?: string }; + wsProtocols?: string[]; + } + + export default class RFB extends EventTarget { + constructor(target: HTMLElement, url: string | URL, options?: RFBOptions); + disconnect(): void; + sendCredentials(credentials: { password: string }): void; + get viewOnly(): boolean; + set viewOnly(value: boolean); + get scaleViewport(): boolean; + set scaleViewport(value: boolean); + get resizeSession(): boolean; + set resizeSession(value: boolean); + get clipViewport(): boolean; + set clipViewport(value: boolean); + } +} diff --git a/frontend/src/pages/NodeDetailPage.svelte b/frontend/src/pages/NodeDetailPage.svelte index 1cbc7d84..56492ce7 100644 --- a/frontend/src/pages/NodeDetailPage.svelte +++ b/frontend/src/pages/NodeDetailPage.svelte @@ -1,6 +1,8 @@ + +
This should not be visible
diff --git a/frontend/src/components/__tests__/MockNeverReadyWidget.svelte b/frontend/src/components/__tests__/MockNeverReadyWidget.svelte new file mode 100644 index 00000000..861684fd --- /dev/null +++ b/frontend/src/components/__tests__/MockNeverReadyWidget.svelte @@ -0,0 +1,12 @@ + + +
Loading forever...
diff --git a/frontend/src/components/__tests__/MockReadyWidget.svelte b/frontend/src/components/__tests__/MockReadyWidget.svelte new file mode 100644 index 00000000..057a5840 --- /dev/null +++ b/frontend/src/components/__tests__/MockReadyWidget.svelte @@ -0,0 +1,17 @@ + + +
Widget loaded for {nodeId}
diff --git a/frontend/src/lib/widgetRegistry.property.test.ts b/frontend/src/lib/widgetRegistry.property.test.ts new file mode 100644 index 00000000..a0e503a0 --- /dev/null +++ b/frontend/src/lib/widgetRegistry.property.test.ts @@ -0,0 +1,288 @@ +/** + * Property-based tests for widgetRegistry.svelte.ts + * + * Uses fast-check to verify universal invariants of the widget registry, + * integration filtering, and priority sorting. + * + * Validates: Requirements 1.1, 1.2, 1.3, 2.2, 2.4, 3.2, 3.3 + */ + +import { describe, it, expect, beforeEach } from 'vitest'; +import fc from 'fast-check'; +import type { Component } from 'svelte'; +import { + registerWidget, + getWidgets, + _resetForTesting, + filterWidgetsByStatus, + stableSortByPriority, +} from './widgetRegistry.svelte'; +import type { WidgetDefinition, WidgetType, IntegrationStatusEntry } from './widgetRegistry.svelte'; + +// Stub component for property tests (never rendered) +const stubComponent = {} as Component; + +// --- Generators --- + +const widgetTypeArb: fc.Arbitrary = fc.constantFrom('action', 'list', 'summary'); + +const integrationNameArb: fc.Arbitrary = fc.stringMatching(/^[a-z]{1,12}$/); + +const widgetIdArb: fc.Arbitrary = fc.stringMatching(/^[a-z0-9-]{1,20}$/); + +function widgetDefinitionArb(): fc.Arbitrary { + return fc.record({ + id: widgetIdArb, + name: fc.string({ minLength: 1, maxLength: 30 }), + component: fc.constant(stubComponent), + integration: integrationNameArb, + type: widgetTypeArb, + colSpan: fc.integer({ min: -10, max: 10 }), + priority: fc.integer({ min: -1000, max: 1000 }), + }); +} + +function validWidgetDefinitionArb(): fc.Arbitrary { + return fc.record({ + id: widgetIdArb, + name: fc.string({ minLength: 1, maxLength: 30 }), + component: fc.constant(stubComponent), + integration: integrationNameArb, + type: widgetTypeArb, + colSpan: fc.integer({ min: 1, max: 3 }), + priority: fc.integer({ min: 0, max: 1000 }), + }); +} + +const integrationStatusArb: fc.Arbitrary = fc.record({ + name: integrationNameArb, + status: fc.constantFrom('connected', 'degraded', 'not_configured', 'error', 'disconnected'), + type: fc.constantFrom('execution', 'information', 'both'), +}); + +// --- Tests --- + +describe('widgetRegistry property tests', () => { + beforeEach(() => { + _resetForTesting(); + }); + + /** + * Property 1: Registration preserves widget definitions + * + * For any valid WidgetDefinition, registering it and querying the registry + * SHALL return a definition with all original fields preserved (except colSpan + * which may be clamped). + * + * **Validates: Requirements 1.1, 1.2** + */ + describe('Property 1: Registration preserves widget definitions', () => { + it('all fields except colSpan are preserved after registration', () => { + fc.assert( + fc.property(widgetDefinitionArb(), (def) => { + _resetForTesting(); + registerWidget(def); + const stored = getWidgets(); + expect(stored).toHaveLength(1); + + const result = stored[0]; + expect(result.id).toBe(def.id); + expect(result.name).toBe(def.name); + // Component reference equality checked via toStrictEqual due to Svelte reactivity proxy + expect(result.component).toStrictEqual(def.component); + expect(result.integration).toBe(def.integration); + expect(result.type).toBe(def.type); + expect(result.priority).toBe(def.priority); + }), + { numRuns: 200 }, + ); + }); + + it('multiple registrations are all preserved in order', () => { + fc.assert( + fc.property(fc.array(widgetDefinitionArb(), { minLength: 1, maxLength: 20 }), (defs) => { + _resetForTesting(); + for (const def of defs) { + registerWidget(def); + } + const stored = getWidgets(); + expect(stored).toHaveLength(defs.length); + + for (let i = 0; i < defs.length; i++) { + expect(stored[i].id).toBe(defs[i].id); + expect(stored[i].integration).toBe(defs[i].integration); + expect(stored[i].type).toBe(defs[i].type); + expect(stored[i].priority).toBe(defs[i].priority); + } + }), + { numRuns: 100 }, + ); + }); + }); + + /** + * Property 2: Column span clamping + * + * For any integer value provided as colSpan during registration, the stored + * colSpan SHALL equal `Math.max(1, Math.min(3, Math.round(value)))`. + * + * **Validates: Requirements 1.3** + */ + describe('Property 2: Column span clamping', () => { + it('stored colSpan equals Math.max(1, Math.min(3, Math.round(value)))', () => { + fc.assert( + fc.property( + widgetDefinitionArb(), + fc.integer({ min: -100, max: 100 }), + (def, rawColSpan) => { + _resetForTesting(); + const input = { ...def, colSpan: rawColSpan }; + registerWidget(input); + const stored = getWidgets()[0]; + const expected = Math.max(1, Math.min(3, Math.round(rawColSpan))); + expect(stored.colSpan).toBe(expected); + }, + ), + { numRuns: 300 }, + ); + }); + + it('colSpan is always in [1, 3] regardless of input', () => { + fc.assert( + fc.property(widgetDefinitionArb(), (def) => { + _resetForTesting(); + registerWidget(def); + const stored = getWidgets()[0]; + expect(stored.colSpan).toBeGreaterThanOrEqual(1); + expect(stored.colSpan).toBeLessThanOrEqual(3); + }), + { numRuns: 200 }, + ); + }); + }); + + /** + * Property 3: Integration filtering + * + * For any set of registered WidgetDefinitions and any integration status + * response, the visible widget set SHALL contain exactly those widgets whose + * integration name appears in the status response with status "connected" or + * "degraded". + * + * **Validates: Requirements 2.2, 2.4** + */ + describe('Property 3: Integration filtering', () => { + it('returns exactly widgets whose integration is connected or degraded', () => { + fc.assert( + fc.property( + fc.array(validWidgetDefinitionArb(), { minLength: 0, maxLength: 15 }), + fc.array(integrationStatusArb, { minLength: 0, maxLength: 10 }), + (widgets, integrations) => { + const enabledNames = new Set( + integrations + .filter((i) => i.status === 'connected' || i.status === 'degraded') + .map((i) => i.name), + ); + + const result = filterWidgetsByStatus(widgets, integrations); + + // Every result widget has an enabled integration + for (const w of result) { + expect(enabledNames.has(w.integration)).toBe(true); + } + + // Every widget with an enabled integration is in the result + const expectedWidgets = widgets.filter((w) => enabledNames.has(w.integration)); + expect(result).toHaveLength(expectedWidgets.length); + + // Preserves order from input + for (let i = 0; i < result.length; i++) { + expect(result[i]).toBe(expectedWidgets[i]); + } + }, + ), + { numRuns: 200 }, + ); + }); + + it('widgets with integration names absent from status are excluded', () => { + fc.assert( + fc.property( + fc.array(validWidgetDefinitionArb(), { minLength: 1, maxLength: 10 }), + (widgets) => { + // Empty integration status → all widgets excluded + const result = filterWidgetsByStatus(widgets, []); + expect(result).toHaveLength(0); + }, + ), + { numRuns: 100 }, + ); + }); + }); + + /** + * Property 4: Stable priority ordering + * + * For any set of widgets, the rendered sequence SHALL be sorted by ascending + * priority weight, and widgets with equal priority weight SHALL appear in their + * original registration order (stable sort). + * + * **Validates: Requirements 3.2, 3.3** + */ + describe('Property 4: Stable priority ordering', () => { + it('output is sorted by ascending priority', () => { + fc.assert( + fc.property( + fc.array(validWidgetDefinitionArb(), { minLength: 0, maxLength: 20 }), + (widgets) => { + const sorted = stableSortByPriority(widgets); + for (let i = 1; i < sorted.length; i++) { + expect(sorted[i].priority).toBeGreaterThanOrEqual(sorted[i - 1].priority); + } + }, + ), + { numRuns: 200 }, + ); + }); + + it('widgets with equal priority preserve original order (stable sort)', () => { + fc.assert( + fc.property( + fc.integer({ min: -100, max: 100 }), + fc.array(validWidgetDefinitionArb(), { minLength: 2, maxLength: 15 }), + (samePriority, widgets) => { + // Give all widgets the same priority to test stability + const samePriorityWidgets = widgets.map((w, i) => ({ + ...w, + priority: samePriority, + id: `widget-${i}`, + })); + + const sorted = stableSortByPriority(samePriorityWidgets); + + // All same priority → original order preserved + expect(sorted).toHaveLength(samePriorityWidgets.length); + for (let i = 0; i < sorted.length; i++) { + expect(sorted[i].id).toBe(samePriorityWidgets[i].id); + } + }, + ), + { numRuns: 200 }, + ); + }); + + it('does not mutate the input array', () => { + fc.assert( + fc.property( + fc.array(validWidgetDefinitionArb(), { minLength: 1, maxLength: 10 }), + (widgets) => { + const original = [...widgets]; + stableSortByPriority(widgets); + expect(widgets).toEqual(original); + }, + ), + { numRuns: 100 }, + ); + }); + }); +}); From 72fcf8faf029d198e11be99a085e48dba2fc1988 Mon Sep 17 00:00:00 2001 From: Alessandro Franceschi Date: Thu, 18 Jun 2026 18:20:19 +0200 Subject: [PATCH 07/13] feat(frontend): add Puppet Agent Actions widget and improve UI integration - Add new PuppetAgentActionsWidget component for managing Puppet agent operations - Implement puppetAgentActions widget with registry integration - Update security middleware to exclude non-credential auth endpoints from rate limiting (GET /providers, POST /refresh, POST /logout, GET /callback) - Enhance ConsoleAccessWidget with expandable state and integration badges - Expand GeneralInfoWidget with comprehensive system information display (CPU, memory, disk, network interfaces) - Update LatestActionsWidget with enhanced filtering and pagination - Refactor PuppetRunsWidget to support new data structures - Improve Navigation component with updated styling and route handling - Add PUBLIC_PATHS set to App.svelte for conditional navigation shell rendering - Update widget registry with new puppet agent actions widget - Ensure authenticated users only see navigation and footer on protected route --- backend/src/middleware/securityMiddleware.ts | 17 +- frontend/src/App.svelte | 8 +- .../src/components/ConsoleAccessWidget.svelte | 48 +- .../src/components/GeneralInfoWidget.svelte | 449 +++++++++++++----- .../src/components/LatestActionsWidget.svelte | 4 +- frontend/src/components/Navigation.svelte | 2 +- .../PuppetAgentActionsWidget.svelte | 165 +++++++ frontend/src/components/WidgetFrame.svelte | 3 +- .../src/lib/widgetRegistry.property.test.ts | 10 +- frontend/src/lib/widgetRegistry.svelte.ts | 6 +- frontend/src/lib/widgets/index.ts | 1 + .../lib/widgets/puppetAgentActions.widget.ts | 12 + frontend/src/lib/widgets/puppetRuns.widget.ts | 2 +- 13 files changed, 586 insertions(+), 141 deletions(-) create mode 100644 frontend/src/components/PuppetAgentActionsWidget.svelte create mode 100644 frontend/src/lib/widgets/puppetAgentActions.widget.ts diff --git a/backend/src/middleware/securityMiddleware.ts b/backend/src/middleware/securityMiddleware.ts index 6d872db8..fc324951 100644 --- a/backend/src/middleware/securityMiddleware.ts +++ b/backend/src/middleware/securityMiddleware.ts @@ -104,7 +104,22 @@ export function createAuthRateLimitMiddleware(): (req: Request, res: Response, n // Use IP address as the key with proper IPv6 handling keyGenerator: (req: Request): string => ipKeyGenerator(req.ip ?? req.socket.remoteAddress ?? ""), - // Custom handler for rate limit exceeded + // Skip rate limiting for non-credential endpoints that happen to live + // under /api/auth. These are either read-only discovery endpoints or + // authenticated operations that are not brute-force targets. + skip: (req: Request): boolean => { + // GET /api/auth/providers — public discovery, not an auth attempt + if (req.method === "GET" && req.path === "/providers") return true; + // POST /api/auth/refresh — token refresh, not a credential submission + if (req.method === "POST" && req.path === "/refresh") return true; + // POST /api/auth/logout — requires existing auth, not an attempt + if (req.method === "POST" && req.path === "/logout") return true; + // GET /api/auth/entra-id/callback — automated OAuth callback from provider + if (req.method === "GET" && req.path === "/callback") return true; + return false; + }, + + // Custom handler for auth rate limit exceeded handler: (_req: Request, res: Response): void => { res.status(429).json({ error: "Too many authentication attempts", diff --git a/frontend/src/App.svelte b/frontend/src/App.svelte index 676cd6d0..58370089 100644 --- a/frontend/src/App.svelte +++ b/frontend/src/App.svelte @@ -23,10 +23,14 @@ import CrashDumpsPage from './pages/CrashDumpsPage.svelte'; import LogsPage from './pages/LogsPage.svelte'; import { router } from './lib/router.svelte'; + import { authManager } from './lib/auth.svelte'; import type { RouteConfig } from './lib/router.svelte'; import { get } from './lib/api'; import { onMount } from 'svelte'; + // Public pages that should render without the navigation shell + const PUBLIC_PATHS = new Set(['/login', '/register', '/setup']); + const routes: Record = { '/': { component: HomePage, requiresAuth: true }, '/login': LoginPage, @@ -98,14 +102,14 @@ {:else}
- {#if setupComplete} + {#if setupComplete && authManager.isAuthenticated && !PUBLIC_PATHS.has(router.currentPath)} {/if}
- {#if setupComplete} + {#if setupComplete && authManager.isAuthenticated && !PUBLIC_PATHS.has(router.currentPath)}