@atlasauth/js 0.15.0 → 0.16.0

package/dist/mfa-enrollment.js

@@ -0,0 +1,288 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mfaChoicesFrom = mfaChoicesFrom;
+exports.prepareMfaEnrollment = prepareMfaEnrollment;
+exports.groupSetupKey = groupSetupKey;
+exports.createMfaEnrollment = createMfaEnrollment;
+exports.enrollmentSubmitKey = enrollmentSubmitKey;
+exports.prepareSecondFactorCode = prepareSecondFactorCode;
+exports.recoveryCodesFrom = recoveryCodesFrom;
+exports.pendingRecoveryCodes = pendingRecoveryCodes;
+exports.acknowledgeRecoveryCodes = acknowledgeRecoveryCodes;
+exports.recoveryCodesText = recoveryCodesText;
+exports.copyRecoveryCodes = copyRecoveryCodes;
+exports.canDownloadRecoveryCodes = canDownloadRecoveryCodes;
+exports.downloadRecoveryCodes = downloadRecoveryCodes;
+/**
+ * The MFA choices from the instance's settings (`InstanceSettings.account`).
+ * A server that does not publish `account.mfa` gets the authenticator app only,
+ * with two code fields (an instance asking for one code uses the first). Texted
+ * codes are offered only where the server says the app can text, so nobody is
+ * shown an option that cannot work.
+ */
+function mfaChoicesFrom(account) {
+    const mfa = account?.mfa;
+    return {
+        totp: mfa ? mfa.totp : true,
+        sms: mfa ? mfa.sms : false,
+        emailCode: account?.emailSecondFactor === true,
+        totpCodes: mfa ? mfa.totpCodes : 2,
+    };
+}
+/** `POST /v1/client/sign_ins/:id/prepare_mfa_enrollment`. */
+async function prepareMfaEnrollment(client, attemptId, input) {
+    const response = await client.post(`/v1/client/sign_ins/${encodeURIComponent(attemptId)}/prepare_mfa_enrollment`, input.strategy === 'phone_code' ? { strategy: 'phone_code', phone: input.phone } : { strategy: 'totp' });
+    const d = response.data;
+    if (!response.ok || !d || typeof d.factor_id !== 'string') {
+        return { enrollment: null, errors: response.errors, status: response.status };
+    }
+    const str = (v) => (typeof v === 'string' && v ? v : undefined);
+    const enrollment = { strategy: input.strategy, factorId: d.factor_id };
+    if (input.strategy === 'totp') {
+        if (str(d.secret))
+            enrollment.secret = str(d.secret);
+        if (str(d.uri))
+            enrollment.uri = str(d.uri);
+        // Only an image URL a page can show safely.
+        const qr = str(d.qr_code);
+        if (qr && /^data:image\//.test(qr))
+            enrollment.qrCode = qr;
+    }
+    else if (str(d.phone)) {
+        enrollment.phone = str(d.phone);
+    }
+    return { enrollment, errors: [], status: response.status };
+}
+/** A setup key split into groups of four, for reading off the screen. */
+function groupSetupKey(secret) {
+    return secret.replace(/\s+/g, '').replace(/(.{4})(?=.)/g, '$1 ');
+}
+/**
+ * A refusal that means the factor cannot be set up here at all (turned off, or
+ * the app cannot text), as opposed to a mistake the user can fix (a bad number).
+ */
+function factorUnavailable(errors, status) {
+    if (status === 409)
+        return true;
+    return errors.some((e) => e.code === 'STRATEGY_DISABLED' || e.param === 'strategy');
+}
+/** The enrolment step's state and requests, independent of any framework. */
+function createMfaEnrollment(client, choices) {
+    const read = () => (typeof choices === 'function' ? choices() : choices);
+    const offered = (c) => {
+        const out = [];
+        if (c.totp)
+            out.push('totp');
+        if (c.sms)
+            out.push('phone_code');
+        // Nothing on offer is a misconfiguration; the authenticator app is the
+        // default the server enrols, so ask for it rather than draw nothing.
+        return out.length ? out : ['totp'];
+    };
+    const empty = () => {
+        const c = read();
+        return { options: offered(c), method: null, enrollment: null, busy: false, errors: [], totpCodes: c.totpCodes };
+    };
+    let state = empty();
+    let attemptId = null;
+    let phone = '';
+    let generation = 0;
+    const listeners = new Set();
+    const set = (patch) => {
+        state = { ...state, ...patch };
+        for (const listener of listeners)
+            listener(state);
+    };
+    const prepare = async (input) => {
+        const id = attemptId;
+        if (!id)
+            return;
+        const gen = generation;
+        set({ busy: true, errors: [] });
+        const out = await prepareMfaEnrollment(client, id, input);
+        if (gen !== generation)
+            return; // the flow moved on meanwhile
+        if (out.enrollment) {
+            set({ busy: false, enrollment: out.enrollment, errors: [] });
+            return;
+        }
+        if (factorUnavailable(out.errors, out.status) && state.options.length > 1) {
+            // Not available after all: drop it and carry on with what is left.
+            const options = state.options.filter((m) => m !== input.strategy);
+            set({ busy: false, options, method: null, enrollment: null, errors: out.errors });
+            if (options.length === 1)
+                await controller.choose(options[0]);
+            return;
+        }
+        set({ busy: false, errors: out.errors });
+    };
+    const controller = {
+        get state() {
+            return state;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        start(id) {
+            if (id === attemptId)
+                return;
+            generation += 1;
+            attemptId = id;
+            phone = '';
+            state = empty();
+            set({});
+            if (state.options.length === 1)
+                void controller.choose(state.options[0]);
+        },
+        async choose(method) {
+            if (!state.options.includes(method))
+                return;
+            set({ method, enrollment: null, errors: [] });
+            if (method === 'totp')
+                await prepare({ strategy: 'totp' });
+        },
+        async sendPhone(value) {
+            const number = value.trim();
+            if (!number) {
+                set({ errors: [{ code: 'FORM_PARAM_MISSING', message: 'A phone number is required.', param: 'phone' }] });
+                return;
+            }
+            phone = number;
+            await prepare({ strategy: 'phone_code', phone: number });
+        },
+        async resend() {
+            if (state.method === 'phone_code' && phone)
+                await prepare({ strategy: 'phone_code', phone });
+        },
+        async submit(values) {
+            if (state.method === 'phone_code' && !state.enrollment) {
+                await controller.sendPhone(values.phone ?? '');
+                return null;
+            }
+            const e = state.enrollment;
+            if (!e)
+                return null;
+            const out = e.strategy === 'phone_code'
+                ? { factorId: e.factorId, enrollStrategy: 'phone_code', code: values.code ?? '' }
+                : { factorId: e.factorId, code: values.code ?? '', secondCode: values.secondCode ?? '' };
+            return out;
+        },
+        reset() {
+            generation += 1;
+            attemptId = null;
+            phone = '';
+            state = empty();
+            set({});
+        },
+    };
+    return controller;
+}
+/**
+ * The enrolment form's submit button: the catalog key of its label, or null
+ * when the step has nothing to submit yet (choosing a method, or fetching the
+ * authenticator's setup). `mfa.sendCode` before a code was texted.
+ */
+function enrollmentSubmitKey(state) {
+    if (state.method === null)
+        return null;
+    if (state.method === 'phone_code' && !state.enrollment)
+        return 'mfa.sendCode';
+    return state.enrollment ? 'signIn.submit' : null;
+}
+/**
+ * "Text me a code instead" / "Email me a code instead" at the second-factor
+ * step: `prepare_second_factor` sends the code (to the account's enrolled phone,
+ * or its verified email), and it is then submitted like any second-factor code.
+ * Resolves the masked number / address; throws with the server's message (and
+ * `code`) when the channel is not offered for this sign-in.
+ */
+async function prepareSecondFactorCode(client, attemptId, strategy) {
+    const response = await client.post(`/v1/client/sign_ins/${encodeURIComponent(attemptId)}/prepare_second_factor`, { strategy });
+    if (!response.ok) {
+        const first = response.errors[0];
+        const error = new Error(first?.message ?? 'Could not send the code.');
+        if (first?.code)
+            error.code = first.code;
+        throw error;
+    }
+    return { sentTo: typeof response.data?.sent_to === 'string' ? response.data.sent_to : '' };
+}
+/**
+ * The recovery codes in an `attempt_mfa_enrollment` response (`backup_codes`):
+ * the non-empty strings, or null when there are none.
+ */
+function recoveryCodesFrom(value) {
+    if (!Array.isArray(value))
+        return null;
+    const codes = value.filter((c) => typeof c === 'string' && c.length > 0);
+    return codes.length ? codes : null;
+}
+/**
+ * The recovery codes to show before the sign-in finishes: set while an
+ * enrolment has completed the attempt and the user has not yet said they saved
+ * them. A component that gets codes here draws them (once) instead of the
+ * finished step, and holds the ticket exchange until
+ * {@link acknowledgeRecoveryCodes}.
+ */
+function pendingRecoveryCodes(state) {
+    if (state.attempt?.status !== 'complete')
+        return null;
+    return state.recoveryCodes && state.recoveryCodes.length ? state.recoveryCodes : null;
+}
+/** The flow once the user has saved the codes: forgotten, ready for the ticket exchange. */
+function acknowledgeRecoveryCodes(state) {
+    return { ...state, recoveryCodes: null };
+}
+/** The codes as a text file's contents: one per line. */
+function recoveryCodesText(codes) {
+    return `${codes.join('\n')}\n`;
+}
+/** Copy the codes (one per line) to the clipboard. Resolves whether it worked. */
+async function copyRecoveryCodes(codes) {
+    const clipboard = globalThis.navigator
+        ?.clipboard;
+    if (!clipboard?.writeText)
+        return false;
+    try {
+        await clipboard.writeText(codes.join('\n'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether this page can offer the codes as a download. */
+function canDownloadRecoveryCodes() {
+    return (typeof document !== 'undefined' &&
+        typeof Blob !== 'undefined' &&
+        typeof URL !== 'undefined' &&
+        typeof URL.createObjectURL === 'function');
+}
+/**
+ * Save the codes as a .txt file (`recovery-codes.txt`) through a temporary
+ * object URL, revoked straight after. Returns whether the download started.
+ */
+function downloadRecoveryCodes(codes, filename = 'recovery-codes.txt') {
+    if (!canDownloadRecoveryCodes())
+        return false;
+    const url = URL.createObjectURL(new Blob([recoveryCodesText(codes)], { type: 'text/plain;charset=utf-8' }));
+    try {
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = filename;
+        a.rel = 'noopener';
+        a.style.display = 'none';
+        (document.body ?? document.documentElement).appendChild(a);
+        a.click();
+        a.remove();
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        setTimeout(() => URL.revokeObjectURL(url), 0);
+    }
+}
+//# sourceMappingURL=mfa-enrollment.js.map

package/dist/mfa-enrollment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mfa-enrollment.js","sourceRoot":"","sources":["../src/mfa-enrollment.ts"],"names":[],"mappings":"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"}

package/dist/organization-audit-log.d.ts

@@ -0,0 +1,63 @@
+import type { FapiClient } from './fapi';
+/**
+ * An organization's audit trail, for its admins — the framework-agnostic state
+ * behind `<OrganizationAuditLog/>` in every framework SDK, so React, Vue,
+ * Svelte, Solid and Angular page through `GET /v1/client/organizations/:id/
+ * audit_logs` the same way.
+ */
+/** One entry of an organization's audit trail, as the Frontend API returns it. */
+export interface OrganizationAuditLogEntry {
+    object: 'audit_log';
+    id: string;
+    action: string;
+    actor: {
+        type: string;
+        id: string | null;
+    };
+    target: {
+        type: string | null;
+        id: string | null;
+    };
+    organization_id: string;
+    ip: string | null;
+    user_agent: string | null;
+    metadata: Record<string, unknown>;
+    created_at: number;
+}
+export interface OrganizationAuditLogOptions {
+    /** Entries per page (the server caps it). Default 20. */
+    pageSize?: number;
+    /** Narrow to one action, or a prefix ending in `.` (`organization_membership.`). */
+    action?: string;
+}
+export interface OrganizationAuditLogState {
+    entries: OrganizationAuditLogEntry[];
+    loading: boolean;
+    /** The signed-in member may not read this organization's log: hide the surface. */
+    forbidden: boolean;
+    hasMore: boolean;
+}
+export interface OrganizationAuditLogController {
+    getState(): OrganizationAuditLogState;
+    /** Called with the new state on every change; returns the unsubscribe. */
+    subscribe(listener: (state: OrganizationAuditLogState) => void): () => void;
+    /** Show `organizationId`'s log from its newest entry (null clears it). */
+    load(organizationId: string | null): Promise<void>;
+    /** Append the next page, when there is one. */
+    loadMore(): Promise<void>;
+    /** Re-read the current organization's log from its newest entry. */
+    reload(): Promise<void>;
+}
+export declare const EMPTY_ORGANIZATION_AUDIT_LOG: OrganizationAuditLogState;
+/** The Frontend API path for one page of an organization's audit log. */
+export declare function organizationAuditLogPath(organizationId: string, options?: OrganizationAuditLogOptions & {
+    startingAfter?: string | null;
+}): string;
+/** `organization_invitation.created` → `Organization invitation created`. */
+export declare function describeAuditAction(action: string): string;
+/**
+ * Page through an organization's audit log. A response for an organization
+ * that is no longer the one shown (the user switched while it was in flight)
+ * is dropped, so a slow page never lands in the wrong organization's list.
+ */
+export declare function createOrganizationAuditLog(client: Pick<FapiClient, 'get'>, options?: OrganizationAuditLogOptions): OrganizationAuditLogController;

package/dist/organization-audit-log.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_ORGANIZATION_AUDIT_LOG = void 0;
+exports.organizationAuditLogPath = organizationAuditLogPath;
+exports.describeAuditAction = describeAuditAction;
+exports.createOrganizationAuditLog = createOrganizationAuditLog;
+exports.EMPTY_ORGANIZATION_AUDIT_LOG = Object.freeze({
+    entries: [],
+    loading: false,
+    forbidden: false,
+    hasMore: false,
+});
+/** The Frontend API path for one page of an organization's audit log. */
+function organizationAuditLogPath(organizationId, options = {}) {
+    const params = new URLSearchParams({ limit: String(options.pageSize ?? 20) });
+    if (options.startingAfter)
+        params.set('starting_after', options.startingAfter);
+    if (options.action)
+        params.set('action', options.action);
+    return `/v1/client/organizations/${encodeURIComponent(organizationId)}/audit_logs?${params.toString()}`;
+}
+/** `organization_invitation.created` → `Organization invitation created`. */
+function describeAuditAction(action) {
+    const text = action.replace(/[._]+/g, ' ').trim();
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
+/**
+ * Page through an organization's audit log. A response for an organization
+ * that is no longer the one shown (the user switched while it was in flight)
+ * is dropped, so a slow page never lands in the wrong organization's list.
+ */
+function createOrganizationAuditLog(client, options = {}) {
+    let state = exports.EMPTY_ORGANIZATION_AUDIT_LOG;
+    let organizationId = null;
+    let cursor = null;
+    let generation = 0;
+    const listeners = new Set();
+    const set = (patch) => {
+        state = { ...state, ...patch };
+        for (const listener of listeners)
+            listener(state);
+    };
+    const fetchPage = async (after) => {
+        const orgId = organizationId;
+        if (!orgId)
+            return;
+        const mine = generation;
+        set({ loading: true });
+        try {
+            const res = await client.get(organizationAuditLogPath(orgId, { ...options, startingAfter: after }));
+            if (mine !== generation)
+                return;
+            if (!res.ok || !res.data) {
+                set({ forbidden: res.status === 403 || res.status === 404 });
+                return;
+            }
+            const page = res.data;
+            cursor = page.next_cursor;
+            set({
+                forbidden: false,
+                entries: after ? [...state.entries, ...page.data] : page.data,
+                hasMore: page.has_more,
+            });
+        }
+        finally {
+            if (mine === generation)
+                set({ loading: false });
+        }
+    };
+    return {
+        getState: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        async load(next) {
+            generation += 1;
+            organizationId = next;
+            cursor = null;
+            set({ ...exports.EMPTY_ORGANIZATION_AUDIT_LOG });
+            await fetchPage(null);
+        },
+        async loadMore() {
+            if (cursor && !state.loading)
+                await fetchPage(cursor);
+        },
+        async reload() {
+            generation += 1;
+            cursor = null;
+            await fetchPage(null);
+        },
+    };
+}
+//# sourceMappingURL=organization-audit-log.js.map

package/dist/organization-audit-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization-audit-log.js","sourceRoot":"","sources":["../src/organization-audit-log.ts"],"names":[],"mappings":"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"}