@danypops/tickets 0.1.0

package/src/application/service.ts

@@ -0,0 +1,84 @@
+/**
+ * Application service — the hexagon's core orchestration layer. Implements the
+ * driver-facing operations (used by the CLI and the pi-tickets extension) and
+ * routes every call to the named backend's repository. Depends only on ports,
+ * never on a concrete adapter.
+ */
+import type { Comment, CreateInput, Issue, ListFilter, UpdateInput } from "../domain/issue.js";
+import { parseRef } from "../domain/issue.js";
+import { hasComments, type IssueRepository } from "../ports/repository.js";
+
+export class UnknownBackendError extends Error {
+  constructor(backend: string, known: string[]) {
+    super(`unknown backend "${backend}" (known: ${known.join(", ") || "none configured"})`);
+    this.name = "UnknownBackendError";
+  }
+}
+
+export class NotSupportedError extends Error {
+  constructor(backend: string, capability: string) {
+    super(`${backend} does not support ${capability}`);
+    this.name = "NotSupportedError";
+  }
+}
+
+export class TicketService {
+  constructor(private readonly repos: Record<string, IssueRepository>) {}
+
+  backends(): string[] {
+    return Object.keys(this.repos);
+  }
+
+  private repo(backend: string): IssueRepository {
+    const repo = this.repos[backend];
+    if (!repo) throw new UnknownBackendError(backend, this.backends());
+    return repo;
+  }
+
+  // Every method here is declared `async` deliberately, even where the body
+  // doesn't otherwise need to await anything: ref parsing and backend lookup
+  // can throw synchronously (UnknownBackendError, invalid ref), and callers
+  // uniformly treat every TicketService call as a Promise. Without `async`,
+  // those synchronous throws would escape before a Promise ever existed,
+  // breaking `await`/`.rejects` callers alike.
+  async list(backend: string, filter: ListFilter = {}): Promise<Issue[]> {
+    return this.repo(backend).list(filter);
+  }
+
+  async get(ref: string): Promise<Issue> {
+    const { backend, key } = parseRef(ref);
+    return this.repo(backend).get(key);
+  }
+
+  async create(backend: string, input: CreateInput): Promise<Issue> {
+    return this.repo(backend).create(input);
+  }
+
+  async update(ref: string, input: UpdateInput): Promise<Issue> {
+    const { backend, key } = parseRef(ref);
+    return this.repo(backend).update(key, input);
+  }
+
+  async search(backend: string, query: string, limit?: number): Promise<Issue[]> {
+    return this.repo(backend).search(query, limit);
+  }
+
+  async children(ref: string): Promise<Issue[]> {
+    const { backend, key } = parseRef(ref);
+    return this.repo(backend).listChildren(key);
+  }
+
+  async comments(ref: string): Promise<Comment[]> {
+    const { backend, key } = parseRef(ref);
+    const repo = this.repo(backend);
+    if (!hasComments(repo)) throw new NotSupportedError(backend, "comments");
+    return repo.listComments(key);
+  }
+
+  async addComment(ref: string, body: string): Promise<Comment> {
+    const { backend, key } = parseRef(ref);
+    const repo = this.repo(backend);
+    if (!hasComments(repo)) throw new NotSupportedError(backend, "comments");
+    return repo.addComment(key, body);
+  }
+}

package/src/auth/browser.ts

