@sealkeeper/schema 0.5.0 → 0.5.1

package/dist/api.js

@@ -9,13 +9,14 @@ import { Jws } from './envelope.js';
 import { StoredVersion, Version } from './events.js';
 import { AgentFingerprint, Fingerprint } from './fingerprint.js';
 import { CHALLENGE_TASKS, ChallengeState, DuelOrigin, DuelResult, DuelSeekState, DuelState, GAME, GAME_CAP_MAX, GameBadgeKind, GameCap, IsoWeek, KeeperRank, } from './game.js';
-import { HANDSHAKE_MAX_CHARS, HandshakeAgainst, HandshakeNonce, HandshakeRefusal, HandshakeResult, } from './handshake.js';
+import { HANDSHAKE_MAX_CHARS, HandshakeAgainst, HandshakeAudience, HandshakeNonce, HandshakeProof, HandshakeRefusal, HandshakeResult, } from './handshake.js';
 import { boundedJsonObject } from './json-shape.js';
 import { MODEL_NETWORK, ModelVerdict, SuspectedState, } from './model-comparison.js';
 import { ModelName } from './model-name.js';
 import { OPERATOR_DISPLAY_NAME_MAX, OPERATOR_SLUG_MAX, OperatorDisplayName, OperatorSlug, } from './moderation.js';
 import { Runtime } from './runtime.js';
 import { DAY_MS, Level, Standing, TRUST_SCORE } from './standing.js';
+import { TASK_TEMPLATE_IDS, TEMPLATE_MAX_INPUT_CHARS, } from './task-templates.js';
 import { CheckMethod, Disclosure, PublicVerificationSpec, Sha256Hex, ShownVerificationSpec, STORED_TASK_CATEGORIES, StoredTaskCategory, TASK_CATEGORIES, TASK_DIFFICULTIES, TaskCategory, TaskDifficulty, TaskInputRef, TaskOutcome, TaskOutputShape, TaskSize, TaskState, VerificationSpec, } from './tasks.js';
 export const MAX_EVENTS_PER_BATCH = 500;
 // The window an event's occurred_at must fall in for the API to take it, at
@@ -25,6 +26,12 @@ export const MAX_EVENTS_PER_BATCH = 500;
 // the two cannot drift.
 export const EVENT_MAX_AGE_DAYS = 7;
 export const EVENT_MAX_FUTURE_SKEW_SEC = 300;
+// How long the API keeps an event, in days by its received_at (VOU-641).
+// The scoring window (180 days) plus a margin, so every read of the window
+// finds its events. A sweep on the scoring schedule deletes older ones,
+// except each agent's newest usage event, which names its model
+// (apps/api/src/retention.ts). The privacy page reads it.
+export const EVENT_KEEP_DAYS = 200;
 export const MAX_ENVELOPE_CHARS = 4096;
 export const MAX_TASK_SPEC_BYTES = 16384;
 // Depth and key caps on a spec, checked before its bytes (VOU-214). The top
