npl-presence-sdk 1.0.0

package/README.md

@@ -0,0 +1,73 @@
+# @nextera.one/npl-sdk
+
+TypeScript SDK for **NPL (Network Presence Layer)** - cryptographic presence verification.
+
+> "IP moves packets. DNS finds locators. NPL proves presence."
+
+## Install
+
+```bash
+npm install @nextera.one/npl-sdk
+```
+
+## Quick Start
+
+```typescript
+import {
+  createPresence,
+  computeNplId,
+  signPresence,
+  validatePresence,
+  generateKeypair,
+} from '@nextera.one/npl-sdk';
+
+// Generate a keypair
+const keypair = await generateKeypair();
+
+// Create a presence object
+const presence = createPresence('device:sensor-001', ['net', 'log'], 5);
+
+// Compute NPL-ID
+const nplId = computeNplId(presence);
+console.log('NPL-ID:', nplId);
+
+// Sign the presence
+const signedPresence = await signPresence(presence, keypair);
+
+// Validate
+const result = validatePresence(signedPresence);
+console.log('Valid:', result.ok);
+```
+
+## API Reference
+
+### Presence Objects
+
+| Function                                          | Description                   |
+| ------------------------------------------------- | ----------------------------- |
+| `createPresence(subject, scopes?, ttl?, anchor?)` | Create a new presence object  |
+| `computeNplId(presence)`                          | Compute NPL-ID hash           |
+| `signPresence(presence, keypair)`                 | Sign with Ed25519             |
+| `validatePresence(presence)`                      | Validate structure and timing |
+| `isPresenceValid(presence)`                       | Check if within time window   |
+
+### Resolution Records
+
+| Function                                         | Description                     |
+| ------------------------------------------------ | ------------------------------- |
+| `createResolutionRecord(nplId, ips, ttl?, ctx?)` | Create RR binding NPL-ID to IPs |
+| `signResolutionRecord(rr, keypair)`              | Sign the resolution record      |
+| `validateResolutionRecord(rr)`                   | Validate RR structure           |
+
+### Cryptographic Utilities
+
+| Function                                | Description              |
+| --------------------------------------- | ------------------------ |
+| `generateKeypair()`                     | Generate Ed25519 keypair |
+| `sign(message, privateKey)`             | Sign raw bytes           |
+| `verify(signature, message, publicKey)` | Verify signature         |
+| `hash(data)`                            | SHA-256 hash             |
+
+## License
+
+Apache-2.0

package/dist/core/index.d.mts

