@xkova/sdk 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/workforce-bff.d.ts

@@ -0,0 +1,202 @@
+import { type XKOVAClientOptions } from './client.js';
+import { WorkforceWalletsResource } from './resources/workforce-wallets.js';
+export { serializeXKOVAMemberSessionCookie as serializeXKOVAWorkforceSessionCookie, serializeXKOVAMemberFlowCookie as serializeXKOVAWorkforceFlowCookie, serializeClearedXKOVAMemberCookie as serializeClearedXKOVAWorkforceCookie, readXKOVAMemberCookie as readXKOVAWorkforceCookie, readXKOVAMemberCallbackFlow as readXKOVAWorkforceCallbackFlow, xkovaMemberFlowCookieName as xkovaWorkforceFlowCookieName, createXKOVAMemberCsrfToken as createXKOVAWorkforceCsrfToken, verifyXKOVAMemberCsrfToken as verifyXKOVAWorkforceCsrfToken, assertXKOVAMemberRequestOrigin as assertXKOVAWorkforceRequestOrigin, } from './member-bff.js';
+export interface XKOVAWorkforceBffClientOptions extends XKOVAClientOptions {
+    /** Exact nonsecret workforce registration selector. This is not a member selector. */
+    readonly workforceKey: string;
+}
+export interface XKOVAWorkforceSession {
+    readonly session_id: string;
+    readonly application_id: string;
+    readonly staff_id: string;
+    readonly person_id: string;
+    readonly tenant_id: string;
+    readonly workspace_id: string;
+    readonly provider_namespace: string;
+    readonly provider_subject: string;
+    readonly roles: readonly string[];
+    readonly scopes: readonly string[];
+    readonly resource_grants: {
+        readonly treasury_wallet_ids: readonly string[];
+        readonly customer_token_ids: readonly string[];
+    };
+    readonly action_authorization_enabled: boolean;
+    readonly expires_at: string;
+    readonly absolute_expires_at: string;
+}
+export interface XKOVAWorkforceSessionMaterial {
+    readonly session_token: string;
+    readonly refresh_token: string;
+    readonly refresh_attempt_token: string;
+    readonly session: XKOVAWorkforceSession;
+}
+export interface XKOVAWorkforceActionReview {
+    readonly operation: string;
+    readonly proof_method: string;
+    readonly review: Readonly<Record<string, unknown>>;
+    readonly review_digest: string;
+    readonly expires_at: string;
+}
+export interface XKOVAWorkforceActionChallenge {
+    readonly nonce: string;
+    readonly issuer: string;
+    readonly audience: string;
+    readonly authorization_endpoint: string;
+    readonly max_auth_age_seconds: number;
+    readonly required_acr_values: readonly string[];
+    readonly required_amr_values: readonly string[];
+    readonly expires_at: string;
+    readonly review: Readonly<Record<string, unknown>>;
+    readonly review_digest: string;
+}
+/** Confidential, one-use authority for the unchanged reviewed request only. */
+export interface XKOVAWorkforceActionGrant {
+    readonly grant_token: string;
+    readonly expires_at: string;
+}
+export interface StoredXKOVAWorkforceSession<T = unknown> {
+    readonly clientFingerprint: string;
+    readonly authorizationCodeHash: string;
+    readonly material: XKOVAWorkforceSessionMaterial;
+    readonly applicationExpiresAt: number;
+    readonly applicationData: T;
+    /** Persist before remote logout. It permanently blocks refresh and resource resolution. */
+    readonly logoutPending?: boolean;
+}
+/**
+ * Encrypt credentials and proofs at rest. All writes commit before resolving,
+ * independently of later callback errors. replace is exact-existing-only.
+ * runExclusive serializes the same record across every BFF replica. It is not
+ * a surrounding rollback transaction. Use separate transaction/session stores.
+ */
+export interface XKOVAWorkforceStore<T> {
+    put(reference: string, value: T): Promise<void>;
+    get(reference: string): Promise<T | null>;
+    replace(reference: string, value: T): Promise<void>;
+    delete(reference: string): Promise<void>;
+    runExclusive<R>(reference: string, work: () => Promise<R>): Promise<R>;
+}
+export interface XKOVAWorkforceAuthorizationTransaction<T = unknown> {
+    readonly clientFingerprint: string;
+    readonly status: 'pending' | 'completed';
+    readonly redirectUri: string;
+    readonly codeVerifier: string;
+    readonly codeChallenge: string;
+    readonly exchangeAttemptId: string;
+    readonly sessionReference: string;
+    readonly expiresAt: number;
+    readonly transactionId?: string;
+    readonly nonce?: string;
+    readonly issuer?: string;
+    readonly audience?: string;
+    /** Written before the one-use provider call. An unknown result is never redeemed again. */
+    readonly providerExchangeStarted?: {
+        readonly codeHash: string;
+        readonly applicationData: T;
+    };
+    readonly stagedProofToken?: string;
+}
+export declare class XKOVAWorkforceBffError extends Error {
+    readonly code: 'transaction_unavailable' | 'binding_mismatch' | 'provider_exchange_outcome_unknown' | 'session_unavailable';
+    constructor(code: 'transaction_unavailable' | 'binding_mismatch' | 'provider_exchange_outcome_unknown' | 'session_unavailable');
+}
+/** Confidential workforce protocol. It neither enrolls a subject nor creates local staff authority. */
+export declare class XKOVAWorkforceBffClient {
+    private readonly options;
+    private readonly client;
+    private readonly fingerprint;
+    constructor(options: XKOVAWorkforceBffClientOptions);
+    beginAuthorization<T>(input: {
+        browserOrigin: string;
+        redirectUri: string;
+        transactionStore: XKOVAWorkforceStore<XKOVAWorkforceAuthorizationTransaction<T>>;
+    }): Promise<{
+        state: string;
+        nonce: string;
+        redirectUri: string;
+        codeChallenge: string;
+        codeChallengeMethod: "S256";
+        issuer: string;
+        audience: string;
+        authorizationEndpoint: string;
+        maxAuthAgeSeconds: number;
+        requiredAcrValues: string[];
+        expiresAt: string;
+    }>;
+    completeAuthorizationCallback<T>(input: {
+        callbackUrl: string;
+        /** Read from the genuine initiating browser's HttpOnly flow cookie. */
+        expectedState: string;
+        transactionStore: XKOVAWorkforceStore<XKOVAWorkforceAuthorizationTransaction<T>>;
+        sessionStore: XKOVAWorkforceStore<StoredXKOVAWorkforceSession<T>>;
+        applicationData: T;
+        /** Perform the provider's real code exchange and signature/nonce checks server-side. */
+        exchangeProviderCode: (input: {
+            code: string;
+            codeVerifier: string;
+            redirectUri: string;
+            expectedNonce: string;
+            issuer: string;
+            audience: string;
+        }) => Promise<{
+            proofToken: string;
+        }>;
+    }): Promise<{
+        reference: string;
+        session: StoredXKOVAWorkforceSession<T>;
+    }>;
+    getSession(sessionToken: string): Promise<XKOVAWorkforceSession>;
+    resolveSession<T>(input: {
+        reference: string;
+        sessionStore: XKOVAWorkforceStore<StoredXKOVAWorkforceSession<T>>;
+    }): Promise<StoredXKOVAWorkforceSession<T> | null>;
+    /** Request-scoped resources only. Check the browser's Origin/CSRF before invoking writes. */
+    resolveResources<T>(input: {
+        reference: string;
+        sessionStore: XKOVAWorkforceStore<StoredXKOVAWorkforceSession<T>>;
+        browserOrigin: string;
+        /** Keep the API-issued grant on the server and repeat only its frozen request. */
+        actionGrant?: XKOVAWorkforceActionGrant;
+    }): Promise<{
+        session: StoredXKOVAWorkforceSession<T>;
+        resources: {
+            treasury: import("./resources/treasury.js").TreasuryResource;
+            tokenization: import("./resources/index.js").TokenizationResource;
+            wallets: WorkforceWalletsResource;
+        };
+    } | null>;
+    /** Review the locator returned by human_authorization_required. Never send it to a third-party host. */
+    inspectAction(input: {
+        authorizationToken: string;
+        sessionToken: string;
+        browserOrigin: string;
+    }): Promise<XKOVAWorkforceActionReview>;
+    /** Starts a real provider ceremony after the user reviews the exact request. No action is executed. */
+    beginActionProof(input: {
+        authorizationToken: string;
+        sessionToken: string;
+        browserOrigin: string;
+    }): Promise<XKOVAWorkforceActionChallenge>;
+    /** Submit the real, freshly verified provider token. A lost response is never automatically retried. */
+    completeActionProof(input: {
+        authorizationToken: string;
+        sessionToken: string;
+        browserOrigin: string;
+        nonce: string;
+        proofToken: string;
+    }): Promise<XKOVAWorkforceActionGrant>;
+    logoutSession<T>(input: {
+        reference: string;
+        sessionStore: XKOVAWorkforceStore<StoredXKOVAWorkforceSession<T>>;
+    }): Promise<void>;
+    private assertSession;
+    private postJson;
+    private getJson;
+}
+/** Advisory browser UI data only; provider identity, credentials and grants stay confidential. */
+export declare function projectXKOVAWorkforceSession(value: StoredXKOVAWorkforceSession): {
+    signedIn: true;
+    staffId: string;
+    roles: string[];
+    expiresAt: string;
+};

