@stackonward/server-boundary

Server-only primitives for two security boundaries: resolving private secret references and deriving the client IP from a finite trusted-proxy topology.

The package has no browser entry and provides no trust-all or hop-count mode.

Install

pnpm add @stackonward/server-boundary

Resolve a trusted client IP

import {
  NodeTrustedClientIpAdapter,
  TrustedClientIpResolver,
} from "@stackonward/server-boundary/server";

const resolver = new TrustedClientIpResolver(["127.0.0.0/8", "10.0.0.0/8"]);
const adapter = new NodeTrustedClientIpAdapter({
  mode: "strict",
  resolver,
});

const client = adapter.resolve({
  headers: request.headers,
  socket: { remoteAddress: request.socket.remoteAddress },
});

Forwarding headers are considered only when the socket peer is trusted. The resolver validates every address and returns the nearest untrusted address in the chain. Malformed or oversized topology fails with TrustedClientIpError.

strict mode requires a socket peer. local-development permits a missing socket only when there is exactly one forwarded loopback address; it is not a production proxy fallback.

Resolve a private secret

import { PrivateSecretResolver } from "@stackonward/server-boundary/server";

const secrets = new PrivateSecretResolver();
const sessionKey = await secrets.resolve("env://SESSION_KEYRING");
const signingKey = await secrets.resolve("file:///run/secrets/signing-key");

Environment references must use uppercase names. File references must be absolute local file:// URLs that identify owner-only regular files. Symlinks, group/world permissions, empty files, NUL content, and files above the bounded size are rejected.

Entry points

| Entry point | Purpose | | ------------------------------------- | ---------------------------------------- | | @stackonward/server-boundary | Server exports for direct Node consumers | | @stackonward/server-boundary/server | Explicit server-only import boundary |

Errors and logging

• TrustedClientIpError uses code invalid_proxy_topology.
• PrivateSecretResolutionError uses code private_secret_unavailable and status 503.
• Errors describe the failed boundary without including secret values.
• The package never logs resolved secrets, forwarding headers, or request data.

Compatibility

• Node.js 20 or newer
• ESM with TypeScript declarations
• Node request adapters compatible with a header record and socket address

Related packages

@stackonward/onex-identity-nuxt uses these boundaries for request admission and secret-backed identity configuration.

License

MIT