@opengeni/api-router 3.0.1 → 3.1.2

package/src/routes/api-keys.ts

@@ -2,6 +2,10 @@ import {
   CreateApiKeyRequest,
   CreateApiKeyResponse,
   CreateOrganizationApiKeyRequest,
+  UpdateOrganizationApiKeyRequest,
+  normalizeOrganizationAccessPolicy,
+  type OrganizationAccessPolicy,
+  DEVELOPER_SETUP_API_KEY_PRESET,
   Permission,
   type AccessContext,
   type ApiKey,
@@ -12,7 +16,12 @@ import {
   createOrganizationApiKey as createOrganizationApiKeyRecord,
   listApiKeys,
   listOrganizationApiKeys,
+  getOrganizationApiKey,
+  updateOrganizationApiKey,
+  OrganizationApiKeyWorkspaceScopeError,
   OrganizationApiKeyLimitExceededError,
+  OrganizationServiceAccountNotFoundError,
+  OrganizationServiceAccountRoleError,
   revokeApiKey,
   revokeOrganizationApiKey,
 } from "@opengeni/db";
@@ -23,13 +32,19 @@ import { HTTPException } from "hono/http-exception";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
   accountScopedApiKeyWorkspaceAuthority,
+  organizationApiKeyAccess,
+  hasPermission,
+  organizationWorkspaceInScope,
   requireAccessContext,
-  requireAccessGrant,
   requireAccessGrantAuthorization,
+  requireApiKeyManagementContext,
+  requireExplicitPermissionDelegation,
   type AccessGrantAuthorization,
 } from "@opengeni/core";
 import { requireLimit } from "@opengeni/core";
 
