@anthusai/papyrus 1.0.0-next.9 → 1.1.0

package/lib/prospectus-sign-in-routes.ts

@@ -0,0 +1,284 @@
+import { NextResponse, type NextRequest } from "next/server";
+import {
+  CYCLOTRON_LAB_PRODUCT,
+  ProspectusAccountsError,
+  authorizeSignedInPersonForAccount,
+  beginProspectusGoogleSignIn,
+  completeProspectusGoogleSignIn,
+  type CompleteProspectusGoogleSignInInput,
+} from "./prospectus-site-identity";
+import {
+  PROSPECTUS_PENDING_SIGN_IN_COOKIE,
+  PROSPECTUS_SESSION_COOKIE,
+  openProspectusCookie,
+  resolveProspectusSignInRuntime,
+  sameSiteReturnPath,
+  sealProspectusCookie,
+  sealedCookieAttributes,
+  type PendingProspectusSignInCookie,
+  type ProspectusSignInRuntime,
+  type ProspectusSignedInSession,
+} from "./prospectus-session";
+import {
+  prospectusSiteProduct,
+  publicationCapabilitiesForProspectusRole,
+  publishingAccountsForSite,
+  type PublicationCapability,
+} from "./prospectus-publication-access";
+
+/**
+ * The site's sign-in routes for Prospectus accounts: start (challenge, then the
+ * Google-only Cognito redirect), callback (verify, resolve, seal the session),
+ * session (who is signed in and which accounts they belong to) and sign-out.
+ * Every route answers 503 until the site is registered and configured, so an
+ * unregistered deployment never half-signs anyone in.
+ */
+export interface ProspectusSignInRouteOptions {
+  resolveRuntime?: (siteOrigin: string) => Promise<ProspectusSignInRuntime | null>;
+  siteProduct?: string | null;
+  completionOverrides?: Pick<CompleteProspectusGoogleSignInInput, "verifyCognitoTokens" | "fetcher">;
+  nowInSeconds?: () => number;
+}
+
+const NO_STORE_HEADERS = { "cache-control": "no-store" };
+
+function siteProductFor(options: ProspectusSignInRouteOptions): string | null {
+  return options.siteProduct !== undefined ? options.siteProduct : prospectusSiteProduct();
+}
+
+function currentTimeInSeconds(options: ProspectusSignInRouteOptions): number {
+  return options.nowInSeconds?.() ?? Math.floor(Date.now() / 1000);
+}
+
+async function signInRuntimeFor(request: NextRequest, options: ProspectusSignInRouteOptions): Promise<ProspectusSignInRuntime | null> {
+  return (options.resolveRuntime ?? resolveProspectusSignInRuntime)(request.nextUrl.origin);
+}
+
+function signInUnavailableResponse(): NextResponse {
+  return NextResponse.json(
+    { error: "prospectus_sign_in_unavailable", message: "Sign-in through Prospectus is not configured for this site." },
+    { status: 503, headers: NO_STORE_HEADERS },
+  );
+}
+
+function clearSealedCookie(response: NextResponse, cookieName: string): void {
+  response.cookies.set(cookieName, "", sealedCookieAttributes(0, 0));
+}
+
+function signInFailedResponse(status: number, code: string, message: string): NextResponse {
+  return NextResponse.json({ error: code, message }, { status, headers: NO_STORE_HEADERS });
+}
+
+export function signedInProspectusSession(
+  request: NextRequest,
+  sealingSecret: string,
+  nowInSeconds?: number,
+): ProspectusSignedInSession | null {
+  return openProspectusCookie<ProspectusSignedInSession>(
+    sealingSecret,
+    PROSPECTUS_SESSION_COOKIE,
+    request.cookies.get(PROSPECTUS_SESSION_COOKIE)?.value,
+    nowInSeconds,
+  );
+}
+
+export async function handleProspectusSignInStart(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+  const runtime = await signInRuntimeFor(request, options);
+  if (!runtime) return signInUnavailableResponse();
+  const { authorizationUrl, pendingSignIn } = await beginProspectusGoogleSignIn(runtime.accounts, runtime.cognitoClient);
+  const pendingSignInCookie: PendingProspectusSignInCookie = {
+    ...pendingSignIn,
+    returnPath: sameSiteReturnPath(request.nextUrl.searchParams.get("returnTo")),
+  };
+  const response = NextResponse.redirect(authorizationUrl, { status: 303, headers: NO_STORE_HEADERS });
+  response.cookies.set(
+    PROSPECTUS_PENDING_SIGN_IN_COOKIE,
+    sealProspectusCookie(runtime.sealingSecret, PROSPECTUS_PENDING_SIGN_IN_COOKIE, pendingSignInCookie, pendingSignIn.expiresAt),
+    sealedCookieAttributes(pendingSignIn.expiresAt, currentTimeInSeconds(options)),
+  );
+  return response;
+}
+
+export async function handleProspectusSignInCallback(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+  const runtime = await signInRuntimeFor(request, options);
+  if (!runtime) return signInUnavailableResponse();
+  const nowInSeconds = currentTimeInSeconds(options);
+  const pendingSignIn = openProspectusCookie<PendingProspectusSignInCookie>(
+    runtime.sealingSecret,
+    PROSPECTUS_PENDING_SIGN_IN_COOKIE,
+    request.cookies.get(PROSPECTUS_PENDING_SIGN_IN_COOKIE)?.value,
+    nowInSeconds,
+  );
+  const response = await completeCallback(request, runtime, pendingSignIn, options, nowInSeconds);
+  clearSealedCookie(response, PROSPECTUS_PENDING_SIGN_IN_COOKIE);
+  return response;
+}
+
+async function completeCallback(
+  request: NextRequest,
+  runtime: ProspectusSignInRuntime,
+  pendingSignIn: PendingProspectusSignInCookie | null,
+  options: ProspectusSignInRouteOptions,
+  nowInSeconds: number,
+): Promise<NextResponse> {
+  if (!pendingSignIn) return signInFailedResponse(401, "sign_in_expired", "This sign-in is no longer pending. Start again.");
+  const searchParams = request.nextUrl.searchParams;
+  if (searchParams.get("error")) return signInFailedResponse(401, "sign_in_declined", "Google sign-in did not complete.");
+  const authorizationCode = searchParams.get("code");
+  const returnedState = searchParams.get("state");
+  if (!authorizationCode || !returnedState) return signInFailedResponse(400, "sign_in_incomplete", "The sign-in response is missing its code or state.");
+  try {
+    const signedIn = await completeProspectusGoogleSignIn({
+      accounts: runtime.accounts,
+      cognitoClient: runtime.cognitoClient,
+      pendingSignIn,
+      returnedState,
+      authorizationCode,
+      nowInSeconds,
+      ...options.completionOverrides,
+    });
+    const session: ProspectusSignedInSession = {
+      personId: signedIn.person.id,
+      accessToken: signedIn.accessToken,
+      accessTokenExpiresAt: signedIn.accessTokenExpiresAt,
+    };
+    const response = NextResponse.redirect(new URL(pendingSignIn.returnPath, request.nextUrl.origin), { status: 303, headers: NO_STORE_HEADERS });
+    response.cookies.set(
+      PROSPECTUS_SESSION_COOKIE,
+      sealProspectusCookie(runtime.sealingSecret, PROSPECTUS_SESSION_COOKIE, session, session.accessTokenExpiresAt),
+      sealedCookieAttributes(session.accessTokenExpiresAt, nowInSeconds),
+    );
+    return response;
+  } catch (error) {
+    if (error instanceof ProspectusAccountsError) return signInFailedResponse(error.status, error.code, error.message);
+    console.error(`Prospectus sign-in failed (${error instanceof Error ? error.name : "error"}).`);
+    return signInFailedResponse(401, "sign_in_failed", "Sign-in could not be completed.");
+  }
+}
+
+export async function handleProspectusSessionRead(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+  const runtime = await signInRuntimeFor(request, options);
+  if (!runtime) return signInUnavailableResponse();
+  const session = signedInProspectusSession(request, runtime.sealingSecret, currentTimeInSeconds(options));
+  if (!session) return NextResponse.json({ signedIn: false }, { headers: NO_STORE_HEADERS });
+  try {
+    const directory = await runtime.accounts.accountDirectory(session.accessToken);
+    if (!directory.person || directory.person.id !== session.personId) {
+      const response = NextResponse.json({ signedIn: false }, { headers: NO_STORE_HEADERS });
+      clearSealedCookie(response, PROSPECTUS_SESSION_COOKIE);
+      return response;
+    }
+    const publishingAccounts = publishingAccountsForSite(directory.accounts, siteProductFor(options));
+    return NextResponse.json(
+      {
+        signedIn: true,
+        person: directory.person,
+        accounts: directory.accounts,
+        cyclotronLabAccess: directory.accounts.some((account) =>
+          account.products.some((product) => product.product === CYCLOTRON_LAB_PRODUCT && product.status === "active"),
+        ),
+        publishingAccounts,
+        selectedAccountId: publishingAccounts.some((account) => account.accountId === session.selectedAccountId)
+          ? session.selectedAccountId
+          : null,
+      },
+      { headers: NO_STORE_HEADERS },
+    );
+  } catch (error) {
+    if (error instanceof ProspectusAccountsError && error.status === 401) {
+      const response = NextResponse.json({ signedIn: false }, { headers: NO_STORE_HEADERS });
+      clearSealedCookie(response, PROSPECTUS_SESSION_COOKIE);
+      return response;
+    }
+    if (error instanceof ProspectusAccountsError) return signInFailedResponse(error.status, error.code, error.message);
+    console.error(`Prospectus account directory failed (${error instanceof Error ? error.name : "error"}).`);
+    return signInFailedResponse(503, "prospectus_unavailable", "Prospectus could not be reached.");
+  }
+}
+
+export async function handleProspectusSignOut(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+  const runtime = await signInRuntimeFor(request, options);
+  const signedOutDestination = new URL("/", request.nextUrl.origin);
+  const destination = runtime
+    ? new URL(
+      `/logout?${new URLSearchParams({ client_id: runtime.cognitoClient.clientId, logout_uri: signedOutDestination.toString() })}`,
+      runtime.cognitoClient.hostedUiOrigin,
+    )
+    : signedOutDestination;
+  const response = NextResponse.redirect(destination, { status: 303, headers: NO_STORE_HEADERS });
+  clearSealedCookie(response, PROSPECTUS_SESSION_COOKIE);
+  clearSealedCookie(response, PROSPECTUS_PENDING_SIGN_IN_COOKIE);
+  return response;
+}
+
+export interface ProspectusPublishingSelection {
+  personId: string;
+  accountId: string;
+  role: string;
+  publicationCapabilities: PublicationCapability[];
+}
+
+async function freshlyAuthorizedPublishingSelection(
+  runtime: ProspectusSignInRuntime,
+  session: ProspectusSignedInSession,
+  accountId: string,
+  siteProduct: string | null,
+): Promise<ProspectusPublishingSelection | null> {
+  const directory = await runtime.accounts.accountDirectory(session.accessToken);
+  if (!directory.person || directory.person.id !== session.personId) return null;
+  if (!publishingAccountsForSite(directory.accounts, siteProduct).some((account) => account.accountId === accountId)) return null;
+  const authorization = await authorizeSignedInPersonForAccount(runtime.accounts, session.accessToken, accountId, "console:read");
+  if (authorization.personId !== session.personId) return null;
+  const publicationCapabilities = publicationCapabilitiesForProspectusRole(authorization.role);
+  if (publicationCapabilities.length === 0) return null;
+  return { personId: session.personId, accountId, role: authorization.role, publicationCapabilities };
+}
+
+export async function currentProspectusPublishingSelection(
+  request: NextRequest,
+  options: ProspectusSignInRouteOptions = {},
+): Promise<ProspectusPublishingSelection | null> {
+  const runtime = await signInRuntimeFor(request, options);
+  if (!runtime) return null;
+  const session = signedInProspectusSession(request, runtime.sealingSecret, currentTimeInSeconds(options));
+  if (!session?.selectedAccountId) return null;
+  try {
+    return await freshlyAuthorizedPublishingSelection(runtime, session, session.selectedAccountId, siteProductFor(options));
+  } catch (error) {
+    if (error instanceof ProspectusAccountsError) return null;
+    throw error;
+  }
+}
+
+export async function handleProspectusAccountSelection(request: NextRequest, options: ProspectusSignInRouteOptions = {}): Promise<NextResponse> {
+  const runtime = await signInRuntimeFor(request, options);
+  if (!runtime) return signInUnavailableResponse();
+  if (request.headers.get("origin") !== request.nextUrl.origin) {
+    return signInFailedResponse(403, "cross_origin_selection", "Choose an account from this site.");
+  }
+  const nowInSeconds = currentTimeInSeconds(options);
+  const session = signedInProspectusSession(request, runtime.sealingSecret, nowInSeconds);
+  if (!session) return signInFailedResponse(401, "signed_out", "Sign in first.");
+  const body = await request.json().catch(() => null) as { accountId?: unknown } | null;
+  const accountId = typeof body?.accountId === "string" ? body.accountId.trim() : "";
+  if (!accountId) return signInFailedResponse(400, "account_required", "Choose an account.");
+  try {
+    const selection = await freshlyAuthorizedPublishingSelection(runtime, session, accountId, siteProductFor(options));
+    if (!selection) return signInFailedResponse(403, "not_a_publishing_account", "You cannot work on this site's publications in that account.");
+    const response = NextResponse.json(
+      { selectedAccountId: selection.accountId, role: selection.role, publicationCapabilities: selection.publicationCapabilities },
+      { headers: NO_STORE_HEADERS },
+    );
+    const selectedSession: ProspectusSignedInSession = { ...session, selectedAccountId: selection.accountId };
+    response.cookies.set(
+      PROSPECTUS_SESSION_COOKIE,
+      sealProspectusCookie(runtime.sealingSecret, PROSPECTUS_SESSION_COOKIE, selectedSession, session.accessTokenExpiresAt),
+      sealedCookieAttributes(session.accessTokenExpiresAt, nowInSeconds),
+    );
+    return response;
+  } catch (error) {
+    if (error instanceof ProspectusAccountsError) return signInFailedResponse(error.status, error.code, error.message);
+    console.error(`Prospectus account selection failed (${error instanceof Error ? error.name : "error"}).`);
+    return signInFailedResponse(503, "prospectus_unavailable", "Prospectus could not be reached.");
+  }
+}

