@opengeni/core 2.10.0-canary.0 → 2.10.0-canary.2

package/dist/remote-mcp-credentials.d.ts

@@ -1,8 +1,23 @@
 import type { Settings } from "@opengeni/config";
+import { type Database, type HostMcpResolverRoute } from "@opengeni/db";
 import { type ConnectionCredentialsPort } from "@opengeni/contracts";
 import { pinnedFetch } from "@opengeni/network";
 /** Optional standalone transport for the existing request-time host port.
  * No successful credential is cached or persisted. The host must authorize
  * every immutable request context, including revocation and binding generation.
  */
-export declare function createRemoteMcpCredentialsPort(settings: Pick<Settings, "hostMcpCredentialResolversJson" | "environment" | "integrationsAllowPrivateNetworkTargets">, transport?: typeof pinnedFetch): ConnectionCredentialsPort;
+export declare function createRemoteMcpCredentialsPort(settings: Pick<Settings, "hostMcpCredentialResolversJson" | "environment" | "integrationsAllowPrivateNetworkTargets">, transport?: typeof pinnedFetch, routes?: {
+    resolve: (input: {
+        accountId: string;
+        workspaceId: string;
+    }) => Promise<HostMcpResolverRoute>;
+    isCurrent: (input: {
+        accountId: string;
+        workspaceId: string;
+    }, route: HostMcpResolverRoute) => Promise<boolean>;
+}): ConnectionCredentialsPort;
+/** Native standalone transport; the database remains authoritative on every
+ * resolution/use. Embedded in-process ports retain their existing precedence. */
+export declare function createNativeRemoteMcpCredentialsPort(settings: Settings, db: Database, transport?: typeof pinnedFetch): ConnectionCredentialsPort;
+/** Parses only server configuration; never return parser errors containing secrets. */
+export declare function hasLegacyHostMcpResolver(settings: Pick<Settings, "hostMcpCredentialResolversJson">, accountId: string): boolean;

package/dist/remote-mcp-credentials.js

