@anthusai/papyrus 5.38.1 → 5.40.0

package/components/papyrus-private-chat-panel.tsx

@@ -0,0 +1,134 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { PapyrusConsoleConversation, type ConsoleConversationMessage } from "./papyrus-console-conversation";
+import {
+  listPapyrusPrivateChatMessages,
+  openPapyrusPrivateChat,
+  sendPapyrusPrivateChatMessage,
+  type PapyrusPrivateChatChannel,
+  type PapyrusPrivateChatMessage,
+} from "../lib/papyrus-private-chat-client";
+
+const REFRESH_MS = 2_000;
+
+function toConsoleMessages(messages: readonly PapyrusPrivateChatMessage[]): ConsoleConversationMessage[] {
+  return messages.map((message) => ({
+    id: message.message_id,
+    role: message.author_kind === "human" ? "USER" : "ASSISTANT",
+    text: message.body,
+    createdAt: message.created_at,
+  }));
+}
+
+function failureMessage(error: unknown): string {
+  return error instanceof Error && error.message.trim() ? error.message : "Private chat is unavailable.";
+}
+
+export function PapyrusPrivateChatPanel({ onClose }: { onClose: () => void }) {
+  const [channel, setChannel] = useState<PapyrusPrivateChatChannel | null>(null);
+  const [messages, setMessages] = useState<PapyrusPrivateChatMessage[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [sending, setSending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const retryAttempt = useRef<{ text: string; key: string } | null>(null);
+  const isWaitingForReply = messages.length > 0 && messages[messages.length - 1].author_kind === "human" &&
+    messages[messages.length - 1].addressed_to_bot_id !== null;
+  const conversationMessages = useMemo(() => {
+    const current = toConsoleMessages(messages);
+    if (!isWaitingForReply) return current;
+    const last = messages[messages.length - 1];
+    return [...current, {
+      id: `pending-reply:${last.message_id}`,
+      role: "ASSISTANT",
+      text: "",
+      pending: true,
+    }];
+  }, [isWaitingForReply, messages]);
+
+  const refreshMessages = useCallback(async (channelId: string) => {
+    const next = await listPapyrusPrivateChatMessages(channelId);
+    setMessages(next);
+  }, []);
+
+  const openConversation = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const nextChannel = await openPapyrusPrivateChat();
+      setChannel(nextChannel);
+      await refreshMessages(nextChannel.channel_id);
+    } catch (nextError) {
+      setError(failureMessage(nextError));
+    } finally {
+      setLoading(false);
+    }
+  }, [refreshMessages]);
+
+  useEffect(() => {
+    void openConversation();
+  }, [openConversation]);
+
+  useEffect(() => {
+    if (!channel || !isWaitingForReply) return;
+    let active = true;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const poll = async () => {
+      try {
+        await refreshMessages(channel.channel_id);
+      } catch (nextError) {
+        if (active) setError(failureMessage(nextError));
+        return;
+      }
+      if (active) timer = setTimeout(poll, REFRESH_MS);
+    };
+    timer = setTimeout(poll, REFRESH_MS);
+    return () => {
+      active = false;
+      if (timer) clearTimeout(timer);
+    };
+  }, [channel, isWaitingForReply, refreshMessages]);
+
+  const sendMessage = useCallback(async (text: string) => {
+    if (!channel || !text.trim() || sending) return;
+    const attempt = retryAttempt.current?.text === text
+      ? retryAttempt.current
+      : { text, key: globalThis.crypto.randomUUID() };
+    retryAttempt.current = attempt;
+    setSending(true);
+    setError(null);
+    try {
+      const result = await sendPapyrusPrivateChatMessage(channel.channel_id, text, attempt.key);
+      setMessages((current) => current.some((message) => message.message_id === result.message.message_id)
+        ? current
+        : [...current, result.message]);
+      retryAttempt.current = null;
+    } catch (nextError) {
+      setError(failureMessage(nextError));
+    } finally {
+      setSending(false);
+    }
+  }, [channel, sending]);
+
+  return <div className="papyrus-console__panel">
+    <header className="papyrus-console__header">
+      <p className="papyrus-console__header-label">Private chat</p>
+      <button className="papyrus-console__close" onClick={onClose} type="button" aria-label="Close console">×</button>
+    </header>
+    {channel ? <p className="papyrus-console__empty" role="status">Private conversation for your selected Account.</p> : null}
+    {!channel && !loading ? <div className="papyrus-console__empty" role="alert">
+      <strong>Private chat could not be opened.</strong>
+      <span>{error}</span>
+      <button className="papyrus-console__new-session" onClick={() => void openConversation()} type="button">Retry</button>
+    </div> : <PapyrusConsoleConversation
+      messages={conversationMessages}
+      isSending={sending || loading || !channel}
+      isRunning={isWaitingForReply}
+      onSendMessage={sendMessage}
+      error={error}
+      emptyState={loading ? <p className="papyrus-console__empty">Opening private conversation…</p> : (
+        <p className="papyrus-console__empty">This conversation is private to your selected Account and editor session.</p>
+      )}
+    />}
+  </div>;
+}

