@abot-ai/socket 0.0.0-stage → 0.1.0

package/docs/MIGRATION.md

@@ -0,0 +1,48 @@
+# Moving to pairing
+
+Installing the package does not change existing services or applications. Use a
+separately approved cutover after real-device verification.
+
+The chat envelopes, runtime bridge and runtime credential grants remain compatible.
+Authentication changes: the new client uses local-operator pairing instead of
+email. Old in-memory sessions cannot be imported. Existing devices must pair to
+the new service, receiving separate credentials bound to its HTTPS origin.
+
+1. Back up the current private configuration and deployed version.
+2. Prepare a separate candidate endpoint and private state with a unique test
+   runtime identity. Do not attach two active runtimes using the same ID.
+3. Issue pairing locally; verify pairing, restart persistence, runtime discovery,
+   history, chat, steering, approvals and revocation through the actual app.
+4. Perform the approved service/client cutover while retaining a rollback path.
+
+The new configuration has `publicOrigin`, `port`, `stateDirectory`, and
+`runtimeGrants`. Remove old `allowedEmail` and `mail` settings; they are rejected.
+`ABOT_SOCKET_CONFIG` accepts `SOCKET_V2_CONFIG` as a path alias. No mail-token
+variable is used. The existing runtime adapter needs configuration only, not
+source changes. Setup generates new runtime credentials rather than rotating or
+migrating an existing installation automatically.
+
+After cutover, retain the private state directory through upgrades. Device
+sessions persist there; transient relay routes still disappear on restart.
+Interrupted requests must be reconciled against runtime history before retry.
+
+
+## Notification preview schema upgrade
+
+Schema v3 adds a device-scoped preview-key table and nullable encrypted-preview
+column on the existing outbox. Both schema v1 and v2 upgrade transactionally;
+paired-device tokens, pending pairing, owner identity, notification metadata and
+generic delivery queues are preserved. Preview remains off until that device
+explicitly provisions a key after push registration. No runtime changes are needed.
+
+Stop the service and back up the private state directory and matching deployed
+code before upgrading. Older binaries reject schema v3. Rollback requires restoring
+the matching pre-upgrade database snapshot together with old code while stopped;
+do not point an old binary at the migrated state or delete the database to make it
+start. Restoring a snapshot also restores its older device/revocation/delivery state,
+so reconcile changes made since that snapshot before resuming service.
+
+For gateway delivery, upgrade the publisher gateway before clients enable previews.
+Keep previews off until compatible client support is installed. Old clients and
+opted-out devices retain the original generic push behavior. This source change
+alone does not deploy or enable preview delivery on an existing installation.

package/docs/PROTOCOL.md

