@memorax/memorax-code 0.1.4 → 0.1.6

package/lib/trial-provision-client.mjs

@@ -0,0 +1,307 @@
+const DEFAULT_SERVICE_BASE_URL = "https://platform.memorax.net";
+const PROVISION_PATH = "/account/api/v1/trial/provision";
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 16_384;
+const MAX_RETRY_AFTER_MS = 120_000;
+const MARK_ID_PATTERN = /^mk_[0-9a-f]{64}$/;
+const API_KEY_PATTERN = /^sk_[A-Za-z0-9_-]{43}$/;
+const MACHINE_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+const ERROR_REASONS = new Set([
+  "invalid_options",
+  "invalid_service_url",
+  "tls_unsafe",
+  "invalid_request",
+  "aborted",
+  "timeout",
+  "transport",
+  "response_too_large",
+  "invalid_response",
+  "response_contract",
+  "rate_limit_exceeded",
+  "server_error",
+  "server_rejected",
+]);
+
+export class TrialProvisionClientError extends Error {
+  constructor(reason, fields = {}) {
+    const safeReason = ERROR_REASONS.has(reason) ? reason : "invalid_response";
+    super(`Trial provision request failed (${safeReason})`);
+    this.name = "TrialProvisionClientError";
+    this.code = "TRIAL_PROVISION_CLIENT_FAILED";
+    this.reason = safeReason;
+    if (Number.isInteger(fields.httpStatus)) this.httpStatus = fields.httpStatus;
+    if (Number.isSafeInteger(fields.retryAfterMs)
+      && fields.retryAfterMs >= 0
+      && fields.retryAfterMs <= MAX_RETRY_AFTER_MS) {
+      this.retryAfterMs = fields.retryAfterMs;
+    }
+  }
+}
+
+export function createTrialProvisionClient(options = {}) {
+  const serviceBaseUrl = validateServiceBaseUrl(
+    options.serviceBaseUrl ?? DEFAULT_SERVICE_BASE_URL,
+  );
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") throw clientError("invalid_options");
+  const env = isRecord(options.env) ? options.env : process.env;
+  if (process.env.NODE_TLS_REJECT_UNAUTHORIZED === "0"
+    || env.NODE_TLS_REJECT_UNAUTHORIZED === "0") {
+    throw clientError("tls_unsafe");
+  }
+  const timeoutMs = positiveInteger(options.timeoutMs ?? DEFAULT_TIMEOUT_MS, 120_000);
+  const maxResponseBytes = positiveInteger(
+    options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES,
+    DEFAULT_MAX_RESPONSE_BYTES,
+  );
+
+  return Object.freeze({
+    async provision(request, requestOptions = {}) {
+      const snapshot = validateRequest(request);
+      const body = JSON.stringify({
+        mark_id: snapshot.markId,
+        mark_version: snapshot.markVersion,
+        app_salt: snapshot.appSalt,
+        machine_id: snapshot.machineId,
+        hostname: snapshot.hostname,
+        platform: snapshot.platform,
+        arch: snapshot.arch,
+        mac_hash: snapshot.macHash,
+      });
+      const response = await postJson(
+        `${serviceBaseUrl}${PROVISION_PATH}`,
+        body,
+        {
+          fetchImpl,
+          maxResponseBytes,
+          signal: requestOptions.signal,
+          timeoutMs,
+        },
+      );
+      return mapProvisionResponse(response, snapshot.markId);
+    },
+  });
+}
+
+async function postJson(url, body, options) {
+  const externalSignal = options.signal;
+  if (externalSignal?.aborted) throw clientError("aborted");
+  const controller = new AbortController();
+  let timedOut = false;
+  const onAbort = () => controller.abort();
+  externalSignal?.addEventListener?.("abort", onAbort, { once: true });
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, options.timeoutMs);
+  timer.unref?.();
+
+  try {
+    const response = await options.fetchImpl(url, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+      },
+      body,
+      cache: "no-store",
+      credentials: "omit",
+      redirect: "error",
+      signal: controller.signal,
+    });
+    return await readResponse(response, options.maxResponseBytes);
+  } catch (error) {
+    if (error instanceof TrialProvisionClientError) throw error;
+    if (timedOut) throw clientError("timeout");
+    if (externalSignal?.aborted) throw clientError("aborted");
+    throw clientError("transport");
+  } finally {
+    clearTimeout(timer);
+    externalSignal?.removeEventListener?.("abort", onAbort);
+  }
+}
+
+async function readResponse(response, maxResponseBytes) {
+  const status = response?.status;
+  if (!Number.isInteger(status) || status < 100 || status > 599) {
+    throw clientError("invalid_response");
+  }
+  const contentLength = response.headers?.get?.("content-length");
+  if (/^[0-9]+$/.test(contentLength ?? "")
+    && Number(contentLength) > maxResponseBytes) {
+    throw clientError("response_too_large", { httpStatus: status });
+  }
+
+  const text = await readResponseBody(response, maxResponseBytes, status);
+
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    if (status !== 200) throw responseError(status, response);
+    throw clientError("invalid_response", { httpStatus: status });
+  }
+  if (status !== 200) {
+    throw responseError(status, response, body);
+  }
+  if (!isRecord(body)) throw clientError("invalid_response", { httpStatus: status });
+  if (body.success !== true) throw responseError(status, response, body);
+  return body;
+}
+
+async function readResponseBody(response, maxResponseBytes, status) {
+  if (response.body == null) return "";
+  const reader = response.body.getReader?.();
+  if (!reader || typeof reader.read !== "function") {
+    throw clientError("invalid_response", { httpStatus: status });
+  }
+  const chunks = [];
+  let byteLength = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!(value instanceof Uint8Array)) {
+        throw clientError("invalid_response", { httpStatus: status });
+      }
+      byteLength += value.byteLength;
+      if (byteLength > maxResponseBytes) {
+        await reader.cancel().catch(() => undefined);
+        throw clientError("response_too_large", { httpStatus: status });
+      }
+      chunks.push(Buffer.from(value));
+    }
+  } finally {
+    reader.releaseLock?.();
+  }
+  return Buffer.concat(chunks, byteLength).toString("utf8");
+}
+
+function responseError(status, response, body) {
+  const retryAfterMs = retryAfterDelay(response.headers?.get?.("retry-after"), body);
+  if (status === 429) {
+    return clientError("rate_limit_exceeded", { httpStatus: status, retryAfterMs });
+  }
+  if (status >= 500) {
+    return clientError("server_error", { httpStatus: status, retryAfterMs });
+  }
+  return clientError("server_rejected", { httpStatus: status, retryAfterMs });
+}
+
+function mapProvisionResponse(envelope, expectedMarkId) {
+  const data = envelope.data;
+  const accountId = decimalPublicId(data?.account_id);
+  const projectId = decimalPublicId(data?.project_id);
+  const apiKey = typeof data?.api_key === "string" && API_KEY_PATTERN.test(data.api_key)
+    ? data.api_key
+    : undefined;
+  const keyPrefix = typeof data?.key_prefix === "string" ? data.key_prefix.trim() : "";
+  if (!accountId
+    || !projectId
+    || data?.mark_id !== expectedMarkId
+    || !apiKey
+    || !keyPrefix
+    || !apiKey.startsWith(keyPrefix)
+    || typeof data?.created !== "boolean") {
+    throw clientError("response_contract", { httpStatus: 200 });
+  }
+  return Object.freeze({
+    accountId,
+    projectId,
+    apiKey,
+    created: data.created,
+  });
+}
+
+function validateRequest(request) {
+  const snapshot = {
+    markId: request?.markId,
+    markVersion: request?.markVersion,
+    appSalt: request?.appSalt,
+    machineId: request?.machineId,
+    hostname: request?.hostname,
+    platform: request?.platform,
+    arch: request?.arch,
+    macHash: request?.macHash,
+  };
+  if (!MARK_ID_PATTERN.test(snapshot.markId ?? "")
+    || snapshot.markVersion !== 1
+    || snapshot.appSalt !== "memorax-plugin-v1"
+    || !MACHINE_ID_PATTERN.test(snapshot.machineId ?? "")
+    || !validText(snapshot.hostname, 120)
+    || !["windows", "linux", "macos"].includes(snapshot.platform)
+    || !["x86_64", "arm64"].includes(snapshot.arch)
+    || !SHA256_PATTERN.test(snapshot.macHash ?? "")) {
+    throw clientError("invalid_request");
+  }
+  return snapshot;
+}
+
+function validateServiceBaseUrl(value) {
+  try {
+    const url = new URL(value);
+    if (typeof value !== "string"
+      || value !== value.trim()
+      || url.protocol !== "https:"
+      || !url.hostname
+      || url.username
+      || url.password
+      || url.search
+      || url.hash
+      || !["", "/"].includes(url.pathname)) {
+      throw new Error();
+    }
+    return url.origin;
+  } catch {
+    throw clientError("invalid_service_url");
+  }
+}
+
+function retryAfterDelay(header, body) {
+  const headerText = typeof header === "string" ? header.trim() : "";
+  let headerDelay;
+  if (/^\d+$/.test(headerText)) {
+    headerDelay = Number(headerText) * 1000;
+  } else if (headerText) {
+    const retryAt = Date.parse(headerText);
+    if (Number.isFinite(retryAt)) headerDelay = Math.max(0, retryAt - Date.now());
+  }
+  if (Number.isSafeInteger(headerDelay) && headerDelay <= MAX_RETRY_AFTER_MS) {
+    return headerDelay;
+  }
+  const bodySeconds = isRecord(body) && isRecord(body.error)
+    ? body.error.retry_after_seconds
+    : undefined;
+  const delay = Number.isSafeInteger(bodySeconds) && bodySeconds >= 0
+    ? bodySeconds * 1000
+    : undefined;
+  return Number.isSafeInteger(delay) && delay <= MAX_RETRY_AFTER_MS ? delay : undefined;
+}
+
+function validText(value, maximumLength) {
+  return typeof value === "string"
+    && value.length > 0
+    && value.length <= maximumLength
+    && value === value.trim()
+    && !value.includes("\0");
+}
+
+function decimalPublicId(value) {
+  return typeof value === "string" && /^\d+$/.test(value) ? value : undefined;
+}
+
+function positiveInteger(value, maximum) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > maximum) {
+    throw clientError("invalid_options");
+  }
+  return value;
+}
+
+function clientError(reason, fields) {
+  return new TrialProvisionClientError(reason, fields);
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/lib/trial-provision-flow.mjs

@@ -0,0 +1,215 @@
+import {
+  TrialProvisionClientError,
+} from "./trial-provision-client.mjs";
+import { generateTrialPluginIdentity } from "./trial-plugin-mark.mjs";
+
+export {
+  generateTrialPluginIdentity,
+  generateTrialMarkId,
+} from "./trial-plugin-mark.mjs";
+
+const RETRY_DELAYS_MS = Object.freeze([1_000, 2_000, 4_000]);
+const ERROR_REASONS = new Set([
+  "invalid_options",
+  "invalid_credential_state",
+  "identity_generation_failed",
+  "credential_failure",
+  "response_state_mismatch",
+  "client_failure",
+  "retry_failed",
+]);
+const MARK_ID_PATTERN = /^mk_[0-9a-f]{64}$/;
+const API_KEY_PATTERN = /^sk_[A-Za-z0-9_-]{43}$/;
+
+export class TrialProvisionFlowError extends Error {
+  constructor(reason) {
+    const safeReason = ERROR_REASONS.has(reason) ? reason : "client_failure";
+    super(`Trial provision flow failed (${safeReason})`);
+    this.name = "TrialProvisionFlowError";
+    this.code = "TRIAL_PROVISION_FLOW_FAILED";
+    this.reason = safeReason;
+  }
+}
+
+export async function ensureTrialCredentialReady(options = {}) {
+  const context = validateOptions(options);
+  try {
+    return await context.credentialPort.withProvisionLock(
+      () => runTrialCredentialFlow(context),
+      { timeoutMs: 30_000 },
+    );
+  } catch (error) {
+    if (error instanceof TrialProvisionFlowError
+      || error instanceof TrialProvisionClientError) {
+      throw error;
+    }
+    throw flowError("credential_failure");
+  }
+}
+
+async function runTrialCredentialFlow(context) {
+  let record = await context.credentialPort.load();
+  if (record === null) record = await createCredential(context);
+  assertCredentialRecord(record);
+  if (record.state === "ready") return readyResult(record, false);
+
+  const response = await provisionWithRetry(record, context);
+  validateProvisionResponse(response);
+  const ready = await context.credentialPort.complete(record, {
+    accountId: response.accountId,
+    projectId: response.projectId,
+    apiKey: response.apiKey,
+  });
+  return readyResult(ready, true);
+}
+
+async function createCredential(context) {
+  let seed;
+  try {
+    const identity = context.generatePluginIdentity();
+    seed = context.recordPort.createInitial({
+      markId: identity.markId,
+      markVersion: identity.markVersion,
+      appSalt: identity.appSalt,
+      machineId: identity.machineId,
+      hostname: identity.hostname,
+      platform: identity.platform,
+      arch: identity.arch,
+      macHash: identity.macHash,
+    });
+  } catch {
+    throw flowError("identity_generation_failed");
+  }
+  const result = await context.credentialPort.createIfAbsent(seed);
+  if (!isRecord(result) || !Object.hasOwn(result, "record")) {
+    throw flowError("credential_failure");
+  }
+  return result.record;
+}
+
+async function provisionWithRetry(record, context) {
+  const request = Object.freeze({
+    markId: record.mark_id,
+    markVersion: record.mark_version,
+    appSalt: record.app_salt,
+    machineId: record.machine_id,
+    hostname: record.hostname,
+    platform: record.platform,
+    arch: record.arch,
+    macHash: record.mac_hash,
+  });
+
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await context.client.provision(request);
+    } catch (error) {
+      if (!(error instanceof TrialProvisionClientError)) {
+        throw flowError("client_failure");
+      }
+      const delay = retryDelay(error, attempt);
+      if (delay === undefined) throw error;
+      try {
+        await context.sleep(delay);
+      } catch {
+        throw flowError("retry_failed");
+      }
+    }
+  }
+}
+
+function retryDelay(error, attempt) {
+  if (attempt >= RETRY_DELAYS_MS.length) return undefined;
+  if (error.reason === "rate_limit_exceeded") return error.retryAfterMs;
+  if (["transport", "timeout", "server_error"].includes(error.reason)) {
+    return RETRY_DELAYS_MS[attempt];
+  }
+  if (["invalid_response", "response_contract"].includes(error.reason)
+    && error.httpStatus === 200
+    && attempt === 0) {
+    return 0;
+  }
+  return undefined;
+}
+
+function validateProvisionResponse(response) {
+  if (!isRecord(response)
+    || typeof response.accountId !== "string"
+    || typeof response.projectId !== "string"
+    || typeof response.apiKey !== "string"
+    || !API_KEY_PATTERN.test(response.apiKey)
+    || typeof response.created !== "boolean") {
+    throw flowError("response_state_mismatch");
+  }
+}
+
+function assertCredentialRecord(record) {
+  if (!isRecord(record)
+    || !["provisioning", "ready"].includes(record.state)
+    || typeof record.mark_id !== "string"
+    || !MARK_ID_PATTERN.test(record.mark_id)
+    || (record.state === "provisioning" && record.api_key !== null)
+    || (record.state === "ready"
+      && (typeof record.api_key !== "string"
+        || !API_KEY_PATTERN.test(record.api_key)
+        || typeof record.account_id !== "string"
+        || typeof record.project_id !== "string"))) {
+    throw flowError("invalid_credential_state");
+  }
+}
+
+function readyResult(record, provisioned) {
+  assertCredentialRecord(record);
+  if (record.state !== "ready") throw flowError("credential_failure");
+  return Object.freeze({
+    status: "ready",
+    provisioned,
+    markId: record.mark_id,
+    accountId: record.account_id,
+    projectId: record.project_id,
+    apiKey: record.api_key,
+  });
+}
+
+function validateOptions(options) {
+  const credentialPort = options.credentialPort;
+  const recordPort = options.recordPort;
+  const client = options.client;
+  if (!hasFunctions(credentialPort, [
+    "load",
+    "createIfAbsent",
+    "complete",
+    "withProvisionLock",
+  ])
+    || !hasFunctions(recordPort, ["createInitial"])
+    || !hasFunctions(client, ["provision"])) {
+    throw flowError("invalid_options");
+  }
+  const generatePluginIdentity = options.generatePluginIdentity ?? generateTrialPluginIdentity;
+  const sleep = options.sleep ?? defaultSleep;
+  if (typeof generatePluginIdentity !== "function" || typeof sleep !== "function") {
+    throw flowError("invalid_options");
+  }
+  return {
+    credentialPort,
+    recordPort,
+    client,
+    generatePluginIdentity,
+    sleep,
+  };
+}
+
+function defaultSleep(delayMs) {
+  return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+
+function hasFunctions(value, names) {
+  return isRecord(value) && names.every((name) => typeof value[name] === "function");
+}
+
+function flowError(reason) {
+  return new TrialProvisionFlowError(reason);
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/lib/trial-setup.mjs

@@ -0,0 +1,53 @@
+import { createTrialProvisionClient } from "./trial-provision-client.mjs";
+import { ensureTrialCredentialReady } from "./trial-provision-flow.mjs";
+
+export async function ensureTrialSetupCredential(options = {}) {
+  const env = options.env ?? process.env;
+  const credentialApis = options.credentialApis ?? await loadCredentialApis();
+  const credentialPort = trialCredentialPort(options, credentialApis, env);
+  const recordPort = options.recordPort ?? {
+    createInitial: credentialApis.createInitialTrialCredentialRecord,
+  };
+  const client = options.client ?? createTrialProvisionClient({
+    ...options.provisionClientOptions,
+    env,
+  });
+  return await ensureTrialCredentialReady({
+    ...options.flowOptions,
+    credentialPort,
+    recordPort,
+    client,
+  });
+}
+
+export async function loadReadyTrialSetupCredential(options = {}) {
+  const env = options.env ?? process.env;
+  const credentialApis = options.credentialApis ?? await loadCredentialApis();
+  const record = await trialCredentialPort(options, credentialApis, env).load();
+  if (record?.state !== "ready") return undefined;
+  return Object.freeze({
+    status: "ready",
+    provisioned: false,
+    markId: record.mark_id,
+    accountId: record.account_id,
+    projectId: record.project_id,
+    apiKey: record.api_key,
+  });
+}
+
+function trialCredentialPort(options, credentialApis, env) {
+  return options.credentialPort
+    ?? credentialApis.createTrialCredentialStorePort({
+      ...options.credentialStoreOptions,
+      memoraxCodeHome: options.memoraxCodeHome,
+      env,
+    });
+}
+
+async function loadCredentialApis() {
+  const [recordApi, storeApi] = await Promise.all([
+    import("./memorax-code-adapter-common/src/credentials/trial-credential-record.mjs"),
+    import("./memorax-code-adapter-common/src/credentials/trial-credential-store.mjs"),
+  ]);
+  return { ...recordApi, ...storeApi };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorax/memorax-code",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Persistent coding memory for Codex, Claude Code, DeepSeek Harness, and OpenCode.",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=24"
+    "node": ">=20"
   },
   "dependencies": {
     "smol-toml": "^1.7.0"