Hessra AuthZ Extension for PostgreSQL

A PostgreSQL extension for authorization and token verification using Biscuit tokens, built with pgrx.

Overview

The hessra_authz extension provides a lightweight, secure way to manage and verify authorization tokens directly within PostgreSQL. It supports:

• Public key management for token verification
• Service chain verification for multi-service architectures
• Integration with Biscuit tokens (attenuation-based authorization tokens)
• SQL-friendly API for authorization checks

This extension is ideal for applications that use PostgreSQL and need to perform token-based authorization checks directly in database queries.

Prerequisites

• PostgreSQL 12 or newer
• Rust toolchain (1.65+)
• pgrx (PostgreSQL Rust Extension framework)

Mac Setup

On macOS, set the following environment variables:

export MACOSX_DEPLOYMENT_TARGET=15.4
export PKG_CONFIG_PATH=/opt/homebrew/opt/icu4c/lib/pkgconfig

Consider adding these to your ~/.zshrc or ~/.bashrc for persistent setup.

Installation

1. Install pgrx if you haven't already:

cargo install cargo-pgrx
cargo pgrx init

2. Build and install the extension:

cargo pgrx install --package hessra_authz

3. Enable the extension in your PostgreSQL database:

CREATE EXTENSION hessra_authz;

Usage

Managing Public Keys

-- Add a public key (last parameter sets it as the default key)
SELECT add_public_key('my_key', '-----BEGIN PUBLIC KEY-----\n...', true);

-- Retrieve a key
SELECT get_public_key('my_key');

-- Get the default key
SELECT get_public_key(NULL);

-- Update a key
SELECT update_public_key('my_key', '-----BEGIN PUBLIC KEY-----\n...', false);

-- Delete a key
SELECT delete_public_key('my_key');

Managing Service Chains

-- Add a service chain
SELECT add_service_chain('payment_flow', '[
  {
    "component": "auth_service",
    "public_key": "ed25519/0123456789abcdef0123456789abcdef"
  },
  {
    "component": "payment_service",
    "public_key": "ed25519/fedcba9876543210fedcba9876543210"
  }
]');

-- Retrieve a service chain
SELECT get_service_chain('payment_flow');

-- Update a service chain
SELECT update_service_chain('payment_flow', '[...]');

-- Delete a service chain
SELECT delete_service_chain('payment_flow');

Verifying Tokens

-- Verify a token directly
SELECT verify_token(
  'biscuit_token_string',
  '-----BEGIN PUBLIC KEY-----\n...',
  'user_id',
  'resource_path'
);

-- Verify a token using a stored key
SELECT verify_token_with_stored_key(
  'biscuit_token_string',
  'my_key',  -- Optional, uses default key if NULL
  'user_id',
  'resource_path'
);

-- Verify a token in a service chain
SELECT verify_service_chain_token_with_stored_config(
  'biscuit_token_string',
  'my_key',  -- Optional, uses default key if NULL
  'user_id',
  'resource_path',
  'payment_flow',
  'payment_service'  -- Optional, verifies for specific component
);

Integration Example

-- Create a policy that uses token verification
CREATE POLICY user_data_policy ON user_data
  USING (
    verify_token_with_stored_key(
      current_setting('app.auth_token', true),
      NULL,  -- Use default key
      user_id::text,
      'user_data/' || id::text
    ) IS NULL  -- Successful verification returns NULL
  );

-- Enable row-level security
ALTER TABLE user_data ENABLE ROW LEVEL SECURITY;

Development

Running Tests

cargo pgrx test --package hessra_authz

Running in Development Mode

cargo pgrx run --package hessra_authz

About Biscuit Tokens

Biscuit is an authorization token format built for microservices and distributed systems:

• Attenuation-based: Tokens can be restricted but not extended
• Offline verification: No need to call a central service
• Cryptographically secure: Based on public-key cryptography
• Capability-based: Tokens contain the necessary authorization information

This extension integrates with the Biscuit token format to enable secure, decentralized authorization directly within PostgreSQL.

License

This project is licensed under the MIT License.