cerceis-lib/src/obfuscator/README.md

Contains list of quality of life functions that is written in TypeScript and es6

# Obfuscator

Small reversible string obfuscation helpers.

This module is for making values less readable in logs, URLs, fixtures, or casual storage. It is not encryption and should not be used to protect passwords, tokens, private keys, or other real secrets.

## Recommended API

```ts
import { obfuscator } from "cerceis-lib/obfuscator";

const key = "my-app-key";

const encoded = obfuscator.encode("hello world", { key });
const decoded = obfuscator.decode(encoded, { key });

console.log(encoded); // cob:v4:<salt>:<payload>
console.log(decoded); // hello world
```

`encode` uses V4 by default. V4 converts the string to UTF-8 bytes, derives a deterministic pseudo-random byte stream from the key and stored salt, masks each byte, rotates it, and stores the result as base64url.

The salt is included in the output, so the same string and key can produce different encoded values while still being decoded with the same key.

## Direct V4 API

```ts
import { obfuscator } from "cerceis-lib/obfuscator";

const encoded = obfuscator.obfuscatev4("Cerceis", "secret-key");
const decoded = obfuscator.deobfuscatev4(encoded, "secret-key");
```

V4 output uses this format:

```txt
cob:v4:<salt>:<payload>
```

## Legacy Versions

The older methods are still available for compatibility:

```ts
const v1 = obfuscator.obfuscate("hello", "key");
obfuscator.deobfuscate(v1, "key");

const v2 = obfuscator.obfuscatev2("hello");
obfuscator.deobfuscatev2(v2);

const v3 = obfuscator.obfuscatev3("hello", "key");
obfuscator.deobfuscatev3(v3, "key");
```

You can also route through the preferred API:

```ts
obfuscator.encode("hello", { version: "v3", key: "key" });
obfuscator.decode(v3, { version: "v3", key: "key" });
```

## Notes

- V4 requires a non-empty key.
- V2 does not use a key.
- Legacy `obfuscate()` can generate a random key if none is passed, but then the result cannot be decoded.
- Wrong keys usually decode to unreadable text, not an explicit authentication error.