@porulle/plugin-pos 0.8.0 → 0.10.0

package/dist/services/pin-service.js

@@ -1,6 +1,7 @@
 import { eq, and } from "@porulle/core/drizzle";
 import { Ok, Err } from "@porulle/core";
-import { posOperatorPins, posShifts } from "../schema.js";
+import { user } from "@porulle/core/auth-schema";
+import { posOperatorPins, posPinAttempts, posShifts } from "../schema.js";
 /**
  * PIN auth runtime (issue #51).
  *
@@ -12,6 +13,9 @@ import { posOperatorPins, posShifts } from "../schema.js";
  * `canOverride` and returns an audited approval.
  */
 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";
 function toBase64(bytes) {
     let binary = "";
     for (const b of bytes)
@@ -48,6 +52,22 @@ export async function verifyPinHash(pin, encoded) {
         diff |= actual[i] ^ expected[i];
     return diff === 0;
 }
+async function ensureOperatorUser(db, operatorId) {
+    // 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 {
     db;
     options;
@@ -55,6 +75,60 @@ export class PinService {
         this.db = db;
         this.options = options;
     }
+    lockoutMaxAttempts() {
+        return this.options.lockoutMaxAttempts ?? DEFAULT_LOCKOUT_MAX_ATTEMPTS;
+    }
+    lockoutWindowMs() {
+        const minutes = this.options.lockoutWindowMinutes ?? DEFAULT_LOCKOUT_WINDOW_MINUTES;
+        return minutes * 60 * 1000;
+    }
+    async getPinAttempt(orgId, operatorId) {
+        const rows = await this.db
+            .select()
+            .from(posPinAttempts)
+            .where(and(eq(posPinAttempts.organizationId, orgId), eq(posPinAttempts.operatorId, operatorId)));
+        return rows[0];
+    }
+    isLockedOut(attempt, now) {
+        return attempt?.lockedUntil != null && attempt.lockedUntil > now;
+    }
+    async recordFailedPinAttempt(orgId, operatorId) {
+        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,
+            });
+        }
+    }
+    async clearPinAttempts(orgId, operatorId) {
+        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, input) {
         if (!/^\d{4,8}$/.test(input.pin)) {
             return Err("PIN must be 4-8 digits");
@@ -85,14 +159,25 @@ export class PinService {
         return Ok({ operatorId: input.operatorId, canOverride: input.canOverride ?? false });
     }
     async verifyOperatorPin(orgId, operatorId, pin) {
+        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)
             .where(and(eq(posOperatorPins.organizationId, orgId), eq(posOperatorPins.operatorId, operatorId)));
         const record = rows[0];
-        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 };
     }
     /**
      * PIN login: verifies the PIN, resolves the operator's open shift, and
@@ -100,8 +185,10 @@ export class PinService {
      * authenticates this call (pos:operate); the returned key is personal.
      */
     async pinLogin(orgId, input, auth) {
-        const record = await this.verifyOperatorPin(orgId, input.operatorId, input.pin);
-        if (!record)
+        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),
@@ -117,22 +204,31 @@ export class PinService {
         if (!auth) {
             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",
-            },
-        }));
+        let created;
+        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",
+                },
+            }));
+        }
+        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.
@@ -156,10 +252,12 @@ export class PinService {
      * canOverride) and returns an approval envelope for the requested action.
      */
     async override(orgId, input) {
-        const record = await this.verifyOperatorPin(orgId, input.operatorId, input.pin);
-        if (!record)
+        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 (!record.canOverride)
+        if (!verified.record.canOverride)
             return Err("This operator cannot approve overrides");
         return Ok({
             approved: true,

package/dist/services/transaction-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transaction-service.d.ts","sourceRoot":"","sources":["../../src/services/transaction-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,EAAE,EAAE,WAAW,EAAqB,MAAM,aAAa,CAAC;AAEtE,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,WAAW;gBADX,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC;IAGvE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE;QACjC,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;QACtC,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IA4BhC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAUtE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAclF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAcrE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC;IAcjF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAgCnF,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAc9F,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;QACrC,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOX,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;YAgExE,qBAAqB;CA0BpC"}
+{"version":3,"file":"transaction-service.d.ts","sourceRoot":"","sources":["../../src/services/transaction-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,EAAE,EAAE,WAAW,EAAqB,MAAM,aAAa,CAAC;AAEtE,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,WAAW;gBADX,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC;IAGvE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE;QACjC,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;QACtC,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IA4BhC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAUtE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAclF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAcrE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC;IAcjF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAgCnF,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAc9F,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;QACrC,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOX,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;YAgExE,qBAAqB;CA2BpC"}

package/dist/services/transaction-service.js

@@ -16,7 +16,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)
             .values({
@@ -99,7 +99,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]);
         });
         return result;
@@ -172,7 +172,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);
         });
