shared

func AccountID ¶

func AccountID(ctx context.Context) string

AccountID returns the authenticated account ID from context, or empty string.

func CORSMiddleware ¶

func CORSMiddleware(allowedOrigins []string) func(http.Handler) http.Handler

CORSMiddleware sets CORS headers per an explicit origin allowlist.

Semantics:

• Empty allowedOrigins → deny all cross-origin requests. Same-origin requests (where the browser omits Origin, or Origin matches the served host) are unaffected because browsers don't enforce CORS on them. This is the safe default for local/trial installs.
• allowedOrigins contains "*" → echo back the request Origin for any cross-origin caller (dev/testing only — do not use in prod).
• Otherwise → echo back the Origin only when it's in the allowlist.

Why the default flipped (2026-04-24 security review): the previous behavior treated an empty allowlist as "allow all", which contradicted the documented "Empty = same-origin only" contract and let any website read /api/user/vault/* via the browser when combined with local_bypass auth (anonymous → LocalOwnerAccountID). A malicious page could enumerate vault metadata including route_token — a usable proxy bearer.

func CorrelationID ¶

func CorrelationID(ctx context.Context) string

CorrelationID returns the request correlation ID from context, or empty string.

func CorrelationIDMiddleware ¶

func CorrelationIDMiddleware(next http.Handler) http.Handler

CorrelationIDMiddleware attaches a correlation/request ID to every request context. It honours the X-Correlation-ID header if present; otherwise generates a new UUID.

func DomainErrorResponse ¶

func DomainErrorResponse(w http.ResponseWriter, err *DomainError)

DomainErrorResponse converts a DomainError to an HTTP response, including any structured meta fields (field, rule, upstream_status, etc.). Internal-only meta (db_detail, constraint) is stripped from the response but logged server-side for debugging. See Issue #17.

func Error ¶

func Error(w http.ResponseWriter, status int, code, message string)

Error writes a structured JSON error response without meta context. Prefer DomainErrorResponse for typed errors.

func GenerateOpaqueToken ¶

func GenerateOpaqueToken() (plaintext, hash string, err error)

GenerateOpaqueToken returns a URL-safe base64-encoded random token and its SHA-256 hex hash. The plaintext is sent to clients; only the hash is stored in the database so the plaintext cannot be recovered from a DB breach.

func HandleDomainErr ¶

func HandleDomainErr(w http.ResponseWriter, err error)

HandleDomainErr converts service errors to HTTP responses. Uses errors.As to unwrap DomainErrors through fmt.Errorf chains. All other errors are logged and returned as SYS_INTERNAL. Exported so that handler sub-packages (master/, user/) can use it without importing the api package (which would cause circular imports).

func HashToken ¶

func HashToken(plaintext string) string

HashToken returns the SHA-256 hex hash of a client-supplied plaintext token. Use this to look up a stored token hash from a value presented by the client.

func JSON ¶

func JSON(w http.ResponseWriter, status int, v any)

JSON writes a JSON-encoded body with the given status code.

func JWTMiddleware ¶

func JWTMiddleware(ts *TokenService) func(http.Handler) http.Handler

JWTMiddleware validates the Bearer token in Authorization header and injects Claims into the request context. Returns 401 if the token is missing or invalid.

func LocalIdentityMiddleware ¶

func LocalIdentityMiddleware(ts ...*TokenService) func(http.Handler) http.Handler

LocalIdentityMiddleware provides a permissive auth layer for local/trial modes. If the request carries a valid Bearer JWT, it extracts the real account identity (needed for CLI sync where each member must see their own keys). Otherwise it falls back to the fixed "local-owner" identity so web pages work without login.

func LoggingMiddleware ¶

func LoggingMiddleware(logger *slog.Logger) func(http.Handler) http.Handler

LoggingMiddleware logs every request with method, path, and correlation ID.

func MasterKeyFromBase64 ¶

func MasterKeyFromBase64(encoded string) ([]byte, error)

MasterKeyFromBase64 decodes a base64-encoded 32-byte master key string (e.g. from the MASTER_KEY environment variable).

func NewID ¶

func NewID() string

NewID generates a new UUID-based string ID.

func NewRevision ¶

func NewRevision() string

NewRevision generates a short random hex string used as an object revision token. Revisions are opaque, monotonically increasing only by convention (latest wins in fact tables).

func OpenDB ¶

func OpenDB(dsn string) (*sql.DB, error)

OpenDB opens a PostgreSQL connection pool from the given DSN.

func RunMigrations ¶

func RunMigrations(db *sql.DB, dir string) error

RunMigrations executes unapplied .sql files from the given directory in lexical order. It tracks applied migrations in a `schema_migrations` table so each migration runs only once. Each migration runs in its own transaction; if any fails, the process stops.

func TranslatePGError ¶

func TranslatePGError(err error) error

TranslatePGError converts a PostgreSQL driver error to a DomainError when a known constraint mapping exists. Unknown DB errors are returned unchanged (they become SYS_INTERNAL in handleDomainErr).

Rule: call this at the repository boundary immediately on INSERT/UPDATE errors, before any fmt.Errorf wrapping, so the domain error can be unwrapped by handleDomainErr via errors.As.