Connected devices

Optional plumbing for any fleet of devices or agents your app manages - enrolment, device identity and attestation, signed telemetry, policy sync, approved commands and health - with nothing loaded until you declare it.

device:
  driver: local                 # local | taps (from @mainsdk/device-taps)
  path: /mainsdk/device
  authority: secret:MAINSDK_DEVICE_KEY
  enrol: { proofs: [token, code] }
  attest: { require: none }
  telemetry: { streams: { app.status: {} }, max-batch: 1MB }
  heartbeat: { every: 60s }
  policy:
    rollout: { stages: ["5%", "25%", "100%"], hold: 1h }
    tighten: { report.interval: higher }
  commands:
    ttl: 15m
    max-targets: 100
    reaction-max: 50

import { device } from "mainsdk/device";             // not exported from "mainsdk"
import { deviceClient, fileKeyStore } from "mainsdk/device/client";

const { token } = await device.enrolments.create({ group: "lab", uses: 10 });
device.telemetry.on("app.status", async (records) => { await store(records); });

// on the device
const client = deviceClient({ url: "https://app.example.com/mainsdk/device", keys: fileKeyStore("/var/lib/acme") });
await client.enrol({ token });
await client.start();
client.send("app.status", { ok: true });

device:
  driver: local

Quick start

schema: 1
device:
  driver: local                 # local | taps (from @mainsdk/device-taps)
  path: /mainsdk/device
  authority: secret:MAINSDK_DEVICE_KEY
  enrol: { proofs: [token, code] }
  attest: { require: none }
  telemetry: { streams: { app.status: {} }, max-batch: 1MB }
  heartbeat: { every: 60s }
  policy: { rollout: { stages: ["5%", "25%", "100%"], hold: 1h } }
  commands: { ttl: 15m, max-targets: 100 }

import { device } from "mainsdk/device";             // not exported from "mainsdk"
import { deviceClient, fileKeyStore } from "mainsdk/device/client";

const { token } = await device.enrolments.create({ group: "lab", uses: 10 });
device.telemetry.on("app.status", async (records) => { console.log(records.length); });

// on the device
const client = deviceClient({ url: "https://app.example.com/mainsdk/device", keys: fileKeyStore("/var/lib/acme") });
await client.enrol({ token });
await client.start();
client.send("app.status", { ok: true });

Calls

Enrolment and identity are built (spec device-identity); the other calls follow their own specs (telemetry, policy, commands, health) and are still being built. Server calls are from mainsdk/device; device-side calls are from mainsdk/device/client. Server calls read the tenant from the context.

device.policy and device.commands are not loaded with mainsdk/device, which stays small for apps that only enrol devices. Call mountPolicy(device) from mainsdk/device/policy and mountCommands(device) from mainsdk/device/commands once where the app starts. On the device, mountPolicy(client) and mountCommands(client) from mainsdk/device/policy/client and mainsdk/device/commands/client add client.policy and client.commands. Using one before its mount call throws an error that names the subpath.

Configuration

device:
  driver: local                       # local | taps (taps from @mainsdk/device-taps)
  path: /mainsdk/device               # where device.handler() is mounted
  audience: acme-fleet                # the aud every device envelope carries; default the project id
  authority: secret:MAINSDK_DEVICE_KEY   # Ed25519 PKCS#8 that signs credentials; a list of 2 rolls it over
  max: 10000                          # devices per tenant; 1 to 1,000,000
  concurrency: 64                     # device requests in flight per instance
  enrol:
    proofs: [token, code]             # token | code | oidc | attested
    token-ttl: 24h                    # default and longest expiresIn for a token; 5m to 30d
  credential:
    ttl: 24h                          # credential lifetime, renewed by the heartbeat; 1h to 30d
    renew-grace: 30d                  # an expired credential can still be renewed with the device key

A revoked device is refused on the next request on every instance. A third party that checks a credential offline learns of a revocation only when the credential expires, so credential.ttl bounds that window.

What you get

Enrolment by one-time token, code, OIDC token or attested evidence. A device key made on the device that never leaves it. A did:key identity, a signed credential with renewal, rotation and revocation, every message signed, fresh and bound to one tenant, and a registry in the tenant's region. The device side is mainsdk/device/client, which needs no main.yaml.

Examples

import { device } from "mainsdk/device";

const { token, uses } = await device.enrolments.create({ group: "lab", uses: 3 });
const page = await device.list({ group: "lab" });

Drivers

What it always does

• Off until declared in main.yaml and imported; no route, table, timer or cost otherwise, and never re-exported from mainsdk
• Device keys are made on the device and never leave it
• Every device message is signed, fresh and bound to one tenant
• Telemetry is delivered once and in order, with redaction on the device and on the server
• A device keeps its last good policy when the app is unreachable and never accepts an older one
• Commands run only registered handlers, expire, and need people's approval when risky; an agent never approves
• No detection rules, endpoint event schemas or code delivery, now or later (ADR-0076)

Errors and checks

See check codes.

Swapping drivers

device:
  driver: taps                        # needs @mainsdk/device-taps

The taps driver issues the TAPS credential form from the same device record. Nothing else in your code changes.

Testing

simulateDevices(app, { count }) from @mainsdk/testing enrols simulated devices, each a real deviceClient on a memory key store, and drives them on the fake clock. deviceConformance({ driver }) is the suite every driver passes.

Next

• Sign-in and sessions
• Permissions