secret 🤫

secret is a simple utility library for handling sensitive data in any typescript app. no more accidentally leaking tokens or emails into logs!

is has zero dependencies and has fairly exhaustive test coverage.

motivation

the main purpose is to prevent accidental leaking of secrets into logs, stdout, JSON.stringify calls, writes to files and so on by the developer. secret makes revealing the secret value explicit.

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 at rest.

behind the scenes the secret is stored in the secret object as a bytes array so it's not plaintext. but keep in mind that this is more security by obscurity than anything else.

usage

install the library using your package manager of choice:

npm install @latehours/secret
pnpm install @latehours/secret
bun add @latehours/secret
yarn add @latehours/secret

usage in your code:

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);

when wrapping a value into a secret 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.

io-ts codec

provided for convenience. check out tests for exported io-ts decoder and encoder usage.

you need to have io-ts installed in your project.

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.

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.

the implementation is based on the following libraries:

• secret-value
• effect/secret

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:

bun install

To run tests:

bun --watch test

when creating commits follow the conventional commits format.