@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/auth/AuthManager.js

@@ -0,0 +1,435 @@
+import { randomBytes, randomUUID, createHash, timingSafeEqual } from 'node:crypto';
+import { resolve } from 'node:path';
+import { createRemoteJWKSet, customFetch, jwtVerify } from 'jose';
+import { AuthError } from './types.js';
+import { KeyringCredentialStore } from './store.js';
+import { withAuthLock } from './lock.js';
+import { openBrowser, receiveAuthorizationCode } from './callback.js';
+const MAX_REFRESH_MS = 3650 * 24 * 60 * 60 * 1000;
+/** One rotation attempt's own bound. A caller's deadline never cuts into it (see `rotate`). */
+const REFRESH_ATTEMPT_MS = 10_000;
+/** How long after a first attempt a lost rotation may be repeated. The deployment keeps the
+ *  previous refresh token usable for a 60-second grace after rotating, which exists for exactly
+ *  this retry; the window stays well inside it even when the first attempt used its whole bound. */
+const REFRESH_RETRY_WINDOW_MS = 20_000;
+/** JWKS fetching and signature verification after a rotation. */
+const AUTH_VERIFY_BUDGET_MS = 5_000;
+/** One complete exchange path: two attempts plus verification of the result. */
+const AUTH_EXCHANGE_BUDGET_MS = 2 * REFRESH_ATTEMPT_MS + AUTH_VERIFY_BUDGET_MS;
+/** A concurrent waiter must outlast one complete retry-and-verify path, not just one attempt:
+ *  a waiter that times out here would report `busy` for a session that is about to be persisted. */
+const AUTH_LOCK_WAIT_MS = AUTH_EXCHANGE_BUDGET_MS + 5_000;
+/**
+ * What a caller must be willing to wait for token acquisition.
+ *
+ * The caller's signal is not allowed to abandon a rotation (see `rotate`), but it does bound how
+ * long the caller waits: a caller that cancels while another process holds the auth lock would
+ * report a valid session as unavailable instead of reading the session that process is about to
+ * persist. The budget therefore covers waiting for the lock *and* running this caller's own
+ * exchange, not just the exchange.
+ */
+export const AUTH_REFRESH_BUDGET_MS = AUTH_LOCK_WAIT_MS + AUTH_EXCHANGE_BUDGET_MS;
+const same = (a, b) => Buffer.byteLength(a) === Buffer.byteLength(b) && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+/** Early persistence for a rotated refresh token: claims are decoded without signature checks
+ *  only to reject a response naming a different subject; full verification runs right after.
+ *  The zero expiry keeps every later call on the refresh path until verification succeeds, so a
+ *  token whose claimed expiry is in the future cannot wedge recovery behind a failed check. */
+function interimSession(tokens, previous) {
+    const accessToken = typeof tokens.access_token === 'string' && tokens.access_token ? tokens.access_token : undefined;
+    const refreshToken = typeof tokens.refresh_token === 'string' && tokens.refresh_token.length > 0 && tokens.refresh_token.length <= 16000 ? tokens.refresh_token : undefined;
+    if (!accessToken || !refreshToken)
+        return;
+    try {
+        const claims = JSON.parse(Buffer.from(accessToken.split('.')[1] ?? '', 'base64url').toString('utf8'));
+        if (typeof claims.sub === 'string' && claims.sub && claims.sub !== previous.subject)
+            return;
+    }
+    catch { /* The token stays usable for recovery: the next call refreshes with it. */ }
+    return { accessToken, refreshToken, subject: previous.subject, expiresAt: 0, refreshExpiresAt: previous.refreshExpiresAt, nonce: previous.nonce };
+}
+async function abortable(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted) {
+        void promise.catch(() => { });
+        throw new AuthError('cancelled', 'Authentication cancelled.');
+    }
+    let cancel;
+    const aborted = new Promise((_, reject) => { cancel = () => reject(new AuthError('cancelled', 'Authentication cancelled.')); signal.addEventListener('abort', cancel, { once: true }); });
+    try {
+        return await Promise.race([promise, aborted]);
+    }
+    finally {
+        signal.removeEventListener('abort', cancel);
+    }
+}
+export function validateAuthConfiguration(c) {
+    if (!c || !/^[a-z0-9]{1,128}$/.test(c.clientId) || c.redirectUri !== 'http://localhost:43187/callback')
+        throw new AuthError('configuration', 'Andorra account authentication is not configured in this installation.');
+    for (const key of ['issuer', 'domain', 'apiBaseUrl']) {
+        let url;
+        try {
+            url = new URL(c[key]);
+        }
+        catch {
+            throw new AuthError('configuration', 'Andorra account authentication is not configured in this installation.');
+        }
+        if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || c[key].endsWith('/'))
+            throw new AuthError('configuration', 'Invalid Andorra account service configuration.');
+        if (key === 'domain' && url.pathname !== '/')
+            throw new AuthError('configuration', 'Invalid Andorra sign-in domain.');
+    }
+}
+/**
+ * The credential store's identity.
+ *
+ * The deployment binds a stored session to one account service. A distinct config home
+ * (`ANDORRACODE_HOME`) additionally binds it to that home, so a test, QA or throwaway home can
+ * never read, rotate or wipe the credentials of the real one — those processes authenticate
+ * against the same account service, and a rotation lost on their side would end the user's
+ * session. The default home keeps the original identity, so an existing login survives an
+ * upgrade unchanged.
+ */
+/**
+ * Whether a verification failure came from fetching the JSON Web Key Set rather than from the token:
+ * jose's own timeout and non-200 errors, a failed fetch, or a transport error anywhere in the cause
+ * chain. A signature, issuer, audience or claim failure is none of these and stays a rejection.
+ */
+export function keySetUnavailable(error) {
+    let current = error;
+    for (let depth = 0; depth < 8 && current && typeof current === 'object'; depth++) {
+        const failure = current;
+        if (failure.code === 'ERR_JWKS_TIMEOUT')
+            return true;
+        if (failure.code === 'ERR_JOSE_GENERIC' && typeof failure.message === 'string' && /JSON Web Key Set HTTP response/i.test(failure.message))
+            return true;
+        if (typeof failure.code === 'string' && /^(?:ECONN|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|EPIPE|UND_ERR_)/.test(failure.code))
+            return true;
+        if (current instanceof TypeError && typeof failure.message === 'string' && /fetch failed|network/i.test(failure.message))
+            return true;
+        current = failure.cause;
+    }
+    return false;
+}
+export function credentialIdentity(config, environment = process.env) {
+    const identity = `${config.issuer}|${config.clientId}`;
+    const home = environment.ANDORRACODE_HOME;
+    if (!home)
+        return identity;
+    // The path is kept exactly as given: Windows directories can be case-sensitive or hosted on a
+    // case-sensitive mount, and two distinct homes must never share one credential scope.
+    return `${identity}|${resolve(home)}`;
+}
+export class AuthManager {
+    options;
+    config;
+    store;
+    fetch;
+    keys;
+    constructor(options) {
+        this.options = options;
+        validateAuthConfiguration(options.config);
+        this.config = { ...options.config };
+        this.store = options.store ?? new KeyringCredentialStore(credentialIdentity(this.config));
+        this.fetch = options.fetch ?? globalThis.fetch;
+        this.keys = createRemoteJWKSet(new URL(`${this.config.issuer}/.well-known/jwks.json`), { timeoutDuration: 5000, [customFetch]: (url, init) => this.fetch(url, init) });
+    }
+    locked(operation, signal) { return withAuthLock(operation, signal, this.options.lockPort, AUTH_LOCK_WAIT_MS); }
+    async read() {
+        const text = await this.store.read();
+        if (!text)
+            return { version: 1, generation: randomUUID() };
+        try {
+            const value = JSON.parse(text);
+            if (value.version !== 1 || typeof value.generation !== 'string' || value.generation.length > 100)
+                throw new Error();
+            const s = value.session;
+            if (s && (!s.accessToken || typeof s.accessToken !== 'string' || typeof s.refreshToken !== 'string' || !s.refreshToken || typeof s.subject !== 'string' || !s.subject || typeof s.nonce !== 'string' || !Number.isFinite(s.expiresAt) || !Number.isFinite(s.refreshExpiresAt)))
+                throw new Error();
+            return value;
+        }
+        catch {
+            throw new AuthError('storage', 'Stored authentication data is invalid. Run andorra logout, then sign in again.');
+        }
+    }
+    async post(path, body, signal) {
+        // A caller's abort and this layer's own deadline are different failures: only the former is
+        // a cancellation, and only the latter can be treated as a lost response and retried.
+        const deadline = AbortSignal.timeout(10000);
+        try {
+            return await this.fetch(`${this.config.domain}${path}`, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body, redirect: 'error', signal: signal ? AbortSignal.any([signal, deadline]) : deadline });
+        }
+        catch {
+            if (signal?.aborted)
+                throw new AuthError('cancelled', 'Authentication cancelled.');
+            if (deadline.aborted)
+                throw new AuthError('network', 'The account service did not respond in time. Retry shortly.');
+            throw new AuthError('network', 'The account service is unavailable. Retry shortly.');
+        }
+    }
+    async tokenResponse(body, signal) {
+        const response = await this.post('/oauth2/token', body, signal);
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => { });
+            if (response.status === 400 || response.status === 401)
+                throw new AuthError('login_required', 'Your Andorra session has expired or was revoked. Please sign in again.');
+            throw new AuthError('network', 'The account service is unavailable. Retry shortly.');
+        }
+        let reader;
+        try {
+            reader = response.body?.getReader();
+            if (!reader)
+                throw new Error();
+            const chunks = [];
+            let size = 0;
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                size += value.length;
+                if (size > 64000)
+                    throw new Error();
+                chunks.push(value);
+            }
+            const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            if (!value || typeof value !== 'object' || Array.isArray(value) || value.token_type?.toLowerCase() !== 'bearer')
+                throw new Error();
+            return value;
+        }
+        catch {
+            throw new AuthError('invalid_token', 'The account service returned an invalid token response.');
+        }
+        finally {
+            if (reader) {
+                await reader.cancel().catch(() => { });
+                reader.releaseLock();
+            }
+        }
+    }
+    async verify(token, use, signal) {
+        try {
+            signal?.throwIfAborted();
+            const { payload } = await abortable(jwtVerify(token, this.keys, { issuer: this.config.issuer, algorithms: ['RS256'], requiredClaims: ['exp', 'iat', 'sub', 'token_use'], ...(use === 'id' ? { audience: this.config.clientId } : {}) }), signal);
+            signal?.throwIfAborted();
+            if (payload.token_use !== use || (use === 'access' && (payload.client_id !== this.config.clientId || typeof payload.scope !== 'string' || !payload.scope.split(' ').includes('andorra-code/decisions'))) || typeof payload.sub !== 'string' || !payload.sub || typeof payload.iat !== 'number' || payload.iat > Date.now() / 1000 + 30 || typeof payload.exp !== 'number' || payload.exp - payload.iat > 900)
+                throw new Error();
+            return payload;
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new AuthError('cancelled', 'Authentication cancelled.');
+            // A key set that could not be fetched says nothing about the token. Every fresh process
+            // fetches the keys on its first verification, and a transient failure there used to surface
+            // as a rejected credential: the membership client then answered "not signed in" and the run
+            // started with Jev off, silently. It is the service being unreachable, and is reported as such.
+            if (keySetUnavailable(error))
+                throw new AuthError('network', 'The account key set could not be fetched. Check the connection and retry.', { cause: error });
+            throw new AuthError('invalid_token', 'The account token could not be verified. Please sign in again.');
+        }
+    }
+    async session(value, nonce, previous, signal) {
+        if (typeof value.access_token !== 'string' || typeof value.id_token !== 'string' || typeof value.refresh_token !== 'string' || !value.refresh_token || value.refresh_token.length > 16000)
+            throw new AuthError('invalid_token', 'The account service did not return the required rotated tokens.');
+        const access = await this.verify(value.access_token, 'access', signal), id = await this.verify(value.id_token, 'id', signal);
+        if (id.sub !== access.sub || (previous && access.sub !== previous.subject) || (!previous && (typeof id.nonce !== 'string' || !same(id.nonce, nonce))) || (previous && id.nonce !== undefined && (typeof id.nonce !== 'string' || !same(id.nonce, nonce))))
+            throw new AuthError('invalid_token', 'The account token identity or login nonce did not match.');
+        return { accessToken: value.access_token, refreshToken: value.refresh_token, subject: access.sub, expiresAt: access.exp * 1000, refreshExpiresAt: previous?.refreshExpiresAt ?? Date.now() + MAX_REFRESH_MS, nonce };
+    }
+    async login(options = {}) {
+        const signal = AbortSignal.any([...(options.signal ? [options.signal] : []), AbortSignal.timeout(this.options.loginTimeoutMs ?? 120000)]);
+        const generation = randomUUID();
+        const state = randomBytes(32).toString('base64url'), nonce = randomBytes(32).toString('base64url'), verifier = randomBytes(48).toString('base64url');
+        const url = new URL(`${this.config.domain}/oauth2/authorize`);
+        url.search = new URLSearchParams({ response_type: 'code', client_id: this.config.clientId, redirect_uri: this.config.redirectUri, scope: 'openid email andorra-code/decisions', state, nonce, code_challenge: createHash('sha256').update(verifier).digest('base64url'), code_challenge_method: 'S256',
+            // Always ask for credentials: without this the hosted page silently reuses the browser's
+            // existing session, so signing out and back in could never switch to another account.
+            prompt: 'login' }).toString();
+        const code = await receiveAuthorizationCode({ url: url.toString(), state, redirectUri: this.config.redirectUri, signal, openBrowser: this.options.openBrowser ?? openBrowser, onMessage: options.onMessage,
+            // A competing login must own the callback port before superseding this generation.
+            onReady: () => this.locked(async () => { const current = await abortable(this.read(), signal); signal.throwIfAborted(); await this.store.write(JSON.stringify({ ...current, generation })); }, signal),
+        });
+        const tokens = await this.tokenResponse(new URLSearchParams({ grant_type: 'authorization_code', client_id: this.config.clientId, redirect_uri: this.config.redirectUri, code, code_verifier: verifier }), signal);
+        let session;
+        let replacedToken;
+        try {
+            session = await this.session(tokens, nonce, undefined, signal);
+            await this.locked(async () => {
+                const current = await abortable(this.read(), signal);
+                if (current.generation !== generation)
+                    throw new AuthError('superseded', 'This login was superseded by another login or logout.');
+                signal.throwIfAborted();
+                await this.store.write(JSON.stringify({ version: 1, generation, session }));
+                // Native writes cannot be interrupted safely. Undo a login cancelled during that write
+                // while still holding the cross-process lock, retaining any preceding signed-in session.
+                if (signal.aborted) {
+                    await this.store.write(JSON.stringify({ ...current, generation: randomUUID() }));
+                    throw new AuthError('cancelled', 'Authentication cancelled.');
+                }
+                replacedToken = current.session?.refreshToken;
+            }, signal);
+        }
+        catch (error) {
+            // Validation can fail before a Session exists. Only submit a bounded opaque token
+            // to the configured revocation endpoint, independently of the cancelled login.
+            if (typeof tokens.refresh_token === 'string' && tokens.refresh_token.length > 0 && tokens.refresh_token.length <= 16000) {
+                await this.revoke(tokens.refresh_token).catch(() => { });
+            }
+            throw error;
+        }
+        // Revoke only after the replacement commits and cancellation rollback is complete.
+        // A revocation outage must not turn the newly persisted login into a failure.
+        if (replacedToken && replacedToken !== session.refreshToken)
+            await this.revoke(replacedToken).catch(() => { });
+        return { signedIn: true, subject: session.subject, expiresAt: session.expiresAt };
+    }
+    async revoke(token, signal) {
+        const response = await this.post('/oauth2/revoke', new URLSearchParams({ token, client_id: this.config.clientId }), signal);
+        await response.body?.cancel().catch(() => { });
+        return response.ok;
+    }
+    async logout(signal) {
+        const token = await this.locked(async () => {
+            let token;
+            try {
+                token = (await abortable(this.read(), signal)).session?.refreshToken;
+            }
+            catch (error) {
+                if (!(error instanceof AuthError) || error.code !== 'storage')
+                    throw error;
+            }
+            if (signal?.aborted)
+                throw new AuthError('cancelled', 'Authentication cancelled.');
+            await this.store.clear(JSON.stringify({ version: 1, generation: randomUUID() }));
+            return token;
+        }, signal);
+        return { revoked: token ? await this.revoke(token, signal).catch(() => false) : true };
+    }
+    /**
+     * Exchange the stored refresh token for a rotated session.
+     *
+     * Runs on this layer's own bound, never a caller's: the token endpoint invalidates the
+     * previous refresh token as it issues the new one, so a caller's deadline that abandoned the
+     * request after the server rotated would leave the store holding a dead token — and the next
+     * refresh would be rejected as reuse and wipe the credential. Callers keep their deadlines
+     * for what they *observe* (`getAccessToken` checks the signal once the exchange has landed).
+     */
+    async rotate(current, session) {
+        const tokens = await this.refreshTokens(session.refreshToken);
+        // Rotation invalidated the previous refresh token the moment this response was issued,
+        // so the replacement is persisted before any verification work: a process interrupted
+        // between the token response and this write would otherwise restart on the dead token,
+        // fail its next refresh, and wipe the only credential it had. Verification still runs
+        // before anything is returned from this call.
+        const interim = interimSession(tokens, session);
+        if (interim)
+            await this.store.write(JSON.stringify({ ...current, session: interim }));
+        const next = await this.session(tokens, session.nonce, session);
+        await this.store.write(JSON.stringify({ ...current, session: next }));
+        return next;
+    }
+    /**
+     * Request one rotation, repeating a lost response once inside the server's retry grace.
+     *
+     * A transport failure, our own deadline, or an unreadable response all mean the same thing:
+     * whether the server rotated is unknown. This deployment keeps the previous refresh token
+     * usable for a short grace window after a rotation, so repeating the identical request
+     * recovers whether or not that happened. A token the server rejected outright is dead and is
+     * never retried; the caller wipes it.
+     */
+    async refreshTokens(refreshToken) {
+        const request = () => this.tokenResponse(new URLSearchParams({ grant_type: 'refresh_token', client_id: this.config.clientId, refresh_token: refreshToken }));
+        const started = Date.now();
+        try {
+            return await request();
+        }
+        catch (error) {
+            const uncertain = error instanceof AuthError && (error.code === 'network' || error.code === 'invalid_token');
+            if (!uncertain || Date.now() - started >= REFRESH_RETRY_WINDOW_MS)
+                throw error;
+            return await request();
+        }
+    }
+    /**
+     * Wipe a credential the account service has definitively rejected, report that once, and return
+     * the error the caller should surface.
+     *
+     * The rejection stays the surfaced failure even when the store could not finish clearing: the
+     * token really was refused, and reporting only a storage error would let callers treat the
+     * refusal as uncertainty — the graph editor, for instance, keeps paid access on an unavailable
+     * membership result. A cleanup failure rides along as the cause, and the removal is announced
+     * only when the credential is actually gone: a clear() that failed before writing its tombstone
+     * leaves the rejected session readable, so claiming it was removed would be wrong and would
+     * repeat on every run until the store recovers.
+     */
+    async clearRejectedCredential(rejection) {
+        let failure;
+        try {
+            await this.store.clear(JSON.stringify({ version: 1, generation: randomUUID() }));
+        }
+        catch (error) {
+            failure = error;
+        }
+        const removed = failure === undefined || await this.credentialAbsent();
+        if (removed) {
+            try {
+                this.options.onSignOut?.(rejection);
+            }
+            catch { /* Reporting must never replace the failure the caller is about to see. */ }
+        }
+        if (failure === undefined)
+            return rejection;
+        return new AuthError(rejection.code, `${rejection.message}${removed ? '' : ' The stored credential could not be removed; unlock the OS credential store and run andorra logout.'}`, { cause: failure });
+    }
+    /** Whether the store no longer holds a session: a clear() committed, or it was already empty. */
+    async credentialAbsent() {
+        try {
+            return (await this.read()).session === undefined;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * The access token and the account it belongs to, read as one answer.
+     *
+     * The two are one credential: a sign-in between a status read and a token read would let a
+     * request that named one account authenticate as another, and the request would answer with the
+     * other account's data. Under the same lock they are one answer, and the caller can check the
+     * subject against the token it is about to use.
+     */
+    async tokenAndSubject(signal) {
+        const current = await abortable(this.read(), signal);
+        const session = current.session;
+        if (!session || session.refreshExpiresAt <= Date.now())
+            throw new AuthError('login_required', 'Sign in to your Andorra account first with andorra login.');
+        if (session.expiresAt > Date.now() + 60000) {
+            const payload = await this.verify(session.accessToken, 'access', signal);
+            if (payload.sub !== session.subject)
+                throw new AuthError('invalid_token', 'Stored account identity did not match.');
+            return { token: session.accessToken, subject: session.subject };
+        }
+        try {
+            const next = await this.rotate(current, session);
+            // The rotated session is persisted no matter what the caller does now; the deadline
+            // only decides whether that caller waits for it or is told it was cancelled.
+            if (signal?.aborted)
+                throw new AuthError('cancelled', 'Authentication cancelled.');
+            return { token: next.accessToken, subject: next.subject };
+        }
+        catch (error) {
+            if (error instanceof AuthError && error.code === 'login_required')
+                throw await this.clearRejectedCredential(error);
+            throw error;
+        }
+    }
+    async getAccessToken(signal) {
+        return this.locked(async () => (await this.tokenAndSubject(signal)).token, signal);
+    }
+    /** The access token and the account it belongs to, read as one operation. */
+    async credential(signal) {
+        return this.locked(() => this.tokenAndSubject(signal), signal);
+    }
+    async status(signal) {
+        return this.locked(async () => { const session = (await abortable(this.read(), signal)).session; return session && session.refreshExpiresAt > Date.now() ? { signedIn: true, subject: session.subject, expiresAt: session.expiresAt } : { signedIn: false }; }, signal);
+    }
+}

package/dist/src/auth/callback.d.ts

@@ -0,0 +1,10 @@
+export declare function openBrowser(url: string): Promise<void>;
+export declare function receiveAuthorizationCode(options: {
+    url: string;
+    state: string;
+    redirectUri: string;
+    signal: AbortSignal;
+    openBrowser: (url: string) => Promise<void>;
+    onReady?: () => Promise<void>;
+    onMessage?: (text: string) => void;
+}): Promise<string>;

package/dist/src/auth/callback.js

@@ -0,0 +1,96 @@
+import { createServer } from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { AuthError } from './types.js';
+export function openBrowser(url) {
+    return new Promise((resolve, reject) => {
+        const command = process.platform === 'win32' ? 'rundll32.exe' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+        const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+        execFile(command, args, { windowsHide: true, timeout: 10000 }, error => error ? reject(new AuthError('callback', 'Could not open your browser. Retry login from a desktop session.')) : resolve());
+    });
+}
+export async function receiveAuthorizationCode(options) {
+    const redirect = new URL(options.redirectUri);
+    const servers = [];
+    let settle;
+    const response = new Promise(resolve => { settle = resolve; });
+    const cancel = () => settle(new AuthError('cancelled', 'Authentication cancelled or timed out.'));
+    options.signal.addEventListener('abort', cancel, { once: true });
+    try {
+        options.signal.throwIfAborted();
+        for (const host of ['127.0.0.1', '::1']) {
+            const server = createServer({ maxHeaderSize: 8192 }, (request, reply) => {
+                reply.setHeader('Content-Type', 'text/plain; charset=utf-8');
+                reply.setHeader('Cache-Control', 'no-store');
+                reply.setHeader('Referrer-Policy', 'no-referrer');
+                reply.setHeader('X-Content-Type-Options', 'nosniff');
+                const fail = () => { reply.writeHead(400); reply.end('Invalid login callback. Return to the original login window.'); };
+                if (request.method !== 'GET' || request.headers.host !== redirect.host || request.rawHeaders.filter((_, i) => i % 2 === 0 && request.rawHeaders[i].toLowerCase() === 'host').length !== 1 || !request.url?.startsWith('/') || request.url.startsWith('//') || request.url.length > 8192) {
+                    fail();
+                    return;
+                }
+                let url;
+                try {
+                    url = new URL(request.url, redirect.origin);
+                }
+                catch {
+                    fail();
+                    return;
+                }
+                if (url.pathname !== redirect.pathname || [...url.searchParams.keys()].some(key => url.searchParams.getAll(key).length !== 1)) {
+                    fail();
+                    return;
+                }
+                const state = url.searchParams.get('state') ?? '';
+                if (Buffer.byteLength(state) !== Buffer.byteLength(options.state) || !timingSafeEqual(Buffer.from(state), Buffer.from(options.state))) {
+                    fail();
+                    return;
+                }
+                if (url.searchParams.has('error')) {
+                    reply.writeHead(400);
+                    reply.end('Login was not completed. Return to Andorra.');
+                    settle(new AuthError('callback', 'The sign-in service declined this login.'));
+                    return;
+                }
+                const code = url.searchParams.get('code');
+                if (!code || code.length > 4096 || /[\r\n]/.test(code)) {
+                    fail();
+                    return;
+                }
+                reply.end('Login received. You may close this tab and return to Andorra.');
+                settle(code);
+            });
+            server.headersTimeout = 5000;
+            server.requestTimeout = 5000;
+            server.keepAliveTimeout = 1000;
+            servers.push(server);
+            await new Promise((resolve, reject) => {
+                server.once('error', (error) => host === '::1' && ['EAFNOSUPPORT', 'EADDRNOTAVAIL'].includes(error.code ?? '') ? resolve() : reject(new AuthError('callback', 'The login callback port 43187 is unavailable. Close other login attempts and retry.')));
+                server.listen({ host, port: Number(redirect.port), ipv6Only: host === '::1', exclusive: true }, resolve);
+            });
+        }
+        options.signal.throwIfAborted();
+        await options.onReady?.();
+        if (options.signal.aborted)
+            cancel();
+        else {
+            options.onMessage?.('Opening your browser to sign in or create an Andorra account.');
+            // Race a stuck desktop opener against cancellation without delaying listener cleanup.
+            void options.openBrowser(options.url).catch(() => settle(new AuthError('callback', 'Could not open your browser. Retry login from a desktop session.')));
+        }
+        const result = await response;
+        if (result instanceof AuthError)
+            throw result;
+        return result;
+    }
+    catch (error) {
+        throw error instanceof AuthError ? error : new AuthError('cancelled', 'Authentication cancelled.');
+    }
+    finally {
+        options.signal.removeEventListener('abort', cancel);
+        await Promise.all(servers.map(server => new Promise(resolve => { server.closeAllConnections(); if (!server.listening)
+            resolve();
+        else
+            server.close(() => resolve()); })));
+    }
+}

package/dist/src/auth/deployment.d.ts

@@ -0,0 +1,18 @@
+/** Public deployment metadata only. Tokens and client secrets never belong here. */
+export declare const AUTH_DEPLOYMENT: {
+    issuer: string;
+    clientId: string;
+    domain: string;
+    apiBaseUrl: string;
+    /**
+     * The dedicated telemetry ingest, provisioned in the same stack as `apiBaseUrl`. It is a REST API
+     * of its own because WAF attaches only to REST APIs, and telemetry load must not share the
+     * throttle membership and decision traffic depend on. Its id is generated at deploy time, so this
+     * value is stamped from the stack's `TelemetryApiUrl` output by
+     * `node scripts/telemetry-endpoint.mjs --write` after the template is deployed — not edited by
+     * hand. Until then it stays empty and the drainer is a no-op that only holds events in the
+     * bounded outbox.
+     */
+    telemetryBaseUrl: string;
+    redirectUri: string;
+};

package/dist/src/auth/deployment.js

@@ -0,0 +1,18 @@
+/** Public deployment metadata only. Tokens and client secrets never belong here. */
+export const AUTH_DEPLOYMENT = {
+    issuer: 'https://cognito-idp.us-east-2.amazonaws.com/us-east-2_RBw7LImHf',
+    clientId: '5gsaecbpdqnt6a0mh6u6h46gag',
+    domain: 'https://andorra-code-auth-950992723121.auth.us-east-2.amazoncognito.com',
+    apiBaseUrl: 'https://g2jkeh2w1k.execute-api.us-east-2.amazonaws.com/v1',
+    /**
+     * The dedicated telemetry ingest, provisioned in the same stack as `apiBaseUrl`. It is a REST API
+     * of its own because WAF attaches only to REST APIs, and telemetry load must not share the
+     * throttle membership and decision traffic depend on. Its id is generated at deploy time, so this
+     * value is stamped from the stack's `TelemetryApiUrl` output by
+     * `node scripts/telemetry-endpoint.mjs --write` after the template is deployed — not edited by
+     * hand. Until then it stays empty and the drainer is a no-op that only holds events in the
+     * bounded outbox.
+     */
+    telemetryBaseUrl: '',
+    redirectUri: 'http://localhost:43187/callback',
+};

package/dist/src/auth/index.d.ts

@@ -0,0 +1,31 @@
+import type { AuthConfiguration, AuthError } from './types.js';
+export * from './types.js';
+export { AuthManager, AUTH_REFRESH_BUDGET_MS } from './AuthManager.js';
+export { credentialIdentity } from './AuthManager.js';
+export { KeyringCredentialStore } from './store.js';
+export declare function getAuthConfiguration(): AuthConfiguration;
+/**
+ * Report an automatic sign-out: the account service rejected the stored refresh token, so the
+ * credential was removed and the user must sign in again. The report is the only trace that
+ * sign-out leaves, because the wipe itself is silent by design (it removes the credential).
+ */
+export declare function setAuthSignOutReporter(reporter?: (error: AuthError) => void): void;
+export declare const login: (options?: {
+    signal?: AbortSignal;
+    onMessage?: (message: string) => void;
+}) => Promise<import("./types.js").AuthStatus>;
+export declare const logout: (signal?: AbortSignal) => Promise<{
+    revoked: boolean;
+}>;
+export declare const getAccessToken: (signal?: AbortSignal) => Promise<string>;
+/**
+ * The access token and the account it belongs to, read as one operation.
+ *
+ * A caller that must know which account a token belongs to asks here: the two are one credential,
+ * and a sign-in between two reads would answer with another account's.
+ */
+export declare const getCredential: (signal?: AbortSignal) => Promise<{
+    token: string;
+    subject: string;
+}>;
+export declare const getAuthStatus: (signal?: AbortSignal) => Promise<import("./types.js").AuthStatus>;

package/dist/src/auth/index.js

@@ -0,0 +1,27 @@
+import { AUTH_DEPLOYMENT } from './deployment.js';
+import { AuthManager } from './AuthManager.js';
+export * from './types.js';
+export { AuthManager, AUTH_REFRESH_BUDGET_MS } from './AuthManager.js';
+export { credentialIdentity } from './AuthManager.js';
+export { KeyringCredentialStore } from './store.js';
+export function getAuthConfiguration() { return { ...AUTH_DEPLOYMENT }; }
+let manager;
+let signOutReporter;
+/**
+ * Report an automatic sign-out: the account service rejected the stored refresh token, so the
+ * credential was removed and the user must sign in again. The report is the only trace that
+ * sign-out leaves, because the wipe itself is silent by design (it removes the credential).
+ */
+export function setAuthSignOutReporter(reporter) { signOutReporter = reporter; }
+function auth() { return manager ??= new AuthManager({ config: getAuthConfiguration(), onSignOut: error => signOutReporter?.(error) }); }
+export const login = (options = {}) => auth().login(options);
+export const logout = (signal) => auth().logout(signal);
+export const getAccessToken = (signal) => auth().getAccessToken(signal);
+/**
+ * The access token and the account it belongs to, read as one operation.
+ *
+ * A caller that must know which account a token belongs to asks here: the two are one credential,
+ * and a sign-in between two reads would answer with another account's.
+ */
+export const getCredential = (signal) => auth().credential(signal);
+export const getAuthStatus = (signal) => auth().status(signal);

package/dist/src/auth/lock.d.ts

@@ -0,0 +1,2 @@
+/** An OS-owned exclusive loopback listener is released on process death, with no stale lockfiles. */
+export declare function withAuthLock<T>(operation: () => Promise<T>, signal?: AbortSignal, port?: number, waitMs?: number): Promise<T>;