@opengeni/api-router 0.30.3 → 2.2.0-canary.0

package/src/routes/social.ts

@@ -15,7 +15,11 @@ import {
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { z } from "zod";
-import { requireAccessGrant } from "@opengeni/core";
+import { requireAccessGrant, requireAccessGrantAuthorization } from "@opengeni/core";
+import {
+  assertPersonalConnectionOwnerPrincipal,
+  isPersonalConnectionOwnerPrincipal,
+} from "../connection-ownership";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { boundedLimit } from "../http/common";
 import { completeSocialOAuthCallback, startSocialOAuth } from "../integrations/social-oauth";
@@ -99,18 +103,26 @@ export function registerSocialRoutes(app: Hono, deps: ApiRouteDeps): void {
       });
     }
     const payload = parsed.data;
-    const grant = await requireAccessGrant(
+    const access = await requireAccessGrantAuthorization(
       c,
       deps,
       workspaceId,
       payload.ownership === "workspace" ? "workspace:admin" : "workspace:read",
     );
+    // The contract already defaults this request to workspace ownership; an
+    // explicit personal choice still needs a human who can own it.
+    const personalOwnershipAllowed = isPersonalConnectionOwnerPrincipal(access);
+    if (payload.ownership === "personal") {
+      assertPersonalConnectionOwnerPrincipal(access);
+    }
+    const grant = access.grant;
     const result = await startSocialOAuth(
       { db, settings, observability },
       {
         accountId: grant.accountId,
         workspaceId,
         subjectId: grant.subjectId,
+        personalOwnershipAllowed,
         requestUrl: c.req.url,
         payload,
       },

package/src/routes/supergrok.ts

@@ -31,11 +31,11 @@ import {
   XAI_CLIENT_VERSION,
   XaiSubscriptionError,
   fetchXaiSubscriptionModels,
-  fetchXaiVerifiedIdentity,
   pollXaiDeviceCode,
   refreshXaiToken,
   requestXaiDeviceCode,
   xaiAccessTokenExpiry,
+  xaiIdentityFromDeviceTokens,
   type XaiFetch,
   type XaiProxyAuthContext,
 } from "@opengeni/xai-subscription";
@@ -392,6 +392,7 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (Math.floor(Date.now() / 1_000) >= state.expiresAt) {
       return c.json({ status: "expired" as const });
     }
+    let phase = "device_token_exchange";
     try {
       const poll = await pollXaiDeviceCode(
         {
@@ -401,9 +402,9 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
         { fetch: (deps.xaiFetch ?? fetch) as XaiFetch },
       );
       if (poll.status !== "authorized") return c.json(poll);
-      const identity = await fetchXaiVerifiedIdentity(poll.tokens.accessToken, {
-        fetch: (deps.xaiFetch ?? fetch) as XaiFetch,
-      });
+      phase = "token_identity";
+      const identity = xaiIdentityFromDeviceTokens(poll.tokens);
+      phase = "credential_persist";
       const encryptionKey = environmentsEncryptionKeyBytes(deps.settings);
       if (!encryptionKey) {
         throw new HTTPException(500, {
@@ -458,6 +459,24 @@ export function registerSuperGrokRoutes(app: Hono, deps: ApiRouteDeps): void {
         email: identity.email,
       });
     } catch (error) {
+      deps.observability?.warn("SuperGrok connection operation failed", {
+        provider: "xai",
+        providerApi: "oauth",
+        op: phase,
+        outcome: "failed",
+        reason:
+          error instanceof XaiSubscriptionError
+            ? error.kind
+            : error instanceof HTTPException
+              ? "http_exception"
+              : "unexpected",
+        status:
+          error instanceof XaiSubscriptionError
+            ? error.status
+            : error instanceof HTTPException
+              ? error.status
+              : undefined,
+      });
       throw xaiHttpError(error, "SuperGrok device login failed");
     }
   });

package/src/routes/transcription-recordings.ts

@@ -17,6 +17,7 @@ import {
   TranscriptionServiceError,
   type ApiRouteDeps,
 } from "@opengeni/core";
+import { retryWhileMissing } from "@opengeni/storage";
 import {
   claimNextTranscriptionRecordingSegment,
   claimTranscriptionRecordingAssembly,
@@ -394,7 +395,10 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
           );
         }
         segmentNumber = claim.segment.segmentNumber;
-        const stored = await deps.objectStorage?.getObjectBytes(claim.segment.objectKey);
+        const segmentKey = claim.segment.objectKey;
+        const stored = deps.objectStorage
+          ? await retryWhileMissing(async () => deps.objectStorage!.getObjectBytes(segmentKey))
+          : null;
         if (!stored) {
           throw new RecordingProcessingError("Provider segment is missing", "invalid_audio", false);
         }
@@ -578,7 +582,9 @@ async function* verifiedChunkBytes(
     }
     let stored: Awaited<ReturnType<NonNullable<ApiRouteDeps["objectStorage"]>["getObjectBytes"]>>;
     try {
-      stored = await deps.objectStorage!.getObjectBytes(chunk.objectKey);
+      stored = await retryWhileMissing(async () =>
+        deps.objectStorage!.getObjectBytes(chunk.objectKey),
+      );
     } catch {
       throw new RecordingProcessingError("Chunk download failed", "network", true);
     }

package/src/routes/user-resource-authorities.ts

@@ -0,0 +1,138 @@
+import {
+  IssueUserResourceGrantRequest,
+  ListUserResourceAuthoritiesQuery,
+  ListUserResourceAuthoritiesResponse,
+  RevokeUserResourceGrantQuery,
+  UserResourceGrantMutationResponse,
+  UserResourceGrantRevocationResponse,
+} from "@opengeni/contracts";
+import {
+  issueManagedHumanUserResourceGrant,
+  listManagedHumanUserResourceAuthorities,
+  requireAccessGrantAuthorization,
+  revokeManagedHumanUserResourceGrant,
+  SessionAuthorizationDeniedError,
+  SessionAuthorizationUnavailableError,
+  SessionTenancyManagedHumanRequiredError,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import { nestedPostgresSqlState, SessionTenancyNotActivatedError } from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+async function body<S extends z.ZodType>(context: Context, schema: S): Promise<z.infer<S>> {
+  const parsed = schema.safeParse(await context.req.json().catch(() => null));
+  if (!parsed.success) throw new HTTPException(422, { message: "invalid user-resource request" });
+  return parsed.data;
+}
+
+function lifecycleError(error: unknown): never {
+  if (
+    error instanceof SessionAuthorizationDeniedError ||
+    error instanceof SessionTenancyManagedHumanRequiredError ||
+    error instanceof SessionTenancyNotActivatedError
+  ) {
+    throw new HTTPException(403, { message: "user-resource authority denied" });
+  }
+  if (error instanceof SessionAuthorizationUnavailableError) {
+    throw new HTTPException(503, { message: "session authorization unavailable" });
+  }
+  if (nestedPostgresSqlState(error) === "42501") {
+    throw new HTTPException(403, { message: "user-resource authority denied" });
+  }
+  if (nestedPostgresSqlState(error) === "22023") {
+    throw new HTTPException(422, { message: "invalid user-resource request" });
+  }
+  throw error;
+}
+
+export function registerUserResourceAuthorityRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const base = "/v1/workspaces/:workspaceId/user-resource-authorities";
+  app.get(base, async (context) => {
+    const query = ListUserResourceAuthoritiesQuery.safeParse({
+      scope: context.req.query("scope"),
+      resourceKind: context.req.query("resourceKind"),
+      cursor: context.req.query("cursor"),
+      limit: context.req.query("limit"),
+    });
+    if (!query.success) throw new HTTPException(422, { message: "explicit scope=user required" });
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    try {
+      const page = await listManagedHumanUserResourceAuthorities(
+        deps,
+        access,
+        workspaceId,
+        query.data,
+      );
+      return context.json(
+        ListUserResourceAuthoritiesResponse.parse({
+          scope: "user",
+          ...page,
+        }),
+      );
+    } catch (error) {
+      return lifecycleError(error);
+    }
+  });
+
+  app.post(`${base}/:authorityId/grants`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const authorityId = z.string().uuid().safeParse(context.req.param("authorityId"));
+    if (!authorityId.success) throw new HTTPException(422, { message: "invalid authority id" });
+    const request = await body(context, IssueUserResourceGrantRequest);
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    try {
+      return context.json(
+        UserResourceGrantMutationResponse.parse({
+          scope: "user",
+          grant: await issueManagedHumanUserResourceGrant(
+            deps,
+            access,
+            workspaceId,
+            authorityId.data,
+            request,
+            "http",
+          ),
+        }),
+      );
+    } catch (error) {
+      return lifecycleError(error);
+    }
+  });
+
+  app.delete(`${base}/grants/:grantId`, async (context) => {
+    const query = RevokeUserResourceGrantQuery.safeParse({ scope: context.req.query("scope") });
+    if (!query.success) throw new HTTPException(422, { message: "explicit scope=user required" });
+    const grantId = z.string().uuid().safeParse(context.req.param("grantId"));
+    if (!grantId.success) throw new HTTPException(422, { message: "invalid grant id" });
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    try {
+      return context.json(
+        UserResourceGrantRevocationResponse.parse({
+          scope: "user",
+          grant: await revokeManagedHumanUserResourceGrant(deps, access, workspaceId, grantId.data),
+        }),
+      );
+    } catch (error) {
+      return lifecycleError(error);
+    }
+  });
+}

package/src/routes/workspace-artifacts.ts

@@ -11,6 +11,7 @@ import {
   normalizeWorkspaceArtifactSlug,
 } from "@opengeni/contracts";
 import { requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import { retryWhileMissing } from "@opengeni/storage";
 import {
   createWorkspaceArtifact,
   getWorkspaceArtifact,
@@ -197,7 +198,9 @@ export function registerWorkspaceArtifactRoutes(app: Hono, deps: ApiRouteDeps):
         artifactId(context),
         parsedVersion,
       );
-      const object = await deps.objectStorage.getObjectBytes(ref.contentKey);
+      const object = await retryWhileMissing(async () =>
+        deps.objectStorage!.getObjectBytes(ref.contentKey),
+      );
       if (!object) throw new HTTPException(503, { message: "Artifact content is unavailable" });
       const actualHash = createHash("sha256").update(object.bytes).digest("hex");
       if (actualHash !== ref.version.contentSha256) {

package/src/routes/workspace-capture.ts

@@ -215,10 +215,20 @@ async function loadManifest(
  * manifest blob has been GC'd (all graceful cold-fallback states — never errors).
  * Inline manifest for ≤2MB, signed URL above.
  */
+/** Awaited before a signed capture URL is returned to the caller: the route
+ *  records the metadata-only issuance audit fact. A throwing recorder fails
+ *  the serve closed - no recorded fact, no bearer capability. */
+export type CaptureSignedUrlIssuanceRecorder = (fact: {
+  kind: "capture_manifest" | "capture_file";
+  revision: number;
+  expiresAt: string;
+}) => Promise<void>;
+
 export async function serveWorkspaceCapture(
   row: WorkspaceCaptureRow | null,
   storage: CaptureStoragePort,
   cache?: WorkspaceCaptureManifestCache,
+  onSignedUrlIssued?: CaptureSignedUrlIssuanceRecorder,
 ): Promise<GetWorkspaceCaptureResponse> {
   if (!row) {
     return { available: false };
@@ -274,6 +284,11 @@ export async function serveWorkspaceCapture(
     key: row.manifestKey,
     expiresInSeconds: CAPTURE_SIGNED_URL_TTL_SECONDS,
   });
+  await onSignedUrlIssued?.({
+    kind: "capture_manifest",
+    revision: row.revision,
+    expiresAt: signed.expiresAt.toISOString(),
+  });
   return GetWorkspaceCaptureResponse.parse({
     ...meta,
     manifest: null,
@@ -293,6 +308,7 @@ export async function serveWorkspaceCaptureFile(
   row: WorkspaceCaptureRow | null,
   path: string,
   storage: CaptureStoragePort,
+  onSignedUrlIssued?: CaptureSignedUrlIssuanceRecorder,
 ): Promise<GetWorkspaceCaptureFileResponse> {
   const loaded = row ? await loadManifest(row, storage) : null;
   if (!loaded) {
@@ -347,6 +363,11 @@ export async function serveWorkspaceCaptureFile(
     key: file.contentRef,
     expiresInSeconds: CAPTURE_SIGNED_URL_TTL_SECONDS,
   });
+  await onSignedUrlIssued?.({
+    kind: "capture_file",
+    revision: row!.revision,
+    expiresAt: signed.expiresAt.toISOString(),
+  });
   return GetWorkspaceCaptureFileResponse.parse({
     ...base,
     encoding: null,

package/src/routes/workspace-learning.ts

@@ -0,0 +1,228 @@
+import { randomUUID } from "node:crypto";
+import {
+  ActivateWorkspaceLearningPolicyRevisionRequest,
+  CreateWorkspaceLearningPolicyRevisionRequest,
+  RollbackWorkspaceLearningPolicyRevisionRequest,
+  UndoGovernedLearningActivationHttpRequest,
+  WorkspaceLearningHistoryResponse,
+  WorkspaceLearningPolicyHistoryQuery,
+  WorkspaceLearningPolicyMutationResponse,
+  WorkspaceLearningPolicyRevision,
+} from "@opengeni/contracts";
+import {
+  publishGovernedLearningEventToSlack,
+  requireAccessGrant,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  activateWorkspaceLearningPolicyRevision,
+  createWorkspaceLearningPolicyRevision,
+  GovernedLearningActivationAuthorityError,
+  GovernedLearningActivationConflictError,
+  GovernedLearningActivationInvalidOperationError,
+  GovernedLearningEvaluationAuthorityError,
+  listGovernedLearningActivationHistory,
+  listGovernedLearningDecisionReceipts,
+  listWorkspaceLearningPolicyHistory,
+  rollbackWorkspaceLearningPolicyRevision,
+  undoGovernedLearningActivation,
+  WorkspaceLearningPolicyAuthorityError,
+  WorkspaceLearningPolicyConflictError,
+  WorkspaceLearningPolicyInvalidOperationError,
+  WorkspaceLearningPolicyNotFoundError,
+  WorkspaceLearningPolicyOperationReuseError,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+async function parseBody<S extends z.ZodType>(context: Context, schema: S): Promise<z.infer<S>> {
+  const parsed = schema.safeParse(await context.req.json().catch(() => null));
+  if (!parsed.success) {
+    throw new HTTPException(422, { message: "Invalid workspace learning request" });
+  }
+  return parsed.data;
+}
+
+function learningError(error: unknown): never {
+  if (
+    error instanceof WorkspaceLearningPolicyAuthorityError ||
+    error instanceof GovernedLearningEvaluationAuthorityError ||
+    error instanceof GovernedLearningActivationAuthorityError
+  ) {
+    throw new HTTPException(403, { message: error.message });
+  }
+  if (error instanceof WorkspaceLearningPolicyNotFoundError) {
+    throw new HTTPException(404, { message: error.message });
+  }
+  if (
+    error instanceof WorkspaceLearningPolicyConflictError ||
+    error instanceof WorkspaceLearningPolicyOperationReuseError ||
+    error instanceof GovernedLearningActivationConflictError
+  ) {
+    throw new HTTPException(409, { message: error.message });
+  }
+  if (
+    error instanceof WorkspaceLearningPolicyInvalidOperationError ||
+    error instanceof GovernedLearningActivationInvalidOperationError
+  ) {
+    throw new HTTPException(422, { message: error.message });
+  }
+  throw error;
+}
+
+export function registerWorkspaceLearningRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const base = "/v1/workspaces/:workspaceId/learning";
+
+  app.get(base, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const query = WorkspaceLearningPolicyHistoryQuery.safeParse({
+      limit: context.req.query("limit"),
+    });
+    if (!query.success) {
+      throw new HTTPException(422, { message: "Invalid workspace learning history query" });
+    }
+    try {
+      const [policy, decisions, lifecycle] = await Promise.all([
+        listWorkspaceLearningPolicyHistory(deps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          limit: query.data.limit,
+        }),
+        listGovernedLearningDecisionReceipts(deps.db, {
+          workspaceId,
+          subjectId: grant.subjectId,
+          principalKind: grant.principalKind ?? "",
+          limit: query.data.limit,
+        }),
+        listGovernedLearningActivationHistory(deps.db, {
+          workspaceId,
+          subjectId: grant.subjectId,
+          principalKind: grant.principalKind ?? "",
+          limit: query.data.limit,
+        }),
+      ]);
+      return context.json(
+        WorkspaceLearningHistoryResponse.parse({
+          head: policy.head,
+          revisions: policy.revisions,
+          policyEvents: policy.events,
+          decisions: decisions.receipts,
+          activations: lifecycle.activations,
+          undos: lifecycle.undos,
+          truncated: policy.truncated || decisions.truncated || lifecycle.truncated,
+          effectiveBoundary: "next_accepted_attempt",
+        }),
+      );
+    } catch (error) {
+      learningError(error);
+    }
+  });
+
+  app.post(`${base}/revisions`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:admin");
+    const request = await parseBody(context, CreateWorkspaceLearningPolicyRevisionRequest);
+    try {
+      return context.json(
+        WorkspaceLearningPolicyRevision.parse(
+          await createWorkspaceLearningPolicyRevision(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
+            accountId: grant.accountId,
+            workspaceId,
+            workspaceMode: request.workspaceMode,
+            sourceOverrides: request.sourceOverrides,
+            supersedesRevisionId: request.supersedesRevisionId,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+          }),
+        ),
+        201,
+      );
+    } catch (error) {
+      learningError(error);
+    }
+  });
+
+  app.post(`${base}/revisions/:revisionId/activate`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const revisionId = z.string().uuid().safeParse(context.req.param("revisionId"));
+    if (!revisionId.success) throw new HTTPException(422, { message: "Invalid revision id" });
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:admin");
+    const request = await parseBody(context, ActivateWorkspaceLearningPolicyRevisionRequest);
+    try {
+      return context.json(
+        WorkspaceLearningPolicyMutationResponse.parse(
+          await activateWorkspaceLearningPolicyRevision(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
+            accountId: grant.accountId,
+            workspaceId,
+            revisionId: revisionId.data,
+            expectedCurrentRevisionId: request.expectedCurrentRevisionId,
+            expectedActivationVersion: request.expectedActivationVersion,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            reason: request.reason,
+          }),
+        ),
+      );
+    } catch (error) {
+      learningError(error);
+    }
+  });
+
+  app.post(`${base}/rollback`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:admin");
+    const request = await parseBody(context, RollbackWorkspaceLearningPolicyRevisionRequest);
+    try {
+      return context.json(
+        WorkspaceLearningPolicyMutationResponse.parse(
+          await rollbackWorkspaceLearningPolicyRevision(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
+            accountId: grant.accountId,
+            workspaceId,
+            targetRevisionId: request.targetRevisionId,
+            expectedCurrentRevisionId: request.expectedCurrentRevisionId,
+            expectedActivationVersion: request.expectedActivationVersion,
+            actorSubjectId: grant.subjectId,
+            principalKind: grant.principalKind,
+            reason: request.reason,
+          }),
+        ),
+      );
+    } catch (error) {
+      learningError(error);
+    }
+  });
+
+  app.post(`${base}/activations/:activationReceiptId/undo`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const activationReceiptId = z
+      .string()
+      .uuid()
+      .safeParse(context.req.param("activationReceiptId"));
+    if (!activationReceiptId.success) {
+      throw new HTTPException(422, { message: "Invalid activation receipt id" });
+    }
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:admin");
+    const request = await parseBody(context, UndoGovernedLearningActivationHttpRequest);
+    try {
+      const undo = await undoGovernedLearningActivation(deps.db, {
+        caller: { workspaceId, subjectId: grant.subjectId },
+        request: {
+          operationId: request.operationId ?? randomUUID(),
+          activationReceiptId: activationReceiptId.data,
+        },
+      });
+      // Best-effort notification; the undo receipt is already durable.
+      await publishGovernedLearningEventToSlack(deps.db, { kind: "undone", receipt: undo }).catch(
+        () => undefined,
+      );
+      return context.json(undo);
+    } catch (error) {
+      learningError(error);
+    }
+  });
+}