@idp.global/sdk 18.3.1 → 19.1.0

package/dist_ts_relyingparty/testing.d.ts

@@ -0,0 +1,103 @@
+import { type IOidcAuthorizationOptions, type IOidcCompletion, type IOidcCompletionOptions, type IOidcOrganizationClaim, type IOidcOrganizationObservation, type IOidcProvider, type IOidcRefreshedTokens, type TOidcTokenHint } from './classes.idpoidcprovider.js';
+/**
+ * `@idp.global/sdk/relyingparty/testing`: an in-process idp.global for the
+ * tests of an application built on `RelyingPartySessions`. It is a test
+ * double and nothing else — no socket, no persistence, no check a real
+ * provider makes beyond the ones named here — and belongs in test code only.
+ */
+/** A person at the double, with the organizations idp.global reports for them. */
+export interface IProviderDoublePersona {
+    /** the stable `sub` */
+    subject: string;
+    displayName?: string;
+    email?: string;
+    /** `email_verified`; `true` when absent, as for an active idp.global account */
+    emailVerified?: boolean;
+    /** the `organizations` claim, and what introspection answers for each organization */
+    organizations?: IOidcOrganizationClaim[];
+}
+export interface IProviderDoubleOptions {
+    /** the issuer origin the authorization URLs point at; `https://idp.test` by default */
+    issuer?: string;
+    /** how long an access token lives, in seconds; 3600 by default, `0` names no lifetime */
+    accessTokenLifetimeSeconds?: number;
+    /** the clock every expiry reads; tests step it instead of sleeping */
+    now?: () => number;
+    requestTimeoutSeconds?: number;
+}
+/**
+ * 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 declare class RelyingPartyProviderDouble implements IOidcProvider {
+    #private;
+    readonly requestTimeoutSeconds: number;
+    readonly issuer: string;
+    accessTokenLifetimeSeconds: number;
+    readonly authorizations: IOidcAuthorizationOptions[];
+    readonly completions: Array<{
+        subject: string;
+        state: string;
+    }>;
+    readonly revocations: Array<{
+        token: string;
+        hint: TOidcTokenHint;
+    }>;
+    readonly introspections: Array<{
+        accessToken: string;
+        subject: string;
+        organizationId: string;
+    }>;
+    readonly refreshes: string[];
+    /** when set, the completion of a login fails with it (an `OidcCompletionError` names its stage) */
+    completionFailure?: Error;
+    /** when set, every introspection fails with it (an `OidcAuthorityUnavailableError` for an unreachable provider) */
+    introspectionFailure?: Error;
+    /** when set, every refresh fails with it */
+    refreshFailure?: Error;
+    /** when set, every revocation fails with it, after it was recorded */
+    revocationFailure?: Error;
+    /** runs inside an introspection before it answers: a test holds one open with it */
+    onIntrospect?: (optionsArg: {
+        accessToken: string;
+        subject: string;
+        organizationId: string;
+    }) => Promise<void>;
+    /** runs inside a refresh before it answers: a test races a logout with it */
+    onRefresh?: (refreshTokenArg: string) => Promise<void>;
+    constructor(optionsArg?: IProviderDoubleOptions);
+    /** Adds a persona, or replaces the one with its subject. */
+    addPersona(personaArg: IProviderDoublePersona): void;
+    persona(subjectArg: string): IProviderDoublePersona | undefined;
+    /** The persona the next authorization signs in as; a persona given whole is added first. */
+    signInNextAs(personaArg: string | IProviderDoublePersona): void;
+    /**
+     * 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: string, organizationIdArg: string, rolesArg: string[] | null): void;
+    /** Ends every login of the persona at the provider: its tokens neither introspect nor rotate any more. */
+    endLoginsOf(subjectArg: string): void;
+    /** Where the provider would send the browser back after the login this authorization URL started. */
+    callbackUrlFor(authorizationUrlArg: URL, redirectUriArg: URL | string): URL;
+    init(): Promise<void>;
+    buildAuthorizationUrl(optionsArg: IOidcAuthorizationOptions): Promise<URL>;
+    completeAuthorization(optionsArg: IOidcCompletionOptions): Promise<IOidcCompletion>;
+    revokeToken(tokenArg: string, hintArg: TOidcTokenHint): Promise<void>;
+    introspectOrganization(optionsArg: {
+        accessToken: string;
+        subject: string;
+        organizationId: string;
+    }): Promise<IOidcOrganizationObservation>;
+    refreshTokens(refreshTokenArg: string): Promise<IOidcRefreshedTokens>;
+    private requirePersona;
+    private issue;
+    private isLive;
+}

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": "18.3.1",
+  "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",
@@ -34,13 +35,13 @@
   },
   "devDependencies": {
     "@api.global/typedserver": "^11.4.0",
-    "@git.zone/tsbuild": "^5.0.0",
-    "@git.zone/tsdoc": "^3.0.0",
+    "@git.zone/tsbuild": "^5.1.2",
+    "@git.zone/tsdoc": "^3.0.2",
     "@git.zone/tsrun": "^3.0.2",
-    "@git.zone/tstest": "^6.3.2",
+    "@git.zone/tstest": "^7.2.0",
     "@lossless.org/client": "^1.0.0",
     "@lossless.org/nosqldb": "10.5.0",
-    "@types/node": "26.6.2"
+    "@types/node": "26.6.3"
   },
   "files": [
     "ts/**/*",

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
@@ -660,7 +676,59 @@ then the application's. The two options are not combined.
 
 **Socket peers.** `RelyingPartySocketBinding.tagConnection` and `upgradeOf` take
 the connection wrapper or the bare SmartServe peer (`TRelyingPartySocketPeer`),
-the two forms `TypedSocket.setServerTag` accepts.
+the two forms `TypedSocket.setServerTag` accepts. The binding names no
+TypedSocket or SmartServe version: its transport, connection and peer types are
+only what it reads (`setServerTag`, `findAllTargetConnectionsByTag`, a peer's
+upgrade headers), so the application's own server `TypedSocket` fits whichever
+major it runs. Name the application's connection type as the second type
+parameter and `connectionsOfSession` answers it:
+
+```ts
+import type { ISmartServeConnectionWrapper } from '@api.global/typedsocket';
+
+const binding = new RelyingPartySocketBinding<IUser, ISmartServeConnectionWrapper>({
+  sessions,
+  transport: () => typedserver.typedsocket,
+});
+for (const connection of await binding.connectionsOfSession(sessionId)) {
+  typedserver.removeServerTag(connection, binding.tagOf(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
 
@@ -668,13 +736,14 @@ the two forms `TypedSocket.setServerTag` accepts.
 | --- | --- |
 | `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
 
@@ -693,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: '18.3.1',
+  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);