feat(landing): standardized VGI landing surface + _vgi_identity cookie

Add a landingDescribe provider hook: serve the shared self-contained landing.html
(vendored byte-identical from vgi-web-frontend) with content negotiation, plus
GET {prefix}/describe.json and the lazy column endpoint. At the OAuth callback
decode the OIDC id_token and set a JS-readable `_vgi_identity` cookie (display
claims only) that the shared page reads; clear it on logout; remove the old
per-language user-info pill injection. Add a landing-conformance CI job.

Bump 0.9.0 -> 0.10.0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rustyconover

.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
         run: bun install && bun run postinstall
 
       - name: Run unit tests
-        run: bun test test/wire.test.ts test/describe.test.ts test/schema.test.ts test/output-collector.test.ts test/http/handler.test.ts test/http/token.test.ts
+        run: bun test test/wire.test.ts test/describe.test.ts test/schema.test.ts test/output-collector.test.ts test/http/handler.test.ts test/http/landing.test.ts test/http/oauth-pkce.test.ts test/http/token.test.ts
 
       - name: Run client tests (bun transports only)
         run: timeout 120 bun test test/client.test.ts
@@ -120,6 +120,43 @@ jobs:
       - name: Smoke test (Deno)
         run: timeout 60 deno run --allow-all .smoke-bundle/smoke.js
 
+  landing-conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install JS dependencies
+        run: bun install && bun run postinstall
+
+      - name: Install Python dependencies
+        run: pip install jsonschema
+
+      - name: Boot landing worker and run landing conformance
+        run: |
+          bun run examples/conformance-landing.ts > /tmp/landing-port.txt &
+          WORKER_PID=$!
+          for i in $(seq 1 30); do
+            PORT=$(grep -o 'PORT:[0-9]*' /tmp/landing-port.txt | cut -d: -f2 || true)
+            [ -n "$PORT" ] && break
+            sleep 0.5
+          done
+          test -n "$PORT" || { echo "worker did not report a port"; cat /tmp/landing-port.txt; exit 1; }
+          echo "worker on port $PORT"
+          # The runner + describe.schema.json are vendored under conformance/;
+          # DEFAULT_SCHEMA resolves next to the script.
+          python conformance/run_landing_conformance.py --url "http://localhost:$PORT"
+          STATUS=$?
+          kill $WORKER_PID 2>/dev/null || true
+          exit $STATUS
+
   conformance:
     runs-on: ubuntu-latest
     steps:

Makefile

@@ -7,7 +7,7 @@
 PYTHON ?= /Users/rusty/Development/vgi-rpc/.venv/bin/python
 
 # Unit test files (no external dependencies)
