go first commit

2025-12-17 22:57:57 +01:00
parent e5a4de7aab
commit 7749ebfd08
22 changed files with 1044 additions and 0 deletions
--- a/go_cloud/README.md
+++ b/go_cloud/README.md
@@ -0,0 +1,113 @@
+# Go Backend Control Plane
+
+This is the Go backend for the enterprise document collaboration platform, serving as the single source of truth for authentication, organizations, permissions, sessions, and orchestration.
+
+## Architecture
+
+The backend is designed for security, scale, auditability, and SaaS readiness. It uses OIDC authentication via Nextcloud and enforces organization-scoped permissions.
+
+### Core Principles
+- **Single Source of Truth**: All auth, orgs, permissions, and sessions are managed here.
+- **Untrusted Frontend**: The backend does not trust client-side permissions.
+- **Organization Scoping**: Every API request is org-scoped.
+- **Audit Logging**: All sensitive actions are logged.
+
+### Key Components
+- **Authentication**: OIDC via Nextcloud
+- **Sessions**: Short-lived JWTs (5-15 minutes)
+- **Organizations**: Multi-org support with role-based permissions
+- **File Mediation**: Talks to Nextcloud via WebDAV/APIs, no direct client access
+- **Document Sessions**: Generates signed URLs for viewers and editors (Collabora)
+
+### Tech Stack
+- **Language**: Go 1.22+
+- **Framework**: Chi router
+- **Database**: PostgreSQL 16
+- **JWT**: golang-jwt/jwt/v4
+- **Deployment**: Ready for containerization
+
+## Project Structure
+```
+.
+├── cmd/api/main.go          # Application entry point
+├── internal/
+│   ├── auth/                # OIDC authentication logic
+│   ├── session/             # Session management
+│   ├── org/                 # Organization resolution
+│   ├── permission/          # Permission checking
+│   ├── files/               # File access mediation
+│   ├── documents/           # Document session generation
+│   ├── collabora/           # Collabora editor integration
+│   ├── audit/               # Audit logging
+│   ├── middleware/          # HTTP middleware (auth, org, rate limit)
+│   ├── config/              # Configuration loading
+│   ├── database/            # DB connections and migrations
+│   └── http/                # HTTP server and routes
+├── pkg/jwt/                 # JWT utilities
+├── migrations/              # Database migrations
+├── scripts/                 # Utility scripts
+├── .env.example             # Environment variables template
+├── Makefile                 # Build and deployment tasks
+└── README.md
+```
+
+## Getting Started
+
+1. **Initialize**:
+   ```bash
+   go mod init go.b0esche.cloud/backend
+   go mod tidy
+   ```
+
+2. **Set up PostgreSQL**:
+   - Install PostgreSQL 16
+   - Create a database
+   - Run migrations:
+     ```bash
+     psql -d your_database < migrations/0001_initial.sql
+     ```
+
+3. **Configure Environment**:
+   Copy `.env.example` to `.env` and fill in values, especially database URL and OIDC settings.
+
+4. **Run**:
+   ```bash
+   go run cmd/api/main.go
+   ```
+
+5. **Health Check**:
+   ```bash
+   curl http://localhost:8080/health
+   ```
+
+## API Endpoints
+
+- `GET /health` - Health check
+- `GET /auth/login` - Initiate OIDC login (redirects to Nextcloud)
+- `GET /auth/callback` - OIDC callback (returns JWT token)
+
+## Development
+
+- Use Go 1.22+
+- Follow Go conventions
+- Add tests for critical components
+- Use structured logging
+- No global mutable state
+- No business logic in handlers
+
+## Security
+
+- All handlers must go through middleware chain
+- JWTs are short-lived
+- Permissions resolved server-side only
+- Audit all sensitive actions
+- Rate limiting implemented
+- No direct DB access from handlers
+
+## Roadmap
+
+1. Complete OIDC implementation
+2. Add database integration
+3. Implement org and permission resolution
+4. Add file access APIs
+5. Integrate with Nextcloud and Collabora