@porulle/plugin-pos 0.8.0 → 0.9.0

package/src/services/pin-service.ts

@@ -1,8 +1,9 @@
 import { eq, and } from "@porulle/core/drizzle";
 import { Ok, Err } from "@porulle/core";
 import type { PluginResult } from "@porulle/core";
-import { posOperatorPins, posShifts } from "../schema.js";
-import type { Db, OperatorPin, Shift } from "../types.js";
+import { user } from "@porulle/core/auth-schema";
+import { posOperatorPins, posPinAttempts, posShifts } from "../schema.js";
+import type { Db, OperatorPin, PinAttempt, Shift } from "../types.js";
 
 /**
  * PIN auth runtime (issue #51).
@@ -16,6 +17,14 @@ import type { Db, OperatorPin, Shift } from "../types.js";
  */
 
 const PBKDF2_ITERATIONS = 100_000;
+const DEFAULT_LOCKOUT_MAX_ATTEMPTS = 5;
+const DEFAULT_LOCKOUT_WINDOW_MINUTES = 15;
+export const PIN_LOCKOUT_ERROR = "Too many failed PIN attempts; try again later";
+
+type PinVerifyOutcome =
+  | { status: "ok"; record: OperatorPin }
+  | { status: "locked" }
+  | { status: "invalid" };
 
 /** Narrow Better Auth surface the PIN runtime uses. */
 export interface PinAuthApi {
@@ -70,6 +79,23 @@ export async function verifyPinHash(pin: string, encoded: string): Promise<boole
   return diff === 0;
 }
 
