@porulle/plugin-pos 0.7.0 → 0.9.0

package/dist/services/exchange-service.d.ts

@@ -0,0 +1,55 @@
+import type { PluginResult } from "@porulle/core";
+import type { Db, Transaction } from "../types.js";
+import type { ReturnService } from "./return-service.js";
+import type { TransactionService } from "./transaction-service.js";
+/**
+ * Exchanges (issue #53): return line items + create a replacement order +
+ * settle the difference, in one call.
+ *
+ * The financially-critical half — the line-level refund on the original
+ * order (core issue #52 primitives: refundable-quantity enforcement, daily
+ * cap, audited ledger) and the replacement order creation — runs inside ONE
+ * database transaction, so a failure in either leaves no money moved and no
+ * order created. The POS bookkeeping rows (transaction, return items) are
+ * written after commit and cross-linked for audit.
+ */
+export interface ExchangeInput {
+    shiftId: string;
+    terminalId: string;
+    originalOrderId: string;
+    currency?: string | undefined;
+    customerId?: string | undefined;
+    returnItems: Array<{
+        originalLineItemId: string;
+        quantity: number;
+        reason: "defective" | "wrong_item" | "changed_mind" | "other";
+    }>;
+    replacementItems: Array<{
+        entityId: string;
+        variantId?: string | undefined;
+        sku?: string | undefined;
+        title: string;
+        quantity: number;
+        unitPrice: number;
+        taxAmount?: number | undefined;
+    }>;
+}
+export declare class ExchangeService {
+    private db;
+    private services;
+    private transaction;
+    private transactionService;
+    private returnService;
+    constructor(db: Db, services: Record<string, unknown>, transaction: <T>(fn: (tx: Db) => Promise<T>) => Promise<T>, transactionService: TransactionService, returnService: ReturnService);
+    exchange(orgId: string, input: ExchangeInput, actor: {
+        userId: string;
+    } & Record<string, unknown>): Promise<PluginResult<{
+        transaction: Transaction;
+        refundId: string;
+        returnTotal: number;
+        replacementOrderId: string;
+        replacementTotal: number;
+        netDelta: number;
+    }>>;
+}
+//# sourceMappingURL=exchange-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-service.d.ts","sourceRoot":"","sources":["../../src/services/exchange-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,KAAK,CAAC;QACjB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,OAAO,CAAC;KAC/D,CAAC,CAAC;IACH,gBAAgB,EAAE,KAAK,CAAC;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC/B,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACzB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAChC,CAAC,CAAC;CACJ;AA8BD,qBAAa,eAAe;IAExB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,kBAAkB;IAC1B,OAAO,CAAC,aAAa;gBAJb,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1D,kBAAkB,EAAE,kBAAkB,EACtC,aAAa,EAAE,aAAa;IAGhC,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClD,OAAO,CAAC,YAAY,CAAC;QACtB,WAAW,EAAE,WAAW,CAAC;QACzB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,gBAAgB,EAAE,MAAM,CAAC;QACzB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;CAqLJ"}

package/dist/services/exchange-service.js

