@abot-ai/socket 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## 0.2.0 - 2026-11-14
+
+### Added
+
+- Recover pending tool approvals after client reconnects and Socket or runtime
+  restarts, using persistent request ownership and runtime-authoritative waits.
+- Continue and approve requests started on the computer from a paired client,
+  after the current runtime confirms the exact session and request. Existing
+  ownership is never reassigned to another owner or session.
+- Open and chat with the runtime's SPARK companion through compatible clients,
+  using its configured model and permissions. This does not expose SPARK
+  management, settings writes or proactive activity.
+
+### Fixed
+
+- Restore scoped live request delivery when recovering an owned request, without
+  rerunning it or reconstructing events missed during disconnection.
+
+### Upgrade notes
+
+- New features require a compatible client and the selected runtime's
+  `request_approvals_v1` or `spark_chat_v1` capability. Legacy chat and live-only
+  approval behavior remain available when the new capabilities are not used.
+- Private SQLite state upgrades transactionally from schema v1, v2 or v3 to v4.
+  Existing pairing, device credentials, notification metadata, preview keys and
+  delivery queues are preserved. Stop the service and back up its private state
+  and matching code before upgrading; rollback requires both the pre-upgrade
+  state and old code. See [Migration](docs/MIGRATION.md).
+- Node.js 24 or later remains required. Dependencies and the HTTP/WebSocket
+  protocol envelope are unchanged.
+
+## 0.1.0 - 2026-11-11
+
+- Initial MIT-licensed npm release with authenticated runtime relay, QR/manual
+  pairing, device revocation, notification delivery and optional encrypted
+  previews, and CLI setup/deployment guidance.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dor Shitrit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# ABot Socket
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A self-hosted chat relay between a native ABot client and your ABot Runtime
+instances. You operate the relay, pair your devices, and connect your own
+computers. The relay does not require an ABot-hosted account or backend.
+
+The source is available under the [MIT license](LICENSE). Install the versioned
+`@abot-ai/socket` package from npm, or build a local tarball from source.
+See the [changelog](CHANGELOG.md) for release notes and upgrade requirements.
+
+## Install and prepare
+
+Start with [Installation and first connection](docs/INSTALLATION.md), the consumer
+guide for installing the command, preparing a server, connecting a runtime and
+pairing the app by QR or manual entry.
+
+```sh
+npm install --global @abot-ai/socket@0.2.0
+abot-socket setup
+```
+
+The command requires Node.js 24 or later. Its terminal wizard creates private
+configuration/state and, on Linux, reviewable systemd/HTTPS proxy files. The
+operator supplies DNS, TLS, service activation and the runtime's bridge settings.
+Neither npm installation nor setup activates those services; no install hook runs.
+
+- [Installation](docs/INSTALLATION.md): wizard, defaults, runtime connection and pairing.
+- [Deployment](docs/DEPLOYMENT.md): explicit Linux service and HTTPS activation.
+- [Self-hosting](docs/SELF-HOSTING.md): configuration, operation and the proxy trust boundary.
+- [Protocol](docs/PROTOCOL.md): pairing API and existing runtime bridge.
+- [Security](docs/SECURITY.md): authentication, trust boundaries and limitations.
+- [Migration](docs/MIGRATION.md): moving an existing installation deliberately.
+- [App review preparation](docs/APP-REVIEW.md): a separate review installation,
+  protected renewable pairing access and the remaining deployment/device checks.
+
+`abot-socket start` runs the relay in the foreground. `abot-socket doctor` checks
+public HTTPS relay health without credentials; runtime readiness is verified in
+the paired app. `abot-socket pair` creates fresh one-time pairing details and
+displays a private QR in a capable terminal. Scanner-enabled clients can scan it
+and confirm the server address; manual entry remains available.
+
+## Scope
+
+One installation represents one owner, with up to 10 paired devices and 16
+runtimes. Pairing requires a six-digit code and a separate random temporary key
+created locally by the operator. Both expire after five minutes or one successful
+use. There is no email delivery or central authentication provider.
+
+ABot App scans the private pairing QR and asks you to confirm its server address.
+Manual code, HTTPS URL and temporary-key entry remains available. The app receives
+its own device credential; never copy the runtime credential into the app.
+
+The relay supports chat, steering, tool approvals, runtime history, model selection
+and attachments through the runtime Bridge. Compatible clients can recover pending
+approvals across reconnects and restarts, continue requests created on their
+computer, and open the runtime's SPARK companion chat. SPARK model settings and
+permissions remain runtime-owned; management and proactive activity are not exposed.
+These features require the selected runtime to advertise `request_approvals_v1`
+or `spark_chat_v1` respectively; older runtimes retain the legacy chat path.
+The relay does not execute models or store conversation history. Configure the
+runtime's existing Bridge; this installer does not modify runtime source.
+
+Device sessions last up to 30 days without sliding renewal and survive restarts
+in a private SQLite database. Operators can list and revoke devices locally.
+The device-scoped notification inbox records completion, failure and observed
+approval events for routed requests. Notifications belong to the initiating device
+or the device that first recovers a computer-created request through the verified
+ownership flow; later recovery by another device does not transfer that inbox.
+Push delivery is off by default;
+operators may configure their own FCM sender or an explicitly trusted ABot push
+gateway. Notifications are generic by default. An optional per-device encrypted
+preview can show a bounded final-answer excerpt; the gateway/provider never gets
+the preview key or plaintext. The app remains usable without push.
+Cancellation and reconstruction of events missed while disconnected are not
+implemented. Approval recovery queries current runtime state and restores scoped
+live delivery; it never automatically resends an interrupted request. The relay
+host is trusted and can read routed content; transport encryption is not end-to-end
+encryption.
+
+Notification metadata, pending deliveries and durable request ownership share the
+private SQLite state. Upgrading migrates schema v1, v2 or v3 to v4 without replacing
+paired devices. Back up the private state and matching code while stopped before
+upgrading. Older binaries cannot open v4; rollback requires the matching state
+backup and old code together. See [migration](docs/MIGRATION.md#durable-request-ownership-schema-upgrade)
+and [notification protocol and delivery](docs/PROTOCOL.md#notifications).
+
+## Source layout
+
+`bin/abot-socket.mjs` is the installed entry point; `src/main.mjs` starts a
+configured relay. The source modules are grouped by responsibility:
+
+| Directory | Owns |
+| --- | --- |
+| `src/cli/`, `src/setup/` | Command dispatch, operator output and new-installation preparation. |
+| `src/config/`, `src/deployment/` | Private configuration validation and reviewable service/proxy plans. |
+| `src/auth/`, `src/pairing/` | Durable device credentials, revocation and one-use pairing/QR. |
+| `src/transport/`, `src/protocol/` | HTTP/WebSocket boundary, limits and allowed client message shapes. |
+| `src/relay/` | Runtime routing, correlations, request ownership and session operations. |
+| `src/notifications/` | Device inbox/outbox, delivery adapters, gateway and encrypted previews. |
+| `src/review/` | Separate app-review installation and protected pairing portal. |
+
+## Local validation
+
+From the development checkout, install the locked dependencies and run the local tests:
+
+```sh
+npm ci --omit=optional --ignore-scripts
+npm test
+```
+
+Runtime dependencies are pinned `ws` for transport and `qrcode-generator` for
+local pairing QR generation; the latter has no runtime dependencies. Source tests and
+package-verification scripts are not shipped inside the npm consumer package.
+
+To inspect the exact distribution files before installing a source-built package:
+
+```sh
+npm pack --ignore-scripts --json > /tmp/abot-socket-pack.json
+npm run check-package -- /tmp/abot-socket-pack.json
+```
+
+The tarball contains an explicit allowlist of runtime modules and consumer docs.
+Keep credentials, machine configuration, state, logs and private support reports
+outside the checkout. Never attach pairing codes or QR images to a public issue.
+
+Tests use dummy identities and mock runtime peers. The transport tests
+open loopback HTTP and WebSocket listeners; they do not connect to a live runtime
+or send email. Run them only in an environment permitted for that local traffic.
+Passing these tests does not establish proxy correctness,
+or compatibility with a separately installed client/runtime version.

package/bin/abot-socket.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+// Check before loading node:sqlite so unsupported Node versions get a useful error.
+if (Number(process.versions.node.split('.')[0]) < 24) {
+  console.error('ABot Socket requires Node.js 24 or later. Install a supported Node.js version first.');
+  process.exitCode = 1;
+} else {
+  try {
+    const { runEntry } = await import('../src/cli/cli-entry.mjs');
+    process.exitCode = await runEntry(process.argv.slice(2));
+  } catch {
+    console.error('ABot Socket could not complete the command. Check the local configuration and installation.');
+    process.exitCode = 1;
+  }
+}

package/config.example.json

@@ -0,0 +1,14 @@
+{
+  "publicOrigin": "https://socket.example.invalid",
+  "port": 8788,
+  "runtimeGrants": [
+    {
+      "runtimeId": "workstation",
+      "tokenSha256": "REPLACE_WITH_SHA256_OF_A_NEW_RUNTIME_TOKEN",
+      "allowedModes": [
+        "ask"
+      ]
+    }
+  ],
+  "stateDirectory": "./state"
+}

package/docs/APP-REVIEW.md

@@ -0,0 +1,184 @@
+# Preparing a dedicated app-review installation
+
+This guide prepares renewable access to an isolated review Socket using the
+ordinary app pairing protocol. It does not deploy services, configure a model,
+publish a package or establish App Store readiness. Actual hosting and signed
+device checks remain required; installing the package does not complete them.
+
+Apple requests full app access, necessary resources such as pairing QR codes,
+and backend services that remain live during review. See the current
+[App Review Guidelines](https://developer.apple.com/app-store/review/guidelines/#before-you-submit),
+including sections 2.1 and 2.3.1. Reviewers should not have to contact the developer
+for each new five-minute code.
+
+## 1. Prepare a fresh installation
+
+Use Node.js 24 or later and an explicitly installed package version. Choose a
+new, private output directory outside source control. Its parent must already
+exist; the output directory must not. Run setup as the account that will own and
+run both processes; the private files are deliberately rejected for another owner.
+Replace these reserved example origins
+with the dedicated HTTPS origins you intend to operate:
+
+```sh
+abot-socket review-setup \
+  --output /srv/abot-review \
+  --origin https://demo.example.test \
+  --runtime-id review-demo \
+  --review-origin https://review.example.test \
+  --port 8788 \
+  --review-port 8789
+```
+
+The Socket and reviewer portal require distinct HTTPS origins and listener
+ports. The default ports are 8788 and 8789. Pick unused ports if other services
+share the host. These examples do not authorize or perform changes to those
+services.
+
+The command creates a separate installation rather than attaching review access
+to an existing Socket:
+
+| Output | Purpose |
+| --- | --- |
+| `config.json` | Configuration for the dedicated review Socket. |
+| `runtime-connection.json` | Private bridge URL, runtime identity and runtime secret. |
+| `state/` | Dedicated Socket database, ownership and review-installation metadata. |
+| `review-portal.json` | Private portal configuration bound to this review installation. |
+| `review-access.txt` | Portal URL, reviewer username and generated stable password. |
+
+The directory is private and the credential/configuration files use mode 0600.
+Console output identifies the files; do not copy their secret contents into
+logs, source, screenshots or a public support page. Keep this installation's
+state separate from production and from any push gateway database.
+
+The portal verifies its fresh-installation marker and database owner as well as
+the bound Socket identity: origin, state directory and runtime credentials.
+Changing those identity fields makes the binding invalid. Do not edit a marker
+or credential hash to attach the portal to another installation. This workflow
+is not a migration or a generic pairing endpoint for an existing personal server.
+
+## 2. Configure the review runtime and optional push
+
+Privately transfer `runtime-connection.json` only to the dedicated runtime host.
+Use that runtime's existing bridge configuration to connect it; never enter the
+runtime secret into the app or disclose it to reviewers. Configure a working
+model and benign sample resources on that runtime. No runtime source changes
+are required by this setup.
+
+Provide enough access to exercise the app's normal features while isolating the
+review workspace from personal files, accounts, credentials and production
+administration. Do not rely on a home Mac remaining awake or on a developer
+manually maintaining the connection during review. Hosting, model capacity and
+availability are operator responsibilities.
+
+The app uses the same submitted binary and standard behavior. There is no
+reviewer-specific client mode, fake chat implementation or hidden feature switch.
+Document the normal model/tool capabilities offered by this workspace.
+
+Remote push remains disabled unless configured deliberately. If the submitted
+app offers push, configure the dedicated Socket's appropriate delivery mode and
+provider/gateway through the normal configuration described in
+[Self-hosting](SELF-HOSTING.md) and [Deployment](DEPLOYMENT.md#optional-notification-gateway).
+Keep sender credentials and gateway configuration private. Permitted operational
+changes such as notification delivery and allowed permission modes do not replace
+the installation's bound identity. Restart the affected process after a deliberate
+configuration change, then verify the complete signed-device flow. Setup does not
+prove push delivery or provision a sender service.
+
+## 3. Prepare separate HTTPS forwarding
+
+Run each process behind its own HTTPS origin, forwarding only to the corresponding
+loopback listener. Use valid certificates and separate proxy routes. Keep the
+relay's WebSocket upgrade support; the reviewer portal is a separate HTTP service.
+
+The direct HTTPS proxy must:
+
+- Preserve `Host` for the intended public origin, and pass `Authorization` and
+  `Origin` without rewriting their meaning.
+- Remove untrusted incoming `X-Forwarded-Proto` and `X-Socket-Client-IP`, then set
+  the verified HTTPS protocol and the actual connection client's IP itself.
+  Never trust a client-supplied forwarding header.
+- Disable caching for the reviewer portal, including authenticated pages and
+  QR responses. Do not enable CDN caching for this origin.
+- Disable proxy access/body/header logging and tracing for the reviewer portal.
+  Ensure upstream/CDN logging cannot record credentials, generated pairing
+  bundles or responses. Do not introduce secret logging in the relay either.
+
+See [the proxy trust boundary](SELF-HOSTING.md#3-configure-https-and-the-proxy-boundary).
+Additional proxies or a CDN require a separately validated trusted-peer policy;
+copying their incoming IP headers is not sufficient. Configuring DNS, TLS,
+firewalls, service users and process supervision is separate deployment work.
+No setup command activates or reloads those components.
+
+## 4. Start and verify deliberately
+
+After the hosting configuration has been reviewed, run the two processes with
+the same Socket configuration path, in separate supervised processes or terminals:
+
+```sh
+abot-socket start --config /srv/abot-review/config.json
+```
+
+```sh
+abot-socket review-portal --config /srv/abot-review/config.json
+```
+
+The second command derives the fixed sibling `review-portal.json`; do not pass
+that file as the `--config` argument. Keep the separate portal origin and port
+chosen during setup.
+
+Open the protected `/review` webpage on the portal origin using the access
+details in `review-access.txt` (for example, `https://review.example.test/review`).
+Generate a fresh standard QR and pair the real app. The QR
+lasts five minutes and is single-use. Generating another QR replaces the pending
+one, while devices already paired successfully remain authorized.
+
+Display the webpage on another screen for camera scanning. A reviewer using one
+device can instead copy the displayed six-digit code, Socket URL and temporary
+pairing key into the app's normal manual flow. The QR is not an app-opening link.
+The app also requires the device's own passcode or biometric authentication;
+this is separate from the webpage's reviewer login and Socket pairing code.
+
+Put actual reviewer access details only in private App Review Information in
+App Store Connect. Keep the portal login usable throughout review and allow
+repeat pairing without developer intervention. Monitor capacity so additional
+review devices can pair; revoke only obsolete review devices deliberately.
+
+## 5. Readiness record
+
+Before submitting the app, verify and record:
+
+- Both public HTTPS origins, their proxy boundaries and the protected portal
+  work externally; no secret appears in caches or operational logs.
+- Fresh, expired, replaced and already-used pairing codes behave correctly.
+  Replacing a pending code leaves paired devices usable.
+- The intended runtime is online, the configured model completes real chat
+  requests, and history, attachments, tool activity and approvals work with the
+  submitted app. An HTTP health check proves neither runtime nor model readiness.
+- The runtime and review files are isolated from personal data, and availability
+  does not depend on a home computer or developer attendance.
+- Device authentication, background return, camera permissions and manual
+  pairing work on the actual supported Apple devices and signed build.
+- Any advertised push capability is configured and verified end to end,
+  including permission denial, background delivery and authenticated tap routing.
+- App privacy disclosures describe actual Socket, runtime, model-provider,
+  Firebase/APNs and gateway traffic. User-controlled hosting is not a substitute
+  for verifying those data flows.
+
+No deployment, live runtime/model test, notification send, account operation or
+submission is implied by this guide. Keep readiness evidence and actual access
+details outside the source repository.
+
+## 6. End or renew review access
+
+Keep both services and the runtime available until the review and any follow-up
+checks finish. Afterwards, stopping the portal prevents new reviewer pairings;
+it does not revoke devices that have already paired. Inspect those devices with
+`abot-socket devices --config /srv/abot-review/config.json` and revoke obsolete
+ones with `abot-socket revoke <device-id> --config /srv/abot-review/config.json`.
+Stop the dedicated Socket/runtime as well when the demo is no longer needed.
+
+The reviewer password remains stable until the installation is retired. If it
+needs replacement, prepare a new dedicated installation and replace the private
+review instructions; do not weaken checks or reuse a production configuration.
+Retiring or deleting actual hosted resources is a separate operator action.

package/docs/DEPLOYMENT.md

@@ -0,0 +1,124 @@
+# Preparing a Linux deployment
+
+The deployment command creates files for operator review. It does not install
+packages, enable services, reload a proxy, obtain certificates or change system
+configuration. The existing operating-system user and proxy remain your choice.
+Begin with [Installation](INSTALLATION.md) to install the package and
+prepare private state; this guide is the subsequent service/HTTPS step.
+
+After creating the private installation, prepare a plan on the Linux host where
+the package is persistently installed. Run this as the installation owner; the
+optional --user value must match that current unprivileged account:
+
+```sh
+abot-socket deployment --config /srv/abot/config.json \
+  --output /srv/abot/deployment-plan --user abot --proxy nginx \
+  --certificate /etc/tls/socket/fullchain.pem \
+  --private-key /etc/tls/socket/private.key
+```
+
+Use `--proxy apache` for Apache 2.4.47 or later. Use `--proxy none` if HTTPS is
+already configured; certificate/key arguments are then unnecessary. The output
+directory must not exist. Its parent must exist. Generated files use mode 0600
+inside a new 0700 directory. No certificate contents or pairing secrets are read
+or copied into the plan.
+
+## Review the service
+
+The systemd unit runs the installed Node executable and CLI directly in the
+foreground. It uses the specified unprivileged user, a 0077 umask, restart on
+failure, and limits persistent writes to the configured state directory.
+
+The named user must already exist and own the private configuration/state. The
+state directory must exist with mode 0700 and its files must be private. It must
+be outside temporary filesystem paths. The user also needs access to the Node
+and package paths; a root-only Node installation cannot serve an unprivileged
+application. Do not use an `npx` cache installation for a persistent service.
+
+The plan contains exact executable/configuration paths. Regenerate it after
+changing those locations. Paths with spaces are quoted; percent signs are escaped
+for systemd. Other shell/proxy metacharacters are rejected rather than interpreted.
+See [systemd command syntax](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html).
+
+## Review HTTPS forwarding
+
+The proxy examples require existing certificate/key files and a DNS hostname.
+They preserve the incoming Host authority, including a non-default port, so the
+relay can reject unknown authorities. They preserve Origin and Authorization,
+support WebSocket upgrades and overwrite the trusted client-IP/protocol headers.
+The generated proxy plans cap request bodies at 4 KiB. Application limits differ
+by route: push registration accepts up to 8 KiB and preview-key registration up
+to 512 bytes. See [HTTP limits](PROTOCOL.md#http); a stricter proxy limit wins.
+If an installation needs the full registration limit, review that proxy setting
+explicitly while retaining the application's route-specific limits.
+
+The nginx example belongs in the `http` context and uses its connection address.
+Review inherited real-IP settings before use. The Apache example uses
+`CONN_REMOTE_ADDR`, the actual connection peer, and requires `ssl`, `headers`,
+`proxy` and `proxy_http`. Apache also needs an existing Listen directive for the
+HTTPS port; the plan does not add a potentially duplicate listener.
+
+These examples describe a direct Internet-to-local-proxy-to-relay connection.
+CDN or additional proxy chains need a separate trusted-peer policy. Keep pairing
+details, request bodies and Authorization headers out of inherited logging rules.
+
+References: [nginx WebSocket proxying](https://nginx.org/en/docs/http/websocket.html),
+[Apache WebSocket upgrade](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html),
+[Apache header handling](https://httpd.apache.org/docs/2.4/mod/mod_headers.html),
+[Apache connection address](https://httpd.apache.org/docs/current/en/expr.html).
+
+## Apply explicitly
+
+`DEPLOYMENT.txt` lists commands to run manually from the generated directory.
+Inspect existing destination files before copying anything; these are new-install
+examples, not an overwrite or migration tool. Execute one command at a time and
+stop on a failure. Check the proxy configuration before reloading it. The Apache
+command examples use Debian/Ubuntu conventions; other distributions differ.
+
+The service starts separately from the HTTPS proxy. After verifying both, issue
+fresh pairing details and connect the app. An HTTPS health response establishes
+relay reachability; the paired app must still verify that the intended runtime
+is online and can complete a chat request.
+
+## Optional notification gateway
+
+Users of the Store app configure their Socket to use the publisher's trusted
+gateway; they do not need to host this additional process. Self-built apps can
+use their own FCM sender directly. See [push delivery configuration](SELF-HOSTING.md#optional-push-delivery).
+
+The Store application's publisher can run a separate sender process from this
+package. It is distinct from a user's Socket and must have its own private state
+directory, HTTPS origin and Firebase service account. Nothing in ordinary Socket
+setup creates an account, starts this gateway or enables remote delivery.
+
+Keep the gateway JSON and service-account file outside source with mode `0600`:
+
+```json
+{
+  "publicOrigin": "https://push.example.invalid",
+  "port": 8790,
+  "stateDirectory": "./push-state",
+  "serviceAccountFile": "./firebase-service-account.json"
+}
+```
+
+Run `abot-socket push-gateway --config /absolute/private/gateway.json` behind a
+trusted HTTPS reverse proxy. Like the Socket, it binds loopback only; the proxy
+must supply the verified client address and HTTPS forwarding headers described
+in this guide and allow its bounded JSON requests up to 8 KiB. Do not reuse the
+Socket's authentication state directory: the gateway
+has a separate database identity and rejects mixed state.
+
+The app uses `/v1/enroll` and `/v1/confirm` to prove receipt of a short-lived
+provider challenge. It receives separate device-scoped send and revoke grants,
+valid for up to 30 days. Only proof of receipt can replace an existing target.
+The paired Socket calls `/v1/deliver` with the send grant, fixed event kind and
+opaque notification ID. The gateway accepts neither arbitrary text nor a target
+token from a sender. `/v1/revoke` requires the separate management grant.
+
+Enrollment and sending have bounded rates, record counts, request sizes and
+timeouts. Provider tokens and credential hashes stay in private gateway state.
+The gateway sees delivery metadata, not chat text or pairing/runtime credentials.
+Data-only enrollment delivery is best effort; a delayed challenge can expire
+and must be retried while the app is open. Production deployment and a real
+signed-device test remain separate from local mocked validation.