# Malice

Malice is a hosted Matrix client with a Rust backend built on macltok and a
Svelte frontend. The Nix package serves both the API and the built frontend.

## NixOS module

Add this repository to your NixOS flake inputs, then include its module:

```nix
# In your flake.nix
inputs.malice.url = "git+file:///absolute/path/to/malice";

# In the modules list for your nixosSystem:
malice.nixosModules.default
```

Use a published Git URL instead of the local path if you deploy from another
machine. For a local Git flake, add new source files to Git before rebuilding;
Nix does not include untracked files.

Enable the service in your NixOS configuration. For access from another machine,
put it behind an HTTPS reverse proxy; the service binds to localhost and uses
Secure session cookies by default:

```nix
{
  services.malice.enable = true;
  # Optional: services.malice.port = 3000;

  services.nginx.enable = true;
  networking.firewall.allowedTCPPorts = [ 80 443 ];
  services.nginx.virtualHosts."chat.example.org" = {
    enableACME = true;
    forceSSL = true;
    locations."/" = {
      proxyPass = "http://127.0.0.1:3000";
      extraConfig = ''
        proxy_set_header Host $host;
        proxy_buffering off; # Keep event-stream updates timely.
      '';
    };
  };
  security.acme.acceptTerms = true;
  security.acme.defaults.email = "you@example.org";
}
```

Replace the domain and ACME email, then rebuild your NixOS configuration as
usual. Check `systemctl status malice` and visit `https://chat.example.org/`.
The module stores the master key and sessions in `/var/lib/malice`; back up that
entire directory together. Its `listenAddress`, `port`, `package`, and
`openFirewall` options can be overridden. Do not expose the HTTP listener
without a trusted TLS proxy.

## Client behavior

The home list shows non-space rooms (channels); Matrix spaces have their own
navigation and show their advertised child rooms. A Matrix homeserver is the
network address used at sign-in, not a space. Sending a message returns a queued
command, then the timeline shows whether delivery is queued, sending, confirmed
by the server, or failed. Opening a room loads its timeline; scrolling up loads
older history. Images and avatars are served through authenticated, bounded
media endpoints; SVG content is not rendered. Link previews embedded by the
sender always show. Otherwise the homeserver fetches previews in unencrypted
rooms, and in encrypted rooms only when the user enables it in the Security
panel. Room admins can disable previews per room.

The Security panel accepts incoming device-verification requests and supports
emoji/number comparison, confirmation, rejection, and recovery-key entry.
Recovery keys and encryption state are per Matrix account; preserve the local
session data when migrating an installation.

## Development

From the repository root:

```sh
nix develop
```

The dev shell links `web/node_modules` from a nix build of `web/package-lock.json`,
so there is no install step. After changing dependencies in `web/package.json`,
refresh the lockfile with `npm --prefix web install --package-lock-only` and
re-enter the shell.

For live frontend changes, start these in separate terminals inside `nix develop`:

```sh
MALICE_SESSION_COOKIE_SECURE=false cargo run --bin malice
npm --prefix web run dev
```

Open `http://127.0.0.1:5173/`. Vite proxies `/api` to the Rust server on port
3000. The cookie override is for local HTTP development only. By default,
Malice accepts HTTPS homeservers; set `MALICE_ALLOW_HTTP_HOMESERVER=true` only
when testing against a trusted local HTTP homeserver.

To serve the built frontend directly from Rust instead of using Vite:

```sh
npm --prefix web run build
MALICE_SESSION_COOKIE_SECURE=false cargo run --bin malice
```

Open `http://127.0.0.1:3000/`. Rust uses `web/dist` unless `MALICE_WEB_DIR`
points at another built frontend directory. Local session data defaults to
`local-data/`; set `MALICE_DATA_DIR` to use another directory. Keep its
`master.key` and session files private.

### Storybook

Component stories live next to their components as `web/src/**/*.stories.ts`.
Storybook runs inside `nix develop`:

```sh
cd web
npm run storybook
npm run build-storybook
```

Open `http://localhost:6006/`. While it runs, `@storybook/addon-mcp` serves an
MCP endpoint at `http://localhost:6006/mcp`, which the repository `.mcp.json`
registers for Claude Code in this project only.

## Testing

In `nix develop`:

```sh
cargo fmt -- --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
npm --prefix web run check
npm --prefix web test
npm --prefix web run build
```

The Rust integration test uses a mocked Matrix homeserver; it does not require
live account credentials. To verify the deployable package and NixOS module:

```sh
nix build .#server
nix flake check
```

`nix build` creates `result/bin/malice` with the frontend bundled. On a NixOS
host, `curl -fsS http://127.0.0.1:3000/api/health` checks the local backend;
opening the proxied URL checks the frontend and TLS setup.