+async function ensureOperatorUser(db: Db, operatorId: string): Promise<void> {
+  // SEC-16/R-01: ensure ONLY a user row exists so a user-referenced API key can
+  // be minted. We create NO org membership and grant NO role — better-auth's
+  // org-referenced keys require owner/admin (a cashier->owner escalation), so
+  // the key is user-referenced and carries the operator's store in metadata,
+  // read back by authMiddleware.
+  const users = await db.select().from(user).where(eq(user.id, operatorId));
+  if (users.length === 0) {
+    await db.insert(user).values({
+      id: operatorId,
+      name: operatorId,
+      email: `${operatorId}@pos.local`,
+      emailVerified: true,
+    });
+  }
+}
+
 export class PinService {
   constructor(
     private db: Db,
@@ -78,9 +104,80 @@ export class PinService {
       apiKeyScope?: string | undefined;
       /** Shift-credential lifetime in seconds. Default: 12h. */
       credentialTtlSeconds?: number | undefined;
+      /** Failed PIN attempts before lockout (SEC-15). Default: 5. */
+      lockoutMaxAttempts?: number | undefined;
+      /** Failure window and lockout duration in minutes (SEC-15). Default: 15. */
+      lockoutWindowMinutes?: number | undefined;
     } = {},
   ) {}
 
+  private lockoutMaxAttempts(): number {
+    return this.options.lockoutMaxAttempts ?? DEFAULT_LOCKOUT_MAX_ATTEMPTS;
+  }
+
+  private lockoutWindowMs(): number {
+    const minutes = this.options.lockoutWindowMinutes ?? DEFAULT_LOCKOUT_WINDOW_MINUTES;
+    return minutes * 60 * 1000;
+  }
+
+  private async getPinAttempt(
+    orgId: string,
+    operatorId: string,
+  ): Promise<PinAttempt | undefined> {
+    const rows = await this.db
+      .select()
+      .from(posPinAttempts)
+      .where(and(
+        eq(posPinAttempts.organizationId, orgId),
+        eq(posPinAttempts.operatorId, operatorId),
+      ));
+    return rows[0] as PinAttempt | undefined;
+  }
+
+  private isLockedOut(attempt: PinAttempt | undefined, now: Date): boolean {
+    return attempt?.lockedUntil != null && attempt.lockedUntil > now;
+  }
+
+  private async recordFailedPinAttempt(orgId: string, operatorId: string): Promise<void> {
+    const now = new Date();
+    const windowMs = this.lockoutWindowMs();
+    const maxAttempts = this.lockoutMaxAttempts();
+    const existing = await this.getPinAttempt(orgId, operatorId);
+
+    let failedCount = 1;
+    if (existing) {
+      const windowExpired = now.getTime() - existing.updatedAt.getTime() > windowMs;
+      failedCount = windowExpired ? 1 : existing.failedCount + 1;
+    }
+
+    const lockedUntil = failedCount >= maxAttempts
+      ? new Date(now.getTime() + windowMs)
+      : null;
+
+    if (existing) {
+      await this.db
+        .update(posPinAttempts)
+        .set({ failedCount, lockedUntil, updatedAt: now })
+        .where(eq(posPinAttempts.id, existing.id));
+    } else {
+      await this.db.insert(posPinAttempts).values({
+        organizationId: orgId,
+        operatorId,
+        failedCount,
+        lockedUntil,
+      });
+    }
+  }
+
+  private async clearPinAttempts(orgId: string, operatorId: string): Promise<void> {
+    const existing = await this.getPinAttempt(orgId, operatorId);
+    if (!existing) return;
+    await this.db
+      .update(posPinAttempts)
+      .set({ failedCount: 0, lockedUntil: null, updatedAt: new Date() })
+      .where(eq(posPinAttempts.id, existing.id));
+  }
+
   async setPin(
     orgId: string,
     input: { operatorId: string; pin: string; canOverride?: boolean | undefined },
@@ -120,7 +217,11 @@ export class PinService {
     orgId: string,
     operatorId: string,
     pin: string,
-  ): Promise<OperatorPin | null> {
+  ): Promise<PinVerifyOutcome> {
+    const now = new Date();
+    const attempt = await this.getPinAttempt(orgId, operatorId);
+    if (this.isLockedOut(attempt, now)) return { status: "locked" };
+
     const rows = await this.db
       .select()
       .from(posOperatorPins)
@@ -129,8 +230,18 @@ export class PinService {
         eq(posOperatorPins.operatorId, operatorId),
       ));
     const record = rows[0] as OperatorPin | undefined;
-    if (!record) return null;
-    return (await verifyPinHash(pin, record.pinHash)) ? record : null;
+    if (!record) {
+      await this.recordFailedPinAttempt(orgId, operatorId);
+      return { status: "invalid" };
+    }
+
+    if (!(await verifyPinHash(pin, record.pinHash))) {
+      await this.recordFailedPinAttempt(orgId, operatorId);
+      return { status: "invalid" };
+    }
+
+    await this.clearPinAttempts(orgId, operatorId);
+    return { status: "ok", record };
   }
 
   /**
@@ -149,8 +260,9 @@ export class PinService {
     apiKey: string;
     expiresAt: string;
   }>> {
-    const record = await this.verifyOperatorPin(orgId, input.operatorId, input.pin);
-    if (!record) return Err("Invalid operator or PIN");
+    const verified = await this.verifyOperatorPin(orgId, input.operatorId, input.pin);
+    if (verified.status === "locked") return Err(PIN_LOCKOUT_ERROR);
+    if (verified.status !== "ok") return Err("Invalid operator or PIN");
 
     const conditions = [
       eq(posShifts.organizationId, orgId),
@@ -166,22 +278,31 @@ export class PinService {
       return Err("PIN login requires the Better Auth instance (plugin ctx.auth) — are routes mounted by createServer?");
     }
 
+    await ensureOperatorUser(this.db, input.operatorId);
+
     const ttlSeconds = this.options.credentialTtlSeconds ?? 12 * 3600;
-    const created = (await auth.api.createApiKey({
-      body: {
-        // Better Auth caps name length at 32; the full shift id lives on the
-        // shift row (metadata.pinLoginApiKeyId links back).
-        name: `pos-shift-${shift.id.slice(0, 8)}`,
-        userId: input.operatorId,
-        expiresIn: ttlSeconds,
-        permissions: { pos: ["operate"] },
-        // Shift/terminal binding is recorded on the shift row (metadata is
-        // disabled by default in Better Auth's apiKey plugin); the key name
-        // carries the shift id for traceability.
-        // The plugin registers this scope via its apiKeyScopes manifest.
-        configId: this.options.apiKeyScope ?? "pos",
-      },
-    })) as { key?: string; id?: string };
+    let created: { key?: string; id?: string };
+    try {
+      created = (await auth.api.createApiKey({
+        body: {
+          // Better Auth caps name length at 32; the full shift id lives on the
+          // shift row (metadata.pinLoginApiKeyId links back).
+          name: `pos-shift-${shift.id.slice(0, 8)}`,
+          userId: input.operatorId,
+          organizationId: orgId,
+          expiresIn: ttlSeconds,
+          permissions: { pos: ["operate"] },
+          metadata: { operatorId: input.operatorId, organizationId: orgId },
+          // Shift/terminal binding is recorded on the shift row; the key name
+          // carries the shift id for traceability.
+          // The plugin registers this scope via its apiKeyScopes manifest.
+          configId: this.options.apiKeyScope ?? "pos",
+        },
+      })) as { key?: string; id?: string };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to mint shift credential";
+      return Err(message);
+    }
     if (!created?.key) return Err("Failed to mint shift credential");
 
     // Record the credential on the shift so admins can trace/revoke it.
@@ -215,9 +336,10 @@ export class PinService {
     action: string;
     approvedAt: string;
   }>> {
-    const record = await this.verifyOperatorPin(orgId, input.operatorId, input.pin);
-    if (!record) return Err("Invalid operator or PIN");
-    if (!record.canOverride) return Err("This operator cannot approve overrides");
+    const verified = await this.verifyOperatorPin(orgId, input.operatorId, input.pin);
+    if (verified.status === "locked") return Err(PIN_LOCKOUT_ERROR);
+    if (verified.status !== "ok") return Err("Invalid operator or PIN");
+    if (!verified.record.canOverride) return Err("This operator cannot approve overrides");
     return Ok({
       approved: true,
       operatorId: input.operatorId,

package/src/services/transaction-service.ts

@@ -25,7 +25,7 @@ export class TransactionService {
       .where(and(eq(posShifts.id, input.shiftId), eq(posShifts.status, "open")));
     if (shifts.length === 0) return Err("Shift is not open");
 
-    const receiptNumber = await this.generateReceiptNumber(input.terminalId);
+    const receiptNumber = await this.generateReceiptNumber(orgId, input.terminalId);
 
     const rows = await this.db
       .insert(posTransactions)
@@ -121,7 +121,7 @@ export class TransactionService {
       await tx
         .update(posShifts)
         .set({ voidsCount: sql`${posShifts.voidsCount} + 1`, updatedAt: new Date() })
-        .where(eq(posShifts.id, txn.shiftId));
+        .where(and(eq(posShifts.id, txn.shiftId), eq(posShifts.organizationId, orgId)));
 
       return Ok(updated[0]!);
     });
@@ -207,7 +207,7 @@ export class TransactionService {
             salesTotal: sql`${posShifts.salesTotal} + ${paymentTotal}`,
             updatedAt: new Date(),
           })
-          .where(eq(posShifts.id, txn.shiftId));
+          .where(and(eq(posShifts.id, txn.shiftId), eq(posShifts.organizationId, txn.organizationId)));
       }
 
       return Ok(txn);
@@ -219,7 +219,7 @@ export class TransactionService {
   // ─── Receipt Number Generation ─────────────────────────────────────
   // Sequential per terminal per day: {terminal_code}-{sequence}
 
-  private async generateReceiptNumber(terminalId: string): Promise<string> {
+  private async generateReceiptNumber(orgId: string, terminalId: string): Promise<string> {
     const today = new Date();
     const startOfDay = new Date(today.getFullYear(), today.getMonth(), today.getDate());
     const startOfDayISO = startOfDay.toISOString();
@@ -238,6 +238,7 @@ export class TransactionService {
       .select({ count: sql<number>`COUNT(*)`.as("count") })
       .from(posTransactions)
       .where(and(
+        eq(posTransactions.organizationId, orgId),
         eq(posTransactions.terminalId, terminalId),
         sql`${posTransactions.createdAt} >= ${startOfDayISO}::timestamptz`,
       ));

package/src/types.ts

@@ -7,6 +7,7 @@ import type {
   posPayments,
   posReturnItems,
   posOperatorPins,
+  posPinAttempts,
 } from "./schema.js";
 
 export type Terminal = typeof posTerminals.$inferSelect;
@@ -30,6 +31,9 @@ export type ReturnItemInsert = typeof posReturnItems.$inferInsert;
 export type OperatorPin = typeof posOperatorPins.$inferSelect;
 export type OperatorPinInsert = typeof posOperatorPins.$inferInsert;
 
+export type PinAttempt = typeof posPinAttempts.$inferSelect;
+export type PinAttemptInsert = typeof posPinAttempts.$inferInsert;
+
 export type TransactionStatus = "open" | "held" | "completed" | "voided";
 export type TransactionType = "sale" | "return" | "exchange";
 export type PaymentMethod = "cash" | "card" | "gift_card" | "store_credit" | "other";
@@ -50,6 +54,10 @@ export interface POSPluginOptions {
     apiKeyScope?: string;
     /** Shift-credential lifetime in seconds. Default: 43200 (12h). */
     credentialTtlSeconds?: number;
+    /** Failed PIN attempts before lockout. Default: 5 (SEC-15). */
+    lockoutMaxAttempts?: number;
+    /** Failure counting window and lockout duration in minutes. Default: 15 (SEC-15). */
+    lockoutWindowMinutes?: number;
   };
 }