configuring-tauri-http-headers

name	configuring-tauri-http-headers
description	Configure HTTP response headers in Tauri v2.1+ webview responses, covering security headers, custom headers, and CORS from the allowlist. USE WHEN adding security headers, setting CORS for cross-origin requests, or customizing webview response headers.
cluster	tauri
version	1.0.0

Tauri HTTP Headers Security Configuration

This skill covers HTTP headers configuration in Tauri v2.1.0+, enabling developers to set security headers in webview responses.

Overview

Tauri allows configuring HTTP headers that are included in responses to the webview. These headers apply to production builds and do not affect IPC messages or error responses.

Supported Headers (Allowlist)

Tauri restricts header configuration to a specific allowlist for security:

CORS Headers

• Access-Control-Allow-Credentials
• Access-Control-Allow-Headers
• Access-Control-Allow-Methods
• Access-Control-Expose-Headers
• Access-Control-Max-Age

Cross-Origin Policies

• Cross-Origin-Embedder-Policy
• Cross-Origin-Opener-Policy
• Cross-Origin-Resource-Policy

Security Headers

• X-Content-Type-Options
• Permissions-Policy
• Timing-Allow-Origin
• Service-Worker-Allowed

Testing Only

• Tauri-Custom-Header (not for production use)

Configuration in tauri.conf.json

Headers are configured under app.security.headers in src-tauri/tauri.conf.json.

Value Formats

1. String: Direct assignment
2. Array: Items joined by commas
3. Object: Key-value pairs formatted as "key value", joined by semicolons
4. Null: Header is ignored

Basic Configuration Example

{
  "app": {
    "security": {
      "headers": {
        "Cross-Origin-Opener-Policy": "same-origin",
        "Cross-Origin-Embedder-Policy": "require-corp",
        "X-Content-Type-Options": "nosniff"
      }
    }
  }
}

Comprehensive Configuration Example

{
  "app": {
    "security": {
      "headers": {
        "Cross-Origin-Opener-Policy": "same-origin",
        "Cross-Origin-Embedder-Policy": "require-corp",
        "Cross-Origin-Resource-Policy": "same-origin",
        "Timing-Allow-Origin": [
          "https://example.com",
          "https://api.example.com"
        ],
        "X-Content-Type-Options": "nosniff",
        "Permissions-Policy": {
          "camera": "()",
          "microphone": "()",
          "geolocation": "(self)"
        },
        "Access-Control-Allow-Methods": ["GET"   
          
         
      
       
    
  

Enabling SharedArrayBuffer

SharedArrayBuffer requires specific cross-origin policies. Configure both headers together:

{
  "app": {
    "security": {
      "headers": {
        "Cross-Origin-Opener-Policy": "same-origin",
        "Cross-Origin-Embedder-Policy": "require-corp"
      }
    }
  }
}

CORS Configuration Examples

Restrictive CORS (Recommended for Production)

{
  "app": {
    "security": {
      "headers": {
        "Cross-Origin-Resource-Policy": "same-origin",
        "Access-Control-Allow-Credentials": "false",
        "Access-Control-Allow-Methods": ["GET"],
        "Access-Control-Max-Age": "3600"
      }
    }
  }
}

Permissive CORS (Development/API Scenarios)

{
  "app": {
    "security": {
      "headers": {
        "Cross-Origin-Resource-Policy": "cross-origin",
        "Access-Control-Allow-Methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
        "Access-Control-Allow-Headers": ["Content-Type", "Authorization", "X-Requested-With"],
        "Access-Control-Expose-Headers": ["Content-Length", "X-Request-Id"],
        "Access-Control-Max-Age": "86400"
      }
    }
  }
}

Development Server Configuration

Development frameworks require separate header configuration for their dev servers. Tauri header injection only applies to production builds.

Vite (React, Vue, Svelte, Solid, Qwik)

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp',
      'X-Content-Type-Options': 'nosniff'
    }
  }
});

Angular

// angular.json
{
  "projects": {
    "your-app": {
      "architect": {
        "serve": {
          "options": {
            "headers": {
              "Cross-Origin-Opener-Policy": "same-origin",
              "Cross-Origin-Embedder-Policy": "require-corp"
            }
          }
        }
      }
    }
  }
}

Nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    server: {
      headers: {
        'Cross-Origin-Opener-Policy': 'same-origin',
        'Cross-Origin-Embedder-Policy': 'require-corp'
      }
    }
  }
});

Next.js

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Cross-Origin-Opener-Policy',
            value: 'same-origin'
          },
          {
            key: 'Cross-Origin-Embedder-Policy',
            value: 'require-corp'
          }
        ]
      }
    ];
  }
};

Trunk (Yew, Leptos)

# Trunk.toml
[serve]
headers = { "Cross-Origin-Opener-Policy" = "same-origin", "Cross-Origin-Embedder-Policy" = "require-corp" }

Security Headers Reference

Cross-Origin-Opener-Policy (COOP)

Controls window opener relationships:

Value	Description
unsafe-none	Default, allows opener access
same-origin	Isolates browsing context to same-origin
same-origin-allow-popups	Same-origin but allows popups

Cross-Origin-Embedder-Policy (COEP)

Controls resource embedding:

Value	Description
unsafe-none	Default, no restrictions
require-corp	Requires CORP or CORS for cross-origin resources
credentialless	Cross-origin requests without credentials

Cross-Origin-Resource-Policy (CORP)

Controls who can load your resources:

Value	Description
same-site	Only same-site requests
same-origin	Only same-origin requests
cross-origin	Allows cross-origin requests

X-Content-Type-Options

Prevents MIME type sniffing:

{
  "X-Content-Type-Options": "nosniff"
}

Permissions-Policy

Controls browser feature access:

{
  "Permissions-Policy": {
    "camera": "()",
    "microphone": "()",
    "geolocation": "(self)",
    "fullscreen": "(self)"
  }
}

Best Practices

1. Configure Both Dev and Prod: Set headers in both your framework's dev server config and tauri.conf.json for consistent behavior.

2. Use Restrictive Defaults: Start with restrictive policies and loosen only as needed.

3. Enable COOP/COEP Together: For SharedArrayBuffer support, both headers must be configured.

4. Separate CSP Configuration: Content-Security-Policy is configured under app.security.csp, not in the headers section.

5. Avoid Tauri-Custom-Header in Production: This header is for testing purposes only.

6. Test Cross-Origin Scenarios: Verify that CORS headers work correctly with your API endpoints.

Troubleshooting

SharedArrayBuffer Not Available

Ensure both headers are set:

{
  "Cross-Origin-Opener-Policy": "same-origin",
  "Cross-Origin-Embedder-Policy": "require-corp"
}

Headers Not Applied in Development

Headers in tauri.conf.json only apply to production builds. Configure your dev server separately.

CORS Errors with External APIs

Add required headers for cross-origin requests:

{
  "Access-Control-Allow-Methods": ["GET", "POST", "OPTIONS"],
  "Access-Control-Allow-Headers": ["Content-Type", "Authorization"]
}

Custom Headers Not Visible

Expose custom headers via:

{
  "Access-Control-Expose-Headers": ["X-Custom-Header", "X-Request-Id"]
}

Version Requirements

• Tauri v2.1.0 or later required for HTTP headers configuration
• Headers feature is not available in earlier versions

Related Configuration

• CSP: Configure under app.security.csp for Content Security Policy
• Capabilities: Use Tauri's capability system for fine-grained permissions
• IPC Security: Headers do not affect IPC message handling