Class Session

ReadonlyhandleId

ReadonlyhandleName

Readonlyaudience

Readonlyscopes

ReadonlyexpiresAt

Readonlytoken

Optional Readonlypath

ReadonlysessionId

isExpired

• isExpired(): boolean

• Checks if the session has expired based on the current time.

  Returns boolean

  true if the current time is past the expiresAt timestamp.

Staticcreate

• create(handle, options): Promise<Session>

• Creates a new signed session token.

  If the handle is a SubHandle, its constraints are validated before signing (audience, scopes, TTL, expiration). The derivation path is included in the payload as hPath.

  Parameters

  • handle: SubHandle | Handle

    The Handle or SubHandle that will sign this session.
  • options: SessionOptions

    Session configuration including audience, scopes, TTL, and optional sessionId.

  Returns Promise<Session>

  A Promise resolving to a new Session instance.

  Example

  const session = await Session.create(handle, {
    audience: 'app.example.com',
    scopes: ['read', 'write'],
    ttl: 3600,
    sessionId: 'unique-session-id' // optional
  });
  Copy

StaticverifyStateless

• verifyStateless(token, companyIdentity, expectedAudience, revocationChecker?): Promise<Session>

• Verifies a session token statelessly without server-side storage.

  Validates:

  • Token format (two Base64URL parts)
  • Payload size limit
  • Required fields (hId, hNm, aud, scp, exp, iat, jti)
  • Audience match
  • Expiration (with clock skew tolerance)
  • Signature (against the reconstructed Handle or SubHandle public key)
  • Revocation status (if a RevocationChecker is provided)

  For SubHandle sessions (those with hPath), the Handle/SubHandle is reconstructed atomically via Identity.deriveSubHandle.

  Parameters

  • token: string

    The Base64URL-encoded session token string.
  • companyIdentity: Identity

    The Identity used to reconstruct Handle/SubHandle public keys.
  • expectedAudience: string

    The audience that this token must be intended for.
  • OptionalrevocationChecker: RevocationChecker

    Optional checker for revocation list.

  Returns Promise<Session>

  A Promise resolving to a verified Session instance.

  Throws

  If the token is invalid, expired, tampered, audience mismatch, or revoked.

  Example

  const session = await Session.verifyStateless(
    token,
    companyIdentity,
    'app.example.com',
    redisRevocationChecker // optional
  );
  Copy

StaticverifyAttested

• verifyAttested(token, rootPublicKey, attestationChain, expectedAudience, revocationChecker?): Promise<Session>

• Verifies a session token together with its attestation chain (Mode 2 - using an attestation chain) — for verifiers that hold only the root PUBLIC key.

  The chain contains serialized attestations, root first:

  • handle sessions: [attestHandle_token] (length 1)
  • subhandle sessions: [attestHandle_token, attestSubHandle_token] (length 2)

  Enforced, in order: token structure and required fields (including iat); audience; session time (±30 s skew); chain shape; parent signature against rootPublicKey; parent validity and revocation; for subhandle sessions — child signature against the parent's subjectId, child validity/revocation, name/path agreement, wildcard permitting, hId == child.subjectId, and grant nesting (child scopes ⊆ parent scopes, child maxTtl ≤ parent maxTtl); session vs the effective grant (scopes, audiences, TTL); session expiry against the earliest attestation expiry; session signature against hId; session revocation — last.

  Parameters

  • token: string
  • rootPublicKey: Uint8Array
  • attestationChain: string[]

    Attestation tokens, root first; length must match the session kind (1 for Handle, 2 for SubHandle).
  • expectedAudience: string
  • OptionalrevocationChecker: RevocationChecker

    Optional; consulted for attestation jti values (each chain level) and the session jti.

  Returns Promise<Session>

  The verified session.

  Throws

  With code and level identifying the failed layer — integrate on these fields, not on message text.

  Example

  const A = await identity.attestHandle('station-001', grantA);
  const sub = await station.deriveSubHandle('connector-ccs');
  const B = await station.attestSubHandle('connector-ccs', grantB);
  const session = await Session.create(sub, {
    audience: 'ev-app.com', scopes: ['charge:start'], ttl: 1800,
  });
  const verified = await Session.verifyAttested(
    session.token, identity.getPublicKey(), [A.token, B.token],
    'ev-app.com',
  );
  Copy