@archlast/shared 0.1.0 → 0.1.2

package/README.md

@@ -1,270 +1,77 @@
 # @archlast/shared
 
-Internal shared utilities for Archlast packages. This package provides token obfuscation, validation helpers, and shared constants used across the Archlast ecosystem.
-
-> ⚠️ **Internal Package**: Most applications should use `@archlast/client`, `@archlast/server`, or `@archlast/cli` instead. This package is primarily for internal use by other Archlast packages.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Features](#features)
-- [Token Obfuscation](#token-obfuscation)
-- [Token Format](#token-format)
-- [API Reference](#api-reference)
-- [Configuration](#configuration)
-- [Security Considerations](#security-considerations)
+Shared utilities for Archlast packages. This package is mainly internal; most
+applications should use `@archlast/client`, `@archlast/server`, or `@archlast/cli`.
 
 ## Installation
 
 ```bash
 npm install @archlast/shared
-
-# Or with other package managers
-pnpm add @archlast/shared
-bun add @archlast/shared
 ```
 
-## Features
-
-- **Token Obfuscation**: Secure token wrapping with HMAC signatures
-- **Token Validation**: Verify and extract obfuscated tokens
-- **Path-Bound Tokens**: Tokens are bound to specific API paths
-- **Timestamp Validation**: Short validity window prevents replay attacks
-- **Shared Constants**: Common constants used across packages
-
-## Token Obfuscation
-
-Token obfuscation protects sensitive tokens (API keys, session tokens) in transit by:
-
-1. Adding a timestamp for time-limited validity
-2. Including a random nonce for uniqueness
-3. Computing an HMAC signature bound to the request path
-4. Encoding the result in a structured format
-
-### Why Obfuscate?
-
-- **Path Binding**: A token obfuscated for `/api/users` cannot be reused for `/api/admin`
-- **Time Limiting**: Tokens expire after a short window (default: 5 minutes)
-- **Replay Prevention**: Random nonce ensures each request is unique
-- **Signature Verification**: HMAC ensures token integrity
+## Token obfuscation
 
-## Token Format
-
-Obfuscated tokens follow this structure:
+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>
 ```
 
-| Component | Description |
-|-----------|-------------|
-| `v1` | Version identifier for future format changes |
-| `timestamp` | Unix milliseconds when token was obfuscated |
-| `nonce` | Random 16-character string |
-| `signature` | HMAC-SHA256 of `token:timestamp:nonce:path` |
-| `token` | The original raw token |
-
-### Example
-
-```
-v1:1704067200000:a1b2c3d4e5f6g7h8:8f4e2c1a9b7d5e3f1a2b4c6d8e0f2a4b6:arch_sk_live_xxx
-```
-
-## API Reference
-
-### `obfuscateToken(token, path, options?)`
-
-Obfuscate a raw token for a specific API path.
-
-```ts
-import { obfuscateToken } from "@archlast/shared";
-
-const obfuscated = obfuscateToken(
-  "arch_sk_live_abc123",
-  "/_archlast/admin/auth/me"
-);
-
-// Result: "v1:1704067200000:a1b2c3d4e5f6g7h8:..."
-```
-
-**Parameters:**
+- `timestamp` is unix milliseconds
+- `nonce` is a random 16-character string
+- `signature` is an HMAC of `token:timestamp:nonce:path`
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `token` | `string` | Raw token to obfuscate |
-| `path` | `string` | API path the token is bound to |
-| `options.secret` | `string?` | Custom HMAC secret (default: env var) |
-| `options.timestamp` | `number?` | Custom timestamp (default: now) |
+The current implementation uses a five minute window.
 
-### `deobfuscateToken(obfuscated, path, options?)`
+## API
 
-Verify and extract a token from its obfuscated form.
+### `obfuscateToken(token, path)`
 
-```ts
-import { deobfuscateToken } from "@archlast/shared";
+Returns an obfuscated token string.
 
-const result = deobfuscateToken(
-  "v1:1704067200000:...",
-  "/_archlast/admin/auth/me"
-);
+### `deobfuscateToken(obfuscated, path)`
 
-if (result.valid) {
-  console.log("Token:", result.token);
-} else {
-  console.error("Invalid:", result.error);
-}
-```
+Returns the raw token when valid, otherwise `null`.
 
-**Returns:**
+### `isObfuscatedToken(token)`
 
-```ts
-// Success
-{ valid: true, token: string }
+Returns `true` when the token uses the `v1:` prefix.
 
-// Failure
-{ valid: false, error: string }
-```
+### `extractRawToken(token, path)`
 
-**Possible Errors:**
+Accepts either a raw or obfuscated token and returns the raw token or `null`.
 
-| Error | Description |
-|-------|-------------|
-| `"Invalid format"` | Token doesn't match expected structure |
-| `"Unsupported version"` | Version prefix is not recognized |
-| `"Token expired"` | Timestamp is outside validity window |
-| `"Invalid signature"` | HMAC verification failed |
-| `"Path mismatch"` | Token was created for a different path |
-
-### `extractRawToken(obfuscated, path, options?)`
-
-Convenience wrapper that returns the raw token or throws.
+## Usage
 
 ```ts
-import { extractRawToken } from "@archlast/shared";
-
-try {
-  const rawToken = extractRawToken(obfuscated, path);
-  // Use rawToken...
-} catch (error) {
-  console.error("Token validation failed:", error.message);
+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
 }
 ```
 
-### `isObfuscatedToken(value)`
-
-Check if a string looks like an obfuscated token.
-
-```ts
-import { isObfuscatedToken } from "@archlast/shared";
-
-isObfuscatedToken("v1:123:abc:def:token");  // true
-isObfuscatedToken("arch_sk_live_xxx");       // false
-```
-
 ## Configuration
 
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `ARCHLAST_TOKEN_OBFUSCATION_SECRET` | - | **Required in production.** HMAC secret for signatures. |
-| `ARCHLAST_TOKEN_VALIDITY_MS` | `300000` | Token validity window (5 minutes) |
-
-### Setting the Secret
-
-```bash
-# Generate a strong secret
-openssl rand -base64 32
-
-# Set in environment
-export ARCHLAST_TOKEN_OBFUSCATION_SECRET="your-32-char-random-secret-here"
-```
-
-### Custom Options
-
-```ts
-const obfuscated = obfuscateToken(token, path, {
-  secret: "custom-secret",
-  timestamp: Date.now(),
-});
-
-const result = deobfuscateToken(obfuscated, path, {
-  secret: "custom-secret",
-  validityMs: 60000, // 1 minute
-});
-```
-
-## Security Considerations
-
-### Production Requirements
-
-1. **Set a Strong Secret**: Always set `ARCHLAST_TOKEN_OBFUSCATION_SECRET` in production
-2. **Keep Clocks Synced**: Use NTP to keep server clocks synchronized
-3. **Use HTTPS**: Always transmit tokens over HTTPS
-4. **Short Validity**: Keep the validity window short (default: 5 minutes)
-
-### Best Practices
-
-```ts
-// ✅ Good: Obfuscate before sending
-const headers = {
-  Authorization: `Bearer ${obfuscateToken(apiKey, requestPath)}`
-};
-
-// ❌ Bad: Sending raw tokens in headers
-const headers = {
-  Authorization: `Bearer ${apiKey}`
-};
-```
-
-### Clock Skew
-
-The validation allows for some clock skew between client and server:
-
-```ts
-// Token is valid if:
-// (serverTime - validityMs) < tokenTimestamp < (serverTime + clockSkew)
-```
-
-Default clock skew allowance: 30 seconds.
-
-## Internal Usage
-
-This package is used internally by:
-
-- **@archlast/server**: Validating incoming requests
-- **@archlast/client**: Preparing authenticated requests
-- **@archlast/cli**: API key handling for deployments
-
-### Example: Server Middleware
-
-```ts
-// Internal usage in @archlast/server
-import { deobfuscateToken } from "@archlast/shared";
-
-function authMiddleware(req, res, next) {
-  const authHeader = req.headers.authorization;
-  const token = authHeader?.replace("Bearer ", "");
-
-  if (!token) {
-    return res.status(401).json({ error: "No token" });
-  }
-
-  const result = deobfuscateToken(token, req.path);
-
-  if (!result.valid) {
-    return res.status(401).json({ error: result.error });
-  }
-
-  req.apiKey = result.token;
-  next();
-}
-```
+Set `ARCHLAST_TOKEN_OBFUSCATION_SECRET` in production. If it is not set, a
+development default is used.
 
-## Publishing (Maintainers)
+## Security notes
 
-See `docs/npm-publishing.md` for release and publish steps.
+- 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.
 
-## License
+## Publishing (maintainers)
 
-MIT
+See `docs/npm-publishing.md` for release and publish steps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archlast/shared",
-    "version": "0.1.0",
+    "version": "0.1.2",
   "description": "Shared utilities for Archlast packages",
   "type": "module",
   "main": "./dist/index.js",