package/lib/prospectus-site-identity.ts

@@ -0,0 +1,303 @@
+
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { defaultProvider } from "@aws-sdk/credential-provider-node";
+import { SignatureV4 } from "@smithy/signature-v4";
+import { HttpRequest } from "@smithy/protocol-http";
+import { Sha256 } from "@aws-crypto/sha256-js";
+import { CognitoJwtVerifier } from "aws-jwt-verify";
+import type { JwksCache } from "aws-jwt-verify/jwk";
+
+/**
+ * A Papyrus site's server-side view of Prospectus, the single account service.
+ *
+ * The site signs requests with its own runtime role (the Amplify SSR compute role
+ * registered in Prospectus). People sign in through the site's Google-only Cognito
+ * client; Prospectus binds that sign-in to a canonical person through a one-time
+ * challenge nonce. Papyrus keeps no account or membership tables: every answer here
+ * comes from Prospectus, and publication-level grants are never inferred from an
+ * account role.
+ */
+
+export type ProspectusRole = "owner" | "admin" | "member" | "viewer";
+export type ProspectusOperation = "console:read" | "console:write" | "members:read" | "members:write";
+
+export interface ProspectusPerson {
+  id: string;
+  createdAt: string;
+}
+
+export interface ProspectusAccountAuthorization {
+  allowed: true;
+  accountId: string;
+  personId: string;
+  product: string;
+  role: ProspectusRole;
+  operation: ProspectusOperation;
+  revision: number;
+}
+
+export interface ProspectusDirectoryAccount {
+  id: string;
+  name: string;
+  role: ProspectusRole;
+  products: Array<{ product: string; status: "active" | "disabled" }>;
+}
+
+export interface ProspectusRequest {
+  path: string;
+  method: "GET" | "POST";
+  body?: unknown;
+  humanAccessToken?: string;
+  identityToken?: string;
+}
+
+export type ProspectusTransport = (request: ProspectusRequest) => Promise<unknown>;
+
+export class ProspectusAccountsError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export interface TemporaryRuntimeCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+  expiration?: Date;
+}
+
+export interface SignedProspectusTransportOptions {
+  endpoint: string;
+  region: string;
+  runtimeCredentials?: () => Promise<TemporaryRuntimeCredentials>;
+  fetcher?: typeof fetch;
+}
+
+export function signedProspectusTransport(options: SignedProspectusTransportOptions): ProspectusTransport {
+  const endpoint = new URL(options.endpoint);
+  if (endpoint.protocol !== "https:" || endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+    throw new Error("Use an HTTPS Prospectus accounts endpoint.");
+  }
+  const runtimeCredentials = options.runtimeCredentials ?? defaultProvider();
+  const fetcher = options.fetcher ?? fetch;
+  return async ({ path, method, body, humanAccessToken, identityToken }) => {
+    const credentials = await runtimeCredentials();
+    if (!credentials.sessionToken || (credentials.expiration && credentials.expiration.getTime() <= Date.now())) {
+      throw new Error("Prospectus calls require the site's temporary runtime credentials; static access keys are refused.");
+    }
+    const url = new URL(`${endpoint.toString().replace(/\/$/, "")}${path}`);
+    const payload = body === undefined ? undefined : JSON.stringify(body);
+    const headers: Record<string, string> = {
+      host: url.host,
+      ...(humanAccessToken ? { "x-prospectus-human-token": humanAccessToken } : {}),
+      ...(identityToken ? { "x-prospectus-identity-token": identityToken } : {}),
+      ...(payload ? { "content-type": "application/json" } : {}),
+    };
+    const signer = new SignatureV4({ service: "execute-api", region: options.region, credentials, sha256: Sha256 });
+    const signed = await signer.sign(
+      new HttpRequest({ protocol: url.protocol, hostname: url.hostname, path: url.pathname, method, headers, body: payload }),
+    );
+    const response = await fetcher(url, { method, headers: signed.headers, body: payload, cache: "no-store", redirect: "error" });
+    const responseBody = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      throw new ProspectusAccountsError(response.status, responseBody.error ?? "request_failed", responseBody.message ?? "Prospectus request failed.");
+    }
+    return responseBody;
+  };
+}
+
+export class ProspectusSiteAccounts {
+  constructor(private readonly transport: ProspectusTransport) {}
+
+  requestGoogleSignInChallenge(): Promise<{ challengeId: string; nonce: string; expiresAt: number }> {
+    return this.transport({ path: "/v1/identities/google/challenge", method: "POST", body: {} }) as Promise<{
+      challengeId: string;
+      nonce: string;
+      expiresAt: number;
+    }>;
+  }
+
+  resolveGoogleSignIn(challengeId: string, humanAccessToken: string, identityToken: string): Promise<{ person: ProspectusPerson }> {
+    return this.transport({
+      path: "/v1/identities/google/resolve",
+      method: "POST",
+      body: { challengeId },
+      humanAccessToken,
+      identityToken,
+    }) as Promise<{ person: ProspectusPerson }>;
+  }
+
+  currentPerson(humanAccessToken: string): Promise<{ person: ProspectusPerson | null }> {
+    return this.transport({ path: "/v1/identities/me", method: "GET", humanAccessToken }) as Promise<{ person: ProspectusPerson | null }>;
+  }
+
+  authorizeAccountOperation(humanAccessToken: string, accountId: string, operation: ProspectusOperation): Promise<ProspectusAccountAuthorization> {
+    return this.transport({
+      path: `/v1/accounts/${encodeURIComponent(accountId)}/authorize`,
+      method: "POST",
+      body: { operation },
+      humanAccessToken,
+    }) as Promise<ProspectusAccountAuthorization>;
+  }
+
+  accountDirectory(humanAccessToken: string): Promise<{ person: ProspectusPerson | null; accounts: ProspectusDirectoryAccount[] }> {
+    return this.transport({ path: "/v1/account-directory", method: "GET", humanAccessToken }) as Promise<{
+      person: ProspectusPerson | null;
+      accounts: ProspectusDirectoryAccount[];
+    }>;
+  }
+}
+
+export interface GoogleOnlyCognitoClient {
+  hostedUiOrigin: string;
+  userPoolId: string;
+  clientId: string;
+  redirectUri: string;
+}
+
+export interface PendingProspectusSignIn {
+  challengeId: string;
+  nonce: string;
+  state: string;
+  codeVerifier: string;
+  expiresAt: number;
+}
+
+export interface CognitoTokens {
+  accessToken: string;
+  idToken: string;
+  refreshToken?: string;
+  expiresInSeconds: number;
+}
+
+export type CognitoTokenVerifier = (tokens: CognitoTokens, expectedNonce: string) => Promise<void>;
+
+function base64UrlRandom(byteLength: number): string {
+  return randomBytes(byteLength).toString("base64url");
+}
+
+function constantTimeEquals(left: string, right: string): boolean {
+  const leftBytes = Buffer.from(left);
+  const rightBytes = Buffer.from(right);
+  return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes);
+}
+
+export async function beginProspectusGoogleSignIn(
+  accounts: ProspectusSiteAccounts,
+  cognitoClient: GoogleOnlyCognitoClient,
+): Promise<{ authorizationUrl: string; pendingSignIn: PendingProspectusSignIn }> {
+  const challenge = await accounts.requestGoogleSignInChallenge();
+  const state = base64UrlRandom(32);
+  const codeVerifier = base64UrlRandom(48);
+  const authorizationUrl = new URL("/oauth2/authorize", cognitoClient.hostedUiOrigin);
+  authorizationUrl.search = new URLSearchParams({
+    response_type: "code",
+    client_id: cognitoClient.clientId,
+    redirect_uri: cognitoClient.redirectUri,
+    scope: "openid email profile",
+    identity_provider: "Google",
+    state,
+    nonce: challenge.nonce,
+    code_challenge: createHash("sha256").update(codeVerifier).digest("base64url"),
+    code_challenge_method: "S256",
+  }).toString();
+  return {
+    authorizationUrl: authorizationUrl.toString(),
+    pendingSignIn: { challengeId: challenge.challengeId, nonce: challenge.nonce, state, codeVerifier, expiresAt: challenge.expiresAt },
+  };
+}
+
+export function cognitoTokenVerifier(cognitoClient: GoogleOnlyCognitoClient, signingKeyCache?: JwksCache): CognitoTokenVerifier {
+  const verifierOptions = signingKeyCache ? { jwksCache: signingKeyCache } : undefined;
+  const accessTokenVerifier = CognitoJwtVerifier.create({ userPoolId: cognitoClient.userPoolId, tokenUse: "access", clientId: cognitoClient.clientId }, verifierOptions);
+  const identityTokenVerifier = CognitoJwtVerifier.create({ userPoolId: cognitoClient.userPoolId, tokenUse: "id", clientId: cognitoClient.clientId }, verifierOptions);
+  return async (tokens, expectedNonce) => {
+    const accessClaims = await accessTokenVerifier.verify(tokens.accessToken);
+    const identityClaims = await identityTokenVerifier.verify(tokens.idToken);
+    if (identityClaims.nonce !== expectedNonce) throw new ProspectusAccountsError(401, "nonce_mismatch", "Sign-in did not carry this site's Prospectus challenge.");
+    if (identityClaims.sub !== accessClaims.sub) throw new ProspectusAccountsError(401, "token_pair_mismatch", "Access and identity tokens describe different people.");
+  };
+}
+
+export interface CompleteProspectusGoogleSignInInput {
+  accounts: ProspectusSiteAccounts;
+  cognitoClient: GoogleOnlyCognitoClient;
+  pendingSignIn: PendingProspectusSignIn;
+  returnedState: string;
+  authorizationCode: string;
+  verifyCognitoTokens?: CognitoTokenVerifier;
+  fetcher?: typeof fetch;
+  nowInSeconds?: number;
+}
+
+export async function completeProspectusGoogleSignIn(
+  input: CompleteProspectusGoogleSignInInput,
+): Promise<{ person: ProspectusPerson; accessToken: string; refreshToken?: string; accessTokenExpiresAt: number }> {
+  const nowInSeconds = input.nowInSeconds ?? Math.floor(Date.now() / 1000);
+  if (nowInSeconds >= input.pendingSignIn.expiresAt) {
+    throw new ProspectusAccountsError(401, "sign_in_expired", "Sign-in took too long. Start again.");
+  }
+  if (!constantTimeEquals(input.returnedState, input.pendingSignIn.state)) {
+    throw new ProspectusAccountsError(401, "state_mismatch", "Sign-in response does not belong to this browser's sign-in.");
+  }
+  const tokenResponse = await (input.fetcher ?? fetch)(new URL("/oauth2/token", input.cognitoClient.hostedUiOrigin), {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: input.cognitoClient.clientId,
+      code: input.authorizationCode,
+      redirect_uri: input.cognitoClient.redirectUri,
+      code_verifier: input.pendingSignIn.codeVerifier,
+    }).toString(),
+    cache: "no-store",
+    redirect: "error",
+  });
+  const tokenBody = await tokenResponse.json().catch(() => ({}));
+  if (!tokenResponse.ok || typeof tokenBody.access_token !== "string" || typeof tokenBody.id_token !== "string") {
+    throw new ProspectusAccountsError(401, "code_exchange_failed", "Cognito did not complete the sign-in.");
+  }
+  const tokens: CognitoTokens = {
+    accessToken: tokenBody.access_token,
+    idToken: tokenBody.id_token,
+    refreshToken: typeof tokenBody.refresh_token === "string" ? tokenBody.refresh_token : undefined,
+    expiresInSeconds: Number(tokenBody.expires_in) || 0,
+  };
+  await (input.verifyCognitoTokens ?? cognitoTokenVerifier(input.cognitoClient))(tokens, input.pendingSignIn.nonce);
+  const { person } = await input.accounts.resolveGoogleSignIn(input.pendingSignIn.challengeId, tokens.accessToken, tokens.idToken);
+  return {
+    person,
+    accessToken: tokens.accessToken,
+    refreshToken: tokens.refreshToken,
+    accessTokenExpiresAt: nowInSeconds + tokens.expiresInSeconds,
+  };
+}
+
+export async function authorizeSignedInPersonForAccount(
+  accounts: ProspectusSiteAccounts,
+  humanAccessToken: string,
+  accountId: string,
+  operation: ProspectusOperation,
+): Promise<ProspectusAccountAuthorization> {
+  const { person } = await accounts.currentPerson(humanAccessToken);
+  if (!person) throw new ProspectusAccountsError(401, "unknown_person", "Sign in again: Prospectus does not recognize this session.");
+  const authorization = await accounts.authorizeAccountOperation(humanAccessToken, accountId, operation);
+  if (authorization.allowed !== true || authorization.personId !== person.id || authorization.accountId !== accountId || authorization.operation !== operation) {
+    throw new ProspectusAccountsError(403, "not_authorized", "Prospectus did not authorize this account operation.");
+  }
+  return authorization;
+}
+
+export const CYCLOTRON_LAB_PRODUCT = "cyclotron";
+
+export async function signedInPersonHasCyclotronLabAccess(accounts: ProspectusSiteAccounts, humanAccessToken: string): Promise<boolean> {
+  const directory = await accounts.accountDirectory(humanAccessToken);
+  if (!directory.person) return false;
+  return directory.accounts.some((account) =>
+    account.products.some((product) => product.product === CYCLOTRON_LAB_PRODUCT && product.status === "active"),
+  );
+}

