@valon-technologies/gestalt 0.0.1-alpha.11 → 0.0.1-alpha.13

package/src/cache.ts

@@ -1,13 +1,16 @@
 import { connect } from "node:net";
 
-import { createClient, type Client } from "@connectrpc/connect";
+import { createClient, type Client, type Interceptor } from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
 
 import { Cache as CacheService } from "../gen/v1/cache_pb.ts";
 import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
 import type { MaybePromise } from "./api.ts";
 
-const ENV_CACHE_SOCKET = "GESTALT_CACHE_SOCKET";
+export const ENV_CACHE_SOCKET = "GESTALT_CACHE_SOCKET";
+const CACHE_SOCKET_TOKEN_SUFFIX = "_TOKEN";
+const CACHE_RELAY_TOKEN_HEADER = "x-gestalt-host-service-relay-token";
+export const ENV_CACHE_SOCKET_TOKEN = `${ENV_CACHE_SOCKET}${CACHE_SOCKET_TOKEN_SUFFIX}`;
 
 /**
  * Single cache entry used by batch cache APIs.
@@ -55,6 +58,49 @@ export function cacheSocketEnv(name?: string): string {
   return `${ENV_CACHE_SOCKET}_${trimmed.replace(/[^A-Za-z0-9]/gu, "_").toUpperCase()}`;
 }
 
+/**
+ * Returns the environment variable name used to discover a cache relay token.
+ */
+export function cacheSocketTokenEnv(name?: string): string {
+  return `${cacheSocketEnv(name)}${CACHE_SOCKET_TOKEN_SUFFIX}`;
+}
+
+function cacheTransportOptions(rawTarget: string): {
+  baseUrl: string;
+  nodeOptions?: { path: string };
+} {
+  const target = rawTarget.trim();
+  if (!target) {
+    throw new Error("cache transport target is required");
+  }
+  if (target.startsWith("tcp://")) {
+    const address = target.slice("tcp://".length).trim();
+    if (!address) {
+      throw new Error(`cache tcp target ${JSON.stringify(rawTarget)} is missing host:port`);
+    }
+    return { baseUrl: `http://${address}` };
+  }
+  if (target.startsWith("tls://")) {
+    const address = target.slice("tls://".length).trim();
+    if (!address) {
+      throw new Error(`cache tls target ${JSON.stringify(rawTarget)} is missing host:port`);
+    }
+    return { baseUrl: `https://${address}` };
+  }
+  if (target.startsWith("unix://")) {
+    const socketPath = target.slice("unix://".length).trim();
+    if (!socketPath) {
+      throw new Error(`cache unix target ${JSON.stringify(rawTarget)} is missing a socket path`);
+    }
+    return { baseUrl: "http://localhost", nodeOptions: { path: socketPath } };
+  }
+  if (target.includes("://")) {
+    const parsed = new URL(target);
+    throw new Error(`Unsupported cache target scheme ${JSON.stringify(parsed.protocol.replace(/:$/, ""))}`);
+  }
+  return { baseUrl: "http://localhost", nodeOptions: { path: target } };
+}
+
 /**
  * Client for invoking a host-provided cache over the Gestalt transport.
  *
@@ -71,16 +117,30 @@ export class Cache {
 
   constructor(name?: string) {
     const envName = cacheSocketEnv(name);
-    const socketPath = process.env[envName];
-    if (!socketPath) {
+    const target = process.env[envName];
+    if (!target) {
       throw new Error(`cache: ${envName} is not set`);
     }
-
+    const token = process.env[cacheSocketTokenEnv(name)]?.trim() ?? "";
+    const transportOptions = cacheTransportOptions(target);
+    const interceptors: Interceptor[] = token
+      ? [
+          (next) => async (req) => {
+            req.header.set(CACHE_RELAY_TOKEN_HEADER, token);
+            return await next(req);
+          },
+        ]
+      : [];
     const transport = createGrpcTransport({
-      baseUrl: "http://localhost",
-      nodeOptions: {
-        createConnection: () => connect(socketPath),
-      },
+      ...transportOptions,
+      ...(transportOptions.nodeOptions
+        ? {
+            nodeOptions: {
+              createConnection: () => connect(transportOptions.nodeOptions!.path),
+            },
+          }
+        : {}),
+      interceptors,
     });
     this.client = createClient(CacheService, transport);
   }

package/src/http-subject.ts

@@ -0,0 +1,113 @@
+import type { Access, Credential, MaybePromise, Subject } from "./api.ts";
+
+/**
+ * Verified hosted HTTP request metadata passed into optional plugin-local
+ * subject resolution hooks before normal operation dispatch.
+ */
+export interface HTTPSubjectRequest {
+  binding: string;
+  method: string;
+  path: string;
+  contentType: string;
+  headers: Record<string, string[]>;
+  query: Record<string, string[]>;
+  params: Record<string, unknown>;
+  rawBody: Uint8Array;
+  securityScheme: string;
+  verifiedSubject: string;
+  verifiedClaims: Record<string, string>;
+}
+
+/**
+ * Request-scoped caller context available while resolving the concrete subject
+ * for a hosted HTTP request.
+ */
+export interface HTTPSubjectResolutionContext {
+  subject: Subject;
+  credential: Credential;
+  access: Access;
+  workflow: Record<string, unknown>;
+}
+
+/**
+ * Explicit HTTP rejection surfaced from a hosted HTTP subject resolver.
+ */
+export class HTTPSubjectResolutionError extends Error {
+  readonly status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "HTTPSubjectResolutionError";
+    this.status = status;
+  }
+}
+
+/**
+ * Creates an explicit hosted HTTP subject-resolution rejection.
+ */
+export function httpSubjectError(
+  status: number,
+  message: string,
+): HTTPSubjectResolutionError {
+  return new HTTPSubjectResolutionError(status, message);
+}
+
+/**
+ * Optional hook that maps a verified hosted HTTP request to a concrete Gestalt
+ * subject before the target operation is authorized and executed.
+ */
+export type HTTPSubjectResolver = (
+  request: HTTPSubjectRequest,
+  context: HTTPSubjectResolutionContext,
+) => MaybePromise<Subject | null | undefined>;
+
+export function cloneHTTPSubjectRequest(
+  input: HTTPSubjectRequest,
+): HTTPSubjectRequest {
+  return {
+    binding: input.binding,
+    method: input.method,
+    path: input.path,
+    contentType: input.contentType,
+    headers: cloneStringLists(input.headers),
+    query: cloneStringLists(input.query),
+    params: {
+      ...input.params,
+    },
+    rawBody: new Uint8Array(input.rawBody),
+    securityScheme: input.securityScheme,
+    verifiedSubject: input.verifiedSubject,
+    verifiedClaims: {
+      ...input.verifiedClaims,
+    },
+  };
+}
+
+export function cloneHTTPSubjectResolutionContext(
+  input: HTTPSubjectResolutionContext,
+): HTTPSubjectResolutionContext {
+  return {
+    subject: {
+      ...input.subject,
+    },
+    credential: {
+      ...input.credential,
+    },
+    access: {
+      ...input.access,
+    },
+    workflow: {
+      ...input.workflow,
+    },
+  };
+}
+
+function cloneStringLists(
+  input: Record<string, string[]>,
+): Record<string, string[]> {
+  const output: Record<string, string[]> = {};
+  for (const [key, value] of Object.entries(input)) {
+    output[key] = [...value];
+  }
+  return output;
+}

