File request support

[awehttam]

To start with I want to retrieve backbone.na from my uplink so that groups can be added through a web interface.

Then it would be cool to let users setup their own feeds instead of showing the same to all.

[awehttam]

/!\ This analysis is outdated

Based on my analysis of the existing BinktermPHP codebase, here's what would be involved in adding FREQ (File
Request) support:

Current State

• Existing: Basic file transfer infrastructure in BinkpSession.php
• UI Placeholder: Nodelist view shows "File request feature coming soon!" button
• Missing: FREQ-specific protocol handling, request management, and security controls

FREQ Implementation Requirements

1. Database Schema Changes

-- File request tracking table
CREATE TABLE file_requests (
id SERIAL PRIMARY KEY,
requesting_user_id INT REFERENCES users(id),
target_address VARCHAR(50) NOT NULL,
requested_filename VARCHAR(255) NOT NULL,
magic_filename VARCHAR(255), -- For !MAGIC requests
status VARCHAR(20) DEFAULT 'pending', -- pending, sent, failed, expired
created_at TIMESTAMP DEFAULT NOW(),
processed_at TIMESTAMP,
expiry_time TIMESTAMP,
notes TEXT
);

-- Available files for FREQ (file index)
CREATE TABLE freq_files (
id SERIAL PRIMARY KEY,
filename VARCHAR(255) NOT NULL,
file_path TEXT NOT NULL,
description TEXT,
file_size BIGINT,
available BOOLEAN DEFAULT TRUE,
magic_name VARCHAR(255), -- Optional magic filename
password VARCHAR(50), -- Optional password protection
max_requests_per_day INT DEFAULT 10,
created_at TIMESTAMP DEFAULT NOW()
);

2. Protocol Extensions

Extend BinkpSession.php:

• Add FREQ request parsing during file transfer phase
• Handle .REQ file processing (standard FREQ format)
• Support magic filename resolution (!FILENAME)
• Implement password-protected file requests

3. Core Components Needed

FreqHandler.php

class FreqHandler {
public function createFileRequest($userId, $targetAddress, $filename, $password = null);
public function processIncomingRequests($reqFilePath);
public function resolveFreqFiles($requestedFiles);
public function validateFreqPermissions($remoteAddress, $filename);
public function generateFreqResponse($requests);
}

FreqManager.php

class FreqManager {
public function addFreqFile($filename, $filePath, $description = null);
public function removeFreqFile($filename);
public function listAvailableFiles($remoteAddress = null);
public function checkRateLimits($remoteAddress);
public function updateRequestStatus($requestId, $status);
}

4. File Management

• Upload Interface: Web UI for admins to add/manage FREQ-available files
• File Security: Validate file paths, prevent directory traversal
• Storage Structure: Organized file repository with metadata
• Rate Limiting: Prevent abuse with request limits per node/day

5. Web Interface Components

FREQ Request Form (templates/freq_request.twig)

• Target node selection (from nodelist)
• Filename input with magic filename support
• Password field for protected files
• Request history/status tracking

Admin FREQ Management (templates/admin/freq.twig)

• File upload/management interface
• Request monitoring and approval
• Security settings (passwords, rate limits)
• Usage statistics

6. Security Considerations

• File Access Control: Only serve approved files
• Authentication: Support password-protected files
• Rate Limiting: Prevent DOS attacks
• Path Validation: Prevent directory traversal
• User Permissions: Control who can make requests

7. Integration Points

BinkpSession Integration

// During file transfer phase
if ($this->hasFreqRequests()) {
$this->processFreqRequests();
}

API Endpoints (in index.php)

SimpleRouter::post('/api/freq/request', 'createFreqRequest');
SimpleRouter::get('/api/freq/files', 'listFreqFiles');
SimpleRouter::get('/api/freq/status/{id}', 'getFreqStatus');

Implementation Phases

Phase 1: Basic Infrastructure

1. Database schema creation
2. Core FreqHandler/FreqManager classes
3. Basic .REQ file parsing
4. Simple file serving

Phase 2: Web Interface

1. FREQ request form
2. Admin file management
3. Request status tracking
4. Integration with nodelist

Phase 3: Advanced Features

1. Magic filename support (!FILENAME)
2. Password-protected files
3. Rate limiting and security
4. Request approval workflows

Phase 4: Polish & Integration

1. Statistics and reporting
2. Email notifications
3. Automated cleanup
4. Performance optimization

● Estimated Effort

Medium-Large Feature (~2-3 weeks development time)

The existing binkp infrastructure provides a solid foundation, but FREQ requires significant protocol extensions,
security considerations, and user interface development. The good news is that BinktermPHP already has file
transfer capabilities in BinkpSession.php that can be extended for FREQ support.