@idp.global/sdk 18.0.1 → 18.1.0

package/ts_relyingparty/classes.actorscope.ts

@@ -0,0 +1,39 @@
+import * as plugins from './plugins.js';
+
+export interface IActorScope<TContext> {
+  /** Runs `operationArg` and everything it awaits as this actor. */
+  run<T>(contextArg: TContext, operationArg: () => T): T;
+  /** The actor of the operation in flight, or `undefined` outside one. */
+  current(): TContext | undefined;
+  /** Runs `operationArg` without any actor, for background work entered from a request. */
+  exit<T>(operationArg: () => T): T;
+  /**
+   * The request scope of a `TypedRouter` (`addRequestScope`): middleware and
+   * handler of every dispatch run as the actor the transport's trusted local
+   * data names. A dispatch without one runs without an actor.
+   */
+  readonly requestScope: plugins.typedrequest.TTypedRouterRequestScope;
+}
+
+/**
+ * An AsyncLocalStorage-backed actor context. The application decides what an
+ * actor is and how it is read from the trusted local data its transports set;
+ * nothing a handler can reach decides it.
+ */
+export const createActorScope = <TContext>(optionsArg: {
+  fromLocalData(localDataArg: Readonly<Record<string, unknown>>): TContext | undefined;
+}): IActorScope<TContext> => {
+  const storage = new plugins.asyncHooks.AsyncLocalStorage<TContext>();
+  return {
+    run: (contextArg, operationArg) => storage.run(contextArg, operationArg),
+    current: () => storage.getStore(),
+    exit: (operationArg) => storage.exit(operationArg),
+    requestScope: (_typedRequestArg, nextArg, contextArg) => {
+      const actor = optionsArg.fromLocalData(contextArg.localData);
+      if (actor === undefined) {
+        return nextArg();
+      }
+      return storage.run(actor, nextArg);
+    },
+  };
+};

package/ts_relyingparty/classes.authorityobserver.ts

