DataHandler.DataRequest

DataRequest was originally built with XRUIOS in mind. It gives a group of related apps a safe and organized way to share user data on the same device without blindly trusting each other.

Think of it as a zero-trust foundation for multi-app setups:

  • It sets up a standard folder structure everyone follows.
  • It creates a cryptographic "root of trust" using post-quantum signatures to make sure nothing has been tampered with.
  • It lets you define permission tiers (like employee / manager / admin levels) so apps only get the access they need.
  • It can register approved apps and blacklist bad ones.
  • It includes a full user account system: secure password storage (Argon2), encrypted session tokens, automatic expiry with sliding renewal, tampering checks, and even a recovery system with rate-limiting.

Apps don’t talk to each other directly or send live "requests." Instead, they read and write encrypted JSON files in shared, access-controlled folders. Everything important (sessions, tiers, paths) is checked and validated before use.

In short, DataRequest makes it easy to build a secure ecosystem where multiple apps feel like one cohesive experience — while staying locked down and verifiable behind the scenes.

DirectoryData

Immutable data structure representing the standardized directory hierarchy for a secure application ecosystem. Generated via GetPaths for consistency across apps.

Property Type Description
CompanyPath string Root path under %LOCALAPPDATA%/{author} (e.g., %LOCALAPPDATA%/Zakstar).
MainServicePath string Service-level path (e.g., %LOCALAPPDATA%/Zakstar/GunGaleOnline).
ServiceParent string Parent service name (e.g., "GunGaleOnline").
Author string Developer/author identifier (e.g., "Zakstar").
Software string Specific software/app name (e.g., "TournamentOfBullets").
UserSharedResources string Shared resources folder for cross-app data (e.g., .../UserSharedResources).
UserFolder string User-specific folder (e.g., .../{identifier}).
ExePath string Full path to the executable (resolved via GetExecutablePathAsync).
Program string Program name (e.g., executable basename).

Constructors:

  • DirectoryData() { } — Default for deserialization.
  • DirectoryData(string companyPath, string mainServicePath, string serviceParent, string author, string software, string userSharedResources, string userFolder, string exePath, string program)

Usage Note: Paths follow a hierarchical structure: Company/Author/ServiceParent/Software/[UserSharedResources|UserFolder]. Ensures isolation while allowing controlled sharing.

EncryptedTier

Data structure for storing tiered access passwords with encryption and post-quantum signatures. Used in "Data Tiers.json" for RBAC (role-based access control).

Property Type Description
SignedEncryptedTier byte[] Signature of the tier identifier (e.g., "0" for admin tier).
EncryptedTierPass string Tier password encrypted under the system public key.
SignedTierPass byte[] Signature of the plain tier password.

Constructors:

  • EncryptedTier() { } — Default for deserialization.
  • EncryptedTier(byte[] signedEncryptedTier, string encryptedTierPass, byte[] signedTierPass)

Usage Note: Tiers represent permission levels (e.g., 0 = full access, 1 = manager, 2 = user). Higher tiers inherit lower ones. Signatures prevent tampering; decrypt/verify before granting access.

Core Methods

GetExecutablePathAsync(string command)

Resolves the full path to an executable using platform-specific tools (where on Windows, which on Unix-like systems).

  • Parameters:
    • command: Executable name (e.g., "myapp.exe").
  • Returns: Task<string?> — Full path or null if not found.
  • Exceptions: None (graceful failure).

Usage: Automatically called in GetPaths to populate ExePath. Useful for verifying app integrity.

MakeRelativeFromAuthor(string fullPath, string author) (internal helper)

Normalizes paths relative to the author directory for signing/verification.

  • Parameters:
    • fullPath: Absolute path to relativize.
    • author: Author name (e.g., "Zakstar").
  • Returns: string — Relative path (e.g., "GunGaleOnline/TournamentOfBullets") or fallback to full path.

GetPaths(SecureData identifier, string software, string author, string programName, string serviceParent)

Computes the full DirectoryData structure for an app/user.

  • Parameters:
    • identifier: User/device identifier (e.g., XRUIOS User ID).
    • software: App name (e.g., "TournamentOfBullets").
    • author: Developer (e.g., "Zakstar").
    • programName: Executable name for path resolution.
    • serviceParent: Service group (e.g., "GunGaleOnline").
  • Returns: Task<DirectoryData>
  • Exceptions: On path computation errors.

Usage: Call before any directory operations to ensure standardized paths.

CheckMainPathValidity(DirectoryData data, SecureData PublicKey)

