go-apple-dm

go-apple-dm

A pure Go library for Apple device management: the MDM check-in and command protocol, Declarative Device Management (DDM), every enrollment path Apple documents (profile, automated, account-driven, user channel and Shared iPad), an ACME server with Managed Device Attestation, and clients for the device enrollment service and the Apple Business Manager API. A thin reference server, cmd/dmserver, wires it all together.

Why

Apple documents its device management protocol thoroughly, and in Go it has never been available as something you can simply import. The implementations that exist are servers first. NanoMDM is deliberately minimal: it hides context.Context inside a request struct, hands DDM check-ins back as raw []byte, and offers a single webhook as its one integration point. KMFDDM runs declarative management as a separate experimental process. Fleet's MDM is a product, and vendors NanoMDM and NanoDEP as forks rather than depending on them. Each is a sound answer to the question it was built to answer, and this library learns from all three. None of them is a library you can build your own product on.

That is what this is. The protocol, the declarative engine, every enrollment path, and the Apple service clients, as ordinary Go packages you import into your own program and wire the way your program needs.

• Typed from Apple's own schema, not by hand. All 65 commands with their responses, check-in messages, profiles, declarations, status and protocol types are generated in this repository from the pinned apple/device-management YAML, along with the metadata that answers whether a key applies to a supervised Mac on 15.0. A naming lock makes regeneration fail loudly rather than rename a type out from under you, so Apple's schema drift becomes make generate and a diff to review instead of a manual audit every autumn.
• A library shape, held to deliberately. context.Context first, typed errors, and a hook chain; every state change is a typed event on an in-process bus, so audit trails, webhooks, metrics, and reconcilers are ordinary subscribers rather than special cases wired into the core.
• Storage you choose. Interfaces split by concern, with in-memory, SQLite, PostgreSQL, and MySQL backends that all pass one contract suite. Secrets at rest are sealed under named keys with in-place rotation.
• The whole surface, not the core alone. The parts most projects leave you to write — ACME with Managed Device Attestation, account-driven enrollment, Shared iPad, the device enrollment service, the Business Manager API — are here, each with a fake for your tests.
• Testable without hardware. A device simulator speaks MDM, DDM, ADE, account-driven, user channel, Shared iPad, and ACME, so your server can be exercised end to end before a real device ever touches it. The coverage floor is 95%, gated in CI.

What it is not: a product. There is no UI, no inventory, and no fleet management. cmd/dmserver is a thin wiring of these packages, there to prove the library works and to be read as an example of using it, not to be deployed as a device management platform. Nothing is copied from the projects above; github.com/micromdm/plist is the single dependency shared with them, so fixtures interoperate. The reasoning behind all of this is decision record 0001, and the projects studied are credited in reference_projects.md.

Quick start

go get github.com/deploymenttheory/go-apple-dm

The API is not yet stable. This is a v0 module, which is Go's way of saying so: expect breaking changes between minor versions until it reaches v1.

That is the library: the protocol, the declarative engine, every enrollment path, the Apple service clients, the storage contracts and their in-memory backend. It pulls nine dependencies. The SQL backends and the reference server are a second module, so a program that only speaks the protocol never downloads a database driver:

go get github.com/deploymenttheory/go-apple-dm/server

A check-in and command endpoint over an in-memory store, and a typed command queued for a device:

package main

import (
	"context"
	"log"
	"net/http"

	"github.com/deploymenttheory/go-apple-dm/mdmprotocol/mdm"
	"github.com/deploymenttheory/go-apple-dm/schema/commands"
	"github.com/deploymenttheory/go-apple-dm/server/httpapi"
	"github.com/deploymenttheory/go-apple-dm/server/service"
	"github.com/deploymenttheory/go-apple-dm/storage"
	"github.com/deploymenttheory/go-apple-dm/storage/inmem"
)

func main() {
	core, err := service.New(service.Config{Store: inmem.New()})
	if err != nil {
		log.Fatal(err)
	}

	// One path serves check-in and connect; the handler routes on content type,
	// and the middleware takes the device identity from the TLS peer certificate.
	http.Handle("/mdm", httpapi.CertFromTLS(httpapi.Handler(httpapi.Config{
		Checkin: core,
		Connect: core,
	})))

	// The payload carries its own RequestType; the envelope gets a time-ordered
	// CommandUUID. Targets are checked against the schema before they are queued.
	cmd, err := mdm.NewCommand(&commands.DeviceInformation{})
	if err != nil {
		log.Fatal(err)
	}
	id := mdm.EnrollmentID{Channel: mdm.ChannelDevice, ID: "00008030-000000000000001E"}
	if _, err := core.Enqueue(context.Background(), []mdm.EnrollmentID{id}, cmd, storage.EnqueueOptions{}); err != nil {
		log.Fatal(err)
	}

	log.Fatal(http.ListenAndServe(":8080", nil))
}

Swap inmem.New() for sqlite.Open, postgres.Open, or mysql.Open and nothing above changes. For a real deployment add a push certificate, an enrollment identity (SCEP or ACME), and TLS; the reference server shows each of those wired together.

Or run the reference server

# One terminal: an all-in-one process on :8080, nothing to install.
DM_ROLE=all DM_STORAGE=inmem DM_ADMIN_TOKEN=dev-token go run ./cmd/dmserver

# Another: ask it what it is.
curl -s localhost:8080/healthz
go run ./cmd/dmctl -server http://localhost:8080 -token dev-token status

Role:           all
Version:        v0.0.0-20260903102158-a26bcbb63052
Families:       ddm, dep, introspection, mdm
Authorization:  static token (development)
Break-glass:    active (the only credential; no principal store configured)

DM_ADMIN_TOKEN is a break-glass credential for getting started: it bypasses policy and cannot be revoked without a restart. Create real principals with it, then unset it. Every variable is in Reference server below, and make docker-build produces the container image.

Explore the protocol without a server

dmctl explain reads the generated schema tables offline, so it needs neither a server nor a device:

go run ./cmd/dmctl explain DeviceInformation
go run ./cmd/dmctl explain DeviceInformation -target macos:15.0,supervised
go run ./cmd/dmctl explain com.apple.configuration.softwareupdate.enforcement.specific

From there: docs/diagrams for how the pieces fit together, e2e/ and docs/testing/e2e-scenarios.md for worked end-to-end scenarios, and simulator/ to drive a server without hardware.

Architecture

Twenty-seven interactive diagrams cover each component and each protocol flow, from package layering to the ACME attestation exchange. Architecture diagrams carry git-verified source pins. See docs/diagrams.

What it provides

• Protocol core. Typed check-in, command, and response messages generated from Apple's device-management schema, never hand-edited. Detached and attached CMS verification.
• Service layer. Enrollment lifecycle, identity pinning, command queue with dedupe keys, hooks and an event bus, user-channel and Shared iPad handling, optional user authentication gate, and schema-driven checks that a command is supported by the enrolled OS and version.
• Storage. In-memory, SQLite (pure Go), PostgreSQL, and MySQL behind one contract-tested interface set. Secret columns are sealed with AES-256-GCM under named keys with in-place rotation. Every schema lives in a single 0001_init.sql per dialect per migration set.
• Push. APNs HTTP/2 client, notifier with invalid-token events, coalescing, push certificate parsing and topic derivation, and a fake APNs server for tests.
• Enrollment identities. A certificate authority abstraction and a SCEP service with one-time and HMAC challenges, plus a client. Or ACME with Managed Device Attestation: the device generates a key in its Secure Enclave, Apple attests to the key and the hardware, and the server issues only after checking that attestation against the device it expected and against a policy of your choosing.
• Enrollment paths. Profile enrollment with an OTA profile service; automated device enrollment with typed MachineInfo parsing, CMS signature verification against Apple's device CAs, the software update gate, and an OIDC web view; service discovery for account-driven enrollment with both the apple-as-web and apple-oauth2 flows on an authorization server of our own; user channel enrollment and Shared iPad users.
• Device enrollment service (DEP). OAuth 1.0a session client with cursor handling, token PKI for the portal exchange, a device syncer, a profile assigner with read-back, in-memory and SQL stores, and a fake service for tests.
• Apple Business Manager API. ES256 client assertion, JSON:API paging, device and server listing, assignment activities with convergence, rate-limit handling, and a fake server.
• Declarative Device Management. Declarations with content-addressed ServerTokens (RFC 8785 canonical JSON), sets and dynamic membership, per-enrollment snapshots so a device always fetches what its manifest advertised, status reports stored per item, synthesised status subscriptions, an NSPredicate subset validated at upload, and a coalescing change notifier. The engine runs in-process or split across our own mdm and ddm roles.
• Managed Device Attestation. Chain verification to the Apple Enterprise Attestation Root, a required freshness code, the attested key bound to the key being certified, and all ten of Apple's device property extensions parsed by their documented types. The same verifier reads an ACME challenge response and a DevicePropertiesAttestation query response.
• Device simulator. MDM, DDM, ADE, account-driven, user channel, Shared iPad, and ACME clients so a server can be tested without hardware.
• Reference server. Roles mdm, ddm, and all, a bearer-protected admin API, DM_* environment configuration, /healthz, and a distroless container image built by CI.

Layout

The repository is two Go modules. github.com/deploymenttheory/go-apple-dm is the library; everything under server/ is github.com/deploymenttheory/go-apple-dm/server, which depends on the library and never the other way round. Within them, packages are arranged in tiers, and a package may import its own tier and every tier below it, never above. internal/layout asserts this in tests, because the lint workflow cannot fail a build. Decision record 0044 has the reasoning.

Reference server

cmd/dmserver runs one of three roles. mdm serves devices (/mdm, /scep, the enrollment routes) and forwards DDM check-ins to a ddm role when DM_DDM_URL is set; ddm runs the engine and the admin API; all runs everything in one process. Configuration is by environment:

cmd/dmctl drives every one of those routes. Typed verbs cover the surfaces this project models -- enrollments, commands, push, pushcerts, export/import, declarations, sets, notify, principals, policies, audit, plus status, routes and actions -- and dmctl api <METHOD> <path> reaches the rest, including the Business Manager, DEP and ACME families that proxy Apple-shaped APIs. dmctl explain answers offline from the compiled-in schema. E2E-024 walks the server's own route table and fails if any route cannot be driven.

The admin API manages declarations, sets, and assignments (/admin/v1/declarations, /sets, /enrollments), Business Manager servers, devices, and activities (/admin/v1/axm/), DEP accounts: token PKI generation, .p7m import, device listing, profile definition, and sync (/admin/v1/dep/accounts/), and issued ACME identities with the hardware Apple attested for each (/admin/v1/acme/certificates). The exact routes and constants are in internal/app.

Development

git submodule update --init   # pinned Apple schema
make ci                       # lint, verify, test, storage, e2e, fuzz smoke, coverage gate
make testdb-up                # PostgreSQL and MySQL in Docker for `make test-storage` and `E2E_STORE=postgres make test-e2e`
make test-storage-perf        # the 100k-row Clear timing gate on PostgreSQL, without the race detector
make testdb-down              # remove the Docker test databases
make testdb-ddm-up            # build our image and run the ddm role for `TestE2E_DDMSplitDeployment`
make testdb-ddm-down          # remove the ddm role container
make refs                     # clone the reference projects for research (never imported)

Coverage floor is 95% overall and per package. See Makefile targets with make help.

Dependencies stay minimal on purpose: the plist codec, the smallstep CMS and SCEP libraries, the SQL drivers, golang.org/x/crypto, and cedar-policy/cedar-go for admin authorization. OAuth 1.0a, the ES256 client assertion, the OIDC relying party, the OAuth 2 authorization server, the ACME server, its JWS layer, and the CBOR subset an attestation object needs are all implemented in this module. Cedar is the one deliberate exception, and decision record 0034 gives the reasoning: an authorization policy language is not a few hundred lines of parsing the way a JWS serialisation or a CBOR subset is, and hand-rolling one is how the reference CAs ended up matching URL prefixes. The simulator drives the ACME server with golang.org/x/crypto/acme, because testing a server against its own client shows only that the two agree. Nothing from NanoMDM or MicroMDM is imported beyond the plist package.

Sources

Apple's Device Management documentation and the apple/device-management schema repository are the primary sources. The open source projects this work learns from are catalogued in docs/research/reference_projects.md.

Contributing

See CONTRIBUTING.md and the decision record process in docs/research/decisions/README.md.

License

MIT. See LICENSE.