@atlasauth/js 0.1.0

package/dist/telemetry.js

@@ -0,0 +1,357 @@
+"use strict";
+/**
+ * §bot — client-side signal collection for the anti-bot pipeline.
+ *
+ * Two collectors, both privacy-preserving and both fully best-effort (they never
+ * throw, and degrade to nulls in any environment):
+ *
+ *   - `collectDeviceSignals()` — a snapshot of the device/environment: screen,
+ *     timezone, hardware, a coarse canvas/WebGL fingerprint, and AUTOMATION
+ *     TELLS (navigator.webdriver, headless markers, Selenium/Puppeteer traces).
+ *   - `BehaviorRecorder` — accumulates interaction TIMING AGGREGATES on the auth
+ *     form: mouse kinematics, keystroke dwell/flight, time-to-submit, scrolls.
+ *     It records COUNTS AND TIMINGS ONLY — never which keys were pressed, never
+ *     field values. There is nothing sensitive to leak.
+ *
+ * `sendTelemetry()` posts a snapshot to `/v1/client/telemetry`. It is
+ * fire-and-forget: a failure resolves `false` and is swallowed, so telemetry can
+ * never interfere with a real sign-in.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BehaviorRecorder = void 0;
+exports.collectDeviceSignals = collectDeviceSignals;
+exports.deviceId = deviceId;
+exports.deviceFingerprint = deviceFingerprint;
+exports.sendTelemetry = sendTelemetry;
+const hasWindow = typeof window !== 'undefined';
+const nav = () => (typeof navigator !== 'undefined' ? navigator : undefined);
+function safe(fn, fallback) {
+    try {
+        return fn();
+    }
+    catch {
+        return fallback;
+    }
+}
+/** WebGL unmasked vendor/renderer, if exposed. */
+function webglInfo() {
+    return safe(() => {
+        if (!hasWindow || typeof document === 'undefined')
+            return { vendor: null, renderer: null };
+        const canvas = document.createElement('canvas');
+        const gl = (canvas.getContext('webgl') ||
+            canvas.getContext('experimental-webgl'));
+        if (!gl)
+            return { vendor: null, renderer: null };
+        const ext = gl.getExtension('WEBGL_debug_renderer_info');
+        const vendor = ext ? gl.getParameter(ext.UNMASKED_VENDOR_WEBGL) : null;
+        const renderer = ext ? gl.getParameter(ext.UNMASKED_RENDERER_WEBGL) : null;
+        return { vendor: vendor ?? null, renderer: renderer ?? null };
+    }, { vendor: null, renderer: null });
+}
+/** A short non-crypto canvas fingerprint (a bucket key, never a credential). */
+function canvasHash() {
+    return safe(() => {
+        if (typeof document === 'undefined')
+            return null;
+        const canvas = document.createElement('canvas');
+        canvas.width = 220;
+        canvas.height = 40;
+        const ctx = canvas.getContext('2d');
+        if (!ctx)
+            return null;
+        ctx.textBaseline = 'top';
+        ctx.font = "14px 'Arial'";
+        ctx.fillStyle = '#f60';
+        ctx.fillRect(0, 0, 60, 20);
+        ctx.fillStyle = '#069';
+        ctx.fillText('Atlas anti-bot ✈ 1.0', 2, 15);
+        return djb2(canvas.toDataURL());
+    }, null);
+}
+/** Detect common headless/automation markers without being fooled by UA alone. */
+function automationTells() {
+    const n = nav();
+    const w = hasWindow ? window : {};
+    const ua = n?.userAgent ?? '';
+    const webdriver = safe(() => n?.webdriver === true, false);
+    const hasChrome = safe(() => 'chrome' in w && !!w.chrome, false);
+    const headless = /headless/i.test(ua) ||
+        // A Chrome UA with no chrome object and no plugins is a classic headless tell.
+        (/chrome/i.test(ua) && !hasChrome && safe(() => (n?.plugins?.length ?? 0) === 0, false));
+    const automationHint = safe(() => webdriver ||
+        '_phantom' in w ||
+        'callPhantom' in w ||
+        '__nightmare' in w ||
+        'domAutomation' in w ||
+        'domAutomationController' in w ||
+        // chromedriver injects cdc_* properties on document.
+        (typeof document !== 'undefined' &&
+            Object.keys(document).some((k) => k.startsWith('cdc_') || k.startsWith('$cdc_'))) ||
+        /electron|phantomjs|slimerjs/i.test(ua), webdriver);
+    return { webdriver, headless, hasChrome, automationHint };
+}
+function collectDeviceSignals() {
+    const n = nav();
+    const gl = webglInfo();
+    const tells = automationTells();
+    const languages = safe(() => Array.from(n?.languages ?? []), []);
+    const renderer = gl.renderer;
+    return {
+        screenWidth: safe(() => window.screen?.width ?? null, null),
+        screenHeight: safe(() => window.screen?.height ?? null, null),
+        colorDepth: safe(() => window.screen?.colorDepth ?? null, null),
+        pixelRatio: safe(() => window.devicePixelRatio ?? null, null),
+        timezone: safe(() => Intl.DateTimeFormat().resolvedOptions().timeZone ?? null, null),
+        timezoneOffset: safe(() => new Date().getTimezoneOffset(), null),
+        language: safe(() => n?.language ?? null, null),
+        languages,
+        platform: safe(() => n?.platform ?? null, null),
+        hardwareConcurrency: safe(() => n?.hardwareConcurrency ?? null, null),
+        deviceMemory: safe(() => n?.deviceMemory ?? null, null),
+        maxTouchPoints: safe(() => n?.maxTouchPoints ?? null, null),
+        touchSupport: safe(() => (n?.maxTouchPoints ?? 0) > 0 || 'ontouchstart' in window, false),
+        cookieEnabled: safe(() => n?.cookieEnabled ?? null, null),
+        doNotTrack: safe(() => n?.doNotTrack === '1' || n?.doNotTrack === 'yes', null),
+        webglVendor: gl.vendor,
+        webglRenderer: renderer,
+        pluginCount: safe(() => n?.plugins?.length ?? null, null),
+        pointerType: safe(() => (window.matchMedia?.('(pointer: fine)')?.matches ? 'fine' : 'coarse'), null),
+        webdriver: tells.webdriver,
+        headless: tells.headless,
+        hasChrome: tells.hasChrome,
+        webglSoftware: renderer ? /swiftshader|llvmpipe|software|basic render/i.test(renderer) : false,
+        automationHint: tells.automationHint,
+        // canvasHash folds into the device fingerprint below; kept off the wire shape
+        // to stay small, but influences deviceFingerprint().
+    };
+}
+/** A stable pseudonymous client id, persisted in localStorage. */
+function deviceId() {
+    return safe(() => {
+        if (typeof localStorage === 'undefined')
+            return null;
+        const KEY = '__atlas_did';
+        let id = localStorage.getItem(KEY);
+        if (!id) {
+            id = 'd_' + djb2(String(Math.random()) + String(Date.now()) + (nav()?.userAgent ?? ''));
+            localStorage.setItem(KEY, id);
+        }
+        return id;
+    }, null);
+}
+/** A short client-side fingerprint over the stable device signals. */
+function deviceFingerprint(device) {
+    const parts = [
+        device.timezone,
+        device.platform,
+        device.languages.join(','),
+        device.webglVendor,
+        device.webglRenderer,
+        device.screenWidth,
+        device.screenHeight,
+        device.colorDepth,
+        device.hardwareConcurrency,
+        canvasHash(),
+    ];
+    return djb2(parts.map((p) => (p == null ? '' : String(p))).join('|'));
+}
+/** A tiny deterministic string hash (djb2) → 8-hex. Not a credential. */
+function djb2(s) {
+    let h = 5381;
+    for (let i = 0; i < s.length; i += 1)
+        h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+    return h.toString(16).padStart(8, '0');
+}
+const mean = (xs) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : null);
+const variance = (xs) => {
+    const m = mean(xs);
+    if (m === null)
+        return null;
+    return xs.reduce((a, b) => a + (b - m) ** 2, 0) / xs.length;
+};
+/**
+ * Records interaction TIMINGS on the page/form. Start it when the auth form
+ * mounts; call `snapshot()` at submit. It listens passively and captures no
+ * content — only counts, distances and millisecond timings.
+ */
+class BehaviorRecorder {
+    start = Date.now();
+    firstInteraction = null;
+    moves = 0;
+    distance = 0;
+    maxSpeed = 0;
+    speeds = [];
+    lastX = null;
+    lastY = null;
+    lastMoveT = 0;
+    netDx = 0;
+    netDy = 0;
+    keyCount = 0;
+    downAt = new Map();
+    dwell = [];
+    flight = [];
+    lastUpAt = null;
+    pastes = 0;
+    backspaces = 0;
+    focusChanges = 0;
+    scrolls = 0;
+    target;
+    bound = [];
+    constructor(target) {
+        this.target = target ?? (typeof document !== 'undefined' ? document : undefined);
+        this.attach();
+    }
+    mark() {
+        if (this.firstInteraction === null)
+            this.firstInteraction = Date.now() - this.start;
+    }
+    attach() {
+        const t = this.target;
+        if (!t)
+            return;
+        const on = (type, fn) => {
+            safe(() => t.addEventListener(type, fn, { passive: true }), undefined);
+            this.bound.push([type, fn]);
+        };
+        on('pointermove', (e) => this.onMove(e));
+        on('mousemove', (e) => this.onMove(e));
+        on('keydown', (e) => this.onKeyDown(e));
+        on('keyup', (e) => this.onKeyUp(e));
+        on('paste', () => {
+            this.mark();
+            this.pastes += 1;
+        });
+        on('focusin', () => {
+            this.mark();
+            this.focusChanges += 1;
+        });
+        on('scroll', () => {
+            this.mark();
+            this.scrolls += 1;
+        });
+    }
+    onMove(e) {
+        this.mark();
+        const x = e.clientX ?? 0;
+        const y = e.clientY ?? 0;
+        const now = Date.now();
+        if (this.lastX !== null && this.lastY !== null) {
+            const dx = x - this.lastX;
+            const dy = y - this.lastY;
+            const d = Math.hypot(dx, dy);
+            this.distance += d;
+            this.netDx += dx;
+            this.netDy += dy;
+            const dt = now - this.lastMoveT;
+            if (dt > 0) {
+                const speed = d / dt;
+                this.speeds.push(speed);
+                if (speed > this.maxSpeed)
+                    this.maxSpeed = speed;
+            }
+        }
+        this.moves += 1;
+        this.lastX = x;
+        this.lastY = y;
+        this.lastMoveT = now;
+    }
+    onKeyDown(e) {
+        this.mark();
+        this.keyCount += 1;
+        if (e.key === 'Backspace')
+            this.backspaces += 1;
+        // Keyed by physical code only — never the character. Content is never read.
+        this.downAt.set(e.code || e.key || String(this.keyCount), Date.now());
+        if (this.lastUpAt !== null)
+            this.flight.push(Date.now() - this.lastUpAt);
+    }
+    onKeyUp(e) {
+        const k = e.code || e.key || '';
+        const down = this.downAt.get(k);
+        const now = Date.now();
+        if (down !== undefined) {
+            this.dwell.push(now - down);
+            this.downAt.delete(k);
+        }
+        this.lastUpAt = now;
+    }
+    /** A snapshot of aggregates so far. Safe to call repeatedly. */
+    snapshot() {
+        const netDist = Math.hypot(this.netDx, this.netDy);
+        return {
+            mouseMoves: this.moves,
+            mouseDistance: Math.round(this.distance),
+            mouseAvgSpeed: mean(this.speeds),
+            mouseMaxSpeed: Math.round(this.maxSpeed * 1000) / 1000,
+            mouseSpeedVariance: variance(this.speeds),
+            mouseStraightLineRatio: this.distance > 0 ? Math.min(1, netDist / this.distance) : null,
+            keyCount: this.keyCount,
+            keyAvgDwellMs: mean(this.dwell),
+            keyAvgFlightMs: mean(this.flight),
+            keyDwellVariance: variance(this.dwell),
+            keyFlightVariance: variance(this.flight),
+            pasteCount: this.pastes,
+            backspaceCount: this.backspaces,
+            timeToFirstInteractionMs: this.firstInteraction,
+            timeToSubmitMs: Date.now() - this.start,
+            focusChanges: this.focusChanges,
+            scrollCount: this.scrolls,
+            hadPointerMove: this.moves > 0,
+            hadKeydown: this.keyCount > 0,
+            interactionCount: this.moves + this.keyCount + this.scrolls + this.focusChanges,
+        };
+    }
+    /** Detach all listeners. */
+    stop() {
+        const t = this.target;
+        if (!t)
+            return;
+        for (const [type, fn] of this.bound)
+            safe(() => t.removeEventListener(type, fn), undefined);
+        this.bound = [];
+    }
+}
+exports.BehaviorRecorder = BehaviorRecorder;
+/**
+ * Collect a device snapshot (+ behaviour from `recorder`, if given) and POST it.
+ * Resolves `true` when the beacon was accepted, `false` otherwise — never
+ * throws. Uses `navigator.sendBeacon` when possible so it survives navigation.
+ */
+async function sendTelemetry(opts) {
+    return safe(async () => {
+        const device = collectDeviceSignals();
+        const payload = {
+            attempt_id: opts.attemptId,
+            kind: opts.kind ?? 'telemetry',
+            device_id: deviceId(),
+            device_fingerprint: deviceFingerprint(device),
+            device,
+            behavior: opts.recorder?.snapshot(),
+        };
+        const url = `${opts.api}/v1/client/telemetry?publishable_key=${encodeURIComponent(opts.publishableKey)}`;
+        const body = JSON.stringify(payload);
+        // Prefer sendBeacon in production: it is fire-and-forget and survives the
+        // page unloading on submit. It cannot set the publishable-key HEADER, hence
+        // the query param above. A caller that INJECTS a fetchImpl (tests, custom
+        // transports) means "use exactly this" — so sendBeacon is skipped then.
+        const n = nav();
+        if (!opts.fetchImpl && n && typeof n.sendBeacon === 'function' && typeof Blob !== 'undefined') {
+            const ok = n.sendBeacon(url, new Blob([body], { type: 'application/json' }));
+            if (ok)
+                return true;
+        }
+        const doFetch = opts.fetchImpl ?? (typeof fetch !== 'undefined' ? fetch : undefined);
+        if (!doFetch)
+            return false;
+        const res = await doFetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'x-publishable-key': opts.publishableKey },
+            body,
+            keepalive: true,
+            credentials: 'include',
+        });
+        return res.ok;
+    }, Promise.resolve(false));
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

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

