feat(sdk): let plugins mint a short-lived user session and read a user's locale (#1666)

ctx.auth.issueUserToken(userId, { purpose, ttlSeconds }) gives background
work a session for calling Termix's own API as an existing user. It needs
users:impersonate, defaults to 300s and is capped at 900s, is stored as a
normal session row marked as plugin-issued, and every issue is audited.
Such sessions are refused on routes that change the user's password,
second factors, API keys or linked logins.

ctx.users.getLocale(userId) reads the user's UI language under users:read.

SDK 1.0.11, plugin API 1.3.0.

packages/plugin-sdk/src/backend.ts

@@ -1464,6 +1464,20 @@ export interface PluginSecondFactor {
   reset?: (userId: string) => Promise<void>;
 }
 
+export interface PluginUserTokenOptions {
+  /** Why the token exists, kept in the audit log and on the session. */
+  purpose: string;
+  /** Seconds until it expires. Defaults to 300 and is capped at 900. */
+  ttlSeconds?: number;
+}
+
+export interface PluginUserToken {
+  /** Send as `Authorization: Bearer <token>` to core's own API. */
+  token: string;
+  /** ISO time the session ends. */
+  expiresAt: string;
+}
+
 /**
  * Login methods, second factors and SSH auth types. Every register call needs
  * auth:provide and a matching contributes.auth entry, and is undone on
@@ -1525,6 +1539,26 @@ export interface PluginAuth {
    * delete a provider people still sign in with.
    */
   countLinkedUsers: (provider: string) => Promise<number>;
