@ticketlayer/backstage 3.1.0 → 4.1.0

package/dist/auth/index.js

@@ -0,0 +1,332 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthSession = exports.BackstageAuth = exports.ACCESS_TOKEN_TYPE = exports.REFRESH_TOKEN_TYPE = exports.TOKEN_EXCHANGE_GRANT = exports.jwkThumbprint = exports.dpopProof = exports.dpopHtu = exports.createDpopKey = exports.pkceChallenge = exports.pkce = void 0;
+exports.createAuth = createAuth;
+const client_1 = require("../client");
+const dpop_1 = require("./dpop");
+const encoding_1 = require("./encoding");
+const pkce_1 = require("./pkce");
+var pkce_2 = require("./pkce");
+Object.defineProperty(exports, "pkce", { enumerable: true, get: function () { return pkce_2.pkce; } });
+Object.defineProperty(exports, "pkceChallenge", { enumerable: true, get: function () { return pkce_2.pkceChallenge; } });
+var dpop_2 = require("./dpop");
+Object.defineProperty(exports, "createDpopKey", { enumerable: true, get: function () { return dpop_2.createDpopKey; } });
+Object.defineProperty(exports, "dpopHtu", { enumerable: true, get: function () { return dpop_2.dpopHtu; } });
+Object.defineProperty(exports, "dpopProof", { enumerable: true, get: function () { return dpop_2.dpopProof; } });
+Object.defineProperty(exports, "jwkThumbprint", { enumerable: true, get: function () { return dpop_2.jwkThumbprint; } });
+exports.TOKEN_EXCHANGE_GRANT = 'urn:ietf:params:oauth:grant-type:token-exchange';
+exports.REFRESH_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:refresh_token';
+exports.ACCESS_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:access_token';
+function assertServerSide() {
+    const g = globalThis;
+    if (typeof g.window !== 'undefined' && typeof g.document !== 'undefined') {
+        throw new Error('clientSecret is for server use only (the shell BFF). Never ship a client secret to a browser; public clients use PKCE and DPoP.');
+    }
+}
+const formEncode = (value) => encodeURIComponent(value).replace(/%20/g, '+');
+function organisationsFrom(idToken) {
+    if (!idToken)
+        return undefined;
+    const claim = (0, encoding_1.decodeJwtPayload)(idToken)?.organisations;
+    if (!Array.isArray(claim))
+        return undefined;
+    return claim
+        .filter((o) => !!o && typeof o === 'object' && typeof o.slug === 'string')
+        .map((o) => ({ id: String(o.id), slug: o.slug, name: String(o.name) }));
+}
+function toTokenSet(body, previous) {
+    const accessToken = body.access_token;
+    if (typeof accessToken !== 'string' || !accessToken) {
+        throw new client_1.BackstageAPIError('The token endpoint answered no access token', 'INVALID_TOKEN_RESPONSE', 502);
+    }
+    const expiresIn = typeof body.expires_in === 'number' ? body.expires_in : 0;
+    const idToken = typeof body.id_token === 'string' ? body.id_token : undefined;
+    let organisation;
+    if ('org_slug' in body) {
+        organisation =
+            typeof body.org_slug === 'string'
+                ? { slug: body.org_slug, name: typeof body.org_name === 'string' ? body.org_name : null }
+                : null;
+    }
+    else {
+        organisation = previous?.organisation ?? null;
+    }
+    const tokens = {
+        accessToken,
+        tokenType: typeof body.token_type === 'string' ? body.token_type : 'Bearer',
+        expiresIn,
+        expiresAt: Date.now() + expiresIn * 1000,
+        organisation,
+    };
+    const refreshToken = typeof body.refresh_token === 'string' ? body.refresh_token : previous?.refreshToken;
+    if (refreshToken)
+        tokens.refreshToken = refreshToken;
+    if (typeof body.scope === 'string')
+        tokens.scope = body.scope;
+    if (idToken)
+        tokens.idToken = idToken;
+    const organisations = organisationsFrom(idToken) ?? previous?.organisations;
+    if (organisations)
+        tokens.organisations = organisations;
+    return tokens;
+}
+class BackstageAuth {
+    constructor(config) {
+        this.pkce = pkce_1.pkce;
+        this.pkceChallenge = pkce_1.pkceChallenge;
+        this.createDpopKey = dpop_1.createDpopKey;
+        this.dpopProof = dpop_1.dpopProof;
+        if (!config || !config.issuerUrl)
+            throw new Error('createAuth needs issuerUrl (https://auth.<domain>)');
+        this.issuerUrl = config.issuerUrl.replace(/\/$/, '');
+        this.tokenEndpoint = config.tokenEndpoint ?? `${this.issuerUrl}/oauth/token`;
+        this.clientId = config.clientId;
+        this.debugConfig =
+            config.debug === true
+                ? { logRequests: true, logResponses: true, logErrors: true }
+                : config.debug && typeof config.debug === 'object'
+                    ? config.debug
+                    : null;
+        this.logger = this.debugConfig
+            ? this.debugConfig.logger ?? {
+                log: (...args) => console.log('[BackstageSDK]', ...args),
+                error: (...args) => console.error('[BackstageSDK]', ...args),
+            }
+            : null;
+        this.issuer = new client_1.BackstageClient({
+            baseUrl: this.issuerUrl,
+            authMode: 'bearer',
+            debug: config.debug,
+            headers: config.headers,
+            credentials: config.credentials,
+        });
+    }
+    async start(input) {
+        const answer = (await this.issuer.identity.start({
+            client_id: this.clientIdOf(input.clientId),
+            code_challenge: input.codeChallenge,
+            code_challenge_method: 'S256',
+            email: input.email,
+            redirect_uri: input.redirectUri,
+            scope: input.scope,
+            dpop_jkt: input.dpop?.thumbprint,
+            organisation: input.organisation,
+        }));
+        const result = {
+            method: answer.method,
+            authSession: answer.authSession,
+            alternatives: answer.alternatives ?? [],
+            expiresIn: answer.expiresIn,
+        };
+        if (answer.redirectUrl)
+            result.redirectUrl = answer.redirectUrl;
+        return result;
+    }
+    async password(input) {
+        return this.step(await this.issuer.identity.password({ authSession: input.authSession, password: input.password }));
+    }
+    async sendEmailCode(input) {
+        const answer = await this.issuer.identity.emailCode({ authSession: input.authSession });
+        if (answer.status !== 'code_sent') {
+            throw new client_1.BackstageAPIError('Expected code_sent from /auth/email-code', 'UNEXPECTED_RESPONSE', 502);
+        }
+        return { status: 'code_sent' };
+    }
+    async emailCode(input) {
+        if (!input.code)
+            throw new Error('emailCode needs the code; use sendEmailCode to have one sent');
+        return this.step(await this.issuer.identity.emailCode({ authSession: input.authSession, code: input.code }));
+    }
+    async mfa(input) {
+        return this.step(await this.issuer.identity.mfa({ authSession: input.authSession, code: input.code }));
+    }
+    step(answer) {
+        if (answer.status === 'code')
+            return { status: 'code', code: answer.code, redirectUri: answer.redirectUri };
+        if (answer.status === 'mfa_required') {
+            return { status: 'mfa_required', authSession: answer.authSession, factors: [...answer.factors] };
+        }
+        throw new client_1.BackstageAPIError(`Unexpected sign-in answer: ${String(answer.status)}`, 'UNEXPECTED_RESPONSE', 502);
+    }
+    async exchange(input) {
+        const params = { code: input.code, code_verifier: input.codeVerifier };
+        if (input.redirectUri)
+            params.redirect_uri = input.redirectUri;
+        return this.token('authorization_code', params, input);
+    }
+    async refresh(input) {
+        return this.token('refresh_token', { refresh_token: input.refreshToken }, input, {
+            refreshToken: input.refreshToken,
+        });
+    }
+    async selectOrganisation(input) {
+        const subject = input.refreshToken ?? input.accessToken;
+        if (!subject)
+            throw new Error('selectOrganisation needs a refreshToken or an accessToken');
+        return this.token(exports.TOKEN_EXCHANGE_GRANT, {
+            subject_token: subject,
+            subject_token_type: input.refreshToken ? exports.REFRESH_TOKEN_TYPE : exports.ACCESS_TOKEN_TYPE,
+            requested_token_type: exports.ACCESS_TOKEN_TYPE,
+            organisation_slug: input.slug,
+        }, input);
+    }
+    async token(grantType, params, credentials, previous) {
+        const clientId = this.clientIdOf(credentials.clientId);
+        const headers = {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Accept: 'application/json',
+        };
+        const form = new URLSearchParams({ grant_type: grantType, ...params });
+        if (credentials.clientSecret) {
+            assertServerSide();
+            headers.Authorization = `Basic ${btoa(`${formEncode(clientId)}:${formEncode(credentials.clientSecret)}`)}`;
+        }
+        else {
+            form.set('client_id', clientId);
+        }
+        const send = async (nonce) => {
+            if (credentials.dpop) {
+                headers.DPoP = await credentials.dpop.proof({ method: 'POST', url: this.tokenEndpoint, nonce });
+            }
+            if (this.debugConfig?.logRequests)
+                this.logger?.log('→', 'POST', this.tokenEndpoint, { grant_type: grantType });
+            return fetch(this.tokenEndpoint, { method: 'POST', headers, body: form.toString() });
+        };
+        let response = await send();
+        let body = (await response.json().catch(() => ({})));
+        const nonce = response.headers?.get?.('DPoP-Nonce');
+        if (!response.ok && body.error === 'use_dpop_nonce' && nonce && credentials.dpop) {
+            response = await send(nonce);
+            body = (await response.json().catch(() => ({})));
+        }
+        if (!response.ok) {
+            const code = typeof body.error === 'string' ? body.error : 'HTTP_ERROR';
+            const message = typeof body.error_description === 'string' ? body.error_description : `Token request failed (${code})`;
+            if (this.debugConfig?.logErrors)
+                this.logger?.error('✗', 'POST', this.tokenEndpoint, { status: response.status, code });
+            throw new client_1.BackstageAPIError(message, code, response.status, {
+                requestId: response.headers?.get?.('x-request-id') ?? undefined,
+            });
+        }
+        if (this.debugConfig?.logResponses) {
+            this.logger?.log('←', 'POST', this.tokenEndpoint, { status: response.status, grant_type: grantType });
+        }
+        return toTokenSet(body, previous);
+    }
+    clientIdOf(clientId) {
+        const id = clientId ?? this.clientId;
+        if (!id)
+            throw new Error('No clientId: pass one to the call or to createAuth');
+        return id;
+    }
+    createSession(options) {
+        return new AuthSession(this, options);
+    }
+    createClient(options) {
+        return this.createSession(options).client;
+    }
+}
+exports.BackstageAuth = BackstageAuth;
+class AuthSession {
+    constructor(auth, options) {
+        this.auth = auth;
+        this.options = options;
+        this.ended = false;
+        if (options.clientSecret)
+            assertServerSide();
+        this.current = { ...options.tokens };
+        this.leewayMs = (options.refreshLeewaySeconds ?? 30) * 1000;
+        const { tokens: _tokens, clientId: _clientId, clientSecret: _clientSecret, dpop, onTokens: _onTokens, onSessionEnded: _onSessionEnded, refreshLeewaySeconds: _leeway, organisationSlug, ...config } = options;
+        this.client = new client_1.BackstageClient({
+            ...config,
+            authMode: 'bearer',
+            accessToken: () => {
+                this.refreshAhead();
+                return this.current.accessToken;
+            },
+            organisationSlug: organisationSlug ?? (() => this.current.organisation?.slug ?? undefined),
+            onAuthFailure: () => this.refresh(),
+            dpop,
+        });
+    }
+    get tokens() {
+        return { ...this.current };
+    }
+    get organisation() {
+        return this.current.organisation ?? null;
+    }
+    get hasEnded() {
+        return this.ended;
+    }
+    refresh() {
+        if (this.ended)
+            return Promise.resolve(false);
+        if (!this.pending) {
+            this.pending = this.runRefresh().finally(() => {
+                this.pending = undefined;
+            });
+        }
+        return this.pending;
+    }
+    async selectOrganisation(slug) {
+        while (this.pending)
+            await this.pending.catch(() => false);
+        const run = (async () => {
+            const next = await this.auth.selectOrganisation({
+                slug,
+                refreshToken: this.current.refreshToken,
+                accessToken: this.current.refreshToken ? undefined : this.current.accessToken,
+                clientId: this.options.clientId,
+                clientSecret: this.options.clientSecret,
+                dpop: this.options.dpop,
+            });
+            await this.adopt(next);
+            return next;
+        })();
+        this.pending = run.then(() => true, () => false);
+        try {
+            return await run;
+        }
+        finally {
+            this.pending = undefined;
+        }
+    }
+    refreshAhead() {
+        if (this.ended || this.pending || !this.current.refreshToken)
+            return;
+        const { accessToken, expiresAt } = this.current;
+        const due = !accessToken || (typeof expiresAt === 'number' && expiresAt - Date.now() < this.leewayMs);
+        if (due)
+            void this.refresh();
+    }
+    async runRefresh() {
+        const refreshToken = this.current.refreshToken;
+        if (!refreshToken)
+            return false;
+        try {
+            const next = await this.auth.refresh({
+                refreshToken,
+                clientId: this.options.clientId,
+                clientSecret: this.options.clientSecret,
+                dpop: this.options.dpop,
+            });
+            await this.adopt({ ...next, organisation: next.organisation ?? this.current.organisation ?? null });
+            return true;
+        }
+        catch (error) {
+            if (error instanceof client_1.BackstageAPIError && error.statusCode >= 400 && error.statusCode < 500) {
+                this.ended = true;
+                await this.options.onSessionEnded?.(error);
+            }
+            return false;
+        }
+    }
+    async adopt(next) {
+        this.current = { ...next };
+        await this.options.onTokens?.({ ...next });
+    }
+}
+exports.AuthSession = AuthSession;
+function createAuth(config) {
+    return new BackstageAuth(config);
+}

package/dist/auth/pkce.d.ts

@@ -0,0 +1,8 @@
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+    method: 'S256';
+}
+export declare function pkceChallenge(verifier: string): Promise<string>;
+export declare function pkce(): Promise<PkcePair>;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/auth/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/auth/pkce.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAGD,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKrE;AAMD,wBAAsB,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,CAG9C"}

package/dist/auth/pkce.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pkceChallenge = pkceChallenge;
+exports.pkce = pkce;
+const encoding_1 = require("./encoding");
+async function pkceChallenge(verifier) {
+    if (!/^[A-Za-z0-9\-._~]{43,128}$/.test(verifier)) {
+        throw new Error('A PKCE verifier is 43 to 128 characters of [A-Za-z0-9-._~] (RFC 7636 4.1)');
+    }
+    return (0, encoding_1.base64url)(await (0, encoding_1.sha256)(verifier));
+}
+async function pkce() {
+    const verifier = (0, encoding_1.base64url)((0, encoding_1.randomBytes)(32));
+    return { verifier, challenge: await pkceChallenge(verifier), method: 'S256' };
+}

package/dist/client.d.ts

@@ -12,14 +12,15 @@ type CreateTagDefinitionRequest = components['schemas']['CreateTagDefinitionRequ
 type CreateUserInvitationRequest = components['schemas']['CreateUserInvitationRequest'];
 type CreateWebhookEndpoint = components['schemas']['CreateWebhookEndpoint'];
 type GrantSalesChannelAccessRequest = components['schemas']['GrantSalesChannelAccessRequest'];
-type LoginRequest = components['schemas']['LoginRequest'];
-type RedeemInvitationRequest = components['schemas']['RedeemInvitationRequest'];
-type RefreshTokenRequest = components['schemas']['RefreshTokenRequest'];
 type SavePaymentMethodRequest = components['schemas']['SavePaymentMethodRequest'];
 type SignInInteractionLogin = components['schemas']['SignInInteractionLogin'];
 type SignInInteractionOrganisation = components['schemas']['SignInInteractionOrganisation'];
 type SignUpRequest = components['schemas']['SignUpRequest'];
 type StaffUnlockRequest = components['schemas']['StaffUnlockRequest'];
+type StartSignInRequest = components['schemas']['StartSignInRequest'];
+type SubmitSignInEmailCodeRequest = components['schemas']['SubmitSignInEmailCodeRequest'];
+type SubmitSignInMfaRequest = components['schemas']['SubmitSignInMfaRequest'];
+type SubmitSignInPasswordRequest = components['schemas']['SubmitSignInPasswordRequest'];
 type UpdateAutoTopupRequest = components['schemas']['UpdateAutoTopupRequest'];
 type UpdateCodeRequest = components['schemas']['UpdateCodeRequest'];
 type UpdateIdentityProviderRequest = components['schemas']['UpdateIdentityProviderRequest'];
@@ -65,6 +66,15 @@ export interface BackstageClientConfig {
     refreshEndpoint?: string;
     organisationSlug?: string | (() => string | undefined);
     headers?: Record<string, string>;
+    dpop?: DpopSigner;
+    credentials?: RequestCredentials;
+}
+export interface DpopSigner {
+    proof(input: {
+        method: string;
+        url: string;
+        accessToken?: string;
+    }): Promise<string>;
 }
 export declare const API_DATED_VERSION = "2026-06-13";
 export declare const SDK_CLIENT_HEADER: string;
@@ -76,8 +86,10 @@ export declare class BackstageClient {
     private headers;
     private onTokenRefresh?;
     private onAuthFailure?;
-    private refreshEndpoint;
+    private refreshEndpoint?;
     private organisationSlug?;
+    private dpop?;
+    private credentials?;
     private debugConfig;
     private logger;
     constructor(config: BackstageClientConfig);
@@ -91,6 +103,7 @@ export declare class BackstageClient {
     private resolveOrgSlug;
     private getOrgFromSubdomain;
     private attemptTokenRefresh;
+    private authorise;
     private request;
     identity: {
         getSignInInteraction: (uid: string) => Promise<{
@@ -130,6 +143,41 @@ export declare class BackstageClient {
             status: "continue";
             redirectTo: string;
         }>;
+        start: (request: StartSignInRequest) => Promise<{
+            authSession: string;
+            method: "password";
+            alternatives: "email_code"[];
+            expiresIn: number;
+        }>;
+        password: (request: SubmitSignInPasswordRequest) => Promise<{
+            status: "code";
+            code: string;
+            redirectUri: string;
+        } | {
+            status: "mfa_required";
+            authSession: string;
+            factors: ("totp" | "email")[];
+        }>;
+        emailCode: (request: SubmitSignInEmailCodeRequest) => Promise<{
+            status: "code";
+            code: string;
+            redirectUri: string;
+        } | {
+            status: "mfa_required";
+            authSession: string;
+            factors: ("totp" | "email")[];
+        } | {
+            status: "code_sent";
+        }>;
+        mfa: (request: SubmitSignInMfaRequest) => Promise<{
+            status: "code";
+            code: string;
+            redirectUri: string;
+        } | {
+            status: "mfa_required";
+            authSession: string;
+            factors: ("totp" | "email")[];
+        }>;
     };
     identityProviders: {
         discover: (options?: {
@@ -235,32 +283,6 @@ export declare class BackstageClient {
             versions: components["schemas"]["ApiVersion"][];
         }>;
     };
-    authentication: {
-        login: (request: LoginRequest) => Promise<{
-            accessToken: string;
-            refreshToken: string;
-            user: {
-                id: string;
-                email: string;
-                firstName?: string;
-                lastName?: string;
-            };
-        }>;
-        refresh: (request: RefreshTokenRequest) => Promise<{
-            accessToken: string;
-            refreshToken: string;
-        }>;
-        redeem: (request: RedeemInvitationRequest) => Promise<{
-            accessToken: string;
-            refreshToken: string;
-            user: {
-                id: string;
-                email: string;
-                firstName?: string;
-                lastName?: string;
-            };
-        }>;
-    };
     signup: {
         signUp: (request: SignUpRequest) => Promise<{
             organisation: {