shogun-core 3.0.4 → 3.0.6

package/dist/types/plugins/web3/web3Signer.d.ts

@@ -0,0 +1,114 @@
+import { Web3Connector } from "./web3Connector";
+/**
+ * Web3 Signing Credential for oneshot signing
+ */
+export interface Web3SigningCredential {
+    address: string;
+    signature: string;
+    message: string;
+    username: string;
+    password: string;
+    gunUserPub?: string;
+}
+/**
+ * Web3 Signer - Provides oneshot signing functionality
+ * Similar to webauthn.js but for Web3/MetaMask
+ * CONSISTENT with normal Web3 approach
+ */
+export declare class Web3Signer {
+    private web3Connector;
+    private credentials;
+    private readonly MESSAGE_TO_SIGN;
+    constructor(web3Connector?: Web3Connector);
+    /**
+     * Creates a new Web3 signing credential
+     * CONSISTENT with normal Web3 approach
+     */
+    createSigningCredential(address: string): Promise<Web3SigningCredential>;
+    /**
+     * Request signature from MetaMask
+     * Uses the same approach as normal Web3Connector
+     */
+    private requestSignature;
+    /**
+     * Creates an authenticator function compatible with SEA.sign
+     * This is the key function that makes it work like webauthn.js but for Web3
+     */
+    createAuthenticator(address: string): (data: any) => Promise<string>;
+    /**
+     * Creates a derived key pair from Web3 credential
+     * CONSISTENT with normal approach: uses password as seed
+     */
+    createDerivedKeyPair(address: string, extra?: string[]): Promise<{
+        pub: string;
+        priv: string;
+        epub: string;
+        epriv: string;
+    }>;
+    /**
+     * Authenticate with existing pair (for login)
+     * This generates the deterministic pair from address and authenticates with GunDB
+     * GunDB will recognize the user because the pair is deterministic
+     */
+    authenticateWithExistingPair(address: string, gunInstance: any): Promise<{
+        success: boolean;
+        userPub?: string;
+        error?: string;
+    }>;
+    /**
+     * Creates a derived key pair directly from address (deterministic)
+     * This ensures the same pair is generated every time for the same address
+     */
+    createDerivedKeyPairFromAddress(address: string, extra?: string[]): Promise<{
+        pub: string;
+        priv: string;
+        epub: string;
+        epriv: string;
+    }>;
+    /**
+     * Creates a Gun user from Web3 credential
+     * This ensures the SAME user is created as with normal approach
+     * FIX: Use derived pair instead of username/password for GunDB auth
+     */
+    createGunUser(address: string, gunInstance: any): Promise<{
+        success: boolean;
+        userPub?: string;
+        error?: string;
+    }>;
+    /**
+     * Signs data using Web3 + derived keys
+     * This provides a hybrid approach: Web3 for user verification + derived keys for actual signing
+     * CONSISTENT with normal approach
+     */
+    signWithDerivedKeys(data: any, address: string, extra?: string[]): Promise<string>;
+    /**
+     * Get the Gun user public key for a credential
+     * This allows checking if the same user would be created
+     */
+    getGunUserPub(address: string): Promise<string | undefined>;
+    /**
+     * Get the password (for consistency checking)
+     */
+    getPassword(address: string): string | undefined;
+    /**
+     * Check if this credential would create the same Gun user as normal approach
+     */
+    verifyConsistency(address: string, expectedUserPub?: string): Promise<{
+        consistent: boolean;
+        actualUserPub?: string;
+        expectedUserPub?: string;
+    }>;
+    /**
+     * Get credential by address
+     */
+    getCredential(address: string): Web3SigningCredential | undefined;
+    /**
+     * List all stored credentials
+     */
+    listCredentials(): Web3SigningCredential[];
+    /**
+     * Remove a credential
+     */
+    removeCredential(address: string): boolean;
+}
+export default Web3Signer;

package/dist/types/plugins/webauthn/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./webauthnPlugin";
+export * from "./types";
+export * from "./webauthn";

package/dist/types/plugins/webauthn/types.d.ts

