@maestro-js/agent-skills 1.0.0-alpha.2 → 1.0.0-alpha.21

package/skills/maestro-examples/references/setlist/packages/schemas/src/user/index.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod'
+import { isoZ } from '@maestro-js/iso-zod'
+
+const userModel = z.object({
+  id: z.number(),
+  email: z.string().email(),
+  credentialsInvalidBefore: isoZ.instant().nullable(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+
+const loginForm = userModel.pick({ email: true })
+
+const verifyTokenForm = z.object({
+  token: z.string().min(1, 'Please enter your token')
+})
+
+export const UserSchemas = {
+  userModel,
+  loginForm,
+  verifyTokenForm
+}
+
+export declare namespace UserSchemas {
+  export type userModel = z.infer<typeof userModel>
+  export type loginForm = z.infer<typeof loginForm>
+  export type verifyTokenForm = z.infer<typeof verifyTokenForm>
+}

package/skills/maestro-examples/references/setlist/packages/schemas/tests/position.test.ts

@@ -0,0 +1,106 @@
+import { generateKeyBetween } from '../src/position.ts'
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+
+test('empty list returns a0', () => {
+  expect(generateKeyBetween(null, null)).toBe('a0')
+})
+
+test('insert before first item', () => {
+  const key = generateKeyBetween(null, 'a0')
+  expect(key).toBe('Zz')
+  expect(key < 'a0').toBe(true)
+})
+
+test('insert after last item', () => {
+  const key = generateKeyBetween('a0', null)
+  expect(key).toBe('a1')
+  expect(key > 'a0').toBe(true)
+})
+
+test('insert between two items', () => {
+  const key = generateKeyBetween('a0', 'a1')
+  expect(key > 'a0').toBe(true)
+  expect(key < 'a1').toBe(true)
+})
+
+test('insert between two items with fractional', () => {
+  const key = generateKeyBetween('a0', 'a0V')
+  expect(key > 'a0').toBe(true)
+  expect(key < 'a0V').toBe(true)
+})
+
+test('repeated insertions at the end', () => {
+  let key = generateKeyBetween(null, null) // a0
+  const keys = [key]
+  for (let i = 0; i < 10; i++) {
+    key = generateKeyBetween(key, null)
+    keys.push(key)
+  }
+  // All keys should be in ascending order
+  for (let i = 1; i < keys.length; i++) {
+    expect(keys[i] > keys[i - 1]).toBe(true)
+  }
+})
+
+test('repeated insertions at the start', () => {
+  let key = generateKeyBetween(null, null) // a0
+  const keys = [key]
+  for (let i = 0; i < 10; i++) {
+    key = generateKeyBetween(null, key)
+    keys.unshift(key)
+  }
+  // All keys should be in ascending order
+  for (let i = 1; i < keys.length; i++) {
+    expect(keys[i] > keys[i - 1]).toBe(true)
+  }
+})
+
+test('repeated insertions between same two keys', () => {
+  let a = 'a0'
+  const b = 'a1'
+  const keys = [a]
+  for (let i = 0; i < 10; i++) {
+    const mid = generateKeyBetween(a, b)
+    expect(mid > a).toBe(true)
+    expect(mid < b).toBe(true)
+    a = mid
+    keys.push(a)
+  }
+  keys.push(b)
+  // All keys should be in ascending order
+  for (let i = 1; i < keys.length; i++) {
+    expect(keys[i] > keys[i - 1]).toBe(true)
+  }
+})
+
+test('throws when a >= b', () => {
+  expect(() => generateKeyBetween('a1', 'a0')).toThrow()
+  expect(() => generateKeyBetween('a0', 'a0')).toThrow()
+})
+
+test('throws for invalid order key', () => {
+  expect(() => generateKeyBetween('0', null)).toThrow()
+  expect(() => generateKeyBetween('!', null)).toThrow()
+})
+
+test('keys from spec examples are correct', () => {
+  // From position-ordering.md
+  expect(generateKeyBetween('a0', 'a1')).toBe('a0V')
+  expect(generateKeyBetween(null, 'a0')).toBe('Zz')
+  expect(generateKeyBetween('a2', null)).toBe('a3')
+  expect(generateKeyBetween(null, null)).toBe('a0')
+})
+
+test('string comparison correctly reflects ordering', () => {
+  const keys = [
+    generateKeyBetween(null, null),
+    generateKeyBetween('a0', null),
+    generateKeyBetween('a1', null),
+    generateKeyBetween('a2', null)
+  ]
+  const sorted = [...keys].sort()
+  expect(sorted).toEqual(keys)
+})
+
+test.run()

package/skills/maestro-examples/references/setlist/packages/schemas/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "es2022",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true
+  },
+  "include": ["./src"]
+}

package/skills/maestro-examples/references/setlist/packages/services/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@setlist/services",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "maestro config:run --config services --root $PWD/../.. -- node ./run-tests.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@maestro-js/auth": "^1.0.0-alpha.21",
+    "@maestro-js/cache": "^1.0.0-alpha.21",
+    "@maestro-js/crypt": "^1.0.0-alpha.21",
+    "@maestro-js/custom-errors": "^1.0.0-alpha.21",
+    "@maestro-js/db": "^1.0.0-alpha.21",
+    "@maestro-js/iso-zod": "^1.0.0-alpha.21",
+    "@maestro-js/hash": "^1.0.0-alpha.21",
+    "@maestro-js/helpers": "^1.0.0-alpha.21",
+    "@maestro-js/log": "^1.0.0-alpha.21",
+    "@maestro-js/mail": "^1.0.0-alpha.21",
+    "@maestro-js/queue": "^1.0.0-alpha.21",
+    "@maestro-js/rate-limiting": "^1.0.0-alpha.21",
+    "@maestro-js/recurring-jobs": "^1.0.0-alpha.21",
+    "@maestro-js/session": "^1.0.0-alpha.21",
+    "@setlist/email-templates": "workspace:*",
+    "@setlist/schemas": "workspace:*",
+    "iso-fns": "npm:iso-fns@2.0.0-alpha.26",
+    "zod": "^4.3.0"
+  },
+  "devDependencies": {
+    "@maestro-js/cli": "^1.0.0-alpha.21",
+    "@aws-sdk/client-ses": "^3.0.0",
+    "@types/node": "^22.0.0",
+    "mailtrap": "^4.0.0",
+    "tsup": "^8.0.2",
+    "typescript": "~5.8.3"
+  }
+}

