@anthusai/papyrus 1.14.0 → 1.15.0

package/amplify/data/resource.js

@@ -219,6 +219,25 @@ const schema = a.schema({
         grantorLabel: a.string(),
         expiresAt: a.datetime().required(),
         revokedAt: a.datetime(),
+        state: a.string(),
+        userCode: a.string(),
+        requestedHours: a.integer(),
+        pendingExpiresAt: a.datetime(),
+        approvedAt: a.datetime(),
+        deniedAt: a.datetime(),
+    }),
+    CurationDelegationRequestResult: a.customType({
+        ok: a.boolean().required(),
+        delegationId: a.id().required(),
+        userCode: a.string().required(),
+        pendingExpiresAt: a.datetime().required(),
+        requestedHours: a.integer().required(),
+    }),
+    CurationDelegationStatusResult: a.customType({
+        delegationId: a.id().required(),
+        state: a.string().required(),
+        expiresAt: a.datetime().required(),
+        grantorLabel: a.string(),
     }),
     ReferenceCurationActionResult: a.customType({
         ok: a.boolean().required(),
@@ -333,6 +352,49 @@ const schema = a.schema({
         allow.groups(categoryWriteGroups),
     ])
         .handler(a.handler.function(categoryAction)),
+    requestCurationDelegation: a
+        .mutation()
+        .arguments({
+        delegationId: a.id().required(),
+        tokenHash: a.string().required(),
+        agentLabel: a.string().required(),
+        hours: a.integer(),
+    })
+        .returns(a.ref("CurationDelegationRequestResult"))
+        .authorization((allow) => [
+        allow.authenticated("identityPool"),
+    ])
+        .handler(a.handler.function(categoryAction)),
+    approveCurationDelegation: a
+        .mutation()
+        .arguments({
+        userCode: a.string().required(),
+    })
+        .returns(a.ref("CurationDelegationResult"))
+        .authorization((allow) => [
+        allow.groups(categoryWriteGroups),
+    ])
+        .handler(a.handler.function(categoryAction)),
+    denyCurationDelegation: a
+        .mutation()
+        .arguments({
+        userCode: a.string().required(),
+    })
+        .returns(a.ref("CurationDelegationResult"))
+        .authorization((allow) => [
+        allow.groups(categoryWriteGroups),
+    ])
+        .handler(a.handler.function(categoryAction)),
+    getCurationDelegationStatus: a
+        .query()
+        .arguments({
+        delegationId: a.id().required(),
+    })
+        .returns(a.ref("CurationDelegationStatusResult"))
+        .authorization((allow) => [
+        allow.authenticated("identityPool"),
+    ])
+        .handler(a.handler.function(categoryAction)),
     recordDelegatedCuration: a
         .mutation()
         .arguments({

package/amplify/data/resource.ts

@@ -236,6 +236,27 @@ const schema = a.schema({
     grantorLabel: a.string(),
     expiresAt: a.datetime().required(),
     revokedAt: a.datetime(),
+    state: a.string(),
+    userCode: a.string(),
+    requestedHours: a.integer(),
+    pendingExpiresAt: a.datetime(),
+    approvedAt: a.datetime(),
+    deniedAt: a.datetime(),
+  }),
+
+  CurationDelegationRequestResult: a.customType({
+    ok: a.boolean().required(),
+    delegationId: a.id().required(),
+    userCode: a.string().required(),
+    pendingExpiresAt: a.datetime().required(),
+    requestedHours: a.integer().required(),
+  }),
+
+  CurationDelegationStatusResult: a.customType({
+    delegationId: a.id().required(),
+    state: a.string().required(),
+    expiresAt: a.datetime().required(),
+    grantorLabel: a.string(),
   }),
 
   ReferenceCurationActionResult: a.customType({
@@ -363,6 +384,53 @@ const schema = a.schema({
     ])
     .handler(a.handler.function(categoryAction)),
 
+  requestCurationDelegation: a
+    .mutation()
+    .arguments({
+      delegationId: a.id().required(),
+      tokenHash: a.string().required(),
+      agentLabel: a.string().required(),
+      hours: a.integer(),
+    })
+    .returns(a.ref("CurationDelegationRequestResult"))
+    .authorization((allow) => [
+      allow.authenticated("identityPool"),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
+  approveCurationDelegation: a
+    .mutation()
+    .arguments({
+      userCode: a.string().required(),
+    })
+    .returns(a.ref("CurationDelegationResult"))
+    .authorization((allow) => [
+      allow.groups(categoryWriteGroups),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
+  denyCurationDelegation: a
+    .mutation()
+    .arguments({
+      userCode: a.string().required(),
+    })
+    .returns(a.ref("CurationDelegationResult"))
+    .authorization((allow) => [
+      allow.groups(categoryWriteGroups),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
+  getCurationDelegationStatus: a
+    .query()
+    .arguments({
+      delegationId: a.id().required(),
+    })
+    .returns(a.ref("CurationDelegationStatusResult"))
+    .authorization((allow) => [
+      allow.authenticated("identityPool"),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
   recordDelegatedCuration: a
     .mutation()
     .arguments({

package/amplify/data/schema.js

@@ -211,6 +211,25 @@ const baseDefinitions = {
         grantorLabel: a.string(),
         expiresAt: a.datetime().required(),
         revokedAt: a.datetime(),
+        state: a.string(),
+        userCode: a.string(),
+        requestedHours: a.integer(),
+        pendingExpiresAt: a.datetime(),
+        approvedAt: a.datetime(),
+        deniedAt: a.datetime(),
+    }),
+    CurationDelegationRequestResult: a.customType({
+        ok: a.boolean().required(),
+        delegationId: a.id().required(),
+        userCode: a.string().required(),
+        pendingExpiresAt: a.datetime().required(),
+        requestedHours: a.integer().required(),
+    }),
+    CurationDelegationStatusResult: a.customType({
+        delegationId: a.id().required(),
+        state: a.string().required(),
+        expiresAt: a.datetime().required(),
+        grantorLabel: a.string(),
     }),
     ReferenceCurationActionResult: a.customType({
         ok: a.boolean().required(),
@@ -291,6 +310,49 @@ const baseDefinitions = {
         allow.groups(categoryWriteGroups),
     ])
         .handler(a.handler.function(categoryAction)),
+    requestCurationDelegation: a
+        .mutation()
+        .arguments({
+        delegationId: a.id().required(),
+        tokenHash: a.string().required(),
+        agentLabel: a.string().required(),
+        hours: a.integer(),
+    })
+        .returns(a.ref("CurationDelegationRequestResult"))
+        .authorization((allow) => [
+        allow.authenticated("identityPool"),
+    ])
+        .handler(a.handler.function(categoryAction)),
+    approveCurationDelegation: a
+        .mutation()
+        .arguments({
+        userCode: a.string().required(),
+    })
+        .returns(a.ref("CurationDelegationResult"))
+        .authorization((allow) => [
+        allow.groups(categoryWriteGroups),
+    ])
+        .handler(a.handler.function(categoryAction)),
+    denyCurationDelegation: a
+        .mutation()
+        .arguments({
+        userCode: a.string().required(),
+    })
+        .returns(a.ref("CurationDelegationResult"))
+        .authorization((allow) => [
+        allow.groups(categoryWriteGroups),
+    ])
+        .handler(a.handler.function(categoryAction)),
+    getCurationDelegationStatus: a
+        .query()
+        .arguments({
+        delegationId: a.id().required(),
+    })
+        .returns(a.ref("CurationDelegationStatusResult"))
+        .authorization((allow) => [
+        allow.authenticated("identityPool"),
+    ])
+        .handler(a.handler.function(categoryAction)),
     recordDelegatedCuration: a
         .mutation()
         .arguments({

package/amplify/data/schema.ts

@@ -230,6 +230,27 @@ const baseDefinitions = {
     grantorLabel: a.string(),
     expiresAt: a.datetime().required(),
     revokedAt: a.datetime(),
+    state: a.string(),
+    userCode: a.string(),
+    requestedHours: a.integer(),
+    pendingExpiresAt: a.datetime(),
+    approvedAt: a.datetime(),
+    deniedAt: a.datetime(),
+  }),
+
+  CurationDelegationRequestResult: a.customType({
+    ok: a.boolean().required(),
+    delegationId: a.id().required(),
+    userCode: a.string().required(),
+    pendingExpiresAt: a.datetime().required(),
+    requestedHours: a.integer().required(),
+  }),
+
+  CurationDelegationStatusResult: a.customType({
+    delegationId: a.id().required(),
+    state: a.string().required(),
+    expiresAt: a.datetime().required(),
+    grantorLabel: a.string(),
   }),
 
   ReferenceCurationActionResult: a.customType({
@@ -319,6 +340,53 @@ const baseDefinitions = {
     ])
     .handler(a.handler.function(categoryAction)),
 
+  requestCurationDelegation: a
+    .mutation()
+    .arguments({
+      delegationId: a.id().required(),
+      tokenHash: a.string().required(),
+      agentLabel: a.string().required(),
+      hours: a.integer(),
+    })
+    .returns(a.ref("CurationDelegationRequestResult"))
+    .authorization((allow) => [
+      allow.authenticated("identityPool"),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
+  approveCurationDelegation: a
+    .mutation()
+    .arguments({
+      userCode: a.string().required(),
+    })
+    .returns(a.ref("CurationDelegationResult"))
+    .authorization((allow) => [
+      allow.groups(categoryWriteGroups),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
+  denyCurationDelegation: a
+    .mutation()
+    .arguments({
+      userCode: a.string().required(),
+    })
+    .returns(a.ref("CurationDelegationResult"))
+    .authorization((allow) => [
+      allow.groups(categoryWriteGroups),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
+  getCurationDelegationStatus: a
+    .query()
+    .arguments({
+      delegationId: a.id().required(),
+    })
+    .returns(a.ref("CurationDelegationStatusResult"))
+    .authorization((allow) => [
+      allow.authenticated("identityPool"),
+    ])
+    .handler(a.handler.function(categoryAction)),
+
   recordDelegatedCuration: a
     .mutation()
     .arguments({

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

@@ -12,14 +12,28 @@ import {
   delegationRefusalMessage,
   delegationVerdict,
   newDelegationToken,
+  PENDING_REQUEST_GRANTOR_SUB,
   type CurationDelegation,
 } from "../shared/curation-delegation";
+import {
+  approveDelegation,
+  delegationResult as flowDelegationResult,
+  delegationStatus,
+  denyDelegation,
+  livePendingRequests,
+  requestDelegation,
+  type DelegationStore,
+} from "../shared/curation-delegation-flow";
 
 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 RequestCurationDelegationHandler = Schema["requestCurationDelegation"]["functionHandler"];
+type ApproveCurationDelegationHandler = Schema["approveCurationDelegation"]["functionHandler"];
+type DenyCurationDelegationHandler = Schema["denyCurationDelegation"]["functionHandler"];
+type GetCurationDelegationStatusHandler = Schema["getCurationDelegationStatus"]["functionHandler"];
 type RecordDelegatedCurationHandler = Schema["recordDelegatedCuration"]["functionHandler"];
 type ReferenceQualityHandler = Schema["setReferenceQualityRating"]["functionHandler"];
 type ReferenceNoteHandler = Schema["createReferenceNote"]["functionHandler"];
@@ -39,6 +53,10 @@ type CategoryActionEvent =
   | Parameters<CreateCurationDelegationHandler>[0]
   | Parameters<RevokeCurationDelegationHandler>[0]
   | Parameters<ListCurationDelegationsHandler>[0]
+  | Parameters<RequestCurationDelegationHandler>[0]
+  | Parameters<ApproveCurationDelegationHandler>[0]
+  | Parameters<DenyCurationDelegationHandler>[0]
+  | Parameters<GetCurationDelegationStatusHandler>[0]
   | Parameters<RecordDelegatedCurationHandler>[0]
   | Parameters<ReferenceQualityHandler>[0]
   | Parameters<ReferenceNoteHandler>[0]
@@ -108,6 +126,10 @@ export const handler = async (event: CategoryActionEvent) => {
   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 === "requestCurationDelegation") return requestCurationDelegationAction(event as Parameters<RequestCurationDelegationHandler>[0]);
+  if (fieldName === "approveCurationDelegation") return approveCurationDelegationAction(event as Parameters<ApproveCurationDelegationHandler>[0]);
+  if (fieldName === "denyCurationDelegation") return denyCurationDelegationAction(event as Parameters<DenyCurationDelegationHandler>[0]);
+  if (fieldName === "getCurationDelegationStatus") return getCurationDelegationStatusAction(event as Parameters<GetCurationDelegationStatusHandler>[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]);
@@ -376,17 +398,68 @@ async function writeCurationDelegation(client: DataClient, delegation: CurationD
 }
 
 function delegationResult(delegation: CurationDelegation, token: string | null) {
+  return { ...flowDelegationResult(delegation, new Date().toISOString()), token };
+}
+
+async function listPendingCurationDelegations(client: DataClient): Promise<CurationDelegation[]> {
+  const pending: CurationDelegation[] = [];
+  let nextToken: string | null | undefined;
+  do {
+    const page: any = await (client.models.KnowledgeRawPayload as any).listKnowledgeRawPayloadsByOwnerAndKind(
+      { ownerId: PENDING_REQUEST_GRANTOR_SUB, payloadKind: { eq: CURATION_DELEGATION_PAYLOAD_KIND } },
+      { nextToken },
+    );
+    assertNoDataErrors(page.errors, "list pending curation delegations");
+    for (const payload of page.data ?? []) {
+      const delegation = await readCurationDelegation(client, payload.id);
+      if (delegation) pending.push(delegation);
+    }
+    nextToken = page.nextToken;
+  } while (nextToken);
+  return pending;
+}
+
+function curationDelegationStore(client: DataClient): DelegationStore {
   return {
-    ok: true,
-    delegationId: delegation.delegationId,
-    token,
-    agentLabel: delegation.agentLabel,
-    grantorLabel: delegation.grantorLabel,
-    expiresAt: delegation.expiresAt,
-    revokedAt: delegation.revokedAt,
+    read: (delegationId) => readCurationDelegation(client, delegationId),
+    write: (delegation, now, created) => writeCurationDelegation(client, delegation, now, created),
+    listPending: () => listPendingCurationDelegations(client),
   };
 }
 
+async function requestCurationDelegationAction(event: Parameters<RequestCurationDelegationHandler>[0]) {
+  const client = await getDataClient();
+  return requestDelegation(
+    curationDelegationStore(client),
+    {
+      delegationId: normalizeRequiredString(event.arguments.delegationId, "delegationId"),
+      tokenHash: normalizeRequiredString(event.arguments.tokenHash, "tokenHash"),
+      agentLabel: normalizeRequiredString(event.arguments.agentLabel, "agentLabel"),
+      hours: event.arguments.hours,
+    },
+    new Date().toISOString(),
+  );
+}
+
+async function approveCurationDelegationAction(event: Parameters<ApproveCurationDelegationHandler>[0]) {
+  const person = requireSignedInPerson(event);
+  const client = await getDataClient();
+  const now = new Date().toISOString();
+  return { ...(await approveDelegation(curationDelegationStore(client), person, normalizeRequiredString(event.arguments.userCode, "userCode"), now)), token: null };
+}
+
+async function denyCurationDelegationAction(event: Parameters<DenyCurationDelegationHandler>[0]) {
+  const person = requireSignedInPerson(event);
+  const client = await getDataClient();
+  const now = new Date().toISOString();
+  return { ...(await denyDelegation(curationDelegationStore(client), person, normalizeRequiredString(event.arguments.userCode, "userCode"), now)), token: null };
+}
+
+async function getCurationDelegationStatusAction(event: Parameters<GetCurationDelegationStatusHandler>[0]) {
+  const client = await getDataClient();
+  return delegationStatus(curationDelegationStore(client), normalizeRequiredString(event.arguments.delegationId, "delegationId"), new Date().toISOString());
+}
+
 async function createCurationDelegation(event: Parameters<CreateCurationDelegationHandler>[0]) {
   const person = requireSignedInPerson(event);
   const client = await getDataClient();
@@ -412,7 +485,7 @@ async function revokeCurationDelegation(event: Parameters<RevokeCurationDelegati
   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.");
+  if (delegation.grantorSub !== person.sub && delegation.grantorSub !== PENDING_REQUEST_GRANTOR_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);
@@ -436,6 +509,8 @@ async function listCurationDelegations(event: Parameters<ListCurationDelegations
     }
     nextToken = page.nextToken;
   } while (nextToken);
+  const now = new Date().toISOString();
+  delegations.push(...(await livePendingRequests(curationDelegationStore(client), now)));
   return delegations
     .sort((first, second) => second.createdAt.localeCompare(first.createdAt))
     .map((delegation) => delegationResult(delegation, null));

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

@@ -0,0 +1,147 @@
+import {
+  EXPIRED_REQUEST_GRANTOR_SUB,
+  MAXIMUM_PENDING_DELEGATION_REQUESTS,
+  PENDING_DELEGATION_MINUTES,
+  PENDING_REQUEST_GRANTOR_SUB,
+  delegationExpiry,
+  delegationState,
+  formatUserCode,
+  newUserCode,
+  normalizeUserCode,
+  type CurationDelegation,
+} from "./curation-delegation"
+
+export type DelegationStore = {
+  read(delegationId: string): Promise<CurationDelegation | null>
+  write(delegation: CurationDelegation, now: string, created: boolean): Promise<void>
+  listPending(): Promise<CurationDelegation[]>
+}
+
+export type SignedInPerson = { sub: string; label: string; isAdmin: boolean }
+
+const DELEGATION_ID_PATTERN = /^curation-delegation-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+const TOKEN_HASH_PATTERN = /^[0-9a-f]{64}$/
+const MAXIMUM_AGENT_LABEL_LENGTH = 80
+const USER_CODE_ATTEMPTS = 50
+
+export function delegationResult(delegation: CurationDelegation, now: string) {
+  const state = delegationState(delegation, now)
+  return {
+    ok: true,
+    delegationId: delegation.delegationId,
+    token: null,
+    agentLabel: delegation.agentLabel,
+    grantorLabel: delegation.grantorLabel || null,
+    expiresAt: delegation.expiresAt,
+    revokedAt: delegation.revokedAt,
+    state,
+    userCode: state === "pending" && delegation.userCode ? formatUserCode(delegation.userCode) : null,
+    requestedHours: delegation.requestedHours ?? null,
+    pendingExpiresAt: delegation.pendingExpiresAt ?? null,
+    approvedAt: delegation.approvedAt ?? null,
+    deniedAt: delegation.deniedAt ?? null,
+  }
+}
+
+export async function livePendingRequests(store: DelegationStore, now: string): Promise<CurationDelegation[]> {
+  const live: CurationDelegation[] = []
+  for (const candidate of await store.listPending()) {
+    if (delegationState(candidate, now) === "pending") {
+      live.push(candidate)
+    } else if (candidate.grantorSub === PENDING_REQUEST_GRANTOR_SUB) {
+      await store.write({ ...candidate, grantorSub: EXPIRED_REQUEST_GRANTOR_SUB }, now, false)
+    }
+  }
+  return live
+}
+
+export async function requestDelegation(
+  store: DelegationStore,
+  input: { delegationId: string; tokenHash: string; agentLabel: string; hours: number | null | undefined },
+  now: string,
+) {
+  if (!DELEGATION_ID_PATTERN.test(input.delegationId)) {
+    throw new Error("The delegation id must look like curation-delegation-<uuid>.")
+  }
+  if (!TOKEN_HASH_PATTERN.test(input.tokenHash)) throw new Error("The token hash must be 64 lowercase hexadecimal characters.")
+  const agentLabel = input.agentLabel.trim()
+  if (!agentLabel) throw new Error("Name the agent asking for the delegation.")
+  if (agentLabel.length > MAXIMUM_AGENT_LABEL_LENGTH) throw new Error("The agent name is too long.")
+  const requestedHours = input.hours ?? 8
+  delegationExpiry(now, requestedHours)
+  if (await store.read(input.delegationId)) throw new Error("That delegation id is already in use.")
+  const live = await livePendingRequests(store, now)
+  if (live.length >= MAXIMUM_PENDING_DELEGATION_REQUESTS) {
+    throw new Error("Too many delegation requests are waiting for approval. Try again later.")
+  }
+  const takenCodes = new Set(live.map((request) => request.userCode))
+  let userCode = newUserCode()
+  for (let attempt = 0; takenCodes.has(userCode); attempt += 1) {
+    if (attempt >= USER_CODE_ATTEMPTS) throw new Error("Could not allocate a unique approval code. Try again.")
+    userCode = newUserCode()
+  }
+  const pendingExpiresAt = new Date(Date.parse(now) + PENDING_DELEGATION_MINUTES * 60_000).toISOString()
+  const delegation: CurationDelegation = {
+    delegationId: input.delegationId,
+    tokenHash: input.tokenHash,
+    grantorSub: PENDING_REQUEST_GRANTOR_SUB,
+    grantorLabel: "",
+    agentLabel,
+    createdAt: now,
+    expiresAt: pendingExpiresAt,
+    revokedAt: null,
+    userCode,
+    requestedHours,
+    pendingExpiresAt,
+    approvedAt: null,
+    deniedAt: null,
+  }
+  await store.write(delegation, now, true)
+  return {
+    ok: true,
+    delegationId: delegation.delegationId,
+    userCode: formatUserCode(userCode),
+    pendingExpiresAt,
+    requestedHours,
+  }
+}
+
+async function findLivePendingByCode(store: DelegationStore, typedCode: string, now: string): Promise<CurationDelegation> {
+  const code = normalizeUserCode(typedCode)
+  const found = code ? (await livePendingRequests(store, now)).find((request) => request.userCode === code) : undefined
+  if (!found) throw new Error("No pending delegation request has that code. It may have expired or already been decided.")
+  return found
+}
+
+export async function approveDelegation(store: DelegationStore, person: SignedInPerson, typedCode: string, now: string) {
+  const pending = await findLivePendingByCode(store, typedCode, now)
+  const approved: CurationDelegation = {
+    ...pending,
+    grantorSub: person.sub,
+    grantorLabel: person.label,
+    createdAt: now,
+    expiresAt: delegationExpiry(now, pending.requestedHours),
+    approvedAt: now,
+    userCode: null,
+  }
+  await store.write(approved, now, false)
+  return delegationResult(approved, now)
+}
+
+export async function denyDelegation(store: DelegationStore, person: SignedInPerson, typedCode: string, now: string) {
+  const pending = await findLivePendingByCode(store, typedCode, now)
+  const denied: CurationDelegation = { ...pending, grantorSub: person.sub, grantorLabel: person.label, deniedAt: now, userCode: null }
+  await store.write(denied, now, false)
+  return delegationResult(denied, now)
+}
+
+export async function delegationStatus(store: DelegationStore, delegationId: string, now: string) {
+  const delegation = await store.read(delegationId)
+  if (!delegation) throw new Error("That delegation was not found.")
+  return {
+    delegationId: delegation.delegationId,
+    state: delegationState(delegation, now),
+    expiresAt: delegation.expiresAt,
+    grantorLabel: delegation.grantorLabel || null,
+  }
+}

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

@@ -1,4 +1,4 @@
-import { createHash, randomBytes } from "node:crypto"
+import { createHash, randomBytes, randomInt } from "node:crypto"
 
 export const CURATION_DELEGATION_PAYLOAD_KIND = "curation-delegation"
 export const CURATION_DELEGATION_OWNER_TYPE = "curationDelegation"
@@ -14,11 +14,18 @@ export type CurationDelegation = {
   createdAt: string
   expiresAt: string
   revokedAt: string | null
+  userCode?: string | null
+  requestedHours?: number | null
+  pendingExpiresAt?: string | null
+  approvedAt?: string | null
+  deniedAt?: string | null
 }
 
+export type DelegationState = "pending" | "approved" | "denied" | "expired" | "revoked"
+
 export type DelegationVerdict =
   | { ok: true }
-  | { ok: false; reason: "unknown-token" | "wrong-agent" | "revoked" | "expired" }
+  | { ok: false; reason: "unknown-token" | "wrong-agent" | "revoked" | "not-approved" | "expired" }
 
 export function hashDelegationToken(token: string): string {
   return createHash("sha256").update(token, "utf8").digest("hex")
@@ -53,6 +60,10 @@ export function delegationVerdict(
     return { ok: false, reason: "wrong-agent" }
   }
   if (delegation.revokedAt) return { ok: false, reason: "revoked" }
+  const state = delegationState(delegation, presented.now)
+  if (state === "pending" || state === "denied" || (state === "expired" && delegation.userCode && !delegation.approvedAt)) {
+    return { ok: false, reason: "not-approved" }
+  }
   if (Date.parse(delegation.expiresAt) <= Date.parse(presented.now)) return { ok: false, reason: "expired" }
   return { ok: true }
 }
@@ -62,6 +73,43 @@ export function delegationRefusalMessage(reason: Exclude<DelegationVerdict, { ok
     "unknown-token": "That delegation token is not recognized.",
     "wrong-agent": "That delegation was granted to a different agent.",
     "revoked": "That delegation was revoked.",
+    "not-approved": "That delegation has not been approved by a person. Ask them to approve the code in the Newsroom.",
     "expired": "That delegation has expired. Ask the person for a new one.",
   }[reason]
 }
+
+export const PENDING_DELEGATION_MINUTES = 10
+export const MAXIMUM_PENDING_DELEGATION_REQUESTS = 5
+export const PENDING_REQUEST_GRANTOR_SUB = "pending-device-authorization"
+export const EXPIRED_REQUEST_GRANTOR_SUB = "expired-device-authorization"
+export const USER_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"
+export const USER_CODE_LENGTH = 8
+
+export function newUserCode(): string {
+  let code = ""
+  for (let position = 0; position < USER_CODE_LENGTH; position += 1) {
+    code += USER_CODE_ALPHABET[randomInt(USER_CODE_ALPHABET.length)]
+  }
+  return code
+}
+
+export function formatUserCode(code: string): string {
+  return `${code.slice(0, 4)}-${code.slice(4)}`
+}
+
+export function normalizeUserCode(typed: string | null | undefined): string | null {
+  const stripped = (typed ?? "").toUpperCase().replace(/[\s-]/g, "")
+  if (stripped.length !== USER_CODE_LENGTH) return null
+  for (const character of stripped) if (!USER_CODE_ALPHABET.includes(character)) return null
+  return stripped
+}
+
+export function delegationState(delegation: CurationDelegation, now: string): DelegationState {
+  if (delegation.revokedAt) return "revoked"
+  if (delegation.deniedAt) return "denied"
+  if (delegation.userCode && !delegation.approvedAt) {
+    const pendingEnd = delegation.pendingExpiresAt ?? delegation.expiresAt
+    return Date.parse(pendingEnd) <= Date.parse(now) ? "expired" : "pending"
+  }
+  return Date.parse(delegation.expiresAt) <= Date.parse(now) ? "expired" : "approved"
+}