@opengeni/api-router 0.23.1 → 0.30.0

package/src/routes/canonical-human-identities.ts

@@ -0,0 +1,156 @@
+import { randomUUID } from "node:crypto";
+import {
+  CanonicalHumanBindingOperationRequest,
+  CanonicalHumanIdentityMutationResponse,
+  CanonicalHumanIdentityProjection,
+  LinkCanonicalHumanLoginBindingRequest,
+} from "@opengeni/contracts/canonical-human-identities";
+import { requireCanonicalHumanRequestIdentity } from "@opengeni/core/canonical-human-identities";
+import type { ApiRouteDeps } from "@opengeni/core";
+import {
+  applyCanonicalHumanIdentityOperation,
+  CanonicalHumanIdentityAuthorityError,
+  CanonicalHumanIdentityConflictError,
+  CanonicalHumanIdentityNotFoundError,
+  CanonicalHumanIdentityOperationReuseError,
+  getCanonicalHumanIdentityProjection,
+} from "@opengeni/db/canonical-human-identities";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+const BindingId = z.string().uuid();
+
+async function requestIdentity(context: Context, deps: ApiRouteDeps) {
+  return await requireCanonicalHumanRequestIdentity(context, {
+    db: deps.db,
+    ...(deps.managedAuth === undefined ? {} : { managedAuth: deps.managedAuth }),
+    allowRecovery: true,
+  });
+}
+
+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 canonical human identity request" });
+  }
+  return parsed.data;
+}
+
+function bindingId(context: Context): string {
+  const parsed = BindingId.safeParse(context.req.param("bindingId"));
+  if (!parsed.success) throw new HTTPException(422, { message: "Invalid login binding id" });
+  return parsed.data;
+}
+
+function identityError(context: Context, error: unknown): Response {
+  if (error instanceof CanonicalHumanIdentityConflictError) {
+    return context.json({ code: error.code, message: error.message }, 409);
+  }
+  if (error instanceof CanonicalHumanIdentityOperationReuseError) {
+    return context.json({ code: error.code, message: error.message }, 409);
+  }
+  if (error instanceof CanonicalHumanIdentityNotFoundError) {
+    return context.json(
+      { code: "CANONICAL_HUMAN_IDENTITY_NOT_FOUND", message: error.message },
+      404,
+    );
+  }
+  if (error instanceof CanonicalHumanIdentityAuthorityError) {
+    return context.json(
+      { code: "CANONICAL_HUMAN_IDENTITY_AUTHORITY_DENIED", message: error.message },
+      403,
+    );
+  }
+  throw error;
+}
+
+async function mutate(
+  context: Context,
+  deps: ApiRouteDeps,
+  input: {
+    operationType: "link" | "unlink" | "begin_recovery" | "recover";
+    bindingId?: string;
+    providerId?: string;
+    providerAccountId?: string;
+    operationId: string;
+    expectedIdentityRevision: number;
+    reason: string;
+  },
+): Promise<Response> {
+  const identity = await requestIdentity(context, deps);
+  try {
+    return context.json(
+      CanonicalHumanIdentityMutationResponse.parse(
+        await applyCanonicalHumanIdentityOperation(deps.db, {
+          operationId: input.operationId,
+          authUserId: identity.authUserId,
+          expectedIdentityRevision: input.expectedIdentityRevision,
+          operationType: input.operationType,
+          ...(input.bindingId ? { bindingId: input.bindingId } : {}),
+          ...(input.providerId ? { providerId: input.providerId } : {}),
+          ...(input.providerAccountId ? { providerAccountId: input.providerAccountId } : {}),
+          reason: input.reason,
+        }),
+      ),
+    );
+  } catch (error) {
+    return identityError(context, error);
+  }
+}
+
+export function registerCanonicalHumanIdentityRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const base = "/v1/identity";
+
+  app.get(base, async (context) => {
+    const identity = await requestIdentity(context, deps);
+    try {
+      return context.json(
+        CanonicalHumanIdentityProjection.parse(
+          await getCanonicalHumanIdentityProjection(deps.db, identity.authUserId),
+        ),
+      );
+    } catch (error) {
+      return identityError(context, error);
+    }
+  });
+
+  app.post(`${base}/login-bindings`, async (context) => {
+    const request = await parseBody(context, LinkCanonicalHumanLoginBindingRequest);
+    return await mutate(context, deps, {
+      operationType: "link",
+      ...request,
+      operationId: request.operationId ?? randomUUID(),
+    });
+  });
+
+  app.delete(`${base}/login-bindings/:bindingId`, async (context) => {
+    const request = await parseBody(context, CanonicalHumanBindingOperationRequest);
+    return await mutate(context, deps, {
+      operationType: "unlink",
+      bindingId: bindingId(context),
+      ...request,
+      operationId: request.operationId ?? randomUUID(),
+    });
+  });
+
+  app.post(`${base}/login-bindings/:bindingId/recovery`, async (context) => {
+    const request = await parseBody(context, CanonicalHumanBindingOperationRequest);
+    return await mutate(context, deps, {
+      operationType: "begin_recovery",
+      bindingId: bindingId(context),
+      ...request,
+      operationId: request.operationId ?? randomUUID(),
+    });
+  });
+
+  app.post(`${base}/login-bindings/:bindingId/recovery/complete`, async (context) => {
+    const request = await parseBody(context, CanonicalHumanBindingOperationRequest);
+    return await mutate(context, deps, {
+      operationType: "recover",
+      bindingId: bindingId(context),
+      ...request,
+      operationId: request.operationId ?? randomUUID(),
+    });
+  });
+}