@@ -180,7 +180,7 @@ export class TransactionService {
     }
     // ─── Receipt Number Generation ─────────────────────────────────────
     // Sequential per terminal per day: {terminal_code}-{sequence}
-    async generateReceiptNumber(terminalId) {
+    async generateReceiptNumber(orgId, terminalId) {
         const today = new Date();
         const startOfDay = new Date(today.getFullYear(), today.getMonth(), today.getDate());
         const startOfDayISO = startOfDay.toISOString();
@@ -195,7 +195,7 @@ export class TransactionService {
         const countRows = await this.db
             .select({ count: sql `COUNT(*)`.as("count") })
             .from(posTransactions)
-            .where(and(eq(posTransactions.terminalId, terminalId), sql `${posTransactions.createdAt} >= ${startOfDayISO}::timestamptz`));
+            .where(and(eq(posTransactions.organizationId, orgId), eq(posTransactions.terminalId, terminalId), sql `${posTransactions.createdAt} >= ${startOfDayISO}::timestamptz`));
         const seq = Number(countRows[0]?.count ?? 0) + 1;
         return `${terminalCode}-${String(seq).padStart(4, "0")}`;
     }

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 export type { PluginDb as Db } from "@porulle/core";
-import type { posTerminals, posShifts, posCashEvents, posTransactions, posPayments, posReturnItems, posOperatorPins } from "./schema.js";
+import type { posTerminals, posShifts, posCashEvents, posTransactions, posPayments, posReturnItems, posOperatorPins, posPinAttempts } from "./schema.js";
 export type Terminal = typeof posTerminals.$inferSelect;
 export type TerminalInsert = typeof posTerminals.$inferInsert;
 export type Shift = typeof posShifts.$inferSelect;
@@ -14,6 +14,8 @@ export type ReturnItem = typeof posReturnItems.$inferSelect;
 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";
@@ -33,6 +35,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;
     };
 }
 export declare const DEFAULT_POS_OPTIONS: Required<POSPluginOptions>;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,aAAa,EACb,eAAe,EACf,WAAW,EACX,cAAc,EACd,eAAe,EAChB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,QAAQ,GAAG,OAAO,YAAY,CAAC,YAAY,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,OAAO,YAAY,CAAC,YAAY,CAAC;AAE9D,MAAM,MAAM,KAAK,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AAClD,MAAM,MAAM,WAAW,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AAExD,MAAM,MAAM,SAAS,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC;AAC1D,MAAM,MAAM,eAAe,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC;AAEhE,MAAM,MAAM,WAAW,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAEpE,MAAM,MAAM,OAAO,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC;AACtD,MAAM,MAAM,aAAa,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC;AAE5D,MAAM,MAAM,UAAU,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAElE,MAAM,MAAM,WAAW,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAEpE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AACzE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAC7D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,cAAc,GAAG,OAAO,CAAC;AACrF,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AACjF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC;AAC5C,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,oCAAoC;IACpC,OAAO,CAAC,EAAE;QACR,kEAAkE;QAClE,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,kEAAkE;QAClE,oBAAoB,CAAC,EAAE,MAAM,CAAC;KAC/B,CAAC;CACH;AAED,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,gBAAgB,CAK1D,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,aAAa,EACb,eAAe,EACf,WAAW,EACX,cAAc,EACd,eAAe,EACf,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,QAAQ,GAAG,OAAO,YAAY,CAAC,YAAY,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,OAAO,YAAY,CAAC,YAAY,CAAC;AAE9D,MAAM,MAAM,KAAK,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AAClD,MAAM,MAAM,WAAW,GAAG,OAAO,SAAS,CAAC,YAAY,CAAC;AAExD,MAAM,MAAM,SAAS,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC;AAC1D,MAAM,MAAM,eAAe,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC;AAEhE,MAAM,MAAM,WAAW,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAEpE,MAAM,MAAM,OAAO,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC;AACtD,MAAM,MAAM,aAAa,GAAG,OAAO,WAAW,CAAC,YAAY,CAAC;AAE5D,MAAM,MAAM,UAAU,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAElE,MAAM,MAAM,WAAW,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AAEpE,MAAM,MAAM,UAAU,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,cAAc,CAAC,YAAY,CAAC;AAElE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AACzE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAC7D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,cAAc,GAAG,OAAO,CAAC;AACrF,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AACjF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC;AAC5C,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,oCAAoC;IACpC,OAAO,CAAC,EAAE;QACR,kEAAkE;QAClE,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,kEAAkE;QAClE,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,+DAA+D;QAC/D,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,qFAAqF;QACrF,oBAAoB,CAAC,EAAE,MAAM,CAAC;KAC/B,CAAC;CACH;AAED,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,gBAAgB,CAK1D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-pos",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -19,16 +19,16 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.8.0",
