@govcore/federation 0.2.1 → 0.2.3

package/src/links.ts

@@ -1,328 +0,0 @@
-// @govcore/federation/links — the cross-org content-link lifecycle.
-//
-// A cross-org link is an approved relationship between a content item in one org
-// and one in another. Entity ids carry no FK (they cross org boundaries) and the
-// link semantics are app-defined: `linkType`, `sourceEntityType`/`targetEntityType`
-// are plain strings here. The *source* org proposes a link; only the *target* org
-// approves or rejects it. Entity ownership and federated-visibility preconditions
-// are the caller's responsibility (they live over app-owned content) — this module
-// owns the link record and its transitions. Each transition is audited.
-
-import { and, eq, inArray, or } from 'drizzle-orm'
-import { crossOrgLinks, type GovcoreDb } from '@govcore/schema'
-import { writeAuditLog } from '@govcore/audit'
-
-export type CrossOrgLink = typeof crossOrgLinks.$inferSelect
-
-/** What to do with a link request given any existing link for the same pair. */
-export type LinkRequestAction = 'block' | 'reactivate' | 'create'
-
-/**
- * Pure: a pending/active link blocks a new request; a previously rejected one is
- * reactivated; otherwise a fresh link is created.
- */
-export function resolveLinkRequest(
-  existing: Pick<CrossOrgLink, 'status'> | null | undefined,
-): LinkRequestAction {
-  if (!existing) return 'create'
-  if (existing.status === 'pending' || existing.status === 'active') return 'block'
-  return 'reactivate'
-}
-
-const touchesEntity = (entityType: string, entityId: string) =>
-  or(
-    and(eq(crossOrgLinks.sourceEntityType, entityType), eq(crossOrgLinks.sourceEntityId, entityId)),
-    and(eq(crossOrgLinks.targetEntityType, entityType), eq(crossOrgLinks.targetEntityId, entityId)),
-  )
-
-const betweenOrgs = (orgAId: string, orgBId: string) =>
-  or(
-    and(eq(crossOrgLinks.sourceOrgId, orgAId), eq(crossOrgLinks.targetOrgId, orgBId)),
-    and(eq(crossOrgLinks.sourceOrgId, orgBId), eq(crossOrgLinks.targetOrgId, orgAId)),
-  )
-
-/** All links where `orgId` is either the source or target org. */
-export async function getCrossOrgLinks(db: GovcoreDb, orgId: string): Promise<CrossOrgLink[]> {
-  return db
-    .select()
-    .from(crossOrgLinks)
-    .where(or(eq(crossOrgLinks.sourceOrgId, orgId), eq(crossOrgLinks.targetOrgId, orgId)))
-}
-
-/** All links touching a given entity (on either side). */
-export async function getLinksForEntity(
-  db: GovcoreDb,
-  entityType: string,
-  entityId: string,
-): Promise<CrossOrgLink[]> {
-  return db.select().from(crossOrgLinks).where(touchesEntity(entityType, entityId))
-}
-
-export interface LinkEndpoints {
-  sourceEntityType: string
-  sourceEntityId: string
-  targetEntityType: string
-  targetEntityId: string
-}
-
-/** The existing link for an exact source→target entity pair, or null. */
-export async function findCrossOrgLink(
-  db: GovcoreDb,
-  ends: LinkEndpoints,
-): Promise<CrossOrgLink | null> {
-  const [row] = await db
-    .select()
-    .from(crossOrgLinks)
-    .where(
-      and(
-        eq(crossOrgLinks.sourceEntityType, ends.sourceEntityType),
-        eq(crossOrgLinks.sourceEntityId, ends.sourceEntityId),
-        eq(crossOrgLinks.targetEntityType, ends.targetEntityType),
-        eq(crossOrgLinks.targetEntityId, ends.targetEntityId),
-      ),
-    )
-    .limit(1)
-  return row ?? null
-}
-
-export interface RequestCrossOrgLinkParams extends LinkEndpoints {
-  sourceOrgId: string
-  targetOrgId: string
-  linkType: string
-  actorUserId: string
-}
-
-/**
- * Propose a cross-org link. Blocks if a pending/active link for the pair already
- * exists; reactivates a previously rejected one; otherwise creates a pending
- * link. Audited. Entity ownership/visibility must be validated by the caller.
- */
-export async function requestCrossOrgLink(
-  db: GovcoreDb,
-  params: RequestCrossOrgLinkParams,
-): Promise<CrossOrgLink> {
-  if (params.sourceOrgId === params.targetOrgId) {
-    throw new Error('Use same-org relationships for links within one organization')
-  }
-
-  const existing = await findCrossOrgLink(db, params)
-  const action = resolveLinkRequest(existing)
-  if (action === 'block') {
-    throw new Error('A cross-org link already exists or is awaiting approval')
-  }
-
-  let link: CrossOrgLink
-  if (action === 'reactivate' && existing) {
-    const [row] = await db
-      .update(crossOrgLinks)
-      .set({ linkType: params.linkType, status: 'pending', rejectionReason: null, updatedAt: new Date() })
-      .where(eq(crossOrgLinks.id, existing.id))
-      .returning()
-    link = row
-  } else {
-    const [row] = await db
-      .insert(crossOrgLinks)
-      .values({
-        sourceOrgId: params.sourceOrgId,
-        sourceEntityType: params.sourceEntityType,
-        sourceEntityId: params.sourceEntityId,
-        targetOrgId: params.targetOrgId,
-        targetEntityType: params.targetEntityType,
-        targetEntityId: params.targetEntityId,
-        linkType: params.linkType,
-        status: 'pending',
-        createdBy: params.actorUserId,
-      })
-      .returning()
-    link = row
-  }
-
-  await writeAuditLog(db, {
-    action: 'federation.cross_org_link.request',
-    entityType: 'cross_org_link',
-    entityId: link.id,
-    userId: params.actorUserId,
-    organizationId: params.sourceOrgId,
-    after: {
-      sourceEntityId: params.sourceEntityId,
-      targetEntityId: params.targetEntityId,
-      linkType: params.linkType,
-      targetOrgId: params.targetOrgId,
-    },
-  })
-  return link
-}
-
-/** Internal: a target-org-only status transition with an audit row. */
-async function transitionByTarget(
-  db: GovcoreDb,
-  params: { linkId: string; orgId: string; actorUserId: string; reason?: string },
-  status: 'active' | 'rejected',
-  action: string,
-): Promise<CrossOrgLink> {
-  const [link] = await db
-    .select()
-    .from(crossOrgLinks)
-    .where(and(eq(crossOrgLinks.id, params.linkId), eq(crossOrgLinks.targetOrgId, params.orgId)))
-    .limit(1)
-  if (!link) throw new Error('Cross-org link not found or not authorized')
-  if (link.status !== 'pending') throw new Error('Only pending links can be approved or rejected')
-
-  const [row] = await db
-    .update(crossOrgLinks)
-    .set({
-      status,
-      rejectionReason: status === 'rejected' && params.reason?.trim() ? params.reason.trim() : null,
-      updatedAt: new Date(),
-    })
-    .where(eq(crossOrgLinks.id, params.linkId))
-    .returning()
-
-  await writeAuditLog(db, {
-    action,
-    entityType: 'cross_org_link',
-    entityId: params.linkId,
-    userId: params.actorUserId,
-    organizationId: params.orgId,
-    after: { sourceEntityId: link.sourceEntityId, targetEntityId: link.targetEntityId },
-  })
-  return row
-}
-
-export interface LinkDecisionParams {
-  linkId: string
-  /** The acting org — must be the link's target org. */
-  orgId: string
-  actorUserId: string
-}
-
-/** Approve a pending link. Target org only. Audited. */
-export async function approveCrossOrgLink(
-  db: GovcoreDb,
-  params: LinkDecisionParams,
-): Promise<CrossOrgLink> {
-  return transitionByTarget(db, params, 'active', 'federation.cross_org_link.approve')
-}
-
-/** Reject a pending link with an optional reason. Target org only. Audited. */
-export async function rejectCrossOrgLink(
-  db: GovcoreDb,
-  params: LinkDecisionParams & { reason?: string },
-): Promise<CrossOrgLink> {
-  return transitionByTarget(db, params, 'rejected', 'federation.cross_org_link.reject')
-}
-
-/** Internal: delete a link the acting org owns on the given side, audited. */
-async function deleteOwnedLink(
-  db: GovcoreDb,
-  params: { linkId: string; orgId: string; actorUserId: string; requireActive?: boolean },
-  ownerColumn: typeof crossOrgLinks.sourceOrgId | typeof crossOrgLinks.targetOrgId,
-  action: string,
-): Promise<CrossOrgLink> {
-  const [link] = await db
-    .select()
-    .from(crossOrgLinks)
-    .where(and(eq(crossOrgLinks.id, params.linkId), eq(ownerColumn, params.orgId)))
-    .limit(1)
-  if (!link) throw new Error('Cross-org link not found or not authorized')
-  if (params.requireActive && link.status !== 'active') {
-    throw new Error('Only active links can be revoked')
-  }
-
-  await db.delete(crossOrgLinks).where(eq(crossOrgLinks.id, params.linkId))
-
-  await writeAuditLog(db, {
-    action,
-    entityType: 'cross_org_link',
-    entityId: params.linkId,
-    userId: params.actorUserId,
-    organizationId: params.orgId,
-    before: {
-      sourceEntityId: link.sourceEntityId,
-      targetEntityId: link.targetEntityId,
-      status: link.status,
-    },
-  })
-  return link
-}
-
-/** Withdraw a link the *source* org proposed (any status). Audited. */
-export async function withdrawCrossOrgLink(
-  db: GovcoreDb,
-  params: LinkDecisionParams,
-): Promise<CrossOrgLink> {
-  return deleteOwnedLink(db, params, crossOrgLinks.sourceOrgId, 'federation.cross_org_link.withdraw')
-}
-
-/** Revoke an active link from the *target* org. Audited. */
-export async function revokeCrossOrgLink(
-  db: GovcoreDb,
-  params: LinkDecisionParams,
-): Promise<CrossOrgLink> {
-  return deleteOwnedLink(
-    db,
-    { ...params, requireActive: true },
-    crossOrgLinks.targetOrgId,
-    'federation.cross_org_link.revoke',
-  )
-}
-
-/**
- * Flag every pending/active link touching an entity for review — used when the
- * entity's visibility drops so both orgs are alerted the link may no longer be
- * accessible. Caller must have verified the entity belongs to its org.
- */
-export async function flagLinksForVisibilityDrop(
-  db: GovcoreDb,
-  entityType: string,
-  entityId: string,
-  reason: string,
-): Promise<void> {
-  await db
-    .update(crossOrgLinks)
-    .set({ flaggedForReview: true, flagReason: reason, updatedAt: new Date() })
-    .where(and(touchesEntity(entityType, entityId), inArray(crossOrgLinks.status, ['pending', 'active'])))
-}
-
-/** Clear review flags on an entity's links — used when visibility is raised back. */
-export async function clearLinksFlag(
-  db: GovcoreDb,
-  entityType: string,
-  entityId: string,
-): Promise<void> {
-  await db
-    .update(crossOrgLinks)
-    .set({ flaggedForReview: false, flagReason: null, updatedAt: new Date() })
-    .where(and(touchesEntity(entityType, entityId), eq(crossOrgLinks.flaggedForReview, true)))
-}
-
-/**
- * Delete every cross-org link between two orgs — called when their connection is
- * removed. Audits a snapshot of the removed links (when any) under the actor.
- * Returns the removed rows.
- */
-export async function removeLinksForConnection(
-  db: GovcoreDb,
-  orgAId: string,
-  orgBId: string,
-  actorUserId: string,
-  actorOrgId: string,
-): Promise<CrossOrgLink[]> {
-  const affected = await db.select().from(crossOrgLinks).where(betweenOrgs(orgAId, orgBId))
-  if (affected.length === 0) return []
-
-  await db.delete(crossOrgLinks).where(betweenOrgs(orgAId, orgBId))
-
-  await writeAuditLog(db, {
-    action: 'federation.cross_org_link.remove_for_connection',
-    entityType: 'org_connection',
-    userId: actorUserId,
-    organizationId: actorOrgId,
-    before: {
-      orgAId,
-      orgBId,
-      removedLinkIds: affected.map((l) => l.id),
-    },
-  })
-  return affected
-}

package/src/visibility.ts

@@ -1,110 +0,0 @@
-// @govcore/federation/visibility — federated read scoping.
-//
-// Content rows carry a `visibility` (org | connections | instance). A list query
-// is scoped to the caller's org by default; broadening to `federated` also pulls
-// in instance-wide rows and rows owned by a *connected* org whose visibility
-// permits it. These helpers build the query condition and answer single-row
-// read checks; the content tables themselves are app-owned (content is a later
-// milestone), so callers pass the columns.
-
-import { and, eq, inArray, or, type SQL } from 'drizzle-orm'
-import type { AnyPgColumn } from 'drizzle-orm/pg-core'
-import { orgConnections, type GovcoreDb } from '@govcore/schema'
-
-/** A content row's visibility vocabulary (mirrors the `visibility` schema enum). */
-export type FederationVisibility = 'org' | 'connections' | 'instance'
-
-/**
- * List-view scope. `org` (default) restricts to the caller's own org;
- * `federated` is an explicit, user-requested broadening so list queries never
- * silently fan out across every visible org.
- */
-export type ListScope = 'org' | 'federated'
-
-/** Coerce a raw query-string value into a ListScope, defaulting to `org`. */
-export function parseListScope(value: string | string[] | undefined): ListScope {
-  return value === 'federated' ? 'federated' : 'org'
-}
-
-/**
- * Build the visibility WHERE condition for an org-scoped list query.
- *
- * - `org` scope → only rows owned by `orgId`.
- * - `federated` scope → owned rows, plus instance-wide rows, plus
- *   connections/instance rows owned by a connected org.
- *
- * Pass `connectedOrgIds` empty under `org` scope (callers should skip the
- * connected-org lookup there). Compose with any status filter via `and(...)`.
- */
-export function listScopeFilter(
-  cols: { organizationId: AnyPgColumn; visibility: AnyPgColumn },
-  opts: { orgId: string; scope: ListScope; connectedOrgIds?: string[] },
-): SQL {
-  const base = eq(cols.organizationId, opts.orgId)
-  if (opts.scope === 'org') return base
-
-  const instanceWide = eq(cols.visibility, 'instance')
-  const connectedOrgIds = opts.connectedOrgIds ?? []
-  if (connectedOrgIds.length === 0) return or(base, instanceWide)!
-  return or(
-    base,
-    instanceWide,
-    and(
-      inArray(cols.organizationId, connectedOrgIds),
-      inArray(cols.visibility, ['connections', 'instance']),
-    ),
-  )!
-}
-
-/**
- * Throw if an entity's owning org doesn't match the caller's. Use before any
- * write to content fetched without an org filter.
- */
-export function assertOwnership(
-  entityOrgId: string | null | undefined,
-  callerOrgId: string,
-): void {
-  if (!entityOrgId || entityOrgId !== callerOrgId) {
-    throw new Error('Forbidden: content owned by another organization')
-  }
-}
-
-/** Org IDs with an *active* bilateral connection to `organizationId` (either direction). */
-export async function getConnectedOrgIds(
-  db: GovcoreDb,
-  organizationId: string,
-): Promise<string[]> {
-  const rows = await db
-    .select({ fromOrgId: orgConnections.fromOrgId, toOrgId: orgConnections.toOrgId })
-    .from(orgConnections)
-    .where(
-      and(
-        or(
-          eq(orgConnections.fromOrgId, organizationId),
-          eq(orgConnections.toOrgId, organizationId),
-        ),
-        eq(orgConnections.status, 'active'),
-      ),
-    )
-  return rows.map((r) => (r.fromOrgId === organizationId ? r.toOrgId : r.fromOrgId))
-}
-
-/**
- * Whether `callerOrgId` may read a single entity given its owning org and
- * visibility. Own-org always; `instance` always; `connections` only when an
- * active connection exists. A null org/visibility is unreadable.
- */
-export async function canReadFederatedEntity(
-  db: GovcoreDb,
-  entityOrgId: string | null | undefined,
-  visibility: FederationVisibility | null | undefined,
-  callerOrgId: string,
-): Promise<boolean> {
-  if (!entityOrgId || !visibility) return false
-  if (entityOrgId === callerOrgId) return true
-  if (visibility === 'instance') return true
-  if (visibility !== 'connections') return false
-
-  const connectedOrgIds = await getConnectedOrgIds(db, callerOrgId)
-  return connectedOrgIds.includes(entityOrgId)
-}