@neetru/sdk 3.7.0 → 3.8.0

package/dist/index.d.cts

@@ -1,7 +1,8 @@
 export { createNeetruClient, getServerNeetruClient } from './auth.cjs';
 export { NeetruAuthRequiredError, NeetruError, NeetruErrorCode } from './errors.cjs';
-export { A as AiChatChoice, a as AiChatMessage, b as AiChatOptions, c as AiChatResult, d as AiChatUsage, e as AiContentPart, f as AiImageUrlPart, g as AiNamespace, h as AiResponseFormat, i as AiStreamHandle, j as AiStreamMeta, k as AiTextPart, l as AuthNamespace, m as AuthStateListener, C as CatalogListOptions, n as CatalogListResponse, p as CheckoutIntentInfo, q as CheckoutIntentStatus, r as CheckoutNamespace, s as CheckoutStartInput, t as CheckoutStartResult, u as CheckoutTenantType, v as CompleteSignInResult, y as CreateTicketInput, D as DEFAULT_BASE_URL, z as DbBatchOp, B as DbChangeType, E as DbCollectionRef, F as DbDoc, G as DbDocRef, H as DbGetResult, I as DbListResult, J as DbNamespace, K as DbQuery, L as DbSqlLease, M as DbWhereFilter, O as EntitlementCheck, P as FieldSentinel, Q as IncrementSentinel, R as ListNotificationsOptions, S as MockCheckout, T as MockNotifications, U as MockWebhooks, V as NEETRU_SENTINEL_KEY, W as NeetruClient, X as NeetruClientConfig, Y as NeetruDb, _ as NeetruDbEngine, $ as NeetruDbError, a0 as NeetruDbErrorCode, a1 as NeetruDbOptions, a2 as NeetruDbTransport, a3 as NeetruEnv, a4 as NeetruSqlClient, a5 as NeetruUser, a6 as NotificationScopeOptions, a7 as NotificationsNamespace, a8 as Product, a9 as ProductNotification, aa as ProductNotificationSeverity, ab as ProductPlan, ac as ProductStatus, ae as RedirectCallbackResult, af as RegisterWebhookInput, ag as ResolvedConfig, ah as SendNotificationInput, ai as ServerTimestampSentinel, aj as SignInOptions, al as SupportNamespace, am as SupportSeverity, an as SupportStatus, ao as SupportTicket, ar as TelemetryEventAck, as as TelemetryEventInput, aw as UsageEventInput, ax as UsageNamespace, ay as UsageQuota, az as VerifyTokenOptions, aA as VerifyWebhookRequestOptions, aB as VerifyWebhookRequestResult, aC as WebhookEndpoint, aD as WebhookEvent, aE as WebhookScopeOptions, aF as WebhookTestResult, aG as WebhooksNamespace, aH as WithFieldSentinels, aJ as createAiNamespace, aK as createCheckoutNamespace, aL as createNeetruDb, aM as createNotificationsNamespace, aO as createWebhooksNamespace, aQ as increment, aR as isFieldSentinel, aS as isIncrementSentinel, aT as isServerTimestampSentinel, aU as serverTimestamp, aV as verifyWebhookRequest, aW as verifyWebhookSignature } from './types-Bx4kTLmk.cjs';
+export { A as AiChatChoice, a as AiChatMessage, b as AiChatOptions, c as AiChatResult, d as AiChatUsage, e as AiContentPart, f as AiImageUrlPart, g as AiNamespace, h as AiResponseFormat, i as AiStreamHandle, j as AiStreamMeta, k as AiTextPart, l as AuthNamespace, m as AuthStateListener, C as CatalogListOptions, n as CatalogListResponse, p as CheckoutIntentInfo, q as CheckoutIntentStatus, r as CheckoutNamespace, s as CheckoutStartInput, t as CheckoutStartResult, u as CheckoutTenantType, v as CompleteSignInResult, y as CreateTicketInput, D as DEFAULT_BASE_URL, z as DbBatchOp, B as DbChangeType, E as DbCollectionRef, F as DbDoc, G as DbDocRef, H as DbGetResult, I as DbListResult, J as DbNamespace, K as DbQuery, L as DbSqlLease, M as DbWhereFilter, O as EndUserTokenProvider, P as EntitlementCheck, Q as FieldSentinel, R as IncrementSentinel, S as ListNotificationsOptions, T as MockCheckout, U as MockNotifications, V as MockWebhooks, W as NEETRU_SENTINEL_KEY, X as NeetruClient, Y as NeetruClientConfig, Z as NeetruDb, $ as NeetruDbEngine, a0 as NeetruDbError, a1 as NeetruDbErrorCode, a2 as NeetruDbOptions, a3 as NeetruDbTransport, a4 as NeetruEnv, a5 as NeetruSqlClient, a6 as NeetruUser, a7 as NotificationScopeOptions, a8 as NotificationsNamespace, a9 as Product, aa as ProductNotification, ab as ProductNotificationSeverity, ac as ProductPlan, ad as ProductStatus, af as RedirectCallbackResult, ag as RegisterWebhookInput, ah as ResolvedConfig, ai as SendNotificationInput, aj as ServerTimestampSentinel, ak as SignInOptions, am as SupportNamespace, an as SupportSeverity, ao as SupportStatus, ap as SupportTicket, as as TelemetryEventAck, at as TelemetryEventInput, ax as UsageEventInput, ay as UsageNamespace, az as UsageQuota, aA as VerifyTokenOptions, aB as VerifyWebhookRequestOptions, aC as VerifyWebhookRequestResult, aD as WebhookEndpoint, aE as WebhookEvent, aF as WebhookScopeOptions, aG as WebhookTestResult, aH as WebhooksNamespace, aI as WithFieldSentinels, aK as createAiNamespace, aL as createCheckoutNamespace, aM as createNeetruDb, aN as createNotificationsNamespace, aP as createWebhooksNamespace, aR as increment, aS as isFieldSentinel, aT as isIncrementSentinel, aU as isServerTimestampSentinel, aV as serverTimestamp, aW as verifyWebhookRequest, aX as verifyWebhookSignature } from './types-D-9bjlM0.cjs';
 export { DEV_FIXTURE_USER, MockAi, MockAuth, MockAuthOptions, MockDb, MockEntitlements, MockSupport, MockUsage } from './mocks.cjs';
