@opengeni/core 3.0.1 → 3.1.2

package/src/access/service-initiator.ts

@@ -0,0 +1,50 @@
+import { ServiceTurnInitiatorContext, type AccessGrant } from "@opengeni/contracts";
+import { HTTPException } from "hono/http-exception";
+
+/** Validated provenance only. The API key remains the authenticated principal. */
+export function serviceInitiatorFromHeaders(
+  headers: Headers,
+): Pick<AccessGrant, "serviceInitiator" | "serviceInitiatorContext"> | null {
+  const name = headers.get("x-opengeni-service-initiator");
+  const rawContext = headers.get("x-opengeni-service-context");
+  if (name === null && rawContext === null) return null;
+  if (headers.has("x-opengeni-external-actor")) {
+    throw new HTTPException(422, {
+      message: "service initiator and external actor (asUser) are mutually exclusive",
+    });
+  }
+  if (name === null || !/^[a-z0-9][a-z0-9:._-]{0,63}$/.test(name)) {
+    throw new HTTPException(422, {
+      message: "x-opengeni-service-initiator must match ^[a-z0-9][a-z0-9:._-]{0,63}$",
+    });
+  }
+  let context: Record<string, string | number | boolean> = {};
+  if (rawContext !== null) {
+    try {
+      if (new TextEncoder().encode(rawContext).byteLength > 2048) throw new Error("oversize");
+      const parsed: unknown = JSON.parse(rawContext);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("object");
+      if (
+        !Object.values(parsed).every(
+          (value) =>
+            typeof value === "string" ||
+            typeof value === "boolean" ||
+            (typeof value === "number" && Number.isFinite(value)),
+        )
+      )
+        throw new Error("flat");
+      context = parsed as typeof context;
+      // Keep delegated provenance's reserved, Opengeni-owned lineage fields.
+      if (!ServiceTurnInitiatorContext.safeParse(context).success) throw new Error("reserved");
+    } catch {
+      throw new HTTPException(422, {
+        message:
+          "x-opengeni-service-context must be a JSON object of flat string/number/boolean values, at most 2048 UTF-8 bytes, without reserved Opengeni provenance fields",
+      });
+    }
+  }
+  return {
+    serviceInitiator: { kind: "service", subjectId: name },
+    serviceInitiatorContext: context,
+  };
+}

package/src/application/api-integration-servers.ts

@@ -15,6 +15,7 @@ import type {
   ResolveConnectionCredentialInput,
   ResolveConnectionCredentialResult,
 } from "@opengeni/db";
+import { apiIntegrationToolEffect } from "@opengeni/db";
 import type { FetchLike } from "@opengeni/network";
 import type { LocalMcpServerRegistration } from "@opengeni/runtime";
 
