gnexus-creds Technical Specification

Overview

gnexus-creds is a personal secret storage service with a REST API, MCP server, and web UI. The service stores only personal user data. Team, organization, and secret sharing features are out of scope for the MVP.

The service is implemented in Python with FastAPI. The frontend is implemented with Vue.js and gnexus-ui-kit.

External Dependencies

gnexus-auth-client-py must be used as a backend dependency, not copied into this repository. The integration must rely on its public API only.

gnexus-ui-kit must be used as a frontend dependency, not copied into this repository. The UI must rely on public exported Vue components/styles only.

Both dependencies should be version-pinned through lock files while keeping a clear upgrade path through the normal package manager flow.

Expected dependency forms:

gnexus-gauth @ git+https://git.gnexus.space/git/root/gnexus-auth-client-py.git

{
  "gnexus-ui-kit": "git+https://git.gnexus.space/git/root/gnexus-ui-kit.git"
}

Core Entity: Secret

The main domain entity is secret.

A secret has fixed metadata and a variable list of fields. Fixed metadata:

title
purpose
category
tags
source
notes
status
archived
access flags
timestamps

notes is limited to 140 characters.

status has two values:

actual
outdated

archived hides a secret from ordinary lists. Archived secrets are never available through MCP.

Each secret has one category. Category is a plain text field. Tags are separate search keywords.

Secret Fields

Secret contents are represented as a variable-length list of fields:

{
  "name": "password",
  "value": "...",
  "encrypted": true,
  "masked": true,
  "position": 2
}

There are no built-in templates. A secret can represent a login/password pair, API token, SSH key, card PIN, server credentials, or any other structured text data.

Field rules:

name is the field label.
value is the field value.
encrypted=true means the value is encrypted at rest and is not searchable.
masked=true means the value is hidden by default in UI/API responses.
position controls display order.
field values may be multiline.
maximum field value size is 64 KB.

Metadata, tags, category, field names, and values of fields with encrypted=false are searchable. Values of fields with encrypted=true are not searchable.

Versioning

Secret versioning is required.

A new version is created when any of the following changes:

field list
field value
field encrypted flag
field masked flag
field order

Metadata updates do not create a new version. Metadata includes:

title
purpose
category
tags
source
notes
status
access flags
archived

Old versions are available for viewing and reveal. Revealing an old version must create an audit event.

There is no dedicated rollback operation. If a user wants to restore old values, they update the secret normally, creating a new version.

The actual / outdated status belongs to the whole secret, not to individual versions.

Access Flags

Access is configured globally per secret, not per field.

Flags:

allow_ui
allow_rest_api
allow_mcp

For MCP reveal, both conditions are required:

API token has the reveal scope.
secret has allow_mcp=true.

REST API

The REST API is JSON-only and versioned under /api/v1.

List and search endpoints return metadata plus non-encrypted fields. Full field values are returned only by reveal endpoints.

Pagination uses offset and limit.

The OpenAPI schema is a public contract and must include clear schemas, descriptions, and examples.

Errors use a stable envelope:

{
  "error": {
    "code": "secret_not_found",
    "message": "Secret not found",
    "details": {}
  }
}

Required REST surface:

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 Tokens

External clients use gnexus-creds API tokens. gnexus-auth is used for user login, not as the long-term token source for third-party clients.

API token rules:

created by the user in UI.
has a user-defined name.
has scopes.
is shown only once after creation.
only a token hash is stored.
does not expire.
can be revoked/deleted.

Scopes:

read
reveal
write
admin
mcp

MCP

MCP is part of the same FastAPI application. The first supported transport is HTTP/SSE. stdio is out of scope because the AI agent and MCP server are expected to run on different servers.

MCP uses the same API token model with the additional mcp scope.

MCP tools:

search_secrets
get_secret
reveal_secret
create_secret
update_secret
set_secret_status
archive_secret

Archived secrets are never available through MCP.

MCP search without reveal is not audited. MCP reveal and write operations are audited with channel=mcp.

Authentication and Sessions

User login goes through gnexus-auth OAuth authorization code flow with PKCE. gnexus-creds acts as the backend/BFF for its UI:

redirect user to gnexus-auth;
receive OAuth callback;
exchange code for token set through gnexus-auth-client-py;
fetch /oauth/userinfo;
create or update the local user;
create a server-side session;
set a session cookie for the UI.

UI requests use the server-side session cookie.

Third-party REST and MCP clients use gnexus-creds API tokens.

gnexus-auth is the source of truth for user profile data. Local user data is a cache/mapping.

Local user fields:

local id
auth_subject
email
display_name
profile/avatar data as needed
status
created_at
last_seen_at

Profile/status changes are received through gnexus-auth webhooks.

If a user is deleted or blocked in gnexus-auth, login is blocked, local data is preserved, and the local user is marked disabled.

Roles come from gnexus-auth. MVP roles:

user
admin

Admin UI and admin API access must be enforced on the backend.

Encryption

The service master key is provided through an environment variable.

Each user gets a separate user encryption key on first login. The user key is encrypted by the master key and stored in the database.

User key rotation is out of scope for MVP.

Only values of fields with encrypted=true are encrypted. Metadata, tags, category, field names, and non-encrypted field values are stored in plaintext.

The crypto implementation should store enough metadata for future key handling, including key id, nonce, ciphertext, and algorithm.

Audit

Audit is required.

Events to log:

secret created
metadata updated
new version created
reveal
archive / unarchive
status changed
hard delete
API token created
API token revoked
MCP access where applicable
failed access attempt
export created

Search/list events are not audited. MCP search without reveal is not audited.

Failed access attempts must be rate-limited or aggregated so repeated identical bot traffic does not flood the audit log. At minimum, only the first repeated event in a suppression window should be stored.

Audit event data:

actor user
channel: ui, rest, or mcp
IP when available
user agent when available
API token/client id when applicable
secret id when applicable
action
timestamp
short metadata diff when applicable
snapshot data needed to understand events after secret deletion

Secret values must never be stored in audit events.

Audit is available:

as a global list for the user;
filtered by secret.

Audit retention is 1 year. Users cannot edit or clear audit logs.

Export and Import

Users can export all their data in the service's own JSON format. Export includes decrypted field values.

Export is a high-risk operation and must require explicit confirmation in UI. It must create an audit event.

Import supports only JSON files created by gnexus-creds export. CSV and third-party import formats are out of scope.

Deletion

Secret deletion is hard delete. Secret versions are deleted with the secret. Audit events remain and must include enough snapshot data to remain meaningful.

Users can delete all their own gnexus-creds data. Dangerous actions require a confirmation modal in UI.

UI

The UI is implemented with Vue.js and gnexus-ui-kit.

Required 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

The main screen after login is dashboard/overview plus search.

Secret list columns:

title
purpose
category
tags
status
access flags
created at
updated at

The list may show non-encrypted fields.

Creating a secret uses one form. Required/important fields appear first. Optional fields appear below.

Reveal behavior:

values are shown in the card after pressing a reveal button.
values can be copied without visual reveal.
no additional password/PIN confirmation is required before reveal.

Encrypted fields display the field name and reveal/copy buttons.

Categories and tags use text input with autocomplete from existing values.

Bulk actions are out of scope for MVP.

Localization is required, but MVP ships only English. User locale should be read from gnexus-auth when available.

Accessibility requirements:

keyboard navigation for core flows;
visible focus states;
labels for controls;
sufficient contrast;
no formal WCAG audit required for MVP.

Admin

Admin features are based on roles from gnexus-auth.

Admin capabilities:

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

Admins must not get access to decrypted user secrets by default.

Runtime and Deployment

Production domain:

https://creds.gnexus.space

Auth domains:

production: https://auth.gnexus.space
development: http://gnexus-auth.local

Runtime choices:

Python + FastAPI
PostgreSQL only
no Redis for MVP
server-side sessions in PostgreSQL
OAuth state/PKCE storage in PostgreSQL
rate limit state in PostgreSQL
JSON application logs
/health and /ready

Docker is not required at the beginning of development. The project must be containerized before production deployment.

Backup and restore are outside the application scope.