Web Console

CoreLib includes a lightweight HTTP Web Console. WebConsoleService starts the embedded HTTP server, serves the frontend bundled under EmakiCoreLib/src/main/resources/web, and lets the browser inspect module status, browse registered configuration trees, edit structured YAML, open source editors, manage scripts/GUI/item files, and load module-provided frontend extensions.

The Web Console is a high-permission maintenance entry point. Change the default password before enabling it, and prefer binding it to 127.0.0.1, a private network address, or a protected reverse proxy.

Commands

CoreLib registers /emakicorelib with aliases /corelib and /emakicore.

Command	Description	Permission
/emakicorelib help	Show CoreLib command help.	None
/emakicorelib web	Print the Web Console address and a clickable link when supported. Aliases: webconsole, url, link.	emakicorelib.web
/emakicorelib reload	Reload CoreLib configuration, action system, and Web Console.	emakicorelib.reload
`/emakicorelib webdebug [all	frontend	backend]`

Permissions:

Permission	Default	Description
emakicorelib.admin	op	Admin umbrella permission, including Web Console and reload.
emakicorelib.web	op	Allows viewing the Web Console link.
emakicorelib.reload	op	Allows reloading CoreLib and toggling Web Console debug logging.

Configuration

The configuration lives under plugins/EmakiCoreLib/config.yml > web_console. The current default resource writes the minimal security section:

web_console:
  enabled: false
  host: "127.0.0.1"
  port: 38765
  public_access_warning: true
  auth:
    username: "EmakiAdmin"
    password: "EmakiAdminPassword"
    session_timeout_minutes: 60
  security:
    allow_config_write: false
    max_request_body_kb: 256

The source also supports optional nodes. Older generated configs can omit them and still use built-in defaults:

web_console:
  security:
    allowed_modules: []
  config_browser:
    max_file_size_kb: 512
    allowed_extensions:
      - ".yml"
      - ".yaml"
      - ".json"
      - ".txt"

allowed_modules: [] means no explicit module allowlist; the console uses registered module IDs. Fill it only when you need to hide or isolate specific installed modules.

Fields

Field	Type	Default	Description
enabled	boolean	false	Starts the embedded HTTP service.
host	string	127.0.0.1	Bind address. 0.0.0.0 listens on all interfaces and must be protected.
port	int	38765	Listening port. Invalid ports fall back to 38765.
public_access_warning	boolean	true	Returns a warning flag in login responses for risky public access.
auth.username	string	resource default EmakiAdmin, internal default admin	Login username.
auth.password	string	resource default EmakiAdminPassword, internal default change-me	Login password. Change it before enabling.
auth.session_timeout_minutes	int	60	Token lifetime, minimum 1 minute.
security.allow_config_write	boolean	false	Allows saving config, script, GUI, item, or custom resource files.
security.max_request_body_kb	int	256	Request body limit. Increase it for large YAML or script saves.
security.allowed_modules	list	[]	Module ID allowlist. Empty means all registered modules.
config_browser.max_file_size_kb	int	512	Max file size readable by the config browser.
config_browser.allowed_extensions	list	.yml/.yaml/.json/.txt	Allowed extensions. Values are normalized to lowercase with a leading dot.

Security behavior

Current source behavior:

1. enabled=false means no HTTP server is started.
2. If the config falls back to the internal password change-me, startup is refused.
3. The generated sample password is EmakiAdminPassword; it is not blocked by the change-me check, so production servers must still change it.
4. After login, frontend API requests use a bearer token. Expired tokens require logging in again.
5. When allow_config_write=false, save/create/delete endpoints reject writes; reads and previews remain available.
6. /extensions/ scripts are loaded with <script> tags and therefore cannot send Authorization headers. The backend only serves registered plugin resources from this route.
7. File paths are checked against absolute paths, .., cross-module access, and unregistered extension paths.

Recommended operation:

• Bind to 127.0.0.1 or a trusted private network for routine use.
• For public access, place it behind HTTPS reverse proxy and additional access control.
• Keep allow_config_write=false on production servers and enable it only during maintenance windows.
• Run /emakicorelib reload after changing Web Console configuration.
• Use /emakicorelib webdebug frontend, backend, or all temporarily while troubleshooting, then disable debug logging again.

