chore(release): promote staging to production for v1.3.0

.dockerignore

@@ -1 +1,45 @@
-.venv
+# Keep the build context to what the image actually runs.
+#
+# The tracked tree is ~13 MB; the context was ~316 MB, almost entirely .git.
+# CI clones full history, and every Dagster+ deploy was transferring it before
+# the first layer could build.
+
+# Version control. Nothing in the image reads git metadata.
+.git
+.github
+.gitignore
+
+# Python build and cache artifacts. Stale .pyc from a different interpreter is
+# worse than useless in an image built on a pinned base.
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Virtualenvs and local tooling state.
+.venv
+.dg
+*.tfstate
+*.tfstate.*
+.terraform/
+
+# Local-only data from legacy transfer runs. Untracked, machine-specific, and
+# the largest thing on a developer checkout by an order of magnitude -- a local
+# `docker build` would otherwise ship ~900 MB of CSV cache.
+transfers/data/
+transfers/logs/
+transfers/metrics/
+
+# Test fixtures and BDD features. The image runs the code location, not the
+# suite; CI runs the suite outside the image.
+tests/
+features/
+
+# Editor and OS noise.
+.DS_Store
+.idea/
+.vscode/

.env.example

@@ -10,6 +10,26 @@ POSTGRES_PORT=5432
 PYGEOAPI_POSTGRES_PASSWORD=your_password
 PYGEOAPI_POSTGRES_USER=your_username
 
+# PYGEOAPI internal mount (/ogcapi-internal) -- authenticated, unfiltered
+# (private/draft-inclusive) mirror of /ogcapi. Shares PYGEOAPI_POSTGRES_*
+# above; only the mount path, runtime dir, and advertised server URL differ.
+PYGEOAPI_INTERNAL_MOUNT_PATH=/ogcapi-internal
+PYGEOAPI_INTERNAL_RUNTIME_DIR=/tmp/pygeoapi-internal
+# Leave blank to derive from PYGEOAPI_SERVER_URL's application root. Only set
+# this when the internal mount is served from a different host than /ogcapi.
+PYGEOAPI_INTERNAL_SERVER_URL=
+
+# Static API keys for /ogcapi-internal, for desktop GIS clients that cannot
+# refresh an Authentik access token (ArcGIS Pro, QGIS). Comma- or
+# whitespace-separated `label:sha256hex` entries; the label is bookkeeping
+# only. Blank means bearer-JWT access only. Mint one with:
+#   python -c "import secrets,hashlib;k=secrets.token_urlsafe(32);print(k,hashlib.sha256(k.encode()).hexdigest())"
+# Give the first value to the user, put `label:<second value>` here.
+# Deployed environments source this from the Secret Manager secret
+# `internal-ogc-api-keys`, not from a GitHub secret.
+# See docs/internal-ogc-desktop-gis.md.
+INTERNAL_OGC_API_KEYS=
+
 # Connection pool configuration for parallel transfers
 # pool_size: number of persistent connections to maintain
 # max_overflow: additional connections allowed during peak usage
@@ -73,19 +93,28 @@ MODE=development
 # ENABLE_PG_CRON=0
 
 # disable authentication (for development only)
+#
+# Honored ONLY when MODE=development. With any other MODE (including unset or
+# "staging"), the app refuses to start -- core.permissions.assert_auth_configuration()
+# raises AuthConfigurationError rather than serving every endpoint anonymously.
 AUTHENTIK_DISABLE_AUTHENTICATION=1
 
 # erase and rebuild the database for step tests
 REBUILD_DB=1
 
 # authentik
+# AUTHENTIK_URL is both the JWKS base and the expected `iss` claim; trailing
+# slash optional, both spellings are accepted.
 AUTHENTIK_URL=
 AUTHENTIK_CLIENT_ID=
 AUTHENTIK_AUTHORIZE_URL=
 AUTHENTIK_TOKEN_URL=
 
-# middleware
-SESSION_SECRET_KEY=your_secret_key_here
+# How long a fetched JWKS document is trusted, in seconds (default 3600).
+# An unrecognized `kid` forces one immediate refresh regardless, so this only
+# bounds how long a revoked key stays usable.
+# AUTHENTIK_JWKS_TTL_SECONDS=3600
+
 
 # feedback endpoint (POST /feedback) — bug reports and feature requests
 JIRA_BASE_URL=https://nmbgmr.atlassian.net

.github/app.template.yaml

@@ -34,6 +34,13 @@ env_variables:
   PYGEOAPI_POSTGRES_PASSWORD: |-
     ${PYGEOAPI_POSTGRES_PASSWORD}
   PYGEOAPI_SERVER_URL: "${PYGEOAPI_SERVER_URL}"
+  # Hashed static API keys for the authenticated /ogcapi-internal mount, as
+  # `label:sha256hex` entries, sourced from the Secret Manager secret
+  # `internal-ogc-api-keys`. Needed because ArcGIS Pro and QGIS cannot refresh
+  # an Authentik access token; see core/internal_ogc_auth.py and
+  # docs/internal-ogc-desktop-gis.md. Unset means bearer-JWT access only.
+  INTERNAL_OGC_API_KEYS: |-
+    ${INTERNAL_OGC_API_KEYS}
   CLOUD_SQL_IAM_AUTH: "${CLOUD_SQL_IAM_AUTH}"
   GCS_SERVICE_ACCOUNT_KEY: |-
     ${GCS_SERVICE_ACCOUNT_KEY}
