CyberRanger/identity/claude/classified/RANGERBLOCK_REGISTRATION_CONTRACTS_PLAN.md

RANGERBLOCK REGISTRATION & CONSENT BLOCKCHAIN SYSTEM

Project Codename: "SENTINEL PROTOCOL"

Version 1.0.0 - December 4, 2025

---

CLASSIFICATION: PRIVATE

DO NOT COMMIT TO PUBLIC GIT

---

1. EXECUTIVE SUMMARY

The Vision

When a user:

1. Creates identity (hardware-bound)
2. Accepts Terms of Use (18+, content policy, etc.)

A REGISTRATION BLOCK is created on the RangerBlock blockchain, providing:

• Immutable proof of acceptance
• Cryptographic signature
• Admin notification for approval
• Privilege assignment upon approval

Components Needed

Component	Purpose	Location
RegistrationBlock.sol	Solidity contract for EVM chains	Blockchain/contracts/
registration-service.cjs	Node.js registration handler	rangerblock/lib/
consent-service.cjs	Consent/terms handler	rangerblock/lib/
Admin integration	View/approve registrations	~/.claude/ranger/admin/

Apps Covered

• ranger-chat-lite (Electron)
• just-chat (Terminal)
• server-only (Server deployment)
• RangerPlex (Full browser)

---

2. REGISTRATION BLOCK STRUCTURE

2.1 Solidity Contract (Remix Standard)

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

/**
 * @title RangerRegistration
 * @dev User registration and consent tracking for RangerBlock
 * @author David Keane (IrishRanger) + Claude Code (Ranger)
 */
