@byline/admin 2.4.0 → 2.4.2

package/dist/vendor/noble-argon2/utils.js.LICENSE.txt

@@ -0,0 +1 @@
+/*! noble-hashes - MIT License (c) 2022 Paul Miller (paulmillr.com) */

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/admin",
   "private": false,
   "license": "MPL-2.0",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -28,6 +28,9 @@
   "main": "dist/index.js",
   "index": "dist/index.js",
   "types": "dist/index.d.ts",
+  "sideEffects": [
+    "**/*.css"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -59,28 +62,104 @@
       "import": "./dist/modules/admin-account/index.js",
       "require": "./dist/modules/admin-account/index.js"
     },
+    "./services": {
+      "types": "./dist/services/admin-services-context.d.ts",
+      "import": "./dist/services/admin-services-context.js",
+      "require": "./dist/services/admin-services-context.js"
+    },
+    "./admin-users/components/create": {
+      "types": "./dist/modules/admin-users/components/create.d.ts",
+      "import": "./dist/modules/admin-users/components/create.js",
+      "require": "./dist/modules/admin-users/components/create.js"
+    },
+    "./admin-users/components/update": {
+      "types": "./dist/modules/admin-users/components/update.d.ts",
+      "import": "./dist/modules/admin-users/components/update.js",
+      "require": "./dist/modules/admin-users/components/update.js"
+    },
+    "./admin-users/components/roles": {
+      "types": "./dist/modules/admin-users/components/roles.d.ts",
+      "import": "./dist/modules/admin-users/components/roles.js",
+      "require": "./dist/modules/admin-users/components/roles.js"
+    },
+    "./admin-users/components/set-password": {
+      "types": "./dist/modules/admin-users/components/set-password.d.ts",
+      "import": "./dist/modules/admin-users/components/set-password.js",
+      "require": "./dist/modules/admin-users/components/set-password.js"
+    },
+    "./admin-roles/components/create": {
+      "types": "./dist/modules/admin-roles/components/create.d.ts",
+      "import": "./dist/modules/admin-roles/components/create.js",
+      "require": "./dist/modules/admin-roles/components/create.js"
+    },
+    "./admin-roles/components/update": {
+      "types": "./dist/modules/admin-roles/components/update.d.ts",
+      "import": "./dist/modules/admin-roles/components/update.js",
+      "require": "./dist/modules/admin-roles/components/update.js"
+    },
+    "./admin-roles/components/permissions": {
+      "types": "./dist/modules/admin-roles/components/permissions.d.ts",
+      "import": "./dist/modules/admin-roles/components/permissions.js",
+      "require": "./dist/modules/admin-roles/components/permissions.js"
+    },
+    "./admin-permissions/components/inspector": {
+      "types": "./dist/modules/admin-permissions/components/inspector.d.ts",
+      "import": "./dist/modules/admin-permissions/components/inspector.js",
+      "require": "./dist/modules/admin-permissions/components/inspector.js"
+    },
+    "./admin-account/components/container": {
+      "types": "./dist/modules/admin-account/components/container.d.ts",
+      "import": "./dist/modules/admin-account/components/container.js",
+      "require": "./dist/modules/admin-account/components/container.js"
+    },
+    "./admin-account/components/update": {
+      "types": "./dist/modules/admin-account/components/update.d.ts",
+      "import": "./dist/modules/admin-account/components/update.js",
+      "require": "./dist/modules/admin-account/components/update.js"
+    },
+    "./admin-account/components/change-password": {
+      "types": "./dist/modules/admin-account/components/change-password.d.ts",
+      "import": "./dist/modules/admin-account/components/change-password.js",
+      "require": "./dist/modules/admin-account/components/change-password.js"
+    },
+    "./auth/components/sign-in-form": {
+      "types": "./dist/modules/auth/components/sign-in-form.d.ts",
+      "import": "./dist/modules/auth/components/sign-in-form.js",
+      "require": "./dist/modules/auth/components/sign-in-form.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist/",
+    "src/"
   ],
   "dependencies": {
+    "@tanstack/react-form-start": "^1.32.0",
+    "classnames": "^2.5.1",
     "jose": "^6.2.3",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "2.4.0",
-    "@byline/core": "2.4.0"
+    "@byline/auth": "2.4.2",
+    "@byline/core": "2.4.2",
+    "@byline/ui": "2.4.2"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",
+    "@rsbuild/plugin-react": "^2.0.0",
+    "@rslib/core": "^0.21.5",
     "@types/node": "^25.9.1",
-    "chokidar": "^5.0.0",
-    "chokidar-cli": "^3.0.0",
-    "npm-run-all": "^4.1.5",
+    "@types/react": "19.2.15",
+    "@types/react-dom": "19.2.3",
+    "react": "19.2.6",
+    "react-dom": "19.2.6",
     "rimraf": "^6.1.3",
-    "tsc-alias": "^1.8.17",
     "tsx": "^4.22.3",
     "typescript": "6.0.3",
+    "typescript-plugin-css-modules": "^5.2.0",
     "vitest": "^4.1.7"
   },
   "publishConfig": {
@@ -89,8 +168,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "dev": "chokidar 'src/**/*' -c 'npm-run-all build'",
-    "build": "tsc -p tsconfig.json && tsc-alias",
+    "dev": "rslib build --watch",
+    "build": "rslib build",
     "clean": "node scripts/clean.js node_modules dist build .turbo",
     "lint": "biome check --write --unsafe --diagnostic-level=error",
     "test": "vitest run --mode=node",

package/src/abilities.ts

@@ -0,0 +1,32 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { AbilityRegistry } from '@byline/auth'
+
+import { registerAdminPermissionsAbilities } from './modules/admin-permissions/abilities.js'
+import { registerAdminRolesAbilities } from './modules/admin-roles/abilities.js'
+import { registerAdminUsersAbilities } from './modules/admin-users/abilities.js'
+
+/**
+ * Register every ability contributed by the admin subsystem.
+ *
+ * Called once at `initBylineCore()` time from the webapp config. Each
+ * admin module contributes its own registrar (`registerAdminUsersAbilities`,
+ * `registerAdminRolesAbilities`, …); this function fans out to them so
+ * the webapp wiring stays a single line.
+ *
+ * Admin does not self-register from core to keep the `@byline/core`
+ * package free of a dependency on `@byline/admin` — the registration
+ * call is an opt-in at the composition root.
+ */
+export function registerAdminAbilities(registry: AbilityRegistry): void {
+  registerAdminUsersAbilities(registry)
+  registerAdminRolesAbilities(registry)
+  registerAdminPermissionsAbilities(registry)
+  // registerAccountAbilities(registry) — added when that module lands
+}

package/src/declarations.d.ts

@@ -0,0 +1,4 @@
+declare module '*.css' {
+  const classes: { [key: string]: string }
+  export default classes
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * `@byline/admin` — the admin subsystem.
+ *
+ * Concrete implementation of the admin side of Byline: admin users,
+ * roles, permissions, account self-service, and the built-in JWT
+ * session provider. Depends on `@byline/auth` (the Actor / RequestContext
+ * / SessionProvider contract) and `@byline/core` (collection and lifecycle
+ * machinery). Third-party session providers (Lucia, WorkOS, Clerk, SSO)
+ * are intentionally kept out of this package — they live as separate
+ * adapters against `@byline/auth` directly.
+ *
+ * Prefer the per-module subpath exports (`@byline/admin/admin-users`,
+ * `@byline/admin/auth`, etc.) over the root barrel; this root exists so
+ * the package is importable as a single unit when that is convenient.
+ */
+
+export { registerAdminAbilities } from './abilities.js'
+export { assertAdminActor, requireAdminActor } from './lib/assert-admin-actor.js'
+export {
+  type Command,
+  type CreateCommandAuthSpec,
+  type CreateCommandHandlerArgs,
+  type CreateCommandSpec,
+  createCommand,
+} from './lib/create-command.js'
+export * from './modules/admin-account/index.js'
+export * from './modules/admin-permissions/index.js'
+export * from './modules/admin-roles/index.js'
+export * from './modules/admin-users/index.js'
+export * from './modules/auth/index.js'
+export type { AdminStore } from './store.js'

package/src/lib/assert-admin-actor.ts

@@ -0,0 +1,90 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { type AdminAuth, ERR_UNAUTHENTICATED, isAdminAuth, type RequestContext } from '@byline/auth'
+
+/**
+ * Gate every admin command behind three checks, in order:
+ *
+ *   1. `context` exists. No in-process call may reach an admin command
+ *      without threading a `RequestContext` — seeds/tests pass
+ *      `createSuperAdminContext()`.
+ *   2. `context.actor` is an `AdminAuth`. Anonymous admin calls are
+ *      rejected outright — admin actions are never public. A `UserAuth`
+ *      (end-user identity) also fails here: it may sign in against the
+ *      app realm, but it does not have an admin identity.
+ *   3. The actor holds the required ability. `AdminAuth.assertAbility`
+ *      short-circuits on `isSuperAdmin: true`; otherwise the flat
+ *      ability set is consulted.
+ *
+ * Returns the narrowed `AdminAuth` so callers can use it without a
+ * second type guard — the typical shape is:
+ *
+ *   ```ts
+ *   export async function deleteAdminUserCommand(context, input, deps) {
+ *     const parsed = deleteAdminUserRequestSchema.parse(input)
+ *     const actor = assertAdminActor(context, ADMIN_USERS_ABILITIES.delete)
+ *     return service.deleteUser(actor, parsed)
+ *   }
+ *   ```
+ *
+ * The three failures produce distinct error codes:
+ *   - missing context / missing actor / wrong actor type → `ERR_UNAUTHENTICATED`
+ *   - ability missing                                    → `ERR_FORBIDDEN`
+ *     (thrown from `AdminAuth.assertAbility`)
+ */
+export function assertAdminActor(context: RequestContext | undefined, ability: string): AdminAuth {
+  const actor = requireAdminActor(context, `admin action requiring '${ability}'`)
+  actor.assertAbility(ability)
+  return actor
+}
+
+/**
+ * Authentication-only counterpart of `assertAdminActor`. Runs the same
+ * three checks (context present, actor present, actor is `AdminAuth`)
+ * but **does not** assert any ability key.
+ *
+ * Used by self-service commands where the actor is the target by
+ * definition — `@byline/admin/admin-account` for "change my own
+ * password" / "update my own profile". For those flows there is no
+ * meaningful ability to gate against; the security property is "you
+ * may only mutate your own row," and the commands enforce that by
+ * sourcing the target id from `actor.id` rather than from the
+ * request payload.
+ *
+ * Reasoning is described as part of the request narrative so the
+ * `ERR_UNAUTHENTICATED` message stays useful when it surfaces in logs
+ * — the helper has no `ability` argument to fall back on.
+ */
+export function requireAdminActor(
+  context: RequestContext | undefined,
+  reasonForLog: string
+): AdminAuth {
+  if (!context) {
+    throw ERR_UNAUTHENTICATED({
+      message:
+        `missing requestContext on ${reasonForLog}. Pass createSuperAdminContext() ` +
+        `from @byline/auth for scripts/tests, or construct a request-scoped context from your ` +
+        `session provider in the admin webapp.`,
+    })
+  }
+
+  const { actor } = context
+  if (actor == null) {
+    throw ERR_UNAUTHENTICATED({
+      message: `anonymous caller cannot perform ${reasonForLog}`,
+    })
+  }
+  if (!isAdminAuth(actor)) {
+    throw ERR_UNAUTHENTICATED({
+      message: `non-admin actor cannot perform ${reasonForLog}`,
+    })
+  }
+
+  return actor
+}

package/src/lib/create-command.ts

@@ -0,0 +1,109 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type { AdminAuth, RequestContext } from '@byline/auth'
+import type { ZodType } from 'zod'
+
+import { assertAdminActor, requireAdminActor } from './assert-admin-actor.js'
+
+/**
+ * `createCommand` — the wrapper that folds the four-step admin command
+ * contract (validate → authorise → invoke → shape) into a single
+ * declaration.
+ *
+ * Implements Phase 1 of `docs/CORE-COMPOSITION.md`. Today's scope is
+ * `@byline/admin`-internal: it gates against admin actor identity using
+ * the existing `assertAdminActor` / `requireAdminActor` helpers, which
+ * inherit the super-admin bypass from `AdminAuth.assertAbility`.
+ *
+ * The `auth` slot is a discriminated union:
+ *
+ *   - `{ ability }`         — full admin gate. Requires an `AdminAuth`
+ *                             actor holding the named ability. Maps to
+ *                             `assertAdminActor`.
+ *   - `{ authenticated }`   — identity gate only. Requires an `AdminAuth`
+ *                             actor but does not assert any ability. Used
+ *                             by self-service commands in `admin-account`
+ *                             where the security property is "you may
+ *                             only mutate your own row" and the target
+ *                             id is sourced from `actor.id`.
+ *
+ * The handler receives an args object so it can cherry-pick what it
+ * needs without positional ordering — `context` for downstream calls
+ * that need the full request context, `input` (already Zod-parsed),
+ * `deps` (typed by the module), and `actor` (already narrowed to
+ * `AdminAuth` by the auth step).
+ *
+ * The returned command preserves today's `(context, input, deps) =>
+ * Promise<Output>` signature so existing server-fn call sites keep
+ * working without change.
+ *
+ * Collection-document operations (create / update / delete / status /
+ * upload) are gated through a separate helper, `assertActorCanPerform`,
+ * which fires inside the `document-lifecycle` service functions in
+ * `@byline/core`. They do not flow through this wrapper today; if the
+ * two enforcement paths ever converge, the `auth` discriminator can
+ * grow a `collection` variant without breaking existing call sites.
+ */
+
+export type CreateCommandAuthSpec =
+  | { readonly ability: string; readonly authenticated?: never }
+  | { readonly authenticated: true; readonly ability?: never }
+
+export interface CreateCommandHandlerArgs<TInput, TDeps> {
+  readonly context: RequestContext
+  readonly input: TInput
+  readonly deps: TDeps
+  readonly actor: AdminAuth
+}
+
+export interface CreateCommandSpec<TInput, TOutput, TDeps> {
+  /**
+   * Stable identifier for the command, used in error messages and
+   * future telemetry (Phase 1 of `CORE-COMPOSITION.md` calls out
+   * uniform logging as a downstream benefit of the wrapper).
+   */
+  readonly method: string
+  readonly auth: CreateCommandAuthSpec
+  readonly schemas: {
+    readonly input: ZodType<TInput>
+    readonly output: ZodType<TOutput>
+  }
+  readonly handler: (args: CreateCommandHandlerArgs<TInput, TDeps>) => Promise<TOutput> | TOutput
+}
+
+export type Command<_TInput, TOutput, TDeps> = (
+  context: RequestContext | undefined,
+  input: unknown,
+  deps: TDeps
+) => Promise<TOutput>
+
+export function createCommand<TInput, TOutput, TDeps>(
+  spec: CreateCommandSpec<TInput, TOutput, TDeps>
+): Command<TInput, TOutput, TDeps> {
+  return async function command(
+    context: RequestContext | undefined,
+    input: unknown,
+    deps: TDeps
+  ): Promise<TOutput> {
+    const parsed = spec.schemas.input.parse(input ?? {}) as TInput
+    const actor =
+      spec.auth.ability !== undefined
+        ? assertAdminActor(context, spec.auth.ability)
+        : requireAdminActor(context, spec.method)
+    // `context` is non-null after the auth step — both helpers throw
+    // `ERR_UNAUTHENTICATED` when the request context is missing.
+    const result = await spec.handler({
+      context: context as RequestContext,
+      input: parsed,
+      deps,
+      actor,
+    })
+    return spec.schemas.output.parse(result) as TOutput
+  }
+}

package/src/modules/admin-account/commands.ts

@@ -0,0 +1,76 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { type Command, createCommand } from '../../lib/create-command.js'
+import { adminUserResponseSchema } from '../admin-users/schemas.js'
+import {
+  changeAccountPasswordRequestSchema,
+  getAccountRequestSchema,
+  updateAccountRequestSchema,
+} from './schemas.js'
+import { AdminAccountService } from './service.js'
+import type { AdminStore } from '../../store.js'
+import type {
+  AccountResponse,
+  ChangeAccountPasswordRequest,
+  GetAccountRequest,
+  UpdateAccountRequest,
+} from './schemas.js'
+
+/**
+ * Transport-agnostic commands for admin-account self-service.
+ *
+ * Same `createCommand` shape as the other admin modules, with one
+ * deliberate difference: `auth` is `{ authenticated: true }` rather than
+ * `{ ability }`. There is no ability key to gate against — the security
+ * property is "you may only mutate your own row," enforced structurally
+ * by sourcing the target id from `actor.id` rather than from the request
+ * payload. The request schemas do not accept an `id` field, so a caller
+ * has no way to express "operate on someone else."
+ */
+
+export interface AdminAccountCommandDeps {
+  store: AdminStore
+}
+
+function serviceOf(deps: AdminAccountCommandDeps): AdminAccountService {
+  return new AdminAccountService({ repo: deps.store.adminUsers })
+}
+
+export const getAccountCommand: Command<
+  GetAccountRequest,
+  AccountResponse,
+  AdminAccountCommandDeps
+> = createCommand({
+  method: 'getAccount',
+  auth: { authenticated: true },
+  schemas: { input: getAccountRequestSchema, output: adminUserResponseSchema },
+  handler: ({ deps, actor }) => serviceOf(deps).getAccount(actor.id),
+})
+
+export const updateAccountCommand: Command<
+  UpdateAccountRequest,
+  AccountResponse,
+  AdminAccountCommandDeps
+> = createCommand({
+  method: 'updateAccount',
+  auth: { authenticated: true },
+  schemas: { input: updateAccountRequestSchema, output: adminUserResponseSchema },
+  handler: ({ input, deps, actor }) => serviceOf(deps).updateAccount(actor.id, input),
+})
+
+export const changeAccountPasswordCommand: Command<
+  ChangeAccountPasswordRequest,
+  AccountResponse,
+  AdminAccountCommandDeps
+> = createCommand({
+  method: 'changeAccountPassword',
+  auth: { authenticated: true },
+  schemas: { input: changeAccountPasswordRequestSchema, output: adminUserResponseSchema },
+  handler: ({ input, deps, actor }) => serviceOf(deps).changePassword(actor.id, input),
+})

package/src/modules/admin-account/components/change-password.module.css

@@ -0,0 +1,40 @@
+/**
+ * ChangeAccountPassword — self-service password-change form (drawer body).
+ *
+ * Override handles:
+ *   .byline-account-change-password-wrap     — outer container
+ *   .byline-account-change-password-form     — vertical-stack form element
+ *   .byline-account-change-password-actions  — Cancel/Save row
+ *   .byline-account-change-password-action   — buttons in the actions row
+ */
+
+.wrap,
+:global(.byline-account-change-password-wrap) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-8);
+  padding: var(--spacing-4);
+  margin-top: var(--spacing-4);
+}
+
+.form,
+:global(.byline-account-change-password-form) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-16);
+  padding-top: var(--spacing-8);
+}
+
+.actions,
+:global(.byline-account-change-password-actions) {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--spacing-8);
+  margin-top: var(--spacing-16);
+}
+
+.action,
+:global(.byline-account-change-password-action) {
+  min-width: 4rem;
+}