nostr-bray 0.0.0-development

package/dist/trust/handlers.js

@@ -0,0 +1,133 @@
+import { createAttestation, createRevocation } from 'nostr-attestations';
+import { validateAttestation } from 'nostr-attestations';
+import { attestationFilter } from 'nostr-attestations';
+import { wrapEvent } from 'nostr-tools/nip17';
+import { toUnsignedEvent } from 'nsec-tree/event';
+import { decode } from 'nostr-tools/nip19';
+/** Create and publish a kind 31000 attestation */
+export async function handleTrustAttest(ctx, pool, args) {
+    const template = createAttestation({
+        type: args.type,
+        identifier: args.identifier,
+        subject: args.subject,
+        summary: args.summary,
+        content: args.content,
+        expiration: args.expiration,
+    });
+    const sign = ctx.getSigningFunction();
+    const event = await sign({
+        kind: template.kind,
+        created_at: template.created_at ?? Math.floor(Date.now() / 1000),
+        tags: template.tags,
+        content: template.content,
+    });
+    const publish = await pool.publish(ctx.activeNpub, event);
+    // Warn if attesting as a derived persona
+    const identities = ctx.listIdentities();
+    const active = identities.find(i => i.npub === ctx.activeNpub);
+    let warning;
+    if (active && active.purpose !== 'master') {
+        warning = `Attesting as derived identity (purpose: ${active.purpose}). Attestations are usually issued from the master identity.`;
+    }
+    return { event, publish, warning };
+}
+/** Read attestations from relays, filtered by subject/type/attestor */
+export async function handleTrustRead(pool, npub, args) {
+    const filter = attestationFilter({
+        subject: args.subject,
+        type: args.type,
+        authors: args.attestor ? [args.attestor] : undefined,
+    });
+    return pool.query(npub, filter);
+}
+/** Validate attestation event structure */
+export function handleTrustVerify(event) {
+    const result = validateAttestation(event);
+    return { valid: result.valid, errors: result.errors ?? [] };
+}
+/** Create and publish a revocation for an attestation */
+export async function handleTrustRevoke(ctx, pool, args) {
+    // Check that active identity matches the original attestor
+    if (args.originalAttestorPubkey) {
+        // Decode active npub to hex for comparison
+        const activeHex = decode(ctx.activeNpub).data;
+        if (args.originalAttestorPubkey !== activeHex) {
+            throw new Error(`Active identity does not match original attestor. Switch identity before revoking.`);
+        }
+    }
+    const template = createRevocation({
+        type: args.type,
+        identifier: args.identifier,
+    });
+    const sign = ctx.getSigningFunction();
+    const event = await sign({
+        kind: template.kind,
+        created_at: template.created_at ?? Math.floor(Date.now() / 1000),
+        tags: template.tags,
+        content: template.content,
+    });
+    const publish = await pool.publish(ctx.activeNpub, event);
+    return { event, publish };
+}
+// --- Task 14: Attestation request via NIP-17 ---
+const ATTESTATION_REQUEST_TYPE = 'nip-va/attestation-request';
+/** Send an attestation request as a NIP-17 structured DM */
+export async function handleTrustRequest(ctx, pool, args) {
+    const payload = JSON.stringify({
+        type: ATTESTATION_REQUEST_TYPE,
+        v: 1,
+        subject: args.subject,
+        attestation_type: args.attestationType,
+        message: args.message,
+    });
+    const event = wrapEvent(ctx.activePrivateKey, { publicKey: args.recipientPubkeyHex }, payload);
+    const publish = await pool.publish(ctx.activeNpub, event);
+    return { event, publish };
+}
+/** Scan NIP-17 DMs for attestation request payloads */
+export async function handleTrustRequestList(ctx, pool) {
+    const { handleDmRead } = await import('../social/dm.js');
+    const dms = await handleDmRead(ctx, pool);
+    const requests = [];
+    for (const dm of dms) {
+        if (!dm.decrypted || !dm.content)
+            continue;
+        try {
+            const payload = JSON.parse(dm.content);
+            if (payload.type === ATTESTATION_REQUEST_TYPE && payload.v === 1) {
+                requests.push({
+                    from: dm.from,
+                    subject: payload.subject,
+                    attestationType: payload.attestation_type,
+                    message: payload.message,
+                });
+            }
+        }
+        catch { /* not a structured DM */ }
+    }
+    return requests;
+}
+// --- Task 15: Linkage proof publishing ---
+/** Publish a linkage proof as a kind 30078 event. Requires confirmation. */
+export async function handleTrustProofPublish(ctx, pool, args) {
+    const proof = ctx.prove(args.mode ?? 'blind');
+    const reveals = args.mode === 'full'
+        ? `Full proof — reveals purpose "${proof.purpose}" and index ${proof.index}. This is irreversible.`
+        : 'Blind proof — reveals that child belongs to master, but NOT the derivation path.';
+    if (!args.confirm) {
+        return {
+            published: false,
+            warning: `About to publish linkage proof. ${reveals} Set confirm: true to proceed.`,
+        };
+    }
+    const unsigned = toUnsignedEvent(proof);
+    const sign = ctx.getSigningFunction();
+    const event = await sign({
+        kind: unsigned.kind,
+        created_at: unsigned.created_at,
+        tags: unsigned.tags,
+        content: unsigned.content,
+    });
+    const publish = await pool.publish(ctx.activeNpub, event);
+    return { event, published: true, publish };
+}

