> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westyx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK - File-type secret security

> What the SDK guarantees about a materialised file-type secret: mode, directory, filename, and removal.

A `file`-type secret is materialised on disk so that tools which need a *path* can use it - a TLS library reading a certificate, a cloud SDK reading a credentials file, a database driver reading a client key.

`getSecretFilePath(key)` returns that path. This page states what the SDK guarantees about the file it hands you.

## The guarantees

| Property                 | Guarantee                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------- |
| Directory                | A freshly created private directory per client instance: mode `0700`, name unguessable |
| File mode                | `0600` - owner read/write only                                                         |
| When the mode is applied | At **creation**, as a parameter of the `open`, never by a `chmod` afterwards           |
| Existing path            | Removed first, then created with `O_EXCL`                                              |
| Symbolic links           | `O_NOFOLLOW`; a link at the target path is removed rather than followed                |
| Filename                 | Hashes of the key and the value - neither appears in clear                             |
| Removal                  | On `close()`, and on process exit                                                      |

## Why the mode is applied at creation

Passing a mode is not the same as the file landing with it, and the difference is not obvious.

Node's documentation is explicit: the `mode` option "only affects the newly created file". Writing over a path that already exists therefore leaves that file's own permissions in place - so a leftover from an earlier run at looser permissions would receive the new secret and keep them.

Creating exclusively is what closes that: the SDK removes any leftover, then opens with `O_CREAT | O_EXCL` and the mode, so `0600` is what the file is created with, every time.

A `chmod` after the write would be worse still. It leaves a window - however short - in which the secret exists on disk at the process umask, which in a shared temp directory typically means readable by every local user on the host.

## Why the directory is per instance

The path is derived from the secret's key and value. If that were all, two clients holding the same secret would resolve to the same file, and whichever was disposed first would unlink it out from under the other - which then hands out a path to a file that no longer exists. Where the temp directory is shared across processes, that collision is not even limited to one process.

Each `NexusClient` therefore owns a directory created by `mkdtemp`, which gives both an unguessable name and mode `0700`. Two clients holding an identical secret get different paths, and disposing one cannot affect the other.

## Why the filename carries hashes

The path is handed to your application, and paths travel: into log lines, into environment variables passed to a child process, into a process listing, into a container inspection.

So the filename is `nexus-<key-hash>-<value-hash>`, where each is a truncated SHA-256. Neither the secret's name - which describes what it is for - nor its value appears in clear anywhere on the filesystem.

## Removal

`close()` deletes the files and the directory. A process-exit hook does the same, so an ordinary exit that forgot to call `close()` does not leave secrets behind.

**A process killed by a signal can leave them.** This is deliberate: installing a SIGINT or SIGTERM listener suppresses Node's default termination, so a library doing it would silently change how your application responds to Ctrl-C. What is left behind is `0600` inside a `0700` directory owned by the same user, which is the same protection it had while running.

If your deployment needs certainty here, enable your framework's shutdown hooks and call `close()` from them - [the NestJS module](/sdks/nodejs/nestjs) does this for you.

## On Windows

There is no `0600` equivalent, and `O_NOFOLLOW` does not exist. The file inherits the temp directory's ACL. This caveat applies to every Nexus SDK; on Windows, prefer text-type secrets where the choice is yours.

## Next

* [API reference](/sdks/nodejs/api-reference)
* [Logging](/sdks/nodejs/logging) - secrets never reach the logger either