@dotobokuri/fleet-console 1.54.0 → 1.55.0

package/AGENTS.md

@@ -28,7 +28,7 @@
 ## Security and state constraints
 
 - The loopback listener's core browser APIs do not use bearer, admin, MCP, or session tokens. Loopback is not authorization: preserve route-specific Host and Origin gates.
-- A remote listener is the opposite default: every request it accepts requires a session, decided once before routing, and the only exceptions are the join endpoint and the static notice that explains an access link. Sessions are bound to the listener that issued them and never cross between loopback and remote.
+- A remote listener is the opposite default: every request it accepts requires a session, decided once before routing, and the only exception is the join endpoint. That endpoint is the one unauthenticated door on a public address, so it carries a failure budget per source and a global cap on concurrent attempts; the count of rejected attempts is reported to the owner rather than kept silent. Pairing happens only in the dedicated apps - a browser cannot check this console's certificate fingerprint - so the listener serves no browser-facing surface, not even an explanatory one. Sessions are bound to the listener that issued them and never cross between loopback and remote.
 - A session is an open connection; a pairing is the standing permission behind it, and the two never collapse into one. A single-use grant from an access link creates a pairing; after that the paired device reopens a session on its own, so ending a session — by reclaiming control, by idling out, or by restarting the console — never costs that device its way back. Unpairing and a new certificate do, and so does a device that stays away longer than the cookie carrying its secret: browsers cap that lifetime well below the certificate's, so each return renews it and only a dormant device ages out. Console stores a pairing's hash, never its secret, and the device carries the secret in a cookie the console sets.
 - A link publishes an address as much as a credential, and a device keeps only what the link told it. So the remote listener remembers the port it first opened on and reopens that one, rather than following the console's own port, which is free to move on every start; it never slides to another port on its own, because a device that cannot find the address it was given is unpaired in fact while the list still says otherwise. Releasing that port belongs with the acts that already void every pairing.
 - Console owns which other consoles this one can reach, and that list is reachable only from the loopback listener — a remote session must not enumerate or edit the addresses and certificate pins of third machines. A saved host stores where to go and what certificate to trust, never a credential; a link's single-use grant lives in memory until the shell takes it, and is handed over exactly once.

package/dist/access-protocol.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 액세스 링크는 주소·1회용 자격·서버 신원·이름을 하나의 봉투에 담아 `fleet://join?code=`로
+ * 실어 나른다. 주소를 URL 껍데기에 두지 않는 이유는 두 가지다 — 붙여넣는 사람 눈에 사설 IP와
+ * 포트가 드러나지 않고, 봉투가 버전을 가지므로 나중에 필드를 늘려도 옛 링크를 구분할 수 있다.
+ *
+ * 이 스킴은 브라우저가 따라갈 수 없다. 링크를 여는 주체는 Fleet 네이티브 셸(Desktop과 Mobile)이며,
+ * 브라우저 원격 접속은 별도 결정 전까지 열지 않는다.
+ *
+ * 링크를 신뢰한다는 것이 곧 그 서버를 신뢰한다는 뜻이므로 파싱은 관대할 이유가 없다. 모양이
+ * 어긋난 링크는 고쳐 쓰지 않고 거절한다.
+ */
+interface AccessLinkPayload {
+    readonly v: number;
+    /** `https://host:port`. origin 형태 그대로이며 경로·질의·fragment를 갖지 않는다. */
+    readonly endpoint: string;
+    readonly token: string;
+    /** 구분자 없는 대문자 SHA-256 hex. */
+    readonly fingerprint: string;
+    /** 발급한 콘솔이 스스로를 부르는 이름. 목록에서 호스트를 알아보는 유일한 단서다. */
+    readonly label: string;
+}
+interface ValidatedAccessLink {
+    readonly origin: string;
+    /** 인증서 핀의 키. URL이 대괄호로 감싼 IPv6 리터럴은 벗겨서 담는다. */
+    readonly hostname: string;
+    readonly port: number;
+    readonly label: string;
+    readonly consoleUrl: string;
+    readonly joinUrl: string;
+    readonly token: string;
+    readonly fingerprint: string;
+}
+declare const ACCESS_LINK_SCHEME = "fleet:";
+declare const ACCESS_LINK_HOST = "join";
+declare const ACCESS_LINK_PREFIX = "fleet://join?code=";
+declare const ACCESS_LINK_VERSION = 1;
+declare const ACCESS_JOIN_PATH = "/api/v1/join";
+declare const MAX_ACCESS_LABEL_LENGTH = 48;
+/** 링크 후보인지만 가른다 — 유효성은 parseAccessLink가 판정한다. */
+declare function isAccessLinkInput(value: string): boolean;
+declare function encodeAccessLink(payload: Omit<AccessLinkPayload, "v">): string;
+declare function parseAccessLink(input: string): ValidatedAccessLink;
+/** 인증서 핀은 호스트 단위다. Chromium은 검증기에 대괄호 없는 호스트명을 넘긴다. */
+declare function pinHostname(hostname: string): string;
+/**
+ * 링크와 UI가 같은 표기를 쓰도록 지문 비교는 항상 정규화한 뒤 수행한다. 콘솔은 구분자 없이
+ * 발급하지만 손으로 옮긴 콜론·공백 표기도 같은 값으로 본다.
+ *
+ * 지문 표기의 유일한 정의다 — 두 벌이 되면 한쪽만 고쳐진 채로 갈라진다.
+ */
+declare function normalizeFingerprint(value: string): string;
+/**
+ * 라벨은 목록에 그대로 그려지므로 제어문자와 방향 재정의 문자를 남겨 두지 않는다 — 호스트
+ * 이름이 옆줄의 주소를 가리는 형태로 읽히면 안 된다.
+ */
+declare function sanitizeAccessLabel(value: string): string;
+
+export { ACCESS_JOIN_PATH, ACCESS_LINK_HOST, ACCESS_LINK_PREFIX, ACCESS_LINK_SCHEME, ACCESS_LINK_VERSION, type AccessLinkPayload, MAX_ACCESS_LABEL_LENGTH, type ValidatedAccessLink, encodeAccessLink, isAccessLinkInput, normalizeFingerprint, parseAccessLink, pinHostname, sanitizeAccessLabel };

