@porulle/plugin-pos 0.6.0 → 0.8.0

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

@@ -0,0 +1,62 @@
+import type { PluginResult } from "@porulle/core";
+import type { Db } from "../types.js";
+/** 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;
+    });
+    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;AAElD,OAAO,KAAK,EAAE,EAAE,EAAsB,MAAM,aAAa,CAAC;AAe1D,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;AAED,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;KACtC;IAGF,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;IAiB/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;IAsDH;;;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;CAWJ"}

package/dist/services/pin-service.js

@@ -0,0 +1,171 @@
+import { eq, and } from "@porulle/core/drizzle";
+import { Ok, Err } from "@porulle/core";
+import { posOperatorPins, 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;
+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;
+}
+export class PinService {
+    db;
+    options;
+    constructor(db, options = {}) {
+        this.db = db;
+        this.options = options;
+    }
+    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 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;
+    }
+    /**
+     * 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 record = await this.verifyOperatorPin(orgId, input.operatorId, input.pin);
+        if (!record)
+            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?");
+        }
+        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",
+            },
+        }));
+        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 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");
+        return Ok({
+            approved: true,
+            operatorId: input.operatorId,
+            action: input.action,
+            approvedAt: new Date().toISOString(),
+        });
+    }
+}

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 } from "./schema.js";
 export type Terminal = typeof posTerminals.$inferSelect;
 export type TerminalInsert = typeof posTerminals.$inferInsert;
 export type Shift = typeof posShifts.$inferSelect;
@@ -12,6 +12,8 @@ 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 TransactionStatus = "open" | "held" | "completed" | "voided";
 export type TransactionType = "sale" | "return" | "exchange";
 export type PaymentMethod = "cash" | "card" | "gift_card" | "store_credit" | "other";
@@ -25,6 +27,13 @@ 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;
+    };
 }
 export declare const DEFAULT_POS_OPTIONS: Required<POSPluginOptions>;
 //# sourceMappingURL=types.d.ts.map

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,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,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;CACpC;AAED,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,gBAAgB,CAI1D,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,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"}

package/dist/types.js

@@ -2,4 +2,5 @@ export const DEFAULT_POS_OPTIONS = {
     defaultCurrency: "USD",
     maxHoldHours: 24,
     discountOverrideThreshold: 20,
+    pinAuth: {},
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-pos",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -19,8 +19,8 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.6.0",
-    "@porulle/db": "0.6.0"
+    "@porulle/core": "0.8.0",
+    "@porulle/db": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",

package/src/index.ts

@@ -6,6 +6,7 @@ import {
   posTransactions,
   posPayments,
   posReturnItems,
+  posOperatorPins,
 } from "./schema.js";
 import { TerminalService } from "./services/terminal-service.js";
 import { ShiftService } from "./services/shift-service.js";
@@ -14,6 +15,8 @@ import { PaymentService } from "./services/payment-service.js";
 import { ReturnService } from "./services/return-service.js";
 import { LookupService } from "./services/lookup-service.js";
 import { ReceiptService } from "./services/receipt-service.js";
+import { PinService } from "./services/pin-service.js";
+import { ExchangeService } from "./services/exchange-service.js";
 import { buildTerminalRoutes } from "./routes/terminals.js";
 import { buildShiftRoutes } from "./routes/shifts.js";
 import { buildTransactionRoutes } from "./routes/transactions.js";
@@ -21,6 +24,8 @@ import { buildPaymentRoutes } from "./routes/payments.js";
 import { buildReturnRoutes } from "./routes/returns.js";
 import { buildLookupRoutes } from "./routes/lookup.js";
 import { buildReceiptRoutes } from "./routes/receipts.js";
+import { buildPinAuthRoutes } from "./routes/auth.js";
+import { buildExchangeRoutes } from "./routes/exchanges.js";
 import { buildPOSShippingHook, buildPOSFinalizationHook } from "./hooks/checkout-pos.js";
 import type { POSPluginOptions, Db } from "./types.js";
 import { DEFAULT_POS_OPTIONS } from "./types.js";
@@ -33,6 +38,8 @@ export { PaymentService } from "./services/payment-service.js";
 export { ReturnService } from "./services/return-service.js";
 export { LookupService } from "./services/lookup-service.js";
 export { ReceiptService } from "./services/receipt-service.js";
+export { PinService, hashPin, verifyPinHash } from "./services/pin-service.js";
+export { ExchangeService } from "./services/exchange-service.js";
 export { createPOSPaymentAdapter } from "./payment-adapter.js";
 
 /**
@@ -84,6 +91,19 @@ export function posPlugin(userOptions: POSPluginOptions = {}) {
       posTransactions,
       posPayments,
       posReturnItems,
+      posOperatorPins,
+    }),
+
+    // Scope used by PIN login to mint per-shift credentials (issue #51).
+    apiKeyScopes: () => ({
+      [options.pinAuth.apiKeyScope ?? "pos"]: {
+        prefix: "pos_shift_",
+        description: "Short-lived per-shift POS credentials minted by PIN login.",
+        permissions: { pos: ["operate"] },
+        // Allow credentials as short as 15 minutes (Better Auth default
+        // minimum is 1 day — too long for per-shift keys).
+        keyExpiration: { minExpiresIn: 1 / 96 },
+      },
     }),
 
     hooks: () => [
@@ -111,6 +131,14 @@ export function posPlugin(userOptions: POSPluginOptions = {}) {
       const returnService = new ReturnService(db);
       const lookupService = new LookupService(db, ctx.services);
       const receiptService = new ReceiptService(db, ctx.services);
+      const pinService = new PinService(db, options.pinAuth);
+      const exchangeService = new ExchangeService(
+        db,
+        ctx.services,
+        transactionFn as <T>(fn: (tx: typeof db) => Promise<T>) => Promise<T>,
+        transactionService,
+        returnService,
+      );
 
       // Cart service from core (for creating POS transaction carts)
       const cartService = ctx.services.cart as {
@@ -125,6 +153,8 @@ export function posPlugin(userOptions: POSPluginOptions = {}) {
         ...buildReturnRoutes(returnService, transactionService, paymentService, cartService, ctx),
         ...buildLookupRoutes(lookupService, ctx),
         ...buildReceiptRoutes(receiptService, ctx),
+        ...buildPinAuthRoutes(pinService, ctx),
+        ...buildExchangeRoutes(exchangeService, ctx),
       ];
     },
   });

package/src/routes/auth.ts

@@ -0,0 +1,67 @@
+import { router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { PinService, PinAuthApi } from "../services/pin-service.js";
+import type { PluginRouteRegistration } from "@porulle/core";
+
+/**
+ * PIN auth runtime (issue #51).
+ *
+ * - PUT /pos/auth/pin        — set/rotate an operator's PIN (pos:admin)
+ * - POST /pos/auth/pin-login — operator PIN → short-lived per-shift API key.
+ *   Authenticated by the terminal's device credential (pos:operate); the
+ *   minted key is personal and carries pos:operate + shift/terminal metadata.
+ * - POST /pos/auth/override  — manager PIN approves one elevated action.
+ */
+export function buildPinAuthRoutes(
+  service: PinService,
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown }; auth?: unknown },
+): PluginRouteRegistration[] {
+  const r = router("POS Auth", "/pos/auth", ctx);
+
+  r.put("/pin")
+    .summary("Set or rotate an operator PIN")
+    .permission("pos:admin")
+    .input(z.object({
+      operatorId: z.string().min(1),
+      pin: z.string().regex(/^\d{4,8}$/, "PIN must be 4-8 digits"),
+      canOverride: z.boolean().optional(),
+    }))
+    .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);
+      return result.value;
+    });
+
+  r.post("/pin-login")
+    .summary("PIN login — mint a short-lived per-shift credential")
+    .permission("pos:operate")
+    .input(z.object({
+      operatorId: z.string().min(1),
+      pin: z.string().regex(/^\d{4,8}$/),
+      shiftId: z.string().uuid().optional(),
+    }))
+    .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);
+      return result.value;
+    });
+
+  r.post("/override")
+    .summary("Manager override — approve one elevated action by PIN")
+    .permission("pos:operate")
+    .input(z.object({
+      operatorId: z.string().min(1),
+      pin: z.string().regex(/^\d{4,8}$/),
+      action: z.string().min(1).max(200),
+    }))
+    .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);
+      return result.value;
+    });
+
+  return r.routes();
+}

