@lamplitisles/dsh-nanocodex 0.1.0-beta.0

package/vendor/nanocodex/cloud/server/HostPrincipal.mjs

@@ -0,0 +1,202 @@
+const APP_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const OPAQUE_CLAIM = /^[^\u0000-\u001f\u007f]{1,512}$/;
+const EXCHANGE_TOKEN = /^[A-Za-z0-9_-]{43}$/;
+const EXCHANGE_RESOURCE_PREFIX = "urn:nanocodex:host-principal:exchange:";
+
+export function create(parameters) {
+  if (!parameters || typeof parameters !== "object") {
+    throw new TypeError("HostPrincipal.create requires parameters");
+  }
+  if (!APP_ID.test(parameters.appId)) {
+    throw new TypeError("HostPrincipal.create requires a valid appId");
+  }
+  if (typeof parameters.secret !== "string" || !/^\S{32,512}$/.test(parameters.secret)) {
+    throw new TypeError("HostPrincipal.create requires a 32 to 512 character project secret");
+  }
+  const appOrigin = publicOrigin(parameters.appOrigin, "HostPrincipal.create appOrigin");
+  const baseUrl = serviceBaseUrl(parameters.baseUrl ?? "https://api.nanocodex.xyz");
+  const fetchFn = parameters.fetch ?? globalThis.fetch;
+  if (typeof fetchFn !== "function") throw new TypeError("HostPrincipal.create requires fetch");
+
+  const client = {
+    async create(options) {
+      const claims = principalClaims(options);
+      const resources = principalResources(options?.resources);
+      const expiresIn = exchangeExpiry(options?.expiresIn);
+      const response = await fetchFn(new URL("/v1/host-principal/exchanges", baseUrl), {
+        method: "POST",
+        headers: serverHeaders(parameters.appId, parameters.secret),
+        body: JSON.stringify({
+          app_origin: appOrigin,
+          issuer: claims.issuer,
+          tenant: claims.tenant,
+          subject: claims.subject,
+          session_id: claims.sessionId,
+          resources,
+          ...(expiresIn === undefined ? {} : { expires_in: expiresIn }),
+        }),
+        signal: options?.signal,
+      });
+      const body = await response.json().catch(() => undefined);
+      if (!response.ok) throw serviceError(response, body, "creation");
+      return exchangeFromWire(body);
+    },
+    handler(options) {
+      if (!options || typeof options.authenticate !== "function") {
+        throw new TypeError("host principal handler requires authenticate");
+      }
+      return async function hostPrincipalExchange(request) {
+        if (!request || request.method !== "POST") {
+          return errorResponse(405, "Method not allowed.", { allow: "POST" });
+        }
+        const origin = request.headers?.get?.("origin");
+        const fetchSite = request.headers?.get?.("sec-fetch-site");
+        if (origin !== appOrigin || (fetchSite && fetchSite !== "same-origin")) {
+          return errorResponse(403, "Origin not allowed.");
+        }
+        let requestBody;
+        try {
+          requestBody = await request.json();
+        } catch {
+          return errorResponse(400, "Invalid host principal request.");
+        }
+        if (!requestBody || typeof requestBody !== "object" || Array.isArray(requestBody)
+          || Object.keys(requestBody).some((key) => key !== "resources")) {
+          return errorResponse(400, "Invalid host principal request.");
+        }
+        let resources;
+        try {
+          resources = principalResources(requestBody.resources);
+        } catch (error) {
+          return errorResponse(400, error.message);
+        }
+        const identity = await options.authenticate(request);
+        if (!identity) return errorResponse(401, "Authentication required.");
+        const exchange = await client.create({ ...identity, resources });
+        return Response.json({ token: exchange.token, expires_at: exchange.expiresAt }, {
+          headers: { "cache-control": "no-store" },
+        });
+      };
+    },
+    async revoke(options) {
+      const claims = principalClaims(options);
+      const response = await fetchFn(new URL("/v1/host-principal/sessions", baseUrl), {
+        method: "DELETE",
+        headers: serverHeaders(parameters.appId, parameters.secret),
+        body: JSON.stringify({
+          app_origin: appOrigin,
+          issuer: claims.issuer,
+          tenant: claims.tenant,
+          subject: claims.subject,
+          session_id: claims.sessionId,
+        }),
+        signal: options?.signal,
+      });
+      if (!response.ok) {
+        const body = await response.json().catch(() => undefined);
+        throw serviceError(response, body, "revocation");
+      }
+      await response.body?.cancel();
+    },
+  };
+  return Object.freeze(client);
+}
+
+function principalClaims(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || !boundedOpaqueClaim(value.issuer) || !boundedOpaqueClaim(value.tenant)
+    || !boundedOpaqueClaim(value.subject) || !boundedOpaqueClaim(value.sessionId)) {
+    throw new TypeError("host principal requires bounded opaque issuer, tenant, subject, and sessionId");
+  }
+  return {
+    issuer: value.issuer,
+    tenant: value.tenant,
+    subject: value.subject,
+    sessionId: value.sessionId,
+  };
+}
+
+function boundedOpaqueClaim(value) {
+  return typeof value === "string" && OPAQUE_CLAIM.test(value);
+}
+
+function principalResources(value) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 64
+    || value.some((resource) => typeof resource !== "string" || resource.length === 0
+      || resource.length > 512 || resource.startsWith(EXCHANGE_RESOURCE_PREFIX)
+      || forbiddenAuthority(resource))) {
+    throw new TypeError("host principal resources must be 1 through 64 bounded non-exchange strings");
+  }
+  return Object.freeze([...value]);
+}
+
+function forbiddenAuthority(resource) {
+  const value = resource.toLowerCase();
+  return value.startsWith("urn:nanocodex:mpp:")
+    || value.startsWith("urn:nanocodex:access-key:")
+    || value.startsWith("urn:nanocodex:access_key:")
+    || value === "urn:nanocodex:authorize-access-key";
+}
+
+function exchangeExpiry(value) {
+  if (value === undefined) return undefined;
+  if (!Number.isSafeInteger(value) || value < 30 || value > 300) {
+    throw new TypeError("host principal expiresIn must be between 30 and 300 seconds");
+  }
+  return value;
+}
+
+function exchangeFromWire(value) {
+  const now = Math.floor(Date.now() / 1_000);
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || !EXCHANGE_TOKEN.test(value.token)
+    || !Number.isSafeInteger(value.expires_at)
+    || value.expires_at <= now || value.expires_at > now + 300) {
+    throw new Error("Nanocodex returned an invalid host principal exchange.");
+  }
+  return Object.freeze({ token: value.token, expiresAt: value.expires_at });
+}
+
+function serverHeaders(appId, secret) {
+  return {
+    accept: "application/json",
+    authorization: `Bearer ${secret}`,
+    "content-type": "application/json",
+    "x-nanocodex-app-id": appId,
+  };
+}
+
+function serviceError(response, body, operation) {
+  const error = new Error(
+    body?.error?.message ?? `Nanocodex host principal ${operation} failed with ${response.status}.`,
+  );
+  error.status = response.status;
+  return error;
+}
+
+function errorResponse(status, message, headers = {}) {
+  return Response.json({ error: { message } }, {
+    status,
+    headers: { ...headers, "cache-control": "no-store" },
+  });
+}
+
+function serviceBaseUrl(value) {
+  const url = new URL(value);
+  const origin = publicOrigin(url.origin, "HostPrincipal.create baseUrl");
+  if (url.username || url.password || url.hash) {
+    throw new TypeError("HostPrincipal.create baseUrl cannot contain credentials or a fragment");
+  }
+  return new URL(origin);
+}
+
+function publicOrigin(value, label) {
+  if (typeof value !== "string") throw new TypeError(`${label} must be an exact origin`);
+  const url = new URL(value);
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname.toLowerCase());
+  if (url.origin !== value || (url.protocol !== "https:" && !(url.protocol === "http:" && loopback))
+    || url.username || url.password) {
+    throw new TypeError(`${label} must be an exact HTTPS or loopback origin`);
+  }
+  return url.origin;
+}