@@ -1,219 +1,11 @@
-// src/remote-mcp-credentials.ts
 import {
-  McpConnectionResourceScope
-} from "@opengeni/contracts";
-import { pinnedFetch, readResponseJsonBounded, validateHttpUrl } from "@opengeni/network";
-import { z } from "zod";
-var configuration = z.array(
-  z.object({
-    accountId: z.string().uuid(),
-    url: z.string().max(2048),
-    bearerToken: z.string().min(1).max(8192).regex(/^[^\r\n]+$/),
-    timeoutMs: z.number().int().min(100).max(3e4).default(1e4)
-  }).strict()
-).max(128);
-var scope = {
-  accountId: z.string(),
-  workspaceId: z.string(),
-  sessionId: z.string(),
-  providerDomain: z.string(),
-  provider: z.string().optional(),
-  scopes: z.array(z.string()).max(256).optional(),
-  resource: z.string().optional(),
-  selectedResources: z.array(McpConnectionResourceScope).max(256).optional()
-};
-var resolution = z.discriminatedUnion("status", [
-  z.object({
-    ...scope,
-    status: z.literal("ok"),
-    connectionId: z.string().min(1),
-    headers: z.record(z.string(), z.string()),
-    placements: z.array(
-      z.object({
-        carrier: z.enum(["header", "query", "cookie"]),
-        name: z.string(),
-        value: z.string(),
-        prefix: z.string().optional()
-      }).strict()
-    ).max(64).optional(),
-    expiresAt: z.string().datetime({ offset: true })
-  }).strict(),
-  z.object({
-    ...scope,
-    status: z.literal("auth_needed"),
-    connectionId: z.string().optional(),
-    reason: z.enum([
-      "missing_connection",
-      "expired",
-      "insufficient_scope",
-      "refresh_failed",
-      "personal_authority_unavailable",
-      "unsupported_auth",
-      "resource_scope_unavailable"
-    ]),
-    authorizationUrl: z.string().optional()
-  }).strict()
-]);
-var gatewayResolution = z.discriminatedUnion("status", [
-  resolution.options[0].omit({ sessionId: true }).extend({ requestId: z.string().uuid() }),
-  resolution.options[1].omit({ sessionId: true }).extend({ requestId: z.string().uuid() })
-]);
-var responseEnvelope = z.object({
-  version: z.literal(1),
-  requestId: z.string().uuid(),
-  destinationUrl: z.string(),
-  resolution: z.union([resolution, gatewayResolution])
-}).strict();
-function normalizeResolution(value) {
-  const common = {
-    accountId: value.accountId,
-    workspaceId: value.workspaceId,
-    ..."sessionId" in value ? { sessionId: value.sessionId } : { requestId: value.requestId },
-    providerDomain: value.providerDomain,
-    ...value.provider !== void 0 ? { provider: value.provider } : {},
-    ...value.scopes !== void 0 ? { scopes: value.scopes } : {},
-    ...value.resource !== void 0 ? { resource: value.resource } : {},
-    ...value.selectedResources !== void 0 ? { selectedResources: value.selectedResources } : {}
-  };
-  if (value.status === "auth_needed")
-    return {
-      ...common,
-      status: "auth_needed",
-      reason: value.reason,
-      ...value.connectionId !== void 0 ? { connectionId: value.connectionId } : {},
-      ...value.authorizationUrl !== void 0 ? { authorizationUrl: value.authorizationUrl } : {}
-    };
-  return {
-    ...common,
-    status: "ok",
-    connectionId: value.connectionId,
-    headers: value.headers,
-    expiresAt: value.expiresAt,
-    ...value.placements !== void 0 ? {
-      placements: value.placements.map((placement) => ({
-        carrier: placement.carrier,
-        name: placement.name,
-        value: placement.value,
-        ...placement.prefix !== void 0 ? { prefix: placement.prefix } : {}
-      }))
-    } : {}
-  };
-}
-function createRemoteMcpCredentialsPort(settings, transport = pinnedFetch) {
-  if (!settings.hostMcpCredentialResolversJson) return {};
-  let entries;
-  try {
-    entries = configuration.parse(JSON.parse(settings.hostMcpCredentialResolversJson));
-    for (const entry of entries) validateHttpUrl(entry.url);
-    if (new Set(entries.map((entry) => entry.accountId)).size !== entries.length) throw new Error();
-  } catch {
-    throw new Error("Invalid host MCP credential resolver configuration");
-  }
-  const byAccount = new Map(entries.map((entry) => [entry.accountId, entry]));
-  const active = /* @__PURE__ */ new Map();
-  let physicalRequests = 0;
-  const resolveRemote = async (input) => {
-    const serialized = JSON.stringify(input);
-    const request = JSON.parse(serialized);
-    const unavailable = (reason) => ({
-      status: "auth_needed",
-      accountId: request.accountId,
-      workspaceId: request.workspaceId,
-      ..."sessionId" in request ? { sessionId: request.sessionId } : { requestId: request.requestId },
-      providerDomain: request.connectionRef.providerDomain,
-      ...request.connectionRef.provider !== void 0 ? { provider: request.connectionRef.provider } : {},
-      ...request.connectionRef.connectionId !== void 0 ? { connectionId: request.connectionRef.connectionId } : {},
-      ...request.connectionRef.scopes !== void 0 ? { scopes: request.connectionRef.scopes } : {},
-      ...request.connectionRef.resource !== void 0 ? { resource: request.connectionRef.resource } : {},
-      ...request.connectionRef.selectedResources !== void 0 ? { selectedResources: request.connectionRef.selectedResources } : {},
-      reason
-    });
-    const config = byAccount.get(request.accountId);
-    if (!config || request.connectionRef.authoritySource !== "host")
-      return unavailable("unsupported_auth");
-    if (new TextEncoder().encode(serialized).byteLength > 65536)
-      return unavailable("refresh_failed");
-    const pending = active.get(serialized);
-    if (pending) return structuredClone(await pending);
-    if (physicalRequests >= 128) return unavailable("refresh_failed");
-    const run = async () => {
-      const requestId = crypto.randomUUID();
-      const controller = new AbortController();
-      let timer;
-      const deadline = new Promise((_, reject) => {
-        timer = setTimeout(() => {
-          controller.abort();
-          reject(new Error("Host resolver deadline"));
-        }, config.timeoutMs);
-      });
-      try {
-        physicalRequests++;
-        return await Promise.race([
-          deadline,
-          (async () => {
-            const response = await transport(
-              config.url,
-              {
-                method: "POST",
-                redirect: "manual",
-                signal: controller.signal,
-                headers: {
-                  Authorization: `Bearer ${config.bearerToken}`,
-                  "Content-Type": "application/json"
-                },
-                body: JSON.stringify({ version: 1, requestId, request })
-              },
-              settings,
-              { requireHttpsOutsideLocalTest: true, label: "Host MCP credential resolver" }
-            );
-            if (!response.ok) {
-              await response.body?.cancel();
-              return unavailable("refresh_failed");
-            }
-            const parsed = responseEnvelope.parse(
-              await readResponseJsonBounded(response, 65536, "Host MCP credential resolver", {
-                signal: controller.signal
-              })
-            );
-            if (parsed.requestId !== requestId || parsed.destinationUrl !== request.destinationUrl || parsed.resolution.accountId !== request.accountId || parsed.resolution.workspaceId !== request.workspaceId || ("sessionId" in request ? !("sessionId" in parsed.resolution) || parsed.resolution.sessionId !== request.sessionId : !("requestId" in parsed.resolution) || parsed.resolution.requestId !== request.requestId))
-              return unavailable("refresh_failed");
-            if (parsed.resolution.status === "ok" && (Date.parse(parsed.resolution.expiresAt) <= Date.now() + 5e3 || Date.parse(parsed.resolution.expiresAt) > Date.now() + 9e5)) {
-              return unavailable("refresh_failed");
-            }
-            return normalizeResolution(parsed.resolution);
-          })().finally(() => {
-            physicalRequests--;
-          })
-        ]);
-      } catch {
-        return unavailable("refresh_failed");
-      } finally {
-        clearTimeout(timer);
-      }
-    };
-    const task = run();
-    active.set(serialized, task);
-    try {
-      return structuredClone(await task);
-    } finally {
-      if (active.get(serialized) === task) active.delete(serialized);
-    }
-  };
-  return {
-    mcpAuthoritySource: "host",
-    async mcpCredentials(input) {
-      const result = await resolveRemote(input);
-      if (!("sessionId" in result)) throw new Error("Invalid host turn credential scope");
-      return result;
-    },
-    async mcpGatewayCredentials(input) {
-      const result = await resolveRemote(input);
-      if (!("requestId" in result)) throw new Error("Invalid host gateway credential scope");
-      return result;
-    }
-  };
-}
+  createNativeRemoteMcpCredentialsPort,
+  createRemoteMcpCredentialsPort,
+  hasLegacyHostMcpResolver
+} from "./chunk-5WZYFL45.js";
 export {
-  createRemoteMcpCredentialsPort
+  createNativeRemoteMcpCredentialsPort,
+  createRemoteMcpCredentialsPort,
+  hasLegacyHostMcpResolver
 };
 //# sourceMappingURL=remote-mcp-credentials.js.map

