{"id":22268106,"url":"https://github.com/curityio/token-handler-js-assistant","last_synced_at":"2025-10-13T01:38:58.156Z","repository":{"id":244207164,"uuid":"803143005","full_name":"curityio/token-handler-js-assistant","owner":"curityio","description":"A helper library to help SPAs interact with OAuth Agent in the Token Handler pattern. ","archived":false,"fork":false,"pushed_at":"2024-08-12T09:20:35.000Z","size":88,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-12-03T11:11:49.535Z","etag":null,"topics":["oauth-agent","oauth2","openid-connect","spa","token-handler"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/curityio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-20T06:40:01.000Z","updated_at":"2024-10-22T09:56:27.000Z","dependencies_parsed_at":"2024-06-13T12:30:31.784Z","dependency_job_id":"d9c8bb0e-8131-4848-b1fd-c5b29b1a5afb","html_url":"https://github.com/curityio/token-handler-js-assistant","commit_stats":null,"previous_names":["curityio/token-handler-js-assistant"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Ftoken-handler-js-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Ftoken-handler-js-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Ftoken-handler-js-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Ftoken-handler-js-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/curityio","download_url":"https://codeload.github.com/curityio/token-handler-js-assistant/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236355802,"owners_count":19136006,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["oauth-agent","oauth2","openid-connect","spa","token-handler"],"created_at":"2024-12-03T11:11:08.987Z","updated_at":"2025-10-13T01:38:58.130Z","avatar_url":"https://github.com/curityio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# token-handler-js-assistant\nA helper library to help SPAs interact with the OAuth Agent in the Token Handler pattern.\n\n## Add to project\nAdd to your project using npm\n\n```\nnpm install @curity/token-handler-js-assistant\n```\n\n## How to use in your project\n\nImport the Assistant into your project and initialize it using `Configuration` object.\n```typescript\nimport {OAuthAgentClient} from \"@curity/token-handler-js-assistant\";\nconst client = new OAuthAgentClient({oauthAgentBaseUrl: 'https://api.example.com/oauthagent/example'})\n```\nThe `Configuration` object contains the following options:\n- `oauthAgentBaseUrl` - a URL with path to the token handler application created in the Curity Identity Server (this URL ends with a token handler application ID\n  as defined in the Curity Identity Server configuration).\n\n### Using the initialized client\n\n1. Starting the user login\n   ```typescript\n   const response = await this.oauthAgentClient.startLogin({\n     extraAuthorizationParameters: {\n       scope: \"openid profile\", \n       login_hint: \"username\",\n       ui_locales: \"en\"\n     }\n   })\n   location.href = response.authorizationUrl\n   ```\n2. Finishing the user login\n   ```typescript\n   const url = new URL(location.href)\n   const response = await client.endLogin({ searchParams: url.searchParams })\n   if (response.isLoggedIn) {\n     // use id token claims to get username, e.g. response.idTokenClaims?.sub\n   }\n   ``` \nNote: The `endLogin` function should only be called with authorization response parameters (when the authorization\nserver redirected user to the SPA after a successful user login). It's recommended to call `onPageLoad()` instead\non every load of the SPA. This function makes a decision based the query string and either calls `endLogin()` or `session()`.\n\n3. Handling page load\n   ```typescript\n   const sessionResponse = await client.onPageLoad(location.href)\n   if (sessionResponse.isLoggedIn) {\n     // user is logged in\n   } else {\n     const response = await client.startLogin()\n     // redirect the user to the authorization server\n     location.href = response.authorizationUrl\n   }\n   ```\n4. Refreshing tokens\n   ```typescript\n   await client.refresh({\n    extraRefreshParameters: {\n      scope: 'openid'\n    }\n   })\n   ```\n5. Retrieving ID token claims\n   ```typescript\n   const sessionResponse = await client.session()\n   // use session data\n   if (session.isLoggedIn === true) {\n     session.idTokenClaims?.sub\n   }\n   ```\n6. Logging out\n   ```typescript\n   const logoutResponse = await client.logout()\n   if (logoutResponse.logoutUrl) {\n     // redirect user to the single logout url\n     location.href = logoutResponse.logoutUrl;\n   }\n   ```\n   \n7. Implementing preemptive refresh. `session()`, `refresh()`, `endLogin()` and `onPageLoad()` functions return `accessTokenExpiresIn`\n   if the Authorization Server includes `expires_in` in token responses. This field contains number of seconds until an  \n   access token that is in the proxy cookie expires. This value can be used to preemptively refresh the access token.\n   After calling `onPageLoad()` and `refresh()`:\n   ```typescript\n   // const response = await client.onPageLoad(location.href)\n   // const response = await client.refresh()\n   if (response.accessTokenExpiresIn != null) {\n     const delay = Math.max(response.accessTokenExpiresIn - 2, 1)\n     setTimeout(\n       () =\u003e { client.refresh(); },\n       delay * 1000\n     );\n   }\n   ```\n   Note: This is just a simplified example. The timeout has to be cleared properly (before every refresh, or before logout).\n\n## Cookie Security\n\n- `SameSite=Strict` cookies are sent to APIs, which cannot be sent from malicious sites\n- to ensure that only precise whitelisted origins can send cookies to APIs, a `token-handler-version: 1` header is\n  sent by this library on every request to the OAuth Agent. In cross-origin deployments this ensures that a CORS pre-flight\n  request authorizes access. SPA developers may be required to send this header to token handler proxies as well (refer \n  to the token handler proxy documentation for details). ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurityio%2Ftoken-handler-js-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcurityio%2Ftoken-handler-js-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurityio%2Ftoken-handler-js-assistant/lists"}