dextunnel 0.1.0

package/src/lib/surface-access.mjs

@@ -0,0 +1,189 @@
+import { createHmac, randomBytes } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { normalizeSurfaceName } from "./shared-room-state.mjs";
+
+export const DEFAULT_SURFACE_TOKEN_TTL_MS = 24 * 60 * 60 * 1000;
+
+export const SURFACE_CAPABILITIES = {
+  agent: [
+    "read_room",
+    "select_room",
+    "refresh_room",
+    "respond_interaction",
+    "control_remote",
+    "send_turn"
+  ],
+  host: [
+    "read_room",
+    "select_room",
+    "sync_presence",
+    "refresh_room",
+    "open_in_codex",
+    "respond_interaction",
+    "release_remote_control",
+    "debug_tools"
+  ],
+  remote: [
+    "read_room",
+    "select_room",
+    "sync_presence",
+    "refresh_room",
+    "open_in_codex",
+    "respond_interaction",
+    "control_remote",
+    "send_turn",
+    "use_companion",
+    "use_agent_room"
+  ]
+};
+
+export function defaultSurfaceAccessSecretPath({ cwd = process.cwd() } = {}) {
+  return path.join(cwd, ".agent", "artifacts", "runtime", "surface-access-secret.txt");
+}
+
+function signatureFor(secret, payload) {
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+function encodePayload(value) {
+  return Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+}
+
+function decodePayload(value) {
+  return JSON.parse(Buffer.from(String(value || ""), "base64url").toString("utf8"));
+}
+
+function surfaceAccessError(message, statusCode = 403) {
+  const error = new Error(message);
+  error.statusCode = statusCode;
+  return error;
+}
+
+export async function loadOrCreateSurfaceAccessSecret({
+  secretPath = defaultSurfaceAccessSecretPath()
+} = {}) {
+  try {
+    const existing = (await readFile(secretPath, "utf8")).trim();
+    if (existing) {
+      return existing;
+    }
+  } catch {}
+
+  const secret = randomBytes(32).toString("base64url");
+  await mkdir(path.dirname(secretPath), { recursive: true });
+  await writeFile(secretPath, `${secret}\n`, "utf8");
+  return secret;
+}
+
+export function createSurfaceAccessRegistry({
+  now = () => new Date().toISOString(),
+  nowMs = () => Date.now(),
+  ttlMs = DEFAULT_SURFACE_TOKEN_TTL_MS,
+  secret
+} = {}) {
+  if (!secret) {
+    throw new Error("createSurfaceAccessRegistry requires a signing secret.");
+  }
+
+  function issueBootstrap(surface = "remote") {
+    const nextSurface = normalizeSurfaceName(surface);
+    const capabilities = SURFACE_CAPABILITIES[nextSurface];
+    if (!capabilities) {
+      throw surfaceAccessError(`Unsupported surface: ${surface}`, 400);
+    }
+
+    const payload = {
+      clientId: `${nextSurface}-${randomBytes(10).toString("base64url")}`,
+      issuedAt: now(),
+      expiresAt: new Date(nowMs() + ttlMs).toISOString(),
+      nonce: randomBytes(12).toString("base64url"),
+      surface: nextSurface
+    };
+    const encoded = encodePayload(payload);
+    const signature = signatureFor(secret, encoded);
+
+    return {
+      accessToken: `${encoded}.${signature}`,
+      capabilities: [...capabilities],
+      clientId: payload.clientId,
+      expiresAt: payload.expiresAt,
+      issuedAt: payload.issuedAt,
+      surface: payload.surface
+    };
+  }
+
+  function resolve({ headers = {}, searchParams = null } = {}) {
+    const bearerToken = String(headers.authorization || "")
+      .replace(/^Bearer\s+/i, "")
+      .trim();
+    const headerToken = String(headers["x-dextunnel-surface-token"] || "").trim();
+    const queryToken = String(searchParams?.get?.("surfaceToken") || "").trim();
+    const token = bearerToken || headerToken || queryToken;
+    if (!token || !token.includes(".")) {
+      return null;
+    }
+
+    const [encoded, signature] = token.split(".", 2);
+    if (!encoded || !signature) {
+      return null;
+    }
+
+    const expected = signatureFor(secret, encoded);
+    if (signature !== expected) {
+      return null;
+    }
+
+    let payload = null;
+    try {
+      payload = decodePayload(encoded);
+    } catch {
+      return null;
+    }
+
+    const surface = normalizeSurfaceName(payload.surface);
+    const capabilities = SURFACE_CAPABILITIES[surface];
+    if (!capabilities) {
+      return null;
+    }
+    if (payload.expiresAt && new Date(payload.expiresAt).getTime() <= nowMs()) {
+      return null;
+    }
+
+    return {
+      accessToken: token,
+      capabilities: [...capabilities],
+      clientId: String(payload.clientId || "").trim() || null,
+      expiresAt: payload.expiresAt || null,
+      issuedAt: payload.issuedAt || null,
+      surface
+    };
+  }
+
+  function requireCapability({ capability, headers = {}, searchParams = null } = {}) {
+    const access = resolve({ headers, searchParams });
+    if (!access) {
+      throw surfaceAccessError("Dextunnel surface access is missing or expired.");
+    }
+    if (!access.capabilities.includes(capability)) {
+      throw surfaceAccessError(
+        `${access.surface} surface is not allowed to ${capability.replaceAll("_", " ")}.`
+      );
+    }
+    return access;
+  }
+
+  return {
+    issueBootstrap,
+    requireCapability,
+    resolve
+  };
+}
+
+export function injectSurfaceBootstrap(html, bootstrap) {
+  const script = `<script>window.__DEXTUNNEL_SURFACE_BOOTSTRAP__ = ${JSON.stringify(bootstrap)};</script>`;
+  return html.includes("</body>")
+    ? html.replace("</body>", `    ${script}\n  </body>`)
+    : `${html}\n${script}\n`;
+}

package/src/lib/surface-presence-service.mjs

@@ -0,0 +1,118 @@
+export function createSurfacePresenceService({
+  appServerState,
+  applySurfacePresenceUpdateState,
+  buildSelectedAttachmentsState,
+  countSurfacePresenceState,
+  defaultStaleMs = null,
+  liveState,
+  normalizeSurfaceName,
+  nowIso = () => new Date().toISOString(),
+  pruneStaleSurfacePresenceState,
+  randomId = () => `${Date.now()}`
+} = {}) {
+  function recordSurfaceEvent({ action, cause = "", surface = "", threadId = null } = {}) {
+    const nextThreadId = String(threadId || "").trim();
+    const nextAction = action === "attach" ? "attach" : action === "detach" ? "detach" : "";
+    const nextSurface = normalizeSurfaceName(surface);
+    if (!nextThreadId || !nextAction || !nextSurface) {
+      return null;
+    }
+
+    const event = {
+      action: nextAction,
+      at: nowIso(),
+      cause: String(cause || "").trim() || null,
+      id: randomId(),
+      surface: nextSurface,
+      threadId: nextThreadId
+    };
+    appServerState.lastSurfaceEvent = event;
+    return event;
+  }
+
+  function pruneStaleSurfacePresence({ now = Date.now(), staleMs = defaultStaleMs } = {}) {
+    if (!Number.isFinite(staleMs)) {
+      return false;
+    }
+
+    const result = pruneStaleSurfacePresenceState(liveState.surfacePresenceByClientId, {
+      now,
+      staleMs
+    });
+
+    if (result.changed) {
+      liveState.surfacePresenceByClientId = result.nextPresenceByClientId;
+      for (const event of result.events) {
+        recordSurfaceEvent(event);
+      }
+    }
+
+    return result.changed;
+  }
+
+  function countSurfacePresence(threadId, surface) {
+    return countSurfacePresenceState(liveState.surfacePresenceByClientId, threadId, surface);
+  }
+
+  function applySurfacePresenceUpdate(payload = {}, { now = Date.now(), selectedThreadId = "" } = {}) {
+    const result = applySurfacePresenceUpdateState(liveState.surfacePresenceByClientId, payload, {
+      now,
+      selectedThreadId
+    });
+
+    if (result.changed) {
+      liveState.surfacePresenceByClientId = result.nextPresenceByClientId;
+      for (const event of result.events) {
+        recordSurfaceEvent(event);
+      }
+    }
+
+    return result.changed;
+  }
+
+  function upsertSurfacePresence(payload = {}, { now = Date.now(), selectedThreadId = liveState.selectedThreadId || "" } = {}) {
+    pruneStaleSurfacePresence({ now });
+    return applySurfacePresenceUpdate(
+      {
+        ...payload,
+        detach: false,
+        threadId: payload.threadId || liveState.selectedThreadId || ""
+      },
+      {
+        now,
+        selectedThreadId
+      }
+    );
+  }
+
+  function removeSurfacePresence(clientId, { now = Date.now(), selectedThreadId = liveState.selectedThreadId || "" } = {}) {
+    return applySurfacePresenceUpdate(
+      {
+        clientId,
+        detach: true
+      },
+      {
+        now,
+        selectedThreadId
+      }
+    );
+  }
+
+  function buildSelectedAttachments(
+    threadId = liveState.selectedThreadId || liveState.selectedThreadSnapshot?.thread?.id || null,
+    { now = Date.now(), staleMs = defaultStaleMs } = {}
+  ) {
+    pruneStaleSurfacePresence({ now, staleMs });
+    return buildSelectedAttachmentsState(liveState.surfacePresenceByClientId, threadId);
+  }
+
+  return {
+    applySurfacePresenceUpdate,
+    buildSelectedAttachments,
+    countSurfacePresence,
+    pruneStaleSurfacePresence,
+    recordSurfaceEvent,
+    removeSurfacePresence,
+    upsertSurfacePresence
+  };
+}

package/src/lib/surface-request-guard.mjs

@@ -0,0 +1,52 @@
+function normalizeAddress(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
+function normalizeComparableAddress(value) {
+  const address = normalizeAddress(value);
+  if (address.startsWith("::ffff:")) {
+    return address.slice(7);
+  }
+  return address;
+}
+
+export function isLoopbackAddress(value) {
+  const address = normalizeComparableAddress(value);
+  if (!address) {
+    return false;
+  }
+
+  return (
+    address === "::1" ||
+    address === "::ffff:127.0.0.1" ||
+    address === "127.0.0.1" ||
+    address.startsWith("127.")
+  );
+}
+
+export function isSameMachineAddress(remoteAddress, localAddress) {
+  const remote = normalizeComparableAddress(remoteAddress);
+  const local = normalizeComparableAddress(localAddress);
+  if (!remote || !local) {
+    return false;
+  }
+  return remote === local;
+}
+
+export function canServeSurfaceBootstrap({
+  exposeHostSurface = false,
+  localAddress = "",
+  pathname = "",
+  remoteAddress = ""
+} = {}) {
+  const nextPath = String(pathname || "").trim();
+  if (nextPath !== "/host.html" && nextPath !== "host.html") {
+    return true;
+  }
+
+  return (
+    Boolean(exposeHostSurface) ||
+    isLoopbackAddress(remoteAddress) ||
+    isSameMachineAddress(remoteAddress, localAddress)
+  );
+}