§37 Loams Desktop and Mobile Apps: a cordis Console, a Tauri Shell, Native Phones

Status: Proposed · 2026-10-01, revised 2026-10-02 (the Authentik and D220 rulings). The direction is the owner's, given on 2026-10-01 in two messages:

1. "I downloaded the DeepSeek Harness desktop and mobile app repos. They serve as the base for the Loams desktop app and mobile app, with Connect-RPC. The harness desktop's Rust backend is Tauri, so adapt our control-plane React to Tauri. Mobile is Kotlin, so use Connect-RPC natively in Swift (iOS) and Jetpack Compose (Android)."
2. The same day's correction: "cordis" is the JavaScript meta-framework the harness is built on (contexts, services, a plugin lifecycle with scoped disposal and hot reload), not Tauri. The intent is to adapt Loam's control-plane React to cordis so that any code can be loaded as a plugin: console pages, panels, engine adapters, connectors, agent tools, and the integrations of §26, §30, §32–§34, each a cordis plugin with declared services and dependencies, loaded from a catalog like the harness's cordis.yml, in the browser and inside Tauri. Tauri stays the desktop shell; cordis is the application architecture inside it. "Native Connect-RPC" on mobile means connect-swift and connect-kotlin generated from the shared protos, with no web view or bridge, in native SwiftUI and Compose.

The owner's standing rulings that apply: Connect-RPC everywhere (connect-es, connect-swift, connect-kotlin, all from the protos connect-rust serves, D128); the package namespace loams (crates.io, PyPI, npm @loams), Go paths loams.dev/..., the domain loams.dev, CloudEvents types io.loams.dev.*; the repository moving to the GitHub organisation ostrium-labs; mobile native per platform, not Kotlin Multiplatform UI. Two further rulings arrived while this document was written (2026-10-01 and 2026-10-02): the identity provider is Authentik, open-source edition only (Clerk and Keycloak are gone), so every app sign-in flow targets Authentik (§6.5, §7.2); and D220's open-core split stands: the console's multi-tenant, hosted and billing parts stay in the private loam-cloud and loam-platform repositories, loaded as private plugins from a private registry. This document designs only the open side and names the extension points the private side uses (§5.8); it contains no design for hosted or billing plugins.

This document turns that direction into decisions D420–D439 and open questions Q420–Q439. Every choice beyond the direction (formats, trust tiers, flows, phasing) is a proposal until the owner confirms it. No code is written by this document. The plans are AP0, AP1a, AP1, AP2 and AP3.

Markers: (verified 2026-10-01) means checked against a primary source on that date (§17). (verify) means the plan that builds it checks it first. (estimate) means computed, not measured. Paths of the form harness-desktop/… point into dina-kar/deepseek-harness-desktop at 2d1b505 (2026-08-15); harness-mobile/… into dina-kar/deepseek-harness-mobile at 68b6c2f.

