Security model

A device can change the physical world. 8DK is built so that nothing happens on a device unless a person allowed it, and so that taking that permission back works from the next call.

What 8DK enforces

• Deny by default. A paired device has no allowed capabilities until the person ticks them. No grant, no tool, no call.
• Consent at pairing. Pairing needs a person's yes. No answer within 2 minutes, or an error, is a no and stores nothing.
• One capability at a time. Grants are per device and per capability. There is no wildcard and no generic command capability.
• The grant check cannot be switched off. It runs before the permission engine, and no policy rule lifts it.
• The permission engine on every call. Every call is checked as action device_use. Your rules can block or ask. Background candidate agents (shadow runs) can never use a device, even an allowed one.
• Asking every time where it matters. A confirm capability asks the person on every call.
• Revocation counts on the next call. Grants are read on every call, never cached, and read again after any wait for the person.
• Tokens are not stored. A device token is 32 random bytes. The vessel keeps its SHA-256 and compares in constant time.
• A device cannot grow new powers quietly. Tools always come from the manifest the person approved, and a changed manifest fails authentication when it is passed to authenticate, so the device pairs again and the person sees the new list.
• Device text is checked. Manifests are validated with size limits, and text containing control, escape, direction-changing or other invisible formatting characters is refused, never cleaned up, so a prompt shows exactly what a person would read.
• Input is checked before anyone is asked. The call's input is copied, then checked against the capability's params, and only that copy is shown to the person and sent to the device. Text values inside the input are not filtered yet; see below.

What 8DK does not protect against

• Interception during pairing. The 6-digit code shows that the device in front of you is the one on this connection. It is not protection against someone relaying frames between the device and the vessel. The connection has to be trusted end to end, for example an encrypted (wss) connection to your own vessel.
• A device that lies. The name, description and Can read or Can do label are what the device declares. 8DK cannot check that a capability does what its description says. Only allow capabilities on devices you trust.
• What a device sends back. A result is whatever the device returns, and it reaches the agent as tool output. Treat it as untrusted data, like a web page.
• Devices with no screen. In v1, a device that cannot show the code leaves nothing to compare. Slice 2 defines a fallback.
• Restarts. Pairings and grants are in memory in v1 and vanish when the process exits. Keeping them is slice 2.
• An audit record. v1 reports each decision to an optional onDecision hook. Writing device decisions to 8gent's audit log is a later slice.
• Text values the agent sends. A call's string values are checked for type, not for control characters or length. Whatever shows an approval prompt must escape them.
• A device claiming another device's id. Anyone who can reach the pairing step can claim an id and name that is already paired. A yes replaces the old pairing, and the v1 prompt does not say so.
• A changed manifest, unless you check it. authenticate only notices a changed manifest when it is passed one, and a failed check does not unpair the device.
• Size. v1 puts no limit on the size of a frame, a result or an error message. The route in slice 2 caps them.
• Closed connections. A call waiting on a device that disconnects is not failed until its timeout, the timeout is not clamped, and there is no cap on waiting calls. Use one CallCorrelator per authenticated connection.
• The device token in transit. The token is a long-lived secret with no expiry or rotation in v1. Anyone who reads it can act as the device, so it must only travel over an encrypted connection (wss) and be stored on the device like a password.
• Children's accounts. The child-safety gate in the permission engine does not cover device_use yet. Do not pair devices on an 8gent Jr or under-13 account; slice 2 must close this first.

Where the code is

packages/8dk on main of 8gent-code, merged by #3364, not yet in a release: manifest.ts (validation and limits), pairing.ts (consent, tokens, grants), adapter.ts (the call checks), link.ts (frames). Issue #3362.

Found a problem? Open an issue on 8gent-code.

Next: Status and roadmap.