Born from the ancient runes of OpenDoas, Voix is a modern, secure invocation designed to govern the ascension of privileges across your systems. As a hardened successor to traditional tools like sudo and doas, it utilizes the pact of Pluggable Authentication Modules (PAM) and immutable rules to ensure only the worthy are granted the power to traverse higher planes of execution.

"Where sudo scatters trust, Voix binds it with modern security."

• Ascension by Design: Execute incantations with elevated privileges only when explicitly ordained by the Elders.
• The PAM Pact: Cryptographically secure authentication tied into your realm’s deep foundations.
• Runes of Clarity: Configuration is ordained in unmistakable syntax within the /etc/voix.conf sanctuary.
• Seamless Transmutation: Properly spawns the user's shell environment upon successful ascent.
• Sanctified Tokens: Optional time-gated persistence of power, mimicking familiar boons.

The Elders command strict adherence to modern crafting:

• LLVM Clang Toolchain (Only Clang is accepted by the forge)
• A C++26 compliant arcane environment
• CMake (v3.18+) and Ninja
• Core dependencies:
  • yaml-cpp, pam, libcap, libseccomp, pkg-config.
  • On Debian/Ubuntu: libyaml-cpp-dev, libpam0g-dev, libcap-dev, libseccomp-dev.
  • On Fedora/RHEL: yaml-cpp-devel, pam-devel, libcap-devel, libseccomp-devel.

1. Obtain the Scrolls:

   git clone https://github.com/Veridian-Zenith/Voix.git && cd Voix

2. Forge the Release Artifact:

   cmake -B build -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release
   cmake --build build

3. Install the Artifact:

   sudo cmake --install build

4. Distribution Specifics:

   • Arch Linux: Users are encouraged to install via AUR using paru or yay:

     paru -S voix
     # OR
     yay -S voix

   • Other Distributions: Please refer to the packaging directory for guidance on creating packages for your specific system.

With the forge and installation complete, ensure your PAM configuration at /etc/pam.d/voix is aligned with your security policy, and you may now invoke Voix.

The heart of Voix is defined in /etc/voix.conf using a structured YAML format.

Deconstructing the Runes:

• core: Global settings like the sanctuary (temp directory) and allowed execution paths.
• acl: The Access Control List, divided into user and group realms.
  • action: Use permit to ordain power or deny to shun a soul.
  • options: (Optional) Use trust to grant power without re-authentication for a time.
  • target: (Optional) The entity to execute as. Defaults to root.
  • command: (Optional) The specific rite allowed.
  • args: (Optional) Specific arguments required for the rite.
• security: Global restrictions, such as a blocklist of forbidden incantations.

An Offering to the Config:

For the most up-to-date and complete configuration example, please refer to the [config/voix.conf](config/voix.conf) file within this repository:

# Voix configuration

# Core system settings
core:
  sanctuary: /tmp
  paths:
    - /bin
    - /sbin
    - /usr/bin
    - /usr/sbin

# Access Control List
acl:
  group:
    wheel:
      - action: permit
        options: [trust]

# Security Policies
security:
  blocklist:
    - /bin/sh

To cast a command beyond your station:

voix <incantation> [args...]

• -u USER, --user USER: Invoke as a specific entity.
• -n, --non-interactive: Fail the cast immediately if blood (password) is required.
• -C, --clear: Forsake any lingering tokens of power instantly.

Problem: "PAM authentication failed"

Solution: The pact is broken. Ensure that the PAM scroll at /etc/pam.d/voix is correctly inscribed.

Problem: "Permission denied"

Solution: The runes of law are not in your favor. Consult the /etc/voix.conf scroll to ensure you are worthy.

Every function, every design, everything is modular, has a use, and is well put-together. If you seek to alter the artifact:

1. Speak exclusively in C++26.
2. Honor the Clang compiler constraints.
3. Bind your work with clang-tidy to cleanse any lingering chaos (see [CONTRIBUTING.md](./CONTRIBUTING.md) for the exact ritual).

Voix is sealed and distributed under the Open Software License v3.0 (OSL-3.0). See the [LICENSE](./LICENSE) scroll for eternal details.