First run of specs

Author: rjzondervan

openspec/ROADMAP.md

@@ -1,34 +1,62 @@
 # Roadmap
 
-This document tracks the planned development of Nextcloud App Template.
+This document tracks the planned development of Doriath.
 
-Features are defined in [`appspec/features/`](../appspec/features/). When a feature reaches `planned` status during an `/app-explore` session, it is listed here and an OpenSpec change is created with `/opsx:ff`.
+Features are defined in [`openspec/specs/`](specs/). When a feature reaches `planned` status it is listed here and an OpenSpec change is created with `/opsx:ff`.
 
 ## Status Overview
 
 | Feature | Status | Priority | OpenSpec Change |
 |---------|--------|----------|----------------|
-| _(no features defined yet — use `/app-explore` to start)_ | — | — | — |
+| [Encryption Suites](specs/encryption-suites/spec.md) | planned | 1 — must be first | — |
+| [Secrets](specs/secrets/spec.md) | planned | 2 | — |
+| [Key Generator](specs/key-generator/spec.md) | planned | 3 — needed for secret creation UI | — |
+| [Application Management](specs/application-mgmt/spec.md) | planned | 4 | — |
+| [User Sharing](specs/user-sharing/spec.md) | planned | 5 | — |
+| [Link Sharing](specs/link-sharing/spec.md) | planned | 6 | — |
+| [Secret Requests](specs/secret-requests/spec.md) | planned | 7 | — |
 
 ## Phases
 
-### Phase 1 — Foundation
+### Phase 1 — Foundation (Core)
 
-_Define the core features needed for a working app. These are the minimum set that make the app useful._
+The minimum set that makes Doriath useful as a secrets manager.
 
-### Phase 2 — Enhancement
+1. **Encryption Suites** — CA bootstrap, key pair generation, user setup on first login
+2. **Secrets** — CRUD with RSA encryption at rest
+3. **Key Generator** — random key generation integrated into secret creation
 
-_Add features that improve the experience, extend functionality, and cover more use cases._
+### Phase 2 — Sharing (Core)
 
-### Phase 3 — Polish
+Features that enable secrets to move between parties.
 
-_Performance, accessibility improvements, full localization, and hardening for production._
+4. **Application Management** — register apps, approval queue, CSR-based EncryptionSuite
+5. **User Sharing** — copy + re-encrypt for Nextcloud users, sync on change
+6. **Link Sharing** — password-protected links with usage limits
+7. **Secret Requests** — fill-in links for write-without-read secrets
+
+### Phase 3 — Advanced (Future)
+
+_Not yet specced. To be explored in future `/opsx:app-explore` sessions._
+
+- Multiple encryption suites per owner (key rotation, compromise recovery)
+- API (basic auth + OAuth)
+- Custom CA chain upload
+- Post-quantum cryptography (when available in PHP)
+
+### Phase 4 — Future Development
+
+_Noted in Vault-app.docx but explicitly out of scope for now._
+
+- Encrypted mail integration
+- Certificate Authority (public CA functionality)
+- File encryption
 
 ---
 
 ## How This Works
 
-1. Run `/app-explore` to define features in `appspec/features/`
+1. Run `/opsx:app-explore` to define or refine features in `openspec/specs/`
 2. When a feature is `planned`, add it to the table above
 3. Run `/opsx:ff {feature-name}` to create the implementation spec
 4. Update the **OpenSpec Change** column with a link to the change directory

openspec/app-config.json

@@ -1,25 +1,30 @@
 {
-  "id": "app-template",
-  "name": "Nextcloud App Template",
-  "namespace": "AppTemplate",
-  "summary": "A template for creating new Nextcloud apps",
-  "goal": "A starting point for building Nextcloud apps following ConductionNL conventions",
-  "category": "tools",
+  "id": "doriath",
+  "name": "Doriath",
+  "namespace": "Doriath",
+  "summary": "Encrypted secrets manager for Nextcloud — password manager and key store for users and applications",
+  "goal": "Securely store and share secrets (passwords, API keys, certificates) for Nextcloud users and applications, using end-to-end RSA/AES encryption backed by a private Certificate Authority",
+  "category": "security",
   "version": "0.1.0",
   "license": "EUPL-1.2",
   "author": "Conduction B.V.",
-  "repository": "https://github.com/ConductionNL/nextcloud-app-template",
+  "repository": "https://github.com/ConductionNL/doriath",
   "dependencies": {
-    "requiresOpenRegister": true,
-    "additionalCiApps": [
-      {"repo": "ConductionNL/openregister", "app": "openregister", "ref": "main"}
-    ]
+    "requiresOpenRegister": false,
+    "additionalCiApps": []
   },
   "cicd": {
     "phpVersions": ["8.3", "8.4"],
     "nextcloudRefs": ["stable31", "stable32"],
     "enableNewman": false
   },
-  "createdAt": "2025-01-01",
+  "architecture": {
+    "dataLayer": "own-database-tables",
+    "pattern": "Thick backend — Doriath owns its own encrypted database tables; no OpenRegister, no n8n",
+    "encryption": "RSA-4096 + AES-256 via OpenSSL; private CA with root and intermediate certificates",
+    "frontend": "Vue 2.7 + Pinia, queries Doriath REST API",
+    "authentication": "Nextcloud session (users) or X-Vault-Password header (external apps)"
+  },
+  "createdAt": "2026-03-23",
   "updatedAt": "2026-03-23"
 }

