src-advisory/SRCmail
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add RFC specifications (txt + pdf) organized by category (core, mail, contacts, calendar, sieve, quotas, auth)

Browse Source
This commit is contained in:
Linus Rath
2026-03-13 02:51:07 +01:00
parent 5a679275ca
commit 1267efa307
31 changed files with 57249 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
-1
View File
@@ -23,7 +23,6 @@
# misc # misc
.DS_Store .DS_Store
*.pem *.pem
/specifications/
# debug # debug
npm-debug.log* npm-debug.log*
specifications/addon-plugin-theme-concept.md
+937
View File
@@ -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.
specifications/auth/rfc6570.pdf
BIN
View File
Binary file not shown.
specifications/auth/rfc6570.txt
+1907
View File
File diff suppressed because it is too large Load Diff
specifications/auth/rfc7636.pdf
BIN
View File
Binary file not shown.
specifications/auth/rfc7636.txt
+1123
View File
File diff suppressed because it is too large Load Diff
specifications/calendar/rfc8984.pdf
BIN
View File
Binary file not shown.
specifications/calendar/rfc8984.txt
+3987
View File
File diff suppressed because it is too large Load Diff
specifications/calendar/rfc9670.pdf
BIN
View File
Binary file not shown.
specifications/calendar/rfc9670.txt
+857
View File
@@ -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
specifications/contacts/rfc6350.pdf
BIN
View File
Binary file not shown.
specifications/contacts/rfc6350.txt
+4147
View File
File diff suppressed because it is too large Load Diff
specifications/contacts/rfc9553.pdf
+17115
View File
File diff suppressed because one or more lines are too long
specifications/contacts/rfc9553.txt
+4043
View File
File diff suppressed because it is too large Load Diff
specifications/contacts/rfc9610.pdf
BIN
View File
Binary file not shown.
specifications/contacts/rfc9610.txt
+844
View File
@@ -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
specifications/core/rfc8620.pdf
BIN
View File
Binary file not shown.
specifications/core/rfc8620.txt
+5043
View File
File diff suppressed because it is too large Load Diff
specifications/mail/rfc2369.pdf
BIN
View File
Binary file not shown.
specifications/mail/rfc2369.txt
+843
View File
@@ -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]
specifications/mail/rfc5322.pdf
BIN
View File
Binary file not shown.
specifications/mail/rfc5322.txt
+3195
View File
File diff suppressed because it is too large Load Diff
specifications/mail/rfc8621.pdf
BIN
View File
Binary file not shown.
specifications/mail/rfc8621.txt
+6051
View File
File diff suppressed because it is too large Load Diff
specifications/mail/rfc9007.pdf
BIN
View File
Binary file not shown.
specifications/mail/rfc9007.txt
+614
View File
@@ -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
specifications/quotas/rfc9425.pdf
+2388
View File
File diff suppressed because one or more lines are too long
specifications/quotas/rfc9425.txt
+518
View File
@@ -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
specifications/sieve/rfc9661.pdf
BIN
View File
Binary file not shown.
specifications/sieve/rfc9661.txt
+1015
View File
File diff suppressed because it is too large Load Diff
specifications/stalwart_openapi.yml
+2622
View File
File diff suppressed because it is too large Load Diff