@nanhara/hara 0.127.0 → 0.127.1

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.127.1 — 2026-07-20 — managed access lifecycle
+
+- Managed enrollment now persists the control plane's authoritative device-token expiry. Hara warns
+  during the final 24 hours, reports the boundary in `whoami`/`enroll --status`, and fails closed with
+  a focused re-enrollment command once access expires or lifecycle data is corrupt.
+- Serve provider settings expose only expiry metadata—not the token—so Hara Desktop can distinguish
+  an authenticated managed route from an expired one.
+- Upgrade with `npm i -g @nanhara/hara@0.127.1`.
+
 ## 0.127.0 — 2026-07-20 — structured context and typed task lifecycle
 
 - **Prompt assembly is now an explicit, ordered runtime layer.** Cache-stable policy, tool, project, and

package/dist/index.js

@@ -22,7 +22,7 @@ import { notifyDone } from "./notify.js";
 import { startMcpServer, mcpServeToolNames } from "./mcp/server.js";
 import { completionScript } from "./completions.js";
 import { renderSessionMarkdown } from "./export.js";
-import { clearEnrollment, enrollDevice, heartbeat, syncOrgRoles } from "./org-fleet/enroll.js";
+import { clearEnrollment, enrollDevice, heartbeat, syncOrgRoles, deviceTokenExpired, deviceTokenExpiryWarning, } from "./org-fleet/enroll.js";
 import { loadActiveProfile, listProfiles, useProfile, addProfile, upsertProfile, removeProfile, setModel as setProfileModel, resetModel as resetProfileModel, getProfile, effectiveModel, routingLabel, routeHost, activeId, resolveActive, setFlagOverride, writePin, removePin, pinFilePath, DEFAULT_ORG_ID, PERSONAL_ID, } from "./profile/profile.js";
 import { loadPermissionRules, scaffoldPermissions, globalPermissionsPath, projectPermissionsPath } from "./security/permissions.js";
 import { routingProvider } from "./agent/route.js";