contract RangerRegistration {

    // ========================================================================
    // STRUCTURES
    // ========================================================================

    struct Registration {
        bytes32 userIdHash;           // SHA256 of userId
        bytes32 publicKeyHash;        // SHA256 of RSA public key
        bytes32 hardwareIdHash;       // SHA256 of hardware fingerprint
        string username;              // Display name
        string appType;               // ranger-chat-lite, just-chat, etc.

        // Consent
        string termsVersion;          // "1.0.0"
        bytes32 termsHash;            // SHA256 of terms text
        bytes signature;              // RSA signature of consent

        // Timestamps
        uint256 registeredAt;         // Block timestamp
        uint256 consentedAt;          // When terms accepted

        // Status
        RegistrationStatus status;    // pending, approved, denied, revoked
        string statusReason;          // Reason for status change

        // Admin
        address approvedBy;           // Admin who approved
        uint256 approvedAt;           // Approval timestamp
    }

    enum RegistrationStatus {
        PENDING,
        APPROVED,
        DENIED,
        REVOKED
    }

    // ========================================================================
    // STATE
    // ========================================================================

    address public owner;
    address public supremeAdmin;

    mapping(bytes32 => Registration) public registrations;  // userIdHash => Registration
    mapping(bytes32 => bool) public hardwareUsed;           // hardwareIdHash => used
    bytes32[] public registrationList;                      // All registration IDs

    uint256 public totalRegistrations;
    uint256 public pendingCount;
    uint256 public approvedCount;
    uint256 public deniedCount;

    // ========================================================================
    // EVENTS
    // ========================================================================

    event RegistrationSubmitted(
        bytes32 indexed userIdHash,
        string username,
        string appType,
        uint256 timestamp
    );

    event RegistrationApproved(
        bytes32 indexed userIdHash,
        address approvedBy,
        uint256 timestamp
    );

    event RegistrationDenied(
        bytes32 indexed userIdHash,
        address deniedBy,
        string reason,
        uint256 timestamp
    );

    event RegistrationRevoked(
        bytes32 indexed userIdHash,
        address revokedBy,
        string reason,
        uint256 timestamp
    );

    event ConsentRecorded(
        bytes32 indexed userIdHash,
        string termsVersion,
        bytes32 termsHash,
        uint256 timestamp
    );

    // ========================================================================
    // MODIFIERS
    // ========================================================================

    modifier onlyOwner() {
        require(msg.sender == owner || msg.sender == supremeAdmin, "Not authorized");
        _;
    }

    modifier onlyAdmin() {
        require(msg.sender == owner || msg.sender == supremeAdmin, "Not admin");
        _;
    }

    // ========================================================================
    // CONSTRUCTOR
    // ========================================================================

    constructor(address _supremeAdmin) {
        owner = msg.sender;
        supremeAdmin = _supremeAdmin;
    }

    // ========================================================================
    // REGISTRATION FUNCTIONS
    // ========================================================================

    /**
     * @dev Submit a new registration with consent
     */
    function register(
        bytes32 userIdHash,
        bytes32 publicKeyHash,
        bytes32 hardwareIdHash,
        string memory username,
        string memory appType,
        string memory termsVersion,
        bytes32 termsHash,
        bytes memory signature
    ) public returns (bool) {
        // Check hardware not already used (prevents ban evasion)
        require(!hardwareUsed[hardwareIdHash], "Hardware already registered");

        // Check not already registered
        require(registrations[userIdHash].registeredAt == 0, "Already registered");

        // Create registration
        Registration storage reg = registrations[userIdHash];
        reg.userIdHash = userIdHash;
        reg.publicKeyHash = publicKeyHash;
        reg.hardwareIdHash = hardwareIdHash;
        reg.username = username;
        reg.appType = appType;
        reg.termsVersion = termsVersion;
        reg.termsHash = termsHash;
        reg.signature = signature;
        reg.registeredAt = block.timestamp;
        reg.consentedAt = block.timestamp;
        reg.status = RegistrationStatus.PENDING;

        // Mark hardware as used
        hardwareUsed[hardwareIdHash] = true;

        // Add to list
        registrationList.push(userIdHash);
        totalRegistrations++;
        pendingCount++;

        emit RegistrationSubmitted(userIdHash, username, appType, block.timestamp);
        emit ConsentRecorded(userIdHash, termsVersion, termsHash, block.timestamp);

        return true;
    }

    /**
     * @dev Approve a pending registration (admin only)
     */
    function approve(bytes32 userIdHash) public onlyAdmin {
        Registration storage reg = registrations[userIdHash];
        require(reg.registeredAt > 0, "Registration not found");
        require(reg.status == RegistrationStatus.PENDING, "Not pending");

        reg.status = RegistrationStatus.APPROVED;
        reg.approvedBy = msg.sender;
        reg.approvedAt = block.timestamp;

        pendingCount--;
        approvedCount++;

        emit RegistrationApproved(userIdHash, msg.sender, block.timestamp);
    }

    /**
     * @dev Deny a pending registration (admin only)
     */
    function deny(bytes32 userIdHash, string memory reason) public onlyAdmin {
        Registration storage reg = registrations[userIdHash];
        require(reg.registeredAt > 0, "Registration not found");
        require(reg.status == RegistrationStatus.PENDING, "Not pending");

        reg.status = RegistrationStatus.DENIED;
        reg.statusReason = reason;

        pendingCount--;
        deniedCount++;

        emit RegistrationDenied(userIdHash, msg.sender, reason, block.timestamp);
    }

    /**
     * @dev Revoke an approved registration (admin only)
     */
    function revoke(bytes32 userIdHash, string memory reason) public onlyAdmin {
        Registration storage reg = registrations[userIdHash];
        require(reg.registeredAt > 0, "Registration not found");
        require(reg.status == RegistrationStatus.APPROVED, "Not approved");

        reg.status = RegistrationStatus.REVOKED;
        reg.statusReason = reason;

        approvedCount--;

        emit RegistrationRevoked(userIdHash, msg.sender, reason, block.timestamp);
    }

    // ========================================================================
    // VIEW FUNCTIONS
    // ========================================================================

    function getRegistration(bytes32 userIdHash) public view returns (
        string memory username,
        string memory appType,
        string memory termsVersion,
        RegistrationStatus status,
        uint256 registeredAt,
        uint256 approvedAt
    ) {
        Registration storage reg = registrations[userIdHash];
        return (
            reg.username,
            reg.appType,
            reg.termsVersion,
            reg.status,
            reg.registeredAt,
            reg.approvedAt
        );
    }

    function isApproved(bytes32 userIdHash) public view returns (bool) {
        return registrations[userIdHash].status == RegistrationStatus.APPROVED;
    }

    function isPending(bytes32 userIdHash) public view returns (bool) {
        return registrations[userIdHash].status == RegistrationStatus.PENDING;
    }

    function getPendingCount() public view returns (uint256) {
        return pendingCount;
    }

    function getStats() public view returns (
        uint256 total,
        uint256 pending,
        uint256 approved,
        uint256 denied
    ) {
        return (totalRegistrations, pendingCount, approvedCount, deniedCount);
    }
}