package/skills/maestro-examples/references/setlist/packages/services/run-tests.ts

@@ -0,0 +1,59 @@
+import './src/index.ts'
+import { run } from 'beartest-js'
+import { promises } from 'node:fs'
+import { sep, resolve, isAbsolute, parse, relative } from 'node:path'
+
+const INCLUDE = ['**/*.{test,spec}.{js,ts,jsx,tsx}']
+const EXCLUDE = ['**/node_modules/**', '**/dist/**', '**/.git/**', '**/build/**', '**/coverage/**']
+
+const hasGlob = (s: string) => /[*?\[\]{}()!]/.test(s)
+const norm = (p: string) => p.split(sep).join('/')
+
+async function discoverAll() {
+  const seen = new Set<string>()
+  for (const pat of INCLUDE) {
+    for await (const f of promises.glob(pat, { ignore: EXCLUDE })) seen.add(norm(f))
+  }
+  return [...seen].sort()
+}
+
+async function applyFilters(files: string[], args: string) {
+  if (!args.length) return files
+
+  let out = files
+  for (const arg of args) {
+    if (hasGlob(arg)) {
+      const gset = new Set()
+      for await (const f of promises.glob(arg, { ignore: EXCLUDE })) gset.add(norm(f))
+      out = out.filter((f) => gset.has(f)) // glob filter
+    } else {
+      const needle = norm(arg)
+      out = out.filter((f) => f.includes(needle)) // substring filter
+    }
+  }
+  return out
+}
+
+async function cli() {
+  const discovered = await discoverAll()
+  const selected = await applyFilters(discovered, process.argv.slice(2))
+
+  for await (let event of run({ files: selected.map((f) => resolve(f)) })) {
+    const prefix = '  '.repeat(event.data.nesting)
+    if (event.type === 'test:start' && event.data.type === 'suite') {
+      if (isAbsolute(event.data.name)) {
+        console.log(`\x1b[36m${prefix}${parse(event.data.name).name} (${relative('./', event.data.name)})\x1b[0m`)
+      } else {
+        console.log(`\x1b[36m${prefix}${event.data.name}\x1b[0m`)
+      }
+    } else if (event.type === 'test:pass' && event.data.details.type === 'test' && !event.data.skip) {
+      process.stdout.write(`\x1b[32m${prefix}✓\x1b[0m\x1b[90m ${event.data.name}\n\x1b[0m`)
+    } else if (event.type === 'test:fail' && event.data.details.type === 'test') {
+      process.stdout.write(`\x1b[31m\n${prefix}✗ ${event.data.name} \n\n\x1b[0m`)
+    }
+  }
+
+  process.exit(0)
+}
+
+cli()

