Skip to content
Kozou

Authentication and authorization

A question that comes up early with any database-backed system is “where does login live?” For Kozou the answer is deliberate, and it splits cleanly into two axes.

Two questions, two axes

Section titled “Two questions, two axes”

There are two different security questions, and conflating them causes confusion:

  • Is the text trusted? — the COMMENT trust boundary, covered in PostgreSQL as the source of truth. It is about prompt injection: the COMMENT text Kozou forwards to an AI agent is treated as authored by a trusted principal.
  • Who may read or write the data? — access control. This page is about that axis.

This page answers the second question. The short version: Kozou is a resource server and an enforcement layer, not an identity provider.

What Kozou is: a resource server and enforcement layer

Section titled “What Kozou is: a resource server and enforcement layer”

When you enable auth, the in-house REST backend (@kozou/api) verifies a signed JWT on each request that carries one — an HS256 shared secret, an RS256 public key, or a provider’s remote JWKS endpoint — and then runs that request inside a transaction under:

SET LOCAL ROLE <role-from-claim>;
-- request.jwt.claims is published too, so policies can read the claims

From there, your own PostgreSQL row-level-security (RLS) policies decide what the request can read and write. Kozou switches role and publishes the claims; it does not write the policies. Because enforcement lives in the database, it is route-independent — the same RLS applies whether a row is reached through Kozou, through psql, or through any other client connecting under a role subject to those policies.

This maps directly onto the roles an application already needs. “Admin”, “editor”, “author”, “viewer” are PostgreSQL roles plus RLS policies, and Kozou already runs each request under the role named by the verified token. A request with no token is rejected with 401, unless you configure an anonymous role — in which case it runs under that role with empty claims so your policies decide what an anonymous caller sees.

What Kozou is not: an identity provider

Section titled “What Kozou is not: an identity provider”

Kozou does not provide identity. The following are out of scope and are expected to come from elsewhere:

  • user registration and self-service signup,
  • login, sessions, and password storage / reset,
  • OAuth and social login,
  • minting and refreshing the JWT itself.

A FastAPI-Users-style authentication / user-management library is a non-goal for Kozou. Kozou consumes a token; it does not issue one (beyond the internal service token the bundled Admin UI uses under kozou dev).

Section titled “Recommended setups”

Bring an identity provider that issues a role-claim JWT, and point Kozou at it:

  • Supabase Auth — recommended. It is PostgreSQL-native, issues JWTs with a role claim, and is designed around RLS — it lines up directly with Kozou’s enforcement model.
  • Auth0 / Clerk — verify against the provider’s remote JWKS endpoint (jwt.jwksUri); keys are selected by kid, cached, and refreshed on rotation.
  • A minimal self-hosted issuer — any small service that mints a role-claim JWT signed with the secret Kozou verifies.
  • Enterprise OIDC providers (Entra ID / Okta / Google Workspace) — for internal / line-of-business use, point Kozou at your corporate identity provider via the same JWKS path; see Single sign-on with Entra ID, Okta, or Google.

The auth block that wires this up is documented in kozou.config.yaml, and the request-level behaviour is described in the REST API guide.

Why this boundary

Section titled “Why this boundary”

Kozou is a compiler from your schema to its surfaces — an Admin UI, a REST API, MCP context. Identity is a cross-cutting concern that is not part of that core, and it is the highest-stakes, highest-maintenance surface in any system: credential storage, password reset, account takeover, MFA, OAuth. Delegating it to a hardened provider is the better trade. It is also the same boundary the broader ecosystem already draws — PostgREST delegates identity to GoTrue / Supabase Auth rather than implementing login itself. Kozou drawing the same line keeps it focused and keeps your credentials in a system built to guard them.

Where Kozou invests instead

Section titled “Where Kozou invests instead”

The part of authorization that is Kozou-shaped is the model, not the login screen. Roles and RLS policies are facts about the schema, and Kozou is a schema compiler. So the direction Kozou invests in is compiling the role + RLS authorization model from the schema and surfacing it — through the @policy advisory tag shown to AI agents, through generated documentation, and through MCP context — not through building login features.

Where to next

Section titled “Where to next”