signet-protocol 1.10.1 → 1.11.1

package/llms.txt

@@ -0,0 +1,134 @@
+# Signet Protocol
+
+> Nostr has no identity layer: anyone can impersonate anyone, and there's no way to verify age for child safety. Signet is a decentralised identity verification protocol for Nostr that lets users prove claims about their identity (age, profession, parenthood) using zero-knowledge proofs, without revealing personal data or relying on a central authority.
+
+Signet is for Nostr client developers, relay operators, and anyone building identity-aware applications on Nostr. It provides a TypeScript library (`signet-protocol`) that handles credentials, vouches, trust scoring, and ZKP age proofs. Unlike centralised identity services, Signet anchors trust to professional bodies (law societies, medical boards, notary commissions) and uses cryptographic proofs instead of data collection.
+
+## Getting Started
+
+```bash
+npm install signet-protocol
+```
+
+Requires Node ≥22. ESM only (no CommonJS `require` export).
+
+Display a verification badge for any Nostr pubkey (Level 1 integration: a weekend):
+
+```typescript
+import { computeBadge, buildBadgeFilters, fetchFromRelay, meetsMinimumTier } from 'signet-protocol';
+
+// Build relay filters and fetch events (fetchFromRelay is the package's own minimal relay client)
+const filters = buildBadgeFilters(['<hex-pubkey>']);
+const events = await fetchFromRelay('wss://relay.example.com', filters);
+
+// Compute badge (async: returns Promise<BadgeInfo>)
+const badge = await computeBadge('<hex-pubkey>', events, { verifySignatures: true });
+// badge.tier => 3, badge.score => 106, badge.displayLabel => "Verified (Tier 3)"
+
+// Gate features on verification level
+if (meetsMinimumTier(badge, 2)) {
+  // allow posting in verified-only community
+}
+```
+
+`fetchFromRelay(relayUrl: string, filters: NostrFilter[]): Promise<NostrEvent[]>` connects, collects events until EOSE and disconnects. Non-localhost relay URLs must be `wss://`. Any other Nostr client works equally well: pass the `buildBadgeFilters` output as REQ filters and give the returned events to `computeBadge`.
+
+## Key Concepts
+
+- **4 verification tiers**: Self-declared (Tier 1) → Web-of-trust via peer vouches (Tier 2) → Professional verification with ZKP age proof (Tier 3) → Professional + child safety (Tier 4)
+- **Signet IQ** (0–200): A continuous identity quality score measuring statistical confidence that an identity is real, not fabricated. Weighted by professional verification, in-person vouches, online vouches, account age, and identity bridges. 100 represents the current government standard. IQ is not reputation: it measures identity quality, not trustworthiness. The source calls the same number the "Signet Score" (`TrustScoreBreakdown.score`).
+- **Zero-knowledge age proofs**: Pedersen range proofs on secp256k1 (the `@forgesworn/range-proof` dependency; no trusted setup) prove age ranges (e.g. "adult" or "child aged 8–12") without revealing date of birth.
+- **Document nullifiers**: SHA-256 of document fields prevents duplicate identity registration without storing any personal data.
+- **Single attestation kind** (31000, NIP-VA) plus policies (30078): All identity attestations (credentials, vouches, verifier management, challenges, revocations, identity bridges, delegation) share kind 31000, differentiated by `type` tag. The voting extension (kinds 30482–30484) is a separate package, `nostr-anon-vote`.
+
+## API Surface
+
+Conventions used throughout:
+- Private keys are 64-character hex strings (not `Uint8Array`). Public keys are 64-character x-only hex. The identity functions are the exception: `createSignetIdentity` takes a BIP-39 mnemonic and `createSignetIdentityFromNsec` takes a bech32 nsec string or 32 raw bytes.
+- Of the `create*` functions documented in this file, the event-signing ones (credentials, vouches, policies, verifiers, challenges, revocations, identity bridges, guardian delegations) are async and return a signed `Promise<NostrEvent>` (with `id` and `sig`). The matching `build*Event` functions return an unsigned `UnsignedEvent`. The documented `create*` helpers that are not event signers return what is stated beside them: `createAgeRangeProof` (synchronous, `RangeProof`), `createSignetIdentity` / `createSignetIdentityFromNsec` (synchronous, `SignetIdentity`) and `createLinkageProof` (synchronous, `LinkageProof`). The package root exports other `create*` functions that this file does not cover (for example `createTwoCredentialCeremony`, `createBondProof`); check their return types in `src/` rather than assuming the event-signer shape.
+- Tiers are `SignetTier` (`1 | 2 | 3 | 4`). Timestamps (`expiresAt`, `occurredAt`, `accountCreatedAt`) are unix seconds.
+- Throws use the `SignetError` hierarchy (`SignetValidationError`, `SignetCryptoError`).
+
+### Credentials (kind 31000, type: credential)
+- `createSelfDeclaredCredential(privateKey, scope = 'adult', expiresAt?)`: Tier 1. `scope` is `'adult' | 'adult+child'`.
+- `createPeerVouchedCredential(issuerPrivateKey, subjectPubkey, opts)`: Tier 2. `opts: { assertionEventId: string; assertionRelay?: string; expiresAt?: number }`. `assertionEventId` is the subject's Tier 1 event.
+- `createProfessionalCredential(verifierPrivateKey, subjectPubkey, opts)`: Tier 3. `opts: { assertionEventId: string; profession: string; jurisdiction: string; actualAge: number; assertionRelay?: string; expiresAt?: number; occurredAt?: number; proofBlob?: string }`. Generates an `'18+'` range proof from `actualAge` into the event content.
+- `createChildSafetyCredential(verifierPrivateKey, subjectPubkey, opts)`: Tier 4. Same `opts` as Tier 3 plus `ageRange: string` (the range proved, e.g. `'8-12'`).
+- `verifyCredential(event)`: `Promise<{ signatureValid: boolean; structureValid: boolean; expired: boolean; errors: string[] }>`
+- `parseCredential(event)`: `ParsedCredential | null`
+
+`ageRange` format everywhere: `'<min>-<max>'` inclusive (e.g. `'8-12'`, `'13-17'`) or `'<min>+'` (e.g. `'18+'`, upper bound 150). Anything else fails to parse.
+
+Default credential expiry is two years (`DEFAULT_CREDENTIAL_EXPIRY_SECONDS`) when `expiresAt` is omitted.
+
+### Vouches (kind 31000, type: vouch)
+- `createVouch(voucherPrivateKey, params)`: vouch for another user. `params: { subjectPubkey: string; method: 'in-person' | 'online'; voucherTier: SignetTier; voucherScore: number; context?: string; occurredAt?: number }`. `voucherScore` is the voucher's own Signet IQ (0–200).
+- `hasEnoughVouches(vouches, subjectPubkey, threshold = 3, minVoucherTier = 2)`: `boolean`. `true` when the number of qualifying vouches (one per voucher, voucher tier ≥ `minVoucherTier`) reaches `threshold`. `countQualifyingVouches(vouches, subjectPubkey, minVoucherTier?)` returns the count.
+
+### Trust & Badges
+- `computeBadge(pubkey, events, opts?)`: `Promise<BadgeInfo>`. `opts: { verifySignatures?: boolean (default false); now?: number }`. `BadgeInfo: { pubkey, tier, tierLabel, score, isVerified, displayLabel, credentialCount, vouchCount, entityType? }`.
+- `buildBadgeFilters(pubkeys: string[])`: `Array<{ kinds: number[]; '#d': string[] }>`. One filter for kind 31000 with d-tags `credential:<pubkey>` and `vouch:<pubkey>` for each pubkey.
+- `meetsMinimumTier(badge: BadgeInfo, minTier: SignetTier)`: `boolean`. `true` only when `badge.isVerified` and `badge.tier >= minTier`.
+- `computeTrustScore(subjectPubkey, credentials, vouches, accountCreatedAt?, bridges?)`: `TrustScoreBreakdown` (`{ score, tier, professionalVerifications, inPersonVouches, onlineVouches, accountAgeDays, signals }`). This is the full Signet IQ. It does not verify signatures.
+
+`badge.score` is on the same 0–200 scale and uses the same weights as `computeTrustScore(...).score` (professional verification 80, in-person vouch up to 16, online vouch up to 4, each vouch scaled by the voucher's score ÷ 200), but it is a Level 1 approximation, not the full IQ: `computeBadge` ignores account age and identity bridges and does not apply the per-type caps (1 professional, 3 in-person vouches, 5 online vouches). Use `computeTrustScore` when you need the full IQ.
+
+### Policies (kind 30078, NIP-78)
+- `createPolicy(operatorPrivateKey, params)`: community verification requirements. `params: { communityId: string; adultMinTier: SignetTier; childMinTier: SignetTier; enforcement: 'client' | 'relay' | 'both'; minScore?: number; modMinTier?: SignetTier; verifierBond?: number; revocationThreshold?: number; description?: string }`. The d-tag is `signet:policy:<communityId>`.
+- `new PolicyChecker(policyEvent: NostrEvent)`: throws `SignetValidationError('Invalid policy event')` if the event is not a valid policy. Methods: `getPolicy(): ParsedPolicy`, `checkAdult(tier, score)`, `checkChild(tier, score)`, `checkModerator(tier, score)`. Each check returns `PolicyCheckResult`: `{ allowed: boolean; reason?: string; requiredTier: SignetTier; actualTier: SignetTier; requiredScore?: number; actualScore?: number }`.
+- `parsePolicy(event)`: `ParsedPolicy | null`. `checkPolicyCompliance(policy, userTier, userScore, { isChild?, isModerator? })`: `PolicyCheckResult`.
+
+### Verifiers (kind 31000, type: verifier)
+- `createVerifierCredential(privateKey, params)`: register as professional verifier. `params: { profession: string; jurisdiction: string; licenceHash: string; professionalBody: string; statement?: string; bondProof?: BondProof }`.
+- `checkCrossVerification(verifierPubkey, vouches, verifierCredentials)`: activation check. Returns `{ activated: boolean; vouchCount: number; professions: string[]; errors: string[] }`.
+- `isVerifierRevoked(verifierPubkey, revocations)`: `boolean`
+
+### Challenges and Revocations (kind 31000, type: challenge / revocation)
+- `createChallenge(reporterPrivateKey, params)`: `Promise<NostrEvent>`. `params: { verifierPubkey: string; reason: 'anomalous-volume' | 'registry-mismatch' | 'fraudulent-attestation' | 'licence-revoked' | 'other'; evidenceType: string; reporterTier: SignetTier; evidence: string; occurredAt?: number }`. `evidence` becomes the event content.
+- `createRevocation(authorityPrivateKey, params)`: `Promise<NostrEvent>`. `params: { verifierPubkey: string; challengeEventId: string; confirmations: number; bondAction: 'slashed' | 'returned' | 'held'; scope: 'full' | 'partial'; effectiveAt: number; summary: string }`.
+- `countChallengeConfirmations(challengeEventId, confirmationEvents, credentialEvents)`: `number`
+- `hasReachedRevocationThreshold(confirmations, threshold = 5)`: `boolean`
+- `parseChallenge(event)` / `parseRevocation(event)`: parsed object or `null`.
+
+### Identity Bridge (kind 31000, type: identity-bridge)
+- `createIdentityBridge(anonPrivateKey, realPrivateKey, ring, signerIndex, ringMinTier, opts?)`: link anonymous account to verified identity via ring signature. `ring: string[]` of pubkeys (at least 5, `MIN_BRIDGE_RING_SIZE`); `opts: { occurredAt?: number }`. Signed by the anonymous key.
+- `selectDecoyRing(verifiedPubkeys, realPubkey, ringSize = 5)`: `{ ring: string[]; signerIndex: number }`
+- `verifyIdentityBridge(event, opts?)`: `Promise<boolean>`. `opts: { maxAgeSeconds?: number }` (default 24 hours; `0` disables the freshness check).
+
+### ZKP Age Proofs
+- `createAgeRangeProof(age: number, ageRange: string, subjectPubkey?: string)`: `RangeProof` (synchronous). `subjectPubkey` binds the proof to one credential.
+- `verifyAgeRangeProof(proof, expectedAgeRange, expectedSubjectPubkey?)`: `boolean`. Verify against the age policy you expect, not the range the proof claims.
+- `serializeRangeProof(proof): string` / `deserializeRangeProof(json: string): RangeProof`
+
+### Identity & Personas
+- `createSignetIdentity(mnemonic, passphrase?)` / `createSignetIdentityFromNsec(nsec: string | Uint8Array)`: derive a master identity. Both return `SignetIdentity` (`{ root, naturalPerson, persona, mnemonic? }`) with natural-person and persona sub-identities.
+- `deriveAdditionalPersona(root, name, index = 0)`: further `Persona`. `deriveDependantIdentity(root, dependantIndex)`: `DependantIdentity` (`{ derivationPath, naturalPerson, persona }`) for a child.
+- `createLinkageProof(root, child, type: 'blind' | 'full')` / `verifyLinkageProof(proof)` (returns `boolean`): prove or verify that a child identity belongs to a root.
+- `destroyIdentity(identity)`: zeroes the root and persona keys.
+- nsec-tree's own `fromMnemonic` / `fromNsec` are not re-exported; this package wraps them as the two `createSignetIdentity*` functions. `derive` and `zeroise` are re-exported.
+
+### Guardian Delegation
+- `createGuardianDelegation(guardianPrivateKey, params)`: kind 31000 (type: delegation) event scoping a guardian's authority over a dependant. `params: { childPubkey: string; delegatePubkey: string; scope: 'full' | 'activity-approval' | 'content-management' | 'contact-approval'; expiresAt?: number; occurredAt?: number }`.
+
+### signet-protocol/experimental (unstable)
+
+Import from `signet-protocol/experimental`. Nothing here is exported from the package root. These are unreleased draft contracts under protocol review: any export may change or be removed in any release, including a minor or patch, with no deprecation period. Do not depend on them for production data.
+
+- Private vault keys (see `docs/private-vault-v1.md`): `vaultPurpose`, `parseVaultPurpose`, `vaultKeyContext`, `deriveVaultIdentity`, `vaultIdentityFromMnemonic`; type `VaultDataset`.
+- Private vault checkpoints: `VAULT_EVENT_KIND`, `MAX_VAULT_CHUNKS`, `MAX_VAULT_DEVICES`, `MAX_VAULT_CONTROL_BYTES`, `MAX_VAULT_CHUNK_BYTES`, `vaultCheckpointTag`, `vaultContentHash`, `parseVaultCheckpoint`, `matchesVaultChunk`, `vaultCheckpointShapedTag`; types `VaultCheckpoint`, `VaultChunkRef`.
+- Private vault recovery: `readVaultSnapshot`, `readVaultRotations`, `readVaultHeads`, `readVaultHeadRotations`, `VAULT_CLOCK_TOLERANCE_SECONDS`; types `VaultReadResult`, `VaultReader`, `VaultHeadsResult`.
+- Private vault relay reads: `createVaultRelayReader`, `fetchVaultEvents`, `MAX_VAULT_EVENTS_PER_RELAY`, `VaultRelayError`.
+- Bot ownership profile (see `docs/bot-ownership-v1.md`): `BOT_OWNERSHIP_TYPE`, `BOT_OWNERSHIP_POLICY`, `buildBotOwnership`, `buildBotOwnershipRevocation`, `readBotOwnership`, `readBotOwnershipSync`, `botOwnershipRenewalDue`; types `BotOwnershipClaim`, `BotOwnershipResult`.
+
+The voting extension (kinds 30482–30484) is specified in `spec/voting.md` and implemented in the separate `nostr-anon-vote` package on npm, not in `signet-protocol`.
+
+## Optional
+
+- [llms-full.txt](llms-full.txt): llms.txt plus the full protocol and voting specifications and the developer guides in one file
+- [Full protocol specification](spec/protocol.md)
+- [Voting extension specification](spec/voting.md)
+- [Signet in 5 Minutes: developer overview](docs/signet-in-5-minutes.md)
+- [Implementation levels guide](docs/implementation-levels.md)
+- [Full flow example](examples/full-flow.ts)
+- [Jurisdiction-specific examples](examples/jurisdictions/)
+- [Regulatory compatibility](README.md#regulatory-compatibility)

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "signet-protocol",
-  "version": "1.10.1",
+  "version": "1.11.1",
   "description": "Decentralised identity verification protocol for Nostr",
+  "homepage": "https://github.com/forgesworn/signet#readme",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -9,11 +10,17 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./experimental": {
+      "import": "./dist/experimental.js",
+      "types": "./dist/experimental.d.ts"
     }
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "publishConfig": {
     "provenance": true
@@ -25,7 +32,9 @@
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
     "prepare": "npm run build",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+    "build:llms": "node scripts/build-llms-full.mjs",
+    "check:llms": "node scripts/build-llms-full.mjs --check",
+    "prepublishOnly": "npm run build:llms && npm run typecheck && npm test && npm run build"
   },
   "keywords": [
     "nostr",
@@ -55,20 +64,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() }
+}