+  /**
+   * A short-lived session for an existing user, for calling core's own HTTP
+   * API as them from work with no request behind it, like a scheduled task
+   * driving the Termix CLI. The user's RBAC applies unchanged. Needs
+   * users:impersonate, not auth:provide, and every call is audited.
+   *
+   * The session is marked with the plugin and purpose. It cannot change the
+   * user's password, second factors, API keys or linked logins, so it can
+   * never outlive itself.
+   */
+  issueUserToken: (
+    userId: string,
+    options: PluginUserTokenOptions,
+  ) => Promise<PluginUserToken>;
+}
+
+/** What a plugin may learn about a user. Needs users:read. */
+export interface PluginUsers {
+  /** The user's UI language, like "zh_CN", or null when they never chose one. */
+  getLocale: (userId: string) => Promise<string | null>;
 }
 
 export interface PluginOpenIsolatedWindowRequest {
@@ -2013,8 +2047,13 @@ export interface PluginContext {
   readonly hosts: PluginHosts;
   /** SSH through core's connect pipeline. Needs ssh:connect and credentials:use. */
   readonly ssh: PluginSsh;
-  /** Login methods, second factors and SSH auth types. Needs auth:provide. */
+  /**
+   * Login methods, second factors and SSH auth types. Needs auth:provide,
+   * except issueUserToken, which needs users:impersonate.
+   */
   readonly auth: PluginAuth;
+  /** What a plugin may learn about a user. Needs users:read. */
+  readonly users: PluginUsers;
   /** Opens Electron windows outside the main renderer. Needs desktop:window. */
   readonly desktop: PluginDesktop;
   /** Host protocol credentials and the user's saved SSH keys. See PluginCredentials. */
@@ -2039,8 +2078,9 @@ export interface PluginContext {
    * no request behind it. Always audited, and every core API inside still
    * applies that user's RBAC.
    *
-   * Needs users:impersonate. That and a `userId` option on services.get or
-   * secrets.getShared are the only ways a plugin can name a user.
+   * Needs users:impersonate. That, auth.issueUserToken and a `userId` option
+   * on services.get or secrets.getShared are the only ways a plugin can act
+   * as a user it names.
    */
   asUser: <T>(userId: string, fn: () => Promise<T> | T) => Promise<T>;
 

packages/plugin-sdk/src/manifest.ts

@@ -36,7 +36,7 @@ export {
  * "^1.2" needs 1.2 or later). engine.termix is checked against the core
  * version by the server.
  */
-export const PLUGIN_API_VERSION = "1.2.0";
+export const PLUGIN_API_VERSION = "1.3.0";
 
 /** The API major, the default engine.api for a new plugin. */
 export const SUPPORTED_PLUGIN_API_VERSION = String(

packages/plugin-sdk/src/testing.ts

@@ -174,6 +174,8 @@ export interface FakeContextOptions {
   linkedUsers?: Record<string, number>;
   /** Failures before ctx.auth.loginRateLimit locks a key. Defaults to 5. */
   loginAttemptLimit?: number;
+  /** What ctx.users.getLocale answers, by user id. A missing user answers null. */
+  locales?: Record<string, string>;
 }
 
 export interface FakeProcessOptions {
@@ -247,6 +249,8 @@ export interface FakeAuthRegistrations {
   }>;
   /** Failures recorded through ctx.auth.loginRateLimit, by "<ip>|<key>". */
   loginFailures: Map<string, number>;
+  /** Every ctx.auth.issueUserToken call, in order. */
+  userTokens: Array<{ userId: string; purpose: string; ttlSeconds?: number }>;
 }
 
 export interface FakePluginContext {
@@ -574,6 +578,7 @@ export function createFakeContext(
     completedLogins: [],
     revokedSessions: [],
     loginFailures: new Map(),
+    userTokens: [],
   };
   const sshClient = options.sshClient ?? {};
   let actor = options.actor;
@@ -1140,6 +1145,18 @@ export function createFakeContext(
       },
       countLinkedUsers: async (provider) =>
         options.linkedUsers?.[provider] ?? 0,
+      issueUserToken: async (userId, tokenOptions) => {
+        auth.userTokens.push({ userId, ...tokenOptions });
+        const ttl = Math.min(tokenOptions.ttlSeconds ?? 300, 900);
+        return {
+          token: `fake-token-${auth.userTokens.length}`,
+          expiresAt: new Date(Date.now() + ttl * 1000).toISOString(),
+        };
+      },
+    },
+
+    users: {
+      getLocale: async (userId) => options.locales?.[userId] ?? null,
     },
 
     desktop: {
@@ -1442,6 +1459,8 @@ export interface MockContextOptions {
   linkedUsers?: Record<string, number>;
   /** See FakeContextOptions. */
   loginAttemptLimit?: number;
+  /** See FakeContextOptions. */
+  locales?: Record<string, string>;
 }
 
 export interface MockPluginContext extends FakePluginContext {
@@ -1458,7 +1477,8 @@ export interface MockPluginContext extends FakePluginContext {
  * topic outside the plugin's own namespace, settings:read-core on
  * ctx.settings.readCore, ssh:connect plus credentials:use on ctx.ssh,
  * notify:send on ctx.notify (notify:hub on serve), network:outbound on ctx.fetch, process:spawn on
- * ctx.process, system:tls on ctx.system, plugins:read on ctx.plugins, and auth:provide on ctx.auth. Reading a plugin's own settings is deliberately
+ * ctx.process, system:tls on ctx.system, plugins:read on ctx.plugins, auth:provide on ctx.auth
+ * (users:impersonate on issueUserToken), and users:read on ctx.users. Reading a plugin's own settings is deliberately
  * ungated. As the SDK grows a member, add its gate here in the same shape.
  */
 export function createMockCtx(
@@ -1495,6 +1515,7 @@ export function createMockCtx(
     baseUrl: options.baseUrl,
     linkedUsers: options.linkedUsers,
     loginAttemptLimit: options.loginAttemptLimit,
+    locales: options.locales,
     manifest: {
       capabilities: options.capabilities ?? [],
       ...options.manifest,
@@ -1786,6 +1807,17 @@ export function createMockCtx(
         require("auth:provide");
         return ctx.auth.countLinkedUsers(provider);
       },
+      issueUserToken: async (userId, tokenOptions) => {
+        require("users:impersonate");
+        return ctx.auth.issueUserToken(userId, tokenOptions);
+      },
+    },
+
+    users: {
+      getLocale: async (userId) => {
+        require("users:read");
+        return ctx.users.getLocale(userId);
+      },
     },
 
     desktop: {