@@ -0,0 +1,168 @@
+import { eq } from "@porulle/core/drizzle";
+import { Ok, Err } from "@porulle/core";
+import { posTransactions } from "../schema.js";
+export class ExchangeService {
+    db;
+    services;
+    transaction;
+    transactionService;
+    returnService;
+    constructor(db, services, transaction, transactionService, returnService) {
+        this.db = db;
+        this.services = services;
+        this.transaction = transaction;
+        this.transactionService = transactionService;
+        this.returnService = returnService;
+    }
+    async exchange(orgId, input, actor) {
+        if (input.returnItems.length === 0)
+            return Err("At least one return item is required");
+        if (input.replacementItems.length === 0)
+            return Err("At least one replacement item is required");
+        const orders = this.services.orders;
+        const pricing = this.services.pricing;
+        const currency = input.currency ?? "USD";
+        // Atomic core half: refund the returned lines + create the replacement.
+        const core = await this.transaction(async (tx) => {
+            const txCtx = { tx, actor };
+            const pricedReplacements = [];
+            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, {
+                lines: input.returnItems.map((item) => ({
+                    lineItemId: item.originalLineItemId,
+                    quantity: item.quantity,
+                })),
+                reason: "exchange",
+            }, actor, txCtx);
+            if (!refund.ok || !refund.value) {
+                throw new Error(refund.error?.message ?? "Exchange refund failed");
+            }
+            const replacement = await orders.create({
+                currency,
+                subtotal,
+                taxTotal,
+                shippingTotal: 0,
+                grandTotal: replacementTotal,
+                ...(input.customerId ? { customerId: input.customerId } : {}),
+                metadata: {
+                    exchange: {
+                        originalOrderId: input.originalOrderId,
+                        refundId: refund.value.refund.id,
+                    },
+                },
+                lineItems: pricedReplacements.map((item) => ({
+                    entityId: item.entityId,
+                    entityType: "product",
+                    ...(item.variantId ? { variantId: item.variantId } : {}),
+                    ...(item.sku ? { sku: item.sku } : {}),
+                    title: item.title,
+                    quantity: item.quantity,
+                    unitPrice: item.unitPrice,
+                    totalPrice: item.unitPrice * item.quantity,
+                    taxAmount: item.taxAmount ?? 0,
+                })),
+            }, 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,
+                subtotal,
+                taxTotal,
+                replacementTotal,
+            };
+        }).catch((error) => error);
+        if (core instanceof Error)
+            return Err(core.message);
+        const returnTotal = core.refund.amount;
+        const netDelta = core.replacementTotal - returnTotal;
+        // POS bookkeeping (post-commit): cart + exchange transaction + return rows.
+        const cart = this.services.cart;
+        const cartResult = await cart.create({ currency, metadata: { posExchange: true, originalOrderId: input.originalOrderId } }, actor);
+        if (!cartResult.ok || !cartResult.value)
+            return Err("Failed to create cart for exchange");
+        const txnResult = await this.transactionService.create(orgId, {
+            shiftId: input.shiftId,
+            terminalId: input.terminalId,
+            operatorId: actor.userId,
+            cartId: cartResult.value.id,
+            type: "exchange",
+            ...(input.customerId ? { customerId: input.customerId } : {}),
+        });
+        if (!txnResult.ok)
+            return Err(txnResult.error);
+        const txn = txnResult.value;
+        await this.returnService.addReturnItems(txn.id, input.returnItems.map((item) => ({
+            originalOrderId: input.originalOrderId,
+            originalLineItemId: item.originalLineItemId,
+            quantity: item.quantity,
+            reason: item.reason,
+            refundAmount: core.refund.lines.find((l) => l.lineItemId === item.originalLineItemId)?.amount ?? 0,
+        })));
+        await this.transactionService.updateTotals(txn.id, {
+            subtotal: core.subtotal,
+            taxTotal: core.taxTotal,
+            total: netDelta,
+            discountTotal: 0,
+        });
+        // Cross-link everything on the POS transaction for audit.
+        await this.db
+            .update(posTransactions)
+            .set({
+            orderId: core.replacementOrder.id,
+            metadata: {
+                exchange: {
+                    originalOrderId: input.originalOrderId,
+                    refundId: core.refund.id,
+                    replacementOrderId: core.replacementOrder.id,
+                    returnTotal,
+                    replacementTotal: core.replacementTotal,
+                    netDelta,
+                },
+            },
+            updatedAt: new Date(),
+        })
+            .where(eq(posTransactions.id, txn.id));
+        // An even exchange settles itself — nothing to tender.
+        let finalTxn = txn;
+        if (netDelta === 0) {
+            const completed = await this.transactionService.complete(txn.id, core.replacementOrder.id);
+            if (completed.ok)
+                finalTxn = completed.value;
+        }
+        else {
+            const rows = await this.db
+                .select()
+                .from(posTransactions)
+                .where(eq(posTransactions.id, txn.id));
+            if (rows[0])
+                finalTxn = rows[0];
+        }
+        return Ok({
+            transaction: finalTxn,
+            refundId: core.refund.id,
+            returnTotal,
+            replacementOrderId: core.replacementOrder.id,
+            replacementTotal: core.replacementTotal,
+            netDelta,
+        });
+    }
+}

package/dist/services/pin-service.d.ts

