@enformik/auth 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @enformik/auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Enformik web sitenizde kullanıcı girişi için tarayıcı kütüphanesi: OIDC yetkilendirme kodu + PKCE, sıfır bağımlılık. Siteniz **gizli anahtar taşımaz**; giriş Enformik'in barındırdığı giriş sayfasında yapılır, siteniz yalnızca bu uygulamaya özel kısa ömürlü bir oturum belirteci alır.
+
+Tam kılavuz (kurulum, web kullanıcıları, erişim kuralları): <https://help.enformik.com/rehber/web-sitesi-girisi/>
+
+## Önkoşul
+
+Konsolda web sitenizin **Geliştirici sitesi → Site girişi** sekmesinden girişi açıp siteyi yeniden dağıtın. Her dağıtımda `/_enformik/config.json` içine giriş bilgileri (`auth` bloğu) yazılır; kütüphane yapılandırmayı buradan okur.
+
+## Kullanım
+
+```bash
+npm install @enformik/auth
+```
+
+```js
+import { createAuth } from '@enformik/auth';
+
+const auth = await createAuth();
+
+// Sayfa yüklenirken giriş dönüşünü tamamlayın (dönüş yoksa hiçbir şey yapmaz).
+const done = await auth.handleRedirect();
+if (done) history.replaceState(null, '', done.returnTo);
+
+if (!auth.isAuthenticated()) {
+  await auth.login();                       // giriş sayfasına yönlendirir
+} else {
+  // Bearer ve çalışma alanı başlığı otomatik eklenir; süre dolarsa belirteç yenilenir.
+  const res = await auth.fetch('/data/musteri?limit=20');
+  console.log(auth.getUser(), await res.json());
+}
+
+// await auth.logout();
+```
+
+## API
+
+| Üye | Açıklama |
+|---|---|
+| `createAuth(options?)` | Yapılandırmayı okuyup istemciyi kurar; site girişi açık değilse `not_configured` hatası verir. |
+| `config` | Okunan site yapılandırması (`appUrl`, `apiUrl`, `workspaceId`, `auth`…). |
+| `isAuthenticated()` | Geçerli ya da yenilenebilir oturum var mı. |
+| `login(returnTo?)` | Giriş sayfasına yönlendirir; `returnTo` giriş sonrası dönülecek yoldur. |
+| `handleRedirect()` | Girişten dönüşü tamamlar; `{ returnTo }` ya da `null` döner. |
+| `getAccessToken()` | Geçerli access token'ı döner, gerekirse yeniler (eşzamanlı çağrılar tek yenilemede birleşir). |
+| `fetch(path, init?)` | Uygulamanın API'sini oturumla çağırır; 401'de bir kez yenileyip tekrarlar. |
+| `getUser()` | ID token'dan `{ sub, email?, name? }` — yalnızca arayüzde göstermek içindir. |
+| `logout()` | Oturumu siler ve giriş sayfasından çıkış yaptırır. |
+
+Seçenekler (`AuthOptions`): `config` (nesne ya da adres; varsayılan `/_enformik/config.json`), `redirectPath` (varsayılan `/callback`), `postLogoutPath` (varsayılan `/`), `storage` (`'session'` varsayılan, `'local'` ya da kendi `getItem/setItem/removeItem` nesneniz).
+
+`redirectPath` sitenizin kayıtlı dönüş adreslerinden biri olmalıdır: `/`, `/callback`, `/auth/callback`, `/login/callback`.
+
+Hatalar `EnformikAuthError` olarak atılır; `code` alanı: `not_configured`, `state_mismatch`, `no_pending_login`, `login_rejected`, `token_exchange_failed`, `not_authenticated`.
+
+## Güvenlik notları
+
+- Belirteçler varsayılan olarak `sessionStorage`'da tutulur (sekme kapanınca silinir); `'local'` seçerseniz sitenizdeki herhangi bir betik okuyabilir — üçüncü taraf betik yüklüyorsanız önermiyoruz.
+- Oturum belirteci yalnızca bu uygulamanın API'sinde geçerlidir; kullanıcının ne görebileceğini sitenizin değil, uygulamanızdaki **Kayıt erişim kuralları** belirler.

