meyi-vault-server 1.0.0

package/README.md

@@ -0,0 +1,95 @@
+# vault-server
+
+> Self-hosted AES-256-GCM encrypted password manager — Express plugin for MeyiConnect
+
+## Installation
+
+```bash
+npm install vault-server
+```
+
+## MeyiConnect plugin integration
+
+Copy the wrapper into your MeyiConnect backend:
+
+```
+backend/src/plugins/vault/index.mjs
+```
+
+```js
+import { install, start, stop } from 'vault-server'
+import { verifyToken } from '../../middleware/auth.mjs'
+
+export async function install() {
+  await install()
+}
+
+export async function start(app, config, db) {
+  await start(app, config, db, verifyToken)
+}
+
+export async function stop() {
+  await stop()
+}
+```
+
+MeyiConnect's `pluginService` will call `install()` once and `start()` on each boot.
+
+## Standalone usage
+
+```js
+import express from 'express'
+import { install, start } from 'vault-server'
+
+const app = express()
+
+// Your own auth middleware that sets req.user = { id, role, email }
+const myAuth = (req, res, next) => { /* ... */ next() }
+
+await install()                    // create DB tables
+await start(app, {}, null, myAuth) // mount at /api/v1/vault
+
+app.listen(4000)
+```
+
+## Environment variables
+
+| Variable          | Default          | Description                          |
+|-------------------|------------------|--------------------------------------|
+| `DATABASE_URL`    | required         | PostgreSQL connection string         |
+| `VAULT_DB_SCHEMA` | `meyiconnect`    | PostgreSQL schema for vault tables   |
+| `VAULT_MOUNT_PATH`| `/api/v1/vault`  | Express mount path                   |
+
+## API routes
+
+All routes require `req.user` set by the injected auth middleware.
+
+```
+GET    /api/v1/vault/vaults
+POST   /api/v1/vault/vaults
+DELETE /api/v1/vault/vaults/:id
+
+GET    /api/v1/vault/vaults/:vaultId/groups
+POST   /api/v1/vault/vaults/:vaultId/groups
+PUT    /api/v1/vault/vaults/:vaultId/groups/:id
+DELETE /api/v1/vault/vaults/:vaultId/groups/:id
+
+GET    /api/v1/vault/groups/:groupId/entries
+POST   /api/v1/vault/groups/:groupId/entries
+PUT    /api/v1/vault/groups/:groupId/entries/:id
+DELETE /api/v1/vault/groups/:groupId/entries/:id   (soft delete)
+
+POST   /api/v1/vault/grants
+GET    /api/v1/vault/grants
+GET    /api/v1/vault/grants/received
+DELETE /api/v1/vault/grants/:id
+
+GET    /api/v1/vault/stats
+```
+
+## Security
+
+- **AES-256-GCM** — authenticated encryption, throws on tampered ciphertext
+- **Per-vault keys** — each vault has its own random 32-byte key
+- **Soft deletes** — entries are never hard-deleted; `deleted_at` timestamp set
+- **No auth code** — delegates entirely to the host's auth middleware via `verifyToken` injection