# gnexus-creds Implementation Plan

## Stage 0: Scaffold

Goal: create the initial project structure and runtime baseline.

Deliverables:

- `pyproject.toml`
- FastAPI application factory
- environment-based settings
- PostgreSQL connection setup
- Alembic migrations
- `/health`
- `/ready`
- JSON logging
- pytest setup
- dependency on `gnexus-auth-client-py` as a Python package

Acceptance criteria:

- app starts locally.
- `/health` works without database access.
- `/ready` checks database connectivity.
- migrations can be applied.
- test suite runs.
- `gnexus-auth-client-py` is installed as a dependency, not copied into the
  repository.

## Stage 1: Core Domain

Goal: implement the domain model without external auth or MCP.

Modules:

```text
gnexus_creds/models/
gnexus_creds/schemas/
gnexus_creds/services/
gnexus_creds/crypto/
gnexus_creds/repositories/
```

Initial database entities:

- `users`
- `user_encryption_keys`
- `secrets`
- `secret_versions`
- `secret_fields`
- `secret_tags`
- `api_tokens`
- `audit_events`
- `sessions`
- `oauth_states`
- `rate_limits`

Core behavior:

- create user.
- create user encryption key on first user initialization.
- create secret.
- update metadata without creating a new version.
- update fields and create a new version.
- reveal current version.
- reveal historical version.
- hard delete secret while preserving audit events.
- search metadata, tags, field names, and non-encrypted field values.
- never search encrypted field values.

Acceptance criteria:

- core service tests cover versioning decisions.
- core service tests cover encryption/decryption.
- metadata update does not create a version.
- field update creates a version.
- old versions can be revealed.
- audit never stores secret values.

## Stage 2: REST API

Goal: expose the public JSON API under `/api/v1`.

Endpoints:

```text
GET    /api/v1/me

GET    /api/v1/secrets
POST   /api/v1/secrets
GET    /api/v1/secrets/{id}
PATCH  /api/v1/secrets/{id}
DELETE /api/v1/secrets/{id}

POST   /api/v1/secrets/{id}/reveal
GET    /api/v1/secrets/{id}/versions
GET    /api/v1/secrets/{id}/versions/{version_id}
POST   /api/v1/secrets/{id}/versions/{version_id}/reveal

GET    /api/v1/categories
GET    /api/v1/tags
GET    /api/v1/suggestions

GET    /api/v1/audit-events
GET    /api/v1/secrets/{id}/audit-events

GET    /api/v1/api-tokens
POST   /api/v1/api-tokens
DELETE /api/v1/api-tokens/{id}

POST   /api/v1/export
POST   /api/v1/import
DELETE /api/v1/account-data
```

API behavior:

- JSON only.
- stable error envelope.
- offset/limit pagination.
- list/search returns metadata plus non-encrypted fields.
- reveal returns all fields.
- OpenAPI includes schemas, descriptions, and examples.
- API token auth uses token hash lookup.
- scopes: `read`, `reveal`, `write`, `admin`, `mcp`.

Acceptance criteria:

- REST integration tests cover CRUD.
- REST integration tests cover search/list/reveal.
- REST integration tests cover version history.
- REST integration tests cover API token scopes.
- REST integration tests cover audit creation.
- export/import round trip works.
- rate limiting protects sensitive endpoints.

## Stage 3: gnexus-auth Integration

Goal: implement real UI login and session flow.

Deliverables:

- dependency-backed `gnexus-auth-client-py` integration.
- OAuth login route.
- OAuth callback route.
- logout route.
- server-side sessions stored in PostgreSQL.
- OAuth state and PKCE storage in PostgreSQL.
- `/oauth/userinfo` user sync.
- first-login user initialization.
- `gnexus-auth` webhook endpoint.
- local disabled-user handling.
- role mapping for `user` and `admin`.

Routes:

```text
GET  /auth/login
GET  /auth/callback
POST /auth/logout
POST /webhooks/gnexus-auth
```

Acceptance criteria:

- user can log in through `gnexus-auth.local`.
- local user is created on first login.
- user encryption key is created on first login.
- repeated login updates local profile fields.
- disabled users cannot log in.
- webhook updates profile/status.
- UI session cookie works.
- API token auth and UI session auth coexist.

