gnexus-creds
=============

Personal secret storage service with REST API, MCP HTTP/SSE adapter, and Vue UI.

## Backend

Install dependencies:

```bash
uv sync --extra dev
```

Run migrations:

```bash
uv run alembic upgrade head
```

Start API:

```bash
uv run uvicorn gnexus_creds.main:app --reload
```

For local PostgreSQL development:

```env
GNEXUS_CREDS_DATABASE_URL=postgresql+psycopg://gnexus_creds:gnexus_creds@127.0.0.1:5432/gnexus_creds
```

Health endpoints:

```text
GET /health
GET /ready
```

## MCP

Two MCP-facing surfaces are available:

- `/mcp/tools/*` is the lightweight HTTP tools adapter used during early
  integration.
- `/mcp-protocol/` is the official MCP Streamable HTTP endpoint backed by the
  Python MCP SDK.

Both require a Bearer API token with the `mcp` scope. Tool access is further
limited to secrets with `allow_mcp=true`.

## Frontend

The frontend lives in `frontend/` and uses Vue 3 plus `gnexus-ui-kit` as a git
dependency.

```bash
cd frontend
npm install
npm run dev
```

Note: `gnexus-ui-kit` must publish or prepare its `dist/` artifacts for git
dependency consumers. If `dist/` is missing from the installed package, the UI
build cannot resolve `gnexus-ui-kit/vue` or the kit CSS.

## Tests

```bash
uv run pytest
uv run ruff check .
```

Coverage report:

```bash
uv run pytest --cov=gnexus_creds --cov-report=term-missing
```

The MVP backend currently targets focused coverage for core services, REST,
auth/session, MCP, and production configuration. UI end-to-end checks remain a
manual smoke-testing step.

## Demo Data

After applying migrations against a configured PostgreSQL database:

```bash
uv run python scripts/seed_demo.py
```

## Docker

Prepare a production env file from `.env.example`, then build the image:

```bash
docker build -t gnexus-creds .
```

Apply migrations:

```bash
docker run --rm --env-file .env gnexus-creds alembic upgrade head
```

Start the app:

```bash
docker run --env-file .env -p 8000:8000 gnexus-creds
```

Local compose stack with PostgreSQL:

```bash
docker-compose up -d postgres
docker-compose run --rm app alembic upgrade head
docker-compose up -d app
```

The image includes the built Vue UI and serves it from FastAPI. The container
does not run migrations automatically; run `alembic upgrade head` explicitly
during deploy.

## Operations

Required production settings are documented in `.env.example`. In production,
the app fails fast if default secrets are still configured, if SQLite is used,
or if public auth/MCP URLs do not use HTTPS.

Operational endpoints:

```text
GET /health
GET /ready
```

`/health` only confirms that the process is alive. `/ready` checks database
connectivity and should be used for readiness checks.

Run database migrations before each deploy:

```bash
alembic upgrade head
```

The session cookie is `HttpOnly`, `SameSite=Lax`, and is marked `Secure` when
`GNEXUS_CREDS_ENV=production`.

Secrets and old versions are hard-deleted when a secret is deleted. Audit events
are retained and intentionally do not store decrypted secret values.