@idp.global/sdk 19.0.0 → 19.2.0

package/readme.md

@@ -525,6 +525,25 @@ What it does:
   releases the return path only to the browser holding the session that attempt
   created. Return paths stay on the public origin and outside the login routes.
   Expired attempts are swept when the next login starts.
+- **Starting before discovery**: `provider.init()` runs discovery. An
+  application that must not depend on idp.global to start calls it in the
+  background until it succeeds. Until then, a login start fails and stores no
+  attempt, and introspection and refresh throw
+  `OidcAuthorityUnavailableError`, which fails closed.
+- **Intents and prompts**: `sessions.startLogin(returnPath, { intent, prompt })`
+  is what an application calls from a login entry of its own (an invitation it
+  accepts, an account it links, a client it authorizes). `intent` is the
+  application's text of up to 4,096 characters, sealed into the login attempt
+  like the verifier; it never travels through the browser or the provider, and
+  `principals.admit(completion, { intent, loginAttemptId })` receives it when
+  exactly this login comes back. `prompt` (`login`, `none`, `consent`) goes to
+  the authorization endpoint: `login` makes the person authenticate again
+  before something long-lived is made. A refusal from `admit` may name where
+  in the application the browser goes
+  (`new RelyingPartyRefusal(code, status, { location: '/#link/<token>' })`);
+  the routes follow it only when it is a plain path on the public origin
+  outside the login routes, exactly as given, and otherwise answer as if it
+  named none.
 - **Sessions**: an HttpOnly, `SameSite=Lax` cookie whose token is stored as a
   hash, touched at most once a minute, with a CSRF token derived per request as
   an HMAC of the cookie token. `GET /auth/session` answers the session and
@@ -532,7 +551,9 @@ What it does:
   cancelled as soon as it passes `maxBodyBytes`. Every end of a session is one
   conditional update; its provider tokens go back to idp.global within a
   three-second budget afterwards, and so do the tokens of a login that failed
-  after the code exchange.
+  after the code exchange. `openSession({ principalId, maxAgeSeconds })` opens
+  a session the application authenticated itself, optionally shorter than
+  `sessionMaxAgeSeconds` (the cookie with it), and without provider tokens.
 - **Provider tokens**: sealed with AES-256-GCM (`SecretBox`) and rotated shortly
   before they expire, once per process and under a lock stored on the session,
   so two replicas never spend one refresh token. A refused refresh ends the
