sdk

package
v0.1.2 Latest Latest
Warning

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

Go to latest
Published: Oct 12, 2026 License: Apache-2.0, Apache-2.0 Imports: 13 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 Assignment added in v0.1.1

type Assignment struct {
	ID         string  `json:"id"`
	PositionID string  `json:"positionId"`
	MemberID   string  `json:"memberId"`
	ValidFrom  string  `json:"validFrom"`
	ValidTo    *string `json:"validTo"`
}

Assignment is a member holding a position for a validity window.

type BatchItem added in v0.1.1

type BatchItem struct {
	Object struct {
		Type string `json:"type"`
		ID   string `json:"id"`
	} `json:"object"`
	Relation string `json:"relation"`
}

BatchItem is one object-relation pair of a batch check.

func NewBatchItem added in v0.1.1

func NewBatchItem(objectType, objectID, relation string) BatchItem

NewBatchItem builds a BatchItem.

type BatchResult added in v0.1.1

type BatchResult struct {
	Object struct {
		Type string `json:"type"`
		ID   string `json:"id"`
	} `json:"object"`
	Relation string   `json:"relation"`
	Decision Decision `json:"decision"`
}

BatchResult is one item's decision.

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) BatchCan added in v0.1.1

func (c *Client) BatchCan(ctx context.Context, userBearer string, req CanRequest, items []BatchItem) ([]BatchResult, error)

BatchCan asks up to 100 object-relation questions for the user in one call; req carries the feature, module and company, items the objects. One round trip for a page of controls.

func (*Client) BatchCanService added in v0.1.1

func (c *Client) BatchCanService(ctx context.Context, req CanRequest, items []BatchItem) ([]BatchResult, error)

BatchCanService is BatchCan for the app's own service account.

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) GroupMembers added in v0.1.1

func (c *Client) GroupMembers(ctx context.Context, companyID, groupID string) ([]GroupMember, error)

GroupMembers lists the current members of groupID in companyID, as the app's service account.

func (*Client) MeCompanies added in v0.1.1

func (c *Client) MeCompanies(ctx context.Context, userBearer string) ([]Company, error)

MeCompanies lists the companies the user behind userBearer may see: their active memberships in active companies. The company switcher's source.

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) MemberDirectory added in v0.1.1

func (c *Client) MemberDirectory(ctx context.Context, companyID, q string, page, pageSize int) (DirectoryPage, error)

MemberDirectory reads one page of companyID's active members, optionally filtered by a substring of display name or email, as the app's service account. The service account must be a member of the company.

func (*Client) PositionHolder added in v0.1.1

func (c *Client) PositionHolder(ctx context.Context, companyID, positionID string, date time.Time) (Assignment, error)

PositionHolder answers who holds positionID in companyID on date, as the app's service account. A 404 APIError means nobody holds it that day.

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 Company added in v0.1.1

type Company struct {
	ID       string `json:"id"`
	Code     string `json:"code"`
	Name     string `json:"name"`
	IsActive bool   `json:"isActive"`
}

Company is one company the user may see.

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 DirectoryEntry added in v0.1.1

type DirectoryEntry struct {
	ID            string `json:"id"`
	DisplayName   string `json:"displayName"`
	Email         string `json:"email"`
	HasLinkedUser bool   `json:"hasLinkedUser"`
	Kind          string `json:"kind"` // "person" or "service"
}

DirectoryEntry is one member of a company's directory: the least-disclosure view.

type DirectoryPage added in v0.1.1

type DirectoryPage struct {
	Items      []DirectoryEntry `json:"items"`
	Total      int              `json:"total"`
	Page       int              `json:"page"`
	PageSize   int              `json:"pageSize"`
	TotalPages int              `json:"totalPages"`
}

DirectoryPage is one page of a company's directory.

type GroupMember added in v0.1.1

type GroupMember struct {
	GroupID           string `json:"groupId"`
	MemberID          string `json:"memberId"`
	MemberDisplayName string `json:"memberDisplayName"`
	MemberEmail       string `json:"memberEmail"`
	AddedBy           string `json:"addedBy"`
	AddedAt           string `json:"addedAt"`
}

GroupMember is one member of a group.

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