package/skills/maestro-examples/references/setlist/packages/services/src/area/area-db-provider.test.ts

@@ -0,0 +1,29 @@
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+import { H } from '../testing/index.ts'
+import { areaDbProvider } from './area-db-provider.ts'
+
+const user = H.UserSeed({ id: 1 })
+const pipe = H.SeedPipe(user)
+
+test.beforeEach(async () => { await pipe.setup() })
+test.afterEach(async () => { await pipe.teardown() })
+
+test('create and getById', async () => {
+  const id = await areaDbProvider.create({ userId: 1, title: 'Work', position: 'a0' })
+  const area = await areaDbProvider.getById(id)
+  expect(area).not.toBeNull()
+  expect(area!.title).toBe('Work')
+  expect(area!.userId).toBe(1)
+  expect(area!.position).toBe('a0')
+  expect(area!.deletedDate).toBeNull()
+})
+
+test('update and listByUserId', async () => {
+  const id = await areaDbProvider.create({ userId: 1, title: 'Personal', position: 'a0' })
+  await areaDbProvider.update(id, { title: 'Home' })
+
+  const areas = await areaDbProvider.listByUserId(1)
+  expect(areas).toHaveLength(1)
+  expect(areas[0]!.title).toBe('Home')
+})

package/skills/maestro-examples/references/setlist/packages/services/src/area/area-db-provider.ts

@@ -0,0 +1,81 @@
+import { Db } from '@maestro-js/db'
+import { AreaSchemas } from '@setlist/schemas'
+import { instantFns } from 'iso-fns'
+
+type Area = AreaSchemas.areaModel
+
+async function create(data: { userId: number; title: string; position: string }): Promise<number> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  const result = await Db.insert(
+    'INSERT INTO areas (userId, title, position, createdDate, lastModifiedDate) VALUES (?, ?, ?, ?, ?)',
+    [data.userId, data.title, data.position, now, now]
+  )
+  return result.insertId
+}
+
+async function getById(id: number): Promise<Area | null> {
+  const rows = await Db.select('SELECT * FROM areas WHERE id = ?', [id])
+  const row = rows[0]
+  if (!row) return null
+  return AreaSchemas.areaModel.parse(row)
+}
+
+async function listByUserId(userId: number): Promise<Area[]> {
+  const rows = await Db.select(
+    'SELECT * FROM areas WHERE userId = ? AND deletedDate IS NULL ORDER BY position COLLATE utf8mb4_bin ASC',
+    [userId]
+  )
+  return rows.map((row) => AreaSchemas.areaModel.parse(row))
+}
+
+async function update(id: number, data: { title: string }): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.update('UPDATE areas SET title = ?, lastModifiedDate = ? WHERE id = ?', [data.title, now, id])
+}
+
+async function softDelete(id: number): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.update('UPDATE areas SET deletedDate = ?, lastModifiedDate = ? WHERE id = ?', [now, now, id])
+}
+
+async function updatePosition(id: number, position: string): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.update('UPDATE areas SET position = ?, lastModifiedDate = ? WHERE id = ?', [position, now, id])
+}
+
+async function orphanChildProjects(areaId: number): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.update('UPDATE projects SET areaId = NULL, lastModifiedDate = ? WHERE areaId = ?', [now, areaId])
+}
+
+async function seedCreate(data: Area): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.insert(
+    'INSERT INTO areas (id, userId, title, position, deletedDate, createdDate, lastModifiedDate) VALUES (?, ?, ?, ?, ?, ?, ?)',
+    [
+      data.id,
+      data.userId,
+      data.title,
+      data.position,
+      data.deletedDate ? instantFns.formatISO9075(data.deletedDate) : null,
+      now,
+      now
+    ]
+  )
+}
+
+async function hardDelete(id: number): Promise<void> {
+  await Db.delete('DELETE FROM areas WHERE id = ?', [id])
+}
+
+export const areaDbProvider = {
+  create,
+  getById,
+  listByUserId,
+  update,
+  softDelete,
+  updatePosition,
+  orphanChildProjects,
+  seedCreate,
+  hardDelete
+}

