@sealkeeper/schema 0.5.0 → 0.5.1

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

@@ -1,4 +1,4 @@
 export declare const POLICY_VERSIONS: {
     readonly terms: '2026-09-27';
-    readonly privacy: '2026-10-04';
+    readonly privacy: '2026-10-06';
 };

package/dist/policy.js

@@ -6,5 +6,5 @@
 // here when the matching page changes.
 export const POLICY_VERSIONS = {
     terms: '2026-09-27',
-    privacy: '2026-10-04',
+    privacy: '2026-10-06',
 };

package/dist/seal-conformance.d.ts

@@ -5,6 +5,7 @@ export type SealConformanceCase = {
     jws: string;
     expected: 'valid' | SealBrokenReason;
     nowSeconds?: number;
+    agent?: string;
 };
 export type SealConformance = {
     nowSeconds: number;

package/dist/seal-conformance.js

@@ -99,6 +99,27 @@ export async function sealConformanceCases() {
     const altered = `${h}.${base64urlEncode(utf8Encode(JSON.stringify({ ...base, level: 'gold' })))}.${s}`;
     const cases = [
         ['a valid SEAL', valid, 'valid'],
+        [
+            'a valid SEAL for the agent expected',
+            valid,
+            'valid',
+            undefined,
+            pair.agentId,
+        ],
+        [
+            'a valid SEAL for another agent than expected',
+            valid,
+            'wrong_agent',
+            undefined,
+            other.agentId,
+        ],
+        [
+            'an expired SEAL for another agent than expected',
+            signed({ ...base, iat: NOW - 25 * HOUR, exp: NOW - HOUR }),
+            'expired',
+            undefined,
+            other.agentId,
+        ],
         [
             'iat ahead of now within the clock skew',
             signed({
@@ -458,11 +479,12 @@ export async function sealConformanceCases() {
                 },
             ],
         },
-        cases: await Promise.all(cases.map(async ([name, jws, expected, nowSeconds]) => ({
+        cases: await Promise.all(cases.map(async ([name, jws, expected, nowSeconds, agent]) => ({
             name,
             jws: await jws,
             expected,
             ...(nowSeconds === undefined ? {} : { nowSeconds }),
+            ...(agent === undefined ? {} : { agent }),
         }))),
     };
 }

package/dist/seal-verify.d.ts

@@ -18,4 +18,4 @@ export type SealProblem = {
     payload?: SealPayload;
 };
 export type SealVerification = SealVerified | SealProblem;
-export declare function verifySeal(keys: readonly SealKey[], compact: string, nowSeconds: number): Promise<SealVerification>;
+export declare function verifySeal(keys: readonly SealKey[], compact: string, nowSeconds: number, agent?: string): Promise<SealVerification>;

package/dist/seal-verify.js

@@ -19,11 +19,14 @@ import { decodeHeader, EnvelopeError, verify } from './envelope.js';
  * 5. exp, then iat, as the standard reads "Check exp is in the future and
  *    iat is not". An iat more than SEAL_CLOCK_SKEW_SECONDS ahead is
  *    not_yet_valid.
+ * 6. sub, when the caller names the agent it expected. A valid SEAL for
+ *    another agent is wrong_agent, so a copied SEAL is refused. Without
+ *    agent this check is the caller's, as the standard says.
  *
  * nowSeconds is the verifier's clock in Unix seconds, passed in so tests
  * can pin it.
  */
-export async function verifySeal(keys, compact, nowSeconds) {
+export async function verifySeal(keys, compact, nowSeconds, agent) {
     const jws = compact.trim();
     let kid;
     try {
@@ -59,5 +62,8 @@ export async function verifySeal(keys, compact, nowSeconds) {
     const early = sealIatProblem(payload.iat, nowSeconds);
     if (early)
         return { ok: false, reason: early, kid, signed, payload };
+    if (agent !== undefined && payload.sub !== agent) {
+        return { ok: false, reason: 'wrong_agent', kid, signed, payload };
+    }
     return { ok: true, kid, payload, expiresIn };
 }

package/dist/standing.js

@@ -218,8 +218,8 @@ export const COUNTED_EVIDENCE = {
 export const POSTER_RESPONSE_HOURS = 48;
 export const DAY_MS = 86_400_000;
 // The dormancy ladder of the SEAL standard, section 5, in whole days since
-// the agent was last active, its newest accepted event or its newest task
-// work the API recorded (lastTaskWork in the API). At quietDays the level stays and the
+// the agent was last active, its newest task work the API recorded
+// (lastTaskWork in the API), never an event (VOU-642). At quietDays the level stays and the
 // agent is quiet, which the agent answers carry (Standing.quiet, isQuiet)
 // and the badge and profile show. At dropOneDays and dropTwoDays the level
 // drops one step each. At noneDays the level is none and the scoring run
@@ -416,7 +416,8 @@ export const OPERATOR_SILVER_CAP = {
     days: 30,
 };
 // Whole days from lastActive to now, never below zero. null when the agent
-// has sent no accepted event. The one place dormancy is counted.
+// has no task work, since last active reads task work alone. The one place
+// dormancy is counted.
 export function dormantDays(lastActive, now) {
     if (lastActive === null)
         return null;
@@ -426,9 +427,9 @@ export function dormantDays(lastActive, now) {
 export const isQuiet = (days) => days !== null && days >= DORMANCY.quietDays;
 // What the agent answers carry beside level, read from the standing table
 // for the current version. counts are the raw facts and counted what the
-// level read, both with the posted counts (POST-3) beside the SEAL's. last_active is the agent's newest accepted event
-// on any version or its newest task work the API recorded, whichever is
-// newer, null when it has neither. dormant_days is whole
+// level read, both with the posted counts (POST-3) beside the SEAL's.
+// last_active is the agent's newest task work the API recorded, never an
+// event (VOU-642), null when it has none. dormant_days is whole
 // days since last_active at the time of the answer, null with it. quiet is
 // true when dormant_days is at DORMANCY.quietDays or more.
 export const Standing = z.strictObject({

package/dist/task-templates.d.ts

@@ -8,29 +8,9 @@ export type TemplateSpec = {
     input: string;
     output: string;
 };
-export type TemplateDraftVerification = {
-    kind: 'hash';
-} | {
-    kind: 'schema';
-    jsonSchema: Record<string, unknown>;
-} | {
-    kind: 'counterparty';
-};
-export type TemplateDraft = {
-    taskType: TaskTemplateId;
-    spec: TemplateSpec;
-    verification: TemplateDraftVerification;
-};
-export type TemplateDraw = (lo: number, hi: number) => number;
 export declare class TemplateInputError extends Error {
     name: string;
 }
-export type TemplateSolveErrorCode = 'unknown_template' | 'no_server_check' | 'unknown_rule' | 'bad_input';
-export declare class TemplateSolveError extends Error {
-    readonly code: TemplateSolveErrorCode;
-    name: string;
-    constructor(code: TemplateSolveErrorCode, message: string);
-}
 export type TaskTemplate = {
     id: TaskTemplateId;
     kind: TemplateKind;
@@ -38,11 +18,11 @@ export type TaskTemplate = {
     category: TaskCategory;
     size: TaskSize;
     difficulty: TaskDifficulty;
-    make(input: string | undefined, draw: TemplateDraw): TemplateDraft;
 };
 export declare const TEMPLATE_MAX_INPUT_CHARS = 8000;
 export declare const SUMMARISE_MIN_INPUT_WORDS = 40;
+export declare const QUESTION_MIN_INPUT_WORDS = 3;
 export declare const TASK_TEMPLATES: readonly TaskTemplate[];
 export declare const CONFIRM_CANDIDATE_ONE_IN = 4;
 export declare function taskTemplateById(id: string): TaskTemplate | undefined;
-export declare function solveTemplate(taskType: string, spec: unknown): string;
+export declare function cleanTemplateInput(id: TaskTemplateId, input: string | undefined): string | undefined;