@oneidentity/safeguard 1.0.5 → 8.0.0-pre36948

package/README.md

@@ -1,279 +1,408 @@
-# safeguard.js
-One Identity Safeguard JavaScript SDK
-
------------
-
-<p align="center">
-<i>Check out our <a href="samples">sample projects</a> to get started with your own custom integration to Safeguard!</i>
-</p>
-
------------
-
-## Support
-
-One Identity open source projects are supported through [One Identity GitHub issues](https://github.com/OneIdentity/safeguard.js/issues) and the [One Identity Community](https://www.oneidentity.com/community/). This includes all scripts, plugins, SDKs, modules, code snippets or other solutions. For assistance with any One Identity GitHub project, please raise a new Issue on the [One Identity GitHub project](https://github.com/OneIdentity/safeguard.js/issues) page. You may also visit the [One Identity Community](https://www.oneidentity.com/community/) to ask questions.  Requests for assistance made through official One Identity Support will be referred back to GitHub and the One Identity Community forums where those requests can benefit all users.  
-
-If you would like to add to safeguard.js? See the [developer guide](https://github.com/OneIdentity/safeguard.js/blob/master/src/README.md).
-
-## Introduction
-
-All functionality in Safeguard is available via the Safeguard API. There is
-nothing that can be done in the Safeguard UI that cannot also be performed
-using the Safeguard API programmatically.
-
-safeguard.js is provided to facilitate calling the Safeguard API from JavaScript.
-It is meant to remove the complexity of dealing with authentication via
-Safeguard's embedded secure token service (STS). The basic usage is to call
-`connect()` to establish a connection to Safeguard, then you can call
-`invoke()` multiple times using the same authenticated connection.
-
-safeguard.js also provides an easy way to call Safeguard A2A from JavaScript. The A2A service requires client certificate authentication for retrieving passwords for application integration. When Safeguard A2A is properly configured, specified passwords can be retrieved with a single method call without requiring access request workflow approvals. Safeguard A2A is protected by API keys and IP restrictions in addition to client certificate authentication.
-
-safeguard.js includes an SDK for listening to Safeguard's powerful, real-time event notification system. Safeguard provides role-based event notifications via SignalR to subscribed clients. If a Safeguard user is an Asset Administrator events related to the creation, modification, or deletion of Assets and Asset Accounts will be sent to that user. When used with a certificate user, this provides an opportunity for reacting programmatically to any data modification in Safeguard. Events are also supported for access request workflow and for A2A password changes.
-
-## Installation
-
-This javascript module is published to the [npm registry](https://www.npmjs.com/package/@oneidentity/safeguard) to make it as easy as possible to install.
-
-```Bash
-> npm install @oneidentity/safeguard
-```
-
-## Getting Started
-
-A simple code example for calling the Safeguard API for authentication through the standard Safeguard STS login page:
-
-```JavaScript
-// Browser Example
-SafeguardJs.connectRsts('safeguard.sample.corp', `${window.location.protocol}//${window.location.host}${window.location.pathname}`)
-.then((connection) => {
-    connection.invoke(SafeguardJs.Services.CORE, SafeguardJs.HttpMethods.GET, 'v3/Me')
-    .then((results) => {
-        console.log(results);
-    });
-});
-```
-
-For Node.JS, password authentication is available:
-
-```JavaScript
-// Node.JS Example
-SafeguardJs.addCAFromFile('ssl/ca.pem');
-let connection = await SafeguardJs.connectPassword('safeguard.sample.corp', 'myuser', 'mypassword');
-```
-
-Password authentication to an external provider is as follows:
-
-```JavaScript
-// Node.JS Example
-SafeguardJs.addCAFromFile('ssl/ca.pem');
-let connection = await SafeguardJs.connectPassword('safeguard.sample.corp', 'myuser', 'mypassword', 'myexternalprovider');
-```
-
-Client certificate authentication is also available. This can be done either using a PFX certificate file or a PEM and KEY.
-
-```JavaScript
-// Node.JS Example
-SafeguardJs.addCAFromFile('ssl/ca.pem');
-let connection = await SafeguardJs.connectCertificateFromFiles('safeguard.sample.corp', 'ssl/certificateuser.pem', 'ssl/certificateuser.key', null, 'password');
-```
-
-```JavaScript
-// Node.JS Example
-SafeguardJs.addCAFromFile('ssl/ca.pem');
-let connection = await SafeguardJs.connectCertificateFromFiles('safeguard.sample.corp', null, null, 'ssl/certificateuser.pfx', 'password');
-```
-
-Client certificate authentication to an external provider is also available. This can again be done either using a PFX certificate file or a PEM and KEY.
-
-```JavaScript
-// Node.JS Example
-SafeguardJs.addCAFromFile('ssl/ca.pem');
-SafeguardJs.addCAFromFile('ssl/ca2.pem'); // additional CA for external provider
-let connection = await SafeguardJs.connectCertificateFromFiles('safeguard.sample.corp', 'ssl/certificateuser.pem', 'ssl/certificateuser.key', null, 'password', 'myexternalprovider');
-```
-
-```JavaScript
-// Node.JS Example
-SafeguardJs.addCAFromFile('ssl/ca.pem');
-SafeguardJs.addCAFromFile('ssl/ca2.pem'); // additional CA for external provider
-let connection = await SafeguardJs.connectCertificateFromFiles('safeguard.sample.corp', null, null, 'ssl/certificateuser.pfx', 'password', 'myexternalprovider');
-```
-
-A connection can also be made anonymously 
-
-```JavaScript
-// Browser Example
-let connection = SafeguardJs.connectAnonymous('safeguard.sample.corp');
-```
-
-```JavaScript
-// Node.JS Example
-let localStorage = new require('src/LocalStorage').LocalStorage;
-SafeguardJs.addCAFromFile('ca.pem');
-let connection = SafeguardJs.connectAnonymous('safeguard.sample.corp', null, localStorage);
-```
-
-Authentication is also possible using an existing Safeguard API token:
-
-```JavaScript
-// Browser Example
-let apiToken = GetTokenSomehow();
-let connection = SafeguardJs.connectAnonymous('safeguard.sample.corp');
-SafeguardJs.Storage.setUserToken(apiToken);
-```
-
-```JavaScript
-// Node.JS Example
-let apiToken = GetTokenSomehow();
-let localStorage = new require('src/LocalStorage').LocalStorage;
-
-let connection = SafeguardJs.connectAnonymous('safeguard.sample.corp', null, localStorage);
-SafeguardJs.Storage.setUserToken(apiToken);
-```
-
-Two-factor authentication can only be performed through `connectRsts()`, so that the secure token service can use the browser agent to redirect you to multiple authentication providers.
-
-Most of the examples above use the default SafeguardJs.Storage locations. For RSTS and anonymous connections, SessionStorage is used to persist authentication information. For password and certificate authentication, LocalStorage is used, which is an in memory storage. By writing a new SafeguardJs storage class, these authentication values can be stored elsewhere. Further information can be found <a href="src/SessionStorage.js">here</a> for session storage and <a href="src/LocalStorage.js">here</a> for local storage.
-
-## Getting Started With A2A
-
-Once you have configured your A2A registration in Safeguard you can retrieve an A2A password or private key using a certificate and api key.
-
-To retrieve a password via A2A:
-
-```JavaScript
-// Node.JS Example
-SafeguardJs.addCAFromFile('ssl/ca.pem');
-let password = await SafeguardJs.a2aGetCredentialFromFiles('safeguard.sample.corp', 'myapikey', SafeguardJs.A2ATypes.PASSWORD, null, 'ssl/certificateuser.pem', 'ssl/certificateuser.key', 'password');
-```
-
-To retrieve a private key via A2A:
-
-```JavaScript
-// Node.JS Example
-SafeguardJs.addCAFromFile('ssl/ca.pem');
-let privateKey = await SafeguardJs.a2aGetCredentialFromFiles('safeguard.sample.corp', 'myapikey', SafeguardJs.A2ATypes.PRIVATEKEY, SafeguardJs.SshKeyFormats.OPENSSH, 'ssl/certificateuser.pem', 'ssl/certificateuser.key', 'password');
-```
-
-## About the Safeguard API
-
-The Safeguard API is a REST-based Web API. Safeguard API endpoints are called
-using HTTP operators and JSON (or XML) requests and responses. The Safeguard API
-is documented using Swagger. You may use Swagger UI to call the API directly or
-to read the documentation about URLs, parameters, and payloads.
-
-To access the Swagger UI use a browser to navigate to:
-`https://<address>/service/<service>/swagger`
-
-- `<address>` = Safeguard network address
-- `<service>` = Safeguard service to use
-
-The Safeguard API is made up of multiple services: core, appliance, notification,
-and a2a.
-
-|Service|Description|
-|-|-|
-|core|Most product functionality is found here. All cluster-wide operations: access request workflow, asset management, policy management, etc.|
-|appliance|Appliance specific operations, such as setting IP address, maintenance, backups, support bundles, appliance management|
-|notification|Anonymous, unauthenticated operations. This service is available even when the appliance isn't fully online|
-|a2a|Application integration specific operations. Fetching passwords, making access requests on behalf of users, etc.|
-
-Each of these services provides a separate Swagger endpoint.
-
-You may use the `Authorize` button at the top of the screen to get an API token
-to call the Safeguard API directly using Swagger.
-
-### Examples
-
-Most functionality is in the core service as mentioned above.  The notification service
-provides read-only information for status, etc.
-
-#### Anonymous Call for Safeguard Status
-
-Sample can be found <a href="samples\Browser\Promises\AnonymousExample">here</a>.
-
-```JavaScript
-// Browser Example
-SafeguardJs.connectAnonymous('safeguard.sample.corp', saveConnectionCallback)
-.then((connection) => { 
-    connection.invoke(SafeguardJs.Services.NOTIFICATION, SafeguardJs.HttpMethods.GET, 'v3/Status')
-    .then((results) => { 
-        console.log(results);
-    });
-});
-```
-
-Sample can be found <a href="samples\Node.JS\anonymousExample.js">here</a>.
-
-```JavaScript
-// Node.JS Example
-let localStorage = new require('src/LocalStorage').LocalStorage;
-SafeguardJs.addCAFromFile(caFile);
-let connection = await SafeguardJs.connectAnonymous(hostName, null, localStorage);
-let result = await connection.invoke(SafeguardJs.Services.NOTIFICATION, SafeguardJs.HttpMethods.GET, 'v3/Status');
-console.log(result);
-```
-
-#### Get remaining access token lifetime
-
-Sample can be found <a href="samples\Node.JS\passwordExample.js">here</a>.
-
-```JavaScript
-// Node.JS Example
-SafeguardJs.addCAFromFile('ssl/ca.pem');
-let connection = await SafeguardJs.connectPassword('safeguard.sample.corp', 'myuser', 'mypassword');
-let result = await connection.getAccessTokenLifetimeRemaining();
-console.log(result);
-```
-
-#### Register for SignalR events
-
-Sample can be found <a href="samples\Browser\Promises\SignalRExample">here</a>.
-
-```JavaScript
-// Browser Example
-function callback(ev) {
-    console.log(`Received SignalR event: ${ev.Message}`);
-}
-
-SafeguardJs.connectRsts('safeguard.sample.corp', `${window.location.protocol}//${window.location.host}${window.location.pathname}`)
-.then((connection) => {
-    connection.registerSignalR(logCallback);
-});
-```
-
-Sample can be found <a href="samples\Node.JS\signalRExample.js">here</a>.
-
-```JavaScript
-// Node.JS Example
-function callback(ev) {
-    console.log(`Received SignalR event: ${ev.Message}`);
-}
-
-SafeguardJs.addCAFromFile('ssl/ca.pem');
-let connection = await SafeguardJs.connectPassword('safeguard.sample.corp', 'myuser', 'mypassword');
-await connection.registerSignalR(callback);
-```
-
-#### Create a New User and Set the Password
-
-Sample can be found <a href="samples\Browser\Promises\NewUserExample">here</a>.
-
-```JavaScript
-// Browser Example
-let user = {
-    'PrimaryAuthenticationProviderId': -1,
-    'UserName': 'MyNewUser'
-};
-let password = 'MyNewUser123';
-
-SafeguardJs.connectRsts('safeguard.sample.corp', `${window.location.protocol}//${window.location.host}${window.location.pathname}`)
-.then((connection) => {
-    connection.invoke(SafeguardJs.Services.CORE, SafeguardJs.HttpMethods.POST, 'v3/Users', user)
-    .then((results) => {
-        let newUser = JSON.parse(results);
-        connection.invoke(SafeguardJs.Services.CORE, SafeguardJs.HttpMethods.PUT, `v3/Users/${newUser.Id}/Password`, `"${password}"`);
-    });
-});
-```
+[![npm](https://img.shields.io/npm/v/@oneidentity/safeguard.svg)](https://www.npmjs.com/package/@oneidentity/safeguard)
+[![license](https://img.shields.io/github/license/OneIdentity/safeguard.js.svg)](https://github.com/OneIdentity/safeguard.js/blob/main/LICENSE)
+
+# safeguard.js
+
+One Identity Safeguard JavaScript/TypeScript SDK
+
+-----------
+
+<p align="center">
+<i>Check out our <a href="samples">sample projects</a> to get started with your own custom integration to Safeguard!</i>
+</p>
+
+-----------
+
+## Support
+
+One Identity open source projects are supported through [One Identity GitHub issues](https://github.com/OneIdentity/safeguard.js/issues) and the [One Identity Community](https://www.oneidentity.com/community/). This includes all scripts, plugins, SDKs, modules, code snippets or other solutions. For assistance with any One Identity GitHub project, please raise a new Issue on the [One Identity GitHub project](https://github.com/OneIdentity/safeguard.js/issues) page. You may also visit the [One Identity Community](https://www.oneidentity.com/community/) to ask questions. Requests for assistance made through official One Identity Support will be referred back to GitHub and the One Identity Community forums where those requests can benefit all users.
+
+## Introduction
+
+All functionality in Safeguard is available via the Safeguard API. There is
+nothing that can be done in the Safeguard UI that cannot also be performed
+using the Safeguard API programmatically.
+
+safeguard.js is provided to facilitate calling the Safeguard API from
+JavaScript and TypeScript. It is meant to remove the complexity of dealing
+with authentication via Safeguard's embedded secure token service (STS). The
+basic usage is to create a `SafeguardClient` with your chosen authentication
+strategy, call `connect()`, then call API methods using the same authenticated
+client.
+
+safeguard.js also provides an easy way to call Safeguard A2A from JavaScript.
+The A2A service requires client certificate authentication for retrieving
+passwords for application integration. When Safeguard A2A is properly
+configured, specified passwords can be retrieved with a single method call
+without requiring access request workflow approvals.
+
+safeguard.js includes an SDK for listening to Safeguard's powerful, real-time
+event notification system. Safeguard provides role-based event notifications
+via SignalR to subscribed clients. The `PersistentSafeguardEventListener`
+provides automatic reconnection with token refresh for long-running listeners.
+
+### Features
+
+- **TypeScript-first** with full type declarations
+- **Dual ESM/CJS** — works with `import` and `require()`
+- **Node.js and Browser** support
+- **Multiple auth strategies** — Password, Certificate, PKCE (browser), PKCE Non-Interactive (headless), Token, Anonymous
+- **A2A client** — retrieve/set passwords, SSH keys, API key secrets, broker access requests
+- **SignalR events** — one-shot and persistent event listeners with auto-reconnect
+- **Secure by default** — TLS verification enabled, no secrets in memory longer than needed
+
+## Installation
+
+```bash
+npm install @oneidentity/safeguard
+```
+
+Requires Node.js 20 or later.
+
+## Getting Started
+
+### Password Authentication (Node.js)
+
+```typescript
+import { SafeguardClient, PasswordAuth, Service } from '@oneidentity/safeguard';
+
+const client = new SafeguardClient('safeguard.sample.corp', {
+  auth: new PasswordAuth({
+    username: 'Admin',
+    password: 'Admin123',
+    provider: 'Local',
+  }),
+});
+
+await client.connect();
+
+const me = await client.get(Service.CORE, 'v4/Me');
+console.log(me);
+
+await client.disconnect();
+```
+
+### PKCE Authentication (Browser)
+
+```typescript
+import { SafeguardClient, PkceAuth, handlePkceCallback, Service } from '@oneidentity/safeguard';
+
+// On your callback page, call this first:
+handlePkceCallback();
+
+// On your main page:
+const client = new SafeguardClient('safeguard.sample.corp', {
+  auth: new PkceAuth({ redirectUri: window.location.href }),
+});
+
+await client.connect(); // Redirects to Safeguard login if no stored tokens
+
+const me = await client.get(Service.CORE, 'v4/Me');
+console.log(me);
+```
+
+### PKCE Non-Interactive (Headless Automation)
+
+For automated scenarios where no browser is available (CI/CD, scripts):
+
+```typescript
+import { SafeguardClient, PkceNonInteractiveAuth, Service } from '@oneidentity/safeguard';
+
+const client = new SafeguardClient('safeguard.sample.corp', {
+  auth: new PkceNonInteractiveAuth({
+    username: 'Admin',
+    password: 'Admin123',
+    provider: 'Local',
+  }),
+});
+
+await client.connect();
+const me = await client.get(Service.CORE, 'v4/Me');
+await client.disconnect();
+```
+
+### Client Certificate Authentication
+
+```typescript
+import { SafeguardClient, CertificateAuth, Service } from '@oneidentity/safeguard';
+
+const client = new SafeguardClient('safeguard.sample.corp', {
+  auth: new CertificateAuth({
+    certFile: '/path/to/client.pem',
+    keyFile: '/path/to/client.key',
+    passphrase: 'optional-key-passphrase',
+  }),
+});
+
+await client.connect();
+const me = await client.get(Service.CORE, 'v4/Me');
+await client.disconnect();
+```
+
+### Anonymous Access
+
+```typescript
+import { SafeguardClient, AnonymousAuth, Service } from '@oneidentity/safeguard';
+
+const client = new SafeguardClient('safeguard.sample.corp', {
+  auth: new AnonymousAuth(),
+});
+
+await client.connect();
+const status = await client.get(Service.NOTIFICATION, 'v4/Status');
+console.log(status);
+```
+
+### Pre-existing API Token
+
+```typescript
+import { SafeguardClient, TokenAuth, Service } from '@oneidentity/safeguard';
+
+const client = new SafeguardClient('safeguard.sample.corp', {
+  auth: new TokenAuth({ accessToken: 'your-token-here' }),
+});
+
+await client.connect();
+const me = await client.get(Service.CORE, 'v4/Me');
+```
+
+## Calling the API
+
+The client provides typed HTTP methods:
+
+```typescript
+// GET
+const users = await client.get(Service.CORE, 'v4/Users');
+
+// GET with query parameters
+const filtered = await client.get(Service.CORE, 'v4/Users', {
+  query: { filter: "Name eq 'Admin'", fields: 'Id,Name' },
+});
+
+// POST (create)
+const newUser = await client.post(Service.CORE, 'v4/Users', {
+  json: { Name: 'newuser', PrimaryAuthenticationProvider: { Id: -1 } },
+});
+
+// PUT (update)
+await client.put(Service.CORE, `v4/Users/${newUser.Id}/Password`, {
+  json: 'NewPassword123',
+});
+
+// DELETE
+await client.delete(Service.CORE, `v4/Users/${newUser.Id}`);
+```
+
+### Services
+
+| Service | Description |
+|---------|-------------|
+| `Service.CORE` | Most product functionality — access requests, asset management, policy, users |
+| `Service.APPLIANCE` | Appliance-specific operations — IP address, maintenance, backups |
+| `Service.NOTIFICATION` | Anonymous/unauthenticated — status, availability |
+| `Service.A2A` | Application integration — credential retrieval, access request brokering |
+
+## A2A (Application to Application)
+
+```typescript
+import { A2AClient, CertificateAuth } from '@oneidentity/safeguard';
+
+const a2a = new A2AClient('safeguard.sample.corp', {
+  auth: new CertificateAuth({
+    certFile: 'client.pem',
+    keyFile: 'client.key',
+  }),
+});
+
+// Retrieve a password
+const password = await a2a.retrievePassword(apiKey);
+
+// Retrieve an SSH private key
+const sshKey = await a2a.retrievePrivateKey(apiKey);
+
+// Set a password (write-back)
+await a2a.setPassword(apiKey, 'NewPassword123');
+
+// Discover retrievable accounts
+const accounts = await a2a.getRetrievableAccounts();
+```
+
+## Event Listeners (SignalR)
+
+Real-time event support requires the optional `@microsoft/signalr` peer dependency:
+
+```bash
+npm install @microsoft/signalr
+```
+
+Event classes are imported from the `@oneidentity/safeguard/events` subpath:
+
+```typescript
+import { SafeguardEventListener } from '@oneidentity/safeguard/events';
+import { PasswordAuth, NodeHttpClient, MemoryStorage } from '@oneidentity/safeguard';
+import * as signalR from '@microsoft/signalr';
+```
+
+### One-Shot Listener
+
+```typescript
+// Authenticate and build SignalR connection
+const auth = new PasswordAuth({ username: 'Admin', password: 'Admin123', provider: 'Local' });
+const httpClient = new NodeHttpClient();
+const storage = new MemoryStorage();
+const tokenSet = await auth.authenticate('safeguard.sample.corp', httpClient, storage);
+
+const connection = new signalR.HubConnectionBuilder()
+  .withUrl(`https://safeguard.sample.corp/service/event/signalr`, {
+    accessTokenFactory: () => tokenSet.accessToken.expose(),
+  })
+  .withAutomaticReconnect()
+  .build();
+
+const listener = new SafeguardEventListener(connection);
+
+listener.on('NotifyEventAsync', (event) => {
+  console.log('Event received:', event);
+});
+
+await listener.start();
+```
+
+### Persistent Listener (Auto-Reconnect)
+
+For long-running processes that need to survive network interruptions and
+token expiration:
+
+```typescript
+import { PersistentSafeguardEventListener } from '@oneidentity/safeguard/events';
+
+const listener = new PersistentSafeguardEventListener(
+  connection, auth, 'safeguard.sample.corp', httpClient, storage,
+);
+
+listener.onStateChange((state) => {
+  console.log('State:', state);
+});
+
+listener.on('NotifyEventAsync', (event) => {
+  console.log('Event:', event);
+});
+
+await listener.start();
+```
+
+The persistent listener automatically checks token lifetime and refreshes
+credentials before they expire (with a 60-second safety margin).
+
+## Security
+
+### Token Storage (Browser)
+
+The SDK stores access tokens **in memory only**. Tokens do not survive a page
+refresh, which is the secure default for single-page applications without a
+backend-for-frontend (BFF).
+
+If your application requires persistence across page reloads, you may
+explicitly store the token yourself — but be aware this exposes the token to
+cross-site scripting (XSS) attacks:
+
+```typescript
+await client.connect();
+// ⚠️ Customer explicitly accepts the XSS risk:
+sessionStorage.setItem('my_token', client.accessToken.expose());
+```
+
+For high-security environments, prefer in-memory tokens with re-authentication
+on refresh, or implement a BFF pattern where tokens never reach the browser.
+
+### SecretValue
+
+Credentials and access tokens are wrapped in `SecretValue`, a class that
+redacts content from `toString()`, `toJSON()`, and `console.log()` output.
+This prevents accidental logging of secrets.
+
+To retrieve the raw string value (e.g., for HTTP headers or storage), call
+`.expose()`:
+
+```typescript
+const tokenSet = await auth.authenticate(host, httpClient, storage);
+const raw: string = tokenSet.accessToken.expose(); // explicit opt-in
+```
+
+### TLS Verification
+
+TLS certificate verification is **enabled by default** and should never be
+disabled in production. For development environments with self-signed
+certificates:
+
+```typescript
+// Development only — never use in production
+const client = new SafeguardClient('dev-appliance.local', {
+  auth: new PasswordAuth({ ... }),
+  verify: false,
+});
+```
+
+For production with a custom CA:
+
+```typescript
+const client = new SafeguardClient('safeguard.corp', { auth });
+client.setHttpClient(new NodeHttpClient({ ca: '/path/to/ca-bundle.pem' }));
+```
+
+### Host Validation
+
+The `SafeguardClient` constructor validates the `host` parameter to prevent
+injection attacks. Only bare hostnames or IP addresses are accepted — URLs,
+paths, ports, query strings, and whitespace are rejected with a
+`ConfigurationError`.
+
+### Token Lifetime
+
+`client.getAccessTokenLifetimeRemaining()` decodes the JWT `exp` claim
+client-side. This is a convenience for scheduling token refresh — never use it
+as an authorization decision. The server is the sole authority on token
+validity.
+
+## About the Safeguard API
+
+The Safeguard API is a REST-based Web API. Safeguard API endpoints are called
+using HTTP operators and JSON requests and responses. The Safeguard API is
+documented using Swagger. You may use Swagger UI to call the API directly or
+to read the documentation about URLs, parameters, and payloads.
+
+To access the Swagger UI use a browser to navigate to:
+`https://<address>/service/<service>/swagger`
+
+- `<address>` = Safeguard network address
+- `<service>` = Safeguard service to use
+
+To access the Swagger OpenAPI specification:
+`https://<address>/service/<service>/swagger/v4/swagger.json`
+
+### Query Parameters
+
+| Parameter | Example | Description |
+|-----------|---------|-------------|
+| `filter` | `filter=Name eq 'Admin'` | Filter results |
+| `fields` | `fields=Id,Name` | Select specific properties |
+| `orderby` | `orderby=Name` or `orderby=-Name` | Sort ascending/descending |
+| `page` | `page=0` | Page number (0-based) |
+| `limit` | `limit=100` | Results per page |
+| `count` | `count=true` | Include total count |
+| `q` | `q=admin` | Full-text search |
+
+## Migration from v7.x
+
+See [MIGRATION.md](MIGRATION.md) for a complete guide to upgrading from the
+legacy JavaScript API to the v8.0 TypeScript SDK.
+
+## Related Projects
+
+| Project | Language | Description |
+|---------|----------|-------------|
+| [SafeguardDotNet](https://github.com/OneIdentity/SafeguardDotNet) | C# | .NET SDK |
+| [PySafeguard](https://github.com/OneIdentity/PySafeguard) | Python | Python SDK |
+| [SafeguardJava](https://github.com/OneIdentity/SafeguardJava) | Java | Java SDK |
+| [safeguard-ps](https://github.com/OneIdentity/safeguard-ps) | PowerShell | PowerShell module |
+| [safeguard-bash](https://github.com/OneIdentity/safeguard-bash) | Bash | Bash utilities |