@@ -0,0 +1,253 @@
+import { AuthorityTokenError } from './classes.errors.js';
+import { OidcAuthorityUnavailableError, type IOidcProvider } from './classes.idpoidcprovider.js';
+import type { IAuthorityTokenSource } from './interfaces.js';
+
+/** Why an observation refused: no membership at all, or roles the application maps to nothing. */
+export type TAuthorityRefusalReason = 'idp_membership_absent' | 'idp_roles_unmapped';
+
+/**
+ * idp.global no longer reports a usable membership of the organization.
+ * `firstRefusal` is `true` exactly once per transition from access to refusal
+ * for one login session and organization, so an audit trail records the
+ * transition and not every refused request.
+ */
+export class AuthorityRefusedError extends Error {
+  public readonly code = 'organization_access_revoked';
+  public readonly status = 403;
+
+  constructor(
+    public readonly reason: TAuthorityRefusalReason,
+    public readonly firstRefusal: boolean,
+  ) {
+    super('organization_access_revoked');
+    this.name = 'AuthorityRefusedError';
+  }
+}
+
+/** One live observation, as the caller reads it. */
+export interface IAuthorityObservation<TGrant> {
+  /** what the application's projection made of the roles */
+  grant: TGrant;
+  /** the idp role keys the provider reported, sorted */
+  roles: readonly string[];
+  /** the observation's own `exp` in epoch milliseconds */
+  tokenExpiresAt: number;
+  observedAt: number;
+}
+
+export interface IAuthorityObserverOptions<TGrant> {
+  provider: IOidcProvider;
+  tokens: IAuthorityTokenSource;
+  /** the application's role table: what the provider's role keys grant here, `undefined` for nothing */
+  project(rolesArg: readonly string[]): TGrant | undefined;
+  /**
+   * How long a positive observation answers later requests of the same login
+   * session and organization. `0` (the default) observes freshly for every
+   * operation, which is the provider's contract; a positive value is an
+   * explicit opt-in under which a revocation at idp.global takes effect here
+   * only once the cached answer expires.
+   */
+  positiveTtlMs?: number;
+  /** How long a refusal is reused; `0` (the default) never reuses one. */
+  negativeTtlMs?: number;
+  /** the bound of remembered observations */
+  maxEntries?: number;
+  now?: () => number;
+}
+
+const DEFAULT_MAX_ENTRIES = 2_000;
+/** how much room an eviction makes, so it does not run on every insert */
+const EVICTION_HEADROOM = 0.1;
+
+interface ICachedObservation<TGrant> {
+  outcome: 'active' | 'inactive';
+  grant?: TGrant;
+  reason?: TAuthorityRefusalReason;
+  roles: readonly string[];
+  tokenExpiresAt: number;
+  observedAt: number;
+  /** an entry at or past it never answers a request */
+  expiresAt: number;
+  /** the refusal whose transition was already reported */
+  reported: boolean;
+}
+
+const assertTtl = (valueArg: number, labelArg: string): number => {
+  if (!Number.isSafeInteger(valueArg) || valueArg < 0) {
+    throw new Error(labelArg + ' must be a non-negative integer of milliseconds');
+  }
+  return valueArg;
+};
+
+/**
+ * Live organization authority through idp.global: one `POST /oauth/introspect`
+ * observation of a login session's subject in one organization, projected by
+ * the application's role table.
+ *
+ * Observations of one key run once however many callers ask at the same time.
+ * A failure to observe is never remembered, so the caller fails closed on
+ * every attempt while the provider is unreachable. A session that is forgotten
+ * while its observation is in flight never stores a positive answer. Nothing
+ * runs on a timer: the cache is pruned when it is written to.
+ */
+export class AuthorityObserver<TGrant> {
+  readonly #cache = new Map<string, ICachedObservation<TGrant>>();
+  readonly #inFlight = new Map<string, Promise<ICachedObservation<TGrant>>>();
+  readonly #forgotten = new Set<string>();
+  readonly #provider: IOidcProvider;
+  readonly #tokens: IAuthorityTokenSource;
+  readonly #project: (rolesArg: readonly string[]) => TGrant | undefined;
+  readonly #positiveTtlMs: number;
+  readonly #negativeTtlMs: number;
+  readonly #maxEntries: number;
+  readonly #now: () => number;
+
+  constructor(optionsArg: IAuthorityObserverOptions<TGrant>) {
+    this.#provider = optionsArg.provider;
+    this.#tokens = optionsArg.tokens;
+    this.#project = optionsArg.project;
+    this.#positiveTtlMs = assertTtl(optionsArg.positiveTtlMs ?? 0, 'positiveTtlMs');
+    this.#negativeTtlMs = assertTtl(optionsArg.negativeTtlMs ?? 0, 'negativeTtlMs');
+    this.#maxEntries = optionsArg.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    if (!Number.isSafeInteger(this.#maxEntries) || this.#maxEntries < 1) {
+      throw new Error('maxEntries must be a positive integer');
+    }
+    this.#now = optionsArg.now ?? (() => Date.now());
+  }
+
+  /** How many observations are remembered right now. */
+  public get size(): number {
+    return this.#cache.size;
+  }
+
+  /**
+   * The grant of `principalId`'s login session in one organization at
+   * idp.global, or a throw: `AuthorityRefusedError` for a refusal,
+   * `AuthorityTokenError` when there is no live login to observe with or the
+   * provider could not be observed.
+   */
+  public async observe(optionsArg: {
+    loginSessionId: string;
+    principalId: string;
+    idpOrganizationId: string;
+  }): Promise<IAuthorityObservation<TGrant>> {
+    const key = `${optionsArg.loginSessionId} ${optionsArg.idpOrganizationId}`;
+    const cached = this.liveEntry(key);
+    const observation = cached ?? (await this.observeOnce(key, optionsArg));
+    if (observation.outcome !== 'active' || observation.grant === undefined) {
+      const firstRefusal = cached === undefined && !observation.reported;
+      observation.reported = true;
+      throw new AuthorityRefusedError(observation.reason ?? 'idp_membership_absent', firstRefusal);
+    }
+    return {
+      grant: observation.grant,
+      roles: observation.roles,
+      tokenExpiresAt: observation.tokenExpiresAt,
+      observedAt: observation.observedAt,
+    };
+  }
+
+  /** Drops every observation of a session; wire it to the session layer's `onSessionEnded`. */
+  public forgetSession(sessionIdArg: string): void {
+    const prefix = `${sessionIdArg} `;
+    for (const key of this.#cache.keys()) {
+      if (key.startsWith(prefix)) {
+        this.#cache.delete(key);
+      }
+    }
+    for (const key of this.#inFlight.keys()) {
+      if (key.startsWith(prefix)) {
+        this.#forgotten.add(key);
+      }
+    }
+  }
+
+  private liveEntry(keyArg: string): ICachedObservation<TGrant> | undefined {
+    const entry = this.#cache.get(keyArg);
+    return entry && entry.expiresAt > this.#now() ? entry : undefined;
+  }
+
+  private async observeOnce(
+    keyArg: string,
+    optionsArg: { loginSessionId: string; principalId: string; idpOrganizationId: string },
+  ): Promise<ICachedObservation<TGrant>> {
+    const running = this.#inFlight.get(keyArg);
+    if (running) {
+      return running;
+    }
+    const pending = this.makeObservation(keyArg, optionsArg).finally(() => {
+      this.#inFlight.delete(keyArg);
+      this.#forgotten.delete(keyArg);
+    });
+    this.#inFlight.set(keyArg, pending);
+    return pending;
+  }
+
+  private async makeObservation(
+    keyArg: string,
+    optionsArg: { loginSessionId: string; principalId: string; idpOrganizationId: string },
+  ): Promise<ICachedObservation<TGrant>> {
+    const token = await this.#tokens.liveProviderToken(optionsArg.loginSessionId, optionsArg.principalId);
+    let answer: Awaited<ReturnType<IOidcProvider['introspectOrganization']>>;
+    try {
+      answer = await this.#provider.introspectOrganization({
+        accessToken: token.accessToken,
+        subject: token.subject,
+        organizationId: optionsArg.idpOrganizationId,
+      });
+    } catch (error) {
+      if (error instanceof OidcAuthorityUnavailableError) {
+        throw new AuthorityTokenError('authority_unavailable', error);
+      }
+      throw error;
+    }
+    const grant = answer.active ? this.#project(answer.roles) : undefined;
+    const active = answer.active && grant !== undefined;
+    const previous = this.#cache.get(keyArg);
+    const entry: ICachedObservation<TGrant> = {
+      outcome: active ? 'active' : 'inactive',
+      ...(active ? { grant } : { reason: answer.active ? 'idp_roles_unmapped' : 'idp_membership_absent' }),
+      roles: answer.roles,
+      tokenExpiresAt: answer.expiresAt,
+      observedAt: this.#now(),
+      expiresAt: this.#now() + (active ? this.#positiveTtlMs : this.#negativeTtlMs),
+      // a refusal after a reported refusal is the same transition
+      reported: !active && previous?.outcome === 'inactive' && previous.reported,
+    };
+    if (active && this.#forgotten.has(keyArg)) {
+      // the request holding this answer finishes — it was authorized before
+      // the session ended — and every later one observes again
+      entry.expiresAt = 0;
+      return entry;
+    }
+    // a refusal is kept even when it answers nothing (`negativeTtlMs` 0): it is
+    // what reports one transition instead of one per refused request
+    this.#cache.delete(keyArg);
+    this.#cache.set(keyArg, entry);
+    this.prune();
+    return entry;
+  }
+
+  /** Expired entries go first; if that is not enough, the oldest do. */
+  private prune(): void {
+    if (this.#cache.size <= this.#maxEntries) {
+      return;
+    }
+    const now = this.#now();
+    for (const [key, entry] of this.#cache) {
+      if (entry.expiresAt <= now) {
+        this.#cache.delete(key);
+      }
+    }
+    if (this.#cache.size <= this.#maxEntries) {
+      return;
+    }
+    const target = Math.floor(this.#maxEntries * (1 - EVICTION_HEADROOM));
+    for (const key of this.#cache.keys()) {
+      if (this.#cache.size <= target) {
+        break;
+      }
+      this.#cache.delete(key);
+    }
+  }
+}

