QCOS Licensing Design Document

Version: 1.0 Status: APPROVED Author: SoftQuantus Engineering Date: December 2024

Executive Summary

This document describes the technical architecture for QCOS binary distribution and license management. QCOS is delivered exclusively as binary artifacts (containers, VM images, libraries) with cryptographic license enforcement.

Key Principles

Binary-Only Distribution: QCOS source code is never distributed. All deliverables are pre-compiled binaries.
Cryptographic License Enforcement: Licenses are digitally signed and verified at runtime.
Offline-First: The system works completely offline for air-gapped environments (HPC, government, defense).
Enterprise Control: Customers manage licenses through a secure portal with full audit trails.

1. Distribution Architecture

1.1 Artifact Types

Format	Use Case	Delivery
OCI Container	Cloud, Kubernetes, HPC	Registry pull or tar export
VM Image	On-prem hypervisors	Portal download
Shared Library	OEM integration	Portal download
SDK/Wheel	Development tools	Public PyPI (open)

1.2 Container Registry

Primary Registry: registry.softquantus.com

registry.softquantus.com/
├── softqcos/
│   ├── core:<version>              # QCOS Kernel + Runtime
│   ├── autopilot:<version>         # Autopilot Optimization Engine
│   ├── license-server:<version>    # On-prem license management
│   ├── benchmark-suite:<version>   # Benchmarking tools
│   └── hal-<vendor>:<version>      # Hardware Abstraction Layers
│       ├── hal-ibm
│       ├── hal-iqm
│       ├── hal-pasqal
│       ├── hal-quantinuum
│       └── hal-generic

1.3 Version Tagging

<major>.<minor>.<patch>[-<customer>]

Examples:
  1.0.0          # General release
  1.0.0-ibm      # IBM-specific build (HAL included)
  1.0.0-lts      # Long-term support

2. License File Format

2.1 Structure

Licenses are JSON files with cryptographic signatures:

{
  "version": "1.0",
  "format": "softquantus-license-v1",
  "grant": {
    "license_id": "QCOS-20241201-ABCD1234",
    "customer_id": "IBM-001",
    "customer_name": "IBM Corporation",
    "contract_id": "QSOFT-IBM-EP-2024-001",
    "product": "QCOS",
    "version": {
      "major": 1,
      "minor_min": 0,
      "minor_max": 99
    },
    "license_type": "enterprise_platform",
    "sla_tier": "platinum",
    "modules": ["kernel", "autopilot", "hal_ibm", "benchmarking"],
    "environments": ["ibm-hpc-east", "ibm-hpc-west"],
    "validity": {
      "issued_at": "2024-12-01T00:00:00Z",
      "valid_from": "2024-12-01",
      "valid_until": "2026-12-31"
    },
    "features": {
      "autopilot_enabled": true,
      "benchmark_suite_enabled": true,
      "max_qubits": 127,
      "max_backends": 20,
      "max_concurrent_jobs": 100
    }
  },
  "signature": "<base64-encoded-rsa-pss-signature>",
  "public_key_id": "a1b2c3d4e5f6"
}

2.2 Cryptography

Component	Algorithm
Key Type	RSA-4096
Signature	RSA-PSS with SHA-256
Key Storage	HSM (production)

2.3 License ID Format

QCOS-<YYYYMMDD>-<RANDOM8>

Example: QCOS-20241201-ABCD1234

3. License Enforcement

3.1 Runtime Validation Flow

┌─────────────────────────────────────────────────────────────────┐
│                       QCOS Startup                               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Load Public Key (embedded in binary or /etc/softqcos/license.pub)  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Load License File                                               │
│  - QCOS_LICENSE_FILE env var                                     │
│  - /etc/softqcos/license.lic                                         │
│  - ~/.softqcos/license.lic                                           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Verify Signature                                                │
│  - Extract grant JSON                                            │
│  - Verify RSA-PSS signature                                      │
│  - Check key ID matches embedded key                             │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
        ┌──────────┐                   ┌──────────────┐
        │ INVALID  │                   │    VALID     │
        │ → EXIT 1 │                   │              │
        └──────────┘                   └──────────────┘
                                              │
                                              ▼
                              ┌─────────────────────────────────┐
                              │  Check Validity Dates            │
                              │  - Not before valid_from        │
                              │  - Not after valid_until        │
                              └─────────────────────────────────┘
                                              │
                                              ▼
                              ┌─────────────────────────────────┐
                              │  Check Version Compatibility     │
                              │  - Major version match          │
                              │  - Minor within range           │
                              └─────────────────────────────────┘
                                              │
                                              ▼
                              ┌─────────────────────────────────┐
                              │  Check Environment (if set)      │
                              │  - Hostname in allowed list     │
                              └─────────────────────────────────┘
                                              │
                                              ▼
                              ┌─────────────────────────────────┐
                              │  Load Features & Limits          │
                              │  - max_qubits                   │
                              │  - max_backends                 │
                              │  - enabled modules              │
                              └─────────────────────────────────┘
                                              │
                                              ▼
                              ┌─────────────────────────────────┐
                              │  ✓ QCOS Ready                   │
                              └─────────────────────────────────┘