package/skills/maestro-examples/references/setlist/packages/services/src/area/area-use-cases.ts

@@ -0,0 +1,130 @@
+import z from 'zod'
+import { Db } from '@maestro-js/db'
+import { Log } from '@maestro-js/log'
+import { CustomErrors } from '@maestro-js/custom-errors'
+import { AreaSchemas, UserSchemas } from '@setlist/schemas'
+import { areaDbProvider } from './area-db-provider.ts'
+import { taskDbProvider } from '../task/task-db-provider.ts'
+import { projectDbProvider } from '../project/project-db-provider.ts'
+import { generateKeyBetween } from '@setlist/schemas'
+
+const log = Log.channel('area')
+
+const Profile = UserSchemas.userModel.pick({ id: true })
+
+export const AreaNotFoundError = CustomErrors.create({
+  name: 'AreaNotFoundError',
+  message: 'Area not found',
+  httpStatusCode: 'notFound' as const
+})
+
+export const AreaNotOwnedError = CustomErrors.create({
+  name: 'AreaNotOwnedError',
+  message: 'Area does not belong to the authenticated user',
+  httpStatusCode: 'forbidden' as const
+})
+
+export const ListAreas = z
+  .function({
+    input: [Profile]
+  })
+  .implement(async (profile) => {
+    return areaDbProvider.listByUserId(profile.id)
+  })
+
+export const CreateArea = z
+  .function({
+    input: [AreaSchemas.createAreaForm, Profile]
+  })
+  .implement(async ({ title }, profile) => {
+    const areas = await areaDbProvider.listByUserId(profile.id)
+    const lastArea = areas.at(-1)
+    const position = generateKeyBetween(lastArea?.position ?? null, null)
+
+    const areaId = await areaDbProvider.create({
+      userId: profile.id,
+      title,
+      position
+    })
+
+    log.info('Area created', { action: 'area.create', userId: profile.id, areaId })
+
+    return { areaId }
+  })
+
+export const EditArea = z
+  .function({
+    input: [AreaSchemas.editAreaForm.extend({ id: z.number() }), Profile]
+  })
+  .implement(async ({ id, title }, profile) => {
+    const area = await areaDbProvider.getById(id)
+    if (!area) throw new AreaNotFoundError()
+    if (area.userId !== profile.id) throw new AreaNotOwnedError()
+
+    await areaDbProvider.update(id, { title })
+
+    log.info('Area edited', { action: 'area.edit', userId: profile.id, areaId: id })
+  })
+
+export const DeleteArea = z
+  .function({
+    input: [z.object({ id: z.number() }), Profile]
+  })
+  .implement(async ({ id }, profile) => {
+    const area = await areaDbProvider.getById(id)
+    if (!area) throw new AreaNotFoundError()
+    if (area.userId !== profile.id) throw new AreaNotOwnedError()
+
+    await Db.transaction(async () => {
+      await areaDbProvider.softDelete(id)
+      await areaDbProvider.orphanChildProjects(id)
+    })
+
+    log.info('Area deleted', { action: 'area.delete', userId: profile.id, areaId: id })
+  })
+
+export const ReorderArea = z
+  .function({
+    input: [z.object({ id: z.number(), beforeKey: z.string().nullable(), afterKey: z.string().nullable() }), Profile]
+  })
+  .implement(async ({ id, beforeKey, afterKey }, profile) => {
+    const area = await areaDbProvider.getById(id)
+    if (!area) throw new AreaNotFoundError()
+    if (area.userId !== profile.id) throw new AreaNotOwnedError()
+
+    const position = generateKeyBetween(beforeKey, afterKey)
+    await areaDbProvider.updatePosition(id, position)
+
+    log.info('Area reordered', { action: 'area.reorder', userId: profile.id, areaId: id })
+  })
+
+export const GetAreaById = z
+  .function({
+    input: [z.object({ id: z.number() }), Profile]
+  })
+  .implement(async ({ id }, profile) => {
+    const area = await areaDbProvider.getById(id)
+    if (!area) throw new AreaNotFoundError()
+    if (area.deletedDate !== null) throw new AreaNotFoundError()
+    if (area.userId !== profile.id) throw new AreaNotOwnedError()
+
+    return area
+  })
+
+export const ListTasksByAreaId = z
+  .function({
+    input: [z.object({ areaId: z.number() }), Profile]
+  })
+  .implement(async ({ areaId }, profile) => {
+    await GetAreaById({ id: areaId }, profile)
+    return taskDbProvider.listByAreaId(areaId)
+  })
+
+export const ListProjectsByAreaId = z
+  .function({
+    input: [z.object({ areaId: z.number() }), Profile]
+  })
+  .implement(async ({ areaId }, profile) => {
+    await GetAreaById({ id: areaId }, profile)
+    return projectDbProvider.listByAreaId(areaId)
+  })