Verifies the integrity of the main service path using post-quantum signatures stored in "CORE.json".

  • Parameters:
    • data: Directory structure from GetPaths.
    • PublicKey: System public key (from SecuritySettings or derived).
  • Process:
    1. Load "CORE.json" and extract public key & signed path.
    2. Verify signature with EasyPQC.Signatures.VerifySignature.
  • Returns: Task<bool> — true if path is untampered.
  • Exceptions: On file I/O or verification failures.

Usage: Guard clause for all app operations (e.g., in CreateNewApp, VerifySessionIntegrity).

CreateNewSystem(string username, SecureData identifier, SecureData password, string software, string author, string exePath, string serviceParent, int tiers, SecureData PublicKey, SecureData userID)

Initializes a complete secure ecosystem: directories, CORE signatures, secret bank, tiers, allow/block lists, and first user.

  • Parameters:
    • username, identifier, password: Initial user details.
    • software, author, exePath, serviceParent: Ecosystem metadata.
    • tiers: Number of permission tiers to generate (e.g., 3 for employee/manager/director).
    • PublicKey, userID: Encryption key & user ID (auto-derives master secret).
  • Process:
    1. Create directory hierarchy.
    2. Generate PQ keys & sign paths/author in "CORE.json".
    3. Initialize secret bank in UserSharedResources.
    4. Generate & encrypt tier passwords in "Data Tiers.json" (with signatures).
    5. Create empty "Allowed Programs.json" with blocklists.
    6. Call SetupFiles and CreateUser for initial account.
  • Returns: Task<SecureData> — Recovery key for the new user.
  • Exceptions: On directory creation, key gen, or user creation failures.

Usage: Call once per service (e.g., on XRUIOS install) to bootstrap the ecosystem.

CreateNewApp(string username, SecureData password, string Directory, DirectoryData directories, string tier, SecureData PublicKey)

Registers a new application under an existing system, assigns a tier, adds to allow list, and creates a user.

  • Parameters:
    • username, password: New app-specific user.
    • Directory: Base directory (from GetPaths).
    • directories: Full path structure.
    • tier: Permission level (e.g., "1" for manager access).
    • PublicKey: System key.
  • Process:
    1. Validate path integrity (CheckMainPathValidity).
    2. Check blacklists; throw if blocked.
    3. Verify tier exists and signatures match in "Data Tiers.json".
    4. Add to "Allowed Programs.json" (encrypted tier ID).
    5. Call CreateUser for app-specific account.
  • Returns: Task<SecureData> — Recovery key.
  • Exceptions: On blacklist, invalid tier, signature mismatch, or user creation.

Usage: For adding XRUIOS apps; use tiers for access control (e.g., low tier for UI, high for system proxy).

AddToBlacklist(string softwareName, ConnectedSessionReturn connSession, string mainServicePath, SecureData PublicKey)

Blocks a program from the ecosystem (requires valid session).

  • Parameters:
    • softwareName: App to block.
    • connSession: Validated session.
    • mainServicePath: Service directory.
    • PublicKey: Encryption key.
  • Process:
    1. Call ValidateSession.
    2. Load "Allowed Programs.json"; add to "Blacklisted Programs" if not already present.
    3. Save encrypted.
  • Returns: Task
  • Exceptions: If already blacklisted or session invalid.

RemoveFromBlacklist(string softwareName, ConnectedSessionReturn connSession, string mainServicePath, SecureData PublicKey)

Unblocks a previously blacklisted program.

  • Process: Similar to AddToBlacklist, but removes from blacklist.
  • Returns: Task
  • Exceptions: If not blacklisted or session invalid.

RemoveAccount(string softwareName, ConnectedSessionReturn connSession, string mainServicePath, SecureData PublicKey)

Removes a program from the allowed list (de-registers it).

  • Process: Similar to above, but removes from "Allowed Programs".
  • Returns: Task
  • Exceptions: If not allowed or session invalid.

Note on Naming: These methods manage program registries; consider renaming for clarity (e.g., BlockProgram, UnblockProgram, DeregisterProgram).

VerifySessionIntegrity(DirectoryData data, ConnectedSessionReturn connSession, string mainServicePath, SecureData PublicKey)

Combines path integrity and session validation for end-to-end checks.

  • Process:
    1. Call CheckMainPathValidity.
    2. Call ValidateSession.
    3. Throw if either fails.
  • Returns: Task
  • Exceptions: On path/session failure ("logged off").

Usage: Ideal for XRUIOS sync points between proxy and facade apps.