anchordb-lens-link 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AnchorDB contributors
+
+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

@@ -0,0 +1,87 @@
+# anchordb-lens-link
+
+**Open a QA build's AnchorDB database in Anchor Lens, on the same Android phone, from a file.** No
+laptop, no relay, no pairing code.
+
+```bash
+npm install anchordb-lens-link
+```
+
+```ts
+import { enableLensLink } from "anchordb-lens-link";
+import { db } from "./db";
+
+// QA builds only — see "Keep it out of production" below.
+if (process.env.EXPO_PUBLIC_LENS_LINK === "on") {
+  void enableLensLink(db, { allowInProduction: true });
+}
+```
+
+Rebuild the app (a development or release build — not Expo Go), install it, open it once. Then in
+Anchor Lens: **Connect to an app → Open app from file**, and pick
+
+```
+Android/media/<your app's package>/anchor-lens/<database>.anchorlens
+```
+
+Lens opens the app's database live. Edits in either app show up in the other.
+
+## How it works
+
+1. `enableLensLink` starts a WebSocket server on **127.0.0.1**, on a random port, and puts an
+   `InspectorAgent` on the database behind it.
+2. It makes a **secret for this launch** — 32 random bytes — and writes the port and the secret into
+   the link file, **sealed** so that only Anchor Lens can read it.
+3. Lens reads the file, connects to `ws://127.0.0.1:<port>` with React Native's own WebSocket, and
+   proves it holds the secret with the inspector's HMAC challenge. The secret never crosses the
+   connection.
+4. From there it is an ordinary inspector session: the same protocol, capability checks and Model API
+   writes — validation, unique indexes, timestamps, the sync queue — as through `anchor-relay`.
+
+The file is rewritten on every launch, because the port and the secret change. It works only while the
+app is running; if Lens says the app closed, open the app and pick the file again.
+
+## Keep it out of production
+
+A link exposes the database to Anchor Lens on the phone, so:
+
+- Nothing happens unless the app calls `enableLensLink`. Put the call behind a build flag.
+- In a release build — which includes a QA APK — it refuses to start without `allowInProduction: true`.
+- `readOnly: true` refuses every write from Lens.
+- `link.close()` stops the server and deletes the file.
+
+What protects the database:
+
+- **Loopback only.** The server listens on 127.0.0.1; nothing on the network can reach it. A web page in
+  the phone's browser can reach 127.0.0.1, and is refused by its Origin before it gets further.
+- **A new secret every launch**, proved over a single-use challenge, never sent.
+- **The seal** makes the file unreadable and tamper-evident to other apps. It is not secrecy from someone
+  who holds both the file and Anchor Lens, which carries the key — the two points above are what count.
+
+## API
+
+```ts
+enableLensLink(db, options?): Promise<LensLink>
+```
+
+| Option | |
+| --- | --- |
+| `allowInProduction` | Required in a release build |
+| `readOnly` | Refuse every write from Lens |
+| `anchorVersion`, `platform` | Reported to Lens |
+| `onConnectionsChange(count)` | Lens connections opening and closing |
+
+`LensLink` has `port`, `fileName`, `filePath`, `connections`, `agent` and `close()`. Calling
+`enableLensLink` again for the same database replaces the running link, so it is safe in an effect and
+through Fast Refresh.
+
+For a Lens client: `readLensLink(fileText)` returns `{ app, database, port, secret, … }` or throws a
+`LensLinkError` (`not_a_link`, `tampered`, `unsupported`, `invalid`) with a message worth showing, and
+`lensLinkUrl(link)` is where to connect.
+
+## Requirements
+
+- Android. The native module is an Expo module, so the app needs `expo` (any Expo app has it; a bare
+  React Native app needs `expo-modules-core` installed). iOS is not supported yet.
+- `anchordb` 1.3 or later, whose inspector accepts a shared secret.
+- Anchor Lens with **Open app from file**.

package/android/build.gradle

@@ -0,0 +1,21 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'dev.anchordb'
+version = '1.3.0'
+
+android {
+  namespace "dev.anchordb.lenslink"
+  defaultConfig {
+    versionCode 1
+    versionName '1.3.0'
+  }
+}
+
+dependencies {
+  // The WebSocket server on 127.0.0.1. Anchor Lens connects with React Native's built-in WebSocket, so
+  // this is the only native networking code on either side.
+  implementation "org.java-websocket:Java-WebSocket:1.6.0"
+}

