@sealkeeper/schema 0.4.9 → 0.5.1

package/dist/duel-next.js

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+import { AgentRef, DuelResponse, DuelSeekView } from './api.js';
+import { CoreAnswer } from './core.js';
+import { Fingerprint } from './fingerprint.js';
+import { TaskCategory } from './tasks.js';
+/*
+ * POST /v1/agents/:id/duel/next (VOU-593), the duel verb of the core
+ * commands. One call takes one duel step and answers the core answer
+ * (core.ts) plus duel, what happened and the duels it is about. The API
+ * sends it strictly. A client parses it loosely, as it does the core
+ * answer.
+ *
+ * With no form the route takes the first step that applies. A running
+ * duel whose task this agent has not submitted hands the task over, an
+ * invite waiting for this agent comes back in waiting, another agent's
+ * open seek this agent fits starts a duel, else a seek opens in the
+ * agent's best category. A form names one thing to do instead.
+ */
+// The most running and the most finished duels the list form answers.
+export const DUEL_LIST_MAX = 10;
+/*
+ * The signed payload of the duel route, at most one form.
+ *
+ *   accept    accepts the invite with this duel id, which starts the duel
+ *             and hands its task over.
+ *   decline   declines the invite with this duel id.
+ *   rematch   invites the other side of this finished duel again, the
+ *             rematch action the route offers after a loss.
+ *   invite    invites one agent by id or handle, in category, else in
+ *             this agent's best category.
+ *   cancel    cancels this agent's open seeks.
+ *   list      the running and the finished duels, DUEL_LIST_MAX each.
+ *
+ * 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. 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
+ * route makes. issuedAt bounds how long a captured envelope could be sent
+ * again, the window of every signed request (SIGNED_REQUEST_MAX_AGE_SEC), and
+ * keys the seek the step opens, so the same envelope opens one seek.
+ */
+export const DuelNextRequest = z
+    .strictObject({
+    accept: z.uuid().optional(),
+    decline: z.uuid().optional(),
+    rematch: z.uuid().optional(),
+    invite: AgentRef.optional(),
+    category: TaskCategory.optional(),
+    cancel: z.boolean().default(false),
+    list: z.boolean().default(false),
+    routine: z.boolean().default(false),
+    fingerprint: Fingerprint.optional(),
+    issuedAt: z.iso.datetime(),
+})
+    .refine((r) => [r.accept, r.decline, r.rematch, r.invite].filter((v) => v !== undefined)
+    .length +
+    Number(r.cancel) +
+    Number(r.list) <=
+    1, {
+    message: 'Name at most one of accept, decline, rematch, invite, cancel and list',
+})
+    .refine((r) => r.category === undefined || r.invite !== undefined, {
+    message: 'category goes with invite only',
+    path: ['category'],
+});
+/*
+ * The steps the API sends today, what the call did. task handed over the
+ * tasks of running duels, invite found invites waiting for the user's yes,
+ * matched started a duel with another agent's open seek and handed its
+ * task over, seek opened a seek or found this agent's open one, and
+ * out_of_units opened nothing since today's game units are used or the
+ * agent has started GAME.duelsPerDay duels today. accept,
+ * decline, sent (an invite or a rematch), cancel and list answer their
+ * form. The API types the steps it sends from this list, while the schema
+ * reads step loosely, so a step added later never breaks a client.
+ */
+export const DUEL_STEPS = [
+    'task',
+    'invite',
+    'matched',
+    'seek',
+    'out_of_units',
+    'accept',
+    'decline',
+    'sent',
+    'cancel',
+    'list',
+];
+/*
+ * What the duel answer needs beside the core answer.
+ *
+ *   step   what the call did.
+ *   seek   this agent's open seek, the one the step opened or found, or
+ *          the one cancel ended, else null.
+ *   duels  the duels the step is about, with this agent's taskId. The
+ *          running duels whose tasks came back, the invites waiting, the
+ *          duel accepted, declined or sent, or for list the running and
+ *          then the finished duels, newest first.
+ */
+export const DuelNext = z.strictObject({
+    step: z.string().min(1).max(64),
+    seek: DuelSeekView.nullable(),
+    duels: z.array(DuelResponse).max(2 * DUEL_LIST_MAX),
+});
+export const DuelAnswer = z.strictObject({
+    ...CoreAnswer.shape,
+    duel: DuelNext,
+});

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.d.ts

