@idp.global/sdk 16.0.0 → 16.1.0

package/changelog.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 2026-09-09 - 16.1.0
+
+### Features
+
+- add confidential OIDC introspection client (server)
+  - Add a server-only OidcIntrospectionClient with Basic authentication, nonce binding, deadlines, response size limits, and sanitized errors.
+  - Validate active and inactive introspection responses against issuer, client, subject, organization, scopes, revisions, roles, and freshness.
+  - Export the client and error types from the server entrypoint and document live organization authority usage.
+  - Update @idp.global/interfaces to ^29.1.0 for introspection response types.
+
+### Fixes
+
+- update development tooling dependencies (tooling)
+  - Bump @git.zone/tsdoc to ^2.2.0 and @git.zone/tstest to ^4.1.1
+  - Pin @types/node to 26.4.1
+  - Update packageManager to pnpm@12.2.1
+
 ## 2026-09-05 - 16.0.0
 
 ### Breaking Changes

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@idp.global/sdk',
-    version: '16.0.0',
+    version: '16.1.0',
     description: 'Reusable browser and server SDK for idp.global authentication.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxpQkFBaUI7SUFDdkIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLGdFQUFnRTtDQUM5RSxDQUFBIn0=

package/dist_ts_server/classes.oidc-introspection-client.d.ts

@@ -0,0 +1,24 @@
+import * as plugins from './plugins.js';
+export interface IOidcIntrospectionClientOptions {
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+}
+export interface IOidcIntrospectionClientRequest {
+    token: string;
+    subject: string;
+    organizationId: string;
+}
+export declare class OidcIntrospectionError extends Error {
+    readonly code: 'invalid_request' | 'invalid_response' | 'unavailable';
+    constructor(code: 'invalid_request' | 'invalid_response' | 'unavailable');
+}
+/** Server-only confidential client. Each result is one live observation, never a cached grant. */
+export declare class OidcIntrospectionClient {
+    #private;
+    constructor(optionsArg: IOidcIntrospectionClientOptions);
+    introspect(requestArg: IOidcIntrospectionClientRequest): Promise<plugins.idpInterfaces.data.TOidcIntrospectionResponse>;
+    private validateResponse;
+}

package/dist_ts_server/classes.oidc-introspection-client.js

