Many assume that encrypting data at rest is enough to satisfy HIPAA for vector databases, but auditability and controlled access are equally critical.
HIPAA’s Security Rule obliges covered entities to maintain detailed records of who accessed electronic protected health information (ePHI), when the access occurred, and what was disclosed. Auditors look for immutable logs, evidence of least‑privilege enforcement, and proof that any inadvertent exposure was mitigated. For a vector database that stores embeddings derived from patient records, the burden is not just protecting the storage layer; it is also proving that every query, update, or export was authorized and traceable.
In practice, many teams connect to a vector store using a shared service account or a static API key. The credential lives in configuration files or CI pipelines, and developers invoke the database directly from notebooks or micro‑services. This model provides no visibility into individual user actions, no way to block a risky query, and no systematic masking of PHI that might appear in a result set. When an audit request arrives, the only artifact available is the credential itself – a clear gap between operational convenience and regulatory compliance.
Organizations often respond by adding an identity layer: they federate the service account with an OIDC provider, assign users to roles, and enforce token‑based authentication at the database endpoint. While this step ensures that only authenticated identities can connect, the request still travels straight to the vector store. The database records a successful connection, but it does not capture the exact query, cannot redact sensitive fields on the fly, and cannot require a manual approval for high‑risk operations. The audit trail remains incomplete, and the system cannot guarantee that PHI never leaves the controlled environment.
hoop.dev addresses this shortfall by inserting a Layer 7 gateway between the authenticated identity and the vector database. The gateway becomes the sole data‑path for every request, and it enforces the controls required for HIPAA evidence.
How hoop.dev creates audit‑ready artifacts
hoop.dev records each session end‑to‑end, storing a timestamped log that includes the user identity, the exact query text, and the response metadata. Because the gateway sits in the protocol stream, the log reflects the true operation performed on the vector store, not just a successful connection.
hoop.dev masks sensitive fields in query results before they reach the client. If an embedding lookup returns a record that contains a patient name or identifier, the gateway can replace those values with placeholders, ensuring that downstream tools never see raw PHI.
When a request matches a high‑risk pattern, such as a bulk export, a similarity search across an entire index, or a write operation that could overwrite existing embeddings, hoop.dev routes the request to a human approver. The approver’s decision is captured as part of the session record, providing undeniable proof that the operation was reviewed and authorized.
hoop.dev can also block disallowed commands outright. For example, a DELETE statement that attempts to remove an entire collection can be intercepted, logged, and rejected, preventing accidental data loss that would otherwise be hard to explain to an auditor.
Mapping hoop.dev’s outcomes to HIPAA requirements
- Audit controls (45 CFR 164.312(b)): The session logs generated by hoop.dev satisfy the requirement for recording user activity, including the who, what, and when of every interaction with ePHI.
- Integrity (45 CFR 164.312(c)): By blocking unauthorized commands and requiring approval for risky operations, hoop.dev helps maintain the integrity of the underlying data.
- Transmission security (45 CFR 164.312(e)(1)): Inline masking ensures that any PHI that might be returned to a client is transformed before it leaves the trusted boundary.
- Access control (45 CFR 164.308(a)(1)(i)): The gateway enforces just‑in‑time, identity‑aware policies, guaranteeing that each request is scoped to the minimum privileges required for the task.
Because hoop.dev stores these artifacts outside the vector database process, the evidence cannot be tampered with by someone who has access to the database itself. Auditors can retrieve the logs directly from the gateway’s audit store, providing a clear chain of custody for every ePHI interaction.
Operational flow for a HIPAA‑aligned vector search
- A developer authenticates to the organization’s OIDC provider (Okta, Azure AD, etc.).
- The issued token is presented to hoop.dev, which validates the signature and extracts group membership.
- The request is forwarded through hoop.dev to the vector database. Policy rules evaluate the query in real time.
- If the query is benign, hoop.dev forwards it, applies any configured masking, and returns the sanitized result.
- If the query matches a high‑risk pattern, hoop.dev pauses execution, notifies an approver, records the decision, and then either forwards or rejects the request.
- Throughout the session, hoop.dev writes a detailed audit record that can be exported for compliance reporting.
This flow shows that the only point where enforcement occurs is the gateway itself. The identity provider supplies who the requester is, but without hoop.dev the request would reach the vector store unchecked.
Getting started
hoop.dev is open source and released under the MIT license. Deploy the gateway using the Docker Compose quick‑start, point it at your vector database, and configure OIDC authentication. The getting‑started guide walks you through the minimal setup, and the learn site contains deeper discussions of masking policies, approval workflows, and audit‑log retention.
FAQ
What specific evidence does hoop.dev provide for a HIPAA audit?It generates session logs that include user identity, timestamp, full query text, any masking actions applied, and the outcome of approval steps. These logs can be exported in JSON or CSV for audit review.Do I need to change my vector‑database client code?No. hoop.dev accepts standard client connections (e.g., the Python SDK, REST API, or gRPC client). The client points to the gateway’s address instead of the raw database endpoint.How does inline masking protect PHI without breaking the vector search?Masking rules can target specific fields in the response payload. For similarity searches that return identifiers, hoop.dev replaces those identifiers with opaque tokens while preserving the embedding vectors needed for downstream processing.
By placing a single, identity‑aware gateway in front of your vector store, you obtain the audit trail, data‑masking, and just‑in‑time approval that HIPAA expects. The result is a compliance‑ready architecture without redesigning your existing applications.
Explore the source code and contribute to the project on GitHub.