package/src/routes/exchanges.ts

@@ -0,0 +1,53 @@
+import { router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { ExchangeService, ExchangeInput } from "../services/exchange-service.js";
+import type { PluginRouteRegistration } from "@porulle/core";
+
+/**
+ * Exchanges (issue #53): POST /pos/exchanges — return + replacement order +
+ * net delta in one call. Requires pos:manage (like returns) plus core order
+ * scopes on the actor (orders:update for the refund, orders:create for the
+ * replacement) since the exchange moves money on core orders.
+ */
+export function buildExchangeRoutes(
+  service: ExchangeService,
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown } },
+): PluginRouteRegistration[] {
+  const r = router("POS Exchanges", "/pos/exchanges", ctx);
+
+  r.post("/")
+    .summary("Exchange — return lines + replacement order in one atomic operation")
+    .permission("pos:manage")
+    .input(z.object({
+      shiftId: z.string().uuid(),
+      terminalId: z.string().uuid(),
+      originalOrderId: z.string().uuid(),
+      currency: z.string().length(3).optional(),
+      customerId: z.string().uuid().optional(),
+      returnItems: z.array(z.object({
+        originalLineItemId: z.string().uuid(),
+        quantity: z.number().int().positive(),
+        reason: z.enum(["defective", "wrong_item", "changed_mind", "other"]),
+      })).min(1),
+      replacementItems: z.array(z.object({
+        entityId: z.string().uuid(),
+        variantId: z.string().uuid().optional(),
+        sku: z.string().optional(),
+        title: z.string().min(1),
+        quantity: z.number().int().positive(),
+        unitPrice: z.number().int().min(0),
+        taxAmount: z.number().int().min(0).optional(),
+      })).min(1),
+    }))
+    .handler(async ({ input, actor, orgId }) => {
+      const result = await service.exchange(
+        orgId,
+        input as ExchangeInput,
+        actor as { userId: string } & Record<string, unknown>,
+      );
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  return r.routes();
+}

package/src/schema.ts

@@ -118,6 +118,22 @@ export const posPayments = pgTable("pos_payments", {
   transactionIdx: index("idx_pos_payments_transaction").on(table.transactionId),
 }));
 
+// ─── Operator PINs (issue #51) ──────────────────────────────────────────
+
+export const posOperatorPins = pgTable("pos_operator_pins", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  operatorId: text("operator_id").notNull(),
+  // PBKDF2-SHA256, encoded as pbkdf2$<iterations>$<saltB64>$<hashB64>
+  pinHash: text("pin_hash").notNull(),
+  // Manager override capability — checked by POST /pos/auth/override.
+  canOverride: boolean("can_override").notNull().default(false),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgOperatorUnique: uniqueIndex("pos_operator_pins_org_operator_unique").on(table.organizationId, table.operatorId),
+}));
+
 // ─── Return Items ───────────────────────────────────────────────────────
 
 export const posReturnItems = pgTable("pos_return_items", {