package/dist/trust/ring.d.ts

@@ -0,0 +1,19 @@
+import type { RingSignature } from '@forgesworn/ring-sig';
+import type { IdentityContext } from '../context.js';
+import type { RelayPool } from '../relay-pool.js';
+import type { PublishResult } from '../types.js';
+import type { Event as NostrEvent } from 'nostr-tools';
+/** Create a ring signature proving membership in a group */
+export declare function handleTrustRingProve(ctx: IdentityContext, pool: RelayPool, args: {
+    ring: string[];
+    attestationType: string;
+    message?: string;
+}): Promise<{
+    signature: RingSignature;
+    event: NostrEvent;
+    publish: PublishResult;
+}>;
+/** Verify a ring signature */
+export declare function handleTrustRingVerify(signatureOrEvent: RingSignature | NostrEvent): {
+    valid: boolean;
+};

package/dist/trust/ring.js

@@ -0,0 +1,54 @@
+import { ringSign, ringVerify } from '@forgesworn/ring-sig';
+/** Create a ring signature proving membership in a group */
+export async function handleTrustRingProve(ctx, pool, args) {
+    const createdAt = Math.floor(Date.now() / 1000);
+    const canonicalMessage = args.message ?? `ring-membership:${args.attestationType}:${createdAt}`;
+    // Find our index in the ring
+    const activeHex = (await import('nostr-tools/nip19')).decode(ctx.activeNpub).data;
+    const signerIndex = args.ring.indexOf(activeHex);
+    if (signerIndex === -1) {
+        throw new Error('Active identity not found in ring. Derive and switch to a matching identity first.');
+    }
+    // Get private key as hex — strings can't be zeroised, so limit scope
+    let privateKeyHex = Buffer.from(ctx.activePrivateKey).toString('hex');
+    let signature;
+    try {
+        signature = ringSign(canonicalMessage, args.ring, signerIndex, privateKeyHex);
+    }
+    finally {
+        privateKeyHex = ''; // remove reference; original string remains until GC
+    }
+    // Build kind 30078 event
+    const sign = ctx.getSigningFunction();
+    const msgHash = Buffer.from(signature.message, 'hex').toString('hex').slice(0, 16);
+    const tags = [
+        ['d', `ring-proof:${msgHash}`],
+        ['attestation-type', args.attestationType],
+        ...args.ring.map(pk => ['p', pk]),
+    ];
+    const event = await sign({
+        kind: 30078,
+        created_at: createdAt,
+        tags,
+        content: JSON.stringify(signature),
+    });
+    const publish = await pool.publish(ctx.activeNpub, event);
+    return { signature, event, publish };
+}
+/** Verify a ring signature */
+export function handleTrustRingVerify(signatureOrEvent) {
+    let sig;
+    if ('content' in signatureOrEvent && 'kind' in signatureOrEvent) {
+        // It's a Nostr event — parse the signature from content
+        try {
+            sig = JSON.parse(signatureOrEvent.content);
+        }
+        catch {
+            return { valid: false };
+        }
+    }
+    else {
+        sig = signatureOrEvent;
+    }
+    return { valid: ringVerify(sig) };
+}

package/dist/trust/spoken.d.ts