package/dist/token-cache.d.ts

@@ -0,0 +1,74 @@
+/**
+ * §7.4 step 1: "the SDK calls POST /v1/client/sessions/:sid/tokens with the
+ * refresh cookie whenever its cached JWT is within 10 s of expiry (proactive,
+ * jittered to avoid thundering herds across tabs)."
+ *
+ * The scheduling is the whole problem, and every parameter here is chosen
+ * against a specific failure:
+ *
+ *   Refreshing at expiry rather than before it means every request in the
+ *   window between "token died" and "new token arrived" gets a 401. Users
+ *   experience that as random logouts on slow connections.
+ *
+ *   Refreshing with no jitter means twenty tabs wake at the same millisecond
+ *   and hit the API together — which is fine at ten users and an outage at ten
+ *   thousand.
+ *
+ *   Jittering too WIDELY is worse than not jittering: a token with 60 seconds
+ *   of life, refreshed 10 seconds early with ±15 seconds of jitter, sometimes
+ *   refreshes after it has already expired. The jitter window is therefore
+ *   bounded to strictly less than the lead time, and there is a test that
+ *   pins it.
+ */
+/** §7.4: refresh once the token is within this of expiring. */
+export declare const REFRESH_LEAD_MS = 10000;
+/**
+ * Jitter is subtracted from the delay only, never added. Adding could push the
+ * refresh past expiry; subtracting only ever makes it earlier, which is safe.
+ */
+export declare const MAX_JITTER_MS = 5000;
+export interface CachedToken {
+    jwt: string;
+    /** Absolute expiry, epoch ms. */
+    expiresAt: number;
+    sessionId: string;
+}
+export interface ScheduleInput {
+    token: CachedToken;
+    now: number;
+    leadMs?: number;
+    /** Injected so the schedule is deterministic under test. */
+    jitter?: () => number;
+}
+/**
+ * Milliseconds until this token should be refreshed.
+ *
+ * Zero means "refresh now" — the token is already inside its lead window, or
+ * past expiry. Never negative, because a negative delay in a `setTimeout` is
+ * silently treated as zero anyway and the explicit clamp is clearer than
+ * relying on that.
+ */
+export declare function msUntilRefresh(input: ScheduleInput): number;
+/** Whether the cached token can still be handed to a caller. */
+export declare function isUsable(token: CachedToken | null, now: number, skewMs?: number): boolean;
+/**
+ * Read `exp` out of a JWT without verifying it.
+ *
+ * Deliberately does NOT verify. The client cannot verify — it has no key, and
+ * shipping one would be absurd — so this is a scheduling hint and nothing more.
+ * Every security decision is made by the server against a signature; a token
+ * whose `exp` a hostile party edited only causes the client to refresh at the
+ * wrong moment, which the server then rejects on its own terms.
+ */
+export declare function readExpiry(jwt: string): number | null;
+export declare class TokenCache {
+    private readonly now;
+    private token;
+    constructor(now?: () => number);
+    set(token: CachedToken): void;
+    /** The cached token, or null if it is gone or too close to expiry to use. */
+    get(skewMs?: number): CachedToken | null;
+    /** Present regardless of usability — for deciding whether to refresh or sign in. */
+    peek(): CachedToken | null;
+    clear(): void;
+}

