# NimPak License & Compliance Framework

The NimPak system implements a pragmatic, scalable approach to license compliance and verification that operates at the system and environment level rather than requiring individual package verification endpoints.

## Overview

**Why not individual package verification?**
- Individual URL endpoints for every package would create excessive management overhead and "domain spam"
- Per-package verification is inefficient, slow, and doesn't scale
- Compliance verification should be practical, clear, and simple to execute without unnecessary burden

## Recommended Approach: System-Level Proof of Compliance

Instead of verifying each package individually, we establish compliance verification at higher levels:

### 1. System-Wide (OS-Level) Compliance

An entire **NexusOS system** (compiled image, ISO, or container) has **a single, deterministic hash verification**.

The OS-wide hash verification encompasses:
- All installed packages
- All associated ACUL manifests and license information
- Complete build and configuration history (`build.log`)

**Advantage:** Simple compliance proof for a complete system in a single step.

**Example OS-Level Compliance:**

```kdl
system "NexusOS Secure Edition" {
  version "2025.07"
  compliance {
    acul {
      manifest_hash "blake2b-abcdef1234567890..."
      verification_url "https://verify.nexusos.nexus/systems/abcdef1234567890"
    }
  }
}
```

### 2. NexusCell-Level Compliance (User Environments)

Similarly, a single hash verification applies per **NexusCell** (isolated user environment):

- Each cell (e.g., "Developer Tools Cell") receives an individual, deterministic compliance verification
- No separate package-level verifications needed

**Advantage:** Clear compliance boundaries per user environment, perfect for enterprise and multi-user scenarios.

**Example Cell-Level Compliance:**

```kdl
cell "Developer Tools Cell" {
  owner "user123"
  compliance {
    acul {
      manifest_hash "blake2b-0987654321fedcba..."
      verification_url "https://verify.nexusos.nexus/cells/0987654321fedcba"
    }
  }
}
```

## Compliance Verification Workflow

### 1. Manifest Generation
The manifest (`license.kdl`) is generated once during system or cell build, including a deterministic hash over all relevant data:
- Packages (`.npk`)
- License data
- Build logs

### 2. URL-Based Verification (Meta-Level)
A central URL verifies hash correctness and provides simple compliance information.

**Example:**
```
GET https://verify.nexusos.nexus/systems/abcdef1234567890

Response:
{
  "system_name": "NexusOS Secure Edition",
  "version": "2025.07",
  "compliance_status": "✅ ACUL compliant",
  "manifest_hash": "blake2b-abcdef1234567890...",
  "timestamp": "2025-07-20T12:00:00Z",
  "foundation_membership": "Gold"
}
```

### 3. Simplified Audit Process
- Organizations need only publish this single URL + hash
- Auditors verify complete system compliance with minimal effort

## Technical Implementation

| Component | Responsibility |
|-----------|----------------|
| `nip build` | Generates deterministic hashes & compliance manifests |
| `nip verify` | Verifies ACUL compliance at OS and cell level |
| `verify.nexusos.nexus` | Central endpoint for compliance queries |
| `nip manifest` | Creates license & compliance manifest (`license.kdl`) |

## Complete Compliance Manifest Example

```kdl
license {
  type "ACUL"
  version "1.0"
  foundation_membership "Gold"
  attribution "© 2025 Maiwald Systems / NexusOS Project"

  reproducibility {
    npk_logs true
    reproducible_build true
  }

  scope "system" // or 'cell'
  system_id "nexusos-secure-edition-202507"
  manifest_hash "blake2b-abcdef1234567890..."
  verification_url "https://verify.nexusos.nexus/systems/abcdef1234567890"
}
```

## Individual Package Handling

Individual packages remain:
- Cryptographically verified with ACUL information
- Locally verifiable with `nip verify <package.npk>`
- Auditable on-demand (security review) via local or internal systems - **but not publicly under a domain**

**No domain spam risk. No unnecessary public individual verification.**

## Implementation Roadmap

- [ ] Implement **system and cell-wide compliance manifests** in `nip build`
- [ ] Set up central, simple endpoint (`verify.nexusos.nexus`) for meta-level compliance
- [ ] Create clear documentation & workflow description for auditors & enterprise users
- [ ] Update license manifest template (`license.kdl`) according to this structure
- [ ] Test complete solution pragmatically with initial exemplary systems and cells

## Benefits

- 🚀 **Scalable:** Only a few, well-managed compliance URLs
- 🔍 **Audit-friendly:** Simple verification, reduced effort
- 🛡️ **Robust & Secure:** Provably deterministic compliance at the highest level
- 🧹 **Clean domains:** No unnecessary load, no "package spam"

This approach fulfills requirements for clarity, simplicity, and pragmatism without compromising security and compliance.