### Install @shellicar/core-config package

Source: https://github.com/shellicar/core-config/blob/main/packages/core-config/README.md

Commands to install the library using common Node.js package managers.

```bash
npm i --save @shellicar/core-config
```

```bash
pnpm add @shellicar/core-config
```

--------------------------------

### Install Shellicar Core Config

Source: https://context7.com/shellicar/core-config/llms.txt

Instructions for installing the library using common Node.js package managers.

```bash
npm install @shellicar/core-config
# or
pnpm add @shellicar/core-config
```

--------------------------------

### Implement Custom Encryption Provider with TypeScript

Source: https://context7.com/shellicar/core-config/llms.txt

This snippet shows how to implement a custom encryption provider by creating a class that adheres to the IEncryptionProvider interface. The example demonstrates a 'VaultEncryptionProvider' that simulates fetching secrets from an external vault. It integrates with the core-config factory to secure sensitive string values.

```typescript
import { createFactory, type IEncryptionProvider, type IEncryptedValue } from '@shellicar/core-config';

// Custom encryption provider using external vault
class VaultEncryptionProvider implements IEncryptionProvider {
  encrypt(value: string): IEncryptedValue {
    return {
      getValue: () => value, // Decrypt from vault in real implementation
      toString: () => '[VaultSecret]',
      toJSON: () => ({ type: 'VaultSecret', encrypted: true }),
    };
  }
}

const factory = createFactory({
  encryptionProvider: new VaultEncryptionProvider(),
});

const secret = factory.string('mySecret');
console.log(secret.toString()); // sha256:... (hash is independent of encryption)
```

--------------------------------

### Real World Example: Zod Environment Validation with @shellicar/core-config

Source: https://github.com/shellicar/core-config/blob/main/README.md

Shows how to integrate @shellicar/core-config with Zod for validating and securing environment variables. It demonstrates transforming raw environment variables into secure types.

```typescript
import { env } from 'node:process';
import { createFactory } from '@shellicar/core-config';
import { z } from 'zod';

const factory = createFactory();

const envSchema = z.object({
  // MongoDB connection string with username/password
  MONGODB_URL: z.url().transform((x) => factory.url(new URL(x))),

  // API key for external service
  API_KEY:
    z
      .string()
      .min(1)
      .transform((x) => factory.string(x)),

  // SQL Server connection string
  SQL_CONNECTION: z.string().transform((x) => factory.connectionString(x)),
});

// Parse environment variables
const config = envSchema.parse(env);

// Values are now strongly typed and secured
console.log(config.MONGODB_URL.toString());
// mongodb://myuser:sha256%3A...@mongodb.example.com/

console.log(config.API_KEY.toString());
// sha256:...

console.log(config.SQL_CONNECTION.toString());
// Server=myserver;Database=mydb;User Id=admin;Password=sha256:...
```

--------------------------------

### Initialize and use configuration factory

Source: https://github.com/shellicar/core-config/blob/main/packages/core-config/README.md

Demonstrates how to import the factory, instantiate it, and process sensitive strings, connection strings, and URLs.

```typescript
import { createFactory } from '@shellicar/core-config';

const factory = createFactory();

console.log(factory.string('myPassword123'));
console.log(factory.connectionString('Server=myserver.uri;Password=myPassword123'));
console.log(factory.url(new URL('http://myuser:myPassword123@myserver.uri')));
```

--------------------------------

### Initialize Factory with createFactory

Source: https://context7.com/shellicar/core-config/llms.txt

Demonstrates how to instantiate a factory for generating secure types, including support for HMAC secrets and custom secret key definitions.

```typescript
import { createFactory } from '@shellicar/core-config';

// Basic factory with SHA-256 hashing
const factory = createFactory();

// Factory with HMAC secret for verifiable hashes
const hmacFactory = createFactory({ secret: 'myHmacSecret' });

// Factory with custom secret keys for connection strings
const customFactory = createFactory({
  secretKeys: ['CustomKey', 'MyToken', 'PrivateKey']
});

// Use factory methods
const secureString = factory.string('myPassword123');
const secureConn = factory.connectionString('Server=db.example.com;Password=secret123');
const secureUrl = factory.url(new URL('https://user:pass@example.com'));
```

--------------------------------

### Handle Connection Strings with @shellicar/core-config

Source: https://github.com/shellicar/core-config/blob/main/README.md

Shows how to securely handle connection strings using the `connectionString` method. It demonstrates default behavior and custom secret key handling.

```typescript
import { createFactory } from '@shellicar/core-config';

const factory = createFactory();
const conn = factory.connectionString('Server=myserver;Password=myPassword123');
console.log(conn.toString());
// Server=myserver;Password=sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716

// Custom secret keys
console.log(factory.connectionString('Server=myserver;SuperSecretKey=myPassword123', ['SuperSecretKey']));
// {
//   Server: 'myserver',
//   SuperSecretKey: 'sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716'
// }
```

--------------------------------

### Handle Strings with @shellicar/core-config

Source: https://github.com/shellicar/core-config/blob/main/README.md

Demonstrates how to use the `createFactory` and `string` methods to securely handle string data. The output shows the hashed representation of the string.

```typescript
import { createFactory } from '@shellicar/core-config';

const factory = createFactory();
const secret = factory.string('myPassword123');

console.log(secret.toString()); 
// sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716

console.log(JSON.stringify({ secret }));
// {"secret":"sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716"}
```

--------------------------------

### Secure Connection Strings with SecureConnectionString

