feat: enhance secret management in SDK

- Introduced `SecretRef` class to represent stored secrets without their values. - Updated `SecretStore` to manage `SecretRef` instances, allowing for better handling of secret resolution and status checks. - Added `resolve` and `status` methods to `SecretStore` for retrieving secret values and checking their availability. - Refactored in-memory secret store to support the new structure and added a default in-memory secret provider. - Updated OpenAPI plugin to resolve secret-backed headers during invocation, improving security handling in API requests. - Enhanced tests to cover new secret management features and ensure proper resolution of secrets in headers. All changes are aimed at improving the flexibility and security of secret handling within the SDK.

Rhys Sullivan committed 7 months ago

Commit 8d3cddf1 parent 673821a11 files · +441 −87Browse files

Showing the changes to packages/plugins/openapi/src (4 of 11 files). Show all

Unified · Split

4 files

packages/plugins/openapi/src/invoke.ts +68 −19
packages/plugins/openapi/src/plugin.test.ts +96 −1
packages/plugins/openapi/src/plugin.ts +11 −3
packages/plugins/openapi/src/types.ts +15 −2

packages/plugins/openapi/src/invoke.ts+68−19

   type ToolInvoker,
   ToolInvocationResult,
   ToolInvocationError,
+  type ScopeId,
+  type SecretId,
 } from "@executor/sdk";
 import { OpenApiInvocationError } from "./errors";
 import type { OpenApiOperationStore } from "./operation-store";
 import {
+  type HeaderValue,
   type OperationBinding,
   InvocationConfig,
   InvocationResult,
 });
 // ---------------------------------------------------------------------------
-// Header application
+// Header resolution — resolves secret refs at invocation time
 // ---------------------------------------------------------------------------
+const resolveHeaders = (
+  headers: Record<string, HeaderValue>,
+  secrets: { readonly resolve: (secretId: SecretId, scopeId: ScopeId) => Effect.Effect<string, unknown> },
+  scopeId: ScopeId,
+): Effect.Effect<Record<string, string>, ToolInvocationError> =>
+  Effect.gen(function* () {
+    const resolved: Record<string, string> = {};
+    for (const [name, value] of Object.entries(headers)) {
+      if (typeof value === "string") {
+        resolved[name] = value;
+      } else {
+        const secret = yield* secrets.resolve(value.secretId as SecretId, scopeId).pipe(
+          Effect.mapError(() =>
+            new ToolInvocationError({
+              toolId: "" as ToolId,
+              message: `Failed to resolve secret "${value.secretId}" for header "${name}"`,
+              cause: undefined,
+            }),
+          ),
+        );
+        resolved[name] = value.prefix ? `${value.prefix}${secret}` : secret;
+      }
+    }
+    return resolved;
+  });
 const applyHeaders = (
   request: HttpClientRequest.HttpClientRequest,
   headers: Record<string, string>,
   operation: OperationBinding,
   args: Record<string, unknown>,
   config: InvocationConfig,
+  /** Pre-resolved headers (secrets already resolved) */
+  resolvedHeaders?: Record<string, string>,
 ) {
   const client = yield* HttpClient.HttpClient;
     }
   }
