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

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,22 @@
  * import { parseRuntimeArgs, serve } from "@valon-technologies/gestalt/runtime";
  * ```
  */
+export {
+  Authorization,
+  AuthorizationClient,
+  ENV_AUTHORIZATION_SOCKET,
+  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 +58,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,6 +99,7 @@ export {
 } from "./build.ts";
 export {
   ENV_PLUGIN_INVOKER_SOCKET,
+  ENV_PLUGIN_INVOKER_SOCKET_TOKEN,
   PluginInvoker,
   type PluginGraphQLInvokeOptions,
   type PluginInvocationGrant,
@@ -84,12 +108,21 @@ export {
 export {
   ENV_WORKFLOW_MANAGER_SOCKET,
   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 +140,11 @@ export {
   Cache,
   CacheProvider,
   cacheSocketEnv,
+  cacheSocketTokenEnv,
   defineCacheProvider,
   isCacheProvider,
+  ENV_CACHE_SOCKET,
+  ENV_CACHE_SOCKET_TOKEN,
   type CacheEntry,
   type CacheProviderOptions,
   type CacheSetOptions,
@@ -200,6 +236,7 @@ export {
   AlreadyExistsError,
   ColumnType,
   indexedDBSocketEnv,
+  indexedDBSocketTokenEnv,
   type Record,
   type KeyRange,
   type ColumnSchema,

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;

package/src/plugin.ts

@@ -23,7 +23,15 @@ import {
   type Request,
   responseBrand,
   type Response,
+  type Subject,
 } from "./api.ts";
+import {
+  cloneHTTPSubjectRequest,
+  cloneHTTPSubjectResolutionContext,
+  type HTTPSubjectRequest,
+  type HTTPSubjectResolutionContext,
+  type HTTPSubjectResolver,
+} from "./http-subject.ts";
 import { RuntimeProvider, type RuntimeProviderOptions } from "./provider.ts";
 import type { Schema } from "./schema.ts";
 
@@ -93,6 +101,7 @@ export interface PluginDefinitionOptions extends RuntimeProviderOptions {
   connectionParams?: Record<string, ConnectionParamDefinition>;
   securitySchemes?: Record<string, HTTPSecurityScheme>;
   http?: Record<string, HTTPBinding>;
+  resolveHTTPSubject?: HTTPSubjectResolver;
   iconSvg?: string;
   operations: Array<OperationDefinition<any, any>>;
   sessionCatalog?: SessionCatalogHandler;
@@ -149,6 +158,7 @@ export class PluginProvider extends RuntimeProvider {
   readonly http: Record<string, HTTPBinding>;
 
   private readonly sessionCatalogHandler: SessionCatalogHandler | undefined;
+  private readonly httpSubjectResolver: HTTPSubjectResolver | undefined;
   private readonly operations = new Map<string, OperationDefinition<any, any>>();
 
   constructor(options: PluginDefinitionOptions) {
@@ -159,6 +169,7 @@ export class PluginProvider extends RuntimeProvider {
     this.connectionParams = normalizeConnectionParams(options.connectionParams);
     this.securitySchemes = normalizeHTTPSecuritySchemes(options.securitySchemes);
     this.http = normalizeHTTPBindings(options.http);
+    this.httpSubjectResolver = options.resolveHTTPSubject;
     this.sessionCatalogHandler = options.sessionCatalog;
 
     for (const rawEntry of options.operations) {
@@ -189,6 +200,20 @@ export class PluginProvider extends RuntimeProvider {
     return await this.sessionCatalogHandler?.(request);
   }
 
+  /**
+   * Resolves the concrete Gestalt subject for a verified hosted HTTP request,
+   * if the plugin opts into subject resolution.
+   */
+  async resolveHTTPSubject(
+    request: HTTPSubjectRequest,
+    context: HTTPSubjectResolutionContext,
+  ): Promise<Subject | null | undefined> {
+    return await this.httpSubjectResolver?.(
+      cloneHTTPSubjectRequest(request),
+      cloneHTTPSubjectResolutionContext(context),
+    );
+  }
+
   /**
    * Returns the static catalog emitted during provider startup.
    */
@@ -424,6 +449,21 @@ function cloneHTTPSecurityScheme(value: HTTPSecurityScheme): HTTPSecurityScheme
   if (value.description !== undefined) {
     output.description = value.description;
   }
+  if (value.signatureHeader !== undefined) {
+    output.signatureHeader = value.signatureHeader;
+  }
+  if (value.signaturePrefix !== undefined) {
+    output.signaturePrefix = value.signaturePrefix;
+  }
+  if (value.payloadTemplate !== undefined) {
+    output.payloadTemplate = value.payloadTemplate;
+  }
+  if (value.timestampHeader !== undefined) {
+    output.timestampHeader = value.timestampHeader;
+  }
+  if (value.maxAgeSeconds !== undefined) {
+    output.maxAgeSeconds = value.maxAgeSeconds;
+  }
   if (value.name !== undefined) {
     output.name = value.name;
   }

package/src/runtime.ts

@@ -40,9 +40,12 @@ import {
   CatalogSchema as ProtoCatalogSchema,
   ConnectionMode as ProviderConnectionMode,
   GetSessionCatalogResponseSchema,
+  ResolveHTTPSubjectResponseSchema,
   OperationResultSchema,
   ProviderMetadataSchema,
+  type HTTPSubjectRequest as ProtoHTTPSubjectRequest,
   type RequestContext as ProtoRequestContext,
+  type ResolveHTTPSubjectRequest as ProtoResolveHTTPSubjectRequest,
   IntegrationProvider as IntegrationProviderService,
   StartProviderResponseSchema,
   type ExecuteRequest,
@@ -68,6 +71,11 @@ import {
 import { CacheProvider, isCacheProvider } from "./cache.ts";
 import { SecretsProvider, isSecretsProvider } from "./secrets.ts";
 import { catalogToYaml, type Catalog } from "./catalog.ts";
+import {
+  HTTPSubjectResolutionError,
+  type HTTPSubjectRequest,
+  type HTTPSubjectResolutionContext,
+} from "./http-subject.ts";
 import {
   PluginProvider,
   connectionModeToProtoValue,
@@ -519,6 +527,36 @@ export function createProviderService(
         ),
       );
     },
+    async resolveHTTPSubject(request: ProtoResolveHTTPSubjectRequest) {
+      let subject;
+      try {
+        subject = await provider.resolveHTTPSubject(
+          providerHTTPSubjectRequest(request.request),
+          providerHTTPSubjectResolutionContext(request.context),
+        );
+      } catch (error) {
+        if (error instanceof HTTPSubjectResolutionError) {
+          return create(ResolveHTTPSubjectResponseSchema, {
+            rejectStatus: error.status,
+            rejectMessage: error.message,
+          });
+        }
+        throw new ConnectError(
+          `resolve http subject: ${errorMessage(error)}`,
+          Code.Unknown,
+        );
+      }
+      return create(ResolveHTTPSubjectResponseSchema, subject
+        ? {
+            subject: {
+              id: subject.id,
+              kind: subject.kind,
+              displayName: subject.displayName,
+              authSource: subject.authSource,
+            },
+          }
+        : {});
+    },
     async getSessionCatalog(request: GetSessionCatalogRequest) {
       let catalog: Catalog | Record<string, unknown> | null | undefined;
       try {
@@ -752,6 +790,48 @@ function providerRequest(
   };
 }
 
+function providerHTTPSubjectRequest(
+  request?: ProtoHTTPSubjectRequest,
+): HTTPSubjectRequest {
+  return {
+    binding: request?.binding ?? "",
+    method: request?.method ?? "",
+    path: request?.path ?? "",
+    contentType: request?.contentType ?? "",
+    headers: providerStringLists(request?.headers),
+    query: providerStringLists(request?.query),
+    params: objectFromUnknown(request?.params),
+    rawBody: new Uint8Array(request?.rawBody ?? new Uint8Array()),
+    securityScheme: request?.securityScheme ?? "",
+    verifiedSubject: request?.verifiedSubject ?? "",
+    verifiedClaims: {
+      ...(request?.verifiedClaims ?? {}),
+    },
+  };
+}
+
+function providerHTTPSubjectResolutionContext(
+  requestContext?: ProtoRequestContext,
+): HTTPSubjectResolutionContext {
+  const request = providerRequest("", {}, requestContext);
+  return {
+    subject: request.subject,
+    credential: request.credential,
+    access: request.access,
+    workflow: request.workflow,
+  };
+}
+
+function providerStringLists(
+  input: Record<string, { values?: string[] }> | undefined,
+): Record<string, string[]> {
+  const output: Record<string, string[]> = {};
+  for (const [key, value] of Object.entries(input ?? {})) {
+    output[key] = [...(value.values ?? [])];
+  }
+  return output;
+}
+
 function providerRuntimeEntry(
   kind: ProviderKind,
 ): ProviderRuntimeEntry {

package/src/s3.ts

@@ -1,5 +1,3 @@
-import { connect } from "node:net";
-
 import { create } from "@bufbuild/protobuf";
 import { EmptySchema } from "@bufbuild/protobuf/wkt";
 import {
@@ -503,9 +501,9 @@ export class S3 {
       throw new Error(`${envName} is not set`);
     }
     const transport = createGrpcTransport({
-      baseUrl: "http://localhost",
+      baseUrl: unixSocketBaseUrl(socketPath),
       nodeOptions: {
-        createConnection: () => connect(socketPath),
+        path: socketPath,
       },
     });
     this.client = createClient(S3Service, transport);
@@ -740,6 +738,15 @@ export class S3Object {
   }
 }
 
+function unixSocketBaseUrl(socketPath: string): string {
+  let hash = 0x811c9dc5;
+  for (const char of socketPath) {
+    hash ^= char.charCodeAt(0);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return `http://unix-${(hash >>> 0).toString(16)}.local`;
+}
+
 async function invokeS3Provider<T>(label: string, fn: () => Promise<T>): Promise<T> {
   try {
     return await fn();