+import { JWTPayload } from 'jose';
 import 'drizzle-orm/node-postgres';
 
 /**
@@ -38,6 +39,179 @@ import 'drizzle-orm/node-postgres';
  */
 declare function checkCoreVersionCompat(coreVersion: string): void;
 
+/**
+ * 3.8.0 — `verifyAccessToken`: validação SERVER-SIDE do access_token OIDC do
+ * usuário final, para a API do PRODUTO aceitar `Authorization: Bearer
+ * <access_token>` (app React Native / SPA) além do cookie de sessão.
+ *
+ * ## Fluxo canônico (decisão do dono, 2026-10-03)
+ *
+ *   app/site ──Bearer access_token──▶ API do produto ──SDK + nrt_ (servidor)──▶ Core
+ *
+ * O app nunca carrega a chave `nrt_`. Ele faz login no auth.neetru.com (PKCE,
+ * client OIDC público do app) e manda o access_token pra API do produto, que
+ * valida aqui — sem ir ao Core por request.
+ *
+ * ## Formato real do token (conferido no Core, `src/lib/oidc/tokens.ts`)
+ *
+ *   header: `{ alg: 'RS256', kid, typ: 'JWT' }`
+ *   claims: `iss` = `https://auth.neetru.com` · `sub` = uid do usuário (ou
+ *           `client:<client_id>` em client_credentials) · `aud` = `client_id`
+ *           (string) · `client_id` · `scope` (string separada por espaço) ·
+ *           `iat` · `exp` (15 min) · `jti`.
+ *   JWKS:   `https://auth.neetru.com/api/v1/oauth/.well-known/jwks`.
+ *
+ * O id_token usa a MESMA chave, `iss` e `aud` — o que o distingue é NÃO ter
+ * `jti`/`scope`/`client_id`. Por isso exigimos os três: um id_token (que vai
+ * para terceiros como prova de login) não serve de credencial de API.
+ *
+ * ## Revogação
+ *
+ * A validação é local (assinatura + claims), sem consulta ao Core. Um access
+ * token revogado continua aceito até expirar — no máximo 15 min (TTL do Core).
+ * Para encerrar a sessão de verdade, o app revoga o refresh_token no logout
+ * (o `@neetru/sdk/mobile` faz isso no `signOut`). O `/introspect` do Core é só
+ * para clients confidenciais do mesmo `client_id`, então não serve a uma API
+ * que aceita tokens de vários clients (web + iOS + Android).
+ */
+
+/** Issuer canônico do Core em produção. */
+declare const NEETRU_OIDC_ISSUER = "https://auth.neetru.com";
+interface VerifyAccessTokenOptions {
+    /**
+     * `client_id` OIDC aceitos como `aud` — tipicamente o client web + o do app
+     * iOS + o do app Android DO MESMO PRODUTO. Obrigatório e não-vazio: sem isso
+     * um token emitido para o client de OUTRO produto passaria.
+     */
+    audience: string | readonly string[];
+    /** Escopos que o token TEM que ter (todos). Ex.: `['openid']`. Default: nenhum. */
+    requiredScopes?: readonly string[];
+    /** Issuer esperado. Default `https://auth.neetru.com`. Só mude para staging/emulador. */
+    issuer?: string;
+    /** URL do JWKS. Default `<issuer>/api/v1/oauth/.well-known/jwks`. */
+    jwksUrl?: string;
+    /** TTL da instância de JWKS cacheada. Default 1h. */
+    jwksCacheTtlMs?: number;
+    /** Tolerância de relógio para `exp`/`iat`/`nbf`, em segundos. Default 5, máx 60. */
+    clockToleranceSec?: number;
+    /**
+     * Aceitar token de máquina (`client_credentials`, `sub` = `client:<id>`).
+     * Default `false` — a API do produto quer um USUÁRIO.
+     */
+    allowClientCredentials?: boolean;
+}
+interface VerifiedAccessToken {
+    /** uid do usuário final (ou `client:<id>` se `allowClientCredentials`). */
+    sub: string;
+    /** `client_id` que pediu o token (web, iOS ou Android). */
+    clientId: string;
+    /** `aud` do token (= `clientId` no Core). */
+    audience: string;
+    /** Escopos concedidos. */
+    scopes: string[];
+    /** Id único do token (útil pra log/auditoria; NÃO é segredo). */
+    jti: string;
+    /** Emitido em (epoch s). */
+    issuedAt: number;
+    /** Expira em (epoch s). */
+    expiresAt: number;
+    /** `true` se é token de máquina (`client_credentials`). */
+    isClientCredentials: boolean;
+    /** Claims crus verificados. */
+    claims: JWTPayload;
+}
+/**
+ * Valida um access_token OIDC emitido pelo auth.neetru.com.
+ *
+ * Checa: assinatura RS256 contra o JWKS (cacheado) · `iss` · `exp` (com
+ * tolerância curta) · `aud ∈ audience` · formato de access token (`jti`,
+ * `scope`, `client_id` === `aud`) · usuário (não máquina) · `requiredScopes`.
+ *
+ * @throws {NeetruError} `invalid_config` (sem audience) · `token_expired` ·
+ *   `token_invalid_signature` · `token_invalid_audience` · `token_invalid_issuer` ·
+ *   `token_invalid` (não é access token / malformado / máquina) ·
+ *   `insufficient_scope` (status 403).
+ */
+declare function verifyAccessToken(token: string, options: VerifyAccessTokenOptions): Promise<VerifiedAccessToken>;
+/** Qualquer coisa com headers: `Request` (fetch/Next), `Headers`, ou objeto Node (`req.headers`). */
+type HeadersSource = Headers | {
+    headers: Headers | Record<string, string | string[] | undefined>;
+} | Record<string, string | string[] | undefined>;
+/**
+ * Extrai o token de `Authorization: Bearer <token>`. `null` se ausente ou se o
+ * esquema não for Bearer.
+ */
+declare function readBearerToken(source: HeadersSource): string | null;
+/** Lê um cookie pelo nome do header `Cookie`. */
+declare function readCookie(source: HeadersSource, name: string): string | null;
+interface AuthenticateProductRequestOptions<TSession> extends VerifyAccessTokenOptions {
+    /**
+     * Sessão por cookie do site (o caminho que o produto JÁ tem). Se a request
+     * não trouxer `Authorization: Bearer`, o helper lê o cookie `name` e chama
+     * `verify(valor)` — a validação do cookie continua sendo do produto.
+     */
+    cookie?: {
+        name: string;
+        verify: (value: string) => Promise<TSession | null> | TSession | null;
+    };
+}
+type ProductRequestAuth<TSession> = {
+    kind: 'access_token';
+    token: VerifiedAccessToken;
+} | {
+    kind: 'cookie';
+    session: TSession;
+};
+/**
+ * Autentica uma request na API do produto aceitando `Authorization: Bearer
+ * <access_token>` (app/SPA) **ou** o cookie de sessão do site.
+ *
+ * - Bearer presente → valida com `verifyAccessToken`. Inválido → LANÇA (não cai
+ *   pro cookie: credencial ruim explícita nunca é "rebaixada" em silêncio).
+ * - Sem Bearer e com `cookie` configurado → `cookie.verify(valor)`.
+ * - Nada válido → `null` (o produto responde 401).
+ *
+ * @example
+ * ```ts
+ * // app/api/v1/vendas/route.ts (Next.js, servidor)
+ * import { authenticateProductRequest, accessTokenErrorToHttp } from '@neetru/sdk';
+ * export async function GET(req: Request) {
+ *   try {
+ *     const auth = await authenticateProductRequest(req, {
+ *       audience: [process.env.NEETRU_OIDC_CLIENT_ID_WEB!, process.env.NEETRU_OIDC_CLIENT_ID_IOS!,
+ *                  process.env.NEETRU_OIDC_CLIENT_ID_ANDROID!],
+ *       requiredScopes: ['openid'],
+ *       cookie: { name: 'session', verify: verifySessionCookie },
+ *     });
+ *     if (!auth) return Response.json({ error: 'unauthorized' }, { status: 401 });
+ *     // ... usa o SDK com a chave (servidor) em nome de auth.token.sub
+ *   } catch (err) {
+ *     const r = accessTokenErrorToHttp(err);
+ *     return Response.json(r.body, { status: r.status, headers: r.headers });
+ *   }
+ * }
+ * ```
+ */
+declare function authenticateProductRequest<TSession = unknown>(request: HeadersSource, options: AuthenticateProductRequestOptions<TSession>): Promise<ProductRequestAuth<TSession> | null>;
+/**
+ * Converte um erro de `verifyAccessToken`/`authenticateProductRequest` na
+ * resposta HTTP padrão (RFC 6750 §3): 401 `invalid_token` ou 403
+ * `insufficient_scope`, com `WWW-Authenticate`. Erros que não são de token
+ * viram 500 genérico (sem vazar detalhe).
+ */
+declare function accessTokenErrorToHttp(err: unknown): {
+    status: number;
+    headers: Record<string, string>;
+    body: {
+        error: string;
+        error_description: string;
+    };
+};
+
+type NonServerRuntime = 'browser' | 'react-native';
+/** Detecta se o código está rodando fora de um servidor. `null` = servidor. */
+declare function detectNonServerRuntime(): NonServerRuntime | null;
+
 /**
  * @neetru/sdk — biblioteca runtime para consumir o ecossistema Neetru.
  *
@@ -72,6 +246,6 @@ declare function checkCoreVersionCompat(coreVersion: string): void;
  */
 
 /** Versão do SDK — exportada explicitamente pra detecção em runtime. */
