hoop

The webapp_v2 migration follows a structured roadmap to transition the Hoop Web App from ClojureScript (CLJS) to React. The process is divided into three main tracks:

1. Track A (Dead-CLJS Cleanup): Sequential PRs to prepare for migration by cleaning up dead scaffolding, settings, admin panels, and auth/user/org logic.
2. Track B (Migration Waves): The core migration effort organized into waves (Wave 1 to Wave 7). Waves move from visible value/tiny pages to complex infrastructure like resource wizards, runners, session details, and finally the Webclient.
3. Track C (Parity Track): Interleaved tasks to ensure global CLJS behaviors (like Segment tracking, MS Clarity, clipboard blocking, and organization migration dialogs) are replicated in React before the CLJS bundle is removed.

The migration concludes with the Endgame, which involves removing the bridge, tearing down the build process, and deleting the original webapp/ source.

Review resources consist of one or more review groups. Each group tracks its own status, the reviewer, and the timestamp of the review.

Review Group Data Structures

Initial State (PENDING) When a review is first created, groups are initialized with null for reviewer and date information:

{
    "id": "aaa257be-5cc9-401d-ae7e-18ae806d366a",
    "group": "banking",
    "status": "PENDING",
    "reviewed_by": null,
    "review_date": null
}

Completed State Once a review is processed, the entry is populated with the reviewer's identity and the timestamp:

{
    "id": "a546dfba-d917-4c2b-bc38-7852a7932573",
    "group": "banking",
    "status": "REJECTED",
    "reviewed_by": {
        "id": "17e4ff1a-104c-482c-be68-3c01bfc7028e",
        "name": "John Doe",
        "email": "john.doe@domain.tld",
        "slack_id": ""
    },
    "review_date": "2025-05-27T16:40:05.519754143Z"
}

hoopinspect uses a layered policy approach via policy.Chain{local, opa}.

Local Rules are evaluated first to avoid unnecessary network round-trips. They support protocol-specific matching:

• SQL: deny_words_list, pattern_match (REVER), operation, table.
• HTTP: http_resource, http_status.
• Cross-protocol: pii (for detecting sensitive information).

OPA (Open Policy Agent) is used for more complex logic. hoopinspect sends an input document to an OPA Data API endpoint. The input document is a strict superset of metadata provided by ext_authz and postgres_proxy and works for both protocols.

Important: Both evaluators fail closed. If OPA is unreachable or returns an undefined decision, the request is denied. You can set FailOpen to invert this behavior if availability is a higher priority than enforcement.

policy.NewRules([]policy.Rule{
    {Name: "no-drop", Type: policy.MatchOperation,
     Operations: []hoopinspect.Operation{hoopinspect.OpDrop}},

    policy.Rule{Name: "no-admin", Type: policy.MatchHTTPResource}. 
        WithResources("/admin/**"),

    policy.Rule{Name: "no-5xx-leak", Type: policy.MatchHTTPStatus}.
        WithStatuses("5xx").
        WithMessage("upstream failure suppressed by policy"),
})

Before writing policies, be aware of the following technical limits of the inspection engine:

• Table Detection: Tables identification is best-effort. An empty result means "could not determine," not "touches nothing." For critical protection, use RequireTableMatch: true.
• Postgres Response Truncation: To protect relay memory, the Postgres codec stops decoding columns after 1000 rows in a single result set. The batch is marked Truncated. Policies must treat a Truncated batch as inconclusive rather than proof that a value is absent.
• Database Statement Verbs: Database response statements report OpUnknown because the operation is tied to the original request. Key response-side SQL rules on Result instead of Operation.
• PII Detection: PII detection is pattern-based and not exhaustive. It is not a replacement for table-level access control.
• HTTP Protocols: Stream decoding is supported for HTTP/1.x only. For HTTP/2 and HTTP/3, use InspectRequest as the framing is handled by the connection terminator.
• Path Normalization: Normalization is conservative. Numeric, UUID, hex, and long opaque segments are collapsed, but short slugs are not. Policies may be narrower than intended.
• Transaction Isolation: The gate evaluates each statement independently; there is no cross-statement session state.

The hsh tunnel provides a dual-stack virtual network to allow seamless access to tunneled resources. It uses a client-side resolver that maps connection names to virtual IP addresses. This approach ensures that multiple connections to the same service (e.g., multiple Postgres instances) can all listen on the same port (e.g., 5432) without local port collisions.

Addressing Schemes

• IPv6 (ULA): Uses Unique Local Addresses from the fd00::/8 range. A /48 prefix is determined per tunnel session based on a hash of the Org ID and Tunnel Session ID.
• IPv4 (CGNAT): Uses the 100.64.0.0/10 range. A /16 prefix is allocated per tunnel session.

Key Properties

• Deterministic Mapping: Connection names map to IPs via a stable hash. The same name will resolve to the same IP across tunnel restarts within a single session lifetime.
• Immutability: IPs are immutable for the duration of a tunnel session. While the connection list can refresh and add new mappings, existing name-to-IP mappings are never reassigned to prevent breaking in-flight TCP connections.
• Client-Side Resolution: The DNS resolver is owned by the tunnel client and is bound to the tunnel gateway IP (e.g., [fd00:hash:hash:hash::1]:53). It is not recursive; it only resolves names within the .hoop (or overridden) domain.