01The Problem
TinySync is a file sync engine. It has its own identity primitives: devices and device tokens. Everything that reads or writes to a vault authenticates as a device. There are no users, sessions, or roles inside TinySync itself.
But Drive is deployed into other products — Scribe, a workspace platform, a developer tool. Those products have their own users, login flows, roles, and organization structures. When a user opens the Drive app on their laptop, something has to bridge the gap between "Alice logged in to Scribe" and "device dev_7a3b is authorized to read vault v_docs".
That bridge is what this document describes. The goal is to keep TinySync's sync engine simple and product-agnostic while giving ecosystems the control they need over who can access what.
02Six Elements
The integration model is built from six distinct concepts. Understanding what each one is — and what it deliberately is not — is the foundation for everything else.
The key boundary: everything left of TinySync is the ecosystem's responsibility. TinySync never reads ecosystem user records, session tokens, or role assignments. It only sees device IDs and group memberships — both of which are managed for it by the Platform Service.
03Identity Model
TinySync's identity unit is the device. A device is not a machine — it is a logged-in session of a specific user on a specific machine. The same laptop has two different device identities if two different users log in on it.
Device token format
Device tokens are custom bearer tokens, not JWTs. Each token encodes its device ID and a random secret:
tsdev_{device_id}_{secret}
device_id — opaque identifier, assigned at registration
secret — 32 random bytes, base64url-encoded
The server stores only the SHA-256 hash of the secret (with a domain separator). The raw token never persists on the server side. This means a device token cannot be recovered after issuance — only revoked.
One token per session
There is exactly one device token per (user × physical device) pair. If Alice logs in on her MacBook, the Platform Service registers a device and issues one token. That token lives on Alice's MacBook. It is not shared with Bob's MacBook, even if both are in the same group.
Who knows about users?
TinySync does not. The Platform Service maintains the user_id → [device_ids] mapping. When an ecosystem event arrives (user added to workspace, user promoted to admin), the Platform Service translates it into device operations and calls the TinySync API.
| Concern | Lives in | TinySync knows? |
|---|---|---|
| User identity | Ecosystem + Platform Service | No |
| User → Devices mapping | Platform Service | No |
| Device identity | TinySync | Yes (it's the primary key) |
| Device → Groups | TinySync | Yes |
| Group → Vaults | TinySync | Yes |
04Group-Based Authorization
In TinySync, access to a vault is granted at the group level — never directly to individual devices. A device gets access to a vault by virtue of being a member of a group that has access to that vault.
Why groups, not direct device authorization?
Consider a workspace with 50 users each with 2 devices (100 devices) accessing 20 vaults. Without groups, adding a new vault requires 100 authorization records. Adding a new device requires 20. With group-based auth, adding a vault is one group-vault edge. Adding a device is one device-group edge. Neither requires touching the other.
Group membership is opaque to TinySync
TinySync stores group IDs as opaque identifiers. It does not know what a group "means" in the ecosystem — whether it maps to a team, an organization, a billing tier, or a product subscription. That interpretation lives entirely in the Platform Service. TinySync only answers: "is device X a member of a group that has access to vault Y?"
Authorization at request time
TinySync resolves authorization lazily, at each request. When a device presents a token and requests access to a vault, the server checks: is this device in a group that has access to this vault? If yes, the request proceeds. There is no pre-computed access matrix that needs to be kept in sync.
05Multi-Group Access
A device can belong to multiple groups. A vault can belong to multiple groups. This is a deliberate design choice that enables complex organizational structures without requiring TinySync to understand them.
In this example: Alice's MacBook is in both groups and can reach both vaults. Carol's MacBook is only in the Engineering group and can reach both vaults her group has access to. Bob's MacBook is only in the All-Access group and can reach only the company drive.
Access is the union of all group memberships
If a device belongs to groups G1 and G2, its effective vault access is the union of vaults accessible via G1 and vaults accessible via G2. There is no "deny" — group membership is purely additive. Access restriction is achieved by keeping a device out of a group, not by adding a deny rule.
Practical patterns
| Ecosystem concept | Mapped as |
|---|---|
| Organization-wide Drive | One group containing all org members' devices, one vault |
| Team-specific Drive | One group per team, one vault per team; devices in team group |
| Cross-team shared vault | Vault accessible by multiple groups; each team group gets the edge |
| Personal Drive | One group per user containing all their devices, one personal vault |
| Admin full access | Admin devices added to all relevant groups, or a special admin group with all vault edges |
06Containers
A container is a tagged view inside a vault. Containers carry product namespace and policy information — they are how different consuming products carve out their space within a shared vault without interfering with each other.
What containers are for
Imagine Scribe and Drive both use the same vault for an organization. Scribe might store document attachments; Drive stores the full file tree. Containers let them tag their items differently and apply different access policies without requiring separate vaults per product.
Container ↔ Group: no direct relationship
This is a deliberate choice. A device authorized to a vault (via a group) can read any container in that vault — unless container-level access controls are added separately. The primary access gate is the group. Containers add a layer of namespace and policy on top, not a separate authorization layer.
07Platform Service
The Platform Service is the translation layer between the external ecosystem and TinySync. It is not part of TinySync — it is a service that the ecosystem operator builds and runs, which speaks to TinySync's management API.
What the Platform Service owns
- The user → devices mapping (which devices belong to which user)
- The device registration lifecycle (when to create a device, when to revoke it)
- The group management logic (when to add a device to a group, when to remove it)
- Translation from ecosystem events to TinySync API calls
What the Platform Service does not own
- It does not decide whether a sync succeeds or fails — that's TinySync's job
- It does not manage file contents or metadata — that's the vault
- It does not run on the client device — it's a server-side service
Platform Service is ecosystem-specific
Each ecosystem that embeds Drive builds its own Platform Service. The service shape is consistent (it talks to TinySync's management API), but the event sources and business logic are ecosystem-specific. A Scribe integration listens to Scribe events; a different product integration listens to its own events.
08Integration 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.
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 deletes the device's token hash from TinySync. The device token immediately stops working. It cannot be recovered — the device must re-register to get a new token.
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.
09Token Management
Token management is the operational concern of keeping device tokens secure and current across the fleet of devices an ecosystem manages.
Token storage on the client
Device tokens are stored by the Drive app in the OS credential store (Keychain on macOS, Windows Credential Manager). They are not stored in plaintext. The token is the device's long-lived credential — losing it (or having it revoked) requires re-registration.
Token storage on the server
TinySync stores only the SHA-256 hash of the secret portion of each token, with a domain separator to prevent cross-purpose hash reuse. The raw token is never stored. Validation is: hash the presented secret, compare to stored hash.
stored_hash = SHA-256("tinysync-device-token:" + secret_bytes)No token rotation in v1
Device tokens do not expire and are not rotated automatically. Revocation is the only way to invalidate a token. This keeps the implementation simple and avoids the complexity of refresh flows on a sync engine that must work offline.
Group token? No.
There is no "group token" — a single credential that grants access to all vaults a group can reach. Each device has its own token. The group structure is a server-side authorization record, not a credential. This ensures that compromising one device never grants access to the group's vaults from a different device — the attacker also needs the group membership to be in place, which is managed server-side.
10Design Invariants
These are the properties the design is built to maintain. Violating any of them means rethinking the model, not finding a workaround.