@idp.global/sdk 19.0.0 → 19.1.0

package/dist_ts_relyingparty/testing.js

@@ -0,0 +1,222 @@
+import * as plugins from './plugins.js';
+import { OidcCompletionError, OidcRefreshRefusedError, } from './classes.idpoidcprovider.js';
+const randomToken = () => plugins.crypto.randomBytes(18).toString('base64url');
+/**
+ * The provider as `IOidcProvider` sees it. A test adds personas, names the one
+ * the next login signs in as (`signInNextAs`), follows the authorization URL
+ * back with `callbackUrlFor`, and changes what idp.global reports live
+ * (`setOrganizationRoles`, `endLoginsOf`). Codes are single use and bound to
+ * their login's state; 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,
+ * and each step can be made to fail.
+ */
+export class RelyingPartyProviderDouble {
+    requestTimeoutSeconds;
+    issuer;
+    accessTokenLifetimeSeconds;
+    authorizations = [];
+    completions = [];
+    revocations = [];
+    introspections = [];
+    refreshes = [];
+    /** when set, the completion of a login fails with it (an `OidcCompletionError` names its stage) */
+    completionFailure;
+    /** when set, every introspection fails with it (an `OidcAuthorityUnavailableError` for an unreachable provider) */
+    introspectionFailure;
+    /** when set, every refresh fails with it */
+    refreshFailure;
+    /** when set, every revocation fails with it, after it was recorded */
+    revocationFailure;
+    /** runs inside an introspection before it answers: a test holds one open with it */
+    onIntrospect;
+    /** runs inside a refresh before it answers: a test races a logout with it */
+    onRefresh;
+    #now;
+    #personas = new Map();
+    #codes = new Map();
+    #tokens = new Map();
+    #next;
+    constructor(optionsArg = {}) {
+        this.issuer = new URL(optionsArg.issuer ?? 'https://idp.test').origin;
+        this.accessTokenLifetimeSeconds = optionsArg.accessTokenLifetimeSeconds ?? 3_600;
+        this.requestTimeoutSeconds = optionsArg.requestTimeoutSeconds ?? 10;
+        this.#now = optionsArg.now ?? (() => Date.now());
+    }
+    // ---- personas ----
+    /** Adds a persona, or replaces the one with its subject. */
+    addPersona(personaArg) {
+        this.#personas.set(personaArg.subject, {
+            ...personaArg,
+            organizations: (personaArg.organizations ?? []).map((entryArg) => ({ ...entryArg, roles: [...entryArg.roles] })),
+        });
+    }
+    persona(subjectArg) {
+        return this.#personas.get(subjectArg);
+    }
+    /** The persona the next authorization signs in as; a persona given whole is added first. */
+    signInNextAs(personaArg) {
+        if (typeof personaArg !== 'string') {
+            this.addPersona(personaArg);
+        }
+        const subject = typeof personaArg === 'string' ? personaArg : personaArg.subject;
+        if (!this.#personas.has(subject)) {
+            throw new Error(`RelyingPartyProviderDouble: no persona ${subject}; addPersona first`);
+        }
+        this.#next = subject;
+    }
+    /**
+     * What idp.global reports for the persona in an organization from now on:
+     * its roles, or `null` when the persona is no member any more. Introspection
+     * reads it at once; the claims of a login are those of its sign-in.
+     */
+    setOrganizationRoles(subjectArg, organizationIdArg, rolesArg) {
+        const persona = this.requirePersona(subjectArg);
+        const organizations = (persona.organizations ?? []).filter((entryArg) => entryArg.id !== organizationIdArg);
+        if (rolesArg) {
+            const known = persona.organizations?.find((entryArg) => entryArg.id === organizationIdArg);
+            organizations.push({
+                id: organizationIdArg,
+                name: known?.name ?? organizationIdArg,
+                slug: known?.slug ?? organizationIdArg,
+                roles: [...rolesArg],
+            });
+        }
+        persona.organizations = organizations;
+    }
+    /** Ends every login of the persona at the provider: its tokens neither introspect nor rotate any more. */
+    endLoginsOf(subjectArg) {
+        for (const token of this.#tokens.values()) {
+            if (token.subject === subjectArg) {
+                token.revoked = true;
+            }
+        }
+    }
+    /** Where the provider would send the browser back after the login this authorization URL started. */
+    callbackUrlFor(authorizationUrlArg, redirectUriArg) {
+        const callback = new URL(redirectUriArg);
+        callback.searchParams.set('code', authorizationUrlArg.searchParams.get('code') ?? '');
+        callback.searchParams.set('state', authorizationUrlArg.searchParams.get('state') ?? '');
+        return callback;
+    }
+    // ---- IOidcProvider ----
+    async init() { }
+    async buildAuthorizationUrl(optionsArg) {
+        if (!this.#next) {
+            throw new Error('RelyingPartyProviderDouble: name the persona this login signs in as with signInNextAs');
+        }
+        this.authorizations.push({ ...optionsArg });
+        const code = 'code_' + randomToken();
+        this.#codes.set(code, { state: optionsArg.state, nonce: optionsArg.nonce, subject: this.#next });
+        const url = new URL('/oauth/authorize', this.issuer);
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('state', optionsArg.state);
+        url.searchParams.set('nonce', optionsArg.nonce);
+        if (optionsArg.prompt) {
+            url.searchParams.set('prompt', optionsArg.prompt);
+        }
+        // what the double hands back at once; a real provider answers it after the login page
+        url.searchParams.set('code', code);
+        return url;
+    }
+    async completeAuthorization(optionsArg) {
+        const code = optionsArg.callbackUrl.searchParams.get('code') ?? '';
+        const issued = this.#codes.get(code);
+        this.#codes.delete(code);
+        if (!issued || issued.state !== optionsArg.state) {
+            throw new OidcCompletionError('token_exchange', new Error('unknown, used or foreign code'));
+        }
+        if (issued.nonce !== optionsArg.nonce) {
+            throw new OidcCompletionError('token_validation', new Error('nonce mismatch'));
+        }
+        this.completions.push({ subject: issued.subject, state: issued.state });
+        if (this.completionFailure) {
+            throw this.completionFailure;
+        }
+        const persona = this.requirePersona(issued.subject);
+        const family = randomToken();
+        const access = this.issue('access', issued.subject, family);
+        const refresh = this.issue('refresh', issued.subject, family);
+        return {
+            subject: persona.subject,
+            accessToken: access.token,
+            refreshToken: refresh.token,
+            accessTokenExpiresAt: access.expiresAt,
+            ...(persona.email !== undefined ? { email: persona.email } : {}),
+            emailVerified: persona.emailVerified ?? true,
+            ...(persona.displayName !== undefined ? { displayName: persona.displayName } : {}),
+            organizations: (persona.organizations ?? []).map((entryArg) => ({ ...entryArg, roles: [...entryArg.roles] })),
+        };
+    }
+    async revokeToken(tokenArg, hintArg) {
+        this.revocations.push({ token: tokenArg, hint: hintArg });
+        if (this.revocationFailure) {
+            throw this.revocationFailure;
+        }
+        const token = this.#tokens.get(tokenArg);
+        if (token) {
+            token.revoked = true;
+        }
+    }
+    async introspectOrganization(optionsArg) {
+        this.introspections.push({ ...optionsArg });
+        await this.onIntrospect?.({ ...optionsArg });
+        if (this.introspectionFailure) {
+            throw this.introspectionFailure;
+        }
+        const token = this.#tokens.get(optionsArg.accessToken);
+        const inactive = { active: false, roles: [], expiresAt: 0 };
+        if (!token || token.kind !== 'access' || !this.isLive(token) || token.subject !== optionsArg.subject) {
+            return inactive;
+        }
+        const membership = this.#personas.get(token.subject)?.organizations?.find((entryArg) => entryArg.id === optionsArg.organizationId);
+        if (!membership) {
+            return inactive;
+        }
+        return { active: true, roles: [...membership.roles].sort(), expiresAt: token.expiresAt };
+    }
+    async refreshTokens(refreshTokenArg) {
+        this.refreshes.push(refreshTokenArg);
+        await this.onRefresh?.(refreshTokenArg);
+        if (this.refreshFailure) {
+            throw this.refreshFailure;
+        }
+        const token = this.#tokens.get(refreshTokenArg);
+        if (!token || token.kind !== 'refresh' || token.revoked) {
+            throw new OidcRefreshRefusedError(new Error('invalid_grant'));
+        }
+        if (token.used) {
+            // reuse of a superseded refresh token: the family dies
+            for (const entry of this.#tokens.values()) {
+                if (entry.family === token.family) {
+                    entry.revoked = true;
+                }
+            }
+            throw new OidcRefreshRefusedError(new Error('invalid_grant'));
+        }
+        token.used = true;
+        const access = this.issue('access', token.subject, token.family);
+        const refresh = this.issue('refresh', token.subject, token.family);
+        return { accessToken: access.token, refreshToken: refresh.token, accessTokenExpiresAt: access.expiresAt };
+    }
+    // ---- internals ----
+    requirePersona(subjectArg) {
+        const persona = this.#personas.get(subjectArg);
+        if (!persona) {
+            throw new Error(`RelyingPartyProviderDouble: no persona ${subjectArg}`);
+        }
+        return persona;
+    }
+    issue(kindArg, subjectArg, familyArg) {
+        const token = (kindArg === 'access' ? 'at_' : 'rt_') + randomToken();
+        const expiresAt = kindArg === 'access' && this.accessTokenLifetimeSeconds > 0
+            ? this.#now() + this.accessTokenLifetimeSeconds * 1_000
+            : 0;
+        this.#tokens.set(token, { subject: subjectArg, family: familyArg, expiresAt, kind: kindArg, revoked: false, used: false });
+        return { token, expiresAt };
+    }
+    isLive(tokenArg) {
+        return !tokenArg.revoked && (tokenArg.expiresAt === 0 || tokenArg.expiresAt > this.#now());
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidGVzdGluZy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX3JlbHlpbmdwYXJ0eS90ZXN0aW5nLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBQ3hDLE9BQU8sRUFDTCxtQkFBbUIsRUFDbkIsdUJBQXVCLEdBU3hCLE1BQU0sOEJBQThCLENBQUM7QUFnRHRDLE1BQU0sV0FBVyxHQUFHLEdBQVcsRUFBRSxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUMsV0FBVyxDQUFDLEVBQUUsQ0FBQyxDQUFDLFFBQVEsQ0FBQyxXQUFXLENBQUMsQ0FBQztBQUV2Rjs7Ozs7Ozs7O0dBU0c7QUFDSCxNQUFNLE9BQU8sMEJBQTBCO0lBQ3JCLHFCQUFxQixDQUFTO0lBQzlCLE1BQU0sQ0FBUztJQUN4QiwwQkFBMEIsQ0FBUztJQUUxQixjQUFjLEdBQWdDLEVBQUUsQ0FBQztJQUNqRCxXQUFXLEdBQThDLEVBQUUsQ0FBQztJQUM1RCxXQUFXLEdBQW1ELEVBQUUsQ0FBQztJQUNqRSxjQUFjLEdBQTRFLEVBQUUsQ0FBQztJQUM3RixTQUFTLEdBQWEsRUFBRSxDQUFDO0lBRXpDLG1HQUFtRztJQUM1RixpQkFBaUIsQ0FBUztJQUNqQyxtSEFBbUg7SUFDNUcsb0JBQW9CLENBQVM7SUFDcEMsNENBQTRDO0lBQ3JDLGNBQWMsQ0FBUztJQUM5QixzRUFBc0U7SUFDL0QsaUJBQWlCLENBQVM7SUFDakMsb0ZBQW9GO0lBQzdFLFlBQVksQ0FBbUc7SUFDdEgsNkVBQTZFO0lBQ3RFLFNBQVMsQ0FBOEM7SUFFckQsSUFBSSxDQUFlO0lBQ25CLFNBQVMsR0FBRyxJQUFJLEdBQUcsRUFBa0MsQ0FBQztJQUN0RCxNQUFNLEdBQUcsSUFBSSxHQUFHLEVBQXVCLENBQUM7SUFDeEMsT0FBTyxHQUFHLElBQUksR0FBRyxFQUF3QixDQUFDO0lBQ25ELEtBQUssQ0FBVTtJQUVmLFlBQVksYUFBcUMsRUFBRTtRQUNqRCxJ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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idp.global/sdk",
-  "version": "19.0.0",
+  "version": "19.1.0",
   "private": false,
   "description": "Reusable browser and server SDK for idp.global authentication.",
   "type": "module",
@@ -8,7 +8,8 @@
     ".": "./dist_ts/index.js",
     "./browser": "./dist_ts_browser/index.js",
     "./server": "./dist_ts_server/index.js",
-    "./relyingparty": "./dist_ts_relyingparty/index.js"
+    "./relyingparty": "./dist_ts_relyingparty/index.js",
+    "./relyingparty/testing": "./dist_ts_relyingparty/testing.js"
   },
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
@@ -18,7 +19,7 @@
     "@api.global/typedrequest": "^8.2.0",
     "@api.global/typedrequest-interfaces": "^7.1.0",
     "@api.global/typedsocket": "^8.7.0",
-    "@idp.global/interfaces": "^29.1.0",
+    "@idp.global/interfaces": "^30.0.0",
     "@push.rocks/smartjson": "^6.0.1",
     "@push.rocks/smartjwt": "^2.7.0",
     "@push.rocks/smartpromise": "^4.2.4",

package/readme.md

@@ -525,6 +525,20 @@ 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.
+- **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 +546,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 +695,55 @@ 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`). 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 +762,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.1.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 {
@@ -300,6 +312,7 @@ export class IdpOidcProvider implements IOidcProvider {
       code_challenge_method: 'S256',
       state: optionsArg.state,
       nonce: optionsArg.nonce,
+      ...(optionsArg.prompt ? { prompt: optionsArg.prompt } : {}),
     });
   }
 

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,15 @@ 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;
     await attempt.save();
 
     return {
-      authorizationUrl: await provider.buildAuthorizationUrl({ state, nonce, pkceVerifier }),
+      authorizationUrl: await provider.buildAuthorizationUrl({ state, nonce, pkceVerifier, ...(prompt ? { prompt } : {}) }),
       intentCookie: serializeCookie(this.intentCookieName, bindingToken, {
         httpOnly: true,
         secure: this.secureCookies,
@@ -456,7 +477,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 +720,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 +728,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 +736,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 +744,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;