Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jozan/secret
a simple utility library to prevent leaking secrets
https://github.com/jozan/secret
Last synced: 3 months ago
JSON representation
a simple utility library to prevent leaking secrets
- Host: GitHub
- URL: https://github.com/jozan/secret
- Owner: jozan
- License: mit
- Created: 2024-04-15T17:34:45.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-08-18T21:36:04.000Z (6 months ago)
- Last Synced: 2024-11-07T09:08:26.160Z (3 months ago)
- Language: TypeScript
- Size: 115 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# `secret` 🤫
[](https://bundlejs.com/?q=%40latehours/secret)
**`secret`** is a simple utility library for handling sensitive data in any
typescript app. no more leaking tokens or emails into logs by accident.
is has **zero dependencies** and has fairly exhaustive test coverage.
### motivation
`secret` makes revealing the secret value explicit and intentional. it
prevents accidental leaking of secrets into logs, stdout, JSON.stringify
calls, writes to files and so on by the developer.
keep in mind that the secret is still stored in memory unencrypted and can be
read by a debugger or by inspecting the memory of the process. this is not a
security library. continue to use encryption for sensitive data.
behind the scenes the secret is stored in javascript object as a bytes array,
not plaintext. this is more security by obscurity than anything else.
## usage
install the library using your package manager of choice:
```sh
npm install @latehours/secret
pnpm install @latehours/secret
bun add @latehours/secret
yarn add @latehours/secret
```
usage in your code:
```typescript
import * as Secret from "@latehours/secret";
// conceal a string into a secret
const hidden = Secret.fromString("tussihovi");
console.log(hidden); // logs [REDACTED]
// convert the secret back to a string
const exposed = Secret.expose(hidden);
```
#### considerations
when wrapping a value into a secret such as in `io-ts` or `zod` schema make
sure to clean up any intermediate secrets such as the unparsed input.
sending a secret over the network is not possible as the secret is not
serializable by design. use encryption for that or better yet, don't handle the
secret at all.
### usage as a `Secret` `class`
sometimes it can be more convenient to wrap the secret into a class and pass it
around in your app. this way one doesn't need to litter codebase with
`@latehours/secret` imports.
example code:
```typescript
import { fromString, expose } from "@latehours/secret"
import type { Secret as SecretInternal } from "@latehours/secret"
class Secret {
secret: SecretInternal
constructor(value: string) {
this.secret = fromString(value)
}
expose() {
return expose(this.secret)
}
toString() {
return this.secret.toString()
}
}
export function createSecret(value: string) {
return new Secret(value)
}
```
### `io-ts` codec
provided for convenience. check out tests for exported `io-ts` `decoder` and
`encoder` for usage.
you need to have `fp-ts` and `io-ts` installed in your project.
```typescript
import { SecretCodec } from "@latehours/secret/io-ts";
import { pipe } from "fp-ts/function";
import { fold } from "fp-ts/Either";
pipe(
"tussihovi",
SecretCodec.decode,
fold(
() => {
expect.unreachable("decoding should not fail");
},
(secret) => {
const exposed = SecretCodec.encode(secret);
expect(exposed).toEqual("tussihovi");
}
)
);
```
### `zod` schema
provided for convenience.
you need to have `zod` installed in your project.
```typescript
import * as Secret from "@latehours/secret";
import { Secret as SecretSchema } from "@latehours/secret/zod";
const secret = SecretSchema.safeParse(input);
if (secret.success) {
expect(Secret.isSecret(secret.data)).toBe(true);
const exposed = Secret.expose(secret.data);
expect(exposed).toEqual(input);
}
```
## acknowledgements
the idea for this library came from the rust cargo [`secrecy`](https://docs.rs/secrecy/latest/secrecy/).
the implementation is based on the following libraries:
- [`secret-value`](https://github.com/transcend-io/secret-value)
- [`effect/secret`](https://github.com/Effect-TS/effect/blob/main/packages/effect/src/internal/secret.ts)
this improves on the above libraries by hiding the raw value of the secret
(bytes array) from leaking when calling `console.log` or `utils.inspect` on the
secret object. also the raw value is not retrievable by object access.
## development
To install dev dependencies:
```bash
bun install
```
To run tests:
```bash
bun --watch test
```
when creating commits follow the [conventional commits](https://www.conventionalcommits.org)
format.