-    "@porulle/db": "0.8.0"
+    "@porulle/db": "0.10.0",
+    "@porulle/core": "0.10.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
     "eslint": "^9.39.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
-    "@porulle/eslint-config": "0.1.0",
-    "@porulle/typescript-config": "0.1.0"
+    "@porulle/typescript-config": "0.1.0",
+    "@porulle/eslint-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/hooks/checkout-pos.ts

@@ -5,7 +5,7 @@
  * checkout.afterCreate: Updates POS transaction with orderId, increments shift counters.
  */
 
-import { eq, sql } from "@porulle/core/drizzle";
+import { eq, and, sql } from "@porulle/core/drizzle";
 import { posTransactions, posShifts } from "../schema.js";
 import type { Db } from "../types.js";
 
@@ -79,6 +79,13 @@ export function buildPOSFinalizationHook(getDb: () => Db) {
       // Increment shift sales counters
       const posShiftId = metadata?.posShiftId as string | undefined;
       if (posShiftId) {
+        const txnRows = await db
+          .select({ organizationId: posTransactions.organizationId })
+          .from(posTransactions)
+          .where(eq(posTransactions.id, posTransactionId));
+        const orgId = txnRows[0]?.organizationId;
+        if (!orgId) return;
+
         await db
           .update(posShifts)
           .set({
@@ -86,7 +93,7 @@ export function buildPOSFinalizationHook(getDb: () => Db) {
             salesTotal: sql`${posShifts.salesTotal} + ${result.grandTotal ?? 0}`,
             updatedAt: new Date(),
           })
-          .where(eq(posShifts.id, posShiftId));
+          .where(and(eq(posShifts.id, posShiftId), eq(posShifts.organizationId, orgId)));
       }
     },
   };

package/src/index.ts

@@ -7,6 +7,7 @@ import {
   posPayments,
   posReturnItems,
   posOperatorPins,
+  posPinAttempts,
 } from "./schema.js";
 import { TerminalService } from "./services/terminal-service.js";
 import { ShiftService } from "./services/shift-service.js";