package/src/index.ts

@@ -28,6 +28,23 @@
  * import { parseRuntimeArgs, serve } from "@valon-technologies/gestalt/runtime";
  * ```
  */
+export {
+  Authorization,
+  AuthorizationClient,
+  ENV_AUTHORIZATION_SOCKET,
+  ENV_AUTHORIZATION_SOCKET_TOKEN,
+  type AuthorizationActionSearchMessage,
+  type AuthorizationDecisionMessage,
+  type AuthorizationEvaluateInput,
+  type AuthorizationMetadataMessage,
+  type AuthorizationReadRelationshipsInput,
+  type AuthorizationReadRelationshipsMessage,
+  type AuthorizationResourceSearchMessage,
+  type AuthorizationSearchActionsInput,
+  type AuthorizationSearchResourcesInput,
+  type AuthorizationSearchSubjectsInput,
+  type AuthorizationSubjectSearchMessage,
+} from "./authorization.ts";
 export {
   connectionParam,
   ok,
@@ -42,6 +59,13 @@ export {
   type Response,
   type Subject,
 } from "./api.ts";
+export {
+  type HTTPSubjectRequest,
+  type HTTPSubjectResolutionContext,
+  HTTPSubjectResolutionError,
+  type HTTPSubjectResolver,
+  httpSubjectError,
+} from "./http-subject.ts";
 export {
   catalogToJson,
   catalogToYaml,
@@ -76,20 +100,47 @@ export {
 } from "./build.ts";
 export {
   ENV_PLUGIN_INVOKER_SOCKET,
+  ENV_PLUGIN_INVOKER_SOCKET_TOKEN,
   PluginInvoker,
   type PluginGraphQLInvokeOptions,
   type PluginInvocationGrant,
   type PluginInvokeOptions,
 } from "./invoker.ts";
+export {
+  ENV_AGENT_MANAGER_SOCKET,
+  ENV_AGENT_MANAGER_SOCKET_TOKEN,
+  AgentManager,
+  type AgentManagerCancelTurnInput,
+  type AgentManagerCreateSessionInput,
+  type AgentManagerCreateTurnInput,
+  type AgentManagerGetSessionInput,
+  type AgentManagerGetTurnInput,
+  type AgentManagerListInteractionsInput,
+  type AgentManagerListSessionsInput,
+  type AgentManagerListTurnEventsInput,
+  type AgentManagerListTurnsInput,
+  type AgentManagerResolveInteractionInput,
+  type AgentManagerUpdateSessionInput,
+} from "./agent-manager.ts";
 export {
   ENV_WORKFLOW_MANAGER_SOCKET,
+  ENV_WORKFLOW_MANAGER_SOCKET_TOKEN,
   WorkflowManager,
+  type ManagedWorkflowEventTriggerMessage,
   type ManagedWorkflowScheduleMessage,
+  type WorkflowEventMessage,
+  type WorkflowManagerCreateTriggerInput,
   type WorkflowManagerCreateScheduleInput,
+  type WorkflowManagerDeleteTriggerInput,
   type WorkflowManagerDeleteScheduleInput,
+  type WorkflowManagerGetTriggerInput,
   type WorkflowManagerGetScheduleInput,
+  type WorkflowManagerPauseTriggerInput,
   type WorkflowManagerPauseScheduleInput,
+  type WorkflowManagerPublishEventInput,
+  type WorkflowManagerResumeTriggerInput,
   type WorkflowManagerResumeScheduleInput,
+  type WorkflowManagerUpdateTriggerInput,
   type WorkflowManagerUpdateScheduleInput,
 } from "./workflow-manager.ts";
 export {
@@ -107,8 +158,11 @@ export {
   Cache,
   CacheProvider,
   cacheSocketEnv,
+  cacheSocketTokenEnv,
   defineCacheProvider,
   isCacheProvider,
+  ENV_CACHE_SOCKET,
+  ENV_CACHE_SOCKET_TOKEN,
   type CacheEntry,
   type CacheProviderOptions,
   type CacheSetOptions,
@@ -119,6 +173,7 @@ export {
   type SecretsProviderOptions,
 } from "./secrets.ts";
 export {
+  type ConnectedToken,
   PluginProvider,
   connectionModeToProtoValue,
   connectionParamToProto,
@@ -129,6 +184,7 @@ export {
   type ConnectionParamDefinition,
   type OperationDefinition,
   type OperationOptions,
+  type PostConnectHandler,
   type PluginDefinitionOptions,
   type SessionCatalog,
   type SessionCatalogHandler,
@@ -200,6 +256,7 @@ export {
   AlreadyExistsError,
   ColumnType,
   indexedDBSocketEnv,
+  indexedDBSocketTokenEnv,
   type Record,
   type KeyRange,
   type ColumnSchema,
@@ -218,7 +275,10 @@ export {
   createS3Service,
   defineS3Provider,
   isS3Provider,
+  ENV_S3_SOCKET,
+  ENV_S3_SOCKET_TOKEN,
   s3SocketEnv,
+  s3SocketTokenEnv,
   type ByteRange,
   type CopyOptions,
   type ListOptions,
@@ -234,6 +294,50 @@ export {
   type S3ProviderOptions,
   type WriteOptions,
 } from "./s3.ts";
+export {
+  ENV_AGENT_HOST_SOCKET,
+  AgentHost,
+  AgentExecutionStatus,
+  AgentInteractionState,
+  AgentInteractionType,
+  AgentMessagePartType,
+  AgentProvider,
+  AgentSessionState,
+  AgentToolSourceMode,
+  createAgentProviderService,
+  defineAgentProvider,
+  isAgentProvider,
+  type AgentActor,
+  type AgentInteraction,
+  type AgentMessage,
+  type AgentMessagePart,
+  type AgentMessagePartImageRef,
+  type AgentMessagePartToolCall,
+  type AgentMessagePartToolResult,
+  type AgentProviderCapabilities,
+  type AgentProviderOptions,
+  type AgentSession,
+  type AgentToolRef,
+  type AgentTurn,
+  type AgentTurnEvent,
+  type BoundAgentToolTarget,
+  type CancelAgentProviderTurnRequest,
+  type CreateAgentProviderSessionRequest,
+  type CreateAgentProviderTurnRequest,
+  type ExecuteAgentToolRequest,
+  type ExecuteAgentToolResponse,
+  type GetAgentProviderCapabilitiesRequest,
+  type GetAgentProviderInteractionRequest,
+  type GetAgentProviderSessionRequest,
+  type GetAgentProviderTurnRequest,
+  type ListAgentProviderInteractionsRequest,
+  type ListAgentProviderSessionsRequest,
+  type ListAgentProviderTurnEventsRequest,
+  type ListAgentProviderTurnsRequest,
+  type ResolvedAgentTool,
+  type ResolveAgentProviderInteractionRequest,
+  type UpdateAgentProviderSessionRequest,
+} from "./agent.ts";
 export {
   ENV_WORKFLOW_HOST_SOCKET,
   WorkflowHost,

package/src/indexeddb.ts

@@ -1,4 +1,4 @@
-import { createClient, type Client } from "@connectrpc/connect";
+import { createClient, type Client, type Interceptor } from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
 import {
   IndexedDB as IndexedDBService,
@@ -6,6 +6,8 @@ import {
 } from "../gen/v1/datastore_pb";
 
 const ENV_INDEXEDDB_SOCKET = "GESTALT_INDEXEDDB_SOCKET";
+const INDEXEDDB_SOCKET_TOKEN_SUFFIX = "_TOKEN";
+const INDEXEDDB_RELAY_TOKEN_HEADER = "x-gestalt-host-service-relay-token";
 
 /**
  * Returns the environment variable name used to discover an IndexedDB socket.
@@ -16,6 +18,49 @@ export function indexedDBSocketEnv(name?: string): string {
   return `${ENV_INDEXEDDB_SOCKET}_${trimmed.replace(/[^A-Za-z0-9]/g, "_").toUpperCase()}`;
 }
 
+/**
+ * Returns the environment variable name used to discover an IndexedDB relay token.
+ */
+export function indexedDBSocketTokenEnv(name?: string): string {
+  return `${indexedDBSocketEnv(name)}${INDEXEDDB_SOCKET_TOKEN_SUFFIX}`;
+}
+
+function indexedDBTransportOptions(rawTarget: string): {
+  baseUrl: string;
+  nodeOptions?: { path: string };
+} {
+  const target = rawTarget.trim();
+  if (!target) {
+    throw new Error("IndexedDB transport target is required");
+  }
+  if (target.startsWith("tcp://")) {
+    const address = target.slice("tcp://".length).trim();
+    if (!address) {
+      throw new Error(`IndexedDB tcp target ${JSON.stringify(rawTarget)} is missing host:port`);
+    }
+    return { baseUrl: `http://${address}` };
+  }
+  if (target.startsWith("tls://")) {
+    const address = target.slice("tls://".length).trim();
+    if (!address) {
+      throw new Error(`IndexedDB tls target ${JSON.stringify(rawTarget)} is missing host:port`);
+    }
+    return { baseUrl: `https://${address}` };
+  }
+  if (target.startsWith("unix://")) {
+    const socketPath = target.slice("unix://".length).trim();
+    if (!socketPath) {
+      throw new Error(`IndexedDB unix target ${JSON.stringify(rawTarget)} is missing a socket path`);
+    }
+    return { baseUrl: "http://localhost", nodeOptions: { path: socketPath } };
+  }
+  if (target.includes("://")) {
+    const parsed = new URL(target);
+    throw new Error(`Unsupported IndexedDB target scheme ${JSON.stringify(parsed.protocol.replace(/:$/, ""))}`);
+  }
+  return { baseUrl: "http://localhost", nodeOptions: { path: target } };
+}
+
 class AsyncQueue<T> implements AsyncIterable<T> {
   private queue: T[] = [];
   private waiting: ((result: IteratorResult<T>) => void) | null = null;
@@ -447,15 +492,16 @@ export interface ObjectStoreSchema {
 export class IndexedDB {
   private client: Client<typeof IndexedDBService>;
 
-  constructor(name?: string) {
+ constructor(name?: string) {
     const envName = indexedDBSocketEnv(name);
-    const socketPath = process.env[envName];
-    if (!socketPath) {
+    const target = process.env[envName];
+    if (!target) {
       throw new Error(`${envName} is not set`);
     }
+    const token = process.env[indexedDBSocketTokenEnv(name)]?.trim() ?? "";
     const transport = createGrpcTransport({
-      baseUrl: `http://localhost`,
-      nodeOptions: { path: socketPath },
+      ...indexedDBTransportOptions(target),
+      interceptors: token ? [indexedDBRelayTokenInterceptor(token)] : [],
     });
     this.client = createClient(IndexedDBService, transport);
   }
@@ -498,6 +544,13 @@ export class IndexedDB {
   }
 }
 
+function indexedDBRelayTokenInterceptor(token: string): Interceptor {
+  return (next) => async (req) => {
+    req.header.set(INDEXEDDB_RELAY_TOKEN_HEADER, token);
+    return next(req);
+  };
+}
+
 /**
  * Object store client used for primary-key operations.
  */

package/src/invoker.ts

@@ -1,13 +1,13 @@
-import { connect } from "node:net";
-
 import type { JsonObject, JsonValue } from "@bufbuild/protobuf";
-import { createClient, type Client } from "@connectrpc/connect";
+import { createClient, type Client, type Interceptor } from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
 
 import { PluginInvoker as PluginInvokerService } from "../gen/v1/plugin_pb.ts";
 import type { OperationResult, Request } from "./api.ts";
 
 export const ENV_PLUGIN_INVOKER_SOCKET = "GESTALT_PLUGIN_INVOKER_SOCKET";
+export const ENV_PLUGIN_INVOKER_SOCKET_TOKEN = `${ENV_PLUGIN_INVOKER_SOCKET}_TOKEN`;
+const PLUGIN_INVOKER_RELAY_TOKEN_HEADER = "x-gestalt-host-service-relay-token";
 
 export interface PluginInvokeOptions {
   connection?: string;
@@ -38,12 +38,11 @@ export class PluginInvoker {
     if (!socketPath) {
       throw new Error(`plugin invoker: ${ENV_PLUGIN_INVOKER_SOCKET} is not set`);
     }
+    const relayToken = process.env[ENV_PLUGIN_INVOKER_SOCKET_TOKEN]?.trim() ?? "";
 
     const transport = createGrpcTransport({
-      baseUrl: "http://localhost",
-      nodeOptions: {
-        createConnection: () => connect(socketPath),
-      },
+      ...pluginInvokerTransportOptions(socketPath),
+      interceptors: relayToken ? [pluginInvokerRelayTokenInterceptor(relayToken)] : [],
     });
     this.client = createClient(PluginInvokerService, transport);
   }
@@ -118,6 +117,49 @@ export class PluginInvoker {
   }
 }
 
+function pluginInvokerTransportOptions(rawTarget: string): {
+  baseUrl: string;
+  nodeOptions?: { path: string };
+} {
+  const target = rawTarget.trim();
+  if (!target) {
+    throw new Error("plugin invoker: transport target is required");
+  }
+  if (target.startsWith("tcp://")) {
+    const address = target.slice("tcp://".length).trim();
+    if (!address) {
+      throw new Error(`plugin invoker: tcp target ${JSON.stringify(rawTarget)} is missing host:port`);
+    }
+    return { baseUrl: `http://${address}` };
+  }
+  if (target.startsWith("tls://")) {
+    const address = target.slice("tls://".length).trim();
+    if (!address) {
+      throw new Error(`plugin invoker: tls target ${JSON.stringify(rawTarget)} is missing host:port`);
+    }
+    return { baseUrl: `https://${address}` };
+  }
+  if (target.startsWith("unix://")) {
+    const socketPath = target.slice("unix://".length).trim();
+    if (!socketPath) {
+      throw new Error(`plugin invoker: unix target ${JSON.stringify(rawTarget)} is missing a socket path`);
+    }
+    return { baseUrl: "http://localhost", nodeOptions: { path: socketPath } };
+  }
+  if (target.includes("://")) {
+    const parsed = new URL(target);
+    throw new Error(`plugin invoker: unsupported target scheme ${JSON.stringify(parsed.protocol.replace(/:$/, ""))}`);
+  }
+  return { baseUrl: "http://localhost", nodeOptions: { path: target } };
+}
+
+function pluginInvokerRelayTokenInterceptor(token: string): Interceptor {
+  return (next) => async (req) => {
+    req.header.set(PLUGIN_INVOKER_RELAY_TOKEN_HEADER, token);
+    return next(req);
+  };
+}
+
 function normalizeInvocationToken(requestOrToken: Request | string): string {
   const invocationToken =
     typeof requestOrToken === "string"

package/src/manifest-metadata.ts

@@ -3,7 +3,7 @@ import { writeFileSync } from "node:fs";
 import YAML from "yaml";
 
 export type HTTPSecuritySchemeType =
-  | "slack_signature"
+  | "hmac"
   | "apiKey"
   | "http"
   | "none";
@@ -20,6 +20,11 @@ export interface HTTPSecretRef {
 export interface HTTPSecurityScheme {
   type?: HTTPSecuritySchemeType;
   description?: string;
+  signatureHeader?: string;
+  signaturePrefix?: string;
+  payloadTemplate?: string;
+  timestampHeader?: string;
+  maxAgeSeconds?: number;
   name?: string;
   in?: HTTPIn;
   scheme?: HTTPAuthScheme;
@@ -42,6 +47,7 @@ export interface HTTPAck {
 export interface HTTPBinding {
   path: string;
   method: string;
+  credentialMode?: "none" | "user";
   requestBody?: HTTPRequestBody;
   security: string;
   target: string;