@opengeni/core 2.8.3 → 2.9.1-canary.0

package/src/access/index.ts

@@ -1,14 +1,28 @@
 import { resolveFirstPartyDelegationSecret, type Settings } from "@opengeni/config";
+import {
+  ExternalActorSelection,
+  ExternalActorAttribution,
+  type ExternalActorContinuation,
+  type ExternalIdentity,
+} from "@opengeni/contracts/external-identities";
 import {
   verifyDelegatedAccessToken,
   type AccountGrant,
   type AccessContext,
   type AccessGrant,
-  type Permission,
+  Permission,
+  type Workspace,
 } from "@opengeni/contracts";
 import {
   bootstrapWorkspace,
   ensureManagedAccessForUser,
+  ensureExternalIdentity,
+  resolveExternalIdentityLink,
+  managedPersonalWorkspacePermissions,
+  nestedPostgresSqlState,
+  withWorkspaceSubjectRls,
+  withAccountRls,
+  listWorkspacesForSubject,
   findActiveApiKeyByHash,
   getWorkspaceGrant,
   requireWorkspace,
@@ -45,11 +59,102 @@ const accessContextByRequest = new WeakMap<Request, Promise<AccessContext | null
  */
 const canonicalManagedCookieContexts = new WeakSet<AccessContext>();
 const canonicalLocalHumanContexts = new WeakSet<AccessContext>();
+const externalActorContexts = new WeakMap<
+  AccessContext,
+  {
+    identity: ExternalIdentity;
+    keyId: string;
+    permissions: Permission[];
+    linked?: NonNullable<Awaited<ReturnType<typeof resolveExternalIdentityLink>>>;
+  }
+>();
+function attributionForExternalContext(context: AccessContext): ExternalActorAttribution {
+  const external = externalActorContexts.get(context);
+  if (!external) throw new Error("Verified external context required");
+  return ExternalActorAttribution.parse({
+    accountId: external.identity.accountId,
+    authenticatingApiKeyId: external.keyId,
+    externalIdentityId: external.identity.id,
+    externalSubjectId: external.identity.subjectId,
+    externalAuthorizationRevision: external.identity.authorizationRevision,
+    effectiveSubjectId: context.subjectId,
+    actingMode: external.linked ? "linked_native" : "external",
+    ...(external.linked
+      ? { linkId: external.linked.link.id, linkRevision: external.linked.link.revision }
+      : {}),
+  });
+}
 const resolvedAccessGrantAuthorizations = new WeakSet<object>();
+const verifiedExternalAuthorizations = new WeakMap<
+  AccessGrantAuthorization,
+  {
+    grant: AccessGrant;
+    workspaceId: string;
+    identityReference: { externalId: string; source: string };
+    attribution: ExternalActorAttribution;
+  }
+>();
+
+/** Creation audit only, never an authentication or delegation token. Metadata
+ * claiming to be external is insufficient; the exact resolver proof is needed. */
+export function externalAttributionForAuthorization(
+  authorization: AccessGrantAuthorization | undefined,
+  grant: AccessGrant,
+): ExternalActorAttribution | null {
+  if (!authorization || authorization.grant !== grant) return null;
+  const verified = verifiedExternalAuthorizations.get(authorization);
+  if (
+    !verified ||
+    verified.grant !== grant ||
+    verified.workspaceId !== grant.workspaceId ||
+    verified.attribution.accountId !== grant.accountId ||
+    verified.attribution.effectiveSubjectId !== grant.subjectId
+  )
+    return null;
+  return structuredClone(verified.attribution);
+}
+
+export function externalActorContinuationForAuthorization(
+  authorization: AccessGrantAuthorization,
+): ExternalActorContinuation | null {
+  const actor = externalAttributionForAuthorization(authorization, authorization.grant);
+  const verified = verifiedExternalAuthorizations.get(authorization);
+  return actor && verified ? { actor, identity: { ...verified.identityReference } } : null;
+}
+
+/** Dedicated owning-user proof. External admission never sets the native
+ * cookie stamp. The resource/session layer still checks the exact owner. */
+export function hasVerifiedOwningUserAuthorization(
+  authorization: AccessGrantAuthorization,
+): boolean {
+  if (
+    !authorization.contextIntegrity ||
+    authorization.authenticatedSubjectId !== authorization.grant.subjectId
+  )
+    return false;
+  return (
+    authorization.canonicalManagedHumanSession ||
+    externalAttributionForAuthorization(authorization, authorization.grant) !== null
+  );
+}
 const accountScopedApiKeyContexts = new WeakMap<
   AccessContext,
   Readonly<{ accountId: string; permissions: readonly Permission[] }>
 >();
+const verifiedOrganizationServiceAuthorizations = new WeakMap<
+  AccessGrantAuthorization,
+  AccessGrant
+>();
+
+/** Request-local organization service-key proof, not a principal-kind claim. */
+export function isVerifiedOrganizationServiceAuthorization(
+  authorization: AccessGrantAuthorization,
+): boolean {
+  return (
+    verifiedOrganizationServiceAuthorizations.has(authorization) &&
+    verifiedOrganizationServiceAuthorizations.get(authorization) === authorization.grant
+  );
+}
 
 const accountScopedApiKeyAccountPermissions = new Set<Permission>([
   "account:read",
@@ -119,6 +224,39 @@ export type AccessDeps = {
   managedAuthSessionAdapter?: ManagedAuthSessionAdapter | null;
 };
 
+/** null means this is not an authenticated external lane; [] means that lane
+ * has no readable inventory. Callers must not fall back from [] to service or
+ * bare-subject discovery. */
+export async function listExternalActorWorkspaces(
+  context: AccessContext,
+  deps: AccessDeps,
+): Promise<Workspace[] | null> {
+  const actor = externalActorContexts.get(context);
+  if (!actor) return null;
+  if (
+    !hasPermission(actor.permissions, "workspace:read") ||
+    (actor.linked && !hasPermission(actor.linked.link.permissions, "workspace:read"))
+  )
+    return [];
+  const candidates = await withAccountRls(deps.db, actor.identity.accountId, (tx) =>
+    listWorkspacesForSubject(tx, context.subjectId),
+  );
+  const authorized: Workspace[] = [];
+  const personal = await withAccountRls(deps.db, actor.identity.accountId, (tx) =>
+    requireWorkspace(tx, actor.linked?.personalWorkspaceId ?? actor.identity.personalWorkspaceId),
+  );
+  if (personal.accountId === actor.identity.accountId && personal.kind === "personal")
+    authorized.push(personal);
+  for (const workspace of candidates) {
+    if (workspace.accountId !== actor.identity.accountId || workspace.kind !== "shared") continue;
+    const grant = await withWorkspaceSubjectRls(deps.db, workspace.id, context.subjectId, (tx) =>
+      getWorkspaceGrant(tx, context.subjectId, workspace.id),
+    );
+    if (grant && hasPermission(grant.permissions, "workspace:read")) authorized.push(workspace);
+  }
+  return authorized;
+}
+
 export async function requireAccessContext(c: Context, deps: AccessDeps): Promise<AccessContext> {
   let pending = accessContextByRequest.get(c.req.raw);
   if (!pending) {
@@ -210,6 +348,25 @@ export function accessGrantAuthorizationFromContext(
     canonicalLocalHumanSession: isCanonicalLocalHumanSession(context, grant),
   };
   resolvedAccessGrantAuthorizations.add(authorization);
+  if (
+    contextIntegrity &&
+    accountScopedApiKeyWorkspaceAuthority(context)?.accountId === grant.accountId &&
+    grant.principalKind === "api_key"
+  ) {
+    verifiedOrganizationServiceAuthorizations.set(authorization, grant);
+  }
+  const external = externalActorContexts.get(context);
+  if (external && contextIntegrity && grant.accountId === external.identity.accountId) {
+    verifiedExternalAuthorizations.set(authorization, {
+      grant,
+      workspaceId: grant.workspaceId,
+      identityReference: {
+        externalId: external.identity.externalId,
+        source: external.identity.source,
+      },
+      attribution: attributionForExternalContext(context),
+    });
+  }
   return authorization;
 }
 
@@ -345,6 +502,42 @@ async function accessGrantAuthorization(
   workspaceId: string,
   permission?: Permission,
 ): Promise<AccessGrantAuthorization> {
+  const external = externalActorContexts.get(context);
+  if (external) {
+    const grant: AccessGrant | null =
+      workspaceId ===
+      (external.linked?.personalWorkspaceId ?? external.identity.personalWorkspaceId)
+        ? {
+            accountId: external.identity.accountId,
+            workspaceId,
+            subjectId: context.subjectId,
+            principalKind: "human_session",
+            permissions: [...managedPersonalWorkspacePermissions],
+          }
+        : await withWorkspaceSubjectRls(deps.db, workspaceId, context.subjectId, (tx) =>
+            getWorkspaceGrant(tx, context.subjectId, workspaceId, {
+              principalKind: "human_session",
+            }),
+          );
+    if (!grant || grant.accountId !== external.identity.accountId) {
+      throw new HTTPException(403, { message: "external workspace access denied" });
+    }
+    // Intersect effective permissions using the existing wildcard/literal
+    // semantics on each side independently. Never return workspace:admin
+    // unless both sides hold it, and never infer literal secrets:read.
+    grant.permissions = Permission.options.filter(
+      (value) =>
+        hasPermission(grant.permissions, value) &&
+        hasPermission(external.permissions, value) &&
+        (!external.linked || hasPermission(external.linked.link.permissions, value)),
+    );
+    grant.metadata = {
+      ...grant.metadata,
+      externalActor: attributionForExternalContext(context),
+    };
+    if (permission) requirePermission(grant, permission);
+    return accessGrantAuthorizationFromContext(context, grant);
+  }
   const principalKind = hostedHumanSessionPrincipalKind(context);
   let grant =
     context.workspaceGrants.find((candidate) => candidate.workspaceId === workspaceId) ??
@@ -497,6 +690,14 @@ export function hasPermission(permissions: Permission[], permission: Permission)
 }
 
 async function resolveAccessContext(c: Context, deps: AccessDeps): Promise<AccessContext | null> {
+  if (c.req.header("x-opengeni-external-actor") !== undefined) {
+    if (deps.settings.productAccessMode === "local") {
+      throw new HTTPException(401, {
+        message: "external actors require organization key authentication",
+      });
+    }
+    return apiKeyAccessContext(c, deps, deps.settings.productAccessMode);
+  }
   if (deps.settings.productAccessMode === "local") {
     const delegated = await delegatedAccessContext(c, deps, "local");
     if (delegated) {
@@ -592,6 +793,59 @@ async function apiKeyAccessContext(
   if (!apiKey) {
     return null;
   }
+  const externalHeader = c.req.header("x-opengeni-external-actor");
+  if (externalHeader !== undefined) {
+    if (apiKey.workspaceId !== null || apiKey.credentialKind !== "organization") {
+      throw new HTTPException(403, { message: "external actors require an organization key" });
+    }
+    let selection: ExternalActorSelection;
+    try {
+      if (externalHeader.length > 16384) throw new Error("oversize");
+      selection = ExternalActorSelection.parse(JSON.parse(decodeURIComponent(externalHeader)));
+    } catch {
+      throw new HTTPException(400, { message: "invalid external actor selection" });
+    }
+    let identity: ExternalIdentity;
+    try {
+      identity = await ensureExternalIdentity(deps.db, {
+        accountId: apiKey.accountId,
+        ...selection.identity,
+      });
+    } catch (error) {
+      if (nestedPostgresSqlState(error) === "42501") {
+        throw new HTTPException(403, { message: "external identity is unavailable" });
+      }
+      throw new HTTPException(503, { message: "external identity authority is unavailable" });
+    }
+    const linked =
+      selection.mode === "linked_native"
+        ? await resolveExternalIdentityLink(deps.db, {
+            identity,
+            linkId: selection.linkId,
+            expectedRevision: selection.expectedLinkRevision,
+          })
+        : null;
+    if (selection.mode === "linked_native" && !linked)
+      throw new HTTPException(403, { message: "Native identity link is unavailable or changed" });
+    const effectiveSubjectId = linked?.link.nativeSubjectId ?? identity.subjectId;
+    const context: AccessContext = {
+      mode,
+      subjectId: effectiveSubjectId,
+      accountGrants: [
+        { accountId: identity.accountId, subjectId: effectiveSubjectId, permissions: [] },
+      ],
+      workspaceGrants: [],
+      defaultAccountId: identity.accountId,
+      defaultWorkspaceId: null,
+    };
+    externalActorContexts.set(context, {
+      identity,
+      keyId: apiKey.id,
+      permissions: [...apiKey.permissions],
+      ...(linked ? { linked } : {}),
+    });
+    return context;
+  }
   const subjectId = `api_key:${apiKey.id}`;
   const accountPermissions = apiKey.workspaceId
     ? apiKey.permissions.filter(

package/src/application/connect-authority.ts

@@ -0,0 +1,77 @@
+import type { Permission } from "@opengeni/contracts";
+import type { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
+import { hasPermission } from "../access";
+import { requireExternalContinuationAuthority } from "./external-continuation";
+import {
+  getWorkspaceGrant,
+  resolveNamedManagedPersonalWorkspaceGrant,
+  lockExternalWorkspaceMembershipLifecycle,
+  withWorkspaceSubjectRls,
+  type Database,
+  lockConnectionSetupKey,
+  nestedPostgresSqlState,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+
+/** Accept only a verified request owner or authenticated server-minted OAuth
+ * state. The callback does not need a browser cookie: it rechecks the stored
+ * principal against current authority before claiming and committing effects. */
+export async function requireConnectOwnerAuthority(
+  db: Database,
+  state: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    personalOwnerVerified?: boolean;
+    externalContinuation?: ExternalActorContinuation;
+  },
+  permission: Permission = "connections:write",
+  origin: ExternalActorContinuation | null = null,
+): Promise<void> {
+  async function requireExternal(continuation: ExternalActorContinuation) {
+    try {
+      await requireExternalContinuationAuthority(db, continuation, state, permission);
+    } catch (error) {
+      const denied =
+        nestedPostgresSqlState(error) === "42501" ||
+        (error instanceof Error && error.message === "External continuation authority unavailable");
+      throw new HTTPException(denied ? 403 : 503, {
+        message: denied
+          ? "Connection origin authority changed"
+          : "Connection origin authority unavailable",
+        cause: error,
+      });
+    }
+  }
+  // Current request authority cannot replace the original restriction. Native
+  // owners may resume their work, but an expired host/link origin still denies.
+  if (origin) await requireExternal(origin);
+  if (state.externalContinuation) {
+    await requireExternal(state.externalContinuation);
+    return;
+  }
+  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))
+      throw new HTTPException(403, { message: "Connection API key authority changed" });
+    return;
+  }
+  await withWorkspaceSubjectRls(db, state.workspaceId, state.subjectId, async (tx) => {
+    await lockExternalWorkspaceMembershipLifecycle(tx, state.accountId);
+    const membership = await getWorkspaceGrant(tx, state.subjectId, state.workspaceId);
+    const grant =
+      membership?.accountId === state.accountId
+        ? membership
+        : state.personalOwnerVerified
+          ? await resolveNamedManagedPersonalWorkspaceGrant(tx, state)
+          : null;
+    if (
+      !grant ||
+      grant.accountId !== state.accountId ||
+      !hasPermission(grant.permissions, permission)
+    )
+      throw new HTTPException(403, { message: "Connection owner authority changed" });
+  });
+}

package/src/application/connect-operation.ts

@@ -0,0 +1,51 @@
+import type { ConnectAttempt } from "@opengeni/contracts/connect";
+import {
+  claimConnectOperation,
+  finishConnectOperation,
+  type ConnectActorScope,
+  type ConnectOperationAuthorization,
+  type Database,
+} from "@opengeni/db";
+
+/** Provider result is deliberately not serializable: secrets can remain in its
+ * closure until encrypted credential persistence. Do not retain/log this value. */
+export type PreparedConnectOperation = {
+  commit: (tx: Database, current: ConnectAttempt) => Promise<ConnectAttempt>;
+};
+
+/** Internal provider-adapter boundary, not an HTTP authentication adapter.
+ *
+ * authorize is mandatory, including for a receipt replay. It must validate the
+ * exact saved key/actor/link authority and current permission under database
+ * locks. execute owns provider-specific proof, destination and cancellation.
+ * No remote effects may occur inside authorize or commit.
+ *
+ * A failed execute/authorization/commit keeps the durable claim occupied. It
+ * does not release or retry work whose provider outcome may be unknown.
+ */
+export async function executeConnectOperation(input: {
+  db: Database;
+  scope: ConnectActorScope;
+  attemptId: string;
+  expectedRevision: number;
+  operationId: string;
+  /** Caller computes a stable keyed digest if input contains low-entropy secrets. */
+  inputDigest: string;
+  authorize: ConnectOperationAuthorization;
+  execute: (attempt: ConnectAttempt) => Promise<PreparedConnectOperation>;
+}): Promise<ConnectAttempt> {
+  // Snapshot caller-controlled identity before the first asynchronous boundary.
+  const { db, authorize, execute } = input;
+  const scope = { ...input.scope };
+  const operation = {
+    attemptId: input.attemptId,
+    expectedRevision: input.expectedRevision,
+    operationId: input.operationId,
+    inputDigest: input.inputDigest,
+    authorize,
+  };
+  const claim = await claimConnectOperation(db, scope, operation);
+  if (claim.status === "replayed") return claim.attempt;
+  const prepared = await execute(structuredClone(claim.attempt));
+  return finishConnectOperation(db, scope, { ...operation, commit: prepared.commit });
+}

package/src/application/external-continuation.ts

@@ -0,0 +1,112 @@
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
+import type { Permission } from "@opengeni/contracts";
+import {
+  ensureExternalIdentity,
+  resolveExternalIdentityLink,
+  getWorkspaceGrant,
+  lockActiveExternalOrganizationKey,
+  lockExternalWorkspaceMembershipLifecycle,
+  managedPersonalWorkspacePermissions,
+  nestedPostgresSqlState,
+  withWorkspaceSubjectRls,
+  type Database,
+} from "@opengeni/db";
+import {
+  hasPermission,
+  externalActorContinuationForAuthorization,
+  type AccessGrantAuthorization,
+} from "../access";
+import { HTTPException } from "hono/http-exception";
+
+/** Capture verified request authority before asynchronous preflight. Invoke
+ * inside the canonical mutation transaction after its lifecycle locks, so a
+ * revoked key/generation rolls the write back without changing lock order. */
+export function externalContinuationCommitAuthorizer(
+  authorization: AccessGrantAuthorization | undefined,
+): ((tx: Database) => Promise<void>) | undefined {
+  const continuation = authorization
+    ? externalActorContinuationForAuthorization(authorization)
+    : null;
+  if (!continuation || !authorization) return undefined;
+  const scope = {
+    accountId: authorization.grant.accountId,
+    workspaceId: authorization.grant.workspaceId,
+    subjectId: authorization.grant.subjectId,
+  };
+  const permissions = [...authorization.grant.permissions];
+  return async (tx) => {
+    try {
+      await requireExternalContinuationAuthority(tx, continuation, scope, permissions);
+    } catch (error) {
+      const denied =
+        nestedPostgresSqlState(error) === "42501" ||
+        (error instanceof Error && error.message === "External continuation authority unavailable");
+      throw new HTTPException(denied ? 403 : 503, {
+        message: denied ? "external authority changed" : "external authority is unavailable",
+        cause: error,
+      });
+    }
+  };
+}
+
+/** Caller verifies/decrypts its server-minted continuation before invoking.
+ * An open transaction retains lifecycle/key/identity locks through persistence.
+ * Historical creator audit alone must never enter this path as a credential. */
+export async function requireExternalContinuationAuthority(
+  tx: Database,
+  raw: unknown,
+  scope: { accountId: string; workspaceId: string; subjectId: string },
+  permission: Permission | readonly Permission[],
+): Promise<void> {
+  const { actor, identity: reference } = ExternalActorContinuation.parse(raw);
+  const required = typeof permission === "string" ? [permission] : [...permission];
+  const deny = () => {
+    throw new Error("External continuation authority unavailable");
+  };
+  if (actor.accountId !== scope.accountId || actor.effectiveSubjectId !== scope.subjectId) deny();
+  await lockExternalWorkspaceMembershipLifecycle(tx, scope.accountId);
+  const permissions = await lockActiveExternalOrganizationKey(
+    tx,
+    scope.accountId,
+    actor.authenticatingApiKeyId,
+  );
+  if (!permissions || required.some((value) => !hasPermission(permissions, value))) deny();
+  const identity = await ensureExternalIdentity(tx, { accountId: scope.accountId, ...reference });
+  if (
+    identity.id !== actor.externalIdentityId ||
+    identity.subjectId !== actor.externalSubjectId ||
+    identity.authorizationRevision !== actor.externalAuthorizationRevision
+  )
+    deny();
+  const linked =
+    actor.actingMode === "linked_native"
+      ? await resolveExternalIdentityLink(tx, {
+          identity,
+          linkId: actor.linkId!,
+          expectedRevision: actor.linkRevision!,
+        })
+      : null;
+  if (
+    actor.actingMode === "linked_native" &&
+    (!linked ||
+      linked.link.nativeSubjectId !== scope.subjectId ||
+      required.some((value) => !hasPermission(linked.link.permissions, value)))
+  )
+    deny();
+  if (actor.actingMode === "external" && scope.subjectId !== identity.subjectId) deny();
+  const grant =
+    scope.workspaceId === (linked?.personalWorkspaceId ?? identity.personalWorkspaceId)
+      ? {
+          accountId: identity.accountId,
+          permissions: managedPersonalWorkspacePermissions,
+        }
+      : await withWorkspaceSubjectRls(tx, scope.workspaceId, scope.subjectId, (db) =>
+          getWorkspaceGrant(db, scope.subjectId, scope.workspaceId),
+        );
+  if (
+    !grant ||
+    grant.accountId !== scope.accountId ||
+    required.some((value) => !hasPermission(grant.permissions, value))
+  )
+    deny();
+}

package/src/application/external-identity-lifecycle.ts

@@ -0,0 +1,48 @@
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { UpdateExternalIdentityMembershipRequest } from "@opengeni/contracts/external-identities";
+import { updateOrganizationMember } from "@opengeni/db";
+import {
+  accountScopedApiKeyWorkspaceAuthority,
+  requireAccessContext,
+  type AccessDeps,
+} from "../access";
+
+/** Host service administration is separate from asUser and native-cookie
+ * administration. The database rechecks the live key and exact external target
+ * under the canonical organization lifecycle fences, including receipt replay. */
+export async function updateExternalIdentityMembershipForRequest(
+  context: Context,
+  deps: AccessDeps,
+  organizationId: string,
+  membershipId: string,
+  input: unknown,
+) {
+  const access = await requireAccessContext(context, deps);
+  const service = accountScopedApiKeyWorkspaceAuthority(access);
+  // The workspace projection deliberately excludes account:admin. Its opaque
+  // proof establishes service provenance; the exact account grant supplies
+  // this account-level permission, independently rechecked by the database.
+  const account = access.accountGrants.find(
+    (grant) => grant.accountId === organizationId && grant.subjectId === access.subjectId,
+  );
+  if (
+    !service ||
+    service.accountId !== organizationId ||
+    !account?.permissions.includes("account:admin")
+  ) {
+    throw new HTTPException(403, {
+      message: "external identity administration requires an organization service key",
+    });
+  }
+  const parsed = UpdateExternalIdentityMembershipRequest.safeParse(input);
+  if (!parsed.success)
+    throw new HTTPException(422, { message: "invalid external identity transition" });
+  return updateOrganizationMember(deps.db, {
+    organizationId,
+    membershipId,
+    actorSubjectId: access.subjectId,
+    operationId: parsed.data.operationId,
+    transition: parsed.data,
+  });
+}

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

@@ -0,0 +1,87 @@
+import type { ScheduledTask } from "@opengeni/contracts";
+import { ExternalLinkWorkSnapshot } from "@opengeni/contracts/external-identities";
+import {
+  captureExternalLinkTurnAuthority,
+  captureExternalLinkTaskAuthority,
+  getExternalLinkTurnSnapshot,
+  getSessionTurnForAttempt,
+  type Database,
+} from "@opengeni/db";
+import {
+  externalActorContinuationForAuthorization,
+  hasVerifiedOwningUserAuthorization,
+  type AccessGrantAuthorization,
+} from "../access";
+import { externalContinuationCommitAuthorizer } from "./external-continuation";
+
+function snapshotFor(authorization: AccessGrantAuthorization | undefined) {
+  const continuation = authorization
+    ? externalActorContinuationForAuthorization(authorization)
+    : null;
+  return continuation?.actor.actingMode === "linked_native"
+    ? ExternalLinkWorkSnapshot.parse({
+        ...continuation,
+        permissions: [...authorization!.grant.permissions],
+      })
+    : null;
+}
+
+/** Closure is created only from the access resolver's object-identity proof.
+ * JSON metadata and an ordinary named native subject can never enter it. */
+export function prepareExternalLinkTurnAdmission(
+  authorization: AccessGrantAuthorization | undefined,
+) {
+  const snapshot = snapshotFor(authorization);
+  if (!snapshot || !authorization) return undefined;
+  const workspaceId = authorization.grant.workspaceId;
+  const accountId = authorization.grant.accountId;
+  const commit = externalContinuationCommitAuthorizer(authorization)!;
+  return async (tx: Database, sessionId: string, turnId: string) => {
+    await commit(tx);
+    await captureExternalLinkTurnAuthority(tx, {
+      accountId,
+      workspaceId,
+      sessionId,
+      turnId,
+      snapshot,
+    });
+  };
+}
+
+export function prepareExternalLinkTaskAdmission(
+  authorization: AccessGrantAuthorization | undefined,
+  actor?: {
+    sessionId: string;
+    turnId: string;
+    attemptId: string;
+    executionGeneration: number;
+  } | null,
+): ((tx: Database, task: ScheduledTask) => Promise<void>) | undefined {
+  const snapshot = snapshotFor(authorization);
+  const commit = externalContinuationCommitAuthorizer(authorization);
+  if (snapshot)
+    return async (tx, task) => {
+      await commit?.(tx);
+      await captureExternalLinkTaskAuthority(tx, task, snapshot);
+    };
+  if (!actor) {
+    // A fresh, explicitly authenticated owning-user revision uses that user's
+    // own lane. It does not inherit a previous editor's link by accident.
+    // Service lifecycle edits and internal promotion still clone old provenance.
+    return authorization && hasVerifiedOwningUserAuthorization(authorization)
+      ? async () => {}
+      : undefined;
+  }
+  return async (tx, task) => {
+    const turn = await getSessionTurnForAttempt(
+      tx,
+      task.workspaceId,
+      actor.sessionId,
+      actor.attemptId,
+    );
+    if (!turn || turn.id !== actor.turnId || turn.executionGeneration !== actor.executionGeneration)
+      throw new Error("Linked task creator attempt is no longer active");
+    const inherited = await getExternalLinkTurnSnapshot(tx, task, actor.turnId);
+    if (inherited) await captureExternalLinkTaskAuthority(tx, task, inherited);
+  };
+}