# KeePassGO

KeePassGO is a Go-based KeePass-compatible password manager targeting desktop first, with future Android support.

## Current Capabilities

- KDBX load and save
- password-only, key-file-only, and composite master-key flows through the desktop product UI
- master-key changes for existing vault sessions
- WebDAV-backed open and save support in the session layer
- password generation profiles
- gRPC integration surface for trusted automation
- template, attachment, group, history, and recycle-bin persistence

## Run

```bash
go run .
```

Phone-sized preview:

```bash
go run . -mode phone
```

## Test

```bash
go test ./...
go tool golangci-lint run ./...
```

KDBX security and KDF compatibility notes are documented in [`docs/kdbx-compatibility.md`](./docs/kdbx-compatibility.md).

## Build

Desktop build:

```bash
go build ./cmd/keepassgo
```

By default, build outputs stamp the app version from `git describe --tags --always --dirty`.
You can override the version shown in KeePassGO with:

```bash
go build -ldflags "-X git.julianfamily.org/keepassgo/internal/appui.appVersion=v0.0.1" ./cmd/keepassgo
```

## Arch Linux Package

An AUR-style package definition for the Linux desktop client lives under:

- `packaging/archlinux/keepassgo-git/`

From that directory you can build and install it with:

```bash
makepkg -si
```

The package installs:

- `/usr/bin/keepassgo`
- `/usr/bin/keepassgo-browser-bridge`
- a desktop entry at `/usr/share/applications/keepassgo.desktop`
- application icons under the hicolor theme

## Android Packaging

KeePassGO uses Gio, so Android packaging is done with `gogio`.

The repo now has automated tests for the packaging contract:
- default APK build arguments
- required Android SDK / NDK / JDK layout checks

Those are covered by normal test runs:

```bash
go test ./...
```

Install:

```bash
go get -tool gioui.org/cmd/gogio@latest
```

Package:

```bash
make apk
```

`make apk` prefers a local Java 25 install at `JAVA_HOME`. If that is not
available, it falls back to the repo-managed Docker build image, which also
uses Java 25. CI provisions Java 25 directly in the build job so release
packaging follows that same local path. You still need the Android SDK and NDK
installed and configured for real device or release packaging.

Release package:

```bash
make apk-release
```

`make apk-release` is the production-signing path. It requires a dedicated
release keystore at `~/.config/keepassgo/android-release.keystore` and a
password file at `~/.config/keepassgo/android-release.pass`, unless you
override `RELEASE_SIGNKEY` and `RELEASE_SIGNPASS_FILE`.

## Automation

Desktop automation is resolved through the secure gRPC API rather than synthetic auto-type.
See [`docs/desktop-automation.md`](./docs/desktop-automation.md).

On desktop, KeePassGO now listens on a Unix socket by default under the user runtime directory.
Set `KEEPASSGO_GRPC_ADDR` or `-grpc-addr` to override it, for example `tcp://127.0.0.1:47777`.

## MCP Server

KeePassGO includes a stdio Model Context Protocol server for agent and assistant integrations.
It connects to the same local authenticated gRPC API used by browser and desktop automation, so
existing token policy and approval prompts remain in force.

Build it with:

```bash
make mcp-server
```

Configure your MCP client to run `keepassgo-mcp-server` and provide an API token through
`KEEPASSGO_MCP_TOKEN`. The server also accepts `KEEPASSGO_BEARER_TOKEN` for compatibility with
existing local gRPC tooling. Set `KEEPASSGO_GRPC_ADDR` or pass `-grpc-addr` when KeePassGO is not
listening on the default local socket.

The MCP server exposes tools for session status, metadata-only entry search, browser-login matching,
and explicit credential retrieval. Metadata tools do not return passwords, notes, or custom field
values; credential retrieval uses KeePassGO's credential access policy.

## Browser Extension

Firefox and Chromium browser integration is available through the local gRPC API plus a native messaging bridge.
See [`docs/browser-extension.md`](./docs/browser-extension.md).