Device Flag
Reference current APP, WEB, PC, SYSTEM, and Device Level values plus connection-conflict boundaries.
Device Flag identifies a client device category. Device Level expresses connection-conflict policy within the same UID and category. Neither is an OS version, concrete device ID, or product role.
Goal and completion criteria
The product backend chooses a stable device_flag, concrete device_id, and server-controlled device_level for every endpoint and can explain whether same-category devices coexist or use single-active policy.
Authority
The tables align with internal/contracts/protocolmeta/types.go and pkg/protocol/frame/common.go. Tests freeze client categories, the server-reserved value, and both conflict levels.
| Value | Name | Scope | Integrator guidance |
|---|---|---|---|
0 | APP | Client | Native mobile-application device category. |
1 | WEB | Client | Web browser or web-application device category. |
2 | PC | Client | Desktop-client device category. |
99 | SYSTEM | Server-reserved | Server-reserved system device category; end-user clients must not impersonate it. |
Device Levels
| Value | Name | Scope | Integrator guidance |
|---|---|---|---|
0 | DeviceLevelSlave | Client | Allows multiple endpoints in the same device category to coexist. |
1 | DeviceLevelMaster | Client | Declares single-active conflict policy within one device category; enforcement still depends on verified connection authentication and composition. |
Do not merge these fields
| Field | Question answered |
|---|---|
device_flag | Is this APP, WEB, PC, or server-side SYSTEM? |
device_id | Which concrete installation or endpoint in that category? |
device_level | May endpoints in the same UID/category coexist or use single-active conflict policy? |
Do not use a phone brand, browser user agent, or OS version directly as device_id. Generate a stable random identifier and define whether reinstall, cleared storage, device migration, or backup restore creates a new ID.
Current authentication limitation
Token metadata can store Device Level, and the user use case can schedule matching local Sessions to close after a Master update or device quit. However, the default v3 Beta Gateway has no injected stored-token verifier, so CONNECT uses Slave level by default.
Setting device_level=1 therefore does not prove that a later connection becomes single-active. Before release, wire the verifier into Gateway and test new Master connection, old Session closure, cross-node conflict, revocation, and reconnect rejection.
Integration guidance
- Use different categories when APP, WEB, and PC coexist.
- Use Slave for multiple same-category endpoints and process RECVACK independently per Session.
- A backend issues Master for single-active policy; clients never select it.
- SYSTEM is for trusted server identities; reject it from end-user ingress.
- Keep provider push token, OS permissions, risk, and revocation in a product device registry; Presence is not a device database.
Troubleshooting
- PC renders as a number: wire value 2 remains authoritative; a log/management String method is not the numeric contract.
- Same-category Master does not replace: inspect the Device Level actually returned by the CONNECT verifier.
- Different platforms replace each other: inspect accidental reuse of one Device Flag.
- A device reconnects after logout: inspect token revocation and Gateway verification rather than Session close alone.
Security boundary
A device category grants no product permission. SYSTEM is not an “administrator mode” for ordinary clients; restrict it to trusted internal components and reject spoofing at public ingress.
Next step
Apply these values with the Device model, then use Authentication & Security for issuance and revocation.