package/dist/token-cache.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * §7.4 step 1: "the SDK calls POST /v1/client/sessions/:sid/tokens with the
+ * refresh cookie whenever its cached JWT is within 10 s of expiry (proactive,
+ * jittered to avoid thundering herds across tabs)."
+ *
+ * The scheduling is the whole problem, and every parameter here is chosen
+ * against a specific failure:
+ *
+ *   Refreshing at expiry rather than before it means every request in the
+ *   window between "token died" and "new token arrived" gets a 401. Users
+ *   experience that as random logouts on slow connections.
+ *
+ *   Refreshing with no jitter means twenty tabs wake at the same millisecond
+ *   and hit the API together — which is fine at ten users and an outage at ten
+ *   thousand.
+ *
+ *   Jittering too WIDELY is worse than not jittering: a token with 60 seconds
+ *   of life, refreshed 10 seconds early with ±15 seconds of jitter, sometimes
+ *   refreshes after it has already expired. The jitter window is therefore
+ *   bounded to strictly less than the lead time, and there is a test that
+ *   pins it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenCache = exports.MAX_JITTER_MS = exports.REFRESH_LEAD_MS = void 0;
+exports.msUntilRefresh = msUntilRefresh;
+exports.isUsable = isUsable;
+exports.readExpiry = readExpiry;
+/** §7.4: refresh once the token is within this of expiring. */
+exports.REFRESH_LEAD_MS = 10_000;
+/**
+ * Jitter is subtracted from the delay only, never added. Adding could push the
+ * refresh past expiry; subtracting only ever makes it earlier, which is safe.
+ */
+exports.MAX_JITTER_MS = 5_000;
+/**
+ * Milliseconds until this token should be refreshed.
+ *
+ * Zero means "refresh now" — the token is already inside its lead window, or
+ * past expiry. Never negative, because a negative delay in a `setTimeout` is
+ * silently treated as zero anyway and the explicit clamp is clearer than
+ * relying on that.
+ */
+function msUntilRefresh(input) {
+    const lead = input.leadMs ?? exports.REFRESH_LEAD_MS;
+    const jitterFn = input.jitter ?? (() => Math.random() * exports.MAX_JITTER_MS);
+    // Bounded to strictly less than the lead, so subtracting jitter can never
+    // move the refresh past the moment the token actually dies.
+    const jitter = Math.min(Math.max(jitterFn(), 0), Math.max(lead - 1, 0));
+    const target = input.token.expiresAt - lead - jitter;
+    return Math.max(0, target - input.now);
+}
+/** Whether the cached token can still be handed to a caller. */
+function isUsable(token, now, skewMs = 0) {
+    if (!token)
+        return false;
+    return token.expiresAt - skewMs > now;
+}
+/**
+ * Read `exp` out of a JWT without verifying it.
+ *
+ * Deliberately does NOT verify. The client cannot verify — it has no key, and
+ * shipping one would be absurd — so this is a scheduling hint and nothing more.
+ * Every security decision is made by the server against a signature; a token
+ * whose `exp` a hostile party edited only causes the client to refresh at the
+ * wrong moment, which the server then rejects on its own terms.
+ */
+function readExpiry(jwt) {
+    const parts = jwt.split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        const payload = JSON.parse(atob(parts[1].replace(/-/g, '+').replace(/_/g, '/')));
+        return typeof payload.exp === 'number' ? payload.exp * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}
+class TokenCache {
+    now;
+    token = null;
+    constructor(now = () => Date.now()) {
+        this.now = now;
+    }
+    set(token) {
+        this.token = token;
+    }
+    /** The cached token, or null if it is gone or too close to expiry to use. */
+    get(skewMs = 0) {
+        if (!isUsable(this.token, this.now(), skewMs))
+            return null;
+        return this.token;
+    }
+    /** Present regardless of usability — for deciding whether to refresh or sign in. */
+    peek() {
+        return this.token;
+    }
+    clear() {
+        this.token = null;
+    }
+}
+exports.TokenCache = TokenCache;
+//# sourceMappingURL=token-cache.js.map