@@ -0,0 +1,35 @@
+/**
+ * Cross-platform "open this URL in the user's browser" helper. Deliberately
+ * hand-rolled rather than a dependency: it's a 3-way platform switch behind
+ * one array-form spawn call (no shell string interpolation, so no injection
+ * surface from an untrusted URL), well under the size where a mature
+ * dependency would remove a real bug class.
+ */
+import { spawn } from "node:child_process";
+
+export type Spawner = (command: string, args: string[]) => void;
+
+const defaultSpawner: Spawner = (command, args) => {
+  const child = spawn(command, args, { stdio: "ignore", detached: true });
+  child.unref();
+};
+
+function isHttpUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/** Throws on anything that isn't a well-formed http(s) URL — never hands an untrusted string to a shell. */
+export function openUrl(url: string, opts: { platform?: NodeJS.Platform; spawner?: Spawner } = {}): void {
+  if (!isHttpUrl(url)) throw new Error(`refusing to open non-http(s) URL: ${url}`);
+  const platform = opts.platform ?? process.platform;
+  const spawner = opts.spawner ?? defaultSpawner;
+
+  if (platform === "darwin") return spawner("open", [url]);
+  if (platform === "win32") return spawner("cmd", ["/c", "start", '""', url]);
+  return spawner("xdg-open", [url]);
+}

package/src/auth/device-flow.ts

@@ -0,0 +1,140 @@
+/**
+ * OAuth 2.0 Device Authorization Grant (RFC 8628), shared between GitHub and
+ * GitLab — both implement the same shape, confirmed against their own docs:
+ *   GitHub: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow
+ *     POST https://github.com/login/device/code
+ *     POST https://github.com/login/oauth/access_token (grant_type=urn:ietf:params:oauth:grant-type:device_code)
+ *   GitLab: https://docs.gitlab.com/api/oauth2/ ("Device Authorization Grant", GA in GitLab 17.9)
+ *     POST {baseUrl}/oauth/authorize_device
+ *     POST {baseUrl}/oauth/token (same grant_type)
+ * This is the "open a link, enter a code" flow: no client secret, no redirect
+ * URI/local callback server needed, ideal for a headless daemon. Jira/Atlassian
+ * has no equivalent (see jira-oauth.ts, which uses Authorization Code instead).
+ */
+import type { FetchLike } from "../adapters/http.js";
+
+export const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+
+export class DeviceFlowError extends Error {
+  constructor(
+    public readonly provider: string,
+    public readonly code: string,
+    description?: string,
+  ) {
+    super(`${provider} device authorization failed: ${code}${description ? ` (${description})` : ""}`);
+    this.name = "DeviceFlowError";
+  }
+}
+
+export interface DeviceFlowConfig {
+  /** Used only in error messages, e.g. "github". */
+  provider: string;
+  deviceAuthorizationUrl: string;
+  tokenUrl: string;
+  clientId: string;
+  scope?: string;
+  fetchImpl?: FetchLike;
+}
+
+export interface DeviceAuthorization {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  verificationUriComplete?: string;
+  expiresInSeconds: number;
+  intervalSeconds: number;
+}
+
+export interface DeviceFlowToken {
+  accessToken: string;
+  tokenType: string;
+  scope?: string;
+  /** ISO timestamp; undefined when the provider issues a non-expiring token (classic GitHub OAuth Apps). */
+  expiresAt?: string;
+  refreshToken?: string;
+}
+
+async function postForm(
+  fetchImpl: FetchLike,
+  url: string,
+  params: Record<string, string>,
+): Promise<Record<string, unknown>> {
+  const res = await fetchImpl(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+    body: new URLSearchParams(params).toString(),
+  });
+  const text = await res.text();
+  return text ? (JSON.parse(text) as Record<string, unknown>) : {};
+}
+
+export async function requestDeviceAuthorization(config: DeviceFlowConfig): Promise<DeviceAuthorization> {
+  const fetchImpl = config.fetchImpl ?? fetch;
+  const params: Record<string, string> = { client_id: config.clientId };
+  if (config.scope) params.scope = config.scope;
+  const body = await postForm(fetchImpl, config.deviceAuthorizationUrl, params);
+  if (typeof body.device_code !== "string" || typeof body.user_code !== "string") {
+    throw new DeviceFlowError(config.provider, "invalid_response", JSON.stringify(body));
+  }
+  return {
+    deviceCode: body.device_code,
+    userCode: body.user_code,
+    verificationUri: String(body.verification_uri ?? ""),
+    verificationUriComplete:
+      typeof body.verification_uri_complete === "string" ? body.verification_uri_complete : undefined,
+    expiresInSeconds: Number(body.expires_in ?? 900),
+    intervalSeconds: Number(body.interval ?? 5),
+  };
+}
+
+export interface PollOptions {
+  /** Injectable for tests; defaults to a real timer. */
+  sleep?: (ms: number) => Promise<void>;
+  /** Safety cap independent of the server's expires_in, so a misbehaving server can't loop forever. */
+  maxAttempts?: number;
+}
+
+const DEFAULT_MAX_ATTEMPTS = 200;
+
+export async function pollForToken(
+  config: DeviceFlowConfig,
+  authorization: DeviceAuthorization,
+  opts: PollOptions = {},
+): Promise<DeviceFlowToken> {
+  const fetchImpl = config.fetchImpl ?? fetch;
+  const sleep = opts.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  let intervalMs = authorization.intervalSeconds * 1000;
+  const deadline = Date.now() + authorization.expiresInSeconds * 1000;
+
+  for (let attempt = 0; attempt < maxAttempts && Date.now() < deadline; attempt++) {
+    await sleep(intervalMs);
+    const body = await postForm(fetchImpl, config.tokenUrl, {
+      grant_type: DEVICE_GRANT_TYPE,
+      device_code: authorization.deviceCode,
+      client_id: config.clientId,
+    });
+
+    if (body.error === "authorization_pending") continue;
+    if (body.error === "slow_down") {
+      intervalMs += 5_000;
+      continue;
+    }
+    if (typeof body.error === "string") {
+      throw new DeviceFlowError(config.provider, body.error, body.error_description as string | undefined);
+    }
+    if (typeof body.access_token !== "string") {
+      throw new DeviceFlowError(config.provider, "invalid_response", JSON.stringify(body));
+    }
+    return {
+      accessToken: body.access_token,
+      tokenType: String(body.token_type ?? "Bearer"),
+      scope: typeof body.scope === "string" ? body.scope : undefined,
+      expiresAt:
+        typeof body.expires_in === "number" ? new Date(Date.now() + body.expires_in * 1000).toISOString() : undefined,
+      refreshToken: typeof body.refresh_token === "string" ? body.refresh_token : undefined,
+    };
+  }
+
+  throw new DeviceFlowError(config.provider, "expired_token", "device code expired before authorization completed");
+}

