@agnt-sdk/simon-server 0.1.1 → 0.2.0

package/dist/account.d.ts

@@ -52,7 +52,9 @@ export declare function endGrant(ctx: Context, req: Request): Promise<Reply>;
 export declare function cancelRecovery(ctx: Context, req: Request): Promise<Reply>;
 /**
  * A key principal ends its pairing: the address retires at once, its keys revoked, whatever they say. The
- * unpairing is the authority, so any key may sign the request; a repeat answers as the first call did.
+ * unpairing is the authority, so any key may sign the request; a repeat answers as the first call did. An
+ * unpairing by a key the principal moved on from counts when `succession` leads from that key to the
+ * principal held here.
  */
 export declare function unpair(ctx: Context, req: Request): Promise<Reply>;
 /** Recovery status is reserved to a currently authorized agent key. */

package/dist/account.js

@@ -214,18 +214,22 @@ async function cancelByCode(ctx, req, address, cancelCode) {
 }
 /**
  * A key principal ends its pairing: the address retires at once, its keys revoked, whatever they say. The
- * unpairing is the authority, so any key may sign the request; a repeat answers as the first call did.
+ * unpairing is the authority, so any key may sign the request; a repeat answers as the first call did. An
+ * unpairing by a key the principal moved on from counts when `succession` leads from that key to the
+ * principal held here.
  */
 export async function unpair(ctx, req) {
     const now = ctx.now();
     const headers = readSignedHeaders(req.headers, now, { agent: true, optionalAgent: true });
-    const body = readBody(req.body, ['address', 'unpairing']);
+    const body = readBody(req.body, ['address', 'unpairing', 'succession']);
     const named = normalizeAddress(body.address);
     checkActor(headers, named, now);
     await verifyAnyKey(ctx, req, headers);
     const agent = named === null ? null : await ctx.store.agentByAddress(named);
     // One answer for every refusal, with nothing in it: a principal is shown only to its agent's recipients.
-    if (!agent?.principal || !verifyUnpairing(agent.address, agent.principal, body.unpairing)) {
+    // Unpairing always wins (spec section 2.2): a key the principal moved on from unpairs too, given the succession
+    // from it to the principal held here.
+    if (!agent?.principal || !verifyUnpairing(agent.address, agent.principal, body.unpairing, body.succession)) {
         throw unauthorized('bad_proof', "unpairing is the key principal's signature over SIMON-UNPAIR, the address and the principal.", now);
     }
     if (!agent.retiredAt) {

package/dist/deliver.js

@@ -111,7 +111,7 @@ export async function deliver(ctx, req) {
         id,
         message: m,
         carrier: server,
-        claims: await judgeClaims(m, envelope.claims, author.kind, server, d => ctx.resolver.resolve(d, { charge: carrier })),
+        claims: await judgeClaims(m, envelope.claims, server, d => ctx.resolver.resolve(d, { charge: carrier })),
         signedClaims: envelope.claims ? { claims: envelope.claims, signature: envelope.claimsSignature } : null,
         receivedAt: iso(now),
         expiresAt: later(now, ctx.config.retentionDays * DAY_MS),

package/dist/extensions.d.ts

@@ -104,7 +104,7 @@ export interface Upload {
     bytes: Buffer;
 }
 /**
- * A reader asking for a published message whose `audience` header is `audience` (spec section 7.1). `reader`
+ * A reader asking for a published message whose `audience` header is `audience` (publishing profile, section 1). `reader`
  * is the address that signed the request with a key of its own agent document, or null when nobody in
  * particular asks.
  */

package/dist/notice.js

@@ -5,7 +5,7 @@
  * into the inbox: no policy stands between a server and its own agent.
  */
 import crypto from 'node:crypto';
-import { b64url, domainOf, fromB64url, keyToken, messageId, privateKeyFromSeed, signMessage, timestamp, } from '@agnt-sdk/simon-protocol';
+import { b64url, domainOf, fromB64url, keyToken, messageId, privateKeyFromSeed, signMessage, timestamp, VERSION, } from '@agnt-sdk/simon-protocol';
 import { iso, later } from "./context.js";
 import { takeIntoInbox } from "./fanout.js";
 /** The local part this server writes notices as, on every domain it serves; no agent may register it. */
@@ -39,7 +39,7 @@ export async function notify(ctx, address, text) {
         return false;
     }
     const message = signMessage({
-        v: 1,
+        v: VERSION,
         from,
         to: [address],
         inReplyTo: null,

package/dist/parts.js

@@ -35,7 +35,7 @@ import { authenticateAgent, authenticateServer, isAgentSigned, isServerSigned }
 import { iso, later } from "./context.js";
 import { notFound, unavailable } from "./errors.js";
 import { clientKey } from "./net/ip.js";
-import { askerOf, asReader, audienceOf, mayRead } from "./readers.js";
+import { askerOf, asReader, isPublic, mayRead } from "./readers.js";
 import { contentParts } from "./send.js";
 const SHA256 = /^[0-9a-f]{64}$/;
 export const PREFETCH_JITTER_MS = 3 * 60_000;
@@ -341,7 +341,7 @@ export function partRoutes(ctx) {
         const reader = await viewer.published.reader();
         // Try every unconditional grant before invoking an unrelated asynchronous audience policy.
         // Yield lazily: read() can return held bytes without starting or retaining that policy work.
-        const unconditional = ({ message }) => audienceOf(message) === null || reader === message.from;
+        const unconditional = ({ message }) => isPublic(message) || reader === message.from;
         for (const { author } of namers.filter(unconditional)) {
             for (const source of await ctx.store.heldFor(sha256, author, self))
                 yield source;

package/dist/public.js

@@ -62,7 +62,6 @@ export function agentDocument(ctx, agent) {
     for (;;) {
         const doc = signAgentDocument({
             address: agent.address,
-            kind: agent.kind,
             keys,
             ...(agent.retiredAt && {
                 retired: retiredAt(agent.retiredAt, keys),

package/dist/published.js

@@ -2,14 +2,14 @@
  * Published messages: messages written here with an empty `to` (spec section 7), served to whoever their
  * audience admits (readers.ts):
  *
- *   GET /simon/messages/<id>                  the message and its author's keys valid at its `sentAt`
+ *   GET /simon/messages/<id>                  the message, and its carrier's signed claims when it made any
  *   GET /simon/feeds/<address>/<feed>         the author's published messages in that feed, newest first
  *   GET /simon/messages/<id>/related          the relations to it marked listed that this server shows, newest first
  *
  * A message a reader may not see, an unknown one and a retired author's are answered alike: `404` for a
  * message and its relations, an empty page for a feed. Listings page with an opaque cursor, `before`.
  */
-import { header, invalid, MAX_CURSOR_LENGTH, MAX_LISTING_LIMIT, DEFAULT_LISTING_LIMIT, parseTimestamp, PUBLIC_RELATIONS, validAt, VERSION, } from '@agnt-sdk/simon-protocol';
+import { header, invalid, MAX_CURSOR_LENGTH, MAX_LISTING_LIMIT, DEFAULT_LISTING_LIMIT, PUBLIC_RELATIONS, VERSION, } from '@agnt-sdk/simon-protocol';
 import { notFound } from "./errors.js";
 import { json } from "./http.js";
 import { askerOf, mayRead } from "./readers.js";
@@ -18,7 +18,7 @@ import { askerOf, mayRead } from "./readers.js";
  * scan that ends there ends the listing too: its next cursor would be a hidden message's.
  */
 const MAX_SCANNED = 5000;
-/** The feed of a published message that names none (spec section 7.3). */
+/** The feed of a published message that names none (publishing profile, section 3). */
 const DEFAULT_FEED = 'posts';
 const CURSOR = new RegExp(`^[\\x21-\\x7e]{1,${MAX_CURSOR_LENGTH}}$`);
 const EMPTY = { messages: [], cursor: null, more: false };
@@ -71,7 +71,7 @@ async function listing(next, shows, before, limit) {
     return { messages: page.map(s => s.message), cursor: more ? page.at(-1).cursor : null, more };
 }
 /**
- * Whether a relation to a published message is one its author's server lists (spec section 7.4): its writer
+ * Whether a relation to a published message is one its author's server lists (publishing profile, section 4): its writer
  * marked it `listed`, a plain reply never is; of those, the relations this server shows (PUBLIC_RELATIONS);
  * and not retracted by its writer since.
  */
@@ -96,16 +96,11 @@ export function publishedRoutes(ctx) {
                 const record = await readable(req.params.id, await askerOf(ctx, req));
                 if (!record)
                     throw notFound('No published message has this id here.');
-                const author = (await ctx.store.agentByAddress(record.message.from));
-                const at = new Date(parseTimestamp(record.message.sentAt));
                 const claims = record.signedClaims
                     ? { claims: record.signedClaims.claims, claimsSignature: record.signedClaims.signature }
                     : {};
-                return json({
-                    message: record.message,
-                    keys: author.keys.filter(k => validAt(k, at)).map(({ key, added, revoked }) => ({ key, added, revoked })),
-                    ...claims,
-                });
+                // No keys beside it: a reader takes them from the author's agent document, where they are signed.
+                return json({ message: record.message, ...claims });
             },
         },
         {

package/dist/readers.d.ts

@@ -1,13 +1,14 @@
 /**
- * Who reads a published message, and whether its audience admits them (spec section 7.1).
+ * Who reads a published message, and whether its audience admits them (publishing profile, section 1).
  *
  * A reader proves who it is the way an author does: it signs the request with a key of its own agent
  * document and names itself in `simon-agent` (section 8). A request that is not signed, or whose signature
  * fails, asks as nobody in particular, and is answered exactly as one, so a refusal tells nothing about
  * the message.
  *
- * A message with no `audience` header is for anyone. One with a label is for whoever the extensions'
- * `admitsReader` chain admits; with no extension deciding, for no one but its author.
+ * `audience: public` is for anyone. Any other label is for whoever the extensions' `admitsReader` chain
+ * admits, and always its author; with no extension deciding, for no one but its author. A published message
+ * with no audience, which this version refuses, is its author's alone.
  */
 import { type AnyMessage } from '@agnt-sdk/simon-protocol';
 import type { Context } from './context.ts';
@@ -22,10 +23,17 @@ export declare const asReader: (address: string) => Asker;
  * Who asks, settled before anything is looked up for the request: a request naming `simon-agent` is
  * authenticated at once, its reader's document fetched and charged to the client, whatever it asks for and
  * whether or not anything matches, so neither the answer nor the fetches it makes tell which ids, feeds or
- * parts hold audience-limited posts (spec section 7.1).
+ * parts hold audience-limited posts (publishing profile, section 1).
  */
 export declare function askerOf(ctx: Context, req: Request): Promise<Asker>;
-/** The audience label a published version 1 message carries, or null for anyone. */
+/** The audience label that admits anyone (publishing profile, section 1). */
+export declare const PUBLIC = "public";
+/** The audience label a published message of a version known here carries, or null. */
 export declare const audienceOf: (m: AnyMessage) => string | null;
-/** Whether a published message written here may be shown to this asker. */
+/** Whether anyone may read a published message: its audience is `public`. */
+export declare const isPublic: (m: AnyMessage) => boolean;
+/**
+ * Whether a published message written here may be shown to this asker. A message without an audience
+ * label, which this version refuses, is its author's alone: closed, never open.
+ */
 export declare function mayRead(ctx: Context, m: AnyMessage, asker: Asker): Promise<boolean>;

package/dist/readers.js

@@ -1,13 +1,14 @@
 /**
- * Who reads a published message, and whether its audience admits them (spec section 7.1).
+ * Who reads a published message, and whether its audience admits them (publishing profile, section 1).
  *
  * A reader proves who it is the way an author does: it signs the request with a key of its own agent
  * document and names itself in `simon-agent` (section 8). A request that is not signed, or whose signature
  * fails, asks as nobody in particular, and is answered exactly as one, so a refusal tells nothing about
  * the message.
  *
- * A message with no `audience` header is for anyone. One with a label is for whoever the extensions'
- * `admitsReader` chain admits; with no extension deciding, for no one but its author.
+ * `audience: public` is for anyone. Any other label is for whoever the extensions' `admitsReader` chain
+ * admits, and always its author; with no extension deciding, for no one but its author. A published message
+ * with no audience, which this version refuses, is its author's alone.
  */
 import { header, VERSION, WireError } from '@agnt-sdk/simon-protocol';
 import { authenticateReader, isAgentSigned } from "./auth.js";
@@ -18,7 +19,7 @@ export const asReader = (address) => ({ reader: async () => address });
  * Who asks, settled before anything is looked up for the request: a request naming `simon-agent` is
  * authenticated at once, its reader's document fetched and charged to the client, whatever it asks for and
  * whether or not anything matches, so neither the answer nor the fetches it makes tell which ids, feeds or
- * parts hold audience-limited posts (spec section 7.1).
+ * parts hold audience-limited posts (publishing profile, section 1).
  */
 export async function askerOf(ctx, req) {
     if (!isAgentSigned(req))
@@ -34,15 +35,24 @@ export async function askerOf(ctx, req) {
         throw e;
     }
 }
-/** The audience label a published version 1 message carries, or null for anyone. */
+/** The audience label that admits anyone (publishing profile, section 1). */
+export const PUBLIC = 'public';
+/** The audience label a published message of a version known here carries, or null. */
 export const audienceOf = (m) => (m.v === VERSION ? header(m, 'audience') : null);
-/** Whether a published message written here may be shown to this asker. */
+/** Whether anyone may read a published message: its audience is `public`. */
+export const isPublic = (m) => audienceOf(m) === PUBLIC;
+/**
+ * Whether a published message written here may be shown to this asker. A message without an audience
+ * label, which this version refuses, is its author's alone: closed, never open.
+ */
 export async function mayRead(ctx, m, asker) {
     const audience = audienceOf(m);
-    if (audience === null)
+    if (audience === PUBLIC)
         return true;
     const reader = await asker.reader();
     if (reader === m.from)
         return true;
+    if (audience === null)
+        return false;
     return (await ctx.hooks.admitsReader({ message: m, audience, reader })) === 'admit';
 }

package/dist/register.js

@@ -18,7 +18,7 @@
  * account (account.ts).
  */
 import crypto from 'node:crypto';
-import { b64url, domainOf, invalid, isPrincipal, isPublicKey, normalizeAddress, pairingBytes, parseTimestamp, principalKey, readSignedHeaders, SEND_WINDOW_MS, SENT_AT_FUTURE_MS, unauthorized, verifyPairing, verifyRecovery, WireError, } from '@agnt-sdk/simon-protocol';
+import { b64url, domainOf, invalid, isPrincipal, isPublicKey, normalizeAddress, pairingBytes, parsePairing, parseTimestamp, principalKey, readSignedHeaders, SEND_WINDOW_MS, SENT_AT_FUTURE_MS, unauthorized, verifyPairing, verifyRecovery, WireError, } from '@agnt-sdk/simon-protocol';
 import { account, canPublishAgent, CANCEL_CODE, keysMayCancel, matches, readBody, RECOVERY, sha256, } from "./account.js";
 import { checkActor, verifyAnyKey } from "./auth.js";
 import { iso, later } from "./context.js";
@@ -169,10 +169,9 @@ async function pairing(ctx, address, key, body) {
     if (principalKey(principal) !== null) {
         if (body.pairing === undefined)
             return json({ status: 'pairing_required', address }, 202);
-        if (!verifyPairing(address, principal, body.pairing)) {
-            throw unauthorized('bad_proof', "pairing is the principal key's signature over the pairing string.", ctx.now(), {
-                pairingString: pairingBytes(address, principal),
-            });
+        if (!verifyPairing(address, principal, body.pairing, ctx.now())) {
+            const until = parsePairing(body.pairing)?.until ?? '<until>';
+            throw unauthorized('bad_proof', "pairing is <until> <signature>: the principal key's signature over the pairing string, lapsing within 366 days from now.", ctx.now(), { pairingString: pairingBytes(address, principal, until) });
         }
         return principal;
     }

package/dist/resolver.d.ts

@@ -23,7 +23,7 @@
  *     so it holds for every process sharing it). Only lookups made count: a cache hit, or a lookup another
  *     ask already has underway, costs nothing. Past either bound the lookup is `429`, and it is not counted.
  */
-import { type AgentKind, type KeyEntry, type Resolution, type ServerDocument } from '@agnt-sdk/simon-protocol';
+import { type KeyEntry, type Resolution, type ServerDocument } from '@agnt-sdk/simon-protocol';
 import type { Config } from './config.ts';
 import type { Log } from './extensions.ts';
 import type { Dns } from './net/dns.ts';
@@ -52,7 +52,6 @@ export type Peer = {
     outcome: Exclude<Resolution['outcome'], 'server'>;
 };
 export interface AgentKeys {
-    kind: AgentKind | 'unknown';
     keys: KeyEntry[];
 }
 /** Counts one lookup against whoever caused it, before it is made; throws 429 when they have none left. */

package/dist/send.d.ts

@@ -3,7 +3,7 @@
  * client API gives: the message as a delivery would check it (spec section 6.3, steps 1, 3 and 4); a
  * version this server implements; `from` the agent's own address, on a domain that still names this
  * server; the author's signature; the paired or solo rule; the 24-hour window; no message with an audience
- * carried whole (spec section 7.1); every content-addressed
+ * carried whole (spec section 5.4); every content-addressed
  * part held for this agent, uploaded or received, so a part it received can be forwarded. Then the message,
  * this server's claims about it signed for it (spec section 6.2), and one delivery row per recipient domain
  * are stored as one, and the answer is given; delivery follows.

package/dist/send.js

@@ -3,7 +3,7 @@
  * client API gives: the message as a delivery would check it (spec section 6.3, steps 1, 3 and 4); a
  * version this server implements; `from` the agent's own address, on a domain that still names this
  * server; the author's signature; the paired or solo rule; the 24-hour window; no message with an audience
- * carried whole (spec section 7.1); every content-addressed
+ * carried whole (spec section 5.4); every content-addressed
  * part held for this agent, uploaded or received, so a part it received can be forwarded. Then the message,
  * this server's claims about it signed for it (spec section 6.2), and one delivery row per recipient domain
  * are stored as one, and the answer is given; delivery follows.
@@ -11,7 +11,7 @@
  * A repeat answers as the first call did, and stores again whatever rows a store lost, so a client that
  * retries after a crash never leaves its message undelivered.
  */
-import { carriedMessages, checkEnvelopeShape, claimsBytes, checkMessage, checkPrincipal, checkSupportedVersion, deliveryWindow, domainOf, invalid, isFresh, isJsonObject, judgeClaims, messageId, namedFiles, parseMessage, parseStrict, SEND_WINDOW_MS, sign, unauthorized, verifyMessage, } from '@agnt-sdk/simon-protocol';
+import { carriedMessages, checkEnvelopeShape, claimsBytes, checkMessage, checkPrincipal, checkSupportedVersion, deliveryWindow, domainOf, header, invalid, isFresh, isJsonObject, judgeClaims, messageId, namedFiles, parseMessage, parseStrict, readSuccession, SEND_WINDOW_MS, sign, unauthorized, verifyMessage, VERSION, } from '@agnt-sdk/simon-protocol';
 import { authenticateAgent } from "./auth.js";
 import { iso, later } from "./context.js";
 import { badRequest, conflict } from "./errors.js";
@@ -41,6 +41,8 @@ async function write(ctx, agent, m, hints) {
         // The claims that travel, as the first call checked them: without this server's judgement.
         checkHints(ctx, hints, m, earlier.signedClaims?.claims ?? []);
         await ctx.store.putMessage(earlier, { deliveries: deliveriesFor(earlier, hints) });
+        // The first call may have stored the message and stopped before it moved the record.
+        await follow(ctx, agent, earlier.message);
         ctx.wake();
         return { id, receivedAt: earlier.receivedAt };
     }
@@ -57,7 +59,7 @@ async function write(ctx, agent, m, hints) {
     if (!verifyMessage(m, agent.keys)) {
         throw unauthorized('bad_signature', "The message does not verify with the author's keys valid at its sentAt.", now);
     }
-    checkPrincipal(m, agent.principal === null ? { kind: 'solo' } : { kind: 'paired', for: agent.principal });
+    checkPrincipal(m, agent.principal === null ? { kind: 'solo' } : { kind: 'paired', for: agent.principal }, now);
     if (!isFresh(m, now, SEND_WINDOW_MS)) {
         throw invalid('sentAt is more than 24 hours old or more than 5 minutes ahead.', { field: 'sentAt' });
     }
@@ -68,12 +70,23 @@ async function write(ctx, agent, m, hints) {
         }
     }
     const made = await ctx.hooks.claimsFor(m, agent);
-    const claims = await judgeClaims(m, made, agent.kind, ctx.config.origin, d => ctx.resolver.resolve(d, { charge: payer }));
+    const claims = await judgeClaims(m, made, ctx.config.origin, d => ctx.resolver.resolve(d, { charge: payer }));
     // What travels, and is signed for the message, is the claims considered, without this server's judgement.
     const sent = claims.map(({ authoritative: _, ...c }) => c);
     checkHints(ctx, hints, m, sent);
     ctx.rate.hit('send', agent.address);
     ctx.rate.distinct('destinations', agent.address, m.to.map(domainOf));
+    // A succession its principal signed moves a paired agent's principal on to the successor (spec section 2.2),
+    // once the message is stored, so a message that is not stored moves nothing. A concurrent send may have made
+    // the same move first; anything else that changed the record meanwhile refuses this one.
+    const forValue = m.v === VERSION ? header(m, 'for') : null;
+    const moving = agent.principal !== null && forValue !== null && forValue !== agent.principal;
+    if (moving) {
+        const held = (await ctx.store.agentByAddress(agent.address))?.principal;
+        if (held !== agent.principal && held !== forValue) {
+            throw conflict('principal_changed', "This agent's principal changed meanwhile: compose the message again.");
+        }
+    }
     const record = {
         id,
         message: m,
@@ -84,10 +97,35 @@ async function write(ctx, agent, m, hints) {
         expiresAt: later(now, ctx.config.retentionDays * DAY_MS),
     };
     const stored = await ctx.store.putMessage(record, { deliveries: deliveriesFor(record, hints) });
+    if (moving)
+        await follow(ctx, agent, m);
     ctx.defer(() => ctx.hooks.emit('stored', { message: stored }));
     await changed(ctx, agent.address);
     return { id, receivedAt: stored.receivedAt };
 }
+/**
+ * Move the agent's record on to the successor a stored message names along its succession from the principal
+ * held (spec section 2.2), as a compare-and-set. A record that changed otherwise since the message was checked
+ * stays as that change left it: the message was checked against the record as it was, as any message racing
+ * a change is.
+ */
+async function follow(ctx, agent, m) {
+    const from = agent.principal;
+    if (from === null || m.v !== VERSION)
+        return;
+    const to = header(m, 'for');
+    const succession = header(m, 'succession');
+    if (to === null || to === from || succession === null)
+        return;
+    if (!readSuccession(succession, to)?.some(step => step.from === from))
+        return;
+    if (await ctx.store.succeedPrincipal(agent.address, from, to)) {
+        ctx.log('info', 'principal succeeded', { address: agent.address });
+    }
+    else if ((await ctx.store.agentByAddress(agent.address))?.principal !== to) {
+        ctx.log('warn', 'principal changed while a move was stored', { address: agent.address });
+    }
+}
 /** How often a send renews what it noted about serving its domain, at most. */
 const SERVING_CHECKED_EVERY_MS = 10 * 60_000;
 /**
@@ -112,15 +150,23 @@ async function notedServing(ctx, domain, now) {
     }
 }
 /**
- * A message with an `audience` header is never forwarded or quoted whole (spec section 7.1): a message that
- * carries one inline, at any depth, is refused as the message checks refuse a part (`400 invalid`, `parts`).
- * One carried by content address is not seen here; its bytes are the client's to keep to itself.
+ * A message for a narrower audience than `public` is never forwarded or quoted whole (spec section 5.4): a
+ * message that carries one inline, at any depth, is refused as the message checks refuse a part (`400
+ * invalid`, `parts`). Narrower means an `audience` other than `public`, whatever the carried message's
+ * version (one that cannot tell keeps it to itself), or a message of this version to no one with no
+ * audience, which is its author's alone. One carried by content address is not seen here; its bytes are the
+ * client's to keep to itself.
  */
 function checkCarriedAudience(m) {
     for (const inner of carriedMessages(m)) {
         const headers = inner.headers;
-        if (inner.v === 1 && isJsonObject(headers) && Object.hasOwn(headers, 'audience')) {
-            throw invalid('A message with an audience is never forwarded or quoted whole (spec section 7.1).', {
+        if (!isJsonObject(headers))
+            continue;
+        const narrower = Object.hasOwn(headers, 'audience')
+            ? headers.audience !== 'public'
+            : inner.v === VERSION && Array.isArray(inner.to) && inner.to.length === 0;
+        if (narrower) {
+            throw invalid('A message for a narrower audience than public is never forwarded or quoted whole (spec section 5.4).', {
                 field: 'parts',
             });
         }

package/dist/server.js

@@ -74,7 +74,7 @@ export function createServer(opts) {
             ownDocument: () => (docCache ??= ownDocument(ctx)),
             localAgent: async (address) => {
                 const agent = await store.agentByAddress(address);
-                return agent && !agent.retiredAt ? { kind: agent.kind, keys: agent.keys } : null;
+                return agent && !agent.retiredAt ? { keys: agent.keys } : null;
             },
             publicSuffixes: config.publicSuffixFile ? loadPublicSuffixes(config.publicSuffixFile) : undefined,
             chargeCarrier: carrier => ctx.rate.hit('carrierLookup', carrier),

package/dist/store/contract.js

@@ -8,6 +8,7 @@
  */
 import assert from 'node:assert/strict';
 import { afterEach, beforeEach, describe, it } from 'node:test';
+import { VERSION } from '@agnt-sdk/simon-protocol';
 import { MAX_STORED_KEYS } from "./store.js";
 const T0 = Date.parse('2026-10-15T00:00:00.000Z');
 const at = (ms = 0) => new Date(T0 + ms).toISOString();
@@ -26,7 +27,7 @@ const agent = (address, ...keys) => ({
 let n = 0;
 function message(from, to, extra = {}) {
     const m = {
-        v: 1,
+        v: VERSION,
         from,
         to,
         inReplyTo: null,
@@ -92,6 +93,17 @@ export function storeContract(name, make) {
                 assert.equal(retired?.unpairing ?? null, null);
                 assert.equal(await store.createAgent(agent('ada@a.test', 'k3')), 'address_taken');
             });
+            it("moves a paired agent's principal to its successor only from the principal it holds, never once retired", async () => {
+                await store.createAgent({ ...agent('ada@a.test', 'k1'), kind: 'paired', principal: 'simon-key:p1' });
+                assert.equal(await store.succeedPrincipal('ada@a.test', 'simon-key:p0', 'simon-key:p2'), false, 'stale');
+                assert.equal(await store.succeedPrincipal('ada@a.test', 'simon-key:p1', 'simon-key:p2'), true);
+                assert.equal((await store.agentByAddress('ada@a.test'))?.principal, 'simon-key:p2');
+                assert.equal(await store.succeedPrincipal('ada@a.test', 'simon-key:p1', 'simon-key:p3'), false, 'a fork');
+                assert.equal(await store.succeedPrincipal('bob@a.test', 'simon-key:p1', 'simon-key:p2'), false, 'no agent');
+                await store.retireAgent('ada@a.test', at(1));
+                assert.equal(await store.succeedPrincipal('ada@a.test', 'simon-key:p2', 'simon-key:p3'), false, 'retired');
+                assert.equal((await store.agentByAddress('ada@a.test'))?.principal, 'simon-key:p2');
+            });
             it('keeps the unpairing that retired an address, and only the first retirement', async () => {
                 await store.createAgent(agent('ada@a.test', 'k1'));
                 await store.retireAgent('ada@a.test', at(1), 'UNPAIRING');

package/dist/store/sqlite-migration.js

@@ -7,7 +7,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { backup, DatabaseSync } from 'node:sqlite';
-import { canonicalize, checkMessage, isAddress, isImplemented, isPrincipal, fromB64url, normalizeDomain, readKeys, serverOrigin, isPublicKey, MAX_DOCUMENT_BYTES, MAX_DOCUMENT_KEYS, messageId, namedFiles, parseJson, parseKeyToken, parseTimestamp, } from '@agnt-sdk/simon-protocol';
+import { canonicalize, checkMessage, isAddress, isImplemented, isPrincipal, fromB64url, normalizeDomain, readKeys, serverOrigin, isPublicKey, MAX_DOCUMENT_BYTES, MAX_DOCUMENT_KEYS, messageId, namedFiles, parseJson, parseKeyToken, parseTimestamp, VERSION, } from '@agnt-sdk/simon-protocol';
 import { listedKeys } from "../public.js";
 import { SqliteStore } from "./sqlite.js";
 import { resolveRetractionCapacity } from "./store.js";
@@ -519,7 +519,7 @@ function precomputedReceipts(data, messages, limits) {
     const receipts = Object.create(null);
     for (const row of data.messages) {
         const message = messages.get(row.id);
-        if (message.v !== 1)
+        if (message.v !== VERSION)
             continue;
         const v1 = message;
         if (v1.headers.rel !== 'retract' || v1.inReplyTo === null)
@@ -854,7 +854,7 @@ export async function createSqliteV2Candidate(options) {
                         const message = messages.get(row.id);
                         extra = {
                             ...extra,
-                            in_reply_to: message.v === 1 ? message.inReplyTo : null,
+                            in_reply_to: message.v === VERSION ? message.inReplyTo : null,
                             signed_claims: null,
                             cursor: null,
                             taken: null,

package/dist/store/sqlite.d.ts

@@ -13,6 +13,7 @@ export declare class SqliteStore implements Store {
     revokeKey(address: string, key: string, at: string, admit?: AgentAdmission): Promise<"not_found" | "revoked" | "last_key">;
     replaceKeys(address: string, entry: AgentKey, admit?: AgentAdmission): Promise<"retired" | "key_in_use" | "too_many_keys" | "replaced">;
     keepOnlyKey(address: string, key: string, at: string): Promise<"kept" | "not_held">;
+    succeedPrincipal(address: string, from: string, to: string): Promise<boolean>;
     retireAgent(address: string, at: string, unpairing?: string): Promise<void>;
     beginRecovery(address: string, value: unknown, expiresAt: string | null, now: string, admit?: AgentAdmission): Promise<unknown>;
     activateRecovery(address: string, expectedRecovery: unknown, now: string): Promise<boolean>;

package/dist/store/sqlite.js

@@ -4,7 +4,7 @@
  * the file. Times are stored as epoch milliseconds, so comparisons never depend on how a timestamp is spelled.
  */
 import { randomUUID } from 'node:crypto';
-import { canonicalize, header, namedFiles } from '@agnt-sdk/simon-protocol';
+import { canonicalize, header, namedFiles, VERSION } from '@agnt-sdk/simon-protocol';
 import { MAX_STORED_KEYS, StoreCapacityError, resolveRetractionCapacity } from "./store.js";
 /** The schema's version, kept in `PRAGMA user_version`. A file made by another version is refused. */
 const SCHEMA_VERSION = 9;
@@ -76,7 +76,7 @@ const uniqueSources = (sources) => [
     ...new Map(sources.map(s => [`${'uploader' in s ? 'u' : 'c'} ${sourceKey(s)} ${s.size}`, s])).values(),
 ];
 /** A version 1 message's `inReplyTo`. Other versions point at nothing the server can see. */
-const inReplyTo = (m) => (m.v === 1 ? (m.inReplyTo ?? null) : null);
+const inReplyTo = (m) => m.v === VERSION ? (m.inReplyTo ?? null) : null;
 /** A page of rows, newest first, fetched one beyond `limit` to tell whether there are more. */
 const page = (rows, limit, record) => ({
     records: rows.slice(0, limit).map(r => ({ cursor: r.id, message: record(r) })),
@@ -332,6 +332,15 @@ export class SqliteStore {
             return 'kept';
         });
     }
+    async succeedPrincipal(address, from, to) {
+        return this.#tx(() => {
+            const sql = 'UPDATE agents SET principal = ? WHERE address = ? AND principal = ? AND retired_at IS NULL';
+            if (this.#run(sql, to, address, from).changes !== 1)
+                return false;
+            this.#bumpAuthority(address);
+            return true;
+        });
+    }
     async retireAgent(address, at, unpairing) {
         this.#tx(() => {
             if (!this.#get('SELECT 1 FROM agents WHERE address = ? AND retired_at IS NULL', address))
@@ -422,7 +431,7 @@ export class SqliteStore {
         });
     }
     #isRetraction(record) {
-        return (record.message.v === 1 &&
+        return (record.message.v === VERSION &&
             header(record.message, 'rel') === 'retract' &&
             inReplyTo(record.message) !== null);
     }

package/dist/store/store.d.ts

@@ -201,6 +201,11 @@ export interface Store {
     /** Recovery is atomic with retirement, uniqueness and final signed-document admission. */
     replaceKeys(address: string, entry: AgentKey, admit?: AgentAdmission): Promise<'replaced' | 'key_in_use' | 'retired' | 'too_many_keys'>;
     keepOnlyKey(address: string, key: string, at: string): Promise<'kept' | 'not_held'>;
+    /**
+     * Move a paired agent's principal from `from` to `to`, its successor (spec section 2.2), atomically: only
+     * while the agent is not retired and its principal is still `from`. False when it is not.
+     */
+    succeedPrincipal(address: string, from: string, to: string): Promise<boolean>;
     /** Only the first retirement counts, including its unpairing evidence. */
     retireAgent(address: string, at: string, unpairing?: string): Promise<void>;
     /** Begin only against the current admitted authority; return its existing live pending proof or the new one. */
@@ -237,8 +242,8 @@ export interface Store {
     published(author: string, before: string | null, limit: number): Promise<Page>;
     /**
      * The messages in `address`'s inbox whose `inReplyTo` is `id`, newest first, after the one whose id is
-     * `before` (null for the newest): the relations to a published message its author may show (spec section
-     * 7.4). A record's cursor is its message id.
+     * `before` (null for the newest): the relations to a published message its author may show (publishing
+     * profile, section 4). A record's cursor is its message id.
      */
     repliesTo(address: string, id: string, before: string | null, limit: number): Promise<Page>;
     /** Durable same-author rel:retract suppression for a live listing, scoped to its owner's accepted inbox. */

package/dist/testing.d.ts

@@ -1,6 +1,8 @@
 import type { Reply, Request } from './http.ts';
 import { type Dns } from './net/dns.ts';
 import { type Http, type HttpRequest, type HttpResponse } from './net/fetch.ts';
+/** A pairing's until a year after the test clock starts, so it counts at the clock's time, not the wall's. */
+export declare const CLOCK_PAIRING_UNTIL = "2027-10-15T12:00:00.000Z";
 export declare class Clock {
     t: number;
     now: () => Date;

package/dist/testing.js

@@ -12,8 +12,11 @@
 import { canonicalize } from '@agnt-sdk/simon-protocol';
 import { DnsFailure } from "./net/dns.js";
 import { Unreachable } from "./net/fetch.js";
+const CLOCK_START = '2026-10-15T12:00:00.000Z';
+/** A pairing's until a year after the test clock starts, so it counts at the clock's time, not the wall's. */
+export const CLOCK_PAIRING_UNTIL = '2027-10-15T12:00:00.000Z';
 export class Clock {
-    t = Date.parse('2026-10-15T12:00:00.000Z');
+    t = Date.parse(CLOCK_START);
     now = () => new Date(this.t);
     advance(ms) {
         this.t += ms;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agnt-sdk/simon-server",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "The SIMON reference server: the whole protocol and client API, hardened, with Node's standard library only, and the Store contract any storage proves itself with.",
   "license": "Apache-2.0",
   "keywords": [
@@ -53,7 +53,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@agnt-sdk/simon-protocol": "0.1.1"
+    "@agnt-sdk/simon-protocol": "0.2.0"
   },
-  "gitHead": "ffb7c0a68f0dff4cb1d03b29b2ebad02f99831af"
+  "gitHead": "1606981305ede14c02ddfdac9409b45b3a91a903"
 }