@hellolynk-ai/codex-plugin 0.0.0-stage → 0.2.100

package/plugins/hellolynk-codex/runtime/bootstrap/core/hellolynk-client-profile.mjs

@@ -0,0 +1,191 @@
+import { lstat, mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import {
+  assertCredentialProfileId,
+  runWindowsClientTrustCommand,
+} from "./hellolynk-platform-credential-store.mjs";
+import { normalizeHelloLynkBaseUrl } from "./hellolynk-client-core.mjs";
+import runtimeSafety from "./hellolynk-runtime-safety.cjs";
+
+const {
+  containsHelloLynkCredentialMaterial,
+  normalizeHelloLynkClientProfileContainer,
+} = runtimeSafety;
+
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{2,127}$/;
+const SAFE_SCOPE = /^[a-z][a-z0-9_.:-]{0,127}$/;
+const MAX_PROFILE_BYTES = 64 * 1024;
+
+export function defaultHelloLynkClientRoot(platform = process.platform, env = process.env) {
+  const home = resolve(String(env.HOME || env.USERPROFILE || homedir()));
+  if (platform === "win32") return resolve(String(env.LOCALAPPDATA || join(home, "AppData", "Local")), "HelloLynk");
+  if (platform === "darwin") return join(home, "Library", "Application Support", "HelloLynk");
+  return resolve(String(env.XDG_DATA_HOME || join(home, ".local", "share")), "hellolynk");
+}
+
+function safeId(value, code) {
+  const normalized = String(value || "").trim();
+  if (!SAFE_ID.test(normalized)) throw new Error(code);
+  return normalized;
+}
+
+function validateProfile(value) {
+  const allowedScopes = Array.isArray(value.allowedScopes) ? value.allowedScopes.map((scope) => {
+    const normalized = String(scope || "");
+    if (!SAFE_SCOPE.test(normalized)) throw new Error("client_profile_scope_invalid");
+    return normalized;
+  }) : [];
+  const schemaVersion = value.schemaVersion == null ? 1 : Number(value.schemaVersion);
+  if (![1, 2].includes(schemaVersion)) throw new Error("client_profile_schema_unsupported");
+  const delegateId = value.delegateId == null
+    ? null : safeId(value.delegateId, "client_profile_delegate_id_invalid");
+  const hostId = value.hostId == null ? null : safeId(value.hostId, "client_profile_host_id_invalid");
+  const authorizationVersion = value.authorizationVersion == null ? null : Number(value.authorizationVersion);
+  if (
+    (schemaVersion === 1 && (hostId != null || authorizationVersion != null))
+    || (schemaVersion === 2 && (
+      !delegateId || !hostId || !Number.isSafeInteger(authorizationVersion) || authorizationVersion < 1
+    ))
+  ) throw new Error("client_profile_route_binding_invalid");
+  return {
+    contract: value.contract,
+    schemaVersion,
+    profileId: assertCredentialProfileId(value.profileId),
+    baseUrl: normalizeHelloLynkBaseUrl(value.baseUrl, { allowLoopbackHttp: value.allowLoopbackHttp === true }),
+    allowLoopbackHttp: value.allowLoopbackHttp === true,
+    deviceId: safeId(value.deviceId, "client_profile_device_id_invalid"),
+    credentialId: safeId(value.credentialId, "client_profile_credential_id_invalid"),
+    principalId: safeId(value.principalId, "client_profile_principal_id_invalid"),
+    hellolynkId: value.hellolynkId == null ? null : safeId(value.hellolynkId, "client_profile_hellolynk_id_invalid"),
+    agentId: safeId(value.agentId, "client_profile_agent_id_invalid"),
+    delegateId,
+    ...(schemaVersion === 2 ? { hostId, authorizationVersion } : {}),
+    region: safeId(value.region, "client_profile_region_invalid"),
+    allowedScopes,
+    platform: String(value.platform || process.platform),
+  };
+}
+
+async function atomicWriteJson(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  const body = `${JSON.stringify(value, null, 2)}\n`;
+  const handle = await open(temporary, "wx", 0o600);
+  try {
+    await handle.writeFile(body, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+function windowsClientFile(path, category) {
+  const requested = String(path || "");
+  if (!requested || !isAbsolute(requested)) throw new Error("client_root_path_invalid");
+  const absolute = resolve(requested);
+  const parent = dirname(absolute);
+  const profileId = assertCredentialProfileId(basename(absolute, ".json"));
+  const clientRoot = dirname(parent);
+  if (
+    basename(parent).toLowerCase() !== category
+    || absolute.toLowerCase() !== join(clientRoot, category, `${profileId}.json`).toLowerCase()
+  ) throw new Error("client_root_path_invalid");
+  return { clientRoot, profileId };
+}
+
+async function writeWindowsClientJson(path, category, command, value) {
+  const target = windowsClientFile(path, category);
+  await runWindowsClientTrustCommand(command, {
+    ...target,
+    stdin: `${JSON.stringify(value, null, 2)}\n`,
+  });
+}
+
+export async function writeClientProfile(path, value) {
+  const original = JSON.stringify(value);
+  if (containsHelloLynkCredentialMaterial(original)) {
+    throw new Error("client_profile_contains_secret");
+  }
+  const container = normalizeHelloLynkClientProfileContainer(value);
+  const profile = validateProfile(container.value);
+  const serialized = JSON.stringify(profile);
+  if (containsHelloLynkCredentialMaterial(serialized)) {
+    throw new Error("client_profile_contains_secret");
+  }
+  if (process.platform === "win32") {
+    await writeWindowsClientJson(path, "profiles", "StoreProfile", profile);
+  } else {
+    await atomicWriteJson(path, profile);
+  }
+  return profile;
+}
+
+export async function readClientProfile(path) {
+  const body = await readClientProfileBody(path);
+  const container = normalizeHelloLynkClientProfileContainer(JSON.parse(body));
+  return validateProfile(container.value);
+}
+
+// A profile holds no secret, so Windows reads it directly too, avoiding
+// one helper process per profile. Writes keep the helper.
+async function readClientProfileBody(path) {
+  const windows = process.platform === "win32";
+  if (windows) windowsClientFile(path, "profiles");
+  let metadata;
+  try { metadata = await (windows ? lstat : stat)(path); }
+  catch (error) { throw windows && error?.code === "ENOENT" ? new Error("client_profile_missing") : error; }
+  if (!metadata.isFile()) throw new Error("client_profile_not_regular_file");
+  if (metadata.size > MAX_PROFILE_BYTES) throw new Error("client_profile_too_large");
+  const bytes = await readFile(path);
+  if (bytes.length > MAX_PROFILE_BYTES) throw new Error("client_profile_too_large");
+  let body;
+  try { body = new TextDecoder("utf-8", { fatal: true }).decode(bytes); }
+  catch { throw new Error("client_profile_invalid_utf8"); }
+  if (containsHelloLynkCredentialMaterial(body)) throw new Error("client_profile_contains_secret");
+  return body;
+}
+
+export async function writeSanitizedHostStatus(path, value) {
+  const runtimeSessionExpiresAt = value.runtimeSessionExpiresAt == null
+    ? null
+    : new Date(value.runtimeSessionExpiresAt).toISOString();
+  const status = {
+    schemaVersion: 1,
+    checkedAt: new Date(value.checkedAt || Date.now()).toISOString(),
+    ok: value.ok === true,
+    serviceReachable: value.serviceReachable === true,
+    credentialPresent: value.credentialPresent === true,
+    runtimeSessionReady: value.runtimeSessionReady === true,
+    runtimeSessionExpiresAt,
+    messageReceiverReady: value.messageReceiverReady === true,
+    lastPollStatus: ["no_messages", "events_projected", "receiver_error"].includes(value.lastPollStatus)
+      ? value.lastPollStatus
+      : null,
+    newEventCount: Number.isSafeInteger(Number(value.newEventCount)) && Number(value.newEventCount) >= 0
+      ? Number(value.newEventCount)
+      : 0,
+    newNotificationCount: Number.isSafeInteger(Number(value.newNotificationCount)) && Number(value.newNotificationCount) >= 0
+      ? Number(value.newNotificationCount)
+      : 0,
+    platform: String(value.platform || process.platform),
+    errorCode: value.errorCode == null ? null : String(value.errorCode),
+  };
+  const serialized = JSON.stringify(status);
+  if (containsHelloLynkCredentialMaterial(serialized)) {
+    throw new Error("host_status_contains_secret");
+  }
+  if (process.platform === "win32") {
+    await writeWindowsClientJson(path, "status", "StoreStatus", status);
+  } else {
+    await atomicWriteJson(path, status);
+  }
+  return status;
+}

package/plugins/hellolynk-codex/runtime/bootstrap/core/hellolynk-host-auth.mjs

@@ -0,0 +1,347 @@
+import crypto from "node:crypto";
+
+export const HELLOLYNK_HOST_REQUEST_AUTH_DOMAIN = "hellolynk-host-request-v1";
+export const HELLOLYNK_HOST_REQUEST_MAX_SKEW_MS = 30_000;
+export const HELLOLYNK_HOST_NONCE_TTL_MS = 90_000;
+export const HELLOLYNK_HOST_NONCE_CACHE_MAX_ENTRIES = 4_096;
+// One installed capability is shared by every open conversation, receiver and
+// card. Its replay history may use the existing Host-wide budget; a smaller
+// default quota throttles ordinary reads and then rejects unrelated new sends.
+export const HELLOLYNK_HOST_NONCE_CACHE_MAX_ENTRIES_PER_CAPABILITY = HELLOLYNK_HOST_NONCE_CACHE_MAX_ENTRIES;
+export const HELLOLYNK_HOST_CAPABILITY_CONTRACT = "hellolynk-host-capability-v1";
+
+export const HELLOLYNK_HOST_AUTH_HEADERS = Object.freeze({
+  capabilityId: "x-hellolynk-host-capability-id",
+  adapterId: "x-hellolynk-host-adapter-id",
+  hostGeneration: "x-hellolynk-host-generation",
+  timestampMs: "x-hellolynk-host-timestamp",
+  nonce: "x-hellolynk-host-nonce",
+  proof: "x-hellolynk-host-proof",
+});
+
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._:-]{0,126}[A-Za-z0-9])?$/;
+const GENERATION_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9_-]{0,126}[A-Za-z0-9])?$/;
+const NONCE_PATTERN = /^[A-Za-z0-9_-]{22,128}$/;
+const PROOF_PATTERN = /^[a-f0-9]{64}$/;
+
+export function sha256RawBody(rawBody) {
+  return crypto.createHash("sha256").update(asRawBody(rawBody)).digest("hex");
+}
+
+export function createHostRequestAuth(input) {
+  const normalized = normalizeRequestAuthInput(input);
+  const proof = crypto
+    .createHmac("sha256", normalized.secretBuffer)
+    .update(normalized.message, "utf8")
+    .digest("hex");
+  return {
+    capabilityId: normalized.capabilityId,
+    adapterId: normalized.adapterId,
+    hostGeneration: normalized.hostGeneration,
+    timestampMs: normalized.timestampMs,
+    nonce: normalized.nonce,
+    bodySha256: normalized.bodySha256,
+    proof,
+    headers: {
+      [HELLOLYNK_HOST_AUTH_HEADERS.capabilityId]: normalized.capabilityId,
+      [HELLOLYNK_HOST_AUTH_HEADERS.adapterId]: normalized.adapterId,
+      [HELLOLYNK_HOST_AUTH_HEADERS.hostGeneration]: normalized.hostGeneration,
+      [HELLOLYNK_HOST_AUTH_HEADERS.timestampMs]: String(normalized.timestampMs),
+      [HELLOLYNK_HOST_AUTH_HEADERS.nonce]: normalized.nonce,
+      [HELLOLYNK_HOST_AUTH_HEADERS.proof]: proof,
+    },
+  };
+}
+
+export function hostRequestAuthMatches(input) {
+  try {
+    const expected = createHostRequestAuth(input).proof;
+    const candidate = String(input?.proof || "").toLowerCase();
+    if (!PROOF_PATTERN.test(candidate)) return false;
+    return crypto.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(candidate, "hex"));
+  } catch {
+    return false;
+  }
+}
+
+export function canonicalHostRequestMessage(input) {
+  return normalizeRequestAuthInput(input).message;
+}
+
+export function createHostNonce(bytes = 24) {
+  if (!Number.isSafeInteger(bytes) || bytes < 16 || bytes > 64) {
+    throw codeError("host_nonce_size_invalid");
+  }
+  return crypto.randomBytes(bytes).toString("base64url");
+}
+
+export function createNonceReplayGuard(options = {}) {
+  const now = normalizeNow(options.clock);
+  const ttlMs = normalizePositiveInteger(options.ttlMs, HELLOLYNK_HOST_NONCE_TTL_MS, 1_000, 1_800_001);
+  const maxEntries = normalizePositiveInteger(
+    options.maxEntries,
+    HELLOLYNK_HOST_NONCE_CACHE_MAX_ENTRIES,
+    1,
+    65_536,
+  );
+  const maxEntriesPerCapability = normalizePositiveInteger(
+    options.maxEntriesPerCapability,
+    Math.min(HELLOLYNK_HOST_NONCE_CACHE_MAX_ENTRIES_PER_CAPABILITY, maxEntries),
+    1,
+    maxEntries,
+  );
+  const entries = new Map();
+  const capabilityEntryCounts = new Map();
+
+  function consume(capabilityId, nonce, timestampMs) {
+    const normalizedCapabilityId = assertIdentifier(capabilityId, "host_capability_id_invalid");
+    const normalizedNonce = assertNonce(nonce);
+    const normalizedTimestamp = assertTimestamp(timestampMs);
+    const current = assertTimestamp(now());
+    prune(current);
+    const key = `${normalizedCapabilityId}\0${normalizedNonce}`;
+    if (entries.has(key)) return false;
+    const capabilityEntryCount = capabilityEntryCounts.get(normalizedCapabilityId) || 0;
+    if (capabilityEntryCount >= maxEntriesPerCapability) {
+      throw codeError("host_nonce_capability_cache_full");
+    }
+    if (entries.size >= maxEntries) throw codeError("host_nonce_cache_full");
+    entries.set(key, {
+      capabilityId: normalizedCapabilityId,
+      expiresAt: Math.max(current, normalizedTimestamp) + ttlMs,
+    });
+    capabilityEntryCounts.set(normalizedCapabilityId, capabilityEntryCount + 1);
+    return true;
+  }
+
+  function prune(current = assertTimestamp(now())) {
+    for (const [key, entry] of entries) {
+      if (entry.expiresAt <= current) {
+        entries.delete(key);
+        const count = capabilityEntryCounts.get(entry.capabilityId) || 0;
+        if (count <= 1) capabilityEntryCounts.delete(entry.capabilityId);
+        else capabilityEntryCounts.set(entry.capabilityId, count - 1);
+      }
+    }
+  }
+
+  return {
+    consume,
+    prune,
+    get size() {
+      prune();
+      return entries.size;
+    },
+    sizeForCapability(capabilityId) {
+      prune();
+      return capabilityEntryCounts.get(assertIdentifier(capabilityId, "host_capability_id_invalid")) || 0;
+    },
+  };
+}
+
+export function assertRequestFresh(timestampMs, nowMs, maxSkewMs = HELLOLYNK_HOST_REQUEST_MAX_SKEW_MS) {
+  const timestamp = assertTimestamp(timestampMs);
+  const current = assertTimestamp(nowMs);
+  const allowedSkew = normalizePositiveInteger(maxSkewMs, HELLOLYNK_HOST_REQUEST_MAX_SKEW_MS, 1, 300_000);
+  if (Math.abs(current - timestamp) > allowedSkew) throw codeError("host_request_stale");
+  return timestamp;
+}
+
+export function assertCapabilityRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw codeError("host_capability_invalid");
+  }
+  const expectedKeys = [
+    "adapterId",
+    "capabilityId",
+    "contract",
+    "delegateId",
+    "hostInstallationId",
+    "issuedAt",
+    "principalId",
+    "region",
+    "revokedAt",
+    "scopes",
+    "secretBuffer",
+    "state",
+    "version",
+  ];
+  const actualKeys = Object.keys(value).sort();
+  if (
+    actualKeys.length !== expectedKeys.length
+    || actualKeys.some((key, index) => key !== expectedKeys[index])
+  ) {
+    throw codeError("host_capability_fields_invalid");
+  }
+  if (value.contract !== HELLOLYNK_HOST_CAPABILITY_CONTRACT) {
+    throw codeError("host_capability_contract_invalid");
+  }
+  const capabilityId = assertIdentifier(value.capabilityId, "host_capability_id_invalid");
+  const region = assertIdentifier(value.region, "host_capability_region_invalid");
+  const principalId = assertIdentifier(value.principalId, "host_principal_id_invalid");
+  const adapterId = assertIdentifier(value.adapterId, "host_adapter_id_invalid");
+  const delegateId = assertIdentifier(value.delegateId, "host_delegate_id_invalid");
+  const hostInstallationId = assertIdentifier(
+    value.hostInstallationId,
+    "host_installation_id_invalid",
+  );
+  const version = Number(value.version);
+  if (!Number.isSafeInteger(version) || version < 1) throw codeError("host_capability_version_invalid");
+  if (value.state !== "active") throw codeError("host_capability_inactive");
+  const issuedAt = assertTimestamp(value.issuedAt);
+  if (value.revokedAt !== null) throw codeError("host_capability_revoked_at_invalid");
+  if (!Array.isArray(value.scopes) || value.scopes.length > 64) {
+    throw codeError("host_capability_scopes_invalid");
+  }
+  const scopes = value.scopes.map((scope) => (
+    assertIdentifier(scope, "host_capability_scope_invalid")
+  ));
+  const canonicalScopes = [...new Set(scopes)].sort();
+  if (
+    canonicalScopes.length !== scopes.length
+    || canonicalScopes.some((scope, index) => scope !== scopes[index])
+  ) {
+    throw codeError("host_capability_scopes_noncanonical");
+  }
+  const secretBuffer = assertSecretBuffer(value.secretBuffer);
+  return Object.freeze({
+    contract: HELLOLYNK_HOST_CAPABILITY_CONTRACT,
+    capabilityId,
+    region,
+    principalId,
+    delegateId,
+    hostInstallationId,
+    adapterId,
+    version,
+    state: "active",
+    scopes: Object.freeze(scopes),
+    issuedAt,
+    revokedAt: null,
+    secretBuffer,
+  });
+}
+
+export function assertIdentifier(value, errorCode = "host_identifier_invalid") {
+  const identifier = String(value || "");
+  if (!IDENTIFIER_PATTERN.test(identifier)) throw codeError(errorCode);
+  return identifier;
+}
+
+export function assertHostGeneration(value) {
+  const generation = String(value || "");
+  if (!GENERATION_PATTERN.test(generation)) throw codeError("host_generation_invalid");
+  return generation;
+}
+
+export function assertNonce(value) {
+  const nonce = String(value || "");
+  if (!NONCE_PATTERN.test(nonce)) throw codeError("host_nonce_invalid");
+  return nonce;
+}
+
+export function assertPathname(value) {
+  const pathname = String(value || "");
+  if (
+    !pathname.startsWith("/")
+    || pathname.length > 512
+    || pathname.includes("?")
+    || pathname.includes("#")
+    || pathname.includes("\r")
+    || pathname.includes("\n")
+    || pathname.includes("\\")
+  ) {
+    throw codeError("host_pathname_invalid");
+  }
+  return pathname;
+}
+
+export function assertMethod(value) {
+  const method = String(value || "");
+  if (!/^[A-Z]{3,12}$/.test(method)) throw codeError("host_method_invalid");
+  return method;
+}
+
+export function asRawBody(value) {
+  if (Buffer.isBuffer(value)) return value;
+  if (value instanceof Uint8Array) return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  if (typeof value === "string") return Buffer.from(value, "utf8");
+  if (value == null) return Buffer.alloc(0);
+  throw codeError("host_raw_body_invalid");
+}
+
+function normalizeRequestAuthInput(input = {}) {
+  const capabilityId = assertIdentifier(input.capabilityId, "host_capability_id_invalid");
+  const adapterId = assertIdentifier(input.adapterId, "host_adapter_id_invalid");
+  const method = assertMethod(input.method);
+  const pathname = assertPathname(input.pathname);
+  const hostGeneration = assertHostGeneration(input.hostGeneration);
+  const timestampMs = assertTimestamp(input.timestampMs);
+  const nonce = assertNonce(input.nonce);
+  const secretBuffer = assertSecretBuffer(input.secretBuffer);
+  const bodySha256 = sha256RawBody(input.rawBody);
+  const message = [
+    HELLOLYNK_HOST_REQUEST_AUTH_DOMAIN,
+    capabilityId,
+    adapterId,
+    method,
+    pathname,
+    hostGeneration,
+    String(timestampMs),
+    nonce,
+    bodySha256,
+  ].join("\n");
+  return {
+    capabilityId,
+    adapterId,
+    method,
+    pathname,
+    hostGeneration,
+    timestampMs,
+    nonce,
+    secretBuffer,
+    bodySha256,
+    message,
+  };
+}
+
+function assertSecretBuffer(value) {
+  const secret = Buffer.isBuffer(value)
+    ? Buffer.from(value)
+    : value instanceof Uint8Array
+      ? Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+      : null;
+  if (!secret || secret.length < 32 || secret.length > 128) {
+    throw codeError("host_capability_secret_invalid");
+  }
+  return secret;
+}
+
+function assertTimestamp(value) {
+  if (typeof value !== "number" && !/^(?:0|[1-9][0-9]{0,15})$/.test(String(value || ""))) {
+    throw codeError("host_timestamp_invalid");
+  }
+  const timestamp = typeof value === "number" ? value : Number(value);
+  if (!Number.isSafeInteger(timestamp) || timestamp < 0) throw codeError("host_timestamp_invalid");
+  return timestamp;
+}
+
+function normalizeNow(clock) {
+  if (clock == null) return () => Date.now();
+  if (typeof clock === "function") return clock;
+  if (typeof clock?.now === "function") return () => clock.now();
+  throw codeError("host_clock_invalid");
+}
+
+function normalizePositiveInteger(value, fallback, minimum, maximum) {
+  const normalized = Number(value ?? fallback);
+  if (!Number.isSafeInteger(normalized) || normalized < minimum || normalized > maximum) {
+    throw codeError("host_limit_invalid");
+  }
+  return normalized;
+}
+
+function codeError(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}