@@ -0,0 +1,73 @@
+import type { PluginResult } from "@porulle/core";
+import type { Db } from "../types.js";
+export declare const PIN_LOCKOUT_ERROR = "Too many failed PIN attempts; try again later";
+/** Narrow Better Auth surface the PIN runtime uses. */
+export interface PinAuthApi {
+    api: {
+        createApiKey(input: {
+            body: Record<string, unknown>;
+        }): Promise<unknown>;
+    };
+}
+export declare function hashPin(pin: string): Promise<string>;
+export declare function verifyPinHash(pin: string, encoded: string): Promise<boolean>;
+export declare class PinService {
+    private db;
+    private options;
+    constructor(db: Db, options?: {
+        /** Named auth.apiKeyScopes config used to mint shift keys (optional). */
+        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;
+    private lockoutWindowMs;
+    private getPinAttempt;
+    private isLockedOut;
+    private recordFailedPinAttempt;
+    private clearPinAttempts;
+    setPin(orgId: string, input: {
+        operatorId: string;
+        pin: string;
+        canOverride?: boolean | undefined;
+    }): Promise<PluginResult<{
+        operatorId: string;
+        canOverride: boolean;
+    }>>;
+    private verifyOperatorPin;
+    /**
+     * PIN login: verifies the PIN, resolves the operator's open shift, and
+     * mints a short-lived API key bound to it. The terminal's device key
+     * authenticates this call (pos:operate); the returned key is personal.
+     */
+    pinLogin(orgId: string, input: {
+        operatorId: string;
+        pin: string;
+        shiftId?: string | undefined;
+    }, auth: PinAuthApi | undefined): Promise<PluginResult<{
+        operatorId: string;
+        shiftId: string;
+        terminalId: string;
+        apiKey: string;
+        expiresAt: string;
+    }>>;
+    /**
+     * Manager override: verifies the manager's PIN (record must carry
+     * canOverride) and returns an approval envelope for the requested action.
+     */
+    override(orgId: string, input: {
+        operatorId: string;
+        pin: string;
+        action: string;
+    }): Promise<PluginResult<{
+        approved: true;
+        operatorId: string;
+        action: string;
+        approvedAt: string;
+    }>>;
+}
+//# sourceMappingURL=pin-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pin-service.d.ts","sourceRoot":"","sources":["../../src/services/pin-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,KAAK,EAAE,EAAE,EAAkC,MAAM,aAAa,CAAC;AAgBtE,eAAO,MAAM,iBAAiB,kDAAkD,CAAC;AAOjF,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE;QACH,YAAY,CAAC,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;KAC1E,CAAC;CACH;AA+BD,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAI1D;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASlF;AAmBD,qBAAa,UAAU;IAEnB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,OAAO;gBADP,EAAE,EAAE,EAAE,EACN,OAAO,GAAE;QACf,yEAAyE;QACzE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACjC,0DAA0D;QAC1D,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC1C,+DAA+D;QAC/D,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACxC,4EAA4E;QAC5E,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACtC;IAGR,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,eAAe;YAKT,aAAa;IAc3B,OAAO,CAAC,WAAW;YAIL,sBAAsB;YA+BtB,gBAAgB;IASxB,MAAM,CACV,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;KAAE,GAC5E,OAAO,CAAC,YAAY,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;YAgCxD,iBAAiB;IA+B/B;;;;OAIG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,EACxE,IAAI,EAAE,UAAU,GAAG,SAAS,GAC3B,OAAO,CAAC,YAAY,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;IAgEH;;;OAGG;IACG,QAAQ,CACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GACzD,OAAO,CAAC,YAAY,CAAC;QACtB,QAAQ,EAAE,IAAI,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CAYJ"}

package/dist/services/pin-service.js

@@ -0,0 +1,269 @@
+import { eq, and } from "@porulle/core/drizzle";
+import { Ok, Err } from "@porulle/core";
+import { user } from "@porulle/core/auth-schema";
+import { posOperatorPins, posPinAttempts, posShifts } from "../schema.js";
+/**
+ * PIN auth runtime (issue #51).
+ *
+ * PINs hash with PBKDF2-SHA256 via Web Crypto (Workers-safe, no Node-only
+ * APIs). PIN login verifies the operator's PIN against their open shift and
+ * mints a short-lived Better Auth API key scoped to POS operation — the
+ * per-shift credential POS apps previously hand-rolled through module-global
+ * auth holders. Manager override verifies a PIN whose record carries
+ * `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)
+        binary += String.fromCharCode(b);
+    return btoa(binary);
+}
+function fromBase64(value) {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+async function deriveHash(pin, salt, iterations) {
+    const keyMaterial = await crypto.subtle.importKey("raw", new TextEncoder().encode(pin), "PBKDF2", false, ["deriveBits"]);
+    const bits = await crypto.subtle.deriveBits({ name: "PBKDF2", hash: "SHA-256", salt: salt.slice().buffer, iterations }, keyMaterial, 256);
+    return new Uint8Array(bits);
+}
+export async function hashPin(pin) {
+    const salt = crypto.getRandomValues(new Uint8Array(16));
+    const hash = await deriveHash(pin, salt, PBKDF2_ITERATIONS);
+    return `pbkdf2$${PBKDF2_ITERATIONS}$${toBase64(salt)}$${toBase64(hash)}`;
+}
+export async function verifyPinHash(pin, encoded) {
+    const [scheme, iterationsRaw, saltB64, hashB64] = encoded.split("$");
+    if (scheme !== "pbkdf2" || !iterationsRaw || !saltB64 || !hashB64)
+        return false;
+    const expected = fromBase64(hashB64);
+    const actual = await deriveHash(pin, fromBase64(saltB64), Number(iterationsRaw));
+    if (actual.length !== expected.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < actual.length; i++)
+        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;
+    constructor(db, options = {}) {
+        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");
+        }
+        const pinHash = await hashPin(input.pin);
+        const existing = await this.db
+            .select()
+            .from(posOperatorPins)
+            .where(and(eq(posOperatorPins.organizationId, orgId), eq(posOperatorPins.operatorId, input.operatorId)));
+        if (existing.length > 0) {
+            await this.db
+                .update(posOperatorPins)
+                .set({
+                pinHash,
+                canOverride: input.canOverride ?? existing[0].canOverride,
+                updatedAt: new Date(),
+            })
+                .where(eq(posOperatorPins.id, existing[0].id));
+        }
+        else {
+            await this.db.insert(posOperatorPins).values({
+                organizationId: orgId,
+                operatorId: input.operatorId,
+                pinHash,
+                canOverride: input.canOverride ?? false,
+            });
+        }
+        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) {
+            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
+     * mints a short-lived API key bound to it. The terminal's device key
+     * authenticates this call (pos:operate); the returned key is personal.
+     */
+    async pinLogin(orgId, input, auth) {
+        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),
+            eq(posShifts.operatorId, input.operatorId),
+            eq(posShifts.status, "open"),
+        ];
+        if (input.shiftId)
+            conditions.push(eq(posShifts.id, input.shiftId));
+        const shifts = await this.db.select().from(posShifts).where(and(...conditions));
+        const shift = shifts[0];
+        if (!shift)
+            return Err("No open shift for this operator — open a shift first");
+        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;
+        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.
+        await this.db
+            .update(posShifts)
+            .set({
+            metadata: { ...(shift.metadata ?? {}), pinLoginApiKeyId: created.id ?? null },
+            updatedAt: new Date(),
+        })
+            .where(eq(posShifts.id, shift.id));
+        return Ok({
+            operatorId: input.operatorId,
+            shiftId: shift.id,
+            terminalId: shift.terminalId,
+            apiKey: created.key,
+            expiresAt: new Date(Date.now() + ttlSeconds * 1000).toISOString(),
+        });
+    }
+    /**
+     * Manager override: verifies the manager's PIN (record must carry
+     * canOverride) and returns an approval envelope for the requested action.
+     */
+    async override(orgId, input) {
+        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,
+            action: input.action,
+            approvedAt: new Date().toISOString(),
+        });
+    }
+}

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 } 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;
@@ -12,6 +12,10 @@ export type Payment = typeof posPayments.$inferSelect;
 export type PaymentInsert = typeof posPayments.$inferInsert;
 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";
@@ -25,6 +29,17 @@ export interface POSPluginOptions {
     maxHoldHours?: number;
     /** Require manager override for discounts above this percentage. Default: 20 */
     discountOverrideThreshold?: number;
+    /** PIN auth runtime (issue #51). */
+    pinAuth?: {
+        /** Named auth.apiKeyScopes config used to mint per-shift keys. */
+        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>;
 //# sourceMappingURL=types.d.ts.map