orgjwt

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package orgjwt puts the session's active organization into the tokens plugin/jwt mints: its id, slug, the caller's role in it and the permissions that role grants, Clerk's "o" organization claim. A service receiving the token can then scope a request to the organization without reading the auth database.

Claims builds a jwt.ClaimsFunc, so it rides in the session token (jwt.ClaimSource(claims)) or in one template (jwt.Template{Claims: claims}); nothing is added until the app passes it. Claims returns an error for a bad option, so a misconfiguration stops the app at start instead of failing every token call. Like every claim in a JWT, it is a copy that lives for the token's TTL: a member removed from the organization keeps the claim in a token already minted until that token expires, and the next token has none.

Index

Constants

View Source
const (
	// DefaultClaim is the claim the organization object is written under;
	// ClaimName changes it (Clerk's tokens use "o").
	//ds:def id=orgjwt-defaultclaim-k8tn3wqz owner=@khanakia stability=stable
	DefaultClaim = "org"
)

Claim and field names.

Variables

This section is empty.

Functions

func Claims

func Claims(src Source, opts ...Option) (jwt.ClaimsFunc, error)

Claims returns the claims func. With an active organization the caller is still a member of, the claim is

{"org": {"id": "...", "slug": "...", "role": "admin", "permissions": ["member:create", ...]}}

with permissions sorted, so two tokens of one role are byte-equal. With no active organization, or one the caller has left or been removed from, there is no claim: a receiver reads the missing claim as "no organization" rather than trusting a stale one. A failing read fails the token call, so no token is minted without a claim the receiver relies on.

A nil Source or an option given nil (Permissions(nil)) returns an error naming it, and a func that fails every token call with that error, never one that quietly uses the role-derived permissions. Check the error to stop at start; ignoring it still fails loudly at the first token.

func Flatten

func Flatten(p access.Permissions) []string

Flatten turns permissions into "resource:action" strings, sorted and without duplicates; a resource with no action yields nothing. Never nil, so the claim is [] rather than null for a role that grants nothing.

Types

type Option

type Option func(*config)

Option configures Claims.

func ClaimName

func ClaimName(name string) Option

ClaimName writes the organization object under name instead of DefaultClaim. The name must not be a registered claim (sub, iss, aud, exp, iat, nbf, jti, sid, act): the token call fails with jwt.ErrReservedClaim if it is. "" keeps DefaultClaim.

func Permissions

func Permissions(fn PermissionsFunc) Option

Permissions replaces where the permissions come from. The default reads the organization plugin's own roles (Source.PermissionsOf), which is wrong for an app that decides permissions elsewhere: with organization.WithAuthorizer backed by Casbin, OPA, Cedar or a relationship store, the roles say nothing about what the authorizer allows, so a token built from them would claim permissions the app never grants, or miss ones it does. Such an app passes its authorizer's answer here, or turns the claim off with WithoutPermissions. An error fails the token call. nil is refused: every token call then fails with auth.ErrNilOption naming the option, because silently falling back to the role-derived list is exactly the wrong-permissions case this option exists to prevent.

func WithoutPermissions

func WithoutPermissions() Option

WithoutPermissions leaves the permissions out, for a receiver that checks roles only, a token that must stay small, or an app whose authorizer cannot list permissions up front (see Permissions); every role's permissions otherwise ride in every token.

type PermissionsFunc

type PermissionsFunc func(ctx context.Context, orgID, userID string, role organization.Role) ([]string, error)

PermissionsFunc lists what userID may do in orgID, as the strings the claim carries ("member:create" by Flatten's convention, or whatever the receiver checks). role is the stored role, for a source that maps roles.

type Source

type Source interface {
	// ActiveOrgID is the active organization of the request's session in
	// ctx; ok is false for none.
	ActiveOrgID(ctx context.Context) (id string, ok bool, err error)
	// GetFor reads an organization by id.
	GetFor(ctx context.Context, orgID string) (organization.Org, error)
	// RoleOf is userID's role in orgID, or organization.ErrNotMember.
	RoleOf(ctx context.Context, orgID, userID string) (organization.Role, error)
	// PermissionsOf is what role grants in orgID.
	PermissionsOf(ctx context.Context, orgID string, role organization.Role) (access.Permissions, error)
}

Source is what the claim reads the organization from. *organization.Plugin implements it; a test or an app with its own organization model passes another, which is why the claim depends on this and not on the plugin.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL