@opengeni/api-router 0.30.1 → 2.1.0-canary.0

package/src/auth/managed-auth.ts

@@ -20,10 +20,25 @@ import { decideCanonicalHumanSessionAdmission } from "./canonical-human-session-
 // importers (`app.ts`) keep the same import path.
 export type { ManagedAuth };
 
+export function managedAuthRequiresEmailVerification(
+  settings: Pick<Settings, "environment">,
+): boolean {
+  return settings.environment !== "local";
+}
+
+export function managedAuthUserCreateOverride(
+  settings: Pick<Settings, "environment">,
+  user: { emailVerified: boolean } & Record<string, unknown>,
+): { data: typeof user } | undefined {
+  if (managedAuthRequiresEmailVerification(settings)) return undefined;
+  return { data: { ...user, emailVerified: true } };
+}
+
 export function createManagedAuth(settings: Settings, db: Database): ManagedAuth | null {
   if (settings.productAccessMode !== "managed") {
     return null;
   }
+  const requireEmailVerification = managedAuthRequiresEmailVerification(settings);
   const pool = new Pool({ connectionString: settings.databaseUrl });
   return betterAuth({
     appName: "OpenGeni",
@@ -124,10 +139,13 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
     },
     emailAndPassword: {
       enabled: true,
-      requireEmailVerification: true,
+      // Local managed mode exists so the complete human/org tenancy flow can
+      // be exercised without first configuring a transactional-email vendor.
+      // Every non-local deployment retains the verified-email boundary.
+      requireEmailVerification,
       revokeSessionsOnPasswordReset: true,
       onExistingUserSignUp: async ({ user }) => {
-        if (!user.emailVerified) {
+        if (requireEmailVerification && !user.emailVerified) {
           const url = await verificationUrl(settings, user.email);
           await sendEmail(settings, {
             to: user.email,
@@ -147,7 +165,7 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
       },
     },
     emailVerification: {
-      sendOnSignUp: true,
+      sendOnSignUp: requireEmailVerification,
       sendVerificationEmail: async ({ user, url }) => {
         await sendEmail(settings, {
           to: user.email,
@@ -161,6 +179,7 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
           userId: user.id,
           email: user.email,
           name: user.name,
+          emailVerified: true,
         });
       },
     },
@@ -239,11 +258,14 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
       },
       user: {
         create: {
+          before: async (user) => managedAuthUserCreateOverride(settings, user),
           after: async (user) => {
+            if (!user.emailVerified) return;
             await ensureManagedAccessForUser(db, {
               userId: user.id,
               email: user.email,
               name: user.name,
+              emailVerified: true,
             });
           },
         },

package/src/codemode.ts

@@ -31,12 +31,33 @@ export type CodemodeGrantAuthority = {
   subjectId: string;
 };
 
+export type CodemodeAuthorityFailureReason =
+  | "invalid_grant"
+  | "inactive_attempt"
+  | "catalog_mismatch";
+
+const CODEMODE_AUTHORITY_FAILURE_MESSAGES: Record<CodemodeAuthorityFailureReason, string> = {
+  invalid_grant: "Codemode bearer does not carry valid execution-attempt authority",
+  inactive_attempt: "Codemode execution attempt is no longer active",
+  catalog_mismatch: "Codemode tool catalog does not match the active execution attempt",
+};
+
 export class CodemodeAuthorityError extends Error {
-  readonly code = "codemode_authority_invalid";
+  readonly code: `codemode_${CodemodeAuthorityFailureReason}`;
 
-  constructor() {
-    super("Codemode bearer is not bound to an active execution attempt");
+  constructor(readonly reason: CodemodeAuthorityFailureReason) {
+    super(CODEMODE_AUTHORITY_FAILURE_MESSAGES[reason]);
     this.name = "CodemodeAuthorityError";
+    this.code = `codemode_${reason}`;
+  }
+}
+
+export class CodemodeCatalogNotReadyError extends Error {
+  readonly code = "codemode_catalog_not_ready";
+
+  constructor() {
+    super("Codemode tool catalog is not ready for the active execution attempt");
+    this.name = "CodemodeCatalogNotReadyError";
   }
 }
 
@@ -71,11 +92,29 @@ export function isCodemodeGrant(grant: AccessGrant): boolean {
   );
 }
 
+export function requireMatchingCodemodeCatalog(
+  authority: CodemodeGrantAuthority,
+  catalog: AttemptToolCatalog | null,
+): AttemptToolCatalog {
+  if (!catalog) throw new CodemodeCatalogNotReadyError();
+  if (
+    catalog.accountId !== authority.accountId ||
+    catalog.workspaceId !== authority.workspaceId ||
+    catalog.sessionId !== authority.sessionId ||
+    catalog.turnId !== authority.turnId ||
+    catalog.attemptId !== authority.attemptId ||
+    catalog.executionGeneration !== authority.executionGeneration
+  ) {
+    throw new CodemodeAuthorityError("catalog_mismatch");
+  }
+  return catalog;
+}
+
 export async function requireActiveCodemodeCatalog(
   deps: ApiRouteDeps,
   grant: AccessGrant,
 ): Promise<{ authority: CodemodeGrantAuthority; catalog: AttemptToolCatalog }> {
-  if (!isCodemodeGrant(grant)) throw new CodemodeAuthorityError();
+  if (!isCodemodeGrant(grant)) throw new CodemodeAuthorityError("invalid_grant");
   const authority = codemodeAuthorityForGrant(grant)!;
   await requireSessionAuthorization(deps, grant, {
     sessionId: authority.sessionId,
@@ -94,24 +133,16 @@ export async function requireActiveCodemodeCatalog(
     active.activeAttemptId !== authority.attemptId ||
     active.executionGeneration !== authority.executionGeneration
   ) {
-    throw new CodemodeAuthorityError();
-  }
-  const catalog = await getAttemptToolCatalog(deps.db, {
-    accountId: authority.accountId,
-    workspaceId: authority.workspaceId,
-    attemptId: authority.attemptId,
-  });
-  if (
-    !catalog ||
-    catalog.accountId !== authority.accountId ||
-    catalog.workspaceId !== authority.workspaceId ||
-    catalog.sessionId !== authority.sessionId ||
-    catalog.turnId !== authority.turnId ||
-    catalog.attemptId !== authority.attemptId ||
-    catalog.executionGeneration !== authority.executionGeneration
-  ) {
-    throw new CodemodeAuthorityError();
+    throw new CodemodeAuthorityError("inactive_attempt");
   }
+  const catalog = requireMatchingCodemodeCatalog(
+    authority,
+    await getAttemptToolCatalog(deps.db, {
+      accountId: authority.accountId,
+      workspaceId: authority.workspaceId,
+      attemptId: authority.attemptId,
+    }),
+  );
   return { authority, catalog };
 }
 
@@ -128,7 +159,6 @@ export async function submitAndDispatchCodemodeCall(
       ...request,
       caller: { kind: "codemode", subjectId: authority.subjectId },
     },
-    callLimit: deps.settings.codemodeMaxCallsPerTurn,
   });
   let operation = submitted.operation;
   let dispatch: CodemodeCallSubmissionValue["dispatch"] = terminal(operation)
@@ -171,7 +201,7 @@ export async function readCodemodeOperation(
   grant: AccessGrant,
   operationId: string,
 ): Promise<CodemodeOperation | null> {
-  if (!isCodemodeGrant(grant)) throw new CodemodeAuthorityError();
+  if (!isCodemodeGrant(grant)) throw new CodemodeAuthorityError("invalid_grant");
   const authority = codemodeAuthorityForGrant(grant)!;
   return await getCodemodeOperation(deps.db, {
     accountId: authority.accountId,

package/src/codex-realtime.ts

@@ -5,6 +5,7 @@ import {
   CodexRealtimeError,
   CodexReloginRequired,
   createCodexRealtimeCall,
+  fetchCodexRealtimeProviderConfig,
   selectCodexCredentialId,
   type CodexAuthHeaders,
   type CodexFetch,
@@ -295,8 +296,13 @@ export function buildSessionCodexRealtimeBroker(
         },
         tokenResolver: (credentialId) =>
           buildCodexTokenResolver(db, settings, workspaceId, credentialId),
-        createCall: async (auth, callInput, options) =>
-          await createCodexRealtimeCall(auth, callInput, fetchImpl, options),
+        createCall: async (auth, callInput, options) => {
+          const providerConfig = await fetchCodexRealtimeProviderConfig(auth, fetchImpl, options);
+          return await createCodexRealtimeCall(auth, callInput, fetchImpl, {
+            ...options,
+            providerConfig,
+          });
+        },
       },
       { ...input, sessionId },
     );

package/src/company-brain-okf.ts

@@ -0,0 +1,340 @@
+import {
+  COMPANY_BRAIN_GUIDANCE_MAX_CONTENT_BYTES,
+  COMPANY_BRAIN_GUIDANCE_MAX_ENTRIES,
+  CompanyBrainOkfPackage,
+  type CompanyBrainGuidanceEntry,
+  type CompanyBrainGuidanceTruncationReason,
+  type CompanyBrainOkfPackage as CompanyBrainOkfPackageType,
+  type CompanyProfileListResponse,
+  type WorkspaceInstructionPolicyListResponse,
+  type WorkspaceInstructionPolicyRevision,
+  type WorkspaceStateKnowledge,
+} from "@opengeni/contracts";
+import type { CompanyBrainPreferenceGuidancePage } from "@opengeni/db";
+
+const OKF_MARKER = "<!-- opengeni-company-brain-okf-v1 -->";
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, nested]) => [key, canonicalize(nested)]),
+  );
+}
+
+function canonicalJson(value: unknown): string {
+  return `${JSON.stringify(canonicalize(value), null, 2)}\n`;
+}
+
+function companyProfileEntries(profile: CompanyProfileListResponse): {
+  entries: CompanyBrainGuidanceEntry[];
+  truncated: boolean;
+} {
+  const activeRevisionId = profile.current?.revisionId ?? null;
+  const byId = new Map(profile.revisions.map((revision) => [revision.id, revision] as const));
+  if (profile.activeRevision) byId.set(profile.activeRevision.id, profile.activeRevision);
+  return {
+    entries: [...byId.values()].map((revision) => {
+      const active = revision.id === activeRevisionId;
+      return {
+        id: "company-profile",
+        revisionId: revision.id,
+        path: "company/profile",
+        scope: "organization",
+        classification: "company_profile",
+        title: "Company profile",
+        description: "Company identity, mission, products, customers, goals, and constraints.",
+        // Company-profile hashes cover this exact canonical field order.
+        content: JSON.stringify(revision.profile),
+        contentHash: revision.contentHash,
+        revision: revision.revision,
+        active,
+        lifecycle: active ? "active" : revision.intent === "proposal" ? "proposal" : "historical",
+        provenance: {
+          source: revision.provenance.source,
+          sourceId: revision.provenance.sourceId,
+          trust: revision.intent === "proposal" ? "untrusted_proposal" : "organization_managed",
+        },
+        relationships:
+          revision.supersedesRevisionId && byId.has(revision.supersedesRevisionId)
+            ? [{ type: "supersedes" as const, targetId: revision.supersedesRevisionId }]
+            : [],
+        createdAt: revision.createdAt,
+      } satisfies CompanyBrainGuidanceEntry;
+    }),
+    truncated: profile.nextAfterRevision !== null,
+  };
+}
+
+function instructionPolicyEntries(
+  policies: WorkspaceInstructionPolicyListResponse,
+  activeRevisions: WorkspaceInstructionPolicyRevision[],
+  activatedRevisionIds: string[],
+): { entries: CompanyBrainGuidanceEntry[]; truncated: boolean } {
+  const byId = new Map(policies.revisions.map((revision) => [revision.id, revision] as const));
+  for (const revision of activeRevisions) byId.set(revision.id, revision);
+  const activeIds = new Set(policies.activeHeads.map((head) => head.revisionId));
+  const activatedIds = new Set(activatedRevisionIds);
+  return {
+    entries: [...byId.values()].map((revision) => {
+      const roleSegment = revision.roleKey ?? "all";
+      const active = activeIds.has(revision.id);
+      const lifecycle = active
+        ? "active"
+        : activatedIds.has(revision.id)
+          ? "historical"
+          : revision.provenance.source === "onboarding" ||
+              revision.provenance.source === "knowledge_proposal"
+            ? "proposal"
+            : "inactive";
+      return {
+        id: `instruction-policy:${revision.kind}:${revision.scope}:${roleSegment}`,
+        revisionId: revision.id,
+        path: `ways-of-working/rules/${revision.kind}/${revision.scope}/${roleSegment}`,
+        scope: "workspace",
+        classification: "mandatory_rule",
+        title:
+          revision.kind === "charter"
+            ? "Workspace charter"
+            : revision.scope === "role"
+              ? `Role policy: ${roleSegment}`
+              : "Workspace policy",
+        description: active ? "Mandatory context included for applicable agents." : null,
+        content: revision.content,
+        contentHash: revision.contentHash,
+        revision: revision.revision,
+        active,
+        lifecycle,
+        provenance: {
+          source: revision.provenance.source,
+          sourceId: revision.provenance.sourceId,
+          trust:
+            revision.provenance.source === "human"
+              ? "workspace_managed"
+              : revision.provenance.source === "legacy_import"
+                ? "migrated"
+                : "untrusted_proposal",
+        },
+        relationships:
+          revision.supersedesRevisionId && byId.has(revision.supersedesRevisionId)
+            ? [{ type: "supersedes" as const, targetId: revision.supersedesRevisionId }]
+            : [],
+        createdAt: revision.createdAt,
+      } satisfies CompanyBrainGuidanceEntry;
+    }),
+    truncated: policies.nextAfterRevision !== null,
+  };
+}
+
+function preferenceLifecycle(
+  row: CompanyBrainPreferenceGuidancePage["rows"][number],
+  generatedAt: string,
+): CompanyBrainGuidanceEntry["lifecycle"] {
+  if (row.active && row.expiresAt && row.expiresAt.getTime() <= Date.parse(generatedAt)) {
+    return "expired";
+  }
+  if (row.active && row.status === "active") return "active";
+  if (row.status === "proposed") return "proposal";
+  if (row.status === "inactive") return "inactive";
+  if (row.status === "rejected") return "rejected";
+  if (row.status === "superseded") return "superseded";
+  return "historical";
+}
+
+function preferenceEntries(
+  page: CompanyBrainPreferenceGuidancePage,
+  generatedAt: string,
+): CompanyBrainGuidanceEntry[] {
+  const visibleRevisionIds = new Set(page.rows.map((row) => row.revisionId));
+  const visiblePreferenceIds = new Set(page.rows.map((row) => row.preferenceId));
+  return page.rows.map((row) => {
+    const scope =
+      row.scope === "organization"
+        ? "organization"
+        : row.scope === "user"
+          ? "personal"
+          : "workspace";
+    const lifecycle = preferenceLifecycle(row, generatedAt);
+    const relationships: CompanyBrainGuidanceEntry["relationships"] = [];
+    if (row.correctsRevisionId && visibleRevisionIds.has(row.correctsRevisionId)) {
+      relationships.push({ type: "corrects", targetId: row.correctsRevisionId });
+    }
+    if (row.supersededByPreferenceId && visiblePreferenceIds.has(row.supersededByPreferenceId)) {
+      relationships.push({
+        type: "superseded_by",
+        targetId: `preference:${row.supersededByPreferenceId}`,
+      });
+    }
+    return {
+      id: `preference:${row.preferenceId}`,
+      revisionId: row.revisionId,
+      path: `ways-of-working/guides/${scope}/${row.stableKey}`,
+      scope,
+      classification: "guide",
+      title: row.title,
+      description: row.description,
+      content: row.content,
+      contentHash: row.contentHash,
+      revision: row.revision,
+      active: lifecycle === "active",
+      lifecycle,
+      provenance: {
+        source: row.provenanceSource,
+        sourceId: row.provenanceSourceId,
+        trust: row.trust,
+      },
+      relationships,
+      createdAt: row.createdAt.toISOString(),
+    } satisfies CompanyBrainGuidanceEntry;
+  });
+}
+
+function guidanceEntryOrder(
+  left: CompanyBrainGuidanceEntry,
+  right: CompanyBrainGuidanceEntry,
+): number {
+  return (
+    left.classification.localeCompare(right.classification) ||
+    left.path.localeCompare(right.path) ||
+    right.revision - left.revision ||
+    left.revisionId.localeCompare(right.revisionId)
+  );
+}
+
+function relationshipTargetKeys(entry: CompanyBrainGuidanceEntry): string[] {
+  return [entry.id, entry.revisionId];
+}
+
+export function boundCompanyBrainGuidanceEntries(entries: CompanyBrainGuidanceEntry[]): {
+  entries: CompanyBrainGuidanceEntry[];
+  itemCountTruncated: boolean;
+  contentBytesTruncated: boolean;
+} {
+  const prioritized = [...entries].sort(
+    (left, right) => Number(right.active) - Number(left.active) || guidanceEntryOrder(left, right),
+  );
+  const selected: CompanyBrainGuidanceEntry[] = [];
+  let contentBytes = 0;
+  let itemCountTruncated = false;
+  let contentBytesTruncated = false;
+  for (const entry of prioritized) {
+    if (selected.length >= COMPANY_BRAIN_GUIDANCE_MAX_ENTRIES) {
+      itemCountTruncated = true;
+      continue;
+    }
+    const entryBytes = new TextEncoder().encode(entry.content).byteLength;
+    if (contentBytes + entryBytes > COMPANY_BRAIN_GUIDANCE_MAX_CONTENT_BYTES) {
+      contentBytesTruncated = true;
+      continue;
+    }
+    selected.push(entry);
+    contentBytes += entryBytes;
+  }
+  const visibleTargets = new Set(selected.flatMap(relationshipTargetKeys));
+  return {
+    entries: selected
+      .map((entry) => ({
+        ...entry,
+        relationships: entry.relationships.filter((relationship) =>
+          visibleTargets.has(relationship.targetId),
+        ),
+      }))
+      .sort(guidanceEntryOrder),
+    itemCountTruncated,
+    contentBytesTruncated,
+  };
+}
+
+export function createCompanyBrainOkfPackage(input: {
+  workspaceId: string;
+  generatedAt: string;
+  companyProfile: CompanyProfileListResponse;
+  instructionPolicies: WorkspaceInstructionPolicyListResponse;
+  activeInstructionPolicyRevisions: WorkspaceInstructionPolicyRevision[];
+  activatedInstructionPolicyRevisionIds: string[];
+  preferences: CompanyBrainPreferenceGuidancePage;
+  knowledge: WorkspaceStateKnowledge;
+}): CompanyBrainOkfPackageType {
+  const company = companyProfileEntries(input.companyProfile);
+  const policies = instructionPolicyEntries(
+    input.instructionPolicies,
+    input.activeInstructionPolicyRevisions,
+    input.activatedInstructionPolicyRevisionIds,
+  );
+  const preferences = preferenceEntries(input.preferences, input.generatedAt);
+  const truncationReasons: CompanyBrainGuidanceTruncationReason[] = [];
+  if (company.truncated) truncationReasons.push("company_profile_history");
+  if (policies.truncated) truncationReasons.push("instruction_policy_history");
+  if (input.preferences.preferenceCountTruncated) truncationReasons.push("preference_count");
+  if (input.preferences.revisionCountTruncated) truncationReasons.push("preference_history");
+  if (input.preferences.contentBytesTruncated) truncationReasons.push("aggregate_content_bytes");
+
+  const bounded = boundCompanyBrainGuidanceEntries([
+    ...company.entries,
+    ...policies.entries,
+    ...preferences,
+  ]);
+  if (bounded.itemCountTruncated) truncationReasons.push("aggregate_item_count");
+  if (bounded.contentBytesTruncated && !truncationReasons.includes("aggregate_content_bytes")) {
+    truncationReasons.push("aggregate_content_bytes");
+  }
+  const knowledgeAvailable = input.knowledge.availability === "available";
+  return CompanyBrainOkfPackage.parse({
+    kind: "opengeni.company_brain.okf",
+    schemaVersion: 1,
+    workspaceId: input.workspaceId,
+    generatedAt: input.generatedAt,
+    permissions: {
+      guidance: "available",
+      knowledge: knowledgeAvailable ? "available" : "unavailable",
+    },
+    guidance: {
+      entries: bounded.entries,
+      truncated: truncationReasons.length > 0,
+      truncationReasons,
+    },
+    knowledge: input.knowledge,
+    omissions: [
+      ...(knowledgeAvailable ? [] : (["inaccessible_knowledge"] as const)),
+      "document_bodies_use_documents_export",
+      "memory_bodies_and_provenance",
+      "secret_values_and_credentials",
+      "session_messages_and_task_notes",
+      "policy_and_preference_actor_identifiers",
+    ],
+  });
+}
+
+/**
+ * JSON is a strict subset of YAML 1.2. Keeping the payload in one fenced YAML
+ * block gives humans a readable Markdown package while making arbitrary
+ * guidance Markdown structurally inert and exactly round-trippable.
+ */
+export function serializeCompanyBrainOkf(value: CompanyBrainOkfPackageType): string {
+  const parsed = CompanyBrainOkfPackage.parse(value);
+  return [
+    OKF_MARKER,
+    "# OpenGeni Company Brain",
+    "",
+    "This permission-filtered package is portable evidence. Postgres remains canonical.",
+    "",
+    "```yaml",
+    canonicalJson(parsed).trimEnd(),
+    "```",
+    "",
+  ].join("\n");
+}
+
+export function parseCompanyBrainOkf(markdown: string): CompanyBrainOkfPackageType {
+  if (!markdown.startsWith(`${OKF_MARKER}\n`)) throw new Error("Invalid Company Brain OKF marker");
+  const opening = markdown.indexOf("```yaml\n");
+  if (opening < 0) throw new Error("Company Brain OKF payload is missing");
+  const payloadStart = opening + "```yaml\n".length;
+  const closing = markdown.indexOf("\n```", payloadStart);
+  if (closing < 0) throw new Error("Company Brain OKF payload is incomplete");
+  const trailing = markdown.slice(closing + "\n```".length).trim();
+  if (trailing.length > 0) throw new Error("Company Brain OKF has unexpected trailing content");
+  return CompanyBrainOkfPackage.parse(JSON.parse(markdown.slice(payloadStart, closing)));
+}

package/src/connected-machine-computer-access.ts

@@ -0,0 +1,33 @@
+export type ConnectedMachineComputerAccessState = {
+  hasDisplay: boolean;
+  desktopUnavailableReason: string | null;
+  allowScreenControl: boolean;
+};
+
+export type ConnectedMachineComputerAccessError = {
+  status: 403 | 409;
+  message: string;
+};
+
+/** Keep passive desktop viewing separate from input consent. */
+export function connectedMachineComputerAccessError(
+  state: ConnectedMachineComputerAccessState,
+  requiresControl: boolean,
+): ConnectedMachineComputerAccessError | null {
+  if (!state.hasDisplay) {
+    const reason = state.desktopUnavailableReason?.trim();
+    return {
+      status: 409,
+      message: reason
+        ? `Connected Machine desktop is unavailable. ${reason}`
+        : "Connected Machine desktop is unavailable because this machine has no capturable display.",
+    };
+  }
+  if (requiresControl && !state.allowScreenControl) {
+    return {
+      status: 403,
+      message: "Screen control is not enabled for this Connected Machine.",
+    };
+  }
+  return null;
+}

package/src/connection-authority-owner.ts

@@ -0,0 +1,61 @@
+import type { AccessGrantAuthorization } from "@opengeni/core";
+import type { UserResourceAuthoritySummary } from "@opengeni/db";
+import {
+  IssueConnectionUseGrantRequest,
+  ListConnectionAuthoritiesResponse,
+  type IssueConnectionUseGrantRequest as IssueConnectionUseGrantRequestValue,
+} from "@opengeni/contracts/connection-authority";
+import { HTTPException } from "hono/http-exception";
+
+/**
+ * Personal connection authority is available only to the exact authenticated
+ * human. API keys, delegated bearers, services, and agent attempts cannot name
+ * or substitute a personal owner.
+ */
+export function requireConnectionAuthorityOwner(access: AccessGrantAuthorization): string {
+  if (
+    !access.contextIntegrity ||
+    access.authenticatedSubjectId !== access.grant.subjectId ||
+    access.grant.principalKind !== "human_session" ||
+    access.grant.serviceInitiator ||
+    access.grant.serviceInitiatorContext ||
+    access.grant.subjectId.startsWith("api_key:")
+  ) {
+    throw new HTTPException(403, { message: "authenticated connection owner required" });
+  }
+  return access.grant.subjectId;
+}
+
+/** Removes generic resource kind and refuses non-connection grant actions. */
+export function projectSelfConnectionAuthorities(page: {
+  authorities: UserResourceAuthoritySummary[];
+  nextCursor: string | null;
+}) {
+  return ListConnectionAuthoritiesResponse.parse({
+    scope: "user",
+    authorities: page.authorities
+      .filter((authority) => authority.resourceKind === "connection")
+      .map(({ resourceKind: _resourceKind, ...authority }) => authority),
+    nextCursor: page.nextCursor,
+  });
+}
+
+/** The API owns the action; callers supply neither action nor owner identity. */
+export function connectionUseGrantLifecycleInput(input: unknown): {
+  action: "connection.use";
+  mode: IssueConnectionUseGrantRequestValue["mode"];
+  context: IssueConnectionUseGrantRequestValue["context"];
+  sessionId: string | null;
+  expectedAuthorityEpoch: number | null;
+  workspaceSharedAcknowledged: boolean;
+} {
+  const request = IssueConnectionUseGrantRequest.parse(input);
+  return {
+    action: "connection.use",
+    mode: request.mode,
+    context: request.context,
+    sessionId: request.sessionId ?? null,
+    expectedAuthorityEpoch: request.expectedAuthorityEpoch ?? null,
+    workspaceSharedAcknowledged: request.workspaceSharedAcknowledged,
+  };
+}