@anthusai/papyrus 1.4.0-next.6 → 1.4.0-next.8

package/amplify/data/resource.js

@@ -211,6 +211,15 @@ const schema = a.schema({
         .returns(a.ref("SteeringActionResult"))
         .authorization((allow) => [allow.groups(categoryWriteGroups)])
         .handler(a.handler.function(categoryAction)),
+    CurationDelegationResult: a.customType({
+        ok: a.boolean().required(),
+        delegationId: a.id().required(),
+        token: a.string(),
+        agentLabel: a.string().required(),
+        grantorLabel: a.string(),
+        expiresAt: a.datetime().required(),
+        revokedAt: a.datetime(),
+    }),
     ReferenceCurationActionResult: a.customType({
         ok: a.boolean().required(),
         action: a.string().required(),
@@ -289,12 +298,62 @@ const schema = a.schema({
         reasonCode: a.string(),
         decisionRelationId: a.id(),
         shareable: a.boolean(),
+        sectionId: a.id(),
     })
         .returns(a.ref("ReferenceCurationActionResult"))
         .authorization((allow) => [
         allow.groups(categoryWriteGroups),
     ])
         .handler(a.handler.function(categoryAction)),
+    createCurationDelegation: a
+        .mutation()
+        .arguments({
+        agentLabel: a.string().required(),
+        hours: a.integer(),
+    })
+        .returns(a.ref("CurationDelegationResult"))
+        .authorization((allow) => [
+        allow.groups(categoryWriteGroups),
+    ])
+        .handler(a.handler.function(categoryAction)),
+    revokeCurationDelegation: a
+        .mutation()
+        .arguments({
+        delegationId: a.id().required(),
+    })
+        .returns(a.ref("CurationDelegationResult"))
+        .authorization((allow) => [
+        allow.groups(categoryWriteGroups),
+    ])
+        .handler(a.handler.function(categoryAction)),
+    listCurationDelegations: a
+        .query()
+        .returns(a.ref("CurationDelegationResult").array())
+        .authorization((allow) => [
+        allow.groups(categoryWriteGroups),
+    ])
+        .handler(a.handler.function(categoryAction)),
+    recordDelegatedCuration: a
+        .mutation()
+        .arguments({
+        referenceId: a.id().required(),
+        action: a.string().required(),
+        delegationId: a.id().required(),
+        delegationToken: a.string().required(),
+        agentLabel: a.string().required(),
+        onBehalfOf: a.string().required(),
+        instruction: a.string().required(),
+        note: a.string(),
+        reasonCode: a.string(),
+        decisionRelationId: a.id(),
+        shareable: a.boolean(),
+        sectionId: a.id(),
+    })
+        .returns(a.ref("ReferenceCurationActionResult"))
+        .authorization((allow) => [
+        allow.authenticated("identityPool"),
+    ])
+        .handler(a.handler.function(categoryAction)),
     setReferenceQualityRating: a
         .mutation()
         .arguments({

package/amplify/data/resource.ts

@@ -228,6 +228,16 @@ const schema = a.schema({
     .authorization((allow) => [allow.groups(categoryWriteGroups)])
     .handler(a.handler.function(categoryAction)),
 
+  CurationDelegationResult: a.customType({
+    ok: a.boolean().required(),
+    delegationId: a.id().required(),
+    token: a.string(),
+    agentLabel: a.string().required(),
+    grantorLabel: a.string(),
+    expiresAt: a.datetime().required(),
+    revokedAt: a.datetime(),
+  }),
+
   ReferenceCurationActionResult: a.customType({
     ok: a.boolean().required(),
     action: a.string().required(),
@@ -314,6 +324,7 @@ const schema = a.schema({
       reasonCode: a.string(),
       decisionRelationId: a.id(),
       shareable: a.boolean(),
+      sectionId: a.id(),
     })
     .returns(a.ref("ReferenceCurationActionResult"))
     .authorization((allow) => [
@@ -321,6 +332,59 @@ const schema = a.schema({
     ])
     .handler(a.handler.function(categoryAction)),
 
+  createCurationDelegation: a
+    .mutation()
+    .arguments({
+      agentLabel: a.string().required(),
+      hours: a.integer(),
+    })
+    .returns(a.ref("CurationDelegationResult"))
+    .authorization((allow) => [
+      allow.groups(categoryWriteGroups),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
+  revokeCurationDelegation: a
+    .mutation()
+    .arguments({
+      delegationId: a.id().required(),
+    })
+    .returns(a.ref("CurationDelegationResult"))
+    .authorization((allow) => [
+      allow.groups(categoryWriteGroups),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
+  listCurationDelegations: a
+    .query()
+    .returns(a.ref("CurationDelegationResult").array())
+    .authorization((allow) => [
+      allow.groups(categoryWriteGroups),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
+  recordDelegatedCuration: a
+    .mutation()
+    .arguments({
+      referenceId: a.id().required(),
+      action: a.string().required(),
+      delegationId: a.id().required(),
+      delegationToken: a.string().required(),
+      agentLabel: a.string().required(),
+      onBehalfOf: a.string().required(),
+      instruction: a.string().required(),
+      note: a.string(),
+      reasonCode: a.string(),
+      decisionRelationId: a.id(),
+      shareable: a.boolean(),
+      sectionId: a.id(),
+    })
+    .returns(a.ref("ReferenceCurationActionResult"))
+    .authorization((allow) => [
+      allow.authenticated("identityPool"),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
   setReferenceQualityRating: a
     .mutation()
     .arguments({

package/amplify/data/schema.js

@@ -203,6 +203,15 @@ const baseDefinitions = {
         .returns(a.ref("SteeringActionResult"))
         .authorization((allow) => [allow.groups(categoryWriteGroups)])
         .handler(a.handler.function(categoryAction)),
+    CurationDelegationResult: a.customType({
+        ok: a.boolean().required(),
+        delegationId: a.id().required(),
+        token: a.string(),
+        agentLabel: a.string().required(),
+        grantorLabel: a.string(),
+        expiresAt: a.datetime().required(),
+        revokedAt: a.datetime(),
+    }),
     ReferenceCurationActionResult: a.customType({
         ok: a.boolean().required(),
         action: a.string().required(),
@@ -247,12 +256,62 @@ const baseDefinitions = {
         reasonCode: a.string(),
         decisionRelationId: a.id(),
         shareable: a.boolean(),
+        sectionId: a.id(),
     })
         .returns(a.ref("ReferenceCurationActionResult"))
         .authorization((allow) => [
         allow.groups(categoryWriteGroups),
     ])
         .handler(a.handler.function(categoryAction)),
+    createCurationDelegation: a
+        .mutation()
+        .arguments({
+        agentLabel: a.string().required(),
+        hours: a.integer(),
+    })
+        .returns(a.ref("CurationDelegationResult"))
+        .authorization((allow) => [
+        allow.groups(categoryWriteGroups),
+    ])
+        .handler(a.handler.function(categoryAction)),
+    revokeCurationDelegation: a
+        .mutation()
+        .arguments({
+        delegationId: a.id().required(),
+    })
+        .returns(a.ref("CurationDelegationResult"))
+        .authorization((allow) => [
+        allow.groups(categoryWriteGroups),
+    ])
+        .handler(a.handler.function(categoryAction)),
+    listCurationDelegations: a
+        .query()
+        .returns(a.ref("CurationDelegationResult").array())
+        .authorization((allow) => [
+        allow.groups(categoryWriteGroups),
+    ])
+        .handler(a.handler.function(categoryAction)),
+    recordDelegatedCuration: a
+        .mutation()
+        .arguments({
+        referenceId: a.id().required(),
+        action: a.string().required(),
+        delegationId: a.id().required(),
+        delegationToken: a.string().required(),
+        agentLabel: a.string().required(),
+        onBehalfOf: a.string().required(),
+        instruction: a.string().required(),
+        note: a.string(),
+        reasonCode: a.string(),
+        decisionRelationId: a.id(),
+        shareable: a.boolean(),
+        sectionId: a.id(),
+    })
+        .returns(a.ref("ReferenceCurationActionResult"))
+        .authorization((allow) => [
+        allow.authenticated("identityPool"),
+    ])
+        .handler(a.handler.function(categoryAction)),
     setReferenceQualityRating: a
         .mutation()
         .arguments({

package/amplify/data/schema.ts

@@ -222,6 +222,16 @@ const baseDefinitions = {
     .authorization((allow) => [allow.groups(categoryWriteGroups)])
     .handler(a.handler.function(categoryAction)),
 
+  CurationDelegationResult: a.customType({
+    ok: a.boolean().required(),
+    delegationId: a.id().required(),
+    token: a.string(),
+    agentLabel: a.string().required(),
+    grantorLabel: a.string(),
+    expiresAt: a.datetime().required(),
+    revokedAt: a.datetime(),
+  }),
+
   ReferenceCurationActionResult: a.customType({
     ok: a.boolean().required(),
     action: a.string().required(),
@@ -270,6 +280,7 @@ const baseDefinitions = {
       reasonCode: a.string(),
       decisionRelationId: a.id(),
       shareable: a.boolean(),
+      sectionId: a.id(),
     })
     .returns(a.ref("ReferenceCurationActionResult"))
     .authorization((allow) => [
@@ -277,6 +288,59 @@ const baseDefinitions = {
     ])
     .handler(a.handler.function(categoryAction)),
 
+  createCurationDelegation: a
+    .mutation()
+    .arguments({
+      agentLabel: a.string().required(),
+      hours: a.integer(),
+    })
+    .returns(a.ref("CurationDelegationResult"))
+    .authorization((allow) => [
+      allow.groups(categoryWriteGroups),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
+  revokeCurationDelegation: a
+    .mutation()
+    .arguments({
+      delegationId: a.id().required(),
+    })
+    .returns(a.ref("CurationDelegationResult"))
+    .authorization((allow) => [
+      allow.groups(categoryWriteGroups),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
+  listCurationDelegations: a
+    .query()
+    .returns(a.ref("CurationDelegationResult").array())
+    .authorization((allow) => [
+      allow.groups(categoryWriteGroups),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
+  recordDelegatedCuration: a
+    .mutation()
+    .arguments({
+      referenceId: a.id().required(),
+      action: a.string().required(),
+      delegationId: a.id().required(),
+      delegationToken: a.string().required(),
+      agentLabel: a.string().required(),
+      onBehalfOf: a.string().required(),
+      instruction: a.string().required(),
+      note: a.string(),
+      reasonCode: a.string(),
+      decisionRelationId: a.id(),
+      shareable: a.boolean(),
+      sectionId: a.id(),
+    })
+    .returns(a.ref("ReferenceCurationActionResult"))
+    .authorization((allow) => [
+      allow.authenticated("identityPool"),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
   setReferenceQualityRating: a
     .mutation()
     .arguments({

package/amplify/functions/category-action/handler.ts

@@ -4,10 +4,23 @@ import { Amplify } from "aws-amplify";
 import { generateClient } from "aws-amplify/data";
 import type { Schema } from "../../data/resource";
 import { putJsonModelPayload, putTextModelPayload, readJsonModelPayload } from "../shared/model-payloads";
-import { curationActorKind, referenceCurationMetadata } from "../shared/reference-curation-metadata";
+import { curationActorKind, referenceCurationMetadata, validatedCurationSectionId } from "../shared/reference-curation-metadata";
+import {
+  CURATION_DELEGATION_OWNER_TYPE,
+  CURATION_DELEGATION_PAYLOAD_KIND,
+  delegationExpiry,
+  delegationRefusalMessage,
+  delegationVerdict,
+  newDelegationToken,
+  type CurationDelegation,
+} from "../shared/curation-delegation";
 
 type ReviewHandler = Schema["reviewSteeringProposal"]["functionHandler"];
 type ReferenceCurationHandler = Schema["reviewReferenceCuration"]["functionHandler"];
+type CreateCurationDelegationHandler = Schema["createCurationDelegation"]["functionHandler"];
+type RevokeCurationDelegationHandler = Schema["revokeCurationDelegation"]["functionHandler"];
+type ListCurationDelegationsHandler = Schema["listCurationDelegations"]["functionHandler"];
+type RecordDelegatedCurationHandler = Schema["recordDelegatedCuration"]["functionHandler"];
 type ReferenceQualityHandler = Schema["setReferenceQualityRating"]["functionHandler"];
 type ReferenceNoteHandler = Schema["createReferenceNote"]["functionHandler"];
 type MoveReferenceCorpusHandler = Schema["moveReferenceCorpus"]["functionHandler"];
@@ -23,6 +36,10 @@ type ReviewReferenceTopicLabelHandler = Schema["reviewReferenceTopicLabel"]["fun
 type CategoryActionEvent =
   | Parameters<ReviewHandler>[0]
   | Parameters<ReferenceCurationHandler>[0]
+  | Parameters<CreateCurationDelegationHandler>[0]
+  | Parameters<RevokeCurationDelegationHandler>[0]
+  | Parameters<ListCurationDelegationsHandler>[0]
+  | Parameters<RecordDelegatedCurationHandler>[0]
   | Parameters<ReferenceQualityHandler>[0]
   | Parameters<ReferenceNoteHandler>[0]
   | Parameters<MoveReferenceCorpusHandler>[0]
@@ -88,6 +105,10 @@ export const handler = async (event: CategoryActionEvent) => {
   }
   if (fieldName === "reviewSteeringProposal") return reviewSteeringProposal(event as Parameters<ReviewHandler>[0]);
   if (fieldName === "reviewReferenceCuration") return reviewReferenceCuration(event as Parameters<ReferenceCurationHandler>[0]);
+  if (fieldName === "createCurationDelegation") return createCurationDelegation(event as Parameters<CreateCurationDelegationHandler>[0]);
+  if (fieldName === "revokeCurationDelegation") return revokeCurationDelegation(event as Parameters<RevokeCurationDelegationHandler>[0]);
+  if (fieldName === "listCurationDelegations") return listCurationDelegations(event as Parameters<ListCurationDelegationsHandler>[0]);
+  if (fieldName === "recordDelegatedCuration") return recordDelegatedCuration(event as Parameters<RecordDelegatedCurationHandler>[0]);
   if (fieldName === "setReferenceQualityRating") return setReferenceQualityRating(event as Parameters<ReferenceQualityHandler>[0]);
   if (fieldName === "createReferenceNote") return createReferenceNote(event as Parameters<ReferenceNoteHandler>[0]);
   if (fieldName === "moveReferenceCorpus") return moveReferenceCorpus(event as Parameters<MoveReferenceCorpusHandler>[0]);
@@ -162,13 +183,21 @@ async function reviewSteeringProposal(event: Parameters<ReviewHandler>[0]) {
   };
 }
 
-async function reviewReferenceCuration(event: Parameters<ReferenceCurationHandler>[0]) {
+async function reviewReferenceCuration(
+  event: Parameters<ReferenceCurationHandler>[0],
+  delegation: { delegationId: string; relayedBy: string; instruction: string } | null = null,
+) {
   const client = await getDataClient();
   const referenceId = normalizeRequiredString(event.arguments.referenceId, "referenceId");
   const action = normalizeReferenceCurationAction(event.arguments.action);
   const nextStatus = referenceCurationStatusForAction(action);
   const reasonCode = normalizeReferenceRejectionReasonCode(event.arguments.reasonCode, action === "reject");
   const reference = await getRequiredRecord(client.models.Reference, referenceId, "Reference");
+  const requestedSectionId = normalizeOptionalString(event.arguments.sectionId);
+  const sectionRecord = requestedSectionId
+    ? (await client.models.NewsroomSection.get({ id: requestedSectionId })).data ?? null
+    : null;
+  const sectionId = validatedCurationSectionId(requestedSectionId, action, sectionRecord);
   const now = new Date().toISOString();
   const actorSub = normalizeOptionalString(event.arguments.actorSub) ?? getIdentitySub(event);
   const actorLabel = normalizeOptionalString(event.arguments.actorLabel) ?? getIdentityLabel(event);
@@ -234,7 +263,9 @@ async function reviewReferenceCuration(event: Parameters<ReferenceCurationHandle
       referenceLineageId,
       decisionRelationId: normalizeOptionalString(event.arguments.decisionRelationId),
       shareable: event.arguments.shareable ?? null,
-      actorKind: curationActorKind(event.identity),
+      actorKind: delegation ? "human" : curationActorKind(event.identity),
+      sectionId,
+      delegation,
     }),
     { filename: "metadata.json", now },
   );
@@ -301,6 +332,151 @@ async function reviewReferenceCuration(event: Parameters<ReferenceCurationHandle
   };
 }
 
+function requireSignedInPerson(event: { identity?: unknown }): { sub: string; label: string; isAdmin: boolean } {
+  if (curationActorKind(event.identity) !== "human") {
+    throw new Error("Only a person signed in to the Newsroom can manage curation delegations.");
+  }
+  const identity = event.identity as { sub?: unknown; claims?: Record<string, unknown> };
+  const claims = identity.claims ?? {};
+  const groups = Array.isArray(claims["cognito:groups"]) ? (claims["cognito:groups"] as unknown[]) : [];
+  return {
+    sub: normalizeRequiredString(claims.sub ?? identity.sub, "identity.sub"),
+    label: normalizeOptionalString(claims.email) ?? normalizeOptionalString(claims.name) ?? "Newsroom editor",
+    isAdmin: groups.includes("admin"),
+  };
+}
+
+async function readCurationDelegation(client: DataClient, delegationId: string): Promise<CurationDelegation | null> {
+  const stored = await readJsonModelPayload(client as any, "knowledgeRawPayload", delegationId, "raw_payload", CURATION_DELEGATION_PAYLOAD_KIND);
+  return stored ? (stored as unknown as CurationDelegation) : null;
+}
+
+async function writeCurationDelegation(client: DataClient, delegation: CurationDelegation, now: string, created: boolean) {
+  const input = {
+    id: delegation.delegationId,
+    ownerType: CURATION_DELEGATION_OWNER_TYPE,
+    ownerId: delegation.grantorSub,
+    payloadKind: CURATION_DELEGATION_PAYLOAD_KIND,
+    createdAt: delegation.createdAt,
+    updatedAt: now,
+  };
+  if (created) {
+    await requireDataResult(client.models.KnowledgeRawPayload.create(input), "create curation delegation");
+  } else {
+    await requireDataResult(client.models.KnowledgeRawPayload.update(input), "update curation delegation");
+  }
+  await putJsonModelPayload(
+    client as any,
+    { ownerKind: "knowledgeRawPayload", ownerId: delegation.delegationId },
+    "raw_payload",
+    CURATION_DELEGATION_PAYLOAD_KIND,
+    delegation as unknown as Record<string, unknown>,
+    { filename: "curation-delegation.json", now },
+  );
+}
+
+function delegationResult(delegation: CurationDelegation, token: string | null) {
+  return {
+    ok: true,
+    delegationId: delegation.delegationId,
+    token,
+    agentLabel: delegation.agentLabel,
+    grantorLabel: delegation.grantorLabel,
+    expiresAt: delegation.expiresAt,
+    revokedAt: delegation.revokedAt,
+  };
+}
+
+async function createCurationDelegation(event: Parameters<CreateCurationDelegationHandler>[0]) {
+  const person = requireSignedInPerson(event);
+  const client = await getDataClient();
+  const now = new Date().toISOString();
+  const delegationId = `curation-delegation-${randomUUID()}`;
+  const { token, tokenHash } = newDelegationToken(delegationId);
+  const delegation: CurationDelegation = {
+    delegationId,
+    tokenHash,
+    grantorSub: person.sub,
+    grantorLabel: person.label,
+    agentLabel: normalizeRequiredString(event.arguments.agentLabel, "agentLabel"),
+    createdAt: now,
+    expiresAt: delegationExpiry(now, event.arguments.hours),
+    revokedAt: null,
+  };
+  await writeCurationDelegation(client, delegation, now, true);
+  return delegationResult(delegation, token);
+}
+
+async function revokeCurationDelegation(event: Parameters<RevokeCurationDelegationHandler>[0]) {
+  const person = requireSignedInPerson(event);
+  const client = await getDataClient();
+  const delegation = await readCurationDelegation(client, normalizeRequiredString(event.arguments.delegationId, "delegationId"));
+  if (!delegation) throw new Error("That delegation was not found.");
+  if (delegation.grantorSub !== person.sub && !person.isAdmin) throw new Error("Only the person who granted a delegation can revoke it.");
+  const now = new Date().toISOString();
+  const revoked = { ...delegation, revokedAt: delegation.revokedAt ?? now };
+  await writeCurationDelegation(client, revoked, now, false);
+  return delegationResult(revoked, null);
+}
+
+async function listCurationDelegations(event: Parameters<ListCurationDelegationsHandler>[0]) {
+  const person = requireSignedInPerson(event);
+  const client = await getDataClient();
+  const delegations: CurationDelegation[] = [];
+  let nextToken: string | null | undefined;
+  do {
+    const page: any = await (client.models.KnowledgeRawPayload as any).listKnowledgeRawPayloadsByOwnerAndKind(
+      { ownerId: person.sub, payloadKind: { eq: CURATION_DELEGATION_PAYLOAD_KIND } },
+      { nextToken },
+    );
+    assertNoDataErrors(page.errors, "list curation delegations");
+    for (const payload of page.data ?? []) {
+      const delegation = await readCurationDelegation(client, payload.id);
+      if (delegation) delegations.push(delegation);
+    }
+    nextToken = page.nextToken;
+  } while (nextToken);
+  return delegations
+    .sort((first, second) => second.createdAt.localeCompare(first.createdAt))
+    .map((delegation) => delegationResult(delegation, null));
+}
+
+async function recordDelegatedCuration(event: Parameters<RecordDelegatedCurationHandler>[0]) {
+  const client = await getDataClient();
+  const now = new Date().toISOString();
+  const delegationId = normalizeRequiredString(event.arguments.delegationId, "delegationId");
+  const agentLabel = normalizeRequiredString(event.arguments.agentLabel, "agentLabel");
+  const delegation = await readCurationDelegation(client, delegationId);
+  const verdict = delegationVerdict(delegation, {
+    token: normalizeRequiredString(event.arguments.delegationToken, "delegationToken"),
+    agentLabel,
+    now,
+  });
+  if (!verdict.ok || !delegation) {
+    throw new Error(delegationRefusalMessage(verdict.ok ? "unknown-token" : verdict.reason));
+  }
+  const instruction = normalizeRequiredString(event.arguments.instruction, "instruction").slice(0, 2000);
+  const namedPerson = normalizeRequiredString(event.arguments.onBehalfOf, "onBehalfOf");
+  if (namedPerson.toLowerCase() !== delegation.grantorLabel.toLowerCase()) {
+    throw new Error(`That delegation was granted by ${delegation.grantorLabel}, not ${namedPerson}.`);
+  }
+  const onBehalfOfPerson = {
+    ...event,
+    arguments: {
+      referenceId: event.arguments.referenceId,
+      action: event.arguments.action,
+      note: event.arguments.note,
+      reasonCode: event.arguments.reasonCode,
+      decisionRelationId: event.arguments.decisionRelationId,
+      shareable: event.arguments.shareable,
+      sectionId: event.arguments.sectionId,
+      actorSub: delegation.grantorSub,
+      actorLabel: delegation.grantorLabel,
+    },
+  } as unknown as Parameters<ReferenceCurationHandler>[0];
+  return reviewReferenceCuration(onBehalfOfPerson, { delegationId, relayedBy: agentLabel, instruction });
+}
+
 async function setReferenceQualityRating(event: Parameters<ReferenceQualityHandler>[0]) {
   const client = await getDataClient();
   const referenceId = normalizeRequiredString(event.arguments.referenceId, "referenceId");

package/amplify/functions/shared/curation-delegation.ts

@@ -0,0 +1,67 @@
+import { createHash, randomBytes } from "node:crypto"
+
+export const CURATION_DELEGATION_PAYLOAD_KIND = "curation-delegation"
+export const CURATION_DELEGATION_OWNER_TYPE = "curationDelegation"
+export const DEFAULT_DELEGATION_HOURS = 8
+export const MAXIMUM_DELEGATION_HOURS = 72
+
+export type CurationDelegation = {
+  delegationId: string
+  tokenHash: string
+  grantorSub: string
+  grantorLabel: string
+  agentLabel: string
+  createdAt: string
+  expiresAt: string
+  revokedAt: string | null
+}
+
+export type DelegationVerdict =
+  | { ok: true }
+  | { ok: false; reason: "unknown-token" | "wrong-agent" | "revoked" | "expired" }
+
+export function hashDelegationToken(token: string): string {
+  return createHash("sha256").update(token, "utf8").digest("hex")
+}
+
+export function newDelegationToken(delegationId: string): { token: string; tokenHash: string } {
+  const token = `${delegationId}~${randomBytes(24).toString("base64url")}`
+  return { token, tokenHash: hashDelegationToken(token) }
+}
+
+export function delegationIdFromToken(token: string): string | null {
+  const separator = token.indexOf("~")
+  return separator > 0 ? token.slice(0, separator) : null
+}
+
+export function delegationExpiry(now: string, hours: number | null | undefined): string {
+  const requested = hours ?? DEFAULT_DELEGATION_HOURS
+  if (!Number.isFinite(requested) || requested <= 0 || requested > MAXIMUM_DELEGATION_HOURS) {
+    throw new Error(`A delegation lasts between 1 and ${MAXIMUM_DELEGATION_HOURS} hours.`)
+  }
+  return new Date(Date.parse(now) + requested * 3_600_000).toISOString()
+}
+
+export function delegationVerdict(
+  delegation: CurationDelegation | null,
+  presented: { token: string; agentLabel: string; now: string },
+): DelegationVerdict {
+  if (!delegation || delegation.tokenHash !== hashDelegationToken(presented.token)) {
+    return { ok: false, reason: "unknown-token" }
+  }
+  if (delegation.agentLabel.trim().toLowerCase() !== presented.agentLabel.trim().toLowerCase()) {
+    return { ok: false, reason: "wrong-agent" }
+  }
+  if (delegation.revokedAt) return { ok: false, reason: "revoked" }
+  if (Date.parse(delegation.expiresAt) <= Date.parse(presented.now)) return { ok: false, reason: "expired" }
+  return { ok: true }
+}
+
+export function delegationRefusalMessage(reason: Exclude<DelegationVerdict, { ok: true }>["reason"]): string {
+  return {
+    "unknown-token": "That delegation token is not recognized.",
+    "wrong-agent": "That delegation was granted to a different agent.",
+    "revoked": "That delegation was revoked.",
+    "expired": "That delegation has expired. Ask the person for a new one.",
+  }[reason]
+}

package/amplify/functions/shared/reference-curation-metadata.ts

@@ -13,6 +13,8 @@ export type ReferenceCurationMetadataInput = {
   decisionRelationId?: string | null
   shareable?: boolean | null
   actorKind?: CurationActorKind | null
+  sectionId?: string | null
+  delegation?: { delegationId: string; relayedBy: string; instruction: string } | null
 }
 
 export type CurationActorKind = "human" | "service"
@@ -38,7 +40,41 @@ export function referenceCurationMetadata(input: ReferenceCurationMetadataInput)
     referenceId: input.referenceId,
     referenceLineageId: input.referenceLineageId,
     ...(input.actorKind ? {actorKind: input.actorKind} : {}),
+    ...(input.sectionId?.trim() ? {sectionId: input.sectionId.trim()} : {}),
+    ...(input.delegation
+      ? {attestation: "delegated", relayedBy: input.delegation.relayedBy, delegationId: input.delegation.delegationId,
+         instruction: input.delegation.instruction}
+      : {}),
     ...(decisionRelationId ? {decisionRelationId} : {}),
     ...(decisionRelationId ? {shareable: input.shareable === true} : {}),
   }
 }
+
+export type CurationSectionCandidate = {
+  id?: string | null
+  enabled?: boolean | null
+  enabledStatus?: string | null
+} | null | undefined
+
+/**
+ * A curation may name the newsroom Section the Reference belongs in, but only
+ * when it accepts the Reference and the Section exists and is enabled.
+ */
+export function validatedCurationSectionId(
+  requestedSectionId: string | null | undefined,
+  action: string,
+  section: CurationSectionCandidate,
+): string | null {
+  const sectionId = requestedSectionId?.trim() || null
+  if (!sectionId) return null
+  if (action !== "accept") {
+    throw new Error("A section can be recorded only when accepting a reference.")
+  }
+  if (!section || section.id !== sectionId) {
+    throw new Error(`Newsroom section ${sectionId} was not found.`)
+  }
+  if (section.enabled === false || section.enabledStatus === "disabled") {
+    throw new Error(`Newsroom section ${sectionId} is disabled.`)
+  }
+  return sectionId
+}