-declare const VERSION: "3.7.0";
+declare const VERSION: "3.8.0";
 
-export { VERSION, checkCoreVersionCompat };
+export { type AuthenticateProductRequestOptions, type HeadersSource, NEETRU_OIDC_ISSUER, type NonServerRuntime, type ProductRequestAuth, VERSION, type VerifiedAccessToken, type VerifyAccessTokenOptions, accessTokenErrorToHttp, authenticateProductRequest, checkCoreVersionCompat, detectNonServerRuntime, readBearerToken, readCookie, verifyAccessToken };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export { createNeetruClient, getServerNeetruClient } from './auth.js';
 export { NeetruAuthRequiredError, NeetruError, NeetruErrorCode } from './errors.js';
-export { A as AiChatChoice, a as AiChatMessage, b as AiChatOptions, c as AiChatResult, d as AiChatUsage, e as AiContentPart, f as AiImageUrlPart, g as AiNamespace, h as AiResponseFormat, i as AiStreamHandle, j as AiStreamMeta, k as AiTextPart, l as AuthNamespace, m as AuthStateListener, C as CatalogListOptions, n as CatalogListResponse, p as CheckoutIntentInfo, q as CheckoutIntentStatus, r as CheckoutNamespace, s as CheckoutStartInput, t as CheckoutStartResult, u as CheckoutTenantType, v as CompleteSignInResult, y as CreateTicketInput, D as DEFAULT_BASE_URL, z as DbBatchOp, B as DbChangeType, E as DbCollectionRef, F as DbDoc, G as DbDocRef, H as DbGetResult, I as DbListResult, J as DbNamespace, K as DbQuery, L as DbSqlLease, M as DbWhereFilter, O as EntitlementCheck, P as FieldSentinel, Q as IncrementSentinel, R as ListNotificationsOptions, S as MockCheckout, T as MockNotifications, U as MockWebhooks, V as NEETRU_SENTINEL_KEY, W as NeetruClient, X as NeetruClientConfig, Y as NeetruDb, _ as NeetruDbEngine, $ as NeetruDbError, a0 as NeetruDbErrorCode, a1 as NeetruDbOptions, a2 as NeetruDbTransport, a3 as NeetruEnv, a4 as NeetruSqlClient, a5 as NeetruUser, a6 as NotificationScopeOptions, a7 as NotificationsNamespace, a8 as Product, a9 as ProductNotification, aa as ProductNotificationSeverity, ab as ProductPlan, ac as ProductStatus, ae as RedirectCallbackResult, af as RegisterWebhookInput, ag as ResolvedConfig, ah as SendNotificationInput, ai as ServerTimestampSentinel, aj as SignInOptions, al as SupportNamespace, am as SupportSeverity, an as SupportStatus, ao as SupportTicket, ar as TelemetryEventAck, as as TelemetryEventInput, aw as UsageEventInput, ax as UsageNamespace, ay as UsageQuota, az as VerifyTokenOptions, aA as VerifyWebhookRequestOptions, aB as VerifyWebhookRequestResult, aC as WebhookEndpoint, aD as WebhookEvent, aE as WebhookScopeOptions, aF as WebhookTestResult, aG as WebhooksNamespace, aH as WithFieldSentinels, aJ as createAiNamespace, aK as createCheckoutNamespace, aL as createNeetruDb, aM as createNotificationsNamespace, aO as createWebhooksNamespace, aQ as increment, aR as isFieldSentinel, aS as isIncrementSentinel, aT as isServerTimestampSentinel, aU as serverTimestamp, aV as verifyWebhookRequest, aW as verifyWebhookSignature } from './types-Dx0IrOSF.js';
+export { A as AiChatChoice, a as AiChatMessage, b as AiChatOptions, c as AiChatResult, d as AiChatUsage, e as AiContentPart, f as AiImageUrlPart, g as AiNamespace, h as AiResponseFormat, i as AiStreamHandle, j as AiStreamMeta, k as AiTextPart, l as AuthNamespace, m as AuthStateListener, C as CatalogListOptions, n as CatalogListResponse, p as CheckoutIntentInfo, q as CheckoutIntentStatus, r as CheckoutNamespace, s as CheckoutStartInput, t as CheckoutStartResult, u as CheckoutTenantType, v as CompleteSignInResult, y as CreateTicketInput, D as DEFAULT_BASE_URL, z as DbBatchOp, B as DbChangeType, E as DbCollectionRef, F as DbDoc, G as DbDocRef, H as DbGetResult, I as DbListResult, J as DbNamespace, K as DbQuery, L as DbSqlLease, M as DbWhereFilter, O as EndUserTokenProvider, P as EntitlementCheck, Q as FieldSentinel, R as IncrementSentinel, S as ListNotificationsOptions, T as MockCheckout, U as MockNotifications, V as MockWebhooks, W as NEETRU_SENTINEL_KEY, X as NeetruClient, Y as NeetruClientConfig, Z as NeetruDb, $ as NeetruDbEngine, a0 as NeetruDbError, a1 as NeetruDbErrorCode, a2 as NeetruDbOptions, a3 as NeetruDbTransport, a4 as NeetruEnv, a5 as NeetruSqlClient, a6 as NeetruUser, a7 as NotificationScopeOptions, a8 as NotificationsNamespace, a9 as Product, aa as ProductNotification, ab as ProductNotificationSeverity, ac as ProductPlan, ad as ProductStatus, af as RedirectCallbackResult, ag as RegisterWebhookInput, ah as ResolvedConfig, ai as SendNotificationInput, aj as ServerTimestampSentinel, ak as SignInOptions, am as SupportNamespace, an as SupportSeverity, ao as SupportStatus, ap as SupportTicket, as as TelemetryEventAck, at as TelemetryEventInput, ax as UsageEventInput, ay as UsageNamespace, az as UsageQuota, aA as VerifyTokenOptions, aB as VerifyWebhookRequestOptions, aC as VerifyWebhookRequestResult, aD as WebhookEndpoint, aE as WebhookEvent, aF as WebhookScopeOptions, aG as WebhookTestResult, aH as WebhooksNamespace, aI as WithFieldSentinels, aK as createAiNamespace, aL as createCheckoutNamespace, aM as createNeetruDb, aN as createNotificationsNamespace, aP as createWebhooksNamespace, aR as increment, aS as isFieldSentinel, aT as isIncrementSentinel, aU as isServerTimestampSentinel, aV as serverTimestamp, aW as verifyWebhookRequest, aX as verifyWebhookSignature } from './types-bVztFQTI.js';
 export { DEV_FIXTURE_USER, MockAi, MockAuth, MockAuthOptions, MockDb, MockEntitlements, MockSupport, MockUsage } from './mocks.js';