@@ -679,19 +700,59 @@ for (const connection of await binding.connectionsOfSession(sessionId)) {
 }
 ```
 
+### Testing an Application
+
+`@idp.global/sdk/relyingparty/testing` exports `RelyingPartyProviderDouble`, an
+in-process idp.global implementing `IOidcProvider` for an application's own
+tests; it belongs in test code only.
+
+```ts
+import { RelyingPartyProviderDouble } from '@idp.global/sdk/relyingparty/testing';
+
+const idp = new RelyingPartyProviderDouble({ now: clock.now });
+idp.addPersona({
+  subject: 'sub-owner',
+  displayName: 'Olga Owner',
+  email: 'olga@example.com',
+  organizations: [{ id: 'idp-org-1', name: 'Example GmbH', slug: 'example', roles: ['owner'] }],
+});
+idp.signInNextAs('sub-owner');
+
+// the application's GET /auth/login answers with the authorization URL …
+const callback = idp.callbackUrlFor(authorizationUrl, new URL('/auth/callback', publicOrigin));
+// … and the browser comes back to the application's callback with it
+
+idp.setOrganizationRoles('sub-owner', 'idp-org-1', ['viewer']); // what introspection answers from now on
+idp.endLoginsOf('sub-owner'); // every token of the persona stops working
+```
+
+Codes are single use and bound to their login's state and nonce; access tokens
+introspect for their subject while they live; refresh tokens rotate, and a
+superseded one coming back revokes its whole family, as idp.global's reuse
+detection does. Every call is recorded (`authorizations`, `completions`,
+`revocations`, `introspections`, `refreshes`), and each step can be made to
+fail (`completionFailure`, `introspectionFailure`, `refreshFailure`,
+`revocationFailure`) or held open (`onIntrospect`, `onRefresh`). With
+`discoveryFailure` set, an `init` before one has succeeded fails with it, and
+until an `init` succeeds the double answers as `IdpOidcProvider` does before
+discovery. Once one has succeeded, discovery stays done, as with
+`IdpOidcProvider`; `discoveries` counts the calls. The claims of a login are
+those of its sign-in; introspection reads the persona as it is now.
+
 ### Relying-Party API Surface
 
 | API | Description |
 | --- | --- |
 | `IdpOidcProvider` | Discovery, PKCE authorization URL, code exchange with UserInfo, refresh, revocation and organization introspection for idp.global. Implements `IOidcProvider`. `trustedCaPem` or `fetch` for an issuer under a private CA. |
 | `createRelyingPartyModels()` | Binds the session and login-attempt models to one `SmartdataDb`, or to a function asked for it on every use, optionally under existing collection names. |
-| `RelyingPartySessions<TPrincipal>` | Login start/complete/abandon/finalize, `openSession`, `resolveCookieSession`, `revalidateSession`, `revalidateLiveSession`, `isSessionLive`, `validateCsrf`, `logout`/`endSession`, `endSessionsOfPrincipal`, `liveProviderToken`. Principals give `isActive` or `resolve` (`IRelyingPartyPrincipals`, `IRelyingPartyPrincipalResolver<TPrincipal>`); with `resolve`, live sessions carry `principal`. |
+| `RelyingPartySessions<TPrincipal>` | Login start (with an application intent and a prompt)/complete/abandon/finalize, `openSession` (with a shorter lifetime), `resolveCookieSession`, `revalidateSession`, `revalidateLiveSession`, `isSessionLive`, `validateCsrf`, `logout`/`endSession`, `endSessionsOfPrincipal`, `liveProviderToken`. Principals give `isActive` or `resolve` (`IRelyingPartyPrincipals`, `IRelyingPartyPrincipalResolver<TPrincipal>`); with `resolve`, live sessions carry `principal`. |
 | `AuthorityObserver` | Live organization authority with opt-in positive and negative reuse. |
 | `RelyingPartyRoutes` | `handle(ctx)` for `/auth/login`, `/auth/callback`, `/auth/finalize`, `/auth/session` and `/auth/logout`; `null` for anything else. Takes a typedserver route context. `onLogout` is awaited after a CSRF-checked logout ended the session. |
 | `createActorScope()` | AsyncLocalStorage actor context with a TypedRouter request scope. |
 | `RelyingPartySocketBinding` | TypedSocket browser registration, per-request re-validation and session tags; takes a connection wrapper or its peer. |
 | `SecretBox`, `deriveCsrfToken()`, `decodeSecretKey()`, `parseCookies()`, `serializeCookie()`, `sanitizeReturnPath()` | The primitives underneath. |
-| `RelyingPartyError`, `RelyingPartyRefusal`, `LoginCallbackError`, `AuthorityTokenError`, `AuthorityRefusedError`, `RelyingPartyDatabaseUnavailableError` | Errors with stable codes; none carries token material. |
+| `RelyingPartyError`, `RelyingPartyRefusal`, `LoginCallbackError`, `AuthorityTokenError`, `AuthorityRefusedError`, `RelyingPartyDatabaseUnavailableError` | Errors with stable codes; none carries token material. A `RelyingPartyRefusal` may name the application's `location` for the browser. |
+| `RelyingPartyProviderDouble` (`/relyingparty/testing`) | An in-process idp.global for an application's tests: personas, live organization roles, single-use codes, rotating and reuse-detecting refresh tokens, recorded calls and injectable failures. |
 
 ## Runtime Notes
 
@@ -710,7 +771,7 @@ The SDK uses typed sockets and typed requests from `@api.global/*`, shared idp.g
 pnpm test
 ```
 
-The test suite covers the server account store and auth service, browser transfer-token handling, typed administrative request names, the exact backend JWT keyset and blocklist contracts, and the relying-party layer: its primitives, the OIDC provider against a fetch-level issuer double, sessions and two-replica token rotation on an in-memory NoSQL engine with an injected clock, the persisted shape, the authority observer, the HTTP routes, the actor scope and the socket binding.
+The test suite covers the server account store and auth service, browser transfer-token handling, typed administrative request names, the exact backend JWT keyset and blocklist contracts, and the relying-party layer: its primitives, the OIDC provider against a fetch-level issuer double, sessions and two-replica token rotation on an in-memory NoSQL engine with an injected clock, the persisted shape, the authority observer, the HTTP routes, login intents and prompts, the actor scope, the socket binding and the provider double.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@idp.global/sdk',
-  version: '19.0.0',
+  version: '19.2.0',
   description: 'Reusable browser and server SDK for idp.global authentication.'
 }

package/ts_relyingparty/classes.errors.ts

@@ -30,14 +30,25 @@ export class RelyingPartyError extends Error {
  * 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.
+ * `location` is where in the application the browser goes for this very
+ * refusal (a step it has to take, with a one-time token in the fragment);
+ * `RelyingPartyRoutes` follows it only when it is a plain path on the
+ * application's origin outside the login routes, and otherwise answers as if
+ * none was given.
  */
 export class RelyingPartyRefusal extends Error {
+  public readonly location?: string;
+
   constructor(
     public readonly code: string,
     public readonly status: number,
+    optionsArg: { location?: string } = {},
   ) {
     super(code);
     this.name = 'RelyingPartyRefusal';
+    if (optionsArg.location !== undefined) {
+      this.location = optionsArg.location;
+    }
   }
 }
 

