Organization reference

Config

organization({ … }) takes the config below, plus what a schema cannot carry: roles, ownership, onDelete, the four lifecycle hooks and the two membership hooks.

retention.purgeAfterDays is the default a Worker’s policy can replace. When the retention block in the Worker’s pithy.config.ts names purgeWindows.organization, that window wins, and the manifest and pithy doctor say which one is in force: retention and legal holds.

Routes

{base} is basePath. The member routes verify a bearer token or a session; every mutating one is CSRF-guarded. The control-plane routes are reached by a registered connection, each under the scope it names.

The five ownership routes mount only where ownership is passed — the four member routes and the forced-ownership route — and only then does the manifest advertise the last one. Every control-plane write takes a reason, and so do the two previews, which take their write’s own body, and the invitation listing, in its query. The tenant listing pages on a cursor: an optional limit, 1 to 100, and cursor, the last page’s nextCursor, which is null at the end. It narrows on the server with state, active, suspended or deleted, judged as every door judges it, so a suspension past its end is active. One tenant’s roster takes an optional limit, 1 to 100, and answers truncated when there were more. The role catalog is read from config, so it answers the same against an empty database: a management client offers roles without owningRole, and never a role it only saw on a roster. What each membership route does, and refuses, is membership administration; the last six rows are organization lifecycle.

ORGANIZATION_ROUTES in src/http/routes.ts is the registry this table mirrors, and the package’s route-contract test compares it against what Hono actually mounted, in both directions.

Control-plane scopes

Matched exactly, with no prefix rule, so none implies another and none implies a read. The kind is what the manifest carries beside each route’s scope, for a management client’s own roles. Scopes explains why each is split where it is.

Error codes

Read the way every error code in the kit is.

Three codes from other domains reach these routes. controlplane/insufficient_scope (403) refuses an operator’s roster write that would move the owning role, naming the ownership route in params.ownershipRoute. core/conflict (409) refuses a write whose subject’s role changed while it ran, a forced transfer to somebody who already owns the account, a suspension or reinstatement of a deleted organization, naming the restore route, and a restore once the purge window has closed. validation/invalid_input (400) refuses a malformed body, an operator naming a role the catalog does not declare, a member’s role change to a role nobody may assign, and a suspension whose until is not in the future. An invitation offering such a role is organization/forbidden instead.

Audit events

Every code is organization/*. The member acts are recorded against the member who took them; the operator acts with actorType: "control-plane", the token’s sub as the actor, the connection and the reason. No event carries an email address.

organization/refused records four refusals: organization/forbidden, organization/last_administrator, organization/invitation_invalid and organization/nomination_invalid, each from a session with an organization in force. organization/not_found is never recorded, because anybody can produce it by naming a UUID.

An operator’s scope refusal is the control plane’s to record. A roster write refused for moving the owning role writes controlplane/call_denied with refusedBy: "handler", not an organization/* event.

Every event that changes a role says what it was before. A role change, either ownership event and the operator’s role change carry previousRole beside role, and every member event names the member as subjectUserId, so the access history replays who held what without a guess. An accepted transfer also writes an organization/member_role_changed for each previous holder it demoted, as a forced transfer already did with its admin_* events.

Tables

All six in the app D1, bound as DB, beside auth’s.

Imports

@pithy-sh/organization/src/index exports organization, defineRoles, requireOrganization, requirePower, organizationDatabase, requireMayAssign, organizationRefusal and the seven scope constants, among others. Three are deep imports: clearActing from @pithy-sh/organization/src/acting/acting; runOrganizationPurge and runOrganizationPurgeDue from @pithy-sh/organization/src/purge/workflow, the bodies of the two purge Workflows your Worker exports; and deriveSlug from @pithy-sh/organization/src/data/slug, which previews the short name a form will get. The server derives it again, and the unique index settles it.

License

MIT. The root LICENSE covers it.