---

3. NODE.JS INTEGRATION

3.1 Registration Block (JSON Format for RangerBlock P2P)

For our custom blockchain (non-EVM), registrations are blocks:

// Registration block structure
const registrationBlock = {
    type: 'USER_REGISTRATION',
    version: '1.0.0',

    // Identity (hashed for privacy)
    identity: {
        userIdHash: 'sha256_of_rb_xxx',
        publicKeyHash: 'sha256_of_public_key',
        hardwareIdHash: 'sha256_of_hardware_fingerprint',
        username: 'SwiftRanger',
        appType: 'ranger-chat-lite'
    },

    // Consent record
    consent: {
        termsVersion: '1.0.0',
        termsHash: 'sha256_of_terms_text',
        acceptedAt: '2025-12-04T10:30:00.000Z',
        ageConfirmed: true,  // User confirmed 18+
        signature: 'RSA_signature_of_consent'
    },

    // Block metadata
    metadata: {
        timestamp: '2025-12-04T10:30:05.000Z',
        previousHash: 'abc123...',
        nonce: 12345,
        minedBy: 'relay_node_id'
    },

    // Status (updated by admin)
    status: {
        current: 'pending',  // pending, approved, denied, revoked
        updatedAt: null,
        updatedBy: null,
        reason: null
    }
};

3.2 Registration Service (registration-service.cjs)

// Location: rangerblock/lib/registration-service.cjs

class RegistrationService {
    constructor(identityService, consentService) {
        this.identity = identityService;
        this.consent = consentService;
    }

    // Create registration block
    async createRegistrationBlock() { }

    // Submit to relay (goes to admin queue)
    async submitRegistration(block) { }

    // Check registration status
    async checkStatus(userId) { }

    // Handle approval notification
    onApproved(callback) { }

    // Handle denial notification
    onDenied(callback) { }
}

---

4. ADMIN INTEGRATION

4.1 Admin Dashboard Updates

New "Registrations" Tab:

┌─────────────────────────────────────────────────────────────────┐
│ PENDING REGISTRATIONS (3)                                       │
├───────┬──────────────┬─────────────────┬───────────┬───────────┤
│ #     │ Username     │ App             │ Date      │ Actions   │
├───────┼──────────────┼─────────────────┼───────────┼───────────┤
│ 1     │ SwiftRanger  │ ranger-chat-lite│ Dec 4     │ [A] [D]   │
│ 2     │ StormWolf    │ just-chat       │ Dec 4     │ [A] [D]   │
│ 3     │ NightHawk    │ just-chat       │ Dec 4     │ [A] [D]   │
└───────┴──────────────┴─────────────────┴───────────┴───────────┘

[A] = Approve   [D] = Deny   [V] = View Details

Registration Details (SwiftRanger):
─────────────────────────────────────
User ID:      rb_abc123...
Hardware:     M4Max-xxx (masked)
App:          ranger-chat-lite
Registered:   2025-12-04 10:30:05
Terms:        v1.0.0 (18+ accepted)
Signature:    ✓ Valid
Status:       PENDING

[A]pprove  [D]eny  [B]ack

4.2 Admin Registry Updates

Add to admin-registry.cjs:

// Registration queue management
getPendingRegistrations() { }
approveRegistration(userIdHash, adminId) { }
denyRegistration(userIdHash, adminId, reason) { }
revokeRegistration(userIdHash, adminId, reason) { }

// Consent verification
verifyConsent(userIdHash) { }
getConsentRecord(userIdHash) { }

---

5. APP INTEGRATION FLOW

5.1 ranger-chat-lite Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  App Start  │────>│   Check     │────>│   Show      │
│             │     │  Identity   │     │ Terms Modal │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                    ┌──────────────────────────┘
                    │ User Accepts
                    v
              ┌─────────────┐     ┌─────────────┐
              │  Sign       │────>│  Submit to  │
              │  Consent    │     │  Relay      │
              └─────────────┘     └──────┬──────┘
                                         │
                    ┌────────────────────┘
                    v
              ┌─────────────┐
              │ PENDING     │ <── Limited features
              │ status      │     (view only)
              └──────┬──────┘
                     │
        ┌────────────┴────────────┐
        v                         v
  ┌───────────┐           ┌───────────────┐
  │ APPROVED  │           │    DENIED     │
  │ Full      │           │ Show reason,  │
  │ access    │           │ exit app      │
  └───────────┘           └───────────────┘

5.2 just-chat Flow

Same flow but terminal-based:

1. First run → Show terms in terminal
2. User types 'y' to accept
3. Consent signed and submitted
4. Status: PENDING (can view chat, can't send)
5. When approved → Full access
6. When denied → Exit with message

5.3 server-only Flow

Server operators get different terms:

1. Setup script shows server terms
2. Operator accepts
3. Server registration submitted
4. Admin approves server node
5. Server can join network

---

6. PRIVILEGE SYSTEM

6.1 Status-Based Privileges

Status	Chat	Voice	Files	DM	Channels
PENDING	View	No	No	No	View
APPROVED	Full	Full	Full	Full	Full
DENIED	No	No	No	No	No
REVOKED	No	No	No	No	No

6.2 Implementation

// In each app's message handler
if (registrationStatus !== 'APPROVED') {
    if (registrationStatus === 'PENDING') {
        showNotification('Registration pending admin approval. View-only mode.');
        return false;  // Can't send
    } else {
        showError('Access denied. Contact admin.');
        exitApp();
    }
}

---

7. FILES TO CREATE

File	Location	Purpose
RangerRegistration.sol	Blockchain/contracts/	Solidity contract
registration-service.cjs	rangerblock/lib/	Node.js registration
consent-service.cjs	rangerblock/lib/	Consent management
Admin dashboard updates	~/.claude/ranger/admin/	Registration queue UI

---

8. IMPLEMENTATION PHASES

Phase 1: Core Infrastructure (This Week)

• Create RangerRegistration.sol
• Create registration-service.cjs
• Create consent-service.cjs
• Test locally

Phase 2: Admin Integration (Next Week)

• Add registration queue to admin-registry.cjs
• Add Registrations tab to admin-dashboard.cjs
• Test approve/deny flow

Phase 3: App Integration (Week 3)

• Integrate into ranger-chat-lite
• Integrate into just-chat
• Integrate into server-only setup
• Test end-to-end

Phase 4: Testing (Week 4)

• Test on MSI Vector
• Test on AWS
• Security review
• Deploy to production

---

9. SECURITY NOTES

What Admin Can See:

• Username
• App type
• Registration date
• Terms version accepted
• Signature validity
• Hardware ID (hashed, for ban enforcement)

What Admin CANNOT See:

• Full userId (only hash)
• Full hardware fingerprint
• Private key
• Message content

Hardware Ban Enforcement:

• Hardware ID hashed but tracked
• If banned user creates new identity, same hardware = blocked
• Admin can see "hardware previously used by banned user"

---

Document Status: READY FOR IMPLEMENTATION Created: December 4, 2025 Author: Claude Code (Ranger) for David Keane (IrishRanger)

Rangers lead the way!