Naming. This document writes loams for the CLI binary and @loams/* for npm packages, following the owner's namespace rulings (D400, D401; the binary loams answers §30's Q284). Until D33's rename PR, everything builds under the working names (operon, @loam/console, @loam/ui).

1. SummaryCopy Anchor Link

2. Goals, non-goals and personasCopy Anchor Link

2.1 PersonasCopy Anchor Link

2.2 GoalsCopy Anchor Link

1. The console is extensible without a fork. Any page, panel, engine view, connector form, approval renderer or agent-tool view is a plugin with a manifest, declared services and declared permissions (D422–D427).
2. One console in three places. The engine's /ui, the desktop window and (when Q436 says so) Loam Cloud run the same host with different plugin sets (D428).
3. A desktop app that is a better local stack manager than the terminal, built on the CLI rather than beside it (D429).
4. Phones that are safe approvers. A decision proves a person on a known device; notifications reveal nothing to Apple, Google or the gateway (D434–D436).
5. One contract. Protos generate the server and all three clients; one mock and one scenario set test all of them (D433, D438).
6. Open by default (D220): every app, the plugin host, the first-party plugins and the push gateway's code are Apache-2.0 here or in loams-mobile.

2.3 Non-goalsCopy Anchor Link

• No Electron, no React Native, no Flutter, no Tauri mobile, no KMP UI. The owner chose Tauri for the desktop and native UI on phones. Tauri's own mobile targets shipped in 2.0 but its team calls the developer experience unfinished (verified 2026-10-01); they stay a fallback only.
• No Node server. §19 P8 rules out a Node service beside the binary. The harness's cordis host half (Node) is not used: Loam's host side is the Rust engine (Connect services) and, on the desktop, the Tauri host.
• No model-written plugins at run time. The harness's cordis_define lets an agent submit code that runs in the console after a click. Loam does not ship that: agents act through MCP and tokens (§15, §19 §5), not by injecting UI code.
• No full console on phones. Phones show environments, approvals, operations, jobs, runs and the inbox. Identity administration, keys and collection editing stay on the console and desktop.
• No relay in track AP. Phones reach instances that are reachable: Loam Cloud, or a self-hosted gateway exposed with TLS after the auth plan (Q425).
• No offline decisions (D435).

3. What we take from the harness repositories (D421)Copy Anchor Link

3.1 The desktop harnessCopy Anchor Link

harness-desktop is upstream DeepSeek Harness (about 12 000 commits by its authors) plus a Tauri 2 host added on 2026-08-14 by fendouai. The host is apps/desktop/src-tauri/src/lib.rs (164 lines) and a capability file.

Gaps we fix rather than copy: no per-launch token, no supervision after readiness (a crash leaves a dead page), logs discarded after readiness, a hard kill with no process group, no single-instance guard, no CSP on the loopback UI, no updater, no signing or CI, and bundle targets that contradict each other ("all" with a macOS ["app"] override).

3.2 The mobile harnessCopy Anchor Link

harness-mobile is an Android client (Kotlin 2.0, Compose, Hilt, OkHttp, one multiplexed WebSocket) by sorsama and contributors, talking to a harness through the dsh-relay plugin (TypeScript, in a separate repository not studied here).

Gaps we fix: the relay terminates TLS and sees all plaintext; no token refresh; notifications only while a foreground service holds the socket, and no approving from a notification; approvals show only a tool name and a reason; cleartextTrafficPermitted="true" and user CAs trusted app-wide; a plaintext session cookie in DataStore with allowBackup="true"; a 2 000-line singleton store; no iOS.

3.3 Licences and attributionCopy Anchor Link

4. ArchitectureCopy Anchor Link

                         ┌────────────────────── one console host (cordis v4) ─────────────────────────┐
                         │ boot: Context + Loader + browser module table + boot manifest (loams.yml)    │
  browser at /ui ───────▶│ services: transport · rpc.* (Connect) · api (OpenAPI) · session · platform   │
  (engine-served)        │           slots · router · settings · flags · i18n                           │
                         │ plugins:  shell · identity · collections · jobs · durable · approvals ·      │
  Tauri webview ────────▶│           devices · connectors · flow · gateway · live · (desktop) stacks ·  │
  (bundled, desktop set) │           mcp · (hosted: private plugins from a private registry, D220)     │
                         │ third-party plugins ──▶ sandboxed iframes ◀──bridge──▶ attenuated tokens     │
                         └───────────────┬───────────────────────────────┬──────────────────────────────┘
                                         │ fetch (browser)               │ net_fetch over IPC + Channel (desktop)
                                         ▼                               ▼
   ┌──────────── Tauri host (Rust, desktop only) ────────────┐   ┌──────── Loam instance (Rust) ─────────────────┐
   │ cli: `loams … --output json` (D283) ── stacks (D285)    │   │ connect-rust: Connect + gRPC + gRPC-Web       │
   │ net: bridge, origin allowlist, bearer injection         │──▶│ loam.instance/devices/approvals/operations/    │
   │ auth: PKCE loopback, keychain (keyring)                 │   │   notifications.v1 (AP0, AP4) · loam.jobs.v1   │
   │ tray · single instance · deep links · updater · logs    │   │   (J1) · loam.live.v1 · /api/v1 (OpenAPI, P9)  │
   └──────────────┬──────────────────────────────────────────┘   │ approvals = §21 approval promises             │
                  │ spawns via CLI (setsid, detached)            │ notifier: io.loams.dev.* → inbox → seal ──┐   │
                  ▼                                              └───────────────────────────────────────────┼───┘
         local stacks under ~/.loam/stacks/<name>                                                            │ sealed
                                                                                                             ▼
   ┌── Loams for iOS (SwiftUI) ──┐  ┌── Loams for Android (Compose) ──┐        ┌── loams-push gateway ─────────────┐
   │ connect-swift (URLSession)  │  │ connect-kotlin (OkHttp)         │◀──────▶│ APNs / FCM credentials of the     │
   │ Secure Enclave keys         │  │ StrongBox / TEE keys            │  push  │ store apps; sees ciphertext only  │
   │ NSE unseals HPKE payloads   │  │ FCM or UnifiedPush, Tink HPKE   │        │ (UnifiedPush: instance → endpoint)│
   └─────────────────────────────┘  └─────────────────────────────────┘        └───────────────────────────────────┘

5. The console as a cordis application (D422–D428)Copy Anchor Link

5.1 Why cordis, and what it givesCopy Anchor Link

cordis (MIT, cordiverse/cordis, by Shigma, the framework under Koishi and DeepSeek Harness) is a dependency-injection and lifecycle framework: a Context whose services are declared and injected, plugins with an apply function, an inject list and a config schema, and fibers (v4's scopes) whose side effects are all registered through ctx.effect or ctx.on and undone when the fiber is disposed. A plugin whose injected services are missing stays pending and activates when they appear; when a provider is replaced, its dependents reload. That is exactly what an extensible console needs: a page can depend on rpc.jobs and appear only on instances that serve loam.jobs.v1; disabling a plugin removes its routes, slot entries and streams without a page reload.

What exists today (verified 2026-10-01): cordis 4.0.0-rc.10 (2026-09-08; release candidates every 2–4 weeks; the README says the API "is not yet stable"), @cordisjs/plugin-loader 1.0.0-rc.7, @cordisjs/plugin-include 1.1.0, @cordisjs/plugin-hmr 1.1.0. The core imports no node: module, so it runs in browsers and in Tauri's webview; the harness runs the stock loader in the browser by stubbing node:module and process in Vite. The maintainer bus factor is one (548 of about 560 commits). §14 risk 1 covers it.

The harness proves the browser half at scale: about 40 client plugins in its web bundle, a boot manifest the server injects (window.__DSH_BOOT__), per-plugin bundles that may not import each other's values, a slot system for React, and fiber-by-fiber reload. Loam takes that half. The harness's Node host half (the loader on the server, Typert RPC over POST /api/<ns>/<method> and downlink WebSockets) does not apply: Loam's host side is Rust, and its RPC is Connect, which adds typed server streaming that Typert lacks.

5.2 The hostCopy Anchor Link

@loams/console-host (in web/packages/console-host) is the only code that is not a plugin. It:

1. reads the boot manifest: GET /ui/plugins/manifest.json from the engine in a browser, or the bundled plugins/manifest.json in Tauri. Each row is {id, name, url, integrity, rev, tier, inject, slots};
2. creates new Context(), installs @cordisjs/plugin-loader with loader.internal set to a browser module table that resolves rows to import(url) with Subresource Integrity checks, and loads the catalog (loams.yml, §5.3);
3. provides the core services (§5.4) and renders the React root, which renders only the root slot;
4. finishes boot with an all-fibers sweep: any fiber still pending after 10 s is reported in a "plugins" diagnostics page with the services it waits for (the harness's boot check).

Shared platform modules (React, React DOM, React Router, cordis, @loams/ui, @loams/slots, @bufbuild/protobuf, @connectrpc/connect, @loams/proto) are provided once through an import map; plugin bundles mark them external. A plugin that bundles its own React fails the build (AP1a Task 2).

5.3 The manifest and the catalog (D423)Copy Anchor Link

A plugin's manifest is a block in its package.json:

{
  "name": "@loams/plugin-jobs",
  "version": "0.1.0",
  "type": "module",
  "exports": { "./client": "./dist/client.js" },
  "loams": {
    "plugin": {
      "kind": "console",
      "entry": "./client",
      "tier": "first-party",
      "inject": ["rpc.jobs", "router", "slots", "session"],
      "provides": [],
      "slots": ["console.nav", "console.page", "environment.overview.card", "engine.view"],
      "permissions": ["jobs:read", "jobs:admin"],
      "requires": { "console": "^1.0.0", "api": ["loam.jobs.v1"] },
      "editions": ["oss", "desktop", "cloud"],
      "config": "./dist/config.schema.json",
      "server": null
    }
  }
}

The catalog is a cordis v4 loader entry list, the format the harness's cordis.yml uses (- id, name, config, group, disabled, inject). Loam names it loams.yml and composes it the harness's way: a base list, then patch lists per bundle and per edition (- id: x patches replace a row's config; - insert: adds rows):

# web/apps/console/catalog/base.yml   (the oss set)
- id: shell
  name: '@loams/plugin-shell'
- id: identity
  name: '@loams/plugin-identity'
- id: collections
  name: '@loams/plugin-collections'
- id: jobs
  name: '@loams/plugin-jobs'
  config: { pageSize: 50 }
- id: approvals
  name: '@loams/plugin-approvals'
- id: connectors
  name: '@loams/plugin-connectors'
# web/apps/desktop/catalog/desktop.patch.yml
- insert:
    - id: platform-tauri
      name: '@loams/platform-tauri'
    - id: stacks
      name: '@loams/plugin-stacks'
      inject: [platform.stacks]

!!js is not allowed in any Loam catalog. The harness evaluates !!js config with new Function, which needs unsafe-eval and is a code-execution path through configuration. Loam's console CSP has no unsafe-eval (§6.3), and the AP1a loader rejects a catalog that contains the tag. Dynamic values come from services (flags, session) inside apply, not from the catalog.

5.4 Service contracts (D424)Copy Anchor Link

The rule from the harness holds: a value import from one plugin into another is a build error. Plugins share types through @loams/proto and declare module merges on the Context and SlotMap interfaces, and behaviour only through services.

5.5 Slots (D425)Copy Anchor Link

The integrations of the other designs land as plugins in these slots:

5.6 Trust tiers, isolation and permissions (D426)Copy Anchor Link

cordis has no sandbox: its isolate and intercept only give scopes separate service names, and the harness says plainly that its plugins are as trusted as shell access. Loam needs a boundary for code its users did not write.

Server-side enforcement. A third-party plugin's calls do not carry the user's token. When the plugin activates, the host asks the gateway for a vended token (§19 §5.2 flow 3) with scp = the manifest's permissions ∩ the user's rights, act = {"sub": "plugin:<id>@<version>"} in the actor chain, one environment, and a 15-minute TTL, renewed while the plugin is active. The server's Authorizer decides as for any token, and the audit log shows the plugin as the actor. Client-side checks only shorten the path to a refusal.

Consequences:

• Before the unified auth plan (D111) there is nothing to vend, so third-party plugins are disabled in every build, and local-path plugins in development run as first-party with a red "unverified plugin" banner.
• A third-party plugin cannot render outside its frame (no overlays across the console, no access to other plugins' DOM), and cannot read the clipboard; ui:clipboard-write and ui:notifications go through the bridge with a visible host prompt the first time.
• On the desktop, third-party frames load from the loams-plugin:// custom scheme, a different origin from the app's; AP1a Task 6 verifies that frames get no Tauri IPC (verify).
• Installing a plugin on an instance is an org-owner action, and in a protected environment it goes through an approval gate (D435). The install screen shows the permissions, the publisher, and whether npm provenance links it to a public repository.

5.7 Sources, distribution and reload (D427)Copy Anchor Link

Reload. In development, Vite's HMR replaces React components in place; a change to a plugin's apply triggers the harness's fiber refresh (invalidate the module, dispose the fiber, which undoes its slot entries, routes and streams, then load it again). React state inside that plugin is lost, as in the harness. In production, the host subscribes to PluginService.WatchManifest; an install, upgrade, enable or disable becomes a fiber add, replace or dispose, with no page reload. Desktop updates replace the whole bundle on restart (§6.6).

Versioning. The host exposes console (semver) and the plugin declares requires.console. Breaking changes to a core service or slot's props bump the host's major version; the slot catalog and SlotMap types are generated into docs (the harness's catalog generator pattern), and a CI check fails if a slot's props change without a version bump.

5.8 Editions as plugin sets (D428)Copy Anchor Link

D220 stands: everything a single organisation needs to self-host is open, and the console's multi-tenant, hosted and billing parts stay in the private loam-cloud and loam-platform repositories. In plugin terms:

The extension points the open host offers, and the only things this document fixes about the hosted set:

The open host has no knowledge of the private plugins, and this repository never depends on them. Today's loam-cloud console is a separate Next.js app (with Clerk, which the Authentik ruling retires) and placeholder pages; whether it moves onto this host as a set of private plugins is Q436.

5.9 What the browser console needs to changeCopy Anchor Link

The console on main (web/apps/console, Vite 8, React 19, React Router 8, openapi-fetch) is already a static SPA, so it embeds in Tauri. AP1a turns it into the host plus plugins and fixes what blocks the desktop: baseUrl: window.location.origin in src/api/client.ts and the raw fetch('/v1/…') become the api and transport services; the hard-coded /ui in window.location.assign calls (pages/auth.tsx) becomes router navigation; the /ui basename and Vite base become build options; the cookie-and-CSRF session stays for the browser, and the desktop uses bearer tokens through the bridge (which needs GET /api/v1/session to accept a bearer and return the principal; an auth-plan item, §16).

6. The desktop shell (D429–D432)Copy Anchor Link

6.1 ShapeCopy Anchor Link

One Tauri 2.12 window (verified 2026-10-01) loads the bundled console with the desktop set. The Rust host (loams-desktop, its own Cargo workspace under web/apps/desktop/src-tauri, not part of the engine workspace) owns everything privileged: the CLI, the network, credentials, the tray, deep links, updates and logs. It exposes them to the console only as typed commands, which @loams/platform-tauri turns into cordis services.

6.2 Stacks through the CLI (D429)Copy Anchor Link

The harness's host spawns one fixed runtime. Loam's desktop manages any number of stacks, and the CLI already does that well: stack.toml, the engine registry, port blocks, /ready polling, setsid, log rotation (§30 §8). Re-implementing it in the app would give two supervisors of the same directories. So:

• The sidecar is the loams binary, the standard variant (§30 D286), bundled as externalBin (binaries/loams-<target-triple>). Bundling costs tens of MB (estimate; Q428 asks whether to download it on first run instead).
• Every stack action is loams stack <verb> --output json, parsed by D283's contract: one JSON document on stdout, one error object on stderr, the exit code classified (0 ok … 9 integrity, 130 interrupted). Children run in their own process group with no TTY, LOAM_NO_UPDATE_CHECK=1 and a timeout.
• LOAM_HOME is shared (default ~/.loam), so a stack created in a terminal appears in the app within one poll, and the other way round.
• Stacks outlive the app, as they outlive a terminal. The tray lists running stacks. A setting stops the stacks the app started on quit (default off, Q429).
• The app adds a restart policy the CLI lacks: a keep_running stack reported crashed restarts with backoff 1 s … 30 s, at most 5 times in 10 minutes, then stays crashed with its log tail.
• Creation and deletion stay in the terminal in AP1. stack create (it can download variants and touch disks) and stack delete --yes are shown as exact commands to copy. Start, stop, restart, upgrade and logs are buttons.
• "Add loams to PATH" links ~/.loam/bin/loams to the bundled binary and writes receipt.json with install_method: "desktop". loams self-update refuses that install (exit 6 managed_install, hint "update Loams Desktop"), which amends D294.

Windows has no server variant (§30 Q285), so the desktop on Windows is remote-only: it signs in to Cloud or self-hosted instances and has no stacks page (Q437).

6.3 Capability lockdown (D430)Copy Anchor Link

6.4 The network bridge (D430)Copy Anchor Link

Three ways a webview can reach a Loam instance were considered:

tauriFetch implements the standard fetch signature, so connect-es (createConnectTransport({ fetch: tauriFetch })) and openapi-fetch use it unchanged. The Rust side allows only origins in the active environment's endpoint set, adds Authorization: Bearer (and a DPoP proof once Q438 lands), strips Cookie, Authorization and Proxy-* headers set by JavaScript, uses HTTP/2 when the server offers it, and pins the TLS key for environments that came from a pairing (§7.2.3). Credentials travel only over HTTPS: a request to a non-loopback origin over plain http is refused before any credential is attached; unauthenticated http to loopback (local stacks, D111) keeps working. Redirects never carry credentials to a new origin: a 3xx to the same origin and scheme is followed at most 3 times; a redirect to another origin, or from https to http, is not followed and reaches JavaScript as an error, so no bearer or DPoP proof is ever sent to a location the allowlist did not admit. The phones' clients do the same (followRedirects(false) on OkHttp, a refusing redirect delegate on URLSession). AP1 Task 0's spike measures throughput and memory.

6.5 Sign-in and credentials (D431)Copy Anchor Link

• Identity provider: Authentik, open-source edition (owner ruling, 2026-10-01). GetInstance names the instance's Authentik issuer and the Loam gateway's token endpoint.
• Flow: OIDC authorization code with PKCE at Authentik, started from the desktop and completed in the system browser, so whatever Authentik is configured with (passwords, TOTP, WebAuthn, upstream SSO) works; redirect to http://127.0.0.1:<port 0>/callback (RFC 8252 §7.3), one request accepted, state and nonce checked. Public client id loams-desktop, registered as an Authentik application for the instance. The desktop then exchanges Authentik's token at the Loam gateway (RFC 8693, §19 §5.2) for Loam's access and refresh tokens; Authentik's own tokens are not kept. tauri-plugin-oauth 2.1 provides the loopback listener if its licence passes deny.toml (verify); otherwise it is about 60 lines.
• Storage: the refresh token in the OS keychain through keyring 4.2 (macOS Keychain, Windows Credential Manager, Linux Secret Service), one entry per (instance_id, principal_id); the access token in memory; rotation on every refresh. tauri-plugin-stronghold is deprecated and will not exist in Tauri v3 (plugins-workspace#3494, verified 2026-10-01). Without a Secret Service on Linux, sign-in lasts the session only and the UI says so.
• Local stacks before the auth plan report auth: none (D111) and need no sign-in. After it, a local stack is signed in to like any instance.
• Approvals on the desktop use step-up SESSION: a session older than 5 minutes re-authenticates at Authentik in the browser (max_age=0) before a decision is sent (D435). A desktop device key with OS user presence (Touch ID through Keychain access control, Windows Hello) is a later option.

6.6 Updates, signing and packaging (D432)Copy Anchor Link

6.7 Deep links, single instance, tray and logs (D432)Copy Anchor Link

• loams:// links: open/<env>/<console path>, approvals/<id>, stacks/<name>. Rust parses them against an allowlist and hands the console a typed route through the desktop/deeplink event. No deep link performs an action; it can only navigate. tauri-plugin-deep-link 2.6 registers the scheme at install (macOS has no runtime registration), and tauri-plugin-single-instance 2.5 with its deep-link feature forwards links to the running instance.
• The tray shows stacks with their state and the number of pending approvals.
• Logs go to the app log directory, rotating at 10 MB, 5 files, and the startup failure page names that path.

7. The mobile apps (D433–D437)Copy Anchor Link

7.1 Shared rulesCopy Anchor Link

• Native UI and native clients. SwiftUI (iOS 17+) with connect-swift 1.2 (stable; URLSessionHTTPClient), and Compose with connect-kotlin 0.9 (beta; ConnectOkHttpClient, javalite). Neither app uses a web view except the system browser for sign-in.
• Protocol: Connect, binary codec, unary and server-streaming only (§8.3). gRPC would need trailers, which URLSession lacks (connect-swift's gRPC needs ConnectNIO); nothing requires it.
• Module split from the harness (§3.2): a pure core (pairing payload, decision canonicalization, watch resume, unsealing, error reasons) testable without a device; a data layer (clients, trust, keys, tokens, cache); push; UI; conformance.
• Same screens on both: environments, approvals (list and detail), operations, jobs and runs (when loam.jobs.v1 is served), the inbox, devices and settings. No identity administration.

7.2 Pairing and identity (D434)Copy Anchor Link

Mapping the harness onto §19. The harness's relay issued its own per-device bearer token and pinned its own TLS key. Loam already has an identity system: people sign in at the instance's Authentik (the identity provider, owner ruling 2026-10-01), and the Loam gateway issues Loam tokens signed by the instance's Ed25519 key, with a JWKS and revocation through the ControlStore change feed (§19 §5). So:

7.2.1 The QR payload (v1)Copy Anchor Link

{"v":1,"kind":"loams-pair","issuer":"https://loam.acme.example","instance_id":"01J9Z3…",
 "spki":["Rk9PQkFSLi4u…"],"jkt":"NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
 "code":"7JQ2KX4M2ZB6V3NAQ6E5RW2HCA","user_code":"48213977","exp":1790899500}

issuer is the Loam gateway (the authorization server for Loam tokens), not Authentik. spki is null for instances with publicly trusted certificates. code is 128 random bits, single use, valid 5 minutes, bound to the user who created it (DeviceService.CreatePairing); the example's exp is 2026-10-02 00:05 UTC. user_code is the typed alternative to code for the same pairing: the pairing grant accepts either code or user_code (never both), and a pairing is burned after 5 failed user_code attempts, so 8 digits within 5 minutes cannot be guessed (AP0 Task 2). A reader refuses v other than 1, another kind, an expired payload or a non-https issuer.

7.2.2 Three ways to pairCopy Anchor Link

1. QR (primary). The signed-in user opens "Pair a phone" in the console or desktop. The phone scans, pins spki before sending a byte, calls GetInstance, checks instance_id and that the JWKS contains jkt, creates two hardware keys (§7.6, §7.7), and redeems the pairing: POST {issuer}/api/v1/oauth/token with grant_type=urn:loams:params:oauth:grant-type:pairing (an extension grant, RFC 6749 §4.5), code, client_id (loams-ios or loams-android), device_name, platform, decision_jwk (the public key of the decision key), an optional key attestation, and a DPoP header. The answer is {access_token, token_type: "DPoP", expires_in: 3600, refresh_token, device_id}.
2. Browser sign-in at Authentik. ASWebAuthenticationSession or Custom Tabs with PKCE at the instance's Authentik, returning through https://loams.dev/app/auth/callback (universal and app links, Q281). The phone then exchanges Authentik's token at the Loam gateway (RFC 8693) with a DPoP proof and the same device fields, and receives the same DPoP-bound Loam tokens as the QR path.
3. Device code at Authentik (no camera, or a phone that cannot open the browser flow). The phone starts Authentik's device authorization flow (RFC 8628, verify the version that ships it) and shows the user code; the user enters it on the desktop or console, already signed in. Before that the phone connects trusting on first use, shows the gateway's key fingerprint as six words, and the console shows the same six words for the user to compare; the app says this pairing was not pinned in advance (the harness's honesty rule). The result is exchanged at the gateway as in path 2.

All three produce the same Device record. Authentik authenticates the person; the Loam gateway issues and binds the tokens, because DPoP binding, the dev and env claims and revocation are Loam's (§19 §5.3–§5.4). The unified auth plan implements the pairing grant, the exchange, the device record and DPoP binding (Q438); AP0 fixes the contract.

7.2.3 Pins that rotate without re-pairingCopy Anchor Link

The harness's relay minted a new TLS key whenever its addresses changed, which forced every phone to pair again. Loam separates the anchor from the transport key:

• The anchor is jkt. GetInstance returns tls_pins: a JWS signed by that key listing the current and next SPKI hashes. A phone accepts a new TLS key only if a pin set signed by the anchored key announced it.
• When the instance rotates its signing key, its JWKS lists both keys for an overlap period, and GetInstance.key_rotation carries the new key's thumbprint signed by the old key. A phone moves its anchor only along that chain.
• A mismatch is a hard stop ("this server's identity changed"), never a fallback to CA validation.

7.2.4 No relay in track APCopy Anchor Link

dsh-relay terminates TLS on the user's network and sees everything. A hosted relay for Loam would have to be end-to-end (TLS passthrough by SNI, so the relay sees ciphertext only) and is a service with abuse and cost questions of its own. Phones in track AP reach instances that are reachable on the internet: Loam Cloud, or a self-hosted gateway with TLS after the auth plan (D111 keeps M1 listeners on loopback). Teams that keep instances private can use their VPN or a tunnel (Tailscale, Cloudflare Tunnel). Q425 asks whether to build a relay.

7.3 Approvals (D435)Copy Anchor Link

§21 §6.5 defines approval gates: a destructive operation (collection or namespace drop, erasure, restore over live data) or a requires_approval agent action becomes an operation whose first step waits on an approval promise, settled by an approver, timing out after 72 hours. loam.approvals.v1 makes that a service every app shares:

• What an approval shows: a server-rendered summary and detail_lines in the user's locale (so iOS, Android, desktop and push show the same words and new kinds need no app release), the environment and whether it is protected, the requester and the actor chain (an agent acting for a user shows both), the risk, the policy's progress (1 of 2), and the time left.
• Who may decide: the org's approval policy through the Authorizer (§21 §6.5); the requester, or the user an agent acts for, cannot approve their own request by default (Q432).
• A decision needs a proof. DecideApproval carries decision_proof, a compact JWS (ES256 from the Secure Enclave or StrongBox; EdDSA allowed for software keys) over {approval_id, revision, decision, iat, jti}, signed by the device's decision key, which needs biometrics or the device passcode for every signature. The server verifies it against the key registered at pairing, checks revision (a stale card cannot be approved) and jti (no replay). A desktop or browser decision without a device key is accepted when the session is younger than 5 minutes, or when the policy says step_up: none.
• Typed confirmation for the worst cases. A DESTRUCTIVE approval requires typing the target's name, carrying §19 §4's protected-environment rule to the phone. Rejecting requires a reason.
• Not offered: "always allow" (policy changes are console actions, themselves approval-gated in protected environments), decisions from the lock screen without the app, and queued decisions.

7.4 Push notifications (D436)Copy Anchor Link

The constraint. An APNs token-signing key belongs to one Apple developer team (Apple offers team-scoped and topic-specific keys), and a push is accepted only for a topic, the app's bundle id, that the key may send to. A team-scoped key can authorize pushes to every app of that team, so loams-push uses a topic-specific key limited to the Loams app's topics, held only by the gateway; FCM credentials belong to the app's Firebase project. Only the publisher of the store apps can push to them, so a self-hosted instance cannot push directly. Matrix (Sygnal), Mattermost (its push proxy), ntfy (upstream poll_request) and Home Assistant all solve this with a push gateway that the publisher runs (verified 2026-10-01). Loam does the same, with the gateway blind to content:

 engine: CloudEvent io.loams.dev.approval.requested.v1 (or …operation.failed.v1, …job.dead_lettered.v1)
   └─ notifier (a durable function in the engine): per-user projection, preferences, quiet hours
        ├─ inbox row (loam.notifications.v1, kept 30 days, estimate)
        └─ per device push target: seal(Notification) with HPKE to the device's X25519 key,
             AAD = instance_id ‖ notification_id  →  POST https://push.loams.dev/v1/notify
                                                      {target, app_id, sealed, collapse_id, priority, ttl}
 loams-push gateway: instance credential check, per-instance rate limit → APNs (token auth) / FCM HTTP v1
 device: NSE (iOS) or FirebaseMessagingService (Android) unseals → shows title and body → tap → app fetches details over Connect

• What the gateway sees: the device token, the app id, the instance id, sizes and timing. Not the title, body, environment or approval.
• What Apple and Google see: the same, plus a generic alert text ("New activity in Loams") that the extension replaces after unsealing. If unsealing fails, the generic text stays and the app syncs its inbox.
• HPKE (RFC 9180, DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, ChaCha20-Poly1305): CryptoKit's HPKE on iOS 17 and Tink on Android. The sealed body stays under 2 KB to fit APNs' 4 KB limit; details are fetched.
• The gateway is open source (loams-push, a small Rust service in this repository, AP4) and Loam operates the instance the store apps use (an operational service in loam-platform, D220). Self-hosters who publish their own app builds run their own gateway with their own keys, as Mattermost requires. Instances register with the gateway for a credential; abuse limits are per instance (Q424).
• Android without Google services: a unifiedpush flavor; the instance posts the same sealed payload to the user's UnifiedPush endpoint (RFC 8030), with no gateway (Q439).
• Desktop: no push service; the running app holds WatchApprovals and raises native notifications (AP1 Task 8).
• Categories: approvals (high priority; actionable with Review, which opens the approval and asks for biometrics), operations, jobs, runs, security (device added, device revoked). Approvals may bypass quiet hours (a user preference, default on).

7.5 Offline and background (D437)Copy Anchor Link

7.6 Android specificsCopy Anchor Link

Keystore keys per instance, EC P-256, StrongBox when present: dpop-<instance> without user authentication (background refresh works) and decide-<instance> with setUserAuthenticationRequired(true), strong biometrics or device credential for every use, and invalidation on biometric enrolment changes; signing through BiometricPrompt with a CryptoObject. The refresh token is AES-GCM-encrypted with a Keystore key in DataStore (the harness's RelayCredentialStore pattern). cleartextTrafficPermitted="false", no user CAs, allowBackup="false", FLAG_SECURE on approval and pairing screens. Flavors fcm and unifiedpush. Details: AP2.

7.7 iOS specificsCopy Anchor Link

Secure Enclave P-256 keys per instance: dpop (.privateKeyUsage) and decide (.privateKeyUsage + .biometryCurrentSet, or .userPresence without biometry), so DPoP and decision proofs are ES256. Keychain items AfterFirstUnlockThisDeviceOnly, never synchronizable, shared with the Notification Service Extension through an access group. ATS on with no exceptions outside Debug; pins evaluated in the URLSession delegate. Categories with a REVIEW action that opens the app (.foreground, .authenticationRequired). Details: AP3.

7.8 Kotlin Multiplatform: evaluated, not recommended (D433)Copy Anchor Link

Recommendation: no KMP. The protos are the shared contract; golden fixtures (canonical DecisionClaims bytes, pairing payloads, sealed notifications) and the conformance scenarios keep the two cores equal, and LoamsCore also builds on Linux so the fixtures run in Linux CI (AP3 Ruling 6). Revisit if connect-kotlin gains KMP support and the shared logic grows past roughly a third of either app.

8. The proto surface (D438)Copy Anchor Link

8.1 What each app needs, and what existsCopy Anchor Link

8.2 The new packages (AP0)Copy Anchor Link

Package names stay loam.* to match loam.live.v1 and loam.stream.v1; whether the rename moves every proto package to loams.* before the first app release is Q422 (Connect URL paths contain the package, so it is cheap before a release and breaking after one).

8.3 Protocol choicesCopy Anchor Link

8.4 GenerationCopy Anchor Link

buf generates every client from proto/: protobuf-es 2 (@bufbuild/protobuf 2.16, used by @connectrpc/connect 2.2) into web/packages/proto (@loams/proto, committed, checked for drift in CI); buf.build/apple/swift + buf.build/connectrpc/swift (GenerateAsyncMethods) and buf.build/protocolbuffers/java (lite) + buf.build/connectrpc/kotlin for the mobile repository, which generates at build time from a pinned git ref of this repository. The server keeps D128's generation (buffa and connectrpc-build in build.rs). buf breaking is enforced for the new packages.

9. Repository layout (D439)Copy Anchor Link

Recommendation: desktop and console in this repository; both phone apps in one new repository, ostrium-labs/loams-mobile.

ostrium-labs/loams (this repository)
├── proto/loam/{instance,devices,approvals,operations,notifications,errors}/v1/   (AP0)
├── crates/operon-apps-mock/                       (AP0; scenarios shared by every app)
├── crates/loams-push/                             (AP4, not yet planned)
├── web/packages/{console-host,slots,forms,proto,platform-web,platform-tauri,ui}/
├── web/plugins/{shell,identity,agents,keys,audit,collections,jobs,durable,live,flow,connectors,gateway,approvals,devices,stacks,mcp,plugins}/
├── web/apps/console/                              (the browser build the engine embeds at /ui)
└── web/apps/desktop/ + src-tauri/                 (its own Cargo workspace and lockfile)

ostrium-labs/loams-mobile
├── android/  (core, proto, data, push, app, conformance)
├── ios/      (Packages/LoamsCore, LoamsProto, LoamsData; Loams app; LoamsNotificationService; LoamsConformance)
├── conformance/proto-ref.lock                     (this repository's git ref both apps generate from)
└── buf.gen.swift.yaml, buf.gen.kotlin.yaml        (copies of AP0's templates)

10. Open-core placement (D220)Copy Anchor Link

Nothing here makes this repository depend on loam-platform. A self-hoster gets every app, every open plugin and the gateway code; what they cannot get from us is our APNs key, which no one can share.

11. Security modelCopy Anchor Link

12. TestingCopy Anchor Link

The harness's three layers, shared across apps:

1. Pure cores with golden fixtures. Android :core and iOS LoamsCore test pairing payloads, error reasons, watch resume, decision canonicalization and unsealing against the same fixture files, which operon-apps-mock also uses. A descriptor-set hash test ties each app to conformance/proto-ref.lock.
2. A shared, scriptable mock. operon-apps-mock (AP0) serves every AP0 service over Connect, gRPC and gRPC-Web, is stateful, verifies decision proofs for real, and replays YAML scenarios (approvals-basic, approval-expiry, stream-drop-and-resume, device-revoked, operation-progress, notification-burst). Its validation is the server's acceptance module, so it refuses what the server will refuse.
3. Conformance per app. Each app runs every scenario and an endpoint catalogue (a typed business error counts as a pass) on the JVM or the macOS host, with no emulator or simulator for the network layer.

Plus, per surface: Vitest for plugins with fake services, Playwright for the browser console, tauri-driver with WebdriverIO on Linux and Windows for the desktop, Compose UI tests and screenshots, XCUITest. Security tests are named in each plan's Review Focus: the capability allowlist, the secret canary, deep-link property tests, pin bypass tests, and iframe_cannot_reach_network.

13. Roadmap: track AP (D439)Copy Anchor Link

Order: AP0 first; AP1a and the two phone plans in parallel; AP1 after AP1a's host. Everything runs against the mock until AP4; nothing is published before D33's rename and the move to ostrium-labs.

14. RisksCopy Anchor Link

15. Open questionsCopy Anchor Link

16. Contradictions with earlier decisions, and how they are resolvedCopy Anchor Link

17. SourcesCopy Anchor Link

Read on 2026-10-01 and 2026-10-02.

• Harness desktop (dina-kar/deepseek-harness-desktop at 2d1b505): LICENSE, README.md, AGENTS.md, THIRD_PARTY_NOTICES.md, apps/desktop/src-tauri/{src/lib.rs,tauri.conf.json,tauri.macos.conf.json,capabilities/default.json,Cargo.toml}, apps/desktop/scripts/prepare-runtime.mjs, .agents/notes/implemented/architecture/2026-08-14-tauri-desktop-sidecar-host.md and 2026-07-23-client-plugin-loading-model.md, packages/client/connection/src/api-request-trust.ts, packages/client/web/src/boot.tsx, packages/client/ui-slots, packages/bundle/web-app/cordis.patch.yml, packages/boot/app-boot/src/profile.ts, vendor/README.md, vendor/loader/src/config/{entry.ts,tree.ts,utils.ts,isolate.ts}, vendor/cordis/src/registry.ts, scripts/gen-cordis-catalog.ts, docs/api-gateway.md, tsconfig*.json.
• Harness mobile (dina-kar/deepseek-harness-mobile at 68b6c2f): LICENSE, README.md, THIRD_PARTY_NOTICES.md, settings.gradle.kts, gradle/libs.versions.toml, docs/{PROTOCOL.md,SECURITY.md,COMPATIBILITY.md}, core/.../wire/{RelayPairing.kt,RelayTls.kt,ConnectionLoop.kt,RemoteStreamMux.kt}, app/.../data/{SessionStore.kt,RelayCredentialStore.kt,HarnessSessionStore.kt}, app/.../notify/*, app/src/main/res/xml/network_security_config.xml, mock-harness/, conformance/, .github/workflows/ci.yml.
• cordis: github.com/cordiverse/cordis (licence, releases v4.0.0-rc.7 to rc.10, contributors); npm cordis, @cordisjs/plugin-loader, @cordisjs/plugin-include, @cordisjs/plugin-hmr, @cordisjs/plugin-webui, @koishijs/plugin-console (licence metadata).
• Connect: github.com/connectrpc/connect-es (2.2.0), connectrpc.com/docs/{faq,node/using-clients,swift/using-clients,kotlin/using-clients,kotlin/getting-started}; github.com/connectrpc/connect-swift (1.2.3, Package.swift, conformance configs); github.com/connectrpc/connect-kotlin (0.9.0, issue #140); github.com/connectrpc/connect-rust and buf.build/blog/connect-rust-joins-the-connect-project; connectrpc 0.9.1 on crates.io; github.com/connectrpc/connect-query-es (2.3.1); npm @bufbuild/protobuf 2.16.0.
• Tauri: github.com/tauri-apps/tauri releases (2.12.1); v2.tauri.app/plugin/{updater,deep-linking,single-instance}, v2.tauri.app/develop/sidecar, v2.tauri.app/distribute/sign/{macos,windows}, v2.tauri.app/blog/tauri-20; tauri-apps/plugins-workspace#3494 (Stronghold); github.com/tauri-apps/tauri-action (1.0.0); github.com/FabianLars/tauri-plugin-oauth (2.1.0); crates.io keyring (4.2.0).
• Mobile platform: Apple's "Establishing a token-based connection to APNs", the Apple developer forum thread on URLSession trailers; github.com/square/okhttp; kotlinlang.org/docs/{components-stability,native-swift-export}; github.com/touchlab/SKIE releases; unifiedpush.org (spec).
• Push gateways: github.com/element-hq/sygnal; docs.mattermost.com/deploy/mobile/host-your-own-push-proxy-service; docs.ntfy.sh/config; companion.home-assistant.io/docs/notifications/{notification-details,notification-local}.
• Proxies: developers.cloudflare.com/fundamentals/reference/connection-limits and the 524 error page; docs.aws.amazon.com/elasticloadbalancing/latest/application/edit-load-balancer-attributes.
• Loam: §19, §21 (§6.4, §6.5), §26 (D206, §6.6), docs/open-core.md (D220, D221), §30 and its pending log (branch cli-design), §32–§33 and their pending log (branch flow-fabric-house-design), §34 (branch gateway-runtime-design); web/ on main at 9eaddae (apps/console/{vite.config.ts,src/main.tsx,src/api/client.ts,src/session.tsx,src/pages/auth.tsx}, packages/ui), api/console/openapi.json, crates/operon-console-mock, buf.yaml, buf.gen.yaml, proto/loam/live/v1/live.proto, crates/operon-stream-grpc/proto/loam/stream/v1/stream.proto; loam-cloud at c738de7 (next.config.*, proxy.ts, app/(console)/, lib/console.ts, lib/integrations.ts; read only).