package/ts_relyingparty/classes.errors.ts

@@ -0,0 +1,69 @@
+import type { TLoginCallbackStage } from './interfaces.js';
+
+export type TRelyingPartyErrorCode =
+  | 'login_method_unavailable'
+  | 'invalid_login_callback'
+  | 'missing_login_intent'
+  | 'invalid_or_replayed_login'
+  | 'invalid_login_finalize';
+
+const RELYING_PARTY_ERROR_STATUS: Readonly<Record<TRelyingPartyErrorCode, number>> = {
+  login_method_unavailable: 404,
+  invalid_login_callback: 400,
+  missing_login_intent: 400,
+  invalid_or_replayed_login: 400,
+  invalid_login_finalize: 400,
+};
+
+/** A request the login flow refuses; the code is safe to answer, the browser learns nothing more. */
+export class RelyingPartyError extends Error {
+  public readonly status: number;
+
+  constructor(public readonly code: TRelyingPartyErrorCode) {
+    super(code);
+    this.name = 'RelyingPartyError';
+    this.status = RELYING_PARTY_ERROR_STATUS[code];
+  }
+}
+
+/**
+ * The application refuses a verified provider login (a disabled account, a
+ * subject of another issuer, no organization it serves). Thrown from
+ * `IRelyingPartyPrincipals.admit`; it reaches the caller unchanged.
+ */
+export class RelyingPartyRefusal extends Error {
+  constructor(
+    public readonly code: string,
+    public readonly status: number,
+  ) {
+    super(code);
+    this.name = 'RelyingPartyRefusal';
+  }
+}
+
+/** A login callback that failed for a reason other than a refusal; the stage is for the log only. */
+export class LoginCallbackError extends Error {
+  constructor(
+    public readonly stage: TLoginCallbackStage,
+    causeArg: unknown,
+  ) {
+    super('The login callback could not be completed', { cause: causeArg });
+    this.name = 'LoginCallbackError';
+  }
+}
+
+export type TAuthorityTokenErrorCode =
+  /** there is no live provider login this credential could be observed with */
+  | 'authority_login_required'
+  /** the provider could not be reached; the caller fails closed */
+  | 'authority_unavailable';
+
+export class AuthorityTokenError extends Error {
+  public readonly status: number;
+
+  constructor(public readonly code: TAuthorityTokenErrorCode, causeArg?: unknown) {
+    super(code, { cause: causeArg });
+    this.name = 'AuthorityTokenError';
+    this.status = code === 'authority_login_required' ? 403 : 503;
+  }
+}