@opengeni/api-router 0.30.3 → 1.0.0

package/src/routes/api-keys.ts

@@ -1,16 +1,112 @@
-import { CreateApiKeyRequest, CreateApiKeyResponse, Permission } from "@opengeni/contracts";
-import { createApiKey, listApiKeys, revokeApiKey } from "@opengeni/db";
+import {
+  CreateApiKeyRequest,
+  CreateApiKeyResponse,
+  CreateOrganizationApiKeyRequest,
+  UpdateOrganizationApiKeyRequest,
+  normalizeOrganizationAccessPolicy,
+  type OrganizationAccessPolicy,
+  DEVELOPER_SETUP_API_KEY_PRESET,
+  Permission,
+  type AccessContext,
+  type ApiKey,
+  type OrganizationApiKeyAccess,
+} from "@opengeni/contracts";
+import {
+  createApiKey,
+  createOrganizationApiKey as createOrganizationApiKeyRecord,
+  listApiKeys,
+  listOrganizationApiKeys,
+  getOrganizationApiKey,
+  updateOrganizationApiKey,
+  OrganizationApiKeyWorkspaceScopeError,
+  OrganizationApiKeyLimitExceededError,
+  OrganizationServiceAccountNotFoundError,
+  OrganizationServiceAccountRoleError,
+  revokeApiKey,
+  revokeOrganizationApiKey,
+} from "@opengeni/db";
+import { configuredStaticUsageLimits } from "@opengeni/config";
 import { zValidator } from "@hono/zod-validator";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import type { ApiRouteDeps } from "@opengeni/core";
