@archlast/shared

Shared utilities for Archlast packages. This package is mainly internal; most applications should use @archlast/client, @archlast/server, or @archlast/cli.

Installation

npm install @archlast/shared

Token obfuscation

Token obfuscation protects sensitive tokens by binding them to a request path and a short validity window. The format is:

v1:<timestamp>:<nonce>:<signature>:<token>

• timestamp is unix milliseconds
• nonce is a random 16-character string
• signature is an HMAC of token:timestamp:nonce:path

The current implementation uses a five minute window.

API

obfuscateToken(token, path)

Returns an obfuscated token string.

deobfuscateToken(obfuscated, path)

Returns the raw token when valid, otherwise null.

isObfuscatedToken(token)

Returns true when the token uses the v1: prefix.

extractRawToken(token, path)

Accepts either a raw or obfuscated token and returns the raw token or null.

Usage

import {
  obfuscateToken,
  deobfuscateToken,
  extractRawToken,
  isObfuscatedToken
} from "@archlast/shared";

const obfuscated = obfuscateToken(rawToken, "/_archlast/admin/auth/me");
const raw = deobfuscateToken(obfuscated, "/_archlast/admin/auth/me");
const rawEither = extractRawToken(obfuscated, "/_archlast/admin/auth/me");

if (isObfuscatedToken(obfuscated)) {
  // token was wrapped
}

Configuration

Set ARCHLAST_TOKEN_OBFUSCATION_SECRET in production. If it is not set, a development default is used.

Security notes

• Keep clocks in sync between clients and servers.
• Rotate the secret if you suspect exposure.
• Bind tokens to the exact path you expect to validate.

Publishing (maintainers)

See docs/npm-publishing.md for release and publish steps.