package/dist/auth.d.ts

@@ -0,0 +1,28 @@
+import { type AuthConfig, type AuthOptions, type AuthUser, type SiteConfig } from './types.js';
+export interface Auth {
+    /** Okunan site yapılandırması (`auth` bloğu doludur; yoksa `createAuth` zaten `not_configured` verir). */
+    readonly config: SiteConfig & {
+        auth: AuthConfig;
+    };
+    /** Oturum var mı (geçerli access token ya da yenilenebilir oturum). */
+    isAuthenticated(): boolean;
+    /** Giriş sayfasına yönlendirir. `returnTo`: giriş sonrası dönülecek yol (varsayılan: şu anki yol). */
+    login(returnTo?: string): Promise<void>;
+    /**
+     * Dönüş adresinde (`?code=&state=`) girişi tamamlar. Her sayfa yüklemesinde çağırmak güvenlidir: dönüş yoksa `null` döner.
+     * Başarıda `{ returnTo }` döner (sayfayı oraya yönlendirmek istemci koduna bırakılır).
+     */
+    handleRedirect(): Promise<{
+        returnTo: string;
+    } | null>;
+    /** Geçerli access token'ı döner (gerekirse yeniler); oturum yoksa `null`. */
+    getAccessToken(): Promise<string | null>;
+    /** Uygulamanın API'sini oturum belirteciyle çağırır. `path` apiUrl'ye göre göreli ya da tam adres olabilir. */
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+    /** ID token'dan kullanıcı bilgisi (yalnızca arayüz için). */
+    getUser(): AuthUser | null;
+    /** Oturumu siler ve sağlayıcıdan çıkış yaptırır. */
+    logout(): Promise<void>;
+}
+/** Siteyi Enformik girişine bağlar. Yapılandırmada `auth` yoksa `not_configured` hatası verir. */
+export declare function createAuth(opts?: AuthOptions): Promise<Auth>;

package/dist/auth.js

