@stackonward/onex-identity-nuxt

Nuxt BFF integration for OneX opaque identity sessions. The module exposes a finite same-origin /api/onex surface, keeps credentials inside Nitro, stores session state in Redis, and returns only browser-safe session projections.

Use it when a Nuxt application authenticates against one OneX Platform gateway and needs server-owned refresh, CSRF, trusted-proxy, admission, and service-token boundaries.

Install

pnpm add @stackonward/onex-identity-nuxt @stackonward/identity-browser @stackonward/identity-session @stackonward/server-boundary

Nuxt, Nitro, and H3 are peer dependencies. See Compatibility for supported ranges.

Prerequisites

Before enabling the module, the product must own:

• one OneX product code and browser client ID;
• an HTTPS OneX Platform base URL and exact application origin;
• Redis reachable by the Nitro runtime;
• a finite trusted-proxy CIDR list;
• a session AES-256-GCM keyring reference;
• an admission HMAC secret reference;
• an IAM bootstrap credential reference bound to one absolute service-token audience;
• the expected guest-capability policy version, digest, limits, and TTLs.

Secret references accept only env://NAME and absolute file:///path values. They are resolved by the server runtime and never exposed through public runtime config.

Setup

import { identityPolicy } from "./config/identity-policy";

export default defineNuxtConfig({
  modules: ["@stackonward/onex-identity-nuxt"],
  identityNuxt: {
    platform: { baseUrl: "https://platform.internal.example/" },
    identity: { productCode: "alpha", clientId: "alpha-web" },
    allowedOrigin: "https://alpha.example",
    trustedProxyCidrs: ["10.0.0.0/8"],
    redis: {
      url: "rediss://redis.internal.example:6379",
      keyPrefix: "alpha:identity",
    },
    session: {
      activeKeyId: "primary",
      keyringRef: "env://ONEX_IDENTITY_SESSION_KEYRING",
      absoluteTtlSeconds: 604800,
      idleTtlSeconds: 86400,
      preAuthenticatedTtlSeconds: identityPolicy.bootstrapPendingTtlSeconds,
      refreshBeforeSeconds: 300,
      transitionLockTtlSeconds: 30,
    },
    admission: {
      prefixHmacSecretRef: "env://ONEX_IDENTITY_ADMISSION_HMAC",
    },
    serviceAuthorization: {
      audience: "https://platform.internal.example/identity",
      bootstrapCredentialRef: "file:///run/secrets/onex-identity-bootstrap",
      serviceAccountCode: "svc_alpha_identity",
    },
    policy: identityPolicy,
  },
});

identityPolicy is a product-owned IdentityNuxtExpectedPolicy generated or copied from the deployed OneX guest-capability policy. Its digest and TTLs must match the gateway contract; the module rejects inconsistent configuration at startup.

Set localDevelopment: true only for an explicit local HTTP origin and platform URL. Production configuration requires HTTPS. The default request timeout is 10 seconds; accepted values are 500–30,000 milliseconds.

Browser API

useIdentitySession() returns the shared IdentityNuxtBrowserRuntime:

<script setup lang="ts">
import { computed } from "vue";

const identity = useIdentitySession();
const principal = computed(() => identity.session.value?.principal ?? null);

async function refreshSession() {
  await identity.load({ force: true });
}
</script>

The runtime exposes:

• session: readonly browser-safe session projection;
• pending: readonly state for load();
• error: the latest IdentityBrowserError produced by load();
• load({ force? }): reads the current same-origin session;
• client: the complete IdentityBrowserClient transaction API for login, registration, MFA, WebAuthn, OAuth, guest activation, recovery, profile, logout, and deletion.

Browser transactions use exact JSON, same-origin credentials, manual redirects, and the public /api/onex base path. Access and refresh tokens never enter the browser response.

Server API

Use the explicit server entry from product-owned Nitro routes:

import { requireIdentitySession } from "@stackonward/onex-identity-nuxt/server";

export default defineEventHandler(async (event) => {
  const session = await requireIdentitySession(event);
  return {
    principalKind: session.principalKind,
    expiresAt: session.absoluteExpiresAt,
  };
});

| Export | Purpose | | ------------------------------------ | --------------------------------------------------------------------- | | requireIdentitySession | Authorize the opaque session, enforcing origin and CSRF for mutations | | executeAuthorizedIdentityOperation | Run a platform operation with an explicit replay policy | | exchangeIdentityRecoveryLink | Exchange a password-recovery link inside the server boundary | | IdentityAuthorizationRejected | Strictly identify a canonical OneX bearer-token rejection |

executeAuthorizedIdentityOperation defaults to replayPolicy: "never". Use "safe" only for a side-effect-free operation, or "idempotent" only when the complete business command and idempotency key are fixed outside the callback. After a strictly validated authorization rejection, the helper performs at most one credential rotation and replay. A second rejection or terminal refresh failure terminates the server session; transient failures preserve refresh authority.

Installed routes

All module-owned routes are private, no-store endpoints under /api/onex:

| Area | Routes | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Session | GET /session | | Sign-in | POST /auth/register, /auth/login, /auth/mfa/verify, /auth/webauthn/begin, /auth/webauthn/finish, /auth/oauth/:provider | | Guest | POST /auth/guest, /auth/guest/activation-requests | | Verification | POST /auth/verify-email, /auth/resend-verification | | Password | POST /auth/forgot-password, /auth/password-recovery/verify-code, /auth/password-recovery/exchange-link, /auth/reset-password, /auth/change-password | | Account | POST /auth/logout, PUT /profile, POST /account/deletion, /account/deletion/cancel |

The table omits the common /api/onex prefix for readability.

Session and security model

• HTTPS runtimes use __Host-onex_session with Secure, HttpOnly, SameSite=Lax, and Path=/.
• Explicit local HTTP runtimes use onex_local_identity_session without Secure.
• The trusted-proxy resolver rejects wildcard and /0 CIDRs and derives client context only from configured proxies.
• Same-origin mutation routes enforce exact origin and CSRF checks.
• Canonical OneX errors keep their HTTP status and { error: { type, code, message, param?, errors? } } envelope.
• No-store route rules prevent identity responses from entering Nitro caches.

Entry points

| Entry point | Runtime | | ---------------------------------------- | ----------------------------------------------------------------- | | @stackonward/onex-identity-nuxt | Nuxt module, option types, browser plugin, composable, and routes | | @stackonward/onex-identity-nuxt/server | Nitro-only authorization and recovery helpers |

Compatibility

• Node.js 20 or newer
• Nuxt >=3.15.0 <5
• Nitro >=2.10.0 <3
• H3 >=1.15.0 <2
• Peer versions matching the declared @stackonward/identity-browser, identity-session, and server-boundary ranges

Related packages

• @stackonward/identity-browser owns browser transactions and projections.
• @stackonward/identity-session owns the opaque-session state machine and server ports.
• @stackonward/server-boundary owns secret references and trusted client IP resolution.

License

MIT