Skip to content
Python
7.7 KB
Raw Blame
import type {
  ContextSearchRequest,
  SdkContextSearchResponse,
} from "@one-memory/contracts";
import { HostGrantError, type VerifiedHostIdentity } from "./host-grants.js";

/** What a lookup gets when the host does not ask for a budget of its own.
 *
 * Core's own default is two seconds, which a first lookup after launch
 * overruns: the whole path then comes back as a timeout and the host sees
 * nothing. The host side fills this in so Core's contract stays as it is.
 */
export const HOST_CONTEXT_TIMEOUT_MS = 8000;

/** Return only the invalid field path; never echo content from Core. */
export function contextResponseInvalidField(value: unknown): string | null {
  return isSdkContextSearchResponse(value) ? null : "response";
}

export function isContextSearchRequest(
  value: unknown,
): value is ContextSearchRequest {
  if (
    !record(value) ||
    !only(value, [
      "query",
      "kinds",
      "raw_source_ids",
      "limit",
      "character_budget",
      "timeout_ms",
    ]) ||
    !text(value.query, 1, 2000) ||
    !value.query.trim()
  )
    return false;
  const kinds = value.kinds ?? ["raw", "memory"];
  if (
    (value.kinds !== undefined && value.kinds === null) ||
    !Array.isArray(kinds) ||
    kinds.length < 1 ||
    kinds.length > 2 ||
    !kinds.every((kind) => kind === "raw" || kind === "memory") ||
    new Set(kinds).size !== kinds.length
  )
    return false;
  const sources = value.raw_source_ids;
  if (
    sources !== undefined &&
    sources !== null &&
    (!kinds.includes("raw") ||
      !Array.isArray(sources) ||
      sources.length < 1 ||
      sources.length > 32 ||
      new Set(sources).size !== sources.length ||
      !sources.every(
        (source) =>
          typeof source === "string" &&
          /^[a-z0-9][a-z0-9-]{0,127}$/.test(source),
      ))
  )
    return false;
  return (
    optionalInteger(value.limit, 1, 20) &&
    optionalInteger(value.character_budget, 200, 20000) &&
    optionalInteger(value.timeout_ms, 50, 30000)
  );
}

/** Composition of existing rights, not a new all-content grant. Core checks live sources. */
export function authorizeContext(
  identity: VerifiedHostIdentity,
  request: ContextSearchRequest,
): void {
  const kinds = request.kinds ?? ["raw", "memory"];
  const raw =
    kinds.includes("raw") &&
    identity.allowedTools.includes("om_conversations") &&
    identity.allowedScopes.includes("all-apps") &&
    identity.allowedScopes.some((s) => s.startsWith("source:"));
  const memory = kinds.includes("memory") && hasMemoryAuthority(identity);
  if (
    request.raw_source_ids &&
    (!raw ||
      !request.raw_source_ids.every((s) =>
        identity.allowedScopes.includes(`source:${s}`),
      ))
  )
    throw new HostGrantError("host_grant_scope_denied");
  if (!raw && !memory) throw new HostGrantError("host_grant_tool_denied");
}

function hasMemoryAuthority(identity: VerifiedHostIdentity): boolean {
  return (
    identity.allowedTools.includes("om_recall") &&
    identity.allowedScopes.some(
      (scope) =>
        scope === "all-apps" || /^workspace:v1:[a-f0-9]{64}$/.test(scope),
    )
  );
}

/** Defense in depth for a faulty Core response. Memory content scopes remain Core-owned. */
export function isContextResponseAuthorized(
  response: SdkContextSearchResponse,
  identity: VerifiedHostIdentity,
): boolean {
  return response.items.every((item) =>
    item.kind === "memory"
      ? hasMemoryAuthority(identity)
      : identity.allowedTools.includes("om_conversations") &&
        identity.allowedScopes.includes("all-apps") &&
        identity.allowedScopes.includes(`source:${item.source}`),
  );
}

