graphile-presigned-url-plugin 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# graphile-presigned-url-plugin
+
+Presigned URL upload plugin for PostGraphile v5.
+
+## Features
+
+- `requestUploadUrl` mutation — generates presigned PUT URLs for direct client-to-S3 upload
+- `confirmUpload` mutation — verifies upload and transitions file status to 'ready'
+- `downloadUrl` computed field — presigned GET URLs for private files, public URLs for public files
+- Content-hash based S3 keys (SHA-256) with automatic deduplication
+- Per-bucket MIME type and file size validation
+- Upload request tracking for audit and rate limiting
+
+## Usage
+
+```typescript
+import { PresignedUrlPreset } from 'graphile-presigned-url-plugin';
+import { S3Client } from '@aws-sdk/client-s3';
+
+const s3Client = new S3Client({ region: 'us-east-1' });
+
+const preset = {
+  extends: [
+    PresignedUrlPreset({
+      s3: {
+        client: s3Client,
+        bucket: 'my-uploads',
+        publicUrlPrefix: 'https://cdn.example.com',
+      },
+      urlExpirySeconds: 900,
+      maxFileSize: 200 * 1024 * 1024,
+    }),
+  ],
+};
+```
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/download-url-field.d.ts

@@ -0,0 +1,27 @@
+/**
+ * downloadUrl Computed Field Plugin
+ *
+ * Adds a `downloadUrl` computed field to File types in the GraphQL schema.
+ * For public files, returns the public URL prefix + key.
+ * For private files, generates a presigned GET URL.
+ *
+ * Detection: Uses the `@storageFiles` smart tag on the codec (table).
+ * The storage module generator in constructive-db sets this tag on the
+ * generated files table via a smart comment:
+ *   COMMENT ON TABLE files IS E'@storageFiles\nStorage files table';
+ *
+ * This is explicit and reliable — no duck-typing on column names.
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { PresignedUrlPluginOptions } from './types';
+/**
+ * Creates the downloadUrl computed field plugin.
+ *
+ * This is a separate plugin from the main presigned URL plugin because it
+ * uses the GraphQLObjectType_fields hook (low-level) rather than extendSchema.
+ * The downloadUrl field needs to be added dynamically to whatever table is
+ * the storage module's files table, which we discover at schema-build time
+ * via the `@storageFiles` smart tag.
+ */
+export declare function createDownloadUrlPlugin(options: PresignedUrlPluginOptions): GraphileConfig.Plugin;
+export default createDownloadUrlPlugin;

