Skip to content

INTEGRATION.md

Latest commit

 

History

History
435 lines (344 loc) · 8.61 KB

INTEGRATION.md

File metadata and controls

435 lines (344 loc) · 8.61 KB
Raw

Palimpsest-MPL Integration Guide

Overview

This guide covers integrating PMPL-1.0 (SPDX: PMPL-1.0-or-later) into your development workflow, CI/CD pipelines, and compliance systems.

File Headers

Standard Header

For most source files:

// SPDX-License-Identifier: PMPL-1.0-or-later
// SPDX-FileCopyrightText: 2025 Your Name <email@example.com>

Multi-line Header (with context)

For files with significant creative content:

// SPDX-License-Identifier: PMPL-1.0-or-later
// SPDX-FileCopyrightText: 2025 Your Name <email@example.com>
//
// Emotional Lineage: [Brief description of cultural/narrative context]
// See LINEAGE.md for full provenance

Language-Specific Headers

Rust:

// SPDX-License-Identifier: PMPL-1.0-or-later
// SPDX-FileCopyrightText: 2025 Author Name

Python:

# SPDX-License-Identifier: PMPL-1.0-or-later
# SPDX-FileCopyrightText: 2025 Author Name

HTML:

<!-- SPDX-FileCopyrightText: 2025 Author Name -->

Shell:

#!/usr/bin/env bash
# SPDX-License-Identifier: PMPL-1.0-or-later
# SPDX-FileCopyrightText: 2025 Author Name

CI/CD Integration

GitHub Actions

# .github/workflows/license-check.yml
name: License Compliance

on: [push, pull_request]

jobs:
  check-headers:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check SPDX headers
        run: |
          # Find files missing SPDX headers
          find src -name "*.rs" -type f | while read file; do
            if ! head -5 "$file" | grep -q "SPDX-License-Identifier"; then
              echo "Missing SPDX header: $file"
              exit 1
            fi
          done

  verify-provenance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install pmpl-verify
        run: cargo install pmpl-verify

      - name: Verify signatures
        run: pmpl-verify --recursive src/

GitLab CI

# .gitlab-ci.yml
license-compliance:
  stage: test
  image: rust:latest
  script:
    - cargo install pmpl-audit
    - pmpl-audit .
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

provenance-check:
  stage: test
  image: rust:latest
  script:
    - cargo install pmpl-verify
    - pmpl-verify --recursive src/
  allow_failure: true  # Signatures are optional

GitLoom Integration

# .gitloom/compliance.toml
[license]
type = "Palimpsest-MPL-1.0"
exhibits = ["ethical-use", "quantum-safe"]

[checks]
require_spdx_headers = true
require_signatures = false  # Set true for strict mode
verify_on_commit = true

[provenance]
algorithm = "ML-DSA-65"
key_path = "~/.pmpl/signing-key.pem"

Package Managers

Cargo (Rust)

# Cargo.toml
[package]
name = "your-project"
version = "1.0.0"
license = "PMPL-1.0"
license-file = "LICENSE"

[package.metadata.pmpl]
exhibits = ["ethical-use", "quantum-safe"]
provenance = true

Deno

{
  "name": "@your-scope/your-project",
  "version": "1.0.0",
  "license": "PMPL-1.0",
  "exports": "./mod.ts"
}

Mix (Elixir)

# mix.exs
defmodule YourProject.MixProject do
  use Mix.Project

  def project do
    [
      app: :your_project,
      version: "1.0.0",
      licenses: ["PMPL-1.0"],
      files: ~w(lib priv LICENSE mix.exs README.md)
    ]
  end
end

Provenance Signing

Initial Setup

# Generate a quantum-safe key pair
pmpl-keygen --algorithm ML-DSA-65 --output ~/.pmpl/

# Publish your public key
pmpl-publish-key --key ~/.pmpl/public.pem --to keys.pmpl.dev

Signing Commits

# Sign all modified files in a commit
git diff --name-only HEAD~1 | xargs pmpl-sign --key ~/.pmpl/private.pem

# Or use git hook
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
git diff --cached --name-only | xargs pmpl-sign --key ~/.pmpl/private.pem
git add $(git diff --cached --name-only | sed 's/$/.sig/')
EOF
chmod +x .git/hooks/pre-commit

Verifying Signatures

# Verify a single file
pmpl-verify src/main.rs

# Verify entire repository
pmpl-verify --recursive .

# Verify with specific trust anchors
pmpl-verify --trust-anchor keys/trusted-signers.pem --recursive .

SBOM (Software Bill of Materials)

SPDX Document

