@edge-markets/connect-node 1.8.0 → 1.9.0

package/README.md

@@ -12,9 +12,16 @@ Server SDK for EDGE Connect token exchange and API calls.
 - 🪝 **Webhook signature verification** - Constant-time HMAC-SHA256 with replay protection
 - ✅ **Webhook parsing + validation** - Verify raw bodies and fail closed on malformed event payloads
 - 🔁 **Webhook reconciliation** - Cursor-based sync for catching missed events
+- 📥 **Webhook inbox orchestration** - Durable accept/process/replay control flow with partner-owned storage
 - 🔐 **Token vault** - Versioned AES-256-GCM token encryption with key rotation
+- 🔄 **User sessions** - Token-store callbacks with refresh, encryption, and single-flight refresh protection
 - ⚙️ **Env config helper** - Build SDK config from standard EDGE env vars
 
+These helpers are framework-neutral: the SDK owns repeatable Connect mechanics
+such as token refresh, webhook validation, replay control flow, and transfer
+intent checks, while partner applications keep ownership of persistence, wallet
+mutation, admin authorization, and business rules.
+
 ## Installation
 
 ```bash
@@ -248,35 +255,46 @@ const decrypted = tokenVault.decryptTokens(connection.encryptedTokens)
 const client = edge.forUser(decrypted.accessToken)
 ```
 
-## Token Refresh
+## Token Refresh And User Sessions
 
-Refresh tokens before they expire:
+Use `EdgeUserSession` when you store encrypted tokens and want the SDK to
+handle decrypt-refresh-save-client lifecycle. You still own the database table
+and user mapping.
 
 ```typescript
-async function getValidAccessToken(userId: string): Promise<string> {
-  const connection = await db.edgeConnections.get(userId)
-  
-  // Refresh 5 minutes before expiry
-  const BUFFER = 5 * 60 * 1000
-  
-  if (Date.now() > connection.expiresAt.getTime() - BUFFER) {
-    const newTokens = await edge.refreshTokens(
-      decrypt(connection.refreshToken)
-    )
-    
-    await db.edgeConnections.update(userId, {
-      accessToken: encrypt(newTokens.accessToken),
-      refreshToken: encrypt(newTokens.refreshToken),
-      expiresAt: new Date(newTokens.expiresAt),
-    })
-    
-    return newTokens.accessToken
-  }
-  
-  return decrypt(connection.accessToken)
-}
+const session = edge.createUserSession({
+  subjectId: userId,
+  tokenVault,
+  tokenStore: {
+    load: async (subjectId) => {
+      const row = await db.edgeConnections.get(subjectId)
+      return row?.encryptedTokens
+    },
+    save: async (subjectId, encryptedTokens, { tokens }) => {
+      await db.edgeConnections.update(subjectId, {
+        encryptedTokens,
+        expiresAt: new Date(tokens.expiresAt),
+      })
+    },
+  },
+  refreshSkewMs: 60_000,
+})
+
+const balance = await session.withClient((client) => client.getBalance())
 ```
 
+`EdgeUserSession` refreshes near-expiry tokens, preserves refresh tokens when
+the token endpoint does not rotate them, saves the refreshed token envelope
+before returning a client, and single-flights concurrent refreshes on the same
+process. In horizontally scaled services, keep your storage callbacks
+idempotent or add DB-level optimistic locking.
+
+For migrations from split token columns, use `createSessionTokenRecord`,
+`parseSessionTokenRecord`, `normalizeSessionExpiresAt`, and
+`encryptLegacySessionTokens`. Plaintext migration requires an explicit
+`allowPlaintext: true` option so production request paths do not silently accept
+raw tokens.
+
 ## API Methods
 
 All user-scoped API methods live on `EdgeUserClient`, created via `edge.forUser(accessToken)`:
@@ -526,6 +544,110 @@ calls, fetches and caches the partner `client_credentials` token internally,
 retries transient sync failures with the SDK retry policy, and redacts token
 material from observability hooks.
 