-UNIT_TESTS := test/wire.test.ts test/describe.test.ts test/schema.test.ts test/output-collector.test.ts test/http/handler.test.ts test/http/token.test.ts test/http/sticky.test.ts test/auth.test.ts test/http-auth.test.ts test/bearer.test.ts
+UNIT_TESTS := test/wire.test.ts test/describe.test.ts test/schema.test.ts test/output-collector.test.ts test/http/handler.test.ts test/http/landing.test.ts test/http/oauth-pkce.test.ts test/http/token.test.ts test/http/sticky.test.ts test/auth.test.ts test/http-auth.test.ts test/bearer.test.ts
 
 SRC := $(wildcard src/**/*.ts src/*.ts)
 

conformance/describe.schema.json

@@ -0,0 +1,166 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://query.farm/vgi/describe.schema.json",
+  "title": "VGI worker describe.json (landing contract)",
+  "description": "Validates GET {prefix}/describe.json. See docs/http-landing-contract.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["landing_schema_version", "worker", "server_id", "oauth", "cupola_base", "catalogs"],
+  "properties": {
+    "landing_schema_version": { "type": "integer", "minimum": 1 },
+    "worker": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "doc", "version", "lang"],
+      "properties": {
+        "name": { "type": "string" },
+        "doc": { "type": "string" },
+        "version": { "type": "string" },
+        "lang": { "enum": ["python", "go", "rust", "typescript", "java"] }
+      }
+    },
+    "server_id": { "type": "string" },
+    "oauth": { "type": "boolean" },
+    "cupola_base": { "type": "string", "format": "uri" },
+    "catalogs": { "type": "array", "items": { "$ref": "#/$defs/catalog" } }
+  },
+  "$defs": {
+    "catalog": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "implementation_version", "data_version_spec", "data_versions", "attach_options", "tags", "counts", "schemas"],
+      "properties": {
+        "name": { "type": "string" },
+        "implementation_version": { "type": ["string", "null"] },
+        "data_version_spec": { "type": ["string", "null"] },
+        "data_versions": { "type": "array", "items": { "$ref": "#/$defs/dataVersion" } },
+        "attach_options": { "type": "array", "items": { "$ref": "#/$defs/attachOption" } },
+        "tags": { "$ref": "#/$defs/tags" },
+        "counts": { "$ref": "#/$defs/counts" },
+        "schemas": { "type": "array", "items": { "$ref": "#/$defs/schema" } }
+      }
+    },
+    "dataVersion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["spec"],
+      "properties": {
+        "spec": { "type": "string" },
+        "label": { "type": "string" }
+      }
+    },
+    "attachOption": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "type", "default", "description"],
+      "properties": {
+        "name": { "type": "string" },
+        "type": { "type": "string" },
+        "default": { "type": "string" },
+        "description": { "type": "string" }
+      }
+    },
+    "tags": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "title": { "type": "string" },
+        "doc_md": { "type": "string" },
+        "source_url": { "type": "string" },
+        "license": { "type": "string" },
+        "author": { "type": "string" },
+        "copyright": { "type": "string" },
+        "support_contact": { "type": "string" },
+        "support_policy_url": { "type": "string" },
+        "keywords": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "counts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemas", "tables", "views", "functions"],
+      "properties": {
+        "schemas": { "type": "integer", "minimum": 0 },
+        "tables": { "type": "integer", "minimum": 0 },
+        "views": { "type": "integer", "minimum": 0 },
+        "functions": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "schema": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "tables", "views", "functions"],
+      "properties": {
+        "name": { "type": "string" },
+        "tables": { "type": "array", "items": { "$ref": "#/$defs/table" } },
+        "views": { "type": "array", "items": { "$ref": "#/$defs/view" } },
+        "functions": { "type": "array", "items": { "$ref": "#/$defs/function" } }
+      }
+    },
+    "table": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "cols", "comment"],
+      "properties": {
+        "name": { "type": "string" },
+        "cols": { "type": "integer", "minimum": 0 },
+        "comment": { "type": "string" }
+      }
+    },
+    "view": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "cols", "comment", "def"],
+      "properties": {
+        "name": { "type": "string" },
+        "cols": { "type": "integer", "minimum": 0 },
+        "comment": { "type": "string" },
+        "def": { "type": "string" }
+      }
+    },
+    "function": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "type", "doc", "args"],
+      "properties": {
+        "name": { "type": "string" },
+        "type": { "enum": ["scalar", "table", "aggregate", "table_in_out"] },
+        "doc": { "type": "string" },
+        "args": { "type": "array", "items": { "$ref": "#/$defs/arg" } },
+        "returns": { "type": "string" }
+      }
+    },
+    "arg": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "type"],
+      "properties": {
+        "name": { "type": "string" },
+        "type": { "type": "string" },
+        "named": { "type": "boolean" },
+        "default": { "type": "string" },
+        "desc": { "type": "string" }
+      }
+    },
+    "columns": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["columns"],
+      "properties": {
+        "columns": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "type"],
+            "properties": {
+              "name": { "type": "string" },
+              "type": { "type": "string" },
+              "comment": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

conformance/run_landing_conformance.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Landing-page conformance checker for VGI workers (all languages).
+
+Drives a running worker's HTTP landing surface and asserts it conforms to the
+contract in ``docs/http-landing-contract.md``:
+
+* ``GET {prefix}/describe.json`` validates against ``describe.schema.json`` and
+  (optionally) equals a **normalized golden** — the cross-language equality guard.
+* ``GET {prefix}/`` serves the pinned shared ``landing.html`` (asset marker), and
+  ``?format=json`` returns a JSON status.
+* ``GET {prefix}/describe/{catalog}/{schema}/{table}.json`` returns valid columns.
+
+Usage:
+    run_landing_conformance.py --url http://localhost:8790 [--golden fixtures/describe.expected.json]
+    run_landing_conformance.py --url http://localhost:8790 --golden fixtures/describe.expected.json --update
+
+Exit code is non-zero on any failure. ``--update`` (re)writes the golden from the
+live worker (reviewers inspect the diff).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+import urllib.request
+
+import jsonschema
+
+_HERE = pathlib.Path(__file__).resolve().parent
+DEFAULT_SCHEMA = _HERE / "describe.schema.json"
+ASSET_MARKER = "vgi-landing-asset v"
+
+# Fields dropped before comparing to a golden (volatile or language-specific).
+_VOLATILE_TOP = ("server_id", "worker", "oauth")
+
+
+def _get(url: str, accept: str = "application/json") -> tuple[int, bytes, str]:
+    req = urllib.request.Request(url, headers={"Accept": accept})
+    try:
+        with urllib.request.urlopen(req) as resp:  # noqa: S310 — trusted local URL
+            return resp.status, resp.read(), resp.headers.get("Content-Type", "")
+    except urllib.error.HTTPError as exc:  # type: ignore[attr-defined]
+        return exc.code, exc.read(), exc.headers.get("Content-Type", "")
+
+
+def normalize(doc: dict) -> dict:
+    """Strip volatile/language-specific fields so goldens compare across languages."""
+    return {k: v for k, v in doc.items() if k not in _VOLATILE_TOP}
+
+
+def _canonical(doc: dict) -> str:
+    return json.dumps(doc, indent=2, sort_keys=True, ensure_ascii=False)
+
+
+def check(
+    base_url: str,
+    *,
+    schema_path: pathlib.Path = DEFAULT_SCHEMA,
+    golden_path: pathlib.Path | None = None,
+) -> list[str]:
+    """Return a list of failure strings (empty == conformant)."""
+    base = base_url.rstrip("/")
+    fails: list[str] = []
+    schema = json.loads(schema_path.read_text())
+    columns_schema = {**schema, **schema["$defs"]["columns"]}
+
+    # 1) describe.json — schema-valid.
+    status, body, _ = _get(f"{base}/describe.json")
+    if status != 200:
+        return [f"GET /describe.json returned HTTP {status}"]
+    doc = json.loads(body)
+    try:
+        jsonschema.validate(doc, schema)
+    except jsonschema.ValidationError as exc:
+        fails.append(f"describe.json schema violation: {exc.message} at {list(exc.absolute_path)}")
+
+    # 2) GET / serves the pinned shared page; ?format=json is a JSON status.
+    status, html, ctype = _get(f"{base}/", accept="text/html")
+    if status != 200 or "text/html" not in ctype:
+        fails.append(f"GET / (Accept: text/html) returned HTTP {status} {ctype!r}")
+    elif ASSET_MARKER not in html.decode("utf-8", "replace"):
+        fails.append(f"GET / did not serve the pinned landing.html (missing {ASSET_MARKER!r} marker)")
+    status, jbody, _ = _get(f"{base}/?format=json")
+    try:
+        assert json.loads(jbody).get("status") == "ok"
+    except Exception:  # noqa: BLE001
+        fails.append("GET /?format=json did not return a JSON status object")
+
+    # 3) Lazy column endpoints — validate one table + one view per schema.
+    for cat in doc.get("catalogs", []):
+        for sch in cat.get("schemas", []):
+            samples = (sch.get("tables") or [])[:1] + (sch.get("views") or [])[:1]
+            for obj in samples:
+                cstatus, cbody, _ = _get(f"{base}/describe/{cat['name']}/{sch['name']}/{obj['name']}.json")
+                if cstatus != 200:
+                    fails.append(f"columns {cat['name']}/{sch['name']}/{obj['name']} -> HTTP {cstatus}")
+                    continue
+                try:
+                    jsonschema.validate(json.loads(cbody), columns_schema)
+                except jsonschema.ValidationError as exc:
+                    fails.append(f"columns {sch['name']}.{obj['name']} schema violation: {exc.message}")
+
+    # 4) Golden diff (cross-language equality).
+    if golden_path is not None:
+        got = _canonical(normalize(doc))
+        want = golden_path.read_text() if golden_path.exists() else None
+        if want is None:
+            fails.append(f"golden {golden_path} does not exist (run with --update)")
+        elif got.strip() != want.strip():
+            fails.append(f"describe.json does not match golden {golden_path.name} (normalized diff)")
+
+    return fails
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--url", required=True, help="Worker base URL, e.g. http://localhost:8790")
+    ap.add_argument("--schema", type=pathlib.Path, default=DEFAULT_SCHEMA)
+    ap.add_argument("--golden", type=pathlib.Path, default=None)
+    ap.add_argument("--update", action="store_true", help="Write the normalized golden from the live worker")
+    args = ap.parse_args()
+
+    if args.update:
+        if args.golden is None:
+            ap.error("--update requires --golden")
+        _, body, _ = _get(f"{args.url.rstrip('/')}/describe.json")
+        args.golden.parent.mkdir(parents=True, exist_ok=True)
+        args.golden.write_text(_canonical(normalize(json.loads(body))) + "\n")
+        print(f"wrote golden {args.golden}")
+        return 0
+
+    fails = check(args.url, schema_path=args.schema, golden_path=args.golden)
+    if fails:
+        print(f"FAIL ({len(fails)}):")
+        for f in fails:
+            print(f"  - {f}")
+        return 1
+    print("PASS: landing conformance OK")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dist/http/handler.d.ts.map

@@ -10,6 +10,6 @@ export type { CertValidateFn, XfccElement, XfccValidateFn } from "./mtls.js";
 export { mtlsAuthenticate, mtlsAuthenticateFingerprint, mtlsAuthenticateSubject, mtlsAuthenticateXfcc, parseXfcc, } from "./mtls.js";
 export { cookieAuthenticate } from "./oauth-pkce.js";
 export { type UnpackedToken, unpackStateToken } from "./token.js";
-export type { HttpHandlerOptions, StateSerializer } from "./types.js";
+export type { HttpHandlerOptions, LandingDescribeProvider, StateSerializer } from "./types.js";
 export { jsonStateSerializer } from "./types.js";
 //# sourceMappingURL=index.d.ts.map