@@ -0,0 +1,162 @@
+import { AuthResult, SignUpResult } from "../../interfaces/shogun";
+import { BaseEvent, BaseConfig, BaseDeviceInfo, BaseResult, BaseAuthResult } from "../../interfaces/common";
+/**
+ * WebAuthn types definitions
+ */
+/**
+ * WebAuthn device information
+ */
+export interface DeviceInfo extends BaseDeviceInfo {
+    registeredBy?: string;
+}
+/**
+ * WebAuthn credentials storage
+ */
+export interface WebAuthnCredentials {
+    salt: string;
+    timestamp: number;
+    credentials: Record<string, DeviceInfo>;
+}
+/**
+ * Result of credential operations
+ */
+export interface CredentialResult extends BaseAuthResult {
+    credentialId?: string;
+    deviceInfo?: DeviceInfo;
+    webAuthnCredentials?: WebAuthnCredentials;
+    publicKey?: ArrayBuffer | null;
+}
+/**
+ * WebAuthn configuration options
+ */
+export interface WebAuthnConfig extends BaseConfig {
+    rpName: string;
+    rpId?: string;
+    userVerification?: UserVerificationRequirement;
+    attestation?: AttestationConveyancePreference;
+    authenticatorAttachment?: AuthenticatorAttachment;
+    requireResidentKey?: boolean;
+}
+/**
+ * WebAuthn event types
+ */
+export declare enum WebAuthnEventType {
+    DEVICE_REGISTERED = "deviceRegistered",
+    DEVICE_REMOVED = "deviceRemoved",
+    AUTHENTICATION_SUCCESS = "authenticationSuccess",
+    AUTHENTICATION_FAILED = "authenticationFailed",
+    ERROR = "error"
+}
+/**
+ * WebAuthn event data
+ */
+export interface WebAuthnEvent extends BaseEvent {
+    type: WebAuthnEventType;
+}
+/**
+ * WebAuthn operation options
+ */
+export interface WebAuthnOperationOptions extends BaseConfig {
+    userVerification?: UserVerificationRequirement;
+    attestation?: AttestationConveyancePreference;
+}
+/**
+ * WebAuthn credential data
+ */
+export interface WebAuthnCredentialData {
+    id: string;
+    rawId: ArrayBuffer;
+    response: {
+        clientDataJSON: ArrayBuffer;
+        attestationObject?: ArrayBuffer;
+        authenticatorData?: ArrayBuffer;
+        signature?: ArrayBuffer;
+        userHandle?: ArrayBuffer;
+        getPublicKey?: () => ArrayBuffer;
+    };
+    type: string;
+    getClientExtensionResults: () => AuthenticationExtensionsClientOutputs;
+}
+/**
+ * WebAuthn verification result
+ */
+export interface WebAuthnVerificationResult extends BaseResult {
+    username?: string;
+    credentialId?: string;
+    error?: string;
+}
+/**
+ * WebAuthn credential creation options with extensions
+ */
+export interface WebAuthnCredentialCreationOptions extends PublicKeyCredentialCreationOptions {
+    signal?: AbortSignal;
+}
+/**
+ * Interfaccia per il plugin WebAuthn
+ */
+export interface WebauthnPluginInterface {
+    /**
+     * Verifica se WebAuthn è supportato nel browser corrente
+     * @returns true se WebAuthn è supportato, false altrimenti
+     */
+    isSupported(): boolean;
+    /**
+     * Genera credenziali WebAuthn
+     * @param username Nome utente
+     * @param existingCredential Credenziali esistenti (opzionale)
+     * @param isLogin Flag che indica se è per login
+     * @returns Promise con il risultato dell'operazione
+     */
+    generateCredentials(username: string, existingCredential?: WebAuthnCredentials | null, isLogin?: boolean): Promise<CredentialResult>;
+    /**
+     * Crea un nuovo account WebAuthn
+     * @param username Nome utente
+     * @param credentials Credenziali WebAuthn
+     * @param isNewDevice Flag che indica se è un nuovo dispositivo
+     * @returns Promise con il risultato dell'operazione
+     */
+    createAccount(username: string, credentials: WebAuthnCredentials | null, isNewDevice?: boolean): Promise<CredentialResult>;
+    /**
+     * Autentica un utente con WebAuthn
+     * @param username Nome utente
+     * @param salt Salt per l'autenticazione
+     * @param options Opzioni per l'operazione
+     * @returns Promise con il risultato dell'autenticazione
+     */
+    authenticateUser(username: string, salt: string | null, options?: any): Promise<CredentialResult>;
+    /**
+     * Interrompe un tentativo di autenticazione in corso
+     */
+    abortAuthentication(): void;
+    /**
+     * Rimuove un dispositivo WebAuthn
+     * @param username Nome utente
+     * @param credentialId ID della credenziale
+     * @param credentials Credenziali WebAuthn
+     * @returns Promise con il risultato dell'operazione
+     */
+    removeDevice(username: string, credentialId: string, credentials: WebAuthnCredentials): Promise<{
+        success: boolean;
+        updatedCredentials?: WebAuthnCredentials;
+    }>;
+    /**
+     * Login con WebAuthn
+     * @param username Nome utente
+     * @returns Promise con il risultato dell'operazione
+     */
+    login(username: string): Promise<AuthResult>;
+    /**
+     * Signup con WebAuthn
+     * @param username Nome utente
+     * @returns Promise con il risultato dell'operazione
+     */
+    signUp(username: string): Promise<SignUpResult>;
+}
+export interface WebAuthnUniformCredentials {
+    success: boolean;
+    username: string;
+    key: any;
+    credentialId: string;
+    publicKey?: ArrayBuffer | null;
+    error?: string;
+}

