@everystack/storage 0.2.0 → 0.3.0

package/LICENSE

@@ -16,7 +16,7 @@ A commercial license is available for organizations that cannot or do not
 wish to comply with the AGPL-3.0 terms. Commercial licenses are issued
 exclusively by Scalable Technology, Inc.
 
-For commercial licensing inquiries, contact: licensing@scalabletechnology.com
+For commercial licensing inquiries, contact: licensing@scalable.technology
 
                     GNU AFFERO GENERAL PUBLIC LICENSE
                        Version 3, 19 November 2007

package/README.md

@@ -267,4 +267,8 @@ Part of [everystack](https://github.com/scalable-technology/everystack) — a se
 
 ## License
 
-MIT
+[AGPL-3.0-only](https://www.gnu.org/licenses/agpl-3.0.html) © Scalable Technology, Inc.
+
+A commercial license is available for organizations that cannot or do not wish to
+comply with the AGPL-3.0 terms. For commercial licensing, contact
+licensing@scalable.technology.

package/package.json

@@ -1,8 +1,18 @@
 {
   "name": "@everystack/storage",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "File uploads via S3 + CloudFront CDN with presigned URLs",
   "license": "AGPL-3.0-only",
+  "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scalable-technology/everystack.git",
+    "directory": "packages/storage"
+  },
+  "homepage": "https://github.com/scalable-technology/everystack#readme",
+  "bugs": {
+    "url": "https://github.com/scalable-technology/everystack/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -19,6 +29,10 @@
       "types": "./src/schema.ts",
       "default": "./src/schema.ts"
     },
+    "./models": {
+      "types": "./src/models/index.ts",
+      "default": "./src/models/index.ts"
+    },
     "./client": {
       "types": "./src/client/index.ts",
       "default": "./src/client/index.ts"
@@ -28,9 +42,12 @@
       "default": "./src/plugin.ts"
     }
   },
+  "dependencies": {
+    "@everystack/model": "0.3.3"
+  },
   "peerDependencies": {
-    "@aws-sdk/client-s3": "3.1045.0",
-    "@aws-sdk/s3-request-presigner": "3.1045.0",
+    "@aws-sdk/client-s3": "3.1053.0",
+    "@aws-sdk/s3-request-presigner": "3.1053.0",
     "@everystack/server": ">=0.1.0",
     "drizzle-orm": "0.41.0",
     "react": "19.2.6",
@@ -54,8 +71,8 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1045.0",
-    "@aws-sdk/s3-request-presigner": "3.1045.0",
+    "@aws-sdk/client-s3": "3.1053.0",
+    "@aws-sdk/s3-request-presigner": "3.1053.0",
     "@testing-library/react-native": "13.3.3",
     "@types/jest": "29.5.14",
     "@types/node": "22.19.18",
@@ -66,7 +83,7 @@
     "react-test-renderer": "19.2.6",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/server": "0.2.0"
+    "@everystack/server": "0.3.1"
   },
   "scripts": {
     "test": "jest",

package/src/handler/index.ts

@@ -14,12 +14,34 @@ async function computeSha256(data: ArrayBuffer | Buffer | Uint8Array): Promise<s
     .join('');
 }
 
+// Postgres identifier rule — the only value interpolated into SET ROLE. The role is set by
+// server config, never user input, but validate defensively against injection.
+const ROLE_NAME = /^[a-z_][a-z0-9_]*$/;
+
 export function createStorageHandler(options: StorageHandlerOptions): (request: Request) => Promise<Response> {
   const basePath = options.basePath || '';
   const { db, storage, auth, validation, publishJob } = options;
   const allowUnauthenticated = options.allowUnauthenticated === true;
   const keyGenerator = options.keyGenerator || defaultKeyGenerator;
   const bucket = options.bucket || 'default';
+  const role = options.role;
+  if (role && !ROLE_NAME.test(role)) {
+    throw new Error(`Invalid role name: ${role}`);
+  }
+
+  /**
+   * Run `fn` against the connection — directly when no role is configured, or inside a
+   * SET LOCAL ROLE transaction when one is (the least-privilege API path: dist.blobs is
+   * reachable only via the admin policy). Per-user ownership is still enforced in the handler.
+   */
+  async function scope(fn: (db: any) => any): Promise<any> {
+    if (!role) return fn(db);
+    return db.transaction(async (tx: any) => {
+      await tx.execute(sql.raw(`SET LOCAL ROLE ${role}`));
+      await tx.execute(sql`SELECT set_config('request.jwt.claims', ${JSON.stringify({ role })}, true)`);
+      return fn(tx);
+    });
+  }
 
   function json(data: unknown, status: number = 200): Response {
     return new Response(JSON.stringify(data), {
@@ -121,8 +143,8 @@ export function createStorageHandler(options: StorageHandlerOptions): (request:
       // Compute content hash for dedup
       const sha256 = await computeSha256(buffer);
 
-      // Write metadata to DB
-      const result = await db
+      // Write metadata to DB (as the configured role; dist.blobs is admin-policy gated).
+      const result = await scope((d) => d
         .insert(blobs)
         .values({
           type: 'original',
@@ -136,7 +158,7 @@ export function createStorageHandler(options: StorageHandlerOptions): (request:
             userId: (user.sub as string) || null,
           },
         })
-        .returning({ id: blobs.id });
+        .returning({ id: blobs.id }));
 
       const uploadId = result[0].id;
 
@@ -180,15 +202,13 @@ export function createStorageHandler(options: StorageHandlerOptions): (request:
       const limit = Math.min(Math.max(1, parsedLimit || 50), maxLimit);
       const offset = url.searchParams.has('offset') ? Math.max(0, parseInt(url.searchParams.get('offset')!, 10) || 0) : 0;
 
-      let query = db.select().from(blobs);
-
-      if (user.sub) {
-        query = query.where(sql`${blobs.metadata}->>'userId' = ${user.sub}`);
-      }
-
-      query = query.orderBy(sql`${blobs.createdAt} DESC`).limit(limit).offset(offset);
-
-      const result = await query;
+      const result = await scope((d) => {
+        let query = d.select().from(blobs);
+        if (user.sub) {
+          query = query.where(sql`${blobs.metadata}->>'userId' = ${user.sub}`);
+        }
+        return query.orderBy(sql`${blobs.createdAt} DESC`).limit(limit).offset(offset);
+      });
       return json(result);
     }
 
@@ -198,10 +218,10 @@ export function createStorageHandler(options: StorageHandlerOptions): (request:
       const user = await verifyAuth(request);
       if (!user) return json({ error: 'Unauthorized' }, 401);
 
-      const result = await db
+      const result = await scope((d) => d
         .select()
         .from(blobs)
-        .where(sql`${blobs.id} = ${uploadMatch[1]}`);
+        .where(sql`${blobs.id} = ${uploadMatch[1]}`));
 
       if (!result[0]) return json({ error: 'Upload not found' }, 404);
 
@@ -220,10 +240,10 @@ export function createStorageHandler(options: StorageHandlerOptions): (request:
       const user = await verifyAuth(request);
       if (!user) return json({ error: 'Unauthorized' }, 401);
 
-      const result = await db
+      const result = await scope((d) => d
         .select()
         .from(blobs)
-        .where(sql`${blobs.id} = ${deleteMatch[1]}`);
+        .where(sql`${blobs.id} = ${deleteMatch[1]}`));
 
       if (!result[0]) return json({ error: 'Upload not found' }, 404);
 
@@ -234,7 +254,7 @@ export function createStorageHandler(options: StorageHandlerOptions): (request:
       }
 
       await storage.delete(result[0].s3Key!);
-      await db.delete(blobs).where(sql`${blobs.id} = ${deleteMatch[1]}`);
+      await scope((d) => d.delete(blobs).where(sql`${blobs.id} = ${deleteMatch[1]}`));
 
       return json({ ok: true });
     }

package/src/models/blob.ts

@@ -0,0 +1,55 @@
+/**
+ * dist.blobs — the content-addressed S3 object registry (deduped by sha256).
+ *
+ * The v3 Model that owns this table's schema AND its authorization. The drizzle
+ * runtime table (`../schema`) derives from it, and `db:generate` reads it to emit
+ * the table's DDL + RLS + grants — so the package, not the consuming app, owns
+ * dist.blobs end to end.
+ *
+ * Authz shape (matches the live 0020 migration):
+ *  - `writtenBy: 'worker'` — the image worker writes derived blobs (thumbnail/webp)
+ *    as the table owner and must keep its owner bypass, so RLS is ENABLE-not-FORCE.
+ *  - `can('manage', { role: 'admin' })` — the storage handler runs as `admin`
+ *    (SET ROLE) and enforces per-user ownership in code; admin gets CRUD + the
+ *    `blobs_admin` policy. No anon/authenticated grant exists.
+ *  - `private: true` — reached through the storage handler (/api/storage), never the
+ *    generic data API, so it never enters `exposedTables`.
+ */
+
+import { defineModel, field, can, index } from '@everystack/model';
+
+export const Blob = defineModel('blobs', {
+  schema: 'dist',
+  writtenBy: 'worker',
+  private: true,
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    repositoryId: field.uuid().nullable(),
+    type: field.text().notNull(), // 'original' | 'thumbnail' | 'preview' | 'webp' | …
+    sha256: field.text().notNull().unique(),
+
+    // S3 object location (bytes live in S3, not the database)
+    s3Key: field.text().nullable(),
+    bucket: field.text().nullable(),
+
+    sizeBytes: field.bigint().notNull(),
+    contentType: field.text().nullable(),
+
+    // Derived content (thumbnail → original, webp → original, …)
+    parentId: field.uuid().nullable(),
+
+    // Intrinsic content metadata ({ width, height, format, originalName, userId })
+    metadata: field.jsonb().nullable(),
+
+    createdAt: field.timestamptz().defaultNow().notNull(),
+  },
+  constraints: [
+    index('type'),
+    index('contentType'),
+    index('createdAt'),
+    index('repositoryId'),
+    index('parentId'),
+    index('s3Key'),
+  ],
+  abilities: [can('manage', { role: 'admin' })],
+});

package/src/models/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Storage's package-owned models. A consuming app composes these into its own
+ * model list so `db:generate` emits dist.blobs' schema + authz alongside the app's
+ * tables: `models = [...appModels, ...storageModels]`.
+ */
+
+export { Blob } from './blob';
+
+import { defineModule } from '@everystack/model';
+import { Blob } from './blob';
+
+/** All storage-owned models, for the app to spread into its db:generate model list. */
+export const storageModels = [Blob];
+
+/** The storage Module — dist.blobs (schema + authz). No functions/extensions of its own. */
+export const storageModule = defineModule({ models: storageModels });

package/src/plugin.ts

@@ -20,6 +20,12 @@ export interface StoragePluginOptions {
   basePath?: string;
   /** Presigned URL expiry in seconds (default: 3600) */
   presignedUrlExpiry?: number;
+  /**
+   * Postgres role for the dist.blobs access (e.g. 'admin' on the least-privilege API
+   * connection, so the handler reaches dist.blobs under the admin policy). Unset = run on the
+   * bound connection (single-credential / owner apps).
+   */
+  role?: string;
 }
 
 export function storagePlugin(options: StoragePluginOptions): Plugin {
@@ -44,6 +50,7 @@ export function storagePlugin(options: StoragePluginOptions): Plugin {
       validation: options.validation,
       publishJob: ctx.publishJob,
       presignedUrlExpiry: options.presignedUrlExpiry,
+      role: options.role,
     });
 
     return {

package/src/schema.ts

@@ -1,87 +1,15 @@
 /**
- * Storage schema — everyschema dist.blobs
+ * Storage schema — dist.blobs, the runtime drizzle table.
  *
- * Content-addressed storage — in-DB (bytea) or S3-backed.
- * Replaces the old `uploads` table.
- *
- * Type values for everystack:
- *   'original'  — user-uploaded content (S3-backed)
- *   'thumbnail' — derived image variant (parentId → original)
- *   'preview'   — derived preview image
- *   'webp'      — derived WebP variant
- *
- * @see everyschema — canonical schema definitions
- */
-
-import {
-  pgSchema,
-  text,
-  timestamp,
-  uuid,
-  bigint,
-  index,
-  uniqueIndex,
-  jsonb,
-  customType,
-} from 'drizzle-orm/pg-core';
-
-const distSchema = pgSchema('dist');
-
-const bytea = customType<{ data: Buffer; driverValue: Buffer }>({
-  dataType() {
-    return 'bytea';
-  },
-});
-
-// =============================================================================
-// BLOBS - Raw binary storage, deduped by sha256
-// =============================================================================
-
-/**
- * Content-addressed storage — in-DB or S3-backed.
- *
- * Storage modes:
- *   In-DB:  data (bytea) populated, s3Key/bucket NULL
- *   S3:     s3Key + bucket populated, data NULL
- *
- * Derived content uses parentId:
- *   original → thumbnail, preview, webp, etc.
+ * DERIVED from the package-owned Model (`./models/blob`) — the Model is the single
+ * source of the table's columns, schema, indexes, and authz; this just materializes
+ * the drizzle-orm runtime object the handler queries. Edit the Model, not this file.
  *
- * metadata stores intrinsic content properties:
- *   Images: { width, height, format, originalName, userId }
- *   Video/audio: { codec, duration, bitrate }
+ * Content-addressed storage — S3-backed (the object registry; bytes live in S3).
+ * Replaces the old `uploads` table.
  */
-export const blobs = distSchema.table(
-  'blobs',
-  {
-    id: uuid('id').primaryKey().defaultRandom(),
-    repositoryId: uuid('repository_id'),
-    type: text('type').notNull(), // 'original' | 'thumbnail' | 'preview' | 'webp' | etc.
-    sha256: text('sha256').notNull().unique(),
-
-    // Storage: in-DB (bytea) or S3-backed (s3Key + bucket)
-    data: bytea('data'),
-    s3Key: text('s3_key'),
-    bucket: text('bucket'),
-
-    sizeBytes: bigint('size_bytes', { mode: 'number' }).notNull(),
-    contentType: text('content_type'),
-
-    // Derived content (thumbnail → original, webp → original, etc.)
-    parentId: uuid('parent_id'),
 
-    // Intrinsic content metadata
-    metadata: jsonb('metadata'),
+import { toDrizzleTable } from '@everystack/model/drizzle';
+import { Blob } from './models/blob';
 
-    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
-  },
-  (table) => ({
-    typeIdx: index('blobs_type_idx').on(table.type),
-    sha256Idx: uniqueIndex('blobs_sha256_idx').on(table.sha256),
-    contentTypeIdx: index('blobs_content_type_idx').on(table.contentType),
-    createdAtIdx: index('blobs_created_at_idx').on(table.createdAt),
-    repoIdx: index('blobs_repo_idx').on(table.repositoryId),
-    parentIdx: index('blobs_parent_idx').on(table.parentId),
-    s3KeyIdx: index('blobs_s3_key_idx').on(table.s3Key),
-  })
-);
+export const blobs = toDrizzleTable(Blob);

package/src/types.ts

@@ -51,4 +51,13 @@ export interface StorageHandlerOptions {
   presignedUrlExpiry?: number;
   /** Maximum value for ?limit= on listing endpoints. Default: 1000. */
   maxLimit?: number;
+  /**
+   * Postgres role to run the dist.blobs access as. On the least-privilege API connection
+   * (`authenticator`) set this to `admin` so the handler reaches dist.blobs under the admin
+   * policy; the per-user ownership check stays in the handler (metadata.userId === sub). Unset
+   * = run directly on the bound connection (single-credential / owner apps). When set, each DB
+   * operation runs inside a transaction with SET LOCAL ROLE (transaction-scoped, resets on
+   * return).
+   */
+  role?: string;
 }