@sealkeeper/schema 0.4.7 → 0.4.9

package/dist/goal.js

@@ -24,12 +24,36 @@ export const GOAL_ACTION_CODES = [
     // confirmed task counts for its claimant, so this counts toward the
     // agent's own level. count is how many.
     'confirm_outcomes',
+    // Counterparty tasks this agent posted wait for its outcome report. It
+    // confirms the task for the claimant, and since POST-3 the confirmed task
+    // counts in this agent's posted tasks too, so it comes beside
+    // confirm_outcomes. count is how many.
+    'report_as_poster',
     // Tasks addressed to this agent are waiting to be claimed. count is how
     // many.
     'addressed_waiting',
+    // Trust Score still needed (VOU-503). Every verified task earns it, seed
+    // tasks included, a harder task more. count is the Trust Score missing,
+    // rounded up.
+    'earn_trust',
+    // Categories still needed with at least TRUST_SCORE.diversityMinTasks
+    // verified tasks each, which silver reads beside its Trust Score
+    // (VOU-503). count is how many.
+    'trust_categories',
     // Verified tasks still needed. Seed tasks count toward it at every level
     // (VOU-172). count is how many.
     'claim_seed_tasks',
+    // Posted tasks that other operators' agents complete still needed, for
+    // the posted tasks or posted operators of the next level (POST-3). count
+    // is the posts at least still needed. It comes before claim_seed_tasks
+    // when posting is further behind than taking (POST-6), else where the
+    // posted rows come in the table.
+    'post_task',
+    // Posted confirmed tasks still needed (POST-6). Only a counterparty task
+    // the agent posted by hand, completed by another operator's agent and
+    // confirmed by both outcome reports, counts, so a template or adopted
+    // post never closes it. count is how many.
+    'post_confirmed_task',
     // Verified tasks from other operators' agents still needed. No threshold
     // sends it since VOU-172, where seed tasks count at every level. Kept so
     // a client that knows it keeps working.
@@ -40,7 +64,10 @@ export const GOAL_ACTION_CODES = [
     'need_operators',
     // Active days (or span of days) still needed.
     'history_days',
-    // Reliability or safety under the threshold. count is null.
+    // Reliability or safety under the threshold. count is null. No threshold
+    // sends safety_below while safety is not measured (SAFETY_MEASURED,
+    // VOU-437), since no level reads a safety score then. Kept so a client
+    // that knows it keeps working, and it comes back with the switch.
     'reliability_below',
     'safety_below',
     // An incident in the window. count is the incidents counted.
@@ -50,7 +77,8 @@ export const GOAL_ACTION_CODES = [
     'clean_days',
     // The version's share of the agent's events is under the threshold.
     'provenance_below',
-    // No model declared on the card or in a usage event.
+    // No model declared, in the model part of the agent's current fingerprint
+    // or in a usage event (VOU-386).
     'declare_model',
     // Operator identity not verified beyond a GitHub login. The operator
     // verifies a domain on the account page (VOU-185).
@@ -65,10 +93,6 @@ export const GOAL_ACTION_CODES = [
     // taken (OPERATOR_SILVER_CAP), so the agent is held at bronze. count is
     // the whole days until the next slot frees and until the moment it does.
     'operator_silver_cap',
-    // Counterparty tasks this agent posted wait for its outcome report. It
-    // helps the claimant, the other agent, and adds nothing to this agent's
-    // level, so it comes after every step that does. count is how many.
-    'report_as_poster',
 ];
 export const GoalActionCode = z.enum(GOAL_ACTION_CODES);
 // One rule of the next level. current is what the version has (0 for a
@@ -77,7 +101,9 @@ export const GoalActionCode = z.enum(GOAL_ACTION_CODES);
 // or above, or at required or below for incident counts. Task thresholds
 // are in counted units (VOU-139), after the daily ceiling and diminishing
 // returns, and raw is every verified task beside it. raw is null for the
-// other rules.
+// other rules. trust_score is the version's Trust Score and
+// trust_categories its categories with at least
+// TRUST_SCORE.diversityMinTasks verified tasks (VOU-503).
 export const GoalThreshold = z.strictObject({
     name: z.string().min(1).max(64),
     current: z.number(),
@@ -156,6 +182,17 @@ export const GoalPending = z.strictObject({
     outcomes: Count,
     posterOutcomes: Count,
 });
+// One side of the agent's work toward the next level (POST-6), current
+// against required. taken is the verified_tasks threshold, in counted
+// units, the tasks the agent took. trustScore is the trust_score
+// threshold, the Trust Score the tasks the agent took earned, which every
+// level reads beside taken since VOU-503. posted is the posted_tasks
+// threshold, in counted units, the tasks it posted that other operators'
+// agents completed.
+export const GoalSide = z.strictObject({
+    current: z.number(),
+    required: z.number(),
+});
 export const GoalResponse = z.strictObject({
     agentId: AgentId,
     version: StoredVersion,
@@ -164,6 +201,12 @@ export const GoalResponse = z.strictObject({
     ladder: z.array(GoalLadderStep),
     thresholds: z.array(GoalThreshold),
     steps: z.array(GoalStep),
+    // Taken and posted toward nextLevel, null when nextLevel is null.
+    taken: GoalSide.nullable(),
+    posted: GoalSide.nullable(),
+    // Trust Score toward nextLevel, null when nextLevel is null (VOU-503).
+    // Optional, so an answer from an API before it still parses.
+    trustScore: GoalSide.nullable().optional(),
     actions: z.array(GoalAction),
     pending: GoalPending,
     today: GoalToday,

package/dist/handshake-conformance.d.ts

@@ -0,0 +1,18 @@
+import { type WellKnown } from './credential.js';
+import { type HandshakeRefusal, type HandshakeResult } from './handshake.js';
+export type HandshakeConformanceCase = {
+    name: string;
+    jws: string;
+    expected: Exclude<HandshakeResult, 'no_fingerprint'> | HandshakeRefusal;
+    nonce?: string;
+    nowSeconds?: number;
+};
+export type HandshakeConformance = {
+    nowSeconds: number;
+    sub: string;
+    fingerprint: string;
+    seal: string;
+    wellKnown: WellKnown;
+    cases: HandshakeConformanceCase[];
+};
+export declare function handshakeConformanceCases(): Promise<HandshakeConformance>;

package/dist/handshake-conformance.js

@@ -0,0 +1,276 @@
+import { signAsync } from '@noble/ed25519';
+import { generateKeypair } from './agent-id.js';
+import { base64urlEncode, utf8Encode } from './base64url.js';
+import { CREDENTIAL_ISSUER } from './credential.js';
+import { sign } from './envelope.js';
+import { HANDSHAKE_MAX_AGE_SECONDS, HANDSHAKE_SKEW_SECONDS, } from './handshake.js';
+const KID = 'sealkeeper-handshake-conformance-1';
+// 1 October 2026, the clock of the SEAL conformance cases.
+const NOW = 1_790_812_800;
+const HOUR = 3600;
+// Two SHA-256 digests in base64url, the one the SEAL carries and another.
+const FINGERPRINT = 'unFXnGMKWNOP4f_NnbearJn0prLlxoGia2LaZcqnzy8';
+const OTHER_FINGERPRINT = 'BHAfx6dALmCdt3aXz-g6iAjLLGDurK95DZm15ZjIVZg';
+const NONCE = 'check-7f3a';
+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.
+async function signRaw(headerText, body, privateKey) {
+    const input = `${headerText}.${base64urlEncode(utf8Encode(body))}`;
+    const signature = await signAsync(utf8Encode(input), privateKey);
+    return `${input}.${base64urlEncode(signature)}`;
+}
+// One character in the middle of the signature, changed.
+function tamper(jws) {
+    const [h, p, s = ''] = jws.split('.');
+    const i = Math.floor(s.length / 2);
+    return `${h}.${p}.${s.slice(0, i)}${s[i] === 'A' ? 'B' : 'A'}${s.slice(i + 1)}`;
+}
+export async function handshakeConformanceCases() {
+    const issuer = await generateKeypair();
+    const agent = await generateKeypair();
+    const other = await generateKeypair();
+    const sub = agent.agentId;
+    const seal = await sign({
+        iss: CREDENTIAL_ISSUER,
+        sub,
+        ver: 3,
+        iat: NOW - HOUR,
+        exp: NOW + 23 * HOUR,
+        agent_version: '1.0.0',
+        level: 'bronze',
+        scores: { reliability: 0.9, safety: null },
+        counts: {
+            events: 40,
+            history_days: 4,
+            verified_tasks: 26,
+            seed_tasks: 25,
+            server_checked_tasks: 1,
+            confirmed_tasks: 0,
+            distinct_operators: 1,
+            safety_incidents_90d: 0,
+            posted_tasks: 0,
+            posted_distinct_operators: 0,
+            posted_confirmed_tasks: 0,
+        },
+        counted: {
+            verified_tasks: 17,
+            seed_tasks: 17,
+            server_checked_tasks: 0,
+            confirmed_tasks: 0,
+            posted_tasks: 0,
+            posted_confirmed_tasks: 0,
+        },
+        fingerprint: { hash: FINGERPRINT, at: NOW - 2 * HOUR },
+        state: 'matches',
+        operator: { verified: false },
+        identity: [],
+        last_active: NOW - HOUR,
+        dormant_days: 0,
+    }, issuer.privateKey, KID);
+    // The payload of a good handshake, captured ten minutes ago and signed
+    // now.
+    const base = { sub, fingerprint: FINGERPRINT, at: NOW - 600, iat: NOW };
+    const byAgent = (payload) => sign(payload, agent.privateKey, sub);
+    const agentHeader = header({ alg: 'EdDSA', kid: sub });
+    const good = await byAgent(base);
+    // A good handshake signed offset seconds from NOW, captured ten minutes
+    // before that, with a nonce when given. The clock stays at NOW, so the
+    // SEAL stays valid.
+    const signedAt = (offset, nonce) => byAgent({
+        ...base,
+        at: NOW + offset - 600,
+        iat: NOW + offset,
+        ...(nonce === undefined ? {} : { nonce }),
+    });
+    const cases = [
+        ['a handshake over the SEAL fingerprint', good, 'matches'],
+        [
+            'a handshake over another fingerprint',
+            byAgent({ ...base, fingerprint: OTHER_FINGERPRINT }),
+            'changed',
+        ],
+        [
+            'the nonce the verifier asked for',
+            byAgent({ ...base, nonce: 'check-7f3a' }),
+            'matches',
+            { nonce: 'check-7f3a' },
+        ],
+        [
+            'a nonce the verifier did not ask for',
+            byAgent({ ...base, nonce: 'check-7f3a' }),
+            'matches',
+        ],
+        [
+            'a 64 character nonce with spaces',
+            byAgent({ ...base, nonce: `a b${'c'.repeat(61)}` }),
+            'matches',
+            { nonce: `a b${'c'.repeat(61)}` },
+        ],
+        // Without a nonce, iat may be up to the SEAL's 24 hour life old.
+        ['no nonce, signed 6 hours ago', signedAt(-6 * HOUR), 'matches'],
+        [
+            'no nonce, signed exactly 24 hours ago',
+            signedAt(-HANDSHAKE_MAX_AGE_SECONDS),
+            'matches',
+        ],
+        [
+            'no nonce, signed 24 hours and 1 second ago',
+            signedAt(-HANDSHAKE_MAX_AGE_SECONDS - 1),
+            'stale',
+        ],
+        ['no nonce, signed 25 hours ago', signedAt(-25 * HOUR), 'stale'],
+        [
+            'no nonce, signed exactly the skew ahead',
+            signedAt(HANDSHAKE_SKEW_SECONDS),
+            'matches',
+        ],
+        [
+            'no nonce, signed 1 second past the skew ahead',
+            signedAt(HANDSHAKE_SKEW_SECONDS + 1),
+            'stale',
+        ],
+        // With a nonce, a live challenge, iat is within the skew either way.
+        [
+            'a nonce, signed exactly the skew ago',
+            signedAt(-HANDSHAKE_SKEW_SECONDS, NONCE),
+            'matches',
+            { nonce: NONCE },
+        ],
+        [
+            'a nonce, signed 1 second past the skew ago',
+            signedAt(-HANDSHAKE_SKEW_SECONDS - 1, NONCE),
+            'stale',
+            { nonce: NONCE },
+        ],
+        [
+            'a nonce, signed 6 minutes ago',
+            signedAt(-360, NONCE),
+            'stale',
+            { nonce: NONCE },
+        ],
+        [
+            'a nonce, signed exactly the skew ahead',
+            signedAt(HANDSHAKE_SKEW_SECONDS, NONCE),
+            'matches',
+            { nonce: NONCE },
+        ],
+        [
+            'a nonce, signed 1 second past the skew ahead',
+            signedAt(HANDSHAKE_SKEW_SECONDS + 1, NONCE),
+            'stale',
+            { nonce: NONCE },
+        ],
+        [
+            'a nonce the verifier did not ask for, signed 6 minutes ago',
+            signedAt(-360, NONCE),
+            'stale',
+        ],
+        [
+            'a wrong nonce',
+            byAgent({ ...base, nonce: 'check-0000' }),
+            'nonce_mismatch',
+            { nonce: 'check-7f3a' },
+        ],
+        [
+            'no nonce when the verifier asked for one',
+            good,
+            'nonce_mismatch',
+            { nonce: 'check-7f3a' },
+        ],
+        // Verified with the SEAL's sub key before the header is read, so a
+        // handshake another agent signed for itself fails the signature.
+        [
+            'another agent signing for itself',
+            sign({ ...base, sub: other.agentId }, other.privateKey, other.agentId),
+            'bad_signature',
+        ],
+        [
+            'the agent signing under another kid',
+            sign(base, agent.privateKey, other.agentId),
+            'wrong_agent',
+        ],
+        [
+            'the agent signing for another sub',
+            byAgent({ ...base, sub: other.agentId }),
+            'wrong_agent',
+        ],
+        [
+            'another key under the agent kid',
+            sign(base, other.privateKey, sub),
+            'bad_signature',
+        ],
+        ['an altered signature', tamper(good), 'bad_signature'],
+        [
+            'an altered payload',
+            `${agentHeader}.${base64urlEncode(utf8Encode(JSON.stringify({ ...base, fingerprint: OTHER_FINGERPRINT })))}.${good.split('.')[2]}`,
+            'bad_signature',
+        ],
+        ['an extra field', byAgent({ ...base, level: 'gold' }), 'malformed'],
+        [
+            'no fingerprint',
+            byAgent({ ...base, fingerprint: undefined }),
+            'malformed',
+        ],
+        [
+            'a fingerprint that is not a SHA-256',
+            byAgent({ ...base, fingerprint: 'abc' }),
+            'malformed',
+        ],
+        ['at after iat', byAgent({ ...base, at: NOW + 1 }), 'malformed'],
+        [
+            'a 65 character nonce',
+            byAgent({ ...base, nonce: 'n'.repeat(65) }),
+            'malformed',
+        ],
+        ['an empty nonce', byAgent({ ...base, nonce: '' }), 'malformed'],
+        [
+            'a nonce with a control character',
+            byAgent({ ...base, nonce: 'line\nbreak' }),
+            'malformed',
+        ],
+        ['iat as a string', byAgent({ ...base, iat: String(NOW) }), 'malformed'],
+        [
+            'a payload that is not JSON',
+            signRaw(agentHeader, 'not json', agent.privateKey),
+            'malformed',
+        ],
+        [
+            'a header with typ, signed by another key',
+            signRaw(header({ alg: 'EdDSA', kid: sub, typ: 'JWT' }), JSON.stringify(base), other.privateKey),
+            'bad_signature',
+        ],
+        [
+            'a header with typ, signed by the agent',
+            signRaw(header({ alg: 'EdDSA', kid: sub, typ: 'JWT' }), JSON.stringify(base), agent.privateKey),
+            'malformed',
+        ],
+        ['not a JWS', 'not a handshake', 'malformed'],
+    ];
+    return {
+        nowSeconds: NOW,
+        sub,
+        fingerprint: FINGERPRINT,
+        seal,
+        wellKnown: {
+            keys: [
+                {
+                    kid: KID,
+                    kty: 'OKP',
+                    crv: 'Ed25519',
+                    alg: 'EdDSA',
+                    x: base64urlEncode(issuer.publicKey),
+                },
+            ],
+        },
+        cases: await Promise.all(cases.map(async ([name, jws, expected, opts]) => ({
+            name,
+            jws: await jws,
+            expected,
+            ...(opts?.nonce === undefined ? {} : { nonce: opts.nonce }),
+            ...(opts?.nowSeconds === undefined
+                ? {}
+                : { nowSeconds: opts.nowSeconds }),
+        }))),
+    };
+}

package/dist/handshake.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import type { SealPayload } from './credential.js';
+export declare const HANDSHAKE_SKEW_SECONDS = 300;
+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_MAX_CHARS = 2048;
+export declare const HandshakePayload: z.ZodObject<{
+    sub: z.ZodString;
+    fingerprint: z.ZodString;
+    at: z.ZodInt;
+    nonce: z.ZodOptional<z.ZodString>;
+    iat: z.ZodInt;
+}, z.core.$strict>;
+export type HandshakePayload = z.infer<typeof HandshakePayload>;
+export declare const HandshakeRefusal: z.ZodEnum<{
+    bad_signature: "bad_signature";
+    malformed: "malformed";
+    nonce_mismatch: "nonce_mismatch";
+    stale: "stale";
+    wrong_agent: "wrong_agent";
+}>;
+export type HandshakeRefusal = z.infer<typeof HandshakeRefusal>;
+export declare const HandshakeResult: z.ZodEnum<{
+    changed: "changed";
+    matches: "matches";
+    no_fingerprint: "no_fingerprint";
+}>;
+export type HandshakeResult = z.infer<typeof HandshakeResult>;
+export declare const HandshakeAgainst: z.ZodEnum<{
+    record: "record";
+    seal: "seal";
+}>;
+export type HandshakeAgainst = z.infer<typeof HandshakeAgainst>;
+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;
+    payload: HandshakePayload;
+} | {
+    ok: false;
+    reason: HandshakeRefusal;
+};
+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 type HandshakeCheck = {
+    ok: true;
+    result: HandshakeResult;
+    against: HandshakeAgainst;
+    payload: HandshakePayload;
+} | {
+    ok: false;
+    reason: HandshakeRefusal;
+};
+export type HandshakeCheckOptions = {
+    handshake: string;
+    seal: SealPayload;
+    nowSeconds: number;
+    nonce?: string;
+    record: (sub: string) => Promise<string | null>;
+};
+export declare function checkHandshake(options: HandshakeCheckOptions): Promise<HandshakeCheck>;

package/dist/handshake.js

@@ -0,0 +1,188 @@
+import { z } from 'zod';
+import { AgentId } from './agent-id.js';
+import { base64urlDecode } from './base64url.js';
+import { EnvelopeError, sign, verify } from './envelope.js';
+import { FINGERPRINT_MAX_CAPTURED_AT, Sha256Base64url } from './fingerprint.js';
+/*
+ * The handshake (VB-6, D-VB-3). A JWS compact the agent signs with its own
+ * key over its current fingerprint hash, so whoever holds a SEAL can ask the
+ * presenter to prove it holds the key the SEAL names and to say what it runs
+ * now. The header is the closed { alg, kid } every JWS here carries, with
+ * kid the agent id. The payload is HandshakePayload, strict.
+ *
+ * A verifier checks it with verifyHandshake, in this order. The signature
+ * over the exact header.payload bytes with the key the SEAL's sub is, before
+ * 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.
+ *
+ * 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
+ * comparison reads the issuer's current record of the agent instead and says
+ * so. There is no nonce exchange with the issuer. A verifier that wants
+ * freshness hands the agent a nonce out of band.
+ *
+ * The window. A handshake that carries a nonce answers a live challenge, so
+ * its iat must be within HANDSHAKE_SKEW_SECONDS of the verifier's clock
+ * either way. A handshake without a nonce can only be replayed for as long
+ * as the SEAL beside it verifies, and a static card carries exactly that,
+ * so its iat may be up to HANDSHAKE_MAX_AGE_SECONDS old, the most a SEAL
+ * lives, and no more than HANDSHAKE_SKEW_SECONDS ahead, so it cannot be
+ * signed ahead to outlive the SEAL.
+ */
+// How far the iat of a handshake with a nonce may be from the verifier's
+// clock, either way, and how far ahead of it any handshake's iat may be, in
+// seconds.
+export const HANDSHAKE_SKEW_SECONDS = 300;
+// How old the iat of a handshake without a nonce may be, in seconds. 24
+// hours, SEAL_MAX_TTL_SECONDS in ./credential.ts, written out here since
+// credential.ts imports from this file. handshake.test.ts checks the two
+// match.
+export const HANDSHAKE_MAX_AGE_SECONDS = 24 * 3600;
+// stale when iat is outside the window for a handshake with or without a
+// nonce, see the window above. null inside it.
+export function handshakeWindowProblem(iat, hasNonce, nowSeconds) {
+    if (iat - nowSeconds > HANDSHAKE_SKEW_SECONDS)
+        return 'stale';
+    const maxAge = hasNonce ? HANDSHAKE_SKEW_SECONDS : HANDSHAKE_MAX_AGE_SECONDS;
+    return nowSeconds - iat > maxAge ? 'stale' : null;
+}
+// A nonce is 1 to 64 printable ASCII characters, spaces allowed, so it
+// prints on one line and cannot carry a control character to a terminal.
+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');
+// 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.
+export const HandshakePayload = z
+    .strictObject({
+    sub: AgentId,
+    fingerprint: Sha256Base64url,
+    at: Seconds,
+    nonce: HandshakeNonce.optional(),
+    iat: Seconds,
+})
+    .refine((h) => h.at <= h.iat, 'at must not be after iat');
+/*
+ * Why a handshake is refused. malformed is not three base64url parts, or a
+ * header or payload that is not in the shape once the signature verified.
+ * bad_signature is a signature the SEAL's sub key does not verify, so a
+ * handshake another agent signed for itself is bad_signature too.
+ * 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.
+ */
+export const HandshakeRefusal = z.enum([
+    'malformed',
+    'wrong_agent',
+    'bad_signature',
+    'stale',
+    'nonce_mismatch',
+]);
+// 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
+// nothing to compare it with, a version 3 or 4 SEAL whose fingerprint is
+// null or an agent the issuer holds no fingerprint for.
+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']);
+// 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.
+ */
+export async function signHandshake(privateKey, agentId, fingerprint, nowSeconds, nonce) {
+    const parsed = HandshakePayload.safeParse({
+        sub: agentId,
+        fingerprint: fingerprint.hash,
+        at: fingerprint.captured_at,
+        ...(nonce === undefined ? {} : { nonce }),
+        iat: Math.floor(nowSeconds),
+    });
+    if (!parsed.success) {
+        throw new EnvelopeError('invalid_input', `Handshake payload is not in the shape: ${parsed.error.issues[0]?.message ?? 'invalid'}`);
+    }
+    return sign(parsed.data, privateKey, agentId);
+}
+/*
+ * 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.
+ */
+export async function verifyHandshake(compact, sub, nowSeconds, nonce) {
+    const jws = compact.trim();
+    if (jws.length > HANDSHAKE_MAX_CHARS) {
+        return { ok: false, reason: 'malformed' };
+    }
+    // The key is the SEAL's sub, never anything the JWS names, so nothing in
+    // it is read before the signature checks out.
+    if (!AgentId.safeParse(sub).success) {
+        return { ok: false, reason: 'wrong_agent' };
+    }
+    let signed;
+    try {
+        const verified = await verify(jws, base64urlDecode(sub));
+        if (verified.header.kid !== sub) {
+            return { ok: false, reason: 'wrong_agent' };
+        }
+        signed = verified.payload;
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: error instanceof EnvelopeError && error.code === 'bad_signature'
+                ? 'bad_signature'
+                : 'malformed',
+        };
+    }
+    const parsed = HandshakePayload.safeParse(signed);
+    if (!parsed.success)
+        return { ok: false, reason: 'malformed' };
+    const payload = parsed.data;
+    if (payload.sub !== sub)
+        return { ok: false, reason: 'wrong_agent' };
+    const stale = handshakeWindowProblem(payload.iat, payload.nonce !== undefined, nowSeconds);
+    if (stale)
+        return { ok: false, reason: stale };
+    if (nonce !== undefined && payload.nonce !== nonce) {
+        return { ok: false, reason: 'nonce_mismatch' };
+    }
+    return { ok: true, payload };
+}
+/*
+ * The handshake beside a verified SEAL, Matches, Changed or a refusal. The
+ * API's POST /v1/seal/verify, `sealkeeper seal verify --handshake` and the
+ * web's verify tool all call this, and the handshake conformance cases hold
+ * each of them to the same answers.
+ */
+export async function checkHandshake(options) {
+    const { seal } = options;
+    const v = await verifyHandshake(options.handshake, seal.sub, options.nowSeconds, options.nonce);
+    if (!v.ok)
+        return v;
+    // Version 3 and 4 carry their own fingerprint.
+    const against = 'fingerprint' in seal ? 'seal' : 'record';
+    const expected = 'fingerprint' in seal
+        ? (seal.fingerprint?.hash ?? null)
+        : await options.record(seal.sub);
+    const result = expected === null
+        ? 'no_fingerprint'
+        : expected === v.payload.fingerprint
+            ? 'matches'
+            : 'changed';
+    return { ok: true, result, against, payload: v.payload };
+}