@book.dev/sdk 3.3.2 → 3.3.3

package/dist/provenance.d.ts

@@ -41,6 +41,16 @@ export interface TrustedIssuerConfig {
 /** The instance's multi-user policy, persisted in the `settings` table. */
 export interface InstanceConfig {
     guestAccess: GuestAccess;
+    /**
+     * A stable, opaque per-library identifier (STAB-5). Minted once at first
+     * startup and persisted; it authorizes NOTHING (like {@link ownerSubject}, it's
+     * a non-secret coordinate) and only exists so an out-of-process connector can
+     * confirm it reached THIS library's server rather than a foreign responder that
+     * happens to answer on the same loopback port (e.g. a stale `pnpm dev`). Surfaced
+     * on `GET /api/instance` as {@link InstanceInfo.instanceId}. Absent on a
+     * pre-STAB-5 config until the next boot's {@link ensureInstanceId} mints it.
+     */
+    instanceId?: string;
     /** The principal subject that administers this instance, once claimed. */
     ownerSubject?: string;
     trustedIssuers: TrustedIssuerConfig[];
@@ -130,6 +140,14 @@ export declare const DEFAULT_INSTANCE_CONFIG: InstanceConfig;
  */
 export interface InstanceInfo {
     guestAccess: GuestAccess;
+    /**
+     * The stable, opaque per-library identifier (STAB-5) — see
+     * {@link InstanceConfig.instanceId}. An out-of-process MCP connector compares
+     * this against its configured `OPENBOOK_INSTANCE_ID` to refuse a foreign
+     * responder on the same port. Not a secret (authorizes nothing). Optional:
+     * absent on a pre-STAB-5 server / a test fixture — a connector then can't verify
+     * identity and falls back to a reachability-only probe. */
+    instanceId?: string | null;
     ownerSubject: string | null;
     trustedIssuers: string[];
     /** This server's audience identifier, so a client can request an `aud`-scoped

package/dist/provenance.js.map

@@ -1 +1 @@
-{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAC,mBAAmB,EAAC,MAAM,WAAW,CAAC;AA6H9C,MAAM,CAAC,MAAM,uBAAuB,GAAmB;IACrD,WAAW,EAAE,OAAO;IACpB,+EAA+E;IAC/E,+EAA+E;IAC/E,gFAAgF;IAChF,4EAA4E;IAC5E,cAAc,EAAE;QACd;YACE,MAAM,EAAE,mBAAmB;YAC3B,OAAO,EAAE,GAAG,mBAAmB,oBAAoB;YACnD,2EAA2E;YAC3E,uDAAuD;YACvD,cAAc,EAAE,GAAG,mBAAmB,2BAA2B;SAClE;KACF;IACD,iFAAiF;IACjF,+EAA+E;IAC/E,iBAAiB,EAAE,SAAS;IAC5B,iFAAiF;IACjF,+EAA+E;IAC/E,cAAc,EAAE,mBAAmB;CACpC,CAAC"}
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAC,mBAAmB,EAAC,MAAM,WAAW,CAAC;AAuI9C,MAAM,CAAC,MAAM,uBAAuB,GAAmB;IACrD,WAAW,EAAE,OAAO;IACpB,+EAA+E;IAC/E,+EAA+E;IAC/E,gFAAgF;IAChF,4EAA4E;IAC5E,cAAc,EAAE;QACd;YACE,MAAM,EAAE,mBAAmB;YAC3B,OAAO,EAAE,GAAG,mBAAmB,oBAAoB;YACnD,2EAA2E;YAC3E,uDAAuD;YACvD,cAAc,EAAE,GAAG,mBAAmB,2BAA2B;SAClE;KACF;IACD,iFAAiF;IACjF,+EAA+E;IAC/E,iBAAiB,EAAE,SAAS;IAC5B,iFAAiF;IACjF,+EAA+E;IAC/E,cAAc,EAAE,mBAAmB;CACpC,CAAC"}

package/dist/types.d.ts

@@ -261,6 +261,17 @@ export interface ServerInfo {
     accessToken?: string | null;
     /** Folder the on-disk book mirror writes to (durable mode). */
     bookDir?: string | null;
+    /**
+     * Whether the host also binds a loopback TCP listener (`127.0.0.1:4319`) on the
+     * same sidecar so an out-of-process local MCP/agent connector can reach this
+     * exact library (STAB-5). Gated on the local-MCP/agent toggle — OFF by default,
+     * and independent of {@link published} (which binds `0.0.0.0` for the LAN).
+     * Unlike the FS-permissioned IPC socket, this loopback listener is reachable by
+     * any local process AND by any web origin the user's browser will POST to (the
+     * sidecar serves wildcard CORS and guestAccess defaults to 'write') — a real
+     * added surface, hence the explicit opt-in toggle; browser-reachability
+     * hardening is tracked separately. */
+    agentLocalTcp?: boolean;
 }
 /**
  * Controls for the host-managed local server, provided by the platform layer
@@ -281,4 +292,11 @@ export interface ServerControls {
     chooseBookDir?(): Promise<ServerInfo>;
     /** Reveal the current book-mirror directory in the OS file manager. */
     revealBookDir?(): Promise<void>;
+    /**
+     * Bind (or unbind) the loopback TCP listener (`127.0.0.1:4319`) used by an
+     * out-of-process local MCP/agent connector (STAB-5). Flipped together with the
+     * agent-API toggle so the connector's default endpoint actually points at THIS
+     * library's server. Resolves the new status (with {@link ServerInfo.agentLocalTcp}).
+     * Absent on the web / an old host that predates the capability. */
+    setAgentLocalTcp?(enabled: boolean): Promise<ServerInfo>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@book.dev/sdk",
-  "version": "3.3.2",
+  "version": "3.3.3",
   "description": "Shared OpenBook types and HTTP client used by the server, desktop, and web.",
   "repository": {
     "type": "git",