## Stage 4: MCP

Goal: expose MCP over HTTP/SSE inside the same FastAPI application.

Tools:

```text
search_secrets
get_secret
reveal_secret
create_secret
update_secret
set_secret_status
archive_secret
```

Rules:

- auth uses API token with `mcp` scope.
- tool actions additionally require `read`, `reveal`, or `write`.
- archived secrets are never returned.
- existing secret operations require `allow_mcp=true`.
- reveal creates audit event with `channel=mcp`.
- tool implementations reuse the REST service layer.

Acceptance criteria:

- MCP tests cover authentication.
- MCP tests cover scope checks.
- MCP tests cover `allow_mcp`.
- MCP tests cover archived secret exclusion.
- MCP tests cover reveal audit.
- HTTP/SSE transport works without stdio.

## Stage 5: UI

Goal: build the MVP frontend with Vue.js and `gnexus-ui-kit`.

Dependency requirements:

- `gnexus-ui-kit` is installed as a frontend dependency.
- no `gnexus-ui-kit` source code is copied into this repository.
- integration uses public Vue components/styles only.
- dependency version is lock-file pinned after successful integration.

Screens:

- login/session bootstrap
- dashboard/overview with search
- secrets list
- secret detail
- create/edit form
- reveal/copy controls
- version history screen
- audit list
- API token management
- export/import
- settings/delete data
- admin UI

UI behavior:

- default locale is English.
- locale is read from `gnexus-auth` when available.
- categories and tags use autocomplete.
- encrypted fields show name plus reveal/copy controls.
- reveal can display the value in-card.
- copy can work without visual reveal.
- dangerous actions use confirmation modals.
- core flows support keyboard navigation and visible focus states.

Acceptance criteria:

- all MVP user scenarios are available through UI.
- no direct dependency on private internals of `gnexus-ui-kit`.
- seed data supports manual end-to-end smoke testing.
- UI respects backend authorization failures.
- user role cannot access admin screens.

## Stage 6: Admin

Goal: provide role-based admin capabilities.

Admin features:

- list users.
- view user profile/status.
- view user-related system audit.
- view basic health/ready diagnostics.

Constraints:

- admin role is determined from `gnexus-auth`.
- backend enforces admin permissions.
- admins do not get decrypted user secrets by default.

Acceptance criteria:

- `user` role cannot access admin API routes.
- `user` role cannot access admin UI screens.
- `admin` role can access admin screens.
- admin API tests cover permission checks.

## Stage 7: Packaging

Goal: prepare the service for production deployment.

Deliverables:

- Dockerfile.
- production env example.
- migration command documentation.
- app start command documentation.
- README update.
- operational notes.

Acceptance criteria:

- container builds.
- app starts from container.
- app connects to PostgreSQL.
- migrations apply.
- production configuration is documented.

## Testing Strategy

Core:

- service layer tests.
- crypto tests.
- versioning tests.
- audit safety tests.

REST:

- FastAPI integration tests.
- API token auth tests.
- scope tests.
- export/import tests.

Auth:

- mock `gnexus-auth` token/userinfo responses.
- webhook verification and parsing tests.
- session tests.

MCP:

- tool tests.
- auth/scope tests.
- access flag tests.

UI:

- no full e2e test suite in MVP.
- manual smoke testing with seed data.

## Technical Choices

Preferred defaults:

- ORM: SQLAlchemy 2.x.
- migrations: Alembic.
- crypto: `cryptography`, AES-GCM with explicit key id, nonce, ciphertext,
  and algorithm metadata.
- sessions: PostgreSQL-backed server-side sessions.
- API token format: `gcr_<public_id>_<secret>`, with only a hash stored.
- MCP library: choose during implementation after verifying FastAPI HTTP/SSE
  compatibility.

## Implementation Order

1. Scaffold.
2. Core domain.
3. REST API.
4. `gnexus-auth` login/session integration.
5. MCP.
6. Vue UI with `gnexus-ui-kit`.
7. Admin UI/API.
8. Docker packaging and deploy docs.