@delma/fylo 1.0.0

package/eslint.config.js

@@ -0,0 +1,28 @@
+import tsPlugin from '@typescript-eslint/eslint-plugin'
+import tsParser from '@typescript-eslint/parser'
+import prettierConfig from 'eslint-config-prettier'
+
+export default [
+    {
+        files: ['src/**/*.ts', 'tests/**/*.ts'],
+        languageOptions: {
+            parser: tsParser,
+            parserOptions: {
+                project: './tsconfig.json'
+            }
+        },
+        plugins: {
+            '@typescript-eslint': tsPlugin
+        },
+        rules: {
+            ...tsPlugin.configs['recommended'].rules,
+            '@typescript-eslint/no-explicit-any': 'warn',
+            '@typescript-eslint/explicit-function-return-type': 'warn',
+            '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }]
+        }
+    },
+    prettierConfig,
+    {
+        ignores: ['bin/**', 'node_modules/**', '**/*.d.ts']
+    }
+]

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@delma/fylo",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "bin": {
+    "fylo.query": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "format": "prettier --write src tests"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.19",
+    "@types/node": "^20.19.39",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^9.0.0",
+    "prettier": "^3.0.0"
+  },
+  "dependencies": {
+    "@vyckr/ttid": "1.3.1",
+    "@vyckr/chex": "0.3.0"
+  },
+  "type": "module",
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Chidelma/Fylo.git"
+  },
+  "homepage": "https://fylo.vyckr.com",
+  "license": "MIT",
+  "keywords": [
+    "storage",
+    "database",
+    "s3",
+    "aws",
+    "typescript",
+    "bun"
+  ],
+  "author": "Chidelma",
+  "bugs": {
+    "url": "https://github.com/Chidelma/Fylo/issues"
+  }
+}

package/src/CLI

@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+/// <reference path="./types/index.d.ts" />
+import Silo from '.'
+
+const SQL = process.argv[process.argv.length - 1]
+
+const op = SQL.match(/^((?:SELECT|select)|(?:INSERT|insert)|(?:UPDATE|update)|(?:DELETE|delete)|(?:CREATE|create)|(?:DROP|drop))/i)
+
+if(!op) throw new Error("Missing SQL Operation")
+
+const res = await new Silo().executeSQL(SQL)
+
+const cmnd = op.shift()!
+
+switch(cmnd.toUpperCase()) {
+    case "CREATE":
+        console.log("Successfully created schema")
+        break
+    case "DROP":
+        console.log("Successfully dropped schema")
+        break
+    case "SELECT":
+        if(typeof res === 'object' && !Array.isArray(res)) console.format(res)
+        else console.log(res)
+        break
+    case "INSERT":
+        console.log(res)
+        break
+    case "UPDATE":
+        console.log(`Successfully updated ${res} document(s)`)
+        break
+    case "DELETE":
+        console.log(`Successfully deleted ${res} document(s)`)
+        break
+    default:
+        throw new Error("Invalid Operation: " + cmnd)
+}

package/src/adapters/cipher.ts