package/android/src/main/java/dev/anchordb/lenslink/AnchorLensLinkModule.kt

@@ -0,0 +1,203 @@
+package dev.anchordb.lenslink
+
+import android.os.Bundle
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.exception.CodedException
+import expo.modules.kotlin.exception.Exceptions
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import org.java_websocket.WebSocket
+import org.java_websocket.drafts.Draft
+import org.java_websocket.exceptions.InvalidDataException
+import org.java_websocket.framing.CloseFrame
+import org.java_websocket.handshake.ClientHandshake
+import org.java_websocket.handshake.ServerHandshakeBuilder
+import org.java_websocket.server.WebSocketServer
+import java.io.File
+import java.net.InetSocketAddress
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicInteger
+
+/**
+ * The native half of Anchor Lens Link: a WebSocket server on this phone's loopback address, and the link
+ * file in Android/media/<package>/anchor-lens/.
+ *
+ * Only transport and files live here. Authentication, the inspector protocol and the database are all
+ * JavaScript, in anchordb itself — this module never sees a secret it checks, or a document.
+ */
+class AnchorLensLinkModule : Module() {
+  private var server: LinkServer? = null
+
+  override fun definition() = ModuleDefinition {
+    Name("AnchorLensLink")
+
+    Events("onOpen", "onMessage", "onClose")
+
+    AsyncFunction("startServer") { promise: Promise ->
+      stopServerNow()
+      val next = LinkServer(this@AnchorLensLinkModule, promise)
+      server = next
+      next.start()
+    }
+
+    AsyncFunction("stopServer") {
+      stopServerNow()
+    }
+
+    Function("send") { id: Int, data: String ->
+      server?.sendTo(id, data) ?: false
+    }
+
+    Function("closeConnection") { id: Int ->
+      closeConnectionNow(id)
+    }
+
+    Function("packageName") {
+      context().packageName
+    }
+
+    Function("writeLinkFile") { name: String, contents: String ->
+      val file = linkFile(name)
+      file.parentFile?.mkdirs()
+      file.writeText(contents)
+      file.absolutePath
+    }
+
+    Function("deleteLinkFile") { name: String ->
+      linkFile(name).delete()
+    }
+
+    OnDestroy {
+      stopServerNow()
+    }
+  }
+
+  internal fun emit(event: String, body: Bundle) {
+    sendEvent(event, body)
+  }
+
+  private fun stopServerNow() {
+    server?.shutdown()
+    server = null
+  }
+
+  private fun closeConnectionNow(id: Int) {
+    server?.closeConnection(id)
+  }
+
+  private fun context() = appContext.reactContext ?: throw Exceptions.ReactContextLost()
+
+  @Suppress("DEPRECATION")
+  private fun linkFile(name: String): File {
+    if (!FILE_NAME.matches(name)) throw InvalidLinkFileName(name)
+    // externalMediaDirs is the call that creates Android/media/<package>, which another app's file picker
+    // can open. getExternalFilesDir would put the file under Android/data, which pickers hide.
+    val media = context().externalMediaDirs.firstOrNull { it != null } ?: throw NoMediaDirectory()
+    return File(File(media, "anchor-lens"), name)
+  }
+
+  companion object {
+    private val FILE_NAME = Regex("^[A-Za-z0-9._-]{1,120}\\.anchorlens$")
+  }
+}
+
+private class InvalidLinkFileName(name: String) :
+  CodedException("\"$name\" is not an Anchor Lens link file name.")
+
+private class NoMediaDirectory :
+  CodedException("This device has no shared media storage to write the Anchor Lens link file to.")
+
+/** One launch's server. A stopped WebSocketServer cannot be started again, so each start makes a new one. */
+private class LinkServer(
+  private val module: AnchorLensLinkModule,
+  private val started: Promise,
+) : WebSocketServer(InetSocketAddress("127.0.0.1", 0)) {
+  private val connections = ConcurrentHashMap<Int, WebSocket>()
+  private val nextId = AtomicInteger(0)
+  private val settled = AtomicBoolean(false)
+
+  init {
+    isReuseAddr = true
+  }
+
+  override fun onWebsocketHandshakeReceivedAsServer(
+    conn: WebSocket,
+    draft: Draft,
+    request: ClientHandshake,
+  ): ServerHandshakeBuilder {
+    // A web page open in the phone's browser can reach 127.0.0.1 too. It could never prove the secret,
+    // but it is turned away before that: browsers always send their page's Origin, and React Native's
+    // WebSocket sends none or a loopback one.
+    val origin = request.getFieldValue("Origin")
+    if (origin.isNotEmpty() && !LOOPBACK_ORIGIN.matches(origin)) {
+      throw InvalidDataException(CloseFrame.POLICY_VALIDATION, "Origin not allowed")
+    }
+    return super.onWebsocketHandshakeReceivedAsServer(conn, draft, request)
+  }
+
+  override fun onStart() {
+    if (settled.compareAndSet(false, true)) started.resolve(port)
+  }
+
+  override fun onOpen(conn: WebSocket, handshake: ClientHandshake) {
+    val id = nextId.incrementAndGet()
+    conn.setAttachment(id)
+    connections[id] = conn
+    module.emit("onOpen", Bundle().apply { putInt("id", id) })
+  }
+
+  override fun onMessage(conn: WebSocket, message: String) {
+    val id: Int = conn.getAttachment<Int>() ?: return
+    module.emit(
+      "onMessage",
+      Bundle().apply {
+        putInt("id", id)
+        putString("data", message)
+      },
+    )
+  }
+
+  override fun onClose(conn: WebSocket, code: Int, reason: String?, remote: Boolean) {
+    val id: Int = conn.getAttachment<Int>() ?: return
+    connections.remove(id)
+    module.emit(
+      "onClose",
+      Bundle().apply {
+        putInt("id", id)
+        putInt("code", code)
+      },
+    )
+  }
+
+  override fun onError(conn: WebSocket?, ex: Exception) {
+    // With no connection it is the server itself that failed; before it started, that is start failing.
+    if (conn == null && settled.compareAndSet(false, true)) {
+      started.reject("ERR_LENS_LINK_START", ex.message ?: "The Anchor Lens Link server did not start.", ex)
+    }
+  }
+
+  fun sendTo(id: Int, data: String): Boolean {
+    val conn = connections[id] ?: return false
+    if (!conn.isOpen) return false
+    conn.send(data)
+    return true
+  }
+
+  fun closeConnection(id: Int) {
+    connections[id]?.close(CloseFrame.NORMAL)
+  }
+
+  fun shutdown() {
+    try {
+      stop(1000)
+    } catch (_: InterruptedException) {
+      Thread.currentThread().interrupt()
+    }
+    connections.clear()
+  }
+
+  companion object {
+    private val LOOPBACK_ORIGIN = Regex("^https?://(127\\.0\\.0\\.1|localhost)(:\\d+)?$")
+  }
+}