package/dist/remote-mcp-credentials.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/remote-mcp-credentials.ts"],"sourcesContent":["import type { Settings } from \"@opengeni/config\";\nimport {\n  McpConnectionResourceScope,\n  type ConnectionCredentialsPort,\n  type McpCredentialsRequest,\n  type McpCredentialResolution,\n  type McpGatewayCredentialsRequest,\n  type McpGatewayCredentialResolution,\n} from \"@opengeni/contracts\";\nimport { pinnedFetch, readResponseJsonBounded, validateHttpUrl } from \"@opengeni/network\";\nimport { z } from \"zod\";\n\nconst configuration = z\n  .array(\n    z\n      .object({\n        accountId: z.string().uuid(),\n        url: z.string().max(2048),\n        bearerToken: z\n          .string()\n          .min(1)\n          .max(8192)\n          .regex(/^[^\\r\\n]+$/),\n        timeoutMs: z.number().int().min(100).max(30_000).default(10_000),\n      })\n      .strict(),\n  )\n  .max(128);\n\nconst scope = {\n  accountId: z.string(),\n  workspaceId: z.string(),\n  sessionId: z.string(),\n  providerDomain: z.string(),\n  provider: z.string().optional(),\n  scopes: z.array(z.string()).max(256).optional(),\n  resource: z.string().optional(),\n  selectedResources: z.array(McpConnectionResourceScope).max(256).optional(),\n};\nconst resolution = z.discriminatedUnion(\"status\", [\n  z\n    .object({\n      ...scope,\n      status: z.literal(\"ok\"),\n      connectionId: z.string().min(1),\n      headers: z.record(z.string(), z.string()),\n      placements: z\n        .array(\n          z\n            .object({\n              carrier: z.enum([\"header\", \"query\", \"cookie\"]),\n              name: z.string(),\n              value: z.string(),\n              prefix: z.string().optional(),\n            })\n            .strict(),\n        )\n        .max(64)\n        .optional(),\n      expiresAt: z.string().datetime({ offset: true }),\n    })\n    .strict(),\n  z\n    .object({\n      ...scope,\n      status: z.literal(\"auth_needed\"),\n      connectionId: z.string().optional(),\n      reason: z.enum([\n        \"missing_connection\",\n        \"expired\",\n        \"insufficient_scope\",\n        \"refresh_failed\",\n        \"personal_authority_unavailable\",\n        \"unsupported_auth\",\n        \"resource_scope_unavailable\",\n      ]),\n      authorizationUrl: z.string().optional(),\n    })\n    .strict(),\n]);\nconst gatewayResolution = z.discriminatedUnion(\"status\", [\n  resolution.options[0].omit({ sessionId: true }).extend({ requestId: z.string().uuid() }),\n  resolution.options[1].omit({ sessionId: true }).extend({ requestId: z.string().uuid() }),\n]);\nconst responseEnvelope = z\n  .object({\n    version: z.literal(1),\n    requestId: z.string().uuid(),\n    destinationUrl: z.string(),\n    resolution: z.union([resolution, gatewayResolution]),\n  })\n  .strict();\n\ntype RemoteResolution = McpCredentialResolution | McpGatewayCredentialResolution;\nfunction normalizeResolution(\n  value: z.infer<typeof resolution> | z.infer<typeof gatewayResolution>,\n): RemoteResolution {\n  const common = {\n    accountId: value.accountId,\n    workspaceId: value.workspaceId,\n    ...(\"sessionId\" in value ? { sessionId: value.sessionId } : { requestId: value.requestId }),\n    providerDomain: value.providerDomain,\n    ...(value.provider !== undefined ? { provider: value.provider } : {}),\n    ...(value.scopes !== undefined ? { scopes: value.scopes } : {}),\n    ...(value.resource !== undefined ? { resource: value.resource } : {}),\n    ...(value.selectedResources !== undefined\n      ? { selectedResources: value.selectedResources }\n      : {}),\n  };\n  if (value.status === \"auth_needed\")\n    return {\n      ...common,\n      status: \"auth_needed\",\n      reason: value.reason,\n      ...(value.connectionId !== undefined ? { connectionId: value.connectionId } : {}),\n      ...(value.authorizationUrl !== undefined ? { authorizationUrl: value.authorizationUrl } : {}),\n    };\n  return {\n    ...common,\n    status: \"ok\",\n    connectionId: value.connectionId,\n    headers: value.headers,\n    expiresAt: value.expiresAt,\n    ...(value.placements !== undefined\n      ? {\n          placements: value.placements.map((placement) => ({\n            carrier: placement.carrier,\n            name: placement.name,\n            value: placement.value,\n            ...(placement.prefix !== undefined ? { prefix: placement.prefix } : {}),\n          })),\n        }\n      : {}),\n  };\n}\n\n/** Optional standalone transport for the existing request-time host port.\n * No successful credential is cached or persisted. The host must authorize\n * every immutable request context, including revocation and binding generation.\n */\nexport function createRemoteMcpCredentialsPort(\n  settings: Pick<\n    Settings,\n    \"hostMcpCredentialResolversJson\" | \"environment\" | \"integrationsAllowPrivateNetworkTargets\"\n  >,\n  transport: typeof pinnedFetch = pinnedFetch,\n): ConnectionCredentialsPort {\n  if (!settings.hostMcpCredentialResolversJson) return {};\n  let entries: z.infer<typeof configuration>;\n  try {\n    entries = configuration.parse(JSON.parse(settings.hostMcpCredentialResolversJson));\n    for (const entry of entries) validateHttpUrl(entry.url);\n    if (new Set(entries.map((entry) => entry.accountId)).size !== entries.length) throw new Error();\n  } catch {\n    // Configuration includes credentials: never return parser input or causes.\n    throw new Error(\"Invalid host MCP credential resolver configuration\");\n  }\n  const byAccount = new Map(entries.map((entry) => [entry.accountId, entry]));\n  const active = new Map<string, Promise<RemoteResolution>>();\n  let physicalRequests = 0;\n  const resolveRemote = async (\n    input: McpCredentialsRequest | McpGatewayCredentialsRequest,\n  ): Promise<RemoteResolution> => {\n    const serialized = JSON.stringify(input);\n    const request: McpCredentialsRequest | McpGatewayCredentialsRequest = JSON.parse(serialized);\n    const unavailable = (reason: \"unsupported_auth\" | \"refresh_failed\"): RemoteResolution => ({\n      status: \"auth_needed\",\n      accountId: request.accountId,\n      workspaceId: request.workspaceId,\n      ...(\"sessionId\" in request\n        ? { sessionId: request.sessionId }\n        : { requestId: request.requestId }),\n      providerDomain: request.connectionRef.providerDomain,\n      ...(request.connectionRef.provider !== undefined\n        ? { provider: request.connectionRef.provider }\n        : {}),\n      ...(request.connectionRef.connectionId !== undefined\n        ? { connectionId: request.connectionRef.connectionId }\n        : {}),\n      ...(request.connectionRef.scopes !== undefined\n        ? { scopes: request.connectionRef.scopes }\n        : {}),\n      ...(request.connectionRef.resource !== undefined\n        ? { resource: request.connectionRef.resource }\n        : {}),\n      ...(request.connectionRef.selectedResources !== undefined\n        ? { selectedResources: request.connectionRef.selectedResources }\n        : {}),\n      reason,\n    });\n    const config = byAccount.get(request.accountId);\n    if (!config || request.connectionRef.authoritySource !== \"host\")\n      return unavailable(\"unsupported_auth\");\n    // Snapshot before any asynchronous operation; never retain mutable caller\n    // objects as the authority for a delayed response.\n    if (new TextEncoder().encode(serialized).byteLength > 65_536)\n      return unavailable(\"refresh_failed\");\n    const pending = active.get(serialized);\n    if (pending) return structuredClone(await pending);\n    if (physicalRequests >= 128) return unavailable(\"refresh_failed\");\n    const run = async (): Promise<RemoteResolution> => {\n      const requestId = crypto.randomUUID();\n      const controller = new AbortController();\n      let timer: ReturnType<typeof setTimeout> | undefined;\n      const deadline = new Promise<never>((_, reject) => {\n        timer = setTimeout(() => {\n          controller.abort();\n          reject(new Error(\"Host resolver deadline\"));\n        }, config.timeoutMs);\n      });\n      try {\n        physicalRequests++;\n        return await Promise.race([\n          deadline,\n          (async () => {\n            const response = await transport(\n              config.url,\n              {\n                method: \"POST\",\n                redirect: \"manual\",\n                signal: controller.signal,\n                headers: {\n                  Authorization: `Bearer ${config.bearerToken}`,\n                  \"Content-Type\": \"application/json\",\n                },\n                body: JSON.stringify({ version: 1, requestId, request }),\n              },\n              settings,\n              { requireHttpsOutsideLocalTest: true, label: \"Host MCP credential resolver\" },\n            );\n            if (!response.ok) {\n              await response.body?.cancel();\n              return unavailable(\"refresh_failed\");\n            }\n            const parsed = responseEnvelope.parse(\n              await readResponseJsonBounded(response, 65_536, \"Host MCP credential resolver\", {\n                signal: controller.signal,\n              }),\n            );\n            if (\n              parsed.requestId !== requestId ||\n              parsed.destinationUrl !== request.destinationUrl ||\n              parsed.resolution.accountId !== request.accountId ||\n              parsed.resolution.workspaceId !== request.workspaceId ||\n              (\"sessionId\" in request\n                ? !(\"sessionId\" in parsed.resolution) ||\n                  parsed.resolution.sessionId !== request.sessionId\n                : !(\"requestId\" in parsed.resolution) ||\n                  parsed.resolution.requestId !== request.requestId)\n            )\n              return unavailable(\"refresh_failed\");\n            if (\n              parsed.resolution.status === \"ok\" &&\n              (Date.parse(parsed.resolution.expiresAt) <= Date.now() + 5_000 ||\n                Date.parse(parsed.resolution.expiresAt) > Date.now() + 900_000)\n            ) {\n              return unavailable(\"refresh_failed\");\n            }\n            // Existing buildHostConnectionTokenResolver validates the precise\n            // connection, provider, scopes, resources and credential placements.\n            return normalizeResolution(parsed.resolution);\n          })().finally(() => {\n            physicalRequests--;\n          }),\n        ]);\n      } catch {\n        return unavailable(\"refresh_failed\");\n      } finally {\n        clearTimeout(timer);\n      }\n    };\n    const task = run();\n    active.set(serialized, task);\n    try {\n      return structuredClone(await task);\n    } finally {\n      if (active.get(serialized) === task) active.delete(serialized);\n    }\n  };\n  return {\n    mcpAuthoritySource: \"host\",\n    async mcpCredentials(input) {\n      const result = await resolveRemote(input);\n      if (!(\"sessionId\" in result)) throw new Error(\"Invalid host turn credential scope\");\n      return result;\n    },\n    async mcpGatewayCredentials(input) {\n      const result = await resolveRemote(input);\n      if (!(\"requestId\" in result)) throw new Error(\"Invalid host gateway credential scope\");\n      return result;\n    },\n  };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "2.10.0-canary.0",
+  "version": "2.10.0-canary.2",
   "description": "OpenGeni framework-agnostic core: the domain, access, and billing layers (neutral access, off-HTTP V2 surface). Behavior-preserving extraction from apps/api — keeps Hono's HTTPException for error throwing (typed-errors cleanup deferred).",
   "license": "Apache-2.0",
   "repository": {
@@ -58,17 +58,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/capabilities": "^0.3.3-canary.12",
-    "@opengeni/codex": "^0.2.22-canary.12",
-    "@opengeni/config": "^1.2.0-canary.0",
-    "@opengeni/contracts": "^3.1.0-canary.0",
-    "@opengeni/db": "^4.4.0-canary.0",
-    "@opengeni/documents": "^0.8.28-canary.0",
-    "@opengeni/events": "^0.4.26-canary.0",
-    "@opengeni/network": "^0.3.1-canary.12",
-    "@opengeni/observability": "^0.8.27-canary.0",
-    "@opengeni/runtime": "^2.6.0-canary.0",
-    "@opengeni/storage": "^0.2.128-canary.0",
+    "@opengeni/capabilities": "^0.3.3-canary.14",
+    "@opengeni/codex": "^0.2.22-canary.14",
+    "@opengeni/config": "^1.2.0-canary.2",
+    "@opengeni/contracts": "^3.1.0-canary.2",
+    "@opengeni/db": "^4.4.0-canary.2",
+    "@opengeni/documents": "^0.8.28-canary.2",
+    "@opengeni/events": "^0.4.26-canary.2",
+    "@opengeni/network": "^0.3.1-canary.14",
+    "@opengeni/observability": "^0.8.27-canary.2",
+    "@opengeni/runtime": "^2.6.0-canary.2",
+    "@opengeni/storage": "^0.2.128-canary.2",
     "hono": "^4.12.18",
     "zod": "^4.2.1"
   },