export function isContextResponseForRequest(
  value: unknown,
  request: ContextSearchRequest,
): value is SdkContextSearchResponse {
  if (!isSdkContextSearchResponse(value)) return false;
  const kinds = request.kinds ?? ["raw", "memory"];
  // Core's default item cap.
  const limit = request.limit ?? 10;
  return (
    value.items.length <= limit &&
    value.used_characters <= (request.character_budget ?? 4000) &&
    value.items.every(
      (item) =>
        kinds.includes(item.kind) &&
        (item.kind !== "raw" ||
          !request.raw_source_ids ||
          request.raw_source_ids.includes(item.source)),
    )
  );
}

export function isSdkContextSearchResponse(
  value: unknown,
): value is SdkContextSearchResponse {
  if (
    !record(value) ||
    !exact(value, [
      "schema_version",
      "request_id",
      "state",
      "items",
      "used_characters",
      "truncated",
      "total_ms",
    ]) ||
    value.schema_version !== 2 ||
    !text(value.request_id, 1, 64) ||
    !member(value.state, ["grounded", "empty", "partial", "unavailable"]) ||
    !integer(value.used_characters, 0, 20000) ||
    typeof value.truncated !== "boolean" ||
    !nonnegative(value.total_ms) ||
    !Array.isArray(value.items) ||
    value.items.length > 20 ||
    !value.items.every(validSdkItem)
  )
    return false;
  const typed = value as unknown as SdkContextSearchResponse;
  if (typed.state === "grounded" && typed.items.length === 0) return false;
  if (
    (typed.state === "empty" || typed.state === "unavailable") &&
    typed.items.length !== 0
  )
    return false;
  return (
    typed.items.reduce((used, item) => used + [...item.content].length, 0) ===
    typed.used_characters
  );
}

function validSdkItem(value: unknown): boolean {
  if (!record(value) || typeof value.truncated !== "boolean") return false;
  if (value.kind === "raw")
    return (
      exact(value, [
        "kind",
        "raw_id",
        "content",
        "source",
        "session_id",
        "memory_at",
        "score",
        "truncated",
      ]) &&
      text(value.raw_id, 1, 512) &&
      text(value.content, 0, 20000) &&
      text(value.source, 1, 128) &&
      text(value.session_id, 1, 512) &&
      (value.memory_at === null || date(value.memory_at)) &&
      score(value.score)
    );
  return (
    value.kind === "memory" &&
    exact(value, [
      "kind",
      "memory_id",
      "content",
      "layer",
      "status",
      "source",
      "updated_at",
      "score",
      "truncated",
    ]) &&
    text(value.memory_id, 1, 512) &&
    text(value.content, 0, 20000) &&
    text(value.layer, 0, 64) &&
    text(value.status, 0, 32) &&
    (value.source === null || text(value.source, 0, 128)) &&
    (value.updated_at === null || date(value.updated_at)) &&
    score(value.score)
  );
}

function record(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value);
}
function only(value: Record<string, unknown>, keys: string[]): boolean {
  return Object.keys(value).every((key) => keys.includes(key));
}
function exact(value: Record<string, unknown>, keys: string[]): boolean {
  return only(value, keys) && keys.every((key) => Object.hasOwn(value, key));
}
function text(value: unknown, min: number, max: number): value is string {
  return (
    typeof value === "string" &&
    [...value].length >= min &&
    [...value].length <= max
  );
}
function integer(value: unknown, min: number, max: number): boolean {
  return (
    typeof value === "number" &&
    Number.isSafeInteger(value) &&
    value >= min &&
    value <= max
  );
}
function optionalInteger(value: unknown, min: number, max: number): boolean {
  return value === undefined || integer(value, min, max);
}
function nonnegative(value: unknown): boolean {
  return typeof value === "number" && Number.isFinite(value) && value >= 0;
}
function score(value: unknown): boolean {
  return nonnegative(value) && (value as number) <= 1;
}
function member(value: unknown, values: string[]): boolean {
  return typeof value === "string" && values.includes(value);
}
function date(value: unknown): boolean {
  return text(value, 1, 64) && Number.isFinite(Date.parse(value));
}