sdk

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Sep 27, 2026 License: Apache-2.0, Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package sdk is the Go client for an application that runs beside Kiban: the app's backend authenticates as its registered service client, verifies the user tokens Kiban's login issued, asks for access decisions, writes and removes relation tuples on the app's own object types, and looks members up — all through the gateway's public API, never by network position.

client, err := sdk.New(ctx, sdk.Config{GatewayURL: "https://kiban.example", ClientID: "tokidesk-backend", ClientSecret: secret})
sub, err := client.VerifyUserToken(ctx, bearer)            // the user behind a request
d, err := client.Can(ctx, bearer, sdk.CanRequest{...})       // may this user do this here?
err = client.Grant(ctx, companyID, sdk.Tuple{...})           // the app owns its own types

Index

Constants

This section is empty.

Variables

View Source
var ErrTokenInvalid = modulekit.ErrTokenInvalid

ErrTokenInvalid is returned by VerifyUserToken for a token Kiban did not issue, or one that expired or names another audience.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	Status  int
	Code    string
	Message string
	Details any
}

APIError is Kiban's error envelope.

func (*APIError) Error

func (e *APIError) Error() string

type AppManifest

type AppManifest struct {
	Key             string          `json:"key"`
	DisplayName     string          `json:"displayName"`
	Version         string          `json:"version"`
	ServiceClientID string          `json:"serviceClientId"`
	Features        []string        `json:"features,omitempty"`
	AuthzFragment   json.RawMessage `json:"authzFragment"`
}

AppManifest registers the app: its key, service client, feature keys and object types.

type CanRequest

type CanRequest struct {
	FeatureKey string `json:"featureKey"`
	ModuleKey  string `json:"moduleKey,omitempty"`
	CompanyID  string `json:"companyId,omitempty"`
	Scope      string `json:"scope,omitempty"` // "company" (default) or "global"
	Object     *struct {
		Type string `json:"type"`
		ID   string `json:"id"`
	} `json:"object,omitempty"`
	Relation string `json:"relation,omitempty"`
}

CanRequest asks "may the bearer use featureKey of moduleKey in companyId?", optionally bound to one object relation.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is safe for concurrent use.

func New

func New(ctx context.Context, cfg Config) (*Client, error)

New validates cfg and fetches the realm's signing keys once; a gateway that cannot be reached is an error here, not later.

func (*Client) Can

func (c *Client) Can(ctx context.Context, userBearer string, req CanRequest) (Decision, error)

Can asks for a decision on behalf of the user whose bearer the app received. Kiban answers for that bearer only.

func (*Client) CanService

func (c *Client) CanService(ctx context.Context, req CanRequest) (Decision, error)

CanService asks for a decision for the app's own service account (a background job).

func (*Client) Grant

func (c *Client) Grant(ctx context.Context, companyID string, tuples ...Tuple) error

Grant writes tuples on the app's own object types in companyID. Every module object must carry its company anchor; AnchorTuple builds it.

func (*Client) MemberBySubject

func (c *Client) MemberBySubject(ctx context.Context, companyID, subject string) (MemberFact, error)

MemberBySubject asks org whether subject is an active member of companyID.

func (*Client) RegisterApp

func (c *Client) RegisterApp(ctx context.Context, superadminBearer string, m AppManifest) error

RegisterApp registers (or re-registers) the app with a superadmin's bearer. Typically run once by an operator or at the app's first start.

func (*Client) Revoke

func (c *Client) Revoke(ctx context.Context, companyID string, tuples ...Tuple) error

Revoke removes tuples the app wrote.

func (*Client) ServiceToken

func (c *Client) ServiceToken(ctx context.Context) (string, error)

ServiceToken returns the app's own access token (client credentials), refreshed before it expires. Callers rarely need it directly; the methods below use it.

func (*Client) VerifyUserToken

func (c *Client) VerifyUserToken(ctx context.Context, bearer string) (string, error)

VerifyUserToken checks a bearer a user presented to the app and returns its subject.

type Config

type Config struct {
	// GatewayURL is the gateway's origin, e.g. "https://kiban.example". Login, JWKS and the
	// API all hang off it.
	GatewayURL string
	// Realm defaults to "kiban".
	Realm string
	// ClientID and ClientSecret are the app's confidential service client.
	ClientID     string
	ClientSecret string
	// Audience defaults to "kiban-api".
	Audience string
	// HTTPClient defaults to one with a 15 s timeout.
	HTTPClient *http.Client
}

Config names the Kiban deployment and the app's service client (KIBAN_SERVICE_CLIENTS).

type Decision

type Decision struct {
	Allowed bool   `json:"allowed"`
	Reason  string `json:"reason"`
}

Decision is Kiban's answer: allowed, or denied with one of the frozen reason codes.

type MemberFact

type MemberFact struct {
	IsMember bool    `json:"isMember"`
	IsActive bool    `json:"isActive"`
	MemberID *string `json:"memberId"`
}

MemberFact answers "is this subject an active member of this company, and which member".

type Tuple

type Tuple = modulekit.Tuple

Tuple is one relation tuple: object#relation@subject (subjectRelation for a userset).

func AnchorTuple

func AnchorTuple(appKey, objectType, objectID, companyID string) Tuple

AnchorTuple is the `<objectType>:<objectID>#company_module @ company_module:<companyID>/<appKey>` tuple every object of the app must carry: it binds the object to the company. Write it in the same Grant call as the object's first tuple.

Jump to

Keyboard shortcuts

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