{
  "uid": "cogitave.learn.understand-massar.the-security-model",
  "kind": "moduleUnit",
  "href": "/modules/understand-massar/the-security-model/",
  "title": "The security and consent model",
  "summary": "",
  "type": null,
  "products": [],
  "roles": [],
  "levels": [],
  "subjects": [],
  "headings": [
    "How the device authenticates",
    "How the operator is authorized",
    "No standing shell",
    "Consent, stated at install time",
    "What is verified before the binary is trusted",
    "Platforms this covers today"
  ],
  "source": "Two separate authorization boundaries protect a Massar session: the device proves who it is with a token, and the operator is authorized and audited on the Diyar side. This unit covers both, plus exactly what is shipped today versus designed for later.\n\n## How the device authenticates\n\nEvery device is issued a per-device secret at enrollment. The installer takes it as a required flag, and the agent sends it as a bearer token on every connection to the broker:\n\n```bash\nsudo ./install/install.sh --broker-url wss://diyar.cogitave.com/api/v1/console/agent --token <device-secret>\n```\n\n```powershell\n.\\install\\install.ps1 -BrokerUrl wss://diyar.cogitave.com/api/v1/console/agent -Token <device-secret>\n```\n\nThe agent stores this alongside its broker URL and device ID in an environment file it reads at startup, and sends it as an `Authorization: Bearer` header when it dials the broker - the cloud side derives the device's identity from that token; the agent does not identify itself to the broker any other way.\n\n```bash\n# /etc/massar/agent.env, written by install.sh, chmod 0600:\nMASSAR_BROKER_URL=wss://diyar.cogitave.com/api/v1/console/agent\nMASSAR_AGENT_TOKEN=<device-secret>\nMASSAR_DEVICE_ID=<hostname>\n```\n\n> [!NOTE]\n> **This static, pre-issued token is the enrollment path that ships today.** Massar's frontend also includes a graphical setup wizard and mocked UI for an RFC 8628 device-code / QR-code enrollment flow - the kind where you would approve a new device from an already-authenticated console instead of copying a secret to it. That flow is a preview of where enrollment is headed: the UI exists, but the backend commands behind it are not implemented. If you are enrolling a device today, the token flag above is the real path.\n\n## How the operator is authorized\n\nMassar itself does not decide who may open a session against a device - that authority sits entirely on the Diyar side. The operator side of a session is gated by Diyar's role-based access control (an operator needs operator rank on the device's workspace), and every session that is opened is recorded there. Massar's own job stops at the wire and the PTY; it holds no user directory and makes no authorization decision of its own.\n\n## No standing shell\n\nMassar never keeps a shell running \"just in case.\" A PTY is created only in response to an explicit `open` control frame sent through the broker, and it is torn down the moment the session's WebSocket connection ends - deliberately closed by the operator, dropped by the broker, or lost to the network. There is no idle session sitting between uses, and no persistent shell to find if something on the device is compromised independent of an active console session.\n\nSessions are also TTL-bounded on top of that: they exist for as long as an explicitly opened session is active, not indefinitely.\n\n## Consent, stated at install time\n\nInstalling Massar is a deliberate grant of access, and both installers say so before anything is configured:\n\n> \"Consent: installing this grants Cogitave operators the ability to open a remote console (terminal) to this device, gated by Diyar RBAC and fully audited. Do not install unless you authorize that access.\"\n\nThe Linux installer prints the same point again after the service starts, so the person running it sees the consequence twice - once as a warning, once as a confirmation of what just happened:\n\n```text\nMassar agent installed and running.\nThis device is now connected to Diyar. An authorized operator can open a web terminal to it (role-gated and fully audited).\nTo remove it: sudo ./uninstall.sh\n```\n\n## What is verified before the binary is trusted\n\nThe token and the RBAC/audit boundary protect a *running* agent; supply-chain controls protect the binary itself before it is installed. Each release attaches a SHA-256 checksum, a CycloneDX SBOM, a keyless cosign signature (verified against the OIDC identity of Cogitave's GitHub Actions), and SLSA build provenance; Windows binaries are additionally Authenticode-signed. The installer verifies the checksum and signature before it places the binary - `--skip-signature` (Linux) and `-SkipSignatureCheck` (Windows) exist only for local development builds and are loudly labeled as such.\n\n> [!WARNING]\n> Windows Authenticode signing today runs without a provisioned EV certificate, so `-SkipSignatureCheck` is currently the only way to install a locally built test binary. This is a known, tracked gap - not a supported way to skip verification on a production device.\n\n## Platforms this covers today\n\nMassar installs on Windows and Linux only today. macOS is deliberately deferred - there is no installer path and no service definition for it, even though Cogitave's release pipeline cross-compiles a macOS binary as part of its build matrix. The Linux installer's own header flags this directly: it targets Linux first, with macOS (via launchd) explicitly \"not yet.\" If your fleet includes macOS devices, there is no supported way to run Massar on them yet.\n",
  "partOf": "cogitave.learn.understand-massar",
  "durationInMinutes": 7,
  "quiz": null
}