package/dist/workforce-bff.js

@@ -0,0 +1,462 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { XKOVAClient } from './client.js';
+import { XKOVAApiError } from './errors.js';
+import { isAllowedProtocol } from './url.js';
+import { WorkforceWalletsResource } from './resources/workforce-wallets.js';
+// These helpers operate only on a customer's cookie/reference and CSRF proof.
+// Reusing their cryptography does not reuse member identity or session authority.
+export { serializeXKOVAMemberSessionCookie as serializeXKOVAWorkforceSessionCookie, serializeXKOVAMemberFlowCookie as serializeXKOVAWorkforceFlowCookie, serializeClearedXKOVAMemberCookie as serializeClearedXKOVAWorkforceCookie, readXKOVAMemberCookie as readXKOVAWorkforceCookie, readXKOVAMemberCallbackFlow as readXKOVAWorkforceCallbackFlow, xkovaMemberFlowCookieName as xkovaWorkforceFlowCookieName, createXKOVAMemberCsrfToken as createXKOVAWorkforceCsrfToken, verifyXKOVAMemberCsrfToken as verifyXKOVAWorkforceCsrfToken, assertXKOVAMemberRequestOrigin as assertXKOVAWorkforceRequestOrigin, } from './member-bff.js';
+export class XKOVAWorkforceBffError extends Error {
+    code;
+    constructor(code) {
+        super('The workforce sign-in or session cannot safely continue. Start sign-in again.');
+        this.code = code;
+        this.name = 'XKOVAWorkforceBffError';
+    }
+}
+/** Confidential workforce protocol. It neither enrolls a subject nor creates local staff authority. */
+export class XKOVAWorkforceBffClient {
+    options;
+    client;
+    fingerprint;
+    constructor(options) {
+        this.options = options;
+        if (!/^xkova_wf_[A-Za-z0-9_-]{43}$/.test(options.workforceKey)) {
+            throw new TypeError('Invalid workforce application selector');
+        }
+        this.client = XKOVAClient.forTenant(options);
+        const origin = new URL(options.baseUrl).origin;
+        this.fingerprint = digest(JSON.stringify([origin, options.apiKey, options.workforceKey]));
+    }
+    async beginAuthorization(input) {
+        const origin = new URL(input.browserOrigin);
+        const callback = exactCallback(input.redirectUri);
+        if (origin.origin !== input.browserOrigin ||
+            !isAllowedProtocol(origin) ||
+            callback.origin !== origin.origin) {
+            throw new TypeError('Workforce callback must belong to the exact application origin');
+        }
+        const state = random(), codeVerifier = random();
+        const transaction = {
+            clientFingerprint: this.fingerprint,
+            status: 'pending',
+            redirectUri: callback.href,
+            codeVerifier,
+            codeChallenge: digest(codeVerifier),
+            exchangeAttemptId: random(),
+            sessionReference: random(),
+            expiresAt: Date.now() + 300_000,
+        };
+        const key = digest(state);
+        await input.transactionStore.put(key, transaction);
+        const result = object(await this.postJson('/workforce-auth/transactions', {
+            browser_origin: origin.origin,
+            redirect_uri: callback.href,
+            code_challenge: transaction.codeChallenge,
+            code_challenge_method: 'S256',
+        }, transaction.exchangeAttemptId));
+        const expiresAt = timestamp(result, 'expires_at');
+        if (expiresAt <= Date.now() || expiresAt > transaction.expiresAt + 5_000)
+            throw new Error('Invalid workforce transaction lifetime');
+        const issuer = text(result, 'issuer');
+        secureUrl(issuer);
+        const authorizationEndpoint = secureUrl(text(result, 'authorization_endpoint')).href;
+        const audience = text(result, 'audience'), nonce = text(result, 'nonce');
+        opaque(nonce);
+        const maxAuthAgeSeconds = result.max_auth_age_seconds;
+        if (!Number.isSafeInteger(maxAuthAgeSeconds) || Number(maxAuthAgeSeconds) < 1)
+            throw new Error('Invalid workforce authentication policy');
+        const requiredAcrValues = strings(result.required_acr_values);
+        const bound = {
+            ...transaction,
+            transactionId: text(result, 'transaction_id'),
+            nonce,
+            issuer,
+            audience,
+            expiresAt,
+        };
+        await input.transactionStore.replace(key, bound);
+        return {
+            state,
+            nonce,
+            redirectUri: callback.href,
+            codeChallenge: transaction.codeChallenge,
+            codeChallengeMethod: 'S256',
+            issuer,
+            audience,
+            authorizationEndpoint,
+            maxAuthAgeSeconds: Number(maxAuthAgeSeconds),
+            requiredAcrValues,
+            expiresAt: new Date(expiresAt).toISOString(),
+        };
+    }
+    async completeAuthorizationCallback(input) {
+        const callback = secureUrl(input.callbackUrl), states = callback.searchParams.getAll('state');
+        opaque(input.expectedState);
+        if (states.length !== 1 ||
+            !equal(states[0], input.expectedState) ||
+            callback.searchParams.has('error')) {
+            throw new XKOVAWorkforceBffError('binding_mismatch');
+        }
+        const codes = callback.searchParams.getAll('code');
+        if (codes.length !== 1 || !codes[0] || codes[0].length > 8192)
+            throw new XKOVAWorkforceBffError('binding_mismatch');
+        const code = codes[0], codeHash = digest(code), key = digest(input.expectedState);
+        return input.transactionStore.runExclusive(key, async () => {
+            const initial = await input.transactionStore.get(key);
+            if (!initial ||
+                initial.expiresAt <= Date.now() ||
+                initial.clientFingerprint !== this.fingerprint ||
+                callback.origin + callback.pathname !== initial.redirectUri) {
+                throw new XKOVAWorkforceBffError('transaction_unavailable');
+            }
+            if (initial.providerExchangeStarted &&
+                initial.providerExchangeStarted.codeHash !== codeHash) {
+                throw new XKOVAWorkforceBffError('binding_mismatch');
+            }
+            const reference = initial.sessionReference;
+            return input.sessionStore.runExclusive(reference, async () => {
+                let transaction = initial;
+                if (transaction.stagedProofToken && !transaction.providerExchangeStarted) {
+                    throw new XKOVAWorkforceBffError('transaction_unavailable');
+                }
+                const existing = await input.sessionStore.get(reference);
+                if (existing) {
+                    this.assertSession(existing);
+                    if (existing.authorizationCodeHash !== codeHash || existing.logoutPending) {
+                        throw new XKOVAWorkforceBffError('session_unavailable');
+                    }
+                    await input.transactionStore.replace(key, { ...transaction, status: 'completed' });
+                    return { reference, session: existing };
+                }
+                if (transaction.status === 'completed' ||
+                    !transaction.transactionId ||
+                    !transaction.nonce ||
+                    !transaction.issuer ||
+                    !transaction.audience)
+                    throw new XKOVAWorkforceBffError('session_unavailable');
+                if (!transaction.stagedProofToken) {
+                    if (transaction.providerExchangeStarted)
+                        throw new XKOVAWorkforceBffError('provider_exchange_outcome_unknown');
+                    // Freeze application data before consuming a code. A later retry cannot replace it.
+                    transaction = {
+                        ...transaction,
+                        providerExchangeStarted: {
+                            codeHash,
+                            applicationData: JSON.parse(JSON.stringify({ value: input.applicationData })).value,
+                        },
+                    };
+                    await input.transactionStore.replace(key, transaction);
+                    const proof = await input.exchangeProviderCode({
+                        code,
+                        codeVerifier: transaction.codeVerifier,
+                        redirectUri: transaction.redirectUri,
+                        expectedNonce: transaction.nonce,
+                        issuer: transaction.issuer,
+                        audience: transaction.audience,
+                    });
+                    if (typeof proof.proofToken !== 'string' ||
+                        !proof.proofToken ||
+                        proof.proofToken.length > 65536) {
+                        throw new Error('Invalid workforce provider proof result');
+                    }
+                    transaction = { ...transaction, stagedProofToken: proof.proofToken };
+                    await input.transactionStore.replace(key, transaction);
+                }
+                const material = parseMaterial(await this.postJson('/workforce-auth/exchange', {
+                    transaction_id: transaction.transactionId,
+                    nonce: transaction.nonce,
+                    proof_token: transaction.stagedProofToken,
+                    exchange_attempt_id: transaction.exchangeAttemptId,
+                }, transaction.exchangeAttemptId));
+                const stored = {
+                    clientFingerprint: this.fingerprint,
+                    authorizationCodeHash: codeHash,
+                    material,
+                    applicationExpiresAt: timestamp(material.session, 'absolute_expires_at'),
+                    applicationData: transaction.providerExchangeStarted.applicationData,
+                };
+                await input.sessionStore.put(reference, stored);
+                await input.transactionStore.replace(key, { ...transaction, status: 'completed' });
+                return { reference, session: stored };
+            });
+        });
+    }
+    async getSession(sessionToken) {
+        credential(sessionToken, 'xwfs');
+        return parseSession(await this.getJson('/workforce-auth/session', sessionToken));
+    }
+    async resolveSession(input) {
+        opaque(input.reference);
+        return input.sessionStore.runExclusive(input.reference, async () => {
+            let stored = await input.sessionStore.get(input.reference);
+            if (!stored || stored.logoutPending)
+                return null;
+            this.assertSession(stored);
+            if (stored.applicationExpiresAt <= Date.now())
+                return null;
+            try {
+                if (timestamp(stored.material.session, 'expires_at') <= Date.now() + 30_000) {
+                    const material = parseMaterial(await this.postJson('/workforce-auth/refresh', {
+                        refresh_token: stored.material.refresh_token,
+                        refresh_attempt_token: stored.material.refresh_attempt_token,
+                    }));
+                    assertSameHuman(stored.material.session, material.session);
+                    stored = { ...stored, material };
+                    await input.sessionStore.replace(input.reference, stored);
+                }
+                const session = await this.getSession(stored.material.session_token);
+                assertSameHuman(stored.material.session, session);
+                stored = { ...stored, material: { ...stored.material, session } };
+                await input.sessionStore.replace(input.reference, stored);
+                return stored;
+            }
+            catch (error) {
+                if (error instanceof XKOVAApiError && (error.status === 401 || error.status === 403)) {
+                    await input.sessionStore.replace(input.reference, { ...stored, logoutPending: true });
+                    return null;
+                }
+                throw error;
+            }
+        });
+    }
+    /** Request-scoped resources only. Check the browser's Origin/CSRF before invoking writes. */
+    async resolveResources(input) {
+        const session = await this.resolveSession(input);
+        if (!session)
+            return null;
+        if (input.actionGrant) {
+            opaque(input.actionGrant.grant_token);
+            if (timestamp(input.actionGrant, 'expires_at') <= Date.now())
+                throw new XKOVAWorkforceBffError('session_unavailable');
+        }
+        const bound = XKOVAClient.forWorkforceSession(this.options, {
+            workforceKey: this.options.workforceKey,
+            sessionToken: session.material.session_token,
+            browserOrigin: input.browserOrigin,
+            ...(input.actionGrant && { humanAuthorization: input.actionGrant.grant_token }),
+        });
+        return {
+            session,
+            resources: {
+                treasury: bound.treasury,
+                tokenization: bound.tokenization,
+                wallets: new WorkforceWalletsResource(bound),
+            },
+        };
+    }
+    /** Review the locator returned by human_authorization_required. Never send it to a third-party host. */
+    async inspectAction(input) {
+        opaque(input.authorizationToken);
+        const raw = object(await this.getJson(`/workforce-auth/actions/${encodeURIComponent(input.authorizationToken)}`, input.sessionToken, input.browserOrigin));
+        text(raw, 'operation');
+        text(raw, 'proof_method');
+        object(raw.review);
+        validateReview(raw);
+        return raw;
+    }
+    /** Starts a real provider ceremony after the user reviews the exact request. No action is executed. */
+    async beginActionProof(input) {
+        opaque(input.authorizationToken);
+        const raw = object(await this.postJson(`/workforce-auth/actions/${encodeURIComponent(input.authorizationToken)}/begin`, undefined, undefined, input));
+        if (text(raw, 'nonce') !== input.authorizationToken)
+            throw new XKOVAWorkforceBffError('binding_mismatch');
+        secureUrl(text(raw, 'issuer'));
+        secureUrl(text(raw, 'authorization_endpoint'));
+        text(raw, 'audience');
+        const maxAge = raw.max_auth_age_seconds;
+        if (!Number.isSafeInteger(maxAge) || Number(maxAge) < 1 || Number(maxAge) > 300)
+            throw new Error('Invalid workforce action policy');
+        strings(raw.required_acr_values);
+        strings(raw.required_amr_values);
+        object(raw.review);
+        validateReview(raw);
+        return raw;
+    }
+    /** Submit the real, freshly verified provider token. A lost response is never automatically retried. */
+    async completeActionProof(input) {
+        opaque(input.authorizationToken);
+        if (input.nonce !== input.authorizationToken)
+            throw new XKOVAWorkforceBffError('binding_mismatch');
+        if (!input.proofToken || input.proofToken.length > 16384)
+            throw new TypeError('Invalid workforce action proof');
+        const raw = object(await this.postJson(`/workforce-auth/actions/${encodeURIComponent(input.authorizationToken)}/complete`, { nonce: input.nonce, proof_token: input.proofToken }, undefined, input));
+        opaque(text(raw, 'grant_token'));
+        if (timestamp(raw, 'expires_at') <= Date.now())
+            throw new XKOVAWorkforceBffError('session_unavailable');
+        return raw;
+    }
+    async logoutSession(input) {
+        opaque(input.reference);
+        await input.sessionStore.runExclusive(input.reference, async () => {
+            const stored = await input.sessionStore.get(input.reference);
+            if (!stored)
+                return;
+            this.assertSession(stored);
+            if (!stored.logoutPending)
+                await input.sessionStore.replace(input.reference, { ...stored, logoutPending: true });
+            await this.postJson('/workforce-auth/sign-out', {
+                session_token: stored.material.session_token,
+            });
+            await input.sessionStore.delete(input.reference);
+        });
+    }
+    assertSession(session) {
+        if (session.clientFingerprint !== this.fingerprint)
+            throw new XKOVAWorkforceBffError('binding_mismatch');
+    }
+    postJson(path, body, idempotencyKey, context) {
+        const client = context
+            ? XKOVAClient.forWorkforceSession(this.options, {
+                ...context,
+                workforceKey: this.options.workforceKey,
+            })
+            : this.client;
+        return client.requestJson({
+            method: 'POST',
+            path,
+            ...(body !== undefined && { body }),
+            headers: { 'X-XKOVA-Workforce-Key': this.options.workforceKey },
+            ...(idempotencyKey !== undefined && { idempotencyKey }),
+        });
+    }
+    getJson(path, sessionToken, browserOrigin) {
+        const client = browserOrigin
+            ? XKOVAClient.forWorkforceSession(this.options, {
+                sessionToken,
+                browserOrigin,
+                workforceKey: this.options.workforceKey,
+            })
+            : this.client;
+        return client.requestJson({
+            method: 'GET',
+            path,
+            headers: {
+                'X-XKOVA-Workforce-Key': this.options.workforceKey,
+                'X-Workforce-Session': sessionToken,
+            },
+        });
+    }
+}
+/** Advisory browser UI data only; provider identity, credentials and grants stay confidential. */
+export function projectXKOVAWorkforceSession(value) {
+    return {
+        signedIn: true,
+        staffId: value.material.session.staff_id,
+        roles: [...value.material.session.roles],
+        expiresAt: value.material.session.expires_at,
+    };
+}
+function parseMaterial(value) {
+    const raw = object(value);
+    const sessionToken = text(raw, 'session_token'), refreshToken = text(raw, 'refresh_token'), attempt = text(raw, 'refresh_attempt_token');
+    credential(sessionToken, 'xwfs');
+    credential(refreshToken, 'xwfr');
+    credential(attempt, 'xwfa');
+    return {
+        session_token: sessionToken,
+        refresh_token: refreshToken,
+        refresh_attempt_token: attempt,
+        session: parseSession(raw.session),
+    };
+}
+function parseSession(value) {
+    const raw = object(value), grants = object(raw.resource_grants);
+    for (const name of ['session_id', 'application_id', 'person_id', 'tenant_id', 'workspace_id']) {
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(text(raw, name))) {
+            throw new Error('Invalid workforce session identity');
+        }
+    }
+    if (!/^stf_[a-f0-9]{32}$/i.test(text(raw, 'staff_id')))
+        throw new Error('Invalid workforce staff identity');
+    const expires = timestamp(raw, 'expires_at'), absolute = timestamp(raw, 'absolute_expires_at');
+    if (expires > absolute || typeof raw.action_authorization_enabled !== 'boolean')
+        throw new Error('Invalid workforce session policy');
+    text(raw, 'provider_namespace');
+    text(raw, 'provider_subject');
+    strings(raw.roles);
+    strings(raw.scopes);
+    strings(grants.treasury_wallet_ids);
+    strings(grants.customer_token_ids);
+    if (!strings(grants.treasury_wallet_ids).every((id) => /^vlt_[a-f0-9]{32}$/i.test(id)) ||
+        !strings(grants.customer_token_ids).every((id) => /^ctk_[a-f0-9]{32}$/i.test(id))) {
+        throw new Error('Invalid workforce resource identity');
+    }
+    return raw;
+}
+function assertSameHuman(before, after) {
+    for (const name of [
+        'session_id',
+        'application_id',
+        'staff_id',
+        'person_id',
+        'tenant_id',
+        'workspace_id',
+        'provider_namespace',
+        'provider_subject',
+    ]) {
+        if (before[name] !== after[name])
+            throw new XKOVAWorkforceBffError('binding_mismatch');
+    }
+}
+function random() {
+    return randomBytes(32).toString('base64url');
+}
+function digest(value) {
+    return createHash('sha256').update(value).digest('base64url');
+}
+function opaque(value) {
+    if (!/^[A-Za-z0-9_-]{43}$/.test(value))
+        throw new TypeError('Invalid opaque workforce reference');
+}
+function credential(value, prefix) {
+    if (!new RegExp(`^${prefix}_[A-Za-z0-9_-]{43}$`).test(value))
+        throw new TypeError('Invalid workforce credential');
+}
+function equal(a, b) {
+    const left = Buffer.from(a), right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+function secureUrl(value) {
+    const url = new URL(value);
+    if (!isAllowedProtocol(url) || url.username || url.password || url.hash)
+        throw new TypeError('Invalid workforce URL');
+    return url;
+}
+function exactCallback(value) {
+    const url = secureUrl(value);
+    if (url.search)
+        throw new TypeError('Workforce callback cannot contain a query');
+    return url;
+}
+function object(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid workforce API response');
+    return value;
+}
+function text(value, key) {
+    const field = value[key];
+    if (typeof field !== 'string' || !field || field.length > 65536)
+        throw new Error('Invalid workforce API response field');
+    return field;
+}
+function strings(value) {
+    if (!Array.isArray(value) ||
+        value.length > 1000 ||
+        !value.every((item) => typeof item === 'string' && item.length > 0 && item.length <= 512)) {
+        throw new Error('Invalid workforce API response list');
+    }
+    return value;
+}
+function timestamp(value, key) {
+    const result = Date.parse(text(value, key));
+    if (!Number.isFinite(result))
+        throw new Error('Invalid workforce API expiry');
+    return result;
+}
+function validateReview(raw) {
+    if (!/^[a-f0-9]{64}$/i.test(text(raw, 'review_digest')) ||
+        timestamp(raw, 'expires_at') <= Date.now()) {
+        throw new XKOVAWorkforceBffError('session_unavailable');
+    }
+}