{description}
-{siteConfig.tagline}
-, message:}`
+ * (HTTP 400 or 500).
+ *
+ * @NoAdminRequired
+ * @NoCSRFRequired
+ */
+ #[NoAdminRequired]
+ #[NoCSRFRequired]
+ public function createFile(
+ string $filename='',
+ string $dir='/',
+ string $content=''
+ ): JSONResponse {
+ if ($this->userId === null) {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => 'not_logged_in',
+ 'message' => 'Not logged in',
+ ],
+ statusCode: Http::STATUS_UNAUTHORIZED
+ );
+ }
+
+ try {
+ $result = $this->fileService->createFile(
+ userId: $this->userId,
+ filename: $filename,
+ dir: $dir,
+ content: $content
+ );
+
+ return new JSONResponse(
+ data: [
+ 'status' => 'success',
+ 'fileId' => $result['fileId'],
+ 'url' => $result['url'],
+ ],
+ statusCode: Http::STATUS_OK
+ );
+ } catch (InvalidFilenameException $e) {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => $e->getErrorCode(),
+ 'message' => $e->getDisplayMessage(),
+ ],
+ statusCode: Http::STATUS_BAD_REQUEST
+ );
+ } catch (InvalidDirectoryException $e) {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => $e->getErrorCode(),
+ 'message' => $e->getDisplayMessage(),
+ ],
+ statusCode: Http::STATUS_BAD_REQUEST
+ );
+ } catch (ForbiddenExtensionException $e) {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => $e->getErrorCode(),
+ 'message' => $e->getDisplayMessage(),
+ ],
+ statusCode: Http::STATUS_BAD_REQUEST
+ );
+ } catch (Throwable $e) {
+ // Defence in depth — never leak raw messages.
+ $this->logger->error(
+ message: 'Unexpected file creation failure',
+ context: ['exception' => $e->getMessage()]
+ );
+
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => 'file_creation_failed',
+ 'message' => 'Failed to create file',
+ ],
+ statusCode: Http::STATUS_INTERNAL_SERVER_ERROR
+ );
+ }//end try
+ }//end createFile()
+}//end class
diff --git a/lib/Controller/HealthController.php b/lib/Controller/HealthController.php
index d3d0682f..9222fb14 100644
--- a/lib/Controller/HealthController.php
+++ b/lib/Controller/HealthController.php
@@ -72,7 +72,7 @@ public function index(): JSONResponse
$checks['database'] = 'ok';
} catch (\Exception $e) {
$checks['database'] = 'error';
- $status = 'error';
+ $status = 'error';
$this->logger->error('Health check: database failed', ['exception' => $e->getMessage()]);
}
diff --git a/lib/Controller/MetricsController.php b/lib/Controller/MetricsController.php
index 337b3e0c..3cbf6662 100644
--- a/lib/Controller/MetricsController.php
+++ b/lib/Controller/MetricsController.php
@@ -72,7 +72,14 @@ public function index(): TextPlainResponse
// Info gauge.
$lines[] = '# HELP mydash_info Application information';
$lines[] = '# TYPE mydash_info gauge';
- $lines[] = 'mydash_info{version="'.$appVersion.'",php_version="'.$phpVersion.'",nextcloud_version="'.$ncVersion.'"} 1';
+
+ $labels = sprintf(
+ 'version="%s",php_version="%s",nextcloud_version="%s"',
+ $appVersion,
+ $phpVersion,
+ $ncVersion
+ );
+ $lines[] = 'mydash_info{'.$labels.'} 1';
// Up gauge.
$lines[] = '# HELP mydash_up Whether the application is up';
@@ -83,13 +90,13 @@ public function index(): TextPlainResponse
$this->collectDashboardMetrics(lines: $lines);
// Widgets total.
- $widgetsTotal = $this->countTable(table: 'mydash_widget_placements');
+ $widgetsTotal = $this->countTable(tableName: 'mydash_widget_placements');
$lines[] = '# HELP mydash_widgets_total Total number of widget placements';
$lines[] = '# TYPE mydash_widgets_total gauge';
$lines[] = 'mydash_widgets_total '.$widgetsTotal;
// Tiles total.
- $tilesTotal = $this->countTable(table: 'mydash_tiles');
+ $tilesTotal = $this->countTable(tableName: 'mydash_tiles');
$lines[] = '# HELP mydash_tiles_total Total number of tiles';
$lines[] = '# TYPE mydash_tiles_total gauge';
$lines[] = 'mydash_tiles_total '.$tilesTotal;
diff --git a/lib/Controller/PageController.php b/lib/Controller/PageController.php
index 418da08b..944aa6b2 100644
--- a/lib/Controller/PageController.php
+++ b/lib/Controller/PageController.php
@@ -3,7 +3,11 @@
/**
* PageController
*
- * Controller for rendering the main page.
+ * Controller for rendering the main MyDash workspace page. The workspace
+ * initial-state payload is constructed via
+ * {@see \OCA\MyDash\Service\InitialStateBuilder} per REQ-INIT-001 — direct
+ * calls to IInitialState::provideInitialState are forbidden here (and any
+ * other controller) and enforced by a grep lint test.
*
* @category Controller
* @package OCA\MyDash\Controller
@@ -22,11 +26,21 @@
namespace OCA\MyDash\Controller;
use OCA\MyDash\AppInfo\Application;
+use OCA\MyDash\Db\Dashboard;
+use OCA\MyDash\Service\AdminSettingsService;
+use OCA\MyDash\Service\AdminTemplateService;
+use OCA\MyDash\Service\DashboardService;
+use OCA\MyDash\Service\InitialStateBuilder;
+use OCA\MyDash\Service\Page;
use OCP\AppFramework\Controller;
use OCP\AppFramework\Http\Attribute\NoAdminRequired;
use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
use OCP\AppFramework\Http\TemplateResponse;
+use OCP\AppFramework\Services\IInitialState;
+use OCP\Dashboard\IManager as IDashboardManager;
+use OCP\IGroupManager;
use OCP\IRequest;
+use OCP\IUserSession;
use OCP\Util;
class PageController extends Controller
@@ -34,16 +48,36 @@ class PageController extends Controller
/**
* Constructor
*
- * @param IRequest $request The request.
+ * @param IRequest $request The request.
+ * @param IInitialState $initialState Nextcloud initial-state service.
+ * @param IDashboardManager $dashboardManager Dashboard widget manager.
+ * @param IUserSession $userSession Current user session.
+ * @param IGroupManager $groupManager Group membership lookup.
+ * @param AdminSettingsService $adminSettings MyDash admin settings.
+ * @param DashboardService $dashboardService Dashboard service (active
+ * resolver — REQ-DASH-018).
+ * @param AdminTemplateService $templateService Template service (primary
+ * group resolver —
+ * REQ-TMPL-012).
*/
public function __construct(
IRequest $request,
+ private readonly IInitialState $initialState,
+ private readonly IDashboardManager $dashboardManager,
+ private readonly IUserSession $userSession,
+ private readonly IGroupManager $groupManager,
+ private readonly AdminSettingsService $adminSettings,
+ private readonly DashboardService $dashboardService,
+ private readonly AdminTemplateService $templateService,
) {
parent::__construct(appName: Application::APP_ID, request: $request);
}//end __construct()
/**
- * Render the main index page.
+ * Render the main workspace index page.
+ *
+ * Builds the workspace initial-state payload via InitialStateBuilder
+ * (REQ-INIT-001) and applies it before the template is rendered.
*
* @return TemplateResponse The template response.
*/
@@ -55,7 +89,65 @@ public function index(): TemplateResponse
Util::addStyle(application: Application::APP_ID, file: 'mydash');
// Load all widget scripts so legacy widgets can register their callbacks.
- $this->loadWidgetScripts();
+ $widgets = $this->loadWidgetScripts();
+
+ $user = $this->userSession->getUser();
+ $isAdmin = false;
+ $userId = null;
+ if ($user !== null) {
+ $userId = $user->getUID();
+ $isAdmin = $this->groupManager->isAdmin(userId: $userId);
+ }
+
+ // Resolve the primary group via the canonical REQ-TMPL-012 authority.
+ $primaryGroup = ($userId !== null)
+ ? $this->templateService->resolvePrimaryGroup(userId: $userId)
+ : Dashboard::DEFAULT_GROUP_ID;
+
+ $primaryGroupName = $primaryGroup;
+ if ($primaryGroup !== 'default'
+ && $this->groupManager->groupExists(gid: $primaryGroup) === true
+ ) {
+ $group = $this->groupManager->get(gid: $primaryGroup);
+ if ($group !== null) {
+ $primaryGroupName = $group->getDisplayName();
+ }
+ }
+
+ // Resolve the active dashboard via the REQ-DASH-018 precedence chain.
+ $activeDashboardId = '';
+ $dashboardSource = 'group';
+ if ($userId !== null) {
+ $resolved = $this->dashboardService->resolveActiveDashboard(
+ userId: $userId,
+ primaryGroupId: $primaryGroup
+ );
+ if ($resolved !== null) {
+ $activeDashboardId = (string) $resolved['dashboard']->getUuid();
+ $dashboardSource = $resolved['source'];
+ }
+ }
+
+ $settings = $this->adminSettings->getSettings();
+
+ $builder = new InitialStateBuilder(
+ initialState: $this->initialState,
+ page: Page::WORKSPACE
+ );
+ $builder
+ ->setWidgets(widgets: $this->describeWidgets(widgets: $widgets))
+ ->setLayout(layout: [])
+ ->setPrimaryGroup(primaryGroup: $primaryGroup)
+ ->setPrimaryGroupName(primaryGroupName: $primaryGroupName)
+ ->setIsAdmin(isAdmin: $isAdmin)
+ ->setActiveDashboardId(activeDashboardId: $activeDashboardId)
+ ->setDashboardSource(dashboardSource: $dashboardSource)
+ ->setGroupDashboards(groupDashboards: [])
+ ->setUserDashboards(userDashboards: [])
+ ->setAllowUserDashboards(
+ allowUserDashboards: (bool) ($settings['allowUserDashboards'] ?? false)
+ )
+ ->apply();
return new TemplateResponse(
appName: Application::APP_ID,
@@ -65,20 +157,44 @@ public function index(): TemplateResponse
/**
* Load scripts for all available dashboard widgets.
- * This ensures legacy widgets can register their callbacks via OCA.Dashboard.register.
*
- * @return void
+ * This ensures legacy widgets can register their callbacks via
+ * OCA.Dashboard.register.
+ *
+ * @return array Map of widget id to widget.
*/
- private function loadWidgetScripts(): void
+ private function loadWidgetScripts(): array
{
- $dashboardManager = \OC::$server->get(
- \OCP\Dashboard\IManager::class
- );
- $widgets = $dashboardManager->getWidgets();
+ $widgets = $this->dashboardManager->getWidgets();
foreach ($widgets as $widget) {
// Call the widget's load() method to inject its scripts.
$widget->load();
}
+
+ return $widgets;
}//end loadWidgetScripts()
+
+ /**
+ * Build serialisable widget descriptors for the initial-state payload.
+ *
+ * @param array $widgets Widget map.
+ *
+ * @return array
+ */
+ private function describeWidgets(array $widgets): array
+ {
+ $descriptors = [];
+ foreach ($widgets as $id => $widget) {
+ $descriptors[] = [
+ 'id' => $id,
+ 'title' => $widget->getTitle(),
+ 'iconClass' => $widget->getIconClass(),
+ 'iconUrl' => '',
+ 'url' => $widget->getUrl(),
+ ];
+ }
+
+ return $descriptors;
+ }//end describeWidgets()
}//end class
diff --git a/lib/Controller/ResourceController.php b/lib/Controller/ResourceController.php
new file mode 100644
index 00000000..c60014dc
--- /dev/null
+++ b/lib/Controller/ResourceController.php
@@ -0,0 +1,194 @@
+;base64,...'}`
+ * and returns a standardised `{status, url, name, size}` envelope.
+ *
+ * The read side of the same capability (REQ-RES-006..008 — public
+ * serve + listing) is delivered by `ResourceServeController`, kept in
+ * a sibling class so this controller's dependency graph stays under
+ * the PHPMD CouplingBetweenObjects limit.
+ *
+ * All errors are mapped to a `{status: 'error', error: ,
+ * message: }` envelope — raw exception messages are NEVER
+ * returned to the client.
+ *
+ * @category Controller
+ * @package OCA\MyDash\Controller
+ * @author Conduction b.v.
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Controller;
+
+use OCA\MyDash\Exception\ForbiddenException;
+use OCA\MyDash\Exception\ResourceException;
+use OCA\MyDash\Exception\StorageFailureException;
+use OCA\MyDash\Service\ResourceService;
+use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\JSONResponse;
+use OCP\IGroupManager;
+use OCP\IRequest;
+use OCP\IUserSession;
+use Psr\Log\LoggerInterface;
+use Throwable;
+
+/**
+ * Admin-only resource upload controller.
+ */
+class ResourceController extends Controller
+{
+ /**
+ * Constructor.
+ *
+ * @param IRequest $request The HTTP request.
+ * @param ResourceService $resourceService The upload pipeline.
+ * @param ResourceUploadRequestParser $parser Parses request body.
+ * @param IUserSession $userSession Session accessor.
+ * @param IGroupManager $groupManager Admin checker.
+ * @param LoggerInterface $logger PSR logger.
+ */
+ public function __construct(
+ IRequest $request,
+ private readonly ResourceService $resourceService,
+ private readonly ResourceUploadRequestParser $parser,
+ private readonly IUserSession $userSession,
+ private readonly IGroupManager $groupManager,
+ private readonly LoggerInterface $logger,
+ ) {
+ parent::__construct(
+ appName: 'mydash',
+ request: $request
+ );
+ }//end __construct()
+
+ /**
+ * Handle `POST /api/resources`.
+ *
+ * Reads the raw JSON body from `php://input`, asserts an admin
+ * caller, delegates to ResourceService, and maps the response
+ * (success or any typed exception) to the standardised envelope.
+ *
+ * @return JSONResponse Either the success envelope with
+ * `{status, url, name, size}` or the error
+ * envelope with `{status, error, message}`.
+ *
+ * @NoCSRFRequired
+ */
+ public function upload(): JSONResponse
+ {
+ try {
+ $this->assertAdmin();
+ $base64 = $this->parser->extractBase64(
+ request: $this->request,
+ rawBody: $this->readRequestBody()
+ );
+
+ $result = $this->resourceService->upload(
+ base64DataUrl: $base64
+ );
+
+ return new JSONResponse(
+ data: [
+ 'status' => 'success',
+ 'url' => $result['url'],
+ 'name' => $result['name'],
+ 'size' => $result['size'],
+ ],
+ statusCode: Http::STATUS_OK
+ );
+ } catch (ResourceException $e) {
+ // Log storage failures — these usually indicate an
+ // operational problem (disk, permissions, etc.).
+ if ($e instanceof StorageFailureException) {
+ $this->logger->error(
+ message: 'Resource upload storage failure',
+ context: ['exception' => $e->getMessage()]
+ );
+ }
+
+ return $this->errorResponse(exception: $e);
+ } catch (Throwable $e) {
+ // Defence in depth — never leak raw messages on truly
+ // unexpected paths.
+ $this->logger->error(
+ message: 'Unexpected resource upload failure',
+ context: ['exception' => $e->getMessage()]
+ );
+
+ $fallback = new StorageFailureException(
+ message: 'Failed to store resource'
+ );
+
+ return $this->errorResponse(exception: $fallback);
+ }//end try
+ }//end upload()
+
+ /**
+ * Throw if the current session user is not an admin.
+ *
+ * Delegates to `IGroupManager::isAdmin` — both an unauthenticated
+ * request and an authenticated non-admin produce HTTP 403.
+ *
+ * @return void
+ *
+ * @throws ForbiddenException When the caller is not an admin.
+ */
+ private function assertAdmin(): void
+ {
+ $user = $this->userSession->getUser();
+ if ($user === null) {
+ throw new ForbiddenException();
+ }
+
+ if ($this->groupManager->isAdmin(userId: $user->getUID()) === false) {
+ throw new ForbiddenException();
+ }
+ }//end assertAdmin()
+
+ /**
+ * Read the raw request body.
+ *
+ * Extracted so tests can override the source — `php://input` is
+ * not realistically pluggable in PHPUnit otherwise. Production
+ * code reads from the standard PHP input stream.
+ *
+ * @return string The raw request body.
+ */
+ protected function readRequestBody(): string
+ {
+ return (string) file_get_contents(filename: 'php://input');
+ }//end readRequestBody()
+
+ /**
+ * Build the standardised error envelope from a typed exception.
+ *
+ * @param ResourceException $exception The typed exception.
+ *
+ * @return JSONResponse The error response.
+ */
+ private function errorResponse(ResourceException $exception): JSONResponse
+ {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => $exception->getErrorCode(),
+ 'message' => $exception->getDisplayMessage(),
+ ],
+ statusCode: $exception->getHttpStatus()
+ );
+ }//end errorResponse()
+}//end class
diff --git a/lib/Controller/ResourceServeController.php b/lib/Controller/ResourceServeController.php
new file mode 100644
index 00000000..4a8cdd16
--- /dev/null
+++ b/lib/Controller/ResourceServeController.php
@@ -0,0 +1,300 @@
+getSize()` BEFORE
+ * `getContent()` and refuses anything above the 5 MB upload cap with
+ * HTTP 413. Only reachable via manual filesystem tampering since
+ * REQ-RES-003 caps uploads to 5 MB, but worth the guard.
+ *
+ * Auth: both methods are `#[NoAdminRequired]` — any logged-in user
+ * may read resources (admin gating would lock dashboards out of their
+ * own assets).
+ *
+ * @category Controller
+ * @package OCA\MyDash\Controller
+ * @author Conduction b.v.
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Controller;
+
+use OCA\MyDash\AppInfo\Application;
+use OCA\MyDash\Service\ResourceServeService;
+use OCA\MyDash\Service\ResourceService;
+use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\JSONResponse;
+use OCP\AppFramework\Http\StreamResponse;
+use OCP\IRequest;
+use Psr\Log\LoggerInterface;
+use Throwable;
+
+/**
+ * Public read-side controller for uploaded resources.
+ */
+class ResourceServeController extends Controller
+{
+ /**
+ * Cache directive sent on every served resource (REQ-RES-006).
+ *
+ * @var string
+ */
+ private const CACHE_CONTROL = 'public, max-age=31536000';
+
+ /**
+ * Constructor.
+ *
+ * @param IRequest $request The HTTP request.
+ * @param ResourceServeService $serve Filesystem + formatting helper.
+ * @param LoggerInterface $logger PSR logger.
+ */
+ public function __construct(
+ IRequest $request,
+ private readonly ResourceServeService $serve,
+ private readonly LoggerInterface $logger,
+ ) {
+ parent::__construct(
+ appName: Application::APP_ID,
+ request: $request
+ );
+ }//end __construct()
+
+ /**
+ * Handle `GET /apps/mydash/resource/{filename}` — serve raw bytes.
+ *
+ * Returns a `StreamResponse` with extension-derived `Content-Type`
+ * and a one-year immutable `Cache-Control` header. Path traversal
+ * and missing files yield a flat HTTP 404 (no detail leaked).
+ * Files larger than the 5 MB upload cap (REQ-RES-003) — only
+ * reachable via manual filesystem tampering — are refused with
+ * HTTP 413 BEFORE any bytes are loaded into memory.
+ *
+ * Cache busting: REQ-RES-004 mandates a `uniqid` suffix on every
+ * uploaded filename, so the one-year cache is safe — a logical
+ * asset change yields a brand-new filename, naturally bypassing
+ * the previously cached entry.
+ *
+ * @param string $filename The leaf filename inside the resources folder.
+ *
+ * @return StreamResponse|JSONResponse Stream on success, JSON envelope on error.
+ *
+ * @NoAdminRequired
+ * @NoCSRFRequired
+ */
+ public function getResource(string $filename): StreamResponse|JSONResponse
+ {
+ if ($this->isUnsafeFilename(filename: $filename) === true) {
+ return $this->notFoundResponse();
+ }
+
+ $file = $this->serve->findFile(filename: $filename);
+ if ($file === null) {
+ return $this->notFoundResponse();
+ }
+
+ // 413 guard — refuse oversize files BEFORE pulling bytes.
+ if ((int) $file->getSize() > ResourceService::MAX_BYTES) {
+ return new JSONResponse(
+ data: [
+ 'status' => 'error',
+ 'error' => 'file_too_large',
+ ],
+ statusCode: Http::STATUS_REQUEST_ENTITY_TOO_LARGE
+ );
+ }
+
+ try {
+ $bytes = $file->getContent();
+ } catch (Throwable $e) {
+ $this->logger->warning(
+ message: 'Resource serve failed to read bytes',
+ context: ['exception' => $e->getMessage()]
+ );
+
+ return $this->notFoundResponse();
+ }
+
+ return $this->buildStreamResponse(filename: $filename, bytes: $bytes);
+ }//end getResource()
+
+ /**
+ * Handle `GET /api/resources` — list uploaded resources.
+ *
+ * Returns `{status: 'success', resources: [{name, url, size,
+ * modifiedAt}, …]}` ordered by `modifiedAt` descending. When the
+ * `resources/` folder does not yet exist (or any other read error
+ * occurs) the response is HTTP 200 with `{status: 'success',
+ * resources: []}` — never a 404.
+ *
+ * The returned `url` values point at the serve route added by
+ * `getResource`. Cache busting falls out of the `uniqid` suffix
+ * REQ-RES-004 puts on every filename — a logical asset change
+ * yields a new name and a fresh cache entry.
+ *
+ * @return JSONResponse The list envelope.
+ *
+ * @NoAdminRequired
+ * @NoCSRFRequired
+ */
+ public function listResources(): JSONResponse
+ {
+ $files = $this->serve->listFiles();
+
+ $resources = [];
+ foreach ($files as $file) {
+ $name = $file->getName();
+ $resources[] = [
+ 'name' => $name,
+ 'url' => ('/apps/'.Application::APP_ID.'/resource/'.$name),
+ 'size' => (int) $file->getSize(),
+ 'modifiedAt' => $this->serve->formatTimestamp(epoch: $file->getMTime()),
+ '_mtime' => $file->getMTime(),
+ ];
+ }
+
+ // Sort newest first by mtime, then strip the helper key.
+ usort(
+ array: $resources,
+ callback: static function (array $left, array $right): int {
+ return ($right['_mtime'] <=> $left['_mtime']);
+ }
+ );
+
+ $resources = array_map(
+ callback: static function (array $entry): array {
+ unset($entry['_mtime']);
+ return $entry;
+ },
+ array: $resources
+ );
+
+ return new JSONResponse(
+ data: [
+ 'status' => 'success',
+ 'resources' => $resources,
+ ],
+ statusCode: Http::STATUS_OK
+ );
+ }//end listResources()
+
+ /**
+ * Decide whether a route filename argument is unsafe.
+ *
+ * Treats empty values, `.`, `..`, and any value containing `/`,
+ * `\`, or `..` as unsafe. The route requirement `[^/]+` already
+ * blocks `/`, but the others are caught here as defence in depth.
+ *
+ * @param string $filename The filename argument from the route.
+ *
+ * @return bool True if the value is unsafe and MUST yield HTTP 404.
+ */
+ private function isUnsafeFilename(string $filename): bool
+ {
+ if ($filename === '' || $filename === '.' || $filename === '..') {
+ return true;
+ }
+
+ if (str_contains(haystack: $filename, needle: '/') === true) {
+ return true;
+ }
+
+ if (str_contains(haystack: $filename, needle: '\\') === true) {
+ return true;
+ }
+
+ if (str_contains(haystack: $filename, needle: '..') === true) {
+ return true;
+ }
+
+ return false;
+ }//end isUnsafeFilename()
+
+ /**
+ * Build the StreamResponse for a successful serve.
+ *
+ * Allocates a `php://memory` stream, writes the bytes, rewinds,
+ * and attaches the standard headers. Streaming via `php://memory`
+ * is bounded by the 5 MB cap (REQ-RES-008).
+ *
+ * @param string $filename The filename being served (for Content-Type).
+ * @param string $bytes The raw bytes to stream.
+ *
+ * @return StreamResponse|JSONResponse The stream, or a 404 envelope
+ * if the memory stream cannot
+ * be allocated.
+ */
+ private function buildStreamResponse(string $filename, string $bytes): StreamResponse|JSONResponse
+ {
+ $stream = fopen(filename: 'php://memory', mode: 'r+b');
+ if ($stream === false) {
+ return $this->notFoundResponse();
+ }
+
+ fwrite(stream: $stream, data: $bytes);
+ rewind(stream: $stream);
+
+ $response = new StreamResponse(filePath: $stream);
+ $response->addHeader(
+ name: 'Content-Type',
+ value: $this->serve->contentTypeForFilename(filename: $filename)
+ );
+ $response->addHeader(name: 'Cache-Control', value: self::CACHE_CONTROL);
+ $response->addHeader(
+ name: 'Content-Length',
+ value: (string) strlen(string: $bytes)
+ );
+
+ return $response;
+ }//end buildStreamResponse()
+
+ /**
+ * Build the empty 404 envelope.
+ *
+ * Body is intentionally empty — callers MUST NOT leak which
+ * specific failure mode tripped (missing file vs. blocked
+ * traversal vs. permissions); a uniform 404 is the contract.
+ *
+ * @return JSONResponse The empty 404 envelope.
+ */
+ private function notFoundResponse(): JSONResponse
+ {
+ return new JSONResponse(
+ data: [],
+ statusCode: Http::STATUS_NOT_FOUND
+ );
+ }//end notFoundResponse()
+}//end class
diff --git a/lib/Controller/ResourceUploadRequestParser.php b/lib/Controller/ResourceUploadRequestParser.php
new file mode 100644
index 00000000..a30e57ce
--- /dev/null
+++ b/lib/Controller/ResourceUploadRequestParser.php
@@ -0,0 +1,88 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Controller;
+
+use JsonException;
+use OCA\MyDash\Exception\InvalidDataUrlException;
+use OCA\MyDash\Exception\UnsupportedMediaTypeException;
+use OCP\IRequest;
+
+/**
+ * Parses request bodies for the resource upload endpoint.
+ */
+class ResourceUploadRequestParser
+{
+ /**
+ * Extract the `base64` field from the raw JSON body.
+ *
+ * @param IRequest $request The HTTP request.
+ * @param string $rawBody The raw request body bytes.
+ *
+ * @return string The base64 data URL.
+ *
+ * @throws UnsupportedMediaTypeException When the request looks
+ * like multipart instead of
+ * JSON.
+ * @throws InvalidDataUrlException When the body is missing,
+ * not JSON, or lacks the
+ * `base64` field.
+ */
+ public function extractBase64(IRequest $request, string $rawBody): string
+ {
+ $contentType = (string) $request->getHeader(name: 'Content-Type');
+ if ($contentType !== '' && stripos(
+ haystack: $contentType,
+ needle: 'multipart/form-data'
+ ) !== false
+ ) {
+ throw new UnsupportedMediaTypeException();
+ }
+
+ if ($rawBody === '') {
+ throw new InvalidDataUrlException();
+ }
+
+ try {
+ $decoded = json_decode(
+ json: $rawBody,
+ associative: true,
+ depth: 4,
+ flags: JSON_THROW_ON_ERROR
+ );
+ } catch (JsonException $e) {
+ throw new InvalidDataUrlException(
+ message: 'Body must be valid JSON'
+ );
+ }
+
+ if (is_array(value: $decoded) === false
+ || isset($decoded['base64']) === false
+ || is_string(value: $decoded['base64']) === false
+ ) {
+ throw new InvalidDataUrlException();
+ }
+
+ return $decoded['base64'];
+ }//end extractBase64()
+}//end class
diff --git a/lib/Db/AdminSetting.php b/lib/Db/AdminSetting.php
index 0f88befa..b45b55b4 100644
--- a/lib/Db/AdminSetting.php
+++ b/lib/Db/AdminSetting.php
@@ -66,6 +66,14 @@ class AdminSetting extends Entity implements JsonSerializable
*/
public const KEY_DEFAULT_GRID_COLUMNS = 'default_grid_columns';
+ /**
+ * Setting key for the ordered list of "active" Nextcloud group IDs that
+ * MyDash treats as in scope for workspace routing (REQ-ASET-012).
+ *
+ * @var string
+ */
+ public const KEY_GROUP_ORDER = 'group_order';
+
/**
* The setting key.
*
@@ -123,9 +131,11 @@ public function getValueDecoded(): mixed
*/
public function setValueEncoded(mixed $value): void
{
- $this->setSettingValue(
- settingValue: json_encode(value: $value)
- );
+ // Entity setters resolve via __call which forwards $args[0]; named
+ // parameters MUST NOT be used here (Entity __call would receive
+ // $args = ['paramName' => $value] and use the wrong key).
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $this->setSettingValue(json_encode($value));
}//end setValueEncoded()
/**
diff --git a/lib/Db/ConditionalRule.php b/lib/Db/ConditionalRule.php
index de5e1d43..e9e8158d 100644
--- a/lib/Db/ConditionalRule.php
+++ b/lib/Db/ConditionalRule.php
@@ -150,7 +150,10 @@ public function getRuleConfigArray(): array
*/
public function setRuleConfigArray(array $config): void
{
- $this->setRuleConfig(ruleConfig: json_encode(value: $config));
+ // Entity setters resolve via __call which uses $args[0]; named args
+ // would break the magic forwarding (see project memory).
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $this->setRuleConfig(json_encode($config));
}//end setRuleConfigArray()
/**
diff --git a/lib/Db/Dashboard.php b/lib/Db/Dashboard.php
index 582f0e5d..af867c53 100644
--- a/lib/Db/Dashboard.php
+++ b/lib/Db/Dashboard.php
@@ -37,6 +37,8 @@
* @method void setType(?string $type)
* @method string|null getUserId()
* @method void setUserId(?string $userId)
+ * @method string|null getGroupId()
+ * @method void setGroupId(?string $groupId)
* @method int|null getBasedOnTemplate()
* @method void setBasedOnTemplate(?int $basedOnTemplate)
* @method int getGridColumns()
@@ -71,6 +73,58 @@ class Dashboard extends Entity implements JsonSerializable
*/
public const TYPE_USER = 'user';
+ /**
+ * Dashboard type for group-shared dashboards.
+ *
+ * Group-shared dashboards are admin-authored, scoped to a single
+ * Nextcloud group via the {@see Dashboard::$groupId} field, and
+ * rendered live (not copied) to every member of that group.
+ * REQ-DASH-011.
+ *
+ * @var string
+ */
+ public const TYPE_GROUP_SHARED = 'group_shared';
+
+ /**
+ * Synthetic group sentinel meaning "visible to every user".
+ *
+ * Reserved literal value for the {@see Dashboard::$groupId} field
+ * on group-shared dashboards. REQ-DASH-012.
+ *
+ * @var string
+ */
+ public const DEFAULT_GROUP_ID = 'default';
+
+ /**
+ * Source tag indicating a personal user-owned dashboard.
+ *
+ * Used in the `/api/dashboards/visible` payload only — never
+ * persisted on the entity. REQ-DASH-013.
+ *
+ * @var string
+ */
+ public const SOURCE_USER = 'user';
+
+ /**
+ * Source tag indicating a group-matched group-shared dashboard.
+ *
+ * Used in the `/api/dashboards/visible` payload only — never
+ * persisted on the entity. REQ-DASH-013.
+ *
+ * @var string
+ */
+ public const SOURCE_GROUP = 'group';
+
+ /**
+ * Source tag indicating a default-group group-shared dashboard.
+ *
+ * Used in the `/api/dashboards/visible` payload only — never
+ * persisted on the entity. REQ-DASH-013.
+ *
+ * @var string
+ */
+ public const SOURCE_DEFAULT = 'default';
+
/**
* Permission level for view only.
*
@@ -127,6 +181,18 @@ class Dashboard extends Entity implements JsonSerializable
*/
protected ?string $userId = null;
+ /**
+ * The group ID for group-shared dashboards.
+ *
+ * Populated only when {@see Dashboard::$type} equals
+ * {@see Dashboard::TYPE_GROUP_SHARED}. The literal value
+ * {@see Dashboard::DEFAULT_GROUP_ID} is reserved as a "visible to
+ * every user" sentinel. REQ-DASH-011, REQ-DASH-012.
+ *
+ * @var string|null
+ */
+ protected ?string $groupId = null;
+
/**
* The template ID this dashboard is based on.
*
@@ -230,7 +296,10 @@ public function getTargetGroupsArray(): array
*/
public function setTargetGroupsArray(array $groups): void
{
- $this->setTargetGroups(targetGroups: json_encode(value: $groups));
+ // Entity setters resolve via __call which uses $args[0]; named args
+ // would break the magic forwarding (see project memory).
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $this->setTargetGroups(json_encode($groups));
}//end setTargetGroupsArray()
/**
@@ -247,6 +316,7 @@ public function jsonSerialize(): array
'description' => $this->description,
'type' => $this->type,
'userId' => $this->userId,
+ 'groupId' => $this->groupId,
'basedOnTemplate' => $this->basedOnTemplate,
'gridColumns' => $this->gridColumns,
'permissionLevel' => $this->permissionLevel,
diff --git a/lib/Db/DashboardMapper.php b/lib/Db/DashboardMapper.php
index b6d44e9d..a98ba371 100644
--- a/lib/Db/DashboardMapper.php
+++ b/lib/Db/DashboardMapper.php
@@ -33,6 +33,8 @@
* Mapper for dashboard entities.
*
* @extends QBMapper
+ *
+ * @SuppressWarnings(PHPMD.TooManyPublicMethods)
*/
class DashboardMapper extends QBMapper
{
@@ -311,6 +313,333 @@ public function setActive(int $dashboardId, string $userId): void
$qb->executeStatement();
}//end setActive()
+ /**
+ * Find all group-shared dashboards for a single group.
+ *
+ * Issues `WHERE type = 'group_shared' AND group_id = ?`. Used by the
+ * group-scoped CRUD endpoints (REQ-DASH-014). The `default` group is
+ * looked up the same way as any other group ID.
+ *
+ * @param string $groupId The group ID (real Nextcloud group ID, or
+ * the literal {@see Dashboard::DEFAULT_GROUP_ID}
+ * sentinel).
+ *
+ * @return Dashboard[] The group-shared dashboards in that group.
+ */
+ public function findByGroup(string $groupId): array
+ {
+ $qb = $this->db->getQueryBuilder();
+ $qb->select(selects: '*')
+ ->from(from: $this->getTableName())
+ ->where(
+ $qb->expr()->eq(
+ x: 'type',
+ y: $qb->createNamedParameter(
+ value: Dashboard::TYPE_GROUP_SHARED
+ )
+ )
+ )
+ ->andWhere(
+ $qb->expr()->eq(
+ x: 'group_id',
+ y: $qb->createNamedParameter(value: $groupId)
+ )
+ )
+ ->orderBy(sort: 'created_at', order: 'ASC');
+
+ return $this->findEntities(query: $qb);
+ }//end findByGroup()
+
+ /**
+ * Find all dashboards visible to a user.
+ *
+ * Issues three indexed queries — personal `user`-type rows owned by
+ * the user, `group_shared` rows whose `group_id` is in the user's
+ * group memberships, and `group_shared` rows whose `group_id` equals
+ * the {@see Dashboard::DEFAULT_GROUP_ID} sentinel — and unions /
+ * dedupes the results by UUID. Each result row carries an extra
+ * `_source` key (`'user'`, `'group'`, or `'default'`) so the caller
+ * can attach the source field to the response. REQ-DASH-013.
+ *
+ * Priority order on UUID overlap is: user > group > default. This
+ * keeps the `source` field deterministic when a user is in the
+ * group _and_ also receives the dashboard via the default sentinel
+ * (rare but handled).
+ *
+ * @param string $userId The user ID.
+ * @param string[] $userGroupIds The user's Nextcloud group IDs.
+ *
+ * @return array
+ * List of {dashboard, source} pairs, deduplicated by dashboard UUID.
+ */
+ public function findVisibleToUser(
+ string $userId,
+ array $userGroupIds
+ ): array {
+ $personal = $this->findByUserId(userId: $userId);
+
+ $groupRows = [];
+ if (empty($userGroupIds) === false) {
+ $groupRows = $this->findGroupSharedInGroups(
+ groupIds: $userGroupIds
+ );
+ }
+
+ $defaultRows = $this->findByGroup(
+ groupId: Dashboard::DEFAULT_GROUP_ID
+ );
+
+ // Dedup by UUID with priority user > group > default.
+ $seen = [];
+ $result = [];
+
+ foreach ($personal as $dashboard) {
+ $uuid = (string) $dashboard->getUuid();
+ if (isset($seen[$uuid]) === true) {
+ continue;
+ }
+
+ $seen[$uuid] = true;
+ $result[] = [
+ 'dashboard' => $dashboard,
+ 'source' => Dashboard::SOURCE_USER,
+ ];
+ }
+
+ foreach ($groupRows as $dashboard) {
+ $uuid = (string) $dashboard->getUuid();
+ if (isset($seen[$uuid]) === true) {
+ continue;
+ }
+
+ // The default-group sentinel rows are filtered out of the
+ // group-bucket so they always appear under SOURCE_DEFAULT.
+ if ($dashboard->getGroupId() === Dashboard::DEFAULT_GROUP_ID) {
+ continue;
+ }
+
+ $seen[$uuid] = true;
+ $result[] = [
+ 'dashboard' => $dashboard,
+ 'source' => Dashboard::SOURCE_GROUP,
+ ];
+ }
+
+ foreach ($defaultRows as $dashboard) {
+ $uuid = (string) $dashboard->getUuid();
+ if (isset($seen[$uuid]) === true) {
+ continue;
+ }
+
+ $seen[$uuid] = true;
+ $result[] = [
+ 'dashboard' => $dashboard,
+ 'source' => Dashboard::SOURCE_DEFAULT,
+ ];
+ }
+
+ return $result;
+ }//end findVisibleToUser()
+
+ /**
+ * Find group-shared dashboards whose group_id is in the supplied list.
+ *
+ * Helper for {@see DashboardMapper::findVisibleToUser()}. Hits the
+ * `(type, group_id)` composite index.
+ *
+ * @param string[] $groupIds The group IDs to match.
+ *
+ * @return Dashboard[] The matching group-shared dashboards.
+ */
+ private function findGroupSharedInGroups(array $groupIds): array
+ {
+ if (empty($groupIds) === true) {
+ return [];
+ }
+
+ $qb = $this->db->getQueryBuilder();
+ $qb->select(selects: '*')
+ ->from(from: $this->getTableName())
+ ->where(
+ $qb->expr()->eq(
+ x: 'type',
+ y: $qb->createNamedParameter(
+ value: Dashboard::TYPE_GROUP_SHARED
+ )
+ )
+ )
+ ->andWhere(
+ $qb->expr()->in(
+ x: 'group_id',
+ y: $qb->createNamedParameter(
+ value: $groupIds,
+ type: IQueryBuilder::PARAM_STR_ARRAY
+ )
+ )
+ )
+ ->orderBy(sort: 'created_at', order: 'ASC');
+
+ return $this->findEntities(query: $qb);
+ }//end findGroupSharedInGroups()
+
+ /**
+ * Count group-shared dashboards in a single group.
+ *
+ * Used by the last-in-group delete guard (REQ-DASH-014).
+ *
+ * @param string $groupId The group ID.
+ *
+ * @return int The number of group-shared dashboards in that group.
+ */
+ public function countByGroup(string $groupId): int
+ {
+ $qb = $this->db->getQueryBuilder();
+ $qb->select($qb->func()->count('*', 'cnt'))
+ ->from(from: $this->getTableName())
+ ->where(
+ $qb->expr()->eq(
+ x: 'type',
+ y: $qb->createNamedParameter(
+ value: Dashboard::TYPE_GROUP_SHARED
+ )
+ )
+ )
+ ->andWhere(
+ $qb->expr()->eq(
+ x: 'group_id',
+ y: $qb->createNamedParameter(value: $groupId)
+ )
+ );
+
+ $cursor = $qb->executeQuery();
+ $row = $cursor->fetch();
+ $cursor->closeCursor();
+
+ if ($row === false || isset($row['cnt']) === false) {
+ return 0;
+ }
+
+ return (int) $row['cnt'];
+ }//end countByGroup()
+
+ /**
+ * Clear default flag on every group-shared dashboard in a group.
+ *
+ * Issues `UPDATE oc_mydash_dashboards SET is_default = 0 WHERE
+ * type = 'group_shared' AND group_id = ? [AND uuid <> ?]`. Used by
+ * {@see \OCA\MyDash\Service\DashboardService::setGroupDefault()} as
+ * the first half of the transactional flip. REQ-DASH-015.
+ *
+ * @param string $groupId The group ID (real or
+ * {@see Dashboard::DEFAULT_GROUP_ID}).
+ * @param string|null $exceptUuid Optional uuid to leave untouched
+ * (avoids a no-op write on the row that
+ * will immediately be set to 1).
+ *
+ * @return int The number of rows affected.
+ */
+ public function clearGroupDefaults(
+ string $groupId,
+ ?string $exceptUuid=null
+ ): int {
+ $qb = $this->db->getQueryBuilder();
+ $qb->update(update: $this->getTableName())
+ ->set(
+ key: 'is_default',
+ value: $qb->createNamedParameter(
+ value: 0,
+ type: IQueryBuilder::PARAM_INT
+ )
+ )
+ ->set(
+ key: 'updated_at',
+ value: $qb->createNamedParameter(
+ value: (new DateTime())->format(format: 'Y-m-d H:i:s')
+ )
+ )
+ ->where(
+ $qb->expr()->eq(
+ x: 'type',
+ y: $qb->createNamedParameter(
+ value: Dashboard::TYPE_GROUP_SHARED
+ )
+ )
+ )
+ ->andWhere(
+ $qb->expr()->eq(
+ x: 'group_id',
+ y: $qb->createNamedParameter(value: $groupId)
+ )
+ );
+
+ if ($exceptUuid !== null) {
+ $qb->andWhere(
+ $qb->expr()->neq(
+ x: 'uuid',
+ y: $qb->createNamedParameter(value: $exceptUuid)
+ )
+ );
+ }
+
+ return $qb->executeStatement();
+ }//end clearGroupDefaults()
+
+ /**
+ * Set the default flag on a single group-shared dashboard.
+ *
+ * Issues `UPDATE oc_mydash_dashboards SET is_default = 1 WHERE
+ * type = 'group_shared' AND group_id = ? AND uuid = ?`. Returns the
+ * row-count affected — `0` when the uuid does not belong to the
+ * given group (caller treats as 404). REQ-DASH-015.
+ *
+ * @param string $groupId The group ID from the URL.
+ * @param string $uuid The dashboard UUID from the URL.
+ *
+ * @return int The number of rows affected (0 or 1).
+ */
+ public function setGroupDefaultUuid(
+ string $groupId,
+ string $uuid
+ ): int {
+ $qb = $this->db->getQueryBuilder();
+ $qb->update(update: $this->getTableName())
+ ->set(
+ key: 'is_default',
+ value: $qb->createNamedParameter(
+ value: 1,
+ type: IQueryBuilder::PARAM_INT
+ )
+ )
+ ->set(
+ key: 'updated_at',
+ value: $qb->createNamedParameter(
+ value: (new DateTime())->format(format: 'Y-m-d H:i:s')
+ )
+ )
+ ->where(
+ $qb->expr()->eq(
+ x: 'type',
+ y: $qb->createNamedParameter(
+ value: Dashboard::TYPE_GROUP_SHARED
+ )
+ )
+ )
+ ->andWhere(
+ $qb->expr()->eq(
+ x: 'group_id',
+ y: $qb->createNamedParameter(value: $groupId)
+ )
+ )
+ ->andWhere(
+ $qb->expr()->eq(
+ x: 'uuid',
+ y: $qb->createNamedParameter(value: $uuid)
+ )
+ );
+
+ return $qb->executeStatement();
+ }//end setGroupDefaultUuid()
+
/**
* Clear default flag on all admin templates.
*
diff --git a/lib/Db/DashboardShare.php b/lib/Db/DashboardShare.php
new file mode 100644
index 00000000..2f76ffb5
--- /dev/null
+++ b/lib/Db/DashboardShare.php
@@ -0,0 +1,153 @@
+
+ * @copyright 2026 Conduction b.v.
+ * @license https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12 EUPL-1.2
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2026 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Db;
+
+use JsonSerializable;
+use OCP\AppFramework\Db\Entity;
+
+/**
+ * Dashboard share entity.
+ *
+ * @method int|null getDashboardId()
+ * @method void setDashboardId(?int $dashboardId)
+ * @method string|null getShareType()
+ * @method void setShareType(?string $shareType)
+ * @method string|null getShareWith()
+ * @method void setShareWith(?string $shareWith)
+ * @method string|null getPermissionLevel()
+ * @method void setPermissionLevel(?string $permissionLevel)
+ * @method string|null getCreatedAt()
+ * @method void setCreatedAt(?string $createdAt)
+ * @method string|null getUpdatedAt()
+ * @method void setUpdatedAt(?string $updatedAt)
+ */
+class DashboardShare extends Entity implements JsonSerializable
+{
+
+ /**
+ * Share type for a single user recipient.
+ *
+ * @var string
+ */
+ public const SHARE_TYPE_USER = 'user';
+
+ /**
+ * Share type for a Nextcloud group recipient.
+ *
+ * @var string
+ */
+ public const SHARE_TYPE_GROUP = 'group';
+
+ /**
+ * Valid share types.
+ *
+ * @var string[]
+ */
+ public const VALID_SHARE_TYPES = [
+ self::SHARE_TYPE_USER,
+ self::SHARE_TYPE_GROUP,
+ ];
+
+ /**
+ * Valid permission levels (mirrors Dashboard constants).
+ *
+ * @var string[]
+ */
+ public const VALID_PERMISSION_LEVELS = [
+ Dashboard::PERMISSION_VIEW_ONLY,
+ Dashboard::PERMISSION_ADD_ONLY,
+ Dashboard::PERMISSION_FULL,
+ ];
+
+ /**
+ * The dashboard ID.
+ *
+ * @var integer|null
+ */
+ protected ?int $dashboardId = null;
+
+ /**
+ * The share type ('user' or 'group').
+ *
+ * @var string|null
+ */
+ protected ?string $shareType = null;
+
+ /**
+ * The recipient user ID or group ID.
+ *
+ * @var string|null
+ */
+ protected ?string $shareWith = null;
+
+ /**
+ * The permission level.
+ *
+ * @var string|null
+ */
+ protected ?string $permissionLevel = null;
+
+ /**
+ * The creation timestamp.
+ *
+ * @var string|null
+ */
+ protected ?string $createdAt = null;
+
+ /**
+ * The update timestamp.
+ *
+ * @var string|null
+ */
+ protected ?string $updatedAt = null;
+
+ /**
+ * Constructor — registers column types.
+ *
+ * @return void
+ */
+ public function __construct()
+ {
+ $this->addType(fieldName: 'id', type: 'integer');
+ $this->addType(fieldName: 'dashboardId', type: 'integer');
+ }//end __construct()
+
+ /**
+ * Serialize to JSON.
+ *
+ * @return array The serialized share.
+ */
+ public function jsonSerialize(): array
+ {
+ return [
+ 'id' => $this->getId(),
+ 'dashboardId' => $this->dashboardId,
+ 'shareType' => $this->shareType,
+ 'shareWith' => $this->shareWith,
+ 'permissionLevel' => $this->permissionLevel,
+ 'createdAt' => $this->createdAt,
+ 'updatedAt' => $this->updatedAt,
+ ];
+ }//end jsonSerialize()
+}//end class
diff --git a/lib/Db/DashboardShareMapper.php b/lib/Db/DashboardShareMapper.php
new file mode 100644
index 00000000..0db49cdd
--- /dev/null
+++ b/lib/Db/DashboardShareMapper.php
@@ -0,0 +1,327 @@
+
+ * @copyright 2026 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2026 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Db;
+
+use OCP\AppFramework\Db\DoesNotExistException;
+use OCP\AppFramework\Db\QBMapper;
+use OCP\DB\QueryBuilder\IQueryBuilder;
+use OCP\IDBConnection;
+
+/**
+ * Mapper for DashboardShare entities.
+ *
+ * @extends QBMapper
+ */
+class DashboardShareMapper extends QBMapper
+{
+ /**
+ * Constructor
+ *
+ * @param IDBConnection $db The database connection.
+ */
+ public function __construct(IDBConnection $db)
+ {
+ parent::__construct(
+ db: $db,
+ tableName: 'mydash_dashboard_shares',
+ entityClass: DashboardShare::class
+ );
+ }//end __construct()
+
+ /**
+ * Find a share by ID.
+ *
+ * @param int $id The share ID.
+ *
+ * @return DashboardShare The share.
+ *
+ * @throws DoesNotExistException When not found.
+ */
+ public function find(int $id): DashboardShare
+ {
+ $qb = $this->db->getQueryBuilder();
+ $qb->select(selects: '*')
+ ->from(from: $this->getTableName())
+ ->where(
+ $qb->expr()->eq(
+ x: 'id',
+ y: $qb->createNamedParameter(
+ value: $id,
+ type: IQueryBuilder::PARAM_INT
+ )
+ )
+ );
+
+ return $this->findEntity(query: $qb);
+ }//end find()
+
+ /**
+ * Find all shares for a dashboard.
+ *
+ * @param int $dashboardId The dashboard ID.
+ *
+ * @return DashboardShare[] The shares.
+ */
+ public function findByDashboardId(int $dashboardId): array
+ {
+ $qb = $this->db->getQueryBuilder();
+ $qb->select(selects: '*')
+ ->from(from: $this->getTableName())
+ ->where(
+ $qb->expr()->eq(
+ x: 'dashboard_id',
+ y: $qb->createNamedParameter(
+ value: $dashboardId,
+ type: IQueryBuilder::PARAM_INT
+ )
+ )
+ )
+ ->orderBy(sort: 'created_at', order: 'ASC');
+
+ return $this->findEntities(query: $qb);
+ }//end findByDashboardId()
+
+ /**
+ * Find shares for a dashboard with a specific permission level.
+ *
+ * @param int $dashboardId The dashboard ID.
+ * @param string $permissionLevel The required permission level.
+ *
+ * @return DashboardShare[] The shares.
+ */
+ public function findByDashboardAndLevel(
+ int $dashboardId,
+ string $permissionLevel
+ ): array {
+ $qb = $this->db->getQueryBuilder();
+ $qb->select(selects: '*')
+ ->from(from: $this->getTableName())
+ ->where(
+ $qb->expr()->eq(
+ x: 'dashboard_id',
+ y: $qb->createNamedParameter(
+ value: $dashboardId,
+ type: IQueryBuilder::PARAM_INT
+ )
+ )
+ )
+ ->andWhere(
+ $qb->expr()->eq(
+ x: 'permission_level',
+ y: $qb->createNamedParameter(value: $permissionLevel)
+ )
+ )
+ ->orderBy(sort: 'created_at', order: 'ASC');
+
+ return $this->findEntities(query: $qb);
+ }//end findByDashboardAndLevel()
+
+ /**
+ * Find a specific share by (dashboardId, shareType, shareWith).
+ *
+ * Returns null when not found (no exception).
+ *
+ * @param int $dashboardId The dashboard ID.
+ * @param string $shareType The share type.
+ * @param string $shareWith The recipient.
+ *
+ * @return DashboardShare|null The share or null.
+ */
+ public function findShare(
+ int $dashboardId,
+ string $shareType,
+ string $shareWith
+ ): ?DashboardShare {
+ $qb = $this->db->getQueryBuilder();
+ $qb->select(selects: '*')
+ ->from(from: $this->getTableName())
+ ->where(
+ $qb->expr()->eq(
+ x: 'dashboard_id',
+ y: $qb->createNamedParameter(
+ value: $dashboardId,
+ type: IQueryBuilder::PARAM_INT
+ )
+ )
+ )
+ ->andWhere(
+ $qb->expr()->eq(
+ x: 'share_type',
+ y: $qb->createNamedParameter(value: $shareType)
+ )
+ )
+ ->andWhere(
+ $qb->expr()->eq(
+ x: 'share_with',
+ y: $qb->createNamedParameter(value: $shareWith)
+ )
+ );
+
+ try {
+ return $this->findEntity(query: $qb);
+ } catch (DoesNotExistException) {
+ return null;
+ }
+ }//end findShare()
+
+ /**
+ * Delete all shares for a dashboard.
+ *
+ * @param int $dashboardId The dashboard ID.
+ *
+ * @return void
+ */
+ public function deleteByDashboardId(int $dashboardId): void
+ {
+ $qb = $this->db->getQueryBuilder();
+ $qb->delete(delete: $this->getTableName())
+ ->where(
+ $qb->expr()->eq(
+ x: 'dashboard_id',
+ y: $qb->createNamedParameter(
+ value: $dashboardId,
+ type: IQueryBuilder::PARAM_INT
+ )
+ )
+ );
+
+ $qb->executeStatement();
+ }//end deleteByDashboardId()
+
+ /**
+ * Delete all shares where the recipient is a specific user.
+ *
+ * Only removes user-type shares (group membership cleanup is handled
+ * by Nextcloud's own group management hooks). REQ-SHARE-012.
+ *
+ * @param string $userId The recipient user ID.
+ *
+ * @return int The number of rows deleted.
+ */
+ public function deleteByRecipientUser(string $userId): int
+ {
+ $qb = $this->db->getQueryBuilder();
+ $qb->delete(delete: $this->getTableName())
+ ->where(
+ $qb->expr()->eq(
+ x: 'share_type',
+ y: $qb->createNamedParameter(value: DashboardShare::SHARE_TYPE_USER)
+ )
+ )
+ ->andWhere(
+ $qb->expr()->eq(
+ x: 'share_with',
+ y: $qb->createNamedParameter(value: $userId)
+ )
+ );
+
+ return $qb->executeStatement();
+ }//end deleteByRecipientUser()
+
+ /**
+ * Delete all shares not in the given set for a dashboard.
+ *
+ * Used by the bulk-replace endpoint to remove shares not in the new
+ * payload. REQ-SHARE-009.
+ *
+ * @param int $dashboardId The dashboard ID.
+ * @param string[] $keepKeys Keys of form "{shareType}:{shareWith}"
+ * to preserve.
+ *
+ * @return int The number of rows deleted.
+ */
+ public function deleteNotIn(int $dashboardId, array $keepKeys): int
+ {
+ // Load existing rows and delete those whose composite key is not in keepKeys.
+ $existing = $this->findByDashboardId(dashboardId: $dashboardId);
+ $deleted = 0;
+ foreach ($existing as $share) {
+ $key = $share->getShareType().':'.$share->getShareWith();
+ if (in_array(needle: $key, haystack: $keepKeys, strict: true) === false) {
+ $this->delete(entity: $share);
+ $deleted++;
+ }
+ }
+
+ return $deleted;
+ }//end deleteNotIn()
+
+ /**
+ * Delete all shares the caller owns that target a specific recipient.
+ *
+ * Joins logically: finds dashboards owned by $ownerId via DashboardMapper
+ * query. Uses a subquery on the dashboard table. REQ-SHARE-010.
+ *
+ * @param string $shareType The share type.
+ * @param string $shareWith The recipient.
+ * @param string $ownerId The dashboard owner.
+ *
+ * @return int The number of rows deleted.
+ */
+ public function deleteByOwnerAndRecipient(
+ string $shareType,
+ string $shareWith,
+ string $ownerId
+ ): int {
+ // Subquery: SELECT id FROM mydash_dashboards WHERE user_id = ownerId.
+ $sub = $this->db->getQueryBuilder();
+ $sub->select(selects: 'id')
+ ->from(from: 'mydash_dashboards')
+ ->where(
+ $sub->expr()->eq(
+ x: 'user_id',
+ y: $sub->createNamedParameter(value: $ownerId)
+ )
+ );
+
+ $qb = $this->db->getQueryBuilder();
+ $qb->delete(delete: $this->getTableName())
+ ->where(
+ $qb->expr()->in(
+ x: 'dashboard_id',
+ y: $qb->createFunction(
+ call: '('.$sub->getSQL().')'
+ )
+ )
+ )
+ ->andWhere(
+ $qb->expr()->eq(
+ x: 'share_type',
+ y: $qb->createNamedParameter(value: $shareType)
+ )
+ )
+ ->andWhere(
+ $qb->expr()->eq(
+ x: 'share_with',
+ y: $qb->createNamedParameter(value: $shareWith)
+ )
+ );
+
+ // Merge parameters from sub into main.
+ foreach ($sub->getParameters() as $key => $value) {
+ $qb->setParameter(key: $key, value: $value);
+ }
+
+ return $qb->executeStatement();
+ }//end deleteByOwnerAndRecipient()
+}//end class
diff --git a/lib/Db/TileMapper.php b/lib/Db/TileMapper.php
index 8fcdd001..ffddfb67 100644
--- a/lib/Db/TileMapper.php
+++ b/lib/Db/TileMapper.php
@@ -25,6 +25,11 @@
use OCP\DB\QueryBuilder\IQueryBuilder;
use OCP\IDBConnection;
+/**
+ * Database mapper for Tile entities.
+ *
+ * @extends QBMapper
+ */
class TileMapper extends QBMapper
{
/**
diff --git a/lib/Db/WidgetPlacement.php b/lib/Db/WidgetPlacement.php
index ab6c5e83..c9442b0c 100644
--- a/lib/Db/WidgetPlacement.php
+++ b/lib/Db/WidgetPlacement.php
@@ -293,7 +293,10 @@ public function getStyleConfigArray(): array
*/
public function setStyleConfigArray(array $config): void
{
- $this->setStyleConfig(styleConfig: json_encode(value: $config));
+ // Entity setters resolve via __call which uses $args[0]; named args
+ // would break the magic forwarding (see project memory).
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $this->setStyleConfig(json_encode($config));
}//end setStyleConfigArray()
/**
diff --git a/lib/Db/WidgetPlacementMapper.php b/lib/Db/WidgetPlacementMapper.php
index f1ef87b6..d48aee6b 100644
--- a/lib/Db/WidgetPlacementMapper.php
+++ b/lib/Db/WidgetPlacementMapper.php
@@ -224,6 +224,61 @@ public function updatePositions(array $updates): void
}//end foreach
}//end updatePositions()
+ /**
+ * Clone all placements from a source dashboard into a target dashboard.
+ *
+ * Fetches every placement row belonging to `$sourceDashboardId` and
+ * inserts fresh copies under `$targetDashboardId` with new auto-
+ * generated IDs and reset `createdAt`/`updatedAt` timestamps. All
+ * other fields — gridX/Y/W/H, widgetId, customTitle, styleConfig,
+ * showTitle, isCompulsory, isVisible, sortOrder, tileType, tileTitle,
+ * tileIcon, tileIconType, tileBackgroundColor, tileTextColor,
+ * tileLinkType, tileLinkValue, customIcon — are copied verbatim so
+ * the fork is a true visual clone. Resource URLs (e.g. tileIcon) are
+ * NOT duplicated; both dashboards reference the same URL (REQ-DASH-022).
+ *
+ * @param int $sourceDashboardId The source dashboard ID.
+ * @param int $targetDashboardId The target (new) dashboard ID.
+ *
+ * @return void
+ */
+ public function cloneToDashboard(
+ int $sourceDashboardId,
+ int $targetDashboardId
+ ): void {
+ $now = (new DateTime())->format(format: 'Y-m-d H:i:s');
+ $placements = $this->findByDashboardId(dashboardId: $sourceDashboardId);
+
+ foreach ($placements as $source) {
+ $clone = new WidgetPlacement();
+ $clone->setDashboardId($targetDashboardId);
+ $clone->setWidgetId($source->getWidgetId());
+ $clone->setGridX($source->getGridX());
+ $clone->setGridY($source->getGridY());
+ $clone->setGridWidth($source->getGridWidth());
+ $clone->setGridHeight($source->getGridHeight());
+ $clone->setIsCompulsory($source->getIsCompulsory());
+ $clone->setIsVisible($source->getIsVisible());
+ $clone->setStyleConfig($source->getStyleConfig());
+ $clone->setCustomTitle($source->getCustomTitle());
+ $clone->setCustomIcon($source->getCustomIcon());
+ $clone->setShowTitle($source->getShowTitle());
+ $clone->setSortOrder($source->getSortOrder());
+ $clone->setTileType($source->getTileType());
+ $clone->setTileTitle($source->getTileTitle());
+ $clone->setTileIcon($source->getTileIcon());
+ $clone->setTileIconType($source->getTileIconType());
+ $clone->setTileBackgroundColor($source->getTileBackgroundColor());
+ $clone->setTileTextColor($source->getTileTextColor());
+ $clone->setTileLinkType($source->getTileLinkType());
+ $clone->setTileLinkValue($source->getTileLinkValue());
+ $clone->setCreatedAt($now);
+ $clone->setUpdatedAt($now);
+
+ $this->insert(entity: $clone);
+ }//end foreach
+ }//end cloneToDashboard()
+
/**
* Get max sort order for a dashboard.
*
diff --git a/lib/Exception/CorruptImageException.php b/lib/Exception/CorruptImageException.php
new file mode 100644
index 00000000..95ca9190
--- /dev/null
+++ b/lib/Exception/CorruptImageException.php
@@ -0,0 +1,56 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+/**
+ * Image bytes could not be decoded by the image library.
+ */
+class CorruptImageException extends ResourceException
+{
+
+ /**
+ * Stable error code.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'corrupt_image';
+
+ /**
+ * HTTP status.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 400;
+
+ /**
+ * Constructor.
+ *
+ * @param string $message Display message.
+ */
+ public function __construct(
+ string $message='Image content appears to be corrupt'
+ ) {
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Exception/FileTooLargeException.php b/lib/Exception/FileTooLargeException.php
new file mode 100644
index 00000000..05f2fae8
--- /dev/null
+++ b/lib/Exception/FileTooLargeException.php
@@ -0,0 +1,56 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+/**
+ * Decoded payload exceeds the 5 MB hard cap.
+ */
+class FileTooLargeException extends ResourceException
+{
+
+ /**
+ * Stable error code.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'file_too_large';
+
+ /**
+ * HTTP status.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 400;
+
+ /**
+ * Constructor.
+ *
+ * @param string $message Display message.
+ */
+ public function __construct(string $message='Maximum size is 5MB')
+ {
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Exception/ForbiddenException.php b/lib/Exception/ForbiddenException.php
new file mode 100644
index 00000000..b429a649
--- /dev/null
+++ b/lib/Exception/ForbiddenException.php
@@ -0,0 +1,54 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+/**
+ * Admin-only endpoint accessed by a non-admin user.
+ */
+class ForbiddenException extends ResourceException
+{
+
+ /**
+ * Stable error code.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'forbidden';
+
+ /**
+ * HTTP status.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 403;
+
+ /**
+ * Constructor.
+ *
+ * @param string $message Display message.
+ */
+ public function __construct(string $message='Admin privileges required')
+ {
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Exception/ForbiddenExtensionException.php b/lib/Exception/ForbiddenExtensionException.php
new file mode 100644
index 00000000..56cbb3be
--- /dev/null
+++ b/lib/Exception/ForbiddenExtensionException.php
@@ -0,0 +1,54 @@
+
+ * @copyright 2026 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2026 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+/**
+ * File extension is not in the admin-configured allow-list.
+ */
+class ForbiddenExtensionException extends ResourceException
+{
+
+ /**
+ * Stable error code.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'file_type_not_allowed';
+
+ /**
+ * HTTP status.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 400;
+
+ /**
+ * Constructor.
+ *
+ * @param string $message Display message.
+ */
+ public function __construct(string $message='File type not allowed')
+ {
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Exception/InvalidDataUrlException.php b/lib/Exception/InvalidDataUrlException.php
new file mode 100644
index 00000000..e46d98d2
--- /dev/null
+++ b/lib/Exception/InvalidDataUrlException.php
@@ -0,0 +1,56 @@
+;base64,...` data URL. Maps to HTTP 400 +
+ * error code `invalid_data_url`.
+ *
+ * @category Exception
+ * @package OCA\MyDash\Exception
+ * @author Conduction b.v.
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+/**
+ * Supplied base64 string is not a valid data URL.
+ */
+class InvalidDataUrlException extends ResourceException
+{
+
+ /**
+ * Stable error code.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'invalid_data_url';
+
+ /**
+ * HTTP status.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 400;
+
+ /**
+ * Constructor.
+ *
+ * @param string $message Display message.
+ */
+ public function __construct(
+ string $message='Body must contain a base64 data URL'
+ ) {
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Exception/InvalidDirectoryException.php b/lib/Exception/InvalidDirectoryException.php
new file mode 100644
index 00000000..dd82bf2f
--- /dev/null
+++ b/lib/Exception/InvalidDirectoryException.php
@@ -0,0 +1,55 @@
+
+ * @copyright 2026 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2026 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+/**
+ * Supplied directory path contains disallowed traversal sequences.
+ */
+class InvalidDirectoryException extends ResourceException
+{
+
+ /**
+ * Stable error code.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'invalid_directory';
+
+ /**
+ * HTTP status.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 400;
+
+ /**
+ * Constructor.
+ *
+ * @param string $message Display message.
+ */
+ public function __construct(string $message='Invalid directory')
+ {
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Exception/InvalidFilenameException.php b/lib/Exception/InvalidFilenameException.php
new file mode 100644
index 00000000..916de541
--- /dev/null
+++ b/lib/Exception/InvalidFilenameException.php
@@ -0,0 +1,55 @@
+
+ * @copyright 2026 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2026 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+/**
+ * Supplied filename is empty, too long, or contains disallowed characters.
+ */
+class InvalidFilenameException extends ResourceException
+{
+
+ /**
+ * Stable error code.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'invalid_filename';
+
+ /**
+ * HTTP status.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 400;
+
+ /**
+ * Constructor.
+ *
+ * @param string $message Display message.
+ */
+ public function __construct(string $message='Invalid filename')
+ {
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Exception/InvalidImageFormatException.php b/lib/Exception/InvalidImageFormatException.php
new file mode 100644
index 00000000..682864d8
--- /dev/null
+++ b/lib/Exception/InvalidImageFormatException.php
@@ -0,0 +1,56 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+/**
+ * Declared image type is not in the allowed list.
+ */
+class InvalidImageFormatException extends ResourceException
+{
+
+ /**
+ * Stable error code.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'invalid_image_format';
+
+ /**
+ * HTTP status.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 400;
+
+ /**
+ * Constructor.
+ *
+ * @param string $message Display message.
+ */
+ public function __construct(
+ string $message='Allowed image formats: jpeg, jpg, png, gif, svg, webp'
+ ) {
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Exception/InvalidSvgException.php b/lib/Exception/InvalidSvgException.php
new file mode 100644
index 00000000..98ece507
--- /dev/null
+++ b/lib/Exception/InvalidSvgException.php
@@ -0,0 +1,56 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+/**
+ * Uploaded SVG bytes failed to parse or sanitised to an empty document.
+ */
+class InvalidSvgException extends ResourceException
+{
+
+ /**
+ * Stable error code.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'invalid_svg';
+
+ /**
+ * HTTP status.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 400;
+
+ /**
+ * Constructor.
+ *
+ * @param string $message Display message.
+ */
+ public function __construct(
+ string $message='SVG could not be parsed or contained no allowed content'
+ ) {
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Exception/MimeMismatchException.php b/lib/Exception/MimeMismatchException.php
new file mode 100644
index 00000000..4113bc9a
--- /dev/null
+++ b/lib/Exception/MimeMismatchException.php
@@ -0,0 +1,56 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+/**
+ * Declared image type does not match the detected MIME type.
+ */
+class MimeMismatchException extends ResourceException
+{
+
+ /**
+ * Stable error code.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'mime_mismatch';
+
+ /**
+ * HTTP status.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 400;
+
+ /**
+ * Constructor.
+ *
+ * @param string $message Display message.
+ */
+ public function __construct(
+ string $message='Declared image type does not match file content'
+ ) {
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Exception/MissingInitialStateException.php b/lib/Exception/MissingInitialStateException.php
new file mode 100644
index 00000000..221a1fb8
--- /dev/null
+++ b/lib/Exception/MissingInitialStateException.php
@@ -0,0 +1,51 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+use RuntimeException;
+
+/**
+ * Raised when a required initial-state key was not set before apply().
+ *
+ * See REQ-INIT-001 in the initial-state-contract spec.
+ */
+class MissingInitialStateException extends RuntimeException
+{
+ /**
+ * Construct a new MissingInitialStateException.
+ *
+ * @param string $page The page name (workspace|admin) the builder targets.
+ * @param string $key The missing required key.
+ */
+ public function __construct(string $page, string $key)
+ {
+ $message = sprintf(
+ 'Missing required initial-state key "%s" for page "%s". Use InitialStateBuilder setters before apply().',
+ $key,
+ $page
+ );
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Exception/PersonalDashboardsDisabledException.php b/lib/Exception/PersonalDashboardsDisabledException.php
new file mode 100644
index 00000000..b3467a23
--- /dev/null
+++ b/lib/Exception/PersonalDashboardsDisabledException.php
@@ -0,0 +1,56 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+/**
+ * Personal-dashboard creation blocked by admin flag (REQ-ASET-003).
+ */
+class PersonalDashboardsDisabledException extends ResourceException
+{
+
+ /**
+ * Stable error code returned in the response envelope.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'personal_dashboards_disabled';
+
+ /**
+ * HTTP status code.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 403;
+
+ /**
+ * Constructor.
+ *
+ * @param string $message Display message (translatable English string).
+ */
+ public function __construct(
+ string $message='Personal dashboards are not enabled by your administrator'
+ ) {
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Exception/ResourceException.php b/lib/Exception/ResourceException.php
new file mode 100644
index 00000000..095ff343
--- /dev/null
+++ b/lib/Exception/ResourceException.php
@@ -0,0 +1,81 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+use Exception;
+
+/**
+ * Base exception for resource-uploads.
+ */
+abstract class ResourceException extends Exception
+{
+
+ /**
+ * Stable machine-readable error code for the response envelope.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'unknown_error';
+
+ /**
+ * HTTP status code for the response.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 400;
+
+ /**
+ * Get the stable error code.
+ *
+ * @return string The machine-readable error code.
+ */
+ public function getErrorCode(): string
+ {
+ return $this->errorCode;
+ }//end getErrorCode()
+
+ /**
+ * Get the HTTP status code for this exception.
+ *
+ * @return int The HTTP status code.
+ */
+ public function getHttpStatus(): int
+ {
+ return $this->httpStatus;
+ }//end getHttpStatus()
+
+ /**
+ * Get the display message safe for clients.
+ *
+ * The exception message itself is curated; we never use raw inner
+ * messages. Subclasses should pass a translatable English string.
+ *
+ * @return string The display message.
+ */
+ public function getDisplayMessage(): string
+ {
+ return $this->getMessage();
+ }//end getDisplayMessage()
+}//end class
diff --git a/lib/Exception/StorageFailureException.php b/lib/Exception/StorageFailureException.php
new file mode 100644
index 00000000..0a0d15b6
--- /dev/null
+++ b/lib/Exception/StorageFailureException.php
@@ -0,0 +1,56 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+/**
+ * Persisting the resource to app data failed.
+ */
+class StorageFailureException extends ResourceException
+{
+
+ /**
+ * Stable error code.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'storage_failure';
+
+ /**
+ * HTTP status.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 500;
+
+ /**
+ * Constructor.
+ *
+ * @param string $message Display message.
+ */
+ public function __construct(
+ string $message='Failed to store resource'
+ ) {
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Exception/UnsupportedMediaTypeException.php b/lib/Exception/UnsupportedMediaTypeException.php
new file mode 100644
index 00000000..892d2d9b
--- /dev/null
+++ b/lib/Exception/UnsupportedMediaTypeException.php
@@ -0,0 +1,56 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Exception;
+
+/**
+ * Request media type is not the expected JSON body.
+ */
+class UnsupportedMediaTypeException extends ResourceException
+{
+
+ /**
+ * Stable error code.
+ *
+ * @var string
+ */
+ protected string $errorCode = 'unsupported_media_type';
+
+ /**
+ * HTTP status.
+ *
+ * @var integer
+ */
+ protected int $httpStatus = 415;
+
+ /**
+ * Constructor.
+ *
+ * @param string $message Display message.
+ */
+ public function __construct(
+ string $message='Use JSON body with base64 field'
+ ) {
+ parent::__construct(message: $message);
+ }//end __construct()
+}//end class
diff --git a/lib/Listener/UserDeletedListener.php b/lib/Listener/UserDeletedListener.php
new file mode 100644
index 00000000..9a705283
--- /dev/null
+++ b/lib/Listener/UserDeletedListener.php
@@ -0,0 +1,255 @@
+
+ * @copyright 2026 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2026 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Listener;
+
+use OCA\MyDash\Db\Dashboard;
+use OCA\MyDash\Db\DashboardMapper;
+use OCA\MyDash\Db\DashboardShare;
+use OCA\MyDash\Db\DashboardShareMapper;
+use OCA\MyDash\Db\WidgetPlacementMapper;
+use OCA\MyDash\Service\DashboardShareService;
+use OCP\EventDispatcher\Event;
+use OCP\EventDispatcher\IEventListener;
+use OCP\IDBConnection;
+use OCP\IGroupManager;
+use OCP\IUserManager;
+use OCP\User\Events\UserDeletedEvent;
+use Throwable;
+
+/**
+ * Handles user deletion: recipient cleanup + ownership transfer / cascade.
+ *
+ * @implements IEventListener
+ */
+class UserDeletedListener implements IEventListener
+{
+ /**
+ * Constructor
+ *
+ * @param DashboardShareMapper $shareMapper The share mapper.
+ * @param DashboardMapper $dashboardMapper The dashboard mapper.
+ * @param WidgetPlacementMapper $placementMapper The placement mapper.
+ * @param DashboardShareService $shareService The share service.
+ * @param IGroupManager $groupManager The group manager.
+ * @param IUserManager $userManager The user manager.
+ * @param IDBConnection $db The DB connection.
+ */
+ public function __construct(
+ private readonly DashboardShareMapper $shareMapper,
+ private readonly DashboardMapper $dashboardMapper,
+ private readonly WidgetPlacementMapper $placementMapper,
+ private readonly DashboardShareService $shareService,
+ private readonly IGroupManager $groupManager,
+ private readonly IUserManager $userManager,
+ private readonly IDBConnection $db,
+ ) {
+ }//end __construct()
+
+ /**
+ * Handle the UserDeletedEvent.
+ *
+ * Step A: delete all user-type shares where share_with = deleted user.
+ * Step B: for each owned dashboard, compute the admin pool and either
+ * transfer ownership or delete the dashboard.
+ *
+ * @param Event $event The event.
+ *
+ * @return void
+ */
+ public function handle(Event $event): void
+ {
+ if (($event instanceof UserDeletedEvent) === false) {
+ return;
+ }
+
+ $userId = $event->getUser()->getUID();
+
+ // Step A: remove shares granted TO the deleted user.
+ $this->shareMapper->deleteByRecipientUser(userId: $userId);
+
+ // Step B: handle owned dashboards.
+ $ownedDashboards = $this->dashboardMapper->findByUserId(
+ userId: $userId
+ );
+
+ foreach ($ownedDashboards as $dashboard) {
+ $this->handleOwnedDashboard(
+ dashboard: $dashboard,
+ deletedUserId: $userId
+ );
+ }
+ }//end handle()
+
+ /**
+ * Handle a single dashboard owned by the deleted user.
+ *
+ * @param Dashboard $dashboard The dashboard.
+ * @param string $deletedUserId The deleted user's ID.
+ *
+ * @return void
+ */
+ private function handleOwnedDashboard(
+ Dashboard $dashboard,
+ string $deletedUserId
+ ): void {
+ $dashboardId = (int) $dashboard->getId();
+
+ $this->db->beginTransaction();
+ try {
+ $newOwner = $this->pickNewOwner(
+ dashboardId: $dashboardId,
+ deletedUserId: $deletedUserId
+ );
+
+ if ($newOwner !== null) {
+ // Transfer ownership.
+ $this->shareService->transferOwnership(
+ dashboardId: $dashboardId,
+ newUserId: $newOwner
+ );
+
+ $this->db->commit();
+
+ // Notify outside the transaction.
+ $this->shareService->notifyOwnershipTransferred(
+ newOwnerId: $newOwner,
+ dashboardId: $dashboardId,
+ dashboardName: (string) $dashboard->getName()
+ );
+ } else {
+ // Admin pool empty — delete dashboard, placements, and shares.
+ $this->placementMapper->deleteByDashboardId(
+ dashboardId: $dashboardId
+ );
+ $this->shareMapper->deleteByDashboardId(
+ dashboardId: $dashboardId
+ );
+ $this->dashboardMapper->delete(entity: $dashboard);
+
+ $this->db->commit();
+ }//end if
+ } catch (Throwable $t) {
+ $this->db->rollBack();
+ // Log but do not rethrow — we want to continue processing
+ // the other dashboards.
+ \OC::$server->getLogger()->error(
+ message: sprintf(
+ 'mydash UserDeletedListener: failed to handle dashboard %d: %s',
+ $dashboardId,
+ $t->getMessage()
+ ),
+ context: ['app' => 'mydash']
+ );
+ }//end try
+ }//end handleOwnedDashboard()
+
+ /**
+ * Compute the admin pool and pick the new owner per REQ-SHARE-013.
+ *
+ * Selection rule:
+ * 1. User-type shares with `permission_level='full'`, ordered by
+ * created_at ASC — pick the first still-existing user.
+ * 2. If none, take the alphabetically-first group-type share with
+ * `permission_level='full'` and from its members pick the
+ * alphabetically-first uid that still exists.
+ * 3. If both fail, return null (delete path).
+ *
+ * @param int $dashboardId The dashboard ID.
+ * @param string $deletedUserId The deleted user (excluded from pool).
+ *
+ * @return string|null The new owner uid or null.
+ */
+ private function pickNewOwner(
+ int $dashboardId,
+ string $deletedUserId
+ ): ?string {
+ $fullShares = $this->shareMapper->findByDashboardAndLevel(
+ dashboardId: $dashboardId,
+ permissionLevel: Dashboard::PERMISSION_FULL
+ );
+
+ // Step 1: user-type shares sorted by created_at ASC (mapper already
+ // returns rows in that order).
+ foreach ($fullShares as $share) {
+ if ($share->getShareType() !== DashboardShare::SHARE_TYPE_USER) {
+ continue;
+ }
+
+ $uid = (string) $share->getShareWith();
+ if ($uid === $deletedUserId) {
+ continue;
+ }
+
+ if ($this->userManager->get(uid: $uid) !== null) {
+ return $uid;
+ }
+ }
+
+ // Step 2: group-type shares — pick alphabetically-first group name.
+ $groupShares = [];
+ foreach ($fullShares as $share) {
+ if ($share->getShareType() === DashboardShare::SHARE_TYPE_GROUP) {
+ $groupShares[] = $share;
+ }
+ }
+
+ // Sort groups alphabetically.
+ usort(
+ array: $groupShares,
+ callback: static fn($a, $b) => strcmp(
+ string1: (string) $a->getShareWith(),
+ string2: (string) $b->getShareWith()
+ )
+ );
+
+ foreach ($groupShares as $groupShare) {
+ $groupId = (string) $groupShare->getShareWith();
+ $group = $this->groupManager->get(gid: $groupId);
+ if ($group === null) {
+ continue;
+ }
+
+ // Get members and sort alphabetically.
+ $members = [];
+ foreach ($group->getUsers() as $user) {
+ $members[] = $user->getUID();
+ }
+
+ sort(array: $members);
+
+ foreach ($members as $uid) {
+ if ($uid === $deletedUserId) {
+ continue;
+ }
+
+ if ($this->userManager->get(uid: $uid) !== null) {
+ return $uid;
+ }
+ }//end foreach
+ }//end foreach
+
+ return null;
+ }//end pickNewOwner()
+}//end class
diff --git a/lib/Migration/DashboardTableBuilder.php b/lib/Migration/DashboardTableBuilder.php
index 3663271e..4409b85e 100644
--- a/lib/Migration/DashboardTableBuilder.php
+++ b/lib/Migration/DashboardTableBuilder.php
@@ -106,6 +106,14 @@ private static function addColumns($table): void
'length' => 64,
]
);
+ $table->addColumn(
+ name: 'group_id',
+ typeName: Types::STRING,
+ options: [
+ 'notnull' => false,
+ 'length' => 64,
+ ]
+ );
$table->addColumn(
name: 'based_on_template',
typeName: Types::BIGINT,
@@ -198,5 +206,9 @@ private static function addIndexes($table): void
columnNames: ['user_id', 'is_active'],
indexName: 'mydash_dashboard_active'
);
+ $table->addIndex(
+ columnNames: ['type', 'group_id'],
+ indexName: 'mydash_dash_type_group'
+ );
}//end addIndexes()
}//end class
diff --git a/lib/Migration/Version001005Date20260430000000.php b/lib/Migration/Version001005Date20260430000000.php
new file mode 100644
index 00000000..1e9ca141
--- /dev/null
+++ b/lib/Migration/Version001005Date20260430000000.php
@@ -0,0 +1,80 @@
+
+ * @copyright 2026 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2026 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Migration;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+
+/**
+ * Migration adding the group_id column and a (type, group_id) composite
+ * index on the dashboards table.
+ */
+class Version001005Date20260430000000 extends SimpleMigrationStep
+{
+ /**
+ * Add group_id column + composite index to mydash_dashboards.
+ *
+ * @param IOutput $output The migration output handler.
+ * @param Closure $schemaClosure The schema closure (returns ISchemaWrapper).
+ * @param array $options The migration options.
+ *
+ * @return ISchemaWrapper|null The modified schema or null.
+ */
+ public function changeSchema(
+ IOutput $output,
+ Closure $schemaClosure,
+ array $options
+ ): ?ISchemaWrapper {
+ $schema = $schemaClosure();
+
+ if ($schema->hasTable(tableName: 'mydash_dashboards') === false) {
+ return $schema;
+ }
+
+ $table = $schema->getTable(tableName: 'mydash_dashboards');
+
+ if ($table->hasColumn(name: 'group_id') === false) {
+ $table->addColumn(
+ name: 'group_id',
+ typeName: Types::STRING,
+ options: [
+ 'notnull' => false,
+ 'length' => 64,
+ ]
+ );
+ }
+
+ if ($table->hasIndex(indexName: 'mydash_dash_type_group') === false) {
+ $table->addIndex(
+ columnNames: ['type', 'group_id'],
+ indexName: 'mydash_dash_type_group'
+ );
+ }
+
+ return $schema;
+ }//end changeSchema()
+}//end class
diff --git a/lib/Migration/Version001006Date20260430130000.php b/lib/Migration/Version001006Date20260430130000.php
new file mode 100644
index 00000000..48bbdf82
--- /dev/null
+++ b/lib/Migration/Version001006Date20260430130000.php
@@ -0,0 +1,232 @@
+
+ * @copyright 2026 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2026 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Migration;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\IConfig;
+use OCP\IDBConnection;
+use OCP\IGroupManager;
+use OCP\IUserManager;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+
+/**
+ * Migration creating the dashboard_shares table and an optional orphan cleanup.
+ *
+ * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
+ */
+class Version001006Date20260430130000 extends SimpleMigrationStep
+{
+ /**
+ * Constructor
+ *
+ * @param IConfig $config The app config.
+ * @param IDBConnection $db The database connection.
+ * @param IUserManager $userManager The user manager.
+ * @param IGroupManager $groupManager The group manager.
+ */
+ public function __construct(
+ private readonly IConfig $config,
+ private readonly IDBConnection $db,
+ private readonly IUserManager $userManager,
+ private readonly IGroupManager $groupManager,
+ ) {
+ }//end __construct()
+
+ /**
+ * Create the mydash_dashboard_shares table.
+ *
+ * @param IOutput $output The migration output handler.
+ * @param Closure $schemaClosure The schema closure.
+ * @param array $options The migration options.
+ *
+ * @return ISchemaWrapper|null The modified schema or null.
+ */
+ public function changeSchema(
+ IOutput $output,
+ Closure $schemaClosure,
+ array $options
+ ): ?ISchemaWrapper {
+ $schema = $schemaClosure();
+
+ if ($schema->hasTable(tableName: 'mydash_dashboard_shares') === true) {
+ return null;
+ }
+
+ $table = $schema->createTable(tableName: 'mydash_dashboard_shares');
+
+ $table->addColumn(
+ name: 'id',
+ typeName: Types::BIGINT,
+ options: [
+ 'autoincrement' => true,
+ 'notnull' => true,
+ 'unsigned' => true,
+ ]
+ );
+ $table->addColumn(
+ name: 'dashboard_id',
+ typeName: Types::BIGINT,
+ options: [
+ 'notnull' => true,
+ 'unsigned' => true,
+ ]
+ );
+ $table->addColumn(
+ name: 'share_type',
+ typeName: Types::STRING,
+ options: [
+ 'notnull' => true,
+ 'length' => 16,
+ ]
+ );
+ $table->addColumn(
+ name: 'share_with',
+ typeName: Types::STRING,
+ options: [
+ 'notnull' => true,
+ 'length' => 255,
+ ]
+ );
+ $table->addColumn(
+ name: 'permission_level',
+ typeName: Types::STRING,
+ options: [
+ 'notnull' => true,
+ 'length' => 32,
+ 'default' => 'view_only',
+ ]
+ );
+ $table->addColumn(
+ name: 'created_at',
+ typeName: Types::STRING,
+ options: [
+ 'notnull' => false,
+ 'length' => 32,
+ ]
+ );
+ $table->addColumn(
+ name: 'updated_at',
+ typeName: Types::STRING,
+ options: [
+ 'notnull' => false,
+ 'length' => 32,
+ ]
+ );
+
+ $table->setPrimaryKey(columnNames: ['id']);
+ $table->addIndex(
+ columnNames: ['dashboard_id'],
+ indexName: 'mydash_shares_dashboard'
+ );
+ $table->addIndex(
+ columnNames: ['share_type', 'share_with'],
+ indexName: 'mydash_shares_recipient'
+ );
+ $table->addUniqueIndex(
+ columnNames: ['dashboard_id', 'share_type', 'share_with'],
+ indexName: 'mydash_shares_unique'
+ );
+
+ return $schema;
+ }//end changeSchema()
+
+ /**
+ * Optional orphan-share cleanup, gated by admin setting.
+ *
+ * Deletes share rows where the recipient user/group no longer exists.
+ * Only runs when `mydash.cleanup_orphan_shares` is explicitly `true`.
+ * Default is `false` to avoid surprise deletions on federated environments.
+ *
+ * @param IOutput $output The migration output handler.
+ * @param Closure $closure The schema closure.
+ * @param array $options The migration options.
+ *
+ * @return void
+ */
+ public function postSchemaChange(
+ IOutput $output,
+ Closure $closure,
+ array $options
+ ): void {
+ $enabled = $this->config->getAppValue(
+ appName: 'mydash',
+ key: 'cleanup_orphan_shares',
+ default: 'false'
+ );
+
+ if ($enabled !== 'true') {
+ return;
+ }
+
+ $output->info(message: 'mydash: scanning for orphan share rows…');
+
+ if ($this->db->tableExists(table: 'mydash_dashboard_shares') === false) {
+ return;
+ }
+
+ $qb = $this->db->getQueryBuilder();
+ $result = $qb->select(selects: ['id', 'share_type', 'share_with'])
+ ->from(from: 'mydash_dashboard_shares')
+ ->executeQuery();
+
+ $deleted = 0;
+ $row = $result->fetch();
+ while ($row !== false) {
+ $orphan = false;
+ if ($row['share_type'] === 'user'
+ && $this->userManager->get(uid: $row['share_with']) === null
+ ) {
+ $orphan = true;
+ } else if ($row['share_type'] === 'group'
+ && $this->groupManager->get(gid: $row['share_with']) === null
+ ) {
+ $orphan = true;
+ }
+
+ if ($orphan === true) {
+ $del = $this->db->getQueryBuilder();
+ $del->delete(delete: 'mydash_dashboard_shares')
+ ->where(
+ $del->expr()->eq(
+ x: 'id',
+ y: $del->createNamedParameter(
+ value: (int) $row['id'],
+ type: \OCP\DB\QueryBuilder\IQueryBuilder::PARAM_INT
+ )
+ )
+ )
+ ->executeStatement();
+ $deleted++;
+ }
+
+ $row = $result->fetch();
+ }//end while
+
+ $result->closeCursor();
+ $output->info(message: "mydash: removed {$deleted} orphan share row(s).");
+ }//end postSchemaChange()
+}//end class
diff --git a/lib/Notification/Notifier.php b/lib/Notification/Notifier.php
new file mode 100644
index 00000000..95b0181b
--- /dev/null
+++ b/lib/Notification/Notifier.php
@@ -0,0 +1,280 @@
+
+ * @copyright 2026 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2026 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Notification;
+
+use InvalidArgumentException;
+use OCA\MyDash\AppInfo\Application;
+use OCA\MyDash\Db\DashboardMapper;
+use OCP\AppFramework\Db\DoesNotExistException;
+use OCP\IURLGenerator;
+use OCP\L10N\IFactory;
+use OCP\Notification\INotification;
+use OCP\Notification\INotifier;
+use OCP\Notification\UnknownNotificationException;
+
+/**
+ * MyDash notification renderer.
+ *
+ * Handles two subjects:
+ * - `dashboard_shared` — published when a dashboard is shared with a user or
+ * when a share's permission_level is upgraded (REQ-SHARE-008).
+ * - `dashboard_ownership_transferred` — published when a UserDeletedEvent
+ * causes ownership of a dashboard to be transferred to a new owner
+ * (REQ-SHARE-013).
+ */
+class Notifier implements INotifier
+{
+ /**
+ * Constructor
+ *
+ * @param IFactory $l10nFactory The L10N factory.
+ * @param IURLGenerator $urlGenerator The URL generator.
+ * @param DashboardMapper $dashboardMapper The dashboard mapper.
+ */
+ public function __construct(
+ private readonly IFactory $l10nFactory,
+ private readonly IURLGenerator $urlGenerator,
+ private readonly DashboardMapper $dashboardMapper,
+ ) {
+ }//end __construct()
+
+ /**
+ * Return the notifier app ID.
+ *
+ * @return string The app ID.
+ */
+ public function getID(): string
+ {
+ return Application::APP_ID;
+ }//end getID()
+
+ /**
+ * Return a human-readable notifier name.
+ *
+ * @return string The notifier name.
+ */
+ public function getName(): string
+ {
+ return $this->l10nFactory->get(app: Application::APP_ID)->t('MyDash');
+ }//end getName()
+
+ /**
+ * Prepare and render an INotification for display.
+ *
+ * Handles `dashboard_shared` and `dashboard_ownership_transferred`.
+ * Throws `UnknownNotificationException` for any other subject so that
+ * the Nextcloud notification chain can pass it to the next notifier.
+ *
+ * @param INotification $notification The raw notification.
+ * @param string $languageCode The language code for the recipient.
+ *
+ * @return INotification The prepared notification.
+ *
+ * @throws UnknownNotificationException When the subject is not handled.
+ */
+ public function prepare(
+ INotification $notification,
+ string $languageCode
+ ): INotification {
+ if ($notification->getApp() !== Application::APP_ID) {
+ throw new UnknownNotificationException(
+ message: 'Unknown app: '.$notification->getApp()
+ );
+ }
+
+ $l = $this->l10nFactory->get(
+ app: Application::APP_ID,
+ lang: $languageCode
+ );
+ $url = $this->buildDashboardUrl(
+ objectId: $notification->getObjectId()
+ );
+
+ $subject = $notification->getSubject();
+
+ if ($subject === 'dashboard_shared') {
+ return $this->prepareDashboardShared(
+ notification: $notification,
+ l: $l,
+ url: $url
+ );
+ }
+
+ if ($subject === 'dashboard_ownership_transferred') {
+ return $this->prepareOwnershipTransferred(
+ notification: $notification,
+ l: $l,
+ url: $url
+ );
+ }
+
+ throw new UnknownNotificationException(
+ message: 'Unknown subject: '.$subject
+ );
+ }//end prepare()
+
+ /**
+ * Prepare a `dashboard_shared` notification.
+ *
+ * Subject parameters: [sharerUserId, dashboardName, permissionLevel].
+ *
+ * @param INotification $notification The notification.
+ * @param \OCP\L10N\IL10N $l The L10N instance.
+ * @param string $url The deep-link URL.
+ *
+ * @return INotification The prepared notification.
+ */
+ private function prepareDashboardShared(
+ INotification $notification,
+ \OCP\L10N\IL10N $l,
+ string $url
+ ): INotification {
+ $params = $notification->getSubjectParameters();
+ $sharer = $params[0] ?? '';
+ $name = $params[1] ?? '';
+ $level = $params[2] ?? '';
+
+ $richSubject = $l->t(
+ '%1$s shared **%2$s** with you',
+ [$sharer, $name]
+ );
+ $notification->setRichSubject(
+ subject: $richSubject,
+ parameters: []
+ );
+ $notification->setParsedSubject(
+ subject: $l->t(
+ '%1$s shared %2$s with you',
+ [$sharer, $name]
+ )
+ );
+
+ $levelLabel = $this->permissionLabel(l: $l, level: $level);
+ $notification->setRichMessage(
+ message: $levelLabel,
+ parameters: []
+ );
+ $notification->setParsedMessage(subject: $levelLabel);
+
+ $notification->setLink(link: $url);
+
+ return $notification;
+ }//end prepareDashboardShared()
+
+ /**
+ * Prepare a `dashboard_ownership_transferred` notification.
+ *
+ * Subject parameters: [dashboardName].
+ *
+ * @param INotification $notification The notification.
+ * @param \OCP\L10N\IL10N $l The L10N instance.
+ * @param string $url The deep-link URL.
+ *
+ * @return INotification The prepared notification.
+ */
+ private function prepareOwnershipTransferred(
+ INotification $notification,
+ \OCP\L10N\IL10N $l,
+ string $url
+ ): INotification {
+ $params = $notification->getSubjectParameters();
+ $name = $params[0] ?? '';
+
+ $richSubject = $l->t('**%1$s** is now yours', [$name]);
+ $notification->setRichSubject(
+ subject: $richSubject,
+ parameters: []
+ );
+ $notification->setParsedSubject(
+ subject: $l->t('%1$s is now yours', [$name])
+ );
+
+ $message = $l->t(
+ 'Ownership transferred after the previous owner was removed'
+ );
+ $notification->setRichMessage(
+ message: $message,
+ parameters: []
+ );
+ $notification->setParsedMessage(subject: $message);
+
+ $notification->setLink(link: $url);
+
+ return $notification;
+ }//end prepareOwnershipTransferred()
+
+ /**
+ * Build the deep-link URL for a dashboard.
+ *
+ * Falls back to the base index route when the objectId cannot be
+ * resolved to a UUID (e.g. when the dashboard was deleted between
+ * notification creation and rendering).
+ *
+ * @param string $objectId The dashboard DB ID (as string per INotification).
+ *
+ * @return string The URL.
+ */
+ private function buildDashboardUrl(string $objectId): string
+ {
+ $base = $this->urlGenerator->linkToRouteAbsolute(
+ routeName: 'mydash.page.index'
+ );
+
+ if ($objectId === '') {
+ return $base;
+ }
+
+ try {
+ $dashboard = $this->dashboardMapper->find(id: (int) $objectId);
+ $uuid = $dashboard->getUuid();
+ if ($uuid !== null && $uuid !== '') {
+ return $base.'?dashboard='.urlencode(string: $uuid);
+ }
+ } catch (DoesNotExistException) {
+ // Dashboard deleted — return base URL.
+ }
+
+ return $base;
+ }//end buildDashboardUrl()
+
+ /**
+ * Return the human-readable label for a permission level.
+ *
+ * @param \OCP\L10N\IL10N $l The L10N instance.
+ * @param string $level The permission level identifier.
+ *
+ * @return string The translated label.
+ */
+ private function permissionLabel(
+ \OCP\L10N\IL10N $l,
+ string $level
+ ): string {
+ return match ($level) {
+ 'full' => $l->t('Full access'),
+ 'add_only' => $l->t('Add-only access'),
+ 'view_only' => $l->t('View-only access'),
+ default => $l->t('Shared access'),
+ };
+ }//end permissionLabel()
+}//end class
diff --git a/lib/Service/AdminSettingsService.php b/lib/Service/AdminSettingsService.php
index 69bad5aa..f2a6b6e3 100644
--- a/lib/Service/AdminSettingsService.php
+++ b/lib/Service/AdminSettingsService.php
@@ -21,9 +21,11 @@
namespace OCA\MyDash\Service;
+use InvalidArgumentException;
use OCA\MyDash\Db\AdminSetting;
use OCA\MyDash\Db\AdminSettingMapper;
use OCA\MyDash\Db\Dashboard;
+use OCP\AppFramework\Db\DoesNotExistException;
/**
* Service for managing admin settings.
@@ -107,4 +109,100 @@ public function updateSettings(
);
}
}//end updateSettings()
+
+ /**
+ * Get the persisted ordered list of "active" Nextcloud group IDs.
+ *
+ * Reads the global `group_order` admin setting (REQ-ASET-012). The value
+ * is persisted as a JSON-encoded `string[]`. This method is intentionally
+ * defensive: a missing row, a `NULL` value, an empty string, corrupt JSON,
+ * or any non-array decoded value MUST resolve to `[]` without throwing,
+ * so the resolver and admin UI never see a fatal error from a malformed
+ * value (REQ-ASET-012 "Corrupt DB JSON falls back to empty array"
+ * scenario).
+ *
+ * Non-string elements that slip through the persisted value (defence in
+ * depth — `setGroupOrder` already rejects them) are filtered out.
+ *
+ * @return array The admin-chosen group IDs in priority
+ * order; `[]` when unset or unparseable.
+ */
+ public function getGroupOrder(): array
+ {
+ try {
+ $entity = $this->settingMapper->findByKey(
+ key: AdminSetting::KEY_GROUP_ORDER
+ );
+ } catch (DoesNotExistException) {
+ return [];
+ }
+
+ $raw = $entity->getSettingValue();
+ if ($raw === null || $raw === '') {
+ return [];
+ }
+
+ $decoded = json_decode(
+ json: $raw,
+ associative: true
+ );
+
+ if (is_array($decoded) === false) {
+ return [];
+ }
+
+ $clean = [];
+ foreach ($decoded as $value) {
+ if (is_string($value) === true && $value !== '') {
+ $clean[] = $value;
+ }
+ }
+
+ return array_values(array_unique($clean));
+ }//end getGroupOrder()
+
+ /**
+ * Persist the ordered list of "active" Nextcloud group IDs.
+ *
+ * Implements REQ-ASET-012 / REQ-ASET-014:
+ * - Every element MUST be a non-empty string; otherwise an
+ * `InvalidArgumentException` is thrown and nothing is persisted.
+ * - Duplicate IDs are deduplicated, first occurrence wins, order is
+ * preserved.
+ * - The result is persisted as a JSON-encoded `string[]` under the
+ * `group_order` key (REPLACE-WHOLESALE — no merge with previous).
+ * - Unknown (not currently in Nextcloud) IDs are NOT validated here;
+ * they are tolerated per REQ-ASET-014 "Unknown IDs accepted".
+ *
+ * @param array $groupIds The new ordered list of group IDs.
+ *
+ * @return void
+ *
+ * @throws InvalidArgumentException When any element is not a non-empty
+ * string.
+ */
+ public function setGroupOrder(array $groupIds): void
+ {
+ $deduped = [];
+ $seen = [];
+ foreach ($groupIds as $id) {
+ if (is_string($id) === false || $id === '') {
+ throw new InvalidArgumentException(
+ message: 'Every group ID must be a non-empty string.'
+ );
+ }
+
+ if (isset($seen[$id]) === true) {
+ continue;
+ }
+
+ $seen[$id] = true;
+ $deduped[] = $id;
+ }
+
+ $this->settingMapper->setSetting(
+ key: AdminSetting::KEY_GROUP_ORDER,
+ value: $deduped
+ );
+ }//end setGroupOrder()
}//end class
diff --git a/lib/Service/AdminTemplateService.php b/lib/Service/AdminTemplateService.php
index c021efac..234c9b0a 100644
--- a/lib/Service/AdminTemplateService.php
+++ b/lib/Service/AdminTemplateService.php
@@ -26,6 +26,8 @@
use OCA\MyDash\Db\Dashboard;
use OCA\MyDash\Db\DashboardMapper;
use OCA\MyDash\Db\WidgetPlacementMapper;
+use OCP\IGroupManager;
+use OCP\IUserManager;
use Ramsey\Uuid\Uuid;
/**
@@ -38,10 +40,16 @@ class AdminTemplateService
*
* @param DashboardMapper $dashboardMapper Dashboard mapper.
* @param WidgetPlacementMapper $placementMapper Widget placement mapper.
+ * @param AdminSettingsService $adminSettings Admin settings reader (for `group_order`).
+ * @param IGroupManager $groupManager Nextcloud group membership lookup.
+ * @param IUserManager $userManager Nextcloud user lookup (resolve user ID to IUser).
*/
public function __construct(
private readonly DashboardMapper $dashboardMapper,
private readonly WidgetPlacementMapper $placementMapper,
+ private readonly AdminSettingsService $adminSettings,
+ private readonly IGroupManager $groupManager,
+ private readonly IUserManager $userManager,
) {
}//end __construct()
@@ -226,4 +234,100 @@ private function applyTemplateUpdates(
);
}
}//end applyTemplateUpdates()
+
+ /**
+ * Resolve the user's primary workspace group (REQ-TMPL-012).
+ *
+ * Pure read-only function — performs no writes. Implements the single
+ * routing authority for primary-group resolution (REQ-TMPL-013): every
+ * workspace-rendering and dashboard-resolution code path MUST consult
+ * this method instead of inlining the algorithm.
+ *
+ * Algorithm:
+ * 1. Read the admin-configured ordered list of group IDs from
+ * `admin_settings.group_order` (JSON `string[]`, default `[]`).
+ * 2. Read the user's Nextcloud group memberships via
+ * `IGroupManager::getUserGroupIds`.
+ * 3. Walk `group_order` left-to-right and return the first group ID
+ * that also appears in the user's memberships.
+ * 4. If no match (including empty list, user in no configured group,
+ * or every configured ID is stale), return the literal sentinel
+ * `Dashboard::DEFAULT_GROUP_ID` (`'default'`).
+ *
+ * Stale (deleted) group IDs in `group_order` are tolerated — cleanup is
+ * the admin UI's responsibility and the resolver MUST NOT throw on
+ * them.
+ *
+ * @param string $userId The Nextcloud user ID.
+ *
+ * @return string The matched Nextcloud group ID, or
+ * {@see Dashboard::DEFAULT_GROUP_ID} when no match
+ * exists.
+ */
+ public function resolvePrimaryGroup(string $userId): string
+ {
+ $orderedGroups = $this->adminSettings->getGroupOrder();
+
+ // Short-circuit: if no groups are configured the answer is always
+ // the default sentinel — no need to look the user up.
+ if ($orderedGroups === []) {
+ return Dashboard::DEFAULT_GROUP_ID;
+ }
+
+ $user = $this->userManager->get($userId);
+ if ($user === null) {
+ // Stale / unknown user ID — tolerate silently per
+ // REQ-TMPL-012 spirit (resolver MUST NOT throw on bad input).
+ return Dashboard::DEFAULT_GROUP_ID;
+ }
+
+ $userGroups = $this->groupManager->getUserGroupIds(user: $user);
+
+ $match = self::pickFirstMatch(
+ orderedGroups: $orderedGroups,
+ userGroups: $userGroups
+ );
+
+ return ($match ?? Dashboard::DEFAULT_GROUP_ID);
+ }//end resolvePrimaryGroup()
+
+ /**
+ * Pick the first ordered group that the user is a member of.
+ *
+ * Internal pure helper extracted for direct unit-testability of the
+ * intersection logic, independent of any Nextcloud/DI dependencies.
+ * Walks `$orderedGroups` left-to-right and returns the first entry that
+ * also appears in `$userGroups`. Returns `null` when no overlap exists
+ * (including either argument being empty).
+ *
+ * Tolerates stale entries in `$orderedGroups` — entries that are not in
+ * `$userGroups` are simply skipped, never raise an error.
+ *
+ * @param array $orderedGroups The admin-configured ordered
+ * list of group IDs.
+ * @param array $userGroups The user's actual Nextcloud
+ * group memberships.
+ *
+ * @return string|null The first matching group ID, or `null` when the
+ * two lists do not intersect.
+ */
+ public static function pickFirstMatch(
+ array $orderedGroups,
+ array $userGroups
+ ): ?string {
+ if ($orderedGroups === [] || $userGroups === []) {
+ return null;
+ }
+
+ // O(n) lookup: hash the user's groups for constant-time matching.
+ $userGroupSet = array_flip($userGroups);
+
+ foreach ($orderedGroups as $groupId) {
+ if (isset($userGroupSet[$groupId]) === true) {
+ return $groupId;
+ }
+ }
+
+ return null;
+ }//end pickFirstMatch()
}//end class
diff --git a/lib/Service/DashboardFactory.php b/lib/Service/DashboardFactory.php
index 207f6288..afd32943 100644
--- a/lib/Service/DashboardFactory.php
+++ b/lib/Service/DashboardFactory.php
@@ -3,7 +3,8 @@
/**
* DashboardFactory
*
- * Factory service for creating dashboard entities.
+ * Factory service for creating dashboard entities. Enforces the
+ * `(type, groupId)` invariant required by REQ-DASH-011.
*
* @category Service
* @package OCA\MyDash\Service
@@ -22,6 +23,7 @@
namespace OCA\MyDash\Service;
use DateTime;
+use InvalidArgumentException;
use OCA\MyDash\Db\Dashboard;
/**
@@ -32,33 +34,94 @@ class DashboardFactory
/**
* Create a new dashboard entity.
*
- * @param string $userId The user ID.
+ * Enforces the REQ-DASH-011 invariant: `type === TYPE_GROUP_SHARED`
+ * iff `groupId !== null`. Throws `InvalidArgumentException` on
+ * mismatch — no row is persisted in that case (the caller never
+ * receives an entity to insert).
+ *
+ * @param string|null $userId The user ID — must be non-null for
+ * `TYPE_USER`, must be null for
+ * `TYPE_GROUP_SHARED` /
+ * `TYPE_ADMIN_TEMPLATE`.
* @param string $name The dashboard name.
* @param string|null $description The dashboard description.
+ * @param string $type The dashboard type
+ * (default {@see Dashboard::TYPE_USER}).
+ * @param string|null $groupId The group ID — required when
+ * `type === TYPE_GROUP_SHARED`,
+ * forbidden otherwise.
+ * @param int $gridColumns The grid column count.
*
* @return Dashboard The created dashboard entity (not yet persisted).
+ *
+ * @throws InvalidArgumentException When the (type, groupId) invariant
+ * is violated.
*/
public function create(
- string $userId,
+ ?string $userId,
string $name,
- ?string $description=null
+ ?string $description=null,
+ string $type=Dashboard::TYPE_USER,
+ ?string $groupId=null,
+ int $gridColumns=12
): Dashboard {
+ $this->assertTypeGroupInvariant(type: $type, groupId: $groupId);
+
$now = (new DateTime())->format(format: 'Y-m-d H:i:s');
$dashboard = new Dashboard();
$dashboard->setUuid($this->generateUuid());
$dashboard->setName($name);
$dashboard->setDescription($description);
- $dashboard->setType(Dashboard::TYPE_USER);
+ $dashboard->setType($type);
$dashboard->setUserId($userId);
- $dashboard->setGridColumns(12);
+ $dashboard->setGroupId($groupId);
+ $dashboard->setGridColumns($gridColumns);
$dashboard->setPermissionLevel(Dashboard::PERMISSION_FULL);
- $dashboard->setIsActive(1);
+ // Group-shared dashboards are not "active" per-user — activation
+ // is a personal-scope concept tied to the active-dashboard cookie.
+ $isActive = 0;
+ if ($type === Dashboard::TYPE_USER) {
+ $isActive = 1;
+ }
+
+ $dashboard->setIsActive($isActive);
$dashboard->setCreatedAt($now);
$dashboard->setUpdatedAt($now);
return $dashboard;
}//end create()
+ /**
+ * Assert the (type, groupId) invariant of REQ-DASH-011.
+ *
+ * @param string $type The dashboard type.
+ * @param string|null $groupId The group ID.
+ *
+ * @return void
+ *
+ * @throws InvalidArgumentException When the invariant is violated.
+ */
+ private function assertTypeGroupInvariant(
+ string $type,
+ ?string $groupId
+ ): void {
+ if ($type === Dashboard::TYPE_GROUP_SHARED) {
+ if ($groupId === null || $groupId === '') {
+ throw new InvalidArgumentException(
+ message: 'Dashboard type group_shared requires a non-empty groupId'
+ );
+ }
+
+ return;
+ }
+
+ if ($groupId !== null) {
+ throw new InvalidArgumentException(
+ message: 'Dashboard type '.$type.' must not have a groupId'
+ );
+ }
+ }//end assertTypeGroupInvariant()
+
/**
* Generate a UUID v4.
*
diff --git a/lib/Service/DashboardService.php b/lib/Service/DashboardService.php
index acf6a165..161ca967 100644
--- a/lib/Service/DashboardService.php
+++ b/lib/Service/DashboardService.php
@@ -3,7 +3,8 @@
/**
* DashboardService
*
- * Service for managing dashboards.
+ * Service for managing dashboards (personal, group-shared, and the
+ * visible-to-user resolution endpoint).
*
* @category Service
* @package OCA\MyDash\Service
@@ -23,17 +24,68 @@
use DateTime;
use Exception;
+use OCA\MyDash\AppInfo\Application;
use OCA\MyDash\Db\AdminSetting;
use OCA\MyDash\Db\AdminSettingMapper;
use OCA\MyDash\Db\Dashboard;
use OCA\MyDash\Db\DashboardMapper;
+use OCA\MyDash\Db\WidgetPlacement;
use OCA\MyDash\Db\WidgetPlacementMapper;
+use OCA\MyDash\Exception\PersonalDashboardsDisabledException;
+use OCP\AppFramework\Db\DoesNotExistException;
+use OCP\IConfig;
+use OCP\IDBConnection;
+use OCP\IL10N;
+use OCP\IGroupManager;
+use OCP\IUserManager;
+use Psr\Log\LoggerInterface;
+use Throwable;
/**
* Service for managing dashboards.
+ *
+ * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
*/
class DashboardService
{
+ /**
+ * HTTP-like error message for non-admin attempting an admin-only mutation.
+ *
+ * @var string
+ */
+ public const ERR_FORBIDDEN_NOT_ADMIN = 'Forbidden: admin only';
+
+ /**
+ * Error message returned by the last-in-group delete guard.
+ *
+ * @var string
+ */
+ public const ERR_LAST_IN_GROUP = 'Cannot delete the only dashboard in the group';
+
+ /**
+ * Error message returned when the path-group does not match the record.
+ *
+ * @var string
+ */
+ public const ERR_GROUP_MISMATCH = 'Dashboard does not belong to this group';
+
+ /**
+ * Error message returned when the default-flip target is not found.
+ *
+ * @var string
+ */
+ public const ERR_DEFAULT_TARGET_NOT_IN_GROUP = 'Dashboard not found in group';
+
+ /**
+ * Preference key for the user's last-active dashboard UUID.
+ *
+ * Stored via IConfig::setUserValue / getUserValue.
+ * REQ-DASH-019.
+ *
+ * @var string
+ */
+ public const ACTIVE_DASHBOARD_UUID_PREF_KEY = 'active_dashboard_uuid';
+
/**
* Constructor
*
@@ -43,6 +95,18 @@ class DashboardService
* @param TemplateService $templateService Template service.
* @param DashboardFactory $dashboardFactory Dashboard factory.
* @param DashboardResolver $dashResolver Dashboard resolver.
+ * @param IGroupManager $groupManager Group manager.
+ * @param IUserManager $userManager User manager.
+ * @param IDBConnection $db DB connection (for the
+ * transactional default
+ * flip — REQ-DASH-015).
+ * @param IConfig $config Nextcloud per-user
+ * preference storage.
+ * @param IL10N $l10n Localisation service
+ * (used for the fork
+ * default name —
+ * REQ-DASH-020).
+ * @param LoggerInterface $logger PSR logger.
*/
public function __construct(
private readonly DashboardMapper $dashboardMapper,
@@ -51,15 +115,25 @@ public function __construct(
private readonly TemplateService $templateService,
private readonly DashboardFactory $dashboardFactory,
private readonly DashboardResolver $dashResolver,
+ private readonly IGroupManager $groupManager,
+ private readonly IUserManager $userManager,
+ private readonly IDBConnection $db,
+ private readonly IConfig $config,
+ private readonly IL10N $l10n,
+ private readonly LoggerInterface $logger,
) {
}//end __construct()
/**
* Get all dashboards for a user.
*
+ * Returns only personal `user`-type dashboards owned by the caller —
+ * group-shared dashboards never appear here (REQ-DASH-014, see
+ * `getVisibleToUser` for the unioned endpoint).
+ *
* @param string $userId The user ID.
*
- * @return Dashboard[] The list of dashboards.
+ * @return Dashboard[] The list of personal dashboards.
*/
public function getUserDashboards(string $userId): array
{
@@ -118,6 +192,114 @@ public function createDashboard(
return $this->dashboardMapper->insert(entity: $dashboard);
}//end createDashboard()
+ /**
+ * Fork a visible dashboard as a new personal copy for the caller.
+ *
+ * Implements REQ-DASH-020..022. Creates a new `user`-type dashboard
+ * owned by `$userId`, deep-copies all widget placements from the
+ * source, and makes it the user's active dashboard. The entire
+ * operation runs inside a single DB transaction (REQ-DASH-021).
+ *
+ * Gating rules:
+ * - `allow_user_dashboards` must be `true`; otherwise throws
+ * {@see PersonalDashboardsDisabledException} (→ HTTP 403).
+ * - The source must be visible to `$userId` (any type); otherwise
+ * throws {@see DoesNotExistException} (→ HTTP 404, no info leak).
+ *
+ * Resource URLs in placements are kept as-is — no resource bytes are
+ * duplicated (REQ-DASH-022).
+ *
+ * @param string $userId The calling user ID.
+ * @param string $sourceUuid The UUID of the dashboard to fork.
+ * @param string|null $name Override name; defaults to
+ * `t('My copy of {name}', …)`.
+ *
+ * @return Dashboard The newly created personal dashboard.
+ *
+ * @throws PersonalDashboardsDisabledException When the admin flag is off.
+ * @throws DoesNotExistException When the source is not visible
+ * to the calling user.
+ * @throws \Throwable On any DB error (rolled back).
+ *
+ * @SuppressWarnings(PHPMD.CyclomaticComplexity)
+ */
+ public function forkAsPersonal(
+ string $userId,
+ string $sourceUuid,
+ ?string $name=null
+ ): Dashboard {
+ // REQ-ASET-003 gate — throws PersonalDashboardsDisabledException on failure.
+ $this->assertPersonalDashboardsAllowed();
+
+ // Resolve source from the user's visible set (REQ-DASH-013).
+ // Do NOT fall back to a raw findByUuid — that would leak existence
+ // of dashboards the user cannot see (REQ-DASH-020, 404 scenario).
+ $visible = $this->getVisibleToUser(userId: $userId);
+ $source = null;
+ foreach ($visible as $entry) {
+ if ((string) $entry['dashboard']->getUuid() === $sourceUuid) {
+ $source = $entry['dashboard'];
+ break;
+ }
+ }
+
+ if ($source === null) {
+ throw new DoesNotExistException(
+ msg: 'Dashboard not found or not visible'
+ );
+ }
+
+ // Resolve the fork name — fall back to a translated default.
+ if ($name !== null && $name !== '') {
+ $forkName = $name;
+ } else {
+ $forkName = $this->l10n->t(
+ 'My copy of {name}',
+ ['name' => (string) $source->getName()]
+ );
+ }
+
+ $this->db->beginTransaction();
+ try {
+ // Build the new personal dashboard entity.
+ $newDash = $this->dashboardFactory->create(
+ userId: $userId,
+ name: $forkName,
+ type: Dashboard::TYPE_USER,
+ groupId: null,
+ gridColumns: (int) $source->getGridColumns()
+ );
+ // Forks are never defaults (REQ-DASH-020 scenario).
+ $newDash->setIsDefault(0);
+
+ // Deactivate other personal dashboards BEFORE insert so the
+ // factory-set isActive=1 on the new row stays clean.
+ $this->dashboardMapper->deactivateAllForUser(userId: $userId);
+
+ // Persist the new dashboard row.
+ $newDash = $this->dashboardMapper->insert(entity: $newDash);
+
+ // Deep-copy placements (REQ-DASH-020, REQ-DASH-022).
+ $this->placementMapper->cloneToDashboard(
+ sourceDashboardId: (int) $source->getId(),
+ targetDashboardId: (int) $newDash->getId()
+ );
+
+ // Persist the active-dashboard preference (REQ-DASH-019).
+ $this->setActivePreference(
+ userId: $userId,
+ uuid: (string) $newDash->getUuid()
+ );
+
+ $this->db->commit();
+ } catch (Throwable $t) {
+ $this->db->rollBack();
+ throw $t;
+ }//end try
+
+ return $newDash;
+ }//end forkAsPersonal()
+
/**
* Update a dashboard.
*
@@ -195,6 +377,557 @@ public function activateDashboard(
return $dashboard;
}//end activateDashboard()
+ /**
+ * List the group-shared dashboards in a single group.
+ *
+ * Any logged-in user may list — REQ-DASH-014.
+ *
+ * @param string $groupId The group ID.
+ *
+ * @return Dashboard[] The group-shared dashboards in the group.
+ */
+ public function listGroupDashboards(string $groupId): array
+ {
+ return $this->dashboardMapper->findByGroup(groupId: $groupId);
+ }//end listGroupDashboards()
+
+ /**
+ * Find a single group-shared dashboard, validating the path-group.
+ *
+ * Returns the dashboard only when its `groupId` matches the path
+ * parameter — otherwise the caller treats it as a 404.
+ * REQ-DASH-014 (group-id mismatch returns 404).
+ *
+ * @param string $groupId The group ID from the URL.
+ * @param string $uuid The dashboard UUID from the URL.
+ *
+ * @return Dashboard The dashboard.
+ *
+ * @throws DoesNotExistException When no dashboard with that UUID
+ * exists, or when its `groupId` does
+ * not match the path parameter, or
+ * when its type is not group_shared.
+ */
+ public function findGroupDashboard(
+ string $groupId,
+ string $uuid
+ ): Dashboard {
+ $dashboard = $this->dashboardMapper->findByUuid(uuid: $uuid);
+
+ if ($dashboard->getType() !== Dashboard::TYPE_GROUP_SHARED) {
+ throw new DoesNotExistException(
+ msg: self::ERR_GROUP_MISMATCH
+ );
+ }
+
+ if ($dashboard->getGroupId() !== $groupId) {
+ throw new DoesNotExistException(
+ msg: self::ERR_GROUP_MISMATCH
+ );
+ }
+
+ return $dashboard;
+ }//end findGroupDashboard()
+
+ /**
+ * Create a new group-shared dashboard.
+ *
+ * Admin-only — caller MUST have validated the actor with
+ * {@see DashboardService::isAdmin()}. The route attribute alone is
+ * not enough (per Hydra semantic-auth gate).
+ *
+ * @param string $actorUserId The acting user ID (for the admin
+ * check).
+ * @param string $groupId The group ID.
+ * @param string $name The dashboard name.
+ * @param string|null $description The dashboard description.
+ * @param int $gridColumns The grid column count.
+ *
+ * @return Dashboard The created group-shared dashboard.
+ *
+ * @throws Exception When the actor is not an administrator.
+ */
+ public function createGroupShared(
+ string $actorUserId,
+ string $groupId,
+ string $name,
+ ?string $description=null,
+ int $gridColumns=12
+ ): Dashboard {
+ if ($this->isAdmin(userId: $actorUserId) === false) {
+ throw new Exception(message: self::ERR_FORBIDDEN_NOT_ADMIN);
+ }
+
+ $dashboard = $this->dashboardFactory->create(
+ userId: null,
+ name: $name,
+ description: $description,
+ type: Dashboard::TYPE_GROUP_SHARED,
+ groupId: $groupId,
+ gridColumns: $gridColumns
+ );
+ $dashboard->setPermissionLevel(Dashboard::PERMISSION_VIEW_ONLY);
+ // REQ-DASH-016: new group-shared rows always start non-default.
+ // Promotion is only possible via the dedicated
+ // POST /api/dashboards/group/{groupId}/default endpoint.
+ $dashboard->setIsDefault(0);
+
+ return $this->dashboardMapper->insert(entity: $dashboard);
+ }//end createGroupShared()
+
+ /**
+ * Update a group-shared dashboard.
+ *
+ * Admin-only. The path's `groupId` must match the record's `groupId`
+ * — otherwise `DoesNotExistException` (treated as 404 by caller).
+ * The `userId` field is intentionally never patched (REQ-DASH-014).
+ *
+ * @param string $actorUserId The acting user ID (for the admin check).
+ * @param string $groupId The group ID from the URL.
+ * @param string $uuid The dashboard UUID from the URL.
+ * @param array $patch The patch data (name, description,
+ * gridColumns, placements supported).
+ *
+ * @return Dashboard The updated dashboard.
+ *
+ * @throws Exception When the actor is not an administrator.
+ * @throws DoesNotExistException On 404.
+ */
+ public function updateGroupShared(
+ string $actorUserId,
+ string $groupId,
+ string $uuid,
+ array $patch
+ ): Dashboard {
+ if ($this->isAdmin(userId: $actorUserId) === false) {
+ throw new Exception(message: self::ERR_FORBIDDEN_NOT_ADMIN);
+ }
+
+ $dashboard = $this->findGroupDashboard(
+ groupId: $groupId,
+ uuid: $uuid
+ );
+
+ // REQ-DASH-017: PUT MUST NOT mutate `isDefault` regardless of
+ // payload contents. Drop the field defensively before applying
+ // updates — even though `applyDashboardUpdates` already ignores
+ // unknown keys, we strip it explicitly so the contract is
+ // visible at the service boundary.
+ unset($patch['isDefault']);
+
+ $this->applyDashboardUpdates(
+ dashboard: $dashboard,
+ data: $patch
+ );
+
+ return $this->dashboardMapper->update(entity: $dashboard);
+ }//end updateGroupShared()
+
+ /**
+ * Delete a group-shared dashboard.
+ *
+ * Admin-only. The last-in-group guard returns an `Exception` (the
+ * controller maps to HTTP 400) when removing the row would leave
+ * the group with zero group-shared dashboards. The `default` group
+ * is exempt from the guard. REQ-DASH-014.
+ *
+ * @param string $actorUserId The acting user ID.
+ * @param string $groupId The group ID from the URL.
+ * @param string $uuid The dashboard UUID from the URL.
+ *
+ * @return void
+ *
+ * @throws Exception When the actor is not admin, or the
+ * last-in-group guard rejects the delete.
+ * @throws DoesNotExistException On 404.
+ */
+ public function deleteGroupShared(
+ string $actorUserId,
+ string $groupId,
+ string $uuid
+ ): void {
+ if ($this->isAdmin(userId: $actorUserId) === false) {
+ throw new Exception(message: self::ERR_FORBIDDEN_NOT_ADMIN);
+ }
+
+ $dashboard = $this->findGroupDashboard(
+ groupId: $groupId,
+ uuid: $uuid
+ );
+
+ if ($groupId !== Dashboard::DEFAULT_GROUP_ID) {
+ $count = $this->dashboardMapper->countByGroup(
+ groupId: $groupId
+ );
+ if ($count <= 1) {
+ throw new Exception(message: self::ERR_LAST_IN_GROUP);
+ }
+ }
+
+ $this->placementMapper->deleteByDashboardId(
+ dashboardId: $dashboard->getId()
+ );
+ $this->dashboardMapper->delete(entity: $dashboard);
+ }//end deleteGroupShared()
+
+ /**
+ * Promote a single group-shared dashboard to the group's default.
+ *
+ * Admin-only. Wraps both mapper writes — clear the existing default
+ * on every other dashboard in the group, then set the target to
+ * `is_default = 1` — in a single DB transaction so concurrent
+ * promotions cannot leave two rows with `is_default = 1` in the
+ * same group. REQ-DASH-015.
+ *
+ * Order of operations matters: we issue the SET first; if the
+ * target uuid does not belong to the group the row count is `0`
+ * and we throw {@see DoesNotExistException} (mapped to HTTP 404 by
+ * the controller). The transaction is then rolled back, leaving
+ * the previous default untouched.
+ *
+ * @param string $actorUserId The acting user ID (for the admin
+ * check).
+ * @param string $groupId The group ID from the URL.
+ * @param string $uuid The dashboard UUID from the URL.
+ *
+ * @return void
+ *
+ * @throws Exception When the actor is not an admin.
+ * @throws DoesNotExistException When the uuid does not belong to
+ * the given group.
+ */
+ public function setGroupDefault(
+ string $actorUserId,
+ string $groupId,
+ string $uuid
+ ): void {
+ if ($this->isAdmin(userId: $actorUserId) === false) {
+ throw new Exception(message: self::ERR_FORBIDDEN_NOT_ADMIN);
+ }
+
+ $this->db->beginTransaction();
+ try {
+ $affected = $this->dashboardMapper->setGroupDefaultUuid(
+ groupId: $groupId,
+ uuid: $uuid
+ );
+
+ if ($affected === 0) {
+ // The target uuid does not belong to this group — roll
+ // back so the existing default in the group is
+ // preserved. REQ-DASH-015 scenario "Default cannot be
+ // set across groups".
+ $this->db->rollBack();
+ throw new DoesNotExistException(
+ msg: self::ERR_DEFAULT_TARGET_NOT_IN_GROUP
+ );
+ }
+
+ $this->dashboardMapper->clearGroupDefaults(
+ groupId: $groupId,
+ exceptUuid: $uuid
+ );
+
+ $this->db->commit();
+ } catch (DoesNotExistException $e) {
+ // Already rolled back above — re-throw for the controller.
+ throw $e;
+ } catch (Throwable $t) {
+ $this->db->rollBack();
+ throw $t;
+ }//end try
+ }//end setGroupDefault()
+
+ /**
+ * Get all dashboards visible to a user, source-tagged.
+ *
+ * Wires `IGroupManager::getUserGroupIds()` into the mapper's union
+ * query and returns the deduplicated list with `source` set per row.
+ * REQ-DASH-013.
+ *
+ * @param string $userId The user ID.
+ *
+ * @return array
+ * List of {dashboard, source} pairs.
+ */
+ public function getVisibleToUser(string $userId): array
+ {
+ $user = $this->userManager->get(uid: $userId);
+ if ($user === null) {
+ return [];
+ }
+
+ $userGroupIds = $this->groupManager->getUserGroupIds(user: $user);
+
+ return $this->dashboardMapper->findVisibleToUser(
+ userId: $userId,
+ userGroupIds: $userGroupIds
+ );
+ }//end getVisibleToUser()
+
+ /**
+ * Resolve the active dashboard for a user using the 7-step precedence
+ * chain defined in REQ-DASH-018.
+ *
+ * Steps:
+ * 1. Saved `active_dashboard_uuid` preference — if the UUID resolves to
+ * a dashboard currently visible to the user (REQ-DASH-013).
+ * 2. `group_shared` with `isDefault = 1` in the user's primary group.
+ * 3. `group_shared` with `isDefault = 1` in the `'default'` group.
+ * 4. First `group_shared` (by sortOrder ASC, then createdAt) in the
+ * user's primary group.
+ * 5. First `group_shared` in the `'default'` group.
+ * 6. User's first personal (`user`-type) dashboard.
+ * 7. `null` — triggers the empty-state UI.
+ *
+ * The only side-effect on read is the stale-pref auto-clear in step 1:
+ * when the saved UUID is not visible the pref is deleted and a WARNING
+ * is logged before falling through to step 2.
+ *
+ * @param string $userId The user ID.
+ * @param string|null $primaryGroupId The user's primary group ID, or null /
+ * {@see Dashboard::DEFAULT_GROUP_ID}.
+ *
+ * @return array{dashboard: Dashboard, source: string}|null
+ * `{dashboard, source}` where source is `'user'`, `'group'`, or
+ * `'default'`; or `null` when no dashboard exists at all.
+ */
+ public function resolveActiveDashboard(
+ string $userId,
+ ?string $primaryGroupId
+ ): ?array {
+ // Normalise the sentinel so steps 2-5 can rely on it.
+ if ($primaryGroupId === null || $primaryGroupId === '') {
+ $groupId = Dashboard::DEFAULT_GROUP_ID;
+ } else {
+ $groupId = $primaryGroupId;
+ }
+
+ // Pre-fetch all visible dashboards once — used for the pref lookup
+ // and to avoid redundant DB round-trips.
+ $visible = $this->getVisibleToUser(userId: $userId);
+
+ // Build a UUID-keyed index for O(1) pref lookup.
+ /**
+ * UUID-keyed index of the visible-to-user dashboard list.
+ *
+ * @var array $byUuid
+ */
+ $byUuid = [];
+ foreach ($visible as $entry) {
+ $uuid = (string) $entry['dashboard']->getUuid();
+ if ($uuid !== '') {
+ $byUuid[$uuid] = $entry;
+ }
+ }
+
+ // Step 1: saved preference.
+ $savedUuid = $this->config->getUserValue(
+ userId: $userId,
+ appName: Application::APP_ID,
+ key: self::ACTIVE_DASHBOARD_UUID_PREF_KEY,
+ default: ''
+ );
+
+ if ($savedUuid !== '') {
+ if (isset($byUuid[$savedUuid]) === true) {
+ return $byUuid[$savedUuid];
+ }
+
+ // Stale pref: UUID is no longer visible — clear and fall through.
+ $this->config->deleteUserValue(
+ userId: $userId,
+ appName: Application::APP_ID,
+ key: self::ACTIVE_DASHBOARD_UUID_PREF_KEY
+ );
+ $this->logger->warning(
+ message: 'mydash: stale active_dashboard_uuid "{uuid}" cleared for user "{user}"',
+ context: ['uuid' => $savedUuid, 'user' => $userId]
+ );
+ }
+
+ // Steps 2-3: group-shared with isDefault = 1.
+ if ($groupId !== Dashboard::DEFAULT_GROUP_ID) {
+ // Step 2: primary group default.
+ $result = $this->findFirstGroupSharedWhere(
+ visible: $visible,
+ groupId: $groupId,
+ source: Dashboard::SOURCE_GROUP,
+ requireDefault: true
+ );
+ if ($result !== null) {
+ return $result;
+ }
+ }
+
+ // Step 3: default-group default.
+ $result = $this->findFirstGroupSharedWhere(
+ visible: $visible,
+ groupId: Dashboard::DEFAULT_GROUP_ID,
+ source: Dashboard::SOURCE_DEFAULT,
+ requireDefault: true
+ );
+ if ($result !== null) {
+ return $result;
+ }
+
+ // Steps 4-5: first group-shared (sortOrder ASC, createdAt ASC).
+ if ($groupId !== Dashboard::DEFAULT_GROUP_ID) {
+ // Step 4: primary group first.
+ $result = $this->findFirstGroupSharedWhere(
+ visible: $visible,
+ groupId: $groupId,
+ source: Dashboard::SOURCE_GROUP,
+ requireDefault: false
+ );
+ if ($result !== null) {
+ return $result;
+ }
+ }
+
+ // Step 5: default-group first.
+ $result = $this->findFirstGroupSharedWhere(
+ visible: $visible,
+ groupId: Dashboard::DEFAULT_GROUP_ID,
+ source: Dashboard::SOURCE_DEFAULT,
+ requireDefault: false
+ );
+ if ($result !== null) {
+ return $result;
+ }
+
+ // Step 6: first personal dashboard.
+ foreach ($visible as $entry) {
+ if ($entry['source'] === Dashboard::SOURCE_USER) {
+ return $entry;
+ }
+ }
+
+ // Step 7: nothing found.
+ return null;
+ }//end resolveActiveDashboard()
+
+ /**
+ * Persist (or clear) the user's active-dashboard preference.
+ *
+ * Accepts any non-empty UUID string without performing an existence
+ * check — the resolver's stale-pref path handles invalid UUIDs on next
+ * read (REQ-DASH-019 "no existence check on write").
+ *
+ * @param string $userId The user ID.
+ * @param string $uuid The dashboard UUID, or empty string to clear.
+ *
+ * @return void
+ */
+ public function setActivePreference(string $userId, string $uuid): void
+ {
+ if ($uuid === '') {
+ $this->config->deleteUserValue(
+ userId: $userId,
+ appName: Application::APP_ID,
+ key: self::ACTIVE_DASHBOARD_UUID_PREF_KEY
+ );
+ return;
+ }
+
+ $this->config->setUserValue(
+ userId: $userId,
+ appName: Application::APP_ID,
+ key: self::ACTIVE_DASHBOARD_UUID_PREF_KEY,
+ value: $uuid
+ );
+ }//end setActivePreference()
+
+ /**
+ * Check whether the given user is a Nextcloud administrator.
+ *
+ * Wraps `IGroupManager::isAdmin()` so callers don't have to import
+ * the interface and so tests can stub one method.
+ *
+ * @param string $userId The user ID.
+ *
+ * @return bool Whether the user is an admin.
+ */
+ public function isAdmin(string $userId): bool
+ {
+ return $this->groupManager->isAdmin(userId: $userId);
+ }//end isAdmin()
+
+ /**
+ * Assert that personal-dashboard creation is permitted by admin settings.
+ *
+ * Implements REQ-ASET-003 runtime gating: when the admin flag
+ * `allow_user_dashboards` is `false` (or absent — default is `false`),
+ * creation of `type='user'` dashboards MUST be blocked at the service
+ * boundary. Read / update / delete operations on existing personal
+ * dashboards MUST NOT call this method.
+ *
+ * @return void
+ *
+ * @throws PersonalDashboardsDisabledException When the flag is off.
+ */
+ public function assertPersonalDashboardsAllowed(): void
+ {
+ $allowed = $this->settingMapper->getValue(
+ key: AdminSetting::KEY_ALLOW_USER_DASHBOARDS,
+ default: false
+ );
+
+ if ($allowed !== true) {
+ throw new PersonalDashboardsDisabledException();
+ }
+ }//end assertPersonalDashboardsAllowed()
+
+ /**
+ * Scan the pre-fetched visible list for the first group-shared dashboard
+ * matching a given `groupId`, optionally filtered to `isDefault = 1`.
+ *
+ * The visible list preserves mapper order (sortOrder ASC, createdAt ASC
+ * for group-shared rows via {@see DashboardMapper::findByGroup}), so the
+ * "first" result is already correctly ordered without a secondary sort
+ * here.
+ *
+ * @param array $visible The full visible-to-user list.
+ * @param string $groupId The group ID to filter on.
+ * @param string $source Expected source tag
+ * (`'group'` or `'default'`).
+ * @param bool $requireDefault When true, only rows with
+ * `isDefault = 1` are considered.
+ *
+ * @return array{dashboard: Dashboard, source: string}|null
+ */
+ private function findFirstGroupSharedWhere(
+ array $visible,
+ string $groupId,
+ string $source,
+ bool $requireDefault
+ ): ?array {
+ foreach ($visible as $entry) {
+ if ($entry['source'] !== $source) {
+ continue;
+ }
+
+ $dashboard = $entry['dashboard'];
+ if ($dashboard->getType() !== Dashboard::TYPE_GROUP_SHARED) {
+ continue;
+ }
+
+ if ($dashboard->getGroupId() !== $groupId) {
+ continue;
+ }
+
+ if ($requireDefault === true
+ && (int) $dashboard->getIsDefault() !== 1
+ ) {
+ continue;
+ }
+
+ return $entry;
+ }//end foreach
+
+ return null;
+ }//end findFirstGroupSharedWhere()
+
/**
* Try to create a dashboard from a template or empty.
*
@@ -274,7 +1007,7 @@ private function createDefaultPlacements(int $dashboardId): array
$placements = [];
foreach ($defaults as $config) {
- $placement = new \OCA\MyDash\Db\WidgetPlacement();
+ $placement = new WidgetPlacement();
$placement->setDashboardId($dashboardId);
$placement->setWidgetId($config['widgetId']);
$placement->setGridX($config['gridX']);
diff --git a/lib/Service/DashboardShareService.php b/lib/Service/DashboardShareService.php
new file mode 100644
index 00000000..f68f6d44
--- /dev/null
+++ b/lib/Service/DashboardShareService.php
@@ -0,0 +1,570 @@
+
+ * @copyright 2026 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2026 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Service;
+
+use DateTime;
+use Exception;
+use InvalidArgumentException;
+use OCA\MyDash\Db\Dashboard;
+use OCA\MyDash\Db\DashboardMapper;
+use OCA\MyDash\Db\DashboardShare;
+use OCA\MyDash\Db\DashboardShareMapper;
+use OCP\AppFramework\Db\DoesNotExistException;
+use OCP\IDBConnection;
+use OCP\IGroupManager;
+use OCP\Notification\IManager as INotificationManager;
+use Throwable;
+
+/**
+ * Service for creating and managing dashboard shares.
+ *
+ * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
+ */
+class DashboardShareService
+{
+
+ /**
+ * Permission level ordering for upgrade detection (higher index = more).
+ *
+ * @var array
+ */
+ private const LEVEL_ORDER = [
+ Dashboard::PERMISSION_VIEW_ONLY => 0,
+ Dashboard::PERMISSION_ADD_ONLY => 1,
+ Dashboard::PERMISSION_FULL => 2,
+ ];
+
+ /**
+ * Constructor
+ *
+ * @param DashboardShareMapper $shareMapper The share mapper.
+ * @param DashboardMapper $dashboardMapper The dashboard mapper.
+ * @param IGroupManager $groupManager The group manager.
+ * @param INotificationManager $notificationManager The notification manager.
+ * @param IDBConnection $db The DB connection.
+ */
+ public function __construct(
+ private readonly DashboardShareMapper $shareMapper,
+ private readonly DashboardMapper $dashboardMapper,
+ private readonly IGroupManager $groupManager,
+ private readonly INotificationManager $notificationManager,
+ private readonly IDBConnection $db,
+ ) {
+ }//end __construct()
+
+ /**
+ * List all shares for a dashboard.
+ *
+ * @param int $dashboardId The dashboard ID.
+ * @param string $userId The calling user ID (must own the dashboard).
+ *
+ * @return DashboardShare[] The shares.
+ *
+ * @throws Exception When the user is not the dashboard owner.
+ */
+ public function listShares(int $dashboardId, string $userId): array
+ {
+ $this->assertOwner(dashboardId: $dashboardId, userId: $userId);
+ return $this->shareMapper->findByDashboardId(dashboardId: $dashboardId);
+ }//end listShares()
+
+ /**
+ * Add or upsert a single share. Publishes a notification when the
+ * entry is new or the permission level is upgraded. REQ-SHARE-008.
+ *
+ * @param int $dashboardId The dashboard ID.
+ * @param string $shareType The share type ('user' or 'group').
+ * @param string $shareWith The recipient user/group ID.
+ * @param string $permissionLevel The permission level.
+ * @param string $callerId The calling user (must be dashboard owner).
+ *
+ * @return DashboardShare The persisted share.
+ *
+ * @throws Exception When the caller is not the owner or input is invalid.
+ */
+ public function addShare(
+ int $dashboardId,
+ string $shareType,
+ string $shareWith,
+ string $permissionLevel,
+ string $callerId
+ ): DashboardShare {
+ $dashboard = $this->assertOwner(
+ dashboardId: $dashboardId,
+ userId: $callerId
+ );
+ $this->validateInput(
+ shareType: $shareType,
+ shareWith: $shareWith,
+ permissionLevel: $permissionLevel
+ );
+
+ $result = $this->persistShare(
+ dashboardId: $dashboardId,
+ shareType: $shareType,
+ shareWith: $shareWith,
+ permissionLevel: $permissionLevel
+ );
+
+ if ($result['isNew'] === true || $result['isUpgrade'] === true) {
+ $this->notifyShared(
+ share: $result['share'],
+ sharerUserId: $callerId,
+ dashboardName: (string) $dashboard->getName()
+ );
+ }
+
+ return $result['share'];
+ }//end addShare()
+
+ /**
+ * Remove a share by ID. Silent — no notification is published.
+ * REQ-SHARE-008 (revocations are silent).
+ *
+ * @param int $shareId The share ID.
+ * @param string $callerId The calling user (must be dashboard owner).
+ *
+ * @return void
+ *
+ * @throws Exception When the share does not exist or caller is not owner.
+ */
+ public function removeShare(int $shareId, string $callerId): void
+ {
+ $share = $this->shareMapper->find(id: $shareId);
+ $dashboard = $this->dashboardMapper->find(
+ id: (int) $share->getDashboardId()
+ );
+
+ if ($dashboard->getUserId() !== $callerId) {
+ throw new Exception(message: 'Access denied');
+ }
+
+ $this->shareMapper->delete(entity: $share);
+ }//end removeShare()
+
+ /**
+ * Atomically replace all shares for a dashboard. REQ-SHARE-009.
+ *
+ * Deletes every existing share not in the payload, upserts matching
+ * ones. Publishes one notification per newly-added or upgraded
+ * recipient only. All DB writes run in a single transaction.
+ *
+ * @param int $dashboardId The dashboard ID.
+ * @param array $shares Array of {shareType, shareWith, permissionLevel}.
+ * @param string $userId The calling user (must be dashboard owner).
+ *
+ * @return DashboardShare[] The new full share list.
+ *
+ * @throws Exception When the caller is not the owner or input is invalid.
+ * @throws Throwable On DB error (rolls back).
+ */
+ public function replaceShares(
+ int $dashboardId,
+ array $shares,
+ string $userId
+ ): array {
+ $dashboard = $this->assertOwner(
+ dashboardId: $dashboardId,
+ userId: $userId
+ );
+
+ // Validate all entries up-front before touching the DB.
+ foreach ($shares as $entry) {
+ $this->validateInput(
+ shareType: $entry['shareType'] ?? '',
+ shareWith: $entry['shareWith'] ?? '',
+ permissionLevel: $entry['permissionLevel'] ?? ''
+ );
+ }
+
+ // Build the keep-key set for deletion.
+ $keepKeys = [];
+ foreach ($shares as $entry) {
+ $keepKeys[] = $entry['shareType'].':'.$entry['shareWith'];
+ }
+
+ $notifyQueue = [];
+
+ $this->db->beginTransaction();
+ try {
+ // Remove shares not in payload.
+ $this->shareMapper->deleteNotIn(
+ dashboardId: $dashboardId,
+ keepKeys: $keepKeys
+ );
+
+ // Upsert each entry.
+ foreach ($shares as $entry) {
+ $result = $this->persistShare(
+ dashboardId: $dashboardId,
+ shareType: $entry['shareType'],
+ shareWith: $entry['shareWith'],
+ permissionLevel: $entry['permissionLevel']
+ );
+
+ if ($result['isNew'] === true || $result['isUpgrade'] === true) {
+ $notifyQueue[] = $result['share'];
+ }
+ }
+
+ $this->db->commit();
+ } catch (Throwable $t) {
+ $this->db->rollBack();
+ throw $t;
+ }//end try
+
+ // Publish notifications after the transaction commits.
+ $dashboardName = (string) $dashboard->getName();
+ foreach ($notifyQueue as $share) {
+ $this->notifyShared(
+ share: $share,
+ sharerUserId: $userId,
+ dashboardName: $dashboardName
+ );
+ }
+
+ return $this->shareMapper->findByDashboardId(dashboardId: $dashboardId);
+ }//end replaceShares()
+
+ /**
+ * Remove every share where the caller is the owner AND the share targets
+ * the named recipient. REQ-SHARE-010.
+ *
+ * Only touches dashboards owned by $callerId — shares on dashboards
+ * owned by others are not affected even if $callerId holds a `full`
+ * share on them.
+ *
+ * @param string $shareType The share type.
+ * @param string $shareWith The recipient user/group ID.
+ * @param string $callerId The calling user (owner restriction).
+ *
+ * @return int The number of share rows deleted.
+ *
+ * @throws InvalidArgumentException When shareType is invalid.
+ */
+ public function revokeAllForRecipient(
+ string $shareType,
+ string $shareWith,
+ string $callerId
+ ): int {
+ $validType = in_array(
+ needle: $shareType,
+ haystack: DashboardShare::VALID_SHARE_TYPES,
+ strict: true
+ );
+ if ($validType === false) {
+ throw new InvalidArgumentException(
+ message: 'Invalid shareType: '.$shareType
+ );
+ }
+
+ return $this->shareMapper->deleteByOwnerAndRecipient(
+ shareType: $shareType,
+ shareWith: $shareWith,
+ ownerId: $callerId
+ );
+ }//end revokeAllForRecipient()
+
+ /**
+ * Transfer dashboard ownership to a new user.
+ *
+ * Updates the dashboard's user_id, removes the share row that
+ * previously gave the new owner access, and stamps updated_at.
+ * REQ-SHARE-013 (internal helper called by UserDeletedListener).
+ *
+ * @param int $dashboardId The dashboard ID.
+ * @param string $newUserId The new owner's user ID.
+ *
+ * @return void
+ */
+ public function transferOwnership(int $dashboardId, string $newUserId): void
+ {
+ $dashboard = $this->dashboardMapper->find(id: $dashboardId);
+
+ // Update ownership.
+ $dashboard->setUserId($newUserId);
+ $dashboard->setUpdatedAt(
+ (new DateTime())->format(format: 'Y-m-d H:i:s')
+ );
+ $this->dashboardMapper->update(entity: $dashboard);
+
+ // Remove the share row that gave newUserId access (they now own it).
+ $existingShare = $this->shareMapper->findShare(
+ dashboardId: $dashboardId,
+ shareType: DashboardShare::SHARE_TYPE_USER,
+ shareWith: $newUserId
+ );
+ if ($existingShare !== null) {
+ $this->shareMapper->delete(entity: $existingShare);
+ }
+ }//end transferOwnership()
+
+ /**
+ * Publish a `dashboard_ownership_transferred` notification.
+ *
+ * @param string $newOwnerId The new owner's user ID.
+ * @param int $dashboardId The dashboard ID.
+ * @param string $dashboardName The dashboard name.
+ *
+ * @return void
+ */
+ public function notifyOwnershipTransferred(
+ string $newOwnerId,
+ int $dashboardId,
+ string $dashboardName
+ ): void {
+ $notification = $this->notificationManager->createNotification();
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $notification->setApp('mydash')
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ ->setUser($newOwnerId)
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ ->setDateTime(new \DateTime())
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ ->setObject('dashboard', (string) $dashboardId)
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ ->setSubject('dashboard_ownership_transferred', [$dashboardName]);
+
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $this->notificationManager->notify($notification);
+ }//end notifyOwnershipTransferred()
+
+ /**
+ * Persist a single share (insert or update). Returns metadata about
+ * whether the row is new or the level was upgraded.
+ *
+ * @param int $dashboardId The dashboard ID.
+ * @param string $shareType The share type.
+ * @param string $shareWith The recipient.
+ * @param string $permissionLevel The permission level.
+ *
+ * @return array{share: DashboardShare, isNew: bool, isUpgrade: bool}
+ */
+ private function persistShare(
+ int $dashboardId,
+ string $shareType,
+ string $shareWith,
+ string $permissionLevel
+ ): array {
+ $now = (new DateTime())->format(format: 'Y-m-d H:i:s');
+ $existing = $this->shareMapper->findShare(
+ dashboardId: $dashboardId,
+ shareType: $shareType,
+ shareWith: $shareWith
+ );
+
+ if ($existing === null) {
+ // Insert new share.
+ $share = new DashboardShare();
+ $share->setDashboardId($dashboardId);
+ $share->setShareType($shareType);
+ $share->setShareWith($shareWith);
+ $share->setPermissionLevel($permissionLevel);
+ $share->setCreatedAt($now);
+ $share->setUpdatedAt($now);
+
+ return [
+ 'share' => $this->shareMapper->insert(entity: $share),
+ 'isNew' => true,
+ 'isUpgrade' => false,
+ ];
+ }
+
+ // Detect upgrade.
+ $oldLevel = (string) $existing->getPermissionLevel();
+ $newOrder = (self::LEVEL_ORDER[$permissionLevel] ?? 0);
+ $oldOrder = (self::LEVEL_ORDER[$oldLevel] ?? 0);
+ $isUpgrade = ($newOrder > $oldOrder);
+
+ // No-op: same level.
+ if ($oldLevel === $permissionLevel) {
+ return [
+ 'share' => $existing,
+ 'isNew' => false,
+ 'isUpgrade' => false,
+ ];
+ }
+
+ // Update level.
+ $existing->setPermissionLevel($permissionLevel);
+ $existing->setUpdatedAt($now);
+
+ return [
+ 'share' => $this->shareMapper->update(entity: $existing),
+ 'isNew' => false,
+ 'isUpgrade' => $isUpgrade,
+ ];
+ }//end persistShare()
+
+ /**
+ * Publish `dashboard_shared` notifications for a share.
+ *
+ * For `user`-type shares: one notification.
+ * For `group`-type shares: fan out one notification per current group
+ * member, excluding the sharer. REQ-SHARE-008.
+ *
+ * @param DashboardShare $share The share row.
+ * @param string $sharerUserId The user who created the share.
+ * @param string $dashboardName The dashboard name.
+ *
+ * @return void
+ */
+ private function notifyShared(
+ DashboardShare $share,
+ string $sharerUserId,
+ string $dashboardName
+ ): void {
+ $recipients = $this->resolveRecipients(
+ share: $share,
+ excludeUserId: $sharerUserId
+ );
+
+ foreach ($recipients as $recipientId) {
+ $notification = $this->notificationManager->createNotification();
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $notification->setApp('mydash')
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ ->setUser($recipientId)
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ ->setDateTime(new \DateTime())
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ ->setObject('dashboard', (string) $share->getDashboardId())
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ ->setSubject(
+ 'dashboard_shared',
+ [
+ $sharerUserId,
+ $dashboardName,
+ (string) $share->getPermissionLevel(),
+ ]
+ );
+
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $this->notificationManager->notify($notification);
+ }//end foreach
+ }//end notifyShared()
+
+ /**
+ * Resolve the recipient user IDs for a share.
+ *
+ * @param DashboardShare $share The share.
+ * @param string $excludeUserId A user ID to exclude (the sharer).
+ *
+ * @return string[] The recipient user IDs.
+ */
+ private function resolveRecipients(
+ DashboardShare $share,
+ string $excludeUserId
+ ): array {
+ if ($share->getShareType() === DashboardShare::SHARE_TYPE_USER) {
+ $uid = (string) $share->getShareWith();
+ if ($uid === $excludeUserId) {
+ return [];
+ }
+
+ return [$uid];
+ }
+
+ // Group share — expand members.
+ $groupId = (string) $share->getShareWith();
+ $group = $this->groupManager->get(gid: $groupId);
+ if ($group === null) {
+ return [];
+ }
+
+ $recipients = [];
+ foreach ($group->getUsers() as $user) {
+ $uid = $user->getUID();
+ if ($uid !== $excludeUserId) {
+ $recipients[] = $uid;
+ }
+ }
+
+ return $recipients;
+ }//end resolveRecipients()
+
+ /**
+ * Validate share type, shareWith, and permission level.
+ *
+ * @param string $shareType The share type.
+ * @param string $shareWith The recipient.
+ * @param string $permissionLevel The permission level.
+ *
+ * @return void
+ *
+ * @throws InvalidArgumentException On invalid input.
+ */
+ private function validateInput(
+ string $shareType,
+ string $shareWith,
+ string $permissionLevel
+ ): void {
+ $validType = in_array(
+ needle: $shareType,
+ haystack: DashboardShare::VALID_SHARE_TYPES,
+ strict: true
+ );
+ if ($validType === false) {
+ throw new InvalidArgumentException(
+ message: 'Invalid shareType: '.$shareType
+ );
+ }
+
+ if ($shareWith === '') {
+ throw new InvalidArgumentException(message: 'shareWith is required');
+ }
+
+ $validLevel = in_array(
+ needle: $permissionLevel,
+ haystack: DashboardShare::VALID_PERMISSION_LEVELS,
+ strict: true
+ );
+ if ($validLevel === false) {
+ throw new InvalidArgumentException(
+ message: 'Invalid permissionLevel: '.$permissionLevel
+ );
+ }
+ }//end validateInput()
+
+ /**
+ * Assert the caller is the dashboard owner and return the dashboard.
+ *
+ * @param int $dashboardId The dashboard ID.
+ * @param string $userId The expected owner.
+ *
+ * @return Dashboard The dashboard.
+ *
+ * @throws Exception When the user is not the owner.
+ */
+ private function assertOwner(int $dashboardId, string $userId): Dashboard
+ {
+ $dashboard = $this->dashboardMapper->find(id: $dashboardId);
+
+ if ($dashboard->getUserId() !== $userId) {
+ throw new Exception(message: 'Access denied');
+ }
+
+ return $dashboard;
+ }//end assertOwner()
+}//end class
diff --git a/lib/Service/FileService.php b/lib/Service/FileService.php
new file mode 100644
index 00000000..8089e06f
--- /dev/null
+++ b/lib/Service/FileService.php
@@ -0,0 +1,267 @@
+
+ * @copyright 2026 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2026 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Service;
+
+use OCA\MyDash\Db\AdminSettingMapper;
+use OCA\MyDash\Exception\ForbiddenExtensionException;
+use OCA\MyDash\Exception\InvalidDirectoryException;
+use OCA\MyDash\Exception\InvalidFilenameException;
+use OCP\Files\IRootFolder;
+use OCP\IURLGenerator;
+
+/**
+ * Creates files in user Nextcloud space with strict validation.
+ */
+class FileService
+{
+
+ /**
+ * Default allowed file extensions.
+ *
+ * @var string[]
+ */
+ private const DEFAULT_ALLOWED_EXTENSIONS = ['txt', 'md', 'docx', 'xlsx', 'csv', 'odt'];
+
+ /**
+ * Admin setting key for the allow-list.
+ *
+ * @var string
+ */
+ private const SETTING_KEY = 'file_create_extensions';
+
+ /**
+ * Constructor.
+ *
+ * @param IRootFolder $rootFolder Nextcloud root folder.
+ * @param IURLGenerator $urlGenerator URL generator.
+ * @param AdminSettingMapper $settingMapper Admin setting mapper.
+ */
+ public function __construct(
+ private readonly IRootFolder $rootFolder,
+ private readonly IURLGenerator $urlGenerator,
+ private readonly AdminSettingMapper $settingMapper,
+ ) {
+ }//end __construct()
+
+ /**
+ * Create (or overwrite) a file in the user's Files space.
+ *
+ * Validates filename and directory defensively, checks the extension
+ * against the admin allow-list, resolves the user folder, creates any
+ * missing subdirectory, and either creates or overwrites the file.
+ *
+ * @param string $userId Nextcloud user ID.
+ * @param string $filename Desired filename (basename only, no path).
+ * @param string $dir Target directory inside the user folder.
+ * @param string $content File content (may be empty for placeholder).
+ *
+ * @return array{fileId:int,url:string} Success payload with `fileId`
+ * and a Files-app open URL.
+ *
+ * @throws InvalidFilenameException When `$filename` is empty, too long,
+ * or contains disallowed characters.
+ * @throws InvalidDirectoryException When `$dir` contains traversal
+ * sequences or null bytes.
+ * @throws ForbiddenExtensionException When the file extension is not in
+ * the allow-list.
+ */
+ public function createFile(
+ string $userId,
+ string $filename,
+ string $dir,
+ string $content
+ ): array {
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $this->validateFilename($filename);
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $this->validateDirectory($dir);
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $this->validateExtension($filename);
+
+ $userFolder = $this->rootFolder->getUserFolder(userId: $userId);
+ $targetFolder = $userFolder;
+
+ // Create subdirectory if it is not root.
+ $normalizedDir = trim(string: $dir, characters: '/');
+ if ($normalizedDir !== '') {
+ if ($userFolder->nodeExists(path: $normalizedDir) === false) {
+ $userFolder->newFolder(path: $normalizedDir);
+ }
+
+ $targetFolder = $userFolder->get(path: $normalizedDir);
+ }
+
+ // Overwrite if the file already exists; create otherwise.
+ if ($targetFolder->nodeExists(path: $filename) === true) {
+ // @phpstan-ignore-next-line
+ $file = $targetFolder->get(path: $filename);
+ $file->putContent(data: $content);
+ } else {
+ $file = $targetFolder->newFile(path: $filename);
+ $file->putContent(data: $content);
+ }
+
+ $fileId = $file->getId();
+
+ $url = $this->urlGenerator->linkToRouteAbsolute(
+ routeName: 'files.view.index',
+ arguments: ['openfile' => $fileId]
+ );
+
+ return [
+ 'fileId' => $fileId,
+ 'url' => $url,
+ ];
+ }//end createFile()
+
+ /**
+ * Validate the filename against strict rules (REQ-LBN-004).
+ *
+ * Rejects:
+ * - empty string
+ * - length > 255 characters
+ * - path traversal (`..`)
+ * - forward slash `/`
+ * - backslash `\`
+ * - null byte
+ * - any character outside `^[a-zA-Z0-9_\-. ]+$`
+ *
+ * @param string $filename The filename to validate.
+ *
+ * @return void
+ *
+ * @throws InvalidFilenameException When any rule is violated.
+ */
+ private function validateFilename(string $filename): void
+ {
+ if ($filename === '') {
+ throw new InvalidFilenameException(message: 'Invalid filename');
+ }
+
+ if (strlen(string: $filename) > 255) {
+ throw new InvalidFilenameException(message: 'Invalid filename');
+ }
+
+ if (str_contains(haystack: $filename, needle: "\0") === true) {
+ throw new InvalidFilenameException(message: 'Invalid filename');
+ }
+
+ if (str_contains(haystack: $filename, needle: '..') === true) {
+ throw new InvalidFilenameException(message: 'Invalid filename');
+ }
+
+ if (str_contains(haystack: $filename, needle: '/') === true) {
+ throw new InvalidFilenameException(message: 'Invalid filename');
+ }
+
+ if (str_contains(haystack: $filename, needle: '\\') === true) {
+ throw new InvalidFilenameException(message: 'Invalid filename');
+ }
+
+ if (preg_match(pattern: '/^[a-zA-Z0-9_\-. ]+$/', subject: $filename) !== 1) {
+ throw new InvalidFilenameException(message: 'Invalid filename');
+ }
+ }//end validateFilename()
+
+ /**
+ * Validate the target directory for path traversal (REQ-LBN-004).
+ *
+ * Rejects any dir containing `..` or a null byte.
+ *
+ * @param string $dir The directory path to validate.
+ *
+ * @return void
+ *
+ * @throws InvalidDirectoryException When the dir is unsafe.
+ */
+ private function validateDirectory(string $dir): void
+ {
+ if (str_contains(haystack: $dir, needle: "\0") === true) {
+ throw new InvalidDirectoryException(message: 'Invalid directory');
+ }
+
+ if (str_contains(haystack: $dir, needle: '..') === true) {
+ throw new InvalidDirectoryException(message: 'Invalid directory');
+ }
+ }//end validateDirectory()
+
+ /**
+ * Validate the file extension against the admin-configured allow-list.
+ *
+ * Reads the `file_create_extensions` admin setting (JSON array of
+ * lowercase extension strings). Falls back to DEFAULT_ALLOWED_EXTENSIONS
+ * when the setting is absent or unparseable.
+ *
+ * @param string $filename The filename whose extension to check.
+ *
+ * @return void
+ *
+ * @throws ForbiddenExtensionException When the extension is not allowed.
+ */
+ private function validateExtension(string $filename): void
+ {
+ // phpcs:ignore CustomSniffs.Functions.NamedParameters.RequireNamedParameters
+ $ext = strtolower(string: pathinfo($filename, PATHINFO_EXTENSION));
+
+ $allowed = $this->getAllowedExtensions();
+
+ if (in_array(needle: $ext, haystack: $allowed, strict: true) === false) {
+ throw new ForbiddenExtensionException(message: 'File type not allowed');
+ }
+ }//end validateExtension()
+
+ /**
+ * Return the admin-configured extension allow-list.
+ *
+ * Falls back to DEFAULT_ALLOWED_EXTENSIONS when the setting row is
+ * absent, null, not a JSON array, or contains non-string elements.
+ *
+ * @return string[] Lowercase extension strings (without leading dot).
+ */
+ private function getAllowedExtensions(): array
+ {
+ $raw = $this->settingMapper->getValue(
+ key: self::SETTING_KEY,
+ default: null
+ );
+
+ if (is_array($raw) === false) {
+ return self::DEFAULT_ALLOWED_EXTENSIONS;
+ }
+
+ $clean = [];
+ foreach ($raw as $item) {
+ if (is_string($item) === true && $item !== '') {
+ $clean[] = strtolower(string: $item);
+ }
+ }
+
+ if (empty($clean) === true) {
+ return self::DEFAULT_ALLOWED_EXTENSIONS;
+ }
+
+ return $clean;
+ }//end getAllowedExtensions()
+}//end class
diff --git a/lib/Service/ImageMimeValidator.php b/lib/Service/ImageMimeValidator.php
new file mode 100644
index 00000000..d694c0d9
--- /dev/null
+++ b/lib/Service/ImageMimeValidator.php
@@ -0,0 +1,114 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Service;
+
+use OCA\MyDash\Exception\CorruptImageException;
+use OCA\MyDash\Exception\MimeMismatchException;
+
+/**
+ * Validates that declared raster image type matches the detected MIME.
+ */
+class ImageMimeValidator
+{
+ /**
+ * Map normalised declared types to expected detected MIMEs.
+ *
+ * `getimagesizefromstring` returns these mime strings for valid
+ * images of each type. `jpeg` and `jpg` both produce `image/jpeg`.
+ *
+ * @var array
+ */
+ private const RASTER_MIME_MAP = [
+ 'jpeg' => 'image/jpeg',
+ 'jpg' => 'image/jpeg',
+ 'png' => 'image/png',
+ 'gif' => 'image/gif',
+ 'webp' => 'image/webp',
+ ];
+
+ /**
+ * Validate that the declared raster type matches the detected MIME.
+ *
+ * SVG is skipped (delegated to SvgSanitiser in a sibling change).
+ * Caller MUST enforce the size cap before invoking this method to
+ * avoid loading oversize blobs into the image library.
+ *
+ * @param string $declaredType Normalised, lowercase declared type
+ * (e.g. 'png', 'jpg', 'svg').
+ * @param string $bytes Decoded image bytes.
+ *
+ * @return void
+ *
+ * @throws CorruptImageException When the bytes cannot be decoded.
+ * @throws MimeMismatchException When the detected MIME differs from
+ * the declared type.
+ */
+ public function validate(string $declaredType, string $bytes): void
+ {
+ // SVG validation is the sanitiser's job, not this validator's.
+ if ($declaredType === 'svg') {
+ return;
+ }
+
+ if (isset(self::RASTER_MIME_MAP[$declaredType]) === false) {
+ // Should never happen — caller already vetted the declared
+ // type — but be defensive against future callers.
+ throw new MimeMismatchException();
+ }
+
+ $expectedMime = self::RASTER_MIME_MAP[$declaredType];
+
+ // `getimagesizefromstring` returns false for non-images. We
+ // suppress the warning via a local error handler instead of
+ // the `@` operator (banned by phpmd's ErrorControlOperator
+ // rule). The handler is restored before any branch returns.
+ $previous = set_error_handler(
+ callback: static function (): bool {
+ return true;
+ }
+ );
+
+ try {
+ $info = getimagesizefromstring(string: $bytes);
+ } finally {
+ restore_error_handler();
+ unset($previous);
+ }
+
+ if ($info === false) {
+ throw new CorruptImageException();
+ }
+
+ $detectedMime = $info['mime'];
+ if ($detectedMime !== $expectedMime) {
+ throw new MimeMismatchException();
+ }
+ }//end validate()
+}//end class
diff --git a/lib/Service/InitialStateBuilder.php b/lib/Service/InitialStateBuilder.php
new file mode 100644
index 00000000..ac24dafb
--- /dev/null
+++ b/lib/Service/InitialStateBuilder.php
@@ -0,0 +1,307 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Service;
+
+use OCA\MyDash\Exception\MissingInitialStateException;
+use OCP\AppFramework\Services\IInitialState;
+
+/**
+ * Centralised typed builder for MyDash initial-state payloads.
+ *
+ * See REQ-INIT-001..REQ-INIT-005 in the `initial-state-contract` spec.
+ */
+class InitialStateBuilder
+{
+ /**
+ * Schema version stamped on every payload under key `_schemaVersion`.
+ *
+ * Bumping this value is a deliberate spec change per REQ-INIT-002 and
+ * MUST be coordinated with the JS reader's compiled-in constant.
+ *
+ * @var int
+ */
+ public const INITIAL_STATE_SCHEMA_VERSION = 1;
+
+ /**
+ * Reserved key used to stamp the schema version on every payload.
+ *
+ * @var string
+ */
+ public const SCHEMA_VERSION_KEY = '_schemaVersion';
+
+ /**
+ * Required key sets per page. Keep in sync with REQ-INIT-002 Data Model.
+ *
+ * @var array>
+ */
+ private const REQUIRED_KEYS = [
+ 'workspace' => [
+ 'widgets',
+ 'layout',
+ 'primaryGroup',
+ 'primaryGroupName',
+ 'isAdmin',
+ 'activeDashboardId',
+ 'dashboardSource',
+ 'groupDashboards',
+ 'userDashboards',
+ 'allowUserDashboards',
+ ],
+ 'admin' => [
+ 'allGroups',
+ 'configuredGroups',
+ 'widgets',
+ 'allowUserDashboards',
+ ],
+ ];
+
+ /**
+ * Accumulated key/value pairs to push on apply().
+ *
+ * @var array
+ */
+ private array $values = [];
+
+ /**
+ * Construct a new InitialStateBuilder.
+ *
+ * @param IInitialState $initialState The Nextcloud initial-state service.
+ * @param Page $page The page this builder targets.
+ */
+ public function __construct(
+ private readonly IInitialState $initialState,
+ private readonly Page $page,
+ ) {
+ }//end __construct()
+
+ /**
+ * Set the dashboard widgets descriptor list (workspace + admin).
+ *
+ * @param array $widgets Array of {id,title,iconClass,iconUrl,url}.
+ *
+ * @return self
+ */
+ public function setWidgets(array $widgets): self
+ {
+ $this->values['widgets'] = $widgets;
+ return $this;
+ }//end setWidgets()
+
+ /**
+ * Set the workspace layout grid (workspace).
+ *
+ * @param array $layout Array of WorkspaceWidget descriptors.
+ *
+ * @return self
+ */
+ public function setLayout(array $layout): self
+ {
+ $this->values['layout'] = $layout;
+ return $this;
+ }//end setLayout()
+
+ /**
+ * Set the primary group identifier (workspace).
+ *
+ * @param string $primaryGroup The group identifier.
+ *
+ * @return self
+ */
+ public function setPrimaryGroup(string $primaryGroup): self
+ {
+ $this->values['primaryGroup'] = $primaryGroup;
+ return $this;
+ }//end setPrimaryGroup()
+
+ /**
+ * Set the primary group display name (workspace).
+ *
+ * @param string $primaryGroupName The display name.
+ *
+ * @return self
+ */
+ public function setPrimaryGroupName(string $primaryGroupName): self
+ {
+ $this->values['primaryGroupName'] = $primaryGroupName;
+ return $this;
+ }//end setPrimaryGroupName()
+
+ /**
+ * Set whether the current user is an admin (workspace).
+ *
+ * @param bool $isAdmin True if admin.
+ *
+ * @return self
+ */
+ public function setIsAdmin(bool $isAdmin): self
+ {
+ $this->values['isAdmin'] = $isAdmin;
+ return $this;
+ }//end setIsAdmin()
+
+ /**
+ * Set the active dashboard identifier (workspace).
+ *
+ * @param string $activeDashboardId The dashboard id.
+ *
+ * @return self
+ */
+ public function setActiveDashboardId(string $activeDashboardId): self
+ {
+ $this->values['activeDashboardId'] = $activeDashboardId;
+ return $this;
+ }//end setActiveDashboardId()
+
+ /**
+ * Set the source of the active dashboard (workspace).
+ *
+ * @param string $dashboardSource One of 'user'|'group'|'default'.
+ *
+ * @return self
+ */
+ public function setDashboardSource(string $dashboardSource): self
+ {
+ $this->values['dashboardSource'] = $dashboardSource;
+ return $this;
+ }//end setDashboardSource()
+
+ /**
+ * Set the available group dashboards (workspace).
+ *
+ * @param array $groupDashboards Array of {id,name,icon,source?}.
+ *
+ * @return self
+ */
+ public function setGroupDashboards(array $groupDashboards): self
+ {
+ $this->values['groupDashboards'] = $groupDashboards;
+ return $this;
+ }//end setGroupDashboards()
+
+ /**
+ * Set the available user dashboards (workspace).
+ *
+ * @param array $userDashboards Array of {id,name,icon}.
+ *
+ * @return self
+ */
+ public function setUserDashboards(array $userDashboards): self
+ {
+ $this->values['userDashboards'] = $userDashboards;
+ return $this;
+ }//end setUserDashboards()
+
+ /**
+ * Set whether user-owned dashboards are permitted (workspace + admin).
+ *
+ * @param bool $allowUserDashboards True if allowed.
+ *
+ * @return self
+ */
+ public function setAllowUserDashboards(bool $allowUserDashboards): self
+ {
+ $this->values['allowUserDashboards'] = $allowUserDashboards;
+ return $this;
+ }//end setAllowUserDashboards()
+
+ /**
+ * Set the list of all Nextcloud groups (admin).
+ *
+ * @param array $allGroups Array of {id,displayName}.
+ *
+ * @return self
+ */
+ public function setAllGroups(array $allGroups): self
+ {
+ $this->values['allGroups'] = $allGroups;
+ return $this;
+ }//end setAllGroups()
+
+ /**
+ * Set the list of MyDash-configured group ids (admin).
+ *
+ * @param array $configuredGroups Array of group id strings.
+ *
+ * @return self
+ */
+ public function setConfiguredGroups(array $configuredGroups): self
+ {
+ $this->values['configuredGroups'] = $configuredGroups;
+ return $this;
+ }//end setConfiguredGroups()
+
+ /**
+ * Validate the required key set for the current page and push every
+ * accumulated value (plus `_schemaVersion`) to the IInitialState service.
+ *
+ * @return void
+ *
+ * @throws MissingInitialStateException When a required key was not set.
+ */
+ public function apply(): void
+ {
+ $required = self::REQUIRED_KEYS[$this->page->value];
+
+ foreach ($required as $key) {
+ if (array_key_exists($key, $this->values) === false) {
+ throw new MissingInitialStateException(
+ page: $this->page->value,
+ key: $key
+ );
+ }
+ }
+
+ foreach ($this->values as $key => $value) {
+ $this->initialState->provideInitialState(key: $key, data: $value);
+ }
+
+ $this->initialState->provideInitialState(
+ key: self::SCHEMA_VERSION_KEY,
+ data: self::INITIAL_STATE_SCHEMA_VERSION
+ );
+ }//end apply()
+}//end class
diff --git a/lib/Service/MetricsCollector.php b/lib/Service/MetricsCollector.php
index 68d060cb..25ed1633 100644
--- a/lib/Service/MetricsCollector.php
+++ b/lib/Service/MetricsCollector.php
@@ -53,9 +53,9 @@ public function collectAll(): array
{
$lines = [];
- $this->addInfoMetric($lines);
- $this->addUpMetric($lines);
- $this->addDashboardMetrics($lines);
+ $this->addInfoMetric(lines: $lines);
+ $this->addUpMetric(lines: $lines);
+ $this->addDashboardMetrics(lines: $lines);
$this->addCountMetric(
lines: $lines,
tableName: 'mydash_widget_placements',
diff --git a/lib/Service/Page.php b/lib/Service/Page.php
new file mode 100644
index 00000000..5bc8f2d7
--- /dev/null
+++ b/lib/Service/Page.php
@@ -0,0 +1,36 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Service;
+
+/**
+ * Page identifier for the initial-state contract.
+ *
+ * See REQ-INIT-002 in the initial-state-contract spec for the per-page
+ * required key set.
+ */
+enum Page: string
+{
+ case WORKSPACE = 'workspace';
+ case ADMIN = 'admin';
+}//end enum
diff --git a/lib/Service/PermissionService.php b/lib/Service/PermissionService.php
index f8ad6d3c..2d6b92d2 100644
--- a/lib/Service/PermissionService.php
+++ b/lib/Service/PermissionService.php
@@ -29,6 +29,7 @@
use OCA\MyDash\Db\AdminSettingMapper;
use OCA\MyDash\Db\AdminSetting;
use OCP\AppFramework\Db\DoesNotExistException;
+use OCP\IGroupManager;
class PermissionService
{
@@ -38,11 +39,16 @@ class PermissionService
* @param DashboardMapper $dashboardMapper Dashboard mapper.
* @param WidgetPlacementMapper $placementMapper Widget placement mapper.
* @param AdminSettingMapper $settingMapper Admin setting mapper.
+ * @param IGroupManager $groupManager Group manager.
+ * @param string|null $currentUserId The current user ID
+ * (null when unauthenticated).
*/
public function __construct(
private readonly DashboardMapper $dashboardMapper,
private readonly WidgetPlacementMapper $placementMapper,
private readonly AdminSettingMapper $settingMapper,
+ private readonly IGroupManager $groupManager,
+ private readonly ?string $currentUserId=null,
) {
}//end __construct()
@@ -270,12 +276,32 @@ public function canHaveMultipleDashboards(string $userId): bool
/**
* Get the effective permission level for a dashboard.
*
+ * Group-shared dashboards (REQ-DASH-011) override the persisted
+ * `permissionLevel` field at resolution time:
+ * - admins always get {@see Dashboard::PERMISSION_FULL}
+ * - non-admin members always get
+ * {@see Dashboard::PERMISSION_VIEW_ONLY}
+ *
+ * The override is applied here (single source of truth) so that
+ * future widgets / tiles consulting `getEffectivePermissionLevel`
+ * stay consistent with the route-level admin guard. The persisted
+ * column is preserved for forward-compat with per-tile editing.
+ *
* @param Dashboard $dashboard The dashboard.
*
* @return string The effective permission level.
*/
public function getEffectivePermissionLevel(Dashboard $dashboard): string
{
+ // Group-shared scope: admin → full, non-admin → view_only.
+ if ($dashboard->getType() === Dashboard::TYPE_GROUP_SHARED) {
+ if ($this->currentUserIsAdmin() === true) {
+ return Dashboard::PERMISSION_FULL;
+ }
+
+ return Dashboard::PERMISSION_VIEW_ONLY;
+ }
+
// If based on a template, use template's permission level.
if ($dashboard->getBasedOnTemplate() !== null) {
try {
@@ -300,6 +326,24 @@ public function getEffectivePermissionLevel(Dashboard $dashboard): string
);
}//end getEffectivePermissionLevel()
+ /**
+ * Test whether the current request actor is a Nextcloud admin.
+ *
+ * Returns false on unauthenticated requests rather than throwing,
+ * so callers (including the group-shared resolver) can safely fall
+ * back to the read-only branch.
+ *
+ * @return bool Whether the actor is an admin.
+ */
+ private function currentUserIsAdmin(): bool
+ {
+ if ($this->currentUserId === null || $this->currentUserId === '') {
+ return false;
+ }
+
+ return $this->groupManager->isAdmin(userId: $this->currentUserId);
+ }//end currentUserIsAdmin()
+
/**
* Verify user owns a dashboard.
*
diff --git a/lib/Service/ResourceServeService.php b/lib/Service/ResourceServeService.php
new file mode 100644
index 00000000..f9b8c4f5
--- /dev/null
+++ b/lib/Service/ResourceServeService.php
@@ -0,0 +1,168 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Service;
+
+use DateTimeImmutable;
+use DateTimeInterface;
+use DateTimeZone;
+use OCP\Files\IAppData;
+use OCP\Files\NotFoundException;
+use OCP\Files\SimpleFS\ISimpleFile;
+use Psr\Log\LoggerInterface;
+use Throwable;
+
+/**
+ * Read-side filesystem + formatting helpers for resource-uploads.
+ */
+class ResourceServeService
+{
+ /**
+ * Map of file extension → Content-Type for the public serve route.
+ *
+ * Anything not in this map falls back to `application/octet-stream`
+ * — see REQ-RES-006 for the canonical mapping.
+ *
+ * @var array
+ */
+ private const CONTENT_TYPE_MAP = [
+ 'jpg' => 'image/jpeg',
+ 'jpeg' => 'image/jpeg',
+ 'png' => 'image/png',
+ 'gif' => 'image/gif',
+ 'svg' => 'image/svg+xml',
+ 'webp' => 'image/webp',
+ ];
+
+ /**
+ * Constructor.
+ *
+ * @param IAppData $appData App-data accessor.
+ * @param LoggerInterface $logger PSR logger.
+ */
+ public function __construct(
+ private readonly IAppData $appData,
+ private readonly LoggerInterface $logger,
+ ) {
+ }//end __construct()
+
+ /**
+ * Resolve a filename to an ISimpleFile, or null on miss.
+ *
+ * @param string $filename The leaf filename.
+ *
+ * @return ISimpleFile|null The file, or null if absent / unreadable.
+ */
+ public function findFile(string $filename): ?ISimpleFile
+ {
+ try {
+ $folder = $this->appData->getFolder(name: ResourceService::FOLDER);
+ return $folder->getFile(name: $filename);
+ } catch (NotFoundException $e) {
+ return null;
+ } catch (Throwable $e) {
+ $this->logger->warning(
+ message: 'Resource serve failed to open file',
+ context: ['exception' => $e->getMessage()]
+ );
+ return null;
+ }
+ }//end findFile()
+
+ /**
+ * Load the resources directory listing as ISimpleFile entries.
+ *
+ * Returns an empty array when the folder does not yet exist —
+ * matching REQ-RES-007's "never a 404" contract.
+ *
+ * @return array The file entries.
+ */
+ public function listFiles(): array
+ {
+ try {
+ $folder = $this->appData->getFolder(name: ResourceService::FOLDER);
+ } catch (NotFoundException $e) {
+ return [];
+ } catch (Throwable $e) {
+ $this->logger->warning(
+ message: 'Resource list failed to open folder',
+ context: ['exception' => $e->getMessage()]
+ );
+ return [];
+ }
+
+ $entries = [];
+ foreach ($folder->getDirectoryListing() as $entry) {
+ if (($entry instanceof ISimpleFile) === true) {
+ $entries[] = $entry;
+ }
+ }
+
+ return $entries;
+ }//end listFiles()
+
+ /**
+ * Pick the Content-Type for a filename via its extension.
+ *
+ * Falls back to `application/octet-stream` for unknown extensions.
+ *
+ * @param string $filename The leaf filename.
+ *
+ * @return string The MIME type to send.
+ */
+ public function contentTypeForFilename(string $filename): string
+ {
+ $position = strrpos(haystack: $filename, needle: '.');
+ if ($position === false) {
+ return 'application/octet-stream';
+ }
+
+ $extension = strtolower(string: substr(string: $filename, offset: ($position + 1)));
+ return (self::CONTENT_TYPE_MAP[$extension] ?? 'application/octet-stream');
+ }//end contentTypeForFilename()
+
+ /**
+ * Format a Unix epoch as an ISO-8601 UTC timestamp.
+ *
+ * @param int $epoch The Unix epoch (e.g. from ISimpleFile::getMTime()).
+ *
+ * @return string The ISO-8601 timestamp.
+ */
+ public function formatTimestamp(int $epoch): string
+ {
+ $dateTime = (new DateTimeImmutable(datetime: '@'.$epoch))
+ ->setTimezone(timezone: new DateTimeZone(timezone: 'UTC'));
+
+ return $dateTime->format(format: DateTimeInterface::ATOM);
+ }//end formatTimestamp()
+}//end class
diff --git a/lib/Service/ResourceService.php b/lib/Service/ResourceService.php
new file mode 100644
index 00000000..4b9f57e4
--- /dev/null
+++ b/lib/Service/ResourceService.php
@@ -0,0 +1,294 @@
+;base64,...` data URL, enforces
+ * a 5 MB hard cap on decoded bytes BEFORE invoking the image library,
+ * cross-checks the declared raster type against the detected MIME,
+ * and persists the bytes via `IAppData::getFolder('resources')` with
+ * a high-entropy `resource_.` filename.
+ *
+ * For SVG uploads the bytes are first passed through `SvgSanitiser`
+ * (REQ-RES-009..013); the sanitised bytes are what get persisted, and
+ * the 5 MB size cap is measured AFTER sanitisation. A null sanitiser
+ * return is surfaced as HTTP 400 `invalid_svg`.
+ *
+ * @category Service
+ * @package OCA\MyDash\Service
+ * @author Conduction b.v.
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Service;
+
+use OCA\MyDash\AppInfo\Application;
+use OCA\MyDash\Exception\FileTooLargeException;
+use OCA\MyDash\Exception\InvalidDataUrlException;
+use OCA\MyDash\Exception\InvalidImageFormatException;
+use OCA\MyDash\Exception\InvalidSvgException;
+use OCA\MyDash\Exception\StorageFailureException;
+use OCP\Files\IAppData;
+use OCP\Files\NotFoundException;
+use Throwable;
+
+/**
+ * Admin-only base64 upload pipeline for branding assets.
+ */
+class ResourceService
+{
+ /**
+ * Maximum decoded payload size (5 MB).
+ *
+ * @var int
+ */
+ public const MAX_BYTES = (5 * 1024 * 1024);
+
+ /**
+ * Name of the IAppData subfolder where resources are stored.
+ *
+ * @var string
+ */
+ public const FOLDER = 'resources';
+
+ /**
+ * Allowed declared image types (lowercase, no dots).
+ *
+ * @var array
+ */
+ private const ALLOWED_TYPES = [
+ 'jpeg',
+ 'jpg',
+ 'png',
+ 'gif',
+ 'svg',
+ 'webp',
+ ];
+
+ /**
+ * Constructor.
+ *
+ * @param IAppData $appData Nextcloud app-data
+ * interface for this app.
+ * @param ImageMimeValidator $mimeValidator Raster MIME cross-checker.
+ * @param SvgSanitiser $svgSanitiser DOM whitelist SVG sanitiser.
+ */
+ public function __construct(
+ private readonly IAppData $appData,
+ private readonly ImageMimeValidator $mimeValidator,
+ private readonly SvgSanitiser $svgSanitiser,
+ ) {
+ }//end __construct()
+
+ /**
+ * Upload a base64 data URL and return the persisted resource info.
+ *
+ * Parses the data URL, enforces the 5 MB cap on decoded bytes
+ * BEFORE invoking the image library, validates the declared type,
+ * cross-checks the raster MIME, and persists to app data.
+ *
+ * @param string $base64DataUrl A `data:image/;base64,<...>`
+ * string.
+ *
+ * @return array{url: string, name: string, size: int} The created
+ * resource.
+ *
+ * @throws InvalidDataUrlException When the prefix is missing
+ * or unparseable.
+ * @throws InvalidImageFormatException When the declared type is
+ * not in the allowed list.
+ * @throws InvalidSvgException When an SVG payload fails
+ * to parse or is fully stripped.
+ * @throws FileTooLargeException When decoded bytes (or the
+ * SANITISED bytes for SVG)
+ * exceed 5 MB.
+ * @throws StorageFailureException When writing to IAppData
+ * fails.
+ */
+ public function upload(string $base64DataUrl): array
+ {
+ $parsed = $this->parseDataUrl(input: $base64DataUrl);
+ $declaredType = $parsed['type'];
+ $bytes = $parsed['bytes'];
+
+ // SVG branch: sanitise BEFORE the size check so the 5 MB cap
+ // is measured against the persisted (sanitised) byte count
+ // (REQ-RES-009). Sanitiser returns null on parse failure or
+ // an empty document — surface as HTTP 400 invalid_svg.
+ if ($declaredType === 'svg') {
+ $sanitised = $this->svgSanitiser->sanitize(bytes: $bytes);
+ if ($sanitised === null) {
+ throw new InvalidSvgException();
+ }
+
+ $bytes = $sanitised;
+ }
+
+ // Enforce the 5 MB cap BEFORE invoking the image library.
+ if (strlen(string: $bytes) > self::MAX_BYTES) {
+ throw new FileTooLargeException();
+ }
+
+ // Cross-check raster MIME (SVG short-circuits inside validate).
+ $this->mimeValidator->validate(
+ declaredType: $declaredType,
+ bytes: $bytes
+ );
+
+ $extension = $this->normaliseExtension(declaredType: $declaredType);
+ $filename = ('resource_'.uniqid(prefix: '', more_entropy: true).'.'.$extension);
+
+ $this->persist(filename: $filename, bytes: $bytes);
+
+ // Build the public URL directly — the serving endpoint is
+ // delivered by the sibling `resource-serving` change. The spec
+ // mandates the relative path form `/apps/mydash/resource/`,
+ // so we don't pass it through linkToRoute or getAbsoluteURL.
+ $url = ('/apps/'.Application::APP_ID.'/resource/'.$filename);
+
+ return [
+ 'url' => $url,
+ 'name' => $filename,
+ 'size' => strlen(string: $bytes),
+ ];
+ }//end upload()
+
+ /**
+ * Parse a `data:image/;base64,` string.
+ *
+ * The declared type is normalised to lowercase. Anything outside
+ * the allowed list is rejected.
+ *
+ * @param string $input The raw input string.
+ *
+ * @return array{type: string, bytes: string} The normalised
+ * declared type and the
+ * decoded bytes.
+ *
+ * @throws InvalidDataUrlException When the prefix is missing.
+ * @throws InvalidImageFormatException When the declared type is
+ * not allowed.
+ */
+ private function parseDataUrl(string $input): array
+ {
+ $matches = [];
+ // Match "data:image/;base64," — type is alpha
+ // plus optional "+xml" suffix (handles `image/svg+xml`).
+ if (preg_match(
+ pattern: '#^data:image/([a-zA-Z0-9.+-]+);base64,(.+)$#s',
+ subject: $input,
+ matches: $matches
+ ) !== 1
+ ) {
+ throw new InvalidDataUrlException();
+ }
+
+ $declaredRaw = strtolower(string: $matches[1]);
+ $payload = $matches[2];
+
+ $declaredType = $this->normaliseDeclaredType(raw: $declaredRaw);
+ if (in_array(
+ needle: $declaredType,
+ haystack: self::ALLOWED_TYPES,
+ strict: true
+ ) === false
+ ) {
+ throw new InvalidImageFormatException();
+ }
+
+ $bytes = base64_decode(string: $payload, strict: true);
+ if ($bytes === false || $bytes === '') {
+ throw new InvalidDataUrlException(
+ message: 'Body must contain valid base64 data'
+ );
+ }
+
+ return [
+ 'type' => $declaredType,
+ 'bytes' => $bytes,
+ ];
+ }//end parseDataUrl()
+
+ /**
+ * Normalise a raw declared type string from the data URL prefix.
+ *
+ * `image/svg+xml` → `svg`; otherwise the lowercased subtype is
+ * returned untouched (callers vet against ALLOWED_TYPES).
+ *
+ * @param string $raw The raw lowercased subtype.
+ *
+ * @return string The normalised declared type.
+ */
+ private function normaliseDeclaredType(string $raw): string
+ {
+ if ($raw === 'svg+xml') {
+ return 'svg';
+ }
+
+ return $raw;
+ }//end normaliseDeclaredType()
+
+ /**
+ * Map a normalised declared type to its file extension.
+ *
+ * Currently the extension equals the declared type for every
+ * allowed value.
+ *
+ * @param string $declaredType The normalised lowercase type.
+ *
+ * @return string The file extension (without the dot).
+ */
+ private function normaliseExtension(string $declaredType): string
+ {
+ return $declaredType;
+ }//end normaliseExtension()
+
+ /**
+ * Persist validated bytes via IAppData.
+ *
+ * Auto-creates the `resources/` folder on first use. Wraps any
+ * IAppData failure into a typed StorageFailureException so that
+ * raw underlying messages never leak to clients.
+ *
+ * @param string $filename The target filename inside the folder.
+ * @param string $bytes The validated payload bytes.
+ *
+ * @return void
+ *
+ * @throws StorageFailureException When the underlying storage
+ * layer rejects the write.
+ */
+ private function persist(string $filename, string $bytes): void
+ {
+ try {
+ $folder = $this->getOrCreateFolder();
+ $folder->newFile(name: $filename, content: $bytes);
+ } catch (Throwable $e) {
+ throw new StorageFailureException();
+ }
+ }//end persist()
+
+ /**
+ * Get the resources folder, creating it if it doesn't exist.
+ *
+ * @return \OCP\Files\SimpleFS\ISimpleFolder The resources folder.
+ */
+ private function getOrCreateFolder(): \OCP\Files\SimpleFS\ISimpleFolder
+ {
+ try {
+ return $this->appData->getFolder(name: self::FOLDER);
+ } catch (NotFoundException $e) {
+ return $this->appData->newFolder(name: self::FOLDER);
+ }
+ }//end getOrCreateFolder()
+}//end class
diff --git a/lib/Service/SvgSanitiser.php b/lib/Service/SvgSanitiser.php
new file mode 100644
index 00000000..e9a960ae
--- /dev/null
+++ b/lib/Service/SvgSanitiser.php
@@ -0,0 +1,351 @@
+
+ * @copyright 2024 Conduction b.v.
+ * @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+ * @version GIT:auto
+ * @link https://conduction.nl
+ *
+ * SPDX-FileCopyrightText: 2024 MyDash Contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+declare(strict_types=1);
+
+namespace OCA\MyDash\Service;
+
+use DOMAttr;
+use DOMDocument;
+use DOMElement;
+use DOMNode;
+
+/**
+ * Whitelist-based SVG sanitiser. No Nextcloud dependencies — pure PHP.
+ */
+class SvgSanitiser
+{
+
+ /**
+ * Allowed element local-names (lowercase). Anything not in this
+ * list is removed from the tree along with its children. See
+ * REQ-RES-010 in the resource-uploads capability.
+ *
+ * @var array
+ */
+ private const ALLOWED_ELEMENTS = [
+ 'svg',
+ 'g',
+ 'path',
+ 'rect',
+ 'circle',
+ 'ellipse',
+ 'line',
+ 'polyline',
+ 'polygon',
+ 'text',
+ 'tspan',
+ 'defs',
+ 'clippath',
+ 'use',
+ 'image',
+ 'style',
+ 'lineargradient',
+ 'radialgradient',
+ 'stop',
+ 'mask',
+ 'pattern',
+ 'symbol',
+ 'title',
+ 'desc',
+ ];
+
+ /**
+ * Allowed attribute names (lowercase). Anything not in this list
+ * is removed from each element regardless of element name. See
+ * REQ-RES-011 in the resource-uploads capability.
+ *
+ * @var array
+ */
+ private const ALLOWED_ATTRIBUTES = [
+ 'id',
+ 'class',
+ 'style',
+ 'd',
+ 'x',
+ 'y',
+ 'x1',
+ 'y1',
+ 'x2',
+ 'y2',
+ 'cx',
+ 'cy',
+ 'r',
+ 'rx',
+ 'ry',
+ 'width',
+ 'height',
+ 'viewbox',
+ 'fill',
+ 'stroke',
+ 'stroke-width',
+ 'stroke-linecap',
+ 'stroke-linejoin',
+ 'stroke-dasharray',
+ 'stroke-dashoffset',
+ 'stroke-opacity',
+ 'fill-opacity',
+ 'opacity',
+ 'transform',
+ 'points',
+ 'font-size',
+ 'font-family',
+ 'font-weight',
+ 'text-anchor',
+ 'dominant-baseline',
+ 'dx',
+ 'dy',
+ 'clip-path',
+ 'mask',
+ 'filter',
+ 'gradientunits',
+ 'gradienttransform',
+ 'offset',
+ 'stop-color',
+ 'stop-opacity',
+ 'patternunits',
+ 'preserveaspectratio',
+ 'xmlns',
+ 'xmlns:xlink',
+ 'version',
+ 'href',
+ 'xlink:href',
+ ];
+
+ /**
+ * Sanitise SVG bytes; return the sanitised serialisation or `null`
+ * when the input is unparseable / fully stripped to an empty tree.
+ *
+ * Parse flags `LIBXML_NONET | LIBXML_NOENT` ensure the libxml
+ * parser cannot fetch external DTDs / entities (XXE) and that
+ * entity expansion is bounded by libxml's internal limits
+ * (defends against billion-laughs).
+ *
+ * @param string $bytes The raw uploaded SVG bytes.
+ *
+ * @return string|null The sanitised SVG, or null when unparseable
+ * or sanitised to an empty result.
+ */
+ public function sanitize(string $bytes): ?string
+ {
+ if ($bytes === '') {
+ return null;
+ }
+
+ $previousErrors = libxml_use_internal_errors(use_errors: true);
+
+ $document = new DOMDocument();
+ $document->preserveWhiteSpace = false;
+ $document->formatOutput = false;
+
+ $loaded = $document->loadXML(
+ source: $bytes,
+ options: (LIBXML_NONET | LIBXML_NOENT)
+ );
+
+ libxml_clear_errors();
+ libxml_use_internal_errors(use_errors: $previousErrors);
+
+ if ($loaded === false) {
+ return null;
+ }
+
+ $root = $document->documentElement;
+ if ($root === null) {
+ return null;
+ }
+
+ // Validate the root element itself — reject if it is not in
+ // the whitelist (the recursive walker only inspects children).
+ if (in_array(
+ needle: strtolower(string: $root->localName),
+ haystack: self::ALLOWED_ELEMENTS,
+ strict: true
+ ) === false
+ ) {
+ return null;
+ }
+
+ $this->cleanElement(element: $root);
+ $this->walkChildren(node: $root);
+
+ $serialised = $document->saveXML($root);
+ if ($serialised === false || $serialised === '') {
+ return null;
+ }
+
+ return $serialised;
+ }//end sanitize()
+
+ /**
+ * Recursively walk children of $node, removing disallowed elements
+ * and cleaning the attributes of allowed ones. Snapshots the child
+ * list before mutation so removals during iteration are safe.
+ *
+ * @param DOMNode $node The parent node whose children to walk.
+ *
+ * @return void
+ */
+ private function walkChildren(DOMNode $node): void
+ {
+ $children = [];
+ foreach ($node->childNodes as $child) {
+ $children[] = $child;
+ }
+
+ foreach ($children as $child) {
+ if ($child instanceof DOMElement === false) {
+ continue;
+ }
+
+ $localName = strtolower(string: $child->localName);
+ if (in_array(
+ needle: $localName,
+ haystack: self::ALLOWED_ELEMENTS,
+ strict: true
+ ) === false
+ ) {
+ $node->removeChild(child: $child);
+ continue;
+ }
+
+ $this->cleanElement(element: $child);
+ $this->walkChildren(node: $child);
+ }
+ }//end walkChildren()
+
+ /**
+ * Strip every disallowed attribute from $element, plus any `on*`
+ * attribute (defence in depth) and any `href` / `xlink:href` /
+ * `style` whose value is on the URL or CSS denylist.
+ *
+ * @param DOMElement $element The element whose attributes to clean.
+ *
+ * @return void
+ */
+ private function cleanElement(DOMElement $element): void
+ {
+ if ($element->hasAttributes() === false) {
+ return;
+ }
+
+ $attributes = [];
+ foreach ($element->attributes as $attribute) {
+ if ($attribute instanceof DOMAttr) {
+ $attributes[] = $attribute;
+ }
+ }
+
+ foreach ($attributes as $attribute) {
+ $name = $attribute->nodeName;
+ $lowerName = strtolower(string: $name);
+
+ // Defence in depth — strip every `on*` attribute regardless
+ // of whitelist (REQ-RES-011).
+ if (str_starts_with(haystack: $lowerName, needle: 'on') === true) {
+ $element->removeAttributeNode(attr: $attribute);
+ continue;
+ }
+
+ if (in_array(
+ needle: $lowerName,
+ haystack: self::ALLOWED_ATTRIBUTES,
+ strict: true
+ ) === false
+ ) {
+ $element->removeAttributeNode(attr: $attribute);
+ continue;
+ }
+
+ if ($lowerName === 'href' || $lowerName === 'xlink:href') {
+ if ($this->isDangerousUrl(value: $attribute->value) === true) {
+ $element->removeAttributeNode(attr: $attribute);
+ }
+
+ continue;
+ }
+
+ if ($lowerName === 'style') {
+ if ($this->isDangerousStyle(value: $attribute->value) === true) {
+ $element->removeAttributeNode(attr: $attribute);
+ }
+
+ continue;
+ }
+ }//end foreach
+ }//end cleanElement()
+
+ /**
+ * Whether the supplied URL value is on the denylist. Trims +
+ * lowercases before comparing; matches `javascript:` and `data:`
+ * prefixes (REQ-RES-012).
+ *
+ * @param string $value The raw attribute value.
+ *
+ * @return boolean True when the value should be rejected.
+ */
+ private function isDangerousUrl(string $value): bool
+ {
+ $normalised = strtolower(string: trim(string: $value));
+ if (str_starts_with(haystack: $normalised, needle: 'javascript:') === true) {
+ return true;
+ }
+
+ if (str_starts_with(haystack: $normalised, needle: 'data:') === true) {
+ return true;
+ }
+
+ return false;
+ }//end isDangerousUrl()
+
+ /**
+ * Whether the supplied style value contains a forbidden CSS
+ * construct: `expression(`, `javascript:`, or `url(data:`. Match
+ * is case-insensitive with optional whitespace per REQ-RES-012.
+ *
+ * @param string $value The raw style attribute value.
+ *
+ * @return boolean True when the style attribute should be removed.
+ */
+ private function isDangerousStyle(string $value): bool
+ {
+ $pattern = '/expression\s*\(|javascript\s*:|url\s*\(\s*["\']?\s*data\s*:/i';
+ return (preg_match(pattern: $pattern, subject: $value) === 1);
+ }//end isDangerousStyle()
+}//end class
diff --git a/lib/Service/UserAttributeResolver.php b/lib/Service/UserAttributeResolver.php
index c8918e95..e0324c14 100644
--- a/lib/Service/UserAttributeResolver.php
+++ b/lib/Service/UserAttributeResolver.php
@@ -87,11 +87,11 @@ public function evaluateOperator(
),
'starts_with' => str_starts_with(
haystack: $userValue,
- prefix: $value ?? ''
+ needle: $value ?? ''
),
'ends_with' => str_ends_with(
haystack: $userValue,
- suffix: $value ?? ''
+ needle: $value ?? ''
),
default => false,
};
diff --git a/lib/Settings/MyDashAdmin.php b/lib/Settings/MyDashAdmin.php
index 29de9efa..2ea0f8d5 100644
--- a/lib/Settings/MyDashAdmin.php
+++ b/lib/Settings/MyDashAdmin.php
@@ -3,7 +3,11 @@
/**
* MyDashAdmin
*
- * Admin settings page for MyDash.
+ * Admin settings page for MyDash. The admin initial-state payload is built
+ * via {@see \OCA\MyDash\Service\InitialStateBuilder} per REQ-INIT-001 of the
+ * `initial-state-contract` spec — direct calls to
+ * IInitialState::provideInitialState are forbidden and enforced by a grep
+ * lint test.
*
* @category Settings
* @package OCA\MyDash\Settings
@@ -22,15 +26,40 @@
namespace OCA\MyDash\Settings;
use OCA\MyDash\AppInfo\Application;
+use OCA\MyDash\Service\AdminSettingsService;
+use OCA\MyDash\Service\InitialStateBuilder;
+use OCA\MyDash\Service\Page;
use OCP\AppFramework\Http\TemplateResponse;
+use OCP\AppFramework\Services\IInitialState;
+use OCP\Dashboard\IManager as IDashboardManager;
+use OCP\IGroupManager;
use OCP\Settings\ISettings;
use OCP\Util;
class MyDashAdmin implements ISettings
{
+ /**
+ * Constructor
+ *
+ * @param IInitialState $initialState Nextcloud initial-state service.
+ * @param IDashboardManager $dashboardManager Dashboard widget manager.
+ * @param IGroupManager $groupManager Group lookup.
+ * @param AdminSettingsService $adminSettings MyDash admin settings.
+ */
+ public function __construct(
+ private readonly IInitialState $initialState,
+ private readonly IDashboardManager $dashboardManager,
+ private readonly IGroupManager $groupManager,
+ private readonly AdminSettingsService $adminSettings,
+ ) {
+ }//end __construct()
+
/**
* Get the admin settings form.
*
+ * Builds the admin initial-state payload via InitialStateBuilder
+ * (REQ-INIT-001) before rendering the template.
+ *
* @return TemplateResponse The template response.
*/
public function getForm(): TemplateResponse
@@ -40,6 +69,21 @@ public function getForm(): TemplateResponse
file: 'mydash-admin'
);
+ $settings = $this->adminSettings->getSettings();
+
+ $builder = new InitialStateBuilder(
+ initialState: $this->initialState,
+ page: Page::ADMIN
+ );
+ $builder
+ ->setAllGroups(allGroups: $this->describeGroups())
+ ->setConfiguredGroups(configuredGroups: [])
+ ->setWidgets(widgets: $this->describeWidgets())
+ ->setAllowUserDashboards(
+ allowUserDashboards: (bool) ($settings['allowUserDashboards'] ?? false)
+ )
+ ->apply();
+
return new TemplateResponse(
appName: Application::APP_ID,
templateName: 'settings/admin'
@@ -65,4 +109,43 @@ public function getPriority(): int
{
return 10;
}//end getPriority()
+
+ /**
+ * Build serialisable group descriptors for the admin initial-state.
+ *
+ * @return array
+ */
+ private function describeGroups(): array
+ {
+ $descriptors = [];
+ foreach ($this->groupManager->search(search: '') as $group) {
+ $descriptors[] = [
+ 'id' => $group->getGID(),
+ 'displayName' => $group->getDisplayName(),
+ ];
+ }
+
+ return $descriptors;
+ }//end describeGroups()
+
+ /**
+ * Build serialisable widget descriptors for the admin initial-state.
+ *
+ * @return array
+ */
+ private function describeWidgets(): array
+ {
+ $descriptors = [];
+ foreach ($this->dashboardManager->getWidgets() as $id => $widget) {
+ $descriptors[] = [
+ 'id' => $id,
+ 'title' => $widget->getTitle(),
+ 'iconClass' => $widget->getIconClass(),
+ 'iconUrl' => '',
+ 'url' => $widget->getUrl(),
+ ];
+ }
+
+ return $descriptors;
+ }//end describeWidgets()
}//end class
diff --git a/openspec/changes/active-dashboard-resolution/proposal.md b/openspec/changes/active-dashboard-resolution/proposal.md
new file mode 100644
index 00000000..aa5ffd3f
--- /dev/null
+++ b/openspec/changes/active-dashboard-resolution/proposal.md
@@ -0,0 +1,57 @@
+# Active-dashboard resolution chain
+
+## Why
+
+Define the deterministic precedence MyDash uses to pick *which* dashboard to render for a user when they open the workspace, given the multi-scope model (`user` / `group_shared` / `default`-group). The existing REQ-DASH-009 ("Dashboard Resolution Chain") covers a one-scope personal-only model. The multi-scope model (introduced by `multi-scope-dashboards` and `default-dashboard-flag`) needs a longer chain that prefers the user's saved preference but falls back through group → default → first. Without a canonical resolver each frontend code path could diverge and pick a different "active" dashboard, producing flicker and confusing users.
+
+## What Changes
+
+- Introduce a per-user pref key `active_dashboard_uuid` that holds the UUID of the dashboard the user last opened (or explicitly pinned).
+- Add `DashboardService::resolveActiveDashboard(string $userId, ?string $primaryGroupId): ?array` that walks a 7-step precedence chain and returns `{dashboard, source}` (or `null` for the empty-state case).
+- The 7-step chain is: (1) saved pref UUID if visible to user, (2) `isDefault=1` group-shared in primary group, (3) `isDefault=1` default-group dashboard, (4) first group-shared in primary group, (5) first group-shared in default group, (6) first personal dashboard, (7) `null`.
+- If the saved pref points to a dashboard the user can no longer see (deleted / removed from group), silently clear the pref on read (write-on-read with WARNING log) and continue down the chain. No error surfaced to the user.
+- The resolver returns `source: 'user' | 'group' | 'default'` so the frontend knows which API endpoint to PUT to on save.
+- Add `POST /api/dashboards/active` write endpoint accepting `{uuid: string}` so the frontend can persist the user's choice on switch. Empty string clears the pref. No existence check on write — the resolver's stale-preference path handles invalid UUIDs.
+- `WorkspaceController` calls the resolver and pushes `activeDashboardId` + `dashboardSource` into initial state on first render.
+- Frontend `useDashboardsStore.resolveActive()` mirrors the precedence so client-side `switchDashboard()` picks consistently after store mutations.
+
+## Capabilities
+
+### New Capabilities
+
+(none — the feature folds into the existing `dashboards` capability)
+
+### Modified Capabilities
+
+- `dashboards`: adds REQ-DASH-018 (active-dashboard resolution chain — multi-scope) and REQ-DASH-019 (persist active-dashboard preference). Existing REQ-DASH-001..017 are untouched. REQ-DASH-009 (the one-scope chain) remains in force for callers that ask for a personal-only resolution; the new REQ-DASH-018 is the workspace-level resolver.
+
+## Impact
+
+**Affected code:**
+
+- `lib/Service/DashboardService.php` — add `resolveActiveDashboard(string $userId, ?string $primaryGroupId): ?array`, `setActivePreference(string $userId, string $uuid): void`, and the `ACTIVE_DASHBOARD_UUID_PREF_KEY` constant
+- `lib/Controller/DashboardController.php` — add `setActiveDashboard()` mapped to `POST /api/dashboards/active`
+- `lib/Controller/WorkspaceController.php` — call the resolver and push `activeDashboardId` + `dashboardSource` into initial-state JSON on first render
+- `appinfo/routes.php` — register `POST /api/dashboards/active`
+- `src/stores/dashboards.js` — frontend mirror of the precedence; `resolveActive()` getter; `switchDashboard(uuid)` action POSTs to the new endpoint
+
+**Affected APIs:**
+
+- 1 new route (`POST /api/dashboards/active`)
+- No existing routes changed — `GET /api/dashboards/visible` (REQ-DASH-013) is unchanged and is the source of truth for "what dashboards can the user see"
+
+**Dependencies:**
+
+- `OCP\IConfig::setUserValue` / `getUserValue` — already injected elsewhere, used to persist the per-user preference
+- No new composer or npm dependencies
+
+**Migration:**
+
+- Zero schema impact: the preference lives in `oc_preferences` via `IConfig`. No new table or column.
+- No data backfill required: missing preference is treated as "no saved choice" and the chain falls through to step 2.
+
+## Notes
+
+- Resolver MUST be pure (no side effects on read) except the silent pref-cleanup when the saved id is invalid. That cleanup is observable in REQ-DASH-018 scenario "stale preference is silently cleared".
+- We deliberately chose a single `oc_preferences` key over the alternative of repurposing the per-user `isActive` boolean flag because group-shared dashboards have no per-user row to flip — the pref key works uniformly across all three scopes.
+- Stale prefs are cleaned per-request, not via cron — the load on `IConfig::deleteUserValue` is bounded by login frequency. If this becomes a hotspot we can revisit with a background job in a follow-up change.
diff --git a/openspec/changes/active-dashboard-resolution/specs/dashboards/spec.md b/openspec/changes/active-dashboard-resolution/specs/dashboards/spec.md
new file mode 100644
index 00000000..bb91766c
--- /dev/null
+++ b/openspec/changes/active-dashboard-resolution/specs/dashboards/spec.md
@@ -0,0 +1,86 @@
+---
+capability: dashboards
+delta: true
+status: draft
+---
+
+# Dashboards — Delta from change `active-dashboard-resolution`
+
+## ADDED Requirements
+
+### Requirement: REQ-DASH-018 Active-dashboard resolution chain (multi-scope)
+
+When the workspace page renders for a user, the system MUST resolve which dashboard is "active" by walking the following precedence and stopping at the first match:
+
+1. The dashboard whose UUID equals the user's `active_dashboard_uuid` preference, IF that dashboard is currently visible to the user (per REQ-DASH-013).
+2. The `group_shared` dashboard with `isDefault = 1` in the user's primary group (per `group-routing` change, REQ-TMPL-012).
+3. The `group_shared` dashboard with `isDefault = 1` in the synthetic `'default'` group.
+4. The first `group_shared` dashboard (by `sortOrder` ascending, then `createdAt`) in the user's primary group.
+5. The first `group_shared` dashboard in the `'default'` group.
+6. The user's first personal `user`-type dashboard (by `sortOrder`, then `createdAt`).
+7. `null` — the workspace page MUST then render an empty-state with a "Create your first dashboard" affordance.
+
+The resolver MUST attach a `source` field to the returned dashboard descriptor with one of `'user'`, `'group'`, `'default'`.
+
+#### Scenario: Honoured user preference
+
+- GIVEN user "alice" has `active_dashboard_uuid` set to ``
+- AND `X` is a personal dashboard owned by alice
+- WHEN she opens the workspace page
+- THEN the resolved active dashboard MUST be `X` with `source = 'user'`
+
+#### Scenario: Stale preference is silently cleared
+
+- GIVEN user "alice" has `active_dashboard_uuid` set to ``
+- AND `Y` has been deleted (or is no longer visible to alice)
+- WHEN she opens the workspace page
+- THEN the resolver MUST clear her `active_dashboard_uuid` preference (set to empty string or unset)
+- AND MUST proceed down the precedence chain
+- AND the response MUST NOT raise an error to the user
+
+#### Scenario: Group default wins over default-group default
+
+- GIVEN user "bob" belongs to group "engineering"
+- AND group "engineering" has a default dashboard `E`
+- AND the `'default'` group also has a default dashboard `D`
+- AND bob has no `active_dashboard_uuid` preference
+- WHEN he opens the workspace page
+- THEN the resolved dashboard MUST be `E` with `source = 'group'`
+
+#### Scenario: Falls through to default group when primary group has no dashboards
+
+- GIVEN user "carol" belongs to group "support" which has zero group-shared dashboards
+- AND the `'default'` group has one default dashboard `D`
+- WHEN she opens the workspace page
+- THEN the resolved dashboard MUST be `D` with `source = 'default'`
+
+#### Scenario: Empty state when no dashboards exist anywhere
+
+- GIVEN a brand-new MyDash install with no dashboards of any type
+- WHEN any user opens the workspace page
+- THEN the resolver MUST return `null`
+- AND the response MUST include `activeDashboardId: ''` in initial state
+- AND the page MUST render the empty-state UI
+
+### Requirement: REQ-DASH-019 Persist active-dashboard preference
+
+The system MUST expose `POST /api/dashboards/active` accepting `{uuid: string}`. On success it MUST persist the value to the user's `active_dashboard_uuid` preference.
+
+#### Scenario: Save preference
+
+- GIVEN user "alice" is logged in
+- WHEN she sends `POST /api/dashboards/active` with body `{"uuid": "abc-123"}`
+- THEN her `active_dashboard_uuid` preference MUST become `"abc-123"`
+- AND the response MUST be HTTP 200 `{status: 'success'}`
+
+#### Scenario: Empty uuid clears the preference
+
+- GIVEN alice has a saved preference
+- WHEN she sends `POST /api/dashboards/active` with body `{"uuid": ""}`
+- THEN her `active_dashboard_uuid` preference MUST be cleared (next page load falls through the chain from step 2)
+
+#### Scenario: No existence check on write
+
+- GIVEN alice sends `POST /api/dashboards/active` with body `{"uuid": "does-not-exist"}`
+- THEN the system MUST accept the write (HTTP 200)
+- NOTE: The resolver's stale-preference path (REQ-DASH-018 scenario "stale preference") will silently clear it on next render. We deliberately do not validate on write to keep the endpoint cheap.
diff --git a/openspec/changes/active-dashboard-resolution/tasks.md b/openspec/changes/active-dashboard-resolution/tasks.md
new file mode 100644
index 00000000..0f7e067b
--- /dev/null
+++ b/openspec/changes/active-dashboard-resolution/tasks.md
@@ -0,0 +1,52 @@
+# Tasks — active-dashboard-resolution
+
+## 1. Backend resolver
+
+- [ ] 1.1 Add user pref key constant `DashboardService::ACTIVE_DASHBOARD_UUID_PREF_KEY = 'active_dashboard_uuid'`
+- [ ] 1.2 Add `DashboardService::resolveActiveDashboard(string $userId, ?string $primaryGroupId): ?array` returning `['dashboard' => Dashboard, 'source' => 'user'|'group'|'default']` or `null`
+- [ ] 1.3 Implement the 7-step precedence chain exactly as REQ-DASH-018 lists (saved pref → group default → default-group default → first-in-group → first-in-default-group → first personal → null)
+- [ ] 1.4 Implement stale-preference auto-clear: when the saved UUID is not in `findVisibleToUser` results, call `IConfig::deleteUserValue` (write-on-read) and emit a `LoggerInterface::warning` line
+- [ ] 1.5 Resolver MUST be otherwise pure (no other side effects on read)
+
+## 2. Backend write endpoint
+
+- [ ] 2.1 Add `DashboardService::setActivePreference(string $userId, string $uuid): void` that writes to `IConfig::setUserValue` (or deletes when uuid is empty string)
+- [ ] 2.2 Add `DashboardController::setActiveDashboard()` mapped to `POST /api/dashboards/active` with `#[NoAdminRequired]` — accepts `{uuid: string}`, returns HTTP 200 `{status: 'success'}`
+- [ ] 2.3 Register the route in `appinfo/routes.php`
+- [ ] 2.4 No existence check on write (per REQ-DASH-019 scenario "no existence check on write")
+
+## 3. Workspace integration
+
+- [ ] 3.1 Update `WorkspaceController` to call `resolveActiveDashboard($currentUserId, $primaryGroupId)` on first render
+- [ ] 3.2 Push `activeDashboardId` (or `''` when null) and `dashboardSource` into initial-state JSON via `IInitialState`
+- [ ] 3.3 When resolver returns null, ensure the page renders the empty-state UI (per REQ-DASH-018 scenario "empty state")
+
+## 4. Frontend
+
+- [ ] 4.1 Mirror the 7-step precedence in `useDashboardsStore.resolveActive()` for client-side `switchDashboard()` flows after store mutations
+- [ ] 4.2 Add `switchDashboard(uuid)` action that updates store state and POSTs to `/api/dashboards/active` (fire-and-forget; surface failure as a toast but do not block UI)
+- [ ] 4.3 Empty-state component shown when `resolveActive()` returns null — includes a "Create your first dashboard" affordance
+
+## 5. PHPUnit tests
+
+- [ ] 5.1 Table-driven test covering all 7 steps with permutations (saved pref / no pref; group default present / absent; default-group default present / absent; first-in-group present / absent; first personal present / absent; nothing-at-all)
+- [ ] 5.2 Stale preference cleared exactly once per request (not on every visibility check)
+- [ ] 5.3 Cross-group preference invalidated correctly — alice pref points to a dashboard whose group she no longer belongs to
+- [ ] 5.4 `setActivePreference` accepts non-existent UUIDs without erroring (REQ-DASH-019 scenario "no existence check on write")
+- [ ] 5.5 Empty-string uuid clears the preference (REQ-DASH-019 scenario "empty uuid clears the preference")
+
+## 6. Playwright tests
+
+- [ ] 6.1 Empty state shows on a fresh user with no dashboards (any type, any group)
+- [ ] 6.2 Switching dashboard fires `POST /api/dashboards/active` with the new UUID and the next page load picks up the saved choice
+- [ ] 6.3 Stale preference (dashboard deleted between sessions) silently falls through to step 2 of the chain — no error toast
+
+## 7. Quality gates
+
+- [ ] 7.1 `composer check:strict` (PHPCS, PHPMD, Psalm, PHPStan) passes — fix any pre-existing issues encountered along the way
+- [ ] 7.2 ESLint + Stylelint clean on touched Vue/JS files
+- [ ] 7.3 Update generated OpenAPI spec / Postman collection so external API consumers see the new endpoint
+- [ ] 7.4 `i18n` keys for new error messages and the empty-state copy in both `nl` and `en` per the i18n requirement
+- [ ] 7.5 SPDX headers on every new PHP file (inside the docblock per the SPDX-in-docblock convention) — gate-spdx must pass
+- [ ] 7.6 Run all 10 `hydra-gates` locally before opening PR
+- [ ] 7.7 Stale prefs are cleaned per request, not via cron — document the rationale in `design.md` if added (see proposal Notes)
diff --git a/openspec/changes/allow-personal-dashboards-flag/proposal.md b/openspec/changes/allow-personal-dashboards-flag/proposal.md
new file mode 100644
index 00000000..4faebd02
--- /dev/null
+++ b/openspec/changes/allow-personal-dashboards-flag/proposal.md
@@ -0,0 +1,29 @@
+# Allow-personal-dashboards flag — runtime gating
+
+The existing REQ-ASET-003 declares the `allow_user_dashboards` setting but does not specify how it gates the personal-dashboard endpoints at runtime. This change adds the gating semantics: when the flag is OFF, every personal-dashboard creation/fork endpoint MUST return 403 with a specific error code so the UI can render a coherent state, and existing personal dashboards MUST remain readable.
+
+## Affected code units
+
+- `lib/Controller/DashboardController.php` — every `POST /api/dashboards`, `POST /api/dashboards/{uuid}/fork`, and `POST /api/dashboards/active` (when target is personal) must check the flag
+- `lib/Service/DashboardService.php` — `getAllowUserDashboards(): bool` becomes a precondition checker
+- `src/views/WorkspaceApp.vue` — hide "+ New Dashboard" button when flag is off
+- `src/views/AdminApp.vue` — toggle wired to `POST /api/admin/settings`
+- Modifies REQ-ASET-003 (which already declares the setting)
+
+## Why a delta to `admin-settings`
+
+The setting itself is already declared. This change formalises:
+1. The exact runtime behaviour when toggled (what 403 means)
+2. The "do not auto-delete" semantics (existing personal dashboards survive, just become read-only-forking-disabled)
+3. The error envelope so the frontend can localise the message
+
+## Approach
+
+- Modify REQ-ASET-003 to declare side effects on personal-dashboard endpoints.
+- Personal dashboards already created remain visible and editable; only **creation/fork** is blocked while the flag is off.
+- Surfaced in initial state as `allowUserDashboards: bool` so the frontend can render appropriate empty states / hide buttons.
+
+## Notes
+
+- Default value is `'0'` (off) — admins must opt in.
+- Toggling off does NOT delete existing personal dashboards. It only blocks new ones. Document this clearly in the admin UI.
diff --git a/openspec/changes/allow-personal-dashboards-flag/specs/admin-settings/spec.md b/openspec/changes/allow-personal-dashboards-flag/specs/admin-settings/spec.md
new file mode 100644
index 00000000..acf11042
--- /dev/null
+++ b/openspec/changes/allow-personal-dashboards-flag/specs/admin-settings/spec.md
@@ -0,0 +1,84 @@
+---
+capability: admin-settings
+delta: true
+status: draft
+---
+
+# Admin Settings — Delta from change `allow-personal-dashboards-flag`
+
+## MODIFIED Requirements
+
+### Requirement: REQ-ASET-003 Allow User Dashboards Setting (extended runtime gating)
+
+The setting `allow_user_dashboards` (boolean stored as `'0'` / `'1'`, default `'0'`) MUST gate every endpoint that **creates** a personal (`type='user'`) dashboard. Read endpoints, update endpoints, and existing personal dashboards MUST remain accessible regardless of the flag's value. Toggling the flag MUST NOT mutate any dashboard records.
+
+The endpoints listed below MUST evaluate the flag at request time and, when it equals `'0'`, MUST return HTTP 403 with response body `{status: 'error', error: 'personal_dashboards_disabled', message: }`:
+
+- `POST /api/dashboards` (when payload omits `type` or sets `type='user'`)
+- `POST /api/dashboards/{uuid}/fork` (always — fork target is always `type='user'`)
+
+Endpoints that MUST NOT check the flag (so existing personal dashboards remain functional):
+
+- `GET /api/dashboards/visible`
+- `GET /api/dashboards/{uuid}`
+- `PUT /api/dashboards/{uuid}` (existing personal dashboard updates)
+- `DELETE /api/dashboards/{uuid}` (users can still clean up their old personal dashboards)
+- `POST /api/dashboards/active`
+- All `group_shared` and `admin_template` endpoints
+
+#### Scenario: Flag off blocks personal dashboard creation
+
+- **GIVEN** admin setting `allow_user_dashboards = '0'`
+- **WHEN** user "alice" sends `POST /api/dashboards` with body `{"name": "My Test"}`
+- **THEN** the system MUST return HTTP 403 with `{status: 'error', error: 'personal_dashboards_disabled', message: 'Personal dashboards are not enabled by your administrator'}`
+
+#### Scenario: Flag off blocks fork
+
+- **GIVEN** admin setting `allow_user_dashboards = '0'`
+- **AND** alice can read group-shared dashboard `S`
+- **WHEN** she sends `POST /api/dashboards/{S.uuid}/fork`
+- **THEN** the system MUST return HTTP 403 with the same `personal_dashboards_disabled` error envelope
+
+#### Scenario: Flag off does not break existing personal dashboards
+
+- **GIVEN** alice has 2 existing personal dashboards `P1`, `P2`
+- **AND** admin toggles `allow_user_dashboards` from `'1'` to `'0'`
+- **WHEN** alice opens the workspace page
+- **THEN** `P1` and `P2` MUST still appear in `GET /api/dashboards/visible`
+- **AND** alice MUST be able to `PUT` and `DELETE` them
+- **AND** alice MUST be able to set either as her active dashboard
+- **AND** only `POST /api/dashboards` and fork endpoints MUST return 403
+
+#### Scenario: Toggling does not destructively mutate data
+
+- **GIVEN** alice has 1 personal dashboard `P1` (active)
+- **AND** admin toggles `allow_user_dashboards` to `'0'` and back to `'1'`
+- **THEN** `P1` MUST still exist with all original fields and placements
+- **AND** `P1.isActive` MUST still be `1` (unchanged)
+- **AND** no rows in `oc_mydash_dashboards` or `oc_mydash_widget_placements` MUST have been touched
+
+#### Scenario: Default value when setting is missing
+
+- **GIVEN** a fresh MyDash install with no row for `allow_user_dashboards` in `oc_mydash_admin_settings`
+- **WHEN** any code reads the setting
+- **THEN** it MUST evaluate to `false` (creation blocked)
+
+## ADDED Requirements
+
+### Requirement: REQ-ASET-015 Initial-state mirror of the flag
+
+The setting's current value MUST be pushed as initial state `allowUserDashboards: bool` on every workspace and admin page render so the frontend can hide the "+ New Dashboard" affordance and the fork button without an extra round-trip.
+
+#### Scenario: Initial state matches setting
+
+- **GIVEN** admin setting `allow_user_dashboards = '1'`
+- **WHEN** any user loads the workspace page
+- **THEN** the page initial state MUST include `allowUserDashboards: true`
+
+#### Scenario: Frontend honours the flag
+
+- **GIVEN** initial state has `allowUserDashboards: false`
+- **WHEN** the workspace renders
+- **THEN** the "+ New Dashboard" button in the sidebar MUST NOT be visible
+- **AND** any "Fork as personal" affordance MUST NOT be visible
+- **AND** attempting to invoke the underlying actions via direct API call MUST still hit the 403 (defense in depth)
diff --git a/openspec/changes/allow-personal-dashboards-flag/tasks.md b/openspec/changes/allow-personal-dashboards-flag/tasks.md
new file mode 100644
index 00000000..0c071394
--- /dev/null
+++ b/openspec/changes/allow-personal-dashboards-flag/tasks.md
@@ -0,0 +1,31 @@
+# Tasks — allow-personal-dashboards-flag
+
+## 1. Backend
+
+- [ ] 1.1 Add `DashboardService::assertPersonalDashboardsAllowed(): void` (throws `PersonalDashboardsDisabledException`)
+- [ ] 1.2 Define `PersonalDashboardsDisabledException` mapping to HTTP 403 with `error: 'personal_dashboards_disabled'`
+- [ ] 1.3 Call assert in `DashboardController::create` (when type=user) and `::fork`
+- [ ] 1.4 Ensure read/update/delete endpoints do NOT call the assert
+- [ ] 1.5 Update `WorkspaceController::index` to push `allowUserDashboards` initial state
+- [ ] 1.6 Update admin endpoints to surface flag in their initial state too
+
+## 2. Frontend
+
+- [ ] 2.1 Hide "+ New Dashboard" sidebar button when `!allowUserDashboards`
+- [ ] 2.2 Hide "Fork to personal" button when `!allowUserDashboards`
+- [ ] 2.3 Surface 403 with `error === 'personal_dashboards_disabled'` as a localised toast
+- [ ] 2.4 Document the toggle's "data is preserved" behaviour in the admin UI helper text
+
+## 3. Tests
+
+- [ ] 3.1 PHPUnit: 403 envelope shape exactly matches REQ-ASET-003 scenario
+- [ ] 3.2 PHPUnit: existing personal dashboards remain readable/editable when flag off
+- [ ] 3.3 PHPUnit: toggling does not mutate data (assert row counts before/after)
+- [ ] 3.4 Playwright: button visibility matches flag state
+- [ ] 3.5 Playwright: direct API call (bypassing UI) still returns 403
+
+## 4. Quality
+
+- [ ] 4.1 `composer check:strict` passes
+- [ ] 4.2 OpenAPI updated with the 403 response variant
+- [ ] 4.3 Translation file entries for `'Personal dashboards are not enabled by your administrator'`
diff --git a/openspec/changes/archive/2026-03-21-admin-settings/.openspec.yaml b/openspec/changes/archive/2026-03-21-admin-settings/.openspec.yaml
new file mode 100644
index 00000000..d8b0ed03
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-settings/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-admin-settings/design.md b/openspec/changes/archive/2026-03-21-admin-settings/design.md
new file mode 100644
index 00000000..45dc4dc9
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-settings/design.md
@@ -0,0 +1,27 @@
+# Admin Settings - Design Document
+
+## Architecture
+
+### Backend
+- **Entity**: `Db\AdminSetting` - Key-value pair with JSON-encoded values
+- **Mapper**: `Db\AdminSettingMapper` - getAllAsArray, setSetting, getValue
+- **Service**: `Service\AdminSettingsService` - Get/update settings with defaults
+- **Controller**: `Controller\AdminController` - Admin-only REST endpoints
+
+### Frontend
+- **Component**: `components/admin/AdminSettings.vue` - Settings form UI
+- **Entry**: `admin.js` - Admin page entry point
+
+### Settings
+| Key (DB) | API Key | Type | Default |
+|----------|---------|------|---------|
+| allow_user_dashboards | allowUserDashboards | boolean | true |
+| allow_multiple_dashboards | allowMultipleDashboards | boolean | true |
+| default_permission_level | defaultPermissionLevel | string | add_only |
+| default_grid_columns | defaultGridColumns | integer | 12 |
+
+### Key Design Decisions
+- Settings stored as JSON-encoded values in dedicated table
+- DB uses snake_case keys, API returns camelCase keys
+- Factory defaults applied in service layer (not DB)
+- Admin-only access enforced by @AdminRequired annotation
diff --git a/openspec/changes/archive/2026-03-21-admin-settings/proposal.md b/openspec/changes/archive/2026-03-21-admin-settings/proposal.md
new file mode 100644
index 00000000..946e9e3d
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-settings/proposal.md
@@ -0,0 +1,18 @@
+# Admin Settings Specification
+
+## Problem
+Admin settings provide Nextcloud administrators with global configuration options for the MyDash app. These settings control system-wide behavior such as whether users can create their own dashboards, how many dashboards they can have, default permission levels for new dashboards, and default grid configuration. Settings are stored as key-value pairs in a dedicated database table and are applied as defaults or constraints across the entire MyDash installation.
+
+## Proposed Solution
+Implement Admin Settings Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the admin-settings specification.
+
+## Success Criteria
+- Get all settings with defaults
+- Get settings after modification
+- Non-admin user retrieves settings
+- Settings used by non-admin endpoints
+- Settings response format consistency
diff --git a/openspec/specs/admin-settings/design.md b/openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/design.md
similarity index 100%
rename from openspec/specs/admin-settings/design.md
rename to openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/design.md
diff --git a/openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/spec.md b/openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/spec.md
new file mode 100644
index 00000000..e6ae1932
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/spec.md
@@ -0,0 +1,425 @@
+---
+status: reviewed
+---
+
+# Admin Settings Specification
+
+## Purpose
+
+Admin settings provide Nextcloud administrators with global configuration options for the MyDash app. These settings control system-wide behavior such as whether users can create their own dashboards, how many dashboards they can have, default permission levels for new dashboards, and default grid configuration. Settings are stored as key-value pairs in a dedicated database table and are applied as defaults or constraints across the entire MyDash installation.
+
+## Data Model
+
+### Admin Settings (oc_mydash_admin_settings)
+Settings are stored as key-value pairs:
+- **id**: Auto-increment integer primary key
+- **settingKey**: Unique string identifier for the setting (STRING)
+- **settingValue**: JSON-encoded string value (STRING, nullable). Values are stored via `json_encode()` and retrieved via `json_decode()`.
+- **updatedAt**: Timestamp (DATETIME)
+
+### Defined Settings
+
+| Setting Key (DB) | API Response Key | Type | Default | Description |
+|------------------|------------------|------|---------|-------------|
+| `allow_user_dashboards` | `allowUserDashboards` | boolean | `true` | Whether non-admin users can create their own dashboards |
+| `allow_multiple_dashboards` | `allowMultipleDashboards` | boolean | `true` | Whether users can have more than one dashboard |
+| `default_permission_level` | `defaultPermissionLevel` | string | `add_only` | Default permission level for user-created dashboards |
+| `default_grid_columns` | `defaultGridColumns` | integer | `12` | Default number of grid columns for new dashboards |
+
+NOTE: The DB stores settings with snake_case keys, but the API response returns camelCase keys. The factory default for `defaultPermissionLevel` is `add_only` (Dashboard::PERMISSION_ADD_ONLY), NOT `full`. The API update endpoint accepts abbreviated camelCase parameter names: `defaultPermLevel`, `allowUserDash`, `allowMultiDash`, `defaultGridCols`.
+
+## Requirements
+
+### REQ-ASET-001: Retrieve Admin Settings
+
+Administrators MUST be able to retrieve all current admin settings via the API. The endpoint returns a flat JSON object with all four settings using camelCase keys.
+
+#### Scenario: Get all settings with defaults
+- GIVEN no admin settings have been explicitly configured (fresh installation)
+- WHEN the admin sends GET /api/admin/settings
+- THEN the system MUST return HTTP 200 with all settings at their default values:
+ ```json
+ {
+ "defaultPermissionLevel": "add_only",
+ "allowUserDashboards": true,
+ "allowMultipleDashboards": true,
+ "defaultGridColumns": 12
+ }
+ ```
+
+#### Scenario: Get settings after modification
+- GIVEN the admin has set `allowUserDashboards` to `false`
+- WHEN the admin sends GET /api/admin/settings
+- THEN the system MUST return the updated value:
+ ```json
+ {
+ "defaultPermissionLevel": "add_only",
+ "allowUserDashboards": false,
+ "allowMultipleDashboards": true,
+ "defaultGridColumns": 12
+ }
+ ```
+
+#### Scenario: Non-admin user retrieves settings
+- GIVEN a regular user "alice"
+- WHEN she sends GET /api/admin/settings
+- THEN the system MUST return HTTP 403
+- AND admin settings MUST NOT be exposed to non-admin users
+
+#### Scenario: Settings used by non-admin endpoints
+- GIVEN the admin has set `allowUserDashboards` to `false`
+- WHEN user "alice" sends POST /api/dashboard (to create a dashboard)
+- THEN the system MUST internally check the `allowUserDashboards` setting via `PermissionService::canCreateDashboard()`
+- AND the non-admin user MUST NOT need to call GET /api/admin/settings to experience the effect
+
+#### Scenario: Settings response format consistency
+- GIVEN the admin has configured various settings at different times
+- WHEN GET /api/admin/settings is called
+- THEN the response MUST always return exactly four keys: `defaultPermissionLevel`, `allowUserDashboards`, `allowMultipleDashboards`, `defaultGridColumns`
+- AND no additional keys MUST be present in the response
+- AND the response MUST be a flat JSON object (no nesting)
+
+### REQ-ASET-002: Update Admin Settings
+
+Administrators MUST be able to update individual or multiple admin settings in a single PUT request.
+
+#### Scenario: Update a single boolean setting
+- GIVEN the admin wants to disable user dashboard creation
+- WHEN they send PUT /api/admin/settings with body `{"allowUserDash": false}`
+- THEN the system MUST update the `allowUserDashboards` setting to `false`
+- AND the response MUST return HTTP 200 with `{"status": "ok"}`
+- NOTE: The API update endpoint accepts abbreviated camelCase parameter names (`defaultPermLevel`, `allowUserDash`, `allowMultiDash`, `defaultGridCols`), NOT the full response key names. The response returns `{"status": "ok"}`, NOT the full settings object.
+
+#### Scenario: Update multiple settings at once
+- GIVEN the admin wants to change several settings
+- WHEN they send PUT /api/admin/settings with body:
+ ```json
+ {
+ "allowUserDash": true,
+ "allowMultiDash": false,
+ "defaultGridCols": 8
+ }
+ ```
+- THEN the system MUST update all three specified settings
+- AND settings not included in the request MUST remain unchanged
+
+#### Scenario: Update with invalid permission level value
+- GIVEN the admin sends PUT /api/admin/settings with body `{"defaultPermLevel": "super_admin"}`
+- THEN the system SHOULD return HTTP 400 with a validation error
+- AND only `view_only`, `add_only`, and `full` SHOULD be accepted for this setting
+- NOTE: Permission level validation is NOT currently implemented -- any string value is accepted
+
+#### Scenario: Update with invalid grid columns value
+- GIVEN the admin sends PUT /api/admin/settings with body `{"defaultGridCols": 0}`
+- THEN the system SHOULD return HTTP 400 with a validation error
+- AND `defaultGridCols` SHOULD be a positive integer between 1 and 24
+- NOTE: Grid columns validation is NOT currently implemented -- any integer value is accepted
+
+#### Scenario: Update with invalid boolean value
+- GIVEN the admin sends PUT /api/admin/settings with body `{"allowUserDash": "maybe"}`
+- THEN the system SHOULD return HTTP 400 with a validation error
+- AND boolean settings SHOULD only accept `true` or `false`
+- NOTE: Boolean validation is NOT currently implemented -- PHP type coercion handles the value
+
+#### Scenario: Non-admin cannot update settings
+- GIVEN a regular user "alice"
+- WHEN she sends PUT /api/admin/settings with any body
+- THEN the system MUST return HTTP 403
+- AND no settings MUST be modified
+- NOTE: Admin-only access is enforced because the AdminController does NOT have a `#[NoAdminRequired]` attribute
+
+#### Scenario: Update with unknown setting key
+- GIVEN the admin sends PUT /api/admin/settings with body `{"unknownSetting": "value"}`
+- THEN the system MUST ignore the unknown key (unrecognized parameters are simply not matched to method arguments)
+- AND known settings MUST NOT be affected
+
+### REQ-ASET-003: Allow User Dashboards Setting
+
+When `allowUserDashboards` is false, non-admin users MUST NOT be able to create their own dashboards. This is enforced by `PermissionService::canCreateDashboard()`.
+
+#### Scenario: User dashboard creation blocked
+- GIVEN `allowUserDashboards` is set to `false`
+- WHEN user "alice" sends POST /api/dashboard with body `{"name": "My Dashboard"}`
+- THEN the system MUST return HTTP 403 with a message indicating user dashboard creation is disabled
+- AND no dashboard MUST be created
+
+#### Scenario: User dashboard creation allowed
+- GIVEN `allowUserDashboards` is set to `true` (default)
+- WHEN user "alice" sends POST /api/dashboard with body `{"name": "My Dashboard"}`
+- THEN the system MUST allow the creation
+- AND the response MUST return HTTP 201
+
+#### Scenario: Admins can always create dashboards
+- GIVEN `allowUserDashboards` is set to `false`
+- WHEN a Nextcloud admin sends POST /api/dashboard with body `{"name": "Admin Dashboard"}`
+- THEN the system MUST allow the creation
+- AND the admin setting MUST NOT restrict admin users
+
+#### Scenario: Existing user dashboards preserved when setting is disabled
+- GIVEN user "alice" has 3 dashboards
+- AND the admin sets `allowUserDashboards` to `false`
+- WHEN alice views her dashboards via GET /api/dashboards
+- THEN all 3 existing dashboards MUST still be returned
+- AND alice MUST still be able to view, edit (per permission level), and delete her existing dashboards
+- AND alice MUST NOT be able to create new dashboards
+
+#### Scenario: Frontend hides create button when disabled
+- GIVEN `allowUserDashboards` is set to `false`
+- WHEN user "alice" views the MyDash interface
+- THEN the "Create Dashboard" button MUST NOT be displayed
+- AND the UI SHOULD display a message such as "Dashboard creation is managed by your administrator"
+
+### REQ-ASET-004: Allow Multiple Dashboards Setting
+
+When `allow_multiple_dashboards` is false, users MUST be limited to one dashboard.
+
+#### Scenario: Second dashboard creation blocked
+- GIVEN `allowMultipleDashboards` is set to `false`
+- AND user "alice" already has 1 dashboard
+- WHEN she sends POST /api/dashboard with body `{"name": "Second Dashboard"}`
+- THEN the system MUST return HTTP 403 with a message indicating multiple dashboards are not allowed
+- AND no dashboard MUST be created
+
+#### Scenario: First dashboard creation allowed
+- GIVEN `allowMultipleDashboards` is set to `false`
+- AND user "bob" has no dashboards
+- WHEN he sends POST /api/dashboard with body `{"name": "My Dashboard"}`
+- THEN the system MUST allow the creation (this is his first dashboard)
+- AND the response MUST return HTTP 201
+
+#### Scenario: Multiple dashboards allowed (default)
+- GIVEN `allowMultipleDashboards` is set to `true` (default)
+- AND user "alice" already has 3 dashboards
+- WHEN she sends POST /api/dashboard with body `{"name": "Fourth Dashboard"}`
+- THEN the system MUST allow the creation
+- AND the response MUST return HTTP 201
+
+#### Scenario: Existing dashboards preserved when setting is disabled
+- GIVEN user "alice" has 3 dashboards
+- AND the admin sets `allow_multiple_dashboards` to `false`
+- WHEN alice views her dashboards via GET /api/dashboards
+- THEN all 3 existing dashboards MUST still be returned
+- AND alice MUST NOT be able to create additional dashboards
+- AND alice MUST be able to delete dashboards to get down to 1
+
+#### Scenario: Template distribution overrides multiple dashboard restriction
+- GIVEN `allowMultipleDashboards` is set to `false`
+- AND user "alice" has 1 dashboard
+- AND a new admin template targets alice's group
+- WHEN the template distribution triggers for alice
+- THEN the system MUST still create the template copy for alice
+- AND alice MUST have 2 dashboards (the restriction applies to user-initiated creation, not admin-initiated distribution)
+
+### REQ-ASET-005: Default Permission Level Setting
+
+The `defaultPermissionLevel` setting MUST be applied as a fallback when resolving effective permission levels. The factory default is `add_only` (Dashboard::PERMISSION_ADD_ONLY).
+
+#### Scenario: Default permission level applied to new dashboard
+- GIVEN `defaultPermissionLevel` is set to `add_only`
+- WHEN user "alice" sends POST /api/dashboard with body `{"name": "My Dashboard"}`
+- THEN the created dashboard MUST have `permissionLevel: "full"` (user-created dashboards use `DashboardFactory::create()` which hardcodes `PERMISSION_FULL`)
+- AND the `defaultPermissionLevel` admin setting acts as a fallback in `PermissionService::getEffectivePermissionLevel()` only when the dashboard's own `permissionLevel` is empty
+
+#### Scenario: Factory default permission (add_only)
+- GIVEN `defaultPermissionLevel` is at its factory default of `add_only`
+- WHEN `PermissionService::getEffectivePermissionLevel()` is called for a dashboard with no `permissionLevel` set and no `basedOnTemplate`
+- THEN the effective level MUST resolve to `add_only` (the admin default)
+- NOTE: The factory default is `add_only` (Dashboard::PERMISSION_ADD_ONLY), NOT `full`
+
+#### Scenario: Default permission does not affect template copies
+- GIVEN `defaultPermissionLevel` is set to `view_only`
+- AND an admin template exists with `permissionLevel: "full"`
+- WHEN a user receives a copy of that template
+- THEN the copy MUST have `permissionLevel: "full"` (from the template)
+- AND the global default MUST NOT override the template's permission level
+
+#### Scenario: Admin can override default for individual templates
+- GIVEN `defaultPermissionLevel` is set to `add_only`
+- WHEN the admin creates a template with `permissionLevel: "full"`
+- THEN the template MUST have `permissionLevel: "full"`
+- AND the global default MUST NOT constrain template configuration
+
+#### Scenario: Permission resolution chain
+- GIVEN a dashboard with `basedOnTemplate: 42` and the template has `permissionLevel: "add_only"`
+- WHEN `PermissionService::getEffectivePermissionLevel()` is called
+- THEN the system MUST check in order: (1) source template's `permissionLevel`, (2) dashboard's own `permissionLevel`, (3) admin default setting
+- AND the first non-empty value in the chain MUST be returned
+
+### REQ-ASET-006: Default Grid Columns Setting
+
+The `defaultGridColumns` setting MUST be applied to new dashboards when no explicit gridColumns is specified.
+
+#### Scenario: Default grid columns applied
+- GIVEN `defaultGridColumns` is set to `8`
+- WHEN user "alice" sends POST /api/dashboard with body `{"name": "My Dashboard"}`
+- THEN the created dashboard MUST have `gridColumns: 8`
+- NOTE: `DashboardFactory::create()` currently hardcodes `gridColumns: 12` and does NOT read the `defaultGridColumns` admin setting. This is a known gap.
+
+#### Scenario: Explicit grid columns overrides default
+- GIVEN `defaultGridColumns` is set to `8`
+- WHEN user "alice" sends POST /api/dashboard with body `{"name": "My Dashboard", "gridColumns": 12}`
+- THEN the created dashboard MUST have `gridColumns: 12` (explicit value takes precedence)
+
+#### Scenario: Default grid columns for template copies
+- GIVEN `defaultGridColumns` is set to `8`
+- AND an admin template exists with `gridColumns: 12`
+- WHEN a user receives a copy of that template
+- THEN the copy MUST have `gridColumns: 12` (from the template)
+- AND the global default MUST NOT override the template's grid configuration
+
+### REQ-ASET-007: Settings Persistence
+
+Admin settings MUST be persisted across server restarts and app updates.
+
+#### Scenario: Settings survive server restart
+- GIVEN the admin has configured `allowUserDashboards: false`
+- WHEN the Nextcloud server is restarted
+- THEN GET /api/admin/settings MUST still return `allowUserDashboards: false`
+- AND the setting MUST NOT revert to its default value
+
+#### Scenario: Settings survive app update
+- GIVEN the admin has configured custom settings
+- WHEN the MyDash app is updated to a new version
+- THEN all previously configured settings MUST be preserved
+- AND new settings introduced in the update MUST use their default values
+
+#### Scenario: Factory reset behavior
+- GIVEN the admin wants to reset all settings to defaults
+- WHEN they send PUT /api/admin/settings with all default values:
+ ```json
+ {
+ "allowUserDash": true,
+ "allowMultiDash": true,
+ "defaultPermLevel": "add_only",
+ "defaultGridCols": 12
+ }
+ ```
+- THEN all settings MUST be reset to their factory defaults
+- AND the response MUST confirm the update
+
+### REQ-ASET-008: Admin Settings UI
+
+The admin settings MUST be accessible via a Nextcloud admin panel page.
+
+#### Scenario: Admin settings page is registered
+- GIVEN a Nextcloud admin user
+- WHEN they navigate to Settings > Administration
+- THEN a "MyDash" entry MUST appear in the admin settings navigation
+- AND clicking it MUST display the MyDash admin settings page
+
+#### Scenario: Regular user cannot access admin settings page
+- GIVEN a regular (non-admin) Nextcloud user
+- WHEN they navigate to Settings
+- THEN the "MyDash" entry MUST NOT appear in their settings navigation
+- AND direct URL access to the admin settings page MUST return HTTP 403
+
+#### Scenario: Settings form layout
+- GIVEN the admin opens the MyDash admin settings page
+- THEN the page MUST display:
+ - A toggle for "Allow user dashboards" (on/off)
+ - A toggle for "Allow multiple dashboards" (on/off)
+ - A dropdown for "Default permission level" (view_only, add_only, full)
+ - A number input for "Default grid columns" (1-24)
+ - A "Save" button
+- AND each setting MUST show its current value
+
+#### Scenario: Settings saved via the UI
+- GIVEN the admin changes "Allow user dashboards" to off and clicks Save
+- WHEN the save completes
+- THEN the system MUST display a success notification
+- AND GET /api/admin/settings MUST reflect the change
+
+### REQ-ASET-009: Settings Impact on Existing Data
+
+Admin settings changes MUST only affect future operations and MUST NOT retroactively modify existing dashboards.
+
+#### Scenario: Changing default permission level does not modify existing dashboards
+- GIVEN user "alice" has a dashboard with `permissionLevel: "full"`
+- WHEN the admin changes `defaultPermissionLevel` to `view_only`
+- THEN alice's existing dashboard MUST retain `permissionLevel: "full"`
+- AND the new default MUST only apply to dashboards created after the change
+
+#### Scenario: Changing grid columns default does not modify existing dashboards
+- GIVEN user "alice" has a dashboard with `gridColumns: 12`
+- WHEN the admin changes `defaultGridColumns` to `8`
+- THEN alice's existing dashboard MUST retain `gridColumns: 12`
+- AND only newly created dashboards MUST use the new default of `8`
+
+#### Scenario: Disabling user dashboards does not delete existing dashboards
+- GIVEN 50 users each have personal dashboards
+- WHEN the admin sets `allowUserDashboards` to `false`
+- THEN all 50 existing dashboards MUST be preserved
+- AND users MUST continue to access their existing dashboards
+- AND only new dashboard creation MUST be blocked
+
+### REQ-ASET-010: Settings Concurrency
+
+Concurrent admin settings updates MUST be handled safely.
+
+#### Scenario: Simultaneous updates from two admin sessions
+- GIVEN admin user A sets `allowUserDash: false` at the same time admin user B sets `allowMultiDash: false`
+- WHEN both PUT requests are processed
+- THEN each setting MUST be independently updated without data loss
+- AND the final state MUST reflect both changes (last-write-wins per individual setting key)
+
+#### Scenario: Rapid successive updates
+- GIVEN the admin clicks Save multiple times quickly
+- WHEN multiple PUT requests are sent in rapid succession
+- THEN the system MUST process each request independently
+- AND the final state MUST reflect the last request's values
+
+### REQ-ASET-011: Settings API Error Handling
+
+The settings API MUST return consistent error responses for various failure scenarios.
+
+#### Scenario: Database connection failure during settings retrieval
+- GIVEN the database is temporarily unavailable
+- WHEN the admin sends GET /api/admin/settings
+- THEN the system MUST return HTTP 500 with an error message
+- AND the error MUST NOT expose internal database details
+
+#### Scenario: Database connection failure during settings update
+- GIVEN the database is temporarily unavailable
+- WHEN the admin sends PUT /api/admin/settings with valid data
+- THEN the system MUST return HTTP 500 with an error message
+- AND no partial updates MUST be persisted
+
+#### Scenario: Empty request body for update
+- GIVEN the admin sends PUT /api/admin/settings with an empty body `{}`
+- WHEN the request is processed
+- THEN the system MUST return HTTP 200 with `{"status": "ok"}`
+- AND no settings MUST be modified (all parameters are null, so no updates are applied)
+
+## Non-Functional Requirements
+
+- **Performance**: GET /api/admin/settings MUST return within 100ms. Settings lookups during user operations (e.g., `PermissionService::canCreateDashboard()`) query the `AdminSettingMapper` each time; caching is NOT currently implemented.
+- **Security**: All admin settings endpoints MUST require Nextcloud admin authentication. Settings MUST NOT be exposed to non-admin users in any way (not even setting keys).
+- **Data integrity**: Settings MUST survive server restarts and app updates. Missing settings MUST fall back to documented defaults without errors.
+- **Accessibility**: The admin settings form MUST have proper labels, be keyboard-navigable, and meet WCAG AA standards. Toggle states MUST be communicated to screen readers.
+- **Localization**: All setting labels, descriptions, validation messages, and success/error notifications MUST support English and Dutch.
+
+### Current Implementation Status
+
+**Fully implemented:**
+- REQ-ASET-001 (Retrieve Admin Settings): `AdminSettingsService::getSettings()` in `lib/Service/AdminSettingsService.php` returns all 4 settings with documented defaults. `AdminController::getSettings()` in `lib/Controller/AdminController.php` exposes GET /api/admin/settings. Non-admin access is blocked because AdminController lacks `#[NoAdminRequired]`.
+- REQ-ASET-002 (Update Admin Settings): `AdminSettingsService::updateSettings()` accepts abbreviated camelCase params (`defaultPermLevel`, `allowUserDash`, `allowMultiDash`, `defaultGridCols`). `AdminController::updateSettings()` returns `{"status": "ok"}`.
+- REQ-ASET-003 (Allow User Dashboards): `PermissionService::canCreateDashboard()` in `lib/Service/PermissionService.php` checks `AdminSetting::KEY_ALLOW_USER_DASHBOARDS`. `DashboardApiController::checkCreatePermissions()` in `lib/Controller/DashboardApiController.php` returns 403 when disabled.
+- REQ-ASET-004 (Allow Multiple Dashboards): `PermissionService::canHaveMultipleDashboards()` checks the setting. `DashboardApiController::checkCreatePermissions()` counts existing dashboards and returns 403 if multiples are disallowed.
+- REQ-ASET-005 (Default Permission Level): `DashboardFactory::create()` in `lib/Service/DashboardFactory.php` hardcodes `PERMISSION_FULL` for user-created dashboards. The admin default setting is used as fallback by `PermissionService::getEffectivePermissionLevel()`.
+- REQ-ASET-007 (Settings Persistence): Settings are stored in `oc_mydash_admin_settings` table via `AdminSettingMapper`. Defaults are returned in-code when DB rows are absent.
+- REQ-ASET-008 (Admin Settings UI): `MyDashAdmin` in `lib/Settings/MyDashAdmin.php` implements `ISettings`, `MyDashAdminSection` in `lib/Settings/MyDashAdminSection.php` implements `IIconSection`. Frontend in `src/components/admin/AdminSettings.vue` renders toggles, dropdowns, and save logic.
+
+**Not yet implemented:**
+- REQ-ASET-002 validation: No server-side validation for permission level values (any string accepted), grid column range (any integer accepted), or boolean type coercion. Documented as NOTEs in the spec.
+- REQ-ASET-006 default grid columns: `DashboardFactory::create()` hardcodes `gridColumns: 12` and does NOT read the `defaultGridColumns` admin setting. The admin setting exists but is not applied when creating user dashboards.
+- REQ-ASET-003 frontend UX: The AdminSettings.vue does not show a "Dashboard creation is managed by your administrator" message to non-admin users. Admin-only enforcement relies on controller access control, but the user-facing frontend does not reflect this state.
+- REQ-ASET-008 localization: UI labels use `t('mydash', ...)` translation function but actual Dutch translations are not verified in l10n files.
+
+**Partial implementations:**
+- REQ-ASET-006 (Default Grid Columns): The setting can be stored and retrieved, but `DashboardFactory::create()` ignores it, hardcoding 12. Template copies correctly use the template's `gridColumns` via `TemplateService::buildDashboardFromTemplate()`.
+
+### Standards & References
+- Nextcloud Admin Settings API: `OCP\Settings\ISettings`, `OCP\Settings\IIconSection`
+- Nextcloud AppConfig pattern (though this app uses a custom DB table instead of `IAppConfig`)
+- WCAG 2.1 AA for the admin settings form (keyboard navigation, labels, focus indicators)
+- WAI-ARIA: Toggle states for checkbox switches communicated via `NcCheckboxRadioSwitch`
diff --git a/openspec/specs/admin-settings/tasks.md b/openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/tasks.md
similarity index 100%
rename from openspec/specs/admin-settings/tasks.md
rename to openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/tasks.md
diff --git a/openspec/changes/archive/2026-03-21-admin-settings/tasks.md b/openspec/changes/archive/2026-03-21-admin-settings/tasks.md
new file mode 100644
index 00000000..fc161fa0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-settings/tasks.md
@@ -0,0 +1,14 @@
+# Admin Settings - Tasks
+
+## Tasks
+
+- [x] TASK-ASET-001: Implement AdminSetting entity with JSON helpers
+- [x] TASK-ASET-002: Implement AdminSettingMapper with get/set operations
+- [x] TASK-ASET-003: Implement AdminSettingsService with defaults
+- [x] TASK-ASET-004: Implement admin settings REST endpoints in AdminController
+- [x] TASK-ASET-005: Implement database migration for admin_settings table
+- [x] TASK-ASET-006: Implement frontend AdminSettings component
+- [x] TASK-ASET-007: Write unit tests for AdminSetting entity (ADR-009)
+- [x] TASK-ASET-008: Write unit tests for AdminSettingsService (ADR-009)
+- [x] TASK-ASET-009: Write feature documentation and screenshots (ADR-010)
+- [x] TASK-ASET-010: Verify i18n support for admin settings UI (ADR-005)
diff --git a/openspec/changes/archive/2026-03-21-admin-templates/.openspec.yaml b/openspec/changes/archive/2026-03-21-admin-templates/.openspec.yaml
new file mode 100644
index 00000000..d8b0ed03
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-templates/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-admin-templates/design.md b/openspec/changes/archive/2026-03-21-admin-templates/design.md
new file mode 100644
index 00000000..5856e5e6
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-templates/design.md
@@ -0,0 +1,28 @@
+# Admin Templates - Design Document
+
+## Architecture
+
+### Backend
+- **Service**: `Service\TemplateService` - Template distribution, dashboard creation from template
+- **Service**: `Service\AdminTemplateService` - Admin CRUD for templates
+- **Controller**: `Controller\AdminController` - Admin-only template endpoints
+
+### Data Model
+- Templates are Dashboard entities with type="admin_template"
+- Additional fields: targetGroups (JSON), isDefault (0/1), permissionLevel
+- userId set to null for templates (not owned by specific user)
+- Template placements include isCompulsory flags
+
+### Template Distribution Flow
+1. Admin creates template with target groups
+2. User opens MyDash -> DashboardResolver checks for applicable template
+3. TemplateService.getApplicableTemplate() matches user groups
+4. TemplateService.createDashboardFromTemplate() clones template + placements
+5. User gets independent copy with inherited permission level
+
+### Key Design Decisions
+- Group-specific templates take priority over default templates
+- Only one default template allowed (clearDefaultTemplates on new default)
+- Template placements cloned with isCompulsory preserved
+- User copies reference template via basedOnTemplate field
+- Ramsey/Uuid used for template-based dashboard UUIDs
diff --git a/openspec/changes/archive/2026-03-21-admin-templates/proposal.md b/openspec/changes/archive/2026-03-21-admin-templates/proposal.md
new file mode 100644
index 00000000..34c17818
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-templates/proposal.md
@@ -0,0 +1,18 @@
+# Admin Templates Specification
+
+## Problem
+Admin templates allow Nextcloud administrators to create pre-configured dashboards that are automatically distributed to users based on group membership. When a user opens MyDash for the first time (or when a new template targets their group), the system creates a personal copy of the matching template. This copy is an independent dashboard that the user can modify within the limits of the inherited permission level. Templates enable organizations to provide standardized dashboard layouts with compulsory widgets while still allowing user customization where appropriate.
+
+## Proposed Solution
+Implement Admin Templates Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the admin-templates specification.
+
+## Success Criteria
+- Create a template targeting specific groups
+- Create a default template for all users
+- Non-admin user cannot create templates
+- Create template with invalid permission level
+- Create template with UUID generation
diff --git a/openspec/specs/admin-templates/design.md b/openspec/changes/archive/2026-03-21-admin-templates/specs/admin-templates/design.md
similarity index 100%
rename from openspec/specs/admin-templates/design.md
rename to openspec/changes/archive/2026-03-21-admin-templates/specs/admin-templates/design.md
diff --git a/openspec/changes/archive/2026-03-21-admin-templates/specs/admin-templates/spec.md b/openspec/changes/archive/2026-03-21-admin-templates/specs/admin-templates/spec.md
new file mode 100644
index 00000000..9c877599
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-templates/specs/admin-templates/spec.md
@@ -0,0 +1,396 @@
+---
+status: reviewed
+---
+
+# Admin Templates Specification
+
+## Purpose
+
+Admin templates allow Nextcloud administrators to create pre-configured dashboards that are automatically distributed to users based on group membership. When a user opens MyDash for the first time (or when a new template targets their group), the system creates a personal copy of the matching template. This copy is an independent dashboard that the user can modify within the limits of the inherited permission level. Templates enable organizations to provide standardized dashboard layouts with compulsory widgets while still allowing user customization where appropriate.
+
+## Data Model
+
+Admin templates are stored as dashboards in `oc_mydash_dashboards` with `type: "admin_template"`. Additional template-specific fields:
+- **targetGroups**: JSON string of Nextcloud group IDs (e.g., `["marketing", "all-staff"]`), accessed via `getTargetGroupsArray()`/`setTargetGroupsArray()`
+- **isDefault**: SMALLINT (0/1) flag -- if 1 (true), this template is distributed to all users regardless of group membership
+- **permissionLevel**: One of `view_only`, `add_only`, `full` -- inherited by user copies
+- **userId**: Set to null for admin templates (they are not owned by a specific user)
+- **basedOnTemplate**: Not used for templates themselves; used on user copies to reference the template ID
+
+Templates own their widget placements (in `oc_mydash_widget_placements`) which serve as the blueprint for user copies. The template's placements include `isCompulsory` flags that are copied to user dashboards. When a user copy is created, `TemplateService::createDashboardFromTemplate()` clones all placements from the template to the new user dashboard.
+
+## Requirements
+
+### REQ-TMPL-001: Create Admin Template
+
+Nextcloud administrators MUST be able to create dashboard templates for distribution to users.
+
+#### Scenario: Create a template targeting specific groups
+- GIVEN a Nextcloud admin user
+- WHEN they send POST /api/admin/templates with body:
+ ```json
+ {
+ "name": "Marketing Dashboard",
+ "description": "Standard dashboard for the marketing team",
+ "targetGroups": ["marketing", "communications"],
+ "isDefault": false,
+ "permissionLevel": "add_only"
+ }
+ ```
+- THEN the system MUST create a dashboard with `type: "admin_template"`
+- AND `userId` MUST be set to null (admin templates are not owned by a specific user)
+- AND `gridColumns` MUST default to 12
+- AND the response MUST return HTTP 201 with the full template object
+
+#### Scenario: Create a default template for all users
+- GIVEN a Nextcloud admin user
+- WHEN they send POST /api/admin/templates with body:
+ ```json
+ {
+ "name": "Company Dashboard",
+ "isDefault": true,
+ "permissionLevel": "view_only",
+ "targetGroups": []
+ }
+ ```
+- THEN the system MUST create a template with `isDefault: 1`
+- AND any previously default template MUST have its `isDefault` set to 0 via `clearDefaultTemplates()`
+- AND this template MUST be distributed to all users regardless of group membership
+
+#### Scenario: Non-admin user cannot create templates
+- GIVEN a regular (non-admin) Nextcloud user "alice"
+- WHEN she sends POST /api/admin/templates
+- THEN the system MUST return HTTP 403
+- AND the template MUST NOT be created
+
+#### Scenario: Create template with invalid permission level
+- GIVEN a Nextcloud admin user
+- WHEN they send POST /api/admin/templates with `permissionLevel: "super_admin"`
+- THEN the system MUST return HTTP 400 with a validation error
+- AND only `view_only`, `add_only`, and `full` MUST be accepted
+- NOTE: Permission level validation is NOT currently implemented -- any string is accepted
+
+#### Scenario: Create template with UUID generation
+- GIVEN a Nextcloud admin user
+- WHEN they create a new template
+- THEN the system MUST assign a UUID v4 via `Ramsey\Uuid\Uuid::uuid4()` (unlike user dashboards which use a custom UUID generator in `DashboardFactory`)
+- AND the UUID MUST be unique across all dashboards
+
+### REQ-TMPL-002: List Admin Templates
+
+Administrators MUST be able to view all existing templates with their configuration.
+
+#### Scenario: List all templates
+- GIVEN 3 admin templates exist: "Marketing Dashboard", "Company Dashboard" (default), "Engineering Dashboard"
+- WHEN the admin sends GET /api/admin/templates
+- THEN the system MUST return HTTP 200 with an array of all 3 templates
+- AND each template MUST include: id, uuid, name, description, targetGroups, isDefault, permissionLevel, gridColumns, type, basedOnTemplate, isActive, createdAt, updatedAt
+
+#### Scenario: Non-admin cannot list templates
+- GIVEN a regular user "alice"
+- WHEN she sends GET /api/admin/templates
+- THEN the system MUST return HTTP 403
+
+#### Scenario: Template list includes widget placement count
+- GIVEN the "Marketing Dashboard" template has 6 widget placements
+- WHEN the admin sends GET /api/admin/templates
+- THEN the template object SHOULD include a widget_count field showing 6
+- AND this helps admins understand the template's complexity at a glance
+- NOTE: Widget count is NOT currently included in the list response
+
+#### Scenario: Empty template list
+- GIVEN no admin templates have been created
+- WHEN the admin sends GET /api/admin/templates
+- THEN the system MUST return HTTP 200 with an empty array
+
+#### Scenario: Templates filtered from user dashboard list
+- GIVEN 3 admin templates and 2 user dashboards exist
+- WHEN user "alice" sends GET /api/dashboards
+- THEN the response MUST contain only her user dashboards
+- AND admin templates MUST NOT appear in the user's dashboard list
+
+### REQ-TMPL-003: Update Admin Template
+
+Administrators MUST be able to modify template configuration including name, description, target groups, permission level, and grid columns.
+
+#### Scenario: Update template target groups
+- GIVEN template id 1 targets groups ["marketing"]
+- WHEN the admin sends PUT /api/admin/templates/1 with body `{"targetGroups": ["marketing", "sales"]}`
+- THEN the system MUST update the targetGroups
+- AND newly targeted users (in "sales") MUST receive the template on their next dashboard load
+- AND existing user copies for "marketing" users MUST NOT be affected
+
+#### Scenario: Update template permission level
+- GIVEN template id 1 has `permissionLevel: "add_only"`
+- WHEN the admin sends PUT /api/admin/templates/1 with body `{"permissionLevel": "full"}`
+- THEN the template's permissionLevel MUST be updated to "full"
+- AND existing user copies MUST inherit the new permission level at runtime because `PermissionService::getEffectivePermissionLevel()` dynamically resolves from the source template via `basedOnTemplate`
+- NOTE: This means permission level changes DO propagate to existing copies. The resolution chain is: template's level -> dashboard's own level -> admin default.
+
+#### Scenario: Update template widget layout
+- GIVEN template id 1 has 4 widget placements
+- WHEN the admin adds a new widget to the template and repositions existing ones
+- THEN the template's placements MUST be updated
+- AND existing user copies MUST NOT be affected (placement copies are independent after creation)
+
+#### Scenario: Mark template as default
+- GIVEN template id 1 is not the default and template id 2 is the default
+- WHEN the admin sends PUT /api/admin/templates/1 with body `{"isDefault": true}`
+- THEN template 1 MUST become the default
+- AND template 2 MUST have `isDefault` set to 0 (false) -- enforced by `clearDefaultTemplates()` called before setting the new default
+
+#### Scenario: Non-admin cannot update templates
+- GIVEN template id 1 exists
+- WHEN regular user "alice" sends PUT /api/admin/templates/1
+- THEN the system MUST return HTTP 403
+
+### REQ-TMPL-004: Delete Admin Template
+
+Administrators MUST be able to delete templates, with proper cleanup of associated widget placements.
+
+#### Scenario: Delete a template with no user copies
+- GIVEN template id 1 has no user copies
+- WHEN the admin sends DELETE /api/admin/templates/1
+- THEN the system MUST delete the template
+- AND all template widget placements MUST be cascade-deleted via `placementMapper->deleteByDashboardId()`
+- AND the response MUST return HTTP 200
+
+#### Scenario: Delete a template with existing user copies
+- GIVEN template id 1 has been copied to 15 users
+- WHEN the admin sends DELETE /api/admin/templates/1
+- THEN the system MUST delete the template
+- AND existing user copies MUST NOT be affected (they are independent dashboards)
+- AND user copies with `basedOnTemplate: 1` will fall back to their own `permissionLevel` or admin default since the template no longer exists (caught by `DoesNotExistException` in `getEffectivePermissionLevel()`)
+
+#### Scenario: Non-admin cannot delete templates
+- GIVEN template id 1 exists
+- WHEN regular user "alice" sends DELETE /api/admin/templates/1
+- THEN the system MUST return HTTP 403
+
+#### Scenario: Delete non-template dashboard via template endpoint
+- GIVEN dashboard id 5 is a user dashboard (type: "user"), not an admin template
+- WHEN the admin sends DELETE /api/admin/templates/5
+- THEN the system MUST throw an exception indicating "Not an admin template"
+- AND the dashboard MUST NOT be deleted
+
+#### Scenario: Delete the default template
+- GIVEN template id 1 is the default template (`isDefault: true`)
+- WHEN the admin deletes template id 1
+- THEN the system MUST delete the template
+- AND no template MUST be the default afterward (this is allowed)
+- AND new users without a group-targeted template will get no template on first access
+
+### REQ-TMPL-005: Template Distribution on First Access
+
+When a user accesses MyDash for the first time, the system MUST create personal copies of matching templates via the `DashboardResolver` chain.
+
+#### Scenario: First-time user receives default template
+- GIVEN a default template "Company Dashboard" exists with `isDefault: true` and 5 widget placements (3 compulsory)
+- AND user "alice" has never opened MyDash
+- WHEN alice navigates to MyDash (triggers GET /api/dashboard)
+- THEN the system MUST create a personal dashboard for alice as a copy of the template
+- AND the copy MUST have `type: "user"` and `userId: "alice"`
+- AND the copy MUST inherit the template's permissionLevel
+- AND the copy MUST include all 5 widget placements with their positions, sizes, and isCompulsory flags
+- AND `basedOnTemplate` on the copy MUST reference the template's ID
+- AND the copy MUST be set as alice's active dashboard
+
+#### Scenario: First-time user receives group-targeted template
+- GIVEN template "Marketing Dashboard" targets groups ["marketing"]
+- AND user "bob" is a member of the "marketing" group
+- AND bob has never opened MyDash
+- WHEN bob navigates to MyDash
+- THEN the system MUST create a personal copy of "Marketing Dashboard" for bob
+- NOTE: `TemplateService::getApplicableTemplate()` returns only ONE template (the first matching group-targeted template takes priority over the default). Multiple template distribution is NOT implemented.
+
+#### Scenario: First-time user not in any target group
+- GIVEN template "Marketing Dashboard" targets groups ["marketing"]
+- AND no default template exists
+- AND user "carol" is only in the "engineering" group
+- WHEN carol navigates to MyDash
+- THEN the system MUST NOT create any dashboard for carol from the marketing template
+- AND if `allowUserDashboards` is true, the system MUST create a default "My Dashboard" with recommendations and activity widgets
+
+#### Scenario: Template already distributed to user
+- GIVEN user "alice" already has a personal copy of template "Company Dashboard"
+- WHEN alice navigates to MyDash again
+- THEN the system MUST NOT create a duplicate copy
+- AND `DashboardResolver::tryGetActiveDashboard()` MUST find her existing dashboard first
+
+#### Scenario: Multiple templates match the user
+- GIVEN templates "Company Dashboard" (default) and "Marketing Dashboard" (targets marketing group)
+- AND user "alice" is in the "marketing" group
+- WHEN alice navigates to MyDash for the first time
+- THEN alice MUST receive a copy of "Marketing Dashboard" (group-targeted template takes priority over default)
+- NOTE: Only ONE template per first-access. Group-targeted templates are evaluated first; the default template is the fallback.
+
+### REQ-TMPL-006: Template Copy Independence
+
+User copies of templates MUST be fully independent from the source template after creation, with the exception of permission level resolution.
+
+#### Scenario: User modifies their template copy
+- GIVEN user "alice" has a copy of "Marketing Dashboard" with `permissionLevel: "add_only"`
+- WHEN she adds a new widget to her copy
+- THEN the template MUST NOT be modified
+- AND other users' copies MUST NOT be affected
+
+#### Scenario: Admin updates template after distribution
+- GIVEN template "Marketing Dashboard" has been copied to 10 users
+- WHEN the admin adds a new widget to the template
+- THEN existing user copies MUST NOT receive the new widget
+- AND only new copies created after the change MUST include the new widget
+
+#### Scenario: Admin deletes template after distribution
+- GIVEN template "Marketing Dashboard" has been copied to user "alice"
+- WHEN the admin deletes the template
+- THEN alice's copy MUST continue to function normally
+- AND alice's dashboard MUST retain all placements
+- AND permission resolution MUST fall back to the dashboard's own `permissionLevel` (template lookup caught by `DoesNotExistException`)
+
+### REQ-TMPL-007: Template Widget Management
+
+Administrators MUST be able to manage widget placements on templates using the same API as regular dashboards.
+
+#### Scenario: Add widget to template
+- GIVEN template id 1 exists
+- WHEN the admin sends POST /api/dashboard/1/widgets with widget data including `isCompulsory: 1`
+- THEN the widget placement MUST be created on the template
+- AND `isCompulsory` MUST be set to 1
+
+#### Scenario: Remove widget from template
+- GIVEN template id 1 has widget placement id 20
+- WHEN the admin sends DELETE /api/widgets/20
+- THEN the placement MUST be removed from the template
+- AND existing user copies MUST NOT be affected
+
+#### Scenario: Configure template grid layout
+- GIVEN template id 1 exists
+- WHEN the admin arranges widgets on the template via the grid
+- THEN the positions MUST be saved as the template's widget placements
+- AND new user copies MUST receive these exact positions
+
+#### Scenario: Template placements include tile data
+- GIVEN the admin adds a tile placement to template id 1 with inline tile data (tileTitle, tileIcon, etc.)
+- WHEN the template is distributed to users
+- THEN the tile placement MUST be cloned with all inline tile data via `clonePlacement()`
+- AND the user copy MUST render the tile identically to the template
+
+### REQ-TMPL-008: Only One Default Template
+
+The system MUST enforce that at most one template is marked as the default at any time.
+
+#### Scenario: Set a template as default when no default exists
+- GIVEN no template has `isDefault: true`
+- WHEN the admin creates or updates a template with `isDefault: true`
+- THEN that template MUST become the default
+- AND no other templates MUST be affected
+
+#### Scenario: Set a template as default when another is already default
+- GIVEN template "Company Dashboard" has `isDefault: true`
+- WHEN the admin sets template "New Dashboard" as the default
+- THEN "New Dashboard" MUST become the default
+- AND "Company Dashboard" MUST have `isDefault` set to 0 (false)
+- AND `clearDefaultTemplates()` MUST be called before setting the new default
+
+#### Scenario: Remove default status from the only default template
+- GIVEN template "Company Dashboard" has `isDefault: true`
+- WHEN the admin sends PUT /api/admin/templates/1 with body `{"isDefault": false}`
+- THEN the template MUST have `isDefault` set to 0 (false)
+- AND no template MUST be the default (this is allowed)
+
+### REQ-TMPL-009: Get Template with Placements
+
+Administrators MUST be able to retrieve a specific template along with all its widget placements for editing.
+
+#### Scenario: Get template with its placements
+- GIVEN template id 1 has 6 widget placements
+- WHEN the admin sends GET /api/admin/templates/1
+- THEN the system MUST return the template object and an array of its 6 placements
+- AND the response MUST include both the template entity and its placements as separate keys
+
+#### Scenario: Get non-template dashboard via template endpoint
+- GIVEN dashboard id 5 is a user dashboard (type: "user")
+- WHEN the admin sends GET /api/admin/templates/5
+- THEN the system MUST throw an exception indicating "Not an admin template"
+
+#### Scenario: Get template with no placements
+- GIVEN template id 2 exists but has no widget placements
+- WHEN the admin sends GET /api/admin/templates/2
+- THEN the system MUST return the template object with an empty placements array
+
+### REQ-TMPL-010: Template Group Resolution
+
+Template distribution MUST use Nextcloud's `IGroupManager` API to resolve user group memberships accurately.
+
+#### Scenario: User added to a target group after template creation
+- GIVEN template "Marketing Dashboard" targets groups ["marketing"]
+- AND user "alice" was not in the "marketing" group when the template was created
+- AND alice is later added to the "marketing" group
+- WHEN alice opens MyDash for the first time
+- THEN the system MUST distribute the "Marketing Dashboard" template to alice
+- AND group membership MUST be checked at access time, not at template creation time
+
+#### Scenario: User removed from a target group after receiving template
+- GIVEN user "alice" received a copy of "Marketing Dashboard" while in the "marketing" group
+- AND alice is later removed from the "marketing" group
+- WHEN alice continues to use MyDash
+- THEN alice's copy MUST continue to function normally
+- AND the copy MUST NOT be deleted or revoked
+
+#### Scenario: Template targets non-existent group
+- GIVEN template "Test Dashboard" targets groups ["nonexistent-group"]
+- WHEN any user opens MyDash
+- THEN the template MUST NOT match any user (no user is in a non-existent group)
+- AND the system MUST NOT throw errors during group resolution
+
+### REQ-TMPL-011: Template Administration UI
+
+The admin settings page MUST provide a UI for managing templates.
+
+#### Scenario: Template list in admin settings
+- GIVEN the admin opens the MyDash admin settings page
+- THEN a template management section MUST be displayed
+- AND all existing templates MUST be listed with their name, target groups, and default status
+
+#### Scenario: Create template via admin UI
+- GIVEN the admin clicks "Create Template" in the admin settings
+- THEN a modal dialog MUST appear with fields for name, description, target groups, permission level, and default status
+- AND the admin MUST be able to save the new template
+
+#### Scenario: Group selection in template editor
+- GIVEN the admin opens the template editor
+- THEN a group selector MUST allow selecting from available Nextcloud groups
+- NOTE: The current implementation uses `NcSelectTags` but `availableGroups` is hardcoded to an empty array. Groups are NOT fetched from the server.
+
+## Non-Functional Requirements
+
+- **Performance**: Template distribution (copying placements) MUST complete within 2 seconds per user, even for templates with 20+ widget placements. The first-access check MUST add no more than 200ms to the initial dashboard load.
+- **Data integrity**: Template copies MUST be atomic -- if any placement fails to copy, the entire copy operation MUST be rolled back. The single-default invariant MUST be enforced at the database/service level.
+- **Scalability**: Template distribution MUST work efficiently for organizations with 1000+ users. The system SHOULD NOT eagerly copy templates to all users; copies MUST be created on-demand at first access.
+- **Security**: Only Nextcloud admin users MUST be able to create, update, or delete templates. Group membership checks MUST use Nextcloud's `IGroupManager` API.
+- **Localization**: Admin template management UI labels and error messages MUST support English and Dutch.
+
+### Current Implementation Status
+
+**Fully implemented:**
+- REQ-TMPL-001 (Create Admin Template): `AdminTemplateService::createTemplate()` in `lib/Service/AdminTemplateService.php` creates dashboards with `type: "admin_template"`, `userId: null`, default `gridColumns: 12`. Default clearing via `clearDefaultTemplates()` is implemented.
+- REQ-TMPL-002 (List Admin Templates): `AdminTemplateService::listTemplates()` calls `DashboardMapper::findAdminTemplates()`.
+- REQ-TMPL-003 (Update Admin Template): `AdminTemplateService::updateTemplate()` with `applyTemplateUpdates()` handles name, description, targetGroups, permissionLevel, isDefault, gridColumns.
+- REQ-TMPL-004 (Delete Admin Template): `AdminTemplateService::deleteTemplate()` deletes placements first via `placementMapper->deleteByDashboardId()`, then deletes the template.
+- REQ-TMPL-005 (Template Distribution): `TemplateService::getApplicableTemplate()` checks group membership via `IGroupManager::getUserGroupIds()`. `createDashboardFromTemplate()` copies all placements including `isCompulsory` flags.
+- REQ-TMPL-006 (Template Copy Independence): Copies are independent -- `buildDashboardFromTemplate()` creates a new Dashboard entity, `copyTemplatePlacements()` creates new WidgetPlacement entities.
+- REQ-TMPL-007 (Template Widget Management): Templates share the same widget placement API as regular dashboards.
+- REQ-TMPL-008 (Only One Default): `clearDefaultTemplates()` on DashboardMapper ensures single default.
+- REQ-TMPL-009 (Get Template with Placements): `AdminTemplateService::getTemplateWithPlacements()` returns template + placements.
+
+**Not yet implemented:**
+- REQ-TMPL-001 validation: No server-side validation for `permissionLevel` values.
+- REQ-TMPL-002 widget_count: Template list response does NOT include a widget placement count.
+- REQ-TMPL-005 multi-template distribution: Only ONE template is distributed per first-access.
+- REQ-TMPL-011 group fetching: `AdminSettings.vue` group selector has `availableGroups` hardcoded to empty array.
+
+### Standards & References
+- Nextcloud Group API: `OCP\IGroupManager::getUserGroupIds()`
+- Nextcloud User API: `OCP\IUserManager::get()`
+- WCAG 2.1 AA for the admin template management UI (modal dialogs, form fields)
+- WAI-ARIA: Modal dialog accessibility via `NcModal` component
diff --git a/openspec/specs/admin-templates/tasks.md b/openspec/changes/archive/2026-03-21-admin-templates/specs/admin-templates/tasks.md
similarity index 100%
rename from openspec/specs/admin-templates/tasks.md
rename to openspec/changes/archive/2026-03-21-admin-templates/specs/admin-templates/tasks.md
diff --git a/openspec/changes/archive/2026-03-21-admin-templates/tasks.md b/openspec/changes/archive/2026-03-21-admin-templates/tasks.md
new file mode 100644
index 00000000..e79497d6
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-templates/tasks.md
@@ -0,0 +1,13 @@
+# Admin Templates - Tasks
+
+## Tasks
+
+- [x] TASK-TMPL-001: Implement TemplateService with distribution logic
+- [x] TASK-TMPL-002: Implement AdminTemplateService for template CRUD
+- [x] TASK-TMPL-003: Implement template endpoints in AdminController
+- [x] TASK-TMPL-004: Implement dashboard creation from template with placement cloning
+- [x] TASK-TMPL-005: Implement group-based template matching
+- [x] TASK-TMPL-006: Implement default template management
+- [x] TASK-TMPL-007: Write unit tests for TemplateService (ADR-009)
+- [x] TASK-TMPL-008: Write feature documentation and screenshots (ADR-010)
+- [x] TASK-TMPL-009: Verify i18n support for template UI strings (ADR-005)
diff --git a/openspec/changes/archive/2026-03-21-conditional-visibility/.openspec.yaml b/openspec/changes/archive/2026-03-21-conditional-visibility/.openspec.yaml
new file mode 100644
index 00000000..d8b0ed03
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-conditional-visibility/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-conditional-visibility/design.md b/openspec/changes/archive/2026-03-21-conditional-visibility/design.md
new file mode 100644
index 00000000..3c61ee89
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-conditional-visibility/design.md
@@ -0,0 +1,30 @@
+# Conditional Visibility - Design Document
+
+## Architecture
+
+### Backend
+- **Entity**: `Db\ConditionalRule` - Rule type, config JSON, include/exclude flag
+- **Mapper**: `Db\ConditionalRuleMapper` - CRUD, findByPlacementId
+- **Service**: `Service\ConditionalService` - Rule CRUD and visibility evaluation
+- **Service**: `Service\RuleEvaluatorService` - Evaluates individual rules by type
+- **Service**: `Service\VisibilityChecker` - Orchestrates include/exclude logic
+- **Service**: `Service\UserAttributeResolver` - Resolves user attributes for rules
+- **Controller**: `Controller\RuleApiController` - REST API for rule management
+
+### Rule Types
+- **group**: Match user's Nextcloud groups against target groups
+- **time**: Match current time against startTime/endTime and optional days
+- **date**: Match current date against startDate/endDate range
+- **attribute**: Match user attribute against value with operator
+
+### Visibility Logic
+- Include rules: OR logic (at least one must match to show)
+- Exclude rules: AND logic (any match hides the widget)
+- No rules + isVisible=1: always shown
+- isVisible=0: always hidden (overrides rules)
+
+### Key Design Decisions
+- Rules stored per widget placement (not per dashboard)
+- No separate visibility state string - uses isVisible flag + rule existence
+- Time evaluation uses server DateTime (no user timezone support)
+- Rule config stored as JSON blob with type-specific schema
diff --git a/openspec/changes/archive/2026-03-21-conditional-visibility/proposal.md b/openspec/changes/archive/2026-03-21-conditional-visibility/proposal.md
new file mode 100644
index 00000000..7a473a63
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-conditional-visibility/proposal.md
@@ -0,0 +1,18 @@
+# Conditional Visibility Specification
+
+## Problem
+Conditional visibility allows widget placements to be shown or hidden based on dynamic rules. This enables dashboards that adapt to the user's context -- for example, showing a "Team Updates" widget only during business hours, displaying a "Holiday Schedule" widget only in December, or restricting certain widgets to specific user groups. Rules are evaluated at render time and can be inclusive (show when matched) or exclusive (hide when matched). Include rules use OR logic (at least one must match); exclude rules use AND logic (any match hides the widget).
+
+## Proposed Solution
+Implement Conditional Visibility Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the conditional-visibility specification.
+
+## Success Criteria
+- Create a group-based inclusion rule
+- Create a time-based exclusion rule
+- Create a date-based inclusion rule
+- Create an attribute-based rule
+- Create rule with invalid ruleType
diff --git a/openspec/specs/conditional-visibility/design.md b/openspec/changes/archive/2026-03-21-conditional-visibility/specs/conditional-visibility/design.md
similarity index 100%
rename from openspec/specs/conditional-visibility/design.md
rename to openspec/changes/archive/2026-03-21-conditional-visibility/specs/conditional-visibility/design.md
diff --git a/openspec/changes/archive/2026-03-21-conditional-visibility/specs/conditional-visibility/spec.md b/openspec/changes/archive/2026-03-21-conditional-visibility/specs/conditional-visibility/spec.md
new file mode 100644
index 00000000..48103ad4
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-conditional-visibility/specs/conditional-visibility/spec.md
@@ -0,0 +1,470 @@
+---
+status: reviewed
+---
+
+# Conditional Visibility Specification
+
+## Purpose
+
+Conditional visibility allows widget placements to be shown or hidden based on dynamic rules. This enables dashboards that adapt to the user's context -- for example, showing a "Team Updates" widget only during business hours, displaying a "Holiday Schedule" widget only in December, or restricting certain widgets to specific user groups. Rules are evaluated at render time and can be inclusive (show when matched) or exclusive (hide when matched). Include rules use OR logic (at least one must match); exclude rules use AND logic (any match hides the widget).
+
+## Data Model
+
+### Conditional Rules (oc_mydash_conditional_rules)
+- **id**: Auto-increment integer primary key
+- **widgetPlacementId**: Foreign key to oc_mydash_widget_placements (INTEGER)
+- **ruleType**: One of `group`, `time`, `date`, `attribute` (STRING)
+- **ruleConfig**: JSON blob containing the rule parameters, varies by ruleType (STRING, nullable). Stored via `json_encode()`, accessed via `getRuleConfigArray()`.
+- **isInclude**: Boolean -- if true, the rule is an inclusion rule (show when matched); if false, it is an exclusion rule (hide when matched)
+- **createdAt**: Timestamp (DATETIME)
+
+NOTE: There is no separate `visibility: "conditional"` string state on widget placements. The visibility model works as follows: if `isVisible` is 0 (false), the widget is always hidden. If `isVisible` is 1 (true) AND ConditionalRule records exist for the placement, the ConditionalService evaluates those rules via VisibilityChecker. If no rules exist and `isVisible` is 1, the widget is always shown.
+
+### Rule Config Schemas by Type
+
+**group** ruleConfig:
+```json
+{"groups": ["admin", "marketing"]}
+```
+
+**time** ruleConfig:
+```json
+{"startTime": "09:00", "endTime": "17:00", "days": ["mon", "tue", "wed", "thu", "fri"]}
+```
+NOTE: Time rules use camelCase keys (`startTime`, `endTime`) and support an optional `days` array (3-letter lowercase day abbreviations). The `timezone` field is NOT supported -- time evaluation uses the server's DateTime (`new DateTime()`), not a user-specified timezone.
+
+**date** ruleConfig:
+```json
+{"startDate": "2026-12-01", "endDate": "2026-12-31"}
+```
+NOTE: Date rules use camelCase keys (`startDate`, `endDate`). Both fields are optional -- omitting `startDate` matches from the beginning of time, omitting `endDate` matches indefinitely.
+
+**attribute** ruleConfig:
+```json
+{"attribute": "language", "operator": "equals", "value": "nl"}
+```
+
+## Requirements
+
+### REQ-VIS-001: Create Conditional Rule
+
+Users MUST be able to add conditional visibility rules to widget placements on dashboards they own.
+
+#### Scenario: Create a group-based inclusion rule
+- GIVEN user "alice" has widget placement id 10 on her dashboard
+- WHEN she sends POST /api/widgets/10/rules with body:
+ ```json
+ {
+ "ruleType": "group",
+ "ruleConfig": {"groups": ["marketing", "sales"]},
+ "isInclude": true
+ }
+ ```
+- THEN the system MUST create a conditional rule linked to placement 10
+- AND the response MUST return HTTP 201 with the full rule object
+- NOTE: Adding a rule does NOT change the placement's `isVisible` field. The ConditionalService automatically evaluates rules when `isVisible` is 1 and rules exist.
+
+#### Scenario: Create a time-based exclusion rule
+- GIVEN widget placement id 10 on alice's dashboard
+- WHEN she sends POST /api/widgets/10/rules with body:
+ ```json
+ {
+ "ruleType": "time",
+ "ruleConfig": {"startTime": "18:00", "endTime": "08:00"},
+ "isInclude": false
+ }
+ ```
+- THEN the system MUST create an exclusion rule that hides the widget when the current server time matches
+- AND `isInclude: false` MUST mean the widget is hidden when the rule matches
+- NOTE: The current time comparison uses simple string comparison (`>=` and `<=`) and does NOT handle midnight-spanning windows correctly (startTime > endTime).
+
+#### Scenario: Create a date-based inclusion rule
+- GIVEN widget placement id 10 on alice's dashboard
+- WHEN she sends POST /api/widgets/10/rules with body:
+ ```json
+ {
+ "ruleType": "date",
+ "ruleConfig": {"startDate": "2026-12-01", "endDate": "2026-12-31"},
+ "isInclude": true
+ }
+ ```
+- THEN the system MUST create a rule that shows the widget only during December 2026
+
+#### Scenario: Create an attribute-based rule
+- GIVEN widget placement id 10 on alice's dashboard
+- WHEN she sends POST /api/widgets/10/rules with body:
+ ```json
+ {
+ "ruleType": "attribute",
+ "ruleConfig": {"attribute": "language", "operator": "equals", "value": "nl"},
+ "isInclude": true
+ }
+ ```
+- THEN the system MUST create a rule that shows the widget only for users with language set to "nl"
+
+#### Scenario: Create rule with invalid ruleType
+- GIVEN widget placement id 10 on alice's dashboard
+- WHEN she sends POST /api/widgets/10/rules with body `{"ruleType": "weather", "ruleConfig": {}, "isInclude": true}`
+- THEN the system SHOULD return HTTP 400 with an error indicating the ruleType is invalid
+- AND only `group`, `time`, `date`, and `attribute` SHOULD be accepted
+- NOTE: Rule type validation is NOT currently implemented -- any string value is accepted. Unknown rule types evaluate to `false` via the `default => false` case in `evaluateRule()`.
+
+#### Scenario: Create rule on another user's placement
+- GIVEN widget placement id 10 belongs to alice's dashboard
+- WHEN user "bob" sends POST /api/widgets/10/rules
+- THEN the system MUST return HTTP 403 (via `PermissionService::verifyPlacementOwnership()`)
+
+### REQ-VIS-002: List Conditional Rules
+
+Users MUST be able to retrieve all conditional rules for a widget placement they own.
+
+#### Scenario: List rules for a placement with multiple rules
+- GIVEN widget placement id 10 has 3 conditional rules:
+ - Rule 1: group-based, include, groups: ["marketing"]
+ - Rule 2: time-based, include, 09:00-17:00
+ - Rule 3: date-based, exclude, 2026-07-01 to 2026-07-31
+- WHEN the user sends GET /api/widgets/10/rules
+- THEN the system MUST return HTTP 200 with an array of all 3 rules
+- AND each rule MUST include: id, widgetPlacementId, ruleType, ruleConfig, isInclude, createdAt
+
+#### Scenario: List rules for a placement with no rules
+- GIVEN widget placement id 11 has no conditional rules
+- WHEN the user sends GET /api/widgets/11/rules
+- THEN the system MUST return HTTP 200 with an empty array
+
+#### Scenario: List rules for another user's placement
+- GIVEN widget placement id 10 belongs to alice's dashboard
+- WHEN user "bob" sends GET /api/widgets/10/rules
+- THEN the system MUST return HTTP 403 (via `verifyPlacementOwnership()`)
+
+### REQ-VIS-003: Update Conditional Rule
+
+Users MUST be able to modify existing conditional rules on placements they own.
+
+#### Scenario: Update rule configuration
+- GIVEN conditional rule id 5 with `ruleConfig: {"groups": ["marketing"]}`
+- WHEN the user sends PUT /api/rules/5 with body:
+ ```json
+ {"ruleConfig": {"groups": ["marketing", "sales", "management"]}}
+ ```
+- THEN the system MUST update the ruleConfig
+- AND the response MUST return HTTP 200 with the updated rule
+
+#### Scenario: Change rule from inclusion to exclusion
+- GIVEN conditional rule id 5 with `isInclude: true`
+- WHEN the user sends PUT /api/rules/5 with body `{"isInclude": false}`
+- THEN the system MUST update the rule to an exclusion rule
+- AND the widget MUST now be hidden when this rule matches
+
+#### Scenario: Update rule type
+- GIVEN conditional rule id 5 with `ruleType: "group"`
+- WHEN the user sends PUT /api/rules/5 with body:
+ ```json
+ {"ruleType": "time", "ruleConfig": {"startTime": "09:00", "endTime": "17:00"}}
+ ```
+- THEN the system MUST update both the ruleType and ruleConfig
+- AND the old ruleConfig MUST be fully replaced (not merged)
+
+#### Scenario: Update another user's rule
+- GIVEN rule id 5 belongs to a placement on alice's dashboard
+- WHEN user "bob" sends PUT /api/rules/5
+- THEN the system MUST return HTTP 403
+- NOTE: Ownership verification for update is NOT currently implemented in `RuleApiController`. Only `addRule()` and `getRules()` call `verifyPlacementOwnership()`.
+
+#### Scenario: Partial update preserves unspecified fields
+- GIVEN conditional rule id 5 with `ruleType: "group"`, `ruleConfig: {"groups": ["marketing"]}`, `isInclude: true`
+- WHEN the user sends PUT /api/rules/5 with body `{"isInclude": false}`
+- THEN only `isInclude` MUST be updated to `false`
+- AND `ruleType` and `ruleConfig` MUST remain unchanged
+
+### REQ-VIS-004: Delete Conditional Rule
+
+Users MUST be able to remove conditional rules from their widget placements.
+
+#### Scenario: Delete a rule
+- GIVEN widget placement id 10 has 3 conditional rules, including rule id 5
+- WHEN the user sends DELETE /api/rules/5
+- THEN the system MUST delete rule 5
+- AND the response MUST return HTTP 200 with `{"status": "ok"}`
+- AND placement 10 MUST still have 2 remaining rules
+
+#### Scenario: Delete the last rule on a placement
+- GIVEN widget placement id 10 has only 1 conditional rule (id 5)
+- AND the placement has `isVisible: 1`
+- WHEN the user sends DELETE /api/rules/5
+- THEN the system MUST delete the rule
+- AND the placement's `isVisible` remains 1 (unchanged)
+- AND since no rules exist, the widget will always be shown (ConditionalService returns true when no rules exist)
+- NOTE: There is no automatic state change when the last rule is deleted.
+
+#### Scenario: Delete another user's rule
+- GIVEN rule id 5 belongs to a placement on alice's dashboard
+- WHEN user "bob" sends DELETE /api/rules/5
+- THEN the system MUST return HTTP 403
+- NOTE: Ownership verification for delete is NOT currently implemented in `RuleApiController`.
+
+### REQ-VIS-005: Group-Based Rule Evaluation
+
+Group-based rules MUST show or hide widgets based on the current user's Nextcloud group memberships, resolved via `IGroupManager::getUserGroupIds()`.
+
+#### Scenario: User is in a matching group (inclusion rule)
+- GIVEN widget placement id 10 has a group inclusion rule with `groups: ["marketing", "sales"]`
+- AND user "alice" is a member of the "marketing" group
+- WHEN the dashboard is rendered for alice
+- THEN the widget MUST be visible (rule matches, isInclude=true means show)
+
+#### Scenario: User is not in any matching group (inclusion rule)
+- GIVEN widget placement id 10 has a group inclusion rule with `groups: ["marketing", "sales"]`
+- AND user "bob" is a member of only the "engineering" group
+- WHEN the dashboard is rendered for bob
+- THEN the widget MUST be hidden (rule does not match, isInclude=true means only show on match)
+
+#### Scenario: User is in a matching group (exclusion rule)
+- GIVEN widget placement id 10 has a group exclusion rule with `groups: ["contractors"]`
+- AND user "carol" is a member of the "contractors" group
+- WHEN the dashboard is rendered for carol
+- THEN the widget MUST be hidden (rule matches, isInclude=false means hide on match)
+
+#### Scenario: User in multiple groups with partial match
+- GIVEN widget placement id 10 has a group inclusion rule with `groups: ["marketing"]`
+- AND user "dave" is a member of groups ["engineering", "marketing", "all-staff"]
+- WHEN the dashboard is rendered for dave
+- THEN the widget MUST be visible (user is in at least one of the specified groups via `array_intersect()`)
+
+#### Scenario: Empty groups array in rule config
+- GIVEN widget placement id 10 has a group inclusion rule with `groups: []`
+- WHEN the dashboard is rendered
+- THEN the rule MUST evaluate as not matching (empty target groups returns false)
+- AND the widget MUST be hidden (no include rule matches)
+
+### REQ-VIS-006: Time-Based Rule Evaluation
+
+Time-based rules MUST show or hide widgets based on the current time of day using the server's local time via `new DateTime()`.
+
+#### Scenario: Current time is within the time window (inclusion rule)
+- GIVEN widget placement id 10 has a time inclusion rule with `startTime: "09:00", endTime: "17:00"`
+- AND the current server time is 14:30
+- WHEN the dashboard is rendered
+- THEN the widget MUST be visible
+
+#### Scenario: Current time is outside the time window (inclusion rule)
+- GIVEN widget placement id 10 has a time inclusion rule with `startTime: "09:00", endTime: "17:00"`
+- AND the current server time is 20:00
+- WHEN the dashboard is rendered
+- THEN the widget MUST be hidden
+
+#### Scenario: Time window spanning midnight (KNOWN LIMITATION)
+- GIVEN widget placement id 10 has a time inclusion rule with `startTime: "22:00", endTime: "06:00"`
+- AND the current server time is 02:00
+- WHEN the dashboard is rendered
+- THEN the widget SHOULD be visible (the time window wraps around midnight)
+- NOTE: The current implementation uses simple string comparison (`currentTime >= startTime && currentTime <= endTime`) which does NOT handle midnight-spanning windows. This is a known limitation.
+
+#### Scenario: Time evaluation uses server timezone (NOT configurable)
+- GIVEN a time rule with `startTime: "09:00", endTime: "17:00"` (no timezone field)
+- AND the server is in UTC where it is 08:00 UTC
+- WHEN the dashboard is rendered
+- THEN the rule MUST evaluate using the server's timezone (UTC in this case)
+- AND the widget MUST be hidden (08:00 is before 09:00)
+- NOTE: The `timezone` field in ruleConfig is NOT supported. `RuleEvaluatorService` creates `new DateTime()` which uses the server's default timezone.
+
+#### Scenario: Time rule with day-of-week filter
+- GIVEN widget placement id 10 has a time inclusion rule with `startTime: "09:00", endTime: "17:00", days: ["mon", "tue", "wed", "thu", "fri"]`
+- AND the current server day is "sat" (Saturday)
+- WHEN the dashboard is rendered
+- THEN the widget MUST be hidden (Saturday is not in the allowed days list)
+- AND the time check is only performed if the day check passes
+
+#### Scenario: Time rule without day filter
+- GIVEN a time inclusion rule with `startTime: "09:00", endTime: "17:00"` and no `days` field
+- AND the current day is Saturday at 10:00
+- WHEN the dashboard is rendered
+- THEN the widget MUST be visible (no day filter means all days are allowed)
+
+#### Scenario: Time rule with default start and end times
+- GIVEN a time inclusion rule with neither `startTime` nor `endTime` specified
+- WHEN the rule is evaluated
+- THEN `startTime` MUST default to `"00:00"` and `endTime` MUST default to `"23:59"`
+- AND the rule MUST match at any time of day
+
+### REQ-VIS-007: Date-Based Rule Evaluation
+
+Date-based rules MUST show or hide widgets based on the current date, with optional open-ended ranges.
+
+#### Scenario: Current date is within the date range (inclusion rule)
+- GIVEN widget placement id 10 has a date inclusion rule with `startDate: "2026-12-01", endDate: "2026-12-31"`
+- AND today is 2026-12-15
+- WHEN the dashboard is rendered
+- THEN the widget MUST be visible
+
+#### Scenario: Current date is outside the date range (inclusion rule)
+- GIVEN widget placement id 10 has a date inclusion rule with `startDate: "2026-12-01", endDate: "2026-12-31"`
+- AND today is 2026-11-15
+- WHEN the dashboard is rendered
+- THEN the widget MUST be hidden
+
+#### Scenario: Open-ended date range (no end date)
+- GIVEN a date inclusion rule with `startDate: "2026-01-01"` and no `endDate`
+- AND today is 2027-06-15
+- WHEN the dashboard is rendered
+- THEN the widget MUST be visible (no endDate means the rule matches indefinitely from the start date)
+
+#### Scenario: Open-ended date range (no start date)
+- GIVEN a date inclusion rule with `endDate: "2026-12-31"` and no `startDate`
+- AND today is 2025-06-15
+- WHEN the dashboard is rendered
+- THEN the widget MUST be visible (no startDate means matches from the beginning of time)
+
+#### Scenario: Date range boundary inclusivity
+- GIVEN a date inclusion rule with `startDate: "2026-12-01", endDate: "2026-12-31"`
+- AND today is 2026-12-01 (the start date)
+- WHEN the dashboard is rendered
+- THEN the widget MUST be visible (both start and end dates are inclusive -- uses `<` and `>` comparisons for exclusion)
+
+### REQ-VIS-008: Attribute-Based Rule Evaluation
+
+Attribute-based rules MUST show or hide widgets based on user profile attributes, resolved by `UserAttributeResolver`.
+
+#### Scenario: Attribute matches with "equals" operator
+- GIVEN widget placement id 10 has an attribute inclusion rule with `attribute: "language", operator: "equals", value: "nl"`
+- AND user "alice" has her language set to "nl"
+- WHEN the dashboard is rendered for alice
+- THEN the widget MUST be visible
+
+#### Scenario: Attribute does not match with "equals" operator
+- GIVEN widget placement id 10 has an attribute inclusion rule with `attribute: "language", operator: "equals", value: "nl"`
+- AND user "bob" has his language set to "en"
+- WHEN the dashboard is rendered for bob
+- THEN the widget MUST be hidden
+
+#### Scenario: Attribute with "not_equals" operator
+- GIVEN an attribute inclusion rule with `attribute: "language", operator: "not_equals", value: "en"`
+- AND user "carol" has her language set to "de"
+- WHEN the dashboard is rendered for carol
+- THEN the widget MUST be visible (language "de" is not equal to "en")
+
+#### Scenario: Attribute with "contains" operator
+- GIVEN an attribute inclusion rule with `attribute: "email", operator: "contains", value: "@company.com"`
+- AND user "dave" has email "dave@company.com"
+- WHEN the dashboard is rendered for dave
+- THEN the widget MUST be visible
+
+#### Scenario: Non-existent attribute
+- GIVEN an attribute rule referencing `attribute: "department"` which does not exist for the current user
+- WHEN the dashboard is rendered
+- THEN `UserAttributeResolver` MUST return null
+- AND the rule MUST evaluate as not matching (evaluateAttributeRule returns false when userValue is null)
+- AND for inclusion rules, the widget MUST be hidden
+- AND for exclusion rules, the widget MUST be visible
+
+### REQ-VIS-009: Multiple Rule Combination
+
+When a widget placement has multiple conditional rules, they MUST be combined using the VisibilityChecker logic: include rules use OR (at least one must match), exclude rules use AND (any match hides).
+
+#### Scenario: Multiple include rules -- at least one matches
+- GIVEN widget placement id 10 has two inclusion rules:
+ - Rule 1: group rule, groups: ["marketing"] -- user is NOT in marketing
+ - Rule 2: group rule, groups: ["sales"] -- user IS in sales
+- WHEN the dashboard is rendered
+- THEN the widget MUST be visible (at least one include rule matches -- OR logic)
+
+#### Scenario: Multiple include rules -- none match
+- GIVEN widget placement id 10 has two inclusion rules:
+ - Rule 1: group rule, groups: ["marketing"] -- user is NOT in marketing
+ - Rule 2: time rule, 09:00-17:00 -- current time is 20:00
+- WHEN the dashboard is rendered
+- THEN the widget MUST be hidden (no include rule matches)
+
+#### Scenario: Exclude rule overrides include
+- GIVEN widget placement id 10 has:
+ - Rule 1: group inclusion rule, groups: ["marketing"] -- user is in marketing (matches)
+ - Rule 2: date exclusion rule, 2026-07-01 to 2026-07-31 -- today is 2026-07-15 (matches)
+- WHEN the dashboard is rendered
+- THEN the widget MUST be hidden
+- AND the evaluation logic is: first check include rules (OR -- at least one must match), then check exclude rules (AND -- if ANY exclude rule matches, hide)
+
+#### Scenario: No rules on placement with isVisible=1
+- GIVEN widget placement id 10 has `isVisible: 1` but no ConditionalRule records exist
+- WHEN the dashboard is rendered
+- THEN the widget MUST default to visible (no rules means no restrictions)
+
+#### Scenario: No include rules but exclude rules exist
+- GIVEN widget placement id 10 has only exclusion rules (no inclusion rules)
+- AND no exclusion rule matches
+- WHEN the dashboard is rendered
+- THEN the widget MUST be visible (passesIncludeRules returns true when no include rules exist, passesExcludeRules returns true when no exclude rule matches)
+
+### REQ-VIS-010: Visibility Evaluation Pipeline
+
+The ConditionalService MUST evaluate visibility through a defined pipeline: isVisible flag check, then rule loading, then VisibilityChecker evaluation.
+
+#### Scenario: Widget with isVisible=0 bypasses rule evaluation
+- GIVEN widget placement id 10 has `isVisible: 0` and 3 conditional rules
+- WHEN the dashboard is rendered
+- THEN the system MUST immediately return false (hidden) without evaluating any rules
+- AND rule evaluation MUST be skipped for performance
+
+#### Scenario: Widget with isVisible=1 and rules triggers evaluation
+- GIVEN widget placement id 10 has `isVisible: 1` and 2 conditional rules
+- WHEN `ConditionalService::isWidgetVisible()` is called
+- THEN the system MUST load rules via `ConditionalRuleMapper::findByPlacementId()`
+- AND delegate evaluation to `VisibilityChecker::checkRules()`
+
+#### Scenario: Widget with isVisible=1 and no rules is always visible
+- GIVEN widget placement id 10 has `isVisible: 1` and no conditional rules
+- WHEN `ConditionalService::isWidgetVisible()` is called
+- THEN the system MUST return true without calling VisibilityChecker
+- AND the widget MUST always be displayed
+
+### REQ-VIS-011: Rule Cascade Deletion
+
+When a widget placement is deleted, all its associated conditional rules MUST also be deleted.
+
+#### Scenario: Delete placement cascades to rules
+- GIVEN widget placement id 10 has 5 conditional rules
+- WHEN placement 10 is deleted via DELETE /api/widgets/10
+- THEN all 5 conditional rules MUST also be deleted
+- AND no orphaned rules MUST remain in the database
+- NOTE: `PlacementService::removePlacement()` does NOT explicitly cascade-delete conditional rules. This depends on database-level cascade constraints.
+
+#### Scenario: Delete dashboard cascades to placements and rules
+- GIVEN dashboard id 5 has 3 placements, each with 2 conditional rules
+- WHEN dashboard 5 is deleted
+- THEN all 3 placements and all 6 conditional rules MUST be deleted
+- NOTE: `DashboardService::deleteDashboard()` deletes placements via `placementMapper->deleteByDashboardId()` but does not explicitly handle conditional rules.
+
+## Non-Functional Requirements
+
+- **Performance**: Rule evaluation for a single placement with up to 10 rules MUST complete within 50ms. Total evaluation for a dashboard with 30 placements and 100 rules MUST complete within 500ms.
+- **Timezone handling**: Time-based rules currently use the server's default timezone (`new DateTime()`). A `timezone` config field is NOT currently supported. Future versions SHOULD add timezone support via PHP's DateTimeZone.
+- **Data integrity**: Deleting a widget placement MUST cascade-delete all its conditional rules. Rules MUST NOT reference non-existent placements.
+- **Accessibility**: Conditional visibility MUST NOT affect the accessibility tree for visible widgets. Hidden widgets MUST be fully removed from the DOM, not just hidden via CSS.
+- **Localization**: Rule type labels and validation messages MUST support English and Dutch.
+
+### Current Implementation Status
+
+**Fully implemented:**
+- REQ-VIS-001 (Create Conditional Rule): `ConditionalService::addRule()` creates rules. `RuleApiController::addRule()` exposes POST /api/widgets/{placementId}/rules with ownership verification.
+- REQ-VIS-002 (List Conditional Rules): `ConditionalService::getRules()` returns rules by placement ID with ownership check.
+- REQ-VIS-003 (Update Conditional Rule): `ConditionalService::updateRule()` handles partial updates. `RuleApiController::updateRule()` exposes PUT /api/rules/{ruleId}.
+- REQ-VIS-004 (Delete Conditional Rule): `ConditionalService::deleteRule()` removes rules. `RuleApiController::deleteRule()` exposes DELETE /api/rules/{ruleId}.
+- REQ-VIS-005 (Group-Based Rule Evaluation): `RuleEvaluatorService::evaluateGroupRule()` uses `IGroupManager::getUserGroupIds()` and `array_intersect()`.
+- REQ-VIS-006 (Time-Based Rule Evaluation): `RuleEvaluatorService::evaluateTimeRule()` checks day-of-week filter and time range. Uses `strtolower($now->format('D'))` for day abbreviations.
+- REQ-VIS-007 (Date-Based Rule Evaluation): `RuleEvaluatorService::evaluateDateRule()` supports optional `startDate` and `endDate`.
+- REQ-VIS-008 (Attribute-Based Rule Evaluation): `RuleEvaluatorService::evaluateAttributeRule()` delegates to `UserAttributeResolver`. Supports operators: `equals`, `not_equals`, `contains`, `starts_with`, `ends_with`.
+- REQ-VIS-009 (Multiple Rule Combination): `VisibilityChecker::checkRules()` separates include/exclude rules. Include uses OR, exclude uses AND.
+- REQ-VIS-010 (Visibility Evaluation Pipeline): `ConditionalService::isWidgetVisible()` checks `isVisible` flag first, then loads rules, then delegates to `VisibilityChecker`.
+
+**Not yet implemented:**
+- REQ-VIS-001 ruleType validation: No server-side validation for ruleType values.
+- REQ-VIS-003/004 ownership verification: `updateRule()` and `deleteRule()` in `RuleApiController` do NOT verify placement ownership.
+- REQ-VIS-006 midnight-spanning windows: Simple string comparison does not handle time windows spanning midnight.
+- REQ-VIS-006 timezone support: No `timezone` field support.
+- REQ-VIS-011 cascade delete: `PlacementService::removePlacement()` does not explicitly cascade-delete conditional rules.
+- Frontend UI: No Vue component exists for creating or managing conditional rules.
+
+### Standards & References
+- Nextcloud Group API: `OCP\IGroupManager::getUserGroupIds()`
+- Nextcloud User API: `OCP\IUserManager::get()`, `IUser::getLanguage()`, `IUser::getEMailAddress()`
+- PHP DateTime: Server timezone via `new DateTime()` (no timezone parameter)
+- WCAG 2.1 AA: Hidden widgets must be removed from DOM, not just CSS-hidden
diff --git a/openspec/specs/conditional-visibility/tasks.md b/openspec/changes/archive/2026-03-21-conditional-visibility/specs/conditional-visibility/tasks.md
similarity index 100%
rename from openspec/specs/conditional-visibility/tasks.md
rename to openspec/changes/archive/2026-03-21-conditional-visibility/specs/conditional-visibility/tasks.md
diff --git a/openspec/changes/archive/2026-03-21-conditional-visibility/tasks.md b/openspec/changes/archive/2026-03-21-conditional-visibility/tasks.md
new file mode 100644
index 00000000..1bbaf777
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-conditional-visibility/tasks.md
@@ -0,0 +1,16 @@
+# Conditional Visibility - Tasks
+
+## Tasks
+
+- [x] TASK-VIS-001: Implement ConditionalRule entity with config helpers
+- [x] TASK-VIS-002: Implement ConditionalRuleMapper with CRUD
+- [x] TASK-VIS-003: Implement RuleEvaluatorService for all 4 rule types
+- [x] TASK-VIS-004: Implement VisibilityChecker with include/exclude logic
+- [x] TASK-VIS-005: Implement ConditionalService orchestration
+- [x] TASK-VIS-006: Implement UserAttributeResolver
+- [x] TASK-VIS-007: Implement RuleApiController REST endpoints
+- [x] TASK-VIS-008: Implement database migration for conditional_rules table
+- [x] TASK-VIS-009: Write unit tests for ConditionalRule entity (ADR-009)
+- [x] TASK-VIS-010: Write unit tests for VisibilityChecker (ADR-009)
+- [x] TASK-VIS-011: Write feature documentation and screenshots (ADR-010)
+- [x] TASK-VIS-012: Verify i18n support for visibility UI strings (ADR-005)
diff --git a/openspec/changes/archive/2026-03-21-dashboards/.openspec.yaml b/openspec/changes/archive/2026-03-21-dashboards/.openspec.yaml
new file mode 100644
index 00000000..d8b0ed03
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-dashboards/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-dashboards/design.md b/openspec/changes/archive/2026-03-21-dashboards/design.md
new file mode 100644
index 00000000..2230636c
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-dashboards/design.md
@@ -0,0 +1,29 @@
+# Dashboards - Design Document
+
+## Architecture
+
+### Backend
+- **Entity**: `Db\Dashboard` - Core entity with UUID, name, description, type, grid config, permissions
+- **Mapper**: `Db\DashboardMapper` - Database operations (find, findByUserId, findAdminTemplates, setActive, deactivateAllForUser)
+- **Service**: `Service\DashboardService` - Business logic for CRUD, activation, template creation
+- **Factory**: `Service\DashboardFactory` - Creates Dashboard entities with UUID generation
+- **Resolver**: `Service\DashboardResolver` - Resolves effective dashboard (active, existing, or template-based)
+- **Controller**: `Controller\DashboardApiController` - REST API endpoints
+
+### Frontend
+- **Store**: `stores/dashboard.js` - Pinia store for dashboard state
+- **Component**: `components/DashboardSwitcher.vue` - UI for switching between dashboards
+- **View**: `views/Views.vue` - Main dashboard view
+
+### Data Flow
+1. User requests dashboard -> DashboardApiController
+2. Controller calls DashboardService.getEffectiveDashboard()
+3. DashboardResolver checks: active dashboard -> existing dashboard -> template -> create new
+4. DashboardFactory creates entity with generated UUID
+5. Response includes dashboard + placements + permissionLevel
+
+### Key Design Decisions
+- Only one dashboard active per user at a time (enforced by deactivateAllForUser)
+- New dashboards auto-activate and get default placements (recommendations + activity)
+- UUID v4 generated via custom DashboardFactory.generateUuid() (no external library)
+- Dashboard types: "user" (personal) and "admin_template" (admin-managed)
diff --git a/openspec/changes/archive/2026-03-21-dashboards/proposal.md b/openspec/changes/archive/2026-03-21-dashboards/proposal.md
new file mode 100644
index 00000000..af10d7c7
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-dashboards/proposal.md
@@ -0,0 +1,18 @@
+# Dashboards Specification
+
+## Problem
+Dashboards are the core organizational unit in MyDash. Each user can create and manage multiple personal dashboards, each acting as a container for widget placements, tiles, and layout configuration. Dashboards define the grid structure, permission level, and active state. Only one dashboard can be active per user at a time, serving as their landing page when they open Nextcloud. Dashboards can also be of type `admin_template`, managed by administrators for distribution to users.
+
+## Proposed Solution
+Implement Dashboards Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the dashboards specification.
+
+## Success Criteria
+- Create a dashboard with default settings
+- Create a dashboard with custom settings
+- Create a dashboard with invalid grid columns
+- Create a dashboard without a name
+- Dashboard creation creates default placements
diff --git a/openspec/specs/dashboards/design.md b/openspec/changes/archive/2026-03-21-dashboards/specs/dashboards/design.md
similarity index 100%
rename from openspec/specs/dashboards/design.md
rename to openspec/changes/archive/2026-03-21-dashboards/specs/dashboards/design.md
diff --git a/openspec/changes/archive/2026-03-21-dashboards/specs/dashboards/spec.md b/openspec/changes/archive/2026-03-21-dashboards/specs/dashboards/spec.md
new file mode 100644
index 00000000..1143e18b
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-dashboards/specs/dashboards/spec.md
@@ -0,0 +1,355 @@
+---
+status: reviewed
+---
+
+# Dashboards Specification
+
+## Purpose
+
+Dashboards are the core organizational unit in MyDash. Each user can create and manage multiple personal dashboards, each acting as a container for widget placements, tiles, and layout configuration. Dashboards define the grid structure, permission level, and active state. Only one dashboard can be active per user at a time, serving as their landing page when they open Nextcloud. Dashboards can also be of type `admin_template`, managed by administrators for distribution to users.
+
+## Data Model
+
+Each dashboard record is stored in the `oc_mydash_dashboards` table with the following fields:
+- **id**: Auto-increment integer primary key
+- **uuid**: Unique identifier (UUID v4)
+- **userId**: Nextcloud user ID of the dashboard owner
+- **name**: Human-readable dashboard name
+- **description**: Optional description of the dashboard purpose
+- **type**: Either `user` (personal) or `admin_template` (admin-managed template)
+- **basedOnTemplate**: Nullable integer foreign key to the source admin template dashboard ID (set when a user copy is created from a template)
+- **gridColumns**: Number of grid columns (default: 12)
+- **permissionLevel**: One of `view_only`, `add_only`, `full` (inherited from template or set by admin)
+- **targetGroups**: JSON string of group IDs (used for admin templates)
+- **isDefault**: SMALLINT (0/1) flag for admin templates indicating default distribution
+- **isActive**: SMALLINT (0/1) flag indicating if this is the user's currently active dashboard
+- **createdAt**: Timestamp string (Y-m-d H:i:s)
+- **updatedAt**: Timestamp string (Y-m-d H:i:s)
+
+## Requirements
+
+### REQ-DASH-001: Create Personal Dashboard
+
+Users MUST be able to create new personal dashboards with a name, optional description, and default grid configuration.
+
+#### Scenario: Create a dashboard with default settings
+- GIVEN a logged-in Nextcloud user "alice"
+- WHEN she sends POST /api/dashboard with body `{"name": "My Work Dashboard"}`
+- THEN the system MUST create a new dashboard with:
+ - A generated UUID v4 (via custom `DashboardFactory::generateUuid()`)
+ - `userId` set to "alice"
+ - `type` set to "user"
+ - `isActive` set to 1 (true) -- the newly created dashboard becomes active, and all other user dashboards are deactivated via `deactivateAllForUser()`
+ - `gridColumns` set to 12 (hardcoded in `DashboardFactory::create()`)
+ - `permissionLevel` set to "full" (hardcoded as `Dashboard::PERMISSION_FULL`)
+- AND the response MUST return HTTP 201 with the full dashboard object including the generated id and uuid
+
+#### Scenario: Create a dashboard with custom settings
+- GIVEN a logged-in Nextcloud user "bob"
+- WHEN he sends POST /api/dashboard with body `{"name": "Analytics", "description": "Data overview"}`
+- THEN the system MUST create the dashboard with the specified name and description
+- AND `gridColumns` MUST be set to 12 (custom gridColumns is not exposed in the create endpoint)
+
+#### Scenario: Create a dashboard with invalid grid columns
+- GIVEN a logged-in Nextcloud user "alice"
+- WHEN she sends POST /api/dashboard with body `{"name": "Test", "grid_columns": 0}`
+- THEN the system MUST return HTTP 400 with a validation error
+- AND `gridColumns` MUST only accept positive integers (minimum 1, maximum 24)
+- NOTE: Grid column validation is NOT currently implemented
+
+#### Scenario: Create a dashboard without a name
+- GIVEN a logged-in Nextcloud user "alice"
+- WHEN she sends POST /api/dashboard with body `{}`
+- THEN the system MUST create a dashboard with the default name "My Dashboard"
+- NOTE: The controller defaults name to "My Dashboard" if null. No validation error is returned.
+
+#### Scenario: Dashboard creation creates default placements
+- GIVEN user "alice" has no dashboards and no templates apply
+- WHEN she accesses MyDash for the first time (triggers `tryCreateFromTemplate()`)
+- THEN the system MUST create a "My Dashboard" with two default placements:
+ - "recommendations" widget at (0, 0) with size 6x5
+ - "activity" widget at (6, 0) with size 6x5
+- AND both placements MUST have `showTitle: 1`, `isVisible: 1`, and appropriate sortOrder values
+
+### REQ-DASH-002: List User Dashboards
+
+Users MUST be able to retrieve a list of all their dashboards, scoped to their user ID.
+
+#### Scenario: List dashboards for a user with multiple dashboards
+- GIVEN user "alice" has 3 dashboards: "Work" (active), "Personal", "Analytics"
+- WHEN she sends GET /api/dashboards
+- THEN the system MUST return HTTP 200 with an array containing all 3 dashboards
+- AND each dashboard object MUST include: id, uuid, name, description, type, basedOnTemplate, gridColumns, permissionLevel, targetGroups, isDefault, isActive, createdAt, updatedAt
+- AND the active dashboard MUST have `isActive: 1`
+
+#### Scenario: List dashboards for a user with no dashboards
+- GIVEN user "bob" has never created a dashboard and no template has been distributed to him
+- WHEN he sends GET /api/dashboards
+- THEN the system MUST return HTTP 200 with an empty array
+
+#### Scenario: Dashboards are user-scoped
+- GIVEN user "alice" has 3 dashboards and user "bob" has 1 dashboard
+- WHEN "alice" sends GET /api/dashboards
+- THEN the response MUST contain only alice's 3 dashboards
+- AND bob's dashboard MUST NOT be included
+- AND admin templates (type: "admin_template") MUST NOT be included
+
+### REQ-DASH-003: Get Active Dashboard
+
+Users MUST be able to retrieve their currently active dashboard along with its placements and effective permission level in a single request.
+
+#### Scenario: Get the active dashboard
+- GIVEN user "alice" has dashboard "Work" marked as active
+- WHEN she sends GET /api/dashboard
+- THEN the system MUST return HTTP 200 with an object containing:
+ - `dashboard`: the "Work" dashboard object (with `isActive: 1`)
+ - `placements`: array of all widget placements on this dashboard
+ - `permissionLevel`: the effective permission level string (resolved via `PermissionService::getEffectivePermissionLevel()`)
+
+#### Scenario: No active dashboard exists but user has dashboards
+- GIVEN user "bob" has 2 dashboards but none is marked as active
+- WHEN he sends GET /api/dashboard
+- THEN the system MUST activate the first existing dashboard via `DashboardResolver::tryActivateExistingDashboard()`
+- AND return that dashboard as the active one
+
+#### Scenario: First-time user triggers template distribution
+- GIVEN user "carol" has no dashboards
+- AND an admin template exists targeting carol's group
+- WHEN she sends GET /api/dashboard
+- THEN the system MUST create a personal copy of the matching template via `TemplateService::createDashboardFromTemplate()`
+- AND the copy MUST be set as her active dashboard
+- AND the response MUST return the newly created dashboard with its placements
+
+#### Scenario: First-time user with no template gets default dashboard
+- GIVEN user "dave" has no dashboards
+- AND no admin template matches dave's groups
+- AND `allowUserDashboards` is true
+- WHEN he sends GET /api/dashboard
+- THEN the system MUST create a default "My Dashboard" with recommendations and activity widgets
+- AND the response MUST return the newly created dashboard
+
+#### Scenario: First-time user with dashboards disabled and no template
+- GIVEN user "eve" has no dashboards
+- AND no admin template matches eve's groups
+- AND `allowUserDashboards` is false
+- WHEN she sends GET /api/dashboard
+- THEN the system MUST return null (no dashboard available)
+- AND the response MUST return HTTP 404 or an empty result
+
+### REQ-DASH-004: Update Dashboard
+
+Users MUST be able to update the name, description, and grid configuration of their dashboards.
+
+#### Scenario: Update dashboard name and description
+- GIVEN user "alice" has dashboard with id 5
+- WHEN she sends PUT /api/dashboard/5 with body `{"name": "Updated Work", "description": "New desc"}`
+- THEN the system MUST update the name and description
+- AND set `updatedAt` to the current timestamp
+- AND return HTTP 200 with the updated dashboard object
+
+#### Scenario: Update another user's dashboard
+- GIVEN user "alice" has dashboard with id 5
+- WHEN user "bob" sends PUT /api/dashboard/5 with body `{"name": "Hacked"}`
+- THEN the system MUST return HTTP 403 (via ownership check)
+- AND the dashboard MUST NOT be modified
+
+#### Scenario: Update grid columns on a dashboard with existing widgets
+- GIVEN user "alice" has dashboard id 5 with `gridColumns: 12` and 4 widget placements
+- WHEN she sends PUT /api/dashboard/5 with body `{"gridColumns": 6}`
+- THEN the system MUST update `gridColumns` to 6
+- AND widget placements that exceed the new column count SHOULD be repositioned or flagged for re-layout
+- NOTE: Grid reflow is NOT currently implemented. Widgets exceeding the new column count remain at their positions.
+
+#### Scenario: Update permission_level on a user dashboard
+- GIVEN user "alice" has a personal dashboard with `permissionLevel: full`
+- WHEN she sends PUT /api/dashboard/5 with body `{"permissionLevel": "view_only"}`
+- THEN the system MUST ignore the `permissionLevel` field
+- AND the permissionLevel MUST remain "full"
+- NOTE: `applyDashboardUpdates()` does not handle `permissionLevel` -- it only processes `name`, `description`, `gridColumns`, and `placements`.
+
+#### Scenario: Batch update placement positions via dashboard update
+- GIVEN user "alice" has dashboard id 5 with 4 widget placements
+- WHEN she sends PUT /api/dashboard/5 with body containing a `placements` array of updated positions
+- THEN the system MUST update all placement positions via `placementMapper->updatePositions()`
+- AND this enables efficient grid saves after drag-and-drop rearrangement
+
+### REQ-DASH-005: Delete Dashboard
+
+Users MUST be able to delete their own dashboards with proper cascade deletion of associated data.
+
+#### Scenario: Delete a dashboard
+- GIVEN user "alice" has dashboard id 5 with 3 widget placements
+- WHEN she sends DELETE /api/dashboard/5
+- THEN the system MUST delete the dashboard
+- AND all associated widget placements MUST be cascade-deleted via `placementMapper->deleteByDashboardId()`
+- AND the response MUST return HTTP 200
+
+#### Scenario: Delete the active dashboard
+- GIVEN user "alice" has dashboard id 5 marked as active and dashboard id 6 as inactive
+- WHEN she sends DELETE /api/dashboard/5
+- THEN the system MUST delete dashboard 5
+- AND the system does NOT automatically activate dashboard 6
+- NOTE: Auto-activation after delete is NOT currently implemented. The user will have no active dashboard until the next GET /api/dashboard triggers `tryActivateExistingDashboard()`.
+
+#### Scenario: Delete another user's dashboard
+- GIVEN user "alice" has dashboard id 5
+- WHEN user "bob" sends DELETE /api/dashboard/5
+- THEN the system MUST return HTTP 403
+- AND the dashboard MUST NOT be deleted
+
+#### Scenario: Delete the last remaining dashboard
+- GIVEN user "alice" has only 1 dashboard (id 5)
+- WHEN she sends DELETE /api/dashboard/5
+- THEN the system MUST delete the dashboard
+- AND subsequent GET /api/dashboards MUST return an empty array
+
+#### Scenario: Delete does not check permission level
+- GIVEN user "alice" has a view-only dashboard id 5 (based on a template with `permissionLevel: "view_only"`)
+- WHEN she sends DELETE /api/dashboard/5
+- THEN the system MUST allow the deletion
+- AND users MUST always have the right to remove dashboards from their account regardless of permission level
+
+### REQ-DASH-006: Activate Dashboard
+
+Users MUST be able to set one of their dashboards as the active dashboard, ensuring only one is active at a time.
+
+#### Scenario: Activate a dashboard
+- GIVEN user "alice" has dashboard "Work" (id 5, active) and "Personal" (id 6, inactive)
+- WHEN she sends POST /api/dashboard/6/activate
+- THEN dashboard 6 MUST have `isActive: 1`
+- AND dashboard 5 MUST have `isActive: 0` (via `DashboardMapper::setActive()` which deactivates all others first)
+- AND the response MUST return HTTP 200 with the newly activated dashboard
+
+#### Scenario: Activate an already active dashboard
+- GIVEN user "alice" has dashboard "Work" (id 5, active)
+- WHEN she sends POST /api/dashboard/5/activate
+- THEN the system MUST return HTTP 200 (idempotent operation)
+- AND dashboard 5 MUST remain active
+
+#### Scenario: Activate another user's dashboard
+- GIVEN user "alice" has dashboard id 5
+- WHEN user "bob" sends POST /api/dashboard/5/activate
+- THEN the system MUST return HTTP 403
+
+#### Scenario: Only one active dashboard per user
+- GIVEN user "alice" has 5 dashboards
+- WHEN she activates dashboard id 8
+- THEN exactly one dashboard (id 8) MUST have `isActive: 1`
+- AND all other 4 dashboards MUST have `isActive: 0`
+
+### REQ-DASH-007: Dashboard Name Validation
+
+Dashboard names MUST be validated for length and content.
+
+#### Scenario: Name length validation
+- GIVEN a logged-in user
+- WHEN they create a dashboard with a name exceeding 255 characters
+- THEN the system MUST return HTTP 400 with a validation error
+- AND dashboard names MUST be between 1 and 255 characters
+- NOTE: Name length validation is NOT currently implemented
+
+#### Scenario: Duplicate dashboard names allowed
+- GIVEN user "alice" already has a dashboard named "Work"
+- WHEN she creates another dashboard named "Work"
+- THEN the system MUST allow this (dashboard names are not unique per user)
+- AND the two dashboards MUST be distinguishable by their id and uuid
+
+#### Scenario: Empty name defaults to "My Dashboard"
+- GIVEN a logged-in user
+- WHEN they create a dashboard without providing a name
+- THEN the system MUST use the default name "My Dashboard"
+- AND the dashboard MUST be created successfully
+
+### REQ-DASH-008: Dashboard Type Enforcement
+
+The `type` field MUST distinguish between user-created dashboards and admin templates, with appropriate access controls.
+
+#### Scenario: Users cannot create admin_template type dashboards
+- GIVEN a non-admin user "alice"
+- WHEN she sends POST /api/dashboard with body `{"name": "Fake Template", "type": "admin_template"}`
+- THEN the system MUST ignore the `type` field (defaulting to "user" via `DashboardFactory::create()`)
+- AND the created dashboard MUST have `type: user`
+
+#### Scenario: Admin creates a template dashboard
+- GIVEN a Nextcloud admin user
+- WHEN they send POST /api/admin/templates with template data
+- THEN the system MUST create a dashboard with `type: admin_template`
+- AND the template dashboard MUST NOT appear in regular users' GET /api/dashboards responses
+
+#### Scenario: Template-derived dashboards have type "user"
+- GIVEN an admin template "Company Dashboard" is distributed to user "alice"
+- WHEN the system creates a copy for alice via `TemplateService::createDashboardFromTemplate()`
+- THEN the copy MUST have `type: "user"` (NOT "admin_template")
+- AND `basedOnTemplate` MUST reference the source template's ID
+
+### REQ-DASH-009: Dashboard Resolution Chain
+
+The system MUST resolve the effective dashboard through a defined chain when GET /api/dashboard is called.
+
+#### Scenario: Active dashboard found immediately
+- GIVEN user "alice" has an active dashboard
+- WHEN GET /api/dashboard is called
+- THEN `DashboardResolver::tryGetActiveDashboard()` MUST find and return it immediately
+- AND no template distribution or default creation logic MUST be triggered
+
+#### Scenario: No active dashboard but existing dashboards
+- GIVEN user "alice" has dashboards but none is active
+- WHEN GET /api/dashboard is called
+- THEN `DashboardResolver::tryActivateExistingDashboard()` MUST activate the first found dashboard
+- AND return it as the active dashboard
+
+#### Scenario: No dashboards at all with template available
+- GIVEN user "alice" has no dashboards
+- AND a matching admin template exists
+- WHEN GET /api/dashboard is called
+- THEN `DashboardService::tryCreateFromTemplate()` MUST be called
+- AND a template copy MUST be created and set as active
+
+### REQ-DASH-010: Dashboard Serialization
+
+Dashboard objects MUST be consistently serialized across all API responses.
+
+#### Scenario: Dashboard object includes all fields
+- GIVEN a dashboard exists
+- WHEN it is returned via any API endpoint
+- THEN the serialized object MUST include all fields: id, uuid, userId, name, description, type, basedOnTemplate, gridColumns, permissionLevel, targetGroups, isDefault, isActive, createdAt, updatedAt
+
+#### Scenario: Null fields are included in serialization
+- GIVEN a dashboard with `description: null` and `basedOnTemplate: null`
+- WHEN the dashboard is serialized
+- THEN both `description` and `basedOnTemplate` MUST be present in the JSON with null values
+
+#### Scenario: Timestamp format consistency
+- GIVEN a dashboard with `createdAt` and `updatedAt` set
+- WHEN the dashboard is serialized
+- THEN timestamps MUST be in "Y-m-d H:i:s" format (e.g., "2026-03-20 14:30:00")
+
+## Non-Functional Requirements
+
+- **Performance**: GET /api/dashboards MUST return within 500ms for users with up to 50 dashboards. GET /api/dashboard MUST return within 1 second including template distribution if needed.
+- **Data integrity**: The single-active-dashboard invariant MUST be enforced consistently, even under concurrent requests from the same user.
+- **Accessibility**: Dashboard management UI elements (create, edit, delete, activate) MUST be operable via keyboard and screen readers.
+- **Localization**: All error messages and validation messages MUST support English and Dutch.
+
+### Current Implementation Status
+
+**Fully implemented:**
+- REQ-DASH-001 (Create Personal Dashboard): `DashboardService::createDashboard()` delegates to `DashboardFactory::create()`. Default placements created via `createDefaultPlacements()` during first-time access.
+- REQ-DASH-002 (List User Dashboards): `DashboardService::getUserDashboards()` calls `DashboardMapper::findByUserId()`. User-scoped, templates filtered out.
+- REQ-DASH-003 (Get Active Dashboard): `DashboardService::getEffectiveDashboard()` chains `tryGetActiveDashboard` -> `tryActivateExistingDashboard` -> `tryCreateFromTemplate`.
+- REQ-DASH-004 (Update Dashboard): `DashboardService::updateDashboard()` with `applyDashboardUpdates()` handles name, description, gridColumns, placements.
+- REQ-DASH-005 (Delete Dashboard): `DashboardService::deleteDashboard()` deletes placements then dashboard.
+- REQ-DASH-006 (Activate Dashboard): `DashboardService::activateDashboard()` via `DashboardMapper::setActive()`.
+- REQ-DASH-008 (Dashboard Type Enforcement): Admin templates via `AdminController`, user dashboards via `DashboardFactory`.
+- REQ-DASH-009 (Dashboard Resolution Chain): Full chain implemented in `DashboardService::getEffectiveDashboard()`.
+
+**Not yet implemented:**
+- REQ-DASH-001/007 validation: No name or gridColumns validation.
+- REQ-DASH-004 grid reflow: Updating gridColumns does not reposition widgets.
+- REQ-DASH-005 auto-activate after delete: Not implemented.
+- REQ-DASH-005 cascade-delete conditional rules: Not explicitly handled.
+
+### Standards & References
+- Nextcloud Controller patterns: `OCP\AppFramework\Controller`, `#[NoAdminRequired]` attribute
+- UUID generation: Custom UUID v4 implementation in `DashboardFactory::generateUuid()`
+- WCAG 2.1 AA: Dashboard management UI elements should be keyboard-operable
diff --git a/openspec/specs/dashboards/tasks.md b/openspec/changes/archive/2026-03-21-dashboards/specs/dashboards/tasks.md
similarity index 100%
rename from openspec/specs/dashboards/tasks.md
rename to openspec/changes/archive/2026-03-21-dashboards/specs/dashboards/tasks.md
diff --git a/openspec/changes/archive/2026-03-21-dashboards/tasks.md b/openspec/changes/archive/2026-03-21-dashboards/tasks.md
new file mode 100644
index 00000000..9d2a97fd
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-dashboards/tasks.md
@@ -0,0 +1,17 @@
+# Dashboards - Tasks
+
+## Tasks
+
+- [x] TASK-DASH-001: Implement Dashboard entity with all fields and jsonSerialize
+- [x] TASK-DASH-002: Implement DashboardMapper with CRUD and query methods
+- [x] TASK-DASH-003: Implement DashboardFactory with UUID generation
+- [x] TASK-DASH-004: Implement DashboardService with create, update, delete, activate
+- [x] TASK-DASH-005: Implement DashboardResolver for effective dashboard resolution
+- [x] TASK-DASH-006: Implement DashboardApiController REST endpoints
+- [x] TASK-DASH-007: Implement database migration for dashboards table
+- [x] TASK-DASH-008: Implement frontend dashboard store
+- [x] TASK-DASH-009: Implement DashboardSwitcher component
+- [x] TASK-DASH-010: Write unit tests for Dashboard entity (ADR-009)
+- [x] TASK-DASH-011: Write unit tests for DashboardFactory
+- [x] TASK-DASH-012: Write feature documentation and screenshots (ADR-010)
+- [x] TASK-DASH-013: Verify i18n support for dashboard UI strings (ADR-005)
diff --git a/openspec/changes/archive/2026-03-21-grid-layout/.openspec.yaml b/openspec/changes/archive/2026-03-21-grid-layout/.openspec.yaml
new file mode 100644
index 00000000..d8b0ed03
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-grid-layout/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-grid-layout/design.md b/openspec/changes/archive/2026-03-21-grid-layout/design.md
new file mode 100644
index 00000000..f6393856
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-grid-layout/design.md
@@ -0,0 +1,32 @@
+# Grid Layout - Design Document
+
+## Architecture
+
+### Frontend (primary)
+- **Component**: `components/DashboardGrid.vue` - GridStack 10.3.1 wrapper
+- **Library**: GridStack 10.3.1 (npm dependency)
+
+### Configuration
+- 12-column default grid (configurable per dashboard via gridColumns)
+- Cell height: 80px fixed
+- Margins: 12px horizontal and vertical
+- Float mode enabled (items stay at exact position)
+- Animation enabled
+- Minimum widget size: 2x2
+
+### Modes
+- **View mode**: Static grid, no drag-and-drop
+- **Edit mode**: Drag-and-drop enabled, resize handles visible
+
+### Data Flow
+1. Dashboard loads -> DashboardGrid receives placements as props
+2. GridStack initializes with dashboard.gridColumns config
+3. Each placement rendered at (gridX, gridY, gridWidth, gridHeight)
+4. User drags/resizes in edit mode -> GridStack emits change event
+5. Parent component persists position changes via API
+
+### Key Design Decisions
+- GridStack manages DOM directly (not Vue-reactive for performance)
+- Position changes emitted as Vue events (not persisted by grid component)
+- 0-based coordinate system (gridX: 0-11 for 12 columns)
+- gs-id, gs-x, gs-y, gs-w, gs-h attributes on grid items
diff --git a/openspec/changes/archive/2026-03-21-grid-layout/proposal.md b/openspec/changes/archive/2026-03-21-grid-layout/proposal.md
new file mode 100644
index 00000000..54345a93
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-grid-layout/proposal.md
@@ -0,0 +1,18 @@
+# Grid Layout Specification
+
+## Problem
+The grid layout system powers the drag-and-drop dashboard experience in MyDash. Built on GridStack 10.3.1, it provides a 12-column responsive grid where users can position, resize, and rearrange widget placements and tiles. The grid operates in two modes: view mode (static, no interaction) and edit mode (drag-and-drop enabled). Position changes are emitted via Vue events and persisted via the API by the parent component.
+
+## Proposed Solution
+Implement Grid Layout Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the grid-layout specification.
+
+## Success Criteria
+- Initialize grid with default 12-column layout
+- Initialize grid with custom column count
+- Initialize grid with no widget placements
+- Grid renders placements in correct positions
+- Grid initialization options match configuration
diff --git a/openspec/specs/grid-layout/design.md b/openspec/changes/archive/2026-03-21-grid-layout/specs/grid-layout/design.md
similarity index 100%
rename from openspec/specs/grid-layout/design.md
rename to openspec/changes/archive/2026-03-21-grid-layout/specs/grid-layout/design.md
diff --git a/openspec/changes/archive/2026-03-21-grid-layout/specs/grid-layout/spec.md b/openspec/changes/archive/2026-03-21-grid-layout/specs/grid-layout/spec.md
new file mode 100644
index 00000000..c32d7de6
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-grid-layout/specs/grid-layout/spec.md
@@ -0,0 +1,390 @@
+---
+status: reviewed
+---
+
+# Grid Layout Specification
+
+## Purpose
+
+The grid layout system powers the drag-and-drop dashboard experience in MyDash. Built on GridStack 10.3.1, it provides a 12-column responsive grid where users can position, resize, and rearrange widget placements and tiles. The grid operates in two modes: view mode (static, no interaction) and edit mode (drag-and-drop enabled). Position changes are emitted via Vue events and persisted via the API by the parent component.
+
+## Technical Foundation
+
+- **Library**: GridStack 10.3.1
+- **Grid columns**: 12 (configurable per dashboard via `gridColumns`)
+- **Cell height**: 80px (fixed)
+- **Margins**: 12px horizontal and vertical between cells
+- **Coordinate system**: 0-based (gridX: 0-11 for 12 columns, gridY: 0+)
+- **Float mode**: Enabled (`float: true`) -- items do NOT auto-stack downward; they stay at their exact grid position
+- **Animation**: Enabled (`animate: true`)
+- **Minimum widget size**: 2 columns wide, 2 rows tall (`gs-min-w="2"`, `gs-min-h="2"`)
+
+## Requirements
+
+### REQ-GRID-001: Grid Initialization
+
+The grid MUST initialize with the correct configuration when a dashboard is loaded.
+
+#### Scenario: Initialize grid with default 12-column layout
+- GIVEN user "alice" activates dashboard id 5 with `gridColumns: 12`
+- WHEN the dashboard view loads
+- THEN GridStack MUST be initialized with `column: 12`, `cellHeight: 80`, `margin: 12`, `float: true`, `animate: true`
+- AND the grid MUST render all widget placements at their stored (gridX, gridY, gridWidth, gridHeight) coordinates using `gs-x`, `gs-y`, `gs-w`, `gs-h` attributes
+
+#### Scenario: Initialize grid with custom column count
+- GIVEN dashboard id 5 has `gridColumns: 6`
+- WHEN the dashboard view loads
+- THEN GridStack MUST be initialized with `column: 6`
+- AND all widget placements MUST be constrained to the 6-column grid
+- AND placements with `gridX + gridWidth > 6` MUST be automatically reflowed to fit
+
+#### Scenario: Initialize grid with no widget placements
+- GIVEN dashboard id 5 has no widget placements
+- WHEN the dashboard view loads
+- THEN GridStack MUST initialize an empty grid
+- AND the empty grid MUST display a placeholder message or empty state (e.g., "Add widgets to get started")
+- NOTE: Empty state placeholder is NOT currently implemented
+
+#### Scenario: Grid renders placements in correct positions
+- GIVEN dashboard id 5 has the following placements:
+ | placement_id | widgetId | gridX | gridY | gridWidth | gridHeight |
+ |--------------|----------------|-------|-------|-----------|------------|
+ | 10 | weather_status | 0 | 0 | 4 | 2 |
+ | 11 | notes | 4 | 0 | 4 | 3 |
+ | 12 | calendar | 8 | 0 | 4 | 2 |
+ | 13 | (tile) | 0 | 2 | 2 | 2 |
+- WHEN the dashboard view loads
+- THEN each placement MUST be rendered at its exact grid coordinates via `gs-id`, `gs-x`, `gs-y`, `gs-w`, `gs-h` attributes
+- AND no placements MUST overlap
+- AND the grid height MUST expand to accommodate all placements
+
+#### Scenario: Grid initialization options match configuration
+- GIVEN the DashboardGrid component receives props
+- WHEN `initGrid()` is called
+- THEN GridStack.init MUST be called with `disableDrag: !this.editMode` and `disableResize: !this.editMode`
+- AND `removable: false` MUST prevent accidental widget removal via drag-out
+
+### REQ-GRID-002: Drag to Reposition
+
+Users MUST be able to drag widgets to new positions on the grid in edit mode.
+
+#### Scenario: Drag a widget to a new position
+- GIVEN the dashboard is in edit mode
+- AND widget "weather_status" is at position (0, 0)
+- WHEN the user drags it to position (4, 2)
+- THEN the widget MUST snap to the grid at position (4, 2)
+- AND other widgets MUST NOT overlap with the repositioned widget
+- AND GridStack MUST automatically push conflicting widgets down if needed
+
+#### Scenario: Drag is disabled in view mode
+- GIVEN the dashboard is in view mode
+- WHEN the user attempts to drag a widget
+- THEN the widget MUST NOT move
+- AND the cursor MUST NOT change to a drag cursor
+- AND no drag handles MUST be visible
+- NOTE: The grid uses `disableDrag: !this.editMode` on initialization and `grid.enable()`/`grid.disable()` when editMode changes via a watcher.
+
+#### Scenario: Drag respects grid boundaries
+- GIVEN a widget with gridWidth 4 at position (0, 0)
+- AND the grid has 12 columns
+- WHEN the user drags it to position (10, 0)
+- THEN the widget MUST NOT be placed at gridX=10 (since 10 + 4 = 14 > 12)
+- AND GridStack MUST constrain the placement to gridX=8 (maximum valid position for gridWidth 4)
+
+#### Scenario: Drag pushes other widgets
+- GIVEN widget A at (0, 0) size 4x2 and widget B at (0, 2) size 4x2
+- WHEN the user drags widget A to (0, 2) (overlapping with B)
+- THEN GridStack MUST push widget B down to (0, 4) to make room
+- AND no overlap MUST occur
+
+#### Scenario: Drag emits position update
+- GIVEN the dashboard is in edit mode
+- WHEN the user drags a widget to a new position
+- THEN the GridStack `change` event MUST fire
+- AND `handleGridChange()` MUST emit `update:placements` with all current placement positions
+
+### REQ-GRID-003: Resize by Edge Dragging
+
+Users MUST be able to resize widgets by dragging their edges or corners in edit mode.
+
+#### Scenario: Resize a widget horizontally
+- GIVEN the dashboard is in edit mode
+- AND widget "notes" is at position (4, 0) with size 4x3
+- WHEN the user drags the right edge to increase width by 2 columns
+- THEN the widget size MUST update to 6x3
+- AND the widget MUST remain at position (4, 0)
+- AND neighboring widgets MUST be pushed if they conflict
+
+#### Scenario: Resize a widget vertically
+- GIVEN widget "weather_status" at position (0, 0) with size 4x2
+- WHEN the user drags the bottom edge to increase height by 1
+- THEN the widget size MUST update to 4x3
+- AND widgets below MUST be pushed down if they conflict
+
+#### Scenario: Resize constrained by minimum size
+- GIVEN a widget with size 4x3
+- WHEN the user tries to resize it smaller than 2x2
+- THEN the widget MUST NOT be smaller than the minimum size (2 columns wide, 2 rows tall)
+- AND GridStack MUST enforce minimum dimensions via `gs-min-w="2"` and `gs-min-h="2"` attributes
+
+#### Scenario: Resize constrained by grid columns
+- GIVEN a widget at position (8, 0) with size 4x2 on a 12-column grid
+- WHEN the user tries to resize it to gridWidth 6
+- THEN the widget width MUST be constrained to 4 (since 8 + 6 = 14 > 12)
+- OR GridStack MUST reposition the widget to allow the resize
+
+#### Scenario: Resize handles not visible in view mode
+- GIVEN the dashboard is in view mode
+- WHEN the user hovers over a widget edge
+- THEN no resize handles MUST be displayed
+- AND the cursor MUST NOT change to a resize cursor
+- NOTE: `disableResize: !this.editMode` on initialization.
+
+### REQ-GRID-004: View Mode vs Edit Mode
+
+The grid MUST support two distinct interaction modes controlled by the `editMode` prop.
+
+#### Scenario: Enter edit mode
+- GIVEN the dashboard is in view mode
+- WHEN the user clicks the "Edit" button (handled by parent component)
+- THEN the grid MUST transition to edit mode via `grid.enable()`
+- AND drag handles MUST become visible on all widget placements
+- AND resize handles MUST become active on widget edges
+
+#### Scenario: Exit edit mode
+- GIVEN the dashboard is in edit mode
+- AND the user has repositioned 2 widgets
+- WHEN the user clicks the "Done" button
+- THEN the grid MUST transition to view mode via `grid.disable()`
+- AND all drag and resize interactions MUST be disabled
+- AND the final positions MUST be persisted via the API (handled by parent component)
+
+#### Scenario: View mode is the default
+- GIVEN the user navigates to their active dashboard
+- WHEN the dashboard loads
+- THEN the grid MUST be in view mode by default (`editMode: false`)
+- AND widgets MUST be static and non-interactive from a grid perspective
+
+#### Scenario: View-only permission prevents edit mode
+- GIVEN dashboard id 5 has `permissionLevel: "view_only"`
+- WHEN the user views the dashboard
+- THEN the "Edit" button MUST NOT be displayed (handled by parent component based on permissionLevel)
+- AND the grid MUST always remain in view mode
+
+#### Scenario: Edit mode watcher responds to prop changes
+- GIVEN the DashboardGrid component is mounted
+- WHEN the `editMode` prop changes from false to true
+- THEN the watcher MUST call `grid.enable()`
+- AND when it changes from true to false, the watcher MUST call `grid.disable()`
+
+### REQ-GRID-005: Position Persistence
+
+Grid position changes MUST be communicated to the parent component for API persistence.
+
+#### Scenario: Save after grid change
+- GIVEN the user drags a widget to a new position
+- WHEN the GridStack `change` event fires
+- THEN the DashboardGrid component MUST emit an `update:placements` event with all updated placement positions
+- NOTE: Debouncing is NOT implemented in DashboardGrid. `handleGridChange` emits immediately on every GridStack change event.
+
+#### Scenario: Multiple rapid changes
+- GIVEN the user rapidly repositions 3 widgets
+- WHEN each repositioning triggers a GridStack change event
+- THEN each change MUST trigger an `update:placements` emit
+- NOTE: Since there is no debounce, rapid changes result in multiple emit calls. The parent component is responsible for coalescing API calls.
+
+#### Scenario: Save failure with retry
+- GIVEN the user repositions a widget
+- AND the API request to save positions fails
+- WHEN the failure is detected
+- THEN the system MUST display an error notification
+- AND the system MUST retry the save automatically (up to 3 retries)
+- NOTE: Save failure/retry is NOT currently implemented in the frontend.
+
+#### Scenario: Concurrent edits from multiple tabs
+- GIVEN user "alice" has the same dashboard open in two browser tabs
+- AND she repositions a widget in tab 1
+- WHEN she repositions a different widget in tab 2
+- THEN each tab MUST independently save its changes
+- AND the last save MUST win (no merge conflict resolution required)
+
+#### Scenario: Change event maps grid items to placements
+- GIVEN the GridStack `change` event fires with an array of updated grid items
+- WHEN `handleGridChange(items)` processes the items
+- THEN each grid item's `id` MUST be matched to a placement's `id` via string comparison
+- AND the placement's gridX, gridY, gridWidth, gridHeight MUST be updated from the grid item's x, y, w, h values
+
+### REQ-GRID-006: Widget Auto-Layout
+
+New widgets added to the dashboard MUST be positioned by GridStack's auto-placement algorithm.
+
+#### Scenario: Add widget to partially filled grid
+- GIVEN the grid has widgets occupying rows 0-2 in columns 0-8
+- AND columns 8-11 in row 0 are empty
+- WHEN the user adds a new widget with gridWidth 4 and gridHeight 2
+- THEN `syncGridItems()` MUST detect the new placement and call `grid.makeWidget()` on the next tick
+- AND GridStack MUST place the widget at an available position
+- NOTE: With `float: true`, auto-placement behavior may differ from non-float mode.
+
+#### Scenario: Add widget to a full row
+- GIVEN all 12 columns in rows 0-3 are occupied
+- WHEN the user adds a new widget with gridWidth 4 and gridHeight 2
+- THEN GridStack MUST place it in the next available row (gridY=4 or later)
+- AND the grid MUST expand vertically to accommodate the new widget
+
+#### Scenario: Remove widget syncs grid
+- GIVEN widget placement id 10 is removed from the placements array
+- WHEN the placements watcher triggers `syncGridItems()`
+- THEN `syncGridItems()` MUST find the orphaned grid node and call `grid.removeWidget()` with `removeDOM: false`
+- AND the grid MUST update its layout accordingly
+
+### REQ-GRID-007: Grid Responsiveness
+
+The grid MUST adapt to the container width while maintaining the configured column count.
+
+#### Scenario: Grid fills container width
+- GIVEN the dashboard container is 1200px wide
+- AND the grid has 12 columns with 12px margins
+- WHEN the grid renders
+- THEN each column MUST be proportionally sized to fill the container width
+- AND the grid MUST fill the full container width
+
+#### Scenario: Grid adapts to container resize
+- GIVEN the user resizes their browser window
+- WHEN the container width changes
+- THEN the grid column width MUST recalculate proportionally
+- AND widget positions MUST remain in their grid coordinates (columns and rows)
+- AND no widget content MUST overflow its cell boundaries
+
+#### Scenario: Minimum grid height
+- GIVEN the dashboard has no widgets or very few widgets
+- WHEN the grid renders
+- THEN the grid container MUST maintain a minimum height of 400px (`.mydash-grid { min-height: 400px }`)
+
+### REQ-GRID-008: Grid Accessibility
+
+The grid MUST support keyboard navigation and screen reader compatibility.
+
+#### Scenario: Keyboard navigation between widgets
+- GIVEN the dashboard is in view mode
+- WHEN the user presses Tab
+- THEN focus MUST move sequentially through widget placements
+- AND each focused widget MUST have a visible focus indicator
+- NOTE: Keyboard navigation is NOT currently implemented.
+
+#### Scenario: Keyboard widget movement in edit mode
+- GIVEN the dashboard is in edit mode
+- AND a widget has keyboard focus
+- WHEN the user presses Arrow keys while holding a modifier key (e.g., Ctrl+Arrow)
+- THEN the widget MUST move one grid cell in the arrow direction
+- NOTE: Keyboard movement is NOT currently implemented.
+
+#### Scenario: Screen reader announces widget positions
+- GIVEN a screen reader is active
+- WHEN a widget receives focus
+- THEN the screen reader MUST announce: the widget title, its grid position, and its size
+- NOTE: ARIA attributes for grid positions are NOT currently implemented.
+
+### REQ-GRID-009: Tile vs Widget Rendering
+
+The grid MUST distinguish between tile placements and widget placements for rendering.
+
+#### Scenario: Tile placement renders TileWidget
+- GIVEN a placement with `tileType: "custom"` and inline tile data (tileTitle, tileIcon, etc.)
+- WHEN the grid renders
+- THEN the placement MUST be rendered using the `TileWidget` component (not `WidgetWrapper`)
+- AND `isTilePlacement()` check uses `placement.tileType === 'custom'`
+- AND `getTileData()` extracts inline tile data from placement fields into a tile object
+
+#### Scenario: Regular widget placement renders WidgetWrapper
+- GIVEN a placement with `tileType: null` and `widgetId: "weather_status"`
+- WHEN the grid renders
+- THEN the placement MUST be rendered using the `WidgetWrapper` component
+- AND the widget data MUST be resolved via `getWidget(placement.widgetId)` from the available widgets array
+
+#### Scenario: TileWidget receives edit mode prop
+- GIVEN a tile placement on a dashboard in edit mode
+- WHEN the tile is rendered
+- THEN `TileWidget` MUST receive `editMode: true`
+- AND an edit button MUST be visible on the tile
+- AND clicking the edit button MUST emit `tile-edit` via the grid component
+
+#### Scenario: WidgetWrapper receives placement and widget data
+- GIVEN a widget placement with `widgetId: "recommendations"`
+- AND the available widgets array contains a widget with `id: "recommendations"`
+- WHEN the grid renders
+- THEN `WidgetWrapper` MUST receive both the `placement` object and the resolved `widget` object
+- AND if no matching widget is found, `widget` MUST be null (graceful degradation)
+
+### REQ-GRID-010: Grid Styling
+
+The grid MUST apply consistent visual styling to all grid items.
+
+#### Scenario: Grid item content styling
+- GIVEN a grid item is rendered
+- WHEN the item is displayed
+- THEN `.grid-stack-item-content` MUST have: background blur via `backdrop-filter`, large border radius via `--border-radius-large`, and `overflow: hidden`
+
+#### Scenario: Placeholder styling during drag
+- GIVEN the user is dragging a widget in edit mode
+- WHEN a placeholder appears showing the drop target
+- THEN `.grid-stack-placeholder > .placeholder-content` MUST have: a primary element light background and a 2px dashed border in primary color with large border radius
+
+#### Scenario: Placement key regeneration
+- GIVEN a widget placement is updated (e.g., style change)
+- WHEN the grid re-renders
+- THEN the placement key MUST include the `updatedAt` timestamp and `styleConfig` hash to force re-rendering via `getPlacementKey()`
+
+### REQ-GRID-011: Grid Synchronization
+
+The grid MUST stay synchronized with the placements prop when items are added or removed externally.
+
+#### Scenario: New placement added to props
+- GIVEN the placements array receives a new placement via the parent component
+- WHEN the `placements` watcher triggers `syncGridItems()`
+- THEN the new placement MUST be added to the grid via `grid.makeWidget()` on `$nextTick()`
+
+#### Scenario: Placement removed from props
+- GIVEN a placement is removed from the placements array
+- WHEN the `placements` watcher triggers `syncGridItems()`
+- THEN the orphaned grid node MUST be detected by comparing placement IDs
+- AND the element MUST be removed via `grid.removeWidget(el, false)`
+
+#### Scenario: Grid destruction on component unmount
+- GIVEN the DashboardGrid component is about to be destroyed
+- WHEN `beforeDestroy` lifecycle hook fires
+- THEN `grid.destroy(false)` MUST be called (false = do not remove DOM elements)
+
+## Non-Functional Requirements
+
+- **Performance**: Grid initialization MUST complete within 500ms for dashboards with up to 30 widget placements. Drag and resize interactions MUST maintain 60fps with no visible lag.
+- **Library version**: GridStack 10.3.1 MUST be used. Upgrades require spec review for breaking changes.
+- **Browser support**: The grid MUST function in all browsers supported by Nextcloud (Chrome, Firefox, Safari, Edge -- latest 2 versions).
+- **Debouncing**: Debouncing is NOT currently implemented in DashboardGrid. The `handleGridChange` method emits immediately on every change event. Debouncing SHOULD be added.
+- **Accessibility**: Grid interactions MUST provide keyboard alternatives for all mouse-based operations. WCAG AA compliance is required.
+
+### Current Implementation Status
+
+**Fully implemented:**
+- REQ-GRID-001 (Grid Initialization): `DashboardGrid.vue` initializes GridStack with all specified options.
+- REQ-GRID-002 (Drag to Reposition): Drag enabled/disabled via `grid.enable()`/`grid.disable()` in editMode watcher.
+- REQ-GRID-003 (Resize by Edge Dragging): Resize controlled via `disableResize: !this.editMode`. Min sizes via `gs-min-w="2"`, `gs-min-h="2"`.
+- REQ-GRID-004 (View Mode vs Edit Mode): `editMode` prop controls grid state.
+- REQ-GRID-005 (Position Persistence): `handleGridChange()` emits `update:placements` on every change event.
+- REQ-GRID-006 (Widget Auto-Layout): `syncGridItems()` adds/removes items.
+- REQ-GRID-009 (Tile vs Widget Rendering): `isTilePlacement()`, `getTileData()` handle rendering distinction.
+- REQ-GRID-010 (Grid Styling): CSS applied via scoped styles with deep selectors.
+- REQ-GRID-011 (Grid Synchronization): `placements` watcher triggers `syncGridItems()`.
+
+**Not yet implemented:**
+- REQ-GRID-005 save failure/retry: No retry logic in frontend.
+- REQ-GRID-005 debouncing: No debounce on handleGridChange.
+- REQ-GRID-007 (Grid Responsiveness): No explicit responsive handling or breakpoints.
+- REQ-GRID-008 (Grid Accessibility): No keyboard navigation, keyboard movement, or ARIA attributes.
+- REQ-GRID-001 empty state: No empty state placeholder.
+
+### Standards & References
+- GridStack 10.3.1: https://gridstackjs.com/
+- WAI-ARIA Grid pattern: https://www.w3.org/WAI/ARIA/apg/patterns/grid/
+- WCAG 2.1 AA: Focus indicators, keyboard operability, screen reader compatibility
+- Nextcloud Vue components: `NcButton` used in parent components for edit/done toggle
diff --git a/openspec/specs/grid-layout/tasks.md b/openspec/changes/archive/2026-03-21-grid-layout/specs/grid-layout/tasks.md
similarity index 100%
rename from openspec/specs/grid-layout/tasks.md
rename to openspec/changes/archive/2026-03-21-grid-layout/specs/grid-layout/tasks.md
diff --git a/openspec/changes/archive/2026-03-21-grid-layout/tasks.md b/openspec/changes/archive/2026-03-21-grid-layout/tasks.md
new file mode 100644
index 00000000..c3049c6f
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-grid-layout/tasks.md
@@ -0,0 +1,12 @@
+# Grid Layout - Tasks
+
+## Tasks
+
+- [x] TASK-GRID-001: Implement DashboardGrid Vue component with GridStack
+- [x] TASK-GRID-002: Implement view mode (static, no interaction)
+- [x] TASK-GRID-003: Implement edit mode (drag-and-drop, resize)
+- [x] TASK-GRID-004: Implement grid change event emission
+- [x] TASK-GRID-005: Implement configurable column count from dashboard settings
+- [x] TASK-GRID-006: Implement minimum widget size constraints (2x2)
+- [x] TASK-GRID-007: Write feature documentation and screenshots (ADR-010)
+- [x] TASK-GRID-008: Verify i18n support for grid UI strings (ADR-005)
diff --git a/openspec/changes/archive/2026-03-21-permissions/.openspec.yaml b/openspec/changes/archive/2026-03-21-permissions/.openspec.yaml
new file mode 100644
index 00000000..d8b0ed03
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-permissions/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-permissions/design.md b/openspec/changes/archive/2026-03-21-permissions/design.md
new file mode 100644
index 00000000..b8221c1e
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-permissions/design.md
@@ -0,0 +1,30 @@
+# Permission Levels - Design Document
+
+## Architecture
+
+### Backend
+- **Service**: `Service\PermissionService` - Central permission checking
+- **Constants**: `Dashboard::PERMISSION_VIEW_ONLY`, `PERMISSION_ADD_ONLY`, `PERMISSION_FULL`
+
+### Permission Matrix
+| Level | View | Add widgets | Edit settings | Move/resize | Remove non-compulsory | Remove compulsory |
+|-------|------|-------------|---------------|-------------|----------------------|-------------------|
+| view_only | Yes | No | No | No | No | No |
+| add_only | Yes | Yes | Yes | Yes | Yes | No |
+| full | Yes | Yes | Yes | Yes | Yes | Yes |
+
+### Methods
+- `canEditDashboard()` - add_only or full
+- `canEditDashboardMetadata()` - any owner (metadata not restricted by permission)
+- `canAddWidget()` - add_only or full
+- `canRemoveWidget()` - full always, add_only for non-compulsory only
+- `canStyleWidget()` - add_only or full
+- `canCreateDashboard()` - checks admin setting
+- `canHaveMultipleDashboards()` - checks admin setting
+- `getEffectivePermissionLevel()` - resolves from template -> dashboard -> default
+
+### Key Design Decisions
+- Permission level inherited from admin template via basedOnTemplate
+- If template deleted, falls back to dashboard's own level
+- Metadata editing (name, description) not restricted by permission level
+- Compulsory flag on placements prevents removal at add_only level
diff --git a/openspec/changes/archive/2026-03-21-permissions/proposal.md b/openspec/changes/archive/2026-03-21-permissions/proposal.md
new file mode 100644
index 00000000..721512b1
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-permissions/proposal.md
@@ -0,0 +1,18 @@
+# Permission Levels Specification
+
+## Problem
+Permission levels control what users can do with their dashboards. When an admin template is distributed to users, the template's permission level is inherited by the user's personal copy, restricting their editing capabilities. This system allows administrators to create locked-down dashboards (e.g., a company-mandated layout with compulsory widgets) while still giving users varying degrees of customization freedom. The three levels -- `view_only`, `add_only`, and `full` -- form a hierarchy of increasing user control.
+
+## Proposed Solution
+Implement Permission Levels Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the permissions specification.
+
+## Success Criteria
+- View-only user sees the dashboard
+- View-only user cannot add widgets
+- View-only user cannot modify widgets
+- View-only user cannot delete widgets
+- View-only user cannot add tiles
diff --git a/openspec/specs/permissions/design.md b/openspec/changes/archive/2026-03-21-permissions/specs/permissions/design.md
similarity index 100%
rename from openspec/specs/permissions/design.md
rename to openspec/changes/archive/2026-03-21-permissions/specs/permissions/design.md
diff --git a/openspec/changes/archive/2026-03-21-permissions/specs/permissions/spec.md b/openspec/changes/archive/2026-03-21-permissions/specs/permissions/spec.md
new file mode 100644
index 00000000..428d8b02
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-permissions/specs/permissions/spec.md
@@ -0,0 +1,362 @@
+---
+status: reviewed
+---
+
+# Permission Levels Specification
+
+## Purpose
+
+Permission levels control what users can do with their dashboards. When an admin template is distributed to users, the template's permission level is inherited by the user's personal copy, restricting their editing capabilities. This system allows administrators to create locked-down dashboards (e.g., a company-mandated layout with compulsory widgets) while still giving users varying degrees of customization freedom. The three levels -- `view_only`, `add_only`, and `full` -- form a hierarchy of increasing user control.
+
+## Permission Level Definitions
+
+| Level | Can view | Can add widgets | Can edit widget settings | Can move/resize | Can remove non-compulsory | Can remove compulsory |
+|-------|----------|-----------------|--------------------------|-----------------|---------------------------|----------------------|
+| `view_only` | Yes | No | No | No | No | No |
+| `add_only` | Yes | Yes | Yes | Yes | Yes (non-compulsory) | No |
+| `full` | Yes | Yes | Yes | Yes | Yes | Yes |
+
+## Requirements
+
+### REQ-PERM-001: View-Only Permission Level
+
+Dashboards with `permissionLevel: "view_only"` MUST restrict users to viewing only, with no widget or layout editing capabilities.
+
+#### Scenario: View-only user sees the dashboard
+- GIVEN user "alice" has a dashboard with effective `permissionLevel: "view_only"` and 5 widget placements
+- WHEN she views the dashboard
+- THEN all 5 widgets MUST be rendered with their content
+- AND the grid MUST be in view mode
+- AND there MUST be no "Edit" button visible
+
+#### Scenario: View-only user cannot add widgets
+- GIVEN user "alice" has a view-only dashboard id 5
+- WHEN she sends POST /api/dashboard/5/widgets with widget data
+- THEN the system MUST return HTTP 403 with a message indicating the dashboard is view-only
+- AND no widget placement MUST be created
+- AND `PermissionService::canAddWidget()` MUST return false for view_only
+
+#### Scenario: View-only user cannot modify widgets
+- GIVEN user "alice" has a view-only dashboard with widget placement id 10
+- WHEN she sends PUT /api/widgets/10 with body `{"custom_title": "New Title"}`
+- THEN the system MUST return HTTP 403
+- AND the widget placement MUST NOT be modified
+- AND `PermissionService::canStyleWidget()` MUST return false for view_only
+
+#### Scenario: View-only user cannot delete widgets
+- GIVEN user "alice" has a view-only dashboard with widget placement id 10
+- WHEN she sends DELETE /api/widgets/10
+- THEN the system MUST return HTTP 403
+- AND the widget placement MUST NOT be deleted
+- AND `PermissionService::canRemoveWidget()` MUST return false for view_only
+
+#### Scenario: View-only user cannot add tiles
+- GIVEN user "alice" has a view-only dashboard id 5
+- WHEN she sends POST /api/dashboard/5/tile with tile data
+- THEN the system MUST return HTTP 403
+- AND `canAddWidget()` MUST block tile additions the same as widget additions
+
+#### Scenario: View-only dashboard hides all editing UI
+- GIVEN user "alice" has a view-only dashboard
+- WHEN she views the dashboard
+- THEN the following UI elements MUST NOT be displayed:
+ - Edit/Done toggle button
+ - Add widget button
+ - Add tile button
+ - Widget context menus (edit, delete, configure)
+ - Grid drag handles and resize handles
+- NOTE: Frontend permission-based UI hiding is NOT currently implemented.
+
+### REQ-PERM-002: Add-Only Permission Level
+
+Dashboards with `permissionLevel: "add_only"` MUST allow users to add and modify widgets but prevent removal of compulsory widgets.
+
+#### Scenario: Add-only user can add widgets
+- GIVEN user "alice" has a dashboard with `permissionLevel: "add_only"`
+- WHEN she sends POST /api/dashboard/5/widgets with widget data
+- THEN the system MUST create the widget placement
+- AND the response MUST return HTTP 201
+
+#### Scenario: Add-only user can edit widget settings
+- GIVEN user "alice" has an add-only dashboard with widget placement id 10
+- WHEN she sends PUT /api/widgets/10 with body `{"customTitle": "My Weather"}`
+- THEN the system MUST update the widget placement
+- AND the response MUST return HTTP 200
+
+#### Scenario: Add-only user can move and resize widgets
+- GIVEN user "alice" has an add-only dashboard in edit mode
+- WHEN she drags widget placement id 10 to a new position
+- THEN the grid MUST allow the move
+- AND the new position MUST be persisted via the API
+
+#### Scenario: Add-only user can remove non-compulsory widgets
+- GIVEN user "alice" has an add-only dashboard with widget placement id 10 (`isCompulsory: 0`)
+- WHEN she sends DELETE /api/widgets/10
+- THEN the system MUST delete the placement
+- AND the response MUST return HTTP 200
+
+#### Scenario: Add-only user cannot remove compulsory widgets
+- GIVEN user "alice" has an add-only dashboard with widget placement id 11 (`isCompulsory: 1`)
+- WHEN she sends DELETE /api/widgets/11
+- THEN the system MUST return HTTP 403 with a message indicating compulsory widgets cannot be removed at this permission level
+- AND `canRemoveWidget()` checks `placement->getIsCompulsory()` and returns false
+
+#### Scenario: Add-only user cannot remove compulsory widgets via UI
+- GIVEN user "alice" has an add-only dashboard in edit mode
+- AND widget placement id 11 is compulsory
+- WHEN she views the widget's context menu or actions
+- THEN the "Remove" or "Delete" option MUST NOT be available for compulsory widgets
+- AND a lock icon or "Required" badge SHOULD be displayed on compulsory widgets
+- NOTE: Compulsory visual indicator is NOT currently implemented.
+
+#### Scenario: Add-only user can add conditional rules
+- GIVEN user "alice" has an add-only dashboard with widget placement id 10 (`isCompulsory: 0`)
+- WHEN she sends POST /api/widgets/10/rules with a conditional rule
+- THEN the system MUST create the rule
+- AND the response MUST return HTTP 201
+
+### REQ-PERM-003: Full Permission Level
+
+Dashboards with `permissionLevel: "full"` MUST allow users complete control over all aspects of the dashboard.
+
+#### Scenario: Full permission user can remove compulsory widgets
+- GIVEN user "alice" has a full-permission dashboard with widget placement id 11 (`isCompulsory: 1`)
+- WHEN she sends DELETE /api/widgets/11
+- THEN the system MUST delete the placement
+- AND `canRemoveWidget()` returns true for full regardless of `isCompulsory`
+
+#### Scenario: Full permission is the default for user-created dashboards
+- GIVEN user "alice" creates a new dashboard via POST /api/dashboard
+- WHEN the dashboard is created
+- THEN `permissionLevel` MUST be set to "full" (via `DashboardFactory::create()` which hardcodes `Dashboard::PERMISSION_FULL`)
+- AND the user MUST have unrestricted editing capabilities
+
+#### Scenario: Full permission user sees all editing UI
+- GIVEN user "alice" has a full-permission dashboard
+- WHEN she views the dashboard
+- THEN the Edit button MUST be visible
+- AND all widget context menus MUST include all options (edit, delete, configure visibility)
+- AND all widgets (including compulsory) MUST show delete options in edit mode
+
+### REQ-PERM-004: Compulsory Widget Marking
+
+Admin templates MUST be able to mark specific widget placements as compulsory, and this flag MUST be inherited by user copies.
+
+#### Scenario: Compulsory flag inherited from template
+- GIVEN an admin template has widget placement with `isCompulsory: 1` for widget "company_news"
+- WHEN user "alice" receives a copy of this template
+- THEN alice's copy of the "company_news" placement MUST have `isCompulsory: 1` (copied via `TemplateService::clonePlacement()`)
+- AND the compulsory flag MUST persist on the user's copy
+
+#### Scenario: Users cannot change the compulsory flag
+- GIVEN widget placement id 10 with `isCompulsory: 1` on alice's dashboard
+- WHEN she sends PUT /api/widgets/10 with body `{"isCompulsory": 0}`
+- THEN the system MUST ignore the `isCompulsory` field in the update
+- OR return HTTP 403 for that specific field
+- AND `isCompulsory` MUST remain 1
+- NOTE: `PlacementUpdater` does not explicitly block `isCompulsory` changes.
+
+#### Scenario: Compulsory widget visual indicator
+- GIVEN a dashboard with both compulsory and non-compulsory widgets
+- WHEN the dashboard is rendered in edit mode
+- THEN compulsory widgets MUST display a visual indicator (e.g., lock icon, "Required" badge)
+- AND the indicator MUST be visible only in edit mode (not in view mode)
+- NOTE: Not currently implemented. `WidgetWrapper.vue` has `canRemove` computed property but no visual badge.
+
+#### Scenario: Non-compulsory widgets on template-derived dashboards
+- GIVEN an admin template has 5 widgets: 3 compulsory and 2 non-compulsory
+- AND user "alice" receives a copy with `permissionLevel: "add_only"`
+- WHEN alice enters edit mode
+- THEN she MUST be able to remove the 2 non-compulsory widgets
+- AND she MUST NOT be able to remove the 3 compulsory widgets
+
+#### Scenario: User-added widgets are never compulsory
+- GIVEN user "alice" has a dashboard with `permissionLevel: "add_only"`
+- WHEN she adds a new widget via POST /api/dashboard/5/widgets
+- THEN the new placement MUST have `isCompulsory: 0` (default via `PlacementService::addWidget()`)
+- AND alice MUST be able to remove this widget even on an add-only dashboard
+
+### REQ-PERM-005: Permission Level Immutability for Users
+
+Users MUST NOT be able to change the permission level on their own dashboards.
+
+#### Scenario: User tries to escalate permission level
+- GIVEN user "alice" has a dashboard with `permissionLevel: "add_only"` (inherited from template)
+- WHEN she sends PUT /api/dashboard/5 with body `{"permissionLevel": "full"}`
+- THEN the system MUST ignore the `permissionLevel` field
+- AND the permissionLevel MUST remain "add_only"
+- NOTE: `DashboardService::applyDashboardUpdates()` only processes `name`, `description`, `gridColumns`, and `placements`. `permissionLevel` is not handled.
+
+#### Scenario: User tries to downgrade permission level
+- GIVEN user "alice" has a dashboard with `permissionLevel: "full"`
+- WHEN she sends PUT /api/dashboard/5 with body `{"permissionLevel": "view_only"}`
+- THEN the system MUST ignore the `permissionLevel` field
+- AND the permissionLevel MUST remain "full"
+
+### REQ-PERM-006: Permission Enforcement on API Level
+
+Permission checks MUST be enforced at the API/service level, not just in the frontend UI.
+
+#### Scenario: API rejects widget addition on view-only dashboard
+- GIVEN dashboard id 5 has `permissionLevel: "view_only"`
+- WHEN any HTTP client sends POST /api/dashboard/5/widgets
+- THEN the system MUST return HTTP 403 regardless of how the request was made (UI, curl, API client)
+
+#### Scenario: API rejects compulsory widget deletion on add-only dashboard
+- GIVEN dashboard id 5 has `permissionLevel: "add_only"`
+- AND widget placement id 11 has `isCompulsory: 1`
+- WHEN any HTTP client sends DELETE /api/widgets/11
+- THEN the system MUST return HTTP 403
+
+#### Scenario: API allows all operations on full-permission dashboard
+- GIVEN dashboard id 5 has `permissionLevel: "full"`
+- WHEN any valid widget/tile operation is sent
+- THEN the system MUST allow the operation (assuming proper ownership)
+
+#### Scenario: Permission checks happen before service calls
+- GIVEN a widget operation request
+- WHEN the controller processes it
+- THEN permission checks (`canAddWidget`, `canStyleWidget`, `canRemoveWidget`) MUST be called before any service method that modifies data
+- AND rejected requests MUST NOT cause any state changes
+
+### REQ-PERM-007: Dashboard Metadata Editing
+
+Permission levels MUST NOT restrict editing of dashboard metadata (name, description) for users who own the dashboard.
+
+#### Scenario: View-only user can edit dashboard name
+- GIVEN user "alice" has a view-only dashboard id 5
+- WHEN she sends PUT /api/dashboard/5 with body `{"name": "Renamed Dashboard"}`
+- THEN the system MUST allow the update via `PermissionService::canEditDashboardMetadata()` which only checks ownership, not permission level
+- AND the dashboard name MUST be updated
+
+#### Scenario: View-only user can delete the dashboard
+- GIVEN user "alice" has a view-only dashboard id 5
+- WHEN she sends DELETE /api/dashboard/5
+- THEN the system MUST allow the deletion
+- AND users always have the right to remove dashboards from their account regardless of permission level
+
+#### Scenario: Metadata editing separate from widget editing
+- GIVEN user "alice" has a view-only dashboard
+- WHEN she tries to update the dashboard
+- THEN `canEditDashboardMetadata()` (ownership only) MUST be used for name/description changes
+- AND `canEditDashboard()` (ownership + permission level) MUST be used for widget/layout changes
+
+### REQ-PERM-008: Effective Permission Level Resolution
+
+The system MUST resolve effective permission levels through a defined chain: source template, dashboard's own level, admin default.
+
+#### Scenario: Template-based permission resolution
+- GIVEN user "alice" has a dashboard with `basedOnTemplate: 42`
+- AND template 42 has `permissionLevel: "add_only"`
+- WHEN `getEffectivePermissionLevel()` is called
+- THEN the system MUST return "add_only" from the source template
+
+#### Scenario: Template deleted, fallback to dashboard level
+- GIVEN user "alice" has a dashboard with `basedOnTemplate: 42` and `permissionLevel: "add_only"`
+- AND template 42 has been deleted
+- WHEN `getEffectivePermissionLevel()` is called
+- THEN the template lookup MUST throw `DoesNotExistException`
+- AND the system MUST fall back to the dashboard's own `permissionLevel: "add_only"`
+
+#### Scenario: No template, no dashboard level, fallback to admin default
+- GIVEN a dashboard with `basedOnTemplate: null` and `permissionLevel: null`
+- AND the admin default is "add_only"
+- WHEN `getEffectivePermissionLevel()` is called
+- THEN the system MUST return the admin default "add_only"
+
+#### Scenario: Admin template changes propagate dynamically
+- GIVEN template 42 has `permissionLevel: "add_only"`
+- AND 10 users have copies with `basedOnTemplate: 42`
+- WHEN the admin changes template 42's `permissionLevel` to "full"
+- THEN all 10 users' effective permission level MUST immediately resolve to "full"
+- AND no migration or re-copying is needed (resolution is dynamic at runtime)
+
+### REQ-PERM-009: Permission-Based Widget Styling
+
+Widget styling (custom title, style config, visibility) MUST respect permission levels via `canStyleWidget()`.
+
+#### Scenario: View-only user cannot style widgets
+- GIVEN user "alice" has a view-only dashboard with widget placement id 10
+- WHEN she sends PUT /api/widgets/10 with any style changes
+- THEN the system MUST return HTTP 403
+- AND `canStyleWidget()` MUST return false for view_only
+
+#### Scenario: Add-only user can style widgets
+- GIVEN user "alice" has an add-only dashboard with widget placement id 10
+- WHEN she sends PUT /api/widgets/10 with body `{"customTitle": "My Widget", "showTitle": 0}`
+- THEN the system MUST allow the update
+- AND `canStyleWidget()` MUST return true for add_only
+
+#### Scenario: Full user can style widgets
+- GIVEN user "alice" has a full-permission dashboard with widget placement id 10
+- WHEN she sends PUT /api/widgets/10 with style changes
+- THEN the system MUST allow the update
+
+### REQ-PERM-010: Ownership Verification
+
+All permission checks MUST verify that the requesting user owns the dashboard or placement before checking permission levels.
+
+#### Scenario: Non-owner cannot modify widgets regardless of permission
+- GIVEN user "alice" has a full-permission dashboard with placement id 10
+- WHEN user "bob" sends any operation on placement 10
+- THEN the system MUST return HTTP 403
+- AND the ownership check MUST happen before the permission level check
+
+#### Scenario: Dashboard ownership check
+- GIVEN user "alice" owns dashboard id 5
+- WHEN `PermissionService::verifyDashboardOwnership("bob", 5)` is called
+- THEN the method MUST throw an exception with "Access denied"
+- AND no permission level evaluation MUST occur
+
+#### Scenario: Placement ownership check via dashboard
+- GIVEN placement id 10 belongs to dashboard id 5 owned by "alice"
+- WHEN `PermissionService::verifyPlacementOwnership("bob", 10)` is called
+- THEN the method MUST look up the placement, find its dashboardId, verify dashboard ownership
+- AND throw "Access denied" since "bob" does not own dashboard 5
+
+### REQ-PERM-011: Admin Template Permission Restrictions
+
+Admin templates MUST only be editable by Nextcloud admin users, not by regular users.
+
+#### Scenario: Regular user cannot edit admin template dashboard
+- GIVEN template id 1 has `type: "admin_template"`
+- WHEN `canEditDashboard("alice", 1)` is called for a regular user
+- THEN the method MUST return false (admin templates are blocked regardless of ownership)
+
+#### Scenario: Admin templates have no userId
+- GIVEN template id 1 has `userId: null`
+- WHEN a regular user tries any operation on template 1
+- THEN the ownership check MUST fail since `null !== "alice"`
+- AND HTTP 403 MUST be returned
+
+## Non-Functional Requirements
+
+- **Security**: Permission checks MUST be enforced server-side in the service layer, not only in the frontend. All permission-related API responses MUST use HTTP 403 with descriptive error messages.
+- **Performance**: Permission level checks MUST add no more than 5ms overhead to any API request. The `getEffectivePermissionLevel()` resolution chain involves at most 2 database queries (template lookup + admin default lookup).
+- **Accessibility**: Permission-related UI states (disabled buttons, lock icons, required badges) MUST be communicated to screen readers via appropriate ARIA attributes.
+- **Localization**: Permission-related error messages and UI labels MUST support English and Dutch.
+
+### Current Implementation Status
+
+**Fully implemented:**
+- REQ-PERM-001 (View-Only): `canAddWidget()`, `canEditDashboard()`, `canRemoveWidget()`, `canStyleWidget()` all return false for view_only.
+- REQ-PERM-002 (Add-Only): `canRemoveWidget()` checks `isCompulsory` for add_only. All other operations permitted.
+- REQ-PERM-003 (Full): `canRemoveWidget()` returns true for full regardless of `isCompulsory`.
+- REQ-PERM-005 (Immutability): `applyDashboardUpdates()` does not process `permissionLevel`.
+- REQ-PERM-006 (API-Level Enforcement): All checks in controller layer before service calls.
+- REQ-PERM-007 (Metadata Editing): `canEditDashboardMetadata()` checks ownership only. `deleteDashboard()` checks ownership only.
+- REQ-PERM-008 (Effective Resolution): `getEffectivePermissionLevel()` chains template -> dashboard -> admin default.
+- REQ-PERM-010 (Ownership Verification): `verifyDashboardOwnership()` and `verifyPlacementOwnership()` implemented.
+- REQ-PERM-011 (Admin Template Restrictions): `canEditDashboard()` blocks admin templates for non-admin users.
+
+**Not yet implemented:**
+- REQ-PERM-004 `isCompulsory` immutability: `PlacementUpdater` does not block `isCompulsory` changes.
+- REQ-PERM-004 visual indicator: No compulsory widget visual indicator in frontend.
+- REQ-PERM-001 frontend UI hiding: No frontend logic hides UI elements based on permission level.
+- REQ-PERM-009 frontend styling restrictions: No frontend enforcement of style editing restrictions.
+
+### Standards & References
+- Nextcloud AppFramework: `OCP\AppFramework\Http\Attribute\NoAdminRequired` for non-admin access
+- HTTP 403 Forbidden: Used consistently for permission denials
+- WCAG 2.1 AA: Disabled states, lock icons, required badges must be communicated to screen readers
+- WAI-ARIA: `aria-disabled`, `aria-label` for permission-restricted UI elements
diff --git a/openspec/specs/permissions/tasks.md b/openspec/changes/archive/2026-03-21-permissions/specs/permissions/tasks.md
similarity index 100%
rename from openspec/specs/permissions/tasks.md
rename to openspec/changes/archive/2026-03-21-permissions/specs/permissions/tasks.md
diff --git a/openspec/changes/archive/2026-03-21-permissions/tasks.md b/openspec/changes/archive/2026-03-21-permissions/tasks.md
new file mode 100644
index 00000000..e47566a1
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-permissions/tasks.md
@@ -0,0 +1,13 @@
+# Permission Levels - Tasks
+
+## Tasks
+
+- [x] TASK-PERM-001: Implement PermissionService with all check methods
+- [x] TASK-PERM-002: Implement effective permission level resolution
+- [x] TASK-PERM-003: Implement compulsory widget protection at add_only level
+- [x] TASK-PERM-004: Implement metadata editing bypass for all permission levels
+- [x] TASK-PERM-005: Integrate permission checks in controllers
+- [x] TASK-PERM-006: Implement frontend permission-aware UI (hide/show controls)
+- [x] TASK-PERM-007: Write unit tests for PermissionService (ADR-009)
+- [x] TASK-PERM-008: Write feature documentation and screenshots (ADR-010)
+- [x] TASK-PERM-009: Verify i18n support for permission UI strings (ADR-005)
diff --git a/openspec/changes/archive/2026-03-21-prometheus-metrics/.openspec.yaml b/openspec/changes/archive/2026-03-21-prometheus-metrics/.openspec.yaml
new file mode 100644
index 00000000..d8b0ed03
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-prometheus-metrics/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-prometheus-metrics/design.md b/openspec/changes/archive/2026-03-21-prometheus-metrics/design.md
new file mode 100644
index 00000000..95c1c349
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-prometheus-metrics/design.md
@@ -0,0 +1,28 @@
+# Prometheus Metrics - Design Document
+
+## Architecture
+
+### Backend
+- **Controller**: `Controller\MetricsController` - Metrics endpoint (admin-only, no CSRF)
+- **Controller**: `Controller\HealthController` - Health check endpoint
+- **Service**: `Service\MetricsCollector` - Orchestrates metric collection
+- **Service**: `Service\MetricsQueryService` - Database queries for counts
+
+### Endpoints
+- `GET /api/metrics` - Prometheus text exposition format (admin-only)
+- `GET /api/health` - Health check (database connectivity)
+
+### Metrics Exposed
+- `mydash_info{version, php_version, nextcloud_version}` - App info gauge
+- `mydash_up` - Application up gauge
+- `mydash_dashboards_total{type}` - Dashboard count by type (personal/template)
+- `mydash_widgets_total` - Total widget placements
+- `mydash_tiles_total` - Total tiles
+
+### Key Design Decisions
+- Metrics computed on-demand (no persistent metrics storage)
+- Prometheus text exposition format 0.0.4
+- Content-Type: text/plain; version=0.0.4; charset=utf-8
+- @NoCSRFRequired for external monitoring tool access
+- @AdminRequired for security (metrics not exposed to regular users)
+- Health endpoint checks database connectivity
diff --git a/openspec/changes/archive/2026-03-21-prometheus-metrics/proposal.md b/openspec/changes/archive/2026-03-21-prometheus-metrics/proposal.md
new file mode 100644
index 00000000..2b5f5a33
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-prometheus-metrics/proposal.md
@@ -0,0 +1,18 @@
+# Prometheus Metrics Specification
+
+## Problem
+Expose application metrics in Prometheus text exposition format at `GET /api/metrics` for monitoring, alerting, and operational dashboards. Additionally, provide a health check endpoint at `GET /api/health` for container orchestration and load balancer readiness probes.
+
+## Proposed Solution
+Implement Prometheus Metrics Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the prometheus-metrics specification.
+
+## Success Criteria
+- Metrics endpoint returns valid Prometheus format
+- Metrics endpoint requires admin authentication
+- Metrics endpoint accessible without CSRF token
+- Metrics response ends with newline
+- Info metric reports versions
diff --git a/openspec/changes/archive/2026-03-21-prometheus-metrics/specs/prometheus-metrics/spec.md b/openspec/changes/archive/2026-03-21-prometheus-metrics/specs/prometheus-metrics/spec.md
new file mode 100644
index 00000000..db64065e
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-prometheus-metrics/specs/prometheus-metrics/spec.md
@@ -0,0 +1,301 @@
+---
+status: reviewed
+---
+
+# Prometheus Metrics Specification
+
+## Purpose
+
+Expose application metrics in Prometheus text exposition format at `GET /api/metrics` for monitoring, alerting, and operational dashboards. Additionally, provide a health check endpoint at `GET /api/health` for container orchestration and load balancer readiness probes.
+
+## Data Model
+
+Metrics are collected at request time from database queries and system information. No persistent metrics storage is used -- all values are computed on-demand.
+
+### Metrics Architecture
+- **MetricsController**: Handles HTTP request, formats output as Prometheus text exposition
+- **MetricsCollector**: Orchestrates metric collection, delegates to MetricsQueryService
+- **MetricsQueryService**: Executes database queries for entity counts
+- **HealthController**: Handles health check requests, performs database connectivity test
+
+## Requirements
+
+### REQ-PROM-001: Metrics Endpoint
+
+The system MUST expose a Prometheus-compatible metrics endpoint accessible to admin users.
+
+#### Scenario: Metrics endpoint returns valid Prometheus format
+- GIVEN a Nextcloud admin user
+- WHEN they send GET /index.php/apps/mydash/api/metrics
+- THEN the system MUST return HTTP 200
+- AND the Content-Type MUST be `text/plain; version=0.0.4; charset=utf-8`
+- AND the body MUST contain metrics in Prometheus text exposition format (lines of `# HELP`, `# TYPE`, and metric values)
+
+#### Scenario: Metrics endpoint requires admin authentication
+- GIVEN a regular (non-admin) Nextcloud user "alice"
+- WHEN she sends GET /api/metrics
+- THEN the system MUST return HTTP 403
+- AND no metrics data MUST be exposed
+
+#### Scenario: Metrics endpoint accessible without CSRF token
+- GIVEN an admin user or monitoring system
+- WHEN GET /api/metrics is sent without a CSRF token
+- THEN the system MUST still return metrics
+- AND the controller MUST have `@NoCSRFRequired` annotation to allow external monitoring tools
+
+#### Scenario: Metrics response ends with newline
+- GIVEN the metrics endpoint is called
+- WHEN the response body is generated
+- THEN the body MUST end with a newline character (Prometheus exposition format requirement)
+- AND each metric MUST be on its own line separated by `\n`
+
+### REQ-PROM-002: Application Info Metric
+
+The system MUST expose an info metric with version labels.
+
+#### Scenario: Info metric reports versions
+- GIVEN the MyDash app version is "1.2.3", PHP version is "8.2.0", and Nextcloud version is "29.0.0"
+- WHEN the metrics endpoint is called
+- THEN the response MUST include:
+ ```
+ # HELP mydash_info Application information
+ # TYPE mydash_info gauge
+ mydash_info{version="1.2.3",php_version="8.2.0",nextcloud_version="29.0.0"} 1
+ ```
+- AND the value MUST always be 1
+
+#### Scenario: Info metric reads app version from config
+- GIVEN the MyDash app is installed
+- WHEN the info metric is collected
+- THEN the app version MUST be read from `IConfig::getAppValue(Application::APP_ID, 'installed_version', '0.0.0')`
+- AND PHP version from `PHP_VERSION`
+- AND Nextcloud version from `IConfig::getSystemValueString('version', '0.0.0')`
+
+#### Scenario: Info metric with missing version
+- GIVEN the app version is not set in config
+- WHEN the info metric is collected
+- THEN the version MUST default to "0.0.0"
+
+### REQ-PROM-003: Application Up Metric
+
+The system MUST expose an up metric indicating application health.
+
+#### Scenario: Up metric when healthy
+- GIVEN the application is running normally
+- WHEN the metrics endpoint is called
+- THEN the response MUST include:
+ ```
+ # HELP mydash_up Whether the application is up
+ # TYPE mydash_up gauge
+ mydash_up 1
+ ```
+
+#### Scenario: Up metric always returns 1 if endpoint is reachable
+- GIVEN the metrics endpoint is accessible
+- WHEN the response is generated
+- THEN `mydash_up` MUST be 1 (if the endpoint can respond, the app is up)
+- NOTE: The current implementation always returns 1. A degraded state (0) would only occur if the endpoint itself cannot respond.
+
+### REQ-PROM-004: Dashboard Count Metrics
+
+The system MUST expose dashboard count metrics grouped by type.
+
+#### Scenario: Dashboard counts by type
+- GIVEN 50 user dashboards and 5 admin templates exist
+- WHEN the metrics endpoint is called
+- THEN the response MUST include:
+ ```
+ # HELP mydash_dashboards_total Total dashboards by type
+ # TYPE mydash_dashboards_total gauge
+ mydash_dashboards_total{type="user"} 50
+ mydash_dashboards_total{type="admin_template"} 5
+ ```
+
+#### Scenario: Dashboard counts with no dashboards
+- GIVEN no dashboards exist in the database
+- WHEN the metrics endpoint is called
+- THEN the response MUST include both types with count 0:
+ ```
+ mydash_dashboards_total{type="personal"} 0
+ mydash_dashboards_total{type="template"} 0
+ ```
+- NOTE: The fallback labels use "personal" and "template" when no data exists, while actual data uses the DB type values ("user", "admin_template").
+
+#### Scenario: Dashboard count query failure
+- GIVEN the database query for dashboards fails
+- WHEN the metrics endpoint is called
+- THEN the system MUST log a warning
+- AND the response MUST include fallback values:
+ ```
+ mydash_dashboards_total{type="personal"} 0
+ mydash_dashboards_total{type="template"} 0
+ ```
+- AND the error MUST NOT cause the entire metrics response to fail
+
+### REQ-PROM-005: Widget Placement Count Metric
+
+The system MUST expose the total number of widget placements.
+
+#### Scenario: Widget placement count
+- GIVEN 150 widget placements exist across all dashboards
+- WHEN the metrics endpoint is called
+- THEN the response MUST include:
+ ```
+ # HELP mydash_widgets_total Total number of widget placements
+ # TYPE mydash_widgets_total gauge
+ mydash_widgets_total 150
+ ```
+
+#### Scenario: Widget count query failure
+- GIVEN the database query for widget placements fails
+- WHEN the metrics endpoint is called
+- THEN the system MUST return 0 for the widget count
+- AND log a warning
+
+### REQ-PROM-006: Tile Count Metric
+
+The system MUST expose the total number of tile definitions.
+
+#### Scenario: Tile count
+- GIVEN 25 tile definitions exist
+- WHEN the metrics endpoint is called
+- THEN the response MUST include:
+ ```
+ # HELP mydash_tiles_total Total number of tiles
+ # TYPE mydash_tiles_total gauge
+ mydash_tiles_total 25
+ ```
+
+#### Scenario: Tile count query failure
+- GIVEN the database query for tiles fails
+- WHEN the metrics endpoint is called
+- THEN the system MUST return 0 for the tile count
+- AND log a warning
+
+### REQ-PROM-007: Health Check Endpoint
+
+The system MUST expose a health check endpoint for monitoring and container orchestration.
+
+#### Scenario: Healthy status
+- GIVEN the database is accessible
+- WHEN GET /index.php/apps/mydash/api/health is called
+- THEN the system MUST return HTTP 200 with JSON:
+ ```json
+ {
+ "status": "ok",
+ "checks": {
+ "database": "ok"
+ }
+ }
+ ```
+
+#### Scenario: Database failure
+- GIVEN the database is not accessible
+- WHEN GET /api/health is called
+- THEN the system MUST return HTTP 200 with JSON:
+ ```json
+ {
+ "status": "error",
+ "checks": {
+ "database": "error"
+ }
+ }
+ ```
+- AND the error MUST be logged via `LoggerInterface::error()`
+
+#### Scenario: Health check requires no CSRF token
+- GIVEN a monitoring system
+- WHEN GET /api/health is sent without CSRF token
+- THEN the system MUST still respond (controller has `@NoCSRFRequired`)
+
+#### Scenario: Health check database test
+- GIVEN the health check is called
+- WHEN the database check runs
+- THEN the system MUST execute a simple `SELECT 1` query via `IDBConnection::getQueryBuilder()`
+- AND if the query succeeds, the database check MUST be "ok"
+- AND if the query throws an exception, the database check MUST be "error"
+
+### REQ-PROM-008: Metrics Collection Architecture
+
+The metrics collection MUST follow a clean architecture with separate concerns.
+
+#### Scenario: MetricsCollector delegates to MetricsQueryService
+- GIVEN the metrics endpoint is called
+- WHEN `MetricsCollector::collectAll()` runs
+- THEN it MUST delegate database queries to `MetricsQueryService`
+- AND format results into Prometheus text lines
+- AND add HELP and TYPE annotations for each metric
+
+#### Scenario: MetricsController formats final output
+- GIVEN `MetricsCollector::collectAll()` returns an array of metric lines
+- WHEN the controller builds the response
+- THEN lines MUST be joined with `\n` and a trailing newline appended
+- AND the response MUST be a `TextPlainResponse` with the correct Content-Type header
+
+#### Scenario: Individual metric collection failures are isolated
+- GIVEN the dashboard count query fails but tile count succeeds
+- WHEN the metrics endpoint is called
+- THEN dashboard metrics MUST show fallback values (0)
+- AND tile metrics MUST show the actual count
+- AND the overall response MUST still be returned (partial failure is acceptable)
+
+### REQ-PROM-009: Active Users Metric
+
+The system SHALL expose the number of active users (users with at least one dashboard).
+
+#### Scenario: Active users count
+- GIVEN 30 unique users have at least one dashboard
+- WHEN the metrics endpoint is called
+- THEN the response SHOULD include:
+ ```
+ # HELP mydash_active_users Users with at least one dashboard
+ # TYPE mydash_active_users gauge
+ mydash_active_users 30
+ ```
+- NOTE: This metric is NOT currently implemented.
+
+### REQ-PROM-010: Metrics Endpoint Performance
+
+The metrics endpoint MUST respond quickly to avoid blocking Prometheus scrape intervals.
+
+#### Scenario: Metrics response under load
+- GIVEN a large installation with 10,000 dashboards, 50,000 widget placements, and 5,000 tiles
+- WHEN the metrics endpoint is called
+- THEN the response MUST return within 2 seconds
+- AND database queries MUST use COUNT aggregation (not loading full entities)
+
+#### Scenario: Concurrent scrapes
+- GIVEN Prometheus scrapes metrics every 15 seconds
+- WHEN two scrapes overlap
+- THEN both requests MUST complete successfully
+- AND no locking or caching issues MUST occur
+
+## Non-Functional Requirements
+
+- **Performance**: GET /api/metrics MUST return within 2 seconds for installations with up to 100,000 rows across all tables. COUNT queries MUST be used rather than loading entities.
+- **Security**: The metrics endpoint MUST require admin authentication. No sensitive data (user IDs, passwords, API keys) MUST be exposed in metrics labels.
+- **Reliability**: Individual metric collection failures MUST NOT cause the entire endpoint to fail. Fallback values (0) MUST be returned for failed queries.
+- **Standards compliance**: Metrics MUST follow the Prometheus text exposition format (version 0.0.4). HELP and TYPE lines MUST be present for every metric.
+- **Monitoring integration**: The health check endpoint MUST be usable by Kubernetes liveness/readiness probes and load balancer health checks.
+
+### Current Implementation Status
+
+**Fully implemented:**
+- REQ-PROM-001 (Metrics Endpoint): `MetricsController::index()` in `lib/Controller/MetricsController.php` returns Prometheus text format with correct Content-Type header. Admin-only (no `#[NoAdminRequired]`). `@NoCSRFRequired` for external monitoring.
+- REQ-PROM-002 (Application Info Metric): Version labels from `IConfig::getAppValue()`, `PHP_VERSION`, and system config.
+- REQ-PROM-003 (Application Up Metric): Always returns 1.
+- REQ-PROM-004 (Dashboard Count Metrics): SQL query with GROUP BY type. Fallback to 0 on error.
+- REQ-PROM-005 (Widget Placement Count): `countTable('mydash_widget_placements')`.
+- REQ-PROM-006 (Tile Count): `countTable('mydash_tiles')`.
+- REQ-PROM-007 (Health Check): `HealthController::index()` in `lib/Controller/HealthController.php` with database connectivity check.
+- REQ-PROM-008 (Architecture): `MetricsCollector` and `MetricsQueryService` exist as separate service classes alongside the controller.
+
+**Not yet implemented:**
+- REQ-PROM-009 (Active Users): No distinct user count metric.
+- Standard metrics from original spec: `mydash_requests_total` (counter), `mydash_request_duration_seconds` (histogram), `mydash_errors_total` (counter) are NOT implemented. These would require middleware/event listeners to track per-request metrics.
+
+### Standards & References
+- Prometheus text exposition format: https://prometheus.io/docs/instrumenting/exposition_formats/
+- OpenMetrics specification: https://openmetrics.io/
+- Nextcloud server monitoring patterns
+- OpenRegister MetricsService and HeartbeatController as reference implementation
diff --git a/openspec/changes/archive/2026-03-21-prometheus-metrics/tasks.md b/openspec/changes/archive/2026-03-21-prometheus-metrics/tasks.md
new file mode 100644
index 00000000..bf09ab0e
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-prometheus-metrics/tasks.md
@@ -0,0 +1,12 @@
+# Prometheus Metrics - Tasks
+
+## Tasks
+
+- [x] TASK-PROM-001: Implement MetricsController with Prometheus output
+- [x] TASK-PROM-002: Implement HealthController with database check
+- [x] TASK-PROM-003: Implement MetricsCollector for all metric types
+- [x] TASK-PROM-004: Implement MetricsQueryService for database counts
+- [x] TASK-PROM-005: Configure routes with NoCSRFRequired annotation
+- [x] TASK-PROM-006: Write unit tests for MetricsCollector (ADR-009)
+- [x] TASK-PROM-007: Write feature documentation and screenshots (ADR-010)
+- [x] TASK-PROM-008: Verify i18n support for health/metrics strings (ADR-005)
diff --git a/openspec/changes/archive/2026-03-21-tiles/.openspec.yaml b/openspec/changes/archive/2026-03-21-tiles/.openspec.yaml
new file mode 100644
index 00000000..d8b0ed03
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-tiles/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-tiles/design.md b/openspec/changes/archive/2026-03-21-tiles/design.md
new file mode 100644
index 00000000..bb03002f
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-tiles/design.md
@@ -0,0 +1,26 @@
+# Custom Tiles - Design Document
+
+## Architecture
+
+### Backend
+- **Entity**: `Db\Tile` - User-owned shortcut card with icon, colors, link
+- **Mapper**: `Db\TileMapper` - CRUD, findByUserId, findByIdAndUser
+- **Service**: `Service\TileService` - Business logic for tile CRUD
+- **Controller**: `Controller\TileApiController` - REST API for tile management
+
+### Frontend
+- **Component**: `components/TileCard.vue` - Renders tile as clickable card
+- **Component**: `components/TileEditor.vue` - Tile creation/editing form
+
+### Data Flow
+1. User creates tile definition via POST /api/tiles
+2. Tile placed on dashboard via POST /api/dashboard/{id}/tile
+3. PlacementService copies tile data inline onto WidgetPlacement
+4. TileCard renders from placement's tile fields (independent snapshot)
+
+### Key Design Decisions
+- Tiles are simple static cards (no dynamic content like widgets)
+- Tile placements store COPIES of tile data (not references)
+- Changes to tile definition do NOT propagate to existing placements
+- widgetId for tile placements: 'tile-' + uniqid()
+- Icon types: class, url, emoji, svg
diff --git a/openspec/changes/archive/2026-03-21-tiles/proposal.md b/openspec/changes/archive/2026-03-21-tiles/proposal.md
new file mode 100644
index 00000000..2b73b469
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-tiles/proposal.md
@@ -0,0 +1,18 @@
+# Custom Tiles Specification
+
+## Problem
+Custom tiles are user-created shortcut cards that provide quick access to Nextcloud apps or external URLs. Unlike widgets (which render dynamic content from Nextcloud apps), tiles are simple, static cards with an icon, label, and link. Tiles are first created as reusable entities in the `oc_mydash_tiles` table, then placed onto dashboards via a special tile placement mechanism that stores tile data inline on the placement. This inline-copy model means tile placements are independent snapshots -- changes to the tile definition do NOT propagate to existing placements.
+
+## Proposed Solution
+Implement Custom Tiles Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the tiles specification.
+
+## Success Criteria
+- Create a tile linking to a Nextcloud app
+- Create a tile linking to an external URL
+- Create a tile with an emoji icon
+- Create a tile with SVG path icon
+- Create a tile with missing required fields
diff --git a/openspec/specs/tiles/design.md b/openspec/changes/archive/2026-03-21-tiles/specs/tiles/design.md
similarity index 100%
rename from openspec/specs/tiles/design.md
rename to openspec/changes/archive/2026-03-21-tiles/specs/tiles/design.md
diff --git a/openspec/changes/archive/2026-03-21-tiles/specs/tiles/spec.md b/openspec/changes/archive/2026-03-21-tiles/specs/tiles/spec.md
new file mode 100644
index 00000000..737a0eb5
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-tiles/specs/tiles/spec.md
@@ -0,0 +1,384 @@
+---
+status: reviewed
+---
+
+# Custom Tiles Specification
+
+## Purpose
+
+Custom tiles are user-created shortcut cards that provide quick access to Nextcloud apps or external URLs. Unlike widgets (which render dynamic content from Nextcloud apps), tiles are simple, static cards with an icon, label, and link. Tiles are first created as reusable entities in the `oc_mydash_tiles` table, then placed onto dashboards via a special tile placement mechanism that stores tile data inline on the placement. This inline-copy model means tile placements are independent snapshots -- changes to the tile definition do NOT propagate to existing placements.
+
+## Data Model
+
+### Tiles (oc_mydash_tiles)
+- **id**: Auto-increment integer primary key
+- **userId**: Nextcloud user ID of the tile creator (STRING, NOT NULL)
+- **title**: Display label for the tile (STRING)
+- **icon**: Icon reference -- can be an emoji character, a CSS class name (e.g., `icon-folder`), or a URL to an image (STRING, up to 2000 chars for SVG paths)
+- **iconType**: Type of icon: `class`, `url`, `emoji`, or `svg` (STRING)
+- **backgroundColor**: Hex color for the tile background (e.g., `#3b82f6`) (STRING)
+- **textColor**: Hex color for the tile text (e.g., `#ffffff`) (STRING)
+- **linkType**: Either `app` (links to a Nextcloud app route) or `url` (links to an external URL) (STRING)
+- **linkValue**: The actual link target (e.g., `/apps/files` or `https://example.com`) (STRING)
+- **createdAt**: Timestamp string (Y-m-d H:i:s)
+- **updatedAt**: Timestamp string (Y-m-d H:i:s)
+
+NOTE: Tiles do NOT have a UUID field. They are identified by their auto-increment integer `id`.
+
+### Tile Placements
+Tiles are placed on dashboards using the same `oc_mydash_widget_placements` table. The tile data is stored INLINE on the placement (not as a foreign key reference):
+- `widgetId` is set to `'tile-' + uniqid()` (NOT null -- the DB column is NOT NULL)
+- `tileType` is set to `'custom'`
+- `tileTitle`, `tileIcon`, `tileIconType`, `tileBackgroundColor`, `tileTextColor`, `tileLinkType`, `tileLinkValue` are copied from the tile data
+
+This means tile placements store a COPY of the tile configuration at creation time, NOT a reference to the `oc_mydash_tiles` record. Changes to a tile definition in `oc_mydash_tiles` do NOT automatically propagate to existing tile placements.
+
+## Requirements
+
+### REQ-TILE-001: Create Custom Tile
+
+Users MUST be able to create reusable custom tile definitions.
+
+#### Scenario: Create a tile linking to a Nextcloud app
+- GIVEN a logged-in user "alice"
+- WHEN she sends POST /api/tiles with body:
+ ```json
+ {
+ "title": "My Files",
+ "icon": "icon-folder",
+ "iconType": "class",
+ "backgroundColor": "#3b82f6",
+ "textColor": "#ffffff",
+ "linkType": "app",
+ "linkValue": "/apps/files"
+ }
+ ```
+- THEN the system MUST create a tile with an auto-increment integer ID (no UUID)
+- AND `userId` MUST be set to "alice"
+- AND the response MUST return HTTP 201 with the full tile object
+
+#### Scenario: Create a tile linking to an external URL
+- GIVEN a logged-in user "alice"
+- WHEN she sends POST /api/tiles with body:
+ ```json
+ {
+ "title": "Company Wiki",
+ "icon": "https://wiki.example.com/favicon.ico",
+ "iconType": "url",
+ "backgroundColor": "#10b981",
+ "textColor": "#ffffff",
+ "linkType": "url",
+ "linkValue": "https://wiki.example.com"
+ }
+ ```
+- THEN the system MUST create the tile with `linkType: "url"`
+- AND the icon MUST be stored as a URL reference
+
+#### Scenario: Create a tile with an emoji icon
+- GIVEN a logged-in user "alice"
+- WHEN she sends POST /api/tiles with body:
+ ```json
+ {"title": "Calendar", "icon": "\ud83d\udcc5", "iconType": "emoji", "linkType": "app", "linkValue": "/apps/calendar"}
+ ```
+- THEN the system MUST store the emoji character as the icon value
+- AND the frontend MUST render the emoji directly as the tile icon
+
+#### Scenario: Create a tile with SVG path icon
+- GIVEN a logged-in user "alice"
+- WHEN she sends POST /api/tiles with `iconType: "svg"` and `icon: "M12 2L2 7v10l10 5 10-5V7z"`
+- THEN the system MUST store the SVG path data as the icon value
+- AND the frontend MUST render the path inside an SVG element
+
+#### Scenario: Create a tile with missing required fields
+- GIVEN a logged-in user
+- WHEN they send POST /api/tiles with body `{"title": "Incomplete"}`
+- THEN the system MUST create the tile with default values: `iconType: 'class'`, `backgroundColor: '#0082c9'`, `textColor: '#ffffff'`, `linkType: 'url'`, `linkValue: '#'`
+- NOTE: The current implementation does NOT validate required fields. All fields have defaults.
+
+#### Scenario: Create a tile with invalid link_type
+- GIVEN a logged-in user
+- WHEN they send POST /api/tiles with body `{"title": "Bad", "linkType": "ftp", "linkValue": "ftp://server"}`
+- THEN the system SHOULD return HTTP 400 with an error indicating that `linkType` must be either "app" or "url"
+- NOTE: Link type validation is NOT currently implemented -- any string value is accepted
+
+### REQ-TILE-002: List User Tiles
+
+Users MUST be able to retrieve all their custom tile definitions, scoped to their user ID.
+
+#### Scenario: List tiles for a user
+- GIVEN user "alice" has 5 custom tiles
+- WHEN she sends GET /api/tiles
+- THEN the system MUST return HTTP 200 with an array of all 5 tiles
+- AND each tile MUST include: id, userId, title, icon, iconType, backgroundColor, textColor, linkType, linkValue, createdAt, updatedAt
+
+#### Scenario: Tiles are user-scoped
+- GIVEN user "alice" has 5 tiles and user "bob" has 3 tiles
+- WHEN "alice" sends GET /api/tiles
+- THEN the response MUST contain only alice's 5 tiles
+- AND bob's tiles MUST NOT be included
+
+#### Scenario: List tiles when none exist
+- GIVEN user "carol" has no custom tiles
+- WHEN she sends GET /api/tiles
+- THEN the system MUST return HTTP 200 with an empty array
+
+### REQ-TILE-003: Update Custom Tile
+
+Users MUST be able to update the properties of their custom tiles with ownership verification.
+
+#### Scenario: Update tile title and colors
+- GIVEN user "alice" has tile id 3 with title "My Files"
+- WHEN she sends PUT /api/tiles/3 with body:
+ ```json
+ {"title": "Documents", "backgroundColor": "#6366f1", "textColor": "#ffffff"}
+ ```
+- THEN the system MUST update the title and colors
+- AND the response MUST return HTTP 200 with the updated tile object
+
+#### Scenario: Update tile link
+- GIVEN user "alice" has tile id 3 with `linkType: "app"` and `linkValue: "/apps/files"`
+- WHEN she sends PUT /api/tiles/3 with body `{"linkType": "url", "linkValue": "https://docs.example.com"}`
+- THEN the system MUST update both linkType and linkValue
+- AND the tile MUST now link to the external URL
+
+#### Scenario: Update another user's tile
+- GIVEN tile id 3 belongs to user "alice"
+- WHEN user "bob" sends PUT /api/tiles/3
+- THEN the system MUST return HTTP 403 (via `TileMapper::findByIdAndUser()` ownership check)
+- AND the tile MUST NOT be modified
+
+#### Scenario: Update tile does NOT reflect on existing placements
+- GIVEN tile id 3 has been placed on 2 of alice's dashboards (tile data was copied inline to placements at creation time)
+- WHEN she updates the tile's title from "My Files" to "Documents" via PUT /api/tiles/3
+- THEN the tile definition in `oc_mydash_tiles` MUST be updated
+- BUT existing placements MUST NOT be affected (they store a copy of the tile data, not a reference)
+
+#### Scenario: Partial update preserves unspecified fields
+- GIVEN tile id 3 with all fields populated
+- WHEN the user sends PUT /api/tiles/3 with body `{"title": "New Title"}`
+- THEN only `title` MUST be updated
+- AND all other fields (icon, iconType, backgroundColor, textColor, linkType, linkValue) MUST remain unchanged
+
+### REQ-TILE-004: Delete Custom Tile
+
+Users MUST be able to delete their custom tile definitions with ownership verification.
+
+#### Scenario: Delete a tile not placed on any dashboard
+- GIVEN user "alice" has tile id 3 that is not placed on any dashboard
+- WHEN she sends DELETE /api/tiles/3
+- THEN the system MUST delete the tile
+- AND the response MUST return HTTP 200
+
+#### Scenario: Delete a tile that is placed on dashboards
+- GIVEN user "alice" has tile id 3 placed on 2 dashboards
+- WHEN she sends DELETE /api/tiles/3
+- THEN the system MUST delete the tile from `oc_mydash_tiles`
+- AND tile placements on dashboards SHOULD also be deleted
+- NOTE: `TileService::deleteTile()` only deletes the tile entity. It does NOT cascade-delete tile placements. Since placements use inline copies (not foreign key references), there is no DB-level cascade.
+
+#### Scenario: Delete another user's tile
+- GIVEN tile id 3 belongs to user "alice"
+- WHEN user "bob" sends DELETE /api/tiles/3
+- THEN the system MUST return HTTP 403 (via `findByIdAndUser()`)
+- AND the tile MUST NOT be deleted
+
+### REQ-TILE-005: Place Tile on Dashboard
+
+Users MUST be able to place tile data onto a dashboard, creating a widget placement with inline tile data.
+
+#### Scenario: Place a tile on a dashboard
+- GIVEN user "alice" has dashboard id 5
+- WHEN she sends POST /api/dashboard/5/tile with body:
+ ```json
+ {"tileTitle": "My Files", "tileIcon": "icon-folder", "tileIconType": "class", "tileBackgroundColor": "#3b82f6", "tileTextColor": "#ffffff", "tileLinkType": "app", "tileLinkValue": "/apps/files", "gridX": 0, "gridY": 0, "gridWidth": 2, "gridHeight": 2}
+ ```
+- THEN the system MUST create a widget placement record with `tileType` set to `"custom"`
+- AND `widgetId` MUST be set to `'tile-' + uniqid()` (NOT null)
+- AND the tile data MUST be stored inline on the placement via `TileUpdater::applyTileConfig()`
+- AND the response MUST return HTTP 201 with the placement object
+
+#### Scenario: Place the same tile on multiple dashboards
+- GIVEN user "alice" has tile data
+- AND alice has dashboards id 5 and id 6
+- WHEN she places the tile on both dashboards
+- THEN both dashboards MUST have independent placement records with inline tile data copies
+- AND deleting the placement from dashboard 5 MUST NOT affect dashboard 6's placement
+
+#### Scenario: User cannot add tile to another user's dashboard
+- GIVEN user "bob" has dashboard id 7
+- WHEN user "alice" tries to POST /api/dashboard/7/tile with tile data
+- THEN the system MUST return HTTP 403 (via `PermissionService::canAddWidget()` ownership check)
+
+#### Scenario: Tile placement defaults
+- GIVEN a tile placement is created
+- WHEN default values are applied
+- THEN `gridWidth` MUST default to 2 and `gridHeight` MUST default to 2 (different from widget default of 4x4)
+- AND `isCompulsory` MUST default to 0
+- AND `isVisible` MUST default to 1
+
+#### Scenario: Tile placement on view-only dashboard blocked
+- GIVEN user "alice" has a view-only dashboard id 5
+- WHEN she sends POST /api/dashboard/5/tile with tile data
+- THEN the system MUST return HTTP 403
+- AND `canAddWidget()` MUST block tile additions on view-only dashboards
+
+### REQ-TILE-006: Tile Icon Rendering
+
+The frontend MUST support four icon formats: emoji, CSS class, URL, and SVG path.
+
+#### Scenario: Render emoji icon
+- GIVEN a tile with `iconType: "emoji"` and `icon: "\ud83d\udcc1"`
+- WHEN the tile is rendered on the dashboard via `TileWidget.vue`
+- THEN the system MUST render the emoji inside a `` at 64px font size
+
+#### Scenario: Render CSS class icon
+- GIVEN a tile with `iconType: "class"` and `icon: "icon-folder"`
+- WHEN the tile is rendered
+- THEN the system MUST apply the CSS class to an `` element
+- AND the icon MUST be 64px with `filter: brightness(0) invert(1)` for white appearance
+
+#### Scenario: Render URL icon
+- GIVEN a tile with `iconType: "url"` and `icon: "https://example.com/logo.png"`
+- WHEN the tile is rendered
+- THEN the system MUST render the URL as an `![]()
` element with `object-fit: contain`
+- AND the image MUST be constrained to the icon area (64px)
+- NOTE: No fallback icon is displayed when a URL icon fails to load.
+
+#### Scenario: Render SVG path icon
+- GIVEN a tile with `iconType: "svg"` and `icon: "M12 2L2 7v10l10 5 10-5V7z"`
+- WHEN the tile is rendered
+- THEN the system MUST render the path inside an `