docs: document plugin vs backend authentication boundaries
Clarify that the native Daily Notification Plugin does not authenticate users or call notification-wakeup-service directly. Authentication belongs in the host app; the plugin only schedules local notifications and orchestrates host-provided content fetch. Add docs/security-boundaries.md with responsibility matrix, auth flow diagram, SPI boundary notes, and a warning against adding backend auth logic to the plugin layer.
This commit is contained in:
Jose Olarte III
228
docs/security-boundaries.md
Normal file
228
docs/security-boundaries.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# Security Boundaries — Native Plugin vs Backend Auth
|
||||
|
||||
**Purpose:** Document intentional architectural boundaries so
|
||||
contributors do not add backend authentication into the plugin layer.
|
||||
|
||||
**Owner:** Development Team
|
||||
**Last Updated:** 2026-05-20
|
||||
**Status:** active
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
The **Daily Notification Plugin** is a **local notification
|
||||
orchestration layer**. It schedules alarms, manages permissions, caches
|
||||
content for offline delivery, and invokes **host-provided** fetch logic
|
||||
when configured.
|
||||
|
||||
It is **not** an authentication client and **not** a backend service
|
||||
client for TimeSafari identity or session management.
|
||||
|
||||
**Authentication belongs in the host app**, which talks to
|
||||
**notification-wakeup-service**. The plugin must never own that flow.
|
||||
|
||||
---
|
||||
|
||||
## Responsibility Matrix
|
||||
|
||||
| Concern | Plugin | Host app | Backend
|
||||
(notification-wakeup-service) |
|
||||
| --- | --- | --- | --- |
|
||||
| User login / session | No | Yes | Yes |
|
||||
| JWT / token issuance | No | Yes (or via backend) | Yes |
|
||||
| Token refresh | No | Yes | Yes |
|
||||
| DID / identity selection | No | Yes | May validate |
|
||||
| Schedule local notifications | Yes | Configures via API | No |
|
||||
| OS permission prompts | Yes | May explain UX | No |
|
||||
| Local SQLite / cache | Yes | No | No |
|
||||
| Prefetch timing (WorkManager, BG tasks) | Yes | No | No |
|
||||
| Fetch notification **content** | Orchestrates only | Implements fetcher | Serves API data |
|
||||
| Business API contracts | No | Yes | Yes |
|
||||
|
||||
---
|
||||
|
||||
## Layer Responsibilities
|
||||
|
||||
### Plugin (`@timesafari/daily-notification-plugin`)
|
||||
|
||||
The plugin **does**:
|
||||
|
||||
- Schedule and cancel **local** notifications (AlarmManager,
|
||||
UNUserNotificationCenter, etc.).
|
||||
- Persist schedules, cached content, and delivery metadata locally.
|
||||
- Run background **prefetch orchestration** (when to fetch, retries,
|
||||
TTL-at-fire).
|
||||
- Request and track **notification permission** status.
|
||||
- Expose a **Service Provider Interface (SPI)** so the host app can
|
||||
supply content in native code (`NativeNotificationContentFetcher`).
|
||||
- Forward **already-obtained** credentials to a registered native
|
||||
fetcher via `configureNativeFetcher()` (passthrough only; see below).
|
||||
- Perform **generic HTTP GET** only when a schedule supplies an
|
||||
explicit `contentFetch.url` (no login, no token refresh, no
|
||||
TimeSafari-specific auth).
|
||||
|
||||
The plugin **does not**:
|
||||
|
||||
- Authenticate users.
|
||||
- Communicate with **notification-wakeup-service** or other backend
|
||||
auth endpoints **as an auth client**.
|
||||
- Sign JWTs, manage refresh tokens, or implement OAuth/OIDC flows.
|
||||
- Encode TimeSafari-specific identity or API contracts in plugin code.
|
||||
|
||||
### Backend (`notification-wakeup-service` and related APIs)
|
||||
|
||||
The backend **does**:
|
||||
|
||||
- Authenticate users and establish sessions (exact mechanism is owned
|
||||
by the TimeSafari platform).
|
||||
- Issue, validate, and refresh credentials used for API access.
|
||||
- Expose wakeup / notification-related APIs consumed by the **app**,
|
||||
not by the plugin directly.
|
||||
|
||||
The backend **does not**:
|
||||
|
||||
- Depend on the Capacitor plugin for login or session lifecycle.
|
||||
- Assume the plugin will call auth endpoints on its own.
|
||||
|
||||
### Host app (TimeSafari / consuming Capacitor application)
|
||||
|
||||
The app **does**:
|
||||
|
||||
- Authenticate the user against **notification-wakeup-service**
|
||||
(and any related identity services).
|
||||
- Obtain and refresh tokens **before** background fetch runs.
|
||||
- Register `NativeNotificationContentFetcher` in native code and
|
||||
implement `fetchContent()` using app-owned HTTP clients and auth.
|
||||
- Call plugin APIs to configure schedules, permissions, and optional
|
||||
`configureNativeFetcher()` with **pre-generated** tokens from app code.
|
||||
- Handle auth failures (401/403), logout, and identity changes without
|
||||
expecting the plugin to recover sessions.
|
||||
|
||||
The app **does not**:
|
||||
|
||||
- Assume the plugin will log in or refresh credentials on its behalf.
|
||||
|
||||
---
|
||||
|
||||
## Authentication Flow (Authoritative)
|
||||
|
||||
Authentication **does not** go through the plugin.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant App as Host app
|
||||
participant Auth as notification-wakeup-service
|
||||
participant Plugin as Daily Notification Plugin
|
||||
participant OS as OS notification APIs
|
||||
|
||||
User->>App: Sign in / unlock identity
|
||||
App->>Auth: Authenticate (credentials, DID, etc.)
|
||||
Auth-->>App: Session / tokens
|
||||
App->>App: Build or obtain JWT for API fetch
|
||||
App->>Plugin: configureNativeFetcher(tokens from app)
|
||||
App->>Plugin: registerNativeFetcher(app implementation)
|
||||
Plugin->>Plugin: Schedule prefetch / notify alarms
|
||||
Plugin->>App: NativeNotificationContentFetcher.fetchContent()
|
||||
Note over App: App uses tokens from Auth;<br/>not plugin auth logic
|
||||
App-->>Plugin: NotificationContent list
|
||||
Plugin->>OS: Show local notification
|
||||
```
|
||||
|
||||
**Rule:** `App → notification-wakeup-service` for authentication.
|
||||
The plugin sits **below** that boundary and only receives outputs the
|
||||
app chooses to pass in (e.g. a JWT string for a registered fetcher).
|
||||
|
||||
---
|
||||
|
||||
## Native Content Fetcher (SPI Boundary)
|
||||
|
||||
Background workers **cannot** rely on JavaScript bridges. The plugin
|
||||
calls **`NativeNotificationContentFetcher`**, which the **host app
|
||||
implements and registers**.
|
||||
|
||||
- **Plugin:** When to fetch, timeouts, retries, cache write, notify
|
||||
scheduling.
|
||||
- **Host fetcher:** How to call APIs, which headers to send, how to
|
||||
handle 401 and refresh **in app code**.
|
||||
|
||||
Example pattern (conceptual): the fetcher uses a token the app already
|
||||
minted; the plugin never signs JWTs. See
|
||||
`android/.../NativeNotificationContentFetcher.java` Javadoc.
|
||||
|
||||
`configureNativeFetcher()` stores or forwards `apiBaseUrl`, `activeDid`,
|
||||
and `jwtToken` supplied by the app. It is **configuration passthrough**,
|
||||
not an authentication implementation. Tokens are **not** persisted by
|
||||
default (`persistToken` defaults to `false`).
|
||||
|
||||
---
|
||||
|
||||
## Explicit Non-Goals (Plugin)
|
||||
|
||||
The following are **intentionally out of scope** for this repository:
|
||||
|
||||
1. **User authentication** — no login UI, no credential storage for
|
||||
platform identity, no session store tied to wakeup-service.
|
||||
2. **Direct backend auth traffic** — the plugin must not implement
|
||||
clients for `notification-wakeup-service` auth/login/refresh routes.
|
||||
3. **Backend business logic** — plans, offers, projects, and community
|
||||
rules live in app + backend, not in the plugin.
|
||||
|
||||
The plugin’s job is **local reliability**: prefetch → cache → schedule →
|
||||
display.
|
||||
|
||||
---
|
||||
|
||||
## Warning — Do Not Add Backend Auth to the Plugin
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ DO NOT add backend authentication logic to the plugin │
|
||||
│ layer (TypeScript bridge, Android Kotlin/Java, iOS Swift). │
|
||||
│ │
|
||||
│ Wrong: JWT signing, refresh flows, or HTTP clients to │
|
||||
│ notification-wakeup-service auth endpoints inside │
|
||||
│ DailyNotificationPlugin / FetchWorker / iOS plugin│
|
||||
│ │
|
||||
│ Right: Implement auth in the host app; register a native │
|
||||
│ fetcher; pass short-lived tokens from app code. │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Why this matters:**
|
||||
|
||||
- **Security:** Auth secrets and refresh logic stay in one place (the
|
||||
app), subject to app review and platform keychains.
|
||||
- **Coupling:** The plugin stays reusable across apps and test harnesses.
|
||||
- **Background limits:** OS background tasks must stay short; auth
|
||||
refresh belongs in app lifecycle, not plugin workers.
|
||||
- **Audit clarity:** Security reviewers can treat wakeup-service + app
|
||||
as the trust boundary; the plugin is untrusted for identity.
|
||||
|
||||
If integration docs elsewhere mention “plugin provides authentication,”
|
||||
treat that as **orchestration of fetch timing**, not **identity
|
||||
authentication**. This document is the security boundary reference.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- `doc/integration/REFACTOR_NOTES.md` — SPI refactor; host-owned fetch
|
||||
- `doc/integration/REFACTOR_NOTES_QUICK_START.md` — “JWT generation in
|
||||
host app only”
|
||||
- `android/.../NativeNotificationContentFetcher.java` — SPI contract
|
||||
- `ARCHITECTURE.md` — broader system design (encryption, local storage)
|
||||
|
||||
---
|
||||
|
||||
## Assumptions & Limits
|
||||
|
||||
- **notification-wakeup-service** is named as the TimeSafari auth/wakeup
|
||||
entry point per platform architecture; endpoint details live in app
|
||||
and backend repos, not here.
|
||||
- Generic `contentFetch.url` HTTP GET in the plugin is a **legacy /
|
||||
optional** path for URL-configured schedules; new integrations should
|
||||
prefer the native fetcher SPI with app-owned auth.
|
||||
- This document does not change runtime behavior; it records existing
|
||||
intent for reviewers and implementers.
|
||||
Reference in New Issue
Block a user