package/skills/maestro-examples/references/setlist/packages/services/src/area/index.ts

@@ -0,0 +1,27 @@
+import {
+  ListAreas,
+  CreateArea,
+  EditArea,
+  DeleteArea,
+  ReorderArea,
+  GetAreaById,
+  ListTasksByAreaId,
+  ListProjectsByAreaId,
+  AreaNotFoundError,
+  AreaNotOwnedError
+} from './area-use-cases.ts'
+
+export const AreaService = {
+  ListAreas,
+  CreateArea,
+  EditArea,
+  DeleteArea,
+  ReorderArea,
+  GetAreaById,
+  ListTasksByAreaId,
+  ListProjectsByAreaId,
+  errors: {
+    AreaNotFoundError,
+    AreaNotOwnedError
+  }
+}

package/skills/maestro-examples/references/setlist/packages/services/src/auth/auth-db-provider.test.ts

@@ -0,0 +1,34 @@
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+import { instantFns } from 'iso-fns'
+import { H } from '../testing/index.ts'
+import { authDbProvider } from './auth-db-provider.ts'
+
+const user = H.UserSeed({ id: 1 })
+const pipe = H.SeedPipe(user)
+
+test.beforeEach(async () => {
+  await pipe.setup()
+})
+test.afterEach(async () => {
+  await pipe.teardown()
+})
+
+test('getAuthenticatableById', async () => {
+  const auth = await authDbProvider.getAuthenticatableById(1)
+  expect(auth).not.toBeNull()
+  expect(auth!.id).toBe(1)
+  expect(auth!.credentialsInvalidBefore).toBeNull()
+
+  const missing = await authDbProvider.getAuthenticatableById(999)
+  expect(missing).toBeNull()
+})
+
+test('updateCredentialsInvalidBefore', async () => {
+  const now = instantFns.now()
+  await authDbProvider.updateCredentialsInvalidBefore(1, now)
+
+  const auth = await authDbProvider.getAuthenticatableById(1)
+  expect(auth).not.toBeNull()
+  expect(auth!.credentialsInvalidBefore).not.toBeNull()
+})

package/skills/maestro-examples/references/setlist/packages/services/src/auth/auth-db-provider.ts

@@ -0,0 +1,24 @@
+import { Auth } from '@maestro-js/auth'
+import { Db } from '@maestro-js/db'
+import { isoZ } from '@maestro-js/iso-zod'
+import { instantFns, type Iso } from 'iso-fns'
+import { z } from 'zod'
+
+const authenticatableModel = z.object({
+  id: z.number(),
+  credentialsInvalidBefore: isoZ.instant().nullable()
+})
+
+async function getAuthenticatableById(id: number): Promise<Auth.Authenticatable | null> {
+  const rows = await Db.select('SELECT id, credentialsInvalidBefore FROM users WHERE id = ?', [id])
+  return rows.length ? authenticatableModel.parse(rows[0]) : null
+}
+
+async function updateCredentialsInvalidBefore(id: number, date: Iso.Instant): Promise<void> {
+  await Db.update('UPDATE users SET credentialsInvalidBefore = ? WHERE id = ?', [instantFns.formatISO9075(date), id])
+}
+
+export const authDbProvider = {
+  getAuthenticatableById,
+  updateCredentialsInvalidBefore
+}

package/skills/maestro-examples/references/setlist/packages/services/src/auth/auth-use-cases.ts