Current capabilities

Capability	Description
Login/session	Password login with token-based API access.
Module tree	Reads modules, files, child files, icons, versions, and status from the backend registry.
Structured config editor	Edits single-file CONFIG nodes and lazily loads glob child-file nodes.
Source editor	Opens source for config, GUI, item, script, and custom resource files with revision conflict checks.
File create/delete	Creates and deletes child files under glob entries such as **/*.yml or **/*.js.
GUI editor	Generic GUI surface for Bukkit InventoryType, titles, rows, slots, display items, sounds, and components.
Item editor	Generic ITEM surface for field forms, source editing, item preview, and custom field renderers.
Runtime information	Runtime libraries, economy providers, name/lore action types, and Bukkit DamageCause enum values.
Variable-map editing	variablesMap fields use a dedicated key/value editor instead of plain object or text editing.
Changed-field highlight	The structured editor tracks changed paths and highlights modified fields before saving.
Frontend extensions	Dynamically loads module IIFE scripts returned by the registry; scripts register pages, fields, translations, and preview logic through window.EmakiWebConsole.

Declarative registration

Business modules currently register their Web Console entries mainly through src/main/resources/web-console.yml, then call:

WebConsoleRegistry.registerFromYaml(this);

On disable or reload they call:

WebConsoleRegistry.unregisterModule(this);

Supported web-console.yml sections:

Section	Description
module	Module metadata: name, summary, tone, icon. Current built-in modules mostly define tone and SVG icon; display text is provided by frontend i18n.
files	File entries. Each supports path, kind, title, comment, and editor.
extensions	Frontend extension scripts. Each supports id and resource.
nodes	Structured config node metadata. Each supports path, type, label, comment, and creatableChildren.
comments	Legacy node-comment format kept for compatibility.

File kinds

kind	Backend registration	Default frontend behavior
CONFIG	registerConfigFile	Structured editing for fixed files; child-file tree for glob paths.
GUI	registerGuiFile	Generic GUI editor; can bind a dedicated editor with editor.
ITEM	registerItemFile	Generic item editor; can bind a dedicated editor with editor.
SCRIPT	registerScriptFile	Script text read/write interface.
Other values	registerResourceFile	Custom resource kind exposed to the frontend surface registry, such as SET.

Structured field types

Besides the base text, number, boolean, list, and object types, current Web Console schemas can use these CoreLib field types:

Type	Description
stringList / numberList / actions	Frontend list display overrides. actions uses the shared Name/Lore action-chain editor.
effects	Shared effect-list editor. The selected effect type controls which payload fields are shown.
economyProvider	Shared economy provider selector. Options come from the runtime CoreLib economy manager, with auto as the standard default.
variablesMap	Key/value variable-map editor for dynamic variable tables.
dynamic_map	Treats an object node as an editable dynamic-key map.
enum:A,B,C	Static enum options.
dynamic_enum:folder	Dynamic enum options loaded from YAML ids or file names under a module data folder.

Registered module entries

Module	Registered file entries	Frontend extension
EmakiCoreLib	config.yml, scripts/**/*.js	Core frontend shell and generic components.
EmakiAttribute	config.yml, attribute_balance.yml, attributes/**/*.yml, damage_types/**/*.yml, lore_formats/**/*.yml, conditions/**/*.yml	emakiattribute:locale for field metadata and runtime enum usage.
EmakiForge	config.yml, recipes/**/*.yml, item_adjustments/**/*.yml, gui/**/*.yml	emakiforge:gui-surface for forge config schemas and GUI editor.
EmakiStrengthen	config.yml, recipes/**/*.yml, gui/**/*.yml	emakistrengthen:gui-surface for strengthen config, recipes, and GUI editor.
EmakiCooking	config.yml, recipes/**/*.yml, gui/**/*.yml	emakicooking:gui-surface for station config and cooking GUI editor.
EmakiGem	config.yml, conditions/**/*.yml, resonances/**/*.yml, gui/**/*.yml, items/**/*.yml, gems/**/*.yml	emakigem:item-surface for gem/socket item editors, cost/upgrade fields, local previews, and GUI editor.
EmakiSkills	config.yml, skills/**/*.yml, resources/**/*.yml, gui/**/*.yml	emakiskills:gui-surface for skills, resources, triggers, and GUI editor.
EmakiItem	config.yml, items/**/*.yml, sets/**/*.yml	emakiitem:locale for SET kind, item/set editors, field renderers, and source adapter.