package/src/application/external-workspace-members.ts

@@ -2,6 +2,8 @@ import type { Context } from "hono";
 import { HTTPException } from "hono/http-exception";
 import {
   AddExternalWorkspaceMemberRequest,
+  ExternalIdentityReference,
+  CancelExternalWorkspaceMemberGrantRequest,
   type ExternalIdentity,
 } from "@opengeni/contracts/external-identities";
 import {
@@ -12,7 +14,12 @@ import {
   requireWorkspace,
   setRlsContext,
   withWorkspaceSubjectRls,
+  addExternalWorkspaceMemberOperation,
+  cancelExternalWorkspaceMemberGrant,
+  lookupExternalIdentity,
+  nestedPostgresSqlState,
 } from "@opengeni/db";
+import { organizationMembershipHttpStatus } from "../domain/organization-membership-lifecycle";
 import {
   accountScopedApiKeyWorkspaceAuthority,
   hasPermission,
@@ -43,6 +50,21 @@ export async function addExternalWorkspaceMemberForRequest(
   ) {
     throw new HTTPException(403, { message: "membership exceeds key authority" });
   }
+  if (payload.operationId) {
+    try {
+      return await addExternalWorkspaceMemberOperation(
+        deps.db,
+        {
+          organizationId: authority.accountId,
+          workspaceId,
+          actorSubjectId: grant.subjectId,
+        },
+        { ...payload, operationId: payload.operationId },
+      );
+    } catch (error) {
+      rethrowExternalWorkspaceOperation(error);
+    }
+  }
   return withWorkspaceSubjectRls(deps.db, workspaceId, grant.subjectId, async (tx) => {
     await lockExternalWorkspaceMembershipLifecycle(tx, grant.accountId);
     const live = await requireFreshAccessGrant(
@@ -93,3 +115,70 @@ export async function addExternalWorkspaceMemberForRequest(
     return identity;
   });
 }
+
+function rethrowExternalWorkspaceOperation(error: unknown): never {
+  const status = organizationMembershipHttpStatus(nestedPostgresSqlState(error));
+  if (status)
+    throw new HTTPException(status, {
+      message:
+        status === 409
+          ? "External membership operation changed or was cancelled"
+          : "External membership operation is not available",
+    });
+  throw error;
+}
+
+async function externalService(c: Context, deps: AccessDeps, organizationId: string) {
+  const context = await requireAccessContext(c, deps);
+  const authority = accountScopedApiKeyWorkspaceAuthority(context);
+  if (
+    !authority ||
+    authority.accountId !== organizationId ||
+    !hasPermission(authority.permissions, "members:manage")
+  ) {
+    throw new HTTPException(403, {
+      message: "External membership operation requires an organization service key",
+    });
+  }
+  return { organizationId, actorSubjectId: context.subjectId };
+}
+
+export async function lookupExternalIdentityForRequest(
+  c: Context,
+  deps: AccessDeps,
+  organizationId: string,
+  input: unknown,
+) {
+  const service = await externalService(c, deps, organizationId);
+  const identity = ExternalIdentityReference.safeParse(input);
+  if (!identity.success)
+    throw new HTTPException(422, { message: "Invalid external identity reference" });
+  try {
+    return await lookupExternalIdentity(deps.db, service, identity.data);
+  } catch (error) {
+    rethrowExternalWorkspaceOperation(error);
+  }
+}
+
+export async function cancelExternalWorkspaceMemberGrantForRequest(
+  c: Context,
+  deps: AccessDeps,
+  organizationId: string,
+  workspaceId: string,
+  membershipId: string,
+  input: unknown,
+) {
+  const service = await externalService(c, deps, organizationId);
+  const request = CancelExternalWorkspaceMemberGrantRequest.safeParse(input);
+  if (!request.success)
+    throw new HTTPException(422, { message: "Invalid external grant cancellation" });
+  try {
+    return await cancelExternalWorkspaceMemberGrant(
+      deps.db,
+      { ...service, workspaceId, membershipId },
+      request.data,
+    );
+  } catch (error) {
+    rethrowExternalWorkspaceOperation(error);
+  }
+}

package/src/application/host-mcp-resolvers.ts

@@ -0,0 +1,85 @@
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+import {
+  HostMcpResolverSource,
+  PutHostMcpResolverRequest,
+  RevokeHostMcpResolverRequest,
+} from "@opengeni/contracts/host-mcp-resolvers";
+import { getHostMcpResolver, mutateHostMcpResolver, HostMcpResolverError } from "@opengeni/db";
+import { isLocalTestEnvironment, validateHttpUrl } from "@opengeni/network";
+import {
+  accountScopedApiKeyWorkspaceAuthority,
+  requireAccessContext,
+  type AccessDeps,
+} from "../access";
+import { requireVariableSetEncryption } from "../domain/environments";
+import { hasLegacyHostMcpResolver } from "../remote-mcp-credentials";
+
+export async function hostMcpResolverForRequest(
+  context: Context,
+  deps: AccessDeps,
+  organizationId: string,
+  source: string,
+  method: "get" | "put" | "revoke",
+  raw?: unknown,
+) {
+  const id = z.string().uuid().safeParse(organizationId);
+  const externalSource = HostMcpResolverSource.safeParse(source);
+  if (!id.success || !externalSource.success)
+    throw new HTTPException(422, { message: "invalid resolver identity" });
+  const access = await requireAccessContext(context, deps);
+  const service = accountScopedApiKeyWorkspaceAuthority(access);
+  const account = access.accountGrants.find(
+    (grant) => grant.accountId === id.data && grant.subjectId === access.subjectId,
+  );
+  if (!service || service.accountId !== id.data || !account?.permissions.includes("account:admin"))
+    throw new HTTPException(403, {
+      message: "resolver administration requires an organization service key",
+    });
+  const actor = { accountId: id.data, subjectId: access.subjectId };
+  try {
+    if (method === "get") return await getHostMcpResolver(deps.db, actor, externalSource.data);
+    const common = {
+      externalSource: externalSource.data,
+      encryptionKey: requireVariableSetEncryption(deps.settings),
+      legacyConfigured: hasLegacyHostMcpResolver(deps.settings, id.data),
+    };
+    if (method === "put") {
+      const parsed = PutHostMcpResolverRequest.safeParse(raw);
+      if (!parsed.success) throw new HTTPException(422, { message: "invalid resolver operation" });
+      let url: string;
+      try {
+        url = validateHttpUrl(parsed.data.url, {
+          allowLoopbackHttp: isLocalTestEnvironment(deps.settings.environment),
+        });
+        if (
+          new URL(url).protocol !== "https:" &&
+          !isLocalTestEnvironment(deps.settings.environment)
+        )
+          throw new Error();
+      } catch {
+        throw new HTTPException(422, { message: "invalid resolver URL" });
+      }
+      return await mutateHostMcpResolver(deps.db, actor, {
+        ...common,
+        kind: "put",
+        request: { ...parsed.data, url },
+      });
+    }
+    const parsed = RevokeHostMcpResolverRequest.safeParse(raw);
+    if (!parsed.success) throw new HTTPException(422, { message: "invalid resolver operation" });
+    return await mutateHostMcpResolver(deps.db, actor, {
+      ...common,
+      kind: "revoke",
+      request: parsed.data,
+    });
+  } catch (error) {
+    if (error instanceof HostMcpResolverError)
+      throw new HTTPException(error.status, { message: error.message });
+    if (error instanceof HTTPException) throw error;
+    // Database/encryption errors can carry SQL parameters. Never expose or log
+    // the underlying credential-bearing cause at the public route boundary.
+    throw new HTTPException(503, { message: "resolver administration unavailable" });
+  }
+}

package/src/application/new-session-drafts.ts

@@ -1,3 +1,5 @@
+import { fileOwnerContextForAccess } from "../domain/file-owner";
+import { withSessionRlsActorContext } from "@opengeni/db";
 import {
   NewSessionDraft,
   SaveNewSessionDraftRequest,
@@ -184,7 +186,7 @@ async function hydrateNewSessionDraft(
 }
 
 /** Read the authenticated actor's server-authoritative pre-session composer state. */
-export async function getActorNewSessionDraft(
+async function getActorNewSessionDraftInFileScope(
   deps: Pick<NewSessionDraftDependencies, "settings" | "db">,
   grant: AccessGrant,
   workspaceId: string,
@@ -219,7 +221,7 @@ export async function getActorNewSessionDraft(
  * draft may represent incomplete options, while no invalid option can become a
  * session without passing that single canonical create boundary.
  */
-export async function saveActorNewSessionDraft(
+async function saveActorNewSessionDraftInFileScope(
   deps: NewSessionDraftDependencies,
   grant: AccessGrant,
   workspaceId: string,
@@ -253,7 +255,16 @@ export async function saveActorNewSessionDraft(
       message: "object storage is not configured",
     });
   }
-  await validateFileResources(deps.db, grant.accountId, workspaceId, grant.subjectId, resources);
+  await validateFileResources(
+    deps.db,
+    grant.accountId,
+    workspaceId,
+    grant.subjectId,
+    resources,
+    externalAuthorization
+      ? await fileOwnerContextForAccess(deps, externalAuthorization, "sessions:create")
+      : undefined,
+  );
   assertConfiguredModel(deps.settings, input.model);
   await assertWorkspaceModelPolicyAllows(deps.db, deps.settings, workspaceId, input.model);
 
@@ -299,3 +310,26 @@ export async function saveActorNewSessionDraft(
     throw error;
   }
 }
+
+export async function getActorNewSessionDraft(
+  deps: Parameters<typeof getActorNewSessionDraftInFileScope>[0],
+  grant: AccessGrant,
+  workspaceId: string,
+  authorization?: AccessGrantAuthorization,
+): Promise<NewSessionDraftValue> {
+  const actor = authorization
+    ? await fileOwnerContextForAccess(deps, authorization, "sessions:read")
+    : { subjectId: grant.subjectId, privateFileOwnerSubjectId: null };
+  return withSessionRlsActorContext(actor, () =>
+    getActorNewSessionDraftInFileScope(deps, grant, workspaceId),
+  );
+}
+export async function saveActorNewSessionDraft(
+  ...args: Parameters<typeof saveActorNewSessionDraftInFileScope>
+): Promise<NewSessionDraftValue> {
+  const [deps, grant, , , , authorization] = args;
+  const actor = authorization
+    ? await fileOwnerContextForAccess(deps, authorization, "sessions:create")
+    : { subjectId: grant.subjectId, privateFileOwnerSubjectId: null };
+  return withSessionRlsActorContext(actor, () => saveActorNewSessionDraftInFileScope(...args));
+}

package/src/domain/file-owner.ts

@@ -0,0 +1,52 @@
+import { requireLiveAgentAttemptAuthorization } from "../session-authorization";
+import { freezeAgentLearningPolicy, type SessionRlsActorContext } from "@opengeni/db";
+import type { AccessGrant, Permission } from "@opengeni/contracts";
+import { requirePermission, type AccessGrantAuthorization } from "../access";
+import type { ApiRouteDeps } from "../dependencies";
+import { knowledgeContextForAccess } from "./knowledge";
+
+/** Personal original-file access follows verified ownership, never a subject-shaped bearer. */
+export async function fileOwnerContextForAccess(
+  deps: Pick<ApiRouteDeps, "db">,
+  access: AccessGrantAuthorization,
+  permission: Permission,
+): Promise<SessionRlsActorContext> {
+  if (access.grant.principalKind === "agent_attempt")
+    return fileOwnerContextForAgent(deps, access.grant, permission);
+  const context = await knowledgeContextForAccess(deps, access, permission);
+  if (context.actor.kind === "human")
+    return {
+      subjectId: context.actor.subjectId,
+      privateFileOwnerSubjectId: context.actor.subjectId,
+    };
+  return { subjectId: access.grant.subjectId, privateFileOwnerSubjectId: null };
+}
+
+/** Internal MCP/core callers can prove an agent attempt without inventing a human authorization. */
+export async function fileOwnerContextForAgent(
+  deps: Pick<ApiRouteDeps, "db">,
+  grant: AccessGrant,
+  permission: Permission,
+): Promise<SessionRlsActorContext> {
+  requirePermission(grant, permission);
+  const sessionId = grant.metadata?.sessionId;
+  if (grant.principalKind !== "agent_attempt" || typeof sessionId !== "string")
+    throw new Error("File access requires an exact agent attempt");
+  const attempt = await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
+  const snapshot = await freezeAgentLearningPolicy(deps.db, {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    actor: {
+      kind: "agent",
+      sessionId,
+      turnId: attempt.turnId,
+      attemptId: attempt.attemptId,
+      executionGeneration: attempt.executionGeneration,
+    },
+  });
+  return {
+    subjectId: grant.subjectId,
+    initiatingHumanSubjectId: attempt.initiatingHumanSubjectId,
+    privateFileOwnerSubjectId: snapshot.defaultScope === "personal" ? snapshot.subjectId : null,
+  };
+}