package/dist/token-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-cache.js","sourceRoot":"","sources":["../src/token-cache.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAkCH,wCAUC;AAGD,4BAGC;AAWD,gCAYC;AAvED,+DAA+D;AAClD,QAAA,eAAe,GAAG,MAAM,CAAC;AAEtC;;;GAGG;AACU,QAAA,aAAa,GAAG,KAAK,CAAC;AAiBnC;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,KAAoB;IACjD,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,IAAI,uBAAe,CAAC;IAC7C,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,qBAAa,CAAC,CAAC;IAEvE,0EAA0E;IAC1E,4DAA4D;IAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAExE,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,GAAG,MAAM,CAAC;IACrD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC;AAED,gEAAgE;AAChE,SAAgB,QAAQ,CAAC,KAAyB,EAAE,GAAW,EAAE,MAAM,GAAG,CAAC;IACzE,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,OAAO,KAAK,CAAC,SAAS,GAAG,MAAM,GAAG,GAAG,CAAC;AACxC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,UAAU,CAAC,GAAW;IACpC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEpC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAE/E,CAAC;QACF,OAAO,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAa,UAAU;IAGQ;IAFrB,KAAK,GAAuB,IAAI,CAAC;IAEzC,YAA6B,MAAoB,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;QAApC,QAAG,GAAH,GAAG,CAAiC;IAAG,CAAC;IAErE,GAAG,CAAC,KAAkB;QACpB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,6EAA6E;IAC7E,GAAG,CAAC,MAAM,GAAG,CAAC;QACZ,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3D,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,oFAAoF;IACpF,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;CACF;AAvBD,gCAuBC"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@atlasauth/js",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "devDependencies": {
+    "happy-dom": "^15.11.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "dependencies": {
+    "@atlasauth/authz": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}