package/download-url-field.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * downloadUrl Computed Field Plugin
+ *
+ * Adds a `downloadUrl` computed field to File types in the GraphQL schema.
+ * For public files, returns the public URL prefix + key.
+ * For private files, generates a presigned GET URL.
+ *
+ * Detection: Uses the `@storageFiles` smart tag on the codec (table).
+ * The storage module generator in constructive-db sets this tag on the
+ * generated files table via a smart comment:
+ *   COMMENT ON TABLE files IS E'@storageFiles\nStorage files table';
+ *
+ * This is explicit and reliable — no duck-typing on column names.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDownloadUrlPlugin = createDownloadUrlPlugin;
+const logger_1 = require("@pgpmjs/logger");
+const s3_signer_1 = require("./s3-signer");
+const storage_module_cache_1 = require("./storage-module-cache");
+const log = new logger_1.Logger('graphile-presigned-url:download-url');
+/**
+ * Creates the downloadUrl computed field plugin.
+ *
+ * This is a separate plugin from the main presigned URL plugin because it
+ * uses the GraphQLObjectType_fields hook (low-level) rather than extendSchema.
+ * The downloadUrl field needs to be added dynamically to whatever table is
+ * the storage module's files table, which we discover at schema-build time
+ * via the `@storageFiles` smart tag.
+ */
+function createDownloadUrlPlugin(options) {
+    const { s3 } = options;
+    return {
+        name: 'PresignedUrlDownloadPlugin',
+        version: '0.1.0',
+        description: 'Adds downloadUrl computed field to File types tagged with @storageFiles',
+        schema: {
+            hooks: {
+                GraphQLObjectType_fields(fields, build, context) {
+                    const { scope: { pgCodec, isPgClassType }, } = context;
+                    // Only process PG class types (table row types)
+                    if (!isPgClassType || !pgCodec || !pgCodec.attributes) {
+                        return fields;
+                    }
+                    // Check for @storageFiles smart tag — set by the storage module generator
+                    const tags = pgCodec.extensions?.tags;
+                    if (!tags?.storageFiles) {
+                        return fields;
+                    }
+                    log.debug(`Adding downloadUrl field to type: ${pgCodec.name} (has @storageFiles tag)`);
+                    const { graphql: { GraphQLString }, } = build;
+                    return build.extend(fields, {
+                        downloadUrl: context.fieldWithHooks({ fieldName: 'downloadUrl' }, {
+                            description: 'URL to download this file. For public files, returns the public URL. ' +
+                                'For private files, returns a time-limited presigned URL.',
+                            type: GraphQLString,
+                            async resolve(parent, _args, context) {
+                                const key = parent.key || parent.get?.('key');
+                                const isPublic = parent.is_public ?? parent.get?.('is_public');
+                                const filename = parent.filename || parent.get?.('filename');
+                                const status = parent.status || parent.get?.('status');
+                                if (!key)
+                                    return null;
+                                // Only provide download URLs for ready/processed files
+                                if (status !== 'ready' && status !== 'processed') {
+                                    return null;
+                                }
+                                if (isPublic && s3.publicUrlPrefix) {
+                                    // Public file: return direct URL
+                                    return `${s3.publicUrlPrefix}/${key}`;
+                                }
+                                // Resolve download URL expiry from storage module config (per-database)
+                                let downloadUrlExpirySeconds = 3600; // fallback default
+                                try {
+                                    const withPgClient = context.pgSettings
+                                        ? context.withPgClient
+                                        : null;
+                                    if (withPgClient) {
+                                        const config = await withPgClient(null, async (pgClient) => {
+                                            const dbResult = await pgClient.query(`SELECT jwt_private.current_database_id() AS id`);
+                                            const databaseId = dbResult.rows[0]?.id;
+                                            if (!databaseId)
+                                                return null;
+                                            return (0, storage_module_cache_1.getStorageModuleConfig)(pgClient, databaseId);
+                                        });
+                                        if (config) {
+                                            downloadUrlExpirySeconds = config.downloadUrlExpirySeconds;
+                                        }
+                                    }
+                                }
+                                catch {
+                                    // Fall back to default if config lookup fails
+                                }
+                                // Private file: generate presigned GET URL
+                                return (0, s3_signer_1.generatePresignedGetUrl)(s3, key, downloadUrlExpirySeconds, filename || undefined);
+                            },
+                        }),
+                    }, 'PresignedUrlDownloadPlugin adding downloadUrl field');
+                },
+            },
+        },
+    };
+}
+exports.default = createDownloadUrlPlugin;

package/esm/download-url-field.d.ts

@@ -0,0 +1,27 @@
+/**
+ * downloadUrl Computed Field Plugin
+ *
+ * Adds a `downloadUrl` computed field to File types in the GraphQL schema.
+ * For public files, returns the public URL prefix + key.
+ * For private files, generates a presigned GET URL.
+ *
+ * Detection: Uses the `@storageFiles` smart tag on the codec (table).
+ * The storage module generator in constructive-db sets this tag on the
+ * generated files table via a smart comment:
+ *   COMMENT ON TABLE files IS E'@storageFiles\nStorage files table';
+ *
+ * This is explicit and reliable — no duck-typing on column names.
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { PresignedUrlPluginOptions } from './types';
+/**
+ * Creates the downloadUrl computed field plugin.
+ *
+ * This is a separate plugin from the main presigned URL plugin because it
+ * uses the GraphQLObjectType_fields hook (low-level) rather than extendSchema.
+ * The downloadUrl field needs to be added dynamically to whatever table is
+ * the storage module's files table, which we discover at schema-build time
+ * via the `@storageFiles` smart tag.
+ */
+export declare function createDownloadUrlPlugin(options: PresignedUrlPluginOptions): GraphileConfig.Plugin;
+export default createDownloadUrlPlugin;

package/esm/download-url-field.js

