@byline/admin 2.4.0 → 2.4.1

package/src/modules/auth/components/sign-in-form.module.css

@@ -0,0 +1,62 @@
+/**
+ * SignInForm — admin sign-in card form.
+ *
+ * Override handles:
+ *   .byline-sign-in-card      — outer Card (responsive width)
+ *   .byline-sign-in-alert     — error alert spacing
+ *   .byline-sign-in-form      — the form element
+ *   .byline-sign-in-fields    — vertical stack of inputs
+ *   .byline-sign-in-actions   — action row (optional Home link + submit button)
+ *   .byline-sign-in-home-link — left-side "Home" link (rendered when homeUrl is set)
+ *   .byline-sign-in-button    — the submit button (min-width)
+ */
+
+.card,
+:global(.byline-sign-in-card) {
+  width: 100%;
+}
+
+@media (min-width: 40rem) {
+  .card,
+  :global(.byline-sign-in-card) {
+    max-width: 380px;
+  }
+}
+
+.alert,
+:global(.byline-sign-in-alert) {
+  margin-top: var(--spacing-12);
+}
+
+.form,
+:global(.byline-sign-in-form) {
+  padding-top: var(--spacing-8);
+  margin-bottom: var(--spacing-8);
+}
+
+.fields,
+:global(.byline-sign-in-fields) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-16);
+}
+
+.actions,
+:global(.byline-sign-in-actions) {
+  display: flex;
+  align-items: center;
+  margin-top: var(--spacing-24);
+}
+
+.home-link,
+:global(.byline-sign-in-home-link) {
+  font-size: 0.9rem;
+  text-decoration: underline;
+}
+
+.button,
+:global(.byline-sign-in-button) {
+  min-width: 5rem;
+  /* Always floats right whether or not a Home link is present on the left. */
+  margin-left: auto;
+}

package/src/modules/auth/components/sign-in-form.tsx

@@ -0,0 +1,132 @@
+'use client'
+
+/**
+ * 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
+ */
+
+/**
+ * Admin sign-in form.
+ *
+ * Client component — collects email + password, calls the `adminSignIn`
+ * server fn, and on success navigates to the caller-supplied
+ * `callbackUrl` (or `/admin`). On failure renders a generic "Invalid
+ * credentials" alert; the provider equalises timing between
+ * unknown-email and wrong-password so the UI doesn't distinguish the two.
+ *
+ * Stable override handles: `.byline-sign-in-card`, `.byline-sign-in-alert`,
+ * `.byline-sign-in-form`, `.byline-sign-in-fields`,
+ * `.byline-sign-in-actions`, `.byline-sign-in-button`,
+ * `.byline-sign-in-home-link`.
+ */
+
+import { type FormEvent, useState } from 'react'
+
+import { Alert, Button, Card, Input, LoaderEllipsis } from '@byline/ui/react'
+import cx from 'classnames'
+
+import { useBylineAdminServices } from '../../../services/admin-services-context.js'
+import styles from './sign-in-form.module.css'
+
+interface SignInFormProps {
+  /** Destination after successful sign-in. Defaults to `/admin`. */
+  callbackUrl?: string
+  /**
+   * Optional plain "Home" link rendered on the left of the action row.
+   * Typically the host's configured `serverURL` so signed-out admins can
+   * navigate back to the public site without typing the URL.
+   */
+  homeUrl?: string
+}
+
+export function SignInForm({ callbackUrl, homeUrl }: SignInFormProps) {
+  const { adminSignIn } = useBylineAdminServices()
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [pending, setPending] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault()
+    if (pending) return
+    if (email.trim().length === 0 || password.length === 0) {
+      setError('Enter your email and password.')
+      return
+    }
+
+    setPending(true)
+    setError(null)
+    try {
+      await adminSignIn({ data: { email: email.trim(), password } })
+      const target = callbackUrl && callbackUrl.length > 0 ? callbackUrl : '/admin'
+      // Full-page navigation — the admin layout needs to re-run its
+      // `beforeLoad` guard against the freshly-set session cookies.
+      window.location.assign(target)
+    } catch (err) {
+      console.warn('sign-in failed', err)
+      setError('Invalid credentials.')
+      setPending(false)
+    }
+  }
+
+  return (
+    <Card className={cx('byline-sign-in-card', styles.card)}>
+      <Card.Header>
+        <Card.Title>
+          <h2>Sign in</h2>
+        </Card.Title>
+        <Card.Description>Sign in to the Byline admin.</Card.Description>
+        {error && (
+          <Alert intent="danger" className={cx('byline-sign-in-alert', styles.alert)}>
+            {error}
+          </Alert>
+        )}
+      </Card.Header>
+      <Card.Content>
+        <form onSubmit={handleSubmit} noValidate className={cx('byline-sign-in-form', styles.form)}>
+          <div className={cx('byline-sign-in-fields', styles.fields)}>
+            <Input
+              label="Email"
+              id="email"
+              name="email"
+              type="email"
+              autoComplete="email"
+              required
+              value={email}
+              onChange={(event) => setEmail(event.currentTarget.value)}
+              disabled={pending}
+            />
+            <Input
+              label="Password"
+              id="password"
+              name="password"
+              type="password"
+              autoComplete="current-password"
+              required
+              value={password}
+              onChange={(event) => setPassword(event.currentTarget.value)}
+              disabled={pending}
+            />
+          </div>
+          <div className={cx('byline-sign-in-actions', styles.actions)}>
+            {homeUrl && (
+              <a href={homeUrl} className={cx('byline-sign-in-home-link', styles['home-link'])}>
+                Home
+              </a>
+            )}
+            <Button
+              type="submit"
+              disabled={pending}
+              className={cx('byline-sign-in-button', styles.button)}
+            >
+              {pending ? <LoaderEllipsis size={30} color="#aaaaaa" /> : <span>Sign In</span>}
+            </Button>
+          </div>
+        </form>
+      </Card.Content>
+    </Card>
+  )
+}