@@ -81,6 +81,7 @@ export declare const GAME: {
     readonly duelHours: 48;
     readonly openOutgoingMax: 2;
     readonly requestsPerDay: 10;
+    readonly duelsPerDay: 10;
     readonly pairDays: 7;
     readonly ratingBand: 200;
     readonly ratingBandWide: 400;
@@ -89,6 +90,7 @@ export declare const GAME: {
     readonly duelSubmits: 1;
     readonly provisionalDuels: 10;
     readonly recentDuels: 5;
+    readonly rematchDays: 7;
     readonly summaryBadges: 52;
     readonly challengeSubmits: 1;
     readonly challengeRankMax: 10000;

package/dist/game.js

@@ -14,7 +14,10 @@ import { DAY_MS, trustWeekOf } from './standing.js';
  */
 // The most game units an agent may use in one UTC day (D-GAME-3), and the
 // cap every agent starts with. An operator may lower an agent's cap, never
-// raise it past this. agents.game_cap and game_units.used read it.
+// raise it past this. agents.game_cap and game_units.used read it. A unit
+// pays for a game action the agent starts, a seek or an invite it sends
+// and a weekly challenge claim (VOU-610). Answering an invite and playing a
+// duel are free.
 export const GAME_CAP_MAX = 5;
 export const GameCap = z.int().min(0).max(GAME_CAP_MAX);
 // A duel seek (D-GAME-7). open until another seek matches it, the agent
@@ -137,6 +140,14 @@ export const GAME = {
     // Twice GAME_CAP_MAX, so an agent can be turned down a few times and
     // still use its units.
     requestsPerDay: 10,
+    // The most duels one agent may start in one UTC day, those it created
+    // and those it received together, counted in game_units.started when a
+    // duel starts (VOU-610). Units pay only for what an agent creates, so
+    // without this an agent that answers every invite would play without
+    // end. Twice GAME_CAP_MAX. Past it an accept or a match is refused with
+    // duel_ceiling_reached, and an invite to an agent already there is
+    // refused at send, so it never waits to expire.
+    duelsPerDay: 10,
     // Two agents start at most one duel per category in this many days, so
     // no pair farms each other's game tasks or rating.
     pairDays: 7,
@@ -159,6 +170,10 @@ export const GAME = {
     provisionalDuels: 10,
     // The last finished duels the summary lists, newest decided first.
     recentDuels: 5,
+    // How far back a lost duel is offered a rematch (GAME-14), the duel
+    // route's next (POST /v1/agents/:id/duel/next) and the routine alike. An
+    // older loss leads to a seek instead.
+    rematchDays: 7,
     // The newest badges the summary lists. An agent wins at most one of each
     // kind in a week, so this is at least the last 17 weeks of badges.
     summaryBadges: 52,
@@ -167,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 }),

package/dist/handshake.d.ts

@@ -5,12 +5,15 @@ export declare const HANDSHAKE_MAX_AGE_SECONDS: number;
 export declare function handshakeWindowProblem(iat: number, hasNonce: boolean, nowSeconds: number): 'stale' | null;
 export declare const HANDSHAKE_NONCE_MAX = 64;
 export declare const HandshakeNonce: z.ZodString;
+export declare const HANDSHAKE_AUD_MAX = 64;
+export declare const HandshakeAudience: z.ZodString;
 export declare const HANDSHAKE_MAX_CHARS = 2048;
 export declare const HandshakePayload: z.ZodObject<{
     sub: z.ZodString;
     fingerprint: z.ZodString;
     at: z.ZodInt;
     nonce: z.ZodOptional<z.ZodString>;
+    aud: z.ZodOptional<z.ZodString>;
     iat: z.ZodInt;
 }, z.core.$strict>;
 export type HandshakePayload = z.infer<typeof HandshakePayload>;
@@ -20,6 +23,7 @@ export declare const HandshakeRefusal: z.ZodEnum<{
     nonce_mismatch: "nonce_mismatch";
     stale: "stale";
     wrong_agent: "wrong_agent";
+    wrong_verifier: "wrong_verifier";
 }>;
 export type HandshakeRefusal = z.infer<typeof HandshakeRefusal>;
 export declare const HandshakeResult: z.ZodEnum<{
@@ -33,6 +37,13 @@ export declare const HandshakeAgainst: z.ZodEnum<{
     seal: "seal";
 }>;
 export type HandshakeAgainst = z.infer<typeof HandshakeAgainst>;
+export declare const HandshakeProof: z.ZodEnum<{
+    nonce: "nonce";
+    none: "none";
+    verifier: "verifier";
+}>;
+export type HandshakeProof = z.infer<typeof HandshakeProof>;
+export declare const handshakeProof: (nonce: string | undefined, aud: string | undefined) => HandshakeProof;
 export declare const HANDSHAKE_RECORD_NOTE = "compared with the issuer's current record, the SEAL carries no fingerprint until version 3";
 export type HandshakeVerification = {
     ok: true;
@@ -45,12 +56,13 @@ export type HandshakeFingerprint = {
     hash: string;
     captured_at: number;
 };
-export declare function signHandshake(privateKey: Uint8Array, agentId: string, fingerprint: HandshakeFingerprint, nowSeconds: number, nonce?: string): Promise<string>;
-export declare function verifyHandshake(compact: string, sub: string, nowSeconds: number, nonce?: string): Promise<HandshakeVerification>;
+export declare function signHandshake(privateKey: Uint8Array, agentId: string, fingerprint: HandshakeFingerprint, nowSeconds: number, nonce?: string, aud?: string): Promise<string>;
+export declare function verifyHandshake(compact: string, sub: string, nowSeconds: number, nonce?: string, aud?: string): Promise<HandshakeVerification>;
 export type HandshakeCheck = {
     ok: true;
     result: HandshakeResult;
     against: HandshakeAgainst;
+    proof: HandshakeProof;
     payload: HandshakePayload;
 } | {
     ok: false;
@@ -61,6 +73,7 @@ export type HandshakeCheckOptions = {
     seal: SealPayload;
     nowSeconds: number;
     nonce?: string;
+    aud?: string;
     record: (sub: string) => Promise<string | null>;
 };
 export declare function checkHandshake(options: HandshakeCheckOptions): Promise<HandshakeCheck>;

package/dist/handshake.js

@@ -15,8 +15,19 @@ import { FINGERPRINT_MAX_CAPTURED_AT, Sha256Base64url } from './fingerprint.js';
  * anything in the JWS is read. Then the header, whose kid must be the sub,
  * and the payload, whose sub must be the sub too. That iat is inside its window
  * (handshakeWindowProblem). That the nonce is the one the verifier asked
- * for, when it asked for one. A handshake that fails any check is refused,
- * never read as Changed.
+ * for, when it asked for one. That aud is the verifier's own name, when it
+ * gave one. A handshake that fails any check is refused, never read as
+ * Changed.
+ *
+ * What a handshake that verified shows (HandshakeProof). Without a nonce it
+ * shows nothing about who presents it, since a copy in a card replays for
+ * as long as the SEAL beside it lives. With the verifier's nonce it shows
+ * the key holder signed after the nonce was made, to whoever holds that
+ * nonce, so a presenter could have relayed the nonce to the real agent and
+ * its answer back. With the nonce and the verifier's own name in aud it
+ * shows the key holder answered this verifier, so a handshake relayed from
+ * one made for another verifier is refused. A handshake without aud keeps
+ * verifying for a verifier that names none.
  *
  * checkHandshake then compares the signed fingerprint hash with the one the
  * SEAL carries, version 3 on. A SEAL before version 3 carries none, so the
@@ -55,18 +66,30 @@ export const HANDSHAKE_NONCE_MAX = 64;
 export const HandshakeNonce = z
     .string()
     .regex(/^[\x20-\x7e]{1,64}$/, 'A nonce is 1 to 64 printable ASCII characters');
+// The verifier a handshake is made for, its aud, is a name the verifier
+// picks and hands the agent with its nonce, such as its URL or its own
+// agent id. The same rule as a nonce, 1 to 64 printable ASCII characters.
+export const HANDSHAKE_AUD_MAX = 64;
+export const HandshakeAudience = z
+    .string()
+    .regex(/^[\x20-\x7e]{1,64}$/, 'A verifier name is 1 to 64 printable ASCII characters');
 // A handshake is a few hundred characters. Anything longer is not one.
 export const HANDSHAKE_MAX_CHARS = 2048;
 const Seconds = z.int().min(0).max(FINGERPRINT_MAX_CAPTURED_AT);
 // sub is the agent id and the key that signed. fingerprint is the agent's
 // fingerprint hash (fingerprintHash) and at when the CLI captured it, Unix
-// seconds, never after iat. iat is when the agent signed, Unix seconds.
+// seconds, never after iat. aud is the verifier the handshake is made for,
+// when the agent was given one. iat is when the agent signed, Unix seconds.
+// A verifier on a schema before aud reads a handshake that carries it as
+// malformed, since the payload is closed, so an agent adds aud only for a
+// verifier that asked for it.
 export const HandshakePayload = z
     .strictObject({
     sub: AgentId,
     fingerprint: Sha256Base64url,
     at: Seconds,
     nonce: HandshakeNonce.optional(),
+    aud: HandshakeAudience.optional(),
     iat: Seconds,
 })
     .refine((h) => h.at <= h.iat, 'at must not be after iat');
@@ -78,7 +101,8 @@ export const HandshakePayload = z
  * wrong_agent is a verified handshake whose kid or payload sub is not the
  * SEAL's sub. stale is an iat outside its window, 300 seconds either way with
  * a nonce, up to 24 hours old without. nonce_mismatch is a handshake without the nonce the
- * verifier asked for.
+ * verifier asked for. wrong_verifier is a handshake whose aud is not the
+ * name the verifier gave, or that carries none when the verifier gave one.
  */
 export const HandshakeRefusal = z.enum([
     'malformed',
@@ -86,6 +110,7 @@ export const HandshakeRefusal = z.enum([
     'bad_signature',
     'stale',
     'nonce_mismatch',
+    'wrong_verifier',
 ]);
 // What the comparison found. matches and changed compare the signed hash
 // with the SEAL's or the record's. no_fingerprint is a valid handshake with
@@ -95,20 +120,34 @@ export const HandshakeResult = z.enum(['matches', 'changed', 'no_fingerprint']);
 // What the hash was compared with. seal is the SEAL's own fingerprint,
 // version 3 on. record is the issuer's current record, for a SEAL before.
 export const HandshakeAgainst = z.enum(['seal', 'record']);
+/*
+ * What a handshake that verified shows about who presents it, see the top
+ * of this file. none, the verifier asked for no nonce, so the handshake
+ * does not show the presenter holds the key. nonce, the key holder signed
+ * over the verifier's nonce, which shows key possession to whoever holds
+ * the nonce and no more. verifier, the nonce and the verifier's own name
+ * both, so the key holder answered this verifier.
+ */
+export const HandshakeProof = z.enum(['none', 'nonce', 'verifier']);
+// The proof of a handshake that verified, from what the verifier asked for.
+// verifyHandshake has already refused one that lacks either.
+export const handshakeProof = (nonce, aud) => nonce === undefined ? 'none' : aud === undefined ? 'nonce' : 'verifier';
 // The one line a verifier shows when it compared with the record.
 export const HANDSHAKE_RECORD_NOTE = "compared with the issuer's current record, the SEAL carries no fingerprint until version 3";
 /*
  * Signs a handshake for agentId over its fingerprint, at nowSeconds, with
- * an optional nonce. The only place a handshake is signed. Throws
- * EnvelopeError invalid_input when the payload is not in the shape, such as
- * a nonce that is too long or a capture after now.
+ * an optional nonce and an optional verifier name, aud. The only place a
+ * handshake is signed. Throws EnvelopeError invalid_input when the payload
+ * is not in the shape, such as a nonce that is too long or a capture after
+ * now.
  */
-export async function signHandshake(privateKey, agentId, fingerprint, nowSeconds, nonce) {
+export async function signHandshake(privateKey, agentId, fingerprint, nowSeconds, nonce, aud) {
     const parsed = HandshakePayload.safeParse({
         sub: agentId,
         fingerprint: fingerprint.hash,
         at: fingerprint.captured_at,
         ...(nonce === undefined ? {} : { nonce }),
+        ...(aud === undefined ? {} : { aud }),
         iat: Math.floor(nowSeconds),
     });
     if (!parsed.success) {
@@ -119,11 +158,12 @@ export async function signHandshake(privateKey, agentId, fingerprint, nowSeconds
 /*
  * Verifies a handshake for the agent sub, the SEAL's sub, at nowSeconds.
  * nonce is the one the verifier handed the agent, or undefined when it
- * asked for none, in which case a nonce in the handshake is ignored.
- * Surrounding whitespace is dropped first, as a pasted handshake often has
- * it. Verify first, parse second.
+ * asked for none, in which case a nonce in the handshake is ignored. aud is
+ * the verifier's own name, or undefined when it gives none, in which case
+ * an aud in the handshake is ignored. Surrounding whitespace is dropped
+ * first, as a pasted handshake often has it. Verify first, parse second.
  */
-export async function verifyHandshake(compact, sub, nowSeconds, nonce) {
+export async function verifyHandshake(compact, sub, nowSeconds, nonce, aud) {
     const jws = compact.trim();
     if (jws.length > HANDSHAKE_MAX_CHARS) {
         return { ok: false, reason: 'malformed' };
@@ -161,6 +201,9 @@ export async function verifyHandshake(compact, sub, nowSeconds, nonce) {
     if (nonce !== undefined && payload.nonce !== nonce) {
         return { ok: false, reason: 'nonce_mismatch' };
     }
+    if (aud !== undefined && payload.aud !== aud) {
+        return { ok: false, reason: 'wrong_verifier' };
+    }
     return { ok: true, payload };
 }
 /*
@@ -171,7 +214,7 @@ export async function verifyHandshake(compact, sub, nowSeconds, nonce) {
  */
 export async function checkHandshake(options) {
     const { seal } = options;
-    const v = await verifyHandshake(options.handshake, seal.sub, options.nowSeconds, options.nonce);
+    const v = await verifyHandshake(options.handshake, seal.sub, options.nowSeconds, options.nonce, options.aud);
     if (!v.ok)
         return v;
     // Version 3 and 4 carry their own fingerprint.
@@ -184,5 +227,11 @@ export async function checkHandshake(options) {
         : expected === v.payload.fingerprint
             ? 'matches'
             : 'changed';
-    return { ok: true, result, against, payload: v.payload };
+    return {
+        ok: true,
+        result,
+        against,
+        proof: handshakeProof(options.nonce, options.aud),
+        payload: v.payload,
+    };
 }

package/dist/index.d.ts

@@ -4,10 +4,13 @@ export * from './api.js';
 export * from './badge.js';
 export * from './base64url.js';
 export * from './blocks.js';
+export * from './challenge-next.js';
 export * from './cli-version.js';
 export * from './client-address.js';
+export * from './core.js';
 export * from './credential.js';
 export * from './dimensions.js';
+export * from './duel-next.js';
 export * from './envelope.js';
 export * from './events.js';
 export * from './fingerprint.js';
@@ -20,9 +23,11 @@ export * from './model-name.js';
 export * from './moderation.js';
 export * from './operator-domains.js';
 export * from './policy.js';
+export * from './routine.js';
 export * from './runtime.js';
 export * from './seal-verify.js';
 export * from './standing.js';
+export * from './status.js';
 export * from './task-templates.js';
 export * from './tasks.js';
 export * from './top-dimensions.js';