openspec/architecture/adr-001-own-database-tables.md

@@ -0,0 +1,46 @@
+# ADR-001: Own Database Tables (No OpenRegister)
+
+**Status**: accepted
+
+**Date**: 2026-03-23
+
+## Context
+
+Org-wide ADR-001 mandates that Conduction apps use OpenRegister as their data layer (JSON object storage with schema validation). This keeps data architecture consistent across apps and avoids each app managing its own migrations.
+
+Doriath is a secrets manager that stores highly sensitive encrypted data: private keys (AES-encrypted), encrypted secret values, and Certificate Authority certificates. The security model depends on:
+
+- Strict schema control — encrypted fields must never be accidentally exposed or logged as plain text
+- Fine-grained DB-level isolation — secrets must be queryable by owner and encryption suite without exposing their contents to the query layer
+- No intermediary services in the data path — every hop between Doriath and the database is a potential point of failure or leakage
+
+OpenRegister is a generic JSON object store. It introduces an external service in the data path and provides no mechanism for field-level encryption guarantees. Storing encrypted blobs in OpenRegister's generic object model would mix encrypted and non-encrypted data in a shared store, complicating auditing and access control.
+
+## Decision
+
+Doriath manages its own Doctrine entities and Nextcloud database migrations. It does **not** depend on OpenRegister for any data storage.
+
+This is an explicit app-specific exception to org-wide ADR-001.
+
+Doriath also does **not** use n8n for any internal workflow or automation — all business logic runs directly in PHP.
+
+## Consequences
+
+**Positive:**
+- Full control over schema — encrypted fields are typed and documented at the DB level
+- No external service dependency for core functionality — Doriath works standalone
+- Simpler audit trail — the only path to the data is through Doriath's own controllers and services
+- Migrations use Nextcloud's ISchemaWrapper, keeping the app upgrade path clean
+
+**Negative / trade-offs:**
+- Doriath must maintain its own DB migrations — more maintenance than OpenRegister-managed objects
+- No benefit from OpenRegister's search, filtering, or schema validation infrastructure
+- The thin-client pattern used by other Conduction apps does not apply here — Doriath requires a proper backend service layer
+
+## Alternatives Considered
+
+| Option | Reason not chosen |
+|--------|------------------|
+| OpenRegister JSON object store | Introduces external service in data path; no field-level encryption guarantees; shared object store complicates access control auditing |
+| Nextcloud's UserPreferences / AppConfig | Not suited for structured relational data or large encrypted blobs |
+| External secrets backend (e.g., HashiCorp Vault) | Breaks Nextcloud-native design; introduces dependency outside the Nextcloud instance |

openspec/architecture/adr-002-polymorphic-encryption-suite-ownership.md

