qumra-pos-auth 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,479 @@
+import { P as PinHasher, S as SignatureVerifier } from './SignatureVerifier-ueydiL4D.js';
+
+/**
+ * أنواع الـ auth المشتركة. كل الأوقات = مللي ثانية epoch.
+ *
+ * حزمة auth مستقلة تماماً عن qumra-pos-storage — الربط بينهم في التطبيق فقط عبر
+ * callback واحد: transport.getAuthToken = () => auth.getValidToken().
+ */
+/**
+ * - online:            توكنات قمرة صالحة — بنزامن فعلياً.
+ * - offline-degraded:  اتفعّل أونلاين قبل كده، التوكنات انتهت/النت مقطوع — بيشتغل
+ *                      على جلسة محلية، الـ sync واقف بس.
+ * - offline-activated: مفتاح تفعيل Ed25519 موقّع، اتحقق محلياً من غير ما الجهاز
+ *                      يكلّم السيرفر أبداً.
+ * - unactivated:       الجهاز لسه ماتفعّلش — لا توكنات ولا مفتاح.
+ */
+type OperatingMode = "online" | "offline-degraded" | "offline-activated" | "unactivated";
+/**
+ * حالة الوصول = هل نقدر نبيع دلوقتي؟ الانتقال: active → grace → locked.
+ * القفل بيمنع البيع الجديد بس — الـ outbox والتاريخ محفوظين دايماً.
+ */
+type AccessState = "active" | "grace" | "locked";
+/** رد السيرفر على login/refresh (مدد نسبية بالثواني). */
+interface TokenResponse {
+    accessToken: string;
+    refreshToken: string;
+    /** عمر الـ access token بالثواني (~900 = 15 دقيقة). */
+    expiresInSec: number;
+    /** عمر الـ refresh token بالثواني (~2592000 = 30 يوم). */
+    refreshExpiresInSec: number;
+    tokenType?: string;
+}
+/** التوكنات كما تُخزّن — بمواعيد انتهاء مطلقة (ms epoch). */
+interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    accessExpiresAt: number;
+    refreshExpiresAt: number;
+    tokenType: string;
+}
+/** مدخلات تسجيل الدخول الأونلاين (التاجر/الجهاز). */
+interface LoginInput {
+    username: string;
+    password: string;
+    deviceId?: string;
+}
+/** صف كاشير متزامن من السيرفر — الـ pinHash argon2id. */
+interface CashierRecord {
+    id: string;
+    name: string;
+    /** hash بصيغة PHC القياسية (argon2id) الجاي من السيرفر. */
+    pinHash: string;
+    active: boolean;
+}
+/** نسخة آمنة للعرض — من غير الـ hash. */
+interface PublicCashier {
+    id: string;
+    name: string;
+    active: boolean;
+}
+/** جلسة الكاشير المفتوحة حالياً على الجهاز. */
+interface CashierSession {
+    cashierId: string;
+    name: string;
+    /** وقت تسجيل الدخول (ms epoch). */
+    since: number;
+}
+/** نتيجة محاولة PIN. */
+type PinResult = {
+    ok: true;
+    cashier: CashierSession;
+} | {
+    ok: false;
+    reason: "bad-pin" | "unknown-cashier" | "inactive" | "locked";
+    /** موجود مع locked — كام مللي ثانية لحد ما القفل يفك. */
+    retryAfterMs?: number;
+    /** كام محاولة فاضلة قبل القفل (مع bad-pin). */
+    attemptsLeft?: number;
+};
+/** حمولة مفتاح التفعيل الموقّع — كل الأوقات ms epoch. */
+interface ActivationClaims {
+    merchantId: string;
+    deviceId: string;
+    /** وقت الإصدار. */
+    issuedAt: number;
+    /** انتهاء الرخصة — بعده يبدأ grace ثم lock. */
+    expiresAt: number;
+    /** مدة الـ grace بعد الانتهاء (لو مش موجودة يُستخدم policy.graceMs). */
+    graceMs?: number;
+    version?: number;
+}
+/** مفتاح تفعيل متحقق منه ومخزّن. */
+interface StoredActivation {
+    claims: ActivationClaims;
+    /** المفتاح الخام الموقّع (للعرض/إعادة التحقق). */
+    key: string;
+    /** وقت آخر تحقق ناجح محلياً. */
+    verifiedAt: number;
+}
+type ActivationResult = {
+    ok: true;
+    claims: ActivationClaims;
+} | {
+    ok: false;
+    reason: "malformed" | "bad-signature" | "expired" | "wrong-device";
+};
+/**
+ * قد إيه مسموح للجهاز يفضل أوفلاين قبل ما يتقفل. القيم دي من الاشتراك — الافتراضي
+ * معقول لكن مفتاح التفعيل يقدر يتجاوزه (claims.graceMs).
+ */
+interface AccessPolicy {
+    /** أقصى مدة أوفلاين من غير اتصال بالسيرفر قبل بدء الـ grace (offline-degraded). */
+    maxOfflineMs: number;
+    /** مدة الـ grace قبل القفل النهائي. */
+    graceMs: number;
+}
+/** بيانات وصفية للجلسة تُحفظ في الـ vault. */
+interface AuthMeta {
+    /** آخر اتصال ناجح بالسيرفر (login/refresh) — مرساة حساب الأوفلاين. */
+    lastServerContactAt: number | null;
+    /** أول تفعيل أونلاين ناجح — بيفتح وضع offline-degraded. */
+    activatedOnlineAt: number | null;
+}
+interface AuthStatus {
+    mode: OperatingMode;
+    access: AccessState;
+    /** access token صالح دلوقتي؟ */
+    tokenValid: boolean;
+    /** الكاشير المسجّل حالياً (null = مفيش حد على الشاشة). */
+    cashier: CashierSession | null;
+    /** لو في grace: امتى هيتحوّل لـ locked (ms epoch). */
+    graceEndsAt: number | null;
+    /** سبب القفل لو locked. */
+    lockedReason: string | null;
+    lastServerContactAt: number | null;
+    /** التفعيل الأوفلاين لو موجود. */
+    activation: StoredActivation | null;
+}
+
+/**
+ * منفذ الشبكة لـ OAuth. نقطة الحقن الوحيدة للسيرفر — الاختبارات بتمرّر mock،
+ * والإنتاج بيمرّر عميل fetch.
+ *
+ * كل دالة بترمي:
+ *   - AuthNetworkError  عند فشل الشبكة/السيرفر (offline, 5xx) → قابل للإعادة.
+ *   - AuthRejectedError عند رفض صريح (401/400 invalid_grant) → دائم.
+ */
+interface AuthApi {
+    /** POST /oauth/token (grant=password) — تسجيل دخول أونلاين. */
+    login(input: LoginInput): Promise<TokenResponse>;
+    /** POST /oauth/token (grant=refresh_token) — refresh دوّار: بيرجّع refresh جديد. */
+    refresh(refreshToken: string): Promise<TokenResponse>;
+    /** POST /oauth/revoke — best-effort عند الخروج (اختياري). */
+    revoke?(refreshToken: string): Promise<void>;
+}
+
+/**
+ * منفذ التخزين الآمن للـ auth. التطبيق بيوصّله بتخزين آمن حسب المنصة:
+ *   - Electron: safeStorage (DPAPI/Keychain) فوق ملف.
+ *   - Web:      IndexedDB (+ WebCrypto لو حبينا نشفّر الـ refresh).
+ *   - RN:       Keychain / EncryptedSharedPreferences.
+ *
+ * الـ core مابيعرفش عن التشفير — ده مسؤولية الـ vault. القيمة null معناها "امسح".
+ * ملاحظة: مسح التوكنات ≠ مسح البيانات التجارية — دي في qumra-pos-storage ومابتتمسّش.
+ */
+interface AuthVault {
+    loadTokens(): Promise<AuthTokens | null>;
+    saveTokens(tokens: AuthTokens | null): Promise<void>;
+    loadSession(): Promise<CashierSession | null>;
+    saveSession(session: CashierSession | null): Promise<void>;
+    loadActivation(): Promise<StoredActivation | null>;
+    saveActivation(activation: StoredActivation | null): Promise<void>;
+    loadMeta(): Promise<AuthMeta | null>;
+    saveMeta(meta: AuthMeta): Promise<void>;
+}
+
+/**
+ * مصدر hashes الكاشيرية المتزامنة. الحزمة مش بتعرف qumra-pos-storage، فالتطبيق
+ * بيوصّل الدالة دي لقراءة جدول cashiers المتزامن من الـ storage.
+ *
+ * بكده "نفس الكود أونلاين وأوفلاين": PinManager دايماً بيتحقق ضد الـ hash المحلي
+ * المتزامن — مفيش نداء سيرفر وقت دخول الكاشير.
+ */
+interface CashierDirectory {
+    listCashiers(): Promise<CashierRecord[]>;
+}
+
+/**
+ * كل حسابات الوقت في الـ auth بالمللي ثانية منذ epoch (نفس شكل Date.now).
+ * دالة now محقونة علشان الاختبارات تتحكم في الزمن (زي SyncEngine).
+ */
+type Clock = () => number;
+declare const systemClock: Clock;
+declare const SECOND = 1000;
+declare const MINUTE: number;
+declare const HOUR: number;
+declare const DAY: number;
+
+/**
+ * نتيجة محاولة ضمان توكن صالح. غنية علشان AuthService يقدر يفرّق بين "النت مقطوع"
+ * (pause، الجلسة تكمل) و "السيرفر رفض" (التوكنات اتمسحت، ندخل مسار grace/lock).
+ */
+type RefreshOutcome = {
+    status: "valid";
+    tokens: AuthTokens;
+} | {
+    status: "refreshed";
+    tokens: AuthTokens;
+} | {
+    status: "network";
+} | {
+    status: "rejected";
+} | {
+    status: "signed-out";
+};
+interface TokenManagerOptions {
+    vault: AuthVault;
+    api: AuthApi;
+    now?: Clock;
+    /**
+     * هامش أمان: نعتبر التوكن "منتهي" قبل انتهائه الحقيقي بـ skew — علشان ماننفّذش
+     * نداء بتوكن هيقع أثناء الرحلة. افتراضي 30 ثانية.
+     */
+    skewMs?: number;
+    /** يتنادى بعد كل اتصال ناجح بالسيرفر (login/refresh) — AuthService بيحدّث الـ meta. */
+    onServerContact?: (at: number) => void | Promise<void>;
+}
+/**
+ * TokenVault + OAuth. بيملك دورة حياة التوكنات: login، refresh دوّار single-flight،
+ * وينتج التوكن الصالح للـ SyncEngine. القاعدة الذهبية: getValidToken مابيرميش أبداً —
+ * null معناها "اعمل pause"، مش استثناء.
+ */
+declare class TokenManager {
+    private readonly vault;
+    private readonly api;
+    private readonly now;
+    private readonly skewMs;
+    private readonly onServerContact;
+    /** single-flight: كل النداءات المتزامنة بتشارك نفس عملية الـ refresh. */
+    private inflight;
+    /**
+     * نسخة في الذاكرة من آخر توكنات معروفة. الغرض الوحيد: peekValidToken المتزامن
+     * — لأن SyncEngine.getAuthToken متزامن بينما الـ vault async. بتتحدّث مع كل
+     * تحميل/حفظ للتوكنات، ودورة الـ refresh الخلفية بتحافظ عليها دافية.
+     */
+    private cached;
+    constructor(opts: TokenManagerOptions);
+    /** تسجيل دخول أونلاين. بيرمي AuthRejectedError/AuthNetworkError زي الـ api. */
+    login(input: LoginInput): Promise<AuthTokens>;
+    /** خروج: إبطال best-effort على السيرفر ثم مسح التوكنات المحلية. */
+    logout(): Promise<void>;
+    getTokens(): Promise<AuthTokens | null>;
+    /** يملأ الكاش من الـ vault مرة (عند الإقلاع) — علشان peek يشتغل قبل أي نداء. */
+    primeCache(): Promise<void>;
+    /**
+     * توكن access صالح متزامن من الكاش — من غير أي I/O أو refresh. ده اللي بيتوصّل
+     * لـ SyncEngine.getAuthToken. بيرجّع null لو مفيش كاش أو الكاش منتهي؛ دورة الـ
+     * refresh الخلفية (getValidToken) هي اللي بتجدّد الكاش.
+     */
+    peekValidToken(): string | null;
+    /**
+     * التوكن الصالح للـ SyncEngine. مابيرميش: أي فشل → null (= pause).
+     */
+    getValidToken(): Promise<string | null>;
+    /**
+     * يضمن توكن access صالح: يرجّعه لو صالح، أو يعمل refresh دوّار single-flight.
+     * مابيرميش — بيرجّع RefreshOutcome. AuthService بيستخدمه لتحديث حالة الوصول.
+     */
+    ensureFresh(): Promise<RefreshOutcome>;
+    isAccessValid(tokens: AuthTokens): boolean;
+    isRefreshValid(tokens: AuthTokens): boolean;
+    /** refresh single-flight: نداء واحد بس بيطير حتى لو اتنادى من كذا مكان. */
+    private refreshOnce;
+    private doRefresh;
+    private toTokens;
+}
+
+interface PinManagerOptions {
+    directory: CashierDirectory;
+    hasher: PinHasher;
+    now?: Clock;
+    /** عدد المحاولات الخاطئة قبل القفل المؤقت. افتراضي 5. */
+    maxAttempts?: number;
+    /** مدة القفل بعد استنفاد المحاولات. افتراضي دقيقة. */
+    lockoutMs?: number;
+}
+/**
+ * دخول الكاشير اليومي بالـ PIN المحلي. بيتحقق بـ argon2id ضد الـ hash المتزامن —
+ * نفس الكود أونلاين وأوفلاين، مفيش نداء سيرفر. فيه قفل مؤقت لكل كاشير بعد محاولات
+ * فاشلة متتالية (حماية من التخمين).
+ *
+ * ملاحظة: PinManager بيتحقق بس — إدارة الكاشيرية (إضافة/تعديل PIN) من داشبورد
+ * التاجر، وبتوصل الجهاز عن طريق مزامنة جدول cashiers.
+ */
+declare class PinManager {
+    private readonly directory;
+    private readonly hasher;
+    private readonly now;
+    private readonly maxAttempts;
+    private readonly lockoutMs;
+    private readonly attempts;
+    constructor(opts: PinManagerOptions);
+    /** قائمة الكاشيرية للعرض (من غير الـ hashes). */
+    listCashiers(): Promise<PublicCashier[]>;
+    /**
+     * يتحقق من PIN كاشير معيّن. النجاح بيصفّر عدّاد محاولاته؛ الفشل بيزوّده ويقفل
+     * مؤقتاً عند الوصول للحد.
+     */
+    verify(cashierId: string, pin: string): Promise<PinResult>;
+    /** يفكّ القفل يدوياً (مثلاً المدير سمح). */
+    reset(cashierId: string): void;
+    private registerFailure;
+    private findCashier;
+}
+
+/**
+ * التفعيل الأوفلاين: مفتاح موقّع بـ Ed25519 يصدره سيرفر قمرة، يتحقق منه الجهاز
+ * محلياً بالمفتاح العام المثبّت — بدون أي اتصال بالسيرفر. ده اللي بيسمح بوضع
+ * offline-activated لجهاز اتفعّل من غير ما يشوف النت.
+ *
+ * صيغة المفتاح (زي JWT بس Ed25519):  <payloadB64url>.<signatureB64url>
+ * التوقيع على بايتات مقطع الـ payload نفسه (نص b64url).
+ */
+interface ActivationManagerOptions {
+    vault: AuthVault;
+    verifier: SignatureVerifier;
+    /** المفتاح العام لقمرة (32 بايت Ed25519) — مثبّت في التطبيق. */
+    publicKey: Uint8Array;
+    now?: Clock;
+    /** لو محدَّد، لازم claims.deviceId يطابقه (منع نقل المفتاح لجهاز تاني). */
+    deviceId?: string;
+}
+declare class ActivationManager {
+    private readonly vault;
+    private readonly verifier;
+    private readonly publicKey;
+    private readonly now;
+    private readonly deviceId;
+    constructor(opts: ActivationManagerOptions);
+    /**
+     * يتحقق من مفتاح تفعيل ويخزّنه لو صالح. الترتيب: صيغة → توقيع → الجهاز → الانتهاء.
+     * التوقيع بيتفحص قبل أي حاجة تانية علشان مانثقش في أي claim قبل التأكد إنه من قمرة.
+     */
+    activate(activationKey: string): Promise<ActivationResult>;
+    getActivation(): Promise<StoredActivation | null>;
+    /**
+     * يعيد التحقق من المفتاح المخزّن (توقيع + جهاز) ويحدّث verifiedAt. بيُستدعى عند
+     * الإقلاع علشان نتأكد إن المفتاح المخزّن لسه سليم ومش متلاعب فيه.
+     */
+    revalidateStored(): Promise<ActivationResult | null>;
+    clear(): Promise<void>;
+    private parse;
+}
+
+interface AuthServiceOptions {
+    vault: AuthVault;
+    tokenManager: TokenManager;
+    pinManager: PinManager;
+    activationManager: ActivationManager;
+    policy?: AccessPolicy;
+    now?: Clock;
+}
+type Listener = (status: AuthStatus) => void;
+/**
+ * الواجهة الموحّدة للـ auth. بتجمع الثلاث مدراء وبتدير آلة الحالة
+ * (active → grace → locked) والأوضاع الثلاثة. بتعرض callback واحد getValidToken
+ * للـ SyncEngine، وبثّ حالة onStatusChange للـ UI.
+ *
+ * مبدأ ثابت: مفيش أي مسار هنا بيمسح بيانات تجارية — أسوأ حالة إن البيع الجديد
+ * يتقفل. مسح التوكنات (عند رفض السيرفر) مش مسح للـ outbox أو التاريخ.
+ */
+declare class AuthService {
+    private readonly vault;
+    private readonly now;
+    private readonly policy;
+    readonly tokens: TokenManager;
+    readonly pins: PinManager;
+    readonly activation: ActivationManager;
+    private readonly listeners;
+    private status;
+    constructor(opts: AuthServiceOptions);
+    /** الإقلاع: يملأ كاش التوكن، يعيد التحقق من مفتاح التفعيل المخزّن، ثم يحسب الحالة. */
+    init(): Promise<AuthStatus>;
+    /**
+     * يحاول تحديث التوكن (لو النت رجع) ثم يعيد حساب الحالة. التطبيق بينادي ده دورياً
+     * وبعد أي reconnect. مابيرميش.
+     */
+    refresh(): Promise<AuthStatus>;
+    getStatus(): AuthStatus;
+    /** هل مسموح ببيع جديد دلوقتي؟ (locked = لأ). */
+    canSell(): boolean;
+    onStatusChange(cb: Listener): () => void;
+    /** تسجيل دخول أونلاين. بيرمي زي الـ api (rejected/network). */
+    onlineLogin(input: LoginInput): Promise<AuthStatus>;
+    /** إدخال مفتاح تفعيل أوفلاين. */
+    activateOffline(activationKey: string): Promise<ActivationResult>;
+    /** خروج التاجر: يمسح التوكنات وجلسة الكاشير (مش البيانات، مش التفعيل). */
+    logout(): Promise<AuthStatus>;
+    /** callback الوحيد للـ SyncEngine (async). null = pause. */
+    getValidToken(): Promise<string | null>;
+    /**
+     * نسخة متزامنة للـ SyncEngine (getAuthToken بتاعه متزامن). بترجّع آخر توكن صالح
+     * من الكاش من غير I/O؛ refresh()/getValidToken الدورية هي اللي بتدفّي الكاش.
+     */
+    getAccessTokenSync(): string | null;
+    /** يُمرَّر للـ TokenManager: يسجّل آخر اتصال ناجح بالسيرفر ويعلّم التفعيل الأونلاين. */
+    recordServerContact(at: number): Promise<void>;
+    listCashiers(): Promise<PublicCashier[]>;
+    cashierLogin(cashierId: string, pin: string): Promise<PinResult>;
+    cashierLogout(): Promise<void>;
+    private reevaluate;
+    private computeStatus;
+}
+
+interface CreateAuthOptions {
+    /** التخزين الآمن (حسب المنصة). */
+    vault: AuthVault;
+    /** عميل OAuth. */
+    api: AuthApi;
+    /** مصدر hashes الكاشيرية المتزامنة (بيقرأ جدول cashiers من storage). */
+    directory: CashierDirectory;
+    /** المفتاح العام لقمرة (Ed25519, 32 بايت) للتفعيل الأوفلاين. */
+    activationPublicKey: Uint8Array;
+    /** هوية الجهاز — لو محدَّدة، مفتاح التفعيل لازم يطابقها. */
+    deviceId?: string;
+    /** سياسة الـ grace/lock. الافتراضي 30 يوم + 3 أيام grace. */
+    policy?: AccessPolicy;
+    hasher?: PinHasher;
+    verifier?: SignatureVerifier;
+    now?: Clock;
+    skewMs?: number;
+    maxPinAttempts?: number;
+    pinLockoutMs?: number;
+}
+interface Auth {
+    service: AuthService;
+    tokens: TokenManager;
+    pins: PinManager;
+    activation: ActivationManager;
+    /** async — للاستخدام العام. */
+    getValidToken: () => Promise<string | null>;
+    /** متزامن — للربط مع SyncEngine: `{ getAuthToken: auth.getAccessTokenSync }`. */
+    getAccessTokenSync: () => string | null;
+}
+/**
+ * يركّب حزمة الـ auth كاملة بأقل إعداد ممكن. الافتراضيات: crypto من @noble،
+ * ساعة النظام، سياسة قياسية. كل حاجة قابلة للحقن.
+ *
+ * لاحظ: بيحلّ اعتماد دائري خفيف — TokenManager محتاج callback بعد كل اتصال
+ * ناجح، والـ callback ده بتاع AuthService. بنمرّر closure متأخّر التنفيذ.
+ */
+declare function createAuth(opts: CreateAuthOptions): Auth;
+
+/**
+ * الافتراضي: 30 يوم أوفلاين مسموحة (يطابق عمر الـ refresh)، بعدها 3 أيام grace
+ * (تحذير للمدير) ثم قفل البيع الجديد. البيانات لا تُمسح أبداً في أي مرحلة.
+ */
+declare const DEFAULT_ACCESS_POLICY: AccessPolicy;
+
+/**
+ * فرق جوهري بين نوعي الفشل — بيحدد سلوك الـ auth بالكامل:
+ *
+ * - AuthNetworkError: النت/السيرفر مش متاح (offline أو 5xx). قابل لإعادة المحاولة،
+ *   ومابيمسحش أي توكن. النتيجة: sync يقف مؤقتاً (pause) والجلسة تفضل شغّالة أوفلاين.
+ *
+ * - AuthRejectedError: السيرفر رفض صراحةً (401/400 invalid_grant، refresh متبطّل،
+ *   كلمة سر غلط). دائم — إعادة المحاولة مش هتفيد. النتيجة: التوكنات تتمسح والجلسة
+ *   تتحوّل للوضع الأوفلاين/المقفول. البيانات التجارية لا تُمسح أبداً.
+ */
+declare class AuthNetworkError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+declare class AuthRejectedError extends Error {
+    /** كود السيرفر لو متاح (invalid_grant, invalid_credentials …). */
+    readonly code: string | undefined;
+    constructor(message: string, code?: string, cause?: unknown);
+}
+
+export { type AccessPolicy, type AccessState, type ActivationClaims, ActivationManager, type ActivationManagerOptions, type ActivationResult, type Auth, type AuthApi, type AuthMeta, AuthNetworkError, AuthRejectedError, AuthService, type AuthServiceOptions, type AuthStatus, type AuthTokens, type AuthVault, type CashierDirectory, type CashierRecord, type CashierSession, type Clock, type CreateAuthOptions, DAY, DEFAULT_ACCESS_POLICY, HOUR, type LoginInput, MINUTE, type OperatingMode, PinHasher, PinManager, type PinManagerOptions, type PinResult, type PublicCashier, type RefreshOutcome, SECOND, SignatureVerifier, type StoredActivation, TokenManager, type TokenManagerOptions, type TokenResponse, createAuth, systemClock };