npm package: @synet/hasher
Description: Conscious Cryptographic Hashing Unit with SHA3-512 quantum readiness
Author: Synet Team
Latest version: 1.0.3

# @synet/hasher

**Stop wrestling with crypto libraries.** Hash anything, verify everything, teach AI agents to do it for you.

```typescript
import { Hasher } from '@synet/hasher';

// Works exactly like you'd expect
const hasher = Hasher.create();
const hash = hasher.sha256('Hello World');
console.log(hash); // ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

// But then it gets interesting...
const smith = Smith.create({ ai });
smith.learn([hasher.teach()]); // Now Smith can hash anything
await smith.run("Hash all files in ./docs and save report");
```

## Why This Exists

You've been there: 
- Crypto.createHash('sha256').update(data).digest('hex') for the millionth time
- Forgetting which algorithm to use for which use case
- Building password hashing that doesn't suck
- Writing the same verification logic over and over

**Then AI agents happened.** And suddenly you need crypto that can be used reliably with AI Agents.

This is that library.

## Quick Start

```bash
npm install @synet/hasher
```

```typescript
import { Hasher, sha256 } from '@synet/hasher';

// Option 1: Traditional approach
const hash = sha256('data');

// Option 2: Unit approach (more powerful)
const hasher = Hasher.create();
const result = hasher.hash('data', { algorithm: 'sha512' });

// Option 3: AI agent approach (magic happens)
const agent = Switch.create({ ai });
agent.learn([hasher.teach()]);
await agent.run("Hash the user passwords and save to secure-hashes.json");
```

## Real-World Examples

### Password Hashing That Doesn't Suck
```typescript
const hasher = Hasher.create();

// Register user
const saltedHash = hasher.hashPassword('user_password', 'random_salt', 10000);
// Store: { hash: saltedHash, salt: 'random_salt', iterations: 10000 }

// Login verification
const isValid = hasher.verify('user_password', storedHash);
```

### File Integrity Checking
```typescript
import { AsyncFileSystem } from '@synet/fs';

const hasher = Hasher.create();
const fs = AsyncFileSystem.create();

// Teach hasher about files
hasher.learn([fs.teach()]);

// Now it can hash files
const fileContent = await hasher.execute('fs-async.readFile', 'important.pdf');
const integrity = hasher.sha256(fileContent);
```

### AI Agent Integration
```typescript
import { Smith } from '@synet/agent';

const hasher = Hasher.create();
const agent = Smith.create({ ai, agent });

// Teach the agent to hash things
agent.learn([hasher.teach()]);

// Let AI handle the crypto
await agent.run(`
  Generate SHA256 hashes for all JSON files in ./config
  Create a manifest.json with filename -> hash mapping
  Verify no files have been tampered with
`);
```

## Algorithms That Matter

We included the ones you actually use:

- **SHA256** (default) - Bitcoin, most APIs, general purpose
- **SHA512** - When you need stronger SHA-2
- **SHA3-512** - Post-quantum ready
- **BLAKE2b** - Fastest secure option
- **MD5/SHA1** - Legacy (marked deprecated, but you still need them)

```typescript
const hasher = Hasher.create();

hasher.sha256('data');    // Most common
hasher.sha512('data');    // Stronger
hasher.sha3_512('data');  // Future-proof
hasher.blake2b('data');   // Fastest
hasher.md5('data');       // Legacy (don't use for new stuff)
```

## Features You'll Use

### Timing-Safe Comparisons
```typescript
// Prevents timing attacks
const isEqual = hasher.compare(hash1, hash2);
```

### HMAC Authentication
```typescript
const signature = hasher.hmac('message', 'secret_key');
const isValid = hasher.verifyHmac('message', signature, 'secret_key');
```

### Encoding Options
```typescript
hasher.hash('data', { encoding: 'hex' });      // Default
hasher.hash('data', { encoding: 'base64' });   // Shorter
hasher.hash('data', { encoding: 'base64url' }); // URL-safe
```

## AI Agent Superpowers

This is where it gets interesting. The Hasher follows [Unit Architecture](https://github.com/synthetism/unit), which means:

### Teaching AI Agents
```typescript
const teachingContract = hasher.teach();
// Contains: hash, verify, hmac methods + schemas

agent.learn([hasher.teach()]);
// Agent now knows: "To hash data, call hasher.hash with these parameters..."
```

### AI Agents Teaching Back
```typescript
import { FileSystem } from '@synet/fs';

const fs = FileSystem.create();
hasher.learn([fs.teach()]);

// Hasher learned file operations
const fileHash = await hasher.execute('fs.readFile', 'data.txt')
  .then(content => hasher.sha256(content));
```

### Real Agent Scenarios
```typescript
// Scenario: Security audit
await agent.run(`
  1. Hash all source files in ./src
  2. Compare with known-good-hashes.json  
  3. Report any files that changed
  4. Generate new integrity manifest
`);

// Scenario: Password migration
await agent.run(`
  1. Read user passwords from old-system.db
  2. Re-hash with SHA256 + salt + 10000 iterations
  3. Save to new-system.db with proper schema
`);
```

## Error Handling

Throws on programmer errors, returns `false` on data errors:

```typescript
// Throws (your bug)
hasher.hash('data', { algorithm: 'invalid' }); 

// Returns false (bad data)
hasher.verify('data', 'malformed-hash'); // false, doesn't throw
```

## Performance

Benchmarked on real data:
- SHA256: ~500MB/s
- SHA512: ~350MB/s  
- BLAKE2b: ~800MB/s
- Timing-safe compare: constant time regardless of input

## Testing

```bash
npm test           # Run tests
npm run benchmark  # Performance tests
npm run demo      # See it working with AI agents
```

## When To Use This vs crypto

**Use Node's `crypto` when:**
- Building a simple API
- One-off hashing needs
- Maximum performance critical

**Use `@synet/hasher` when:**
- Building with AI agents
- Need teaching/learning capabilities
- Want better error handling
- Working with SYNET ecosystem

## Real Projects Using This

- **Agent Smith** - AI agents for file integrity
- **SYNET Network** - Identity verification  
- **Crypto Trading Bots** - API signature verification
- **Document Verification** - Legal document integrity

## What's Next

```typescript
import { Switch } from '@synet/agent';
import { Hasher } from '@synet/hasher';

const agent = Switch.create({ ai });
const hasher = Hasher.create();

agent.learn([hasher.teach()]);

// The future is AI agents that understand crypto
await agent.run("Build a document integrity system");
```

Want to see more? Check out [@synet/agent](https://github.com/synthetism/agent) and [Unit Architecture](https://github.com/synthetism/unit).

## License

MIT - Build whatever you want.