adobe / adobe/aio-lib-ims-jwt

Proposal: Break circular dependency by extracting aio-lib-ims-core

Open
#79 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
2
Forks
8
Avg merge
20h 24m
Merged PRs (30d)
2

Description

## Problem

There's a circular dependency between `aio-lib-ims` and `aio-lib-ims-jwt`:

```
aio-lib-ims
├── imports: aio-lib-ims-jwt (as plugin)

aio-lib-ims-jwt
├── peerDependency: aio-lib-ims (needs ims instance)
└── calls: ims.getApiUrl(), ims.exchangeJwtToken()
```

This causes:
- npm to install nested old copies (audit false positives)
- Confusing dependency graph
- Difficulty maintaining version compatibility

## Analysis

### What aio-lib-ims-jwt needs from aio-lib-ims:
- `ims.getApiUrl(path)` - Get IMS API URL with path
- `ims.exchangeJwtToken(clientId, clientSecret, jwtToken)` - Exchange JWT for access token

### What aio-lib-ims needs from aio-lib-ims-jwt:
- Plugin interface: `supports(config)`, `canSupport(config)`, `imsLogin(ims, config)`

## Proposed Solution: Extract `@adobe/aio-lib-ims-core`

Create a new core package that both packages depend on:

```
aio-lib-ims-core (NEW)
├── ImsCore class (API URLs, token exchange)
├── Plugin interface definitions
└── Shared types/utilities

aio-lib-ims-jwt
├── depends on: aio-lib-ims-core
└── implements: ImsPlugin interface

aio-lib-ims
├── depends on: aio-lib-ims-core
├── depends on: aio-lib-ims-jwt (as plugin)
└── extends: ImsCore with plugin management
```

### What goes in `aio-lib-ims-core`:

```javascript
class ImsCore {
constructor(env) { ... }

// API URL helpers
getApiUrl(path) { ... }

// Token exchange (no plugin dependencies)
exchangeJwtToken(clientId, clientSecret, jwtToken) { ... }
getAccessToken(refreshToken, clientId, clientSecret, scope) { ... }
invalidateToken(token, clientId, clientSecret) { ... }
}

// Plugin interface
interface ImsPlugin {
canSupport(config): Promise
supports(config): boolean
imsLogin(ims: ImsCore, config): Promise
}
```

## Benefits

✅ **No circular dependency** - clean dependency graph
✅ **Architecturally correct** - separation of concerns
✅ **Extensible** - easier to add new auth plugins (SAML, API key, etc.)
✅ **Reusable** - other packages can use core without full ims
✅ **Type safety** - shared interfaces/types in one place
✅ **No audit false positives** - no nested old copies

## Implementation Strategy

### Phase 1: Create core (beta)
1. Create `@adobe/aio-lib-ims-core@1.0.0-beta.1`
2. Extract: `ImsCore` class, plugin interfaces, token exchange
3. Publish beta

### Phase 2: Update jwt (beta)
1. Release `@adobe/aio-lib-ims-jwt@6.0.0-beta.1`
2. Depend on `aio-lib-ims-core` instead of peer on `aio-lib-ims`
3. Publish beta

### Phase 3: Update ims (beta)
1. Release `@adobe/aio-lib-ims@9.0.0-beta.1`
2. Extend `ImsCore`
3. Depend on `aio-lib-ims-jwt@^6.0.0-beta`
4. Publish beta

### Phase 4: Stable release
Once validated in beta, release stable versions

## Effort Estimate

- **Core extraction**: 2-3 days
- **JWT refactor**: 1 day
- **IMS refactor**: 2-3 days
- **Testing**: 2-3 days
- **Total**: ~1-2 weeks

## Alternative Considered

**Make jwt a peer dependency in aio-lib-ims:**
- Simpler but doesn't solve architectural issues
- Makes jwt plugin "special" vs other auth plugins
- Consumers must install both packages manually

## Related

- Current PR with dependency upgrades: #78
- This is a long-term architectural improvement
- Short-term: Can proceed with current PR as v6.0.0 major bump

## Questions

1. Is the Adobe team interested in this architectural refactor?
2. What's the timeline/priority for this work?
3. Should we coordinate with other auth plugin maintainers?

cc @dthampy for visibility

Contributor guide

Open the contributing guide

Research direction

Review the existing implementations of getApiUrl, exchangeJwtToken, getAccessToken, invalidateToken, and the supports, canSupport, and imsLogin plugin entry points, along with PR #78. Done means the core package owns the shared APIs and interfaces, both packages depend on it without a circular dependency, and the beta package plan is validated by tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
authentication, backend, backend-api-design
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.