@andco/sdk 0.0.1

package/dist/browser/index.js

@@ -0,0 +1,117 @@
+import { AndcoClient } from "../client.js";
+import { ANDCO_ERROR_CODES, Result } from "../errors.js";
+import { WebStorage } from "../storage.js";
+import { andcoPopupPresentationId, isAndcoNativeHost, openAndcoPopup, relayAndcoPopupCallback } from "./popup.js";
+export { AndcoButtonController, } from "./controller.js";
+export { AndcoButtonBridge } from "./frame.js";
+export { andcoPopupPresentationId, isAndcoNativeHost, openAndcoPopup, openAndcoPopupWindow, relayAndcoPopupCallback, } from "./popup.js";
+/**
+ * Presents an authorization in a browser.
+ *
+ * It detects the first-party Andco Host and routes over the native bridge instead of opening a
+ * window, so a Miniapp runs the same build in a browser tab and inside the Host without branching
+ * on the platform. That is why there is no mobile presenter and no mobile builder.
+ */
+export function browserPresenter() {
+    return {
+        async present(options) {
+            if (typeof window === "undefined")
+                return Result.fail(ANDCO_ERROR_CODES.BROWSER_REQUIRED);
+            if (options.presentation === "redirect") {
+                window.location.assign(options.url.href);
+                // The document is being replaced. The result arrives on the next load, not here.
+                return Result.ok(null);
+            }
+            if (isAndcoNativeHost() && window.__ANDCO_NATIVE_POPUP_HANDLER__ !== true) {
+                return Result.fail(ANDCO_ERROR_CODES.PRESENTATION_UNSUPPORTED, {
+                    message: "the native Host cannot present a popup without navigating the Miniapp",
+                });
+            }
+            return openAndcoPopup({
+                url: options.url,
+                presentationId: options.presentationId,
+                expectedOrigin: options.returnTo.origin,
+                signal: options.signal,
+            });
+        },
+    };
+}
+const TRANSACTION_KEY = "andco.transaction";
+/**
+ * Creates an Andco Instance for a browser.
+ *
+ * Construction is synchronous and performs no I/O. The one effect it does perform is the popup
+ * relay, and only when five conditions hold: this document has an opener, its `window.name` carries
+ * a valid Presentation ID, the URL carries callback parameters, the state parses, and the opener
+ * origin is allowed. A normal page fails the first two and the call is inert.
+ *
+ * Exchanging an authorization code is *not* done here. That is a credential write, the code is
+ * single-use, and a construction a framework discards must not burn it — so it happens lazily, on
+ * the store's first read.
+ *
+ * @example
+ * ```ts
+ * const andco = createAndcoInstanceForBrowser({
+ *   clientId: "your-public-oauth-client-id",
+ *   redirectTo: "https://app.example.com/auth/callback",
+ *   initialScopes: ["openid", "email", "profile"],
+ * });
+ * ```
+ */
+export function createAndcoInstanceForBrowser(options) {
+    const presenter = options.presenter ?? browserPresenter();
+    const storage = options.storage ?? (typeof window === "undefined" ? undefined : new WebStorage(window.sessionStorage));
+    // Annotated because `source` closes over `client`; the closure only runs on the first read.
+    const client = new AndcoClient({
+        ...options,
+        presenter,
+        storage,
+        source: () => consumeAuthorizationCode(client.config, client.oauth, options),
+        persistTransaction: (request) => storeAndcoTransaction(client.config.clientId, request, options.transactionStorage),
+    });
+    if (options.relayPopupCallback !== false && typeof window !== "undefined") {
+        relayAndcoPopupCallback(client.config.allowedPopupOrigins);
+    }
+    return client;
+}
+/**
+ * Exchanges an authorization code left in the URL by a redirect presentation.
+ *
+ * Skipped when this document is an Andco popup: there the code belongs to the relay, which delivers
+ * it to the opener that holds the PKCE verifier.
+ */
+async function consumeAuthorizationCode(config, oauth, options) {
+    if (options.detectSessionInUrl === false)
+        return Result.ok(null);
+    if (typeof window === "undefined")
+        return Result.ok(null);
+    if (andcoPopupPresentationId())
+        return Result.ok(null);
+    const url = new URL(window.location.href);
+    if (!url.searchParams.has("code") && !url.searchParams.has("error"))
+        return Result.ok(null);
+    const storage = options.transactionStorage ?? window.sessionStorage;
+    const stored = storage.getItem(`${TRANSACTION_KEY}.${config.clientId}`);
+    if (!stored)
+        return Result.ok(null);
+    storage.removeItem(`${TRANSACTION_KEY}.${config.clientId}`);
+    let request;
+    try {
+        const parsed = JSON.parse(stored);
+        request = { ...parsed, authorizationUrl: new URL(parsed.authorizationUrl) };
+    }
+    catch {
+        return Result.fail(ANDCO_ERROR_CODES.INVALID_CALLBACK);
+    }
+    const exchanged = await oauth.exchangeCallback({ callbackUrl: url, request });
+    for (const parameter of ["code", "state", "error", "error_description"])
+        url.searchParams.delete(parameter);
+    const replace = options.replaceUrl ?? ((next) => window.history.replaceState(window.history.state, "", next));
+    replace(url);
+    return exchanged.error ? Result.fail(exchanged.error) : Result.ok(exchanged.data);
+}
+/** Persists a transaction across a full-page redirect. Used by the redirect presentation. */
+export function storeAndcoTransaction(clientId, request, storage) {
+    const target = storage ?? window.sessionStorage;
+    target.setItem(`${TRANSACTION_KEY}.${clientId}`, JSON.stringify({ ...request, authorizationUrl: request.authorizationUrl.href }));
+}