+### Durable webhook inbox with `createWebhookInbox`
+
+For production integrations, accept a verified webhook into durable storage
+before returning `200`, then process it asynchronously. The SDK can own the
+state machine while your app owns the database callbacks and wallet mutation.
+
+```typescript
+import {
+  createWebhookInbox,
+  parseWebhookHttpRequest,
+} from '@edge-markets/connect-node'
+
+const inbox = createWebhookInbox({
+  store: {
+    insert: db.webhookInbox.insertIdempotently,
+    find: db.webhookInbox.find,
+    markProcessing: db.webhookInbox.markProcessing,
+    markProcessed: db.webhookInbox.markProcessed,
+    markFailed: db.webhookInbox.markFailed,
+    markPending: db.webhookInbox.markPending,
+    list: db.webhookInbox.list,
+  },
+  processEvent: async (event) => {
+    // Partner-owned business logic. Keep wallet mutation idempotent.
+    await processEdgeEvent(event)
+  },
+})
+
+app.post('/webhooks/edge', express.raw({ type: 'application/json' }), async (req, res) => {
+  const parsed = parseWebhookHttpRequest({
+    request: { headers: req.headers, rawBody: req.body },
+    secret: process.env.EDGE_WEBHOOK_SECRET!,
+  })
+
+  const accepted = await inbox.acceptRaw(
+    parsed,
+    Buffer.from(req.body).toString('utf8'),
+    String(req.headers['x-edge-signature'] ?? ''),
+  )
+
+  res.status(200).json({
+    received: true,
+    duplicate: accepted.duplicate,
+    status: accepted.status,
+  })
+
+  void inbox.process(accepted.eventId).catch((error) => {
+    logger.error('EDGE webhook processing failed', { eventId: accepted.eventId, error })
+  })
+})
+```
+
+The inbox statuses are `pending`, `processing`, `processed`, and `failed`.
+Duplicate `event.id` deliveries are idempotent if the payload fingerprint
+matches. A duplicate event ID with different payload fails closed.
+
+Sync reconciliation can use the same inbox path:
+
+```typescript
+const reconciler = edge.createWebhookReconciler({
+  cursorStore,
+  inbox,
+  limit: 100,
+})
+```
+
+The reconciler accepts each synced event into the inbox, processes it, and saves
+the cursor only after processing succeeds or the event is already processed.
+Use `inbox.replay(eventId)` for explicit admin replays and
+`inbox.recoverStaleProcessing()` to make crashed `processing` rows replayable.
+
+### Transfer safety helpers
+
+Use transfer helpers to avoid decimal and direction mistakes:
+
+```typescript
+import {
+  assertWebhookMatchesTransfer,
+  createTransferIdempotencyKey,
+  getConnectTransferDirection,
+  mapTransferStatusToPartnerState,
+  normalizeMoneyAmount,
+  validateTransferAmount,
+} from '@edge-markets/connect-node'
+
+const amount = validateTransferAmount(input.amount, { min: '1.00', max: '10000.00' }, { allowNumber: false })
+const idempotencyKey = createTransferIdempotencyKey({
+  partnerUserId: user.id,
+  type: 'debit',
+  amount,
+  category: 'sportsbook',
+  externalId: bet.id,
+})
+
+// debit = EDGE user to partner; credit = partner to EDGE user
+const direction = getConnectTransferDirection('debit')
+
+assertWebhookMatchesTransfer(event, {
+  transferId: localTransfer.edgeTransferId,
+  type: 'debit',
+  amount: localTransfer.amount,
+})
+```
+
 ## Error Handling
 
 ```typescript

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as node_https from 'node:https';
-import { EdgeEnvironment, TransferCategory, Transfer, VerificationSession, TransferType, User, VerifyIdentityOptions, VerifyIdentityResult, Balance, ListTransfersParams, TransferList, CreateVerificationSessionRequest, VerificationSessionStatusResponse, EdgeTokens, EdgeWebhookEvent, TransferStatus, EdgeWebhookEventType } from '@edge-markets/connect';
+import { EdgeEnvironment, TransferCategory, Transfer, VerificationSession, TransferType, TransferStatus, User, VerifyIdentityOptions, VerifyIdentityResult, Balance, ListTransfersParams, TransferList, CreateVerificationSessionRequest, VerificationSessionStatusResponse, EdgeTokens, EdgeWebhookEvent, EdgeWebhookEventType } from '@edge-markets/connect';
 export { Balance, BaseWebhookEvent, ConsentRevokedEventData, CreateVerificationSessionRequest, EDGE_WEBHOOK_EVENT_TYPES, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, EdgeEnvironment, EdgeError, EdgeIdentityVerificationError, EdgeInsufficientScopeError, EdgeNetworkError, EdgeNotFoundError, EdgeTokenExchangeError, EdgeTokens, EdgeValidationError, EdgeWebhookEvent, EdgeWebhookEventType, ListTransfersParams, SdkGeolocation, TRANSFER_CATEGORIES, Transfer, TransferCategory, TransferCompletedEventData, TransferExpiredEventData, TransferFailedEventData, TransferList, TransferListItem, TransferProcessingEventData, TransferStatus, TransferType, User, UserAddress, VerificationSession, VerificationSessionStatus, VerificationSessionStatusResponse, VerifyIdentityAddress, VerifyIdentityOptions, VerifyIdentityResult, VerifyIdentityScores, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isIdentityVerificationError, isNetworkError, isProductionEnvironment } from '@edge-markets/connect';
 
 type RequestEndpoint = 'connect_api' | 'oauth_token' | 'partner_webhook_sync';
@@ -107,6 +107,9 @@ interface TransferAmountLimits {
     min?: string | number;
     max?: string | number;
 }
+interface MoneyAmountOptions {
+    allowNumber?: boolean;
+}
 interface CreateTransferIdempotencyKeyOptions {
     partnerUserId: string;
     type: TransferType;
@@ -121,6 +124,14 @@ interface TransferIntent {
     amount: string | number;
     category?: TransferCategory | null;
 }
+type ConnectTransferDirection = 'user_to_partner' | 'partner_to_user';
+interface TransferStatusMapping<TPartnerState extends string = string> {
+    pending_verification: TPartnerState;
+    processing: TPartnerState;
+    completed: TPartnerState;
+    failed: TPartnerState;
+    expired: TPartnerState;
+}
 interface StartTransferVerificationOptions {
     transfer: TransferOptions;
     origin: string;
@@ -129,10 +140,18 @@ interface StartTransferVerificationResult {
     transfer: Transfer;
     verificationSession: VerificationSession;
 }
-declare function normalizeMoneyAmount(value: string | number): string;
-declare function validateTransferAmount(value: string | number, limits?: TransferAmountLimits): string;
+declare const CONNECT_TRANSFER_DIRECTIONS: {
+    readonly debit: "user_to_partner";
+    readonly credit: "partner_to_user";
+};
+declare function getConnectTransferDirection(type: TransferType): ConnectTransferDirection;
+declare function normalizeMoneyAmount(value: string | number, options?: MoneyAmountOptions): string;
+declare function validateTransferAmount(value: string | number, limits?: TransferAmountLimits, options?: MoneyAmountOptions): string;
 declare function createTransferIdempotencyKey(options: CreateTransferIdempotencyKeyOptions): string;
 declare function assertSameTransferIntent(existing: TransferIntent, requested: TransferIntent): void;
+declare function fingerprintTransferIntent(intent: TransferIntent): string;
+declare function moneyAmountsEqual(left: string | number, right: string | number, options?: MoneyAmountOptions): boolean;
+declare function mapTransferStatusToPartnerState<TPartnerState extends string>(status: TransferStatus, mapping: TransferStatusMapping<TPartnerState>): TPartnerState;
 declare function startTransferVerification(client: Pick<EdgeUserClient, 'initiateTransfer' | 'createVerificationSession'>, options: StartTransferVerificationOptions): Promise<StartTransferVerificationResult>;
 
 /**
@@ -205,10 +224,22 @@ interface EdgeUserSessionOptions {
     refreshSkewMs?: number;
     now?: () => number;
     onRefresh?: (tokens: EdgeTokens) => Promise<void> | void;
+    onEvent?: (event: EdgeUserSessionEvent) => Promise<void> | void;
+    singleFlightRefresh?: boolean;
 }
 interface GetValidTokensOptions {
     forceRefresh?: boolean;
 }
+type EdgeUserSessionEventType = 'session.loaded' | 'session.refresh_started' | 'session.refresh_succeeded' | 'session.refresh_failed' | 'session.saved';
+interface EdgeUserSessionEvent {
+    type: EdgeUserSessionEventType;
+    subjectId: string;
+    refreshed?: boolean;
+    encrypted?: boolean;
+    expiresAt?: number;
+    scope?: string;
+    error?: string;
+}
 declare class EdgeUserSession {
     private readonly edge;
     private readonly subjectId;
@@ -217,15 +248,225 @@ declare class EdgeUserSession {
     private readonly refreshSkewMs;
     private readonly now;
     private readonly onRefresh?;
+    private readonly onEvent?;
+    private readonly singleFlightRefresh;
+    private refreshPromise;
     constructor(options: EdgeUserSessionOptions);
     getValidTokens(options?: GetValidTokensOptions): Promise<EdgeTokens>;
     getClient(options?: GetValidTokensOptions): Promise<EdgeUserClient>;
-    withClient<T>(callback: (client: EdgeUserClient, tokens: EdgeTokens) => Promise<T> | T): Promise<T>;
+    withClient<T>(callback: (client: EdgeUserClient, tokens: EdgeTokens) => Promise<T> | T, options?: GetValidTokensOptions): Promise<T>;
     saveTokens(tokens: EdgeTokens, refreshed?: boolean): Promise<void>;
     private loadTokens;
+    private refreshTokens;
+    private emitLoaded;
+    private emit;
 }
 declare function createEdgeUserSession(options: EdgeUserSessionOptions): EdgeUserSession;
 
+/**
+ * Webhook Signature Verification (SDK-001)
+ *
+ * HMAC-SHA256 verification for EDGE Connect webhook payloads.
+ *
+ * Signature header format: `t={timestamp},v1={hex_hmac}`
+ * Signed message: `{timestamp}.{raw_json_body}`
+ *
+ * The timestamp prefix prevents replay attacks — events older than the
+ * tolerance window (default 5 minutes) are rejected. The HMAC is verified
+ * with constant-time comparison to prevent timing attacks.
+ */
+/**
+ * Options for {@link verifyWebhookSignature}.
+ */
+interface VerifyWebhookSignatureOptions {
+    /**
+     * Maximum age of the signature timestamp, in seconds.
+     *
+     * Signatures older than this are rejected as potential replays.
+     * Defaults to 300 seconds (5 minutes), matching the producer.
+     */
+    toleranceSeconds?: number;
+}
+/**
+ * Verifies an EDGE Connect webhook signature.
+ *
+ * **Always pass the raw request body bytes** — never `JSON.stringify(req.body)`.
+ * Re-stringifying after the framework parses JSON will reorder keys, change
+ * whitespace, and silently break verification with no diagnostic. Capture
+ * the raw body via your framework's raw-body middleware:
+ *
+ * - Express: `express.raw({ type: 'application/json' })`
+ * - Fastify: built-in (use `request.rawBody`)
+ * - NestJS: `{ rawBody: true }` on `NestFactory.create` + `RawBodyRequest<Request>`
+ *
+ * @param header - The `X-Edge-Signature` header value (`t=...,v1=...`)
+ * @param body - The raw request body as a UTF-8 string (NOT a parsed object)
+ * @param secret - The partner's webhook signing secret
+ * @param options - Optional overrides
+ * @returns `true` if the signature is valid and within the tolerance window,
+ *          `false` otherwise. Never throws — malformed input returns `false`.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from '@edge-markets/connect-node'
+ *
+ * app.post('/webhooks/edge', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const ok = verifyWebhookSignature(
+ *     req.headers['x-edge-signature'] as string,
+ *     req.body.toString('utf8'),
+ *     process.env.EDGE_WEBHOOK_SECRET!,
+ *   )
+ *
+ *   if (!ok) return res.status(401).send('invalid signature')
+ *
+ *   const event = JSON.parse(req.body.toString('utf8'))
+ *   // ... process event
+ *   res.status(200).send('ok')
+ * })
+ * ```
+ */
+declare function verifyWebhookSignature(header: string, body: string, secret: string, options?: VerifyWebhookSignatureOptions): boolean;
+
+type EdgeWebhookRawBody = string | Buffer | Uint8Array;
+type EdgeWebhookSignatureHeader = string | string[] | undefined | null;
+interface ParseAndVerifyWebhookOptions extends VerifyWebhookSignatureOptions {
+    rawBody: EdgeWebhookRawBody;
+    signatureHeader: EdgeWebhookSignatureHeader;
+    secret: string;
+    receivedAt?: Date;
+}
+interface ParsedEdgeWebhook {
+    event: EdgeWebhookEvent;
+    eventId: string;
+    eventType: EdgeWebhookEventType;
+    signatureTimestamp: number;
+    receivedAt: Date;
+}
+declare function parseAndVerifyWebhook(options: ParseAndVerifyWebhookOptions): ParsedEdgeWebhook;
+declare function extractWebhookSignatureTimestamp(header: EdgeWebhookSignatureHeader): number | undefined;
+declare function isEdgeWebhookEvent(value: unknown): value is EdgeWebhookEvent;
+declare function validateEdgeWebhookEvent(value: unknown): EdgeWebhookEvent;
+
+type WebhookInboxStatus = 'pending' | 'processing' | 'processed' | 'failed';
+type WebhookInboxSource = 'live_webhook' | 'sync';
+interface WebhookInboxRecord {
+    eventId: string;
+    eventType: EdgeWebhookEventType;
+    event: EdgeWebhookEvent;
+    payloadFingerprint: string;
+    status: WebhookInboxStatus;
+    source: WebhookInboxSource;
+    attempts: number;
+    receivedAt: Date;
+    updatedAt?: Date;
+    processedAt?: Date | null;
+    lastError?: string | null;
+    signatureTimestamp?: number | null;
+    signatureHeader?: string | null;
+    rawBody?: string | null;
+}
+interface WebhookInboxInsertRecord {
+    eventId: string;
+    eventType: EdgeWebhookEventType;
+    event: EdgeWebhookEvent;
+    payloadFingerprint: string;
+    source: WebhookInboxSource;
+    receivedAt: Date;
+    signatureTimestamp?: number | null;
+    signatureHeader?: string | null;
+    rawBody?: string | null;
+}
+type WebhookInboxInsertResult = {
+    inserted: true;
+    record: WebhookInboxRecord;
+} | {
+    inserted: false;
+    record: WebhookInboxRecord;
+};
+interface WebhookInboxListOptions {
+    status?: WebhookInboxStatus;
+    updatedBefore?: Date;
+    limit?: number;
+}
+interface WebhookInboxStore {
+    insert: (record: WebhookInboxInsertRecord) => Promise<WebhookInboxInsertResult> | WebhookInboxInsertResult;
+    find: (eventId: string) => Promise<WebhookInboxRecord | null | undefined> | WebhookInboxRecord | null | undefined;
+    markProcessing: (eventId: string, context: {
+        now: Date;
+    }) => Promise<WebhookInboxRecord | null | undefined> | WebhookInboxRecord | null | undefined;
+    markProcessed: (eventId: string, context: {
+        now: Date;
+    }) => Promise<WebhookInboxRecord | null | undefined> | WebhookInboxRecord | null | undefined;
+    markFailed: (eventId: string, context: {
+        now: Date;
+        error: string;
+    }) => Promise<WebhookInboxRecord | null | undefined> | WebhookInboxRecord | null | undefined;
+    markPending?: (eventId: string, context: {
+        now: Date;
+        reason: string;
+    }) => Promise<WebhookInboxRecord | null | undefined> | WebhookInboxRecord | null | undefined;
+    list?: (options: WebhookInboxListOptions) => Promise<WebhookInboxRecord[]> | WebhookInboxRecord[];
+}
+interface WebhookInboxOptions {
+    store: WebhookInboxStore;
+    processEvent: (event: EdgeWebhookEvent, record: WebhookInboxRecord) => Promise<void> | void;
+    now?: () => Date;
+    storeRawBody?: boolean;
+    processingTimeoutMs?: number;
+    onEvent?: (event: WebhookInboxLifecycleEvent) => Promise<void> | void;
+}
+interface WebhookInboxLifecycleEvent {
+    type: 'webhook.accepted' | 'webhook.duplicate' | 'webhook.payload_mismatch' | 'webhook.processing_started' | 'webhook.processing_succeeded' | 'webhook.processing_failed' | 'webhook.recovered_stale';
+    eventId: string;
+    eventType?: EdgeWebhookEventType;
+    status?: WebhookInboxStatus;
+    source?: WebhookInboxSource;
+    attempts?: number;
+    error?: string;
+}
+interface WebhookInboxAcceptResult {
+    eventId: string;
+    eventType: EdgeWebhookEventType;
+    inserted: boolean;
+    duplicate: boolean;
+    status: WebhookInboxStatus;
+    record: WebhookInboxRecord;
+}
+interface WebhookInboxProcessResult {
+    eventId: string;
+    status: WebhookInboxStatus;
+    processed: boolean;
+    skipped: boolean;
+    reason?: 'already_processed' | 'not_found' | 'locked';
+    record?: WebhookInboxRecord;
+}
+interface WebhookInboxRecoverResult {
+    recovered: number;
+    skipped: boolean;
+    reason?: 'list_not_configured' | 'mark_pending_not_configured';
+}
+declare class EdgeWebhookInbox {
+    private readonly store;
+    private readonly processEvent;
+    private readonly now;
+    private readonly storeRawBody;
+    private readonly processingTimeoutMs;
+    private readonly onEvent?;
+    constructor(options: WebhookInboxOptions);
+    accept(parsed: ParsedEdgeWebhook): Promise<WebhookInboxAcceptResult>;
+    acceptRaw(parsed: ParsedEdgeWebhook, rawBody: string, signatureHeader: string): Promise<WebhookInboxAcceptResult>;
+    acceptSyncedEvent(event: EdgeWebhookEvent, receivedAt?: Date): Promise<WebhookInboxAcceptResult>;
+    process(eventId: string, options?: {
+        force?: boolean;
+    }): Promise<WebhookInboxProcessResult>;
+    replay(eventId: string): Promise<WebhookInboxProcessResult>;
+    recoverStaleProcessing(): Promise<WebhookInboxRecoverResult>;
+    private acceptEvent;
+    private emit;
+}
+declare function createWebhookInbox(options: WebhookInboxOptions): EdgeWebhookInbox;
+declare function fingerprintWebhookEvent(event: EdgeWebhookEvent): string;
+
 interface WebhookReconcilerCursorStore {
     load: () => Promise<string | null | undefined> | string | null | undefined;
     save: (cursor: string) => Promise<void> | void;
@@ -233,12 +474,15 @@ interface WebhookReconcilerCursorStore {
 interface WebhookReconcilerOptions {
     edge: Pick<EdgeConnectServer, 'syncWebhookEvents'>;
     cursorStore: WebhookReconcilerCursorStore;
-    processEvent: (event: EdgeWebhookEvent) => Promise<void> | void;
+    processEvent?: (event: EdgeWebhookEvent) => Promise<void> | void;
+    inbox?: Pick<EdgeWebhookInbox, 'acceptSyncedEvent' | 'process'>;
     limit?: SyncWebhookEventsOptions['limit'];
     maxPages?: number;
 }
 interface WebhookReconcilerRunResult {
     processed: number;
+    accepted?: number;
+    duplicates?: number;
     pages: number;
     cursor?: string;
     hasMore: boolean;
@@ -437,6 +681,19 @@ interface EdgeHttpError {
 declare function toEdgeHttpError(error: unknown): EdgeHttpError;
 declare function toEdgeProblemJson(error: unknown): EdgeProblemJson;
 
+interface EdgeWebhookHttpRequestLike {
+    headers?: Record<string, unknown>;
+    rawBody?: Buffer | Uint8Array | string;
+    body?: unknown;
+}
+interface ParseWebhookHttpRequestOptions extends Omit<ParseAndVerifyWebhookOptions, 'rawBody' | 'signatureHeader'> {
+    request: EdgeWebhookHttpRequestLike;
+    signatureHeaderName?: string;
+}
+declare function getEdgeWebhookRawBody(request: EdgeWebhookHttpRequestLike): EdgeWebhookRawBody;
+declare function getEdgeWebhookSignatureHeader(request: EdgeWebhookHttpRequestLike, headerName?: string): EdgeWebhookSignatureHeader;
+declare function parseWebhookHttpRequest(options: ParseWebhookHttpRequestOptions): ParsedEdgeWebhook;
+
 interface PartnerIdentityAddress {
     street?: string | null;
     line1?: string | null;
@@ -467,6 +724,43 @@ interface IdentityPolicyEvaluation {
 declare function buildVerifyIdentityPayload(profile: PartnerIdentityProfile): VerifyIdentityOptions;
 declare function evaluateIdentityResult(result: VerifyIdentityResult, policy?: IdentityPolicy): IdentityPolicyEvaluation;
 
+interface EdgeSessionTokenRecord {
+    subjectId: string;
+    encryptedTokens: string;
+    expiresAt: number;
+    scopes?: string[];
+    edgeUserId?: string;
+    keyId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateSessionTokenRecordOptions {
+    scopes?: string[];
+    edgeUserId?: string;
+    keyId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface LegacySessionTokenRecord {
+    subjectId?: string;
+    accessToken?: string | null;
+    refreshToken?: string | null;
+    idToken?: string | null;
+    expiresAt?: unknown;
+    expiresIn?: unknown;
+    scope?: unknown;
+    scopes?: unknown;
+    edgeUserId?: string | null;
+    metadata?: Record<string, unknown>;
+}
+interface EncryptLegacySessionTokensOptions {
+    subjectId: string;
+    keyId?: string;
+    allowPlaintext?: boolean;
+}
+declare function createSessionTokenRecord(subjectId: string, tokens: EdgeTokens, tokenVault: Pick<EdgeTokenVault, 'encryptTokens'>, options?: CreateSessionTokenRecordOptions): EdgeSessionTokenRecord;
+declare function parseSessionTokenRecord(record: unknown): EdgeSessionTokenRecord;
+declare function encryptLegacySessionTokens(legacyRecord: LegacySessionTokenRecord, tokenVault: Pick<EdgeTokenVault, 'encryptTokens' | 'isEncrypted'>, options: EncryptLegacySessionTokensOptions): EdgeSessionTokenRecord;
+declare function normalizeSessionExpiresAt(value: unknown): number;
+
 interface TransferWebhookIntent {
     transferId: string;
     type?: TransferType;
@@ -477,89 +771,6 @@ declare function isTransferWebhookEvent(event: EdgeWebhookEvent): event is Extra
     type: `transfer.${string}`;
 }>;
 declare function assertTransferEventMatchesIntent(event: EdgeWebhookEvent, intent: TransferWebhookIntent): void;
+declare const assertWebhookMatchesTransfer: typeof assertTransferEventMatchesIntent;
 
-/**
- * Webhook Signature Verification (SDK-001)
- *
- * HMAC-SHA256 verification for EDGE Connect webhook payloads.
- *
- * Signature header format: `t={timestamp},v1={hex_hmac}`
- * Signed message: `{timestamp}.{raw_json_body}`
- *
- * The timestamp prefix prevents replay attacks — events older than the
- * tolerance window (default 5 minutes) are rejected. The HMAC is verified
- * with constant-time comparison to prevent timing attacks.
- */
-/**
- * Options for {@link verifyWebhookSignature}.
- */
-interface VerifyWebhookSignatureOptions {
-    /**
-     * Maximum age of the signature timestamp, in seconds.
-     *
-     * Signatures older than this are rejected as potential replays.
-     * Defaults to 300 seconds (5 minutes), matching the producer.
-     */
-    toleranceSeconds?: number;
-}
-/**
- * Verifies an EDGE Connect webhook signature.
- *
- * **Always pass the raw request body bytes** — never `JSON.stringify(req.body)`.
- * Re-stringifying after the framework parses JSON will reorder keys, change
- * whitespace, and silently break verification with no diagnostic. Capture
- * the raw body via your framework's raw-body middleware:
- *
- * - Express: `express.raw({ type: 'application/json' })`
- * - Fastify: built-in (use `request.rawBody`)
- * - NestJS: `{ rawBody: true }` on `NestFactory.create` + `RawBodyRequest<Request>`
- *
- * @param header - The `X-Edge-Signature` header value (`t=...,v1=...`)
- * @param body - The raw request body as a UTF-8 string (NOT a parsed object)
- * @param secret - The partner's webhook signing secret
- * @param options - Optional overrides
- * @returns `true` if the signature is valid and within the tolerance window,
- *          `false` otherwise. Never throws — malformed input returns `false`.
- *
- * @example
- * ```typescript
- * import { verifyWebhookSignature } from '@edge-markets/connect-node'
- *
- * app.post('/webhooks/edge', express.raw({ type: 'application/json' }), (req, res) => {
- *   const ok = verifyWebhookSignature(
- *     req.headers['x-edge-signature'] as string,
- *     req.body.toString('utf8'),
- *     process.env.EDGE_WEBHOOK_SECRET!,
- *   )
- *
- *   if (!ok) return res.status(401).send('invalid signature')
- *
- *   const event = JSON.parse(req.body.toString('utf8'))
- *   // ... process event
- *   res.status(200).send('ok')
- * })
- * ```
- */
-declare function verifyWebhookSignature(header: string, body: string, secret: string, options?: VerifyWebhookSignatureOptions): boolean;
-
-type EdgeWebhookRawBody = string | Buffer | Uint8Array;
-type EdgeWebhookSignatureHeader = string | string[] | undefined | null;
-interface ParseAndVerifyWebhookOptions extends VerifyWebhookSignatureOptions {
-    rawBody: EdgeWebhookRawBody;
-    signatureHeader: EdgeWebhookSignatureHeader;
-    secret: string;
-    receivedAt?: Date;
-}
-interface ParsedEdgeWebhook {
-    event: EdgeWebhookEvent;
-    eventId: string;
-    eventType: EdgeWebhookEventType;
-    signatureTimestamp: number;
-    receivedAt: Date;
-}
-declare function parseAndVerifyWebhook(options: ParseAndVerifyWebhookOptions): ParsedEdgeWebhook;
-declare function extractWebhookSignatureTimestamp(header: EdgeWebhookSignatureHeader): number | undefined;
-declare function isEdgeWebhookEvent(value: unknown): value is EdgeWebhookEvent;
-declare function validateEdgeWebhookEvent(value: unknown): EdgeWebhookEvent;
-
-export { type CreateEdgeConnectServerFromEnvOptions, type CreateTransferIdempotencyKeyOptions, type EdgeConnectEnv, EdgeConnectServer, type EdgeConnectServerConfig, type EdgeConnectServerFromEnvCapabilities, type EdgeConnectServerFromEnvResult, type EdgeHttpError, type EdgeProblemJson, type EdgeTokenStore, type EdgeTokenStoreSaveContext, type EdgeTokenStoreValue, EdgeTokenVault, type EdgeTokenVaultKey, type EdgeTokenVaultKeyMaterial, type EdgeTokenVaultOptions, EdgeUserClient, EdgeUserSession, type EdgeUserSessionOptions, type EdgeWebhookRawBody, EdgeWebhookReconciler, type EdgeWebhookSignatureHeader, type GetValidTokensOptions, type IdentityPolicy, type IdentityPolicyEvaluation, type MtlsConfig, type ParseAndVerifyWebhookOptions, type ParsedEdgeWebhook, type PartnerIdentityAddress, type PartnerIdentityProfile, type RequestInfo, type ResponseInfo, type RetryConfig, type StartTransferVerificationOptions, type StartTransferVerificationResult, type SyncWebhookEventsOptions, type SyncWebhookEventsResult, type TransferAmountLimits, type TransferIntent, type TransferOptions, type TransferWebhookIntent, type VerifyWebhookSignatureOptions, type WebhookReconcilerCursorStore, type WebhookReconcilerOptions, type WebhookReconcilerRunResult, assertSameTransferIntent, assertTransferEventMatchesIntent, buildVerifyIdentityPayload, createEdgeConnectServerFromEnv, createEdgeTokenVault, createEdgeUserSession, createTransferIdempotencyKey, createWebhookReconciler, evaluateIdentityResult, extractWebhookSignatureTimestamp, isEdgeTokenVaultEnvelope, isEdgeWebhookEvent, isTransferWebhookEvent, normalizeMoneyAmount, parseAndVerifyWebhook, startTransferVerification, toEdgeHttpError, toEdgeProblemJson, validateEdgeWebhookEvent, validateTransferAmount, verifyWebhookSignature };
+export { CONNECT_TRANSFER_DIRECTIONS, type ConnectTransferDirection, type CreateEdgeConnectServerFromEnvOptions, type CreateSessionTokenRecordOptions, type CreateTransferIdempotencyKeyOptions, type EdgeConnectEnv, EdgeConnectServer, type EdgeConnectServerConfig, type EdgeConnectServerFromEnvCapabilities, type EdgeConnectServerFromEnvResult, type EdgeHttpError, type EdgeProblemJson, type EdgeSessionTokenRecord, type EdgeTokenStore, type EdgeTokenStoreSaveContext, type EdgeTokenStoreValue, EdgeTokenVault, type EdgeTokenVaultKey, type EdgeTokenVaultKeyMaterial, type EdgeTokenVaultOptions, EdgeUserClient, EdgeUserSession, type EdgeUserSessionEvent, type EdgeUserSessionEventType, type EdgeUserSessionOptions, type EdgeWebhookHttpRequestLike, EdgeWebhookInbox, type EdgeWebhookRawBody, EdgeWebhookReconciler, type EdgeWebhookSignatureHeader, type EncryptLegacySessionTokensOptions, type GetValidTokensOptions, type IdentityPolicy, type IdentityPolicyEvaluation, type LegacySessionTokenRecord, type MoneyAmountOptions, type MtlsConfig, type ParseAndVerifyWebhookOptions, type ParseWebhookHttpRequestOptions, type ParsedEdgeWebhook, type PartnerIdentityAddress, type PartnerIdentityProfile, type RequestInfo, type ResponseInfo, type RetryConfig, type StartTransferVerificationOptions, type StartTransferVerificationResult, type SyncWebhookEventsOptions, type SyncWebhookEventsResult, type TransferAmountLimits, type TransferIntent, type TransferOptions, type TransferStatusMapping, type TransferWebhookIntent, type VerifyWebhookSignatureOptions, type WebhookInboxAcceptResult, type WebhookInboxInsertRecord, type WebhookInboxInsertResult, type WebhookInboxLifecycleEvent, type WebhookInboxListOptions, type WebhookInboxOptions, type WebhookInboxProcessResult, type WebhookInboxRecord, type WebhookInboxRecoverResult, type WebhookInboxSource, type WebhookInboxStatus, type WebhookInboxStore, type WebhookReconcilerCursorStore, type WebhookReconcilerOptions, type WebhookReconcilerRunResult, assertSameTransferIntent, assertTransferEventMatchesIntent, assertWebhookMatchesTransfer, buildVerifyIdentityPayload, createEdgeConnectServerFromEnv, createEdgeTokenVault, createEdgeUserSession, createSessionTokenRecord, createTransferIdempotencyKey, createWebhookInbox, createWebhookReconciler, encryptLegacySessionTokens, evaluateIdentityResult, extractWebhookSignatureTimestamp, fingerprintTransferIntent, fingerprintWebhookEvent, getConnectTransferDirection, getEdgeWebhookRawBody, getEdgeWebhookSignatureHeader, isEdgeTokenVaultEnvelope, isEdgeWebhookEvent, isTransferWebhookEvent, mapTransferStatusToPartnerState, moneyAmountsEqual, normalizeMoneyAmount, normalizeSessionExpiresAt, parseAndVerifyWebhook, parseSessionTokenRecord, parseWebhookHttpRequest, startTransferVerification, toEdgeHttpError, toEdgeProblemJson, validateEdgeWebhookEvent, validateTransferAmount, verifyWebhookSignature };