apple-icloud-mcp 0.0.0 → 0.2.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.2.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.2.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.2.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/README.md

@@ -12,8 +12,9 @@ It talks to Apple over the network through Apple's own web APIs and standard pro
 IMAP/SMTP), so — unlike Mac-only Apple integrations such as
 [apple-swift-mcp](https://github.com/chrischall/apple-swift-mcp) — it runs anywhere: Linux, Windows, a
 container, or hosted on [mcp-host](#running-on-mcp-host) as a claude.ai connector. The two complement each other:
-`apple-swift-mcp` drives the Mac's own apps (Calendar, Reminders, Contacts, Mail, Messages, Notes, Photos, Maps),
-while `apple-icloud-mcp` reaches Apple's web services from anywhere and adds Apple Music, WeatherKit and iTunes.
+`apple-swift-mcp` drives the Mac's own apps (Calendar, Reminders, Contacts, Mail, Messages, Notes, Photos, Maps,
+and Music.app playlists), while `apple-icloud-mcp` reaches Apple's web services from anywhere and adds the Apple
+Music catalog, WeatherKit and iTunes.
 
 > [!NOTE]
 > **Unofficial.** This project is not affiliated with, endorsed by or sponsored by Apple Inc. Apple, iCloud,
@@ -210,6 +211,12 @@ works with **no** Apple Developer account. It is unsupported by Apple and may st
 tools that need it say so in their descriptions, and their answers report which backend (`official` or `web`)
 served them.
 
+> [!TIP]
+> **On a Mac, you may not need web-player mode at all.** [apple-swift-mcp](https://github.com/chrischall/apple-swift-mcp)
+> makes the same playlist edits — rename, delete, remove, reorder, sort, dedupe, move into folders — in the local
+> Music.app library through Music's own scripting, with no tokens or developer account. It works on songs already in
+> your library, so a catalog song still needs adding first (`apple_music_add_to_library` here).
+
 ## Running on mcp-host
 
 The package ships a [`mint.yaml`](mint.yaml) that mcp-host reads when you register `apple-icloud-mcp`:
@@ -259,7 +266,7 @@ recorded on disk, so a shared secret does not let one be replayed.
 | `apple_music_get_recommendations` | Your personal Apple Music recommendations ("Made for You", "Recently Played" and similar groups), each with its title and the albums, playlists or stations in it (catalog ids). | read |  |
 | `apple_music_get_replay` | Apple Music Replay: your top songs, albums and artists for the latest Replay year, or for a given year (with play counts where Apple provides them). | read |  |
 | `apple_music_get_ratings` | Whether you have loved or disliked songs, albums, playlists, music videos or stations — catalog or library ids — returning love, dislike or none per id. | read |  |
-| `apple_music_create_playlist` | Create a new playlist in your Apple Music library, optionally with tracks (up to 500 catalog or library song ids; added 100 at a time), a description, a folder and public visibility. | additive |  |
+| `apple_music_create_playlist` | Create a new playlist in your Apple Music library, optionally with tracks (up to 500 catalog or library song ids; added 100 at a time), a description, a folder and public visibility (not in APPLE_WRITE_MODE=additive). | additive |  |
 | `apple_music_add_playlist_tracks` | Append songs (up to 500 catalog or library ids) to the end of one of your library playlists. | additive |  |
 | `apple_music_create_folder` | Create a playlist folder in your Apple Music library, at the top level or inside another folder. | additive |  |
 | `apple_music_add_to_library` | Add catalog songs, albums, playlists or music videos to your Apple Music library by catalog id (up to 100 per type). | additive |  |
@@ -341,7 +348,7 @@ recorded on disk, so a shared secret does not let one be replayed.
 | Value | What is registered |
 |---|---|
 | `none` | Read tools only. |
-| `additive` | Reads, plus writes that only **add** to your own account: create a playlist or folder, append tracks, add to library/favorites, create an event (without attendees, and not in a calendar shared with other people) or a contact. Nothing existing is modified or removed and nothing is sent to anyone. |
+| `additive` | Reads, plus writes that only **add** to your own account: create a (private) playlist or folder, append tracks, add to library/favorites, create an event (without attendees, and not in a calendar shared with other people) or a contact. Nothing existing is modified or removed and nothing is sent to anyone. |
 | `all` (default) | Everything. |
 
 Gated tools are not registered at all below their mode, so no prompt or injected instruction can call them.
@@ -443,12 +450,29 @@ All optional; each service activates when its credentials are present. Values th
 Run **`apple_healthcheck`** first. For each service it reports whether credentials are configured (and which
 variables to set if not), whether Apple accepted them just now, the active write mode and the display time zone.
 
+The same check runs from a terminal, with no MCP client involved — useful before wiring the server into Claude,
+or to tell a credential problem from a client problem. It reads the shell environment only, not the `env` block
+of `.mcp.json`, Claude Desktop's config or the extension's settings, so export the same values first:
+
+```bash
+printf 'App-specific password: '; read -rs ICLOUD_APP_PASSWORD; echo   # not echoed, kept out of shell history
+export ICLOUD_APP_PASSWORD ICLOUD_USERNAME=you@icloud.com
+npx -y apple-icloud-mcp doctor                  # every enabled service
+npx -y apple-icloud-mcp doctor calendar mail    # only these
+npx -y apple-icloud-mcp doctor --json           # the apple_healthcheck report as JSON
+```
+
+It exits 0 when every configured service works (and every service named on the command line is configured,
+enabled and working), 1 otherwise, and 2 for a usage error. It sends each configured service one read-only
+request (the iCloud ones one at a time, so a revoked password is sent once), and prints no secrets. From a
+source checkout, `node dist/index.js doctor` also reads the repo's `.env`.
+
 | Symptom | Likely cause |
 |---|---|
 | iCloud "credentials rejected" | The app-specific password was revoked (Apple ID password changed) or the normal password was used. Generate a new app-specific password. |
 | Apple Music 401 | Developer key problem: wrong Team/Key ID, or the key lacks MusicKit. In web mode: the `media-user-token` cookie expired — copy a fresh one. |
 | Apple Music 403 | The Music User Token expired (≈6 months), was minted with a different key, or the account has no Apple Music subscription. Run `music-auth` again (without the developer key: ask its owner for `music-auth --print-developer-token`). |
-| `PLAYLIST_CHANGED` | Apple has not caught up with the previous playlist change yet (its reads lag writes by seconds), or the playlist was edited elsewhere. Re-read with `apple_music_get_playlist` and retry. |
+| `PLAYLIST_CHANGED` | Apple has not caught up with a recent change this server made to the playlist yet (its reads lag writes by seconds), or the playlist was edited elsewhere. Reorders, track removals, duplicate-checked adds and playlist updates refuse to act on such a read. Re-read with `apple_music_get_playlist` and retry. |
 | Times are off by hours | Set `DISPLAY_TZ` to your IANA zone. |
 | Mail times out on a hosted deployment | Check `imap.mail.me.com` / `smtp.mail.me.com` are in the egress allowlist. |
 

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;
+    }
+}