ETN Identity SDK

ስሪት 1.0.0 | የተለቀቀው: ጃንዋሪ 13, 2026

"ETN Identityን ለማዋሃድ ኦፊሴላዊው React SDK።"

ETN Identity SDK ሰነዶች (Documentation)

አጠቃላይ እይታ

ይህ SDK ገንቢዎች "በ ETN ይግቡ" (Sign in with ETN) ን ወደ መተግበሪያዎቻቸው እንዲያዋህዱ ይረዳቸዋል። ይህ በ ETN ስነ-ምህዳር (ለምሳሌ፡ ETN Vibe) ውስጥ ጥቅም ላይ የሚውለው መደበኛ የደህንነት ንድፍ (pattern) የሆነውን OIDC Authorization Code Flow ከ Token Rotation ጋር ይከተላል።

ውህደቱ ሁለት ክፍሎችን ያቀፈ ነው፡-

1. ግንባር-ገጽ (Frontend/Client): ተጠቃሚውን ወደ ETN Identity አቅራቢ ማዞር።
2. ኋላ-ገጽ (Backend/Server): ኮዱን ለቶከኖች መቀየር እና ክፍለ-ጊዜውን (session) ማስተዳደር።

መጫን (Installation)

npm install @etn-ecosystem/identity-sdk iron-session

(ማስታወሻ፡ iron-session ለደህንነቱ የተጠበቀ የኩኪ (cookie) አስተዳደር ይመከራል)።

1. የደንበኛ-ጎን (Client-Side): ወደ መግቢያ ማዞር

የፍቃድ ዩአርኤልን (authorization URL) ለመገንባት SDKውን ይጠቀሙ።

// src/lib/auth-client.ts
import { ETNAuthClient } from '@etn-ecosystem/identity-sdk';

export const authClient = new ETNAuthClient({
  clientId: process.env.ETN_CLIENT_ID!,
  redirectUri: process.env.ETN_REDIRECT_URI!,
  // ነባሪ (Default) scope 'openid profile offline_access' ነው
});

export function signIn() {
  // ለ CSRF ጥበቃ በዘፈቀደ state ያመነጫል
  const state = crypto.randomUUID(); 
  const url = authClient.buildAuthorizeUrl(state);
  window.location.href = url; // ወይም Next.js redirect() ይጠቀሙ
}

2. የአገልጋይ-ጎን (Server-Side): Callbackን እና የቶከን ልውውጥን ማስተናገድ

ከ ETN Identity የሚመጣውን ቅየራ (redirect) ለማስተናገድ የመንገድ ተቆጣጣሪ (route handler) ይፍጠሩ (ለምሳሌ በ Next.js ውስጥ app/api/auth/callback/route.ts)።

// app/api/auth/callback/route.ts
import { getSession } from '@/lib/session'; // ደረጃ 3ን ይመልከቱ
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const { code } = await req.json(); // ወይም GET ከሆነ ከ searchParams ያግኙ

  // ኮድን ለቶከኖች ይቀይሩ (Exchange Code for Tokens)
  const tokenResponse = await fetch('https://auth.etnecosystem.org/api/v1/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        grant_type: 'authorization_code',
        code: code,
        client_id: process.env.ETN_CLIENT_ID,
        client_secret: process.env.ETN_CLIENT_SECRET, // ይህንን ለደንበኛ (client) በጭራሽ አያጋልጡ
        redirect_uri: process.env.ETN_REDIRECT_URI,
    }),
  });

  const tokens = await tokenResponse.json();

  if (tokens.error) {
     return NextResponse.json({ error: tokens.error_description }, { status: 400 });
  }

  // ወደ ክፍለ-ጊዜ (Session) ያስቀምጡ
  const session = await getSession();
  session.isLoggedIn = true;
  session.token = tokens.access_token;
  session.refreshToken = tokens.refresh_token; 
  // የአገልግሎት ማብቂያን ያስሉ: አሁን + expires_in - 1 ደቂቃ መጠባበቂያ
  session.expiresAt = Date.now() + (tokens.expires_in * 1000) - 60000;
  
  await session.save();

  return NextResponse.json({ success: true });
}

3. የክፍለ-ጊዜ አስተዳደር እና የቶከን ሽክርክሪት (Token Rotation)

ተጠቃሚው ደህንነቱ በተጠበቀ ሁኔታ እንደገባ እንዲቆይ የቶከን ሽክርክሪት (Token Rotation) መተግበር ወሳኝ ነው። የመዳረሻ ቶከን (Access Token) በ1 ሰዓት ውስጥ ጊዜው ያልፍበታል፤ ተጠቃሚው እንደገና እንዲገባ ሳያስገድዱ አዲስ ለማግኘት የማደሻ ቶከን (Refresh Token) ይጠቀሙ።

ረዳት src/lib/session.ts ይፍጠሩ (iron-session በመጠቀም):

import { getIronSession } from 'iron-session';
import { cookies } from 'next/headers';

// ... የክፍለ-ጊዜ ውሂብ በይነገጽ (Session Data Interface) ...

export async function getValidSession({ redirectOnExpire = false } = {}) {
  const session = await getSession();

  if (!session.isLoggedIn || !session.expiresAt) return session;

  // የመዳረሻ ቶከን ጊዜው ያለፈበት መሆኑን ያረጋግጡ
  if (Date.now() > session.expiresAt) {
    if (redirectOnExpire) {
       // በአገልጋይ አካላት (Server Components) ውስጥ ኩኪዎችን ማዘጋጀት ስለማንችል፣ ወደሚችል መንገድ እናዞራለን።
       const { redirect } = await import('next/navigation');
       redirect('/api/auth/refresh'); 
    }

    // ማደስን ይሞክሩ (Server Actions / Route Handlers ብቻ)
    try {
        const res = await fetch("https://auth.etnecosystem.org/api/v1/oauth/token", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({
                grant_type: "refresh_token",
                refresh_token: session.refreshToken,
                client_id: process.env.ETN_CLIENT_ID,
                client_secret: process.env.ETN_CLIENT_SECRET,
            }),
        });
        
        const newTokens = await res.json();
        // ክፍለ-ጊዜውን በአዲስ ቶከኖች ያዘምኑ
        session.token = newTokens.access_token;
        if (newTokens.refresh_token) session.refreshToken = newTokens.refresh_token;
        session.expiresAt = Date.now() + (newTokens.expires_in * 1000) - 60000;
        await session.save();
    } catch (e) {
        session.isLoggedIn = false;
        // ስህተትን ያስተናግዱ
    }
  }
  return session;
}

4. ገጾችን መጠበቅ (Protecting Pages)

በተጠበቁ ገጾችዎ (Server Components) ውስጥ፣ ሁልጊዜ getValidSessionን ከ redirectOnExpire: true ጋር ይጥሩ።

// app/dashboard/page.tsx
export default async function Dashboard() {
  // ይህ የአገልግሎት ማብቂያን ያረጋግጣል እና አስፈላጊ ከሆነ ወደ ማደስ (refresh) ያዞራል
  const session = await getValidSession({ redirectOnExpire: true });

  if (!session.isLoggedIn) redirect('/');

  // ...
}