feat(sdk): add provider-neutral authorization seam

.changeset/provider-neutral-authorization.md

@@ -0,0 +1,5 @@
+---
+"executor": patch
+---
+
+Add an optional provider-neutral authorization seam for tool execution. Hosts can supply an `AuthorizationProvider` that receives Executor-bound tenant/subject identity and resolved tool metadata before credentials or plugin invocation; deny and provider failures fail closed, approval reuses the existing elicitation path, and nested tool execution re-enters the same authorization check. Existing hosts that do not configure a provider retain current behavior.

packages/core/api/src/server/scoped-executor.authorization.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Layer, Schema } from "effect";
+
+import {
+  collectTables,
+  definePlugin,
+  tool,
+  ToolAddress,
+  type AuthorizationProvider,
+  type AuthorizationRequest,
+} from "@executor-js/sdk";
+import { createSqliteTestFumaDb } from "@executor-js/sdk/testing";
+
+import { DbProvider } from "./executor-fuma-db";
+import { HostConfig, makeScopedExecutor, PluginsProvider } from "./scoped-executor";
+
+describe("scoped executor authorization composition", () => {
+  it.effect("threads HostConfig authorizationProvider into the real scoped executor", () =>
+    Effect.acquireUseRelease(
+      Effect.promise(() => createSqliteTestFumaDb({ tables: collectTables() })),
+      (db) =>
+        Effect.gen(function* () {
+          const seen: AuthorizationRequest[] = [];
+          const provider: AuthorizationProvider = {
+            authorize: (request) =>
+              Effect.sync(() => {
+                seen.push(request);
+                return {
+                  outcome: "allow" as const,
+                  decisionId: "host-composition-allow",
+                  policyRevision: "host-composition-v1",
+                  reason: "test",
+                };
+              }),
+          };
+          const plugin = definePlugin(() => ({
+            id: "host-authz-fixture" as const,
+            storage: () => ({}),
+            staticIntegrations: () => [
+              {
+                id: "host-authz-fixture.control",
+                kind: "control" as const,
+                name: "Host authz fixture",
+                tools: [
+                  tool({
+                    name: "ping",
+                    description: "ping",
+                    inputSchema: Schema.toStandardSchemaV1(
+                      Schema.toStandardJSONSchemaV1(Schema.Struct({})),
+                    ),
+                    execute: () => Effect.succeed("pong"),
+                  }),
+                ],
+              },
+            ],
+          }))();
+
+          const seams = Layer.mergeAll(
+            Layer.succeed(DbProvider)(db),
+            Layer.succeed(PluginsProvider)({ plugins: () => [plugin] }),
+            Layer.succeed(HostConfig)({
+              allowLocalNetwork: false,
+              oauthCallbackPath: "/api/oauth/callback",
+              authorizationProvider: provider,
+            }),
+          );
+          const executor = yield* makeScopedExecutor("subject-1", "tenant-1", "Tenant One").pipe(
+            Effect.provide(seams),
+          );
+
+          const result = yield* executor
+            .execute(ToolAddress.make("host-authz-fixture.control.ping"), {})
+            .pipe(Effect.ensuring(executor.close().pipe(Effect.ignore)));
+          expect(result).toBe("pong");
+          expect(seen).toHaveLength(1);
+          expect(String(seen[0]!.identity.tenant)).toBe("tenant-1");
+          expect(String(seen[0]!.identity.subject)).toBe("subject-1");
+          expect(seen[0]!.operation).toBe("tool.execute");
+          expect(seen[0]!.tool.address).toBe("host-authz-fixture.control.ping");
+        }),
+      (db) => Effect.promise(() => db.close()),
+    ),
+  );
+});

packages/core/api/src/server/scoped-executor.ts

@@ -6,7 +6,8 @@
 // hosted HTTP client, build the `[userOrgScope, orgScope]` scope stack (P1), and
 // call `createExecutor({...})` with a byte-identical option shape. The ONLY real
 // differences were the DB source/lifetime, the plugin instances, and two host
-// config scalars (`allowLocalNetwork`, `webBaseUrl`).
+// config values (`allowLocalNetwork`, `webBaseUrl`, and optional horizontal
+// authorization provider).
 //
 // `makeScopedExecutor` owns that common body. The per-host knobs are injected
 // through three Effect seams:
@@ -17,8 +18,9 @@
 //     so both lifetimes are preserved by the Layer the host supplies.
 //   - `PluginsProvider` — the plugin array. Cloud injects per-request WorkOS
 //     credentials; self-host returns the plain plugin list.
-//   - `HostConfig` — `allowLocalNetwork` (drives the hosted HTTP client guard)
-//     and `webBaseUrl` (the core-tools elicitation base URL).
+//   - `HostConfig` — `allowLocalNetwork` (drives the hosted HTTP client guard),
+//     `webBaseUrl` (the core-tools elicitation base URL), and an optional
+//     provider-neutral authorization provider threaded to `createExecutor`.
 //
 // This is host-composition machinery: it lives in `@executor-js/api/server`
 // (the host surface), not in `@executor-js/sdk` (the plugin-author contract).
@@ -52,7 +54,7 @@ import {
 import { DbProvider } from "./executor-fuma-db";
 
 // ---------------------------------------------------------------------------
-// HostConfig seam — the two host scalars that vary the `createExecutor` options.
+// HostConfig seam — host values that vary the `createExecutor` options.
 // ---------------------------------------------------------------------------
 
 export interface HostConfigShape {
@@ -97,6 +99,12 @@ export interface HostConfigShape {
    * Hosts that record product analytics supply it; omitted -> no observation.
    */
   readonly onIntegrationChange?: ExecutorConfig["onIntegrationChange"];
+  /**
+   * Optional horizontal authorization PEP provider. The shared host layer only
+   * threads this provider-neutral seam into `createExecutor`; concrete PDP
+   * adapters belong to the host/product composition, not @executor-js/api.
+   */
+  readonly authorizationProvider?: ExecutorConfig["authorizationProvider"];
 }
 
 export class HostConfig extends Context.Service<HostConfig, HostConfigShape>()(
@@ -284,6 +292,7 @@ export const makeScopedExecutor = <
       httpClientLayer,
       fetch: hostedFetch,
       onIntegrationChange: config.onIntegrationChange,
+      authorizationProvider: config.authorizationProvider,
       onElicitation: "accept-all",
       redirectUri,
       oauthCallbackStateOrgSlug: orgSlug,