+import { JWTPayload } from 'jose';
 import 'drizzle-orm/node-postgres';
 
 /**
@@ -38,6 +39,179 @@ import 'drizzle-orm/node-postgres';
  */
 declare function checkCoreVersionCompat(coreVersion: string): void;
 
+/**
+ * 3.8.0 — `verifyAccessToken`: validação SERVER-SIDE do access_token OIDC do
+ * usuário final, para a API do PRODUTO aceitar `Authorization: Bearer
+ * <access_token>` (app React Native / SPA) além do cookie de sessão.
+ *
+ * ## Fluxo canônico (decisão do dono, 2026-10-03)
+ *
+ *   app/site ──Bearer access_token──▶ API do produto ──SDK + nrt_ (servidor)──▶ Core
+ *
+ * O app nunca carrega a chave `nrt_`. Ele faz login no auth.neetru.com (PKCE,
+ * client OIDC público do app) e manda o access_token pra API do produto, que
+ * valida aqui — sem ir ao Core por request.
+ *
+ * ## Formato real do token (conferido no Core, `src/lib/oidc/tokens.ts`)
+ *
+ *   header: `{ alg: 'RS256', kid, typ: 'JWT' }`
+ *   claims: `iss` = `https://auth.neetru.com` · `sub` = uid do usuário (ou
+ *           `client:<client_id>` em client_credentials) · `aud` = `client_id`
+ *           (string) · `client_id` · `scope` (string separada por espaço) ·
+ *           `iat` · `exp` (15 min) · `jti`.
+ *   JWKS:   `https://auth.neetru.com/api/v1/oauth/.well-known/jwks`.
+ *
+ * O id_token usa a MESMA chave, `iss` e `aud` — o que o distingue é NÃO ter
+ * `jti`/`scope`/`client_id`. Por isso exigimos os três: um id_token (que vai
+ * para terceiros como prova de login) não serve de credencial de API.
+ *
+ * ## Revogação
+ *
+ * A validação é local (assinatura + claims), sem consulta ao Core. Um access
+ * token revogado continua aceito até expirar — no máximo 15 min (TTL do Core).
+ * Para encerrar a sessão de verdade, o app revoga o refresh_token no logout
+ * (o `@neetru/sdk/mobile` faz isso no `signOut`). O `/introspect` do Core é só
+ * para clients confidenciais do mesmo `client_id`, então não serve a uma API
+ * que aceita tokens de vários clients (web + iOS + Android).
+ */
+
+/** Issuer canônico do Core em produção. */
+declare const NEETRU_OIDC_ISSUER = "https://auth.neetru.com";
+interface VerifyAccessTokenOptions {
+    /**
+     * `client_id` OIDC aceitos como `aud` — tipicamente o client web + o do app
+     * iOS + o do app Android DO MESMO PRODUTO. Obrigatório e não-vazio: sem isso
+     * um token emitido para o client de OUTRO produto passaria.
+     */
+    audience: string | readonly string[];
+    /** Escopos que o token TEM que ter (todos). Ex.: `['openid']`. Default: nenhum. */
+    requiredScopes?: readonly string[];
+    /** Issuer esperado. Default `https://auth.neetru.com`. Só mude para staging/emulador. */
+    issuer?: string;
+    /** URL do JWKS. Default `<issuer>/api/v1/oauth/.well-known/jwks`. */
+    jwksUrl?: string;
+    /** TTL da instância de JWKS cacheada. Default 1h. */
+    jwksCacheTtlMs?: number;
+    /** Tolerância de relógio para `exp`/`iat`/`nbf`, em segundos. Default 5, máx 60. */
+    clockToleranceSec?: number;
+    /**
+     * Aceitar token de máquina (`client_credentials`, `sub` = `client:<id>`).
+     * Default `false` — a API do produto quer um USUÁRIO.
+     */
+    allowClientCredentials?: boolean;
+}
+interface VerifiedAccessToken {
+    /** uid do usuário final (ou `client:<id>` se `allowClientCredentials`). */
+    sub: string;
+    /** `client_id` que pediu o token (web, iOS ou Android). */
+    clientId: string;
+    /** `aud` do token (= `clientId` no Core). */
+    audience: string;
+    /** Escopos concedidos. */
+    scopes: string[];
+    /** Id único do token (útil pra log/auditoria; NÃO é segredo). */
+    jti: string;
+    /** Emitido em (epoch s). */
+    issuedAt: number;
+    /** Expira em (epoch s). */
+    expiresAt: number;
+    /** `true` se é token de máquina (`client_credentials`). */
+    isClientCredentials: boolean;
+    /** Claims crus verificados. */
+    claims: JWTPayload;
+}
+/**
+ * Valida um access_token OIDC emitido pelo auth.neetru.com.
+ *
+ * Checa: assinatura RS256 contra o JWKS (cacheado) · `iss` · `exp` (com
+ * tolerância curta) · `aud ∈ audience` · formato de access token (`jti`,
+ * `scope`, `client_id` === `aud`) · usuário (não máquina) · `requiredScopes`.
+ *
+ * @throws {NeetruError} `invalid_config` (sem audience) · `token_expired` ·
+ *   `token_invalid_signature` · `token_invalid_audience` · `token_invalid_issuer` ·
+ *   `token_invalid` (não é access token / malformado / máquina) ·
+ *   `insufficient_scope` (status 403).
+ */
+declare function verifyAccessToken(token: string, options: VerifyAccessTokenOptions): Promise<VerifiedAccessToken>;
+/** Qualquer coisa com headers: `Request` (fetch/Next), `Headers`, ou objeto Node (`req.headers`). */
+type HeadersSource = Headers | {
+    headers: Headers | Record<string, string | string[] | undefined>;
+} | Record<string, string | string[] | undefined>;
+/**
+ * Extrai o token de `Authorization: Bearer <token>`. `null` se ausente ou se o
+ * esquema não for Bearer.
+ */
+declare function readBearerToken(source: HeadersSource): string | null;
+/** Lê um cookie pelo nome do header `Cookie`. */
+declare function readCookie(source: HeadersSource, name: string): string | null;
+interface AuthenticateProductRequestOptions<TSession> extends VerifyAccessTokenOptions {
+    /**
+     * Sessão por cookie do site (o caminho que o produto JÁ tem). Se a request
+     * não trouxer `Authorization: Bearer`, o helper lê o cookie `name` e chama
+     * `verify(valor)` — a validação do cookie continua sendo do produto.
+     */
+    cookie?: {
+        name: string;
+        verify: (value: string) => Promise<TSession | null> | TSession | null;
+    };
+}
+type ProductRequestAuth<TSession> = {
+    kind: 'access_token';
+    token: VerifiedAccessToken;
+} | {
+    kind: 'cookie';
+    session: TSession;
+};
+/**
+ * Autentica uma request na API do produto aceitando `Authorization: Bearer
+ * <access_token>` (app/SPA) **ou** o cookie de sessão do site.
+ *
+ * - Bearer presente → valida com `verifyAccessToken`. Inválido → LANÇA (não cai
+ *   pro cookie: credencial ruim explícita nunca é "rebaixada" em silêncio).
+ * - Sem Bearer e com `cookie` configurado → `cookie.verify(valor)`.
+ * - Nada válido → `null` (o produto responde 401).
+ *
+ * @example
+ * ```ts
+ * // app/api/v1/vendas/route.ts (Next.js, servidor)
+ * import { authenticateProductRequest, accessTokenErrorToHttp } from '@neetru/sdk';
+ * export async function GET(req: Request) {
+ *   try {
+ *     const auth = await authenticateProductRequest(req, {
+ *       audience: [process.env.NEETRU_OIDC_CLIENT_ID_WEB!, process.env.NEETRU_OIDC_CLIENT_ID_IOS!,
+ *                  process.env.NEETRU_OIDC_CLIENT_ID_ANDROID!],
+ *       requiredScopes: ['openid'],
+ *       cookie: { name: 'session', verify: verifySessionCookie },
+ *     });
+ *     if (!auth) return Response.json({ error: 'unauthorized' }, { status: 401 });
+ *     // ... usa o SDK com a chave (servidor) em nome de auth.token.sub
+ *   } catch (err) {
+ *     const r = accessTokenErrorToHttp(err);
+ *     return Response.json(r.body, { status: r.status, headers: r.headers });
+ *   }
+ * }
+ * ```
+ */
+declare function authenticateProductRequest<TSession = unknown>(request: HeadersSource, options: AuthenticateProductRequestOptions<TSession>): Promise<ProductRequestAuth<TSession> | null>;
+/**
+ * Converte um erro de `verifyAccessToken`/`authenticateProductRequest` na
+ * resposta HTTP padrão (RFC 6750 §3): 401 `invalid_token` ou 403
+ * `insufficient_scope`, com `WWW-Authenticate`. Erros que não são de token
+ * viram 500 genérico (sem vazar detalhe).
+ */
+declare function accessTokenErrorToHttp(err: unknown): {
+    status: number;
+    headers: Record<string, string>;
+    body: {
+        error: string;
+        error_description: string;
+    };
+};
+
+type NonServerRuntime = 'browser' | 'react-native';
+/** Detecta se o código está rodando fora de um servidor. `null` = servidor. */
+declare function detectNonServerRuntime(): NonServerRuntime | null;
+
 /**
  * @neetru/sdk — biblioteca runtime para consumir o ecossistema Neetru.
  *
@@ -72,6 +246,6 @@ declare function checkCoreVersionCompat(coreVersion: string): void;
  */
 
 /** Versão do SDK — exportada explicitamente pra detecção em runtime. */
-declare const VERSION: "3.7.0";
+declare const VERSION: "3.8.0";
 
-export { VERSION, checkCoreVersionCompat };
+export { type AuthenticateProductRequestOptions, type HeadersSource, NEETRU_OIDC_ISSUER, type NonServerRuntime, type ProductRequestAuth, VERSION, type VerifiedAccessToken, type VerifyAccessTokenOptions, accessTokenErrorToHttp, authenticateProductRequest, checkCoreVersionCompat, detectNonServerRuntime, readBearerToken, readCookie, verifyAccessToken };