@@ -79,6 +80,14 @@ export function buildApiIntegrationMcpServers(
     return {
       id: integration.serverId,
       server,
+      effectAuthority: (toolName) => ({
+        kind: "api_integration",
+        instanceId: integration.instanceId,
+        baseUrl: integration.baseUrl,
+        connectionRef: integration.connectionRef,
+        connectionAuthorityGeneration: integration.connectionAuthorityGeneration,
+        effect: apiIntegrationToolEffect(integration.revision, toolName),
+      }),
       approvalAuthority: {
         kind: "api_integration",
         capabilityId: integration.capabilityId,

package/src/application/archived-session-imports.ts

@@ -0,0 +1,161 @@
+import {
+  AppendArchivedSessionEventsRequest,
+  AppendArchivedSessionEventsResponse,
+  ImportArchivedSessionRequest,
+  ImportArchivedSessionResponse,
+  type Permission,
+  type SessionEvent,
+} from "@opengeni/contracts";
+import {
+  ArchivedSessionImportError,
+  appendArchivedSessionEvents,
+  getArchivedSessionImportId,
+  importArchivedSession,
+  withSessionRlsActorContext,
+} from "@opengeni/db";
+import { publishDurableSessionEvents } from "@opengeni/events";
+import { HTTPException } from "hono/http-exception";
+import {
+  hasVerifiedOwningUserAuthorization,
+  requirePermission,
+  requireResolvedAccessGrantAuthorization,
+  type AccessGrantAuthorization,
+} from "../access";
+import type { ApiRouteDeps } from "../dependencies";
+import { creationInitiatorForGrant } from "../domain/sessions";
+import { fileOwnerContextForAccess } from "../domain/file-owner";
+import {
+  grantHasAgentAttemptAuthority,
+  requireSessionAuthorization,
+} from "../session-authorization";
+import { externalContinuationCommitAuthorizer } from "./external-continuation";
+import { requireManagedHumanPrivateSessionCreate } from "./session-tenancy";
+
+export { ArchivedSessionImportError } from "@opengeni/db";
+
+function requireImportAuthorization(
+  authorization: AccessGrantAuthorization,
+  workspaceId: string,
+  permission: Permission,
+) {
+  const grant = requireResolvedAccessGrantAuthorization(authorization, workspaceId);
+  requirePermission(grant, permission);
+  if (grantHasAgentAttemptAuthority(grant)) {
+    throw new HTTPException(403, {
+      message: "Session history imports require a user or service request",
+    });
+  }
+  return grant;
+}
+
+function importerScope(
+  authorization: AccessGrantAuthorization,
+  workspaceId: string,
+  permission: Permission,
+  fileOwnerSubjectId: string | null,
+) {
+  const grant = authorization.grant;
+  const apiKeyId =
+    grant.principalKind === "api_key" && grant.subjectId.startsWith("api_key:")
+      ? grant.subjectId.slice("api_key:".length)
+      : undefined;
+  const beforeCommit = externalContinuationCommitAuthorizer(authorization);
+  return {
+    accountId: grant.accountId,
+    workspaceId,
+    subjectId: grant.subjectId,
+    fileOwnerSubjectId,
+    requiredPermission: permission,
+    requireLiveSubject:
+      hasVerifiedOwningUserAuthorization(authorization) || authorization.canonicalLocalHumanSession,
+    ...(apiKeyId ? { apiKeyId } : {}),
+    ...(beforeCommit ? { beforeCommit } : {}),
+  };
+}
+
+/** Committed import truth survives unavailable fanout; SSE catch-up repairs it.
+ * Never make a known committed append look failed and invite an unsafe retry. */
+async function publishImportedEvents(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+  sessionId: string,
+  events: SessionEvent[],
+): Promise<void> {
+  if (!events.length) return;
+  try {
+    await publishDurableSessionEvents(deps.bus, workspaceId, sessionId, events);
+  } catch {
+    console.warn("[session-import] committed timeline fanout deferred to replay", { sessionId });
+  }
+}
+
+export async function importArchivedSessionForRequest(
+  deps: ApiRouteDeps,
+  authorization: AccessGrantAuthorization,
+  workspaceId: string,
+  rawPayload: unknown,
+): Promise<ImportArchivedSessionResponse> {
+  const grant = requireImportAuthorization(authorization, workspaceId, "sessions:create");
+  const payload = ImportArchivedSessionRequest.parse(rawPayload);
+  if (payload.visibility === "user_private") {
+    await requireManagedHumanPrivateSessionCreate(deps, authorization, workspaceId);
+  }
+  const creator = creationInitiatorForGrant(grant);
+  if (!creator.initiator)
+    throw new HTTPException(403, { message: "Import creator is unavailable" });
+  const actor = await fileOwnerContextForAccess(deps, authorization, "sessions:create");
+  const result = await withSessionRlsActorContext(actor, () =>
+    importArchivedSession(deps.db, {
+      ...importerScope(
+        authorization,
+        workspaceId,
+        "sessions:create",
+        actor.privateFileOwnerSubjectId ?? null,
+      ),
+      payload,
+      createdBy: creator.initiator!,
+      createdByContext: creator.context ?? {},
+    }),
+  );
+  await publishImportedEvents(deps, workspaceId, result.session.id, result.events);
+  return ImportArchivedSessionResponse.parse(result);
+}
+
+export async function appendArchivedSessionEventsForRequest(
+  deps: ApiRouteDeps,
+  authorization: AccessGrantAuthorization,
+  workspaceId: string,
+  importId: string,
+  rawPayload: unknown,
+): Promise<AppendArchivedSessionEventsResponse> {
+  const grant = requireImportAuthorization(authorization, workspaceId, "sessions:control");
+  const payload = AppendArchivedSessionEventsRequest.parse(rawPayload);
+  const actor = await fileOwnerContextForAccess(deps, authorization, "sessions:control");
+  const result = await withSessionRlsActorContext(actor, async () => {
+    const sessionId = await getArchivedSessionImportId(
+      deps.db,
+      workspaceId,
+      grant.subjectId,
+      importId,
+    );
+    if (!sessionId) throw new ArchivedSessionImportError("SESSION_IMPORT_NOT_FOUND");
+    await requireSessionAuthorization(deps, grant, {
+      sessionId,
+      operation: "session.append",
+      surface: "core",
+    });
+    return appendArchivedSessionEvents(deps.db, {
+      ...importerScope(
+        authorization,
+        workspaceId,
+        "sessions:control",
+        actor.privateFileOwnerSubjectId ?? null,
+      ),
+      importId,
+      sessionId,
+      payload,
+    });
+  });
+  await publishImportedEvents(deps, workspaceId, result.sessionId, result.events);
+  return AppendArchivedSessionEventsResponse.parse(result);
+}

package/src/application/composer-submit.ts

@@ -26,7 +26,7 @@ export type SubmitComposerDraftForRequestOptions = {
  * This is the application boundary shared by the stock HTTP adapter and an
  * in-process embedding host. A host may prepare its own durable business state
  * before calling this function and project the returned receipt afterward, but
- * OpenGeni remains the sole authority for draft validation/rotation, event
+ * Opengeni remains the sole authority for draft validation/rotation, event
  * append, turn creation, routing, and idempotent replay.
  */
 export async function submitComposerDraftForRequest(
@@ -48,7 +48,8 @@ export async function submitComposerDraftForRequest(
     reasoningEffort: input.reasoningEffort,
     latencyMode: input.latencyMode,
     mcpCredentialUpdates: input.mcpCredentialUpdates ?? [],
-    connectionAuthorities: input.connectionAuthorities,
+    connectionAccounts: input.connectionAccounts,
+
     ...(input.personalResourceAttachment
       ? { personalResourceAttachment: input.personalResourceAttachment }
       : {}),

package/src/application/connect-authority.ts

@@ -8,7 +8,7 @@ import {
   lockExternalWorkspaceMembershipLifecycle,
   withWorkspaceSubjectRls,
   type Database,
-  lockConnectionSetupKey,
+  lockConnectionSetupKeyAuthority,
   nestedPostgresSqlState,
 } from "@opengeni/db";
 import { HTTPException } from "hono/http-exception";
@@ -53,8 +53,8 @@ export async function requireConnectOwnerAuthority(
   if (state.subjectId.startsWith("external_user:"))
     throw new HTTPException(403, { message: "External Connect continuation required" });
   if (state.subjectId.startsWith("api_key:")) {
-    const permissions = await lockConnectionSetupKey(db, state);
-    if (!permissions || !hasPermission(permissions, permission))
+    const authority = await lockConnectionSetupKeyAuthority(db, state);
+    if (!authority || !hasPermission(authority.permissions, permission, authority.permissionMode))
       throw new HTTPException(403, { message: "Connection API key authority changed" });
     return;
   }

package/src/application/connect-operation.ts

@@ -1,4 +1,7 @@
 import type { ConnectAttempt } from "@opengeni/contracts/connect";
+import { assertOrganizationIntegrationAllowed } from "@opengeni/contracts";
+import { withOrganizationIntegrationPolicyFence } from "@opengeni/db/organization-integration-policy";
+import { integrationKeyForConnectProvider } from "../domain/organization-integration-catalog";
 import {
   claimConnectOperation,
   finishConnectOperation,
@@ -31,11 +34,17 @@ export async function executeConnectOperation(input: {
   operationId: string;
   /** Caller computes a stable keyed digest if input contains low-entropy secrets. */
   inputDigest: string;
+  /** Trusted server adapter classification, never derived from request data.
+   * Cancellation releases pending setup; it acquires no integration authority. */
+  purpose?: "acquisition" | "cancellation";
+  /** Trusted adapter's exact attempt fence, inside the organization policy
+   * prefix and before Connect row locks, for both claim and final commit. */
+  beforeOperation?: ((tx: Database) => Promise<void>) | undefined;
   authorize: ConnectOperationAuthorization;
   execute: (attempt: ConnectAttempt) => Promise<PreparedConnectOperation>;
 }): Promise<ConnectAttempt> {
   // Snapshot caller-controlled identity before the first asynchronous boundary.
-  const { db, authorize, execute } = input;
+  const { db, authorize, execute, beforeOperation, purpose = "acquisition" } = input;
   const scope = { ...input.scope };
   const operation = {
     attemptId: input.attemptId,
@@ -44,8 +53,33 @@ export async function executeConnectOperation(input: {
     inputDigest: input.inputDigest,
     authorize,
   };
-  const claim = await claimConnectOperation(db, scope, operation);
+  const claim = await withOrganizationIntegrationPolicyFence(db, scope, async (tx, policy) => {
+    await beforeOperation?.(tx);
+    return claimConnectOperation(tx, scope, {
+      ...operation,
+      authorizeAcquisition: async (_tx, attempt) => {
+        if (purpose === "cancellation") return;
+        assertOrganizationIntegrationAllowed(
+          policy,
+          integrationKeyForConnectProvider(attempt.providerId),
+        );
+      },
+    });
+  });
   if (claim.status === "replayed") return claim.attempt;
   const prepared = await execute(structuredClone(claim.attempt));
-  return finishConnectOperation(db, scope, { ...operation, commit: prepared.commit });
+  return withOrganizationIntegrationPolicyFence(db, scope, async (tx, policy) => {
+    await beforeOperation?.(tx);
+    return finishConnectOperation(tx, scope, {
+      ...operation,
+      commit: prepared.commit,
+      authorizeAcquisition: async (_tx, attempt) => {
+        if (purpose === "cancellation") return;
+        assertOrganizationIntegrationAllowed(
+          policy,
+          integrationKeyForConnectProvider(attempt.providerId),
+        );
+      },
+    });
+  });
 }

package/src/application/external-continuation.ts

@@ -4,7 +4,9 @@ import {
   ensureExternalIdentity,
   resolveExternalIdentityLink,
   getWorkspaceGrant,
-  lockActiveExternalOrganizationKey,
+  lockActiveExternalOrganizationKeyAuthority,
+  getOrganizationApiKey,
+  requireWorkspace,
   lockExternalWorkspaceMembershipLifecycle,
   managedPersonalWorkspacePermissions,
   nestedPostgresSqlState,
@@ -13,6 +15,7 @@ import {
 } from "@opengeni/db";
 import {
   hasPermission,
+  organizationWorkspaceInScope,
   externalActorContinuationForAuthorization,
   type AccessGrantAuthorization,
 } from "../access";
@@ -65,12 +68,26 @@ export async function requireExternalContinuationAuthority(
   };
   if (actor.accountId !== scope.accountId || actor.effectiveSubjectId !== scope.subjectId) deny();
   await lockExternalWorkspaceMembershipLifecycle(tx, scope.accountId);
-  const permissions = await lockActiveExternalOrganizationKey(
+  const authority = await lockActiveExternalOrganizationKeyAuthority(
     tx,
     scope.accountId,
     actor.authenticatingApiKeyId,
   );
-  if (!permissions || required.some((value) => !hasPermission(permissions, value))) deny();
+  const key = authority
+    ? await getOrganizationApiKey(tx, scope.accountId, actor.authenticatingApiKeyId)
+    : null;
+  if (
+    !authority ||
+    !key ||
+    !organizationWorkspaceInScope(key.workspaceScope ?? { kind: "all" }, scope.workspaceId) ||
+    required.some((value) => !hasPermission(authority.permissions, value, authority.permissionMode))
+  )
+    deny();
+  if (
+    key?.permissionMode === "explicit" &&
+    (await requireWorkspace(tx, scope.workspaceId)).kind !== "shared"
+  )
+    deny();
   const identity = await ensureExternalIdentity(tx, { accountId: scope.accountId, ...reference });
   if (
     identity.id !== actor.externalIdentityId ||

package/src/application/external-link-work-admission.ts

@@ -22,6 +22,9 @@ function snapshotFor(authorization: AccessGrantAuthorization | undefined) {
     ? ExternalLinkWorkSnapshot.parse({
         ...continuation,
         permissions: [...authorization!.grant.permissions],
+        ...(authorization!.grant.permissionMode === "explicit"
+          ? { permissionMode: "explicit" }
+          : {}),
       })
     : null;
 }

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

@@ -4,6 +4,7 @@ import {
   AddExternalWorkspaceMemberRequest,
   ExternalIdentityReference,
   CancelExternalWorkspaceMemberGrantRequest,
+  UpdateExternalWorkspaceMemberRequest,
   type ExternalIdentity,
 } from "@opengeni/contracts/external-identities";
 import {
@@ -16,6 +17,7 @@ import {
   withWorkspaceSubjectRls,
   addExternalWorkspaceMemberOperation,
   cancelExternalWorkspaceMemberGrant,
+  updateExternalWorkspaceMemberOperation,
   lookupExternalIdentity,
   nestedPostgresSqlState,
 } from "@opengeni/db";
@@ -24,11 +26,14 @@ import {
   accountScopedApiKeyWorkspaceAuthority,
   hasPermission,
   requireAccessContext,
+  requireApiKeyDelegationContext,
   requireFreshAccessGrant,
   type AccessDeps,
 } from "../access";
 
-/** Explicit host onboarding. Ordinary asUser reads never call this operation.
+/** Explicit host onboarding. Ordinary asUser requests never call this
+ * operation; their first-use membership is `provisionExternalMemberOnFirstUse`
+ * in `../access`, under the same key authority and lifecycle fence.
  * Existing memberships are not overwritten, including reduced permissions. */
 export async function addExternalWorkspaceMemberForRequest(
   c: Context,
@@ -38,6 +43,7 @@ export async function addExternalWorkspaceMemberForRequest(
 ): Promise<ExternalIdentity> {
   const payload = AddExternalWorkspaceMemberRequest.parse(input);
   const context = await requireAccessContext(c, deps);
+  requireApiKeyDelegationContext(context, payload.permissions);
   const authority = accountScopedApiKeyWorkspaceAuthority(context);
   if (!authority)
     throw new HTTPException(403, {
@@ -128,7 +134,12 @@ function rethrowExternalWorkspaceOperation(error: unknown): never {
   throw error;
 }
 
-async function externalService(c: Context, deps: AccessDeps, organizationId: string) {
+async function externalService(
+  c: Context,
+  deps: AccessDeps,
+  organizationId: string,
+  workspaceId?: string,
+) {
   const context = await requireAccessContext(c, deps);
   const authority = accountScopedApiKeyWorkspaceAuthority(context);
   if (
@@ -140,6 +151,11 @@ async function externalService(c: Context, deps: AccessDeps, organizationId: str
       message: "External membership operation requires an organization service key",
     });
   }
+  if (workspaceId !== undefined) {
+    const grant = await requireFreshAccessGrant(c, deps, workspaceId, "members:manage");
+    if (grant.accountId !== organizationId)
+      throw new HTTPException(403, { message: "External membership workspace authority changed" });
+  }
   return { organizationId, actorSubjectId: context.subjectId };
 }
 
@@ -168,7 +184,7 @@ export async function cancelExternalWorkspaceMemberGrantForRequest(
   membershipId: string,
   input: unknown,
 ) {
-  const service = await externalService(c, deps, organizationId);
+  const service = await externalService(c, deps, organizationId, workspaceId);
   const request = CancelExternalWorkspaceMemberGrantRequest.safeParse(input);
   if (!request.success)
     throw new HTTPException(422, { message: "Invalid external grant cancellation" });
@@ -182,3 +198,35 @@ export async function cancelExternalWorkspaceMemberGrantForRequest(
     rethrowExternalWorkspaceOperation(error);
   }
 }
+
+/** Keyed permission change for an existing external member. Widening only
+ * rewrites the set; narrowing also advances the member's authorization
+ * revision so live authority re-checks. Never cancels or tears down work. */
+export async function updateExternalWorkspaceMemberForRequest(
+  c: Context,
+  deps: AccessDeps,
+  organizationId: string,
+  workspaceId: string,
+  membershipId: string,
+  input: unknown,
+) {
+  const service = await externalService(c, deps, organizationId, workspaceId);
+  const request = UpdateExternalWorkspaceMemberRequest.safeParse(input);
+  if (!request.success)
+    throw new HTTPException(422, {
+      message: `Invalid external member update: ${request.error.issues
+        .slice(0, 5)
+        .map((issue) => `${issue.path.map(String).join(".") || "request"}: ${issue.message}`)
+        .join("; ")}`,
+    });
+  requireApiKeyDelegationContext(await requireAccessContext(c, deps), request.data.permissions);
+  try {
+    return await updateExternalWorkspaceMemberOperation(
+      deps.db,
+      { ...service, workspaceId, membershipId },
+      request.data,
+    );
+  } catch (error) {
+    rethrowExternalWorkspaceOperation(error);
+  }
+}