@@ -0,0 +1,174 @@
+/**
+ * AES-256-CBC encryption adapter for field-level value encryption.
+ *
+ * Two modes are supported via the `deterministic` flag on `encrypt()`:
+ *
+ * - **Random IV (default)**: A cryptographically random IV is generated per
+ *   encryption operation. Identical plaintexts produce different ciphertexts.
+ *   Use this for fields that do not need exact-match ($eq/$ne) queries.
+ *
+ * - **Deterministic IV (opt-in)**: The IV is derived from HMAC-SHA256 of the
+ *   plaintext, so identical values always produce identical ciphertext. This
+ *   enables exact-match queries on encrypted fields but leaks equality — an
+ *   observer can determine which records share field values without decrypting.
+ *   Use only when $eq/$ne queries on encrypted fields are required.
+ *
+ * Encrypted fields are declared per-collection in JSON schema files via the
+ * `$encrypted` array. The encryption key is sourced from `ENCRYPTION_KEY` env var.
+ * Set `CIPHER_SALT` to a unique random value to prevent cross-deployment attacks.
+ */
+
+export class Cipher {
+
+    private static key: CryptoKey | null = null
+    private static hmacKey: CryptoKey | null = null
+
+    /** Per-collection encrypted field sets, loaded from schema `$encrypted` arrays. */
+    private static collections: Map<string, Set<string>> = new Map()
+
+    static isConfigured(): boolean {
+        return Cipher.key !== null
+    }
+
+    static hasEncryptedFields(collection: string): boolean {
+        const fields = Cipher.collections.get(collection)
+        return !!fields && fields.size > 0
+    }
+
+    static isEncryptedField(collection: string, field: string): boolean {
+        const fields = Cipher.collections.get(collection)
+        if (!fields || fields.size === 0) return false
+
+        for (const pattern of fields) {
+            if (field === pattern) return true
+            // Support nested: encrypting "address" encrypts "address/city" etc.
+            if (field.startsWith(`${pattern}/`)) return true
+        }
+
+        return false
+    }
+
+    /**
+     * Registers encrypted fields for a collection (from schema `$encrypted` array).
+     */
+    static registerFields(collection: string, fields: string[]): void {
+        if (fields.length > 0) {
+            Cipher.collections.set(collection, new Set(fields))
+        }
+    }
+
+    /**
+     * Derives AES + HMAC keys from a secret string. Called once at startup.
+     */
+    static async configure(secret: string): Promise<void> {
+        const encoder = new TextEncoder()
+        const keyMaterial = await crypto.subtle.importKey(
+            'raw',
+            encoder.encode(secret),
+            'PBKDF2',
+            false,
+            ['deriveBits']
+        )
+
+        const cipherSalt = process.env.CIPHER_SALT
+        if (!cipherSalt) {
+            console.warn('CIPHER_SALT is not set. Using default salt is insecure for multi-deployment use. Set CIPHER_SALT to a unique random value.')
+        }
+
+        // Derive 48 bytes: 32 for AES key + 16 for HMAC key
+        const bits = await crypto.subtle.deriveBits(
+            { name: 'PBKDF2', salt: encoder.encode(cipherSalt ?? 'fylo-cipher'), iterations: 100000, hash: 'SHA-256' },
+            keyMaterial,
+            384
+        )
+
+        const derived = new Uint8Array(bits)
+
+        Cipher.key = await crypto.subtle.importKey(
+            'raw',
+            derived.slice(0, 32),
+            { name: 'AES-CBC' },
+            false,
+            ['encrypt', 'decrypt']
+        )
+
+        Cipher.hmacKey = await crypto.subtle.importKey(
+            'raw',
+            derived.slice(32),
+            { name: 'HMAC', hash: 'SHA-256' },
+            false,
+            ['sign']
+        )
+    }
+
+    static reset(): void {
+        Cipher.key = null
+        Cipher.hmacKey = null
+        Cipher.collections = new Map()
+    }
+
+    /**
+     * Deterministic IV from HMAC-SHA256 of plaintext, truncated to 16 bytes.
+     */
+    private static async deriveIV(plaintext: string): Promise<Uint8Array> {
+        const encoder = new TextEncoder()
+        const sig = await crypto.subtle.sign('HMAC', Cipher.hmacKey!, encoder.encode(plaintext))
+        return new Uint8Array(sig).slice(0, 16)
+    }
+
+    /**
+     * Encrypts a value. Returns a URL-safe base64 string (no slashes).
+     *
+     * @param value - The plaintext to encrypt.
+     * @param deterministic - When true, derives IV from HMAC of plaintext (same
+     *   input always produces same ciphertext). Required for $eq/$ne queries on
+     *   encrypted fields. Defaults to false (random IV per operation).
+     */
+    static async encrypt(value: string, deterministic = false): Promise<string> {
+        if (!Cipher.key) throw new Error('Cipher not configured — set ENCRYPTION_KEY env var')
+
+        const iv = deterministic
+            ? await Cipher.deriveIV(value)
+            : crypto.getRandomValues(new Uint8Array(16))
+        const encoder = new TextEncoder()
+
+        const encrypted = await crypto.subtle.encrypt(
+            { name: 'AES-CBC', iv },
+            Cipher.key,
+            encoder.encode(value)
+        )
+
+        // Concatenate IV + ciphertext and encode as URL-safe base64
+        const combined = new Uint8Array(iv.length + encrypted.byteLength)
+        combined.set(iv)
+        combined.set(new Uint8Array(encrypted), iv.length)
+
+        return btoa(String.fromCharCode(...combined))
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=+$/, '')
+    }
+
+    /**
+     * Decrypts a URL-safe base64 encoded value back to plaintext.
+     */
+    static async decrypt(encoded: string): Promise<string> {
+        if (!Cipher.key) throw new Error('Cipher not configured — set ENCRYPTION_KEY env var')
+
+        // Restore standard base64
+        const b64 = encoded.replace(/-/g, '+').replace(/_/g, '/')
+        const padded = b64 + '='.repeat((4 - b64.length % 4) % 4)
+
+        const combined = Uint8Array.from(atob(padded), c => c.charCodeAt(0))
+        const iv = combined.slice(0, 16)
+        const ciphertext = combined.slice(16)
+
+        const decrypted = await crypto.subtle.decrypt(
+            { name: 'AES-CBC', iv },
+            Cipher.key,
+            ciphertext
+        )
+
+        return new TextDecoder().decode(decrypted)
+    }
+}

package/src/adapters/redis.ts

