@idp.global/sdk 18.0.1 → 18.2.0

package/ts_relyingparty/interfaces.ts

@@ -0,0 +1,165 @@
+import type { IOidcCompletion, TOidcCompletionFailureStage, TOidcTokenHint } from './classes.idpoidcprovider.js';
+
+/** A session as the application reads it; no token and no sealed value is part of it. */
+export interface IRelyingPartySession {
+  id: string;
+  /** the application's principal (user) the session acts as */
+  principalId: string;
+  createdAt: number;
+  lastSeenAt: number;
+  expiresAt: number;
+  /** the provider subject; absent for a session the application opened itself */
+  idpSubject?: string;
+  loginAttemptId?: string;
+}
+
+/**
+ * A live session with the principal it acts as. `principal` is what
+ * `principals.resolve` answered for it in the same read; with `isActive`
+ * principals it is `undefined`.
+ */
+export interface IRelyingPartyLiveSession<TPrincipal extends object | undefined = undefined> {
+  session: IRelyingPartySession;
+  principal: TPrincipal;
+}
+
+/** A live session behind a cookie, with its principal and the CSRF token derived for it. */
+export interface IResolvedRelyingPartySession<TPrincipal extends object | undefined = undefined> extends IRelyingPartyLiveSession<TPrincipal> {
+  csrfToken: string;
+}
+
+/** A session just opened: the answer, the CSRF token and the `Set-Cookie` value that carries it. */
+export interface IRelyingPartySessionOpening {
+  session: IRelyingPartySession;
+  csrfToken: string;
+  sessionCookie: string;
+}
+
+/** The redirect that starts a provider login, and the cookie that binds it to this browser. */
+export interface IRelyingPartyLoginStart {
+  authorizationUrl: URL;
+  intentCookie: string;
+}
+
+/** A provider access token usable right now, with the subject it belongs to. */
+export interface IProviderToken {
+  accessToken: string;
+  subject: string;
+  /** epoch milliseconds; `0` when the provider named no lifetime */
+  expiresAt: number;
+}
+
+/** What an authority observer needs from the session owner. `RelyingPartySessions` implements it. */
+export interface IAuthorityTokenSource {
+  /**
+   * The access token of a login session, rotated first when it is due. The
+   * session must belong to `expectedPrincipalIdArg`. Throws `AuthorityTokenError`.
+   */
+  liveProviderToken(sessionIdArg: string, expectedPrincipalIdArg: string): Promise<IProviderToken>;
+}
+
+/**
+ * The application's side of a provider login: who the verified subject is
+ * here. `admit` creates or updates the local principal (and whatever the
+ * application projects from the organization claims) and answers its id, or
+ * throws `RelyingPartyRefusal` to refuse the login; the provider tokens are
+ * then handed back and the refusal reaches the caller unchanged.
+ */
+export interface IRelyingPartyPrincipals {
+  admit(completionArg: IOidcCompletion): Promise<{ principalId: string }>;
+  /** Whether a principal may act right now; a session of an inactive principal resolves to nothing. */
+  isActive(principalIdArg: string): Promise<boolean>;
+}
+
+/**
+ * Principals that answer the principal itself instead of a yes or no, so a
+ * request reads its user once: `resolve` answers the principal when it may act
+ * right now and `null` otherwise, and every live session carries the answer as
+ * `principal`. Give either `isActive` or `resolve`, never both.
+ */
+export interface IRelyingPartyPrincipalResolver<TPrincipal extends object | undefined> {
+  admit(completionArg: IOidcCompletion): Promise<{ principalId: string }>;
+  /** The principal object when it may act right now, `null` otherwise; any answer that is not an object (including `false`) resolves the session to nothing. */
+  resolve(principalIdArg: string): Promise<TPrincipal | null>;
+}
+
+/**
+ * What `RelyingPartySessions` accepts as its principals: a resolver whose
+ * principal type every live session carries, or — only while that type is
+ * left `undefined` — the `isActive` form.
+ */
+export type TRelyingPartyPrincipals<TPrincipal extends object | undefined> =
+  | IRelyingPartyPrincipalResolver<TPrincipal>
+  | (undefined extends TPrincipal ? IRelyingPartyPrincipals : never);
+
+export type TRelyingPartySessionEndReason =
+  /** the application or the user ended it */
+  | 'logout'
+  /** the provider refused to rotate its tokens: the login is over there */
+  | 'refresh_token_refused'
+  /** its refresh token was sealed under a key this deployment no longer has */
+  | 'sealed_refresh_token_unreadable'
+  /** its access token is dead and there is nothing to rotate it with */
+  | 'access_token_unusable'
+  /** a rotation found it revoked by someone else */
+  | 'revoked_elsewhere';
+
+export type TRelyingPartyEventName =
+  | 'idp_token_refresh_failed'
+  | 'idp_token_store_failed'
+  | 'idp_session_ended'
+  | 'oidc_sealed_token_unreadable'
+  | 'oidc_token_revocation_failed'
+  | 'oidc_token_revocation_timed_out'
+  | 'login_attempt_sweep_failed'
+  /** an application hook threw; the step it belonged to ran on regardless */
+  | 'hook_failed'
+  /** a session whose opening failed could not be revoked; its provider tokens went back anyway */
+  | 'session_discard_failed';
+
+/** The application hooks whose failures `hook_failed` names. */
+export type TRelyingPartyHookName = 'onProviderSessionOpened' | 'onSessionEnded' | 'onEvent';
+
+/** One structured diagnostic line. It never carries a token, a cookie or a sealed value. */
+export interface IRelyingPartyEvent {
+  event: TRelyingPartyEventName;
+  sessionId?: string;
+  reason?: string;
+  hint?: TOidcTokenHint;
+  hook?: TRelyingPartyHookName;
+  message?: string;
+}
+
+export interface IRelyingPartyHooks {
+  /**
+   * A provider login opened a session, linked to its attempt. Runs before the
+   * login answers; a throw fails the login: the session is revoked, the
+   * provider tokens are handed back and the original error is rethrown.
+   */
+  onProviderSessionOpened?(eventArg: { session: IRelyingPartySession }): Promise<void>;
+  /**
+   * A session ended, or a caller tried to end one that was already over
+   * (`revokedHere: false`). Close its live connections when `revokedHere`,
+   * drop cached authority either way. Must not wait. A throw (or a rejected
+   * promise) is reported as a `hook_failed` event and never stops the end:
+   * the provider tokens go back regardless.
+   */
+  onSessionEnded?(eventArg: {
+    sessionId: string;
+    reason: TRelyingPartySessionEndReason;
+    revokedHere: boolean;
+  }): void;
+  /**
+   * Structured diagnostics; the default writes one JSON line to
+   * `console.error`. A throwing sink never interrupts the step that reported:
+   * the event and a `hook_failed` line go to `console.error` instead.
+   */
+  onEvent?(eventArg: IRelyingPartyEvent): void;
+}
+
+/** Where a failed login callback stopped; for the log, never for the browser. */
+export type TLoginCallbackStage =
+  | TOidcCompletionFailureStage
+  | 'attempt_persistence'
+  | 'principal_admission'
+  | 'session_persistence';

package/ts_relyingparty/plugins.ts

@@ -0,0 +1,17 @@
+import * as asyncHooks from 'node:async_hooks';
+import * as crypto from 'node:crypto';
+
+export { asyncHooks, crypto };
+
+import * as typedrequest from '@api.global/typedrequest';
+import * as typedsocket from '@api.global/typedsocket';
+
+export { typedrequest, typedsocket };
+
+import * as nosqldb from '@lossless.org/client/nosqldb';
+
+export { nosqldb };
+
+import * as openidClient from 'openid-client';
+
+export { openidClient };