Merge branch 'master' into fix/api-stacks-optional-auth-strict

Author: mastermanas805

.github/workflows/ci.yml

@@ -213,3 +213,87 @@ jobs:
           echo "Configure services, secrets, and port-forwards, then run e.g.:"
           echo "  go test ./e2e/... -tags e2e -count=1 -timeout 180s"
           echo "See CLAUDE.md (Full-stack E2E) for required env vars."
+
+  # Cross-repo Layer-1 auth-contract gate. The api owns the CORS allowlist
+  # and the /auth/exchange + /auth/email/start endpoints — an api-side
+  # change that drops access-control-allow-credentials would not trigger
+  # the instanode-web CI on its own, so the browser-level regression
+  # (2026-05-29 → 2026-05-30) could ship despite green api unit tests.
+  #
+  # This job fires a repository_dispatch on instanode-web; instanode-web's
+  # .github/workflows/auth-contract-e2e.yml listens for the matching
+  # `auth-contract-e2e-from-api` type and runs the Chromium smoke against
+  # the same prod targets. The dispatch result will not gate this PR
+  # mechanically (cross-repo status checks aren't wired here yet — see
+  # follow-up issue), but it surfaces the failure in the instanode-web
+  # Actions tab so anyone reviewing the api PR can click through.
+  #
+  # Auth: REPO_ACCESS_TOKEN must have `repo` scope on instanode-web. If the
+  # secret is missing the step soft-skips (warn, don't fail) so the api CI
+  # stays green during initial rollout — flip the soft-skip to `exit 1`
+  # once the secret is provisioned on all relevant environments.
+  dispatch-auth-contract-e2e:
+    name: Trigger instanode-web auth-contract smoke
+    runs-on: ubuntu-latest
+    needs: build-and-test
+    if: github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref == 'refs/heads/master')
+    steps:
+      - name: Fire repository_dispatch on instanode-web
+        env:
+          DISPATCH_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}
+          # SECURITY: avoid interpolating untrusted github.event.* fields
+          # into the shell. Only stable repo-controlled identifiers are
+          # exposed and the payload is constructed via printf with
+          # parameter expansion (no string concatenation of attacker
+          # input).
+          SHA: ${{ github.sha }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          TRIGGER: ${{ github.event_name }}
+        run: |
+          set -euo pipefail
+          if [ -z "${DISPATCH_TOKEN:-}" ]; then
+            echo "::warning::REPO_ACCESS_TOKEN not set; skipping cross-repo auth-contract dispatch. " \
+              "Provision the secret on the api repo (with `repo` scope on instanode-web) to enable Layer-1 gate."
+            exit 0
+          fi
+          # PR_NUMBER may be empty on push events; default to "main".
+          # Defense-in-depth: enforce numeric PR number even though
+          # github.event.pull_request.number is an integer assigned by
+          # GitHub, never user-controlled.
+          pr="${PR_NUMBER:-main}"
+          case "$pr" in
+            main|[0-9]*) ;;
+            *) echo "::error::unexpected PR_NUMBER value: $pr"; exit 1 ;;
+          esac
+          # SHA is a 40-char hex from github.sha — repo-controlled. Validate
+          # shape to keep the JSON payload trivially-injection-proof.
+          case "$SHA" in
+            [0-9a-f]*) ;;
+            *) echo "::error::unexpected SHA shape: $SHA"; exit 1 ;;
+          esac
+          # TRIGGER is github.event_name — a GitHub-controlled enum
+          # (push|pull_request|schedule|workflow_dispatch|...). Allowlist
+          # the values this job is reachable from.
+          case "$TRIGGER" in
+            push|pull_request) ;;
+            *) echo "::error::unexpected TRIGGER: $TRIGGER"; exit 1 ;;
+          esac
+          payload=$(printf '{"event_type":"auth-contract-e2e-from-api","client_payload":{"api_sha":"%s","api_pr":"%s","trigger":"%s","api_url":"https://api.instanode.dev","web_origin":"https://instanode.dev"}}' \
+            "$SHA" "$pr" "$TRIGGER")
+          echo "Dispatching to InstaNode-dev/instanode-web: $payload"
+          http_code=$(curl -sS -o /tmp/dispatch.out -w '%{http_code}' \
+            -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${DISPATCH_TOKEN}" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/InstaNode-dev/instanode-web/dispatches \
+            -d "$payload")
+          echo "dispatch response: HTTP $http_code"
+          cat /tmp/dispatch.out || true
+          # GitHub returns 204 on success. Treat anything else as a soft
+          # failure during the rollout window — log and pass so a transient
+          # cross-repo hiccup doesn't red the api PR. Tighten to `exit 1`
+          # once we have a week of clean runs.
+          if [ "$http_code" != "204" ]; then
+            echo "::warning::cross-repo dispatch returned $http_code (expected 204). Not failing the api PR yet."
+          fi

internal/handlers/openapi.go

@@ -1623,6 +1623,19 @@ const openAPISpec = `{
         }
       }
     },
+    "/auth/exchange": {
+      "post": {
+        "summary": "Exchange the AUTH-004 bridge cookie for a session JWT",
+        "description": "Final leg of the AUTH-004 cross-origin sign-in handshake. The /auth/email/callback and /auth/github/callback handlers set a short-lived HttpOnly auth_exchange_cookie and 302 to https://instanode.dev/login/callback?signed_in=1. The dashboard then makes a credentials:include POST to this endpoint. CORS contract: response MUST include Access-Control-Allow-Origin: https://instanode.dev AND Access-Control-Allow-Credentials: true — the browser blocks the read otherwise. Request MUST be a CORS-simple POST (no custom headers like Accept: application/json), since adding one forces a preflight that PreflightAllowlist may reject. Returns 200 + the bearer JWT (24h, HS256, aud=https://api.instanode.dev) on success. The 2026-05-29 to 2026-05-30 prod-login outage chained three failures along this exact endpoint — documenting it here so any future regression is catchable by the cross-stack contract gate (api PR #202).",
+        "requestBody": { "required": false, "description": "No body. The bridge cookie travels in the Cookie header via credentials:include." },
+        "responses": {
+          "200": { "description": "Cookie verified; JWT minted", "content": { "application/json": { "schema": { "type": "object", "required": ["ok", "token"], "properties": { "ok": { "type": "boolean" }, "token": { "type": "string", "description": "Session JWT — store in localStorage and send as Authorization: Bearer for /api/v1/* calls" } } } } } },
+          "400": { "description": "Bridge cookie missing / expired (canonical envelope with error code cookie_missing_or_expired)" },
+          "401": { "description": "Cookie present but signature invalid or aud mismatch" },
+          "503": { "description": "JWT signing failed (downstream)" }
+        }
+      }
+    },
     "/auth/email/callback": {
       "get": {
         "summary": "Consume a magic link, mint a session JWT, 302 to <return_to>",
@@ -3090,7 +3103,7 @@ const openAPISpec = `{
           "notify_webhook": { "type": "string", "description": "Optional https:// URL fired by POST when the deploy reaches a terminal state (status='healthy' or 'failed'). Lets callers subscribe instead of polling GET /deploy/:id. Rejected with 400 + agent_action if the URL is not https, the hostname is unresolvable, or resolves to a private/loopback/link-local/CGNAT IP (SSRF protection). Payload shape: { event: 'deploy.healthy' | 'deploy.failed', deploy_id, app_id, url, commit_id, build_time, duration_s, error_message? }. 2xx → notify_state='sent'; 4xx → 'failed' (no retry — user URL is broken); 5xx/network → up to 3 retries, then 'failed'." },
           "notify_webhook_secret": { "type": "string", "description": "Optional HMAC-SHA256 signing key. When set, every dispatch includes an X-InstaNode-Signature: sha256=<hex(hmac(secret, body))> header. Stored AES-256-GCM encrypted; plaintext never leaves the request. Omit to dispatch without a signature header." },
           "ttl_policy": { "type": "string", "enum": ["auto_24h", "permanent"], "description": "Wave FIX-J. Sets the deploy's lifecycle. 'auto_24h' (default for new deploys) means the deploy auto-expires 24h from creation; the response's agent_action sentence tells the LLM the three explicit routes to keep it permanent. 'permanent' opts the deploy out of TTL up front — useful for production deploys where the agent already knows the user wants it kept. Anonymous tier is FORCED to auto_24h regardless of caller intent. Team-wide default can be flipped via PATCH /api/v1/team/settings." },
-          "redeploy": { "type": "boolean", "default": false, "description": "When true with a matching 'name', replace the existing deployment in place (same app_id + URL, same provider_id) instead of minting a fresh one. The platform looks up the team's most-recent non-terminal deployment whose env_vars._name matches the supplied 'name' (scoped to the resolved 'env'), then routes through the same compute path as POST /deploy/:id/redeploy. Closes the agent-UX gap (2026-05-30): multiple /deploy/new calls for the same logical app used to fan out into N distinct URLs because there was no way to upsert by name. Truthy values: 'true', '1', 'yes' (case-insensitive); anything else is false. Errors: 400 redeploy_requires_name when 'name' is empty; 404 no_existing_deployment_to_redeploy when no live row matches (omit 'redeploy' to create a new deployment, or call GET /api/v1/deployments first to discover the id); 409 not_ready when the matching row exists but has no provider_id yet (initial build still running). Default false: leaving the field absent keeps the legacy fan-out behaviour." }
+          "redeploy": { "type": "boolean", "default": false, "description": "When true with a matching 'name', replace the existing deployment in place (same app_id + URL, same provider_id) instead of minting a fresh one. The platform looks up the team's most-recent non-terminal deployment whose env_vars._name matches the supplied 'name' (scoped to the resolved 'env'), then routes through the same compute path as POST /deploy/:id/redeploy. Closes the agent-UX gap (2026-05-30): multiple /deploy/new calls for the same logical app used to fan out into N distinct URLs because there was no way to upsert by name. Truthy values: 'true', '1', 'yes' (case-insensitive); anything else is false. Errors: 404 no_existing_deployment_to_redeploy when no live row matches (note: an empty 'name' is rejected upstream by the standard name_required check, before this flag is even consulted) (omit 'redeploy' to create a new deployment, or call GET /api/v1/deployments first to discover the id); 409 not_ready when the matching row exists but has no provider_id yet (initial build still running). Default false: leaving the field absent keeps the legacy fan-out behaviour." }
         },
         "required": ["tarball", "name"]
       },