package/dist/types/plugins/webauthn/webauthn.d.ts

@@ -0,0 +1,129 @@
+import { EventEmitter } from "../../utils/eventEmitter";
+import { DeviceInfo, WebAuthnCredentials, CredentialResult, WebAuthnConfig, WebAuthnOperationOptions } from "./types";
+import { IGunInstance } from "gun";
+/**
+ * Extends Window interface to include WebauthnAuth
+ */
+declare global {
+    interface Window {
+        Webauthn?: typeof Webauthn;
+    }
+}
+/**
+ * Extends NodeJS Global interface to include WebauthnAuth
+ */
+declare global {
+    namespace NodeJS {
+        interface Global {
+            Webauthn?: typeof Webauthn;
+        }
+    }
+}
+/**
+ * Main WebAuthn class for authentication management
+ */
+export declare class Webauthn extends EventEmitter {
+    private readonly config;
+    private readonly gunInstance?;
+    private credential;
+    private abortController;
+    /**
+     * Creates a new WebAuthn instance
+     */
+    constructor(gunInstance?: IGunInstance, config?: Partial<WebAuthnConfig>);
+    /**
+     * Validates a username
+     */
+    validateUsername(username: string): void;
+    /**
+     * Creates a new WebAuthn account with retry logic
+     */
+    createAccount(username: string, credentials: WebAuthnCredentials | null, isNewDevice?: boolean): Promise<CredentialResult>;
+    /**
+     * Authenticates a user with timeout and abort handling
+     */
+    authenticateUser(username: string, salt: string | null, options?: WebAuthnOperationOptions): Promise<CredentialResult>;
+    /**
+     * Aborts current authentication attempt
+     */
+    abortAuthentication(): void;
+    /**
+     * Gets device information
+     */
+    private getDeviceInfo;
+    /**
+     * Gets platform information
+     */
+    private getPlatformInfo;
+    /**
+     * Generates a challenge for WebAuthn operations
+     */
+    private generateChallenge;
+    /**
+     * Gets cryptographically secure random bytes
+     */
+    private getRandomBytes;
+    /**
+     * Converts Uint8Array to hexadecimal string
+     */
+    private uint8ArrayToHex;
+    /**
+     * Converts ArrayBuffer to URL-safe base64 string
+     */
+    private bufferToBase64;
+    /**
+     * Generates credentials from username and salt
+     */
+    private generateCredentialsFromSalt;
+    /**
+     * Checks if WebAuthn is supported
+     */
+    isSupported(): boolean;
+    /**
+     * Creates a WebAuthn credential for registration
+     */
+    private createCredential;
+    /**
+     * Generates WebAuthn credentials (uniforme con altri plugin)
+     */
+    generateCredentials(username: string, existingCredential?: WebAuthnCredentials | null, isLogin?: boolean): Promise<{
+        success: boolean;
+        username: string;
+        key: any;
+        credentialId: string;
+        publicKey?: ArrayBuffer | null;
+        error?: string;
+    }>;
+    /**
+     * Verifies a credential
+     */
+    private verifyCredential;
+    /**
+     * Removes device credentials
+     */
+    removeDevice(username: string, credentialId: string, credentials: WebAuthnCredentials): Promise<{
+        success: boolean;
+        updatedCredentials?: WebAuthnCredentials;
+    }>;
+    /**
+     * Signs data with the credential
+     */
+    sign(data: Record<string, unknown>): Promise<unknown>;
+}
+export type { WebAuthnCredentials, DeviceInfo, CredentialResult };
+export declare function deriveWebauthnKeys(username: string, credentialId: string): Promise<{
+    pub: string;
+    priv: string;
+    epub: string;
+    epriv: string;
+    secp256k1Bitcoin: {
+        privateKey: string;
+        publicKey: string;
+        address: string;
+    };
+    secp256k1Ethereum: {
+        privateKey: string;
+        publicKey: string;
+        address: string;
+    };
+}>;