@@ -0,0 +1,110 @@
+import crypto from 'node:crypto'
+import z from 'zod'
+import { Auth } from '@maestro-js/auth'
+import { Hash } from '@maestro-js/hash'
+import { Mail } from '@maestro-js/mail'
+import { Log } from '@maestro-js/log'
+import { CustomErrors } from '@maestro-js/custom-errors'
+import { RateLimiting } from '@maestro-js/rate-limiting'
+import { instantFns } from 'iso-fns'
+import type { Session } from '@maestro-js/session'
+import { renderEmailTemplate } from '@setlist/email-templates'
+import type { DeviceContext } from '../maestro.ts'
+import { magicLinkDbProvider } from './magic-link-db-provider.ts'
+import { userDbProvider } from './user-db-provider.ts'
+
+const log = Log.channel('auth')
+const isTesting = process.env.IS_TESTING === 'true'
+
+async function getOrCreateUserId(email: string): Promise<number> {
+  const existing = await userDbProvider.getByEmail(email)
+  if (existing) return existing.id
+  return userDbProvider.create({ email })
+}
+
+export const MagicLinkThrottledError = CustomErrors.create({
+  name: 'MagicLinkThrottledError',
+  message: 'Please wait before requesting another magic link',
+  additionalAttributes: (input: { retryAfterSeconds: number }) => ({ retryAfterSeconds: input.retryAfterSeconds }),
+  httpStatusCode: 'tooManyRequests' as const
+})
+
+export const RequestMagicLink = z
+  .function({
+    input: [z.object({ email: z.string().email(), baseUrl: z.string() })]
+  })
+  .implement(async ({ email: emailRaw, baseUrl }) => {
+    const email = emailRaw.toLowerCase().trim()
+
+    // Rate limit: 5 requests per 60 seconds per email
+    if (!isTesting) {
+      const rateLimitKey = `magic-link:${email}`
+      if (await RateLimiting.tooManyAttempts(rateLimitKey, 5)) {
+        const retryAfter = await RateLimiting.availableIn(rateLimitKey)
+        const seconds = retryAfter ? Number(String(retryAfter).match(/PT(\d+)S/)?.[1]) || 60 : 60
+        log.warn('Magic link throttled', { action: 'auth.requestMagicLink', email })
+        throw new MagicLinkThrottledError({ retryAfterSeconds: seconds })
+      }
+      await RateLimiting.increment(rateLimitKey, 1, 60)
+    }
+
+    // Look up user by email, create if not exists
+    const userId = await getOrCreateUserId(email)
+
+    // Generate selector (16 bytes) and verifier (32 bytes)
+    const selector = crypto.randomBytes(16).toString('base64url')
+    const verifier = crypto.randomBytes(32).toString('base64url')
+
+    // Hash verifier with bcrypt
+    const verifierHash = await Hash.provider('bcrypt').hash(verifier)
+
+    // Store magic link record with 15-minute expiry
+    const now = instantFns.now()
+    const expirationDate = instantFns.add(now, { minutes: 15 })
+
+    await magicLinkDbProvider.create({
+      userId,
+      selector,
+      verifierHash,
+      expirationDate,
+      createdDate: now
+    })
+
+    // Build token and queue email
+    const token = `${selector}|${verifier}`
+    const loginUrl = `${baseUrl}/auth/verify?token=${encodeURIComponent(token)}`
+
+    const html = await renderEmailTemplate('magic-link-login', { loginUrl, token })
+
+    Mail.send({ to: email, subject: 'Your Setlist login link', content: { html } })
+
+    log.info('Magic link requested', { action: 'auth.requestMagicLink', userId, email })
+  })
+
+export const MagicLinkInvalidTokenError = CustomErrors.create({
+  name: 'MagicLinkInvalidTokenError',
+  message: 'Invalid or expired magic link token',
+  httpStatusCode: 'badRequest' as const
+})
+
+export const VerifyMagicLink = z
+  .function({
+    input: [
+      z.object({
+        token: z.string(),
+        session: z.custom<Session | Promise<Session>>(),
+        deviceContext: z.custom<DeviceContext>()
+      })
+    ]
+  })
+  .implement(async ({ token, session, deviceContext }) => {
+    const result = await Auth.login({ credentials: { token }, session, deviceContext })
+
+    if (result.id !== null) {
+      log.info('Magic link verified', { action: 'auth.verifyMagicLink', userId: result.id })
+    } else {
+      log.warn('Magic link verification failed', { action: 'auth.verifyMagicLink' })
+    }
+
+    return result
+  })