@anthusai/papyrus 1.0.0-next.3 → 1.0.0-next.4

package/infra/site-config.ts

@@ -0,0 +1,163 @@
+export type AmplifyAppShellSiteConfig = {
+  siteId: string;
+  repository: string;
+  brand: string;
+  frontend: "pretext" | "markus-static";
+  hostedZoneId: string;
+  cms: {
+    appName?: string;
+    domainName: string;
+    buildComputeType?: "STANDARD" | "STANDARD_8GB";
+    environment: Record<string, string>;
+    stagingDomainName?: string;
+  };
+  reader?: {
+    appName?: string;
+    domainName: string;
+    branchName?: string;
+    buildCommand: string;
+    baseDirectory: string;
+    environment?: Record<string, string>;
+  };
+  papyrusVersion: string;
+  storagePreviewPrefix?: string;
+};
+
+const SITE_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const REPOSITORY_PATTERN = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const HOSTED_ZONE_ID_PATTERN = /^Z[A-Z0-9]+$/;
+const HOST_NAME_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
+const APP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.-]*$/;
+const BRANCH_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9/_.-]*$/;
+const PAPYRUS_VERSION_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+\.\d+)?$/;
+const LOCAL_DEVELOPMENT_ORIGIN = "http://localhost:3001/";
+
+function fail(field: string, problem: string): never {
+  throw new Error(`site.json: ${field} ${problem}`);
+}
+
+function requireObject(value: unknown, field: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    fail(field, "must be an object");
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireString(value: unknown, field: string, pattern?: RegExp, patternHint?: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    fail(field, "must be a non-empty string");
+  }
+  if (pattern && !pattern.test(value as string)) {
+    fail(field, `is invalid${patternHint ? ` (${patternHint})` : ""}: ${JSON.stringify(value)}`);
+  }
+  return value as string;
+}
+
+function optionalString(value: unknown, field: string, pattern?: RegExp, patternHint?: string): string | undefined {
+  return value === undefined ? undefined : requireString(value, field, pattern, patternHint);
+}
+
+function requireStringRecord(value: unknown, field: string): Record<string, string> {
+  const record = requireObject(value, field);
+  const result: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(record)) {
+    if (typeof entry !== "string") fail(`${field}.${key}`, "must be a string");
+    result[key] = entry as string;
+  }
+  return result;
+}
+
+function rejectUnknownKeys(record: Record<string, unknown>, allowed: string[], field: string): void {
+  for (const key of Object.keys(record)) {
+    if (!allowed.includes(key)) fail(`${field}.${key}`, `is not a known field (known: ${allowed.join(", ")})`);
+  }
+}
+
+export function resolveStagingDomainName(config: Pick<AmplifyAppShellSiteConfig, "cms">): string {
+  if (config.cms.stagingDomainName) return config.cms.stagingDomainName;
+  const [, ...rest] = config.cms.domainName.split(".");
+  return ["staging", ...rest].join(".");
+}
+
+export function resolveStoragePreviewPrefix(config: Pick<AmplifyAppShellSiteConfig, "storagePreviewPrefix">): string {
+  return config.storagePreviewPrefix ?? "preview/";
+}
+
+export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
+  const record = requireObject(raw, "site");
+  rejectUnknownKeys(
+    record,
+    ["siteId", "repository", "brand", "frontend", "hostedZoneId", "cms", "reader", "papyrusVersion", "storagePreviewPrefix"],
+    "site",
+  );
+
+  const siteId = requireString(record.siteId, "siteId", SITE_ID_PATTERN, "kebab-case");
+  const repository = requireString(record.repository, "repository", REPOSITORY_PATTERN, "https://github.com/<org>/<repo>");
+  const brand = requireString(record.brand, "brand");
+  const frontend = requireString(record.frontend, "frontend");
+  if (frontend !== "pretext" && frontend !== "markus-static") {
+    fail("frontend", `must be "pretext" or "markus-static", got ${JSON.stringify(frontend)}`);
+  }
+  const hostedZoneId = requireString(record.hostedZoneId, "hostedZoneId", HOSTED_ZONE_ID_PATTERN, "Route 53 zone id");
+  const papyrusVersion = requireString(record.papyrusVersion, "papyrusVersion", PAPYRUS_VERSION_PATTERN, "exact version such as 1.0.0 or 1.0.0-next.1");
+  const storagePreviewPrefix = optionalString(record.storagePreviewPrefix, "storagePreviewPrefix", /^[A-Za-z0-9._-]+\/$/, "must end with /");
+
+  const cmsRecord = requireObject(record.cms, "cms");
+  rejectUnknownKeys(cmsRecord, ["appName", "domainName", "buildComputeType", "environment", "stagingDomainName"], "cms");
+  const buildComputeType = cmsRecord.buildComputeType;
+  if (buildComputeType !== undefined && buildComputeType !== "STANDARD" && buildComputeType !== "STANDARD_8GB") {
+    fail("cms.buildComputeType", `must be "STANDARD" or "STANDARD_8GB", got ${JSON.stringify(buildComputeType)}`);
+  }
+  const cms: AmplifyAppShellSiteConfig["cms"] = {
+    appName: optionalString(cmsRecord.appName, "cms.appName", APP_NAME_PATTERN),
+    domainName: requireString(cmsRecord.domainName, "cms.domainName", HOST_NAME_PATTERN, "host name"),
+    buildComputeType: buildComputeType as "STANDARD" | "STANDARD_8GB" | undefined,
+    environment: requireStringRecord(cmsRecord.environment, "cms.environment"),
+    stagingDomainName: optionalString(cmsRecord.stagingDomainName, "cms.stagingDomainName", HOST_NAME_PATTERN, "host name"),
+  };
+
+  let reader: AmplifyAppShellSiteConfig["reader"];
+  if (record.reader !== undefined) {
+    if (frontend !== "markus-static") fail("reader", `is only allowed when frontend is "markus-static"`);
+    const readerRecord = requireObject(record.reader, "reader");
+    rejectUnknownKeys(readerRecord, ["appName", "domainName", "branchName", "buildCommand", "baseDirectory", "environment"], "reader");
+    reader = {
+      appName: optionalString(readerRecord.appName, "reader.appName", APP_NAME_PATTERN),
+      domainName: requireString(readerRecord.domainName, "reader.domainName", HOST_NAME_PATTERN, "host name"),
+      branchName: optionalString(readerRecord.branchName, "reader.branchName", BRANCH_NAME_PATTERN),
+      buildCommand: requireString(readerRecord.buildCommand, "reader.buildCommand"),
+      baseDirectory: requireString(readerRecord.baseDirectory, "reader.baseDirectory"),
+      environment: readerRecord.environment === undefined ? undefined : requireStringRecord(readerRecord.environment, "reader.environment"),
+    };
+  } else if (frontend === "markus-static") {
+    fail("reader", `is required when frontend is "markus-static"`);
+  }
+
+  const config: AmplifyAppShellSiteConfig = {
+    siteId,
+    repository,
+    brand,
+    frontend,
+    hostedZoneId,
+    cms,
+    reader,
+    papyrusVersion,
+    storagePreviewPrefix,
+  };
+
+  const redirectValue = cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS;
+  if (redirectValue === undefined) fail("cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS", "is required");
+  const redirectUrls = redirectValue.split(",").map((url) => url.trim());
+  const requiredOrigins = [
+    `https://${cms.domainName}/`,
+    `https://${resolveStagingDomainName(config)}/`,
+    LOCAL_DEVELOPMENT_ORIGIN,
+  ];
+  for (const origin of requiredOrigins) {
+    if (!redirectUrls.includes(origin)) {
+      fail("cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS", `must include ${origin}`);
+    }
+  }
+
+  return config;
+}