package/ts_relyingparty/classes.idpoidcprovider.ts

@@ -5,10 +5,22 @@ import {
 } from '../ts_server/classes.oidc-introspection-client.js';
 import { createTrustedCaFetch, type TOidcFetch } from '../ts_server/helpers.trusted-ca-fetch.js';
 
+/** The `prompt` values idp.global takes at its authorization endpoint. */
+export type TOidcPrompt = 'none' | 'login' | 'consent';
+
+export const OIDC_PROMPTS: readonly TOidcPrompt[] = ['none', 'login', 'consent'];
+
 export interface IOidcAuthorizationOptions {
   state: string;
   nonce: string;
   pkceVerifier: string;
+  /**
+   * What the provider is asked to do with a login it holds already: `login`
+   * asks the person to authenticate again (a fresh proof before something
+   * long-lived is made), `none` never shows a page, `consent` asks again.
+   * Absent: the provider decides.
+   */
+  prompt?: TOidcPrompt;
 }
 
 export interface IOidcCompletionOptions extends IOidcAuthorizationOptions {
@@ -104,6 +116,11 @@ export interface IOidcProvider {
    * keeps two replicas from spending one refresh token outlives it.
    */
   readonly requestTimeoutSeconds: number;
+  /**
+   * Discovery. Until it has succeeded no authorization URL can be built, and
+   * introspection and refresh fail with `OidcAuthorityUnavailableError`, so an
+   * application may start without it and call it again until it succeeds.
+   */
   init(): Promise<void>;
   buildAuthorizationUrl(optionsArg: IOidcAuthorizationOptions): Promise<URL>;
   completeAuthorization(optionsArg: IOidcCompletionOptions): Promise<IOidcCompletion>;
@@ -300,6 +317,7 @@ export class IdpOidcProvider implements IOidcProvider {
       code_challenge_method: 'S256',
       state: optionsArg.state,
       nonce: optionsArg.nonce,
+      ...(optionsArg.prompt ? { prompt: optionsArg.prompt } : {}),
     });
   }
 
