Fork: 0
root / gnexus-creds
Transfer to URL with SHA Find file
Newer
Older
gnexus-creds / docs / implementation-plan.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy 4 days ago 7 KB Add project specification and implementation plan
Raw Blame History

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:

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:

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:

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:

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.