@@ -0,0 +1,203 @@
+/**
+ * NPL SDK - Core Type Definitions
+ * Network Presence Layer - Cryptographically Verifiable Presence
+ */
+type NplAlgorithm = 'ed25519';
+type NplScope = 'net' | 'log' | 'auth' | 'exec';
+type AnchorType = 'geo' | 'carrier' | 'org' | 'dns' | 'hardware' | 'jur';
+interface NplPayload {
+    sub: string;
+    iat: string;
+    exp: string;
+    scp: NplScope[];
+    nonce: string;
+    anchor?: AnchorType;
+}
+interface NplPresenceObject {
+    ver: 1;
+    alg: NplAlgorithm;
+    pay: NplPayload;
+    sig?: string;
+}
+interface NplResolutionRecord {
+    ver: 1;
+    typ: 'NPL-RR';
+    alg: NplAlgorithm;
+    npl_id: string;
+    ips: Array<{
+        ip: string;
+        fam: 4 | 6;
+    }>;
+    nbf: string;
+    exp: string;
+    ctx?: {
+        port?: number[];
+        proto?: ('tcp' | 'quic' | 'udp')[];
+        scope?: NplScope[];
+    };
+    sig?: string;
+}
+interface NplClientHello {
+    typ: 'NPL-CH';
+    ver: 1;
+    cap: string[];
+    want: string[];
+    ts: string;
+}
+interface NplServerChallenge {
+    typ: 'NPL-SC';
+    ver: 1;
+    cookie: string;
+    ttl_ms: number;
+    srv_ts: string;
+    req: {
+        need: string[];
+        scope: NplScope[];
+    };
+}
+interface NplClientProof {
+    typ: 'NPL-CP';
+    ver: 1;
+    cookie: string;
+    presence: NplPresenceObject;
+    rr?: NplResolutionRecord;
+    bind: {
+        sid: string;
+        cnonce: string;
+        ts: string;
+    };
+    sig: string;
+}
+interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+interface NplKeypair {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+}
+
+/**
+ * NPL SDK - Canonicalization
+ * Deterministic JSON serialization for NPL-ID computation
+ */
+/**
+ * Canonicalize an object for hashing.
+ * Keys are sorted lexicographically, no whitespace.
+ */
+declare function canonicalize(obj: unknown): string;
+
+/**
+ * NPL SDK - Cryptographic Operations
+ * Ed25519 signing and verification using @noble/ed25519
+ */
+
+/**
+ * Generate a new Ed25519 keypair
+ */
+declare function generateKeypair(): Promise<NplKeypair>;
+/**
+ * Sign a message with Ed25519
+ */
+declare function sign(message: Uint8Array, privateKey: Uint8Array): Promise<Uint8Array>;
+/**
+ * Verify an Ed25519 signature
+ */
+declare function verify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
+/**
+ * Compute SHA-256 hash
+ */
+declare function hash(data: Uint8Array): Uint8Array;
+/**
+ * Convert bytes to hex string
+ */
+declare function bytesToHex(bytes: Uint8Array): string;
+/**
+ * Convert hex string to bytes
+ */
+declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Base64url encode
+ */
+declare function base64urlEncode(bytes: Uint8Array): string;
+/**
+ * Base64url decode
+ */
+declare function base64urlDecode(str: string): Uint8Array;
+/**
+ * Generate random bytes
+ */
+declare function randomBytes(length: number): Uint8Array;
+/**
+ * Generate random nonce as hex string
+ */
+declare function generateNonce(length?: number): string;
+
+/**
+ * NPL SDK - Presence Object
+ * Create, validate, and sign NPL Presence Objects
+ */
+
+/**
+ * Create a new NPL Presence Object
+ */
+declare function createPresence(subject: string, scopes?: NplScope[], ttlMinutes?: number, anchor?: AnchorType): NplPresenceObject;
+/**
+ * Compute NPL-ID from a presence object.
+ * NPL-ID = SHA256("NPL:v1:" || Canonical(Payload))
+ */
+declare function computeNplId(presence: NplPresenceObject): string;
+/**
+ * Sign a presence object
+ */
+declare function signPresence(presence: NplPresenceObject, keypair: NplKeypair): Promise<NplPresenceObject>;
+/**
+ * Validate an NPL Presence Object structure
+ */
+declare function validatePresence(presence: NplPresenceObject): ValidationResult;
+/**
+ * Check if presence is currently valid (within time window)
+ */
+declare function isPresenceValid(presence: NplPresenceObject): boolean;
+/**
+ * Get remaining TTL in seconds
+ */
+declare function getPresenceTtl(presence: NplPresenceObject): number;
+/**
+ * Format presence for display
+ */
+declare function formatPresence(presence: NplPresenceObject): string;
+
+/**
+ * NPL SDK - Resolution Records
+ * Create and validate NPL Resolution Records
+ */
+
+/**
+ * Create a Resolution Record
+ */
+declare function createResolutionRecord(nplId: string, ips: Array<{
+    ip: string;
+    fam: 4 | 6;
+}>, ttlMinutes?: number, ctx?: {
+    port?: number[];
+    proto?: ('tcp' | 'quic' | 'udp')[];
+    scope?: NplScope[];
+}): NplResolutionRecord;
+/**
+ * Sign a Resolution Record
+ */
+declare function signResolutionRecord(rr: NplResolutionRecord, keypair: NplKeypair): Promise<NplResolutionRecord>;
+/**
+ * Validate a Resolution Record structure
+ */
+declare function validateResolutionRecord(rr: NplResolutionRecord): {
+    ok: boolean;
+    errors: string[];
+};
+/**
+ * Check if resolution record is currently valid
+ */
+declare function isResolutionRecordValid(rr: NplResolutionRecord): boolean;
+
+export { type AnchorType, type NplAlgorithm, type NplClientHello, type NplClientProof, type NplKeypair, type NplPayload, type NplPresenceObject, type NplResolutionRecord, type NplScope, type NplServerChallenge, type ValidationResult, base64urlDecode, base64urlEncode, bytesToHex, canonicalize, computeNplId, createPresence, createResolutionRecord, formatPresence, generateKeypair, generateNonce, getPresenceTtl, hash, hexToBytes, isPresenceValid, isResolutionRecordValid, randomBytes, sign, signPresence, signResolutionRecord, validatePresence, validateResolutionRecord, verify };

package/dist/core/index.d.ts

