@pgpm/defaults 0.4.0 → 0.5.0

package/Makefile

@@ -1,5 +1,5 @@
 EXTENSION = launchql-defaults
-DATA = sql/launchql-defaults--0.4.6.sql
+DATA = sql/launchql-defaults--0.4.0.sql
 
 PG_CONFIG = pg_config
 PGXS := $(shell $(PG_CONFIG) --pgxs)

package/README.md

@@ -2,4 +2,337 @@
 
 Security defaults and baseline configurations.
 
-Provides default security settings, configurations, and baseline security policies for PostgreSQL applications.
+## Overview
+
+`@pgpm/defaults` establishes a secure baseline configuration for PostgreSQL databases by revoking default public access. This package implements the principle of least privilege by removing PostgreSQL's default permissive settings and requiring explicit permission grants.
+
+## Features
+
+- **Revoke Public Database Access**: Removes default PUBLIC access to databases
+- **Restrict Function Execution**: Prevents PUBLIC from executing functions by default
+- **Lock Down Public Schema**: Removes CREATE privilege on public schema from PUBLIC
+- **Secure by Default**: Forces explicit permission grants
+- **One-Time Setup**: Applies baseline security configuration
+
+## Installation
+
+If you have `pgpm` installed:
+
+```bash
+pgpm install @pgpm/defaults
+pgpm deploy
+```
+
+This is a quick way to get started. The sections below provide more detailed installation options.
+
+### Prerequisites
+
+```bash
+# Install pgpm globally
+npm install -g pgpm
+
+# Start PostgreSQL
+pgpm docker start
+
+# Set environment variables
+eval "$(pgpm env)"
+```
+
+### Deploy
+
+#### Option 1: Deploy by installing with pgpm
+
+```bash
+pgpm install @pgpm/defaults
+pgpm deploy
+```
+
+#### Option 2: Deploy from Package Directory
+
+```bash
+cd packages/security/defaults
+pgpm deploy --createdb
+```
+
+#### Option 3: Deploy from Workspace Root
+
+```bash
+# Install workspace dependencies
+pgpm install
+
+# Deploy with dependencies
+pgpm deploy mydb1 --yes --createdb
+```
+
+## What It Does
+
+This package executes three critical security operations:
+
+### 1. Revoke Database Access from PUBLIC
+
+```sql
+REVOKE ALL ON DATABASE current_database FROM PUBLIC;
+```
+
+Removes all default privileges that PUBLIC role has on the database, preventing unauthorized access.
+
+### 2. Revoke Function Execution from PUBLIC
+
+```sql
+ALTER DEFAULT PRIVILEGES REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC;
+```
+
+Prevents PUBLIC from executing any functions by default. Functions must be explicitly granted to roles.
+
+### 3. Revoke Schema Creation from PUBLIC
+
+```sql
+REVOKE CREATE ON SCHEMA public FROM PUBLIC;
+```
+
+Prevents PUBLIC from creating objects in the public schema, requiring explicit permissions.
+
+## Usage
+
+### Deploying Security Defaults
+
+This is typically one of the first packages you deploy to establish a secure baseline.
+
+#### From Package Directory
+
+```bash
+cd packages/security/defaults
+pgpm deploy --createdb
+```
+
+#### From Workspace Root
+
+```bash
+pgpm install
+pgpm deploy mydb1 --yes --createdb
+```
+
+### After Deployment
+
+After deploying this package, you must explicitly grant permissions:
+
+```sql
+-- Grant database connection to specific roles
+GRANT CONNECT ON DATABASE mydb TO authenticated;
+
+-- Grant schema usage
+GRANT USAGE ON SCHEMA public TO authenticated;
+
+-- Grant table access
+GRANT SELECT, INSERT, UPDATE, DELETE ON my_table TO authenticated;
+
+-- Grant function execution
+GRANT EXECUTE ON FUNCTION my_function() TO authenticated;
+```
+
+## Security Model
+
+### Before @pgpm/defaults
+
+PostgreSQL's default configuration is permissive:
+- PUBLIC can connect to databases
+- PUBLIC can execute functions
+- PUBLIC can create objects in public schema
+
+This is convenient for development but insecure for production.
+
+### After @pgpm/defaults
+
+All access must be explicitly granted:
+- Roles need CONNECT privilege to access database
+- Roles need USAGE privilege on schemas
+- Roles need specific privileges on tables/functions
+- No implicit permissions exist
+
+## Integration with Other Packages
+
+### With @pgpm/default-roles
+
+```bash
+# Deploy both packages from their directories
+cd packages/security/defaults && pgpm deploy --createdb
+cd packages/security/default-roles && pgpm deploy --createdb
+```
+
+Then grant permissions to roles:
+
+```sql
+-- Grant permissions to roles
+GRANT CONNECT ON DATABASE mydb TO anonymous, authenticated, administrator;
+GRANT USAGE ON SCHEMA public TO anonymous, authenticated, administrator;
+```
+
+### With Application Tables
+
+```sql
+-- Create table
+CREATE TABLE users (id uuid PRIMARY KEY, email text);
+
+-- Explicitly grant access (nothing is granted by default)
+GRANT SELECT ON users TO anonymous;
+GRANT SELECT, INSERT, UPDATE ON users TO authenticated;
+GRANT ALL ON users TO administrator;
+```
+
+## Best Practices
+
+1. **Deploy Early**: Apply this package before creating application objects
+2. **Explicit Grants**: Always explicitly grant required permissions
+3. **Least Privilege**: Grant only the minimum permissions needed
+4. **Document Grants**: Keep track of what permissions each role has
+5. **Test Thoroughly**: Verify that your application works with restricted permissions
+
+## Common Patterns
+
+### Public Read, Authenticated Write
+
+```sql
+-- Public data that anyone can read
+GRANT SELECT ON public_data TO anonymous;
+GRANT SELECT, INSERT, UPDATE, DELETE ON public_data TO authenticated;
+```
+
+### Private User Data
+
+```sql
+-- Enable RLS for user isolation
+ALTER TABLE user_data ENABLE ROW LEVEL SECURITY;
+
+-- Only authenticated users can access their own data
+GRANT SELECT, INSERT, UPDATE, DELETE ON user_data TO authenticated;
+
+CREATE POLICY user_data_policy ON user_data
+  FOR ALL TO authenticated
+  USING (user_id = jwt_public.current_user_id());
+```
+
+### Admin-Only Tables
+
+```sql
+-- Only administrators can access
+GRANT ALL ON admin_config TO administrator;
+```
+
+## Troubleshooting
+
+### "Permission Denied" Errors
+
+If you see permission denied errors after deploying this package:
+
+1. Check which role is being used: `SELECT current_role;`
+2. Verify role has CONNECT: `SELECT has_database_privilege('rolename', 'mydb', 'CONNECT');`
+3. Verify schema USAGE: `SELECT has_schema_privilege('rolename', 'public', 'USAGE');`
+4. Grant missing permissions explicitly
+
+### Functions Not Executable
+
+If functions can't be executed:
+
+```sql
+-- Grant execute on specific function
+GRANT EXECUTE ON FUNCTION my_function() TO authenticated;
+
+-- Or grant execute on all functions in schema
+GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA public TO authenticated;
+```
+
+## Dependencies
+
+- `@pgpm/verify`: Verification utilities
+
+## Testing
+
+```bash
+pnpm test
+```
+
+## Development
+
+See the [Development](#development) section below for information on working with this package.
+
+---
+
+## Development
+
+### **Before You Begin**
+
+```bash
+# 1. Install pgpm
+npm install -g pgpm
+
+# 2. Start Postgres (Docker or local)
+pgpm docker start
+
+# 3. Load PG* environment variables (PGHOST, PGUSER, ...)
+eval "$(pgpm env)"
+```
+
+---
+
+### **Starting a New Project**
+
+```bash
+# 1. Create a workspace
+pgpm init --workspace
+cd my-app
+
+# 2. Create your first module
+pgpm init
+
+# 3. Add a migration
+pgpm add some_change
+
+# 4. Deploy (auto-creates database)
+pgpm deploy --createdb
+```
+
+---
+
+### **Working With an Existing Project**
+
+```bash
+# 1. Clone and enter the project
+git clone <repo> && cd <project>
+
+# 2. Install dependencies
+pnpm install
+
+# 3. Deploy locally
+pgpm deploy --createdb
+```
+
+---
+
+### **Testing a Module Inside a Workspace**
+
+```bash
+# 1. Install workspace deps
+pnpm install
+
+# 2. Enter the module directory
+cd packages/<some-module>
+
+# 3. Run tests in watch mode
+pnpm test:watch
+```
+
+## Related Tooling
+
+* [pgpm](https://github.com/launchql/launchql/tree/main/packages/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+* [pgsql-test](https://github.com/launchql/launchql/tree/main/packages/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [supabase-test](https://github.com/launchql/launchql/tree/main/packages/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/launchql/launchql/tree/main/packages/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pgsql-parser](https://github.com/launchql/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://github.com/launchql/libpg-query-node): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://github.com/launchql/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+
+## 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/launchql-defaults.control

@@ -1,6 +1,6 @@
 # launchql-defaults extension
 comment = 'launchql-defaults extension'
-default_version = '0.4.6'
+default_version = '0.4.0'
 module_pathname = '$libdir/launchql-defaults'
 requires = 'plpgsql,launchql-verify'
 relocatable = false

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@pgpm/defaults",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Security defaults and baseline configurations",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "bundle": "lql package",
+    "bundle": "pgpm package",
     "test": "jest",
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@pgpm/verify": "0.4.0"
+    "@pgpm/verify": "0.5.0"
   },
   "devDependencies": {
-    "@launchql/cli": "^4.9.0"
+    "pgpm": "^0.2.0"
   },
   "repository": {
     "type": "git",
@@ -24,5 +24,5 @@
   "bugs": {
     "url": "https://github.com/launchql/extensions/issues"
   },
-  "gitHead": "cc9f52a335caa6e21ee7751b04b77c84ce6cb809"
+  "gitHead": "d8eedbb24ad22a106634bc3b919bfb8d41976c16"
 }