internal/handlers/openapi_test.go

@@ -693,6 +693,15 @@ func TestOpenAPI_CoversAllRegisteredRoutes(t *testing.T) {
 		// thinking cookies are a valid auth mechanism — they're not
 		// (CLAUDE.md "Live API surface" + auth_beareronly_authp0_test.go).
 		"POST /auth/exchange": true,
+		// BUG-API-411 (QA 2026-05-29): RFC 9116 security.txt is a
+		// security-researcher disclosure surface, not an agent-facing
+		// API. The body is hand-crafted text/plain matching RFC §2.3,
+		// not JSON, so it has no OpenAPI schema. Both the canonical
+		// .well-known path and the apex fallback are excluded from the
+		// public spec on the same rationale. See security_txt.go for
+		// the builder and security_txt_test.go for the wire contract.
+		"GET /.well-known/security.txt": true,
+		"GET /security.txt":             true,
 	}
 
 	var missing []string

internal/router/export_test.go

@@ -0,0 +1,15 @@
+package router
+
+// export_test.go — re-export package-private symbols for the
+// _test.go siblings that live in `router_test` (external test
+// package). Keeping these in a `_test.go` file means they're
+// compiled only during `go test` and never leak into the
+// distributed binary.
+
+// ExportedMakeSecurityTxtHandler is the unit-test-facing alias for
+// makeSecurityTxtHandler. The handler builder is package-private in
+// production because the only legitimate consumer is router.New; the
+// alias exists so the patch-coverage gate (100% of changed lines)
+// can directly cover the closure body without standing up the full
+// router New(...) wiring (which needs Postgres + Redis + gRPC).
+var ExportedMakeSecurityTxtHandler = makeSecurityTxtHandler

