@kubitnodes/stellaris 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kr4t0n
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -22,10 +22,11 @@ export STELLARIS_DATA_DIR=~/stellaris-data
 stellaris init --name my-society                          # prints your user token once
 stellaris agent add desk --role concierge --cli claude    # the front desk, which routes what you ask
 stellaris agent add stew --role steward --cli claude      # the steward, which reads the society's signals
-stellaris runner add laptop                               # prints the runner's token once
 stellaris-server                                          # http://127.0.0.1:4700
 ```
 
-Open the server's address and enter the user token. Then start a runner with the runner's token on any machine that reaches the server.
+Open the server's address and enter the user token. Then start a runner on any machine that reaches the server; it prints a code to approve on the board, under runners.
+
+To sign in with GitHub instead, create a GitHub OAuth app whose callback URL is the server's address followed by `/auth/github/callback`, and start the server with `STELLARIS_GITHUB_CLIENT_ID`, `STELLARIS_GITHUB_CLIENT_SECRET`, and `STELLARIS_GITHUB_USERS`, the logins allowed in. A lost user token is replaced with `stellaris user token --rotate`, which a running server takes after a restart.
 
 The CLI writes the data directory directly, so run its setup commands before the server starts; once it runs, act as the user through the interface or the HTTP API. `STELLARIS_HOST` and `STELLARIS_PORT` set where the server listens (`127.0.0.1:4700`); every setting is a `STELLARIS_*` variable, listed in the [repository's README](https://github.com/kr4t0n/stellaris#environment-variables). The server is also published as a Docker image, `kr4t0n/stellaris-server`, and a Helm chart.

package/dist/cli/index.js

@@ -670,6 +670,9 @@ var BOARD_EVENT_TYPES = [
   "knowledge.written",
   "skill.promoted",
   "runner.added",
+  "user.signed_in",
+  "user.signed_out",
+  "user.token_rotated",
   "runner.changed",
   "ops.signal",
   "paused.changed",
@@ -771,6 +774,36 @@ var RunnerHelloSchema = z6.object({
   turns: z6.array(UlidSchema).default([])
 });
 var RunnerWelcomeSchema = z6.object({ name: NameSchema, version: z6.string() });
+var RunnerEnrollRequestSchema = z6.object({
+  protocol: z6.number().int().positive(),
+  version: z6.string().min(1).max(64),
+  hostname: z6.string().min(1).max(253),
+  os: RunnerOsSchema,
+  clis: z6.array(CliKindSchema).max(8),
+  capabilities: z6.array(z6.string().min(1).max(64)).max(32).default([])
+});
+var RunnerEnrollmentSchema = z6.object({
+  deviceCode: z6.string().min(1),
+  userCode: z6.string().min(1),
+  expiresAt: IsoDateTimeSchema,
+  intervalMs: z6.number().int().positive()
+});
+var RunnerEnrollPollSchema = z6.object({ deviceCode: z6.string().min(1) });
+var RunnerEnrollStatusSchema = z6.discriminatedUnion("status", [
+  z6.object({ status: z6.literal("pending") }),
+  z6.object({ status: z6.literal("approved"), name: NameSchema, token: z6.string().min(1) }),
+  z6.object({ status: z6.literal("denied") })
+]);
+var PendingEnrollmentSchema = z6.object({
+  userCode: z6.string().min(1),
+  hostname: z6.string(),
+  os: RunnerOsSchema,
+  clis: z6.array(CliKindSchema),
+  capabilities: z6.array(z6.string()),
+  version: z6.string(),
+  requestedAt: IsoDateTimeSchema,
+  expiresAt: IsoDateTimeSchema
+});
 var ProjectRepoSchema = z6.object({
   slug: NameSchema,
   origin: z6.string().nullable(),
@@ -1077,6 +1110,12 @@ var MetricsSchema = z9.object({
 // packages/shared/dist/config.js
 import { z as z10 } from "zod";
 var LogLevelSchema = z10.enum(["trace", "debug", "info", "warn", "error", "fatal"]);
+var GithubSignInSchema = z10.object({
+  clientId: z10.string().min(1),
+  clientSecret: z10.string().min(1),
+  /** Logins, lowercased; GitHub logins are case-insensitive. */
+  users: z10.array(z10.string().min(1)).min(1)
+});
 var ServerConfigSchema = z10.object({
   dataDir: z10.string().min(1),
   host: z10.string().min(1),
@@ -1094,13 +1133,23 @@ var ServerConfigSchema = z10.object({
   /** Rounds of tool calls one Claude turn may take, or null for no limit. */
   toolRounds: z10.number().int().positive().nullable(),
   /** How long a resident session stays warm after its last turn. */
-  residentIdleMs: z10.number().int().positive()
+  residentIdleMs: z10.number().int().positive(),
+  /** Signing in to the board with GitHub, or null when only a token lets anyone in. */
+  github: GithubSignInSchema.nullable(),
+  /**
+   * Reverse proxies in front of the server whose X-Forwarded-For entries name the client, for the
+   * rate limits on what anyone may ask without a token: 0 when clients connect directly.
+   */
+  trustedProxies: z10.number().int().min(0).max(16)
 });
 var RunnerConfigSchema = z10.object({
   /** The board server, for example http://127.0.0.1:4700. */
   serverUrl: z10.string().url(),
-  /** The runner's token, minted by `runner add`. */
-  token: z10.string().min(1),
+  /**
+   * The runner's token, from `runner add`, or null for the one it saved when it was enrolled, or
+   * to enroll it.
+   */
+  token: z10.string().min(1).nullable(),
   /** The runner's own data directory: the board mirror, agent homes, repositories, worktrees. */
   dataDir: z10.string().min(1),
   logLevel: LogLevelSchema,
@@ -1111,7 +1160,7 @@ var RunnerConfigSchema = z10.object({
 });
 
 // packages/shared/dist/version.js
-var STELLARIS_VERSION = "0.1.0";
+var STELLARIS_VERSION = "0.3.0";
 
 // packages/board-core/dist/errors.js
 var BoardError = class extends Error {
@@ -2141,6 +2190,14 @@ var SKIPPED_IN_HOME = /* @__PURE__ */ new Set([".git", "turns", ".claude", ".cod
 var RunnerTokensSchema = z12.object({
   runners: z12.record(z12.string(), z12.object({ tokenHash: z12.string().min(1) }))
 });
+var SignInsSchema = z12.object({
+  signIns: z12.array(z12.object({
+    tokenHash: z12.string().min(1),
+    login: z12.string().min(1),
+    createdAt: IsoDateTimeSchema,
+    expiresAt: IsoDateTimeSchema
+  })).default([])
+});
 var TurnHistoryPayloadSchema = z12.object({
   project: NameSchema,
   thread: UlidSchema.optional(),
@@ -2346,6 +2403,8 @@ var Board = class _Board {
   turnTokens = /* @__PURE__ */ new Map();
   /** Runner token hashes to runner names. */
   runnerTokens = /* @__PURE__ */ new Map();
+  /** Sign-ins by token hash, each acting as the user until it expires. */
+  signIns = /* @__PURE__ */ new Map();
   files = new FileTree();
   homes;
   constructor(dataDir, options) {
@@ -2374,6 +2433,7 @@ var Board = class _Board {
     await board.mutex.run(() => board.applyAlignments());
     await board.loadTokenIndex();
     await board.loadRunnerTokens();
+    await board.loadSignIns();
     await board.homes.installHooks();
     return board;
   }
@@ -2621,7 +2681,7 @@ var Board = class _Board {
         }
       }
     }
-    await this.updateAgent(USER_NAME, (user) => ({ ...user, subscriptions: [] }));
+    await this.updateAgent(USER_NAME, (user2) => ({ ...user2, subscriptions: [] }));
     await this.refreshMember(USER_NAME);
   }
   /** Writes every missing seed charter and aligns the existing ones with their seed. */
@@ -2696,6 +2756,14 @@ ${charter.purpose}
     if (persistent !== void 0) {
       return persistent;
     }
+    const signIn = this.signIns.get(hash);
+    if (signIn !== void 0) {
+      if (signIn.expiresAt > this.now().getTime()) {
+        return this.userActor();
+      }
+      this.signIns.delete(hash);
+      return null;
+    }
     const temporary = this.turnTokens.get(hash);
     if (temporary === void 0) {
       return null;
@@ -2740,6 +2808,77 @@ ${charter.purpose}
   userActor() {
     return { name: USER_NAME, role: USER_ROLE };
   }
+  /**
+   * Signs the user in, as `login` on the identity provider, for `ttlMs`, and returns the sign-in's
+   * token, shown once. Only its hash is kept, in `state/sign-ins.json`, so a sign-in outlives a
+   * restart; it acts as the user, like the user's own token, until it expires or is signed out.
+   */
+  async signIn(login, ttlMs) {
+    return this.mutex.run(async () => {
+      const token = mintToken();
+      const now = this.now().getTime();
+      const record = {
+        tokenHash: hashToken(token),
+        login,
+        createdAt: new Date(now).toISOString(),
+        expiresAt: new Date(now + ttlMs).toISOString()
+      };
+      const live = (await this.readSignIns()).filter((each) => Date.parse(each.expiresAt) > now);
+      await writeJson(this.signInsFile(), { signIns: [...live, record] });
+      this.signIns.set(record.tokenHash, { login, expiresAt: Date.parse(record.expiresAt) });
+      await this.events.append("user.signed_in", USER_NAME, { login });
+      return token;
+    });
+  }
+  /** Ends the sign-in a token belongs to; false for a token that is no sign-in's. */
+  async signOut(token) {
+    const hash = hashToken(token);
+    return this.mutex.run(async () => {
+      const signIn = this.signIns.get(hash);
+      if (signIn === void 0) {
+        return false;
+      }
+      this.signIns.delete(hash);
+      await writeJson(this.signInsFile(), {
+        signIns: (await this.readSignIns()).filter((each) => each.tokenHash !== hash)
+      });
+      await this.events.append("user.signed_out", USER_NAME, { login: signIn.login });
+      return true;
+    });
+  }
+  /**
+   * Issues the user a new token and revokes the old one, returning the new one, shown once: the way
+   * back in when the token is lost. A server already running keeps the old token's hash in memory
+   * until it restarts, since the admin CLI that calls this writes the data directory beside it.
+   */
+  async rotateUserToken() {
+    return this.mutex.run(async () => {
+      const previous = await this.readAgent(USER_NAME);
+      const token = mintToken();
+      await this.updateAgent(USER_NAME, (agent2) => ({ ...agent2, tokenHash: hashToken(token) }));
+      this.tokenIndex.delete(previous.tokenHash);
+      this.tokenIndex.set(hashToken(token), this.userActor());
+      await this.events.append("user.token_rotated", USER_NAME, {});
+      return token;
+    });
+  }
+  signInsFile() {
+    return path6.join(this.paths.state(), "sign-ins.json");
+  }
+  async readSignIns() {
+    const file = this.signInsFile();
+    return await exists(file) ? (await readJson(file, SignInsSchema)).signIns : [];
+  }
+  async loadSignIns() {
+    this.signIns.clear();
+    const now = this.now().getTime();
+    for (const signIn of await this.readSignIns()) {
+      const expiresAt = Date.parse(signIn.expiresAt);
+      if (expiresAt > now) {
+        this.signIns.set(signIn.tokenHash, { login: signIn.login, expiresAt });
+      }
+    }
+  }
   async actorFor(name) {
     const agent2 = await this.readAgent(name);
     return { name: agent2.name, role: agent2.role };
@@ -3074,9 +3213,9 @@ ${charter.purpose}
 
 Agents may edit this file. It is rendered by the board UI.
 `);
-    await this.updateAgent(USER_NAME, (user) => ({
-      ...user,
-      memberships: [.../* @__PURE__ */ new Set([...user.memberships, project2.slug])]
+    await this.updateAgent(USER_NAME, (user2) => ({
+      ...user2,
+      memberships: [.../* @__PURE__ */ new Set([...user2.memberships, project2.slug])]
     }));
     await this.refreshMember(USER_NAME);
     await this.events.append("project.added", by, {
@@ -4736,8 +4875,9 @@ ${rationale}`}`);
   /**
    * Registers a runner and mints its token, returned once; only its hash is kept, outside the
    * projection. The runner reports its operating system, CLIs, and capabilities when it connects.
+   * An enrolled runner names the machine that asked, which the event records.
    */
-  async addRunner(actor, name) {
+  async addRunner(actor, name, enrolled) {
     if (actor.role !== USER_ROLE) {
       throw new BoardError("FORBIDDEN", "only the user adds runners");
     }
@@ -4761,7 +4901,10 @@ ${rationale}`}`);
         runners: { ...tokens, [parsed]: { tokenHash: hashToken(token) } }
       });
       this.runnerTokens.set(hashToken(token), parsed);
-      await this.events.append("runner.added", actor.name, { name: parsed });
+      await this.events.append("runner.added", actor.name, {
+        name: parsed,
+        ...enrolled === void 0 ? {} : { enrolledFrom: enrolled.hostname }
+      });
       return { runner: runner2, token };
     });
   }