@@ -92,6 +93,7 @@ export function posPlugin(userOptions: POSPluginOptions = {}) {
       posPayments,
       posReturnItems,
       posOperatorPins,
+      posPinAttempts,
     }),
 
     // Scope used by PIN login to mint per-shift credentials (issue #51).
@@ -100,6 +102,7 @@ export function posPlugin(userOptions: POSPluginOptions = {}) {
         prefix: "pos_shift_",
         description: "Short-lived per-shift POS credentials minted by PIN login.",
         permissions: { pos: ["operate"] },
+        enableMetadata: true,
         // Allow credentials as short as 15 minutes (Better Auth default
         // minimum is 1 day — too long for per-shift keys).
         keyExpiration: { minExpiresIn: 1 / 96 },

package/src/routes/auth.ts

@@ -1,8 +1,13 @@
-import { router } from "@porulle/core";
+import { router, CommerceValidationError } from "@porulle/core";
 import { z } from "@hono/zod-openapi";
-import type { PinService, PinAuthApi } from "../services/pin-service.js";
+import { PIN_LOCKOUT_ERROR, type PinService, type PinAuthApi } from "../services/pin-service.js";
 import type { PluginRouteRegistration } from "@porulle/core";
 
+function throwPinRouteError(message: string): never {
+  if (message === PIN_LOCKOUT_ERROR) throw new CommerceValidationError(message);
+  throw new Error(message);
+}
+
 /**
  * PIN auth runtime (issue #51).
  *
@@ -29,7 +34,7 @@ export function buildPinAuthRoutes(
     .handler(async ({ input, orgId }) => {
       const body = input as { operatorId: string; pin: string; canOverride?: boolean };
       const result = await service.setPin(orgId, body);
-      if (!result.ok) throw new Error(result.error);
+      if (!result.ok) throwPinRouteError(result.error);
       return result.value;
     });
 
@@ -44,7 +49,7 @@ export function buildPinAuthRoutes(
     .handler(async ({ input, orgId }) => {
       const body = input as { operatorId: string; pin: string; shiftId?: string };
       const result = await service.pinLogin(orgId, body, ctx.auth as PinAuthApi | undefined);
-      if (!result.ok) throw new Error(result.error);
+      if (!result.ok) throwPinRouteError(result.error);
       return result.value;
     });
 
@@ -59,7 +64,7 @@ export function buildPinAuthRoutes(
     .handler(async ({ input, orgId }) => {
       const body = input as { operatorId: string; pin: string; action: string };
       const result = await service.override(orgId, body);
-      if (!result.ok) throw new Error(result.error);
+      if (!result.ok) throwPinRouteError(result.error);
       return result.value;
     });
 

package/src/routes/returns.ts

@@ -26,7 +26,8 @@ export function buildReturnRoutes(
         quantity: z.number().int().positive(),
         reason: z.enum(["defective", "wrong_item", "changed_mind", "other"]),
         restockingFee: z.number().int().min(0).optional(),
-        refundAmount: z.number().int().positive(),
+        // refundAmount is NOT accepted from the client — it is computed
+        // server-side from the original order (SEC-08).
       })).min(1),
     }))
     .handler(async ({ input, actor, orgId }) => {
@@ -39,7 +40,6 @@ export function buildReturnRoutes(
           quantity: number;
           reason: "defective" | "wrong_item" | "changed_mind" | "other";
           restockingFee?: number;
-          refundAmount: number;
         }>;
       };
 
@@ -62,18 +62,60 @@ export function buildReturnRoutes(
       });
       if (!txnResult.ok) throw new Error(txnResult.error);
 
-      // Record return items
+      // SEC-08: derive the refund server-side via orders.refundLines (the same
+      // primitive the exchange flow uses). It validates the order + line items
+      // belong to this org, enforces the per-line refundable quantity
+      // (quantity - refundedQuantity) and updates that ledger — so a fabricated
+      // or foreign order, an over-refund, or a repeat refund of the same units
+      // is rejected — and computes the amount from the recorded sale price. The
+      // client can no longer set the refund amount.
+      const orders = ctx.services?.orders as
+        | {
+            refundLines(
+              orderId: string,
+              refundInput: { lines: Array<{ lineItemId: string; quantity: number }>; reason?: string },
+              actor: unknown,
+            ): Promise<{
+              ok: boolean;
+              value?: { refund: { amount: number; lines: Array<{ lineItemId: string; quantity: number; amount: number }> } };
+              error?: { message?: string };
+            }>;
+          }
+        | undefined;
+      if (!orders?.refundLines) {
+        throw new Error("Orders service unavailable for return refund");
+      }
+
+      const refundResult = await orders.refundLines(
+        body.originalOrderId,
+        {
+          lines: body.items.map((i) => ({ lineItemId: i.originalLineItemId, quantity: i.quantity })),
+          reason: "pos_return",
+        },
+        actor,
+      );
+      if (!refundResult.ok || !refundResult.value) {
+        throw new Error(
+          refundResult.error?.message ??
+            "Return could not be validated against the original order.",
+        );
+      }
+      const serverAmountByLine = new Map(
+        refundResult.value.refund.lines.map((l) => [l.lineItemId, l.amount]),
+      );
+      const refundTotal = refundResult.value.refund.amount;
+
+      // Record return items with the SERVER-computed refund amounts
       const itemsResult = await returnService.addReturnItems(
         txnResult.value.id,
         body.items.map((item) => ({
           ...item,
           originalOrderId: body.originalOrderId,
+          refundAmount: serverAmountByLine.get(item.originalLineItemId) ?? 0,
         })),
       );
       if (!itemsResult.ok) throw new Error(itemsResult.error);
 
-      // Update transaction totals
-      const refundTotal = body.items.reduce((sum, i) => sum + i.refundAmount, 0);
       await transactionService.updateTotals(txnResult.value.id, {
         subtotal: refundTotal,
         taxTotal: 0,

package/src/schema.ts

@@ -134,6 +134,19 @@ export const posOperatorPins = pgTable("pos_operator_pins", {
   orgOperatorUnique: uniqueIndex("pos_operator_pins_org_operator_unique").on(table.organizationId, table.operatorId),
 }));
 
+// ─── PIN attempt lockout (SEC-15) ───────────────────────────────────────
+
+export const posPinAttempts = pgTable("pos_pin_attempts", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  operatorId: text("operator_id").notNull(),
+  failedCount: integer("failed_count").notNull().default(0),
+  lockedUntil: timestamp("locked_until", { withTimezone: true }),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgOperatorUnique: uniqueIndex("pos_pin_attempts_org_operator_unique").on(table.organizationId, table.operatorId),
+}));
+
 // ─── Return Items ───────────────────────────────────────────────────────
 
 export const posReturnItems = pgTable("pos_return_items", {

package/src/services/exchange-service.ts

@@ -40,6 +40,19 @@ export interface ExchangeInput {
   }>;
 }
 
+interface PricingService {
+  resolve(
+    input: {
+      entityId: string;
+      variantId?: string | undefined;
+      currency: string;
+      quantity: number;
+    },
+    actor: unknown,
+    ctx?: unknown,
+  ): Promise<{ ok: boolean; value?: { finalAmount: number }; error?: { message?: string } }>;
+}
+
 interface CoreOrdersService {
   refundLines(
     orderId: string,
@@ -51,6 +64,7 @@ interface CoreOrdersService {
     input: Record<string, unknown>,
     actor: unknown,
     ctx?: unknown,
+    opts?: { trustedPricing?: boolean; stockPolicy?: "reserve" | "backorder" },
   ): Promise<{ ok: boolean; value?: { id: string; grandTotal: number }; error?: { message?: string } }>;
 }
 
@@ -79,15 +93,37 @@ export class ExchangeService {
     if (input.replacementItems.length === 0) return Err("At least one replacement item is required");
 
     const orders = this.services.orders as CoreOrdersService;
+    const pricing = this.services.pricing as PricingService;
     const currency = input.currency ?? "USD";
 
-    const subtotal = input.replacementItems.reduce((sum, i) => sum + i.unitPrice * i.quantity, 0);
-    const taxTotal = input.replacementItems.reduce((sum, i) => sum + (i.taxAmount ?? 0), 0);
-    const replacementTotal = subtotal + taxTotal;
-
     // Atomic core half: refund the returned lines + create the replacement.
     const core = await this.transaction(async (tx) => {
       const txCtx = { tx, actor };
+
+      const pricedReplacements: Array<ExchangeInput["replacementItems"][number] & { unitPrice: number }> = [];
+      for (const item of input.replacementItems) {
+        const resolved = await pricing.resolve(
+          {
+            entityId: item.entityId,
+            currency,
+            quantity: item.quantity,
+            ...(item.variantId ? { variantId: item.variantId } : {}),
+          },
+          actor,
+          txCtx,
+        );
+        if (!resolved.ok || !resolved.value) {
+          throw new Error(
+            resolved.error?.message ?? `Cannot resolve price for replacement item ${item.entityId}`,
+          );
+        }
+        pricedReplacements.push({ ...item, unitPrice: resolved.value.finalAmount });
+      }
+
+      const subtotal = pricedReplacements.reduce((sum, i) => sum + i.unitPrice * i.quantity, 0);
+      const taxTotal = pricedReplacements.reduce((sum, i) => sum + (i.taxAmount ?? 0), 0);
+      const replacementTotal = subtotal + taxTotal;
+
       const refund = await orders.refundLines(
         input.originalOrderId,
         {
@@ -118,7 +154,7 @@ export class ExchangeService {
               refundId: refund.value.refund.id,
             },
           },
-          lineItems: input.replacementItems.map((item) => ({
+          lineItems: pricedReplacements.map((item) => ({
             entityId: item.entityId,
             entityType: "product",
             ...(item.variantId ? { variantId: item.variantId } : {}),
@@ -132,17 +168,26 @@ export class ExchangeService {
         },
         actor,
         txCtx,
+        // Prices are server-resolved above (pricing.resolve); reserve stock for
+        // the replacement items so an exchange cannot oversell.
+        { trustedPricing: true, stockPolicy: "reserve" },
       );
       if (!replacement.ok || !replacement.value) {
         throw new Error(replacement.error?.message ?? "Replacement order creation failed");
       }
-      return { refund: refund.value.refund, replacementOrder: replacement.value };
+      return {
+        refund: refund.value.refund,
+        replacementOrder: replacement.value,
+        subtotal,
+        taxTotal,
+        replacementTotal,
+      };
     }).catch((error: unknown) => error as Error);
 
     if (core instanceof Error) return Err(core.message);
 
     const returnTotal = core.refund.amount;
-    const netDelta = replacementTotal - returnTotal;
+    const netDelta = core.replacementTotal - returnTotal;
 
     // POS bookkeeping (post-commit): cart + exchange transaction + return rows.
     const cart = this.services.cart as {
@@ -178,8 +223,8 @@ export class ExchangeService {
     );
 
     await this.transactionService.updateTotals(txn.id, {
-      subtotal,
-      taxTotal,
+      subtotal: core.subtotal,
+      taxTotal: core.taxTotal,
       total: netDelta,
       discountTotal: 0,
     });
@@ -194,7 +239,7 @@ export class ExchangeService {
             refundId: core.refund.id,
             replacementOrderId: core.replacementOrder.id,
             returnTotal,
-            replacementTotal,
+            replacementTotal: core.replacementTotal,
             netDelta,
           },
         },
@@ -220,7 +265,7 @@ export class ExchangeService {
       refundId: core.refund.id,
       returnTotal,
       replacementOrderId: core.replacementOrder.id,
-      replacementTotal,
+      replacementTotal: core.replacementTotal,
       netDelta,
     });
   }