Platform Integration Playbook

How platforms integrate SOVEREIGN\PROVENANCE to verify provenance and enforce rights

Overview

Platforms (GitHub, Figma, Adobe, etc.) can integrate SOVEREIGN\PROVENANCE to verify content provenance and enforce creator rights before allowing use.

Integration Architecture

User Upload → Verify Passport → Evaluate Rights → Allow/Deny Use

Basic Integration

1. Verify Passport on Upload

import { createSovProvClient } from '@sovprovenance/sdk-js';

const client = createSovProvClient({
  baseUrl: 'https://api.sovereign.provenance',
  apiKey: 'your-platform-api-key',
});

async function handleUserUpload(file, passportId) {
  // Verify passport exists and is valid
  const verification = await client.verifyPassport(passportId);
  
  if (!verification.valid) {
    throw new Error('Invalid passport');
  }

  // Get passport details
  const passport = await client.getPassport(passportId);
  
  // Store passport reference with file
  await storeFile({
    file,
    passportId: passport.id,
    identityId: passport.identityId,
    accordId: passport.accordId,
  });
}

2. Evaluate Rights Before Use

async function checkUsageRights(passportId, proposedUse) {
  const passport = await client.getPassport(passportId);
  
  if (!passport.accordId) {
    // No rights declared, allow by default (or use platform policy)
    return { allowed: true, reason: 'No rights declared' };
  }

  const evaluation = await client.evaluateUse(passport.accordId, {
    type: proposedUse.type,
    commercial: proposedUse.commercial,
    geographicRegion: proposedUse.region,
  });

  return evaluation;
}

// Before allowing download/use
const evaluation = await checkUsageRights(passportId, {
  type: 'display',
  commercial: false,
});

if (!evaluation.allowed) {
  return { error: evaluation.reason };
}

3. Track Derivative Creation

async function createDerivative(originalPassportId, newFile) {
  // Check if derivatives are allowed
  const passport = await client.getPassport(originalPassportId);
  const evaluation = await client.evaluateUse(passport.accordId, {
    type: 'derivative',
  });

  if (!evaluation.allowed) {
    throw new Error('Derivatives not allowed: ' + evaluation.reason);
  }

  // Create new passport for derivative
  const derivativeSeal = await client.generateSeal(newFile);
  const derivativePassport = await client.createPassport({
    identityId: currentUserIdentity.id,
    sealId: derivativeSeal.id,
    metadata: {
      artifactType: 'image',
      title: 'Derivative Work',
    },
    lineage: {
      ancestors: [originalPassportId],
      derivatives: [],
      datasets: [],
    },
  });

  // Link in ledger
  await client.writeEvent({
    type: 'lineage_linked',
    identity: currentUserIdentity.id,
    payload: {
      originalPassportId,
      derivativePassportId: derivativePassport.id,
    },
  });

  return derivativePassport;
}

Platform-Specific Examples

GitHub Integration

# .github/workflows/provenance.yml
name: Verify Provenance

on:
  push:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Verify Provenance
        run: |
          # Check if code has passport
          # Verify passport
          # Evaluate rights for public repo

Figma Plugin

// Figma plugin to verify design provenance
figma.on('selectionchange', async () => {
  const selection = figma.currentPage.selection;
  
  for (const node of selection) {
    const passportId = node.getPluginData('passportId');
    
    if (passportId) {
      const passport = await client.getPassport(passportId);
      const verification = await client.verifyPassport(passportId);
      
      figma.notify(`Provenance: ${verification.valid ? 'Verified' : 'Invalid'}`);
    }
  }
});

Content Management System

// WordPress/CMS integration
async function onMediaUpload(mediaFile, passportId) {
  // Verify passport
  const verification = await client.verifyPassport(passportId);
  
  if (!verification.valid) {
    return { error: 'Invalid provenance passport' };
  }

  // Store with media
  await wp.media.create({
    file: mediaFile,
    meta: {
      passportId,
      verified: true,
    },
  });

  // Display provenance badge
  return {
    success: true,
    badge: `<div class="provenance-badge">Verified Provenance</div>`,
  };
}

Best Practices

Verify Early - Check passports on upload
Cache Results - Cache passport data for performance
Show Provenance - Display provenance badges to users
Respect Rights - Enforce rights before allowing use
Track Lineage - Link derivatives properly
Handle Errors - Gracefully handle API failures

UI Components

Provenance Badge

function ProvenanceBadge({ passportId }) {
  const [verified, setVerified] = useState(false);
  
  useEffect(() => {
    client.verifyPassport(passportId).then(result => {
      setVerified(result.valid);
    });
  }, [passportId]);

  if (!verified) return null;

  return (
    <div className="provenance-badge">
      <span>✓ Verified Provenance</span>
      <a href={`/explorer/passport/${passportId}`}>View</a>
    </div>
  );
}