@pgpm/totp 0.4.0 → 0.5.0

package/Makefile

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

package/README.md

@@ -2,9 +2,73 @@
 
 TOTP implementation in pure PostgreSQL plpgsql
 
-This extension provides the HMAC Time-Based One-Time Password Algorithm (TOTP) as specfied in RFC 4226 as pure plpgsql functions.
+This extension provides the HMAC Time-Based One-Time Password Algorithm (TOTP) as specified in RFC 4226 as pure plpgsql functions.
 
-# Usage
+## Overview
+
+`@pgpm/totp` implements Time-based One-Time Password (TOTP) authentication entirely in PostgreSQL using plpgsql. This package enables two-factor authentication (2FA) directly in your database without external dependencies. It supports TOTP code generation, verification, and QR code URL generation for authenticator apps like Google Authenticator, Authy, and 1Password.
+
+## Features
+
+- **Pure plpgsql Implementation**: No external dependencies or libraries required
+- **TOTP Code Generation**: Generate 6-digit time-based codes
+- **Code Verification**: Verify user-provided TOTP codes
+- **QR Code URLs**: Generate otpauth:// URLs for authenticator apps
+- **Configurable Parameters**: Customize interval and code length
+- **RFC 4226 Compliant**: Follows the HOTP standard
+- **Base32 Integration**: Uses `@pgpm/base32` for secret encoding
+
+## Installation
+
+If you have `pgpm` installed:
+
+```bash
+pgpm install @pgpm/totp
+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/totp
+pgpm deploy
+```
+
+#### Option 2: Deploy from Package Directory
+
+```bash
+cd packages/security/totp
+pgpm deploy --createdb
+```
+
+#### Option 3: Deploy from Workspace Root
+
+```bash
+# Install workspace dependencies
+pgpm install
+
+# Deploy with dependencies
+pgpm deploy mydb1 --yes --createdb
+```
+
+## Usage
 
 ## totp.generate
 
@@ -50,11 +114,97 @@ Will produce a URL-encoded string
 otpauth://totp/customer@email.com?secret=mysecret&period=30&issuer=Acme%20Inc
 ```
 
-# caveats
+## Integration Examples
+
+### User Registration with 2FA
+
+```sql
+-- Store TOTP secret for user
+CREATE TABLE user_totp (
+  user_id uuid PRIMARY KEY,
+  totp_secret text NOT NULL,
+  enabled boolean DEFAULT false,
+  created_at timestamptz DEFAULT now()
+);
+
+-- Generate and store secret for new user
+INSERT INTO user_totp (user_id, totp_secret)
+VALUES ('user-uuid', 'mysecret');
+
+-- Get QR code URL for user to scan
+SELECT totp.url(
+  'user@example.com',
+  totp_secret,
+  30,
+  'My App'
+) FROM user_totp WHERE user_id = 'user-uuid';
+```
+
+### Login Verification
+
+```sql
+-- Verify TOTP code during login
+CREATE FUNCTION verify_user_totp(
+  p_user_id uuid,
+  p_code text
+) RETURNS boolean AS $$
+DECLARE
+  v_secret text;
+BEGIN
+  SELECT totp_secret INTO v_secret
+  FROM user_totp
+  WHERE user_id = p_user_id AND enabled = true;
+  
+  IF v_secret IS NULL THEN
+    RETURN false;
+  END IF;
+  
+  RETURN totp.verify(v_secret, p_code, 30, 6);
+END;
+$$ LANGUAGE plpgsql;
+```
+
+### Enable 2FA Flow
+
+```sql
+-- 1. Generate secret and QR code URL
+SELECT totp.url('user@example.com', 'newsecret', 30, 'My App');
+
+-- 2. User scans QR code with authenticator app
+
+-- 3. User provides first code to verify setup
+SELECT totp.verify('newsecret', '123456', 30, 6);
+
+-- 4. If verified, enable 2FA
+UPDATE user_totp
+SET enabled = true
+WHERE user_id = 'user-uuid';
+```
+
+## Use Cases
+
+- **Two-Factor Authentication (2FA)**: Add an extra layer of security to user logins
+- **API Access Tokens**: Generate time-based tokens for API authentication
+- **Transaction Verification**: Require TOTP codes for sensitive operations
+- **Admin Access**: Require 2FA for administrative functions
+- **Password Reset**: Use TOTP as part of password reset flow
+
+## Dependencies
+
+- `@pgpm/base32`: Base32 encoding for TOTP secrets
+- `@pgpm/verify`: Verification utilities
+
+## Testing
+
+```bash
+pnpm test
+```
+
+## Caveats
 
 Currently only supports `sha1`, pull requests welcome!
 
-# debugging
+## Debugging
 
 use the verbose option to show keys
 
@@ -75,8 +225,7 @@ using time for testing
 
 oathtool --totp -v -d 6 -s 30s -b vmlhl2knm27eftq7 --now "2020-02-05 22:11:40 UTC"
 
-
-# credits
+## Credits
 
 Thanks to 
 
@@ -90,7 +239,9 @@ And major improvements from
 
 https://gist.github.com/bwbroersma/676d0de32263ed554584ab132434ebd9
 
-# Development
+---
+
+## Development
 
 ## start the postgres db process
 
@@ -131,30 +282,110 @@ yarn test:watch
 Create a new folder in `packages/`
 
 ```sh
-lql init
+pgpm init
 ```
 
 Then, run a generator:
 
 ```sh
-lql generate
+pgpm generate
 ```
 
 You can also add arguments if you already know what you want to do:
 
 ```sh
-lql generate schema --schema myschema
-lql generate table --schema myschema --table mytable
+pgpm generate schema --schema myschema
+pgpm generate table --schema myschema --table mytable
 ```
 
 ## deploy code as extensions
 
-`cd` into `packages/<module>`, and run `lql package`. This will make an sql file in `packages/<module>/sql/` used for `CREATE EXTENSION` calls to install your sqitch module as an extension.
+`cd` into `packages/<module>`, and run `pgpm package`. This will make an sql file in `packages/<module>/sql/` used for `CREATE EXTENSION` calls to install your sqitch module as an extension.
 
 ## recursive deploy
 
 You can also deploy all modules utilizing versioning as sqtich modules. Remove `--createdb` if you already created your db:
 
 ```sh
-lql deploy awesome-db --yes --recursive --createdb
+pgpm deploy mydb1 --yes --createdb
+```
+
+---
+
+### **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-totp.control

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

package/package.json

@@ -1,21 +1,21 @@
 {
   "name": "@pgpm/totp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Time-based One-Time Password (TOTP) authentication",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "bundle": "lql package",
+    "bundle": "pgpm package",
     "test": "jest",
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@pgpm/base32": "0.4.0",
-    "@pgpm/verify": "0.4.0"
+    "@pgpm/base32": "0.5.0",
+    "@pgpm/verify": "0.5.0"
   },
   "devDependencies": {
-    "@launchql/cli": "^4.9.0"
+    "pgpm": "^0.2.0"
   },
   "repository": {
     "type": "git",
@@ -25,5 +25,5 @@
   "bugs": {
     "url": "https://github.com/launchql/extensions/issues"
   },
-  "gitHead": "cc9f52a335caa6e21ee7751b04b77c84ce6cb809"
+  "gitHead": "d8eedbb24ad22a106634bc3b919bfb8d41976c16"
 }