package/src/routes/channels.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { CreateChannelRequest, UpdateChannelRequest } from "@opengeni/contracts";
+import {
+  ChannelNameConflictError,
+  createChannel,
+  deleteChannel,
+  listChannels,
+  updateChannel,
+} from "@opengeni/db";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { requireAccessGrant } from "@opengeni/core";
+import type { ApiRouteDeps } from "@opengeni/core";
+
+// Workspace-shared channels organize root sessions ("workstreams") by work
+// type in the rail. Deliberately session-permission-gated (not workspace:admin):
+// anyone who can read sessions can see how they are organized, and anyone who
+// can create sessions can organize them.
+// Reject malformed ids before they reach UUID-typed persistence queries,
+// preserving the non-enumerating 404 contract over a driver-level 500.
+function channelIdParam(value: string): string {
+  if (!z.string().uuid().safeParse(value).success) {
+    throw new HTTPException(404, { message: "channel not found" });
+  }
+  return value;
+}
+
+export function registerChannelRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const { db } = deps;
+
+  app.get("/v1/workspaces/:workspaceId/channels", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "sessions:read");
+    return c.json(await listChannels(db, workspaceId));
+  });
+
+  app.post("/v1/workspaces/:workspaceId/channels", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:create");
+    const payload = CreateChannelRequest.parse(await c.req.json());
+    try {
+      const channel = await createChannel(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        name: payload.name,
+        description: payload.description ?? null,
+        createdBy: grant.subjectId,
+      });
+      return c.json(channel, 201);
+    } catch (error) {
+      if (error instanceof ChannelNameConflictError) {
+        throw new HTTPException(409, { message: error.message });
+      }
+      throw error;
+    }
+  });
+
+  app.patch("/v1/workspaces/:workspaceId/channels/:channelId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "sessions:create");
+    const payload = UpdateChannelRequest.parse(await c.req.json());
+    try {
+      const channel = await updateChannel(
+        db,
+        workspaceId,
+        channelIdParam(c.req.param("channelId")),
+        payload,
+      );
+      if (!channel) {
+        throw new HTTPException(404, { message: "channel not found" });
+      }
+      return c.json(channel);
+    } catch (error) {
+      if (error instanceof ChannelNameConflictError) {
+        throw new HTTPException(409, { message: error.message });
+      }
+      throw error;
+    }
+  });
+
+  app.delete("/v1/workspaces/:workspaceId/channels/:channelId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "sessions:create");
+    const deleted = await deleteChannel(db, workspaceId, channelIdParam(c.req.param("channelId")));
+    if (!deleted) {
+      throw new HTTPException(404, { message: "channel not found" });
+    }
+    return c.json({ ok: true });
+  });
+}

