Update, August 2025: This repo (PADS) is no longer needed. It's business logic was rolled over into PEAS.

---

🐾 PADS
PATH Auth Data Server

Table of Contents

• 1. Introduction
• 2. Gateway Endpoints
• 3. Data Sources
  • 3.1. YAML
    • 3.1.1. Example YAML File
    • 3.1.2. YAML Schema
  • 3.2. Postgres
    • 3.2.1. Grove Portal DB Driver

1. Introduction

PADS (PATH Auth Data Server) is a gRPC server that provides Gateway Endpoint data from a data source to PEAS (PATH External Auth Server) in order to enable authorization for PATH.

The nature of the data source is configurable, for example it could be a YAML file or a Postgres database.

2. Gateway Endpoints

The PEAS repo contains the proto package which contains the gateway_endpoint.proto file, which contains the definitions for the GatewayEndpoints that PADS must provides to PEAS.

A single GatewayEndpoint represents a single authorized endpoint of the PATH Gateway service, which may be authorized for use by any number of users.

// Simplified representation of the GatewayEndpoint proto message that
// PADS must provide to the `Go External Authorization Server`.
type GatewayEndpoint struct {
    EndpointId string
    // AuthType will be exactly one of the following structs:
    AuthType {
        // 1. No Authorization Required
        NoAuth struct{}
        // 2. Static API Key
        StaticApiKey struct {
          ApiKey string
        }
    }
    Metadata struct {
        Name string
        AccountId string
        UserId string
        PlanType string
        Email string
        Environment string
    }
}

3. Data Sources

The grpc package contains the AuthDataSource interface, which abstracts the data source that provides GatewayEndpoints to PEAS.

type GatewayEndpointsClient interface {
	// FetchAuthDataSync requests the initial set of GatewayEndpoints from the remote gRPC server.
	FetchAuthDataSync(ctx context.Context, in *AuthDataRequest, opts ...grpc.CallOption) (*AuthDataResponse, error)
	// StreamAuthDataUpdates listens for updates from the remote gRPC server and streams them to the client.
	StreamAuthDataUpdates(ctx context.Context, in *AuthDataUpdatesRequest, opts ...grpc.CallOption) (GatewayEndpoints_StreamAuthDataUpdatesClient, error)
}

• FetchAuthDataSync() returns the full set of Gateway Endpoints.
  • This is called when PADS starts to populate its Gateway Endpoint Data Store.
• StreamAuthDataUpdates() returns a channel that receives auth data updates to the Gateway Endpoints.
  • Updates are streamed as changes are made to the data source.

3.1. YAML

If the YAML_FILEPATH environment variable is set, PADS will load the data from a YAML file at the specified path.

Hot reloading is supported, so changes to the YAML file will be reflected in the Go External Authorization Server without the need to restart PADS.

3.1.1. Example YAML File

endpoints:
  # 1. Example of a gateway endpoint using API Key Authorization
  # This endpoint has no rate limits defined (the rate_limiting field is omitted entirely in this case).
  endpoint_1_static_key: # The unique identifier for a gateway endpoint.
    auth: # The auth field is required for all endpoints that use authorization.
      # The sub-field 'api_key' is required for API Key Authorization.
      # If auth is not set, the endpoint will be treated as using no authorization.
      api_key: "api_key_1" # For API Key Authorization, the API key string is required.

    metadata: # Metadata fields may be any key-value pairs and are optional.
      plan_type: "PLAN_UNLIMITED" # Example of a key-value pair (in this case, a pricing plan).
      account_id: "account_1" # Example of a key-value pair (in this case, an account ID).
      email: "user1@example.com" # Example of a key-value pair (in this case, an owner email).

  # 2. Example of a gateway endpoint with no authorization (the auth field is omitted entirely in this case).
  endpoint_2_no_auth:
    metadata:
      plan_type: "PLAN_FREE"
      account_id: "account_2"
      email: "user2@example.com"

Full Example Gateway Endpoints YAML File

3.1.2. YAML Schema

The YAML Schema defines the expected structure of the YAML file.

3.2. Postgres

If the POSTGRES_CONNECTION_STRING environment variable is set, PADS will connect to the specified Postgres database.

3.2.1. Grove Portal DB Driver

A highly opinionated Postgres driver that is compatible with the Grove Portal DB is provided in this repository for use in the Grove Portal's authentication implementation.

For more details, see the Grove Portal DB Driver README.md documentation.