@valon-technologies/gestalt 0.0.1-alpha.10 → 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,
@@ -53,6 +76,21 @@ export {
   type CatalogParameter,
   type CatalogSchema,
 } from "./catalog.ts";
+export {
+  hasPluginManifestMetadata,
+  manifestMetadataToYaml,
+  writeManifestMetadataYaml,
+  type HTTPAck,
+  type HTTPAuthScheme,
+  type HTTPBinding,
+  type HTTPIn,
+  type HTTPMediaType,
+  type HTTPRequestBody,
+  type HTTPSecretRef,
+  type HTTPSecurityScheme,
+  type HTTPSecuritySchemeType,
+  type PluginManifestMetadata,
+} from "./manifest-metadata.ts";
 export {
   buildProviderBinary,
   bunBuildCommand,
@@ -61,18 +99,30 @@ 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_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 {
@@ -90,8 +140,11 @@ export {
   Cache,
   CacheProvider,
   cacheSocketEnv,
+  cacheSocketTokenEnv,
   defineCacheProvider,
   isCacheProvider,
+  ENV_CACHE_SOCKET,
+  ENV_CACHE_SOCKET_TOKEN,
   type CacheEntry,
   type CacheProviderOptions,
   type CacheSetOptions,
@@ -146,6 +199,7 @@ export {
   ENV_PROVIDER_PARENT_PID,
   ENV_PROVIDER_SOCKET,
   ENV_WRITE_CATALOG,
+  ENV_WRITE_MANIFEST_METADATA,
   createAuthenticationService,
   createCacheService,
   createSecretsService,
@@ -182,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;
@@ -16,7 +16,13 @@ export interface PluginInvokeOptions {
 
 export interface PluginInvocationGrant {
   plugin: string;
-  operations: string[];
+  operations?: string[];
+  surfaces?: string[];
+  allOperations?: boolean;
+}
+
+export interface PluginGraphQLInvokeOptions extends PluginInvokeOptions {
+  variables?: Record<string, unknown>;
 }
 
 export class PluginInvoker {
@@ -32,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);
   }
@@ -62,6 +67,32 @@ export class PluginInvoker {
     };
   }
 
+  async invokeGraphQL(
+    plugin: string,
+    document: string,
+    options?: PluginGraphQLInvokeOptions,
+  ): Promise<OperationResult> {
+    const trimmedDocument = document.trim();
+    if (!trimmedDocument) {
+      throw new Error("plugin invoker: graphql document is required");
+    }
+
+    const response = await this.client.invokeGraphQL({
+      invocationToken: this.invocationToken,
+      plugin,
+      document: trimmedDocument,
+      ...(options?.variables
+        ? { variables: toJsonObject(options.variables) }
+        : {}),
+      connection: options?.connection ?? "",
+      instance: options?.instance ?? "",
+    });
+    return {
+      status: response.status,
+      body: response.body,
+    };
+  }
+
   async exchangeInvocationToken(options?: {
     grants?: PluginInvocationGrant[];
     ttlSeconds?: number;
@@ -71,9 +102,13 @@ export class PluginInvoker {
       grants: (options?.grants ?? [])
         .map((grant) => ({
           plugin: grant.plugin.trim(),
-          operations: grant.operations
+          operations: (grant.operations ?? [])
             .map((operation) => operation.trim())
             .filter(Boolean),
+          surfaces: (grant.surfaces ?? [])
+            .map((surface) => surface.trim().toLowerCase())
+            .filter(Boolean),
+          allOperations: grant.allOperations ?? false,
         }))
         .filter((grant) => grant.plugin.length > 0),
       ttlSeconds: BigInt(Math.max(0, options?.ttlSeconds ?? 0)),
@@ -82,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

@@ -0,0 +1,106 @@
+import { writeFileSync } from "node:fs";
+
+import YAML from "yaml";
+
+export type HTTPSecuritySchemeType =
+  | "hmac"
+  | "apiKey"
+  | "http"
+  | "none";
+
+export type HTTPIn = "header" | "query";
+
+export type HTTPAuthScheme = "basic" | "bearer";
+
+export interface HTTPSecretRef {
+  env?: string;
+  secret?: string;
+}
+
+export interface HTTPSecurityScheme {
+  type?: HTTPSecuritySchemeType;
+  description?: string;
+  signatureHeader?: string;
+  signaturePrefix?: string;
+  payloadTemplate?: string;
+  timestampHeader?: string;
+  maxAgeSeconds?: number;
+  name?: string;
+  in?: HTTPIn;
+  scheme?: HTTPAuthScheme;
+  secret?: HTTPSecretRef;
+}
+
+export interface HTTPMediaType {}
+
+export interface HTTPRequestBody {
+  required?: boolean;
+  content?: Record<string, HTTPMediaType>;
+}
+
+export interface HTTPAck {
+  status?: number;
+  headers?: Record<string, string>;
+  body?: any;
+}
+
+export interface HTTPBinding {
+  path: string;
+  method: string;
+  requestBody?: HTTPRequestBody;
+  security: string;
+  target: string;
+  ack?: HTTPAck;
+}
+
+export interface PluginManifestMetadata {
+  securitySchemes?: Record<string, HTTPSecurityScheme>;
+  http?: Record<string, HTTPBinding>;
+}
+
+export function hasPluginManifestMetadata(
+  metadata: PluginManifestMetadata | null | undefined,
+): boolean {
+  return !!(
+    metadata &&
+    ((metadata.securitySchemes &&
+      Object.keys(metadata.securitySchemes).length > 0) ||
+      (metadata.http && Object.keys(metadata.http).length > 0))
+  );
+}
+
+export function manifestMetadataToYaml(
+  metadata: PluginManifestMetadata | Record<string, unknown>,
+): string {
+  return YAML.stringify(toManifestMetadataJsonObject(metadata));
+}
+
+export function writeManifestMetadataYaml(
+  path: string,
+  metadata: PluginManifestMetadata | Record<string, unknown>,
+): void {
+  writeFileSync(path, manifestMetadataToYaml(metadata), "utf8");
+}
+
+function toManifestMetadataJsonObject(
+  metadata: PluginManifestMetadata | Record<string, unknown>,
+): Record<string, unknown> {
+  if (!("securitySchemes" in metadata) && !("http" in metadata)) {
+    return {
+      ...metadata,
+    };
+  }
+
+  const typedMetadata = metadata as PluginManifestMetadata;
+  const output: Record<string, unknown> = {};
+  if (
+    typedMetadata.securitySchemes &&
+    Object.keys(typedMetadata.securitySchemes).length > 0
+  ) {
+    output.securitySchemes = typedMetadata.securitySchemes;
+  }
+  if (typedMetadata.http && Object.keys(typedMetadata.http).length > 0) {
+    output.http = typedMetadata.http;
+  }
+  return output;
+}