@archlast/shared 0.0.1

package/README.md

@@ -0,0 +1,10 @@
+# @archlast/shared
+
+Shared utilities used by Archlast packages.
+
+This package is primarily an internal dependency. Most users should install
+`@archlast/client`, `@archlast/server`, or `@archlast/cli` instead.
+
+## Publishing (maintainers)
+
+See `docs/npm-publishing.md` for release and publish steps.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { obfuscateToken, deobfuscateToken, isObfuscatedToken, extractRawToken, } from "./src/token-obfuscation.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { obfuscateToken, deobfuscateToken, isObfuscatedToken, extractRawToken, } from "./src/token-obfuscation.js";

package/dist/src/token-obfuscation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Dynamic Token Obfuscation
+ *
+ * Adds dynamic obfuscation to admin tokens to prevent replay attacks
+ * and protect the raw token from being intercepted.
+ *
+ * Format: v1:<timestamp>:<nonce>:<signature>
+ * - v1: Version identifier
+ * - timestamp: Unix milliseconds (must be within 5 minutes)
+ * - nonce: Random 16-char string for uniqueness
+ * - signature: HMAC-SHA256 of "token:timestamp:nonce:path"
+ */
+/**
+ * Obfuscate an admin token for a specific request
+ * @param token - The raw admin token (sat_...)
+ * @param path - The request path (for binding)
+ * @returns Obfuscated token string
+ */
+export declare function obfuscateToken(token: string, path: string): string;
+/**
+ * Parse and validate an obfuscated token
+ * @param obfuscated - The obfuscated token string
+ * @param path - The request path (must match what was used for obfuscation)
+ * @returns The raw token if valid, null if invalid
+ */
+export declare function deobfuscateToken(obfuscated: string, path: string): string | null;
+/**
+ * Check if a token is obfuscated (starts with v1:)
+ */
+export declare function isObfuscatedToken(token: string): boolean;
+/**
+ * Extract raw token from obfuscated or raw token
+ * Handles both obfuscated (v1:...) and raw (sat_...) tokens
+ */
+export declare function extractRawToken(token: string, path: string): string | null;

package/dist/src/token-obfuscation.js

@@ -0,0 +1,88 @@
+/**
+ * Dynamic Token Obfuscation
+ *
+ * Adds dynamic obfuscation to admin tokens to prevent replay attacks
+ * and protect the raw token from being intercepted.
+ *
+ * Format: v1:<timestamp>:<nonce>:<signature>
+ * - v1: Version identifier
+ * - timestamp: Unix milliseconds (must be within 5 minutes)
+ * - nonce: Random 16-char string for uniqueness
+ * - signature: HMAC-SHA256 of "token:timestamp:nonce:path"
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+const VERSION = "v1";
+const TIMESTAMP_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+const NONCE_LENGTH = 16;
+const SECRET_KEY = process.env.ARCHLAST_TOKEN_OBFUSCATION_SECRET || "archlast-default-secret-change-in-production";
+/**
+ * Obfuscate an admin token for a specific request
+ * @param token - The raw admin token (sat_...)
+ * @param path - The request path (for binding)
+ * @returns Obfuscated token string
+ */
+export function obfuscateToken(token, path) {
+    const timestamp = Date.now();
+    const nonce = randomBytes(NONCE_LENGTH).toString("base64url").slice(0, NONCE_LENGTH);
+    // Create signature: HMAC-SHA256(token:timestamp:nonce:path)
+    const message = `${token}:${timestamp}:${nonce}:${path}`;
+    const signature = createHmac("sha256", SECRET_KEY)
+        .update(message)
+        .digest("base64url");
+    return `${VERSION}:${timestamp}:${nonce}:${signature}:${token}`;
+}
+/**
+ * Parse and validate an obfuscated token
+ * @param obfuscated - The obfuscated token string
+ * @param path - The request path (must match what was used for obfuscation)
+ * @returns The raw token if valid, null if invalid
+ */
+export function deobfuscateToken(obfuscated, path) {
+    try {
+        // Parse format: v1:timestamp:nonce:signature:token
+        const parts = obfuscated.split(":");
+        if (parts.length !== 5 || parts[0] !== VERSION) {
+            return null;
+        }
+        const [, timestampStr, nonce, signature, token] = parts;
+        const timestamp = parseInt(timestampStr, 10);
+        // Check timestamp is within window
+        const now = Date.now();
+        if (Math.abs(now - timestamp) > TIMESTAMP_WINDOW_MS) {
+            console.warn(`[Token Obfuscation] Timestamp outside window: ${Math.abs(now - timestamp)}ms ago`);
+            return null;
+        }
+        // Verify signature
+        const message = `${token}:${timestamp}:${nonce}:${path}`;
+        const expectedSignature = createHmac("sha256", SECRET_KEY)
+            .update(message)
+            .digest("base64url");
+        // Use timing-safe comparison to prevent timing attacks
+        if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
+            console.warn(`[Token Obfuscation] Signature verification failed`);
+            return null;
+        }
+        return token;
+    }
+    catch (error) {
+        console.error(`[Token Obfuscation] Deobfuscation error:`, error);
+        return null;
+    }
+}
+/**
+ * Check if a token is obfuscated (starts with v1:)
+ */
+export function isObfuscatedToken(token) {
+    return token.startsWith(`${VERSION}:`);
+}
+/**
+ * Extract raw token from obfuscated or raw token
+ * Handles both obfuscated (v1:...) and raw (sat_...) tokens
+ */
+export function extractRawToken(token, path) {
+    if (isObfuscatedToken(token)) {
+        return deobfuscateToken(token, path);
+    }
+    // Raw token - return as-is (for backwards compatibility during transition)
+    return token;
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@archlast/shared",
+  "version": "0.0.1",
+  "description": "Shared utilities for Archlast packages",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  }
+}