@@ -0,0 +1,144 @@
+import * as plugins from './plugins.js';
+export class OidcIntrospectionError extends Error {
+    code;
+    constructor(code) {
+        super(`OIDC introspection ${code.replace(/_/g, ' ')}.`);
+        this.code = code;
+        this.name = 'OidcIntrospectionError';
+    }
+}
+const exactString = (valueArg, maximumArg = 512) => typeof valueArg === 'string' && valueArg.length > 0 && valueArg.length <= maximumArg
+    && valueArg.trim() === valueArg;
+const record = (valueArg) => valueArg !== null && typeof valueArg === 'object' && !Array.isArray(valueArg);
+const exactKeys = (valueArg, keysArg) => Object.keys(valueArg).length === keysArg.length && keysArg.every((keyArg) => Object.hasOwn(valueArg, keyArg));
+const revision = (valueArg) => Number.isSafeInteger(valueArg) && valueArg >= 0;
+const sortedUnique = (valuesArg) => Array.isArray(valuesArg)
+    && valuesArg.length > 0 && valuesArg.every((valueArg, indexArg) => exactString(valueArg, 64)
+    && (indexArg === 0 || valuesArg[indexArg - 1] < valueArg));
+/** Server-only confidential client. Each result is one live observation, never a cached grant. */
+export class OidcIntrospectionClient {
+    #issuer;
+    #clientId;
+    #authorization;
+    #timeoutMs;
+    #maxResponseBytes;
+    constructor(optionsArg) {
+        if (!optionsArg || !exactString(optionsArg.issuer, 2048) || !exactString(optionsArg.clientId)
+            || !exactString(optionsArg.clientSecret, 4096))
+            throw new OidcIntrospectionError('invalid_request');
+        let issuer;
+        try {
+            issuer = new URL(optionsArg.issuer);
+        }
+        catch {
+            throw new OidcIntrospectionError('invalid_request');
+        }
+        const canonicalIssuer = issuer.origin + (issuer.pathname === '/' ? '' : issuer.pathname);
+        if (issuer.protocol !== 'https:' || issuer.username || issuer.password || issuer.search || issuer.hash
+            || issuer.pathname.includes('//') || issuer.pathname.endsWith('/') && issuer.pathname !== '/'
+            || canonicalIssuer !== optionsArg.issuer)
+            throw new OidcIntrospectionError('invalid_request');
+        this.#timeoutMs = optionsArg.timeoutMs ?? 5000;
+        this.#maxResponseBytes = optionsArg.maxResponseBytes ?? 16384;
+        if (!Number.isSafeInteger(this.#timeoutMs) || this.#timeoutMs < 1 || this.#timeoutMs > 30000
+            || !Number.isSafeInteger(this.#maxResponseBytes) || this.#maxResponseBytes < 1 || this.#maxResponseBytes > 65536) {
+            throw new OidcIntrospectionError('invalid_request');
+        }
+        this.#issuer = canonicalIssuer;
+        this.#clientId = optionsArg.clientId;
+        // OAuth Basic components are form-encoded separately before joining with ':'.
+        const encode = (valueArg) => new URLSearchParams({ value: valueArg }).toString().slice(6);
+        this.#authorization = `Basic ${Buffer.from(`${encode(optionsArg.clientId)}:${encode(optionsArg.clientSecret)}`, 'utf8').toString('base64')}`;
+    }
+    async introspect(requestArg) {
+        if (!requestArg || !exactString(requestArg.token, 16384) || !exactString(requestArg.subject)
+            || !exactString(requestArg.organizationId))
+            throw new OidcIntrospectionError('invalid_request');
+        // Capture bindings before crossing any asynchronous boundary.
+        const { token, subject, organizationId } = requestArg;
+        const nonce = plugins.crypto.randomBytes(32).toString('base64url');
+        const controller = new AbortController();
+        let timer;
+        const deadline = new Promise((_resolveArg, rejectArg) => {
+            timer = setTimeout(() => { controller.abort(); rejectArg(new OidcIntrospectionError('unavailable')); }, this.#timeoutMs);
+        });
+        let reader;
+        try {
+            const response = await Promise.race([fetch(`${this.#issuer}/oauth/introspect`, {
+                    method: 'POST', redirect: 'error', credentials: 'omit', cache: 'no-store', signal: controller.signal,
+                    headers: { authorization: this.#authorization, 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+                    body: new URLSearchParams({ token, subject, organization_id: organizationId, nonce, token_type_hint: 'access_token' }),
+                }), deadline]);
+            if (response.status !== 200)
+                throw new OidcIntrospectionError('unavailable');
+            if (response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/json'
+                || !response.headers.get('cache-control')?.toLowerCase().split(',').map((partArg) => partArg.trim()).includes('no-store')
+                || !response.body)
+                throw new OidcIntrospectionError('invalid_response');
+            const contentLength = response.headers.get('content-length');
+            if (contentLength !== null && (!/^\d+$/.test(contentLength) || Number(contentLength) > this.#maxResponseBytes)) {
+                throw new OidcIntrospectionError('invalid_response');
+            }
+            reader = response.body.getReader();
+            const chunks = [];
+            let size = 0;
+            while (true) {
+                const part = await Promise.race([reader.read(), deadline]);
+                if (part.done)
+                    break;
+                size += part.value.byteLength;
+                if (size > this.#maxResponseBytes)
+                    throw new OidcIntrospectionError('invalid_response');
+                chunks.push(part.value);
+            }
+            let value;
+            try {
+                value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+            }
+            catch {
+                throw new OidcIntrospectionError('invalid_response');
+            }
+            return this.validateResponse(value, subject, organizationId, nonce);
+        }
+        catch (errorArg) {
+            if (errorArg instanceof OidcIntrospectionError)
+                throw errorArg;
+            // Never include request, credentials, token, transport details or body in an error.
+            throw new OidcIntrospectionError('unavailable');
+        }
+        finally {
+            clearTimeout(timer);
+            controller.abort();
+            if (reader)
+                void reader.cancel().catch(() => undefined);
+        }
+    }
+    validateResponse(valueArg, subjectArg, organizationIdArg, nonceArg) {
+        const invalid = () => new OidcIntrospectionError('invalid_response');
+        if (!record(valueArg))
+            throw invalid();
+        if (valueArg.active === false && exactKeys(valueArg, ['active']))
+            return { active: false };
+        if (valueArg.active !== true || !exactKeys(valueArg, ['active', 'token_type', 'client_id', 'scope', 'iss', 'aud', 'sub', 'exp', 'iat', 'idp_global_authority'])
+            || valueArg.token_type !== 'Bearer' || valueArg.client_id !== this.#clientId || valueArg.aud !== this.#clientId
+            || valueArg.iss !== this.#issuer || valueArg.sub !== subjectArg || !revision(valueArg.exp) || !revision(valueArg.iat)
+            || valueArg.exp <= Math.floor(Date.now() / 1000) || valueArg.iat > Math.floor(Date.now() / 1000)
+            || valueArg.exp <= valueArg.iat || typeof valueArg.scope !== 'string')
+            throw invalid();
+        const scopes = valueArg.scope.split(' ');
+        if (!sortedUnique(scopes) || !scopes.includes('openid') || !scopes.includes('organizations')
+            || !scopes.every((scopeArg) => ['openid', 'profile', 'email', 'organizations', 'roles'].includes(scopeArg)))
+            throw invalid();
+        const authority = valueArg.idp_global_authority;
+        if (!record(authority) || !exactKeys(authority, ['version', 'nonce', 'subject_revision', 'organization_id',
+            'organization_revision', 'membership_id', 'membership_revision', 'app_connection_id', 'app_connection_revision', 'roles'])
+            || authority.version !== 1 || authority.nonce !== nonceArg || authority.organization_id !== organizationIdArg
+            || !revision(authority.subject_revision) || !revision(authority.organization_revision)
+            || !revision(authority.membership_revision) || !revision(authority.app_connection_revision)
+            || !exactString(authority.membership_id) || !exactString(authority.app_connection_id) || !sortedUnique(authority.roles)
+            || !authority.roles.every((roleArg) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(roleArg)))
+            throw invalid();
+        return valueArg;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5vaWRjLWludHJvc3BlY3Rpb24tY2xpZW50LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfc2VydmVyL2NsYXNzZXMub2lkYy1pbnRyb3NwZWN0aW9uLWNsaWVudC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQWdCeEMsTUFBTSxPQUFPLHNCQUF1QixTQUFRLEtBQUs7SUFDbkI7SUFBNUIsWUFBNEIsSUFBNEQ7UUFDdEYsS0FBSyxDQUFDLHNCQUFzQixJQUFJLENBQUMsT0FBTyxDQUFDLElBQUksRUFBRSxHQUFHLENBQUMsR0FBRyxDQUFDLENBQUM7UUFEOUIsU0FBSSxHQUFKLElBQUksQ0FBd0Q7UUFFdEYsSUFBSSxDQUFDLElBQUksR0FBRyx3QkFBd0IsQ0FBQztJQUN2QyxDQUFDO0NBQ0Y7QUFFRCxNQUFNLFdBQVcsR0FBRyxDQUFDLFFBQWlCLEVBQUUsVUFBVSxHQUFHLEdBQUcsRUFBc0IsRUFBRSxDQUM5RSxPQUFPLFFBQVEsS0FBSyxRQUFRLElBQUksUUFBUSxDQUFDLE1BQU0sR0FBRyxDQUFDLElBQUksUUFBUSxDQUFDLE1BQU0sSUFBSSxVQUFVO09BQ2pGLFFBQVEsQ0FBQyxJQUFJLEVBQUUsS0FBSyxRQUFRLENBQUM7QUFDbEMsTUFBTSxNQUFNLEdBQUcsQ0FBQyxRQUFpQixFQUF1QyxFQUFFLENBQ3hFLFFBQVEsS0FBSyxJQUFJLElBQUksT0FBTyxRQUFRLEtBQUssUUFBUSxJQUFJLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUMsQ0FBQztBQUNoRixNQUFNLFNBQVMsR0FBRyxDQUFDLFFBQWlDLEVBQUUsT0FBaUIsRUFBRSxFQUFFLENBQ3pFLE1BQU0sQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLENBQUMsTUFBTSxLQUFLLE9BQU8sQ0FBQyxNQUFNLElBQUksT0FBTyxDQUFDLEtBQUssQ0FBQyxDQUFDLE1BQU0sRUFBRSxFQUFF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

package/dist_ts_server/index.d.ts

@@ -3,4 +3,5 @@ export * from './classes.account-auth-service.js';
 export * from './classes.account-doc.js';
 export * from './classes.account-store.js';
 export * from './classes.idp-global-server-client.js';
+export * from './classes.oidc-introspection-client.js';
 export * from './classes.password-hasher.js';

package/dist_ts_server/index.js

@@ -3,5 +3,6 @@ export * from './classes.account-auth-service.js';
 export * from './classes.account-doc.js';
 export * from './classes.account-store.js';
 export * from './classes.idp-global-server-client.js';
+export * from './classes.oidc-introspection-client.js';
 export * from './classes.password-hasher.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19zZXJ2ZXIvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLG1DQUFtQyxDQUFDO0FBQ2xELGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYyw0QkFBNEIsQ0FBQztBQUMzQyxjQUFjLHVDQUF1QyxDQUFDO0FBQ3RELGNBQWMsOEJBQThCLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90c19zZXJ2ZXIvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLG1DQUFtQyxDQUFDO0FBQ2xELGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYyw0QkFBNEIsQ0FBQztBQUMzQyxjQUFjLHVDQUF1QyxDQUFDO0FBQ3RELGNBQWMsd0NBQXdDLENBQUM7QUFDdkQsY0FBYyw4QkFBOEIsQ0FBQyJ9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idp.global/sdk",
-  "version": "16.0.0",
+  "version": "16.1.0",
   "private": false,
   "description": "Reusable browser and server SDK for idp.global authentication.",
   "type": "module",
@@ -17,7 +17,7 @@
     "@api.global/typedrequest": "^5.2.1",
     "@api.global/typedrequest-interfaces": "^5.1.1",
     "@api.global/typedsocket": "^6.0.0",
-    "@idp.global/interfaces": "^29.0.0",
+    "@idp.global/interfaces": "^29.1.0",
     "@push.rocks/smartdata": "^11.7.0",
     "@push.rocks/smartjson": "^6.0.1",
     "@push.rocks/smartpromise": "^4.2.4",
@@ -30,11 +30,11 @@
   },
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsdoc": "^2.1.1",
+    "@git.zone/tsdoc": "^2.2.0",
     "@git.zone/tsrun": "^2.0.6",
-    "@git.zone/tstest": "^4.0.0",
+    "@git.zone/tstest": "^4.1.1",
     "@push.rocks/smartdb": "^2.12.2",
-    "@types/node": "^26.4.1"
+    "@types/node": "26.4.1"
   },
   "files": [
     "ts/**/*",
@@ -44,7 +44,7 @@
     "dist_*/**/*",
     "readme.md",
     "changelog.md",
-    "license"
+    "license.md"
   ],
   "repository": {
     "type": "git",

package/readme.md

@@ -1,6 +1,6 @@
 # @idp.global/sdk
 
-Reusable TypeScript SDK for building against idp.global from both sides of the wire: browser apps that need SSO, JWT housekeeping, transfer-token handoff, and typed IdP requests; and server apps that need explicit account storage, local password auth, and optional idp.global password verification.
+Reusable TypeScript SDK for building against idp.global from both sides of the wire: browser apps that need SSO, JWT housekeeping, transfer-token handoff, and typed IdP requests; and server apps that need explicit account storage, local password auth, optional idp.global password verification, and confidential OIDC membership introspection.
 
 The package is intentionally split by runtime. Use `@idp.global/sdk/browser` in browser bundles and `@idp.global/sdk/server` in Node.js services. The root `@idp.global/sdk` export does not expose application APIs.
 
@@ -13,7 +13,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 | Runtime | Import | What it does |
 | --- | --- | --- |
 | Browser | `@idp.global/sdk/browser` | SSO client, JWT and refresh-token storage, login redirects, logout, transfer-token exchange, and typed request shortcuts for user, organization, billing, OIDC, and admin flows. |
-| Server | `@idp.global/sdk/server` | Smartdata-backed account store, scrypt password hashing, local/idp.global account authentication, and a server-side typed-socket client for idp.global password login. |
+| Server | `@idp.global/sdk/server` | Smartdata-backed account store, scrypt password hashing, local/idp.global account authentication, a server-side typed-socket client for idp.global password login, and confidential OIDC introspection. |
 
 ## Install
 
@@ -291,6 +291,46 @@ themselves.
 Verification is keyset-only. Replace the cached snapshot on every push, select
 the verification key by the JWT header `kid`, and reject unknown key IDs.
 
+### Live Organization Authority
+
+`OidcIntrospectionClient` calls the public issuer's `/oauth/introspect` endpoint
+with confidential OAuth Basic authentication. Keep the client secret and access
+token on the server. The token must belong to that same OAuth client and include
+`openid organizations`; use the exact subject from the validated OIDC login and
+the canonical organization ID.
+
+```ts
+import { OidcIntrospectionClient } from '@idp.global/sdk/server';
+
+const introspection = new OidcIntrospectionClient({
+  issuer: 'https://idp.global',
+  clientId: process.env.IDP_OIDC_CLIENT_ID!,
+  clientSecret: process.env.IDP_OIDC_CLIENT_SECRET!,
+});
+const authority = await introspection.introspect({
+  token: serverSession.accessToken,
+  subject: serverSession.idpSubject,
+  organizationId: requestedOrganizationId,
+});
+if (!authority.active) throw new Error('Organization access denied.');
+const currentRoles = authority.idp_global_authority.roles;
+```
+
+Every call generates a fresh nonce and validates the exact issuer, client,
+subject, organization, response shape, revisions, and current roles. The default
+request deadline is five seconds and the response limit is 16 KiB; redirects
+are rejected. `OidcIntrospectionError` exposes only a sanitized `code`:
+`invalid_request`, `invalid_response`, or `unavailable`. Deny the operation when
+introspection fails.
+
+An active result observes current authority while the provider holds its
+mutation fences. It is not a cached membership grant: membership can change
+after that observation. `exp` bounds token, session, and refresh-family expiry;
+it does not promise membership remains valid until then. Keep the application's
+existing login and principal binding and make a fresh observation for each
+operation requiring live authority. The response contains no identity profile
+or email-based organization inference.
+
 ### Server API Surface
 
 | API | Description |
@@ -298,6 +338,8 @@ the verification key by the JWT header `kid`, and reject unknown key IDs.
 | `SmartdataAccountStore` | Smartdata-backed account persistence and local password verification. |
 | `AccountAuthService` | Existing-account authentication orchestration for `local`, `idp.global`, and `auto`. |
 | `IdpGlobalServerClient` | Typed-socket client for idp.global password login, JWT refresh, `whoIs` lookup, backend JWT validation fetches, and JWT key/blocklist pushes. |
+| `OidcIntrospectionClient` | Confidential server client for an exact live organization authority observation. |
+| `OidcIntrospectionError` | Sanitized introspection failure with a stable error code. |
 | `IdpMfaRequiredError` | Password-login error carrying the MFA challenge token and available factor methods. |
 | `defaultIdpGlobalBaseUrl` | Default hosted server origin: `https://app.idp.global`. |
 | `PasswordHasher` | Static `hashPassword()` and `verifyPassword()` helpers using `scrypt:v1`. |
@@ -310,6 +352,8 @@ The server export includes these TypeScript types:
 
 | Type | Values or purpose |
 | --- | --- |
+| `IOidcIntrospectionClientOptions` | Exact HTTPS issuer, confidential client credentials, and optional deadline/response limits. |
+| `IOidcIntrospectionClientRequest` | Server-held access token, exact subject, and canonical organization ID. |
 | `TIdpAccountAuthSource` | `'local' | 'idp.global'` |
 | `TIdpAccountRole` | `'admin' | 'user'` |
 | `TIdpAccountStatus` | `'active' | 'disabled'` |
@@ -341,7 +385,7 @@ The test suite covers the server account store and auth service, browser transfe
 
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license.md](./license.md) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 

package/ts/00_commitinfo_data.ts

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

package/ts_server/classes.oidc-introspection-client.ts

@@ -0,0 +1,140 @@
+import * as plugins from './plugins.js';
+
+export interface IOidcIntrospectionClientOptions {
+  issuer: string;
+  clientId: string;
+  clientSecret: string;
+  timeoutMs?: number;
+  maxResponseBytes?: number;
+}
+
+export interface IOidcIntrospectionClientRequest {
+  token: string;
+  subject: string;
+  organizationId: string;
+}
+
+export class OidcIntrospectionError extends Error {
+  constructor(public readonly code: 'invalid_request' | 'invalid_response' | 'unavailable') {
+    super(`OIDC introspection ${code.replace(/_/g, ' ')}.`);
+    this.name = 'OidcIntrospectionError';
+  }
+}
+
+const exactString = (valueArg: unknown, maximumArg = 512): valueArg is string =>
+  typeof valueArg === 'string' && valueArg.length > 0 && valueArg.length <= maximumArg
+  && valueArg.trim() === valueArg;
+const record = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  valueArg !== null && typeof valueArg === 'object' && !Array.isArray(valueArg);
+const exactKeys = (valueArg: Record<string, unknown>, keysArg: string[]) =>
+  Object.keys(valueArg).length === keysArg.length && keysArg.every((keyArg) => Object.hasOwn(valueArg, keyArg));
+const revision = (valueArg: unknown): valueArg is number => Number.isSafeInteger(valueArg) && (valueArg as number) >= 0;
+const sortedUnique = (valuesArg: unknown): valuesArg is string[] => Array.isArray(valuesArg)
+  && valuesArg.length > 0 && valuesArg.every((valueArg, indexArg) => exactString(valueArg, 64)
+    && (indexArg === 0 || valuesArg[indexArg - 1] < valueArg));
+
+/** Server-only confidential client. Each result is one live observation, never a cached grant. */
+export class OidcIntrospectionClient {
+  readonly #issuer: string;
+  readonly #clientId: string;
+  readonly #authorization: string;
+  readonly #timeoutMs: number;
+  readonly #maxResponseBytes: number;
+
+  constructor(optionsArg: IOidcIntrospectionClientOptions) {
+    if (!optionsArg || !exactString(optionsArg.issuer, 2048) || !exactString(optionsArg.clientId)
+      || !exactString(optionsArg.clientSecret, 4096)) throw new OidcIntrospectionError('invalid_request');
+    let issuer: URL;
+    try { issuer = new URL(optionsArg.issuer); } catch { throw new OidcIntrospectionError('invalid_request'); }
+    const canonicalIssuer = issuer.origin + (issuer.pathname === '/' ? '' : issuer.pathname);
+    if (issuer.protocol !== 'https:' || issuer.username || issuer.password || issuer.search || issuer.hash
+      || issuer.pathname.includes('//') || issuer.pathname.endsWith('/') && issuer.pathname !== '/'
+      || canonicalIssuer !== optionsArg.issuer) throw new OidcIntrospectionError('invalid_request');
+    this.#timeoutMs = optionsArg.timeoutMs ?? 5000;
+    this.#maxResponseBytes = optionsArg.maxResponseBytes ?? 16384;
+    if (!Number.isSafeInteger(this.#timeoutMs) || this.#timeoutMs < 1 || this.#timeoutMs > 30000
+      || !Number.isSafeInteger(this.#maxResponseBytes) || this.#maxResponseBytes < 1 || this.#maxResponseBytes > 65536) {
+      throw new OidcIntrospectionError('invalid_request');
+    }
+    this.#issuer = canonicalIssuer;
+    this.#clientId = optionsArg.clientId;
+    // OAuth Basic components are form-encoded separately before joining with ':'.
+    const encode = (valueArg: string) => new URLSearchParams({ value: valueArg }).toString().slice(6);
+    this.#authorization = `Basic ${Buffer.from(`${encode(optionsArg.clientId)}:${encode(optionsArg.clientSecret)}`, 'utf8').toString('base64')}`;
+  }
+
+  public async introspect(requestArg: IOidcIntrospectionClientRequest): Promise<plugins.idpInterfaces.data.TOidcIntrospectionResponse> {
+    if (!requestArg || !exactString(requestArg.token, 16384) || !exactString(requestArg.subject)
+      || !exactString(requestArg.organizationId)) throw new OidcIntrospectionError('invalid_request');
+    // Capture bindings before crossing any asynchronous boundary.
+    const { token, subject, organizationId } = requestArg;
+    const nonce = plugins.crypto.randomBytes(32).toString('base64url');
+    const controller = new AbortController();
+    let timer: ReturnType<typeof setTimeout>;
+    const deadline = new Promise<never>((_resolveArg, rejectArg) => {
+      timer = setTimeout(() => { controller.abort(); rejectArg(new OidcIntrospectionError('unavailable')); }, this.#timeoutMs);
+    });
+    let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+    try {
+      const response = await Promise.race([fetch(`${this.#issuer}/oauth/introspect`, {
+        method: 'POST', redirect: 'error', credentials: 'omit', cache: 'no-store', signal: controller.signal,
+        headers: { authorization: this.#authorization, 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+        body: new URLSearchParams({ token, subject, organization_id: organizationId, nonce, token_type_hint: 'access_token' }),
+      }), deadline]);
+      if (response.status !== 200) throw new OidcIntrospectionError('unavailable');
+      if (response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/json'
+        || !response.headers.get('cache-control')?.toLowerCase().split(',').map((partArg) => partArg.trim()).includes('no-store')
+        || !response.body) throw new OidcIntrospectionError('invalid_response');
+      const contentLength = response.headers.get('content-length');
+      if (contentLength !== null && (!/^\d+$/.test(contentLength) || Number(contentLength) > this.#maxResponseBytes)) {
+        throw new OidcIntrospectionError('invalid_response');
+      }
+      reader = response.body.getReader();
+      const chunks: Uint8Array[] = [];
+      let size = 0;
+      while (true) {
+        const part = await Promise.race([reader.read(), deadline]);
+        if (part.done) break;
+        size += part.value.byteLength;
+        if (size > this.#maxResponseBytes) throw new OidcIntrospectionError('invalid_response');
+        chunks.push(part.value);
+      }
+      let value: unknown;
+      try { value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))); }
+      catch { throw new OidcIntrospectionError('invalid_response'); }
+      return this.validateResponse(value, subject, organizationId, nonce);
+    } catch (errorArg) {
+      if (errorArg instanceof OidcIntrospectionError) throw errorArg;
+      // Never include request, credentials, token, transport details or body in an error.
+      throw new OidcIntrospectionError('unavailable');
+    } finally {
+      clearTimeout(timer);
+      controller.abort();
+      if (reader) void reader.cancel().catch(() => undefined);
+    }
+  }
+
+  private validateResponse(valueArg: unknown, subjectArg: string, organizationIdArg: string, nonceArg: string): plugins.idpInterfaces.data.TOidcIntrospectionResponse {
+    const invalid = () => new OidcIntrospectionError('invalid_response');
+    if (!record(valueArg)) throw invalid();
+    if (valueArg.active === false && exactKeys(valueArg, ['active'])) return { active: false };
+    if (valueArg.active !== true || !exactKeys(valueArg,
+      ['active', 'token_type', 'client_id', 'scope', 'iss', 'aud', 'sub', 'exp', 'iat', 'idp_global_authority'])
+      || valueArg.token_type !== 'Bearer' || valueArg.client_id !== this.#clientId || valueArg.aud !== this.#clientId
+      || valueArg.iss !== this.#issuer || valueArg.sub !== subjectArg || !revision(valueArg.exp) || !revision(valueArg.iat)
+      || valueArg.exp <= Math.floor(Date.now() / 1000) || valueArg.iat > Math.floor(Date.now() / 1000)
+      || valueArg.exp <= valueArg.iat || typeof valueArg.scope !== 'string') throw invalid();
+    const scopes = valueArg.scope.split(' ');
+    if (!sortedUnique(scopes) || !scopes.includes('openid') || !scopes.includes('organizations')
+      || !scopes.every((scopeArg) => ['openid', 'profile', 'email', 'organizations', 'roles'].includes(scopeArg))) throw invalid();
+    const authority = valueArg.idp_global_authority;
+    if (!record(authority) || !exactKeys(authority, ['version', 'nonce', 'subject_revision', 'organization_id',
+      'organization_revision', 'membership_id', 'membership_revision', 'app_connection_id', 'app_connection_revision', 'roles'])
+      || authority.version !== 1 || authority.nonce !== nonceArg || authority.organization_id !== organizationIdArg
+      || !revision(authority.subject_revision) || !revision(authority.organization_revision)
+      || !revision(authority.membership_revision) || !revision(authority.app_connection_revision)
+      || !exactString(authority.membership_id) || !exactString(authority.app_connection_id) || !sortedUnique(authority.roles)
+      || !authority.roles.every((roleArg) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(roleArg))) throw invalid();
+    return valueArg as unknown as plugins.idpInterfaces.data.IOidcActiveIntrospectionResponse;
+  }
+}

package/ts_server/index.ts

@@ -3,4 +3,5 @@ export * from './classes.account-auth-service.js';
 export * from './classes.account-doc.js';
 export * from './classes.account-store.js';
 export * from './classes.idp-global-server-client.js';
+export * from './classes.oidc-introspection-client.js';
 export * from './classes.password-hasher.js';