@archlast/server 0.1.8 → 0.1.9

package/README.md

@@ -1,100 +1,104 @@
-# @archlast/server
-
-Type-safe server definitions and runtime helpers for Archlast. This package is
-used to define schema, functions, and shared types, and it ships Docker
-templates for runtime deployment.
-
-## Install
-
-```bash
-npm install -D @archlast/server
-```
-
-## Library vs runtime
-
-This package is a dev-time library for schema and function definitions. The
-runtime server is delivered via the Docker image (`algochad/archlast-server`) and managed
-by the CLI (`archlast start`).
-
-## Schema
-
-```ts
-import { defineSchema, defineTable, v } from "@archlast/server/schema/definition";
-
-export default defineSchema({
-  tasks: defineTable({
-    id: v.id(),
-    text: v.string(),
-  }),
-});
-```
-
-## Functions
-
-```ts
-import { query, mutation } from "@archlast/server/functions/definition";
-import { z } from "zod";
-
-export const list = query({
-  handler: async (ctx) => ctx.db.table("tasks").findMany(),
-});
-
-export const create = mutation({
-  args: { text: z.string() },
-  handler: async (ctx, args) => ctx.db.table("tasks").insert({ text: args.text }),
-});
-```
-
-Other function types:
-- `action` for long running tasks
-- `http` for explicit HTTP routes
-- `webhook` for signed incoming events
-- `rpc` for tRPC-style public procedures
-
-## Auth and permissions
-
-All functions default to `auth: "required"`. You can mark functions public or
-optional, and attach permissions.
-
-```ts
-export const publicPing = query({
-  auth: "public",
-  handler: async () => "pong",
-});
-```
-
-## Runtime exports
-
-Common entry points:
-- `@archlast/server/schema/definition` and `@archlast/server/schema/validators`
-- `@archlast/server/functions/definition` and `@archlast/server/functions/types`
-- `@archlast/server/http` and `@archlast/server/webhook`
-- `@archlast/server/jobs`
-- `@archlast/server/storage/types`
-- `@archlast/server/context`
-
-## Docker templates
-
-Templates live under `templates/` in this package:
-- `docker-compose.yml`, `docker-compose.dev.yml`, `docker-compose.prod.yml`
-- `.env.example`
-- `archlast.config.js`
-
-The CLI uses these templates to generate a local Docker setup.
-
-## Environment configuration
-
-Key variables used by the server runtime:
-- `PORT` (default: 4000)
-- `ARCHLAST_DB_ROOT` (default: `./data`)
-- `ARCHLAST_ALLOWED_ORIGINS` (CSV)
-- `ARCHLAST_CORS_ALLOW_CREDENTIALS` (`true` or `false`)
-- `STORAGE_ROOT` and `STORAGE_SIGNING_SECRET`
-- `S3_ENABLED`, `S3_BUCKET`, `S3_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
-- `ARCHLAST_ADMIN_TOKEN` (deprecated), `ARCHLAST_AUTH_TOKEN_PEPPER`
-- `ARCHLAST_DASHBOARD_DIR` or `ARCHLAST_DASHBOARD_URL`
-- `ARCHLAST_STORE_PORT`, `ARCHLAST_STORE_NO_TLS`
-
-## Publishing (maintainers)
-
-See `docs/npm-publishing.md` for release and publish steps.
+# @archlast/server
+
+Type-safe server definitions and runtime helpers for Archlast. This package is
+used to define schema, functions, and shared types, and it ships Docker
+templates for runtime deployment.
+
+## Install
+
+```bash
+npm install -D @archlast/server
+```
+
+## Library vs runtime
+
+This package is a dev-time library for schema and function definitions. The
+runtime server is delivered via the Docker image (`algochad/archlast-server`) and managed
+by the CLI (`archlast start`).
+
+## Schema
+
+```ts
+import { defineSchema, defineTable, v } from "@archlast/server/schema/definition";
+
+export default defineSchema({
+    tasks: defineTable({
+        id: v.id(),
+        text: v.string(),
+    }),
+});
+```
+
+## Functions
+
+```ts
+import { query, mutation } from "@archlast/server/functions/definition";
+import { z } from "zod";
+
+export const list = query({
+    handler: async (ctx) => ctx.db.table("tasks").findMany(),
+});
+
+export const create = mutation({
+    args: { text: z.string() },
+    handler: async (ctx, args) => ctx.db.table("tasks").insert({ text: args.text }),
+});
+```
+
+Other function types:
+
+- `action` for long running tasks
+- `http` for explicit HTTP routes
+- `webhook` for signed incoming events
+- `rpc` for tRPC-style public procedures
+
+## Auth and permissions
+
+All functions default to `auth: "required"`. You can mark functions public or
+optional, and attach permissions.
+
+```ts
+export const publicPing = query({
+    auth: "public",
+    handler: async () => "pong",
+});
+```
+
+## Runtime exports
+
+Common entry points:
+
+- `@archlast/server/schema/definition` and `@archlast/server/schema/validators`
+- `@archlast/server/functions/definition` and `@archlast/server/functions/types`
+- `@archlast/server/http` and `@archlast/server/webhook`
+- `@archlast/server/jobs`
+- `@archlast/server/storage/types`
+- `@archlast/server/context`
+
+## Docker templates
+
+Templates live under `templates/` in this package:
+
+- `docker-compose.yml`, `docker-compose.dev.yml`, `docker-compose.prod.yml`
+- `.env.example`
+- `archlast.config.js`
+
+The CLI uses these templates to generate a local Docker setup.
+
+## Environment configuration
+
+Key variables used by the server runtime:
+
+- `PORT` (default: 4000)
+- `ARCHLAST_DB_ROOT` (default: `./data`)
+- `ARCHLAST_ALLOWED_ORIGINS` (CSV)
+- `ARCHLAST_CORS_ALLOW_CREDENTIALS` (`true` or `false`)
+- `STORAGE_ROOT` and `STORAGE_SIGNING_SECRET`
+- `S3_ENABLED`, `S3_BUCKET`, `S3_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
+- `ARCHLAST_ADMIN_TOKEN` (deprecated), `ARCHLAST_AUTH_TOKEN_PEPPER`
+- `ARCHLAST_DASHBOARD_DIR` or `ARCHLAST_DASHBOARD_URL`
+- `ARCHLAST_STORE_PORT`, `ARCHLAST_STORE_NO_TLS`
+
+## Publishing (maintainers)
+
+See `docs/npm-publishing.md` for release and publish steps.