package/lib/publication-cyclotron.ts

@@ -0,0 +1,74 @@
+import type {CyclotronDecision,CyclotronReview} from 'cyclotron/sdk-types';
+import type {CyclotronStatus} from 'cyclotron/cyclotron-status';
+import type {ReviewControlReview} from 'cyclotron/components/review-control';
+
+export type PublicationScope={accountId:string;publicationId:string;bindingRevision:string};
+export type PublicationEnvelope=PublicationScope&{contractVersion:'cyclotron-publication/v1';publicationId:string;bindingRevision:string;features?:{frozenContext:boolean;replayExport:boolean;steering:boolean};outputs:Array<{id:string;question:string;classes:string[];positiveLabel:string|null}>};
+export type PublicationStatus=PublicationEnvelope&{classifiers:Record<string,CyclotronStatus>};
+export type PublicationRevisionRef={listId:string;itemId:string;revision:number;contentHash:string};
+export type PublicationContext={contextId:string;decisionId:string;publicationId:string;sourceRef:PublicationRevisionRef;bindingRef:PublicationRevisionRef;source:{id:string;values:Record<string,unknown>};binding:{values:{accountId:string;publicationId:string;revision:string;outputs:string[]}}};
+export type PublicationHistoryRow={decision:CyclotronDecision;item:Record<string,unknown>;state?:string;reviews:Record<string,CyclotronReview>;context?:PublicationContext;historicalContext?:boolean;provenanceUnavailable?:boolean;feedbackReconciliationRequired?:boolean};
+export type PublicationHistory=PublicationEnvelope&{history:PublicationHistoryRow[]};
+export type PublicationReviewPayload={bindingRevision:string;decisionId:string;classifier:string;predictionVersion:number;predictionFingerprint:string;requestId:string;label:string;explanation:string;reasonCode:string|null;contextId?:string};
+export type PublicationSteeringInput={requestId:string;explanation:string}&({action:'evaluate';proposal:Record<string,unknown>}|{action:'promote';trialFingerprint:string});
+export type PublicationSteeringPayload=PublicationSteeringInput&{bindingRevision:string;bindingRef:PublicationRevisionRef;classifier:string;expectedFingerprint:string};
+
+function ordered(value:unknown):unknown{
+ if(Array.isArray(value))return value.map(ordered);
+ if(value&&typeof value==='object')return Object.fromEntries(Object.entries(value).sort(([a],[b])=>a.localeCompare(b)).map(([key,item])=>[key,ordered(item)]));
+ return value;
+}
+
+/** Stable cache/component identity; length-safe even when IDs contain delimiters. */
+export function publicationScopeKey(scope:PublicationScope):string{
+ if([scope.accountId,scope.publicationId,scope.bindingRevision].some(value=>typeof value!=='string'||!value.trim()))throw new Error('Complete publication account scope required');
+ return JSON.stringify([scope.accountId,scope.publicationId,scope.bindingRevision]);
+}
+
+export function assertPublicationScope(status:PublicationStatus,history:PublicationHistory){
+ if(status.contractVersion!=='cyclotron-publication/v1'||history.contractVersion!==status.contractVersion||publicationScopeKey(status)!==publicationScopeKey(history)||status.publicationId!==history.publicationId||status.bindingRevision!==history.bindingRevision)throw new Error('Publication snapshot binding mismatch');
+ const outputs=new Set(status.outputs.map(output=>output.id));
+ if(!outputs.size||outputs.size!==status.outputs.length||status.outputs.some(output=>status.classifiers[output.id]?.cyclotron.classifier!==output.id)||JSON.stringify(history.outputs)!==JSON.stringify(status.outputs))throw new Error('Publication snapshot is incomplete');
+ if(Object.keys(status.classifiers).some(id=>!outputs.has(id))||history.outputs.some(output=>!outputs.has(output.id))||history.history.some(row=>[...Object.keys(row.decision.classifiers),...Object.keys(row.reviews)].some(id=>!outputs.has(id))))throw new Error('Snapshot includes an output outside this publication');
+ if(history.history.some(row=>row.context&&(row.context.binding.values.accountId!==status.accountId||row.context.publicationId!==status.publicationId||row.context.decisionId!==row.decision.decisionId||JSON.stringify(ordered(row.context.source.values))!==JSON.stringify(ordered(row.item)))))throw new Error('Historical source context mismatch');
+}
+
+/** Explicit output target and incumbent pin; never a global review-rate mutation. */
+export function publicationSteeringPayload(status:PublicationStatus,classifier:string,bindingRef:PublicationRevisionRef,command:PublicationSteeringInput):PublicationSteeringPayload{
+ if(!status.outputs.some(output=>output.id===classifier)||!status.classifiers[classifier])throw new Error('Steering output is outside this publication');
+ if(!command.requestId.trim()||!command.explanation.trim())throw new Error('Steering needs a stable identity and explicit explanation');
+ const fingerprint=status.classifiers[classifier].cyclotron.fingerprint;
+ if(!fingerprint)throw new Error('Active classifier fingerprint unavailable');
+ if(command.action==='evaluate'){
+  if(!Object.keys(command.proposal).length||Object.keys(command.proposal).some(key=>!['rubric','tasks','example_ids','dynamic_elements'].includes(key)))throw new Error('Native proposal fields required');
+ }else if(command.action!=='promote'||!command.trialFingerprint.trim())throw new Error('An explicitly evaluated trial is required');
+ return {...command,explanation:command.explanation.trim(),bindingRevision:status.bindingRevision,bindingRef,classifier,expectedFingerprint:fingerprint};
+}
+
+export function publicationReviewPayload(binding:PublicationEnvelope,row:PublicationHistoryRow,classifier:string,review:ReviewControlReview,requestId:string):PublicationReviewPayload{
+ if(row.context&&row.context.binding.values.accountId!==binding.accountId)throw new Error('Review account context mismatch');
+ if(row.historicalContext||row.provenanceUnavailable||row.feedbackReconciliationRequired||row.context&&row.context.binding.values.revision!==binding.bindingRevision)throw new Error('Historical source or binding revision is read-only');
+ const output=binding.outputs.find(output=>output.id===classifier);const prediction=row.decision.classifiers[classifier];
+ if(!output||!prediction||review.decisionId!==row.decision.decisionId||review.itemId!==row.decision.itemId)throw new Error('Review does not match the displayed publication decision');
+ if(!review.label||!output.classes.includes(review.label))throw new Error('Choose an explicit classification label');
+ if(!requestId.trim())throw new Error('A stable review request identity is required');
+ return {bindingRevision:binding.bindingRevision,decisionId:row.decision.decisionId,classifier,predictionVersion:prediction.version,predictionFingerprint:prediction.fingerprint,requestId,label:review.label,explanation:review.explanation?.trim()??'',reasonCode:review.reasonCode,...(row.context?{contextId:row.context.contextId}:{})};
+}
+
+/** Host chooses an authenticated same-origin BFF; storage mode never changes UI semantics. */
+export function createPublicationClient(scope:PublicationScope,request:(operation:string,payload:Record<string,unknown>,scope:Readonly<PublicationScope>)=>Promise<PublicationEnvelope&Record<string,unknown>>,currentScope:()=>PublicationScope|null){
+ const pinned=Object.freeze({accountId:scope.accountId,publicationId:scope.publicationId,bindingRevision:scope.bindingRevision});
+ const key=publicationScopeKey(pinned);
+ const assertSelected=()=>{const current=currentScope();if(!current||publicationScopeKey(current)!==key)throw new Error('Publication account selection changed; refresh context');};
+ const command=async(operation:string,payload:Record<string,unknown>)=>{
+  assertSelected();
+  if('bindingRevision' in payload&&payload.bindingRevision!==pinned.bindingRevision)throw new Error('Publication binding changed; refresh context');
+  const value=await request(operation,payload,pinned);
+  assertSelected();
+  if(value.contractVersion!=='cyclotron-publication/v1'||publicationScopeKey(value)!==key)throw new Error('Publication response contract mismatch');
+  return value;
+ };
+ return {scope:pinned,cacheKey:key,command,status:async()=>await command('status',{}) as PublicationStatus,history:async()=>await command('history',{}) as PublicationHistory,
+  review:async(payload:PublicationReviewPayload)=>command('review',payload),
+  steer:async(payload:PublicationSteeringPayload)=>command('steer',payload),replayRecords:async()=>command('replay',{})};
+}