feat: POS PIN unlock with employee number + PIN auth

- Add employeeNumber and pinHash fields to users table
- POST /auth/pin-login: takes combined code (4-digit employee# + 4-digit PIN)
- POST /auth/set-pin: employee sets their own PIN (requires full auth)
- DELETE /auth/pin: remove PIN
- Lock screen with numpad, auto-submits on 8 digits, visual dot separator
- POS uses its own auth token separate from admin session
- Admin "POS" link clears admin session before navigating
- /pos route has no auth guard — lock screen is the auth
- API client uses POS token when available, admin token otherwise
- Auto-lock timer reads pos_lock_timeout from app_config (default 15 min)
- Lock button in POS top bar, shows current cashier name

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

packages/admin/src/components/pos/pos-lock-screen.tsx

@@ -0,0 +1,168 @@
+import { useState, useCallback, useEffect, useRef } from 'react'
+import { usePOSStore } from '@/stores/pos.store'
+import { api } from '@/lib/api-client'
+import { Button } from '@/components/ui/button'
+import { Delete, Lock } from 'lucide-react'
+
+interface PinUser {
+  id: string
+  email: string
+  firstName: string
+  lastName: string
+  role: string
+}
+
+export function POSLockScreen() {
+  const unlock = usePOSStore((s) => s.unlock)
+  const [code, setCode] = useState('')
+  const [error, setError] = useState('')
+  const [loading, setLoading] = useState(false)
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  // Auto-focus on mount
+  useEffect(() => {
+    containerRef.current?.focus()
+  }, [])
+
+  const handleDigit = useCallback((digit: string) => {
+    setError('')
+    setCode((p) => {
+      if (p.length >= 10) return p
+      return p + digit
+    })
+  }, [])
+
+  const handleBackspace = useCallback(() => {
+    setError('')
+    setCode((p) => p.slice(0, -1))
+  }, [])
+
+  const handleClear = useCallback(() => {
+    setError('')
+    setCode('')
+  }, [])
+
+  const handleSubmit = useCallback(async (submitCode: string) => {
+    if (submitCode.length < 8) {
+      setError('Enter your employee # (4) + PIN (4)')
+      return
+    }
+    setLoading(true)
+    setError('')
+    try {
+      const res = await api.post<{ user: PinUser; token: string }>('/v1/auth/pin-login', { code: submitCode })
+      unlock(res.user, res.token)
+      setCode('')
+    } catch {
+      setError('Invalid code')
+      setCode('')
+    } finally {
+      setLoading(false)
+    }
+  }, [unlock])
+
+  // Auto-submit when 8 digits entered
+  useEffect(() => {
+    if (code.length === 8) {
+      handleSubmit(code)
+    }
+  }, [code, handleSubmit])
+
+  const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
+    if (e.key >= '0' && e.key <= '9') handleDigit(e.key)
+    else if (e.key === 'Backspace') handleBackspace()
+    else if (e.key === 'Enter' && code.length >= 8) handleSubmit(code)
+    else if (e.key === 'Escape') handleClear()
+  }, [handleDigit, handleBackspace, handleSubmit, handleClear, code])
+
+  return (
+    <div
+      ref={containerRef}
+      className="absolute inset-0 z-50 bg-background flex items-center justify-center"
+      onKeyDown={handleKeyDown}
+      tabIndex={0}
+    >
+      <div className="w-80 space-y-6">
+        {/* Header */}
+        <div className="text-center space-y-2">
+          <Lock className="h-10 w-10 mx-auto text-muted-foreground" />
+          <h1 className="text-xl font-semibold">POS Locked</h1>
+          <p className="text-sm text-muted-foreground">Employee # + PIN</p>
+        </div>
+
+        {/* Code dots — 4 employee + 4 PIN with separator */}
+        <div className="flex justify-center items-center gap-2">
+          <div className="flex gap-1.5">
+            {Array.from({ length: 4 }).map((_, i) => (
+              <div
+                key={`e${i}`}
+                className={`w-3.5 h-3.5 rounded-full border-2 ${
+                  i < Math.min(code.length, 4) ? 'bg-foreground border-foreground' : 'border-muted-foreground/30'
+                }`}
+              />
+            ))}
+          </div>
+          <span className="text-muted-foreground/40 text-lg">-</span>
+          <div className="flex gap-1.5">
+            {Array.from({ length: 4 }).map((_, i) => (
+              <div
+                key={`p${i}`}
+                className={`w-3.5 h-3.5 rounded-full border-2 ${
+                  i < Math.max(0, code.length - 4) ? 'bg-foreground border-foreground' : 'border-muted-foreground/30'
+                }`}
+              />
+            ))}
+          </div>
+        </div>
+
+        {/* Error */}
+        {error && (
+          <p className="text-sm text-destructive text-center">{error}</p>
+        )}
+
+        {/* Numpad */}
+        <div className="grid grid-cols-3 gap-2">
+          {['1', '2', '3', '4', '5', '6', '7', '8', '9'].map((d) => (
+            <Button
+              key={d}
+              variant="outline"
+              className="h-14 text-xl font-medium"
+              onClick={() => handleDigit(d)}
+              disabled={loading}
+            >
+              {d}
+            </Button>
+          ))}
+          <Button
+            variant="outline"
+            className="h-14 text-sm"
+            onClick={handleClear}
+            disabled={loading}
+          >
+            Clear
+          </Button>
+          <Button
+            variant="outline"
+            className="h-14 text-xl font-medium"
+            onClick={() => handleDigit('0')}
+            disabled={loading}
+          >
+            0
+          </Button>
+          <Button
+            variant="outline"
+            className="h-14"
+            onClick={handleBackspace}
+            disabled={loading}
+          >
+            <Delete className="h-5 w-5" />
+          </Button>
+        </div>
+
+        {loading && (
+          <p className="text-sm text-muted-foreground text-center">Verifying...</p>
+        )}
+      </div>
+    </div>
+  )
+}

