@autumnsgrove/groveengine 0.6.4 → 0.6.5

package/dist/server/services/database.d.ts

@@ -234,3 +234,141 @@ export declare function exists(db: D1DatabaseOrSession, table: string, where: st
  * ```
  */
 export declare function count(db: D1DatabaseOrSession, table: string, where?: string, whereParams?: unknown[]): Promise<number>;
+/**
+ * Error thrown when tenant context is missing or invalid
+ */
+export declare class TenantContextError extends Error {
+    constructor(message: string);
+}
+/**
+ * Tenant-scoped database context
+ * Ensures all queries are automatically scoped to a specific tenant
+ */
+export interface TenantContext {
+    /** The tenant ID for this context */
+    tenantId: string;
+    /** Optional user ID for audit logging */
+    userId?: string;
+}
+/**
+ * Tenant-aware database wrapper
+ *
+ * This wrapper enforces tenant isolation by:
+ * 1. Automatically adding tenant_id to all INSERT operations
+ * 2. Requiring tenant_id in all SELECT/UPDATE/DELETE WHERE clauses
+ * 3. Validating tenant_id in query results
+ *
+ * SECURITY: This is a critical security boundary. All multi-tenant data access
+ * MUST go through this wrapper to prevent cross-tenant data leaks.
+ *
+ * @example
+ * ```ts
+ * // In your API route or server load function:
+ * const tenantDb = getTenantDb(platform.env.DB, { tenantId: locals.tenant.id });
+ *
+ * // All queries are now automatically scoped to this tenant
+ * const posts = await tenantDb.queryMany<Post>('posts', 'status = ?', ['published']);
+ * // Equivalent to: SELECT * FROM posts WHERE tenant_id = ? AND status = ?
+ * ```
+ */
+export declare class TenantDb {
+    private db;
+    private context;
+    constructor(db: D1DatabaseOrSession, context: TenantContext);
+    /**
+     * Get the tenant ID for this context
+     */
+    get tenantId(): string;
+    /**
+     * Query a single row with automatic tenant scoping
+     */
+    queryOne<T>(table: string, where?: string, whereParams?: unknown[]): Promise<T | null>;
+    /**
+     * Query a single row, throw if not found
+     */
+    queryOneOrThrow<T>(table: string, where?: string, whereParams?: unknown[], errorMessage?: string): Promise<T>;
+    /**
+     * Query multiple rows with automatic tenant scoping
+     */
+    queryMany<T>(table: string, where?: string, whereParams?: unknown[], options?: {
+        orderBy?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<T[]>;
+    /**
+     * Insert a row with automatic tenant_id injection
+     */
+    insert(table: string, data: Record<string, unknown>, options?: {
+        id?: string;
+    }): Promise<string>;
+    /**
+     * Update rows with automatic tenant scoping
+     * The WHERE clause is automatically combined with tenant_id check
+     */
+    update(table: string, data: Record<string, unknown>, where: string, whereParams?: unknown[]): Promise<number>;
+    /**
+     * Update a row by ID with tenant scoping
+     */
+    updateById(table: string, id: string, data: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Delete rows with automatic tenant scoping
+     */
+    delete(table: string, where: string, whereParams?: unknown[]): Promise<number>;
+    /**
+     * Delete a row by ID with tenant scoping
+     */
+    deleteById(table: string, id: string): Promise<boolean>;
+    /**
+     * Check if a row exists with tenant scoping
+     */
+    exists(table: string, where: string, whereParams?: unknown[]): Promise<boolean>;
+    /**
+     * Count rows with tenant scoping
+     */
+    count(table: string, where?: string, whereParams?: unknown[]): Promise<number>;
+    /**
+     * Execute a raw query with tenant scoping
+     *
+     * WARNING: You must ensure the query includes tenant_id filtering.
+     * This method validates that 'tenant_id' appears in the SQL.
+     */
+    rawQuery<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    /**
+     * Execute a raw statement with tenant scoping validation
+     *
+     * WARNING: You must ensure the statement includes tenant_id filtering.
+     */
+    rawExecute(sql: string, params?: unknown[]): Promise<ExecuteResult>;
+}
+/**
+ * Create a tenant-scoped database wrapper
+ *
+ * This is the primary entry point for multi-tenant database access.
+ * All data operations for tenant-specific tables MUST use this wrapper.
+ *
+ * @example
+ * ```ts
+ * // In a SvelteKit load function:
+ * export async function load({ platform, locals }) {
+ *   const tenantDb = getTenantDb(platform.env.DB, { tenantId: locals.tenant.id });
+ *
+ *   const posts = await tenantDb.queryMany<Post>('posts', 'status = ?', ['published']);
+ *   return { posts };
+ * }
+ *
+ * // In an API route:
+ * export async function POST({ request, platform, locals }) {
+ *   const tenantDb = getTenantDb(platform.env.DB, { tenantId: locals.tenant.id });
+ *
+ *   const data = await request.json();
+ *   const postId = await tenantDb.insert('posts', {
+ *     title: data.title,
+ *     content: data.content,
+ *     status: 'draft'
+ *   });
+ *
+ *   return json({ id: postId });
+ * }
+ * ```
+ */
+export declare function getTenantDb(db: D1DatabaseOrSession, context: TenantContext): TenantDb;

package/dist/server/services/database.js

@@ -448,3 +448,237 @@ export async function count(db, table, where, whereParams = []) {
         throw new DatabaseError(`Count on ${table} failed`, 'QUERY_FAILED', err);
     }
 }
+// ============================================================================
+// Multi-Tenant Database Wrapper
+// ============================================================================
+/**
+ * Error thrown when tenant context is missing or invalid
+ */
+export class TenantContextError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TenantContextError';
+    }
+}
+/**
+ * Tenant-aware database wrapper
+ *
+ * This wrapper enforces tenant isolation by:
+ * 1. Automatically adding tenant_id to all INSERT operations
+ * 2. Requiring tenant_id in all SELECT/UPDATE/DELETE WHERE clauses
+ * 3. Validating tenant_id in query results
+ *
+ * SECURITY: This is a critical security boundary. All multi-tenant data access
+ * MUST go through this wrapper to prevent cross-tenant data leaks.
+ *
+ * @example
+ * ```ts
+ * // In your API route or server load function:
+ * const tenantDb = getTenantDb(platform.env.DB, { tenantId: locals.tenant.id });
+ *
+ * // All queries are now automatically scoped to this tenant
+ * const posts = await tenantDb.queryMany<Post>('posts', 'status = ?', ['published']);
+ * // Equivalent to: SELECT * FROM posts WHERE tenant_id = ? AND status = ?
+ * ```
+ */
+export class TenantDb {
+    db;
+    context;
+    constructor(db, context) {
+        if (!context.tenantId) {
+            throw new TenantContextError('Tenant ID is required for database operations');
+        }
+        this.db = db;
+        this.context = context;
+    }
+    /**
+     * Get the tenant ID for this context
+     */
+    get tenantId() {
+        return this.context.tenantId;
+    }
+    /**
+     * Query a single row with automatic tenant scoping
+     */
+    async queryOne(table, where, whereParams = []) {
+        validateTableName(table);
+        const tenantWhere = where
+            ? `tenant_id = ? AND (${where})`
+            : 'tenant_id = ?';
+        const params = [this.context.tenantId, ...whereParams];
+        const sql = `SELECT * FROM ${table} WHERE ${tenantWhere} LIMIT 1`;
+        return queryOne(this.db, sql, params);
+    }
+    /**
+     * Query a single row, throw if not found
+     */
+    async queryOneOrThrow(table, where, whereParams = [], errorMessage = 'Record not found') {
+        const result = await this.queryOne(table, where, whereParams);
+        if (result === null) {
+            throw new DatabaseError(errorMessage, 'NOT_FOUND');
+        }
+        return result;
+    }
+    /**
+     * Query multiple rows with automatic tenant scoping
+     */
+    async queryMany(table, where, whereParams = [], options) {
+        validateTableName(table);
+        const tenantWhere = where
+            ? `tenant_id = ? AND (${where})`
+            : 'tenant_id = ?';
+        const params = [this.context.tenantId, ...whereParams];
+        let sql = `SELECT * FROM ${table} WHERE ${tenantWhere}`;
+        if (options?.orderBy) {
+            // Strict validation for ORDER BY - only allow column names and ASC/DESC
+            const orderParts = options.orderBy.split(/\s+/);
+            if (orderParts.length > 2) {
+                throw new DatabaseError(`Invalid ORDER BY clause: too many parts`, 'VALIDATION_ERROR');
+            }
+            validateColumnName(orderParts[0]);
+            const direction = orderParts[1]?.toUpperCase();
+            if (direction && direction !== 'ASC' && direction !== 'DESC') {
+                throw new DatabaseError(`Invalid ORDER BY direction: ${direction}`, 'VALIDATION_ERROR');
+            }
+            sql += ` ORDER BY ${orderParts[0]}${direction ? ` ${direction}` : ''}`;
+        }
+        if (options?.limit !== undefined) {
+            // Clamp to reasonable bounds to prevent Infinity or excessive values
+            const limit = Math.max(0, Math.min(Math.floor(options.limit), 1000));
+            sql += ` LIMIT ${limit}`;
+        }
+        if (options?.offset !== undefined) {
+            // Clamp to reasonable bounds to prevent Infinity or excessive values
+            const offset = Math.max(0, Math.min(Math.floor(options.offset), 100000));
+            sql += ` OFFSET ${offset}`;
+        }
+        return queryMany(this.db, sql, params);
+    }
+    /**
+     * Insert a row with automatic tenant_id injection
+     */
+    async insert(table, data, options) {
+        const dataWithTenant = {
+            ...data,
+            tenant_id: this.context.tenantId
+        };
+        return insert(this.db, table, dataWithTenant, options);
+    }
+    /**
+     * Update rows with automatic tenant scoping
+     * The WHERE clause is automatically combined with tenant_id check
+     */
+    async update(table, data, where, whereParams = []) {
+        validateTableName(table);
+        const tenantWhere = `tenant_id = ? AND (${where})`;
+        const params = [this.context.tenantId, ...whereParams];
+        return update(this.db, table, data, tenantWhere, params);
+    }
+    /**
+     * Update a row by ID with tenant scoping
+     */
+    async updateById(table, id, data) {
+        const changes = await this.update(table, data, 'id = ?', [id]);
+        return changes > 0;
+    }
+    /**
+     * Delete rows with automatic tenant scoping
+     */
+    async delete(table, where, whereParams = []) {
+        validateTableName(table);
+        const tenantWhere = `tenant_id = ? AND (${where})`;
+        const params = [this.context.tenantId, ...whereParams];
+        return deleteWhere(this.db, table, tenantWhere, params);
+    }
+    /**
+     * Delete a row by ID with tenant scoping
+     */
+    async deleteById(table, id) {
+        const changes = await this.delete(table, 'id = ?', [id]);
+        return changes > 0;
+    }
+    /**
+     * Check if a row exists with tenant scoping
+     */
+    async exists(table, where, whereParams = []) {
+        validateTableName(table);
+        const tenantWhere = `tenant_id = ? AND (${where})`;
+        const params = [this.context.tenantId, ...whereParams];
+        return exists(this.db, table, tenantWhere, params);
+    }
+    /**
+     * Count rows with tenant scoping
+     */
+    async count(table, where, whereParams = []) {
+        validateTableName(table);
+        const tenantWhere = where
+            ? `tenant_id = ? AND (${where})`
+            : 'tenant_id = ?';
+        const params = [this.context.tenantId, ...whereParams];
+        return count(this.db, table, tenantWhere, params);
+    }
+    /**
+     * Execute a raw query with tenant scoping
+     *
+     * WARNING: You must ensure the query includes tenant_id filtering.
+     * This method validates that 'tenant_id' appears in the SQL.
+     */
+    async rawQuery(sql, params = []) {
+        if (!sql.toLowerCase().includes('tenant_id')) {
+            throw new TenantContextError('Raw queries must include tenant_id filtering. Use the scoped methods or add tenant_id to your WHERE clause.');
+        }
+        return queryMany(this.db, sql, params);
+    }
+    /**
+     * Execute a raw statement with tenant scoping validation
+     *
+     * WARNING: You must ensure the statement includes tenant_id filtering.
+     */
+    async rawExecute(sql, params = []) {
+        const sqlLower = sql.toLowerCase();
+        // INSERT statements should have tenant_id in the columns
+        // UPDATE/DELETE statements should have tenant_id in WHERE
+        if (sqlLower.startsWith('insert') && !sqlLower.includes('tenant_id')) {
+            throw new TenantContextError('INSERT statements must include tenant_id. Use the insert() method instead.');
+        }
+        if ((sqlLower.startsWith('update') || sqlLower.startsWith('delete')) &&
+            !sqlLower.includes('tenant_id')) {
+            throw new TenantContextError('UPDATE/DELETE statements must include tenant_id in WHERE clause. Use the scoped methods instead.');
+        }
+        return execute(this.db, sql, params);
+    }
+}
+/**
+ * Create a tenant-scoped database wrapper
+ *
+ * This is the primary entry point for multi-tenant database access.
+ * All data operations for tenant-specific tables MUST use this wrapper.
+ *
+ * @example
+ * ```ts
+ * // In a SvelteKit load function:
+ * export async function load({ platform, locals }) {
+ *   const tenantDb = getTenantDb(platform.env.DB, { tenantId: locals.tenant.id });
+ *
+ *   const posts = await tenantDb.queryMany<Post>('posts', 'status = ?', ['published']);
+ *   return { posts };
+ * }
+ *
+ * // In an API route:
+ * export async function POST({ request, platform, locals }) {
+ *   const tenantDb = getTenantDb(platform.env.DB, { tenantId: locals.tenant.id });
+ *
+ *   const data = await request.json();
+ *   const postId = await tenantDb.insert('posts', {
+ *     title: data.title,
+ *     content: data.content,
+ *     status: 'draft'
+ *   });
+ *
+ *   return json({ id: postId });
+ * }
+ * ```
+ */
+export function getTenantDb(db, context) {
+    return new TenantDb(db, context);
+}

package/dist/server/services/index.d.ts

@@ -29,6 +29,10 @@
 export * as storage from './storage.js';
 export { type StorageFile, type UploadOptions, type GetFileResult, type FileMetadata, StorageError, type StorageErrorCode, uploadFile, getFile, getFileMetadata, fileExists, deleteFile, deleteFileByKey, getFileRecord, getFileRecordByKey, listFiles, listAllFiles, listFolders, updateAltText, validateFile, isAllowedContentType, shouldReturn304, buildFileHeaders } from './storage.js';
 export * as db from './database.js';
-export { type D1DatabaseOrSession, type QueryMeta, type ExecuteResult, DatabaseError, type DatabaseErrorCode, generateId, now, futureTimestamp, isExpired, queryOne, queryOneOrThrow, queryMany, execute, executeOrThrow, batch, withSession, insert, update, deleteWhere, deleteById, exists, count } from './database.js';
+export { type D1DatabaseOrSession, type QueryMeta, type ExecuteResult, type TenantContext, DatabaseError, type DatabaseErrorCode, TenantContextError, generateId, now, futureTimestamp, isExpired, queryOne, queryOneOrThrow, queryMany, execute, executeOrThrow, batch, withSession, insert, update, deleteWhere, deleteById, exists, count, TenantDb, getTenantDb } from './database.js';
 export * as cache from './cache.js';
 export { type CacheOptions, type GetOrSetOptions, CacheError, type CacheErrorCode, get as cacheGet, set as cacheSet, del as cacheDel, getOrSet, getOrSetSync, delMany, delByPrefix, has as cacheHas, touch, rateLimit, CACHE_DEFAULTS } from './cache.js';
+export * as users from './users.js';
+export { type User, getUserByGroveAuthId, getUserById, getUserByEmail, getUserByTenantId, getUserFromSession, getUserFromValidatedSession, linkUserToTenant, updateUserDisplayName, deactivateUser, reactivateUser } from './users.js';
+export * as turnstile from './turnstile.js';
+export { type TurnstileVerifyResult, type TurnstileVerifyOptions, verifyTurnstileToken, TURNSTILE_COOKIE_NAME, TURNSTILE_COOKIE_MAX_AGE, createVerificationCookie, validateVerificationCookie, getVerificationCookieOptions } from './turnstile.js';

package/dist/server/services/index.js

@@ -47,7 +47,7 @@ shouldReturn304, buildFileHeaders } from './storage.js';
 export * as db from './database.js';
 export { 
 // Errors
-DatabaseError, 
+DatabaseError, TenantContextError, 
 // Utilities
 generateId, now, futureTimestamp, isExpired, 
 // Query Helpers
@@ -57,7 +57,9 @@ batch, withSession,
 // CRUD Helpers
 insert, update, deleteWhere, deleteById, 
 // Existence Checks
-exists, count } from './database.js';
+exists, count, 
+// Multi-Tenant
+TenantDb, getTenantDb } from './database.js';
 // ============================================================================
 // Cache Service (KV)
 // ============================================================================
@@ -75,3 +77,23 @@ has as cacheHas, touch,
 rateLimit, 
 // Constants
 CACHE_DEFAULTS } from './cache.js';
+// ============================================================================
+// Users Service (D1)
+// ============================================================================
+export * as users from './users.js';
+export { 
+// Query Functions
+getUserByGroveAuthId, getUserById, getUserByEmail, getUserByTenantId, 
+// Session Functions
+getUserFromSession, getUserFromValidatedSession, 
+// Update Functions
+linkUserToTenant, updateUserDisplayName, deactivateUser, reactivateUser } from './users.js';
+// ============================================================================
+// Turnstile Service (Shade - Human Verification)
+// ============================================================================
+export * as turnstile from './turnstile.js';
+export { 
+// Verification
+verifyTurnstileToken, 
+// Cookie Management
+TURNSTILE_COOKIE_NAME, TURNSTILE_COOKIE_MAX_AGE, createVerificationCookie, validateVerificationCookie, getVerificationCookieOptions } from './turnstile.js';

package/dist/server/services/turnstile.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Turnstile Server-Side Verification (Shade)
+ *
+ * Validates Turnstile tokens with Cloudflare's siteverify endpoint.
+ * Part of Grove's Shade AI protection system.
+ */
+export interface TurnstileVerifyResult {
+    success: boolean;
+    challenge_ts?: string;
+    hostname?: string;
+    'error-codes'?: string[];
+    action?: string;
+    cdata?: string;
+}
+export interface TurnstileVerifyOptions {
+    /** The Turnstile token from the client */
+    token: string;
+    /** The secret key from Cloudflare Dashboard */
+    secretKey: string;
+    /** Optional: The user's IP address for additional validation */
+    remoteip?: string;
+}
+/**
+ * Verify a Turnstile token server-side
+ *
+ * @example
+ * const result = await verifyTurnstileToken({
+ *   token: formData.get('cf-turnstile-response'),
+ *   secretKey: platform.env.TURNSTILE_SECRET_KEY,
+ *   remoteip: request.headers.get('CF-Connecting-IP')
+ * });
+ *
+ * if (!result.success) {
+ *   throw error(403, 'Human verification failed');
+ * }
+ */
+export declare function verifyTurnstileToken(options: TurnstileVerifyOptions): Promise<TurnstileVerifyResult>;
+/**
+ * Cookie name for tracking Turnstile verification status
+ */
+export declare const TURNSTILE_COOKIE_NAME = "grove_verified";
+/**
+ * Cookie max age (7 days in seconds)
+ */
+export declare const TURNSTILE_COOKIE_MAX_AGE: number;
+/**
+ * Create the verification cookie value (signed timestamp)
+ * Simple format: timestamp:hash
+ */
+export declare function createVerificationCookie(secretKey: string): string;
+/**
+ * Validate a verification cookie
+ * Returns true if valid and not expired
+ */
+export declare function validateVerificationCookie(cookie: string | undefined, secretKey: string, maxAgeMs?: number): boolean;
+/**
+ * Get cookie options for the verification cookie
+ */
+export declare function getVerificationCookieOptions(domain?: string): {
+    domain?: string | undefined;
+    path: string;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax";
+    maxAge: number;
+};

package/dist/server/services/turnstile.js

@@ -0,0 +1,131 @@
+/**
+ * Turnstile Server-Side Verification (Shade)
+ *
+ * Validates Turnstile tokens with Cloudflare's siteverify endpoint.
+ * Part of Grove's Shade AI protection system.
+ */
+const TURNSTILE_VERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
+/**
+ * Verify a Turnstile token server-side
+ *
+ * @example
+ * const result = await verifyTurnstileToken({
+ *   token: formData.get('cf-turnstile-response'),
+ *   secretKey: platform.env.TURNSTILE_SECRET_KEY,
+ *   remoteip: request.headers.get('CF-Connecting-IP')
+ * });
+ *
+ * if (!result.success) {
+ *   throw error(403, 'Human verification failed');
+ * }
+ */
+export async function verifyTurnstileToken(options) {
+    const { token, secretKey, remoteip } = options;
+    if (!token) {
+        return {
+            success: false,
+            'error-codes': ['missing-input-response']
+        };
+    }
+    if (!secretKey) {
+        console.error('Turnstile: Missing secret key');
+        return {
+            success: false,
+            'error-codes': ['missing-input-secret']
+        };
+    }
+    const formData = new FormData();
+    formData.append('secret', secretKey);
+    formData.append('response', token);
+    if (remoteip) {
+        formData.append('remoteip', remoteip);
+    }
+    try {
+        const response = await fetch(TURNSTILE_VERIFY_URL, {
+            method: 'POST',
+            body: formData
+        });
+        if (!response.ok) {
+            console.error('Turnstile: Verification request failed', response.status);
+            return {
+                success: false,
+                'error-codes': ['request-failed']
+            };
+        }
+        const result = await response.json();
+        return result;
+    }
+    catch (err) {
+        console.error('Turnstile: Verification error', err);
+        return {
+            success: false,
+            'error-codes': ['network-error']
+        };
+    }
+}
+/**
+ * Cookie name for tracking Turnstile verification status
+ */
+export const TURNSTILE_COOKIE_NAME = 'grove_verified';
+/**
+ * Cookie max age (7 days in seconds)
+ */
+export const TURNSTILE_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
+/**
+ * Create the verification cookie value (signed timestamp)
+ * Simple format: timestamp:hash
+ */
+export function createVerificationCookie(secretKey) {
+    const timestamp = Date.now().toString();
+    // Simple hash using the timestamp and a portion of the secret
+    const hash = simpleHash(timestamp + secretKey.slice(0, 16));
+    return `${timestamp}:${hash}`;
+}
+/**
+ * Validate a verification cookie
+ * Returns true if valid and not expired
+ */
+export function validateVerificationCookie(cookie, secretKey, maxAgeMs = TURNSTILE_COOKIE_MAX_AGE * 1000) {
+    if (!cookie)
+        return false;
+    const parts = cookie.split(':');
+    if (parts.length !== 2)
+        return false;
+    const [timestamp, hash] = parts;
+    const timestampNum = parseInt(timestamp, 10);
+    if (isNaN(timestampNum))
+        return false;
+    // Check expiration
+    if (Date.now() - timestampNum > maxAgeMs)
+        return false;
+    // Verify hash
+    const expectedHash = simpleHash(timestamp + secretKey.slice(0, 16));
+    return hash === expectedHash;
+}
+/**
+ * Simple hash function for cookie signing
+ * Not cryptographically secure, but sufficient for cookie validation
+ */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    return Math.abs(hash).toString(36);
+}
+/**
+ * Get cookie options for the verification cookie
+ */
+export function getVerificationCookieOptions(domain) {
+    return {
+        path: '/',
+        httpOnly: true,
+        secure: true,
+        sameSite: 'lax',
+        maxAge: TURNSTILE_COOKIE_MAX_AGE,
+        // Set domain to .grove.place to work across subdomains
+        ...(domain ? { domain } : {})
+    };
+}