Source: https://context7.com/shellicar/core-config/llms.txt

Demonstrates parsing and automatic hashing of sensitive keys within connection strings, supporting custom key definitions and case-insensitive matching.

```typescript
import { createFactory } from '@shellicar/core-config';

const factory = createFactory();

// SQL Server connection string
const sqlConn = factory.connectionString(
  'Server=myserver.database.windows.net;Database=mydb;User Id=admin;Password=secret123'
);

console.log(sqlConn.toString());

// JSON serialization returns key-value object
console.log(JSON.stringify(sqlConn, null, 2));

// Azure Service Bus connection string
const serviceBusConn = factory.connectionString(
  'Endpoint=sb://mynamespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=myAccessKey123'
);
console.log(serviceBusConn.toString());

// Access original connection string
const originalConn = sqlConn.secretValue;

// Custom secret keys (only hash specified keys)
const customFactory = createFactory({ secretKeys: ['MyCustomSecret', 'PrivateToken'] });
const customConn = customFactory.connectionString(
  'Server=myserver;MyCustomSecret=value123;PrivateToken=token456;PublicKey=visible'
);
console.log(customConn.toString());
```

--------------------------------

### Handle URLs with Passwords using @shellicar/core-config

Source: https://github.com/shellicar/core-config/blob/main/README.md

Illustrates how to securely handle URLs containing passwords using the `url` method. The output shows the secured URL and its components.

```typescript
import { createFactory } from '@shellicar/core-config';

const factory = createFactory();
const url = new URL('https://user:myPassword123@example.com?key=value');
const secureUrl = factory.url(url);

console.log(secureUrl.toString());
// https://user:sha256%3A71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716@example.com/?key=value

console.log(secureUrl);
// {
//   href: 'https://user@example.com/',
//   password: 'sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716',
//   searchParams: { key: 'value' }
// }
```

--------------------------------

### Use HMAC with @shellicar/core-config

Source: https://github.com/shellicar/core-config/blob/main/README.md

Demonstrates the use of HMAC for securing data by initializing the factory with a secret key. This affects how strings are hashed.

```typescript
import { createFactory } from '@shellicar/core-config';

const factory = createFactory({ secret: 'mySecret' });
const secret = factory.string('myPassword123');

console.log(secret.toString()); 
// sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716

console.log(JSON.stringify({ secret }));
// {"secret":"sha256:71d4ec024886c1c8e4707fb02b46fd568df44e77dd5055cadc3451747f0f2716"}
```

--------------------------------

### Manage Sensitive Strings with SecureString

Source: https://context7.com/shellicar/core-config/llms.txt

Shows how to wrap sensitive strings to ensure they are hashed during logging and JSON serialization, while allowing access to the original value.

```typescript
import { createFactory } from '@shellicar/core-config';

const factory = createFactory();
const secret = factory.string('myPassword123');

// toString() returns hash
console.log(secret.toString());

// Safe for JSON serialization
console.log(JSON.stringify({ apiKey: secret }));

// Access original value when needed
const originalValue = secret.secretValue;

// With HMAC secret for verifiable hashes
const hmacFactory = createFactory({ secret: 'mySecret' });
const hmacSecret = hmacFactory.string('myPassword123');
console.log(hmacSecret.toString());
```

--------------------------------

### Managing Secure Keys for Automatic Hashing

Source: https://context7.com/shellicar/core-config/llms.txt

The defaultSecureKeys constant defines a list of keys that are automatically treated as secrets. Users can extend this list when initializing the configuration factory.

```typescript
import { defaultSecureKeys, createFactory } from '@shellicar/core-config';

const factory = createFactory({
  secretKeys: [...defaultSecureKeys, 'MyCustomKey', 'InternalToken']
});
```

--------------------------------

### Environment Variable Validation with Zod

Source: https://context7.com/shellicar/core-config/llms.txt

Integrate core-config with Zod schemas to transform raw environment variables into secure types. This ensures that sensitive data is automatically protected upon application startup.

```typescript
import { env } from 'node:process';
import { createFactory } from '@shellicar/core-config';
import { z } from 'zod';

const factory = createFactory();
const envSchema = z.object({
  MONGODB_URL: z.string().url().transform((x) => factory.url(new URL(x))),
  API_KEY: z.string().min(1).transform((x) => factory.string(x))
});

const config = envSchema.parse(env);
```

--------------------------------

### Secure URL Password Hashing with SecureURL

Source: https://context7.com/shellicar/core-config/llms.txt

The SecureURL class wraps standard URL objects to automatically hash password components. It provides safe string and JSON representations while allowing access to the original URL via the secretValue property.

```typescript
import { createFactory } from '@shellicar/core-config';

const factory = createFactory();
const mongoUrl = factory.url(new URL('mongodb://myuser:myPassword123@mongodb.example.com:27017/mydb?authSource=admin'));

console.log(mongoUrl.toString());
console.log(JSON.stringify(mongoUrl, null, 2));
const originalUrl = mongoUrl.secretValue;
```

--------------------------------

### In-memory Secret Encryption with EncryptedValue

Source: https://context7.com/shellicar/core-config/llms.txt

EncryptedValue utilizes AES-256-GCM to protect sensitive strings in memory. It provides safe logging outputs and a getValue() method to retrieve the decrypted plaintext.

```typescript
import { EncryptedValue } from '@shellicar/core-config';

const encrypted = new EncryptedValue('mySensitiveData');
console.log(encrypted.toString());
const decrypted = encrypted.getValue();
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.