12 KiB
Werkzeug development and data
Privacy
Everything is computed on the device. Werkzeug makes no network requests unless you set up sync or explicitly request an account or device-link action. Each tool keeps its own files, readable only by your user:
| Platform | Data |
|---|---|
| Linux | $XDG_DATA_HOME/werk (or ~/.local/share/werk) |
| Android | the app's private storage |
| Browser | IndexedDB on this site |
Auth's accounts are synced records: otpauth links in the private
records/auth.txt, protected by the file permissions of your account or the
Android app sandbox.
Sync
Profile uses the shared Self bundle. Desktop Account management shows the public ID, alias, sync status and queued changes, and provides account creation, key-file import, backups, device linking and logout. Switching accounts asks whether to keep and merge local Auth records or replace them. A private rollback journal preserves the previous key and records if a switch is interrupted.
The account can use a Mesh node,
api.waozi.xyz by default. Tools work locally without an account. Saved nodes
and the preferred node live in Profile → Nodes; choosing a node preserves the
account and its paused state. The sync switch pauses automatic synchronization
and stays paused after restarting. Logout keeps local Auth records.
Desktop key backups retain Werkzeug's Auth vault key as protected recovery context. Use a passphrase to encrypt the backup. Importing a legacy account key for the already-connected identity preserves its existing vault key. The shared QR workflow also preserves that context and asks both devices to compare digits before connecting. Legacy clients cannot read the extended QR payload when Werkzeug vault context is included.
Desktop Self and participating native apps share public profile preferences only for the same verified account ID. Account keys and Auth records stay in the host's private store. Android retains its existing native Account screen and legacy device-link flow. In the browser, Profile opens the shared manager at https://entity.waozi.xyz. Public name, picture and appearance follow the active waozi.xyz profile. Werkzeug's browser tool data stays local; account sync for those tool records is unavailable.
The embedded web app (/app/?mini) shows only the tools, as large tiles,
with no Profile; werk --mini does the same on the desktop. Use
?mini&app=pass, auth, calculator or clock to open a particular tool
first; Back returns to the tiles. Browser sync is currently unavailable.
- Each record is sealed on the device with XChaCha20-Poly1305 under a random vault key that is never sent to the node unencrypted. The seal covers the account, the record and the time of the change, so the server can neither read nor alter a record or a removal.
- The account key (ML-DSA-44) signs in and signs each sync together with the device's own Ed25519 key.
- Desktop device linking uses the shared Self QR/code exchange with X25519 and encrypted key transfer. Confirm the matching number on both devices. Android's existing 12-character connection code remains available in its native account screen.
- The server can still withhold changes or serve an older copy to a device that has not seen a newer one. A lost device keeps the keys it had: stop syncing there if you can, and replace two-factor secrets you care about.
scripts/sync_e2e_test.sh runs two devices against a local Mesh node.
The werk sync and werk auth commands
On Linux, the same data works without a window, for devices without a screen and for scripts:
werk sync status | create | show | join [CODE] | key [FILE] | now
werk auth list
werk auth code ID
werk auth import [FILE]
werk auth rename ID SERVICE ACCOUNT
werk auth sites ID [WEBSITE ...]
werk auth remove ID
werk sync show prints a code for another device to enter; werk sync join
reads one from its argument or standard input. werk sync key signs in with
an account key from FILE or standard input; for a key with a passphrase, give
FILE and the passphrase on standard input. werk auth list prints the
accounts as JSON with their ids and websites, never their secrets.
werk auth code ID prints the current code and the seconds it stays valid.
werk auth import reads a file, or standard input: otpauth links, Google
Authenticator export links, an unencrypted Aegis export, or a PNG or JPEG of
an export's QR code when GdkPixbuf and ZBar (libzbar0) are installed.
Changes sync right away when the device has an account. werk --app auth
opens the window on one tool, as Harmony's Auth entry does.
Tools are separate apps
Each tool is built into its own portable bundle, build/apps/<tool>.zx:
Pass, Calculator and Clock from apps/<tool>/, Auth from its own Ziran
package (waozixyz/auth), and Workbook from
kryonlabs/workbook. All five are
preinstalled. A tool reaches the host only through Kryon's app context (its
private files, clipboard, clock, key derivation and device-protected
secret), and the host checks every call a bundle asks for before it runs.
Tools never import each other; what two need, such as SHA-256 and PBKDF2,
comes from a Ziran package (crypto).
Build and test
Dependencies and the compiler are pinned in ziran.lock. Desktop builds need
SDL2, Cairo, FreeType, Fontconfig, Pango, GTK 3 and X11 development packages.
Workbook uses its built-in spreadsheet engine on Android and the web; Linux
also uses the installed Gnumeric library for imported documents. Linux file choosers need Zenity. Browser
builds need Emscripten; Android builds need JDK 21 and the SDK/NDK versions in
droid/app/build.gradle. Desktop tests use Xvfb, xdotool, xclip and
ImageMagick on private displays.
make gui # build/werk and the app bundles in build/apps
make install-gui # Werkzeug and each tool in the app menu and on the desktop
make test # Pass/CLI, Auth, Calculator and private account recovery fixtures
make gui-smoke # light and dark home screens on a private Xvfb display
make gui-test # every tool, clipboard and profile on a private display,
# and werk auth without one
make site # build/site: browser app and offline worker
make web-smoke # private headless Chromium
make android-debug # ARM32, ARM64 and universal APKs
make android-fdroid # unsigned F-Droid candidate, same Android ID and version
make android-emulator # the x86_64 APK for a private emulator
Android input tests require an explicitly owned private emulator through
WERK_ANDROID_EMULATOR. python3 scripts/private-emulator.py make android-input-test
owns a headless API 31 Google APIs emulator, including Workbook's system document picker.
CI also retains API 30 input, profile and in-place update coverage through
make android-profile-test.
Linux installs include separate Pass, Auth, Calculator, Clock, Workbook and Gallery
launchers, each with its own icon. They open the selected tool directly and
share Werkzeug's existing private data. make install-gui also adds shortcuts
to the desktop folder configured by xdg-user-dir; set DESKTOP_DIR= to skip
those shortcuts. Debian packages include the same application-menu entries.
F-Droid metadata is maintained in packaging/fdroid. The android-fdroid
target disables developer signing even when a release keystore is configured
and writes build/fdroid/werk.apk for comparison with the signed release. It adds no version or
package suffix, preserving existing installations and reference-APK checks.
The unsigned candidate is for builders, not installation. Werkzeug currently
has no built-in updater: F-Droid or your chosen installer handles updates.
Android requires the same signing certificate for an in-place update; the
F-Droid recipe retains the developer-signature reproducibility requirement.
The F-Droid TODO records completed checks, the remaining submission/reproducibility steps and the prepared merge-request text.
For development with the real project repositories, create an ignored
ziran.local.toml:
[overrides]
kryon = "../../kryonlabs/kryon"
ziran = "../../ziranlang/ziran"
The pass command
pass [OPTIONS] SITE LOGIN [MASTER_PASSWORD]
pass [OPTIONS] PROFILE SITE
make cli builds it and make install-cli installs it. The default password
has 16 characters and includes lowercase letters, uppercase letters, digits
and symbols. Length must be between 5 and 35, matching LessPass clients. The
default counter is 1.
Passing a master password as an argument can expose it to process inspection
and shell history. Omitting it is safer: pass first checks
LESSPASS_MASTER_PASSWORD, then reads one line from standard input. Use
--prompt to bypass the environment and read from standard input:
pass --prompt example.com alice
pass --length 24 --counter 2 example.com alice
pass --no-symbols --exclude '0O1Il' example.com alice
The Linux CLI also reads saved identities from
$XDG_CONFIG_HOME/pass/profiles.json (or ~/.config/pass/profiles.json).
pass w example.com and pass --profile w example.com use the saved login
and generation options. Existing OpenSSL-encrypted vaults are unlocked with
a hidden Vault passphrase: prompt. A configured vault takes precedence over
LESSPASS_MASTER_PASSWORD; --prompt bypasses it. Explicit flags override
profile defaults. Profiles and vaults are read without changing them.
--copy or a profile's copy setting copies through xclip on X11;
--clear-after 90s releases that clipboard selection after the given time
without erasing a later copy from another application. Use --no-copy to
print the generated password instead. Run pass --help for all flags.
Source layout
apps/pass/ Pass: LessPass core, settings and profiles, screens, CLI
auth (package) Auth: TOTP, otpauth links, exports, accounts and screens (waozixyz/auth)
apps/calculator/ Calculator
apps/clock/ Clock and stopwatch
src/werk.zi home screen, profile screen and the bar above a tool
src/apps.zi loads, checks and runs the app bundles
src/platform.zi files, clock, clipboard and secrets per platform
src/desktop.zi, src/android_main.zi, src/browser.zi platform main loops
src/command.zi werk sync and werk auth without a window
Profile-picture diagnostics
make entity-account-test uses a private local HTTP fixture to fetch a
picture through the normal background pump while Profile is closed. It checks
the challenge and signed login, saves the returned picture locally and in the
shared profile, and preserves another app's name. Its sanitized result is
build/entity-account-test/picture-sync-diagnostics.json; it contains no account
identifiers, keys, signatures or tokens.
make gui-test also extracts and decodes all 17 Entity picture resources in a
private display. Its resource names, dimensions and permissions are recorded
in build/apps-gui-test/entity-resource-diagnostics.json. This distinguishes
bundled-resource failures from sync failures without reading a real account.
Werkzeug previously skipped starting the background picture reader when Profile was closed and no local picture was pending. Sync-enabled accounts now start it automatically. These tests cover that reproduced failure. The reported shared-resource failure across other apps has not been reproduced; the tests do not establish its server-side or cross-app cause.
License
Copyright © 2026 Waozi. Distributed under the BSD 3-Clause License. See
LICENSE.