@trillboards/cli 0.1.0 → 0.1.1

package/dist/user-auth.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Agent-ads user-JWT authentication.
+ *
+ * The agent-ads surface authenticates as the DEVELOPER (a Trillboards user),
+ * NOT the partner. The virtual-screen register route only accepts a user JWT
+ * (`Authorization: Bearer <JWT>` via middleware/auth.js verifyToken) — the
+ * partner `api_key` does not work there. So we maintain a separate token pair:
+ *   - user_token            (access JWT, 1h TTL)
+ *   - user_refresh_token    (refresh token, 90d TTL)
+ *
+ * Tokens are stored in ~/.trillboards/config.json (same file/perms as api_key)
+ * and are NEVER logged.
+ */
+/** deviceType sent to /v1/user/login + /v1/user/refresh-token (the route requires it). */
+export declare const AGENT_CLI_DEVICE_TYPE = "agent_cli";
+export interface LoginResult {
+    token: string;
+    refreshToken: string;
+    /** Seconds until the access token expires (server returns 3600). */
+    expiresIn: number;
+}
+/**
+ * POST /v1/user/login {email, password, deviceType} → {token, refreshToken, expiresIn}.
+ *
+ * Throws TrillboardsApiError on non-2xx (401 invalid creds, 404 no user, etc.).
+ */
+export declare function loginUser(baseUrl: string, email: string, password: string): Promise<LoginResult>;
+export interface RefreshResult {
+    /** New access token. NOTE: refresh returns `accessToken`, login returns `token`. */
+    token: string;
+    refreshToken: string;
+    expiresIn: number;
+}
+/**
+ * POST /v1/user/refresh-token {refreshToken, deviceType} → {accessToken, refreshToken, expiresIn}.
+ *
+ * Tokens are rotated: a NEW refresh token comes back too and must be persisted.
+ */
+export declare function refreshUserToken(baseUrl: string, refreshToken: string): Promise<RefreshResult>;
+/** Persist a login/refresh result to config (token, refresh token, computed expiry). */
+export declare function persistTokens(result: {
+    token: string;
+    refreshToken: string;
+    expiresIn: number;
+}): void;
+/**
+ * Resolve the active user JWT, refreshing it first if it is missing an expiry,
+ * expired, or within the refresh skew window. Returns the valid access token, or
+ * `null` if there is no usable credential (caller should tell the user to log in).
+ *
+ * Precedence:
+ *   1. TRILLBOARDS_USER_TOKEN env (headless paste — used verbatim, never refreshed)
+ *   2. config.user_token (refreshed via config.user_refresh_token when stale)
+ */
+export declare function refreshUserTokenIfNeeded(baseUrl: string): Promise<string | null>;
+/** Expose the access-token TTL for tests / callers that want to set expiry. */
+export declare const ACCESS_TOKEN_TTL: number;

package/dist/user-auth.js