package/dist/browser/popup.d.ts

@@ -0,0 +1,105 @@
+import { AndcoError, Result } from "../errors.js";
+/** The message a popup relays to its opener. Carries a lifecycle outcome, never financial data. */
+export type AndcoPopupMessage = {
+    protocol: "andco";
+    version: 1;
+    presentationId: string;
+    callbackUrl: string;
+};
+/** What consuming the current document as a popup callback did. */
+export type AndcoRelayOutcome = {
+    status: "not_callback";
+} | {
+    status: "not_popup";
+} | {
+    status: "relayed";
+    presentationId: string;
+} | {
+    status: "rejected";
+    error: AndcoError;
+};
+declare global {
+    interface Window {
+        /** Capability marker injected by the first-party Andco mobile Host. */
+        __ANDCO_NATIVE_HOST__?: boolean;
+        /** Capability marker for Host-presented popups that preserve the mounted document. */
+        __ANDCO_NATIVE_POPUP_HANDLER__?: boolean;
+        ReactNativeWebView?: {
+            postMessage(message: string): void;
+        };
+    }
+}
+/** Whether the document is running inside the first-party Andco Host. */
+export declare function isAndcoNativeHost(): boolean;
+/**
+ * Whether this document is a popup Andco opened.
+ *
+ * One predicate, two consumers. The relay uses it to decide the callback is its to deliver, and the
+ * session store uses it to decide the authorization code is *not* its to exchange. Without a single
+ * predicate the two would race, and an authorization code is single-use: whichever ran first would
+ * leave the other broken.
+ */
+export declare function andcoPopupPresentationId(): string | null;
+/**
+ * Hands this document's callback to the window that opened it, then closes.
+ *
+ * The popup cannot complete the exchange itself: the PKCE verifier was generated by the opener and
+ * never left it. So this is a courier, not a consumer — it carries the callback URL back and dies.
+ *
+ * Synchronous throughout. There is no network call and nothing to await, which is why running it at
+ * construction is safe even inside a render a framework may discard: closing a document is terminal,
+ * so there is no retained construction left for a discarded one to make inconsistent.
+ */
+export declare function relayAndcoPopupCallback(allowedOrigins: ReadonlySet<string>, options?: {
+    /**
+     * The URL to relay, when the application already knows this document is a callback.
+     *
+     * A host-managed flow runs the authorization on the Project's own server and lands on a page
+     * whose result parameters the Project chose. There is no authorization code to recognise, so
+     * the caller asserts what to deliver instead of the relay guessing.
+     */
+    callbackUrl?: string | URL;
+}): AndcoRelayOutcome;
+/** A popup opened during user activation, navigated once its destination is known. */
+export type AndcoPopupWindow = {
+    /**
+     * Whether the browser refused to open the window.
+     *
+     * Exposed so a caller can abandon before doing server work. A blocked popup that still triggered
+     * an authorization would leave a transaction nobody can complete.
+     */
+    readonly blocked: boolean;
+    /** Sends the popup to its destination. Safe to call once. */
+    navigate(url: URL): void;
+    /** Settles with the relayed callback, `null` on dismissal, or an error. */
+    readonly result: Promise<Result<URL | null>>;
+    close(): void;
+};
+/**
+ * Opens a popup now and navigates it later.
+ *
+ * A browser only grants `window.open` during a user activation, so a flow whose destination needs a
+ * server round trip has to open first and navigate second. That is the host-managed shape: the
+ * Project's own backend builds the authorization, and the popup is already waiting when it answers.
+ *
+ * @example
+ * ```ts
+ * const popup = openAndcoPopupWindow({ presentationId, expectedOrigin: location.origin });
+ * popup.navigate(await authorizationUrlFromMyServer());
+ * const { data } = await popup.result;
+ * ```
+ */
+export declare function openAndcoPopupWindow(options: {
+    presentationId: string;
+    expectedOrigin: string;
+    url?: URL;
+    signal?: AbortSignal;
+}): AndcoPopupWindow;
+/** Opens a popup straight to its destination and waits for the relayed callback. */
+export declare function openAndcoPopup(options: {
+    url: URL;
+    presentationId: string;
+    expectedOrigin: string;
+    signal?: AbortSignal;
+}): Promise<Result<URL | null>>;
+//# sourceMappingURL=popup.d.ts.map