package/src/routes/company-profile.ts

@@ -0,0 +1,255 @@
+import { randomUUID } from "node:crypto";
+import {
+  ActivateCompanyProfileRevisionRequest,
+  CompanyProfileConflictResponse,
+  CompanyProfileDiffRequest,
+  CompanyProfileDiffResponse,
+  CompanyProfileListQuery,
+  CompanyProfileListResponse,
+  CompanyProfileMutationResponse,
+  CompanyProfileOperationReuseResponse,
+  CompanyProfileRevision,
+  RollbackCompanyProfileRequest,
+  UpdateCompanyProfileRequest,
+} from "@opengeni/contracts";
+import {
+  requireAccessGrant,
+  requireAccessGrantAuthorization,
+  type AccessGrantAuthorization,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  activateCompanyProfileRevision,
+  CompanyProfileConflictError,
+  CompanyProfileInvalidOperationError,
+  CompanyProfileNotFoundError,
+  CompanyProfileOperationReuseError,
+  diffCompanyProfileRevisions,
+  getCompanyProfileRevision,
+  listCompanyProfile,
+  rollbackCompanyProfileRevision,
+  updateCompanyProfile,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+const RevisionId = z.string().uuid();
+
+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 company-profile request" });
+  return parsed.data;
+}
+
+function requireDirectAccountAdmin(access: AccessGrantAuthorization): void {
+  const { grant } = access;
+  if (
+    !access.contextIntegrity ||
+    access.authenticatedSubjectId !== grant.subjectId ||
+    grant.principalKind !== "human_session" ||
+    grant.serviceInitiator ||
+    grant.serviceInitiatorContext ||
+    grant.subjectId.startsWith("api_key:")
+  ) {
+    throw new HTTPException(403, {
+      message: "Company-profile administration requires a direct human-authorized request",
+    });
+  }
+  if (!access.accountGrant?.permissions.includes("account:admin")) {
+    throw new HTTPException(403, { message: "missing permission: account:admin" });
+  }
+}
+
+function profileError(context: Context, error: unknown): Response {
+  if (error instanceof CompanyProfileConflictError) {
+    return context.json(
+      CompanyProfileConflictResponse.parse({
+        code: error.code,
+        message: error.message,
+        currentHead: error.currentHead,
+      }),
+      409,
+    );
+  }
+  if (error instanceof CompanyProfileOperationReuseError) {
+    return context.json(
+      CompanyProfileOperationReuseResponse.parse({ code: error.code, message: error.message }),
+      409,
+    );
+  }
+  if (error instanceof CompanyProfileNotFoundError) {
+    return context.json({ code: "COMPANY_PROFILE_NOT_FOUND", message: error.message }, 404);
+  }
+  if (error instanceof CompanyProfileInvalidOperationError) {
+    return context.json({ code: "INVALID_COMPANY_PROFILE_OPERATION", message: error.message }, 422);
+  }
+  throw error;
+}
+
+function revisionId(context: Context): string {
+  const parsed = RevisionId.safeParse(context.req.param("revisionId"));
+  if (!parsed.success)
+    throw new HTTPException(422, { message: "Invalid company-profile revision id" });
+  return parsed.data;
+}
+
+export function registerCompanyProfileRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const base = "/v1/workspaces/:workspaceId/company-profile";
+
+  app.get(base, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const query = CompanyProfileListQuery.safeParse({
+      afterRevision: context.req.query("afterRevision"),
+      limit: context.req.query("limit"),
+    });
+    if (!query.success) throw new HTTPException(422, { message: "Invalid company-profile query" });
+    return context.json(
+      CompanyProfileListResponse.parse(
+        await listCompanyProfile(deps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          limit: query.data.limit,
+          ...(query.data.afterRevision === undefined
+            ? {}
+            : { afterRevision: query.data.afterRevision }),
+        }),
+      ),
+    );
+  });
+
+  app.put(base, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    requireDirectAccountAdmin(access);
+    const request = await parseBody(context, UpdateCompanyProfileRequest);
+    try {
+      return context.json(
+        CompanyProfileMutationResponse.parse(
+          await updateCompanyProfile(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
+            accountId: access.grant.accountId,
+            workspaceId,
+            profile: request.profile,
+            expectedCurrentRevisionId: request.expectedCurrentRevisionId,
+            expectedActivationVersion: request.expectedActivationVersion,
+            actorSubjectId: access.grant.subjectId,
+            principalKind: "human_session",
+            reason: request.reason,
+          }),
+        ),
+      );
+    } catch (error) {
+      return profileError(context, error);
+    }
+  });
+
+  app.get(`${base}/diff`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    const request = CompanyProfileDiffRequest.safeParse({
+      fromRevisionId: context.req.query("fromRevisionId"),
+      toRevisionId: context.req.query("toRevisionId"),
+    });
+    if (!request.success) throw new HTTPException(422, { message: "Invalid company-profile diff" });
+    try {
+      return context.json(
+        CompanyProfileDiffResponse.parse(
+          await diffCompanyProfileRevisions(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            ...request.data,
+          }),
+        ),
+      );
+    } catch (error) {
+      return profileError(context, error);
+    }
+  });
+
+  app.post(`${base}/rollback`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    requireDirectAccountAdmin(access);
+    const request = await parseBody(context, RollbackCompanyProfileRequest);
+    try {
+      return context.json(
+        CompanyProfileMutationResponse.parse(
+          await rollbackCompanyProfileRevision(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
+            accountId: access.grant.accountId,
+            workspaceId,
+            targetRevisionId: request.targetRevisionId,
+            expectedCurrentRevisionId: request.expectedCurrentRevisionId,
+            expectedActivationVersion: request.expectedActivationVersion,
+            actorSubjectId: access.grant.subjectId,
+            principalKind: "human_session",
+            reason: request.reason,
+          }),
+        ),
+      );
+    } catch (error) {
+      return profileError(context, error);
+    }
+  });
+
+  app.get(`${base}/revisions/:revisionId`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const grant = await requireAccessGrant(context, deps, workspaceId, "workspace:read");
+    try {
+      return context.json(
+        CompanyProfileRevision.parse(
+          await getCompanyProfileRevision(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            revisionId: revisionId(context),
+          }),
+        ),
+      );
+    } catch (error) {
+      return profileError(context, error);
+    }
+  });
+
+  app.post(`${base}/revisions/:revisionId/activate`, async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const access = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "workspace:read",
+    );
+    requireDirectAccountAdmin(access);
+    const request = await parseBody(context, ActivateCompanyProfileRevisionRequest);
+    try {
+      return context.json(
+        CompanyProfileMutationResponse.parse(
+          await activateCompanyProfileRevision(deps.db, {
+            operationId: request.operationId ?? randomUUID(),
+            accountId: access.grant.accountId,
+            workspaceId,
+            revisionId: revisionId(context),
+            expectedCurrentRevisionId: request.expectedCurrentRevisionId,
+            expectedActivationVersion: request.expectedActivationVersion,
+            actorSubjectId: access.grant.subjectId,
+            principalKind: "human_session",
+            reason: request.reason,
+          }),
+        ),
+      );
+    } catch (error) {
+      return profileError(context, error);
+    }
+  });
+}