@@ -367,7 +385,9 @@ export class IdpOidcProvider implements IOidcProvider {
     organizationId: string;
   }): Promise<IOidcOrganizationObservation> {
     if (!this.#introspection) {
-      throw new Error('The identity provider is not initialized');
+      // before discovery the provider cannot be asked: that is an
+      // unavailable authority, which the caller fails closed on
+      throw new OidcAuthorityUnavailableError('unavailable', new Error('The identity provider is not initialized'));
     }
     let response: Awaited<ReturnType<OidcIntrospectionClient['introspect']>>;
     try {

package/ts_relyingparty/classes.relyingpartyroutes.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import { LoginCallbackError, RelyingPartyError, RelyingPartyRefusal } from './classes.errors.js';
 import type { RelyingPartySessions } from './classes.relyingpartysessions.js';
+import { sanitizeReturnPath } from './helpers.returnpath.js';
 import type { IRelyingPartySession, IResolvedRelyingPartySession } from './interfaces.js';
 
 /**
@@ -167,6 +168,20 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
     }
   }
 
+  /**
+   * The location a refusal names itself, when it is a plain path on this
+   * origin outside the login routes exactly as given; anything the sanitizer
+   * would have to change is no location of this application.
+   */
+  private refusalLocationOf(refusalArg: RelyingPartyRefusal): string | undefined {
+    const location = refusalArg.location;
+    if (typeof location !== 'string' || location.length === 0) {
+      return undefined;
+    }
+    const sanitized = sanitizeReturnPath(location, this.#sessions.publicOrigin, this.#sessions.loginPathPrefix);
+    return sanitized === location ? sanitized : undefined;
+  }
+
   private async callback(contextArg: IRelyingPartyHttpContext): Promise<Response> {
     // the callback is read from the public origin, never from a forwarded host
     const callbackUrl = new URL(contextArg.url.pathname + contextArg.url.search, this.#sessions.publicOrigin);
@@ -186,6 +201,10 @@ export class RelyingPartyRoutes<TPrincipal extends object | undefined = undefine
       const clearIntent = { 'Set-Cookie': this.#sessions.clearIntentCookie() };
       if (error instanceof RelyingPartyRefusal) {
         this.emit({ event: 'auth_callback_refused', code: error.code });
+        const own = this.refusalLocationOf(error);
+        if (own) {
+          return redirect(own, clearIntent);
+        }
         const locations = this.#options.refusalLocations ?? {};
         if (Object.hasOwn(locations, error.code)) {
           return redirect(locations[error.code], clearIntent);

package/ts_relyingparty/classes.relyingpartysessions.ts

@@ -6,6 +6,7 @@ import {
   RelyingPartyRefusal,
 } from './classes.errors.js';
 import {
+  OIDC_PROMPTS,
   OidcCompletionError,
   OidcRefreshRefusedError,
   type IOidcCompletion,
@@ -22,7 +23,9 @@ import type {
   IProviderToken,
   IRelyingPartyEvent,
   IRelyingPartyHooks,
+  IRelyingPartyAdmission,
   IRelyingPartyLiveSession,
+  IRelyingPartyLoginOptions,
   IRelyingPartyLoginStart,
   IRelyingPartySession,
   IRelyingPartySessionOpening,
@@ -41,6 +44,8 @@ const MAX_COOKIE_TOKEN_LENGTH = 256;
 const SESSION_TOUCH_INTERVAL_MS = 60_000;
 /** A sign-in transaction has to survive an interactive login at the provider, not a working day. */
 export const LOGIN_ATTEMPT_MAX_AGE_SECONDS = 10 * 60;
+/** The longest intent a login carries (`IRelyingPartyLoginOptions.intent`), in characters. */
+export const RELYING_PARTY_MAX_INTENT_LENGTH = 4_096;
 /** Attempts are swept once they are this much older than their expiry. */
 const LOGIN_ATTEMPT_SWEEP_GRACE_MS = 60 * 60 * 1_000;
 /** How many of them one sign-in removes; the next sign-in takes the following page. */
@@ -141,7 +146,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
   public readonly loginPathPrefix: string;
   public readonly sessionMaxAgeSeconds: number;
   readonly #models: IRelyingPartyModels;
-  readonly #admit: TRelyingPartyPrincipals<TPrincipal>['admit'];
+  readonly #admit: (completionArg: IOidcCompletion, admissionArg: IRelyingPartyAdmission) => Promise<{ principalId: string }>;
   /** the principal of a session when it may act right now, `null` otherwise */
   readonly #activePrincipal: (principalIdArg: string) => Promise<{ principal: TPrincipal } | null>;
   readonly #provider?: IOidcProvider;
@@ -195,7 +200,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     if ((typeof resolve === 'function') === (typeof isActive === 'function')) {
       throw new Error('principals needs exactly one of isActive and resolve');
     }
-    this.#admit = (completionArg) => principals.admit(completionArg);
+    this.#admit = (completionArg, admissionArg) => principals.admit(completionArg, admissionArg);
     // choose the form by the same test the check above used, so a present but
     // undefined `resolve` (a spread, a widened object) selects `isActive`
     if (typeof resolve === 'function') {
@@ -243,16 +248,22 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
 
   /**
    * Opens a session the application authenticated itself (a local password
-   * login). It carries no provider tokens.
+   * login, a one-time link of its own). It carries no provider tokens.
+   * `maxAgeSeconds` makes it live shorter than `sessionMaxAgeSeconds`, the
+   * cookie with it; it is a whole number of seconds from 1 to that maximum.
    */
-  public async openSession(optionsArg: { principalId: string }): Promise<IRelyingPartySessionOpening> {
+  public async openSession(optionsArg: { principalId: string; maxAgeSeconds?: number }): Promise<IRelyingPartySessionOpening> {
     if (typeof optionsArg?.principalId !== 'string' || optionsArg.principalId.length === 0) {
       throw new Error('openSession needs a principal id');
     }
+    const maxAgeSeconds = optionsArg.maxAgeSeconds ?? this.sessionMaxAgeSeconds;
+    if (!Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds < 1 || maxAgeSeconds > this.sessionMaxAgeSeconds) {
+      throw new RangeError(`openSession maxAgeSeconds must be a whole number from 1 to ${this.sessionMaxAgeSeconds}`);
+    }
     const token = randomToken(32);
-    const session = this.newSessionDoc(token, optionsArg.principalId);
+    const session = this.newSessionDoc(token, optionsArg.principalId, maxAgeSeconds);
     await session.save();
-    return this.opening(session, token);
+    return this.opening(session, token, maxAgeSeconds);
   }
 
   /** The live session behind the session cookie, or `null`. A read touches it at most once a minute. */
@@ -378,8 +389,15 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * sealed next to it, and an intent cookie that binds the callback to this
    * browser.
    */
-  public async startLogin(returnPathArg: unknown): Promise<IRelyingPartyLoginStart> {
+  public async startLogin(returnPathArg: unknown, optionsArg: IRelyingPartyLoginOptions = {}): Promise<IRelyingPartyLoginStart> {
     const provider = this.requireProvider();
+    const { intent, prompt } = optionsArg;
+    if (intent !== undefined && (typeof intent !== 'string' || intent.length === 0 || intent.length > RELYING_PARTY_MAX_INTENT_LENGTH)) {
+      throw new RangeError(`a login intent is text of 1 to ${RELYING_PARTY_MAX_INTENT_LENGTH} characters`);
+    }
+    if (prompt !== undefined && !OIDC_PROMPTS.includes(prompt)) {
+      throw new RangeError(`a login prompt is one of ${OIDC_PROMPTS.join(', ')}`);
+    }
     await this.sweepExpiredAttempts();
     const state = randomToken(32);
     const nonce = randomToken(32);
@@ -394,12 +412,17 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     attempt.sealedPkceVerifier = this.#secretBox.seal(pkceVerifier);
     attempt.nonce = nonce;
     attempt.returnPath = sanitizeReturnPath(returnPathArg, this.publicOrigin, this.loginPathPrefix);
+    if (intent !== undefined) {
+      attempt.sealedIntent = this.#secretBox.seal(intent);
+    }
     attempt.createdAt = now;
     attempt.expiresAt = now + LOGIN_ATTEMPT_MAX_AGE_SECONDS * 1_000;
+    // the URL first: a login the provider cannot start yet (before discovery) stores no attempt
+    const authorizationUrl = await provider.buildAuthorizationUrl({ state, nonce, pkceVerifier, ...(prompt ? { prompt } : {}) });
     await attempt.save();
 
     return {
-      authorizationUrl: await provider.buildAuthorizationUrl({ state, nonce, pkceVerifier }),
+      authorizationUrl,
       intentCookie: serializeCookie(this.intentCookieName, bindingToken, {
         httpOnly: true,
         secure: this.secureCookies,
@@ -456,7 +479,10 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
         pkceVerifier: this.#secretBox.open(attempt.sealedPkceVerifier),
       });
       stage = 'principal_admission';
-      const { principalId } = await this.#admit(completion);
+      const { principalId } = await this.#admit(completion, {
+        loginAttemptId: attempt.id,
+        ...(attempt.sealedIntent ? { intent: this.#secretBox.open(attempt.sealedIntent) } : {}),
+      });
       stage = 'session_persistence';
       return await this.createProviderSession(attempt, principalId, completion);
     } catch (error) {
@@ -696,7 +722,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return this.#provider;
   }
 
-  private newSessionDoc(tokenArg: string, principalIdArg: string): RelyingPartySessionDoc {
+  private newSessionDoc(tokenArg: string, principalIdArg: string, maxAgeSecondsArg: number = this.sessionMaxAgeSeconds): RelyingPartySessionDoc {
     const now = this.#now();
     const session = new this.#models.Session();
     session.id = 'ses_' + randomToken(18);
@@ -704,7 +730,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     session.userId = principalIdArg;
     session.createdAt = now;
     session.lastSeenAt = now;
-    session.expiresAt = now + this.sessionMaxAgeSeconds * 1_000;
+    session.expiresAt = now + maxAgeSecondsArg * 1_000;
     return session;
   }
 
@@ -712,7 +738,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return deriveCsrfToken(tokenArg, this.#csrfKey, this.#csrfLabel);
   }
 
-  private opening(sessionArg: RelyingPartySessionDoc, tokenArg: string): IRelyingPartySessionOpening {
+  private opening(sessionArg: RelyingPartySessionDoc, tokenArg: string, maxAgeSecondsArg: number = this.sessionMaxAgeSeconds): IRelyingPartySessionOpening {
     return {
       session: this.snapshot(sessionArg),
       csrfToken: this.csrfTokenOf(tokenArg),
@@ -720,7 +746,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
         httpOnly: true,
         secure: this.secureCookies,
         sameSite: 'Lax',
-        maxAgeSeconds: this.sessionMaxAgeSeconds,
+        maxAgeSeconds: maxAgeSecondsArg,
       }),
     };
   }

package/ts_relyingparty/classes.rpmodels.ts

@@ -86,6 +86,10 @@ export class RelyingPartyLoginAttemptDoc extends plugins.nosqldb.SmartDataDbDoc<
   @plugins.nosqldb.svDb()
   public returnPath: string = '/';
 
+  /** the application's intent for this login, sealed like the verifier (`IRelyingPartyLoginOptions.intent`); absent without one */
+  @plugins.nosqldb.svDb()
+  public sealedIntent?: string;
+
   @plugins.nosqldb.svDb()
   public createdAt: number = 0;
 

package/ts_relyingparty/interfaces.ts

@@ -1,4 +1,4 @@
-import type { IOidcCompletion, TOidcCompletionFailureStage, TOidcTokenHint } from './classes.idpoidcprovider.js';
+import type { IOidcCompletion, TOidcCompletionFailureStage, TOidcPrompt, 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 {
@@ -35,6 +35,27 @@ export interface IRelyingPartySessionOpening {
   sessionCookie: string;
 }
 
+/**
+ * What `startLogin` carries besides the return path. `intent` is the
+ * application's own text — the invitation a login accepts, the account it
+ * links, the client it authorizes — sealed into the login attempt and handed
+ * to admission (`IRelyingPartyAdmission`) when exactly this login comes back;
+ * it never travels through the browser or the provider.
+ */
+export interface IRelyingPartyLoginOptions {
+  /** at most `RELYING_PARTY_MAX_INTENT_LENGTH` characters, not empty */
+  intent?: string;
+  prompt?: TOidcPrompt;
+}
+
+/** What admission learns about the login besides the provider's completion. */
+export interface IRelyingPartyAdmission {
+  /** the intent `startLogin` was given for this login, opened from its seal; absent when there was none */
+  intent?: string;
+  /** the login attempt the session will name (`IRelyingPartySession.loginAttemptId`) */
+  loginAttemptId: string;
+}
+
 /** The redirect that starts a provider login, and the cookie that binds it to this browser. */
 export interface IRelyingPartyLoginStart {
   authorizationUrl: URL;
@@ -66,7 +87,7 @@ export interface IAuthorityTokenSource {
  * then handed back and the refusal reaches the caller unchanged.
  */
 export interface IRelyingPartyPrincipals {
-  admit(completionArg: IOidcCompletion): Promise<{ principalId: string }>;
+  admit(completionArg: IOidcCompletion, admissionArg: IRelyingPartyAdmission): Promise<{ principalId: string }>;
   /** Whether a principal may act right now; a session of an inactive principal resolves to nothing. */
   isActive(principalIdArg: string): Promise<boolean>;
 }
@@ -78,7 +99,7 @@ export interface IRelyingPartyPrincipals {
  * `principal`. Give either `isActive` or `resolve`, never both.
  */
 export interface IRelyingPartyPrincipalResolver<TPrincipal extends object | undefined> {
-  admit(completionArg: IOidcCompletion): Promise<{ principalId: string }>;
+  admit(completionArg: IOidcCompletion, admissionArg: IRelyingPartyAdmission): 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>;
 }