signet-protocol 1.10.1 → 1.11.0

package/dist/vault-relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-relay.d.ts","sourceRoot":"","sources":["../src/vault-relay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAGtD,oFAAoF;AACpF,eAAO,MAAM,0BAA0B,MAAM,CAAA;AA2B7C;yDACyD;AACzD,qBAAa,eAAgB,SAAQ,KAAK;IACX,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE;gBAAhD,OAAO,EAAE,MAAM,EAAW,YAAY,EAAE,MAAM,EAAE;CAI7D;AAED;;;mCAGmC;AACnC,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,mBAAmB,CAAC,EAC1F,MAAM,EAAE,WAAW,EAAE,SAAS,SAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAsBxG;AAED;;;;;;;;;;uDAUuD;AACvD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,WAAW,CA6BxG"}

package/dist/vault-relay.js

@@ -0,0 +1,131 @@
+import { RelayClient } from './relay.js';
+import { VAULT_EVENT_KIND, vaultCheckpointShapedTag } from './vault-checkpoint.js';
+/** Matching events one relay may contribute to one query. More fails that relay. */
+export const MAX_VAULT_EVENTS_PER_RELAY = 128;
+const MAX_VAULT_RELAYS = 8;
+/** Must agree with the RelayClient constructor: a URL accepted here but rejected
+ * there would be skipped silently. Plain ws:// is loopback-only (localhost and
+ * 127.0.0.1; RelayClient does not accept [::1]). */
+function validRelay(raw) {
+    try {
+        const url = new URL(raw);
+        return !url.username && !url.password && !url.hash && (url.protocol === 'wss:'
+            || (url.protocol === 'ws:' && ['localhost', '127.0.0.1'].includes(url.hostname)));
+    }
+    catch {
+        return false;
+    }
+}
+/** Client-side re-check of the relay filter. Relays are untrusted, so an event
+ * outside the requested author/kind/id/d-tag is dropped before it counts
+ * towards any limit. */
+function matchesFilter(filter, event) {
+    if (!event || typeof event.id !== 'string' || typeof event.pubkey !== 'string' || !Array.isArray(event.tags))
+        return false;
+    if (filter.ids && !filter.ids.includes(event.id))
+        return false;
+    if (filter.authors && !filter.authors.includes(event.pubkey))
+        return false;
+    if (filter.kinds && !filter.kinds.includes(event.kind))
+        return false;
+    const dTags = filter['#d'];
+    if (dTags && !event.tags.some(t => Array.isArray(t) && t[0] === 'd' && dTags.includes(t[1])))
+        return false;
+    return true;
+}
+/** A relay query that did not complete on every relay. `failedRelays` names the
+ * relays that errored, timed out or exceeded the cap. */
+export class VaultRelayError extends Error {
+    failedRelays;
+    constructor(message, failedRelays) {
+        super(message);
+        this.failedRelays = failedRelays;
+        this.name = 'VaultRelayError';
+    }
+}
+/** EOSE is required: a timed-out empty query is not evidence of absence.
+ * Events are filtered against `filter` (and `accept`, when given) and
+ * de-duplicated before the per-relay cap applies, so unrelated events cannot
+ * crowd out the requested ones. */
+export function fetchVaultEvents(relay, filter, timeoutMs = 10000, accept) {
+    return new Promise((resolve, reject) => {
+        const events = new Map();
+        let subId;
+        let finished = false;
+        const finish = (error) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            if (subId)
+                relay.closeSubscription(subId);
+            if (error)
+                reject(error);
+            else
+                resolve([...events.values()]);
+        };
+        const timer = setTimeout(() => finish(new Error('Vault query did not complete')), timeoutMs);
+        try {
+            subId = relay.subscribe([filter], event => {
+                if (finished || !matchesFilter(filter, event) || (accept && !accept(event)) || events.has(event.id))
+                    return;
+                if (events.size >= MAX_VAULT_EVENTS_PER_RELAY)
+                    finish(new Error('Vault query exceeds event limit'));
+                else
+                    events.set(event.id, event);
+            }, () => finish());
+            if (finished)
+                relay.closeSubscription(subId);
+        }
+        catch {
+            finish(new Error('Vault query failed'));
+        }
+    });
+}
+/** Relay-backed reader. At most eight valid relay URLs are queried.
+ *
+ * A checkpoint query, empty or not, completes only when EVERY queried relay
+ * answered with EOSE: one relay's "nothing" is not evidence of absence, and one
+ * relay's heads may omit a device head another relay holds. Otherwise it throws
+ * a `VaultRelayError` naming the failed relays, and recovery reports
+ * `unavailable` with `failedRelays`. A permanently dead configured relay keeps
+ * reads unavailable until it is removed from the set. A chunk fetch by exact
+ * ID succeeds as soon as any relay returns it (its hash is pinned); "not found"
+ * again needs every relay. Checkpoint queries drop events without a
+ * checkpoint-shaped d-tag before the per-relay cap. */
+export function createVaultRelayReader(relays, open) {
+    const urls = [...new Set(relays.filter(validRelay))].slice(0, MAX_VAULT_RELAYS);
+    const query = async (filter, accept, enough) => {
+        if (!urls.length)
+            throw new VaultRelayError('No valid vault relays', []);
+        const events = new Map();
+        const failed = [];
+        await Promise.all(urls.map(async (url) => {
+            let relay;
+            try {
+                relay = new RelayClient(url);
+                await relay.connect();
+                const found = await fetchVaultEvents(relay, filter, undefined, accept);
+                for (const e of found)
+                    events.set(e.id, e);
+            }
+            catch {
+                failed.push(url);
+            }
+            finally {
+                relay?.disconnect();
+            }
+        }));
+        const result = [...events.values()];
+        if (failed.length && !(enough && enough(result))) {
+            throw new VaultRelayError(`Vault relays did not all answer: ${failed.length} of ${urls.length} failed`, failed.sort());
+        }
+        return result;
+    };
+    return {
+        checkpoints: (author, dTag) => query({ kinds: [VAULT_EVENT_KIND], authors: [author], ...(dTag ? { '#d': [dTag] } : {}), limit: MAX_VAULT_EVENTS_PER_RELAY }, event => vaultCheckpointShapedTag(event) !== null),
+        chunk: async (id) => (await query({ ids: [id], limit: 1 }, undefined, found => found.some(e => e.id === id))).find(e => e.id === id) ?? null,
+        open,
+    };
+}
+//# sourceMappingURL=vault-relay.js.map