3.2 Module Enforcement

Each QCOS module checks its own license at initialization:

from licensing.client import require_module, Module

class AutopilotEngine:
    def __init__(self):
        require_module(Module.AUTOPILOT)  # Raises if not licensed
        ...

3.3 Feature Limits

Runtime enforcement of licensed limits:

def submit_job(circuit, shots):
    ctx = get_license_context()

    if circuit.num_qubits > ctx.features.max_qubits:
        raise LicenseError(f"Circuit exceeds licensed qubit limit ({ctx.features.max_qubits})")

    if shots > ctx.features.max_shots_per_job:
        raise LicenseError(f"Shots exceed licensed limit ({ctx.features.max_shots_per_job})")

4. License Server (Enterprise)

4.1 Purpose

For large deployments, customers can run a License Server inside their datacenter to:

Centralize license management
Enforce seat/concurrent usage limits
Enable license updates without redeploying QCOS

4.2 Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Customer Datacenter                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────────┐     ┌──────────────────────────────────┐  │
│  │ License Server   │     │  QCOS Nodes                      │  │
│  │ (softqcos-license-   │◄───►│  - softqcos-core                     │  │
│  │  server:1.0.0)   │     │  - softqcos-autopilot                │  │
│  │                  │     │  - softqcos-hal-ibm                  │  │
│  │  *.lic files     │     │                                  │  │
│  │  license.pub     │     │  (checkout license at startup)   │  │
│  └──────────────────┘     └──────────────────────────────────┘  │
│         │                                                        │
│         │ (no internet required)                                │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

4.3 API Endpoints

Endpoint	Method	Description
`/validate`	POST	Validate license
`/checkout`	POST	Acquire license seat
`/release`	POST	Release license seat
`/heartbeat`	POST	Maintain seat checkout
`/status/{id}`	GET	Get license status

4.4 Seat Management

License: max_concurrent_jobs = 100

┌─────────────────────────────────────────┐
│  Active Seats: 45/100                   │
├─────────────────────────────────────────┤
│  node-01  │ autopilot │ checked out 2h │
│  node-02  │ core      │ checked out 1h │
│  node-03  │ benchmark │ checked out 4h │
│  ...                                    │
└─────────────────────────────────────────┘

5. Enterprise Portal

5.1 Customer Portal

URL: https://portal.softquantus.com

Features:

View contracts and products
Download license files
Access release artifacts
Generate registry credentials
View usage/audit logs

5.2 Portal Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    SoftQuantus Cloud                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────────────┐ │
│  │   Portal UI  │   │  Portal API  │   │  Container Registry  │ │
│  │  (React/Vue) │──►│  (FastAPI)   │──►│  (registry.soft...)  │ │
│  └──────────────┘   └──────────────┘   └──────────────────────┘ │
│                            │                       │             │
│                            ▼                       ▼             │
│                     ┌──────────────┐   ┌──────────────────────┐ │
│                     │  License DB  │   │  Artifact Storage    │ │
│                     │  (Postgres)  │   │  (Azure Blob/S3)     │ │
│                     └──────────────┘   └──────────────────────┘ │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

5.3 Authentication

SSO integration (Azure AD, Okta, etc.)
Per-customer user management
Role-based access (admin, download-only, view-only)

6. Delivery Workflow

6.1 New Customer Onboarding

1. Contract Signed
      │
      ▼
2. Create Customer in Portal
   - customer_id: IBM-001
   - tier: enterprise
   - contacts
      │
      ▼
3. Create Contract Record
   - contract_id: QSOFT-IBM-EP-2024-001
   - products: [QCOS-EP, QCOS-BENCH]
   - modules: [kernel, autopilot, hal_ibm, benchmarking]
   - term: 2024-2026
      │
      ▼
4. Generate License
   - Run: softqcos-license generate --customer-id IBM-001 ...
   - Output: IBM_qcos_enterprise_2024.lic
      │
      ▼
5. Upload License to Portal
   - Customer can download from portal
      │
      ▼
6. Generate Registry Credentials
   - Customer receives docker login command
      │
      ▼
7. Customer Deploys QCOS
   - Pull images or load tars
   - Mount license file
   - Start services

6.2 Air-Gapped Delivery

For environments without internet:

1. Package Artifacts
   $ ./scripts/build_binaries.sh package IBM kernel,autopilot,hal_ibm

   Output: dist/customers/IBM/
   ├── softqcos-core-1.0.0.tar.gz
   ├── softqcos-license-server-1.0.0.tar.gz
   ├── softqcos-hal-ibm-1.0.0.tar.gz
   ├── MANIFEST.json
   ├── SHA256SUMS
   └── install.sh

2. Secure Transfer
   - USB/physical media
   - Secure file transfer
   - VPN upload to customer

