Rename to OMS Wallet and align session/OIDC auth

[tolgahan-arikan]

Summary

• Persist wallet sessions using the local credential identity, so completed and restored sessions retain their authenticated signer binding.
• Standardize the full verification entry point as pnpm verify and run it in CI.
• Rename and publish the TypeScript packages as OMS Wallet: @polygonlabs/oms-wallet, @polygonlabs/oms-wallet-wagmi-connector, root export OMSWallet, stable 0.2.0 metadata, and full pnpm verify checks for stable, prerelease, and snapshot releases.
• Replace legacy session loginType / sessionEmail metadata with structured OMSWalletSessionAuth for email, OIDC redirect, and OIDC ID-token sessions, including expiry handling and provider-aware session labels.
• Add signInWithOidcIdToken, built-in Apple OIDC defaults alongside Google, provider/providerLabel/email auth metadata, configurable OIDC auth modes, and session lifetime validation up to 30 days.
• Tighten OIDC redirect behavior so SDK-helper Google/Apple providers are the only OMS-relayed providers using omsRelayReturnUri and provider-specific callbacks at {apiBase}/auth/waas/callback/{google|apple}; custom providers require providerRedirectUri and cannot use the OMS relay option.
• Tighten package exports and wagmi connector behavior for ESM/CJS type resolution, OMS Wallet naming, fee option selection, provider request handling, and public error contracts.
• Update examples, including the main React app, wagmi example, Trails Actions example, Node examples, and a custom Google redirect example that verifies Google configured without the SDK relay.
• Refresh README/API/publishing/testing/error docs and type tests around non-custodial positioning, setup, auth, wallet address, signing, balances, security model, OIDC provider choices, testnet-first transaction guidance, and stable release readiness.

Diff Drivers

• The largest runtime change is walletClient.ts, which replaces the session/auth state model and enforces the default-versus-custom OIDC boundary. Session, redirect, ID-token, transaction, error-contract, and type tests expand alongside that behavior.
• scripts/public-api-baseline.txt is an 895-line generated public-API contract, not runtime implementation. Release verification scripts and type checks make package publishing repeatable.
• README/API revisions, package renaming, connector changes, and the custom Google redirect example account for the remaining documentation, example, and path-move churn.

Review

• Checked session lifecycle behavior for pending auth, completed sessions, restore, expiry, sign-out, wallet selection, and provider-aware display labels.
• Checked OIDC redirect and ID-token flows for state persistence, callback completion, wallet selection, session lifetime, auth mode, provider metadata, provider callback errors, and storage errors.
• Checked default-vs-custom OIDC boundaries so helper-created Google/Apple providers are the only OMS-relayed providers, manually configured Google/Apple-looking providers remain custom, and omsRelayReturnUri is rejected for custom providers.
• Checked public docs/API references for public SDK surface only, including structured session auth, stable OMS error codes, OIDC redirect terminology, package names, and 30-day session lifetime limits.
• Checked package metadata and wagmi connector publish validation for stable release behavior.
• Checked README first-impression flow so new SDK users see non-custodial positioning, setup, auth, wallet address, signing, balances, security, and OIDC choices before transaction-heavy examples.

Validation

• pnpm verify
• GitHub Actions Tests (passed)
• pnpm test:types
• pnpm exec tsc --noEmit
• pnpm test
• pnpm check:stable-package-versions
• pnpm build
• pnpm --filter @polygonlabs/oms-wallet-wagmi-connector build
• git diff --check
• Targeted README/API scans for OIDC redirect names, session metadata, package naming, generated/internal terminology, unsafe placeholders, and mainnet-first examples.

[claude]

Claude finished @tolgahan-arikan's task —— View job

---

PR Review: Add structured session auth and Apple defaults

• Read core SDK changes (walletClient.ts, index.ts, oidc.ts, omsEnvironment.ts, constants.ts)
• Review public API sync (API.md, type-tests)
• Check test coverage for changed behavior
• Verify .js import extensions in src/
• Check for committed secrets / unsafe casts

Overall this is a clean, well-structured refactor. The loginType/sessionEmail → structured auth migration is consistent across source, storage, docs, type-tests, and tests. .js extensions are preserved, no new secrets, and the new normalizeSessionAuth parser is appropriately defensive. A few things worth addressing before merge:

🔴 Backward-compat / migration gap (behavior + coverage)

On restore, src/clients/walletClient.ts:402-407, a stored session that fails to produce auth is now discarded and cleared. For users upgrading with a live session persisted in the old format (omsWallet_session_login_type + omsWallet_session_email, no omsWallet_session_auth), parseSessionAuth returns undefined, so they are silently signed out on upgrade.

• Is silent sign-out on upgrade intentional? If so, worth a note in the PR/changelog. If not, consider a one-time migration that reads the legacy keys and reconstructs auth (you already delete those keys in clearSessionMetadata() at walletClient.ts:791-792, so the intent seems to be "drop legacy," but a migration would be more user-friendly).
• Either way, there is no test for the legacy-keys-present-but-no-auth-key scenario. The existing test "does not restore wallet metadata without completed session auth" (tests/walletSession.test.ts:599) only covers the no keys at all case. Add a regression test seeding the old keys to lock in whatever the intended behavior is.

🟡 'id-token' flow is public but never produced

OMSClientOidcSessionAuthFlow = 'redirect' | 'id-token' (walletClient.ts:168) is exported and documented in API.md, but nothing in the SDK ever sets flow: 'id-token' — only 'redirect' is produced (walletClient.ts:1344). getIdToken() fetches a token for an already-authenticated session; it doesn't create a session. Two options:

• If a token-based OIDC auth path is coming later, fine to leave it — but a brief code comment noting it's reserved would help.
• If not, consider dropping 'id-token' from the public union until it's actually emitted, to avoid advertising a value consumers will never observe.

🟢 Minor observations (non-blocking)

• Behavior change: activeWalletActivationContext now throws OmsSessionError when metadata is missing (walletClient.ts, previously metadata was optional). This is a reasonable tightening since persistSession/activateWallet now always require metadata, but it's a new throw path — a focused test asserting the error would be nice if any operation can reach it with an active-but-metadata-less session.
• Lossy google-auth mapping: the old loginType distinguished 'google-auth' vs generic 'oidc'. That distinction is now expressed via provider: 'google' / providerLabel: 'Google' derived from the issuer (builtInOidcProviderForIssuer), which is a strict improvement. Just flagging it as an intentional public-shape change for consumers who keyed on loginType === 'google-auth' — this is well-documented in API.md.
• serializeSessionAuth/normalizeSessionAuth round-trip and the isSessionAuthFlow guard look correct; JSON parse is wrapped in try/catch. 👍

✅ Verified