packages/admin/src/components/pos/pos-register.tsx

@@ -1,4 +1,4 @@
-import { useEffect } from 'react'
+import { useEffect, useRef, useCallback } from 'react'
 import { useQuery } from '@tanstack/react-query'
 import { queryOptions } from '@tanstack/react-query'
 import { api } from '@/lib/api-client'
@@ -7,12 +7,18 @@ import { currentDrawerOptions, transactionOptions } from '@/api/pos'
 import { POSTopBar } from './pos-top-bar'
 import { POSItemPanel } from './pos-item-panel'
 import { POSCartPanel } from './pos-cart-panel'
+import { POSLockScreen } from './pos-lock-screen'
 
 interface Location {
   id: string
   name: string
 }
 
+interface AppConfigEntry {
+  key: string
+  value: string | null
+}
+
 function locationsOptions() {
   return queryOptions({
     queryKey: ['locations'],
@@ -20,11 +26,61 @@ function locationsOptions() {
   })
 }
 
+function configOptions(key: string) {
+  return queryOptions({
+    queryKey: ['config', key],
+    queryFn: async (): Promise<string | null> => {
+      try {
+        const entry = await api.get<AppConfigEntry>(`/v1/config/${key}`)
+        return entry.value
+      } catch {
+        return null
+      }
+    },
+  })
+}
+
 export function POSRegister() {
-  const { locationId, setLocation, currentTransactionId, setDrawerSession } = usePOSStore()
+  const { locationId, setLocation, currentTransactionId, setDrawerSession, locked, lock, touchActivity, token } = usePOSStore()
+
+  // Fetch lock timeout from config
+  const { data: lockTimeoutStr } = useQuery({
+    ...configOptions('pos_lock_timeout'),
+    enabled: !!token,
+  })
+  const lockTimeoutMinutes = parseInt(lockTimeoutStr ?? '15') || 15
+
+  // Auto-lock timer
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null)
+
+  useEffect(() => {
+    if (locked || lockTimeoutMinutes === 0) {
+      if (timerRef.current) clearInterval(timerRef.current)
+      return
+    }
+
+    timerRef.current = setInterval(() => {
+      const { lastActivity, locked: isLocked } = usePOSStore.getState()
+      if (!isLocked && Date.now() - lastActivity > lockTimeoutMinutes * 60_000) {
+        lock()
+      }
+    }, 30_000)
+
+    return () => {
+      if (timerRef.current) clearInterval(timerRef.current)
+    }
+  }, [locked, lockTimeoutMinutes, lock])
+
+  // Track activity on any interaction
+  const handleActivity = useCallback(() => {
+    if (!locked) touchActivity()
+  }, [locked, touchActivity])
 
   // Fetch locations
-  const { data: locationsData } = useQuery(locationsOptions())
+  const { data: locationsData } = useQuery({
+    ...locationsOptions(),
+    enabled: !!token,
+  })
   const locations = locationsData?.data ?? []
 
   // Auto-select first location
@@ -38,6 +94,7 @@ export function POSRegister() {
   const { data: drawer } = useQuery({
     ...currentDrawerOptions(locationId),
     retry: false,
+    enabled: !!locationId && !!token,
   })
 
   // Sync drawer session ID
@@ -50,10 +107,18 @@ export function POSRegister() {
   }, [drawer, setDrawerSession])
 
   // Fetch current transaction
-  const { data: transaction } = useQuery(transactionOptions(currentTransactionId))
+  const { data: transaction } = useQuery({
+    ...transactionOptions(currentTransactionId),
+    enabled: !!currentTransactionId && !!token,
+  })
 
   return (
-    <div className="flex flex-col h-full">
+    <div
+      className="relative flex flex-col h-full"
+      onPointerDown={handleActivity}
+      onKeyDown={handleActivity}
+    >
+      {locked && <POSLockScreen />}
       <POSTopBar
         locations={locations}
         locationId={locationId}
@@ -62,7 +127,7 @@ export function POSRegister() {
       />
       <div className="flex flex-1 min-h-0">
         <div className="w-[60%] border-r border-border overflow-hidden">
-          <POSItemPanel transaction={transaction ?? null} />
+          <POSItemPanel _transaction={transaction ?? null} />
         </div>
         <div className="w-[40%] overflow-hidden">
           <POSCartPanel transaction={transaction ?? null} />

packages/admin/src/components/pos/pos-top-bar.tsx

@@ -1,10 +1,9 @@
-import { Link, useRouter } from '@tanstack/react-router'
+import { Link } from '@tanstack/react-router'
-import { useAuthStore } from '@/stores/auth.store'
+import { usePOSStore } from '@/stores/pos.store'
-
 import { Button } from '@/components/ui/button'
 import { Badge } from '@/components/ui/badge'
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
-import { ArrowLeft, LogOut, DollarSign } from 'lucide-react'
+import { ArrowLeft, Lock, DollarSign } from 'lucide-react'
 import type { DrawerSession } from '@/api/pos'
 import { useState } from 'react'
 import { POSDrawerDialog } from './pos-drawer-dialog'
@@ -17,24 +16,18 @@ interface POSTopBarProps {
 }
 
 export function POSTopBar({ locations, locationId, onLocationChange, drawer }: POSTopBarProps) {
-  const router = useRouter()
+  const cashier = usePOSStore((s) => s.cashier)
-  const user = useAuthStore((s) => s.user)
+  const lockFn = usePOSStore((s) => s.lock)
-  const logout = useAuthStore((s) => s.logout)
   const [drawerDialogOpen, setDrawerDialogOpen] = useState(false)
 
   const drawerOpen = drawer?.status === 'open'
 
-  function handleLogout() {
-    logout()
-    router.navigate({ to: '/login', replace: true })
-  }
-
   return (
     <>
       <div className="h-12 border-b border-border bg-card flex items-center justify-between px-3 shrink-0">
         {/* Left: back + location */}
         <div className="flex items-center gap-3">
-          <Link to="/" className="flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground">
+          <Link to="/login" className="flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground">
             <ArrowLeft className="h-4 w-4" />
             <span className="hidden sm:inline">Admin</span>
           </Link>
@@ -70,11 +63,13 @@ export function POSTopBar({ locations, locationId, onLocationChange, drawer }: P
           )}
         </Button>
 
-        {/* Right: user + logout */}
+        {/* Right: cashier + lock */}
         <div className="flex items-center gap-2">
-          <span className="text-sm text-muted-foreground">{user?.firstName}</span>
+          {cashier && (
-          <Button variant="ghost" size="icon" className="h-8 w-8" onClick={handleLogout} title="Sign out">
+            <span className="text-sm text-muted-foreground">{cashier.firstName}</span>
-            <LogOut className="h-4 w-4" />
+          )}
+          <Button variant="ghost" size="icon" className="h-8 w-8" onClick={lockFn} title="Lock POS">
+            <Lock className="h-4 w-4" />
           </Button>
         </div>
       </div>

packages/admin/src/lib/api-client.ts

@@ -1,4 +1,5 @@
 import { useAuthStore } from '@/stores/auth.store'
+import { usePOSStore } from '@/stores/pos.store'
 
 class ApiError extends Error {
   statusCode: number
@@ -13,7 +14,8 @@ class ApiError extends Error {
 }
 
 async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
-  const { token } = useAuthStore.getState()
+  // Use POS token if available (POS screen), otherwise admin token
+  const token = usePOSStore.getState().token ?? useAuthStore.getState().token
 
   const headers: Record<string, string> = {}
 
@@ -32,9 +34,12 @@ async function request<T>(method: string, path: string, body?: unknown): Promise
   })
 
   if (res.status === 401) {
-    useAuthStore.getState().logout()
+    // On POS, lock the screen instead of logging out admin
-    // Don't use window.location — that causes a full reload and flash
+    if (usePOSStore.getState().token) {
-    // The router's beforeLoad guard will redirect to /login on next navigation
+      usePOSStore.getState().lock()
+    } else {
+      useAuthStore.getState().logout()
+    }
     throw new ApiError('Unauthorized', 401)
   }
 

packages/admin/src/routes/_authenticated.tsx

@@ -176,7 +176,14 @@ function AuthenticatedLayout() {
           <div className="flex-1 overflow-y-auto px-2 space-y-1 scrollbar-thin">
             {isModuleEnabled('pos') && canViewPOS && (
               <div className="mb-2">
-                <NavLink to="/pos" icon={<ShoppingCart className="h-4 w-4" />} label="Point of Sale" collapsed={collapsed} />
+                <button
+                  onClick={() => { logout(); router.navigate({ to: '/pos' }) }}
+                  className="flex items-center gap-2 px-3 py-2 rounded-md text-sm text-sidebar-foreground hover:bg-sidebar-accent w-full"
+                  title={collapsed ? 'Point of Sale' : undefined}
+                >
+                  <ShoppingCart className="h-4 w-4" />
+                  {!collapsed && 'Point of Sale'}
+                </button>
               </div>
             )}
             {canViewAccounts && (

packages/admin/src/routes/pos.tsx

@@ -1,14 +1,7 @@
-import { createFileRoute, redirect } from '@tanstack/react-router'
+import { createFileRoute } from '@tanstack/react-router'
-import { useAuthStore } from '@/stores/auth.store'
 import { POSRegister } from '@/components/pos/pos-register'
 
 export const Route = createFileRoute('/pos')({
-  beforeLoad: () => {
-    const { token } = useAuthStore.getState()
-    if (!token) {
-      throw redirect({ to: '/login' })
-    }
-  },
   component: POSPage,
 })
 

packages/admin/src/stores/pos.store.ts

@@ -1,12 +1,27 @@
 import { create } from 'zustand'
 
+interface POSUser {
+  id: string
+  email: string
+  firstName: string
+  lastName: string
+  role: string
+}
+
 interface POSState {
   currentTransactionId: string | null
   locationId: string | null
   drawerSessionId: string | null
+  locked: boolean
+  cashier: POSUser | null
+  token: string | null
+  lastActivity: number
   setTransaction: (id: string | null) => void
   setLocation: (id: string) => void
   setDrawerSession: (id: string | null) => void
+  unlock: (user: POSUser, token: string) => void
+  lock: () => void
+  touchActivity: () => void
   reset: () => void
 }
 
@@ -14,8 +29,15 @@ export const usePOSStore = create<POSState>((set) => ({
   currentTransactionId: null,
   locationId: null,
   drawerSessionId: null,
+  locked: true,
+  cashier: null,
+  token: null,
+  lastActivity: Date.now(),
   setTransaction: (id) => set({ currentTransactionId: id }),
   setLocation: (id) => set({ locationId: id }),
   setDrawerSession: (id) => set({ drawerSessionId: id }),
+  unlock: (user, token) => set({ locked: false, cashier: user, token, lastActivity: Date.now() }),
+  lock: () => set({ locked: true, currentTransactionId: null }),
+  touchActivity: () => set({ lastActivity: Date.now() }),
   reset: () => set({ currentTransactionId: null }),
 }))

packages/backend/src/db/migrations/0042_user-pin.sql

@@ -0,0 +1,16 @@
+ALTER TABLE "user" ADD COLUMN IF NOT EXISTS "pin_hash" varchar(255);
+ALTER TABLE "user" ADD COLUMN IF NOT EXISTS "employee_number" varchar(20) UNIQUE;
+
+-- Auto-assign employee numbers to existing users
+DO $$ DECLARE r RECORD; num INT := 1001;
+BEGIN
+  FOR r IN (SELECT id FROM "user" WHERE employee_number IS NULL ORDER BY created_at) LOOP
+    UPDATE "user" SET employee_number = num::text WHERE id = r.id;
+    num := num + 1;
+  END LOOP;
+END $$;
+
+-- Seed POS lock timeout config
+INSERT INTO "app_config" ("key", "value", "description")
+VALUES ('pos_lock_timeout', '15', 'POS auto-lock timeout in minutes (0 to disable)')
+ON CONFLICT ("key") DO NOTHING;

packages/backend/src/db/migrations/meta/_journal.json

@@ -302,6 +302,13 @@
       "when": 1775590000000,
       "tag": "0042_drawer-adjustments",
       "breakpoints": true
+    },
+    {
+      "idx": 42,
+      "version": "7",
+      "when": 1775590000000,
+      "tag": "0042_user-pin",
+      "breakpoints": true
     }
   ]
 }

packages/backend/src/db/schema/users.ts

@@ -15,6 +15,8 @@ export const users = pgTable('user', {
   firstName: varchar('first_name', { length: 100 }).notNull(),
   lastName: varchar('last_name', { length: 100 }).notNull(),
   role: userRoleEnum('role').notNull().default('staff'),
+  employeeNumber: varchar('employee_number', { length: 20 }).unique(),
+  pinHash: varchar('pin_hash', { length: 255 }),
   isActive: boolean('is_active').notNull().default(true),
   createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
   updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),

packages/backend/src/routes/v1/auth.ts

@@ -1,7 +1,7 @@
 import type { FastifyPluginAsync } from 'fastify'
 import { eq } from 'drizzle-orm'
 import bcrypt from 'bcryptjs'
-import { RegisterSchema, LoginSchema } from '@lunarfront/shared/schemas'
+import { RegisterSchema, LoginSchema, PinLoginSchema, SetPinSchema } from '@lunarfront/shared/schemas'
 import { users } from '../../db/schema/users.js'
 
 const SALT_ROUNDS = 10
@@ -226,4 +226,71 @@ export const authRoutes: FastifyPluginAsync = async (app) => {
 
     return reply.send(user)
   })
+
+  // PIN login — for POS unlock, no JWT required to call
+  app.post('/auth/pin-login', rateLimitConfig, async (request, reply) => {
+    const parsed = PinLoginSchema.safeParse(request.body)
+    if (!parsed.success) {
+      return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
+    }
+
+    const { code } = parsed.data
+    // First 4 digits = employee number, rest = PIN
+    const employeeNumber = code.slice(0, 4)
+    const pin = code.slice(4)
+
+    if (!pin) {
+      return reply.status(401).send({ error: { message: 'Invalid code', statusCode: 401 } })
+    }
+
+    const [user] = await app.db
+      .select()
+      .from(users)
+      .where(eq(users.employeeNumber, employeeNumber))
+      .limit(1)
+
+    if (!user || !user.isActive || !user.pinHash) {
+      return reply.status(401).send({ error: { message: 'Invalid code', statusCode: 401 } })
+    }
+
+    const match = await bcrypt.compare(pin, user.pinHash)
+    if (!match) {
+      return reply.status(401).send({ error: { message: 'Invalid code', statusCode: 401 } })
+    }
+
+    const token = app.jwt.sign({ id: user.id, role: user.role }, { expiresIn: '8h' })
+    request.log.info({ userId: user.id }, 'PIN login')
+    return reply.send({
+      user: {
+        id: user.id,
+        email: user.email,
+        firstName: user.firstName,
+        lastName: user.lastName,
+        role: user.role,
+      },
+      token,
+    })
+  })
+
+  // Set PIN — requires full auth
+  app.post('/auth/set-pin', { preHandler: [app.authenticate] }, async (request, reply) => {
+    const parsed = SetPinSchema.safeParse(request.body)
+    if (!parsed.success) {
+      return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
+    }
+
+    const pinHash = await bcrypt.hash(parsed.data.pin, SALT_ROUNDS)
+    await app.db.update(users).set({ pinHash, updatedAt: new Date() }).where(eq(users.id, request.user.id))
+
+    request.log.info({ userId: request.user.id }, 'POS PIN set')
+    return reply.send({ message: 'PIN set' })
+  })
+
+  // Remove PIN — requires full auth
+  app.delete('/auth/pin', { preHandler: [app.authenticate] }, async (request, reply) => {
+    await app.db.update(users).set({ pinHash: null, updatedAt: new Date() }).where(eq(users.id, request.user.id))
+
+    request.log.info({ userId: request.user.id }, 'POS PIN removed')
+    return reply.send({ message: 'PIN removed' })
+  })
 }

packages/shared/src/schemas/auth.schema.ts

@@ -17,3 +17,13 @@ export const LoginSchema = z.object({
   password: z.string().min(1),
 })
 export type LoginInput = z.infer<typeof LoginSchema>
+
+export const PinLoginSchema = z.object({
+  code: z.string().min(8).max(10).regex(/^\d+$/, 'Code must be digits only'),
+})
+export type PinLoginInput = z.infer<typeof PinLoginSchema>
+
+export const SetPinSchema = z.object({
+  pin: z.string().min(4).max(6).regex(/^\d+$/, 'PIN must be digits only'),
+})
+export type SetPinInput = z.infer<typeof SetPinSchema>

packages/shared/src/schemas/index.ts

@@ -1,8 +1,8 @@
 export { PaginationSchema } from './pagination.schema.js'
 export type { PaginationInput, PaginatedResponse } from './pagination.schema.js'
 
-export { UserRole, RegisterSchema, LoginSchema } from './auth.schema.js'
+export { UserRole, RegisterSchema, LoginSchema, PinLoginSchema, SetPinSchema } from './auth.schema.js'
-export type { RegisterInput, LoginInput } from './auth.schema.js'
+export type { RegisterInput, LoginInput, PinLoginInput, SetPinInput } from './auth.schema.js'
 
 export {
   BillingMode,