etn-ecosystem/etn-identity-sdk

1. Repository role

- This is a published SDK package, not an application.

- Its job is to help a consuming app implement “Sign in with ETN” using the OIDC Authorization Code Flow.

- The SDK’s scope is primarily client-side initiation and UI, while the README explicitly places code exchange, session storage, and token rotation on the consumer’s backend.

2. Primary architectural boundary

- The key boundary is between:

- SDK code in this repo

- Application backend/session layer in the integrating app

- ETN Identity Provider at auth.etnecosystem.org

- The SDK initiates the login redirect, but does not own the secure token/session lifecycle.

3. Source tree structure

- src/ contains the authored TypeScript source.

- dist/ contains the compiled distributable artifacts (.js and .d.ts) that are published to npm.

- This indicates a library build pipeline: author in TypeScript/React, compile to consumable JS plus type definitions.

4. Public API surface

- src/index.ts is the likely package entrypoint, exporting the SDK’s supported surfaces.

- src/client.ts contains the programmatic auth client used to construct ETN authorization URLs.

- src/components/ETNConnectButton.tsx provides the React UI component for a login/connect action.

5. Client-side auth flow

- The SDK’s client-side responsibility is to build the authorization URL and hand control to the browser via redirect.

- It supports the standard OIDC login initiation pattern, including a state value for CSRF protection.

- This makes the browser the start of the authentication flow, but not the place where secrets or tokens should be stored.

6. UI component layer

- ETNConnectButton is the main reusable UI boundary.

- It likely encapsulates the “sign in with ETN” interaction so consuming apps can add login with minimal wiring.

- Architecturally, this is a thin presentation layer over the client auth helper.

7. Distribution and typing

- dist/client.js, dist/components/ETNConnectButton.js, and corresponding .d.ts files show the package is shipped as prebuilt runtime code plus TypeScript declarations.

- This matters for architecture because consumers do not compile the SDK source themselves; they integrate the published bundle.

8. External dependency model

- The README documents the ETN Identity Provider endpoints, especially the token endpoint at https://auth.etnecosystem.org/api/v1/oauth/token.

- The actual secure operations are performed by the integrating app’s server, which exchanges the auth code for tokens and manages refresh tokens.

- The SDK therefore sits in front of an external identity service, but not in front of a proprietary backend.

9. Session and token handling are intentionally outside the SDK

- The README shows session management using iron-session, but that code is presented as integration guidance, not as part of this repository’s source tree.

- That means the repo is architected as a frontend SDK plus documentation, not a full auth platform.

- If you diagram the full system, token rotation and session cookies should be shown in the consumer application, not inside this package.

10. Docs and operational guidance

- README.md is a substantial architecture document in its own right, describing:

- login redirect

- callback handling

- token exchange

- session persistence

- token rotation

- Integration-Debugging-Guide.md suggests there is also operational guidance for troubleshooting integration issues, reinforcing that the repo is meant to support app developers adopting the ETN auth flow.

11. Tooling/runtime

- The package is built with TypeScript and npm.

- tsconfig.json, package-lock.json, and the compiled dist/ output confirm a standard Node-based library workflow.

- public/ exists, but the tree does not show a full app shell; it likely contains assets used for documentation or examples rather than a live runtime backend.

12. How to draw the architecture

- Place the ETN Identity SDK as a library box with two main exported surfaces:

- a client helper for building login redirects

- a React connect button for UI integration

- Draw an arrow from the consuming browser app to ETN Identity Provider for authorization redirect.

- Draw a separate arrow from the consumer’s backend to the token endpoint and session store, because that logic is outside the SDK but required for the overall authentication architecture.