@@ -4958,7 +5101,7 @@ ${charter.purpose}
     await writeJson(this.paths.pausedFile(), { paused: false });
     const userToken = mintToken();
     const userCharter = await this.readRole(USER_ROLE);
-    const user = AgentSchema.parse({
+    const user2 = AgentSchema.parse({
       name: USER_NAME,
       role: USER_ROLE,
       cli: null,
@@ -4968,7 +5111,7 @@ ${charter.purpose}
       createdAt,
       tokenHash: hashToken(userToken)
     });
-    await this.writeAgentHome(user, userCharter);
+    await this.writeAgentHome(user2, userCharter);
     await this.events.append("society.initialized", USER_NAME, { name: society.name });
     return userToken;
   }
@@ -5871,6 +6014,18 @@ program.command("init").description("Create a society in the data directory and
     `User token (shown once): ${userToken}`
   ].join("\n"));
 });
+var user = program.command("user").description("The user's own access");
+user.command("token").description("Issue the user a new token and print it once; the old one stops working").option("--rotate", "replace the token", false).action(async (opts) => {
+  if (!opts.rotate) {
+    throw new BoardError("VALIDATION", "the board keeps only a hash of the user token, so it cannot show it again; `user token --rotate` issues a new one");
+  }
+  const board = await open();
+  const userToken = await board.rotateUserToken();
+  print({ userToken }, () => [
+    `User token (shown once): ${userToken}`,
+    "A board server running on this data directory reads the new token only when it restarts."
+  ].join("\n"));
+});
 var project = program.command("project").description("Manage projects");
 project.command("add <slug>").description("Add a project with its default channels").option("--name <name>", "display name").option("--repo <url>", "git remote").option("--on-done <effect>", "what finishing a task does: none, or merge its branch").action(async (slug, opts) => {
   const board = await open();