The lifecycle
The lifecycle covers the key moments in a device's relationship with a vault: registration, group assignment, active sync, and revocation.
Device registration
A device is registered when a user sets up Drive on a specific machine. This is not the same as a user logging in to the ecosystem — a login might create a session, but a Drive device is only registered when the user explicitly activates the Drive app on that device.
Device registration flow
sequenceDiagram
participant App as Drive App (client)
participant PS as Platform Service
participant TS as TinySync
App->>PS: "Set up Drive" (user auth token)
PS->>PS: verify user identity, generate device_id
PS->>TS: POST /v1/devices (display_name)
TS-->>PS: device token (tsdev_...)
PS->>PS: add device to user's groups
PS-->>App: device token
App->>App: persist token locally
App->>TS: first sync (using device token)
POST /v1/devices is open by default — registration grants no vault access, so an unprovisioned identity reaches nothing. Deployments with a Platform Service set TINYSYNC_OPEN_DEVICE_REGISTRATION=false, making the admin token (held by the PS) required to register — the mediated flow shown above.
Group assignment
Once a device is registered, the Platform Service determines which groups it should belong to — based on the user's membership in the ecosystem (teams, org, subscription tier). Group assignment happens immediately after registration and is updated whenever the user's ecosystem memberships change.
Active sync lifecycle
During normal operation, the device uses its token to communicate directly with TinySync. The Platform Service is not involved in individual sync operations — its job is to keep group membership current as ecosystem state changes.
Revocation
A device is revoked in TinySync when any of these occur:
- User explicitly disconnects Drive on that device (uninstall, sign out of Drive)
- User loses access to the ecosystem (account deleted, subscription ended)
- Admin revokes the device for security reasons
Revocation marks the device revoked (revoked_at) rather than deleting it — the row and its credential hash are retained so change-log attribution survives forever, but every subsequent request fails authorization. An already-open WebSocket stream persists until its next authorized request; streams carry only wake hints, never data, so a revoked device can at most observe that something changed. Revocation cannot be undone — re-enabling Drive on that machine means registering a new device identity (POST /v1/devices) and re-granting groups. Removing a device from a single vault is not a revocation at all: it's a group-membership edit (DELETE /v1/groups/{gid}/devices/{did}).
Logout vs revocation
Logging out of the ecosystem does not automatically revoke the Drive device token. A Drive session persists across ecosystem logins unless explicitly revoked. This is a deliberate choice — Drive is a local-first sync engine; files should remain available on the device even when the user is offline or not logged into the web app.
Re-registration
If a device is revoked and the user wants to re-enable Drive on the same machine, the Platform Service creates a new device registration. This issues a new device_id and a new token. The new device goes through group assignment again. The physical machine having had a prior device registered has no effect on the new registration.
Open questions
Each of these graduates to a decision record in the decision log when resolved.
Open Question 1
What triggers Drive device registration? Does every ecosystem login automatically register a Drive device, or only when the user explicitly activates the Drive app on that device?
- Explicit activation — user opens the Drive app and clicks "Set up Drive". Registration is intentional. Platform Service only acts when Drive setup occurs.
- Automatic on login — any ecosystem login on a known device auto-registers a Drive device. Platform Service listens to
user.login events.
- Hybrid — auto-register for users with a Drive entitlement, manual setup for everyone else.
Open Question 2
What happens to the Drive device token on ecosystem logout?
- Token is preserved — Drive continues syncing even when the user is logged out of the ecosystem. Re-login does not require re-registration. This is the local-first-friendly model.
- Token is revoked on logout — Drive stops syncing when the user logs out. Logging back in triggers re-registration. Cleaner security model, worse offline experience.
- Token is suspended (soft revoke) — sync pauses on logout, resumes on login without re-registration. Requires a "suspended" device state in TinySync (not currently in scope).
Open Question 3
Same device_id or new on re-registration? When a user re-registers Drive on the same physical machine (after revocation), does the Platform Service reuse the old device_id or generate a new one?
- Always new device_id — simpler, no state to look up. Each registration is independent. Old sync history is not carried over.
- Reuse device_id if same machine — Platform Service tracks machine fingerprint → device_id mapping. Allows history continuity but adds complexity to the Platform Service.
Open Question 4
Should TinySync groups have names or types? Right now groups are opaque IDs. Should TinySync store metadata (name, type, owning ecosystem) on groups to aid debugging and multi-ecosystem deployments?
- Opaque IDs only — TinySync stores no group metadata. Debugging maps group IDs through the Platform Service. Simpler TinySync schema.
- Name + ecosystem tag — TinySync stores a display name and the ecosystem that owns the group. Useful for admin dashboards and audit logs without exposing business logic to TinySync.