@opengeni/core 0.28.0 → 1.0.0

package/src/application/external-continuation.ts

@@ -0,0 +1,129 @@
+import { ExternalActorContinuation } from "@opengeni/contracts/external-identities";
+import type { Permission } from "@opengeni/contracts";
+import {
+  ensureExternalIdentity,
+  resolveExternalIdentityLink,
+  getWorkspaceGrant,
+  lockActiveExternalOrganizationKeyAuthority,
+  getOrganizationApiKey,
+  requireWorkspace,
+  lockExternalWorkspaceMembershipLifecycle,
+  managedPersonalWorkspacePermissions,
+  nestedPostgresSqlState,
+  withWorkspaceSubjectRls,
+  type Database,
+} from "@opengeni/db";
+import {
+  hasPermission,
+  organizationWorkspaceInScope,
+  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 authority = await lockActiveExternalOrganizationKeyAuthority(
+    tx,
+    scope.accountId,
+    actor.authenticatingApiKeyId,
+  );
+  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 ||
+    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,90 @@
+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],
+        ...(authorization!.grant.permissionMode === "explicit"
+          ? { permissionMode: "explicit" }
+          : {}),
+      })
+    : 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);
+  };
+}

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

@@ -0,0 +1,232 @@
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import {
+  AddExternalWorkspaceMemberRequest,
+  ExternalIdentityReference,
+  CancelExternalWorkspaceMemberGrantRequest,
+  UpdateExternalWorkspaceMemberRequest,
+  type ExternalIdentity,
+} from "@opengeni/contracts/external-identities";
+import {
+  ensureExternalIdentity,
+  grantWorkspaceAccess,
+  listWorkspaceMembers,
+  lockExternalWorkspaceMembershipLifecycle,
+  requireWorkspace,
+  setRlsContext,
+  withWorkspaceSubjectRls,
+  addExternalWorkspaceMemberOperation,
+  cancelExternalWorkspaceMemberGrant,
+  updateExternalWorkspaceMemberOperation,
+  lookupExternalIdentity,
+  nestedPostgresSqlState,
+} from "@opengeni/db";
+import { organizationMembershipHttpStatus } from "../domain/organization-membership-lifecycle";
+import {
+  accountScopedApiKeyWorkspaceAuthority,
+  hasPermission,
+  requireAccessContext,
+  requireApiKeyDelegationContext,
+  requireFreshAccessGrant,
+  type AccessDeps,
+} from "../access";
+
+/** 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,
+  deps: AccessDeps,
+  workspaceId: string,
+  input: unknown,
+): 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, {
+      message: "external onboarding requires an organization service key",
+    });
+  const grant = await requireFreshAccessGrant(c, deps, workspaceId, "members:manage");
+  if (
+    grant.accountId !== authority.accountId ||
+    payload.permissions.some((permission) => !hasPermission(grant.permissions, permission))
+  ) {
+    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(
+      c,
+      { ...deps, db: tx },
+      workspaceId,
+      "members:manage",
+    );
+    if (
+      live.accountId !== grant.accountId ||
+      live.subjectId !== grant.subjectId ||
+      payload.permissions.some((permission) => !hasPermission(live.permissions, permission))
+    ) {
+      throw new HTTPException(403, { message: "membership authority changed" });
+    }
+    const workspace = await requireWorkspace(tx, workspaceId);
+    if (workspace.kind !== "shared" || workspace.accountId !== authority.accountId)
+      throw new HTTPException(403, {
+        message: "external onboarding requires a shared organization workspace",
+      });
+    const identity = await ensureExternalIdentity(tx, {
+      accountId: authority.accountId,
+      ...payload.identity,
+    });
+    await setRlsContext(tx, { accountId: authority.accountId, workspaceId });
+    const existing = (await listWorkspaceMembers(tx, workspaceId)).find(
+      (member) => member.subjectId === identity.subjectId,
+    );
+    const permissions = [...new Set(payload.permissions)];
+    if (existing) {
+      if (
+        existing.permissions.length !== permissions.length ||
+        existing.permissions.some((permission) => !permissions.includes(permission))
+      ) {
+        throw new HTTPException(409, {
+          message: "existing membership differs; onboarding does not overwrite permissions",
+        });
+      }
+      return identity;
+    }
+    await grantWorkspaceAccess(tx, {
+      accountId: authority.accountId,
+      workspaceId,
+      subjectId: identity.subjectId,
+      role: "member",
+      permissions,
+    });
+    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,
+  workspaceId?: 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",
+    });
+  }
+  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 };
+}
+
+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, workspaceId);
+  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);
+  }
+}
+
+/** 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);
+  }
+}