@archlast/shared 0.0.1 → 0.1.0

package/README.md

@@ -1,10 +1,270 @@
 # @archlast/shared
 
-Shared utilities used by Archlast packages.
+Internal shared utilities for Archlast packages. This package provides token obfuscation, validation helpers, and shared constants used across the Archlast ecosystem.
 
-This package is primarily an internal dependency. Most users should install
-`@archlast/client`, `@archlast/server`, or `@archlast/cli` instead.
+> ⚠️ **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.
 
-## Publishing (maintainers)
+## 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)
+
+## 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 Format
+
+Obfuscated tokens follow this structure:
+
+```
+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:**
+
+| 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) |
+
+### `deobfuscateToken(obfuscated, path, options?)`
+
+Verify and extract a token from its obfuscated form.
+
+```ts
+import { deobfuscateToken } from "@archlast/shared";
+
+const result = deobfuscateToken(
+  "v1:1704067200000:...",
+  "/_archlast/admin/auth/me"
+);
+
+if (result.valid) {
+  console.log("Token:", result.token);
+} else {
+  console.error("Invalid:", result.error);
+}
+```
+
+**Returns:**
+
+```ts
+// Success
+{ valid: true, token: string }
+
+// Failure
+{ valid: false, error: string }
+```
+
+**Possible Errors:**
+
+| 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.
+
+```ts
+import { extractRawToken } from "@archlast/shared";
+
+try {
+  const rawToken = extractRawToken(obfuscated, path);
+  // Use rawToken...
+} catch (error) {
+  console.error("Token validation failed:", error.message);
+}
+```
+
+### `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();
+}
+```
+
+## Publishing (Maintainers)
 
 See `docs/npm-publishing.md` for release and publish steps.
+
+## License
+
+MIT

package/package.json

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