-  // Static headers (auth, custom headers, etc.)
+  // Static headers (auth, custom headers, etc.) — use pre-resolved if available
-  request = applyHeaders(request, config.headers);
+  request = applyHeaders(request, resolvedHeaders ?? {});
   // Execute
   const response = yield* client.execute(request).pipe(
 // ToolInvoker — bridges operation store + HTTP client into SDK invoker
 // ---------------------------------------------------------------------------
-export const makeOpenApiInvoker = (
+export const makeOpenApiInvoker = (opts: {
-  operationStore: OpenApiOperationStore,
+  readonly operationStore: OpenApiOperationStore;
-  httpClientLayer: Layer.Layer<HttpClient.HttpClient>,
+  readonly httpClientLayer: Layer.Layer<HttpClient.HttpClient>;
-): ToolInvoker => ({
+  readonly secrets: { readonly resolve: (secretId: SecretId, scopeId: ScopeId) => Effect.Effect<string, unknown> };
+  readonly scopeId: ScopeId;
+}): ToolInvoker => ({
   invoke: (toolId: ToolId, args: unknown, _options) =>
     Effect.gen(function* () {
-      const entry = yield* operationStore.get(toolId);
+      const entry = yield* opts.operationStore.get(toolId);
       if (!entry) {
         return yield* new ToolInvocationError({
           toolId,
       const { binding, config } = entry;
       const baseUrl = config.baseUrl;
+      // Resolve secret-backed headers
+      const resolvedHeaders = yield* resolveHeaders(
+        config.headers,
+        opts.secrets,
+        opts.scopeId,
+      );
       const clientWithBaseUrl = baseUrl
         ? Layer.effect(
             HttpClient.HttpClient,
                 HttpClientRequest.prependUrl(baseUrl),
               ),
             ),
-          ).pipe(Layer.provide(httpClientLayer))
+          ).pipe(Layer.provide(opts.httpClientLayer))
-        : httpClientLayer;
+        : opts.httpClientLayer;
       const result = yield* invoke(
         binding,
         (args ?? {}) as Record<string, unknown>,
         config,
+        resolvedHeaders,
       ).pipe(Effect.provide(clientWithBaseUrl));
       return new ToolInvocationResult({
         status: result.status,
       });
     }).pipe(
-      Effect.mapError((err) =>
+      Effect.catchAll((err) => {
-        err._tag === "ToolInvocationError"
+        if (
-          ? err
+          typeof err === "object" &&
-          : new ToolInvocationError({
+          err !== null &&
-              toolId,
+          "_tag" in err &&
-              message: `OpenAPI invocation failed: ${err.message}`,
+          (err as { _tag: string })._tag === "ToolInvocationError"
-              cause: err,
+        ) {
-            }),
+          return Effect.fail(err as ToolInvocationError);
-      ),
+        }
+        return Effect.fail(
+          new ToolInvocationError({
+            toolId,
+            message: `OpenAPI invocation failed: ${err instanceof Error ? err.message : String(err)}`,
+            cause: err,
+          }),
+        );
+      }),
     ),
 });

packages/plugins/openapi/src/plugin.test.ts+96−1

@@ -6,11 +6,12 @@ import { · 5 unmodified lines
6	HttpApiEndpoint,	6	HttpApiEndpoint,
7	HttpApiGroup,	7	HttpApiGroup,
8	HttpClient,	8	HttpClient,
		9	HttpServerRequest,
9	OpenApi,	10	OpenApi,
10	} from "@effect/platform";	11	} from "@effect/platform";
11	import { NodeHttpServer } from "@effect/platform-node";	12	import { NodeHttpServer } from "@effect/platform-node";
12		13
13	import { createExecutor, makeTestConfig } from "@executor/sdk";	14	import { createExecutor, makeTestConfig, SecretId } from "@executor/sdk";
14	import { openApiPlugin } from "./plugin";	15	import { openApiPlugin } from "./plugin";
15		16
16	// ---------------------------------------------------------------------------	17	// ---------------------------------------------------------------------------
@@ -22,6 +23,11 @@ class Item extends Schema.Class<Item>("Item")({ · 5 unmodified lines
22	name: Schema.String,	23	name: Schema.String,
23	}) {}	24	}) {}
24		25
		26	class EchoHeaders extends Schema.Class<EchoHeaders>("EchoHeaders")({
		27	authorization: Schema.optional(Schema.String),
		28	"x-static": Schema.optional(Schema.String),
		29	}) {}
		30