internal/router/router.go

@@ -546,6 +546,31 @@ func NewWithHooks(cfg *config.Config, db *sql.DB, rdb *redis.Client, geoDbs *mid
 	// MCP authorization profile — RFC 8414 / OAuth 2.0 Protected Resource Metadata.
 	app.Get("/.well-known/oauth-protected-resource", handlers.ServeOAuthProtectedResourceMetadata)
 
+	// BUG-API-411 (QA 2026-05-29): RFC 9116 — security researchers reach for
+	// /.well-known/security.txt to find a responsible-disclosure contact
+	// before filing a public vulnerability report. Pre-fix both api and
+	// apex returned 404 for both /.well-known/security.txt and /security.txt
+	// which made the disclosure surface effectively unreachable. We serve
+	// the same body from BOTH paths so a researcher's first guess works
+	// regardless of which convention they hit, and the body validates
+	// cleanly against https://securitytxt.org/ — Contact + Expires + the
+	// Preferred-Languages and Canonical fields the standard recommends.
+	//
+	// Expires is set 1 year from the build_time stamp so the file stays
+	// fresh as long as the binary is redeployed regularly (each new
+	// image pushes the window forward). When the binary stalls past its
+	// expiry the file silently becomes stale-but-still-served — that's
+	// the right call vs returning 410, which would lock out researchers
+	// during a deploy freeze.
+	serveSecurityTxt := makeSecurityTxtHandler(time.Now())
+	app.Get("/.well-known/security.txt", serveSecurityTxt)
+	// Some scanners + older guidance hit /security.txt at the root. RFC
+	// 9116 §3 names the .well-known path as canonical (the file itself
+	// declares it via the Canonical: field above) but the apex path is
+	// a documented fallback — serving the same body avoids a needless
+	// 404 on the legacy path.
+	app.Get("/security.txt", serveSecurityTxt)
+
 	// Prometheus metrics — gated by METRICS_TOKEN when set (open in local dev).
 	app.Get("/metrics", func(c *fiber.Ctx) error {
 		if cfg.MetricsToken != "" {

internal/router/security_txt.go

@@ -0,0 +1,56 @@
+package router
+
+// security_txt.go — RFC 9116 /.well-known/security.txt handler builder.
+//
+// Extracted from router.go's inline closure so the handler stays
+// directly addressable from package_test.go (the New(...) wiring path
+// is heavyweight to bring up in a test — needs Postgres + Redis + gRPC
+// — and the 100%-of-changed-lines patch coverage gate trips on lines
+// only reachable through that path). Keeping the body builder + the
+// handler closure here makes the unit test cover both via a direct
+// call.
+//
+// The handler is deliberately stateless. It captures `now` at builder
+// time so the Expires field round-trips through `time.Time` (and tests
+// can inject a known time without relying on time.Now() drift).
+
+import (
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+)
+
+// makeSecurityTxtHandler returns a fiber handler that serves the RFC
+// 9116 security.txt body. The body's Expires field is set to 1 year
+// after `now` (RFC 9116 §2.5.5 SHOULD-NOT exceed 1 year), so each
+// fresh deploy pushes the window forward — the file stays valid as
+// long as the binary is redeployed regularly.
+//
+// Body content is constant across handler instances except for the
+// Expires field, which is the only time-varying line.
+func makeSecurityTxtHandler(now time.Time) fiber.Handler {
+	expiresAt := now.UTC().AddDate(1, 0, 0).Format("2006-01-02T15:04:05Z")
+	body := buildSecurityTxtBody(expiresAt)
+	return func(c *fiber.Ctx) error {
+		c.Set(fiber.HeaderContentType, "text/plain; charset=utf-8")
+		return c.SendString(body)
+	}
+}
+
+// buildSecurityTxtBody assembles the RFC 9116 body. Split from
+// makeSecurityTxtHandler so the body shape is testable without
+// instantiating a fiber.Handler closure.
+//
+// Field order matches the RFC's example: Contact (mandatory, ×2 for
+// channel redundancy), Expires (mandatory), then the recommended
+// fields. Trailing newline on the final field per §2.3 line-format
+// (every field MUST be CRLF-terminated; LF-only is widely accepted
+// and is what every other instanode file uses).
+func buildSecurityTxtBody(expiresAt string) string {
+	return "Contact: mailto:security@instanode.dev\n" +
+		"Contact: https://instanode.dev/security\n" +
+		"Expires: " + expiresAt + "\n" +
+		"Preferred-Languages: en\n" +
+		"Canonical: https://api.instanode.dev/.well-known/security.txt\n" +
+		"Policy: https://instanode.dev/security\n"
+}