Add service API for Ladill Mail large attachment uploads.

Webmail can POST /api/v1/transfers with a mailbox address to create share links for files above 25 MB.

Co-authored-by: Cursor <cursoragent@cursor.com>

.env.example

@@ -41,6 +41,10 @@ TRANSFER_PRICE_PER_GB_MONTH=0.15
 TRANSFER_MAX_FILE_BYTES=524288000
 TRANSFER_MAX_FILES=20
 TRANSFER_DEFAULT_RETENTION_DAYS=30
+TRANSFER_MAIL_RETENTION_DAYS=30
+
+# Ladill Mail — large attachment uploads (service-to-service).
+TRANSFER_API_KEY_WEBMAIL=
 
 AFIA_ENABLED=true
 AFIA_PRODUCT=transfer

app/Http/Controllers/Api/TransferController.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Services\Identity\MailboxUserResolver;
+use App\Services\Transfer\TransferService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use RuntimeException;
+
+class TransferController extends Controller
+{
+    public function __construct(
+        private TransferService $transfers,
+        private MailboxUserResolver $users,
+    ) {}
+
+    /** Service-to-service upload (e.g. Ladill Mail for attachments above 25 MB). */
+    public function store(Request $request): JsonResponse
+    {
+        if ($request->attributes->get('service_caller') !== 'webmail') {
+            return response()->json(['message' => 'Forbidden.'], 403);
+        }
+
+        $maxKb = (int) ceil(((int) config('transfer.max_file_bytes', 524288000)) / 1024);
+        $maxFiles = (int) config('transfer.max_files_per_transfer', 20);
+
+        $data = $request->validate([
+            'mailbox' => ['required', 'email', 'max:255'],
+            'title' => ['nullable', 'string', 'max:120'],
+            'message' => ['nullable', 'string', 'max:2000'],
+            'retention_days' => ['nullable', 'integer', 'min:1', 'max:365'],
+            'files' => ['required', 'array', 'min:1', 'max:'.$maxFiles],
+            'files.*' => ['required', 'file', 'max:'.$maxKb],
+        ]);
+
+        try {
+            $user = $this->users->resolve((string) $data['mailbox']);
+        } catch (RuntimeException $e) {
+            return response()->json(['message' => $e->getMessage()], 422);
+        }
+
+        $title = trim((string) ($data['title'] ?? ''));
+        if ($title === '') {
+            $title = 'Email attachment';
+        }
+
+        $retentionDays = (int) ($data['retention_days'] ?? config('transfer.mail_retention_days', config('transfer.default_retention_days', 30)));
+
+        try {
+            $transfer = $this->transfers->create($user, [
+                'title' => $title,
+                'message' => $data['message'] ?? null,
+                'retention_days' => $retentionDays,
+            ], $request->file('files', []));
+        } catch (RuntimeException $e) {
+            return response()->json(['message' => $e->getMessage()], 422);
+        }
+
+        $transfer->load(['files', 'qrCode']);
+
+        return response()->json([
+            'data' => [
+                'id' => $transfer->id,
+                'title' => $transfer->title,
+                'public_url' => $transfer->qrCode?->publicUrl(),
+                'expires_at' => $transfer->expires_at?->toIso8601String(),
+                'files' => $transfer->files->map(fn ($file) => [
+                    'name' => $file->original_name,
+                    'size_bytes' => $file->size_bytes,
+                ])->values(),
+            ],
+        ], 201);
+    }
+}

app/Http/Middleware/AuthenticateService.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * Service-to-service auth for internal APIs. Validates the bearer token against
+ * per-consumer keys in config("{namespace}.service_api_keys").
+ */
+class AuthenticateService
+{
+    public function handle(Request $request, Closure $next, string $namespace = 'transfer'): Response
+    {
+        $token = (string) $request->bearerToken();
+        $caller = null;
+
+        if ($token !== '') {
+            foreach ((array) config("{$namespace}.service_api_keys", []) as $name => $key) {
+                if (is_string($key) && $key !== '' && hash_equals($key, $token)) {
+                    $caller = $name;
+                    break;
+                }
+            }
+        }
+
+        if ($caller === null) {
+            return response()->json(['error' => 'Unauthorized.'], 401);
+        }
+
+        $request->attributes->set('service_caller', $caller);
+
+        return $next($request);
+    }
+}

app/Services/Identity/MailboxUserResolver.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace App\Services\Identity;
+
+use App\Models\User;
+use Illuminate\Support\Facades\Http;
+use RuntimeException;
+
+/** Resolves a Ladill Transfer user mirror for a mailbox address (webmail integration). */
+class MailboxUserResolver
+{
+    public function resolve(string $mailbox): User
+    {
+        $mailbox = strtolower(trim($mailbox));
+        if ($mailbox === '' || ! str_contains($mailbox, '@')) {
+            throw new RuntimeException('Invalid mailbox address.');
+        }
+
+        $existing = User::query()->where('email', $mailbox)->first();
+        if ($existing) {
+            return $existing;
+        }
+
+        $base = rtrim((string) config('identity.api_url'), '/');
+        $key = (string) config('identity.api_key');
+        if ($base === '' || $key === '') {
+            throw new RuntimeException('Identity API is not configured.');
+        }
+
+        $res = Http::withToken($key)
+            ->acceptJson()
+            ->timeout(10)
+            ->get("{$base}/identity/profile", ['mailbox' => $mailbox]);
+
+        if ($res->failed()) {
+            throw new RuntimeException('Could not resolve the Ladill account for this mailbox.');
+        }
+
+        $data = $res->json('data');
+        if (! is_array($data)) {
+            throw new RuntimeException('Could not resolve the Ladill account for this mailbox.');
+        }
+
+        $publicId = trim((string) ($data['public_id'] ?? ''));
+        if ($publicId === '') {
+            throw new RuntimeException('No Ladill account is linked to this mailbox.');
+        }
+
+        return User::updateOrCreate(
+            ['public_id' => $publicId],
+            [
+                'name' => trim((string) ($data['name'] ?? '')) ?: $mailbox,
+                'email' => $mailbox,
+                'avatar_url' => ($picture = trim((string) ($data['picture'] ?? ''))) !== '' ? $picture : null,
+            ],
+        );
+    }
+}

