@collective-intelligence/external-apps-server-sdk 0.1.5 → 0.1.7

package/README.md

@@ -1204,7 +1204,100 @@ The store persists only hashed opaque-cookie state, token grants and revisions;
 the browser receives a `Secure`, `HttpOnly`, `SameSite=Lax` host cookie. Every
 session lookup revalidates the short-lived CI identity. Revoked or expired CI
 access ends application authorization on the next validation. A confidential
-OAuth client may supply `clientSecret`; a public PKCE client omits it.
+OAuth client may supply `clientSecret`; a public PKCE client omits it. The
+client type decides how long the User session lasts; see
+[Session lifetime and renewal](#session-lifetime-and-renewal).
+
+### Session lifetime and renewal
+
+`sessionTtlSeconds` sets the Session lifetime: the time from sign-in to the
+end of the User session. The default is `86400` (one day). The SDK accepts an
+integer from `300` to `604800` (seven days).
+
+A User session lasts its Session lifetime only with renewal. Without renewal,
+the User session ends when its Access token expires, 300 seconds after
+sign-in, whatever the value of `sessionTtlSeconds`. The Access token lifetime
+is always 300 seconds. There is no setting for it.
+
+Renewal needs these three conditions:
+
+- The external Application is confidential at CI.
+- `createFederatedAuth` gets the `clientSecret` of that Application.
+- The user signed in after the upgrade to an SDK version that renews. An
+  earlier cookie or store record holds no Renewal credential. That User
+  session ends at its Access token expiry.
+
+When the three conditions are true, CI returns a Renewal credential at
+sign-in. On the wire it is the OAuth `refresh_token`. The SDK keeps it in the
+session record and uses it to get a new Access token with no browser redirect.
+The application code does not change.
+
+A public client has no client secret, so it gets no Renewal credential. Its
+User session lasts 300 seconds. To continue, the application sends the browser
+to `<basePath>/login` again, as before. A `fetch` call or a form post cannot
+follow that redirect. For a public client, `createFederatedAuth` still accepts
+each `sessionTtlSeconds` value in the range and gives no warning.
+
+`getSession`, `getAccessToken`, `getEntityContext` and
+`GET <basePath>/session` are the session lookups. With renewal, each lookup
+first gets a new Access token when the current one is expired or expires in 30
+seconds or less. Then it checks the current identity at `/oauth/identity`. A
+lookup never returns an expired Access token. Lookups at the same time share
+one renewal request.
+
+The SDK writes the cookie or the store record one time, at sign-in. A renewal
+writes no cookie and no store record. A renewed Access token stays only in
+process memory. Each `createFederatedAuth` instance keeps at most 5000 of
+them, separate from each other instance. A restart loses them, and the next
+lookup renews again.
+
+A Federated authorization is the record that CI keeps of one sign-in to one
+external Application. It lasts at most 604800 seconds from sign-in, and never
+longer than the CI session of the user. The User session ends at the earlier
+of these two times:
+
+- sign-in plus `sessionTtlSeconds`;
+- the end of the Federated authorization.
+
+`expiresAt` of the session reports that end. It is the same at each lookup,
+because a lookup does not extend the User session. Without a Renewal
+credential, `expiresAt` stays the Access token expiry.
+
+A lookup has one of three results:
+
+- **A session.** CI accepts the identity, after a renewal when one is
+  necessary.
+- **`null`**, and `401` on `GET <basePath>/session`. CI refuses the user or
+  the Federated authorization: it answers `invalid_grant` to the renewal, or
+  it refuses the identity. The result is also `null` after the end of the User
+  session. Send the user to the login route.
+- **`ApplicationUserAuthUnavailableError`**, and `503` on
+  `GET <basePath>/session`. The client secret is wrong or rotated
+  (`invalid_client`), CI gives another OAuth error, or CI does not answer. The
+  User session stays. It returns when the fault is corrected, with no
+  sign-in.
+
+A renewal applies the same admission rule as `/oauth/identity`:
+
+- the external Application is enabled;
+- the CI session is live;
+- the user is not banned and is still admitted to the Organization, which
+  today means the Organization membership of the user and its role;
+- the scopes of the sign-in are still allowed.
+
+A refusal ends nothing. When the condition is corrected, the same Renewal
+credential renews again. A Federated authorization ends for good only by one
+of these events: logout, a new sign-in in the same User session, its limit of
+604800 seconds, or the end of the CI session.
+
+`POST <basePath>/logout` presents the Renewal credential to CI, and CI ends
+the Federated authorization. If CI does not answer, the route answers `503`
+and still clears the User session. That Federated authorization then ends at
+its limit or with its CI session.
+
+An application that does not use this SDK finds the CI token and logout
+contract in
+[Access token renewal](../../../docs/architecture/external-app-gateway.md#access-token-renewal).
 
 ### Configure from the CLI enrollment
 

package/dist/admin.d.ts

@@ -368,6 +368,11 @@ export type UpdatePackageInstallationRequestEncoded = {
 			};
 		};
 	};
