• English

      • Mod protection & credentials

      Estimated reading time: 2 minutes

      From v3.2.5 onward the framework ships full mod encryption support: the framework itself is not encrypted; dependent mods that need protection should be packaged as .modpack shells via the companion tooling, with runtime credential checks and ModLoader lazy-load of the decrypted payload.

      Framework vs dependent mods

      TargetEncrypted?Notes
      maplebirch frameworkNoDistributed as a normal .mod.zip or as a release .modpack shell that only wraps the framework install
      Mods that depend on maplebirchOptionalConvert the source zip with dol-mod-protection-tools

      A protected .modpack only exposes the shell boot.json, an earlyload decryptor, and .crypt shards. The original boot.json, auth.json, scripts, and assets live inside the encrypted payload and are not left in plaintext in the shell.

      Tooling

      • dol-mod-protection-tools — official packager for .modpack, auth.json, prompts, and metadata (see that repo’s README).
      • ModLoader basics — Mod encryption covers SideLazyLoad, tryInitWaitingLazyLoadMod, and related loader concepts.

      Runtime flow

      1. The .modpack shell runs during earlyload and asks the framework to verify credentials (maplebirch.credential / CredentialVault).
      2. On first load the player enters a password via SweetAlert2 (and similar UI deps); successful unlocks are stored in IndexedDB.
      3. After verification the real mod is decrypted and handed to ModLoader SideLazyLoad. Closing the dialog or failed verification disables the encrypted mod.
      v3.2.5

      Credential handling, guard digests, and disable logic align with v3.2.5 and dol-mod-protection-tools. Declare maplebirch >=3.2.5 in your dependenceInfo. See the changelog.

      auth.json (in the source zip before conversion)

      Generated by the tools or placed at the root of the zip you convert; it is not shipped in plaintext inside the shell. Minimal shape:

      {
  "key": "main",
  "publicKey": "BASE64_SPKI_PUBLIC_KEY"
}

      Optional fields include subject, name, prompt, date, etc.—see the dol-mod-protection-tools README.

      CredentialVault API (conceptual)

      maplebirch.credential complements ModLoader’s libsodium pipeline; it does not replace ModLoader encryption by itself:

      1. After IndexedDB is ready (e.g. :idbReady), call maplebirch.credential.prompt(modName, authConfig) when you need unlock UI.
      2. Use unlock, readPassword, guard, etc. to validate payloads or derive guard digests.

      For exact types (AuthConfig, AuthPayload, …) follow SCML-DOL-maplebirchFramework (src/services/CredentialVault.ts) and the v3.2.5 release notes.