@joeybuilt/plexo-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,599 @@
+// src/types/channel.ts
+var PEX_VERSION = "0.4.0";
+
+// src/channel-client.ts
+import { createHmac } from "crypto";
+function sign(secret, body) {
+  return "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
+}
+function defaultHeaders(opts, body) {
+  return {
+    "Content-Type": "application/json",
+    "X-App-Id": opts.appId,
+    "X-Plexo-Timestamp": (/* @__PURE__ */ new Date()).toISOString(),
+    "X-Plexo-Signature": sign(opts.serviceKey, body)
+  };
+}
+async function request(opts, method, path, body) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const serialized = body === void 0 ? "" : JSON.stringify(body);
+  const res = await fetchImpl(`${opts.baseUrl}${path}`, {
+    method,
+    headers: defaultHeaders(opts, serialized),
+    body: body === void 0 ? void 0 : serialized
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`channel-client: ${method} ${path} failed: ${res.status} ${detail}`);
+  }
+  if (res.status === 204) return void 0;
+  return await res.json();
+}
+function createChannelClient(opts) {
+  return {
+    list: (q) => request(
+      opts,
+      "GET",
+      `/api/plexo/channels${q?.workspaceId ? `?workspaceId=${encodeURIComponent(q.workspaceId)}` : ""}`
+    ),
+    subscribe: (channelId, scopes) => request(opts, "POST", `/api/plexo/channels/${channelId}/subscribe`, { scopes }),
+    unsubscribe: async (channelId, subscriptionId) => {
+      await request(
+        opts,
+        "DELETE",
+        `/api/plexo/channels/${channelId}/subscribe/${subscriptionId}`
+      );
+    },
+    threads: (channelId, q) => {
+      const params = new URLSearchParams();
+      if (q?.cursor) params.set("cursor", q.cursor);
+      if (q?.limit) params.set("limit", String(q.limit));
+      const qs = params.toString();
+      return request(
+        opts,
+        "GET",
+        `/api/plexo/channels/${channelId}/threads${qs ? `?${qs}` : ""}`
+      );
+    },
+    messages: (channelId, threadId, q) => {
+      const params = new URLSearchParams();
+      if (q?.cursor) params.set("cursor", q.cursor);
+      if (q?.limit) params.set("limit", String(q.limit));
+      const qs = params.toString();
+      return request(
+        opts,
+        "GET",
+        `/api/plexo/channels/${channelId}/threads/${threadId}/messages${qs ? `?${qs}` : ""}`
+      );
+    },
+    send: (channelId, threadId, payload) => request(
+      opts,
+      "POST",
+      `/api/plexo/channels/${channelId}/threads/${threadId}/messages`,
+      payload
+    ),
+    events: (channelId, q) => createEventStream(opts, channelId, q)
+  };
+}
+async function* createEventStream(opts, channelId, q) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const url = `${opts.baseUrl}/api/plexo/channels/${channelId}/events`;
+  const headers = {
+    Accept: "text/event-stream",
+    "X-App-Id": opts.appId,
+    "X-Plexo-Timestamp": (/* @__PURE__ */ new Date()).toISOString(),
+    "X-Plexo-Signature": sign(opts.serviceKey, "")
+  };
+  if (q?.lastEventId) headers["Last-Event-ID"] = q.lastEventId;
+  const res = await fetchImpl(url, { method: "GET", headers, signal: q?.signal });
+  if (!res.ok || !res.body) {
+    throw new Error(`channel-client: SSE ${url} failed: ${res.status}`);
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    let idx;
+    while ((idx = buffer.indexOf("\n\n")) !== -1) {
+      const raw = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 2);
+      const dataLine = raw.split("\n").find((l) => l.startsWith("data:"));
+      if (!dataLine) continue;
+      const json = dataLine.slice(5).trim();
+      if (!json) continue;
+      try {
+        yield JSON.parse(json);
+      } catch {
+      }
+    }
+  }
+}
+
+// src/types/events.ts
+var TOPICS = {
+  // Task lifecycle
+  TASK_CREATED: "task.created",
+  TASK_COMPLETED: "task.completed",
+  TASK_FAILED: "task.failed",
+  TASK_BLOCKED: "task.blocked",
+  // Channel
+  CHANNEL_MESSAGE_RECEIVED: "channel.message.received",
+  CHANNEL_HEALTH_CHANGED: "channel.health.changed",
+  // Extension lifecycle
+  EXTENSION_ACTIVATED: "extension.activated",
+  EXTENSION_DEACTIVATED: "extension.deactivated",
+  EXTENSION_CRASHED: "extension.crashed",
+  // Connection lifecycle
+  CONNECTION_ADDED: "connection.added",
+  CONNECTION_REMOVED: "connection.removed",
+  // Memory
+  MEMORY_WRITTEN: "memory.written",
+  // §16 — Entity lifecycle
+  ENTITY_CREATED: "entity.created",
+  ENTITY_MODIFIED: "entity.modified",
+  ENTITY_DELETED: "entity.deleted",
+  ENTITY_LINKED: "entity.linked",
+  // §23 — Escalation
+  ESCALATION_TRIGGERED: "escalation.triggered",
+  ESCALATION_RESOLVED: "escalation.resolved",
+  ESCALATION_TIMED_OUT: "escalation.timed_out",
+  // §18 — Audit (host-internal, owner-tier subscribe only)
+  AUDIT_ENTRY_CREATED: "audit.entry.created",
+  // §20 — UserSelf
+  SELF_UPDATED: "self.updated",
+  SELF_PROPOSAL_RECEIVED: "self.proposal.received",
+  // Agent lifecycle (core architecture — Agent ≠ Extension)
+  AGENT_ACTIVATED: "agent.activated",
+  AGENT_DEACTIVATED: "agent.deactivated",
+  AGENT_PLAN_CREATED: "agent.plan.created",
+  AGENT_STEP_COMPLETED: "agent.step.completed",
+  AGENT_STEP_FAILED: "agent.step.failed",
+  // §22 — A2A
+  A2A_INBOUND_RECEIVED: "a2a.inbound.received",
+  A2A_DELEGATION_SENT: "a2a.delegation.sent",
+  A2A_DELEGATION_COMPLETED: "a2a.delegation.completed",
+  // §7.6 — Prompt Library
+  PROMPT_REGISTERED: "prompt.registered",
+  PROMPT_ENABLED: "prompt.enabled",
+  // §7.7 — Context Layer
+  CONTEXT_REGISTERED: "context.registered",
+  CONTEXT_UPDATED: "context.updated",
+  CONTEXT_EXPIRED: "context.expired"
+};
+function customTopic(scope, name, event) {
+  return `ext.${scope}.${name}.${event}`;
+}
+
+// src/validation/manifest.ts
+var VALID_TYPES = ["agent", "skill", "channel", "tool", "connector"];
+var LEGACY_TYPES = /* @__PURE__ */ new Set(["function", "mcp-server"]);
+var VALID_ENTITY_TYPES = [
+  "person",
+  "task",
+  "thread",
+  "note",
+  "transaction",
+  "calendar_event",
+  "file"
+];
+var VALID_TRUST_TIERS = ["owner", "verified", "community"];
+var DISPLAY_NAME_MAX = 50;
+var STANDARD_CAPABILITIES = /* @__PURE__ */ new Set([
+  // Legacy (deprecated at Standard + Full)
+  "memory:read",
+  "memory:write",
+  "memory:delete",
+  // Entity-scoped memory wildcards (owner tier only)
+  "memory:read:*",
+  "memory:write:*",
+  // Channel
+  "channel:send",
+  "channel:send-direct",
+  "channel:receive",
+  // Scheduling
+  "schedule:register",
+  "schedule:manage",
+  // UI
+  "ui:register-widget",
+  "ui:notify",
+  // Tasks
+  "tasks:create",
+  "tasks:read",
+  "tasks:read-all",
+  // Events
+  "events:subscribe",
+  "events:publish",
+  // Storage
+  "storage:read",
+  "storage:write",
+  // §20 — UserSelf
+  "self:read",
+  "self:write",
+  // §18 — Audit
+  "audit:read",
+  // §21 — Identity
+  "identity:present",
+  // §22 — A2A
+  "a2a:delegate",
+  // §24 — Model
+  "model:override",
+  // Prompts
+  "prompts:register",
+  "prompts:read",
+  // Context
+  "context:register",
+  "context:write",
+  "context:read"
+]);
+var OWNER_ONLY_CAPABILITIES = /* @__PURE__ */ new Set([
+  "memory:read:*",
+  "memory:write:*",
+  "audit:read",
+  "model:override"
+]);
+var RATIONALE_OPTIONAL_CAPABILITIES = /* @__PURE__ */ new Set([
+  "storage:read",
+  "storage:write",
+  "events:subscribe",
+  "events:publish",
+  "ui:register-widget",
+  "ui:notify",
+  "identity:present",
+  "prompts:register",
+  "prompts:read",
+  "context:register",
+  "context:read",
+  "schedule:register"
+]);
+function validateManifest(raw, options) {
+  const errors = [];
+  const complianceLevel = options?.hostComplianceLevel ?? "core";
+  const installSource = options?.source ?? "registry";
+  if (typeof raw !== "object" || raw === null) {
+    return { valid: false, errors: [{ field: "root", message: "Manifest must be a JSON object" }] };
+  }
+  const m = raw;
+  if (typeof m["plexo"] !== "string" || !isSemver(m["plexo"])) {
+    errors.push({ field: "plexo", message: 'Must be a valid semver string (e.g. "0.4.0")' });
+  }
+  if (typeof m["name"] !== "string" || !isValidPackageName(m["name"])) {
+    errors.push({ field: "name", message: "Must match @scope/name format (lowercase alphanumeric, hyphens, dots allowed)" });
+  }
+  if (typeof m["version"] !== "string" || !isSemver(m["version"])) {
+    errors.push({ field: "version", message: "Must be a valid semver string" });
+  }
+  const rawType = m["type"];
+  if (LEGACY_TYPES.has(rawType)) {
+    const replacement = rawType === "function" ? "tool (or skill)" : "connector";
+    errors.push({
+      field: "type",
+      message: `Type "${rawType}" is deprecated in v0.4.0. Use "${replacement}" instead.`,
+      severity: "warning"
+    });
+  } else if (!VALID_TYPES.includes(rawType)) {
+    errors.push({ field: "type", message: `Must be one of: ${VALID_TYPES.join(", ")}` });
+  }
+  if (typeof m["entry"] !== "string" || m["entry"].length === 0) {
+    errors.push({ field: "entry", message: "Must be a non-empty string path to the entry point" });
+  }
+  if (!Array.isArray(m["capabilities"])) {
+    errors.push({ field: "capabilities", message: "Must be an array of capability token strings" });
+  } else {
+    ;
+    m["capabilities"].forEach((cap, i) => {
+      if (typeof cap !== "string") {
+        errors.push({ field: `capabilities[${i}]`, message: "Each capability must be a string" });
+        return;
+      }
+      if (!isValidCapability(cap)) {
+        errors.push({
+          field: `capabilities[${i}]`,
+          message: `Unknown capability token "${cap}". Must be a standard token, entity-scoped memory, connections:<service>, or host:<hostname>:<capability>`
+        });
+        return;
+      }
+      if (isHostScopedCapability(cap)) {
+        errors.push({
+          field: `capabilities[${i}]`,
+          message: `Host-scoped capability "${cap}" is not validated by this tool. The target host must confirm this token is supported.`,
+          severity: "warning"
+        });
+      }
+      if (isUnscopedMemoryCapability(cap) && (complianceLevel === "standard" || complianceLevel === "full")) {
+        errors.push({
+          field: `capabilities[${i}]`,
+          message: `Unscoped memory capability "${cap}" is invalid at ${complianceLevel} compliance. Use entity-scoped tokens (e.g. memory:read:person, memory:write:task).`
+        });
+      }
+      if (isWildcardMemoryCapability(cap)) {
+        const trust = m["trust"];
+        if (trust !== "owner") {
+          errors.push({
+            field: `capabilities[${i}]`,
+            message: `Wildcard memory capability "${cap}" is only allowed at trust tier: owner. Declared trust: ${trust ?? "none"}`
+          });
+        }
+      }
+      if (cap === "audit:read") {
+        const trust = m["trust"];
+        if (trust !== "owner") {
+          errors.push({
+            field: `capabilities[${i}]`,
+            message: `audit:read capability is only allowed at trust tier: owner. Declared trust: ${trust ?? "none"}`
+          });
+        }
+      }
+      if (installSource === "sideload" && OWNER_ONLY_CAPABILITIES.has(cap)) {
+        errors.push({
+          field: `capabilities[${i}]`,
+          message: `Capability "${cap}" is restricted to owner-tier extensions and cannot be used in a sideloaded install.`
+        });
+      }
+    });
+  }
+  const trustValue = m["trust"];
+  const capabilitiesList = Array.isArray(m["capabilities"]) ? m["capabilities"].filter((c) => typeof c === "string") : [];
+  const rationale = m["capabilitiesRationale"];
+  if (rationale !== void 0) {
+    if (typeof rationale !== "object" || rationale === null || Array.isArray(rationale)) {
+      errors.push({
+        field: "capabilitiesRationale",
+        message: "Must be an object mapping capability tokens to explanation strings"
+      });
+    } else {
+      const r = rationale;
+      for (const [token, explanation] of Object.entries(r)) {
+        if (!capabilitiesList.includes(token)) {
+          errors.push({
+            field: `capabilitiesRationale.${token}`,
+            message: `Rationale declared for "${token}" but the capability is not in capabilities[]`
+          });
+          continue;
+        }
+        if (typeof explanation !== "string") {
+          errors.push({
+            field: `capabilitiesRationale.${token}`,
+            message: "Rationale value must be a string"
+          });
+          continue;
+        }
+        if (explanation.length === 0) {
+          errors.push({
+            field: `capabilitiesRationale.${token}`,
+            message: "Rationale value must be non-empty"
+          });
+        } else if (explanation.length > 200) {
+          errors.push({
+            field: `capabilitiesRationale.${token}`,
+            message: "Rationale must be 200 characters or fewer"
+          });
+        }
+      }
+    }
+  }
+  if (trustValue === "owner" || trustValue === "verified") {
+    const r = rationale && typeof rationale === "object" && !Array.isArray(rationale) ? rationale : {};
+    for (const token of capabilitiesList) {
+      if (RATIONALE_OPTIONAL_CAPABILITIES.has(token)) continue;
+      if (typeof r[token] !== "string" || r[token].length === 0) {
+        errors.push({
+          field: "capabilitiesRationale",
+          message: `Capability "${token}" requires a rationale entry for trust tier "${trustValue}". Add capabilitiesRationale["${token}"].`
+        });
+      }
+    }
+  } else if (trustValue === "community" && capabilitiesList.length > 0) {
+    const r = rationale && typeof rationale === "object" && !Array.isArray(rationale) ? rationale : {};
+    for (const token of capabilitiesList) {
+      if (RATIONALE_OPTIONAL_CAPABILITIES.has(token)) continue;
+      if (typeof r[token] !== "string" || r[token].length === 0) {
+        errors.push({
+          field: "capabilitiesRationale",
+          message: `Capability "${token}" has no rationale \u2014 community extensions are strongly encouraged to explain each capability.`,
+          severity: "warning"
+        });
+      }
+    }
+  }
+  if (typeof m["displayName"] !== "string" || m["displayName"].length === 0) {
+    errors.push({ field: "displayName", message: "Must be a non-empty string" });
+  } else if (m["displayName"].length > DISPLAY_NAME_MAX) {
+    errors.push({ field: "displayName", message: `Must be ${DISPLAY_NAME_MAX} characters or fewer` });
+  }
+  if (typeof m["description"] !== "string") {
+    errors.push({ field: "description", message: "Must be a string" });
+  } else if (m["description"].length > 280) {
+    errors.push({ field: "description", message: "Must be 280 characters or fewer" });
+  }
+  if (typeof m["author"] !== "string" || m["author"].length === 0) {
+    errors.push({ field: "author", message: "Must be a non-empty string" });
+  }
+  if (typeof m["license"] !== "string" || m["license"].length === 0) {
+    errors.push({ field: "license", message: "Must be a valid SPDX license identifier" });
+  }
+  if (m["keywords"] !== void 0) {
+    if (!Array.isArray(m["keywords"])) {
+      errors.push({ field: "keywords", message: "Must be an array of strings" });
+    } else if (m["keywords"].length > 10) {
+      errors.push({ field: "keywords", message: "Max 10 keywords allowed" });
+    }
+  }
+  if (m["screenshots"] !== void 0) {
+    if (!Array.isArray(m["screenshots"])) {
+      errors.push({ field: "screenshots", message: "Must be an array of HTTPS URLs" });
+    } else if (m["screenshots"].length > 5) {
+      errors.push({ field: "screenshots", message: "Max 5 screenshots allowed" });
+    }
+  }
+  if (m["type"] === "connector" && m["mcpServer"] === void 0) {
+    errors.push({ field: "mcpServer", message: "Required for connector type extensions" });
+  }
+  if (m["channelTransport"] !== void 0) {
+    if (m["type"] !== "channel") {
+      errors.push({ field: "channelTransport", message: "channelTransport is only valid for channel type extensions" });
+    } else if (m["channelTransport"] !== "worker" && m["channelTransport"] !== "api") {
+      errors.push({ field: "channelTransport", message: 'Must be "worker" or "api"' });
+    }
+  }
+  if (m["trust"] !== void 0) {
+    if (!VALID_TRUST_TIERS.includes(m["trust"])) {
+      errors.push({ field: "trust", message: `Must be one of: ${VALID_TRUST_TIERS.join(", ")}` });
+    }
+  }
+  if (m["dataResidency"] !== void 0) {
+    validateDataResidency(m["dataResidency"], errors);
+  } else if (complianceLevel === "full") {
+    errors.push({
+      field: "dataResidency",
+      message: "dataResidency is required at Full compliance. Omission treated as sendsDataExternally: true with unknown destinations.",
+      severity: "warning"
+    });
+  }
+  if (m["type"] === "agent" && m["escalation"] !== void 0) {
+    validateEscalation(m["escalation"], errors);
+  }
+  if (m["modelRequirements"] !== void 0) {
+    validateModelRequirements(m["modelRequirements"], errors);
+  }
+  const hardErrors = errors.filter((e) => e.severity !== "warning");
+  return { valid: hardErrors.length === 0, errors };
+}
+function validateDataResidency(dr, errors) {
+  if (typeof dr !== "object" || dr === null) {
+    errors.push({ field: "dataResidency", message: "Must be an object" });
+    return;
+  }
+  const obj = dr;
+  if (typeof obj["sendsDataExternally"] !== "boolean") {
+    errors.push({ field: "dataResidency.sendsDataExternally", message: "Must be a boolean" });
+  }
+  if (obj["sendsDataExternally"] === true && !Array.isArray(obj["externalDestinations"])) {
+    errors.push({
+      field: "dataResidency.externalDestinations",
+      message: "Must be provided when sendsDataExternally is true"
+    });
+  }
+}
+function validateEscalation(esc, errors) {
+  if (typeof esc !== "object" || esc === null) {
+    errors.push({ field: "escalation", message: "Must be an object" });
+    return;
+  }
+  const obj = esc;
+  if (obj["irreversibleActions"] !== void 0 && !Array.isArray(obj["irreversibleActions"])) {
+    errors.push({ field: "escalation.irreversibleActions", message: "Must be an array of strings" });
+  }
+}
+function validateModelRequirements(mr, errors) {
+  if (typeof mr !== "object" || mr === null) {
+    errors.push({ field: "modelRequirements", message: "Must be an object" });
+    return;
+  }
+  const obj = mr;
+  if (obj["minimumContextWindow"] !== void 0 && typeof obj["minimumContextWindow"] !== "number") {
+    errors.push({ field: "modelRequirements.minimumContextWindow", message: "Must be a number" });
+  }
+  if (obj["localModelAcceptable"] !== void 0 && typeof obj["localModelAcceptable"] !== "boolean") {
+    errors.push({ field: "modelRequirements.localModelAcceptable", message: "Must be a boolean" });
+  }
+}
+function isSemver(s) {
+  return /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$/.test(s);
+}
+function isValidPackageName(s) {
+  return /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(s);
+}
+function isValidCapability(token) {
+  if (STANDARD_CAPABILITIES.has(token)) return true;
+  if (/^memory:(read|write):([a-z_]+)$/.test(token)) {
+    const entityType = token.split(":")[2];
+    if (VALID_ENTITY_TYPES.includes(entityType)) return true;
+  }
+  if (/^entity:(create|modify|delete):([a-z_]+)$/.test(token)) {
+    const entityType = token.split(":")[2];
+    if (VALID_ENTITY_TYPES.includes(entityType)) return true;
+  }
+  if (/^connections:[a-z0-9-]+$/.test(token)) return true;
+  if (/^host:[a-z0-9-]+:[a-z0-9-:]+$/.test(token)) return true;
+  return false;
+}
+function isHostScopedCapability(token) {
+  return /^host:[a-z0-9-]+:[a-z0-9-:]+$/.test(token);
+}
+function isUnscopedMemoryCapability(token) {
+  return token === "memory:read" || token === "memory:write";
+}
+function isWildcardMemoryCapability(token) {
+  return token === "memory:read:*" || token === "memory:write:*";
+}
+
+// src/validation/signature.ts
+var OWNER_IDENTITY_SUFFIXES = ["@joeybuilt-official", "@plexo-official"];
+function verifySignature(manifest, meta) {
+  const declared = manifest.trust ?? "community";
+  if (!meta || meta.signatureType === "none" || !meta.signature) {
+    if (declared === "owner" || declared === "verified") {
+      return {
+        ok: false,
+        signatureType: "none",
+        signerIdentity: null,
+        effectiveTrust: "community",
+        message: `Manifest declares trust "${declared}" but is unsigned \u2014 downgraded to community.`
+      };
+    }
+    return {
+      ok: true,
+      signatureType: "none",
+      signerIdentity: null,
+      effectiveTrust: "community",
+      message: "Unsigned community extension."
+    };
+  }
+  if (meta.signatureType === "sigstore") {
+    const isOwner = OWNER_IDENTITY_SUFFIXES.some(
+      (suffix) => meta.signerIdentity.toLowerCase().endsWith(suffix)
+    );
+    const ceiling = isOwner ? "owner" : "verified";
+    const effectiveTrust = lowerOf(declared, ceiling);
+    return {
+      ok: true,
+      signatureType: "sigstore",
+      signerIdentity: meta.signerIdentity,
+      effectiveTrust,
+      message: `Sigstore signature accepted (stub v1) \u2014 signer ${meta.signerIdentity}.`
+    };
+  }
+  if (meta.signatureType === "ecdsa-p256") {
+    const effectiveTrust = lowerOf(declared, "verified");
+    return {
+      ok: true,
+      signatureType: "ecdsa-p256",
+      signerIdentity: meta.signerIdentity,
+      effectiveTrust,
+      message: `ECDSA signature accepted (stub v1) \u2014 signer ${meta.signerIdentity}.`
+    };
+  }
+  return {
+    ok: false,
+    signatureType: "none",
+    signerIdentity: null,
+    effectiveTrust: "community",
+    message: `Unknown signature type: ${String(meta.signatureType)}`
+  };
+}
+function lowerOf(a, b) {
+  const order = { community: 0, verified: 1, owner: 2 };
+  return order[a] <= order[b] ? a : b;
+}
+export {
+  PEX_VERSION,
+  TOPICS,
+  createChannelClient,
+  customTopic,
+  validateManifest,
+  verifySignature
+};
+//# sourceMappingURL=index.js.map