@futdevpro/nts-dynamo 1.15.150 → 1.15.153

package/src/_collections/npm-token-check.util.ts

@@ -1,327 +1,327 @@
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-
-import { DyFM_Log } from '@futdevpro/fsm-dynamo';
-
-/**
- * FR-320 — NPM-TOKEN ALLAPOT-OSZTALYOZO (bedrock).
- *
- * MIERT KELLETT (2026-08-20..22, valos incidens): a flotta npm-tokenje lejart, majd egy olyan
- * pot-token kerult be, aminek NEM volt 2FA-bypass joga. A kovetkezmeny NAPOKIG tartott es
- * MINDENHOL `E404`-kent jelentkezett — privat csomagnal ugyanis az npm a jogosulatlan kerest
- * 404-gyel utasitja el, NEM 401-gyel. Emiatt a "nincs ilyen csomag", a "lejart kulcs" es a
- * "rossz jogu kulcs" MEGKULONBOZTETHETETLEN volt, es a diagnozis tobb kort vitt el.
- *
- * A KULCS-DISZKRIMINATOR: a `/-/whoami` vegpont NEM csomag-fuggo, ezert nem esik bele a privat-404
- * elrejtesbe:
- *   - token NELKUL / ROSSZ tokennel -> **401**
- *   - ERVENYES tokennel             -> **200** + a felhasznalonev
- * Innen a csomag-szintu proba mar ertelmezheto: ha a whoami OK, de a scope-olt csomag 404, akkor a
- * token EL, csak nincs joga hozza.
- *
- * ⚠️ AMIT EZ NEM TUD MEGALLAPITANI (szandekosan kimondva, hogy ne igerjunk tobbet a valosagnal):
- *   - a **2FA-bypass** hianya CSAK publikalaskor derul ki (`EOTP` hibakod) — read-only probaval nem;
- *   - a **lejart** es a **visszavont** token kivulrol egyforman 401;
- *   - a token **elettartama** nem kerdezheto le.
- * Ezert a `publishErrorCode` opcionalis bemenet: ha egy publish mar elbukott, az `EOTP` alapjan
- * ERRE is tudunk hatarozott allapotot mondani.
- *
- * A TOKEN ERTEKE SOSEM KERUL A KIMENETBE — sem logba, sem eredmenybe.
- */
-
-/** Az npm-token megallapithato allapotai. */
-export enum DyNTS_NpmTokenState {
-  /** Nincs beallitva token (se env, se .npmrc). */
-  missing = 'missing',
-  /** Van ertek, de nem npm-token alaku — jellemzoen elgepeles / rossz valtozo. */
-  malformed = 'malformed',
-  /** A registry elutasitja (401): lejart, visszavont vagy egyszeruen rossz. */
-  invalid = 'invalid',
-  /** A token EL (whoami OK), de a vizsgalt scope-hoz/csomaghoz NINCS joga. */
-  noScopeAccess = 'no-scope-access',
-  /** A token el es olvas, de publikalasra nincs joga (2FA-bypass hianya — `EOTP`). */
-  missingPublishRight = 'missing-publish-right',
-  /** Minden vizsgalt kepesseg rendben. */
-  ok = 'ok',
-  /** A proba maga nem futott le (halozat/timeout) — NEM azonos azzal, hogy a token rossz. */
-  unknown = 'unknown',
-}
-
-/** A helyi (halozat NELKULI) alak-ellenorzes eredmenye. */
-export enum DyNTS_NpmTokenShape {
-  missing = 'missing',
-  malformed = 'malformed',
-  plausible = 'plausible',
-}
-
-/**
- * PURE — a token ALAKJANAK ellenorzese, halozat nelkul.
- *
- * MIERT KULON LEPES: a "nincs beallitva" es a "rosszul beallitva" eseteket halozat nelkul, azonnal
- * es egyertelmuen el lehet donteni — ezek a leggyakoribb operatori hibak (ures env-var, idezojelek
- * bennragadtak, a `//registry…/:_authToken=` PREFIX is bemasolodott).
- *
- * Az npm mai token-alakjai `npm_`-mel kezdodnek (classic automation + granular). A regi, prefix
- * nelkuli UUID-alaku tokenek MEG ervenyesek lehetnek, ezert azokat is `plausible`-nek vesszuk —
- * inkabb engedunk at egy kesobb 401-et kapo tokent, mint hogy egy jot elutasitsunk.
- */
-export function classifyNpmTokenShape(rawToken: string | undefined | null): DyNTS_NpmTokenShape {
-  const token: string = (rawToken ?? '').trim();
-  if (!token) { return DyNTS_NpmTokenShape.missing; }
-
-  // Gyakori elgepeles: a teljes .npmrc-sor kerult be a token helyere.
-  if (token.includes('_authToken') || token.includes('registry.npmjs.org')) {
-    return DyNTS_NpmTokenShape.malformed;
-  }
-  // Bennragadt idezojelek / whitespace a valtozo erteken belul.
-  if (/["'\s]/.test(token)) { return DyNTS_NpmTokenShape.malformed; }
-  // Nyilvanvaloan tul rovid ertek (pl. "x", "changeme").
-  if (token.length < 24) { return DyNTS_NpmTokenShape.malformed; }
-
-  return DyNTS_NpmTokenShape.plausible;
-}
-
-/**
- * Publish-oldali npm-hibakodok, amik ELO token mellett JOGOSULTSAG-hianyt jelentenek.
- *
- * A lista SZANDEKOSAN tartalmazza az `E404`-et: az npm a `PUT` (publish) kerest is 404-gyel
- * utasitja el, ha a tokennek nincs irasi joga a csomagra. Elo token mellett ez SOSEM jelentheti,
- * hogy a csomag hianyzik — hiszen olvasni tudtuk.
- */
-export const PUBLISH_RIGHT_ERROR_CODES: string[] = ['EOTP', 'E403', 'E404'];
-
-/** A halozati proba nyers bemenete (a `classifyNpmTokenProbe` szamara). */
-export interface DyNTS_NpmTokenProbe_Input {
-  /** A `/-/whoami` HTTP-statusza. `null`, ha a hivas el sem jutott a szerverig. */
-  whoamiStatus: number | null;
-  /** Egy SCOPE-olt (jellemzoen privat) csomag metaadat-lekeresenek statusza; `undefined` = nem mertuk. */
-  scopedPackageStatus?: number;
-  /** Ha egy publish MAR elbukott, annak npm-hibakodja (pl. `EOTP`, `E403`); `undefined` = nem mertuk. */
-  publishErrorCode?: string;
-}
-
-/**
- * PURE — a halozati valaszokbol allapot.
- *
- * A sorrend SZANDEKOS: a `whoami` az egyetlen csomag-fuggetlen jel, ezert az dont eloszor. Csak
- * utana ertelmezheto a csomag-szintu 404 — kulonben ugyanaz a 404 jelentene "nincs ilyen csomag"-ot
- * es "rossz kulcs"-ot is, ami epp a 2026-08-i incidens diagnozisat huzta el.
- */
-export function classifyNpmTokenProbe(input: DyNTS_NpmTokenProbe_Input): DyNTS_NpmTokenState {
-  // A proba el sem jutott a registryig -> NEM allitunk semmit a tokenrol.
-  if (input.whoamiStatus === null) { return DyNTS_NpmTokenState.unknown; }
-
-  // 401 = a registry elutasitja a hitelesitest (hianyzo/lejart/visszavont/rossz token).
-  if (input.whoamiStatus === 401) { return DyNTS_NpmTokenState.invalid; }
-
-  // Barmi mas, ami nem 200: nem tudunk hatarozott allapotot mondani (5xx, rate-limit, proxy).
-  if (input.whoamiStatus !== 200) { return DyNTS_NpmTokenState.unknown; }
-
-  // Innentol a token IGAZOLTAN el (whoami 200). Ezert BARMILYEN publish-oldali elutasitas
-  // JOGOSULTSAG-hiany, NEM hianyzo csomag:
-  //   EOTP  -> 2FA-bypass hianya,
-  //   E403  -> explicit tiltas,
-  //   E404  -> az npm a PUT-ra is 404-gyel valaszol, ha a tokennek NINCS IRASI joga a csomagra
-  //            (ugyanaz a letezes-elrejtes, mint olvasasnal).
-  // MERVE (2026-08-22): `npm error 404 Not Found - PUT .../@futdevpro%2fnts-dynamo` — mikozben
-  // UGYANAZ a token olvasni tudta a csomagot. Enelkul a megkulonboztetes nelkul ez "nincs ilyen
-  // csomag"-nak latszik, es epp ez vitte felre a diagnozist napokig.
-  if (PUBLISH_RIGHT_ERROR_CODES.includes((input.publishErrorCode ?? '').toUpperCase())) {
-    return DyNTS_NpmTokenState.missingPublishRight;
-  }
-
-  // Elo token + a scope-olt csomag 404/403 -> a token nem lat ra a csomagra (jogosultsag).
-  if (input.scopedPackageStatus === 404 || input.scopedPackageStatus === 403) {
-    return DyNTS_NpmTokenState.noScopeAccess;
-  }
-  // A csomag-probat nem mertuk, vagy sikeres volt.
-  if (input.scopedPackageStatus === undefined || input.scopedPackageStatus === 200) {
-    return DyNTS_NpmTokenState.ok;
-  }
-  return DyNTS_NpmTokenState.unknown;
-}
-
-/**
- * PURE — ember-olvashato magyarazat + a KOVETKEZO LEPES. A puszta allapot-cimke keves: az operator
- * azt akarja tudni, mit tegyen.
- */
-export function describeNpmTokenState(state: DyNTS_NpmTokenState): string {
-  switch (state) {
-    case DyNTS_NpmTokenState.missing:
-      return 'Nincs beallitva npm-token. Teendo: allitsd be a Keystore/CI kornyezetben (NEM .npmrc-fajlban).';
-    case DyNTS_NpmTokenState.malformed:
-      return 'A token erteke nem npm-token alaku (idezojel, whitespace, vagy a teljes .npmrc-sor kerult be). '
-        + 'Teendo: csak a NYERS token-erteket add meg.';
-    case DyNTS_NpmTokenState.invalid:
-      return 'A registry ELUTASITJA a tokent (401): lejart, visszavont vagy rossz. Teendo: uj token. '
-        + 'FIGYELEM: privat csomagnal ez a hiba a HIVOKNAL 404-kent jelenik meg, nem 401-kent.';
-    case DyNTS_NpmTokenState.noScopeAccess:
-      return 'A token EL, de a vizsgalt scope-hoz/csomaghoz nincs joga (a whoami rendben, a csomag 404/403). '
-        + 'Teendo: a token jogosultsagi koret bovitsd a scope-ra.';
-    case DyNTS_NpmTokenState.missingPublishRight:
-      return 'A token EL es OLVAS, de PUBLIKALNI nem tud (`EOTP` / `E403` / publish-oldali `E404`): '
-        + 'hianyzik az iras/2FA-bypass jog. FIGYELEM: a PUT-ra kapott 404 NEM hianyzo csomagot jelent, '
-        + 'hanem jogosultsag-hianyt. Teendo: automation/granular token IRASI joggal a scope-ra.';
-    case DyNTS_NpmTokenState.ok:
-      return 'A token ervenyes, es a vizsgalt csomagot is eleri.';
-    default:
-      return 'A proba nem jutott el a registryig (halozat/timeout/proxy) — ez NEM bizonyitja, hogy a token rossz.';
-  }
-}
-
-/** A teljes ellenorzes eredmenye. A token ERTEKE sosem szerepel benne. */
-export interface DyNTS_NpmTokenCheck_Result {
-  state: DyNTS_NpmTokenState;
-  /** A `/-/whoami` altal visszaadott felhasznalonev, ha a token ervenyes. */
-  username: string | null;
-  /** Ember-olvashato magyarazat + kovetkezo lepes. */
-  detail: string;
-  /** Amit tenylegesen mertunk (diagnosztikahoz). */
-  probe: DyNTS_NpmTokenProbe_Input;
-}
-
-/** A `checkNpmToken` bemenete. */
-export interface DyNTS_NpmTokenCheck_Options {
-  /** A vizsgalando token. Ha nincs megadva, a `process.env.NPM_TOKEN`-t hasznaljuk. */
-  token?: string;
-  /** Registry-alap. Default: a publikus npm. */
-  registry?: string;
-  /**
-   * Egy SCOPE-olt csomag, amin a jogosultsagot merjuk (pl. `@futdevpro/cli-dynamo`).
-   * Ha nincs megadva, csak a whoami fut le.
-   */
-  scopedPackage?: string;
-  /** Ha egy publish mar elbukott, annak npm-hibakodja — igy a 2FA-bypass hianya is besorolhato. */
-  publishErrorCode?: string;
-  /** Halozati timeout (ms). Default: 10000. */
-  timeoutMs?: number;
-}
-
-/**
- * PURE — token kinyerese egy `.npmrc` TARTALMABOL.
- *
- * MIERT KELL: az elso valtozat CSAK a `process.env.NPM_TOKEN`-t nezte, es ezert a sajat
- * workstationomon `missing`-et adott — HOLOTT az npm ott tokeletesen mukodott, mert a token a
- * `~/.npmrc`-ben all. Ez HAMIS NEGATIV, es epp a legfontosabb helyeken (runner-kontener, hosztok)
- * sulna el, ahol a token szinten FAJLBAN van.
- *
- * A `.npmrc`-t csak OLVASSUK — letrehozni tilos (flotta-szintu hard rule).
- */
-export function extractTokenFromNpmrc(content: string, registry: string = DEFAULT_REGISTRY): string | null {
-  const host: string = registry.replace(/^https?:/, '').replace(/\/+$/, '');
-  for (const rawLine of content.split(/\r?\n/)) {
-    const line: string = rawLine.trim();
-    if (!line || line.startsWith('#') || line.startsWith(';')) { continue; }
-    // Alak: `//registry.npmjs.org/:_authToken=<ertek>` (a host elotti `//` a kulcs resze).
-    const match: RegExpMatchArray | null = line.match(/^(\/\/[^:]+):_authToken=(.+)$/);
-    if (!match) { continue; }
-    // A `.npmrc` a hostot ZARO PERJELLEL irja (`//registry.npmjs.org/`), a normalizalt
-    // `host` viszont nelkule all — ezert MINDKET oldalt normalizalni kell. Az elso
-    // valtozatom csak az egyiket tette, es ezert SOSEM illeszkedett (a specek fogtak meg).
-    const lineHost: string = match[1].replace(/\/+$/, '');
-    if (lineHost !== host) { continue; }
-    const value: string = match[2].trim().replace(/^["']|["']$/g, '');
-    if (value) { return value; }
-  }
-  return null;
-}
-
-/**
- * A token feloldasa a szokasos helyekrol, PRIORITAS szerint:
- *   1. explicit parameter, 2. `NPM_TOKEN` env, 3. a felhasznaloi `~/.npmrc`.
- * Sose dob; ha egyik sincs, ures stringet ad.
- */
-export function resolveNpmToken(explicit: string | undefined, registry: string): string {
-  const fromExplicit: string = (explicit ?? '').trim();
-  if (fromExplicit) { return fromExplicit; }
-  const fromEnv: string = (process.env.NPM_TOKEN ?? '').trim();
-  if (fromEnv) { return fromEnv; }
-  try {
-    const npmrcPath: string = path.join(os.homedir(), '.npmrc');
-    if (fs.existsSync(npmrcPath)) {
-      return extractTokenFromNpmrc(fs.readFileSync(npmrcPath, 'utf-8'), registry) ?? '';
-    }
-  } catch {
-    // A fajl-olvasas hibaja NEM buktathatja az ellenorzest.
-  }
-  return '';
-}
-
-const DEFAULT_REGISTRY: string = 'https://registry.npmjs.org';
-const DEFAULT_TIMEOUT_MS: number = 10000;
-
-/** Egy statusz-lekeres, timeout-tal. `null`, ha el sem jutottunk a szerverig. */
-async function fetchStatus(url: string, token: string | null, timeoutMs: number): Promise<number | null> {
-  const controller: AbortController = new AbortController();
-  const timer: NodeJS.Timeout = setTimeout((): void => { controller.abort(); }, timeoutMs);
-  try {
-    const response: Response = await fetch(url, {
-      headers: token ? { authorization: `Bearer ${token}` } : {},
-      signal: controller.signal,
-    });
-    return response.status;
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-/**
- * A tenyleges ellenorzes. SOSE dob — a hibat allapotkent adja vissza (a token-ellenorzes nem
- * buktathat meg semmit, amibe beepitjuk).
- */
-export async function checkNpmToken(
-  options: DyNTS_NpmTokenCheck_Options = {},
-): Promise<DyNTS_NpmTokenCheck_Result> {
-  const registry: string = (options.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, '');
-  const token: string = resolveNpmToken(options.token, registry);
-  const timeoutMs: number = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-
-  const shape: DyNTS_NpmTokenShape = classifyNpmTokenShape(token);
-  if (shape !== DyNTS_NpmTokenShape.plausible) {
-    const localState: DyNTS_NpmTokenState = shape === DyNTS_NpmTokenShape.missing
-      ? DyNTS_NpmTokenState.missing
-      : DyNTS_NpmTokenState.malformed;
-    return {
-      state: localState,
-      username: null,
-      detail: describeNpmTokenState(localState),
-      probe: { whoamiStatus: null },
-    };
-  }
-
-  const whoamiStatus: number | null = await fetchStatus(`${registry}/-/whoami`, token, timeoutMs);
-
-  let username: string | null = null;
-  if (whoamiStatus === 200) {
-    try {
-      const response: Response = await fetch(`${registry}/-/whoami`, {
-        headers: { authorization: `Bearer ${token}` },
-      });
-      const body: { username?: string } = await response.json() as { username?: string };
-      username = typeof body.username === 'string' ? body.username : null;
-    } catch {
-      username = null;
-    }
-  }
-
-  let scopedPackageStatus: number | undefined;
-  if (options.scopedPackage && whoamiStatus === 200) {
-    const encoded: string = options.scopedPackage.replace('/', '%2f');
-    const status: number | null = await fetchStatus(`${registry}/${encoded}`, token, timeoutMs);
-    scopedPackageStatus = status === null ? undefined : status;
-  }
-
-  const probe: DyNTS_NpmTokenProbe_Input = {
-    whoamiStatus: whoamiStatus,
-    scopedPackageStatus: scopedPackageStatus,
-    publishErrorCode: options.publishErrorCode,
-  };
-  const state: DyNTS_NpmTokenState = classifyNpmTokenProbe(probe);
-
-  DyFM_Log.info(`[npm-token-check] allapot=${state}${username ? ` user=${username}` : ''} (a token erteke NEM naplozodik)`);
-
-  return { state: state, username: username, detail: describeNpmTokenState(state), probe: probe };
-}
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { DyFM_Log } from '@futdevpro/fsm-dynamo';
+
+/**
+ * FR-320 — NPM-TOKEN ALLAPOT-OSZTALYOZO (bedrock).
+ *
+ * MIERT KELLETT (2026-08-20..22, valos incidens): a flotta npm-tokenje lejart, majd egy olyan
+ * pot-token kerult be, aminek NEM volt 2FA-bypass joga. A kovetkezmeny NAPOKIG tartott es
+ * MINDENHOL `E404`-kent jelentkezett — privat csomagnal ugyanis az npm a jogosulatlan kerest
+ * 404-gyel utasitja el, NEM 401-gyel. Emiatt a "nincs ilyen csomag", a "lejart kulcs" es a
+ * "rossz jogu kulcs" MEGKULONBOZTETHETETLEN volt, es a diagnozis tobb kort vitt el.
+ *
+ * A KULCS-DISZKRIMINATOR: a `/-/whoami` vegpont NEM csomag-fuggo, ezert nem esik bele a privat-404
+ * elrejtesbe:
+ *   - token NELKUL / ROSSZ tokennel -> **401**
+ *   - ERVENYES tokennel             -> **200** + a felhasznalonev
+ * Innen a csomag-szintu proba mar ertelmezheto: ha a whoami OK, de a scope-olt csomag 404, akkor a
+ * token EL, csak nincs joga hozza.
+ *
+ * ⚠️ AMIT EZ NEM TUD MEGALLAPITANI (szandekosan kimondva, hogy ne igerjunk tobbet a valosagnal):
+ *   - a **2FA-bypass** hianya CSAK publikalaskor derul ki (`EOTP` hibakod) — read-only probaval nem;
+ *   - a **lejart** es a **visszavont** token kivulrol egyforman 401;
+ *   - a token **elettartama** nem kerdezheto le.
+ * Ezert a `publishErrorCode` opcionalis bemenet: ha egy publish mar elbukott, az `EOTP` alapjan
+ * ERRE is tudunk hatarozott allapotot mondani.
+ *
+ * A TOKEN ERTEKE SOSEM KERUL A KIMENETBE — sem logba, sem eredmenybe.
+ */
+
+/** Az npm-token megallapithato allapotai. */
+export enum DyNTS_NpmTokenState {
+  /** Nincs beallitva token (se env, se .npmrc). */
+  missing = 'missing',
+  /** Van ertek, de nem npm-token alaku — jellemzoen elgepeles / rossz valtozo. */
+  malformed = 'malformed',
+  /** A registry elutasitja (401): lejart, visszavont vagy egyszeruen rossz. */
+  invalid = 'invalid',
+  /** A token EL (whoami OK), de a vizsgalt scope-hoz/csomaghoz NINCS joga. */
+  noScopeAccess = 'no-scope-access',
+  /** A token el es olvas, de publikalasra nincs joga (2FA-bypass hianya — `EOTP`). */
+  missingPublishRight = 'missing-publish-right',
+  /** Minden vizsgalt kepesseg rendben. */
+  ok = 'ok',
+  /** A proba maga nem futott le (halozat/timeout) — NEM azonos azzal, hogy a token rossz. */
+  unknown = 'unknown',
+}
+
+/** A helyi (halozat NELKULI) alak-ellenorzes eredmenye. */
+export enum DyNTS_NpmTokenShape {
+  missing = 'missing',
+  malformed = 'malformed',
+  plausible = 'plausible',
+}
+
+/**
+ * PURE — a token ALAKJANAK ellenorzese, halozat nelkul.
+ *
+ * MIERT KULON LEPES: a "nincs beallitva" es a "rosszul beallitva" eseteket halozat nelkul, azonnal
+ * es egyertelmuen el lehet donteni — ezek a leggyakoribb operatori hibak (ures env-var, idezojelek
+ * bennragadtak, a `//registry…/:_authToken=` PREFIX is bemasolodott).
+ *
+ * Az npm mai token-alakjai `npm_`-mel kezdodnek (classic automation + granular). A regi, prefix
+ * nelkuli UUID-alaku tokenek MEG ervenyesek lehetnek, ezert azokat is `plausible`-nek vesszuk —
+ * inkabb engedunk at egy kesobb 401-et kapo tokent, mint hogy egy jot elutasitsunk.
+ */
+export function classifyNpmTokenShape(rawToken: string | undefined | null): DyNTS_NpmTokenShape {
+  const token: string = (rawToken ?? '').trim();
+  if (!token) { return DyNTS_NpmTokenShape.missing; }
+
+  // Gyakori elgepeles: a teljes .npmrc-sor kerult be a token helyere.
+  if (token.includes('_authToken') || token.includes('registry.npmjs.org')) {
+    return DyNTS_NpmTokenShape.malformed;
+  }
+  // Bennragadt idezojelek / whitespace a valtozo erteken belul.
+  if (/["'\s]/.test(token)) { return DyNTS_NpmTokenShape.malformed; }
+  // Nyilvanvaloan tul rovid ertek (pl. "x", "changeme").
+  if (token.length < 24) { return DyNTS_NpmTokenShape.malformed; }
+
+  return DyNTS_NpmTokenShape.plausible;
+}
+
+/**
+ * Publish-oldali npm-hibakodok, amik ELO token mellett JOGOSULTSAG-hianyt jelentenek.
+ *
+ * A lista SZANDEKOSAN tartalmazza az `E404`-et: az npm a `PUT` (publish) kerest is 404-gyel
+ * utasitja el, ha a tokennek nincs irasi joga a csomagra. Elo token mellett ez SOSEM jelentheti,
+ * hogy a csomag hianyzik — hiszen olvasni tudtuk.
+ */
+export const PUBLISH_RIGHT_ERROR_CODES: string[] = ['EOTP', 'E403', 'E404'];
+
+/** A halozati proba nyers bemenete (a `classifyNpmTokenProbe` szamara). */
+export interface DyNTS_NpmTokenProbe_Input {
+  /** A `/-/whoami` HTTP-statusza. `null`, ha a hivas el sem jutott a szerverig. */
+  whoamiStatus: number | null;
+  /** Egy SCOPE-olt (jellemzoen privat) csomag metaadat-lekeresenek statusza; `undefined` = nem mertuk. */
+  scopedPackageStatus?: number;
+  /** Ha egy publish MAR elbukott, annak npm-hibakodja (pl. `EOTP`, `E403`); `undefined` = nem mertuk. */
+  publishErrorCode?: string;
+}
+
+/**
+ * PURE — a halozati valaszokbol allapot.
+ *
+ * A sorrend SZANDEKOS: a `whoami` az egyetlen csomag-fuggetlen jel, ezert az dont eloszor. Csak
+ * utana ertelmezheto a csomag-szintu 404 — kulonben ugyanaz a 404 jelentene "nincs ilyen csomag"-ot
+ * es "rossz kulcs"-ot is, ami epp a 2026-08-i incidens diagnozisat huzta el.
+ */
+export function classifyNpmTokenProbe(input: DyNTS_NpmTokenProbe_Input): DyNTS_NpmTokenState {
+  // A proba el sem jutott a registryig -> NEM allitunk semmit a tokenrol.
+  if (input.whoamiStatus === null) { return DyNTS_NpmTokenState.unknown; }
+
+  // 401 = a registry elutasitja a hitelesitest (hianyzo/lejart/visszavont/rossz token).
+  if (input.whoamiStatus === 401) { return DyNTS_NpmTokenState.invalid; }
+
+  // Barmi mas, ami nem 200: nem tudunk hatarozott allapotot mondani (5xx, rate-limit, proxy).
+  if (input.whoamiStatus !== 200) { return DyNTS_NpmTokenState.unknown; }
+
+  // Innentol a token IGAZOLTAN el (whoami 200). Ezert BARMILYEN publish-oldali elutasitas
+  // JOGOSULTSAG-hiany, NEM hianyzo csomag:
+  //   EOTP  -> 2FA-bypass hianya,
+  //   E403  -> explicit tiltas,
+  //   E404  -> az npm a PUT-ra is 404-gyel valaszol, ha a tokennek NINCS IRASI joga a csomagra
+  //            (ugyanaz a letezes-elrejtes, mint olvasasnal).
+  // MERVE (2026-08-22): `npm error 404 Not Found - PUT .../@futdevpro%2fnts-dynamo` — mikozben
+  // UGYANAZ a token olvasni tudta a csomagot. Enelkul a megkulonboztetes nelkul ez "nincs ilyen
+  // csomag"-nak latszik, es epp ez vitte felre a diagnozist napokig.
+  if (PUBLISH_RIGHT_ERROR_CODES.includes((input.publishErrorCode ?? '').toUpperCase())) {
+    return DyNTS_NpmTokenState.missingPublishRight;
+  }
+
+  // Elo token + a scope-olt csomag 404/403 -> a token nem lat ra a csomagra (jogosultsag).
+  if (input.scopedPackageStatus === 404 || input.scopedPackageStatus === 403) {
+    return DyNTS_NpmTokenState.noScopeAccess;
+  }
+  // A csomag-probat nem mertuk, vagy sikeres volt.
+  if (input.scopedPackageStatus === undefined || input.scopedPackageStatus === 200) {
+    return DyNTS_NpmTokenState.ok;
+  }
+  return DyNTS_NpmTokenState.unknown;
+}
+
+/**
+ * PURE — ember-olvashato magyarazat + a KOVETKEZO LEPES. A puszta allapot-cimke keves: az operator
+ * azt akarja tudni, mit tegyen.
+ */
+export function describeNpmTokenState(state: DyNTS_NpmTokenState): string {
+  switch (state) {
+    case DyNTS_NpmTokenState.missing:
+      return 'Nincs beallitva npm-token. Teendo: allitsd be a Keystore/CI kornyezetben (NEM .npmrc-fajlban).';
+    case DyNTS_NpmTokenState.malformed:
+      return 'A token erteke nem npm-token alaku (idezojel, whitespace, vagy a teljes .npmrc-sor kerult be). '
+        + 'Teendo: csak a NYERS token-erteket add meg.';
+    case DyNTS_NpmTokenState.invalid:
+      return 'A registry ELUTASITJA a tokent (401): lejart, visszavont vagy rossz. Teendo: uj token. '
+        + 'FIGYELEM: privat csomagnal ez a hiba a HIVOKNAL 404-kent jelenik meg, nem 401-kent.';
+    case DyNTS_NpmTokenState.noScopeAccess:
+      return 'A token EL, de a vizsgalt scope-hoz/csomaghoz nincs joga (a whoami rendben, a csomag 404/403). '
+        + 'Teendo: a token jogosultsagi koret bovitsd a scope-ra.';
+    case DyNTS_NpmTokenState.missingPublishRight:
+      return 'A token EL es OLVAS, de PUBLIKALNI nem tud (`EOTP` / `E403` / publish-oldali `E404`): '
+        + 'hianyzik az iras/2FA-bypass jog. FIGYELEM: a PUT-ra kapott 404 NEM hianyzo csomagot jelent, '
+        + 'hanem jogosultsag-hianyt. Teendo: automation/granular token IRASI joggal a scope-ra.';
+    case DyNTS_NpmTokenState.ok:
+      return 'A token ervenyes, es a vizsgalt csomagot is eleri.';
+    default:
+      return 'A proba nem jutott el a registryig (halozat/timeout/proxy) — ez NEM bizonyitja, hogy a token rossz.';
+  }
+}
+
+/** A teljes ellenorzes eredmenye. A token ERTEKE sosem szerepel benne. */
+export interface DyNTS_NpmTokenCheck_Result {
+  state: DyNTS_NpmTokenState;
+  /** A `/-/whoami` altal visszaadott felhasznalonev, ha a token ervenyes. */
+  username: string | null;
+  /** Ember-olvashato magyarazat + kovetkezo lepes. */
+  detail: string;
+  /** Amit tenylegesen mertunk (diagnosztikahoz). */
+  probe: DyNTS_NpmTokenProbe_Input;
+}
+
+/** A `checkNpmToken` bemenete. */
+export interface DyNTS_NpmTokenCheck_Options {
+  /** A vizsgalando token. Ha nincs megadva, a `process.env.NPM_TOKEN`-t hasznaljuk. */
+  token?: string;
+  /** Registry-alap. Default: a publikus npm. */
+  registry?: string;
+  /**
+   * Egy SCOPE-olt csomag, amin a jogosultsagot merjuk (pl. `@futdevpro/cli-dynamo`).
+   * Ha nincs megadva, csak a whoami fut le.
+   */
+  scopedPackage?: string;
+  /** Ha egy publish mar elbukott, annak npm-hibakodja — igy a 2FA-bypass hianya is besorolhato. */
+  publishErrorCode?: string;
+  /** Halozati timeout (ms). Default: 10000. */
+  timeoutMs?: number;
+}
+
+/**
+ * PURE — token kinyerese egy `.npmrc` TARTALMABOL.
+ *
+ * MIERT KELL: az elso valtozat CSAK a `process.env.NPM_TOKEN`-t nezte, es ezert a sajat
+ * workstationomon `missing`-et adott — HOLOTT az npm ott tokeletesen mukodott, mert a token a
+ * `~/.npmrc`-ben all. Ez HAMIS NEGATIV, es epp a legfontosabb helyeken (runner-kontener, hosztok)
+ * sulna el, ahol a token szinten FAJLBAN van.
+ *
+ * A `.npmrc`-t csak OLVASSUK — letrehozni tilos (flotta-szintu hard rule).
+ */
+export function extractTokenFromNpmrc(content: string, registry: string = DEFAULT_REGISTRY): string | null {
+  const host: string = registry.replace(/^https?:/, '').replace(/\/+$/, '');
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line: string = rawLine.trim();
+    if (!line || line.startsWith('#') || line.startsWith(';')) { continue; }
+    // Alak: `//registry.npmjs.org/:_authToken=<ertek>` (a host elotti `//` a kulcs resze).
+    const match: RegExpMatchArray | null = line.match(/^(\/\/[^:]+):_authToken=(.+)$/);
+    if (!match) { continue; }
+    // A `.npmrc` a hostot ZARO PERJELLEL irja (`//registry.npmjs.org/`), a normalizalt
+    // `host` viszont nelkule all — ezert MINDKET oldalt normalizalni kell. Az elso
+    // valtozatom csak az egyiket tette, es ezert SOSEM illeszkedett (a specek fogtak meg).
+    const lineHost: string = match[1].replace(/\/+$/, '');
+    if (lineHost !== host) { continue; }
+    const value: string = match[2].trim().replace(/^["']|["']$/g, '');
+    if (value) { return value; }
+  }
+  return null;
+}
+
+/**
+ * A token feloldasa a szokasos helyekrol, PRIORITAS szerint:
+ *   1. explicit parameter, 2. `NPM_TOKEN` env, 3. a felhasznaloi `~/.npmrc`.
+ * Sose dob; ha egyik sincs, ures stringet ad.
+ */
+export function resolveNpmToken(explicit: string | undefined, registry: string): string {
+  const fromExplicit: string = (explicit ?? '').trim();
+  if (fromExplicit) { return fromExplicit; }
+  const fromEnv: string = (process.env.NPM_TOKEN ?? '').trim();
+  if (fromEnv) { return fromEnv; }
+  try {
+    const npmrcPath: string = path.join(os.homedir(), '.npmrc');
+    if (fs.existsSync(npmrcPath)) {
+      return extractTokenFromNpmrc(fs.readFileSync(npmrcPath, 'utf-8'), registry) ?? '';
+    }
+  } catch {
+    // A fajl-olvasas hibaja NEM buktathatja az ellenorzest.
+  }
+  return '';
+}
+
+const DEFAULT_REGISTRY: string = 'https://registry.npmjs.org';
+const DEFAULT_TIMEOUT_MS: number = 10000;
+
+/** Egy statusz-lekeres, timeout-tal. `null`, ha el sem jutottunk a szerverig. */
+async function fetchStatus(url: string, token: string | null, timeoutMs: number): Promise<number | null> {
+  const controller: AbortController = new AbortController();
+  const timer: NodeJS.Timeout = setTimeout((): void => { controller.abort(); }, timeoutMs);
+  try {
+    const response: Response = await fetch(url, {
+      headers: token ? { authorization: `Bearer ${token}` } : {},
+      signal: controller.signal,
+    });
+    return response.status;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * A tenyleges ellenorzes. SOSE dob — a hibat allapotkent adja vissza (a token-ellenorzes nem
+ * buktathat meg semmit, amibe beepitjuk).
+ */
+export async function checkNpmToken(
+  options: DyNTS_NpmTokenCheck_Options = {},
+): Promise<DyNTS_NpmTokenCheck_Result> {
+  const registry: string = (options.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, '');
+  const token: string = resolveNpmToken(options.token, registry);
+  const timeoutMs: number = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  const shape: DyNTS_NpmTokenShape = classifyNpmTokenShape(token);
+  if (shape !== DyNTS_NpmTokenShape.plausible) {
+    const localState: DyNTS_NpmTokenState = shape === DyNTS_NpmTokenShape.missing
+      ? DyNTS_NpmTokenState.missing
+      : DyNTS_NpmTokenState.malformed;
+    return {
+      state: localState,
+      username: null,
+      detail: describeNpmTokenState(localState),
+      probe: { whoamiStatus: null },
+    };
+  }
+
+  const whoamiStatus: number | null = await fetchStatus(`${registry}/-/whoami`, token, timeoutMs);
+
+  let username: string | null = null;
+  if (whoamiStatus === 200) {
+    try {
+      const response: Response = await fetch(`${registry}/-/whoami`, {
+        headers: { authorization: `Bearer ${token}` },
+      });
+      const body: { username?: string } = await response.json() as { username?: string };
+      username = typeof body.username === 'string' ? body.username : null;
+    } catch {
+      username = null;
+    }
+  }
+
+  let scopedPackageStatus: number | undefined;
+  if (options.scopedPackage && whoamiStatus === 200) {
+    const encoded: string = options.scopedPackage.replace('/', '%2f');
+    const status: number | null = await fetchStatus(`${registry}/${encoded}`, token, timeoutMs);
+    scopedPackageStatus = status === null ? undefined : status;
+  }
+
+  const probe: DyNTS_NpmTokenProbe_Input = {
+    whoamiStatus: whoamiStatus,
+    scopedPackageStatus: scopedPackageStatus,
+    publishErrorCode: options.publishErrorCode,
+  };
+  const state: DyNTS_NpmTokenState = classifyNpmTokenProbe(probe);
+
+  DyFM_Log.info(`[npm-token-check] allapot=${state}${username ? ` user=${username}` : ''} (a token erteke NEM naplozodik)`);
+
+  return { state: state, username: username, detail: describeNpmTokenState(state), probe: probe };
+}