@@ -0,0 +1,33 @@
+/** Generate a challenge token for spoken verification */
+export declare function handleTrustSpokenChallenge(args: {
+    secret: string;
+    context: string;
+    counter: number;
+    encoding?: {
+        format: 'words';
+        count?: number;
+    } | {
+        format: 'pin';
+        digits?: number;
+    };
+}): {
+    token: string;
+};
+/** Verify a spoken token response */
+export declare function handleTrustSpokenVerify(args: {
+    secret: string;
+    context: string;
+    counter: number;
+    input: string;
+    tolerance?: number;
+    encoding?: {
+        format: 'words';
+        count?: number;
+    } | {
+        format: 'pin';
+        digits?: number;
+    };
+}): {
+    valid: boolean;
+    identity?: string;
+};

package/dist/trust/spoken.js

@@ -0,0 +1,14 @@
+import { deriveToken, verifyToken } from 'spoken-token';
+/** Generate a challenge token for spoken verification */
+export function handleTrustSpokenChallenge(args) {
+    const token = deriveToken(args.secret, args.context, args.counter, args.encoding);
+    return { token };
+}
+/** Verify a spoken token response */
+export function handleTrustSpokenVerify(args) {
+    const result = verifyToken(args.secret, args.context, args.counter, args.input, undefined, {
+        tolerance: args.tolerance ?? 1,
+        encoding: args.encoding,
+    });
+    return { valid: result.status === 'valid', identity: result.identity };
+}

package/dist/trust/tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolDeps } from '../identity/tools.js';
+export declare function registerTrustTools(server: McpServer, deps: ToolDeps): void;

package/dist/trust/tools.js

