FM / docs

/home/techb158/balavpn.abdallabala.com/docs/

/home/techb158/balavpn.abdallabala.com/docs

Name	Size	Mode	Actions
00-design-study.md	3678	0644	edit dl rm
01-uml-class-diagram.puml	11869	0644	edit dl rm
02-use-case-diagram.puml	3763	0644	edit dl rm
03-sequence-diagrams.puml	9732	0644	edit dl rm
04-database-entity-model.mmd	7051	0644	edit dl rm
05-database-schema.sql	13372	0644	edit dl rm
06-diagram-preview.html	5021	0644	edit dl rm
07-design-checklist.md	3256	0644	edit dl rm
08-step-2-storage-layer.md	5325	0644	edit dl rm
09-step-3-risk-crud-ui.md	3380	0644	edit dl rm
10-step-4-mitigation-workflow.md	3996	0644	edit dl rm
11-step-5-deployment-gate-workflow.md	2292	0644	edit dl rm
12-step-6-multi-pm-integration.md	3770	0644	edit dl rm
13-step-6-1-microsoft-planner-integration.md	2335	0644	edit dl rm
14-step-7-reporting-export.md	4158	0644	edit dl rm
15-step-7-1-oauth-live-connectors.md	4545	0644	edit dl rm
16-step-8-user-roles-access-control.md	3297	0644	edit dl rm
17-step-9-production-deployment-security.md	4228	0644	edit dl rm
18-step-10-final-academic-submission.md	3199	0644	edit dl rm
19-final-report-draft.md	6814	0644	edit dl rm
20-instructor-submission-checklist.md	3639	0644	edit dl rm
21-demo-script.md	3948	0644	edit dl rm
22-traceability-matrix.md	4847	0644	edit dl rm
23-testing-evidence.md	2961	0644	edit dl rm
24-evaluation-rubric-mapping.md	2910	0644	edit dl rm
25-final-deployment-runbook.md	3214	0644	edit dl rm
26-known-limitations-and-future-work.md	2632	0644	edit dl rm
27-final-qa-checklist.md	2893	0644	edit dl rm
28-demo-rehearsal-script.md	3618	0644	edit dl rm
29-submission-freeze-report.md	2769	0644	edit dl rm
30-final-known-issues.md	1876	0644	edit dl rm
31-saas-rebuild-implementation.md	2571	0644	edit dl rm
application-documentation.md	27515	0644	edit dl rm
conversation-log.md	18503	0644	edit dl rm
dashboard-spec.md	3691	0644	edit dl rm
database-guide.md	37826	0644	edit dl rm
development-summary.md	7070	0644	edit dl rm
github-architecture.svg	6288	0644	edit dl rm

Edit: /home/techb158/balavpn.abdallabala.com/docs/17-step-9-production-deployment-security.md (4228B)

# Step 9, Production Deployment and Security Hardening

## Purpose

Step 9 prepares the COSMIC AI-Risk Dashboard for controlled deployment on a server. This step does not change the risk model. It adds operational controls around the existing dashboard, API, OAuth connectors, reporting module, and role-based access control.

## Source alignment

The project source positions COSMIC-Risk as a software prototype and REST API for automated, reproducible AI risk analysis and project-management integration. The production layer is an implementation extension needed to operate that prototype safely.

## Scope

| Area | Implementation |
|---|---|
| Runtime configuration | Central `runtimeConfig` module using environment variables |
| Security headers | CSP, no-sniff, referrer policy, permissions policy, frame policy, optional HSTS |
| HTTPS support | Reverse-proxy aware HTTPS enforcement |
| CORS control | Explicit origin allowlist through environment variables |
| Readiness checks | `/api/ready` validates config, database access, and backup directory |
| Security status | `/api/operations/security` exposes safe configuration summary |
| Backups | Backup API and CLI script create database copy with SHA-256 manifest |
| Deployment files | Dockerfile, docker-compose, Nginx example, systemd service |
| Production scripts | Config check and backup scripts |
| Tests | Production hardening test suite |

## New API endpoints

| Method | Endpoint | Permission | Purpose |
|---|---|---|---|
| GET | `/api/ready` | public | Readiness probe for deployment monitoring |
| GET | `/api/operations/security` | `audit:read` | Review safe security configuration status |
| GET | `/api/operations/backups` | `audit:read` | List backup manifests |
| POST | `/api/operations/backups` | `user:write` | Create a database backup |

## New environment variables

| Variable | Default | Purpose |
|---|---|---|
| `NODE_ENV` | `development` | Runtime mode |
| `COSMIC_SECURITY_HEADERS_ENABLED` | `true` | Enable security response headers |
| `COSMIC_FORCE_HTTPS` | `false` in local `.env.example` | Redirect GET/HEAD traffic to HTTPS when enabled |
| `COSMIC_TRUST_PROXY` | `false` in local `.env.example` | Trust `X-Forwarded-Proto` behind Nginx or another reverse proxy |
| `COSMIC_HSTS_ENABLED` | `false` in local `.env.example` | Add HSTS when request is HTTPS |
| `COSMIC_ALLOWED_ORIGINS` | empty | Comma-separated CORS allowlist |
| `COSMIC_FRAME_ANCESTORS` | `'self'` | CSP frame ancestor list |
| `COSMIC_MAX_BODY_BYTES` | `1048576` | API JSON body limit |
| `COSMIC_BACKUP_DIR` | `./backups` | Backup output directory |
| `COSMIC_BACKUP_RETENTION` | `10` | Number of backups retained |
| `COSMIC_REQUEST_LOG_ENABLED` | `false` | Structured request logging |