package/dist/cjs/app.d.ts

@@ -0,0 +1,65 @@
+import { InspectorAgent, type AnchorDB } from "anchordb";
+/**
+ * The app half of Anchor Lens Link.
+ *
+ * `enableLensLink(db)` starts a WebSocket server on 127.0.0.1, puts an `InspectorAgent` on the database
+ * behind it, and writes the link file Lens opens. Every connection is an ordinary inspector session —
+ * the same protocol, capability checks and Model API writes as through the relay — authenticated with a
+ * secret made for this launch, which exists only inside the sealed file.
+ */
+/** An event from the native module. */
+export interface LensLinkNativeEvent {
+    id: number;
+    data?: string;
+    code?: number;
+}
+/** The native module's surface. Exported so a test, or another runtime, can supply its own. */
+export interface LensLinkNative {
+    startServer(): Promise<number>;
+    stopServer(): Promise<void>;
+    send(id: number, data: string): boolean;
+    closeConnection(id: number): void;
+    packageName(): string;
+    writeLinkFile(name: string, contents: string): string;
+    deleteLinkFile(name: string): boolean;
+    addListener(event: "onOpen" | "onMessage" | "onClose", listener: (event: LensLinkNativeEvent) => void): {
+        remove(): void;
+    };
+}
+export interface LensLinkOptions {
+    /**
+     * Required in a release build — which includes a QA APK. Lens Link exposes the database to Anchor
+     * Lens on this phone, so shipping it to users has to be a decision, not an accident.
+     */
+    allowInProduction?: boolean;
+    /** Refuse every write from Lens. */
+    readOnly?: boolean;
+    /** Reported to Lens. */
+    anchorVersion?: string;
+    platform?: string;
+    /** Called whenever a Lens connection opens or closes, with how many are open. */
+    onConnectionsChange?: (count: number) => void;
+    /** The native module. Defaults to the one this package installs. */
+    native?: LensLinkNative;
+}
+export interface LensLink {
+    readonly agent: InspectorAgent;
+    /** The port on 127.0.0.1. */
+    readonly port: number;
+    /** The link file's name, `<database>.anchorlens`. */
+    readonly fileName: string;
+    /** Where it was written, e.g. /storage/emulated/0/Android/media/<package>/anchor-lens/<database>.anchorlens. */
+    readonly filePath: string;
+    /** Lens connections open right now. */
+    readonly connections: number;
+    /** Stop listening, close every Lens connection, and delete the link file. */
+    close(): Promise<void>;
+}
+/**
+ * Let Anchor Lens on this phone open `db`. For development and QA builds.
+ *
+ * Calling it again for the same database replaces the running link, so it is safe in an effect or
+ * after a reload. Resolves once the link file is written.
+ */
+export declare function enableLensLink(db: AnchorDB, options?: LensLinkOptions): Promise<LensLink>;
+//# sourceMappingURL=app.d.ts.map

