iCloud Calendar — how to connect
The plugin ships one node type, ICloud/Calendar: a node whose content is the connection to
one iCloud account and whose page is a read-only agenda of its calendars and reminders. Getting
the plugin puts a My iCloud node in your own space; that copy is yours to configure and nobody
else can read it. No Apple Developer Program is needed — this speaks CalDAV, the standard
protocol every Apple device uses.
1. Create an app-specific password
At account.apple.com: Sign-In and Security ▸ App-Specific
Passwords ▸ +. Name it (e.g. meshweaver) and copy the generated xxxx-xxxx-xxxx-xxxx value.
Your Apple ID's own password will not work here — Apple refuses it on CalDAV — and must never be stored on the mesh. The app-specific password is the whole point: it is scoped, separate, and revocable on its own.
2. Configure your node
Open your My iCloud node. Until it is configured, its page IS the connect form:
| Setting | Value | How it is entered |
|---|---|---|
appleId |
the email address your Apple Account signs in with | typed into the form; saved as you leave the field |
appPassword |
the app-specific password from step 1 | 🔑 Enter app-specific password opens a masked dialog; paste it as Apple shows it (spaces are stripped) and press Save |
The Apple ID is bound straight to the node — there is no Save button for it, and nothing you did not touch is ever rewritten. The password is the one field that is not: it is write-only, so it goes through its own dialog, and a blank dialog keeps the stored password rather than wiping it.
Optional (on the node's Edit view):
| Setting | Value |
|---|---|
days |
how many days of agenda to show, 1–31 (default 7) |
3. Read your week
The page discovers your account's calendar home (iCloud parks accounts on numbered
pXX-caldav.icloud.com hosts — the plugin follows the server's own pointers), then shows:
- Agenda — the coming days across every calendar, grouped by day. Timed entries render at your wall clock (your profile's time zone); all-day entries are calendar facts and render as their date in every zone. Cancelled events are struck through, never hidden.
- Reminders — every reminder list, incomplete first, completed struck through.
Refresh re-reads the account; the page never polls on its own.
Security, by design
- Read-only. The plugin only ever issues CalDAV reads (PROPFIND, REPORT) — it cannot create, move or delete anything in your calendars.
- The page never renders the password. The connect form says only whether one is set; the
setup guide and the diagnosis show at most
····plus its last four characters. The password is stored in the node's content, in the clear, protected by your space's access control — anyone who can open the node's generic Edit view can read it, so keep the node in your own space. - Scope honesty: an app-specific password is account-scoped, not calendar-scoped — a person who can read this node's content could also use it for iCloud mail or contacts. That is Apple's granularity, not the plugin's choice, and it is why the node belongs in your own space.
- Revocation is instant: delete the password at account.apple.com ▸ App-Specific Passwords and the mesh's access dies with it. Changing your Apple ID password also revokes every app-specific password.
What the mesh calls
https://caldav.icloud.com (discovery), then whatever hosts the account's own hrefs name —
PROPFIND for principal → calendar home → collections, one REPORT per calendar for the window's
events (VEVENT) and one per reminder list (VTODO). All through the mesh's bounded HTTP pool; a
stalled call degrades to a diagnosis on the page, never a hang.