Building a Multi-Tenant NF-e API with Laravel + SEFAZ: 6 Hard Lessons

Tenant App ──REST──► FoxNFe Laravel API ──SOAP/XML──► SEFAZ (27 states)
                            │
                     PostgreSQL RLS
                     Redis + Queues
                     Certificate Store

CREATE POLICY tenant_isolation ON tenant_plan_usages
  USING (
    tenant_id = current_setting('app.tenant_id')::int
    OR current_setting('app.bypass_rls', true) = 'on'
  );

// DANGEROUS without finally
DB::statement("SELECT set_config('app.bypass_rls', 'on', false)");
$usage = TenantPlanUsage::withoutGlobalScopes()->where('tenant_id', $id)->first();
DB::statement("SELECT set_config('app.bypass_rls', '', false)");

public function getOrCreateUsage(Tenant $tenant): TenantPlanUsage
{
    return DB::transaction(function () use ($tenant): TenantPlanUsage {
        DB::statement("SELECT set_config('app.bypass_rls', 'on', false)");
        try {
            $usage = TenantPlanUsage::withoutGlobalScopes()
                ->where('tenant_id', $tenant->id)
                ->lockForUpdate()
                ->first();

            if ($usage === null) {
                $plan  = $this->getActivePlan($tenant);
                $quota = $plan->isEnterprise() ? null : $plan->monthly_note_quota;
                $usage = TenantPlanUsage::forceCreate([
                    'tenant_id'     => $tenant->id,
                    'plan_id'       => $plan->id,
                    'nfes_used'     => 0,
                    'period_start'  => now()->startOfMonth()->toDateString(),
                    'period_end'    => now()->endOfMonth()->toDateString(),
                    'monthly_quota' => $quota,
                ]);
            }

            return $usage;
        } finally {
            // Restore even if an exception fires
            DB::statement("SELECT set_config('app.bypass_rls', '', false)");
        }
    });
}

// Store — encrypt before saving to DB
public function storeCertificate(Tenant $tenant, UploadedFile $pfx, string $password): void
{
    $tenant->update([
        'certificate_content'  => encrypt($pfx->get()),
        'certificate_password' => encrypt($password),
        'certificate_expires'  => $this->extractExpiry($pfx->get(), $password),
    ]);
}

// Load at runtime — decrypt in memory only, never touch disk
public function loadCertificate(Tenant $tenant): array
{
    $certData = [];
    $success  = openssl_pkcs12_read(
        decrypt($tenant->certificate_content),
        $certData,
        decrypt($tenant->certificate_password)
    );

    if (!$success) {
        throw new InvalidCertificateException(
            "Certificate invalid or password wrong for tenant {$tenant->id}"
        );
    }

    return $certData; // ['cert' => '...PEM...', 'pkey' => '...PEM...']
}

private function processResponse(NFeResponse $response): void
{
    match (true) {
        in_array($response->cStat, [100, 150, 204]) => $this->handleAuthorized($response),
        $response->cStat === 110                    => $this->handleDenied($response),
        $response->cStat === 999                    => $this->handleRetry($response),
        default                                     => $this->handleUnknown($response),
    };
}

private function handleAuthorized(NFeResponse $response): void
{
    // 1. Persist authorization first
    $this->nfe->update([
        'status'        => NFeStatus::AUTHORIZED,
        'protocol'      => $response->nProt,
        'authorized_at' => now(),
        'xml_authorized'=> $response->xml,
    ]);

    // 2. Increment quota — if this fails, the NF-e is already authorized
    // in SEFAZ. We cannot reverse it. Log the failure and continue.
    try {
        $this->planEnforcer->incrementNfeUsage($this->tenant);
    } catch (\Throwable $e) {
        Log::warning('Quota increment failed after NF-e authorization', [
            'nfe_id'    => $this->nfe->id,
            'tenant_id' => $this->tenant->id,
            'error'     => $e->getMessage(),
        ]);
    }
}

// VULNERABLE
private function resolveTenant(Request $request): Tenant
{
    return Tenant::findOrFail($request->header('X-Tenant-ID'));
}

// upgrade() used this — any authenticated user could upgrade ANY tenant's plan
public function upgrade(Request $request): JsonResponse
{
    $tenant = $this->resolveTenant($request);
    // ... proceed to upgrade billing
}

private function resolveTenant(Request $request): Tenant
{
    $tenant = Tenant::findOrFail($request->header('X-Tenant-ID'));

    if ($request->user()->tenant_id !== $tenant->id) {
        abort(403, 'Unauthorized: tenant mismatch');
    }

    return $tenant;
}

class PlanEnforcerTest extends TestCase
{
    private ?Tenant $tenant = null;

    protected function setUp(): void
    {
        parent::setUp();

        if (!$this->isPgsqlAvailable()) {
            $this->markTestSkipped('PostgreSQL not available');
            return; // guard required — see tearDown note below
        }

        $this->tenant = Tenant::factory()->create();
    }

    protected function tearDown(): void
    {
        // CRITICAL: markTestSkipped() in setUp() does NOT prevent tearDown()
        // from running. If $this->tenant is null (test was skipped),
        // forceDelete() will throw. Always null-check.
        if ($this->tenant !== null) {
            TenantPlanUsage::where('tenant_id', $this->tenant->id)->forceDelete();
            $this->tenant->forceDelete();
        }

        parent::tearDown();
    }

    public function test_rls_restored_after_exception(): void
    {
        // Simulate exception inside getOrCreateUsage
        $this->mock(TenantPlanUsage::class)
             ->shouldReceive('forceCreate')
             ->andThrow(new \RuntimeException('Simulated DB failure'));

        try {
            app(PlanEnforcer::class)->getOrCreateUsage($this->tenant);
        } catch (\Throwable) {
            // Expected
        }

        $setting = DB::selectOne("SELECT current_setting('app.bypass_rls', true) AS val");
        $this->assertNotEquals('on', $setting->val, 'bypass_rls must be restored after exception');
    }
}

public function validateSchema(string $xml): void
{
    $dom = new \DOMDocument();
    $dom->loadXML($xml);

    $xsdPath = storage_path('sefaz/nfe_v4.00.xsd');

    if (!$dom->schemaValidate($xsdPath)) {
        $errors = libxml_get_errors();
        throw new SchemaValidationException(
            'NF-e XML schema invalid: ' . $errors[0]->message . ' on line ' . $errors[0]->line
        );
    }
}