3. Customer Installation
   $ ./install.sh
   → docker load -i softqcos-core-1.0.0.tar.gz
   → docker load -i softqcos-license-server-1.0.0.tar.gz
   ...

4. License Activation
   - Copy license.lic to /etc/softqcos/
   - Copy license.pub to /etc/softqcos/
   - Start services

7. Security Considerations

7.1 Key Management

Key	Location	Access
Private Key	HSM / Secure Vault	License Authority only
Public Key	Embedded in binaries	All QCOS instances

7.2 License File Security

Licenses are signed, not encrypted (contents are readable)
Customer-specific data (limits, modules) is visible
Financial terms are never in license files
Signature prevents tampering

7.3 Binary Protection

Binaries are not obfuscated (standard Python wheel/containers)
Protection is through license enforcement, not obscurity
All critical paths check license validity
Consider PyInstaller/Nuitka for additional compilation in future

7.4 Audit Trail

Portal and License Server log:

License generation events
Download events
Checkout/release events
Authentication events

8. Operations

8.1 License Revocation

To revoke a license:

Mark license as revoked in portal database
If customer uses License Server:
- Push updated license file to customer
- License Server reloads and rejects revoked license
If customer uses local file:
- Next version of QCOS checks revocation list (future)
- Or: wait for expiry

8.2 License Renewal

1. Customer contract renewed
      │
      ▼
2. Generate new license with extended validity
   - Same license_id prefix
   - New valid_until date
      │
      ▼
3. Customer downloads new .lic file
      │
      ▼
4. Customer replaces old file or reloads License Server

8.3 Version Upgrades

Major Version (1.x → 2.x):
  - May require new license with version.major = 2
  - Commercial upgrade discussion

Minor Version (1.0 → 1.5):
  - Works if version_minor_max >= 5
  - No license change needed

Patch Version (1.0.0 → 1.0.5):
  - Always compatible
  - No license change needed

9. Implementation Status

Phase 1 (Current) ✅

License file format definition
License Authority (signing)
License Validator (verification)
CLI tool for license generation
Basic runtime validation

Phase 2 (Q1 2025)

License Server deployment
Portal backend API
Container registry setup
Customer onboarding workflow

Phase 3 (Q2 2025)

Portal frontend UI
SSO integration
Usage analytics
Revocation list support

10. Appendix

A. Environment Variables

Variable	Description	Default
`QCOS_LICENSE_FILE`	Path to license file	`/etc/softqcos/license.lic`
`QCOS_LICENSE_PUBLIC_KEY`	Path to public key	`/etc/softqcos/license.pub`
`QCOS_LICENSE_SERVER`	License server URL	(none)
`QCOS_LICENSE_ID`	License ID for server mode	(none)
`QCOS_LICENSE_API_TOKEN`	API token for server	(none)
`QCOS_ENVIRONMENT`	Environment name	hostname
`QCOS_VERSION_MAJOR`	Major version	1
`QCOS_VERSION_MINOR`	Minor version	0

B. File Locations

/etc/softqcos/
├── license.lic          # License file
├── license.pub          # Public key
└── licenses/            # For License Server: multiple licenses

~/.softqcos/
├── license.lic          # User-level license (fallback)
└── license.pub          # User-level public key (fallback)

C. Error Messages

Error	Cause	Solution
"Invalid license signature"	Tampering or wrong key	Redownload license
"License expired"	Past valid_until	Renew contract
"License not yet valid"	Before valid_from	Wait or check date
"Version mismatch"	QCOS version not covered	Upgrade license or downgrade QCOS
"Module not licensed"	Using unlicensed feature	Upgrade license
"All seats in use"	Concurrent limit reached	Release other seats or upgrade

Document History

Version	Date	Author	Changes
1.0	2024-12-09	Engineering	Initial release

Executive Summary​

Key Principles​

1. Distribution Architecture​

1.1 Artifact Types​

1.2 Container Registry​

1.3 Version Tagging​

2. License File Format​

2.1 Structure​

2.2 Cryptography​

2.3 License ID Format​

3. License Enforcement​

3.1 Runtime Validation Flow​

3.2 Module Enforcement​

3.3 Feature Limits​

4. License Server (Enterprise)​

4.1 Purpose​

4.2 Architecture​

4.3 API Endpoints​

4.4 Seat Management​

5. Enterprise Portal​

5.1 Customer Portal​

5.2 Portal Architecture​

5.3 Authentication​

6. Delivery Workflow​

6.1 New Customer Onboarding​

6.2 Air-Gapped Delivery​

7. Security Considerations​

7.1 Key Management​

7.2 License File Security​

7.3 Binary Protection​

7.4 Audit Trail​

8. Operations​

8.1 License Revocation​

8.2 License Renewal​

8.3 Version Upgrades​

9. Implementation Status​

Phase 1 (Current) ✅​

Phase 2 (Q1 2025)​

Phase 3 (Q2 2025)​

10. Appendix​

A. Environment Variables​

B. File Locations​

C. Error Messages​

Document History​