@@ -0,0 +1,278 @@
+# Protocol and compatibility
+
+This candidate retains the Socket v2 chat transport contract and replaces email
+authentication with operator-issued pairing. It does not change
+runtime source or expose the complete runtime Web UI API. The `/health` value
+`version: 2` identifies the protocol family, not a package release number.
+
+## HTTP
+
+Use the configured HTTPS origin. JSON body limits depend on the route:
+
+| Route | Maximum JSON request body |
+| --- | --- |
+| `POST /v2/pairing/redeem`, `POST /v2/notifications/read`, `POST /v2/notifications/presence` | 4 KiB (4096 bytes). |
+| `PUT /v2/notifications/push` | 8 KiB (8192 bytes). |
+| `PUT /v2/notifications/push/preview` | 512 bytes. |
+
+These are application limits; a reverse proxy can impose a smaller limit. The
+generated direct-proxy plans currently cap request bodies at 4 KiB. The separate
+notification gateway accepts JSON bodies up to 8 KiB and needs its own proxy
+configuration. Field validation still applies within each body limit.
+
+Responses are `no-store`. Host must match the configured origin, and a supplied
+browser Origin must match it exactly. The local proxy requirements apply to all
+routes, including `/health`.
+
+| Method and path | Request / response |
+| --- | --- |
+| `GET /health` | `{ok:true, version:2}`; no account or runtime details. |
+| `POST /v2/pairing/redeem` | `{pairingId, code, deviceName}` → `{token, expiresAt, session:{id,subject,deviceName}}`. |
+| `GET /v2/auth/sessions` | Bearer session token → `{sessions:[{id,deviceName,createdAt,expiresAt,current}]}`. |
+| `DELETE /v2/auth/sessions/:id` | Bearer session token → `{revoked}`. |
+| `POST /v2/auth/logout` | Bearer session token → `{ok:true}`. |
+| `GET /v2/runtimes` | Bearer session token → `{runtimes:[...]}` with IDs, online state, model catalog, allowed modes, and capabilities. |
+
+`pairingId` is a random 32-character base64url temporary key; `code` is exactly
+six decimal digits, including leading zeros. Both are required. A bundle is
+valid for five minutes and five failed attempts; consume and device issuance
+share a database transaction. A retry after a lost success response cannot reuse
+it: the operator must create a fresh bundle. Neither secret belongs in a URL.
+The ordinary Socket API has no HTTP endpoint for generating pairing bundles.
+The optional, separately enabled [app-review portal](APP-REVIEW.md) exposes an
+authenticated `POST /review/pair` on its own listener/origin, bound to a dedicated
+review installation. It is not part of the ordinary Socket API. Legacy email
+endpoints are no longer supported.
+
+### Pairing QR, version 1
+
+The operator CLI can encode the existing bundle as raw UTF-8 JSON in a QR:
+
+```json
+{"type":"abot-pairing","version":1,"serverUrl":"https://socket.example.test","pairingId":"0123456789abcdefghijklmnopqrstuv","code":"000123","expiresAt":1800000300000}
+```
+
+This example is illustrative, not a usable pairing. `expiresAt` is Unix time in
+milliseconds; the server remains authoritative for validity. The code is a string
+to preserve leading zeros. The QR contains only these six fields, never a runtime
+token, permanent device token, configuration file, or secret-bearing URL/deep link.
+
+Clients validate the type/version and field shapes, accept only a canonical HTTPS
+origin, display the destination for confirmation, and then use the existing
+`POST /v2/pairing/redeem`. Scanning alone must not contact the destination. Suppress
+duplicate camera detections while confirmation or redemption is in progress.
+The existing expiry, attempt limits and one-use transaction apply unchanged;
+creating a new bundle replaces only the pending pairing, not existing devices.
+The QR is a bearer enrollment secret, so it must not be retained in logs or sent
+to external QR-generation services.
+
+An expired, unknown, consumed or wrong pairing returns `invalid_code` / 401.
+General HTTP limits and source/global code-verification limits return `rate_limited` / 429.
+Verification quotas apply only after matching an unexpired, unlocked pending pairing
+key; malformed, unknown, expired or already-locked pairing requests do not spend them.
+A full device list
+returns `device_limit` / 429; free a slot locally. Malformed device names return
+`invalid_request` / 400 without consuming an otherwise valid pairing.
+
+## Native client WebSocket
+
+Connect to `/v2/realtime` using `Authorization: Bearer <device-session-token>` in
+the HTTP upgrade. Credentials are not accepted in URL query parameters. Native
+clients should store the token in the platform's secure credential store.
+Browser WebSocket APIs cannot set this header; browser support needs its own
+designed authentication path.
+
+On connection, the relay sends `authenticated` with the session expiry and
+capability flags. Client commands use `{id, runtimeId, body}`. IDs must be unique
+per connection. Supported body types are:
+
+- `run_request`, `steer_request`, `tool_approval_response`;
+- `session.list.request`, `session.snapshot.request`, `request.events.request`;
+- `session.delete.request`, `session.messages.clear.request`, `session.message.delete.request`;
+- `attachment.upload.request`, `attachment.fetch.request`;
+- relay-local `subscribe_request` for a known request belonging to this owner.
+
+The relay returns `relay.ack`, `relay.error`, `relay.response`, or `relay.event`
+with the appropriate command ID, runtime ID, and body. An acknowledgement means
+dispatched or queued, not completed. Runtime correlations belong to the relay;
+the client cannot choose them. Unknown command fields and unsupported operations
+are rejected rather than forwarded as a generic admin API.
+
+Tool permission values are `ask`, `full_access`, and `full_plus`, constrained by
+the runtime grant. Setup grants only `ask`. The model catalog and supported
+reasoning controls come from the connected runtime, not a hardcoded model list.
+
+### Session mutations
+
+Each runtime in `/v2/runtimes` and the WebSocket `authenticated` frame includes
+`capabilities.sessionMutation: true` for these three relay operations. Clients must treat an
+absent/false flag as unsupported and require explicit user confirmation.
+
+| Request body | Response body (inside `relay.response`) |
+| --- | --- |
+| `{type:'session.delete.request', sessionId}` | `{type:'session.delete.response', ok, sessionId, deleted, deletedMessages, deletedRequests}` |
+| `{type:'session.messages.clear.request', sessionId}` | `{type:'session.messages.clear.response', ok, sessionId, cleared, deletedMessages, deletedRequests, updatedAt}` |
+| `{type:'session.message.delete.request', sessionId, messageId}` | `{type:'session.message.delete.response', ok, sessionId, messageId, deleted, updatedAt, deletedRequestId?, deletedRequestEvents?}` |
+
+Use canonical message IDs from a fresh runtime snapshot, not local UI IDs.
+Numeric message IDs are normalized to strings. Only `ok:true` together with
+`deleted:true` / `cleared:true` confirms a change; reload canonical history after
+the result. The runtime's single-message delete removes only that message row,
+plus its associated request replay/context and memory checkpoints; sibling
+message rows remain. Session deletion/clearing follows the existing runtime's
+history and attachment cleanup semantics.
+
+The relay rejects observed active/uncertain requests and in-flight uploads with
+`session_busy`. Before forwarding a mutation it reads a complete snapshot with
+`includeRequests:true`; active requests prevent deletion, and an incomplete or
+unrecognized snapshot returns `session_state_unavailable`. No snapshot contents
+are added to the mutation response. A pending mutation blocks another mutation,
+new run or upload in that session (`session_mutation_pending`). It retains this
+guard after client disconnect until the outcome or the shared 30-second timeout.
+A client disconnected during the read check cannot begin deletion.
+
+This check is not an atomic lock over independent Web UI clients. A request
+started directly at the runtime after the check can race with deletion; the
+runtime fences deleted generations and that request may be cancelled. Wait for
+work on all clients to finish. `outcome_unknown` never authorizes an automatic
+retry: reload authoritative history first. Missing sessions report
+`session_not_found`; runtime failures remain failures.
+
+## Runtime bridge
+
+Connect to `/agent-bridge` with the separate runtime Bearer token, then send the
+existing `{type:'register', agentId, features?, modelCatalog?}` message. The
+registered ID must match the credential's grant. A second connection cannot
+replace an already connected runtime with the same ID. Client device credentials
+cannot authenticate this role.
+
+## Recovery and capability limits
+
+- A timeout or disconnect can return `outcome_unknown`; do not retry commands
+  automatically. Read canonical runtime history/replay to reconcile the result.
+- Live `eventSequence` and replay `seqNo` are separate counters. `afterSeq` uses
+  the persisted replay counter only.
+- Approval authority requires an observed pending approval for the correct
+  runtime and request. Historical replay alone does not restore that authority.
+  Positive approval expires after five minutes; an explicit decline can remain
+  possible once on that same active runtime connection and request.
+- `cancel` and `durableApprovals` are advertised as false. Restart, cron,
+  configuration, and generic administration are not exposed.
+- The relay keeps bounded temporary routing state. It is not an offline queue,
+  durable conversation store, or exactly-once execution service.
+
+Use the new pairing-capable client. Email-only personal builds cannot enroll
+through this authentication contract. Existing runtime adapters are unchanged.
+
+## Notifications
+
+`capabilities.notifications: true` advertises the authenticated notification API.
+Notifications are owned by the **paired device that initiated the request**, not
+by its current WebSocket connection. Other paired devices cannot list or mark
+that device's records. There are no new unsolicited WebSocket frame types;
+clients poll the inbox while foregrounded and reconcile on resume or push tap.
+
+| Method and path | Request / response |
+| --- | --- |
+| `GET /v2/notifications?limit=50&before=<cursor>` | Device inbox, descending time; limit 1–100; opaque optional cursor. |
+| `POST /v2/notifications/read` | `{ids:[...]}` (maximum 100) → `{ok:true}`. Unknown or foreign IDs have no effect. |
+| `POST /v2/notifications/presence` | `{foreground:boolean,runtimeId?,sessionId?}` → `{ok:true}`; a session requires its runtime. |
+| `PUT /v2/notifications/push` | `{provider:'fcm',token}` or `{provider:'gateway',endpointId,sendToken}` → `{ok:true}`. |
+| `DELETE /v2/notifications/push` | Remove this device's push registration, preview key and queued deliveries → `{ok:true}`. |
+| `PUT /v2/notifications/push/preview` | Exact `{keyId,key}` → `{ok:true}`; opt in after registering push. Replaces the device's key. |
+| `DELETE /v2/notifications/push/preview` | Remove this device's preview key and queued ciphertext, retaining generic deliveries → `{ok:true}`. |
+
+The inbox response is `{version:1,items,nextCursor,unreadCount,unreadByRuntime,
+unreadBySession,delivery,registration,preview}`. Each item is
+`{id,runtimeId,sessionId,requestId,kind,createdAt,readAt,expiresAt}`; timestamps
+are epoch milliseconds, and `readAt` is null until read. `kind` is `completed`,
+`failed` or `approval_required`. `unreadByRuntime` maps runtime IDs to counts;
+`unreadBySession` maps runtime IDs to session-ID/count maps. `delivery` is
+`{mode:'disabled'|'fcm'|'gateway',configured:boolean}`, and `registration` is
+`{enabled:boolean}`. `preview` is `{supported:true,enabled:boolean,keyId:string|null}`.
+Older servers omit `preview`; clients treat that as unsupported and off. Keys
+and registration credentials are never returned by this API.
+
+Foreground presence lasts 45 seconds. Renew while active; `foreground:false`
+clears it. Presence is advisory: the phone may be suspended before its background
+update arrives, so presence alone never marks records read or suppresses delivery.
+Only an explicit authenticated read acknowledgement consumes records and cancels
+queued deliveries. Clients acknowledge fetched IDs after showing the conversation.
+Counts share the same ledger; they are not runtime transcript read receipts.
+Push taps resolve the notification ID through this authenticated inbox
+before opening a conversation; a push payload grants no execution or approval authority.
+
+Only validated live `completed`, `failed` and `tool.approval.required` frames for
+known relay requests create records. Streaming/progress events and replay do not.
+Granted/rejected/terminal events cancel pending approval deliveries. Approval
+notifications expire after five minutes; other records after at most seven days
+or device credential expiry. Storage is capped at 500 records per device.
+Expiration, logout and revocation remove registrations and pending deliveries.
+The outbox retries at most five times, with bounded backoff. Duplicate source
+events are deduplicated, but provider delivery is not an exactly-once guarantee.
+
+The inbox and queued deliveries survive relay restarts. In-flight request routing
+does not: this is not a complete runtime-wide event subscription or an offline
+execution queue. Web UI, schedules and autonomous SPARK events are outside this
+phase. Never interpret a missing notification as a failed request or auto-retry it.
+
+Push is disabled unless private operator configuration includes
+`notifications.delivery`. A self-built client uses
+`{type:'fcm',serviceAccountFile:'./private-sender.json'}`; the path is resolved
+relative to the private socket configuration, and sender credentials stay on
+that operator's server. The client must belong to the same configured Firebase
+project. Official builds can use `{type:'gateway',gatewayOrigin:'https://<trusted-host>'}`
+with a separately enrolled endpoint. Clients cannot choose a gateway URL or send
+provider credentials through the registration API. A missing or mismatched
+configured transport returns `409 push_unavailable`; ordinary chat and the inbox
+continue to work with delivery disabled.
+
+
+### Optional encrypted answer previews
+
+Previews are off by default and enabled per paired device, only after an active
+push registration exists. The app generates a random 32-byte AES-256-GCM key and
+16-byte key ID, sends both over authenticated HTTPS to its own Socket, and enables
+local display only after acknowledgement. Both fields use canonical unpadded
+base64url. No email, additional identity provider, or runtime change is involved.
+Provider-token rotation preserves the preview setting. Key replacement clears
+pending ciphertext. Disabling previews clears the key and ciphertext while leaving
+the generic queue intact; unregistering push removes the entire delivery queue.
+In-flight sends are aborted where possible, but provider-accepted notifications
+cannot be recalled. The client must discard its key immediately on disable/logout.
+
+Only a nonempty final `completed.output` is eligible. The Socket takes a bounded
+prefix, removes unsafe controls and bidi override characters, and truncates on a
+Unicode scalar boundary to at most 1024 UTF-8 bytes, including an ellipsis when
+needed. It is an excerpt, not secret redaction. Approval, failure and progress
+content is never included. No plaintext preview is stored in the inbox or outbox.
+The inbox remains metadata-only; encrypted content exists only in the pending
+outbox and is removed on delivery, read acknowledgement, revocation or expiry.
+
+The exact encrypted envelope is `{v:1,keyId,nonce,ciphertext,expiresAt}`. Nonce is
+12 random bytes. Ciphertext contains encrypted UTF-8 followed by the 16-byte GCM
+authentication tag (at most 1040 bytes), using canonical unpadded base64url.
+Authenticated additional data is UTF-8, with literal newline separators:
+
+```text
+ABot push preview v1
+<keyId>
+<notificationId>
+<expiresAt decimal epoch milliseconds>
+```
+
+The expiry equals notification expiry, capped by the device credential and seven
+days. The device rejects an unknown key, altered ID/expiry/content, expired data
+or malformed envelope and retains a generic alert. The gateway receives neither
+the key nor plaintext. Its `/v1/deliver` accepts an optional strictly validated
+`preview` field alongside the existing fixed delivery fields. Upgrade the gateway
+before enabling previews; older gateways do not accept this field.
+
+Encrypted FCM sends have no top-level `notification` or `android.notification`.
+Their string-valued data is `notificationId`, `abotPreview` (envelope JSON),
+`abotKind` (`completed`), `abotExpiresAt` and `abotBadge`. Android renders the
+notification locally. APNs retains a generic alert and sets `mutable-content:1`
+for the app's notification-service extension. Generic sends keep their existing
+payload. Serialized provider envelopes are bounded to 4096 UTF-8 bytes. Foreground
+display and navigation continue to use the authenticated inbox; push cannot grant
+access or approval authority.

