feat, small refactoring + helper functions

Author: merl111

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axlabs/neofs-sdk-ts-core",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Shared core code for NeoFS TypeScript SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/crypto/ecdsa/signer.ts

@@ -1,5 +1,6 @@
 import { sha256, sha512 } from '../../utils/crypto';
 import { randomBytes } from '../../utils/buffer';
+import { base58Decode } from '../../utils/base58';
 import { ec as EC } from 'elliptic';
 import { Scheme, PublicKey } from '../scheme';
 import { Signer } from '../signer';
@@ -49,8 +50,7 @@ export class ECDSASigner implements Signer {
   static decodeWIF(wif: string): Uint8Array {
     if (!wif) throw new Error('WIF cannot be null');
 
-    // Decode Base58
-    const data = this.base58Decode(wif);
+    const data = base58Decode(wif);
 
     // Neo WIF format: 0x80 + 32 bytes private key + checksum
     if (data.length < 33 || data[0] !== 0x80) {
@@ -64,38 +64,6 @@ export class ECDSASigner implements Signer {
     return privateKey;
   }
 
-  /**
-   * Base58 decoding implementation.
-   */
-  private static base58Decode(encoded: string): Uint8Array {
-    const alphabet = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
-    let value = 0n;
-    
-    // Decode Base58 string to BigInteger
-    for (let i = 0; i < encoded.length; i++) {
-      const digit = alphabet.indexOf(encoded[i]);
-      if (digit < 0) {
-        throw new Error(`Invalid Base58 character '${encoded[i]}' at position ${i}`);
-      }
-      value = value * 58n + BigInt(digit);
-    }
-    
-    // Convert BigInteger to byte array
-    const leadingZeros = encoded.match(/^1+/)?.[0].length || 0;
-    const bytes = [];
-    
-    while (value > 0n) {
-      bytes.unshift(Number(value & 0xFFn));
-      value = value >> 8n;
-    }
-    
-    // Add leading zeros
-    const result = new Uint8Array(leadingZeros + bytes.length);
-    result.set(bytes, leadingZeros);
-    
-    return result;
-  }
-
   /**
    * Generates a new random ECDSA key pair.
    */

src/crypto/index.ts

@@ -1,5 +1,6 @@
 export * from './scheme';
 export * from './signer';
+export * from './signer-factory';
 export * from './signature';
 export * from './ecdsa';
 export * from './util';

src/crypto/signer-factory.ts

@@ -0,0 +1,48 @@
+/**
+ * Unified signer factory that auto-detects key format.
+ */
+
+import { hexToBytes } from '../utils/buffer';
+import { Signer } from './signer';
+import { ECDSASigner } from './ecdsa';
+
+/**
+ * Create an {@link ECDSASigner} from a private key string.
+ *
+ * Accepts two formats:
+ *
+ * - **WIF** (Wallet Import Format): a Base58Check-encoded string
+ *   (e.g. `L1aW4aubDFB7yfras2S1mN3bqg9nwySY8nkoLmJebSLD5BWv3ENZ`)
+ * - **Hex**: a 64-character hex string with optional `0x` prefix
+ *   (e.g. `0xabcdef0123456789...` or `abcdef0123456789...`)
+ *
+ * @throws Error if the key cannot be parsed in either format
+ *
+ * @example
+ * ```ts
+ * import { createSigner } from '@axlabs/neofs-sdk-ts-core';
+ *
+ * const signer = createSigner(process.env.NEOFS_PRIVATE_KEY!);
+ * const client = new NeoFSClient({ endpoint, signer });
+ * ```
+ */
+export function createSigner(privateKey: string): Signer {
+  const trimmed = privateKey.trim();
+  const hex = trimmed.toLowerCase().replace(/^0x/, '');
+
+  // Try hex first (64 hex chars = 32 bytes)
+  if (/^[0-9a-f]+$/i.test(hex) && hex.length === 64) {
+    return ECDSASigner.fromPrivateKeyBytes(hexToBytes(hex));
+  }
+
+  // Try WIF
+  try {
+    return ECDSASigner.fromWIF(trimmed);
+  } catch {
+    // fall through
+  }
+
+  throw new Error(
+    'Invalid private key: expected 64-char hex (with optional 0x prefix) or WIF (Base58Check).',
+  );
+}

src/types/enums.ts

@@ -0,0 +1,50 @@
+/**
+ * NeoFS protocol enums derived from the protobuf definitions.
+ * These are re-exported by platform-specific SDKs (node, react-native).
+ */
+
+/**
+ * Search filter match types for object attribute queries.
+ *
+ * Values correspond to the NeoFS protobuf `MatchType` enum.
+ * IMPORTANT: `UNSPECIFIED` (0) is the protobuf default and is NOT serialized
+ * on the wire — using it in a search filter effectively disables the filter.
+ * Always use an explicit match type like `STRING_EQUAL`.
+ */
+export enum MatchType {
+  UNSPECIFIED = 0,
+  STRING_EQUAL = 1,
+  STRING_NOT_EQUAL = 2,
+  NOT_PRESENT = 3,
+  COMMON_PREFIX = 4,
+  NUM_GT = 5,
+  NUM_GE = 6,
+  NUM_LT = 7,
+  NUM_LE = 8,
+}
+
+/**
+ * Checksum algorithm identifiers used in object headers.
+ *
+ * Values correspond to the NeoFS protobuf `ChecksumType` enum.
+ */
+export enum ChecksumType {
+  CHECKSUM_TYPE_UNSPECIFIED = 0,
+  /** Tillich-Zémor homomorphic hash */
+  TZ = 1,
+  /** SHA-256 */
+  SHA256 = 2,
+}
+
+/**
+ * Object types in NeoFS.
+ *
+ * Values correspond to the NeoFS protobuf `ObjectType` enum.
+ */
+export enum ObjectType {
+  REGULAR = 0,
+  TOMBSTONE = 1,
+  STORAGE_GROUP = 2,
+  LOCK = 3,
+  LINK = 4,
+}

src/types/index.ts

@@ -1,4 +1,5 @@
 export { Decimal } from './decimal';
+export * from './enums';
 
 export interface ContainerID {
   value: Uint8Array;
@@ -12,3 +13,22 @@ export interface Address {
   containerId: ContainerID;
   objectId: ObjectID;
 }
+
+/** Object header attribute as returned by the NeoFS API. */
+export interface ObjectAttribute {
+  key: string;
+  value: string;
+}
+
+/** Object header as returned by head / get operations. */
+export interface ObjectHeader {
+  containerId?: ContainerID;
+  ownerId?: Uint8Array;
+  attributes?: ObjectAttribute[];
+  payloadLength?: number;
+  payloadHash?: { type: number; sum: Uint8Array };
+  homomorphicHash?: { type: number; sum: Uint8Array };
+  objectType?: number;
+  version?: { major: number; minor: number };
+  creationEpoch?: number;
+}

src/utils/base58.ts

@@ -0,0 +1,59 @@
+/**
+ * Base58 encoding/decoding (Bitcoin alphabet).
+ * Extracted from ECDSASigner so it can be shared across the SDK.
+ */
+
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+/**
+ * Decodes a Base58-encoded string to bytes.
+ *
+ * @throws Error if the string contains invalid Base58 characters
+ */
+export function base58Decode(encoded: string): Uint8Array {
+  let value = 0n;
+
+  for (let i = 0; i < encoded.length; i++) {
+    const digit = ALPHABET.indexOf(encoded[i]);
+    if (digit < 0) {
+      throw new Error(`Invalid Base58 character '${encoded[i]}' at position ${i}`);
+    }
+    value = value * 58n + BigInt(digit);
+  }
+
+  const leadingZeros = encoded.match(/^1+/)?.[0].length || 0;
+  const bytes: number[] = [];
+
+  while (value > 0n) {
+    bytes.unshift(Number(value & 0xFFn));
+    value = value >> 8n;
+  }
+
+  const result = new Uint8Array(leadingZeros + bytes.length);
+  result.set(bytes, leadingZeros);
+
+  return result;
+}
+
+/**
+ * Encodes bytes to a Base58 string.
+ */
+export function base58Encode(bytes: Uint8Array): string {
+  let value = 0n;
+  for (const b of bytes) {
+    value = value * 256n + BigInt(b);
+  }
+
+  let encoded = '';
+  while (value > 0n) {
+    encoded = ALPHABET[Number(value % 58n)] + encoded;
+    value = value / 58n;
+  }
+
+  for (const b of bytes) {
+    if (b !== 0) break;
+    encoded = '1' + encoded;
+  }
+
+  return encoded || '1';
+}

src/utils/checksum.ts

@@ -0,0 +1,38 @@
+/**
+ * Payload checksum helpers for NeoFS object headers.
+ */
+
+import { ChecksumType } from '../types/enums';
+import { sha256 } from './crypto';
+import { tzHash } from '../crypto/tz';
+
+/**
+ * Compute both SHA-256 and Tillich-Zémor (TZ) checksums for an object payload.
+ *
+ * NeoFS object headers require `payloadHash` (SHA-256) and `homomorphicHash` (TZ).
+ * This helper produces both in the format expected by the `ObjectClient.put()` header.
+ *
+ * @example
+ * ```ts
+ * const checksums = payloadChecksums(payload);
+ * await objectClient.put({
+ *   header: { containerId, ownerId, ...checksums },
+ *   payload,
+ * });
+ * ```
+ */
+export function payloadChecksums(payload: Uint8Array): {
+  payloadHash: { type: number; sum: Uint8Array };
+  homomorphicHash: { type: number; sum: Uint8Array };
+} {
+  return {
+    payloadHash: {
+      type: ChecksumType.SHA256,
+      sum: sha256(payload),
+    },
+    homomorphicHash: {
+      type: ChecksumType.TZ,
+      sum: tzHash(payload),
+    },
+  };
+}

src/utils/index.ts

@@ -1,2 +1,5 @@
 export * from './buffer';
+export * from './base58';
 export * from './crypto';
+export * from './checksum';
+export * from './neofs';

src/utils/neofs.ts

@@ -0,0 +1,75 @@
+/**
+ * NeoFS-specific utility helpers.
+ */
+
+import { ContainerID, ObjectAttribute } from '../types';
+import { hexToBytes } from './buffer';
+import { base58Decode } from './base58';
+
+/**
+ * Parse a container ID from a hex string (with optional `0x` prefix) or
+ * a Base58-encoded string into a {@link ContainerID}.
+ *
+ * @example
+ * ```ts
+ * const cid = toContainerId('CYzn4HPHXRmGW5cwvrqHtosd79kjBtVYAP3ykH6RCCAa');
+ * const cid2 = toContainerId('0xabcdef...');
+ * ```
+ *
+ * @throws Error if the string is not valid hex or Base58
+ */
+export function toContainerId(containerId: string): ContainerID {
+  const raw = containerId.trim();
+  const hex = raw.toLowerCase().replace(/^0x/, '');
+  if (/^[0-9a-f]+$/i.test(hex) && hex.length > 0 && hex.length % 2 === 0) {
+    return { value: hexToBytes(hex) };
+  }
+  try {
+    const bytes = base58Decode(raw);
+    return { value: bytes };
+  } catch {
+    throw new Error(
+      `Invalid container ID: expected hex (even length, optional 0x prefix) or Base58. Got: "${raw}"`,
+    );
+  }
+}
+
+/**
+ * Convert an array of `{ key, value }` object attributes (as returned by the
+ * NeoFS API) into a plain `Record<string, string>` for easier lookup.
+ *
+ * @example
+ * ```ts
+ * const head = await objectClient.head({ address, raw: false });
+ * const attrs = decodeAttributes(head.attributes);
+ * console.log(attrs['FileName']);
+ * ```
+ */
+export function decodeAttributes(
+  attrs?: ObjectAttribute[] | Array<{ key: string; value: string }>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (attrs) {
+    for (const a of attrs) out[a.key] = a.value;
+  }
+  return out;
+}
+
+/**
+ * Classify a NeoFS gRPC / SDK error as retryable.
+ *
+ * Returns `true` for transient failures such as expired sessions,
+ * authentication issues that may self-resolve after session renewal,
+ * and timeout / deadline errors.
+ */
+export function isRetryableNeoFSError(err: unknown): boolean {
+  const msg = String((err as any)?.message || (err as any)?.details || '');
+  return (
+    msg.includes('session') ||
+    msg.includes('expired') ||
+    msg.includes('UNAUTHENTICATED') ||
+    msg.includes('permission') ||
+    msg.includes('deadline') ||
+    msg.includes('timeout')
+  );
+}