package/src/auth/github-oauth.ts

@@ -0,0 +1,44 @@
+/**
+ * GitHub delegated auth via the OAuth 2.0 Device Authorization Grant.
+ * Docs: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow
+ * Requires a GitHub OAuth App (or GitHub App) with the device flow enabled in
+ * its settings; the client ID is public (no secret needed for this flow).
+ */
+import type { FetchLike } from "../adapters/http.js";
+import { type DeviceFlowConfig, type DeviceFlowToken, type PollOptions, pollForToken, requestDeviceAuthorization } from "./device-flow.js";
+
+export const GITHUB_DEVICE_AUTHORIZATION_URL = "https://github.com/login/device/code";
+export const GITHUB_TOKEN_URL = "https://github.com/login/oauth/access_token";
+export const GITHUB_DEFAULT_SCOPE = "repo read:org";
+
+export interface DevicePrompt {
+  userCode: string;
+  verificationUri: string;
+  verificationUriComplete?: string;
+}
+
+export interface GitHubDeviceLoginOptions {
+  clientId: string;
+  scope?: string;
+  fetchImpl?: FetchLike;
+  onPrompt: (prompt: DevicePrompt) => void | Promise<void>;
+  poll?: PollOptions;
+}
+
+export async function loginWithGitHubDeviceFlow(opts: GitHubDeviceLoginOptions): Promise<DeviceFlowToken> {
+  const config: DeviceFlowConfig = {
+    provider: "github",
+    deviceAuthorizationUrl: GITHUB_DEVICE_AUTHORIZATION_URL,
+    tokenUrl: GITHUB_TOKEN_URL,
+    clientId: opts.clientId,
+    scope: opts.scope ?? GITHUB_DEFAULT_SCOPE,
+    fetchImpl: opts.fetchImpl,
+  };
+  const authorization = await requestDeviceAuthorization(config);
+  await opts.onPrompt({
+    userCode: authorization.userCode,
+    verificationUri: authorization.verificationUri,
+    verificationUriComplete: authorization.verificationUriComplete,
+  });
+  return pollForToken(config, authorization, opts.poll);
+}