package/dist/types/plugins/webauthn/webauthnPlugin.d.ts

@@ -0,0 +1,158 @@
+import { BasePlugin } from "../base";
+import { ShogunCore } from "../../core";
+import { WebAuthnSigningCredential } from "./webauthnSigner";
+import { WebAuthnCredentials, CredentialResult, WebauthnPluginInterface, WebAuthnUniformCredentials } from "./types";
+import { AuthResult, SignUpResult } from "../../interfaces/shogun";
+/**
+ * Plugin per la gestione delle funzionalità WebAuthn in ShogunCore
+ */
+export declare class WebauthnPlugin extends BasePlugin implements WebauthnPluginInterface {
+    name: string;
+    version: string;
+    description: string;
+    private webauthn;
+    private signer;
+    /**
+     * @inheritdoc
+     */
+    initialize(core: ShogunCore): void;
+    /**
+     * @inheritdoc
+     */
+    destroy(): void;
+    /**
+     * Assicura che il modulo Webauthn sia inizializzato
+     * @private
+     */
+    private assertWebauthn;
+    /**
+     * Assicura che il signer sia inizializzato
+     * @private
+     */
+    private assertSigner;
+    /**
+     * Genera un pair SEA dalle credenziali WebAuthn
+     * @private
+     */
+    private generatePairFromCredentials;
+    /**
+     * @inheritdoc
+     */
+    isSupported(): boolean;
+    /**
+     * @inheritdoc
+     */
+    generateCredentials(username: string, existingCredential?: WebAuthnCredentials | null, isLogin?: boolean): Promise<WebAuthnUniformCredentials>;
+    /**
+     * @inheritdoc
+     */
+    createAccount(username: string, credentials: WebAuthnCredentials | null, isNewDevice?: boolean): Promise<CredentialResult>;
+    /**
+     * @inheritdoc
+     */
+    authenticateUser(username: string, salt: string | null, options?: any): Promise<CredentialResult>;
+    /**
+     * @inheritdoc
+     */
+    abortAuthentication(): void;
+    /**
+     * @inheritdoc
+     */
+    removeDevice(username: string, credentialId: string, credentials: WebAuthnCredentials): Promise<{
+        success: boolean;
+        updatedCredentials?: WebAuthnCredentials;
+    }>;
+    /**
+     * @inheritdoc
+     */
+    createSigningCredential(username: string): Promise<WebAuthnSigningCredential>;
+    /**
+     * @inheritdoc
+     */
+    createAuthenticator(credentialId: string): (data: any) => Promise<AuthenticatorAssertionResponse>;
+    /**
+     * @inheritdoc
+     */
+    createDerivedKeyPair(credentialId: string, username: string, extra?: string[]): Promise<{
+        pub: string;
+        priv: string;
+        epub: string;
+        epriv: string;
+    }>;
+    /**
+     * @inheritdoc
+     */
+    signWithDerivedKeys(data: any, credentialId: string, username: string, extra?: string[]): Promise<string>;
+    /**
+     * @inheritdoc
+     */
+    getSigningCredential(credentialId: string): WebAuthnSigningCredential | undefined;
+    /**
+     * @inheritdoc
+     */
+    listSigningCredentials(): WebAuthnSigningCredential[];
+    /**
+     * @inheritdoc
+     */
+    removeSigningCredential(credentialId: string): boolean;
+    /**
+     * Creates a Gun user from WebAuthn signing credential
+     * This ensures the SAME user is created as with normal approach
+     */
+    createGunUserFromSigningCredential(credentialId: string, username: string): Promise<{
+        success: boolean;
+        userPub?: string;
+        error?: string;
+    }>;
+    /**
+     * Get the Gun user public key for a signing credential
+     */
+    getGunUserPubFromSigningCredential(credentialId: string): string | undefined;
+    /**
+     * Get the hashed credential ID (for consistency checking)
+     */
+    getHashedCredentialId(credentialId: string): string | undefined;
+    /**
+     * Verify consistency between oneshot and normal approaches
+     * This ensures both approaches create the same Gun user
+     */
+    verifyConsistency(credentialId: string, username: string, expectedUserPub?: string): Promise<{
+        consistent: boolean;
+        actualUserPub?: string;
+        expectedUserPub?: string;
+    }>;
+    /**
+     * Complete oneshot workflow that creates the SAME Gun user as normal approach
+     * This is the recommended method for oneshot signing with full consistency
+     */
+    setupConsistentOneshotSigning(username: string): Promise<{
+        credential: WebAuthnSigningCredential;
+        authenticator: (data: any) => Promise<AuthenticatorAssertionResponse>;
+        gunUser: {
+            success: boolean;
+            userPub?: string;
+            error?: string;
+        };
+        pub: string;
+        hashedCredentialId: string;
+    }>;
+    /**
+     * Login with WebAuthn
+     * This is the recommended method for WebAuthn authentication
+     * @param username - Username
+     * @returns {Promise<AuthResult>} Authentication result
+     * @description Authenticates user using WebAuthn credentials.
+     * Requires browser support for WebAuthn and existing credentials.
+     */
+    login(username: string): Promise<AuthResult>;
+    /**
+     * Register new user with WebAuthn
+     * This is the recommended method for WebAuthn registration
+     * @param username - Username
+     * @returns {Promise<SignUpResult>} Registration result
+     * @description Creates a new user account using WebAuthn credentials.
+     * Requires browser support for WebAuthn.
+     */
+    signUp(username: string): Promise<SignUpResult>;
+}
+export type { WebauthnPluginInterface } from "./types";