package/dist/access-protocol.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// access-protocol/index.ts
+var ACCESS_LINK_SCHEME = "fleet:";
+var ACCESS_LINK_HOST = "join";
+var ACCESS_LINK_PREFIX = "fleet://join?code=";
+var ACCESS_LINK_VERSION = 1;
+var ACCESS_JOIN_PATH = "/api/v1/join";
+var MAX_ACCESS_LABEL_LENGTH = 48;
+var MAX_ACCESS_LINK_LENGTH = 4096;
+var ACCESS_TOKEN = /^[A-Za-z0-9_-]{16,512}$/u;
+var CERTIFICATE_FINGERPRINT = /^[0-9A-F]{64}$/u;
+var PAYLOAD_KEYS = ["v", "endpoint", "token", "fingerprint", "label"];
+var BASE64_URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+var BASE64_URL_DECODE = createBase64UrlDecodeTable();
+function isAccessLinkInput(value) {
+  return value.trimStart().toLowerCase().startsWith("fleet://");
+}
+function encodeAccessLink(payload) {
+  const envelope = {
+    v: ACCESS_LINK_VERSION,
+    endpoint: payload.endpoint,
+    token: payload.token,
+    fingerprint: normalizeFingerprint(payload.fingerprint),
+    label: sanitizeAccessLabel(payload.label)
+  };
+  return `${ACCESS_LINK_PREFIX}${toBase64Url(new TextEncoder().encode(JSON.stringify(envelope)))}`;
+}
+function parseAccessLink(input) {
+  if (typeof input !== "string") throw invalidLink();
+  const candidate = input.trim();
+  if (candidate.length === 0 || candidate.length > MAX_ACCESS_LINK_LENGTH) throw invalidLink();
+  if (containsDisallowedLinkWhitespace(candidate)) throw invalidLink();
+  let url;
+  try {
+    url = new URL(candidate);
+  } catch {
+    throw invalidLink();
+  }
+  if (url.protocol !== ACCESS_LINK_SCHEME || url.username || url.password || url.hash) throw invalidLink();
+  if (url.hostname !== ACCESS_LINK_HOST || url.port !== "" || url.pathname !== "") throw invalidLink();
+  const keys = [...url.searchParams.keys()];
+  if (keys.length !== 1 || keys[0] !== "code") throw invalidLink();
+  return readPayload(decodePayload(url.searchParams.get("code") ?? ""));
+}
+function decodePayload(code) {
+  if (!/^[A-Za-z0-9_-]+$/u.test(code)) throw invalidLink();
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(fromBase64Url(code));
+  } catch {
+    throw invalidLink();
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw invalidLink();
+  }
+}
+function readPayload(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw invalidLink();
+  const entry = value;
+  const keys = Object.keys(entry);
+  if (keys.length !== PAYLOAD_KEYS.length || !PAYLOAD_KEYS.every((key) => keys.includes(key))) throw invalidLink();
+  if (entry.v !== ACCESS_LINK_VERSION) throw invalidLink();
+  if (typeof entry.endpoint !== "string" || typeof entry.token !== "string" || typeof entry.fingerprint !== "string" || typeof entry.label !== "string") throw invalidLink();
+  const endpoint = readEndpoint(entry.endpoint);
+  const token = entry.token;
+  const fingerprint = normalizeFingerprint(entry.fingerprint);
+  if (!ACCESS_TOKEN.test(token) || !CERTIFICATE_FINGERPRINT.test(fingerprint)) throw invalidLink();
+  const label = sanitizeAccessLabel(entry.label);
+  if (label.length === 0) throw invalidLink();
+  return {
+    origin: endpoint.origin,
+    hostname: pinHostname(endpoint.hostname),
+    port: endpoint.port,
+    label,
+    consoleUrl: new URL("/console/", endpoint.origin).toString(),
+    joinUrl: new URL(ACCESS_JOIN_PATH, endpoint.origin).toString(),
+    token,
+    fingerprint
+  };
+}
+function readEndpoint(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw invalidLink();
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) throw invalidLink();
+  if (url.pathname !== "/" && url.pathname !== "") throw invalidLink();
+  if (url.hostname.length === 0) throw invalidLink();
+  const port = url.port === "" ? 443 : Number(url.port);
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65535) throw invalidLink();
+  return { origin: url.origin, hostname: url.hostname, port };
+}
+function pinHostname(hostname) {
+  const unwrapped = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+  return unwrapped.toLowerCase();
+}
+function normalizeFingerprint(value) {
+  return value.replace(/[^0-9a-fA-F]/gu, "").toUpperCase();
+}
+function sanitizeAccessLabel(value) {
+  return Array.from(value).filter((character) => !isDisallowedAccessLabelCharacter(character.codePointAt(0))).join("").replace(/\s+/gu, " ").trim().slice(0, MAX_ACCESS_LABEL_LENGTH);
+}
+function containsDisallowedLinkWhitespace(value) {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0);
+    if (codePoint <= 31 || codePoint === 127 || isWhitespaceCharacter(character)) return true;
+  }
+  return false;
+}
+function isWhitespaceCharacter(character) {
+  return character.trim().length === 0;
+}
+function isDisallowedAccessLabelCharacter(codePoint) {
+  return codePoint <= 31 || codePoint >= 127 && codePoint <= 159 || codePoint >= 8203 && codePoint <= 8207 || codePoint === 8232 || codePoint === 8233 || codePoint >= 8234 && codePoint <= 8238 || codePoint >= 8294 && codePoint <= 8297;
+}
+function toBase64Url(bytes) {
+  let encoded = "";
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index];
+    const second = bytes[index + 1];
+    const third = bytes[index + 2];
+    encoded += BASE64_URL_ALPHABET[first >> 2];
+    encoded += BASE64_URL_ALPHABET[(first & 3) << 4 | (second ?? 0) >> 4];
+    if (second !== void 0) encoded += BASE64_URL_ALPHABET[(second & 15) << 2 | (third ?? 0) >> 6];
+    if (third !== void 0) encoded += BASE64_URL_ALPHABET[third & 63];
+  }
+  return encoded;
+}
+function fromBase64Url(value) {
+  if (value.length % 4 === 1) throw invalidLink();
+  const bytes = new Uint8Array(Math.floor(value.length * 6 / 8));
+  let buffer = 0;
+  let bits = 0;
+  let offset = 0;
+  for (const character of value) {
+    const decoded = BASE64_URL_DECODE[character.charCodeAt(0)] ?? -1;
+    if (decoded < 0) throw invalidLink();
+    buffer = buffer << 6 | decoded;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes[offset] = buffer >> bits & 255;
+      offset += 1;
+    }
+  }
+  if (bits > 0 && (buffer & (1 << bits) - 1) !== 0) throw invalidLink();
+  return bytes;
+}
+function createBase64UrlDecodeTable() {
+  const table = new Int16Array(128);
+  table.fill(-1);
+  for (let index = 0; index < BASE64_URL_ALPHABET.length; index += 1) {
+    table[BASE64_URL_ALPHABET.charCodeAt(index)] = index;
+  }
+  return table;
+}
+function invalidLink() {
+  return new Error("pairing_target_invalid");
+}
+
+export { ACCESS_JOIN_PATH, ACCESS_LINK_HOST, ACCESS_LINK_PREFIX, ACCESS_LINK_SCHEME, ACCESS_LINK_VERSION, MAX_ACCESS_LABEL_LENGTH, encodeAccessLink, isAccessLinkInput, normalizeFingerprint, parseAccessLink, pinHostname, sanitizeAccessLabel };