Auth-Required Trustline Request Handler

[Kingsman-99]

Description

Assets issued by accounts with AUTH_REQUIRED flag set require the issuer to explicitly approve each trustline before a recipient can hold the asset. The SDK does not automate the AllowTrust or SetTrustlineFlags request on behalf of issuers, leaving recipients unable to receive the asset until the issuer manually acts. An auth-required trustline handler should detect the condition, notify the issuer, and facilitate the approval transaction.

Technical Context

Add src/trustlineAuthHandler.ts. Reads issuer account flags via src/accountFlagsInspector.ts. Builds Operation.setTrustLineFlags() (protocol 18+) or Operation.allowTrust() (legacy) via @stellar/stellar-sdk. Integrates with src/preflightChecker.ts to detect when an approval is needed. Adds TrustlineAuthRequest to src/types.ts. Emits trustlineAuthRequired and trustlineAuthGranted via src/events.ts.

Acceptance Criteria

• TrustlineAuthHandler.checkAndRequest(recipientId, asset): Promise<TrustlineAuthStatus> detects whether the asset requires auth and, if so, emits trustlineAuthRequired with the issuer's public key
• TrustlineAuthHandler.grantAuth(recipientId, asset, issuerKeypair): Promise<TransactionResult> builds and submits the SetTrustLineFlags (AUTHORIZED) operation signed by the issuer
• Prefers SetTrustLineFlags on protocol ≥ 18 and falls back to AllowTrust on older protocol versions detected by src/sorobanFeatureDetector.ts
• Emits trustlineAuthGranted after successful submission
• Unit tests mock account flags (auth required), call checkAndRequest, and assert trustlineAuthRequired is emitted; assert grantAuth submits the correct operation type
• All CI checks (npm test, npm run build, ESLint/TypeScript) pass and the branch has no merge conflicts

---