package/dist/browser/popup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popup.d.ts","sourceRoot":"","sources":["../../src/browser/popup.ts"],"names":[],"mappings":"AAOA,OAAO,EAAqB,UAAU,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAMrE,mGAAmG;AACnG,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,iBAAiB,GACzB;IAAE,MAAM,EAAE,cAAc,CAAA;CAAE,GAC1B;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAE9C,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,uEAAuE;QACvE,qBAAqB,CAAC,EAAE,OAAO,CAAC;QAChC,sFAAsF;QACtF,8BAA8B,CAAC,EAAE,OAAO,CAAC;QACzC,kBAAkB,CAAC,EAAE;YAAE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;SAAE,CAAC;KAC7D;CACF;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,IAAI,OAAO,CAM3C;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAMxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,EACnC,OAAO,GAAE;IACP;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;CACvB,GACL,iBAAiB,CAkCnB;AAsBD,sFAAsF;AACtF,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC;IAC7C,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,gBAAgB,CA+DnB;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,OAAO,EAAE;IACtC,GAAG,EAAE,GAAG,CAAC;IACT,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAE9B"}

package/dist/browser/popup.js

@@ -0,0 +1,177 @@
+import { ANDCO_POPUP_NAME_PREFIX, ANDCO_PROTOCOL_VERSION, ANDCO_SDK_PROTOCOL, CALLBACK_STATE_FROM, } from "@andco/protocol";
+import { ANDCO_ERROR_CODES, AndcoError, Result } from "../errors.js";
+const PRESENTATION_ID_PATTERN = /^[A-Za-z0-9_-]{8,128}$/;
+const POPUP_TIMEOUT_MS = 10 * 60 * 1_000;
+const CLOSE_POLL_MS = 400;
+/** Whether the document is running inside the first-party Andco Host. */
+export function isAndcoNativeHost() {
+    return (typeof window !== "undefined" &&
+        window.__ANDCO_NATIVE_HOST__ === true &&
+        typeof window.ReactNativeWebView?.postMessage === "function");
+}
+/**
+ * Whether this document is a popup Andco opened.
+ *
+ * One predicate, two consumers. The relay uses it to decide the callback is its to deliver, and the
+ * session store uses it to decide the authorization code is *not* its to exchange. Without a single
+ * predicate the two would race, and an authorization code is single-use: whichever ran first would
+ * leave the other broken.
+ */
+export function andcoPopupPresentationId() {
+    if (typeof window === "undefined")
+        return null;
+    if (!window.opener || window.opener === window)
+        return null;
+    if (!window.name.startsWith(ANDCO_POPUP_NAME_PREFIX))
+        return null;
+    const presentationId = window.name.slice(ANDCO_POPUP_NAME_PREFIX.length);
+    return PRESENTATION_ID_PATTERN.test(presentationId) ? presentationId : null;
+}
+/**
+ * Hands this document's callback to the window that opened it, then closes.
+ *
+ * The popup cannot complete the exchange itself: the PKCE verifier was generated by the opener and
+ * never left it. So this is a courier, not a consumer — it carries the callback URL back and dies.
+ *
+ * Synchronous throughout. There is no network call and nothing to await, which is why running it at
+ * construction is safe even inside a render a framework may discard: closing a document is terminal,
+ * so there is no retained construction left for a discarded one to make inconsistent.
+ */
+export function relayAndcoPopupCallback(allowedOrigins, options = {}) {
+    if (typeof window === "undefined")
+        return { status: "not_callback" };
+    const url = options.callbackUrl ? new URL(options.callbackUrl, window.location.href) : new URL(window.location.href);
+    const isCallback = Boolean(options.callbackUrl) || url.searchParams.has("code") || url.searchParams.has("error");
+    if (!isCallback)
+        return { status: "not_callback" };
+    const presentationId = andcoPopupPresentationId();
+    if (!presentationId)
+        return { status: "not_popup" };
+    // Where to deliver comes from the state the request was created with, never from the opener's
+    // own `location`: reading that on a cross-origin opener throws, and a hosted popup is always
+    // opened by the Andco surface rather than by the page that will receive the result.
+    const encoded = url.searchParams.get("state");
+    const openerOrigin = (encoded ? CALLBACK_STATE_FROM(encoded)?.openerOrigin : null) ?? window.location.origin;
+    if (openerOrigin !== window.location.origin && !allowedOrigins.has(openerOrigin)) {
+        return { status: "rejected", error: new AndcoError(ANDCO_ERROR_CODES.UNTRUSTED_ORIGIN) };
+    }
+    // Who opened this window decides what it is told. The Andco surface speaks the Protocol
+    // Contract and gets a protocol result; an opener on this document's own origin is the SDK's own
+    // popup, which holds the transaction and wants the whole callback URL. Sending the SDK's shape
+    // to the hosted surface is what made a completed authorization look like a dismissal.
+    const message = openerOrigin === window.location.origin ? sdkMessage(presentationId, url) : protocolResult(presentationId, url);
+    // Strip before leaving. If closing is refused, the code must not remain visible in the address
+    // bar or in the window name.
+    for (const parameter of ["code", "state", "error", "error_description"])
+        url.searchParams.delete(parameter);
+    window.history.replaceState(window.history.state, "", url);
+    window.name = "";
+    window.opener?.postMessage(message, openerOrigin);
+    window.close();
+    return { status: "relayed", presentationId };
+}
+function sdkMessage(presentationId, url) {
+    return { protocol: "andco", version: 1, presentationId, callbackUrl: url.href };
+}
+function protocolResult(presentationId, url) {
+    const envelope = { protocol: ANDCO_SDK_PROTOCOL, version: ANDCO_PROTOCOL_VERSION, presentationId };
+    const code = url.searchParams.get("code");
+    if (code)
+        return { ...envelope, type: "oauth.authorization_code", authorizationCode: code };
+    const error = url.searchParams.get("error") ?? "invalid_request";
+    // `access_denied` is the only OAuth error that carries a decision, and it is the one the
+    // Authorization Server returns when the user declines.
+    if (error === "access_denied")
+        return { ...envelope, type: "oauth.dismiss" };
+    const description = url.searchParams.get("error_description");
+    return {
+        ...envelope,
+        type: "oauth.error",
+        error: { code: error.slice(0, 256), description: description ? description.slice(0, 2_048) : undefined },
+    };
+}
+/**
+ * Opens a popup now and navigates it later.
+ *
+ * A browser only grants `window.open` during a user activation, so a flow whose destination needs a
+ * server round trip has to open first and navigate second. That is the host-managed shape: the
+ * Project's own backend builds the authorization, and the popup is already waiting when it answers.
+ *
+ * @example
+ * ```ts
+ * const popup = openAndcoPopupWindow({ presentationId, expectedOrigin: location.origin });
+ * popup.navigate(await authorizationUrlFromMyServer());
+ * const { data } = await popup.result;
+ * ```
+ */
+export function openAndcoPopupWindow(options) {
+    const popup = window.open(options.url?.href ?? "about:blank", `${ANDCO_POPUP_NAME_PREFIX}${options.presentationId}`, windowFeatures({ width: 620, height: 720 }));
+    if (!popup) {
+        return {
+            blocked: true,
+            navigate: () => { },
+            result: Promise.resolve(Result.fail(ANDCO_ERROR_CODES.POPUP_BLOCKED)),
+            close: () => { },
+        };
+    }
+    const result = new Promise((resolve) => {
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            window.removeEventListener("message", receive);
+            window.clearInterval(closeMonitor);
+            window.clearTimeout(timeout);
+            resolve(result);
+        };
+        const receive = (event) => {
+            // Three checks: exact origin, the window this presentation opened, and the correlation id.
+            if (event.origin !== options.expectedOrigin || event.source !== popup)
+                return;
+            const message = event.data;
+            if (!message || message.protocol !== "andco" || message.presentationId !== options.presentationId)
+                return;
+            if (typeof message.callbackUrl !== "string")
+                return;
+            // The relay closes itself, but a browser may refuse; closing from the opener guarantees the
+            // window does not outlive the flow it belonged to.
+            popup.close();
+            try {
+                settle(Result.ok(new URL(message.callbackUrl)));
+            }
+            catch {
+                settle(Result.fail(ANDCO_ERROR_CODES.INVALID_CALLBACK));
+            }
+        };
+        window.addEventListener("message", receive);
+        // A closed window with no message is a dismissal, never a failure.
+        const closeMonitor = window.setInterval(() => {
+            if (popup.closed)
+                settle(Result.ok(null));
+        }, CLOSE_POLL_MS);
+        const timeout = window.setTimeout(() => {
+            popup.close();
+            settle(Result.fail(ANDCO_ERROR_CODES.POPUP_TIMEOUT));
+        }, POPUP_TIMEOUT_MS);
+        options.signal?.addEventListener("abort", () => {
+            popup.close();
+            settle(Result.ok(null));
+        });
+    });
+    return {
+        blocked: false,
+        navigate: (url) => popup.location.assign(url.href),
+        result,
+        close: () => popup.close(),
+    };
+}
+/** Opens a popup straight to its destination and waits for the relayed callback. */
+export function openAndcoPopup(options) {
+    return openAndcoPopupWindow(options).result;
+}
+function windowFeatures(size) {
+    const left = Math.max(0, Math.round((window.screen.width - size.width) / 2));
+    const top = Math.max(0, Math.round((window.screen.height - size.height) / 2));
+    return `popup=1,width=${size.width},height=${size.height},left=${left},top=${top}`;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,47 @@
+import { AndcoClient, type AndcoClientOptions } from "../client.js";
+import { Result } from "../errors.js";
+import type { AndcoPresenter, AndcoPresentOptions } from "../presenter.js";
+export type AndcoCliPresenterOptions = {
+    /** Opens the authorization URL. Defaults to printing it, so nothing is assumed about the host. */
+    open?: (url: URL) => void | Promise<void>;
+    /** How long to wait for the user to finish. Defaults to ten minutes. */
+    timeoutMs?: number;
+    /** Receives the URL when no browser can be opened, so the user can paste it. */
+    print?: (message: string) => void;
+};
+/**
+ * Presents an authorization from a terminal, using a one-shot loopback receiver.
+ *
+ * Every command-line integrator needs this exact thing, and until now every one wrote it: bind a
+ * loopback port, refuse anything that is not the registered path, check the state, answer once, and
+ * shut down. The Andco CLI's own version is ninety lines. Getting any of it wrong — accepting a
+ * callback on the wrong path, skipping the state check, leaving the port open — is a security bug
+ * in someone's developer tooling, which is exactly the kind of thing an SDK should own.
+ *
+ * @example
+ * ```ts
+ * const andco = createAndcoInstanceForCLI({
+ *   clientId,
+ *   storage: keychain,
+ *   redirectTo: "http://127.0.0.1:0/callback",
+ * });
+ * const { data: session } = await andco.auth.signIn();
+ * ```
+ */
+export declare class AndcoCliPresenter implements AndcoPresenter {
+    private readonly options;
+    constructor(options?: AndcoCliPresenterOptions);
+    present(presentation: AndcoPresentOptions): Promise<Result<URL | null>>;
+}
+export type AndcoCliOptions = Omit<AndcoClientOptions, "presenter"> & {
+    presenter?: AndcoPresenter;
+};
+/**
+ * Creates an Andco Instance for a terminal.
+ *
+ * Storage is required and may be asynchronous, which is the whole point: a keychain cannot answer
+ * synchronously, and the previous contract left no legal way to supply one. Restoring a saved
+ * credential is `andco.session.set(...)`, not a write into a private storage key.
+ */
+export declare function createAndcoInstanceForCLI(options: AndcoCliOptions): AndcoClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEpE,OAAO,EAAqB,MAAM,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG3E,MAAM,MAAM,wBAAwB,GAAG;IACrC,kGAAkG;IAClG,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,GAAE,wBAA6B;IAE7D,OAAO,CAAC,YAAY,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;CAiC9E;AAED,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,GAAG;IACpE,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW,CAE/E"}

package/dist/cli/index.js

@@ -0,0 +1,72 @@
+import { AndcoClient } from "../client.js";
+import { isLoopback } from "../config.js";
+import { ANDCO_ERROR_CODES, Result } from "../errors.js";
+import { LoopbackServer } from "./server.js";
+/**
+ * Presents an authorization from a terminal, using a one-shot loopback receiver.
+ *
+ * Every command-line integrator needs this exact thing, and until now every one wrote it: bind a
+ * loopback port, refuse anything that is not the registered path, check the state, answer once, and
+ * shut down. The Andco CLI's own version is ninety lines. Getting any of it wrong — accepting a
+ * callback on the wrong path, skipping the state check, leaving the port open — is a security bug
+ * in someone's developer tooling, which is exactly the kind of thing an SDK should own.
+ *
+ * @example
+ * ```ts
+ * const andco = createAndcoInstanceForCLI({
+ *   clientId,
+ *   storage: keychain,
+ *   redirectTo: "http://127.0.0.1:0/callback",
+ * });
+ * const { data: session } = await andco.auth.signIn();
+ * ```
+ */
+export class AndcoCliPresenter {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async present(presentation) {
+        const configured = presentation.returnTo;
+        if (configured.protocol !== "http:" || !isLoopback(configured)) {
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, {
+                message: "a terminal callback must be http on a loopback host",
+            });
+        }
+        let receiver;
+        try {
+            receiver = await LoopbackServer.start(configured);
+        }
+        catch (cause) {
+            return Result.fail(ANDCO_ERROR_CODES.INVALID_CONFIGURATION, {
+                message: "could not bind the loopback port",
+                cause,
+            });
+        }
+        try {
+            // The bound port may differ from the configured one when it asked for any free port, and the
+            // authorization request must carry the exact URI the server will redirect to.
+            const url = new URL(presentation.url.href);
+            url.searchParams.set("redirect_uri", receiver.redirectUri.href);
+            if (this.options.open)
+                await this.options.open(url);
+            else
+                this.options.print?.(`Abre esta URL para continuar:\n\n${url.href}\n`);
+            const callback = await receiver.wait(this.options.timeoutMs ?? 10 * 60 * 1_000);
+            return callback ? Result.ok(callback) : Result.fail(ANDCO_ERROR_CODES.POPUP_TIMEOUT);
+        }
+        finally {
+            await receiver.close();
+        }
+    }
+}
+/**
+ * Creates an Andco Instance for a terminal.
+ *
+ * Storage is required and may be asynchronous, which is the whole point: a keychain cannot answer
+ * synchronously, and the previous contract left no legal way to supply one. Restoring a saved
+ * credential is `andco.session.set(...)`, not a write into a private storage key.
+ */
+export function createAndcoInstanceForCLI(options) {
+    return new AndcoClient({ ...options, presenter: options.presenter ?? new AndcoCliPresenter() });
+}

