near-kit 0.0.0 → 0.1.0

package/dist/keys/native-keystore.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Native OS keystore implementation using system credential storage
+ */
+import type { KeyPair, KeyStore } from "../core/types.js";
+/**
+ * Native OS keystore using system credential storage
+ *
+ * This keystore uses the operating system's native secure credential storage:
+ * - **macOS**: Keychain Access
+ * - **Windows**: Credential Manager (DPAPI)
+ * - **Linux**: libsecret/Secret Service API
+ *
+ * ## Security Benefits
+ * - Keys stored in OS-level secure storage (not plain files)
+ * - Encrypted by OS using hardware-backed keys when available
+ * - Protected by user's system password/biometrics
+ * - Isolated from other applications
+ *
+ * ## Requirements
+ * - Requires `@napi-rs/keyring` native dependency
+ * - Linux requires `libsecret` (`apt install libsecret-1-dev` on Debian/Ubuntu)
+ *
+ * ## Limitations
+ * - Not available in browser environments (use InMemoryKeyStore instead)
+ * - Requires user to be logged in to the system
+ * - Keys are machine-specific (not synced across devices)
+ *
+ * @example
+ * ```typescript
+ * // Use OS keyring for maximum security
+ * const keyStore = new NativeKeyStore()
+ * const near = new Near({ keyStore })
+ *
+ * // Keys stored in:
+ * // - macOS: Keychain Access > "NEAR Credentials"
+ * // - Windows: Credential Manager > Generic Credentials
+ * // - Linux: GNOME Keyring / KDE Wallet
+ * ```
+ */
+export declare class NativeKeyStore implements KeyStore {
+    private readonly service;
+    /**
+     * Create a new native OS keystore
+     *
+     * @param service - Service name for credential storage (default: "NEAR Credentials")
+     *                  This appears in Keychain Access (macOS) or Credential Manager (Windows)
+     *
+     * @example
+     * ```typescript
+     * // Default service name
+     * const keyStore = new NativeKeyStore()
+     *
+     * // Custom service name for your app
+     * const keyStore = new NativeKeyStore("MyApp NEAR Keys")
+     * ```
+     */
+    constructor(service?: string);
+    /**
+     * Create an Entry instance for keyring operations
+     */
+    private getEntry;
+    /**
+     * Add a key to the OS keystore
+     *
+     * Stores the key securely in the operating system's credential storage.
+     * The key is encrypted by the OS and protected by the user's system password.
+     *
+     * @param accountId - NEAR account ID (used as credential name)
+     * @param key - Key pair to store
+     * @param options - Optional metadata (stored alongside the key in OS keyring)
+     *
+     * @throws {Error} If keyring access fails (e.g., user denies permission)
+     */
+    add(accountId: string, key: KeyPair, options?: {
+        seedPhrase?: string;
+        derivationPath?: string;
+        implicitAccountId?: string;
+    }): Promise<void>;
+    /**
+     * Get a key from the OS keystore
+     *
+     * Retrieves and decrypts the key from the operating system's credential storage.
+     *
+     * @param accountId - NEAR account ID
+     * @returns Key pair if found, null otherwise
+     *
+     * @throws {Error} If keyring access fails or key is corrupted
+     */
+    get(accountId: string): Promise<KeyPair | null>;
+    /**
+     * Remove a key from the OS keystore
+     *
+     * Permanently deletes the credential from the operating system's storage.
+     *
+     * @param accountId - NEAR account ID
+     */
+    remove(accountId: string): Promise<void>;
+    /**
+     * List all account IDs in the OS keystore
+     *
+     * ⚠️  **Note**: The underlying keyring library doesn't support listing all
+     * credentials for a service. This method returns an empty array.
+     *
+     * If you need to track multiple accounts, maintain a list separately
+     * (e.g., in a config file) and use this keystore only for secure key storage.
+     *
+     * @returns Empty array (OS keyrings don't support enumeration for security)
+     */
+    list(): Promise<string[]>;
+}
+//# sourceMappingURL=native-keystore.d.ts.map

