TokenShift Enterprise — Installation, Distribution, and Update

TL;DR

Signed artifacts (.pkg, .msi, .deb, .rpm, tarball) deployed by the customer’s MDM or downloaded from the PointFive portal.
One-time enrollment manifest — four fields of plain JSON, deployed by MDM.
All ingest data is hybrid-encrypted on the device against PointFive’s public key (pinned in the binary); only PointFive’s KMS holds the matching private key.
Server-side ingest is stateless: HTTPS endpoint → decrypt → persist.
PointFive can control which release version is offered to a given client. PointFive cannot push configuration, rules, or behaviour changes to running clients.

1. What PointFive can and can’t push remotely

PointFive controls release availability — which version is offered, when, to which fraction of clients. PointFive does not control rules, configuration, opt-out, or any per-fleet behaviour at runtime — those are baked into the binary and the enrollment manifest at install time.

No remote policy push. All config is install-time.
No remote rule update. Rules ship in the binary.
No remote opt-out. A user opts out by changing local config; an admin opts out by redeploying the manifest or uninstalling via MDM.
No audit-event stream. “Who changed what” lives in the customer’s MDM audit log.

2. Distribution channels

Platform	Primary channel	MDM integration
macOS	Signed `.pkg` from the PointFive download portal	Jamf, Mosyle, Kandji, JumpCloud
Linux (Debian/Ubuntu)	apt repository (`.deb` packages)	Ansible, Salt, Chef, JumpCloud, SCCM
Linux (RHEL/Fedora/Amazon)	yum repository (`.rpm` packages)	same
Windows	MSI installer	Group Policy, Intune, Configuration Manager
Direct download	GitHub Releases (signed archives + checksums)	Manual or scripted install

Cross-compiled artifacts for linux/darwin/windows × amd64/arm64.

3. Code signing

Platform	Signing
macOS	Apple Developer ID + notarization. Gatekeeper blocks unsigned binaries.
Windows	EV Code Signing certificate. Required for SmartScreen and Intune.
Linux	Repository GPG signing for apt and yum.

Auto-update artifacts carry an additional signature; the client verifies it against a key pinned in the binary before swapping. A signature mismatch aborts the update.

4. Enrollment

The customer admin logs into the PointFive customer portal via SSO, picks install-time configuration (tier cap, project hash mode, recovery cache, sample allowlist, sample rate, retention extensions), and clicks Generate manifest. The portal returns enrollment.json containing four top-level fields:

tenant_id — customer organization.
bearer_token — for ingest auth, rotated by regenerating the manifest.
user_id_hmac_key — a per-tenant random secret used to derive user_id locally from the developer’s email.
config — the install-time configuration above.

The admin deploys it via MDM as root to the system path so it covers every user on the machine. A per-user variant (tokenshift enroll <path> writing under ~/.tokenshift/) is available for self-serve installs.

No signature, no expiration, no user roster, no public key in the manifest, no ingest URL in the manifest. The public key and ingest URL are pinned in the binary at build time, so manifest tampering grants no decryption capability and no exfiltration path — at worst an attacker can DoS telemetry. Bearer-token rotation handles compromise.

CLI surface for self-serve installs: Enrollment.

Agent harness hooks

The tokenshift binary supports three PreToolUse-style protocols: Claude Code, Cursor, and GitHub Copilot CLI. tokenshift init installs and updates the hook entries idempotently; tokenshift uninstall removes them. Prefix any shell command with <tokenshift>: to skip the rewrite for that command. Hooks always exit 0; the IDE is never blocked.

5. Encryption

HTTPS protects in transit only. TokenShift adds per-record hybrid encryption against PointFive’s public key, pinned in the binary at build time. The client never holds anything but the public key, so a compromised laptop or manifest yields no decryption capability. The matching private key lives only in PointFive’s key-management system, with audited access and no plaintext extraction. Key rotation ships a new binary version with both current and next keys pinned. A single PointFive-wide keypair is the default; per-tenant keypairs are available on request for regulated customers.

