feat: adds long lived refresh token feature for ci

[v3nant]

CI Login Token Exchange: Long-Lived Refresh Tokens for Headless Auth

Summary

Adds support for long-lived organization-scoped refresh tokens for headless CI/CD pipelines. Users can provision a token once (interactive) and use it in CI without running hd auth login in the pipeline.

Design

Flow

sequenceDiagram
    participant User
    participant Login
    participant Provision
    participant CILogin
    participant Scan

    User->>Login: hd auth login
    Login->>Login: OAuth PKCE, persist tokens (keyring)

    User->>Provision: hd auth-ci provision --org-id N
    Provision->>IAM: getOrgAccessTokens(orgId, null) [Bearer from login]
    IAM-->>Provision: refreshToken (long-lived)
    Provision->>Provision: save to ~/.hdcli/ci-token (encrypted)

    Note over User: CI pipeline runs (headless)
    User->>CILogin: eval $(hd auth-ci login)
    CILogin->>IAM: getOrgAccessTokens(orgId, refreshToken)
    IAM-->>CILogin: accessToken, refreshToken (maybe rotated)
    CILogin->>User: export HD_ACCESS_TOKEN=...

    User->>Scan: hd scan eol
    Scan->>Scan: requireAccessTokenForScan uses HD_ACCESS_TOKEN

Loading

Auth Resolution Order

requireAccessTokenForScan (used by scan, Apollo default, completeUserSetup) now:

1. CI first: If getCIToken() or config.accessTokenFromEnv → use CI path (requireCIAccessToken)
2. Keyring second: Else use stored OAuth tokens (keyring) with refresh via Keycloak

CI tokens come from:

• Env (CI): HD_AUTH_TOKEN, HD_ORG_ID, HD_ACCESS_TOKEN
• File (local): ~/.hdcli/ci-token (encrypted, machine-bound)

Changes

New Commands

Command	Purpose
hd auth-ci provision --org-id <id>	Provision long-lived CI token (requires hd auth login first). Saves to ~/.hdcli/ci-token and outputs token for CI secrets.
hd auth-ci login	Exchange CI refresh token for access token. Outputs export HD_ACCESS_TOKEN=... for eval.

New / Updated Files

• src/commands/auth-ci/login.ts – CI login command
• src/commands/auth-ci/provision.ts – CI provision command
• src/service/ci-auth.svc.ts – CI auth path (exchange, no keyring)
• src/service/ci-token.svc.ts – CI token storage (env + encrypted file via conf)
• src/api/ci-token.client.ts – IAM getOrgAccessTokens client (provisionCIToken, exchangeCITokenForAccess)
• src/api/apollo.client.ts – Extracted from nes.client.ts; shared Apollo factory with token provider
• src/config/constants.ts – Added ENABLE_AUTH, ENABLE_USER_SETUP, ciTokenFromEnv, orgIdFromEnv, accessTokenFromEnv, IAM config
• src/service/auth.svc.ts – requireAccessTokenForScan delegates to CI path first, re-exports CITokenError

README

• CI/CD authentication section updated with new flow
• One-time setup: hd auth login → hd auth-ci provision --org-id <id>
• CI pipeline: eval $(hd auth-ci login) before scan
• GitHub Actions and GitLab CI examples with HD_ORG_ID and HD_AUTH_TOKEN
• Local testing example

Other

• nes.client.ts: Uses shared createApollo from apollo.client.ts
• user-setup.client.ts: completeUserSetup uses requireAccessTokenForScan; error propagation improved
• scan/eol.ts: Auth gated by config.enableAuth; error message handling improved

Usage

One-time setup (interactive):

hd auth login
hd auth-ci provision --org-id <your-org-id>

Copy token and org ID into CI secrets: HD_AUTH_TOKEN, HD_ORG_ID.

CI pipeline:

export HD_ORG_ID=<id> HD_AUTH_TOKEN="<token>"
eval $(hd auth-ci login) && hd scan eol --dir .

Gaps & Follow-ups

Gap	Notes
Docker image auth	README Docker examples do not show CI auth; document if ghcr.io/herodevs/eol-scan supports HD_AUTH_TOKEN / HD_ORG_ID.
E2E with real auth	E2E no longer mocks auth; verify E2E still passes when ENABLE_AUTH is false or with CI token injection.

[marco-ippolito]

If you dont need the body consider performing a HEAD request. This improves the memory footprint
https://undici.nodejs.org/#/?id=garbage-collection

[v3nant]

We need the body for the graphql queries and mutations, as we need Apollo to parse the GraphQL data and the request.