package/src/modules/auth/index.ts

@@ -0,0 +1,31 @@
+/**
+ * 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/auth` — session handling for the built-in admin realm.
+ *
+ * Hosts the reference `JwtSessionProvider` and the sign-in / refresh /
+ * revoke orchestration that consumes it, along with password hashing
+ * (`hashPassword` / `verifyPassword`) and the `RefreshTokensRepository`
+ * contract the provider drives.
+ *
+ * The `SessionProvider` **interface** lives in `@byline/auth` so the
+ * pluggability contract stays narrow; this module supplies the
+ * Byline-native implementation. Third-party providers (Lucia, WorkOS,
+ * Clerk, institutional SSO) should be shipped as separate packages
+ * against `@byline/auth` rather than added here.
+ */
+
+export { JwtSessionProvider, type JwtSessionProviderConfig } from './jwt-session-provider.js'
+export { hashPassword, verifyPassword } from './password.js'
+export { resolveActor } from './resolve-actor.js'
+export type {
+  IssueRefreshTokenInput,
+  RefreshTokenRow,
+  RefreshTokensRepository,
+} from './refresh-tokens-repository.js'

package/src/modules/auth/jwt-session-provider.ts

@@ -0,0 +1,301 @@
+/**
+ * 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 { createHash, randomBytes, randomUUID } from 'node:crypto'
+
+import {
+  type AccessTokenPayload,
+  type AdminAuth,
+  ERR_ACCOUNT_DISABLED,
+  ERR_INVALID_CREDENTIALS,
+  ERR_INVALID_TOKEN,
+  ERR_REVOKED_TOKEN,
+  type RefreshSessionArgs,
+  type SessionProvider,
+  type SessionProviderCapabilities,
+  type SessionTokens,
+  type SignInResult,
+  type SignInWithPasswordArgs,
+} from '@byline/auth'
+import { jwtVerify, SignJWT } from 'jose'
+import { v7 as uuidv7 } from 'uuid'
+
+import { verifyPassword } from './password.js'
+import { resolveActor } from './resolve-actor.js'
+import type { AdminStore } from '../../store.js'
+
+const DEFAULT_ISSUER = 'byline'
+const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 15 * 60 // 15 minutes
+const DEFAULT_REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60 // 30 days
+
+const CAPABILITIES: SessionProviderCapabilities = {
+  passwordChange: true,
+  magicLink: false,
+  sso: false,
+}
+
+export interface JwtSessionProviderConfig {
+  /**
+   * Adapter-backed admin repositories. Construct via the DB adapter's
+   * admin-store factory (e.g. `createAdminStore(db)` from
+   * `@byline/db-postgres/admin`) and pass the result in — the provider
+   * does not touch Drizzle or any other adapter-specific API directly.
+   */
+  store: AdminStore
+  /**
+   * HMAC-SHA256 signing secret. Must be at least 32 bytes (256 bits) of
+   * entropy. Load from a secret manager — never hard-code.
+   *
+   * To switch to asymmetric signing (RS256/EdDSA), swap out this provider
+   * for a custom one backed by `jose` key objects.
+   */
+  signingSecret: string | Uint8Array
+  /** Issuer claim (`iss`) on access tokens. Defaults to `'byline'`. */
+  issuer?: string
+  /** Access-token lifetime in seconds. Default 15 min. */
+  accessTokenTtlSeconds?: number
+  /** Refresh-token lifetime in seconds. Default 30 days. */
+  refreshTokenTtlSeconds?: number
+  /** Clock reference — override for deterministic tests. */
+  now?: () => Date
+}
+
+export class JwtSessionProvider implements SessionProvider {
+  public readonly capabilities = CAPABILITIES
+
+  readonly #store: AdminStore
+  readonly #signingKey: Uint8Array
+  readonly #issuer: string
+  readonly #accessTtl: number
+  readonly #refreshTtl: number
+  readonly #now: () => Date
+
+  constructor(config: JwtSessionProviderConfig) {
+    this.#store = config.store
+    this.#signingKey =
+      typeof config.signingSecret === 'string'
+        ? new TextEncoder().encode(config.signingSecret)
+        : config.signingSecret
+    if (this.#signingKey.byteLength < 32) {
+      throw new Error(
+        'JwtSessionProvider: signingSecret must carry at least 32 bytes of entropy (256 bits)'
+      )
+    }
+    this.#issuer = config.issuer ?? DEFAULT_ISSUER
+    this.#accessTtl = config.accessTokenTtlSeconds ?? DEFAULT_ACCESS_TOKEN_TTL_SECONDS
+    this.#refreshTtl = config.refreshTokenTtlSeconds ?? DEFAULT_REFRESH_TOKEN_TTL_SECONDS
+    this.#now = config.now ?? (() => new Date())
+  }
+
+  // -----------------------------------------------------------------------
+  // SessionProvider
+  // -----------------------------------------------------------------------
+
+  async signInWithPassword(args: SignInWithPasswordArgs): Promise<SignInResult> {
+    const users = this.#store.adminUsers
+    const row = await users.getByEmailForSignIn(args.email)
+
+    // Uniform error response for unknown email vs. wrong password — don't
+    // leak which one. Still do a real verify against a dummy hash so the
+    // timing is comparable; the argon2 cost dominates regardless.
+    if (!row) {
+      await verifyPassword(args.password, DUMMY_HASH_FOR_TIMING)
+      throw ERR_INVALID_CREDENTIALS({ message: 'invalid credentials' })
+    }
+
+    const ok = await verifyPassword(args.password, row.password_hash)
+    if (!ok) {
+      await users.recordLoginFailure(row.id)
+      throw ERR_INVALID_CREDENTIALS({ message: 'invalid credentials' })
+    }
+
+    if (!row.is_enabled) {
+      throw ERR_ACCOUNT_DISABLED({ message: 'account disabled' })
+    }
+
+    await users.recordLoginSuccess(row.id, args.ip ?? null)
+
+    const actor = await resolveActor(this.#store, row.id)
+    // resolveActor also checks is_enabled, but we just recorded success
+    // above, so null here would indicate a race (the account was disabled
+    // between the check and the resolve). Treat as disabled.
+    if (!actor) {
+      throw ERR_ACCOUNT_DISABLED({ message: 'account disabled' })
+    }
+
+    const tokens = await this.#issueTokens({
+      adminUserId: row.id,
+      ip: args.ip ?? null,
+      userAgent: args.userAgent ?? null,
+    })
+
+    return { ...tokens, actor }
+  }
+
+  async verifyAccessToken(token: string): Promise<{ actor: AdminAuth }> {
+    let payload: AccessTokenPayload
+    try {
+      const result = await jwtVerify<AccessTokenPayload>(token, this.#signingKey, {
+        issuer: this.#issuer,
+      })
+      payload = result.payload
+    } catch (err) {
+      throw ERR_INVALID_TOKEN({ message: 'access token verification failed', cause: err })
+    }
+
+    if (payload.typ !== 'access') {
+      throw ERR_INVALID_TOKEN({ message: 'unexpected token type' })
+    }
+
+    const actor = await resolveActor(this.#store, payload.sub)
+    if (!actor) {
+      // The token was valid but the user is now disabled or deleted.
+      throw ERR_ACCOUNT_DISABLED({ message: 'account disabled or deleted' })
+    }
+
+    return { actor }
+  }
+
+  async refreshSession(args: RefreshSessionArgs): Promise<SessionTokens> {
+    const refreshTokens = this.#store.refreshTokens
+    const hash = hashToken(args.refreshToken)
+    const row = await refreshTokens.findByHash(hash)
+
+    if (!row) {
+      throw ERR_INVALID_TOKEN({ message: 'refresh token not recognised' })
+    }
+
+    const now = this.#now()
+
+    // Already revoked?
+    if (row.revoked_at != null) {
+      if (row.rotated_to_id != null) {
+        // Rotated token replayed — the chain is compromised. Revoke every
+        // descendant so the attacker and the legitimate holder are both
+        // signed out.
+        await refreshTokens.revokeChain(row.id, now)
+        throw ERR_REVOKED_TOKEN({
+          message: 'refresh token was already rotated — chain revoked',
+        })
+      }
+      throw ERR_REVOKED_TOKEN({ message: 'refresh token has been revoked' })
+    }
+
+    if (row.expires_at.getTime() <= now.getTime()) {
+      throw ERR_INVALID_TOKEN({ message: 'refresh token expired' })
+    }
+
+    // Rotate: mint a new token, mark the old one rotated_to the new id.
+    const newId = uuidv7()
+    const newRefreshPlain = generateOpaqueToken()
+    const newRefreshHash = hashToken(newRefreshPlain)
+    const refreshExpiresAt = new Date(now.getTime() + this.#refreshTtl * 1000)
+
+    await refreshTokens.issue({
+      id: newId,
+      admin_user_id: row.admin_user_id,
+      token_hash: newRefreshHash,
+      expires_at: refreshExpiresAt,
+      user_agent: args.userAgent ?? null,
+      ip: args.ip ?? null,
+    })
+    await refreshTokens.markRotated(row.id, newId, now)
+
+    const accessToken = await this.#signAccessToken(row.admin_user_id, now)
+    const accessExpiresAt = new Date(now.getTime() + this.#accessTtl * 1000)
+
+    return {
+      accessToken,
+      refreshToken: newRefreshPlain,
+      accessTokenExpiresAt: accessExpiresAt,
+      refreshTokenExpiresAt: refreshExpiresAt,
+    }
+  }
+
+  async revokeSession(refreshToken: string): Promise<void> {
+    const refreshTokens = this.#store.refreshTokens
+    const row = await refreshTokens.findByHash(hashToken(refreshToken))
+    if (!row) return // Idempotent — unknown tokens are a no-op.
+    await refreshTokens.revoke(row.id, this.#now())
+  }
+
+  async resolveActor(adminUserId: string): Promise<AdminAuth | null> {
+    return resolveActor(this.#store, adminUserId)
+  }
+
+  // -----------------------------------------------------------------------
+  // Internals
+  // -----------------------------------------------------------------------
+
+  async #issueTokens(input: {
+    adminUserId: string
+    ip: string | null
+    userAgent: string | null
+  }): Promise<SessionTokens> {
+    const now = this.#now()
+    const refreshTokens = this.#store.refreshTokens
+
+    const accessToken = await this.#signAccessToken(input.adminUserId, now)
+    const accessExpiresAt = new Date(now.getTime() + this.#accessTtl * 1000)
+
+    const refreshPlain = generateOpaqueToken()
+    const refreshHash = hashToken(refreshPlain)
+    const refreshExpiresAt = new Date(now.getTime() + this.#refreshTtl * 1000)
+    await refreshTokens.issue({
+      id: uuidv7(),
+      admin_user_id: input.adminUserId,
+      token_hash: refreshHash,
+      expires_at: refreshExpiresAt,
+      user_agent: input.userAgent,
+      ip: input.ip,
+    })
+
+    return {
+      accessToken,
+      refreshToken: refreshPlain,
+      accessTokenExpiresAt: accessExpiresAt,
+      refreshTokenExpiresAt: refreshExpiresAt,
+    }
+  }
+
+  async #signAccessToken(adminUserId: string, now: Date): Promise<string> {
+    const iat = Math.floor(now.getTime() / 1000)
+    const exp = iat + this.#accessTtl
+    return new SignJWT({ typ: 'access' })
+      .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
+      .setSubject(adminUserId)
+      .setIssuer(this.#issuer)
+      .setIssuedAt(iat)
+      .setExpirationTime(exp)
+      .setJti(randomUUID())
+      .sign(this.#signingKey)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+/** 32 bytes of randomness, base64url-encoded. ~43 chars on the wire. */
+function generateOpaqueToken(): string {
+  return randomBytes(32).toString('base64url')
+}
+
+/** SHA-256 hex digest of the raw refresh-token string. */
+function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex')
+}
+
+/**
+ * A stable argon2id hash used only to equalise sign-in timing on the
+ * unknown-email code path. The plaintext here is arbitrary — we never
+ * succeed against it. This is pre-generated at module-load time so the
+ * first sign-in call doesn't pay the generation cost.
+ */
+const DUMMY_HASH_FOR_TIMING =
+  '$argon2id$v=19$m=19456,t=2,p=1$c2lkZS1jaGFubmVsLW1pdGlnYXRpb24$0Hqf2vQKZqSfZZ4nJRr7K5IOjn9ngjzaQjV+yTG6iNY'

package/src/modules/auth/password.ts

@@ -0,0 +1,94 @@
+/**
+ * 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
+ */
+
+/**
+ * Password hashing — argon2id via the vendored `@noble/hashes` copy at
+ * `../../vendor/noble-argon2/`. Pure-JS, runs anywhere with a modern JS
+ * runtime (Node, Workers, Deno, Bun, browsers).
+ *
+ * Stores the full PHC string (`$argon2id$v=19$m=…$…$…`) in the
+ * `byline_admin_users.password` column. That makes the algorithm and
+ * parameters self-describing, so upgrading params later (or migrating off
+ * argon2id entirely) is a straightforward re-hash on next successful sign-in.
+ *
+ * Defaults follow OWASP 2023 guidance for argon2id: memory 19 MiB,
+ * iterations 2, parallelism 1. These are reasonable for typical server
+ * hardware; tune if sign-in latency becomes a concern under load.
+ *
+ * Note: pure-JS argon2id is meaningfully slower than the previous
+ * `@node-rs/argon2` Rust binding (~50–150 ms vs ~10 ms at these params on
+ * modern server hardware). For interactive sign-in this is fine; for
+ * high-throughput auth services consider tuning `HASH_OPTIONS` or
+ * reintroducing a native binding behind a runtime-feature check.
+ */
+
+import { argon2idAsync } from '../../vendor/noble-argon2/argon2.js'
+import { decodeArgon2idPhc, encodeArgon2idPhc, timingSafeEqual } from './phc.js'
+
+/** Argon2id cost parameters. Matches the prior `@node-rs/argon2` defaults. */
+const HASH_OPTIONS = {
+  /** Memory cost in KiB (19 MiB). */
+  memoryCost: 19456,
+  /** Iterations. */
+  timeCost: 2,
+  /** Parallelism (lanes). */
+  parallelism: 1,
+  /** Derived-key length in bytes — 32 matches the prior stored hashes. */
+  hashLength: 32,
+  /** Salt length in bytes — 16 matches the prior stored hashes. */
+  saltLength: 16,
+} as const
+
+/** Argon2 v1.3 (RFC 9106). */
+const ARGON2_VERSION = 0x13
+
+function randomSalt(length: number): Uint8Array {
+  return crypto.getRandomValues(new Uint8Array(length))
+}
+
+/** Hash a plaintext password. Returns a full PHC string. */
+export async function hashPassword(plaintext: string): Promise<string> {
+  if (plaintext.length === 0) {
+    throw new Error('hashPassword: plaintext must be non-empty')
+  }
+  const salt = randomSalt(HASH_OPTIONS.saltLength)
+  const hash = await argon2idAsync(plaintext, salt, {
+    m: HASH_OPTIONS.memoryCost,
+    t: HASH_OPTIONS.timeCost,
+    p: HASH_OPTIONS.parallelism,
+    dkLen: HASH_OPTIONS.hashLength,
+    version: ARGON2_VERSION,
+  })
+  return encodeArgon2idPhc({
+    algorithm: 'argon2id',
+    version: ARGON2_VERSION,
+    memoryCost: HASH_OPTIONS.memoryCost,
+    timeCost: HASH_OPTIONS.timeCost,
+    parallelism: HASH_OPTIONS.parallelism,
+    salt,
+    hash,
+  })
+}
+
+/**
+ * Verify a plaintext password against a stored PHC string. Returns `false`
+ * on mismatch — never throws for a normal mismatch. Re-throws on malformed
+ * hash strings or underlying library errors so those get surfaced.
+ */
+export async function verifyPassword(plaintext: string, phc: string): Promise<boolean> {
+  if (plaintext.length === 0 || phc.length === 0) return false
+  const decoded = decodeArgon2idPhc(phc)
+  const candidate = await argon2idAsync(plaintext, decoded.salt, {
+    m: decoded.memoryCost,
+    t: decoded.timeCost,
+    p: decoded.parallelism,
+    dkLen: decoded.hash.length,
+    version: decoded.version,
+  })
+  return timingSafeEqual(candidate, decoded.hash)
+}