• Public API changes reflected in API.md (both session type blocks + OidcProviderConfig/*OidcProviderParams) and type-tests/oidcProviderTypes.ts; src/index.ts exports updated.
• .js extensions preserved in all touched relative imports.
• No secrets introduced — defaultGoogleClientId/defaultAppleClientId are public OAuth client IDs and pre-existing.
• No unsafe casts beyond existing (wallet as any) test-only patterns; the value as Record<string, unknown> in normalizeSessionAuth is guarded and idiomatic.
• OIDC redirect session-auth persistence has good coverage (tests/oidcRedirectAuth.test.ts:574 asserts full session.auth shape incl. custom provider/label).

Note: I was unable to run pnpm exec tsc --noEmit / pnpm test in this environment (command not permitted), so I relied on static review. The PR body lists these as passing.
• Branch: session-auth-and-apple-defaults

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e8043fd9e2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[tolgahan-arikan]

@claude review

[claude]

Claude finished @tolgahan-arikan's task —— View job

---

PR Review: Add structured session auth and Apple defaults

• Read core SDK changes (walletClient.ts, index.ts, oidc.ts, oidcIdToken.ts)
• Verify the session-auth aliasing concern from Codex review
• Check test coverage for changed behavior
• Verify public API sync (API.md, type-tests)
• Verify .js import extensions + secrets/type soundness

---

Solid, cohesive PR. The loginType/sessionEmail → structured auth migration is consistent across source, storage, docs, type-tests, and tests, and it now also lands a real id-token OIDC auth path. I verified the two open items from the prior review and the Codex aliasing note — all three are already handled. Details below.

✅ Codex "return a copy of session auth" — already fixed

Codex flagged that returning this.sessionAuth by reference would let callers mutate live client state. That risk isn't present:

• get session() returns auth: cloneSessionAuth(this.sessionAuth) (src/clients/walletClient.ts:467), the expiry event clones too (walletClient.ts:1222, 2065, 2071), and cloneSessionAuth does a {...auth} shallow copy (walletClient.ts:2057).
• All OMSWalletSessionAuth fields are readonly and flat scalars (walletClient.ts:177-191), so a shallow clone fully de-aliases the snapshot. API.md:188 documents these as readonly snapshots.

No change needed here. 👍

✅ Prior review "id-token flow is public but never produced" — now resolved

flow: 'id-token' is genuinely emitted by the new signInWithOidcIdToken path (walletClient.ts:1409 via oidcIdTokenSessionAuthFromParams), so the exported OMSWalletOidcSessionAuthFlow union is no longer advertising an unreachable value. Good.

✅ Prior review "legacy migration/silent sign-out has no test" — now covered

tests/walletSession.test.ts:703 ("does not restore legacy wallet metadata without structured session auth") seeds the old omsWallet_session_login_type + omsWallet_session_email keys and asserts the session is dropped and legacy keys are cleared. This locks in the intended "drop legacy on upgrade" behavior. Note this confirms the upgrade path is a silent sign-out for users on the old format — intentional per the test, worth a changelog line for consumers.

New id-token behavior — correctness looks right

• ID token is validated locally before any network call: exp is parsed (oidcIdTokenExpiresAtEpochSeconds) and an invalid/missing exp throws pre-flight — covered by tests/oidcIdTokenAuth.test.ts:190 (asserts fetchMock not called). 👍
• handle uses a SHA-256 hash of the token rather than the raw token (oidcIdToken.ts:18-27), and crypto.subtle absence throws a clear error — good defensive posture, no token material leaked into logs.
• Full happy-path + manual-selection + pending-redirect-clear coverage in tests/oidcIdTokenAuth.test.ts; the manual-selection test asserts session.auth is undefined until selection completes (:176).

Verified against your focus areas

• Public API sync: src/index.ts:56-73 exports the new CompleteOidcIdTokenAuthResult, SignInWithOidcIdTokenParams, OMSWalletSessionAuth union + flow type; API.md documents them (:165, :308, :1183, :1194, :1324) and type-tests/oidcProviderTypes.ts:144-151 exercises SignInWithOidcIdTokenParams/CompleteOidcIdTokenAuthResult. In sync.
• .js extensions: new src/utils/oidcIdToken.ts:1 imports ./oidcRedirect.js — preserved.
• No secrets: defaultAppleClientId = "service.oms.polygon.technology" and defaultGoogleClientId are public OAuth client IDs, not secrets (src/oidc.ts:24-26).
• Type soundness: normalizeSessionAuth guards the single value as Record<string, unknown> cast and validates type/issuer/flow before constructing (walletClient.ts:2086-2109); isSessionAuthFlow guards the union. cloneSessionAuth overloads are precise. No unsafe casts beyond the existing test-only (wallet as any) pattern.

🟢 Minor / non-blocking

• normalizeSessionAuth drops OIDC email if issuer is missing: an {type:'oidc', flow, email} blob with no issuer returns undefined entirely (walletClient.ts:2097). That's correct given issuer is required (walletClient.ts:187) and shouldn't happen for SDK-serialized data, but it means any hand-tampered/partial OIDC blob is a full sign-out rather than a degraded session — consistent with the legacy behavior, just noting.
• response.identity.iss || params.issuer fallback (walletClient.ts:1406): if the backend echoes an empty iss, the client-supplied issuer is used for provider derivation. Reasonable; the id-token happy-path test asserts the resolved Google issuer, so this is covered.

⚠️ Could not run

I don't have permission to run pnpm install / pnpm exec tsc --noEmit / pnpm test in this environment, so this is static review only. The PR body lists all verification commands (tsc, test, build, all example builds, connector tests) as passing; please ensure CI is green before merge.

Verdict: LGTM — the prior review feedback and the Codex note are all addressed. Only suggestion is a changelog note about the silent sign-out for users upgrading from the legacy session format.

---

• Branch: session-auth-and-apple-defaults •