@@ -0,0 +1,44 @@
+# ADR-002: Polymorphic Ownership on EncryptionSuite
+
+**Status**: accepted
+
+**Date**: 2026-03-23
+
+## Context
+
+EncryptionSuites — the records that hold a public certificate and AES-encrypted private key — must be owned by either a Nextcloud user or a registered Application. Both owner types require identical encryption operations (generate, revoke, look up by owner).
+
+Two design options exist:
+1. **Separate tables** — `UserEncryptionSuite` and `AppEncryptionSuite`
+2. **Polymorphic association** — single `EncryptionSuite` table with `owner_type` (user|application) and `owner_id` columns
+
+A complicating factor: Nextcloud users are not stored in Doriath's own database — they are managed by Nextcloud's user backend. This means that even with separate tables, the "user" side cannot use a native foreign key constraint to the users table.
+
+## Decision
+
+Use a single `EncryptionSuite` table with polymorphic `owner_type` and `owner_id` columns.
+
+- `owner_type`: enum `user` | `application`
+- `owner_id`: string (Nextcloud user ID, or Doriath Application row ID)
+
+Referential integrity for the `application` owner type is enforced at the application layer with cascade delete logic. For the `user` owner type, a Nextcloud `IUserDeletedEvent` listener handles cleanup.
+
+## Consequences
+
+**Positive:**
+- Single table, single query path for all encryption operations regardless of owner type
+- Owner types are small and fixed (user, application) — no combinatorial explosion
+- Encryption logic is identical regardless of owner type — no branching needed
+- Extension to a third owner type (e.g., group) requires only a new enum value and cleanup listener
+
+**Negative / trade-offs:**
+- No database-level foreign key constraint for owner references — orphan risk must be handled in code
+- Queries filtering by owner require composite index on `(owner_type, owner_id)`
+- Code must explicitly handle the `user` case using Nextcloud's user management interfaces rather than a DB join
+
+## Alternatives Considered
+
+| Option | Reason not chosen |
+|--------|------------------|
+| Separate `UserEncryptionSuite` and `AppEncryptionSuite` tables | Duplicates identical schema and logic; does not solve the FK problem for Nextcloud users anyway |
+| Single table with nullable `user_id` and `application_id` columns | Allows invalid state (both null, or both set); more complex validation; no cleaner than polymorphic |

openspec/architecture/adr-003-rsa-aes-encryption-architecture.md