package/dist/admin/auth.d.ts

@@ -29,11 +29,23 @@ export declare function isSetupRequired(db: IDatabaseClient): Promise<boolean>;
 /**
  * Setup: Create the first admin user
  */
-export declare function setupFirstAdmin(db: IDatabaseClient, username: string, password: string, userAgent: string | null, ipAddress: string | null): Promise<SetupResult | AuthError>;
+export declare function setupFirstAdmin(
+    db: IDatabaseClient,
+    username: string,
+    password: string,
+    userAgent: string | null,
+    ipAddress: string | null
+): Promise<SetupResult | AuthError>;
 /**
  * Login: Authenticate admin user
  */
-export declare function loginAdmin(db: IDatabaseClient, username: string, password: string, userAgent: string | null, ipAddress: string | null): Promise<LoginResult | AuthError>;
+export declare function loginAdmin(
+    db: IDatabaseClient,
+    username: string,
+    password: string,
+    userAgent: string | null,
+    ipAddress: string | null
+): Promise<LoginResult | AuthError>;
 /**
  * Logout: Invalidate session
  */
@@ -41,7 +53,10 @@ export declare function logoutAdmin(db: IDatabaseClient, token: string): Promise
 /**
  * Verify session and get admin user
  */
-export declare function verifyAdminSession(db: IDatabaseClient, token: string): Promise<{
+export declare function verifyAdminSession(
+    db: IDatabaseClient,
+    token: string
+): Promise<{
     user: Omit<AdminUser, "password_hash">;
     session: AdminSession;
 } | null>;
@@ -56,7 +71,11 @@ export declare function extractAdminSessionTokens(req: Request): string[];
  * 2. ast_ session tokens (login sessions) - not obfuscated (for browser)
  * 3. ak_ API keys (legacy, user-created) - not obfuscated
  */
-export declare function requireAdminAuth(db: IDatabaseClient, req: Request, requestPath?: string): Promise<{
+export declare function requireAdminAuth(
+    db: IDatabaseClient,
+    req: Request,
+    requestPath?: string
+): Promise<{
     user: Omit<AdminUser, "password_hash">;
     session: AdminSession;
 } | null>;
@@ -76,4 +95,4 @@ export declare function getUserAgent(req: Request): string | null;
  * Get IP address from request
  */
 export declare function getIpAddress(req: Request): string | null;
-//# sourceMappingURL=auth.d.ts.map
+//# sourceMappingURL=auth.d.ts.map

package/dist/admin/auth.js

@@ -43,7 +43,10 @@ async function setupFirstAdmin(db, username, password, userAgent, ipAddress) {
         // Validate username
         const normalizedUsername = (0, schema_js_1.normalizeUsername)(username);
         if (!(0, schema_js_1.isValidUsername)(normalizedUsername)) {
-            return { success: false, error: "Invalid username. Must be 3-32 characters, alphanumeric and underscore only." };
+            return {
+                success: false,
+                error: "Invalid username. Must be 3-32 characters, alphanumeric and underscore only.",
+            };
         }
         // Validate password
         if (!password || password.length < 8) {
@@ -52,10 +55,21 @@ async function setupFirstAdmin(db, username, password, userAgent, ipAddress) {
         // Hash password
         const passwordHash = await (0, crypto_js_1.hashPassword)(password);
         // Create first admin user (always super admin)
-        const user = await (0, schema_js_1.createFirstAdminUser)(db, normalizedUsername, passwordHash);
+        const user = await (0, schema_js_1.createFirstAdminUser)(
+            db,
+            normalizedUsername,
+            passwordHash
+        );
         // Create session
         const token = `ast_${(0, cuid2_1.createId)()}`; // Admin Session Token
-        const session = await (0, schema_js_1.createAdminSession)(db, user._id, token, exports.ADMIN_SESSION_TTL_MS, userAgent, ipAddress);
+        const session = await (0, schema_js_1.createAdminSession)(
+            db,
+            user._id,
+            token,
+            exports.ADMIN_SESSION_TTL_MS,
+            userAgent,
+            ipAddress
+        );
         return {
             success: true,
             token: session.token,
@@ -70,8 +84,7 @@ async function setupFirstAdmin(db, username, password, userAgent, ipAddress) {
                 updated_at: user.updated_at,
             },
         };
-    }
-    catch (err) {
+    } catch (err) {
         logger_js_1.logger.log({
             timestamp: Date.now(),
             level: "error",
@@ -100,7 +113,14 @@ async function loginAdmin(db, username, password, userAgent, ipAddress) {
         }
         // Create session
         const token = `ast_${(0, cuid2_1.createId)()}`;
-        const session = await (0, schema_js_1.createAdminSession)(db, user._id, token, exports.ADMIN_SESSION_TTL_MS, userAgent, ipAddress);
+        const session = await (0, schema_js_1.createAdminSession)(
+            db,
+            user._id,
+            token,
+            exports.ADMIN_SESSION_TTL_MS,
+            userAgent,
+            ipAddress
+        );
         return {
             success: true,
             token: session.token,
@@ -115,8 +135,7 @@ async function loginAdmin(db, username, password, userAgent, ipAddress) {
                 updated_at: user.updated_at,
             },
         };
-    }
-    catch (err) {
+    } catch (err) {
         logger_js_1.logger.log({
             timestamp: Date.now(),
             level: "error",
@@ -167,8 +186,7 @@ async function verifyAdminSession(db, token) {
             },
             session,
         };
-    }
-    catch (err) {
+    } catch (err) {
         logger_js_1.logger.log({
             timestamp: Date.now(),
             level: "error",
@@ -185,7 +203,8 @@ async function verifyAdminSession(db, token) {
 // ============================================================================
 // TOKEN OBFUSCATION
 // ============================================================================
-const TOKEN_OBFUSCATION_SECRET = process.env.ARCHLAST_TOKEN_OBFUSCATION_SECRET || "archlast-default-secret-change-in-production";
+const TOKEN_OBFUSCATION_SECRET =
+    process.env.ARCHLAST_TOKEN_OBFUSCATION_SECRET || "archlast-default-secret-change-in-production";
 const TIMESTAMP_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
 /**
  * Deobfuscate a dynamic token and return the raw token
@@ -219,7 +238,9 @@ function deobfuscateToken(obfuscated, requestPath) {
             .update(message)
             .digest("base64url");
         // Use timing-safe comparison to prevent timing attacks
-        if (!(0, crypto_1.timingSafeEqual)(Buffer.from(signature), Buffer.from(expectedSignature))) {
+        if (
+            !(0, crypto_1.timingSafeEqual)(Buffer.from(signature), Buffer.from(expectedSignature))
+        ) {
             logger_js_1.logger.log({
                 timestamp: Date.now(),
                 level: "warn",
@@ -235,8 +256,7 @@ function deobfuscateToken(obfuscated, requestPath) {
             message: `[Token Obfuscation] ✓ Token deobfuscated successfully`,
         });
         return token;
-    }
-    catch (error) {
+    } catch (error) {
         logger_js_1.logger.log({
             timestamp: Date.now(),
             level: "error",
@@ -256,16 +276,14 @@ function extractAndDeobfuscateTokens(req, requestPath) {
     const xAdminToken = req.headers.get("x-admin-token");
     if (xAdminToken) {
         const deobfuscated = deobfuscateToken(xAdminToken, requestPath);
-        if (deobfuscated)
-            tokens.push(deobfuscated);
+        if (deobfuscated) tokens.push(deobfuscated);
     }
     // 2. Authorization header
     const authHeader = req.headers.get("authorization");
     if (authHeader?.startsWith("Bearer ")) {
         const token = authHeader.slice(7);
         const deobfuscated = deobfuscateToken(token, requestPath);
-        if (deobfuscated)
-            tokens.push(deobfuscated);
+        if (deobfuscated) tokens.push(deobfuscated);
     }
     // 3. Cookie (session tokens are not obfuscated)
     const cookieHeader = req.headers.get("cookie");
@@ -287,8 +305,7 @@ function extractAdminSessionTokens(req) {
     const tokens = [];
     // 1. X-Admin-Token header (highest priority, manual bypass)
     const xAdminToken = req.headers.get("x-admin-token");
-    if (xAdminToken)
-        tokens.push(xAdminToken);
+    if (xAdminToken) tokens.push(xAdminToken);
     // 2. Authorization header
     const authHeader = req.headers.get("authorization");
     if (authHeader?.startsWith("Bearer ")) {
@@ -334,7 +351,7 @@ async function requireAdminAuth(db, req, requestPath) {
         level: "debug",
         kind: "system",
         message: `[Admin Auth] Found ${tokens.length} token(s)`,
-        context: { tokenTypes: tokens.map(t => `${t.slice(0, 4)}...${t.slice(-4)}`) },
+        context: { tokenTypes: tokens.map((t) => `${t.slice(0, 4)}...${t.slice(-4)}`) },
     });
     for (const token of tokens) {
         // 1. Check for sat_ admin tokens (Server Admin Tokens - dashboard-generated)
@@ -357,7 +374,10 @@ async function requireAdminAuth(db, req, requestPath) {
                 });
             }
             if (adminTokenRecord) {
-                const user = await (0, schema_js_1.findAdminUserById)(db, adminTokenRecord.created_by_admin_id);
+                const user = await (0, schema_js_1.findAdminUserById)(
+                    db,
+                    adminTokenRecord.created_by_admin_id
+                );
                 if (user) {
                     await (0, schema_js_1.updateAdminTokenLastUsed)(db, adminTokenRecord._id);
                     const now = Date.now();
@@ -384,7 +404,8 @@ async function requireAdminAuth(db, req, requestPath) {
                             _collection: "admin_tokens",
                             admin_user_id: user._id,
                             token: adminTokenRecord.token,
-                            expires_at: adminTokenRecord.expires_at ?? now + exports.ADMIN_SESSION_TTL_MS,
+                            expires_at:
+                                adminTokenRecord.expires_at ?? now + exports.ADMIN_SESSION_TTL_MS,
                             user_agent: req.headers.get("user-agent"),
                             ip_address: getIpAddress(req),
                             created_at: adminTokenRecord.created_at,
@@ -405,7 +426,10 @@ async function requireAdminAuth(db, req, requestPath) {
         if (token.startsWith("ak_")) {
             const apiKey = await (0, schema_js_1.findApiKeyByKey)(db, token);
             if (apiKey) {
-                const user = await (0, schema_js_1.findAdminUserById)(db, apiKey.created_by_admin_id);
+                const user = await (0, schema_js_1.findAdminUserById)(
+                    db,
+                    apiKey.created_by_admin_id
+                );
                 if (user) {
                     await (0, schema_js_1.updateApiKeyLastUsed)(db, apiKey._id);
                     const now = Date.now();
@@ -484,4 +508,4 @@ function getIpAddress(req) {
     // Fallback to direct connection (may be proxy IP in production)
     return null;
 }
-//# sourceMappingURL=auth.js.map
+//# sourceMappingURL=auth.js.map