@ekanos/cli 0.1.0

package/dist/auth/fusion-api.js

@@ -0,0 +1,310 @@
+import { authRequiredError, networkError, preconditionError } from '../errors.js';
+/**
+ * The CLI's client for the four Fusion auth routes.
+ *
+ * ---------------------------------------------------------------------------
+ * WIRE CONTRACT — the seam between this package and the Fusion web app.
+ *
+ * The server side lives in `apps/web/app/api/auth/cli-<verb>/route.ts` and ships on
+ * a DIFFERENT BRANCH from this file. This block is the single place the shapes
+ * are written down on the client side; if you change one side, change the
+ * other and update this block. Nothing here imports from `apps/web` — the two
+ * halves are coupled only by HTTP, and the tests stub `fetch`, never the route.
+ *
+ *   GET /api/auth/cli-config                                   [no auth]
+ *     → 200 { auth0_domain, client_id, scope,
+ *             device_authorization_endpoint, token_endpoint }   all strings
+ *     → 503 { error, code: "CLI_NOT_CONFIGURED" }   deployment not provisioned
+ *
+ *   POST /api/auth/cli-session                                 [no auth]
+ *     ← { auth0_access_token: string }
+ *     → 200 { access_token, expires_at, user: { id, email } }
+ *     → 400 { error, code: "INVALID_REQUEST" }      malformed / wrong shape
+ *     → 401 { error, code: "SESSION_EXPIRED" }      Auth0 said no, OR no
+ *                                                   Fusion account for it
+ *     → 503 { error, code: "CLI_NOT_CONFIGURED" }   deployment not provisioned
+ *     → 500 { error, code: "INTERNAL_ERROR" }
+ *
+ *   POST /api/auth/cli-refresh                                 [no auth]
+ *     ← { auth0_refresh_token: string }
+ *     → 200 { access_token, expires_at, user: { id, email },
+ *             auth0_refresh_token }   ← ROTATED; the presented one is dead
+ *     → 400 { error, code: "INVALID_REQUEST" }
+ *     → 401 { error, code: "SESSION_EXPIRED" }      expired or revoked
+ *     → 404 { error, code: "ACCOUNT_NOT_FOUND",
+ *             auth0_refresh_token }                 no Fusion account
+ *     → 502 { error, code: "TOKEN_EXCHANGE_FAILED" } Auth0 returned no
+ *                                                   rotated token
+ *     → 503 { error, code: "CLI_NOT_CONFIGURED" }   deployment not provisioned
+ *     → 503 { error, code: "REFRESH_INCOMPLETE",
+ *             auth0_refresh_token }                 rotated, but /userinfo
+ *                                                   did not answer; RETRYABLE
+ *     → 500 { error, code: "INTERNAL_ERROR",
+ *             auth0_refresh_token? }                present iff rotation
+ *                                                   completed before the throw
+ *
+ *   !! cli-refresh MAY RETURN `auth0_refresh_token` ON ERROR RESPONSES, and a
+ *      client MUST persist it before surfacing the error. Once the server's
+ *      exchange with Auth0 succeeds the presented token is dead and the value
+ *      in that body is the ONLY copy in existence; discarding it on a failure
+ *      path destroys the session permanently. Note 503 has TWO codes here —
+ *      branch on `code`, not on the status alone.
+ *
+ *   All three routes above read the Fusion CLI Auth0 application config, so all
+ *   three can answer 503 CLI_NOT_CONFIGURED. cli-whoami cannot — it reads no
+ *   Auth0 config, only the caller's bearer token.
+ *
+ *   GET /api/auth/cli-whoami        [Authorization: Bearer <access_token>]
+ *     → 200 { user: { id, email, name } }
+ *     → 401 { error, code: "AUTH_REQUIRED" }        token absent or invalid
+ *     → 403 { error, code: "MFA_REQUIRED" }
+ *     → 404 { error, code: "ACCOUNT_NOT_FOUND" }
+ *     → 3xx                                         treated as 401, see below
+ *
+ * `access_token` is a Fusion HS256 JWT. Every authenticated Fusion route
+ * accepts it as `Authorization: Bearer` — see `resolveRequestSupabaseJwt` in
+ * `@kit/supabase`, which both `requireUser` and the RLS server client consume.
+ * ---------------------------------------------------------------------------
+ *
+ * Two rules hold everywhere in this file:
+ *
+ *  - `redirect: 'manual'`. Fusion answers an unauthenticated page request with
+ *    a 307 to `/auth/sign-in`; Node's fetch follows redirects by default, so
+ *    without this a stale token would come back as a 200 full of HTML and be
+ *    read as success. A 3xx here is treated as "not authenticated", full stop.
+ *
+ *  - No token is ever interpolated into an error message. The server's error
+ *    bodies are `{ error, code }` documents that do not echo credentials, and
+ *    the request bodies that DO carry credentials are never included in a
+ *    thrown message.
+ */
+const REQUEST_TIMEOUT_MS = 15000;
+/** Fetch the device-flow parameters for a host. */
+export async function fetchCliAuthConfig(host) {
+    const response = await request(`${host}/api/auth/cli-config`, {
+        method: 'GET',
+        headers: { accept: 'application/json' },
+    });
+    throwIfNotConfigured(response, host);
+    if (!response.ok) {
+        throw unexpectedStatus(host, '/api/auth/cli-config', response.status);
+    }
+    const body = await readJson(response, `${host}/api/auth/cli-config`);
+    const config = {
+        auth0Domain: str(body.auth0_domain),
+        clientId: str(body.client_id),
+        scope: str(body.scope),
+        deviceAuthorizationEndpoint: str(body.device_authorization_endpoint),
+        tokenEndpoint: str(body.token_endpoint),
+    };
+    if (Object.values(config).some((value) => value === null)) {
+        throw preconditionError(`${host} returned an incomplete CLI login configuration.`, `Confirm the deployment is running a Fusion build that includes the ` +
+            `/api/auth/cli-config route.`);
+    }
+    // The endpoints come from the server, so they are attacker-controlled if the
+    // host is. Pin them to the Auth0 domain the same response declares, so a
+    // compromised or misconfigured Fusion cannot redirect the device flow — and
+    // the resulting credentials — to an arbitrary origin.
+    assertOnDomain(config.deviceAuthorizationEndpoint, config.auth0Domain);
+    assertOnDomain(config.tokenEndpoint, config.auth0Domain);
+    return config;
+}
+/** Exchange a verified Auth0 access token for a Fusion JWT. */
+export async function createFusionSession(host, auth0AccessToken) {
+    const response = await request(`${host}/api/auth/cli-session`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json' },
+        body: JSON.stringify({ auth0_access_token: auth0AccessToken }),
+    });
+    throwIfNotConfigured(response, host);
+    if (response.status === 401) {
+        throw authRequiredError(`${host} rejected the Auth0 identity.`, `Run "ekanos login" again. If it keeps failing, confirm your account ` +
+            `exists on ${host} — the browser login can succeed for an identity ` +
+            `that has no Fusion account.`);
+    }
+    if (!response.ok) {
+        throw unexpectedStatus(host, '/api/auth/cli-session', response.status);
+    }
+    return toSession(await readJson(response, `${host}/api/auth/cli-session`), host);
+}
+/** Re-mint a Fusion JWT from the stored Auth0 refresh token. */
+export async function refreshFusionSession(host, auth0RefreshToken, options = {}) {
+    var _a;
+    const response = await request(`${host}/api/auth/cli-refresh`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json' },
+        body: JSON.stringify({ auth0_refresh_token: auth0RefreshToken }),
+    });
+    // Read the body FIRST, whatever the status: the rotated token can arrive on
+    // a 503, a 404 or a 500 just as readily as on a 200, and it must be captured
+    // before any branch below throws.
+    const body = await readOptionalJson(response);
+    const rotated = str(body.auth0_refresh_token);
+    if (rotated) {
+        (_a = options.onRotatedToken) === null || _a === void 0 ? void 0 : _a.call(options, rotated);
+    }
+    throwIfNotConfigured(response, host, body);
+    if (response.status === 401) {
+        throw authRequiredError(`The stored session for ${host} is no longer valid.`, `Run "ekanos login" to sign in again. This is expected after the ` +
+            `refresh token expires, after it is revoked in Auth0, or if two ` +
+            `machines used the same credentials file.`);
+    }
+    if (response.status === 503 && body.code === 'REFRESH_INCOMPLETE') {
+        // NOT an auth failure. The credential was renewed — and, thanks to the
+        // callback above, already saved. Auth0's /userinfo is simply not answering.
+        throw networkError(`${host} renewed the session but could not verify the identity with Auth0.`, `Retry in a moment — your credentials are still valid and have been ` +
+            `updated. You do NOT need to run "ekanos login" again.`);
+    }
+    if (response.status === 404) {
+        throw authRequiredError(`${host} has no Fusion account for the signed-in identity.`, `Sign in to ${host} in a browser once to have the account created, ` +
+            `then retry.`);
+    }
+    if (!response.ok) {
+        throw unexpectedStatus(host, '/api/auth/cli-refresh', response.status);
+    }
+    if (!rotated) {
+        throw networkError(`${host} refreshed the session without returning a rotated refresh token.`, `Run "ekanos login" to start a fresh session, and report this — the ` +
+            `deployment's Auth0 CLI application may not have rotation enabled.`);
+    }
+    return Object.assign(Object.assign({}, toSession(body, host)), { auth0RefreshToken: rotated });
+}
+/**
+ * Prove the Fusion JWT authenticates. Returns null on 401 so the caller can
+ * decide whether to refresh and retry — an expired access token is an ordinary
+ * event, not an error.
+ */
+export async function fetchIdentity(host, accessToken) {
+    var _a;
+    const response = await request(`${host}/api/auth/cli-whoami`, {
+        method: 'GET',
+        headers: {
+            accept: 'application/json',
+            authorization: `Bearer ${accessToken}`,
+        },
+    });
+    // 401, or the 307 that an auth-gated Fusion route answers with. Both mean
+    // "this token did not authenticate".
+    if (response.status === 401 || isRedirect(response.status)) {
+        return null;
+    }
+    if (response.status === 403) {
+        throw authRequiredError(`${host} requires multi-factor authentication for this account.`, `Complete MFA in the browser, then run "ekanos login" again.`);
+    }
+    if (response.status === 404) {
+        throw authRequiredError(`${host} has no account for the signed-in identity.`, `Sign in to ${host} in a browser once to have the account created, ` +
+            `then run "ekanos login" again.`);
+    }
+    if (!response.ok) {
+        throw unexpectedStatus(host, '/api/auth/cli-whoami', response.status);
+    }
+    const body = await readJson(response, `${host}/api/auth/cli-whoami`);
+    const user = ((_a = body.user) !== null && _a !== void 0 ? _a : {});
+    const id = str(user.id);
+    if (!id) {
+        throw networkError(`${host} returned an identity without a user id.`, `Confirm the deployment is running a Fusion build that includes the ` +
+            `/api/auth/cli-whoami route.`);
+    }
+    return { id, email: str(user.email), name: str(user.name) };
+}
+function toSession(body, host) {
+    var _a;
+    const user = ((_a = body.user) !== null && _a !== void 0 ? _a : {});
+    const accessToken = str(body.access_token);
+    const expiresAt = str(body.expires_at);
+    const userId = str(user.id);
+    if (!accessToken || !expiresAt || !userId) {
+        throw networkError(`${host} returned an incomplete session.`, `Confirm the deployment is running a Fusion build that includes the ` +
+            `CLI auth routes, then retry.`);
+    }
+    return { accessToken, expiresAt, userId, email: str(user.email) };
+}
+export async function request(url, init) {
+    try {
+        return await fetch(url, Object.assign(Object.assign({}, init), { redirect: 'manual', signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) }));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw networkError(`Could not reach ${new URL(url).origin}: ${reason}`, `Check the host is correct and reachable from this machine ` +
+            `(proxy, VPN, DNS), then retry.`);
+    }
+}
+/**
+ * Best-effort body read for a response whose status may be an error. Returns
+ * an empty object rather than throwing, because the caller needs to inspect
+ * the body BEFORE deciding what the status means — and a 500 from a proxy may
+ * carry no JSON at all.
+ */
+async function readOptionalJson(response) {
+    try {
+        const parsed = await response.json();
+        return typeof parsed === 'object' && parsed !== null
+            ? parsed
+            : {};
+    }
+    catch (_a) {
+        return {};
+    }
+}
+async function readJson(response, what) {
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch (_a) {
+        throw networkError(`${what} did not return JSON.`, `Confirm the host is a Fusion deployment and not a proxy or captive ` +
+            `portal sitting in front of one.`);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw networkError(`${what} returned an unexpected payload.`, `Confirm the host is a Fusion deployment, then retry.`);
+    }
+    return parsed;
+}
+/**
+ * 503 means the deployment is not provisioned for CLI login — an operator
+ * action that has not happened, not a fault in the request.
+ *
+ * Every route that reads the Fusion CLI Auth0 config can answer this, so every
+ * caller has to check for it. Falling through to `unexpectedStatus` would tell
+ * a partner "confirm the host is a Fusion deployment" when the host is a
+ * perfectly good Fusion deployment that is simply missing one env var — and
+ * would exit 8 (network, retryable) instead of 9 (precondition, not).
+ */
+function throwIfNotConfigured(response, host, body) {
+    if (response.status !== 503)
+        return;
+    // 503 carries two meanings on these routes. Only CLI_NOT_CONFIGURED is a
+    // precondition; REFRESH_INCOMPLETE is transient and handled by its caller.
+    if (body && body.code !== 'CLI_NOT_CONFIGURED')
+        return;
+    throw preconditionError(`${host} does not have CLI login configured.`, `Ask the Fusion operator to provision the "Fusion CLI" Auth0 ` +
+        `application and set AUTH0_CLI_CLIENT_ID on that deployment.`);
+}
+function unexpectedStatus(host, route, status) {
+    return networkError(`${host}${route} responded ${status}.`, status >= 500
+        ? `The Fusion deployment returned a server error. Retry shortly; if it ` +
+            `persists, report it with the status code.`
+        : `Confirm the host is a Fusion deployment running a build that ` +
+            `includes ${route}.`);
+}
+function assertOnDomain(endpoint, domain) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch (_a) {
+        throw preconditionError(`The login configuration contains a malformed endpoint.`, `Report this to the operator of the Fusion deployment.`);
+    }
+    if (url.protocol !== 'https:' ||
+        url.host.toLowerCase() !== domain.toLowerCase()) {
+        throw preconditionError(`The login configuration points at an endpoint outside its own Auth0 ` +
+            `domain (${url.host}).`, `Do not continue. Report this to the operator of the Fusion ` +
+            `deployment — it may be misconfigured or compromised.`);
+    }
+}
+function isRedirect(status) {
+    return status >= 300 && status < 400;
+}
+function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+//# sourceMappingURL=fusion-api.js.map