+	variables?: {
+		[key: string]: {
+			link: string;
+		} | unknown;
+	};
 };
 export type PackageOperationAccepted2 = {
 	operationId: string;
@@ -457,6 +462,12 @@ export type ExtensionReleaseManifestEncoded = {
 		size: number;
 		[key: string]: unknown | string | string | "backend" | "dashboard" | "studio" | number | undefined;
 	}>;
+	media?: Array<{
+		digest: string;
+		path: string;
+		size: number;
+		[key: string]: unknown | string | string | number;
+	}>;
 	package: {
 		fqn: string;
 		version: string;
@@ -492,6 +503,11 @@ export type ExtensionReleaseManifestEncoded = {
 		host: "backend" | "dashboard" | "studio";
 		size: number;
 		[key: string]: unknown | string | string | "backend" | "dashboard" | "studio" | number | undefined;
+	}> | Array<{
+		digest: string;
+		path: string;
+		size: number;
+		[key: string]: unknown | string | string | number;
 	}> | {
 		fqn: string;
 		version: string;
@@ -1537,6 +1553,11 @@ export type ExtensionPackagesInstallData = {
 				};
 			};
 		};
+		variables?: {
+			[key: string]: {
+				link: string;
+			} | unknown;
+		};
 	};
 	headers: {
 		authorization?: string;
@@ -2904,6 +2925,7 @@ export type OrganizationsGetData = {
 };
 export type OrganizationsUpdateData = {
 	body: {
+		applicationConsentRequired?: boolean;
 		availableLanguages?: Array<string>;
 		coverFileId?: string | null;
 		defaultKnowledgePropertyCase?: "camel_case" | "snake_case";
@@ -3737,6 +3759,7 @@ export type OrganizationExternalAppsListResponses = {
 	200: {
 		data: Array<{
 			allowedOrigins: Array<string>;
+			applicationConsent: "inherit" | "ask" | "skip";
 			applicationType: "public" | "confidential";
 			audience: string;
 			clientId: string;
@@ -3774,6 +3797,7 @@ export type OrganizationExternalAppsCreateResponses = {
 	201: {
 		application: {
 			allowedOrigins: Array<string>;
+			applicationConsent: "inherit" | "ask" | "skip";
 			applicationType: "public" | "confidential";
 			audience: string;
 			clientId: string;
@@ -3805,6 +3829,7 @@ export type OrganizationExternalAppsCreateResponses = {
 	} | {
 		application: {
 			allowedOrigins: Array<string>;
+			applicationConsent: "inherit" | "ask" | "skip";
 			applicationType: "public" | "confidential";
 			audience: string;
 			clientId: string;
@@ -3843,6 +3868,7 @@ export type OrganizationExternalAppsGetResponses = {
 	 */
 	200: {
 		allowedOrigins: Array<string>;
+		applicationConsent: "inherit" | "ask" | "skip";
 		applicationType: "public" | "confidential";
 		audience: string;
 		clientId: string;
@@ -3875,6 +3901,7 @@ export type OrganizationExternalAppsGetResponse = OrganizationExternalAppsGetRes
 export type OrganizationExternalAppsUpdateData = {
 	body: {
 		allowedOrigins?: Array<string>;
+		applicationConsent?: "inherit" | "ask" | "skip";
 		audience?: string;
 		enabled?: boolean;
 		name?: string;
@@ -3914,6 +3941,7 @@ export type OrganizationExternalAppsRotateCredentialResponses = {
 	200: {
 		application: {
 			allowedOrigins: Array<string>;
+			applicationConsent: "inherit" | "ask" | "skip";
 			applicationType: "public" | "confidential";
 			audience: string;
 			clientId: string;
@@ -4655,18 +4683,26 @@ declare const createAdministrationApi: (client: Client$1) => {
 			type: string;
 		}>;
 		listSsoProviders: (options: Pick<Options$1<OrganizationAuthenticationListProvidersData, true, unknown>, "query" | "body" | "headers" | "path">) => Promise<{
-			connectionId: string | null;
-			connectionName: string | null;
-			connectionStatus: string | null;
-			defaultRole: "organization_admin" | "organization_user";
-			domains: Array<string>;
-			enabled: boolean;
-			id: string;
-			provisionMembers: boolean;
-			testedAt: string | null;
-			testedEmail: string | null;
-			type: string;
-		}[]>;
+			applicationConsentRequired: boolean;
+			managedSettings: {
+				keys: Array<"identity.name" | "identity.companyDomains" | "branding.logo" | "branding.icon" | "branding.cover" | "authentication.password" | "authentication.otp" | "authentication.sso" | "authentication.applicationConsent" | "locale.defaultLanguage" | "locale.languages" | "locale.timezone" | "governance.accessAuditRetentionMonths" | "governance.maxGroupHierarchyDepth">;
+				packageFqn: string;
+				readonly: boolean;
+			} | null;
+			providers: Array<{
+				connectionId: string | null;
+				connectionName: string | null;
+				connectionStatus: string | null;
+				defaultRole: "organization_admin" | "organization_user";
+				domains: Array<string>;
+				enabled: boolean;
+				id: string;
+				provisionMembers: boolean;
+				testedAt: string | null;
+				testedEmail: string | null;
+				type: string;
+			}>;
+		}>;
 		testSsoProvider: (options: Pick<Options$1<OrganizationAuthenticationStartSsoTestData, true, unknown>, "query" | "body" | "headers" | "path">) => Promise<{
 			callbackUrl: string;
 			url: string;
@@ -6985,6 +7021,7 @@ declare const createAdministrationApi: (client: Client$1) => {
 			teardownId: string;
 		}>;
 		get: (options: Pick<Options$1<OrganizationsGetData, true, unknown>, "query" | "body" | "headers" | "path">) => Promise<{
+			applicationConsentRequired: boolean;
 			availableLanguages: Array<string>;
 			coverFileId: string | null;
 			createdAt: string | null;
@@ -6996,6 +7033,11 @@ declare const createAdministrationApi: (client: Client$1) => {
 			iconFileId: string | null;
 			id: string;
 			logoFileId: string | null;
+			managedSettings?: {
+				keys: Array<"identity.name" | "identity.companyDomains" | "branding.logo" | "branding.icon" | "branding.cover" | "authentication.password" | "authentication.otp" | "authentication.sso" | "authentication.applicationConsent" | "locale.defaultLanguage" | "locale.languages" | "locale.timezone" | "governance.accessAuditRetentionMonths" | "governance.maxGroupHierarchyDepth">;
+				packageFqn: string;
+				readonly: boolean;
+			} | null;
 			maxGroupHierarchyDepth: number;
 			meta: string | null;
 			name: string;
@@ -7017,6 +7059,7 @@ declare const createAdministrationApi: (client: Client$1) => {
 		}>;
 		list: (options: Pick<Options$1<OrganizationsSearchData, true, unknown>, "query" | "body" | "headers" | "path">) => Promise<{
 			data: Array<{
+				applicationConsentRequired: boolean;
 				availableLanguages: Array<string>;
 				coverFileId: string | null;
 				createdAt: string | null;
@@ -7028,6 +7071,11 @@ declare const createAdministrationApi: (client: Client$1) => {
 				iconFileId: string | null;
 				id: string;
 				logoFileId: string | null;
+				managedSettings?: {
+					keys: Array<"identity.name" | "identity.companyDomains" | "branding.logo" | "branding.icon" | "branding.cover" | "authentication.password" | "authentication.otp" | "authentication.sso" | "authentication.applicationConsent" | "locale.defaultLanguage" | "locale.languages" | "locale.timezone" | "governance.accessAuditRetentionMonths" | "governance.maxGroupHierarchyDepth">;
+					packageFqn: string;
+					readonly: boolean;
+				} | null;
 				maxGroupHierarchyDepth: number;
 				meta: string | null;
 				name: string;

package/dist/auth/federated.d.ts

@@ -125,6 +125,10 @@ declare class FederatedAuthRejectedError extends Error {
 export type FederatedGrant = Readonly<{
 	accessToken: string;
 	expiresAt: number;
+	/** Renewal credential of the Federated authorization; set together with `refreshExpiresAt`. */
+	refreshToken?: string;
+	/** Epoch milliseconds at which the Renewal credential stops; set together with `refreshToken`. */
+	refreshExpiresAt?: number;
 }>;
 export type FederatedLogin = Readonly<{
 	status: "idle";