@mountainpass/addressr 2.1.2 → 2.1.4

package/README.md

@@ -1,18 +1,38 @@
 # Addressr
 
-![Addressr](https://addressr.io/icons/icon-144x144.png ‘Addressr’)
+![Addressr](https://addressr.io/icons/icon-144x144.png 'Addressr')
 
-[Australian Address Validation, Search and Autocomplete](https://addressr.io) - [addressr.io](https://addressr.io)
+**The only open-source, free self-hosted Australian address validation API.**
 
-[![GitHub license](https://img.shields.io/github/license/mountain-pass/addressr)](https://github.com/mountain-pass/addressr/blob/master/LICENSE) [![npm](https://img.shields.io/npm/v/@mountainpass/addressr)](https://www.npmjs.com/package/@mountainpass/addressr) [![npm downloads](https://img.shields.io/npm/dm/@mountainpass/addressr)](https://www.npmjs.com/package/@mountainpass/addressr)
+[Australian Address Validation, Search and Autocomplete](https://addressr.io) — [addressr.io](https://addressr.io)
 
-[![Maintainability](https://api.codeclimate.com/v1/badges/e5117809cacb7e32eb5c/maintainability)](https://codeclimate.com/github/mountain-pass/addressr/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/e5117809cacb7e32eb5c/test_coverage)](https://codeclimate.com/github/mountain-pass/addressr/test_coverage) ![Uptime Robot ratio (30 days)](https://img.shields.io/uptimerobot/ratio/m788652244-3e35661f9886333310f4dc2f)
+[![GitHub license](https://img.shields.io/github/license/mountain-pass/addressr)](https://github.com/mountain-pass/addressr/blob/master/LICENSE) [![npm](https://img.shields.io/npm/v/@mountainpass/addressr)](https://www.npmjs.com/package/@mountainpass/addressr) [![npm downloads](https://img.shields.io/npm/dm/@mountainpass/addressr)](https://www.npmjs.com/package/@mountainpass/addressr)
 
 [![GitHub issues](https://img.shields.io/github/issues/mountain-pass/addressr)](https://github.com/mountain-pass/addressr/issues) [![GitHub pull requests](https://img.shields.io/github/issues-pr/mountain-pass/addressr)](https://github.com/mountain-pass/addressr/pulls)
 
 # About
 
-Australian Address Validation, Search and Autocomplete powered by the Geocoded National Address File (G-NAF), Australia’s **authoritative** address database with 15+ million addresses.
+Australian Address Validation, Search and Autocomplete powered by the Geocoded National Address File (G-NAF), Australia's **authoritative** address database with 15+ million addresses.
+
+- **Validated addresses** from the official G-NAF source
+- **Real-time autocomplete** with fuzzy matching
+- **Locality, postcode, and state search** for area pickers
+- **Geocoding** to latitude/longitude (optional)
+- **Self-hosted or SaaS** — your choice, your data
+- **Open source** — audit the code, customize as needed
+
+# Why Addressr
+
+|                                    | Addressr | [Addressify](https://addressify.com.au/) | [AddressFinder](https://addressfinder.com.au/) | [Geoscape](https://geoscape.com.au/) | Google Maps |
+| ---------------------------------- | -------- | ---------------------------------------- | ---------------------------------------------- | ------------------------------------ | ----------- |
+| Self-hosted                        | ✅       | ❌                                       | ❌                                             | ❌                                   | ❌          |
+| Open source                        | ✅       | ❌                                       | ❌                                             | ❌                                   | ❌          |
+| Free tier (unlimited, self-hosted) | ✅       | ❌                                       | ❌                                             | ❌                                   | ❌          |
+| G-NAF data source                  | ✅       | ✅                                       | ✅                                             | ✅ (creator)                         | ❌          |
+| Data sovereignty                   | ✅       | ❌                                       | ❌                                             | ❌                                   | ❌          |
+| MCP integration for AI assistants  | ✅       | ❌                                       | ❌                                             | ❌                                   | ❌          |
+
+**Stop paying Google Maps for Australian addresses.** Stop locking your data into third-party SaaS. Addressr gives you unlimited address validation on your own infrastructure, or a cheap hosted API if you prefer.
 
 # Quick Start
 
@@ -85,15 +105,15 @@ Run Addressr on your own infrastructure for full control over your data.
    export ADDRESSR_INDEX_BACKOFF_MAX=10000
    ```
 
-   1. Optional - enable geocodes by setting the following env vars for the data loader. In the third window run:
-      **NOTE:** with geocodes enabled, indexing takes much longer and needs much more memory. Only use turn them on if you need them. You can always add them later.
+   1. Optional — enable geocodes by setting the following env vars for the data loader. In the third window run:
+      **NOTE:** with geocodes enabled, indexing takes much longer and needs much more memory. Only turn them on if you need them. You can always add them later.
 
    ```
    export ADDRESSR_ENABLE_GEO=1
    export NODE_OPTIONS=--max_old_space_size=8196
    ```
 
-   2. Optional - limit the addresses to a single state by setting the `COVERED_STATES` env var for the data loader.
+   2. Optional — limit the addresses to a single state by setting the `COVERED_STATES` env var for the data loader.
       This dramatically speeds up indexing. For example, in the third window run:
 
    ```
@@ -117,7 +137,8 @@ Run Addressr on your own infrastructure for full control over your data.
    addressr-loader
    ```
 
-6. OK, so we stretched the truth a bit with the "Quick Start" heading. The truth is that it takes quite a while to download, store and index the 13+ million addresses from [data.gov.au](http://data.gov.au/). So make a coffee, or tea, or find something else to do and come back in about an hour when it's done.
+6. OK, so we stretched the truth a bit with the "Quick Start" heading. The truth is that it takes quite a while to download, store and index the 15+ million addresses from [data.gov.au](http://data.gov.au/). So make a coffee, or tea, or find something else to do and come back in about an hour when it's done.
+
 7. Search for an address using the command line
 
    ```
@@ -125,7 +146,24 @@ Run Addressr on your own infrastructure for full control over your data.
    ```
 
 8. An updated G-NAF is released every 3 months. Put `addressr-loader` in a cron job or similar to keep addressr regularly updated
-9. Wire you address form up to the address-server api.
+9. Wire your address form up to the address-server api.
+
+# API Endpoints
+
+Addressr exposes a HATEOAS REST API. Start at the root (`/`) and follow links to discover endpoints. A supplementary OpenAPI 3.x spec is available at `/api-docs`.
+
+| Endpoint                     | Purpose                                                            | Example                           |
+| ---------------------------- | ------------------------------------------------------------------ | --------------------------------- |
+| `GET /addresses?q=`          | Search and autocomplete addresses                                  | `/addresses?q=1+george+st+sydney` |
+| `GET /addresses/{pid}`       | Get full address details (with links to locality, postcode, state) | `/addresses/GAOT_717882967`       |
+| `GET /localities?q=`         | Search suburbs/localities by name                                  | `/localities?q=lilydale`          |
+| `GET /localities/{pid}`      | Get locality details (with links to postcode, state)               | `/localities/loc9984d8beb142`     |
+| `GET /postcodes?q=`          | Search postcodes (q optional)                                      | `/postcodes?q=3140`               |
+| `GET /postcodes/{postcode}`  | Get postcode with associated localities                            | `/postcodes/6798`                 |
+| `GET /states?q=`             | Search states/territories (q optional)                             | `/states?q=New`                   |
+| `GET /states/{abbreviation}` | Get state details                                                  | `/states/NSW`                     |
+| `GET /api-docs`              | OpenAPI 3.x specification                                          | `/api-docs`                       |
+| `GET /health`                | Health check                                                       | `/health`                         |
 
 ## How it Works
 
@@ -148,6 +186,30 @@ Run Addressr on your own infrastructure for full control over your data.
 | ADDRESSR_ACCESS_CONTROL_EXPOSE_HEADERS | _non-blank_ | An `Access-Control-Expose-Headers` response header is returned with the value in the environment variable |         |
 | ADDRESSR_ACCESS_CONTROL_ALLOW_HEADERS  | _blank_     | An `Access-Control-Allow-Headers` response header is **not** returned                                     | ✅      |
 | ADDRESSR_ACCESS_CONTROL_ALLOW_HEADERS  | _non-blank_ | An `Access-Control-Allow-Headers` response header is returned with the value in the environment variable  |         |
+| ADDRESSR_PROXY_AUTH_HEADER             | _blank_     | No gateway auth header enforcement (self-hosted default)                                                  | ✅      |
+| ADDRESSR_PROXY_AUTH_HEADER             | _non-blank_ | Name of the header the origin requires — set alongside `ADDRESSR_PROXY_AUTH_VALUE`                        |         |
+| ADDRESSR_PROXY_AUTH_VALUE              | _blank_     | No gateway auth header enforcement (self-hosted default)                                                  | ✅      |
+| ADDRESSR_PROXY_AUTH_VALUE              | _non-blank_ | Expected value the header must carry — set alongside `ADDRESSR_PROXY_AUTH_HEADER`                         |         |
+
+### Gateway auth header (optional)
+
+By default Addressr does not enforce any proxy authentication — self-hosted npm and Docker deployments work with zero configuration.
+
+If you front Addressr with an API gateway (RapidAPI, Kong, Tyk, Apigee, AWS API Gateway, nginx, Caddy, or your own Cloudflare Worker) and want the origin to reject traffic that bypasses your gateway, set both environment variables to the header name your gateway injects and the shared secret it forwards:
+
+| Variable                     | Example                   | Notes                                       |
+| ---------------------------- | ------------------------- | ------------------------------------------- |
+| `ADDRESSR_PROXY_AUTH_HEADER` | `X-RapidAPI-Proxy-Secret` | Header name your gateway forwards           |
+| `ADDRESSR_PROXY_AUTH_VALUE`  | `<your-gateway-secret>`   | Expected value; keep out of version control |
+
+Behaviour:
+
+- Both unset → no enforcement (default).
+- Both set → requests without a matching header receive `401 Authentication required`.
+- Exactly one set → the process exits at startup with a clear error (fails loud to prevent silent bypass).
+- `/health` and `/api-docs` remain reachable without the header so uptime monitors and gateway OpenAPI imports keep working.
+
+See [ADR 024](docs/decisions/024-origin-gateway-auth-header-enforcement.proposed.md) for the decision record.
 
 NOTE: When adjusting PAGE_SIZE, you should take into account how quickly you want the initial results returned to the user. In many use cases, you want this to be as fast as possible. If you need show more results to the user, you are often better off leaving it a 8 and using the paging links to get more results while you are displaying the first 8.
 

package/lib/src/proxy-auth.js

@@ -0,0 +1,53 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.proxyAuthMiddleware = proxyAuthMiddleware;
+exports.validateProxyAuthConfig = validateProxyAuthConfig;
+var _debug = _interopRequireDefault(require("debug"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/* eslint-disable @eslint-community/eslint-comments/disable-enable-pair */
+/* eslint-disable security/detect-object-injection -- env var names are compile-time constants, not user input */
+
+const error = (0, _debug.default)('error');
+error.log = console.error.bind(console);
+const HEADER_VAR = 'ADDRESSR_PROXY_AUTH_HEADER';
+const VALUE_VAR = 'ADDRESSR_PROXY_AUTH_VALUE';
+
+// Closed list per ADR 024: /health for monitoring, /api-docs for gateway
+// OpenAPI imports (ADR 023). Exact-match, not prefix.
+const ALLOWLIST = new Set(['/health', '/api-docs']);
+function isNonEmpty(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+function validateProxyAuthConfig(environment = process.env) {
+  const headerSet = isNonEmpty(environment[HEADER_VAR]);
+  const valueSet = isNonEmpty(environment[VALUE_VAR]);
+  if (headerSet && !valueSet) {
+    throw new Error(`Proxy auth misconfigured: ${HEADER_VAR} is set but ${VALUE_VAR} is missing. Set both to enforce a gateway auth header, or unset both to disable enforcement.`);
+  }
+  if (valueSet && !headerSet) {
+    throw new Error(`Proxy auth misconfigured: ${VALUE_VAR} is set but ${HEADER_VAR} is missing. Set both to enforce a gateway auth header, or unset both to disable enforcement.`);
+  }
+}
+function proxyAuthMiddleware() {
+  return function proxyAuth(request, response, next) {
+    const headerName = process.env[HEADER_VAR];
+    const expected = process.env[VALUE_VAR];
+    if (!isNonEmpty(headerName) || !isNonEmpty(expected)) {
+      return next();
+    }
+    if (ALLOWLIST.has(request.path)) {
+      return next();
+    }
+    const presented = request.get ? request.get(headerName) : undefined;
+    if (presented === expected) {
+      return next();
+    }
+    error('proxy-auth rejected %s', request.path);
+    return response.status(401).json({
+      message: 'Authentication required'
+    });
+  };
+}

package/lib/src/waycharter-server.js

@@ -12,12 +12,645 @@ var _waycharter = require("@mountainpass/waycharter");
 var _addressService = require("../service/address-service");
 var _version = require("../version");
 var _nodeCrypto = _interopRequireDefault(require("node:crypto"));
+var _proxyAuth = require("./proxy-auth");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 //import connect from 'connect';
 
 var app = (0, _express.default)();
 const ONE_DAY = 60 * 60 * 24;
 const ONE_WEEK = ONE_DAY * 7;
+function buildOpenApiSpec(apiVersion) {
+  const schemas = {
+    AddressSearchResult: {
+      type: 'object',
+      properties: {
+        sla: {
+          type: 'string',
+          description: 'Single line address',
+          example: 'UNIT 1, 19 MURRAY RD, CHRISTMAS ISLAND OT 6798'
+        },
+        ssla: {
+          type: 'string',
+          description: 'Short single line address (for addresses with flats)',
+          example: '1/19 MURRAY RD, CHRISTMAS ISLAND OT 6798'
+        },
+        highlight: {
+          type: 'object',
+          description: 'Search term highlights in the address',
+          properties: {
+            sla: {
+              type: 'string'
+            },
+            ssla: {
+              type: 'string'
+            }
+          }
+        },
+        score: {
+          type: 'number',
+          description: 'Search relevance score',
+          example: 5.43
+        },
+        pid: {
+          type: 'string',
+          description: 'Persistent identifier for the address',
+          example: 'GAOT_717882967'
+        }
+      }
+    },
+    Address: {
+      type: 'object',
+      properties: {
+        sla: {
+          type: 'string',
+          example: 'UNIT 1, 19 MURRAY RD, CHRISTMAS ISLAND OT 6798'
+        },
+        structured: {
+          type: 'object',
+          properties: {
+            confidence: {
+              type: 'integer',
+              example: 2
+            },
+            flat: {
+              type: 'object',
+              properties: {
+                number: {
+                  type: 'integer',
+                  example: 1
+                },
+                type: {
+                  type: 'object',
+                  properties: {
+                    code: {
+                      type: 'string',
+                      example: 'UNIT'
+                    },
+                    name: {
+                      type: 'string',
+                      example: 'UNIT'
+                    }
+                  }
+                }
+              }
+            },
+            number: {
+              type: 'object',
+              properties: {
+                number: {
+                  type: 'integer',
+                  example: 19
+                }
+              }
+            },
+            street: {
+              type: 'object',
+              properties: {
+                name: {
+                  type: 'string',
+                  example: 'MURRAY'
+                },
+                type: {
+                  type: 'object',
+                  properties: {
+                    code: {
+                      type: 'string',
+                      example: 'ROAD'
+                    },
+                    name: {
+                      type: 'string',
+                      example: 'RD'
+                    }
+                  }
+                }
+              }
+            },
+            locality: {
+              type: 'object',
+              properties: {
+                name: {
+                  type: 'string',
+                  example: 'CHRISTMAS ISLAND'
+                },
+                class: {
+                  type: 'object',
+                  properties: {
+                    code: {
+                      type: 'string',
+                      example: 'U'
+                    },
+                    name: {
+                      type: 'string',
+                      example: 'UNOFFICIAL SUBURB'
+                    }
+                  }
+                }
+              }
+            },
+            postcode: {
+              type: 'string',
+              example: '6798'
+            },
+            state: {
+              type: 'object',
+              properties: {
+                abbreviation: {
+                  type: 'string',
+                  example: 'OT'
+                },
+                name: {
+                  type: 'string',
+                  example: 'OTHER TERRITORIES'
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    LocalitySearchResult: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          example: 'LILYDALE'
+        },
+        state: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              example: 'VICTORIA'
+            },
+            abbreviation: {
+              type: 'string',
+              example: 'VIC'
+            }
+          }
+        },
+        class: {
+          type: 'object',
+          properties: {
+            code: {
+              type: 'string',
+              description: 'Classification code (G=Gazetted, U=Unofficial, T=Topographic, I=Informal)',
+              example: 'G'
+            },
+            name: {
+              type: 'string',
+              example: 'GAZETTED LOCALITY'
+            }
+          }
+        },
+        postcode: {
+          type: 'string',
+          description: 'Primary postcode for this locality',
+          example: '3140'
+        },
+        score: {
+          type: 'number',
+          example: 5.23
+        },
+        pid: {
+          type: 'string',
+          example: 'loc1234567890ab'
+        }
+      }
+    },
+    Locality: {
+      type: 'object',
+      properties: {
+        locality_name: {
+          type: 'string',
+          example: 'CHRISTMAS ISLAND'
+        },
+        locality_class_code: {
+          type: 'string',
+          example: 'U'
+        },
+        locality_class_name: {
+          type: 'string',
+          example: 'UNOFFICIAL SUBURB'
+        },
+        primary_postcode: {
+          type: 'string',
+          example: '6798'
+        },
+        postcodes: {
+          type: 'array',
+          items: {
+            type: 'string'
+          },
+          example: ['6798']
+        },
+        state_abbreviation: {
+          type: 'string',
+          example: 'OT'
+        },
+        state_name: {
+          type: 'string',
+          example: 'OTHER TERRITORIES'
+        },
+        locality_pid: {
+          type: 'string',
+          example: 'loc9984d8beb142'
+        }
+      }
+    },
+    PostcodeSearchResult: {
+      type: 'object',
+      properties: {
+        postcode: {
+          type: 'string',
+          example: '3140'
+        },
+        localities: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              name: {
+                type: 'string',
+                example: 'LILYDALE'
+              }
+            }
+          }
+        }
+      }
+    },
+    PostcodeDetail: {
+      type: 'object',
+      properties: {
+        postcode: {
+          type: 'string',
+          example: '6798'
+        },
+        localities: {
+          type: 'array',
+          description: 'Locality names. Individual locality resources are linked via related Link headers.',
+          items: {
+            type: 'object',
+            properties: {
+              name: {
+                type: 'string',
+                example: 'CHRISTMAS ISLAND'
+              }
+            }
+          }
+        }
+      }
+    },
+    State: {
+      type: 'object',
+      properties: {
+        abbreviation: {
+          type: 'string',
+          example: 'NSW'
+        },
+        name: {
+          type: 'string',
+          example: 'NEW SOUTH WALES'
+        }
+      }
+    },
+    Health: {
+      type: 'object',
+      properties: {
+        status: {
+          type: 'string',
+          example: 'healthy'
+        },
+        version: {
+          type: 'string',
+          example: '2.1.2'
+        },
+        timestamp: {
+          type: 'string',
+          format: 'date-time',
+          example: '2026-04-14T11:17:54.637Z'
+        }
+      }
+    }
+  };
+  return {
+    openapi: '3.0.3',
+    info: {
+      title: 'Addressr by Mountain Pass',
+      description: 'Free Australian Address Validation, Search and Autocomplete. This OpenAPI spec is supplementary — the HATEOAS link-driven API is the authoritative contract. Follow `related` Link headers to navigate between addresses, localities, postcodes and states.\n\nDirect requests to upstream hosts may be rejected when the operator has configured a gateway auth header. Consumers should always call Addressr through its published gateway endpoint; monitoring (`/health`) and spec discovery (`/api-docs`) remain openly reachable.',
+      version: apiVersion
+    },
+    servers: [{
+      url: 'https://addressr.p.rapidapi.com',
+      description: 'RapidAPI'
+    }],
+    paths: {
+      '/addresses': {
+        get: {
+          summary: 'Search Addresses',
+          description: 'Search Australian addresses by any component — street, suburb, postcode, state. Supports fuzzy and prefix matching.',
+          operationId: 'searchAddresses',
+          tags: ['Addresses'],
+          parameters: [{
+            name: 'q',
+            in: 'query',
+            required: true,
+            schema: {
+              type: 'string',
+              minLength: 3
+            },
+            example: 'UNIT 1, 19 MURRAY RD, CHRISTMAS ISLAND',
+            description: 'Address search query (min 3 characters)'
+          }, {
+            name: 'page',
+            in: 'query',
+            required: false,
+            schema: {
+              type: 'integer',
+              minimum: 0
+            },
+            example: 0,
+            description: 'Zero-based page number for pagination'
+          }],
+          responses: {
+            200: {
+              description: 'List of matching addresses',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: {
+                      $ref: '#/components/schemas/AddressSearchResult'
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/addresses/{pid}': {
+        get: {
+          summary: 'Get Address',
+          description: 'Get full structured details for a specific address. Response includes Link headers with `related` rels to the locality, postcode, and state.',
+          operationId: 'getAddress',
+          tags: ['Addresses'],
+          parameters: [{
+            name: 'pid',
+            in: 'path',
+            required: true,
+            schema: {
+              type: 'string'
+            },
+            example: 'GAOT_717882967',
+            description: 'Address persistent identifier (G-NAF PID)'
+          }],
+          responses: {
+            200: {
+              description: 'Address details with structured data',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Address'
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/localities': {
+        get: {
+          summary: 'Search Localities',
+          description: 'Search Australian suburbs and localities by name. Supports fuzzy and prefix matching. Returns localities with state, postcode, and classification.',
+          operationId: 'searchLocalities',
+          tags: ['Localities'],
+          parameters: [{
+            name: 'q',
+            in: 'query',
+            required: true,
+            schema: {
+              type: 'string',
+              minLength: 2
+            },
+            example: 'lilydale',
+            description: 'Locality/suburb name search query (min 2 characters)'
+          }],
+          responses: {
+            200: {
+              description: 'List of matching localities',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: {
+                      $ref: '#/components/schemas/LocalitySearchResult'
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/localities/{pid}': {
+        get: {
+          summary: 'Get Locality',
+          description: 'Get details for a specific locality. Response includes Link headers with `related` rels to the postcode and state.',
+          operationId: 'getLocality',
+          tags: ['Localities'],
+          parameters: [{
+            name: 'pid',
+            in: 'path',
+            required: true,
+            schema: {
+              type: 'string'
+            },
+            example: 'loc9984d8beb142',
+            description: 'Locality persistent identifier'
+          }],
+          responses: {
+            200: {
+              description: 'Locality details',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Locality'
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/postcodes': {
+        get: {
+          summary: 'Search Postcodes',
+          description: 'Search Australian postcodes by prefix. Returns matching postcodes with their associated localities. Omit `q` to list all postcodes in ascending order.',
+          operationId: 'searchPostcodes',
+          tags: ['Postcodes'],
+          parameters: [{
+            name: 'q',
+            in: 'query',
+            required: false,
+            schema: {
+              type: 'string'
+            },
+            example: '314',
+            description: 'Postcode prefix search query (0+ characters). Omit to list all postcodes.'
+          }],
+          responses: {
+            200: {
+              description: 'List of matching postcodes with associated localities',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: {
+                      $ref: '#/components/schemas/PostcodeSearchResult'
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/postcodes/{postcode}': {
+        get: {
+          summary: 'Get Postcode',
+          description: 'Get details for a specific postcode including all associated localities. Each locality is linked via a `related` Link header.',
+          operationId: 'getPostcode',
+          tags: ['Postcodes'],
+          parameters: [{
+            name: 'postcode',
+            in: 'path',
+            required: true,
+            schema: {
+              type: 'string'
+            },
+            example: '6798',
+            description: 'Australian postcode'
+          }],
+          responses: {
+            200: {
+              description: 'Postcode details with associated localities',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/PostcodeDetail'
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/states': {
+        get: {
+          summary: 'Search States',
+          description: 'Search Australian states and territories by name or abbreviation. Omit `q` to list all states alphabetically.',
+          operationId: 'searchStates',
+          tags: ['States'],
+          parameters: [{
+            name: 'q',
+            in: 'query',
+            required: false,
+            schema: {
+              type: 'string'
+            },
+            example: 'New',
+            description: 'State name or abbreviation search (0+ characters). Omit to list all states.'
+          }],
+          responses: {
+            200: {
+              description: 'List of matching states and territories',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'array',
+                    items: {
+                      $ref: '#/components/schemas/State'
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/states/{abbreviation}': {
+        get: {
+          summary: 'Get State',
+          description: 'Get details for a specific state or territory. Use `/localities?q=` or `/postcodes?q=` to search within a state.',
+          operationId: 'getState',
+          tags: ['States'],
+          parameters: [{
+            name: 'abbreviation',
+            in: 'path',
+            required: true,
+            schema: {
+              type: 'string',
+              enum: ['ACT', 'NSW', 'NT', 'QLD', 'SA', 'TAS', 'VIC', 'WA', 'OT']
+            },
+            example: 'NSW',
+            description: 'State/territory abbreviation'
+          }],
+          responses: {
+            200: {
+              description: 'State/territory details',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/State'
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      '/health': {
+        get: {
+          summary: 'Health Check',
+          description: 'Check API service status. Returns version, timestamp, and health status.',
+          operationId: 'healthCheck',
+          tags: ['System'],
+          responses: {
+            200: {
+              description: 'API is healthy',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Health'
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    components: {
+      schemas
+    },
+    tags: [{
+      name: 'Addresses',
+      description: 'Search and retrieve addresses'
+    }, {
+      name: 'Localities',
+      description: 'Search and retrieve suburbs/localities'
+    }, {
+      name: 'Postcodes',
+      description: 'Search and retrieve postcodes'
+    }, {
+      name: 'States',
+      description: 'Search and retrieve states/territories'
+    }, {
+      name: 'System',
+      description: 'System endpoints'
+    }]
+  };
+}
 var serverPort = process.env.PORT || 8080;
 var logger = (0, _debug.default)('api');
 var error = (0, _debug.default)('error');
@@ -25,6 +658,7 @@ error.log = console.error.bind(console);
 let server;
 const PAGE_SIZE = process.env.PAGE_SIZE || 8;
 function startRest2Server() {
+  (0, _proxyAuth.validateProxyAuthConfig)();
   app.use((_request, response, next) => {
     if (process.env.ADDRESSR_ACCESS_CONTROL_ALLOW_ORIGIN !== undefined) {
       response.append('Access-Control-Allow-Origin', process.env.ADDRESSR_ACCESS_CONTROL_ALLOW_ORIGIN);
@@ -37,6 +671,7 @@ function startRest2Server() {
     }
     next();
   });
+  app.use((0, _proxyAuth.proxyAuthMiddleware)());
   const waycharter = new _waycharter.WayCharter();
   app.use(waycharter.router);
   const addressesType = waycharter.registerCollection({
@@ -340,178 +975,7 @@ function startRest2Server() {
   waycharter.registerResourceType({
     path: '/api-docs',
     loader: async () => {
-      const spec = {
-        openapi: '3.0.3',
-        info: {
-          title: 'Addressr by Mountain Pass',
-          description: 'Free Australian Address Validation, Search and Autocomplete. This OpenAPI spec is supplementary — the HATEOAS link-driven API is the authoritative contract.',
-          version: _version.version
-        },
-        paths: {
-          '/addresses': {
-            get: {
-              summary: 'Search Addresses',
-              operationId: 'searchAddresses',
-              parameters: [{
-                name: 'q',
-                in: 'query',
-                required: true,
-                schema: {
-                  type: 'string',
-                  minLength: 3
-                },
-                description: 'Address search query'
-              }],
-              responses: {
-                200: {
-                  description: 'List of matching addresses'
-                }
-              }
-            }
-          },
-          '/addresses/{pid}': {
-            get: {
-              summary: 'Get Address',
-              operationId: 'getAddress',
-              parameters: [{
-                name: 'pid',
-                in: 'path',
-                required: true,
-                schema: {
-                  type: 'string'
-                },
-                description: 'Address persistent identifier'
-              }],
-              responses: {
-                200: {
-                  description: 'Address details with structured data'
-                }
-              }
-            }
-          },
-          '/localities': {
-            get: {
-              summary: 'Search Localities',
-              operationId: 'searchLocalities',
-              parameters: [{
-                name: 'q',
-                in: 'query',
-                required: true,
-                schema: {
-                  type: 'string',
-                  minLength: 2
-                },
-                description: 'Locality/suburb name search query'
-              }],
-              responses: {
-                200: {
-                  description: 'List of matching localities'
-                }
-              }
-            }
-          },
-          '/localities/{pid}': {
-            get: {
-              summary: 'Get Locality',
-              operationId: 'getLocality',
-              parameters: [{
-                name: 'pid',
-                in: 'path',
-                required: true,
-                schema: {
-                  type: 'string'
-                },
-                description: 'Locality persistent identifier'
-              }],
-              responses: {
-                200: {
-                  description: 'Locality details'
-                }
-              }
-            }
-          },
-          '/postcodes': {
-            get: {
-              summary: 'Search Postcodes',
-              operationId: 'searchPostcodes',
-              parameters: [{
-                name: 'q',
-                in: 'query',
-                required: false,
-                schema: {
-                  type: 'string'
-                },
-                description: 'Postcode prefix search query. Omit to list all postcodes.'
-              }],
-              responses: {
-                200: {
-                  description: 'List of matching postcodes with associated localities'
-                }
-              }
-            }
-          },
-          '/postcodes/{postcode}': {
-            get: {
-              summary: 'Get Postcode',
-              operationId: 'getPostcode',
-              parameters: [{
-                name: 'postcode',
-                in: 'path',
-                required: true,
-                schema: {
-                  type: 'string'
-                },
-                description: 'Australian postcode'
-              }],
-              responses: {
-                200: {
-                  description: 'Postcode details with associated localities'
-                }
-              }
-            }
-          },
-          '/states': {
-            get: {
-              summary: 'Search States',
-              operationId: 'searchStates',
-              parameters: [{
-                name: 'q',
-                in: 'query',
-                required: false,
-                schema: {
-                  type: 'string'
-                },
-                description: 'State name or abbreviation search. Omit to list all states.'
-              }],
-              responses: {
-                200: {
-                  description: 'List of matching states and territories'
-                }
-              }
-            }
-          },
-          '/states/{abbreviation}': {
-            get: {
-              summary: 'Get State',
-              operationId: 'getState',
-              parameters: [{
-                name: 'abbreviation',
-                in: 'path',
-                required: true,
-                schema: {
-                  type: 'string'
-                },
-                description: 'State/territory abbreviation (e.g., NSW, VIC)'
-              }],
-              responses: {
-                200: {
-                  description: 'State/territory details'
-                }
-              }
-            }
-          }
-        }
-      };
+      const spec = buildOpenApiSpec(_version.version);
       return {
         body: spec,
         headers: {

package/lib/version.js

@@ -5,4 +5,4 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.version = void 0;
 // Generated by genversion.
-const version = exports.version = '2.1.2';
+const version = exports.version = '2.1.4';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mountainpass/addressr",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "description": "Australian Address Validation, Search and Autocomplete",
   "author": {
     "name": "Mountain Pass",
@@ -207,7 +207,7 @@
     "dry-aged-deps": "^2.6.0",
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-chai-friendly": "^1.1.0",
+    "eslint-plugin-chai-friendly": "^1.2.0",
     "eslint-plugin-import-x": "^4.16.2",
     "eslint-plugin-n": "^17.24.0",
     "eslint-plugin-prettier": "^5.5.5",