# pg-knoe-auth

PG18 OAUTHBEARER JWT validator for knoe-system.

Implements the `OAuthValidatorCallbacks` interface introduced in PostgreSQL 18
to validate Bearer JWTs issued by knoe-auth (`https://api.knoe.dev/auth`).

## What it does

- Fetches JWKS from `<issuer>/.well-known/jwks.json` via libcurl
- Verifies RS256 JWT signatures using OpenSSL
- Validates `iss`, `aud` (exact match, string or array form), `exp` claims
- Maps `preferred_username` (or a configurable claim) to a Postgres role via
  `pg_ident.conf` `oauthusermap`
- Caches JWKS keys process-locally (10 min TTL, 24 h stale fallback)

## GUCs

| GUC | Default | Description |
|---|---|---|
| `pg_knoe_auth.role_claim` | `preferred_username` | JWT claim used as authn_id |
| `pg_knoe_auth.usermap_required` | `true` | Require pg_ident oauthusermap entry |
| `pg_knoe_auth.audience` | _(unset)_ | Expected `aud` claim value |
| `pg_knoe_auth.issuer` | _(unset)_ | Expected `iss` (overrides pg_hba `oauth_issuer`) |

## Build

```bash
# Inside the builder image (or with PG18 dev headers installed):
cd src
make USE_PGXS=1
make USE_PGXS=1 install
```

## Docker artifact build

```bash
docker build -t pg-knoe-auth:local .
```

The final image stage (`artifact`) contains only:
- `/output/pg_knoe_auth.so`
- `/output/pg_knoe_auth.so.sha256`

The `knoe-db` Dockerfile imports it via:
```dockerfile
COPY --from=us-west3-docker.pkg.dev/.../pg-knoe-auth:${PG_KNOE_AUTH_TAG} \
     /output/pg_knoe_auth.so /usr/lib/postgresql/18/lib/pg_knoe_auth.so
```

## Unit tests

```bash
cd test/unit && make check
```

No PG cluster required — tests link only against OpenSSL.

## Integration tests

```bash
cd test/integration && make installcheck
```

Requires a running PG18 instance with `pg_knoe_auth` loaded and a mock JWKS
server. See `test/integration/README.md` for setup.

## Security hardening

See `docs/plans/junie/pg_knoe_auth-rename-harden-modularize.md` §2.2 for the
full security review and the five fixes (H1–H3, M1–M2) applied in v0.1.0.

## Version

See `version` file. Tagged as `<version>-<git-sha>` in the artifact registry.