package/vendor/nanocodex/cloud/server/index.d.mts

@@ -0,0 +1 @@
+export * as HostPrincipal from "./HostPrincipal.mjs";

package/vendor/nanocodex/cloud/server/index.mjs

@@ -0,0 +1 @@
+export * as HostPrincipal from "./HostPrincipal.mjs";

package/vendor/nanocodex/cloud/types.d.mts

@@ -0,0 +1,211 @@
+export type Hex = `0x${string}`;
+
+export type CloudAccount =
+  | "github"
+  | "gmail"
+  | "gdrive"
+  | "gcalendar"
+  | "gtasks"
+  | "gdocs"
+  | "gsheets"
+  | "gslides"
+  | "gcontacts"
+  | "slack"
+  | "x"
+  | "chatgpt";
+
+/** Secret-free account identity returned by a connector status reader. */
+export type ConnectorConnection = Readonly<{
+  id: string;
+  label: string;
+  accountId?: string | undefined;
+  capabilities?: readonly CloudAccount[] | undefined;
+}>;
+
+/** Provider-neutral status for a connector service capability. */
+export type ConnectorStatus = Readonly<{
+  connected: boolean;
+  connections?: readonly ConnectorConnection[] | undefined;
+}>;
+
+/** Exact approved connector connection IDs keyed by service capability. */
+export type ConnectorConnectionSelection = Readonly<
+  Partial<Record<Exclude<CloudAccount, "chatgpt">, readonly string[]>>
+>;
+
+export type AccessKey = Readonly<{
+  address: Hex;
+  chainId: bigint;
+  keyId: Hex;
+  /** Public key material is present only when the caller supplied an external key. */
+  publicKey?: Hex | undefined;
+  keyType: "secp256k1" | "p256" | "webAuthn";
+  limits: readonly Readonly<{ token: Hex; limit: bigint; period?: number | undefined }>[];
+  scopes: readonly Readonly<{
+    address: Hex;
+    selector?: Hex | string | undefined;
+    recipients?: readonly Hex[] | undefined;
+  }>[];
+  witness: Hex;
+  expiry: number;
+  /** Canonical RLP-encoded, root-signed TIP-1053 authorization. */
+  authorization?: Hex | undefined;
+}>;
+
+export type AgentTurnResult = Readonly<{
+  turnId: string;
+  finalMessage: string;
+  provider: string;
+  capabilitiesUsed: readonly string[];
+  usage: import("../types.mjs").TurnUsage | null;
+  usageError?: string | undefined;
+  cursor?: string | undefined;
+}>;
+
+export type AgentVisibility = Readonly<{
+  finalMessages: boolean;
+  actionSummaries: boolean;
+  conversationHistory: boolean;
+  rawTraces: boolean;
+}>;
+
+/** Secret-free metadata for one account-owned hosted MCP connection. */
+export type McpConnection = Readonly<{
+  /** Exact opaque 43-character hosted connection ID. */
+  id: string;
+  /** Account-visible display name; endpoints and credentials remain broker-owned. */
+  name: string;
+}>;
+
+export type AgentTurn = Readonly<{
+  idempotencyKey: string;
+  accepted(): Promise<string>;
+  state(): Promise<import("../managed/Agent.mjs").TurnView>;
+  steer(options: Readonly<{ input: import("../types.mjs").PromptInput }>): Promise<Readonly<{
+    turn_id: string;
+    state: "steering";
+  }>>;
+  result(options?: import("../managed/Agent.mjs").TurnResultOptions): Promise<AgentTurnResult>;
+  cancel(): Promise<import("../managed/Agent.mjs").TurnView | Readonly<{
+    turn_id: string;
+    state: "cancelling";
+  }>>;
+}>;
+
+export type ConnectAgent = Readonly<{
+  id: string;
+  /** Alias matching the canonical Nanocodex Agent surface. */
+  sessionId: string;
+  type: "connect";
+  provider: string;
+  events: Readonly<{
+    page(options?: import("../managed/Agent.mjs").EventHistoryOptions): Promise<import("../managed/Agent.mjs").EventHistoryPage>;
+    watch(options?: import("../managed/Agent.mjs").WatchEventsOptions): AsyncIterableIterator<import("../managed/Agent.mjs").Event>;
+  }>;
+  mercator: Readonly<{
+    enabled: true;
+    readonly channelId: Hex | undefined;
+    readonly cumulative: bigint;
+    readonly opened: boolean;
+  }>;
+  turn: Readonly<{
+    prompt(options: import("../managed/Agent.mjs").PromptOptions): AgentTurn;
+  }>;
+  state(): Promise<import("../managed/Agent.mjs").State>;
+  session: Readonly<{ shutdown(): Promise<void> }>;
+}>;
+
+export type Grant = Readonly<{
+  id: Hex;
+  permission: string;
+  status: "active" | "revoked" | "expired";
+  expiresAt: number;
+  /** App-generated signed selector for this exact durable conversation. */
+  conversationId?: string | undefined;
+  capabilities: readonly string[];
+  visibility: AgentVisibility;
+  /** Secret-free cloud account providers bound to this grant. */
+  connectors: readonly CloudAccount[];
+  /** Exact account connection subset. Absent only when reading a legacy grant. */
+  connectorConnections?: ConnectorConnectionSelection | undefined;
+  /** Exact secret-free hosted MCP connections bound to this grant. */
+  mcpConnections: readonly McpConnection[];
+  /** Exact signed app-local reverse-tool catalog, when present. */
+  appToolCatalogDigest?: Hex | undefined;
+}>;
+
+export type MppPermission = Readonly<{
+  token: Hex;
+  symbol: string;
+  balance: bigint;
+  balanceStatus: "pending" | "ready";
+  settlementToken: Hex;
+  settlementSymbol: string;
+  settlementBalance: bigint;
+  spent: bigint;
+  limit: bigint;
+  period: number;
+  maxPerRequest: bigint;
+}>;
+
+type ConnectionBase = Readonly<{
+  agentId: string;
+  grant: Grant;
+}>;
+
+export type WalletConnection = ConnectionBase & Readonly<{
+  accountAddress: Hex;
+  principal?: undefined;
+}> & (
+  | Readonly<{
+    authorization: "access_key";
+    accessKey: AccessKey;
+    mpp: MppPermission;
+  }>
+  | Readonly<{
+    authorization: "hosted";
+    accessKey?: undefined;
+    mpp?: undefined;
+  }>
+);
+
+export type HostConnection = ConnectionBase & Readonly<{
+  accountAddress?: undefined;
+  principal: Readonly<{ kind: "host"; id: string }>;
+  authorization: "hosted";
+  accessKey?: undefined;
+  mpp?: undefined;
+}>;
+
+/** The stable passkey/wallet connection contract. */
+export type Connection = WalletConnection;
+
+export type MachineUsdConfig = Readonly<{
+  chainId: number;
+  minUsdAmountCents: number;
+  maxUsdAmountCents: number;
+  onrampEnabled: boolean;
+  stripePublishableKey: string;
+  tokenAddress: Hex;
+}>;
+
+export type MachineUsdFunding = Readonly<{
+  order: Readonly<{
+    id: string;
+    status: string;
+    usdAmountCents: number;
+    machineUsdAmount: bigint;
+    issuanceTransactionHash: Hex;
+  }>;
+  connection: Connection;
+}>;
+
+export type MppCharge = Readonly<{
+  receipt: Readonly<{
+    id: string;
+    amount: bigint;
+    origin: string;
+    transactionHash: Hex;
+  }>;
+  connection: Connection;
+}>;