package/docs/SECURITY.md

@@ -0,0 +1,98 @@
+# Security boundaries
+
+ABot Socket is a single-owner relay. Each installation has its own runtime
+grants, device credentials, private state and HTTPS origin. Every paired device
+represents that owner; this is not tenant isolation for unrelated users.
+
+## Authentication and credentials
+
+- Ordinary installations issue pairing through local operator commands. A random temporary
+  pairing key and six-digit code expire after five minutes or one successful use.
+  Five incorrect code attempts invalidate the challenge; expiry and attempts
+  persist across server restarts. Source and global verification limits apply only
+  to requests identifying an unexpired, unlocked pending pairing key. Unrelated
+  requests do not spend that quota; general HTTP request limits still apply.
+- Generating fresh pairing details replaces only the pending challenge, not
+  existing devices. Consumption and device creation are atomic in SQLite.
+- Device tokens are independently random. Only token digests are stored by the
+  server. Sessions last at most 30 days without sliding renewal, survive restarts
+  and can be revoked locally or by an authenticated owner device. Revocation and
+  expiry close existing WebSockets. At most 10 active device sessions are allowed.
+- The app binds credentials to the selected HTTPS origin in iOS Keychain and
+  refuses redirects. The pairing key is temporary, not a permanent shared key.
+- Runtime tokens are separate and bound to one runtime ID. Only their SHA-256
+  digest is in server configuration. Never put a runtime token into the app.
+- Configuration is private; state directories are 0700 and files 0600. State
+  symlinks, unexpected entries and unsafe ownership/permissions are rejected.
+  Keep installation files outside source, and never log codes, keys or bodies.
+- Setup and `pair` intentionally display new one-time details to the operator.
+  The ordinary Socket HTTP API does not generate or expose pairing bundles and
+  offers no email fallback or login bypass.
+- A separately enabled [app-review portal](APP-REVIEW.md) can generate and display
+  bundles after reviewer authentication. It binds to a dedicated review
+  installation, uses a separate listener/origin and must not share production
+  state or runtime credentials. Protect its access details as credentials.
+
+## Trusted components
+
+The relay, its local reverse proxy and runtime computers are trusted. There is no
+email delivery or third-party identity provider. HTTPS/WSS protects transport;
+the relay can read routed messages and attachments. This is not end-to-end
+encryption against its operator or a compromised relay host.
+
+Follow [the proxy requirements](SELF-HOSTING.md#3-configure-https-and-the-proxy-boundary).
+The listener is private loopback. Proxy headers must be overwritten by a trusted
+local proxy; forwarded addresses are not trustworthy simply because a header
+exists. CDN chains require a separate trusted-peer policy.
+
+## Permission and routing limits
+
+Runtime grants limit the permitted tool modes; `ask` is the setup default.
+Requests and responses are bound to their runtime connection and private
+correlation. Clients cannot use this relay to call generic runtime administration,
+restart, or scheduling. Session deletion/clearing is limited to three validated
+commands for an authorized runtime, with private response correlations and a
+read-before-delete check for active work. See the
+[mutation contract and its cross-client race limit](PROTOCOL.md#session-mutations).
+
+The relay validates command shapes, bounds frames, connections and routing state,
+and rejects unsupported operations. These controls do not make a compromised
+authorized device harmless: it can act within its owner's configured grants.
+Revoking that device session removes its relay access.
+
+The relay does not automatically retry uncertain operations, restore approval
+authority from historical events, or provide exactly-once execution. After a
+disconnect, reconcile against runtime history before resubmission.
+
+## Push preview boundary
+
+Answer previews are opt-in per paired device and off by default. The already
+trusted Socket sees final answers and encrypts a bounded excerpt with a random
+per-device AES-256-GCM key provisioned over the existing authenticated HTTPS API.
+That shared key is stored in the restricted Socket state; it is not sent to the
+publisher gateway, FCM or APNs. The gateway validates and forwards ciphertext only.
+This protects preview content from delivery intermediaries; it does not protect
+against a compromised Socket, device, or its operator. It is not a transcript
+end-to-end encryption claim.
+
+Keys are scoped to the paired device, and notification ID and expiry are bound
+into authenticated data. Key replacement, disable, logout and revocation remove
+queued ciphertext; provider token rotation retains the key. The inbox never
+returns preview content or keys. Pending ciphertext is deleted after delivery,
+read or expiry. SQLite deletion is logical cleanup, not forensic secure erasure;
+protect state backups as credentials. The OS may retain displayed notifications,
+and previews can reveal answer content on a lock screen according to user settings.
+Disabling cannot recall alerts already accepted or displayed by the provider/OS.
+The device must remove its local key immediately so later queued ciphertext falls
+back to generic text. Unsupported, expired or invalid payloads also fail generic.
+
+## Validation status
+
+Local tests use dummy principals, a mock runtime. Some
+tests exercise loopback HTTP/WebSocket transport. Configuration checking itself
+does not send email or open a listener. None of these checks proves a deployed
+proxy, domain, or real client/runtime behavior.
+
+Package publication is not a claim of a completed independent security
+audit. When investigating a problem, use synthetic credentials and redact
+configuration, tokens, codes, and conversation content from reports.

package/docs/SELF-HOSTING.md

@@ -0,0 +1,154 @@
+# Self-hosting ABot Socket
+
+Use [Installation and first connection](INSTALLATION.md) for the consumer
+installation, setup and QR/manual pairing flow. This companion guide covers
+configuration, the proxy trust boundary and ongoing operation. Service/proxy plan
+generation is covered in [Deployment](DEPLOYMENT.md). The source is MIT-licensed;
+the package is distributed as `@abot-ai/socket` on npm.
+
+## Requirements
+
+- Node.js 24 or later. npm installs the package's pinned dependencies, `ws` and
+  `qrcode-generator`, with either the registry package or a local tarball.
+- A server you control and a canonical HTTPS origin such as
+  `https://socket.example.net`.
+- A local HTTPS reverse proxy satisfying the boundary below.
+- An ABot Runtime with its existing agent-bridge adapter, and ABot App with pairing.
+
+There is no public signup. Every paired device acts as this installation's single
+owner and can see all runtimes granted to that installation.
+
+## 1. Prepare a private installation
+
+Follow the [setup steps](INSTALLATION.md#follow-setup) as the unprivileged account
+that will run the relay. Use your own HTTPS origin and keep the configuration,
+runtime connection file and state outside the installed package directory.
+Setup creates files only; applying a deployment plan and configuring the runtime
+remain separate operator actions.
+
+## 2. Check configuration and issue fresh pairing details
+
+For an installation outside the default `~/.abot-socket` directory:
+
+```sh
+abot-socket check-config --config /srv/abot-private/config.json
+abot-socket pair --config /srv/abot-private/config.json
+```
+
+`stateDirectory` is resolved relative to the configuration file, independent of
+the process working directory. An explicit `--config` takes precedence over
+environment settings. Otherwise use `ABOT_SOCKET_CONFIG`; `SOCKET_V2_CONFIG`
+remains a legacy alias and conflicting environment values are rejected.
+No mail credential is used.
+
+`check-config` validates the file without opening listeners or state. `pair`
+updates only local authentication state: it replaces any unused pairing details
+and displays a new five-minute bundle. Already paired devices stay connected.
+The running server sees these changes without a restart. Local operator commands
+must run as the same operating-system user that owns the private state directory.
+Generate pairing details after HTTPS is ready, then follow the
+[QR/manual pairing flow](INSTALLATION.md#connect-runtime-then-pair-the-app).
+
+## 3. Configure HTTPS and the proxy boundary
+
+The application listens only on `127.0.0.1` at the configured port. Keep the proxy
+on the same host and the application listener private. Containers, remote proxies,
+and additional proxy chains require a separately validated network arrangement;
+this package does not ship a Docker deployment.
+
+For direct Internet-to-proxy-to-relay deployment, the proxy must:
+
+1. Accept only the configured HTTPS authority and a valid certificate; preserve
+   the exact configured Host, including a non-default port if one is configured.
+2. Support WebSocket upgrades on `/v2/realtime` and `/agent-bridge`, retaining the
+   `Authorization` header.
+3. Remove incoming `X-Forwarded-Proto` and `X-Socket-Client-IP` values and set its
+   own: `https` for the verified HTTPS request and the actual client IP observed
+   on the proxy's connection. Never copy a client-supplied forwarding header.
+4. Preserve an incoming browser `Origin` so the relay can reject an origin that
+   differs from its configured public origin.
+5. Enforce connection, request-body, and timeout limits. Keep credentials, pairing
+   codes, request bodies, and authorization headers out of logs.
+
+If a CDN or another proxy sits in front, deriving the client IP requires an
+explicit trusted-peer policy. Trusting its claimed IP header from arbitrary
+Internet peers is unsafe. The direct-proxy instructions above do not configure
+that extra trust chain.
+
+## 4. Start and connect
+
+Use the [foreground or Linux service instructions](INSTALLATION.md#configure-https-and-start-the-relay),
+then [connect the runtime and pair the app](INSTALLATION.md#connect-runtime-then-pair-the-app).
+The app binds its device credential to the exact HTTPS origin and stores it in
+the platform's protected credential storage. It does not follow authentication
+or WebSocket redirects. A new server requires a new pairing; credentials are
+never silently copied across hosts.
+
+## Optional push delivery
+
+Push is disabled by default. To enable it, the operator adds
+`notifications.delivery` to the private Socket configuration and restarts the
+relay deliberately:
+
+- A self-built app uses its own Firebase project and
+  `{ "type": "fcm", "serviceAccountFile": "./private-sender.json" }`.
+  The app and sender must belong to the same Firebase project. Keep the service
+  account on the server, owned by the service user with mode `0600`; a relative
+  path is resolved from the Socket configuration file.
+- A Store build uses its publisher's trusted gateway with
+  `{ "type": "gateway", "gatewayOrigin": "https://<trusted-host>" }`.
+  Obtain that origin from the publisher's instructions. The publisher operates
+  the gateway and Firebase credentials; each user operates their own Socket.
+  Do not enter provider credentials into the app or run a second gateway merely
+  to use the Store build.
+
+After server configuration, enable notifications in the app and grant platform
+permission. Gateway builds enroll their own endpoint before registering it with
+the paired Socket. A mismatched delivery mode is rejected; the app cannot replace
+the operator's gateway URL. See [the notification protocol](PROTOCOL.md#notifications)
+for device ownership, retention, delivery limitations and optional encrypted
+answer previews. Gateway operation is separately described in
+[Deployment](DEPLOYMENT.md#optional-notification-gateway).
+
+## Operation and recovery
+
+```sh
+abot-socket devices --config /srv/abot-private/config.json
+abot-socket revoke <device-id> --config /srv/abot-private/config.json
+```
+
+The device list contains names, identifiers and expiry, never tokens. Revocation
+also closes an already-open client WebSocket within the next validity sweep
+(approximately one second). At 10 active devices, revoke an unused device before
+pairing another. The server never silently evicts an existing device.
+
+Sessions have a fixed maximum lifetime of 30 days and survive server restarts.
+After expiry, pair again. Reinstalling the app may require pairing again depending
+on the platform's secure-storage lifecycle; retaining the device's credential is
+not a guarantee across uninstall, signing or bundle-ID changes.
+
+Back up the private configuration, runtime credential and state directory using
+a consistent filesystem/database snapshot or with the service stopped. Losing
+state requires pairing devices again. Restoring an old backup may restore old
+revocation state; reapply necessary revocations. Conversation history remains in
+each runtime. Temporary relay routes do not survive restart, so reconcile
+interrupted requests with runtime history rather than automatically resending.
+
+The package does not provision a public TLS endpoint or install a service.
+Real-device, proxy and runtime verification remains separate from automated tests.
+
+## Source-checkout development
+
+These contributor commands require the repository checkout containing
+`package.json`, `package-lock.json` and the source tests. They are not additional
+steps for an installed npm/tarball consumer:
+
+```sh
+npm ci --omit=optional --ignore-scripts
+npm test
+```
+
+To prepare a separate local development installation from that checkout, use
+`node bin/abot-socket.mjs setup` and the same [installation guide](INSTALLATION.md).
+Keep its private files outside source control. Tests use dummy identities and
+loopback fixtures; they do not establish live runtime, phone or proxy readiness.

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@abot-ai/socket",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "start": "node bin/abot-socket.mjs start",
+    "setup": "node bin/abot-socket.mjs setup",
+    "check-config": "node bin/abot-socket.mjs check-config",
+    "test": "node --test test/*.test.mjs",
+    "pair": "node bin/abot-socket.mjs pair",
+    "devices": "node bin/abot-socket.mjs devices",
+    "revoke": "node bin/abot-socket.mjs revoke",
+    "doctor": "node bin/abot-socket.mjs doctor",
+    "deployment": "node bin/abot-socket.mjs deployment",
+    "check-package": "node scripts/check-package.mjs"
+  },
+  "dependencies": {
+    "qrcode-generator": "2.0.4",
+    "ws": "8.21.0"
+  },
+  "description": "Self-hosted authenticated relay for ABot clients and runtimes",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Dorshitrit/abot-socket.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Dorshitrit/abot-socket/issues"
+  },
+  "homepage": "https://github.com/Dorshitrit/abot-socket#readme",
+  "files": [
+    "bin/abot-socket.mjs",
+    "src/main.mjs",
+    "src/auth/*.mjs",
+    "src/cli/*.mjs",
+    "src/config/*.mjs",
+    "src/deployment/*.mjs",
+    "src/notifications/*.mjs",
+    "src/pairing/*.mjs",
+    "src/protocol/*.mjs",
+    "src/relay/*.mjs",
+    "src/review/*.mjs",
+    "src/setup/*.mjs",
+    "src/transport/*.mjs",
+    "README.md",
+    "LICENSE",
+    "config.example.json",
+    "docs/SELF-HOSTING.md",
+    "docs/PROTOCOL.md",
+    "docs/SECURITY.md",
+    "docs/MIGRATION.md",
+    "docs/DEPLOYMENT.md",
+    "docs/INSTALLATION.md",
+    "docs/APP-REVIEW.md"
+  ],
+  "bin": {
+    "abot-socket": "bin/abot-socket.mjs"
+  }
+}