package/dist/cli/server.d.ts

@@ -0,0 +1,11 @@
+export declare class LoopbackServer {
+    #private;
+    private constructor();
+    static start(configured: URL): Promise<LoopbackServer>;
+    get redirectUri(): URL;
+    wait(timeoutMs: number): Promise<URL | null>;
+    close(): Promise<void>;
+    private listen;
+    private static hostFor;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/cli/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/cli/server.ts"],"names":[],"mappings":"AAEA,qBAAa,cAAc;;IAKzB,OAAO;WAKM,KAAK,CAAC,UAAU,EAAE,GAAG,GAAG,OAAO,CAAC,cAAc,CAAC;IAc5D,IAAI,WAAW,IAAI,GAAG,CAErB;IAED,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAS5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiDtB,OAAO,CAAC,MAAM;IAcd,OAAO,CAAC,MAAM,CAAC,OAAO;CAGvB"}

package/dist/cli/server.js

@@ -0,0 +1,91 @@
+import { createServer } from "node:http";
+export class LoopbackServer {
+    #server;
+    #resolveCallback;
+    #redirectUri;
+    constructor(configured) {
+        this.#redirectUri = configured;
+        this.#server = this.#buildServer();
+    }
+    static async start(configured) {
+        const receiver = new LoopbackServer(configured);
+        await receiver.listen();
+        const address = receiver.#server.address();
+        if (!address || typeof address === "string") {
+            await receiver.close();
+            throw new Error("the loopback receiver reported no address");
+        }
+        receiver.#redirectUri = new URL(configured.href);
+        receiver.#redirectUri.port = String(address.port);
+        return receiver;
+    }
+    get redirectUri() {
+        return this.#redirectUri;
+    }
+    wait(timeoutMs) {
+        return new Promise((resolve) => {
+            this.#resolveCallback = resolve;
+            // Node returns a Timeout with `unref`; the DOM lib types this as a number.
+            const timer = setTimeout(() => resolve(null), timeoutMs);
+            timer.unref?.();
+        });
+    }
+    close() {
+        return new Promise((resolve) => {
+            this.#server.closeAllConnections?.();
+            this.#server.close(() => resolve());
+        });
+    }
+    #buildServer() {
+        const server = createServer((request, response) => {
+            // A local browser must not be able to script this origin or keep it around.
+            response.setHeader("Cache-Control", "no-store");
+            response.setHeader("Connection", "close");
+            response.setHeader("Content-Security-Policy", "default-src 'none'; base-uri 'none'; frame-ancestors 'none'");
+            response.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+            response.setHeader("Referrer-Policy", "no-referrer");
+            response.setHeader("X-Content-Type-Options", "nosniff");
+            if (request.method !== "GET" || !request.url) {
+                response.writeHead(405).end("Method Not Allowed");
+                return;
+            }
+            const url = new URL(request.url, this.#redirectUri.origin);
+            if (url.pathname !== this.#redirectUri.pathname) {
+                response.writeHead(404).end("Not Found");
+                return;
+            }
+            if (!url.searchParams.has("code") && !url.searchParams.has("error")) {
+                response.writeHead(400).end("Missing OAuth response");
+                return;
+            }
+            response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(`
+        <!doctype html>
+          <html lang="es">
+          <head><meta charset="utf-8"><title>Andco</title></head>
+          <body>
+            <main>
+              <h1>Autorización recibida</h1>
+              <p>Puedes cerrar esta ventana y volver a la terminal.</p>
+            </main>
+          </body>
+        </html>
+      `);
+            this.#resolveCallback?.(url);
+        });
+        server.requestTimeout = 10_000;
+        server.headersTimeout = 10_000;
+        return server;
+    }
+    listen() {
+        return new Promise((resolve, reject) => {
+            this.#server.once("error", reject);
+            this.#server.listen(this.#redirectUri.port ? Number(this.#redirectUri.port) : 0, LoopbackServer.hostFor(this.#redirectUri.hostname), () => {
+                this.#server.removeListener("error", reject);
+                resolve();
+            });
+        });
+    }
+    static hostFor(hostname) {
+        return hostname === "localhost" ? "127.0.0.1" : hostname.replace(/^\[|\]$/g, "");
+    }
+}