package/infra/amplify-app-shell.js

@@ -199,6 +199,7 @@ export class AmplifyAppShellStack extends Stack {
             environmentVariables: environmentVariables({
                 ...config.cms.environment,
                 ...emailEnvironment,
+                PAPYRUS_PRIVATE_CHAT_ENABLED: config.cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED ?? "false",
                 PAPYRUS_COGNITO_DOMAIN_PREFIX: config.cms.cognitoDomainPrefix,
                 ...(config.cms.applyCognitoDomainPrefix ? { PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX: "true" } : {}),
                 PAPYRUS_OAUTH_REDIRECT_URLS: oauthRedirectUrls,
@@ -221,6 +222,7 @@ export class AmplifyAppShellStack extends Stack {
                 buildSpec: cmsStagingBuildSpec(config),
                 environmentVariables: environmentVariables({
                     ...config.cms.environment,
+                    PAPYRUS_PRIVATE_CHAT_ENABLED: "false",
                     PAPYRUS_COGNITO_DOMAIN_PREFIX: config.cms.cognitoDomainPrefix,
                     ...(config.cms.applyCognitoDomainPrefix ? { PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX: "true" } : {}),
                     PAPYRUS_OAUTH_REDIRECT_URLS: oauthRedirectUrls,

package/infra/amplify-app-shell.ts

@@ -221,6 +221,7 @@ export class AmplifyAppShellStack extends Stack {
       environmentVariables: environmentVariables({
         ...config.cms.environment,
         ...emailEnvironment,
+        PAPYRUS_PRIVATE_CHAT_ENABLED: config.cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED ?? "false",
         PAPYRUS_COGNITO_DOMAIN_PREFIX: config.cms.cognitoDomainPrefix,
         ...(config.cms.applyCognitoDomainPrefix ? { PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX: "true" } : {}),
         PAPYRUS_OAUTH_REDIRECT_URLS: oauthRedirectUrls,
@@ -244,6 +245,7 @@ export class AmplifyAppShellStack extends Stack {
         buildSpec: cmsStagingBuildSpec(config),
         environmentVariables: environmentVariables({
           ...config.cms.environment,
+          PAPYRUS_PRIVATE_CHAT_ENABLED: "false",
           PAPYRUS_COGNITO_DOMAIN_PREFIX: config.cms.cognitoDomainPrefix,
           ...(config.cms.applyCognitoDomainPrefix ? { PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX: "true" } : {}),
           PAPYRUS_OAUTH_REDIRECT_URLS: oauthRedirectUrls,

package/infra/site-config.js

@@ -273,6 +273,10 @@ function parseCms(value) {
             fail(`cms.environment.${key}`, "is managed by the template: Google sign-in is always on, the Cognito domain comes from cms.cognitoDomainPrefix, the revalidation secret parameter is derived from siteId and the Prospectus endpoint comes from cms.prospectusAccountsApiStageArn and the public site origin comes from the site host");
         }
     }
+    const privateChatEnabled = cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED;
+    if (privateChatEnabled !== undefined && privateChatEnabled !== "true" && privateChatEnabled !== "false") {
+        fail("cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED", "must be the string \"true\" or \"false\"");
+    }
     if (cms.siteOrigin && cms.domainName) {
         fail("cms.siteOrigin", "is for sites whose host is served by their own edge; remove it when cms.domainName is set");
     }

package/infra/site-config.ts

@@ -413,6 +413,10 @@ function parseCms(value: unknown): CmsConfig {
       fail(`cms.environment.${key}`, "is managed by the template: Google sign-in is always on, the Cognito domain comes from cms.cognitoDomainPrefix, the revalidation secret parameter is derived from siteId and the Prospectus endpoint comes from cms.prospectusAccountsApiStageArn and the public site origin comes from the site host");
     }
   }
+  const privateChatEnabled = cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED;
+  if (privateChatEnabled !== undefined && privateChatEnabled !== "true" && privateChatEnabled !== "false") {
+    fail("cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED", "must be the string \"true\" or \"false\"");
+  }
 
   if (cms.siteOrigin && cms.domainName) {
     fail("cms.siteOrigin", "is for sites whose host is served by their own edge; remove it when cms.domainName is set");

package/lib/monitoring-client.ts

@@ -1,29 +1,34 @@
 "use client";
 
 import { generateClient } from "aws-amplify/data";
-import type { MonitoringResult } from "./monitoring-overview";
+import type { MonitoringEmailDetails, MonitoringResult } from "./monitoring-overview";
 
-type GraphQLResult = { data?: { monitoringOverview?: unknown }; errors?: { message?: string; errorType?: string }[] };
+type QueryField = "monitoringOverview" | "monitoringEmailSubmission";
+type GraphQLResult = { data?: Partial<Record<QueryField, unknown>>; errors?: { message?: string; errorType?: string }[] };
 
-/**
- * Reads the monitoring overview through the site's own authenticated API (user pool, editor or admin).
- * The browser holds no table name, key or secret: the function behind the query does the read.
- */
-export async function loadMonitoringOverview(scope: "publication" | "all"): Promise<MonitoringResult> {
+async function query<T>(field: QueryField, queryText: string, variables: Record<string, string>): Promise<T | { error: "forbidden" } | { state: "unavailable" }> {
   const client = generateClient({ authMode: "userPool" });
   let result: GraphQLResult;
   try {
-    result = (await client.graphql({
-      query: `query MonitoringOverview($scope: String) { monitoringOverview(scope: $scope) }`,
-      variables: { scope },
-    })) as GraphQLResult;
+    result = (await client.graphql({ query: queryText, variables })) as GraphQLResult;
   } catch (error) {
-    // Amplify throws the response when AppSync returns errors.
     result = (error && typeof error === "object" && "errors" in error ? error : { errors: [{ message: "failed" }] }) as GraphQLResult;
   }
   const refused = result.errors?.some((entry) => /unauthorized|not authorized|forbidden/i.test(`${entry.errorType ?? ""} ${entry.message ?? ""}`));
   if (refused) return { error: "forbidden" };
-  if (result.errors?.length || result.data?.monitoringOverview === undefined || result.data.monitoringOverview === null) return { state: "unavailable" };
-  const raw = result.data.monitoringOverview;
-  return (typeof raw === "string" ? JSON.parse(raw) : raw) as MonitoringResult;
+  const raw = result.data?.[field];
+  if (result.errors?.length || raw === undefined || raw === null) return { state: "unavailable" };
+  return (typeof raw === "string" ? JSON.parse(raw) : raw) as T;
+}
+
+/** Reads monitoring data only through the site's authenticated editor/admin API. */
+export async function loadMonitoringOverview(scope: "publication" | "all"): Promise<MonitoringResult> {
+  return query<MonitoringResult>("monitoringOverview",
+    `query MonitoringOverview($scope: String) { monitoringOverview(scope: $scope) }`, { scope });
+}
+
+/** Loads one receipt's safe plain-text rendering and its already extracted candidate links. */
+export async function loadMonitoringEmailSubmission(receiptId: string): Promise<MonitoringEmailDetails> {
+  return query<MonitoringEmailDetails>("monitoringEmailSubmission",
+    `query MonitoringEmailSubmission($receiptId: String!) { monitoringEmailSubmission(receiptId: $receiptId) }`, { receiptId });
 }

package/lib/monitoring-overview.ts

@@ -32,6 +32,18 @@ export type MonitoringItem = {
   relevance: MonitoringRelevance[];
 };
 
+export type MonitoringEmailSummary = {
+  receiptId: string; observedAt: string | null; status: string; subject: string | null;
+  envelopeSender: string | null; headerFrom: string | null; warnings: string[];
+  verdicts: Record<string, string>; linkCount: number; processedCount: number; unresolvedLinkCount: number;
+  reviewRequired: boolean; errorCode: string | null;
+};
+
+export type MonitoringEmailDetails = {
+  submission: MonitoringEmailSummary; safeBodyText: string;
+  candidateLinks: { url: string; title: string; resolutionStatus?: "unresolved" }[]; sourceMaterialIsUntrusted: true;
+} | { error: "forbidden" | "bad_request" } | { state: "unavailable" | "not_configured" };
+
 export type MonitoringRun = {
   runId: string;
   startedAt: string;
@@ -82,6 +94,7 @@ export type MonitoringOverview = {
     ceilings: { decisionsTotal?: number; decisionsPerDay?: number; items?: number } | null;
   } | null;
   items: MonitoringItem[];
+  emailSubmissions?: MonitoringEmailSummary[];
   hiddenNotRelevant: number;
 };
 

package/lib/papyrus-chat-admission.ts

@@ -0,0 +1,65 @@
+import { postChatMessage, type ChatHttpTransport, type ChatMessageSubmission, type PostMessageResponse } from "chatticus/chat-client";
+
+/** Stable author mapping supplied by the Papyrus host; never infer it from a display label or email. */
+export interface PapyrusChatAuthor {
+  hostMappedAuthorId: string;
+  addressedToBotId: string | null;
+}
+
+/** One logical send. Reuse this exact value only for an explicit retry of the same message. */
+export interface PapyrusChatAdmissionAttempt {
+  readonly submission: Readonly<ChatMessageSubmission>;
+  readonly idempotencyKey: string;
+}
+
+export interface PapyrusChatAdmissionSenderOptions {
+  /** Host-owned chat URL; no endpoint is configured or exposed by this module. */
+  url: string;
+  /** Must obtain current Papyrus auth headers on every call; token type stays a host decision. */
+  freshAuthorizationHeaders: () => Promise<Record<string, string>>;
+  fetch?: typeof globalThis.fetch;
+  /** Override only in hermetic tests. Production defaults to the platform CSPRNG. */
+  createIdempotencyKey?: () => string;
+}
+
+export interface PapyrusChatAdmissionSender {
+  createAttempt(text: string, author: PapyrusChatAuthor): PapyrusChatAdmissionAttempt;
+  send(attempt: PapyrusChatAdmissionAttempt): Promise<PostMessageResponse>;
+}
+
+/**
+ * Bind Papyrus's host-owned auth and URL to Chatticus's reusable admission
+ * transport. Each send makes one POST; there is no automatic retry or auth
+ * fallback. An explicit retry sends the same attempt and refreshes headers.
+ */
+export function createPapyrusChatAdmissionSender(options: PapyrusChatAdmissionSenderOptions): PapyrusChatAdmissionSender {
+  const transport: ChatHttpTransport = {
+    url: options.url,
+    headers: async () => {
+      const headers = await options.freshAuthorizationHeaders();
+      const authorization = Object.entries(headers).find(([name]) => name.toLowerCase() === "authorization")?.[1];
+      if (!authorization?.trim()) throw new Error("Papyrus authorization headers are required");
+      return headers;
+    },
+    ...(options.fetch ? { fetch: options.fetch } : {}),
+  };
+  const createKey = options.createIdempotencyKey ?? (() => globalThis.crypto.randomUUID());
+
+  return {
+    createAttempt(text, author) {
+      if (!text.trim() || !author.hostMappedAuthorId.trim()) throw new Error("A message and host-mapped author are required");
+      const submission: ChatMessageSubmission = {
+        author_kind: "human",
+        author_id: author.hostMappedAuthorId,
+        body: text,
+        addressed_to_bot_id: author.addressedToBotId,
+      };
+      const idempotencyKey = createKey();
+      if (!idempotencyKey.trim()) throw new Error("A stable message admission key is required");
+      return Object.freeze({ submission: Object.freeze(submission), idempotencyKey });
+    },
+    send(attempt) {
+      return postChatMessage(transport, attempt.submission, attempt.idempotencyKey);
+    },
+  };
+}

package/lib/papyrus-hosted-chat.ts

@@ -0,0 +1,217 @@
+import { createHash } from "node:crypto";
+import type { EmbeddedChatAppDependencies } from "chatticus/chat-server";
+import type { NextRequest } from "next/server";
+import {
+  ProspectusAccountsError,
+  authorizeSignedInPersonForAccount,
+} from "./prospectus-site-identity";
+import {
+  resolveProspectusSignInRuntime,
+  signedInProspectusSession,
+  type ProspectusSignInRuntime,
+} from "./prospectus-session";
+import { prospectusSiteProduct, publishingAccountsForSite } from "./prospectus-publication-access";
+import { publicSiteOrigin } from "./site-origin-value";
+
+const NO_STORE_HEADERS = { "cache-control": "no-store" };
+
+export interface PapyrusChatScope {
+  siteProduct: string;
+  accountId: string;
+  personId: string;
+  tenantId: string;
+  editorId: string;
+}
+
+export interface PapyrusHostedChatOptions {
+  resolveRuntime?: (siteOrigin: string) => Promise<ProspectusSignInRuntime | null>;
+  resolvePrivateDependencies?: () => Promise<EmbeddedChatAppDependencies | null>;
+  privateChatEnabled?: boolean;
+  siteProduct?: string | null;
+  environment?: Record<string, string | undefined>;
+  nowInSeconds?: () => number;
+}
+
+function siteAndAccountKey(siteProduct: string, accountId: string): string {
+  return createHash("sha256").update(JSON.stringify([siteProduct, accountId])).digest("hex");
+}
+
+export function derivePapyrusChatScope(siteProduct: string, accountId: string, personId: string): PapyrusChatScope {
+  const tenantHash = siteAndAccountKey(siteProduct, accountId);
+  const editorHash = createHash("sha256").update(JSON.stringify([siteProduct, accountId, personId])).digest("hex");
+  return {
+    siteProduct,
+    personId,
+    accountId,
+    tenantId: `papyrus-${tenantHash.slice(0, 40)}`,
+    editorId: `papyrus-editor-${editorHash.slice(0, 40)}`,
+  };
+}
+
+type ResolvedPapyrusPrincipal = {
+  kind: "user";
+  tenantId: string;
+  userId: string;
+  workerId: null;
+  organizationStatus: "enabled";
+  role: "member";
+};
+
+async function principalForRequest(
+  request: NextRequest,
+  operation: "console:read" | "console:write",
+  options: PapyrusHostedChatOptions,
+): Promise<{ principal: ResolvedPapyrusPrincipal | null; status: number }> {
+  const environment = options.environment ?? process.env;
+  const siteProduct = options.siteProduct !== undefined ? options.siteProduct : prospectusSiteProduct(environment);
+  if (!siteProduct) return { principal: null, status: 503 };
+
+  let runtime: ProspectusSignInRuntime | null;
+  try {
+    runtime = await (options.resolveRuntime ?? resolveProspectusSignInRuntime)(publicSiteOrigin(request, environment));
+  } catch {
+    return { principal: null, status: 503 };
+  }
+  if (!runtime) return { principal: null, status: 503 };
+
+  const nowInSeconds = options.nowInSeconds?.() ?? Math.floor(Date.now() / 1000);
+  const session = signedInProspectusSession(request, runtime.sealingSecret, nowInSeconds);
+  if (!session || !session.selectedAccountId || !Number.isFinite(session.accessTokenExpiresAt) || session.accessTokenExpiresAt <= nowInSeconds) {
+    return { principal: null, status: 401 };
+  }
+
+  try {
+    const directory = await runtime.accounts.accountDirectory(session.accessToken);
+    if (directory.person?.id !== session.personId) return { principal: null, status: 401 };
+    if (!publishingAccountsForSite(directory.accounts, siteProduct).some((account) => account.accountId === session.selectedAccountId)) {
+      return { principal: null, status: 403 };
+    }
+    const authorization = await authorizeSignedInPersonForAccount(
+      runtime.accounts,
+      session.accessToken,
+      session.selectedAccountId,
+      operation,
+    );
+    if (authorization.personId !== session.personId || authorization.accountId !== session.selectedAccountId || authorization.operation !== operation) {
+      return { principal: null, status: 403 };
+    }
+    const scope = derivePapyrusChatScope(siteProduct, session.selectedAccountId, session.personId);
+    return {
+      principal: {
+        kind: "user",
+        tenantId: scope.tenantId,
+        userId: scope.editorId,
+        workerId: null,
+        organizationStatus: "enabled",
+        role: "member",
+      },
+      status: 200,
+    };
+  } catch (error) {
+    if (error instanceof ProspectusAccountsError && (error.status === 401 || error.status === 403)) {
+      return { principal: null, status: error.status };
+    }
+    return { principal: null, status: 503 };
+  }
+}
+
+function jsonFailure(status: number, error: string): Response {
+  return new Response(JSON.stringify({ error }), {
+    status,
+    headers: { ...NO_STORE_HEADERS, "content-type": "application/json" },
+  });
+}
+
+function supportedPath(path: readonly string[]): boolean {
+  return (path.length === 1 && path[0] === "private-channel") ||
+    (path.length === 3 && path[0] === "channels" && path[2] === "messages") ||
+    (path.length === 3 && path[0] === "turns" && (path[2] === "events" || path[2] === "stream"));
+}
+
+function chatRequestPath(path: readonly string[]): string {
+  return `/${path.map((part) => encodeURIComponent(part)).join("/")}`;
+}
+
+export async function handlePapyrusHostedChatRequest(
+  request: NextRequest,
+  path: readonly string[],
+  options: PapyrusHostedChatOptions = {},
+): Promise<Response> {
+  if (!supportedPath(path) || path.some((part) => !part || part === "." || part === ".." || part.includes("/"))) {
+    return jsonFailure(404, "chat_route_not_found");
+  }
+  if (request.method !== "GET" && request.method !== "POST") return jsonFailure(405, "method_not_allowed");
+  const isMessageRoute = path[0] === "channels";
+  const isPrivateChannelRoute = path[0] === "private-channel";
+  if (isPrivateChannelRoute && request.method !== "POST") return jsonFailure(405, "method_not_allowed");
+  if ((isMessageRoute && path[2] === "messages" && request.method === "POST") || (!isMessageRoute && !isPrivateChannelRoute && request.method !== "GET")) {
+    if (!isMessageRoute && !isPrivateChannelRoute) return jsonFailure(405, "method_not_allowed");
+  }
+  if (isMessageRoute && request.method === "GET" && path[2] !== "messages") return jsonFailure(405, "method_not_allowed");
+  if ((isMessageRoute || isPrivateChannelRoute) && request.method === "POST") {
+    let origin: string;
+    try {
+      origin = publicSiteOrigin(request, options.environment ?? process.env);
+    } catch {
+      return jsonFailure(503, "chat_site_origin_unavailable");
+    }
+    if (request.headers.get("origin") !== origin) return jsonFailure(403, "same_origin_required");
+  }
+
+  const environment = options.environment ?? process.env;
+  const privateChatEnabled = options.privateChatEnabled ?? environment.PAPYRUS_PRIVATE_CHAT_ENABLED === "true";
+  if (!privateChatEnabled) return jsonFailure(404, "private_chat_disabled");
+
+  let dependencies: EmbeddedChatAppDependencies | null;
+  try {
+    if (options.resolvePrivateDependencies) {
+      dependencies = await options.resolvePrivateDependencies();
+    } else {
+      const chatRuntime = await import("chatticus/chat-runtime");
+      dependencies = chatRuntime.createSiteHostedChatDependencies(
+        chatRuntime.siteHostedChatResourcesFromEnvironment(environment),
+        chatRuntime.siteHostedChatClients(),
+      ) as EmbeddedChatAppDependencies;
+    }
+  } catch {
+    dependencies = null;
+  }
+  if (!dependencies) return jsonFailure(503, "private_chat_storage_unavailable");
+
+  const authorization = await principalForRequest(request, request.method === "POST" ? "console:write" : "console:read", options);
+  if (!authorization.principal) return jsonFailure(authorization.status, authorization.status === 401 ? "sign_in_required" : authorization.status === 403 ? "chat_account_access_denied" : "chat_runtime_unavailable");
+
+  const headers = new Headers({ accept: request.headers.get("accept") ?? "application/json" });
+  let body: string | undefined;
+  if (request.method === "POST" && isMessageRoute) {
+    const idempotencyKey = request.headers.get("idempotency-key")?.trim();
+    const input = await request.json().catch(() => null) as Record<string, unknown> | null;
+    const privateBotId = environment.PAPYRUS_CHAT_PRIVATE_BOT_ID?.trim();
+    if (!idempotencyKey || typeof input?.body !== "string" || !input.body.trim()) {
+      return jsonFailure(422, "message_body_and_idempotency_key_required");
+    }
+    if (!privateBotId) return jsonFailure(503, "private_chat_storage_unavailable");
+    headers.set("content-type", "application/json");
+    headers.set("idempotency-key", idempotencyKey);
+    body = JSON.stringify({
+      author_kind: "human",
+      author_id: authorization.principal.userId,
+      body: input.body,
+      addressed_to_bot_id: privateBotId,
+    });
+  }
+
+  const target = new URL(chatRequestPath(path) + new URL(request.url).search, request.url);
+  const forwarded = new Request(target, { method: request.method, headers, ...(body === undefined ? {} : { body }) });
+  let chatServer: typeof import("chatticus/chat-server");
+  try {
+    chatServer = await import("chatticus/chat-server");
+  } catch {
+    return jsonFailure(503, "private_chat_storage_unavailable");
+  }
+  const app = chatServer.createEmbeddedChatApp({
+    ...dependencies,
+    resolvePrincipal: async () => authorization.principal,
+  });
+  return app.fetch(forwarded);
+}

package/lib/papyrus-private-chat-client.ts

@@ -0,0 +1,81 @@
+export type PapyrusPrivateChatChannel = {
+  channel_id: string;
+  participants: Array<{ kind: string; actor_id: string }>;
+};
+
+export type PapyrusPrivateChatMessage = {
+  message_id: string;
+  channel_id: string;
+  seq: number;
+  author_kind: "human" | "bot";
+  body: string;
+  addressed_to_bot_id: string | null;
+  created_at: string;
+};
+
+export type PapyrusPrivateChatSendResult = {
+  message: PapyrusPrivateChatMessage;
+  turn_id: string | null;
+};
+
+export type PapyrusPrivateChatFetch = typeof globalThis.fetch;
+
+const CHAT_API = "/api/newsroom/chat";
+
+async function requestJson<T>(path: string, init: RequestInit, fetcher: PapyrusPrivateChatFetch): Promise<T> {
+  const response = await fetcher(`${CHAT_API}/${path}`, {
+    ...init,
+    credentials: "same-origin",
+    cache: "no-store",
+  });
+  const payload = await response.json().catch(() => null) as Record<string, unknown> | null;
+  if (!response.ok) {
+    const error = typeof payload?.error === "string" ? payload.error
+      : typeof payload?.detail === "string" ? payload.detail
+        : `Private chat request failed (${response.status}).`;
+    throw new Error(error);
+  }
+  if (!payload || typeof payload !== "object") throw new Error("Private chat returned an invalid response.");
+  return payload as T;
+}
+
+/** Open the current editor's server-derived private channel using the signed same-origin session cookie. */
+export async function openPapyrusPrivateChat(fetcher: PapyrusPrivateChatFetch = globalThis.fetch): Promise<PapyrusPrivateChatChannel> {
+  const result = await requestJson<PapyrusPrivateChatChannel>("private-channel", { method: "POST" }, fetcher);
+  if (!result.channel_id?.trim() || !Array.isArray(result.participants)) {
+    throw new Error("Private chat returned an invalid channel.");
+  }
+  return result;
+}
+
+/** Read only the private channel returned by the host's authenticated open request. */
+export async function listPapyrusPrivateChatMessages(
+  channelId: string,
+  fetcher: PapyrusPrivateChatFetch = globalThis.fetch,
+): Promise<PapyrusPrivateChatMessage[]> {
+  if (!channelId.trim()) throw new Error("A private chat channel is required.");
+  const result = await requestJson<{ messages?: unknown }>(`channels/${encodeURIComponent(channelId)}/messages`, { method: "GET" }, fetcher);
+  if (!Array.isArray(result.messages)) throw new Error("Private chat returned an invalid message list.");
+  return result.messages as PapyrusPrivateChatMessage[];
+}
+
+/** One explicit send. The browser sends neither its tenant nor author or bot identity. */
+export async function sendPapyrusPrivateChatMessage(
+  channelId: string,
+  body: string,
+  idempotencyKey: string,
+  fetcher: PapyrusPrivateChatFetch = globalThis.fetch,
+): Promise<PapyrusPrivateChatSendResult> {
+  if (!channelId.trim() || !body.trim() || !idempotencyKey.trim()) {
+    throw new Error("A channel, message and idempotency key are required.");
+  }
+  const result = await requestJson<PapyrusPrivateChatSendResult>(`channels/${encodeURIComponent(channelId)}/messages`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "idempotency-key": idempotencyKey },
+    body: JSON.stringify({ body }),
+  }, fetcher);
+  if (!result.message?.message_id || result.message.channel_id !== channelId) {
+    throw new Error("Private chat returned an invalid sent message.");
+  }
+  return result;
+}

package/lib/prospectus-session.ts

@@ -1,5 +1,6 @@
 import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from "node:crypto";
 import { GetParameterCommand, SSMClient } from "@aws-sdk/client-ssm";
+import type { NextRequest } from "next/server";
 import { readAmplifyOutputsFile } from "./amplify-outputs-path";
 import {
   ProspectusSiteAccounts,
@@ -42,6 +43,20 @@ export interface ProspectusSignedInSession {
   siteSubject?: string;
 }
 
+/** Open the existing sealed Prospectus session cookie for one server request. */
+export function signedInProspectusSession(
+  request: Pick<NextRequest, "cookies">,
+  sealingSecret: string,
+  nowInSeconds?: number,
+): ProspectusSignedInSession | null {
+  return openProspectusCookie<ProspectusSignedInSession>(
+    sealingSecret,
+    PROSPECTUS_SESSION_COOKIE,
+    request.cookies.get(PROSPECTUS_SESSION_COOKIE)?.value,
+    nowInSeconds,
+  );
+}
+
 function sealingKeyForCookie(sealingSecret: string, cookieName: string): Buffer {
   if (sealingSecret.length < MINIMUM_SEALING_SECRET_LENGTH) throw new Error("The Prospectus session sealing secret is too short.");
   return Buffer.from(hkdfSync("sha256", sealingSecret, SEALED_COOKIE_KEY_DERIVATION_SALT, cookieName, 32));