@@ -0,0 +1,110 @@
+/**
+ * Agent-ads user-JWT authentication.
+ *
+ * The agent-ads surface authenticates as the DEVELOPER (a Trillboards user),
+ * NOT the partner. The virtual-screen register route only accepts a user JWT
+ * (`Authorization: Bearer <JWT>` via middleware/auth.js verifyToken) — the
+ * partner `api_key` does not work there. So we maintain a separate token pair:
+ *   - user_token            (access JWT, 1h TTL)
+ *   - user_refresh_token    (refresh token, 90d TTL)
+ *
+ * Tokens are stored in ~/.trillboards/config.json (same file/perms as api_key)
+ * and are NEVER logged.
+ */
+import { readConfig, updateConfig } from './config.js';
+import { TrillboardsApiError, apiRequest } from './http.js';
+/** deviceType sent to /v1/user/login + /v1/user/refresh-token (the route requires it). */
+export const AGENT_CLI_DEVICE_TYPE = 'agent_cli';
+/** Access-token TTL in ms (server issues 1h tokens; expiresIn=3600). */
+const ACCESS_TOKEN_TTL_MS = 3600 * 1000;
+/** Refresh proactively when within this window of expiry (5 minutes). */
+const REFRESH_SKEW_MS = 5 * 60 * 1000;
+/**
+ * POST /v1/user/login {email, password, deviceType} → {token, refreshToken, expiresIn}.
+ *
+ * Throws TrillboardsApiError on non-2xx (401 invalid creds, 404 no user, etc.).
+ */
+export async function loginUser(baseUrl, email, password) {
+    const res = (await apiRequest('POST', '/v1/user/login', {
+        baseUrl,
+        body: { email, password, deviceType: AGENT_CLI_DEVICE_TYPE },
+    }));
+    const token = typeof res.token === 'string' ? res.token : '';
+    const refreshToken = typeof res.refreshToken === 'string' ? res.refreshToken : '';
+    if (!token || !refreshToken) {
+        throw new TrillboardsApiError('Login succeeded but no token was returned', 'LOGIN_NO_TOKEN', 502);
+    }
+    const expiresIn = typeof res.expiresIn === 'number' && res.expiresIn > 0 ? res.expiresIn : 3600;
+    return { token, refreshToken, expiresIn };
+}
+/**
+ * POST /v1/user/refresh-token {refreshToken, deviceType} → {accessToken, refreshToken, expiresIn}.
+ *
+ * Tokens are rotated: a NEW refresh token comes back too and must be persisted.
+ */
+export async function refreshUserToken(baseUrl, refreshToken) {
+    const res = (await apiRequest('POST', '/v1/user/refresh-token', {
+        baseUrl,
+        body: { refreshToken, deviceType: AGENT_CLI_DEVICE_TYPE },
+    }));
+    // Refresh response uses `accessToken` (asymmetric vs login's `token`).
+    const token = typeof res.accessToken === 'string' ? res.accessToken : '';
+    const newRefresh = typeof res.refreshToken === 'string' ? res.refreshToken : '';
+    if (!token) {
+        throw new TrillboardsApiError('Refresh succeeded but no access token was returned', 'REFRESH_NO_TOKEN', 502);
+    }
+    const expiresIn = typeof res.expiresIn === 'number' && res.expiresIn > 0 ? res.expiresIn : 3600;
+    // Keep the existing refresh token if the server somehow omitted a rotated one.
+    return { token, refreshToken: newRefresh || refreshToken, expiresIn };
+}
+/** Persist a login/refresh result to config (token, refresh token, computed expiry). */
+export function persistTokens(result) {
+    updateConfig({
+        user_token: result.token,
+        user_refresh_token: result.refreshToken,
+        user_token_expires_at: Date.now() + result.expiresIn * 1000,
+    });
+}
+/**
+ * Resolve the active user JWT, refreshing it first if it is missing an expiry,
+ * expired, or within the refresh skew window. Returns the valid access token, or
+ * `null` if there is no usable credential (caller should tell the user to log in).
+ *
+ * Precedence:
+ *   1. TRILLBOARDS_USER_TOKEN env (headless paste — used verbatim, never refreshed)
+ *   2. config.user_token (refreshed via config.user_refresh_token when stale)
+ */
+export async function refreshUserTokenIfNeeded(baseUrl) {
+    const envToken = process.env.TRILLBOARDS_USER_TOKEN;
+    if (envToken && envToken.trim()) {
+        // Caller supplied a raw JWT; we have no refresh token for it, so use as-is.
+        return envToken.trim();
+    }
+    const cfg = readConfig();
+    const token = cfg.user_token;
+    const refreshToken = cfg.user_refresh_token;
+    if (!token)
+        return null;
+    const expiresAt = cfg.user_token_expires_at;
+    const nearExpiry = typeof expiresAt !== 'number' || Number.isNaN(expiresAt) || Date.now() >= expiresAt - REFRESH_SKEW_MS;
+    if (!nearExpiry) {
+        return token;
+    }
+    // Token is stale/near-expiry. Refresh if we can; otherwise return what we have
+    // and let the downstream 401 surface a clear re-login prompt.
+    if (!refreshToken)
+        return token;
+    try {
+        const refreshed = await refreshUserToken(baseUrl, refreshToken);
+        persistTokens(refreshed);
+        return refreshed.token;
+    }
+    catch {
+        // Refresh failed (expired/rotated/revoked refresh token). Fall back to the
+        // current access token; if it is also dead the API call will 401 and the
+        // command will instruct the user to run `trillboards ads login`.
+        return token;
+    }
+}
+/** Expose the access-token TTL for tests / callers that want to set expiry. */
+export const ACCESS_TOKEN_TTL = ACCESS_TOKEN_TTL_MS;