@@ -0,0 +1,203 @@
+/**
+ * NPL SDK - Core Type Definitions
+ * Network Presence Layer - Cryptographically Verifiable Presence
+ */
+type NplAlgorithm = 'ed25519';
+type NplScope = 'net' | 'log' | 'auth' | 'exec';
+type AnchorType = 'geo' | 'carrier' | 'org' | 'dns' | 'hardware' | 'jur';
+interface NplPayload {
+    sub: string;
+    iat: string;
+    exp: string;
+    scp: NplScope[];
+    nonce: string;
+    anchor?: AnchorType;
+}
+interface NplPresenceObject {
+    ver: 1;
+    alg: NplAlgorithm;
+    pay: NplPayload;
+    sig?: string;
+}
+interface NplResolutionRecord {
+    ver: 1;
+    typ: 'NPL-RR';
+    alg: NplAlgorithm;
+    npl_id: string;
+    ips: Array<{
+        ip: string;
+        fam: 4 | 6;
+    }>;
+    nbf: string;
+    exp: string;
+    ctx?: {
+        port?: number[];
+        proto?: ('tcp' | 'quic' | 'udp')[];
+        scope?: NplScope[];
+    };
+    sig?: string;
+}
+interface NplClientHello {
+    typ: 'NPL-CH';
+    ver: 1;
+    cap: string[];
+    want: string[];
+    ts: string;
+}
+interface NplServerChallenge {
+    typ: 'NPL-SC';
+    ver: 1;
+    cookie: string;
+    ttl_ms: number;
+    srv_ts: string;
+    req: {
+        need: string[];
+        scope: NplScope[];
+    };
+}
+interface NplClientProof {
+    typ: 'NPL-CP';
+    ver: 1;
+    cookie: string;
+    presence: NplPresenceObject;
+    rr?: NplResolutionRecord;
+    bind: {
+        sid: string;
+        cnonce: string;
+        ts: string;
+    };
+    sig: string;
+}
+interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+interface NplKeypair {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+}
+
+/**
+ * NPL SDK - Canonicalization
+ * Deterministic JSON serialization for NPL-ID computation
+ */
+/**
+ * Canonicalize an object for hashing.
+ * Keys are sorted lexicographically, no whitespace.
+ */
+declare function canonicalize(obj: unknown): string;
+
+/**
+ * NPL SDK - Cryptographic Operations
+ * Ed25519 signing and verification using @noble/ed25519
+ */
+
+/**
+ * Generate a new Ed25519 keypair
+ */
+declare function generateKeypair(): Promise<NplKeypair>;
+/**
+ * Sign a message with Ed25519
+ */
+declare function sign(message: Uint8Array, privateKey: Uint8Array): Promise<Uint8Array>;
+/**
+ * Verify an Ed25519 signature
+ */
+declare function verify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
+/**
+ * Compute SHA-256 hash
+ */
+declare function hash(data: Uint8Array): Uint8Array;
+/**
+ * Convert bytes to hex string
+ */
+declare function bytesToHex(bytes: Uint8Array): string;
+/**
+ * Convert hex string to bytes
+ */
+declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Base64url encode
+ */
+declare function base64urlEncode(bytes: Uint8Array): string;
+/**
+ * Base64url decode
+ */
+declare function base64urlDecode(str: string): Uint8Array;
+/**
+ * Generate random bytes
+ */
+declare function randomBytes(length: number): Uint8Array;
+/**
+ * Generate random nonce as hex string
+ */
+declare function generateNonce(length?: number): string;
+
+/**
+ * NPL SDK - Presence Object
+ * Create, validate, and sign NPL Presence Objects
+ */
+
+/**
+ * Create a new NPL Presence Object
+ */
+declare function createPresence(subject: string, scopes?: NplScope[], ttlMinutes?: number, anchor?: AnchorType): NplPresenceObject;
+/**
+ * Compute NPL-ID from a presence object.
+ * NPL-ID = SHA256("NPL:v1:" || Canonical(Payload))
+ */
+declare function computeNplId(presence: NplPresenceObject): string;
+/**
+ * Sign a presence object
+ */
+declare function signPresence(presence: NplPresenceObject, keypair: NplKeypair): Promise<NplPresenceObject>;
+/**
+ * Validate an NPL Presence Object structure
+ */
+declare function validatePresence(presence: NplPresenceObject): ValidationResult;
+/**
+ * Check if presence is currently valid (within time window)
+ */
+declare function isPresenceValid(presence: NplPresenceObject): boolean;
+/**
+ * Get remaining TTL in seconds
+ */
+declare function getPresenceTtl(presence: NplPresenceObject): number;
+/**
+ * Format presence for display
+ */
+declare function formatPresence(presence: NplPresenceObject): string;
+
+/**
+ * NPL SDK - Resolution Records
+ * Create and validate NPL Resolution Records
+ */
+
+/**
+ * Create a Resolution Record
+ */
+declare function createResolutionRecord(nplId: string, ips: Array<{
+    ip: string;
+    fam: 4 | 6;
+}>, ttlMinutes?: number, ctx?: {
+    port?: number[];
+    proto?: ('tcp' | 'quic' | 'udp')[];
+    scope?: NplScope[];
+}): NplResolutionRecord;
+/**
+ * Sign a Resolution Record
+ */
+declare function signResolutionRecord(rr: NplResolutionRecord, keypair: NplKeypair): Promise<NplResolutionRecord>;
+/**
+ * Validate a Resolution Record structure
+ */
+declare function validateResolutionRecord(rr: NplResolutionRecord): {
+    ok: boolean;
+    errors: string[];
+};
+/**
+ * Check if resolution record is currently valid
+ */
+declare function isResolutionRecordValid(rr: NplResolutionRecord): boolean;
+
+export { type AnchorType, type NplAlgorithm, type NplClientHello, type NplClientProof, type NplKeypair, type NplPayload, type NplPresenceObject, type NplResolutionRecord, type NplScope, type NplServerChallenge, type ValidationResult, base64urlDecode, base64urlEncode, bytesToHex, canonicalize, computeNplId, createPresence, createResolutionRecord, formatPresence, generateKeypair, generateNonce, getPresenceTtl, hash, hexToBytes, isPresenceValid, isResolutionRecordValid, randomBytes, sign, signPresence, signResolutionRecord, validatePresence, validateResolutionRecord, verify };