docs: add RFC specifications (txt + pdf) organized by category (core, mail, contacts, calendar, sieve, quotas, auth)
This commit is contained in:
Linus Rath
@@ -0,0 +1,937 @@
|
||||
# Addons, Plugins & Themes — Architecture Concept
|
||||
|
||||
> **Status**: Draft Concept
|
||||
> **Date**: 2026-03-13
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#1-overview)
|
||||
2. [Terminology](#2-terminology)
|
||||
3. [Manifest Format](#3-manifest-format)
|
||||
4. [Themes](#4-themes)
|
||||
5. [Plugins](#5-plugins)
|
||||
6. [Addon Lifecycle](#6-addon-lifecycle)
|
||||
7. [Extension Points (Hooks & Slots)](#7-extension-points-hooks--slots)
|
||||
8. [Security & Sandboxing](#8-security--sandboxing)
|
||||
9. [Storage & Distribution](#9-storage--distribution)
|
||||
10. [Settings Integration](#10-settings-integration)
|
||||
11. [API Surface](#11-api-surface)
|
||||
12. [Migration Path](#12-migration-path)
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
This document describes a system that allows the JMAP Webmail application to be extended through **themes** (visual customization) and **plugins** (functional extensions). Together, these are called **addons**.
|
||||
|
||||
### Design Goals
|
||||
|
||||
- **Safe by default** — addons cannot break core functionality or access data beyond their declared scope.
|
||||
- **Zero-config for users** — install, enable, done. No code changes to the host app.
|
||||
- **Declarative where possible** — prefer JSON/CSS-based customization over imperative code.
|
||||
- **Aligned with existing architecture** — builds on Zustand stores, React context/providers, CSS variables, and the Next.js App Router patterns already in use.
|
||||
- **Incrementally adoptable** — the core app can ship without any addons; the addon system is a layer on top.
|
||||
|
||||
### Non-Goals (for v1)
|
||||
|
||||
- Server-side plugin execution (all addons run client-side).
|
||||
- A public addon marketplace (addons are self-hosted or bundled).
|
||||
- Modifying JMAP protocol behavior (addons consume JMAP data, not intercept it).
|
||||
|
||||
---
|
||||
|
||||
## 2. Terminology
|
||||
|
||||
| Term | Definition |
|
||||
|------|-----------|
|
||||
| **Addon** | Any installable extension — umbrella term for themes and plugins. |
|
||||
| **Theme** | An addon that only customizes visual appearance (colors, fonts, spacing, density). Ships as CSS + a manifest. Contains no executable code. |
|
||||
| **Plugin** | An addon that adds or modifies functionality. Ships as a JS/TS module + a manifest. May include a theme. |
|
||||
| **Slot** | A named insertion point in the UI where plugins can render components. |
|
||||
| **Hook Point** | A named event or state transition where plugins can run logic. |
|
||||
| **Manifest** | A `addon.json` file that declares metadata, permissions, and extension points. |
|
||||
|
||||
---
|
||||
|
||||
## 3. Manifest Format
|
||||
|
||||
Every addon has an `addon.json` at its root:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
// ── Identity ──
|
||||
"id": "com.example.my-addon", // Reverse-domain unique ID
|
||||
"name": "My Addon",
|
||||
"version": "1.0.0", // Semver
|
||||
"description": "A brief description.",
|
||||
"author": {
|
||||
"name": "Jane Doe",
|
||||
"url": "https://example.com"
|
||||
},
|
||||
"license": "MIT",
|
||||
"homepage": "https://example.com/my-addon",
|
||||
|
||||
// ── Compatibility ──
|
||||
"engine": {
|
||||
"webmail": ">=1.0.0" // Required host app version range
|
||||
},
|
||||
|
||||
// ── Type ──
|
||||
"type": "plugin", // "theme" | "plugin"
|
||||
|
||||
// ── Entry Points (plugins only) ──
|
||||
"main": "dist/index.js", // Plugin entry module
|
||||
"styles": "dist/styles.css", // Optional supplementary CSS
|
||||
|
||||
// ── Theme Definition (themes, or plugins that include a theme) ──
|
||||
"theme": {
|
||||
"variables": "theme.css", // CSS file with variable overrides
|
||||
"presets": ["light", "dark"], // Which base modes it provides
|
||||
"preview": "preview.png" // Screenshot for settings UI
|
||||
},
|
||||
|
||||
// ── Permissions (plugins only) ──
|
||||
"permissions": [
|
||||
"emails:read", // Read email data from store
|
||||
"emails:write", // Modify email data (move, flag, etc.)
|
||||
"contacts:read",
|
||||
"calendar:read",
|
||||
"settings:read",
|
||||
"settings:write",
|
||||
"notifications", // Show toasts / browser notifications
|
||||
"compose:toolbar", // Add buttons to composer toolbar
|
||||
"sidebar:section", // Add sections to the sidebar
|
||||
"viewer:action", // Add actions to email viewer toolbar
|
||||
"navigation:tab", // Add a top-level navigation tab
|
||||
"context-menu:email", // Extend email context menu
|
||||
"keyboard-shortcuts", // Register keyboard shortcuts
|
||||
"external-fetch" // Fetch external URLs (declared origins)
|
||||
],
|
||||
|
||||
// ── External Origins (if external-fetch permission is declared) ──
|
||||
"allowedOrigins": [
|
||||
"https://api.example.com"
|
||||
],
|
||||
|
||||
// ── Slots (declares which UI slots the plugin uses) ──
|
||||
"slots": [
|
||||
"sidebar.bottom",
|
||||
"compose.toolbar",
|
||||
"viewer.actions"
|
||||
],
|
||||
|
||||
// ── Settings Schema (plugin-specific preferences) ──
|
||||
"settings": {
|
||||
"apiKey": {
|
||||
"type": "string",
|
||||
"label": "API Key",
|
||||
"description": "Your API key for the service.",
|
||||
"secret": true
|
||||
},
|
||||
"enabled": {
|
||||
"type": "boolean",
|
||||
"label": "Enable integration",
|
||||
"default": true
|
||||
}
|
||||
},
|
||||
|
||||
// ── i18n ──
|
||||
"locales": "locales/" // Directory with {locale}.json files
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Themes
|
||||
|
||||
Themes are the simplest addon type — pure CSS, no executable code.
|
||||
|
||||
### 4.1 How Themes Work
|
||||
|
||||
The app already uses CSS custom properties (variables) for all colors, defined in `globals.css` under `:root` and `.dark`. A theme overrides these variables:
|
||||
|
||||
```css
|
||||
/* theme.css — "Nord" theme example */
|
||||
|
||||
:root[data-theme="com.example.nord"] {
|
||||
--color-background: #eceff4;
|
||||
--color-foreground: #2e3440;
|
||||
--color-primary: #5e81ac;
|
||||
--color-primary-foreground: #eceff4;
|
||||
--color-border: #d8dee9;
|
||||
--color-sidebar-bg: #e5e9f0;
|
||||
--color-sidebar-hover: #d8dee9;
|
||||
--color-muted: #4c566a;
|
||||
--color-accent: #88c0d0;
|
||||
--color-destructive: #bf616a;
|
||||
|
||||
/* Extended variables for advanced customization */
|
||||
--font-family-base: "Inter", sans-serif;
|
||||
--font-family-mono: "JetBrains Mono", monospace;
|
||||
--radius-base: 8px;
|
||||
--spacing-density: 1; /* 0.8 = compact, 1 = normal, 1.2 = comfortable */
|
||||
--shadow-elevation-1: 0 1px 3px rgba(0,0,0,0.08);
|
||||
}
|
||||
|
||||
:root[data-theme="com.example.nord"].dark {
|
||||
--color-background: #2e3440;
|
||||
--color-foreground: #eceff4;
|
||||
--color-primary: #88c0d0;
|
||||
--color-border: #3b4252;
|
||||
--color-sidebar-bg: #3b4252;
|
||||
--color-sidebar-hover: #434c5e;
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 Theme Application
|
||||
|
||||
```
|
||||
User selects theme in Settings → Appearance
|
||||
→ ThemeStore sets `activeTheme: "com.example.nord"`
|
||||
→ <html data-theme="com.example.nord" class="dark|light">
|
||||
→ Theme CSS is loaded via a <link> tag with the theme's CSS file
|
||||
→ CSS specificity ensures theme variables override defaults
|
||||
```
|
||||
|
||||
### 4.3 Theme Capabilities
|
||||
|
||||
| Capability | Mechanism |
|
||||
|-----------|-----------|
|
||||
| Colors | Override `--color-*` CSS variables |
|
||||
| Typography | Override `--font-family-*` variables |
|
||||
| Spacing/density | Override `--spacing-density` multiplier |
|
||||
| Border radius | Override `--radius-*` variables |
|
||||
| Shadows | Override `--shadow-*` variables |
|
||||
| Dark mode variant | Provide `.dark` overrides |
|
||||
| Tag/label colors | Override `--tag-color-*` palette |
|
||||
| Custom CSS | Additional rules scoped under `[data-theme="..."]` |
|
||||
|
||||
### 4.4 Theme Constraints
|
||||
|
||||
- Themes **cannot** add or remove DOM elements.
|
||||
- Themes **cannot** execute JavaScript.
|
||||
- Themes **cannot** override layout structure (flexbox directions, grid templates).
|
||||
- Theme CSS is scoped by `[data-theme]` attribute — removing the attribute instantly reverts to defaults.
|
||||
- A maximum CSS file size is enforced (e.g., 100 KB) to prevent abuse.
|
||||
|
||||
---
|
||||
|
||||
## 5. Plugins
|
||||
|
||||
Plugins are JavaScript modules that interact with the app through a controlled API.
|
||||
|
||||
### 5.1 Plugin Entry Point
|
||||
|
||||
A plugin exports a single `activate` function and optionally a `deactivate` function:
|
||||
|
||||
```ts
|
||||
// index.ts — Plugin entry point
|
||||
import type { PluginContext } from "@jmap-webmail/addon-api";
|
||||
|
||||
export function activate(ctx: PluginContext) {
|
||||
// Register a sidebar section
|
||||
ctx.slots.register("sidebar.bottom", {
|
||||
component: MySidebarWidget,
|
||||
priority: 10,
|
||||
});
|
||||
|
||||
// Register a composer toolbar button
|
||||
ctx.slots.register("compose.toolbar", {
|
||||
component: EncryptButton,
|
||||
priority: 50,
|
||||
});
|
||||
|
||||
// Listen to store changes
|
||||
ctx.hooks.on("email:selected", (email) => {
|
||||
// React to email selection
|
||||
});
|
||||
|
||||
// Register a keyboard shortcut
|
||||
ctx.shortcuts.register({
|
||||
key: "g t",
|
||||
description: "Open translation panel",
|
||||
action: () => ctx.panels.open("translate"),
|
||||
});
|
||||
|
||||
// Add a context menu item
|
||||
ctx.contextMenu.register("email", {
|
||||
label: ctx.i18n.t("translateEmail"),
|
||||
icon: "Languages",
|
||||
action: (emailId) => { /* ... */ },
|
||||
});
|
||||
}
|
||||
|
||||
export function deactivate(ctx: PluginContext) {
|
||||
// Cleanup — called when the plugin is disabled or uninstalled.
|
||||
// All slot registrations and event subscriptions are
|
||||
// automatically cleaned up, so this is only needed
|
||||
// for external resource cleanup.
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 PluginContext API
|
||||
|
||||
The `PluginContext` object is the plugin's only interface to the host app. It is scoped and sandboxed based on the declared permissions:
|
||||
|
||||
```ts
|
||||
interface PluginContext {
|
||||
/** Plugin metadata from manifest */
|
||||
manifest: AddonManifest;
|
||||
|
||||
/** UI slot registration */
|
||||
slots: {
|
||||
register(slotId: string, registration: SlotRegistration): Disposable;
|
||||
};
|
||||
|
||||
/** Event hooks */
|
||||
hooks: {
|
||||
on(event: HookEvent, handler: Function): Disposable;
|
||||
once(event: HookEvent, handler: Function): Disposable;
|
||||
};
|
||||
|
||||
/** Store access (read-only or read-write based on permissions) */
|
||||
stores: {
|
||||
emails: PluginEmailStore; // If emails:read or emails:write
|
||||
contacts: PluginContactStore; // If contacts:read
|
||||
calendar: PluginCalendarStore; // If calendar:read
|
||||
settings: PluginSettingsStore; // If settings:read or settings:write
|
||||
};
|
||||
|
||||
/** Plugin-specific settings (defined in manifest "settings" schema) */
|
||||
config: {
|
||||
get<T>(key: string): T;
|
||||
set(key: string, value: unknown): void;
|
||||
onChange(key: string, handler: (value: unknown) => void): Disposable;
|
||||
};
|
||||
|
||||
/** Toast notifications */
|
||||
notifications: {
|
||||
success(message: string): void;
|
||||
error(message: string): void;
|
||||
info(message: string): void;
|
||||
};
|
||||
|
||||
/** i18n — scoped to plugin's locale files */
|
||||
i18n: {
|
||||
t(key: string, params?: Record<string, string>): string;
|
||||
locale: string;
|
||||
};
|
||||
|
||||
/** Keyboard shortcuts */
|
||||
shortcuts: {
|
||||
register(shortcut: ShortcutDefinition): Disposable;
|
||||
};
|
||||
|
||||
/** Context menu extensions */
|
||||
contextMenu: {
|
||||
register(target: ContextMenuTarget, item: ContextMenuItem): Disposable;
|
||||
};
|
||||
|
||||
/** Panel API — open side panels or modals */
|
||||
panels: {
|
||||
open(panelId: string, props?: Record<string, unknown>): void;
|
||||
close(panelId: string): void;
|
||||
register(panelId: string, component: React.ComponentType): Disposable;
|
||||
};
|
||||
|
||||
/** Scoped fetch — only allowed origins from manifest */
|
||||
fetch(url: string, init?: RequestInit): Promise<Response>;
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 Disposable Pattern
|
||||
|
||||
All registrations return a `Disposable` object. On plugin deactivation, all disposables are automatically cleaned up:
|
||||
|
||||
```ts
|
||||
interface Disposable {
|
||||
dispose(): void;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Addon Lifecycle
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Addon Lifecycle │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────┐ install ┌───────────┐ enable │
|
||||
│ │ Store │────────────▶│ Installed │──────────┐ │
|
||||
│ │ / URL │ │ (disabled) │ │ │
|
||||
│ └─────────┘ └───────────┘ ▼ │
|
||||
│ ▲ ┌──────────┐ │
|
||||
│ disable│ │ Active │ │
|
||||
│ │ │(running) │ │
|
||||
│ └───────────┤ │ │
|
||||
│ └──────────┘ │
|
||||
│ │ ▲ │
|
||||
│ uninstall update│ │
|
||||
│ │ │ │
|
||||
│ ▼ ┌────┴─────┐ │
|
||||
│ ┌────────┐ │ Updating │ │
|
||||
│ │Removed │ └──────────┘ │
|
||||
│ └────────┘ │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 6.1 Loading Sequence
|
||||
|
||||
1. **Boot**: App starts, `AddonManager` reads the addon registry from `localStorage` (list of installed addons + enabled state).
|
||||
2. **Resolve**: For each enabled addon, load its manifest and verify compatibility (`engine.webmail`).
|
||||
3. **Load Themes**: Inject theme CSS `<link>` for the active theme.
|
||||
4. **Load Plugins**: Dynamically import each plugin's `main` entry point.
|
||||
5. **Activate**: Call `activate(ctx)` for each plugin, passing a scoped `PluginContext`.
|
||||
6. **Ready**: Emit `app:ready` hook — plugins can now interact with stores.
|
||||
|
||||
### 6.2 Addon Manager Store
|
||||
|
||||
A new Zustand store manages addon state:
|
||||
|
||||
```ts
|
||||
interface AddonManagerState {
|
||||
/** Registry of all installed addons */
|
||||
addons: Record<string, InstalledAddon>;
|
||||
|
||||
/** Currently active theme ID (null = default) */
|
||||
activeTheme: string | null;
|
||||
|
||||
/** Actions */
|
||||
installAddon(source: AddonSource): Promise<void>;
|
||||
uninstallAddon(id: string): void;
|
||||
enableAddon(id: string): void;
|
||||
disableAddon(id: string): void;
|
||||
setActiveTheme(id: string | null): void;
|
||||
getAddon(id: string): InstalledAddon | undefined;
|
||||
getEnabledPlugins(): InstalledAddon[];
|
||||
}
|
||||
|
||||
interface InstalledAddon {
|
||||
manifest: AddonManifest;
|
||||
enabled: boolean;
|
||||
installedAt: string; // ISO timestamp
|
||||
source: AddonSource; // Where it was loaded from
|
||||
runtimeState: "inactive" | "active" | "error";
|
||||
error?: string; // Last activation error
|
||||
}
|
||||
|
||||
type AddonSource =
|
||||
| { type: "bundled" } // Shipped with the app
|
||||
| { type: "url"; url: string } // Loaded from a URL
|
||||
| { type: "local"; path: string }; // Development: local file
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Extension Points (Hooks & Slots)
|
||||
|
||||
### 7.1 UI Slots
|
||||
|
||||
Slots are named insertion points scattered across the UI. The host app renders a `<Slot>` component at each point; plugins register components into slots.
|
||||
|
||||
```tsx
|
||||
// Host app — in sidebar.tsx
|
||||
import { Slot } from "@/components/addons/slot";
|
||||
|
||||
function Sidebar() {
|
||||
return (
|
||||
<aside>
|
||||
{/* ... existing sidebar content ... */}
|
||||
<Slot name="sidebar.bottom" />
|
||||
</aside>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
```tsx
|
||||
// Slot component implementation
|
||||
function Slot({ name }: { name: string }) {
|
||||
const registrations = useAddonSlot(name);
|
||||
if (registrations.length === 0) return null;
|
||||
|
||||
return (
|
||||
<>
|
||||
{registrations
|
||||
.sort((a, b) => a.priority - b.priority)
|
||||
.map((reg) => (
|
||||
<AddonErrorBoundary key={reg.addonId} addonId={reg.addonId}>
|
||||
<reg.component />
|
||||
</AddonErrorBoundary>
|
||||
))}
|
||||
</>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
#### Available Slots
|
||||
|
||||
| Slot Name | Location | Use Case |
|
||||
|-----------|----------|----------|
|
||||
| `sidebar.top` | Top of sidebar, below compose button | Quick-access widgets |
|
||||
| `sidebar.bottom` | Bottom of sidebar, above storage quota | Extra navigation, widgets |
|
||||
| `navigation.tabs` | Navigation rail, below contacts icon | New top-level views |
|
||||
| `compose.toolbar` | Composer toolbar (formatting bar) | Encrypt, translate, AI assist buttons |
|
||||
| `compose.footer` | Below composer body, above send button | Send-time options (delay, schedule) |
|
||||
| `viewer.actions` | Email viewer toolbar | Custom actions (translate, summarize) |
|
||||
| `viewer.header` | Above email body in viewer | Banners, warnings, metadata |
|
||||
| `viewer.footer` | Below email body in viewer | Related content, suggestions |
|
||||
| `list.toolbar` | Above email list | Additional filters, bulk actions |
|
||||
| `settings.sections` | Settings page, below existing sections | Plugin settings panels |
|
||||
| `calendar.toolbar` | Calendar view toolbar | Calendar-specific actions |
|
||||
| `contacts.toolbar` | Contacts view toolbar | Contact-specific actions |
|
||||
|
||||
### 7.2 Hook Events
|
||||
|
||||
Plugins can listen to app events and state transitions:
|
||||
|
||||
#### Email Hooks
|
||||
|
||||
| Event | Payload | Description |
|
||||
|-------|---------|-------------|
|
||||
| `email:selected` | `{ emailId, email }` | User selected an email |
|
||||
| `email:opened` | `{ emailId, email }` | Email viewer rendered |
|
||||
| `email:compose:open` | `{ mode, replyTo? }` | Composer opened |
|
||||
| `email:compose:before-send` | `{ draft }` | Before sending — can modify draft |
|
||||
| `email:compose:sent` | `{ emailId }` | Email sent successfully |
|
||||
| `email:moved` | `{ emailId, from, to }` | Email moved between mailboxes |
|
||||
| `email:deleted` | `{ emailId }` | Email deleted |
|
||||
| `email:flagged` | `{ emailId, flags }` | Email flags changed |
|
||||
|
||||
#### Calendar Hooks
|
||||
|
||||
| Event | Payload | Description |
|
||||
|-------|---------|-------------|
|
||||
| `calendar:event:created` | `{ event }` | New event created |
|
||||
| `calendar:event:updated` | `{ event, changes }` | Event modified |
|
||||
| `calendar:event:deleted` | `{ eventId }` | Event deleted |
|
||||
| `calendar:view:changed` | `{ view, date }` | Calendar view switched |
|
||||
|
||||
#### Contact Hooks
|
||||
|
||||
| Event | Payload | Description |
|
||||
|-------|---------|-------------|
|
||||
| `contact:selected` | `{ contactId }` | Contact selected |
|
||||
| `contact:created` | `{ contact }` | New contact created |
|
||||
| `contact:updated` | `{ contact }` | Contact modified |
|
||||
|
||||
#### App Hooks
|
||||
|
||||
| Event | Payload | Description |
|
||||
|-------|---------|-------------|
|
||||
| `app:ready` | `{}` | App fully loaded |
|
||||
| `app:theme:changed` | `{ theme }` | Theme switched |
|
||||
| `app:locale:changed` | `{ locale }` | Language changed |
|
||||
| `app:navigation` | `{ from, to }` | User navigated between views |
|
||||
|
||||
---
|
||||
|
||||
## 8. Security & Sandboxing
|
||||
|
||||
### 8.1 Permission Model
|
||||
|
||||
Plugins declare required permissions in their manifest. On installation, the user sees a permission prompt:
|
||||
|
||||
```
|
||||
"My Translation Plugin" requests:
|
||||
✉️ Read your emails
|
||||
🔔 Show notifications
|
||||
🌐 Connect to https://api.translate.example.com
|
||||
|
||||
[Allow] [Cancel]
|
||||
```
|
||||
|
||||
Permissions are enforced at the `PluginContext` level — if a plugin didn't declare `emails:read`, `ctx.stores.emails` is `undefined`.
|
||||
|
||||
### 8.2 Sandboxing Strategy
|
||||
|
||||
| Layer | Mechanism |
|
||||
|-------|-----------|
|
||||
| **Store access** | `PluginContext` exposes only permitted store slices. Write access returns proxied objects — mutations are validated before applying. |
|
||||
| **DOM access** | Plugin components render inside an `<AddonErrorBoundary>`. They receive a scoped React tree — no direct `document` manipulation. |
|
||||
| **Network** | `ctx.fetch()` is a controlled wrapper. Requests are only allowed to origins listed in `allowedOrigins`. All other `fetch` / `XMLHttpRequest` calls from plugin code are blocked via CSP headers. |
|
||||
| **Storage** | Plugins use `ctx.config` (backed by a namespaced key in `localStorage`). No direct `localStorage` / `sessionStorage` access. |
|
||||
| **Error isolation** | Each plugin slot is wrapped in an `AddonErrorBoundary`. A crashing plugin is caught and disabled without affecting the rest of the app. |
|
||||
| **Resource limits** | Plugin CSS is limited to 100 KB. Plugin JS bundles are limited to 500 KB (configurable). |
|
||||
|
||||
### 8.3 Content Security Policy
|
||||
|
||||
Theme CSS is sanitized to disallow:
|
||||
- `url()` references to external domains (only data URIs and same-origin).
|
||||
- `@import` statements.
|
||||
- `expression()` or `behavior:` (legacy IE attack vectors).
|
||||
|
||||
### 8.4 Error Boundary
|
||||
|
||||
```tsx
|
||||
function AddonErrorBoundary({ addonId, children }) {
|
||||
return (
|
||||
<ErrorBoundary
|
||||
fallback={<AddonCrashedNotice addonId={addonId} />}
|
||||
onError={(error) => {
|
||||
console.error(`[Addon: ${addonId}] Crashed:`, error);
|
||||
addonManager.reportError(addonId, error);
|
||||
// Auto-disable after 3 crashes in 5 minutes
|
||||
}}
|
||||
>
|
||||
{children}
|
||||
</ErrorBoundary>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Storage & Distribution
|
||||
|
||||
### 9.1 Addon Formats
|
||||
|
||||
| Format | Description | Use Case |
|
||||
|--------|-------------|----------|
|
||||
| **Bundled** | Shipped inside the app's `/addons/` directory | Default themes, first-party plugins |
|
||||
| **URL** | Loaded from a remote URL at runtime | Self-hosted or third-party addons |
|
||||
| **Local file** | Loaded from a local path (dev mode only) | Plugin development |
|
||||
|
||||
### 9.2 Addon Bundle Structure
|
||||
|
||||
```
|
||||
my-addon/
|
||||
├── addon.json # Manifest (required)
|
||||
├── dist/
|
||||
│ ├── index.js # Plugin entry (plugins only)
|
||||
│ └── styles.css # Additional styles (optional)
|
||||
├── theme.css # Theme variables (themes only)
|
||||
├── preview.png # Theme preview image (optional)
|
||||
└── locales/
|
||||
├── en.json # English strings
|
||||
├── fr.json # French strings
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 9.3 Built-in Addon Directory
|
||||
|
||||
```
|
||||
addons/
|
||||
├── themes/
|
||||
│ ├── nord/
|
||||
│ │ ├── addon.json
|
||||
│ │ ├── theme.css
|
||||
│ │ └── preview.png
|
||||
│ ├── dracula/
|
||||
│ ├── solarized/
|
||||
│ ├── catppuccin/
|
||||
│ └── high-contrast/
|
||||
└── plugins/
|
||||
└── (none bundled by default)
|
||||
```
|
||||
|
||||
### 9.4 Installation Flow
|
||||
|
||||
**From URL:**
|
||||
1. User pastes addon URL into Settings → Addons → "Install from URL".
|
||||
2. App fetches `{url}/addon.json`, validates schema and compatibility.
|
||||
3. Manifest is stored in addon registry (`localStorage`).
|
||||
4. On next activation, the addon's assets are fetched and cached.
|
||||
|
||||
**Bundled:**
|
||||
1. Addons in `/addons/` are auto-discovered at build time.
|
||||
2. A generated `addon-registry.json` maps addon IDs to their local paths.
|
||||
3. Bundled addons appear pre-installed (but can be disabled).
|
||||
|
||||
---
|
||||
|
||||
## 10. Settings Integration
|
||||
|
||||
### 10.1 Addon Settings Page
|
||||
|
||||
A new page at `/settings/addons` integrates into the existing settings layout:
|
||||
|
||||
```
|
||||
Settings
|
||||
├── Appearance
|
||||
├── Language & Region
|
||||
├── Email
|
||||
├── Composer
|
||||
├── Calendar
|
||||
├── Privacy & Security
|
||||
├── Keyboard Shortcuts
|
||||
├── Addons ← NEW
|
||||
│ ├── Themes
|
||||
│ │ ├── Default (active)
|
||||
│ │ ├── Nord
|
||||
│ │ ├── Dracula
|
||||
│ │ └── [Install Theme...]
|
||||
│ ├── Plugins
|
||||
│ │ ├── Translation Plugin (enabled) [Settings] [Disable]
|
||||
│ │ ├── PGP Encryption (disabled) [Enable] [Uninstall]
|
||||
│ │ └── [Install Plugin...]
|
||||
│ └── Developer
|
||||
│ └── [Load from local path...]
|
||||
```
|
||||
|
||||
### 10.2 Plugin-Specific Settings
|
||||
|
||||
Plugins declare their settings schema in `addon.json`. The app auto-generates a settings UI:
|
||||
|
||||
```jsonc
|
||||
// In addon.json
|
||||
"settings": {
|
||||
"provider": {
|
||||
"type": "select",
|
||||
"label": "Translation Provider",
|
||||
"options": [
|
||||
{ "value": "deepl", "label": "DeepL" },
|
||||
{ "value": "google", "label": "Google Translate" }
|
||||
],
|
||||
"default": "deepl"
|
||||
},
|
||||
"targetLanguage": {
|
||||
"type": "select",
|
||||
"label": "Default Target Language",
|
||||
"options": "locales", // Special: populated from app locales
|
||||
"default": "en"
|
||||
},
|
||||
"autoTranslate": {
|
||||
"type": "boolean",
|
||||
"label": "Auto-translate foreign emails",
|
||||
"default": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Supported setting types: `string`, `boolean`, `number`, `select`, `multiselect`, `color`, `secret` (masked input).
|
||||
|
||||
### 10.3 Theme Selector
|
||||
|
||||
The existing Appearance settings page gains a theme gallery:
|
||||
|
||||
```
|
||||
Appearance
|
||||
├── Theme: [Default ▾] ← dropdown with installed themes
|
||||
│ Preview: [████████████████] ← live color preview strip
|
||||
├── Mode: Light / Dark / System
|
||||
├── Font Size: Small / Medium / Large
|
||||
└── ...
|
||||
```
|
||||
|
||||
When a theme is selected, the app:
|
||||
1. Sets `data-theme` attribute on `<html>`.
|
||||
2. Loads the theme's CSS file.
|
||||
3. Persists the choice in `ThemeStore`.
|
||||
|
||||
---
|
||||
|
||||
## 11. API Surface
|
||||
|
||||
### 11.1 Core Registry (`AddonRegistry`)
|
||||
|
||||
```ts
|
||||
class AddonRegistry {
|
||||
/** Register a slot for plugin component injection */
|
||||
defineSlot(name: string, options?: SlotOptions): void;
|
||||
|
||||
/** Get all registrations for a slot */
|
||||
getSlotRegistrations(name: string): SlotRegistration[];
|
||||
|
||||
/** Subscribe to slot changes (for reactive rendering) */
|
||||
onSlotChange(name: string, cb: () => void): Disposable;
|
||||
|
||||
/** Emit a hook event to all listening plugins */
|
||||
emitHook(event: string, payload: unknown): void;
|
||||
|
||||
/** Emit a hook event that plugins can modify (pipeline) */
|
||||
emitHookPipeline<T>(event: string, value: T): T;
|
||||
}
|
||||
```
|
||||
|
||||
### 11.2 Hook Pipeline (Interceptors)
|
||||
|
||||
Some hooks allow plugins to transform data flowing through them. For example, `email:compose:before-send` lets plugins modify the draft before it's sent:
|
||||
|
||||
```ts
|
||||
// Plugin: auto-add disclaimer
|
||||
ctx.hooks.on("email:compose:before-send", (draft) => {
|
||||
return {
|
||||
...draft,
|
||||
htmlBody: draft.htmlBody + "<p>Sent from JMAP Webmail</p>",
|
||||
};
|
||||
});
|
||||
```
|
||||
|
||||
Pipeline hooks execute in priority order. If any handler throws, the pipeline is aborted and the action is cancelled (with a notification to the user).
|
||||
|
||||
### 11.3 React Hooks for Addon Developers
|
||||
|
||||
```ts
|
||||
// Available inside plugin components:
|
||||
|
||||
/** Access the plugin's scoped context */
|
||||
usePluginContext(): PluginContext;
|
||||
|
||||
/** Access plugin-specific settings (reactive) */
|
||||
usePluginConfig<T>(key: string): [T, (value: T) => void];
|
||||
|
||||
/** Access plugin's i18n */
|
||||
usePluginI18n(): { t: (key: string, params?: Record<string, string>) => string };
|
||||
|
||||
/** Access host app theme info */
|
||||
useHostTheme(): { mode: "light" | "dark"; resolvedMode: "light" | "dark" };
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Migration Path
|
||||
|
||||
### Phase 1: Foundation
|
||||
|
||||
- [ ] Define the complete `addon.json` schema with JSON Schema validation.
|
||||
- [ ] Create the `AddonManagerStore` (Zustand store for managing installed addons).
|
||||
- [ ] Extend `ThemeStore` with `activeTheme` and `data-theme` attribute management.
|
||||
- [ ] Implement CSS variable injection for themes.
|
||||
- [ ] Add 3–5 bundled themes (Nord, Dracula, Solarized, Catppuccin, High Contrast).
|
||||
- [ ] Add the theme selector to Settings → Appearance.
|
||||
|
||||
### Phase 2: Plugin Infrastructure
|
||||
|
||||
- [ ] Implement the `<Slot>` component and `AddonErrorBoundary`.
|
||||
- [ ] Add `<Slot>` insertion points to the 12 defined locations in the UI.
|
||||
- [ ] Build the `PluginContext` factory with permission-gated store access.
|
||||
- [ ] Implement the hook event system (`emitHook`, `emitHookPipeline`).
|
||||
- [ ] Create the Settings → Addons page with install/enable/disable/uninstall UI.
|
||||
- [ ] Implement auto-generated settings UI from plugin settings schema.
|
||||
|
||||
### Phase 3: Developer Experience
|
||||
|
||||
- [ ] Create `@jmap-webmail/addon-api` — TypeScript type definitions package.
|
||||
- [ ] Create `create-jmap-addon` CLI scaffolding tool.
|
||||
- [ ] Write addon developer documentation with examples.
|
||||
- [ ] Build a sample plugin (e.g., email translation) as a reference.
|
||||
- [ ] Add dev mode: hot-reload addons from local filesystem.
|
||||
|
||||
### Phase 4: Hardening
|
||||
|
||||
- [ ] Security audit of the sandboxing layer.
|
||||
- [ ] CSP header configuration for addon CSS/JS.
|
||||
- [ ] Rate limiting for hook events (prevent infinite loops).
|
||||
- [ ] Performance budgets: measure and enforce bundle size + render time limits.
|
||||
- [ ] Auto-disable addons that crash repeatedly.
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Example Addons
|
||||
|
||||
### A. Theme: "Nord"
|
||||
|
||||
```
|
||||
nord-theme/
|
||||
├── addon.json
|
||||
├── theme.css
|
||||
└── preview.png
|
||||
```
|
||||
|
||||
`addon.json`:
|
||||
```json
|
||||
{
|
||||
"id": "org.nordtheme.jmap-webmail",
|
||||
"name": "Nord",
|
||||
"version": "1.0.0",
|
||||
"type": "theme",
|
||||
"description": "An arctic, north-bluish color palette.",
|
||||
"author": { "name": "Arctic Ice Studio" },
|
||||
"license": "MIT",
|
||||
"engine": { "webmail": ">=1.0.0" },
|
||||
"theme": {
|
||||
"variables": "theme.css",
|
||||
"presets": ["light", "dark"],
|
||||
"preview": "preview.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### B. Plugin: "Email Translator"
|
||||
|
||||
```
|
||||
email-translator/
|
||||
├── addon.json
|
||||
├── dist/
|
||||
│ └── index.js
|
||||
└── locales/
|
||||
├── en.json
|
||||
└── fr.json
|
||||
```
|
||||
|
||||
`addon.json`:
|
||||
```json
|
||||
{
|
||||
"id": "com.example.email-translator",
|
||||
"name": "Email Translator",
|
||||
"version": "1.0.0",
|
||||
"type": "plugin",
|
||||
"description": "Translate emails with one click.",
|
||||
"author": { "name": "JMAP Community" },
|
||||
"license": "MIT",
|
||||
"engine": { "webmail": ">=1.0.0" },
|
||||
"main": "dist/index.js",
|
||||
"permissions": [
|
||||
"emails:read",
|
||||
"notifications",
|
||||
"viewer:action",
|
||||
"external-fetch"
|
||||
],
|
||||
"allowedOrigins": ["https://api.deepl.com"],
|
||||
"slots": ["viewer.actions"],
|
||||
"settings": {
|
||||
"apiKey": {
|
||||
"type": "secret",
|
||||
"label": "DeepL API Key"
|
||||
},
|
||||
"targetLanguage": {
|
||||
"type": "select",
|
||||
"label": "Target Language",
|
||||
"options": "locales",
|
||||
"default": "en"
|
||||
}
|
||||
},
|
||||
"locales": "locales/"
|
||||
}
|
||||
```
|
||||
|
||||
### C. Plugin: "Send Later"
|
||||
|
||||
Adds a "Schedule Send" button to the composer:
|
||||
|
||||
```ts
|
||||
export function activate(ctx: PluginContext) {
|
||||
ctx.slots.register("compose.footer", {
|
||||
component: ScheduleSendPicker,
|
||||
priority: 10,
|
||||
});
|
||||
|
||||
ctx.hooks.on("email:compose:before-send", (draft) => {
|
||||
const scheduledTime = ctx.config.get<string>("pendingSchedule");
|
||||
if (scheduledTime) {
|
||||
// Store the scheduled time — the host app handles deferred sending
|
||||
return { ...draft, deliverAt: scheduledTime };
|
||||
}
|
||||
return draft;
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. **Should plugins be able to define new routes (pages)?** Adding full pages (e.g., `/addons/my-plugin/dashboard`) would require deeper Next.js integration. Could use a `navigation:tab` slot that renders a full-pane view instead.
|
||||
|
||||
2. **Web Worker isolation?** Running plugin JS in a Web Worker would provide stronger isolation but prevents direct React rendering. A message-passing bridge is possible but adds complexity. Probably not worth it for v1.
|
||||
|
||||
3. **Server-side plugins?** Some use cases (email filtering, webhook integrations) need server execution. This is out of scope for v1 but could be explored as Sieve filter generation or JMAP push notification handlers.
|
||||
|
||||
4. **Addon signing?** For URL-installed addons, a signature verification system would prevent tampering. Worth considering for v2.
|
||||
|
||||
5. **Shared dependencies?** Should plugins be able to declare peer dependencies on the host app's packages (React, date-fns, Lucide icons)? This would reduce bundle sizes but creates coupling. Recommend providing these as globals via the plugin runtime.
|
||||
Binary file not shown.
File diff suppressed because it is too large
Load Diff
Binary file not shown.
File diff suppressed because it is too large
Load Diff
Binary file not shown.
File diff suppressed because it is too large
Load Diff
Binary file not shown.
@@ -0,0 +1,857 @@
|
||||
|
||||
|
||||
|
||||
|
||||
Internet Engineering Task Force (IETF) N. Jenkins, Ed.
|
||||
Request for Comments: 9670 Fastmail
|
||||
Updates: 8620 November 2024
|
||||
Category: Standards Track
|
||||
ISSN: 2070-1721
|
||||
|
||||
|
||||
JSON Meta Application Protocol (JMAP) Sharing
|
||||
|
||||
Abstract
|
||||
|
||||
This document specifies a data model for sharing data between users
|
||||
using the JSON Meta Application Protocol (JMAP). Future documents
|
||||
can reference this document when defining data types to support a
|
||||
consistent model of sharing.
|
||||
|
||||
Status of This Memo
|
||||
|
||||
This is an Internet Standards Track document.
|
||||
|
||||
This document is a product of the Internet Engineering Task Force
|
||||
(IETF). It represents the consensus of the IETF community. It has
|
||||
received public review and has been approved for publication by the
|
||||
Internet Engineering Steering Group (IESG). Further information on
|
||||
Internet Standards is available in Section 2 of RFC 7841.
|
||||
|
||||
Information about the current status of this document, any errata,
|
||||
and how to provide feedback on it may be obtained at
|
||||
https://www.rfc-editor.org/info/rfc9670.
|
||||
|
||||
Copyright Notice
|
||||
|
||||
Copyright (c) 2024 IETF Trust and the persons identified as the
|
||||
document authors. All rights reserved.
|
||||
|
||||
This document is subject to BCP 78 and the IETF Trust's Legal
|
||||
Provisions Relating to IETF Documents
|
||||
(https://trustee.ietf.org/license-info) in effect on the date of
|
||||
publication of this document. Please review these documents
|
||||
carefully, as they describe your rights and restrictions with respect
|
||||
to this document. Code Components extracted from this document must
|
||||
include Revised BSD License text as described in Section 4.e of the
|
||||
Trust Legal Provisions and are provided without warranty as described
|
||||
in the Revised BSD License.
|
||||
|
||||
Table of Contents
|
||||
|
||||
1. Introduction
|
||||
1.1. Notational Conventions
|
||||
1.2. Terminology
|
||||
1.3. Data Model Overview
|
||||
1.4. Subscribing to Shared Data
|
||||
1.5. Addition to the Capabilities Object
|
||||
1.5.1. urn:ietf:params:jmap:principals
|
||||
1.5.2. urn:ietf:params:jmap:principals:owner
|
||||
2. Principals
|
||||
2.1. Principal/get
|
||||
2.2. Principal/changes
|
||||
2.3. Principal/set
|
||||
2.4. Principal/query
|
||||
2.4.1. Filtering
|
||||
2.5. Principal/queryChanges
|
||||
3. ShareNotifications
|
||||
3.1. ShareNotification/get
|
||||
3.2. ShareNotification/changes
|
||||
3.3. ShareNotification/set
|
||||
3.4. ShareNotification/query
|
||||
3.4.1. Filtering
|
||||
3.4.2. Sorting
|
||||
3.5. ShareNotification/queryChanges
|
||||
4. Framework for Shared Data
|
||||
4.1. Example
|
||||
5. Internationalization Considerations
|
||||
6. Security Considerations
|
||||
6.1. Spoofing
|
||||
6.2. Unnoticed Sharing
|
||||
6.3. Denial of Service
|
||||
6.4. Unauthorized Principals
|
||||
7. IANA Considerations
|
||||
7.1. JMAP Capability Registration for "principals"
|
||||
7.2. JMAP Capability Registration for "principals:owner"
|
||||
7.3. JMAP Data Type Registration for "Principal"
|
||||
7.4. JMAP Data Type Registration for "ShareNotification"
|
||||
8. References
|
||||
8.1. Normative References
|
||||
8.2. Informative References
|
||||
Author's Address
|
||||
|
||||
1. Introduction
|
||||
|
||||
The JSON Meta Application Protocol (JMAP) [RFC8620] is a generic
|
||||
protocol for synchronizing data, such as mail, calendars, or
|
||||
contacts, between a client and a server. It is optimized for mobile
|
||||
and web environments and provides a consistent interface to query,
|
||||
read, and modify different data types, including comprehensive error
|
||||
handling.
|
||||
|
||||
This specification defines a data model to represent entities in a
|
||||
collaborative environment and a framework for sharing data between
|
||||
them that can be used to provide a consistent sharing model for
|
||||
different data types. It does not define _what_ may be shared or the
|
||||
granularity of permissions, as this will depend on the data in
|
||||
question.
|
||||
|
||||
1.1. Notational Conventions
|
||||
|
||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
|
||||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
|
||||
"OPTIONAL" in this document are to be interpreted as described in
|
||||
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
|
||||
capitals, as shown here.
|
||||
|
||||
Type signatures, examples, and property descriptions in this document
|
||||
follow the conventions established in Section 1.1 of [RFC8620]. Data
|
||||
types defined in the core specification are also used in this
|
||||
document.
|
||||
|
||||
Examples of API exchanges only show the methodCalls array of the
|
||||
Request object or the methodResponses array of the Response object.
|
||||
For compactness, the rest of the Request/Response object is omitted.
|
||||
|
||||
1.2. Terminology
|
||||
|
||||
The same terminology is used in this document as in the core JMAP
|
||||
specification. See [RFC8620], Section 1.6.
|
||||
|
||||
The terms "Principal" and "ShareNotification" (with this specific
|
||||
capitalization) are used to refer to the data types defined in this
|
||||
document and instances of those data types.
|
||||
|
||||
1.3. Data Model Overview
|
||||
|
||||
A Principal (see Section 2) represents an individual, team, or
|
||||
resource (e.g., a room or projector). The object contains
|
||||
information about the entity being represented, such as a name,
|
||||
description, and time zone. It may also hold domain-specific
|
||||
information. A Principal may be associated with zero or more
|
||||
Accounts (see [RFC8620], Section 1.6.2) containing data belonging to
|
||||
the Principal. Managing the set of Principals within a system is out
|
||||
of scope for this specification, as it is highly domain specific. It
|
||||
is likely to map directly from a directory service or other user
|
||||
management system.
|
||||
|
||||
Data types may allow users to share data with others by assigning
|
||||
permissions to Principals. When a user's permissions are changed, a
|
||||
ShareNotification object is created for them so a client can inform
|
||||
the user of the changes.
|
||||
|
||||
1.4. Subscribing to Shared Data
|
||||
|
||||
Permissions determine whether a user _may_ access data but not
|
||||
whether they _want_ to. Some shared data is of equal importance as
|
||||
the user's own, while other data is just there should the user wish
|
||||
to explicitly go find it. Clients will often want to differentiate
|
||||
the two. For example, a company may share mailing list archives for
|
||||
all departments with all employees, but a user may only generally be
|
||||
interested in the few they belong to. They would have _permission_
|
||||
to access many mailboxes but can _subscribe_ to just the ones they
|
||||
care about. The client would provide separate interfaces for reading
|
||||
mail in subscribed mailboxes and browsing all mailboxes they have
|
||||
permission to access in order to manage those that they are
|
||||
subscribed to.
|
||||
|
||||
The JMAP Session object (see [RFC8620], Section 2) is defined to
|
||||
include an object in the "accounts" property for every Account that
|
||||
the user has access to. Collaborative systems may share data between
|
||||
a very large number of Principals, most of which the user does not
|
||||
care about day to day. For servers implementing this specification,
|
||||
the Session object MUST only include Accounts where either the user
|
||||
is subscribed to at least one record (see [RFC8620], Section 1.6.3)
|
||||
in the Account or the Account belongs to the user. StateChange
|
||||
events ([RFC8620], Section 7.1) for changes to data SHOULD only be
|
||||
sent for data the user has subscribed to and MUST NOT be sent for any
|
||||
Account where the user is not subscribed to any records in the
|
||||
Account, except where that Account belongs to the user.
|
||||
|
||||
The server MAY reject the user's attempt to subscribe to some
|
||||
resources even if they have permission to access them (e.g., a
|
||||
calendar representing a location).
|
||||
|
||||
A user can query the set of Principals they have access to with
|
||||
"Principal/query" (see Section 2.4). The Principal object will
|
||||
contain an Account object for all Accounts where the user has
|
||||
permission to access data for that Principal, even if they are not
|
||||
yet subscribed.
|
||||
|
||||
1.5. Addition to the Capabilities Object
|
||||
|
||||
The capabilities object is returned as part of the JMAP Session
|
||||
object; see [RFC8620], Section 2. This document defines two
|
||||
additional capability URIs.
|
||||
|
||||
1.5.1. urn:ietf:params:jmap:principals
|
||||
|
||||
The urn:ietf:params:jmap:principals capability represents support for
|
||||
the Principal and ShareNotification data types and associated API
|
||||
methods.
|
||||
|
||||
The value of this property in the JMAP Session "capabilities"
|
||||
property is an empty object.
|
||||
|
||||
The value of this property in an Account's "accountCapabilities"
|
||||
property is an object that MUST contain the following information on
|
||||
server capabilities and permissions for that Account:
|
||||
|
||||
*currentUserPrincipalId*: Id|null
|
||||
The id of the Principal in this Account that corresponds to the
|
||||
user fetching this object, if any.
|
||||
|
||||
1.5.2. urn:ietf:params:jmap:principals:owner
|
||||
|
||||
The URI urn:ietf:params:jmap:principals:owner is solely used as a key
|
||||
in an Account's "accountCapabilities" property. It does not appear
|
||||
in the JMAP Session capabilities -- support is indicated by the
|
||||
urn:ietf:params:jmap:principals URI being present in the session
|
||||
capabilities.
|
||||
|
||||
If urn:ietf:params:jmap:principals:owner is a key in an Account's
|
||||
"accountCapabilities" property, that Account (and the data therein)
|
||||
is owned by a Principal. Some Accounts may not be owned by a
|
||||
Principal (e.g., the Account that contains the data for the
|
||||
Principals themselves), in which case this property is omitted.
|
||||
|
||||
The value of this property is an object with the following
|
||||
properties:
|
||||
|
||||
*accountIdForPrincipal*: Id
|
||||
The id of an Account with the urn:ietf:params:jmap:principals
|
||||
capability that contains the corresponding Principal object.
|
||||
|
||||
*principalId*:Id
|
||||
The id of the Principal that owns this Account.
|
||||
|
||||
2. Principals
|
||||
|
||||
A Principal represents an individual, a group, a location (e.g., a
|
||||
room), a resource (e.g., a projector), or another entity in a
|
||||
collaborative environment. Sharing in JMAP is generally configured
|
||||
by assigning rights to certain data within an Account to other
|
||||
Principals. For example, a user may assign permission to read their
|
||||
calendar to a Principal representing another user or their team.
|
||||
|
||||
In a shared environment, such as a workplace, a user may have access
|
||||
to a large number of Principals.
|
||||
|
||||
In most systems, the user will have access to a single Account
|
||||
containing Principal objects. In some situations, for example, when
|
||||
aggregating data from different places, there may be multiple
|
||||
Accounts containing Principal objects.
|
||||
|
||||
A *Principal* object has the following properties:
|
||||
|
||||
*id*: Id (immutable; server-set)
|
||||
The id of the Principal.
|
||||
|
||||
*type*: String
|
||||
This MUST be one of the following values:
|
||||
|
||||
* "individual": This represents a single person.
|
||||
* "group": This represents a group of other Principals.
|
||||
* "resource": This represents some resource, e.g., a projector.
|
||||
* "location": This represents a location.
|
||||
* "other": This represents some other undefined Principal.
|
||||
|
||||
*name*: String
|
||||
The name of the Principal, e.g., "Jane Doe" or "Room 4B".
|
||||
|
||||
*description*: String|null
|
||||
A longer description of the Principal, for example, details about
|
||||
the facilities of a resource, or null if no description is
|
||||
available.
|
||||
|
||||
*email*: String|null
|
||||
An email address for the Principal, or null if no email is
|
||||
available. If given, the value MUST conform to the "addr-spec"
|
||||
syntax, as defined in [RFC5322], Section 3.4.1.
|
||||
|
||||
*timeZone*: String|null
|
||||
The time zone for this Principal, if known. If not null, the
|
||||
value MUST be a time zone name from the IANA Time Zone Database
|
||||
[IANA-TZDB].
|
||||
|
||||
*capabilities*: String[Object] (server-set)
|
||||
A map of JMAP capability URIs to domain-specific information about
|
||||
the Principal in relation to that capability, as defined in the
|
||||
document that registered the capability.
|
||||
|
||||
*accounts*: Id[Account]|null (server-set)
|
||||
A map of Account id to Account object for each JMAP Account
|
||||
containing data for this Principal that the user has access to, or
|
||||
null if none.
|
||||
|
||||
2.1. Principal/get
|
||||
|
||||
This is a standard "/get" method as described in [RFC8620],
|
||||
Section 5.1.
|
||||
|
||||
2.2. Principal/changes
|
||||
|
||||
This is a standard "/changes" method as described in [RFC8620],
|
||||
Section 5.2.
|
||||
|
||||
| Note: Implementations backed by an external directory may be
|
||||
| unable to calculate changes. In this case, they will always
|
||||
| return a "cannotCalculateChanges" error as described in the
|
||||
| core JMAP specification.
|
||||
|
||||
2.3. Principal/set
|
||||
|
||||
This is a standard "/set" method as described in [RFC8620],
|
||||
Section 5.3.
|
||||
|
||||
Managing Principals is likely tied to a directory service or some
|
||||
other vendor-specific solution. This management may occur out of
|
||||
band or via an additional capability defined elsewhere. Allowing
|
||||
direct user modification of properties has security considerations,
|
||||
as noted in Section 6. A server MUST reject any change it doesn't
|
||||
allow with a "forbidden" SetError.
|
||||
|
||||
Where a server does support changes via this API, it SHOULD allow an
|
||||
update to the "name", "description", and "timeZone" properties of the
|
||||
Principal with the same id as the "currentUserPrincipalId" in the
|
||||
Account capabilities. This allows the user to update their own
|
||||
details.
|
||||
|
||||
2.4. Principal/query
|
||||
|
||||
This is a standard "/query" method as described in [RFC8620],
|
||||
Section 5.5.
|
||||
|
||||
2.4.1. Filtering
|
||||
|
||||
A *FilterCondition* object has the following properties, all of which
|
||||
are optional:
|
||||
|
||||
*accountIds*: String[]
|
||||
A list of Account ids. The Principal matches if any of the ids in
|
||||
this list are keys in the Principal's "accounts" property (i.e.,
|
||||
if any of the Account ids belong to the Principal).
|
||||
|
||||
*email*: String
|
||||
The email property of the Principal contains the given string.
|
||||
|
||||
*name*: String
|
||||
The name property of the Principal contains the given string.
|
||||
|
||||
*text*: String
|
||||
The name, email, or description property of the Principal contains
|
||||
the given string.
|
||||
|
||||
*type*: String
|
||||
The type must be exactly as given to match the condition.
|
||||
|
||||
*timeZone*: String
|
||||
The timeZone must be exactly as given to match the condition.
|
||||
|
||||
All given conditions in the FilterCondition object must match for the
|
||||
Principal to match.
|
||||
|
||||
Text matches for "contains" SHOULD be simple substring matches.
|
||||
|
||||
2.5. Principal/queryChanges
|
||||
|
||||
This is a standard "/queryChanges" method as described in [RFC8620],
|
||||
Section 5.6.
|
||||
|
||||
| Note: Implementations backed by an external directory may be
|
||||
| unable to calculate changes. In this case, they will always
|
||||
| return a "cannotCalculateChanges" error as described in the
|
||||
| core JMAP specification.
|
||||
|
||||
3. ShareNotifications
|
||||
|
||||
The ShareNotification data type records when the user's permissions
|
||||
to access a shared object changes. ShareNotifications are only
|
||||
created by the server; users cannot create them explicitly. They are
|
||||
stored in the same Account as the Principals.
|
||||
|
||||
Clients may present the list of notifications to the user and allow
|
||||
the user to dismiss them. To dismiss a notification, use a standard
|
||||
"/set" call to destroy it.
|
||||
|
||||
The server SHOULD create a ShareNotification whenever the user's
|
||||
permissions change on an object. It MAY choose not to create a
|
||||
notification for permission changes to a group Principal, even if the
|
||||
user is in the group, if this is more likely to be overwhelming than
|
||||
helpful, or if it would create excessive notifications within the
|
||||
system.
|
||||
|
||||
The server MAY limit the maximum number of notifications it will
|
||||
store for a user. When the limit is reached, any new notification
|
||||
will cause the previously oldest notification to be automatically
|
||||
deleted.
|
||||
|
||||
The server MAY coalesce notifications if appropriate or remove
|
||||
notifications after a certain period of time or that it deems are no
|
||||
longer relevant.
|
||||
|
||||
A *ShareNotification* object has the following properties:
|
||||
|
||||
*id*: String (immutable; server-set)
|
||||
The id of the ShareNotification.
|
||||
|
||||
*created*: UTCDate (immutable; server-set)
|
||||
The time this notification was created.
|
||||
|
||||
*changedBy*: Entity (immutable; server-set)
|
||||
Who made the change. An *Entity* object has the following
|
||||
properties:
|
||||
|
||||
*name*: String
|
||||
The name of the entity who made the change.
|
||||
*email*: String|null
|
||||
The email of the entity who made the change, or null if no
|
||||
email is available.
|
||||
*principalId*: Id|null
|
||||
The id of the Principal corresponding to the entity who made
|
||||
the change, or null if no associated Principal.
|
||||
|
||||
*objectType*: String (immutable; server-set)
|
||||
The name of the data type for the object whose permissions have
|
||||
changed, as registered in the IANA "JMAP Data Types" registry
|
||||
[IANA-JMAP], e.g., "Calendar" or "Mailbox".
|
||||
|
||||
*objectAccountId*: Id (immutable; server-set)
|
||||
The id of the Account where this object exists.
|
||||
|
||||
*objectId*: Id (immutable; server-set)
|
||||
The id of the object that this notification is about.
|
||||
|
||||
*oldRights*: String[Boolean]|null (immutable; server-set)
|
||||
The "myRights" property of the object for the user before the
|
||||
change.
|
||||
|
||||
*newRights*: String[Boolean]|null (immutable; server-set)
|
||||
The "myRights" property of the object for the user after the
|
||||
change.
|
||||
|
||||
*name*: String (immutable; server-set)
|
||||
The name of the object at the time the notification was made.
|
||||
Determining the name will depend on the data type in question.
|
||||
For example, it might be the "title" property of a CalendarEvent
|
||||
or the "name" of a Mailbox. The name is to show users who have
|
||||
had their access rights to the object removed what it is that they
|
||||
can no longer access.
|
||||
|
||||
3.1. ShareNotification/get
|
||||
|
||||
This is a standard "/get" method as described in [RFC8620],
|
||||
Section 5.1.
|
||||
|
||||
3.2. ShareNotification/changes
|
||||
|
||||
This is a standard "/changes" method as described in [RFC8620],
|
||||
Section 5.2.
|
||||
|
||||
3.3. ShareNotification/set
|
||||
|
||||
This is a standard "/set" method as described in [RFC8620],
|
||||
Section 5.3.
|
||||
|
||||
Only destroy is supported; any attempt to create/update MUST be
|
||||
rejected with a "forbidden" SetError.
|
||||
|
||||
3.4. ShareNotification/query
|
||||
|
||||
This is a standard "/query" method as described in [RFC8620],
|
||||
Section 5.5.
|
||||
|
||||
3.4.1. Filtering
|
||||
|
||||
A *FilterCondition* object has the following properties, all of which
|
||||
are optional:
|
||||
|
||||
*after*: UTCDate|null
|
||||
The creation date must be on or after this date to match the
|
||||
condition.
|
||||
|
||||
*before*: UTCDate|null
|
||||
The creation date must be before this date to match the condition.
|
||||
|
||||
*objectType*: String
|
||||
The objectType value must be identical to the given value to match
|
||||
the condition.
|
||||
|
||||
*objectAccountId*: Id
|
||||
The objectAccountId value must be identical to the given value to
|
||||
match the condition.
|
||||
|
||||
All given conditions in the FilterCondition object must match for the
|
||||
ShareNotification to match.
|
||||
|
||||
3.4.2. Sorting
|
||||
|
||||
The "created" property MUST be supported for sorting.
|
||||
|
||||
3.5. ShareNotification/queryChanges
|
||||
|
||||
This is a standard "/queryChanges" method as described in [RFC8620],
|
||||
Section 5.6.
|
||||
|
||||
4. Framework for Shared Data
|
||||
|
||||
Shareable data types MUST define the following three properties:
|
||||
|
||||
*isSubscribed*: Boolean
|
||||
The value true indicates that the user wishes to subscribe to see
|
||||
this data. The value false indicates that the user does not wish
|
||||
to subscribe to see this data. The initial value for this
|
||||
property when data is shared by another user is implementation
|
||||
dependent, although data types may give advice on appropriate
|
||||
defaults.
|
||||
|
||||
*myRights*: String[Boolean]
|
||||
The set of permissions the user currently has. Appropriate
|
||||
permissions are domain specific and must be defined per data type.
|
||||
Each key is the name of a permission defined for that data type.
|
||||
The value for the key is true if the user has the permission or
|
||||
false if they do not.
|
||||
|
||||
*shareWith*: Id[String[Boolean]]|null
|
||||
The value of this property is null if the data is not shared with
|
||||
anyone. Otherwise, it is a map where each key is the id of a
|
||||
Principal with which this data is shared, and the value associated
|
||||
with that key is the rights to give that Principal, in the same
|
||||
format as the "myRights" property. The Account id for the
|
||||
Principal id can be found in the capabilities of the Account this
|
||||
object is in (see Section 1.5.2).
|
||||
|
||||
Users with appropriate permission may set this property to modify
|
||||
who the data is shared with. The Principal that owns the Account
|
||||
that this data is in MUST NOT be in the map, since the owner's
|
||||
rights are implicit.
|
||||
|
||||
4.1. Example
|
||||
|
||||
Suppose we are designing a data model for a very simple to-do list.
|
||||
There is a Todo data type representing a single item to do, each of
|
||||
which belongs to a single TodoList. The specification makes the
|
||||
TodoLists shareable by referencing this document and defining the
|
||||
common properties.
|
||||
|
||||
First, it would define a set of domain-specific rights. For example,
|
||||
a TodoListRights object may have the following properties:
|
||||
|
||||
*mayRead*: Boolean
|
||||
The user may fetch this TodoList and any Todos that belong to this
|
||||
TodoList.
|
||||
|
||||
*mayWrite*: Boolean
|
||||
The user may create, update, or destroy Todos that belong to this
|
||||
TodoList and may change the "name" property of this TodoList.
|
||||
|
||||
*mayAdmin*: Boolean
|
||||
The user may see and modify the "myRights" property of this
|
||||
TodoList and may destroy this TodoList.
|
||||
|
||||
Then in the TodoList data type, we would include the three common
|
||||
properties described in Section 4, in addition to any type-specific
|
||||
properties (like "name" in this case):
|
||||
|
||||
*id*: Id (immutable; server-set)
|
||||
The id of the object.
|
||||
|
||||
*name*: String
|
||||
A name for this list of Todos.
|
||||
|
||||
*isSubscribed*: Boolean
|
||||
True if the user has indicated they wish to see this list. If
|
||||
false, clients should not display this TodoList with the user's
|
||||
other TodoLists but should provide a means for users to see and
|
||||
subscribe to all TodoLists that have been shared with them.
|
||||
|
||||
*myRights*: TodoListRights
|
||||
The set of permissions the user currently has for this TodoList.
|
||||
|
||||
*shareWith*: Id[TodoListRights]|null
|
||||
If not shared with anyone, the value is null. Otherwise, it's a
|
||||
map where the keys are Principal ids and the values are the rights
|
||||
given to those Principals. Users with the "mayAdmin" right may
|
||||
set this property to modify who the data is shared with. The
|
||||
Principal that owns the Account that this data is in MUST NOT be
|
||||
in the map; their rights are implicit.
|
||||
|
||||
We would also define a new Principal capability with two properties:
|
||||
|
||||
*accountId*: Id|null
|
||||
The accountId containing the Todo data for this Principal, if it
|
||||
has been shared with the requesting user.
|
||||
|
||||
*mayShareWith*: Boolean
|
||||
The user may give this Principal permission to access a TodoList.
|
||||
|
||||
A client wishing to let the user configure sharing would look at the
|
||||
"capabilities" for the Account containing the user's Todo data and
|
||||
find the "urn:ietf:params:jmap:principals:owner" property, as per
|
||||
Section 1.5.2. For example, the JMAP Session object might contain:
|
||||
|
||||
{
|
||||
"accounts": {
|
||||
"u12345678": {
|
||||
"name": "jane.doe@example.com",
|
||||
"isPersonal": true,
|
||||
"isReadOnly": false,
|
||||
"accountCapabilities": {
|
||||
"urn:com.example:jmap:todo": {},
|
||||
"urn:ietf:params:jmap:principals:owner": {
|
||||
"accountIdForPrincipal": "u33084183",
|
||||
"principalId": "P105aga511jaa"
|
||||
}
|
||||
}
|
||||
},
|
||||
...
|
||||
},
|
||||
...
|
||||
}
|
||||
|
||||
Figure 1: Part of a JMAP Session Object
|
||||
|
||||
From this, the client now knows which Account has the Principal data,
|
||||
and it can fetch the list of Principals and offer to share it with
|
||||
the user by making an API request like this:
|
||||
|
||||
[[ "Principal/get", {
|
||||
"accountId": "u33084183",
|
||||
"ids": null
|
||||
}, "0" ]]
|
||||
|
||||
Figure 2: "methodCalls" Property of a JMAP Request
|
||||
|
||||
Here's an example response (where "Joe Bloggs" is another user that
|
||||
this user could share their TodoList with; Joe has not shared any of
|
||||
their own data with this user, so the "accounts" property is null):
|
||||
|
||||
[[ "Principal/get", {
|
||||
"accountId": "u33084183",
|
||||
"state": "7b8eff5zz",
|
||||
"list": [{
|
||||
"id": "P2342fnddd20",
|
||||
"type": "individual",
|
||||
"name": "Joe Bloggs",
|
||||
"description": null,
|
||||
"email": "joe.bloggs@example.com",
|
||||
"timeZone": "Australia/Melbourne",
|
||||
"capabilities": {
|
||||
"urn:com.example:jmap:todo": {
|
||||
"accountId": null,
|
||||
"mayShareWith": true
|
||||
}
|
||||
},
|
||||
"accounts": null
|
||||
}, {
|
||||
"id": "P674pp24095qo49pr",
|
||||
"name": "Board room",
|
||||
"type": "location",
|
||||
...
|
||||
}, ... ],
|
||||
"notFound": []
|
||||
}, "0" ]]
|
||||
|
||||
Figure 3: "methodResponses" Property of a JMAP Response
|
||||
|
||||
A TodoList can be shared with "Joe Bloggs" by updating its shareWith
|
||||
property, as in this example request:
|
||||
|
||||
[[ "TodoList/set", {
|
||||
"accountId": "u12345678",
|
||||
"update": {
|
||||
"tl01n231": {
|
||||
"shareWith": {
|
||||
"P2342fnddd20": {
|
||||
"mayRead": true,
|
||||
"mayWrite": true,
|
||||
"mayAdmin": false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}, "0" ]]
|
||||
|
||||
Figure 4: "methodCalls" Property of a JMAP Request
|
||||
|
||||
5. Internationalization Considerations
|
||||
|
||||
Experience has shown that unrestricted use of Unicode can lead to
|
||||
problems such as inconsistent rendering, users reading text and
|
||||
interpreting it differently than intended, and unexpected results
|
||||
when copying text from one location to another. Servers MAY choose
|
||||
to mitigate this by restricting the set of characters allowed in
|
||||
otherwise unconstrained String fields. The FreeformClass, as
|
||||
documented in [RFC8264], Section 4.3, might be a good starting point
|
||||
for this.
|
||||
|
||||
Attempts to set a value containing code points outside of the
|
||||
permissible set can be handled in a few ways by the server. The
|
||||
first option is to simply strip the forbidden characters and store
|
||||
the resulting string. This is likely to be appropriate for control
|
||||
characters, for example, where they can end up in data accidentally
|
||||
due to copy-and-paste issues and are probably invisible to the end
|
||||
user. JMAP allows the server to transform data on create/update, as
|
||||
long as any changed properties are returned to the client in the
|
||||
"/set" response so it knows what has changed, as per [RFC8620],
|
||||
Section 5.3. Alternatively, the server MAY just reject the create/
|
||||
update with an "invalidProperties" SetError.
|
||||
|
||||
6. Security Considerations
|
||||
|
||||
All security considerations of JMAP [RFC8620] apply to this
|
||||
specification. Additional considerations are detailed below.
|
||||
|
||||
6.1. Spoofing
|
||||
|
||||
Allowing users to edit their own Principal's name (and, to a lesser
|
||||
extent, email, description, or type) could allow a user to change
|
||||
their Principal to look like another user in the system, potentially
|
||||
tricking others into sharing private data with them. Servers may
|
||||
choose to forbid this and SHOULD keep logs of such changes to provide
|
||||
an audit trail.
|
||||
|
||||
Note that simply forbidding the use of a name already in the system
|
||||
is insufficient protection, as a malicious user could still change
|
||||
their name to something easily confused with the existing name by
|
||||
using trivial misspellings or visually similar Unicode characters.
|
||||
|
||||
6.2. Unnoticed Sharing
|
||||
|
||||
Sharing data with another user allows someone to turn a transitory
|
||||
account compromise (e.g., brief access to an unlocked or logged-in
|
||||
client) into a persistent compromise (by setting up sharing with a
|
||||
user that is controlled by the attacker). This can be mitigated by
|
||||
requiring further authorization for configuring sharing or sending
|
||||
notifications to the sharer via another channel whenever a new
|
||||
permission is added.
|
||||
|
||||
6.3. Denial of Service
|
||||
|
||||
By creating many changes to the sharing status of objects, a user can
|
||||
cause many ShareNotifications to be generated, which could lead to
|
||||
resource exhaustion. Servers can mitigate this by coalescing
|
||||
multiple changes to the same object into a single notification,
|
||||
limiting the maximum number of notifications it stores per user and/
|
||||
or rate-limiting the changes to sharing permissions in the first
|
||||
place. Automatically deleting older notifications after reaching a
|
||||
limit can mean the user is not made aware of a sharing change, which
|
||||
can itself be a security issue. For this reason, it is better to
|
||||
coalesce changes and use other mitigation strategies.
|
||||
|
||||
6.4. Unauthorized Principals
|
||||
|
||||
The set of Principals within a shared environment MUST be strictly
|
||||
controlled. If adding a new Principal is open to the public, risks
|
||||
include:
|
||||
|
||||
* An increased risk of a user accidentally sharing data with an
|
||||
unintended person.
|
||||
* An attacker sharing unwanted or offensive information with the
|
||||
user.
|
||||
* An attacker sharing items with spam content in the names in order
|
||||
to generate ShareNotification objects, which are likely to be
|
||||
prominently displayed to the user receiving them.
|
||||
|
||||
7. IANA Considerations
|
||||
|
||||
7.1. JMAP Capability Registration for "principals"
|
||||
|
||||
IANA has registered "principals" in the "JMAP Capabilities" registry
|
||||
as follows:
|
||||
|
||||
Capability Name: urn:ietf:params:jmap:principals
|
||||
Intended Use: common
|
||||
Change Controller: IETF
|
||||
Security and Privacy Considerations: RFC 9670, Section 6
|
||||
Reference: RFC 9670
|
||||
|
||||
7.2. JMAP Capability Registration for "principals:owner"
|
||||
|
||||
IANA has registered "principals:owner" in the "JMAP Capabilities"
|
||||
registry as follows:
|
||||
|
||||
Capability Name: urn:ietf:params:jmap:principals:owner
|
||||
Intended Use: common
|
||||
Change Controller: IETF
|
||||
Security and Privacy Considerations: RFC 9670, Section 6
|
||||
Reference: RFC 9670
|
||||
|
||||
7.3. JMAP Data Type Registration for "Principal"
|
||||
|
||||
IANA has registered "Principal" in the "JMAP Data Types" registry as
|
||||
follows:
|
||||
|
||||
Type Name: Principal
|
||||
Can Reference Blobs: No
|
||||
Can Use for State Change: Yes
|
||||
Capability: urn:ietf:params:jmap:principals
|
||||
Reference: RFC 9670
|
||||
|
||||
7.4. JMAP Data Type Registration for "ShareNotification"
|
||||
|
||||
IANA has registered "ShareNotification" in the "JMAP Data Types"
|
||||
registry as follows:
|
||||
|
||||
Type Name: ShareNotification
|
||||
Can Reference Blobs: No
|
||||
Can Use for State Change: Yes
|
||||
Capability: urn:ietf:params:jmap:principals
|
||||
Reference: RFC 9670
|
||||
|
||||
8. References
|
||||
|
||||
8.1. Normative References
|
||||
|
||||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
|
||||
Requirement Levels", BCP 14, RFC 2119,
|
||||
DOI 10.17487/RFC2119, March 1997,
|
||||
<https://www.rfc-editor.org/info/rfc2119>.
|
||||
|
||||
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
|
||||
DOI 10.17487/RFC5322, October 2008,
|
||||
<https://www.rfc-editor.org/info/rfc5322>.
|
||||
|
||||
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
|
||||
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
|
||||
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
|
||||
|
||||
[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
|
||||
Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
|
||||
2019, <https://www.rfc-editor.org/info/rfc8620>.
|
||||
|
||||
8.2. Informative References
|
||||
|
||||
[IANA-JMAP]
|
||||
IANA, "JMAP Data Types",
|
||||
<https://www.iana.org/assignments/jmap>.
|
||||
|
||||
[IANA-TZDB]
|
||||
IANA, "Time Zone Database",
|
||||
<https://www.iana.org/time-zones>.
|
||||
|
||||
[RFC8264] Saint-Andre, P. and M. Blanchet, "PRECIS Framework:
|
||||
Preparation, Enforcement, and Comparison of
|
||||
Internationalized Strings in Application Protocols",
|
||||
RFC 8264, DOI 10.17487/RFC8264, October 2017,
|
||||
<https://www.rfc-editor.org/info/rfc8264>.
|
||||
|
||||
Author's Address
|
||||
|
||||
Neil Jenkins (editor)
|
||||
Fastmail
|
||||
PO Box 234, Collins St West
|
||||
Melbourne VIC 8007
|
||||
Australia
|
||||
Email: neilj@fastmailteam.com
|
||||
URI: https://www.fastmail.com
|
||||
Binary file not shown.
File diff suppressed because it is too large
Load Diff
File diff suppressed because one or more lines are too long
File diff suppressed because it is too large
Load Diff
Binary file not shown.
@@ -0,0 +1,844 @@
|
||||
|
||||
|
||||
|
||||
|
||||
Internet Engineering Task Force (IETF) N. Jenkins, Ed.
|
||||
Request for Comments: 9610 Fastmail
|
||||
Category: Standards Track December 2024
|
||||
ISSN: 2070-1721
|
||||
|
||||
|
||||
JSON Meta Application Protocol (JMAP) for Contacts
|
||||
|
||||
Abstract
|
||||
|
||||
This document specifies a data model for synchronising contact data
|
||||
with a server using the JSON Meta Application Protocol (JMAP).
|
||||
|
||||
Status of This Memo
|
||||
|
||||
This is an Internet Standards Track document.
|
||||
|
||||
This document is a product of the Internet Engineering Task Force
|
||||
(IETF). It represents the consensus of the IETF community. It has
|
||||
received public review and has been approved for publication by the
|
||||
Internet Engineering Steering Group (IESG). Further information on
|
||||
Internet Standards is available in Section 2 of RFC 7841.
|
||||
|
||||
Information about the current status of this document, any errata,
|
||||
and how to provide feedback on it may be obtained at
|
||||
https://www.rfc-editor.org/info/rfc9610.
|
||||
|
||||
Copyright Notice
|
||||
|
||||
Copyright (c) 2024 IETF Trust and the persons identified as the
|
||||
document authors. All rights reserved.
|
||||
|
||||
This document is subject to BCP 78 and the IETF Trust's Legal
|
||||
Provisions Relating to IETF Documents
|
||||
(https://trustee.ietf.org/license-info) in effect on the date of
|
||||
publication of this document. Please review these documents
|
||||
carefully, as they describe your rights and restrictions with respect
|
||||
to this document. Code Components extracted from this document must
|
||||
include Revised BSD License text as described in Section 4.e of the
|
||||
Trust Legal Provisions and are provided without warranty as described
|
||||
in the Revised BSD License.
|
||||
|
||||
Table of Contents
|
||||
|
||||
1. Introduction
|
||||
1.1. Notational Conventions
|
||||
1.2. Terminology
|
||||
1.3. Data Model Overview
|
||||
1.4. Addition to the Capabilities Object
|
||||
1.4.1. urn:ietf:params:jmap:contacts
|
||||
2. AddressBooks
|
||||
2.1. AddressBook/get
|
||||
2.2. AddressBook/changes
|
||||
2.3. AddressBook/set
|
||||
3. ContactCards
|
||||
3.1. ContactCard/get
|
||||
3.2. ContactCard/changes
|
||||
3.3. ContactCard/query
|
||||
3.3.1. Filtering
|
||||
3.3.2. Sorting
|
||||
3.4. ContactCard/queryChanges
|
||||
3.5. ContactCard/set
|
||||
3.6. ContactCard/copy
|
||||
4. Examples
|
||||
4.1. Fetching Initial Data
|
||||
4.2. Changing the Default Address Book
|
||||
5. Internationalisation Considerations
|
||||
6. Security Considerations
|
||||
7. IANA Considerations
|
||||
7.1. JMAP Capability Registration for "contacts"
|
||||
7.2. JMAP Data Type Registration for "AddressBook"
|
||||
7.3. JMAP Data Type Registration for "ContactCard"
|
||||
7.4. JMAP Error Codes Registry
|
||||
7.4.1. addressBookHasContents
|
||||
7.5. JSContact Property Registrations
|
||||
7.5.1. id
|
||||
7.5.2. addressBookIds
|
||||
7.5.3. blobId
|
||||
8. References
|
||||
8.1. Normative References
|
||||
8.2. Informative References
|
||||
Author's Address
|
||||
|
||||
1. Introduction
|
||||
|
||||
The JSON Meta Application Protocol (JMAP) [RFC8620] is a generic
|
||||
protocol for synchronising data, such as mail, calendars, or
|
||||
contacts, between a client and a server. It is optimised for mobile
|
||||
and web environments and aims to provide a consistent interface to
|
||||
different data types.
|
||||
|
||||
This specification defines a data model for synchronising contacts
|
||||
between a client and a server using JMAP.
|
||||
|
||||
1.1. Notational Conventions
|
||||
|
||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
|
||||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
|
||||
"OPTIONAL" in this document are to be interpreted as described in
|
||||
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
|
||||
capitals, as shown here.
|
||||
|
||||
Type signatures, examples, and property descriptions in this document
|
||||
follow the conventions established in Section 1.1 of [RFC8620]. The
|
||||
Id, UnsignedInt, and UTCDate data types defined in Sections 1.2, 1.3,
|
||||
and 1.4 of [RFC8620] are also used in this document.
|
||||
|
||||
1.2. Terminology
|
||||
|
||||
The same terminology used in the core JMAP specification (see
|
||||
Section 1.6 of [RFC8620]) is also used in this document.
|
||||
|
||||
The terms AddressBook and ContactCard (with these specific
|
||||
capitalizations) are used to refer to the data types defined in this
|
||||
document and instances of those data types.
|
||||
|
||||
1.3. Data Model Overview
|
||||
|
||||
An Account (see Section 1.6.2 of [RFC8620]) with support for the
|
||||
contact data model contains zero or more AddressBook objects, which
|
||||
is a named collection of zero or more ContactCards. A ContactCard is
|
||||
a representation of a person, company, entity, or a group of such
|
||||
entities in JSContact Card format, as defined in Section 2 of
|
||||
[RFC9553]. Each ContactCard belongs to one or more AddressBooks.
|
||||
|
||||
In servers with support for JMAP Sharing [RFC9670], users may see and
|
||||
configure sharing of contact data with others. Sharing permissions
|
||||
are managed per AddressBook.
|
||||
|
||||
1.4. Addition to the Capabilities Object
|
||||
|
||||
The capabilities object is returned as part of the JMAP Session
|
||||
object; see Section 2 of [RFC8620]. This document defines one
|
||||
additional capability URI.
|
||||
|
||||
1.4.1. urn:ietf:params:jmap:contacts
|
||||
|
||||
This represents support for the AddressBook and ContactCard data
|
||||
types and associated API methods. The value of this property in the
|
||||
JMAP Session "capabilities" property is an empty object.
|
||||
|
||||
The value of this property in an account's "accountCapabilities"
|
||||
property is an object that MUST contain the following information on
|
||||
server capabilities and permissions for that account:
|
||||
|
||||
*maxAddressBooksPerCard*: UnsignedInt|null
|
||||
The maximum number of AddressBooks (see Section 2) that can be
|
||||
assigned to a single ContactCard object (see Section 3). This
|
||||
MUST be an integer >= 1, or null for no limit (or rather, the
|
||||
limit is always the number of AddressBooks in the account).
|
||||
|
||||
*mayCreateAddressBook*: Boolean
|
||||
The user may create an AddressBook in this account if, and only
|
||||
if, this is true.
|
||||
|
||||
2. AddressBooks
|
||||
|
||||
An AddressBook is a named collection of ContactCards. All
|
||||
ContactCards are associated with one or more AddressBooks.
|
||||
|
||||
An *AddressBook* object has the following properties:
|
||||
|
||||
*id*: Id (immutable; server-set)
|
||||
The id of the AddressBook.
|
||||
|
||||
*name*: String
|
||||
The user-visible name of the AddressBook. This MUST NOT be the
|
||||
empty string and MUST NOT be greater than 255 octets in size when
|
||||
encoded as UTF-8.
|
||||
|
||||
*description*: String|null (default: null)
|
||||
An optional long-form description of the AddressBook that provides
|
||||
context in shared environments where users need more than just the
|
||||
name.
|
||||
|
||||
*sortOrder*: UnsignedInt (default: 0)
|
||||
Defines the sort order of AddressBooks when presented in the
|
||||
client's UI so it is consistent between devices. The number MUST
|
||||
be an integer in the range 0 <= sortOrder < 2^31.
|
||||
|
||||
An AddressBook with a lower order is to be displayed before a
|
||||
AddressBook with a higher order in any list of AddressBooks in the
|
||||
client's UI. AddressBooks with equal order should be sorted in
|
||||
alphabetical order by name. The sorting should take into account
|
||||
locale-specific character order convention.
|
||||
|
||||
*isDefault*: Boolean (server-set)
|
||||
This SHOULD be true for exactly one AddressBook in any account and
|
||||
MUST NOT be true for more than one AddressBook within an account.
|
||||
The default AddressBook should be used by clients whenever they
|
||||
need to choose an AddressBook for the user within this account and
|
||||
they do not have any other information on which to make a choice.
|
||||
For example, if the user creates a new contact card, the client
|
||||
may automatically set the card as belonging to the default
|
||||
AddressBook from the user's primary account.
|
||||
|
||||
*isSubscribed*: Boolean
|
||||
True if the user has indicated they wish to see this AddressBook
|
||||
in their client. This SHOULD default to false for AddressBooks in
|
||||
shared accounts that the user has access to and true for any new
|
||||
AddressBooks created by the user themself.
|
||||
|
||||
If false, the AddressBook and its contents SHOULD only be
|
||||
displayed when the user explicitly requests it. The UI may offer
|
||||
to the user the option of subscribing to it.
|
||||
|
||||
*shareWith*: Id[AddressBookRights]|null (default: null)
|
||||
A map of the Principal id (Section 2 of [RFC9670]) to rights for
|
||||
Principals this AddressBook is shared with. The Principal to
|
||||
which this AddressBook belongs MUST NOT be in this set. This is
|
||||
null if the AddressBook is not shared with anyone or if the server
|
||||
does not support [RFC9670]. The value may be modified only if the
|
||||
user has the "mayShare" right. The account id for the Principals
|
||||
may be found in the urn:ietf:params:jmap:principals:owner
|
||||
capability of the Account to which the AddressBook belongs.
|
||||
|
||||
*myRights*: AddressBookRights (server-set)
|
||||
The set of access rights the user has in relation to this
|
||||
AddressBook.
|
||||
|
||||
An *AddressBookRights* object has the following properties:
|
||||
|
||||
*mayRead*: Boolean
|
||||
The user may fetch the ContactCards in this AddressBook.
|
||||
|
||||
*mayWrite*: Boolean
|
||||
The user may create, modify, or destroy all ContactCards in this
|
||||
AddressBook, or move them to or from this AddressBook.
|
||||
|
||||
*mayShare*: Boolean
|
||||
The user may modify the "shareWith" property for this AddressBook.
|
||||
|
||||
*mayDelete*: Boolean
|
||||
The user may delete the AddressBook itself.
|
||||
|
||||
2.1. AddressBook/get
|
||||
|
||||
This is a standard "/get" method as described in Section 5.1 of
|
||||
[RFC8620]. The "ids" argument may be null to fetch all at once.
|
||||
|
||||
2.2. AddressBook/changes
|
||||
|
||||
This is a standard "/changes" method as described in Section 5.2 of
|
||||
[RFC8620].
|
||||
|
||||
2.3. AddressBook/set
|
||||
|
||||
This is a standard "/set" method as described in Section 5.3 of
|
||||
[RFC8620], but with the following additional request arguments:
|
||||
|
||||
*onDestroyRemoveContents*: Boolean (default: false)
|
||||
If false, any attempt to destroy an AddressBook that still has a
|
||||
ContactCard in it will be rejected with an
|
||||
"addressBookHasContents" SetError. If true, any ContactCard that
|
||||
is in the AddressBook will be removed from it, and if such a
|
||||
ContactCard does not belong to any other AddressBook, it will be
|
||||
destroyed.
|
||||
|
||||
*onSuccessSetIsDefault*: Id|null
|
||||
If an id is given, and all creates, updates, and destroys (if any)
|
||||
succeed without error, the server will try to set this AddressBook
|
||||
as the default. (For references to AddressBook creations, this is
|
||||
equivalent to a creation-reference, so the id will be the creation
|
||||
id prefixed with a "#".)
|
||||
|
||||
If the id is not found or if the change is not permitted by the
|
||||
server for policy reasons, it MUST be ignored and the current default
|
||||
AddressBook (if any) will remain as such. No error is returned to
|
||||
the client in this case.
|
||||
|
||||
As per Section 5.3 of [RFC8620], if the default AddressBook is
|
||||
successfully changed, any changed objects MUST be reported in either
|
||||
the "created" or "updated" argument in the response as appropriate,
|
||||
with the server-set value included.
|
||||
|
||||
The "shareWith" property may only be set by users that have the
|
||||
"mayShare" right. When modifying the "shareWith" property, the user
|
||||
cannot give a right to a Principal if the Principal did not already
|
||||
have that right and the user making the change also does not have
|
||||
that right. Any attempt to do so MUST be rejected with a "forbidden"
|
||||
SetError.
|
||||
|
||||
Users can subscribe or unsubscribe to an AddressBook by setting the
|
||||
"isSubscribed" property. The server MAY forbid users from
|
||||
subscribing to certain AddressBooks even though they have permission
|
||||
to see them, rejecting the update with a "forbidden" SetError.
|
||||
|
||||
The following extra SetError type is defined for "destroy":
|
||||
|
||||
*addressBookHasContents*: The AddressBook has at least one
|
||||
ContactCard assigned to it and the "onDestroyRemoveContents"
|
||||
argument was false.
|
||||
|
||||
3. ContactCards
|
||||
|
||||
A *ContactCard* object contains information about a person, company,
|
||||
or other entity, or represents a group of such entities. It is a
|
||||
JSContact Card object as defined in Section 2 of [RFC9553] with the
|
||||
following additional properties:
|
||||
|
||||
*id*: Id (immutable; server-set)
|
||||
The id of the ContactCard. The "id" property MAY be different to
|
||||
the ContactCard's "uid" property (as defined in Section 2.1.9 of
|
||||
[RFC9553]). However, there MUST NOT be more than one ContactCard
|
||||
with the same uid in an Account.
|
||||
|
||||
*addressBookIds*: Id[Boolean]
|
||||
The set of AddressBook ids that this ContactCard belongs to. A
|
||||
card MUST belong to at least one AddressBook at all times (until
|
||||
it is destroyed). The set is represented as an object, with each
|
||||
key being an AddressBook id. The value for each key in the object
|
||||
MUST be true.
|
||||
|
||||
For any Media object in the card (see Section 2.6.4 of [RFC9553]), a
|
||||
new property is defined:
|
||||
|
||||
*blobId*: Id
|
||||
An id for the Blob representing the binary contents of the
|
||||
resource.
|
||||
|
||||
When returning ContactCards, any Media with a URI that uses the
|
||||
"data:" URL scheme [RFC2397] SHOULD return a "blobId" property and
|
||||
omit the "uri" property, as this lets clients load the (potentially
|
||||
large) image file only when needed and avoids the overhead of Base64
|
||||
encoding. The "mediaType" property MUST also be set. Similarly,
|
||||
when creating or updating a ContactCard, clients MAY send a "blobId"
|
||||
instead of the "uri" property for a Media object.
|
||||
|
||||
A contact card with a "kind" property equal to "group" represents a
|
||||
group of contacts. Clients often present these separately from other
|
||||
contact cards. The "members" property, as defined in Section 2.1.6
|
||||
of [RFC9553], contains a set of uids (as defined in Section 2.1.9 of
|
||||
[RFC9553]) for other contacts that are the members of this group.
|
||||
Clients should consider the group to contain any ContactCard with a
|
||||
matching uid from any account they have access to that has support
|
||||
for the urn:ietf:params:jmap:contacts capability. Any uid that
|
||||
cannot be found SHOULD be ignored but preserved. For example,
|
||||
suppose a user adds contacts from a shared address book to their
|
||||
private group, then temporarily loses access to this address book.
|
||||
The uids cannot be resolved, so the contacts will disappear from the
|
||||
group. However, if they are given permission to access the data
|
||||
again, the uids will be found and the contacts will reappear.
|
||||
|
||||
3.1. ContactCard/get
|
||||
|
||||
This is a standard "/get" method as described in Section 5.1 of
|
||||
[RFC8620].
|
||||
|
||||
3.2. ContactCard/changes
|
||||
|
||||
This is a standard "/changes" method as described in Section 5.2 of
|
||||
[RFC8620].
|
||||
|
||||
3.3. ContactCard/query
|
||||
|
||||
This is a standard "/query" method as described in Section 5.5 of
|
||||
[RFC8620].
|
||||
|
||||
3.3.1. Filtering
|
||||
|
||||
A *FilterCondition* object has the following properties, any of which
|
||||
may be omitted:
|
||||
|
||||
*inAddressBook*: Id
|
||||
An AddressBook id. A card must be in this address book to match
|
||||
the condition.
|
||||
|
||||
*uid*: String
|
||||
A card must have this string exactly as its uid (as defined in
|
||||
Section 2.1.9 of [RFC9553]) to match.
|
||||
|
||||
*hasMember*: String
|
||||
A card must have a "members" property (as defined in Section 2.1.6
|
||||
of [RFC9553]) that contains this string as one of the uids in the
|
||||
set to match.
|
||||
|
||||
*kind*: String
|
||||
A card must have a "kind" property (as defined in Section 2.1.4 of
|
||||
[RFC9553]) that equals this string exactly to match.
|
||||
|
||||
*createdBefore*: UTCDate
|
||||
The "created" date-time of the ContactCard (as defined in
|
||||
Section 2.1.3 of [RFC9553]) must be before this date-time to match
|
||||
the condition.
|
||||
|
||||
*createdAfter*: UTCDate
|
||||
The "created" date-time of the ContactCard (as defined in
|
||||
Section 2.1.3 of [RFC9553]) must be the same or after this date-
|
||||
time to match the condition.
|
||||
|
||||
*updatedBefore*: UTCDate
|
||||
The "updated" date-time of the ContactCard (as defined in
|
||||
Section 2.1.10 of [RFC9553]) must be before this date-time to
|
||||
match the condition.
|
||||
|
||||
*updatedAfter*: UTCDate
|
||||
The "updated" date-time of the ContactCard (as defined in
|
||||
Section 2.1.10 of [RFC9553]) must be the same or after this date-
|
||||
time to match the condition.
|
||||
|
||||
*text*: String
|
||||
A card matches this condition if the text matches with text in the
|
||||
card.
|
||||
|
||||
*name*: String
|
||||
A card matches this condition if the value of any NameComponent in
|
||||
the "name" property or the "full" property in the "name" property
|
||||
of the card (as defined in Section 2.2.1.2 of [RFC9553]) matches
|
||||
the value.
|
||||
|
||||
*name/given*: String
|
||||
A card matches this condition if the value of a NameComponent with
|
||||
kind "given" inside the "name" property of the card (as defined in
|
||||
Section 2.2.1.2 of [RFC9553]) matches the value.
|
||||
|
||||
*name/surname*: String
|
||||
A card matches this condition if the value of a NameComponent with
|
||||
kind "surname" inside the "name" property of the card (as defined
|
||||
in Section 2.2.1.2 of [RFC9553]) matches the value.
|
||||
|
||||
*name/surname2*: String
|
||||
A card matches this condition if the value of a NameComponent with
|
||||
kind "surname2" inside the "name" property of the card (as defined
|
||||
in Section 2.2.1.2 of [RFC9553]) matches the value.
|
||||
|
||||
*nickname*: String
|
||||
A card matches this condition if the "name" of any Nickname in the
|
||||
"nicknames" property of the card (as defined in Section 2.2.2 of
|
||||
[RFC9553]) matches the value.
|
||||
|
||||
*organization*: String
|
||||
A card matches this condition if the "name" of any Organization in
|
||||
the "organizations" property of the card (as defined in
|
||||
Section 2.2.3 of [RFC9553]) matches the value.
|
||||
|
||||
*email*: String
|
||||
A card matches this condition if the "address" or "label" of any
|
||||
EmailAddress in the "emails" property of the card (as defined in
|
||||
Section 2.3.1 of [RFC9553]) matches the value.
|
||||
|
||||
*phone*: String
|
||||
A card matches this condition if the "number" or "label" of any
|
||||
Phone in the "phones" property of the card (as defined in
|
||||
Section 2.3.3 of [RFC9553]) matches the value.
|
||||
|
||||
*onlineService*: String
|
||||
A card matches this condition if the "service", "uri", "user", or
|
||||
"label" of any OnlineService in the "onlineServices" property of
|
||||
the card (as defined in Section 2.3.2 of [RFC9553]) matches the
|
||||
value.
|
||||
|
||||
*address*: String
|
||||
A card matches this condition if the value of any AddressComponent
|
||||
in the "addresses" property or the "full" property in the
|
||||
"addresses" property of the card (as defined in Section 2.5.1 of
|
||||
[RFC9553]) matches the value.
|
||||
|
||||
*note*: String
|
||||
A card matches this condition if the "note" of any Note in the
|
||||
"notes" property of the card (as defined in Section 2.8.3 of
|
||||
[RFC9553]) matches the value.
|
||||
|
||||
If zero properties are specified on the FilterCondition, the
|
||||
condition MUST always evaluate to true. If multiple properties are
|
||||
specified, ALL must apply for the condition to be true (it is
|
||||
equivalent to splitting the object into one-property conditions and
|
||||
making them all the child of an AND filter operator).
|
||||
|
||||
The exact semantics for matching String fields is deliberately not
|
||||
defined to allow for flexibility in indexing implementation, subject
|
||||
to the following:
|
||||
|
||||
* Text SHOULD be matched in a case-insensitive manner.
|
||||
|
||||
* Text contained in either (but matched) single or double quotes
|
||||
SHOULD be treated as a phrase search. That is, a match is
|
||||
required for that exact sequence of words, excluding the
|
||||
surrounding quotation marks. Use \", \', and \\ to match a
|
||||
literal ", ', and \ respectively in a phrase.
|
||||
|
||||
* Outside of a phrase, whitespace SHOULD be treated as dividing
|
||||
separate tokens that may be searched for separately in the
|
||||
contact, but MUST all be present for the contact to match the
|
||||
filter.
|
||||
|
||||
* Tokens MAY be matched on a whole-word basis using stemming (e.g.,
|
||||
a text search for bus would match "buses", but not "business").
|
||||
|
||||
3.3.2. Sorting
|
||||
|
||||
The following values for the "property" field on the Comparator
|
||||
object MUST be supported for sorting:
|
||||
|
||||
* "created" - The "created" date on the ContactCard.
|
||||
|
||||
* "updated" - The "updated" date on the ContactCard.
|
||||
|
||||
The following values for the "property" field on the Comparator
|
||||
object SHOULD be supported for sorting:
|
||||
|
||||
* "name/given" - The value of the first NameComponent in the "name"
|
||||
property whose "kind" is "given".
|
||||
|
||||
* "name/surname" - The value of the first NameComponent in the
|
||||
"name" property whose "kind" is "surname".
|
||||
|
||||
* "name/surname2" - The value of the first NameComponent in the
|
||||
"name" property whose "kind" is "surname2".
|
||||
|
||||
3.4. ContactCard/queryChanges
|
||||
|
||||
This is a standard "/queryChanges" method as described in Section 5.6
|
||||
of [RFC8620].
|
||||
|
||||
3.5. ContactCard/set
|
||||
|
||||
This is a standard "/set" method as described in Section 5.3 of
|
||||
[RFC8620].
|
||||
|
||||
To set a new photo, the file must first be uploaded using the upload
|
||||
mechanism as described in Section 6.1 of [RFC8620]. This will give
|
||||
the client a valid blobId, size, and type to use. The server MUST
|
||||
reject attempts to set a file that is not a recognised image type as
|
||||
the photo for a card.
|
||||
|
||||
3.6. ContactCard/copy
|
||||
|
||||
This is a standard "/copy" method as described in Section 5.4 of
|
||||
[RFC8620].
|
||||
|
||||
4. Examples
|
||||
|
||||
For brevity, only the "methodCalls" property of the Request object
|
||||
and the "methodResponses" property of the Response object is shown in
|
||||
the following examples.
|
||||
|
||||
4.1. Fetching Initial Data
|
||||
|
||||
A user has authenticated and the client has fetched the JMAP Session
|
||||
object. It finds a single Account with the
|
||||
"urn:ietf:params:jmap:contacts" capability with id "a0x9" and wants
|
||||
to fetch all the address books and contacts. It might make the
|
||||
following request:
|
||||
|
||||
[
|
||||
["AddressBook/get", {
|
||||
"accountId": "a0x9"
|
||||
}, "0"],
|
||||
["ContactCard/get", {
|
||||
"accountId": "a0x9"
|
||||
}, "1"]
|
||||
]
|
||||
|
||||
Figure 1: "methodCalls" Property of a JMAP Request
|
||||
|
||||
The server might respond with something like:
|
||||
|
||||
[
|
||||
["AddressBook/get", {
|
||||
"accountId": "a0x9",
|
||||
"list": [{
|
||||
"id": "062adcfa-105d-455c-bc60-6db68b69c3f3",
|
||||
"name": "Personal",
|
||||
"description": null,
|
||||
"sortOrder": 0,
|
||||
"isDefault": true,
|
||||
"isSubscribed": true,
|
||||
"shareWith": {
|
||||
"3f1502e0-63fe-4335-9ff3-e739c188f5dd": {
|
||||
"mayRead": true,
|
||||
"mayWrite": false,
|
||||
"mayShare": false,
|
||||
"mayDelete": false
|
||||
}
|
||||
},
|
||||
"myRights": {
|
||||
"mayRead": true,
|
||||
"mayWrite": true,
|
||||
"mayShare": true,
|
||||
"mayDelete": false
|
||||
}
|
||||
}, {
|
||||
"id": "cd40089d-35f9-4fd7-980b-ba3a9f1d74fe",
|
||||
"name": "Autosaved",
|
||||
"description": null,
|
||||
"sortOrder": 1,
|
||||
"isDefault": false,
|
||||
"isSubscribed": true,
|
||||
"shareWith": null,
|
||||
"myRights": {
|
||||
"mayRead": true,
|
||||
"mayWrite": true,
|
||||
"mayShare": true,
|
||||
"mayDelete": false
|
||||
}
|
||||
}],
|
||||
"notFound": [],
|
||||
"state": "~4144"
|
||||
}, "0"],
|
||||
["ContactCard/get", {
|
||||
"accountId": "a0x9",
|
||||
"list": [{
|
||||
"id": "3",
|
||||
"addressBookIds": {
|
||||
"062adcfa-105d-455c-bc60-6db68b69c3f3": true
|
||||
},
|
||||
"name": {
|
||||
"components": [
|
||||
{ "kind": "given", "value": "Joe" },
|
||||
{ "kind": "surname", "value": "Bloggs" }
|
||||
],
|
||||
"isOrdered": true
|
||||
},
|
||||
"emails": {
|
||||
"0": {
|
||||
"contexts": {
|
||||
"private": true
|
||||
},
|
||||
"address": "joe.bloggs@example.com"
|
||||
}
|
||||
}
|
||||
}],
|
||||
"notFound": [],
|
||||
"state": "ewarbckaqJ::112"
|
||||
}, "1"]
|
||||
]
|
||||
|
||||
Figure 2: "methodResponses" Property of a JMAP Response
|
||||
|
||||
4.2. Changing the Default Address Book
|
||||
|
||||
The client tries to change the default address book from "Personal"
|
||||
to "Autosaved" (and makes no other change):
|
||||
|
||||
[
|
||||
["AddressBook/set", {
|
||||
"accountId": "a0x9",
|
||||
"onSuccessSetIsDefault": "cd40089d-35f9-4fd7-980b-ba3a9f1d74fe"
|
||||
}, "0"]
|
||||
]
|
||||
|
||||
Figure 3: "methodCalls" Property of a JMAP Request
|
||||
|
||||
The server allows the change, returning the following response:
|
||||
|
||||
[
|
||||
["AddressBook/set", {
|
||||
"accountId": "a0x9",
|
||||
"updated": {
|
||||
"cd40089d-35f9-4fd7-980b-ba3a9f1d74fe": {
|
||||
"isDefault": true
|
||||
},
|
||||
"062adcfa-105d-455c-bc60-6db68b69c3f3": {
|
||||
"isDefault": false
|
||||
},
|
||||
"oldState": "~4144",
|
||||
"newState": "~4148"
|
||||
}
|
||||
}, "0"]
|
||||
]
|
||||
|
||||
Figure 4: "methodResponses" Property of a JMAP Response
|
||||
|
||||
5. Internationalisation Considerations
|
||||
|
||||
Experience has shown that unrestricted use of Unicode can lead to
|
||||
problems such as inconsistent rendering, users reading text and
|
||||
interpreting it differently than intended, and unexpected results
|
||||
when copying text from one location to another. Servers MAY choose
|
||||
to mitigate this by restricting the set of characters allowed in
|
||||
otherwise unconstrained String fields. The FreeformClass, as
|
||||
documented in Section 4.3 of [RFC8264], might be a good starting
|
||||
point for this.
|
||||
|
||||
Attempts to set a value containing code points outside of the
|
||||
permissible set can be handled in a few ways by the server. The
|
||||
server could choose to strip the forbidden characters or replace them
|
||||
with U+FFFD (the Unicode replacement character) and store the
|
||||
resulting string. This is likely to be appropriate for non-printable
|
||||
characters -- such as the "Control Codes" defined in Section 23.1
|
||||
(https://www.unicode.org/versions/latest/core-spec/chapter-
|
||||
23/#G20365) of [UNICODE], excluding newline (U+000A), carriage return
|
||||
(U+000D), and tab (U+0009) -- that can end up in data accidentally
|
||||
due to copy-and-paste issues but are invisible to the end user. JMAP
|
||||
allows the server to transform data on create/update as long as any
|
||||
changed properties are returned to the client in the "/set" response
|
||||
so it knows what has changed, as per Section 5.3 of [RFC8620].
|
||||
Alternatively, the server MAY just reject the create/update with an
|
||||
"invalidProperties" SetError.
|
||||
|
||||
6. Security Considerations
|
||||
|
||||
All security considerations of JMAP [RFC8620] apply to this
|
||||
specification. Additional considerations specific to the data types
|
||||
and functionality introduced by this document are described in the
|
||||
following subsection.
|
||||
|
||||
Contacts consist almost entirely of private, personally identifiable
|
||||
information, and represent the social connections of users. Privacy
|
||||
leaks can have real world consequences, and contact servers and
|
||||
clients MUST be mindful of the need to keep all data secure.
|
||||
|
||||
Servers MUST enforce the Access Control Lists (ACLs) set on address
|
||||
books to ensure only authorised data is shared.
|
||||
|
||||
7. IANA Considerations
|
||||
|
||||
7.1. JMAP Capability Registration for "contacts"
|
||||
|
||||
IANA has registered "contacts" in the "JMAP Capabilities" registry as
|
||||
follows:
|
||||
|
||||
Capability Name: urn:ietf:params:jmap:contacts
|
||||
Intended Use: common
|
||||
Change Controller: IETF
|
||||
Security and Privacy Considerations: this document, Section 6
|
||||
Reference: this document
|
||||
|
||||
7.2. JMAP Data Type Registration for "AddressBook"
|
||||
|
||||
IANA has registered "AddressBook" in the "JMAP Data Types" registry
|
||||
as follows:
|
||||
|
||||
Type Name: AddressBook
|
||||
Can Reference Blobs: No
|
||||
Can Use for State Change: Yes
|
||||
Capability: urn:ietf:params:jmap:contacts
|
||||
Reference: this document
|
||||
|
||||
7.3. JMAP Data Type Registration for "ContactCard"
|
||||
|
||||
IANA has registered "ContactCard" in the "JMAP Data Types" registry
|
||||
as follows:
|
||||
|
||||
Type Name: ContactCard
|
||||
Can Reference Blobs: Yes
|
||||
Can Use for State Change: Yes
|
||||
Capability: urn:ietf:params:jmap:contacts
|
||||
Reference: this document
|
||||
|
||||
7.4. JMAP Error Codes Registry
|
||||
|
||||
The following subsection has registered a new error code in the "JMAP
|
||||
Error Codes" registry, as defined in Section 9 of [RFC8620].
|
||||
|
||||
7.4.1. addressBookHasContents
|
||||
|
||||
JMAP Error Code: addressBookHasContents
|
||||
Intended Use: common
|
||||
Change Controller: IETF
|
||||
Description: The AddressBook has at least one ContactCard assigned
|
||||
to it, and the "onDestroyRemoveContents" argument was false.
|
||||
Reference: This document, Section 2.3
|
||||
|
||||
7.5. JSContact Property Registrations
|
||||
|
||||
IANA has registered the following additional properties in the
|
||||
"JSContact Properties" registry, as defined in Section 3 of
|
||||
[RFC9553].
|
||||
|
||||
7.5.1. id
|
||||
|
||||
Property Name: id
|
||||
Property Type: not applicable
|
||||
Property Context: Card
|
||||
Intended Usage: reserved
|
||||
Since Version: 1.0
|
||||
Change Controller: IETF
|
||||
Reference: this document
|
||||
|
||||
7.5.2. addressBookIds
|
||||
|
||||
Property Name: addressBookIds
|
||||
Property Type: not applicable
|
||||
Property Context: Card
|
||||
Intended Usage: reserved
|
||||
Since Version: 1.0
|
||||
Change Controller: IETF
|
||||
Reference: this document
|
||||
|
||||
7.5.3. blobId
|
||||
|
||||
Property Name: blobId
|
||||
Property Type: not applicable
|
||||
Property Context: Media
|
||||
Intended Usage: reserved
|
||||
Since Version: 1.0
|
||||
Change Controller: IETF
|
||||
Reference: this document
|
||||
|
||||
8. References
|
||||
|
||||
8.1. Normative References
|
||||
|
||||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
|
||||
Requirement Levels", BCP 14, RFC 2119,
|
||||
DOI 10.17487/RFC2119, March 1997,
|
||||
<https://www.rfc-editor.org/info/rfc2119>.
|
||||
|
||||
[RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397,
|
||||
DOI 10.17487/RFC2397, August 1998,
|
||||
<https://www.rfc-editor.org/info/rfc2397>.
|
||||
|
||||
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
|
||||
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
|
||||
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
|
||||
|
||||
[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
|
||||
Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
|
||||
2019, <https://www.rfc-editor.org/info/rfc8620>.
|
||||
|
||||
[RFC9553] Stepanek, R. and M. Loffredo, "JSContact: A JSON
|
||||
Representation of Contact Data", RFC 9553,
|
||||
DOI 10.17487/RFC9553, May 2024,
|
||||
<https://www.rfc-editor.org/info/rfc9553>.
|
||||
|
||||
[RFC9670] Jenkins, N., Ed., "JSON Meta Application Protocol (JMAP)
|
||||
Sharing", RFC 9670, DOI 10.17487/RFC9670, November 2024,
|
||||
<https://www.rfc-editor.org/info/rfc9670>.
|
||||
|
||||
8.2. Informative References
|
||||
|
||||
[RFC8264] Saint-Andre, P. and M. Blanchet, "PRECIS Framework:
|
||||
Preparation, Enforcement, and Comparison of
|
||||
Internationalized Strings in Application Protocols",
|
||||
RFC 8264, DOI 10.17487/RFC8264, October 2017,
|
||||
<https://www.rfc-editor.org/info/rfc8264>.
|
||||
|
||||
[UNICODE] The Unicode Consortium, "The Unicode Standard",
|
||||
<https://www.unicode.org/versions/latest/>.
|
||||
|
||||
Author's Address
|
||||
|
||||
Neil Jenkins (editor)
|
||||
Fastmail
|
||||
PO Box 234, Collins St West
|
||||
Melbourne VIC 8007
|
||||
Australia
|
||||
Email: neilj@fastmailteam.com
|
||||
URI: https://www.fastmail.com
|
||||
Binary file not shown.
File diff suppressed because it is too large
Load Diff
Binary file not shown.
@@ -0,0 +1,843 @@
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Network Working Group G. Neufeld
|
||||
Request for Comments: 2369 Nisto
|
||||
Category: Standards Track J. Baer
|
||||
SkyWeyr Technologies
|
||||
July 1998
|
||||
|
||||
|
||||
The Use of URLs as Meta-Syntax for Core Mail List Commands
|
||||
and their Transport through Message Header Fields
|
||||
|
||||
Status of this Memo
|
||||
|
||||
This document specifies an Internet standards track protocol for the
|
||||
Internet community, and requests discussion and suggestions for
|
||||
improvements. Please refer to the current edition of the "Internet
|
||||
Official Protocol Standards" (STD 1) for the standardization state
|
||||
and status of this protocol. Distribution of this memo is unlimited.
|
||||
|
||||
Copyright Notice
|
||||
|
||||
Copyright (C) The Internet Society (1998). All Rights Reserved.
|
||||
|
||||
Abstract
|
||||
|
||||
The mailing list command specification header fields are a set of
|
||||
structured fields to be added to email messages sent by email
|
||||
distribution lists. Each field typically contains a URL (usually
|
||||
mailto [RFC2368]) locating the relevant information or performing the
|
||||
command directly. The three core header fields described in this
|
||||
document are List-Help, List-Subscribe, and List-Unsubscribe.
|
||||
|
||||
There are three other header fields described here which, although
|
||||
not as widely applicable, will have utility for a sufficient number
|
||||
of mailing lists to justify their formalization here. These are
|
||||
List-Post, List-Owner and List-Archive.
|
||||
|
||||
By including these header fields, list servers can make it possible
|
||||
for mail clients to provide automated tools for users to perform list
|
||||
functions. This could take the form of a menu item, push button, or
|
||||
other user interface element. The intent is to simplify the user
|
||||
experience, providing a common interface to the often cryptic and
|
||||
varied mailing list manager commands.
|
||||
|
||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
|
||||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
|
||||
document are to be interpreted as described in RFC 2119.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 1]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
1. Introduction
|
||||
|
||||
This is a proposal for additional header fields to be added to email
|
||||
messages sent by email distribution lists. The content of each new
|
||||
field is typically a URL - usually mailto [RFC2368] - which locates
|
||||
the relevant information or performs the command directly. MTAs
|
||||
generating the header fields SHOULD usually include a mailto based
|
||||
command, in addition to any other protocols used, in order to support
|
||||
users who do not have access to non-mail-based protocols.
|
||||
|
||||
Implementing these fields will be optional. Significant functionality
|
||||
and convenience can be gained by including them, however. Many list
|
||||
managers, especially as the proposal first gains acceptance, MAY
|
||||
choose to implement only one or two of the fields. The List-Help
|
||||
field is the most useful individual field since it provides an access
|
||||
point to detailed user support information, and accommodates almost
|
||||
all existing list managers command sets. The List-Subscribe and
|
||||
List-Unsubscribe fields are also very useful, but cannot describe
|
||||
some list manager syntaxes at this time (those which require variable
|
||||
substitution). See appendix A.5 for an explanation.
|
||||
|
||||
The description of command syntax provided by the fields can be used
|
||||
by mail client applications to provide simplified and consistent user
|
||||
access to email distribution list functions. This could take the form
|
||||
of menu items, push buttons, or other user interface elements. The
|
||||
intent is to simplify the user experience, providing a common
|
||||
interface to the often cryptic and varied mailing list manager
|
||||
commands.
|
||||
|
||||
Consideration has been given to avoiding the creation of too many
|
||||
fields, while at the same time avoiding the overloading of individual
|
||||
fields and keeping the syntax clear and simple.
|
||||
|
||||
The use of these fields does not remove the requirement to support
|
||||
the -Request command address for mailing lists [RFC2142].
|
||||
|
||||
2. The Command Syntax
|
||||
|
||||
The list header fields are subject to the encoding and character
|
||||
restrictions for mail headers as described in [RFC822]. Additionally,
|
||||
the URL content is further restricted to the set of URL safe
|
||||
characters [RFC1738].
|
||||
|
||||
The contents of the list header fields mostly consist of angle-
|
||||
bracket ('<', '>') enclosed URLs, with internal whitespace being
|
||||
ignored. MTAs MUST NOT insert whitespace within the brackets, but
|
||||
client applications should treat any whitespace, that might be
|
||||
inserted by poorly behaved MTAs, as characters to ignore.
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 2]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
A list of multiple, alternate, URLs MAY be specified by a comma-
|
||||
separated list of angle-bracket enclosed URLs. The URLs have order of
|
||||
preference from left to right. The client application should use the
|
||||
left most protocol that it supports, or knows how to access by a
|
||||
separate application. By this mechanism, protocols like http may be
|
||||
specified while still providing the basic mailto support for those
|
||||
clients who do not have access to non-mail protocols. The client
|
||||
should only use one of the available URLs for a command, using
|
||||
another only if the first one used failed.
|
||||
|
||||
The use of URLs allows for the use of the syntax with existing URL
|
||||
supporting applications. As the standard for URLs is extended, the
|
||||
list header fields will gain the benefit of those extensions.
|
||||
Additionally, the use of URLs provides access to multiple transport
|
||||
protocols (such as ftp and http) although it is expected that the
|
||||
"mailto" protocol [RFC2368] will be the focus of most use of the list
|
||||
header fields. Use of non-mailto protocols should be considered in
|
||||
light of those users who do not have access to the specified
|
||||
mechanism (those who only have email - with no web access).
|
||||
|
||||
Command syntaxes requiring variable fields to be set by the client
|
||||
(such as including the user's email address within a command) are not
|
||||
supported by this implementation. However, systems using such
|
||||
syntaxes SHOULD still take advantage of the List-Help field to
|
||||
provide the user with detailed instructions as needed or - perhaps
|
||||
more usefully - provide access to some form of structured command
|
||||
interface such as an HTML-based form.
|
||||
|
||||
The additional complications of supporting variable fields within the
|
||||
command syntax was determined to be too difficult to support by this
|
||||
protocol and would compromise the likelihood of implementation by
|
||||
software authors.
|
||||
|
||||
To allow for future extension, client applications MUST follow the
|
||||
following guidelines for handling the contents of the header fields
|
||||
described in this document:
|
||||
|
||||
1) Except where noted for specific fields, if the content of the
|
||||
field (following any leading whitespace, including comments)
|
||||
begins with any character other than the opening angle bracket
|
||||
'<', the field SHOULD be ignored.
|
||||
|
||||
2) Any characters following an angle bracket enclosed URL SHOULD be
|
||||
ignored, unless a comma is the first non-whitespace/comment
|
||||
character after the closing angle bracket.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 3]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
3) If a sub-item (comma-separated item) within the field is not an
|
||||
angle-bracket enclosed URL, the remainder of the field (the
|
||||
current, and all subsequent, sub-items) SHOULD be ignored.
|
||||
|
||||
3. The List Header Fields
|
||||
|
||||
This document presents header fields which will provide the
|
||||
command syntax description for the 'core' and key secondary
|
||||
functions of most email distribution lists. The fields implemented
|
||||
on a given list SHOULD be included on all messages distributed by
|
||||
the list (including command responses to individual users), and on
|
||||
other messages where the message clearly applies to one distinct
|
||||
list. There MUST be no more than one of each field present in any
|
||||
given message.
|
||||
|
||||
These fields MUST only be generated by mailing lists, not end
|
||||
users.
|
||||
|
||||
3.1. List-Help
|
||||
|
||||
The List-Help field is the most important of the header fields
|
||||
described in this document. It would be acceptable for a list
|
||||
manager to include only this field, since by definition it SHOULD
|
||||
direct the user to complete instructions for all other commands.
|
||||
Typically, the URL specified would request the help file, perhaps
|
||||
incorporating an HTML form for list commands, for the list, and
|
||||
alternatively provide access to an instructive website.
|
||||
|
||||
Examples:
|
||||
|
||||
List-Help: <mailto:list@host.com?subject=help> (List Instructions)
|
||||
List-Help: <mailto:list-manager@host.com?body=info>
|
||||
List-Help: <mailto:list-info@host.com> (Info about the list)
|
||||
List-Help: <http://www.host.com/list/>, <mailto:list-info@host.com>
|
||||
List-Help: <ftp://ftp.host.com/list.txt> (FTP),
|
||||
<mailto:list@host.com?subject=help>
|
||||
|
||||
3.2. List-Unsubscribe
|
||||
|
||||
The List-Unsubscribe field describes the command (preferably using
|
||||
mail) to directly unsubscribe the user (removing them from the list).
|
||||
|
||||
Examples:
|
||||
|
||||
List-Unsubscribe: <mailto:list@host.com?subject=unsubscribe>
|
||||
List-Unsubscribe: (Use this command to get off the list)
|
||||
<mailto:list-manager@host.com?body=unsubscribe%20list>
|
||||
List-Unsubscribe: <mailto:list-off@host.com>
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 4]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
List-Unsubscribe: <http://www.host.com/list.cgi?cmd=unsub&lst=list>,
|
||||
<mailto:list-request@host.com?subject=unsubscribe>
|
||||
|
||||
3.3. List-Subscribe
|
||||
|
||||
The List-Subscribe field describes the command (preferably using
|
||||
mail) to directly subscribe the user (request addition to the list).
|
||||
|
||||
Examples:
|
||||
|
||||
List-Subscribe: <mailto:list@host.com?subject=subscribe>
|
||||
List-Subscribe: <mailto:list-request@host.com?subject=subscribe>
|
||||
List-Subscribe: (Use this command to join the list)
|
||||
<mailto:list-manager@host.com?body=subscribe%20list>
|
||||
List-Subscribe: <mailto:list-on@host.com>
|
||||
List-Subscribe: <http://www.host.com/list.cgi?cmd=sub&lst=list>,
|
||||
<mailto:list-manager@host.com?body=subscribe%20list>
|
||||
|
||||
3.4. List-Post
|
||||
|
||||
The List-Post field describes the method for posting to the list.
|
||||
This is typically the address of the list, but MAY be a moderator, or
|
||||
potentially some other form of submission. For the special case of a
|
||||
list that does not allow posting (e.g., an announcements list), the
|
||||
List-Post field may contain the special value "NO".
|
||||
|
||||
Examples:
|
||||
|
||||
List-Post: <mailto:list@host.com>
|
||||
List-Post: <mailto:moderator@host.com> (Postings are Moderated)
|
||||
List-Post: <mailto:moderator@host.com?subject=list%20posting>
|
||||
List-Post: NO (posting not allowed on this list)
|
||||
|
||||
3.5. List-Owner
|
||||
|
||||
The List-Owner field identifies the path to contact a human
|
||||
administrator for the list. The URL MAY contain the address of a
|
||||
administrator for the list, the mail system administrator, or any
|
||||
other person who can handle user contact for the list. There is no
|
||||
need to specify List-Owner if it is the same person as the mail
|
||||
system administrator (postmaster).
|
||||
|
||||
Examples:
|
||||
|
||||
List-Owner: <mailto:listmom@host.com> (Contact Person for Help)
|
||||
List-Owner: <mailto:grant@foo.bar> (Grant Neufeld)
|
||||
List-Owner: <mailto:josh@foo.bar?Subject=list>
|
||||
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 5]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
3.6. List-Archive
|
||||
|
||||
The List-Archive field describes how to access archives for the list.
|
||||
|
||||
Examples:
|
||||
|
||||
List-Archive: <mailto:archive@host.com?subject=index%20list>
|
||||
List-Archive: <ftp://ftp.host.com/pub/list/archive/>
|
||||
List-Archive: <http://www.host.com/list/archive/> (Web Archive)
|
||||
|
||||
4. Supporting Nested Lists
|
||||
|
||||
A list that is a sublist for another list in a nested mailing list
|
||||
hierarchy will need to modify some of the List- header fields, while
|
||||
leaving others as the parent list set them.
|
||||
|
||||
Sublists SHOULD remove the parent list's List-Help, List-Subscribe,
|
||||
List-Unsubscribe and List-Owner fields, and SHOULD insert their own
|
||||
versions of those fields.
|
||||
|
||||
If the sublist provides its own archive, it SHOULD replace the List-
|
||||
Archive with its own. Otherwise, it MUST leave the List-Archive field
|
||||
untouched.
|
||||
|
||||
Dependant on how postings to the list are handled, the sublist MAY
|
||||
replace the List-Post field. The appropriateness of whether to
|
||||
replace List-Post is left to the determination of the individual list
|
||||
managers. If the intention is that postings should be distributed to
|
||||
all members of the primary list, List-Post should not be changed by a
|
||||
sublist in such a way that postings will be distributed only to
|
||||
members of the sublist.
|
||||
|
||||
5. Security Considerations
|
||||
|
||||
There are very few new security concerns generated with this
|
||||
proposal. Message headers are an existing standard, designed to
|
||||
easily accommodate new types. There may be concern with multiple
|
||||
fields being inserted or headers being forged, but these are problems
|
||||
inherent in Internet email, not specific to the protocol described in
|
||||
this document. Further, the implications are relatively harmless.
|
||||
|
||||
Mail list processors should not allow any user-originated list header
|
||||
fields to pass through to their lists, lest they confuse the user and
|
||||
have the potential to create security problems.
|
||||
|
||||
On the client side, there may be some concern with posts or commands
|
||||
being sent in error. It is required that the user have a chance to
|
||||
confirm any action before it is executed. In the case of mailto, it
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 6]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
may be appropriate to create the correctly formatted message without
|
||||
sending it, allowing the user to see exactly what is happening and
|
||||
giving the user the opportunity to approve or discard the message
|
||||
before it is sent.
|
||||
|
||||
All security considerations for the use of URLs [RFC1738] apply
|
||||
equally to this protocol. Mail client applications should not support
|
||||
list header field URLs which could compromise the security of the
|
||||
user's system. This includes the "file://" URL type which could
|
||||
potentially be used to trigger the execution of a local application
|
||||
on some user systems.
|
||||
|
||||
6. Acknowledgements
|
||||
|
||||
The numerous participants of the List-Header [5], ListMom-Talk [6],
|
||||
List-Managers and MIDA-Mail mailing lists contributed much to the
|
||||
formation and structure of this document.
|
||||
|
||||
Keith Moore <moore@cs.utk.edu> and Christopher Allen
|
||||
<ChristopherA@consensus.com> provided guidance on the standards
|
||||
process.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 7]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
A. Background Discussion
|
||||
|
||||
This proposal arose from discussions started on the ListMom-Talk
|
||||
Discussion List [6]. When the discussion reached a sufficient level,
|
||||
a separate list was formed for discussing this proposal, the List
|
||||
Headers Mail List [5] for deeper discussion. We have included
|
||||
summaries of key issues raised, in order to show some of the
|
||||
alternatives examined and reasons for our decisions.
|
||||
|
||||
A.1. Multiple header fields vs. a single header field
|
||||
|
||||
Use of a single header field for transporting command meta-syntax was
|
||||
rejected for a number of reasons.
|
||||
|
||||
Such a field would require the creation of a new meta-syntax in order
|
||||
to describe the list commands (as opposed to the use of the widely
|
||||
deployed URL syntax which was chosen for this implementation). Every
|
||||
additional layer of complexity and newness reduces the likelihood of
|
||||
actual implementation because it will require additional work to
|
||||
support. Also, by using the existing URL syntax, we can profit from
|
||||
the end users' knowledge of that syntax and ability to use it even if
|
||||
their client applications do not support the list header fields.
|
||||
|
||||
Restricting the transport of meta-syntax to the use of a single
|
||||
header field also introduces complications with header field size
|
||||
limitations. Most individual commands can easily be described in a
|
||||
single line, but describing a multitude of commands can take up many
|
||||
lines in the field and runs a greater risk of being modified by an
|
||||
existing server on route.
|
||||
|
||||
The client implementation is also easier with multiple fields, since
|
||||
each command can be supported and implemented individually,
|
||||
completely independent of the others. Thus, some list managers or
|
||||
mail clients can choose to implement a subset of the fields based on
|
||||
the specific needs of their individual lists.
|
||||
|
||||
Finally, the format described in this document is simple and well
|
||||
recognized, which reduces the chances of errors in implementation and
|
||||
parsing.
|
||||
|
||||
A.2. URLs vs. parameter lists
|
||||
|
||||
URLs are already an established syntax which is flexible, well-
|
||||
defined, and in wide spread use. As its definition matures and
|
||||
expands, the abilities of the list fields will grow as well, without
|
||||
requiring modification of this proposal. URLs are well prepared to
|
||||
handle future protocols and developments, and can easily describe the
|
||||
different existing access protocols such as mailto, http and ftp.
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 8]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
Many clients already have functionality for recognizing, parsing, and
|
||||
evaluating URLs, either internally or by passing the request to a
|
||||
helper application. This makes implementation easier and more
|
||||
realistic. As an example, this existing support for URL parsing
|
||||
allowed us to add prototype list header functionality to existing
|
||||
mail clients (Eudora and Emailer for the Macintosh) without modifying
|
||||
their source code.
|
||||
|
||||
A.3. Why not just create a standard command language?
|
||||
|
||||
A standard command language, supported by all email list services,
|
||||
would go a long way to reducing the problems of list access that
|
||||
currently plague existing services. It would reduce the amount of
|
||||
learning required by end users and allow for a number of common
|
||||
support tools to be developed.
|
||||
|
||||
However, such standardization does pose problems in the areas of
|
||||
multi-lingual support and the custom needs of individual mailing
|
||||
lists. The development of such a standard is also expected to be met
|
||||
with a slow adoption rate by software developers and list service
|
||||
providers.
|
||||
|
||||
These points do not preclude the development of such a standard (in
|
||||
fact, it would suggest that we should start sooner rather than
|
||||
later), but we do need a solution that can be widely supported by the
|
||||
current list services.
|
||||
|
||||
We can support most existing list manager command syntaxes without a
|
||||
standard command language. By using URLs, we allow alternate access
|
||||
methods a standard command language probably wouldn't enable, such as
|
||||
web based control.
|
||||
|
||||
Finally, client support for a standard command language is not at all
|
||||
clear or necessarily simple to implement. The variety and large
|
||||
number of commands existing today would require complicated user
|
||||
interfaces which could be confusing and difficult to implement. By
|
||||
restricting this proposal to the core functions, the client
|
||||
|
||||
implementation is much simpler, which significantly increases the
|
||||
likelihood of implementation (as evidenced by the support already
|
||||
announced by a number of client and server application authors).
|
||||
|
||||
A.4. Internationalization
|
||||
|
||||
Multilingual support is up to the URL standard. If URLs support it,
|
||||
then the List- header fields support it. This is another advantage of
|
||||
using URLs as the building blocks for the list header fields.
|
||||
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 9]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
A.5. Variable Substitution
|
||||
|
||||
Variables would allow the List- header fields to accommodate nearly
|
||||
every existing list manager. However, it would immeasurably increase
|
||||
the complexity of the entire proposal, and possibly involve
|
||||
redefining the URL standard, or force us to use something more
|
||||
complicated (and hence more difficult to implement) than URLs to
|
||||
describe the command syntax.
|
||||
|
||||
Parameters would either have to be mandatory (i.e. the user agent
|
||||
doesn't submit the message if it doesn't know what text to
|
||||
substitute) or you need a way to say "if you know this parameter, add
|
||||
its text here; otherwise, do this" where "this" is either: (a)
|
||||
substitute a constant string, or (b) fail.
|
||||
|
||||
The reason you would want a facility like this is because some list
|
||||
server applications insist on having certain parameters like users'
|
||||
names, which the user agent might or might not know. e.g. listserv
|
||||
insists on having a first name and a last name if you supply either
|
||||
one.
|
||||
|
||||
Which could lead to something like the UNIX shell syntax, where
|
||||
${foo-bar} means substitute the value of parameter "foo" if "foo" is
|
||||
defined, else substitute the string "bar". Perhaps $foo would mean
|
||||
"substitute the value of parameter foo if it is defined, else
|
||||
substitute the empty string"
|
||||
|
||||
This all seems far too complicated for the gains involved, especially
|
||||
since the use of variables can often be avoided.
|
||||
|
||||
The use of variables in the command syntaxes of list services appears
|
||||
to be lessening and does not, in any case, apply to all commands.
|
||||
While the unsubscribe and subscribe command header fields may not be
|
||||
usable by those systems which require the use of variables, the help
|
||||
field will still provide end users with a consistent point of access
|
||||
through which they can get support for their use of the list.
|
||||
|
||||
A.6. Why not use a specialized MIME part instead of header fields?
|
||||
|
||||
MIME parts were considered, but because most mail clients currently
|
||||
either don't support MIME or are not equipped to handle such
|
||||
specialized parts - such an implementation would result in problems
|
||||
for end users. It is also not as easy for many list servers to
|
||||
implement MIME as it is to implement new header fields.
|
||||
|
||||
However, we are looking at the design of a MIME part to more fully
|
||||
describe list command syntax, as well as trying to find ways to get
|
||||
it supported by the applicable software.
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 10]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
A.7. Why include a Subscribe command?
|
||||
|
||||
Subscribe and Unsubscribe are the key commands needed by almost every
|
||||
list. Other commands, such as digest mode, are not as widely
|
||||
supported.
|
||||
|
||||
Additionally, users who have unsubscribed (before going on vacation,
|
||||
or for whatever other reason) may want to resubscribe to a list. Or,
|
||||
a message may be forwarded/bounced from a subscriber to a non-
|
||||
subscriber. Or, the user may change addresses and want to subscribe
|
||||
from their new address. Having the List-Subscribe field available
|
||||
could certainly help in all these cases.
|
||||
|
||||
A.8. The Dangers of Header Bloat
|
||||
|
||||
At what point are there just too many header fields? It really
|
||||
varies on a list by list basis. On some lists, the majority of users
|
||||
will never be aware of a field unless the client software provides
|
||||
some alternative user interface to it (akin to the Reply-To field).
|
||||
On others, the users will often see the header fields of messages and
|
||||
would be able to recognize the function of the URLs contained within.
|
||||
|
||||
The flexibility afforded by the protocol described in this document
|
||||
(in that the header fields may be individually implemented as deemed
|
||||
appropriate) provides list administrators with sufficient 'room to
|
||||
maneuver' to meet their individual needs.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 11]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
B. Client Implementation
|
||||
|
||||
B.1. Guidelines
|
||||
|
||||
For 'mailto' URL based commands, mail client applications may choose
|
||||
to provide specialized feedback (such as presenting a dialog or
|
||||
alert), instead of the actual command email message, asking for
|
||||
command confirmation from the user. The feedback should identify the
|
||||
message destination and command within a more descriptive
|
||||
explanation. For example:
|
||||
|
||||
"Do you want to send the unsubscription command 'unsubscribe
|
||||
somelist' to 'somelist-request@some.host.com'? Sending the command
|
||||
will result in your removal from the associated list."
|
||||
|
||||
If the user has multiple email addresses supported by the mail
|
||||
client, the client application should prompt the user for which
|
||||
address to use when subscribing or performing some other action where
|
||||
the address to use cannot be specifically determined. When
|
||||
unsubscribing or such, the address that is subscribed should be used,
|
||||
unless that is not known by the application and cannot be determined
|
||||
from the message headers.
|
||||
|
||||
B.2. Implementation Options
|
||||
|
||||
The following implementation possibilities are suggested here to give
|
||||
some idea as to why these new header fields will be useful, and how
|
||||
they could be supported.
|
||||
|
||||
In most cases, it may be helpful to disable the interface for the
|
||||
commands when not applicable to the currently selected message.
|
||||
|
||||
B.2.1. Key combinations and command lines
|
||||
|
||||
On text based systems which utilize command lines or key
|
||||
combinations, each field could be implemented as a separate command.
|
||||
Thus one combination would subscribe the user, another would
|
||||
unsubscribe, a third request help, etc. The commands would only be
|
||||
available on messages containing the list header fields.
|
||||
|
||||
B.2.2. Menu items
|
||||
|
||||
On graphical systems which have menus, these commands could take the
|
||||
form of a menu or sub-menu of items. For example, a "Lists" menu
|
||||
might appear when viewing messages containing the header fields, with
|
||||
items named "Subscribe", "Unsubscribe", "Get Help", "Post Message to
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 12]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
List", "Contact List Owner" and "Access List Archive". This menu
|
||||
could be disabled when not applicable to the current message or
|
||||
disappear entirely.
|
||||
|
||||
B.2.3. Push Buttons and Pallettes
|
||||
|
||||
On graphical window systems, buttons could be placed in the window of
|
||||
the message, a toolbar, or in a floating pallette of their own. Each
|
||||
button could correspond to a command, with names "Subscribe",
|
||||
"Unsubscribe", "Get Help", "Post to List", "List Owner" and
|
||||
"Archive". These buttons or pallettes could be disabled when not
|
||||
applicable to the current message or disappear entirely.
|
||||
|
||||
B.2.4 Feedback to the User
|
||||
|
||||
If using a dialog interface (or other feedback element) the client
|
||||
application MUST include an option for the user to review (and
|
||||
possibly modify) the message before it is sent. The application may
|
||||
also find it useful to provide a link to more detailed context-
|
||||
sensitive assistance about mail list access in general.
|
||||
|
||||
References
|
||||
|
||||
[RFC822] Crocker, D., "Standard for the Format of ARPA
|
||||
Internet Text Messages", STD 11, RFC 822, August 1982.
|
||||
|
||||
[RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill,
|
||||
"Uniform Resource Locators (URL)" RFC 1738, December 1994.
|
||||
|
||||
[RFC2142] Crocker, D., "Mailbox Names for Common Services, Roles and
|
||||
Functions", RFC 2142, May 1997.
|
||||
|
||||
[RFC2368] Hoffman, P., Masinter, L., and J. Zawinski, "The mailto URL
|
||||
scheme", RFC 2368, July 1998.
|
||||
|
||||
[5] "List-Header" Mail list. list-header@list.nisto.com
|
||||
<URL:http://www.nisto.com/listspec/mail/>
|
||||
<URL:http://www.nisto.com/listspec/>
|
||||
|
||||
[6] "ListMom-Talk" Mail list. listmom-talk@skyweyr.com
|
||||
<URL:http://cgi.skyweyr.com/ListMom.Home>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 13]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
Editors' Addresses
|
||||
|
||||
Joshua D. Baer
|
||||
Box 273
|
||||
4902 Forbes Avenue
|
||||
Pittsburgh, PA 15213-3799
|
||||
USA
|
||||
|
||||
EMail: josh@skyweyr.com
|
||||
|
||||
|
||||
Grant Neufeld
|
||||
Calgary, Alberta
|
||||
Canada
|
||||
|
||||
EMail: grant@acm.org
|
||||
Web: http://www.nisto.com/
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 14]
|
||||
|
||||
RFC 2369 URLs as Meta-Syntax July 1998
|
||||
|
||||
|
||||
Full Copyright Statement
|
||||
|
||||
Copyright (C) The Internet Society (1998). All Rights Reserved.
|
||||
|
||||
This document and translations of it may be copied and furnished to
|
||||
others, and derivative works that comment on or otherwise explain it
|
||||
or assist in its implementation may be prepared, copied, published
|
||||
and distributed, in whole or in part, without restriction of any
|
||||
kind, provided that the above copyright notice and this paragraph are
|
||||
included on all such copies and derivative works. However, this
|
||||
document itself may not be modified in any way, such as by removing
|
||||
the copyright notice or references to the Internet Society or other
|
||||
Internet organizations, except as needed for the purpose of
|
||||
developing Internet standards in which case the procedures for
|
||||
copyrights defined in the Internet Standards process must be
|
||||
followed, or as required to translate it into languages other than
|
||||
English.
|
||||
|
||||
The limited permissions granted above are perpetual and will not be
|
||||
revoked by the Internet Society or its successors or assigns.
|
||||
|
||||
This document and the information contained herein is provided on an
|
||||
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
|
||||
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
|
||||
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
|
||||
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
|
||||
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Neufeld & Baer Standards Track [Page 15]
|
||||
|
||||
Binary file not shown.
File diff suppressed because it is too large
Load Diff
Binary file not shown.
File diff suppressed because it is too large
Load Diff
Binary file not shown.
@@ -0,0 +1,614 @@
|
||||
|
||||
|
||||
|
||||
|
||||
Internet Engineering Task Force (IETF) R. Ouazana, Ed.
|
||||
Request for Comments: 9007 Linagora
|
||||
Category: Standards Track March 2021
|
||||
ISSN: 2070-1721
|
||||
|
||||
|
||||
Handling Message Disposition Notification with the JSON Meta Application
|
||||
Protocol (JMAP)
|
||||
|
||||
Abstract
|
||||
|
||||
This document specifies a data model for handling Message Disposition
|
||||
Notifications (MDNs) (see RFC 8098) in the JSON Meta Application
|
||||
Protocol (JMAP) (see RFCs 8620 and 8621).
|
||||
|
||||
Status of This Memo
|
||||
|
||||
This is an Internet Standards Track document.
|
||||
|
||||
This document is a product of the Internet Engineering Task Force
|
||||
(IETF). It represents the consensus of the IETF community. It has
|
||||
received public review and has been approved for publication by the
|
||||
Internet Engineering Steering Group (IESG). Further information on
|
||||
Internet Standards is available in Section 2 of RFC 7841.
|
||||
|
||||
Information about the current status of this document, any errata,
|
||||
and how to provide feedback on it may be obtained at
|
||||
https://www.rfc-editor.org/info/rfc9007.
|
||||
|
||||
Copyright Notice
|
||||
|
||||
Copyright (c) 2021 IETF Trust and the persons identified as the
|
||||
document authors. All rights reserved.
|
||||
|
||||
This document is subject to BCP 78 and the IETF Trust's Legal
|
||||
Provisions Relating to IETF Documents
|
||||
(https://trustee.ietf.org/license-info) in effect on the date of
|
||||
publication of this document. Please review these documents
|
||||
carefully, as they describe your rights and restrictions with respect
|
||||
to this document. Code Components extracted from this document must
|
||||
include Simplified BSD License text as described in Section 4.e of
|
||||
the Trust Legal Provisions and are provided without warranty as
|
||||
described in the Simplified BSD License.
|
||||
|
||||
Table of Contents
|
||||
|
||||
1. Introduction
|
||||
1.1. Notational Conventions
|
||||
1.2. Terminology
|
||||
1.3. Addition to the Capabilities Object
|
||||
2. MDN
|
||||
2.1. MDN/send
|
||||
2.2. MDN/parse
|
||||
3. Samples
|
||||
3.1. Sending an MDN for a Received Email Message
|
||||
3.2. Asking for an MDN When Sending an Email Message
|
||||
3.3. Parsing a Received MDN
|
||||
4. IANA Considerations
|
||||
4.1. JMAP Capability Registration for "mdn"
|
||||
4.2. JMAP Error Codes Registration for "mdnAlreadySent"
|
||||
5. Security Considerations
|
||||
6. Normative References
|
||||
Author's Address
|
||||
|
||||
1. Introduction
|
||||
|
||||
JMAP ("The JSON Meta Application Protocol (JMAP)" [RFC8620]) is a
|
||||
generic protocol for synchronising data, such as mail, calendars, or
|
||||
contacts, between a client and a server. It is optimised for mobile
|
||||
and web environments, and it provides a consistent interface to
|
||||
different data types.
|
||||
|
||||
JMAP for Mail ("The JSON Meta Application Protocol (JMAP) for Mail"
|
||||
[RFC8621]) specifies a data model for synchronising email data with a
|
||||
server using JMAP. Clients can use this to efficiently search,
|
||||
access, organise, and send messages.
|
||||
|
||||
Message Disposition Notifications (MDNs) are defined in [RFC8098] and
|
||||
are used as "read receipts", "acknowledgements", or "receipt
|
||||
notifications".
|
||||
|
||||
A client can come across MDNs in different ways:
|
||||
|
||||
1. When receiving an email message, an MDN can be sent to the
|
||||
sender. This specification defines an "MDN/send" method to cover
|
||||
this case.
|
||||
|
||||
2. When sending an email message, an MDN can be requested. This
|
||||
must be done with the help of a header field, as already
|
||||
specified by [RFC8098]; the header field can already be handled
|
||||
by guidance in [RFC8621].
|
||||
|
||||
3. When receiving an MDN, the MDN could be related to an existing
|
||||
sent message. This is already covered by [RFC8621] in the
|
||||
EmailSubmission object. A client might want to display detailed
|
||||
information about a received MDN. This specification defines an
|
||||
"MDN/parse" method to cover this case.
|
||||
|
||||
1.1. Notational Conventions
|
||||
|
||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
|
||||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
|
||||
"OPTIONAL" in this document are to be interpreted as described in
|
||||
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
|
||||
capitals, as shown here.
|
||||
|
||||
Type signatures, examples, and property descriptions in this document
|
||||
follow the conventions established in Section 1.1 of [RFC8620]. Data
|
||||
types defined in the core specification are also used in this
|
||||
document.
|
||||
|
||||
Servers MUST support all properties specified for the new data types
|
||||
defined in this document.
|
||||
|
||||
1.2. Terminology
|
||||
|
||||
The same terminology is used in this document as in the core JMAP
|
||||
specification.
|
||||
|
||||
Because keywords are case insensitive in IMAP but case sensitive in
|
||||
JMAP, the "$mdnsent" keyword MUST always be used in lowercase.
|
||||
|
||||
1.3. Addition to the Capabilities Object
|
||||
|
||||
Capabilities are announced as part of the standard JMAP Session
|
||||
resource; see [RFC8620], Section 2. This defines a new capability,
|
||||
"urn:ietf:params:jmap:mdn".
|
||||
|
||||
The capability "urn:ietf:params:jmap:mdn" being present in the
|
||||
"accountCapabilities" property of an account represents support for
|
||||
the "MDN" data type, parsing MDNs via the "MDN/parse" method, and
|
||||
creating and sending MDN messages via the "MDN/send" method. Servers
|
||||
that include the capability in one or more "accountCapabilities"
|
||||
properties MUST also include the property in the "capabilities"
|
||||
property.
|
||||
|
||||
The value of this "urn:ietf:params:jmap:mdn" property is an empty
|
||||
object both in the account's "accountCapabilities" property and in
|
||||
the "capabilities" property.
|
||||
|
||||
2. MDN
|
||||
|
||||
An *MDN* object has the following properties:
|
||||
|
||||
* forEmailId: "Id|null"
|
||||
|
||||
The Email id of the received message to which this MDN is related.
|
||||
This property MUST NOT be null for "MDN/send" but MAY be null in
|
||||
the response from the "MDN/parse" method.
|
||||
|
||||
* subject: "String|null"
|
||||
|
||||
The subject used as "Subject" header field for this MDN.
|
||||
|
||||
* textBody: "String|null"
|
||||
|
||||
The human-readable part of the MDN, as plain text.
|
||||
|
||||
* includeOriginalMessage: "Boolean" (default: false)
|
||||
|
||||
If "true", the content of the original message will appear in the
|
||||
third component of the multipart/report generated for the MDN.
|
||||
See [RFC8098] for details and security considerations.
|
||||
|
||||
* reportingUA: "String|null"
|
||||
|
||||
The name of the Mail User Agent (MUA) creating this MDN. It is
|
||||
used to build the MDN report part of the MDN. Note that a "null"
|
||||
value may have better privacy properties.
|
||||
|
||||
* disposition: "Disposition"
|
||||
|
||||
The object containing the diverse MDN disposition options.
|
||||
|
||||
* mdnGateway: "String|null" (server-set)
|
||||
|
||||
The name of the gateway or Message Transfer Agent (MTA) that
|
||||
translated a foreign (non-Internet) message disposition
|
||||
notification into this MDN.
|
||||
|
||||
* originalRecipient: "String|null" (server-set)
|
||||
|
||||
The original recipient address as specified by the sender of the
|
||||
message for which the MDN is being issued.
|
||||
|
||||
* finalRecipient: "String|null"
|
||||
|
||||
The recipient for which the MDN is being issued. If set, it
|
||||
overrides the value that would be calculated by the server from
|
||||
the Identity defined in the "MDN/send" method, unless explicitly
|
||||
set by the client.
|
||||
|
||||
* originalMessageId: "String|null" (server-set)
|
||||
|
||||
The "Message-ID" header field [RFC5322] (not the JMAP id) of the
|
||||
message for which the MDN is being issued.
|
||||
|
||||
* error: "String[]|null" (server-set)
|
||||
|
||||
Additional information in the form of text messages when the
|
||||
"error" disposition modifier appears.
|
||||
|
||||
* extensionFields: "String[String]|null"
|
||||
|
||||
The object where keys are extension-field names, and values are
|
||||
extension-field values (see [RFC8098], Section 3.3).
|
||||
|
||||
A *Disposition* object has the following properties:
|
||||
|
||||
* actionMode: "String"
|
||||
|
||||
This MUST be one of the following strings: "manual-action" /
|
||||
"automatic-action"
|
||||
|
||||
* sendingMode: "String"
|
||||
|
||||
This MUST be one of the following strings: "mdn-sent-manually" /
|
||||
"mdn-sent-automatically"
|
||||
|
||||
* type: "String"
|
||||
|
||||
This MUST be one of the following strings: "deleted" /
|
||||
"dispatched" / "displayed" / "processed"
|
||||
|
||||
See [RFC8098] for the exact meaning of these different fields. These
|
||||
fields are defined as case insensitive in [RFC8098] but are case
|
||||
sensitive in this RFC and MUST be converted to lowercase by "MDN/
|
||||
parse".
|
||||
|
||||
2.1. MDN/send
|
||||
|
||||
The "MDN/send" method sends a message in the style of [RFC5322] from
|
||||
an MDN object. When calling this method, the "using" property of the
|
||||
Request object MUST contain the capabilities
|
||||
"urn:ietf:params:jmap:mdn" and "urn:ietf:params:jmap:mail"; the
|
||||
latter because of the implicit call to "Email/set" and the use of
|
||||
Identity objects, which is described below. The method takes the
|
||||
following arguments:
|
||||
|
||||
* accountId: "Id"
|
||||
|
||||
The id of the account to use.
|
||||
|
||||
* identityId: "Id"
|
||||
|
||||
The id of the Identity to associate with these MDNs. The server
|
||||
will use this identity to define the sender of the MDNs and to set
|
||||
the "finalRecipient" field.
|
||||
|
||||
* send: "Id[MDN]"
|
||||
|
||||
A map of the creation id (client specified) to MDN objects.
|
||||
|
||||
* onSuccessUpdateEmail: "Id[PatchObject]|null"
|
||||
|
||||
A map of the id to an object containing properties to update on
|
||||
the Email object referenced by the "MDN/send" if the sending
|
||||
succeeds. This will always be a backward reference to the
|
||||
creation id (see the example below in Section 3.1).
|
||||
|
||||
The response has the following arguments:
|
||||
|
||||
* accountId: "Id"
|
||||
|
||||
The id of the account used for the call.
|
||||
|
||||
* sent: "Id[MDN]|null"
|
||||
|
||||
A map of the creation id to an MDN containing any properties that
|
||||
were not set by the client. This includes any properties that
|
||||
were omitted by the client and thus set to a default by the
|
||||
server. This argument is null if no MDN objects were successfully
|
||||
sent.
|
||||
|
||||
* notSent: "Id[SetError]|null"
|
||||
|
||||
A map of the creation id to a SetError object for each record that
|
||||
failed to be sent or null if all successful.
|
||||
|
||||
In this context, the existing SetError types defined in [RFC8620] and
|
||||
[RFC8621] are interpreted as follows:
|
||||
|
||||
notFound: The reference "forEmailId" cannot be found or has no valid
|
||||
"Disposition-Notification-To" header field.
|
||||
|
||||
forbidden: "MDN/send" would violate an Access Control List (ACL) or
|
||||
other permissions policy.
|
||||
|
||||
forbiddenFrom: The user is not allowed to use the given
|
||||
"finalRecipient" property.
|
||||
|
||||
overQuota: "MDN/send" would exceed a server-defined limit on the
|
||||
number or total size of sent MDNs. It could include limitations
|
||||
on sent messages.
|
||||
|
||||
tooLarge: "MDN/send" would result in an MDN that exceeds a server-
|
||||
defined limit for the maximum size of an MDN or more generally, on
|
||||
email message.
|
||||
|
||||
rateLimit: Too many MDNs or email messages have been created
|
||||
recently, and a server-defined rate limit has been reached. It
|
||||
may work if tried again later.
|
||||
|
||||
invalidProperties: The record given is invalid in some way.
|
||||
|
||||
The following is a new SetError:
|
||||
|
||||
mdnAlreadySent: The message has the "$mdnsent" keyword already set.
|
||||
|
||||
If the "accountId" or "identityId" given cannot be found, the method
|
||||
call is rejected with an "invalidArguments" error.
|
||||
|
||||
The client MUST NOT issue an "MDN/send" request if the message has
|
||||
the "$mdnsent" keyword set.
|
||||
|
||||
When sending the MDN, the server is in charge of generating the
|
||||
"originalRecipient" and "originalMessageId" fields according to
|
||||
[RFC8098]. "finalRecipient" will also generally be generated by the
|
||||
server based on the provided identity, but if specified by the client
|
||||
and allowed (see Section 5), the server will use the client-provided
|
||||
value.
|
||||
|
||||
The client is expected to explicitly update each "Email" for which an
|
||||
"MDN/send" has been invoked in order to set the "$mdnsent" keyword on
|
||||
these messages. To ensure that, the server MUST reject an "MDN/send"
|
||||
that does not result in setting the keyword "$mdnsent". Thus, the
|
||||
server MUST check that the "onSuccessUpdateEmail" property of the
|
||||
method is correctly set to update this keyword.
|
||||
|
||||
2.2. MDN/parse
|
||||
|
||||
This method allows a client to parse blobs as messages in the style
|
||||
of [RFC5322] to get MDN objects. This can be used to parse and get
|
||||
detailed information about blobs referenced in the "mdnBlobIds" of
|
||||
the EmailSubmission object or any email message the client could
|
||||
expect to be an MDN.
|
||||
|
||||
The "forEmailId" property can be null or missing if the
|
||||
"originalMessageId" property is missing or does not refer to an
|
||||
existing message or if the server cannot efficiently calculate the
|
||||
related message (for example, if several messages get the same
|
||||
"Message-ID" header field).
|
||||
|
||||
The "MDN/parse" method takes the following arguments:
|
||||
|
||||
* accountId: "Id"
|
||||
|
||||
The id of the account to use.
|
||||
|
||||
* blobIds: "Id[]"
|
||||
|
||||
The ids of the blobs to parse.
|
||||
|
||||
The response has the following arguments:
|
||||
|
||||
* accountId: "Id"
|
||||
|
||||
The id of the account used for the call.
|
||||
|
||||
* parsed: "Id[MDN]|null"
|
||||
|
||||
A map of the blob id to a parsed MDN representation for each
|
||||
successfully parsed blob or null if none.
|
||||
|
||||
* notParsable: "Id[]|null"
|
||||
|
||||
A list of ids given that corresponds to blobs that could not be
|
||||
parsed as MDNs or null if none.
|
||||
|
||||
* notFound: "Id[]|null"
|
||||
|
||||
A list of blob ids given that could not be found or null if none.
|
||||
|
||||
The following additional errors may be returned instead of the "MDN/
|
||||
parse" response:
|
||||
|
||||
requestTooLarge: The number of ids requested by the client exceeds
|
||||
the maximum number the server is willing to process in a single
|
||||
method call.
|
||||
|
||||
invalidArguments: If the given "accountId" cannot be found, the MDN
|
||||
parsing is rejected with an "invalidArguments" error.
|
||||
|
||||
3. Samples
|
||||
|
||||
3.1. Sending an MDN for a Received Email Message
|
||||
|
||||
A client can use the following request to send an MDN back to the
|
||||
sender:
|
||||
|
||||
[[ "MDN/send", {
|
||||
"accountId": "ue150411c",
|
||||
"identityId": "I64588216",
|
||||
"send": {
|
||||
"k1546": {
|
||||
"forEmailId": "Md45b47b4877521042cec0938",
|
||||
"subject": "Read receipt for: World domination",
|
||||
"textBody": "This receipt shows that the email has been
|
||||
displayed on your recipient's computer. There is no
|
||||
guarantee it has been read or understood.",
|
||||
"reportingUA": "joes-pc.cs.example.com; Foomail 97.1",
|
||||
"disposition": {
|
||||
"actionMode": "manual-action",
|
||||
"sendingMode": "mdn-sent-manually",
|
||||
"type": "displayed"
|
||||
},
|
||||
"extension": {
|
||||
"EXTENSION-EXAMPLE": "example.com"
|
||||
}
|
||||
}
|
||||
},
|
||||
"onSuccessUpdateEmail": {
|
||||
"#k1546": {
|
||||
"keywords/$mdnsent": true
|
||||
}
|
||||
}
|
||||
}, "0" ]]
|
||||
|
||||
If the email id matches an existing email message without the
|
||||
"$mdnsent" keyword, the server can answer:
|
||||
|
||||
[[ "MDN/send", {
|
||||
"accountId": "ue150411c",
|
||||
"sent": {
|
||||
"k1546": {
|
||||
"finalRecipient": "rfc822; john@example.com",
|
||||
"originalMessageId": "<199509192301.23456@example.org>"
|
||||
}
|
||||
}
|
||||
}, "0" ],
|
||||
[ "Email/set", {
|
||||
"accountId": "ue150411c",
|
||||
"oldState": "23",
|
||||
"newState": "42",
|
||||
"updated": {
|
||||
"Md45b47b4877521042cec0938": {}
|
||||
}
|
||||
}, "0" ]]
|
||||
|
||||
If the "$mdnsent" keyword has already been set, the server can answer
|
||||
an error:
|
||||
|
||||
[[ "MDN/send", {
|
||||
"accountId": "ue150411c",
|
||||
"notSent": {
|
||||
"k1546": {
|
||||
"type": "mdnAlreadySent",
|
||||
"description" : "$mdnsent keyword is already present"
|
||||
}
|
||||
}
|
||||
}, "0" ]]
|
||||
|
||||
3.2. Asking for an MDN When Sending an Email Message
|
||||
|
||||
This is done with the "Email/set" "create" method of [RFC8621].
|
||||
|
||||
[[ "Email/set", {
|
||||
"accountId": "ue150411c",
|
||||
"create": {
|
||||
"k2657": {
|
||||
"mailboxIds": {
|
||||
"2ea1ca41b38e": true
|
||||
},
|
||||
"keywords": {
|
||||
"$seen": true,
|
||||
"$draft": true
|
||||
},
|
||||
"from": [{
|
||||
"name": "Joe Bloggs",
|
||||
"email": "joe@example.com"
|
||||
}],
|
||||
"to": [{
|
||||
"name": "John",
|
||||
"email": "john@example.com"
|
||||
}],
|
||||
"header:Disposition-Notification-To:asText": "joe@example.com",
|
||||
"subject": "World domination",
|
||||
...
|
||||
}
|
||||
}
|
||||
}, "0" ]]
|
||||
|
||||
Note the specified "Disposition-Notification-To" header field
|
||||
indicating where to send the MDN (usually the sender of the message).
|
||||
|
||||
3.3. Parsing a Received MDN
|
||||
|
||||
The client issues a parse request:
|
||||
|
||||
[[ "MDN/parse", {
|
||||
"accountId": "ue150411c",
|
||||
"blobIds": [ "0f9f65ab-dc7b-4146-850f-6e4881093965" ]
|
||||
}, "0" ]]
|
||||
|
||||
The server responds:
|
||||
|
||||
[[ "MDN/parse", {
|
||||
"accountId": "ue150411c",
|
||||
"parsed": {
|
||||
"0f9f65ab-dc7b-4146-850f-6e4881093965": {
|
||||
"forEmailId": "Md45b47b4877521042cec0938",
|
||||
"subject": "Read receipt for: World domination",
|
||||
"textBody": "This receipt shows that the email has been
|
||||
displayed on your recipient's computer. There is no
|
||||
guarantee it has been read or understood.",
|
||||
"reportingUA": "joes-pc.cs.example.com; Foomail 97.1",
|
||||
"disposition": {
|
||||
"actionMode": "manual-action",
|
||||
"sendingMode": "mdn-sent-manually",
|
||||
"type": "displayed"
|
||||
},
|
||||
"finalRecipient": "rfc822; john@example.com",
|
||||
"originalMessageId": "<199509192301.23456@example.org>"
|
||||
}
|
||||
}
|
||||
}, "0" ]]
|
||||
|
||||
In the case that a blob id is not found, the server would respond:
|
||||
|
||||
[[ "MDN/parse", {
|
||||
"accountId": "ue150411c",
|
||||
"notFound": [ "0f9f65ab-dc7b-4146-850f-6e4881093965" ]
|
||||
}, "0" ]]
|
||||
|
||||
If the blob id has been found but is not parsable, the server would
|
||||
respond:
|
||||
|
||||
[[ "MDN/parse", {
|
||||
"accountId": "ue150411c",
|
||||
"notParsable": [ "0f9f65ab-dc7b-4146-850f-6e4881093965" ]
|
||||
}, "0" ]]
|
||||
|
||||
4. IANA Considerations
|
||||
|
||||
4.1. JMAP Capability Registration for "mdn"
|
||||
|
||||
This section registers the "mdn" JMAP Capability in the "JMAP
|
||||
Capabilities" registry as follows:
|
||||
|
||||
Capability Name: "urn:ietf:params:jmap:mdn"
|
||||
Intended Use: common
|
||||
Change Controller: IETF
|
||||
Security and Privacy Considerations: This document, Section 5.
|
||||
Reference: This document
|
||||
|
||||
4.2. JMAP Error Codes Registration for "mdnAlreadySent"
|
||||
|
||||
IANA has registered one new error code in the "JMAP Error Codes"
|
||||
registry, as defined in [RFC8620].
|
||||
|
||||
JMAP Error Code: mdnAlreadySent
|
||||
Intended Use: common
|
||||
Change Controller: IETF
|
||||
Description: The message has the "$mdnsent" keyword already set.
|
||||
The client MUST NOT try again to send an MDN for this message.
|
||||
Reference: This document, Section 2.1
|
||||
|
||||
5. Security Considerations
|
||||
|
||||
The same considerations regarding MDN (see [RFC8098] and [RFC3503])
|
||||
apply to this document.
|
||||
|
||||
In order to reinforce trust regarding the relation between the user
|
||||
sending an email message and the identity of this user, the server
|
||||
SHOULD validate in conformance to the provided Identity that the user
|
||||
is permitted to use the "finalRecipient" value and return a
|
||||
"forbiddenFrom" error if not.
|
||||
|
||||
6. Normative References
|
||||
|
||||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
|
||||
Requirement Levels", BCP 14, RFC 2119,
|
||||
DOI 10.17487/RFC2119, March 1997,
|
||||
<https://www.rfc-editor.org/info/rfc2119>.
|
||||
|
||||
[RFC3503] Melnikov, A., "Message Disposition Notification (MDN)
|
||||
profile for Internet Message Access Protocol (IMAP)",
|
||||
RFC 3503, DOI 10.17487/RFC3503, March 2003,
|
||||
<https://www.rfc-editor.org/info/rfc3503>.
|
||||
|
||||
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
|
||||
DOI 10.17487/RFC5322, October 2008,
|
||||
<https://www.rfc-editor.org/info/rfc5322>.
|
||||
|
||||
[RFC8098] Hansen, T., Ed. and A. Melnikov, Ed., "Message Disposition
|
||||
Notification", STD 85, RFC 8098, DOI 10.17487/RFC8098,
|
||||
February 2017, <https://www.rfc-editor.org/info/rfc8098>.
|
||||
|
||||
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
|
||||
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
|
||||
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
|
||||
|
||||
[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
|
||||
Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
|
||||
2019, <https://www.rfc-editor.org/info/rfc8620>.
|
||||
|
||||
[RFC8621] Jenkins, N. and C. Newman, "The JSON Meta Application
|
||||
Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621,
|
||||
August 2019, <https://www.rfc-editor.org/info/rfc8621>.
|
||||
|
||||
Author's Address
|
||||
|
||||
Raphaël Ouazana (editor)
|
||||
Linagora
|
||||
100 Terrasse Boieldieu - Tour Franklin
|
||||
92042 Paris - La Défense CEDEX
|
||||
France
|
||||
|
||||
Email: rouazana@linagora.com
|
||||
URI: https://www.linagora.com
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,518 @@
|
||||
|
||||
|
||||
|
||||
|
||||
Internet Engineering Task Force (IETF) R. Cordier, Ed.
|
||||
Request for Comments: 9425 Linagora Vietnam
|
||||
Category: Standards Track June 2023
|
||||
ISSN: 2070-1721
|
||||
|
||||
|
||||
JSON Meta Application Protocol (JMAP) for Quotas
|
||||
|
||||
Abstract
|
||||
|
||||
This document specifies a data model for handling quotas on accounts
|
||||
with a server using the JSON Meta Application Protocol (JMAP).
|
||||
|
||||
Status of This Memo
|
||||
|
||||
This is an Internet Standards Track document.
|
||||
|
||||
This document is a product of the Internet Engineering Task Force
|
||||
(IETF). It represents the consensus of the IETF community. It has
|
||||
received public review and has been approved for publication by the
|
||||
Internet Engineering Steering Group (IESG). Further information on
|
||||
Internet Standards is available in Section 2 of RFC 7841.
|
||||
|
||||
Information about the current status of this document, any errata,
|
||||
and how to provide feedback on it may be obtained at
|
||||
https://www.rfc-editor.org/info/rfc9425.
|
||||
|
||||
Copyright Notice
|
||||
|
||||
Copyright (c) 2023 IETF Trust and the persons identified as the
|
||||
document authors. All rights reserved.
|
||||
|
||||
This document is subject to BCP 78 and the IETF Trust's Legal
|
||||
Provisions Relating to IETF Documents
|
||||
(https://trustee.ietf.org/license-info) in effect on the date of
|
||||
publication of this document. Please review these documents
|
||||
carefully, as they describe your rights and restrictions with respect
|
||||
to this document. Code Components extracted from this document must
|
||||
include Revised BSD License text as described in Section 4.e of the
|
||||
Trust Legal Provisions and are provided without warranty as described
|
||||
in the Revised BSD License.
|
||||
|
||||
Table of Contents
|
||||
|
||||
1. Introduction
|
||||
1.1. Notational Conventions
|
||||
1.2. Terminology
|
||||
2. Addition to the Capabilities Object
|
||||
2.1. urn:ietf:params:jmap:quota
|
||||
3. Sub-types of the Quota Data Type
|
||||
3.1. Scope
|
||||
3.2. ResourceType
|
||||
4. Quota
|
||||
4.1. Properties of the Quota Object
|
||||
4.2. Quota/get
|
||||
4.3. Quota/changes
|
||||
4.4. Quota/query
|
||||
4.5. Quota/queryChanges
|
||||
5. Examples
|
||||
5.1. Fetching Quotas
|
||||
5.2. Requesting Latest Quota Changes
|
||||
6. Push
|
||||
7. IANA Considerations
|
||||
7.1. JMAP Capability Registration for "quota"
|
||||
7.2. JMAP Data Type Registration for "Quota"
|
||||
8. Security Considerations
|
||||
9. Normative References
|
||||
Acknowledgements
|
||||
Author's Address
|
||||
|
||||
1. Introduction
|
||||
|
||||
The JSON Meta Application Protocol (JMAP) [RFC8620] is a generic
|
||||
protocol for synchronizing data, such as mails, calendars, or
|
||||
contacts between a client and a server. It is optimized for mobile
|
||||
and web environments and aims to provide a consistent interface to
|
||||
different data types.
|
||||
|
||||
This specification defines a data model for handling quotas over
|
||||
JMAP, allowing a user to obtain details about a certain quota.
|
||||
|
||||
This specification does not address quota administration, which
|
||||
should be handled by other means.
|
||||
|
||||
1.1. Notational Conventions
|
||||
|
||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
|
||||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
|
||||
"OPTIONAL" in this document are to be interpreted as described in
|
||||
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
|
||||
capitals, as shown here.
|
||||
|
||||
Type signatures, examples, and property descriptions in this document
|
||||
follow the conventions established in Section 1.1 of [RFC8620]. Data
|
||||
types defined in the core specification are also used in this
|
||||
document.
|
||||
|
||||
1.2. Terminology
|
||||
|
||||
This document reuses the terminology from the core JMAP specification
|
||||
established in Section 1.6 of [RFC8620].
|
||||
|
||||
The term "Quota" (when capitalized) is used to refer to the data type
|
||||
defined in Section 4 and instance of that data type.
|
||||
|
||||
2. Addition to the Capabilities Object
|
||||
|
||||
The capabilities object is returned as part of the JMAP Session
|
||||
object; see [RFC8620], Section 2.
|
||||
|
||||
This document defines one additional capability URI.
|
||||
|
||||
2.1. urn:ietf:params:jmap:quota
|
||||
|
||||
This represents support for the Quota data type and associated API
|
||||
methods. Servers supporting this specification MUST add a property
|
||||
called "urn:ietf:params:jmap:quota" to the capabilities object.
|
||||
|
||||
The value of this property is an empty object in both the JMAP
|
||||
Session capabilities property and an account's accountCapabilities
|
||||
property.
|
||||
|
||||
3. Sub-types of the Quota Data Type
|
||||
|
||||
There are two fields within the Quota data type, which have an
|
||||
enumerated set of possible values. These are:
|
||||
|
||||
3.1. Scope
|
||||
|
||||
The Scope data type is used to represent the entities the quota
|
||||
applies to. It is defined as a "String" with values from the
|
||||
following set:
|
||||
|
||||
* account: The quota information applies to just the client's
|
||||
account.
|
||||
|
||||
* domain: The quota information applies to all accounts sharing this
|
||||
domain.
|
||||
|
||||
* global: The quota information applies to all accounts belonging to
|
||||
the server.
|
||||
|
||||
3.2. ResourceType
|
||||
|
||||
The ResourceType data type is used to act as a unit of measure for
|
||||
the quota usage. It is defined as a "String" with values from the
|
||||
following set:
|
||||
|
||||
* count: The quota is measured in a number of data type objects.
|
||||
For example, a quota can have a limit of 50 "Mail" objects.
|
||||
|
||||
* octets: The quota is measured in size (in octets). For example, a
|
||||
quota can have a limit of 25000 octets.
|
||||
|
||||
4. Quota
|
||||
|
||||
The Quota is an object that displays the limit set to an account
|
||||
usage. It then shows as well the current usage in regard to that
|
||||
limit.
|
||||
|
||||
4.1. Properties of the Quota Object
|
||||
|
||||
The Quota object MUST contain the following fields:
|
||||
|
||||
* id: Id
|
||||
|
||||
The unique identifier for this object.
|
||||
|
||||
* resourceType: String
|
||||
|
||||
The resource type of the quota as defined in Section 3.2.
|
||||
|
||||
* used: UnsignedInt
|
||||
|
||||
The current usage of the defined quota, using the "resourceType"
|
||||
defined as unit of measure. Computation of this value is handled
|
||||
by the server.
|
||||
|
||||
* hardLimit: UnsignedInt
|
||||
|
||||
The hard limit set by this quota, using the "resourceType" defined
|
||||
as unit of measure. Objects in scope may not be created or
|
||||
updated if this limit is reached.
|
||||
|
||||
* scope: String
|
||||
|
||||
The "Scope" of this quota as defined in Section 3.1.
|
||||
|
||||
* name: String
|
||||
|
||||
The name of the quota. Useful for managing quotas and using
|
||||
queries for searching.
|
||||
|
||||
* types: String[]
|
||||
|
||||
A list of all the type names as defined in the "JMAP Types Names"
|
||||
registry (e.g., Email, Calendar, etc.) to which this quota
|
||||
applies. This allows the quotas to be assigned to distinct or
|
||||
shared data types.
|
||||
|
||||
The server MUST filter out any types for which the client did not
|
||||
request the associated capability in the "using" section of the
|
||||
request. Further, the server MUST NOT return Quota objects for
|
||||
which there are no types recognized by the client.
|
||||
|
||||
The Quota object MAY contain the following fields:
|
||||
|
||||
* warnLimit: UnsignedInt|null
|
||||
|
||||
The warn limit set by this quota, using the "resourceType" defined
|
||||
as unit of measure. It can be used to send a warning to an entity
|
||||
about to reach the hard limit soon, but with no action taken yet.
|
||||
If set, it SHOULD be lower than the "softLimit" (if present and
|
||||
different from null) and the "hardLimit".
|
||||
|
||||
* softLimit: UnsignedInt|null
|
||||
|
||||
The soft limit set by this quota, using the "resourceType" defined
|
||||
as unit of measure. It can be used to still allow some operations
|
||||
but refuse some others. What is allowed or not is up to the
|
||||
server. For example, it could be used for blocking outgoing
|
||||
events of an entity (sending emails, creating calendar events,
|
||||
etc.) while still receiving incoming events (receiving emails,
|
||||
receiving calendars events, etc.). If set, it SHOULD be higher
|
||||
than the "warnLimit" (if present and different from null) but
|
||||
lower than the "hardLimit".
|
||||
|
||||
* description: String|null
|
||||
|
||||
Arbitrary, free, human-readable description of this quota. It
|
||||
might be used to explain where the different limits come from and
|
||||
explain the entities and data types this quota applies to. The
|
||||
description MUST be encoded in UTF-8 [RFC3629] as described in
|
||||
[RFC8620], Section 1.5, and selected based on an Accept-Language
|
||||
header in the request (as defined in [RFC9110], Section 12.5.4) or
|
||||
out-of-band information about the user's language or locale.
|
||||
|
||||
The following JMAP methods are supported.
|
||||
|
||||
4.2. Quota/get
|
||||
|
||||
Standard "/get" method as described in [RFC8620], Section 5.1. The
|
||||
_id_'s argument may be "null" to fetch all quotas of the account at
|
||||
once, as demonstrated in Section 5.1.
|
||||
|
||||
4.3. Quota/changes
|
||||
|
||||
Standard "/changes" method as described in [RFC8620], Section 5.2,
|
||||
but with one extra argument in the response:
|
||||
|
||||
* updatedProperties: String[]|null
|
||||
|
||||
If only the "used" Quota property has changed since the old state,
|
||||
this will be a list containing only that property. If the server
|
||||
is unable to tell if only "used" has changed, it MUST be null.
|
||||
|
||||
Since "used" frequently changes, but other properties are generally
|
||||
only changed rarely, the server can help the client optimize data
|
||||
transfer by keeping track of changes to quota usage separate from
|
||||
other state changes. The updatedProperties array may be used
|
||||
directly via a back-reference in a subsequent Quota/get call in the
|
||||
same request, so only these properties are returned if nothing else
|
||||
has changed.
|
||||
|
||||
Servers MAY decide to add other properties to the list that they
|
||||
judge to be changing frequently.
|
||||
|
||||
This method's usage is demonstrated in Section 5.2.
|
||||
|
||||
4.4. Quota/query
|
||||
|
||||
This is a standard "/query" method as described in [RFC8620],
|
||||
Section 5.5.
|
||||
|
||||
A FilterCondition object has the following properties, any of which
|
||||
may be included or omitted:
|
||||
|
||||
* name: String
|
||||
|
||||
The Quota _name_ property contains the given string.
|
||||
|
||||
* scope: String
|
||||
|
||||
The Quota _scope_ property must match the given value exactly.
|
||||
|
||||
* resourceType: String
|
||||
|
||||
The Quota _resourceType_ property must match the given value
|
||||
exactly.
|
||||
|
||||
* type: String
|
||||
|
||||
The Quota _types_ property contains the given value.
|
||||
|
||||
A Quota object matches the FilterCondition if, and only if, all the
|
||||
given conditions match. If zero properties are specified, it is
|
||||
automatically true for all objects.
|
||||
|
||||
The following Quota properties MUST be supported for sorting:
|
||||
|
||||
* name
|
||||
|
||||
* used
|
||||
|
||||
4.5. Quota/queryChanges
|
||||
|
||||
This is a standard "/queryChanges" method as described in [RFC8620],
|
||||
Section 5.6.
|
||||
|
||||
5. Examples
|
||||
|
||||
5.1. Fetching Quotas
|
||||
|
||||
Request fetching all quotas related to an account:
|
||||
|
||||
[[ "Quota/get", {
|
||||
"accountId": "u33084183",
|
||||
"ids": null
|
||||
}, "0" ]]
|
||||
|
||||
With response:
|
||||
|
||||
[[ "Quota/get", {
|
||||
"accountId": "u33084183",
|
||||
"state": "78540",
|
||||
"list": [{
|
||||
"id": "2a06df0d-9865-4e74-a92f-74dcc814270e",
|
||||
"resourceType": "count",
|
||||
"used": 1056,
|
||||
"warnLimit": 1600,
|
||||
"softLimit": 1800,
|
||||
"hardLimit": 2000,
|
||||
"scope": "account",
|
||||
"name": "bob@example.com",
|
||||
"description": "Personal account usage. When the soft limit is
|
||||
reached, the user is not allowed to send mails or
|
||||
create contacts and calendar events anymore.",
|
||||
"types" : [ "Mail", "Calendar", "Contact" ]
|
||||
}, {
|
||||
"id": "3b06df0e-3761-4s74-a92f-74dcc963501x",
|
||||
"resourceType": "octets",
|
||||
...
|
||||
}, ...],
|
||||
"notFound": []
|
||||
}, "0" ]]
|
||||
|
||||
5.2. Requesting Latest Quota Changes
|
||||
|
||||
Request fetching the changes for a specific quota:
|
||||
|
||||
[[ "Quota/changes", {
|
||||
"accountId": "u33084183",
|
||||
"sinceState": "78540",
|
||||
"maxChanges": 20
|
||||
}, "0" ],
|
||||
[ "Quota/get", {
|
||||
"accountId": "u33084183",
|
||||
"#ids": {
|
||||
"resultOf": "0",
|
||||
"name": "Quota/changes",
|
||||
"path": "/updated"
|
||||
},
|
||||
"#properties": {
|
||||
"resultOf": "0",
|
||||
"name": "Quota/changes",
|
||||
"path": "/updatedProperties"
|
||||
}
|
||||
}, "1" ]]
|
||||
|
||||
With response:
|
||||
|
||||
[[ "Quota/changes", {
|
||||
"accountId": "u33084183",
|
||||
"oldState": "78540",
|
||||
"newState": "78542",
|
||||
"hasMoreChanges": false,
|
||||
"updatedProperties": ["used"],
|
||||
"created": [],
|
||||
"updated": ["2a06df0d-9865-4e74-a92f-74dcc814270e"],
|
||||
"destroyed": []
|
||||
}, "0" ],
|
||||
[ "Quota/get", {
|
||||
"accountId": "u33084183",
|
||||
"state": "10826",
|
||||
"list": [{
|
||||
"id": "2a06df0d-9865-4e74-a92f-74dcc814270e",
|
||||
"used": 1246
|
||||
}],
|
||||
"notFound": []
|
||||
}, "1" ]]
|
||||
|
||||
6. Push
|
||||
|
||||
Servers MUST support the JMAP push mechanisms, as specified in
|
||||
[RFC8620], Section 7, to allow clients to receive notifications when
|
||||
the state changes for the Quota type defined in this specification.
|
||||
|
||||
7. IANA Considerations
|
||||
|
||||
7.1. JMAP Capability Registration for "quota"
|
||||
|
||||
IANA has registered the "quota" JMAP Capability as follows:
|
||||
|
||||
Capability Name: urn:ietf:params:jmap:quota
|
||||
|
||||
Reference: RFC 9425
|
||||
|
||||
Intended Use: common
|
||||
|
||||
Change Controller: IETF
|
||||
|
||||
Security and Privacy Considerations: RFC 9425, Section 8
|
||||
|
||||
7.2. JMAP Data Type Registration for "Quota"
|
||||
|
||||
IANA has registered the "Quota" Data Type as follows:
|
||||
|
||||
Type Name: Quota
|
||||
|
||||
Can Reference Blobs: No
|
||||
|
||||
Can Use for State Change: Yes
|
||||
|
||||
Capability: urn:ietf:params:jmap:quota
|
||||
|
||||
Reference: RFC 9425
|
||||
|
||||
8. Security Considerations
|
||||
|
||||
All security considerations of JMAP [RFC8620] apply to this
|
||||
specification.
|
||||
|
||||
Implementors should be careful to make sure the implementation of the
|
||||
extension specified in this document does not violate the site's
|
||||
security policy. The resource usage of other users is likely to be
|
||||
considered confidential information and should not be divulged to
|
||||
unauthorized persons.
|
||||
|
||||
As for any resource shared across users (for example, a quota with
|
||||
the "domain" or "global" scope), a user that can consume the resource
|
||||
can affect the resources available to the other users. For example,
|
||||
a user could spam themselves with events and make the shared resource
|
||||
hit the limit and unusable for others (implementors could mitigate
|
||||
that with some rate-limiting implementation on the server).
|
||||
|
||||
Also, revealing domain and global quota counts to all users may cause
|
||||
privacy leakage of other sensitive data, or at least the existence of
|
||||
other sensitive data. For example, some users are part of a private
|
||||
list belonging to the server, so they shouldn't know how many users
|
||||
are in there. However, by comparing the quota count before and after
|
||||
sending a message to the list, it could reveal the number of people
|
||||
of the list, as the domain or global quota count would go up by the
|
||||
number of people subscribed. In order to limit those attacks, quotas
|
||||
with "domain" or "global" scope SHOULD only be visible to server
|
||||
administrators and not to general users.
|
||||
|
||||
9. Normative References
|
||||
|
||||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
|
||||
Requirement Levels", BCP 14, RFC 2119,
|
||||
DOI 10.17487/RFC2119, March 1997,
|
||||
<https://www.rfc-editor.org/info/rfc2119>.
|
||||
|
||||
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
|
||||
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
|
||||
2003, <https://www.rfc-editor.org/info/rfc3629>.
|
||||
|
||||
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
|
||||
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
|
||||
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
|
||||
|
||||
[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
|
||||
Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
|
||||
2019, <https://www.rfc-editor.org/info/rfc8620>.
|
||||
|
||||
[RFC9007] Ouazana, R., Ed., "Handling Message Disposition
|
||||
Notification with the JSON Meta Application Protocol
|
||||
(JMAP)", RFC 9007, DOI 10.17487/RFC9007, March 2021,
|
||||
<https://www.rfc-editor.org/info/rfc9007>.
|
||||
|
||||
[RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
|
||||
Ed., "HTTP Semantics", STD 97, RFC 9110,
|
||||
DOI 10.17487/RFC9110, June 2022,
|
||||
<https://www.rfc-editor.org/info/rfc9110>.
|
||||
|
||||
Acknowledgements
|
||||
|
||||
Thank you to Michael Bailly, who co-wrote the first draft version of
|
||||
this document, before deciding to turn to other matters.
|
||||
|
||||
Thank you to Benoit Tellier for his constant help and support on
|
||||
writing this document.
|
||||
|
||||
Thank you to Raphael Ouazana for sharing his own experience on how to
|
||||
write an RFC after finalizing his own document: [RFC9007].
|
||||
|
||||
Thank you to Bron Gondwana, Neil Jenkins, Alexey Melnikov, Joris
|
||||
Baum, and the people from the IETF JMAP working group in general, who
|
||||
helped with extensive discussions, reviews, and feedback.
|
||||
|
||||
Thank you to the people in the IETF organization, who took the time
|
||||
to read, understand, comment, and give great feedback in the last
|
||||
rounds.
|
||||
|
||||
Author's Address
|
||||
|
||||
René Cordier (editor)
|
||||
Linagora Vietnam
|
||||
5 Dien Bien Phu
|
||||
Hanoi
|
||||
10000
|
||||
Vietnam
|
||||
Email: rcordier@linagora.com
|
||||
URI: https://linagora.vn
|
||||
Binary file not shown.
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user