signet-protocol 1.0.0 → 1.2.0

package/src/signet-me.ts

@@ -0,0 +1,104 @@
+/**
+ * Signet Me — Directional verification using spoken-token.
+ *
+ * Each person gets a DIFFERENT word. Prevents the echo attack.
+ * Uses spoken-token's deriveDirectionalPair for domain-separated,
+ * time-windowed verification words.
+ */
+
+import { deriveDirectionalPair } from 'spoken-token';
+import type { TokenEncoding } from 'spoken-token/encoding';
+import { WORDLIST } from 'spoken-token/wordlist';
+
+const SIGNET_ME_NAMESPACE = 'signet:me';
+
+/** Default rotation period in seconds. */
+export const SIGNET_ME_ROTATION_SECONDS = 30;
+
+/** Default tolerance in epochs (±1 for clock skew). */
+export const SIGNET_ME_TOLERANCE = 1;
+
+export interface SignetMeDisplay {
+  /** Words I say to prove it's me */
+  myWords: string[];
+  /** Words I expect to hear from them */
+  theirWords: string[];
+  /** Seconds until words refresh */
+  expiresIn: number;
+}
+
+function getCounter(nowMs: number, rotationSeconds: number): number {
+  return Math.floor(nowMs / 1000 / rotationSeconds);
+}
+
+function makeEncoding(wordCount: number): TokenEncoding {
+  return { format: 'words', count: wordCount, wordlist: WORDLIST };
+}
+
+/**
+ * Get directional words for a Signet Me verification.
+ * Each side sees different words — I say mine, they say theirs.
+ */
+export function getSignetMeDisplay(
+  sharedSecret: string,
+  myPubkey: string,
+  theirPubkey: string,
+  wordCount: number = 1,
+  nowMs?: number,
+): SignetMeDisplay {
+  const now = nowMs ?? Date.now();
+  const counter = getCounter(now, SIGNET_ME_ROTATION_SECONDS);
+  const encoding = makeEncoding(wordCount);
+
+  const pair = deriveDirectionalPair(
+    sharedSecret,
+    SIGNET_ME_NAMESPACE,
+    [myPubkey, theirPubkey],
+    counter,
+    encoding,
+  );
+
+  const myWords = pair[myPubkey].split(' ');
+  const theirWords = pair[theirPubkey].split(' ');
+
+  const epochMs = SIGNET_ME_ROTATION_SECONDS * 1000;
+  const msIntoEpoch = now % epochMs;
+  const expiresIn = Math.ceil((epochMs - msIntoEpoch) / 1000);
+
+  return { myWords, theirWords, expiresIn };
+}
+
+/**
+ * Verify that the spoken words match what the other person should say.
+ * Checks current counter ±tolerance for clock skew.
+ */
+export function verifySignetMe(
+  sharedSecret: string,
+  myPubkey: string,
+  theirPubkey: string,
+  spokenWords: string[],
+  wordCount: number = 1,
+  nowMs?: number,
+): boolean {
+  const now = nowMs ?? Date.now();
+  const currentCounter = getCounter(now, SIGNET_ME_ROTATION_SECONDS);
+  const encoding = makeEncoding(wordCount);
+  const spokenJoined = spokenWords.map(w => w.toLowerCase().trim()).join(' ');
+
+  for (let offset = -SIGNET_ME_TOLERANCE; offset <= SIGNET_ME_TOLERANCE; offset++) {
+    const pair = deriveDirectionalPair(
+      sharedSecret,
+      SIGNET_ME_NAMESPACE,
+      [myPubkey, theirPubkey],
+      currentCounter + offset,
+      encoding,
+    );
+
+    // I'm verifying THEIR word — what they should say to me
+    if (pair[theirPubkey] === spokenJoined) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/signing-backend.ts

@@ -0,0 +1,29 @@
+/**
+ * Signing Backend Interface
+ *
+ * Defines the abstract SigningBackend interface that all signing
+ * implementations must conform to. Concrete implementations live
+ * in the consuming application (LocalSigningBackend, BunkerSigningBackend,
+ * Nip07SigningBackend) because they depend on app-level NIP-44 encryption.
+ */
+
+import type { NostrEvent, UnsignedEvent } from './types.js';
+
+/** Signing mode for backend type discrimination. */
+export type SigningMode = 'local' | 'bunker' | 'nip07';
+
+/**
+ * Abstract signing backend interface.
+ *
+ * All signing operations go through this interface. The protocol library
+ * defines the contract; the application provides concrete implementations.
+ */
+export interface SigningBackend {
+  readonly type: SigningMode;
+  activePublicKeyHex: string;
+
+  signEvent(event: UnsignedEvent): Promise<NostrEvent>;
+  nip44Encrypt(recipientPubkey: string, plaintext: string): Promise<string>;
+
+  destroy(): void;
+}

package/src/trust-score.ts

@@ -1,7 +1,7 @@
 // Signet Score Computation
 // Continuous 0-200 Signet Score from weighted signals
 
-import { TRUST_WEIGHTS, MAX_TRUST_SCORE, ATTESTATION_KIND, ATTESTATION_TYPES } from './constants.js';
+import { TRUST_WEIGHTS, TRUST_CAPS, MAX_TRUST_SCORE, ATTESTATION_KIND, ATTESTATION_TYPES } from './constants.js';
 import { getTagValue } from './validation.js';
 import type {
   NostrEvent,
@@ -54,13 +54,15 @@ export function computeTrustScore(
     const verificationType = getTagValue(cred, 'verification-type');
     if (verificationType === 'professional') {
       professionalVerifications++;
-      const weight = TRUST_WEIGHTS.PROFESSIONAL_VERIFICATION;
-      rawScore += weight;
-      signals.push({
-        type: 'professional-verification',
-        weight,
-        source: cred.pubkey,
-      });
+      if (professionalVerifications <= TRUST_CAPS.PROFESSIONAL_VERIFICATION) {
+        const weight = TRUST_WEIGHTS.PROFESSIONAL_VERIFICATION;
+        rawScore += weight;
+        signals.push({
+          type: 'professional-verification',
+          weight,
+          source: cred.pubkey,
+        });
+      }
     }
   }
 
@@ -84,24 +86,28 @@ export function computeTrustScore(
 
     if (method === 'in-person') {
       inPersonVouches++;
-      const weight = TRUST_WEIGHTS.IN_PERSON_VOUCH * scoreMultiplier;
-      rawScore += weight;
-      signals.push({
-        type: 'in-person-vouch',
-        weight,
-        source: vouch.pubkey,
-        score: voucherScore,
-      });
+      if (inPersonVouches <= TRUST_CAPS.IN_PERSON_VOUCH) {
+        const weight = TRUST_WEIGHTS.IN_PERSON_VOUCH * scoreMultiplier;
+        rawScore += weight;
+        signals.push({
+          type: 'in-person-vouch',
+          weight,
+          source: vouch.pubkey,
+          score: voucherScore,
+        });
+      }
     } else {
       onlineVouches++;
-      const weight = TRUST_WEIGHTS.ONLINE_VOUCH * scoreMultiplier;
-      rawScore += weight;
-      signals.push({
-        type: 'online-vouch',
-        weight,
-        source: vouch.pubkey,
-        score: voucherScore,
-      });
+      if (onlineVouches <= TRUST_CAPS.ONLINE_VOUCH) {
+        const weight = TRUST_WEIGHTS.ONLINE_VOUCH * scoreMultiplier;
+        rawScore += weight;
+        signals.push({
+          type: 'online-vouch',
+          weight,
+          source: vouch.pubkey,
+          score: voucherScore,
+        });
+      }
     }
   }
 

package/src/url-auth.ts

@@ -0,0 +1,115 @@
+/**
+ * URL-based authentication for "Sign in with Signet" redirect flow.
+ *
+ * External websites redirect to the Signet app with URL params containing
+ * a challenge, origin, callback, and site name. The app signs the challenge
+ * and redirects back with the signature.
+ */
+
+import type { LoginRequest } from './qr-router.js';
+
+/** Check if a URL is https:// or http://localhost (dev). */
+function isValidAuthUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol === 'https:') return true;
+    if (parsed.protocol === 'http:' && (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1')) return true;
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Parse URL auth params from a query string (e.g. window.location.search).
+ * Returns a LoginRequest compatible with the approval flow,
+ * or null if params are missing/invalid.
+ */
+export function parseUrlAuthParams(search: string): LoginRequest | null {
+  const params = new URLSearchParams(search);
+  if (params.get('auth') !== '1') return null;
+
+  const challenge = params.get('challenge');
+  const origin = params.get('origin');
+  const name = params.get('name');
+  const callback = params.get('callback');
+
+  // All four params required
+  if (!challenge || !origin || !name || !callback) return null;
+
+  // Challenge must be 64 hex chars (normalize to lowercase)
+  if (!/^[0-9a-f]{64}$/i.test(challenge)) return null;
+  const normalizedChallenge = challenge.toLowerCase();
+
+  // Name must be non-empty, max 64 chars
+  if (name.length === 0 || name.length > 64) return null;
+
+  // Origin must be https:// (or http://localhost for dev)
+  if (!isValidAuthUrl(origin)) return null;
+
+  // Callback must be https:// (or http://localhost for dev)
+  if (!isValidAuthUrl(callback)) return null;
+
+  // Callback origin must match origin param (prevent open redirect)
+  try {
+    const callbackOrigin = new URL(callback).origin;
+    const requestOrigin = new URL(origin).origin;
+    if (callbackOrigin !== requestOrigin) return null;
+  } catch {
+    return null;
+  }
+
+  const timestampParam = params.get('t') || params.get('timestamp');
+  if (!timestampParam) return null; // timestamp required for replay protection
+  const timestamp = parseInt(timestampParam, 10);
+  if (isNaN(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) return null;
+
+  return {
+    type: 'signet-login-request',
+    requestId: normalizedChallenge, // use challenge as requestId for URL auth
+    challenge: normalizedChallenge,
+    origin,
+    callbackUrl: callback,
+    timestamp,
+  };
+}
+
+/**
+ * Build the callback redirect URL after successful auth.
+ * Uses the URL API to safely append params (no string concatenation).
+ */
+export function buildAuthCallbackUrl(
+  callbackUrl: string,
+  pubkey: string,
+  npub: string,
+  signature: string,
+  eventId: string,
+): string {
+  if (!isValidAuthUrl(callbackUrl)) throw new Error('Invalid callback URL scheme');
+  const url = new URL(callbackUrl);
+  url.searchParams.set('pubkey', pubkey);
+  url.searchParams.set('npub', npub);
+  url.searchParams.set('signature', signature);
+  url.searchParams.set('eventId', eventId);
+  return url.toString();
+}
+
+/**
+ * Build the callback redirect URL for a denied auth request.
+ */
+export function buildAuthDeniedUrl(callbackUrl: string): string {
+  if (!isValidAuthUrl(callbackUrl)) throw new Error('Invalid callback URL scheme');
+  const url = new URL(callbackUrl);
+  url.searchParams.set('error', 'denied');
+  return url.toString();
+}
+
+/**
+ * Extract and sanitise the site name from URL auth params.
+ * Strips control characters and bidirectional text markers, caps at 64 chars.
+ */
+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);
+}

package/src/venue-entry.ts

@@ -0,0 +1,49 @@
+/**
+ * Venue Entry Event Builder (kind 21235)
+ *
+ * Builds unsigned venue entry events for physical venue scanning.
+ * The event is a self-contained, signed QR payload verifiable via
+ * standard NIP-01 signature verification.
+ *
+ * Kind 21235 is in the ephemeral range. The consuming application
+ * signs the event and renders it as a QR code.
+ */
+
+import type { UnsignedEvent } from './types.js';
+
+/** Venue entry event kind (ephemeral range). */
+export const VENUE_ENTRY_KIND = 21235;
+
+/**
+ * Build an unsigned venue entry event template.
+ * The caller must sign this before rendering as a QR code.
+ *
+ * @param pubkey - The natural person's hex public key.
+ * @param photoHash - Optional SHA-256 hash of the uploaded photo.
+ * @param blossomUrl - Optional Blossom server URL where the photo is hosted.
+ */
+export function buildVenueEntryEventTemplate(
+  pubkey: string,
+  photoHash?: string,
+  blossomUrl?: string,
+): UnsignedEvent {
+  const tags: string[][] = [['t', 'signet-venue-entry']];
+
+  if (photoHash) {
+    tags.push(['x', photoHash]);
+  }
+
+  if (blossomUrl && photoHash) {
+    if (/^https:\/\//i.test(blossomUrl) || /^http:\/\/(localhost|127\.0\.0\.1)([:\/]|$)/i.test(blossomUrl)) {
+      tags.push(['blossom', blossomUrl]);
+    }
+  }
+
+  return {
+    pubkey,
+    kind: VENUE_ENTRY_KIND,
+    created_at: Math.floor(Date.now() / 1000),
+    tags,
+    content: '',
+  };
+}