PDPP

reference-dashboard-notifications Specification

Created Updated openspec/specs/reference-dashboard-notifications/spec.mdView on GitHub →

Purpose

TBD - created by archiving change add-dashboard-web-push-notifications. Update Purpose after archive.

Requirements

Requirement: Dashboard Web Push SHALL be VAPID-configured and optional

The reference dashboard SHALL treat browser Web Push as an optional owner notification channel for pending connector interactions. Web Push delivery SHALL require valid VAPID configuration. The VAPID private key SHALL remain server-only, while the VAPID public key MAY be exposed to authenticated dashboard pages for subscription setup.

Scenario: VAPID is not configured

  • WHEN the reference dashboard starts without complete valid VAPID configuration
  • THEN dashboard Web Push subscription and delivery SHALL be reported as unavailable
  • AND pending connector interactions SHALL remain visible in the dashboard
  • AND ntfy/current notification channels SHALL remain eligible for delivery.

Scenario: VAPID is configured

  • WHEN valid VAPID public and private keys are configured
  • THEN authenticated dashboard pages MAY expose the public key for browser subscription
  • AND the private key SHALL NOT be exposed to browser bundles, service workers, diagnostic responses, logs, or notification payloads.

Requirement: Web Push subscriptions SHALL require authenticated owner opt-in

The reference dashboard SHALL persist browser push subscriptions only after explicit opt-in by an authenticated owner. Subscription management SHALL be owner-scoped and revocable.

Scenario: Unauthenticated subscription creation is attempted

  • WHEN owner authentication is enabled and a request creates, updates, lists, or deletes a Web Push subscription without a valid owner session
  • THEN the request SHALL be rejected
  • AND no subscription endpoint SHALL be persisted, disclosed, updated, or deleted.

Scenario: Authenticated owner opts in

  • WHEN an authenticated owner grants browser notification permission and submits a Push API subscription
  • THEN the reference SHALL persist the endpoint and push keys as an owner-scoped delivery target
  • AND the record SHALL include revocation or deletion state and operational metadata sufficient to troubleshoot delivery without storing notification secrets.

Scenario: Owner revokes a subscription

  • WHEN an authenticated owner disables Web Push for a browser or device
  • THEN the reference SHALL stop sending to that subscription
  • AND it SHOULD delete or mark the subscription revoked
  • AND it SHOULD ask the browser to unsubscribe when the active browser context still has access to the subscription.

Requirement: Push payloads SHALL be non-secret and interaction-scoped

Dashboard Web Push notifications for pending connector interactions SHALL include only non-secret display and routing metadata. The payload SHALL be sufficient to route the owner to the relevant dashboard run or interaction UI, but SHALL NOT carry sensitive connector or interaction values.

Scenario: Pending interaction notification is sent

  • WHEN a connector run enters a pending interaction state and Web Push delivery is attempted
  • THEN the push payload MAY include a title, body, connector display label, run id, interaction id, interaction kind, timestamp, and dashboard-relative URL
  • AND the URL SHALL route to the run or interaction UI protected by normal dashboard owner authentication.

Scenario: Sensitive interaction data exists

  • WHEN the pending interaction concerns credentials, OTP, cookies, account data, raw connector output, tokens, or an interaction answer
  • THEN the push payload SHALL NOT include those values
  • AND the notification text SHALL NOT require the owner to infer or expose secret values on a lock screen.

Scenario: Nonblocking owner-assistance is requested during a manual run

  • WHEN a manual connector run emits an ASSISTANCE progress message with response_contract: "none" and owner_action other than none and progress_posture of running or blocked
  • THEN the reference SHALL fan out a Web Push notification to the owner's active subscriptions
  • AND the notification SHALL route the owner to the durable run page (e.g. /dashboard/runs/{run_id}), not the interaction stream URL, because the owner-side action happens outside PDPP
  • AND the payload SHALL NOT include the connector-supplied assistance message, attachments, or any other free-form connector data.

Scenario: Manual-run progress does not require owner attention

  • WHEN a manual connector run emits ordinary progress (non-ASSISTANCE) or an ASSISTANCE message with owner_action: "none" or response_contract: "response_required"
  • THEN the reference SHALL NOT fan out a Web Push for that progress event
  • AND existing blocking INTERACTION Web Push behavior SHALL remain unchanged.

Requirement: Dashboard SHALL allow owner-initiated Web Push delivery proof

The reference dashboard SHALL expose an owner-authenticated way for a subscribed browser to verify that Web Push delivery reaches it, without inducing a connector run. The proof path SHALL not relax authentication or payload-privacy constraints.

Scenario: Subscribed owner requests a test notification

  • WHEN an authenticated owner with at least one active subscription requests a test notification
  • THEN the reference SHALL send a non-secret test payload to that owner's active subscriptions
  • AND the response SHALL report attempted, sent, and unavailable counts
  • AND the notification click SHALL route to the owner dashboard.