package/dist/cjs/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EAGd,KAAK,QAAQ,EAEd,MAAM,UAAU,CAAC;AAGlB;;;;;;;GAOG;AAEH,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,+FAA+F;AAC/F,MAAM,WAAW,cAAc;IAC7B,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,WAAW,IAAI,MAAM,CAAC;IACtB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IACtD,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC,WAAW,CACT,KAAK,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,EACzC,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAC7C;QAAE,MAAM,IAAI,IAAI,CAAA;KAAE,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wBAAwB;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,oEAAoE;IACpE,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gHAAgH;IAChH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAOD;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAOnG"}

package/dist/cjs/app.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enableLensLink = enableLensLink;
+const anchordb_1 = require("anchordb");
+const link_file_ts_1 = require("./link-file.js");
+// On globalThis, not in module scope: Fast Refresh re-runs this module, and a registry that reset with it
+// would leave the previous agent answering on the previous server's events.
+const registry = (globalThis.__anchordbLensLinks ??=
+    new Map());
+/**
+ * Let Anchor Lens on this phone open `db`. For development and QA builds.
+ *
+ * Calling it again for the same database replaces the running link, so it is safe in an effect or
+ * after a reload. Resolves once the link file is written.
+ */
+async function enableLensLink(db, options = {}) {
+    (0, anchordb_1.assertInspectorAllowed)(db.name, options.allowInProduction);
+    const native = options.native ?? nativeModule();
+    await registry.get(db.name)?.close();
+    const link = await start(db, native, options);
+    registry.set(db.name, link);
+    return link;
+}
+async function start(db, native, options) {
+    // Uppercase, so a client that normalises what it proves the way it does a typed pairing code still
+    // proves the same value.
+    const secret = (0, link_file_ts_1.randomHex)(32).toUpperCase();
+    const platform = options.platform ?? "android";
+    const agent = new anchordb_1.InspectorAgent(db, {
+        auth: { sharedSecret: secret },
+        platform,
+        ...(options.anchorVersion ? { anchorVersion: options.anchorVersion } : {}),
+        ...(options.readOnly ? { readOnly: true } : {}),
+    });
+    const sockets = new Map();
+    const report = () => options.onConnectionsChange?.(sockets.size);
+    const subscriptions = [
+        native.addListener("onOpen", ({ id }) => {
+            const socket = new NativeSocket(native, id);
+            const detach = agent.attach(new anchordb_1.WebSocketTransport({ socket }));
+            sockets.set(id, { socket, detach });
+            report();
+        }),
+        native.addListener("onMessage", ({ id, data }) => {
+            sockets.get(id)?.socket.receive(data ?? "");
+        }),
+        native.addListener("onClose", ({ id }) => {
+            const entry = sockets.get(id);
+            if (!entry)
+                return;
+            sockets.delete(id);
+            entry.detach();
+            entry.socket.closed();
+            report();
+        }),
+    ];
+    const fileName = `${db.name.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 100)}.anchorlens`;
+    let port;
+    let filePath;
+    try {
+        port = await native.startServer();
+        const payload = {
+            v: 1,
+            app: native.packageName(),
+            database: db.name,
+            port,
+            secret,
+            platform,
+            ...(options.anchorVersion ? { anchorVersion: options.anchorVersion } : {}),
+            createdAt: new Date().toISOString(),
+        };
+        filePath = native.writeLinkFile(fileName, (0, link_file_ts_1.sealLensLink)(payload));
+    }
+    catch (err) {
+        for (const subscription of subscriptions)
+            subscription.remove();
+        await native.stopServer().catch(() => undefined);
+        await agent.close();
+        throw err;
+    }
+    let closed = false;
+    const link = {
+        agent,
+        port,
+        fileName,
+        filePath,
+        get connections() {
+            return sockets.size;
+        },
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            if (registry.get(db.name) === link)
+                registry.delete(db.name);
+            for (const subscription of subscriptions)
+                subscription.remove();
+            for (const { socket, detach } of sockets.values()) {
+                detach();
+                socket.closed();
+            }
+            sockets.clear();
+            try {
+                native.deleteLinkFile(fileName);
+            }
+            catch {
+                // A link file that is already gone is what closing wants anyway.
+            }
+            await native.stopServer();
+            await agent.close();
+            report();
+        },
+    };
+    return link;
+}
+/** One native connection, shaped like the WebSocket core's transport already speaks. */
+class NativeSocket {
+    constructor(native, id) {
+        this.readyState = 1;
+        this.listeners = new Map();
+        this.native = native;
+        this.id = id;
+    }
+    send(data) {
+        if (this.readyState === 1)
+            this.native.send(this.id, data);
+    }
+    close() {
+        if (this.readyState !== 1)
+            return;
+        this.readyState = 2;
+        this.native.closeConnection(this.id);
+    }
+    addEventListener(type, listener) {
+        let set = this.listeners.get(type);
+        if (!set)
+            this.listeners.set(type, (set = new Set()));
+        set.add(listener);
+    }
+    removeEventListener(type, listener) {
+        this.listeners.get(type)?.delete(listener);
+    }
+    receive(data) {
+        this.emit("message", { data });
+    }
+    closed() {
+        if (this.readyState === 3)
+            return;
+        this.readyState = 3;
+        this.emit("close", {});
+    }
+    emit(type, event) {
+        for (const listener of [...(this.listeners.get(type) ?? [])])
+            listener(event);
+    }
+}
+function nativeModule() {
+    const modules = globalThis.expo?.modules;
+    const found = modules?.AnchorLensLink;
+    if (!found) {
+        throw new Error("Anchor Lens Link needs its native module, and this build does not have it. It runs on Android, in a " +
+            "development or release build (not Expo Go): install anchordb-lens-link, then rebuild the app.");
+    }
+    return found;
+}
+//# sourceMappingURL=app.js.map