@@ -0,0 +1,101 @@
+/**
+ * downloadUrl Computed Field Plugin
+ *
+ * Adds a `downloadUrl` computed field to File types in the GraphQL schema.
+ * For public files, returns the public URL prefix + key.
+ * For private files, generates a presigned GET URL.
+ *
+ * Detection: Uses the `@storageFiles` smart tag on the codec (table).
+ * The storage module generator in constructive-db sets this tag on the
+ * generated files table via a smart comment:
+ *   COMMENT ON TABLE files IS E'@storageFiles\nStorage files table';
+ *
+ * This is explicit and reliable — no duck-typing on column names.
+ */
+import { Logger } from '@pgpmjs/logger';
+import { generatePresignedGetUrl } from './s3-signer';
+import { getStorageModuleConfig } from './storage-module-cache';
+const log = new Logger('graphile-presigned-url:download-url');
+/**
+ * Creates the downloadUrl computed field plugin.
+ *
+ * This is a separate plugin from the main presigned URL plugin because it
+ * uses the GraphQLObjectType_fields hook (low-level) rather than extendSchema.
+ * The downloadUrl field needs to be added dynamically to whatever table is
+ * the storage module's files table, which we discover at schema-build time
+ * via the `@storageFiles` smart tag.
+ */
+export function createDownloadUrlPlugin(options) {
+    const { s3 } = options;
+    return {
+        name: 'PresignedUrlDownloadPlugin',
+        version: '0.1.0',
+        description: 'Adds downloadUrl computed field to File types tagged with @storageFiles',
+        schema: {
+            hooks: {
+                GraphQLObjectType_fields(fields, build, context) {
+                    const { scope: { pgCodec, isPgClassType }, } = context;
+                    // Only process PG class types (table row types)
+                    if (!isPgClassType || !pgCodec || !pgCodec.attributes) {
+                        return fields;
+                    }
+                    // Check for @storageFiles smart tag — set by the storage module generator
+                    const tags = pgCodec.extensions?.tags;
+                    if (!tags?.storageFiles) {
+                        return fields;
+                    }
+                    log.debug(`Adding downloadUrl field to type: ${pgCodec.name} (has @storageFiles tag)`);
+                    const { graphql: { GraphQLString }, } = build;
+                    return build.extend(fields, {
+                        downloadUrl: context.fieldWithHooks({ fieldName: 'downloadUrl' }, {
+                            description: 'URL to download this file. For public files, returns the public URL. ' +
+                                'For private files, returns a time-limited presigned URL.',
+                            type: GraphQLString,
+                            async resolve(parent, _args, context) {
+                                const key = parent.key || parent.get?.('key');
+                                const isPublic = parent.is_public ?? parent.get?.('is_public');
+                                const filename = parent.filename || parent.get?.('filename');
+                                const status = parent.status || parent.get?.('status');
+                                if (!key)
+                                    return null;
+                                // Only provide download URLs for ready/processed files
+                                if (status !== 'ready' && status !== 'processed') {
+                                    return null;
+                                }
+                                if (isPublic && s3.publicUrlPrefix) {
+                                    // Public file: return direct URL
+                                    return `${s3.publicUrlPrefix}/${key}`;
+                                }
+                                // Resolve download URL expiry from storage module config (per-database)
+                                let downloadUrlExpirySeconds = 3600; // fallback default
+                                try {
+                                    const withPgClient = context.pgSettings
+                                        ? context.withPgClient
+                                        : null;
+                                    if (withPgClient) {
+                                        const config = await withPgClient(null, async (pgClient) => {
+                                            const dbResult = await pgClient.query(`SELECT jwt_private.current_database_id() AS id`);
+                                            const databaseId = dbResult.rows[0]?.id;
+                                            if (!databaseId)
+                                                return null;
+                                            return getStorageModuleConfig(pgClient, databaseId);
+                                        });
+                                        if (config) {
+                                            downloadUrlExpirySeconds = config.downloadUrlExpirySeconds;
+                                        }
+                                    }
+                                }
+                                catch {
+                                    // Fall back to default if config lookup fails
+                                }
+                                // Private file: generate presigned GET URL
+                                return generatePresignedGetUrl(s3, key, downloadUrlExpirySeconds, filename || undefined);
+                            },
+                        }),
+                    }, 'PresignedUrlDownloadPlugin adding downloadUrl field');
+                },
+            },
+        },
+    };
+}
+export default createDownloadUrlPlugin;

