feat: implement @nse-dev/core types + @nse-dev/server with full test suite

Core (9 tests): NSEProvider interface, NSEEvent/NSESignedEvent/NSEKeyInfo
types aligned with nostr-crypto-utils, NSEEncryptedBlob format, NSEError
with error codes, NSEStorage interface.

Server (23 tests): NSEServer using nostr-crypto-utils for Schnorr signing,
AES-256-GCM key wrapping via @noble/hashes, generate/sign/verify round-trip,
memory zeroing, wrong-key rejection, NSEMemoryStorage for testing.

Note: uses signEvent instead of finalizeEvent to avoid kind 0 falsy bug
in nostr-crypto-utils (event.kind || 1 treats 0 as falsy).

Author: vveerrgg

platforms/core/package-lock.json

@@ -0,0 +1,39 @@
+{
+  "name": "@nse-dev/core",
+  "version": "0.1.0",
+  "description": "Shared types for Nostr Secure Enclave — hardware-backed key management for Nostr",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": ["nostr", "secure-enclave", "key-management", "hardware-security"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HumanjavaEnterprises/nse-dev.web.landingpage.src",
+    "directory": "platforms/core"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.0"
+  },
+  "peerDependencies": {
+    "nostr-crypto-utils": "^0.7.0"
+  },
+  "peerDependenciesMeta": {
+    "nostr-crypto-utils": {
+      "optional": true
+    }
+  }
+}

platforms/core/package.json

@@ -0,0 +1,130 @@
+import { describe, it, expect } from 'vitest';
+import { NSEError, NSEErrorCode } from './index.js';
+import type {
+  NSEEvent,
+  NSESignedEvent,
+  NSEKeyInfo,
+  NSEProvider,
+  NSEStorage,
+  NSEEncryptedBlob,
+} from './index.js';
+
+describe('@nse-dev/core types', () => {
+  it('NSEEvent is compatible with nostr-crypto-utils BaseNostrEvent', () => {
+    const event: NSEEvent = {
+      kind: 1,
+      content: 'hello nostr',
+      tags: [['p', 'abc123']],
+      created_at: Math.floor(Date.now() / 1000),
+    };
+    expect(event.kind).toBe(1);
+    expect(event.content).toBe('hello nostr');
+    expect(event.tags).toHaveLength(1);
+    expect(typeof event.created_at).toBe('number');
+  });
+
+  it('NSEEvent accepts optional pubkey', () => {
+    const event: NSEEvent = {
+      kind: 0,
+      content: '{}',
+      tags: [],
+      created_at: 1710000000,
+      pubkey: 'aabbccdd'.repeat(8),
+    };
+    expect(event.pubkey).toHaveLength(64);
+  });
+
+  it('NSESignedEvent has all required fields', () => {
+    const signed: NSESignedEvent = {
+      id: 'a'.repeat(64),
+      pubkey: 'b'.repeat(64),
+      sig: 'c'.repeat(128),
+      kind: 1,
+      content: 'test',
+      tags: [],
+      created_at: 1710000000,
+    };
+    expect(signed.id).toHaveLength(64);
+    expect(signed.pubkey).toHaveLength(64);
+    expect(signed.sig).toHaveLength(128);
+  });
+
+  it('NSEKeyInfo includes hardware_backed flag', () => {
+    const info: NSEKeyInfo = {
+      pubkey: 'a'.repeat(64),
+      npub: 'npub1' + 'x'.repeat(58),
+      created_at: 1710000000,
+      hardware_backed: true,
+    };
+    expect(info.hardware_backed).toBe(true);
+  });
+
+  it('NSEEncryptedBlob has version 1', () => {
+    const blob: NSEEncryptedBlob = {
+      version: 1,
+      ciphertext: 'base64encoded==',
+      iv: 'aWluaXR2ZWN0',
+      pubkey: 'a'.repeat(64),
+      npub: 'npub1' + 'x'.repeat(58),
+      created_at: 1710000000,
+      hardware_backed: true,
+    };
+    expect(blob.version).toBe(1);
+  });
+
+  it('NSEError carries error code', () => {
+    const err = new NSEError('No key found', NSEErrorCode.KEY_NOT_FOUND);
+    expect(err.message).toBe('No key found');
+    expect(err.code).toBe('KEY_NOT_FOUND');
+    expect(err.name).toBe('NSEError');
+    expect(err instanceof Error).toBe(true);
+  });
+
+  it('NSEErrorCode has all expected codes', () => {
+    const codes = Object.values(NSEErrorCode);
+    expect(codes).toContain('KEY_NOT_FOUND');
+    expect(codes).toContain('AUTH_FAILED');
+    expect(codes).toContain('HARDWARE_UNAVAILABLE');
+    expect(codes).toContain('KEY_EXISTS');
+    expect(codes).toContain('DECRYPTION_FAILED');
+    expect(codes).toContain('STORAGE_ERROR');
+    expect(codes).toContain('SIGN_FAILED');
+    expect(codes).toHaveLength(7);
+  });
+
+  it('NSEStorage interface is structurally valid', () => {
+    // Verify the interface works with a mock implementation
+    const storage: NSEStorage = {
+      get: async (key: string) => key === 'exists' ? 'value' : null,
+      put: async (_key: string, _value: string) => {},
+      delete: async (_key: string) => {},
+    };
+    expect(storage.get).toBeDefined();
+    expect(storage.put).toBeDefined();
+    expect(storage.delete).toBeDefined();
+  });
+
+  it('NSEProvider interface accepts a mock implementation', () => {
+    // Structural type check — a mock provider satisfies the interface
+    const mock: NSEProvider = {
+      generate: async () => ({
+        pubkey: 'a'.repeat(64),
+        npub: 'npub1test',
+        created_at: Date.now(),
+        hardware_backed: false,
+      }),
+      sign: async (event) => ({
+        ...event,
+        id: 'a'.repeat(64),
+        pubkey: 'b'.repeat(64),
+        sig: 'c'.repeat(128),
+      }),
+      getPublicKey: async () => 'a'.repeat(64),
+      getNpub: async () => 'npub1test',
+      exists: async () => true,
+      destroy: async () => {},
+    };
+    expect(mock.generate).toBeDefined();
+    expect(mock.sign).toBeDefined();
+  });
+});