package/dist/types/plugins/webauthn/webauthnSigner.d.ts

@@ -0,0 +1,91 @@
+import { Webauthn } from "./webauthn";
+/**
+ * WebAuthn Credential for oneshot signing
+ */
+export interface WebAuthnSigningCredential {
+    id: string;
+    rawId: ArrayBuffer;
+    publicKey: {
+        x: string;
+        y: string;
+    };
+    pub: string;
+    hashedCredentialId: string;
+    gunUserPub?: string;
+}
+/**
+ * WebAuthn Signer - Provides oneshot signing functionality
+ * Similar to webauthn.js but integrated with our architecture
+ * CONSISTENT with normal WebAuthn approach
+ */
+export declare class WebAuthnSigner {
+    private webauthn;
+    private credentials;
+    constructor(webauthn?: Webauthn);
+    /**
+     * Creates a new WebAuthn credential for signing
+     * Similar to webauthn.js create functionality but CONSISTENT with normal approach
+     */
+    createSigningCredential(username: string): Promise<WebAuthnSigningCredential>;
+    /**
+     * Creates an authenticator function compatible with SEA.sign
+     * This is the key function that makes it work like webauthn.js
+     */
+    createAuthenticator(credentialId: string): (data: any) => Promise<AuthenticatorAssertionResponse>;
+    /**
+     * Creates a derived key pair from WebAuthn credential
+     * CONSISTENT with normal approach: uses hashedCredentialId as password
+     */
+    createDerivedKeyPair(credentialId: string, username: string, extra?: string[]): Promise<{
+        pub: string;
+        priv: string;
+        epub: string;
+        epriv: string;
+    }>;
+    /**
+     * Creates a Gun user from WebAuthn credential
+     * This ensures the SAME user is created as with normal approach
+     * FIX: Use derived pair instead of username/password for GunDB auth
+     */
+    createGunUser(credentialId: string, username: string, gunInstance: any): Promise<{
+        success: boolean;
+        userPub?: string;
+        error?: string;
+    }>;
+    /**
+     * Signs data using WebAuthn + derived keys
+     * This provides a hybrid approach: WebAuthn for user verification + derived keys for actual signing
+     * CONSISTENT with normal approach
+     */
+    signWithDerivedKeys(data: any, credentialId: string, username: string, extra?: string[]): Promise<string>;
+    /**
+     * Get the Gun user public key for a credential
+     * This allows checking if the same user would be created
+     */
+    getGunUserPub(credentialId: string): string | undefined;
+    /**
+     * Get the hashed credential ID (for consistency checking)
+     */
+    getHashedCredentialId(credentialId: string): string | undefined;
+    /**
+     * Check if this credential would create the same Gun user as normal approach
+     */
+    verifyConsistency(credentialId: string, username: string, expectedUserPub?: string): Promise<{
+        consistent: boolean;
+        actualUserPub?: string;
+        expectedUserPub?: string;
+    }>;
+    /**
+     * Get credential by ID
+     */
+    getCredential(credentialId: string): WebAuthnSigningCredential | undefined;
+    /**
+     * List all stored credentials
+     */
+    listCredentials(): WebAuthnSigningCredential[];
+    /**
+     * Remove a credential
+     */
+    removeCredential(credentialId: string): boolean;
+}
+export default WebAuthnSigner;