@@ -0,0 +1,199 @@
+import { challengeFor, randomString } from './pkce.js';
+import { EnformikAuthError } from './types.js';
+const PENDING_KEY = 'enformik.auth.pending';
+const TOKENS_KEY = 'enformik.auth.tokens';
+const LEEWAY_MS = 30_000; // süresi dolmadan 30 sn önce yenile
+function decodeJwtPayload(token) {
+    try {
+        const part = token.split('.')[1];
+        if (!part)
+            return null;
+        const b64 = part.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (part.length % 4)) % 4);
+        return JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(b64), c => c.charCodeAt(0))));
+    }
+    catch {
+        return null;
+    }
+}
+/** Siteyi Enformik girişine bağlar. Yapılandırmada `auth` yoksa `not_configured` hatası verir. */
+export async function createAuth(opts = {}) {
+    const f = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const loc = opts.location ?? globalThis.location;
+    const hist = opts.history ?? globalThis.history;
+    const cry = opts.crypto ?? globalThis.crypto;
+    const now = opts.now ?? Date.now;
+    const redirectPath = opts.redirectPath ?? '/callback';
+    const postLogoutPath = opts.postLogoutPath ?? '/';
+    const store = typeof opts.storage === 'object' ? opts.storage : opts.storage === 'local' ? globalThis.localStorage : globalThis.sessionStorage;
+    let cfg;
+    if (opts.config && typeof opts.config === 'object') {
+        cfg = opts.config;
+    }
+    else {
+        const url = typeof opts.config === 'string' ? opts.config : '/_enformik/config.json';
+        const res = await f(url, { headers: { Accept: 'application/json' } });
+        if (!res.ok)
+            throw new EnformikAuthError('not_configured', `Yapılandırma okunamadı (${url}: HTTP ${res.status}).`);
+        cfg = (await res.json());
+    }
+    const authCfg = cfg.auth;
+    if (!authCfg?.authority || !authCfg.clientId || !authCfg.gatewayUrl) {
+        throw new EnformikAuthError('not_configured', 'Bu site için giriş açık değil: yapılandırmada "auth" bloğu yok (konsolda Site girişi açıp siteyi yeniden dağıtın).');
+    }
+    const a = authCfg;
+    const redirectUri = () => loc.origin + redirectPath;
+    const tokenUrl = a.authority.replace(/\/$/, '') + '/oauth/v2/token';
+    const read = (key) => {
+        try {
+            const v = store.getItem(key);
+            return v ? JSON.parse(v) : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const write = (key, v) => store.setItem(key, JSON.stringify(v));
+    const saveTokens = (t, prev) => {
+        const expiresIn = typeof t.expires_in === 'number' ? t.expires_in : 3600;
+        const tokens = {
+            accessToken: String(t.access_token),
+            refreshToken: t.refresh_token ?? prev?.refreshToken,
+            idToken: t.id_token ?? prev?.idToken,
+            expiresAt: now() + expiresIn * 1000,
+        };
+        write(TOKENS_KEY, tokens);
+        return tokens;
+    };
+    const tokenRequest = async (params) => {
+        const res = await f(tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+            body: new URLSearchParams({ client_id: a.clientId, ...params }).toString(),
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok || typeof body.access_token !== 'string') {
+            throw new EnformikAuthError('token_exchange_failed', String(body.error_description ?? body.error ?? `HTTP ${res.status}`));
+        }
+        return body;
+    };
+    // Aynı anda birden çok yenileme isteği tek isteğe indirgenir (yenileme belirteci döndürülüyorsa ikincisi başarısız olurdu).
+    let refreshing = null;
+    const refresh = () => {
+        if (refreshing)
+            return refreshing;
+        const cur = read(TOKENS_KEY);
+        if (!cur?.refreshToken) {
+            store.removeItem(TOKENS_KEY);
+            return Promise.resolve(null);
+        }
+        refreshing = tokenRequest({ grant_type: 'refresh_token', refresh_token: cur.refreshToken })
+            .then(body => saveTokens(body, cur))
+            .catch(() => {
+            store.removeItem(TOKENS_KEY);
+            return null;
+        })
+            .finally(() => {
+            refreshing = null;
+        });
+        return refreshing;
+    };
+    const getAccessToken = async () => {
+        const t = read(TOKENS_KEY);
+        if (!t)
+            return null;
+        if (t.expiresAt - now() > LEEWAY_MS)
+            return t.accessToken;
+        return (await refresh())?.accessToken ?? null;
+    };
+    return {
+        config: { ...cfg, auth: a },
+        isAuthenticated() {
+            const t = read(TOKENS_KEY);
+            return !!t && (t.expiresAt > now() || !!t.refreshToken);
+        },
+        async login(returnTo) {
+            const verifier = randomString(32, cry);
+            const state = randomString(16, cry);
+            write(PENDING_KEY, { state, verifier, returnTo: returnTo ?? loc.href.slice(loc.origin.length) });
+            const q = new URLSearchParams({
+                client_id: a.clientId,
+                redirect_uri: redirectUri(),
+                code_challenge: await challengeFor(verifier, cry),
+                code_challenge_method: 'S256',
+                state,
+            });
+            loc.assign(a.gatewayUrl.replace(/\/$/, '') + '/login?' + q.toString());
+        },
+        async handleRedirect() {
+            const q = new URLSearchParams(loc.search);
+            const err = q.get('error');
+            const code = q.get('code');
+            if (!err && !code)
+                return null;
+            const pending = read(PENDING_KEY);
+            store.removeItem(PENDING_KEY); // tek kullanımlık
+            const clean = () => hist.replaceState(null, '', loc.pathname);
+            if (err) {
+                clean();
+                throw new EnformikAuthError('login_rejected', q.get('error_description') ?? err);
+            }
+            if (!pending) {
+                clean();
+                throw new EnformikAuthError('no_pending_login', 'Bekleyen bir giriş yok; girişi yeniden başlatın.');
+            }
+            if (q.get('state') !== pending.state) {
+                clean();
+                throw new EnformikAuthError('state_mismatch', 'Giriş yanıtı bu oturumla eşleşmiyor.');
+            }
+            try {
+                const body = await tokenRequest({ grant_type: 'authorization_code', code: code, redirect_uri: redirectUri(), code_verifier: pending.verifier });
+                saveTokens(body);
+            }
+            finally {
+                clean();
+            }
+            return { returnTo: pending.returnTo };
+        },
+        getAccessToken,
+        async fetch(path, init = {}) {
+            const base = cfg.apiUrl.replace(/\/$/, '');
+            const url = /^https?:\/\//i.test(path) ? path : base + (path.startsWith('/') ? path : '/' + path);
+            const call = async (token) => {
+                const h = new Headers(init.headers);
+                h.set('Authorization', 'Bearer ' + token);
+                if (cfg.workspaceId && !h.has('X-Tenant-ID'))
+                    h.set('X-Tenant-ID', cfg.workspaceId);
+                return f(url, { ...init, headers: h });
+            };
+            let token = await getAccessToken();
+            if (!token)
+                throw new EnformikAuthError('not_authenticated', 'Oturum yok; önce giriş yapın.');
+            let res = await call(token);
+            if (res.status === 401) {
+                // Token sunucuda reddedildi (iptal/erken bitiş): bir kez yenile ve tekrar dene.
+                const t = await refresh();
+                if (!t)
+                    throw new EnformikAuthError('not_authenticated', 'Oturum sona erdi; yeniden giriş yapın.');
+                token = t.accessToken;
+                res = await call(token);
+            }
+            return res;
+        },
+        getUser() {
+            const id = read(TOKENS_KEY)?.idToken;
+            const c = id ? decodeJwtPayload(id) : null;
+            if (!c || typeof c.sub !== 'string')
+                return null;
+            return { sub: c.sub, email: typeof c.email === 'string' ? c.email : undefined, name: typeof c.name === 'string' ? c.name : undefined };
+        },
+        async logout() {
+            const idToken = read(TOKENS_KEY)?.idToken;
+            store.removeItem(TOKENS_KEY);
+            store.removeItem(PENDING_KEY);
+            const q = new URLSearchParams({ client_id: a.clientId, post_logout_redirect_uri: loc.origin + postLogoutPath });
+            if (idToken)
+                q.set('id_token_hint', idToken);
+            loc.assign(a.authority.replace(/\/$/, '') + '/oidc/v1/end_session?' + q.toString());
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createAuth } from './auth.js';
+export type { Auth } from './auth.js';
+export { EnformikAuthError } from './types.js';
+export type { AuthConfig, AuthErrorCode, AuthOptions, AuthUser, KeyValueStorage, SiteConfig } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createAuth } from './auth.js';
+export { EnformikAuthError } from './types.js';

package/dist/pkce.d.ts

@@ -0,0 +1,6 @@
+/** Bayt dizisini Base64URL (dolgusuz) metne çevirir. */
+export declare function base64url(bytes: Uint8Array): string;
+/** Rastgele, URL'de güvenli bir metin üretir (n bayt entropi). */
+export declare function randomString(n: number, c?: Crypto): string;
+/** code_verifier'dan S256 code_challenge üretir. */
+export declare function challengeFor(verifier: string, c?: Crypto): Promise<string>;

package/dist/pkce.js

@@ -0,0 +1,19 @@
+// PKCE (RFC 7636) yardımcıları: Web Crypto, sıfır bağımlılık.
+/** Bayt dizisini Base64URL (dolgusuz) metne çevirir. */
+export function base64url(bytes) {
+    let bin = '';
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/** Rastgele, URL'de güvenli bir metin üretir (n bayt entropi). */
+export function randomString(n, c = globalThis.crypto) {
+    const b = new Uint8Array(n);
+    c.getRandomValues(b);
+    return base64url(b);
+}
+/** code_verifier'dan S256 code_challenge üretir. */
+export async function challengeFor(verifier, c = globalThis.crypto) {
+    const digest = await c.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+    return base64url(new Uint8Array(digest));
+}

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+/** `/_enformik/config.json` içindeki `auth` bloğu (site girişi açıkken yazılır). */
+export interface AuthConfig {
+    /** OIDC yayıncısı; token uç noktası `${authority}/oauth/v2/token`. */
+    authority: string;
+    /** Sitenin istemci kimliği (sırsız). */
+    clientId: string;
+    /** Barındırılan giriş sayfası; `${gatewayUrl}/login`. */
+    gatewayUrl: string;
+    /** Uygulamanın API projesi (access token'ın hedefi). */
+    audience: string;
+}
+/** `/_enformik/config.json` içeriği. */
+export interface SiteConfig {
+    appUrl: string;
+    apiUrl: string;
+    workspaceId?: string;
+    appCode?: string;
+    siteUrl?: string;
+    auth?: AuthConfig;
+}
+/** Oturumdaki kullanıcının kimliği (ID token'dan; yalnızca arayüzde göstermek içindir, API'ye gönderilmez). */
+export interface AuthUser {
+    sub: string;
+    email?: string;
+    name?: string;
+}
+export type AuthErrorCode = 'not_configured' | 'state_mismatch' | 'no_pending_login' | 'login_rejected' | 'token_exchange_failed' | 'not_authenticated';
+export declare class EnformikAuthError extends Error {
+    readonly code: AuthErrorCode;
+    constructor(code: AuthErrorCode, message: string);
+}
+/** Depolama soyutlaması (sessionStorage/localStorage ile uyumlu alt küme). */
+export interface KeyValueStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface AuthOptions {
+    /** Yapılandırma: nesne ya da adres. Varsayılan: `/_enformik/config.json`. */
+    config?: SiteConfig | string;
+    /** Giriş dönüş yolu; sitenin kayıtlı adreslerinden biri olmalı (`/`, `/callback`, `/auth/callback`, `/login/callback`). Varsayılan `/callback`. */
+    redirectPath?: string;
+    /** Çıkış sonrası dönüş yolu (`/` ya da `/login`). Varsayılan `/`. */
+    postLogoutPath?: string;
+    /** Belirteçlerin saklandığı yer: 'session' (varsayılan, sekme kapanınca silinir) ya da 'local'. */
+    storage?: 'session' | 'local' | KeyValueStorage;
+    /** Test/özel ortam için enjekte edilebilir bağımlılıklar. */
+    fetch?: typeof fetch;
+    location?: Pick<Location, 'origin' | 'href' | 'search' | 'pathname' | 'assign'>;
+    history?: Pick<History, 'replaceState'>;
+    crypto?: Crypto;
+    now?: () => number;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+export class EnformikAuthError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'EnformikAuthError';
+        this.code = code;
+    }
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@enformik/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Enformik web sitesi girişi: tarayıcı için OIDC yetkilendirme kodu + PKCE istemcisi (sıfır bağımlılık).",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test && npm run smoke",
+    "smoke": "node --input-type=module -e \"const m = await import('./dist/index.js'); if (typeof m.createAuth !== 'function') throw new Error('createAuth yok')\""
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.8"
+  },
+  "keywords": [
+    "enformik",
+    "auth",
+    "oidc",
+    "pkce",
+    "browser"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eyote-com/eyote.git",
+    "directory": "apps/enformik-auth"
+  },
+  "bugs": {
+    "url": "https://github.com/eyote-com/eyote/issues"
+  }
+}