package/dist/keys/native-keystore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-keystore.d.ts","sourceRoot":"","sources":["../../src/keys/native-keystore.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAOzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,cAAe,YAAW,QAAQ;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAEhC;;;;;;;;;;;;;;OAcG;gBACS,OAAO,SAAqB;IAIxC;;OAEG;YACW,QAAQ;IAMtB;;;;;;;;;;;OAWG;IACG,GAAG,CACP,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,OAAO,EACZ,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,cAAc,CAAC,EAAE,MAAM,CAAA;QACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAC3B,GACA,OAAO,CAAC,IAAI,CAAC;IAyBhB;;;;;;;;;OASG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAqBrD;;;;;;OAMG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9C;;;;;;;;;;OAUG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAKhC"}

package/dist/keys/native-keystore.js

@@ -0,0 +1,167 @@
+/**
+ * Native OS keystore implementation using system credential storage
+ */
+import { parseKey } from "../utils/key.js";
+import { parseCredentialFile, } from "./credential-schemas.js";
+/**
+ * Native OS keystore using system credential storage
+ *
+ * This keystore uses the operating system's native secure credential storage:
+ * - **macOS**: Keychain Access
+ * - **Windows**: Credential Manager (DPAPI)
+ * - **Linux**: libsecret/Secret Service API
+ *
+ * ## Security Benefits
+ * - Keys stored in OS-level secure storage (not plain files)
+ * - Encrypted by OS using hardware-backed keys when available
+ * - Protected by user's system password/biometrics
+ * - Isolated from other applications
+ *
+ * ## Requirements
+ * - Requires `@napi-rs/keyring` native dependency
+ * - Linux requires `libsecret` (`apt install libsecret-1-dev` on Debian/Ubuntu)
+ *
+ * ## Limitations
+ * - Not available in browser environments (use InMemoryKeyStore instead)
+ * - Requires user to be logged in to the system
+ * - Keys are machine-specific (not synced across devices)
+ *
+ * @example
+ * ```typescript
+ * // Use OS keyring for maximum security
+ * const keyStore = new NativeKeyStore()
+ * const near = new Near({ keyStore })
+ *
+ * // Keys stored in:
+ * // - macOS: Keychain Access > "NEAR Credentials"
+ * // - Windows: Credential Manager > Generic Credentials
+ * // - Linux: GNOME Keyring / KDE Wallet
+ * ```
+ */
+export class NativeKeyStore {
+    /**
+     * Create a new native OS keystore
+     *
+     * @param service - Service name for credential storage (default: "NEAR Credentials")
+     *                  This appears in Keychain Access (macOS) or Credential Manager (Windows)
+     *
+     * @example
+     * ```typescript
+     * // Default service name
+     * const keyStore = new NativeKeyStore()
+     *
+     * // Custom service name for your app
+     * const keyStore = new NativeKeyStore("MyApp NEAR Keys")
+     * ```
+     */
+    constructor(service = "NEAR Credentials") {
+        this.service = service;
+    }
+    /**
+     * Create an Entry instance for keyring operations
+     */
+    async getEntry(accountId) {
+        // Dynamic import to allow graceful fallback if not installed
+        const { Entry } = await import("@napi-rs/keyring");
+        return new Entry(this.service, accountId);
+    }
+    /**
+     * Add a key to the OS keystore
+     *
+     * Stores the key securely in the operating system's credential storage.
+     * The key is encrypted by the OS and protected by the user's system password.
+     *
+     * @param accountId - NEAR account ID (used as credential name)
+     * @param key - Key pair to store
+     * @param options - Optional metadata (stored alongside the key in OS keyring)
+     *
+     * @throws {Error} If keyring access fails (e.g., user denies permission)
+     */
+    async add(accountId, key, options) {
+        const entry = await this.getEntry(accountId);
+        // Store full key data as JSON
+        const keyData = {
+            account_id: accountId,
+            public_key: key.publicKey.toString(),
+            private_key: key.secretKey,
+        };
+        // Add optional fields if provided
+        if (options?.seedPhrase) {
+            keyData.master_seed_phrase = options.seedPhrase;
+        }
+        if (options?.derivationPath) {
+            keyData.seed_phrase_hd_path = options.derivationPath;
+        }
+        if (options?.implicitAccountId) {
+            keyData.implicit_account_id = options.implicitAccountId;
+        }
+        // Store as JSON string in keyring
+        entry.setPassword(JSON.stringify(keyData));
+    }
+    /**
+     * Get a key from the OS keystore
+     *
+     * Retrieves and decrypts the key from the operating system's credential storage.
+     *
+     * @param accountId - NEAR account ID
+     * @returns Key pair if found, null otherwise
+     *
+     * @throws {Error} If keyring access fails or key is corrupted
+     */
+    async get(accountId) {
+        try {
+            const entry = await this.getEntry(accountId);
+            const stored = entry.getPassword();
+            if (!stored) {
+                return null;
+            }
+            // Parse stored JSON data
+            const keyData = parseCredentialFile(JSON.parse(stored));
+            return parseKey(keyData.private_key);
+        }
+        catch (error) {
+            // Key not found or access denied
+            if (error instanceof Error && error.message.includes("not found")) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Remove a key from the OS keystore
+     *
+     * Permanently deletes the credential from the operating system's storage.
+     *
+     * @param accountId - NEAR account ID
+     */
+    async remove(accountId) {
+        try {
+            const entry = await this.getEntry(accountId);
+            entry.deletePassword();
+        }
+        catch (error) {
+            // Ignore if credential doesn't exist
+            if (error instanceof Error && error.message.includes("not found")) {
+                return;
+            }
+            throw error;
+        }
+    }
+    /**
+     * List all account IDs in the OS keystore
+     *
+     * ⚠️  **Note**: The underlying keyring library doesn't support listing all
+     * credentials for a service. This method returns an empty array.
+     *
+     * If you need to track multiple accounts, maintain a list separately
+     * (e.g., in a config file) and use this keystore only for secure key storage.
+     *
+     * @returns Empty array (OS keyrings don't support enumeration for security)
+     */
+    async list() {
+        // Native keyrings don't support listing credentials for security reasons
+        // Applications should track account IDs separately if needed
+        return [];
+    }
+}
+//# sourceMappingURL=native-keystore.js.map

package/dist/keys/native-keystore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-keystore.js","sourceRoot":"","sources":["../../src/keys/native-keystore.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Sandbox exports
+ */
+export type { SandboxOptions } from "./sandbox.js";
+export { Sandbox } from "./sandbox.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sandbox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}

package/dist/sandbox/index.js

@@ -0,0 +1,5 @@
+/**
+ * Sandbox exports
+ */
+export { Sandbox } from "./sandbox.js";
+//# sourceMappingURL=index.js.map

package/dist/sandbox/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}

package/dist/sandbox/sandbox.d.ts

@@ -0,0 +1,55 @@
+/**
+ * NEAR Sandbox - Local testing environment
+ *
+ * Simple, explicit API for running a local NEAR node for testing.
+ */
+export interface SandboxOptions {
+    version?: string;
+    /**
+     * Whether to spawn the sandbox process as detached.
+     * Default: true
+     * Set to false in test environments to prevent the process from being killed by test runners.
+     */
+    detached?: boolean;
+}
+/**
+ * NEAR Sandbox instance
+ *
+ * Manages a local NEAR node for testing. Automatically cleans up on stop().
+ *
+ * @example
+ * ```typescript
+ * const sandbox = await Sandbox.start();
+ * const near = new Near({ network: sandbox });
+ * // ... run tests
+ * await sandbox.stop();
+ * ```
+ */
+export declare class Sandbox {
+    readonly rpcUrl: string;
+    readonly networkId: string;
+    readonly rootAccount: {
+        id: string;
+        secretKey: string;
+    };
+    private process;
+    private homeDir;
+    private constructor();
+    /**
+     * Start a new sandbox instance
+     *
+     * Downloads the sandbox binary if needed, initializes a temporary directory,
+     * and starts the sandbox process.
+     *
+     * @param options - Optional configuration
+     * @returns Promise resolving to a running Sandbox instance
+     */
+    static start(options?: SandboxOptions): Promise<Sandbox>;
+    /**
+     * Stop the sandbox and clean up
+     *
+     * Kills the sandbox process and removes temporary files.
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/sandbox.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkCH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,OAAO;IAClB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAEvD,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,OAAO,CAAQ;IAEvB,OAAO;IAcP;;;;;;;;OAQG;WACU,KAAK,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAuDlE;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAiC5B"}