bootstrap/app.php

@@ -16,6 +16,9 @@ return Application::configure(basePath: dirname(__DIR__))
         $middleware->redirectGuestsTo(fn (Request $request) => route('sso.connect', [
             'redirect' => $request->fullUrl(),
         ]));
+        $middleware->alias([
+            'auth.service' => \App\Http\Middleware\AuthenticateService::class,
+        ]);
         $middleware->web(append: [
             \App\Http\Middleware\SetActingAccount::class,
         ]);

config/transfer.php

@@ -1,6 +1,13 @@
 <?php
 
 return [
+    /*
+    | Service-to-service API keys (Bearer) for internal callers such as webmail.
+    */
+    'service_api_keys' => array_filter([
+        'webmail' => env('TRANSFER_API_KEY_WEBMAIL'),
+    ]),
+
     // GHS per GB per month of retention (see qr-suite-decomposition.md §7.3).
     'price_per_gb_month' => (float) env('TRANSFER_PRICE_PER_GB_MONTH', 0.15),
 
@@ -12,4 +19,7 @@ return [
 
     // Default retention when not specified (days).
     'default_retention_days' => (int) env('TRANSFER_DEFAULT_RETENTION_DAYS', 30),
+
+    // Retention for files uploaded via Ladill Mail (large attachments).
+    'mail_retention_days' => (int) env('TRANSFER_MAIL_RETENTION_DAYS', 30),
 ];

deploy/shared.env.example

@@ -41,6 +41,10 @@ TRANSFER_PRICE_PER_GB_MONTH=0.15
 TRANSFER_MAX_FILE_BYTES=524288000
 TRANSFER_MAX_FILES=20
 TRANSFER_DEFAULT_RETENTION_DAYS=30
+TRANSFER_MAIL_RETENTION_DAYS=30
+
+# Ladill Mail — large attachment uploads (must match WEBMAIL_TRANSFER_API_KEY).
+TRANSFER_API_KEY_WEBMAIL=
 
 AFIA_ENABLED=true
 AFIA_PRODUCT=transfer

routes/api.php

@@ -2,8 +2,13 @@
 
 use App\Http\Controllers\Api\MeController;
 use App\Http\Controllers\Api\QrCodeController;
+use App\Http\Controllers\Api\TransferController;
 use Illuminate\Support\Facades\Route;
 
+Route::middleware('auth.service:transfer')->prefix('v1')->group(function () {
+    Route::post('/transfers', [TransferController::class, 'store']);
+});
+
 Route::middleware(['auth:sanctum', \App\Http\Middleware\SetActingAccount::class])->prefix('v1')->group(function () {
     Route::get('/me', MeController::class);
 

tests/Feature/TransferApiTest.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Http\UploadedFile;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Storage;
+use Illuminate\Support\Str;
+use Tests\TestCase;
+
+class TransferApiTest extends TestCase
+{
+    use RefreshDatabase;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        Storage::fake('qr');
+        config([
+            'transfer.service_api_keys' => ['webmail' => 'test-webmail-key'],
+            'identity.api_url' => 'https://ladill.com/api',
+            'identity.api_key' => 'test-identity-key',
+        ]);
+    }
+
+    public function test_webmail_service_can_create_transfer_for_mailbox(): void
+    {
+        Http::fake([
+            rtrim((string) config('identity.api_url'), '/').'/identity/profile*' => Http::response([
+                'data' => [
+                    'public_id' => (string) Str::uuid(),
+                    'name' => 'Mail User',
+                    'email' => 'sender@acme.com',
+                    'picture' => null,
+                ],
+            ]),
+        ]);
+
+        $file = UploadedFile::fake()->create('large.zip', 30000, 'application/zip');
+
+        $this->withToken('test-webmail-key')
+            ->post('/api/v1/transfers', [
+                'mailbox' => 'sender@acme.com',
+                'title' => 'Email: Quarterly report',
+                'files' => [$file],
+            ])
+            ->assertCreated()
+            ->assertJsonPath('data.title', 'Email: Quarterly report')
+            ->assertJsonStructure(['data' => ['public_url', 'files']]);
+
+        $this->assertDatabaseHas('users', ['email' => 'sender@acme.com']);
+        $this->assertDatabaseCount('transfers', 1);
+    }
+
+    public function test_transfer_api_rejects_unauthorized_callers(): void
+    {
+        $this->post('/api/v1/transfers', ['mailbox' => 'x@y.com'])
+            ->assertUnauthorized();
+    }
+}