Authentication & Authorization

Companions:

COLLECTIONS.md — lifecycle hooks (including beforeRead / afterRead) live on the collection schema; this doc is the reference for the auth subsystem the hooks plug into.
ROUTING-API.md — server-fn transport that resolves RequestContext and passes it down.
RELATIONSHIPS.md — ReadContext is the seed for the actor-carrying RequestContext; populate threads beforeRead through to populated target collections.
CLIENT-SDK.md — the in-process SDK is where actor threading becomes externally visible.

Overview

Byline ships an end-to-end authentication and authorization subsystem with three load-bearing properties:

Admin identity is a built-in subsystem, not a collection. admin_users, admin_roles, admin_role_admin_user, and admin_permissions are dedicated tables owned by @byline/admin (with the Postgres adapter in @byline/db-postgres/admin). Admin users are never localized, versioned, workflowed, or rendered by the collection runtime.
Two auth realms from day one — AdminAuth and UserAuth. Actor = AdminAuth | UserAuth | null. Today only AdminAuth and the null (anonymous public) case are used at runtime; UserAuth is reserved in the type union so the contract does not have to grow a discriminator later.
Service-layer enforcement, not transport-layer enforcement. Every gate runs inside @byline/core / @byline/admin services, so the same gate is active no matter which transport (admin server fn, in-process client, future stable HTTP) invokes it. Transport edges only resolve and pass RequestContext.

The subsystem is split across two packages by concern:

Package	Role
`@byline/auth`	Leaf package. Actor primitives (`AdminAuth`, `UserAuth`, `Actor`), the `RequestContext` shape, the `AbilityRegistry`, the `SessionProvider` interface, and the `AuthError` factories. No DB, no transport — types and small classes only.
`@byline/admin`	Concrete admin subsystem. Admin user / role / permission / account modules (each as `commands.ts` + `repository.ts` + `service.ts` + `dto.ts` + `schemas.ts` + `errors.ts` + `abilities.ts`), the built-in `JwtSessionProvider`, password hashing (argon2id), and the `AdminStore` aggregate.

Postgres-backed repositories ship as the @byline/db-postgres/admin subpath, plugged into AdminStore.

Quick reference

Each entry is the minimal shape for one task. The "Edit" line tells you which file you actually change; the link at the end points at the deeper architecture section.

1. Register a new ability

Abilities are flat dotted strings. Subsystems register them once at boot so the role-ability editor can enumerate them as a checkbox tree.

Edit: the registering module — e.g. packages/admin/src/modules/admin-users/abilities.ts for built-in admin abilities, or apps/webapp/byline/server.config.ts after initBylineCore() returns for app-level additions.

import type { AbilityRegistry } from '@byline/auth'

export function registerMyPluginAbilities(registry: AbilityRegistry) {
  registry.register({
    key: 'plugins.myThing.read',
    label: 'Read my-thing',
    group: 'My Plugin',
    description: 'View my-thing records.',
  })
  registry.register({
    key: 'plugins.myThing.update',
    label: 'Update my-thing',
    group: 'My Plugin',
    description: 'Edit my-thing records.',
  })
}

Collection abilities (collections.<path>.{read,create,update,delete,publish,changeStatus}) are auto-registered by initBylineCore() — only plugins outside the collection runtime need to register manually.

→ Abilities

2. Assert an ability at a service-layer call site

Service-layer enforcement is the real boundary. UI cues are cosmetic. Every write entry point and every read entry point on @byline/client already routes through these helpers — you only call them directly when authoring a new service.

Edit: the new service file — e.g. packages/core/src/services/<your-service>.ts (collection scope) or packages/admin/src/modules/<module>/commands.ts (admin scope).

// Collection-scope service — gates `verb` on `collections.<path>.<verb>`.
import { assertActorCanPerform } from '@byline/core/auth'

await assertActorCanPerform(requestContext, collectionPath, 'update')

// Admin-scope command — always requires AdminAuth, asserts the named ability.
import { assertAdminActor } from '@byline/admin'

const actor = assertAdminActor(requestContext, 'admin.users.create')

→ The enforcement boundary

3. Resolve RequestContext in a script or seed

Seeds, migrations, and one-off scripts need a RequestContext to call @byline/client or any service-layer entry point. Use createSuperAdminContext — the super-admin path is explicit in the code, never ambient.

Edit: apps/webapp/byline/seeds/<your-seed>.ts (or any script that imports byline/server.config.ts).

import { createSuperAdminContext } from '@byline/auth'
import { getBylineClient } from '@byline/core'

const context = createSuperAdminContext({ id: 'seed:bootstrap' })
const client = getBylineClient({ requestContext: context })

await client.collection('pages').create({ title: 'Hello world' })

Inside admin server functions, use getAdminRequestContext() instead — see Actors and RequestContext.

→ Actors and RequestContext

4. Recipe — owner-only drafts

Anyone with read sees published documents. Authors additionally see their own drafts. Editors with a broader ability see everything.

Edit: the collection schema — e.g. apps/webapp/byline/collections/posts/schema.ts.

import { defineCollection } from '@byline/core'

export const Posts = defineCollection({
  path: 'posts',
  fields: [/* … includes authorId */],
  hooks: {
    beforeRead: ({ requestContext }) => {
      if (requestContext.actor?.hasAbility('collections.posts.read.any')) return
      return {
        $or: [
          { status: 'published' },
          { status: 'draft', authorId: requestContext.actor?.id ?? '__none__' },
        ],
      }
    },
  },
})

The fallback '__none__' collapses cleanly when actor is absent — anonymous readers get the published-only branch.

→ Read-side scoping — beforeRead

5. Recipe — multi-tenant scoping

Every document belongs to a tenant. Every read clamps to the actor's tenant — full stop, no ability needed. Deny-by-default.