Merge branch 'main' into feature/hardover-shelves

src/lib/utils/api-token.ts

@@ -0,0 +1,30 @@
+/**
+ * Component: API Token Generation Utility
+ * Documentation: documentation/backend/services/api-tokens.md
+ */
+
+import crypto from 'crypto';
+import { API_TOKEN_PREFIX, TOKEN_RANDOM_BYTES, TOKEN_PREFIX_LENGTH } from '../constants/api-tokens';
+
+interface GeneratedToken {
+  /** The full token string to return to the user (shown only once) */
+  fullToken: string;
+  /** SHA-256 hash of the full token (stored in database) */
+  tokenHash: string;
+  /** Display prefix for identification (first 12 chars) */
+  tokenPrefix: string;
+}
+
+/**
+ * Generate a new API token with its hash and display prefix.
+ * The full token is: API_TOKEN_PREFIX + random hex string.
+ * Only the hash is stored; the full token is returned once at creation.
+ */
+export function generateApiToken(): GeneratedToken {
+  const randomPart = crypto.randomBytes(TOKEN_RANDOM_BYTES).toString('hex');
+  const fullToken = `${API_TOKEN_PREFIX}${randomPart}`;
+  const tokenHash = crypto.createHash('sha256').update(fullToken).digest('hex');
+  const tokenPrefix = fullToken.substring(0, TOKEN_PREFIX_LENGTH);
+
+  return { fullToken, tokenHash, tokenPrefix };
+}

src/lib/utils/apiTokenRateLimit.ts

@@ -0,0 +1,92 @@
+/**
+ * Component: API Token Rate Limiting
+ * Documentation: documentation/backend/services/api-tokens.md
+ *
+ * In-memory sliding-window rate limiter with lazy eviction and periodic sweep
+ * to prevent unbounded memory growth.
+ */
+
+type Bucket = {
+  count: number;
+  resetAt: number;
+};
+
+type RateLimitResult = {
+  allowed: boolean;
+  retryAfterSeconds: number;
+};
+
+const buckets = new Map<string, Bucket>();
+
+/** Number of checkRateLimit calls since the last full sweep */
+let checkCount = 0;
+
+/** How often (in calls) to perform a full sweep of expired buckets */
+const SWEEP_INTERVAL = 100;
+
+/**
+ * Sweep the entire bucket map and delete all expired entries.
+ * Called automatically every SWEEP_INTERVAL checks.
+ */
+function sweepExpiredBuckets(): void {
+  const now = Date.now();
+  for (const [key, bucket] of buckets) {
+    if (now >= bucket.resetAt) {
+      buckets.delete(key);
+    }
+  }
+}
+
+function checkRateLimit(key: string, maxRequests: number, windowMs: number): RateLimitResult {
+  const now = Date.now();
+
+  // Periodic full sweep every SWEEP_INTERVAL calls
+  checkCount += 1;
+  if (checkCount >= SWEEP_INTERVAL) {
+    checkCount = 0;
+    sweepExpiredBuckets();
+  }
+
+  const current = buckets.get(key);
+
+  // Lazy eviction: if the bucket is expired, delete it and start fresh
+  if (!current || now >= current.resetAt) {
+    if (current) {
+      buckets.delete(key);
+    }
+    buckets.set(key, { count: 1, resetAt: now + windowMs });
+    return { allowed: true, retryAfterSeconds: Math.ceil(windowMs / 1000) };
+  }
+
+  if (current.count >= maxRequests) {
+    return {
+      allowed: false,
+      retryAfterSeconds: Math.max(1, Math.ceil((current.resetAt - now) / 1000)),
+    };
+  }
+
+  current.count += 1;
+  return {
+    allowed: true,
+    retryAfterSeconds: Math.max(1, Math.ceil((current.resetAt - now) / 1000)),
+  };
+}
+
+export function checkApiTokenCreateRateLimit(actorId: string): RateLimitResult {
+  return checkRateLimit(`api-token-create:${actorId}`, 10, 60 * 1000);
+}
+
+export function checkApiTokenRevokeRateLimit(actorId: string): RateLimitResult {
+  return checkRateLimit(`api-token-revoke:${actorId}`, 20, 60 * 1000);
+}
+
+/** Reset all buckets and the sweep counter. For testing only. */
+export function _resetBuckets(): void {
+  buckets.clear();
+  checkCount = 0;
+}
+
+/** Get the current number of tracked buckets. For testing only. */
+export function _getBucketCount(): number {
+  return buckets.size;
+}

src/lib/utils/client-url.ts

@@ -0,0 +1,12 @@
+/**
+ * Component: Client-side URL Utilities
+ * Documentation: documentation/backend/services/api-tokens.md
+ */
+
+/**
+ * Get the current instance origin URL.
+ * Returns window.location.origin on the client, or a placeholder on the server.
+ */
+export function getInstanceUrl(): string {
+  return typeof window !== 'undefined' ? window.location.origin : 'https://your-instance';
+}