HTTP API overview

The service uses the JDK HttpServer. Main routes include:

Path	Method	Description
/api/auth/login	POST	Log in and receive a token.
/api/session	GET	Validate the current token session.
/api/modules	GET	Show allowed module install/enabled/version status.
/api/registry	GET	Return module tree, file entries, editor descriptors, GUI types, runtime enums, and extension scripts.
/api/registry/file	GET	Return structured YAML nodes for a glob child file.
/api/registry/save	POST	Save a structured config node.
/api/files/create	POST	Create a child file under a glob entry.
/api/files/delete	POST	Delete a child file after path confirmation.
/api/configs/create	POST	Compatibility config-file creation route.
/api/configs/tree	GET	Browse a module config directory.
/api/configs/read / /api/configs/save	GET / POST	Read or save config source.
/api/libraries	GET	Show CoreLib runtime library information.
/api/debug/frontend-error	POST	Report frontend errors.
/api/scripts/read / /api/scripts/save	GET / POST	Read or save scripts.
/api/gui/read / /api/gui/save	GET / POST	Read or save GUI YAML.
/api/items/read / /api/items/save	GET / POST	Read or save item YAML.
/api/resources/read / /api/resources/save	GET / POST	Read or save custom-kind YAML resources.
/api/items/preview	POST	Generate an item display preview from YAML content.
/api/items/action-types	GET	Return registered name/lore operation types.
/api/economy/providers	GET	Return economy provider options and currently available providers.
/extensions/{moduleId}/{resource}	GET	Serve a registered frontend extension script.

These routes are primarily internal frontend routes. Manual calls are only recommended for debugging, reverse-proxy integration, or frontend extension development.

Item preview

WebItemPreviewService can simulate item display output from YAML content:

• Generic items: reads display_name / item_name / id, lore, name_actions, and lore_actions.
• Gem definitions: reads gem_type, levels, effects, inlay_cost, extract_cost, and upgrade.
• Gem socket items: reads match.item_sources, slots, default_open_slots, allowed_gem_types, max_same_type, and max_same_id.

Preview output includes rendered name/lore, resolved variables, operation steps, and summaries for effects, upgrades, materials, and costs. It is an editing aid only and does not replace real server-side item generation, PDC writes, or external item-source resolution.

Gem also registers local preview fallbacks for gem and socket-item editors when server-side preview is unavailable or immediate draft feedback is needed.

Troubleshooting

/emakicorelib web prints a URL but the page does not open

Check:

1. web_console.enabled=true.
2. host is reachable from the browser machine.
3. If host=0.0.0.0, the clickable link falls back to 127.0.0.1; replace it with the real server IP or domain for remote access.
4. Firewall, container port mapping, or reverse proxy allows the port.
5. The server console has no Web Console startup error.

Save buttons fail

Check:

1. security.allow_config_write=true.
2. The login token has not expired.
3. The request body does not exceed security.max_request_body_kb.
4. The file extension is allowed by config_browser.allowed_extensions.
5. The module is allowed by security.allowed_modules, or the allowlist is empty.
6. The server process can write the target file.
7. No revision conflict occurred; refresh before saving again if another admin changed the file.

A module is missing from the tree

Confirm the plugin is enabled, then check:

• The plugin calls WebConsoleRegistry.registerFromYaml(this) during enable.
• The plugin JAR contains web-console.yml.
• web-console.yml registers at least one file entry.
• If security.allowed_modules is configured, it contains the module ID such as EmakiGem.
• Reload cleans stale entries through unregisterModule and then registers again; if it is still missing, check for web-console.yml parse warnings.

A frontend extension fails to load

Check:

1. web-console.yml > extensions[].resource matches the resource path inside the JAR.
2. The resource path does not start with / and does not contain ...
3. Vite outputs the bundle to src/main/resources/web-extensions and it is included in the JAR.
4. The bundle uses IIFE format and externalizes react and emaki-web-console to global React and EmakiWebConsole.
5. Browser console and /emakicorelib webdebug frontend logs do not report script errors.

See Web Extension Integration for implementation details.