package/esm/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Presigned URL Plugin for PostGraphile v5
+ *
+ * Provides presigned URL upload capabilities for PostGraphile v5:
+ * - requestUploadUrl mutation (presigned PUT URL generation)
+ * - confirmUpload mutation (upload verification + status transition)
+ * - downloadUrl computed field (presigned GET URL / public URL)
+ *
+ * @example
+ * ```typescript
+ * import { PresignedUrlPreset } from 'graphile-presigned-url-plugin';
+ * import { S3Client } from '@aws-sdk/client-s3';
+ *
+ * const s3Client = new S3Client({ region: 'us-east-1' });
+ *
+ * const preset = {
+ *   extends: [
+ *     PresignedUrlPreset({
+ *       s3: {
+ *         client: s3Client,
+ *         bucket: 'my-uploads',
+ *         publicUrlPrefix: 'https://cdn.example.com',
+ *       },
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+export { PresignedUrlPlugin, createPresignedUrlPlugin } from './plugin';
+export { createDownloadUrlPlugin } from './download-url-field';
+export { PresignedUrlPreset } from './preset';
+export { getStorageModuleConfig, getBucketConfig, clearStorageModuleCache, clearBucketCache } from './storage-module-cache';
+export { generatePresignedPutUrl, generatePresignedGetUrl, headObject } from './s3-signer';
+export type { BucketConfig, StorageModuleConfig, RequestUploadUrlInput, RequestUploadUrlPayload, ConfirmUploadInput, ConfirmUploadPayload, S3Config, PresignedUrlPluginOptions, } from './types';

package/esm/index.js

@@ -0,0 +1,33 @@
+/**
+ * Presigned URL Plugin for PostGraphile v5
+ *
+ * Provides presigned URL upload capabilities for PostGraphile v5:
+ * - requestUploadUrl mutation (presigned PUT URL generation)
+ * - confirmUpload mutation (upload verification + status transition)
+ * - downloadUrl computed field (presigned GET URL / public URL)
+ *
+ * @example
+ * ```typescript
+ * import { PresignedUrlPreset } from 'graphile-presigned-url-plugin';
+ * import { S3Client } from '@aws-sdk/client-s3';
+ *
+ * const s3Client = new S3Client({ region: 'us-east-1' });
+ *
+ * const preset = {
+ *   extends: [
+ *     PresignedUrlPreset({
+ *       s3: {
+ *         client: s3Client,
+ *         bucket: 'my-uploads',
+ *         publicUrlPrefix: 'https://cdn.example.com',
+ *       },
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+export { PresignedUrlPlugin, createPresignedUrlPlugin } from './plugin';
+export { createDownloadUrlPlugin } from './download-url-field';
+export { PresignedUrlPreset } from './preset';
+export { getStorageModuleConfig, getBucketConfig, clearStorageModuleCache, clearBucketCache } from './storage-module-cache';
+export { generatePresignedPutUrl, generatePresignedGetUrl, headObject } from './s3-signer';

package/esm/plugin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Presigned URL Plugin for PostGraphile v5
+ *
+ * Adds presigned URL upload support to PostGraphile v5:
+ *
+ * 1. `requestUploadUrl` mutation — generates a presigned PUT URL for direct
+ *    client-to-S3 upload. Checks bucket access via RLS, deduplicates by
+ *    content hash, tracks the request in upload_requests.
+ *
+ * 2. `confirmUpload` mutation — confirms a file was uploaded to S3, verifies
+ *    the object exists with correct content-type, transitions file status
+ *    from 'pending' to 'ready'.
+ *
+ * 3. `downloadUrl` computed field on File types — generates presigned GET URLs
+ *    for private files, returns public URL prefix + key for public files.
+ *
+ * Uses the extendSchema + grafast plan pattern (same as PublicKeySignature).
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { PresignedUrlPluginOptions } from './types';
+export declare function createPresignedUrlPlugin(options: PresignedUrlPluginOptions): GraphileConfig.Plugin;
+export declare const PresignedUrlPlugin: typeof createPresignedUrlPlugin;
+export default PresignedUrlPlugin;