@@ -42,8 +49,6 @@ env_variables:
   AUTHENTIK_CLIENT_ID: "${AUTHENTIK_CLIENT_ID}"
   AUTHENTIK_AUTHORIZE_URL: "${AUTHENTIK_AUTHORIZE_URL}"
   AUTHENTIK_TOKEN_URL: "${AUTHENTIK_TOKEN_URL}"
-  SESSION_SECRET_KEY: |-
-    ${SESSION_SECRET_KEY}
   APITALLY_CLIENT_ID: "${APITALLY_CLIENT_ID}"
   JIRA_BASE_URL: "${JIRA_BASE_URL}"
   JIRA_EMAIL: "${JIRA_EMAIL}"

.github/skills/code-review/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: code-review
+description: Repository-specific review rules for OcotilloAPI pull requests. Use this when reviewing a pull request in this repository, so review comments account for the authorization, schema, domain-layer, and migration conventions that are easy to violate silently.
+---
+
+# Reviewing OcotilloAPI pull requests
+
+OcotilloAPI is a FastAPI + PostgreSQL/PostGIS geospatial service for the New Mexico
+Bureau of Geology and Mineral Resources. Read `CLAUDE.md` at the repository root for
+the full architecture; this skill lists the mistakes worth flagging in review because
+they fail silently rather than breaking a test.
+
+Use the GitHub MCP server tools (`list_workflow_runs`, `summarize_job_log_failures`,
+`get_job_logs`) to check whether the `Test Suite` workflow is failing before commenting
+on behavior — a failing `unit-tests` job often explains the diff better than the diff does.
+
+## Authorization is opt-in, so omissions are invisible
+
+Authorization is applied per endpoint via a parameter in the route signature, not by a
+router-level `dependencies=[...]`. Two failure modes to flag:
+
+1. A new route with no `user: <role>_dependency` parameter is fully public and raises no
+   error. If the pull request adds a route, check whether it belongs in the anonymous-route
+   allowlist in `tests/test_authorization.py`. If it does not, it needs a role dependency.
+2. The dependency must be a **type annotation** (`user: viewer_dependency`), never a default
+   value (`user=viewer_dependency`). The latter silently disables the dependency, and FastAPI
+   reinterprets it as a query parameter. Flag this every time.
+
+Role families are orthogonal: general `Admin` confers nothing in the `AMP*` or `Lexicon*`
+families. Only tiers within one family nest. A diff that treats `Admin` as a superset of
+`AMPEditor` is wrong.
+
+`@in_public_schema` controls anonymous OpenAPI visibility only. It grants no access and
+removes no dependency; flag any use that appears to be standing in for authorization.
+
+`/ogcapi-internal` is a raw Starlette Mount and is gated at the ASGI layer in
+`core/internal_ogc_auth.py`, outside `Depends()`. Changes to its credential paths should
+cite `docs/internal-ogc-desktop-gis.md`.
+
+The development auth bypass (`AUTHENTIK_DISABLE_AUTHENTICATION=1`) is honored only when
+`MODE=development`. Any change that widens that condition is a security finding.
+
+## Model changes are a five-step workflow
+
+A pull request that edits a model in `db/` is incomplete unless it also covers the matching
+Pydantic schemas in `schemas/`, an Alembic migration, test fixtures and payloads in `tests/`,
+and the field mappings in `transfers/` when the field is populated from the legacy AMPAPI
+data. Flag whichever step is missing.
+
+Schema conventions: `Create` schemas use `<type>` for non-nullable and `<type> | None = None`
+for nullable; `Update` schemas make every field optional with a `None` default; `Response`
+schemas use `<type>` for non-nullable and `<type> | None` for nullable.
+
+Validation split: input validation belongs in Pydantic validators and produces 422s. Database
+constraint checks are manual in the endpoint and produce 409s. Custom exceptions should use
+`PydanticStyleException` from `services/exceptions_helper.py` so error bodies stay consistent.
+
+## Layer boundaries
+
+`domain/` holds business rules as plain functions over plain values. Modules there must not
+import from `api/`, `db/`, `schemas/`, or `services/`, and must not import `fastapi`,
+`sqlalchemy`, `pydantic`, or `httpx`. Flag any new import that breaks this — it is what keeps
+the rules testable without a database. Domain errors subclass `ValueError` because the CSV
+importers treat a `ValueError` on a row as a per-row validation failure; an exception type
+that does not subclass `ValueError` will escape that handling. See `ADR4.md`.
+
+`services/` is the layer that loads data, calls the domain rule, and persists the result.
+
+## Spatial and query specifics
+
+All geometries are WGS84 (SRID 4326). Legacy transfer scripts convert from UTM (SRID 26913);
+a missing transformation puts points in the wrong hemisphere rather than raising.
+
+List filters arrive from the Refine UI as repeated `filter` query parameters containing JSON.
+Association-backed columns are virtual and map to EXISTS subqueries in
+`services/query_helper.py`, not to `ILIKE` on an ORM proxy. Sorting by monitoring status or
+well status must use SQL subqueries on `StatusHistory`, because `ORDER BY` cannot see a Python
+`@property`. See `docs/refine-json-filters-and-virtual-fields.md`.
+
+## Migrations
+
+Alembic schema migrations run automatically in the deployment pipeline. Registered *data*
+migrations do not — they sit unapplied until someone runs them by hand. If a pull request adds
+a data migration, ask how and when it will be run.