package/src/auth/gitlab-oauth.ts

@@ -0,0 +1,51 @@
+/**
+ * GitLab delegated auth via the OAuth 2.0 Device Authorization Grant, GA
+ * since GitLab 17.9 (self-managed) and available on GitLab.com.
+ * Docs: https://docs.gitlab.com/api/oauth2/ ("Device Authorization Grant").
+ * Requires a "non-confidential" GitLab OAuth application (no client secret
+ * for this flow, same shape as GitHub's device flow / RFC 8628).
+ */
+import type { FetchLike } from "../adapters/http.js";
+import { type DeviceFlowConfig, type DeviceFlowToken, type PollOptions, pollForToken, requestDeviceAuthorization } from "./device-flow.js";
+import type { DevicePrompt } from "./github-oauth.js";
+
+export const GITLAB_DEFAULT_SCOPE = "read_api";
+
+export function gitlabDeviceEndpoints(baseUrl = "https://gitlab.com"): {
+  deviceAuthorizationUrl: string;
+  tokenUrl: string;
+} {
+  const trimmed = baseUrl.replace(/\/+$/, "");
+  return {
+    deviceAuthorizationUrl: `${trimmed}/oauth/authorize_device`,
+    tokenUrl: `${trimmed}/oauth/token`,
+  };
+}
+
+export interface GitLabDeviceLoginOptions {
+  clientId: string;
+  baseUrl?: string;
+  scope?: string;
+  fetchImpl?: FetchLike;
+  onPrompt: (prompt: DevicePrompt) => void | Promise<void>;
+  poll?: PollOptions;
+}
+
+export async function loginWithGitLabDeviceFlow(opts: GitLabDeviceLoginOptions): Promise<DeviceFlowToken> {
+  const endpoints = gitlabDeviceEndpoints(opts.baseUrl);
+  const config: DeviceFlowConfig = {
+    provider: "gitlab",
+    deviceAuthorizationUrl: endpoints.deviceAuthorizationUrl,
+    tokenUrl: endpoints.tokenUrl,
+    clientId: opts.clientId,
+    scope: opts.scope ?? GITLAB_DEFAULT_SCOPE,
+    fetchImpl: opts.fetchImpl,
+  };
+  const authorization = await requestDeviceAuthorization(config);
+  await opts.onPrompt({
+    userCode: authorization.userCode,
+    verificationUri: authorization.verificationUri,
+    verificationUriComplete: authorization.verificationUriComplete,
+  });
+  return pollForToken(config, authorization, opts.poll);
+}

package/src/auth/jira-oauth.ts

