apple-icloud-mcp 0.0.0 → 0.1.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Unofficial Apple Music, iCloud Calendar/Contacts/Mail, Apple Maps and WeatherKit tools for Claude Code",
-    "version": "0.0.0"
+    "version": "0.1.0"
   },
   "plugins": [
     {
@@ -14,7 +14,7 @@
       "displayName": "Apple iCloud",
       "source": "./",
       "description": "Apple Music playlists and library, iCloud Calendar, Contacts and Mail, Apple Maps, WeatherKit and iTunes search for Claude via MCP — runs anywhere, no Mac required. Unofficial; not affiliated with Apple.",
-      "version": "0.0.0",
+      "version": "0.1.0",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "apple-icloud",
   "displayName": "Apple iCloud",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Apple Music playlists and library, iCloud Calendar, Contacts and Mail, Apple Maps, WeatherKit and iTunes search for Claude via MCP — runs anywhere, no Mac required. Unofficial; not affiliated with Apple.",
   "author": {
     "name": "Chris Chall"

package/THIRD_PARTY_NOTICES.md

@@ -23,8 +23,8 @@ MPL-2.0 is a file-level license: it covers ical.js's own files and does not exte
 | Package | Version | License | Source |
 |---|---|---|---|
 | @chrischall/mcp-utils | 2.7.0 | MIT | https://github.com/chrischall/mcp-utils |
-| @fetchproxy/protocol | 3.2.0 | MIT | https://github.com/chrischall/fetchproxy |
-| @fetchproxy/server | 3.2.0 | MIT | https://github.com/chrischall/fetchproxy |
+| @fetchproxy/protocol | 3.2.0 | MIT | — |
+| @fetchproxy/server | 3.2.0 | MIT | — |
 | @modelcontextprotocol/core | 2.1.0 | MIT | https://github.com/modelcontextprotocol/typescript-sdk |
 | @modelcontextprotocol/server | 2.1.0 | MIT | https://github.com/modelcontextprotocol/typescript-sdk |
 | @pinojs/redact | 0.4.0 | MIT | https://github.com/pinojs/redact |
@@ -58,7 +58,7 @@ MPL-2.0 is a file-level license: it covers ical.js's own files and does not exte
 | split2 | 4.2.0 | ISC | https://github.com/mcollina/split2 |
 | thread-stream | 4.2.0 | MIT | https://github.com/mcollina/thread-stream |
 | timezones-ical-library | 2.3.2 | Apache-2.0 | https://github.com/add2cal/timezones-ical-library |
-| ws | 8.21.3 | MIT | https://github.com/websockets/ws |
+| ws | 8.21.3 | MIT | — |
 | zod | 4.6.5 | MIT | https://github.com/colinhacks/zod |
 
 ## License and notice texts
@@ -97,64 +97,14 @@ SOFTWARE.
 ### @fetchproxy/protocol@3.2.0
 
 - License: MIT
-- Source: https://github.com/chrischall/fetchproxy
 
-`LICENSE`:
-
-```text
-MIT License
-
-Copyright (c) 2026 Chris Hall
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
+_An optional dependency that was not installed where this file was generated; see its package on npm._
 
 ### @fetchproxy/server@3.2.0
 
 - License: MIT
-- Source: https://github.com/chrischall/fetchproxy
-
-`LICENSE`:
 
-```text
-MIT License
-
-Copyright (c) 2026 Chris Hall
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
+_An optional dependency that was not installed where this file was generated; see its package on npm._
 
 ### @modelcontextprotocol/core@2.1.0
 
@@ -2217,32 +2167,8 @@ SOFTWARE.
 ### ws@8.21.3
 
 - License: MIT
-- Source: https://github.com/websockets/ws
-
-`LICENSE`:
-
-```text
-Copyright (c) 2011 Einar Otto Stangvik <einaros@gmail.com>
-Copyright (c) 2013 Arnout Kazemier and contributors
-Copyright (c) 2016 Luigi Pinca and contributors
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-```
+_An optional dependency that was not installed where this file was generated; see its package on npm._
 
 ### zod@4.6.5
 

package/dist/apple-keys.js

@@ -0,0 +1,214 @@
+import { createPrivateKey } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { expandPath, readEnvVar, signEs256Jwt } from '@chrischall/mcp-utils';
+import { ConfigError, rememberSecret } from './errors.js';
+const PREFIX = {
+    music: 'APPLE_MUSIC',
+    maps: 'APPLE_MAPS',
+    weather: 'APPLE_WEATHERKIT',
+};
+/**
+ * Accept the shapes a .p8 actually arrives in through an env block:
+ *  - the PEM verbatim (multi-line);
+ *  - the PEM with literal `\n` escapes (a one-line secret field);
+ *  - the whole PEM base64-encoded;
+ *  - just the base64 body between the BEGIN/END lines;
+ *  - the PEM with its line breaks turned into spaces, or dropped entirely —
+ *    what a single-line form field does to a pasted multi-line value, and a
+ *    shape OpenSSL refuses to parse.
+ * Every PEM is re-armored canonically (64-column body, LF endings).
+ * Returns a normalized PEM, or undefined when the value is none of those.
+ */
+export function normalizePrivateKey(raw) {
+    let value = raw.trim().replace(/\\r/g, '').replace(/\\n/g, '\n');
+    if (!value.includes('-----BEGIN')) {
+        const compact = value.replace(/\s+/g, '');
+        if (!/^[A-Za-z0-9+/=]+$/.test(compact))
+            return undefined;
+        const decoded = Buffer.from(compact, 'base64').toString('utf8');
+        if (!decoded.includes('-----BEGIN'))
+            return armor('PRIVATE KEY', compact);
+        value = decoded;
+    }
+    const pem = PEM_BLOCK_RE.exec(value);
+    // An unrecognisable armor is passed through for `validateEcKey` to reject by name.
+    if (!pem)
+        return value.trim().replace(/\r\n/g, '\n') + '\n';
+    return armor(pem[1], pem[2].replace(/\s+/g, ''));
+}
+/** `-----BEGIN <label>-----<body>-----END <label>-----`, whatever whitespace separates the parts. */
+const PEM_BLOCK_RE = /-----BEGIN ([A-Z0-9 ]+)-----([\s\S]*?)-----END \1-----/;
+function armor(label, body) {
+    const lines = body.match(/.{1,64}/g) ?? [];
+    return [`-----BEGIN ${label}-----`, ...lines, `-----END ${label}-----`].join('\n') + '\n';
+}
+/** Validate that `pem` is an EC P-256 private key; returns an error string or undefined. */
+export function validateEcKey(pem) {
+    try {
+        const key = createPrivateKey(pem);
+        if (key.asymmetricKeyType !== 'ec')
+            return `it is a ${key.asymmetricKeyType ?? 'non-EC'} key, not an EC (ES256) key`;
+        const curve = key.asymmetricKeyDetails?.namedCurve;
+        // No name means explicit curve parameters OpenSSL could not match to a
+        // named curve — so not P-256. Accepting it would mint tokens Apple rejects.
+        if (curve !== 'prime256v1')
+            return `it uses ${curve ? `curve ${curve}` : 'an unnamed curve'}, not P-256`;
+        return undefined;
+    }
+    catch {
+        return 'it could not be parsed as a private key';
+    }
+}
+function readKeyFile(path, varName, service) {
+    try {
+        return readFileSync(expandPath(path), 'utf8');
+    }
+    catch {
+        throw new ConfigError(service, `Could not read the private key file named by ${varName}.`, [varName], `Check that ${varName} points at a readable .p8 file.`);
+    }
+}
+/**
+ * Resolve the developer key for `service`, or throw a `ConfigError` naming
+ * exactly which variables are missing.
+ */
+export function resolveDeveloperKey(service, env = process.env) {
+    const svcName = service;
+    const prefix = PREFIX[service];
+    const teamId = readEnvVar('APPLE_TEAM_ID', { env });
+    const ownKeyId = readEnvVar(`${prefix}_KEY_ID`, { env });
+    const ownKey = readEnvVar(`${prefix}_PRIVATE_KEY`, { env });
+    const keyId = ownKeyId ?? readEnvVar('APPLE_KEY_ID', { env });
+    let rawKey;
+    let keyVar;
+    if (ownKey !== undefined) {
+        rawKey = ownKey;
+        keyVar = `${prefix}_PRIVATE_KEY`;
+    }
+    else if (readEnvVar('APPLE_PRIVATE_KEY', { env }) !== undefined) {
+        rawKey = readEnvVar('APPLE_PRIVATE_KEY', { env });
+        keyVar = 'APPLE_PRIVATE_KEY';
+    }
+    else {
+        const path = readEnvVar('APPLE_PRIVATE_KEY_PATH', { env });
+        keyVar = 'APPLE_PRIVATE_KEY_PATH';
+        if (path !== undefined)
+            rawKey = readKeyFile(path, keyVar, svcName);
+    }
+    const missing = [];
+    if (!teamId)
+        missing.push('APPLE_TEAM_ID');
+    if (!keyId)
+        missing.push(`APPLE_KEY_ID (or ${prefix}_KEY_ID)`);
+    if (rawKey === undefined)
+        missing.push(`APPLE_PRIVATE_KEY (or ${prefix}_PRIVATE_KEY / APPLE_PRIVATE_KEY_PATH)`);
+    if (missing.length === 0)
+        assertPairMatches(service, env);
+    if (missing.length > 0) {
+        throw new ConfigError(svcName, `${serviceLabel(service)} needs an Apple Developer key, and ${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} not set.`, missing, `Create a key in the Apple Developer portal (Certificates, Identifiers & Profiles → Keys) with ${capabilityLabel(service)} enabled, then set APPLE_TEAM_ID, APPLE_KEY_ID and APPLE_PRIVATE_KEY (the .p8 contents).`);
+    }
+    const pem = normalizePrivateKey(rawKey);
+    const problem = pem === undefined ? 'it is not a PEM or base64 key' : validateEcKey(pem);
+    if (pem === undefined || problem !== undefined) {
+        throw new ConfigError(svcName, `The private key in ${keyVar} is unusable: ${problem}.`, [keyVar], `Paste the whole .p8 file (including the BEGIN/END PRIVATE KEY lines) into ${keyVar}; one-line values with \\n escapes and base64 are accepted too.`);
+    }
+    rememberSecret(rawKey);
+    return {
+        teamId: teamId,
+        keyId: keyId,
+        privateKeyPem: pem,
+        source: `${ownKeyId ? `${prefix}_KEY_ID` : 'APPLE_KEY_ID'} + ${keyVar}`,
+    };
+}
+/**
+ * A key id names exactly one private key, so the service-specific pair and
+ * the shared pair must not be crossed. When BOTH a shared key id and a shared
+ * private key are set, the shared id provably belongs to the shared key — so
+ * pairing it with `<SVC>_PRIVATE_KEY`, or pairing `<SVC>_KEY_ID` with the
+ * shared key, mints tokens Apple rejects with a bare 401 that names neither
+ * variable. Refuse that up front, by name. With only half of the shared pair
+ * set, crossing is the ordinary single-key setup (e.g. APPLE_MUSIC_KEY_ID +
+ * APPLE_PRIVATE_KEY for one Music key) and is allowed.
+ */
+function assertPairMatches(service, env) {
+    const prefix = PREFIX[service];
+    const ownKeyId = readEnvVar(`${prefix}_KEY_ID`, { env });
+    const ownKey = readEnvVar(`${prefix}_PRIVATE_KEY`, { env });
+    const sharedKeyId = readEnvVar('APPLE_KEY_ID', { env });
+    const sharedKeyVar = readEnvVar('APPLE_PRIVATE_KEY', { env }) !== undefined
+        ? 'APPLE_PRIVATE_KEY'
+        : readEnvVar('APPLE_PRIVATE_KEY_PATH', { env }) !== undefined
+            ? 'APPLE_PRIVATE_KEY_PATH'
+            : undefined;
+    if (sharedKeyId === undefined || sharedKeyVar === undefined)
+        return;
+    if (ownKey !== undefined && ownKeyId === undefined) {
+        throw new ConfigError(service, `${prefix}_PRIVATE_KEY is set but ${prefix}_KEY_ID is not, and APPLE_KEY_ID belongs to the shared key in ${sharedKeyVar} — ` +
+            'a key id must name the key that signs the token.', [`${prefix}_KEY_ID`], `Set ${prefix}_KEY_ID to the Key ID of the key in ${prefix}_PRIVATE_KEY (Apple Developer portal → Keys), or unset ${prefix}_PRIVATE_KEY to use the shared key.`);
+    }
+    if (ownKeyId !== undefined && ownKey === undefined && ownKeyId !== sharedKeyId) {
+        throw new ConfigError(service, `${prefix}_KEY_ID is set but ${prefix}_PRIVATE_KEY is not, and the shared key in ${sharedKeyVar} belongs to APPLE_KEY_ID — ` +
+            'a key id must name the key that signs the token.', [`${prefix}_PRIVATE_KEY`], `Set ${prefix}_PRIVATE_KEY to the .p8 contents of key ${prefix}_KEY_ID, or unset ${prefix}_KEY_ID to use the shared key.`);
+    }
+}
+function serviceLabel(service) {
+    return service === 'music' ? 'Apple Music' : service === 'maps' ? 'Apple Maps' : 'WeatherKit';
+}
+function capabilityLabel(service) {
+    return service === 'music' ? 'Media Services (MusicKit)' : service === 'maps' ? 'MapKit JS' : 'WeatherKit';
+}
+/** Seconds since the epoch. */
+function nowSeconds(now) {
+    return Math.floor(now / 1000);
+}
+/**
+ * An Apple Music developer token. Apple allows up to ~6 months; we mint for
+ * 12 hours and re-mint, so a revoked key stops working within a day and a
+ * leaked token is short-lived.
+ */
+export const MUSIC_TOKEN_TTL_S = 12 * 60 * 60;
+export function mintMusicDeveloperToken(key, now = Date.now()) {
+    const iat = nowSeconds(now);
+    const exp = iat + MUSIC_TOKEN_TTL_S;
+    return { token: signEs256Jwt(key.privateKeyPem, { iss: key.teamId, iat, exp }, { header: { kid: key.keyId } }), expiresAt: exp * 1000 };
+}
+/**
+ * The Maps Server API auth token (exchanged at GET /v1/token for a 30-minute
+ * access token). `scope: server_api` is what makes it a server token.
+ */
+export const MAPS_AUTH_TOKEN_TTL_S = 60 * 60;
+export function mintMapsAuthToken(key, now = Date.now()) {
+    const iat = nowSeconds(now);
+    const exp = iat + MAPS_AUTH_TOKEN_TTL_S;
+    return {
+        token: signEs256Jwt(key.privateKeyPem, { iss: key.teamId, iat, exp, scope: 'server_api' }, { header: { kid: key.keyId } }),
+        expiresAt: exp * 1000,
+    };
+}
+/**
+ * A WeatherKit REST token. The non-standard `id` header (`<team>.<service>`)
+ * and the `sub` claim (the Services ID) are both required; a missing `id` is
+ * the classic cause of `NOT_ENABLED`.
+ */
+export const WEATHERKIT_TOKEN_TTL_S = 60 * 60;
+export function mintWeatherKitToken(key, serviceId, now = Date.now()) {
+    const iat = nowSeconds(now);
+    const exp = iat + WEATHERKIT_TOKEN_TTL_S;
+    return {
+        token: signEs256Jwt(key.privateKeyPem, { iss: key.teamId, iat, exp, sub: serviceId }, { header: { kid: key.keyId, id: `${key.teamId}.${serviceId}` } }),
+        expiresAt: exp * 1000,
+    };
+}
+/** Decode a JWT's payload without verifying it (for expiry and issuer checks on tokens we did not mint). */
+export function decodeJwtPayload(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return undefined;
+    try {
+        const json = Buffer.from(parts[1], 'base64url').toString('utf8');
+        const payload = JSON.parse(json);
+        return payload && typeof payload === 'object' && !Array.isArray(payload) ? payload : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}