Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import type { DbClient } from '../db.js'
import {
type ControlApiPermissionChange,
appendControlApiPermissionEventsInTransaction,
} from './tracing/controlApiPermissionEvents.js'
export const GFS_DESKTOP_OPERATOR_LINK_SOURCES = ['initial_setup'] as const
export type GfsDesktopOperatorLinkSource = (typeof GFS_DESKTOP_OPERATOR_LINK_SOURCES)[number]
export type GfsDesktopOperatorLink = {
id?: string
lineageId?: string
generation?: number
predecessorId?: string | null
desktopUserId: string
controlAdminId: string
source: GfsDesktopOperatorLinkSource
/** Current parent generations read from the same authoritative snapshot. */
desktopUserGeneration?: number
controlAdminGeneration?: number
state?: 'active' | 'revoked'
rowVersion?: number
createdAt: Date
revokedAt?: Date | null
revocationReason?: string | null
}
export type GfsDesktopOperatorLinkErrorCode =
| 'invalid_input'
| 'desktop_user_not_found'
| 'desktop_user_retired'
| 'control_admin_not_found'
| 'control_admin_inactive'
| 'link_conflict'
| 'malformed_link'
| 'resolution_failed'
export type GfsDesktopOperatorLinkConflictIdentity = 'desktop_user' | 'control_admin' | 'both'
export class GfsDesktopOperatorLinkError extends Error {
readonly code: GfsDesktopOperatorLinkErrorCode
readonly conflictIdentity: GfsDesktopOperatorLinkConflictIdentity | null
constructor(
code: GfsDesktopOperatorLinkErrorCode,
message: string,
options?: {
cause?: unknown
conflictIdentity?: GfsDesktopOperatorLinkConflictIdentity
}
) {
super(message, options?.cause === undefined ? undefined : { cause: options.cause })
this.name = 'GfsDesktopOperatorLinkError'
this.code = code
this.conflictIdentity = options?.conflictIdentity ?? null
}
}
export type LinkGfsDesktopOperatorInput = {
desktopUserId: string
controlAdminId: string
source: GfsDesktopOperatorLinkSource
/** Authenticated Control Admin responsible for this lifecycle mutation. */
operatorSub: string
/** Request correlation for the governed lifecycle event. */
requestId?: string | null
}
export type UnlinkGfsDesktopOperatorInput = {
desktopUserId: string
controlAdminId: string
/** Authenticated Control Admin responsible for this lifecycle mutation. */
operatorSub: string
/** Optimistic-concurrency token returned by the Control UI read surface. */
rowVersion?: number
reason?: string
/** Request correlation for the governed lifecycle event. */
requestId?: string | null
}
export type ReactivateGfsDesktopOperatorInput = {
controlAdminId: string
operatorSub: string
/** The revoked generation being reactivated; prevents stale UI writes. */
rowVersion: number
reason: string
/** Request correlation for the governed lifecycle event. */
requestId?: string | null
}
export type LinkGfsDesktopOperatorResult = {
created: boolean
link: GfsDesktopOperatorLink
}
export type UnlinkGfsDesktopOperatorResult =
| { unlinked: false; link: null }
| { unlinked: true; link: GfsDesktopOperatorLink }
export type ReactivateGfsDesktopOperatorResult = {
reactivated: boolean
link: GfsDesktopOperatorLink | null
}
export type GfsDesktopOperatorParentKind = 'desktop_user' | 'control_admin'
/**
* Lifecycle callers name their principal explicitly. The two actor IDs are
* deliberately separate so a UUID is never reinterpreted as another kind.
*/
export type GfsDesktopOperatorLifecycleActor =
| { kind: 'control_admin'; controlAdminId: string }
| { kind: 'platform_user'; desktopUserId: string }
type TransactionRunner = <T>(work: (db: DbClient) => Promise<T>) => Promise<T>
/**
* Keep the singleton import-safe for callers that mock only the read-side DB
* pool. The production transaction primitive remains `db.withTransaction`;
* resolving it only when a link mutation is actually requested avoids making
* unrelated route modules provide a transaction mock merely by importing the
* directory barrel.
*/
const defaultTransaction: TransactionRunner = async work => {
const { withTransaction } = await import('../db.js')
return withTransaction(work)
}
const defaultReadDb: Pick<DbClient, 'query'> = {
query: (text, values) => import('../db.js').then(({ pool }) => pool.query(text, values)),
}
type GfsDesktopOperatorLinkServiceDependencies = {
transaction: TransactionRunner
readDb: Pick<DbClient, 'query'>
appendPermissionEvents: typeof appendControlApiPermissionEventsInTransaction
}
type StoredLinkRow = {
id?: unknown
lineage_id?: unknown
generation?: unknown
predecessor_id?: unknown
row_version?: unknown
state?: unknown
revoked_at?: unknown
revocation_reason?: unknown
user_id: unknown
control_admin_id: unknown
source: unknown
created_at: unknown
desktop_user_lifecycle_state?: unknown
desktop_user_lifecycle_version?: unknown
control_admin_session_version?: unknown
}
function requireRowVersion(value: unknown): number {
const normalized =
typeof value === 'number'
? value
: typeof value === 'string' && /^\d+$/.test(value.trim())
? Number(value)
: Number.NaN
if (!Number.isSafeInteger(normalized) || normalized < 1) {
throw new GfsDesktopOperatorLinkError('invalid_input', 'rowVersion must be a positive integer')
}
return normalized
}
function requireGeneration(value: unknown): number {
const normalized =
typeof value === 'number'
? value
: typeof value === 'string' && /^\d+$/.test(value.trim())
? Number(value)
: Number.NaN
if (!Number.isSafeInteger(normalized) || normalized < 0) {
throw new GfsDesktopOperatorLinkError('malformed_link', 'parent generation is malformed')
}
return normalized
}
function requireReason(value: unknown): string {
const reason = String(value || '').trim()
if (!reason || reason.length > 512) {
throw new GfsDesktopOperatorLinkError(
'invalid_input',
'reason is required and must be at most 512 characters'
)
}
return reason
}
type ResolvedLinkRow = StoredLinkRow & {
desktop_user_exists?: unknown
desktop_user_lifecycle_state?: unknown
desktop_user_lifecycle_version?: unknown
control_admin_exists?: unknown
control_admin_status?: unknown
control_admin_session_version?: unknown
}
const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
function requireUuid(value: string, field: string): string {
const normalized = String(value || '')
.trim()
.toLowerCase()
if (!UUID_PATTERN.test(normalized)) {
throw new GfsDesktopOperatorLinkError('invalid_input', `${field} must be a UUID`)
}
return normalized
}
function requireLifecycleActor(
input: GfsDesktopOperatorLifecycleActor
): GfsDesktopOperatorLifecycleActor {
if (!input || typeof input !== 'object') {
throw new GfsDesktopOperatorLinkError('invalid_input', 'actor is required')
}
if (input.kind === 'control_admin') {
return {
kind: 'control_admin',
controlAdminId: requireUuid(input.controlAdminId, 'actor.controlAdminId'),
}
}
if (input.kind === 'platform_user') {
return {
kind: 'platform_user',
desktopUserId: requireUuid(input.desktopUserId, 'actor.desktopUserId'),
}
}
throw new GfsDesktopOperatorLinkError('invalid_input', 'actor kind is not supported')
}
function lifecycleActorId(actor: GfsDesktopOperatorLifecycleActor): string {
return actor.kind === 'control_admin' ? actor.controlAdminId : actor.desktopUserId
}
function isLinkSource(value: unknown): value is GfsDesktopOperatorLinkSource {
return (
typeof value === 'string' &&
(GFS_DESKTOP_OPERATOR_LINK_SOURCES as readonly string[]).includes(value)
)
}
function requireSource(value: unknown): GfsDesktopOperatorLinkSource {
if (!isLinkSource(value)) {
throw new GfsDesktopOperatorLinkError(
'invalid_input',
'source is not a supported GFS Desktop operator-link source'
)
}
return value
}
function mapStoredLink(row: unknown): GfsDesktopOperatorLink {
if (!row || typeof row !== 'object') {
throw new GfsDesktopOperatorLinkError('malformed_link', 'operator-link row is malformed')
}
const stored = row as StoredLinkRow
const desktopUserId =
typeof stored.user_id === 'string' && UUID_PATTERN.test(stored.user_id)
? stored.user_id.toLowerCase()
: null
const controlAdminId =
typeof stored.control_admin_id === 'string' && UUID_PATTERN.test(stored.control_admin_id)
? stored.control_admin_id.toLowerCase()
: null
const createdAt = stored.created_at instanceof Date ? stored.created_at : null
if (
!desktopUserId ||
!controlAdminId ||
!isLinkSource(stored.source) ||
!createdAt ||
!Number.isFinite(createdAt.getTime())
) {
throw new GfsDesktopOperatorLinkError('malformed_link', 'operator-link row is malformed')
}
const id =
stored.id === undefined || stored.id === null ? undefined : requireUuid(String(stored.id), 'id')
const lineageId =
stored.lineage_id === undefined || stored.lineage_id === null
? undefined
: requireUuid(String(stored.lineage_id), 'lineageId')
const predecessorId =
stored.predecessor_id === undefined || stored.predecessor_id === null
? null
: requireUuid(String(stored.predecessor_id), 'predecessorId')
const generation =
stored.generation === undefined || stored.generation === null
? undefined
: requireRowVersion(stored.generation)
const rowVersion =
stored.row_version === undefined || stored.row_version === null
? undefined
: requireRowVersion(stored.row_version)
const state = stored.state === undefined || stored.state === null ? undefined : stored.state
if (state !== undefined && state !== 'active' && state !== 'revoked') {
throw new GfsDesktopOperatorLinkError('malformed_link', 'operator-link state is malformed')
}
const revokedAt =
stored.revoked_at === undefined || stored.revoked_at === null
? null
: stored.revoked_at instanceof Date
? stored.revoked_at
: null
if (stored.revoked_at !== undefined && stored.revoked_at !== null && !revokedAt) {
throw new GfsDesktopOperatorLinkError(
'malformed_link',
'operator-link revocation timestamp is malformed'
)
}
const desktopUserGeneration =
stored.desktop_user_lifecycle_version === undefined ||
stored.desktop_user_lifecycle_version === null
? undefined
: requireGeneration(stored.desktop_user_lifecycle_version)
const controlAdminGeneration =
stored.control_admin_session_version === undefined ||
stored.control_admin_session_version === null
? undefined
: requireGeneration(stored.control_admin_session_version)
return {
...(id ? { id } : {}),
...(lineageId ? { lineageId } : {}),
...(generation === undefined ? {} : { generation }),
...(stored.predecessor_id === undefined ? {} : { predecessorId }),
desktopUserId,
controlAdminId,
source: stored.source,
...(desktopUserGeneration === undefined ? {} : { desktopUserGeneration }),
...(controlAdminGeneration === undefined ? {} : { controlAdminGeneration }),
...(state === undefined ? {} : { state }),
...(rowVersion === undefined ? {} : { rowVersion }),
createdAt,
...(stored.revoked_at === undefined ? {} : { revokedAt }),
...(stored.revocation_reason === undefined
? {}
: { revocationReason: stored.revocation_reason as string | null }),
}
}
function lifecycleChange(
action: 'grant' | 'revoke',
link: GfsDesktopOperatorLink,
reason?: string,
lifecycleEvent?: 'link.created' | 'link.revoked' | 'link.reactivated' | 'parent.retired',
actor?: GfsDesktopOperatorLifecycleActor
): ControlApiPermissionChange {
return {
action,
resourceClass: 'gfs_desktop_operator_link',
resourceRef: `gfs_desktop_operator_link:${link.desktopUserId}:${link.controlAdminId}`,
subject: { kind: 'user', id: link.desktopUserId },
sourceAuditRef: `gfs_desktop_operator_link_source:${link.source}`,
status: action === 'grant' ? 'linked' : 'unlinked',
detailRef: [
lifecycleEvent ? `event:${lifecycleEvent}` : null,
`desktop_user_id:${link.desktopUserId}`,
`control_admin_id:${link.controlAdminId}`,
`source:${link.source}`,
link.lineageId ? `lineage_id:${link.lineageId}` : null,
link.generation === undefined ? null : `generation:${link.generation}`,
link.predecessorId ? `predecessor_id:${link.predecessorId}` : null,
actor ? `actor_type:${actor.kind}` : null,
actor?.kind === 'control_admin' ? `actor_control_admin_id:${actor.controlAdminId}` : null,
actor?.kind === 'platform_user' ? `actor_desktop_user_id:${actor.desktopUserId}` : null,
reason ? `reason:${reason}` : null,
]
.filter(Boolean)
.join(';'),
}
}
function mapActiveResolvedLink(
row: ResolvedLinkRow,
expected: { desktopUserId?: string; controlAdminId?: string }
): GfsDesktopOperatorLink {
const link = mapStoredLink(row)
if (
(expected.desktopUserId && link.desktopUserId !== expected.desktopUserId) ||
(expected.controlAdminId && link.controlAdminId !== expected.controlAdminId)
) {
throw new GfsDesktopOperatorLinkError(
'malformed_link',
'operator-link lookup returned a different identity'
)
}
if (row.desktop_user_exists !== true) {
throw new GfsDesktopOperatorLinkError(
'malformed_link',
'operator link references a missing Desktop user'
)
}
if (row.desktop_user_lifecycle_state !== 'active') {
throw new GfsDesktopOperatorLinkError(
'desktop_user_retired',
'linked Desktop user is not active'
)
}
if (row.control_admin_exists !== true) {
throw new GfsDesktopOperatorLinkError(
'control_admin_not_found',
'operator link references a missing Control Admin'
)
}
if (row.control_admin_status !== 'active') {
throw new GfsDesktopOperatorLinkError(
'control_admin_inactive',
'linked Control Admin is not active'
)
}
return link
}
/**
* Owns the persisted one-to-one GFS Desktop operator-link lifecycle.
*
* Link mutations are serialized by locking both exact identity rows before the
* relationship is rechecked. Lifecycle events share the caller's transaction,
* so a missing event can never leave behind a committed current-state link.
*/
export class GfsDesktopOperatorLinkService {
private readonly dependencies: GfsDesktopOperatorLinkServiceDependencies
constructor(dependencies: Partial<GfsDesktopOperatorLinkServiceDependencies> = {}) {
this.dependencies = {
transaction: dependencies.transaction ?? defaultTransaction,
readDb: dependencies.readDb ?? defaultReadDb,
appendPermissionEvents:
dependencies.appendPermissionEvents ?? appendControlApiPermissionEventsInTransaction,
}
}
async link(input: LinkGfsDesktopOperatorInput): Promise<LinkGfsDesktopOperatorResult> {
return this.dependencies.transaction(db => this.linkInTransaction(db, input))
}
/** Caller-owned transaction seam used by initial Desktop provisioning. */
async linkInTransaction(
db: DbClient,
input: LinkGfsDesktopOperatorInput
): Promise<LinkGfsDesktopOperatorResult> {
const desktopUserId = requireUuid(input.desktopUserId, 'desktopUserId')
const controlAdminId = requireUuid(input.controlAdminId, 'controlAdminId')
const operatorSub = requireUuid(input.operatorSub, 'operatorSub')
const source = requireSource(input.source)
const user = await db.query(
`SELECT id::text AS id, lifecycle_state
FROM users
WHERE id = $1::uuid
FOR UPDATE`,
[desktopUserId]
)
if (user.rows.length !== 1) {
throw new GfsDesktopOperatorLinkError('desktop_user_not_found', 'Desktop user does not exist')
}
if ((user.rows[0] as { lifecycle_state?: unknown }).lifecycle_state === 'retired') {
throw new GfsDesktopOperatorLinkError(
'desktop_user_retired',
'retired Desktop users cannot receive an operator link'
)
}
const admin = await db.query(
`SELECT id::text AS id, status
FROM control_admin_users
WHERE id = $1::uuid
FOR UPDATE`,
[controlAdminId]
)
if (admin.rows.length !== 1) {
throw new GfsDesktopOperatorLinkError(
'control_admin_not_found',
'Control Admin does not exist'
)
}
const adminStatus = (admin.rows[0] as { status?: unknown }).status
if (adminStatus !== 'active') {
throw new GfsDesktopOperatorLinkError('control_admin_inactive', 'Control Admin is not active')
}
const current = await db.query(
`SELECT id::text AS id, lineage_id::text AS lineage_id, generation,
predecessor_id::text AS predecessor_id, state, row_version,
revoked_at, revocation_reason,
user_id::text AS user_id,
control_admin_id::text AS control_admin_id,
source,
created_at
FROM gfs_desktop_operator_links
WHERE (user_id = $1::uuid
OR control_admin_id = $2::uuid)
ORDER BY user_id::text, control_admin_id::text
FOR UPDATE`,
[desktopUserId, controlAdminId]
)
const links = current.rows.map(mapStoredLink)
const activeLinks = links.filter(link => link.state === undefined || link.state === 'active')
const revokedLinks = links.filter(link => link.state === 'revoked')
const exact = activeLinks.find(
link => link.desktopUserId === desktopUserId && link.controlAdminId === controlAdminId
)
if (exact && activeLinks.length === 1) return { created: false, link: exact }
if (exact || activeLinks.length > 2) {
throw new GfsDesktopOperatorLinkError(
'malformed_link',
'operator-link uniqueness invariant is violated'
)
}
const desktopUserConflict = activeLinks.some(link => link.desktopUserId === desktopUserId)
const controlAdminConflict = activeLinks.some(link => link.controlAdminId === controlAdminId)
if (desktopUserConflict || controlAdminConflict) {
const conflictIdentity: GfsDesktopOperatorLinkConflictIdentity =
desktopUserConflict && controlAdminConflict
? 'both'
: desktopUserConflict
? 'desktop_user'
: 'control_admin'
throw new GfsDesktopOperatorLinkError(
'link_conflict',
'GFS Desktop operator link conflicts with an existing identity assignment',
{ conflictIdentity }
)
}
if (revokedLinks.length > 0) {
throw new GfsDesktopOperatorLinkError(
'link_conflict',
'GFS Desktop operator-link history already exists; use explicit reactivation'
)
}
const inserted = await db.query(
`INSERT INTO gfs_desktop_operator_links(id, lineage_id, generation, user_id, control_admin_id, state, source, created_by, row_version)
VALUES(gen_random_uuid(), gen_random_uuid(), 1, $1::uuid, $2::uuid, 'active', $3, $4::uuid, 1)
RETURNING id::text AS id, lineage_id::text AS lineage_id, generation,
state, row_version,
user_id::text AS user_id,
control_admin_id::text AS control_admin_id,
source,
created_at`,
[desktopUserId, controlAdminId, source, operatorSub]
)
if (inserted.rows.length !== 1) {
throw new GfsDesktopOperatorLinkError(
'malformed_link',
'operator-link insert did not return exactly one row'
)
}
const link = mapStoredLink(inserted.rows[0])
await this.dependencies.appendPermissionEvents(db, {
operatorSub,
operatorKind: 'control_admin',
requestId: input.requestId,
changes: [lifecycleChange('grant', link, undefined, 'link.created')],
})
return { created: true, link }
}
async unlink(input: UnlinkGfsDesktopOperatorInput): Promise<UnlinkGfsDesktopOperatorResult> {
const desktopUserId = requireUuid(input.desktopUserId, 'desktopUserId')
const controlAdminId = requireUuid(input.controlAdminId, 'controlAdminId')
const operatorSub = requireUuid(input.operatorSub, 'operatorSub')
return this.dependencies.transaction(async db => {
const current = await db.query(
`SELECT id::text AS id, lineage_id::text AS lineage_id, generation,
predecessor_id::text AS predecessor_id, state, row_version,
revoked_at, revocation_reason,
user_id::text AS user_id,
control_admin_id::text AS control_admin_id,
source,
created_at
FROM gfs_desktop_operator_links
WHERE (user_id = $1::uuid
OR control_admin_id = $2::uuid)
AND state = 'active'
ORDER BY user_id::text, control_admin_id::text
FOR UPDATE`,
[desktopUserId, controlAdminId]
)
if (current.rows.length === 0) return { unlinked: false as const, link: null }
const links = current.rows.map(mapStoredLink)
const exact = links.find(
link => link.desktopUserId === desktopUserId && link.controlAdminId === controlAdminId
)
if (!exact || links.length !== 1) {
throw new GfsDesktopOperatorLinkError(
'link_conflict',
'requested GFS Desktop operator pair does not match current linkage',
{
conflictIdentity:
links.some(link => link.desktopUserId === desktopUserId) &&
links.some(link => link.controlAdminId === controlAdminId)
? 'both'
: links.some(link => link.desktopUserId === desktopUserId)
? 'desktop_user'
: 'control_admin',
}
)
}
const rowVersion =
input.rowVersion === undefined
? exact.rowVersion === undefined
? 1
: exact.rowVersion
: requireRowVersion(input.rowVersion)
const reason = input.reason === undefined ? 'operator_revoked' : requireReason(input.reason)
// Evidence is appended before the immutable generation is revoked. Both
// operations still commit atomically because they share this transaction.
await this.dependencies.appendPermissionEvents(db, {
operatorSub,
operatorKind: 'control_admin',
requestId: input.requestId,
changes: [lifecycleChange('revoke', exact, reason, 'link.revoked')],
})
const removed = await db.query(
`UPDATE gfs_desktop_operator_links
SET state = 'revoked',
revoked_at = NOW(),
revoked_by_type = 'control_admin',
revoked_by_id = $3::uuid,
revoked_by_control_admin_id = $3::uuid,
revoked_by_desktop_user_id = NULL,
revocation_reason = $4,
row_version = row_version + 1
WHERE user_id = $1::uuid
AND control_admin_id = $2::uuid
AND state = 'active'
AND row_version = $5`,
[desktopUserId, controlAdminId, operatorSub, reason, rowVersion]
)
if (removed.rowCount !== 1) {
throw new GfsDesktopOperatorLinkError(
'malformed_link',
'operator-link was changed by another request'
)
}
return {
unlinked: true as const,
link: {
...exact,
state: 'revoked' as const,
rowVersion: rowVersion + 1,
revokedAt: new Date(),
revocationReason: reason,
},
}
})
}
/**
* Reactivation always creates a successor generation; the revoked row is
* retained as the predecessor and is never modified again.
*/
async reactivate(
input: ReactivateGfsDesktopOperatorInput
): Promise<ReactivateGfsDesktopOperatorResult> {
const controlAdminId = requireUuid(input.controlAdminId, 'controlAdminId')
const operatorSub = requireUuid(input.operatorSub, 'operatorSub')
const rowVersion = requireRowVersion(input.rowVersion)
const reason = requireReason(input.reason)
return this.dependencies.transaction(async db => {
// A replay after a committed reactivation is idempotent. Lock the active
// row before reading the tombstone so no second successor can be made.
const active = await db.query(
`SELECT id::text AS id, lineage_id::text AS lineage_id, generation,
predecessor_id::text AS predecessor_id, state, row_version,
user_id::text AS user_id, control_admin_id::text AS control_admin_id,
source, created_at
FROM gfs_desktop_operator_links
WHERE control_admin_id = $1::uuid AND state = 'active'
LIMIT 1 FOR UPDATE`,
[controlAdminId]
)
if (active.rows.length === 1) {
const activeLink = mapStoredLink(active.rows[0])
// A replay is idempotent only when it names the tombstone that
// produced the currently active successor. A stale request for a
// different generation must not be silently accepted.
if (!activeLink.predecessorId) {
return { reactivated: false, link: activeLink }
}
const predecessor = await db.query(
`SELECT state, row_version
FROM gfs_desktop_operator_links
WHERE id = $1::uuid
FOR UPDATE`,
[activeLink.predecessorId]
)
const predecessorRow = predecessor.rows[0] as
| { state?: unknown; row_version?: unknown }
| undefined
if (
predecessorRow?.state !== 'revoked' ||
requireRowVersion(predecessorRow.row_version) !== rowVersion
) {
throw new GfsDesktopOperatorLinkError(
'link_conflict',
'operator-link reactivation replay is stale'
)
}
return { reactivated: true, link: activeLink }
}
const prior = await db.query(
`SELECT id::text AS id, lineage_id::text AS lineage_id, generation,
predecessor_id::text AS predecessor_id, state, row_version, revoked_at,
revocation_reason, user_id::text AS user_id, control_admin_id::text AS control_admin_id,
source, created_at
FROM gfs_desktop_operator_links
WHERE control_admin_id = $1::uuid AND state = 'revoked'
ORDER BY generation DESC
LIMIT 1 FOR UPDATE`,
[controlAdminId]
)
if (prior.rows.length === 0) return { reactivated: false, link: null }
const previous = prior.rows[0] as StoredLinkRow
const link = mapStoredLink(previous)
if (requireRowVersion(previous.row_version) !== rowVersion) {
throw new GfsDesktopOperatorLinkError(
'link_conflict',
'operator-link was changed by another request'
)
}
const predecessorId = requireUuid(String(previous.id || ''), 'predecessorId')
const lineageId = requireUuid(String(previous.lineage_id || ''), 'lineageId')
const generation = requireRowVersion(previous.generation) + 1
const parents = await db.query(
`SELECT u.id IS NOT NULL AS desktop_user_exists,
u.lifecycle_state AS desktop_user_lifecycle_state,
a.status AS control_admin_status
FROM users u CROSS JOIN control_admin_users a
WHERE u.id = $1::uuid AND a.id = $2::uuid
FOR UPDATE`,
[link.desktopUserId, controlAdminId]
)
const parentState = parents.rows[0] as
| {
desktop_user_exists?: unknown
desktop_user_lifecycle_state?: unknown
control_admin_status?: unknown
}
| undefined
if (parentState?.desktop_user_exists !== true) {
throw new GfsDesktopOperatorLinkError(
'desktop_user_not_found',
'Desktop user does not exist'
)
}
if (parentState.desktop_user_lifecycle_state === 'retired') {
throw new GfsDesktopOperatorLinkError(
'desktop_user_retired',
'retired Desktop users cannot receive an operator link'
)
}
if (parentState.control_admin_status !== 'active') {
throw new GfsDesktopOperatorLinkError(
'control_admin_inactive',
'Control Admin is not active'
)
}
const inserted = await db.query(
`INSERT INTO gfs_desktop_operator_links
(id, lineage_id, generation, predecessor_id, user_id, control_admin_id, state, source, created_by, row_version)
VALUES (gen_random_uuid(), $1::uuid, $2, $3::uuid, $4::uuid, $5::uuid, 'active', 'initial_setup', $6::uuid, 1)
RETURNING id::text AS id, lineage_id::text AS lineage_id, generation,
predecessor_id::text AS predecessor_id, state, row_version,
user_id::text AS user_id, control_admin_id::text AS control_admin_id,
source, created_at`,
[lineageId, generation, predecessorId, link.desktopUserId, controlAdminId, operatorSub]
)
const successor = mapStoredLink(inserted.rows[0])
await this.dependencies.appendPermissionEvents(db, {
operatorSub,
operatorKind: 'control_admin',
requestId: input.requestId,
changes: [lifecycleChange('grant', successor, reason, 'link.reactivated')],
})
return { reactivated: true, link: successor }
})
}
/** Shared parent-retirement seam: evidence precedes every tombstone update. */
async retireParentInTransaction(
db: DbClient,
input: {
kind: GfsDesktopOperatorParentKind
parentId: string
actor: GfsDesktopOperatorLifecycleActor
reason: string
requestId?: string | null
/** Reuses the retirement-operation id as the governed audit operation. */
operationId?: string
}
): Promise<boolean> {
const parentId = requireUuid(input.parentId, 'parentId')
const actor = requireLifecycleActor(input.actor)
const operatorSub = lifecycleActorId(actor)
const reason = requireReason(input.reason)
const column = input.kind === 'desktop_user' ? 'user_id' : 'control_admin_id'
const rows = await db.query(
`SELECT id::text AS id, lineage_id::text AS lineage_id, generation,
predecessor_id::text AS predecessor_id, state, row_version,
revoked_at, revocation_reason,
user_id::text AS user_id, control_admin_id::text AS control_admin_id,
source, created_at
FROM gfs_desktop_operator_links
WHERE ${column} = $1::uuid
ORDER BY generation DESC
LIMIT 1 FOR UPDATE`,
[parentId]
)
if (rows.rows.length === 0) return false
const link = mapStoredLink(rows.rows[0])
const parentRetiredChange = {
action: 'revoke' as const,
resourceClass: `gfs_desktop_operator_${input.kind}`,
resourceRef: `${input.kind}:${parentId}`,
subject:
input.kind === 'desktop_user'
? { kind: 'user' as const, id: parentId }
: {
// The 'operator' principal kind carries no id: the canonical ref
// is the literal 'operator:' everywhere one is disclosed
// (traceSafeFieldProjection.ts, the db.ts CHECK, append.ts's
// canonical-prefix check, subjectKey() in routes/gfs/grants.ts,
// routes/external/gfs.ts:231). The retired control admin's id is
// still fully recorded in detailRef below.
kind: 'service' as const,
id: 'operator:',
principalKind: 'operator' as const,
},
sourceAuditRef: `gfs_desktop_operator_link_source:${link.source}`,
status: 'retired',
detailRef: [
'event:parent.retired',
`desktop_user_id:${link.desktopUserId}`,
`control_admin_id:${link.controlAdminId}`,
`source:${link.source}`,
`actor_type:${actor.kind}`,
actor.kind === 'control_admin'
? `actor_control_admin_id:${actor.controlAdminId}`
: `actor_desktop_user_id:${actor.desktopUserId}`,
`reason:${reason}`,
].join(';'),
}
await this.dependencies.appendPermissionEvents(db, {
operatorSub,
operatorKind: actor.kind,
requestId: input.requestId,
operationId: input.operationId,
changes:
link.state === 'revoked'
? [parentRetiredChange]
: [lifecycleChange('revoke', link, reason, 'link.revoked', actor), parentRetiredChange],
})
// A prior Control UI revoke already created the immutable tombstone. The
// parent can still be retired afterwards; preserve that history and emit
// only the missing parent.retired evidence without creating a generation.
if (link.state === 'revoked') return true
const updated = await db.query(
`UPDATE gfs_desktop_operator_links
SET state = 'revoked',
revoked_at = NOW(),
revoked_by_type = $2,
revoked_by_id = $3::uuid,
revoked_by_control_admin_id = $4::uuid,
revoked_by_desktop_user_id = $5::uuid,
revocation_reason = $6,
row_version = row_version + 1
WHERE ${column} = $1::uuid AND state = 'active' AND row_version = $7`,
[
parentId,
actor.kind,
actor.kind === 'control_admin' ? actor.controlAdminId : null,
actor.kind === 'control_admin' ? actor.controlAdminId : null,
actor.kind === 'platform_user' ? actor.desktopUserId : null,
reason,
link.rowVersion ?? 1,
]
)
if (updated.rowCount !== 1)
throw new GfsDesktopOperatorLinkError(
'link_conflict',
'parent link changed during retirement'
)
return true
}
async resolveActiveLink(desktopUserIdInput: string): Promise<GfsDesktopOperatorLink | null> {
const desktopUserId = requireUuid(desktopUserIdInput, 'desktopUserId')
try {
const result = await this.dependencies.readDb.query(
`SELECT links.id::text AS id, links.lineage_id::text AS lineage_id,
links.generation, links.predecessor_id::text AS predecessor_id,
links.state, links.row_version, links.revoked_at, links.revocation_reason,
links.user_id::text AS user_id,
links.control_admin_id::text AS control_admin_id,
links.source,
links.created_at,
users.id IS NOT NULL AS desktop_user_exists,
users.lifecycle_state AS desktop_user_lifecycle_state,
users.lifecycle_version AS desktop_user_lifecycle_version,
admins.id IS NOT NULL AS control_admin_exists,
admins.status AS control_admin_status,
admins.session_version AS control_admin_session_version
FROM gfs_desktop_operator_links links
LEFT JOIN users ON users.id = links.user_id
LEFT JOIN control_admin_users admins ON admins.id = links.control_admin_id
WHERE links.user_id = $1::uuid
AND links.state = 'active'`,
[desktopUserId]
)
if (result.rows.length === 0) return null
if (result.rows.length !== 1) {
throw new GfsDesktopOperatorLinkError(
'malformed_link',
'operator-link uniqueness invariant is violated'
)
}
return mapActiveResolvedLink(result.rows[0] as ResolvedLinkRow, { desktopUserId })
} catch (error) {
if (error instanceof GfsDesktopOperatorLinkError) throw error
throw new GfsDesktopOperatorLinkError(
'resolution_failed',
'failed to resolve GFS Desktop operator link',
{ cause: error }
)
}
}
/**
* The external-authority boundary checks lifecycle before it can fall back
* to ordinary user-session authority after a link is revoked.
*/
async isDesktopUserActive(desktopUserIdInput: string): Promise<boolean> {
const desktopUserId = requireUuid(desktopUserIdInput, 'desktopUserId')
try {
const result = await this.dependencies.readDb.query(
`SELECT lifecycle_state
FROM users
WHERE id = $1::uuid
LIMIT 1`,
[desktopUserId]
)
return (
(result.rows[0] as { lifecycle_state?: unknown } | undefined)?.lifecycle_state === 'active'
)
} catch (error) {
if (error instanceof GfsDesktopOperatorLinkError) throw error
throw new GfsDesktopOperatorLinkError(
'resolution_failed',
'failed to resolve Desktop user lifecycle state',
{ cause: error }
)
}
}
/** Read-only exact-pair seam for the authenticated Control UI revoke surface. */
async getLinkForControlAdmin(
controlAdminIdInput: string
): Promise<GfsDesktopOperatorLink | null> {
const controlAdminId = requireUuid(controlAdminIdInput, 'controlAdminId')
try {
const result = await this.dependencies.readDb.query(
`SELECT links.id::text AS id,
links.lineage_id::text AS lineage_id,
links.generation,
links.predecessor_id::text AS predecessor_id,
links.state,
links.row_version,
links.revoked_at,
links.revocation_reason,
links.user_id::text AS user_id,
links.control_admin_id::text AS control_admin_id,
links.source,
links.created_at,
users.id IS NOT NULL AS desktop_user_exists,
users.lifecycle_state AS desktop_user_lifecycle_state,
users.lifecycle_version AS desktop_user_lifecycle_version,
admins.id IS NOT NULL AS control_admin_exists,
admins.status AS control_admin_status,
admins.session_version AS control_admin_session_version
FROM gfs_desktop_operator_links links
LEFT JOIN users ON users.id = links.user_id
LEFT JOIN control_admin_users admins ON admins.id = links.control_admin_id
WHERE links.control_admin_id = $1::uuid
ORDER BY links.generation DESC
LIMIT 1`,
[controlAdminId]
)
if (result.rows.length === 0) return null
if (result.rows.length !== 1) {
throw new GfsDesktopOperatorLinkError(
'malformed_link',
'operator-link uniqueness invariant is violated'
)
}
const row = result.rows[0] as ResolvedLinkRow
const link = mapStoredLink(row)
if (link.controlAdminId !== controlAdminId || row.desktop_user_exists !== true) {
throw new GfsDesktopOperatorLinkError(
'malformed_link',
'operator-link lookup returned a malformed identity pair'
)
}
if (row.control_admin_exists !== true) {
throw new GfsDesktopOperatorLinkError(
'control_admin_not_found',
'operator link references a missing Control Admin'
)
}
// Status reads deliberately preserve a structurally valid tombstone for
// the Control UI. Request-time authority still uses resolveActiveLink(),
// which rejects every non-active generation or admin.
return link
} catch (error) {
if (error instanceof GfsDesktopOperatorLinkError) throw error
throw new GfsDesktopOperatorLinkError(
'resolution_failed',
'failed to read GFS Desktop operator link for Control Admin',
{ cause: error }
)
}
}
async getActiveRowVersionForControlAdmin(controlAdminIdInput: string): Promise<number | null> {
const controlAdminId = requireUuid(controlAdminIdInput, 'controlAdminId')
const result = await this.dependencies.readDb.query(
`SELECT row_version
FROM gfs_desktop_operator_links
WHERE control_admin_id = $1::uuid AND state = 'active'
LIMIT 1`,
[controlAdminId]
)
if (result.rows.length === 0) return null
return requireRowVersion((result.rows[0] as { row_version?: unknown }).row_version)
}
}
export const gfsDesktopOperatorLinkService = new GfsDesktopOperatorLinkService()