+export { organizationApiKeyAccess } from "@opengeni/core";
+
 /** Permissions minted onto a `full` organization API key. */
 export const organizationApiKeyPermissions: Permission[] = [
   "account:read",
@@ -55,28 +70,43 @@ export const organizationReadApiKeyPermissions: Permission[] = [
 export function organizationApiKeyPermissionsForAccess(
   access: OrganizationApiKeyAccess,
 ): Permission[] {
-  return access === "read"
-    ? [...organizationReadApiKeyPermissions]
-    : [...organizationApiKeyPermissions];
+  return access === "developer_setup"
+    ? [...DEVELOPER_SETUP_API_KEY_PRESET.permissions]
+    : access === "read"
+      ? [...organizationReadApiKeyPermissions]
+      : [...organizationApiKeyPermissions];
 }
 
-/**
- * The access tier is derived from stored permissions rather than a column: a
- * key that carries the `workspace:admin` wildcard administers the
- * organization, any other organization key is read-only.
- */
-export function organizationApiKeyAccess(permissions: Permission[]): OrganizationApiKeyAccess {
-  return permissions.includes("workspace:admin") ? "full" : "read";
+/** Existing callers retain their expiry; setup keys default to one day. */
+export function organizationApiKeyExpiryDate(
+  request: Pick<CreateOrganizationApiKeyRequest, "preset" | "expiresAt"> &
+    Partial<Pick<CreateOrganizationApiKeyRequest, "access">>,
+  now: Date = new Date(),
+): Date | null {
+  if (request.expiresAt !== undefined) return new Date(request.expiresAt);
+  return request.preset === "developer_setup" || request.access === "developer_setup"
+    ? new Date(now.getTime() + DEVELOPER_SETUP_API_KEY_PRESET.defaultExpiryHours * 60 * 60 * 1000)
+    : null;
 }
 
 function withOrganizationApiKeyAccess(apiKey: ApiKey): ApiKey {
-  return { ...apiKey, access: organizationApiKeyAccess(apiKey.permissions) };
+  const workspaceScope = apiKey.workspaceScope ?? { kind: "all" as const };
+  return {
+    ...apiKey,
+    access: organizationApiKeyAccess(apiKey.permissions),
+    workspaceScope,
+    policy: normalizeOrganizationAccessPolicy({
+      preset: "custom",
+      permissions: apiKey.permissions,
+      workspaceScope,
+    }),
+  };
 }
 
 export function registerApiKeyRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get("/v1/workspaces/:workspaceId/api-keys", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "api_keys:manage");
+    await requireWorkspaceApiKeyControl(c, deps, workspaceId);
     return c.json({ apiKeys: await listApiKeys(deps.db, workspaceId) });
   });
 
@@ -85,12 +115,7 @@ export function registerApiKeyRoutes(app: Hono, deps: ApiRouteDeps): void {
     zValidator("json", CreateApiKeyRequest.omit({ workspaceId: true })),
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
-      const authorization = await requireAccessGrantAuthorization(
-        c,
-        deps,
-        workspaceId,
-        "api_keys:manage",
-      );
+      const authorization = await requireWorkspaceApiKeyControl(c, deps, workspaceId);
       const grant = authorization.grant;
       const body = c.req.valid("json");
       const permissions: Permission[] =
@@ -120,7 +145,7 @@ export function registerApiKeyRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.delete("/v1/workspaces/:workspaceId/api-keys/:apiKeyId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "api_keys:manage");
+    await requireWorkspaceApiKeyControl(c, deps, workspaceId);
     return c.json(await revokeApiKey(deps.db, workspaceId, c.req.param("apiKeyId")));
   });
 
@@ -143,7 +168,26 @@ export function registerApiKeyRoutes(app: Hono, deps: ApiRouteDeps): void {
       const context = await requireAccessContext(c, deps);
       requireOrganizationApiKeyControlPermission(context, organizationId);
       const body = c.req.valid("json");
+      const rawBody: Record<string, unknown> = await c.req.json();
+      if (body.policy && (rawBody.access !== undefined || rawBody.preset !== undefined))
+        throw new HTTPException(400, {
+          message: "Choose either a policy or a legacy access tier/preset",
+        });
       const token = generateApiKeyToken();
+      const permissions =
+        body.policy?.permissions ??
+        (body.preset === "developer_setup"
+          ? [...DEVELOPER_SETUP_API_KEY_PRESET.permissions]
+          : organizationApiKeyPermissionsForAccess(body.access));
+      ensureOrganizationPolicyDelegable(
+        context,
+        body.policy ?? {
+          preset: "custom",
+          permissions,
+          workspaceScope: { kind: "all" },
+        },
+        !body.policy,
+      );
       try {
         const apiKey = await createOrganizationApiKeyRecord(deps.db, {
           accountId: organizationId,
@@ -151,10 +195,13 @@ export function registerApiKeyRoutes(app: Hono, deps: ApiRouteDeps): void {
           description: body.description ?? null,
           prefix: token.slice(0, 14),
           keyHash: await sha256Hex(token),
-          permissions: organizationApiKeyPermissionsForAccess(body.access),
-          expiresAt: body.expiresAt ? new Date(body.expiresAt) : null,
+          permissions,
+          ...(body.policy ? { policy: body.policy } : {}),
+          expiresAt: organizationApiKeyExpiryDate(body),
           maxActiveKeys: organizationApiKeyLimit(deps),
           rotationSourceApiKeyId: authenticatedApiKeyId(context),
+          serviceAccountId: body.serviceAccountId ?? null,
+          createdBySubjectId: context.subjectId,
         });
         return c.json(
           CreateApiKeyResponse.parse({ apiKey: withOrganizationApiKeyAccess(apiKey), token }),
@@ -164,6 +211,44 @@ export function registerApiKeyRoutes(app: Hono, deps: ApiRouteDeps): void {
         if (error instanceof OrganizationApiKeyLimitExceededError) {
           throw new HTTPException(429, { message: error.message });
         }
+        if (error instanceof OrganizationApiKeyWorkspaceScopeError)
+          throw new HTTPException(400, { message: error.message });
+        throwServiceAccountError(error);
+        throw error;
+      }
+    },
+  );
+
+  app.get("/v1/organizations/:organizationId/api-keys/:apiKeyId", async (c) => {
+    const organizationId = c.req.param("organizationId");
+    requireOrganizationApiKeyControlPermission(await requireAccessContext(c, deps), organizationId);
+    const apiKey = await getOrganizationApiKey(deps.db, organizationId, c.req.param("apiKeyId"));
+    if (!apiKey) throw new HTTPException(404, { message: "API key not found" });
+    return c.json(withOrganizationApiKeyAccess(apiKey));
+  });
+
+  app.patch(
+    "/v1/organizations/:organizationId/api-keys/:apiKeyId",
+    zValidator("json", UpdateOrganizationApiKeyRequest),
+    async (c) => {
+      const organizationId = c.req.param("organizationId");
+      const context = await requireAccessContext(c, deps);
+      requireOrganizationApiKeyControlPermission(context, organizationId);
+      const body = c.req.valid("json");
+      if (body.policy) ensureOrganizationPolicyDelegable(context, body.policy);
+      try {
+        const apiKey = await updateOrganizationApiKey(
+          deps.db,
+          organizationId,
+          c.req.param("apiKeyId"),
+          body,
+        );
+        if (!apiKey) throw new HTTPException(404, { message: "API key not found" });
+        return c.json(withOrganizationApiKeyAccess(apiKey));
+      } catch (error) {
+        if (error instanceof OrganizationApiKeyWorkspaceScopeError)
+          throw new HTTPException(400, { message: error.message });
+        throwServiceAccountError(error);
         throw error;
       }
     },
@@ -181,6 +266,14 @@ export function registerApiKeyRoutes(app: Hono, deps: ApiRouteDeps): void {
   });
 }
 
+/** Service account problems read as the person would expect. */
+export function throwServiceAccountError(error: unknown): void {
+  if (error instanceof OrganizationServiceAccountNotFoundError)
+    throw new HTTPException(404, { message: error.message });
+  if (error instanceof OrganizationServiceAccountRoleError)
+    throw new HTTPException(400, { message: error.message });
+}
+
 function requireAccountPermission(
   context: AccessContext,
   accountId: string,
@@ -199,8 +292,12 @@ function ensureDelegablePermissions(
   authorization: AccessGrantAuthorization,
   requested: Permission[],
 ): void {
+  requireExplicitPermissionDelegation(authorization.grant, requested);
   const grantPermissions = authorization.grant.permissions;
-  if (grantPermissions.includes("workspace:admin")) {
+  if (
+    grantPermissions.includes("workspace:admin") &&
+    authorization.grant.permissionMode !== "explicit"
+  ) {
     const accountLiteralPermissions = new Set<Permission>([
       "account:read",
       "account:admin",
@@ -228,22 +325,64 @@ function ensureDelegablePermissions(
   }
 }
 
-function requireOrganizationApiKeyControlPermission(
+/** Key management is not a way for a policy credential to amplify itself. */
+function ensureOrganizationPolicyDelegable(
+  context: AccessContext,
+  policy: OrganizationAccessPolicy,
+  legacy = false,
+): void {
+  const authority = accountScopedApiKeyWorkspaceAuthority(context);
+  const source = context.credential?.policy;
+  if (!authority || authority.permissionMode !== "explicit" || !source) return;
+  const requested = legacy
+    ? Permission.options.filter((permission) => hasPermission(policy.permissions, permission))
+    : policy.permissions;
+  if (requested.some((permission) => !source.permissions.includes(permission)))
+    throw new HTTPException(403, {
+      message: "cannot delegate permissions beyond organization key policy",
+    });
+  if (
+    source.workspaceScope.kind === "selected" &&
+    (policy.workspaceScope.kind === "all" ||
+      policy.workspaceScope.workspaceIds.some(
+        (id) => !organizationWorkspaceInScope(source.workspaceScope, id),
+      ))
+  )
+    throw new HTTPException(403, {
+      message: "cannot delegate workspaces beyond organization key scope",
+    });
+}
+
+export function requireOrganizationApiKeyControlPermission(
   context: AccessContext,
   organizationId: string,
 ): void {
+  requireApiKeyManagementContext(context);
   requireAccountPermission(context, organizationId, "api_keys:manage");
   if (!context.subjectId.startsWith("api_key:")) return;
   const authority = accountScopedApiKeyWorkspaceAuthority(context);
   if (
     !authority ||
     authority.accountId !== organizationId ||
-    !authority.permissions.includes("api_keys:manage")
+    (!authority.permissions.includes("api_keys:manage") &&
+      !context.accountGrants.some(
+        (grant) =>
+          grant.accountId === organizationId && grant.permissions.includes("account:admin"),
+      ))
   ) {
     throw new HTTPException(403, { message: "organization API key authority required" });
   }
 }
 
+async function requireWorkspaceApiKeyControl(
+  c: Parameters<typeof requireAccessContext>[0],
+  deps: ApiRouteDeps,
+  workspaceId: string,
+): Promise<AccessGrantAuthorization> {
+  requireApiKeyManagementContext(await requireAccessContext(c, deps));
+  return await requireAccessGrantAuthorization(c, deps, workspaceId, "api_keys:manage");
+}
+
 function authenticatedApiKeyId(context: AccessContext): string | null {
   return context.subjectId.startsWith("api_key:")
     ? context.subjectId.slice("api_key:".length)

package/src/routes/artifact-catalog.ts

@@ -4,6 +4,8 @@ import {
   ArtifactCatalogKind,
   ArtifactCatalogListQuery,
   ArtifactCatalogListResponse,
+  ArtifactPinResponse,
+  UpdateArtifactPinRequest,
   retainedArtifactReferenceFromFile,
   retainedGeneratedImageReferenceFromFile,
   type AccessGrant,
@@ -19,13 +21,17 @@ import {
   requireSessionAuthorization,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
+  siteViewerForGrant,
   type ApiRouteDeps,
 } from "@opengeni/core";
 import {
   getFilesForSubject,
   getGeneratedImageArtifact,
   getSessionAuthorityProjection,
+  isWorkspaceArtifactVisible,
   listArtifactCatalogCandidates,
+  nestedPostgresSqlState,
+  updateArtifactPin,
   withSessionRlsActorContext,
   type ArtifactCatalogCandidate,
   type ArtifactCatalogPosition,
@@ -33,6 +39,7 @@ import {
 } from "@opengeni/db";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
 import { artifactCatalogCursorCodec } from "../artifact-catalog-cursor";
 import {
   editableArtifactActorForGrant,
@@ -51,9 +58,106 @@ const position = (row: ArtifactCatalogCandidate): ArtifactCatalogPosition => ({
   key: row.sort_key,
   kind: row.kind,
   id: row.id,
+  pinned: row.pinned ?? false,
 });
 
 export function registerArtifactCatalogRoutes(app: Hono, deps: Dependencies): void {
+  app.put("/v1/workspaces/:workspaceId/artifact-catalog/:kind/:artifactId/pin", async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(
+      context,
+      deps,
+      workspaceId,
+      "artifacts:publish",
+    );
+    const grant = authorization.grant;
+    if (!hasPermission(grant.permissions, "artifacts:publish"))
+      throw new HTTPException(403, { message: "Artifact publish access required" });
+    const kind = ArtifactCatalogKind.safeParse(context.req.param("kind"));
+    const body = UpdateArtifactPinRequest.safeParse(await context.req.json().catch(() => null));
+    const requestedId = context.req.param("artifactId");
+    if (
+      !kind.success ||
+      !body.success ||
+      !(editableKinds.has(kind.data)
+        ? /^[0-9a-f]{32}$/.test(requestedId)
+        : z.string().uuid().safeParse(requestedId).success)
+    )
+      throw new HTTPException(422, { message: "Invalid artifact pin request" });
+    const artifactId = editableKinds.has(kind.data) ? requestedId : requestedId.toLowerCase();
+    const fileKind = kind.data === "file" || kind.data === "image";
+    if (!hasPermission(grant.permissions, fileKind ? "files:read" : "artifacts:read"))
+      throw new HTTPException(403, { message: "Artifact read access required" });
+    const actor = fileKind
+      ? await fileOwnerContextForAccess(deps, authorization, "files:read")
+      : { subjectId: grant.subjectId, privateFileOwnerSubjectId: null };
+    context.header("cache-control", "private, no-store");
+    return withSessionRlsActorContext(actor, async () => {
+      if (editableKinds.has(kind.data)) {
+        if (!deps.editableArtifacts)
+          throw new HTTPException(503, { message: "Editable artifacts are unavailable" });
+        try {
+          const scope = editableArtifactScope({ accountId: grant.accountId, workspaceId });
+          const artifact = await deps.editableArtifacts.readArtifact({
+            scope,
+            actor: editableArtifactActorForGrant(grant, "0000000000000001"),
+            artifactId: editableArtifactId(artifactId),
+          });
+          if (
+            artifact.scope.accountId !== scope.accountId ||
+            artifact.scope.workspaceId !== scope.workspaceId ||
+            artifact.id !== artifactId ||
+            artifact.modality !== kind.data
+          )
+            throw new HTTPException(404, { message: "Artifact not found" });
+        } catch (error) {
+          if (isInvisibleListCandidate(error))
+            throw new HTTPException(404, { message: "Artifact not found" });
+          throw editableArtifactHttpError(error);
+        }
+      }
+      // An Only me Site someone else owns answers exactly like a missing one.
+      if (
+        kind.data === "site" &&
+        !(await isWorkspaceArtifactVisible(
+          deps.db,
+          workspaceId,
+          await siteViewerForGrant(deps.db, grant),
+          artifactId,
+        ))
+      )
+        throw new HTTPException(404, { message: "Artifact not found" });
+      if (fileKind) {
+        const subjectId = await fileAuthoritySubjectIdForGrant(deps, grant);
+        const [file] = await getFilesForSubject(deps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          subjectId,
+          fileIds: [artifactId],
+        });
+        if (!file || file.status !== "ready")
+          throw new HTTPException(404, { message: "Artifact not found" });
+      }
+      try {
+        await updateArtifactPin(
+          deps.db,
+          { accountId: grant.accountId, workspaceId },
+          {
+            kind: kind.data,
+            artifactId,
+            pinned: body.data.pinned,
+          },
+        );
+      } catch (error) {
+        if (nestedPostgresSqlState(error) === "42501")
+          throw new HTTPException(404, { message: "Artifact not found" });
+        throw error;
+      }
+      return context.json(
+        ArtifactPinResponse.parse({ kind: kind.data, artifactId, pinned: body.data.pinned }),
+      );
+    });
+  });
   app.get("/v1/workspaces/:workspaceId/artifact-catalog", async (context) => {
     const workspaceId = context.req.param("workspaceId");
     const authorization = await requireAccessGrantAuthorization(context, deps, workspaceId);
@@ -156,6 +260,9 @@ export function registerArtifactCatalogRoutes(app: Hono, deps: Dependencies): vo
       let lastReturned: ArtifactCatalogPosition | undefined;
       let nextCursor: string | null = null;
       const fileSubject = includesFiles ? await fileAuthoritySubjectIdForGrant(deps, grant) : null;
+      const siteViewer = kinds.includes("site")
+        ? await siteViewerForGrant(deps.db, grant)
+        : { subjectId: null };
       for (let batch = 0; batch < MAX_BATCHES; batch++) {
         const candidates = await listArtifactCatalogCandidates(
           deps.db,
@@ -163,6 +270,7 @@ export function registerArtifactCatalogRoutes(app: Hono, deps: Dependencies): vo
           {
             query,
             kinds,
+            siteViewer,
             snapshotAt,
             ...(after ? { after } : {}),
             limit: CANDIDATE_BATCH,
@@ -210,8 +318,11 @@ async function projectCandidate(
     status: row.status,
     createdAt: iso(row.created_at),
     updatedAt: iso(row.updated_at),
+    ...(row.pinned !== undefined ? { pinned: row.pinned } : {}),
   };
   if (row.version_id) item.versionId = row.version_id;
+  if (row.kind === "site")
+    item.visibility = row.site_visibility === "user_private" ? "private" : "workspace";
   if (editableKinds.has(row.kind)) {
     const scope = editableArtifactScope({
       accountId: grant.accountId,