package/src/token-obfuscation.ts

@@ -0,0 +1,100 @@
+/**
+ * Dynamic Token Obfuscation
+ *
+ * Adds dynamic obfuscation to admin tokens to prevent replay attacks
+ * and protect the raw token from being intercepted.
+ *
+ * Format: v1:<timestamp>:<nonce>:<signature>
+ * - v1: Version identifier
+ * - timestamp: Unix milliseconds (must be within 5 minutes)
+ * - nonce: Random 16-char string for uniqueness
+ * - signature: HMAC-SHA256 of "token:timestamp:nonce:path"
+ */
+
+import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+
+const VERSION = "v1";
+const TIMESTAMP_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+const NONCE_LENGTH = 16;
+const SECRET_KEY = process.env.ARCHLAST_TOKEN_OBFUSCATION_SECRET || "archlast-default-secret-change-in-production";
+
+/**
+ * Obfuscate an admin token for a specific request
+ * @param token - The raw admin token (sat_...)
+ * @param path - The request path (for binding)
+ * @returns Obfuscated token string
+ */
+export function obfuscateToken(token: string, path: string): string {
+    const timestamp = Date.now();
+    const nonce = randomBytes(NONCE_LENGTH).toString("base64url").slice(0, NONCE_LENGTH);
+
+    // Create signature: HMAC-SHA256(token:timestamp:nonce:path)
+    const message = `${token}:${timestamp}:${nonce}:${path}`;
+    const signature = createHmac("sha256", SECRET_KEY)
+        .update(message)
+        .digest("base64url");
+
+    return `${VERSION}:${timestamp}:${nonce}:${signature}:${token}`;
+}
+
+/**
+ * Parse and validate an obfuscated token
+ * @param obfuscated - The obfuscated token string
+ * @param path - The request path (must match what was used for obfuscation)
+ * @returns The raw token if valid, null if invalid
+ */
+export function deobfuscateToken(obfuscated: string, path: string): string | null {
+    try {
+        // Parse format: v1:timestamp:nonce:signature:token
+        const parts = obfuscated.split(":");
+        if (parts.length !== 5 || parts[0] !== VERSION) {
+            return null;
+        }
+
+        const [, timestampStr, nonce, signature, token] = parts;
+        const timestamp = parseInt(timestampStr, 10);
+
+        // Check timestamp is within window
+        const now = Date.now();
+        if (Math.abs(now - timestamp) > TIMESTAMP_WINDOW_MS) {
+            console.warn(`[Token Obfuscation] Timestamp outside window: ${Math.abs(now - timestamp)}ms ago`);
+            return null;
+        }
+
+        // Verify signature
+        const message = `${token}:${timestamp}:${nonce}:${path}`;
+        const expectedSignature = createHmac("sha256", SECRET_KEY)
+            .update(message)
+            .digest("base64url");
+
+        // Use timing-safe comparison to prevent timing attacks
+        if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
+            console.warn(`[Token Obfuscation] Signature verification failed`);
+            return null;
+        }
+
+        return token;
+    } catch (error) {
+        console.error(`[Token Obfuscation] Deobfuscation error:`, error);
+        return null;
+    }
+}
+
+/**
+ * Check if a token is obfuscated (starts with v1:)
+ */
+export function isObfuscatedToken(token: string): boolean {
+    return token.startsWith(`${VERSION}:`);
+}
+
+/**
+ * Extract raw token from obfuscated or raw token
+ * Handles both obfuscated (v1:...) and raw (sat_...) tokens
+ */
+export function extractRawToken(token: string, path: string): string | null {
+    if (isObfuscatedToken(token)) {
+        return deobfuscateToken(token, path);
+    }
+    // Raw token - return as-is (for backwards compatibility during transition)
+    return token;
+}