package/dist/auth/fusion-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion-api.js","sourceRoot":"","sources":["../../src/auth/fusion-api.ts"],"names":[],"mappings":"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","sourcesContent":["import { authRequiredError, networkError, preconditionError } from '../errors';\n\n/**\n * The CLI's client for the four Fusion auth routes.\n *\n * ---------------------------------------------------------------------------\n * WIRE CONTRACT — the seam between this package and the Fusion web app.\n *\n * The server side lives in `apps/web/app/api/auth/cli-<verb>/route.ts` and ships on\n * a DIFFERENT BRANCH from this file. This block is the single place the shapes\n * are written down on the client side; if you change one side, change the\n * other and update this block. Nothing here imports from `apps/web` — the two\n * halves are coupled only by HTTP, and the tests stub `fetch`, never the route.\n *\n *   GET /api/auth/cli-config                                   [no auth]\n *     → 200 { auth0_domain, client_id, scope,\n *             device_authorization_endpoint, token_endpoint }   all strings\n *     → 503 { error, code: \"CLI_NOT_CONFIGURED\" }   deployment not provisioned\n *\n *   POST /api/auth/cli-session                                 [no auth]\n *     ← { auth0_access_token: string }\n *     → 200 { access_token, expires_at, user: { id, email } }\n *     → 400 { error, code: \"INVALID_REQUEST\" }      malformed / wrong shape\n *     → 401 { error, code: \"SESSION_EXPIRED\" }      Auth0 said no, OR no\n *                                                   Fusion account for it\n *     → 503 { error, code: \"CLI_NOT_CONFIGURED\" }   deployment not provisioned\n *     → 500 { error, code: \"INTERNAL_ERROR\" }\n *\n *   POST /api/auth/cli-refresh                                 [no auth]\n *     ← { auth0_refresh_token: string }\n *     → 200 { access_token, expires_at, user: { id, email },\n *             auth0_refresh_token }   ← ROTATED; the presented one is dead\n *     → 400 { error, code: \"INVALID_REQUEST\" }\n *     → 401 { error, code: \"SESSION_EXPIRED\" }      expired or revoked\n *     → 404 { error, code: \"ACCOUNT_NOT_FOUND\",\n *             auth0_refresh_token }                 no Fusion account\n *     → 502 { error, code: \"TOKEN_EXCHANGE_FAILED\" } Auth0 returned no\n *                                                   rotated token\n *     → 503 { error, code: \"CLI_NOT_CONFIGURED\" }   deployment not provisioned\n *     → 503 { error, code: \"REFRESH_INCOMPLETE\",\n *             auth0_refresh_token }                 rotated, but /userinfo\n *                                                   did not answer; RETRYABLE\n *     → 500 { error, code: \"INTERNAL_ERROR\",\n *             auth0_refresh_token? }                present iff rotation\n *                                                   completed before the throw\n *\n *   !! cli-refresh MAY RETURN `auth0_refresh_token` ON ERROR RESPONSES, and a\n *      client MUST persist it before surfacing the error. Once the server's\n *      exchange with Auth0 succeeds the presented token is dead and the value\n *      in that body is the ONLY copy in existence; discarding it on a failure\n *      path destroys the session permanently. Note 503 has TWO codes here —\n *      branch on `code`, not on the status alone.\n *\n *   All three routes above read the Fusion CLI Auth0 application config, so all\n *   three can answer 503 CLI_NOT_CONFIGURED. cli-whoami cannot — it reads no\n *   Auth0 config, only the caller's bearer token.\n *\n *   GET /api/auth/cli-whoami        [Authorization: Bearer <access_token>]\n *     → 200 { user: { id, email, name } }\n *     → 401 { error, code: \"AUTH_REQUIRED\" }        token absent or invalid\n *     → 403 { error, code: \"MFA_REQUIRED\" }\n *     → 404 { error, code: \"ACCOUNT_NOT_FOUND\" }\n *     → 3xx                                         treated as 401, see below\n *\n * `access_token` is a Fusion HS256 JWT. Every authenticated Fusion route\n * accepts it as `Authorization: Bearer` — see `resolveRequestSupabaseJwt` in\n * `@kit/supabase`, which both `requireUser` and the RLS server client consume.\n * ---------------------------------------------------------------------------\n *\n * Two rules hold everywhere in this file:\n *\n *  - `redirect: 'manual'`. Fusion answers an unauthenticated page request with\n *    a 307 to `/auth/sign-in`; Node's fetch follows redirects by default, so\n *    without this a stale token would come back as a 200 full of HTML and be\n *    read as success. A 3xx here is treated as \"not authenticated\", full stop.\n *\n *  - No token is ever interpolated into an error message. The server's error\n *    bodies are `{ error, code }` documents that do not echo credentials, and\n *    the request bodies that DO carry credentials are never included in a\n *    thrown message.\n */\n\nconst REQUEST_TIMEOUT_MS = 15_000;\n\nexport interface CliAuthConfig {\n  auth0Domain: string;\n  clientId: string;\n  scope: string;\n  deviceAuthorizationEndpoint: string;\n  tokenEndpoint: string;\n}\n\nexport interface FusionSession {\n  accessToken: string;\n  expiresAt: string;\n  userId: string;\n  email: string | null;\n}\n\nexport interface FusionIdentity {\n  id: string;\n  email: string | null;\n  name: string | null;\n}\n\n/** Fetch the device-flow parameters for a host. */\nexport async function fetchCliAuthConfig(host: string): Promise<CliAuthConfig> {\n  const response = await request(`${host}/api/auth/cli-config`, {\n    method: 'GET',\n    headers: { accept: 'application/json' },\n  });\n\n  throwIfNotConfigured(response, host);\n\n  if (!response.ok) {\n    throw unexpectedStatus(host, '/api/auth/cli-config', response.status);\n  }\n\n  const body = await readJson(response, `${host}/api/auth/cli-config`);\n\n  const config = {\n    auth0Domain: str(body.auth0_domain),\n    clientId: str(body.client_id),\n    scope: str(body.scope),\n    deviceAuthorizationEndpoint: str(body.device_authorization_endpoint),\n    tokenEndpoint: str(body.token_endpoint),\n  };\n\n  if (Object.values(config).some((value) => value === null)) {\n    throw preconditionError(\n      `${host} returned an incomplete CLI login configuration.`,\n      `Confirm the deployment is running a Fusion build that includes the ` +\n        `/api/auth/cli-config route.`,\n    );\n  }\n\n  // The endpoints come from the server, so they are attacker-controlled if the\n  // host is. Pin them to the Auth0 domain the same response declares, so a\n  // compromised or misconfigured Fusion cannot redirect the device flow — and\n  // the resulting credentials — to an arbitrary origin.\n  assertOnDomain(config.deviceAuthorizationEndpoint!, config.auth0Domain!);\n  assertOnDomain(config.tokenEndpoint!, config.auth0Domain!);\n\n  return config as CliAuthConfig;\n}\n\n/** Exchange a verified Auth0 access token for a Fusion JWT. */\nexport async function createFusionSession(\n  host: string,\n  auth0AccessToken: string,\n): Promise<FusionSession> {\n  const response = await request(`${host}/api/auth/cli-session`, {\n    method: 'POST',\n    headers: { 'content-type': 'application/json', accept: 'application/json' },\n    body: JSON.stringify({ auth0_access_token: auth0AccessToken }),\n  });\n\n  throwIfNotConfigured(response, host);\n\n  if (response.status === 401) {\n    throw authRequiredError(\n      `${host} rejected the Auth0 identity.`,\n      `Run \"ekanos login\" again. If it keeps failing, confirm your account ` +\n        `exists on ${host} — the browser login can succeed for an identity ` +\n        `that has no Fusion account.`,\n    );\n  }\n\n  if (!response.ok) {\n    throw unexpectedStatus(host, '/api/auth/cli-session', response.status);\n  }\n\n  return toSession(\n    await readJson(response, `${host}/api/auth/cli-session`),\n    host,\n  );\n}\n\nexport interface RefreshedSession extends FusionSession {\n  /** The ROTATED refresh token. The presented one is already invalid. */\n  auth0RefreshToken: string;\n}\n\nexport interface RefreshOptions {\n  /**\n   * Called the INSTANT a rotated refresh token is seen in the response — on\n   * success and on failure alike, before anything is thrown.\n   *\n   * Persist-on-learn, not persist-on-success. Once the server's exchange with\n   * Auth0 succeeds the presented token is dead and the replacement in that\n   * body is the only copy in existence, so a client that only saves it on the\n   * happy path destroys the partner's credential the first time /userinfo\n   * blips. The callback runs before any throw so no error path can skip it.\n   */\n  onRotatedToken?: (rotated: string) => void;\n}\n\n/** Re-mint a Fusion JWT from the stored Auth0 refresh token. */\nexport async function refreshFusionSession(\n  host: string,\n  auth0RefreshToken: string,\n  options: RefreshOptions = {},\n): Promise<RefreshedSession> {\n  const response = await request(`${host}/api/auth/cli-refresh`, {\n    method: 'POST',\n    headers: { 'content-type': 'application/json', accept: 'application/json' },\n    body: JSON.stringify({ auth0_refresh_token: auth0RefreshToken }),\n  });\n\n  // Read the body FIRST, whatever the status: the rotated token can arrive on\n  // a 503, a 404 or a 500 just as readily as on a 200, and it must be captured\n  // before any branch below throws.\n  const body = await readOptionalJson(response);\n  const rotated = str(body.auth0_refresh_token);\n\n  if (rotated) {\n    options.onRotatedToken?.(rotated);\n  }\n\n  throwIfNotConfigured(response, host, body);\n\n  if (response.status === 401) {\n    throw authRequiredError(\n      `The stored session for ${host} is no longer valid.`,\n      `Run \"ekanos login\" to sign in again. This is expected after the ` +\n        `refresh token expires, after it is revoked in Auth0, or if two ` +\n        `machines used the same credentials file.`,\n    );\n  }\n\n  if (response.status === 503 && body.code === 'REFRESH_INCOMPLETE') {\n    // NOT an auth failure. The credential was renewed — and, thanks to the\n    // callback above, already saved. Auth0's /userinfo is simply not answering.\n    throw networkError(\n      `${host} renewed the session but could not verify the identity with Auth0.`,\n      `Retry in a moment — your credentials are still valid and have been ` +\n        `updated. You do NOT need to run \"ekanos login\" again.`,\n    );\n  }\n\n  if (response.status === 404) {\n    throw authRequiredError(\n      `${host} has no Fusion account for the signed-in identity.`,\n      `Sign in to ${host} in a browser once to have the account created, ` +\n        `then retry.`,\n    );\n  }\n\n  if (!response.ok) {\n    throw unexpectedStatus(host, '/api/auth/cli-refresh', response.status);\n  }\n\n  if (!rotated) {\n    throw networkError(\n      `${host} refreshed the session without returning a rotated refresh token.`,\n      `Run \"ekanos login\" to start a fresh session, and report this — the ` +\n        `deployment's Auth0 CLI application may not have rotation enabled.`,\n    );\n  }\n\n  return { ...toSession(body, host), auth0RefreshToken: rotated };\n}\n\n/**\n * Prove the Fusion JWT authenticates. Returns null on 401 so the caller can\n * decide whether to refresh and retry — an expired access token is an ordinary\n * event, not an error.\n */\nexport async function fetchIdentity(\n  host: string,\n  accessToken: string,\n): Promise<FusionIdentity | null> {\n  const response = await request(`${host}/api/auth/cli-whoami`, {\n    method: 'GET',\n    headers: {\n      accept: 'application/json',\n      authorization: `Bearer ${accessToken}`,\n    },\n  });\n\n  // 401, or the 307 that an auth-gated Fusion route answers with. Both mean\n  // \"this token did not authenticate\".\n  if (response.status === 401 || isRedirect(response.status)) {\n    return null;\n  }\n\n  if (response.status === 403) {\n    throw authRequiredError(\n      `${host} requires multi-factor authentication for this account.`,\n      `Complete MFA in the browser, then run \"ekanos login\" again.`,\n    );\n  }\n\n  if (response.status === 404) {\n    throw authRequiredError(\n      `${host} has no account for the signed-in identity.`,\n      `Sign in to ${host} in a browser once to have the account created, ` +\n        `then run \"ekanos login\" again.`,\n    );\n  }\n\n  if (!response.ok) {\n    throw unexpectedStatus(host, '/api/auth/cli-whoami', response.status);\n  }\n\n  const body = await readJson(response, `${host}/api/auth/cli-whoami`);\n  const user = (body.user ?? {}) as Record<string, unknown>;\n  const id = str(user.id);\n\n  if (!id) {\n    throw networkError(\n      `${host} returned an identity without a user id.`,\n      `Confirm the deployment is running a Fusion build that includes the ` +\n        `/api/auth/cli-whoami route.`,\n    );\n  }\n\n  return { id, email: str(user.email), name: str(user.name) };\n}\n\nfunction toSession(body: Record<string, unknown>, host: string): FusionSession {\n  const user = (body.user ?? {}) as Record<string, unknown>;\n\n  const accessToken = str(body.access_token);\n  const expiresAt = str(body.expires_at);\n  const userId = str(user.id);\n\n  if (!accessToken || !expiresAt || !userId) {\n    throw networkError(\n      `${host} returned an incomplete session.`,\n      `Confirm the deployment is running a Fusion build that includes the ` +\n        `CLI auth routes, then retry.`,\n    );\n  }\n\n  return { accessToken, expiresAt, userId, email: str(user.email) };\n}\n\nexport async function request(\n  url: string,\n  init: RequestInit,\n): Promise<Response> {\n  try {\n    return await fetch(url, {\n      ...init,\n      redirect: 'manual',\n      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),\n    });\n  } catch (error) {\n    const reason = error instanceof Error ? error.message : String(error);\n\n    throw networkError(\n      `Could not reach ${new URL(url).origin}: ${reason}`,\n      `Check the host is correct and reachable from this machine ` +\n        `(proxy, VPN, DNS), then retry.`,\n    );\n  }\n}\n\n/**\n * Best-effort body read for a response whose status may be an error. Returns\n * an empty object rather than throwing, because the caller needs to inspect\n * the body BEFORE deciding what the status means — and a 500 from a proxy may\n * carry no JSON at all.\n */\nasync function readOptionalJson(\n  response: Response,\n): Promise<Record<string, unknown>> {\n  try {\n    const parsed: unknown = await response.json();\n\n    return typeof parsed === 'object' && parsed !== null\n      ? (parsed as Record<string, unknown>)\n      : {};\n  } catch {\n    return {};\n  }\n}\n\nasync function readJson(\n  response: Response,\n  what: string,\n): Promise<Record<string, unknown>> {\n  let parsed: unknown;\n\n  try {\n    parsed = await response.json();\n  } catch {\n    throw networkError(\n      `${what} did not return JSON.`,\n      `Confirm the host is a Fusion deployment and not a proxy or captive ` +\n        `portal sitting in front of one.`,\n    );\n  }\n\n  if (typeof parsed !== 'object' || parsed === null) {\n    throw networkError(\n      `${what} returned an unexpected payload.`,\n      `Confirm the host is a Fusion deployment, then retry.`,\n    );\n  }\n\n  return parsed as Record<string, unknown>;\n}\n\n/**\n * 503 means the deployment is not provisioned for CLI login — an operator\n * action that has not happened, not a fault in the request.\n *\n * Every route that reads the Fusion CLI Auth0 config can answer this, so every\n * caller has to check for it. Falling through to `unexpectedStatus` would tell\n * a partner \"confirm the host is a Fusion deployment\" when the host is a\n * perfectly good Fusion deployment that is simply missing one env var — and\n * would exit 8 (network, retryable) instead of 9 (precondition, not).\n */\nfunction throwIfNotConfigured(\n  response: Response,\n  host: string,\n  body?: Record<string, unknown>,\n): void {\n  if (response.status !== 503) return;\n\n  // 503 carries two meanings on these routes. Only CLI_NOT_CONFIGURED is a\n  // precondition; REFRESH_INCOMPLETE is transient and handled by its caller.\n  if (body && body.code !== 'CLI_NOT_CONFIGURED') return;\n\n  throw preconditionError(\n    `${host} does not have CLI login configured.`,\n    `Ask the Fusion operator to provision the \"Fusion CLI\" Auth0 ` +\n      `application and set AUTH0_CLI_CLIENT_ID on that deployment.`,\n  );\n}\n\nfunction unexpectedStatus(host: string, route: string, status: number) {\n  return networkError(\n    `${host}${route} responded ${status}.`,\n    status >= 500\n      ? `The Fusion deployment returned a server error. Retry shortly; if it ` +\n          `persists, report it with the status code.`\n      : `Confirm the host is a Fusion deployment running a build that ` +\n          `includes ${route}.`,\n  );\n}\n\nfunction assertOnDomain(endpoint: string, domain: string): void {\n  let url: URL;\n\n  try {\n    url = new URL(endpoint);\n  } catch {\n    throw preconditionError(\n      `The login configuration contains a malformed endpoint.`,\n      `Report this to the operator of the Fusion deployment.`,\n    );\n  }\n\n  if (\n    url.protocol !== 'https:' ||\n    url.host.toLowerCase() !== domain.toLowerCase()\n  ) {\n    throw preconditionError(\n      `The login configuration points at an endpoint outside its own Auth0 ` +\n        `domain (${url.host}).`,\n      `Do not continue. Report this to the operator of the Fusion ` +\n        `deployment — it may be misconfigured or compromised.`,\n    );\n  }\n}\n\nfunction isRedirect(status: number): boolean {\n  return status >= 300 && status < 400;\n}\n\nfunction str(value: unknown): string | null {\n  return typeof value === 'string' && value.length > 0 ? value : null;\n}\n"]}

package/dist/auth/session.d.ts

@@ -0,0 +1,57 @@
+import type { CliContext } from '../context.js';
+import { CredentialStore, type StoredSession } from './credential-store.js';
+import { type FusionIdentity } from './fusion-api.js';
+/**
+ * Session plumbing shared by `login`, `logout` and `whoami`: where the Fusion
+ * host comes from, where credentials live, and how a stale access token is
+ * silently replaced.
+ */
+export interface AuthEnvironment {
+    store: CredentialStore;
+    host: string;
+}
+/**
+ * Resolve the Fusion host from `--host`, else `EKANOS_HOST`.
+ *
+ * Deliberately no default. A baked-in default would be wrong for every partner
+ * running against their own sandbox, and — worse — a CLI that silently picks a
+ * host is a CLI that can send a developer's credentials somewhere they did not
+ * intend.
+ */
+export declare function resolveHost(flag: string | undefined, env: Record<string, string | undefined>): string;
+export declare function resolveAuthEnvironment(ctx: CliContext, hostFlag: string | undefined, env: Record<string, string | undefined>): AuthEnvironment;
+/** A store with no host attached — for `logout --all`. */
+export declare function newStore(ctx: CliContext, env: Record<string, string | undefined>): CredentialStore;
+export declare function requireSession(store: CredentialStore, host: string): StoredSession;
+/**
+ * Resolve the caller's identity, refreshing the access token once if the
+ * stored one no longer authenticates.
+ *
+ * Validity is decided by the SERVER, not by comparing `expiresAt` to the local
+ * clock. A container with a skewed clock — the exact environment this flow
+ * exists to support — would otherwise either refuse a perfectly good token or
+ * keep presenting a dead one. A 401 is the authoritative answer; one refresh
+ * and one retry is the whole recovery.
+ */
+export declare function resolveIdentity(env: AuthEnvironment, session: StoredSession): Promise<{
+    identity: FusionIdentity;
+    session: StoredSession;
+}>;
+/**
+ * Refresh and persist.
+ *
+ * The rotated refresh token is written the MOMENT the server reports it, not
+ * when the refresh finishes. Auth0 rotates as soon as the server's exchange
+ * succeeds, so from that instant the presented token is dead and the
+ * replacement is the only copy in existence — and `cli-refresh` can still fail
+ * afterwards (a `/userinfo` blip, a missing account, an unexpected throw) and
+ * return that replacement on an ERROR response. Saving only on success would
+ * discard it and lock the partner out for good over a transient upstream
+ * hiccup: one process, no concurrency needed.
+ *
+ * So `onRotatedToken` writes it immediately and `refreshFusionSession` invokes
+ * that before it throws. The write keeps the OLD access token, which is
+ * correct: that token is merely expired, while the refresh token is current
+ * and is what the next attempt needs.
+ */
+export declare function refreshStoredSession(env: AuthEnvironment, session: StoredSession): Promise<StoredSession>;

package/dist/auth/session.js

@@ -0,0 +1,114 @@
+import { authRequiredError, usageError } from '../errors.js';
+import { CredentialStore, normalizeHost, resolveEkanosHome, } from './credential-store.js';
+import { fetchIdentity, refreshFusionSession, } from './fusion-api.js';
+/**
+ * Resolve the Fusion host from `--host`, else `EKANOS_HOST`.
+ *
+ * Deliberately no default. A baked-in default would be wrong for every partner
+ * running against their own sandbox, and — worse — a CLI that silently picks a
+ * host is a CLI that can send a developer's credentials somewhere they did not
+ * intend.
+ */
+export function resolveHost(flag, env) {
+    const raw = flag !== null && flag !== void 0 ? flag : env.EKANOS_HOST;
+    if (!raw || raw.trim().length === 0) {
+        throw usageError('No Fusion host given.', 'Pass "--host https://<your-fusion-host>" or set EKANOS_HOST.');
+    }
+    return normalizeHost(raw.trim());
+}
+export function resolveAuthEnvironment(ctx, hostFlag, env) {
+    const host = resolveHost(hostFlag, env);
+    warnOnPlaintextHost(ctx, host);
+    return {
+        host,
+        store: newStore(ctx, env),
+    };
+}
+/** A store with no host attached — for `logout --all`. */
+export function newStore(ctx, env) {
+    return new CredentialStore({
+        home: resolveEkanosHome(env),
+        // Permission warnings are diagnostics, not results: stderr, always.
+        warn: (message) => ctx.warn(message),
+    });
+}
+/**
+ * `http://` is allowed because local development needs it, but sending a
+ * bearer token to a plaintext REMOTE host puts it on the wire in the clear.
+ * Warn rather than refuse: refusing would break `--host http://localhost:3000`
+ * for anyone whose loopback resolves to something other than the names below.
+ */
+function warnOnPlaintextHost(ctx, host) {
+    const url = new URL(host);
+    if (url.protocol !== 'http:')
+        return;
+    const loopback = ['localhost', '127.0.0.1', '[::1]', '0.0.0.0'];
+    if (loopback.includes(url.hostname) || url.hostname.endsWith('.localhost')) {
+        return;
+    }
+    ctx.warn(`ekanos: ${host} is plaintext HTTP. Your credentials will cross the ` +
+        `network unencrypted. Use https:// unless this is a local host.`);
+}
+export function requireSession(store, host) {
+    const session = store.read(host);
+    if (!session) {
+        throw authRequiredError(`Not logged in to ${host}.`, `Run "ekanos login --host ${host}".`);
+    }
+    return session;
+}
+/**
+ * Resolve the caller's identity, refreshing the access token once if the
+ * stored one no longer authenticates.
+ *
+ * Validity is decided by the SERVER, not by comparing `expiresAt` to the local
+ * clock. A container with a skewed clock — the exact environment this flow
+ * exists to support — would otherwise either refuse a perfectly good token or
+ * keep presenting a dead one. A 401 is the authoritative answer; one refresh
+ * and one retry is the whole recovery.
+ */
+export async function resolveIdentity(env, session) {
+    const identity = await fetchIdentity(env.host, session.accessToken);
+    if (identity) {
+        return { identity, session };
+    }
+    const refreshed = await refreshStoredSession(env, session);
+    const retried = await fetchIdentity(env.host, refreshed.accessToken);
+    if (!retried) {
+        throw authRequiredError(`The session for ${env.host} could not be renewed.`, `Run "ekanos logout --host ${env.host}" then "ekanos login --host ${env.host}".`);
+    }
+    return { identity: retried, session: refreshed };
+}
+/**
+ * Refresh and persist.
+ *
+ * The rotated refresh token is written the MOMENT the server reports it, not
+ * when the refresh finishes. Auth0 rotates as soon as the server's exchange
+ * succeeds, so from that instant the presented token is dead and the
+ * replacement is the only copy in existence — and `cli-refresh` can still fail
+ * afterwards (a `/userinfo` blip, a missing account, an unexpected throw) and
+ * return that replacement on an ERROR response. Saving only on success would
+ * discard it and lock the partner out for good over a transient upstream
+ * hiccup: one process, no concurrency needed.
+ *
+ * So `onRotatedToken` writes it immediately and `refreshFusionSession` invokes
+ * that before it throws. The write keeps the OLD access token, which is
+ * correct: that token is merely expired, while the refresh token is current
+ * and is what the next attempt needs.
+ */
+export async function refreshStoredSession(env, session) {
+    const persistRotated = (rotated) => {
+        env.store.write(env.host, Object.assign(Object.assign({}, session), { auth0RefreshToken: rotated, updatedAt: new Date().toISOString() }));
+    };
+    const refreshed = await refreshFusionSession(env.host, session.auth0RefreshToken, { onRotatedToken: persistRotated });
+    const next = {
+        auth0RefreshToken: refreshed.auth0RefreshToken,
+        accessToken: refreshed.accessToken,
+        expiresAt: refreshed.expiresAt,
+        userId: refreshed.userId,
+        email: refreshed.email,
+        updatedAt: new Date().toISOString(),
+    };
+    env.store.write(env.host, next);
+    return next;
+}
+//# sourceMappingURL=session.js.map

package/dist/auth/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/auth/session.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CliContext } from '../context';\nimport { authRequiredError, usageError } from '../errors';\nimport {\n  CredentialStore,\n  type StoredSession,\n  normalizeHost,\n  resolveEkanosHome,\n} from './credential-store';\nimport {\n  type FusionIdentity,\n  fetchIdentity,\n  refreshFusionSession,\n} from './fusion-api';\n\n/**\n * Session plumbing shared by `login`, `logout` and `whoami`: where the Fusion\n * host comes from, where credentials live, and how a stale access token is\n * silently replaced.\n */\n\nexport interface AuthEnvironment {\n  store: CredentialStore;\n  host: string;\n}\n\n/**\n * Resolve the Fusion host from `--host`, else `EKANOS_HOST`.\n *\n * Deliberately no default. A baked-in default would be wrong for every partner\n * running against their own sandbox, and — worse — a CLI that silently picks a\n * host is a CLI that can send a developer's credentials somewhere they did not\n * intend.\n */\nexport function resolveHost(\n  flag: string | undefined,\n  env: Record<string, string | undefined>,\n): string {\n  const raw = flag ?? env.EKANOS_HOST;\n\n  if (!raw || raw.trim().length === 0) {\n    throw usageError(\n      'No Fusion host given.',\n      'Pass \"--host https://<your-fusion-host>\" or set EKANOS_HOST.',\n    );\n  }\n\n  return normalizeHost(raw.trim());\n}\n\nexport function resolveAuthEnvironment(\n  ctx: CliContext,\n  hostFlag: string | undefined,\n  env: Record<string, string | undefined>,\n): AuthEnvironment {\n  const host = resolveHost(hostFlag, env);\n\n  warnOnPlaintextHost(ctx, host);\n\n  return {\n    host,\n    store: newStore(ctx, env),\n  };\n}\n\n/** A store with no host attached — for `logout --all`. */\nexport function newStore(\n  ctx: CliContext,\n  env: Record<string, string | undefined>,\n): CredentialStore {\n  return new CredentialStore({\n    home: resolveEkanosHome(env),\n    // Permission warnings are diagnostics, not results: stderr, always.\n    warn: (message) => ctx.warn(message),\n  });\n}\n\n/**\n * `http://` is allowed because local development needs it, but sending a\n * bearer token to a plaintext REMOTE host puts it on the wire in the clear.\n * Warn rather than refuse: refusing would break `--host http://localhost:3000`\n * for anyone whose loopback resolves to something other than the names below.\n */\nfunction warnOnPlaintextHost(ctx: CliContext, host: string): void {\n  const url = new URL(host);\n\n  if (url.protocol !== 'http:') return;\n\n  const loopback = ['localhost', '127.0.0.1', '[::1]', '0.0.0.0'];\n\n  if (loopback.includes(url.hostname) || url.hostname.endsWith('.localhost')) {\n    return;\n  }\n\n  ctx.warn(\n    `ekanos: ${host} is plaintext HTTP. Your credentials will cross the ` +\n      `network unencrypted. Use https:// unless this is a local host.`,\n  );\n}\n\nexport function requireSession(\n  store: CredentialStore,\n  host: string,\n): StoredSession {\n  const session = store.read(host);\n\n  if (!session) {\n    throw authRequiredError(\n      `Not logged in to ${host}.`,\n      `Run \"ekanos login --host ${host}\".`,\n    );\n  }\n\n  return session;\n}\n\n/**\n * Resolve the caller's identity, refreshing the access token once if the\n * stored one no longer authenticates.\n *\n * Validity is decided by the SERVER, not by comparing `expiresAt` to the local\n * clock. A container with a skewed clock — the exact environment this flow\n * exists to support — would otherwise either refuse a perfectly good token or\n * keep presenting a dead one. A 401 is the authoritative answer; one refresh\n * and one retry is the whole recovery.\n */\nexport async function resolveIdentity(\n  env: AuthEnvironment,\n  session: StoredSession,\n): Promise<{ identity: FusionIdentity; session: StoredSession }> {\n  const identity = await fetchIdentity(env.host, session.accessToken);\n\n  if (identity) {\n    return { identity, session };\n  }\n\n  const refreshed = await refreshStoredSession(env, session);\n  const retried = await fetchIdentity(env.host, refreshed.accessToken);\n\n  if (!retried) {\n    throw authRequiredError(\n      `The session for ${env.host} could not be renewed.`,\n      `Run \"ekanos logout --host ${env.host}\" then \"ekanos login --host ${env.host}\".`,\n    );\n  }\n\n  return { identity: retried, session: refreshed };\n}\n\n/**\n * Refresh and persist.\n *\n * The rotated refresh token is written the MOMENT the server reports it, not\n * when the refresh finishes. Auth0 rotates as soon as the server's exchange\n * succeeds, so from that instant the presented token is dead and the\n * replacement is the only copy in existence — and `cli-refresh` can still fail\n * afterwards (a `/userinfo` blip, a missing account, an unexpected throw) and\n * return that replacement on an ERROR response. Saving only on success would\n * discard it and lock the partner out for good over a transient upstream\n * hiccup: one process, no concurrency needed.\n *\n * So `onRotatedToken` writes it immediately and `refreshFusionSession` invokes\n * that before it throws. The write keeps the OLD access token, which is\n * correct: that token is merely expired, while the refresh token is current\n * and is what the next attempt needs.\n */\nexport async function refreshStoredSession(\n  env: AuthEnvironment,\n  session: StoredSession,\n): Promise<StoredSession> {\n  const persistRotated = (rotated: string) => {\n    env.store.write(env.host, {\n      ...session,\n      auth0RefreshToken: rotated,\n      updatedAt: new Date().toISOString(),\n    });\n  };\n\n  const refreshed = await refreshFusionSession(\n    env.host,\n    session.auth0RefreshToken,\n    { onRotatedToken: persistRotated },\n  );\n\n  const next: StoredSession = {\n    auth0RefreshToken: refreshed.auth0RefreshToken,\n    accessToken: refreshed.accessToken,\n    expiresAt: refreshed.expiresAt,\n    userId: refreshed.userId,\n    email: refreshed.email,\n    updatedAt: new Date().toISOString(),\n  };\n\n  env.store.write(env.host, next);\n\n  return next;\n}\n"]}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { run } from './index.js';
+/**
+ * The bin entry — the ONLY place that calls process.exit, so `run()` stays a
+ * pure, testable function that returns an exit code. Argv is sliced to drop
+ * the node executable and this script path.
+ */
+run(process.argv.slice(2))
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((error) => {
+    var _a;
+    // run() catches its own errors and emits the envelope; reaching here means
+    // the envelope machinery itself threw. Fail loudly on stderr (never
+    // stdout) with the internal exit code.
+    process.stderr.write(`ekanos: fatal internal error: ${error instanceof Error ? ((_a = error.stack) !== null && _a !== void 0 ? _a : error.message) : String(error)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAE9B;;;;GAIG;AACH,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;KACvB,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;IACb,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,CAAC;KACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;;IACxB,2EAA2E;IAC3E,oEAAoE;IACpE,uCAAuC;IACvC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iCACE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,MAAA,KAAK,CAAC,KAAK,mCAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CACxE,IAAI,CACL,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { run } from './index';\n\n/**\n * The bin entry — the ONLY place that calls process.exit, so `run()` stays a\n * pure, testable function that returns an exit code. Argv is sliced to drop\n * the node executable and this script path.\n */\nrun(process.argv.slice(2))\n  .then((code) => {\n    process.exitCode = code;\n  })\n  .catch((error: unknown) => {\n    // run() catches its own errors and emits the envelope; reaching here means\n    // the envelope machinery itself threw. Fail loudly on stderr (never\n    // stdout) with the internal exit code.\n    process.stderr.write(\n      `ekanos: fatal internal error: ${\n        error instanceof Error ? (error.stack ?? error.message) : String(error)\n      }\\n`,\n    );\n    process.exitCode = 1;\n  });\n"]}

package/dist/commands/dev.d.ts

@@ -0,0 +1,36 @@
+import type { CliContext } from '../context.js';
+export interface DevArgs {
+    /** Project directory (contains ekanos.json). Defaults to cwd. */
+    dir: string;
+    /** Port for the dev server. */
+    port?: string;
+    /**
+     * Interface to bind. Defaults to loopback — see `resolveHost`. Anything
+     * else is an explicit, warned-about decision to expose the harness.
+     */
+    host?: string;
+    /** Rewrite every generated file even when its bytes already match. */
+    force: boolean;
+    /**
+     * Explicit `--start` / `--no-start`. Undefined means "decide from the
+     * output mode": a JSON caller is an agent or a pipe and must not be handed
+     * a process that never exits.
+     */
+    start?: boolean;
+}
+/**
+ * `dev` — scaffold the local harness shell into the partner's project, then
+ * run it with their own Next.
+ *
+ * The shape of this verb follows from one rule: we must be able to ship a
+ * harness bugfix as an `@ekanos/harness` version bump that a partner picks up
+ * with `pnpm up`, with zero edits to any file they own. So everything under
+ * `.ekanos/` is generated, gitignored and rewritten freely, `harness.config.ts`
+ * at the project root is written once and never touched again, and all actual
+ * harness behaviour lives in the installed package.
+ *
+ * Two idempotency properties matter and are both tested: a second run produces
+ * byte-identical files and rewrites nothing (so Next's watcher stays quiet),
+ * and `.gitignore` never grows a duplicate line.
+ */
+export declare function runDev(ctx: CliContext, args: DevArgs): Promise<number>;