@adonis-agora/authkit-client 1.0.0-rc.1 → 1.0.0-rc.3

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @adonis-agora/authkit-client
 
+## 1.0.0-rc.3
+
+### Patch Changes
+
+- fix(deps): update dependency jose to v6.2.16 ([#454](https://github.com/DavideCarvalho/adonis-agora-authkit/issues/454))
+
+## 1.0.0-rc.2
+
+### Minor Changes
+
+- [#460](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/460) [`1858ee8`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/1858ee837bb4edcf0578f86d224693ac9a86a495) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Service tenants: a client can act as one partition of another service, such as a durable control plane.
+  
+  - `serviceTenants: { resources: { 'urn:agora:durable': { expiresIn: 600 } } }` in `config/authkit.ts` declares the resources (RFC 8707) that issue service-tenant tokens: JWT access tokens (RFC 9068) with `aud` = the resource and the client's `partition` and `capabilities` as claims.
+  - A service-tenant client is confidential, uses only `client_credentials` and has no redirect URIs. Create and edit it from the console (**Service tenant** kind), the Admin API and the SDKs (`serviceTenant: { partition, capabilities? }`), or `node ace authkit:clients:create --partition=acme --capability=reports`.
+  - Any client can now be disabled and enabled again (console, `POST /clients/:id/disable|enable`, SDK `clients.disable/enable`): the token endpoint answers `invalid_client` from the next request on.
+  - `authkitTenantVerifier()` (authkit-server) verifies those tokens against the local issuer and keys and returns `{ tenant, capabilities }`; `authkitTenantToken({ issuer, clientId, clientSecret, resource })` (authkit-client) fetches, caches and refreshes them on the tenant side. Both fit durable's `verifyTenant` and `tenant.token` as a function or a class, without depending on durable.
+  - New audit events: `client.disabled`, `client.enabled`, `service_tenant.token_issued`.
+  - Access-token verification (`oidcBearerGuard`, in-process and remote) now refuses a token whose `sub` is a client (a `client_credentials` token), so a service-tenant token never authenticates a user.
+
 ## 1.0.0-rc.1
 
 ### Major Changes

package/build/index.d.ts

@@ -36,6 +36,7 @@ export type { PostLoginRedirects, RegisterOidcClientOptions, } from './src/regis
 export { registerOidcClient } from './src/register_oidc_client.js';
 export type { LucidRevocationStoreOptions, RevocationStore, } from './src/revocation/revocation_store.js';
 export { DEFAULT_REVOCATION_TABLE, lucidRevocationStore, } from './src/revocation/revocation_store.js';
+export { AuthkitTenantToken, type AuthkitTenantTokenFn, type AuthkitTenantTokenOptions, authkitTenantToken, TenantTokenError, } from './src/tenant_token.js';
 export type { TokenSet } from './src/types.js';
 export type { ClaimsUser, ResolveUserContext, UserinfoResolverOptions, } from './src/user_resolvers.js';
 export { createUserinfoResolver, identityToUser, } from './src/user_resolvers.js';

package/build/index.js

@@ -19,5 +19,6 @@ export { default as RequireOrgMiddleware } from './src/middleware/require_org_mi
 export { buildAuthorizeUrl, buildEndSessionUrl, exchangeCode, exchangeToken, generatePkce, refreshTokens, } from './src/oidc_login.js';
 export { registerOidcClient } from './src/register_oidc_client.js';
 export { DEFAULT_REVOCATION_TABLE, lucidRevocationStore, } from './src/revocation/revocation_store.js';
+export { AuthkitTenantToken, authkitTenantToken, TenantTokenError, } from './src/tenant_token.js';
 export { createUserinfoResolver, identityToUser, } from './src/user_resolvers.js';
 export { verifyJwtAccessToken } from './src/verify_access_token.js';

package/build/src/tenant_token.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The token a service tenant presents to its control plane (e.g. durable's
+ * `tenant.token`): a `client_credentials` JWT access token for one resource (RFC 8707),
+ * fetched from the authkit issuer, cached, and refreshed before it expires.
+ */
+export interface AuthkitTenantTokenOptions {
+    /** Issuer URL of the authkit server (the `issuer` in its config/authkit.ts). */
+    issuer: string;
+    /** Client id of the service-tenant client. */
+    clientId: string;
+    /** Client secret of the service-tenant client. */
+    clientSecret: string;
+    /**
+     * Resource indicator the token is for (one of `serviceTenants.resources` on the
+     * server). Optional when the server declares exactly one.
+     */
+    resource?: string;
+    /** Space-separated scopes to request. Default: none. */
+    scope?: string;
+    /** Refresh this many seconds before the token expires. Default: 60. */
+    refreshSkewSec?: number;
+    /** Token endpoint. Default: `token_endpoint` from the issuer's discovery document. */
+    tokenEndpoint?: string;
+    /** Custom `fetch` (proxy, tests). Default: the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Abort a token request after this many ms. Default: 10 000. */
+    timeoutMs?: number;
+}
+/** Thrown when the token endpoint refuses the credentials or cannot be reached. */
+export declare class TenantTokenError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Fetches and caches a service-tenant token. One request at a time (concurrent callers
+ * share it); after a failure, callers get the same error until a backoff (500 ms,
+ * doubling, capped at 30 s) runs out, unless the cached token is still valid, which is
+ * then served instead. Never logs or exposes the secret or the token in errors.
+ *
+ * Satisfies durable's `TenantCredentialsContract` (`token()`).
+ */
+export declare class AuthkitTenantToken {
+    #private;
+    constructor(options: AuthkitTenantTokenOptions);
+    /** The current token: cached while fresh, fetched (single-flight) otherwise. */
+    token(): Promise<string>;
+    /** Drops the cached token: the next `token()` fetches a new one. */
+    reset(): void;
+}
+/** A token provider usable both as a function and as an object with `token()`. */
+export type AuthkitTenantTokenFn = (() => Promise<string>) & {
+    token(): Promise<string>;
+    reset(): void;
+};
+/**
+ * The token function for a service-tenant process:
+ *
+ * ```ts
+ * // config/durable.ts (tenant process)
+ * tenant: {
+ *   token: authkitTenantToken({
+ *     issuer: env.get('AUTHKIT_ISSUER'),
+ *     clientId: env.get('TENANT_CLIENT_ID'),
+ *     clientSecret: env.get('TENANT_CLIENT_SECRET'),
+ *     resource: 'urn:agora:durable',
+ *   }),
+ * }
+ * ```
+ *
+ * The result is a function (`() => Promise<string>`) that also has `token()` (durable's
+ * `TenantCredentialsContract`).
+ */
+export declare function authkitTenantToken(options: AuthkitTenantTokenOptions): AuthkitTenantTokenFn;

package/build/src/tenant_token.js

@@ -0,0 +1,190 @@
+/**
+ * The token a service tenant presents to its control plane (e.g. durable's
+ * `tenant.token`): a `client_credentials` JWT access token for one resource (RFC 8707),
+ * fetched from the authkit issuer, cached, and refreshed before it expires.
+ */
+import { discoverEndpoints } from './discovery.js';
+/** Thrown when the token endpoint refuses the credentials or cannot be reached. */
+export class TenantTokenError extends Error {
+    status;
+    code;
+    constructor(message, status, code, options) {
+        super(message, options);
+        this.status = status;
+        this.code = code;
+        this.name = 'TenantTokenError';
+    }
+}
+const MIN_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 30_000;
+/**
+ * Fetches and caches a service-tenant token. One request at a time (concurrent callers
+ * share it); after a failure, callers get the same error until a backoff (500 ms,
+ * doubling, capped at 30 s) runs out, unless the cached token is still valid, which is
+ * then served instead. Never logs or exposes the secret or the token in errors.
+ *
+ * Satisfies durable's `TenantCredentialsContract` (`token()`).
+ */
+export class AuthkitTenantToken {
+    #options;
+    #cached;
+    #inflight;
+    #failures = 0;
+    #retryAt = 0;
+    #lastError;
+    /** Bumped by `reset()`: a fetch started before it does not touch the new state. */
+    #generation = 0;
+    constructor(options) {
+        if (!options?.issuer || !options.clientId || !options.clientSecret) {
+            throw new TypeError('authkitTenantToken: issuer, clientId and clientSecret are required');
+        }
+        this.#options = options;
+    }
+    /** The current token: cached while fresh, fetched (single-flight) otherwise. */
+    async token() {
+        const now = Date.now();
+        const cached = this.#cached;
+        if (cached && now < cached.refreshAt)
+            return cached.value;
+        let pending = this.#inflight;
+        if (!pending) {
+            if (now < this.#retryAt) {
+                if (cached && now < cached.expiresAt)
+                    return cached.value;
+                throw this.#lastError;
+            }
+            const started = this.#fetch().finally(() => {
+                if (this.#inflight === started)
+                    this.#inflight = undefined;
+            });
+            this.#inflight = started;
+            pending = started;
+        }
+        // Still-valid token while refreshing early: a failed refresh breaks no caller,
+        // whether it started the refresh or joined it.
+        if (cached && now < cached.expiresAt) {
+            return pending.catch(() => {
+                if (Date.now() < cached.expiresAt)
+                    return cached.value;
+                throw this.#lastError;
+            });
+        }
+        return pending;
+    }
+    /** Drops the cached token: the next `token()` fetches a new one. */
+    reset() {
+        this.#generation += 1;
+        this.#cached = undefined;
+        this.#inflight = undefined;
+        this.#failures = 0;
+        this.#retryAt = 0;
+        this.#lastError = undefined;
+    }
+    async #fetch() {
+        const generation = this.#generation;
+        try {
+            const { value, cached } = await this.#request();
+            if (generation !== this.#generation)
+                return value;
+            this.#cached = cached;
+            this.#failures = 0;
+            this.#retryAt = 0;
+            this.#lastError = undefined;
+            return value;
+        }
+        catch (error) {
+            if (generation !== this.#generation)
+                throw error;
+            this.#failures += 1;
+            const delay = Math.min(MAX_BACKOFF_MS, MIN_BACKOFF_MS * 2 ** (this.#failures - 1));
+            this.#retryAt = Date.now() + delay;
+            this.#lastError = error;
+            throw error;
+        }
+    }
+    async #request() {
+        const o = this.#options;
+        const doFetch = o.fetch ?? globalThis.fetch;
+        let endpoint = o.tokenEndpoint;
+        if (!endpoint) {
+            try {
+                endpoint = (await discoverEndpoints(o.issuer, {
+                    onError: 'fallback',
+                    ...(o.fetch ? { fetchImpl: o.fetch } : {}),
+                })).tokenEndpoint;
+            }
+            catch (cause) {
+                throw new TenantTokenError('could not resolve the token endpoint', undefined, undefined, {
+                    cause,
+                });
+            }
+        }
+        const body = new URLSearchParams({ grant_type: 'client_credentials' });
+        if (o.resource)
+            body.set('resource', o.resource);
+        if (o.scope)
+            body.set('scope', o.scope);
+        // RFC 6749 §2.3.1: form-urlencode id and secret before Basic.
+        const basic = Buffer.from(`${encodeURIComponent(o.clientId)}:${encodeURIComponent(o.clientSecret)}`).toString('base64');
+        const startedAt = Date.now();
+        let res;
+        try {
+            res = await doFetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    authorization: `Basic ${basic}`,
+                    'content-type': 'application/x-www-form-urlencoded',
+                    accept: 'application/json',
+                },
+                body: body.toString(),
+                signal: AbortSignal.timeout(o.timeoutMs ?? 10_000),
+            });
+        }
+        catch (cause) {
+            throw new TenantTokenError(`token request to ${endpoint} failed: ${cause?.name ?? 'Error'}`, undefined, undefined, { cause });
+        }
+        let json = {};
+        try {
+            json = (await res.json());
+        }
+        catch {
+            // A non-JSON body is reported by status below.
+        }
+        if (!res.ok) {
+            const code = typeof json.error === 'string' ? json.error : undefined;
+            const description = typeof json.error_description === 'string' ? `: ${json.error_description}` : '';
+            throw new TenantTokenError(`token endpoint answered ${res.status}${code ? ` ${code}` : ''}${description}`, res.status, code);
+        }
+        const value = json.access_token;
+        if (typeof value !== 'string' || !value) {
+            throw new TenantTokenError('token endpoint answered without an access_token', res.status);
+        }
+        const expiresIn = typeof json.expires_in === 'number' && json.expires_in > 0 ? json.expires_in : 60;
+        const expiresAt = startedAt + expiresIn * 1000;
+        const skew = Math.min((o.refreshSkewSec ?? 60) * 1000, (expiresIn * 1000) / 2);
+        return { value, cached: { value, expiresAt, refreshAt: expiresAt - skew } };
+    }
+}
+/**
+ * The token function for a service-tenant process:
+ *
+ * ```ts
+ * // config/durable.ts (tenant process)
+ * tenant: {
+ *   token: authkitTenantToken({
+ *     issuer: env.get('AUTHKIT_ISSUER'),
+ *     clientId: env.get('TENANT_CLIENT_ID'),
+ *     clientSecret: env.get('TENANT_CLIENT_SECRET'),
+ *     resource: 'urn:agora:durable',
+ *   }),
+ * }
+ * ```
+ *
+ * The result is a function (`() => Promise<string>`) that also has `token()` (durable's
+ * `TenantCredentialsContract`).
+ */
+export function authkitTenantToken(options) {
+    const source = new AuthkitTenantToken(options);
+    const token = () => source.token();
+    return Object.assign(token, { token, reset: () => source.reset() });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-client",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.3",
   "description": "AdonisJS OIDC/OAuth2 relying-party (client) toolkit: session-based authentication against an OpenID Connect identity provider, with JWT/PAT user resolvers and OpenTelemetry metrics.",
   "license": "MIT",
   "author": "dudousxd",
@@ -78,10 +78,10 @@
   },
   "dependencies": {
     "@adonis-agora/authkit-core": "1.0.0-rc.0",
-    "jose": "6.2.15"
+    "jose": "6.2.16"
   },
   "devDependencies": {
-    "@adonis-agora/authkit-server": "1.0.0-rc.1",
+    "@adonis-agora/authkit-server": "1.0.0-rc.4",
     "@adonis-agora/resilience": "0.4.3",
     "@adonisjs/auth": "10.1.0",
     "@adonisjs/core": "7.6.0",