Skip to content

CLI for SidePulse

Python

Preserve shared push keys when pairing and saving phone links

Peter Kuhar330ccbb20eb0
diff --git a/README.md b/README.md
index 9eacebb..76adadf 100644
--- a/README.md
+++ b/README.md
@@ -227,7 +227,30 @@ sector and updates its directory size, preserving its FAT allocation.
Run one command and either scan the terminal QR code with the SidePulse iOS app
or paste the push token shown by the app. Production tokens have 64 hexadecimal
characters; development tokens have the `dev_` prefix followed by 64 hexadecimal
-characters. Keep the prefix when pasting or saving a development token.
+characters. The app appends `_<shared-key>` to identify this sender; keep that
+suffix and its exact letter case when pasting or saving the token. Keep the
+`dev_` prefix on development tokens. Removing the key in the iOS app stops this
+sender's pushes from being processed; pair again to receive a new key.
+
+Pairing issues the key in the iOS app. Saving a new token for the same device
+and APNs environment replaces its previous saved link. The CLI preserves the
+key's case and sends the entire token in the bridge URL; the updated bridge
+strips the suffix for Apple and adds it as top-level `shared_key` in both the
+push and recovery payloads. A request body cannot override that key.
+
+The app accepts only locally active keys. Missing, unknown, or removed keys
+produce no LED write, inbox entry, sender activity, or link-state change. Their
+notifications are suppressed in the foreground and dismissed when the app or
+**Update from Server** handles them. The update action finishes quietly when
+there is nothing authorized to update; with no active keys it skips fetching.
+Background alerts can appear before iOS lets the app run cleanup.
+
+Settings → **Active Push Keys** shows only the last four key characters, last
+accepted activity, and lifetime received count. The app deduplicates the latest
+256 event/message IDs per sender across push and recovery. Removing a key
+revokes it on the phone; removing a saved CLI link alone does not revoke the
+phone's key. Use matching updated versions of the bridge, iOS app, and CLI;
+older unkeyed senders must obtain a new token.
```sh
sidepulse link
diff --git a/src/sidepulse/links.py b/src/sidepulse/links.py
index 394af52..fe2c6a9 100644
--- a/src/sidepulse/links.py
+++ b/src/sidepulse/links.py
@@ -23,7 +23,7 @@ from .settings import default_config_dir
DEFAULT_BRIDGE_SERVER = "https://bridge.sidepulse.io"
PAIRING_TIMEOUT_SECONDS = 5 * 60
IOS_BUNDLE_ID = "io.sidepulse.ios"
-APNS_TOKEN_PATTERN = re.compile(r"(?:dev_)?[0-9a-f]{64}")
+APNS_TOKEN_PATTERN = re.compile(r"(?:dev_)?[0-9a-f]{64}(?:_[A-Za-z0-9_-]{1,128})?")
PAIRING_CHANNEL_PATTERN = re.compile(r"^[A-Za-z0-9_-]{11}$")
@@ -73,10 +73,16 @@ def normalize_server(value: str) -> str:
def normalize_apns_token(value: str) -> str:
- token = "".join(value.split()).lower()
+ text = value.strip()
+ prefix = "dev_" if text[:4].lower() == "dev_" else ""
+ raw = text[4:] if prefix else text
+ device, separator, key = raw.partition("_")
+ # Device-token hex is case-insensitive; shared keys are case-sensitive.
+ token = prefix + "".join(device.split()).lower() + (separator + key if separator else "")
if not APNS_TOKEN_PATTERN.fullmatch(token):
raise LinkError(
- "Push token must be 64 hexadecimal characters, optionally prefixed with 'dev_'."
+ "Push token must be 64 hexadecimal characters, optionally prefixed with 'dev_' "
+ "and suffixed with '_<shared-key>' (1–128 letters, digits, underscores, or hyphens)."
)
return token
@@ -136,7 +142,9 @@ def store_ios_link(link: IOSLink, path: Path | None = None) -> tuple[IOSLink, ..
updated: list[IOSLink] = []
replaced = False
for existing in current:
- if existing.token == link.token:
+ existing_device = existing.token[:68] if existing.token.startswith("dev_") else existing.token[:64]
+ new_device = link.token[:68] if link.token.startswith("dev_") else link.token[:64]
+ if existing_device == new_device:
updated.append(link)
replaced = True
else:
diff --git a/tests/test_links.py b/tests/test_links.py
index 87c3eec..7deca5d 100644
--- a/tests/test_links.py
+++ b/tests/test_links.py
@@ -58,6 +58,34 @@ class LinkStorageTests(unittest.TestCase):
with self.assertRaises(LinkError):
normalize_apns_token(invalid)
+ def test_shared_key_case_is_preserved_through_pairing_and_storage(self) -> None:
+ for prefix in ("", "dev_"):
+ token = prefix + TOKEN_A + "_CaseSensitive_key-1234"
+ self.assertEqual(normalize_apns_token(prefix.upper() + TOKEN_A.upper() + "_CaseSensitive_key-1234"), token)
+ response = json.dumps({"v": 1, "type": "ios_registration", "device": {
+ "name": "iPhone", "bundle_id": "io.sidepulse.ios", "push_token": token,
+ }})
+ link = parse_ios_registration(response, server="https://bridge.sidepulse.io")
+ self.assertEqual(link.token, token)
+ with tempfile.TemporaryDirectory() as temporary:
+ path = Path(temporary) / "links.json"
+ save_ios_links((link,), path)
+ self.assertEqual(load_ios_links(path), (link,))
+
+ def test_pairing_with_a_new_key_replaces_the_same_device_link(self) -> None:
+ with tempfile.TemporaryDirectory() as temporary:
+ path = Path(temporary) / "links.json"
+ store_ios_link(IOSLink("iPhone", TOKEN_A), path)
+ store_ios_link(IOSLink("iPhone", TOKEN_A + "_old-key"), path)
+ latest = IOSLink("iPhone", TOKEN_A + "_new-key")
+ self.assertEqual(store_ios_link(latest, path), (latest,))
+ self.assertEqual(load_ios_links(path), (latest,))
+
+ def test_malformed_shared_key_suffix_is_rejected(self) -> None:
+ for suffix in ("", "a" * 129, "bad/key", "bad.key", "bad key", "é"):
+ with self.subTest(suffix=suffix), self.assertRaises(LinkError):
+ normalize_apns_token(TOKEN_A + "_" + suffix)
+
def test_development_registration_response_keeps_prefix(self) -> None:
response = json.dumps(
{
@@ -521,6 +549,8 @@ class IOSPayloadTests(unittest.TestCase):
for token, expected_url in (
(TOKEN_A, f"https://bridge.sidepulse.io/api/leds/apns_{TOKEN_A}"),
(DEV_TOKEN_A, f"https://bridge.sidepulse.io/api/leds/apns_dev_{TOKEN_A}"),
+ (TOKEN_A + "_CaseSensitive_key", f"https://bridge.sidepulse.io/api/leds/apns_{TOKEN_A}_CaseSensitive_key"),
+ (DEV_TOKEN_A + "_CaseSensitive_key", f"https://bridge.sidepulse.io/api/leds/apns_dev_{TOKEN_A}_CaseSensitive_key"),
):
with self.subTest(token_prefix=token[:4]), patch(
"sidepulse.links.urllib.request.urlopen", return_value=response