package/vendor/nanocodex/cloudflare/Agent.d.mts

@@ -0,0 +1,133 @@
+import type {
+  Agent as BaseAgent,
+  AgentActions,
+  AgentOptions,
+  AgentEvent,
+  DefaultAgent,
+  ToolConfiguration,
+} from "../types.mjs";
+import type { CloudflareDurableObjectStorage } from "../runtime/cloudflare-durability-store.mjs";
+import type { Tool as SubagentTool } from "../runtime/subagents.mjs";
+import type {
+  DurabilityExportPageRequest,
+  DurabilityPortableStateArchive,
+  DurabilityPortableStatePage,
+  DurabilityStoredState,
+} from "../types.mjs";
+
+export type DurableObjectContext = Readonly<{
+  storage: CloudflareDurableObjectStorage;
+  acceptWebSocket(socket: WebSocket, tags?: string[]): void;
+  getWebSockets(tag?: string): WebSocket[];
+}>;
+
+/** The owning Cloudflare Durable Object instance. Runtime fields remain adapter-private. */
+export type DurableObjectOwner = object;
+
+/** Rust-owned first-prompt retrieval policy; the host owns authenticated execution. */
+export type BootstrapPlan = Readonly<{
+  query: string;
+  voice_bootstrap: boolean;
+  calls: readonly Readonly<{ name: "find_session" | "memory"; arguments: unknown }>[];
+}>;
+export function bootstrapPlan(input: string): Promise<BootstrapPlan>;
+
+export type EventFrame = Readonly<{
+  cursor: string;
+  event: AgentEvent;
+}> | Readonly<{
+  type: "replay_paused";
+  cursor: string;
+  latest_cursor: string;
+}>;
+
+type CloudflareAgentActions = Omit<AgentActions, "events" | "turn"> & Readonly<{
+  events: AgentActions["events"] & Readonly<{
+    /** Accepts a read-only hibernatable event socket; reconnect from the last event or replay pause cursor. */
+    connect(request: Request): Response;
+  }>;
+  turn: AgentActions["turn"] & Readonly<{
+    /** Atomically steers the active turn or starts a new independently awaitable turn. */
+    route(options: { input: string }): Promise<import("../types.mjs").Turn | undefined>;
+  }>;
+}>;
+
+/** A durable Agent whose Cloudflare event socket survives typed extensions. */
+export type Agent<extended extends object = {}> =
+  Omit<BaseAgent<CloudflareAgentActions & extended>, "extend"> & Readonly<{
+    extend<const extension extends object>(
+      decorator: (agent: Agent<extended>) => extension,
+    ): Agent<extended & extension>;
+  }>;
+
+/** Removes the package-owned durable history for one Cloudflare Agent. */
+export function destroy(owner: DurableObjectOwner): void;
+
+/** Fences and exports this inactive Cloudflare Agent's provider-neutral state. */
+export function exportDurabilityState(
+  owner: DurableObjectOwner,
+): Promise<DurabilityPortableStateArchive>;
+
+/** Fences once and exports one resumable page of an exact revision range. */
+export function exportDurabilityState(
+  owner: DurableObjectOwner,
+  request: DurabilityExportPageRequest,
+): Promise<DurabilityPortableStatePage>;
+
+/** Imports provider-neutral state into a pristine Cloudflare Agent owner. */
+export function importDurabilityState(
+  owner: DurableObjectOwner,
+  archive: DurabilityPortableStateArchive,
+): Promise<DurabilityStoredState>;
+
+/** Prunes old terminal receipts before constructing the full Agent runtime. */
+export function pruneDurableReceipts(
+  owner: DurableObjectOwner,
+  options?: Readonly<{ terminalReceiptRetention?: number | undefined }>,
+): Promise<void>;
+
+/** Atomically steers an active Cloudflare Agent turn or starts a new turn. */
+export function route(
+  agent: Agent,
+  options: { input: string },
+): Promise<import("../types.mjs").Turn | undefined>;
+
+/** Creates one durable Agent from its owning Durable Object instance. */
+export function create(owner: create.Owner, options?: create.Options): Promise<create.ReturnType>;
+export declare namespace create {
+  type Owner = DurableObjectOwner;
+  type Options = Readonly<{
+    /** Stable portable state identity. It cannot change after first construction or import. */
+    durabilityId?: string | undefined;
+    /**
+     * `durable` retains the adapter's resumable event socket. `caller` leaves
+     * event retention to the embedding Durable Object and disables connect().
+     */
+    eventPersistence?: "durable" | "caller" | undefined;
+    instructions?: string | undefined;
+    /** Appends host instructions while retaining the selected model's prompt. */
+    additionalInstructions?: string | undefined;
+    /**
+     * Bounds terminal receipts retained in the hot Rust state checkpoint.
+     * The caller must preserve older exact-ID results before selecting this.
+     */
+    terminalReceiptRetention?: number | undefined;
+    /** Live child execution is in-memory; interrupted descriptors survive reconstruction. */
+    tools?: ToolConfiguration<SubagentTool> | undefined;
+  }>;
+  type ReturnType = Agent;
+}
+
+/** Creates one non-durable Rust/WASM Agent in the current Cloudflare isolate. */
+export function createEphemeral(
+  owner: createEphemeral.Owner,
+  options?: createEphemeral.Options,
+): Promise<createEphemeral.ReturnType>;
+export declare namespace createEphemeral {
+  type Owner = DurableObjectOwner;
+  type Options = Readonly<AgentOptions & {
+    /** Caller-owned tools exposed directly to the model. */
+    tools?: ToolConfiguration<SubagentTool> | undefined;
+  }>;
+  type ReturnType = DefaultAgent;
+}