6. Ingest pipeline

Client                               PointFive ingest
──────                               ────────────────
encrypt(record)  →  HTTPS POST  →   stateless receiver
                                    └─ decrypt
                                    └─ allowlist-check
                                    └─ persist (one signal type → one stream)
                                    └─ 200 OK

No intermediate storage, no broker, no records at rest in the ingest path. Failed persistence returns a non-2xx and the client re-enqueues from its local outbox.

7. Updates

Auto-update is opt-in on the client side: the developer (or the admin’s deploy script) runs tokenshift update, and the binary verifies the artifact’s signature against its pinned key before atomically swapping itself. PointFive never push-applies an update — but PointFive does control which version a given client is offered, ramping rollouts by client bucket and with a kill switch that stops all auto-updates at once.

MDM-managed fleets typically continue to upgrade via MDM at the admin’s pace; auto-update is the path for developer machines that aren’t tightly MDM-managed. The client_state signal reports the running binary version so admins can see staleness.

8. Version skew

Customers will routinely run multiple versions in their fleet. The backend supports the last several minor versions of each signal’s schema; older versions are rejected at ingest and admins see data dry up via stalled client_state rows. Sunset is the customer’s lever, not PointFive’s — PointFive refuses old versions, the admin pushes the upgrade.

9. Threat model

Threat	Mitigation
Malicious tampered binary substituted for the legitimate one	Code signing on every platform; MDM enforces signature verification before install.
Auto-update artifact tampering	Artifact signature verified against a key pinned in the binary before swap; mismatched signature aborts the update with a sticky failure state, so the same bad version isn’t re-attempted.
Malicious enrollment manifest substituted	Maximum impact: attacker changes config (DoS of telemetry), redirects records (which they can’t decrypt), or invalidates tokens. Public key and ingest URL are pinned in the binary, so manifest tampering grants no decryption capability and no exfiltration path.
Stolen laptop’s enrollment manifest exfiltrated	Attacker has the tenant credentials and HMAC key. They can send fake records as that tenant (DoS / poisoning dashboards) and compute `user_id` for guessed emails — but they had to compromise a customer machine first. Mitigation: regenerate the manifest and redeploy.
Network MITM	TLS to pinned PointFive root certificates; ingest URL is pinned in the binary. Hybrid encryption means even a successful MITM gets ciphertext only.
PointFive ingest breach	Per-record ciphertext; an attacker without access to the private key gets no decryption capability. The ingest service is stateless.
PointFive key-management breach	Worst case — private key extracted means in-flight data decryptable until rotation. Compensated by the key-management posture (no plaintext extraction, audited access).
PointFive release-signing key compromise	Attacker can sign malicious binaries. Mitigated by OS-level code-signing chains (Apple Developer ID, EV cert) — independent of PointFive’s keys. An attacker would need to compromise both.
Stale binary running known-vulnerable code	`client_state` reports version; admins see staleness and drive upgrades.
Attacker tries to reverse `user_id` from leaked PointFive data	Without the per-tenant HMAC key (which lives in customer manifests, not on PointFive’s side), unreversible.

10. Design boundaries

Things we deliberately don’t do:

Remote configuration push. No behaviour-changing control plane.
Manifest signing. Public key and ingest URL are pinned in the binary; tampering grants no decryption capability.
Manifest expiration. Bearer-token rotation handles compromise without operational burden.
User roster in manifest. Replaced by local resolution from git config user.email.
Per-tenant encryption keypairs. Available on request, not the default.
In-binary crash reporting. client_state carries a self-check boolean, nothing more.

Glossary

Enrollment manifest — JSON file generated by the PointFive portal, deployed via MDM. Four top-level fields.
MDM — Mobile Device Management / endpoint management system (Jamf, JumpCloud, Intune, Ansible, etc.).
Pinned public key — PointFive’s ingest public key, compiled into the binary at build time. Not in the manifest.
Tenant — A single customer organization.