@vigilkids/identity-session

Product-neutral identity-session contracts and a server-only opaque session engine.

The default export contains browser-safe session, principal, action, and command types. It cannot read or write credentials. Server applications import @vigilkids/identity-session/server and provide four narrow ports for authentication, guest identity, challenges, and account profiles.

import { IdentitySessionEngine } from '@vigilkids/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,
  guestCapabilityPolicy,
  admission,
  cipher,
  repository,
  ports: {
    authentication,
    guest,
    challenge,
    account,
  },
})

Session projections expose only identity state and a stable principal. Product subscriptions, entitlements, credits, devices, and content access belong to a separate product-owned Viewer endpoint.

Guest capability issuance is persisted before the external request, retries reuse the same idempotency key, credentials remain AEAD-sealed, and every credential transition uses repository CAS and rotation.

Server adapters can call refreshAuthorization after a trusted downstream Bearer boundary rejects the current access token. A successful refresh rotates both credentials and the opaque locator. Terminal authentication rejection deletes local authority and requires browser cookie clearing; transient transport, rate-limit, storage, and refresh-lock failures preserve refresh authority. terminateAuthorization provides the matching fail-closed operation when a trusted caller confirms that authorization is no longer usable.