@stackonward/identity-session

Product-neutral identity-session contracts and a server-only opaque session engine. The default entry is browser-safe; the /server entry owns credential encryption, repository compare-and-swap, lifecycle transitions, and replaceable identity ports.

Install

pnpm add @stackonward/identity-session

Browser-safe contracts

import type { IdentitySessionProjection, LoginIdentityInput } from "@stackonward/identity-session";

The main entry exports session, principal, next-action, command, and canonical error contracts. It does not import server cryptography, read credentials, or expose access-token fields.

Server engine

import { IdentitySessionEngine } from "@stackonward/identity-session/server";

const engine = new IdentitySessionEngine({
  productCode: "alpha",
  clientId: "alpha-web",
  absoluteTtlMilliseconds: 86_400_000,
  idleTtlMilliseconds: 1_800_000,
  preAuthenticatedTtlMilliseconds: 1_800_000,
  refreshBeforeMilliseconds: 120_000,
  transitionLockTtlMilliseconds: 5_000,
  guestCapabilityTtlSeconds: 900,
  guestCapabilityPolicy,
  admission,
  cipher,
  repository,
  ports: {
    authentication,
    guest,
    challenge,
    account,
  },
});

The example assumes the application has implemented the exported ports. The engine contains no HTTP framework, database driver, Redis client, or provider SDK.

Required server ports

| Port | Responsibility | | -------------------------------- | ---------------------------------------------------------------------------------- | | IdentityAuthenticationPort | Registration, login, MFA, WebAuthn, OAuth, password, and authorization transitions | | GuestIdentityPort | Guest capability issue and activation | | IdentityChallengePort | Email verification and password-recovery challenges | | IdentityAccountPort | Profile and account-deletion operations | | IdentitySessionRepository | Durable opaque-session storage, locks, CAS, rotation, and deletion | | SessionCipher | AEAD sealing and opening of credential material | | GuestSessionBootstrapAdmission | Admission control before creating a new session |

AesGcmSessionCipher is the supplied cipher implementation. Repository, admission, and upstream identity adapters remain application-owned.

Engine operations

The engine supports session bootstrap and CSRF validation; registration, login, MFA, WebAuthn, and OAuth; guest identity and activation; email verification and password recovery; profile, password, deletion, and logout; and downstream authorization, refresh, and termination.

Session projections contain identity state and a stable principal only. Entitlements, credits, subscriptions, devices, and content access belong to a separate application-owned viewer endpoint.

Lifecycle guarantees

• Guest capability intent is persisted before the external request, and retries reuse its idempotency key.
• Credentials remain AEAD-sealed at rest.
• Credential transitions use repository CAS, transition locks, and opaque-locator rotation.
• refreshAuthorization rotates credentials and the locator after a trusted downstream access-token rejection.
• Terminal authentication rejection deletes local authority; transient transport, rate-limit, storage, and lock failures preserve refresh authority.
• terminateAuthorization is the fail-closed operation for a trusted caller that confirms authorization is unusable.

Cookie creation, clearing, transport status codes, trusted client IPs, and request-scoped dependency composition belong to the server adapter.

Entry points

| Entry point | Purpose | | -------------------------------------- | -------------------------------------------------------------------------------- | | @stackonward/identity-session | Browser-safe identity contracts, error parsing, and HTTP response helpers | | @stackonward/identity-session/server | Engine, ports, repository contract, cipher, admission, and service authorization |

Compatibility

• Node.js 20 or newer
• ESM with TypeScript declarations
• Node.js node:crypto support for the supplied AES-256-GCM cipher

Related packages

• @stackonward/identity-browser consumes the browser-safe contract.
• @stackonward/server-boundary resolves secrets and trusted request topology.
• @stackonward/onex-identity-nuxt composes the engine into a Nuxt BFF.

License

MIT