package/dist/cjs/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/app.ts"],"names":[],"mappings":"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"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * anchordb-lens-link — open a QA build's database in Anchor Lens on the same Android phone.
+ *
+ * App side: `enableLensLink(db, { allowInProduction: true })`.
+ * Lens side: `readLensLink(fileText)` and `lensLinkUrl(link)`, then an ordinary inspector client over
+ * React Native's WebSocket, authenticated with `link.secret`.
+ */
+export { enableLensLink } from "./app.js";
+export type { LensLink, LensLinkNative, LensLinkNativeEvent, LensLinkOptions } from "./app.js";
+export { LensLinkError, lensLinkUrl, readLensLink, sealLensLink } from "./link-file.js";
+export type { LensLinkErrorCode, LensLinkPayload } from "./link-file.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC/F,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxF,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sealLensLink = exports.readLensLink = exports.lensLinkUrl = exports.LensLinkError = exports.enableLensLink = void 0;
+/**
+ * anchordb-lens-link — open a QA build's database in Anchor Lens on the same Android phone.
+ *
+ * App side: `enableLensLink(db, { allowInProduction: true })`.
+ * Lens side: `readLensLink(fileText)` and `lensLinkUrl(link)`, then an ordinary inspector client over
+ * React Native's WebSocket, authenticated with `link.secret`.
+ */
+var app_ts_1 = require("./app.js");
+Object.defineProperty(exports, "enableLensLink", { enumerable: true, get: function () { return app_ts_1.enableLensLink; } });
+var link_file_ts_1 = require("./link-file.js");
+Object.defineProperty(exports, "LensLinkError", { enumerable: true, get: function () { return link_file_ts_1.LensLinkError; } });
+Object.defineProperty(exports, "lensLinkUrl", { enumerable: true, get: function () { return link_file_ts_1.lensLinkUrl; } });
+Object.defineProperty(exports, "readLensLink", { enumerable: true, get: function () { return link_file_ts_1.readLensLink; } });
+Object.defineProperty(exports, "sealLensLink", { enumerable: true, get: function () { return link_file_ts_1.sealLensLink; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACH,mCAA0C;AAAjC,wGAAA,cAAc,OAAA;AAEvB,+CAAwF;AAA/E,6GAAA,aAAa,OAAA;AAAE,2GAAA,WAAW,OAAA;AAAE,4GAAA,YAAY,OAAA;AAAE,4GAAA,YAAY,OAAA"}

package/dist/cjs/link-file.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The link file: where a running app can be reached on this phone, and the secret that proves it is
+ * Anchor Lens connecting.
+ *
+ * The app writes it on every launch, because the port and the secret change every launch. Lens reads
+ * it when the developer picks it.
+ *
+ * ## What the seal does, and does not do
+ *
+ * The contents are encrypted and authenticated with a key this package and Anchor Lens share: an
+ * HMAC-SHA256 keystream, and an HMAC tag checked before anything is decrypted. So the file is unreadable
+ * and tamper-evident to anything that is not Lens. It is not secrecy from someone who holds both the
+ * file and a copy of Lens, because Lens ships the key. What actually protects the database is the rest:
+ * the server listens on 127.0.0.1 only, the secret changes every launch and is proved rather than sent,
+ * and none of it exists unless a QA build calls `enableLensLink`.
+ *
+ * Built on anchordb's own HMAC-SHA256, so there is no crypto dependency and it behaves the same in
+ * Hermes, Node and a browser.
+ */
+export interface LensLinkPayload {
+    v: 1;
+    /** The app's Android package, such as dev.anchordb.example. */
+    app: string;
+    database: string;
+    /** Where the app listens, on 127.0.0.1. Changes every launch. */
+    port: number;
+    /** 64 uppercase hex digits. Changes every launch. Proved over the connection, never sent. */
+    secret: string;
+    platform: string;
+    anchorVersion?: string;
+    createdAt: string;
+}
+export type LensLinkErrorCode = "not_a_link" | "tampered" | "unsupported" | "invalid";
+export declare class LensLinkError extends Error {
+    readonly code: LensLinkErrorCode;
+    constructor(code: LensLinkErrorCode, message: string);
+}
+/** The file an app writes. The first lines say what it is to anyone who opens it. */
+export declare function sealLensLink(payload: LensLinkPayload, nonce?: string): string;
+/** Read a link file picked in Lens. Throws `LensLinkError` with a message worth showing. */
+export declare function readLensLink(text: string): LensLinkPayload;
+/** Where Lens connects for a link. */
+export declare function lensLinkUrl(payload: Pick<LensLinkPayload, "port">): string;
+/** Random hex from the platform. Drawn only when a link is made, never at import. */
+export declare function randomHex(byteCount: number): string;
+//# sourceMappingURL=link-file.d.ts.map

package/dist/cjs/link-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-file.d.ts","sourceRoot":"","sources":["../../src/link-file.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,eAAe;IAC9B,CAAC,EAAE,CAAC,CAAC;IACL,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,CAAC;AAEtF,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;gBAErB,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM;CAKrD;AAYD,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,GAAE,MAAsB,GAAG,MAAM,CAU5F;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAwC1D;AAED,sCAAsC;AACtC,wBAAgB,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,GAAG,MAAM,CAE1E;AAyED,qFAAqF;AACrF,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQnD"}