@@ -0,0 +1,251 @@
+/**
+ * Jira/Atlassian delegated auth via OAuth 2.0 (3LO), Authorization Code grant.
+ * Docs: https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/
+ *
+ * Unlike GitHub/GitLab, Atlassian's 3LO apps are confidential clients (no
+ * PKCE, no device flow — confirmed absent from their docs) and require a
+ * client secret. That means this flow needs a local redirect: we bind an
+ * ephemeral loopback HTTP server, send the user to Atlassian's consent
+ * screen, and receive the authorization code on the callback.
+ *
+ * OAuth 2.0 (3LO) access tokens are NOT used the way Basic-auth API tokens
+ * are: requests go to https://api.atlassian.com/ex/jira/{cloudId}/... with
+ * `Authorization: Bearer <token>`, not directly to the tenant's *.atlassian.net
+ * domain. The cloudId is discovered via the accessible-resources endpoint
+ * after the token exchange — see JiraOAuthToken below.
+ */
+import { randomBytes } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { FetchLike } from "../adapters/http.js";
+
+export const ATLASSIAN_AUTHORIZE_URL = "https://auth.atlassian.com/authorize";
+export const ATLASSIAN_TOKEN_URL = "https://auth.atlassian.com/oauth/token";
+export const ATLASSIAN_ACCESSIBLE_RESOURCES_URL = "https://api.atlassian.com/oauth/token/accessible-resources";
+export const JIRA_DEFAULT_SCOPE = "read:jira-work write:jira-work read:jira-user offline_access";
+
+export interface JiraSite {
+  id: string;
+  name: string;
+  url: string;
+  scopes: string[];
+}
+
+export interface JiraOAuthToken {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: string;
+  cloudId: string;
+  siteUrl: string;
+}
+
+export class JiraOAuthError extends Error {
+  constructor(message: string) {
+    super(`jira oauth: ${message}`);
+    this.name = "JiraOAuthError";
+  }
+}
+
+export interface CallbackResult {
+  code: string;
+  redirectUri: string;
+}
+
+export interface CallbackServer {
+  redirectUriFor(host?: string): string;
+  waitForCode(timeoutMs: number): Promise<CallbackResult>;
+  close(): Promise<void>;
+}
+
+/**
+ * Binds an ephemeral loopback HTTP server that answers exactly one
+ * `/callback` request, validating `state` before resolving. Exported
+ * separately from loginWithJiraAuthorizationCode so tests can drive it with
+ * a real HTTP request instead of a real browser.
+ */
+export function startCallbackServer(expectedState: string, port = 0): CallbackServer {
+  let resolveCode: ((result: CallbackResult) => void) | undefined;
+  let rejectCode: ((error: Error) => void) | undefined;
+
+  const server: Server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (url.pathname !== "/callback") {
+      res.writeHead(404).end("not found");
+      return;
+    }
+    const error = url.searchParams.get("error");
+    const state = url.searchParams.get("state");
+    const code = url.searchParams.get("code");
+
+    if (error) {
+      res.writeHead(400, { "Content-Type": "text/html" }).end("<html><body>Authorization denied. You can close this tab.</body></html>");
+      rejectCode?.(new JiraOAuthError(`authorization denied: ${error}`));
+      return;
+    }
+    if (state !== expectedState) {
+      res.writeHead(400, { "Content-Type": "text/html" }).end("<html><body>State mismatch. Aborting.</body></html>");
+      rejectCode?.(new JiraOAuthError("state mismatch on OAuth callback"));
+      return;
+    }
+    if (!code) {
+      res.writeHead(400, { "Content-Type": "text/html" }).end("<html><body>Missing authorization code.</body></html>");
+      rejectCode?.(new JiraOAuthError("callback missing authorization code"));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "text/html" }).end("<html><body>Authorized. You can close this tab and return to the terminal.</body></html>");
+    resolveCode?.({ code, redirectUri: redirectUriFor() });
+  });
+
+  function redirectUriFor(host = "127.0.0.1"): string {
+    const address = server.address() as AddressInfo;
+    return `http://${host}:${address.port}/callback`;
+  }
+
+  server.listen(port);
+
+  return {
+    redirectUriFor,
+    waitForCode(timeoutMs: number): Promise<CallbackResult> {
+      return new Promise((resolve, reject) => {
+        resolveCode = resolve;
+        rejectCode = reject;
+        setTimeout(() => reject(new JiraOAuthError("timed out waiting for the OAuth callback")), timeoutMs);
+      });
+    },
+    close(): Promise<void> {
+      return new Promise((resolve) => server.close(() => resolve()));
+    },
+  };
+}
+
+export function buildAuthorizeUrl(opts: {
+  clientId: string;
+  redirectUri: string;
+  scope: string;
+  state: string;
+}): string {
+  const url = new URL(ATLASSIAN_AUTHORIZE_URL);
+  url.searchParams.set("audience", "api.atlassian.com");
+  url.searchParams.set("client_id", opts.clientId);
+  url.searchParams.set("scope", opts.scope);
+  url.searchParams.set("redirect_uri", opts.redirectUri);
+  url.searchParams.set("state", opts.state);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("prompt", "consent");
+  return url.toString();
+}
+
+interface TokenResponse {
+  access_token: string;
+  refresh_token?: string;
+  expires_in?: number;
+  scope?: string;
+}
+
+async function exchangeCode(
+  fetchImpl: FetchLike,
+  opts: { clientId: string; clientSecret: string; code: string; redirectUri: string },
+): Promise<TokenResponse> {
+  const res = await fetchImpl(ATLASSIAN_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      grant_type: "authorization_code",
+      client_id: opts.clientId,
+      client_secret: opts.clientSecret,
+      code: opts.code,
+      redirect_uri: opts.redirectUri,
+    }),
+  });
+  const body = (await res.json()) as TokenResponse & { error?: string; error_description?: string };
+  if (!res.ok || !body.access_token) {
+    throw new JiraOAuthError(body.error_description ?? body.error ?? `token exchange failed with HTTP ${res.status}`);
+  }
+  return body;
+}
+
+export async function fetchAccessibleResources(fetchImpl: FetchLike, accessToken: string): Promise<JiraSite[]> {
+  const res = await fetchImpl(ATLASSIAN_ACCESSIBLE_RESOURCES_URL, {
+    headers: { Authorization: `Bearer ${accessToken}`, Accept: "application/json" },
+  });
+  if (!res.ok) throw new JiraOAuthError(`accessible-resources failed with HTTP ${res.status}`);
+  return (await res.json()) as JiraSite[];
+}
+
+export interface JiraOAuthLoginOptions {
+  clientId: string;
+  clientSecret: string;
+  scope?: string;
+  port?: number;
+  fetchImpl?: FetchLike;
+  onPrompt: (authorizeUrl: string) => void | Promise<void>;
+  timeoutMs?: number;
+  /** Pick a site when the token is granted access to more than one; defaults to the first. */
+  chooseSite?: (sites: JiraSite[]) => JiraSite;
+}
+
+const DEFAULT_CALLBACK_TIMEOUT_MS = 120_000;
+
+export async function loginWithJiraAuthorizationCode(opts: JiraOAuthLoginOptions): Promise<JiraOAuthToken> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const state = randomBytes(16).toString("hex");
+  const server = startCallbackServer(state, opts.port ?? 0);
+
+  try {
+    const redirectUri = server.redirectUriFor();
+    const authorizeUrl = buildAuthorizeUrl({
+      clientId: opts.clientId,
+      redirectUri,
+      scope: opts.scope ?? JIRA_DEFAULT_SCOPE,
+      state,
+    });
+    const waiting = server.waitForCode(opts.timeoutMs ?? DEFAULT_CALLBACK_TIMEOUT_MS);
+    await opts.onPrompt(authorizeUrl);
+    const { code } = await waiting;
+
+    const token = await exchangeCode(fetchImpl, {
+      clientId: opts.clientId,
+      clientSecret: opts.clientSecret,
+      code,
+      redirectUri,
+    });
+    const sites = await fetchAccessibleResources(fetchImpl, token.access_token);
+    if (sites.length === 0) throw new JiraOAuthError("no accessible Atlassian sites granted to this token");
+    const site = (opts.chooseSite ?? ((all: JiraSite[]) => all[0]))(sites) as JiraSite;
+
+    return {
+      accessToken: token.access_token,
+      refreshToken: token.refresh_token,
+      expiresAt: token.expires_in ? new Date(Date.now() + token.expires_in * 1000).toISOString() : undefined,
+      cloudId: site.id,
+      siteUrl: site.url,
+    };
+  } finally {
+    await server.close();
+  }
+}
+
+export async function refreshJiraToken(
+  fetchImpl: FetchLike,
+  opts: { clientId: string; clientSecret: string; refreshToken: string },
+): Promise<{ accessToken: string; refreshToken?: string; expiresAt?: string }> {
+  const res = await fetchImpl(ATLASSIAN_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      grant_type: "refresh_token",
+      client_id: opts.clientId,
+      client_secret: opts.clientSecret,
+      refresh_token: opts.refreshToken,
+    }),
+  });
+  const body = (await res.json()) as TokenResponse & { error?: string; error_description?: string };
+  if (!res.ok || !body.access_token) {
+    throw new JiraOAuthError(body.error_description ?? body.error ?? `refresh failed with HTTP ${res.status}`);
+  }
+  return {
+    accessToken: body.access_token,
+    refreshToken: body.refresh_token,
+    expiresAt: body.expires_in ? new Date(Date.now() + body.expires_in * 1000).toISOString() : undefined,
+  };
+}