@@ -134,7 +134,7 @@ async function buildProvider(cfg, targetOverride) {
     // requests" — gateway (deviceToken at the gateway) vs BYOK (user's key direct to the provider).
     const { profile: ap } = profileForConfig(cfg);
     if (ap.kind === "gateway") {
-        if (!ap.gatewayUrl || !ap.deviceToken)
+        if (!ap.gatewayUrl || !ap.deviceToken || deviceTokenExpired(ap.tokenExpiresAt))
             return null;
         const baseURL = ap.baseURL || `${ap.gatewayUrl.replace(/\/$/, "")}/v1`;
         const model = resolveGatewayModel(cfg, ap, process.env, targetOverride?.model);
@@ -193,8 +193,12 @@ async function buildGuardian(cfg, primary) {
 }
 function authHint(cfg) {
     const { profile: ap } = profileForConfig(cfg);
-    if (ap.kind === "gateway")
+    if (ap.kind === "gateway") {
+        if (deviceTokenExpired(ap.tokenExpiresAt)) {
+            return `Active profile '${ap.id}' has expired organization access — re-enroll with \`hara profile add ${ap.id} --gateway ${ap.gatewayUrl || "<url>"} --code <code>\`.`;
+        }
         return `Active profile '${ap.id}' is a gateway profile but is missing deviceToken — re-enroll with \`hara profile add ${ap.id} --gateway <url> --code <code>\`.`;
+    }
     const target = resolveByokProviderTarget(cfg, ap, false);
     const provider = target.provider;
     if (provider === "qwen-oauth")
@@ -215,6 +219,7 @@ function providerSettingsSnapshot(targetCwd) {
     const catalog = providerCatalog();
     if (profile.kind === "gateway") {
         const entry = catalog.find((candidate) => candidate.id === "hara-gateway");
+        const tokenExpired = deviceTokenExpired(profile.tokenExpiresAt);
         return {
             current: {
                 provider: "hara-gateway",
@@ -223,11 +228,12 @@ function providerSettingsSnapshot(targetCwd) {
                 location: entry.location,
                 auth: entry.auth,
                 keyConfigured: !!profile.deviceToken,
-                authenticated: !!profile.gatewayUrl && !!profile.deviceToken,
+                authenticated: !!profile.gatewayUrl && !!profile.deviceToken && !tokenExpired,
                 profileId: profile.id,
                 profileKind: profile.kind,
                 profileSource: resolution.source,
                 editable: false,
+                ...(profile.tokenExpiresAt ? { tokenExpiresAt: profile.tokenExpiresAt, tokenExpired } : {}),
             },
             providers: catalog,
         };
@@ -1664,6 +1670,11 @@ function printWhoami() {
             out(c.dim(`  device:   ${p.deviceId.length > 8 ? "…" + p.deviceId.slice(-8) : p.deviceId}\n`));
         if (p.availableModels?.length)
             out(c.dim(`  available: ${p.availableModels.join(", ")}\n`));
+        if (p.tokenExpiresAt)
+            out(c.dim(`  expires:  ${p.tokenExpiresAt}\n`));
+        const warning = deviceTokenExpiryWarning(p.tokenExpiresAt);
+        if (warning)
+            out(c.yellow(`  ⚠ ${warning}\n`));
     }
     else {
         out(c.dim(`  provider: ${p.provider}\n`));
@@ -1795,6 +1806,7 @@ profileCmd
                 defaultModel: e.model || "",
                 availableModels: e.model ? [e.model] : [],
                 enrolledAt: e.enrolledAt,
+                tokenExpiresAt: e.expiresAt,
             };
             upsertProfile(p); // upsert: re-enrolling the same id rotates the token
             const r = useProfile(id);
@@ -1982,8 +1994,8 @@ program
     .option("--clear", "switch active profile back to personal (does NOT delete the gateway profile)")
     .action(async (gatewayUrl, opts) => {
     if (opts.status) {
-        const p = loadActiveProfile();
-        return void out(p.kind === "gateway" ? c.green("enrolled") + c.dim(` · ${p.gatewayUrl} · device ${p.deviceId || "?"} · model ${effectiveModel(p) || "(gateway default)"} · since ${p.enrolledAt || "?"}\n`) : c.dim("Not enrolled — `hara enroll <gateway-url> --code <code>`.\n"));
+        printWhoami();
+        return;
     }
     if (opts.clear) {
         // Behavior change: don't *delete* the gateway profile (keeps the token around for re-use);
@@ -2010,6 +2022,7 @@ program
             defaultModel: e.model || "",
             availableModels: e.model ? [e.model] : [],
             enrolledAt: e.enrolledAt,
+            tokenExpiresAt: e.expiresAt,
         };
         upsertProfile(p);
         useProfile(DEFAULT_ORG_ID);
@@ -3093,6 +3106,11 @@ program.action(async (opts) => {
     // to suppress everywhere.
     if (!opts.print && process.env.HARA_QUIET !== "1") {
         out(c.dim(activeProfileLine(__activeP)) + "\n");
+        const expiryWarning = __activeP.kind === "gateway"
+            ? deviceTokenExpiryWarning(__activeP.tokenExpiresAt)
+            : null;
+        if (expiryWarning)
+            out(c.yellow(`⚠ ${expiryWarning}\n`));
     }
     if (__activeP.kind === "gateway" || cfg.provider === "hara-gateway") {
         void heartbeat(); // fleet visibility — fire-and-forget, never blocks startup

package/dist/org-fleet/enroll.js

@@ -5,7 +5,7 @@
 // plane fleet visibility. Token + endpoint live in ~/.hara/org.json (0600).
 //
 // Protocol (what `hara-control` implements on the other end):
-//   POST {gateway}/v1/enroll      {code, device:{name,os,hara_version}} -> {device_token, device_id, model, base_url?}
+//   POST {gateway}/v1/enroll      {code, device:{name,os,hara_version}} -> {device_token, device_id, model, base_url?, expires_at?}
 //   POST {gateway}/v1/heartbeat   Bearer <device_token> {device_id, name, os, hara_version} -> 200/204
 //   GET  {gateway}/v1/roles       Bearer <device_token> -> {version, org_policy, roles:[…]}  (B3 digital-employee push-down)
 //   POST {gateway}/v1/chat/completions  (OpenAI-compatible; the normal agent traffic, Bearer <device_token>)
@@ -45,6 +45,7 @@ export function loadEnrollment() {
                 model: ap.defaultModel || "",
                 baseURL: ap.baseURL,
                 enrolledAt: ap.enrolledAt || new Date().toISOString(),
+                expiresAt: ap.tokenExpiresAt,
             };
         }
     }
@@ -70,6 +71,14 @@ export function parseEnrollResponse(gatewayUrl, j, now) {
     const deviceToken = (j.device_token ?? j.deviceToken);
     if (!deviceToken)
         throw new Error("enroll response missing device_token");
+    const rawExpiresAt = j.expires_at ?? j.expiresAt;
+    let expiresAt;
+    if (rawExpiresAt !== undefined && rawExpiresAt !== null) {
+        if (typeof rawExpiresAt !== "string" || !Number.isFinite(Date.parse(rawExpiresAt))) {
+            throw new Error("enroll response contains an invalid expires_at");
+        }
+        expiresAt = new Date(rawExpiresAt).toISOString();
+    }
     return {
         gatewayUrl: gatewayUrl.replace(/\/$/, ""),
         deviceToken,
@@ -77,8 +86,36 @@ export function parseEnrollResponse(gatewayUrl, j, now) {
         model: String(j.model ?? ""),
         baseURL: (j.base_url ?? j.baseURL),
         enrolledAt: now,
+        expiresAt,
     };
 }
+/** Legacy control planes did not advertise token expiry, so absence remains compatible. New control
+ * planes provide it and the CLI can fail early with an actionable re-enrollment message. */
+export function deviceTokenExpired(expiresAt, now = new Date()) {
+    if (!expiresAt)
+        return false;
+    const expiryMs = Date.parse(expiresAt);
+    // A present-but-corrupt lifecycle boundary must not silently become a legacy non-expiring token.
+    return !Number.isFinite(expiryMs) || expiryMs <= now.getTime();
+}
+/** Only warn near the boundary; healthy week-long tokens should not add startup noise. */
+export function deviceTokenExpiryWarning(expiresAt, now = new Date()) {
+    if (!expiresAt)
+        return null;
+    const expiryMs = Date.parse(expiresAt);
+    if (!Number.isFinite(expiryMs))
+        return "organization access expiry is unreadable; re-enroll this profile";
+    const remainingMs = expiryMs - now.getTime();
+    if (remainingMs <= 0)
+        return "organization access expired; re-enroll this profile before running a task";
+    if (remainingMs > 24 * 60 * 60_000)
+        return null;
+    const remainingMinutes = Math.max(1, Math.ceil(remainingMs / 60_000));
+    const remaining = remainingMinutes < 60
+        ? `${remainingMinutes}m`
+        : `${Math.ceil(remainingMinutes / 60)}h`;
+    return `organization access expires in ${remaining}; ask your admin for a new enrollment code`;
+}
 /** Exchange a one-time code for a device token at the gateway, persist it, and return the Enrollment. */
 export async function enrollDevice(gatewayUrl, code, signal) {
     const base = gatewayUrl.replace(/\/$/, "");

package/dist/profile/profile.js

@@ -98,6 +98,7 @@ function readDefaultOrgFromOrgJson(e) {
         defaultModel,
         availableModels: defaultModel ? [defaultModel] : [],
         enrolledAt: e.enrolledAt || new Date().toISOString(),
+        tokenExpiresAt: typeof e.expiresAt === "string" ? e.expiresAt : undefined,
     };
 }
 /** First-time migration. Idempotent — running again is a no-op (profiles.json already present). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.127.0",
+  "version": "0.127.1",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "runtime-bootstrap.cjs"