@vikingokft/auth-client

Kliens oldali csomag a vikingo-auth-server szerverhez. Drop-in Google Workspace SSO Next.js appokhoz és Node CLI eszközökhöz.

Telepítés

A csomag public npm-en él, auth nélkül pull-olható:

npm install @vikingokft/auth-client

Nem kell .npmrc, nem kell token. (v0.5.0 és korábbi verziók GitHub Packages-en voltak — részletek a CHANGELOG-ban.)

Használat Next.js-ben

1. Regisztráld az appot a szerveren

curl -X POST https://vikingoauth.hu/register \
  -H "Authorization: Bearer $REGISTRATION_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "app_id": "my-app",
    "callback_urls": [
      "https://my-app.vercel.app/auth/callback",
      "http://localhost:3000/auth/callback"
    ]
  }'

A válaszban kapott client_secret-et tedd a .env.local-ba.

2. Környezeti változók

VIKINGO_AUTH_APP_ID=my-app
VIKINGO_AUTH_CLIENT_SECRET=<the-secret-from-register>
VIKINGO_AUTH_SESSION_SECRET=<openssl rand -hex 32>

3. middleware.ts — a repo gyökerében, VAGY src/middleware.ts ha src/-struktúrát használsz

Fontos: ha Next.js src/app/ vagy src/pages/ struktúrát használsz, a middleware.ts kötelezően a src/-ben legyen. A gyökérbe tett middleware.ts-t a Next.js build csendben kihagyja (üres middleware-manifest.json) és az SSO nem fog aktiválódni, hiba nélkül.

import { vikingoAuth } from '@vikingokft/auth-client/next'

export default vikingoAuth({
  appId: process.env.VIKINGO_AUTH_APP_ID!,
  clientSecret: process.env.VIKINGO_AUTH_CLIENT_SECRET!,
  sessionSecret: process.env.VIKINGO_AUTH_SESSION_SECRET!,
  publicPaths: ['/api/public', /^\/_next\//, /\.(ico|png|svg|webp)$/],
})

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}

Ennyi. Minden route védett, kivéve a publicPaths listát.

Vendég invite támogatás (v0.6.0+)

A middleware automatikusan kezeli a /auth/invite-callback path-ot, amit az auth-server /invite/redeem flow használ vendégekre. Ehhez nem kell semmit külön konfigurálnod.

A vendég session JWT guest: true claim-mel jön. A kódban:

import { getUser } from '@vikingokft/auth-client/next'

const user = await getUser(config)

if (user?.guest) {
  // Read-only mód, korlátozott feature-ök, "vendég vagy" hint, stb.
}

Custom path szabályozás (pl. ha nem /auth/-ba teszed a callback-eket):

vikingoAuth({
  callbackPath: '/login/callback',
  inviteCallbackPath: '/login/invite-callback',
  ...
})

A vendég session-öket az auth-server admin UI-ról vissza lehet vonni — a middleware periodikus /sync hívása észleli és kirúgja a sessiont (max ~5 perc latency).

4. User adatok elérése Server Components-ben

import { getUser } from '@vikingokft/auth-client/next'

export default async function Page() {
  const user = await getUser({
    appId: process.env.VIKINGO_AUTH_APP_ID!,
    clientSecret: process.env.VIKINGO_AUTH_CLIENT_SECRET!,
    sessionSecret: process.env.VIKINGO_AUTH_SESSION_SECRET!,
  })

  return <div>Szia, {user?.name}!</div>
}

Vagy ha csak gyors user info kell (middleware által beállított header-ből):

import { getUserFromHeaders } from '@vikingokft/auth-client/next'

const { email, sub } = await getUserFromHeaders() ?? {}

Használat Node CLI-ben

import { requireSSO } from '@vikingokft/auth-client/cli'

const user = await requireSSO({
  appId: 'my-cli-tool',
  clientSecret: process.env.VIKINGO_AUTH_CLIENT_SECRET!,
})

console.log(`Belépve mint ${user.email}`)
// ... a CLI továbblép

Első futtatáskor böngésző nyílik Google SSO-ra, a token ~/.vikingo/<appId>.json-ba mentődik (600 permission). Minden további futtatáskor a cache-ből veszi, és háttérben ellenőrzi a Workspace státuszt.

Hogyan működik

Kliens middleware                  vikingo-auth-server
─────────────────                  ───────────────────

no session cookie?
  │
  └─▶ redirect /authorize ───────▶ redirect to Google
                                         │
                                         ▼
                                   Google login
                                         │
                                         ▼
                                   /callback ─▶ issue auth code
                                                     │
                                                     ▼
  ◀─── redirect /auth/callback?code ─────────────────┘
       │
       └─▶ POST /token (code + client_secret) ──▶ return JWT + user
                                                     │
                                                     ▼
  set session cookie ◀─ pack user into session JWT ──┘
  redirect to original URL

Scriptek

npm run typecheck   # TypeScript check
npm run build       # Build to dist/

Kapcsolódó repók

• vikingo-auth-server — a központi szerver (Cloudflare Worker)
• vikingo-auth-template — új Next.js app sablon SSO-val (tervezett)