Compare commits

..

No commits in common. "main" and "main" have entirely different histories.
main ... main

14 changed files with 33 additions and 858 deletions

1
.gitignore vendored
View File

@ -6,7 +6,6 @@ build/
!gradle/wrapper/gradle-wrapper.jar
!**/src/main/**/build/
!**/src/test/**/build/
CFTunnels/
### STS ###
.apt_generated

186
README.md
View File

@ -1,186 +0,0 @@
# CFTunnels - Cloudflare Tunnels Management API
> **Note**: All pull requests should be raised against the `test` branch.
A Spring Boot REST API for managing Cloudflare Tunnels with ingress mappings and an approval workflow.
## Overview
CFTunnels provides a programmatic way to manage Cloudflare Tunnel configurations, allowing teams to:
- View and manage Cloudflare Tunnels
- Add, modify, and delete ingress mappings
- Request mapping changes through an approval workflow
- Track tunnel configurations locally
## Features
- **Tunnel Management**: Create, update, and delete Cloudflare tunnels
- **Ingress Mappings**: Add custom ingress rules to tunnel configurations
- **Approval Workflow**: Request/approve/reject mapping changes
- **Security**: OIDC-based authentication with role-based access
- **API Documentation**: OpenAPI/Swagger documentation
## Technology Stack
- Java 17
- Spring Boot 3.x
- Spring Data JPA
- Spring Security with OIDC
- H2 Database (configurable for PostgreSQL)
- Cloudflare API v4
## Prerequisites
- Java 17 or higher
- Cloudflare account with API key
- OIDC provider (e.g., Google, Okta, Auth0)
## Configuration
Copy `.env.example` to `.env` and configure:
```bash
cp .env.example .env
```
### Required Environment Variables
| Variable | Description |
|---------|-------------|
| `CLOUDFLARE_ACCOUNT_ID` | Cloudflare Account ID |
| `CLOUDFLARE_API_KEY` | Cloudflare API Key |
| `CLOUDFLARE_EMAIL` | Cloudflare account email |
| `SPRING_PROFILES_ACTIVE` | Environment (local, dev, prod) |
### Security Configuration
OIDC settings in `application.properties`:
```properties
spring.security.oauth2.client.registration.<provider>.client-id=your-client-id
spring.security.oauth2.client.registration.<provider>.client-secret=your-client-secret
spring.security.oauth2.client.provider.<provider>.issuer-uri=https://your-oidc-provider
```
## Running Locally
### Using Gradle
```bash
./gradlew bootRun
```
### Using Docker
```bash
docker-compose up --build
```
The API will be available at `http://localhost:8080`
## API Documentation
Once running, access:
- **Swagger UI**: `http://localhost:8080/swagger-ui.html`
- **OpenAPI JSON**: `http://localhost:8080/v3/api-docs`
## API Endpoints
### Base URL: `/cloudflare`
| Method | Endpoint | Description | Required Role |
|--------|----------|-------------|---------------|
| GET | `/whoami` | Get current user info | USER |
| GET | `/tunnels` | List all Cloudflare tunnels | USER |
| GET | `/configured/tunnels` | List locally configured tunnels | USER |
| GET | `/requests` | List all mapping requests | USER |
| GET | `/tunnels/{tunnelId}/mappings` | Get tunnel configuration | DEVELOPER |
| POST | `/tunnels/{tunnelId}/mappings` | Add ingress mapping | ADMIN |
| DELETE | `/tunnels/{tunnelId}/mappings` | Delete ingress mapping | DEVELOPER |
| POST | `/tunnels/configure/{tunnelId}/requests` | Create mapping request | DEVELOPER |
| PUT | `/requests/{requestId}/approve` | Approve mapping request | APPROVER |
| PUT | `/requests/{requestId}/reject` | Reject mapping request | APPROVER |
| PUT | `/tunnels/configure/{tunnelId}` | Configure tunnel for environment | ADMIN |
## Role-Based Access
| Role | Permissions |
|------|-------------|
| USER | View tunnels and requests |
| DEVELOPER | Create/modify/delete mappings, create requests |
| APPROVER | Approve/reject requests |
| ADMIN | Full access including tunnel configuration |
## Example Usage
### List all tunnels
```bash
curl -H "Authorization: Bearer $TOKEN" \
http://localhost:8080/cloudflare/tunnels
```
### Add an ingress mapping
```bash
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"hostname": "api.example.com",
"service": "http://localhost:8080",
"originRequest": {"noTLSVerify": true}
}' \
http://localhost:8080/cloudflare/tunnels/{tunnelId}/mappings
```
## Project Structure
```
CFTunnels/
├── src/main/java/com/hithomelabs/CFTunnels/
│ ├── CfTunnelsApplication.java # Main application
│ ├── Config/ # Configuration classes
│ ├── Controllers/ # REST controllers
│ │ └── TunnelController.java # Main API controller
│ ├── Entity/ # JPA entities
│ │ ├── Mapping.java # Ingress mapping
│ │ ├── Protocol.java # Protocol enum
│ │ ├── Request.java # Mapping request
│ │ ├── Tunnel.java # Tunnel entity
│ │ └── User.java # User entity
│ ├── Models/ # DTOs
│ ├── Repositories/ # JPA repositories
│ └── Services/ # Business logic
│ ├── CloudflareAPIService.java # Cloudflare API
│ └── MappingRequestService.java # Request workflow
└── src/main/resources/
├── application.properties # Main config
└── schema.sql # Database schema
```
## Testing
Run tests with:
```bash
./gradlew test
```
Run integration tests:
```bash
./gradlew integrationTest
```
## License
Private - All rights reserved
## References
- [Cloudflare Tunnel Documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)
- [Cloudflare API v4](https://api.cloudflare.com/)
- [Spring Boot Documentation](https://docs.spring.io/spring-boot/docs/current/reference/)

View File

@ -45,9 +45,9 @@ repositories {
dependencies {
implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.8.5'
implementation group: 'org.springframework.boot', name:'spring-boot-starter-oauth2-client', version: '3.5.5'
implementation 'org.springframework.boot:spring-boot-starter-web'
compileOnly 'org.projectlombok:lombok:1.18.30'
annotationProcessor 'org.projectlombok:lombok:1.18.30'
implementation 'org.springframework.boot:spring-boot-starter-web'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
testImplementation 'org.springframework.security:spring-security-test'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

View File

@ -2,44 +2,10 @@ package com.hithomelabs.CFTunnels;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
/**
* Main Spring Boot application class for Cloudflare Tunnels API.
*
* <p>This application provides a RESTful API for managing Cloudflare Tunnels,
* allowing users to create tunnel mappings to services with an approval workflow.</p>
*
* <p><b>Features:</b></p>
* <ul>
* <li>Create, update, and delete Cloudflare tunnels</li>
* <li>Add ingress mappings to tunnels</li>
* <li>Request/approval workflow for mapping changes</li>
* <li>OIDC-based authentication with role-based access</li>
* </ul>
*
* <p><b>Technology Stack:</b></p>
* <ul>
* <li>Java 17</li>
* <li>Spring Boot 3.x</li>
* <li>Spring Data JPA</li>
* <li>Spring Security with OIDC</li>
* <li>H2 Database (configurable for PostgreSQL)</li>
* <li>Cloudflare API</li>
* </ul>
*
* <p>Access the API documentation at:
* {@code /swagger-ui.html} for the Swagger/OpenAPI UI</p>
*
* @see <a href="https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-negative">Cloudflare Tunnel Documentation</a>
* @since 1.0.0
*/
@SpringBootApplication
public class CfTunnelsApplication {
/**
* Main entry point for the application.
*
* @param args command line arguments passed to the application
*/
public static void main(String[] args) {
SpringApplication.run(CfTunnelsApplication.class, args);
}

View File

@ -3,47 +3,11 @@ package com.hithomelabs.CFTunnels.Config;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
/**
* Configuration class for Cloudflare API credentials.
*
* <p>Loads Cloudflare configuration from application properties
* using the {@code cloudflare.*} prefix.</p>
*
* <p><b>Example configuration in application.properties:</b></p>
* <pre>
* cloudflare.account-id=your-account-id
* cloudflare.api-key=your-api-key
* cloudflare.email=your@email.com
* </pre>
*
* @see <a href="https://api.cloudflare.com/">Cloudflare API Documentation</a>
*/
@Configuration
@ConfigurationProperties(prefix = "cloudflare")
public class CloudflareConfig {
/**
* Cloudflare account ID.
*
* <p>Found in the Cloudflare Dashboard under
* Overview > Account ID</p>
*/
private String accountId;
/**
* Cloudflare API Key.
*
* <p>Generated in Cloudflare Dashboard under
* Profile > API Tokens > Global API Key</p>
*/
private String apiKey;
/**
* Cloudflare account email.
*
* <p>The email address associated with your
* Cloudflare account.</p>
*/
private String email;
// Getters and Setters

View File

@ -22,6 +22,7 @@ import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.web.servlet.error.ErrorController;
import org.springframework.dao.DataAccessException;
import org.springframework.http.*;
import org.springframework.http.*;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
@ -35,41 +36,6 @@ import java.util.Map;
import java.util.NoSuchElementException;
import java.util.UUID;
/**
* REST Controller for managing Cloudflare Tunnels.
*
* <p>This controller provides the public API for managing Cloudflare Tunnels
* and their ingress mappings. All endpoints require authentication via OIDC
* and are protected by role-based access control.</p>
*
* <p><b>Base URL:</b> {@code /cloudflare}</p>
*
* <p><b>Authentication:</b> OIDC-based with role-based access</p>
*
* <p><b>Available Roles:</b></p>
* <ul>
* <li>USER - View tunnels and requests</li>
* <li>DEVELOPER - Create/modify/delete mappings</li>
* <li>APPROVER - Approve/reject requests</li>
* <li>ADMIN - Full tunnel configuration access</li>
* </ul>
*
* <p><b>Example Usage:</b></p>
* <pre>
* # Get all tunnels (requires USER role)
* curl -H "Authorization: Bearer &lt;token&gt;" \
* https://api.example.com/cloudflare/tunnels
*
* # Add a mapping (requires ADMIN role)
* curl -X POST -H "Authorization: Bearer &lt;token&gt;" \
* -H "Content-Type: application/json" \
* -d '{"hostname":"api.example.com","service":"http://localhost:8080"}' \
* https://api.example.com/cloudflare/tunnels/{tunnelId}/mappings
* </pre>
*
* @see CloudflareAPIService
* @see MappingRequestService
*/
@RestController
@RequestMapping("/cloudflare")
public class TunnelController implements ErrorController {
@ -97,21 +63,9 @@ public class TunnelController implements ErrorController {
@Autowired
private UserRepository userRepository;
/**
* Current environment (loaded from spring.profiles.active).
*/
@Value("${spring.profiles.active}")
private String environment;
/**
* Get current user information.
*
* <p>Returns the authenticated user's username and roles.</p>
*
* @param oidcUser The authenticated OIDC user
* @return Map containing username and roles
* @throws SecurityException if authentication fails
*/
@PreAuthorize("hasAnyRole('USER')")
@GetMapping("/whoami")
public Map<String,Object> whoAmI(@AuthenticationPrincipal OidcUser oidcUser) {
@ -125,16 +79,6 @@ public class TunnelController implements ErrorController {
);
}
/**
* Get all tunnels from Cloudflare API.
*
* <p>Fetches the complete list of tunnels from Cloudflare,
* including their status and configuration from the Cloudflare API.</p>
*
* @return Map containing list of all tunnels
* @throws SecurityException if user lacks required role
* @see <a href="https://api.cloudflare.com/#cfd_tunnel-get-tunnels">Cloudflare API</a>
*/
@PreAuthorize("hasAnyRole('USER')")
@GetMapping("/tunnels")
@Operation( security = { @SecurityRequirement(name = "oidcAuth") } )
@ -148,16 +92,6 @@ public class TunnelController implements ErrorController {
return ResponseEntity.ok(jsonResponse);
}
/**
* Get locally configured tunnels.
*
* <p>Returns the tunnels that have been configured locally
* with environment associations.</p>
*
* @return Map containing list of configured tunnels
* @throws SecurityException if user lacks required role
* @see CloudflareAPIService#getAllConfiguredTunnels()
*/
@PreAuthorize("hasAnyRole('USER')")
@GetMapping("/configured/tunnels")
public ResponseEntity<Map<String,Object>> getConfiguredTunnels(){
@ -172,14 +106,6 @@ public class TunnelController implements ErrorController {
}
}
/**
* Get all mapping requests.
*
* <p>Returns all pending, approved, and rejected mapping requests.</p>
*
* @return Map containing list of all requests
* @throws SecurityException if user lacks required role
*/
@PreAuthorize("hasAnyRole('USER')")
@GetMapping("/requests")
public ResponseEntity<Map<String,Object>> getAllRequests() {
@ -194,17 +120,6 @@ public class TunnelController implements ErrorController {
}
}
/**
* Get tunnel configuration from Cloudflare.
*
* <p>Fetches the complete configuration for a specific tunnel,
* including all ingress rules.</p>
*
* @param tunnelId The Cloudflare tunnel ID (UUID)
* @return Map containing tunnel configuration
* @throws SecurityException if user lacks required role
* @see <a href="https://api.cloudflare.com/#cfd_tunnel-get-tunnel-config">Cloudflare API</a>
*/
@PreAuthorize("hasAnyRole('DEVELOPER')")
@GetMapping("/tunnels/{tunnelId}/mappings")
public ResponseEntity<Map<String,Object>> getTunnelConfigurations(@PathVariable String tunnelId) {
@ -217,41 +132,22 @@ public class TunnelController implements ErrorController {
return ResponseEntity.ok(jsonResponse);
}
/**
* Add an ingress mapping to a tunnel.
*
* <p>Adds a new ingress rule to the tunnel configuration.
* The new rule is inserted at the second-to-last position,
* before any catch-all rule.</p>
*
* @param tunnelId The Cloudflare tunnel ID (UUID)
* @param ingress The ingress rule to add
* @return Map containing the updated configuration
* @throws SecurityException if user lacks required role
* @throws JsonProcessingException if JSON processing fails
*
* @example
* {
* "hostname": "api.example.com",
* "service": "http://localhost:8080",
* "originRequest": {"noTLSVerify": true}
* }
*/
// 50df9101-f625-4618-b7c5-100338a57124
@PreAuthorize("hasAnyRole('ADMIN')")
@PostMapping("/tunnels/{tunnelId}/mappings")
public ResponseEntity<Map<String, Object>> addTunnelconfiguration(@PathVariable String tunnelId, @RequestBody Ingress ingress) throws JsonProcessingException {
ResponseEntity<TunnelResponse> responseEntity = cloudflareAPIService.getCloudflareTunnelConfigurations(tunnelId, restTemplateConfig.restTemplate(), TunnelResponse.class);
// Inserting new ingress value at second-to last position in list
// * * Inserting new ingress value at second-to last position in list
Config config = responseEntity.getBody().getResult().getConfig();
List<Ingress> response_ingress = config.getIngress();
response_ingress.add(response_ingress.size()-1, ingress);
// Hitting put endpoint
// * * Hitting put endpoint
ResponseEntity<TunnelResponse> response = cloudflareAPIService.putCloudflareTunnelConfigurations(tunnelId, restTemplateConfig.restTemplate(), TunnelResponse.class, config);
// Displaying response
// * * Displaying response
Map<String, Object> jsonResponse = new HashMap<>();
jsonResponse.put("status", response.getStatusCode().toString());
jsonResponse.put("data", response.getBody());
@ -259,32 +155,21 @@ public class TunnelController implements ErrorController {
return ResponseEntity.ok(jsonResponse);
}
/**
* Delete an ingress mapping from a tunnel.
*
* <p>Removes an ingress rule by hostname from the tunnel configuration.</p>
*
* @param tunnelId The Cloudflare tunnel ID (UUID)
* @param ingress Ingress containing hostname to delete (only hostname field is used)
* @return Map containing the result
* @throws SecurityException if user lacks required role
* @throws JsonProcessingException if JSON processing fails
*/
@PreAuthorize("hasAnyRole('DEVELOPER')")
@DeleteMapping("/tunnels/{tunnelId}/mappings")
public ResponseEntity<Map<String, Object>> deleteTunnelConfiguration(@PathVariable String tunnelId, @RequestBody Ingress ingress) throws JsonProcessingException {
ResponseEntity<TunnelResponse> responseEntity = cloudflareAPIService.getCloudflareTunnelConfigurations(tunnelId, restTemplateConfig.restTemplate(), TunnelResponse.class);
// Deleting the selected ingress value
// * * Deleting the selected ingress value
Config config = responseEntity.getBody().getResult().getConfig();
List<Ingress> response_ingress = config.getIngress();
Boolean result = Ingress.deleteByHostName(response_ingress, ingress.getHostname());
// Hitting put endpoint
// * * Hitting put endpoint
ResponseEntity<TunnelResponse> response = cloudflareAPIService.putCloudflareTunnelConfigurations(tunnelId, restTemplateConfig.restTemplate(), TunnelResponse.class, config);
// Displaying response
// * * Displaying response
Map<String, Object> jsonResponse = new HashMap<>();
if (result){
@ -299,20 +184,6 @@ public class TunnelController implements ErrorController {
return ResponseEntity.ok(jsonResponse);
}
/**
* Create a mapping change request.
*
* <p>Creates a new request for changing tunnel ingress mappings.
* The request starts in PENDING status and must be approved
* before the changes are applied.</p>
*
* @param tunnelId The Cloudflare tunnel ID (UUID)
* @param oidcUser The authenticated user
* @param ingess The ingress configuration to request
* @return The created request with PENDING status
* @throws SecurityException if user lacks required role
* @see MappingRequestService#createMappingRequest(String, Ingress, OidcUser)
*/
@PreAuthorize("hasAnyRole('DEVELOPER')")
@PostMapping("/tunnels/configure/{tunnelId}/requests")
public ResponseEntity<Request> createTunnelMappingRequest(@PathVariable String tunnelId, @AuthenticationPrincipal OidcUser oidcUser, @RequestBody Ingress ingess){
@ -322,17 +193,6 @@ public class TunnelController implements ErrorController {
return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
}
/**
* Approve a mapping request.
*
* <p>Approves a pending mapping request. If approved, the
* mapping will be applied to the Cloudflare tunnel.</p>
*
* @param requestId The ID of the request to approve
* @param oidcUser The approver (must have APPROVER role)
* @return The updated request with APPROVED status
* @throws SecurityException if user lacks required role
*/
@PreAuthorize("hasAnyRole('APPROVER')")
@PutMapping("/requests/{requestId}/approve")
public ResponseEntity<Request> approveMappingRequest(@PathVariable UUID requestId, @AuthenticationPrincipal OidcUser oidcUser) {
@ -350,17 +210,6 @@ public class TunnelController implements ErrorController {
}
}
/**
* Reject a mapping request.
*
* <p>Rejects a pending mapping request. No changes
* will be made to the tunnel.</p>
*
* @param requestId The ID of the request to reject
* @param oidcUser The rejecter (must have APPROVER role)
* @return The updated request with REJECTED status
* @throws SecurityException if user lacks required role
*/
@PreAuthorize("hasAnyRole('APPROVER')")
@PutMapping("/requests/{requestId}/reject")
public ResponseEntity<Request> rejectMappingRequest(@PathVariable UUID requestId, @AuthenticationPrincipal OidcUser oidcUser) {
@ -378,31 +227,13 @@ public class TunnelController implements ErrorController {
}
}
/**
* Configure a tunnel for the current environment.
*
* <p>Creates a local configuration entry for a tunnel,
* associating it with the current environment (from spring.profiles.active).</p>
*
* <p><b>Response Codes:</b></p>
* <ul>
* <li>200 - Created/updated with new tunnel</li>
* <li>204 - No changes needed</li>
* <li>404 - Tunnel not found in Cloudflare</li>
* </ul>
*
* @param tunnelId The Cloudflare tunnel ID (UUID)
* @param user The authenticated user
* @return The tunnel configuration
* @throws SecurityException if user lacks required role
*/
@PreAuthorize("hasAnyRole('ADMIN')")
@PutMapping("/tunnels/configure/{tunnelId}")
public ResponseEntity<Tunnel> configureTunnelForEnvironment(@PathVariable String tunnelId, @AuthenticationPrincipal OidcUser user) {
/*
* Returns 200 if an object is created or updated with a new representation of the object
* Returns 204 if the object state did not need any changing.
* Returns 404 if the tunnelId is not valid
* * Returns 200 if an object is created or updated with a new representation of the object
* * Returns 204 if the object state did not need any changing.
* * Returns 404 if the tunnelId is not valid
*/
try {

View File

@ -6,29 +6,9 @@ import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import java.util.UUID;
/**
* JPA Entity representing an ingress mapping configuration for a Cloudflare Tunnel.
*
* <p>A mapping defines how incoming traffic should be routed through the tunnel
* to your internal services. It specifies the protocol, port, and subdomain
* where the service will be accessible.</p>
*
* <p>Database Table: {@code mappings}</p>
*
* <p><b>Example Usage:</b></p>
* <pre>
* Mapping mapping = new Mapping();
* mapping.setPort(8080);
* mapping.setProtocol(Protocol.HTTP);
* mapping.setSubdomain("api");
* </pre>
*
* @see Tunnel
* @see Protocol
* @see Request
*/
@Entity
@Getter
@Setter
@ -37,49 +17,21 @@ import java.util.UUID;
@Table(name = "mappings")
public class Mapping {
/**
* Unique identifier for this mapping (auto-generated UUID).
*/
@Id
@GeneratedValue
@Column(columnDefinition = "uuid", nullable = false, unique = true)
private UUID id;
/**
* Port number where the internal service is running.
*
* <p>Example: 8080 for a Spring Boot application's default port.</p>
*/
@Column(nullable = false)
private int port;
/**
* Protocol used for the connection.
*
* <p>Supported values: HTTP, HTTPS, TCP, SSH</p>
* @see Protocol
*/
@Enumerated(EnumType.STRING)
@Column(length = 10, nullable = false)
private Protocol protocol;
/**
* Subdomain prefix for accessing this service.
*
* <p>Example: "api" would make the service available at
* {@code api.yourdomain.com}</p>
*/
@Column(length = 50, nullable = false)
private String subdomain;
/**
* The tunnel this mapping is associated with.
*
* <p>Each mapping belongs to exactly one tunnel.
* This is a lazy-loaded relationship to optimize performance.</p>
*
* @see Tunnel
*/
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "tunnel_id", nullable = false)
private Tunnel tunnel;

View File

@ -1,43 +1,8 @@
package com.hithomelabs.CFTunnels.Entity;
/**
* Enum representing supported protocols for Cloudflare Tunnel ingress mappings.
*
* <p>Cloudflare Tunnel supports multiple protocols for routing traffic
* to your internal services. This enum defines the available options.</p>
*
* <p><b>Supported Protocols:</b></p>
* <ul>
* <li>{@link #HTTP} - Standard HTTP protocol (port 80)</li>
* <li>{@link #HTTPS} - Secure HTTP protocol (port 443)</li>
* <li>{@link #TCP} - Raw TCP connections</li>
* <li>{@link #SSH} - SSH protocol for remote access</li>
* </ul>
*
* @see Mapping
*/
public enum Protocol {
/**
* HTTP protocol for web services.
* Typically used with internal services running on port 80.
*/
HTTP,
/**
* HTTPS protocol for secure web services.
* Use this for services with TLS/SSL certificates.
*/
HTTPS,
/**
* Raw TCP protocol for non-HTTP services.
* Useful for databases, message queues, or custom protocols.
*/
TCP,
/**
* SSH protocol for secure shell access.
* Enables secure remote access to servers.
*/
SSH
}

View File

@ -8,31 +8,6 @@ import lombok.Setter;
import java.util.UUID;
/**
* JPA Entity representing a mapping change request in the approval workflow.
*
* <p>This entity tracks requests to add or modify tunnel ingress mappings.
* It implements an approval workflow where:</p>
* <ul>
* <li>Users create requests (status: PENDING)</li>
* <li>Approvers review and approve/reject (status: APPROVED/REJECTED)</li>
* </ul>
*
* <p><b>Database Table:</b> {@code requests}</p>
*
* <p><b>Workflow:</b></p>
* <pre>
* 1. User submits mapping request via REST API
* 2. Request is created with PENDING status
* 3. APPROVER role reviews the request
* 4. If approved: mapping is applied to Cloudflare tunnel
* 5. If rejected: request is marked REJECTED
* </pre>
*
* @see Mapping
* @see User
* @see RequestStatus
*/
@Entity
@Getter
@Setter
@ -41,79 +16,29 @@ import java.util.UUID;
@Table(name = "requests")
public class Request {
/**
* Unique identifier for this request (auto-generated UUID).
*/
@Id
@GeneratedValue
@Column(columnDefinition = "uuid", unique = true, nullable = false)
private UUID id;
/**
* The mapping configuration being requested.
*
* <p>This is a one-to-one relationship - each request
* contains exactly one mapping configuration.</p>
*
* @see Mapping
*/
@OneToOne
@JoinColumn(name = "mapping_id", unique = true, nullable = false)
private Mapping mapping;
/**
* User who created this request.
*
* <p>This field is required and tracks accountability.</p>
*
* @see User
*/
@ManyToOne
@JoinColumn(name = "created_by", nullable = false)
private User createdBy;
/**
* User who approved or rejected this request.
*
* <p>This is null until the request is processed.</p>
*
* @see User
*/
@ManyToOne
@JoinColumn(name = "accepted_by")
private User acceptedBy;
/**
* Status of the mapping request in the workflow.
*
* @see RequestStatus
*/
public enum RequestStatus {
/**
* Request is waiting for approval.
*/
PENDING,
/**
* Request has been approved.
* The mapping should now be applied to the tunnel.
*/
APPROVED,
/**
* Request has been rejected.
* No changes will be made to the tunnel.
*/
REJECTED
}
/**
* Current status of this request.
*
* <p>Initially set to PENDING when created.</p>
*
* @see RequestStatus
*/
@Enumerated(EnumType.STRING)
@Column(length = 10, nullable = false)
private RequestStatus status;

View File

@ -8,60 +8,21 @@ import lombok.Setter;
import java.util.UUID;
/**
* JPA Entity representing a Cloudflare Tunnel configuration.
*
* <p>This entity stores the locally cached configuration of a Cloudflare Tunnel,
* linking the tunnel's unique identifier from Cloudflare with its local
* environment name for easier reference and management.</p>
*
* <p>The entity is uniquely constrained by tunnel ID and environment name,
* ensuring only one configuration exists per tunnel per environment.</p>
*
* <p><b>Database Table:</b> {@code tunnels}</p>
*
* <p><b>Relationships:</b></p>
* <ul>
* <li>One Tunnel has many Mappings (via tunnel_id foreign key)</li>
* </ul>
*
* @see Mapping
* @see Request
*/
@Entity
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Table(name = "tunnels")
@Table(name="tunnels")
public class Tunnel {
/**
* Unique identifier for the tunnel (UUID).
*
* <p>This corresponds to the Cloudflare-assigned tunnel ID
* and serves as the primary key for this entity.</p>
*/
@Id
@Column(columnDefinition = "uuid", insertable = false, updatable = false, nullable = false)
private UUID id;
/**
* Environment name associated with this tunnel configuration.
*
* <p>Examples: "production", "staging", "development"</p>
* <p>Each tunnel can be configured for multiple environments.</p>
*/
@Column(length = 10, unique = true, nullable = false)
private String environment;
/**
* Display name of the tunnel as configured in Cloudflare.
*
* <p>This is the user-friendly name assigned to the tunnel
* when it was created in Cloudflare Zero Trust Dashboard
* or via the Cloudflare API.</p>
*/
@Column(length = 50, unique = true, nullable = false)
private String name;
}

View File

@ -1,5 +1,4 @@
package com.hithomelabs.CFTunnels.Entity;
import jakarta.persistence.*;
import jakarta.validation.constraints.Size;
import lombok.AllArgsConstructor;
@ -9,26 +8,6 @@ import lombok.Setter;
import java.util.UUID;
/**
* JPA Entity representing a user in the system.
*
* <p>This entity stores user information synced from the OIDC provider
* during authentication. Users are assigned roles that determine their
* access levels to the API endpoints.</p>
*
* <p><b>Database Table:</b> {@code users}</p>
*
* <p><b>Roles:</b></p>
* <ul>
* <li>USER - Basic access to view tunnels</li>
* <li>DEVELOPER - Can create/modify mappings</li>
* <li>APPROVER - Can approve/reject requests</li>
* <li>ADMIN - Full access including tunnel configuration</li>
* </ul>
*
* @see Request
* @see Mapping
*/
@Entity
@Getter
@Setter
@ -36,32 +15,15 @@ import java.util.UUID;
@AllArgsConstructor
@Table(name = "users")
public class User {
/**
* Unique identifier for the user (UUID).
*
* <p>This corresponds to the user's ID in the OIDC provider.</p>
*/
@Id
@GeneratedValue
@Column(columnDefinition = "uuid", insertable = false, updatable = false, nullable = false)
private UUID id;
/**
* User's display name.
*
* <p>This is typically the full name from the OIDC provider.</p>
*/
@Column(length = 50, nullable = false)
@Size(max = 50)
private String name;
/**
* User's email address.
*
* <p>Used as the unique identifier for authentication
* and for associating users with their roles.</p>
*/
@Column(length = 50, nullable = false)
@Size(max = 50)
private String email;

View File

@ -8,86 +8,17 @@ import lombok.Setter;
import java.util.List;
import java.util.Map;
/**
* Model representing an ingress rule for a Cloudflare Tunnel.
*
* <p>Ingress rules define how incoming requests should be routed through
* the tunnel to your internal services. Each rule specifies:</p>
* <ul>
* <li>{@link #hostname} - The domain/subdomain to match</li>
* <li>{@link #service} - The internal service URL</li>
* <li>{@link #originRequest} - Optional settings for origin requests</li>
* <li>{@link #path} - Optional path prefix to match</li>
* </ul>
*
* <p><b>Example JSON:</b></p>
* <pre>
* {
* "hostname": "api.example.com",
* "service": "http://localhost:8080",
* "originRequest": {
* "noTLSVerify": true
* },
* "path": "/api"
* }
* </pre>
*
* @see <a href="https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/routing/ingress/">Cloudflare Ingress Docs</a>
*/
@NoArgsConstructor
@AllArgsConstructor
@Getter
@Setter
public class Ingress {
/**
* The target service URL.
*
* <p>Format: {@code protocol://host:port}</p>
* <p>Example: {@code http://localhost:8080}</p>
*/
private String service;
/**
* Hostname pattern to match for this ingress rule.
*
* <p>Can be a full domain (api.example.com) or use wildcards
* (*.example.com) to match subdomains.</p>
* <p>If null, this rule acts as a catch-all.</p>
*/
private String hostname;
/**
* Optional settings for requests to the origin server.
*
* <p>Supported options:</p>
* <ul>
* <li>noTLSVerify - Skip TLS verification</li>
* <li>connectTimeout - Connection timeout in seconds</li>
* <li>tlsTimeout - TLS handshake timeout</li>
* <li>httpHostHeader - Host header to send</li>
* </ul>
*/
private Map<String, Object> originRequest;
/**
* Optional path to match before routing.
*
* <p>Example: "/api" would only route requests with
* paths starting with /api to this service.</p>
*/
private String path;
/**
* Removes an ingress rule by hostname from a list.
*
* <p>This utility method finds and removes the first ingress
* matching the given hostname.</p>
*
* @param ingressList List of ingress rules to modify
* @param toBeDeleted Hostname of the rule to remove
* @return true if an ingress was removed, false otherwise
*/
public static boolean deleteByHostName(List<Ingress> ingressList, String toBeDeleted){
return ingressList.removeIf(ingress -> ingress.getHostname() != null && ingress.getHostname().equals(toBeDeleted));
}

View File

@ -22,60 +22,21 @@ import java.util.NoSuchElementException;
import java.util.Optional;
import java.util.UUID;
/**
* Service for interacting with the Cloudflare Tunnel API.
*
* <p>This service provides methods to manage Cloudflare Tunnels,
* including fetching tunnel configurations, creating/updating tunnels,
* and adding ingress mappings. It handles all communication with the
* Cloudflare API using the configured credentials.</p>
*
* <p><b>API Endpoints Used:</b></p>
* <ul>
* <li>GET /accounts/{accountId}/cfd_tunnel - List all tunnels</li>
* <li>GET /accounts/{accountId}/cfd_tunnel/{tunnelId}/configurations - Get tunnel config</li>
* <li>PUT /accounts/{accountId}/cfd_tunnel/{tunnelId}/configurations - Update tunnel config</li>
* </ul>
*
* @see CloudflareConfig
* @see Tunnel
* @see Ingress
*/
@Service
public class CloudflareAPIService {
/**
* Configuration for Cloudflare API credentials and settings.
* Loaded from application.properties using the {@code cloudflare.*} prefix.
*/
@Autowired
CloudflareConfig cloudflareConfig;
/**
* Header provider for Cloudflare API authentication.
* Generates the X-Auth-Key and X-Auth-Email headers.
*/
@Autowired
AuthKeyEmailHeader authKeyEmailHeader;
/**
* HTTP client for making API requests.
*/
@Autowired
RestTemplate restTemplate;
/**
* Repository for storing tunnel configurations locally.
*/
@Autowired
TunnelRepository tunnelRepository;
/**
* Fetches all Cloudflare tunnels from the API.
*
* @return Response containing the list of tunnels from Cloudflare
* @see TunnelsResponse
*/
public ResponseEntity<TunnelsResponse> getCloudflareTunnels() {
String url = "https://api.cloudflare.com/client/v4/accounts/" + cloudflareConfig.getAccountId() + "/cfd_tunnel";
@ -85,18 +46,9 @@ public class CloudflareAPIService {
return responseEntity;
}
/**
* Fetches the configuration for a specific tunnel.
*
* @param tunnelId The Cloudflare tunnel ID (UUID string)
* @param restTemplate HTTP client to use for the request
* @param responseType Class to deserialize the response into
* @param <T> Response type
* @return Response containing the tunnel configuration
*/
public <T> ResponseEntity<T> getCloudflareTunnelConfigurations(String tunnelId, RestTemplate restTemplate, Class<T> responseType) {
// Resource URL to hit get request at
// * * Resource URL to hit get request at
String url = "https://api.cloudflare.com/client/v4/accounts/" + cloudflareConfig.getAccountId() + "/cfd_tunnel/" + tunnelId + "/configurations";
HttpEntity<String> httpEntity = new HttpEntity<>("",authKeyEmailHeader.getHttpHeaders());
@ -104,22 +56,9 @@ public class CloudflareAPIService {
return responseEntity;
}
/**
* Updates the configuration for a specific tunnel.
*
* <p>This method is used to add, modify, or remove ingress mappings
* by providing a complete configuration object.</p>
*
* @param tunnelId The Cloudflare tunnel ID (UUID string)
* @param restTemplate HTTP client to use for the request
* @param responseType Class to deserialize the response into
* @param config The new configuration to apply
* @param <T> Response type
* @return Response containing the updated tunnel configuration
*/
public <T> ResponseEntity<T> putCloudflareTunnelConfigurations(String tunnelId, RestTemplate restTemplate, Class<T> responseType, Config config) {
// Resource URL to hit get request at
// * * Resource URL to hit get request at
String url = "https://api.cloudflare.com/client/v4/accounts/" + cloudflareConfig.getAccountId() + "/cfd_tunnel/" + tunnelId + "/configurations";
HttpHeaders httpHeaders = authKeyEmailHeader.getHttpHeaders();
@ -129,29 +68,10 @@ public class CloudflareAPIService {
return responseEntity;
}
/**
* Converts a Cloudflare API tunnel result to a local Tunnel entity.
*
* @param tunnelResult The tunnel result from Cloudflare API
* @param env The environment name to associate
* @return New Tunnel entity instance
*/
private Tunnel getTunnelFromTunnelResponse(TunnelResult tunnelResult, String env){
return new Tunnel(UUID.fromString(tunnelResult.getId()), env, tunnelResult.getName());
}
/**
* Creates or updates a tunnel's local configuration.
*
* <p>This method fetches the tunnel from Cloudflare API, validates it exists,
* and stores a local copy with the environment association.</p>
*
* @param tunnelId The Cloudflare tunnel ID
* @param environment Environment name (e.g., "production", "staging")
* @return The created or updated Tunnel entity
* @throws ExternalServiceException if Cloudflare API returns an error
* @throws NoSuchElementException if the tunnel doesn't exist in Cloudflare
*/
public Tunnel createOrUpdateTunnel(String tunnelId, String environment) throws ExternalServiceException, NoSuchElementException {
ResponseEntity<TunnelsResponse> responseEntity = getCloudflareTunnels();
@ -172,25 +92,10 @@ public class CloudflareAPIService {
return toBeConfigured;
}
/**
* Retrieves all tunnels that have been locally configured.
*
* @return List of locally configured tunnels
*/
public List<Tunnel> getAllConfiguredTunnels() {
return tunnelRepository.findAll();
}
/**
* Adds an ingress mapping to an existing tunnel.
*
* <p>The new ingress is inserted at the second-to-last position in the
* ingress list (Cloudflare requires a catch-all rule at the end).</p>
*
* @param tunnelId The Cloudflare tunnel ID
* @param ingress The ingress configuration to add
* @return Response with the updated tunnel configuration
*/
public ResponseEntity<TunnelResponse> addTunnelIngress(String tunnelId, Ingress ingress) {
ResponseEntity<TunnelResponse> currentConfig = getCloudflareTunnelConfigurations(tunnelId, restTemplate, TunnelResponse.class);

View File

@ -2,9 +2,9 @@ spring.application.name=CFTunnels
cloudflare.accountId=${CLOUDFLARE_ACCOUNT_ID}
cloudflare.apiKey=${CLOUDFLARE_API_KEY}
cloudflare.email=${CLOUDFLARE_EMAIL}
spring.profiles.active=${ENV:default}
spring.profiles.active=${ENV}
# Making sure app works behind a reverse proxy
/ * * Masking sure app works behind a reverse proxy
server.forward-headers-strategy=framework
spring.security.oauth2.client.registration.cftunnels.client-id=${OAUTH_CLIENT_ID}