Scenario: Test notification is requested without VAPID configuration

  • WHEN an authenticated owner requests a test notification while VAPID is not configured
  • THEN the reference SHALL refuse with an unavailable status
  • AND no subscription state SHALL be modified.

Scenario: Unauthenticated test notification is attempted

  • WHEN owner authentication is enabled and a request triggers a test notification without a valid owner session
  • THEN the request SHALL be rejected
  • AND no push SHALL be sent.

Requirement: Service worker behavior SHALL be safe and click-through oriented

The dashboard service worker SHALL handle push events by showing safe notifications and SHALL handle notification clicks by focusing or opening the dashboard run/interaction URL.

Scenario: Push event arrives with a valid payload

  • WHEN the service worker receives a dashboard Web Push event for a pending connector interaction
  • THEN it SHALL render a notification using non-secret title/body data
  • AND it SHALL preserve routing metadata needed for click handling.

Scenario: Owner clicks the notification

  • WHEN the owner clicks a pending-interaction notification
  • THEN the service worker SHALL focus an existing matching dashboard client when practical or open a new dashboard window
  • AND the target URL SHALL resolve to the relevant run/interaction UI
  • AND normal owner authentication SHALL still guard any live dashboard state.

Scenario: Malformed push payload is received

  • WHEN the service worker receives a malformed or unknown dashboard push payload
  • THEN it SHALL fail closed by avoiding secret disclosure and avoiding navigation to untrusted URLs.

Requirement: Dashboard opt-in UI SHALL feature-detect browser and PWA support

The dashboard SHALL expose Web Push only when the current browser context can support it and SHALL communicate unsupported states, denied permissions, insecure contexts, and PWA/iOS caveats without blocking other notification paths.

Scenario: Browser support is missing

  • WHEN the browser lacks required Notification API, Push API, service worker, secure-context, or permission support
  • THEN the dashboard SHALL show Web Push as unavailable for that browser context
  • AND it SHALL continue to show pending interactions and ntfy/current notification options.

Scenario: Permission is denied

  • WHEN the owner has denied browser notification permission
  • THEN the dashboard SHALL not repeatedly prompt for permission
  • AND it SHALL explain that notification permission must be changed in browser or OS settings.

Scenario: iOS or PWA constraints apply

  • WHEN the owner uses a platform where Web Push requires an installed PWA, specific browser support, or OS-level notification permission
  • THEN the dashboard SHALL present that limitation as a caveat or setup requirement
  • AND it SHALL not imply that Web Push delivery is guaranteed before those platform requirements are met.

Scenario: Owner installs the dashboard

  • WHEN the owner opens the dashboard from a mobile browser that supports installable web apps
  • THEN the web application manifest SHALL identify the dashboard as a standalone installable app
  • AND the manifest SHALL start installed sessions at the owner dashboard rather than at public documentation or marketing pages.

Requirement: Web Push SHALL augment rather than replace existing channels

The reference implementation SHALL treat Web Push as a best-effort additional channel. Web Push failure, expiration, unavailability, or rejection SHALL NOT hide pending interactions and SHALL NOT prevent ntfy/current notification channels from being used.

Scenario: Web Push send fails

  • WHEN a push provider rejects a subscription or a send attempt fails
  • THEN the reference SHALL record or expose the failure for operator troubleshooting
  • AND it SHALL disable, prune, or mark expired subscriptions when appropriate
  • AND the pending interaction SHALL remain visible through the dashboard.

Scenario: Multiple notification channels are configured

  • WHEN ntfy/current channels and Web Push subscriptions are both configured
  • THEN a pending connector interaction SHALL remain eligible for delivery through the existing channels
  • AND Web Push delivery SHALL NOT be the sole source of operator awareness.

Requirement: Dashboard notification storage and delivery SHALL protect owner privacy

The reference dashboard SHALL minimize stored subscription data and notification content. Subscription endpoints and push keys SHALL be treated as sensitive delivery metadata, and notification delivery SHALL not disclose owner data beyond the authenticated dashboard context.

Scenario: Subscription records are inspected

  • WHEN subscription records are logged, displayed in diagnostics, or returned to dashboard management UI
  • THEN endpoint and key material SHALL be redacted or scoped to authenticated owner management views
  • AND public docs, sandbox pages, and unauthenticated surfaces SHALL NOT disclose push subscription material.

Scenario: A notification is displayed on a shared device

  • WHEN a browser or operating system displays a dashboard notification outside the authenticated dashboard page
  • THEN the notification content SHALL remain limited to non-secret pending-interaction metadata
  • AND live connector data, credentials, tokens, and interaction answers SHALL remain accessible only after normal dashboard authentication.