Add @suaveplan/api-plugin-vault — per-user vault routes wrapping @suaveplan/vault (3-way plug-and-play)

Package: @suaveplan/api-plugin-vault (NEW, server-tier) Status: PROPOSED Type: new-package Position: depends on add-api-plugin-auth (+ optionally add-api-plugin-user)

Spec delta: ./specs/api-plugin-vault/spec.md

Why

Genesis already ships @suaveplan/vault — the universal encrypted-vault library (open/unlock/lock FSM, items + attachments, container backed by DriveLike). What's missing is the HTTP surface: operators building an app with @suaveplan/api want /vault/items routes that look up the authenticated principal, scope the vault to that user, and apply Better-Auth's session for authorisation. This plugin ships exactly that — three CRUD route groups (items, attachments, shares — items only for v1) plus a vaultService for downstream plugins.

Third instance of the 3-way plug-and-play contract: SurrealQL schema for vault ownership/sharing metadata, Zod schemas at every request boundary, OpenAPI routes registered through definePluginRoutes. The encryption / decryption stays inside @suaveplan/vault; this plugin is the HTTP wrapper + per-user scoping layer only.

What changes

Net-new package at 0.1.0. ADDED:

Plugin factory + descriptor

createVaultPlugin(options): PluginDescriptor<VaultPluginConfig> — definePlugin consumer with dependencies: ["auth"] (user plugin optional). options Zod-validated.
VaultPluginOptions (Zod-validated): { routePrefix?: string (default "/vault"); storage: DriveLike; maxItemSizeBytes?: number (default 10 * 1024 * 1024); applySchemaOnInit?: boolean (default true); logger?: LoggerLike }. storage is the DriveLike instance the vault library writes encrypted blobs to (operator supplies — could be @suaveplan/storage-s3-backed @suaveplan/drive, local fs, etc.).

Routes (5)

All built with RouteBuilder; all gated by requireAuth() upstream. Every route scopes the vault to c.get("user")!.id:

GET /vault/items — list items owned by the principal. Response: VaultItemListResponseSchema (paginated).
POST /vault/items — create a new item. Body: CreateVaultItemBodySchema. Response: VaultItemResponseSchema.
GET /vault/items/:id — fetch a single item. Response: VaultItemResponseSchema. 404 + VAULT_ITEM_NOT_FOUND when the id doesn't exist or isn't owned by the principal.
PATCH /vault/items/:id — update fields. Body: UpdateVaultItemBodySchema (strict mode). Response: VaultItemResponseSchema.
DELETE /vault/items/:id — remove. Response: { deleted: true }. Owner-only or VAULT_FORBIDDEN.

vaultService

vaultService registered via ctx.registerService("vaultService", ...). Surface: { openForPrincipal(principal: Principal, password: string): Promise<VaultHandle>; listItemsForOwner(ownerId: string): Promise<VaultItemSummary[]>; close(handle: VaultHandle): Promise<void> }.
ServiceRegistry augmentation: declare module "@suaveplan/api-plugin/service-registry" { interface ServiceRegistry { vaultService: VaultService } }.
The principal's unlock password is NEVER stored — passed per request via a header (X-Vault-Unlock) or extracted from a separate per-user secret store. Default extractor: headerExtractor("X-Vault-Unlock") (operators override via options.unlockExtractor).

.surql schema (plug-and-play point 1)

./schema exports VAULT_OWNERSHIP_SCHEMA (frozen string) — DDL for two tables:
- vault_item: id, ownerId: record<user> (record-link), containerKey: string, title: string, kind: string, metadata: option<object>, createdAt, updatedAt. Indexed on (ownerId, kind) and (ownerId, createdAt DESC).
- vault_share: forward-declared for future sharing-route follow-up (ownerId: record<user>, granteeId: record<user>, itemId: record<vault_item>, permissions: array<string>, grantedAt, revokedAt: option<datetime>).
DDL uses DEFINE TABLE OVERWRITE for idempotency. Genesis-original (no upstream port; the vault library doesn't define ownership metadata — that's HTTP-layer concern).
applyVaultSchema(adapter): Promise<void> convenience helper. onInit applies via migrationRunner (preferred) or db fallback.

Zod schemas (plug-and-play point 2) — exposed at `./schemas/*`

./schemas/vault-item — VaultItemSchema, VaultItemSummarySchema, VaultItemResponseSchema, VaultItemListResponseSchema, CreateVaultItemBodySchema, UpdateVaultItemBodySchema (strict mode).
./schemas/options — VaultPluginOptionsSchema.

Errors + observability

VaultPluginError extends SuaveplanError<VaultPluginErrorCode> via defineCodes("VAULT_PLUGIN", [...]). Codes: VAULT_PLUGIN_INVALID_INPUT, VAULT_PLUGIN_ITEM_NOT_FOUND, VAULT_PLUGIN_FORBIDDEN, VAULT_PLUGIN_UNLOCK_FAILED, VAULT_PLUGIN_ITEM_TOO_LARGE, VAULT_PLUGIN_SERVICE_NOT_AVAILABLE, VAULT_PLUGIN_SCHEMA_APPLY_FAILED, VAULT_PLUGIN_ROUTE_PREFIX_COLLISION, VAULT_PLUGIN_UNLOCK_HEADER_MISSING.
OTel: counter vault.items.created_total{outcome}, counter vault.items.read_total{outcome}, counter vault.items.updated_total{outcome}, counter vault.items.deleted_total{outcome}, histogram vault.item.size_bytes (on create + update — distribution of item sizes).

Subpath exports

., ./plugin/plugin, ./routes/routes, ./services/vault-service, ./schemas/vault-item, ./schemas/options, ./schema/schema, ./error-codes/error-codes, ./otel/instruments, ./types/types.

Out of scope

Sharing / collaborator endpoints. The vault_share table is forward-declared in the schema but no routes ship — follow-up api-plugin-vault-sharing.
Attachments routes (/vault/items/:id/attachments). Vault library supports attachments; HTTP routes are a follow-up api-plugin-vault-attachments.
Vault discovery / cross-user search. Per-user only in v1.
Vault key escrow / recovery flows. Operator concern; vault library has primitives, this plugin doesn't surface them.
Multi-vault per user. One vault per user in v1; multi-vault is a follow-up.
WebDAV / SFTP gateways. HTTP routes only.

Source mapping

This package is genesis-original. Design intent draws from:

The 3-way plug-and-play contract established by add-api-plugin-auth.
@suaveplan/vault shipped surface (VaultManager, item/attachment APIs).
@suaveplan/api-plugin-auth/middleware/require-auth + Principal.
The legacy enterprise-api-plugin-vault.md proposal's route-surface intent (verbatim: /vault/items CRUD).

Requirement	Source
`definePlugin` consumer w/ `dependencies: ["auth"]`	`@suaveplan/api-plugin`
Per-user scoping via `c.get("user").id`	`@suaveplan/api-plugin-auth` (sibling)
Vault encryption / FSM	`@suaveplan/vault` (shipped)
`RouteBuilder` end-to-end Zod	`@suaveplan/api-openapi` (shipped)
3-way plug-and-play (`.surql` + Zod + OpenAPI)	genesis architectural principle

Impact

Affected dependents

None today — net-new. Future api-plugin-vault-sharing / api-plugin-vault-attachments follow-ups will depend on this.

Catalog additions

None — every dep already in catalogs.

7.1 KiB Raw Blame History