## Production commands

```bash
npm run check:config
npm test
npm run backup
NODE_ENV=production npm start
```

## Docker deployment

```bash
cp .env.example .env
# edit .env with production values
mkdir -p data backups
docker compose up --build -d
curl http://localhost:8090/api/ready
```

## Nginx deployment

Use `deploy/nginx.conf` as a starting point. In production, terminate TLS at Nginx and set:

```env
NODE_ENV=production
COSMIC_TRUST_PROXY=true
COSMIC_FORCE_HTTPS=true
COSMIC_HSTS_ENABLED=true
COSMIC_PUBLIC_BASE_URL=https://your-domain.example
```

## Backup behavior

The backup module copies the JSON database to the backup directory and creates a manifest file containing:

- backup ID
- actor user ID
- source file
- backup file path
- creation timestamp
- file size
- SHA-256 digest

The backup keeps OAuth token ciphertext as stored in the database. The backup directory must therefore be protected like a production secret store.

## Acceptance criteria

| Check | Expected result |
|---|---|
| `/api/health` | Returns service version `2.0.0` |
| `/api/ready` | Returns `ok: true` when database and backup directory are available |
| Security headers | API and static responses include CSP, no-sniff, referrer policy, and permissions policy |
| Backup script | `npm run backup` creates JSON backup and manifest |
| Config script | `npm run check:config` prints safe runtime summary |
| Tests | `npm test` passes including production hardening tests |

# Step 9, Production Deployment and Security Hardening ## Purpose Step 9 prepares the COSMIC AI-Risk Dashboard for controlled deployment on a server. This step does not change the risk model. It adds operational controls around the existing dashboard, API, OAuth connectors, reporting module, and role-based access control. ## Source alignment The project source positions COSMIC-Risk as a software prototype and REST API for automated, reproducible AI risk analysis and project-management integration. The production layer is an implementation extension needed to operate that prototype safely. ## Scope | Area | Implementation | |---|---| | Runtime configuration | Central `runtimeConfig` module using environment variables | | Security headers | CSP, no-sniff, referrer policy, permissions policy, frame policy, optional HSTS | | HTTPS support | Reverse-proxy aware HTTPS enforcement | | CORS control | Explicit origin allowlist through environment variables | | Readiness checks | `/api/ready` validates config, database access, and backup directory | | Security status | `/api/operations/security` exposes safe configuration summary | | Backups | Backup API and CLI script create database copy with SHA-256 manifest | | Deployment files | Dockerfile, docker-compose, Nginx example, systemd service | | Production scripts | Config check and backup scripts | | Tests | Production hardening test suite | ## New API endpoints | Method | Endpoint | Permission | Purpose | |---|---|---|---| | GET | `/api/ready` | public | Readiness probe for deployment monitoring | | GET | `/api/operations/security` | `audit:read` | Review safe security configuration status | | GET | `/api/operations/backups` | `audit:read` | List backup manifests | | POST | `/api/operations/backups` | `user:write` | Create a database backup | ## New environment variables | Variable | Default | Purpose | |---|---|---| | `NODE_ENV` | `development` | Runtime mode | | `COSMIC_SECURITY_HEADERS_ENABLED` | `true` | Enable security response headers | | `COSMIC_FORCE_HTTPS` | `false` in local `.env.example` | Redirect GET/HEAD traffic to HTTPS when enabled | | `COSMIC_TRUST_PROXY` | `false` in local `.env.example` | Trust `X-Forwarded-Proto` behind Nginx or another reverse proxy | | `COSMIC_HSTS_ENABLED` | `false` in local `.env.example` | Add HSTS when request is HTTPS | | `COSMIC_ALLOWED_ORIGINS` | empty | Comma-separated CORS allowlist | | `COSMIC_FRAME_ANCESTORS` | `'self'` | CSP frame ancestor list | | `COSMIC_MAX_BODY_BYTES` | `1048576` | API JSON body limit | | `COSMIC_BACKUP_DIR` | `./backups` | Backup output directory | | `COSMIC_BACKUP_RETENTION` | `10` | Number of backups retained | | `COSMIC_REQUEST_LOG_ENABLED` | `false` | Structured request logging | ## Production commands ```bash npm run check:config npm test npm run backup NODE_ENV=production npm start ``` ## Docker deployment ```bash cp .env.example .env # edit .env with production values mkdir -p data backups docker compose up --build -d curl http://localhost:8090/api/ready ``` ## Nginx deployment Use `deploy/nginx.conf` as a starting point. In production, terminate TLS at Nginx and set: ```env NODE_ENV=production COSMIC_TRUST_PROXY=true COSMIC_FORCE_HTTPS=true COSMIC_HSTS_ENABLED=true COSMIC_PUBLIC_BASE_URL=https://your-domain.example ``` ## Backup behavior The backup module copies the JSON database to the backup directory and creates a manifest file containing: - backup ID - actor user ID - source file - backup file path - creation timestamp - file size - SHA-256 digest The backup keeps OAuth token ciphertext as stored in the database. The backup directory must therefore be protected like a production secret store. ## Acceptance criteria | Check | Expected result | |---|---| | `/api/health` | Returns service version `2.0.0` | | `/api/ready` | Returns `ok: true` when database and backup directory are available | | Security headers | API and static responses include CSP, no-sniff, referrer policy, and permissions policy | | Backup script | `npm run backup` creates JSON backup and manifest | | Config script | `npm run check:config` prints safe runtime summary | | Tests | `npm test` passes including production hardening tests |