@@ -0,0 +1,71 @@
+import { RedisClient } from "bun";
+import { S3 } from "./s3";
+
+export class Redis {
+
+    private client: RedisClient
+
+    private static LOGGING = process.env.LOGGING
+
+    constructor() {
+
+        const redisUrl = process.env.REDIS_URL
+        if (!redisUrl) throw new Error('REDIS_URL environment variable is required')
+
+        this.client = new RedisClient(redisUrl, {
+            connectionTimeout: process.env.REDIS_CONN_TIMEOUT ? Number(process.env.REDIS_CONN_TIMEOUT) : undefined,
+            idleTimeout: process.env.REDIS_IDLE_TIMEOUT ? Number(process.env.REDIS_IDLE_TIMEOUT) : undefined,
+            autoReconnect: process.env.REDIS_AUTO_CONNECT ? true : undefined,
+            maxRetries: process.env.REDIS_MAX_RETRIES ? Number(process.env.REDIS_MAX_RETRIES) : undefined,
+            enableOfflineQueue: process.env.REDIS_ENABLE_OFFLINE_QUEUE ? true : undefined,
+            enableAutoPipelining: process.env.REDIS_ENABLE_AUTO_PIPELINING ? true : undefined,
+            tls: process.env.REDIS_TLS ? true : undefined
+        })
+
+        this.client.onconnect = () => {
+            if(Redis.LOGGING) console.log("Client Connected")
+        }
+
+        this.client.onclose = (err) => console.error("Redis client connection closed", err.message)
+
+        this.client.connect()
+    }
+
+    async publish(collection: string, action: 'insert' | 'delete', keyId: string | _ttid) {
+
+        if(this.client.connected) {
+
+            await this.client.publish(S3.getBucketFormat(collection), JSON.stringify({ action, keyId }))
+        }
+    }
+
+    async claimTTID(_id: _ttid, ttlSeconds: number = 10): Promise<boolean> {
+
+        if(!this.client.connected) return false
+
+        const result = await this.client.send('SET', [`ttid:${_id}`, '1', 'NX', 'EX', String(ttlSeconds)])
+
+        return result === 'OK'
+    }
+
+    async *subscribe(collection: string) {
+
+        if(!this.client.connected) throw new Error('Redis not connected!')
+
+        const client = this.client
+
+        const stream = new ReadableStream({
+            async start(controller) {
+                await client.subscribe(S3.getBucketFormat(collection), (message) => {
+                    controller.enqueue(message)
+                })
+            },
+        })
+
+        for await (const chunk of stream) {
+            const parsed = JSON.parse(chunk)
+            if (typeof parsed !== 'object' || parsed === null || !('action' in parsed) || !('keyId' in parsed)) continue
+            yield parsed
+        }
+    }
+}

package/src/adapters/s3.ts

@@ -0,0 +1,67 @@
+import { $, S3Client } from "bun"
+
+export class S3 {
+
+    static readonly BUCKET_ENV = process.env.BUCKET_PREFIX
+
+    static readonly CREDS = {
+        accessKeyId: process.env.S3_ACCESS_KEY_ID ?? process.env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY ?? process.env.AWS_SECRET_ACCESS_KEY,
+        region: process.env.S3_REGION ?? process.env.AWS_REGION,
+        endpoint: process.env.S3_ENDPOINT ?? process.env.AWS_ENDPOINT
+    }
+
+    private static validateCollection(collection: string): void {
+        if (!/^[a-z0-9][a-z0-9\-]*[a-z0-9]$/.test(collection)) {
+            throw new Error('Invalid collection name')
+        }
+    }
+
+    static getBucketFormat(collection: string) {
+        S3.validateCollection(collection)
+        return S3.BUCKET_ENV ? `${S3.BUCKET_ENV}-${collection}` : collection
+    }
+
+    static file(collection: string, path: string) {
+
+        return S3Client.file(path, {
+            bucket: S3.getBucketFormat(collection),
+            ...S3.CREDS
+        })
+    }
+
+    static async list(collection: string, options?: Bun.S3ListObjectsOptions) {
+
+        return await S3Client.list(options, {
+            bucket: S3.getBucketFormat(collection),
+            ...S3.CREDS
+        })
+    }
+
+    static async put(collection: string, path: string, data: string) {
+
+        await S3Client.write(path, data, {
+            bucket: S3.getBucketFormat(collection),
+            ...S3.CREDS
+        })
+    }
+
+    static async delete(collection: string, path: string) {
+
+        await S3Client.delete(path, {
+            bucket: S3.getBucketFormat(collection),
+            ...S3.CREDS
+        })
+    }
+
+    static async createBucket(collection: string) {
+        const endpoint = S3.CREDS.endpoint
+        await $`aws s3 mb s3://${S3.getBucketFormat(collection)} ${endpoint ? `--endpoint-url=${endpoint}` : ""}`.quiet()
+    }
+
+    static async deleteBucket(collection: string) {
+        const endpoint = S3.CREDS.endpoint
+        await $`aws s3 rm s3://${S3.getBucketFormat(collection)} --recursive ${endpoint ? `--endpoint-url=${endpoint}` : ""}`.quiet()
+        await $`aws s3 rb s3://${S3.getBucketFormat(collection)} ${endpoint ? `--endpoint-url=${endpoint}` : ""}`.quiet()
+    }
+}