{
  "spdxVersion": "SPDX-2.3",
  "dataLicense": "CC0-1.0",
  "SPDXID": "SPDXRef-DOCUMENT",
  "name": "your-project-sbom",
  "packages": [
    {
      "SPDXID": "SPDXRef-Package",
      "name": "your-project",
      "versionInfo": "1.0.0",
      "licenseConcluded": "PMPL-1.0",
      "licenseDeclared": "PMPL-1.0",
      "externalRefs": [
        {
          "referenceCategory": "SECURITY",
          "referenceType": "pmpl-provenance",
          "referenceLocator": "https://your-project.dev/.well-known/pmpl-provenance.json"
        }
      ]
    }
  ]
}

CycloneDX

<?xml version="1.0" encoding="UTF-8"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.5">
  <metadata>
    <component type="application">
      <name>your-project</name>
      <version>1.0.0</version>
      <licenses>
        <license>
          <id>PMPL-1.0</id>
          <url>https://github.com/hyperpolymath/palimpsest-license/blob/main/legal/PALIMPSEST-MPL-1.0.txt</url>
        </license>
      </licenses>
    </component>
  </metadata>
</bom>

Web Integration

Well-Known Files

# .well-known/pmpl-license.json
{
  "license": "PMPL-1.0",
  "version": "1.0.0",
  "license_url": "https://github.com/hyperpolymath/palimpsest-license",
  "provenance": {
    "enabled": true,
    "algorithm": "ML-DSA-65",
    "public_key": "https://your-project.dev/.well-known/pmpl-public-key.pem"
  }
}

Meta Tags

<head>
  <meta name="license" content="PMPL-1.0">
  <link rel="license" href="/LICENSE">
  <meta name="pmpl:provenance" content="https://your-project.dev/.well-known/pmpl-provenance.json">
</head>

Container Images

Dockerfile Labels

FROM rust:1.75-slim

LABEL org.opencontainers.image.licenses="PMPL-1.0"
LABEL org.opencontainers.image.source="https://github.com/your-org/your-project"
LABEL dev.pmpl.provenance="enabled"
LABEL dev.pmpl.algorithm="ML-DSA-65"

COPY LICENSE /licenses/PALIMPSEST-MPL-1.0.txt
COPY legal/exhibits/ /licenses/exhibits/

Wolfi/apk

# melange.yaml
package:
  name: your-package
  version: 1.0.0
  copyright:
    - license: PMPL-1.0
      paths:
        - "*"

IDE Integration

VS Code

// .vscode/settings.json
{
  "files.insertFinalNewline": true,
  "editor.formatOnSave": true,
  "pmpl.headerTemplate": "// SPDX-License-Identifier: PMPL-1.0\n// SPDX-FileCopyrightText: ${YEAR} ${AUTHOR}",
  "pmpl.autoSign": false
}

JetBrains IDEs

<!-- .idea/copyright/PMPL.xml -->
<component name="CopyrightManager">
  <copyright>
    <option name="notice" value="SPDX-License-Identifier: PMPL-1.0&#10;SPDX-FileCopyrightText: $today.year $username"/>
  </copyright>
</component>

Compliance Automation

Pre-commit Hooks

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: spdx-headers
        name: Check SPDX headers
        entry: scripts/check-spdx-headers.sh
        language: script
        types: [file]

      - id: pmpl-sign
        name: Sign modified files
        entry: pmpl-sign --key ~/.pmpl/private.pem
        language: system
        types: [file]
        stages: [commit]

Justfile Recipes

# Justfile

# Check all files have proper SPDX headers
check-headers:
    @find src -name "*.rs" -exec grep -L "SPDX-License-Identifier" {} \; | \
        xargs -I {} echo "Missing header: {}"

# Sign all source files
sign-all:
    find src -name "*.rs" -exec pmpl-sign --key ~/.pmpl/private.pem {} \;

# Verify all signatures
verify:
    pmpl-verify --recursive src/

# Full compliance check
compliance: check-headers verify
    @echo "Compliance check passed"

# Generate SBOM
sbom:
    pmpl-sbom --format spdx --output sbom.json

Troubleshooting

Common Issues

Missing SPDX headers:

# Find files without headers
find . -name "*.rs" -type f ! -path "./target/*" | \
  xargs grep -L "SPDX-License-Identifier"

Invalid signatures:

# Check signature validity
pmpl-verify --verbose file.rs

# Resign with updated key
pmpl-sign --force --key ~/.pmpl/private.pem file.rs

Key not found:

# Check key publication
curl -s https://keys.pmpl.dev/lookup?fingerprint=YOUR_KEY_FP

Support