Documentation
¶
Overview ¶
Package guard provides SQL injection prevention utilities for Quark ORM. It validates identifiers, operators, and raw queries against known-safe patterns.
Index ¶
- Variables
- func HasPlaceholders(query string) bool
- func ValidateJSONPath(path string) error
- func ValidateJSONTablePath(path string) error
- func ValidateJoinOn(expr string) error
- type Quoter
- type SQLGuard
- func (g *SQLGuard) QuoteIdentifier(q Quoter, name string) (string, error)
- func (g *SQLGuard) ValidateIdentifier(name string) error
- func (g *SQLGuard) ValidateIdentifiers(names ...string) error
- func (g *SQLGuard) ValidateJSONPath(path string) error
- func (g *SQLGuard) ValidateJoinOn(expr string) error
- func (g *SQLGuard) ValidateOperator(op string) error
- func (g *SQLGuard) ValidateRawQuery(query string, requirePlaceholders bool) error
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidIdentifier = errors.New("invalid identifier")
ErrInvalidIdentifier is the sentinel for a rejected table/column identifier. It lives here (not in the root package) so ValidateIdentifier can wrap it with %w without an import cycle; the root package re-exports it as quark.ErrInvalidIdentifier, so callers can errors.Is() the rejection regardless of which call site (query, migrate, cte, events…) produced it — consistent with ErrInvalidJoin / ErrInvalidJSONPath.
Functions ¶
func HasPlaceholders ¶
HasPlaceholders checks if a query string contains parameter placeholders.
func ValidateJSONPath ¶ added in v0.3.0
ValidateJSONPath checks that a JSON path is shaped like a dotted identifier chain (e.g. "user.profile.email") and rejects anything that could carry SQL injection: empty paths, paths with quotes, semicolons, comment markers, whitespace, leading "$", or paths longer than maxJSONPathLen.
It is a package-level function (not a method) because the validation has no configurable state and the dialect layer needs to call it without holding an SQLGuard instance.
The error message starts with "ErrInvalidJSONPath:" so callers in package quark can wrap it with the public sentinel via errors.Join.
func ValidateJSONTablePath ¶ added in v0.3.0
ValidateJSONTablePath is a defensive validator for MariaDB's JSON_TABLE root path. Unlike ValidateJSONPath it accepts the JSONPath shapes that JSON_TABLE requires (`$`, `$[*]`, `$.items[0]`, `$.items[*].name`) but rejects anything that looks like injection.
The JSON_TABLE entry point is internal-only today; this validator exists so that any caller in package quark or trusted internal code paths still gets a fail-fast error if a bad value reaches the dialect.
func ValidateJoinOn ¶ added in v0.3.0
ValidateJoinOn checks that an ON clause matches the minimal identifier- only grammar Quark accepts while a structured Join().On() builder is pending. It rejects anything containing literals, semicolons, comments, quotes, parentheses, or arbitrary whitespace surrounding non-token characters — so injection payloads ("...; DROP TABLE x") cannot pass.
Returns an error whose message starts with "ErrInvalidJoin:" so callers in package quark can wrap it with the public sentinel via errors.Join.
Types ¶
type Quoter ¶
Quoter is a minimal interface for quoting SQL identifiers. It avoids a circular import with the dialect package.
type SQLGuard ¶
type SQLGuard struct {
// contains filtered or unexported fields
}
SQLGuard provides security validations for SQL queries. It prevents SQL injection by validating identifiers and enforcing safe practices.
func (*SQLGuard) QuoteIdentifier ¶
QuoteIdentifier validates and quotes an identifier using the provided Quoter.
func (*SQLGuard) ValidateIdentifier ¶
ValidateIdentifier checks if a table or column identifier is safe to use.
func (*SQLGuard) ValidateIdentifiers ¶
ValidateIdentifiers checks multiple identifiers at once.
func (*SQLGuard) ValidateJSONPath ¶ added in v0.3.0
ValidateJSONPath is the SQLGuard-bound counterpart to the package-level function; both share the same logic and accept the same shapes.
func (*SQLGuard) ValidateJoinOn ¶ added in v0.3.0
ValidateJoinOn is the SQLGuard-bound counterpart to the package-level function; both share the same logic and accept the same shapes.
func (*SQLGuard) ValidateOperator ¶
ValidateOperator checks if an operator is in the allowed whitelist.
func (*SQLGuard) ValidateRawQuery ¶
ValidateRawQuery performs basic validation on a raw SQL query. It is a best-effort heuristic backstop for the opt-in raw path (AllowRawQueries), NOT a complete anti-injection filter. It does not parse SQL, so it has known false positives — e.g. a `--` inside a string literal (`'range--max'`) is rejected even though it is not a comment; rephrase such a query. The real boundary for raw queries is AllowRawQueries (off by default) + placeholders for values.
Source Files