@@ -0,0 +1,71 @@
+# ADR-003: RSA + AES Encryption Architecture
+
+**Status**: accepted
+
+**Date**: 2026-03-23
+
+## Context
+
+Doriath stores secrets (passwords, API keys, and other sensitive values) for multiple users and applications. The core security requirement is that:
+
+1. Secrets are encrypted at rest and can only be decrypted by the holder of the correct private key
+2. A user or application can write a secret into another party's vault without being able to read it afterwards
+3. Private keys are never stored in plaintext — they are always protected by a master password
+4. The master password is never stored in the database
+
+These requirements rule out symmetric encryption (where the same key encrypts and decrypts, making write-without-read impossible) and any architecture where the server can decrypt secrets without user involvement.
+
+## Decision
+
+Doriath uses a hybrid RSA + AES encryption scheme, implemented via OpenSSL in PHP:
+
+**Secrets are encrypted with RSA (asymmetric):**
+- Each user and application has an EncryptionSuite containing a public/private key pair
+- Secrets are encrypted with the owner's public certificate — only the private key can decrypt them
+- This enables write-without-read: any party can encrypt a secret for an owner without being able to read it back
+- Minimum key size: 4096 bits (system default; only allowed to increase)
+
+**Private keys are encrypted with AES (symmetric):**
+- The private key in each EncryptionSuite is stored AES-256 encrypted using the owner's master password
+- The master password is never stored in the database
+- For Nextcloud users: master password is held in the user session (configurable timeout: session, 10 min, or 30 min)
+- For external applications: master password is passed via the `X-Vault-Password` HTTP header on each request
+
+**Certificate Authority:**
+- A private CA is bootstrapped on first setup: one root certificate and one intermediate certificate
+- User and application public certificates are signed by the intermediate
+- The intermediate's private key is stored AES-encrypted in the database
+- Administrators may upload their own CA chain (root + signing intermediate) instead of using the generated one
+
+**Chunking:**
+- RSA encryption has a per-chunk limit of approximately 500 bytes (key size in bytes − 1 − 11 bytes PKCS#1 padding)
+- Large values (additional fields, future file encryption) must be chunked before encryption
+- Chunking strategy will be defined before implementing support for additional encrypted fields
+
+**Post-quantum note:**
+- Post-quantum cryptography algorithms are not yet available in stable PHP/OpenSSL libraries (as of 2026-03-23)
+- This architecture will need revisiting when post-quantum support becomes available in PHP
+
+## Consequences
+
+**Positive:**
+- Write-without-read is natively supported by asymmetric encryption — no additional mechanism needed
+- OpenSSL compatibility means Doriath encryption suites are interoperable with standard PKI tooling
+- Master password never at rest — even a full DB dump cannot be decrypted without user involvement
+- CA structure enables future Certificate Authority functionality with minimal additional work
+
+**Negative / trade-offs:**
+- Chunking complexity for data larger than ~500 bytes — must be implemented carefully and uniformly
+- Master password in session is a temporary secret that can be lost (session expiry, server restart)
+- If the master password is lost, secrets become permanently inaccessible — no recovery path
+- RSA operations are slower than symmetric encryption — acceptable for secrets (small payloads), not for bulk data
+- Post-quantum vulnerability is a known future risk
+
+## Alternatives Considered
+
+| Option | Reason not chosen |
+|--------|------------------|
+| Symmetric AES only | Cannot support write-without-read; server holds decrypt key — breaks security model |
+| Client-side encryption (encrypt in browser) | Master password never reaches server, but complicates API access for applications; out of scope for current architecture |
+| External KMS (AWS KMS, HashiCorp Vault) | Breaks Nextcloud-native design; adds external dependency and cost |
+| Age / libsodium (modern alternatives to OpenSSL RSA) | Not yet universally available in PHP distributions; post-quantum support also not mature |

openspec/config.yaml

@@ -1,36 +1,45 @@
 schema: conduction
 
 context: |
-  Project: App Template
-  Repo: ConductionNL/nextcloud-app-template
+  Project: Doriath
+  Repo: ConductionNL/doriath
   Type: Nextcloud App (PHP backend + Vue 2 frontend)
-  Description: Starter template for Conduction Nextcloud apps — replace this description with your app's purpose.
-  Key components: Dashboard, Settings, Example objects
-  Database: PostgreSQL (via OpenRegister's ObjectService)
-  Mount path: /var/www/html/custom_apps/app-template
+  Description: Encrypted secrets manager for Nextcloud — stores and shares secrets (passwords, API keys)
+    for users and applications using end-to-end RSA/AES encryption with a private Certificate Authority.
+  Key components: Secrets, EncryptionSuites, CACertificates, Applications, Sharing (user/link/request)
+  Database: PostgreSQL (own tables — does NOT use OpenRegister)
+  Mount path: /var/www/html/custom_apps/doriath
 
   Architecture:
-    Pattern: Thin client — App Template owns no database tables
-    Data layer: OpenRegister (JSON object storage with schema validation)
-    Frontend: Vue 2.7 + Pinia stores querying OpenRegister API directly
-    Backend: Minimal — SettingsController + SettingsService for register setup
+    Pattern: Thick backend — Doriath owns all database tables and handles all encryption server-side
+    Data layer: Own Doctrine entities and migrations (no OpenRegister dependency)
+    Encryption: RSA-4096 for secrets, AES-256 for private keys; OpenSSL; private CA (root + intermediate)
+    Frontend: Vue 2.7 + Pinia stores querying Doriath REST API
+    Backend: Controllers, Services, and Entities for secrets, encryption suites, applications, sharing
+    Master password: Stored in Nextcloud user session or X-Vault-Password HTTP header (never in DB)
 
   Shared specs: See ../openspec/specs/ for cross-project conventions
   Project guidelines: See ../project.md for workspace-wide standards
 
 rules:
   proposal:
-    - Reference shared nextcloud-app spec for app structure requirements
-    - Consider impact on other Conduction apps
+    - Doriath owns its own database — do NOT reference OpenRegister for data storage
+    - Security implications must be explicitly addressed for any feature touching encryption
+    - Consider impact on other Conduction apps only where Doriath acts as a secret provider
   specs:
-    - Use Schema.org type annotations for all entities
-    - Specify which Nextcloud OCP interfaces are used for integration features
+    - Specify which fields are stored encrypted vs plain text
+    - Specify which Nextcloud OCP interfaces are used for session, user, and auth integration
+    - Encryption chunking constraints (RSA cap ~500 bytes/chunk) must be noted for large data fields
   design:
-    - Uses OpenRegister API directly from frontend (no own backend CRUD)
-    - Register config in lib/Settings/app_template_register.json (OpenAPI 3.0.0 format)
-    - Imported via ConfigurationService::importFromApp() in repair step
+    - All encryption/decryption happens in PHP backend using OpenSSL — never in frontend
+    - Private keys are never stored unencrypted — always AES-256 encrypted with master password
+    - Master password is never stored in the database
+    - Migrations must use Nextcloud's ISchemaWrapper pattern
   tasks:
-    - Test with OpenRegister to verify schema validation works
+    - Test encryption round-trips (encrypt → store → retrieve → decrypt) in integration tests
+    - Test that encrypted fields cannot be read without the correct master password
   review:
     - Cross-reference shared specs (nextcloud-app, api-patterns, nl-design, docker)
-    - Flag spec deviations with WARNING and justification
+    - Flag any pattern that stores a private key or master password unencrypted as a BLOCKER
+    - Flag spec deviations from org-wide ADRs with WARNING and justification
+    - ADR-001 (OpenRegister data layer) is explicitly superseded by Doriath ADR-001 for this app