Host Config & Security

// Three-tier permission model
// Each layer can only RESTRICT, never expand permissions.

// Tier 1: Creator restrictions (embedded in the .mp4e file)
metadata.settings.restrictions = {
  sequential: true,       // No seeking forward
  actions: { download: false }
};

// Tier 2: Host config (React prop)
<MP4EPlayer
  config={{
    sandbox: { actions: { openUrl: false } },
    gated: ['navigate'],
    disabled: { layers: ['debug-layer'] }
  }}
/>

// Tier 3: Viewer preferences (runtime, from player menu)
engine.setViewerPreferences({
  doNotTrack: true,
  reducedMotion: true
});

engine.on('engine:source', ({ source, version, reason }) => {
  // source:  'embedded' | 'bundled'
  // version: the embedded engine's version when source === 'embedded', else null
  // reason:  'preferred' | 'no-embedded-atom' | 'verification-failed' | 'sha256-mismatch'
  //        | 'below-floor' | 'revoked' | 'host-forced-bundled' | 'abi-unsupported'
  //        | 'decompression-failed'
})

<MP4EPlayer
  src="/video.mp4"
  config={{
    permissions: { intelligence: ['chapters', 'moments'] },
  }}
/>

import { MP4EPlayer } from '@mp4e/react';
import '@mp4e/react/styles.css';

function SecurePlayer() {
  return (
    <MP4EPlayer
      src="/video.mp4"
      config={{
        gated: ['openUrl', 'navigate'],
        gateTimeoutMs: 10000,
        gateTimeoutPolicy: 'deny',
      }}
      onActionGate={(action, resolve) => {
        if (action.type === 'openUrl') {
          // Show a confirmation dialog before opening external URLs
          const approved = window.confirm(
            `This video wants to open: ${action.params.url}\nAllow?`
          );
          resolve(approved);
        } else if (action.type === 'navigate') {
          // Always allow in-app navigation
          resolve(true);
        } else {
          // Deny unknown gated actions
          resolve(false);
        }
      }}
    />
  );
}

<MP4EPlayer
  src="/video.mp4"
  config={{
    networkGateTimeoutMs: 3000,
    networkGateTimeoutPolicy: 'deny',
  }}
  onNetworkGate={(request, resolve) => {
    // Only allow requests to your own domains
    const allowed = ['api.mysite.com', 'cdn.mysite.com'];
    const url = new URL(request.url);

    console.log(
      `Plugin ${request.pluginId} requesting ${request.method} ${request.url}`
    );

    resolve(allowed.includes(url.hostname));
  }}
/>

interface PluginSecurityRule {
  /**
   * Network access policy:
   * - 'none': Block all network access
   * - 'manifest': Allow only domains declared in plugin manifest
   * - 'any': Unrestricted (dangerous, explicit opt-in only)
   * - string[]: Explicit domain allowlist (replaces manifest)
   * Applies to mp4e.fetch and, through the plugin frame's Content
   * Security Policy, to the plugin's own requests: fetch, XMLHttpRequest
   * and WebSocket connections, images and form posts may reach only the
   * listed domains (none for 'none'). Under 'none', 'manifest' or a domain
   * list, scripts and styles must be inline in the plugin — external
   * scripts and stylesheets do not load, even from a listed domain.
   */
  network?: 'none' | 'manifest' | 'any' | string[];

  /**
   * Sandbox level controlling iframe capabilities:
   * - 'contained': allow-scripts, allow-forms only (NO same-origin)
   * - 'connected': the default when no pluginSecurity is set (the iframe
   *   is isolated; use mp4e.storage / mp4e.fetch)
   * - 'trusted': + allow-same-origin (full host page access)
   */
  sandbox?: 'contained' | 'connected' | 'trusted';

  /**
   * Required signer name. The rule applies only to a plugin signed by this
   * signer (checked against trustedSigners). An unsigned plugin, a plugin
   * signed by a different trusted signer, or a host with no trustedSigners
   * gets the 'contained' level and no network access instead.
   */
  signer?: string;
}

<MP4EPlayer
  src="/video.mp4"
  config={{
    pluginSecurity: {
      // Global default: contained sandbox, no network
      '*': {
        sandbox: 'contained',
        network: 'none',
      },

      // Official MP4E plugins: connected sandbox, manifest-declared domains
      'mp4e:*': {
        sandbox: 'connected',
        network: 'manifest',
        signer: 'mp4e',
      },

      // Stripe plugins: connected sandbox, explicit domain allowlist
      'stripe:*': {
        sandbox: 'connected',
        network: ['js.stripe.com', 'api.stripe.com'],
      },

      // Specific trusted plugin: full access
      'stripe:checkout': {
        sandbox: 'trusted',
        network: 'any',
      },

      // Block a known-bad namespace entirely
      '!badguy:*': {
        sandbox: 'contained',
        network: 'none',
      },
    },
  }}
/>

// Creator embeds restrictions in the video metadata
// These are enforced by the engine regardless of host config

{
  "settings": {
    "restrictions": {
      "sequential": true,
      "actions": {
        "download": false,
        "openUrl": false
      }
    }
  }
}

<MP4EPlayer
  src="/video.mp4"
  onSecurityViolation={(violation) => {
    console.error(
      `Security violation by plugin ${violation.pluginId}:\n` +
      `  Blocked URI: ${violation.blockedURI}\n` +
      `  Violated directive: ${violation.violatedDirective}`
    );

    // Report to your monitoring service
    analytics.track('security_violation', {
      pluginId: violation.pluginId,
      blockedURI: violation.blockedURI,
      directive: violation.violatedDirective,
    });
  }}
/>

import { MP4EPlayer } from '@mp4e/react';
import '@mp4e/react/styles.css';

function ProductionPlayer({ videoUrl }: { videoUrl: string }) {
  return (
    <MP4EPlayer
      src={videoUrl}
      config={{
        // Block dangerous actions entirely
        sandbox: {
          actions: {
            download: false,
            openUrl: false,
          },
        },

        // Require approval for navigation
        gated: ['navigate', 'goToScene'],
        gateTimeoutMs: 8000,
        gateTimeoutPolicy: 'deny',

        // Disable specific creator content
        disabled: {
          layers: ['debug-layer'],
          actionTypes: ['console'],
        },

        // Plugin security per namespace
        pluginSecurity: {
          '*': { sandbox: 'contained', network: 'none' },
          'mp4e:*': { sandbox: 'connected', network: 'manifest' },
          'stripe:checkout': { sandbox: 'trusted', network: 'any' },
        },

        // Trust official MP4E signatures
        trustedSigners: { mp4e: true },
      }}

      // Gate callbacks
      onActionGate={(action, resolve) => {
        resolve(window.confirm(`Allow action: ${action.type}?`));
      }}
      onNetworkGate={(req, resolve) => {
        const trusted = ['api.mysite.com', 'cdn.mysite.com'];
        resolve(trusted.includes(new URL(req.url).hostname));
      }}
      onSecurityViolation={(v) => {
        console.error('Security violation:', v);
      }}
    />
  );
}