package/lib/cached-content-repository.ts

@@ -10,6 +10,7 @@ import type {
 } from "./content-types";
 import { graphqlContentRepository } from "./graphql-content-repository";
 import { READER_REVALIDATE_SECONDS } from "./reader-route-config";
+import { getContentSource } from "./site-env";
 
 const bypassReaderCacheInDevelopment = process.env.NODE_ENV === "development";
 
@@ -34,7 +35,7 @@ function withReaderCache<T>(
   tags: string[],
   loader: () => Promise<T>,
 ): Promise<T> {
-  if (bypassReaderCacheInDevelopment) return loader();
+  if (bypassReaderCacheInDevelopment || getContentSource() === "drafts") return loader();
   return unstable_cache(loader, cacheKey, {
     tags,
     revalidate: READER_REVALIDATE_SECONDS,

package/lib/content-repository.ts

@@ -1,6 +1,9 @@
 import type { ContentRepository } from "./content-types";
 import { graphqlContentRepository } from "./graphql-content-repository";
 import { getLayoutScenario } from "./layout-scenarios";
+import { assertContentSourceMatchesEnv } from "./site-env";
+
+assertContentSourceMatchesEnv();
 
 export const contentRepository: ContentRepository = {
   loadEditionContent({ scenarioId, editionDate, editionSlug } = {}) {

package/lib/content-source-context.ts

@@ -0,0 +1,16 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { getContentSource, type ContentSource } from "./site-env";
+
+export type ContentSourceContext = {
+  source: ContentSource;
+};
+
+const contentSourceStorage = new AsyncLocalStorage<ContentSourceContext>();
+
+export function runWithContentSource<T>(source: ContentSource, operation: () => Promise<T>): Promise<T> {
+  return contentSourceStorage.run({ source }, operation);
+}
+
+export function currentContentSource(): ContentSource {
+  return contentSourceStorage.getStore()?.source ?? getContentSource();
+}

package/lib/graphql-content-repository.ts

@@ -17,11 +17,13 @@ import {
 } from "./publication-items";
 import { BodyIrError, matchBodyImages, projectBodyIr, type BodyProjection, type BodyProjectionImage } from "./markus-body";
 import { SITE_BRAND } from "./site-brand";
+import { currentContentSource, runWithContentSource } from "./content-source-context";
+import { getContentSource } from "./site-env";
 
-const AUTH_MODE = "identityPool";
 const DEFAULT_EDITION_SLUG = "current";
 const PUBLISHED_STATUS = "published";
-const ARTICLE_TYPE_STATUS = "article#published";
+const DRAFT_STATUS = "draft";
+const ARTICLE_TYPE = "article";
 
 type DataClient = ReturnType<typeof generateClient<Schema>>;
 type EditionPublishedAtIndexQuery = (
@@ -64,8 +66,6 @@ type GraphQLEditionItem = {
 
 type GraphQLItem = {
   id: string;
-  sourceItemId?: string | null;
-  itemLineageId?: string | null;
   versionNumber?: number | null;
   type: string;
   status: string;
@@ -133,19 +133,32 @@ const IMAGE_ROLES: NonNullable<ArticleImageAsset["roles"]> = [
 let readerContextClient: DataClient | null = null;
 let buildTimeClient: DataClient | null = null;
 
+function authMode(): "userPool" | "identityPool" {
+  return currentContentSource() === "drafts" ? "userPool" : "identityPool";
+}
+
+function isVisibleItemStatus(status: string): boolean {
+  if (status === PUBLISHED_STATUS) return true;
+  return currentContentSource() === "drafts" && status === DRAFT_STATUS;
+}
+
 async function withReaderGraphQLContext<T>(operation: () => Promise<T>): Promise<T> {
   const { runWithAmplifyServerContext } = getAmplifyServerRuntime();
-  return runWithAmplifyServerContext({
-    nextServerContext: null,
-    operation: async () => {
-      readerContextClient = generateClient<Schema>({ authMode: AUTH_MODE });
-      try {
-        return await operation();
-      } finally {
-        readerContextClient = null;
-      }
-    },
-  });
+  const source = getContentSource();
+  const nextServerContext = source === "drafts" ? { cookies: (await import("next/headers")).cookies } : null;
+  return runWithContentSource(source, () =>
+    runWithAmplifyServerContext({
+      nextServerContext,
+      operation: async () => {
+        readerContextClient = generateClient<Schema>({ authMode: authMode() });
+        try {
+          return await operation();
+        } finally {
+          readerContextClient = null;
+        }
+      },
+    }),
+  );
 }
 
 export const graphqlContentRepository: ContentRepository = {
@@ -200,7 +213,7 @@ export const graphqlContentRepository: ContentRepository = {
   getArticle(slug) {
     return withReaderGraphQLContext(async () => {
       const item = await getItemBySlug(slug);
-      if (!item || item.type !== "article" || item.status !== "published") return undefined;
+      if (!item || item.type !== ARTICLE_TYPE || !isVisibleItemStatus(item.status)) return undefined;
       return normalizeArticle(item, await listMediaAssets(item.id));
     });
   },
@@ -218,9 +231,9 @@ export const graphqlContentRepository: ContentRepository = {
 
   listArticleSlugs() {
     return withReaderGraphQLContext(async () => {
-      const items = await listItemsByTypeStatus(ARTICLE_TYPE_STATUS);
+      const items = await listItemsByTypeStatus(`${ARTICLE_TYPE}#${PUBLISHED_STATUS}`);
       return items
-        .filter((item) => item.type === "article" && item.status === "published")
+        .filter((item) => item.type === ARTICLE_TYPE && isVisibleItemStatus(item.status))
         .map((item) => item.slug)
         .sort();
     });
@@ -232,7 +245,7 @@ function getClient(): DataClient {
 
   if (!buildTimeClient) {
     getAmplifyServerRuntime();
-    buildTimeClient = generateClient<Schema>({ authMode: AUTH_MODE });
+    buildTimeClient = generateClient<Schema>({ authMode: authMode() });
   }
   return buildTimeClient;
 }
@@ -331,7 +344,7 @@ async function loadEditionContentFromEdition(edition: GraphQLEdition): Promise<E
     await Promise.all(
       editionItems.map(async (editionItem) => {
         const item = await getItemById(editionItem.publishedItemId);
-        if (!item || item.status !== PUBLISHED_STATUS) return null;
+        if (!item || !isVisibleItemStatus(item.status)) return null;
         return normalizePublicationItem(item, await listMediaAssets(item.id));
       }),
     )
@@ -344,7 +357,7 @@ async function loadEditionContentFromEdition(edition: GraphQLEdition): Promise<E
       await Promise.all(
         missingLayoutItems.map(async (itemId) => {
           const item = await getItemBySlug(itemId);
-          if (!item || item.status !== PUBLISHED_STATUS) return null;
+          if (!item || !isVisibleItemStatus(item.status)) return null;
           return normalizePublicationItem(item, await listMediaAssets(item.id));
         }),
       )
@@ -461,7 +474,7 @@ async function loadEditionItem(editionDate: string, itemSlug: string): Promise<P
   const editionItems = await listEditionItems(edition.id);
   for (const editionItem of editionItems) {
     const item = await getItemById(editionItem.publishedItemId);
-    if (!item || item.slug !== itemSlug || item.status !== PUBLISHED_STATUS) continue;
+    if (!item || item.slug !== itemSlug || !isVisibleItemStatus(item.status)) continue;
     return (await normalizePublicationItem(item, await listMediaAssets(item.id))) ?? undefined;
   }
   return undefined;
@@ -505,36 +518,168 @@ function isMissingReaderBackendError(error: unknown): boolean {
 }
 
 function getEditionPublishedAtIndexQuery(): EditionPublishedAtIndexQuery | null {
-  const editionModel = getPublishedEditionModel() as unknown as {
-    listPublishedEditionsByStatusAndPublishedAt?: EditionPublishedAtIndexQuery;
-  };
+  const editionModel = getPublishedEditionModel();
   return typeof editionModel.listPublishedEditionsByStatusAndPublishedAt === "function"
     ? editionModel.listPublishedEditionsByStatusAndPublishedAt
     : null;
 }
 
-function getPublishedEditionModel() {
+type ListOptions = Record<string, unknown>;
+type ListResponse<T> = Promise<GraphQLListResponse<T>>;
+
+type EditionSourceModel = {
+  publishedEditionBySlug: (input: { slug: string }, options: ListOptions) => ListResponse<GraphQLEdition>;
+  listPublishedEditionsByStatusAndEditionDate: (
+    input: { status: string; editionDate?: { eq: string } },
+    options: ListOptions,
+  ) => ListResponse<GraphQLEdition>;
+  listPublishedEditionsByStatusAndPublishedAt?: EditionPublishedAtIndexQuery;
+};
+
+type EditionItemSourceModel = {
+  listPublishedEditionItemsByEditionAndSortKey: (
+    input: { publishedEditionId: string },
+    options: ListOptions,
+  ) => ListResponse<GraphQLEditionItem>;
+};
+
+type ItemSourceModel = {
+  get: (input: { id: string }, options: ListOptions) => Promise<GraphQLGetResponse<GraphQLItem>>;
+  publishedItemBySlug: (input: { slug: string }, options: ListOptions) => ListResponse<GraphQLItem>;
+  listPublishedItemsByTypeStatusAndPublishedAt: (input: { typeStatus: string }, options: ListOptions) => ListResponse<GraphQLItem>;
+};
+
+type MediaAssetSourceModel = {
+  listPublishedMediaAssetsByItemAndSortKey: (
+    input: { publishedItemId: string },
+    options: ListOptions,
+  ) => ListResponse<GraphQLMediaAsset>;
+};
+
+const DRAFTS_EDITION_STATUSES = [PUBLISHED_STATUS, DRAFT_STATUS];
+
+async function listMergedAcrossStatuses<T>(
+  statuses: string[],
+  runForStatus: (status: string, pageOptions: ListOptions) => ListResponse<T>,
+  sortValue: (row: T) => string,
+  options: ListOptions,
+): ListResponse<T> {
+  const rows: T[] = [];
+  for (const status of statuses) {
+    let pageToken: string | null | undefined;
+    do {
+      const response = await runForStatus(status, { authMode: options.authMode, limit: 100, nextToken: pageToken });
+      if (response.errors?.length) return { data: [], errors: response.errors };
+      rows.push(...((response.data ?? []).filter(Boolean) as T[]));
+      pageToken = response.nextToken;
+    } while (pageToken);
+  }
+  const direction = options.sortDirection === "DESC" ? -1 : 1;
+  rows.sort((left, right) => direction * sortValue(left).localeCompare(sortValue(right)));
+  const offset = Number(options.nextToken ?? 0) || 0;
+  const limit = typeof options.limit === "number" ? options.limit : undefined;
+  const end = limit === undefined ? rows.length : offset + limit;
+  return {
+    data: rows.slice(offset, end),
+    nextToken: end < rows.length ? String(end) : undefined,
+  };
+}
+
+function getPublishedEditionModel(): EditionSourceModel {
+  if (currentContentSource() === "drafts") {
+    const model = getClient().models.Edition;
+    if (!model) throw missingProjectionModelError("Edition");
+    return {
+      publishedEditionBySlug: (input, options) => model.editionBySlug(input, options) as ListResponse<GraphQLEdition>,
+      listPublishedEditionsByStatusAndEditionDate: (input, options) =>
+        listMergedAcrossStatuses<GraphQLEdition>(
+          DRAFTS_EDITION_STATUSES,
+          (status, pageOptions) =>
+            model.listEditionsByStatusAndEditionDate({ ...input, status }, pageOptions) as ListResponse<GraphQLEdition>,
+          (edition) => edition.editionDate,
+          options,
+        ),
+    };
+  }
   const model = getClient().models.PublishedEdition;
   if (!model) throw missingProjectionModelError("PublishedEdition");
-  return model;
+  return model as unknown as EditionSourceModel;
 }
 
-function getPublishedEditionItemModel() {
+function getPublishedEditionItemModel(): EditionItemSourceModel {
+  if (currentContentSource() === "drafts") {
+    const model = getClient().models.EditionItem;
+    if (!model) throw missingProjectionModelError("EditionItem");
+    return {
+      listPublishedEditionItemsByEditionAndSortKey: async ({ publishedEditionId }, options) => {
+        const response = (await model.listEditionItemsByEditionAndSortKey(
+          { editionId: publishedEditionId },
+          options,
+        )) as unknown as GraphQLListResponse<{ id: string; editionId: string; itemId: string; sortKey: string }>;
+        return {
+          ...response,
+          data: (response.data ?? []).filter(Boolean).map((row) => ({
+            id: row.id,
+            publishedEditionId: row.editionId,
+            publishedItemId: row.itemId,
+            sortKey: row.sortKey,
+          })),
+        };
+      },
+    };
+  }
   const model = getClient().models.PublishedEditionItem;
   if (!model) throw missingProjectionModelError("PublishedEditionItem");
-  return model;
+  return model as unknown as EditionItemSourceModel;
 }
 
-function getPublishedItemModel() {
+function getPublishedItemModel(): ItemSourceModel {
+  if (currentContentSource() === "drafts") {
+    const model = getClient().models.Item;
+    if (!model) throw missingProjectionModelError("Item");
+    return {
+      get: (input, options) => model.get(input, options) as Promise<GraphQLGetResponse<GraphQLItem>>,
+      publishedItemBySlug: (input, options) => model.itemBySlug(input, options) as ListResponse<GraphQLItem>,
+      listPublishedItemsByTypeStatusAndPublishedAt: ({ typeStatus }, options) => {
+        const itemType = typeStatus.split("#")[0];
+        return listMergedAcrossStatuses<GraphQLItem>(
+          [DRAFT_STATUS, PUBLISHED_STATUS],
+          (status, pageOptions) =>
+            model.listItemsByTypeStatusAndPublishedAt(
+              { typeStatus: `${itemType}#${status}` },
+              pageOptions,
+            ) as ListResponse<GraphQLItem>,
+          (item) => item.publishedAt ?? "",
+          options,
+        );
+      },
+    };
+  }
   const model = getClient().models.PublishedItem;
   if (!model) throw missingProjectionModelError("PublishedItem");
-  return model;
+  return model as unknown as ItemSourceModel;
 }
 
-function getPublishedMediaAssetModel() {
+function getPublishedMediaAssetModel(): MediaAssetSourceModel {
+  if (currentContentSource() === "drafts") {
+    const model = getClient().models.MediaAsset;
+    if (!model) throw missingProjectionModelError("MediaAsset");
+    return {
+      listPublishedMediaAssetsByItemAndSortKey: async ({ publishedItemId }, options) => {
+        const response = (await model.listMediaAssetsByItemAndSortKey(
+          { itemId: publishedItemId },
+          options,
+        )) as unknown as GraphQLListResponse<Omit<GraphQLMediaAsset, "publishedItemId"> & { itemId: string }>;
+        return {
+          ...response,
+          data: (response.data ?? []).filter(Boolean).map((row) => ({ ...row, publishedItemId: row.itemId })),
+        };
+      },
+    };
+  }
   const model = getClient().models.PublishedMediaAsset;
   if (!model) throw missingProjectionModelError("PublishedMediaAsset");
-  return model;
+  return model as unknown as MediaAssetSourceModel;
 }
 
 function missingProjectionModelError(modelName: string): Error {
@@ -561,7 +706,7 @@ async function listItemsByTypeStatus(typeStatus: string): Promise<GraphQLItem[]>
 }
 
 async function getItemById(id: string): Promise<GraphQLItem | null> {
-  const response = await getPublishedItemModel().get({ id }, { authMode: AUTH_MODE });
+  const response = await getPublishedItemModel().get({ id }, { authMode: authMode() });
   return readGetResponse<GraphQLItem>(response);
 }
 
@@ -583,7 +728,7 @@ async function listAll<T>(operation: (options: Record<string, unknown>) => Promi
 
   do {
     const response = await operation({
-      authMode: AUTH_MODE,
+      authMode: authMode(),
       limit: 100,
       nextToken,
     });
@@ -597,7 +742,7 @@ async function listAll<T>(operation: (options: Record<string, unknown>) => Promi
 
 async function listFirst<T>(operation: (options: Record<string, unknown>) => Promise<GraphQLListResponse<T>>): Promise<T[]> {
   const response = await operation({
-    authMode: AUTH_MODE,
+    authMode: authMode(),
     limit: 1,
     sortDirection: "DESC",
   });
@@ -611,7 +756,7 @@ async function listPage<T>(
   nextToken?: string | null,
 ): Promise<{ editions: T[]; nextToken?: string | null }> {
   const response = await operation({
-    authMode: AUTH_MODE,
+    authMode: authMode(),
     limit,
     nextToken,
     sortDirection: "DESC",

package/lib/site-env.ts

@@ -0,0 +1,52 @@
+export type SiteEnv = "production" | "staging" | "development";
+export type ContentSource = "published" | "drafts";
+
+type EnvironmentVariables = Record<string, string | undefined>;
+
+const SITE_ENVIRONMENTS: readonly SiteEnv[] = ["production", "staging", "development"];
+const CONTENT_SOURCES: readonly ContentSource[] = ["published", "drafts"];
+const PRODUCTION_BRANCH = "main";
+
+export function getSiteEnv(environment: EnvironmentVariables = process.env): SiteEnv {
+  const configured = (environment.SITE_ENV ?? "").trim();
+  if (!configured) return "development";
+  if (!SITE_ENVIRONMENTS.includes(configured as SiteEnv)) {
+    throw new Error(`SITE_ENV must be one of ${SITE_ENVIRONMENTS.join(", ")}; received "${configured}".`);
+  }
+  if (configured === "production") {
+    const branch = (environment.AWS_BRANCH ?? "").trim();
+    if (branch && branch !== PRODUCTION_BRANCH) return "staging";
+  }
+  return configured as SiteEnv;
+}
+
+export function getContentSource(environment: EnvironmentVariables = process.env): ContentSource {
+  const configured = (environment.PAPYRUS_CONTENT_SOURCE ?? "").trim();
+  if (!configured) return "published";
+  if (!CONTENT_SOURCES.includes(configured as ContentSource)) {
+    throw new Error(`PAPYRUS_CONTENT_SOURCE must be one of ${CONTENT_SOURCES.join(", ")}; received "${configured}".`);
+  }
+  return configured as ContentSource;
+}
+
+export function isIndexable(environment: EnvironmentVariables = process.env): boolean {
+  return getSiteEnv(environment) === "production";
+}
+
+export function showStagingBanner(environment: EnvironmentVariables = process.env): boolean {
+  return getSiteEnv(environment) === "staging";
+}
+
+export function analyticsAllowed(environment: EnvironmentVariables = process.env): boolean {
+  return getSiteEnv(environment) === "production";
+}
+
+export function assertContentSourceMatchesEnv(environment: EnvironmentVariables = process.env): void {
+  if (getContentSource(environment) !== "drafts") return;
+  const siteEnv = getSiteEnv(environment);
+  if (siteEnv !== "staging") {
+    throw new Error(
+      `PAPYRUS_CONTENT_SOURCE=drafts requires SITE_ENV=staging; the resolved site environment is "${siteEnv}". Drafts must never be served from production or development.`,
+    );
+  }
+}

package/lib/staging-gate.ts

@@ -0,0 +1,37 @@
+import type { NextRequest, NextResponse } from "next/server";
+import { fetchAuthSession } from "aws-amplify/auth/server";
+import { getAmplifyServerRuntime } from "./amplify-server-runtime";
+
+export type StagingAccess = "anonymous" | "forbidden" | "ok";
+
+const STAGING_ALLOWED_GROUPS = ["editor", "admin"];
+
+export function groupsFromIdTokenPayload(payload: Record<string, unknown> | undefined): string[] {
+  const raw = payload?.["cognito:groups"];
+  if (Array.isArray(raw)) return raw.filter((group): group is string => typeof group === "string");
+  if (typeof raw === "string" && raw) return [raw];
+  return [];
+}
+
+export function accessForGroups(groups: string[] | null): StagingAccess {
+  if (groups === null) return "anonymous";
+  return groups.some((group) => STAGING_ALLOWED_GROUPS.includes(group)) ? "ok" : "forbidden";
+}
+
+export async function getStagingAccess(request: NextRequest, response: NextResponse): Promise<StagingAccess> {
+  const { runWithAmplifyServerContext } = getAmplifyServerRuntime();
+  const groups = await runWithAmplifyServerContext({
+    nextServerContext: { request, response },
+    operation: async (contextSpec) => {
+      try {
+        const session = await fetchAuthSession(contextSpec);
+        const idTokenPayload = session.tokens?.idToken?.payload as Record<string, unknown> | undefined;
+        if (!session.tokens?.idToken) return null;
+        return groupsFromIdTokenPayload(idTokenPayload);
+      } catch {
+        return null;
+      }
+    },
+  });
+  return accessForGroups(groups);
+}