package/dist/vault-relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-relay.js","sourceRoot":"","sources":["../src/vault-relay.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signet-protocol",
-  "version": "1.10.1",
+  "version": "1.11.0",
   "description": "Decentralised identity verification protocol for Nostr",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./experimental": {
+      "import": "./dist/experimental.js",
+      "types": "./dist/experimental.d.ts"
     }
   },
   "files": [
@@ -55,20 +59,20 @@
   "dependencies": {
     "@forgesworn/range-proof": "^2.0.0",
     "@forgesworn/ring-sig": "^3.0.0",
-    "@forgesworn/shamir-words": "^1.0.0",
+    "@forgesworn/shamir-words": "^1.2.0-alpha.1",
     "@noble/curves": "^2.0.1",
     "@noble/hashes": "^2.0.1",
     "@scure/bip39": "^2.0.1",
     "jurisdiction-kit": "^1.0.0",
     "nostr-attestations": "^2.3.1",
-    "nsec-tree": "^1.4.1",
+    "nsec-tree": "^1.6.0-alpha.1",
     "spoken-token": "^2.0.3"
   },
   "devDependencies": {
     "@types/node": "^25.3.3",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.4"
+    "vitest": "^5.0.0"
   },
   "funding": {
     "type": "lightning",

package/src/bot-ownership.ts

@@ -0,0 +1,77 @@
+/** Draft bot ownership profile of nostr-attestations. Builders never publish. */
+import { createAttestation, createRevocation, buildDTag } from 'nostr-attestations';
+import { verifyEventSync } from './crypto.js';
+import { isSafeLabel } from './utils.js';
+import type { NostrEvent, UnsignedEvent } from './types.js';
+export const BOT_OWNERSHIP_TYPE = 'bot-ownership';
+export const BOT_OWNERSHIP_POLICY = Object.freeze({ defaultDays: 30, minDays: 1, maxDays: 90,
+  renewBeforeDays: 10, retrySeconds: 86400, clockToleranceSeconds: 300 });
+const DAY = 86400, HEX = /^[0-9a-f]{64}$/;
+const stamp = (value: unknown): value is number => Number.isSafeInteger(value) && Number(value) >= 0;
+const labelOk = (label: unknown): label is string => typeof label === 'string' && !!label.trim() && label.length <= 100
+  && isSafeLabel(label);
+function validateParties(ownerPubkey: string, botPubkey: string, now: number) {
+  if (!HEX.test(ownerPubkey) || !HEX.test(botPubkey) || ownerPubkey === botPubkey || !stamp(now)) throw new Error('Invalid bot ownership parties or time');
+}
+/** The caller selects a persona, obtains explicit creation consent, and signs
+ * this ordinary Nostr event through its existing local or NIP-46 backend. */
+export function buildBotOwnership(args: { ownerPubkey: string; botPubkey: string; label: string; now: number; expiresAt?: number }): UnsignedEvent {
+  validateParties(args.ownerPubkey, args.botPubkey, args.now);
+  const expiresAt = args.expiresAt ?? args.now + BOT_OWNERSHIP_POLICY.defaultDays * DAY;
+  if (!labelOk(args.label) || !stamp(expiresAt) || expiresAt < args.now + DAY || expiresAt > args.now + 90 * DAY) throw new Error('Bot ownership requires a label and a lifetime from one to ninety days');
+  return { ...createAttestation({ type: BOT_OWNERSHIP_TYPE, subject: args.botPubkey,
+    validFrom: args.now, validTo: expiresAt, expiration: expiresAt,
+    content: JSON.stringify({ v: 1, label: args.label.trim() }) }), pubkey: args.ownerPubkey, created_at: args.now };
+}
+export function buildBotOwnershipRevocation(args: { ownerPubkey: string; botPubkey: string; now: number }): UnsignedEvent {
+  validateParties(args.ownerPubkey, args.botPubkey, args.now);
+  return { ...createRevocation({ type: BOT_OWNERSHIP_TYPE, identifier: args.botPubkey, subject: args.botPubkey,
+    effective: args.now }), pubkey: args.ownerPubkey, created_at: args.now };
+}
+export interface BotOwnershipClaim { ownerPubkey: string; botPubkey: string; label: string; issuedAt: number; expiresAt: number; eventId: string }
+export type BotOwnershipResult = { status: 'invalid' } | { status: 'revoked'; ownerPubkey: string; botPubkey: string; eventId: string }
+  | { status: 'valid' | 'lapsed'; claim: BotOwnershipClaim };
+/** No ownership trust is inherited by the bot. Callers pin the expected persona
+ * and bot and separately establish that they selected the newest event. */
+export async function readBotOwnership(event: NostrEvent, expected: { ownerPubkey: string; botPubkey: string; now: number; maxLifetimeDays?: number }): Promise<BotOwnershipResult> {
+  return readBotOwnershipSync(event, expected);
+}
+/** Same validation for synchronous transport/storage codecs. */
+export function readBotOwnershipSync(event: NostrEvent, expected: { ownerPubkey: string; botPubkey: string; now: number; maxLifetimeDays?: number }): BotOwnershipResult {
+  const invalid = { status: 'invalid' } as const;
+  const maximum = expected.maxLifetimeDays ?? BOT_OWNERSHIP_POLICY.maxDays;
+  if (!stamp(expected.now) || !Number.isSafeInteger(maximum) || maximum < 1 || maximum > 90
+    || !event || event.kind !== 31000 || event.pubkey !== expected.ownerPubkey || !HEX.test(expected.ownerPubkey)
+    || !HEX.test(expected.botPubkey) || expected.ownerPubkey === expected.botPubkey
+    || !stamp(event.created_at) || event.created_at > expected.now + BOT_OWNERSHIP_POLICY.clockToleranceSeconds
+    || typeof event.content !== 'string' || event.content.length > 1000 || !Array.isArray(event.tags) || event.tags.length > 16
+    || !event.tags.every(tag => Array.isArray(tag) && tag.length >= 2 && tag.length <= 4 && tag.every(value => typeof value === 'string' && value.length <= 256))) return invalid;
+  const single = (name: string) => {
+    const values = event.tags.filter(tag => tag[0] === name);
+    return values.length === 1 ? values[0][1] : undefined;
+  };
+  if (single('d') !== buildDTag(BOT_OWNERSHIP_TYPE, expected.botPubkey) || single('type') !== BOT_OWNERSHIP_TYPE
+    || single('p') !== expected.botPubkey || !verifyEventSync(event)) return invalid;
+  const statuses = event.tags.filter(tag => tag[0] === 'status');
+  if (statuses.length) {
+    if (statuses.length !== 1 || statuses[0][1] !== 'revoked' || event.content !== '') return invalid;
+    return { status: 'revoked', ownerPubkey: event.pubkey, botPubkey: expected.botPubkey, eventId: event.id };
+  }
+  const start = single('valid_from'), end = single('valid_to'), expiration = single('expiration');
+  if (start !== String(event.created_at) || !end || !/^\d+$/.test(end) || end !== expiration) return invalid;
+  const declared = Number(end);
+  if (!stamp(declared) || declared < event.created_at + DAY) return invalid;
+  let body: { v?: unknown; label?: unknown };
+  try { body = JSON.parse(event.content); } catch { return invalid; }
+  if (!body || body.v !== 1 || !labelOk(body.label)) return invalid;
+  // A user may choose a stricter ceiling. It never extends the signed expiry.
+  const expiresAt = Math.min(declared, event.created_at + maximum * DAY, event.created_at + 90 * DAY);
+  return { status: expected.now > expiresAt + BOT_OWNERSHIP_POLICY.clockToleranceSeconds ? 'lapsed' : 'valid',
+    claim: { ownerPubkey: event.pubkey, botPubkey: expected.botPubkey, label: body.label.trim(), issuedAt: event.created_at, expiresAt, eventId: event.id } };
+}
+/** Scheduling only: hardware signing still needs its normal approval. */
+export function botOwnershipRenewalDue(result: BotOwnershipResult, now: number, lastAttemptAt?: number): boolean {
+  if (!stamp(now) || (lastAttemptAt !== undefined && (!stamp(lastAttemptAt) || now - lastAttemptAt < BOT_OWNERSHIP_POLICY.retrySeconds))) return false;
+  return (result.status === 'valid' || result.status === 'lapsed') && now >= result.claim.issuedAt
+    && result.claim.expiresAt - now <= BOT_OWNERSHIP_POLICY.renewBeforeDays * DAY;
+}

package/src/crypto.ts

@@ -65,6 +65,11 @@ export async function signEvent(
 
 /** Verify a signed Nostr event's signature */
 export async function verifyEvent(event: NostrEvent): Promise<boolean> {
+  return verifyEventSync(event);
+}
+
+/** Synchronous verification for codecs that must reject invalid events inline. */
+export function verifyEventSync(event: NostrEvent): boolean {
   try {
     const expectedId = getEventId(event);
     if (expectedId !== event.id) return false;

package/src/experimental.ts

@@ -0,0 +1,25 @@
+/**
+ * signet-protocol/experimental — UNSTABLE, UNRELEASED draft contracts.
+ *
+ * The private vault checkpoint (docs/private-vault-v1.md) and the bot ownership
+ * profile (docs/bot-ownership-v1.md) are still under protocol review. Anything
+ * exported here may change or be removed in any release, including a minor or
+ * patch, without a deprecation period. Do not depend on it for production data.
+ * None of these names are exported from the package root.
+ */
+// Private vault: dedicated dataset keys (flat derivation; index means rotation).
+export { vaultPurpose, parseVaultPurpose, vaultKeyContext, deriveVaultIdentity, vaultIdentityFromMnemonic } from './vault-keys.js'
+export type { VaultDataset } from './vault-keys.js'
+export { VAULT_EVENT_KIND, MAX_VAULT_CHUNKS, MAX_VAULT_DEVICES, MAX_VAULT_CONTROL_BYTES,
+  MAX_VAULT_CHUNK_BYTES, vaultCheckpointTag, vaultContentHash, parseVaultCheckpoint,
+  matchesVaultChunk, vaultCheckpointShapedTag } from './vault-checkpoint.js'
+export type { VaultCheckpoint, VaultChunkRef } from './vault-checkpoint.js'
+export { readVaultSnapshot, readVaultRotations, readVaultHeads, readVaultHeadRotations,
+  VAULT_CLOCK_TOLERANCE_SECONDS } from './vault-recovery.js'
+export type { VaultReadResult, VaultReader, VaultHeadsResult } from './vault-recovery.js'
+
+export { createVaultRelayReader, fetchVaultEvents, MAX_VAULT_EVENTS_PER_RELAY, VaultRelayError } from './vault-relay.js'
+
+export { BOT_OWNERSHIP_TYPE, BOT_OWNERSHIP_POLICY, buildBotOwnership, buildBotOwnershipRevocation,
+  readBotOwnership, readBotOwnershipSync, botOwnershipRenewalDue } from './bot-ownership.js';
+export type { BotOwnershipClaim, BotOwnershipResult } from './bot-ownership.js';

package/src/index.ts

@@ -518,3 +518,6 @@ export {
   parseMigrationEvent,
   followMigrationChain,
 } from './migration.js';
+
+// Private vault and bot-ownership contracts are unreleased drafts: import them
+// from 'signet-protocol/experimental'. Nothing from them is exported here.

package/src/url-auth.ts

@@ -7,6 +7,7 @@
  */
 
 import type { LoginRequest } from './qr-router.js';
+import { UNSAFE_TEXT_CHARS } from './utils.js';
 
 /** Check if a URL is https:// or http://localhost (dev). */
 function isValidAuthUrl(url: string): boolean {
@@ -152,5 +153,5 @@ export function buildAuthDeniedUrl(callbackUrl: string): string {
 export function getUrlAuthSiteName(search: string): string {
   const params = new URLSearchParams(search);
   const name = params.get('name') ?? '';
-  return name.replace(/[\x00-\x1f\x7f-\x9f\u200b-\u200f\u2028-\u202e\u2066-\u2069]/g, '').slice(0, 64);
+  return name.replace(new RegExp(UNSAFE_TEXT_CHARS.source, 'gu'), '').slice(0, 64);
 }

package/src/utils.ts

@@ -18,3 +18,125 @@ export function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
   }
   return diff === 0;
 }
+
+/**
+ * One character class for text that is shown to people: C0 controls, DEL, C1
+ * controls, Arabic letter mark (U+061C), zero-width and LRM/RLM (U+200B-U+200F),
+ * line/paragraph separators and bidi embeddings/overrides (U+2028-U+202E), and
+ * bidi isolates (U+2066-U+2069). Not global: build a `g` copy to strip.
+ */
+export const UNSAFE_TEXT_CHARS = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028-\u202e\u2066-\u2069]/u;
+
+/**
+ * `UNSAFE_TEXT_CHARS` minus U+200D (zero-width joiner), which is not a bidi
+ * control and is needed for emoji sequences, plus other invisible/deprecated-
+ * format characters a label has no legitimate use for: soft hyphen (U+00AD),
+ * Mongolian vowel separator (U+180E), word joiner and the deprecated invisible
+ * math operators (U+2060-U+2064), and the BOM / zero width no-break space
+ * (U+FEFF). This is a fixed denylist only; it does not cover every Unicode
+ * "format" (Cf) or Default_Ignorable code point (variation selectors, emoji
+ * tag characters, Hangul fillers, Arabic number-sign marks, deprecated music
+ * format controls, ...). Use `isSafeLabel` to validate labels \u2014 it checks
+ * this denylist plus those two Unicode categories, carving out only the
+ * narrow, positionally-constrained exceptions emoji sequences require.
+ */
+export const UNSAFE_LABEL_CHARS = /[\u0000-\u001f\u007f-\u009f\u00ad\u061c\u180e\u200b\u200c\u200e\u200f\u2028-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/u;
+
+const CF_OR_DEFAULT_IGNORABLE = /[\p{Cf}\p{Default_Ignorable_Code_Point}]/u;
+const EXTENDED_PICTOGRAPHIC = /\p{Extended_Pictographic}/u;
+const KEYCAP_BASE = /[#*0-9]/;
+// A single unpaired UTF-16 surrogate is not a valid code point. In `u`-mode a
+// correctly paired surrogate combines into one astral code point first and
+// never matches this class; only a lone (unpaired) half does.
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
+const ZWJ = 0x200d;
+const VS15 = 0xfe0e, VS16 = 0xfe0f;
+const SKIN_TONE_MIN = 0x1f3fb, SKIN_TONE_MAX = 0x1f3ff;
+const TAG_CHAR_MIN = 0xe0020, TAG_CHAR_MAX = 0xe007e, TAG_CANCEL = 0xe007f, FLAG_BASE = 0x1f3f4;
+// RGI emoji tag sequences: only these three UK subdivision flags are
+// well-formed. Each entry is the tag-character run (base and cancel tag
+// excluded) spelling the ISO 3166-2 subdivision code in lowercase ASCII,
+// shifted into the U+E0000 tag-character plane.
+const RGI_FLAG_TAG_SEQUENCES: readonly (readonly number[])[] = ['gbeng', 'gbsct', 'gbwls'].map(code =>
+  Array.from(code, ch => 0xe0000 + (ch.codePointAt(0) as number)));
+
+/**
+ * Whether `codePoints[index]` is "an emoji element" for the zero-width-joiner
+ * rule below: an Extended_Pictographic code point itself, or U+FE0F / an
+ * emoji skin-tone modifier (U+1F3FB-1F3FF) that directly follows one.
+ */
+function endsInEmojiElement(codePoints: string[], index: number): boolean {
+  if (index < 0) return false;
+  const ch = codePoints[index];
+  if (EXTENDED_PICTOGRAPHIC.test(ch)) return true;
+  const cp = ch.codePointAt(0) as number;
+  if (cp !== VS16 && !(cp >= SKIN_TONE_MIN && cp <= SKIN_TONE_MAX)) return false;
+  const prev = codePoints[index - 1];
+  return prev !== undefined && EXTENDED_PICTOGRAPHIC.test(prev);
+}
+
+/**
+ * A label is unsafe if it contains a lone (unpaired) UTF-16 surrogate, any
+ * `UNSAFE_LABEL_CHARS` character, or any Unicode format (Cf) or
+ * Default_Ignorable_Code_Point code point, EXCEPT the narrow in-context uses
+ * emoji sequences need:
+ *
+ *  1. U+200D (ZWJ) only between two emoji elements: the code point before it
+ *     ends in an emoji element (see `endsInEmojiElement`) and the code point
+ *     after it is Extended_Pictographic. A leading, trailing or doubled ZWJ,
+ *     or one between ordinary letters, is rejected.
+ *  2. U+FE0E / U+FE0F (text/emoji variation selectors) only directly after
+ *     an Extended_Pictographic code point or a keycap base ([#*0-9]). Every
+ *     other variation selector (U+FE00-FE0D, U+E0100-E01EF) is rejected
+ *     everywhere.
+ *  3. Tag characters U+E0020-E007E only inside one of the three RGI UK
+ *     subdivision emoji flag sequences: U+1F3F4 (waving black flag) followed
+ *     by the exact tag-character spelling of "gbeng", "gbsct" or "gbwls"
+ *     then the cancel tag U+E007F, with nothing else in between. Any other
+ *     tag run — a different or misspelled subdivision code, extra or missing
+ *     tag characters, a hidden payload, a missing/extra cancel tag, or tag
+ *     characters with no U+1F3F4 base — is rejected, as is U+E0001 anywhere.
+ *
+ * Iterates by code point, not UTF-16 code unit.
+ */
+export function isSafeLabel(label: string): boolean {
+  if (LONE_SURROGATE.test(label) || UNSAFE_LABEL_CHARS.test(label)) return false;
+  const codePoints = Array.from(label);
+  // Indices that are part of one of the three well-formed RGI subdivision
+  // flag tag sequences: the exact tag-character spelling plus its cancel tag,
+  // immediately following a U+1F3F4.
+  const reservedTagIndex = new Set<number>();
+  for (let i = 0; i < codePoints.length; i++) {
+    if (codePoints[i].codePointAt(0) !== FLAG_BASE) continue;
+    for (const seq of RGI_FLAG_TAG_SEQUENCES) {
+      const cancelIndex = i + 1 + seq.length;
+      if (cancelIndex >= codePoints.length) continue;
+      const matchesSpelling = seq.every((cp, k) => codePoints[i + 1 + k].codePointAt(0) === cp);
+      if (matchesSpelling && codePoints[cancelIndex].codePointAt(0) === TAG_CANCEL) {
+        for (let k = i + 1; k <= cancelIndex; k++) reservedTagIndex.add(k);
+        break;
+      }
+    }
+  }
+  for (let i = 0; i < codePoints.length; i++) {
+    const ch = codePoints[i];
+    if (!CF_OR_DEFAULT_IGNORABLE.test(ch)) continue;
+    const cp = ch.codePointAt(0) as number;
+    if (cp === ZWJ) {
+      const next = codePoints[i + 1];
+      if (endsInEmojiElement(codePoints, i - 1) && next !== undefined && EXTENDED_PICTOGRAPHIC.test(next)) continue;
+      return false;
+    }
+    if (cp === VS15 || cp === VS16) {
+      const prev = codePoints[i - 1];
+      if (prev !== undefined && (EXTENDED_PICTOGRAPHIC.test(prev) || KEYCAP_BASE.test(prev))) continue;
+      return false;
+    }
+    if ((cp >= TAG_CHAR_MIN && cp <= TAG_CHAR_MAX) || cp === TAG_CANCEL) {
+      if (reservedTagIndex.has(i)) continue;
+      return false;
+    }
+    return false;
+  }
+  return true;
+}

package/src/vault-checkpoint.ts

@@ -0,0 +1,98 @@
+/** Shared private-vault checkpoint contract. No relay I/O or application data schema. */
+import { hmac } from '@noble/hashes/hmac.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js'
+import { parseVaultPurpose } from './vault-keys.js'
+
+export const VAULT_EVENT_KIND = 30078
+export const MAX_VAULT_CHUNKS = 32
+export const MAX_VAULT_DEVICES = 16
+export const MAX_VAULT_CONTROL_BYTES = 12 * 1024
+export const MAX_VAULT_CHUNK_BYTES = 100_000
+const HEX = /^[0-9a-f]{64}$/
+const encoder = new TextEncoder()
+const uint = (v: unknown): v is number => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0
+const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+
+export interface VaultChunkRef {
+  /** Exact signed event ID, never a mutable latest-by-tag lookup. */
+  eventId: string
+  author: string
+  /** SHA-256 of the UTF-8 encrypted event content. */
+  contentHash: string
+  contentBytes: number
+}
+
+export interface VaultCheckpoint {
+  v: 1
+  purpose: string
+  rotation: number
+  sequence: number
+  /** SHA-256 of the complete plaintext, checked before accepting a restored copy. */
+  revision: string
+  /** Device whose independently replaceable checkpoint this is. */
+  publisher?: string
+  devicePubkeys: string[]
+  /** Ordered chunk references; empty datasets still have one encrypted chunk. */
+  chunks: VaultChunkRef[]
+  /** Optional pointer, exactly rotation + 1; recovery follows it from index zero. */
+  nextRotation?: number
+}
+
+/** Publicly computable opaque tag; confidentiality comes from encryption and private keys. */
+export function vaultCheckpointTag(author: string, publisher?: string): string {
+  if (!HEX.test(author)) throw new Error('Invalid vault author')
+  if (publisher !== undefined && !HEX.test(publisher)) throw new Error('Invalid vault publisher')
+  return bytesToHex(hmac(sha256, hexToBytes(author), encoder.encode(`signet-vault-route\u0000checkpoint\u0000${publisher ?? '0'}`))).slice(0, 32)
+}
+
+const CHECKPOINT_TAG = /^[0-9a-f]{32}$/
+
+/** The single d-tag of a checkpoint-shaped event, or null. Every checkpoint tag
+ * is `vaultCheckpointTag` output: 32 lowercase hex characters. Necessary, not
+ * sufficient: the publisher is encrypted, so the shape cannot prove the tag. */
+export function vaultCheckpointShapedTag(event: { tags?: unknown }): string | null {
+  if (!event || !Array.isArray(event.tags)) return null
+  const dTags = event.tags.filter((t): t is unknown[] => Array.isArray(t) && t[0] === 'd')
+  if (dTags.length !== 1 || dTags[0].length !== 2 || typeof dTags[0][1] !== 'string' || !CHECKPOINT_TAG.test(dTags[0][1])) return null
+  return dTags[0][1]
+}
+
+export function vaultContentHash(content: string): string {
+  return bytesToHex(sha256(encoder.encode(content)))
+}
+
+/** Accept no partial checkpoint. A bad reference must never silently lose data. */
+export function parseVaultCheckpoint(raw: string, expected: { purpose: string; rotation: number }): VaultCheckpoint | null {
+  if (typeof raw !== 'string' || encoder.encode(raw).length > MAX_VAULT_CONTROL_BYTES) return null
+  let v: unknown
+  try { v = JSON.parse(raw) } catch { return null }
+  if (!object(v) || v.v !== 1 || typeof v.purpose !== 'string' || !parseVaultPurpose(v.purpose)
+    || v.purpose !== expected.purpose || v.rotation !== expected.rotation || !uint(v.rotation) || v.rotation > 0xffff_ffff
+    || !uint(v.sequence) || typeof v.revision !== 'string' || !HEX.test(v.revision)) return null
+  if (!Array.isArray(v.devicePubkeys) || !v.devicePubkeys.length || v.devicePubkeys.length > MAX_VAULT_DEVICES
+    || v.devicePubkeys.some(p => typeof p !== 'string' || !HEX.test(p))
+    || new Set(v.devicePubkeys).size !== v.devicePubkeys.length) return null
+  if (v.publisher !== undefined && (typeof v.publisher !== 'string' || !v.devicePubkeys.includes(v.publisher))) return null
+  if (!Array.isArray(v.chunks) || !v.chunks.length || v.chunks.length > MAX_VAULT_CHUNKS) return null
+  const chunks: VaultChunkRef[] = []
+  for (const c of v.chunks) {
+    if (!object(c) || typeof c.eventId !== 'string' || !HEX.test(c.eventId)
+      || typeof c.author !== 'string' || !v.devicePubkeys.includes(c.author)
+      || typeof c.contentHash !== 'string' || !HEX.test(c.contentHash)
+      || !uint(c.contentBytes) || c.contentBytes === 0 || c.contentBytes > MAX_VAULT_CHUNK_BYTES) return null
+    chunks.push({ eventId: c.eventId, author: c.author, contentHash: c.contentHash, contentBytes: c.contentBytes })
+  }
+  if (new Set(chunks.map(c => c.eventId)).size !== chunks.length) return null
+  if (v.nextRotation !== undefined && (v.nextRotation !== v.rotation + 1 || v.nextRotation > 0xffff_ffff)) return null
+  return { v: 1, purpose: v.purpose, rotation: v.rotation, sequence: v.sequence,
+    revision: v.revision, ...(v.publisher === undefined ? {} : { publisher: v.publisher as string }), devicePubkeys: [...v.devicePubkeys] as string[], chunks,
+    ...(v.nextRotation === undefined ? {} : { nextRotation: v.nextRotation as number }) }
+}
+
+/** Integrity check before decrypting. Signature and event-ID verification is also required. */
+export function matchesVaultChunk(ref: VaultChunkRef, event: { id: string; pubkey: string; kind: number; content: string }): boolean {
+  return event.id === ref.eventId && event.pubkey === ref.author && event.kind === VAULT_EVENT_KIND
+    && encoder.encode(event.content).length === ref.contentBytes
+    && vaultContentHash(event.content) === ref.contentHash
+}

package/src/vault-keys.ts

@@ -0,0 +1,59 @@
+/** Private dataset identities, derived directly from the tree root.
+ * Identity ordinals belong in the purpose; the derivation index is rotation.
+ * This does not change any existing persona derivation.
+ */
+import { derive, fromMnemonic } from 'nsec-tree'
+import type { Identity, TreeRoot } from 'nsec-tree'
+
+export type VaultDataset = 'profiles' | 'contacts:owner' | 'contacts:bots' | 'credentials' | 'settings'
+  | { dependant: number }
+
+const FIXED = new Set(['profiles', 'contacts:owner', 'contacts:bots', 'credentials', 'settings'])
+const MAX_INDEX = 0xffff_ffff
+
+function ordinal(value: number): void {
+  if (!Number.isInteger(value) || value < 0 || value > MAX_INDEX) {
+    throw new Error('Vault ordinal must be an unsigned 32-bit integer')
+  }
+}
+
+export function vaultPurpose(dataset: VaultDataset): string {
+  if (typeof dataset === 'string' && FIXED.has(dataset)) return `signet:vault:${dataset}`
+  if (dataset && typeof dataset === 'object' && 'dependant' in dataset) {
+    ordinal(dataset.dependant)
+    return `signet:vault:contacts:dependant-${dataset.dependant}`
+  }
+  throw new Error('Unknown vault dataset')
+}
+
+/** Strict parser: aliases such as dependant-01 would derive a different key. */
+export function parseVaultPurpose(purpose: string): VaultDataset | null {
+  if (typeof purpose !== 'string' || !purpose.startsWith('signet:vault:')) return null
+  const suffix = purpose.slice('signet:vault:'.length)
+  if (FIXED.has(suffix)) return suffix as VaultDataset
+  const match = /^contacts:dependant-(0|[1-9][0-9]*)$/.exec(suffix)
+  if (!match) return null
+  const dependant = Number(match[1])
+  return Number.isInteger(dependant) && dependant <= MAX_INDEX ? { dependant } : null
+}
+
+/** Suitable for Heartwood's per-request context; never a registry persona. */
+export function vaultKeyContext(dataset: VaultDataset, rotation = 0): { purpose: string; index: number } {
+  ordinal(rotation)
+  return { purpose: vaultPurpose(dataset), index: rotation }
+}
+
+/** Caller owns and must zeroise the returned child. The supplied root is retained. */
+export function deriveVaultIdentity(root: TreeRoot, dataset: VaultDataset, rotation = 0): Identity {
+  const { purpose, index } = vaultKeyContext(dataset, rotation)
+  return derive(root, purpose, index)
+}
+
+/** Keep root construction and use in one module instance (roots are opaque).
+ * Caller must zeroise the returned child; the temporary root is always destroyed.
+ */
+export function vaultIdentityFromMnemonic(mnemonic: string, dataset: VaultDataset, rotation = 0): Identity {
+  const root = fromMnemonic(mnemonic)
+  try { return deriveVaultIdentity(root, dataset, rotation) }
+  finally { root.destroy() }
+}