25	const ItemsGroup = HttpApiGroup.make("items")	31	const ItemsGroup = HttpApiGroup.make("items")
26	.add(	32	.add(
27	HttpApiEndpoint.get("listItems", "/items").addSuccess(Schema.Array(Item)),	33	HttpApiEndpoint.get("listItems", "/items").addSuccess(Schema.Array(Item)),
@@ -30,6 +36,9 @@ const ItemsGroup = HttpApiGroup.make("items") · 2 unmodified lines
30	HttpApiEndpoint.get("getItem", "/items/:itemId")	36	HttpApiEndpoint.get("getItem", "/items/:itemId")
31	.setPath(Schema.Struct({ itemId: Schema.NumberFromString }))	37	.setPath(Schema.Struct({ itemId: Schema.NumberFromString }))
32	.addSuccess(Item),	38	.addSuccess(Item),
		39	)
		40	.add(
		41	HttpApiEndpoint.get("echoHeaders", "/echo-headers").addSuccess(EchoHeaders),
33	);	42	);
34		43
35	const TestApi = HttpApi.make("testApi").add(ItemsGroup);	44	const TestApi = HttpApi.make("testApi").add(ItemsGroup);
@@ -57,6 +66,15 @@ const ItemsGroupLive = HttpApiBuilder.group(TestApi, "items", (handlers) => · 21 unmodified lines
57	name: "Unknown",	66	name: "Unknown",
58	},	67	},
59	),	68	),
		69	)
		70	.handle("echoHeaders", () =>
		71	Effect.gen(function* () {
		72	const req = yield* HttpServerRequest.HttpServerRequest;
		73	return new EchoHeaders({
		74	authorization: req.headers["authorization"],
		75	"x-static": req.headers["x-static"],
		76	});
		77	}),
60	),	78	),
61	);	79	);
62		80
@@ -98,6 +116,83 @@ layer(TestLayer)("OpenAPI Plugin", (it) => { · 35 unmodified lines
98	}),	116	}),
99	);	117	);
100		118
		119	it.effect("resolves secret-backed headers at invocation time", () =>
		120	Effect.gen(function* () {
		121	const httpClient = yield* HttpClient.HttpClient;
		122	const clientLayer = Layer.succeed(HttpClient.HttpClient, httpClient);
		123
		124	const executor = yield* createExecutor(
		125	makeTestConfig({
		126	plugins: [
		127	openApiPlugin({ httpClientLayer: clientLayer }),
		128	] as const,
		129	}),
		130	);
		131
		132	// Store a secret
		133	yield* executor.secrets.set({
		134	id: SecretId.make("test-api-token"),
		135	name: "Test API Token",
		136	value: "secret-value-123",
		137	});
		138
		139	// Add spec with secret-backed header
		140	yield* executor.openapi.addSpec({
		141	spec: specJson,
		142	namespace: "authed",
		143	baseUrl: "",
		144	headers: {
		145	"Authorization": { secretId: "test-api-token", prefix: "Bearer " },
		146	"X-Static": "hello",
		147	},
		148	});
		149
		150	// Invoke the echo endpoint — verifies secret was resolved and sent
		151	const result = yield* executor.tools.invoke(
		152	"authed.items.echoHeaders",
		153	{},
		154	);
		155
		156	expect(result.error).toBeNull();
		157	const data = result.data as { authorization?: string; "x-static"?: string };
		158	expect(data.authorization).toBe("Bearer secret-value-123");
		159	expect(data["x-static"]).toBe("hello");
		160	}),
		161	);
		162
		163	it.effect("fails clearly when a secret is missing", () =>
		164	Effect.gen(function* () {
		165	const httpClient = yield* HttpClient.HttpClient;
		166	const clientLayer = Layer.succeed(HttpClient.HttpClient, httpClient);
		167
		168	const executor = yield* createExecutor(
		169	makeTestConfig({
		170	plugins: [
		171	openApiPlugin({ httpClientLayer: clientLayer }),
		172	] as const,
		173	}),
		174	);
		175
		176	// Add spec with secret-backed header but DON'T store the secret
		177	yield* executor.openapi.addSpec({
		178	spec: specJson,
		179	namespace: "noauth",
		180	baseUrl: "",
		181	headers: {
		182	"Authorization": { secretId: "missing-token", prefix: "Bearer " },
		183	},
		184	});
		185
		186	// Invoke — should fail with a clear error about the missing secret
		187	const error = yield* Effect.flip(
		188	executor.tools.invoke("noauth.items.listItems", {}),
		189	);
		190
		191	expect(error._tag).toBe("ToolInvocationError");
		192	expect((error as { message: string }).message).toContain("missing-token");
		193	}),
		194	);
		195
101	it.effect("registers tools from an OpenAPI spec", () =>	196	it.effect("registers tools from an OpenAPI spec", () =>
102	Effect.gen(function* () {	197	Effect.gen(function* () {
103	const httpClient = yield* HttpClient.HttpClient;	198	const httpClient = yield* HttpClient.HttpClient;

packages/plugins/openapi/src/plugin.ts+11−3

 // Plugin config
 // ---------------------------------------------------------------------------
+/** A header value — either a static string or a reference to a secret */
+export type HeaderValue = string | { readonly secretId: string; readonly prefix?: string };
 export interface OpenApiSpecConfig {
   readonly spec: string;
   readonly baseUrl?: string;
   readonly namespace?: string;
-  /** Static headers applied to every request for this spec */
+  /** Headers applied to every request. Values can reference secrets. */
-  readonly headers?: Record<string, string>;
+  readonly headers?: Record<string, HeaderValue>;
 }
 // ---------------------------------------------------------------------------
       Effect.gen(function* () {
         yield* ctx.tools.registerInvoker(
           "openapi",
-          makeOpenApiInvoker(operationStore, httpClientLayer),
+          makeOpenApiInvoker({
+            operationStore,
+            httpClientLayer,
+            secrets: ctx.secrets,
+            scopeId: ctx.scope.id,
+          }),
         );
         return {

packages/plugins/openapi/src/types.ts+15−2

 // Invocation
 // ---------------------------------------------------------------------------
+/**
+ * A header value — either a static string or a reference to a secret.
+ * Stored as JSON-serializable data.
+ */
+export const HeaderValue = Schema.Union(
+  Schema.String,
+  Schema.Struct({
+    secretId: Schema.String,
+    prefix: Schema.optional(Schema.String),
+  }),
+);
+export type HeaderValue = typeof HeaderValue.Type;
 export class InvocationConfig extends Schema.Class<InvocationConfig>(
   "InvocationConfig",
 )({
   baseUrl: Schema.String,
-  /** Static headers applied to every request (auth, custom headers, etc.) */
+  /** Headers applied to every request. Values can reference secrets. */
   headers: Schema.optionalWith(
-    Schema.Record({ key: Schema.String, value: Schema.String }),
+    Schema.Record({ key: Schema.String, value: HeaderValue }),
     { default: () => ({}) },
   ),
 }) {}

feat: enhance secret management in SDK

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code