@@ -0,0 +1,182 @@
+import { z } from 'zod';
+import { hexId } from '../validation.js';
+import { handleTrustAttest, handleTrustRead, handleTrustVerify, handleTrustRevoke, handleTrustRequest, handleTrustRequestList, handleTrustProofPublish, } from './handlers.js';
+import { handleTrustRingProve, handleTrustRingVerify } from './ring.js';
+import { handleTrustSpokenChallenge, handleTrustSpokenVerify } from './spoken.js';
+export function registerTrustTools(server, deps) {
+    server.registerTool('trust_attest', {
+        description: 'Create and publish a kind 31000 verifiable attestation as the active identity.',
+        inputSchema: {
+            type: z.string().describe('Attestation type (e.g. "identity-verification", "endorsement")'),
+            identifier: z.string().optional().describe('D-tag identifier (hex pubkey or context string)'),
+            subject: z.string().optional().describe('Subject hex pubkey (for third-party attestations)'),
+            summary: z.string().optional().describe('Human-readable summary'),
+            content: z.string().optional().describe('Event content (text or JSON)'),
+            expiration: z.number().optional().describe('Unix timestamp for attestation expiry'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ type, identifier, subject, summary, content, expiration }) => {
+        const result = await handleTrustAttest(deps.ctx, deps.pool, {
+            type, identifier, subject, summary, content, expiration,
+        });
+        const response = {
+            id: result.event.id,
+            publish: result.publish,
+        };
+        if (result.warning)
+            response.warning = result.warning;
+        return {
+            content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
+        };
+    });
+    server.registerTool('trust_read', {
+        description: 'Read kind 31000 attestations from relays. Filter by subject, type, or attestor.',
+        inputSchema: {
+            subject: hexId.optional().describe('Subject hex pubkey to filter by'),
+            type: z.string().optional().describe('Attestation type to filter by'),
+            attestor: hexId.optional().describe('Attestor hex pubkey to filter by'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ subject, type, attestor }) => {
+        const events = await handleTrustRead(deps.pool, deps.ctx.activeNpub, { subject, type, attestor });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(events.map(e => ({
+                        id: e.id,
+                        pubkey: e.pubkey,
+                        kind: e.kind,
+                        tags: e.tags,
+                        content: e.content,
+                        created_at: e.created_at,
+                    })), null, 2) }],
+        };
+    });
+    server.registerTool('trust_verify', {
+        description: 'Validate the structural correctness of a kind 31000 attestation event.',
+        inputSchema: {
+            event: z.record(z.string(), z.unknown()).describe('The attestation event object to validate'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ event }) => {
+        const result = handleTrustVerify(event);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    server.registerTool('trust_revoke', {
+        description: 'Revoke a previously issued attestation. Active identity must match the original attestor.',
+        inputSchema: {
+            type: z.string().describe('Attestation type being revoked'),
+            identifier: z.string().describe('D-tag identifier of the attestation'),
+            originalAttestorPubkey: z.string().optional().describe('Hex pubkey of the original attestor (for verification)'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ type, identifier, originalAttestorPubkey }) => {
+        const result = await handleTrustRevoke(deps.ctx, deps.pool, {
+            type, identifier, originalAttestorPubkey,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify({
+                        id: result.event.id,
+                        publish: result.publish,
+                    }, null, 2) }],
+        };
+    });
+    server.registerTool('trust_request', {
+        description: 'Send an attestation request to another Nostr identity via NIP-17 encrypted DM.',
+        inputSchema: {
+            recipientPubkeyHex: hexId.describe('Hex pubkey of the attestor you are requesting from'),
+            subject: hexId.describe('Hex pubkey of the subject to be attested'),
+            attestationType: z.string().describe('Type of attestation requested'),
+            message: z.string().optional().describe('Optional message explaining the request'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ recipientPubkeyHex, subject, attestationType, message }) => {
+        const result = await handleTrustRequest(deps.ctx, deps.pool, {
+            recipientPubkeyHex, subject, attestationType, message,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ id: result.event.id, publish: result.publish }, null, 2) }],
+        };
+    });
+    server.registerTool('trust_request_list', {
+        description: 'Scan received NIP-17 DMs for attestation request payloads.',
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        const requests = await handleTrustRequestList(deps.ctx, deps.pool);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(requests, null, 2) }],
+        };
+    });
+    server.registerTool('trust_proof_publish', {
+        description: 'Publish a cryptographic linkage proof as a kind 30078 event. Requires confirmation — this is irreversible.',
+        inputSchema: {
+            mode: z.enum(['blind', 'full']).default('blind').describe('Proof mode: blind hides derivation path, full reveals it'),
+            confirm: z.boolean().default(false).describe('Set true to publish (irreversible)'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ mode, confirm }) => {
+        const result = await handleTrustProofPublish(deps.ctx, deps.pool, { mode, confirm });
+        if (!result.published) {
+            return { content: [{ type: 'text', text: JSON.stringify({ warning: result.warning }, null, 2) }] };
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ id: result.event.id, published: true }, null, 2) }],
+        };
+    });
+    server.registerTool('trust_ring_prove', {
+        description: 'Create a ring signature proving anonymous membership in a group of public keys.',
+        inputSchema: {
+            ring: z.array(hexId).describe('Hex x-only public keys of ring members (must include active identity)'),
+            attestationType: z.string().describe('Attestation type context for the canonical message'),
+            message: z.string().optional().describe('Custom message to sign (defaults to canonical format)'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ ring, attestationType, message }) => {
+        const result = await handleTrustRingProve(deps.ctx, deps.pool, { ring, attestationType, message });
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ id: result.event.id, ringSize: ring.length }, null, 2) }],
+        };
+    });
+    server.registerTool('trust_ring_verify', {
+        description: 'Verify a ring signature proof.',
+        inputSchema: {
+            signature: z.record(z.string(), z.unknown()).describe('Ring signature object or Nostr event containing one'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ signature }) => {
+        const result = handleTrustRingVerify(signature);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    server.registerTool('trust_spoken_challenge', {
+        description: 'Generate a spoken verification token for in-person identity confirmation.',
+        inputSchema: {
+            secret: z.string().regex(/^[0-9a-f]{32,}$/, 'Hex string, min 32 chars').describe('Shared secret'),
+            context: z.string().describe('Context string for domain separation'),
+            counter: z.number().int().describe('Time-based or usage counter'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ secret, context, counter }) => {
+        const result = handleTrustSpokenChallenge({ secret, context, counter });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    server.registerTool('trust_spoken_verify', {
+        description: 'Verify a spoken token response against the shared secret.',
+        inputSchema: {
+            secret: z.string().regex(/^[0-9a-f]{32,}$/, 'Hex string, min 32 chars').describe('Shared secret'),
+            context: z.string().describe('Context string used during challenge'),
+            counter: z.number().int().describe('Current counter value'),
+            input: z.string().describe('The spoken/entered token to verify'),
+            tolerance: z.number().int().min(0).max(10).default(1).describe('Counter tolerance window (default 1)'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ secret, context, counter, input, tolerance }) => {
+        const result = handleTrustSpokenVerify({ secret, context, counter, input, tolerance });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+import type { Event as NostrEvent, EventTemplate } from 'nostr-tools';
+/** Public identity info returned by tools — never includes private keys */
+export interface PublicIdentity {
+    readonly npub: string;
+    readonly purpose?: string;
+    readonly index?: number;
+    readonly personaName?: string;
+}
+/** Snapshot of an identity's replaceable events from relays */
+export interface IdentitySnapshot {
+    profile?: NostrEvent;
+    contacts?: NostrEvent;
+    relayList?: NostrEvent;
+}
+/** Signing function — signs an event template, returns signed event */
+export type SignFn = (template: EventTemplate) => Promise<NostrEvent>;
+/** Relay set with read/write separation */
+export interface RelaySet {
+    read: string[];
+    write: string[];
+}
+/** Result of a publish operation */
+export interface PublishResult {
+    success: boolean;
+    accepted: string[];
+    rejected: string[];
+    errors: string[];
+}
+/** Parsed configuration */
+export interface BrayConfig {
+    readonly secretKey: string;
+    readonly secretFormat: 'nsec' | 'hex' | 'mnemonic';
+    readonly relays: string[];
+    readonly nwcUri?: string;
+    readonly torProxy?: string;
+    readonly allowClearnetWithTor: boolean;
+    readonly nip04Enabled: boolean;
+    readonly transport: 'stdio' | 'http';
+    readonly port: number;
+    readonly bindAddress: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+/** 64-character lowercase hex string (pubkey or event ID) */
+export declare const hexId: z.ZodString;
+/** Relay WebSocket URL — wss:// or ws:// only */
+export declare const relayUrl: z.ZodString;

package/dist/validation.js

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+/** 64-character lowercase hex string (pubkey or event ID) */
+export const hexId = z.string().regex(/^[0-9a-f]{64}$/, 'Must be a 64-character hex string');
+/** Relay WebSocket URL — wss:// or ws:// only */
+export const relayUrl = z.string().regex(/^wss?:\/\//, 'Must be a wss:// or ws:// URL');

package/dist/zap/handlers.d.ts

@@ -0,0 +1,80 @@
+import type { Event as NostrEvent } from 'nostr-tools';
+import type { IdentityContext } from '../context.js';
+import type { RelayPool } from '../relay-pool.js';
+import type { PublishResult } from '../types.js';
+export interface NwcConnection {
+    pubkey: string;
+    relay: string;
+    secret: string;
+}
+/** Parse a nostr+walletconnect:// URI */
+export declare function parseNwcUri(uri: string): NwcConnection;
+export interface ZapReceipt {
+    id: string;
+    sender?: string;
+    amountMsats?: number;
+    message?: string;
+    createdAt: number;
+}
+/** Parse zap receipts (kind 9735) for the active identity */
+export declare function handleZapReceipts(ctx: IdentityContext, pool: RelayPool, opts?: {
+    since?: number;
+    limit?: number;
+}): Promise<ZapReceipt[]>;
+/** Decode basic bolt11 invoice fields */
+export declare function handleZapDecode(bolt11: string): {
+    amountMsats?: number;
+    description?: string;
+    expiry?: number;
+};
+/** Pay a Lightning invoice via NWC */
+export declare function handleZapSend(ctx: IdentityContext, pool: RelayPool, args: {
+    invoice: string;
+    nwcUri?: string;
+}): Promise<{
+    event: NostrEvent;
+    publish: PublishResult;
+}>;
+/** Request wallet balance via NWC */
+export declare function handleZapBalance(ctx: IdentityContext, pool: RelayPool, args: {
+    nwcUri?: string;
+}): Promise<{
+    event: NostrEvent;
+    publish: PublishResult;
+}>;
+/** Generate a Lightning invoice via NWC */
+export declare function handleZapMakeInvoice(ctx: IdentityContext, pool: RelayPool, args: {
+    amountMsats: number;
+    description?: string;
+    nwcUri?: string;
+}): Promise<{
+    event: NostrEvent;
+    publish: PublishResult;
+}>;
+/** Look up an invoice via NWC */
+export declare function handleZapLookupInvoice(ctx: IdentityContext, pool: RelayPool, args: {
+    paymentHash?: string;
+    invoice?: string;
+    nwcUri?: string;
+}): Promise<{
+    event: NostrEvent;
+    publish: PublishResult;
+}>;
+/** List recent transactions via NWC */
+export declare function handleZapListTransactions(ctx: IdentityContext, pool: RelayPool, args: {
+    limit?: number;
+    offset?: number;
+    nwcUri?: string;
+}): Promise<{
+    event: NostrEvent;
+    publish: PublishResult;
+}>;
+/** Parse a NWC wallet response event */
+export declare function handleZapParseResponse(nwcUri: string, event: NostrEvent): {
+    result_type: string;
+    result?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+    };
+};