-import { requireAccessGrant } from "@opengeni/core";
+import {
+  accountScopedApiKeyWorkspaceAuthority,
+  organizationApiKeyAccess,
+  hasPermission,
+  organizationWorkspaceInScope,
+  requireAccessContext,
+  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",
+  "workspace:create",
+  "workspace:read",
+  "workspace:admin",
+  "api_keys:manage",
+];
+
+/**
+ * Permissions minted onto a `read` organization API key. The key inventories
+ * shared workspaces and reads their sessions, events, and files; it holds no
+ * `workspace:admin` wildcard, so every control, create, and key-management
+ * route denies it, and no `api_keys:manage`, so it cannot mint keys.
+ */
+export const organizationReadApiKeyPermissions: Permission[] = [
+  "account:read",
+  "workspace:read",
+  "sessions:read",
+  "files:read",
+];
+
+export function organizationApiKeyPermissionsForAccess(
+  access: OrganizationApiKeyAccess,
+): Permission[] {
+  return access === "developer_setup"
+    ? [...DEVELOPER_SETUP_API_KEY_PRESET.permissions]
+    : access === "read"
+      ? [...organizationReadApiKeyPermissions]
+      : [...organizationApiKeyPermissions];
+}
+
+/** 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 {
+  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) });
   });
 
@@ -19,11 +115,12 @@ export function registerApiKeyRoutes(app: Hono, deps: ApiRouteDeps): void {
     zValidator("json", CreateApiKeyRequest.omit({ workspaceId: true })),
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
-      const grant = await requireAccessGrant(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[] =
         body.permissions.length > 0 ? (body.permissions as Permission[]) : ["workspace:read"];
-      ensureDelegablePermissions(grant.permissions, permissions);
+      ensureDelegablePermissions(authorization, permissions);
       await requireLimit(deps, {
         accountId: grant.accountId,
         workspaceId,
@@ -36,6 +133,7 @@ export function registerApiKeyRoutes(app: Hono, deps: ApiRouteDeps): void {
         accountId: grant.accountId,
         workspaceId: grant.workspaceId,
         name: body.name,
+        description: body.description ?? null,
         prefix,
         keyHash: await sha256Hex(token),
         permissions,
@@ -47,15 +145,172 @@ 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")));
   });
+
+  app.get("/v1/organizations/:organizationId/api-keys", async (c) => {
+    const organizationId = c.req.param("organizationId");
+    const context = await requireAccessContext(c, deps);
+    requireOrganizationApiKeyControlPermission(context, organizationId);
+    return c.json({
+      apiKeys: (await listOrganizationApiKeys(deps.db, organizationId)).map(
+        withOrganizationApiKeyAccess,
+      ),
+    });
+  });
+
+  app.post(
+    "/v1/organizations/:organizationId/api-keys",
+    zValidator("json", CreateOrganizationApiKeyRequest),
+    async (c) => {
+      const organizationId = c.req.param("organizationId");
+      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,
+          name: body.name,
+          description: body.description ?? null,
+          prefix: token.slice(0, 14),
+          keyHash: await sha256Hex(token),
+          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 }),
+          201,
+        );
+      } catch (error) {
+        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;
+      }
+    },
+  );
+
+  app.delete("/v1/organizations/:organizationId/api-keys/:apiKeyId", async (c) => {
+    const organizationId = c.req.param("organizationId");
+    const context = await requireAccessContext(c, deps);
+    requireOrganizationApiKeyControlPermission(context, organizationId);
+    const apiKey = await revokeOrganizationApiKey(deps.db, organizationId, c.req.param("apiKeyId"));
+    if (!apiKey) {
+      throw new HTTPException(404, { message: "API key not found" });
+    }
+    return c.json(withOrganizationApiKeyAccess(apiKey));
+  });
+}
+
+/** 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,
+  permission: Permission,
+): void {
+  const grant = context.accountGrants.find((candidate) => candidate.accountId === accountId);
+  if (
+    !grant ||
+    (!grant.permissions.includes(permission) && !grant.permissions.includes("account:admin"))
+  ) {
+    throw new HTTPException(403, { message: `missing permission: ${permission}` });
+  }
 }
 
-function ensureDelegablePermissions(grantPermissions: Permission[], requested: Permission[]): void {
-  if (grantPermissions.includes("workspace:admin")) {
+function ensureDelegablePermissions(
+  authorization: AccessGrantAuthorization,
+  requested: Permission[],
+): void {
+  requireExplicitPermissionDelegation(authorization.grant, requested);
+  const grantPermissions = authorization.grant.permissions;
+  if (
+    grantPermissions.includes("workspace:admin") &&
+    authorization.grant.permissionMode !== "explicit"
+  ) {
+    const accountLiteralPermissions = new Set<Permission>([
+      "account:read",
+      "account:admin",
+      "workspace:create",
+      "billing:read",
+      "billing:manage",
+    ]);
+    const workspaceLiteralPermissions = new Set<Permission>(["members:manage", "secrets:read"]);
     const highTrustMissing = requested.filter(
-      (permission) => permission === "secrets:read" && !grantPermissions.includes("secrets:read"),
+      (permission) =>
+        (accountLiteralPermissions.has(permission) &&
+          !authorization.accountGrant?.permissions.includes(permission)) ||
+        (workspaceLiteralPermissions.has(permission) && !grantPermissions.includes(permission)),
     );
     if (highTrustMissing.length === 0) return;
     throw new HTTPException(403, {
@@ -70,6 +325,77 @@ function ensureDelegablePermissions(grantPermissions: Permission[], requested: P
   }
 }
 
+/** 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") &&
+      !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)
+    : null;
+}
+
+function organizationApiKeyLimit(deps: ApiRouteDeps): number | null {
+  if (deps.settings.usageLimitsMode !== "static" && deps.settings.usageLimitsMode !== "managed") {
+    return null;
+  }
+  return configuredStaticUsageLimits(deps.settings).maxApiKeysPerWorkspace ?? null;
+}
+
 function generateApiKeyToken(): string {
   const bytes = new Uint8Array(32);
   crypto.getRandomValues(bytes);

package/src/routes/artifact-catalog.ts

@@ -0,0 +1,279 @@
+import { resolveFirstPartyDelegationSecret } from "@opengeni/config";
+import {
+  ArtifactCatalogItem,
+  ArtifactCatalogKind,
+  ArtifactCatalogListQuery,
+  ArtifactCatalogListResponse,
+  retainedArtifactReferenceFromFile,
+  retainedGeneratedImageReferenceFromFile,
+  type AccessGrant,
+} from "@opengeni/contracts";
+import {
+  editableArtifactId,
+  editableArtifactScope,
+  fileOwnerContextForAccess,
+  grantHasAgentAttemptAuthority,
+  hasPermission,
+  requireAccessGrantAuthorization,
+  requireLiveAgentAttemptAuthorization,
+  requireSessionAuthorization,
+  SessionAuthorizationDeniedError,
+  SessionAuthorizationUnavailableError,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  getFilesForSubject,
+  getGeneratedImageArtifact,
+  getSessionAuthorityProjection,
+  listArtifactCatalogCandidates,
+  withSessionRlsActorContext,
+  type ArtifactCatalogCandidate,
+  type ArtifactCatalogPosition,
+  type SessionRlsActorContext,
+} from "@opengeni/db";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { artifactCatalogCursorCodec } from "../artifact-catalog-cursor";
+import {
+  editableArtifactActorForGrant,
+  editableArtifactHttpError,
+  isInvisibleListCandidate,
+  type EditableArtifactRouteDependencies,
+} from "./editable-artifacts";
+import { fileAuthoritySubjectIdForGrant } from "./files";
+
+type Dependencies = ApiRouteDeps & EditableArtifactRouteDependencies;
+const editableKinds = new Set(["document", "spreadsheet", "presentation"]);
+const CANDIDATE_BATCH = 200;
+const MAX_BATCHES = 10;
+const iso = (value: Date | string) => new Date(value).toISOString();
+const position = (row: ArtifactCatalogCandidate): ArtifactCatalogPosition => ({
+  key: row.sort_key,
+  kind: row.kind,
+  id: row.id,
+});
+
+export function registerArtifactCatalogRoutes(app: Hono, deps: Dependencies): void {
+  app.get("/v1/workspaces/:workspaceId/artifact-catalog", async (context) => {
+    const workspaceId = context.req.param("workspaceId");
+    const authorization = await requireAccessGrantAuthorization(context, deps, workspaceId);
+    const grant = authorization.grant;
+    const parsed = ArtifactCatalogListQuery.safeParse(context.req.query());
+    if (!parsed.success)
+      throw new HTTPException(422, { message: "Invalid artifact catalog query" });
+    const query = parsed.data;
+    const artifactsAllowed = hasPermission(grant.permissions, "artifacts:read");
+    const filesAllowed = hasPermission(grant.permissions, "files:read");
+    if (!artifactsAllowed && !filesAllowed)
+      throw new HTTPException(403, { message: "Artifact catalog read access required" });
+    let kinds = ArtifactCatalogKind.options.filter(
+      (kind) =>
+        (kind === "image" || kind === "file" ? filesAllowed : artifactsAllowed) &&
+        (!query.kind || kind === query.kind),
+    );
+    if (!deps.editableArtifacts) {
+      if (query.kind && editableKinds.has(query.kind) && artifactsAllowed)
+        throw new HTTPException(503, { message: "Editable artifacts are unavailable" });
+      kinds = kinds.filter((kind) => !editableKinds.has(kind));
+    }
+    const includesFiles = kinds.includes("file") || kinds.includes("image");
+    const actor: SessionRlsActorContext = includesFiles
+      ? await fileOwnerContextForAccess(deps, authorization, "files:read")
+      : { subjectId: grant.subjectId, privateFileOwnerSubjectId: null };
+    // Session visibility follows the frozen live initiator independently of
+    // which artifact domains were selected. Never infer it from token labels
+    // or require file ownership merely to discover Sites/editable artifacts.
+    if (grantHasAgentAttemptAuthority(grant) && actor.initiatingHumanSubjectId === undefined) {
+      const callerSessionId = grant.metadata?.["sessionId"];
+      try {
+        if (typeof callerSessionId !== "string")
+          throw new SessionAuthorizationDeniedError("caller_stale");
+        const attempt = await requireLiveAgentAttemptAuthorization(deps.db, grant, callerSessionId);
+        actor.initiatingHumanSubjectId = attempt.initiatingHumanSubjectId;
+      } catch (error) {
+        if (error instanceof SessionAuthorizationDeniedError)
+          throw new HTTPException(404, { message: "Session not found", cause: error });
+        throw error;
+      }
+    }
+    const sourceDecisions = new Map<string, boolean>();
+    const canReadSession = async (sessionId: string): Promise<boolean> => {
+      if (!hasPermission(grant.permissions, "sessions:read")) return false;
+      if (sourceDecisions.has(sessionId)) return sourceDecisions.get(sessionId)!;
+      try {
+        await requireSessionAuthorization(deps, grant, {
+          sessionId,
+          operation: "session.read",
+          surface: "http",
+        });
+        // The optional-host seam can return null for both a shared standalone
+        // session and an RLS-hidden/missing row. Prove visibility independently
+        // AFTER it, so a permissive null is never itself provenance authority.
+        if (!(await getSessionAuthorityProjection(deps.db, workspaceId, sessionId))) {
+          sourceDecisions.set(sessionId, false);
+          return false;
+        }
+        sourceDecisions.set(sessionId, true);
+        return true;
+      } catch (error) {
+        if (error instanceof SessionAuthorizationDeniedError) {
+          sourceDecisions.set(sessionId, false);
+          return false;
+        }
+        if (error instanceof SessionAuthorizationUnavailableError)
+          throw new HTTPException(503, { message: "Session authorization is unavailable" });
+        throw error;
+      }
+    };
+    context.header("cache-control", "private, no-store");
+    return withSessionRlsActorContext(actor, async () => {
+      if (query.sourceSessionId && !(await canReadSession(query.sourceSessionId)))
+        throw new HTTPException(404, { message: "Session not found" });
+      const secret = resolveFirstPartyDelegationSecret(deps.settings);
+      if (!secret)
+        throw new HTTPException(503, { message: "Artifact catalog cursor signing is unavailable" });
+      const filters = { ...query, cursor: undefined };
+      const codec = artifactCatalogCursorCodec(
+        secret,
+        JSON.stringify({
+          accountId: grant.accountId,
+          workspaceId,
+          subjectId: grant.subjectId,
+          principalKind: grant.principalKind,
+          metadata: grant.metadata,
+          permissions: [...grant.permissions].sort(),
+          initiatingHumanSubjectId: actor.initiatingHumanSubjectId ?? null,
+          owner: actor.privateFileOwnerSubjectId ?? null,
+          kinds,
+          filters,
+        }),
+      );
+      const prior = query.cursor ? codec.decode(query.cursor) : undefined;
+      const snapshotAt = prior?.snapshotAt ?? new Date().toISOString();
+      const expiresAt = prior?.expiresAt ?? Date.now() + 60 * 60_000;
+      let after = prior?.after;
+      const items: ArtifactCatalogItem[] = [];
+      let lastReturned: ArtifactCatalogPosition | undefined;
+      let nextCursor: string | null = null;
+      const fileSubject = includesFiles ? await fileAuthoritySubjectIdForGrant(deps, grant) : null;
+      for (let batch = 0; batch < MAX_BATCHES; batch++) {
+        const candidates = await listArtifactCatalogCandidates(
+          deps.db,
+          { accountId: grant.accountId, workspaceId },
+          {
+            query,
+            kinds,
+            snapshotAt,
+            ...(after ? { after } : {}),
+            limit: CANDIDATE_BATCH,
+          },
+        );
+        for (const candidate of candidates) {
+          after = position(candidate);
+          const item = await projectCandidate(deps, grant, candidate, fileSubject);
+          if (
+            !item ||
+            item.status !== query.status ||
+            (query.q && !item.title.toLowerCase().includes(query.q.toLowerCase()))
+          )
+            continue;
+          if (items.length === query.limit) {
+            nextCursor = codec.encode({ version: 1, snapshotAt, expiresAt, after: lastReturned! });
+            return context.json(ArtifactCatalogListResponse.parse({ items, nextCursor }));
+          }
+          if (candidate.source_session_id && (await canReadSession(candidate.source_session_id)))
+            item.sourceSessionId = candidate.source_session_id;
+          items.push(ArtifactCatalogItem.parse(item));
+          lastReturned = after;
+        }
+        if (candidates.length < CANDIDATE_BATCH) break;
+        // Bounded scanning may produce an empty page; the encrypted frontier
+        // reveals neither denied identity nor provenance and can be continued.
+        if (batch === MAX_BATCHES - 1 && after)
+          nextCursor = codec.encode({ version: 1, snapshotAt, expiresAt, after });
+      }
+      return context.json(ArtifactCatalogListResponse.parse({ items, nextCursor }));
+    });
+  });
+}
+
+async function projectCandidate(
+  deps: Dependencies,
+  grant: AccessGrant,
+  row: ArtifactCatalogCandidate,
+  fileSubject: string | null,
+): Promise<ArtifactCatalogItem | null> {
+  const item: ArtifactCatalogItem = {
+    id: row.id,
+    kind: row.kind,
+    title: row.title,
+    status: row.status,
+    createdAt: iso(row.created_at),
+    updatedAt: iso(row.updated_at),
+  };
+  if (row.version_id) item.versionId = row.version_id;
+  if (editableKinds.has(row.kind)) {
+    const scope = editableArtifactScope({
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+    });
+    try {
+      // This is the HTTP application's read-only domain.getArtifact seam, NOT
+      // EditableArtifactAgentApplication.read (which touches session links).
+      const artifact = await deps.editableArtifacts!.readArtifact({
+        scope,
+        actor: editableArtifactActorForGrant(grant, "0000000000000001"),
+        artifactId: editableArtifactId(row.id),
+      });
+      if (
+        artifact.scope.accountId !== scope.accountId ||
+        artifact.scope.workspaceId !== scope.workspaceId ||
+        artifact.id !== row.id ||
+        artifact.modality !== row.kind
+      )
+        throw new Error("Artifact application returned mismatched catalog metadata");
+      return {
+        ...item,
+        title: artifact.title,
+        status: artifact.lifecycle,
+        createdAt: artifact.createdAt,
+        updatedAt: artifact.updatedAt,
+      };
+    } catch (error) {
+      if (isInvisibleListCandidate(error)) return null;
+      throw editableArtifactHttpError(error);
+    }
+  }
+  if (row.kind === "file" || row.kind === "image") {
+    const [file] = await getFilesForSubject(deps.db, {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      subjectId: fileSubject,
+      fileIds: [row.id],
+    });
+    if (!file || file.status !== "ready") return null;
+    const generated =
+      row.origin === "generated_image"
+        ? await getGeneratedImageArtifact(deps.db, grant.workspaceId, row.id)
+        : null;
+    const reference =
+      row.origin === "generated_image"
+        ? generated?.status === "ready"
+          ? retainedGeneratedImageReferenceFromFile({
+              ...file,
+              width: generated.width,
+              height: generated.height,
+            })
+          : null
+        : retainedArtifactReferenceFromFile(file, "file");
+    if (!reference) return null;
+    return {
+      ...item,
+      file: reference,
+      filename: file.filename,
+      contentType: reference.contentType,
+      sizeBytes: file.sizeBytes,
+    };
+  }
+  return item;
+}