package/src/auth/token-store.ts

@@ -0,0 +1,73 @@
+/**
+ * Local, per-backend persistence for delegated OAuth tokens — separate from
+ * daemon-kit's own daemon-auth token (paths.token, which authenticates RPC
+ * callers to the daemon). This one holds what the daemon uses to authenticate
+ * *to* GitHub/GitLab/Jira on the user's behalf. Same security posture as
+ * daemon-kit's ensureAuthToken: 0700 directory, 0600 files, atomic write.
+ */
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export interface StoredToken {
+  accessToken: string;
+  refreshToken?: string;
+  /** ISO timestamp; absent means the provider issued a non-expiring token. */
+  expiresAt?: string;
+  scope?: string;
+  /** Backend-specific extras that don't fit the common shape, e.g. Jira's cloudId. */
+  extra?: Record<string, string>;
+}
+
+export interface TokenStoreEnv {
+  env?: Record<string, string | undefined>;
+  home?: string;
+}
+
+export function tokenStoreDir(opts: TokenStoreEnv = {}): string {
+  const env = opts.env ?? process.env;
+  const home = opts.home ?? homedir();
+  const stateHome = env.XDG_STATE_HOME || join(home, ".local", "state");
+  return join(stateHome, "tickets", "oauth");
+}
+
+function tokenPath(backend: string, opts: TokenStoreEnv = {}): string {
+  return join(tokenStoreDir(opts), `${backend}.json`);
+}
+
+export function saveToken(backend: string, token: StoredToken, opts: TokenStoreEnv = {}): void {
+  const path = tokenPath(backend, opts);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(token, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temp, path);
+}
+
+export function loadToken(backend: string, opts: TokenStoreEnv = {}): StoredToken | undefined {
+  const path = tokenPath(backend, opts);
+  if (!existsSync(path)) return undefined;
+  chmodSync(path, 0o600);
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as StoredToken;
+  } catch {
+    return undefined;
+  }
+}
+
+export function deleteToken(backend: string, opts: TokenStoreEnv = {}): void {
+  rmSync(tokenPath(backend, opts), { force: true });
+}
+
+export function listStoredBackends(opts: TokenStoreEnv = {}): string[] {
+  const dir = tokenStoreDir(opts);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => f.slice(0, -".json".length));
+}
+
+/** A token is usable if it has no expiry, or expires more than `skewMs` from now. */
+export function isTokenFresh(token: StoredToken, skewMs = 60_000): boolean {
+  if (!token.expiresAt) return true;
+  return new Date(token.expiresAt).getTime() - Date.now() > skewMs;
+}