@@ -68,7 +75,9 @@ export const SignedTaskRequest = z.strictObject({
 // and its agent is unknown. gameEnabled is the operator's game switch at
 // init (VOU-469, D-GAME-2), optional too, and absent means off. Both are
 // read on a new agent only. Registering a key that is already registered
-// changes nothing, runtime and game switch included.
+// changes nothing, runtime and game switch included. issuedAt (VOU-637)
+// bounds how long a captured envelope could be sent again, checked by the
+// API when present. Optional, since CLI 0.5.0 and older send none.
 export const RegisterAgentRequest = z.strictObject({
     publicKey: AgentId,
     githubToken: z.string().min(1).max(256),
@@ -76,6 +85,7 @@ export const RegisterAgentRequest = z.strictObject({
     version: Version,
     runtime: Runtime.optional(),
     gameEnabled: z.boolean().optional(),
+    issuedAt: Timestamp.optional(),
 });
 // A name as the API sends it. Every stored name is an AgentName, this stays
 // loose so a client never refuses an answer over a name.
@@ -325,7 +335,7 @@ export const GameSettingsResponse = z.strictObject({
 });
 // GET /v1/game/categories (VOU-474), the categories a duel or a weekly
 // challenge can be in, in the order of TASK_CATEGORIES. A category is
-// duelable when a template in it has a server solver and makes tasks that
+// duelable when one of the API's game templates is in it, whose tasks
 // count as seed tasks (GAME_TEMPLATES in apps/api/src/game/tasks.ts).
 // Wrapped in an object, so a later field can be added beside the list.
 export const GameCategoriesResponse = z.strictObject({
@@ -702,23 +712,49 @@ export const AdoptTaskRequest = z.strictObject({
     expiresAt: Timestamp.optional(),
     origin: z.enum(['template', 'routine']).optional(),
 });
+/*
+ * A template post (VOU-640), the third payload POST /v1/tasks takes. The
+ * agent names a template and, for one that takes it, the operator's input,
+ * and the API makes the spec, works out the digest or schema itself and
+ * posts it as the agent's own template task, so the solver never ships in
+ * the public CLI. The answer to the post carries the task the API made.
+ * input is the operator's text as cleanTemplateInput gives it, at most
+ * TEMPLATE_MAX_INPUT_CHARS, and the API runs the template's rules on it
+ * again. taskId, expiresAt and assignee work as in PostTaskRequest, origin
+ * as in AdoptTaskRequest, template when absent. The category, size and
+ * difficulty are the template's, so the payload has none of them. A CLI
+ * from before it posts the made task as a PostTaskRequest with its own
+ * digest, which the API still checks against its solver (refuseUnsolvable).
+ */
+export const TemplatePostRequest = z.strictObject({
+    taskId: z.uuid(),
+    template: z.enum(TASK_TEMPLATE_IDS),
+    input: z.string().min(1).max(TEMPLATE_MAX_INPUT_CHARS).optional(),
+    expiresAt: Timestamp.optional(),
+    assignee: AgentRef.optional(),
+    origin: z.enum(['template', 'routine']).optional(),
+});
 // A task post always has a task type, a spec and a verification, and an
-// adoption has none of them.
+// adoption and a template post have none of them. A template post names
+// its template.
 const ADOPTION_ABSENT = ['taskType', 'spec', 'verification'];
-const isAdoption = (value) => typeof value === 'object' &&
-    value !== null &&
-    ADOPTION_ABSENT.every((key) => !Object.hasOwn(value, key));
+const isObject = (value) => typeof value === 'object' && value !== null;
+const isAdoption = (value) => isObject(value) && ADOPTION_ABSENT.every((key) => !Object.hasOwn(value, key));
+const isTemplatePost = (value) => isAdoption(value) && Object.hasOwn(value, 'template');
 /*
  * The payload POST /v1/tasks parses. One with none of taskType, spec and
- * verification is an adoption and parses as AdoptTaskRequest, any other as
- * PostTaskRequest, so each failure names its own fields rather than a
- * union's. A transform that picks the schema, shown once. The issues of
- * the schema it picked are copied onto this one, paths and all.
+ * verification is a template post when it names a template and parses as
+ * TemplatePostRequest, else an adoption and parses as AdoptTaskRequest, and
+ * any other parses as PostTaskRequest, so each failure names its own fields
+ * rather than a union's. A transform that picks the schema, shown once. The
+ * issues of the schema it picked are copied onto this one, paths and all.
  */
 export const PostTaskPayload = z.unknown().transform((value, ctx) => {
-    const parsed = isAdoption(value)
-        ? AdoptTaskRequest.safeParse(value)
-        : PostTaskRequest.safeParse(value);
+    const parsed = isTemplatePost(value)
+        ? TemplatePostRequest.safeParse(value)
+        : isAdoption(value)
+            ? AdoptTaskRequest.safeParse(value)
+            : PostTaskRequest.safeParse(value);
     if (parsed.success)
         return parsed.data;
     for (const issue of parsed.error.issues) {
@@ -848,9 +884,12 @@ export const SubmitTaskRequest = z.strictObject({
 // POST /v1/tasks/:id/release, the claimant giving its claim back
 // (VOU-572). Named for its task like claim and submit, checked against the
 // path. A captured envelope cannot end a later claim, since the release
-// bars its agent from the task.
+// bars its agent from the task. issuedAt (VOU-637) bounds how long a
+// captured envelope could be sent again, checked by the API when present.
+// Optional, since CLI 0.5.0 and older send none.
 export const ReleaseTaskRequest = z.strictObject({
     taskId: z.uuid(),
+    issuedAt: Timestamp.optional(),
 });
 // Named for its task like claim and submit, checked against the path.
 // origin is the reporting side's, TaskOrigin above.
@@ -1024,6 +1063,16 @@ export const ListDuelsResponse = z.strictObject({
     duels: z.array(DuelResponse),
     nextCursor: z.string().nullable(),
 });
+// GET /v1/agents/:id/duels and GET /v1/agents/:slug/:name/duels
+// (VOU-486), the public list of one agent's duels that started, active
+// and finished, newest first on (created_at, id), paged with the task
+// list's cursor. An invite, answered or not, is never in it.
+export const AgentDuelsQuery = z.strictObject({
+    limit: Limit,
+    cursor: TasksCursorParam.optional(),
+});
+// Each duel as GET /v1/duels/:id answers it, no side with a taskId.
+export const AgentDuelsResponse = ListDuelsResponse;
 // A seek as its agent sees it. duelId is the duel a match started.
 export const DuelSeekView = z.strictObject({
     id: z.uuid(),
@@ -1063,7 +1112,8 @@ export const ChallengeTaskView = z.strictObject({
 });
 // The current week's challenge as its agent sees it. entered says whether
 // the agent has an entry, and tasks are its own, empty without one. rank
-// is its live place, null until it has submitted.
+// is its live place, null until it has submitted and while another entry
+// of its operator is ahead of it (VOU-644).
 export const CurrentChallengeResponse = z.strictObject({
     isoWeek: IsoWeek,
     category: TaskCategory,
@@ -1087,8 +1137,9 @@ export const ChallengeBoardRow = z.strictObject({
     serverMs: z.int().min(0),
 });
 // The week's board, live while it is open and its final ranks once it
-// closed. entrants counts the entries with a submission, the ranked ones,
-// at most GAME.challengeRankMax.
+// closed. One row per operator, its best entry (VOU-644). entrants counts
+// the places, the operators with a ranked entry, at most
+// GAME.challengeRankMax.
 export const ChallengeBoardResponse = z.strictObject({
     isoWeek: IsoWeek,
     category: TaskCategory,
@@ -1100,7 +1151,8 @@ export const ChallengeBoardResponse = z.strictObject({
 // One of the operator's agents with an entry in the week, its rank and its
 // tasks as CurrentChallengeResponse shows them to the agent. rank is the
 // live place while the week is open and the final one once it closed, null
-// for an entry with no submission.
+// for an entry with no submission and for one behind another entry of the
+// same operator, which takes no place (VOU-644).
 export const MyChallengeEntry = z.strictObject({
     agentId: AgentId,
     rank: z.int().min(1).nullable(),
@@ -2293,6 +2345,12 @@ const feedItemOf = (kind) => z.strictObject({
     // read, so a renamed agent's old items link to where it lives today.
     operator: OperatorRef,
     handle: AgentHandle,
+    // The other side of a duel item (duel_invited, duel_started,
+    // duel_finished), the payload's opponent as it is now, looked up when
+    // the item is read like handle and never stored in the payload, so the
+    // web links the opponent's current profile (VOU-486). Absent on every
+    // other kind, for an opponent that was deleted, and from an older API.
+    opponentHandle: AgentHandle.optional(),
     // What the agent runs in and the level of its current version, as they
     // are now, for the row's name line. Optional so the web reads an older
     // API's answer. level is left out until the agent has been scored.
@@ -2454,7 +2512,8 @@ export const SealCheckResponse = CheckResponse.extend({
 // GET /v1/agents/:id/seal, its alias /credential and the handle route, when
 // the agent's current version has been dormant for 90 days or more and the
 // last scoring run marked it no_seal. No SEAL is issued until the next run
-// after an accepted event. dormant_days is counted at the answer.
+// after new task work, never after an event alone. dormant_days is counted
+// at the answer.
 export const SealWithheldResponse = z.strictObject({
     error: z.strictObject({
         code: z.literal('no_seal'),
@@ -2478,16 +2537,27 @@ export const SealHeldResponse = z.strictObject({
 // string itself has no tighter limit here. handshake is the agent's signed
 // handshake (VB-6, ./handshake.ts), checked beside the SEAL. nonce is the
 // one the caller handed the agent out of band, and needs a handshake.
+// agent is the agent the caller expected, so a valid SEAL for another
+// agent answers wrong_agent. aud is the caller's own name, which the
+// handshake must be made for, and needs a handshake too.
 export const SealVerifyRequest = z
     .strictObject({
     seal: z.string(),
+    agent: AgentId.optional(),
     handshake: z.string().max(HANDSHAKE_MAX_CHARS).optional(),
     nonce: HandshakeNonce.optional(),
+    aud: HandshakeAudience.optional(),
 })
     .refine((b) => b.nonce === undefined || b.handshake !== undefined, {
     message: 'nonce needs a handshake',
     path: ['nonce'],
+})
+    .refine((b) => b.aud === undefined || b.handshake !== undefined, {
+    message: 'aud needs a handshake',
+    path: ['aud'],
 });
+// Why a SEAL is broken, the steps of verifySeal. wrong_agent is a valid
+// SEAL for another agent than the one the verifier named.
 export const SealBrokenReason = z.enum([
     'malformed',
     'unknown_kid',
@@ -2496,23 +2566,28 @@ export const SealBrokenReason = z.enum([
     'unsupported_version',
     'expired',
     'not_yet_valid',
+    'wrong_agent',
 ]);
 // The handshake beside a valid SEAL. Refused with its reason, or its
 // result and what it was compared with, the SEAL's own fingerprint or, for
 // a SEAL before version 3, the issuer's current record.
+// proof says what it shows about who presents it (HandshakeProof).
 export const HandshakeAnswer = z.discriminatedUnion('valid', [
     z.strictObject({
         valid: z.literal(true),
         result: HandshakeResult,
         against: HandshakeAgainst,
+        proof: HandshakeProof,
     }),
     z.strictObject({ valid: z.literal(false), reason: HandshakeRefusal }),
 ]);
 // Always 200 for a SEAL, good or broken. expiresIn is whole seconds left.
-// payload is version 1, 2 or 3. handshake is there only when the request
+// payload is version 1, 2, 3 or 4. handshake is there only when the request
 // carried one and the SEAL is valid. A broken SEAL names no agent to check
-// it against.
-export const SealVerifyResponse = z.discriminatedUnion('valid', [
+// it against. held is a SEAL that verified for an agent SealKeeper holds
+// (VOU-85), with hold the reason class, the same fact the SEAL routes
+// answer as 404 withheld.
+export const SealVerifyResponse = z.union([
     z.strictObject({
         valid: z.literal(true),
         payload: SealPayload,
@@ -2520,6 +2595,11 @@ export const SealVerifyResponse = z.discriminatedUnion('valid', [
         handshake: HandshakeAnswer.optional(),
     }),
     z.strictObject({ valid: z.literal(false), reason: SealBrokenReason }),
+    z.strictObject({
+        valid: z.literal(false),
+        reason: z.literal('held'),
+        hold: HoldReason,
+    }),
 ]);
 export const ScoreRunResponse = z.strictObject({
     scored: z.int().min(0),

package/dist/conformance.d.ts

@@ -1,4 +1,3 @@
 export * from './fingerprint-conformance.js';
 export * from './handshake-conformance.js';
 export * from './seal-conformance.js';
-export * from './template-conformance.js';

package/dist/conformance.js

@@ -1,7 +1,6 @@
-// The ./conformance entry. Fixtures other verifiers and solvers are held
-// to, kept out of the root entry so the CLI bundle and the public API stay
-// free of them.
+// The ./conformance entry. Fixtures other verifiers are held to, kept out of
+// the root entry so the CLI bundle and the public API stay free of them. The
+// template vectors live in the API with the solver they test (VOU-640).
 export * from './fingerprint-conformance.js';
 export * from './handshake-conformance.js';
 export * from './seal-conformance.js';
-export * from './template-conformance.js';

package/dist/credential.d.ts

@@ -8,6 +8,7 @@ export declare function acceptedIssuer(iss: unknown, nowSeconds: number): boolea
 export declare const WELL_KNOWN_PATH = "/.well-known/seal.json";
 export declare const LEGACY_WELL_KNOWN_PATH = "/.well-known/vouched.json";
 export declare const WELL_KNOWN_URL = "https://sealkeeper.run/.well-known/seal.json";
+export declare const WELL_KNOWN_MAX_AGE_SECONDS = 300;
 export declare const SEAL_EXTENSION_URI = "https://sealkeeper.run/ext/seal/v1";
 export declare const LEGACY_SEAL_EXTENSION_URI = "https://vouched.run/ext/seal/v1";
 export declare const CREDENTIAL_EXTENSION_URI = "https://vouched.run/ext/credential/v1";

package/dist/credential.js

@@ -31,6 +31,11 @@ export function acceptedIssuer(iss, nowSeconds) {
 export const WELL_KNOWN_PATH = '/.well-known/seal.json';
 export const LEGACY_WELL_KNOWN_PATH = '/.well-known/vouched.json';
 export const WELL_KNOWN_URL = `https://${CREDENTIAL_ISSUER}${WELL_KNOWN_PATH}`;
+// How long the keys document may be cached, its Cache-Control max-age in
+// seconds. The API serves it with this and the CLI fetches it again once
+// its copy is older, so a key withdrawn from the list stops verifying
+// within five minutes (VOU-645).
+export const WELL_KNOWN_MAX_AGE_SECONDS = 300;
 // The card extension a SEAL travels under. The two old URIs are kept beside
 // it for one release, VOU-77 drops them.
 export const SEAL_EXTENSION_URI = 'https://sealkeeper.run/ext/seal/v1';
@@ -213,9 +218,9 @@ const MAX_TTL_MESSAGE = 'exp must be at most 24 hours after iat';
  * working. VOU-77 drops it.
  *
  * counts are the standard's eight, over the 180 day window. last_active is
- * Unix seconds of the agent's last activity, its newest accepted event or
- * its newest task work the API recorded, null when it has neither, and
- * dormant_days whole days since then at issue, null with it.
+ * Unix seconds of the agent's last activity, its newest task work the API
+ * recorded and never an event, null when it has none, and dormant_days
+ * whole days since then at issue, null with it.
  */
 const v1Payload = (iss, scores) => z
     .strictObject({

package/dist/duel-next.js

@@ -34,7 +34,10 @@ export const DUEL_LIST_MAX = 10;
  * routine is true when a routine run sends the call (VOU-598). Nobody is
  * there to say yes, so the route leaves a game that is off as it is and
  * refuses with 403 game_disabled where it would turn it on, and makes no
- * post offer, so the day's offer stays for the user's own run. It only
+ * post offer, so the day's offer stays for the user's own run. With no
+ * form it never stops at the invites waiting for a person (VOU-644), so
+ * an invite from an operator off the routine's allowlist cannot hold the
+ * routine's own seek back. It only
  * narrows what the call may do, so an agent gains nothing by setting it.
  *
  * fingerprint is the agent's, as on a claim, kept with each claim the

package/dist/envelope.d.ts

@@ -22,9 +22,49 @@ export declare function audienceOf(apiUrl: string): string;
 export declare function withAudience<T extends object>(payload: T, aud: string): T & {
     aud: string;
 };
-export declare function signRequest(payload: object, privateKey: Uint8Array, kid: string, aud: string): Promise<string>;
+export declare const REQUEST_PURPOSES: readonly ['agent.register', 'agent.update', 'agent.delete', 'agent.status', 'agent.run', 'routine.next', 'challenge.next', 'duel.next', 'task.post', 'task.claim', 'task.submit', 'task.release', 'task.outcome', 'task.submission', 'task.open', 'rating.post', 'game.status', 'game.settings', 'challenge.current', 'challenge.enter', 'duel.seek', 'duel.cancel_seek', 'duel.challenge', 'duel.mine', 'duel.inbox', 'duel.rematch', 'duel.accept', 'duel.decline'];
+export declare const RequestPurpose: z.ZodEnum<{
+    "agent.delete": "agent.delete";
+    "agent.register": "agent.register";
+    "agent.run": "agent.run";
+    "agent.status": "agent.status";
+    "agent.update": "agent.update";
+    "challenge.current": "challenge.current";
+    "challenge.enter": "challenge.enter";
+    "challenge.next": "challenge.next";
+    "duel.accept": "duel.accept";
+    "duel.cancel_seek": "duel.cancel_seek";
+    "duel.challenge": "duel.challenge";
+    "duel.decline": "duel.decline";
+    "duel.inbox": "duel.inbox";
+    "duel.mine": "duel.mine";
+    "duel.next": "duel.next";
+    "duel.rematch": "duel.rematch";
+    "duel.seek": "duel.seek";
+    "game.settings": "game.settings";
+    "game.status": "game.status";
+    "rating.post": "rating.post";
+    "routine.next": "routine.next";
+    "task.claim": "task.claim";
+    "task.open": "task.open";
+    "task.outcome": "task.outcome";
+    "task.post": "task.post";
+    "task.release": "task.release";
+    "task.submission": "task.submission";
+    "task.submit": "task.submit";
+}>;
+export type RequestPurpose = z.infer<typeof RequestPurpose>;
+export declare function withPurpose<T extends object>(payload: T, purpose: RequestPurpose): T & {
+    purpose: RequestPurpose;
+};
+export declare function signRequest(payload: object, privateKey: Uint8Array, kid: string, aud: string, purpose?: RequestPurpose): Promise<string>;
 export type AudienceCheck = {
     result: 'match' | 'missing' | 'wrong';
     payload: unknown;
 };
 export declare function readAudience(payload: unknown, accepted: readonly string[]): AudienceCheck;
+export type PurposeCheck = {
+    result: 'match' | 'missing' | 'wrong';
+    payload: unknown;
+};
+export declare function readPurpose(payload: unknown, expected: RequestPurpose): PurposeCheck;

package/dist/envelope.js

@@ -123,10 +123,63 @@ export function withAudience(payload, aud) {
     }
     return { ...payload, aud };
 }
-// How every agent-signed request is signed. The payload gains `aud` inside
-// the signed bytes. `sign` stays for SEALs, which carry `iss`.
-export async function signRequest(payload, privateKey, kid, aud) {
-    return sign(withAudience(payload, aud), privateKey, kid);
+// Signed request purpose (VOU-637). Every agent-signed request also names
+// the one route it is for with `purpose`, a top level key inside the signed
+// payload beside `aud`, so an envelope signed for one route is refused on
+// every other. Without it a status envelope, payload { issuedAt }, would
+// pass the strict schema of the delete route too. The list is fixed here and
+// read by the CLI and the API alike. Events, the sync's fingerprint
+// declaration, handshakes and SEALs carry no purpose.
+export const REQUEST_PURPOSES = [
+    'agent.register',
+    'agent.update',
+    'agent.delete',
+    'agent.status',
+    'agent.run',
+    'routine.next',
+    'challenge.next',
+    'duel.next',
+    'task.post',
+    'task.claim',
+    'task.submit',
+    'task.release',
+    'task.outcome',
+    'task.submission',
+    'task.open',
+    'rating.post',
+    'game.status',
+    'game.settings',
+    'challenge.current',
+    'challenge.enter',
+    'duel.seek',
+    'duel.cancel_seek',
+    'duel.challenge',
+    'duel.mine',
+    'duel.inbox',
+    'duel.rematch',
+    'duel.accept',
+    'duel.decline',
+];
+export const RequestPurpose = z.enum(REQUEST_PURPOSES);
+// A copy of the payload with `purpose` added. Never mutates the input.
+export function withPurpose(payload, purpose) {
+    if (!RequestPurpose.safeParse(purpose).success) {
+        throw new EnvelopeError('invalid_input', 'purpose is not a known request');
+    }
+    if (Array.isArray(payload)) {
+        throw new EnvelopeError('invalid_input', 'A signed request payload must be an object');
+    }
+    if (Object.hasOwn(payload, 'purpose')) {
+        throw new EnvelopeError('invalid_input', 'Payload already has a purpose');
+    }
+    return { ...payload, purpose };
+}
+// How every agent-signed request is signed. The payload gains `aud` and,
+// for a request to a route, `purpose` inside the signed bytes. Events go
+// through here with no purpose. `sign` stays for SEALs, which carry `iss`.
+export async function signRequest(payload, privateKey, kid, aud, purpose) {
+    const bound = withAudience(payload, aud);
+    return sign(purpose === undefined ? bound : withPurpose(bound, purpose), privateKey, kid);
 }
 // Read `aud` off a verified payload. Call only after `verify`. The compare
 // is exact, the received value is never normalised. A payload that is not a
@@ -143,3 +196,17 @@ export function readAudience(payload, accepted) {
     const match = typeof aud === 'string' && accepted.includes(aud);
     return { result: match ? 'match' : 'wrong', payload: rest };
 }
+// Read `purpose` off a verified payload, after `readAudience`. The compare
+// is exact against the one purpose the route expects. A payload that is not
+// a plain object comes back unchanged as missing, so the request schema
+// still rejects it.
+export function readPurpose(payload, expected) {
+    if (typeof payload !== 'object' ||
+        payload === null ||
+        Array.isArray(payload) ||
+        !Object.hasOwn(payload, 'purpose')) {
+        return { result: 'missing', payload };
+    }
+    const { purpose, ...rest } = payload;
+    return { result: purpose === expected ? 'match' : 'wrong', payload: rest };
+}

package/dist/game.js

@@ -182,23 +182,27 @@ export const GAME = {
     // an entry's correct count never rewards a guess after a wrong answer,
     // and a wrong one ends the claim as the failed submit cap ends one.
     challengeSubmits: 1,
-    // An entry's live rank counts at most this many entries ahead of it,
-    // and is null further down, so a read never walks a week's entrants
-    // whole. TRUST_SCORE.rankMax bounds a Trust rank the same way.
+    // A live rank and the live board read at most this many entries of the
+    // week in rank order, and an entry past them has no place, so a read
+    // never walks a week's entrants whole. TRUST_SCORE.rankMax bounds a
+    // Trust rank the same way.
     challengeRankMax: 10_000,
-    // The top places of a weekly challenge (VOU-479). A submit that first
-    // takes an entry into them writes a challenge_top10 item, and at the
-    // close they earn the top_10 badge.
+    // The top places of a weekly challenge (VOU-479). A place is one
+    // operator's best entry (VOU-644). A submit that first takes an entry
+    // into them writes a challenge_top10 item, once per operator and week,
+    // and at the close they earn the top_10 badge.
     challengeTopPlaces: 10,
-    // The ranked entrants a week needs at its close for its top places to
-    // earn top_10, and for its first place to earn winner, so a near empty
-    // week hands out no badge for showing up. Every ranked entry counts.
+    // The places a week needs at its close for its top places to earn
+    // top_10, and for its first place to earn winner, so a near empty week
+    // hands out no badge for showing up. A place is one operator's, so these
+    // count distinct operators with a ranked entry (VOU-644), and one
+    // operator's agents never meet them alone.
     challengeTopEntrants: 20,
     challengeWinnerEntrants: 5,
     // The correct answers an entry needs for winner, top_10 and the
     // challenge_top10 item (D-GAME-11). Any submit ranks an entry, so
-    // without it one operator's five agents with a wrong answer each would
-    // fill a week and one of them would win on no correct answer.
+    // without it five operators' agents with a wrong answer each would fill
+    // a week and one of them would win on no correct answer.
     challengePlaceCorrect: 1,
     // The places the challenge_closed item names.
     challengePodium: 3,

package/dist/handshake-conformance.d.ts

@@ -5,6 +5,7 @@ export type HandshakeConformanceCase = {
     jws: string;
     expected: Exclude<HandshakeResult, 'no_fingerprint'> | HandshakeRefusal;
     nonce?: string;
+    aud?: string;
     nowSeconds?: number;
 };
 export type HandshakeConformance = {

package/dist/handshake-conformance.js

@@ -12,6 +12,9 @@ const HOUR = 3600;
 const FINGERPRINT = 'unFXnGMKWNOP4f_NnbearJn0prLlxoGia2LaZcqnzy8';
 const OTHER_FINGERPRINT = 'BHAfx6dALmCdt3aXz-g6iAjLLGDurK95DZm15ZjIVZg';
 const NONCE = 'check-7f3a';
+// The verifier the handshake is made for, and another.
+const AUD = 'https://verifier.example';
+const OTHER_AUD = 'https://relay.example';
 const header = (value) => base64urlEncode(utf8Encode(JSON.stringify(value)));
 // Signs the header and payload text as they are, so a case can carry a
 // header or payload sign() would never write.
@@ -178,6 +181,43 @@ export async function handshakeConformanceCases() {
             'nonce_mismatch',
             { nonce: 'check-7f3a' },
         ],
+        // aud binds a handshake to the verifier that asked for it, so one made
+        // for another verifier and relayed is refused.
+        [
+            'made for the verifier that asked',
+            byAgent({ ...base, nonce: NONCE, aud: AUD }),
+            'matches',
+            { nonce: NONCE, aud: AUD },
+        ],
+        [
+            'made for another verifier and relayed',
+            byAgent({ ...base, nonce: NONCE, aud: OTHER_AUD }),
+            'wrong_verifier',
+            { nonce: NONCE, aud: AUD },
+        ],
+        [
+            'no aud when the verifier gave its name',
+            byAgent({ ...base, nonce: NONCE }),
+            'wrong_verifier',
+            { nonce: NONCE, aud: AUD },
+        ],
+        [
+            'an aud the verifier did not ask for',
+            byAgent({ ...base, nonce: NONCE, aud: AUD }),
+            'matches',
+            { nonce: NONCE },
+        ],
+        [
+            'a wrong nonce is named before a wrong verifier',
+            byAgent({ ...base, nonce: 'check-0000', aud: OTHER_AUD }),
+            'nonce_mismatch',
+            { nonce: NONCE, aud: AUD },
+        ],
+        [
+            'a 65 character aud',
+            byAgent({ ...base, aud: 'a'.repeat(65) }),
+            'malformed',
+        ],
         // Verified with the SEAL's sub key before the header is read, so a
         // handshake another agent signed for itself fails the signature.
         [
@@ -268,6 +308,7 @@ export async function handshakeConformanceCases() {
             jws: await jws,
             expected,
             ...(opts?.nonce === undefined ? {} : { nonce: opts.nonce }),
+            ...(opts?.aud === undefined ? {} : { aud: opts.aud }),
             ...(opts?.nowSeconds === undefined
                 ? {}
                 : { nowSeconds: opts.nowSeconds }),