platforms/core/src/index.test.ts

@@ -1,42 +1,77 @@
 /**
  * @nse-dev/core — Shared types for Nostr Secure Enclave
+ *
+ * These types align with nostr-crypto-utils where possible.
+ * NSE adds hardware-backing metadata on top of standard Nostr types.
  */
 
-/** Minimal Nostr event for signing */
+// ---------------------------------------------------------------------------
+// Event types — compatible with nostr-crypto-utils BaseNostrEvent / SignedNostrEvent
+// ---------------------------------------------------------------------------
+
+/** Unsigned Nostr event for signing (matches nostr-crypto-utils BaseNostrEvent) */
 export interface NSEEvent {
   kind: number;
   content: string;
   tags: string[][];
   created_at: number;
+  pubkey?: string;
 }
 
-/** Signed Nostr event (id + sig populated) */
-export interface NSESignedEvent extends NSEEvent {
+/** Signed Nostr event (matches nostr-crypto-utils SignedNostrEvent) */
+export interface NSESignedEvent {
   id: string;
   pubkey: string;
   sig: string;
+  kind: number;
+  content: string;
+  tags: string[][];
+  created_at: number;
 }
 
+// ---------------------------------------------------------------------------
+// Key types
+// ---------------------------------------------------------------------------
+
 /** Key info returned by generate() */
 export interface NSEKeyInfo {
+  /** Hex pubkey (64 chars) */
   pubkey: string;
+  /** Bech32 npub */
   npub: string;
+  /** Unix timestamp of key creation */
   created_at: number;
+  /** True if key is protected by hardware (Secure Enclave, StrongBox, TPM) */
   hardware_backed: boolean;
 }
 
-/** Platform-agnostic NSE contract — every implementation conforms to this */
+// ---------------------------------------------------------------------------
+// Storage interface — each platform provides its own
+// ---------------------------------------------------------------------------
+
+/** Platform-specific encrypted blob storage */
+export interface NSEStorage {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Provider interface — the contract every platform implementation conforms to
+// ---------------------------------------------------------------------------
+
+/** Platform-agnostic NSE contract */
 export interface NSEProvider {
   /** Generate a new secp256k1 keypair, protected by hardware */
   generate(): Promise<NSEKeyInfo>;
 
-  /** Sign a Nostr event (biometric unlock → decrypt → sign → zero) */
+  /** Sign a Nostr event (unlock → decrypt → sign → zero) */
   sign(event: NSEEvent): Promise<NSESignedEvent>;
 
-  /** Get the hex pubkey */
+  /** Get the hex pubkey (does not require unlock) */
   getPublicKey(): Promise<string>;
 
-  /** Get the bech32 npub */
+  /** Get the bech32 npub (does not require unlock) */
   getNpub(): Promise<string>;
 
   /** Check if a key exists in storage */
@@ -45,3 +80,56 @@ export interface NSEProvider {
   /** Wipe all key material */
   destroy(): Promise<void>;
 }
+
+// ---------------------------------------------------------------------------
+// Encrypted blob format — what gets stored at rest
+// ---------------------------------------------------------------------------
+
+/** The encrypted key blob stored by every platform */
+export interface NSEEncryptedBlob {
+  /** Version of the blob format (for future migration) */
+  version: 1;
+  /** AES-GCM encrypted secp256k1 private key (base64) */
+  ciphertext: string;
+  /** AES-GCM initialization vector (base64, 12 bytes) */
+  iv: string;
+  /** Hex pubkey (stored alongside for lookup without decryption) */
+  pubkey: string;
+  /** Bech32 npub */
+  npub: string;
+  /** Unix timestamp of key creation */
+  created_at: number;
+  /** Whether the wrapping key is hardware-backed */
+  hardware_backed: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Error types
+// ---------------------------------------------------------------------------
+
+export class NSEError extends Error {
+  constructor(
+    message: string,
+    public readonly code: NSEErrorCode,
+  ) {
+    super(message);
+    this.name = 'NSEError';
+  }
+}
+
+export enum NSEErrorCode {
+  /** No key exists — call generate() first */
+  KEY_NOT_FOUND = 'KEY_NOT_FOUND',
+  /** Biometric / unlock was denied or failed */
+  AUTH_FAILED = 'AUTH_FAILED',
+  /** Hardware enclave not available on this device */
+  HARDWARE_UNAVAILABLE = 'HARDWARE_UNAVAILABLE',
+  /** Key already exists — call destroy() first if you want to regenerate */
+  KEY_EXISTS = 'KEY_EXISTS',
+  /** AES-GCM decryption failed (corrupted blob or wrong wrapping key) */
+  DECRYPTION_FAILED = 'DECRYPTION_FAILED',
+  /** Storage read/write failed */
+  STORAGE_ERROR = 'STORAGE_ERROR',
+  /** Signing failed */
+  SIGN_FAILED = 'SIGN_FAILED',
+}

platforms/core/src/index.ts

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"],
+  "exclude": ["dist", "node_modules", "**/*.test.ts"]
+}